Ontology redesign proposalsCopy wiki link

This note began as a record of a 2026-07-23 design session about the wiki’s note-type ontology, when nothing in it was adopted. A 2026-07-25 session then settled the concept and entity boundary, which shipped to AGENTS.md, and decided to adopt all three remaining proposals in sequence. The note is now an adoption plan with its reasoning attached rather than a set of open proposals. The project is young and its instructions are themselves experimental, so the proposals ranged over changes that would otherwise be treated as settled.

Status of each proposal:

The layering was implemented and reverted within a day. What remains is the agent default, then the skill.

What prompted the sessionCopy wiki link

The immediate question was whether concept and synthesis are clearly distinct. The operative distinction, previously stated only in the audit-structure skill, is the warranty: a concept note defines a thing (“X is such-and-such”), while a synthesis note asserts a proposition, argues it from its sources, and reaches a conclusion the vault has a stake in. The distinction is functional, not topical, so titles cannot settle it: Invoking the Fifth Amendment can itself be used as evidence is a thesis-shaped title doing concept work (a building block for Why you shouldn’t talk to the police), while EU private communications law is a thing-shaped title doing synthesis work (a stake-bearing conclusion for the venture notes). Law notes are the genuine gray zone: compare Encryption key disclosure compulsion (concept) with EU private communications law (synthesis).

The name synthesis survives scrutiny as least-bad, but it names a process that happens at every level — Data as coercive power synthesizes three sources into a definition — when the real type marker is the output: a warranted, stake-bearing conclusion. The current synthesis inventory falls into five clusters, which matters for the deferred sub-typing question below:

The table doubles as the de facto candidate sub-type vocabulary, so it will anchor the deferred sub-typing decision whether or not it is adopted deliberately.

Adopted: demand-driven extractionCopy wiki link

The first proposal changes how concepts and entities come to exist. Sources are treated as foreign transactions; concepts and entities are the vault’s ledger, holding its own checked interpretation of what the sources say; syntheses are reports drawn from the ledger. The dependency graph runs from sources to syntheses, but the writing workflow runs in reverse: an agent starts from the synthesis it wants to write, decomposes the argument into premises, and serves each premise in one of three ways — link an existing concept or entity, create or extend one from the sources, or cite a source directly as a recorded exception.

flowchart TD
  source@{ shape: cyl, label: "source" }
  concept@{ shape: rounded, label: "concept" }
  entity@{ shape: hex, label: "entity" }
  synthesis@{ shape: subproc, label: "synthesis" }

  source --> concept
  source --> entity
  concept --> synthesis
  entity --> synthesis
  concept <-. creation demand .-> synthesis
  entity <-. creation demand .-> synthesis

  class source source
  class concept concept
  class entity entity
  class synthesis synthesis

Solid edges carry evidence downward; dashed edges carry the creation demand that flows back up from the synthesis to the concept and entity notes it needs.

Concept creation becomes demand-driven: the synthesis’s need is the warrant for a concept’s existence, so no page is speculative, and redlinks remain the queue for ideas not yet demanded. Direct citation is not forbidden; the escape valve keeps a needed synthesis from waiting on perfect ledger hygiene. Centralization happens through procedure rather than prohibition.

Three drafting rules carry the model’s risks:

• Extraction reads the source. A concept is written from the evidence, not lifted from the citing synthesis’s sentence.
• Concepts state claims at source-warranted strength, no stronger and no silently narrower, because downstream syntheses will rely on them without re-reading.
• Concepts are written at the idea’s natural scope, not the first customer’s argument scope. The named failure mode is consumer capture: a ledger entry sliced to fit one synthesis.

The case for centralization is the single interpretation site. Today two syntheses can cite the same source differently, and the divergence is invisible until someone compares them; a review pass must re-verify each claim against originals that may be dead URLs or expensive PDFs and EPUBs. A concept note fails visibly instead: one checked site, one fix that propagates, and the existing per-note review machinery (just review, review_after) doubles as claim review for everything downstream. The divergence problem is understated for this vault: the existing syntheses mostly carry note-level provenance only, a frontmatter sources list with few or no claim-level citations in the prose, so the claim-to-source mapping that review presumes largely does not exist yet, and extraction is also how that mapping gets created once instead of being reconstructed at every review. The pattern already operates below the idea level: source notes do it for artifacts, and entity notes such as Vastaamo data breach do it for evidentiary episodes. The objection that extraction creates stubs was largely withdrawn in the session: moving ideas from foreign sources into the vault’s own ontology is the point, and the residual rule is grounding at extraction, not page size or backlink counts. The main reservation is that a hard gate version of this model was rejected: requiring syntheses to cite only concepts and entities would conflate intermediates (primary legal materials belong in source notes, not forced concepts), pay extraction costs speculatively, and distance synthesis writers from primary contact with their evidence.

Shipping it as the agent defaultCopy wiki link

The 2026-07-25 session adopted this proposal as default agent behavior rather than an occasional pass, and widened it from synthesis writing to research generally. The reasoning is that an agent doing research already holds a goal, is already reading sources against it, and is therefore the best-positioned reader to ask which premises the vault should hold instead of restate. Nothing about that question requires a separate maintenance session.

The scope is what the current task needs, not every idea a source touches. Demand-driven means exactly that: the work in hand is the warrant, and an agent that extracts speculatively has misread the model as a completeness obligation.

This is guidance for AGENTS.md, not a procedure skill. It should be short enough to sit in the research workflow, carry the three drafting rules above, and show a worked example or two, since the failure it prevents — writing a concept sliced to one argument’s needs — is easier to recognize than to define. Direct citation remains available as the recorded exception it already was.

Adopted: a distill-syntheses skillCopy wiki link

The second proposal handles the notes written before the agent default existed, as an occasional maintenance skill rather than a rule, working title distill-syntheses.

The 2026-07-25 session removed a mode from it. The skill was to run both a decompose mode at writing time and a ratchet mode over legacy notes, sharing one procedure. Decompose mode is now the agent default above, so the skill keeps only the retroactive job. The two are not one procedure at two moments. An agent writing a synthesis holds the argument already and can name its premises from working memory; recovering the premises of a note written months ago by a different session is a different and harder task, which is why one is guidance and the other is a skill.

The pass is scoped to a cluster, not a note. Processing one synthesis alone, a premise appears once and looks unique to it, which is how a concept gets written to the shape of its first customer. Processing a related group, the same premise surfaces repeatedly in different wording, and the repetition is the evidence both that it deserves a note and what its natural scope is. just clusters already partitions the vault into 30 link neighborhoods and reports their bridge links, so the scoping step has tooling.

The ratchet pass, per cluster:

1. Pick a cluster with just clusters and inventory the direct evidence across all its notes: claim-level citations, inline source links, and frontmatter sources.
2. Find the repetitions before reading for judgment. A source cited from one note for one claim is usually fine where it is. A source cited from four notes is either four claims or one claim restated four times, and the second is a concept whose call sites reveal its scope. Let the repetition nominate candidates so the reading pass starts from evidence rather than from impressions.
3. Score each candidate: reuse across notes, load-bearingness for the conclusions, independent nameability, and interpretive weight at the point of use.
4. Classify every candidate as extract now, redlink, or leave alone with a recorded reason, written into the session’s Log.md entry so the decision survives the session. Leaving in place is a first-class outcome; that is what “within reason” means.
5. Extract: create the concept or entity note carrying the descriptive content and its citations, then rewrite each citing passage minimally to link it. The conclusions stay in the syntheses; no verdicts are laundered into building blocks.
6. Verify that every previously supported sentence still has support afterward, either its own citation or a link whose target carries the claim-level citation.

Because claim-level citations are largely absent from the current syntheses, the inventory step will mostly find frontmatter sources entries with no sentence-level mapping, and the final verification step is vacuous where support was never recorded. On such notes the pass is a claim-mapping pass first and an extraction pass second, and its cost estimate should assume re-reading the sources to attribute claims, not just moving existing citations. Cross-note repetition may also be the only available signal for where the premises are, since a note with no sentence-level citations does not mark its own load-bearing claims.

Auditing direct citations is most of the work. The agent default permits citing a source directly, so those citations accumulate by design, and the skill’s recurring question is whether a given one stands for something that should have been a concept or an entity instead. That question is answered across a cluster, not inside one note.

Guardrails named in the session: do not extract primary sources that are the synthesis’s subject (the fact-check pattern in Why you shouldn’t talk to the police); do not extract one-off cases, figures, or statutes used once; prefer a source note over a concept when the honest intermediate is a primary legal document; create nothing that cannot already state what the subject is and why it matters. The stated goal is not a count of moved citations — that metric rewards over-extraction — but reusable, load-bearing extraction with recorded leave-alone decisions. State the goal as removing demonstrated duplication: premises the vault can be shown to restate across notes. That is checkable against the cluster inventory. A goal phrased as a well-formed ontology is not, and any extraction can be rationalized against it, which matters because extracting always feels like progress and leaving alone never does.

A related caution applies to scope. When a cluster pass finds five notes leaning on one premise, writing the concept that serves all five is better than writing the one that serves the first, but it is still a union of consumers. The call sites reveal the idea’s scope; they do not define it.

The 2026-07-25 session dropped the earlier plan to gate the skill behind a separate hand-run pilot. The procedure would be run on a worked cluster while drafting the skill in any case, so the gate mostly named a step that happens anyway. Write the skill by running it on the evidence-law cluster (Why you shouldn’t talk to the police, Witness reports are not ground truth, Coercive interrogation and false confessions, Invoking the Fifth Amendment can itself be used as evidence, plus the case entities Da Costa-fallet and Kevinfallet), encoding the decisions observed there rather than assumed ones, so the skill ships having already processed one cluster with real leave-alone decisions among its examples. What the dropped gate was protecting against still stands: do not write the procedure abstractly and then point it at every synthesis in the vault. That run doubles as a type-warranty retyping audit of the law-note boundary population, which is cheap while the vault is small.

Withdrawn: the kind and type layeringCopy wiki link

The third proposal restructures the ontology’s vocabulary from one flat field into two layers plus tags. The trigger was the entity inventory: entity already absorbs persons, organizations, and products alongside events (Vastaamo data breach), court cases (Da Costa-fallet, Kevinfallet), statutes (UK Online Safety Act), and regulatory actions, and after the 2026-07-25 sweep it absorbs published standards and protocols too. Flat new types for each were rejected: they all make the same warranty (“this note accurately describes a named, individuated thing”), a type per class multiplies boundaries and renders the graph legend illegible, and it would set a precedent for splitting synthesis into its five clusters as flat types.

The proposed scheme:

The current type field would be renamed kind in one isolated mechanical commit (frontmatter, renderer, lint, queries, template, tests, Obsidian graph groups), which is fail-fast under lint and the cheapest now that it will ever be. The commit must also sweep the instruction surfaces: AGENTS.md, the skills under .agents/skills/, and agent memory files reference type= queries and type: frontmatter, and a stale reference there fails silently — a skill running just query "type=question" would return nothing rather than an error — instead of failing under lint. The word type then returns as the subtype field. The naming attaches each word at its natural level (“what kind of note? an entity; what type of entity? a statute”) and matches the type-theory ordering of values, types, and kinds. A compound value such as entity/statute was rejected because exact-match queries on type=entity would silently stop matching statutes; a separate field works with the existing generic query (just query "kind=entity type=statute" already functions because queries match arbitrary frontmatter fields) and migrates softly because lint currently ignores unknown fields.

The proposed entity type vocabulary is person, organization, product (absorbing services and software), standard (published specifications such as ActivityPub and Messaging Layer Security), event (breaches, cases, enforcement actions), and statute. The standard value was added on 2026-07-25, when the ownership sweep described below moved nineteen specifications, protocols, networks, and vendor features out of concept. The original vocabulary folded protocols into product, which was drafted from the entity inventory as it then stood; that inventory held no protocols, because they were all mistyped as concepts. A published specification and a shipping product differ in authorship and in revision cadence, so they are worth separating. Vendor features such as Memory Integrity Enforcement remain product: Apple ships MIE, no body publishes it. statute needs one decision before the vocabulary ships: UK Online Safety Act is a statute in the strict sense, but the vault’s legal corpus is dense in EU regulations and directives such as the General Data Protection Regulation, so either the value widens to legal-instrument or statute is adopted as a loose term for any enacted legal text. Type would drive review-cadence defaults (events low, products high, statutes amendment-tracked) while review_after stays free to override per note. The zero-cost alternative is kind-as-tags (just query "kind=entity tags=statute" works today), rejected because lint cannot enforce that every entity carries exactly one type, and type tags would pollute the topical tag graph.

Deferred or rejected sub-decisions: synthesis types (thesis, assessment, and the other clusters) are deferred until the first cluster run produces evidence; a data kind (“this note states a measured quantity with its operationalization, population, and provenance, checked against the source”) is pre-committed for creation only if that run shows quantity notes straining concept; a quote type is rejected, since block quotes and source notes already carry exact-wording material.

Settled: the concept and entity boundaryCopy wiki link

Unlike the proposals above, this one was adopted on 2026-07-25 and is now stated in AGENTS.md. It is recorded here because it changes the entity type vocabulary the layering proposal depends on.

The concept definition listed “a mechanism, a doctrine, a framework, or a technical standard”, and the last clause was the defect. A standard is not a reusable idea. It is a specific document a body publishes, versions, and can revise, which is the entity warranty exactly. The clause invited agents to pattern-match a description of a note’s contents instead of asking who owns its subject, and it produced a vault that typed Matrix as an entity and XMPP as a concept with nothing distinguishing them.

The replacement test is ownership, not abstraction and not tangibility: does a specific party control what this is and what it becomes? The reusable idea is the category a standard implements. Federated microblogging is a concept; ActivityPub, AT Protocol, and Nostr are three named entities implementing it.

Three sessions typed the hardware-security pair Titan M secure element and Memory Integrity Enforcement and produced three answers, which is what identified the clause as actively misleading rather than merely underspecified. Both misreadings judged the prose rather than the subject. The first mistook emphasis for ontology: both notes are mechanism-heavy with cross-vendor comparison tables, which feels concept-shaped, but an entity note about a technical product is supposed to explain its mechanism. The second mistook tangibility for individuation, holding that MIE is a design deployed across a product line rather than a discrete object. That test would also disqualify Apple Private Cloud Compute and Samsung Knox, which the vault already types as entities. A third confusion appeared and was rejected: that being argued from makes a note a concept. Entity notes are load-bearing too.

The sweep retyped nineteen notes to entity: the protocols and standards ActivityPub, AT Protocol, Messaging Layer Security, JMAP, XMPP, Nostr, Tox, Secure Scuttlebutt, Marmot Protocol, and Android Package; the vendor features Memory Integrity Enforcement, Apple Advanced Data Protection, and Google client-side encryption; and the networks and currencies Bitcoin, Ethereum, Monero, Zcash, Solana, and Lightning Network.

Two candidates were examined and left as concepts.

Hardware security keys was titled “FIDO security keys”, which ran three things together: the FIDO2 and WebAuthn specifications, which the FIDO Alliance and the W3C publish and version; the FIDO Alliance itself; and the device category any vendor can build. The note defines the third. It opens on what a security key is and does, then gives threat-model and purchasing guidance, and never describes the specification’s version or governing body. Counting settled it: the body said “FIDO” exactly once, in the definitional sentence, and never mentioned WebAuthn, CTAP, or passkeys at all. The specification was in the title and nowhere else, so the note was renamed on 2026-07-25 and its opening now names the standards it implements as redlinks. Yubico already carries the products. The case generalizes: a vendor or body name in a title does not settle the type, because what the note defines does.

Splitting out FIDO2 or a FIDO Alliance entity was considered and deferred. All seven inbound links want the device category and its deployment story, so a specification note would have had no caller. The trigger to write one is a question the generic description cannot answer, such as FIDO2 and U2F compatibility across product lines — which the venture notes already gesture at, since Yubico records that its Security Key line is not interchangeable with every YubiKey.

synthesis was considered for the same note and rejected. Its deployment guidance and its “Catalog role” section sound stake-bearing, but the section reports judgments made elsewhere — Privacy gear catalog rates the product and Swedish and EU privacy suppliers tracks the supplier path — so the note is the building block those argue from. It asserts no proposition of its own. It does carry a mild scope smear worth watching: a definition of the authentication approach sits alongside commercial guidance for the shop venture. If the venture material keeps accumulating, move it into the catalog notes rather than retyping the definition.

PGP and OpenPGP should probably become two entity notes. Its own opening separates them — PGP is Phil Zimmermann’s 1991 software and OpenPGP is the IETF format derived from it, most recently RFC 9580 — so one handle covers a product lineage and a published standard. The split is content work rather than a retype: seven notes link the combined handle, and the failure-modes section critiques both at once. It stays a concept until then, which is defensible while the note’s main work is defining the encryption approach across implementations.

The sweep leaves a gap worth filling. The protocol notes carried the vault’s only account of the categories they implement, so federated microblogging and memory tagging now have no note defining them. Creating those category concepts is follow-on work, not a precondition for the retype.

Adoption sequenceCopy wiki link

The four steps run in this order. The rename leads because it is mechanical, fails fast under lint, and only grows more expensive as the vault grows.

• Add event as a ninth type, shipped 2026-07-25. Fourteen notes moved out of entity: nine breaches, three criminal cases, the Grindr data-sharing enforcement record, and the Mullvad donation controversy. See the settled section below.
• Abandon the layering itself, 2026-07-25. The field was renamed to kind, subtype vocabularies shipped for entity and event, and all of it was reverted within the day. The field is type again and there is no subtype. See the settled section below.
• Add the demand-driven extraction default to AGENTS.md, 2026-07-26. It sits in the research workflow as “Extract what the task needs”, carries the three drafting rules, and works Android app distribution trust models as the example: a comparison resting on two premises that became Android Package and Source-to-binary correspondence rather than paragraphs restating each. The building-block shapes that would have been a concept subtype vocabulary appear there as a prompt instead of a field, since the value was always the noticing rather than the recording. The graph pass in the finishing checklist now also looks for premises the session itself restated.
• Write distill-syntheses by running it on the evidence-law cluster, encoding observed decisions.

Settled: the event typeCopy wiki link

Adopted 2026-07-25 and stated in AGENTS.md. The layering proposal had assumed events were entities carrying a subtype, on the reasoning that both make one warranty: this note accurately describes a named, individuated thing. That reasoning was wrong about half its subject.

Entities and events divide on how their subject exists in time. An entity is wholly itself at any moment and changes by participating in things. An event is only ever partly present, because it is the change. The warranties differ accordingly: an entity note claims an identity, while an event note claims narrative fidelity — an accurate account of what unfolded, when, and per whom. That is a type-level difference, which is the bar this note sets for adding one.

Two false tests were discarded on the way. The first was cultural naming: Kevinfallet and Vastaamo data breach have names the world fixed, and Mullvad donation controversy has one the wiki wrote, but all three are episodes. The second was member count: enforcement was proposed as a subtype and dissolved when its two members turned out unalike.

The vocabulary is deliberately plain. BFO and DOLCE call this the continuant and occurrent divide, and CIDOC CRM separates intentional activity (E7) from mere occurrence (E5), which is the distinction that settles whether a planned festival and an unplanned controversy belong together. Those standards exist for machine interoperability between institutions; this vocabulary exists to tell an agent at a glance what a note promises. The import is the test, not the terminology.

Statutes stayed entities. UK Online Safety Act tracks a document that persists and gets amended, and Australian under-16 social media ban opens on an enactment but spends fifty-three of its sixty-one body lines on standing obligations. The vault’s six court judgments stayed source notes, since each describes a saved artifact rather than a thing in the world. That is the boundary between source and a subject note, and it now has a stated test.

Settled: the layering was wrongCopy wiki link

The third proposal is withdrawn. It shipped on 2026-07-25 and was reverted the same day, so the field is type again and no subtype exists. The reasoning is worth keeping, because the proposal was plausible enough to implement twice.

The layering assumed kind and type were two levels of one hierarchy: what kind of note? an entity; what type of entity? a statute. They are not. kind asked what warranty a note makes to a reader, and the subtype asked what sort of thing the subject is. Those are unrelated questions in adjacent frontmatter lines. organization is not a narrower warranty than entity; it is the same warranty about a different subject. The Haskell ordering that motivated the rename — kinds classify types — applies to a hierarchy the fields did not form.

Four candidate vocabularies were tried and withdrawn, and all four failed one test: their members did not behave differently.

The entity vocabulary is the instructive failure, because it looked strongest. product held 51 of 117 notes, which is a default rather than a classification. person was recoverable from the wrongful-conviction tag. work and judgment had one member and none. Only standard and legislation changed anything, and what they changed was review cadence, which review_after states per note more accurately than a class does for all its members.

A subtype has to earn itself by changing what happens to the notes carrying it: different review cadence, different structure, different handling by some tool or procedure. A vocabulary that only records what a subject is duplicates tags without their flexibility, and one that records what a note is about duplicates them exactly.

What replaced it is a table of examples in AGENTS.md. The original discomfort was real: entity covers people, agencies, protocols, statutes, vendor features, and a documentary series, and an agent meeting that breadth cold will hesitate. Listing the range with worked examples resolves the hesitation without a field to maintain. entity is broad by design, and the answer to a broad category is a clear definition rather than a taxonomy inside it.

Open decisionsCopy wiki link

• synthesis keep-or-rename. The session’s recommendation is to keep and define it; the rename era is the only cheap moment for a rename.
• Synthesis types: deferred until the first cluster run produces evidence.
• data type: confirm the pre-commitment to create it if the first cluster run shows quantity notes straining concept.
• AGENTS.md rewrite scope: a new ontology section only, or a whole-document drift pass.
• Category concepts vacated by the 2026-07-25 sweep: create notes for federated microblogging and memory tagging, or record that the entity notes cover them adequately.
• Split PGP and OpenPGP into a PGP product-lineage entity and an OpenPGP standard entity, redistributing the seven inbound links and the shared failure-modes section.
• Venture content in Hardware security keys: move the “Catalog role” section into the notes that own those judgments, or accept the mixed scope.

{"width": 320, "height": 320, "data": {"values": [{"model": "Claude Opus 5", "label": "Claude Opus 5 (63%)", "lines": 510, "share": 0.6288532675709001}, {"model": "Kimi K3", "label": "Kimi K3 (31%)", "lines": 255, "share": 0.31442663378545005}, {"model": "Claude Fable 5", "label": "Claude Fable 5 (6%)", "lines": 46, "share": 0.05672009864364982}]}, "mark": {"type": "arc"}, "encoding": {"theta": {"field": "lines", "type": "quantitative"}, "color": {"field": "label", "type": "nominal", "legend": {"title": null, "orient": "right"}}, "tooltip": [{"field": "model", "type": "nominal"}, {"field": "lines", "type": "quantitative"}, {"field": "share", "type": "quantitative", "format": ".1%"}], "order": {"field": "lines", "type": "quantitative", "sort": "descending"}}}