# USER GUIDE — JoF-250 Writing Engine

## Concepts
- **Profile** (`profiles/*.yaml`): measured distributions from the train split of the corpus (medians, IQRs, bootstrap CIs, n) for structure (lengths, counts, section shares) and rhetoric (abstract/introduction moves, contribution placement, identification language, robustness/table conventions). Read them as *what published JoF articles did*, not as rules. `/jof-profile empirical_asset_pricing`.
- **Structured retrieval**: hybrid BM25 + local embedding search over structural units (document summaries, identification summaries, introduction paragraphs tagged with moves, claim–evidence links) and short (≤400 chars) excerpts; every hit has provenance (doc_id, DOI, year, page, section, confidence). `jof250 retrieve --topic "..." [--unit annotation|raw|None] [--section results] [--year 2019]`.
- **Engine** (`jof250 write`): `--mode outline|write|upgrade`, `--section introduction|literature|data|empirical_design|results|robustness|conclusion|abstract`, `--condition A_baseline|B_strong_prompt|C_conventional_rag|D_profiles_retrieval|E_full_engine` (default E). Output is **always a new file** (`--output path.tex`) with a sibling `path.report.md` holding the change log, flags, retrieval provenance, deterministic audit (numeric preservation, citation keys, unsupported claims, corpus overlap) and a unified diff against the current section. The manuscript is never modified.
- **Reviews** (`jof250 review --role referee|editor|table_editor|integrity|replication --output file.md`) and **audits** (`jof250 audit --paper P --output file.md`, no API call), **evidence** (`jof250 evidence --paper P --claim "..."`, no API call).

## Slash commands (Claude Code)
| Command | What it runs |
|---|---|
| `/jof-status` | pipeline status + spend |
| `/jof-corpus-audit` | re-inventory + Crossref check |
| `/jof-profile <name>` | explains a profile |
| `/jof-outline <paper> --section introduction` | outline with rhetorical moves |
| `/jof-write <paper> --section introduction [--condition E]` | full draft → `<paper>/jof250_proposals/` |
| `/jof-upgrade <paper> --section results` | rewrite preserving every number/citation |
| `/jof-review <paper> [--role referee] [--full]` | referee/editor/table/integrity/replication reports → `<paper>/jof250_reviews/` |
| `/jof-audit <paper>` | deterministic audit |
| `/jof-evidence <paper> --claim "..."` | locate support for a claim |
| `/jof-benchmark [--dry-run]` | preregistered protocol (spends money; dry-run first) |

Argument syntax: Claude Code passes the raw text after the command as `$ARGUMENTS`; the command file instructs the assistant how to parse it (see `.claude/commands/*.md`).

## Specialist agents
`jof-corpus-auditor`, `jof-rhetorical-analyst`, `jof-writing-editor`, `jof-econometric-referee`, `jof-table-figure-editor`, `jof-integrity-auditor`, `jof-replication-auditor` (`.claude/agents/`). They propose patches/reports and never edit the manuscript silently.

## Manuscripts supported
LaTeX projects (directory with `paper/main.tex` or `main.tex`; `\input`/`\include` resolved; UQO `\WP…` macros read; `*.bib` scanned for keys and DOIs) and Markdown files. Theory, methods and non-finance manuscripts are accepted: the engine prints a genre note explaining which JoF conventions do not apply.

## Worked examples (real runs, see `docs/DELIVERY_REPORT.md`)
- `experiments/outputs/demo/wp41_intro_upgrade_E.tex` + `.report.md` — upgrade of the introduction of UQO WP41 (CHRONOS-X).
- `experiments/outputs/demo/wp29_referee.md` — referee report on UQO WP29.