# fiction-forge

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

**AI-assisted novel writing toolkit** | A [Galleys.ai](https://galleys.ai) project

MCP story-bible context server, a cold-read verification protocol, measured voice-matching, prose/repetition scanners, and a multi-format publisher — a battle-tested system for novel-length manuscripts. Works with [Claude Code](https://claude.ai/claude-code).

---

**v2 (2026-07): what shipping a ~289,000-word novel actually taught us.** v1 of this toolkit was built on a belief: scan for AI fingerprints, fix in parallel waves, and the manuscript converges. That got the book shipped — and then a single front-to-back cold read, carried out with a running state ledger, found **191 real issues that five automated editorial passes had missed**: timeline drift, props in two places, characters knowing things before they learn them. None of it is visible to a linter, because linters are memoryless and novels break through *accumulating state*.

So v2 reframes the toolkit around what actually worked:

1. **Context is the product.** The MCP server and the markdown memory system (ledgers, registers, resume markers) are what make novel-scale AI work possible in a bounded context window.
2. **Discovery is a reader with a ledger.** The cold-read protocol (charter + ledger + append-only issue log) is the verification step that finds what matters.
3. **Scanners are regression fences.** Still shipped, still useful — for verifying that an edit pass didn't reintroduce tics. Not for discovery.
4. **Voice is measured, not guessed.** Build a per-1k-word profile from your target corpus and edit *toward* it. (Generic de-AI advice — kill adverbs, cut similes — made our case-study prose measurably *less* like its target author. Measure first.)

---

## What's Included

**Tools**
- **MCP Context Server** — Gives Claude Code real-time access to your story bible: `get_character(name, chapter)` with timeline-scoped knowledge, `get_chapter_context`, `search_bible`, `check_continuity`, `get_foreshadowing`
- **Prose Scanner** — Detects 24 overused patterns (em-dashes, similes, AI fingerprints) with severity scoring and cluster detection
- **Repetition Scanner** — Cross-chapter n-gram matching, concrete-detail conflict detection, dialogue-beat fingerprinting — the accumulating-pattern layer the prose scanner can't see
- **Em-dash Reducer** — Rule-based rewriter calibrated to a measured target density (keeps dialogue interruptions, rewrites connector dashes)
- **Renumberer** — Two-pass chapter renumbering (temp names first) that updates in-file headers without collisions
- **Publisher** — Compiles markdown chapters into EPUB, PDF, HTML with cover images, part dividers, professional typography
- **Image Generator** — Batch DALL-E 3 illustration generator with rate limiting and manifest tracking

**The Cold-Read Protocol** *(new in v2 — start here for verification)*
- A reader-persona charter, a rolling state ledger (clock table, promise register, knowledge map, prop custody), an append-only issue log with severity taxonomy, and per-batch reports — the discovery pass that catches what linters structurally cannot. [docs/cold-read.md](docs/cold-read.md)

**Templates**
- Cold read: `read_charter.md`, `reader_ledger.md`, `issues.md`, `batch_report.md`
- Planning: `sequel_concept.md` (end-states, carried threads, scene-ID map), `answer_key.md` (private canon rule sheet), `corpus_extraction_prompt.md` (distill source novels into structured reference)
- Foundation: story bible, character profiles, foreshadowing ledger, chapter template, editorial notes, master outline

**Presets**
- Literary fiction and genre fiction pattern presets with configurable thresholds
- Style profiles as examples — but see [docs/voice-matching.md](docs/voice-matching.md): a measured profile from your target corpus beats any hand-written preset

**Documentation**
- [Cold-Read Protocol](docs/cold-read.md) — ledger-carrying verification: why and how *(new)*
- [Context Management](docs/context-management.md) — the markdown-file memory pattern for novel-scale work *(new)*
- [Voice Matching](docs/voice-matching.md) — measure the target corpus, diff, edit toward it *(new)*
- [Workflow Guide](docs/workflow.md) — the full process, foundation through verification
- [Prose Patterns](docs/prose-patterns.md), [MCP Server](docs/mcp-server.md), [Story Bible Guide](docs/story-bible-guide.md), [Publishing](docs/publishing.md)
- [Lessons Learned](docs/lessons-learned.md) — practical insights from the case-study project

## Quick Start

```bash
git clone https://github.com/geobond13/fiction-forge.git
cd fiction-forge
pip install -r requirements.txt
```

1. Edit `project.yaml` with your book's title, author, and part structure
2. Copy `templates/chapter.md` to `book/01_First_Chapter.md` and start writing
3. Populate `reference/bible.md` with your story's voice rules and canon decisions (adapting an existing world? start with `templates/corpus_extraction_prompt.md`)
4. Run `python tools/prose_scanner.py --summary` to scan for pattern issues
5. Open Claude Code in the project — the MCP server starts automatically
6. Before you call anything finished: run a cold read ([docs/cold-read.md](docs/cold-read.md))

## Architecture

```
project.yaml          Single config file — all tools read from here
     |
     ├── tools/
     │   ├── fiction_mcp.py           MCP server (5 tools for Claude Code)
     │   ├── prose_scanner.py         Pattern detection + severity reports
     │   ├── repetition_scanner.py    Cross-chapter n-grams, detail conflicts, beat fingerprints
     │   ├── emdash_reduce.py         Rule-based em-dash rewriter (config-calibrated)
     │   ├── renumber.py              Two-pass chapter renumbering
     │   ├── publish.py               Markdown → EPUB / PDF / HTML
     │   └── generate_images.py       DALL-E 3 batch illustration generator
     │
     ├── presets/                     Pattern definitions + example style profiles
     ├── reference/                   Your story's source of truth (bible, characters,
     │                                foreshadowing, continuity)
     ├── book/                        Your chapters (00_Prologue.md, 01_Title.md, ...)
     ├── templates/                   Blank templates — incl. the cold-read document set
     └── docs/                        Process documentation
```

## The Workflow

1. **Foundation** — Distill your source material, build the bible, and **write the ending first** (the promise register is the spine of the book)
2. **Draft** — Write chapters with MCP context keeping agents grounded
3. **Edit in waves** — Scan, then launch parallel agents on non-overlapping files; re-scan as a regression fence
4. **Match voice by measurement** — Profile the target corpus, diff, edit toward it (both directions)
5. **Verify with a cold read** — A ledger-carrying front-to-back read is the only pass that catches accumulating-state errors

See [docs/workflow.md](docs/workflow.md) for the complete process.

## Case Study: The Third Silence

fiction-forge was developed and battle-tested on [The Third Silence](https://thethirdsilence.com), a ~289,000-word, 105-chapter fan continuation of Patrick Rothfuss's Kingkiller Chronicle (free, non-commercial, AI use disclosed).

- **9 editorial programs** over the project's life: pattern waves, consolidation (−80k words from the 388k draft), two full ledger-carrying cold reads, a structural re-plot, and a measured voice pass
- The cold reads found **191 issues** (first read) that five automated passes had missed — the finding v2 is built on
- The measured voice pass exposed prose tics at up to **8.3×** the target author's rate — and generic de-AI edits that had pushed adverbs to **half** the target rate
- Blind tag-removal test after the voice pass: 5/6 scenes with every character identifiable by voice alone
- A second volume is in progress, planned with `templates/sequel_concept.md`

## Requirements

- Python 3.11+
- [pandoc](https://pandoc.org/installing.html) (for EPUB/HTML generation)
- [xelatex](https://tug.org/texlive/) (for PDF generation, optional)
- [Claude Code](https://claude.ai/claude-code) (for AI-assisted editing)
- OpenAI API key (for DALL-E image generation, optional)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on submitting pattern presets, adding tools, and code style.

## License

MIT — see [LICENSE](LICENSE).

---

A [Galleys.ai](https://galleys.ai) project | [The Third Silence](https://thethirdsilence.com)