Setup

Expand the wiki with new papers. Configure optional integrations. Understand where files land.

The wiki ships pre-built

The cloned repo includes a wiki with 335 entities compiled from a 50-paper wedge. You can start querying immediately -- no setup required. This section covers how to expand the wiki with additional papers or configure optional features.

Expanding the wiki

Option A: Let the orchestrator do it

When you ask a question and the wiki is thin for that domain, the orchestrator automatically searches PubMed, ingests relevant papers, compiles new entities, and then answers your question. You don't need to do anything.

Option B: Ingest specific papers

If you know which papers you want, use the slash command inside Claude Code or the CLI directly:

# Inside Claude Code (slash command)
/compile PMC10103184 PMC9876543 PMC8765432

# Or from the terminal (CLI)
python3 scripts/pmc_convert.py --pmids_file my-papers.txt --out store/raw/papers

The compile workflow extracts intelligence dimensions from each paper (one Sonnet subagent per paper, in parallel), resolves entities against the wiki, and merges new entities into store/wiki/. Every wiki write is hook-gated -- bad frontmatter blocks the write.

Option C: Ingest from reference lists

The repo includes curated reference lists:

# 50 PMC papers (the original wedge)
python3 scripts/pmc_convert.py --pmids_file references/example-pmids.txt --out store/raw/papers

# 76 clinical trials
python3 scripts/ct_convert.py --nct_file references/example-ncts.txt --out store/raw/trials

Rebuilding the index

python3 scripts/wiki_index.py --wiki store/wiki

Regenerates the 7 index files under store/wiki/index/. Idempotent -- same wiki state produces byte-identical indices. This runs automatically after compile, but you can trigger it manually after any wiki change.

Environment variables

All optional. viCRO works without any of them.

ANTHROPIC_API_KEY -- required only for the production webapp route. The CLI uses your Claude Code subscription directly.
.notion-token -- file in the repo root. Enables python3 scripts/md_to_notion.py for Notion delivery.
.openai-key -- file in the repo root. Enables semantic search embeddings. Falls back to TF-IDF when absent.

Store layout

store/
  raw/                  # Immutable. Source documents as fetched.
    papers/PMC.../      #   source.xml, paper.md, meta.json
    trials/NCT.../      #   source.json, trial.md, meta.json
    uploads/            #   institution_slug/...

  wiki/                 # The living graph. Markdown + YAML frontmatter.
    cohorts/            #   75 cohort entities
    institutions/       #   103 institution entities
    investigators/      #   101 investigator entities
    platforms/          #   46 platform entities
    bundles/            #   10 procurement bundles
    protocols/          #   collection protocols
    index/              #   7 auto-generated index files

  queries/              # One directory per query run.
    2026-04-09_slug/    #   request.json, candidates.json, recommendation.md, ...

  runs/                 # Compile telemetry. Token counts, wall times.

  lint/                 # Scan results. Gaps, consistency, staleness.

raw/ is write-once. wiki/ is continuously compiled. queries/ is the audit trail. Every query run is reproducible from its artifacts.

Verifying the setup

# Check entity count and browse summaries
python3 bin/vcro wiki browse

# Validate all entities against the schema
python3 bin/vcro wiki verify

# Check version
python3 bin/vcro version

Optional: TUI enhancements

The bin/vcro CLI works with stdlib Python only. For a richer terminal experience (colored output, spinners, markdown rendering), install the optional packages:

pip install rich prompt_toolkit

These are auto-detected at startup. The CLI gracefully falls back to plain output when they are absent.