@easysociable/cli 0.1.0

package/skills/easysociable-template/references/CATALOG_METADATA.md

@@ -0,0 +1,221 @@
+# Catalog / selection metadata (single-page template)
+
+Metadata that makes a published page template **discoverable and choosable** when Content Skill builds a slideshow.  
+Private AST/bindings stay server-side; this document is the **public selection contract** Agents must fill before Publish.
+
+## Design choices (locked)
+
+1. **One closed `pageRoles` set** (stored as `supportedRoles`) — narrative beat + layout kind in one enum. Do not maintain a second parallel taxonomy.
+2. **`platforms` is a multi-select array**. Include `generic` when the page fits any platform at that aspect.
+3. **P0 fields are required to Publish.** P1 should be filled when known; P2 optional.
+
+Max **1–2** `supportedRoles` per page (primary + optional secondary).
+
+---
+
+## Closed enums
+
+### Platforms (`platforms: Platform[]`)
+
+```text
+xiaohongshu | tiktok | instagram | threads | x | linkedin | wechat_cover | generic
+```
+
+Multi-select. Use `x` for X/Twitter. See **exact recommended pixels** in `references/PLATFORM_SPECS.md` before choosing `canvasPreset`.
+
+### Canvas preset (`canvasPreset`)
+
+```text
+3:4 | 4:5 | 9:16 | 16:9 | 1:1 | 21:9 | custom
+```
+
+Always also store exact `canvas: { width, height }`. Use `16:9` for X **1200×675** in-stream; use `custom` for non-standard boards like link cards **1200×628**. Prefer the platform **Recommended** row in `PLATFORM_SPECS.md`.
+
+### Page roles (`supportedRoles` / pageRoles) — pick 1–2
+
+| Role | When to use |
+|---|---|
+| `cover` | Cover / first-frame poster |
+| `hook` | Scroll-stop hook (often with cover) |
+| `setup` | Setup / problem framing |
+| `context` | Background / context |
+| `value` | Single takeaway / value page |
+| `point` | One sharp point (lighter than value) |
+| `checklist` | Fixed N text lines (no list binding type) |
+| `proof` | Proof / credibility |
+| `evidence` | Evidence artifacts (data, case) |
+| `compare` | Before/after or A/B compare |
+| `screenshot` | App/web UI screenshot frame |
+| `metric` | Big number / KPI / milestone |
+| `quote` | Pull quote / testimonial |
+| `steps` | Fixed-step howto |
+| `cta` | Call to action |
+| `follow` | Follow / profile CTA |
+| `recap` | Summary / closing recap |
+
+Legacy-compatible: `cover`, `setup`, `value`, `proof`, `cta` remain valid.
+
+### Content family (`contentFamily`) — pick one
+
+```text
+narrative | utility | social_proof | conversion
+```
+
+### Content archetypes (`contentArchetypes`) — pick ≥1 from closed set
+
+```text
+product_review | tool_demo | tutorial | listicle
+personal_story | opinion | news_explainer
+lifestyle | travel | fitness | food_recipe
+career | finance_lite | ai_update
+launch | changelog | milestone_celebrate
+ugc_repost | quote_card
+```
+
+### Density (`density`)
+
+```text
+low | medium | high
+```
+
+Align with `textDensityRange` when both are set (e.g. low → `[0, 0.34]`, medium → `[0.33, 0.67]`, high → `[0.66, 1]`).
+
+### Visual style (`visualStyle`) — P1
+
+```text
+swiss | editorial | bold_promo | minimal | dark
+```
+
+### Image roles (`imageRoles`) — when any image slot exists
+
+```text
+hero | screenshot | avatar | product
+```
+
+---
+
+## P0 — required before Publish / must appear on Catalog summary
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | string | Human title |
+| `shortDescription` | string | One sentence for chooser UI |
+| `platforms` | `Platform[]` | Multi-select; use `generic` when truly cross-platform |
+| `canvasPreset` | preset enum | Plus exact `canvas` pixels |
+| `canvas` | `{ width, height }` | Exact board |
+| `supportedRoles` | pageRole[1..2] | Closed set above |
+| `contentFamily` | enum | Narrows before archetype |
+| `contentArchetypes` | archetype[] | ≥1 from closed set |
+| `density` | low/medium/high | |
+| `textDensityRange` | `[number, number]` | Keep in sync with density |
+| `requiresImage` | boolean | |
+| `imageRoles` | imageRole[] | Required if `requiresImage` or any image slot |
+| `mediaRequirements` | string[] | Normalized hints, e.g. `image`, `screenshot` |
+| `slotSummary` | `{ text, number, image }` | Counts of slots by type |
+| `fixedItemCount` | number? | Set for `checklist` / `steps` (absolute layout) |
+| `previewImageUrl` | url? | Required when Gateway/Studio can supply; block Publish if product requires it |
+| `tier` | `free` \| `paid` | From entitlement / owner; do not invent paid for free users |
+
+### `slotSummary` example
+
+```json
+{ "text": 4, "number": 1, "image": 1 }
+```
+
+Derived from the slot table in `SLOTS.md`.
+
+---
+
+## P1 — fill when known (strongly recommended)
+
+| Field | Type | Notes |
+|---|---|---|
+| `bestFor` | string[2..4] | “适合…” bullets for users |
+| `notFor` | string[1..3] | Honest exclusions |
+| `selectionHints` | string | Short Agent-only hint |
+| `visualStyle` | enum | Look affinity |
+| `defaultThemeId` | string? | Soft preview theme |
+| `compatibleThemeIds` | string[]? | Optional |
+| `locale` | `zh-CN` \| `en` \| `bilingual` | |
+| `exampleFilledPreviewUrl` | url? | Filled sample beats empty shell |
+
+---
+
+## P2 — optional
+
+| Field | Notes |
+|---|---|
+| `safeAreaProfile` | e.g. `xhs_default`, `ig_feed` |
+| `featured` | Catalog boost |
+| `colorDependency` | `theme_only` (preferred for new templates) \| `has_hardcoded_accents` |
+| `tags` | Free-form search aides only — never replace closed enums |
+
+---
+
+## Agent selection order (for Content → slideshow)
+
+Content Skill exports a template-neutral `ContentDocument` (slide roles + fields only).  
+**Compose** (Template Skill / Desktop / render workflow) then selects pages:
+
+```text
+1. platforms ∩ aspect/canvasPreset
+2. slide needs role ∈ supportedRoles
+3. contentFamily / contentArchetypes match topic
+4. requiresImage / imageRoles vs available assets
+5. density + slotSummary (+ fixedItemCount) fit copy
+6. Present 3–5 candidates: preview + name + shortDescription + bestFor
+7. User confirms, or accept account/system default Look (Theme) separately
+8. createRender with selected pageTemplateIds (never dump AST to the agent)
+```
+
+Example list call:
+
+```bash
+easysociable templates list --platforms x --roles metric --density low --limit 5 --json
+# MCP: list_templates({ platforms:['xiaohongshu'], roles:['metric'], density:'low', limit:5 })
+```
+
+**Catalog rules**
+
+- Only **published** pages with complete P0 `selection_metadata` appear in `list`.
+- Do **not** list every PageTemplate AST. Explain choices with this public metadata only.
+- Content Skill must not call Directus / TemplatePage; keep ADR-0019 surface split.
+
+---
+
+## Authoring checklist (before create / before Publish)
+
+Agent must produce a `selection-metadata.json` (or equivalent fields on the draft) containing **all P0** keys. Confirm with the user when roles/platforms were inferred from a brief or reference image.
+
+```json
+{
+  "name": "XHS metric milestone 3:4",
+  "shortDescription": "大数字涨粉庆祝页，可选头像",
+  "platforms": ["xiaohongshu", "generic"],
+  "canvasPreset": "3:4",
+  "canvas": { "width": 1080, "height": 1440 },
+  "supportedRoles": ["metric", "cover"],
+  "contentFamily": "conversion",
+  "contentArchetypes": ["milestone_celebrate", "launch"],
+  "density": "low",
+  "textDensityRange": [0, 0.34],
+  "requiresImage": false,
+  "imageRoles": ["avatar"],
+  "mediaRequirements": [],
+  "slotSummary": { "text": 2, "number": 1, "image": 1 },
+  "fixedItemCount": null,
+  "visualStyle": "swiss",
+  "bestFor": ["涨粉节点", "数据庆祝封面"],
+  "notFor": ["长清单干货", "多步教程"],
+  "selectionHints": "Prefer when slide.role is metric or cover and a single KPI dominates.",
+  "locale": "zh-CN"
+}
+```
+
+## Anti-patterns
+
+- Tagging five roles on one page “just in case”
+- Using only free-form `tags` instead of `supportedRoles` / archetypes
+- Checklist without `fixedItemCount`
+- `requiresImage: true` but `imageRoles` empty
+- Platforms empty or inventing values outside the enum

package/skills/easysociable-template/references/DESIGN_INTELLIGENCE.md

@@ -0,0 +1,69 @@
+# Design intelligence (lightweight)
+
+Curated hints for philosophy, concept, and palette phases when the user has no brand hex. Not a replacement for `DESIGN_PHILOSOPHY.md` or `DESIGN_CONCEPTS.md` — use to seed `movementName`, `paletteCandidates`, and font pairing.
+
+## Movement seeds (adapted from canvas-design; template-safe)
+
+Use these as philosophy starters. Rewrite into `design-plan.json` `philosophy` fields; keep required slots readable.
+
+| Seed movement | Space / composition | Rhythm / motif | Color mood | Font voice | Suggested hex |
+|---------------|---------------------|----------------|------------|------------|---------------|
+| Editorial Monument | One oversized focal; quiet gutters; thin attribution rail | Ledger rules, folio marks | Warm paper, dark ink, one accent | Editorial (serif display + Inter body) | `#0D9488` light |
+| Terminal Pulse | Compact header; centered status metric; tabular footer | Prompt glyph, status dot, hairline grid | Near-black canvas, electric accent | Terminal (JetBrains Mono + Inter) | `#14B8A6` dark |
+| Quiet Proof | Centered claim; generous negative space; small evidence row | Thin rules, soft dividers | Off-white, muted slate, restrained accent | Premium / editorial | `#475569` light |
+| Warm Folio | Asymmetric author block; hero quote or metric; soft margin marks | Paper edge, soft rules | Cream-warm canvas, amber or deep ink | Premium | `#B45309` light |
+| Signal Strip | Strong horizontal bands; one CTA or metric band dominates | Bars, ticks, progress marks | Neutral canvas, semantic green/blue sparingly | Modern SaaS (Inter/Inter) | `#2563EB` light |
+| Creator Spark | Playful asymmetry; one bold gesture type; sparse stickers as siblings | Blobs/dots as CSS only | Light canvas, saturated accent | Playful | `#DB2777` light |
+
+Map seed → `philosophy`:
+
+- `movementName` ← seed name
+- `space` / `composition` ← Space / composition column
+- `rhythm` ← Rhythm / motif
+- `color` ← Color mood (no final hex)
+- `typographyAccent` ← Font voice + display/body ratio intent
+- `craftBar` ← always include: one focal; no overlap; refine before adding decoration
+
+## Archetype → style hints
+
+| Archetype | Prefer movement seed | Layout bias | Palette mood |
+|-----------|----------------------|-------------|--------------|
+| Editorial / report | Editorial Monument | author rail, oversized metric | warm canvas, dark ink, one accent |
+| Terminal / indie hacker | Terminal Pulse | compact header, centered metric | dark canvas, electric accent |
+| Playful / creator | Creator Spark | asymmetric blocks | light canvas, saturated accent |
+| Luxury / premium | Warm Folio / Quiet Proof | centered hero, small caps metadata | off-white canvas, gold or deep accent |
+| Data / dashboard | Signal Strip | grid of metrics (still one primary focal) | neutral canvas, semantic green/red sparingly |
+
+## Suggested brand hex (no user color)
+
+Prefer curated presets in `references/THEME_PRESETS.md` / `theme-presets.json`, then generate with `--preset`. Fall back to mood hexes below only when presets do not fit.
+
+| Mood | Light mode hex | Dark mode hex | Notes | Close preset |
+|------|----------------|---------------|-------|--------------|
+| Trust / finance | `#0D9488` | `#14B8A6` | teal — readable on white and near-black | `ocean-depths` |
+| Energy / growth | `#16A34A` | `#22C55E` | green — watch muted contrast on light gray | `botanical-garden` |
+| Tech / product | `#2563EB` | `#3B82F6` | blue — strong default for SaaS | `tech-innovation` |
+| Bold / creator | `#DB2777` | `#EC4899` | pink — verify muted text on canvas | `desert-rose` (softer) |
+| Premium | `#B45309` | `#D97706` | amber — pair with warm off-white canvas | `golden-hour` |
+| Neutral authority | `#475569` | `#94A3B8` | slate — safe when accent must stay subtle | `modern-minimalist` |
+
+## Font pairing (Gateway `themeTokens.fonts`)
+
+| Voice | heading | body |
+|-------|---------|------|
+| Editorial | Georgia, serif stack | Inter |
+| Terminal | JetBrains Mono | Inter |
+| Modern SaaS | Inter | Inter |
+| Playful | Fredoka | Nunito |
+| Premium | Playfair Display | Source Sans 3 |
+
+Use platform-safe stacks if custom fonts are not loaded — default to `Inter` for both when unsure. Do **not** vendor canvas-design’s `canvas-fonts` TTFs into this skill.
+
+## Workflow tie-in
+
+1. After Brief, run `DESIGN_PHILOSOPHY.md` and seed `movementName` from the table above when needed.
+2. During `DESIGN_CONCEPTS.md`, attach `philosophyExpression` + named `paletteCandidates` (`name`, `brandHex`, `mode`, `bestFor`, optional `presetId`) per concept.
+3. After selection, run `PALETTE_REVIEW.md`: showcase swatches → wait for explicit confirmation → lock winner.
+4. Run `THEME_FROM_BRAND.md` (`--preset` or hex) to produce `theme-tokens.json`; do not `theme.create` until confirmed.
+
+Do not treat this table as exhaustive — adjust hex when contrast fails.

package/skills/easysociable-template/references/DESIGN_V2_1.md

@@ -0,0 +1,278 @@
+# V2.1 design and visual-QA contracts
+
+Use these local artifacts to make art direction and screenshot review explicit. They are workflow artifacts, not Gateway DTOs.
+
+## Contents
+
+- `design-philosophy.md`: human-readable visual philosophy (optional companion to the JSON field)
+- `design-plan.json`: philosophy, art direction, concept selection, asset decisions, and theme preview
+- `theme-tokens.json`: generated brand scale, semantic colors, and WCAG contrast report
+- `visual-qa.json`: screenshot evidence, fixed scores, and pass/revise verdict
+
+## `design-plan.json`
+
+```json
+{
+  "schemaVersion": "design_plan_v2_1",
+  "sourceKind": "text_brief",
+  "intent": {
+    "jobToBeDone": "Make monthly revenue understandable in one glance",
+    "primaryPlatform": "x",
+    "canvas": { "width": 1200, "height": 675 }
+  },
+  "philosophy": {
+    "movementName": "Editorial Ledger",
+    "space": "Generous top margin; one monumental metric zone; quiet side gutters",
+    "color": "Warm paper canvas, near-black ink, one teal accent; decoration stays ink-weight",
+    "rhythm": "Horizontal ledger rules and folio marks at a fixed cadence",
+    "composition": "Author rail top; oversized metric center-left; breakdown as a thin footer band",
+    "typographyAccent": "Display metric ~4x body; metadata in small caps or mono; no paragraph stacks",
+    "craftBar": "Museum-grade spacing; no overlap; one focal; refine before adding decoration",
+    "subtleReference": "Monthly close / ledger credibility without literal spreadsheet chrome",
+    "templateConstraints": "Required brief slots stay bindable; flat absolute siblings; Theme owns color; never flatten copy into a generated poster"
+  },
+  "concepts": [
+    {
+      "id": "editorial-ledger",
+      "name": "Editorial ledger",
+      "rationale": "Use report-like credibility and one oversized metric",
+      "philosophyExpression": "Monumental metric left of center; rules as quiet rhythm; author attribution as a thin top rail",
+      "visualMotif": "ledger rules and folio marks",
+      "layout": "author rail at top, metric center-left, breakdown footer",
+      "hierarchy": "revenue > period/title > author > breakdown",
+      "typography": "display metric at roughly 4x body scale",
+      "colorStrategy": "warm canvas, dark ink, one green accent",
+      "paletteCandidates": [
+        {
+          "name": "Ocean Depths",
+          "presetId": "ocean-depths",
+          "brandHex": "#1A6B6B",
+          "mode": "light",
+          "bestFor": "Finance, consulting, trust-building metric cards",
+          "label": "teal editorial"
+        }
+      ],
+      "assetStrategy": "avatar plus CSS/SVG rules; no hero illustration",
+      "risks": ["long currency strings"]
+    },
+    {
+      "id": "terminal-scorecard",
+      "name": "Terminal scorecard",
+      "rationale": "Give an indie-hacker technical voice",
+      "philosophyExpression": "Same ledger philosophy expressed as a compact prompt header and centered status metric",
+      "visualMotif": "terminal prompt and status light",
+      "layout": "compact author header, centered metric, tabular footer",
+      "hierarchy": "revenue > growth > author",
+      "typography": "large grotesk metric with monospace metadata",
+      "colorStrategy": "near-black canvas and one electric accent",
+      "paletteCandidates": [
+        { "brandHex": "#0D9488", "mode": "dark", "label": "teal terminal" }
+      ],
+      "assetStrategy": "avatar and CSS grid",
+      "risks": ["neon contrast can become harsh"]
+    }
+  ],
+  "selectedConceptId": "editorial-ledger",
+  "selectionReason": "Best matches a trustworthy monthly report",
+  "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
+  },
+  "surfacePreview": {
+    "kind": "gradient",
+    "userConfirmed": true,
+    "recipeId": "grad_001_warm-flame",
+    "name": "Warm Flame",
+    "provider": "webgradients",
+    "textSafeZone": "light_end",
+    "contrastAnchor": "#FAD0C4",
+    "placement": "full_bleed"
+  },
+  "assetPlan": [
+    {
+      "role": "avatar",
+      "source": "user_upload",
+      "required": true,
+      "description": "X profile avatar",
+      "treatment": "circular crop; retain face focal point"
+    },
+    {
+      "role": "background",
+      "source": "gradient_catalog",
+      "required": false,
+      "description": "Warm Flame wash under metric"
+    },
+    {
+      "role": "decorative",
+      "source": "css_svg",
+      "required": false,
+      "description": "ledger rules and small folio marks"
+    }
+  ]
+}
+```
+
+Rules:
+
+- `text_brief` requires 2–3 concepts; `image_reference` permits one.
+- `text_brief` requires root `philosophy` with non-empty `movementName`, `space`, `color`, `rhythm`, `composition`, `typographyAccent`, and `craftBar`.
+- `image_reference` should include a short reverse-engineered `philosophy` (same fields) so Visual QA has a craft bar.
+- Optional philosophy fields: `subtleReference`, `templateConstraints` (recommended).
+- Concepts must have unique IDs and all listed art-direction fields.
+- Every concept requires `philosophyExpression` (how this layout expresses the shared philosophy in space).
+- Concept `layout` / `hierarchy` / `typography` must be traceable to philosophy fields (documented rule; not NLP-checked).
+- Concepts are spatial expressions of **one** shared philosophy — not unrelated slogans. Changing only colors is not a different concept.
+- `selectedConceptId` must reference a concept.
+- `selectionReason` is required.
+- `assetPlan` may be empty when the concept intentionally uses typography only.
+- Allowed asset roles: `background`, `hero`, `decorative`, `avatar`, `logo`, `icon`.
+- Allowed sources: `user_upload`, `brand_kit`, `css_svg`, `gradient_catalog`, `asset_library`, `template_icon_catalog` (legacy alias `better_icons`), `external_photo`, `generated`, `none`.
+- Optional per concept: `paletteCandidates` — array of `{ brandHex, mode, name?, presetId?, bestFor?, notFor?, label? }` where `mode` is `light` or `dark`. Prefer `name` + `bestFor` when presenting choices.
+- Optional root: `themePreview` — `{ brandHex, activeMode, contrastPass, themeTokensPath, name?, presetId?, bestFor?, userConfirmed? }` after palette lock. Set `userConfirmed: true` only after explicit user choice (or waived).
+- Optional root: `surfacePreview` — `{ kind: flat|gradient|image, userConfirmed, … }`. When `kind` is `gradient` or `image`, require `userConfirmed: true` before authoring those nodes; `gradient` needs `recipeId`; `image` needs `imageId` (or documented pending import) and `imageMode` (`fixed` default for surface background).
+## Companion `design-philosophy.md`
+
+Human-readable twin of `design-plan.json` → `philosophy`. Recommended structure:
+
+```markdown
+# Design Philosophy — <movementName>
+
+## Space
+...
+
+## Color
+...
+
+## Rhythm
+...
+
+## Composition
+...
+
+## Typography as accent
+...
+
+## Craft bar
+...
+
+## Template constraints
+- Required brief slots stay bindable
+- Flat absolute siblings only
+- Theme owns color; never flatten copy into a generated poster
+```
+
+## `theme-tokens.json`
+
+```json
+{
+  "schemaVersion": "theme_tokens_v2",
+  "brandHex": "#0D9488",
+  "scale": {
+    "50": "#F2FCFC",
+    "500": "#14E1D0",
+    "600": "#10BCAD",
+    "950": "#042F2B"
+  },
+  "semantic": {
+    "light": {
+      "canvas": "#FFFFFF",
+      "text": "#042F2B",
+      "accent": "#10BCAD",
+      "muted": "#10BCAD",
+      "primary": "#10BCAD",
+      "border": "#C6F5F1"
+    },
+    "dark": {
+      "canvas": "#042F2B",
+      "text": "#F2FCFC",
+      "accent": "#14E1D0",
+      "muted": "#51ECDF",
+      "primary": "#14E1D0",
+      "border": "#0B7F75"
+    }
+  },
+  "activeMode": "light",
+  "themeTokens": {
+    "colors": {
+      "canvas": "#FFFFFF",
+      "text": "#042F2B",
+      "accent": "#10BCAD",
+      "muted": "#10BCAD",
+      "primary": "#10BCAD",
+      "border": "#C6F5F1"
+    },
+    "fonts": { "heading": "Inter", "body": "Inter" },
+    "surfaces": { "radius": "12px", "shadow": "0 8px 24px rgba(0,0,0,.12)" },
+    "palette": {}
+  },
+  "themeTokensLight": {},
+  "themeTokensDark": {},
+  "contrast": [
+    {
+      "pair": "text/canvas",
+      "mode": "light",
+      "foreground": "#042F2B",
+      "background": "#FFFFFF",
+      "ratio": 16.2,
+      "wcagAA": true,
+      "wcagAAA": true
+    }
+  ],
+  "contrastPass": true
+}
+```
+
+Rules:
+
+- `scale` must include shades `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `950`.
+- `brandHex` must be `#` + 6 hex digits.
+- `activeMode` is `light` or `dark`; `themeTokens` must match the active semantic palette.
+- `themeTokens.colors` requires `canvas`, `text`, `accent`, `muted` (hex strings). Prefer also `primary` and `border` when co-creating v2.
+- `themeTokens.fonts` requires `heading` and `body`.
+- `themeTokens.surfaces` requires `radius` and `shadow`.
+- `contrast` entries require `pair`, `mode`, `foreground`, `background`, `ratio`, `wcagAA`, `wcagAAA`.
+- `contrastPass` must be `true` before authoring when co-creating a new theme.
+
+## `visual-qa.json`
+
+```json
+{
+  "schemaVersion": "visual_qa_v2_1",
+  "draftId": "draft_123",
+  "iteration": 1,
+  "screenshotEvidence": "/absolute/path/to/studio-render.png",
+  "hardFailures": [],
+  "scores": {
+    "hierarchy": 18,
+    "composition": 13,
+    "spacingAlignment": 13,
+    "typography": 13,
+    "colorContrast": 9,
+    "assetRelevance": 8,
+    "contentResilience": 8,
+    "editability": 5
+  },
+  "total": 87,
+  "verdict": "pass",
+  "issues": [],
+  "changesMade": ["Increased metric size", "Reduced footer density"]
+}
+```
+
+Score maxima total 100. `pass` requires:
+
+- inspectable `screenshotEvidence`
+- `iteration` from 0 to 2
+- no `hardFailures`
+- each score within its maximum
+- declared `total` equal to the calculated sum and at least 80
+
+Use `verdict: "revise"` below threshold while iterating. Do not hand off a `revise` result as a reviewed template unless the user explicitly accepts it.
+
+Craft Pass (behavior, not new score fields): when `iteration >= 1`, prefer tightening existing nodes over adding decoration; score against `philosophy.craftBar` and `philosophyExpression` of the selected concept.

package/skills/easysociable-template/references/EXTERNAL_RESOURCES.md

@@ -0,0 +1,52 @@
+# External resources & Surface routing
+
+Template Skill **orchestrates** discovery; EasySociable **owns** materialization.
+
+## Boundary
+
+| Phase | Who | Tools |
+|---|---|---|
+| Discover photos | Host Agent MCPs | Pinterest, Unsplash, Pexels |
+| Discover icons | Template product | MCP/CLI `search_icons` / `get_icon` → Gateway Icon Catalog (ADR-0023) |
+| Discover gradients | Template product | MCP/CLI `gradients list\|search\|get` → Gateway |
+| Materialize | Template Gateway only | Image import (R2 + Directus `Image`), icon materialize (`TemplateIconAsset`), inline gradient CSS, Draft update, Preview, Publish |
+
+Template MCP/CLI must **not** expose Unsplash/Pexels/Pinterest search tools. Icons are **not** discovered via Better Icons MCP — use the internal catalog only.
+
+## Decision order
+
+```text
+user_upload / brand_kit
+→ Design Primitive / CSS-SVG
+→ gradients (Gateway catalog)
+→ search_icons / get_icon (Gateway Icon Catalog)
+→ Pinterest / Unsplash / Pexels (host MCP)
+→ generated topic image (last resort)
+→ omit
+```
+
+## Degradation
+
+| Missing | Agent behavior |
+|---|---|
+| Unsplash/Pexels/Pinterest MCP | Say so; offer flat / gradient / user upload; continue without photo |
+| Icon Catalog / Gateway auth | Return Gateway error (`ICON_*` / `TEMPLATE_API_KEY_REQUIRED`); offer CSS/SVG mark or omit icon — do **not** install or call Better Icons |
+| Gradients API / auth | Fall back to `flat` or simple CSS two-stop only if user supplies hexes; do not scrape WebGradients at runtime |
+| Draft image import unavailable | Keep confirmed photo out of Publish path; do not embed temp URLs; ask user to upload in Studio |
+
+## Rights
+
+- Record provider, source URL, creator, query, license/Attribution, rights state when importing images.
+- Pinterest often starts `reference_only` / needs explicit publish-rights confirmation.
+- Unsplash/Pexels follow provider license + Attribution rules.
+- Gradients: record `provider` + `license` from catalog detail; inline CSS only.
+- Icons: use `iconAssetId` + provenance from `get_icon`; Theme colors via `currentColor` / `--es-*` — never bake Theme hex into canonical SVG.
+- Publish must reject unresolved rights (product gate); Skill must not pretend rights are cleared.
+
+## Modes
+
+- Surface background image → default **`fixed`**
+- Slot image → ask **`fixed`** or **`slot_default`**
+- Rights state is orthogonal to mode
+
+See `workflows/SURFACE_REVIEW.md` for the confirmation loop.

package/skills/easysociable-template/references/GATEWAY.md

@@ -0,0 +1,25 @@
+# Unified Gateway reference
+
+The public executable is `easysociable`; the public MCP is the unified server.
+Template operations use these command families:
+
+```bash
+easysociable auth status --json
+easysociable templates list --json
+easysociable templates get --id <id> --json
+easysociable templates create-draft --file ./draft.json --json
+easysociable templates update --id <id> --file ./patch.json --json
+easysociable templates validate --id <id> --json
+easysociable templates publish --id <id> --json
+easysociable icons search --query "arrow" --json
+easysociable icons get --icon-id <id> --idempotency-key <key> --json
+easysociable renders create --template-id <id> --slots ./slots.json --format png --idempotency-key render_1 --json
+easysociable renders wait --id <id> --json
+```
+
+All requests go through Gateway. The client receives public summaries, slot
+contracts, stable Image references and render Manifests only. It never receives
+AST, Binding Maps, private RenderPlans or provider credentials.
+
+External Pexels/Unsplash/Pinterest MCPs remain optional host capabilities for
+discovery. They are not auto-installed and are not EasySociable API paths.