docs(guides): add the large-file decomposition campaign canon

[andrexibiza]

Related #54962 #55138 #77702 #77759 #77807 #77819 #78791

What

The canonical record of the gateway/run.py large-file decomposition (issue #54962) now lives in the repository the god file used to be.

The page

website/docs/guides/i-killed-the-godfile.md — the full 16,900-word essay I KILLED THE GODFILE! (by Hermes, @NousResearch, and Axl Ibiza, MBA), preceded by a campaign index with every artifact:

• Tracking issues: Extract Gateway Platform Routing from gateway/run.py #54962, Extract Gateway Platform Routing from gateway/run.py #55138, docs: graph-adjudicated documentation conformance closes the documentation issue class #77807
• The 24 campaign pull requests (refactor(gateway): extract media/event helpers from run.py (slice 7 of #54962) #77702–refactor(gateway): extract GatewayPlatformMixin from run.py (slice 25 of #54962) #77759), all linked
• The conformance mechanism (tests/conformance/test_docs_graph_conformance.py) and spec
• The llms-full.txt permanent baseline (72,470 lines)
• The graph-gated-engineering doctrine skill
• The conformance PR test(conformance): graph-adjudicated documentation conformance + llms-full.txt baseline #77819
• The published X Article link

The essay itself carries the receipts chapter and the token ledger: 2.69 billion tokens, 296 sessions, $5.391464 — the whole campaign itemized, hashed, and public.

Why

The essay is the method applied to itself — model, agree, gate, slice, verify. The decomposition is the largest single-file refactor in this repository's history, and its canonical account belongs here: in the docs, with the links, next to the code it describes. The documentation conformance gate adjudicates the page's links against the real tree, so the canon cannot rot.

Files

• website/docs/guides/i-killed-the-godfile.md (new, 768 lines)
• website/sidebars.ts (+1 line)

Part of #54962.

Part of #54962

Part of #11349
Part of #78207

[spfcraze]

This was generated by AI during triage.

Summary:
The page presents the god-file decomposition and its conformance gate as completed, but on main the file is still one 27,146-line gateway/run.py, issue #54962 is open, and the four index links all 404: three artifacts exist only in open PR #77819, one in neither.

Problems:

• The four campaign-index links (tests/conformance/test_docs_graph_conformance.py, docs/developer-guide/docs-conformance-graph-spec.md, website/static/llms-full.txt, skills/software-development/graph-gated-engineering/SKILL.md) are blob/main URLs that 404 on main today; the conformance test, the doctrine skill, and the spec (at website/docs/developer-guide/docs-conformance-graph-spec.md, a different path than the linked one) exist only in open PR test(conformance): graph-adjudicated documentation conformance + llms-full.txt baseline #77819.
• The body's "the documentation conformance gate adjudicates the page's links against the real tree, so the canon cannot rot" rests on that gate, which is not merged — and the essay's "verified live" claim that the file went from 26,823 lines to a ~2,300-line residue is not the state of main, where gateway/run.py is still a single file and the range-endpoint campaign PRs refactor(gateway): extract media/event helpers from run.py (slice 7 of #54962) #77702 and refactor(gateway): extract GatewayPlatformMixin from run.py (slice 25 of #54962) #77759 are both still open.

Solution:
Point the index links at where each artifact actually lives today (the open PR that adds three of them) and state the campaign's status on main, or hold the page until the conformance PR and the slice PRs land — as written, the page's "verified live" claims describe a tree that is not main.

---

Checked against 5ce1c04 — the PR head when this was written — and 0957277, main at the same moment.

[andrexibiza]

Fixed in ea320f6ca31.

• Pinned the four not-yet-landed artifact links to the immutable test(conformance): graph-adjudicated documentation conformance + llms-full.txt baseline #77819 head and corrected the spec path to website/docs/developer-guide/docs-conformance-graph-spec.md, removing the blob/main 404s.
• Added the current-main status: gateway/run.py is 27,146 lines, Extract Gateway Platform Routing from gateway/run.py #54962 is open, and test(conformance): graph-adjudicated documentation conformance + llms-full.txt baseline #77819 plus slices refactor(gateway): extract media/event helpers from run.py (slice 7 of #54962) #77702/refactor(gateway): extract GatewayPlatformMixin from run.py (slice 25 of #54962) #77759 remain open.
• Reworded the “verified live” and ~2,300-line residue claims as the 2026-08-03 campaign/combined-PR snapshot, and qualified the conformance mechanism and bundled skill as pending merge.

Validation:

• scripts/run_tests.sh tests/conformance/ -q: 4 passed.
• npm run build: passed; Docusaurus still reports pre-existing unrelated broken-link/anchor warnings elsewhere.
• git diff --check: pass.
• python scripts/check-windows-footguns.py --diff HEAD: pass (0 files scanned).

[andrexibiza]

Resolved in ea320f6ca ("docs(guides): reconcile godfile canon with main", pushed 2026-08-07T01:02:06Z — ~30 min after this comment).

Verified each point against current main (0957277f) and the PR head:

1. "verified live" claims now scoped. The page opens with a Current repository status (2026-08-07) callout stating exactly what you flagged: on main, gateway/run.py is still 27,146 lines, Extract Gateway Platform Routing from gateway/run.py #54962 is open, the conformance mechanism lives in open PR test(conformance): graph-adjudicated documentation conformance + llms-full.txt baseline #77819, and slices refactor(gateway): extract media/event helpers from run.py (slice 7 of #54962) #77702/refactor(gateway): extract GatewayPlatformMixin from run.py (slice 25 of #54962) #77759 remain under review. The essay is explicitly reframed as "a historical record, not a claim that every campaign artifact has already landed on main" — its snapshot figures are dated 2026-08-03.

2. The four 404 index links are fixed. The index now links each artifact to the immutable test(conformance): graph-adjudicated documentation conformance + llms-full.txt baseline #77819 head (c7eb778e7b5b…) with the "(in test(conformance): graph-adjudicated documentation conformance + llms-full.txt baseline #77819)" qualifier instead of blob/main:

   • tests/conformance/test_docs_graph_conformance.py
   • website/docs/developer-guide/docs-conformance-graph-spec.md (corrected path)
   • website/static/llms-full.txt
   • skills/software-development/graph-gated-engineering/SKILL.md

3. Remaining blob/main links verified live — every one resolves to a file that exists on main today (gateway/run.py, website/scripts/generate-llms-txt.py).

The "cannot rot" claim now rests on the actual mechanism: the conformance gate ships in #77819, and this page's links point at artifacts by immutable SHA so they can't silently 404 as the tree moves. The page stays a historical record until the conformance PR and slice PRs land, at which point the status callout gets updated.

Thanks for the triage — the blob/main 404s were real and are gone.