Narrative Craft

Narrative Craft is a local toolkit for shaping, drafting, critiquing, revising, verifying and exporting stories. It ships a Python package, the narrative-craft CLI, an agent skill, typed contracts and a reproducible Traditional Chinese example. It requires Python 3.14+ and no external service or agent framework.

Status

0.8.0 is the current release. The narrative system organizes work around Plan, Character and Story, with Evaluation evidence, Owner Decisions and a stateless orchestration loop. Pre-1.0 interfaces may change without compatibility aliases. Read the changelog before upgrading.

A release is qualified by the gate suite CI runs on the tagged commit, which the develop → main promotion and publication steps in Release depend on. The release path retains zhconv under the owner-approved ADR-009 exception: its bundled GPLv2-or-later conversion data reproduces protected published export bytes, and the package ships the corresponding third-party notice.

Install

uv tool install narrative-craft
# or
pipx install narrative-craft
# or
pip install narrative-craft

Development checkout:

git clone https://github.com/clchinkc/narrative-craft.git
cd narrative-craft
uv sync
uv run narrative-craft doctor

Quick start

Author a Plan before creating a workspace. Initialization preserves that source and records attributed genesis acceptances for the initial models.

mkdir lighthouse-story
cd lighthouse-story
printf '# The Second Signal\n\nThe premise, ending and scene intentions.\n' > Plan.md
narrative-craft project init --story . --id lighthouse-story \
  --title "The Second Signal" --locale en --decided-by author:you
narrative-craft project get --story .
narrative-craft check all --story .
narrative-craft story frontier --story .

Follow Quick start or inspect a copy of 《留聲》, a reproducible story built through genesis, Plan change and scene drafting. Author-facing SHAPE, BUILD, POLISH, CRITIQUE and PUBLISH describe the work; accepted narrative moves implement changes.

The current commands are run, project, plan, character, story, eval, decision, check, doctor, export and release-check. Use their --help for leaf arguments. Every product command uses the narrative-craft prefix.

narrative-craft run --story .
narrative-craft plan model get --story .
narrative-craft character list --story .
narrative-craft story model get --story .
narrative-craft decision wave --story .
narrative-craft eval list --story .
narrative-craft export ao3 --story . --output export.html

Export prepares a file; publishing remains an author action.

Workspace and narrative loop

Workspace authorities owns the storage guide. The system spec defines authority and mutation laws; the architecture map presents those relationships.

GROUND → CHOOSE → FRAME → OWNER WAVE? → REALIZE → PROVE → OWNER WAVE → RECONCILE → ADVANCE

The loop handles Plan changes, Character changes, scene drafting, scene revision, Story-model corrections and publication. The public run command stages candidate files and resumes their persisted bundle. decision answer records the author's answer to an exact request. RECONCILE writes accepted changes under incumbent checks; a refusal preserves the existing authority. Human sources never become subordinate to their machine interpretations.

Frontier, Owner Wave and matrices are derived on read. UNKNOWN remains distinct from FALSE and cannot silently become a passing proof. Use narrative-craft eval proof families --move <kind> to inspect current proof coverage. Semantic judgment requires attributed reviewer evidence; a missing review remains UNKNOWN. Acceptance and reconciliation verify the proof's current profile, exact candidate and input bindings, evidence references and deterministic obligations. See the runbook for the complete review and resume sequence. eval plan has no record writer and is not exposed as a stub command.

Semantic packets bind actual authorities, sources, acceptance records and evaluator identity. Finding retrieval derives staleness and joins Owner Decisions by exact references. Checks write no currentness cache. See Semantic checking and Evaluation infrastructure.

Programmatic use

from narrative_craft import api

manifest = api.project.get(workspace)
model = api.story.get_story_model_authority(workspace)
report = api.check.all(workspace)

The typed API exposes the current domains without printing or exiting the host process. Internal modules are not compatibility interfaces. External tools integrate through public artifacts and the declared first-party integrations; there is no third-party code-loading extension system.

Documentation

• Installation
• Quick start
• Pipeline
• Narrative-loop runbook
• Publication metadata
• Locales and bilingual workflows
• Native critique
• Author gates
• Failure modes
• Falsification and rollback
• State format
• First-party integrations (ADR-019: AO3 export, live bridge, remote execution, external-review interchange, vault knowledge/config)
• Eval infrastructure (evidence records, supported packet workflows and installed qualification)
• Versioned schema index
• narrative_craft.api reference
• Architecture decision records
• Release process
• Changelog — pre-1.0, see the loud breaking-change notice for 0.3.0

Repository layout

src/narrative_craft/       package and CLI
skills/narrative-craft/    installable agent skill
spec/                     narrative-system and locale specifications
schemas/                  public JSON Schema contracts
assets/                   rubrics and templates
docs/                     current guides and architecture decisions
examples/                 native workspace and artifact examples
tests/                    feature behavior and shared contract suites

Development

uv sync
uv run pytest -q
uv run ruff check .
uv build
narrative-craft release-check --root . --allow-dirty

release-check is the repository-checkout release-readiness gate CI runs before a tag: schema-index staleness, the import boundary, sanitized-fixture scanning, declared-dependency coverage, and that README documents every live top-level command. Drop --allow-dirty to also require a clean working tree (what CI itself runs); --write-schema-index regenerates docs/schema-index.md when a schema changed.

The documentation check is one-directional. It asserts every live top-level command appears in README; it reads no other file, so nothing asserts the reverse — that a documented command still exists. A passing release-check is never proof the docs are current, only that README has not fallen behind the live tree.

See CONTRIBUTING.md and SECURITY.md.

License

MIT. See LICENSE and the dependency gate in Release.