@easysociable/cli 0.1.2 → 0.1.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@easysociable/cli",
-  "version": "0.1.2",
-  "description": "Agent-first CLI and MCP host for EasySociable Template and Slideshow V1",
+  "version": "0.1.4",
+  "description": "Agent-first CLI for EasySociable: Content Engine, Template, Slideshow, and MCP",
   "type": "module",
   "license": "MIT",
   "author": "EasySociable",
@@ -33,16 +33,10 @@
     "bin",
     "dist",
     "skills",
+    "content-engine",
     "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/"
@@ -51,13 +45,19 @@
     "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",
     "tsup": "^8.0.2",
     "typescript": "^5.8.3",
-    "vitest": "^1.3.1"
+    "vitest": "^1.3.1",
+    "@easysociable/mcp-server": "0.0.0",
+    "@easysociable/tsconfig": "0.0.0",
+    "@easysociable/template-gateway-client": "0.0.0",
+    "@easysociable/vitest-config": "0.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsup",
+    "pack:check": "npm pack --dry-run"
   }
-}
+}

package/skills/ONBOARDING.md

@@ -1,35 +1,38 @@
 # EasySociable agent-first onboarding
 
-V1 expects Codex or Claude Code to drive setup. The website is not the primary
-workspace.
+V1 expects an Agent (Grok Bot, Codex, Claude Code, …) to drive setup. The website is not the primary workspace.
 
-## User steps (3)
+## User steps
 
 1. **Install CLI**
 
    ```bash
    curl -fsSL https://easysociable.com/install.sh | bash
+   # or: npm i -g @easysociable/cli
    ```
 
-2. **Install hosted Skills + MCP** (Template + Slideshow by default)
+2. **Install Skills + MCP** (Template + Slideshow by default; for Codex / Claude Code)
 
    ```bash
    easysociable install --yes
    ```
 
-3. **Ask the Agent to create graphics** — account creation is deferred until a
-   hosted operation requires authentication.
+   Default skills:
 
-Optional later:
+   - `easysociable-slideshow` — turns a draft into slideshow pages you preview and download in the dashboard
+   - `easysociable-template` — creates page templates
 
-```bash
-easysociable install --skills content --yes
-```
+   Optional Content Engine skill (pointer only — operations live in `Content Engine/CLAUDE.md`):
+
+   ```bash
+   easysociable install --skills content,template,slideshow --yes
+   easysociable engine init --root /workspace --yes
+   easysociable engine serve --engine /workspace/Content Engine --no-open
+   ```
+
+   On a laptop, use any parent path instead of `/workspace` for `engine init` / `serve`.
 
-Then run the `easysociable-content` setup workflow (Obsidian Vault + Content
-Engine). For a private copy to another machine, see
-`skills/easysociable-content/INSTALL.md`. Skipping Content does **not** block
-single-page or Slideshow renders.
+3. **Ask the Agent to create graphics** — account creation is deferred until a hosted operation requires authentication. If you installed the content skill: interview and write the profile first, then capture audience quotes into `needs/` (at least 3, aim for 5); do not create a slideshow yet.
 
 ## Lazy auth (Agent script)
 
@@ -37,8 +40,7 @@ When a Gateway call returns `AUTH_REQUIRED`, `API_KEY_INVALID`, or the CLI says
 `Run easysociable auth login`, respond with:
 
 ```text
-EasySociable needs a workspace API key before it can preview or render on the
-Gateway.
+EasySociable needs a workspace API key before it can create Brands, images, drafts or Slideshow Runs on the Gateway.
 
 1. Open https://my.easysociable.com/auth/signup (or sign in with Google).
 2. Verify your email if you used password signup (required before API keys).
@@ -54,10 +56,11 @@ idempotency key when applicable.
 ## What works without auth
 
 - `easysociable install` / `update`
+- `easysociable engine init` / `serve` / `build` / `validate`
 - Reading installed Skill instructions
 - Public template catalog in the browser (`/templates`)
 
 ## What requires auth
 
-- Profiles, Themes, images, drafts, Slideshow Runs
-- Hosted preview sessions and final PNG renders (`hosted_render_page` allowance)
+- Brands, Themes, images, drafts, Slideshow Runs
+- Studio preview and Studio Download (Free: 3 Downloads/month)

package/skills/easysociable-content/SKILL.md

@@ -1,126 +1,132 @@
 ---
 name: easysociable-content
 description: >
-  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.
+  Operate the EasySociable Content Engine (profile, needs, products, recommendations, topics, runs, workbench).
+  Triggers: 采访我, 完善人设, interview me, who am I as a creator, 建立 profile
+  — follow workflows/INTERVIEW.md (engine CLAUDE.md § Interview wins if present).
+  Triggers: 记需求, 扫需求选题, capture audience quotes, user needs, 调研需求, 需求落库
+  — follow workflows/NEEDS.md (engine CLAUDE.md § Needs wins if present).
+  Triggers: 更新产品, 产品库, product facts, product pricing, product offer
+  — follow the engine CLAUDE.md § Products and edit `products/`.
+  Triggers: 推荐产品, 评测工具, compare tools, review an AI product
+  — edit `recommendations/`; do not treat third-party subjects as owned Products.
+  Triggers: 做成选题, 开一单, 出图
+  — follow engine CLAUDE.md (§ Topics / § Open a run / § PagePack).
+  If no engine exists, run `easysociable engine init`. Then follow
+  Content Engine/CLAUDE.md. Render handoff: easysociable-template (1 page) or
+  easysociable-slideshow (2+). Never publish or post.
 ---
 
-# EasySociable Content Skill
-
-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. 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).
+# EasySociable Content
 
-```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
+Entry card for agents. **Do not invent a parallel workflow.** Instance SoT is that engine’s `Content Engine/CLAUDE.md`. Workflows here fill gaps or win when newer than the matching § in CLAUDE.md.
 
-Defer the body of each flow to engine `CLAUDE.md`. Use these skill workflows only for setup and hosted handoff.
+## Product boundary
 
-| 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` |
+- Teach a **Content Engine** (signal → decision → draft → review → reusable learning).
+- **EasySociable** is the **visual production layer** inside that engine — not the content brain, not the whole system.
+- For `easysociable-builder` needs research, prefer **L1 system / L2 judgment-review** pains (sustainable publishing) over **L3 visual-tool** friction, unless the user asks for L3.
 
-### Single-page vs slideshow
+## Pipeline (do not collapse stages)
 
 ```text
-1 page                          → easysociable-template
-2+ pages + slideshow platform   → easysociable-slideshow
-x / xiaohongshu                 → easysociable-template only
+Profile / Audience
+  → Needs (verbatim audience quotes)
+  → optional Product (owned offer facts) or Recommendation (third-party review subject)
+  → Pillar (what this profile discusses) + Lane (how it publishes)
+  → Topic (decision summary + readable judgment + Score appendix)
+  → Run → Pack → Publish / feedback
 ```
 
-Slideshow platforms: `tiktok`, `instagram`/`ig`, `linkedin`, `threads`.
-
-## Run model
+| Stage | Owns | Does not |
+|-------|------|----------|
+| Needs `N-` | Verbatim reader/operator quotes | Watchlist hooks, Agent rewrites |
+| Products `P-` | Owned offer facts, pricing, boundaries | Audience demand or third-party reviews |
+| Recommendations `R-` | Third-party subject, evidence, limits, disclosure | Owned product claims |
+| Pillars / lanes | Durable subject / publishing mode | A replacement for Needs or evidence |
+| Topic `T-` | Human judgment card + opp gate | Being auto-created from heat |
+| Workbench | Read-only observatory | Source of truth (markdown indexes are) |
+
+## Hard rules
+
+1. **No invented quotes** — Needs quote cell = verbatim only. Gloss is separate (`layer=L1|L2|L3` allowed in gloss).
+2. **Heat ≠ topic** — External source metrics never make `ready`.
+3. **Never invent `N-` from a product, vendor claim, or headline.** Match captured needs only.
+4. **Topic decision card first** — start with 结论 / 状态原因 / 适合谁 / 核心判断 / 下一步, then explain the problem, current belief, angle, timing, expected belief change, evidence gap, and recommended form. Keep scores and IDs in the appendix. Chat output is the readable decision card, not a score walkthrough.
+5. **`N-` never in `capture_id`** — needs go in `need_ids` only.
+6. **Rebuild workbench** after markdown writes in the engine vault.
+7. **Keep ownership explicit** — `products/` is for offers we own or provide;
+   `recommendations/` is for third-party tools and products. A Topic may cite
+   `product_ids`, `recommendation_ids`, both, or neither.
+8. **Use the smallest honest Topic mode** — demand-led is the default;
+   product/recommendation inputs do not prove audience demand.
+
+Topic modes:
 
 ```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
+demand             = Needs + Profile
+demand_to_offer    = Needs + Product + Profile
+demand_to_review   = Needs + Recommendation + Profile
+review             = Recommendation + evidence + Profile
+offer_education    = Product + mechanism + Profile
+profile_thesis     = Profile + Pillar
 ```
 
-Copy `runs/_template/` for each platform. Update `runs/_index.md` (one row per run).
-
-Validate before slideshow handoff:
+## Create / serve / build
 
 ```bash
-node scripts/validate-run.mjs --run <run-dir> --json
-node scripts/validate-run.mjs --run <run-dir> --require-pack --json
+easysociable engine init --root <parent-or-engine> --yes
+easysociable engine serve --engine <parent>/Content Engine --no-open
+easysociable engine build --engine <parent>/Content Engine
+# or, inside the vault:
+python3 workbench/build.py
 ```
 
-## Handoff
+On a dedicated agent computer (e.g. Grok Bot), prefer `--root /workspace`.
+
+Existing files are never overwritten. `python3` is required for the workbench. Observatory: `http://127.0.0.1:8765/workbench/` — top tabs include **需求库 / Needs**. If `serve.py` is already up, do not start a second server; rebuild only.
+
+`engine init` adds missing `products/` and `recommendations/` starter files to
+older vaults without overwriting user files. It does not invent recommendation
+entries or migrate existing product notes.
 
-**Slideshow (multi-page):**
+## Operate
 
-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. Resolve account → profile (engine `CLAUDE.md`).
+2. Route by intent (table below). Prefer engine `CLAUDE.md` sections; use `workflows/*` when that file is newer or the § is missing.
+3. Always return the structured chat card the section defines.
+4. Rebuild workbench after writes.
+
+| Intent | Action |
+|--------|--------|
+| 采访我 / interview me / 完善人设 / 建立 profile | **workflows/INTERVIEW.md** (not a render) |
+| 记需求 / 用户原话 / capture audience quotes / 调研需求 / 需求落库 | **workflows/NEEDS.md** (not a render) |
+| 更新产品 / 产品库 / product facts | Engine **§ Products** — update owned offer facts and dated pricing |
+| 推荐产品 / 评测工具 / compare or review | `recommendations/` — collect evidence and disclosure before Topic |
+| 扫需求选题 | **NEEDS.md** then Topics from `needs/` `status=captured` |
+| 做成选题 / 生成 topic | engine **§ Topics** — explicit input |
+| 开一单 / 用 T-… 开一单 | engine **§ Open a run** (ask platform; multi → N runs) |
+| 1 page image | **easysociable-template** (after hard gate) |
+| 2+ pages on tiktok / instagram / linkedin / threads | **easysociable-slideshow** (after hard gate) |
+| x / xiaohongshu images | **easysociable-template** only (after hard gate) |
+
+## Render hard gate
+
+**Before any template/slideshow call:** Identity in `profiles/<active>/voice.md` — Role / What I build / Point of view — no `(fill)` and non-empty; `boundaries.md` exists with Not covering and Never claim both non-empty. If `needs/` exists, `needs/_index.md` ≥ **3** `N-` rows; if `needs/` is absent, skip that count. Public handle MAY stay `(fill)`.
+
+On fail: **stay in this skill**. List missing files. Do not call template or slideshow. User must say **强制继续** / **force continue** to proceed.
+
+```bash
+easysociable engine validate --run <run-dir> --require-pack --require-knowledge
+```
 
-**Template (single-page):**
+Slideshow packs need an **Arc** line first. Do not default Cover → Point → Steps → Recap → CTA. Page 1 is not automatically `cover`. Handoff: **easysociable-slideshow** (`references/ARC.md`).
 
-1. Hand off slot values to `easysociable-template` `FILL_AND_RENDER`.
+## Research (Needs)
 
-Preview does not consume Render Page allowance. Final render does.
+- Prefer host research tools. On **X**: built-in `x_*` first; fall back to agent-reach / `twitter` only if insufficient.
+- Store **commenter** words when scraping threads. Do not invent `N-` when a platform tool is missing—stop and ask for paste.
 
-## Reference loading
+## Out of scope
 
-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.
+No social posting, Content MCP, Local API, or SQLite content library.

package/skills/easysociable-content/workflows/INTERVIEW.md

@@ -0,0 +1,70 @@
+# Interview (creator profile)
+
+Not a fourth skill. If the engine `CLAUDE.md` already has **§ Interview**, follow that section. Otherwise follow this file.
+
+Do **not** ingest needs / quotes here. Do **not** scan the watchlist. Do **not** create a slideshow or call template/slideshow.
+
+## Triggers
+
+- 采访我
+- 完善人设
+- interview me
+- who am I as a creator
+- 建立 profile
+
+## Rules
+
+- Ask **one dimension at a time**. Persist that dimension **before** asking the next. Do not batch seven dimensions to the end.
+- Resume by reading files. Skip Public handle `(fill)` (done unless the user wants a handle). Continue from the first gated empty Identity cell (Role / What I build / Point of view) or the next unfinished dimension. Do not re-ask filled Identity rows.
+- Existing `voice.md` with Identity filled but no `## Experience` / `## Values`: **append those headings at the end**. Do not rewrite filled Identity rows.
+- Missing `boundaries.md`: write the empty starter (headings only), then interview. **Never invent boundaries.**
+- Missing `stories.md` / `expression.md`: create the starter file, mark `profile: partial`, continue.
+- `audience.md` / `pillars.md` in this workflow are **drafts only** (hypothesis). Do not invent a full ICP.
+- Never invent bio facts, stories, or values that the user did not say.
+
+## Dimensions → files (8–12 questions)
+
+| # | Dimension | Questions | Persist immediately to |
+|---|-----------|-----------|------------------------|
+| 1 | Identity (2) | 你对外是谁、做什么？你希望别人记住的那句 point of view 是什么？ | `voice.md` `## Identity` — Role / What I build / Point of view. Public handle MAY stay `(fill)`. |
+| 2 | Experience (1–2) | 文案可以引用的 2–3 件事实（年份、角色、做过的事）。没有的就写「not claiming」。 | `voice.md` `## Experience` (append heading if missing) |
+| 3 | Style (1–2) | 想听起来像谁；最讨厌的 AI 腔 / 营销腔。 | `voice.md` `## Persona` + `## Do not say` |
+| 4 | Values (1) | 你一定会说 / 一定不说的主张。 Repeatable topics → `pillars.md` names later, not a copy of this table. | `voice.md` `## Values` (append heading if missing) |
+| 5 | Boundaries (1) | 哪些话题、人群、承诺碰不得。 | `profiles/<id>/boundaries.md`. If the file is missing, write empty starter first, then fill. Never invent. |
+| 6 | Expression (1) | 举三个你喜欢的表达、三个你看到就烦的。 | `profiles/<id>/expression.md` |
+| 7 | Stories (1, skippable) | 一则你常讲、且愿意公开的故事（情境 → 选择 → 教训）。 | `profiles/<id>/stories.md` |
+| 8 | Audience draft (1) | 你以为在写给谁？ Mark `status: hypothesis`. | `audience.md` Primary readers |
+
+## Persist card (after each dimension)
+
+```text
+✅ Profile · Identity
+【File】 profiles/default/voice.md
+【Wrote】 Role … · POV …
+【Missing】 Experience, Values, stories.md
+【Next】 经历（2–3 条可引用事实）
+```
+
+### Example — boundaries file missing
+
+```text
+✅ Profile · Boundaries
+【File】 profiles/default/boundaries.md
+【Wrote】 empty starter (## Not covering / ## Never claim). Did not invent boundaries.
+【Missing】 Not covering, Never claim
+【Next】 边界（哪些话题、人群、承诺碰不得）
+```
+
+## Completion (single table — do not invent other numbers)
+
+| Level | Condition | Behavior |
+|-------|-----------|----------|
+| **Hard gate** (refuse slideshow handoff / `create_run`) | Identity **only** Role / What I build / Point of view have no `(fill)` and are non-empty (Public handle and Not claiming MAY stay `(fill)` / starter copy) **and** `boundaries.md` exists with Not covering **and** Never claim both non-empty. If `needs/` exists, also `needs/_index.md` ≥ 3 `N-` rows; if `needs/` is absent, skip that count. | Refuse 出图 / PagePack handoff / `slideshows create`. List missing files. User must say **强制继续** / **force continue** to proceed. |
+| **First-session goal** | Hard gate **and** Persona has at least one personalized line **and** needs **target 5** (under 5 still passes the hard gate) **and** `stories.md` may be 0–1 | Open card `profile: partial`. May 扫需求选题. Still no graphics unless forced. |
+| **Complete seven dimensions** | Identity + Experience (≥2) + Values (≥3) + Persona/Do not say + `stories.md` ≥1 + `boundaries.md` + `expression.md` likes/dislikes ≥3 each + needs ≥5 | Open card `profile: complete`. Remaining gaps are draft reminders only — **not** a hard-stop on graphics. |
+
+Experience / Values / expression are **not** the hard gate. Missing `stories.md` / `expression.md` = partial. Missing `boundaries.md` file = hard-gate fail.
+
+## Open card
+
+After the session (or on resume): `profile: partial | complete` from the table above.

package/skills/easysociable-content/workflows/NEEDS.md

@@ -0,0 +1,82 @@
+# Needs (audience quotes)
+
+Not a fourth skill. If the engine `CLAUDE.md` already has **§ Needs**, follow that section **unless this file is newer** — then this file wins for Needs-only rules.
+
+Do **not** invent quotes. Do **not** scan the watchlist to mint needs. Do **not** create a slideshow.
+
+## Triggers
+
+- 记需求 / 用户原话 / 评论导出
+- 扫需求选题
+- capture audience quotes / user needs
+- 调研需求 / 需求落库 / 重新调研并落库
+
+## Research axis (easysociable-builder default)
+
+Product teaches **Content Engines**; EasySociable is the **visual layer**. When researching or screening needs for this profile:
+
+| Layer | Means | Default |
+|-------|--------|---------|
+| **L1** | System / sustainability — what to say, what to publish next, memory, pipeline, consistency | **Prefer** |
+| **L2** | Judgment / review / approval — AI polished but empty; bottleneck moved to human check | **Prefer** |
+| **L3** | Visual / tool friction — Canva, Figma, “looks AI”, brand kit paste | Keep only if user asks; else do not promote as primary |
+
+Put `layer=L1|L2|L3` in **`## Our gloss` only** — never in the index `quote` cell.
+
+**Reject:** course/toolkit CTAs, product demos dressed as pains, watchlist viral titles as quotes, Agent-paraphrased “quotes”, wrong-ICP “idk what to post” with no system angle.
+
+## Rules
+
+- Quote cell = **verbatim**. Gloss goes in `## Our gloss`, never in the index `quote` column.
+- Status is only `captured` | `promoted` | `retired`. **Never** `clustered`. Merge is not a new status.
+- Synonym merge: propose, wait for user yes, then keep the surviving `N-` as `captured`, `frequency += 1`, append a sighting. Retire a mistaken duplicate and note it on the surviving sighting. No hosted clustering.
+- Do not mark `promoted` without a `T-` whose `need_ids` contain this `N-`. `topic_ids` non-empty ≡ `promoted`.
+- Never write `N-` into topic `capture_id`.
+- Hard gate (graphics): once `needs/` exists, `needs/_index.md` needs ≥ **3** `N-` rows. First-session **target** is **5** (under 5 still passes the hard gate). Do not invent quotes to hit the number.
+- Quotes may include DMs / students. Keep local. Redact PII if used as published copy.
+- After Needs writes: rebuild workbench (`python3 workbench/build.py` or `easysociable engine build`).
+
+## Delete vs retire
+
+- `retired` = soft discard while the user may still want the row visible.
+- If the user says **删除 / 删掉 retired / 可以直接删了**: **delete** the entry file(s) and remove the index row(s). Do not leave ghost `retired` rows. Rebuild workbench.
+- Do not delete `captured` or `promoted` without an explicit ask.
+
+## Ingest paths
+
+1. Pasted quote — 「记需求：……」 / “capture audience quotes: …”
+2. Comment / DM export or screenshot — extract quotes; one `N-` each; confirm with the user when unsure.
+3. URL / thread — fetch with host research tools; store the **commenter's** words, not the author's hook. On **X**: `x_*` first, then agent-reach if needed.
+4. After a consult — 「刚才那通咨询记需求」.
+5. Research pass — screen for L1/L2; write `N-` only for verbatim hits; update `_index.md` research note briefly.
+
+Forbidden: Agent-rewritten sentences as quote; watchlist viral titles as need; FAQ templates with no original quote.
+
+## Write
+
+1. New `needs/entries/N-YYYYMMDD-XX.md` from `needs/_template.md`
+2. New row at the top of `needs/_index.md`
+3. Rebuild workbench
+4. Chat card:
+
+```text
+✅ Need N-YYYYMMDD-XX
+【Quote】 …
+【Source】 comment | dm | consult | faq | student | other
+【Layer】 L1 | L2 | L3
+【Frequency】 1
+【Stored】 needs/_index + needs/entries/N-….md
+【Merge】 new | merged into N-… (frequency now k, status still captured)
+```
+
+## 扫需求选题
+
+Input set: `needs/_index.md` rows with `status=captured` (`topic_ids` empty). Max **5** `produce`. Prefer L1/L2 glosses for this profile unless the user asks otherwise.
+
+Then **§ Topics**: Input gate Need ID `N-…`; `source_type=need`; `need_ids` lists the `N-` (never in `capture_id`); default `scout_label=demand`. Still run hard filters.
+
+When `produce` creates a `T-` from an `N-`: update `needs/_index.md` + the entry to `status=promoted` and `topic_ids` containing that `T-`. Discard / library: leave `captured` or `retired` — do not mark `promoted` without a T-.
+
+Audience exception (first activation): `source_type=need` **and** `need_ids` non-empty → matching at least one need gloss counts as one strong audience check; do **not** require a full ICP from `audience.md` / `pillars.md`. `ready` still needs `opp_score ≥ 7.5` **and** `audience ≥ 6`.
+
+Prefer scanning needs before inbox. Inbox is structure / competitor context.