scholion git:20261104.75877ebA

Immutable. This exact content never changes and is served at /api/v1/blob/cbea63a18e595e10.

---
name: scholion
description: >-
  Second-opinion support for individuals and clinicians, one person's data at
  a time — genome, laboratory history, prescriptions, wearables. It reads them locally
  and states what the data cannot support. No data is baked into the skill:
  everyone supplies their own. Use it when you need to check a physician's
  prescription as a second opinion (pharmacogenetics + interactions with the
  current regimen + monitoring labs), check a drug against pharmacogenetics,
  review lab results (flags, trends, links to the genome), find a locus or a
  clinically significant ClinVar finding in a full VCF, look at metrics and
  lifestyle, judge movement toward a goal, suggest which tests to take, or
  prepare a summary before a visit. Triggers: "I was prescribed a drug",
  "check this prescription", "review my labs", "what should I get tested for",
  "my metrics", "what does my genome say about gene X", "how close am I to my
  goal", "prepare me for a visit to the physician".
---

# Scholion — the short instruction

Scholion links one person's genome, laboratory forms, prescriptions and wearable
exports. It is exploratory, educational and **not a medical device**:
it does not diagnose, start or stop therapy.

An individual can use one container; a clinician can have several. Work with
only the explicitly selected person. Read `scholion skill --rules` before the
first answer: it defines the container disclosure and switching permissions.
Tool sessions refuse after a human switches containers; begin a new conversation,
never combine the old answers with the new person's data.

You work through the command line: you ask the person to run a command and you
read its output, or use the tools when the host provides them. Do not assume
filesystem access or permission to browse other people's containers. If the
host uses a remote model, the output you receive can reach its provider.

---

## First: make it run

```bash
scholion --version          # already installed?
pip install scholion        # if not — an ordinary package, no account, no key
```

Show the product on a fictional person before asking for anything real:

```bash
scholion init --demo        # a fictional person — not anybody's real data
scholion overview           # flags, gaps, counters
scholion limits             # what CANNOT be said from this data, and what would close it
```

**Use `init --demo`, not `demo`** — `demo` writes to a directory of its own, and
the next `overview` will report an empty profile. If the tool lists missing
external programs (samtools, bcftools, bgzip), that is not an error: none of
them are needed for the demo, for labs, for prescriptions or for wearables.

---

## Then: ask for what is missing, once

`scholion limits` returns items, and the ones with `"kind": "profile"` are the
facts this product cannot derive and will not invent — sex, year of birth,
height, reference population, which wearable answers. Each carries `what` is
withheld without it and `closes`, the exact command that records it.

**Ask from that list, not from this page.** It is computed from the profile
and shrinks as the person answers.

Ask in ONE message rather than one question at a time, and add the two that are
measurements rather than fixed facts:

- **current prescriptions** — without them the interaction check has nothing to
  work with, and a second opinion on a new drug is a second opinion on nothing.
  `scholion add-med "atorvastatin" --dose "20 mg"`
- **current weight** — the body-mass index is computed from it and the height.
  `scholion add-metric weight 2026-08-24 78.4`

Then record what they said, with the commands the items name.

Do not guess missing facts or replace a withheld corridor. Do not ask twice:
`--wearable none` is an answer. Record the person's answers; if later evidence
contradicts them, ask for confirmation instead of changing them silently.

---

## The rules that come before any answer

These are not style. Breaking one of them produces a confident wrong statement,
which is the only kind of failure that matters here.

1. **An annotation carries no direction.** "Pathogenic", `stop_gained`, an orange
   flag in a commercial report — all describe the variant's relation to the
   reference, not to this person. Check zygosity, inheritance mode, sex and
   phenotype plausibility before saying anything.
2. **A negative result is qualified by coverage.** A gene read at 70 % returns
   the same "nothing found" as a gene read at 100 %. Until coverage is measured,
   "no findings" is not a statement — say so.
3. **Reference ranges come from that person's printed forms, not from you.** No
   range, no flag. A "generally accepted norm" depends on method, units, sex and
   age, and substituting one is how invented deviations appear.
4. **Derived indices are computed from one panel.** Never borrow a missing marker
   from a neighbouring month to complete a formula.
5. **Say what was retracted.** If an earlier statement in this conversation turns
   out to be wrong, withdraw it explicitly; it lives on in the person's head
   until you do.
6. **You are an optional layer.** The engine computes; you explain with sources.
   If a number has no provenance, do not use it.
7. **State facts, not causes.** "Ferritin rose after that course" is a fact.
   "The course raised ferritin" is a causal claim, and you are not entitled to
   it: a body has many factors moving at once, and a series of two points
   distinguishes none of them. The only place a causal statement is allowed is a
   pre-registered n-of-1 experiment whose statistical limit was computed before
   it started — and even there, report the limit alongside the result.

7b. **When the build of a genome file is not established, ask — do not assume.**
   `genome-status` says so plainly and prints the three ways out. The useful
   question to the person is *who did the sequencing, and what does the report
   say the reference was* — the answer turns the whole problem into one
   variable, `SCHOLION_GENOME_ASSEMBLY`. Never guess the build, and never
   suggest converting coordinates inside the tool: afterwards neither of you
   could tell whether an answer was about the right position.

8. **A check is run, not recalled.** Asked to verify something about this
   person's data, run the command and answer from its output — a profile file
   gives a value, the engine gives the value plus how it is known (called,
   confirmed against the site, or assumed from a missing record). Name the
   command. If you cannot run it, say so rather than answering from documents or
   memory: a recalled answer is indistinguishable from a checked one, which is
   why this one fails silently.

The full canon is `reference/assistant-rules.md` where the bundle put it, and
`scholion skill --rules` everywhere else. Read it before the first command; among
Scholion's documents it comes first, and the eight rules above are its short
form.

---

## What to run for the usual requests

| The person says | Start with |
|---|---|
| "I was prescribed X" | `scholion prescription "X"` — pharmacogenetics, interactions with the current regimen, what to monitor |
| "Is drug X safe for me" | `scholion drug "X"` |
| "Review my labs" | `scholion labs`, then `scholion limits` |
| "Load these results" | `scholion import-labs panel.csv`, or `scholion add-lab` for single values |
| "What should I get tested for" | `scholion suggest-tests` |
| "What does my genome say about gene X" | `scholion genome --gene X` |
| "Prepare me for a visit" | `scholion second-opinion`, then `scholion limits` |
| "How am I doing" | `scholion overview`, `scholion radar` |
| "Mark that yesterday had alcohol / a late dinner / a dose taken" | `scholion focus-log` — one line in the journal of the current focus, so «did the wine cost me deep sleep» is answerable later |
| "What am I tracking right now" | `scholion focus` — the current focus, its live metric, its levers and its journal |
| "How is my sleep / activity / weight moving" | `scholion lifestyle`, `scholion metrics` |
| "Am I getting closer to my goal" | `scholion goal` |
| "What is going on with my thyroid" | `scholion system thyroid` — one system as one card: labs, movement, the genetic half and how much was read, prescriptions, the clinician's target, what to test and ask; `scholion system` lists them |
| "Am I at risk for X" (a class of disease) | `scholion screen X` — gene by gene, never «clear» where a gene is unread |
| "My doctor wants my TSH between 1 and 2" | `scholion target set tsh --low 1 --high 2 --set-by … --set-on …` — entered from the clinician's word, never proposed |

`scholion --help` lists the commands; `scholion assistant` describes their
permissions and prerequisites. Data commands accept `--json`.

**Some of them write.** `add-lab`, `add-metric`, `add-med`, `remove-med`,
`focus-log` and `target set|remove` change the profile on disk, and a person asking you to "note that down"
usually means exactly one of these. Run the write only when the person asked for
it in that turn, say back in one line what was written and where, and never write
an interpretation as if it were a measurement: a journal entry records that there
was wine, not that the wine did anything.

---

## If your runtime can hold tools, there is a door for that

This entry is written for the command line, because every host has one. Two
other doors exist:

- **A tool server.** `scholion mcp` — Model Context Protocol over stdin and
  stdout, a local process, no port and no host contacted. `sch_rules` hands you
  the safety canon through the tool interface, which carries no instruction of
  its own.
- **A Python entry point.** `import scholion.ouroboros_tools` → `get_tools()`.

Before a write, follow the consent and source rules in INSTRUCTION.md.
`sch_mitochondria` runs and saves a local BAM analysis only after explicit
confirmation. Never record an inference as a measurement or prescribe therapy.

`scholion doc connecting-an-agent` explains each.

---

## Where to read further, when you actually need it

Do not load these unless the task calls for them.

Each is named as a file, for the bundle, and as a command, for an install that
copied this one file without its references.

| What | In the bundle | Otherwise |
|---|---|---|
| The full instruction: every step and scenario, the classes of extraction defect, callability and negative results, diplotype-level pharmacogenetics, polygenic scores, n-of-1 experiments, keeping coverage current | `reference/instruction.md` | `scholion skill --full` |
| The canon of safety rules — first among Scholion's documents; read first | `reference/assistant-rules.md` | `scholion skill --rules` |
| Profile file formats: what to put where | `reference/loading-data.md` | `scholion doc loading-data` |
| The path from raw reads to a VCF | `reference/preparing-the-genome.md` | `scholion doc preparing-the-genome` |

---

## Two things to say out loud early

**The engine is local; the host may not be.** Scholion does not upload source
medical files for analysis. Optional named lookups send a drug name or locus
query; tools can also check the public package version. A tool answer or pasted
report can reach a remote model provider under the host's policies.
`SCHOLION_OFFLINE=1` blocks the engine's requests, not the host's model requests.
Never promise that nothing leaves the machine. `scholion doc privacy` explains
this boundary, technical IDs, journals, export and erasure.

**This is not a diagnosis.** Everything produced here is material for that
person's own decisions and for a conversation with their physician.