inkos

What this skill does

# InkOS - Story Creation AI Agent

InkOS is a story creation AI agent for long-form novels, short fiction, scripts, fan works, continuations, covers, and open-world / branching interactive play. 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.

Long-form writing still uses the chapter pipeline internally:
- **Input governance**: Architect / Planner / Composer preserve author intent, current focus, outline sections, and relevant truth files instead of injecting everything blindly.
- **Writing**: Writer produces prose with length governance, craft rules, and context selected for the current task.
- **Settlement and review**: Observer / Reflector update runtime state; Auditor checks continuity and quality; Reviser handles critical issues. The default write cycle keeps automatic repair conservative and leaves unresolved issues visible for human or agent follow-up.

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

## v1.5.0 Mental Model

Treat InkOS as a confirmable action system, not a bag of prompt shortcuts.

- Natural-language requests should go through Studio Chat / TUI / `inkos interact` whenever possible.
- Do not infer success from assistant prose. A book, short, cover, or play step is complete only when the corresponding tool result and files exist.
- Use `short_fiction_run` only for a standalone short-fiction package.
- Use `generate_cover` only for cover generation/regeneration.
- Use `play_start` / `play_step` for Open World or Branching Interactive sessions.
- Use long-form chapter tools only for existing long-form books.
- Context is governed: protected facts and current intent should not be silently compressed away; compressible history may be summarized when the context budget is tight.

v1.5 broadly improves instruction following, context management, weak-model formatting resilience, and error separation between InkOS execution, provider calls, and image generation. Still surface unresolved audit issues plainly instead of claiming they were fixed.

## When to Use InkOS

- **English novel writing**: Native English support with 10 genre profiles (LitRPG, Progression Fantasy, Isekai, etc.). Set `--lang en`
- **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
- **Standalone short fiction**: Generate a complete short-fiction package with outline, draft, review artifacts, synopsis, selling points, and optional cover image
- **Cover generation**: Generate or regenerate only a cover prompt and cover image from a title, synopsis, or visual direction without rerunning story writing
- **Interactive worlds**: Start Open World or Branching Interactive sessions with world contracts, character agents, inventory/evidence/relationship state, guided choices, free actions, and optional image generation
- **Quality auditing**: Detect AI-generated content and perform 33-dimension quality checks
- **Genre exploration**: Explore trends and create custom genre rules
- **Analytics**: Track word count, audit pass rate, and issue distribution per book

## Initial Setup

### First Time Setup
```bash
# Initialize a project directory (creates config structure)
inkos init my-writing-project

# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)
# Prefer --api-key-env so the key never appears in shell history:
export OPENAI_API_KEY=sk-xxx
inkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o
# For compatible/proxy endpoints, use --provider custom and point ONLY to trusted endpoints:
# inkos config set-global --provider custom --base-url https://your-trusted-proxy.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o
```

### Multi-Model Routing (Optional)
```bash
# 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.

### Provider setup tip

When 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:
- Chinese website: https://kkaiapi.com/
- English website: https://en.kkaiapi.com/
- Chinese API docs: https://kkaiapi.com/docs
- English API docs: https://en.kkaiapi.com/docs
- Chinese models/pricing: https://kkaiapi.com/models
- English models/pricing: https://en.kkaiapi.com/models

### View System Status
```bash
# Check installation and configuration
inkos doctor

# View current config
inkos status
```

## Common Workflows

### Workflow 1: Create a New Novel

1. **Initialize and create book**:
   ```bash
   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

2. **Generate initial chapters** (e.g., 5 chapters):
   ```bash
   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

3. **Review and approve chapters**:
   ```bash
   inkos review list book-id
   inkos review approve-all book-id
   ```

4. **Export the book** (supports txt, md, epub):
   ```bash
   inkos export book-id
   inkos export book-id --format epub
   ```

### Workflow 2: Continue Writing Existing Novel

1. **List your books**:
   ```bash
   inkos book list
   ```

2. **Continue from last chapter**:
   ```bash
   inkos write next book-id --count 3 --words 2500 --context "protagonist faces critical choice"
   ```
   - InkOS maintains structured runtime state, readable Markdown projections, control docs, and temporal memory for consistency
   - If only one book exists, omit `book-id` for auto-detection

3. **Review and approve**:
   ```bash
   inkos review approve-all
   ```

### Workflow 2.5: Shared Natural-Language Control (Recommended For OpenClaw)

When InkOS is being driven by OpenClaw or another external agent, prefer the shared interaction executor instead of stitching together many ad-hoc CLI calls:

```bash
inkos interact --json --message "continue the current book, but keep the pacing tighter"
inkos interact --json --message "rewrite chapter 3"
inkos interact --json --message "start an open-world detective game about a locked archive room"
```

The current JSON payload contains:
- assistant response text
- interaction session id / session kind / active book id when bound

Real completion still comes from tool results and files. Do not treat assistant prose alone as proof that a book, chapter, short, cover, or play step was created.

Use this as the