# The draft format — MD + YAML frontmatter > **Status: DRAFT · v0.1.** A convention, not a schema: the required set is minimal, everything else is free. Provided AS IS. One file = one node created (Appoint), one edge declared (Trace), or one recognition proposed (Nod). Frontmatter carries what is structured and queryable; the markdown body carries the context a cold reader needs. ## Design goals 1. **Cold-start legibility as a design goal.** A draft should carry enough context to be read without the original chat. Actual comprehension depends on the reader, model, available evidence and the quality of the draft; the format does not guarantee it. 2. **Generatable by light models.** Flat fields, few required keys, nothing computed. 3. **Deterministic retrieval.** Agents query frontmatter by exact match; semantic search over bodies is optional and disposable. 4. **Storage ≠ search.** Files are canonical; any index is derived and disposable. 5. **No cryptography.** Drafts are unsigned by definition. Attestation is defined by The Legible Protocol; a signed record *references* a draft as evidence — the draft itself never mutates into one. ## What each primitive is | Primitive | Graph operation | Declares | Test | |---|---|---|---| | **Appoint** | create node | "I formulated this / I take self-attributed responsibility for it." | Authorship of a formulation — not a promise to finish, not a priority claim, not a task. | | **Trace** | create edge | "This relied on that." | A dependency claim between the work and something prior — a draft, a record, a source, a named conversation. Specific enough that the party named could contradict it. | | **Nod** | attest on node | Consequence received from someone's contribution, after it materialized. | Written by whoever **received** the consequence, about a contribution that generated it — including the sources your own work relied on, once the circuit closes for you. Never about your own work. Value may be zero; zero is data, not absence. | **Not "evaluate".** A Nod is not a rating, a star, or a judgement of the work's quality — it attests what happened to whoever used it. The distinction is the protocol's (spec §2.4) and it holds here: the moment a Nod starts reading as a score, the layer has rebuilt the ranking the grammar exists to do without. **Nods are proposals here.** An unsigned Nod is not a signed protocol declaration. Informal recognition can matter to its readers without formalization. Draft one when consequence has genuinely materialized: as your own reminder to sign, or as a prepared file for a counterparty's signature. Never manufacture one to complete the set: a graph of only Appoints and Traces is complete, and in solo work that is the normal state for a long time. **If something fits none of the three** — a raw fact, a bookmark, a to-do with no formulation behind it — it doesn't need to be a draft. Ordinary notes can stay ordinary notes. ## Frontmatter ### Core fields (all types) | Field | Req. | Description | |---|---|---| | `genealogy` | yes | format version — `"0.1"` | | `type` | yes | `appoint` \| `trace` \| `nod` | | `id` | yes | `--` — a handle for linking, matching the filename | | `created` | yes | ISO 8601 — when the **draft** was written. Always the real, present date. | | `occurred` | no | when the **fact** happened, if earlier — retroactive drafts are legitimate; the two fields keep them honest | | `author` | yes | stable handle — a person's name/pseudonym, or an agent's identifier | | `author_kind` | no | `human` \| `agent` (defaults to `human`); an agent's draft is the agent's, never attributed to a person | | `agent_run` | no | agent mode: stable id grouping one autonomous execution, for batch review | | `title` | yes | one line, ≤ 80 chars, identifies the draft standalone | | `tags` | no | flat list, lowercase kebab-case | ### Per type **Appoint** — `formulation` (yes: one sentence, a real claim someone could evaluate — not "working on X") · `domain` (no). **Trace** — `depends_on` (yes: list of checkable references — draft ids, record ids, named documents, conversations described by role and date; people only where public or consenting — see *Third parties* below) · `statement` (yes: what was produced and *how* it relied on each item) · `appoint_ref` (no: the Appoint this grew from — never repeated in `depends_on`; one edge, declared once). **Nod** — `target_ref` (yes: the contribution being recognized — a draft/record id, or the contribution described; a person by name only where public or consenting, and in the protocol layer identity is a key, not a name — see *Third parties*) · `value` (yes: `0` unless something else actually materialized — the trigger is the consequence, never an amount, and zero is the ordinary case, data rather than absence. Form-agnostic here — the protocol layer distinguishes reputational / monetary / non-monetary at signing, not in the draft) · `consequence` (yes: one sentence on what materialized) · `contribution_ref` (no). ## Body The cold-start test: a model with only this file understands what was formulated / depended on / recognized, and why it matters. ```markdown ## Context Why this draft exists. Assume the reader knows nothing. ## Statement Expands the frontmatter one-liner into prose. Must not contradict it. ## Evidence & references Concrete pointers, briefly described — omit if empty. ## Open threads What's unresolved; the natural handoff for the next session. ``` ## Rules - **Never backdate `created`.** The real date goes in `created`; the earlier fact date, if any, in `occurred`. - **One edge, declared once.** Nothing in `appoint_ref`/`contribution_ref` reappears in `depends_on`; within `depends_on`, reference the nearest link and let the chain carry the rest — duplicated edges corrupt traversal. - **Specific or nothing.** "The 2024 Exampleville public-records response" preserves the chain; "based on research" breaks it. - **Record the path, not just the outcome.** An abandoned hypothesis is still an Appoint; a source evaluated and rejected belongs in a Trace's `statement`; a change of direction is a Trace naming what caused it — the highest-value drafts, and the ones most often skipped. - ISO 8601 dates; block-style lists; no anchors, aliases, or multi-line scalars in frontmatter; omit empty optional fields. ## Third parties A draft is unsigned and usually private, and it is still a file about other people — read by models, pasted into sessions, sometimes referenced by hash from a signed record. The protocol's drafting guard applies here, for the same reasons (protocol repository, `skills/SKILL.md` §8): - **Describe people by role and date, not by name and setting.** `"beekeeper interview, 2026-07-26"` — not `"Interview with , beekeeper, recorded call"`. - **No third-party personal data** — contacts, employer, health, location, anything that identifies someone who did not choose to be in your notes. - **Another person's words enter a draft two ways:** with their consent, or as a short attributed citation — whose limits are set by the law that applies to you, not by this rule. Prefer your own formulation and a pointer where appropriate; paraphrase does not automatically remove rights or access restrictions. - **When in doubt, split:** the draft carries your own formulation; the sensitive part stays in the file it came from, named but not copied. What this costs, stated honestly: a reader who is not you can no longer identify the source from the file alone. That is the intent — the draft is your memory, not a dossier on someone else, and `depends_on` only has to be checkable **by you** to keep the chain walkable. Where a dependency genuinely has to be checkable by a third party — a published paper, a public dataset, an organization, a person who agreed to be named — name it. Public availability and consent are relevant context, not blanket permission for every reuse or processing destination. ## Layout ``` genealogy/ ├── drafts/ # this format — unsigned; preserve shared versions and their origin └── records/ # imported signed records (read-only copies — .appoint/.trace/.nod) ``` Drafts link to records by the record's hash `id`; records reference drafts as evidence (`{type: document, ref, content-hash}` — protocol spec §3.1). ## Example This is a hypothetical teaching example. Exampleville is a fictional municipality; the interview, municipal records, dates, and policy outcome below are illustrative assumptions, not evidence about an actual event. ```markdown --- genealogy: "0.1" type: trace id: trace-20260726-beekeeper-interview created: 2026-07-26T16:40:00-03:00 author: john title: Drafted the article's case section using the beekeeper interview appoint_ref: appoint-20260725-urban-beekeeping-outline depends_on: - "beekeeper interview, 2026-07-26, recorded call" - "City of Exampleville sting-incident report, 2024-2026, public records request" statement: The case section was drafted relying on the beekeeper's account of gentler bee strains and on Exampleville's public data showing no rise in stings after its ban was lifted. --- ## Context Continuation of the urban beekeeping article (see appoint_ref). John is a freelance writer pitching a piece on urban beekeeping policy. ## Statement The case section now exists, built on two sources: a beekeeper's first-hand account of modern strain temperament, and Exampleville's public records showing stings did not rise after the 2024 lift. ## Open threads - Still need data from the other two cities named in the Appoint. ``` Note what the interview entry does **not** carry: the interviewee's name. John knows who she is — the entry is checkable by him, which is all the chain needs — and she did not choose to be in his notes. The public records request, by contrast, names its source in full: it is a public document. When the article is published and paid, John has received a consequence. He can prepare a new Nod recognizing her contribution, review its exact content and sign it. The interview entry remains a separate draft; it is not converted into a signed record. **What identifies her there is her key, not her name.** The specification recommends minimizing personal data (§14); the preparation guides apply a stricter publication-safe practice. A DID identifies a key, not verified civil identity. John's Nod points at the contribution's record or a permitted external reference; a non-monetary Nod requires a record ID. The `statement` describes the contribution rather than disclosing private details. If she is nowhere in the graph, the Nod names the contribution as an external reference and reaching her is ordinary communication. Recognition flows *up* the genealogy, from whoever received value to what made it possible. That signature lives in the protocol layer; here, the Nod draft is the prepared proposal.