THE AI FILES / SPEC
Spec v2 · contract updated 2026-10-25 · machine-readable aif-spec.json
What a deep guide is, how research stays separate from look, how a finished guide ships as a zip you can open offline, and how The AI Files grades quality from A to F. Written for readers and for anyone — human or bot — building or reviewing a guide.
A deep guide must work when someone downloads the folder as a zip, unzips it, and opens index.html in a browser with no site server and no CDN. Core reading — story, explorer, people, timeline, critical path, theories, claims, READING edition — uses only relative paths to files inside that folder.
files/<topic-id>/
├── index.html interactive guide (open this)
├── READING.html long-read, no JavaScript required
├── README.txt how to open; what is local vs outbound
├── AUDIT.md optional research notes (not visitor UI)
├── CHANGELOG.txt optional edition history
├── css/ fonts.css, style.css (local)
├── fonts/ typefaces shipped in the zip
├── images/ free-licensed / PD photos for this guide
├── vendor/ local JS libraries the guide needs
└── js/
├── early.js tiny boot helpers
├── data.js window.GUIDE — generated; do not hand-edit
└── app.js shared chrome / UI (template)
The same shape is used by Watergate, JFK, Biden Family Laptop, and other full guides. Site-wide ads, forum chrome, or collection headers may call parent ../../assets/ when the guide lives under the live site; a portable zip still keeps fonts, vendor, images, CSS, and GUIDE data inside the guide folder so offline reading does not depend on a CDN for those assets.
js/*) are relative paths inside the guide folder.https://cdn… URLs for fonts, CSS, or chapter images are a defect: they break zip-local viewing.README.txt tells a stranger: open index.html for the guide; open READING.html for the plain edition; fonts/code/images are local; the network is only for external source and video links; picture credits live in the guide. Watergate’s README is the model.
Complete long-read of the same story for print, archive, and no-JavaScript reading. Chapters, critical-path prose, and key lists stay in sync with the interactive guide. A static timeline graph may appear when the template supports it.
Research lives in a topic data folder (for example data/<topic-id>/): topic.json, story.md, entries.json, people.json, timeline.json, sources.json, images.json, claims.json, theories.json, memory.json, and related files, plus an images/ directory of source files.
tools/render_guide.py data/<topic> <out_dir> builds the self-contained package and writes js/data.js as window.GUIDE=…. The file header says to edit the data folder, not data.js by hand. Restyle = edit shared templates under tools/guide/ and re-render. New facts = edit one record and re-render. Do not bury unique research only inside a hand-edited index.html.
Data (research) — story chapters, dated entries, people, timeline, critical path, rival theories, memory phases, rated claims, sources, media, open questions, and image metadata — lives in the topic data set and appears in the browser as window.GUIDE.
Look (chrome) — layout, navigation, card chrome, shared CSS, fonts, and interaction code — comes from the shared template (js/app.js, css/, vendor). Many guides share the same chrome; each guide’s unique research stays in its data.
Open Watergate (live) or the same folder from a zip. You should find:
index.html — story in chapters, explorer of entries, people, timeline, theories, claims board, sources.READING.html — plain long-read; no JavaScript needed.README.txt — open instructions; local fonts/code/images; network only for outbound links.js/data.js — generated window.GUIDE from data/watergate/ via render_guide.py.js/app.js + js/early.js — shared UI.css/, fonts/, images/, vendor/ — all local.JFK and Biden Family Laptop use the same package shape. Use Watergate as the bar when checking whether another bot’s build is zip-local and data-driven.
A deep guide is a single scrollable documentary site for one claim-spine topic. Chapters are photo-and-prose sections on the page — not separate chapter URLs you click into. The READING edition repeats the same story as one long page without depending on interactive widgets.
The opening states the topic, the date span, and what kind of file this is. AI authorship is disclosed. The lede tells the reader what question the guide is organized around — not a cable-news tease and not a builder checklist.
On-page sections (#story / .chapter) alternate image and prose. Each chapter is real narrative, typically several paragraphs. Chapter body median should clear about 250 words for principal guides. Short captions next to a picture are not chapters. Do not invent a click-through chapter gallery unless the shared template already uses one.
An interactive graph sits above the ordinary dated timeline list. It helps readers see clusters and jumps; it does not replace the list. The READING edition can carry a static graph when the template supports it.
Dated events and named people open into detail cards with sources. People pages and portraits follow free-license rules; wrong-person lookalikes and decorative stand-ins for named subjects are defects.
The load-bearing chain any serious reading must handle. Cards should grow and explain, in plain language: what the step is; where it fits in the narrative; why it is critical (what collapses if it falls); what rival theories must still account for; sources; and then/now memory when older beliefs were overturned. A skinny checklist of labels is not enough.
Major rival paths are stated at their strongest and mapped to the critical path — what each path accepts, removes, or must show is wrong. Rival ≠ endorsement. Slogans are not a path.
How accepted public facts moved: films, viral claims, older textbooks, later document releases. Fiction is labeled fiction. “Everyone always knew” is usually false; show the turn.
Rate the claim that was asked. Do not swap in a harder neighboring claim to dodge a well-supported answer. Indictment is not guilt. Adjacency is not authorship. Alleged talking points from an accused party are claims to test, not proof that settles the file.
Primary and contemporaneous sources lead the spine. Established secondary sources — including established neutral and right-leaning outlets when they carry the record — belong in the mix; leaving them out to keep a lean is a demerit. When a relevant hearing clip, primary interview, or official video exists for a spine event, include a working link. Mentioning an event or source without linking or including it is a demerit.
Images need credits and free-license or public-domain status. Strip needless personal metadata from files. Typographic-only covers are not a substitute when a documentary image exists.
Collection hubs (people or organizations with many scandals) are gateways: full guides first, then biography, then case nest gateways, then an optional claims archive. They are not a mega fact-check board as the front door.
Nest gateways under a collection are maintained record doors. They point at a full guide when one exists. They are not the product and should not be called “shorts.”
Homepage cards are for top-level files and collections. Nested hubChild full guides stay off the homepage grid so the cabinet does not duplicate every nest. Cards are clean documentary photo tiles — not blank site-made drawer plates, and not fake folder chrome.
Hubs that combine child timelines should present a real combined timeline graph and copy written for visitors — never a literal paste of an internal instruction.
Imagery is part of ship, not optional polish later. Before calling a guide done:
object-fit: cover with a face-biased object-position when the subject is a person. Faces must be readable. No cut-off chin or forehead as the default crop. No busy crowd where the named subject is a speck.Guides may show a discreet grade badge that links here. Grades are editorial quality marks for this site’s bar — not academic accreditation, not a truth ministry, and not a popularity score. Unlabeled pages usually mean “not yet audited” or “nest still converting,” not a secret F.
This Spec page’s own grade (as an AI build contract) is seeded in aif-grades.json under spec. After the zip-local / data-vs-look expand, the honest target is about B+: good enough for another bot to follow with Watergate open beside it; not an A until builders routinely ship from Spec alone without tribal knowledge.
Full structure and dense craft. Story chapters with median prose at or above the ~250-word bar; distinct documentary images correctly cropped; working menus and footers; zip-local core assets; primaries on the claim spine; balanced established sources; critical path cards filled (why-critical, deps, sources); rivals and memory present; no chat-feedback copy on the page.
Solid and usable. Structure is real and honest; package shape is correct. Minor gaps allowed — one thinner chapter, a missing clip, light source skew — without collapsing into blurbs or broken chrome.
Structure present, craft incomplete. Lean prose, incomplete critical path, uneven sources, CDN-dependent core assets, or important spine events mentioned without inclusion. Readable as a start, not ship-as-flagship.
Looks big, reads empty. Kilobyte padding with chapter blurbs (often under ~100 words), lazy reused faces, broken menus, missing sources for mentioned events, agent-instruction labels used as titles, or treating accused/alleged talking points as proof that settles the issue.
Broken, empty, or actively misleading. Includes chat-paste masquerading as documentary content, inventing documents, or chrome that does not work.
Plus/minus marks (A−, B+, …) may appear when a guide sits between letters. Flagship topics such as JFK or Epstein are expected near the A range only when they still clear the full bar on a fresh audit — age alone does not freeze an A.
Automatic demerits — keep this checklist next to every ship:
object-fit: cover + face-biased object-position; no cut-off chin/forehead; no busy crowd where the subject is a speck).This page is Spec v2 (field specVersion: "2"). Bump the Spec version when the contract changes — new required package rules, epistemology bars, or scan signals — not for typos. Record the bump on this page and in /assets/aif-spec.json (and the specVersion field on aif-grades.json).
Each published deep guide should declare which Spec version it was built or audited against, in forms that are easy to scan sitewide:
<meta name="aif-spec-version" content="2"> and <body data-aif-spec="2">aif-spec-decl)window.GUIDE.specVersion in js/data.js when the guide uses GUIDE/assets/aif-guide-versions.json maps path → specVersion (+ optional guideEdition)specVersion on each entry in aif-grades.jsonGuides with no declaration are unknown / behind — not silently current. Do not stamp old guides as current Spec without an audit.
Seeded at Spec v2 ship (examples): Watergate, JFK, Biden Family Laptop. Use Watergate as the package reference when auditing others up to v2.
A bot (or a person) can scan the site and list every deep guide whose declared Spec version is missing or less than the current Spec. Those need updates. Plain method:
/assets/aif-spec.json → specVersion (or this page’s badge)./assets/aif-guide-versions.json → guides. Any published deep guide path under /files/ that is unlisted, or listed with a lower specVersion, is behind.rg -n 'aif-spec-version|data-aif-spec' site/files/*/index.html (and nest deeps). Missing meta / body attribute on a full guide = behind until seeded.rg -n 'GUIDE\\.specVersion|specVersion' site/files/*/js/data.js.Example one-liner after cloning the site tree: compare every /files/*/index.html that looks like a deep guide against aif-guide-versions.json and current aif-spec.json; print path + declared version + “behind” when declared < current or absent.
Prompt to copy: follow this Spec (v2) as the contract, and study the Watergate package at /files/watergate/ (zip shape, README.txt, js/data.js generated from data/watergate/, local fonts/images/vendor). Measure chapter prose before calling a guide done. Prefer one deep guide finished to the bar over many thin shells. When you ship, declare Spec v2 on the guide (meta + data-aif-spec + aif-guide-versions.json). Scan for behind guides as in Versions & scan.
Seed or update the grade in /assets/aif-grades.json when you ship; do not mark everything A. Nest gateways that are not yet rebuilt may stay unlabeled.
Open site work — redo, polish, “update the website” — goes through the Google Form action Queue a website update (see Queue). Spec grades are the build bar. Chat is not the backlog. One worker at a time unless the site owner explicitly asks for parallel.
Updated 2026-10-25 · Spec v2 · self-grade B+ as an AI contract · aif-spec.json · aif-guide-versions.json · Grade badge data: /assets/aif-grades.json