@easysociable/cli 0.1.1 → 0.1.2

package/skills/easysociable-content/references/PAGE_PACK.md

@@ -1,6 +1,129 @@
-# PagePack handoff
+# PagePack handoff (`content-pack.v1`)
 
-`content-pack.v1` is the boundary between semantic content and visual
-composition. It contains platform, optional title, and ordered pages with a
-semantic `role` and public `slots`. The Slideshow Skill performs template
-selection and rendering; Content does not call Template APIs.
+The Pack is the boundary between semantic content (Content Skill) and visual
+composition (Template / Slideshow Skills). Content writes slots and roles;
+downstream skills choose Page Templates and render.
+
+**Source of truth for caps and roles:** `packages/template-public-contracts`
+(`contentPackSchema`). This file is the Agent-facing summary.
+
+## Schema
+
+```json
+{
+  "schemaVersion": "content-pack.v1",
+  "platform": "tiktok",
+  "title": "Optional title",
+  "pages": [
+    {
+      "role": "hook",
+      "slots": { "text_0": "Hook line", "text_1": "Support" },
+      "pageTemplateId": "tpl_selected_at_handoff"
+    }
+  ]
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `schemaVersion` | yes | Must be `content-pack.v1` |
+| `platform` | yes | See platform table below |
+| `title` | no | Display title for Studio |
+| `pages` | yes | Ordered array, length within platform caps |
+| `pages[].role` | yes | Closed `pageRoles` enum |
+| `pages[].slots` | yes | Public slot key → string/number/boolean/null |
+| `pages[].pageTemplateId` | yes | Published Page Template selected by Slideshow before `create` |
+
+## Forbidden in Pack
+
+Never include:
+
+- `deck_template_id` / Deck references
+- Template AST, Binding Maps, RenderPlans
+- `ContentDocument` / `contentDocumentHash`
+- Private gateway credentials or image URLs as slot values (use `imageId` after import)
+
+## Platform page caps
+
+| Platform | Min pages | Max pages | V1 Slideshow |
+|---|---:|---:|---|
+| `tiktok` | 4 | 35 | yes |
+| `instagram` | 2 | 20 | yes |
+| `linkedin` | 2 | 300 | yes |
+| `threads` | 2 | 20 | yes |
+| `xiaohongshu` | — | — | not a Content Pack route in V1; use Template single-page |
+
+`x` is not a Pack platform. Use Template fill-slots for single-page X graphics.
+
+## Page roles (closed set)
+
+`cover`, `hook`, `setup`, `context`, `value`, `point`, `checklist`, `proof`,
+`evidence`, `compare`, `screenshot`, `metric`, `quote`, `steps`, `cta`, `follow`, `recap`
+
+Pick roles that match the narrative arc. Slideshow maps each page to a published
+Page Template with compatible `supportedRoles`.
+
+## File naming
+
+During the run, write vault-native pack markdown:
+
+```text
+pack.md
+pack-<platform>.md
+```
+
+`content-pack.v1` JSON is created **at Slideshow/Template handoff**, not during draft:
+
+```text
+pack-<platform>.json
+```
+
+Example: `pack-tiktok.json`. Pure X text has no pack.
+
+## Validation
+
+```bash
+node scripts/validate-pack.mjs --file ./pack-tiktok.json --platform tiktok --json
+```
+
+Before Slideshow `create`, also run:
+
+```bash
+node scripts/validate-pack.mjs --file ./pack-tiktok.json --require-page-template-id --json
+```
+
+## Examples
+
+### English — TikTok (4 pages, content stage)
+
+```json
+{
+  "schemaVersion": "content-pack.v1",
+  "platform": "tiktok",
+  "title": "Morning routine tips",
+  "pages": [
+    { "role": "hook", "pageTemplateId": "tpl_hook_001", "slots": { "text_0": "Stop scrolling — this changed my mornings" } },
+    { "role": "value", "pageTemplateId": "tpl_value_001", "slots": { "text_0": "Wake at the same time", "text_1": "No phone for 20 minutes" } },
+    { "role": "value", "pageTemplateId": "tpl_value_001", "slots": { "text_0": "Move before caffeine", "text_1": "Even 5 minutes counts" } },
+    { "role": "cta", "pageTemplateId": "tpl_cta_001", "slots": { "text_0": "Save this for tomorrow" } }
+  ]
+}
+```
+
+### 中文 — TikTok（4 页，内容阶段）
+
+```json
+{
+  "schemaVersion": "content-pack.v1",
+  "platform": "tiktok",
+  "title": "晨间习惯三条",
+  "pages": [
+    { "role": "hook", "pageTemplateId": "tpl_hook_001", "slots": { "text_0": "别再瞎忙了——我靠这三条稳住早晨" } },
+    { "role": "value", "pageTemplateId": "tpl_value_001", "slots": { "text_0": "固定起床时间", "text_1": "醒来先别碰手机" } },
+    { "role": "value", "pageTemplateId": "tpl_value_001", "slots": { "text_0": "喝咖啡前先动一动", "text_1": "五分钟也算数" } },
+    { "role": "cta", "pageTemplateId": "tpl_cta_001", "slots": { "text_0": "先收藏，明早试" } }
+  ]
+}
+```
+
+JSON field names and `role` values stay English even when slot copy is 中文.

package/skills/easysociable-content/references/PLATFORM_GUIDE.md

@@ -0,0 +1,36 @@
+# Platform guide
+
+Use this matrix before opening a run. **Ask** if the user did not name a platform. Multi-select → **N runs**.
+
+| Platform | Slideshow (V1) | Pack platform key | Page cap (slideshow) | Default path |
+|---|---|---|---:|---|
+| TikTok | yes | `tiktok` | 4–35 | Slideshow |
+| Instagram | yes | `instagram` (`ig`) | 2–20 | Slideshow |
+| LinkedIn | yes | `linkedin` | 2–300 | Slideshow |
+| Threads | yes | `threads` | 2–20 | Slideshow |
+| X | **no** | — (no Pack) | — | Template single-page or text-only |
+| Xiaohongshu | **no** (V1) | — | — | Template single-page |
+
+Craft notes live under `Content Engine/platforms/`. Map: `instagram` → `ig.md`. Read the file before brief/draft/editor.
+
+## Routing
+
+```text
+1 page                          → easysociable-template
+2+ pages + slideshow platform   → easysociable-slideshow
+x                               → easysociable-template only (if images)
+xiaohongshu                     → easysociable-template until slideshow ships
+```
+
+## Canvas hints (for downstream skills)
+
+| Platform | Typical canvas | Notes |
+|---|---|---|
+| tiktok | 9:16 @ 1080×1920 | Photo Mode carousel |
+| instagram / ig | 4:5 or 1:1 @ 1080 | Feed carousel |
+| linkedin | 4:5 or 1:1 | Document-style decks |
+| threads | 4:5 or 1:1 | Conversational copy |
+| x | 16:9 or 1:1 | Single image post |
+| xiaohongshu | 3:4 @ 1080×1440 | See Template `PLATFORM_SPECS` |
+
+Content Skill does not pick Page Templates — only platform, roles and slot copy. Pack JSON is written at Slideshow/Template handoff, not during draft.

package/skills/easysociable-content/references/RUN_LAYOUT.md

@@ -0,0 +1,73 @@
+# Run layout
+
+Copy `runs/_template/` to `runs/<YYYY-MM-DD-short-slug[-platform]>/`.
+
+**One folder = one platform.** Same Topic on another network = another folder sharing `topic_id`.
+
+```text
+Content Engine/runs/<slug>/
+```
+
+## Core files
+
+| File | Purpose |
+|---|---|
+| `idea.md` | Run id, status, **this** platform, selection (`swipe_id` / `atoms` / `claim_id`) |
+| `brief.md` | Angle, constraints, selection why |
+| `packet.md` | Writer context (pillar + voice + audience + craft notes) |
+| `draft.md` | Copy for **this platform only** |
+| `editor.md` | REVISE / APPROVE |
+| `rubric.md` | 6 × 0–2; SHIP ≥ 8 |
+| `pack.md` | Image deck slots after SHIP (slideshow platforms) |
+| `feedback.md` | URL + `win`/`flat`/`loss` after publish |
+| `pack-<platform>.json` | Complete `content-pack.v1` — **only at render handoff** |
+
+## `idea.md` frontmatter
+
+```yaml
+---
+run_id: RUN-YYYYMMDD-slug
+status: RUN_OPEN
+created: YYYY-MM-DD
+---
+```
+
+Body must include `primary_platform` equal to `platforms` (single value) and the three selection fields. `none` is allowed with why.
+
+### File status vs index status
+
+| `idea.md` | `runs/_index.md` |
+|---|---|
+| `RUN_OPEN` | `open` |
+| `BRIEF_WAIT` | `brief` |
+| `DRAFTED` / `EDIT_WAIT` | `draft` |
+| `SCORED` | `scored` |
+| `READY_TO_POST` | `ready` |
+| `PUBLISHED` | `published` |
+| `HOLD` / `KILLED` / `SUPERSEDED` | `hold` / `killed` / `superseded` |
+
+Do not use index status `partial` for new runs.
+
+## Validation
+
+Semantic run (no Pack JSON yet):
+
+```bash
+node scripts/validate-run.mjs --run <run-dir> --json
+```
+
+Slideshow handoff (Pack JSON required):
+
+```bash
+node scripts/validate-run.mjs --run <run-dir> --require-pack --json
+node scripts/validate-pack.mjs --file <run-dir>/pack-<platform>.json --platform <platform> --json
+```
+
+## Export path
+
+Final PNGs at the **engine root**, not inside the run folder:
+
+```text
+Content Engine/exports/<run-slug>/01.png
+Content Engine/exports/<run-slug>/<platform>/01.png   # optional subfolder
+```

package/skills/easysociable-content/references/TROUBLESHOOTING.md

@@ -1,11 +1,13 @@
 # Troubleshooting
 
-The V1 Content Skill has no Content CLI, Local API, SQLite runtime or runtime
-token. If setup fails, stop before writing files, show the Obsidian install and
-Vault-selection guidance, and ask the user to retry after the prerequisite is
-ready. Never invent `--data-dir`, `init`, `doctor` or runtime credentials.
-
-If a local Run is incomplete, keep the existing Markdown/JSON intact and report
-the missing file or field. Do not auto-migrate or repair an existing Content
-Engine folder. Publication, metrics, retrospectives and experiments are
-deferred in V1; keep those notes as ordinary Markdown only.
+No Content CLI, Local API, SQLite, or Obsidian requirement.
+
+If setup fails, stop before overwriting files. `python3` missing → install Python 3; starter files may already be written.
+
+If port 8765 is in use, reuse `http://127.0.0.1:8765/workbench/` — do not start a second server. Rebuild with `python3 workbench/build.py`.
+
+Never overwrite an existing `workbench/template.html`. `--apply` only adds missing files.
+
+If a run is incomplete, keep existing markdown and report the missing file. `validate-run.mjs` / `validate-pack.mjs` list concrete gaps. Do not auto-migrate an existing engine.
+
+Deferred features: `workflows/OUT_OF_SCOPE.md`.

package/skills/easysociable-content/references/VAULT.md

@@ -1,20 +1,40 @@
-# Vault layout
+# Engine layout
 
-Setup asks the user to choose a locale, then creates one engine root:
+The skill creates one English root:
 
-| Locale | Root | Runs | Exports |
-|---|---|---|---|
-| `en` | `Content Engine/` | `runs/<slug>/` | `exports/<slug>/<platform>/` |
-| `zh` | `内容引擎/` | `成稿/<slug>/` | `导出/<slug>/<platform>/` |
+```text
+<parent>/Content Engine/
+```
 
-Read `locale.json` in that root after setup:
+`--root` is the **parent** directory, or the `Content Engine/` path itself.
 
 ```json
-{ "locale": "zh" }
+{
+  "schemaVersion": "content-engine.v1",
+  "locale": "en",
+  "root": "Content Engine",
+  "paths": { "runs": "runs", "exports": "exports", "workbench": "workbench" }
+}
+```
+
+Folders: `accounts`, `inbox`, `swipe`, `topics`, `discovery`, `raw`, `profiles`, `published`, `wiki`, `platforms`, `runs`, `exports`, `workbench`.
+
+Platform craft files: `x.md`, `ig.md` (`instagram` → `ig.md`), `tiktok.md`, `linkedin.md`, `threads.md`, `xiaohongshu.md`.
+
+## Workbench
+
+Copied from the skill package **only when missing**. Never overwrite an existing `workbench/template.html`.
+
+```text
+http://127.0.0.1:8765/workbench/
 ```
 
-English folders stay English (`accounts`, `inbox`, `swipe`, `topics`, …).
-Chinese folders are `账号`, `收件箱`, `拆解`, `选题`, `素材`, `档案`, `已发布`,
-`百科`, `平台`. Platform note filenames stay `x.md`, `threads.md`, `tiktok.md`.
+Rebuild with `python3 workbench/build.py` after markdown writes.
+
+## Export path
+
+```text
+Content Engine/exports/<run-slug>/01.png
+```
 
-Never create both roots in one Vault. Pack JSON keys stay English.
+Exports are **not** nested under `runs/<slug>/`. See `references/RUN_LAYOUT.md`.

package/skills/easysociable-content/references/VOICE.md

@@ -0,0 +1,16 @@
+# Local voice vs hosted Profile
+
+| Concept | Where | When | Purpose |
+|---|---|---|---|
+| **Local voice** | `profiles/<id>/voice.md` | First draft (optional) | Identity + tone for the Agent |
+| **Local profile** | `profiles/<id>/` | Multi-brand | Pillars + audience + voice |
+| **Hosted Brand Profile** | Gateway (`easysociable profiles …`) | First render | Visual identity: Theme, logo, quotas |
+
+## Rules
+
+1. **Setup does not create a hosted Profile.**
+2. **Local voice is optional.** Ask once; user may skip.
+3. **Hosted Profile is required for render**, owned by Template/Slideshow skills.
+4. Never store API keys, passwords or Stripe tokens in `profiles/` or `accounts/`.
+
+When writing `draft.md` or pack slots, read the resolved voice file and audience **core + this platform**.

package/skills/easysociable-content/scripts/contracts.mjs

@@ -0,0 +1,183 @@
+/** ponytail: mirrors @easysociable/template-public-contracts — upgrade by diffing that package */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, basename } from 'node:path'
+
+export const PAGE_ROLES = [
+  'cover', 'hook', 'setup', 'context', 'value', 'point', 'checklist', 'proof',
+  'evidence', 'compare', 'screenshot', 'metric', 'quote', 'steps', 'cta', 'follow', 'recap',
+]
+
+export const PACK_PLATFORMS = ['tiktok', 'xiaohongshu', 'instagram', 'linkedin', 'threads']
+
+export const SLIDESHOW_PLATFORMS = ['tiktok', 'instagram', 'linkedin', 'threads']
+
+export const PLATFORM_CAPS = {
+  tiktok: { hardMin: 4, hardMax: 35 },
+  xiaohongshu: { hardMin: 2, hardMax: 18 },
+  instagram: { hardMin: 2, hardMax: 20 },
+  linkedin: { hardMin: 2, hardMax: 300 },
+  threads: { hardMin: 2, hardMax: 20 },
+}
+
+const FORBIDDEN_PACK_KEYS = ['deck_template_id', 'deckTemplateId']
+
+const PACK_KEYS = new Set(['schemaVersion', 'platform', 'title', 'pages'])
+const PAGE_KEYS = new Set(['pageTemplateId', 'role', 'slots'])
+export const RUN_FILE_STATUSES = [
+  'RUN_OPEN', 'BRIEF_WAIT', 'DRAFTED', 'EDIT_WAIT', 'SCORED',
+  'READY_TO_POST', 'PUBLISHED', 'HOLD', 'KILLED', 'SUPERSEDED',
+]
+export const RUN_INDEX_STATUSES = [
+  'open', 'brief', 'draft', 'scored', 'ready', 'published', 'hold', 'killed', 'superseded', 'partial',
+]
+const RUN_STATUSES = [
+  ...RUN_FILE_STATUSES,
+  ...RUN_INDEX_STATUSES,
+  'template-ready', 'pack-ready', 'handed-off', 'exported',
+]
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function pushForbidden(errors, value, path) {
+  const text = JSON.stringify(value).toLowerCase()
+  for (const key of FORBIDDEN_PACK_KEYS) {
+    if (text.includes(key.toLowerCase())) errors.push(`${path}: forbidden field ${key}`)
+  }
+}
+
+function pushUnknownKeys(errors, value, allowed, path) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) errors.push(`${path}: unknown field ${key}`)
+  }
+}
+
+function isPublicSlotValue(value) {
+  return value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+}
+
+export function validateContentPack(pack, options = {}) {
+  const { platform: expectedPlatform } = options
+  const errors = []
+  const warnings = []
+
+  if (!isRecord(pack)) {
+    errors.push('pack: must be a JSON object')
+    return { valid: false, errors, warnings }
+  }
+
+  pushForbidden(errors, pack, 'pack')
+  pushUnknownKeys(errors, pack, PACK_KEYS, 'pack')
+
+  if (pack.schemaVersion !== 'content-pack.v1') errors.push('schemaVersion: must be content-pack.v1')
+  if (!PACK_PLATFORMS.includes(pack.platform)) {
+    errors.push(`platform: must be one of ${PACK_PLATFORMS.join(', ')}`)
+  }
+  if (expectedPlatform && pack.platform !== expectedPlatform) {
+    errors.push(`platform: expected ${expectedPlatform}, got ${pack.platform}`)
+  }
+  if (pack.title !== undefined && typeof pack.title !== 'string') errors.push('title: must be a string')
+  if (!Array.isArray(pack.pages) || pack.pages.length === 0) {
+    errors.push('pages: must be a non-empty array')
+    return { valid: errors.length === 0, errors, warnings }
+  }
+
+  const cap = PLATFORM_CAPS[pack.platform]
+  if (cap && (pack.pages.length < cap.hardMin || pack.pages.length > cap.hardMax)) {
+    errors.push(`pages: ${pack.platform} requires ${cap.hardMin}-${cap.hardMax} pages, got ${pack.pages.length}`)
+  }
+
+  pack.pages.forEach((page, index) => {
+    const label = `pages[${index}]`
+    if (!isRecord(page)) {
+      errors.push(`${label}: must be an object`)
+      return
+    }
+    pushUnknownKeys(errors, page, PAGE_KEYS, label)
+    if (!PAGE_ROLES.includes(page.role)) errors.push(`${label}.role: invalid page role`)
+    if (typeof page.pageTemplateId !== 'string' || page.pageTemplateId.length === 0) {
+      errors.push(`${label}.pageTemplateId: required and must be a non-empty string`)
+    }
+    if (!isRecord(page.slots)) {
+      errors.push(`${label}.slots: must be an object`)
+    }
+    else {
+      for (const [key, value] of Object.entries(page.slots)) {
+        if (!isPublicSlotValue(value)) errors.push(`${label}.slots.${key}: must be string, number, boolean or null`)
+      }
+    }
+  })
+
+  if (!SLIDESHOW_PLATFORMS.includes(pack.platform)) {
+    warnings.push(`platform ${pack.platform}: not supported by easysociable-slideshow in V1`)
+  }
+
+  return { valid: errors.length === 0, errors, warnings }
+}
+
+export function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match) return {}
+  const fields = {}
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':')
+    if (idx === -1) continue
+    const key = line.slice(0, idx).trim()
+    const value = line.slice(idx + 1).trim().replace(/^['"]|['"]$/g, '')
+    if (key) fields[key] = value
+  }
+  return fields
+}
+
+export function ideaField(text, name) {
+  const match = text.match(new RegExp(`\\*\\*${name}:\\*\\*\\s*(.+)`, 'i'))
+  return match ? match[1].trim() : ''
+}
+
+export function validateRunLayout(runDir, options = {}) {
+  const { requirePack = false } = options
+  const errors = []
+  const warnings = []
+  const files = { ideaMd: false, draftMd: false, packMd: false, packs: [] }
+  const ideaPath = join(runDir, 'idea.md')
+
+  if (!existsSync(runDir) || !statSync(runDir).isDirectory()) {
+    errors.push('run: directory required')
+    return { valid: false, errors, warnings, files, frontmatter: {} }
+  }
+  if (!existsSync(ideaPath)) {
+    errors.push('idea.md: required')
+    return { valid: false, errors, warnings, files, frontmatter: {} }
+  }
+
+  files.ideaMd = true
+  const ideaText = readFileSync(ideaPath, 'utf8')
+  const frontmatter = parseFrontmatter(ideaText)
+  const platform = (frontmatter.platform || ideaField(ideaText, 'primary_platform') || ideaField(ideaText, 'platforms')).replace(/\s.*/, '')
+  frontmatter.platform = platform
+  frontmatter.slug = frontmatter.slug || basename(runDir)
+  if (!frontmatter.run_id) errors.push('idea.md frontmatter: missing run_id')
+  if (!frontmatter.status) errors.push('idea.md frontmatter: missing status')
+  if (frontmatter.status && !RUN_STATUSES.includes(frontmatter.status)) {
+    errors.push(`idea.md status: must be one of the engine run statuses`)
+  }
+  if (!platform) warnings.push('idea.md: primary_platform recommended')
+
+  files.draftMd = existsSync(join(runDir, 'draft.md'))
+  files.packMd = existsSync(join(runDir, 'pack.md')) || readdirSync(runDir).some((name) => /^pack-[a-z0-9_-]+\.md$/i.test(name))
+  if (!files.draftMd) warnings.push('draft.md: recommended')
+
+  files.packs = readdirSync(runDir).filter((name) => /^pack-[a-z0-9_-]+\.json$/i.test(name))
+  const slideshowRun = SLIDESHOW_PLATFORMS.includes(platform) || platform === 'ig'
+  const expectedPack = platform === 'ig' ? 'pack-instagram.json' : (platform ? `pack-${platform}.json` : 'pack-<platform>.json')
+  if (requirePack && files.packs.length === 0) {
+    errors.push(`${expectedPack}: required for slideshow handoff`)
+  }
+  if (!slideshowRun && files.packs.length > 0) {
+    errors.push('pack-<platform>.json: only slideshow platforms may contain a Content Pack')
+  }
+
+  return { valid: errors.length === 0, errors, warnings, files, frontmatter }
+}

package/skills/easysociable-content/scripts/export-contracts.mjs

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { createHash } from 'node:crypto'
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+export function validateExportDirectory(exportDir, options = {}) {
+  const expectedPages = options.expectedPages
+  const errors = []
+  const warnings = []
+  const files = { manifest: false, pngs: [] }
+
+  if (!existsSync(exportDir) || !statSync(exportDir).isDirectory()) {
+    return { valid: false, errors: ['export: directory required'], warnings, files }
+  }
+
+  const manifestPath = join(exportDir, 'manifest.json')
+  if (!existsSync(manifestPath)) {
+    errors.push('manifest.json: required')
+    return { valid: false, errors, warnings, files }
+  }
+  files.manifest = true
+
+  let manifest
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  }
+  catch (error) {
+    errors.push(`manifest.json: invalid JSON (${error instanceof Error ? error.message : String(error)})`)
+    return { valid: false, errors, warnings, files }
+  }
+  if (!isRecord(manifest)) errors.push('manifest.json: must contain an object')
+
+  const entries = Array.isArray(manifest?.pages)
+    ? manifest.pages
+    : Array.isArray(manifest?.artifacts) ? manifest.artifacts : []
+  if (entries.length === 0) errors.push('manifest.json: pages or artifacts must be a non-empty array')
+
+  files.pngs = readdirSync(exportDir).filter(name => /^\d{2}(?:-[^/]+)?\.png$/i.test(name) && statSync(join(exportDir, name)).isFile())
+  if (entries.length > 0 && files.pngs.length !== entries.length) {
+    errors.push(`export: manifest has ${entries.length} page(s), found ${files.pngs.length} PNG file(s)`)
+  }
+  if (Number.isInteger(expectedPages) && expectedPages > 0 && entries.length !== expectedPages) {
+    errors.push(`export: expected ${expectedPages} page(s), manifest has ${entries.length}`)
+  }
+
+  const pngByName = new Map(files.pngs.map(name => [name, name]))
+  entries.forEach((entry, index) => {
+    if (!isRecord(entry)) {
+      errors.push(`manifest[${index}]: must be an object`)
+      return
+    }
+    const file = typeof entry.file === 'string' && entry.file.length > 0
+      ? basename(entry.file)
+      : `${String(index + 1).padStart(2, '0')}.png`
+    if (file !== entry.file && entry.file !== undefined) errors.push(`manifest[${index}].file: must be a local basename`)
+    if (!pngByName.has(file)) {
+      errors.push(`manifest[${index}].file: missing ${file}`)
+      return
+    }
+    const bytes = readFileSync(join(exportDir, file))
+    if (bytes.length === 0) errors.push(`${file}: empty file`)
+    if (bytes.length < 8 || bytes.subarray(0, 8).toString('hex') !== '89504e470d0a1a0a') {
+      errors.push(`${file}: not a PNG file`)
+    }
+    if (entry.sha256 && entry.sha256 !== sha256(bytes)) errors.push(`${file}: sha256 mismatch`)
+  })
+
+  return { valid: errors.length === 0, errors, warnings, files, manifest }
+}

package/skills/easysociable-content/scripts/fixture.test.mjs

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const root = new URL('..', import.meta.url).pathname
+const goldenRun = join(root, 'fixtures/golden-run-en')
+const validateRun = join(root, 'scripts/validate-run.mjs')
+const validatePack = join(root, 'scripts/validate-pack.mjs')
+
+const packFile = join(goldenRun, 'pack-tiktok.json')
+const packCli = spawnSync(process.execPath, [validatePack, '--file', packFile, '--platform', 'tiktok', '--json'], { encoding: 'utf8' })
+assert.equal(packCli.status, 0, packCli.stdout + packCli.stderr)
+
+const runCli = spawnSync(process.execPath, [validateRun, '--run', goldenRun, '--require-pack', '--json'], { encoding: 'utf8' })
+assert.equal(runCli.status, 0, runCli.stdout + runCli.stderr)
+const runReport = JSON.parse(runCli.stdout)
+assert.equal(runReport.valid, true)
+assert.equal(runReport.layout.frontmatter.status, 'pack-ready')
+
+const pack = JSON.parse(readFileSync(packFile, 'utf8'))
+assert.equal(pack.pages.length, 4)
+
+console.log('Golden fixture validation passed.')

package/skills/easysociable-content/scripts/package-skill.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync, rmSync } from 'node:fs'
+import { join, relative, resolve, sep } from 'node:path'
+
+const skillRoot = resolve(new URL('..', import.meta.url).pathname)
+const include = ['SKILL.md', 'INSTALL.md', 'scripts', 'references', 'workflows', 'platforms', 'fixtures', 'starter', 'workbench']
+
+function parseArgs(argv) {
+  let output = ''
+  let force = false
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--output') output = argv[++i] ?? ''
+    else if (argv[i] === '--force') force = true
+    else if (argv[i] === '--help' || argv[i] === '-h') return { help: true }
+    else throw new Error(`Unknown argument: ${argv[i]}`)
+  }
+  return { output, force }
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2))
+  if (options.help) {
+    process.stdout.write('Usage: node package-skill.mjs --output <destination-dir> [--force]\n')
+    process.exit(0)
+  }
+  if (!options.output) throw new Error('--output is required')
+
+  const dest = resolve(options.output)
+  const sourceToDest = relative(skillRoot, dest)
+  const destToSource = relative(dest, skillRoot)
+  const touchesSource = dest === skillRoot
+    || (!sourceToDest.startsWith(`..${sep}`) && sourceToDest !== '..')
+    || (!destToSource.startsWith(`..${sep}`) && destToSource !== '..')
+  if (touchesSource) throw new Error('--output must be outside the skill source directory')
+  if (existsSync(dest) && !options.force) throw new Error('Output already exists; pass --force to replace it')
+  if (existsSync(dest)) rmSync(dest, { recursive: true, force: true })
+  mkdirSync(dest, { recursive: true })
+
+  for (const name of include) {
+    cpSync(join(skillRoot, name), join(dest, name), { recursive: true })
+  }
+
+  process.stdout.write(`Packaged skill → ${dest}\n`)
+}
+catch (error) {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+}