StoryForge: Configuration
All StoryForge configuration keys: config.yaml, which values actually take effect, the per-book linter_mode setting, the author writing mode and storage locations.
StoryForge: Configuration
The file ~/.storyforge/config.yaml
The setup skill copies config/config.example.yaml to ~/.storyforge/config.yaml. When it loads, the values from the file are laid over built-in defaults. If the file is missing, the defaults apply. Paths under paths are resolved with ~ and environment variables.
You can edit the file directly or use /storyforge:configure. The skill shows the current values, asks what to change and re-reads the file afterwards to confirm.
paths:
content_root: "~/projekte/book-projects"
authors_root: "~/.storyforge/authors"
defaults:
language: "en"
book_type: "novel"
review_handle: "Author"
export:
default_format: "epub"
cover:
platform: "midjourney"
post_processing:
tool: "canva"
Keys and what they do
| Key | Default | Effect |
|---|---|---|
paths.content_root |
~/projekte/book-projects |
Root for books, series and ideas. Used by all book tools. |
paths.authors_root |
~/.storyforge/authors |
Location of the author profiles. |
defaults.review_handle |
Author |
The name you use to start inline comments in draft.md (for example Author: this line is off). The tool get_review_handle_config and the chapter writing brief hand it to the skills. |
export.default_format |
epub |
Format export-engineer uses when you name none (epub, pdf or mobi). If the value is missing, the skill asks. |
post_processing.tool |
canva |
Tool for cover typography: canva, gimp or photoshop. The tool get_post_processing_config and cover-typography-mockup follow it. An unknown value falls back to canva. |
Keys without effect
The example config contains further keys that neither the plugin code nor the skills evaluate. You can set them, but nothing changes. The skill /storyforge:configure still offers some of them for editing (language, book type, book category, PDF engine, cover platform).
| Key | What applies instead |
|---|---|
defaults.language |
new-book asks for the language when creating the book (suggestion: English) and stores it in the book. |
defaults.book_type |
new-book asks for the book type. |
defaults.book_category |
new-book asks for the category (fiction or memoir). |
export.pandoc_path |
The export calls pandoc from the PATH. |
export.calibre_path |
The MOBI export calls ebook-convert from the PATH. |
export.pdf_engine |
The PDF export always uses xelatex. |
cover.platform |
cover-artist generates prompts for DALL-E and Midjourney regardless of the value. |
cover.default_style |
Not read. |
translation.preserve_formatting, translation.include_glossary |
Not read. |
If Pandoc or Calibre are not on your
PATH, a config key will not help. Extend the systemPATH.
Per-book settings
linter_mode
The prose hook checks every change to a draft.md. The default is strict: on findings of severity "block" the hook exits with code 2 and feeds the message back to Claude, which has to correct the text. Per book you can switch to warn, which reports blockers as notes only. The value lives in the YAML frontmatter of the CLAUDE.md in the book's root directory:
---
linter_mode: warn
---
Only strict and warn are valid. There is no global setting in config.yaml. Hook details: Technical details.
Book metadata
Title, author, genres, book type, category and language live in the frontmatter of the book's README.md. Target word counts suggested when you create a book:
Book type (book_type) |
Suggested target word count |
|---|---|
short-story |
5,000 |
novelette |
12,000 |
novella |
30,000 |
novel |
80,000 |
epic |
120,000 |
The category book_category is fiction or memoir and independent of the book type. A memoir can be a novella.
Per-author settings
The author's profile.md frontmatter holds author_writing_mode with the values outliner, plantser or discovery. The value controls which planning skills are suggested to you. You can change it through /storyforge:configure or the tool update_author. For memoir books, /storyforge:create-author asks for Structured, Accumulative or Discovery instead; when saved through update_author, Structured and Accumulative are automatically mapped to outliner and plantser respectively, so the profile ends up holding the canonical value. A book can override the mode. More on the Writing Modes page.
Storage locations
| Path | Content |
|---|---|
~/.storyforge/config.yaml |
Configuration |
~/.storyforge/venv/ |
Python virtual environment |
~/.storyforge/cache/state.json |
State cache, rebuilt automatically |
~/.storyforge/db/ |
SQLite databases: storyforge.db (session), authors.db (author discoveries, review feedback) and one file per series or standalone book |
~/.storyforge/snapshots/ |
Comparison and raw drafts of fiction chapters (plain files, local; directory changeable via the STORYFORGE_SNAPSHOT_DIR environment variable) |
~/.storyforge/authors/{slug}/ |
Author profiles: profile.md, vocabulary.md, studied-works/, examples/ |
~/.storyforge/genres/{genre}/ |
Your own genres (README.md), created with /storyforge:genre-creator. Survive plugin updates; on a name clash your own genre wins over a built-in one. |
{content_root}/projects/{book}/ |
Standalone books |
{content_root}/series/{series}/{book}/ |
Books in a series |
{content_root}/ideas/{slug}.md |
Book ideas, one Markdown file per idea |
The databases hold book rules, callbacks, canon facts, character snapshots, author discoveries, review feedback and cover tracking. Structure and book directory layout: Technical details.