@easysociable/cli 0.1.0

package/skills/easysociable-template/workflows/DESIGN_CONCEPTS.md

@@ -0,0 +1,41 @@
+# Design concepts (text brief V2.1)
+
+Run after `DESIGN_PHILOSOPHY.md` (and `DESIGN_BRIEF.md` for text intake). Act as an art director expressing one shared philosophy, not a slogan generator.
+
+## Output
+
+Create **2–3 materially different concepts**. They are **spatial variations of the same `philosophy`**, like canvas-design multi-page twists — not three unrelated moods.
+
+Each concept must specify:
+
+- `id`, name, one-sentence rationale, and a recognisable visual motif
+- `philosophyExpression` — how this layout expresses the shared philosophy in space (required)
+- Canvas zones with approximate `x/y/width/height`
+- Focal hierarchy: primary, secondary, attribution
+- Typography system: display/body contrast and approximate scale ratio (traceable to `philosophy.typographyAccent`)
+- Color strategy: canvas/ink/muted/one dominant accent (mood only; hex via Theme pipeline)
+- `paletteCandidates` (optional but recommended): named options such as `[{ "name": "Ocean Depths", "presetId": "ocean-depths", "brandHex": "#1A6B6B", "mode": "light", "bestFor": "…" }]` — prefer `references/THEME_PRESETS.md` when user has no brand color
+- Asset strategy: none, CSS/SVG, reuse, or generate
+- Whitespace/density strategy and concrete risks
+
+Changing only colors, radius, or shadows does not create a different concept. Change at least two of: composition, focal placement, type treatment, visual motif, asset role.
+
+`layout` / `hierarchy` / `typography` must be clearly derivable from `philosophy.space` / `composition` / `rhythm` / `typographyAccent`.
+
+## Selection
+
+- Show concise concept summaries when the user asked to choose or collaborate.
+- Otherwise recommend and select the strongest concept; state why it best serves the one-glance job **and** the shared philosophy.
+- Keep rejected concepts in `design-plan.json` so the decision remains auditable.
+- Use one concept only for `source.kind = image_reference`, where the reference already determines composition (still require `philosophyExpression`).
+
+## Guardrails
+
+- Use one dominant focal idea.
+- Prefer editorial hierarchy over a grid of generic SaaS cards.
+- Make decorative choices reinforce the philosophy’s rhythm; do not add illustration by default.
+- Keep replaceable text, numbers, avatars, and logos editable.
+- Design for realistic stress content: long name, large number, missing optional asset.
+- Do not invent a second philosophy per concept.
+
+Continue to `ASSET_PLAN.md`, then `PALETTE_REVIEW.md` and `THEME_FROM_BRAND.md` when co-creating a theme. Validate `design-plan.json` and `theme-tokens.json` using `references/DESIGN_V2_1.md`.

package/skills/easysociable-template/workflows/DESIGN_PHILOSOPHY.md

@@ -0,0 +1,69 @@
+# Design philosophy (after brief, before concepts)
+
+Borrow canvas-design’s order: name a visual movement, write the aesthetic worldview, then express it as layout concepts. This is **not** a free-art poster workflow — the philosophy must serve a one-glance social template with editable slots.
+
+## When to run
+
+- After `DESIGN_BRIEF.md` for `source.kind = text_brief`
+- After image inspection for `AUTHORING_FROM_IMAGE.md` (short reverse-engineered philosophy is enough)
+- Before `DESIGN_CONCEPTS.md`
+
+Skip only when reusing an already validated `design-plan.json` that already contains `philosophy`.
+
+## Goal
+
+Produce one shared philosophy that later concepts will express differently in space. Do **not** invent three unrelated slogans.
+
+## Steps
+
+### 1. Name the movement (1–2 words)
+
+Examples adapted for social templates: `Editorial Ledger`, `Terminal Pulse`, `Quiet Proof`, `Monument Metric`, `Warm Folio`.
+
+Seed from `references/DESIGN_INTELLIGENCE.md` when stuck.
+
+### 2. Write the philosophy (4–6 short paragraphs or structured fields)
+
+Cover each once (no redundancy):
+
+| Field | Ask |
+|-------|-----|
+| `space` | Margins, breathing room, density, where emptiness works |
+| `color` | Mood and limit strategy (not final hex — that comes from Theme pipeline) |
+| `rhythm` | Repeating system: rules, dots, grids, cadence of decoration |
+| `composition` | Zones, focal placement, what stays quiet |
+| `typographyAccent` | Display vs body ratio; where type is a gesture vs metadata |
+| `craftBar` | One sentence: museum-grade spacing, no overlap, one focal, refine before adding |
+
+Optional but recommended:
+
+| Field | Ask |
+|-------|-----|
+| `subtleReference` | Quiet conceptual DNA (jazz quote, not a label sticker) |
+| `templateConstraints` | Slots stay bindable; flat absolute siblings; Theme owns color; never flatten copy into a poster |
+
+Also write companion `design-philosophy.md` for humans using the structure in `references/DESIGN_V2_1.md`.
+
+### 3. Template hard constraints (must appear in philosophy or `templateConstraints`)
+
+Rewrite canvas-design’s “minimal text / pure art” into template-safe rules:
+
+1. **Slots win clarity** — required brief slots become bindable nodes; philosophy may demand sparse chrome, not missing content.
+2. **Theme owns hex** — philosophy states mood/limit only; concrete colors go through `PALETTE_REVIEW.md` + `THEME_FROM_BRAND.md`.
+3. **Decoration is rhythm** — prefer CSS/SVG repeats (lines, dots, grids) over new illustrations.
+4. **Flat absolute layout** — zones are canvas siblings; card chrome is a background sibling, never a nested absolute group.
+5. **Readable focal** — subtle reference is allowed, but title/metric must be one-glance clear on social canvases.
+
+### 4. Hand off
+
+Continue to `DESIGN_CONCEPTS.md`. Every concept must include `philosophyExpression` describing how **this** spatial plan expresses the shared philosophy.
+
+Embed `philosophy` into `design-plan.json` before validation.
+
+## Do not
+
+- Skip philosophy and jump to SaaS three-card layouts
+- Write a philosophy that forbids required text slots
+- Encode final brand hex only inside philosophy prose (use Theme pipeline)
+- Treat philosophy as a PNG art brief that replaces `authoringSource`
+- Ship canvas-design font files; map voice → Theme fonts via `DESIGN_INTELLIGENCE.md`

package/skills/easysociable-template/workflows/FILL_AND_RENDER.md

@@ -0,0 +1,86 @@
+# Fill slots and Hosted Render (published template)
+
+Primary **Agent use** of a published single-page template: read the public slot table, fill values, submit a Hosted Render Job, poll for Artifact / Manifest.
+
+This path belongs to **Template Skill** (ADR-0021 / AC-25～26). Do **not** hand off to Content Skill for single-page fill-slots out图.
+
+## Preconditions
+
+```bash
+easysociable auth status --json
+```
+
+Prefer Template MCP tools when available; CLI is the fallback.
+
+## Steps
+
+### 1. Get template + public slots
+
+**MCP:** `get_template({ templateId })`  
+**CLI:** `easysociable templates get --id <id> --json`
+
+Response MUST include `slots[]` with `key`, `type`, `required`, optional `maxCharacters` / `overflow` / `aiHint` / `label`.  
+MUST NOT include AST, Binding Map, or RenderPlan.
+
+### 2. Fill slots
+
+| Slot type | Agent action |
+|---|---|
+| `text` / `number` | Generate from user brief; respect `maxCharacters` / required |
+| `image` | Ask user: upload or choose an existing account image. After confirmation, use `import_template_image` / the unified image import flow so the bytes are stored through Gateway → R2 and the metadata is recorded in the existing Directus `Image` collection; put the returned **`imageId`** in the slot. Never pass temporary Unsplash/Pexels/Pinterest URLs, local paths or transient asset IDs as authority. |
+
+Omit optional empty slots (`null` / `''`) rather than inventing filler.
+
+All V1 image uploads use the account image import flow. There is no separate
+transient render-asset command.
+
+### 3. Create Hosted Render Job
+
+**MCP:** `create_render_job({ templateId, slots, outputFormats, idempotencyKey? })`  
+**CLI:**
+
+```bash
+easysociable renders create \
+  --template-id <id> \
+  --slots '{"title":"Hello","caption":"World"}' \
+  --format png \
+  --idempotency-key fill_1 \
+  --json
+```
+
+**Forbidden inputs:** `ContentDocument`, `contentDocumentHash`, client `RenderPlan`, AST, Binding Map.
+
+### 4. Poll Job / Manifest
+
+**MCP:** `get_render_job({ jobId })` → when completed, `get_render_manifest` if needed  
+**CLI:** `easysociable renders wait --id <id> --json`
+
+Success: signed Artifact URL(s) on the public Manifest.  
+Job may also return `previewUrl` + `capture` (signed Studio-parity page). Deliver the **Hosted Artifact**, not a local screenshot of that preview URL.
+
+### 5. Hosted Capture failure
+
+V1 does not expose a second local capture command. If Hosted Capture fails,
+surface the Gateway error and retry only when it is marked retryable; do not
+invent a browser URL, selector or viewport and do not treat an Authoring Studio
+screenshot as a billable final Artifact.
+
+#### Error-code table
+
+| Code / signal | Local capture? | Agent action |
+|---|---|---|
+| Job `completed` + Manifest Artifact | No | Deliver signed Artifact URL(s) |
+| Retryable worker/queue/5xx error | No | Retry Hosted with the same idempotency key |
+| Rate limit | No | Respect retry-after/backoff and retry once if allowed |
+| `VALIDATION_ERROR` / missing required slots | **No** | Fix slots; no fallback expected |
+| Auth / entitlement / tier denied | **No** | Fix credentials/plan; no fallback |
+Failed jobs without a retryable error are surfaced to the user; no freestyle
+browser screenshot is accepted as final output.
+
+## Anti-patterns
+
+- Building or submitting a local RenderPlan / AST / Binding Map
+- Using ContentDocument export as a render prerequisite
+- Treating Studio html-to-image as Hosted delivery or as the default on success
+- Local capture when Hosted succeeded or when `fallback.capture` is absent
+- Calling Content MCP/CLI for this single-page fill-slots flow

package/skills/easysociable-template/workflows/MCP_FIRST.md

@@ -0,0 +1,9 @@
+# MCP-first
+
+Use the unified EasySociable MCP for Template authoring, images, icons, Profiles,
+Themes and Render Jobs. Fall back to the equivalent `easysociable` CLI command
+only when MCP is unavailable.
+
+Neither path may call Local API, SQLite, Directus, R2, Stripe, private Template
+Service or a third-party provider through EasySociable. Host-installed image
+MCPs are optional discovery tools and are never auto-installed.

package/skills/easysociable-template/workflows/OUT_OF_SCOPE.md

@@ -0,0 +1,15 @@
+# Out of scope for template-skill
+
+If the user asks for any of the following, **do not** execute them under this skill:
+
+| Request | Hand off |
+|---|---|
+| Generate爆款 copy / topic / Working Draft as Content product | Content Skill |
+| Export `ContentDocument` / checkpoint Content Version | Content Skill |
+| Compose or render a **multi-slide** slideshow Run | **easysociable-slideshow** |
+| Pick Theme as slideshow “Look” for a whole Run | **easysociable-slideshow** + Profile Theme |
+| Local Obsidian content authoring | Content Skill |
+| UGC/publication/social posting | Deferred in V1 |
+| Submit `contentDocumentHash` / ContentDocument to Template render | **Forbidden** — use fill-slots (`FILL_AND_RENDER.md`) |
+
+**In scope:** single-page template authoring/publish **and** fill-slots Hosted Render of one published PageTemplate (`get_template` → slots → `create_render_job`).

package/skills/easysociable-template/workflows/PALETTE_REVIEW.md

@@ -0,0 +1,71 @@
+# Palette review
+
+Choose between 2–3 palette directions and lock theme tokens before layout authoring.
+Adapted from Anthropic `theme-factory`: **show → ask → wait for explicit choice → apply**.
+
+## When to use
+
+- After concept selection in `DESIGN_CONCEPTS.md`
+- Before `AUTHORING_FROM_BRIEF.md` or `AUTHORING_FROM_IMAGE.md` build step
+- When co-creating Theme (no reusable `themeId`)
+
+## Steps
+
+1. Build **2–3 named candidates** (not anonymous A/B hexes):
+   - From user brand hex → light/dark (or slight hex variants) via generator
+   - Or from `references/THEME_PRESETS.md` / `theme-presets.json` when no brand hex
+   - Each candidate needs: `name`, `brandHex`, `mode`, `bestFor` (and optional `notFor` / `presetId`)
+2. Generate a candidate file per option:
+
+```bash
+node scripts/generate-theme-from-hex.mjs --preset ocean-depths -o theme-candidate-ocean.json
+node scripts/generate-theme-from-hex.mjs --preset tech-innovation -o theme-candidate-tech.json
+node scripts/generate-theme-from-hex.mjs #0D9488 --mode light -o theme-candidate-custom.json
+```
+
+3. **Showcase (required)** — present a swatch table before asking the user to choose. Do not dump raw JSON as the only view:
+
+| Name | Preset / custom | Mode | brandHex | Accent | Contrast | bestFor |
+|------|-----------------|------|----------|--------|----------|---------|
+| Ocean Depths | ocean-depths | light | #1A6B6B | … | pass | Finance, trust metrics |
+| Tech Innovation | tech-innovation | dark | #2563EB | … | pass | Startups, launches |
+
+Include one-line canvas/accent feel from each candidate’s `themeTokens.colors`.
+
+4. **Ask and wait** — which theme to apply? Do **not** call `theme.create` or finalize `theme-tokens.json` until the user explicitly confirms (or they already said “直接用 X / 你定”).
+5. On confirmation, copy the winner to `theme-tokens.json` and set Theme create **name** to the candidate `name` (e.g. `Ocean Depths`), never `Theme draft_xxx`.
+6. Update `design-plan.json`:
+
+```json
+"themePreview": {
+  "name": "Ocean Depths",
+  "presetId": "ocean-depths",
+  "brandHex": "#1A6B6B",
+  "activeMode": "light",
+  "contrastPass": true,
+  "bestFor": "Finance, consulting, trust-building metric cards",
+  "themeTokensPath": "theme-tokens.json",
+  "userConfirmed": true
+}
+```
+
+7. Run `node scripts/validate-design-v2.mjs design-plan.json` and `theme-tokens.json`.
+8. Continue to `THEME_FROM_BRAND.md` only if tokens still need regeneration; otherwise proceed to authoring with the locked file.
+
+## Contrast checklist (before authoring)
+
+- [ ] `text` on `canvas` ≥ 4.5:1 (AA body text)
+- [ ] `muted` on `canvas` ≥ 4.5:1
+- [ ] `accent` on `canvas` ≥ 3:1 (accent text / links)
+- [ ] `label` on `primary` ≥ 3:1 (filled buttons — light text on dark primary in dark mode)
+- [ ] Screenshot spot-check: no neon-on-neon or gray-on-gray failures
+
+If any pair fails, regenerate or switch mode — do not proceed to `authoringSource`.
+
+## Do not
+
+- Apply a theme without showcase + explicit confirmation (unless user waived choice)
+- Offer palettes that differ only by one shade step
+- Skip `theme-tokens.json` when creating a new theme
+- Override failed contrast with arbitrary hex without re-running the generator
+- Name Gateway themes as `Theme <draftId>`

package/skills/easysociable-template/workflows/PUBLISH_FROM_DRAFT.md

@@ -0,0 +1,60 @@
+# Publish from saved draft (Agent path)
+
+Authoring Studio has **Save only** — no Publish button.  
+After the user saves and says 「publish」/「发布该模板」, the Agent analyzes the draft, completes catalog metadata, and publishes via Gateway.
+
+## When to run
+
+- User finished editing in `/authoring/{draftId}` and clicked **Save**
+- User explicitly asks to publish (do not auto-publish on create)
+
+## Flow
+
+1. Load the saved draft:
+
+```bash
+easysociable templates get --id <draftId> --json
+```
+
+2. Analyze public fields only (`authoringSource`, canvas, themeId, existing `selectionMetadata`):
+   - Infer `platforms` / `canvasPreset` from canvas + brief
+   - Infer `supportedRoles` (1–2) from layout intent / node types
+   - Derive `slotSummary` / `requiresImage` / `imageRoles` from fillable slots
+   - Fill `contentFamily`, `contentArchetypes`, `density`, `textDensityRange`
+   - Prefer P1: `bestFor`, `notFor`, `selectionHints`, `visualStyle`, `locale`
+
+3. Show a short P0/P1 summary to the user. Wait for confirmation unless they already said 「直接发布」.
+
+4. Write metadata, then publish:
+
+```bash
+easysociable templates publish --id <draftId> --json
+```
+
+Or two steps:
+
+```bash
+easysociable templates update --id <draftId> --file ./draft-patch.json --json
+easysociable templates publish --id <draftId> --json
+```
+
+5. Verify catalog discoverability:
+
+```bash
+easysociable templates list --json
+```
+
+## Rules
+
+- Never invent private AST / Binding Map from Agent-side.
+- Gateway rejects Publish if any P0 field is missing — fix metadata and retry.
+- Incomplete published pages must not appear in `list` (enforced server-side).
+- Theme co-create drafts may still be published via theme APIs when product requires it; page publish is independent.
+
+## Failure recovery
+
+| Error | Action |
+|---|---|
+| `VALIDATION_ERROR` missing P0 | Fill missing fields, `update` + `publish` again |
+| `NOT_FOUND` | Confirm `draftId`; user may not have saved |
+| `VERSION_IMMUTABLE` | Draft already published — create a new template instead |

package/skills/easysociable-template/workflows/SURFACE_REVIEW.md

@@ -0,0 +1,178 @@
+# Surface review (atmosphere layer)
+
+Choose and confirm the canvas **surface** before authoring. Surface is independent of Theme semantic colors.
+
+```text
+Theme  = identity (solid semantic colors + fonts)
+Surface = atmosphere (flat | gradient | image)
+```
+
+Aligned with ADR-0020 (photos) and ADR-0023 (icons): photo discovery may use host MCPs; icon discovery uses Gateway Icon Catalog; materialization only through Template Gateway.
+
+## When to run
+
+- After concept selection (`DESIGN_CONCEPTS.md`) and Theme lock (`PALETTE_REVIEW` / `THEME_FROM_BRAND`) when co-creating
+- During `ASSET_PLAN.md` when the brief needs wash, photography backdrop, or icons
+- Skip only when surface is clearly `flat` (typography-only / Theme.canvas) and no icons/photos are required
+
+## Surface kinds
+
+| `kind` | Discovery | After user confirms | Authoring result |
+|---|---|---|---|
+| `flat` | None | — | Theme.canvas only |
+| `gradient` | Template MCP/CLI `gradients list\|search\|get` | Inline CSS decoration sibling (no `bindingKey`) | Atmosphere wash / band |
+| `image` | Host **Pinterest / Unsplash / Pexels** MCP (not Template MCP) | Gateway draft image import → stable CDN `imageId` | Background usually `fixed` |
+| (+ icons) | Template MCP/CLI `search_icons` / `get_icon` | Materialize `TemplateIconAsset` → inline `canonicalSvg` / `iconAssetId` (Theme via `currentColor`) | Icon chrome |
+
+Photography for **slots** (avatar, hero well) also uses host image MCPs + Gateway import; ask `fixed` vs `slot_default` (surface background defaults to **`fixed`**).
+
+## Steps
+
+### 1. Decide kind
+
+From brief + philosophy `color` / `rhythm` + selected concept:
+
+- Sparse copy + atmospheric mood → prefer `gradient` or soft `image`
+- Dense metrics / checklist → prefer `flat` or a thin gradient band (not full-bleed noisy photo)
+- User asks for photo backdrop / Unsplash vibe → `image`
+- User asks for gradient / wash → `gradient`
+- Default when unsure → `flat`, then ask
+
+Record intent in `design-plan.json` → `surfacePreview.kind` (may be unconfirmed).
+
+### 2. Discover (bounded candidates only)
+
+**Gradient**
+
+```bash
+easysociable templates gradients search --q "<mood>" --limit 8 --json
+# or MCP: search_gradients / list_gradients
+easysociable templates gradients get --id <id> --json   # only after shortlist interest
+```
+
+Show a **text table** (MVP: no thumbnails): name, stopSummary, tags, textSafeZone, bestFor.
+
+**Image (surface or slot)**
+
+1. Call host Unsplash / Pexels / Pinterest MCP with a short query.
+2. Show ≤8 candidates (thumb + attribution if the host MCP returns them).
+3. If the MCP is missing → degrade: say which provider is missing; offer `flat`, `gradient`, user upload, or skip. Do **not** invent URLs or proxy search through Template MCP.
+
+**Icons (hard rule)**
+
+```bash
+easysociable icons search --query "<concept>" --limit 8 --json
+# or MCP: search_icons
+easysociable icons get --icon-id <iconId> --idempotency-key <key> --json   # only after user confirms
+# or MCP: get_icon
+```
+
+**MUST path (every icon, including “just add an arrow”):**
+
+1. Call Template `search_icons` / CLI `icons search` (Gateway Icon Catalog). Show ≤8 candidates with `iconId`, collection, style, license.
+2. Wait for user choice — or explicit waive of choice: “你定 / 用第 N 个 / 随便好看一点的向右箭头”.  
+   Unselected search hits produce **zero** `TemplateIconAsset` writes.
+3. After confirm, call `get_icon` / CLI `icons get` with a **stable** `idempotencyKey`.  
+   Embed returned **`canonicalSvg`** only; record **`iconAssetId`**, `iconId`, collection, license, contentHash on the decoration node (e.g. `data-icon-asset-id`, `data-icon-id`).
+4. Color with Theme `currentColor` / `--es-*` on the wrapper; never bake Theme hex into the SVG paths.
+5. If Gateway Icon Catalog / auth **fails** → say so → degrade to **omit** or temporary CSS/SVG shape **only after user agrees**.  
+   Do **not** fall back to Better Icons MCP, client Iconify, or silent hand-drawn paths.
+
+**Forbidden by default (not a shortcut):**
+
+- Hand-writing SVG `<path d="…">` for arrows, chevrons, checks, social marks, “next page” cues, or any symbol the catalog can supply.
+- Using emoji as a substitute for catalog icons.
+- Skipping search because “it’s only a small arrow” or “faster to draw”.
+
+**Allowed without catalog (not icons):** pure geometry with no symbol meaning — hairlines, solid rails, anonymous disc washes. If it **reads as a UI/icon glyph**, it is an icon → catalog path.
+
+### 3. Confirm gate (required)
+
+Do **not** mutate Draft / Authoring Source until the user:
+
+- picks one candidate, or
+- explicitly waives (“flat 就行 / 你定 / 不要背景”)
+
+Unselected candidates produce **zero** EasySociable writes (no R2, no Directus Image, no decoration node, no gradient get baked into draft).
+
+### 4. Materialize (Gateway / Authoring only)
+
+| Kind | Materialize |
+|---|---|
+| `flat` | Nothing extra |
+| `gradient` | `gradients get` → write absolute background decoration with `style.backgroundImage = <css>`; record `recipeId`, provider, license in `surfacePreview` / node comment |
+| `image` | Import via Template Gateway draft images (when available) or document the import step for TMP-024; Authoring references **CDN / imageId only** — never third-party temp URLs. Mode: surface background → `fixed`; slot → ask `fixed` \| `slot_default` |
+| icon | Inline sanitized SVG as decoration sibling; record `iconAssetId`, provider, collection, license, contentHash |
+
+Prefer band or panel geometry over full-bleed when copy is dense. Keep Theme.canvas as a safe solid under translucent washes when needed (`textSafeZone` / `needs_scrim`).
+
+### 5. Record in `design-plan.json`
+
+```json
+"surfacePreview": {
+  "kind": "gradient",
+  "userConfirmed": true,
+  "recipeId": "grad_001_warm-flame",
+  "name": "Warm Flame",
+  "provider": "webgradients",
+  "textSafeZone": "light_end",
+  "contrastAnchor": "#FAD0C4",
+  "placement": "full_bleed",
+  "notes": "Dark type on light end"
+}
+```
+
+For image:
+
+```json
+"surfacePreview": {
+  "kind": "image",
+  "userConfirmed": true,
+  "imageMode": "fixed",
+  "imageId": "img_…",
+  "provider": "unsplash",
+  "query": "soft paper texture",
+  "rightsState": "licensed_for_publish",
+  "placement": "full_bleed"
+}
+```
+
+For flat: `{ "kind": "flat", "userConfirmed": true }`.
+
+Also mirror assets in `assetPlan` with sources `gradient_catalog` | `external_photo` | `template_icon_catalog` when used.
+
+### 6. Validate
+
+```bash
+node scripts/validate-design-v2.mjs design-plan.json
+```
+
+If `surfacePreview.kind` is `gradient` or `image`, `userConfirmed` must be `true` and required ids must be present before authoring.
+
+## Fixture paths (Skill smoke)
+
+| Path | Expectation |
+|---|---|
+| flat | No host MCP; no gradients get into draft |
+| gradient | Template `gradients.*` only; confirmation → CSS decoration |
+| image | Host image MCP → confirm → CDN/`imageId`; no temp URL in source |
+| icon | `search_icons` → confirm → `get_icon` → inline canonical SVG / `iconAssetId` |
+| none / waive | Explicit waive; remain flat |
+
+## Do not
+
+- Proxy Unsplash / Pexels / Pinterest **search** through Template MCP/CLI
+- Require Better Icons MCP, client Iconify credentials, or runtime Provider fetches for icons
+- **Hand-draw icon paths when Icon Catalog search works** (arrows, chevrons, checks, …)
+- Put third-party temporary URLs or local paths into Authoring Source / Publish
+- Call `theme.create` with gradient CSS (Theme stays solid semantics)
+- Stack a second rainbow signature when a full-bleed gradient is already the signature
+- Treat unselected search hits as EasySociable assets
+- Require `easysociable-media` Skill/CLI/MCP
+
+## Agent self-check before Save handoff (icons)
+
+- [ ] Every symbol-like decoration has `iconAssetId` / came from `get_icon`
+- [ ] No hand-authored icon `<path>` when catalog was available
+- [ ] User confirmed pick (or explicit “你定 / 第 N 个”) before `get_icon`
+- [ ] Icon color uses `currentColor` / `--es-*` (dark/light safe)

package/skills/easysociable-template/workflows/THEME_FROM_BRAND.md

@@ -0,0 +1,73 @@
+# Theme from brand color
+
+Generate deterministic, WCAG-checked theme tokens from a brand hex or curated preset before `theme.create`.
+
+## When to use
+
+- User provides a brand color (hex) or brand kit with primary color
+- User confirmed a preset from `PALETTE_REVIEW.md` / `references/THEME_PRESETS.md`
+- Selected concept has a concrete color direction (not only free-text `colorStrategy`)
+- No existing `themeId` to reuse
+
+Skip when the user already selected a published theme or only wants to tweak an existing theme.
+
+## Inputs
+
+| Input | Required | Notes |
+|-------|----------|-------|
+| `brandHex` **or** `--preset <id>` | Yes | Preset supplies hex + fonts + suggested mode |
+| `activeMode` | Yes | `light` or `dark` — match concept / preset bias |
+| `heading` / `body` font | No | Default from preset or `Inter` |
+| Theme `name` | Yes for create | Human name (preset `name` or custom), not `Theme draft_xxx` |
+| User confirmation | Yes | From `PALETTE_REVIEW` unless user waived |
+
+## Steps
+
+1. Resolve inputs:
+   - Brand hex from brief / brand kit / user message, **or**
+   - `--preset` id from `references/theme-presets.json` after user confirmation
+2. Pick `activeMode` from selected concept / preset:
+   - Light canvas / editorial paper → `light`
+   - Dark canvas / terminal / neon → `dark`
+3. Run:
+
+```bash
+node scripts/generate-theme-from-hex.mjs <#hex> \
+  --mode <light|dark> \
+  --heading "<Font>" \
+  --body "<Font>" \
+  --output theme-tokens.json
+
+# or
+node scripts/generate-theme-from-hex.mjs --preset ocean-depths \
+  --output theme-tokens.json
+
+node scripts/generate-theme-from-hex.mjs --list-presets
+```
+
+4. Validate:
+
+```bash
+node scripts/validate-design-v2.mjs theme-tokens.json
+```
+
+5. If `contrastPass` is `false`, adjust before authoring:
+   - Try the other mode (`light` ↔ `dark`)
+   - Shift brand hex slightly (darker/lighter) and regenerate
+   - Try another preset
+   - Document the trade-off in `design-plan.json` `selectionReason`
+6. **Confirmation gate:** do not call Gateway `theme.create` until `themePreview.userConfirmed` is true (or the user explicitly waived palette choice).
+7. Use `themeTokens` from `theme-tokens.json` for Gateway `theme.create` — includes embedded `palette` for `theme_schema_v2`. Pass a readable `name` (preset name or custom label).
+8. Keep `theme-tokens.json` alongside `design-plan.json` for Visual QA contrast reference.
+
+## Output artifact
+
+`theme-tokens.json` — schema `theme_tokens_v2`. See `references/DESIGN_V2_1.md`. May include `preset: { id, name, bestFor, notFor }` when generated from `--preset`.
+
+## Do not
+
+- Hand-pick four colors without running the generator when a brand hex or preset exists
+- Put scale shades (`500`, `700`) directly on page nodes as hard-coded hex — prefer `--es-color-*` / `--es-scale-*`
+- Skip contrast validation when `colorContrast` is scored in Visual QA
+- Create `authoringSource` or `theme.create` before `theme-tokens.json` validates and the user confirmed (when no `themeId`)
+- Create themes named only after draft ids

package/skills/easysociable-template/workflows/VISUAL_QA.md

@@ -0,0 +1,55 @@
+# Screenshot-based Visual QA (V2.1)
+
+Run after draft creation and before the user handoff. Source inspection alone is not visual QA.
+
+## Render evidence
+
+1. Prefer opening `authoringStudioUrl` with available browser control and capture the rendered canvas.
+2. If browser control is unavailable, record QA as pending; the unified CLI has
+   no separate `easysociable-template preview` command. A final render is not a
+   substitute for inspecting Authoring Studio.
+3. Record an inspectable screenshot path or URL in `visual-qa.json`.
+4. Never mark QA as passed when the page did not render or the screenshot could not be inspected.
+
+## Review order
+
+0. If `theme-tokens.json` exists, compare screenshot contrast to its `contrast` report for the active mode. Failed pairs are hard failures or cap `colorContrast` at 5. When `surfacePreview.kind` is `gradient` or `image`, also check text against `contrastAnchor` / scrim — do not assume Theme.canvas alone matches the wash.
+
+1. **Craft Pass (philosophy discipline)** — before numeric scoring:
+   - Read `design-plan.json` → `philosophy.craftBar` and the selected concept’s `philosophyExpression`
+   - If the screenshot contradicts the philosophy (e.g. generic SaaS three-card grid vs “monumental single metric”), treat that as a composition/hierarchy issue and plan a revise toward the stated expression
+   - For `iteration >= 1`, default revisions **tighten existing nodes** (size, position, whitespace, type scale, contrast). Do **not** add large new decoration layers or new illustrations to chase points
+   - If a full-bleed gradient or photo surface is already the signature, do not add a second competing atmosphere layer
+   - Prefer high-impact changes: focal size/position, whitespace, alignment, type scale, contrast, then decoration
+
+2. Check hard failures:
+
+- render/runtime error
+- clipped or overflowing text
+- overlapping content
+- off-canvas elements or unsafe margins
+- unreadable contrast
+- missing required slot content/image
+- background or decoration obscuring the focal message
+- third-party temp URLs or broken CDN for image surface/slots
+3. Score the fixed rubric in `references/DESIGN_V2_1.md`:
+
+- hierarchy 20
+- composition 15
+- spacing/alignment 15
+- typography 15
+- color/contrast 10
+- asset relevance 10
+- content resilience 10
+- editability 5
+
+## Revision loop
+
+- Pass only with no hard failures and total score `>= 80`.
+- For a failure, list concrete issues by region/node and revise `authoringSource`.
+- In `changesMade`, describe refine-first edits; avoid “added new decorative panel/illustration” unless the user explicitly asked or an assetPlan required asset was missing.
+- Validate the updated source, update the same `draftId`, and capture a new screenshot.
+- Perform at most **two automatic revisions** (`iteration` 0, 1, 2). Ask before doing more.
+- Do not hide a layout problem by rasterising the whole design.
+
+Validate the final `visual-qa.json` with `scripts/validate-design-v2.mjs`. If visual tools are unavailable, disclose the missing QA instead of fabricating a passing artifact.