@easysociable/cli 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easysociable/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agent-first CLI and MCP host for EasySociable Template and Slideshow V1",
   "type": "module",
   "license": "MIT",
@@ -36,23 +36,28 @@
     "LICENSE",
     "README.md"
   ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsup",
+    "prepack": "node scripts/prepack.mjs && pnpm build",
+    "pack:check": "npm pack --dry-run"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "dependencies": {
+    "commander": "^11.1.0"
+  },
   "devDependencies": {
+    "@easysociable/mcp-server": "workspace:*",
+    "@easysociable/template-gateway-client": "workspace:*",
+    "@easysociable/tsconfig": "workspace:*",
+    "@easysociable/vitest-config": "workspace:*",
     "@types/node": "^22.14.0",
-    "commander": "^11.1.0",
     "tsup": "^8.0.2",
     "typescript": "^5.8.3",
-    "vitest": "^1.3.1",
-    "@easysociable/tsconfig": "0.0.0",
-    "@easysociable/vitest-config": "0.0.0"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "build": "tsup",
-    "pack:check": "npm pack --dry-run"
+    "vitest": "^1.3.1"
   }
-}
+}

package/skills/ONBOARDING.md

@@ -27,7 +27,9 @@ easysociable install --skills content --yes
 ```
 
 Then run the `easysociable-content` setup workflow (Obsidian Vault + Content
-Engine). Skipping Content does **not** block single-page or Slideshow renders.
+Engine). For a private copy to another machine, see
+`skills/easysociable-content/INSTALL.md`. Skipping Content does **not** block
+single-page or Slideshow renders.
 
 ## Lazy auth (Agent script)
 

package/skills/easysociable-content/INSTALL.md

@@ -0,0 +1,60 @@
+# Install easysociable-content (private copy)
+
+Ship this folder — **not** the whole monorepo.
+
+## What to copy
+
+```text
+easysociable-content/
+├── SKILL.md
+├── INSTALL.md
+├── scripts/
+├── starter/
+├── workbench/
+├── references/
+├── workflows/
+├── platforms/
+└── fixtures/          # optional
+```
+
+Do **not** include API keys, `.env`, or the user's Content Engine.
+
+## Where to install
+
+| Agent host | Path |
+|---|---|
+| Cursor | `~/.cursor/skills/easysociable-content/` |
+| Claude Code | `~/.claude/skills/easysociable-content/` |
+| Codex | host-specific skills directory (see `platforms/codex.md`) |
+
+```bash
+cp -R easysociable-content ~/.cursor/skills/easysociable-content
+```
+
+Restart the Agent session so the skill is picked up.
+
+## Prerequisites
+
+1. **python3** (workbench `build.py` / `serve.py`)
+2. A parent directory for `Content Engine/` (any folder; Obsidian is not required)
+3. For rendering: unified `easysociable` CLI + Template/Slideshow skills (optional until first render)
+
+## First run (Agent)
+
+1. Ask for a parent directory (or an existing `Content Engine/` path). Do not ask language.
+2. Apply and start workbench:
+
+   ```bash
+   node scripts/setup.mjs --root "<parent>" --preview --json
+   node scripts/setup.mjs --root "<parent>" --apply --json
+   ```
+
+3. Follow `workflows/GETTING_STARTED.md`. Daily operations follow engine `CLAUDE.md`.
+
+Existing files are never overwritten. Later skill updates: `--apply` adds **missing** starter files only; skip existing `workbench/template.html`.
+
+## Package script (maintainers)
+
+```bash
+node skills/easysociable-content/scripts/package-skill.mjs --output /tmp/easysociable-content-skill
+```

package/skills/easysociable-content/SKILL.md

@@ -1,115 +1,126 @@
 ---
 name: easysociable-content
 description: >
-  Set up and operate a local Obsidian-based Content Engine for EasySociable.
-  Obsidian is required. During setup, ask the user to choose 中文 or English;
-  that locale names the engine folders and starter notes. This Skill records
-  Runs, Packs and exports for the Template and Slideshow Skills. It does not
-  provide a hosted content backend, Content API, SQLite runtime, content MCP
-  server or content CLI.
+  Set up and operate a local Content Engine for EasySociable. English folder
+  tree only (Content Engine/). One platform = one Run. The Agent writes
+  markdown; workbench is the observatory UI. Hosted Template/Slideshow work
+  uses the unified easysociable CLI/MCP. No Obsidian requirement, no content
+  MCP, no content CLI.
 ---
 
 # EasySociable Content Skill
 
-This Skill owns the user's local knowledge base. It is intentionally filesystem-
-first: the Agent writes Markdown and JSON under the user's existing Obsidian
-Vault, while hosted Template and Slideshow operations are performed later by
-the unified `easysociable` CLI/MCP.
+This Skill owns the user's local knowledge base. The Agent writes Markdown
+under `Content Engine/`. After writes, rebuild the workbench. Hosted Template
+and Slideshow operations stay with the unified `easysociable` CLI/MCP.
+
+**Operating manual lives in the engine:** `Content Engine/CLAUDE.md`. Follow it
+for capture, discovery, topics, 开一单, ingest, ship, and catalog evidence. This
+file is setup, routing, and hosted handoff only.
 
 ## Non-negotiable rules
 
-1. Obsidian must already be installed. If it is missing, stop and give the
-   official installation guidance; do not create a partial vault.
-2. Ask the user to choose **中文 (`zh`)** or **English (`en`)** before the first
-   preview. Do not default the locale silently.
-3. Ask the user to choose an existing Vault. Never create a new Vault silently.
-4. Create or validate only the locale root: `Content Engine/` (`en`) or
-   `内容引擎/` (`zh`). Never create both in one Vault.
-5. Existing Content Engine files are read-only during setup. Report differences
-   and ask before any migration; never auto-repair or overwrite user content.
-6. Do not start a Local API, open SQLite, call Content MCP, or call private
-   Directus/R2/Stripe endpoints.
-7. Every intent/run is saved under the locale runs folder (`runs/<slug>/` or
-   `成稿/<slug>/`). Every platform gets a Pack. Binary outputs belong only
-   under the locale exports folder.
-8. The host Agent owns copy and semantic decisions. Template and Slideshow Skills
-   own template selection, hosted preview and final rendering.
-9. V1 final output is PNG only. Never create ZIP, JPEG, WebP, PDF or video output.
-10. `content-pack.v1` JSON field names, `role` values and slot keys stay English
-    even when the vault language is 中文. Folder names and Markdown notes follow
-    the chosen locale.
-
-## Setup workflow
-
-1. Detect Obsidian.app.
-2. Ask: 内容引擎用中文还是 English？ Map the answer to `--locale zh` or `--locale en`.
-3. Ask for an existing Vault path.
-4. Preview with `scripts/setup.mjs --vault <path> --locale zh|en --preview --json`.
-5. Create the sanitized Starter and generalized `CLAUDE.md` only after confirmation,
-   using `--apply`.
-6. Open the Vault in Obsidian.
-7. Return the Vault path, locale, engine folder name, and the next workflow.
-
-The deterministic setup helper is `scripts/setup.mjs`. Use `--preview` before
-`--apply`; it never overwrites an existing file and refuses to create anything
-when Obsidian is not installed. It is a helper for the host Agent, not a
-separate product CLI.
-
-After setup, read `locale.json` in the engine root (or detect `内容引擎/` vs
-`Content Engine/`) and keep using that tree. Do not switch language later.
-
-The Starter contains empty indexes, templates and operating rules only. It must
-not contain the owner's personal examples, previous Runs or generated media.
-
-## Run and Pack workflow
-
-For each piece of content, create a local Run with:
-
-- a stable slug and title;
-- platform and language;
-- semantic outline and page roles;
-- generated copy and selected media references;
-- the chosen Profile/Theme identifiers when known;
-- links to the corresponding platform Pack and export Manifest.
-
-Write user-facing notes in the vault locale. The Pack is the handoff to
-`easysociable-slideshow`. It contains public page roles and slot values, never
-private AST, Binding Maps, RenderPlans or a hosted ContentDocument:
-
-```json
-{
-  "schemaVersion": "content-pack.v1",
-  "platform": "tiktok",
-  "title": "A short story",
-  "pages": [
-    { "role": "hook", "slots": { "text_0": "Hook", "text_1": "Support" } },
-    { "role": "value", "slots": { "text_0": "One idea" } }
-  ]
-}
+1. English tree only: `Content Engine/`. Do not ask language.
+2. Obsidian is **not** required. Do not detect, install, or open it.
+3. Ask for a parent directory (or an existing `Content Engine/` path). Never create the engine silently in a random folder.
+4. Existing engine files are read-only during setup. Never overwrite user content, especially `workbench/template.html`.
+5. One platform = one Run (one folder). Same Topic, native rewrite for another network → **N runs**, shared `topic_id`.
+6. On **开一单**: **ask platform(s)** if unset. Multi-select → N runs. Do **not** silent-default to `x`.
+7. Before brief / draft / editor / pack: **read** `platforms/<platform>.md` (`instagram` → `ig.md`).
+8. Write selection into `idea.md` (`swipe_id` / `atoms` / `claim_id`). Chat cards are not citations.
+9. Pack JSON (`content-pack.v1`) only at **handoff to render**. Until then the run uses `pack.md` (slideshow platforms after SHIP).
+10. Final PNGs live under `exports/<run-slug>/`, never inside the run folder. V1 output is PNG only.
+11. Do not start a Local API, open SQLite, call a Content MCP, or call private Directus/R2/Stripe endpoints.
+12. Do not create a hosted Brand Profile during setup.
+
+## When this skill runs
+
+1. Resolve the engine (`--root` parent, or existing `Content Engine/`).
+2. If missing files: `node scripts/setup.mjs --root <path> --apply --json` (never overwrites).
+3. Ensure `workbench/` exists (copy skill `workbench/` files **only if missing**).
+4. `python3` is required. If missing, stop and tell the user.
+5. Run `python3 workbench/build.py`.
+6. If port **8765** is free: start `workbench/serve.py`. If it is already listening, reuse it — do not start a second server.
+7. Open `http://127.0.0.1:8765/workbench/`.
+8. After Agent writes markdown: run `build.py` again (leave serve running).
+
+```bash
+node scripts/setup.mjs --root <parent-or-engine> --preview --json
+node scripts/setup.mjs --root <parent-or-engine> --apply --json
+node scripts/workbench.mjs start --engine "<path>/Content Engine" --json
+node scripts/workbench.mjs build --engine "<path>/Content Engine" --json
+```
+
+`--no-open` skips the browser / server start.
+
+## Intent routing
+
+Defer the body of each flow to engine `CLAUDE.md`. Use these skill workflows only for setup and hosted handoff.
+
+| User intent | Action |
+|---|---|
+| First install / missing engine | Setup above → `workflows/GETTING_STARTED.md` |
+| capture / 记一下 | Engine `CLAUDE.md` § Capture |
+| Watchlist add | Engine `CLAUDE.md` § Topics (watchlist files) |
+| 扫 watchlist / 发现内容 | Engine `CLAUDE.md` § Discovery — Source Digest only; no Topics |
+| 选题 / score topics | Engine `CLAUDE.md` § Topics — explicit input; Scout→opportunity 5-dim; ready=opp≥7.5 and aud≥6; cap=5 produce |
+| 开一单 / open a run | Engine `CLAUDE.md` § Open a run — **ask platforms**; N platforms → N folders |
+| 收成 swipe/atom/claim | Engine `CLAUDE.md` § Library ingest |
+| Ship + URL + result | Engine `CLAUDE.md` § Published index + Catalog evidence |
+| 出图 / pack + render | Engine `CLAUDE.md` § PagePack, then handoff below |
+| Platform craft | `Content Engine/platforms/<platform>.md` + `references/PLATFORM_GUIDE.md` |
+| Single-page image | Hand off → **easysociable-template** |
+| Multi-page slideshow | Hand off → **easysociable-slideshow** (Pack JSON at this step) |
+| Export PNGs | `workflows/CONTENT_EXPORT.md` |
+| Hosted CLI/MCP | `workflows/MCP_FIRST.md` |
+| Out of scope | `workflows/OUT_OF_SCOPE.md` |
+
+### Single-page vs slideshow
+
+```text
+1 page                          → easysociable-template
+2+ pages + slideshow platform   → easysociable-slideshow
+x / xiaohongshu                 → easysociable-template only
+```
+
+Slideshow platforms: `tiktok`, `instagram`/`ig`, `linkedin`, `threads`.
+
+## Run model
+
+```text
+ask platform(s) → N folders
+  runs/<YYYY-MM-DD-slug[-platform]>/idea.md   ← one platform, selection ids
+  brief.md → packet.md → draft.md → editor.md → rubric.md
+  pack.md (after SHIP, image decks only)
+  pack-<platform>.json                        ← only at Slideshow/Template handoff
+```
+
+Copy `runs/_template/` for each platform. Update `runs/_index.md` (one row per run).
+
+Validate before slideshow handoff:
+
+```bash
+node scripts/validate-run.mjs --run <run-dir> --json
+node scripts/validate-run.mjs --run <run-dir> --require-pack --json
 ```
 
 ## Handoff
 
-For a single image, hand the selected published Page Template and slot values to
-the Template workflow. For a slideshow:
+**Slideshow (multi-page):**
+
+1. Rubric SHIP on this run. Write `pack.md` (slots only).
+2. Hand off to `easysociable-slideshow`. It selects a Page Template per page and writes `pack-<platform>.json`.
+3. User confirms Studio preview.
+4. Final render + export to `{engine}/exports/<run-slug>/`.
 
-1. write the Pack to the Run folder;
-2. ask the Slideshow Skill to create/update a temporary Run;
-3. let the Agent review the returned Studio URL;
-4. after confirmation, let the Agent call `easysociable slideshows render`;
-5. let the Agent call `easysociable renders export` to atomically write PNGs and
-   `manifest.json` under the Run's exports directory.
+**Template (single-page):**
 
-Preview is not a final local export and does not consume hosted Render Page
-allowance. The final render does.
+1. Hand off slot values to `easysociable-template` `FILL_AND_RENDER`.
 
-Network research is optional. If the host does not expose a search tool, keep
-the source URL in the local note and continue with user-provided evidence; do
-not install an MCP server automatically and do not block vault setup.
+Preview does not consume Render Page allowance. Final render does.
 
-## Required references
+## Reference loading
 
-- `references/PAGE_PACK.md`
-- `references/VAULT.md`
-- `workflows/CONTENT_EXPORT.md`
-- `workflows/MCP_FIRST.md` (for the unified CLI/MCP handoff only)
+Always read engine `CLAUDE.md`, `engine.json`, `references/RUN_LAYOUT.md` and
+`references/PLATFORM_GUIDE.md`. Load `GETTING_STARTED` on first install,
+`PACK_AUTHORING` / `CONTENT_EXPORT` / `MCP_FIRST` only at render handoff.

package/skills/easysociable-content/fixtures/golden-run-en/draft.md

@@ -0,0 +1,13 @@
+# Draft
+
+## Page 1 (hook)
+Stop scrolling — this changed my mornings.
+
+## Page 2 (value)
+Wake at the same time, even on weekends.
+
+## Page 3 (value)
+No phone for the first 20 minutes after waking.
+
+## Page 4 (cta)
+Save this and try it tomorrow.

package/skills/easysociable-content/fixtures/golden-run-en/idea.md

@@ -0,0 +1,26 @@
+---
+run_id: RUN-20260823-morning-routine-tips
+status: pack-ready
+created: 2026-08-23
+---
+
+# Idea
+
+- **one_liner:** Three morning habits that calm the start of the day
+- **account:** your-handle
+- **profile:** default
+- **pillar:** P1
+- **primary_platform:** tiktok
+- **platforms:** tiktok
+- **topic_id:** none
+- **capture_ids:** none
+- **swipe_id:** none
+- **atoms:** none
+- **claim_id:** none
+- **hypothesis:** none
+
+## Platform (this run)
+
+| platform | copy | images (pack) | publish status |
+|----------|------|---------------|----------------|
+| tiktok | yes | yes | pending |

package/skills/easysociable-content/fixtures/golden-run-en/pack-tiktok.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": "content-pack.v1",
+  "platform": "tiktok",
+  "title": "Three morning habits",
+  "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": "Even on weekends" } },
+    { "role": "value", "pageTemplateId": "tpl_value_001", "slots": { "text_0": "No phone for 20 minutes", "text_1": "Before email or feeds" } },
+    { "role": "cta", "pageTemplateId": "tpl_cta_001", "slots": { "text_0": "Save this for tomorrow" } }
+  ]
+}

package/skills/easysociable-content/platforms/claude.md

@@ -1,5 +1,4 @@
 # Claude Desktop
 
-- Install the unified EasySociable Skill bundle. Content remains Obsidian-first;
-  hosted Template/Slideshow calls use the unified `easysociable` CLI/MCP.
+- Install the unified EasySociable Skill bundle. Content is filesystem-first under `Content Engine/`; hosted Template/Slideshow calls use the unified `easysociable` CLI/MCP.
 - Prefer the Skill frontmatter in each `SKILL.md`.

package/skills/easysociable-content/platforms/codex.md

@@ -1,5 +1,4 @@
 # Codex
 
 - Install `skills/easysociable-content` under the host skill directory for local content workflows.
-- Install the unified EasySociable Skill bundle; hosted preview/render uses the
-  unified `easysociable` CLI/MCP.
+- Install the unified EasySociable Skill bundle; hosted preview/render uses the unified `easysociable` CLI/MCP.

package/skills/easysociable-content/platforms/hermes.md

@@ -1,5 +1,4 @@
 # Hermes overrides
 
 - Point Hermes skill loader at this directory.
-- Prefer explicit Vault paths in multiprocess environments; do not use the
-  retired `--data-dir` Runtime option.
+- Prefer explicit `Content Engine/` paths in multiprocess environments.

package/skills/easysociable-content/platforms/openclaw.md

@@ -1,5 +1,4 @@
 # OpenClaw overrides
 
 - Register the unified `easysociable` CLI/MCP entry.
-- Keep API Keys and session material out of tool logs. Gateway authentication is
-  owned by the unified client.
+- Keep API Keys and session material out of tool logs. Gateway authentication is owned by the unified client.

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

@@ -1,18 +1,25 @@
 # Content Skill filesystem reference
 
-The Content Skill does not own a Content CLI in V1. It writes the user's
-existing Obsidian Vault directly and uses the unified `easysociable` command only
-for the hosted Template/Slideshow handoff.
+The Content Skill does not own a Content CLI. It writes `Content Engine/` on disk and uses the unified `easysociable` command only for hosted Template/Slideshow handoff.
 
 ## Local workflow
 
-Use the host's filesystem tools to detect Obsidian, ask for 中文 or English,
-choose a Vault, preview the locale engine paths (`Content Engine/` or
-`内容引擎/`) with `--locale zh|en`, create or validate Markdown/JSON files after
-confirmation, and open the Vault in Obsidian.
+Ask for a parent directory (or existing engine path). Do not ask language. Do not require Obsidian.
 
-Do not invent `easysociable-content init/start/doctor` commands and do not pass
-`--data-dir`. Those belong to the retired Content Runtime.
+Do not invent `easysociable-content init/start/doctor`.
+
+## Setup
+
+```bash
+node scripts/setup.mjs --detect --json
+node scripts/setup.mjs --root <parent-or-engine> --preview --json
+node scripts/setup.mjs --root <parent-or-engine> --apply --json
+node scripts/setup.mjs --root <parent-or-engine> --validate --json
+node scripts/workbench.mjs start --engine <Content Engine> --json
+node scripts/workbench.mjs build --engine <Content Engine> --json
+```
+
+`--no-open` skips the browser and the workbench server.
 
 ## Hosted handoff
 
@@ -20,8 +27,14 @@ Do not invent `easysociable-content init/start/doctor` commands and do not pass
 easysociable templates list --platforms tiktok --json
 easysociable slideshows create --file ./runs/<slug>/pack-tiktok.json --json
 easysociable slideshows render --id run_xxx --idempotency-key run_xxx-final-1 --json
-easysociable renders wait --id job_xxx --json
-easysociable renders export --id job_xxx --output ./exports/<slug>/tiktok --json
+easysociable slideshows export --id run_xxx --output ./exports/<slug> --json
+```
+
+Validate before slideshow create:
+
+```bash
+node scripts/validate-run.mjs --run ./runs/<slug> --require-pack --json
+node scripts/validate-pack.mjs --file ./runs/<slug>/pack-tiktok.json --json
 ```
 
-Use the unified MCP first when the host exposes it. The CLI is the fallback.
+Use unified MCP first when the host exposes it. CLI is the fallback.

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

@@ -0,0 +1,42 @@
+# Contract sync
+
+Pack validation in this skill mirrors the hosted public contract. When those
+contracts change, update this skill in the same PR.
+
+## Source of truth
+
+| Contract | Repository path |
+|---|---|
+| `content-pack.v1` schema | `packages/template-public-contracts/src/index.ts` → `contentPackSchema` |
+| Platform page caps | `slideshowPlatformCaps` in the same file |
+| Page roles | `pageRoleSchema` in the same file |
+
+## Mirrored in skill
+
+| Skill file | What to sync |
+|---|---|
+| `scripts/contracts.mjs` | caps, roles, forbidden keys, validate logic |
+| `references/PAGE_PACK.md` | Agent-facing summary + examples |
+| `references/PLATFORM_GUIDE.md` | slideshow vs template routing |
+
+## Maintainer checklist
+
+Before merging contract changes:
+
+1. Diff `contentPackSchema` / `slideshowPlatformCaps` / `pageRoleSchema`.
+2. Update `contracts.mjs` and `PAGE_PACK.md`.
+3. Run:
+
+   ```bash
+   node skills/easysociable-content/scripts/validate.test.mjs
+   node skills/easysociable-content/scripts/fixture.test.mjs
+   node skills/easysociable-content/scripts/setup.test.mjs
+   ```
+
+4. If caps or roles changed, refresh `fixtures/golden-run-en/pack-tiktok.json` when needed.
+
+## Optional hard sync (future)
+
+Import `contentPackSchema` from `@easysociable/template-public-contracts` in
+`validate-pack.mjs` once skill scripts run through the monorepo toolchain. Until
+then, `contracts.mjs` is the portable mirror (marked with `ponytail:`).

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

@@ -1,20 +1,15 @@
 # Unified MCP reference
 
-V1 has one MCP server installed by the unified EasySociable installer. It owns
-hosted Template, Image, Profile, Theme, Slideshow and Render tools. The Content
-Skill itself does not require a Content MCP or local MCP bridge.
+V1 has one MCP server from the unified EasySociable installer. It owns hosted Template, Image, Profile, Theme, Slideshow and Render tools. This Content Skill does not require a Content MCP.
 
-Use the MCP tool registry exposed by `easysociable mcp serve --transport stdio`. Content work stays
-in the Obsidian filesystem; hosted calls use the same Gateway client and account
-as the CLI.
+Content work stays on disk under `Content Engine/`. Hosted calls use the same Gateway client as the CLI.
 
 ## Handoff sequence
 
-1. Write a `content-pack.v1` into the local Run folder.
-2. Call `create_slideshow_run` with the Pack.
-3. Open the returned Studio URL and wait for Save.
+1. After SHIP, write `pack.md` (slideshow) or slot values (single-page).
+2. Slideshow skill writes `content-pack.v1` into the run folder, then `create_slideshow_run`.
+3. Open Studio URL; wait for Save.
 4. After confirmation call `render_slideshow_run`.
-5. Poll the render job and export the PNG set into the Vault.
+5. Export PNGs into `exports/<run-slug>/`.
 
-The MCP server must never expose private AST, Binding Maps, RenderPlans, R2
-credentials, Directus credentials, Stripe credentials or Local Runtime tokens.
+The MCP server must never expose private AST, Binding Maps, RenderPlans, R2 credentials, Directus credentials, Stripe credentials or Local Runtime tokens.