nishi code wiki / research / the standard

The brief standard: one document, three audiences

Published 1 Aug 2026 · a specification that is also an example of itself

What this solves

The trap is writing the same fact twice. The obvious way to serve humans, AI agents and machines is three renditions of one brief — readable prose, a summary for models, a JSON sidecar. That is sprawl, and worse, the three drift apart the first time a number is corrected in one of them. This standard has one authored artifact and derives everything else from it, so drift is not a discipline problem, it is structurally impossible.

Three findings decided the design, and each removed work rather than adding it [C1] [C2] [C3]. The short version: the machine channel that matters is the visible HTML, not a parallel data format; the one negotiation worth serving is text/markdown; and two widely-recommended artifacts are dead weight we should not build.

The rule: authored once, derived twice

Exactly one artifact is hand-written: the HTML below. Two views are generated from it at publish time by the tool, never by hand — the embedded JSON data island, extracted from the claims table, and a markdown rendition served on Accept: text/markdown. A publish gate proves the derived views equal the extraction; if a human has edited the derived block, the publish refuses.

The placement rule, which is the whole standard in one sentence: a number, URL, date or label appears exactly once — in its claim row. Prose never restates a value; it cites the claim ID. Prose carries narrative and reasoning; the claims table carries every fact; the gaps section carries every declared unknown; lineage lives in the header nav and the JSON-LD.

Layer	Serves	Authored or derived
Semantic HTML: one `h1`, unskipped headings, `<time datetime>`, `<th scope>`	all three — this is the load-bearing machine layer	authored
Prose sections	humans, and AI reading visible text	authored
Claims table with `data-claim` rows	all three — the single source of truth for facts	authored
Declared gaps	all three — and it is what creates nodes on the family tree	authored
`<script type="application/json">` data island	mechanistic consumers	derived from the claims table
JSON-LD `TechArticle` in head	search and AI crawlers	derived from header + lineage
Markdown rendition on `Accept: text/markdown`	agents, at a fraction of the tokens	derived at publish

Claims

ID	Claim	Value	Label	Source	Source date
C1	llms.txt files are overwhelmingly never fetched by AI crawlers, and Google states it has no ranking effect — so we do not build it	97% never fetched	DEPRECATED	organikpi.com · corroborated by Google statements	2026-06
C2	Edge content negotiation converting HTML to markdown on `Accept: text/markdown` shipped as a production feature; the token saving on a representative page is roughly fivefold	16,180 → 3,150 tokens	SHIPPING	Cloudflare changelog	2026-02-12
C3	Third-party LLMs frequently ignore or fail to parse JSON-LD during runtime retrieval and read the visible text instead — so semantic HTML, not structured data, is the primary machine channel	qualitative, observational	RESEARCH	optimizegeo.ai	2026
C4	Google removed ClaimReview rich-result support, ending Search Console reporting and API support — do not build claim markup expecting a consumer	no surviving verified consumer	DEPRECATED	Poynter/IFCN	2025-06
C5	MCP tools declare an `outputSchema` and return conforming `structuredContent`, which is the mechanism for a machine-checkable publish receipt	spec-mandated	SHIPPING	MCP specification	2025-06-18
C6	MCP tool annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) are the vocabulary clients use for auto-approval; a publish tool is not destructive when it preserves a previous version	4 hints	SHIPPING	MCP blog	2026-03-16

The skeleton

Copy this shape. The data- attributes are what make the derivation mechanical — without them the extractor would have to parse prose, which is exactly the fragility this design removes.

<article data-brief-id="B-2026-041" data-schema="nishi-brief/1">
  <header>
    <h1>Title</h1>                              <!-- the ONLY h1 -->
    <p>Published <time datetime="2026-08-01">1 Aug 2026</time></p>
    <nav aria-label="Lineage">
      <a href="/code/parent" data-rel="parent">parent</a>
      <a href="/code/child"  data-rel="child">child</a>
    </nav>
  </header>

  <section id="summary">  <!-- prose cites facts by ID: ... beats the baseline [C1] -->
  <section id="analysis"> <!-- reasoning, method, caveats. NEVER restates a number -->

  <section id="claims">   <!-- SINGLE SOURCE OF TRUTH -->
    <tr id="c1" data-claim data-value="9.9" data-unit="x" data-label="SHIPPING">
      <td>C1</td><td>statement</td><td>9.9 x</td><td>SHIPPING</td>
      <td><a href="https://...">source</a></td>
      <td><time datetime="2026-08-01">2026-08-01</time></td>
    </tr>

  <section id="gaps">     <!-- <li data-gap="g1"> ... each becomes a node on the family tree -->
</article>

<!-- DERIVED at publish. Hand-editing this block is a publish-time gate failure. -->
<script type="application/json" id="brief-data">
{"schema":"nishi-brief/1","id":"B-2026-041",
 "lineage":{"parent":"/code/parent","children":["/code/child"]},
 "claims":[{"id":"c1","statement":"...","value":9.9,"unit":"x","label":"SHIPPING",
            "source_url":"https://...","source_date":"2026-08-01"}],
 "gaps":[{"id":"g1","text":"..."}]}
</script>

The publish call

One tool call does the whole thing and refuses loudly rather than half-succeeding. It is annotated destructiveHint:false because the previous version is preserved, and idempotentHint:true because republishing identical input is a verified no-op [C6]. The receipt is structuredContent, so a caller can check the publish landed without trusting a status string [C5].

Step	What it does	How it fails
1	Validate — one h1; every `data-claim` row has a statement, a value with units (or an explicit qualitative marker), a label from the fixed set, a source href and a source date; lineage hrefs resolve in the registry	refuses, naming the offending row
2	Derive — regenerate the data island and the JSON-LD from the claims table, render the markdown view, hash the final HTML	refuses if an existing data island disagrees with the extraction, because that means a human edited a derived view
3	Upsert registry — one row keyed by path, additive, prior row superseded and never deleted	unchanged input is a no-op, not a duplicate
4	Publish atomically, preserving the previous version	rolls back
5	Regenerate every index from the registry — the index page and the family-tree map — so a hand edit cannot survive the next publish	drift becomes structurally impossible rather than a discipline
6	Verify over the real edge — fetch the URL and compare the hash of the served bytes; fetch the negotiated JSON and markdown; confirm the index lists the document	restores the previous version, regenerates indexes from the prior registry state, and reports `rolled_back:true`

The same shape extends to sites and apps: the input becomes a manifest of files, step 4 becomes stage-the-tree-then-swap-a-pointer, and step 6 becomes a smoke set that fetches every registered route and hashes each against the manifest.

Declared gaps

None of this is built yet. This page is the specification and its own worked example; the derivation and the publish tool described in the previous section do not exist. Today briefs are hand-written and written straight into the docroot.
The data island and JSON-LD on this page were written by hand, which is precisely what the standard forbids. They are correct as of publication and will drift the moment a claim changes. That is the argument for building step 2, stated against myself.
Whether any major AI retrieval system consumes schema.org lineage fields at runtime in 2026 is UNVERIFIED in both directions. The JSON-LD block is justified only because deriving it costs nothing once step 2 exists.
Our edge's Vary handling has not been tested for correctly cached negotiated variants. Step 6's negotiated fetches must be proven live before anything depends on them.
The existing briefs predate this standard and do not carry claim IDs or data attributes. Retrofitting them is unscheduled work, and until it happens the library is two formats.