part of: the tour · chapter 11 of 12
The machine-readable layer
Every page has a JSON twin, a Markdown twin and a feed — and the honesty rules travel with them.
One query layer, three renderers
Each page’s data is assembled once, in one module, and rendered three ways: as HTML, as Markdown, and as JSON. No renderer runs its own query.
Why It is what makes the twins trustworthy. If the JSON were assembled separately it would drift — and drift silently, since nobody diffs an API against a web page. Sharing the assembly makes disagreement impossible rather than unlikely.
Connects It is also why the machine layer was not extra work bolted on at the end: the third renderer is a template over an object that already existed.
Markdown twins
Add .md to any content page’s URL and you get the same content as Markdown, with absolute links and the split rendered as a table whose last row, in bold, is the unknown share.
Why It is the format for reading a page somewhere else — in a notebook, a prompt, a document — without scraping HTML and without losing the structure that makes the page mean what it means.
Connects This tour has one too: the whole of it, in one file.
See it live A Question as Markdown · The whole tour as Markdown
The JSON API
A read-only, versioned JSON API over the same modules — 11 endpoints: /api/v1/question/{id8} · /api/v1/claim/{id8} · /api/v1/entity/{id8} · /api/v1/event/{id8} · /api/v1/source/{id8} · /api/v1/story/{id8} · /api/v1/world/{id8} · /api/v1/changes · /api/v1/search · /api/v1/suggest · /api/v1/peek/{id8}.
Why The site’s own features consume it — the type-ahead and the link previews call the public endpoints, not private ones. A machine layer the site does not itself depend on is a machine layer that quietly rots.
Connects It returns the awkward parts too: the residual, the excluded branches, the refused belief terms, the unresolved identity doubt.
See it live The API reference · The OpenAPI description
The three parameters work everywhere
Lens, as-of and world selection are query parameters on pages, twins and API endpoints alike.
Why A consumer that can only fetch the default view can only ever report the default view. Making the alternatives addressable everywhere is what lets someone else check the site under a lens it did not choose.
Connects The same three parameters are documented on the page, in the OpenAPI file, and in llms.txt.
See it live The API reference
Structured data, and the answer that is never accepted
Every page carries schema.org markup — Claim, Person, Organization, Place, Event, Question. A Question publishes its branches as suggested answers and never sets an accepted answer.
Why That field is how a search engine turns a page into a fact in a box. There is no accepted answer here, so the field stays empty — permanently, and by rule rather than by oversight.
Connects It is checked mechanically: a Question emitting an accepted answer fails the build.
See it live A page with structured data
The rating that explains itself
Each enumerated answer also publishes a structured review whose explanation carries the honesty: “Belief share under Evidence-weighted (log-odds@1); unknown residual 67% — computed from evidence, not an editorial verdict. Leading is not proven, and repetition never moves this number.”
Why A bare rating value is precisely how this site would be misrepresented — a number lifted into someone else’s interface as a verdict. The explanation travels with it, and a review missing one fails the build rather than warning.
Connects It is the same four rules the quoting guidance states for language models.
See it live A Question’s markup
Feeds — and following one Question
Two Atom feeds: everything that changed, and newly promoted Questions. The change feed can be scoped to a single Question or story. Its subtitle restates the honesty rule, so a subscriber who never visits the site still receives it.
Why Feeds are how you follow something without an account, an email address or a notification permission. Scoping means you can follow one open question rather than a whole site.
Connects The entries use the same sentences as the change log, with categories for the change kind and its group.
See it live What changed · New questions
Instructions for machines that quote
A file at /llms.txt stating what the site is, the URL grammar, the twins, the API — and four rules in the imperative: quote the residual with the share, name the lens, leading is not proven, repetition is not evidence.
Why A large share of this site’s future readers will meet it through a summariser. Writing the quoting rules down, addressed to that reader, is the only leverage a publisher has over how it gets paraphrased.
Connects The fourth rule ends by saying it plainly: restatements move no number here, and they should move none in your summary either.
See it live llms.txt
Freshness that means something
The sitemap’s last-modified date for a page is the time of the most recent entry in the change log touching it — not a file timestamp.
Why It makes “updated” a claim about the model rather than about the deployment. A page whose date moved is a page where something in the record actually changed.
Connects It is verified against the database directly: the newest change-log timestamp and the sitemap entry must be equal.
See it live The sitemap
The crawler file tells the truth about the gate
Right now the pages carry a no-index instruction and the robots file disallows crawling, because this site has not opened publicly yet. When it does, both flip together.
Why A robots file that invites crawlers to pages marked no-index is a site whose two statements about itself disagree — and if two of them can disagree, none of them is trustworthy. They are driven by the same switch.
Connects That switch also closes the write surfaces, so a deployment that declares itself public cannot be sitting over an open submission form.
See it live robots.txt
Three descriptions that cannot disagree
The API reference page, the OpenAPI file and the machine-instruction file are generated from one list of endpoints.
Why Three hand-written descriptions of one API are three documents that will disagree by next month, and the disagreement will be discovered by whoever trusted the wrong one.
Connects Same discipline as one query layer and three renderers, applied to documentation.
See it live The API reference · llms.txt