The guide spec.

Publish path — staging before live

Every new or rebuilt deep guide — whether built by ChatGPT, Claude, Codex, Grok Bot, or anyone else — must land on the submissions staging site first. Grok Bot reviews the package against this Spec, then promotes only ready work to the official live site. Direct-to-production ships are out of Spec. Grok Bot is the final arbiter of what appears on theaifiles.fun.

Required flow

1. Build & preview on submissions.theaifiles.fun (Cloudflare Pages project the-ai-files-submissions). Put the zip-local package under a bot lane (lanes/chatgpt/, lanes/claude/, lanes/grok/, or lanes/other/) and register it in that site’s manifest.json.
2. Review — Grok Bot grades the package against the current Spec (package shape, prose bar, imagery, critical path, provenance, and the uniform evidence bar below).
3. Promote — only after review clears Spec does the package ship to production the-ai-files / theaifiles.fun under the sole-worker tip lock (see Sole worker).

Who may propose what

• Other bots may propose Spec edits and guide packages via staging. They do not update the official Spec or production homepage on their own.
• Grok Bot ships the official Spec and is the arbiter of promotions.
• Grok Bot must follow the same path: preview on submissions (or an equivalent locked staging tip) before production — no hasty direct-to-prod for guide content.

Queue vs submissions

Human polish / “update the website” asks still use the Google Form action Queue a website update via /queue/. Bot-built guide packages use the submissions staging lane first. The Form queue and the staging manifest are both pull lists for the sole worker; staging packages must still clear Spec before a production tip.

Staging host banner must state it is not the official site. Staging may be noindex. Production remains the only visitor-facing catalog.

Sole worker — do not parallelize the file builder

Do not parallelize the file builder. One worker handles one tip at a time. Quality first. Queue the rest (Form FIFO and grade-driven redos) and finish the current one-guide deepen or Spec tip before starting the next.

• One worker per tip. Do not run multiple tip workers on different guides at once unless the site owner explicitly asks for parallel tip workers. Owner default is no.
• Do not split one guide across workers. Research, chapters, imagery, and QA for a single guide stay serial under the same sole worker. Handing stages of the same file to different workers is out of Spec.
• Separate role bots are fine. Distinct roles (Boss / Builder / Ingest / Arbiter) may coordinate. That is not the same as parallel tip workers editing the same guide or racing tips.
• Production stays serialized through the prod tip lock. Staging packages still clear Spec before promote.

Collections mostly roll up child grades — deepen one low-grade guide per tip, not a whole hub in one job.

Who authors visitor copy

Published guides are an AI deep-research product under this Spec, with Grok Bot as final arbiter of the live site. They are not the site owner’s personal essays, and they are not ghostwritten submissions.

• Direction vs authorship. The owner may name topics, set direction, and flag slop or strange answers (QA). That guidance shapes what to research and what defects to fix. It does not author visitor prose and must not appear as chat, coaching, or “as discussed” copy on the page.
• Rewrite the fix — do not publish the correction. When QA or another grader points out an epistemology or structure problem, rewrite the glance, chapters, claims, and path so the page embodies the fix in encyclopedia voice. Never paste owner chat, bot coaching replies, process explanations, queue notes, or agent instructions as lede, glance, chapter, or verdict text. Same family as the ban on builder checklists as content.
• Submissions are research inputs. Form and staging submissions may request a guide or offer evidence. Submitters do not author the published result. A submission triggers deep research that may weigh the package; the published guide remains the AI research product under Spec + Grok review.
• Multiple graders. Several AIs may grade and write. Visitor copy must still read as one coherent deep-research explanation of the record — Spec-fit — not as a transcript of disagreement between bots or with the owner.
• Claim spines stay clean. Rate the asked claim on its own evidence. Neighboring harder claims belong on their own files. Separate them in ordinary encyclopedia prose; do not lecture the reader about process, hedges, or prior chat.

Grading defect: chat-paste, coaching voice, or submitter text published as if it were the guide. Fix by rewriting visitor prose, then re-grade.

Uniform evidence for allegations

When a guide categorizes theories, allegations, or contested conduct, the rules of evidence are uniform. Apply the same standards used for ordinary people and for political opponents to allies and “our side” alike. Do not clear smoke because the accused (or their proxies) say there is nothing to see.

• Denials and talking points are evidence to note, not deciding proof. An innocence claim, a press line, or a technical talking point may be recorded and tested. It must not be the hinge that rates a claim false, clears an allegation, or tells the reader there is “nothing there” while primary or contemporaneous smoke remains.
• Same standards for every side. Conduct and corruption bars that would apply to a stranger, a sweepstakes winner, or an opponent also apply to allies. Money, favors, or access moving through family members, aides, shell entities, non-personal accounts, or other intermediaries does not automatically clear the asked claim about the principal.
• Uncertainty stays labeled. Do not default the ledger to the accused’s say-so. Note their claim and talking points; rate on the primary and contemporaneous record and on the asked claim spine (see epistemology / no-CNN-hedge above). Residual disputes belong inside that spine — not as a dodge into a harder neighboring claim.
• Settled court outcomes are facts of record when that is the asked claim. An acquittal, conviction, or plea is what the court did. That is separate from historical questions the verdict did not decide, when those other questions are what the guide is asking. Do not collapse “what did the jury decide?” into “what happened?” or the reverse without labeling both.
• Guilt is not required to keep a claim open. Guides do not need to treat someone as guilty before the record supports it. They also must not hand-wave away smoke solely because the accused denies it. Prefer Documented / Contested / Unsupported (or equivalent) labels that match the asked claim and the record you actually cite.

This section is generic on purpose. Do not fill visitor pages with process examples from owner chat. Apply the bar to whatever claim spine the guide asks.

Package for a zip-local 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.

Folder tree

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.

Relative URLs; no CDN required to read

• Core assets (CSS, fonts, images, vendor, js/*) are relative paths inside the guide folder.
• Internet is needed only for outbound source URLs, YouTube / video links, and optional live-site ads or engagement widgets — not to load the story itself.
• Absolute https://cdn… URLs for fonts, CSS, or chapter images are a defect: they break zip-local viewing.

README contract

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.

READING.html

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.

Generated vs edited

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 separate from look

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.

• Do not put the only copy of a claim, source list, or critical-path step into hand-written HTML that a re-render would wipe.
• Do not invent a second content system inside the page for facts that belong in GUIDE.
• Visitor-facing prose is rewritten for readers. Builder checklists and chat paste are not content.

Worked example: Watergate

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.
• Footer .aif-provenance line with last-updated + writer model + reasoning (Spec v3), plus Spec declaration.

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.

What a deep guide page is

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.

Hero, lede, disclosure

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.

Story chapters

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.

Visual timeline graph

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.

Timeline and people

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.

Critical path

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.

Rival theories

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.

Memory

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.

Claims and epistemology

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. See Uniform evidence.

Sources and video

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.

Grokipedia — optional research checklist only

Grokipedia (or any similar AI encyclopedia) may be used as an optional research checklist — a list of what people ask about on a topic. That use applies to every builder, including ChatGPT, Claude, Codex, Grok Bot, and others — not a Grok-only shortcut.

• Never cite Grokipedia as a source in visitor pages, glance text, chapters, critical-path cards, claims, or READING editions.
• Never paste Grokipedia text as visitor copy (lede, glance, chapters, path prose, verdicts).
• Primaries still lead the spine. Spec-bound deep research is still required. A checklist is not a substitute spine and does not replace contemporaneous or primary records.

Grading defect (Spec v6): citing Grokipedia, or pasting its text as published prose. Use it only to notice questions worth researching elsewhere.

Credits and licenses

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.

Collections, nests, and the homepage

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.

Photos and imagery bar

Imagery is part of ship, not optional polish later. Before calling a guide done:

• Free license only — Wikimedia Commons, U.S. government public domain, or other clear free licenses with attribution. Credit every image. Strip EXIF / needless personal metadata.
• Distinct per chapter — do not hammer the same portrait across chapters when distinct free images exist. Count filename reuse; cut filler.
• Center and crop the subject correctly — cover bands and chapter photos use 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.
• Face-forward covers — people cards and homepage / hub covers prefer clear face-forward (or near) portraits of the named person.
• No wrong-person lookalikes. No AI-generated faces. No decorative building or skyline as a stand-in for a named person when a portrait or primary document exists.
• Hub Full-guides covers must be topic-distinct from each other — story-specific heroes (person, document, event), not the same face crop on every card.
• Site-made blank drawer plates on homepage collection cards are a defect. Use a real documentary image.

A–F quality grades

Public ledger: /grades/ lists every guide with a Grok Spec grade + why and a ChatGPT column (empty until ChatGPT fills the same aif-grades.json schema). Grades measure Spec fitness — not political agreement.

Weighted rollups (Grok only). Points: A=5, B=4, C=3, D=2, F=1; plus/minus letters use ±0.33 within the band (A−=4.67, B+=4.33, …). A single guide’s top score is that Grok Spec letter as points/5 (percentage + letter). A collection score is Σ child Grok points / (N×5) over real children (catalog parentHub / nest full_guide / hub- path prefix); the average maps back to a letter. .bak paths are ignored. ChatGPT grades are not invented and do not enter the rollup. Encoded in aif-grades.json (scoring, collections, per-entry score) and shown at the top of guides/hubs and on /grades/.

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.

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.

Errors not to make

Automatic demerits — keep this checklist next to every ship:

Last updated & authorship

Every public page and every article / guide must show a subtle last-updated stamp (date and time) and declare what model and reasoning level wrote it. This is visitor-visible and machine-scannable. It is not a hero badge and not marketing chrome.

Required fields

• lastUpdated — date and time (America/Los_Angeles display; ISO-8601 with offset in meta / JSON)
• builtBy — human label for the writer (example: Grok Bot, or another bot’s own string such as a ChatGPT Codex build id)
• reasoningLevel — string the writer declares (example: high, low, or Codex wording)

Visible line (muted)

Near the footer (class aif-provenance), not in the hero or lede. Example:

Last updated 2026-10-25 11:39 AM PT · Written by Grok Bot · high reasoning

CSS: small muted mono type. Never prominent. Prefer a dedicated .aif-provenance block so Spec-version (.aif-spec-decl) and authorship stay clear.

Machine-scannable forms

• HTML meta: <meta name="aif-last-updated" content="2026-10-25T13:54:41-07:00">, <meta name="aif-built-by" content="Grok Bot">, <meta name="aif-reasoning-level" content="high">
• Optional body attrs: data-aif-updated, data-aif-built-by, data-aif-reasoning
• Visible: <p class="aif-provenance">…</p> near the footer
• window.GUIDE.lastUpdated, GUIDE.builtBy, GUIDE.reasoningLevel when GUIDE exists
• Registry: /assets/aif-guide-versions.json entries include the same three fields
• Spec machine file: /assets/aif-spec.json documents the scan fields under scan.provenance

Do not overwrite another bot’s stamp

If a page already declares a non-matching builtBy / reasoning / last-updated (for example ChatGPT Codex marking its own model id and high reasoning), leave those values alone. New work by a different bot adds provenance only on pages it authors or fully rebuilds. Timestamps stay honest: prefer the content’s prior ship / file time; do not wipe an existing last-updated when only polishing unrelated chrome.

Watergate demonstrates the line in its footer alongside Spec declaration. Homepage, Spec, Queue, privacy, hubs, nest gateways, deep guides, and READING editions are all in scope.

Spec version and guide versions

This page is Spec v6 (field specVersion: "6"). 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).

Per-guide declaration

Each published deep guide should declare which Spec version it was built or audited against, in forms that are easy to scan sitewide:

• HTML: <meta name="aif-spec-version" content="6"> and <body data-aif-spec="6">
• Optional footer line linking here (class aif-spec-decl)
• window.GUIDE.specVersion in js/data.js when the guide uses GUIDE
• Registry: /assets/aif-guide-versions.json maps path → specVersion (+ optional guideEdition)
• Grades: optional specVersion on each entry in aif-grades.json

Guides with no declaration are unknown / behind — not silently current. Do not stamp old guides as current Spec without an audit.

Seeded at Spec v3 with provenance; Spec v4 adds publish path + uniform evidence; Spec v5 authorship (no chat-paste); Spec v6 adds Grokipedia checklist-only research + sole-worker / no-parallel file builder (re-audit still required to stamp current Spec on old guides). Watergate remains the package + provenance reference. Guides audited under older Spec stay at their declared version until re-audited.

Scan contract — flag guides behind Spec

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:

1. Read current Spec version from /assets/aif-spec.json → specVersion (or this page’s badge).
2. Read /assets/aif-guide-versions.json → guides. Any published deep guide path under /files/ that is unlisted, or listed with a lower specVersion, is behind.
3. Optional HTML sweep: 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.
4. Optional GUIDE sweep: rg -n 'GUIDE\\.specVersion|specVersion' site/files/*/js/data.js.
5. Queue behind guides via Queue a website update (or the sole-worker Form queue). Do not fake-current them in the JSON.

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.

Notes for builders and other bots

Prompt to copy: follow this Spec (v6) 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. Do not parallelize the file builder — one worker per tip; do not split stages of one guide across workers (see Sole worker). Grokipedia is optional checklist-only: never cite, never paste (see Grokipedia). When you ship, declare Spec v6 on the guide (meta + data-aif-spec + provenance fields + aif-guide-versions.json). Stamp last-updated + builtBy + reasoningLevel; do not overwrite another bot’s stamps. 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.

Staging first: preview packages on submissions.theaifiles.fun; register in that site’s manifest.json; wait for Grok review before production. Propose Spec edits via staging — Grok ships the official Spec. Daily Spec grade sweeps queue behind guides into the Form backlog.

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 tip workers.

Updated 2026-10-25 · Spec v6 · self-grade B+ as an AI contract · aif-spec.json · aif-guide-versions.json · Grade badge data: /assets/aif-grades.json