docs: document input governance workflow

README.en.md

@@ -40,7 +40,7 @@ clawhub install inkos          # Install from ClawHub
 
 If you installed via npm or cloned the repo, `skills/SKILL.md` is already included — 🦞 can read it directly without a separate ClawHub install.
 
-Once installed, Claw can invoke all InkOS atomic commands (`draft`/`audit`/`revise`/`write next`) via `exec`, with `--json` output for structured decision-making. You can also browse it on [ClawHub](https://clawhub.ai) by searching `inkos`.
+Once installed, Claw can invoke InkOS atomic commands and control-surface operations (`plan chapter`/`compose chapter`/`draft`/`audit`/`revise`/`write next`) via `exec`, with `--json` output for structured decision-making. The recommended flow is: update `author_intent.md` or `current_focus.md`, run `plan` / `compose`, then decide whether to call `draft` or the full `write next` pipeline. You can also browse it on [ClawHub](https://clawhub.ai) by searching `inkos`.
 
 ### Configure
 
@@ -158,7 +158,23 @@ De-AI-ification rules are baked into the Writer agent's prompts: fatigue word li
 
 ### Creative Brief
 
-`inkos book create --brief my-ideas.md` — pass your brainstorming notes, worldbuilding doc, or character sheets. The Architect agent builds from your brief (generating story_bible.md and book_rules.md) instead of inventing from scratch.
+`inkos book create --brief my-ideas.md` — pass your brainstorming notes, worldbuilding doc, or character sheets. The Architect agent builds from your brief (generating `story_bible.md` and `book_rules.md`) instead of inventing from scratch, and persists the brief into `story/author_intent.md` so the book's long-horizon intent does not disappear after initialization.
+
+### Input Governance Control Surface
+
+Every book now has two long-lived Markdown control docs:
+
+- `story/author_intent.md`: what this book should become over the long horizon
+- `story/current_focus.md`: what the next 1-3 chapters should pull attention back toward
+
+Before writing, you can run:
+
+```bash
+inkos plan chapter my-book --context "Pull attention back to the mentor conflict first"
+inkos compose chapter my-book
+```
+
+This generates `story/runtime/chapter-XXXX.intent.md`, `context.json`, `rule-stack.yaml`, and `trace.json`. `intent.md` is the human-readable contract; the others are execution/debug artifacts. `plan` / `compose` only compile local documents and state, so they can run before you finish API key setup.
 
 ### Continuation Writing
 
@@ -224,11 +240,24 @@ The Continuity Auditor checks every draft against these files. If a character "r
   <img src="assets/screenshot-state.png" width="800" alt="Truth files snapshot">
 </p>
 
+### Control Surface and Runtime Artifacts
+
+Alongside the 7 truth files, InkOS splits guardrails from customization into reviewable control docs:
+
+- `story/author_intent.md`: long-horizon author intent
+- `story/current_focus.md`: near-term steering
+- `story/runtime/chapter-XXXX.intent.md`: chapter goal, keep/avoid list, conflict resolution
+- `story/runtime/chapter-XXXX.context.json`: the actual context selected for this chapter
+- `story/runtime/chapter-XXXX.rule-stack.yaml`: priority layers and override relationships
+- `story/runtime/chapter-XXXX.trace.json`: compilation trace for this chapter
+
+That means briefs, outline nodes, book rules, and current requests are no longer mashed into one prompt blob; InkOS compiles them first, then writes.
+
 ### Writing Rule System
 
 The Writer agent has ~25 universal writing rules (character craft, narrative technique, logical consistency, language constraints, de-AI-ification), applicable to all genres.
 
-On top of that, each genre has dedicated rules (prohibitions, language constraints, pacing, audit dimensions), and each book has its own `book_rules.md` (protagonist personality, numerical caps, custom prohibitions) and `story_bible.md` (worldbuilding), auto-generated by the Architect agent.
+On top of that, each genre has dedicated rules (prohibitions, language constraints, pacing, audit dimensions), and each book has its own `book_rules.md` (protagonist personality, numerical caps, custom prohibitions), `story_bible.md` (worldbuilding), `author_intent.md` (long-horizon direction), and `current_focus.md` (near-term steering). `volume_outline.md` still acts as the default plan, but in v2 input governance it no longer automatically overrides the current chapter intent.
 
 ## Usage Modes
 
@@ -241,15 +270,27 @@ inkos write next my-book              # Draft → audit → auto-revise, all in
 inkos write next my-book --count 5    # Write 5 chapters in sequence
 ```
 
+If you want `write next` to always go through the `plan -> compose -> write` governance chain, set this in `inkos.json`:
+
+```json
+{
+  "inputGovernanceMode": "v2"
+}
+```
+
+The default remains `legacy` so existing projects do not silently change behavior.
+
 ### 2. Atomic Commands (Composable, External Agent Friendly)
 
 ```bash
+inkos plan chapter my-book --context "Focus on the mentor conflict first" --json
+inkos compose chapter my-book --json
 inkos draft my-book --context "Focus on the dungeon boss encounter and party dynamics" --json
 inkos audit my-book 31 --json
 inkos revise my-book 31 --json
 ```
 
-Each command performs a single operation independently. `--json` outputs structured data. Can be called by external AI agents via `exec`, or used in scripts.
+Each command performs a single operation independently. `--json` outputs structured data. `plan` / `compose` govern inputs; `draft` / `audit` / `revise` handle prose and quality checks. They can be called by external AI agents via `exec`, or used in scripts.
 
 ### 3. Natural Language Agent Mode
 
@@ -259,7 +300,7 @@ inkos agent "Write the next chapter, focus on the boss fight and loot distributi
 inkos agent "Create a progression fantasy about a mage who can only use one spell"
 ```
 
-13 built-in tools (write_draft, audit_chapter, revise_chapter, scan_market, create_book, get_book_status, read_truth_files, list_books, write_full_pipeline, web_fetch, import_style, import_canon, import_chapters), with the LLM deciding call order via tool-use.
+18 built-in tools (write_draft, plan_chapter, compose_chapter, audit_chapter, revise_chapter, scan_market, create_book, update_author_intent, update_current_focus, get_book_status, read_truth_files, list_books, write_full_pipeline, web_fetch, import_style, import_canon, import_chapters, write_truth_file), with the LLM deciding call order via tool-use. The recommended agent flow is: adjust the control surface first, then `plan` / `compose`, then choose draft-only or full-pipeline writing.
 
 ## CLI Reference
 
@@ -271,6 +312,8 @@ inkos agent "Create a progression fantasy about a mage who can only use one spel
 | `inkos book list` | List all books |
 | `inkos book delete <id>` | Delete a book and all its data (`--force` to skip confirmation) |
 | `inkos genre list/show/copy/create` | View, copy, or create genres |
+| `inkos plan chapter [id]` | Generate the next chapter's `intent.md` (`--context` / `--context-file` for current steering) |
+| `inkos compose chapter [id]` | Generate the next chapter's `context.json`, `rule-stack.yaml`, and `trace.json` |
 | `inkos write next [id]` | Full pipeline: write next chapter (`--words` to override, `--count` for batch, `-q` quiet mode) |
 | `inkos write rewrite [id] <n>` | Rewrite chapter N (restores state snapshot, `--force` to skip confirmation) |
 | `inkos draft [id]` | Write draft only (`--words` to override word count, `-q` quiet mode) |
@@ -293,7 +336,7 @@ inkos agent "Create a progression fantasy about a mage who can only use one spel
 | `inkos analytics [id]` / `inkos stats [id]` | Book analytics (audit pass rate, top issues, chapter ranking, token usage) |
 | `inkos up / down` | Start/stop daemon (`-q` quiet mode, auto-writes `inkos.log`) |
 
-`[id]` is auto-detected when the project has only one book. All commands support `--json` for structured output. `book create` supports `--brief <file>` to pass a creative brief — the Architect builds from your ideas instead of generating from scratch.
+`[id]` is auto-detected when the project has only one book. All commands support `--json` for structured output. `draft` / `write next` / `plan chapter` / `compose chapter` accept `--context` for steering. `book create` supports `--brief <file>` to pass a creative brief — the Architect builds from your ideas instead of generating from scratch. `plan chapter` / `compose chapter` do not require a live LLM, so you can inspect governed inputs before finishing API setup.
 
 ## Roadmap
 

README.md

@@ -40,7 +40,7 @@ clawhub install inkos          # 从 ClawHub 安装 InkOS Skill
 
 通过 npm 安装或克隆本项目时，`skills/SKILL.md` 已包含在内，🦞 可直接读取——无需额外从 ClawHub 安装。
 
-安装后，Claw 可通过 `exec` 调用 InkOS 的所有原子命令（`draft`/`audit`/`revise`/`write next`），`--json` 输出结构化数据供 Claw 解析决策。也可以在 [ClawHub](https://clawhub.ai) 搜索 `inkos` 在线查看。
+安装后，Claw 可通过 `exec` 调用 InkOS 的原子命令和控制面操作（`plan chapter`/`compose chapter`/`draft`/`audit`/`revise`/`write next`），`--json` 输出结构化数据供 Claw 解析决策。推荐流程是先更新 `author_intent.md` 或 `current_focus.md`，再 `plan` / `compose`，最后决定是否 `draft` 或完整 `write next`。也可以在 [ClawHub](https://clawhub.ai) 搜索 `inkos` 在线查看。
 
 ### 配置
 
@@ -128,7 +128,23 @@ inkos export 吞天魔帝 --format epub  # 导出 EPUB（手机/Kindle 阅读）
 
 ### 创作简报
 
-`inkos book create --brief my-ideas.md` 传入你的脑洞、世界观设定、人设文档。建筑师 agent 会基于简报生成故事设定（story_bible.md）和创作规则（book_rules.md），而非凭空创作。
+`inkos book create --brief my-ideas.md` 传入你的脑洞、世界观设定、人设文档。建筑师 agent 会基于简报生成故事设定（`story_bible.md`）和创作规则（`book_rules.md`），而非凭空创作；同时把简报落盘到 `story/author_intent.md`，让这本书的长期创作意图不会只在建书时生效一次。
+
+### 输入治理控制面
+
+每本书现在都有两份长期可编辑的 Markdown 控制文档：
+
+- `story/author_intent.md`：这本书长期想成为什么
+- `story/current_focus.md`：最近 1-3 章要把注意力拉回哪里
+
+写作前可以先跑：
+
+```bash
+inkos plan chapter 吞天魔帝 --context "本章先把注意力拉回师徒矛盾"
+inkos compose chapter 吞天魔帝
+```
+
+这会生成 `story/runtime/chapter-XXXX.intent.md`、`context.json`、`rule-stack.yaml`、`trace.json`。其中 `intent.md` 给人看，其他文件给系统执行和调试。`plan` / `compose` 只编译本地文档和状态，不依赖在线 LLM，可在没配好 API Key 前先验证控制输入。
 
 ### 续写已有作品
 
@@ -194,11 +210,24 @@ inkos export 吞天魔帝 --format epub  # 导出 EPUB（手机/Kindle 阅读）
   <img src="assets/screenshot-state.png" width="800" alt="长期记忆快照">
 </p>
 
+### 控制面与运行时产物
+
+除了 7 个真相文件，InkOS 还把“护栏”和“自定义”拆成可审阅的控制层：
+
+- `story/author_intent.md`：长期作者意图
+- `story/current_focus.md`：当前阶段的关注点
+- `story/runtime/chapter-XXXX.intent.md`：本章目标、保留项、避免项、冲突处理
+- `story/runtime/chapter-XXXX.context.json`：本章实际选入的上下文
+- `story/runtime/chapter-XXXX.rule-stack.yaml`：本章的优先级层和覆盖关系
+- `story/runtime/chapter-XXXX.trace.json`：本章输入编译轨迹
+
+这样 `brief`、卷纲、书级规则、当前任务不再混成一坨 prompt，而是先编译，再写作。
+
 ### 创作规则体系
 
 写手 agent 内置 ~25 条通用创作规则（人物塑造、叙事技法、逻辑自洽、语言约束、去 AI 味），适用于所有题材。
 
-在此基础上，每个题材有专属规则（禁忌、语言约束、节奏、审计维度），每本书有独立的 `book_rules.md`（主角人设、数值上限、自定义禁令）和 `story_bible.md`（世界观设定），由建筑师 agent 创建书籍时自动生成。
+在此基础上，每个题材有专属规则（禁忌、语言约束、节奏、审计维度），每本书有独立的 `book_rules.md`（主角人设、数值上限、自定义禁令）、`story_bible.md`（世界观设定）、`author_intent.md`（长期方向）和 `current_focus.md`（近期关注点）。`volume_outline.md` 仍然是默认规划，但在 v2 输入治理模式下不再天然压过当前任务意图。
 
 ## 使用模式
 
@@ -211,15 +240,27 @@ inkos write next 吞天魔帝          # 写草稿 → 审计 → 自动修订
 inkos write next 吞天魔帝 --count 5 # 连续写 5 章
 ```
 
+如果希望 `write next` 也始终走 `plan -> compose -> write` 的输入治理链路，可在 `inkos.json` 中设置：
+
+```json
+{
+  "inputGovernanceMode": "v2"
+}
+```
+
+默认值仍为 `legacy`，避免旧项目无感升级时直接改变写作行为。
+
 ### 2. 原子命令（可组合，适合外部 Agent 调用）
 
 ```bash
+inkos plan chapter 吞天魔帝 --context "本章重点写师徒矛盾" --json
+inkos compose chapter 吞天魔帝 --json
 inkos draft 吞天魔帝 --context "本章重点写师徒矛盾" --json
 inkos audit 吞天魔帝 31 --json
 inkos revise 吞天魔帝 31 --json
 ```
 
-每个命令独立执行单一操作，`--json` 输出结构化数据。可被外部 AI Agent 通过 `exec` 调用，也可用于脚本编排。
+每个命令独立执行单一操作，`--json` 输出结构化数据。`plan` / `compose` 负责控制输入，`draft` / `audit` / `revise` 负责正文与质量链路。可被外部 AI Agent 通过 `exec` 调用，也可用于脚本编排。
 
 ### 3. 自然语言 Agent 模式
 
@@ -229,7 +270,7 @@ inkos agent "写下一章，重点写师徒矛盾"
 inkos agent "先扫描市场趋势，然后根据结果创建一本新书"
 ```
 
-内置 13 个工具（write_draft、audit_chapter、revise_chapter、scan_market、create_book、get_book_status、read_truth_files、list_books、write_full_pipeline、web_fetch、import_style、import_canon、import_chapters），LLM 通过 tool-use 决定调用顺序。
+内置 18 个工具（write_draft、plan_chapter、compose_chapter、audit_chapter、revise_chapter、scan_market、create_book、update_author_intent、update_current_focus、get_book_status、read_truth_files、list_books、write_full_pipeline、web_fetch、import_style、import_canon、import_chapters、write_truth_file），LLM 通过 tool-use 决定调用顺序。推荐的 Agent 工作流是：先调整控制面，再 `plan` / `compose`，最后决定写草稿还是跑完整管线。
 
 ## 实测数据
 
@@ -259,6 +300,8 @@ inkos agent "先扫描市场趋势，然后根据结果创建一本新书"
 | `inkos book list` | 列出所有书籍 |
 | `inkos book delete <id>` | 删除书籍及全部数据（`--force` 跳过确认） |
 | `inkos genre list/show/copy/create` | 查看、复制、创建题材 |
+| `inkos plan chapter [id]` | 生成下一章的 `intent.md`（`--context` / `--context-file` 传入当前指令） |
+| `inkos compose chapter [id]` | 生成下一章的 `context.json`、`rule-stack.yaml`、`trace.json` |
 | `inkos write next [id]` | 完整管线写下一章（`--words` 覆盖字数，`--count` 连写，`-q` 静默模式） |
 | `inkos write rewrite [id] <n>` | 重写第 N 章（恢复状态快照，`--force` 跳过确认，`--words` 覆盖字数） |
 | `inkos draft [id]` | 只写草稿（`--words` 覆盖字数，`-q` 静默模式） |
@@ -287,7 +330,7 @@ inkos agent "先扫描市场趋势，然后根据结果创建一本新书"
 | `inkos update` | 更新到最新版本 |
 | `inkos up / down` | 启动/停止守护进程（`-q` 静默模式，自动写入 `inkos.log`） |
 
-`[id]` 参数在项目只有一本书时可省略，自动检测。所有命令支持 `--json` 输出结构化数据。`draft`/`write next` 支持 `--context` 传入创作指导，`--words` 覆盖每章字数。`book create` 支持 `--brief <file>` 传入创作简报（你的脑洞/设定文档），Architect 会基于此生成设定而非凭空创作。
+`[id]` 参数在项目只有一本书时可省略，自动检测。所有命令支持 `--json` 输出结构化数据。`draft` / `write next` / `plan chapter` / `compose chapter` 支持 `--context` 传入创作指导，`--words` 覆盖每章字数。`book create` 支持 `--brief <file>` 传入创作简报（你的脑洞/设定文档），Architect 会基于此生成设定而非凭空创作。`plan chapter` / `compose chapter` 不要求在线 LLM，可在配置 API Key 之前先检查输入治理结果。
 
 ## 路线图