snowflake

What this skill does

# Snowflake — Static-to-EDS Conversion

Convert a static HTML page into an EDS page while preserving the
original design and making content authorable in Document Authoring.
Two conversion levels are supported:

- **Page-level** (overlay) — the original DOM is preserved
  byte-for-byte via a template with `[data-slot]` markers. One
  template, one CSS file, one DA doc with slot-keyed rows.
- **Block-level** — each content section becomes an independent EDS
  block with its own `decorate()` function and CSS. Content is
  authored in DA block tables. Header and footer stay as static
  fragments.

Both levels keep the original visual design intact. Page-level is
the safer default; block-level produces more standard EDS output
but requires section independence in the source page.

## When to use

The user has an AI-generated polished static HTML page and wants to
launch it on Edge Delivery Services without losing the original
design while still making content editable in DA. Typical phrasing:

- "Convert https://example.com/static-page to EDS"
- "Make this page editable in DA but keep the original markup"
- "Convert this page to EDS blocks" (signals `level=block`)
- "Start the next experimentation for URL …"
- "Static-to-EDS overlay for …" (signals `level=page`)

## What this skill does NOT do

**Not for canonical EDS block-rewrite migrations** — that's
`page-import`. Snowflake preserves the source design; `page-import`
rewrites to standard EDS block patterns with no visual fidelity
target. Three asset strategies are supported (see
[knowledge/methodology.md](./knowledge/methodology.md) §3):
`absolute`, `vendor`, `da-media`.

## Parameters

| Parameter | Values | Default | Description |
|-----------|--------|---------|-------------|
| `level` | `page`, `auto`, `check`, `block` | `page` | Conversion level — see below |

### `level` values

| Value | Behavior |
|-------|----------|
| `auto` | Run the feasibility analysis in Phase 2, present the recommendation, ask the user to confirm before Phase 3 |
| `check` | Run the feasibility analysis only — produce the report in `decisions.json`, stop before Phase 3. Useful for batch scanning |
| `block` | Block-level conversion. Analysis still runs as validation (written to `decisions.json`) but does not gate the conversion |
| `page` | Page-level conversion (standard overlay). Analysis still runs as validation but does not gate the conversion |

When `level` is not provided and the user's phrasing signals intent,
infer it:
- "convert to EDS blocks", "block-level" → `level=block`
- "overlay", "preserve the DOM", "snowflake overlay" → `level=page`
- Neutral phrasing → `level=page`

### Usage examples

```
/snowflake https://example.com/promo              → page-level; infer repo, daRoot, slug
/snowflake https://example.com/promo level=block  → block-level, infer the rest
/snowflake https://example.com/promo level=auto   → feasibility analysis decides
/snowflake level=check                            → feasibility scan only (asks for URL)
/snowflake                                        → page-level, fully interactive
```

The **Source URL** is the leading positional input and the only required
argument. Everything else is resolved automatically and presented in a single
confirmation summary before any work begins.

## Skill dependencies

Snowflake cites DA HTML rules and the DA admin API contract from the
**da-content** skill. **Load `da-content` alongside Snowflake.**
Phases 3 (Generate) and 5 (Round-trip) reference it directly.

## Prerequisites

**Required** — the only input the skill cannot resolve on its own:

1. **Source URL** — the static page to convert. Must be reachable
   (publicly hosted or local dev server).

**Resolved automatically** — shown in the init summary for one-shot
confirmation before any work begins:

2. **Target EDS repo** — detected via `gh repo view --json nameWithOwner`,
   falling back to parsing `git remote get-url origin`. Must already have
   the overlay engine wired (see [knowledge/architecture.md](./knowledge/architecture.md)
   §"Solution shape"). Phase 0 installs it if absent.
3. **DA root path** — read from `.snowflake/config.json` `daRoot` key
   if set, otherwise defaults to the current git branch name (the same
   branch the skill uses for code). Shown in summary; override inline.
4. **Conversion level** — inferred from phrasing (see Parameters), else
   `page`. Shown in summary; override inline.
5. **Slug / template name** — derived from the source URL (kebab-case,
   ≤30 chars). Shown in summary; override inline.

**Auth check (non-blocking)** — DA token resolved from `$DA_TOKEN` →
`~/.aem/da-token.json`. Its status appears in the init summary. Phases
1–4 do not need it; if absent at invocation time, invoke the **da-auth**
skill before Phase 5 (Round-trip) runs.

## Initialization

On every invocation the agent performs these steps **before** entering Phase 0:

1. **Resolve inputs** — apply the fast-path rules from the Prerequisites
   section above.

2. **Probe substrate** —
   ```bash
   node <SKILL_DIR>/scripts/install-substrate.mjs --dry-run
   ```
   Captures the outcome (no-op / clean-install / drift / custom-code-detected).

3. **Check DA token** —
   ```bash
   DA_TOKEN=$(node -e "
     const fs = require('fs');
     const p = process.env.HOME + '/.aem/da-token.json';
     try {
       const t = JSON.parse(fs.readFileSync(p, 'utf8'));
       if (t.expires_at > Date.now() + 60000) process.stdout.write(t.access_token);
     } catch {}
   ")
   ```
   Non-blocking — records status for the summary only.

4. **Always display the run parameters** before any phase begins. Show
   this summary unconditionally — even when all values were provided
   upfront or inferred without ambiguity — then proceed immediately
   without waiting for confirmation:

   ```
   Source URL : https://example.com/promo   ← required (provided)
   Target repo: acme/my-site                ← detected from git
   DA root    : /main                        ← from current branch
   Level      : page                        ← default
   Slug       : promo                       ← derived from URL
   Substrate  : clean install — 9 files     ← (or: already current ✓)
   DA token   : cached ✓                    ← (or: not found — needed at Phase 5)
   ```

   Proceed without pausing for the common case (fresh install — no
   snowflake substrate yet; replaced files are backed up). Only pause
   for **drift** (a prior snowflake substrate that diverged), where
   overwriting could lose intentional customization — Phase 0 handles
   that case.

5. **Proceed** — Phase 0 → 1 → … → 6 in order.

## Quick start — end-to-end example

From the target EDS repository root, here's the full seven-phase
conversion in compressed form. Each phase file under
[phases/](./phases/) holds the complete prompt; this is the
shape of the actual commands the agent emits.

```bash
# Inputs (resolved during init, confirmed in the summary)
SOURCE_URL="https://example.com/promo"
PAGE_SLUG="promo"
DA_ROOT="/main"                       # defaults to current branch name
NNN=001                           # next run number
PROJECT=".snowflake/projects/${NNN}-${PAGE_SLUG}"
TEMPLATE_NAME="promo"
LEVEL="page"                      # page | auto | check | block

# Phase 0 — install (or verify) the overlay substrate (once per repo)
node "<SKILL_DIR>/scripts/install-substrate.mjs"

# Phase 1 — capture: fetch source + assets into the project folder
mkdir -p "$PROJECT/input"
curl -fsS "$SOURCE_URL" -o "$PROJECT/input/index.html"
# For JS-rendered pages, use a browser to get the fully rendered HTML instead

# Phase 2 — analyze: produce decisions.json (sections, slots, asset
# strategy, head-links, conversionLevel). Includes block-level
# feasibility assessment. If LEVEL=check, stop here.
# Driven by phases/2-analyze.md.

# Phase 3 — generate: produce 5 artifacts + DA-source body
# (templates/<tpl>.html, fragments/<tpl>/{header,footer}.html,
# styles/<t