@gobing-ai/knowledge-kit 0.1.14 → 0.1.15

package/plugins/kk/skills/news-editorial/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: news-editorial
+description: >-
+  Use the news-editorial skill for the editorial judgement of a daily news episode — "curate today's
+  news pool", "write the episode script plan", "fix the script plan against these validator errors",
+  "apply the daily news style contract". Owns selection and topic boundary, ordering, the balance of
+  news, opinion and technical detail, and the style contract. Modes: curate | write | write --fix.
+requires: [cli:kk, local-fs]
+---
+
+# news-editorial — daily news editorial policy (curate | write | write --fix)
+
+## Purpose
+
+This skill holds every editorial judgement for a daily news episode: which items to keep, in what order, how
+much opinion and technical detail each gets, and how the spoken words read. Everything deterministic stays
+in code and is **out of scope**: collection and store extraction (`kk store extract`, `decisions/extract/*.yaml`),
+score thresholds (`daily-qc-content`), the VoiceScript builder (fixed greeting and sign-off), validators,
+duration gates, TTS, images and publishing (ADR-045).
+
+A workflow reaches this skill through the run snapshot `<work_dir>/20-editorial/news-editorial/` (written by
+`kk stage daily-script-style`). Read files relative to the `SKILL.md` you were pointed at; do not rely on skill
+discovery.
+
+## Invocation contract
+
+`<mode> [--fix <errors.json>] --in <input> --out <output>`. The calling prompt supplies the paths. Write only
+`--out`, as a single valid file (JSON with no comments or trailing commas). Never edit the input.
+
+| Mode | Input → output | Status |
+|---|---|---|
+| `curate` | QC candidates `Doc[]` → kept translated `Doc[]` (`--out-plan`) + exclusions (`--out-excluded`) | Wired (`curate`, policy: `references/selection.md`) |
+| `curate --fix` | QC candidates `Doc[]` + curate validator errors (`--fix`) → corrected plan + exclusions | Wired (`curate-fix`) |
+| `write` | translated plan `Doc[]` + exclusions (`--excluded`) → master script plan JSON | Wired (`script-write`) |
+| `write --fix` | plan `Doc[]` + previous script plan + validator errors → corrected master script plan | Wired (`script-write-fix`) |
+
+## Shared rules (every mode)
+
+Read `references/style-contract.zh.md` first. Its prose sets the column's identity and the balance of news,
+opinion and technical detail. Its fenced `json` block holds the caps and banned phrases that the dailynews-gen
+validator enforces mechanically, so violating them means the plan is rejected.
+
+1. **News first.** Every item tells the listener who (company, lab, team) did what (released, open-sourced,
+   raised, sued, disclosed) and when. Commentary is restrained and anchored to that item; technical detail is
+   only the one or two sentences needed to understand it.
+2. **Topic boundary (选题边界).** Never retell an item whose mainline is politics or diplomacy, trade controls,
+   military affairs, public-policy disputes or social public events, whatever nickname it travels under. Exclude
+   it with a Chinese reason. In-scope industry and institutional news is reported normally.
+3. **Fact discipline.** Every fact comes from that item's own plan content. Do not invent anything or borrow
+   from other items. Never inflate numbers or actors. Attribute a quote only to its original speaker. Keep
+   hedges (据报道 / 称 / 承诺). If the material is thin, write less.
+4. **Copy discipline.** Use reader-facing spoken Chinese. Do not use scaffold labels (可做角度 / 背景 /
+   潜在影响) or hedge labels (读者宜另行核实 / 仍待验证), use 「」 for quotes, and never add a greeting,
+   sign-off or AI-production footer. The builder adds those.
+
+## Mode: write
+
+Read the curated plan `Doc[]` (`--in`) and the curate exclusions (`--excluded`). For each doc in `--in`, write:
+
+- `lead`: one spoken bridge into the item (≤80 chars). It is not the title and not a rhetorical question.
+- `insight`: 2–4 sentences (≤380 chars) anchored to the doc's named actors, saying why it matters or what to watch. Never restate the doc's facts, numbers or phrasing (the listener has just heard them), give no generic advice or methodology, and add no new facts. The cap is a ceiling, not a target.
+- `card`: optional per-item card slot `{ "copy": "≤12字标题", "points": ["要点1", "要点2"], "subject": "English visual scene" }` (2–4 points).
+
+At the episode level, write:
+
+- `intro` (≤150 chars): names the top two or three concrete in-scope developments.
+- `outro` (≤150 chars): a short close tying the items together.
+- `excluded`: copy the array from `--excluded` (`21-plan/<date>_03_curate_excluded.json`) verbatim so the script plan records every dropped candidate with its Chinese reason.
+- `cover` (≤240 chars): one concrete visual scene in English for the lead item (objects, settings, symbols, metaphor; no text, letters, numbers, logos, flags, or recognizable people).
+- `cards`: `{ "title": "≤20字总标题", "body": "中文导语段落 + 3-5个话题标签" }` for the episode card series.
+- `social`: `{ "short": "≤140字 X/Threads 短帖", "long": "≤500字 微博/LinkedIn 长帖" }` (plain text, no markdown headings, no emoji spam, grounded in the plan).
+
+Output:
+
+```json
+{
+  "version": 1,
+  "intro": "…",
+  "outro": "…",
+  "cover": "…",
+  "cards": { "title": "…", "body": "…" },
+  "social": { "short": "…", "long": "…" },
+  "items": [
+    {
+      "id": "…",
+      "lead": "…",
+      "insight": "…",
+      "card": { "copy": "…", "points": ["…", "…"], "subject": "…" }
+    }
+  ],
+  "excluded": [{ "id": "…", "reason": "…" }]
+}
+```
+
+Every doc id in `--in` appears in `items`, and `excluded` carries the curate exclusions; no id may appear in both.
+
+## Mode: write --fix
+
+Inputs: the plan `Doc[]`, the previous script plan, and `--fix <errors.json>` (`[{itemId, rule}]` from the
+validator). Change only what the errors name and copy everything else unchanged. Fix by rule:
+
+| Rule | Fix |
+|---|---|
+| `cap:<field>` | Shorten that field (`intro`, `outro`, `lead`, `insight`, `cover`, `cardCopy`, `cardTitle`, `socialShort`, `socialLong`) below its cap in the contract. Cut opinion, not the actor |
+| `banned:<phrase>` | Rephrase without the phrase (applies to spoken, card and social fields alike) |
+| `redundant-insight` | Rewrite the insight as commentary; drop the restated facts |
+| `duplicate-insight` | Make each insight specific to its own item |
+| `missing-item` / `unknown-id` / `conflict-id` | Make `items` match `--in` and `excluded` match `--excluded` with no overlap |
+| `schema` / `missing-plan` | Write the full master plan per mode `write` |
+
+## Mode: curate / curate --fix
+
+See `references/selection.md`. Reads QC candidates (`--in`) and writes two JSON files:
+1. `--out-plan` (`21-plan/<date>_03_plan_plan.json`): bare `Doc[]` of **kept** items only, in editorial order (lead first), with `title`, `body` and `metadata.brief` adapted into spoken simplified Chinese.
+2. `--out-excluded` (`21-plan/<date>_03_curate_excluded.json`): `[{"id":"<Doc.id>","reason":"<具体中文原因>"}]` for every dropped candidate (`[]` when none dropped). Every candidate id must land in **exactly one** of the two files.
+
+With `--fix <errors.json>` (`missing-plan`, `invalid-json`, `unknown-id`, `missing-item`, `conflict-id`, `empty-plan`), repair the partition so every candidate id is accounted for exactly once and at least one in-scope item is kept.
+
+## References
+
+- `references/style-contract.zh.md`: the column's style contract and machine block (caps, banned).
+- `references/selection.md`: curate policy (boundary, ordering, depth budget, translation).

package/plugins/kk/skills/news-editorial/references/selection.md

@@ -0,0 +1,47 @@
+# Curate policy
+
+`curate` turns the QC candidates into the episode plan. The deterministic gates have already run before it:
+store thresholds (`decisions/extract/ai-news.yaml`), the QC score floors and the minimum item count
+(`daily-qc-content`). Curate adds judgement, not new numeric thresholds.
+
+## Keep or drop
+
+- Drop items that cross the topic boundary (SKILL.md shared rule 2) and give a specific Chinese reason.
+- Drop low-value items (pure PR fluff, minor point-release changelogs with no architectural or developer impact, thin stubs with no verifiable actor/action) and give a specific Chinese reason.
+- Merge near-duplicates (the same event from two sources) into the item with the richer facts; drop the duplicate id into `--out-excluded` with a Chinese reason (e.g., `与另一条候选同属一事，已合并至信息更完整条目`). Never let the same story be spoken twice.
+- Keep everything else that has a concrete actor and action. An opinion thread or tutorial with no news event
+  stays only when the day is thin, and goes after the news items.
+
+## Output invariant (two files)
+
+`curate` writes two JSON files:
+1. `--out-plan` (`21-plan/<date>_03_plan_plan.json`): a bare `Doc[]` array containing **only the kept docs**, ordered with the day's lead news item first, with `title`, `body` and `metadata.brief` adapted into spoken simplified Chinese.
+2. `--out-excluded` (`21-plan/<date>_03_curate_excluded.json`): `[{ "id": "<Doc.id>", "reason": "<具体中文原因>" }]` for every dropped candidate (`[]` when nothing is dropped).
+
+Every candidate `id` from `21-plan/<date>_04_quality-control-content_candidates.json` (`metadata.docs`) must land in **exactly one** of the two files — never both (`conflict-id`), never neither (`missing-item`), and with no invented ids (`unknown-id`).
+
+## Order and balance
+
+1. Lead with the day's most consequential concrete news (urgency × impact), not the most technical item.
+2. Mix categories (industry, research, tools) instead of running three reddit technical threads in a row.
+3. Episode length comes from item count and complete facts, not from long commentary. The style contract
+   gives the per-driver character rates. If kept items cannot reach the floor, keep more in-scope items rather
+   than padding.
+
+## Spoken Chinese adaptation
+
+For kept items (especially those marked `needsTranslation`), adapt `title`, `body` and `metadata.brief` into spoken simplified Chinese:
+
+- Keep every fact, number, name, quote and hedge. This is a full-length spoken adaptation, not a summary;
+  the body is about 0.6–0.7× the source.
+- Shrink generic background or concept explainers to one sentence.
+- Titles read as news. Keep product and model names and body URLs verbatim, and use 「」 for quotes.
+- Keep `id`, `sourceUri`, `mediaType` and `metadata` as they are.
+
+## Mode: curate --fix
+
+When `daily-curate-check` writes `21-plan/<date>_03_curate_errors.json` (`[{ "itemId": "...", "rule": "..." }]`), inspect the rules and rewrite both `--out-plan` and `--out-excluded`:
+- `missing-plan` / `invalid-json` / `empty-plan`: write a valid non-empty `Doc[]` to `--out-plan` and valid `[{id, reason}]` to `--out-excluded`.
+- `missing-item`: add the missing candidate id either to `--out-plan` (translated) or to `--out-excluded` (with a Chinese reason).
+- `conflict-id`: remove the id from one of the two files so it appears in only one.
+- `unknown-id`: remove any id that does not exist in `candidates.json`'s `metadata.docs`.

package/plugins/kk/skills/news-editorial/references/style-contract.zh.md

@@ -0,0 +1,99 @@
+# 每日AI乱炖 · 主持风格契约（zh）
+
+`kk-daily-ai-voice` 的每一句口播都受这份契约约束（F613 R1；0189 R1 改定位；2026-10-08 改名；ADR-045 起归
+`kk:news-editorial` 技能所有）。`write` 模式与 `dailynews-gen` 的校验器读取同一份机器可读块，因此提示词与
+校验永远一致。
+
+## 栏目定位
+
+「每日AI乱炖」是「咸话咸说」下的 AI 技术分享栏目，完整名称「咸话咸说之每日AI乱炖」，副题
+「工具、论文与实践随聊」。栏目名突出当天，不是把节目名当成说话人。口播是开发者视角的 AI
+行业动态与技术分享：先让听众及时知道谁、在何时、发布/宣布/披露了什么，再给克制的点评。
+不以任何代称、绰号或「闲聊」包装政治、外交、军事、公共政策争议或社会公共事件主线的内容——
+这类条目在选题/QC 阶段就应被排除（0189 R2）；选题边界之内的行业动态与机构信息照常播报。身份与
+经历必须真实：只讲真实做过的实测与实践。制作方式由栏目设置说明，口播、正文和 show notes
+不要再附「文字由 AI 辅助整理，音频为 AI 合成配音」或「本期音频为 AI 合成配音」。
+
+## 人设与语域
+
+- 口语化普通话，第一人称「我」，像一位冷静、有依据的 AI 技术分享主播。
+- 平实、克制、不炒作：不夸大单一消息的意义，不使用惊叹式渲染或营销话术。
+- 面向普通听众说明「这件事为什么重要」或「怎么用得上」，而不是堆砌术语。
+
+## 新闻性、点评与技术细节的平衡（2026-11-08）
+
+2026-11-02 起执笔模型换成 codex-sol 后，成稿漂向「主题化议论 + 泛化建议 + 底层细节」，新闻性
+明显下降。三者按以下比例取舍：
+
+- 新闻性优先：每一条都要让听众听清主体（公司/机构/团队）、动作（发布、开源、融资、诉讼、
+  披露……）和时间；导语与桥段点名具体主体和产品，不把当天新闻改写成抽象议题。
+- 点评克制：每条点评约占该条口播的四分之一到三分之一，锚定这一条的具体主体与事实，说清
+  「为什么重要」或「接下来看什么」即可；不写脱离新闻的方法论、选型指南、采购清单或「我的判断
+  标准是……我建议……」式说教，不连用多个「我会/我建议/我倾向」。
+- 技术细节点到为止：只保留听懂这条新闻所需的一两句机制说明；通用概念（如什么是 HTTP 请求头、
+  KV cache）不展开科普，参数、基准、实现细节择其最关键的一两个。
+- 不重复：同一事实在一条里只讲一次。
+
+## 固定开场与收尾
+
+开场问候与收尾致谢由 builder 固定输出，计划文本只填充两者之间的内容，节目身份永不漂移：
+
+- 开场：`大家好，今天是<日期>。这里是由<主持人>为你带来的咸话咸说之每日AI乱炖。`
+- 收尾：`感谢您的收听，我是<主持人>，祝您拥有充实高效的一天，我们下期节目不见不散！`
+
+## 段落角色
+
+- `intro`：开场导语，点名今天最重要的两三条动态（谁、做了什么），接在固定问候之后，不超过 150 字；不写「今天我想聊聊怎么判断……」式的议题清单。
+- `lead`：一句话口语桥段，引出下一个主题的【标题】；只做铺垫，不得复述标题本身，不用设问句把新闻改写成抽象问题，不超过 80 字。
+- `insight`：只基于这一条自身可核事实的点评（2–4 句），说清这一条对行业或开发者的意义、或接下来值得关注的节点；不得挪用其他条目的话题，不超过 380 字（这是上限不是目标，常规 150–280 字）。听众刚听完这一条的事实叙述，insight 是点评不是复读：不得复述正文已讲过的事实、数字或成串措辞（最多点到一两个关键词）；也不得脱离这条新闻泛泛讲方法论或给通用建议。时长契约：全片按 15–20 分钟口播设计，时长靠覆盖更多条目和完整的事实叙述撑起，不靠拉长点评。字数按配音驱动折算：gemini ≈3.3 字/秒（正文约 4300–5800 字）；Voicebox robin-news ≈6.3 字/秒（正文约 5700–7600 字，或增加条目数）。
+- `outro`：简短收束语，接在固定致谢之前，不超过 150 字。
+- `cover`：头版英文具象视觉场景，不超过 240 字符，不含文字、数字、商标、旗帜或可辨识真人。
+- `cards`：小红书图文笔记总标题 `title`（不超过 20 字）与导语 `body`，单条卡片标题 `card.copy`（不超过 12 字）、2–4 条短要点 `card.points`、英文画面 `card.subject`。
+- `social`：面向 X / Threads 的短帖 `short`（不超过 140 字）与面向微博 / LinkedIn 的长帖 `long`（不超过 500 字）。
+
+## 机器可读契约
+
+`caps` 是各字段的字数上限；`banned` 是任何计划字段都不得出现的短语——包括旧模板的全部罐头
+点评、旧模板的 首先/接着/最后 开头、0133 的研究脚手架标签与对冲语（校验规则
+`banned:<短语>`），以及 0189 R4 退役的旧栏目名（「每日 AI 资讯」「AI科技漫谈」
+「AI Daily Briefing」）：任何路径都不得让旧新闻定位复活。
+
+```json
+{
+  "caps": {
+    "intro": 150,
+    "outro": 150,
+    "lead": 80,
+    "insight": 380,
+    "cover": 240,
+    "cardCopy": 12,
+    "cardTitle": 20,
+    "socialShort": 140,
+    "socialLong": 500
+  },
+  "banned": [
+    "在各种技术光环背后，正是这样专注而不知疲倦的底层攻坚者，为今天整个大模型生态奠定了最坚实的技术基石。",
+    "这其实释放了一个非常明确的信号：AI竞争的下半场，已经不再只是单纯拼模型参数，更是电力、能源和全栈工业基础设施的硬核较量。",
+    "真正被重新定义的，是硬件层承担的安全与算力责任：把能力做进硅片层更可靠、也更难绕过，但生态锁定的代价需要一起算进去。",
+    "我个人觉得，这次最大的看点是内容创作门槛的再次降低。不过正如团队提到的，如何平衡创作自由与防止低质内容泛滥，会是整个行业接下来最值得观察的关键考题。",
+    "这项进展反映出资本与产业界正在加速形成合力，后续实际业务场景的落地效果非常值得我们持续跟进。",
+    "这项新动态反映出技术演进正在进一步提速，对相关领域的实际影响也非常值得我们持续关注。",
+    "首先",
+    "接着",
+    "最后",
+    "可做角度",
+    "背景",
+    "潜在影响",
+    "读者宜另行核实",
+    "仍待验证",
+    "每日AI资讯",
+    "每日 AI 资讯",
+    "今日AI科技漫谈",
+    "AI科技漫谈",
+    "AI Daily Briefing",
+    "我是咸话咸说",
+    "音频为 AI 合成配音",
+    "The audio in this episode is AI-synthesized"
+  ]
+}
+```

package/plugins/kk/skills/publish/SKILL.md

@@ -25,7 +25,7 @@ not add a `kk publish` noun.
 | medium | `medium-pub` | `file-cli` (token API) | `kk executor run medium-pub --in <content.json> --out <result.json>` |
 | wechatmp | `wechatmp-pub` | `file-cli` (`draft/add`) | `kk executor run wechatmp-pub` (default operation `draft`) |
 | x post | `x-pub` | `file-cli` (`POST /2/tweets`) | `kk executor run x-pub` (`options.operation` omitted / `post`) |
-| x article | `x-pub` | `browser` / `script` | `kk executor run x-pub --in <content.json> --out <result.json>` (`options.operation: article`); a missing or expired profile refuses (`ok: false`, naming `profile-check.ts login`) before any window opens |
+| x article | `x-pub` | `browser` / `script` | `kk executor run x-pub --in <content.json> --out <result.json>` (`options.operation: article`); a missing or expired profile refuses (`ok: false`, naming `kk bot login x`) before any window opens |
 | juejin | `juejin-pub` | `browser` / `script` | `kk executor run juejin-pub --in <content.json> --out <result.json>` |
 | infoq | `infoq-pub` | `browser` / `script` | `kk executor run infoq-pub --in <content.json> --out <result.json>` |
 | substack | `substack-pub` | `browser` / `script` | `kk executor run substack-pub --in <content.json> --out <result.json>` (needs `SUBSTACK_PUBLICATION_URL`) |
@@ -43,8 +43,8 @@ credentials. Before the first script-driver run (and after any session expiry),
 headed login, then verify reuse read-only:
 
 ```bash
-bun plugins/publishings/xhs-pub/src/profile-check.ts login   # headed; sign in once in the window
-bun plugins/publishings/xhs-pub/src/profile-check.ts check   # headless; exit 0 = session verified
+kk bot login xhs                                             # headed; sign in once in the window (adapter-verified)
+bun plugins/publishings/xhs-pub/src/profile-check.ts check   # headless; exit 0 = session verified (underlying probe)
 ```
 
 `check` never signs in — with no saved profile it refuses (exit 1) instead of reporting success.

package/plugins/kk/skills/web-automation/SKILL.md

@@ -1,101 +1,253 @@
 ---
 name: web-automation
 description: >-
-  Discover, enhance, and automate web tasks with Playwright (or agent-browser
-  over CDP) — "walk this console and record evidence", "figure out this site's
+  Discover, enhance, and automate web tasks with Playwright, kk bot, or agent-browser
+  over CDP — "walk this console and record evidence", "figure out this site's
   UI", "automate this web flow", "reuse my cached login on <channel>", "check
-  whether my session on <channel> is still valid", "fix this channel's
-  selectors", or when a spur workflow `agent.run` step targets the
-  web-automation skill. Owns method and evidence; transport stays in kk
-  plugins; orchestration is a @gobing-ai/ts-dual-workflow-engine
-  transition-flow (see docs/design/web-automation-engine.md).
-requires: [cli:spur, local-fs]
+  whether my session on <channel> is still valid", "run a browser collection plan",
+  "fix this channel's selectors", or when a spur workflow `agent.run` step targets the
+  web-automation skill. Coordinates with the kk bot session lifecycle and collection
+  substrate. Owns method and evidence; transport stays in kk plugins; orchestration is
+  a @gobing-ai/ts-dual-workflow-engine transition-flow (see docs/design/web-automation-engine.md).
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # web-automation — discover, enhance, automate with a real browser
 
 ## Purpose
 
-Three operations over one method: drive a **real Chromium on the channel's
-cached login profile**, record **evidence** (screenshots, DOM signals, JSON),
+Three operational lenses over one unified browser automation architecture: drive a **real Chromium on the named bot's
+cached login profile**, record **verifiable evidence** (screenshots, DOM signals, JSON responses),
 and never report an outcome that was not observed.
 
-| Operation | When | Output |
-| --- | --- | --- |
-| **discover** | new/changed site; "figure out this UI" | evidence dir + drift list (`docs/design/<channel>-ui-discovery.md` convention) |
-| **enhance** | selectors/signals drifted; a plugin or workflow fails on a live console | fixed selectors/signals in the owning plugin + updated discovery doc, same commit |
-| **automate** | a repeatable web task (login-gated save/draft/fill/read) | workflow-driven run with per-step Result/evidence; draft-safe by default |
+| Operation | When | Tier & Substrate | Output |
+| --- | --- | --- | --- |
+| **discover** | New/changed site; "figure out this UI", inspect selectors/shadow roots | **Tier 3** (`kk bot open` + CDP/Playwright) | Evidence dir (`frames/`, `signals.json`) + drift list (`docs/design/<channel>-ui-discovery.md`) |
+| **enhance** | Selectors drifted; a plugin or collection plan fails on a live console | **Tier 2 / 3** (`kk bot exec`, probe script) | Root-cause fix in plugin + updated discovery doc in same commit |
+| **automate** | Repeatable web task (data collection, form fill, draft save, health audit) | **Tier 1 / 2** (`kk bot exec`, `runBotCollection`) | Bounded Result + captured artifacts (draft-safe by default, fail-closed) |
 
-This skill owns **method**. It does not own transport (that is the
-`kind: publish`/`ingestion` plugins) or orchestration (that is the engine —
-`spur workflow` runs `@gobing-ai/ts-dual-workflow-engine`; see
-`docs/design/web-automation-engine.md` for the layering and the YAML).
+This skill owns **method**. It does not own transport (that belongs to `kind: publish` / `ingestion` plugins) or orchestration
+(that is the engine — `spur workflow` running `@gobing-ai/ts-dual-workflow-engine`; see `docs/design/web-automation-engine.md`).
 
-## Cached login (`auth: cached` — the default)
+---
+
+## The 3-Tier Web Automation Model
+
+To keep workflows clean, safe, and robust against anti-bot friction, all web automation tasks follow a strict 3-tier hierarchy:
+
+```text
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ Tier 1: Session & Probe Gateway (kk bot CLI)                                  │
+│   • Profile inventory & expiry estimates: kk bot list                        │
+│   • Headed login & transactional staging:  kk bot login <channel>            │
+│   • Single-request authenticated queries:  kk bot exec <name> <url>          │
+│   • Local credential wipe:                 kk bot logout <name>              │
+└──────────────────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ Tier 2: Declarative Headless Automation (kk bot plan / bot-collection)       │
+│   • Canonical CLI runner: kk bot plan <bot> <plan.json> [-o <dir>] [-m <sec>]│
+│   • Bounded multi-step JSON plans (navigate, wait, click, scroll, extract)   │
+│   • Declarative network response captures (responses: [{pathPrefix}])        │
+│   • Single profile lease + single headless context launch                    │
+│   • Fail-closed errors: authentication (auth walls) vs empty vs browser      │
+│   • Programmatic runner: runBotCollection in @gobing-ai/publish-harness      │
+│   • Low-level probe tool: bun packages/publish-harness/scripts/bot-collection-probe.ts │
+└──────────────────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ Tier 3: Deep Interactive Automation (Playwright / CDP under withProfileLease)│
+│   • Headed visual inspection & interaction: kk bot open <name> [--login]     │
+│   • File uploads (setInputFiles) & shadow-root coordinate clicks via CDP     │
+│   • Live DOM accessibility dumps & interactive selector reverse-engineering  │
+│   • Strict lease enforcement: withProfileLease prevents concurrent corruption │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Tier 1: Session & Profile Lifecycle (`kk bot`)
+
+All browser sessions live under the fixed default root:
+
+```text
+~/.config/kk/browser-profiles/<name>       # persistent profiles (xhs, infoq, juejin, substack, x, wechatmp, etc.)
+~/.config/kk/browser-transactions/         # crash-safe staging and atomic promotion for logins
+~/.config/kk/browser-leases/               # shared lease locks preventing concurrent profile corruption
+```
+
+### CLI Command Reference
 
-Login state is cached **per channel** as a persistent Playwright profile dir —
-cookies, localStorage, and session live on disk outside git:
+| Command | Purpose | Input / Options | Behavior |
+| --- | --- | --- | --- |
+| `kk bot list` | Inventory | None | Prints tab-separated columns: `name`, `cached`, `defaultUrl`, `identity`, `lastLogin`, `expires`. Browser-free. |
+| `kk bot login <channel>` / `<url> --save <name>` | Fresh authentication | Channel name or URL (`--save <name>`) | Opens headed in isolated staging; saves adapter-verified evidence or waits for operator confirmation; promotes atomically. |
+| `kk bot open <name> [--login]` | Inspection | Bot name (`--login` optional) | Opens saved default URL headed until operator closes browser. `--login` re-authenticates first. |
+| `kk bot logout <name>` | Wipe credentials | Bot name | Deletes local profile directory behind shared lease. Idempotent. |
+| `kk bot exec <name> <url> [opts]` | Authenticated HTTP | `-X`, `-H`, `-d`, `-o`, `-i`, `-L`, `-f`, `-m` | One headless persistent launch; sends request with profile's cached cookies; writes body as raw bytes. |
+| `kk bot plan <name> <plan.json> [opts]` | Declarative Collection | `-o, --output <dir>`, `-m, --max-time <sec>` | Headless persistent launch under shared lease; runs declarative plan steps and captures; writes artifacts or prints JSON result. |
 
+### Session Preflight & Health Check
+
+Before triggering automated runs, perform a fast probe. Age-guessing timestamps is banned — probe, don't predict:
+
+```bash
+# 1. Check local profile inventory
+kk bot list
+
+# 2. Lightweight authenticated query probe (returns status + headers)
+kk bot exec <channel> <console-url> -i -m 15 -o /tmp/probe.txt
+
+# 3. If expired or unauthenticated (HTTP 401/403 or redirect to login):
+kk bot login <channel>
 ```
-~/.config/kk/browser-profiles/<channel>   # xhs, infoq, juejin, substack, x, wechatmp
+
+---
+
+## Tier 2: Declarative Headless Automation (`bot-collection`)
+
+For data collection, scraping, site audits, and structured form workflows, **do not write ad-hoc Playwright scripts**.
+Use the declarative `@gobing-ai/publish-harness/bot-collection` substrate:
+
+```ts
+import { runBotCollection } from '@gobing-ai/publish-harness/bot-collection';
+
+const result = await runBotCollection('wechatmp', {
+    steps: [
+        { id: 'nav-home', kind: 'navigate', url: 'https://mp.weixin.qq.com/' },
+        { id: 'wait-dashboard', kind: 'wait', selector: '.weui-desktop-layout', timeoutMs: 15_000 },
+        { id: 'extract-stats', kind: 'extract', selector: '.weui-desktop-mass__item', format: 'text' },
+    ],
+    responses: [
+        { id: 'appmsg-list', pathPrefix: '/cgi-bin/appmsg' },
+    ],
+    timeoutMs: 30_000,
+});
 ```
 
-| `auth` | Behavior |
-| --- | --- |
-| `cached` (default) | Preflight the profile; reuse it read-only. Launch with `launchPersistentContext` (see `references/browser-launch.md`). No credentials are typed, read, or stored by any script. |
-| `fresh` | Profile missing/expired → **headed** launch, operator completes login by hand (QR/OAuth/password), then the profile is the cache again. Never auto-type credentials; OAuth gates need the stealth args. |
+### Plan Grammar (`BotCollectionPlan`)
+
+A plan is a frozen JSON object with `steps[]`, optional `responses[]` captures, and an optional whole-run `timeoutMs`:
+
+- **`navigate`**: `{ id, kind: 'navigate', url, waitUntil?: 'load'|'domcontentloaded'|'networkidle'|'commit' }`
+- **`wait`**: `{ id, kind: 'wait', selector?, timeoutMs? }`
+- **`click`**: `{ id, kind: 'click', selector, timeoutMs? }`
+- **`scroll`**: `{ id, kind: 'scroll', deltaY, selector?, timeoutMs? }`
+- **`extract`**: `{ id, kind: 'extract', selector, format: 'text'|'html'|'count', timeoutMs? }`
+- **`request`**: `{ id, kind: 'request', url, method?: 'GET'|'POST', headers?, data? }`
+- **`responses`**: `[{ id, origin?, pathPrefix, optional?: boolean }]`
 
-Preflight before any drive — cheap and headless:
+### Fail-Closed Integrity Rules
+
+- **`authentication`**: Fails immediately when an explicit 401/403 occurs on a request, navigation, or required response, or when the final navigation URL path matches `/login|signin|sign-in|auth|sso/i`. Action: alert operator to run `kk bot login <channel>`.
+- **`empty`**: Fails immediately when a declared non-optional capture receives no response, or an `extract`/`request` step yields an empty body. Prevents client-side rendered SPA shells from masquerading as a successful quiet run.
+- **`browser`**: Transport faults, timeouts, navigation drops, and DOM exceptions.
+
+### Running Plans via CLI (`kk bot plan`)
+
+Execute a collection plan directly from the terminal or a workflow script:
+
+```bash
+# Run plan and stream JSON result to stdout
+kk bot plan <channel> <path/to/plan.json> -m 60
+
+# Run plan and write 0600 artifact files + result.json / error.json into output dir
+kk bot plan <channel> <path/to/plan.json> -o <path/to/evidence-dir> -m 60
+```
+
+Exit codes: `0` = success, `1` = operational failure (`authentication`, `empty`, or `browser`), `2` = usage error (invalid JSON, missing profile, invalid timeout).
+
+Low-level debugging can also use the repository probe script:
 
 ```bash
-test -d ~/.config/kk/browser-profiles/<channel> && echo cached || echo fresh-required
+bun packages/publish-harness/scripts/bot-collection-probe.ts \
+  --profile <name> \
+  --plan <path/to/plan.json> \
+  --out <path/to/evidence-dir>
 ```
 
-A profile dir existing is necessary, not sufficient: before `automate` runs,
-do a read-only session probe (open the console URL, check a signed-in-only
-selector) and route to `fresh` on failure. Age-guessing timestamps is banned —
-probe, don't predict.
-
-## Method
-
-1. **Launch** — `chromium.launchPersistentContext(profileDir, { headless, args: [CDP port, stealth] })`.
-   Decision table and the exact snippet: `references/browser-launch.md`.
-2. **Discover** — screenshot first, then read DOM (selectors, shadow roots,
-   iframes, counts) with small throwaway scripts; save frames + a signals JSON
-   into the run's evidence dir; write/refresh the channel's
-   `docs/design/<channel>-ui-discovery.md` (selectors, drift list, date).
-3. **Enhance** — diff observed DOM against the plugin's encoded
-   selectors/signals; fix the plugin (root cause — one shared helper, not
-   every caller), re-walk to prove it, update the discovery doc in the same
-   commit.
-4. **Automate** — encode the flow as engine workflow nodes (preflight →
-   launch → drive → verify → record); `drive` steps run the measured
-   selectors and **assert an observed outcome signal** (toast, counter delta,
-   URL change). An unobserved outcome is reported as failure, never success.
-5. **Confidence-verified verdicts** — every outcome verdict carries
-   `confidence: HIGH | MEDIUM | LOW` (HIGH = measured signal observed;
-   MEDIUM = indirect signal, e.g. counter delta without toast; LOW = partial
-   evidence, one check passed). **Missing or out-of-enum confidence is itself
-   a failure** — the verify gate blocks it, mirroring the safety-verdict
-   convention (`kk-daily-ai-voice.md`, 20261003).
-
-## Safety rails (non-negotiable)
-
-- **Never click publish/send/submit/delete** unless the task explicitly
-  authorizes live publishing. Default target: draft/save/暂存.
-- Bot-walled channels (xhs) and fresh logins stay **headed**; headless only
-  after the session is proven.
-- Every reported success cites observed evidence (signal, screenshot, JSON).
-  No evidence → it is a failure with the reason — and every verdict states
-  its `HIGH | MEDIUM | LOW` confidence; a verdict without a valid level
-  fails the gate like a missing verdict.
-- Secrets stay out of repo, YAML, and vars. Login state lives only in the
-  profile dir under `~/.config` (outside git); scripts print paths, never tokens.
-- One browser per channel/profile at a time; close contexts you launched.
-
-## Engine invocation (summary)
-
-Orchestration is a `kind: transition-flow` workflow; `startable` nodes let a
-run re-enter at `drive` after a manual login without redoing earlier nodes.
-Full YAML, node contract, and the option-B (in-process runners) design:
-`docs/design/web-automation-engine.md`.
+---
+
+## Tier 3: Deep Interactive Automation (Playwright / CDP)
+
+When an activity requires capabilities outside Tier 2 — specifically:
+1. **Interactive UI discovery** (navigating unknown layouts, recording screenshots).
+2. **Shadow-root component piercing** (e.g. XHS creator console shadow boundaries).
+3. **File uploads** (attaching images/videos via `page.setInputFiles`).
+4. **Canvas / complex coordinate dragging**.
+
+You MUST wrap the run inside the shared profile lease to prevent profile corruption:
+
+```ts
+import { chromium } from 'playwright';
+import { withProfileLease } from '@gobing-ai/publish-harness';
+
+const profileName = 'xhs';
+const profileDir = `${process.env.HOME}/.config/kk/browser-profiles/${profileName}`;
+const port = process.env.KK_WEB_CDP ?? '9222';
+
+await withProfileLease(profileName, async () => {
+    const ctx = await chromium.launchPersistentContext(profileDir, {
+        headless: process.env.KK_WEB_HEADLESS === 'true',
+        viewport: null,
+        args: [
+            `--remote-debugging-port=${port}`,
+            '--disable-blink-features=AutomationControlled',
+        ],
+    });
+    try {
+        const page = ctx.pages()[0] ?? (await ctx.newPage());
+        // Drive page actions, upload files, or attach agent-browser via CDP...
+    } finally {
+        await ctx.close();
+    }
+});
+```
+
+---
+
+## Playbook: Common Automation Scenarios
+
+### Scenario A: Site Discovery & Reverse-Engineering
+1. Check cached session: `kk bot list`.
+2. Open target page headed: `kk bot open <channel>`.
+3. Inspect DOM, capture layout, dump accessibility tree, take screenshots.
+4. Document selectors, shadow roots, and observed signals into `docs/design/<channel>-ui-discovery.md`.
+5. Close window; `kk bot open` outputs `<name>\tclosed`.
+
+### Scenario B: Lightweight Authenticated Scraping
+1. Send direct authenticated request:
+   ```bash
+   kk bot exec <channel> "https://target.com/api/data" -H "Accept: application/json" -o data.json
+   ```
+2. If the endpoint returns client-rendered HTML shell rather than JSON, escalate to **Scenario C**.
+
+### Scenario C: Declarative Headless Data Collection
+1. Draft a `plan.json` with required navigation, waits, and response captures.
+2. Probe run:
+   ```bash
+   bun packages/publish-harness/scripts/bot-collection-probe.ts --profile <channel> --plan plan.json --out .spur/run/evidence
+   ```
+3. Verify `result.json` shows all artifacts captured with non-empty bodies.
+4. Wire into ingestion plugin or workflow.
+
+### Scenario D: Broken Selector Repair (`enhance`)
+1. Replay failing plan or run `kk bot exec`.
+2. Inspect `error.json` / diagnostics (is it `authentication`, `empty`, or `browser`?).
+3. If selector changed, launch `kk bot open <channel>`, observe the updated DOM element.
+4. Update selector in shared helper, re-verify with probe script, commit alongside discovery doc.
+
+---
+
+## Safety Rails (Non-Negotiable)
+
+- **Draft-Safe by Default**: Never click publish/send/submit/delete unless the task explicitly authorizes live actions.
+- **Lease Invariant**: Every browser context touching `~/.config/kk/browser-profiles/<name>` must be acquired through `kk bot`, `runBotCollection`, or `withProfileLease`. Direct un-leased `launchPersistentContext` is banned.
+- **Fail Closed on Quiet Failures**: Missing data and auth walls must fail loud (`authentication` or `empty`). Never treat an empty SPA shell or an auth redirect as a normal quiet response.
+- **Headed vs Headless**:
+  - Headless: Session probes (`kk bot list`), authenticated queries (`kk bot exec`), declarative collection (`runBotCollection`).
+  - Headed: First-time logins (`kk bot login`), interactive discovery (`kk bot open`), and bot-walled platforms (XHS).
+- **Secrets Invariant**: Zero credentials in repo, code, or logs. All state lives exclusively in `~/.config/kk/` outside Git.
+- **Confidence-Verified Verdicts**: Every workflow outcome verdict must declare `confidence: HIGH | MEDIUM | LOW`. Missing or out-of-enum confidence halts execution.