# ThoughtML — a guide for the AI that writes it

You are most likely the author. ThoughtML is a plain-text language for recording
**reasoning you keep** — claims, evidence, decisions, and how they change over time —
as a graph a machine can read back. It is written far more often by an AI agent
transforming prose (a report, a case study, a debate, a postmortem, a decision) into
structured thought than by hand. This file is the whole language in one place: read it
once and you can author correct ThoughtML and interpret everything the toolchain gives
back. It is the exact spec the `thoughtml guide` command prints and the site serves — one
source, so it cannot drift from the tool.

The single governing idea: **ThoughtML is a mirror, not an oracle.** It does not decide
for you. It reflects the reasoning you put in — and *surfaces where that reasoning
disagrees with itself*: a confidently-held claim your own evidence defeats, or one belief
defined two incompatible ways. Your job when authoring is to record the reasoning
faithfully so the mirror stays honest. The fastest way to break it is to **overstate** —
e.g. use an evidence relation to write a plain list. The rules below exist to prevent
exactly that.

Everything here is derived from the reference parser's vocabulary and compute code, not
from prose docs. The closed sets (kinds, relations, fields, postures) are **exhaustive** —
if a word is not listed, it does not exist, and inventing one earns a warning (or, worse,
silently changes how a line parses). When unsure, prefer the smaller, more literal
construct.

---

## 1. The 60-second model

A document is a flat or nested list of **records**, one per header line, each with an
indented block beneath it. There are six things you can record:

- **focus** — a node you reason about (a claim, an observation, an option, a goal…).
- **question** — an open question the document is trying to resolve.
- **link** — a typed, directed edge between two nodes (`X supports Y`).
- **stance** — an *agent's* attitude toward a node or edge (the only place `confidence` lives).
- **scope** — a named container grouping related records.
- **profile / import** — advanced: dialect extensions and multi-document namespaces.

From these, the toolchain **derives** readings you never write by hand: a confidence
propagated along evidence, a grounded argument status (which claims survive attack), a
timeline, expected values over a decision, and a **conflict report** (the mirror). You
author the graph; you read back the derived readings (§13). Nothing is computed until you
ask (`--compute` / `--audit`).

Nothing is ever deleted. A superseded belief, an abandoned branch, a divergent
redefinition — all are kept with their reason. **"Fold, don't forget."**

---

## 2. Syntax rules

- **Indentation is structure.** A record's block is the lines indented under its header.
  Nesting a record under a `scope`/`focus`/`question` makes it a *member* (§9). Use
  consistent spaces.
- **Ids are `lowercase-kebab-case`** — `[a-z][a-z0-9-]*`, starting with a letter:
  `cache-is-safe`, `error-rate-up`. One id = one node; mentioning an id again *merges*
  into that same node (§8). A namespaced reference is `ns.id` (only after `import`, §9).
- **Comments are whole-line only**: a line whose first non-space character is `#`. There
  are **no** trailing/inline comments — `focus x  # note` is not a comment, it's a parse
  error.
- **A header is one line**; its body prose, `field value` lines, `= formula` lines, and
  nested records follow, indented.
- **Body prose** is an indented line that is neither a `field` (`name value…`), a
  `= formula`, nor a nested header — it becomes the node's description. Write bodies as
  ordinary sentences (a leading capital or trailing punctuation keeps an all-lowercase
  line from being misread as a field). First mention of a body wins on merge.

Minimal shape — two typed foci and a link, so nothing dangles (strict-clean):

```thml
focus load-test-passed
  kind observation
  Held p99 under 2x peak traffic.

focus cache-is-safe
  kind claim
  Safe to ship the new cache layer today.

link load-test-passed supports cache-is-safe
```

---

## 3. Records and headers

The **first word** of a header decides what it is: seven reserved header keywords, plus
three sugar forms.

| Header form | Makes | Example |
|-------------|-------|---------|
| `focus <id>` | a focus | `focus cache-is-safe` |
| `question <id>` | a question | `question cause-of-shift` |
| `link [alias:] <from> <rel> <to>` | a link | `link load-test supports cache-is-safe` |
| `stance <agent> <posture> <target>` | an agent stance (longhand) | `stance payments-agent holds root-cause` |
| `scope <id>` | a container | `scope incident-742` |
| `profile <name>` | a dialect (advanced, §5/§6) | `profile appsec` |
| `import <name> as <ns>` | a namespace (advanced, §9) | `import control-library as baseline` |
| **`<kind> <id>`** (typed header, sugar) | a focus with that kind | `observation error-rate-up` |
| **`<relation> <target>`** (evidence bundle, sugar) | many links | see §10 |
| **`<agent> <posture> …`** (readable action) | a stance (+ maybe a focus/link) | `team noticed shift` |

If a header's first word is a **kind** (§5) it's a typed focus; if it's a **relation**
(§6) it's a bundle; otherwise it's read as an `<agent> <posture> …` action (§7) — and the
**second** word must then be a posture, or the line errors (`unknown record kind or
header`). So the first word (and an action's second word) is overloaded across the closed
sets — which is why inventing a kind / relation / posture doesn't merely warn, it can
change how a line parses. (`stance` longhand and the readable `<agent> <posture>` form
build the *same* stance object; use whichever reads better — `merge-conflict-beliefs`
mixes both to prove it.)

---

## 4. What can be linked

A link's `from`/`to` may resolve to a **focus, question, or link** (yes, links can target
links — that's how `undercuts` attacks an inference). Targeting a **stance** or **scope**
is an error (`TML202` — "links may only connect …"). Targeting an id that doesn't exist
yet is a warning (`TML201` unresolved reference) — declare it or fix the typo.

---

## 5. Foci and the ten kinds

A focus's `kind` is its semantic category. Set it with a `kind` field, a typed header
(`claim cache-is-safe`), or let a posture infer it (§7). The **ten** kinds are exhaustive:

| Kind | Meaning | Typically introduced by |
|------|---------|-------------------------|
| `observation` | Something seen or measured | `noticed`, or a typed header |
| `claim` | An assertion put forward as true | `infers`, or a typed header |
| `hypothesis` | A proposed explanation, not yet settled | typed header |
| `option` | A choice on the table | `considers`, or a typed header |
| `decision` | A choice to be made or recorded | `holds` / `chooses` |
| `outcome` | A result an option `leads-to` | edge inference, or a typed header |
| `goal` | A desired end | typed header |
| `assumption` | Something taken as given | typed header |
| `memory` | A recollection carried forward | `remembers` |
| `action` | A thing one *does* — a plan, intervention, mitigation | typed header only (no posture infers it) |

An unknown kind warns (`TML101`, with a nearest-spelling suggestion) unless a `profile`
declares it (§6). Two *explicit* kinds disagreeing on one focus keeps the first and warns.

---

## 6. Relations — the fourteen edges (READ THIS TWICE)

Relations are the heart of the language and the easiest thing to get wrong. Grouped by
role. **Only the first three carry evidence polarity** — they, and *only* they, move
derived confidence and argument status (§13).

### Evidence (defeasible — these move the numbers)
| Relation | Polarity | Use for |
|----------|----------|---------|
| `supports` | **+** | source is *evidence for* target |
| `opposes` | **−** | source rebuts a *node*: "that claim is false" |
| `undercuts` | **−** | source attacks an *inference*: "that step doesn't follow" (target is usually a **link**) |

### Structural & causal (no polarity — describe, don't argue)
| Relation | Meaning |
|----------|---------|
| `causes` | source brings about target (expected acyclic) |
| `enables` | source makes target possible |
| `prevents` | source stops target |
| `depends-on` | target is required for source (expected acyclic) |
| `blocks` | source holds target up (what `until … answered` desugars to) |
| `answers` | source *resolves* a question (the one settled answer) |
| `revises` | source supersedes target (nothing deleted; §11) |

### Decision
| Relation | Meaning |
|----------|---------|
| `leads-to` | an option leads to an outcome; carries a `probability` |
| `option-of` | an option belongs to a decision |

### Membership & candidacy (non-evidential — how you list things)
| Relation | Meaning |
|----------|---------|
| `part-of` | source is *one item in* the target collection |
| `candidate-for` | source is a *proposed* answer to a question (not resolved) |

**The mistake that breaks the mirror.** To *list* the items of something — SWOT strengths,
competitors, success factors, sub-points, friction points — use **`part-of`**, never
`supports`. `supports` means "evidence this is true," so enumerating a claim's parts with
it silently inflates that claim's confidence: "Netflix has strengths" reads as
100%-certain just for *naming* them. `part-of` has no polarity, so enumerations stay
structure and the numbers keep meaning something. Likewise use `candidate-for` for a
question's proposed options and reserve `answers` for the one that actually resolves it.
(`roadmap-priorities` and `control-library` show `part-of` done right; `differential-dx`
shows `candidate-for` vs `answers`.)

**Other easy confusions:**
- `opposes` (a claim is false) vs `undercuts` (a step doesn't follow — target the **link**).
  `pr-feedback` sets them side by side.
- `weight` (evidential strength, any evidence/structural link, `0..1`) vs `probability`
  (outcome likelihood, `leads-to` **only**, `0..1`). Putting one where the other belongs
  is ignored with a warning.
- `answers` doubles as a **field** and a **relation**: as an indented line,
  `answers <question>` on a stance/focus points it at the question it settles.
- There is **no** `rejects` or `mitigates` relation in the core. A hard rejection is
  `opposes`; defending X is attacking X's attacker (`guard opposes risk`). (`rejects`
  exists only as a *posture*, §7. A domain that truly wants `mitigates` declares it in a
  `profile` — see `threat-model`.)

**Profiles add relations (and kinds/fields/postures).** A `profile` header opens a dialect
whose declared words are then legal below it; anything it doesn't declare still warns.
Comma-separated lists:

```thml
profile appsec
  kinds threat, control, weakness
  relations mitigates, aggravates, exposes
  fields likelihood, severity
  postures flags
```

---

## 7. Stances and the twelve postures

A **stance** is an agent's attitude toward a node or edge — the only place a `confidence`
lives. You almost never write `stance` longhand; you write the readable form **`<agent>
<posture> <target>`**, where `<agent>` is any id you choose (`team`, `analyst`, `oncall`,
`classifier`). The **twelve** postures are exhaustive:

| Posture | Creates | Kind inferred | Shape |
|---------|---------|---------------|-------|
| `noticed` | focus + stance | `observation` | `team noticed metric-shift` |
| `considers` | focus + stance | `option` | `team considers rollback` |
| `holds` | focus + stance | `decision` | `team holds rollback-decision` |
| `chooses` | focus + stance | `decision` | `team chooses option-a` |
| `remembers` | focus + stance | `memory` | `team remembers last-outage` |
| `infers` | `claim` focus + `supports` links from the listed sources + stance | `claim` | `team infers X from a b c` |
| `suspects` | a **link** (`from rel to`) + a stance over it | — | `team suspects deploy causes shift as deploy-cause` |
| `asks` | a stance on an (existing) question | — | `team asks cause-of-shift` |
| `doubts` | a stance | — | `team doubts vendor-claim` |
| `accepts` | a stance | — | `team accepts postmortem` |
| `rejects` | a stance (rules a target out) | — | `team rejects option-b` |
| `revises` | a stance superseding this agent's *prior* stance on the target | — | `analyst revises on-track-claim` |

Confidence and rationale ride on the stance: put `confidence`, `note`, `because`, and
`asserted-at` in the block under a posture line. `confidence` may be a scalar
(`confidence 0.72`), a **range** (`confidence 0.25..0.70`, read at its midpoint), or
genuinely **unknown** (`confidence ?` — see `assistant-memory`). `suspects` takes a full
edge (`<from> <relation> <to> [as <alias>]`); `infers` takes `<target> from <id> <id> …`
and wires each source with a `supports` link, so the reasoning is explicit.

**Which postures declare a node vs. only reference one** (this decides strict-clean, §12):
the focus-creating postures declare their *target*; `suspects` declares *both* endpoints
of its edge; `infers` declares only its *target* — its **sources** are `supports`
endpoints you must declare elsewhere. `asks` / `doubts` / `accepts` / `rejects` /
`revises` create *only* a stance, so **their target must already exist**, or you get an
unresolved-reference warning.

---

## 8. Merging — one id, one node

An id mentioned more than once is **one** node; the mentions merge. `body`, `quantity`,
`formula` are first-wins; `fields` accumulate; `kind` follows priority (explicit >
posture-inferred). This lets you define a focus once in full, then refer to it by id
anywhere — including from another agent's stance, or a later scope.

**Divergence is kept, not dropped.** If a later mention gives a *different*
body/quantity/formula (not a repeat), the alternative is retained on the node and the
mirror raises a `definition-divergence` conflict (§13). Concurrent authors never clobber
each other — see `merge-conflict-beliefs`, where two teams define one `root-cause` two
ways and both survive.

---

## 9. Scopes, thought-trees, and imports (nesting)

Indent records under a `scope` to group them, or under a `focus`/`question` to make a
**thought-tree** — a claim (or question) and the reasoning that hangs off it, as one unit.
Nested members are recorded on the container's `includes` and **inherit its provenance and
temporal context** — an explicit value on the child wins. (`prod-outage` puts `source
pagerduty` and `observed-at` on a scope and lets the observations inherit; `roadmap-
priorities` nests candidate options under a question.)

```thml
focus ship-decision
  kind decision
  Ship the new cache layer this week.

  observation load-test-passed
    p99 held under 2x peak traffic.

  assumption rollback-ready
    One-command rollback is wired up.
```

**Imports (multi-document).** `import <file> as <ns>` pulls another document's nodes in
under a namespace; you then reference them as `ns.id`. The importer is checked as a
**project** (importer + library together) so cross-document references resolve. A library
must itself be strict-clean as a standalone document. See `control-library` (the library)
and `compliance-rollout` (`import control-library as baseline`, then `depends-on
baseline.encryption-at-rest`).

---

## 10. Numbers, provenance, formulas, and evidence bundles

**Ranges & clamping.** `confidence` / `weight` / `probability` are `0..1`. `weight` and
`probability` outside that range are **clamped** with a warning (`TML402`). `confidence`
is *not* clamped: it accepts a scalar, an ordered range `low..high` (unordered → error),
or `?` for genuinely unknown. `quantity` is a typed measure with a unit (`quantity 30 GB`).

**Provenance basis.** Any number may declare *how it was arrived at*, inline, from the
exhaustive set `measured` / `estimated` / `assumed`:

```thml
  confidence 0.9 assumed
  quantity 30 GB measured
  weight 0.85 estimated
```

A number with no basis is silent about it; the opt-in `--strict-provenance` lint flags the
omission (`TML401`). Prefer stating a basis — an unbased number reads as fact without
saying on what footing it stands.

**Formulas (`= expr`).** A focus can compute its `quantity` from other foci with a
`= expression` line over `+ - * /` and referenced ids. The parser **checks units** as it
goes (USD/hour × hour = USD; USD ÷ user = USD/user), so a dimensional mistake is caught,
not shipped. `--compute` evaluates them into `computed_quantity`. See `cloud-bill` (a
self-computing monthly bill) — change one input and the whole thing recomputes.

```thml
observation instance-price
  quantity 0.096 USD/hour
observation instance-hours
  quantity 21600 hour
focus compute-cost
  kind claim
  = instance-price * instance-hours
```

`compute-cost` computes to `2073.6 USD` — `USD/hour × hour` is unit-checked to `USD`, so a
dimensional slip is an error, not a silent wrong number.

**Evidence bundles** collapse the common "many sources → one target" repetition. A bare
`<relation> <target>` header lists sources one per line, each `<source> [weight <n>]
[basis]`, each desugaring to an ordinary link:

```thml
supports customer-pain-points
  late-fees-problem      weight 0.90 assumed
  limited-availability   weight 0.85
  long-travel-time
```

Bundles work with **any** relation — including `part-of` and `candidate-for`, the
idiomatic way to write a collection:

```thml
part-of netflix-strengths
  strong-global-brand
  large-subscriber-base
  advanced-algorithms
```

**A bundle links; it does not declare.** Every member id *and* the bundle target must be a
node declared somewhere (a `focus`/typed header/`question`, or a focus-creating posture).
An id that appears only inside a bundle is an unresolved reference and warns — so it breaks
strict-clean. Declare the nodes first (see gold example B, §15), then bundle them.

---

## 11. Time — optional, and how belief changes

**Time is optional. Do not invent timestamps to force an ordering.** A dateless document
parses and renders fine — the viewer reveals it in *document order* (narrative replay).
Reach for dates only when *when* actually matters.

When it does, three ISO-8601 fields (partial dates like `2026` or `2026-06` are fine):

- `observed-at` — when something was seen.
- `asserted-at` — when a belief was put on the record.
- `valid-during <start>..<end>` — a span over which something holds (`launch-readiness`).

**Lifecycle (`status`).** A focus can carry a `status`: `open` (default, live), `settled`
(resolved), `superseded` (replaced by a later belief), `abandoned` (a dead end). A
settled/superseded/abandoned branch is kept with its reason and folds in the viewer —
never deleted. (`choose-datastore` parks a rejected option as `abandoned`; `launch-
readiness` walks a call through `superseded`.)

**Revision.** `link new revises old` supersedes a *node*; the `revises` posture supersedes
the same agent's *prior stance*. Either way the old belief stays in the graph (it just
stops counting as live evidence). A revision asserted *earlier* than what it revises warns
(`TML304`).

**Replay.** `--as-of <time>` (valid-time) or `--as-of-seq <n>` (recording order) projects
the document to a moment: later beliefs — and the edges that depended on them — drop out,
and supersession and the audit recompute as of that instant.

---

## 12. The strict-clean contract — your feedback loop

This is the most important operational rule. **A good ThoughtML document is
"strict-clean": zero errors AND zero warnings.** Treat that as a fitness function — author,
run the parser, read the diagnostics, fix, repeat until clean. Every one of the 20 corpus
examples is strict-clean; aim for the same.

Run the reference CLI (`thoughtml <file>`); it prints diagnostics with source lines and
exits nonzero under `--strict` if any warning remains. Useful flags on the bare invocation:

| Flag | What it does |
|------|--------------|
| (none) | parse + validate; emit the canonical JSON model |
| `--strict` | treat warnings as failures (use this as your gate) |
| `--compute` | the whole second reading: derived confidence, argument status, sensitivity, formulas, decision EV, audit |
| `--audit` | just the conflict report (the mirror's headline) |
| `--as-of <t>` / `--as-of-seq <n>` | replay as of a valid-time / a recording step (§11) |
| `--html` | bake a standalone interactive viewer (for humans, not you) |
| `--ast` | emit the surface AST instead of the canonical model |
| `--strict-provenance` | also warn on numbers with no basis |

**Subcommands — the rest of the toolchain** (the bare invocation still works):

| Command | What it does |
|---------|--------------|
| `thoughtml guide [topic] [--full]` | this language, from the binary: a one-screen tour, one section, or `--full` |
| `thoughtml check <f> --json` | validate → diagnostics as JSON with a **stable code, line, and suggested fix** per issue. *This is your self-correction loop:* emit → `check --json` → apply the `help` fixes → repeat until clean. Add `--lint` for the `supports`-as-a-list smell (`TML501`). |
| `thoughtml fmt <f>` | rewrite in the one canonical style (`-w` in place, `--check` for CI); re-parses its own output and never changes the model |
| `thoughtml explain <f> <id>` | trace why a node has its confidence/status — evidence for/against, each edge's leverage, the conflict it's caught in |
| `thoughtml diff <a> <b>` | a **belief-level** diff: what flipped `in`/`out`, which confidences moved, which conflicts appeared/resolved |

Install with `cargo install thoughtml` (or `npm install -g thoughtml`).

**The diagnostic codes** are a stable contract, grouped `1xx` vocabulary, `2xx` references,
`3xx` graph coherence, `4xx` numbers, `5xx` lints:

| Code | Means | Fix |
|------|-------|-----|
| `TML101` | unknown focus kind | use a real kind (§5) or declare it in a `profile` |
| `TML102` | unknown relation | use a real relation (§6) or declare it in a `profile` |
| `TML103` | unknown posture | use one of the twelve (§7) |
| `TML104` | unknown field | use a known field (§16) or declare it in a `profile` |
| `TML201` | unresolved reference | an id in a link/stance/bundle doesn't exist — declare it or fix the typo |
| `TML202` | links may only connect foci/questions/links | you targeted a stance or scope |
| `TML301` | focus not connected to anything | link it in, nest it, or drop it — every node must earn its place |
| `TML302` | contradictory stances | one agent took clashing postures on one target (`accepts`+`rejects`) — reconcile or `revises` |
| `TML303` | cyclic dependency | a cycle in `causes`/`depends-on` — break it |
| `TML304` | revision asserted earlier than its target | check your `asserted-at` ordering |
| `TML305` | malformed decision subgraph | a `leads-to` self-loop, or an option missing from the EV ranking |
| `TML401` | number declares no basis | add `measured`/`estimated`/`assumed` (only under `--strict-provenance`) |
| `TML402` | weight/probability outside `0..1` | it was clamped — use a value in range |
| `TML501` | `supports` used as a list (lint) | if these are items not evidence, use `part-of` (§6) — fires at ≥4 supports with no counter-evidence |

`TML101`–`TML104` come with a nearest-spelling suggestion. (Note: the `definition-
divergence` audit conflict and the decision-EV warnings carry no TML code — they surface in
`--audit` / `--compute`, not as validation diagnostics.)

---

## 13. Reading a document back — the mirror is YOUR interface

You do **not** need to look at the rendered graph; the SVG viewer is for humans. Your view
is the **textual** output of `--compute` / `--audit`. Read these fields to understand a
document — yours or one handed to you. The mechanics are exact and worth knowing so you can
interpret the numbers:

- **`derived_confidence`** — belief propagated along `supports`/`opposes`/`undercuts`. Each
  node's value is `logistic(2.0 × Σ polarity·weight·believedness)` over its incoming
  evidence edges, where `logistic(x)=1/(1+e⁻ˣ)`, polarity is `+1` for `supports` / `−1` for
  `opposes`/`undercuts`, `weight` defaults to **0.5** if unstated, and a source's
  *believedness* is its own derived confidence (transitive), else its authored confidence,
  else `1.0`. No evidence → `0.5` (neutral). Rounded to 3 decimals. So a single strong
  support (`weight 0.85`, full-strength source) yields ≈0.85. **If a claim you'd expect to
  be shaky reads near-certain, suspect a list written with `supports`** (§6).
- **`argument_status`** — grounded labelling (Dung) over the attack graph. A node is `in`
  iff **every** attacker is `out`; `out` iff **some** attacker is `in`; otherwise
  `undecided` (e.g. a mutual attack). Attacks are `opposes` and `undercuts`; defense is
  just attacking an attacker. Only nodes touched by an attack get a status.
  (An `undercuts` edge whose target is a **link** doesn't rebut a node — it cuts that
  inference's weight by `1 − undercut_weight`, so premises flow through a weakened step.)
- **`leverage`** (sensitivity) — how load-bearing each piece of evidence is; what the
  conclusion actually hangs on.
- **decision EV** (`--compute`, over `leads-to`/`option-of`) — an option's expected value is
  `Σ probability·payoff` over its `leads-to` edges. **Payoff** is the outcome's
  `computed_quantity` (a formula) or authored `quantity`, in base units; all payoffs within
  one option must share a dimension. **Probability** is the edge's authored `probability`, or
  — if omitted — the outcome's own `derived_confidence` (belief becomes likelihood, once and
  visibly). Options are **ranked** high-to-low under their decision but **no winner is
  crowned** — it reports, you decide. (`ship-or-hold` is the full worked case, including a
  what-if that flips the ranking.)
- **`timeline`** — the ordered `events` array (by valid-time, `seq` tiebreak).
- **`conflict report`** (`--audit`) — **the headline.** Where structure disagrees with the
  author. Exactly two conflict types:
  - `confidence-vs-status` — a **stance's** confidence contradicts its target's grounded
    status. Two asymmetric cases: high confidence **≥ 0.66** in a claim the structure
    **defeats** (`out`) is an **error**; low confidence **≤ 0.34** in one that **survives**
    every attack (`in`) is a **warning**. Needs both an attack (`opposes`/`undercuts`)
    giving the target a status *and* an authored `confidence` on it. This is the flagship —
    `ship-the-hotfix`.
  - `definition-divergence` — one id defined two different ways (§8); a **warning**.

When you transform prose into ThoughtML, run `--audit` afterward and check the conflicts
are the *real* ones in the source — not artifacts of enumerations you wrote as evidence. A
clean, meaningful conflict report is the sign you modeled the reasoning faithfully.

---

## 14. Authoring checklist (the distilled rules)

1. **Only closed-set words.** Kinds (§5), relations (§6), postures (§7), fields (§16) are
   exhaustive. Never invent one — it warns (or reparses the line). When unsure, use the most
   literal; if a domain truly needs new words, declare a `profile`.
2. **Lists use `part-of`, not `supports`.** Evidence relations move confidence; reserve them
   for genuine evidence. This is the #1 way to corrupt the mirror.
3. **`candidate-for` for proposed answers; `answers` only for the resolved one.**
4. **`opposes` a claim, `undercuts` an inference** (target the link). `weight` for evidence,
   `probability` for `leads-to` only.
5. **Don't date to sort.** Time is optional; document order already orders. Date only when
   *when* matters.
6. **State a basis** (`measured`/`estimated`/`assumed`) on numbers you can; use `confidence
   ?` when you genuinely don't know.
7. **One id = one node**, and **every link/bundle endpoint must be a declared node** — a
   bundle references, it doesn't create. Define once in full, reference by id everywhere.
8. **Record dead ends, don't drop them** — `status abandoned`/`superseded` with a reason.
9. **Gate on strict-clean.** Iterate until `--strict` passes, then read `--audit` and confirm
   the conflicts are the real ones.
10. Prefer **typed headers** (`claim x`) and **bundles** (`part-of group` + members) — same
    model, far less boilerplate.

---

## 15. Gold examples, and the corpus (one worked instance of everything)

Two full strict-clean documents inline; then an index of all 20 corpus files, each a
canonical instance of one construct. To learn a feature, read the file named beside it.

**A. The flagship — clean in form, caught by the mirror (`ship-the-hotfix`):**

```thml
focus hotfix-is-safe
  kind claim
  The payments hotfix is safe to ship to production now.

focus suite-is-green
  kind observation
  The full unit and integration suite passed on the release branch.

focus canary-errored
  kind observation
  The 5% canary threw a spike of HTTP 500s on checkout within ten minutes.

link suite-is-green supports hotfix-is-safe
link canary-errored opposes hotfix-is-safe

oncall holds hotfix-is-safe
  confidence 0.9 assumed
  note Shipping — the suite is green and the release window closes at 17:00.
```

Zero errors, zero warnings — the *form* is perfect. But `--audit` reports a
`confidence-vs-status` **error**: `oncall` holds the claim at 0.90 while its own
`canary-errored` evidence defeats it (`argument_status: out`). The mirror shows the
conflict; it does not decide.

**B. Dateless analysis — declare nodes, then bundle. `part-of` (structure) never inflates,
`supports` (evidence) does; `candidate-for` proposes without resolving:**

```thml
claim eliminate-late-fees-was-key
  Removing late fees was the decisive early move.
observation customer-hated-late-fees
  Late fees were the top customer complaint.
observation subscription-model-proven
  Flat-rate rental had already shown demand.

# evidence -> supports (raises derived_confidence)
supports eliminate-late-fees-was-key
  customer-hated-late-fees   weight 0.9 estimated
  subscription-model-proven  weight 0.7 assumed

claim netflix-strengths
  Netflix's core strengths.
observation strong-global-brand
  Recognized worldwide.
observation large-subscriber-base
  Hundreds of millions of members.

# structure -> part-of (no confidence inflation on netflix-strengths)
part-of netflix-strengths
  strong-global-brand
  large-subscriber-base

question most-impactful-strategy
  Which strategy mattered most?
  expects claim

# proposed answers -> candidate-for (not the resolved `answers`)
candidate-for most-impactful-strategy
  eliminate-late-fees-was-key
  netflix-strengths
```

Under `--compute`: the `supports` bundle raises `eliminate-late-fees-was-key` to ≈0.96; the
`part-of` bundle gives `netflix-strengths` **no** derived confidence at all; the conflict
report is empty because nothing overstates. Swap the `part-of` for `supports` and
`netflix-strengths` would falsely read near-certain — the exact pollution to avoid.

**The corpus — concept → file** (all in `examples/`, all strict-clean):

*Start here (small, complete):*
- `triage-742` — the smallest full incident: `noticed`/`suspects`(edge + `as` alias)/`holds`, an open question, `until … answered` (→ `blocks`), dated replay, a confidence **range**.
- `weekend-plan` — the most pared-down decision: `decision`/`option`/`goal`, `option-of`, `enables`, `chooses`.
- `bad-oyster` — everyday causal reasoning: the `asks` posture, `suspects` + `causes`.

*The mirror (conflict report):*
- `ship-the-hotfix` — `confidence-vs-status` (example A above). The flagship.
- `merge-conflict-beliefs` — `definition-divergence`: two agents define one id two ways, both kept; mixes `stance`/`link` longhand with the readable surface.

*Argument structure (the attack graph):*
- `pr-feedback` — `undercuts` (attack an inference, with a `link alias:`) vs `opposes` (attack a claim), side by side.
- `hiring-panel` — several agents, shared evidence, different `confidence`; `because` ties each stance to what moved it.
- `replication-study` — weighed evidence with `measured`/`estimated` bases on links; a critique that `undercuts` the counter-evidence.
- `differential-dx` — competing `hypothesis`es as `candidate-for` a question, then one `answers` it once labs return.
- `moderation-decision` — an AI call emitted for a human to audit: signals for/against, an `action`, an inspectable `confidence`.

*Structure vs. evidence:*
- `roadmap-priorities` — `part-of` grouping (not `supports`) + candidate options nested under a question (a thought-tree).
- `control-library` — a standalone, importable library: a `part-of` collection of `claim`s, `enables`, a budget `quantity`.

*Time, lifecycle, and change:*
- `launch-readiness` — a call `revises`d twice; `status superseded`, `valid-during`, `--as-of` replay.
- `choose-datastore` — an ADR: an option `abandoned` + `rejects` (kept, not deleted), a question moved to `settled`, `until … answered`.
- `prod-outage` — a postmortem as an acyclic `causes`/`enables`/`prevents` graph; nested scopes with their own timestamps; `-by` attribution (`noticed-by`, `undercut-by`); an `action` that recovers it.
- `assistant-memory` — an AI across turns: `infers` (sources wired explicitly), `kind memory`, `remembers` with a `source`, a `revises` posture, `confidence ?`.

*The compute layer (`--compute`):*
- `cloud-bill` — a cost model that computes itself: `= formula` lines over `quantity`s with real **unit checking** (USD/hour × hour, ÷ users).
- `ship-or-hold` — the capstone: formula payoffs, `leads-to` probabilities (one omitted → falls back to derived confidence), expected-value ranking, and a what-if that flips the order.

*Extensibility:*
- `threat-model` — a `profile` (`appsec`) adding domain kinds/relations/fields/postures, then a full security review in that dialect.
- `compliance-rollout` — `import control-library as baseline`, referencing `baseline.<id>`, checked as a project.

---

## 16. Quick reference (everything, at a glance)

**Header keywords (7):** `scope` `question` `focus` `link` `stance` `profile` `import`
(+ sugar: typed-focus `<kind> <id>`, bundle `<relation> <target>`, action `<agent> <posture> …`).

**Kinds (10):** `observation` `claim` `hypothesis` `option` `decision` `outcome` `goal`
`assumption` `memory` `action`.

**Relations (14):** evidence → `supports` `opposes` `undercuts`; structural/causal →
`causes` `enables` `prevents` `depends-on` `blocks` `answers` `revises`; decision →
`leads-to` `option-of`; membership → `part-of` `candidate-for`.

**Postures (12):** `noticed` `considers` `suspects` `infers` `asks` `holds` `chooses`
`rejects` `revises` `remembers` `doubts` `accepts`.

**Fields:** `note` `kind` `quantity` `about` `weight` `probability` `confidence` `because`
`answers` `expects` `status` `until` `source` `observed-at` `asserted-at` `valid-during`
`noted-by` `noticed-by` `suspected-by` `chosen-by` `blocked-by` `undercut-by`
(+ profile-only: `kinds` `relations` `fields` `postures`). Plus `= <expr>` formula lines.

**Number bases (3):** `measured` `estimated` `assumed`.  **Status (4):** `open` `settled`
`superseded` `abandoned`.  **Confidence:** scalar, `low..high` range, or `?`.

**Compute (`--compute`):** `derived_confidence = logistic(2.0 · Σ polarity·weight·believedness)`,
default `weight` 0.5, no-evidence 0.5; `argument_status` = grounded (`in` iff all attackers
`out`); decision EV = `Σ prob·payoff`, prob falls back to derived confidence.

**Audit (`--audit`):** `confidence-vs-status` (≥0.66 vs `out` = error; ≤0.34 vs `in` =
warning) and `definition-divergence`.

**Diagnostic codes:** `1xx` vocabulary · `2xx` references · `3xx` graph coherence · `4xx`
numbers · `5xx` lints (`TML501` = `supports`-as-a-list).

**The two rules that matter most:** lists are `part-of`, not `supports`; gate on
strict-clean, then read `--audit`.