@easysociable/cli 0.1.3 → 0.1.5

package/content-engine/starter/topics/README.md

@@ -1,25 +1,21 @@
 # topics/
 
-Topic system: **what to produce next**, after an external signal has been understood and converted into an owned opportunity.
+Topic system: **what to produce next**, after an explicit need, offer, review subject, or profile thesis has been judged as an opportunity.
 
 | Path | Role |
 |------|------|
 | `_index.md` | Queue registry (one row per topic + `item` link + source engagement) |
-| `items/T-*.md` | One file per opportunity (context, audience, conflict, insight, evidence) |
-| `WATCHLIST.md` | Watchlist router (per-profile scheme B) |
-| `watchlists/<profile_id>.md` | Profile-scoped radar |
-| `watchlists/_shared.md` | Shared radar for all profiles |
+| `items/T-*.md` | One file per opportunity: decision summary + readable judgment, then Score/Trace/Constraints appendix |
 | `scoring.md` | Opportunity dimensions and dual gate |
 | `_template-item.md` | Template for new items |
 
 Flow:
 
 ```text
-watchlist → Discovery (Source Digest)
-  → user explicitly promotes
+explicit input → editorial judgment
   → `_index` + `items/T-…` (opportunity 5-dim)
   → ready only if opp≥7.5 and audience≥6
   → user opens run → `status=promoted`
 ```
 
-Cap **5 produce** per promotion session. Watchlist scan itself creates Discovery records, not Topics.
+The item file is a **decision card**. A content owner who skips YAML and the appendix must still answer: what problem we address, who it serves, what we will say, why now, what should change, and whether to open a run. Five-dim scores stay in the appendix as a gate, not as the reading surface.

package/content-engine/starter/topics/_index.md

@@ -6,8 +6,8 @@ Statuses live here and in the item—**not** folder names.
 
 Newest on top.
 
-| id | date | opp | aud | status | purpose | scout | platform | pillar | one_liner | item | source_type | src_url | src_handle | src_likes | src_replies | src_bookmarks | engagement_at | capture_id | run |
-| -- | ---- | --- | --- | ------ | ------- | ----- | -------- | ------ | --------- | ---- | ----------- | ------- | ---------- | --------- | ----------- | ------------- | ------------- | ---------- | --- |
+| id | date | opp | aud | status | purpose | scout | platform | pillar | lane | generation_mode | one_liner | item | source_type | src_url | src_handle | src_likes | src_replies | src_bookmarks | engagement_at | capture_id | need_ids | product_ids | product_fit | recommendation_ids | run |
+| -- | ---- | --- | --- | ------ | ------- | ----- | -------- | ------ | --------- | ---- | ----------- | ------- | ---------- | --------- | ----------- | ------------- | ------------- | ---------- | --- | --- | --- | --- |
 
 ## Status values
 
@@ -29,16 +29,23 @@ Newest on top.
 | `opp` | Opportunity score (weighted 5-dim: context/audience/conflict/insight/evidence) |
 | `aud` | Audience dimension score (hard floor ≥ 6 for ready) |
 | `item` | Wikilink to `topics/items/T-….md` |
-| `source_type` | `watchlist` \| `inbox` \| `user` \| `discovery` |
+| `lane` | Publishing lane: teach, build, review, compare, offer, or profile-defined |
+| `generation_mode` | How the Topic was formed; see `topics/_template-item.md` |
+| `source_type` | `inbox` \| `user` \| `need` \| `product` \| `recommendation` |
 | `src_*` | **Source post** engagement snapshot — not your publish metrics |
-| `capture_id` | Set only if linked to inbox `C-…` |
+| `capture_id` | Set only if linked to inbox `C-…`. **Never** put `N-` here; needs live on the item as `need_ids` |
+| `need_ids` | Audience evidence cited by the Topic; demand evidence, not product proof |
+| `product_ids` | Optional product facts cited by the Topic |
+| `product_fit` | `direct` \| `adjacent` \| `none`; editorial relevance only |
+| `recommendation_ids` | Optional third-party subjects used for review or comparison |
 | `run` | One or more `RUN-…` ids after open (comma-separated if multi-platform siblings) |
 
 ## Rules
 
 - Max **5** new **`produce`** topics per promotion session
-- Watchlist scan creates **Discovery** first; Topic only after explicit promotion
+- Topics require an explicit user, need, product, recommendation, or profile input.
 - Scout first; never `ready` on high `src_*` or opp_score alone (need audience ≥ 6 too)
 - Scoring: `topics/scoring.md` (opportunity dimensions)
+- Product fit is optional and never replaces Need evidence or opportunity scoring.
 - `记一下` + URL: **inbox first**, not topics, unless user also asks to score as topic
 - On 开一单: append all new run ids to `run`

package/content-engine/starter/topics/_template-item.md

@@ -6,85 +6,98 @@ account: your-handle
 profile: default
 platform: x
 pillar: P1
-source_type: watchlist | inbox | user | discovery
+lane: teach
+generation_mode: demand
+source_type: inbox | user | need | product | recommendation
 purpose: produce | library | discard
 scout_label: demand | ally | foil | craft_only
+capture_id:
+need_ids:
+product_ids: none
+product_fit: none
+recommendation_ids: none
 ---
 
-# Opportunity
+# 选题判断卡
 
-One sentence — what's the content opportunity, not a title.
+> 这是一条准备讨论的内容机会，不是最终发布标题。
 
-## Source
+**结论：** ready | backlog | parked  
+**状态原因：** 一句话说明为什么得到这个结论  
+**适合谁：** 一句话说明具体受众和场景  
+**核心判断：** 一句话说明这条内容真正要讨论什么  
+**下一步：** 开始生成 / 补需求 / 补证据 / 修改角度 / 放弃
+**产品连接：** none | P-… · direct | adjacent · 一句话说明连接方式
+**生成路径：** demand | demand_to_offer | demand_to_review | review | offer_education | profile_thesis
 
-- **type:** watchlist | inbox | user | discovery
-- **url:**
-- **handle:**
-- **discovery_id:** (only if promoted from D-…; else empty)
-- **capture_id:** (only if linked to inbox; else empty)
-- **raw:** (only if exists)
-- **engagement snapshot:** likes / replies / bookmarks / views @ time
+## 这条内容要解决什么问题？
 
-## Scout
+用 2–4 句话说明现实问题。不要复述标题。
 
-- **purpose:** produce | library
-- **scout_label:** demand | ally | foil | craft_only
-- **scout_note:** (one line — why not discard)
+## 他们现在相信什么？
 
-## Context
+写出受众当前的错误判断或困惑。
 
-- **what_changed:**
-- **why_now:**
+## 我们准备讲哪一刀？
 
-## Audience
+说明我们的独特角度，不写完整标题，也不要把来源内容改写成我们的观点。
 
-- **who:**
-- **current_belief:**
-- **icp_checks:** (pain / buyer shape / wedge — note which hit, from profile)
+## 为什么现在值得讲？
 
-## Conflict
+说明发生了什么变化，以及为什么当前受众需要面对它。不是新闻摘要。
 
-- **old_model:**
-- **new_reality:**
-- **belief_gap:**
+## 看完后应该改变什么？
 
-## Insight
+用“之前 → 之后”表达用户认知或行动上的变化。
 
-- **potential_insight:**
-- **why_nonobvious:**
+## 凭什么这么判断？
 
-## Evidence
+用人话列出 Needs、Product、Recommendation、Capture 或其他依据。
 
-- **available:**
-- **type:** data | example | case | mechanism | expert | observation
-- **gaps:**
+## 当前缺口
 
-## Score (opportunity)
+还缺什么需求证据、案例、用户反馈或产品事实。没有缺口就写“无”。
 
-| dim | score 0-10 | note |
-|-----|------------|------|
-| context | | |
-| audience | | |
-| conflict | | |
-| insight | | |
-| evidence | | |
+## 建议形式
 
-**opp_score:** (weighted per `topics/scoring.md`)  
-**audience_floor:** (hard check ≥ 6)
+平台、Lane 和推荐内容形式。暂时不写完整脚本。
 
-## Profile fit
+---
+
+## 评分与追踪附录
+
+以下内容服务于复核、机器读取和后续交接，不是主阅读面。
+
+### Score
+
+Numbers only. Do not repeat the card above in a note column.
+
+| dim | 0–10 |
+|-----|------|
+| context | |
+| audience | |
+| conflict | |
+| insight | |
+| evidence | |
 
-- pillars:
-- audience_pain:
-- risk:
+**opp:** · **aud:** · **verdict:**
 
-## Suggested production (optional, not binding)
+### Trace
 
+- source:
+- capture_id: (inbox `C-…` only)
+- need_ids:
+- product_ids:
+- product_fit:
+- recommendation_ids:
+- lane:
+- generation_mode:
+- raw:
+- src: likes / replies / bookmarks / views @ time
 - swipe: none | S…
 - atoms: none | …
 - claim: none | C…
 
-## Decision
+### Constraints
 
-- next: open_run | hold | kill | library_ingest | research_evidence
-- run_id: (filled when promoted)
+Writer must-nots. Keep short. Empty is allowed.

package/content-engine/starter/topics/scoring.md

@@ -14,7 +14,9 @@ Scores whether a topic **deserves to exist as content**, not whether it can be w
 ## Pipeline (do not skip)
 
 ```text
-watchlist / inbox / url / discovery signal
+Needs / Products / Recommendations → editorial judgment
+  → user accepts
+inbox / url / need / user idea
   → 0) Hard filters
   → 1) Scout gate (purpose + label)     ← most signals die here
   → 2) Opportunity five-dim score        ← only for produce candidates
@@ -24,7 +26,23 @@ watchlist / inbox / url / discovery signal
 
 Library-only signals may skip (2)–(3) — see Scout purposes below.
 
-Watchlist scans create **Discovery** records first. Topic scoring runs only after the user explicitly promotes a Discovery (or names another explicit input).
+Topic scoring runs only after an explicit input and editorial judgment. Product or recommendation fit is context, not evidence of audience demand.
+
+Need match (`need_ids` non-empty) → default `scout_label=demand`. Do not create an `N-` from a product claim or headline.
+
+Product fit is a separate optional annotation:
+
+```text
+Needs = demand evidence
+Products = offer facts
+Topics = editorial judgment over the evidence
+```
+
+Use `product_ids` only when the Topic honestly connects to an active product
+entry. Use `product_fit=direct` when the Topic addresses a problem the product
+solves, `adjacent` when it builds context without being a pitch, and `none`
+when no product connection is needed. Product fit does not increase a score,
+replace `need_ids`, or make a Topic `ready`.
 
 ---
 
@@ -33,7 +51,6 @@ Watchlist scans create **Discovery** records first. Topic scoring runs only afte
 - Off **profile pillars** (unless user override)
 - Hits audience **Not for** (F4F, pure crypto shill, comment-gate junk as the only substance, etc.)
 - Requires invented personal metrics/experience to write honestly
-- Wrong network for the watchlist row (e.g. X tools on a `tiktok` handle)
 
 ---
 
@@ -84,6 +101,8 @@ Only required for `purpose: produce`. Optional brief notes for `library`.
 **Principle:** these five dimensions answer **"is this worth saying?"** — not "can it be written well?"  
 Presentation concerns (framework, structure, format) belong at Brief stage.
 
+Write reasons in the topic's **readable judgment layer**. The `## Score` table is numbers only — do not duplicate the card in a note column. Verdict (`ready` / `backlog` / `parked`) belongs in the decision summary, then echoed as one line under Score.
+
 | Key | Name | What to judge | Weight |
 |-----|------|---------------|--------|
 | `context` | Context | What changed? Why now? Timing, freshness, relevance to the audience's world | **15%** |
@@ -116,6 +135,15 @@ Score using these checks (note which hit):
 2. **Buyer shape** — who buys/acts matches audience buyer as defined there
 3. **Wedge land** — can honestly teach or contrast toward this account’s product/wedge without inventing claims
 
+If product fit is `direct`, load the cited product entry and verify that the
+Topic's problem and proposed CTA are inside its `Problem`, `Mechanism`, and
+`Not solving` sections. If the product is not needed, score the Topic on its
+audience and wedge without forcing a mention.
+
+**Need-source exception:** when `source_type=need` **and** `need_ids` is non-empty, matching **at least one need gloss** counts as one strong audience check. Do **not** require a full ICP (`audience.md` / `pillars.md` may still be hypothesis). Non-need sources do not get this exception. `ready` is still `opp_score ≥ 7.5` **and** `audience ≥ 6`.
+
+Needs default `scout_label=demand`. Still pass hard filters. `frequency ≥ 3` may strengthen context `why_now`; do **not** fold it into `src_*`.
+
 | Range | Guide |
 |-------|-------|
 | 8–10 | ≥2 checks strong; clear buyer + pain |
@@ -131,7 +159,7 @@ Score using these checks (note which hit):
 | 5–7 | Some tension but the gap is soft or already widely acknowledged |
 | 0–4 | No real conflict; topic is an observation or list with nothing to challenge |
 
-When scoring, the agent must write the `current_belief` and `belief_gap` on the topic item — not just a score. If you can't articulate what the audience currently believes wrong, the conflict score cannot be above 5.
+When scoring, write the false belief and the gap once under 「他们现在相信什么」 — not just a score, and not a second time in the Score table. If you can't articulate what the audience currently believes wrong, the conflict score cannot be above 5.
 
 **Insight (25%)**
 
@@ -149,6 +177,29 @@ When scoring, the agent must write the `current_belief` and `belief_gap` on the
 | 5–7 | Evidence exists but generic or secondhand |
 | 0–4 | No evidence beyond assertion; "experts say" with no expert named |
 
+A verbatim need quote is `observation` evidence. List the quote (or a paraphrase **and** the `N-` id) under `## Evidence.available`. Without an `N-` / `C-` / user-lived experience, evidence cannot be above 5. Mechanism / lived experience is still required to reach 8–10.
+
+Product documentation is evidence of what the product does, not evidence that
+the audience wants it. Do not use a product entry to manufacture a Need or to
+raise the audience score.
+
+### Generation-mode gates
+
+Before scoring, set the smallest honest `generation_mode`:
+
+| mode | Required |
+|------|----------|
+| `demand` | `need_ids` + Profile |
+| `demand_to_offer` | `need_ids` + `product_ids` + Profile |
+| `demand_to_review` | `need_ids` + `recommendation_ids` + Profile |
+| `review` | `recommendation_ids` + named evidence + Profile |
+| `offer_education` | `product_ids` + product mechanism + Profile |
+| `profile_thesis` | Profile + Pillar |
+
+Do not use `review` when the only evidence is vendor marketing. Review entries
+must state limitations, research date, and commercial disclosure where
+relevant. Product-only and recommendation-only inputs do not imply demand.
+
 When `evidence < 5`, agent should flag an **evidence gap** on the topic item and may suggest **research** before finalizing the score. Topics can be re-scored after research fills the gap.
 
 ---