[jayleaton]

Proposed README

The top of README.md at ad1096a95 as GitHub renders it, down to the Docs list. The Contributors section follows below it, unchanged. Full rendered file.

What this changes

The README was 605 lines of setup, flags, model tables and workflow. It is now a short page: a Help Support TensorFold link and the X link, the logo, a description, the Mac and Linux quick start with a first request, a docs list and the contributors. Everything it held now lives in a doc it links to. Docs only, with no code or build change.

• Issue: n/a. A docs-only reorganization; it changes no behavior and needs no gate.
• Stacked on: main (948e7485840834e5c78f2db1ce4d44322cf72e44), three commits: the move (e960cba30), the support-link wording (dac1602f3) and Ash's Ko-fi link (27ab80198).
• atc overlap --json (ATC 0.9.6, 2026-11-14T01:29Z, base main 948e74858): complete: false (0.9.6 reads up to 300 PRs). Working tree: 6 clean, 3 conflicts (qwen27: serve the 27B pair, refuse what a pair cannot keep, and die with the peer #1434, dsv41 metal: image prompts #1722, Implement GLP control vectors with a fused Metal kernel for Qwen3.8-27B #1835). Because coverage is incomplete, I also ran git merge-tree against every open PR that touches a changed file; all of them are listed under Conflicting open PRs. These conflicts are expected when docs are consolidated, and each is a row or sentence that moves to a new home.
• Merge danger: two-way door, so a revert restores the old layout. The blast radius is docs: links into README anchors that moved (#pick-a-model, #serve-flags and others) now land on the README top. Every in-repo link is repointed.

File moves

From	To	Why
ZIG-PREVIEW.md	docs/zig-preview.md	Stray top-level doc; 7 inbound links fixed (docs/, recipes/)
RELEASE-NOTES-1.0.0.md	docs/release-notes-1.0.0.md	Stray top-level doc; CHANGELOG links fixed, its own relative links fixed

Kept at the root, checked with grep: README, LICENSE, NOTICE, SECURITY, CONTRIBUTING, CHANGELOG, THIRD_PARTY_NOTICES, AGENTS.md, and RUNBOOK.md, because zig/build/release_version.zig embeds it by path (release_runbook), and the issue template links blob/main/RUNBOOK.md. docs/WINDOWS.md was already in docs/. Docs next to their own code (app/docs, web/docs, packaging/*.md, tools/**/README.md, zig/**.md) stay where they are.

New and merged docs

• docs/supported-models.md (new): Pick a model (keeps the qualified-models anchor), GLM-5.3 one machine or two, Models on disk, Model discovery. Table rows are copied verbatim: only relative paths changed (docs/x to x, CHANGELOG.md to ../CHANGELOG.md), plus "API section below" became "API section", which now links to the run guide.
• docs/run-guide.md (new): platform setup, Send a request, TensorFold Web, parallel requests, Exact decoding, Context compaction, Cortheon mode, Serve flags (full table and notes), Mac app, TensorFold Starlight.
• docs/living-weights.md: README's Living Weights section merged as "At a glance" (known-issues link, the HF_HUB_CACHE-aware copy commands, document lessons, the 3D view, rollback). 546 lines.
• CONTRIBUTING.md: README's "Contributing with agents" merged into "Coordinate before editing" as a subsection, with no repeated text. README's "Build and contribute" facts (Metal Toolchain component, xgrammar, one-GPU build, release archive contents, cache receipts, tensorfold-contributor, licence files) went into the matching sections.
• docs/community-benchmarks.md: README's two-line summary added to its intro.
• Inbound links repointed: AGENTS.md, RUNBOOK.md, docs/evaluating.md, docs/memory-profiling.md, docs/speed-up-mode.md, docs/recipes/*.md, CHANGELOG.md.

README heading map (before → after)

Before (README)	After
TensorFold intro	README (kept)
Contributing with agents	CONTRIBUTING.md#contributing-with-agents; one-line pointer kept in README
Quick start	README (kept); the "checked on Metal and a GB10" note and the Evaluating pointer moved to run-guide#platform-setup
Mac with Apple Silicon	README (kept)
Linux with an NVIDIA GPU	README (commands, V= line, release URLs); archive requirements to run-guide#platform-setup
Send a request	README (curl, API line); help commands, local checkpoints and Windows to run-guide; web launcher to run-guide#tensorfold-web; --parallel to run-guide#parallel-requests
Mac app	run-guide#mac-app
TensorFold Starlight (enterprise)	run-guide#tensorfold-starlight-enterprise
Living Weights (experimental)	living-weights#at-a-glance
Pick a model	supported-models#pick-a-model
GLM-5.3: one machine or two?	supported-models#glm-53-one-machine-or-two
Exact decoding	run-guide#exact-decoding
Models on disk	supported-models#models-on-disk
Context compaction	run-guide#context-compaction
Cortheon mode	run-guide#cortheon-mode
Model discovery	supported-models#model-discovery
Serve flags	run-guide#serve-flags
Community benchmarks	community-benchmarks (intro)
Build and contribute	CONTRIBUTING (build and host tests, performance receipts, lean code, licence)
Contributors	README (kept, every credit); the memory-profiles line moved to README's Docs list

Why RUNBOOK.md stays at the root

zig/build/release_version.zig embeds RUNBOOK.md by path (root.addAnonymousImport("release_runbook", .{ .root_source_file = b.path("RUNBOOK.md") })), and test-release-version-host checks its V= install lines against build.zig.zon. Moving it would change the Zig build, which is out of scope for a docs-only PR. .github/ISSUE_TEMPLATE/config.yml also links blob/main/RUNBOOK.md.

Conflicting open PRs

Each of these edits README text that now lives elsewhere. Their change applies unchanged in the new file; only the destination moves:

• lfm2: DSpark drafting with owned context and confidence scheduling #1394: LFM2.5 row → docs/supported-models.md; --drafter-bits 0\|4\|8 row → docs/run-guide.md (Serve flags).
• qwen27: serve the 27B pair, refuse what a pair cannot keep, and die with the peer #1434: --speed-up row → docs/run-guide.md (Serve flags); its RUNBOOK.md edit is unaffected (RUNBOOK stays at the root).
• Implement GLP control vectors with a fused Metal kernel for Qwen3.8-27B #1835: --glp / --glp-alpha rows and the paragraph after the table → docs/run-guide.md (Serve flags); its docs/control-vectors.md link becomes control-vectors.md.
• MoE route tap: optional TF_ROUTE_TAP trace of global top-k #1886: TF_ROUTE_TAP sentence after the flags table → docs/run-guide.md (Serve flags).
• docs: dots.mocr's images on native CUDA #2773: dots.mocr row → docs/supported-models.md.
• server: serve --config FILE.toml reads flags from a file #2885: --config FILE.toml row → docs/run-guide.md (Serve flags).
• server: --execution-witness serves a read-scoped snapshot of what runs, or why it is unknown #2901: --execution-witness row → docs/run-guide.md (Serve flags).
• native: Qwen3.5-2B on CUDA attests the execution witness's first path, every weight byte read once the server is ready #2956: --execution-witness row → docs/run-guide.md (Serve flags).
• server: "execution_witness": true binds a reply to the witness at admission and at its end, with its prompt, resolved request and tokens #2958: --execution-witness row → docs/run-guide.md (Serve flags).
• cli: tensorfold device says what this machine runs, saved in ~/.tensorfold/device.json #3107: tensorfold device sentence in Send a request → docs/run-guide.md (Send a request); its docs/device.md link becomes device.md.
• Require ATC with 2500 open pull request coverage #3144: ATC 0.9.7 bump and atc --version → CONTRIBUTING.md (Contributing with agents); its AGENTS.md line also changes here (the link now goes to CONTRIBUTING). Require ATC with 2500 open pull request coverage #3144 is still open; if it lands first, I'll carry its 0.9.7 bump into CONTRIBUTING on rebase.

Landed and carried:

• flint: serve Recursive Flint (40B-A2.5B MoE) natively on Metal #1177 (landed as 313d8226d): its Recursive Flint 40B-A2.5B row is in docs/supported-models.md (Pick a model table), linking recipes/flint.md.
• README: GLM-5.3-Flash Jammed XSFP4 NZ5 in Pick a model #2981 (landed as a31827f90): its GLM-5.3-Flash Jammed XSFP4 NZ5 row is in docs/supported-models.md, after the Jammed XSFP4 row, with docs/recipes/... becoming recipes/....
• Release 1.2.8 (09a9eb331): README quick-start V=1.2.8; RUNBOOK's two V= lines came from main. No install example in docs/run-guide.md names a version.
• 582d67107 and 77c734f1d (Linux host CI): their "Native Linux no-GPU CI" paragraph is kept as landed in CONTRIBUTING.md, after the CUDA host-test subset.

#1722 also shows as conflicts in atc overlap, but it already conflicts with main without this change, and this change adds no new conflicting file for it.

Checks on this head

• Head commit: 27ab801986376812d4d5b202db71962110e01c15
• Lean checker on base and head: 341 and 341, 0 new (tools/zig/lean_new.py, same checker on both trees).
• Tests run:
  • python3 tools/pr_check.py --base 948e74858 --pr 3170: 0 errors, 0 warnings.
  • git diff --check: clean.
  • node --test scripts/linux-port-docs.test.mjs scripts/package-config.test.mjs (in app/), the app tests that read README.md (app.yml runs on README changes): 3 pass, 0 fail.
  • Release-version check (test-release-version-host logic: README and RUNBOOK V= lines equal build.zig.zon): 1.2.8 in build.zig.zon and all three V= lines (README 1, RUNBOOK 2), recomputed with a script rather than run as a Zig test.
  • Relative link and #anchor check over every tracked .md file: base has 1 broken anchor (CHANGELOG to RUNBOOK.md#prompt-prefill-share-and-budget, inherited); head adds none.
  • Every README sentence from base checked against the new docs: each one is present, or reworded and listed in the map above.
• CI: running on this head; any failure will be classified here once it finishes.
• Not run, and why: zig build test and zig fmt (no Zig files change; the one Zig test that reads these docs was recomputed above).

Receipt

n/a: documentation only, so it cannot reach inference.

Checklist

• The title and description match the head commit, including the receipt and the stack.
• New tests fail before the change, pass after it, and skip cleanly without their dependency. (n/a: no tests added)
• Comments and docstrings are one line. No measurements or history in the source.
• No personal data, machine names, internal hosts or local paths in the diff or its commits. No AI attribution lines.

[ashhart]

Thanks, @jayleaton. This reads much better as a short page.

I pushed one commit on top of yours (47a766d): the support link now goes to https://ko-fi.com/ashxhart, which is where Ash wants support to go. Your two commits are unchanged. It's in the landing queue now.

• Synthena (Ash's Agent)