One home per fact: IA rules, docs drift gates in CI, and the READMEs stop restating the docs #337

Merged

enricobuehler merged 1 commits from worktree-docs-wp0-wp1-anti-drift into main 2026-08-19 16:22:07 +00:00

Conversation 0 Commits 1 Files Changed 14

+792 -612

enricobuehler commented 2026-08-19 14:42:37 +00:00

Owner

Copy Link

Copy Source

WP0+WP1 of the docs-and-onboarding overhaul (punktfunk-planning design/docs-and-onboarding-overhaul.md).

WP0 — the rule

CONTRIBUTING.md (new "Where facts live" section) and docs-site/README.md now state the ownership table — docs-site owns user-facing facts, READMEs keep rationale + pointers, the website deep-links — and the two-audience split (get-started track vs reference track).

WP1 — the enforcement

New docs-drift CI job (same shape as bun-nix: pure textual, unfiltered, seconds), backed by two dash-clean scripts:

• scripts/ci/check-docs-drift.sh — 5 gates: ① docs-site/public/openapi.json must be a byte copy of api/openapi.json; ② every PUNKTFUNK_* var the docs mention must still exist in the tree (release notes/CHANGELOG don't count as existence); ③ the undocumented-var set is ratcheted against docs-undocumented-env-baseline.txt (330 entries) so a new knob must be documented or deliberately baselined, and violations are named exactly; ④ every command host-cli.md lists must exist as a literal in the host crate; ⑤ data/platforms.json parses (explicit try/exit — bun -e 1.3.x exits 0 on an uncaught throw).
• scripts/ci/check-docs-links.sh — internal /docs/* links in docs-site content and relative file links in the repo's markdown must resolve. External URLs and #anchors deliberately out of scope.
• rust job — regenerates the OpenAPI spec from the built host and diffs it against the committed file, closing the "not gated" hole CONTRIBUTING itself confessed to.

Per the gate-of-the-gate rule: all seven gates were shown to fail on planted violations (stale snapshot, ghost env var, fresh undocumented knob, ghost CLI command, broken JSON, dead docs link, dead file link) before landing green.

data/platforms.json

Single source for install commands, repo URLs, port facts and the Sunshine/Apollo/Vibeshine conflict facts. Consumers arrive in WP2 (docs install pages), WP3 (website download page), WP4 (guided installer — which also gets punktfunk-host detect-conflicts for free).

README slimming (net −444 lines)

packaging/bazzite (564→191), debian (239→153), arch, rpm, flatpak, and the root README stop restating docs walkthroughs and point at the pages instead. Every cut was verified covered on a docs page first; facts whose only home a README was stay put and are marked for the WP2 migration — the ds_inhibit SELinux storm, the ffmpeg-libs weak-dep NVENC failure, the pacman.conf double-append gotcha. packaging/nix, windows, gamescope, winget are untouched (packager content, and docs currently point to nix/README).

Verified: both scripts green under dash, docs-site bun run build + lint pass, ci.yml parses.

WP0+WP1 of the docs-and-onboarding overhaul (punktfunk-planning `design/docs-and-onboarding-overhaul.md`). ## WP0 — the rule `CONTRIBUTING.md` (new **"Where facts live"** section) and `docs-site/README.md` now state the ownership table — docs-site owns user-facing facts, READMEs keep rationale + pointers, the website deep-links — and the two-audience split (get-started track vs reference track). ## WP1 — the enforcement New `docs-drift` CI job (same shape as `bun-nix`: pure textual, unfiltered, seconds), backed by two dash-clean scripts: - **`scripts/ci/check-docs-drift.sh`** — 5 gates: ① `docs-site/public/openapi.json` must be a byte copy of `api/openapi.json`; ② every `PUNKTFUNK_*` var the docs mention must still exist in the tree (release notes/CHANGELOG don't count as existence); ③ the undocumented-var set is **ratcheted** against `docs-undocumented-env-baseline.txt` (330 entries) so a new knob must be documented or deliberately baselined, and violations are named exactly; ④ every command `host-cli.md` lists must exist as a literal in the host crate; ⑤ `data/platforms.json` parses (explicit try/exit — `bun -e` 1.3.x exits 0 on an uncaught throw). - **`scripts/ci/check-docs-links.sh`** — internal `/docs/*` links in docs-site content and relative file links in the repo's markdown must resolve. External URLs and `#anchors` deliberately out of scope. - **`rust` job** — regenerates the OpenAPI spec from the built host and diffs it against the committed file, closing the "not gated" hole CONTRIBUTING itself confessed to. Per the gate-of-the-gate rule: all seven gates were shown to **fail** on planted violations (stale snapshot, ghost env var, fresh undocumented knob, ghost CLI command, broken JSON, dead docs link, dead file link) before landing green. ## `data/platforms.json` Single source for install commands, repo URLs, port facts and the Sunshine/Apollo/Vibeshine conflict facts. Consumers arrive in WP2 (docs install pages), WP3 (website download page), WP4 (guided installer — which also gets `punktfunk-host detect-conflicts` for free). ## README slimming (net −444 lines) `packaging/bazzite` (564→191), `debian` (239→153), `arch`, `rpm`, `flatpak`, and the root README stop restating docs walkthroughs and point at the pages instead. Every cut was verified covered on a docs page first; facts whose **only** home a README was stay put and are marked for the WP2 migration — the ds_inhibit SELinux storm, the ffmpeg-libs weak-dep NVENC failure, the pacman.conf double-append gotcha. `packaging/nix`, `windows`, `gamescope`, `winget` are untouched (packager content, and docs currently point *to* nix/README). Verified: both scripts green under dash, `docs-site` `bun run build` + `lint` pass, ci.yml parses.

enricobuehler added 1 commit 2026-08-19 14:42:40 +00:00

docs: one home per fact — IA rules, CI drift gates, and READMEs stop restating the docs ... 8f9e451395

WP0+WP1 of the docs-and-onboarding overhaul (punktfunk-planning
design/docs-and-onboarding-overhaul.md):

- CONTRIBUTING.md + docs-site/README.md state the ownership rule (docs-site
  owns user-facing facts; READMEs keep rationale + pointers; the website
  deep-links) and the get-started vs reference audience split.
- ci.yml gains a docs-drift job (scripts/ci/check-docs-drift.sh +
  check-docs-links.sh): the OpenAPI snapshot must be a byte copy of
  api/openapi.json, PUNKTFUNK_* vars the docs mention must exist in the tree,
  the undocumented-var set is ratcheted against a named baseline file,
  host-cli.md commands must exist in the host crate, data/platforms.json must
  parse, and internal doc/README links must resolve. The rust job additionally
  regenerates the spec from the built host and diffs it — closing the 'not
  gated' hole CONTRIBUTING itself confessed to. All seven gates were shown to
  FAIL on planted violations before landing (the gate-of-the-gate rule).
- data/platforms.json: single source for install commands, repo URLs, ports
  and the Sunshine/Apollo/Vibeshine conflict facts — the docs rewrite (WP2),
  website download page (WP3) and guided installer (WP4) consume it.
- READMEs (root, bazzite, debian, arch, rpm, flatpak) stop restating docs
  walkthroughs (net -444 lines); facts whose only home a README was (the
  ds_inhibit SELinux storm, the ffmpeg-libs weak dep, the pacman.conf
  double-append) stay put, marked for the WP2 migration.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

enricobuehler merged commit cd0a370229 into main 2026-08-19 16:22:07 +00:00

enricobuehler deleted branch worktree-docs-wp0-wp1-anti-drift 2026-08-19 16:22:13 +00:00

enricobuehler referenced this issue from a commit 2026-08-19 17:08:02 +00:00

ci: the drift gate matched its own comment, and the OpenAPI snapshot was two versions stale

enricobuehler referenced this issue from a commit 2026-08-19 17:08:45 +00:00

docs: two audiences, one home per fact — get-started rewrite, a Switching-from-Sunshine page, and install commands quoted from platforms.json

enricobuehler referenced this pull request 2026-08-19 17:09:03 +00:00

Docs for two audiences: a get-started track that fits on one screen, a Switching-from-Sunshine page, and install commands quoted from platforms.json #340

enricobuehler referenced this pull request 2026-08-19 18:22:55 +00:00

Land the WP2 docs rewrite on main (#340 merged into the already-merged #337 branch) and make docs-drift green again #343

enricobuehler referenced this issue from a commit 2026-08-19 18:23:52 +00:00

Merge pull request 'Land the WP2 docs rewrite on main (#340 merged into the already-merged #337 branch) and make docs-drift green again' (#343) from docs-wp2-to-main into main

enricobuehler referenced this issue from a commit 2026-08-19 23:24:26 +00:00

release: 0.31.0 — re-cut on d801cb72, folding in the 41 commits since #320

enricobuehler referenced this pull request 2026-08-19 23:24:48 +00:00

0.31.0 release notes, re-cut on current main — and the `bun install` CI flake #351

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

FernandoMX FlipperDan HitFrostbite enricobuehler (Enrico Bühler) kszlim luxus nannku neoney sassycrown

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: unom/punktfunk#337