@easysociable/cli 0.1.0

package/skills/easysociable-template/scripts/validate-design-v2.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const filePath = process.argv[2]
+
+if (!filePath) {
+  console.error('Usage: node scripts/validate-design-v2.mjs <design-plan.json|theme-tokens.json|visual-qa.json|->')
+  process.exit(2)
+}
+
+let value
+try {
+  const input = filePath === '-'
+    ? fs.readFileSync(0, 'utf8')
+    : fs.readFileSync(path.resolve(filePath), 'utf8')
+  value = JSON.parse(input)
+}
+catch (error) {
+  console.error(`Invalid JSON: ${error.message}`)
+  process.exit(1)
+}
+
+const errors = []
+const nonEmpty = (candidate) => typeof candidate === 'string' && candidate.trim().length > 0
+const HEX_RE = /^#[0-9A-Fa-f]{6}$/
+const SHADES = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950']
+const THEME_COLOR_KEYS = ['canvas', 'text', 'accent', 'muted']
+
+function validatePaletteCandidates(candidates, index) {
+  if (!Array.isArray(candidates))
+    return
+  candidates.forEach((candidate, candidateIndex) => {
+    if (!HEX_RE.test(candidate?.brandHex ?? ''))
+      errors.push(`concepts[${index}].paletteCandidates[${candidateIndex}].brandHex must be #RRGGBB`)
+    if (!['light', 'dark'].includes(candidate?.mode))
+      errors.push(`concepts[${index}].paletteCandidates[${candidateIndex}].mode must be light or dark`)
+    if (candidate?.name !== undefined && !nonEmpty(candidate.name))
+      errors.push(`concepts[${index}].paletteCandidates[${candidateIndex}].name must be non-empty when present`)
+    if (candidate?.bestFor !== undefined && !nonEmpty(candidate.bestFor))
+      errors.push(`concepts[${index}].paletteCandidates[${candidateIndex}].bestFor must be non-empty when present`)
+  })
+}
+
+function validateThemePreview(preview) {
+  if (!preview)
+    return
+  if (!HEX_RE.test(preview.brandHex ?? ''))
+    errors.push('themePreview.brandHex must be #RRGGBB')
+  if (!['light', 'dark'].includes(preview.activeMode))
+    errors.push('themePreview.activeMode must be light or dark')
+  if (typeof preview.contrastPass !== 'boolean')
+    errors.push('themePreview.contrastPass must be boolean')
+  if (!nonEmpty(preview.themeTokensPath))
+    errors.push('themePreview.themeTokensPath is required')
+  if (preview.name !== undefined && !nonEmpty(preview.name))
+    errors.push('themePreview.name must be non-empty when present')
+  if (preview.userConfirmed !== undefined && typeof preview.userConfirmed !== 'boolean')
+    errors.push('themePreview.userConfirmed must be boolean when present')
+}
+
+function validateSurfacePreview(preview) {
+  if (!preview)
+    return
+  const kinds = new Set(['flat', 'gradient', 'image'])
+  if (!kinds.has(preview.kind))
+    errors.push('surfacePreview.kind must be flat, gradient, or image')
+  if (typeof preview.userConfirmed !== 'boolean')
+    errors.push('surfacePreview.userConfirmed must be boolean')
+  if (preview.kind === 'gradient' || preview.kind === 'image') {
+    if (preview.userConfirmed !== true)
+      errors.push(`surfacePreview.userConfirmed must be true when kind is ${preview.kind}`)
+  }
+  if (preview.kind === 'gradient' && preview.userConfirmed === true && !nonEmpty(preview.recipeId))
+    errors.push('surfacePreview.recipeId is required when kind is gradient and confirmed')
+  if (preview.kind === 'image' && preview.userConfirmed === true) {
+    if (!nonEmpty(preview.imageId) && preview.importPending !== true)
+      errors.push('surfacePreview.imageId is required when kind is image and confirmed (or set importPending true)')
+    if (preview.imageMode !== undefined && !['fixed', 'slot_default'].includes(preview.imageMode))
+      errors.push('surfacePreview.imageMode must be fixed or slot_default when present')
+  }
+  if (preview.textSafeZone !== undefined
+    && !['light_end', 'dark_end', 'needs_scrim'].includes(preview.textSafeZone)) {
+    errors.push('surfacePreview.textSafeZone must be light_end, dark_end, or needs_scrim when present')
+  }
+  if (preview.contrastAnchor !== undefined && !HEX_RE.test(preview.contrastAnchor))
+    errors.push('surfacePreview.contrastAnchor must be #RRGGBB when present')
+}
+
+const PHILOSOPHY_REQUIRED_FIELDS = [
+  'movementName',
+  'space',
+  'color',
+  'rhythm',
+  'composition',
+  'typographyAccent',
+  'craftBar',
+]
+
+function validatePhilosophy(philosophy, required) {
+  if (!philosophy || typeof philosophy !== 'object') {
+    if (required)
+      errors.push('philosophy is required')
+    return
+  }
+  PHILOSOPHY_REQUIRED_FIELDS.forEach((field) => {
+    if (!nonEmpty(philosophy[field]))
+      errors.push(`philosophy.${field} is required`)
+  })
+}
+
+function validateThemeTokensBlock(tokens, label) {
+  const colors = tokens?.colors ?? {}
+  THEME_COLOR_KEYS.forEach((key) => {
+    if (!HEX_RE.test(colors[key] ?? ''))
+      errors.push(`${label}.colors.${key} must be #RRGGBB`)
+  })
+  if (!nonEmpty(tokens?.fonts?.heading))
+    errors.push(`${label}.fonts.heading is required`)
+  if (!nonEmpty(tokens?.fonts?.body))
+    errors.push(`${label}.fonts.body is required`)
+  if (!nonEmpty(tokens?.surfaces?.radius))
+    errors.push(`${label}.surfaces.radius is required`)
+  if (!nonEmpty(tokens?.surfaces?.shadow))
+    errors.push(`${label}.surfaces.shadow is required`)
+}
+
+function validateDesignPlan(plan) {
+  const allowedSourceKinds = new Set(['text_brief', 'image_reference'])
+  const allowedRoles = new Set(['background', 'hero', 'decorative', 'avatar', 'logo', 'icon'])
+  const allowedSources = new Set([
+    'user_upload',
+    'brand_kit',
+    'css_svg',
+    'gradient_catalog',
+    'asset_library',
+    'better_icons',
+    'template_icon_catalog',
+    'external_photo',
+    'generated',
+    'none',
+  ])
+  const conceptFields = [
+    'id',
+    'name',
+    'rationale',
+    'visualMotif',
+    'layout',
+    'hierarchy',
+    'typography',
+    'colorStrategy',
+    'assetStrategy',
+  ]
+
+  if (!allowedSourceKinds.has(plan.sourceKind))
+    errors.push('sourceKind must be text_brief or image_reference')
+  if (!nonEmpty(plan.intent?.jobToBeDone))
+    errors.push('intent.jobToBeDone is required')
+  if (!nonEmpty(plan.intent?.primaryPlatform))
+    errors.push('intent.primaryPlatform is required')
+  if (!(Number(plan.intent?.canvas?.width) > 0) || !(Number(plan.intent?.canvas?.height) > 0))
+    errors.push('intent.canvas width and height must be positive numbers')
+
+  const concepts = Array.isArray(plan.concepts) ? plan.concepts : []
+  const minimum = plan.sourceKind === 'image_reference' ? 1 : 2
+  if (concepts.length < minimum || concepts.length > 3)
+    errors.push(`${plan.sourceKind || 'text_brief'} requires ${minimum}–3 concepts`)
+
+  // Both source kinds need a philosophy so Visual QA has a craft bar.
+  validatePhilosophy(plan.philosophy, true)
+
+  const ids = new Set()
+  concepts.forEach((concept, index) => {
+    conceptFields.forEach((field) => {
+      if (!nonEmpty(concept?.[field]))
+        errors.push(`concepts[${index}].${field} is required`)
+    })
+    if (!nonEmpty(concept?.philosophyExpression))
+      errors.push(`concepts[${index}].philosophyExpression is required`)
+    if (nonEmpty(concept?.id)) {
+      if (ids.has(concept.id))
+        errors.push(`Duplicate concept id: ${concept.id}`)
+      ids.add(concept.id)
+    }
+    if (!Array.isArray(concept?.risks))
+      errors.push(`concepts[${index}].risks must be an array`)
+    validatePaletteCandidates(concept?.paletteCandidates, index)
+  })
+
+  if (!nonEmpty(plan.selectedConceptId) || !ids.has(plan.selectedConceptId))
+    errors.push('selectedConceptId must reference an existing concept')
+  if (!nonEmpty(plan.selectionReason))
+    errors.push('selectionReason is required')
+  validateThemePreview(plan.themePreview)
+  validateSurfacePreview(plan.surfacePreview)
+  if (!Array.isArray(plan.assetPlan))
+    errors.push('assetPlan must be an array (it may be empty)')
+  else {
+    plan.assetPlan.forEach((asset, index) => {
+      if (!allowedRoles.has(asset?.role))
+        errors.push(`assetPlan[${index}].role is invalid`)
+      if (!allowedSources.has(asset?.source))
+        errors.push(`assetPlan[${index}].source is invalid`)
+      if (typeof asset?.required !== 'boolean')
+        errors.push(`assetPlan[${index}].required must be boolean`)
+      if (!nonEmpty(asset?.description))
+        errors.push(`assetPlan[${index}].description is required`)
+    })
+  }
+}
+
+function validateThemeTokens(theme) {
+  if (!HEX_RE.test(theme.brandHex ?? ''))
+    errors.push('brandHex must be #RRGGBB')
+  if (!['light', 'dark'].includes(theme.activeMode))
+    errors.push('activeMode must be light or dark')
+  if (theme.contrastPass !== true)
+    errors.push('contrastPass must be true — regenerate theme or adjust hex/mode before authoring')
+
+  SHADES.forEach((shade) => {
+    if (!HEX_RE.test(theme.scale?.[shade] ?? ''))
+      errors.push(`scale.${shade} must be #RRGGBB`)
+  })
+  ;['light', 'dark'].forEach((mode) => {
+    const palette = theme.semantic?.[mode] ?? {}
+    ;['canvas', 'text', 'accent', 'muted', 'primary', 'border'].forEach((key) => {
+      if (!HEX_RE.test(palette[key] ?? ''))
+        errors.push(`semantic.${mode}.${key} must be #RRGGBB`)
+    })
+  })
+
+  validateThemeTokensBlock(theme.themeTokens, 'themeTokens')
+  validateThemeTokensBlock(theme.themeTokensLight, 'themeTokensLight')
+  validateThemeTokensBlock(theme.themeTokensDark, 'themeTokensDark')
+
+  if (!Array.isArray(theme.contrast) || theme.contrast.length === 0)
+    errors.push('contrast must be a non-empty array')
+  else {
+    theme.contrast.forEach((entry, index) => {
+      if (!nonEmpty(entry?.pair))
+        errors.push(`contrast[${index}].pair is required`)
+      if (!['light', 'dark'].includes(entry?.mode))
+        errors.push(`contrast[${index}].mode must be light or dark`)
+      if (!HEX_RE.test(entry?.foreground ?? '') || !HEX_RE.test(entry?.background ?? ''))
+        errors.push(`contrast[${index}] foreground and background must be #RRGGBB`)
+      if (typeof entry?.ratio !== 'number' || entry.ratio <= 0)
+        errors.push(`contrast[${index}].ratio must be a positive number`)
+      if (typeof entry?.wcagAA !== 'boolean' || typeof entry?.wcagAAA !== 'boolean')
+        errors.push(`contrast[${index}] wcagAA and wcagAAA must be boolean`)
+    })
+  }
+}
+
+function validateVisualQa(qa) {
+  const maxima = {
+    hierarchy: 20,
+    composition: 15,
+    spacingAlignment: 15,
+    typography: 15,
+    colorContrast: 10,
+    assetRelevance: 10,
+    contentResilience: 10,
+    editability: 5,
+  }
+
+  if (!nonEmpty(qa.draftId))
+    errors.push('draftId is required')
+  if (!Number.isInteger(qa.iteration) || qa.iteration < 0 || qa.iteration > 2)
+    errors.push('iteration must be an integer from 0 to 2')
+  if (!nonEmpty(qa.screenshotEvidence))
+    errors.push('screenshotEvidence is required')
+  if (!Array.isArray(qa.hardFailures))
+    errors.push('hardFailures must be an array')
+  if (!Array.isArray(qa.issues))
+    errors.push('issues must be an array')
+  if (!Array.isArray(qa.changesMade))
+    errors.push('changesMade must be an array')
+  if (!['pass', 'revise'].includes(qa.verdict))
+    errors.push('verdict must be pass or revise')
+
+  let calculatedTotal = 0
+  for (const [field, maximum] of Object.entries(maxima)) {
+    const score = qa.scores?.[field]
+    if (typeof score !== 'number' || score < 0 || score > maximum)
+      errors.push(`scores.${field} must be between 0 and ${maximum}`)
+    else
+      calculatedTotal += score
+  }
+
+  if (qa.total !== calculatedTotal)
+    errors.push(`total must equal calculated score ${calculatedTotal}`)
+  if (qa.verdict === 'pass') {
+    if (qa.hardFailures?.length > 0)
+      errors.push('pass verdict cannot contain hardFailures')
+    if (calculatedTotal < 80)
+      errors.push('pass verdict requires a score of at least 80')
+  }
+  if (qa.verdict === 'revise' && calculatedTotal >= 80 && qa.hardFailures?.length === 0)
+    errors.push('revise verdict conflicts with a passing score and no hardFailures')
+}
+
+if (value?.schemaVersion === 'design_plan_v2_1')
+  validateDesignPlan(value)
+else if (value?.schemaVersion === 'theme_tokens_v2')
+  validateThemeTokens(value)
+else if (value?.schemaVersion === 'visual_qa_v2_1')
+  validateVisualQa(value)
+else
+  errors.push('schemaVersion must be design_plan_v2_1, theme_tokens_v2, or visual_qa_v2_1')
+
+if (errors.length > 0) {
+  console.error(`V2.1 validation failed (${errors.length}):`)
+  errors.forEach((error) => console.error(`- ${error}`))
+  process.exit(1)
+}
+
+console.log(`V2.1 validation passed: ${value.schemaVersion}`)

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

@@ -0,0 +1,34 @@
+# Asset plan (V2.1)
+
+Run after concept selection and before authoring. Give every non-text visual a clear semantic role and source.
+
+When atmosphere, photography, or icons are involved, run `workflows/SURFACE_REVIEW.md` (and read `references/EXTERNAL_RESOURCES.md`) in the same pass.
+
+## Source priority
+
+Choose the first adequate option:
+
+1. `user_upload` — user avatar, logo, product screenshot, supplied photo
+2. `brand_kit` — approved reusable brand asset
+3. `template_icon_catalog` — **required for any icon/glyph** (arrow, chevron, check, social mark, next-page cue, …). Confirmed Gateway `search_icons` → user confirm → `get_icon` (`iconAssetId` + `canonicalSvg`). **Not optional when catalog works.**
+4. `gradient_catalog` — confirmed recipe from Gateway `gradients.*` (inline CSS decoration)
+5. `css_svg` — local CSS/SVG **geometry only** (hairlines, rails, anonymous discs/masks). **Do not** use this source for symbol icons when `template_icon_catalog` is available.
+6. `asset_library` — vetted texture, frame, or decorative primitive (non-icon)
+7. `external_photo` — confirmed host Unsplash/Pexels/Pinterest pick (Gateway import → CDN/`imageId`)
+8. `generated` — topic-specific hero, illustration, object, or complex background
+9. `none` — omit visuals that do not improve communication
+
+## Rules
+
+- Record `role`, `source`, `required`, `description`, and treatment for every asset.
+- Roles: `background | hero | decorative | avatar | logo | icon`.
+- For `external_photo` / `template_icon_catalog` / `gradient_catalog`: discovery → bounded showcase → **user confirm** → materialize. Unselected → no EasySociable write.
+- **`role: icon` ⇒ `source` MUST be `template_icon_catalog`** (unless catalog failed and user approved degrade). Never invent path SVG for icons “to go faster”.
+- Never put third-party temporary URLs into `authoringSource`.
+- Use generated imagery only when it supports the selected concept. Prefer transparent, text-free, crop-safe elements for independent decorations.
+- Never ask image generation to render the final poster, headline, metric, avatar name, or other replaceable content.
+- Keep generated prompts and returned asset IDs/paths as provenance when available.
+- Define focal point/crop behavior for image slots. Ensure foreground text retains contrast over backgrounds (`surfacePreview.contrastAnchor` / scrim when needed).
+- When no asset service/library exists, degrade per `EXTERNAL_RESOURCES.md`; do not invent asset IDs or scrape providers at runtime.
+
+Write the result into `design-plan.json` (`assetPlan` + `surfacePreview` when applicable) and validate before creating `authoringSource`.

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

@@ -0,0 +1,52 @@
+# Author from text brief
+
+Primary intake when the user describes a single-page template in words (no reference image, or image is secondary).
+
+## Goal
+
+One publishable **single-page** template draft: Design Brief → Design Philosophy → 2–3 Concepts → Asset Plan → Theme lock → slot table + absolute layout → screenshot QA → Authoring Studio.
+
+## Steps
+
+1. Confirm this is **one page**, not a slideshow. If they want a multi-slide deck, stop and hand off (`OUT_OF_SCOPE.md`).
+2. Read `references/PLATFORM_SPECS.md` and lock platforms + **Recommended** canvas (preset + pixels).
+3. **Mandatory — V2.1 design plan first** (no reference image):
+   - Follow `workflows/DESIGN_BRIEF.md`
+   - Follow `workflows/DESIGN_PHILOSOPHY.md`; lock shared `philosophy` (+ companion `design-philosophy.md`)
+   - Follow `workflows/DESIGN_CONCEPTS.md`; create 2–3 spatial expressions of that philosophy and select one (`philosophyExpression` on each)
+   - Follow `workflows/ASSET_PLAN.md`; give every planned visual asset a role and source
+   - Follow `workflows/SURFACE_REVIEW.md` when atmosphere, photography, or icons are needed (`flat` | `gradient` | `image`)
+   - Follow `workflows/PALETTE_REVIEW.md` and `workflows/THEME_FROM_BRAND.md` when co-creating Theme (no `themeId`)
+   - Write and validate `design-plan.json` and `theme-tokens.json` using `scripts/validate-design-v2.mjs`
+   - Do not build `authoringSource` before philosophy, concept selection, theme lock, surface confirmation (when applicable), and design-plan validation
+4. After design-plan acceptance, build:
+   - `selection-metadata.json` with all P0 fields (+ P1 when known) — `references/CATALOG_METADATA.md`
+   - Slot table per `references/SLOTS.md` (no `list`; checklists = multiple `text_n` + `fixedItemCount`)
+   - Flat absolutely positioned nodes (canvas siblings only; no absolute-inside-absolute wrappers); bind fillable text/number with **`data-variable`** (Studio/Gateway compile); images use `data-image-mode` + binding per image docs
+   - Inline `style={{...}}` for exact geometry and critical typography; no Tailwind arbitrary-value layout classes
+   - Surface: gradient → unbound CSS decoration sibling; image → CDN/`imageId` background (`fixed` default)
+   - **Icons:** only Gateway `search_icons` → confirm → `get_icon` → `canonicalSvg` + `iconAssetId` (`SURFACE_REVIEW.md`). Never hand-draw icon paths when catalog works.
+   - Other decorations as CSS geometry (rails, hairlines, discs) that obey `philosophy.rhythm` — not new illustrations or fake icons by default
+   - `authoringSource` per `references/AUTHORING_SOURCE.md` (flat tree + text-nesting exception)
+   - Theme per `references/THEME_TOKENS.md` — use `themeTokens` from validated `theme-tokens.json` for `theme.create`
+5. Run `scripts/validate-authoring-source.mjs <authoring-source.json>` and fix every error.
+6. Continue with `workflows/AUTHORING_STUDIO.md` (`source.kind = text_brief`); its Visual QA loop is required before handoff.
+
+## Checklist pages
+
+- Prefer a **fixed** number of required text slots matching the design brief.
+- Do not promise automatic packing when some lines are empty (absolute layout).
+- Optional text lines are allowed but omitting them leaves gaps.
+
+## Do not
+
+- Create multi-page packs
+- Invent `list` / bullets array bindings
+- Skip Design Brief, Philosophy, Concepts, or Asset Plan when there is no reference image
+- Produce concepts that differ only by color or ignore the shared philosophy
+- Generate a whole flattened poster instead of editable text/image/layout nodes
+- Pick a non-recommended canvas without telling the user why
+- Use `left-[...]`, `top-[...]`, `w-[...]`, `text-[...]`, or other arbitrary-value classes for critical runtime layout
+- Nest absolutely positioned nodes inside cards/groups (`profile-card` wrapping avatar + name, etc.)
+- Auto-publish without user Save + explicit “publish” request (`PUBLISH_FROM_DRAFT.md`)
+- Hand-draw SVG icon paths (arrows, chevrons, checks, next cues, …) when Icon Catalog search works — use `search_icons` → confirm → `get_icon`

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

@@ -0,0 +1,52 @@
+# Author from reference image
+
+Intake when the user provides a poster / card image to turn into a **single-page** template.
+
+## Goal
+
+Vision/LLM understanding stays **local**. Output is a structured candidate (`authoringSource` + slot table + Theme), not a claim of pixel-perfect clone. User always finishes in Authoring Studio.
+
+## Steps
+
+1. Confirm single-page intent (not “rebuild this whole carousel as one Agent pack”).
+2. Read `references/PLATFORM_SPECS.md` when mapping detected aspect → platform defaults.
+3. Inspect the image and extract:
+   - Canvas aspect / preset + suggested pixel size; likely `platforms`
+   - Likely **pageRoles** (1–2), contentFamily / archetypes, density, visualStyle
+   - Layout regions (title, metric, image well, footer, …)
+   - **Variable vs fixed**: only variable regions become slots
+   - Theme candidates (canvas/text/accent/muted, font feel)
+4. Reverse-engineer a short shared philosophy (`workflows/DESIGN_PHILOSOPHY.md`) from the reference — movement name + space/color/rhythm/composition/type/craftBar. Write it into `design-plan.json` `philosophy`.
+5. Treat the reconstruction direction as the selected concept (one concept is enough), with `philosophyExpression` describing how the rebuilt zones express that philosophy. Then follow `workflows/ASSET_PLAN.md` and `workflows/SURFACE_REVIEW.md` when the rebuild needs wash, slot photography, or icons:
+   - Reuse the supplied bitmap only when it is meant to remain a background/hero asset
+   - Rebuild editable typography, data, and simple decoration with nodes/CSS/SVG
+   - Never flatten replaceable text or data into a generated image
+   - Never keep third-party temporary image URLs in Authoring Source
+   - Write and validate `design-plan.json`; `image_reference` may contain one concept
+   - When co-creating Theme, run `THEME_FROM_BRAND.md` (sample colors from reference → `brandHex`) and validate `theme-tokens.json`
+6. Build **P0 selection metadata** (`references/CATALOG_METADATA.md`) — infer, then confirm with the user.
+7. Build an explicit **slot table** (`references/SLOTS.md`):
+   - Types: `text` | `number` | `image` only
+   - Keys may be `text_0`, `image_0`, …
+   - Every `text` slot includes `maxLines` (+ `maxCharacters` when known)
+   - No `list` type — repeated lines → `text_1`…`text_n` + `fixedItemCount` when checklist/steps
+8. Map regions to **flat absolutely positioned** canvas siblings (no absolute-inside-absolute groups; card chrome = decoration sibling). Set `bindingKey` on fillable nodes only. Put exact geometry and critical typography in inline `style={{...}}`; do not use Tailwind arbitrary-value layout classes. Fill `slotSummary` / `requiresImage` / `imageRoles`.
+9. Propose Theme reuse or `ThemeTokens` create from `theme-tokens.json` (`references/THEME_TOKENS.md`).
+10. Show the user: selection metadata, slots, Theme, and honesty about approximation limits. Proceed when they accept.
+11. Run `scripts/validate-authoring-source.mjs <authoring-source.json>` and fix every error.
+12. Continue with `workflows/AUTHORING_STUDIO.md` (`source.kind = image_reference`, brief = path or short note); run Visual QA before handoff.
+
+## Limits (state upfront when relevant)
+
+- Complex photography collages, heavy effects, or handwritten type → structure + Theme approximation; Studio required.
+- Absolute layout: do not promise empty lines will pack upward.
+- Never Publish from Agent until the user has Saved in Studio and explicitly asked to publish (`PUBLISH_FROM_DRAFT.md`).
+
+## Do not
+
+- Treat the reference bitmap as the template (must become slotted authoring source)
+- Skip reverse-engineered philosophy / `philosophyExpression`
+- Copy private Binding/AST formats into Gateway requests
+- Use runtime Tailwind arbitrary-value classes for critical geometry or typography
+- Nest absolute frames inside wrapper cards/groups (flatten to canvas siblings instead)
+- Start Content Skill / render a slideshow from this path

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

@@ -0,0 +1,122 @@
+# Authoring Studio (create → edit → Save → Agent publish)
+
+Primary interactive path for **single-page** template drafts. Create the draft, run screenshot-based Visual QA, then hand off the reviewed draft. Do **not** create a Hosted Preview Job merely to show the user a URL.
+
+Studio has **Save only** (no Publish button). Publishing is an Agent step after the user saves and asks to publish — see `PUBLISH_FROM_DRAFT.md`.
+
+## Preconditions
+
+Complete intake first:
+
+- `AUTHORING_FROM_BRIEF.md` or `AUTHORING_FROM_IMAGE.md`
+- Selected concept + Asset Plan in a valid `design-plan.json`
+- Slot table + `authoringSource` + Theme decision ready
+- `authoringSource` passes `scripts/validate-authoring-source.mjs`
+- Optional draft-stage `selectionMetadata` (P0 can be completed at publish time)
+- References: `SLOTS.md`, `AUTHORING_SOURCE.md`, `THEME_TOKENS.md`, `CATALOG_METADATA.md`
+
+## Flow
+
+1. Run the required local preflights (resolve scripts relative to this Skill directory):
+
+```bash
+node scripts/validate-design-v2.mjs ./design-plan.json
+node scripts/validate-authoring-source.mjs ./authoring-source.json
+```
+
+Do not create or update a draft when this command fails.
+
+2. Create the remote draft:
+
+```bash
+easysociable templates create-draft --file ./draft.json --json
+```
+
+The JSON file contains the public `name`, `source`, `authoringSource`, optional
+`selectionMetadata`, and optional `theme`/`themeId` fields. Do not pass private
+AST or Binding Maps.
+
+3. Read `data.id` / `data.templateId` / `data.themeId` / `data.authoringStudioUrl`.
+
+4. **Before handoff, run `workflows/VISUAL_QA.md`.** Open the actual Studio render with available browser control and inspect the screenshot, not only source code. When the draft fails, fix `authoring-source.json`, validate it, update the same draft, and re-render:
+
+```bash
+node scripts/validate-authoring-source.mjs ./authoring-source.json
+easysociable templates update --id <id> --file ./draft-patch.json --json
+```
+
+Stop after two automatic revisions unless the user explicitly requests more. Validate the passing QA artifact:
+
+```bash
+node scripts/validate-design-v2.mjs ./visual-qa.json
+```
+
+5. **Required user handoff message** (paste only after QA — customize the URL):
+
+```text
+已创建草稿，请打开 Authoring Studio 预览/编辑：
+{authoringStudioUrl}
+
+可直接在页面上改布局、文案占位和 Theme。满意后点 Save（页面上没有 Publish）。
+保存完成后回复我「publish」或「发布该模板」，我会分析画布、补齐选型元数据并发布到 Catalog。
+```
+
+English equivalent when the session is EN:
+
+```text
+Draft created. Open Authoring Studio to preview/edit:
+{authoringStudioUrl}
+
+Edit layout, placeholders, and Theme directly on the page. When satisfied, click Save (there is no Publish button).
+Then reply “publish” and I will analyze the draft, complete catalog metadata, and publish to the Catalog.
+```
+
+6. User previews/edits in the **slim** Authoring Studio:
+   - Canvas + right property panel
+   - Left: Theme tokens + optional Catalog hints
+   - Top bar: **Save** and **Fork** only. Final PNG rendering is delegated to the unified CLI/MCP after the user confirms the saved draft.
+   - **No** Publish button; **No** left SidebarMenu (no AI / select-template / typeset rail)
+
+7. When the user says publish → run `workflows/PUBLISH_FROM_DRAFT.md`.
+
+## SDK shape
+
+```ts
+const draft = await client.createDraft({
+  name: 'Dark CTA Poster',
+  source: { kind: 'text_brief', brief: '1080x1350 KPI milestone card' },
+  authoringSource: {
+    canvas: { width: 1080, height: 1350 },
+    json: { /* Studio projection; fillable nodes carry bindingKey e.g. text_0 */ },
+  },
+  theme: {
+    create: {
+      name: 'Dark CTA',
+      tokens: {
+        colors: { canvas: '#0f1419', text: '#e8eef5', accent: '#5b8cff', muted: '#8b9bb0' },
+        fonts: { heading: 'Inter', body: 'Inter' },
+        surfaces: { radius: '12px', shadow: '0 8px 24px rgba(0,0,0,.35)' },
+      },
+    },
+  },
+})
+// Always send the handoff message with draft.authoringStudioUrl
+```
+
+## Rules
+
+- Agent vision/LLM understanding stays local; Gateway stores/compiles `authoringSource` and Theme.
+- Single-page only — never create Carousel packs via this skill.
+- Phase 1: new templates consume Theme via `--es-*` variables.
+- Exact geometry and critical typography use inline styles; runtime arbitrary-value Tailwind classes are forbidden.
+- CLI/MCP must not start Local Runtime or import `template-renderer-react`.
+- There is no separate `easysociable-template preview` command in V1; Authoring
+  Studio is the visual QA surface.
+- Never claim Visual QA passed without inspectable screenshot evidence. If no visual surface is available, disclose that QA was skipped and ask the user to review in Studio.
+- Do not hand off a draft with hard visual failures or a score below 80/100 unless the user explicitly accepts it.
+- The only V1 authoring surface is `/authoring/{draftId}`; the retired full
+  product editor and Carousel routes are not public entry points.
+- Do not instruct the user to Publish in Studio — instruct **Save**, then Agent publish.
+- Remind user: empty optional slots omit nodes at render; absolute layout does not reflow.
+- Flat canvas tree: no absolute-inside-absolute wrappers (validator enforces); visual cards = decoration sibling + content siblings.
+- **Icons:** when adding/changing arrows, chevrons, checks, or any glyph, follow `SURFACE_REVIEW.md` § Icons (`search_icons` → confirm → `get_icon`). Do not hand-draw icon paths while the Icon Catalog works. Fillable text uses **`data-variable`**, not inventing bindings only in private AST.

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

@@ -0,0 +1,92 @@
+# Design brief (required when there is no reference image)
+
+When the user gives **only a text description** (no template/reference image), do **not** jump straight to nodes/slots.
+
+Act as a **professional editorial / social-card strategist**. First produce an intent-and-constraint **Design Brief**. Do not treat this brief as the final visual solution: continue to `DESIGN_PHILOSOPHY.md`, then `DESIGN_CONCEPTS.md`, before materializing nodes.
+
+Skip this workflow when `AUTHORING_FROM_IMAGE.md` applies and a reference image is the primary input (optional short brief still OK).
+
+## When to run
+
+- `source.kind = text_brief`
+- User has no uploaded layout reference
+- Or user says “按描述做一页模板 / 帮我设计”
+
+## Process
+
+### 1. Gather intent (batch questions; skip known answers)
+
+- Platforms (multi-select) + canvas from `references/PLATFORM_SPECS.md`
+- Page roles (1–2) + contentFamily / archetypes / density (`CATALOG_METADATA.md`)
+- Content job: what must the viewer understand in one glance?
+- Must-have slots: title / metric / image / CTA / fixed N checklist lines…
+- Theme: reuse `themeId` or co-create direction (swiss / editorial / bold_promo / minimal / dark). If co-creating, note brand hex or archetype for `DESIGN_INTELLIGENCE.md` palette seeding.
+
+### 2. Write the Design Brief
+
+Use this structure (Chinese or English to match the user):
+
+```markdown
+# Design Brief — <template name>
+
+## 1. Job to be done
+- One-sentence purpose of this page
+- Primary platform(s) + canvas (preset + pixels) — cite PLATFORM_SPECS recommended row
+
+## 2. Visual constraints
+- Desired/forbidden moods or brand rules
+- Existing Theme/brand assets to reuse
+- Accessibility or locale constraints
+
+## 3. Information hierarchy
+- One primary focal message
+- Secondary evidence and author/brand attribution
+- Content priority when space is constrained
+- **Flat frames only:** describe regions as independent absolute boxes on the canvas. If a “card” appears, it is a background panel **plus** separate content boxes — not one parent wrapping children.
+
+## 4. Slot plan
+- Table: key | type | required | maxLines/maxCharacters | purpose
+- fixedItemCount if checklist/steps
+- Optional regions that omit-when-empty (independent blocks only)
+
+## 5. Catalog metadata draft
+- platforms, canvasPreset, supportedRoles, contentFamily, archetypes, density, requiresImage…
+
+## 6. Risks / open questions
+- e.g. need user photo? checklist line count? LinkedIn PDF vs single image?
+```
+
+Design rules to enforce in the brief:
+
+- One primary focal idea per page  
+- Strong type hierarchy; avoid SaaS-card clutter  
+- Theme owns color/font; page owns structure  
+- Match **Recommended** canvas for the primary platform  
+- Absolute layout: do not promise packing empty checklist lines  
+- No nested absolute groups (avatar/name inside a card wrapper); text-only inline nesting is fine  
+
+### 3. Confirm intent when needed
+
+Ask once:
+
+> 先确认内容目标和约束；OK 后我会先定视觉哲学，再给 2–3 个版式方向，最后生成可编辑模板。
+
+Incorporate edits. If the user already said “直接做” or supplied enough constraints, continue without another blocking question.
+
+### 4. Continue to art direction
+
+Do not create nodes yet. Continue in this order:
+
+1. `DESIGN_PHILOSOPHY.md` — name the movement and lock shared visual philosophy
+2. `DESIGN_CONCEPTS.md` — 2–3 spatial expressions of that philosophy; select one
+3. `ASSET_PLAN.md` — decide reuse / CSS-SVG / generated assets
+4. `PALETTE_REVIEW.md` + `THEME_FROM_BRAND.md` — lock `theme-tokens.json` when co-creating Theme
+5. Validate `design-plan.json` and `theme-tokens.json`
+6. `AUTHORING_FROM_BRIEF.md`
+
+## Anti-patterns
+
+- Generating HTML/nodes before philosophy and concept selection when there is no reference image
+- Vague briefs (“好看一点”) without zones, hierarchy, or slot plan
+- Ignoring PLATFORM_SPECS recommended sizes
+- Treating one generic “minimal/professional” paragraph as a design concept or philosophy