Generating a handbook

handbook generate --source <repo> --work <workdir> [options]

This is the only expensive command. Everything on this page is about spending less on it and getting more out of it.

Start cheap, then upgrade

handbook analyze --source $REPO --work $WORK

handbook generate --source $REPO --work $WORK

handbook generate --source $REPO --work $WORK --phase 2a --detail deep --resume

handbook generate --source $REPO --work $WORK --phase 2b,2c,3 --synth-mode doctor

Doing it in this order means you never pay for deep cards on top of a skeleton you are about to throw away.

--detail brief vs deep

Deep is worth it when an agent will use the handbook, because per-function notes are what turn a stage page into an address book. Brief is right for a first pass, for a very large repo, or when you mostly want the structure.

You can mix: generate brief everywhere, then re-run --phase 2a --detail deep --resume after pointing --source at the subdirectory you care about most.

--synth-mode oneshot vs doctor

oneshot synthesizes a skeleton in one pass. Fast, cheap, usually reasonable.

doctor runs an actor–critic repair loop: propose at most three structural changes, review them with three critics (engineer, architect, reader), validate the survivors mechanically against the real graph, apply, re-assign, repeat.

--strategy file vs member

file (default) — the LLM synthesizes the skeleton; a source file is the leaf unit. Scales to large repositories. Use this unless you have a reason not to.

member — you author skeleton.yaml; individual functions and methods are classified into your stages, and the file-level artifacts are derived from that.

metadata:
  version: 1
  archetype: HTTP API server
stages:
  - id: stage-1
    title: Request intake
    description: Accepting connections, parsing requests, and routing them.
    parent: null
    children: []
    crosscut: false
  - id: stage-2
    title: Business logic
    description: What the service actually does with a validated request.
    parent: null
    children: []
    crosscut: false
  - id: crosscut-1
    title: Configuration and logging
    description: Cross-cutting infrastructure used by every stage.
    parent: null
    children: []
    crosscut: true

handbook generate --source $REPO --work $WORK --strategy member --skeleton skeleton.yaml

Member costs more — every function is classified — but gives tighter prose, and phase 2c becomes free because the organization is derived deterministically.

Running phases separately

--phase 1        # just the graph (same as `handbook analyze`)
--phase 2a       # just the cards
--phase 2b       # just skeleton + assignment
--phase 2c       # just the grouping
--phase 3        # just narration + registers
--phase 2        # 2a + 2b + 2c
--phase 2c,3     # a comma list

Each phase reads only its upstream artifacts, so this is always safe. The common ones:

Resuming and caching

• --resume skips files that already have a complete card at the requested depth. Cards are written as they complete, so Ctrl-C is always safe.
• --llm-cache caches raw replies under <work>/phase3/cache, keyed by model, prompt and options. Re-runs while you iterate become nearly free.
• --refresh ignores phase-3 caches. Use it when you changed the prompt inputs but the cache key did not notice — for example after editing skeleton.yaml by hand.

--refresh disables --llm-cache for that run, by design.

Watching it work

handbook generate --source $REPO --work $WORK -v

[scan] auto root=/Users/me/code/api
[scan] typescript: 284 files
[2a] batch 12/36 · 96 cards
[2b] 9 stages; 0 files unassigned
[3] narrating stage-4 (2 children)

Token usage lands in run-manifest.json when the run finishes.

When the result is wrong

More in Troubleshooting.