docs: refresh README and skill for 1.5

2026-08-28 23:02:03 +08:00 · 2026-06-09 12:38:36 +08:00
parent c26573560f
commit a2d3744aae
8 changed files with 426 additions and 233 deletions
@@ -3,7 +3,7 @@
  <img src="assets/inkos-text.svg" width="240" height="65" alt="InkOS">
 </p>

-<h1 align="center">Autonomous Novel Writing AI Agent</h1>
+<h1 align="center">Local AI Fiction Creation System</h1>

 <p align="center">
  <a href="https://www.npmjs.com/package/@actalk/inkos"><img src="https://img.shields.io/npm/v/@actalk/inkos.svg?color=cb3837&logo=npm" alt="npm version"></a>
@@ -16,7 +16,7 @@
 <p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69mt3v89kkekg24gg">
-    <img alt="Kimi Open Source Friends" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0">
+    <img alt="Kimi Open Source Friends" width="760" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0">
  </picture>
 </p>

@@ -26,15 +26,40 @@

 ---

-Open-source AI Agent that autonomously writes, audits, and revises novels — with human review gates that keep you in control. Supports LitRPG, Progression Fantasy, Isekai, Romantasy, Sci-Fi, and more. Continuation, spinoff, fanfic, and style imitation workflows built in.
+InkOS is a local AI creation system for long-form novels, standalone short fiction, fan fiction, spinoffs, style imitation, continuation, and interactive worlds. Studio Chat, CLI, and TUI share the same action surface, so you can discuss ideas, confirm heavy actions, generate work, preview artifacts, and edit persistent project files from one place.

-**InkOS Studio 2.0 is here!** — run `inkos` to launch the local web workbench. Book management, chapter review & editing, real-time writing progress, market radar, analytics, AI detection, style analysis, genre management, daemon control, truth file editing — everything the CLI does, now visual.
+## v1.5.0 Major Update

-**InkOS TUI is here!** — run `inkos tui` to launch a full-screen interactive dashboard. Conversational creation, natural-language book operations, slash command autocomplete, themed animations — TUI, Studio, and OpenClaw share the same interaction kernel.
+v1.5.0 is less about one isolated feature and more about moving InkOS from a chapter pipeline into a conversational, confirmable, context-aware creation system:

-**InkOS Short** — Studio chat and CLI can now create a standalone short-fiction package: complete draft, outline and review records, synopsis, selling points, cover prompt, and an optional generated cover image when a cover provider is configured.
+- **Instruction following**: Studio Chat, TUI, and CLI natural-language entry points now route through a unified action surface. Plain discussion, book creation, Short, cover generation, Play, and long-form writing are no longer driven by scattered keyword shortcuts. Heavy actions require confirmation, and completion is based on real tool results.
+- **Context management**: Long-form context is split into protected / compressible layers. Semantic compression is used only when the context budget is tight; session history is restored through summaries to reduce old-history drift.
+- **Open world / branching interaction**: InkOS Play adds free actions, clickable choices, world contracts, time flow, character / item / evidence / relationship state, HUD, and optional image generation.
+- **Creation entry points**: Long-form novels, Short, fanfic, spinoffs, style imitation, continuation, and cover generation now have first-class Studio entries instead of being hidden behind CLI-only workflows.
+- **Model and format resilience**: Weak-model formatting failures are less likely to crash a run outright. Provider errors, InkOS execution errors, and image generation failures are surfaced more separately, so debugging is clearer.

-**v1.4.1 Windows provider and long-form speed update** — MiniMax now uses its OpenAI-compatible endpoint by default, long-form writing keeps the faster one-pass repair default while allowing `writing.reviewRetries` to be raised when needed, and the short-fiction / Studio Chat workflow from v1.4 remains available.
+This release broadly improves older pain points: accidental natural-language triggers, "I said one thing, the system did another", long histories overwhelming the current instruction, context-window failures, invisible interactive-world state, and mixed text/image provider errors.
+
+<p align="center">
+  <img src="assets/inkos-short-demo-cover.png" width="210" alt="InkOS Short cover example">
+  <img src="assets/play-openworld-warcraft.png" width="210" alt="InkOS Play fantasy open-world example">
+  <img src="assets/play-openworld-romance.png" width="210" alt="InkOS Play romance example">
+  <img src="assets/play-openworld-detective.png" width="210" alt="InkOS Play detective example">
+</p>
+
+**Long-form novels** — create from a brief, generate foundations, chapter intent, context packages, prose, review, revision, and state settlement. Context is governed with protected / compressible layers so long books remain steerable.
+
+**InkOS Short** — Studio chat and CLI can create a complete standalone short-fiction package: full manuscript, outline records, review records, synopsis, selling points, cover prompt, and an optional cover image when a cover provider is configured.
+
+**InkOS Play** — build open worlds or branching interactive fiction from natural-language world contracts: time flow, character agents, inventory, evidence, relationships, scene state, visual rules, guided choices, free actions, and optional image generation.
+
+**Studio Chat** — a persistent chat surface for answering questions, proposing actions, creating books, launching Short / Play, generating covers, and editing text artifacts without pretending an action succeeded before the tool result exists.
+
+**Model setup** — Studio includes provider settings, model routing, cover-service settings, [kkaiapi](https://en.kkaiapi.com/) / OpenRouter aggregator entries, and custom OpenAI-compatible endpoints.
+
+<p align="center">
+  <img src="assets/play-item-warcraft.png" width="420" alt="InkOS Play item image example">
+</p>

 **Native English novel writing now supported！** — 10 built-in English genre profiles with dedicated pacing rules, fatigue word lists, and audit dimensions. Set `--lang en` and go.

@@ -62,19 +87,32 @@ Once installed, Claw should prefer the shared interaction entry:
 inkos interact --json --message "continue the current book, but keep the pacing tighter"
 ```

-This routes through the same conversation executor used by the project TUI, so OpenClaw, TUI, and Studio stay on the same control brain. The JSON payload includes:
- parsed request
- assistant response text
- updated interaction session
- execution state
- pending decision
- recent events
+This routes through the same conversation executor used by the project TUI, so OpenClaw, TUI, and Studio stay on the same control brain. The current JSON output includes assistant response text and the interaction session; real completion should still be derived from tool results and files, not from prose claims.

 Atomic commands (`plan chapter` / `compose chapter` / `draft` / `audit` / `revise` / `write next`) are still available, but they are now lower-level tools rather than the preferred OpenClaw entry. You can also browse it on [ClawHub](https://clawhub.ai) by searching `inkos`.

 ### Configure

-**Option 1: Global config (recommended, one-time setup)**
+InkOS now separates two configuration paths: **Studio uses visual service settings**, while **CLI / daemon / deployment can still use env overrides**. They do not silently overwrite each other.
+
+**Option 1: Studio service settings (recommended for local writing)**
+
+```bash
+inkos init my-novel
+cd my-novel
+inkos
+```
+
+Open Studio, then go to **Model Settings**:
+
+1. Choose a service such as Google Gemini, Moonshot, MiniMax, DeepSeek, kkaiapi, OpenRouter, or a custom endpoint.
+2. Paste the API key and test the connection.
+3. Pick an available model and save.
+4. Return to Studio Chat or your book page.
+
+Studio uses project service settings and `.inkos/secrets.json`. It may show env-detection hints, but env files do not override the Studio-selected service/model/base URL/API key.
+
+**Option 2: CLI / daemon / deployment env config**

 ```bash
 inkos config set-global \
@@ -90,14 +128,9 @@ inkos config set-global \
 # model: your model name
 ```

-`--lang en` sets English as the default writing language for all projects. Saved to `~/.inkos/.env`. New projects just work without extra config.
+`--lang en` sets English as the default writing language for CLI / daemon runs. Saved to `~/.inkos/.env`.

-**Option 2: Per-project `.env`**
-
-```bash
-inkos init my-novel     # Initialize project
-# Edit my-novel/.env
-```
+You can also edit global `~/.inkos/.env` or project `.env` manually:

 ```bash
 # Required
@@ -111,11 +144,10 @@ INKOS_LLM_MODEL=                                   # Model name

 # Optional
 # INKOS_LLM_TEMPERATURE=0.7                       # Temperature
-# INKOS_LLM_MAX_TOKENS=8192                        # Max output tokens
 # INKOS_LLM_THINKING_BUDGET=0                      # Anthropic extended thinking budget
 ```

-Project `.env` overrides global config. Skip it if no override needed.
+CLI resolution starts from Studio/project service settings, then layers service secrets, global env, project env, process env, and CLI flags. That means CLI can reuse the service you configured in Studio, while env and command-line flags remain explicit overrides.

 **Option 3: Multi-model routing (optional)**

@@ -130,18 +162,15 @@ inkos config show-models        # View current routing

 Agents without explicit overrides fall back to the global model.

-### v1.2 Update
+### Current Interaction Entry Points

-**Unified Interaction Kernel + TUI Dashboard + Studio Assistant**
+**Studio Chat + CLI + TUI share the same execution surface**

- **Shared Interaction Runtime**: TUI, Studio, `inkos interact`, and OpenClaw Skill share a single NL understanding + execution kernel, supporting 15+ intents (write, revise, rewrite, rename, export, switch book, etc.)
- **Ink TUI Dashboard**: `inkos` launches a full-screen interactive dashboard (Ink + React) with conversational creation, slash command autocomplete, themed animations, and bilingual i18n
- **Studio Assistant Panel**: right-side AI assistant panel connects to the shared interaction kernel — natural language book operations (rename, write, audit, export) with real-time execution status
- **Conversational Book Creation**: brainstorm book settings through natural language dialogue, one-click create when draft is ready
- **Book-wide Entity Rename**: `rename Lin Jin to Zhang San` or `/rename Lin Jin => Zhang San` — scans all chapters + truth files in one pass
- **`inkos interact`**: shared interaction JSON endpoint for OpenClaw / external agent integration
- **Thinking Model Temperature Clamp**: kimi-k2.5 and similar thinking models auto-clamped to temperature=1, compatible with per-call temperature overrides
- **Studio Dead Code Cleanup**: removed unused shadcn components and dependencies, -2800 lines
+- **Studio Chat**: discuss, create books, run Short, generate covers, launch Play, and edit persistent files from one chat surface; heavy actions show confirmation cards.
+- **Creation entries**: Long-form Novel, Short Fiction, Fan Fiction, Spinoff, Style Imitation, Continuation, Branching Interactive, and Open World are available as first-class Studio entries.
+- **TUI dashboard**: `inkos tui` opens the terminal full-screen interaction mode for keyboard-first users.
+- **External agent entry**: `inkos interact --json --message "..."` remains the structured entry for OpenClaw and other agents.
+- **Atomic commands remain**: `plan` / `compose` / `draft` / `audit` / `revise` / `write next` still work for scripting and advanced usage.

 ### Write Your First Book

@@ -190,9 +219,21 @@ The cover tool writes `covers/<title>/cover-prompt.md` and `covers/<title>/cover
 After generation, you can keep editing the cover prompt through chat, for example: "move the character closer, make the title text bigger, and give her a colder smile." InkOS will pass the revised direction as `coverPrompt`, rewrite `cover-prompt.md`, and regenerate the cover without rewriting the story.

 <p align="center">
-  <img src="assets/screenshot-terminal.png" width="700" alt="Terminal screenshot">
+  <img src="assets/inkos-short-demo-cover.png" width="260" alt="InkOS Short cover example">
+  <img src="assets/play-openworld-warcraft.png" width="260" alt="InkOS Play open-world example">
+  <img src="assets/play-openworld-detective.png" width="260" alt="InkOS Play detective example">
 </p>

+### Launch an Open World or Branching Story
+
+In Studio Chat, choose **Open World** or **Branching Interactive**, then describe the world in natural language:
+
+```text
+Create a Warcraft-like border watchtower open world. Time is not fixed per turn: patrols take an hour, training can take several days. Equipment has rarity, but no stat sheet; show rarity through material, glow, and atmosphere.
+```
+
+InkOS creates the world, characters, items, evidence, relationships, current scene, and suggested actions. Open World supports free-form actions; Branching Interactive provides clickable choices. When image generation is configured, characters, items, evidence, and scenes can render images directly inside the chat stream.
+
 ---

 ## English Genre Profiles
@@ -220,6 +261,14 @@ Every genre includes a **fatigue word list** (e.g., "delve", "tapestry", "testam

 ## Key Features

+### Studio Chat + Action Surface
+
+Studio Chat is not just a Q&A box. It can create long-form books, run Short, generate covers, launch Play, edit persistent text artifacts, and ask for confirmation before heavy actions. Plain discussion remains plain text; explicit creation requests become tool actions.
+
+### InkOS Play: Open Worlds and Branching Interaction
+
+Play maintains a durable interactive world state: characters, locations, items, evidence, relationships, time, current scene, HUD, and images. It is not a hard-coded RPG system. A cultivation world may use rarity and realms; a romance story may use emotional stages; a detective story may use evidence lifecycle and credibility. The rules come from the user's world contract and stay in the world state.
+
 ### 33-Dimension Audit + De-AI-ification

 The Continuity Auditor agent checks every draft across 33 dimensions: character memory, resource continuity, hook payoff, outline adherence, narrative pacing, emotional arcs, and more. Built-in AI-tell detection automatically catches "LLM voice" — overused words, monotonous sentence patterns, excessive summarization. The default long-form write cycle now runs at most one automatic revision pass; unresolved critical findings are kept in the result for human review or later commands.
@@ -261,7 +310,7 @@ This generates `story/runtime/chapter-XXXX.intent.md`, `context.json`, `rule-sta

 ### Continuation Writing

-`inkos import chapters` imports existing novel text, auto reverse-engineers all 7 truth files (world state, character matrix, resource ledger, plot hooks, etc.), supports `Chapter N` and custom split patterns, and resumable import. After import, `inkos write next` seamlessly continues the story.
+`inkos import chapters` imports existing novel text and rebuilds structured state, chapter summaries, hooks, character relationships, and readable Markdown projections. It supports `Chapter N`, custom split patterns, and resumable import. After import, `inkos write next` can continue the story.

 ### Fan Fiction

@@ -273,7 +322,7 @@ Different agents can use different models and providers. Writer on Claude (stron

 ### Daemon Mode + Notifications

-`inkos up` starts an autonomous background loop that writes chapters on a schedule. The pipeline runs fully unattended for non-critical issues, pausing for human review when needed. Notifications via Telegram and Webhook (HMAC-SHA256 signing + event filtering). Logs to `inkos.log` (JSON Lines), `-q` for quiet mode.
+`inkos up` starts an autonomous background loop that writes chapters on a schedule. The pipeline continues through handleable non-critical issues, pausing with reviewable results when human judgment is needed. Notifications via Telegram and Webhook (HMAC-SHA256 signing + event filtering). Logs to `inkos.log` (JSON Lines), `-q` for quiet mode.

 ### Local Model Compatibility

@@ -285,13 +334,15 @@ Every chapter creates an automatic state snapshot — `inkos write rewrite` roll

 The hook system uses Zod schema validation — `lastAdvancedChapter` must be an integer, `status` can only be open/progressing/deferred/resolved. JSON deltas from the LLM are processed through `applyRuntimeStateDelta` (immutable update) and `validateRuntimeState` (structural check) before persistence. Corrupted data is rejected, not propagated.

-User-configured `INKOS_LLM_MAX_TOKENS` now acts as a global cap on all API calls. Reserved keys in `llm.extra` (max_tokens, temperature, etc.) are automatically stripped to prevent accidental overrides.
+Model output limits are managed by provider model cards in the provider bank. Reserved keys in `llm.extra` (max_tokens, temperature, model, messages, stream, etc.) are stripped to prevent accidental overrides of core request parameters.

 ---

 ## How It Works

-Each chapter is produced by multiple agents in sequence, with zero human intervention:
+InkOS now has two main runtime tracks: long-form / short-form production for deliverable text, and Play for persistent interactive worlds. They share Studio Chat, model configuration, action confirmation, artifact preview, and provider handling, but their state models are different.
+
+Long-form chapters are produced by multiple agents in sequence:

 <p align="center">
  <img src="assets/screenshot-pipeline.png" width="800" alt="Pipeline diagram">
@@ -301,34 +352,30 @@ Each chapter is produced by multiple agents in sequence, with zero human interve
 |-------|---------------|
 | **Radar** | Scans platform trends and reader preferences to inform story direction (pluggable, skippable) |
 | **Planner** | Reads author intent + current focus + memory retrieval results, produces chapter intent (must-keep / must-avoid) |
-| **Composer** | Selects relevant context from all truth files by relevance, compiles rule stack and runtime artifacts |
+| **Composer** | Selects task-relevant context from structured state, control docs, and Markdown projections, then compiles rule stack and runtime artifacts |
 | **Architect** | Generates foundation files during book creation, import, or spinoff setup: story frame, rules, characters, and long-horizon control files |
 | **Writer** | Produces prose from the composed context (length-governed, dialogue-driven) |
 | **Observer** | Over-extracts 9 categories of facts from the chapter text (characters, locations, resources, relationships, emotions, information, hooks, time, physical state) |
 | **Reflector** | Outputs a JSON delta (not full markdown); code-layer applies Zod schema validation then immutable write |
 | **Normalizer** | Single-pass compress/expand only when the chapter clearly leaves the hard length range |
-| **Continuity Auditor** | Validates the draft against 7 canonical truth files, 33-dimension check |
+| **Continuity Auditor** | Validates the draft against structured state, control docs, and chapter context |
 | **Reviser** | Fixes critical issues found by the auditor; the default write cycle runs at most one automatic revision pass and flags the rest for human review |

 If the audit fails, the default pipeline runs one revise → re-audit pass. Remaining issues are preserved in the result and state for human review or later commands.

-### Canonical Truth Files
+### Long-Term Memory

-Every book maintains 7 truth files as the single source of truth:
+Each book's canonical memory is split into three layers:

-| File | Purpose |
-|------|---------|
-| `current_state.md` | World state: character locations, relationships, knowledge, emotional arcs |
-| `particle_ledger.md` | Resource accounting: items, money, supplies with quantities and decay tracking |
-| `pending_hooks.md` | Open plot threads: foreshadowing planted, promises to readers, unresolved conflicts |
-| `chapter_summaries.md` | Per-chapter summaries: characters, key events, state changes, hook dynamics |
-| `subplot_board.md` | Subplot progress board: A/B/C line status tracking |
-| `emotional_arcs.md` | Emotional arcs: per-character emotion tracking and growth |
-| `character_matrix.md` | Character interaction matrix: encounter records, information boundaries |
+| Layer | Purpose |
+|-------|---------|
+| `story/state/*.json` | Authoritative structured state: current state, hooks, chapter summaries, and related runtime data, validated with Zod schemas |
+| `story/*.md` | Human-readable projections such as `current_state.md`, `pending_hooks.md`, `chapter_summaries.md`, and `character_matrix.md` |
+| `story/memory.db` | SQLite temporal memory on Node 22+, used for relevance-based retrieval of facts, hooks, and summaries |

-The Continuity Auditor checks every draft against these files. If a character "remembers" something they never witnessed, or pulls a weapon they lost two chapters ago, the auditor catches it.
+The Continuity Auditor checks drafts against this state. If a character "remembers" something they never witnessed, or pulls a weapon they lost two chapters ago, the auditor catches it.

-Since 0.6.0, the authoritative source for truth files has moved from markdown to `story/state/*.json` (Zod schema validated). The Settler no longer outputs full markdown files — it produces a JSON delta that is immutably applied and structurally validated before persistence. Markdown files are retained as human-readable projections. Existing books auto-migrate on first run.
+The Settler no longer asks the model to output full markdown files. It produces a JSON delta, and the code layer applies and validates it immutably before persistence. Markdown remains as a readable projection. Existing books migrate from legacy Markdown on first run.

 On Node 22+, a SQLite temporal memory database (`story/memory.db`) is automatically enabled, supporting relevance-based retrieval of historical facts, hooks, and chapter summaries — preventing context bloat from full-file injection.

@@ -338,7 +385,7 @@ On Node 22+, a SQLite temporal memory database (`story/memory.db`) is automatica

 ### Control Surface and Runtime Artifacts

-Alongside the 7 truth files, InkOS splits guardrails from customization into reviewable control docs:
+Alongside runtime state, InkOS splits guardrails from customization into reviewable control docs:

 - `story/author_intent.md`: long-horizon author intent
 - `story/current_focus.md`: near-term steering
@@ -357,7 +404,7 @@ On top of that, each genre has dedicated rules (prohibitions, language constrain

 ## Usage Modes

-InkOS provides three interaction modes, all sharing the same atomic operations:
+InkOS provides four interaction modes, all sharing the same atomic operations:

 ### 1. Full Pipeline (One Command)

@@ -396,7 +443,11 @@ 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"
 ```

-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.
+Agent mode exposes tools according to the current session kind: book creation, control-surface edits, planning, composition, writing, audit, revision, Short, cover, and Play tools are only made available where they make sense. The recommended agent flow is: adjust the control surface first, then `plan` / `compose`, then choose draft-only or full-pipeline writing.
+
+### 4. Studio Play Mode
+
+Studio's **Open World** and **Branching Interactive** entries launch interactive creation without first creating a book. Describe how the world runs, how time advances, whether characters act as agents, and how items/evidence matter. InkOS writes the result back to a local world state so the session can continue.

 ## CLI Reference

@@ -420,7 +471,12 @@ inkos agent "Create a progression fantasy about a mage who can only use one spel
 | `inkos review approve-all [id]` | Batch approve |
 | `inkos status [id]` | Project status |
 | `inkos export [id]` | Export book (`--format txt/md/epub`, `--output <path>`, `--approved-only`) |
+| `inkos radar scan` | Scan market / trend inputs for new-book direction |
 | `inkos fanfic init` | Create a fanfic book from source material (`--from`, `--mode canon/au/ooc/cp`) |
+| `inkos short run` | Generate a standalone short-fiction package |
+| `inkos eval [id]` | Generate a quality evaluation report (`--json`, chapter ranges) |
+| `inkos consolidate [id]` | Consolidate chapter summaries for long-book context control |
+| `inkos interact` | External-agent / CLI natural-language entry (`--json`, `--message`, `--book`) |
 | `inkos config set-global` | Set global LLM config (~/.inkos/.env) |
 | `inkos config set-model <agent> <model>` | Per-agent model override (`--base-url`, `--provider`, `--api-key-env`) |
 | `inkos config show-models` | Show current model routing |
@@ -428,17 +484,20 @@ inkos agent "Create a progression fantasy about a mage who can only use one spel
 | `inkos detect [id] [n]` | AIGC detection (`--all` for all chapters, `--stats` for statistics) |
 | `inkos style analyze <file>` | Analyze reference text to extract style fingerprint |
 | `inkos style import <file> [id]` | Import style fingerprint into a book |
+| `inkos import canon [id] --from <parent>` | Import parent canon into a spinoff book |
 | `inkos import chapters [id] --from <path>` | Import existing chapters for continuation (`--split`, `--resume-from`) |
 | `inkos analytics [id]` / `inkos stats [id]` | Book analytics (audit pass rate, top issues, chapter ranking, token usage) |
-| `inkos studio` | Start web workbench (`-p` for port, default 4567) |
+| `inkos update` | Update to the latest version |
+| `inkos` / `inkos studio` | Start web workbench (`-p` for port, default 4567) |
+| `inkos tui` | Start terminal full-screen TUI |
 | `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. `draft` / `write next` / `plan chapter` / `compose chapter` accept `--context` for steering, and `--words` overrides the target chapter size. `book create` supports `--brief <file>` to pass a creative brief — the Architect builds from your ideas instead of generating from scratch. `plan chapter` calls the LLM to create chapter intent; `compose chapter` does not require a live LLM, so you can inspect governed inputs before finishing API setup.

 ## Roadmap

- [x] ~~`packages/studio` Web UI workbench (Vite + React + Hono)~~ — shipped, run `inkos studio`
- [ ] Interactive fiction (branching narrative + reader choices)
+- [x] ~~`packages/studio` Web UI workbench (Vite + React + Hono)~~ — shipped, run `inkos` or `inkos studio`
+- [x] ~~Interactive fiction / open worlds (branching choices + free actions + generated images)~~ — shipped in Studio Play
 - [ ] Partial chapter intervention (rewrite half a chapter + cascade truth file updates)
 - [ ] Custom agent plugin system

@@ -3,7 +3,7 @@
  <img src="assets/inkos-text.svg" width="240" height="65" alt="InkOS">
 </p>

-<h1 align="center">自律型小説執筆 AIエージェント</h1>
+<h1 align="center">ローカル AI 物語創作システム</h1>

 <p align="center">
  <a href="https://www.npmjs.com/package/@actalk/inkos"><img src="https://img.shields.io/npm/v/@actalk/inkos.svg?color=cb3837&logo=npm" alt="npm version"></a>
@@ -16,7 +16,7 @@
 <p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69mt3v89kkekg24gg">
-    <img alt="Kimi Open Source Friends" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0">
+    <img alt="Kimi Open Source Friends" width="760" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0">
  </picture>
 </p>

@@ -26,15 +26,40 @@

 ---

-小説の執筆・監査・修正を自律的に行うオープンソースCLIエージェント。人間によるレビューゲートにより、常にコントロールを維持できます。LitRPG、プログレッションファンタジー、異世界転生、ロマンタジー、SF など多数のジャンルに対応。続編・スピンオフ・二次創作・文体模倣ワークフローを内蔵。
+InkOS は、長編小説、独立短編、二次創作、番外、文体模倣、続き書き、インタラクティブ世界を扱うローカル AI 創作システムです。Studio Chat、CLI、TUI は同じ action surface を共有し、相談、確認、生成、プレビュー、永続ファイル編集を一つの流れで扱えます。

-**InkOS Studio 2.0 正式リリース！** — `inkos` を実行してローカル Web ワークベンチを起動。書籍管理、章のレビュー＆編集、リアルタイム執筆進捗、市場レーダー、アナリティクス、AI検出、スタイル分析、ジャンル管理、デーモン制御、真実ファイル編集 — CLI の全機能をビジュアルで利用可能。
+## v1.5.0 主要アップデート

-**InkOS TUI 正式リリース！** — `inkos tui` を実行してフルスクリーンのインタラクティブダッシュボードを起動。会話型創作、自然言語での書籍操作、スラッシュコマンド自動補完、テーマアニメーション——TUI、Studio、OpenClaw が同一のインタラクションカーネルを共有。
+v1.5.0 は単独機能の追加ではなく、InkOS を「章生成パイプライン」から「対話でき、確認でき、コンテキストを継続管理できる創作システム」へ進める更新です。

-**InkOS Short** — Studio のチャットまたは CLI から、独立した短編パッケージを生成できます。完成本文、アウトライン記録、レビュー記録、あらすじ、セールスポイント、表紙プロンプト、表紙サービス設定後の表紙画像に対応します。
+- **指示追従**：Studio Chat、TUI、CLI の自然言語入口を統一された action surface に集約。通常の相談、書籍作成、Short、表紙生成、Play、長編執筆を散らばったキーワードで誤発火させず、重い操作は確認してから実行します。
+- **コンテキスト管理**：長編の入力コンテキストを protected / compressible に分け、予算が厳しい場合だけ意味圧縮します。会話履歴も要約を使って復元し、古い履歴が現在の指示を弱める問題を抑えます。
+- **開放世界 / 分岐インタラクション**：InkOS Play により、自由行動、クリック可能な選択肢、世界契約、時間の進行、キャラクター / アイテム / 証拠 / 関係状態、HUD、画像生成に対応しました。
+- **創作入口の整理**：長編、Short、二次創作、番外、文体模倣、続き書き、表紙生成が Studio の一等入口になり、CLI の奥に隠れた機能ではなくなりました。
+- **モデルと形式の堅牢性**：弱いモデルの形式崩れで即座に失敗しにくくなり、プロバイダーエラー、InkOS の実行エラー、画像生成エラーをより分けて表示します。

-**v1.4.1 Windows プロバイダーと長編速度の更新** — MiniMax は既定で OpenAI-compatible エンドポイントを使用するようになりました。長編執筆は高速な 1 回修正を既定にしつつ、必要に応じて `writing.reviewRetries` を引き上げられます。v1.4 の短編 / Studio Chat ワークフローも引き続き利用できます。
+この更新では、自然言語の誤発火、「言ったことと違うことをする」問題、長い履歴が現在の指示を埋もれさせる問題、コンテキスト上限、インタラクティブ世界の状態不可視、テキスト/画像エラーの混線を広く改善しています。
+
+<p align="center">
+  <img src="assets/inkos-short-demo-cover.png" width="210" alt="InkOS Short 表紙例">
+  <img src="assets/play-openworld-warcraft.png" width="210" alt="InkOS Play ファンタジー開放世界例">
+  <img src="assets/play-openworld-romance.png" width="210" alt="InkOS Play 恋愛例">
+  <img src="assets/play-openworld-detective.png" width="210" alt="InkOS Play 探偵例">
+</p>
+
+**長編小説** — ブリーフから書籍を作成し、基礎設定、章の意図、コンテキスト、本文、レビュー、修正、状態更新まで管理します。長編でも制御を失わないように、コンテキストは protected / compressible に分けて扱います。
+
+**InkOS Short** — Studio Chat と CLI から独立した短編パッケージを生成できます。完成本文、アウトライン記録、レビュー記録、あらすじ、セールスポイント、表紙プロンプト、表紙画像に対応します。
+
+**InkOS Play** — 自然言語の世界契約から、開放世界や分岐型インタラクティブ物語を開始できます。時間の進み方、キャラクター agent、所持品、証拠、関係性、シーン状態、ビジュアルルール、自由行動、選択肢、画像生成に対応します。
+
+**Studio Chat** — 質問応答だけでなく、長編作成、Short、表紙生成、Play、永続テキスト編集を扱います。重いアクションは確認してから実行し、ツール結果がないのに成功したとは扱いません。
+
+**モデル設定** — Studio はサービス設定、モデルルーティング、表紙サービス、[kkaiapi](https://en.kkaiapi.com/) / OpenRouter などのモデル集約入口、カスタム OpenAI-compatible エンドポイントに対応します。
+
+<p align="center">
+  <img src="assets/play-item-warcraft.png" width="420" alt="InkOS Play アイテム画像例">
+</p>

 **英語ネイティブ小説執筆に対応！** — 10種類の英語ジャンルプロファイルを内蔵し、専用のペーシングルール、疲労語リスト、監査ディメンションを搭載。`--lang en` を設定するだけですぐに始められます。

@@ -48,7 +73,7 @@ npm i -g @actalk/inkos

 ### OpenClaw 🦞 経由で使用

-InkOS は [OpenClaw](https://clawhub.ai) Skill として公開されており、互換エージェント（Claude Code、OpenClaw など）から呼び出し可能です：
+InkOS は [OpenClaw](https://clawhub.ai/narcooo/inkos) Skill として公開されており、互換エージェント（Claude Code、OpenClaw など）から呼び出し可能です：

 ```bash
 clawhub install inkos          # ClawHub からインストール
@@ -56,11 +81,36 @@ clawhub install inkos          # ClawHub からインストール

 npm でインストール済み、またはリポジトリをクローン済みの場合、`skills/SKILL.md` が含まれているため、ClawHub の別途インストールなしで 🦞 が直接読み取れます。

-インストール後、Claw は InkOS のアトミックコマンドとコントロールサーフェス操作（`plan chapter`/`compose chapter`/`draft`/`audit`/`revise`/`write next`）を `exec` 経由で呼び出し可能で、`--json` 出力による構造化された意思決定が可能です。推奨フロー：`author_intent.md` または `current_focus.md` を更新し、`plan` / `compose` を実行、その後 `draft` または完全パイプラインの `write next` を選択。[ClawHub](https://clawhub.ai) で `inkos` を検索して閲覧することもできます。
+インストール後、Claw は共有インタラクション入口を優先してください：
+
+```bash
+inkos interact --json --message "continue the current book, but keep the pacing tighter"
+```
+
+この入口はプロジェクト TUI と同じ会話実行カーネルを使います。現在の JSON 出力には assistant の返信と interaction session が含まれます。実際に完了したかどうかは、モデルの文章ではなく、ツール結果と生成ファイルで判断します。`plan` / `compose` / `draft` / `audit` / `revise` / `write next` などのアトミックコマンドも、スクリプトや上級者向けの下位ツールとして残っています。

 ### 設定

-**方法1：グローバル設定（推奨、初回のみ）**
+InkOS は設定経路を分けています。**Studio は可視化されたサービス設定**を使い、**CLI / daemon / デプロイ環境は env オーバーライド**を使えます。両者は暗黙に上書きしません。
+
+**方法1：Studio サービス設定（ローカル執筆に推奨）**
+
+```bash
+inkos init my-novel
+cd my-novel
+inkos
+```
+
+Studio を開き、**モデル設定**へ進みます：
+
+1. Google Gemini、Moonshot、MiniMax、DeepSeek、kkaiapi、OpenRouter、またはカスタムエンドポイントを選択。
+2. API Key を貼り付けて接続をテスト。
+3. 利用可能なモデルを選んで保存。
+4. Studio Chat または書籍ページに戻って創作を開始。
+
+Studio はプロジェクトのサービス設定と `.inkos/secrets.json` を使います。env が検出されてもヒントとして表示するだけで、Studio で選んだ service / model / base URL / API Key を上書きしません。
+
+**方法2：CLI / daemon / デプロイ環境の env 設定**

 ```bash
 inkos config set-global \
@@ -76,14 +126,9 @@ inkos config set-global \
 # model: モデル名
 ```

-`--lang en` で英語をすべてのプロジェクトのデフォルト執筆言語に設定。`~/.inkos/.env` に保存されます。新規プロジェクトは追加設定なしですぐに使えます。
+`--lang en` は CLI / daemon 実行時のデフォルト執筆言語を英語に設定します。`~/.inkos/.env` に保存されます。

-**方法2：プロジェクトごとの `.env`**
-
-```bash
-inkos init my-novel     # プロジェクトを初期化
-# my-novel/.env を編集
-```
+グローバル `~/.inkos/.env` またはプロジェクト `.env` を手動で編集することもできます：

 ```bash
 # 必須
@@ -97,11 +142,10 @@ INKOS_LLM_MODEL=                                   # モデル名

 # オプション
 # INKOS_LLM_TEMPERATURE=0.7                       # Temperature
-# INKOS_LLM_MAX_TOKENS=8192                        # 最大出力トークン数
 # INKOS_LLM_THINKING_BUDGET=0                      # Anthropic拡張思考バジェット
 ```

-プロジェクトの `.env` はグローバル設定を上書きします。上書きが不要な場合はスキップ可能です。
+CLI の解決順序は、Studio/project サービス設定、サービス secrets、グローバル env、プロジェクト env、プロセス env、CLI フラグです。つまり CLI は Studio で設定したサービスを再利用でき、env やコマンドライン引数は明示的な上書きとして扱われます。

 **方法3：マルチモデルルーティング（オプション）**

@@ -116,18 +160,15 @@ inkos config show-models        # 現在のルーティングを表示

 明示的なオーバーライドがないエージェントはグローバルモデルにフォールバックします。

-### v1.2 アップデート
+### 現在のインタラクション入口

-**統一インタラクションカーネル + TUIダッシュボード + Studioアシスタント**
+**Studio Chat + CLI + TUI は同じ実行面を共有します**

- **共有インタラクションランタイム**：TUI、Studio、`inkos interact`、OpenClaw Skillが単一のNL理解+実行カーネルを共有、15以上のインテント（執筆、修正、書き直し、リネーム、エクスポート、書籍切り替え等）をサポート
- **Ink TUIダッシュボード**：`inkos` でフルスクリーンの対話型ダッシュボード（Ink + React）を起動、会話型創作、スラッシュコマンド自動補完、テーマアニメーション、i18nバイリンガル対応
- **Studioアシスタントパネル**：右側AIアシスタントパネルが共有インタラクションカーネルに接続——自然言語で書籍操作（リネーム、執筆、監査、エクスポート）、リアルタイム実行状態表示
- **会話型ブック作成**：自然言語の対話で書籍設定を段階的にブレスト、ドラフト完成後ワンクリック作成
- **全書エンティティリネーム**：`rename 林烬 to 張三` または `/rename 林烬 => 張三`——全章+真実ファイルを一括スキャン＆置換
- **`inkos interact`**：共有インタラクションJSONエンドポイント、OpenClaw/外部Agentから直接呼び出し可能
- **Thinkingモデル温度クランプ**：kimi-k2.5等のthinkingモデルをtemperature=1に自動固定、per-call温度オーバーライドと互換
- **Studio不要コード削除**：未使用のshadcnコンポーネントと依存関係を削除、-2800行
+- **Studio Chat**：相談、書籍作成、Short、表紙、Play、永続ファイル編集を一つのチャット入口から扱えます。重い操作は確認カードを表示します。
+- **創作入口**：長編、短編、二次創作、番外、文体模倣、続き書き、分岐インタラクション、開放世界を Studio の上部入口から開始できます。
+- **TUI ダッシュボード**：`inkos tui` でキーボード中心のフルスクリーン端末 UI を開けます。
+- **外部 Agent 入口**：`inkos interact --json --message "..."` は OpenClaw など外部 agent 向けの構造化入口です。
+- **アトミックコマンド**：`plan` / `compose` / `draft` / `audit` / `revise` / `write next` はスクリプトや上級者向けに残っています。

 ### 最初の本を書く

@@ -176,9 +217,21 @@ inkos short run \
 生成後もチャットで表紙プロンプトを調整できます。例：「人物をもっと近く、タイトル文字を大きく、冷たい笑みにして」。InkOS は新しい指示を `coverPrompt` として渡し、`cover-prompt.md` を更新して表紙を再生成します。本文を書き直す必要はありません。

 <p align="center">
-  <img src="assets/screenshot-terminal.png" width="700" alt="ターミナルスクリーンショット">
+  <img src="assets/inkos-short-demo-cover.png" width="260" alt="InkOS Short 表紙例">
+  <img src="assets/play-openworld-warcraft.png" width="260" alt="InkOS Play 開放世界例">
+  <img src="assets/play-openworld-detective.png" width="260" alt="InkOS Play 探偵例">
 </p>

+### 開放世界 / 分岐型インタラクションを始める
+
+Studio Chat で **Open World** または **Branching Interactive** を選び、自然言語で世界を説明します：
+
+```text
+Warcraft 風の国境見張り塔を舞台にした開放世界を作って。時間は固定ターンではなく、巡回は1時間、訓練は数日かかる。装備には希少感があるが、数値表は使わず、素材・光沢・雰囲気で表現する。
+```
+
+InkOS は世界、キャラクター、アイテム、証拠、関係性、現在シーン、候補アクションを生成します。Open World は自由入力の行動に対応し、Branching Interactive はクリック可能な選択肢を提示します。画像生成を設定すると、キャラクター、アイテム、証拠、シーン画像をチャットの流れの中で表示できます。
+
 ---

 ## 英語ジャンルプロファイル
@@ -206,6 +259,14 @@ InkOS には10種類の英語ネイティブジャンルプロファイルが同

 ## 主な機能

+### Studio Chat + Action Surface
+
+Studio Chat は単なる Q&A ではありません。長編作成、Short、表紙生成、Play 起動、永続テキストファイル編集を扱い、重いアクションの前に確認を出します。普通の相談は普通に回答し、明確な創作アクションだけがツール実行になります。
+
+### InkOS Play：開放世界と分岐インタラクション
+
+Play は、キャラクター、場所、アイテム、証拠、関係性、時間、現在シーン、HUD、画像を含む持続的な世界状態を管理します。固定 RPG システムではありません。修仙世界なら希少度や境界、恋愛ものなら感情段階、探偵ものなら証拠のライフサイクルを、ユーザーの世界契約として状態に保存できます。
+
 ### 33次元監査 + 脱AI化

 継続性監査エージェントがすべての下書きを33の次元でチェックします：キャラクターの記憶、リソースの継続性、フック回収、アウトライン準拠、ナラティブペーシング、感情アークなど。内蔵のAI痕跡検出が「LLMの声」を自動的に捕捉 — 使いすぎの単語、単調な文型、過度な要約。デフォルトの長編執筆チェーンでは自動修正は最大1回まで行い、残った重大問題は結果に残して人間レビューまたは後続コマンドに渡します。
@@ -247,7 +308,7 @@ inkos compose chapter my-book

 ### 続編執筆

-`inkos import chapters` で既存の小説テキストをインポートし、7つの真実ファイル（世界状態、キャラクターマトリクス、リソース台帳、プロットフックなど）を自動でリバースエンジニアリング。`Chapter N` とカスタム分割パターンに対応し、再開可能なインポートをサポート。インポート後、`inkos write next` でシームレスに物語を継続。
+`inkos import chapters` で既存の小説テキストをインポートし、構造化状態、章サマリー、フック、キャラクター関係、人間が読める Markdown プロジェクションを自動で再構築。`Chapter N` とカスタム分割パターンに対応し、再開可能なインポートをサポート。インポート後、`inkos write next` で物語を継続できます。

 ### 二次創作

@@ -259,7 +320,7 @@ inkos compose chapter my-book

 ### デーモンモード + 通知

-`inkos up` で自律的なバックグラウンドループを開始し、スケジュールに従って章を執筆。重要でない問題についてはパイプラインが完全無人で実行され、人間のレビューが必要な場合に一時停止。TelegramとWebhook（HMAC-SHA256署名 + イベントフィルタリング）による通知。`inkos.log`（JSON Lines）にログ出力、`-q` でクワイエットモード。
+`inkos up` で自律的なバックグラウンドループを開始し、スケジュールに従って章を執筆。処理可能な非重要問題は自動で進め、人間の判断が必要な場合はレビュー可能な結果を残して一時停止します。TelegramとWebhook（HMAC-SHA256署名 + イベントフィルタリング）による通知。`inkos.log`（JSON Lines）にログ出力、`-q` でクワイエットモード。

 ### ローカルモデル互換性

@@ -271,13 +332,15 @@ inkos compose chapter my-book

 フックシステムはZodスキーマバリデーションを使用 — `lastAdvancedChapter` は整数、`status` は open/progressing/deferred/resolved のみ。LLMからのJSONデルタは `applyRuntimeStateDelta`（イミュータブル更新）と `validateRuntimeState`（構造チェック）を経て永続化。破損データは伝播されず、拒否されます。

-ユーザー設定の `INKOS_LLM_MAX_TOKENS` がすべてのAPI呼び出しのグローバルキャップとして機能。`llm.extra` の予約キー（max_tokens、temperatureなど）は自動的に除去され、意図しないオーバーライドを防止。
+モデル出力上限は provider bank のモデルカードで管理されます。`llm.extra` の予約キー（max_tokens、temperature、model、messages、stream など）は自動的に除去され、コアリクエストパラメータの意図しない上書きを防止します。

 ---

 ## 仕組み

-各章は複数のエージェントが順次処理し、人間の介入はゼロで作成されます：
+InkOS には二つの主要な実行線があります。長編 / 短編の生産線は納品可能な本文を作り、Play は持続的なインタラクティブ世界を進めます。どちらも Studio Chat、モデル設定、確認アクション、成果物プレビューを共有しますが、状態モデルは異なります。
+
+長編の各章は複数のエージェントが順次処理します：

 <p align="center">
  <img src="assets/screenshot-pipeline.png" width="800" alt="パイプライン図">
@@ -287,34 +350,30 @@ inkos compose chapter my-book
 |-------------|------|
 | **Radar** | プラットフォームのトレンドと読者の好みをスキャンして物語の方向性に反映（プラグイン可能、スキップ可能） |
 | **Planner** | 著者の意図 + 現在のフォーカス + メモリ取得結果を読み取り、章の意図（必須保持 / 必須回避）を生成 |
-| **Composer** | すべての真実ファイルから関連性に基づいてコンテキストを選択し、ルールスタックとランタイムアーティファクトをコンパイル |
+| **Composer** | 構造化状態、制御ドキュメント、Markdownプロジェクションからタスクに関連するコンテキストを選択し、ルールスタックとランタイムアーティファクトをコンパイル |
 | **Architect** | 書籍作成・インポート・スピンオフ初期化時に基盤ファイルを生成：物語フレーム、ルール、キャラクター、長期制御ファイル |
 | **Writer** | コンパイル済みコンテキストから散文を生成（文字数管理、対話駆動） |
 | **Observer** | 章テキストから9カテゴリのファクトを過剰抽出（キャラクター、ロケーション、リソース、関係性、感情、情報、フック、時間、身体状態） |
 | **Reflector** | JSONデルタを出力（フルMarkdownではない）；コードレイヤーがZodスキーマバリデーション後にイミュータブル書き込みを実行 |
 | **Normalizer** | 章が hard range から明確に外れた場合のみ、1パスで圧縮/拡張 |
-| **Continuity Auditor** | 7つの正規真実ファイルに対して下書きを検証、33次元チェック |
+| **Continuity Auditor** | 構造化状態、制御ドキュメント、章コンテキストに対して下書きを検証 |
 | **Reviser** | 監査で発見された重大問題を修正。デフォルトの執筆チェーンでは自動修正は最大1回までで、その他は人間レビュー用にフラグ付け |

 監査に失敗すると、デフォルトのパイプラインは修正→再監査を1回だけ実行します。残った問題は結果と状態に保持され、人間レビューまたは後続コマンドで扱います。

-### 正規真実ファイル
+### 長期記憶

-すべての書籍は7つの真実ファイルを唯一の情報源として維持します：
+各書籍の正規記憶は三つの層に分かれています：

-| ファイル | 目的 |
-|---------|------|
-| `current_state.md` | 世界状態：キャラクターの位置、関係性、知識、感情アーク |
-| `particle_ledger.md` | リソース会計：アイテム、金銭、物資の数量と劣化追跡 |
-| `pending_hooks.md` | 未解決のプロットスレッド：植えられた伏線、読者への約束、未解決の対立 |
-| `chapter_summaries.md` | 章ごとのサマリー：キャラクター、主要イベント、状態変化、フックの動態 |
-| `subplot_board.md` | サブプロット進行ボード：A/B/Cラインのステータス追跡 |
-| `emotional_arcs.md` | 感情アーク：キャラクターごとの感情追跡と成長 |
-| `character_matrix.md` | キャラクター相互作用マトリクス：遭遇記録、情報境界 |
+| 層 | 目的 |
+|----|------|
+| `story/state/*.json` | 正規の構造化状態：現在状態、フック、章サマリーなど。Zodスキーマで検証 |
+| `story/*.md` | 人間が読めるプロジェクション：`current_state.md`、`pending_hooks.md`、`chapter_summaries.md`、`character_matrix.md` など |
+| `story/memory.db` | Node 22+ で自動有効化される SQLite 時系列メモリ。ファクト、フック、サマリーの関連性検索に使用 |

-継続性監査エージェントがすべての下書きをこれらのファイルに対してチェックします。キャラクターが目撃していないことを「覚えて」いたり、2章前に失った武器を取り出したりすると、監査エージェントがそれを検出します。
+継続性監査エージェントが下書きをこれらの状態に対してチェックします。キャラクターが目撃していないことを「覚えて」いたり、2章前に失った武器を取り出したりすると、監査エージェントがそれを検出します。

-0.6.0以降、真実ファイルの権威あるソースはMarkdownから `story/state/*.json`（Zodスキーマバリデーション済み）に移行しました。SettlerはフルMarkdownファイルを出力せず、永続化前にイミュータブルに適用され構造的に検証されるJSONデルタを生成します。Markdownファイルは人間が読めるプロジェクションとして保持されます。既存書籍は初回実行時に自動マイグレーション。
+Settler はフル Markdown ファイルをモデルに出力させず、JSON デルタを生成します。コードレイヤーがそれをイミュータブルに適用し、構造検証してから永続化します。Markdown は人間が読めるプロジェクションとして保持されます。既存書籍は初回実行時に legacy Markdown から自動移行します。

 Node 22+ では、SQLite時系列メモリデータベース（`story/memory.db`）が自動的に有効化され、過去のファクト、フック、チャプターサマリーの関連性ベースの取得をサポート — ファイル全量注入によるコンテキスト肥大化を防止。

@@ -324,7 +383,7 @@ Node 22+ では、SQLite時系列メモリデータベース（`story/memory.db`

 ### コントロールサーフェスとランタイムアーティファクト

-7つの真実ファイルに加え、InkOS はガードレールをカスタマイズからレビュー可能なコントロールドキュメントに分離します：
+ランタイム状態に加え、InkOS はガードレールをカスタマイズからレビュー可能なコントロールドキュメントに分離します：

 - `story/author_intent.md`：長期的な著者の意図
 - `story/current_focus.md`：短期的なステアリング
@@ -343,7 +402,7 @@ Writerエージェントには約25の汎用執筆ルール（キャラクター

 ## 使用モード

-InkOS は3つのインタラクションモードを提供し、すべて同じアトミック操作を共有します：
+InkOS は4つのインタラクションモードを提供し、すべて同じアトミック操作を共有します：

 ### 1. フルパイプライン（ワンコマンド）

@@ -382,7 +441,11 @@ inkos agent "次の章を書いて、ボス戦と戦利品の分配にフォー
 inkos agent "1つの呪文しか使えない魔法使いのプログレッションファンタジーを作成して"
 ```

-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がツール使用で呼び出し順序を決定。推奨エージェントフロー：まずコントロールサーフェスを調整し、次に `plan` / `compose`、その後ドラフトのみまたはフルパイプライン執筆を選択。
+Agent モードは現在の session 種別に応じてツールを絞ります。書籍作成、コントロールサーフェス編集、計画、コンテキスト編成、執筆、監査、修正、Short、表紙、Play は、必要な場面でだけ利用可能になります。推奨フローは、まずコントロールサーフェスを調整し、次に `plan` / `compose`、最後にドラフトのみかフルパイプライン執筆を選ぶ形です。
+
+### 4. Studio Play モード
+
+Studio の **Open World** と **Branching Interactive** は、先に書籍を作らなくても開始できるインタラクティブ創作入口です。世界の動き方、時間の進み方、キャラクターが agent として動くか、アイテムや証拠がどう効くかを説明すると、InkOS は継続可能なローカル世界状態として保存します。

 ## CLIリファレンス

@@ -406,7 +469,12 @@ inkos agent "1つの呪文しか使えない魔法使いのプログレッショ
 | `inkos review approve-all [id]` | 一括承認 |
 | `inkos status [id]` | プロジェクトのステータス |
 | `inkos export [id]` | 書籍をエクスポート（`--format txt/md/epub`、`--output <path>`、`--approved-only`） |
+| `inkos radar scan` | 新規書籍の方向性に使う市場 / トレンド入力をスキャン |
 | `inkos fanfic init` | 原作素材から二次創作書籍を作成（`--from`、`--mode canon/au/ooc/cp`） |
+| `inkos short run` | 独立短編パッケージを生成 |
+| `inkos eval [id]` | 品質評価レポートを生成（`--json`、章範囲指定） |
+| `inkos consolidate [id]` | 長編の章要約を統合し、コンテキスト負荷を下げる |
+| `inkos interact` | 外部 agent / CLI 自然言語入口（`--json`、`--message`、`--book`） |
 | `inkos config set-global` | グローバルLLM設定を設定（~/.inkos/.env） |
 | `inkos config set-model <agent> <model>` | エージェントごとのモデルオーバーライド（`--base-url`、`--provider`、`--api-key-env`） |
 | `inkos config show-models` | 現在のモデルルーティングを表示 |
@@ -414,17 +482,20 @@ inkos agent "1つの呪文しか使えない魔法使いのプログレッショ
 | `inkos detect [id] [n]` | AIGC検出（`--all` で全章、`--stats` で統計） |
 | `inkos style analyze <file>` | 参考テキストを分析してスタイルフィンガープリントを抽出 |
 | `inkos style import <file> [id]` | スタイルフィンガープリントを書籍にインポート |
+| `inkos import canon [id] --from <parent>` | 番外 / スピンオフ用に親作品の正典を導入 |
 | `inkos import chapters [id] --from <path>` | 続編執筆用に既存の章をインポート（`--split`、`--resume-from`） |
 | `inkos analytics [id]` / `inkos stats [id]` | 書籍分析（監査合格率、主要な問題、章ランキング、トークン使用量） |
-| `inkos studio` | Webワークベンチを起動（`-p` でポート指定、デフォルト4567） |
+| `inkos update` | 最新バージョンへ更新 |
+| `inkos` / `inkos studio` | Webワークベンチを起動（`-p` でポート指定、デフォルト4567） |
+| `inkos tui` | 端末フルスクリーン TUI を起動 |
 | `inkos up / down` | デーモンの開始/停止（`-q` クワイエットモード、`inkos.log` に自動出力） |

 `[id]` はプロジェクトに書籍が1つしかない場合に自動検出されます。すべてのコマンドが `--json` による構造化出力に対応。`draft` / `write next` / `plan chapter` / `compose chapter` は `--context` でステアリング可能、`--words` で目標章サイズをオーバーライド。`book create` は `--brief <file>` でクリエイティブブリーフを渡せます — アーキテクトがゼロから生成するのではなく、あなたのアイデアを基に構築します。`plan chapter` は LLM を呼び出して章の意図を作成します。`compose chapter` はライブLLMを必要としないため、APIセットアップ完了前でも管理された入力を確認できます。

 ## ロードマップ

- [x] ~~`packages/studio` Webワークベンチ（Vite + React + Hono）~~ — リリース済み、`inkos studio` で起動
- [ ] インタラクティブフィクション（分岐ナラティブ + 読者の選択）
+- [x] ~~`packages/studio` Webワークベンチ（Vite + React + Hono）~~ — リリース済み、`inkos` または `inkos studio` で起動
+- [x] ~~インタラクティブフィクション / 開放世界（分岐選択 + 自由行動 + 画像生成）~~ — Studio Play としてリリース済み
 - [ ] 部分的な章介入（章の半分をリライト + 真実ファイルの連鎖更新）
 - [ ] カスタムエージェントプラグインシステム

@@ -3,7 +3,7 @@
  <img src="assets/inkos-text.svg" width="240" height="65" alt="InkOS">
 </p>

-<h1 align="center">Autonomous Novel Writing AI Agent<br><sub>自动化小说写作 AI Agent</sub></h1>
+<h1 align="center">Local AI Fiction Creation System<br><sub>本地 AI 小说与互动创作系统</sub></h1>

 <p align="center">
  <a href="https://www.npmjs.com/package/@actalk/inkos"><img src="https://img.shields.io/npm/v/@actalk/inkos.svg?color=cb3837&logo=npm" alt="npm version"></a>
@@ -16,7 +16,7 @@
 <p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69mt3v89kkekg24gg">
-    <img alt="Kimi Open Source Friends" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0">
+    <img alt="Kimi Open Source Friends" width="760" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0">
  </picture>
 </p>

@@ -26,22 +26,39 @@

 ---

-AI Agent 自主写小说——写、审、改，全程接管。覆盖玄幻、仙侠、都市、科幻等多种风格，支持续写、番外、同人、仿写等创作形式。人工审核门控确保你始终掌控全局。已发布为 [OpenClaw](https://clawhub.ai/narcooo/inkos) skill。
+InkOS 是一个面向小说生产的本地 AI 创作系统：长篇连载、独立短篇、同人 / 番外 / 仿写 / 续写、开放世界互动，都通过同一套 Studio Chat / CLI / TUI 交互内核调度。它不只是“写下一章”的脚本，而是把设定、上下文、审稿、修订、封面和互动世界状态统一管理起来。

+## v1.5.0 重大更新

+v1.5.0 的重点不是再加一个孤立功能，而是把 InkOS 从“章节流水线工具”推进到“可对话、可确认、可持续维护上下文的创作系统”：

-**v1.4.0 短篇写作与 Studio Chat 协作更新** — Studio Chat 和 CLI 现在可以生成独立短篇、简介卖点和封面提示词 / 封面图；普通聊天支持持久化 session，生成物可直接预览和编辑；Studio 模型配置内置 [kkaiapi](https://kkaiapi.com/) ，方便接入全球主流模型聚合服务。
+- **指令遵循**：Studio Chat、TUI 和 CLI 的自然语言入口统一到 action surface。普通讨论、确认建书、短篇、封面、Play、长篇写章不再靠散落的关键词抢跑，重动作先确认，完成态来自真实工具结果。
+- **上下文管理**：长篇写作上下文按 protected / compressible 分层，只有接近上下文窗口时才做语义压缩；会话历史也按摘要恢复，降低“旧历史淹没当前指令”的概率。
+- **开放世界 / 分支互动**：新增 InkOS Play，支持自由动作、可点击选择、世界契约、时间推进、角色 / 物品 / 证据 / 关系状态、HUD 和自动配图。
+- **内容生产入口**：长篇、短篇、同人、番外、仿写、续写、封面制作都进入 Studio 的一等创作入口，不再散落在 CLI 深处。
+- **模型与格式鲁棒性**：弱模型不稳定输出时更少直接崩溃；模型服务错误、InkOS 自身执行错误和图片生成错误会更清楚地区分，便于定位是配置、供应商还是系统问题。

-**InkOS Studio 2.0 正式发布！** — 直接运行 `inkos` 启动本地 Web 工作台。书籍管理、章节审阅编辑、实时写作进度、市场雷达、数据分析、AI 检测、文风分析、题材管理、守护进程控制、真相文件编辑——CLI 能做的，Studio 全部可视化。
-
-**InkOS TUI 正式发布！** — 运行 `inkos tui` 进入全屏交互仪表盘。对话式创作、自然语言操作书籍、slash 命令补全、主题动效——TUI、Studio、OpenClaw 共享同一套交互内核。
-
-**InkOS Short** — Studio 对话和 CLI 现在可以直接产出独立短篇：完整正文、大纲记录、审稿记录、简介卖点、封面提示词，并在配置封面服务后生成封面图。
-
-> 短篇开篇示例：宋词三个多月没坐过这辆车了。蓝牙自动连上她的手机，屏幕弹出“子账号登录中”。她点进常用地址统计：新城花园 187 次，妇幼医院 38 次，月子中心 9 次。后备箱传来闷响，徐晋安放完东西坐进来，冲她笑笑：“今晚加班，你自己打车回去？”她抬头看他，也笑了。
+这版集中解决的老问题：自然语言误触发、对话“你说你的它做它的”、长篇越写越被历史拖慢、上下文超限只能硬失败、互动世界状态不可视、图片生成和文本生成混在一起难排查。

 <p align="center">
-  <img src="assets/inkos-short-demo-cover.png" width="320" alt="InkOS Short 短篇封面示例">
+  <img src="assets/inkos-short-demo-cover.png" width="210" alt="InkOS Short 短篇封面示例">
+  <img src="assets/play-openworld-warcraft.png" width="210" alt="InkOS Play 魔幻开放世界示例">
+  <img src="assets/play-openworld-romance.png" width="210" alt="InkOS Play 恋爱互动示例">
+  <img src="assets/play-openworld-detective.png" width="210" alt="InkOS Play 侦探互动示例">
+</p>
+
+**长篇小说** — 从创作简报建书，生成世界观、角色、卷纲、章节意图，按“写作 → 审稿 → 必要修订 → 状态结算”推进。上下文按 protected / compressible 分层组织，避免长书越写越乱。
+
+**InkOS Short** — Studio Chat 和 CLI 可以直接产出独立短篇：完整正文、大纲记录、审稿记录、简介卖点、封面提示词，并在配置封面服务后生成封面图。
+
+**InkOS Play** — 新增开放世界与分支互动。你可以用自然语言指定世界契约、时间推进方式、角色 agent、物品 / 证据 / 关系规则和视觉风格；系统维护世界状态、可点击选择、自由动作、HUD 和自动配图。
+
+**Studio Chat** — 普通聊天、建书、短篇、封面、互动世界都走同一套 action surface。重动作先确认，生成物可预览，可通过聊天修改章节、封面提示词、世界状态和持久化文本产物。
+
+**模型配置** — Studio 内置多服务配置、模型路由和封面服务配置；也支持 [kkaiapi](https://kkaiapi.com/) / OpenRouter 等全球主流模型聚合入口，以及自定义 OpenAI-compatible 服务。
+
+<p align="center">
+  <img src="assets/play-item-warcraft.png" width="420" alt="InkOS Play 物品配图示例">
 </p>

 **Native English novel writing now supported！** Set `--lang en` to write in English. See [English README](README.en.md) for details.
@@ -79,19 +96,13 @@ clawhub install inkos          # 从 ClawHub 安装 InkOS Skill
 inkos interact --json --message "继续当前书，但把节奏再收紧一点"
 ```

-这条入口直接走和项目 TUI 相同的交互执行内核，因此 OpenClaw、TUI、Studio 共用同一套控制脑。返回的 JSON 包含：
- 解析后的 request
- assistant 文本回复
- 更新后的 interaction session
- execution state
- pending decision
- recent events
+这条入口直接走和项目 TUI 相同的交互执行内核，因此 OpenClaw、TUI、Studio 共用同一套控制脑。当前 JSON 输出包含 assistant 文本回复和 interaction session 信息；真正的执行结果以工具结果和落盘文件为准，不从模型口头声明推断完成。

 `plan chapter` / `compose chapter` / `draft` / `audit` / `revise` / `write next` 这些原子命令仍然保留，但更适合作为底层工具，而不是 OpenClaw 的首选入口。也可以在 [ClawHub](https://clawhub.ai) 搜索 `inkos` 在线查看。

 ### 配置

-InkOS 2.0 将 LLM 配置分成两条清晰路径：**Studio 用可视化服务配置**，**CLI / daemon / 部署环境支持 env 覆盖**。两者不会互相污染。
+当前 InkOS 将 LLM 配置分成两条清晰路径：**Studio 用可视化服务配置**，**CLI / daemon / 部署环境支持 env 覆盖**。两者不会互相污染。

 #### 方式一：Studio 服务配置（推荐）

@@ -203,27 +214,24 @@ inkos doctor

 如果服务测试失败，优先检查服务商、模型和协议是否匹配。Google Gemini 的 AI Studio API Key 可用于 Gemini OpenAI-compatible endpoint；InkOS 会自动禁用 Google 不支持的 OpenAI `store` 参数。MiniMax / MiniMax CodingPlan 默认走官方 OpenAI-compatible `/v1/chat/completions`，并优先使用可工作的非流式 transport，避免流式返回 usage 但无正文的问题。

-### v2.0 LLM 配置更新
+### LLM 配置更新

 - **Studio / CLI 配置隔离**：Studio 固定使用服务页配置和 `.inkos/secrets.json`；CLI、daemon、部署环境支持 env 覆盖和一次性命令参数。
- **Provider bank 能力表**：内置 Google Gemini、Moonshot、MiniMax、智谱、百炼、DeepSeek、硅基流动、PPIO、OpenRouter、Ollama、CodingPlan 等服务的 baseUrl、协议、模型和兼容策略。
+- **Provider bank 能力表**：内置 Google Gemini、Moonshot、MiniMax、智谱、百炼、DeepSeek、硅基流动、火山、腾讯混元、文心、讯飞星火、OpenRouter、kkaiapi、Ollama、CodingPlan 等服务的 baseUrl、协议、模型和兼容策略。
 - **模型归属校验**：`--service google --model kimi-k2.5` 这类错配会直接报错，避免把请求发到错误服务商。
 - **Google Gemini 兼容修复**：AI Studio API Key 可直接用于 Gemini OpenAI-compatible endpoint，InkOS 会自动禁用 Google 不支持的 OpenAI `store` 参数。
 - **MiniMax transport 探测**：MiniMax / MiniMax CodingPlan 使用官方 OpenAI-compatible `/v1` 入口，并自动使用可工作的非流式 transport，规避流式 usage 正常但正文为空的问题。
 - **旧 env 兼容**：老的 `INKOS_LLM_BASE_URL + INKOS_LLM_MODEL + INKOS_LLM_API_KEY` 仍可用于 CLI；没有 `INKOS_LLM_SERVICE` 时会尝试从 baseUrl 反推服务商。

-### v1.2 更新
+### 当前交互入口

-**统一交互内核 + TUI 仪表盘 + Studio 助手**
+**Studio Chat + CLI + TUI 共用同一套执行面**

- **共享交互运行时**：TUI、Studio、`inkos interact`、OpenClaw Skill 共用同一套自然语言理解 + 执行内核，支持 15+ 种意图（写作、修订、重写、改名、导出、切换书籍等）
- **Ink TUI 仪表盘**：`inkos` 直接进入全屏交互式仪表盘（Ink + React），对话式创作体验，slash 命令自动补全，主题动效，i18n 双语
- **Studio 助手面板**：右侧 AI 助手面板接入共享交互内核，支持自然语言操作书籍——改名、写章、审计、导出等，实时显示执行状态
- **对话式建书**：通过自然语言对话逐步构思书籍设定，草稿就绪后一键创建
- **全书实体改名**：`把林烬改成张三` 或 `/rename 林烬 => 张三`，全量扫描章节 + 真相文件，一次替换
- **`inkos interact`**：共享交互 JSON 入口，OpenClaw / 外部 Agent 可直接调用
- **Thinking 模型温度夹制**：kimi-k2.5 等 thinking 模型自动强制 temperature=1，兼容 per-call 温度调参
- **Studio 死代码清理**：移除未使用的 shadcn 组件和依赖，-2800 行
+- **Studio Chat**：讨论、建书、短篇、封面、Play、编辑持久化文件都从同一个对话入口发起；重动作会先展示确认卡。
+- **开始创作入口**：长篇小说、短篇小说、同人创作、番外创作、仿写创作、续写创作、分支互动、开放世界都可以从 Studio 顶部入口进入。
+- **TUI 仪表盘**：`inkos tui` 进入终端全屏交互，适合键盘流用户。
+- **外部 Agent 入口**：`inkos interact --json --message "..."` 仍是 OpenClaw / 其他 agent 的结构化入口。
+- **原子命令保留**：`plan` / `compose` / `draft` / `audit` / `revise` / `write next` 仍适合脚本和高级用户。

 ### 写第一本书

@@ -269,13 +277,33 @@ inkos short run \
 生成后也可以继续通过 chat 改封面提示词，例如“把人物拉近一点、标题字更大、表情更冷笑”。系统会用新的 `coverPrompt` 重写 `cover-prompt.md` 并重生成封面，不需要重新写短篇。

 <p align="center">
-  <img src="assets/screenshot-terminal.png" width="700" alt="终端截图">
+  <img src="assets/inkos-short-demo-cover.png" width="260" alt="InkOS Short 短篇封面示例">
+  <img src="assets/play-openworld-warcraft.png" width="260" alt="InkOS Play 开放世界示例">
+  <img src="assets/play-openworld-detective.png" width="260" alt="InkOS Play 侦探互动示例">
 </p>

+### 启动开放世界 / 分支互动
+
+在 Studio Chat 里选择「开放世界」或「分支互动」，直接用自然语言描述你想玩的世界：
+
+```text
+做一个魔兽风格的边境哨塔开放世界。时间不是固定回合，巡逻是一小时，练功可以跨几天。装备有稀有度，但不要数值面板，用材质和光泽体现。
+```
+
+系统会生成世界、角色、物品、证据、关系、当前场景和可选动作。开放世界支持自由输入动作；分支互动会给出可点击选项。配置封面 / 图片服务后，角色、物品、证据、场景都可以生成图，并在对话流里滚动显示。
+
 ---

 ## 核心特性

+### Studio Chat + Action Surface
+
+Studio Chat 不再只是问答框。它可以创建长篇、跑短篇、生成封面、启动 Play、编辑持久化文本文件，并在需要执行重动作前给出确认。普通讨论会直接回答；明确创作动作才进入工具执行。
+
+### InkOS Play：开放世界与分支互动
+
+Play 维护一个可持续推进的世界状态：角色、地点、物品、证据、关系、时间、场景和 HUD。它不是固定 RPG 模板，你可以用自然语言定义世界契约：修仙装备可以有稀有感，恋爱本可以有心动层级，侦探本可以有证据生命周期。系统把这些规则写进世界状态，再用于后续叙事和配图。
+
 ### 多维度审计 + 去 AI 味

 连续性审计员从 33 个维度检查每一章草稿：角色记忆、物资连续性、伏笔回收、大纲偏离、叙事节奏、情感弧线等。内置 AI 痕迹检测维度，自动识别"LLM 味"表达（高频词、句式单调、过度总结）。默认长篇写作链路最多自动修订一次；如果你更看重自动闭环，可以通过 `writing.reviewRetries` 调整修订轮数。
@@ -317,7 +345,7 @@ inkos compose chapter 吞天魔帝

 ### 续写已有作品

-`inkos import chapters` 从已有小说文本导入章节，自动逆向工程 7 个真相文件（世界状态、角色矩阵、资源账本、伏笔钩子等），支持 `第X章` 和自定义分割模式、断点续导。导入后 `inkos write next` 无缝接续创作。
+`inkos import chapters` 从已有小说文本导入章节，自动重建结构化状态、章节摘要、伏笔、角色关系和可读 Markdown 投影，支持 `第X章` 和自定义分割模式、断点续导。导入后 `inkos write next` 可继续创作。

 ### 同人创作

@@ -329,7 +357,7 @@ inkos compose chapter 吞天魔帝

 ### 守护进程 + 通知推送

-`inkos up` 启动后台循环自动写章。管线对非关键问题全自动运行，关键问题暂停等人工审核。通知推送支持 Telegram、飞书、企业微信、Webhook（HMAC-SHA256 签名 + 事件过滤）。日志写入 `inkos.log`（JSON Lines），`-q` 静默模式。
+`inkos up` 启动后台循环自动写章。管线会自动推进可处理的非关键问题；需要人工判断的问题会暂停并留下可审结果。通知推送支持 Telegram、飞书、企业微信、Webhook（HMAC-SHA256 签名 + 事件过滤）。日志写入 `inkos.log`（JSON Lines），`-q` 静默模式。

 ### 本地模型兼容

@@ -347,7 +375,9 @@ inkos compose chapter 吞天魔帝

 ## 工作原理

-每一章由多个 Agent 接力完成，默认按“规划 → 编排 → 写作 → 审计 → 必要修订 → 状态同步”运行：
+InkOS 现在有两条主要运行线：长篇 / 短篇生产线负责生成可交付文本；Play 运行线负责持续互动世界。它们共享模型配置、Studio Chat、确认动作和产物预览，但状态结构不同。
+
+长篇每一章默认按“规划 → 编排 → 写作 → 审计 → 必要修订 → 状态同步”运行：

 <p align="center">
  <img src="assets/screenshot-pipeline.png" width="800" alt="管线流程图">
@@ -357,34 +387,30 @@ inkos compose chapter 吞天魔帝
 |-------|------|
 | **雷达 Radar** | 扫描平台趋势和读者偏好，指导故事方向（可插拔，可跳过） |
 | **规划师 Planner** | 读取作者意图 + 当前焦点 + 记忆检索结果，产出本章意图（must-keep / must-avoid） |
-| **编排师 Composer** | 从全量真相文件中按相关性选择上下文，编译规则栈和运行时产物 |
+| **编排师 Composer** | 从结构化状态、控制文档和 Markdown 投影中按任务选择上下文，编译规则栈和运行时产物 |
 | **建筑师 Architect** | 建书、导入或番外初始化时生成基础设定：故事框架、规则、角色与长期控制文件 |
 | **写手 Writer** | 基于编排后的精简上下文生成正文（字数治理 + 对话引导） |
 | **观察者 Observer** | 从正文中过度提取 9 类事实（角色、位置、资源、关系、情感、信息、伏笔、时间、物理状态） |
 | **反射器 Reflector** | 输出 JSON delta（而非全量 markdown），由代码层做 Zod schema 校验后 immutable 写入 |
 | **归一化器 Normalizer** | 仅在正文明显偏离 hard range 时单 pass 压缩/扩展 |
-| **连续性审计员 Auditor** | 对照 7 个真相文件验证草稿，33 维度检查 |
+| **连续性审计员 Auditor** | 对照结构化状态、控制文档和章节上下文验证草稿，执行连续性与质量检查 |
 | **修订者 Reviser** | 修复审计发现的关键问题；默认最多自动修订一次，可通过 `writing.reviewRetries` 调整，其他问题标记给人工审核 |

 如果审计不通过，默认管线只做一次"修订 → 再审计"；仍未解决的问题会保留在结果和状态里，交给人工或后续命令继续处理。需要更强自动闭环时，可以运行 `inkos config set writing.reviewRetries 3` 把修订轮数调高。

 ### 长期记忆

-每本书维护 7 个真相文件作为唯一事实来源：
+每本书的权威记忆由三层组成：

-| 文件 | 用途 |
-|------|------|
-| `current_state.md` | 世界状态：角色位置、关系网络、已知信息、情感弧线 |
-| `particle_ledger.md` | 资源账本：物品、金钱、物资数量及衰减追踪 |
-| `pending_hooks.md` | 未闭合伏笔：铺垫、对读者的承诺、未解决冲突 |
-| `chapter_summaries.md` | 各章摘要：出场人物、关键事件、状态变化、伏笔动态 |
-| `subplot_board.md` | 支线进度板：A/B/C 线状态、停滞检测 |
-| `emotional_arcs.md` | 情感弧线：按角色追踪情绪变化和成长 |
-| `character_matrix.md` | 角色交互矩阵：相遇记录、信息边界 |
+| 层 | 用途 |
+|----|------|
+| `story/state/*.json` | 权威结构化状态：当前状态、伏笔、章节摘要等，经过 Zod schema 校验 |
+| `story/*.md` | 人类可读投影：`current_state.md`、`pending_hooks.md`、`chapter_summaries.md`、`character_matrix.md` 等 |
+| `story/memory.db` | Node 22+ 自动启用的 SQLite 时序记忆库，用于相关事实、伏笔和摘要检索 |

-连续性审计员对照这些文件检查每一章草稿。如果角色"记起"了从未亲眼见过的事，或者拿出了两章前已经丢失的武器，审计员会捕捉到。
+连续性审计员对照这些状态检查每一章草稿。如果角色"记起"了从未亲眼见过的事，或者拿出了两章前已经丢失的武器，审计员会捕捉到。

-从 0.6.0 起，真相文件的权威来源从 markdown 迁移到 `story/state/*.json`（Zod schema 校验）。Settler 不再输出完整 markdown 文件，而是输出 JSON delta，由代码层做 immutable apply + 结构校验后写入。markdown 文件仍然保留作为人类可读的投影。旧书首次运行时自动从 markdown 迁移到结构化 JSON，零人工操作。
+Settler 不再要求模型输出完整 markdown 文件，而是输出 JSON delta，由代码层做 immutable apply + 结构校验后写入。Markdown 文件保留为人类可读投影。旧书首次运行时会从 legacy Markdown 自动迁移到结构化 JSON。

 Node 22+ 环境下自动启用 SQLite 时序记忆数据库（`story/memory.db`），支持按相关性检索历史事实、伏笔和章节摘要，避免全量注入导致的上下文膨胀。

@@ -394,7 +420,7 @@ Node 22+ 环境下自动启用 SQLite 时序记忆数据库（`story/memory.db`

 ### 控制面与运行时产物

-除了 7 个真相文件，InkOS 还把“护栏”和“自定义”拆成可审阅的控制层：
+除了运行时状态，InkOS 还把“护栏”和“自定义”拆成可审阅的控制层：

 - `story/author_intent.md`：长期作者意图
 - `story/current_focus.md`：当前阶段的关注点
@@ -413,7 +439,7 @@ Node 22+ 环境下自动启用 SQLite 时序记忆数据库（`story/memory.db`

 ## 使用模式

-InkOS 提供三种交互方式，底层共享同一组原子操作：
+InkOS 提供四种交互方式，底层共享同一组原子操作：

 ### 1. 完整管线（一键式）

@@ -452,25 +478,22 @@ inkos agent "写下一章，重点写师徒矛盾"
 inkos agent "先扫描市场趋势，然后根据结果创建一本新书"
 ```

-内置 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`，最后决定写草稿还是跑完整管线。
+Agent 模式暴露的是按场景收窄后的工具集：建书、读写控制面、规划、编排、写作、审稿、修订、短篇、封面、Play 等能力会按当前 session 类型开放。推荐的 Agent 工作流是：先调整控制面，再 `plan` / `compose`，最后决定写草稿还是跑完整管线。

-## 实测数据
+### 4. Studio Play 模式

-用 InkOS 全自动跑了一本玄幻题材的《吞天魔帝》：
+Studio 里的「开放世界」和「分支互动」是交互式创作入口。它们不要求你先建书，也不要求写死 RPG 数值。你可以描述“世界怎样运行、时间怎样推进、角色是否自主行动、物品和证据怎样影响故事”，系统会生成可继续玩的世界，并把每回合状态写回本地。
+
+## 示例产物

 <p align="center">
-  <img src="assets/screenshot-chapters.png" width="800" alt="生产数据">
+  <img src="assets/inkos-short-demo-cover.png" width="230" alt="短篇封面">
+  <img src="assets/play-openworld-romance.png" width="230" alt="恋爱互动">
+  <img src="assets/play-openworld-detective.png" width="230" alt="侦探互动">
+  <img src="assets/play-item-warcraft.png" width="230" alt="物品配图">
 </p>

-| 指标 | 数据 |
-|------|------|
-| 已完成章节 | 31 章 |
-| 总字数 | 452,191 字 |
-| 平均章字数 | ~14,500 字 |
-| 审计通过率 | 100% |
-| 资源追踪项 | 48 个 |
-| 活跃伏笔 | 20 条 |
-| 已回收伏笔 | 10 条 |
+这些图片来自 InkOS Short 和 InkOS Play 的真实本地生成结果。短篇封面用于手机端缩略图点击，Play 图用于展示开放世界、侦探证据和互动场景的视觉能力。

 ## 命令参考

@@ -496,6 +519,10 @@ inkos agent "先扫描市场趋势，然后根据结果创建一本新书"
 | `inkos export [id]` | 导出书籍（`--format txt/md/epub`、`--output <path>`、`--approved-only`） |
 | `inkos radar scan` | 扫描平台趋势 |
 | `inkos fanfic init` | 从原作素材创建同人书（`--from`、`--mode canon/au/ooc/cp`） |
+| `inkos short run` | 生成独立短篇包（正文、简介卖点、封面提示词、可选封面图） |
+| `inkos eval [id]` | 生成质量评估报告（支持 `--json`、章节范围） |
+| `inkos consolidate [id]` | 归并长篇章节摘要，降低长书上下文压力 |
+| `inkos interact` | 外部 agent / CLI 自然语言入口（`--json`、`--message`、`--book`） |
 | `inkos config set-global` | 设置 CLI / daemon / 部署环境的全局 LLM env（`~/.inkos/.env`） |
 | `inkos config show-global` | 查看全局配置 |
 | `inkos config set/show` | 查看/更新项目配置 |
@@ -511,6 +538,7 @@ inkos agent "先扫描市场趋势，然后根据结果创建一本新书"
 | `inkos analytics [id]` / `inkos stats [id]` | 书籍数据分析（审计通过率、高频问题、章节排名、token 用量） |
 | `inkos update` | 更新到最新版本 |
 | `inkos studio` / `inkos` | 启动 Web 工作台（`-p` 指定端口，默认 4567；Studio 使用服务页配置，不使用 env 覆盖） |
+| `inkos tui` | 启动终端全屏 TUI |
 | `inkos up / down` | 启动/停止守护进程（`-q` 静默模式，自动写入 `inkos.log`） |

 `[id]` 参数在项目只有一本书时可省略，自动检测。所有命令支持 `--json` 输出结构化数据。`draft` / `write next` / `plan chapter` / `compose chapter` 支持 `--context` 传入创作指导，`--words` 覆盖每章目标字数。`book create` 支持 `--brief <file>` 传入创作简报（你的脑洞/设定文档），Architect 会基于此生成设定而非凭空创作。`plan chapter` 会调用 LLM 生成章节意图；`compose chapter` 不要求在线 LLM，可在配置 API Key 之前先检查输入治理结果。
@@ -524,8 +552,8 @@ inkos up --service moonshot --model kimi-k2.5 --api-key-env MOONSHOT_API_KEY

 ## 路线图

- [x] ~~`packages/studio` Web UI 工作台（Vite + React + Hono）~~ — 已发布，`inkos studio` 启动
- [ ] 互动小说（分支叙事 + 读者选择）
+- [x] ~~`packages/studio` Web UI 工作台（Vite + React + Hono）~~ — 已发布，`inkos` 或 `inkos studio` 启动
+- [x] ~~互动小说 / 开放世界（分支叙事 + 自由动作 + 自动配图）~~ — Studio Play 已落地
 - [ ] 局部干预（重写半章 + 级联更新后续 truth 文件）
 - [ ] 自定义 agent 插件系统
 - [ ] 平台格式导出（起点、番茄等）
@@ -1,21 +1,35 @@
 ---
 name: inkos
-description: Autonomous novel writing CLI agent with web workbench (InkOS Studio) - use for creative fiction writing, standalone short-fiction packages, cover generation, novel generation, style imitation, chapter continuation/import, EPUB export, AIGC detection, and fan fiction. Native English support with 10 built-in English genre profiles (LitRPG, Progression Fantasy, Isekai, Cultivation, System Apocalypse, Dungeon Core, Romantasy, Sci-Fi, Tower Climber, Cozy Fantasy). Also supports Chinese web novel genres (xuanhuan, xianxia, urban, horror, other). Multi-agent pipeline, two-phase writer (creative + settlement), stronger long-form chapter craft rules, hook-ledger payoff checks, 33-dimension auditing, token usage analytics, creative brief input, structured logging (JSON Lines), multi-model routing, custom OpenAI-compatible provider support, and InkOS Studio web UI for visual book management, short-fiction runs, cover generation, chapter review, real-time writing progress, market radar, and analytics.
+description: Local AI fiction creation system with Studio Chat, CLI, and TUI - use for long-form novel writing, standalone short-fiction packages, cover generation, open-world / branching interactive fiction, fan fiction, spinoffs, style imitation, chapter continuation/import, EPUB export, AIGC detection, and project analytics. Native English support with 10 built-in English genre profiles (LitRPG, Progression Fantasy, Isekai, Cultivation, System Apocalypse, Dungeon Core, Romantasy, Sci-Fi, Tower Climber, Cozy Fantasy). Also supports Chinese web novel genres (xuanhuan, xianxia, urban, horror, other). Includes governed context assembly, protected/compressible context budgeting, chapter planning, writing, audit/revision, persistent world/truth state, multi-model routing, cover/image services, custom OpenAI-compatible providers, and InkOS Studio web UI for visual book management, Short runs, Play worlds, cover generation, chapter review, market radar, and analytics.
 version: 2.3.4
 metadata: { "openclaw": { "emoji": "📖", "requires": { "bins": ["inkos", "node"], "env": ["OPENAI_API_KEY"] }, "primaryEnv": "OPENAI_API_KEY", "homepage": "https://github.com/Narcooo/inkos", "install": [{ "id": "npm", "kind": "node", "package": "@actalk/inkos", "label": "Install InkOS (npm)" }] } }
 ---

-# InkOS - Autonomous Novel Writing Agent
+# InkOS - Local AI Fiction Creation System

-InkOS is a CLI tool for autonomous fiction writing powered by LLM agents. It orchestrates a multi-agent pipeline (Radar → Planner → Composer → Architect → Writer → Observer → Reflector → Normalizer → Auditor → Reviser) to generate, audit, and revise novel content with zero human intervention per chapter.
+InkOS is a local creation system for novels, short fiction, covers, and interactive worlds. Prefer the Studio Chat / action-surface workflow for natural-language requests: the model proposes or invokes typed actions, InkOS executes them, and completion is derived from real tool results and files, not from prose claims.

-The pipeline operates in three phases:
- **Phase 1 (Creative Writing, temp 0.7)**: Planner generates chapter intent with hook agenda, Composer selects relevant context, Writer produces prose with length governance, first-screen hooks, semantic density, hook-ledger payoff, and mobile paragraph rhythm guidance.
- **Phase 2 (State Settlement, temp 0.3)**: Observer over-extracts 9 categories of facts, Reflector outputs a JSON delta (not full markdown), code-layer applies Zod schema validation and immutable state update. Hook operations use upsert/mention/resolve/defer semantics.
- **Phase 3 (Quality Loop)**: Normalizer adjusts chapter length, Auditor runs 33-dimension check including hook health analysis, Reviser auto-fixes critical issues. Self-correction loop runs until all critical issues clear.
+Long-form writing still uses the chapter pipeline internally:
+- **Input governance**: Architect / Planner / Composer preserve author intent, current focus, outline sections, and relevant truth files instead of injecting everything blindly.
+- **Writing**: Writer produces prose with length governance, craft rules, and context selected for the current task.
+- **Settlement and review**: Observer / Reflector update runtime state; Auditor checks continuity and quality; Reviser handles critical issues. The default write cycle keeps automatic repair conservative and leaves unresolved issues visible for human or agent follow-up.

 Truth files are persisted as schema-validated JSON (`story/state/*.json`) with markdown projections for human readability. SQLite temporal memory database (`story/memory.db`) enables relevance-based retrieval on Node 22+.

+## v1.5.0 Mental Model
+
+Treat InkOS as a confirmable action system, not a bag of prompt shortcuts.
+
+- Natural-language requests should go through Studio Chat / TUI / `inkos interact` whenever possible.
+- Do not infer success from assistant prose. A book, short, cover, or play step is complete only when the corresponding tool result and files exist.
+- Use `short_fiction_run` only for a standalone short-fiction package.
+- Use `generate_cover` only for cover generation/regeneration.
+- Use `play_start` / `play_step` for Open World or Branching Interactive sessions.
+- Use long-form chapter tools only for existing long-form books.
+- Context is governed: protected facts and current intent should not be silently compressed away; compressible history may be summarized when the context budget is tight.
+
+v1.5 broadly improves instruction following, context management, weak-model formatting resilience, and error separation between InkOS execution, provider calls, and image generation. Still surface unresolved audit issues plainly instead of claiming they were fixed.
+
 ## When to Use InkOS

 - **English novel writing**: Native English support with 10 genre profiles (LitRPG, Progression Fantasy, Isekai, etc.). Set `--lang en`
@@ -27,6 +41,7 @@ Truth files are persisted as schema-validated JSON (`story/state/*.json`) with m
 - **Spinoff writing**: Write prequels/sequels/spinoffs while maintaining parent canon
 - **Standalone short fiction**: Generate a complete short-fiction package with outline, draft, review artifacts, synopsis, selling points, and optional cover image
 - **Cover generation**: Generate or regenerate only a cover prompt and cover image from a title, synopsis, or visual direction without rerunning story writing
+- **Interactive worlds**: Start Open World or Branching Interactive sessions with world contracts, character agents, inventory/evidence/relationship state, guided choices, free actions, and optional image generation
 - **Quality auditing**: Detect AI-generated content and perform 33-dimension quality checks
 - **Genre exploration**: Explore trends and create custom genre rules
 - **Analytics**: Track word count, audit pass rate, and issue distribution per book
@@ -118,7 +133,7 @@ inkos status
   ```bash
   inkos write next book-id --count 3 --words 2500 --context "protagonist faces critical choice"
   ```
-   - InkOS maintains 7 truth files (world state, character matrix, emotional arcs, etc.) for consistency
+   - InkOS maintains structured runtime state, readable Markdown projections, control docs, and temporal memory for consistency
   - If only one book exists, omit `book-id` for auto-detection

 3. **Review and approve**:
@@ -133,16 +148,14 @@ When InkOS is being driven by OpenClaw or another external agent, prefer the sha
 ```bash
 inkos interact --json --message "continue the current book, but keep the pacing tighter"
 inkos interact --json --message "rewrite chapter 3"
-inkos interact --json --book my-book --message "switch to auto mode"
+inkos interact --json --message "start an open-world detective game about a locked archive room"
 ```

-This returns a structured payload containing:
- the routed request
+The current JSON payload contains:
 - assistant response text
- updated interaction session
- execution state
- pending decision
- recent interaction events
+- interaction session id / session kind / active book id when bound
+
+Real completion still comes from tool results and files. Do not treat assistant prose alone as proof that a book, chapter, short, cover, or play step was created.

 Use this as the primary OpenClaw entry because it shares the same control layer as the project TUI.

@@ -207,7 +220,7 @@ Use this when you have an existing novel (or partial novel) and want InkOS to pi
   ```bash
   inkos write next book-id --count 3
   ```
-   - InkOS reverse-engineers all 7 truth files from the imported chapters
+   - InkOS rebuilds structured state, chapter summaries, hooks, character relationships, readable projections, and a style guide from the imported chapters
   - Generates a style guide from the existing text
   - New chapters maintain consistency with imported content

@@ -322,32 +335,30 @@ inkos fanfic init --title "What If" --from source.txt --mode au --genre other
 - Fanfic-specific audit dimensions and information boundary controls
 - Ensures new content stays consistent with source canon (or deliberately diverges in au/ooc modes)

-### Workflow 12: Rename Characters or Entities Across Entire Book
+### Workflow 12: Edit Persistent Text Through Chat
+
+Use Studio Chat or `inkos interact` for small, explicit edits to generated text artifacts. Treat the chat layer like an external editor: it may edit persisted files, then the writing pipeline can continue from the updated state.

 ```bash
-# Via interact
-inkos interact --json --message "把林烬改成张三"
-inkos interact --json --message "rename Lin Jin to Zhang San"
-
-# Via slash command
-inkos interact --json --message "/rename 林烬 => 张三"
+inkos interact --book my-book --json --message "把第 3 章里那句过长的解释删短一点，但不要改剧情事实"
+inkos interact --json --message "把 covers/demo/cover-prompt.md 里的人物拉近一点，标题字更大"
 ```
- Scans all chapters + all truth files (story_bible, current_state, character_matrix, etc.)
- Replaces every occurrence in one pass
- Returns count of files touched
+- Use for clear text edits, cover prompt edits, and control-document edits.
+- Do not infer success from the assistant's prose; check the tool result or changed file.
+- For broad story direction changes, prefer updating `author_intent.md` / `current_focus.md`, then run `plan` / `compose` before writing.

-### Workflow 13: Patch Specific Text in a Chapter
+### Workflow 13: Explicit Rename / Replacement Requests

-```bash
-inkos interact --json --message "/replace 5 旧文本 => 新文本"
-```
- Precisely replaces text in chapter 5 only
- Marks chapter for review after patching
+When the user asks for a rename or targeted replacement, keep the request explicit and scoped. Prefer Studio Chat / `inkos interact` over hidden slash shortcuts; the agent should route the edit through the shared action surface and report which file changed.
+
+Examples:
+- "把当前书里角色 林烬 改成 张三，先说明会影响哪些文件。"
+- "只改第 5 章，把这句旧文本换成新文本，改完标记需要复核。"

 ### Workflow 14: Interactive TUI Dashboard

 ```bash
-inkos
+inkos tui
 ```
 - Launches a full-screen Ink + React dashboard with conversational creation
 - Slash command autocomplete (Tab), input history (arrow keys)
@@ -396,12 +407,30 @@ The standalone cover tool writes:

 If cover image generation fails, report the provider/configuration error plainly. Do not rewrite the story, do not rerun `short_fiction_run`, and do not suggest unrelated external tools unless the user asks.

+### Workflow 17: Open World / Branching Interactive Play
+
+Use this when the user wants to play inside an interactive world instead of generating a finished manuscript.
+
+In Studio or agent mode, ask naturally:
+
+```text
+Create a Warcraft-like border watchtower open world. Time can advance differently by action: patrols take an hour, training can take days. Equipment should show rarity through material and atmosphere, not stat blocks.
+```
+
+For tool-using agents:
+- Call `play_start` when there is no active world/run yet, or when the user explicitly asks to start a new world.
+- Call `play_step` when the user performs an action inside an existing world.
+- Keep Open World free-form: do not force clickable choices unless the current session is Branching Interactive.
+- If the user changes world rules, persona, visual contract, or character behavior, treat it as a world-state edit or a new instruction for the next step, not as long-form chapter writing.
+- If image generation is configured, let Play generate scene / character / item / evidence images through the Play image path. Do not call the short-fiction cover tool for Play scene images.
+
 ## InkOS Studio (Web Workbench)

 `inkos studio` launches a local web UI (default port 4567) that provides a visual interface for all InkOS operations:

 - **Book management** — create, delete, export (TXT/MD/EPUB), configure per-book settings
 - **Short fiction & cover tools** — generate independent short-fiction packages, synopsis/selling points, cover prompts, and standalone covers
+- **Open World / Branching Interactive** — start and continue interactive worlds with world contracts, free actions, clickable choices, HUD state, and image generation
 - **Chapter review & editing** — approve/reject drafts, edit content inline, multi-mode revision (polish/spot-fix/rewrite/anti-detect)
 - **Real-time writing progress** — SSE-based live updates during chapter generation
 - **Market radar** — AI-powered trend analysis with platform/genre recommendations
@@ -411,14 +440,14 @@ If cover image generation fails, report the provider/configuration error plainly
 - **Genre management** — create/customize genre profiles with fatigue words, pacing rules, audit dimensions
 - **Daemon control** — start/stop background writing with event log
 - **Truth file editor** — view and edit canonical knowledge base per book
- **Config editor** — LLM provider, model routing, notifications
+- **Config editor** — LLM provider, model routing, cover/image services, notifications

 ```bash
 inkos studio              # Start on default port 4567
 inkos studio -p 8080      # Start on custom port
 ```

-The right-side **AI Assistant panel** in Studio shares the same interaction kernel as TUI and `inkos interact`. You can type natural language commands (rename entities, write chapters, audit, export) directly in the assistant panel.
+The **Studio Chat** surface shares the same action kernel as TUI and CLI. It can answer questions, propose/confirm creation actions, run Short, generate covers, start Play, edit persistent text artifacts, and invoke long-form writing operations.

 ## Advanced: Natural Language Agent Mode

@@ -450,7 +479,7 @@ These tools are the preferred control surface for chapter steering:
  - Rewrites `story/current_focus.md`
  - Use for local steering over the next 1-3 chapters

-## Short Fiction and Cover Agent Tools
+## Short Fiction, Cover, and Play Agent Tools

 These are the preferred tools when InkOS is driven by OpenClaw, Studio chat, or `inkos agent`:

@@ -467,6 +496,16 @@ These are the preferred tools when InkOS is driven by OpenClaw, Studio chat, or
  - Also use when the user changes the cover prompt through chat; pass the revised visual direction as `coverPrompt` and reuse the existing `outputDir` when available
  - Do not rerun story generation unless the user explicitly asks for a new story

+- `play_start`
+  - Starts a new Open World or Branching Interactive run
+  - Use when the user asks to play in a world, simulate an interactive story, create a game-like scene, or start a free-action/choice-based session
+  - The user's world contract should carry time rules, character agency, item/evidence rules, tone, genre, and visual style when provided
+
+- `play_step`
+  - Advances an existing Play run by one user action
+  - Use for free-form actions such as "inspect the letter", "talk to the guard", "train for three days", or "choose option 2"
+  - Do not use it to write the next chapter of a long-form book
+
 `write_truth_file` remains available for broad file edits, but prefer the dedicated control tools above for input-governance changes.

 ## Key Concepts
@@ -487,28 +526,24 @@ All content-generating commands support `--json` for structured output. Essentia
 inkos draft book-id --words 3000 --context "guidance" --json
 ```

-### Truth Files (Long-Term Memory)
-InkOS maintains 7 files per book for coherence:
- **World State**: Maps, locations, technology levels, magic systems
- **Character Matrix**: Names, relationships, arcs, motivations
- **Resource Ledger**: In-world items, money, power levels
- **Chapter Summaries**: Events, progression, foreshadowing
- **Subplot Board**: Active and dormant subplots, hooks
- **Emotional Arcs**: Character emotional progression
- **Pending Hooks**: Unresolved cliffhangers and promises to reader
+### Long-Term Memory
+InkOS maintains each book's memory in three layers:
+- **Structured state**: `story/state/*.json` is the authoritative runtime state, validated by Zod schemas.
+- **Readable projections**: `current_state.md`, `pending_hooks.md`, `chapter_summaries.md`, `character_matrix.md`, and related Markdown files are for humans and debugging.
+- **Temporal memory**: `story/memory.db` on Node 22+ supports relevance-based retrieval of facts, hooks, and chapter summaries.

-All agents reference these to maintain long-term consistency. Since 0.6.0, truth files are backed by schema-validated JSON in `story/state/` with automatic bootstrap from markdown for legacy books. During `import chapters`, these files are reverse-engineered from existing content via the ChapterAnalyzerAgent.
+Agents use the governed composer to select the relevant parts for the current task instead of blindly injecting every file. During `import chapters`, InkOS rebuilds structured state and projections from existing content via the ChapterAnalyzerAgent.

 ### Multi-Phase Writer Architecture
 The Writer operates across multiple phases with specialized agents:
 - **Planner**: Generates chapter intent with structured hook agenda (mustAdvance, eligibleResolve, staleDebt) based on memory retrieval.
- **Composer**: Selects relevant context from truth files by relevance scoring, compiles rule stack and runtime artifacts.
+- **Composer**: Selects relevant context from structured state, control docs, readable projections, and retrieval results, then compiles rule stack and runtime artifacts.
 - **Phase 1 (Creative, temp 0.7)**: Generates prose with length governance, English variance brief (anti-repetition), and dialogue-driven guidance.
 - **Phase 2a (Observer, temp 0.5)**: Over-extracts 9 categories of facts from the chapter text.
 - **Phase 2b (Reflector, temp 0.3)**: Outputs a JSON delta with hookOps (upsert/mention/resolve/defer), currentStatePatch, and chapterSummary. Code-layer validates via Zod schema and applies immutably.
 - **Normalizer**: Single-pass compress/expand to bring chapter length into the target band. Safety net rejects destructive normalization (>75% content loss).
 - **Auditor**: 33-dimension check including hook health analysis (stale debt, burst detection, no-advance warnings).
- **Reviser**: Auto-fixes critical issues, self-correction loop until clean.
+- **Reviser**: Attempts one configured repair pass for critical issues, then keeps unresolved findings visible for human or agent follow-up.

 Truth files use structured JSON (`story/state/*.json`) as the authoritative source, with markdown projections for human readability. Hook admission control prevents duplicate/family hooks from inflating the hook table.

@@ -580,11 +615,11 @@ inkos genre copy xuanhuan
 | `inkos compose chapter [book-id]` | Generate runtime artifacts | Context, rule-stack, trace for next chapter |
 | `inkos consolidate [book-id]` | Consolidate chapter summaries | Reduces context for long books (volume-level summaries) |
 | `inkos eval [book-id]` | Quality evaluation report | `--json`, `--chapters <range>`. Composite quality score |
-| `inkos studio` | Start web workbench | `-p` for port. Local web UI for book management |
+| `inkos` / `inkos studio` | Start web workbench | `-p` for port. Local web UI for book management |
 | `inkos fanfic show [book-id]` | Display parsed fanfic canon | Shows imported source material analysis |
 | `inkos fanfic refresh [book-id]` | Re-import and regenerate fanfic canon | `--from <file>` for updated source material |
 | `inkos interact` | Shared interaction endpoint | `--json`, `--message`, `--book`. Primary entry for OpenClaw |
-| `inkos` (no args) | Launch TUI dashboard | Full-screen Ink + React interactive dashboard |
+| `inkos tui` | Launch TUI dashboard | Full-screen Ink + React interactive dashboard |

 ## Error Handling

@@ -642,7 +677,7 @@ inkos down
 - **No install hooks**: npm package has no `preinstall`/`postinstall`/`install` scripts. Install is inert.
 - **Local-only file I/O**: all read/write stays inside the project directory (`books/*`, `inkos.json`, `inkos.log`). No writes outside the working directory.
 - **No telemetry**: InkOS does not phone home, collect usage stats, or ship any data to InkOS-controlled servers. The only outbound traffic is to the LLM provider endpoint you explicitly configure.
- **Credential handling**: always prefer `--api-key-env <VAR_NAME>` over `--api-key <literal>` so keys never hit shell history. Keys are stored in `inkos.json` under your project directory — treat it like a secret and add it to `.gitignore` if you commit the project.
+- **Credential handling**: prefer Studio service settings or `--api-key-env <VAR_NAME>` over literal keys. Studio stores service secrets in project-local `.inkos/secrets.json`; CLI env settings live in `~/.inkos/.env` or project `.env`. Treat all of these as secrets and keep them out of commits.
 - **Custom provider base-URL**: `--provider custom` forwards your API key to whatever URL you specify. Only point it at endpoints you trust (your own proxy or an audited reverse-proxy). Never paste an untrusted `--base-url`.
 - **No elevated privileges**: InkOS requires no sudo, no global state mutation, no network listening port (Studio binds `localhost:4567` only).