InkOS - Autonomous Novel Writing Agent
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.
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 and dialogue-driven 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.
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+.
When to Use InkOS
- English novel writing: Native English support with 10 genre profiles (LitRPG, Progression Fantasy, Isekai, etc.). Set
--lang en
- Chinese web novel writing: 5 built-in Chinese genres (xuanhuan, xianxia, urban, horror, other)
- Fan fiction: Create fanfic from source material with 4 modes (canon, au, ooc, cp)
- Batch chapter generation: Generate multiple chapters with consistent quality
- Import & continue: Import existing chapters from a text file, reverse-engineer truth files, and continue writing
- Style imitation: Analyze and adopt writing styles from reference texts
- Spinoff writing: Write prequels/sequels/spinoffs while maintaining parent canon
- 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
Initial Setup
First Time Setup
# Initialize a project directory (creates config structure)
inkos init my-writing-project
# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)
inkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key sk-xxx --model gpt-4o
# For compatible/proxy endpoints, use --provider custom:
# inkos config set-global --provider custom --base-url https://your-proxy.com/v1 --api-key sk-xxx --model gpt-4o
Multi-Model Routing (Optional)
# Assign different models to different agents — balance quality and cost
inkos config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY
inkos config set-model auditor gpt-4o --provider openai
inkos config show-models
Agents without explicit overrides fall back to the global model.
View System Status
# Check installation and configuration
inkos doctor
# View current config
inkos status
Common Workflows
Workflow 1: Create a New Novel
Initialize and create book:
inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000
# Or with a creative brief (your worldbuilding doc / ideas):
inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 --brief my-ideas.md
- Genres:
xuanhuan (cultivation), xianxia (immortal), urban (city), horror, other
- Returns a
book-id for all subsequent operations
Generate initial chapters (e.g., 5 chapters):
inkos write next book-id --count 5 --words 3000 --context "young protagonist discovering powers"
- The
write next command runs the full pipeline: draft → audit → revise
--context provides guidance to the Architect and Writer agents
- Returns JSON with chapter details and quality metrics
Review and approve chapters:
inkos review list book-id
inkos review approve-all book-id
Export the book (supports txt, md, epub):
inkos export book-id
inkos export book-id --format epub
Workflow 2: Continue Writing Existing Novel
List your books:
inkos book list
Continue from last chapter:
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
- If only one book exists, omit
book-id for auto-detection
Review and approve:
inkos review approve-all
Workflow 2.5: Steering Chapter Focus Before Writing
Use this when the user says things like "pull focus back to the mentor conflict", "pause the merchant guild subplot", or "change what the next chapter should prioritize".
Update the book-level control docs when needed:
- Use
update_author_intent to change the long-horizon identity of the book
- Use
update_current_focus to change the next 1-3 chapters' focus
Compile the next chapter intent:
plan_chapter(bookId, guidance?)
- Generates
story/runtime/chapter-XXXX.intent.md
- Use this to verify what the system thinks the next chapter should do
Compose the actual runtime input package:
compose_chapter(bookId, guidance?)
- Generates
story/runtime/chapter-XXXX.context.json
- Generates
story/runtime/chapter-XXXX.rule-stack.yaml
- Generates
story/runtime/chapter-XXXX.trace.json
Only then write:
write_draft if the user wants intermediate review
write_full_pipeline if they want the usual write → audit → revise flow
Recommended orchestration:
- user asks to redirect focus
update_current_focus
plan_chapter
compose_chapter
- inspect the resulting intent/paths
write_draft or write_full_pipeline
Workflow 3: Import Existing Chapters & Continue
Use this when you have an existing novel (or partial novel) and want InkOS to pick up where it left off.
Import from a single text file (auto-splits by chapter headings):
inkos import chapters book-id --from novel.txt
- Automatically splits by
第X章 pattern
- Custom split pattern:
--split "Chapter\\s+\\d+"
Import from a directory of separate chapter files:
inkos import chapters book-id --from ./chapters/
- Reads
.md and .txt files in sorted order
Resume interrupted import:
inkos import chapters book-id --from novel.txt --resume-from 15
Continue writing from the imported chapters:
inkos write next book-id --count 3
- InkOS reverse-engineers all 7 truth files from the imported chapters
- Generates a style guide from the existing text
- New chapters maintain consistency with imported content
Workflow 4: Style Imitation
Analyze reference text:
inkos style analyze reference_text.txt
- Examines vocabulary, sentence structure, tone, pacing
Import style to your book:
inkos style import reference_text.txt book-id --name "Author Name"
- All future chapters adopt this style profile
- Style rules become part of the Reviser's audit criteria
Workflow 5: Spinoff/Prequel Writing
Import parent canon:
inkos import canon spinoff-book-id --from parent-book-id
- Creates links to parent book's world state, characters, and events
- Reviser enforces canon consistency
Continue spinoff:
inkos write next spinoff-book-id --count 3 --context "alternate timeline after Chapter 20"
Workflow 6: Fine-Grained Control (Draft → Audit → Revise)
If you need separate control over each pipeline stage:
Generate draft only:
inkos draft book-id --words 3000 --context "protagonist escapes" --json
Audit the chapter (33-dimension quality check):
inkos audit book-id chapter-1 --json
- Returns metrics across 33 dimensions including pacing, dialogue, world-building, outline adherence, and more
Revise with specific mode:
inkos revise book-id chapter-1 --mode polish --json
- Modes:
polish (minor), spot-fix (targeted), rewrite (major), rework (structure), anti-detect (reduce AI traces)
Workflow 7: Monitor Platform Trends
inkos radar scan
- Analyzes trending genres, tropes, and reader preferences
- Informs Architect recommendations for new books
Workflow 8: Detect AI-Generated Content
# Detect AIGC in a specific chapter
inkos detect book-id
# Deep scan all chapters
inkos detect book-id --all
- Uses 11 deterministic rules (zero LLM cost) + optional LLM validation
- Returns detection confidence and problematic passages
Workflow 9: View Analytics
inkos analytics book-id --json
# Shorthand alias
inkos stats book-id --json
- Total chapters, word count, average words per chapter
- Audit pass rate and top issue categories
- Chapters with most issues, status distribution
- Token usage stats: total prompt/completion tokens, avg tokens per chapter, recent trend
Workflow 10: Write an English Novel
# Create an English LitRPG novel (language auto-detected from genre)
inkos book create --title "The Last Delver" --genre litrpg --chapter-words 3000
# Or set language explicitly
inkos book create --title "My Novel" --genre other --lang en
# Set English as default for all projects
inkos config set-global --lang en
- 10 English genres: litrpg, progression, isekai, cultivation, system-apocalypse, dungeon-core, romantasy, sci-fi, tower-climber, cozy
- Each genre has dedicated pacing rules, fatigue word lists (e.g., "delve", "tapestry", "testament"), and audit dimensions
- Use
inkos genre list to see all available genres
Workflow 11: Fan Fiction
# Create a fanfic from source material
inkos fanfic init --title "My Fanfic" --from source-novel.txt --mode canon
# Modes: canon (faithful), au (alternate universe), ooc (out of character), cp (ship-focused)
inkos fanfic init --title "What If" --from source.txt --mode au --genre other
- Imports and analyzes source material automatically
- Fanfic-specific audit dimensions and information boundary controls
- Ensures new content stays consistent with source canon (or deliberately diverges in au/ooc modes)
Advanced: Natural Language Agent Mode
For flexible, conversational requests:
inkos agent "写一部都市题材的小说,主角是一个年轻律师,第一章三千字"
- Agent interprets natural language and invokes appropriate commands
- Useful for complex multi-step requests
Input Governance Tools
These tools are the preferred control surface for chapter steering:
plan_chapter(bookId, guidance?)
- Generates chapter intent for the next chapter
- Use before writing when the user wants to change focus
compose_chapter(bookId, guidance?)
- Generates runtime context/rule-stack/trace artifacts
- Use after planning and before writing
update_author_intent(bookId, content)
- Rewrites
story/author_intent.md
- Use for long-horizon changes to the book's identity
update_current_focus(bookId, content)
- Rewrites
story/current_focus.md
- Use for local steering over the next 1-3 chapters
write_truth_file remains available for broad file edits, but prefer the dedicated control tools above for input-governance changes.
Key Concepts
Book ID Auto-Detection
If your project contains only one book, most commands accept book-id as optional. You can omit it for brevity:
# Explicit
inkos write next book-123 --count 1
# Auto-detected (if only one book exists)
inkos write next --count 1
--json Flag
All content-generating commands support --json for structured output. Essential for programmatic use:
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
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.
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.
- 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.
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.
Context Guidance
The --context parameter provides directional hints to the Writer and Architect:
inkos write next book-id --count 2 --context "protagonist discovers betrayal, must decide whether to trust mentor"
- Context is optional but highly recommended for narrative coherence
- Supports both English and Chinese
Genre Management
View Built-In Genres
inkos genre list
inkos genre show xuanhuan
Create Custom Genre
inkos genre create my-genre --name "My Genre"
# Options: --numerical, --power, --era
inkos genre create dark-xuanhuan --name "Dark Xuanhuan" --numerical --power
Copy Built-in Genre for Customization
inkos genre copy xuanhuan
# Copies to project genres/ directory for editing
Command Reference Summary
| Command |
Purpose |
Notes |
inkos init [name] |
Initialize project |
One-time setup |
inkos book create |
Create new book |
Returns book-id. --brief <file>, --lang en/zh, --genre litrpg/progression/... |
inkos book list |
List all books |
Shows IDs, statuses |
inkos write next |
Full pipeline (draft→audit→revise) |
Primary workflow command |
inkos draft |
Generate draft only |
No auditing/revision |
inkos audit |
33-dimension quality check |
Standalone evaluation |
inkos revise |
Revise chapter |
Modes: polish/spot-fix/rewrite/rework/anti-detect |
inkos agent |
Natural language interface |
Flexible requests |
inkos style analyze |
Analyze reference text |
Extracts style profile |
inkos style import |
Apply style to book |
Makes style permanent |
inkos import canon |
Link spinoff to parent |
For prequels/sequels |
inkos import chapters |
Import existing chapters |
Reverse-engineers truth files for continuation |
inkos detect |
AIGC detection |
Flags AI-generated passages |
inkos export |
Export finished book |
Formats: txt, md, epub |
inkos analytics / inkos stats |
View book statistics |
Word count, audit rates, token usage |
inkos radar scan |
Platform trend analysis |
Informs new book ideas |
inkos config set-global |
Configure LLM provider |
OpenAI/Anthropic/custom (any OpenAI-compatible) |
inkos config set-model <agent> <model> |
Set model override for a specific agent |
--provider, --base-url, --api-key-env for multi-provider routing |
inkos config show-models |
Show current model routing |
View per-agent model assignments |
inkos doctor |
Diagnose issues |
Check installation |
inkos update |
Update to latest version |
Self-update |
inkos up/down |
Daemon mode |
Background processing. Logs to inkos.log (JSON Lines). -q for quiet mode |
inkos review list/approve-all |
Manage chapter approvals |
Quality gate |
inkos fanfic init |
Create fanfic from source material |
--from <file>, --mode canon/au/ooc/cp |
inkos genre list |
List all available genres |
Shows English and Chinese genres with default language |
inkos genre create <id> |
Create custom genre profile |
--name, --numerical, --power, --era |
inkos genre copy <id> |
Copy built-in genre to project |
For customization |
inkos write rewrite <book> <ch> |
Rewrite a specific chapter |
Deletes chapter and later, rewrites from that point |
inkos book update [book-id] |
Update book settings |
--chapter-words, --target-chapters, --status, --lang |
inkos book delete <book-id> |
Delete book and all chapters |
--force to skip confirmation |
inkos plan chapter [book-id] |
Generate chapter intent |
Preview what next chapter will do before writing |
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 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 |
Error Handling
Common Issues
"book-id not found"
- Verify the ID with
inkos book list
- Ensure you're in the correct project directory
"Provider not configured"
- Run
inkos config set-global with valid credentials
- Check API key and base URL with
inkos doctor
"Context invalid"
- Ensure
--context is a string (wrap in quotes if multi-word)
- Context can be in English or Chinese
"Audit failed"
- Check chapter for encoding issues
- Ensure chapter-words matches actual word count
- Try
inkos revise with --mode rewrite
"Book already has chapters" (import)
- Use
--resume-from <n> to append to existing chapters
- Or delete existing chapters first
Running Daemon Mode
For long-running operations:
# Start background daemon
inkos up
# Stop daemon
inkos down
# Daemon auto-processes queued chapters
Tips for Best Results
- Provide rich context: The more guidance in
--context, the more coherent the narrative
- Start with style: If imitating an author, run
inkos style import before generation
- Import first: For existing novels, use
inkos import chapters to bootstrap truth files before continuing
- Review regularly: Use
inkos review to catch issues early
- Monitor audits: Check
inkos audit metrics to understand quality bottlenecks
- Use spinoffs strategically: Import canon before writing prequels/sequels
- Batch generation: Generate multiple chapters together (better continuity)
- Check analytics: Use
inkos analytics to track quality trends over time
- Export frequently: Keep backups with
inkos export
Support & Resources
- Homepage: https://github.com/Narcooo/inkos
- Configuration: Stored in project root after
inkos init
- Truth files: Located in
books/<id>/story/ per book, with structured JSON in story/state/
- Logs: Check output of
inkos doctor for troubleshooting
1---2name: inkos3description: Autonomous novel writing CLI agent - use for creative fiction writing, 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), 33-dimension auditing, token usage analytics, creative brief input, structured logging (JSON Lines), multi-model routing, and custom OpenAI-compatible provider support.4version: 2.1.05metadata:6 source: https://skillmd.com/skills/leoyeai-openclaw-master-skills/inkos7 openclaw:8 emoji: 📖9 requires:10 bins:11 - inkos12 - node13 env: []14 primaryEnv: ""15 homepage: https://github.com/Narcooo/inkos16 install:17 - id: npm18 kind: node19 package: "@actalk/inkos"20 label: Install InkOS (npm)21---2223# InkOS - Autonomous Novel Writing Agent2425InkOS 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.2627The pipeline operates in three phases:28- **Phase 1 (Creative Writing, temp 0.7)**: Planner generates chapter intent with hook agenda, Composer selects relevant context, Writer produces prose with length governance and dialogue-driven guidance.29- **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.30- **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.3132Truth 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+.3334## When to Use InkOS3536- **English novel writing**: Native English support with 10 genre profiles (LitRPG, Progression Fantasy, Isekai, etc.). Set `--lang en`37- **Chinese web novel writing**: 5 built-in Chinese genres (xuanhuan, xianxia, urban, horror, other)38- **Fan fiction**: Create fanfic from source material with 4 modes (canon, au, ooc, cp)39- **Batch chapter generation**: Generate multiple chapters with consistent quality40- **Import & continue**: Import existing chapters from a text file, reverse-engineer truth files, and continue writing41- **Style imitation**: Analyze and adopt writing styles from reference texts42- **Spinoff writing**: Write prequels/sequels/spinoffs while maintaining parent canon43- **Quality auditing**: Detect AI-generated content and perform 33-dimension quality checks44- **Genre exploration**: Explore trends and create custom genre rules45- **Analytics**: Track word count, audit pass rate, and issue distribution per book4647## Initial Setup4849### First Time Setup50```bash51# Initialize a project directory (creates config structure)52inkos init my-writing-project5354# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)55inkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key sk-xxx --model gpt-4o56# For compatible/proxy endpoints, use --provider custom:57# inkos config set-global --provider custom --base-url https://your-proxy.com/v1 --api-key sk-xxx --model gpt-4o58```5960### Multi-Model Routing (Optional)61```bash62# Assign different models to different agents — balance quality and cost63inkos config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY64inkos config set-model auditor gpt-4o --provider openai65inkos config show-models66```67Agents without explicit overrides fall back to the global model.6869### View System Status70```bash71# Check installation and configuration72inkos doctor7374# View current config75inkos status76```7778## Common Workflows7980### Workflow 1: Create a New Novel81821. **Initialize and create book**:83 ```bash84 inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 300085 # Or with a creative brief (your worldbuilding doc / ideas):86 inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 --brief my-ideas.md87 ```88 - Genres: `xuanhuan` (cultivation), `xianxia` (immortal), `urban` (city), `horror`, `other`89 - Returns a `book-id` for all subsequent operations90912. **Generate initial chapters** (e.g., 5 chapters):92 ```bash93 inkos write next book-id --count 5 --words 3000 --context "young protagonist discovering powers"94 ```95 - The `write next` command runs the full pipeline: draft → audit → revise96 - `--context` provides guidance to the Architect and Writer agents97 - Returns JSON with chapter details and quality metrics98993. **Review and approve chapters**:100 ```bash101 inkos review list book-id102 inkos review approve-all book-id103 ```1041054. **Export the book** (supports txt, md, epub):106 ```bash107 inkos export book-id108 inkos export book-id --format epub109 ```110111### Workflow 2: Continue Writing Existing Novel1121131. **List your books**:114 ```bash115 inkos book list116 ```1171182. **Continue from last chapter**:119 ```bash120 inkos write next book-id --count 3 --words 2500 --context "protagonist faces critical choice"121 ```122 - InkOS maintains 7 truth files (world state, character matrix, emotional arcs, etc.) for consistency123 - If only one book exists, omit `book-id` for auto-detection1241253. **Review and approve**:126 ```bash127 inkos review approve-all128 ```129130### Workflow 2.5: Steering Chapter Focus Before Writing131132Use this when the user says things like "pull focus back to the mentor conflict", "pause the merchant guild subplot", or "change what the next chapter should prioritize".1331341. **Update the book-level control docs when needed**:135 - Use `update_author_intent` to change the long-horizon identity of the book136 - Use `update_current_focus` to change the next 1-3 chapters' focus1371382. **Compile the next chapter intent**:139 ```text140 plan_chapter(bookId, guidance?)141 ```142 - Generates `story/runtime/chapter-XXXX.intent.md`143 - Use this to verify what the system thinks the next chapter should do1441453. **Compose the actual runtime input package**:146 ```text147 compose_chapter(bookId, guidance?)148 ```149 - Generates `story/runtime/chapter-XXXX.context.json`150 - Generates `story/runtime/chapter-XXXX.rule-stack.yaml`151 - Generates `story/runtime/chapter-XXXX.trace.json`1521534. **Only then write**:154 - `write_draft` if the user wants intermediate review155 - `write_full_pipeline` if they want the usual write → audit → revise flow156157Recommended orchestration:158- user asks to redirect focus159- `update_current_focus`160- `plan_chapter`161- `compose_chapter`162- inspect the resulting intent/paths163- `write_draft` or `write_full_pipeline`164165### Workflow 3: Import Existing Chapters & Continue166167Use this when you have an existing novel (or partial novel) and want InkOS to pick up where it left off.1681691. **Import from a single text file** (auto-splits by chapter headings):170 ```bash171 inkos import chapters book-id --from novel.txt172 ```173 - Automatically splits by `第X章` pattern174 - Custom split pattern: `--split "Chapter\\s+\\d+"`1751762. **Import from a directory** of separate chapter files:177 ```bash178 inkos import chapters book-id --from ./chapters/179 ```180 - Reads `.md` and `.txt` files in sorted order1811823. **Resume interrupted import**:183 ```bash184 inkos import chapters book-id --from novel.txt --resume-from 15185 ```1861874. **Continue writing** from the imported chapters:188 ```bash189 inkos write next book-id --count 3190 ```191 - InkOS reverse-engineers all 7 truth files from the imported chapters192 - Generates a style guide from the existing text193 - New chapters maintain consistency with imported content194195### Workflow 4: Style Imitation1961971. **Analyze reference text**:198 ```bash199 inkos style analyze reference_text.txt200 ```201 - Examines vocabulary, sentence structure, tone, pacing2022032. **Import style to your book**:204 ```bash205 inkos style import reference_text.txt book-id --name "Author Name"206 ```207 - All future chapters adopt this style profile208 - Style rules become part of the Reviser's audit criteria209210### Workflow 5: Spinoff/Prequel Writing2112121. **Import parent canon**:213 ```bash214 inkos import canon spinoff-book-id --from parent-book-id215 ```216 - Creates links to parent book's world state, characters, and events217 - Reviser enforces canon consistency2182192. **Continue spinoff**:220 ```bash221 inkos write next spinoff-book-id --count 3 --context "alternate timeline after Chapter 20"222 ```223224### Workflow 6: Fine-Grained Control (Draft → Audit → Revise)225226If you need separate control over each pipeline stage:2272281. **Generate draft only**:229 ```bash230 inkos draft book-id --words 3000 --context "protagonist escapes" --json231 ```2322332. **Audit the chapter** (33-dimension quality check):234 ```bash235 inkos audit book-id chapter-1 --json236 ```237 - Returns metrics across 33 dimensions including pacing, dialogue, world-building, outline adherence, and more2382393. **Revise with specific mode**:240 ```bash241 inkos revise book-id chapter-1 --mode polish --json242 ```243 - Modes: `polish` (minor), `spot-fix` (targeted), `rewrite` (major), `rework` (structure), `anti-detect` (reduce AI traces)244245### Workflow 7: Monitor Platform Trends246247```bash248inkos radar scan249```250- Analyzes trending genres, tropes, and reader preferences251- Informs Architect recommendations for new books252253### Workflow 8: Detect AI-Generated Content254255```bash256# Detect AIGC in a specific chapter257inkos detect book-id258259# Deep scan all chapters260inkos detect book-id --all261```262- Uses 11 deterministic rules (zero LLM cost) + optional LLM validation263- Returns detection confidence and problematic passages264265### Workflow 9: View Analytics266267```bash268inkos analytics book-id --json269# Shorthand alias270inkos stats book-id --json271```272- Total chapters, word count, average words per chapter273- Audit pass rate and top issue categories274- Chapters with most issues, status distribution275- **Token usage stats**: total prompt/completion tokens, avg tokens per chapter, recent trend276277### Workflow 10: Write an English Novel278279```bash280# Create an English LitRPG novel (language auto-detected from genre)281inkos book create --title "The Last Delver" --genre litrpg --chapter-words 3000282283# Or set language explicitly284inkos book create --title "My Novel" --genre other --lang en285286# Set English as default for all projects287inkos config set-global --lang en288```289- 10 English genres: litrpg, progression, isekai, cultivation, system-apocalypse, dungeon-core, romantasy, sci-fi, tower-climber, cozy290- Each genre has dedicated pacing rules, fatigue word lists (e.g., "delve", "tapestry", "testament"), and audit dimensions291- Use `inkos genre list` to see all available genres292293### Workflow 11: Fan Fiction294295```bash296# Create a fanfic from source material297inkos fanfic init --title "My Fanfic" --from source-novel.txt --mode canon298299# Modes: canon (faithful), au (alternate universe), ooc (out of character), cp (ship-focused)300inkos fanfic init --title "What If" --from source.txt --mode au --genre other301```302- Imports and analyzes source material automatically303- Fanfic-specific audit dimensions and information boundary controls304- Ensures new content stays consistent with source canon (or deliberately diverges in au/ooc modes)305306## Advanced: Natural Language Agent Mode307308For flexible, conversational requests:309310```bash311inkos agent "写一部都市题材的小说,主角是一个年轻律师,第一章三千字"312```313- Agent interprets natural language and invokes appropriate commands314- Useful for complex multi-step requests315316## Input Governance Tools317318These tools are the preferred control surface for chapter steering:319320- `plan_chapter(bookId, guidance?)`321 - Generates chapter intent for the next chapter322 - Use before writing when the user wants to change focus323324- `compose_chapter(bookId, guidance?)`325 - Generates runtime context/rule-stack/trace artifacts326 - Use after planning and before writing327328- `update_author_intent(bookId, content)`329 - Rewrites `story/author_intent.md`330 - Use for long-horizon changes to the book's identity331332- `update_current_focus(bookId, content)`333 - Rewrites `story/current_focus.md`334 - Use for local steering over the next 1-3 chapters335336`write_truth_file` remains available for broad file edits, but prefer the dedicated control tools above for input-governance changes.337338## Key Concepts339340### Book ID Auto-Detection341If your project contains only one book, most commands accept `book-id` as optional. You can omit it for brevity:342```bash343# Explicit344inkos write next book-123 --count 1345346# Auto-detected (if only one book exists)347inkos write next --count 1348```349350### --json Flag351All content-generating commands support `--json` for structured output. Essential for programmatic use:352```bash353inkos draft book-id --words 3000 --context "guidance" --json354```355356### Truth Files (Long-Term Memory)357InkOS maintains 7 files per book for coherence:358- **World State**: Maps, locations, technology levels, magic systems359- **Character Matrix**: Names, relationships, arcs, motivations360- **Resource Ledger**: In-world items, money, power levels361- **Chapter Summaries**: Events, progression, foreshadowing362- **Subplot Board**: Active and dormant subplots, hooks363- **Emotional Arcs**: Character emotional progression364- **Pending Hooks**: Unresolved cliffhangers and promises to reader365366All 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.367368### Multi-Phase Writer Architecture369The Writer operates across multiple phases with specialized agents:370- **Planner**: Generates chapter intent with structured hook agenda (mustAdvance, eligibleResolve, staleDebt) based on memory retrieval.371- **Composer**: Selects relevant context from truth files by relevance scoring, compiles rule stack and runtime artifacts.372- **Phase 1 (Creative, temp 0.7)**: Generates prose with length governance, English variance brief (anti-repetition), and dialogue-driven guidance.373- **Phase 2a (Observer, temp 0.5)**: Over-extracts 9 categories of facts from the chapter text.374- **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.375- **Normalizer**: Single-pass compress/expand to bring chapter length into the target band. Safety net rejects destructive normalization (>75% content loss).376- **Auditor**: 33-dimension check including hook health analysis (stale debt, burst detection, no-advance warnings).377- **Reviser**: Auto-fixes critical issues, self-correction loop until clean.378379Truth 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.380381### Context Guidance382The `--context` parameter provides directional hints to the Writer and Architect:383```bash384inkos write next book-id --count 2 --context "protagonist discovers betrayal, must decide whether to trust mentor"385```386- Context is optional but highly recommended for narrative coherence387- Supports both English and Chinese388389## Genre Management390391### View Built-In Genres392```bash393inkos genre list394inkos genre show xuanhuan395```396397### Create Custom Genre398```bash399inkos genre create my-genre --name "My Genre"400# Options: --numerical, --power, --era401inkos genre create dark-xuanhuan --name "Dark Xuanhuan" --numerical --power402```403404### Copy Built-in Genre for Customization405```bash406inkos genre copy xuanhuan407# Copies to project genres/ directory for editing408```409410## Command Reference Summary411412| Command | Purpose | Notes |413|---------|---------|-------|414| `inkos init [name]` | Initialize project | One-time setup |415| `inkos book create` | Create new book | Returns book-id. `--brief <file>`, `--lang en/zh`, `--genre litrpg/progression/...` |416| `inkos book list` | List all books | Shows IDs, statuses |417| `inkos write next` | Full pipeline (draft→audit→revise) | Primary workflow command |418| `inkos draft` | Generate draft only | No auditing/revision |419| `inkos audit` | 33-dimension quality check | Standalone evaluation |420| `inkos revise` | Revise chapter | Modes: polish/spot-fix/rewrite/rework/anti-detect |421| `inkos agent` | Natural language interface | Flexible requests |422| `inkos style analyze` | Analyze reference text | Extracts style profile |423| `inkos style import` | Apply style to book | Makes style permanent |424| `inkos import canon` | Link spinoff to parent | For prequels/sequels |425| `inkos import chapters` | Import existing chapters | Reverse-engineers truth files for continuation |426| `inkos detect` | AIGC detection | Flags AI-generated passages |427| `inkos export` | Export finished book | Formats: txt, md, epub |428| `inkos analytics` / `inkos stats` | View book statistics | Word count, audit rates, token usage |429| `inkos radar scan` | Platform trend analysis | Informs new book ideas |430| `inkos config set-global` | Configure LLM provider | OpenAI/Anthropic/custom (any OpenAI-compatible) |431| `inkos config set-model <agent> <model>` | Set model override for a specific agent | `--provider`, `--base-url`, `--api-key-env` for multi-provider routing |432| `inkos config show-models` | Show current model routing | View per-agent model assignments |433| `inkos doctor` | Diagnose issues | Check installation |434| `inkos update` | Update to latest version | Self-update |435| `inkos up/down` | Daemon mode | Background processing. Logs to `inkos.log` (JSON Lines). `-q` for quiet mode |436| `inkos review list/approve-all` | Manage chapter approvals | Quality gate |437| `inkos fanfic init` | Create fanfic from source material | `--from <file>`, `--mode canon/au/ooc/cp` |438| `inkos genre list` | List all available genres | Shows English and Chinese genres with default language |439| `inkos genre create <id>` | Create custom genre profile | `--name`, `--numerical`, `--power`, `--era` |440| `inkos genre copy <id>` | Copy built-in genre to project | For customization |441| `inkos write rewrite <book> <ch>` | Rewrite a specific chapter | Deletes chapter and later, rewrites from that point |442| `inkos book update [book-id]` | Update book settings | `--chapter-words`, `--target-chapters`, `--status`, `--lang` |443| `inkos book delete <book-id>` | Delete book and all chapters | `--force` to skip confirmation |444| `inkos plan chapter [book-id]` | Generate chapter intent | Preview what next chapter will do before writing |445| `inkos compose chapter [book-id]` | Generate runtime artifacts | Context, rule-stack, trace for next chapter |446| `inkos consolidate [book-id]` | Consolidate chapter summaries | Reduces context for long books (volume-level summaries) |447| `inkos eval [book-id]` | Quality evaluation report | `--json`, `--chapters <range>`. Composite quality score |448| `inkos studio` | Start web workbench | `-p` for port. Local web UI for book management |449| `inkos fanfic show [book-id]` | Display parsed fanfic canon | Shows imported source material analysis |450| `inkos fanfic refresh [book-id]` | Re-import and regenerate fanfic canon | `--from <file>` for updated source material |451452## Error Handling453454### Common Issues455456**"book-id not found"**457- Verify the ID with `inkos book list`458- Ensure you're in the correct project directory459460**"Provider not configured"**461- Run `inkos config set-global` with valid credentials462- Check API key and base URL with `inkos doctor`463464**"Context invalid"**465- Ensure `--context` is a string (wrap in quotes if multi-word)466- Context can be in English or Chinese467468**"Audit failed"**469- Check chapter for encoding issues470- Ensure chapter-words matches actual word count471- Try `inkos revise` with `--mode rewrite`472473**"Book already has chapters" (import)**474- Use `--resume-from <n>` to append to existing chapters475- Or delete existing chapters first476477### Running Daemon Mode478479For long-running operations:480```bash481# Start background daemon482inkos up483484# Stop daemon485inkos down486487# Daemon auto-processes queued chapters488```489490## Tips for Best Results4914921. **Provide rich context**: The more guidance in `--context`, the more coherent the narrative4932. **Start with style**: If imitating an author, run `inkos style import` before generation4943. **Import first**: For existing novels, use `inkos import chapters` to bootstrap truth files before continuing4954. **Review regularly**: Use `inkos review` to catch issues early4965. **Monitor audits**: Check `inkos audit` metrics to understand quality bottlenecks4976. **Use spinoffs strategically**: Import canon before writing prequels/sequels4987. **Batch generation**: Generate multiple chapters together (better continuity)4998. **Check analytics**: Use `inkos analytics` to track quality trends over time5009. **Export frequently**: Keep backups with `inkos export`501502## Support & Resources503504- **Homepage**: https://github.com/Narcooo/inkos505- **Configuration**: Stored in project root after `inkos init`506- **Truth files**: Located in `books/<id>/story/` per book, with structured JSON in `story/state/`507- **Logs**: Check output of `inkos doctor` for troubleshooting