concierge

The guide to an Oto project: where it is in its life, what the choices are at this point, why Oto does what it does, and which playbook to load next. Use when someone asks "where am I", "what should I do next", "what are my options", "why did it do that", "explain this", or opens a project without a specific task. It quotes the engine's own commands and hands off to the other skills; it never does their work.

The concierge

An Oto project moves through stations: documents in the inbox, Markdown in the corpus, a vocabulary, proposals, a candidate, four gates, a build, a served graph. The engine knows where a project is and says so.

This skill's job is to read that, add the sentence of context a newcomer needs, offer the options at the fork in front of them, and name the playbook that does the work.

The rule that matters most

Quote the engine; never restate it. Run the command, show its output, then explain. The engine's rules change with the code; a paraphrase drifts. If a question is "what will happen if I run X", the honest answer is X's --dry-run or --help, shown.

Three more: offer at most three options at a fork and recommend one; never suggest weakening a gate to make a step feel faster (no --force, no --allow-personal-data, no writing to graph.json by hand); never read, print or ask for a secret (ANTHROPIC_API_KEY, NEO4J_PASSWORD, OTO_SERVE_TOKEN and the other tokens live in the environment only).

1. Orient

Always first, before any advice:

oto status --project <root>          # where the project is, and one next step
oto status --project <root> --json   # the same, for a tool

Quote the output. Then add one sentence for the station it names:

A next: line is the engine's recommendation. Do not contradict it; if the person wants something else, show the fork below and say what the recommendation assumes.

2. The map

One screen. Every arrow is a command; every file named is the only place that thing lives.

documents  --oto ingest-->  build/documents/*.md     (the corpus; processing/ holds the run)
corpus     --oto survey-->  what it is about           (headings, recurring terms, figures)
reading    --ontology-interview skill-->  ontology.config.json + ontology.rationale.json
           --oto ontology check / rationale --strict / accept-->  ontology.lock.json
documents  --build-knowledge-base skill, oto draft-->  proposals/<doc>.json
proposals  --oto curate start / add-->  graph.candidate.json
candidate  --oto curate check-->  the report: blocking problems, contradictions, gaps, personal data
candidate  --oto curate apply --by --note-->  graph.json + changelog   (the ledger)
graph.json --oto build-->  build/: entities, rules (derived.json), ontology, cards, <slug>.db, site
build      --oto serve-->  kg_* tools (stdio) | --http: the explorer, /api/graph
build      --oto bench run-->  answer quality against gold/questions.jsonl

The four gates, in the order a fact meets them: the reader recaps the document before proposing (gate 1); what is already believed is checked before writing (gate 2); oto curate check must be clean (gate 3); a person says yes at oto curate apply (gate 4).

In repository mode gate 4 is a pull request. The detail behind each is printed, not remembered:

oto curate check --project <root>        # what the candidate would break, contradict, or leave uncited
oto ontology check --project <root>      # what changed in the vocabulary since it was accepted
oto rules check --project <root>         # the rules dry-run over the graph
oto vet --project <root>                 # facts citing a document nobody can open
oto bench validate --project <root>      # the gold set's shape

3. The forks

4. Why

Oto writes its reasons down. When someone asks why, print the reason from where it is recorded; if nothing is recorded, say that, because an unexplained rule or class is a finding in itself.

5. Hand-off

The concierge ends its turn by naming the skill. It does not start the work.

6. Questions about the graph itself

Route to query-knowledge. Two exceptions the concierge handles itself:

• A question about a fact that is on its way in: oto query pending --project <root> lists what sits in a proposal or the candidate, by station, with the verdict and the reason for a refusal. Say which station it is at and never present it as believed.
• "What is this project?": oto status, then the project's README.md and GUIDE.md when it has one, quoted, then the counts from oto query overview.
• "What can be done about X?": oto query actions --on <entity> (the kg_actions tool) lists the actions the graph declares on it, ready or not and why, with the inputs bound and the declared way to invoke. Oto never invokes; the caller does, then oto actions record <id> --on <entity> --by <who> --response <file> turns the response into a run record, a source document and a proposal that goes through the gates. Say which.