Create a repo, put a paper in it, get a verified summary out. Then scale up to a review.

Before You Start

1. Create A Repo

$ python3 scripts/research.py init ~/research/my-manuscript-repo
{
  "schema_version": 1,
  "status": "ok",
  "command": "init",
  "repo_root": "/Users/you/research/my-manuscript-repo",
  "created_dirs": [
    "data/sources/assets",
    "data/sources/snapshots",
    "data/papers/extractions",
    "data/papers/appraisals",
    "projects",
    "runs",
    "templates",
    "exports/wiki",
    "exports/bib",
    "exports/html",
    "exports/docx",
    "exports/pdf"
  ],
  "created_files": [ ... ]
}

That is the whole repo. data/papers/registry.jsonl and data/sources/events.jsonl are created empty; data/refmgr/ (the derived SQLite search index) appears the first time you import a PDF or run registry.py reindex. The slash-command form is /deep-research:init <path>.

2. Add A Project

A project is a manuscript question. It matters because appraisal is project-scoped — the same paper can be low-risk-of-bias for one question and unusable for another.

$ python3 scripts/research.py project create adolescent-cbt --repo ~/research/my-manuscript-repo
{
  "schema_version": 1,
  "status": "ok",
  "command": "project create",
  "slug": "adolescent-cbt",
  "project_dir": "/Users/you/research/my-manuscript-repo/projects/adolescent-cbt",
  "created": ["protocol.md", "synthesis.md", "manuscript.qmd", "refs.bib", "corpus.lock.jsonl"]
}

The slug is what you pass as --project everywhere downstream.

3. Put Papers In It

All intake paths converge on the same registry record, so it does not matter which one you use:

# by identifier
/deep-research:pool-add --repo ~/research/my-manuscript-repo --pmid 12345678
python3 scripts/registry.py add --repo ~/research/my-manuscript-repo --doi 10.1000/example

# from files you already have
python3 scripts/registry.py add-pdf       --repo ~/… --file paper.pdf
python3 scripts/registry.py import-bib    --repo ~/… --file refs.bib
python3 scripts/registry.py import-folder --repo ~/… --dir papers/ --recursive

PDF bytes are content-addressed by sha256 — importing the same paper twice merges identifiers into the existing entry rather than storing it again. /deep-research:pool-add covers PMIDs and bounded queries; DOI-only adds, PDFs, bulk .bib, and folders have no slash-command wrapper, so call the script.

4. Summarize One Paper

/deep-research:summarize \
  --repo ~/research/my-manuscript-repo \
  --project adolescent-cbt \
  --pmid 12345678 \
  --purpose journal-club \
  --format both

--purpose takes clinical, methods, journal-club, peer-review, or background; --audience takes researcher, clinician, student, grant-writer, or general. They shape the summary's framing, not its evidence.

Appraisal is on by default whenever full text and a supported framework are available. Use --no-appraise only for a deliberate extraction-only summary — the summary then has to state why appraisal was skipped.

5. Summarize Several

/deep-research:summarize-set \
  --repo ~/research/my-manuscript-repo \
  --project adolescent-cbt \
  --pmid 12345678 --pmid 23456789 \
  --overview --format both

One verified summary per paper, plus an optional bounded overview across them. --ids-file, --bib, and --folder take the set from a file instead; --topic / --question do a bounded PubMed scan for candidates — add --select-only to see the picked set before paying for summaries.

6. Run A Full Review

Ask the agent in plain words — "run a literature review on X", "what does the evidence say about Y". It configures Stage 0 with you, then runs the Stage 0–8 pipeline. Expect to be asked six things up front: the question in framework form, the profile, the target root, your study-selection criteria, filters, and which outputs you want.

While it runs, the state is all on disk and readable at any time:

/deep-research:status <run-dir> --table      # per-paper coverage: downloaded? format? extracted?
/deep-research:status <run-dir> --missing    # only the blocked records
/deep-research:watch --run-dir <run-dir>     # read-only TUI, live or finished

If a run is interrupted, point the agent back at the run directory. It reads config.json's stage pointer plus taskboard.jsonl, continues incomplete and failed tasks, and does not re-prompt or restart the stage.

7. Get Things Out

# BibTeX over the whole registry
/deep-research:bib-export --repo ~/… --out refs.bib --select all

# a ReadCube-importable RIS + PDF bundle
/deep-research:export --repo ~/… --all --destination ~/ReadCube-import --require-pdfs

# HTML / PDF / docx from a finished run
python3 scripts/html_report.py build --run-dir <run> --out <run>/outputs/report.html
python3 scripts/render.py all --run-dir <run> --formats pdf,docx

When Something Goes Wrong

Which Path Do I Want?