Skip to content

Your first corpus, by hand

Six files, an editor, and the binary. No agent session and no template checkout. Under twenty minutes.

quickstart.md §4 makes a corpus the way the product means it to be made. The ontology is argued out in a dialogue with an agent. That is the better corpus, and it is not the shortest way to see what one is. It needs a checkout of the yidam template and an agent session, and a reader without either stops at §3.

This page is the other route. You write the files. Nothing here is a lesser corpus. The tree you finish with passes graph-check and lint, answers open-questions, and serves over MCP. It is the same shape the bootstrap dialogue produces, reached by typing instead of talking.

What is not here. No .yidam.toml, no REGEN blocks, no lint baseline, no decision records. Each is optional, and each is easier to add once you have something to add it to.

If you want the skeleton without typing it, run yidam init in a git repository. It writes this same shape with placeholders, and every placeholder says what to replace it with. This page is then the explanation of what it produced: the keys, and why each one is there. Read it either way — the command saves the typing, not the understanding.


What a corpus is, as files

Everything lives under .yidam/corpus/, and there are two kinds of file in it.

FileWhat it is
<class>.ont.ymlA class — the kinds of thing in your domain, and what may link to what
<class>/<slug>.ymlAn instance — one node of that class

A third directory, .yidam/catalog/, registers the sources nodes draw on. One entry is enough, and step 4 says why you want it.


1. Make the repository — one minute

mkdir tailwater && cd tailwater
git init
mkdir -p .yidam/corpus/concept .yidam/corpus/gauge .yidam/catalog

The git init is not ceremony. A corpus is a git history with a gate over it, and lint dates a finding against that history.


2. Declare two classes — five minutes

This is the part the dialogue exists for, and the part to spend your time on. Two classes and one relationship are enough to start. A concept is something you are trying to understand; a gauge is an instrument that measures one.

.yidam/corpus/concept.ont.yml

class: concept
label: Concept
description: A unit of understanding in this corpus.
properties:
  - name: claim_tag
    type: claim
    description: The evidence standing of this node.
edges:
  - relationship: relates-to
    target: concept
    direction: out
    description: A bare association between two concepts.
  - relationship: measured-by
    target: gauge
    direction: in
    description: A gauge measures this concept — authored on the gauge.

.yidam/corpus/gauge.ont.yml

class: gauge
label: Gauge
description: An instrument reading a concept in the field.
properties:
  - name: station
    type: string
    description: The operator's identifier for this station.
edges:
  - relationship: measured-by
    target: concept
    direction: out
    description: The concept this gauge reads.

Three things are being decided here, and only the first looks like a decision.

direction says who authors the edge. measured-by is declared out on the gauge and in on the concept. So the link is written in the gauge's file, and the concept gets it without being edited. Declaring it out on both would let two files disagree.

A property typed claim is an evidence tag, not a string that happens to hold one. The declaration is what makes the bare value verified count. Untyped, it is an ordinary string. A bracketed [verified] in the prose is counted either way.

An edge you do not declare is a broken link. That is the whole of what a class is for. relates-to between two concepts is licensed, and anything else fails the gate.


3. Write three nodes — five minutes

.yidam/corpus/concept/low-flow.yml

class: concept
label: Low flow
description: >-
  A discharge regime — the flow a channel falls to between storms. Read off
  [the stage–discharge relation](../../catalog/stage-discharge.md). [verified]
properties:
  claim_tag: verified
links:
  - target: ../concept/mixing-zone.yml
    relationship: relates-to

.yidam/corpus/concept/mixing-zone.yml

class: concept
label: Mixing zone
description: >-
  Where the discharge plume stops being distinguishable from the receiving water.
  Nobody here has measured it. [open]
properties:
  claim_tag: open
links:
  - target: ../concept/low-flow.yml
    relationship: relates-to

.yidam/corpus/gauge/riffle-station.yml

class: gauge
label: Riffle station
description: A stage gauge at the riffle, reporting every fifteen minutes.
properties:
  station: "03274000"
links:
  - target: ../concept/low-flow.yml
    relationship: measured-by

One node is [verified] and one is [open], and that asymmetry is the point. A corpus where every claim is settled is a corpus whose tags are decoration.

links: targets are paths relative to the file they are written in, which is why each one starts ../. The gauge authors the measured-by edge because step 2 declared it out there.


4. Register the source — two minutes

A [verified] claim resting on nothing is a finding, and lint will say so. A catalog entry is what it rests on.

.yidam/catalog/stage-discharge.md

---
name: Stage–discharge relation
description: The rating curve the low-flow figures are read off.
type: paper
obtained: true
---

Where the numbers came from.

The link in low-flow.yml is an ordinary markdown link into .yidam/catalog/. That is the whole citation mechanism. Nothing else has to be configured.


5. Let the editor fill in the rest — one minute

yidam schema

It writes JSON Schema for every shape above into .yidam/schemas/. That includes one file per class, derived from what you declared in step 2. yidam schema --settings prints the block to paste into .vscode/settings.json. After that an editor completes property names and rejects a class you have not declared.

This is optional and it is the step that changes how the next hour feels.


6. Run the gates — two minutes

Commit first. The genesis subject is where export and bundle read the domain name from.

git add -A && git commit -m 'genesis: tailwater'
yidam graph-check
# Checked 3 instances across 2 classes — all clean.

yidam lint
# lint: 0 finding(s), no errors

yidam open-questions
# - [Mixing zone](.yidam/corpus/concept/mixing-zone.yml)

yidam status
# **3 nodes** · 1 open · 1 sources · claims 2v / 0i / 2o

Now break it, because a gate you have not watched fail is a gate you do not believe. Delete the links: block from low-flow.yml:

ERROR [orphan-out] Node connected to nothing — 1 finding(s)
  .yidam/corpus/concept/low-flow.yml: no outgoing links

Exit code 1. Put it back, and read quality-rubric.md for what else is checked.

yidam doctor will warn that there is no vector index. That is accurate and it is not a problem. retrieve falls back to keyword search, and says degraded when it does.


7. Point an agent at it

claude mcp add yidam -- yidam serve --mcp

The server answers on this tree with no further setup. mcp-server.md has the tools and the ways to read their answers.

The Claude Code plugin registers the same server and adds the skills that call it. One of them, starting-a-corpus, is this page driven by an agent. Reach for it on the next corpus; this one is already written.


The worked minimum, kept honest

The corpus above is the shape of yidam/sdks/parity/fixtures/reports/basic/repo/.yidam/, which every report golden in this repository is generated from. It is two .ont.yml files, four instances and a catalog, and it is exercised on every commit.

yidam/cli/tests/first_corpus.rs builds this page's files out of the blocks above and runs the gates over them. A command whose output drifts from what is printed here fails there.


Then grow it with the dialogue

What you have is a corpus, not an ontology you have argued about. Two classes were chosen in five minutes, and the second week is where that shows.

The bootstrap dialogue is the repair, and it reads better as a second step than a first. You arrive at it with files to disagree with rather than a blank page.

Derive the repository before you write the corpus, if you can. Both yidam clone and yidam overlay refuse a tree that already holds .yidam/. Run this on the empty repository from step 1, then write steps 2 to 4 inside it:

git clone https://github.com/goedelsoup/yidam
cd yidam && yidam overlay /path/to/tailwater

overlay adds the prelude, the task layer and the agent routing to a repository that already has content. An agent opening it afterwards finds no commits, reads BOOTSTRAP.md and enters the dialogue.

Already wrote the corpus first? yidam clone ~/tailwater-full makes a fresh derived repository, and .yidam/corpus/ moves across as ordinary files.

quickstart.md §4 is the dialogue itself, and bootstrap-flow.md is its specification.

Where to go next

If you wantRead
The rest of the loopquickstart.md
What a class should spanontology/what-an-ontology-is.md
How to write a nodeinformation-architecture.md
What the gates checkquality-rubric.md
What the terms meanvocabulary.md