Slash commands

Use the slash commands for the everyday cases; drop to the raw scripts for everything they don't cover.

Each /deep-research:* command calls one script directly, with no Stage 0-8 negotiation, and prints that script's own JSON. There are deliberately fewer wrappers than scripts — where no wrapper exists, the script call is given below rather than hidden.

How These Commands Behave

Three conventions hold across every script in the skill. Knowing them is worth more than memorizing flags.

Convention	Detail
Everything prints JSON	Every command emits a single object with `schema_version`, `status` (`ok` / `error`), `command`, and its payload. An error carries a human-readable `error` string, quoted rather than paraphrased.
`status` drives the loop	Scripts never call a model. Where model work is needed they return `pending_retrieval`, `pending_extraction`, `pending_appraisal`, or `pending_summary`. The agent dispatches that subagent, the subagent writes its file, the same command is re-run, and the script resumes. `completed` ends the loop.
Re-running is the interface	Not a retry hack. Completed work is not redone: a satisfied ladder rung is never re-attempted, a promoted extraction is immutable unless its `inputs_hash` changes, and an unchanged snapshot is skipped rather than re-split.

$ python3 scripts/registry.py doctor --repo ~/lit/
{
  "schema_version": 1,
  "status": "error",
  "command": "doctor",
  "error": "no refmgr library at ~/lit/data/refmgr — nothing to check; `registry.py reindex` creates one"
}

Exit codes matter for the ones you might cron: doctor exits non-zero only for actual data loss — missing or corrupt assets, dangling attachments — while stale index rows are reported but stay "healthy", because reindex fixes those and nothing is at risk.

Repo And Project

/deep-research:init <path>
/deep-research:init <path> --from-wiki <wiki-root>
/deep-research:project create <slug> --repo <path>
/deep-research:project list --repo <path>

No wrapper for the wiki-export adapter — run it directly:

python3 scripts/research.py export wiki --repo <path> --wiki <wiki-root> --project <slug>

Registry Intake

/deep-research:pool-add --repo <path> --pmid <pmid>
/deep-research:pool-add --repo <path> --query "..." --n 10
/deep-research:pdf-lookup --repo <path> --evidence-id pmid:12345678
/deep-research:bib-export --repo <path> --out refs.bib --select all

No wrapper for a DOI-only add, PDF/bulk-bib/folder import, or the raw registry list/pool projection steps — run these directly:

python3 scripts/registry.py add --repo <path> --doi <doi>
python3 scripts/registry.py add-pdf --repo <path> --file <pdf>
python3 scripts/registry.py import-bib --repo <path> --file refs.bib
python3 scripts/registry.py import-folder --repo <path> --dir papers/ --recursive
python3 scripts/registry.py list --repo <path>
python3 scripts/registry.py pool --repo <path>

Pool Reuse

No slash-command wrapper yet — this is internal run plumbing, not a standalone ask. See Repo architecture for what each step does to the canonical store:

python3 scripts/pool.py seed --run-dir <run> --repo <path> --query "..."
python3 scripts/pool.py lookup --repo <path> --pmid <pmid> --project <slug>
python3 scripts/pool.py reuse --run-dir <run> --repo <path> --pmid <pmid> --project <slug>
python3 scripts/registry.py promote --repo <path> --run-dir <run>
python3 scripts/registry.py appraise-promote --repo <path> --run-dir <run> --project <slug>

Full-Text Acquisition

No wrapper — Stage 4 plumbing, but worth knowing by hand when a run stalls on a ladder handoff (Stage 4):

python3 scripts/fulltext.py acquire --corpus <corpus.jsonl> --run-dir <run> \
    [--only-pmid X] [--from-tier N] [--email addr] [--offline] [--no-ocr] [--workers N]
python3 scripts/fulltext.py status --run-dir <run>
python3 scripts/fulltext.py resolve-mcp     --run-dir <run> --evidence-id <id> (--text-file <p> | --status unavailable)
python3 scripts/fulltext.py resolve-browser --run-dir <run> --evidence-id <id> (--text-file <p> [--institutional] | --status unavailable)

python3 scripts/library.py ingest-inbox --run-dir <run> --wiki <root> [--no-apply]
python3 scripts/library.py lookup --wiki <root> (--doi|--pmid|--pmcid|--title|--sha256)

--from-tier N discards rung state at or above N and walks again from there; --offline marks network rungs skipped rather than failed, so a later online pass still tries them.

Paper Summaries

/deep-research:summarize --repo <path> --pmid <pmid> --project <slug> --format both
/deep-research:summarize --repo <path> --pdf paper.pdf --project <slug>
/deep-research:summarize-set --repo <path> --pmid 123 --pmid 456 --overview
/deep-research:summarize-set --repo <path> --topic "..." --limit 10 --select-only

/deep-research:extract --repo <path> --pmid <pmid>                       # fetch + extract, no summary/appraisal
/deep-research:extract --repo <path> --pmid 123 --pmid 456 --pmid 789    # same, for a set

extract is summarize-set --extract-only under the hood — same selection surface (explicit ids, --ids-file, --bib, --folder, or --question/--topic discovery), stopped one stage earlier: it promotes a verified extraction into the registry and never dispatches an appraisal or summary subagent.

Flags, statuses, and output sections: Paper summaries.

Reference Manager

/deep-research:search --repo <path> --journal "JAMA" --min-rating 4
/deep-research:search --repo <path> --q "biomarker threshold" --tag diagnostics
/deep-research:search --repo <path> --similar-to pmid:38214501 --limit 5
/deep-research:search --repo <path> --mesh depress --article-type randomized
/deep-research:annotate tag  --repo <path> --evidence-id pmid:38214501 --add to-read
/deep-research:annotate rate --repo <path> --evidence-id pmid:38214501 --stars 4
/deep-research:annotate note --repo <path> --evidence-id pmid:38214501 --set "..."
/deep-research:annotate list --repo <path> --tag to-read --min-rating 3
/deep-research:embed index   --repo <path>
/deep-research:embed similar --repo <path> --evidence-id pmid:38214501 --k 5
/deep-research:embed query   --repo <path> --text "does X reduce Y?" --k 10
/deep-research:ask --repo <path> "does exercise reduce depressive symptoms in adolescents?"
/deep-research:alerts save --repo <path> --name cbt --query "CBT AND adolescents"
/deep-research:alerts run  --repo <path> --register
/deep-research:reindex --repo <path>
/deep-research:doctor  --repo <path> --deep
/deep-research:missing-fulltext --repo <path> --status included
/deep-research:okf-export --repo <path> --evidence-id pmid:38214501 --wiki <wiki-root>

embed index and embed query require the optional third-party package sentence-transformers — the one scoped exception to the skill's no-pip-installs policy; ask runs without it, on lexical retrieval alone. ask answers only from spans that verify against the snapshot store, and only from papers the repo already holds — it is not a literature search. okf-export requires each --evidence-id to already have an extraction on file. missing-fulltext reports every registered paper with no PDF stored, each with a doi.org/PubMed link for manual retrieval — read-only, it never fetches anything itself. Details: Reference manager.

ReadCube Export

/deep-research:export --repo <path> --all --destination <folder> --require-pdfs
/deep-research:export --repo <path> --evidence-id pmid:38214501 --destination <folder> --incremental
/deep-research:export --repo <path> --run-dir <run> --destination <folder> --bib --dry-run

Distinct from okf-export: this publishes a local RIS + PDF bundle for the ReadCube desktop app, not an OKF wiki bundle — it never touches wiki state and needs no extraction on file. Add --source refmgr --library <path> to read from the newer SQLite reference-manager layer instead of the registry (supports multiple attachments per paper; --all/ --evidence-id selection only, not --run-dir). Details: ReadCube export.

Run Monitoring

/deep-research:status <run> --table
/deep-research:status <run> --missing
/deep-research:watch --run-dir <run> --once

And the task board and no-progress guard, which have no wrappers:

python3 scripts/corpus.py task list --run-dir <run> --stage extract
python3 scripts/corpus.py guard --run-dir <run> --no-record    # status check, records nothing
python3 scripts/corpus.py prisma --run-dir <run>

Use --no-record when polling: every recording call appends a probe, so repeatedly checking a legitimately parked run manufactures the flat window the guard looks for.

Verification And Rendering

/deep-research:verify run --run-dir <run> --report <run>/outputs/report.md
/deep-research:verify single-paper-summary --summary <run>/workspace/summaries/pmid-123.json --run-dir <run>
/deep-research:verify paper-summary-set --summary-set <run>/workspace/summary-set.json --run-dir <run>

No wrapper for assembly or for HTML/PDF/docx rendering — and the order matters (why):

python3 scripts/assemble.py run --run-dir <run> [--strict]
python3 scripts/verify.py run --run-dir <run> [--gate]
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
python3 scripts/okf.py promote --run-dir <run> --wiki <root> --check
python3 scripts/okf.py promote --run-dir <run> --wiki <root>

Script Index

What each script owns, when you need to go below the command layer:

Script	Job
`eutils.py`	esearch / efetch / elink, throttle, retry, hit counts, translated query
`fulltext.py`	The acquisition ladder — resumable, with the truncation detector
`library.py`	Wiki-mode PDF index, matching, inbox ingestion
`pool.py`	Shared extraction/appraisal pool, `--wiki` or `--repo`; `seed` before search, `reuse` carries spans across runs; `migrate --from-wiki`; wiki-wide BibTeX
`research.py`	Standalone repo mode: `init`, `project`, `export wiki`, `okf-export`
`registry.py`	The canonical registry: intake, lookup, promotion, search, facets, reindex, doctor, BibTeX
`corpus.py`	`corpus.jsonl`, dedupe, PRISMA counters, the `task` CLI, guards
`paper.py`	Single-paper and selected-paper summary profiles
`store.py`	Evidence kernel: immutable snapshots, spans, event log, freshness
`source.py`	`fetch` / `read` / `spans` / `local` over the snapshot store
`assemble.py`	Admissibility gate → `outputs/result.json`
`verify.py`	Citation / corpus / OKF / kernel consistency checks
`okf.py`	Bundle concept writer and validator
`render.py`	`report.md` → `.qmd` + `refs.bib` → quarto render (pdf/docx)
`html_report.py`	Self-contained HTML deliverable: evidence table, effect-direction chart, per-study cards
`status.py`	Stage, progress bar, per-paper coverage table, missing list
`watch.py`	Read-only TUI; attaches to a live or finished run
`annotations.py` · `embeddings.py` · `ask.py` · `alerts.py`	The reference-manager layer
`export.py` · `ris.py` · `export_ledger.py`	ReadCube bundle publication
`eval.py`	Fixture-based smoke harness; `--live` for real PubMed

All scripts are python3 (there is no python on this machine), stdlib plus requests and pdfminer only. No pip installs — with the single scoped exception of embeddings.py.

Full flag reference for a command: commands/<name>.md, or /deep-research:help. For a raw script: python3 scripts/<name>.py --help.