/`\n\nThe standalone cover tool writes:\n- `covers/<title>/cover-prompt.md`\n- `covers/<title>/cover.png`\n\nIf 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.\n\n### Workflow 17: Open World / Branching Interactive Play\n\nUse this when the user wants to play inside an interactive world instead of generating a finished manuscript.\n\nIn Studio or agent mode, ask naturally:\n\n```text\nCreate 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.\n```\n\nFor tool-using agents:\n- Call `play_start` when there is no active world/run yet, or when the user explicitly asks to start a new world.\n- Call `play_step` when the user performs an action inside an existing world.\n- Keep Open World free-form: do not force clickable choices unless the current session is Branching Interactive.\n- 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.\n- 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.\n\n### Workflow 18: Agent Skills\n\nUse this when the user wants reusable professional rules, a domain-specific writing mode, or a forced capability for the current Chat turn.\n\nProject-local skills live at:\n\n```text\n.agents/skills/<skill-id>/SKILL.md\n```\n\nInkOS also discovers standard AgentSkills / OpenClaw locations (`skills/`, `.agents/skills/`, `~/.agents/skills/`, and `~/.openclaw/skills/`). Studio can import a complete skill folder with its static reference files.\n\nExternal skill directories can be loaded with:\n\n```bash\nexport INKOS_SKILL_DIRS=/abs/path/to/skills\n```\n\nGuidelines for agent orchestration:\n- Let the Chat Agent inspect the available skill catalog and call `use_skill` when the current user intent needs that expertise. Do not emulate this with session-kind routing, keyword lists, or substring matching.\n- Force a skill by including `@skill-id` in the user message when the user explicitly chooses one.\n- Treat skills as standard expertise packets containing instructions and static references. Prompt packs and governed context recipes are separate InkOS systems.\n- Skill folders may contain static references. Read them only when needed, and never auto-execute bundled scripts.\n- Do not treat skills as permissions. File edits, book creation, chapter writing, image generation, and exports still require the normal InkOS tools and confirmation gates.\n\n### Workflow 19: Traceable Web Research\n\nUse this when the user asks for real-world references, external facts, era/profession details, market references, or worldbuilding research.\n\nFor tool-using agents, call `research_web` with:\n- `topic` — the research question\n- `purpose` — `worldbuilding`, `era`, `profession`, `market`, `fact-check`, or `general`\n- `depth` — optional: `quick`, `standard`, or `deep`\n\nThe tool writes a Markdown report under:\n\n```text\n.inkos/research/\n```\n\nThe report includes sources, claims, unknowns, conflicts, query logs, and confidence. It is reference material only. If research should change canon, wait for explicit user confirmation and then use the normal truth-file editing path.\n\nSearch credentials are user/project supplied. Studio can configure a Tavily-compatible search API, or the server can use `TAVILY_API_KEY` from the environment.\n\n### Workflow 20: Script, Storyboard, and Interactive-Film Creation\n\nUse this when the user wants a production artifact rather than a casual answer:\n- Script: dramatic scenes, dialogue, acts, episode structure, or format-specific script drafts.\n- Storyboard: visual beats, shot descriptions, image prompts, and scene-by-scene production notes.\n- Interactive film: branch graph, choices, variables/flags, relationship state, endings, node images, and exportable project package.\n\nIn Studio Chat, these actions should be proposed with a confirmation card first. After confirmation, InkOS writes the artifact and reports the saved files. Do not hand-write a fake \"created\" result in prose.\n\n### Workflow 21: Multilingual Translation / Localization\n\nUse a translation project when the user wants a complete, reviewable deliverable rather than a one-off translated paragraph. Inputs can be EPUB, text-based PDF, TXT, or Markdown; source and target languages can be written as normal language names in Studio.\n\n```bash\ninkos translate init --from ./source.epub --source Chinese --target English\ninkos translate run <project-id>\ninkos translate export <project-id> --format epub\n```\n\n- Preserve the project glossary and chapter boundaries across translation batches.\n- Review source and translation side by side; treat the generated review report as the quality record.\n- Export TXT, Markdown, or EPUB only after the requested segments are complete.\n- For scanned PDFs without a text layer, run OCR before importing; InkOS currently reads text-based PDFs.\n\n## InkOS Studio (Web Workbench)\n\n`inkos studio` launches a local web UI (default port 4567) that provides a visual interface for all InkOS operations:\n\n- **Book management** — create, delete, export (TXT/MD/EPUB), configure per-book settings\n- **Short fiction & cover tools** — generate independent short-fiction packages, synopsis/selling points, cover prompts, and standalone covers\n- **Open World / Branching Interactive** — start and continue interactive worlds with world contracts, free actions, clickable choices, HUD state, and image generation\n- **Interactive-film workbench** — create and inspect branch nodes, variables/flags, endings, node images, and export packages\n- **Script / storyboard tools** — generate production-oriented script and storyboard files from ideas, prose, or reference notes\n- **Translation workbench** — import EPUB, text-based PDF, TXT, or Markdown; choose source and target languages; translate, compare, review, and export complete projects\n- **Agent Skills management** — list standard skills, import AgentSkills/OpenClaw folders with static references into `.agents/skills/`, let Chat invoke skills from intent, and force skills from Chat\n- **Research search provider** — configure external web search API credentials for `research_web`\n- **Chapter review & editing** — approve/reject drafts, edit content inline, and revise with polish/spot-fix/rewrite/rework modes\n- **Real-time writing progress** — SSE-based live updates during chapter generation\n- **Market radar** — AI-powered trend analysis with platform/genre recommendations\n- **Analytics** — word count, audit pass rate, chapter ranking, token usage\n- **AI detection** — scan chapters for AI-generated content\n- **Style analysis** — analyze reference texts and import writing styles\n- **Genre management** — create/customize genre profiles with fatigue words, pacing rules, audit dimensions\n- **Daemon control** — start/stop background writing with event log\n- **Truth file editor** — view and edit canonical knowledge base per book\n- **Config editor** — LLM provider, model routing, cover/image services, notifications\n\n```bash\ninkos studio # Start on default port 4567\ninkos studio -p 8080 # Start on custom port\n```\n\nThe **Studio Chat** surface shares the same action kernel as TUI and CLI. It can answer questions, propose/confirm creation and translation actions, run Short, generate covers, start Play, import existing novels, edit persistent text artifacts, and invoke long-form writing operations.\n\n## Advanced: Natural Language Agent Mode\n\nFor flexible, conversational requests:\n\n```bash\ninkos agent \"写一部都市题材的小说，主角是一个年轻律师，第一章三千字\"\n```\n- Agent interprets natural language and invokes appropriate commands\n- Useful for complex multi-step requests\n\n## Input Governance Tools\n\nThese tools are the preferred control surface for chapter steering:\n\n- `plan_chapter(bookId, guidance?)`\n - Generates chapter intent for the next chapter\n - Use before writing when the user wants to change focus\n\n- `compose_chapter(bookId, guidance?)`\n - Generates runtime context/rule-stack/trace artifacts\n - Use after planning and before writing\n\n- `update_author_intent(bookId, content)`\n - Rewrites `story/author_intent.md`\n - Use for long-horizon changes to the book's identity\n\n- `update_current_focus(bookId, content)`\n - Rewrites `story/current_focus.md`\n - Use for local steering over the next 1-3 chapters\n\n## Creative, Research, and Play Agent Tools\n\nThese are the preferred tools when InkOS is driven by OpenClaw, Studio chat, or `inkos agent`:\n\n- `short_fiction_run`\n - Creates an independent short-fiction package from a direction\n - Runs outline → outline review/revision → full draft → draft review/revision → synopsis/selling points/cover prompt → optional cover image\n - Writes to `shorts/<story-name>/`\n - Use only when the user asks for a separate complete short story / short-fiction deliverable\n\n- `generate_cover`\n - Generates only a cover prompt and cover image\n - Writes to `covers/<title>/` by default\n - Use when the user asks to create or regenerate a cover for an existing title, synopsis, or completed short\n - 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\n - Do not rerun story generation unless the user explicitly asks for a new story\n\n- `play_start`\n - Starts a new Open World or Branching Interactive run\n - 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\n - The user's world contract should carry time rules, character agency, item/evidence rules, tone, genre, and visual style when provided\n\n- `play_step`\n - Advances an existing Play run by one user action\n - Use for free-form actions such as \"inspect the letter\", \"talk to the guard\", \"train for three days\", or \"choose option 2\"\n - Do not use it to write the next chapter of a long-form book\n\n- `research_web`\n - Collects external sources and writes a traceable Markdown research report\n - Use only for explicit research/fact-check/worldbuilding/market requests\n - Never mutate canon or prose directly from research output without explicit user confirmation\n\n- Script / storyboard / interactive-film creation tools\n - Use when the user wants saved production artifacts\n - Preserve the user's requested format, market, target audience, and export needs\n - Do not use these tools for casual analysis unless the user asks to create deliverables\n\n`write_truth_file` remains available for broad file edits, but prefer the dedicated control tools above for input-governance changes.\n\n## Key Concepts\n\n### Book ID Auto-Detection\nIf your project contains only one book, most commands accept `book-id` as optional. You can omit it for brevity:\n```bash\n# Explicit\ninkos write next book-123 --count 1\n\n# Auto-detected (if only one book exists)\ninkos write next --count 1\n```\n\n### --json Flag\nAll content-generating commands support `--json` for structured output. Essential for programmatic use:\n```bash\ninkos draft book-id --words 3000 --context \"guidance\" --json\n```\n\n### Long-Term Memory\nInkOS maintains each book's memory in three layers:\n- **Structured state**: `story/state/*.json` is the authoritative runtime state, validated by Zod schemas.\n- **Readable projections**: `current_state.md`, `pending_hooks.md`, `chapter_summaries.md`, `character_matrix.md`, and related Markdown files are for humans and debugging.\n- **Temporal memory**: `story/memory.db` on Node 22+ supports relevance-based retrieval of facts, hooks, and chapter summaries.\n\nAgents 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.\n\n### Multi-Phase Writer Architecture\nThe Writer operates across multiple phases with specialized agents:\n- **Planner**: Generates chapter intent with structured hook agenda (mustAdvance, eligibleResolve, staleDebt) based on memory retrieval.\n- **Composer**: Selects relevant context from structured state, control docs, readable projections, and retrieval results, then compiles rule stack and runtime artifacts.\n- **Phase 1 (Creative, temp 0.7)**: Generates prose with length governance, English variance brief (anti-repetition), and dialogue-driven guidance.\n- **Phase 2a (Observer, temp 0.5)**: Over-extracts 9 categories of facts from the chapter text.\n- **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.\n- **Normalizer**: Single-pass compress/expand to bring chapter length into the target band. Safety net rejects destructive normalization (>75% content loss).\n- **Auditor**: 33-dimension check including hook health analysis (stale debt, burst detection, no-advance warnings).\n- **Reviser**: Attempts one configured repair pass for critical issues, then keeps unresolved findings visible for human or agent follow-up.\n\nTruth 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.\n\n### Context Guidance\nThe `--context` parameter provides directional hints to the Writer and Architect:\n```bash\ninkos write next book-id --count 2 --context \"protagonist discovers betrayal, must decide whether to trust mentor\"\n```\n- Context is optional but highly recommended for narrative coherence\n- Supports both English and Chinese\n\n## Genre Management\n\n### View Built-In Genres\n```bash\ninkos genre list\ninkos genre show xuanhuan\n```\n\n### Create Custom Genre\n```bash\ninkos genre create my-genre --name \"My Genre\"\n# Options: --numerical, --power, --era\ninkos genre create dark-xuanhuan --name \"Dark Xuanhuan\" --numerical --power\n```\n\n### Copy Built-in Genre for Customization\n```bash\ninkos genre copy xuanhuan\n# Copies to project genres/ directory for editing\n```\n\n## Command Reference Summary\n\n| Command | Purpose | Notes |\n|---------|---------|-------|\n| `inkos init [name]` | Initialize project | One-time setup |\n| `inkos book create` | Create new book | Returns book-id. `--brief <file>`, `--lang en/zh`, `--genre litrpg/progression/...` |\n| `inkos book list` | List all books | Shows IDs, statuses |\n| `inkos write next` | Full pipeline (draft→audit→revise) | Primary workflow command |\n| `inkos draft` | Generate draft only | No auditing/revision |\n| `inkos audit` | 33-dimension quality check | Standalone evaluation |\n| `inkos revise` | Revise chapter | Modes documented for agent use: polish/spot-fix/rewrite/rework |\n| `inkos agent` | Natural language interface | Flexible requests |\n| `inkos style analyze` | Analyze reference text | Extracts style profile |\n| `inkos style import` | Apply style to book | Makes style permanent |\n| `inkos import canon` | Link spinoff to parent | For prequels/sequels |\n| `inkos import chapters` | Import existing chapters | Reverse-engineers truth files for continuation |\n| `inkos detect` | AIGC detection | Flags AI-generated passages |\n| `inkos export` | Export finished book | Formats: txt, md, epub |\n| `inkos analytics` / `inkos stats` | View book statistics | Word count, audit rates, token usage |\n| `inkos radar scan` | Platform trend analysis | Informs new book ideas |\n| `inkos short run` | Generate standalone short fiction | Outputs manuscript, sales package, cover prompt, optional cover |\n| `inkos config set-global` | Configure LLM provider | OpenAI/Anthropic/custom (any OpenAI-compatible) |\n| `inkos config set-model <agent> <model>` | Set model override for a specific agent | `--provider`, `--base-url`, `--api-key-env` for multi-provider routing |\n| `inkos config show-models` | Show current model routing | View per-agent model assignments |\n| `inkos doctor` | Diagnose issues | Check installation |\n| `inkos up/down` | Daemon mode | Background processing. Logs to `inkos.log` (JSON Lines). `-q` for quiet mode |\n| `inkos review list/approve-all` | Manage chapter approvals | Quality gate |\n| `inkos fanfic init` | Create fanfic from source material | `--from <file>`, `--mode canon/au/ooc/cp` |\n| `inkos genre list` | List all available genres | Shows English and Chinese genres with default language |\n| `inkos genre create <id>` | Create custom genre profile | `--name`, `--numerical`, `--power`, `--era` |\n| `inkos genre copy <id>` | Copy built-in genre to project | For customization |\n| `inkos write rewrite <book> <ch>` | Rewrite a specific chapter | Deletes chapter and later, rewrites from that point |\n| `inkos book update [book-id]` | Update book settings | `--chapter-words`, `--target-chapters`, `--status`, `--lang` |\n| `inkos book delete <book-id>` | Delete book and all chapters | `--force` to skip confirmation |\n| `inkos plan chapter [book-id]` | Generate chapter intent | Preview what next chapter will do before writing |\n| `inkos compose chapter [book-id]` | Generate runtime artifacts | Context, rule-stack, trace for next chapter |\n| `inkos consolidate [book-id]` | Consolidate chapter summaries | Reduces context for long books (volume-level summaries) |\n| `inkos forecast create/show/select` | Compare non-canonical future branches | Selection saves a candidate plan only; canon remains unchanged |\n| `inkos eval [book-id]` | Quality evaluation report | `--json`, `--chapters <range>`. Composite quality score |\n| `inkos` / `inkos studio` | Start web workbench | `-p` for port. Local web UI for book management |\n| `inkos fanfic show [book-id]` | Display parsed fanfic canon | Shows imported source material analysis |\n| `inkos fanfic refresh [book-id]` | Re-import and regenerate fanfic canon | `--from <file>` for updated source material |\n| `inkos interact` | Shared interaction endpoint | `--json`, `--message`, `--book`. Primary entry for OpenClaw |\n| `inkos tui` | Launch TUI dashboard | Full-screen Ink + React interactive dashboard |\n\n## Error Handling\n\n### Common Issues\n\n**\"book-id not found\"**\n- Verify the ID with `inkos book list`\n- Ensure you're in the correct project directory\n\n**\"Provider not configured\"**\n- Run `inkos config set-global` with valid credentials\n- Check API key and base URL with `inkos doctor`\n\n**\"Context invalid\"**\n- Ensure `--context` is a string (wrap in quotes if multi-word)\n- Context can be in English or Chinese\n\n**\"Audit failed\"**\n- Check chapter for encoding issues\n- Ensure chapter-words matches actual word count\n- Try `inkos revise` with `--mode rewrite`\n\n**\"Book already has chapters\" (import)**\n- Use `--resume-from <n>` to append to existing chapters\n- Or delete existing chapters first\n\n### Running Daemon Mode\n\nFor long-running operations:\n```bash\n# Start background daemon\ninkos up\n\n# Stop daemon\ninkos down\n\n# Daemon auto-processes queued chapters\n```\n\n## Tips for Best Results\n\n1. **Provide rich context**: The more guidance in `--context`, the more coherent the narrative\n2. **Start with style**: If imitating an author, run `inkos style import` before generation\n3. **Import first**: For existing novels, use `inkos import chapters` to bootstrap truth files before continuing\n4. **Review regularly**: Use `inkos review` to catch issues early\n5. **Monitor audits**: Check `inkos audit` metrics to understand quality bottlenecks\n6. **Use spinoffs strategically**: Import canon before writing prequels/sequels\n7. **Batch generation**: Generate multiple chapters together (better continuity)\n8. **Check analytics**: Use `inkos analytics` to track quality trends over time\n9. **Export frequently**: Keep backups with `inkos export`\n\n## Security & Trust\n\n- **License**: the ClawHub skill descriptor is MIT-0 per platform policy, but the underlying `@actalk/inkos`, `@actalk/inkos-core`, and `@actalk/inkos-studio` npm packages are **AGPL-3.0-only**. Running InkOS and distributing modified versions are governed by AGPL. Full source on GitHub for auditability.\n- **No install hooks**: npm package has no `preinstall`/`postinstall`/`install` scripts. Install is inert.\n- **Documented file locations**: manuscripts, story state, logs, imported Skills, and project secrets stay under the selected project directory. Optional global CLI configuration may be stored under `~/.inkos/`; user-level Skills may be read from `~/.agents/skills/` and `~/.openclaw/skills/`.\n- **Project-isolated retention**: each project's manuscripts, state, and memory remain in that project until the user deletes the book or project. Do not reuse one project's persisted memory in another project unless the user explicitly imports that material.\n- **No InkOS telemetry**: InkOS does not send usage analytics to an InkOS-controlled service. Content can leave the machine when the user invokes a configured LLM, image, web-search, aggregator, or custom provider; review each provider's endpoint and data policy before enabling it.\n- **Credential handling**: prefer Studio secret settings or environment-backed API keys over literal values. Agents and imported Skills must never read, print, summarize, or transmit credentials; secret stores must stay outside prompts, exports, archives, and commits.\n- **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`.\n- **Local services**: InkOS requires no sudo. Studio opens a localhost listener on port `4567` by default (or the port selected by the user), and daemon mode runs only when explicitly started.\n\n## Support & Resources\n\n- **Homepage**: https://github.com/Narcooo/inkos\n- **Configuration**: Stored in project root after `inkos init`\n- **Truth files**: Located in `books/<id>/story/` per book, with structured JSON in `story/state/`\n- **Logs**: Check output of `inkos doctor` for troubleshooting","skillMdTruncated","frontmatter",{"_37":40,"_43":44,"_248":249},"version","2.8.3","totalSizeBytes","runtime",{"_253":254,"_255":7,"_256":-5,"_257":7,"_258":254,"_259":7,"_260":261,"_262":263},"requiresBash",true,"requiresMcp","model","requiresNode","requiresNetwork","requiresPython","allowedTools",[],"dependencies",[],"install",{"_266":267,"_268":269,"_270":271,"_272":273,"_274":275},"cli","npx skills add narcooo/inkos/skills","coordinate","narcooo/inkos/skills","browseUrl","https://github.com/narcooo/inkos/tree/master/skills","downloadUrl","https://github.com/narcooo/inkos/archive/refs/heads/master.zip","gitUrl","https://github.com/narcooo/inkos.git","createdAt","2026-08-11T01:31:49.920Z","updatedAt","2026-08-17T18:20:16.409Z","hasNext","page","actionData","errors"] </article></body></html>

[{"_1":2,"_282":-5,"_283":-5},"loaderData",{"_3":4,"_8":9,"_23":24},"root",{"_5":-5,"_6":7},"user","countable",false,"routes/_main",{"_5":-5,"_10":11},"recentPosts",[12,17,20],{"_13":14,"_15":16},"slug","claude-code-gitlab-support","title","Claude Code's GitLab Support: What Changed",{"_13":18,"_15":19},"github-copilot-pricing-tiers","GitHub Copilot Pricing: Which Tier Do You Actually Need?",{"_13":21,"_15":22},"claude-code-self-hosted-runner-production","Deploying a Self-Hosted Claude Code Runner to Production","routes/creators.$handle",{"_25":26,"_27":26,"_28":29,"_30":7,"_31":32,"_280":7,"_281":111},"handle","narcooo","displayName","profileUrl","https://github.com/narcooo","verified","skills",[33],{"_34":35,"_13":36,"_37":38,"_39":40,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_54":55,"_61":62,"_63":64,"_65":66,"_81":82,"_83":-5,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93,"_94":-5,"_95":96,"_97":26,"_30":7,"_98":7,"_99":87,"_100":101,"_102":87,"_103":87,"_104":105,"_106":107,"_135":136,"_170":171,"_221":222,"_251":252,"_264":265,"_276":277,"_278":279},"id","gh__narcooo__inkos__skills","inkos-narcooo","name","InkOS","canonicalName","inkos","tagline","AI-powered story creation and multilingual translation.","description","Story Creation and Translation AI Agent with Studio Chat, CLI, and TUI - use for long-form novels, short fiction, scripts, storyboards, interactive-film projects, open-world / branching play, fan fiction, spinoffs, style imitation, continuations, covers, and multilingual EPUB/PDF/TXT/Markdown translation. Includes Agent Skills, traceable research, governed context, persistent story state, multi-model routing, image services, and InkOS Studio.","longDescription","InkOS is a versatile AI agent designed for story creation and multilingual translation, catering to various writing formats including long-form novels, short fiction, scripts, and storyboards. It excels in managing complex narrative structures, allowing users to create branching interactive stories and fan fiction while maintaining a consistent narrative voice. The system supports a structured workflow through its Studio Chat interface, where users can issue natural-language commands that InkOS translates into actionable tasks, ensuring that the output is derived from real tool results rather than mere text generation.\n\nThe skill features a robust chapter pipeline that emphasizes input governance, allowing authors to preserve their intent and focus throughout the writing process. With components like the Architect, Planner, and Composer, users can maintain a clear outline and relevant truth files, which are crucial for ensuring continuity. The writing phase is governed by craft rules and context selection, while the Observer and Reviser roles help maintain quality and address any issues that arise during the writing cycle. This structured approach not only aids in the production of coherent narratives but also facilitates collaborative writing efforts.\n\nInkOS also includes advanced translation capabilities, enabling users to localize their works into multiple languages, including EPUB, PDF, TXT, and Markdown formats. The system's SQLite-based memory database allows for relevance-based retrieval of project-specific information, ensuring that users can access their story's context without cross-contamination from unrelated projects. This isolation promotes a focused writing environment, making it easier to manage multiple narratives simultaneously.\n\nIdeal for both professional writers and hobbyists, InkOS supports various genres and writing styles, including English and Chinese web novels. Its ability to import existing chapters and continue writing from established materials makes it particularly useful for authors looking to expand on previous works or create spin-offs. Whether you're crafting a novel, a script, or an interactive story, InkOS provides the tools needed to enhance your storytelling process.","primaryCategory","writing","subcategory","creative-writing","secondaryCategories",[53],"entertainment","tags",[56,57,58,59,60],"story-creation","multilingual-translation","interactive-narratives","fan-fiction","novel-writing","skillType","workflow","complexity","intermediate","platforms",[67,68,69,70,71,72,73,74,75,76,77,78,79,80],"claude-code","claude-api","codex-cli","cursor","antigravity","github-copilot","windsurf","opencode","cline","roo-code","goose","kiro","continue","trae","delivery","source-link","skillFileUrl","pricing","free","price",0,"thumbnailType","icon","thumbnailIcon","pen-tool","thumbnailColor","blue","thumbnailImageUrl","sellerId","gh__narcooo","sellerName","featured","downloads","views",9,"rating","reviewCount","status","active","metrics",{"_108":109,"_110":111,"_112":111,"_113":114,"_115":116,"_117":118,"_119":120,"_121":122,"_123":124,"_125":126,"_127":101,"_128":118,"_129":130,"_131":132,"_133":134},"freshnessScore",100,"mirrorCount",1,"skillCountInRepo","qualityScore",85,"daysSinceUpdate",7,"popularityScore",82,"trustScore",60,"repoOpenIssues",219,"repoStars",8886,"repoWatchers",36,"repoContributors","overallScore","repoCreatedAt","2026-03-12T02:12:54Z","repoForks",1668,"repoPushedAt","2026-08-03T08:47:31Z","source",{"_137":26,"_138":139,"_140":141,"_146":147,"_148":40,"_149":-5,"_144":150,"_151":152,"_153":147,"_154":7,"_155":31,"_156":157,"_163":164,"_165":7,"_166":167,"_168":169},"owner","repoUrl","https://github.com/narcooo/inkos","author",{"_28":29,"_142":143,"_37":26,"_25":26,"_144":145},"avatarUrl","https://github.com/narcooo.png","type","User","lastSyncedAt","2026-08-11T01:31:44.784Z","repo","commitSha","github","branch","master","firstSeenAt","isOfficial","path","license",{"_37":158,"_159":160,"_161":162},"GNU Affero General Public License v3.0","spdxId","AGPL-3.0","url","https://github.com/narcooo/inkos/blob/master/LICENSE","sourceUpdatedAt","2026-08-03T08:46:49.000Z","redistributable","permalink","https://github.com/narcooo/inkos/blob/master/skills/SKILL.md","repoFullName","narcooo/inkos","seo",{"_172":173,"_184":185,"_186":187,"_205":-5,"_206":207,"_213":214,"_215":216,"_217":218,"_219":220},"useCases",[174,178,181],{"_15":175,"_176":177},"Writing a Novel","body","Use InkOS to manage the complex narrative structure of your novel, ensuring continuity and quality throughout the writing process.",{"_15":179,"_176":180},"Creating Interactive Stories","Leverage InkOS for developing branching narratives and interactive play, allowing for dynamic storytelling experiences.",{"_15":182,"_176":183},"Translating Works","Utilize InkOS's multilingual capabilities to translate your written works into various formats, ensuring accessibility for a wider audience.","whenNotToUse","InkOS may not be suitable for casual writing or short, one-off pieces where a structured approach is not necessary. It is best utilized for projects requiring depth and continuity.","faqs",[188,193,196,199,202],{"_189":190,"_191":192},"q","What types of writing can I create with InkOS?","a","InkOS supports a variety of writing formats including long-form novels, short fiction, scripts, storyboards, and interactive narratives.",{"_189":194,"_191":195},"Can InkOS help with multilingual translation?","Yes, InkOS includes robust translation capabilities for EPUB, PDF, TXT, and Markdown formats, making it easy to localize your works.",{"_189":197,"_191":198},"How does the chapter pipeline work in InkOS?","The chapter pipeline in InkOS consists of roles like Architect, Planner, and Composer to preserve author intent and maintain narrative continuity throughout the writing process.",{"_189":200,"_191":201},"Is InkOS suitable for casual writing projects?","InkOS is designed for more structured and complex writing projects, so it may not be ideal for casual or one-off writing tasks.",{"_189":203,"_191":204},"Can I import existing chapters into InkOS?","Yes, InkOS allows you to import existing chapters from text files, enabling you to continue writing from established materials.","ogImageUrl","keywords",[208,209,210,211,212],"story creation AI","multilingual translation tool","novel writing assistant","interactive storytelling","fan fiction generator","whenToUse","Use InkOS when you need to create complex narratives, such as novels or interactive stories, or when you require multilingual localization for your written works.","metaTitle","InkOS - AI Story Creation and Translation Tool","problemSolved","InkOS removes the complexity of managing narrative structures and multilingual translation, streamlining the writing process for various formats.","metaDescription","Discover InkOS, the AI agent for story creation and multilingual translation. Perfect for novels, scripts, and more.","content",{"_223":87,"_224":225,"_233":234,"_243":244,"_245":7,"_246":247,"_250":229},"bundledFiles","fileTree",[226],{"_155":227,"_228":229,"_144":230,"_231":232},"SKILL.md","size",45116,"file","language","markdown","codeExamples",[235,239,241],{"_231":236,"_237":238},"bash","snippet","# Initialize a project directory (creates config structure)\ninkos init my-writing-project\n\n# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)\n# Prefer --api-key-env so the key never appears in shell history:\nexport OPENAI_API_KEY=sk-xxx\ninkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o\n# For compatible/proxy endpoints, use --provider custom and point ONLY to trusted endpoints:\n# inkos config set-global --provider custom --base-url https://your-trusted-proxy.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o",{"_231":236,"_237":240},"# Assign different models to different agents — balance quality and cost\ninkos config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY\ninkos config set-model auditor gpt-4o --provider openai\ninkos config show-models",{"_231":236,"_237":242},"# Check installation and configuration\ninkos doctor\n\n# View current config\ninkos status","skillMd","# InkOS - Story Creation AI Agent\n\nInkOS is a story creation and multilingual translation AI agent for long-form novels, short fiction, scripts, storyboards, interactive-film projects, fan works, continuations, covers, open-world / branching interactive play, and long-document localization. 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.\n\nLong-form writing still uses the chapter pipeline internally:\n- **Input governance**: Architect / Planner / Composer preserve author intent, current focus, outline sections, and relevant truth files instead of injecting everything blindly.\n- **Writing**: Writer produces prose with length governance, craft rules, and context selected for the current task.\n- **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.\n\nTruth 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+.\nPersisted story memory is isolated to its project and book, excludes credentials and unrelated files, and is never reused across projects unless the user explicitly imports material. Users can inspect or delete the owning book/project through Studio or CLI.\n\n## v1.7.2 Mental Model\n\nTreat InkOS as a confirmable action system, not a bag of prompt shortcuts. v1.7.2 replaces the former InkOS-private Skill protocol with standard AgentSkills / OpenClaw `SKILL.md` packages. Skills provide professional guidance and static references only: they can be selected explicitly or activated by the Chat Agent through `use_skill`, but they never grant execution permissions.\n\n- Natural-language requests should go through Studio Chat / TUI / `inkos interact` whenever possible.\n- 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.\n- Use `short_fiction_run` only for a standalone short-fiction package.\n- Use `generate_cover` only for cover generation/regeneration.\n- Use `play_start` / `play_step` for Open World or Branching Interactive sessions.\n- Use script / storyboard / interactive-film tools only for production artifacts that should be saved and exported, not for casual discussion.\n- Use the translation project workflow for EPUB, text-based PDF, TXT, or Markdown localization. Keep source and target languages, glossary, review report, and export format explicit; do not replace it with an ad hoc one-turn translation when the user wants a complete deliverable.\n- Use `research_web` only when the user explicitly asks for external facts, market references, era/profession details, or worldbuilding research. Research reports are reference material and do not automatically mutate canon or prose.\n- Use long-form chapter tools only for existing long-form books.\n- Use narrative forecasts when the author wants to compare possible long-form directions before writing. A forecast is non-canonical planning material: selecting a branch may write `selected-branch-plan.md`, but it must not be described as changing prose, outlines, or canonical state.\n- A running production task does not prevent ordinary discussion, but do not start another conflicting book mutation until that task reaches a terminal state.\n- Agent Skills provide professional guidance and static references. They do not grant new file, network, image, or writing permissions by themselves.\n- 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.\n- Studio Chat can receive user-uploaded text / Markdown / image attachments. Text attachments are injected into the LLM context; image attachments require a vision-capable model.\n- External materials can be archived and retrieved later with evidence traces instead of relying on ad hoc pasted context.\n- Prompt packs are user-tunable in Studio Project Settings. Project overrides are saved under `prompt//.md`; do not edit generated artifacts just to change system behavior.\n- Long-form chapter revision from Chat passes the current user instruction into the reviser as a one-off brief. If the revision is not applied, inspect the returned gate metrics and remaining audit issues before claiming it was fixed.\n\nv1.7.0 added complete multilingual translation/localization, English-native short/script/storyboard/interactive-film paths, existing-novel import from Chat, configurable review and revision gates, abortable long tasks, recoverable write locks, material archive/retrieval, and Studio-editable prompt packs. v1.7.1 added non-canonical narrative forecasting, background production tasks, retryable task state, whole-book backup / restore, and rollback-safe latest-chapter deletion. Still surface unresolved review or execution issues plainly instead of claiming they were fixed.\n\n## When to Use InkOS\n\n- **English novel writing**: Native English support with 10 genre profiles (LitRPG, Progression Fantasy, Isekai, etc.). Set `--lang en`\n- **Chinese web novel writing**: 5 built-in Chinese genres (xuanhuan, xianxia, urban, horror, other)\n- **Fan fiction**: Create fanfic from source material with 4 modes (canon, au, ooc, cp)\n- **Batch chapter generation**: Generate multiple chapters with consistent quality\n- **Import & continue**: Import existing chapters from a text file, reverse-engineer truth files, and continue writing\n- **Style imitation**: Analyze and adopt writing styles from reference texts\n- **Spinoff writing**: Write prequels/sequels/spinoffs while maintaining parent canon\n- **Standalone short fiction**: Generate a complete short-fiction package with outline, draft, review artifacts, synopsis, selling points, and optional cover image\n- **Cover generation**: Generate or regenerate only a cover prompt and cover image from a title, synopsis, or visual direction without rerunning story writing\n- **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\n- **Interactive-film projects**: Create playable branch graphs, variables/flags, relationship state, endings, node images, and exportable interactive project packages\n- **Scripts and storyboards**: Convert ideas, outlines, or prose into script/storyboard deliverables while preserving user format choices\n- **Long-document translation**: Translate EPUB, text-based PDF, TXT, or Markdown by chapter and semantic segment, maintain terminology, review source and target side by side, and export TXT/Markdown/EPUB\n- **Agent Skills**: Load standard AgentSkills/OpenClaw or project-local `SKILL.md` packages; let the Chat Agent invoke them from user intent, or force one with `@skill-id`\n- **Traceable web research**: Create sourced Markdown reports for facts, era/profession details, markets, and worldbuilding references\n- **Quality auditing**: Detect AI-generated content and perform 33-dimension quality checks\n- **Genre exploration**: Explore trends and create custom genre rules\n- **Analytics**: Track word count, audit pass rate, and issue distribution per book\n\n## Initial Setup\n\n### First Time Setup\n```bash\n# Initialize a project directory (creates config structure)\ninkos init my-writing-project\n\n# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)\n# Prefer --api-key-env so the key never appears in shell history:\nexport OPENAI_API_KEY=sk-xxx\ninkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o\n# For compatible/proxy endpoints, use --provider custom and point ONLY to trusted endpoints:\n# inkos config set-global --provider custom --base-url https://your-trusted-proxy.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o\n```\n\n### Multi-Model Routing (Optional)\n```bash\n# Assign different models to different agents — balance quality and cost\ninkos config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY\ninkos config set-model auditor gpt-4o --provider openai\ninkos config show-models\n```\nAgents without explicit overrides fall back to the global model.\n\n### Provider setup tip\n\nWhen the user needs an aggregator provider, point them to Studio's service settings. InkOS includes kkaiapi and OpenRouter as optional aggregator choices. For kkaiapi, use:\n- Chinese website: https://kkaiapi.com/\n- English website: https://en.kkaiapi.com/\n- Chinese API docs: https://kkaiapi.com/docs\n- English API docs: https://en.kkaiapi.com/docs\n- Chinese models/pricing: https://kkaiapi.com/models\n- English models/pricing: https://en.kkaiapi.com/models\n\n### View System Status\n```bash\n# Check installation and configuration\ninkos doctor\n\n# View current config\ninkos status\n```\n\n## Common Workflows\n\n### Workflow 1: Create a New Novel\n\n1. **Initialize and create book**:\n ```bash\n inkos book create --title \"My Novel Title\" --genre xuanhuan --chapter-words 3000\n # Or with a creative brief (your worldbuilding doc / ideas):\n inkos book create --title \"My Novel Title\" --genre xuanhuan --chapter-words 3000 --brief my-ideas.md\n ```\n - Genres: `xuanhuan` (cultivation), `xianxia` (immortal), `urban` (city), `horror`, `other`\n - Returns a `book-id` for all subsequent operations\n\n2. **Generate initial chapters** (e.g., 5 chapters):\n ```bash\n inkos write next book-id --count 5 --words 3000 --context \"young protagonist discovering powers\"\n ```\n - The `write next` command runs the full pipeline: draft → audit → revise\n - `--context` provides guidance to the Architect and Writer agents\n - Returns JSON with chapter details and quality metrics\n\n3. **Review and approve chapters**:\n ```bash\n inkos review list book-id\n inkos review approve-all book-id\n ```\n\n4. **Export the book** (supports txt, md, epub):\n ```bash\n inkos export book-id\n inkos export book-id --format epub\n ```\n\n### Workflow 2: Continue Writing Existing Novel\n\n1. **List your books**:\n ```bash\n inkos book list\n ```\n\n2. **Continue from last chapter**:\n ```bash\n inkos write next book-id --count 3 --words 2500 --context \"protagonist faces critical choice\"\n ```\n - InkOS maintains structured runtime state, readable Markdown projections, control docs, and temporal memory for consistency\n - If only one book exists, omit `book-id` for auto-detection\n\n3. **Review and approve**:\n ```bash\n inkos review approve-all\n ```\n\n### Workflow 2.5: Shared Natural-Language Control (Recommended For OpenClaw)\n\nWhen InkOS is being driven by OpenClaw or another external agent, prefer the shared interaction executor instead of stitching together many ad-hoc CLI calls:\n\n```bash\ninkos interact --json --message \"continue the current book, but keep the pacing tighter\"\ninkos interact --json --message \"rewrite chapter 3\"\ninkos interact --json --message \"start an open-world detective game about a locked archive room\"\n```\n\nThe current JSON payload contains:\n- assistant response text\n- interaction session id / session kind / active book id when bound\n\nReal 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.\n\nUse this as the primary OpenClaw entry because it shares the same control layer as the project TUI.\n\n### Workflow 2.6: Steering Chapter Focus Before Writing\n\nUse 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\".\n\n1. **Update the book-level control docs when needed**:\n - Use `update_author_intent` to change the long-horizon identity of the book\n - Use `update_current_focus` to change the next 1-3 chapters' focus\n\n2. **Compile the next chapter intent**:\n ```text\n plan_chapter(bookId, guidance?)\n ```\n - Generates `story/runtime/chapter-XXXX.intent.md`\n - Use this to verify what the system thinks the next chapter should do\n\n3. **Compose the actual runtime input package**:\n ```text\n compose_chapter(bookId, guidance?)\n ```\n - Generates `story/runtime/chapter-XXXX.context.json`\n - Generates `story/runtime/chapter-XXXX.rule-stack.yaml`\n - Generates `story/runtime/chapter-XXXX.trace.json`\n\n4. **Only then write**:\n - `write_draft` if the user wants intermediate review\n - `write_full_pipeline` if they want the usual write → audit → revise flow\n\nRecommended orchestration:\n- user asks to redirect focus\n- `update_current_focus`\n- `plan_chapter`\n- `compose_chapter`\n- inspect the resulting intent/paths\n- `write_draft` or `write_full_pipeline`\n\n### Workflow 2.7: Compare Long-Form Directions Before Writing\n\nUse a narrative forecast when the author wants to inspect several plausible futures without committing any of them to canon.\n\n1. Create isolated candidates from the current book state:\n ```bash\n inkos forecast create book-id --divergence \"Does the protagonist reveal the evidence now?\" --branches 3 --horizon 5\n ```\n2. Compare the branch cards in Studio Chat, or inspect the saved comparison with `inkos forecast show [book-id] `.\n3. Re-check the forecast before relying on it. Canon changes mark the forecast stale.\n4. Select one candidate with the Studio card or:\n ```bash\n inkos forecast select book-id forecast-id branch-2\n ```\n\nSelection writes only `story/runtime/narrative-forecasts//selected-branch-plan.md`. It does not apply the plan to chapter prose, outlines, author intent, or canonical state. Any later application remains a separate explicit authoring action.\n\n### Workflow 3: Import Existing Chapters & Continue\n\nUse this when you have an existing novel (or partial novel) and want InkOS to pick up where it left off.\n\n1. **Import from a single text file** (auto-splits by chapter headings):\n ```bash\n inkos import chapters book-id --from novel.txt\n ```\n - Automatically splits by `第X章` pattern\n - Custom split pattern: `--split \"Chapter\\\\s+\\\\d+\"`\n\n2. **Import from a directory** of separate chapter files:\n ```bash\n inkos import chapters book-id --from ./chapters/\n ```\n - Reads `.md` and `.txt` files in sorted order\n\n3. **Resume interrupted import**:\n ```bash\n inkos import chapters book-id --from novel.txt --resume-from 15\n ```\n\n4. **Continue writing** from the imported chapters:\n ```bash\n inkos write next book-id --count 3\n ```\n - InkOS rebuilds structured state, chapter summaries, hooks, character relationships, readable projections, and a style guide from the imported chapters\n - Generates a style guide from the existing text\n - New chapters maintain consistency with imported content\n\n### Workflow 4: Style Imitation\n\n1. **Analyze reference text**:\n ```bash\n inkos style analyze reference_text.txt\n ```\n - Examines vocabulary, sentence structure, tone, pacing\n\n2. **Import style to your book**:\n ```bash\n inkos style import reference_text.txt book-id --name \"Author Name\"\n ```\n - All future chapters adopt this style profile\n - Style rules become part of the Reviser's audit criteria\n\n### Workflow 5: Spinoff/Prequel Writing\n\n1. **Import parent canon**:\n ```bash\n inkos import canon spinoff-book-id --from parent-book-id\n ```\n - Creates links to parent book's world state, characters, and events\n - Reviser enforces canon consistency\n\n2. **Continue spinoff**:\n ```bash\n inkos write next spinoff-book-id --count 3 --context \"alternate timeline after Chapter 20\"\n ```\n\n### Workflow 6: Fine-Grained Control (Draft → Audit → Revise)\n\nIf you need separate control over each pipeline stage:\n\n1. **Generate draft only**:\n ```bash\n inkos draft book-id --words 3000 --context \"protagonist escapes\" --json\n ```\n\n2. **Audit the chapter** (33-dimension quality check):\n ```bash\n inkos audit book-id chapter-1 --json\n ```\n - Returns metrics across 33 dimensions including pacing, dialogue, world-building, outline adherence, and more\n\n3. **Revise with specific mode**:\n ```bash\n inkos revise book-id chapter-1 --mode polish --json\n ```\n - Modes documented for agent use: `polish` (minor), `spot-fix` (targeted), `rewrite` (major), and `rework` (structure)\n\n### Workflow 7: Monitor Platform Trends\n\n```bash\ninkos radar scan\n```\n- Analyzes trending genres, tropes, and reader preferences\n- Informs Architect recommendations for new books\n\n### Workflow 8: Detect AI-Generated Content\n\n```bash\n# Detect AIGC in a specific chapter\ninkos detect book-id\n\n# Deep scan all chapters\ninkos detect book-id --all\n```\n- Uses 11 deterministic rules (zero LLM cost) + optional LLM validation\n- Returns detection confidence and problematic passages\n\n### Workflow 9: View Analytics\n\n```bash\ninkos analytics book-id --json\n# Shorthand alias\ninkos stats book-id --json\n```\n- Total chapters, word count, average words per chapter\n- Audit pass rate and top issue categories\n- Chapters with most issues, status distribution\n- **Token usage stats**: total prompt/completion tokens, avg tokens per chapter, recent trend\n\n### Workflow 10: Write an English Novel\n\n```bash\n# Create an English LitRPG novel (language auto-detected from genre)\ninkos book create --title \"The Last Delver\" --genre litrpg --chapter-words 3000\n\n# Or set language explicitly\ninkos book create --title \"My Novel\" --genre other --lang en\n\n# Set English as default for all projects\ninkos config set-global --lang en\n```\n- 10 English genres: litrpg, progression, isekai, cultivation, system-apocalypse, dungeon-core, romantasy, sci-fi, tower-climber, cozy\n- Each genre has dedicated pacing rules, fatigue word lists (e.g., \"delve\", \"tapestry\", \"testament\"), and audit dimensions\n- Use `inkos genre list` to see all available genres\n\n### Workflow 11: Fan Fiction\n\n```bash\n# Create a fanfic from source material\ninkos fanfic init --title \"My Fanfic\" --from source-novel.txt --mode canon\n\n# Modes: canon (faithful), au (alternate universe), ooc (out of character), cp (ship-focused)\ninkos fanfic init --title \"What If\" --from source.txt --mode au --genre other\n```\n- Imports and analyzes source material automatically\n- Fanfic-specific audit dimensions and information boundary controls\n- Ensures new content stays consistent with source canon (or deliberately diverges in au/ooc modes)\n\n### Workflow 12: Edit Persistent Text Through Chat\n\nUse 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.\n\n```bash\ninkos interact --book my-book --json --message \"把第 3 章里那句过长的解释删短一点，但不要改剧情事实\"\ninkos interact --json --message \"把 covers/demo/cover-prompt.md 里的人物拉近一点，标题字更大\"\n```\n- Use for clear text edits, cover prompt edits, and control-document edits.\n- Do not infer success from the assistant's prose; check the tool result or changed file.\n- For broad story direction changes, prefer updating `author_intent.md` / `current_focus.md`, then run `plan` / `compose` before writing.\n\n### Workflow 13: Explicit Rename / Replacement Requests\n\nWhen 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.\n\nExamples:\n- \"把当前书里角色林烬改成张三，先说明会影响哪些文件。\"\n- \"只改第 5 章，把这句旧文本换成新文本，改完标记需要复核。\"\n\n### Workflow 14: Interactive TUI Dashboard\n\n```bash\ninkos tui\n```\n- Launches a full-screen Ink + React dashboard with conversational creation\n- Slash command autocomplete (Tab), input history (arrow keys)\n- Themed activity animations per operation (writing, auditing, revising, planning)\n- Bilingual i18n (Chinese / English)\n- Shares the same interaction kernel as `inkos interact` and Studio\n\n### Workflow 15: Standalone Short Fiction Package\n\nUse this when the user wants a complete short story or short-fiction deliverable that is separate from the active long-form book.\n\n```bash\ninkos short run \\\n --direction \"modern short fiction marriage reversal evidence-driven heroine\" \\\n --chapters 12 \\\n --chars 1000\n```\n\nOutputs are written under `shorts//final/`:\n- `full.md` — complete short-fiction manuscript\n- `sales-package.md` — synopsis and selling points\n- `cover-prompt.md` — cover prompt\n- `cover.png` — cover image when a cover provider is configured\n\nFor OpenClaw/Studio/agent orchestration, call the `short_fiction_run` tool when the user asks for a new complete short-fiction package. Do not use it for the next chapter of an existing long-form book.\n\n### Workflow 16: Standalone Cover Tool\n\nUse this when the user only wants a cover for an existing title, synopsis, or visual direction. Do not rerun the short-fiction pipeline.\n\nIn Studio or agent mode, ask naturally:\n\n```text\nGenerate a short-fiction cover for \"The Divorce Papers He Regretted\", modern city, high-drama reversal.\n```\n\nFor tool-using agents, call `generate_cover` with:\n- `title` — required\n- `intro` or `sellingPoints` — optional story context\n- `coverPrompt` — optional visual direction\n- `outputDir` — optional; defaults to `covers//`\n\nThe standalone cover tool writes:\n- `covers/<title>/cover-prompt.md`\n- `covers/<title>/cover.png`\n\nIf 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.\n\n### Workflow 17: Open World / Branching Interactive Play\n\nUse this when the user wants to play inside an interactive world instead of generating a finished manuscript.\n\nIn Studio or agent mode, ask naturally:\n\n```text\nCreate 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.\n```\n\nFor tool-using agents:\n- Call `play_start` when there is no active world/run yet, or when the user explicitly asks to start a new world.\n- Call `play_step` when the user performs an action inside an existing world.\n- Keep Open World free-form: do not force clickable choices unless the current session is Branching Interactive.\n- 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.\n- 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.\n\n### Workflow 18: Agent Skills\n\nUse this when the user wants reusable professional rules, a domain-specific writing mode, or a forced capability for the current Chat turn.\n\nProject-local skills live at:\n\n```text\n.agents/skills/<skill-id>/SKILL.md\n```\n\nInkOS also discovers standard AgentSkills / OpenClaw locations (`skills/`, `.agents/skills/`, `~/.agents/skills/`, and `~/.openclaw/skills/`). Studio can import a complete skill folder with its static reference files.\n\nExternal skill directories can be loaded with:\n\n```bash\nexport INKOS_SKILL_DIRS=/abs/path/to/skills\n```\n\nGuidelines for agent orchestration:\n- Let the Chat Agent inspect the available skill catalog and call `use_skill` when the current user intent needs that expertise. Do not emulate this with session-kind routing, keyword lists, or substring matching.\n- Force a skill by including `@skill-id` in the user message when the user explicitly chooses one.\n- Treat skills as standard expertise packets containing instructions and static references. Prompt packs and governed context recipes are separate InkOS systems.\n- Skill folders may contain static references. Read them only when needed, and never auto-execute bundled scripts.\n- Do not treat skills as permissions. File edits, book creation, chapter writing, image generation, and exports still require the normal InkOS tools and confirmation gates.\n\n### Workflow 19: Traceable Web Research\n\nUse this when the user asks for real-world references, external facts, era/profession details, market references, or worldbuilding research.\n\nFor tool-using agents, call `research_web` with:\n- `topic` — the research question\n- `purpose` — `worldbuilding`, `era`, `profession`, `market`, `fact-check`, or `general`\n- `depth` — optional: `quick`, `standard`, or `deep`\n\nThe tool writes a Markdown report under:\n\n```text\n.inkos/research/\n```\n\nThe report includes sources, claims, unknowns, conflicts, query logs, and confidence. It is reference material only. If research should change canon, wait for explicit user confirmation and then use the normal truth-file editing path.\n\nSearch credentials are user/project supplied. Studio can configure a Tavily-compatible search API, or the server can use `TAVILY_API_KEY` from the environment.\n\n### Workflow 20: Script, Storyboard, and Interactive-Film Creation\n\nUse this when the user wants a production artifact rather than a casual answer:\n- Script: dramatic scenes, dialogue, acts, episode structure, or format-specific script drafts.\n- Storyboard: visual beats, shot descriptions, image prompts, and scene-by-scene production notes.\n- Interactive film: branch graph, choices, variables/flags, relationship state, endings, node images, and exportable project package.\n\nIn Studio Chat, these actions should be proposed with a confirmation card first. After confirmation, InkOS writes the artifact and reports the saved files. Do not hand-write a fake \"created\" result in prose.\n\n### Workflow 21: Multilingual Translation / Localization\n\nUse a translation project when the user wants a complete, reviewable deliverable rather than a one-off translated paragraph. Inputs can be EPUB, text-based PDF, TXT, or Markdown; source and target languages can be written as normal language names in Studio.\n\n```bash\ninkos translate init --from ./source.epub --source Chinese --target English\ninkos translate run <project-id>\ninkos translate export <project-id> --format epub\n```\n\n- Preserve the project glossary and chapter boundaries across translation batches.\n- Review source and translation side by side; treat the generated review report as the quality record.\n- Export TXT, Markdown, or EPUB only after the requested segments are complete.\n- For scanned PDFs without a text layer, run OCR before importing; InkOS currently reads text-based PDFs.\n\n## InkOS Studio (Web Workbench)\n\n`inkos studio` launches a local web UI (default port 4567) that provides a visual interface for all InkOS operations:\n\n- **Book management** — create, delete, export (TXT/MD/EPUB), configure per-book settings\n- **Short fiction & cover tools** — generate independent short-fiction packages, synopsis/selling points, cover prompts, and standalone covers\n- **Open World / Branching Interactive** — start and continue interactive worlds with world contracts, free actions, clickable choices, HUD state, and image generation\n- **Interactive-film workbench** — create and inspect branch nodes, variables/flags, endings, node images, and export packages\n- **Script / storyboard tools** — generate production-oriented script and storyboard files from ideas, prose, or reference notes\n- **Translation workbench** — import EPUB, text-based PDF, TXT, or Markdown; choose source and target languages; translate, compare, review, and export complete projects\n- **Agent Skills management** — list standard skills, import AgentSkills/OpenClaw folders with static references into `.agents/skills/`, let Chat invoke skills from intent, and force skills from Chat\n- **Research search provider** — configure external web search API credentials for `research_web`\n- **Chapter review & editing** — approve/reject drafts, edit content inline, and revise with polish/spot-fix/rewrite/rework modes\n- **Real-time writing progress** — SSE-based live updates during chapter generation\n- **Market radar** — AI-powered trend analysis with platform/genre recommendations\n- **Analytics** — word count, audit pass rate, chapter ranking, token usage\n- **AI detection** — scan chapters for AI-generated content\n- **Style analysis** — analyze reference texts and import writing styles\n- **Genre management** — create/customize genre profiles with fatigue words, pacing rules, audit dimensions\n- **Daemon control** — start/stop background writing with event log\n- **Truth file editor** — view and edit canonical knowledge base per book\n- **Config editor** — LLM provider, model routing, cover/image services, notifications\n\n```bash\ninkos studio # Start on default port 4567\ninkos studio -p 8080 # Start on custom port\n```\n\nThe **Studio Chat** surface shares the same action kernel as TUI and CLI. It can answer questions, propose/confirm creation and translation actions, run Short, generate covers, start Play, import existing novels, edit persistent text artifacts, and invoke long-form writing operations.\n\n## Advanced: Natural Language Agent Mode\n\nFor flexible, conversational requests:\n\n```bash\ninkos agent \"写一部都市题材的小说，主角是一个年轻律师，第一章三千字\"\n```\n- Agent interprets natural language and invokes appropriate commands\n- Useful for complex multi-step requests\n\n## Input Governance Tools\n\nThese tools are the preferred control surface for chapter steering:\n\n- `plan_chapter(bookId, guidance?)`\n - Generates chapter intent for the next chapter\n - Use before writing when the user wants to change focus\n\n- `compose_chapter(bookId, guidance?)`\n - Generates runtime context/rule-stack/trace artifacts\n - Use after planning and before writing\n\n- `update_author_intent(bookId, content)`\n - Rewrites `story/author_intent.md`\n - Use for long-horizon changes to the book's identity\n\n- `update_current_focus(bookId, content)`\n - Rewrites `story/current_focus.md`\n - Use for local steering over the next 1-3 chapters\n\n## Creative, Research, and Play Agent Tools\n\nThese are the preferred tools when InkOS is driven by OpenClaw, Studio chat, or `inkos agent`:\n\n- `short_fiction_run`\n - Creates an independent short-fiction package from a direction\n - Runs outline → outline review/revision → full draft → draft review/revision → synopsis/selling points/cover prompt → optional cover image\n - Writes to `shorts/<story-name>/`\n - Use only when the user asks for a separate complete short story / short-fiction deliverable\n\n- `generate_cover`\n - Generates only a cover prompt and cover image\n - Writes to `covers/<title>/` by default\n - Use when the user asks to create or regenerate a cover for an existing title, synopsis, or completed short\n - 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\n - Do not rerun story generation unless the user explicitly asks for a new story\n\n- `play_start`\n - Starts a new Open World or Branching Interactive run\n - 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\n - The user's world contract should carry time rules, character agency, item/evidence rules, tone, genre, and visual style when provided\n\n- `play_step`\n - Advances an existing Play run by one user action\n - Use for free-form actions such as \"inspect the letter\", \"talk to the guard\", \"train for three days\", or \"choose option 2\"\n - Do not use it to write the next chapter of a long-form book\n\n- `research_web`\n - Collects external sources and writes a traceable Markdown research report\n - Use only for explicit research/fact-check/worldbuilding/market requests\n - Never mutate canon or prose directly from research output without explicit user confirmation\n\n- Script / storyboard / interactive-film creation tools\n - Use when the user wants saved production artifacts\n - Preserve the user's requested format, market, target audience, and export needs\n - Do not use these tools for casual analysis unless the user asks to create deliverables\n\n`write_truth_file` remains available for broad file edits, but prefer the dedicated control tools above for input-governance changes.\n\n## Key Concepts\n\n### Book ID Auto-Detection\nIf your project contains only one book, most commands accept `book-id` as optional. You can omit it for brevity:\n```bash\n# Explicit\ninkos write next book-123 --count 1\n\n# Auto-detected (if only one book exists)\ninkos write next --count 1\n```\n\n### --json Flag\nAll content-generating commands support `--json` for structured output. Essential for programmatic use:\n```bash\ninkos draft book-id --words 3000 --context \"guidance\" --json\n```\n\n### Long-Term Memory\nInkOS maintains each book's memory in three layers:\n- **Structured state**: `story/state/*.json` is the authoritative runtime state, validated by Zod schemas.\n- **Readable projections**: `current_state.md`, `pending_hooks.md`, `chapter_summaries.md`, `character_matrix.md`, and related Markdown files are for humans and debugging.\n- **Temporal memory**: `story/memory.db` on Node 22+ supports relevance-based retrieval of facts, hooks, and chapter summaries.\n\nAgents 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.\n\n### Multi-Phase Writer Architecture\nThe Writer operates across multiple phases with specialized agents:\n- **Planner**: Generates chapter intent with structured hook agenda (mustAdvance, eligibleResolve, staleDebt) based on memory retrieval.\n- **Composer**: Selects relevant context from structured state, control docs, readable projections, and retrieval results, then compiles rule stack and runtime artifacts.\n- **Phase 1 (Creative, temp 0.7)**: Generates prose with length governance, English variance brief (anti-repetition), and dialogue-driven guidance.\n- **Phase 2a (Observer, temp 0.5)**: Over-extracts 9 categories of facts from the chapter text.\n- **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.\n- **Normalizer**: Single-pass compress/expand to bring chapter length into the target band. Safety net rejects destructive normalization (>75% content loss).\n- **Auditor**: 33-dimension check including hook health analysis (stale debt, burst detection, no-advance warnings).\n- **Reviser**: Attempts one configured repair pass for critical issues, then keeps unresolved findings visible for human or agent follow-up.\n\nTruth 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.\n\n### Context Guidance\nThe `--context` parameter provides directional hints to the Writer and Architect:\n```bash\ninkos write next book-id --count 2 --context \"protagonist discovers betrayal, must decide whether to trust mentor\"\n```\n- Context is optional but highly recommended for narrative coherence\n- Supports both English and Chinese\n\n## Genre Management\n\n### View Built-In Genres\n```bash\ninkos genre list\ninkos genre show xuanhuan\n```\n\n### Create Custom Genre\n```bash\ninkos genre create my-genre --name \"My Genre\"\n# Options: --numerical, --power, --era\ninkos genre create dark-xuanhuan --name \"Dark Xuanhuan\" --numerical --power\n```\n\n### Copy Built-in Genre for Customization\n```bash\ninkos genre copy xuanhuan\n# Copies to project genres/ directory for editing\n```\n\n## Command Reference Summary\n\n| Command | Purpose | Notes |\n|---------|---------|-------|\n| `inkos init [name]` | Initialize project | One-time setup |\n| `inkos book create` | Create new book | Returns book-id. `--brief <file>`, `--lang en/zh`, `--genre litrpg/progression/...` |\n| `inkos book list` | List all books | Shows IDs, statuses |\n| `inkos write next` | Full pipeline (draft→audit→revise) | Primary workflow command |\n| `inkos draft` | Generate draft only | No auditing/revision |\n| `inkos audit` | 33-dimension quality check | Standalone evaluation |\n| `inkos revise` | Revise chapter | Modes documented for agent use: polish/spot-fix/rewrite/rework |\n| `inkos agent` | Natural language interface | Flexible requests |\n| `inkos style analyze` | Analyze reference text | Extracts style profile |\n| `inkos style import` | Apply style to book | Makes style permanent |\n| `inkos import canon` | Link spinoff to parent | For prequels/sequels |\n| `inkos import chapters` | Import existing chapters | Reverse-engineers truth files for continuation |\n| `inkos detect` | AIGC detection | Flags AI-generated passages |\n| `inkos export` | Export finished book | Formats: txt, md, epub |\n| `inkos analytics` / `inkos stats` | View book statistics | Word count, audit rates, token usage |\n| `inkos radar scan` | Platform trend analysis | Informs new book ideas |\n| `inkos short run` | Generate standalone short fiction | Outputs manuscript, sales package, cover prompt, optional cover |\n| `inkos config set-global` | Configure LLM provider | OpenAI/Anthropic/custom (any OpenAI-compatible) |\n| `inkos config set-model <agent> <model>` | Set model override for a specific agent | `--provider`, `--base-url`, `--api-key-env` for multi-provider routing |\n| `inkos config show-models` | Show current model routing | View per-agent model assignments |\n| `inkos doctor` | Diagnose issues | Check installation |\n| `inkos up/down` | Daemon mode | Background processing. Logs to `inkos.log` (JSON Lines). `-q` for quiet mode |\n| `inkos review list/approve-all` | Manage chapter approvals | Quality gate |\n| `inkos fanfic init` | Create fanfic from source material | `--from <file>`, `--mode canon/au/ooc/cp` |\n| `inkos genre list` | List all available genres | Shows English and Chinese genres with default language |\n| `inkos genre create <id>` | Create custom genre profile | `--name`, `--numerical`, `--power`, `--era` |\n| `inkos genre copy <id>` | Copy built-in genre to project | For customization |\n| `inkos write rewrite <book> <ch>` | Rewrite a specific chapter | Deletes chapter and later, rewrites from that point |\n| `inkos book update [book-id]` | Update book settings | `--chapter-words`, `--target-chapters`, `--status`, `--lang` |\n| `inkos book delete <book-id>` | Delete book and all chapters | `--force` to skip confirmation |\n| `inkos plan chapter [book-id]` | Generate chapter intent | Preview what next chapter will do before writing |\n| `inkos compose chapter [book-id]` | Generate runtime artifacts | Context, rule-stack, trace for next chapter |\n| `inkos consolidate [book-id]` | Consolidate chapter summaries | Reduces context for long books (volume-level summaries) |\n| `inkos forecast create/show/select` | Compare non-canonical future branches | Selection saves a candidate plan only; canon remains unchanged |\n| `inkos eval [book-id]` | Quality evaluation report | `--json`, `--chapters <range>`. Composite quality score |\n| `inkos` / `inkos studio` | Start web workbench | `-p` for port. Local web UI for book management |\n| `inkos fanfic show [book-id]` | Display parsed fanfic canon | Shows imported source material analysis |\n| `inkos fanfic refresh [book-id]` | Re-import and regenerate fanfic canon | `--from <file>` for updated source material |\n| `inkos interact` | Shared interaction endpoint | `--json`, `--message`, `--book`. Primary entry for OpenClaw |\n| `inkos tui` | Launch TUI dashboard | Full-screen Ink + React interactive dashboard |\n\n## Error Handling\n\n### Common Issues\n\n**\"book-id not found\"**\n- Verify the ID with `inkos book list`\n- Ensure you're in the correct project directory\n\n**\"Provider not configured\"**\n- Run `inkos config set-global` with valid credentials\n- Check API key and base URL with `inkos doctor`\n\n**\"Context invalid\"**\n- Ensure `--context` is a string (wrap in quotes if multi-word)\n- Context can be in English or Chinese\n\n**\"Audit failed\"**\n- Check chapter for encoding issues\n- Ensure chapter-words matches actual word count\n- Try `inkos revise` with `--mode rewrite`\n\n**\"Book already has chapters\" (import)**\n- Use `--resume-from <n>` to append to existing chapters\n- Or delete existing chapters first\n\n### Running Daemon Mode\n\nFor long-running operations:\n```bash\n# Start background daemon\ninkos up\n\n# Stop daemon\ninkos down\n\n# Daemon auto-processes queued chapters\n```\n\n## Tips for Best Results\n\n1. **Provide rich context**: The more guidance in `--context`, the more coherent the narrative\n2. **Start with style**: If imitating an author, run `inkos style import` before generation\n3. **Import first**: For existing novels, use `inkos import chapters` to bootstrap truth files before continuing\n4. **Review regularly**: Use `inkos review` to catch issues early\n5. **Monitor audits**: Check `inkos audit` metrics to understand quality bottlenecks\n6. **Use spinoffs strategically**: Import canon before writing prequels/sequels\n7. **Batch generation**: Generate multiple chapters together (better continuity)\n8. **Check analytics**: Use `inkos analytics` to track quality trends over time\n9. **Export frequently**: Keep backups with `inkos export`\n\n## Security & Trust\n\n- **License**: the ClawHub skill descriptor is MIT-0 per platform policy, but the underlying `@actalk/inkos`, `@actalk/inkos-core`, and `@actalk/inkos-studio` npm packages are **AGPL-3.0-only**. Running InkOS and distributing modified versions are governed by AGPL. Full source on GitHub for auditability.\n- **No install hooks**: npm package has no `preinstall`/`postinstall`/`install` scripts. Install is inert.\n- **Documented file locations**: manuscripts, story state, logs, imported Skills, and project secrets stay under the selected project directory. Optional global CLI configuration may be stored under `~/.inkos/`; user-level Skills may be read from `~/.agents/skills/` and `~/.openclaw/skills/`.\n- **Project-isolated retention**: each project's manuscripts, state, and memory remain in that project until the user deletes the book or project. Do not reuse one project's persisted memory in another project unless the user explicitly imports that material.\n- **No InkOS telemetry**: InkOS does not send usage analytics to an InkOS-controlled service. Content can leave the machine when the user invokes a configured LLM, image, web-search, aggregator, or custom provider; review each provider's endpoint and data policy before enabling it.\n- **Credential handling**: prefer Studio secret settings or environment-backed API keys over literal values. Agents and imported Skills must never read, print, summarize, or transmit credentials; secret stores must stay outside prompts, exports, archives, and commits.\n- **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`.\n- **Local services**: InkOS requires no sudo. Studio opens a localhost listener on port `4567` by default (or the port selected by the user), and daemon mode runs only when explicitly started.\n\n## Support & Resources\n\n- **Homepage**: https://github.com/Narcooo/inkos\n- **Configuration**: Stored in project root after `inkos init`\n- **Truth files**: Located in `books/<id>/story/` per book, with structured JSON in `story/state/`\n- **Logs**: Check output of `inkos doctor` for troubleshooting","skillMdTruncated","frontmatter",{"_37":40,"_43":44,"_248":249},"version","2.8.3","totalSizeBytes","runtime",{"_253":254,"_255":7,"_256":-5,"_257":7,"_258":254,"_259":7,"_260":261,"_262":263},"requiresBash",true,"requiresMcp","model","requiresNode","requiresNetwork","requiresPython","allowedTools",[],"dependencies",[],"install",{"_266":267,"_268":269,"_270":271,"_272":273,"_274":275},"cli","npx skills add narcooo/inkos/skills","coordinate","narcooo/inkos/skills","browseUrl","https://github.com/narcooo/inkos/tree/master/skills","downloadUrl","https://github.com/narcooo/inkos/archive/refs/heads/master.zip","gitUrl","https://github.com/narcooo/inkos.git","createdAt","2026-08-11T01:31:49.920Z","updatedAt","2026-08-17T18:20:16.409Z","hasNext","page","actionData","errors"] </article></body></html>