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

Merged

enricobuehler merged 4 commits from docs-wp2-to-main into main 2026-08-19 18:23:51 +00:00

Conversation 0 Commits 4 Files Changed 60

+2714 -3242

enricobuehler commented 2026-08-19 18:22:54 +00:00

Owner

Copy Link

Copy Source

#340 was merged at 18:16Z — but its base was worktree-docs-wp0-wp1-anti-drift, which #337 had already merged into main at 16:22Z (with its original head), so WP2 and the #337 CI-fix commit (1dd5df01) landed on a dead branch, not on main. This PR carries exactly those commits to main (a00c4d2a = #340's merge, plus a merge of current main on top).

What's in it beyond #340's description:

• Conflict resolution — bazzite.md was rewritten as bazzite.mdx in WP2 and re-touched by #342 on main (the Gaming Mode takeover now idles the session with a user-level drop-in and no longer needs the punktfunk group). #342's fact is ported into bazzite.mdx and the four distro pages' controller step; the old bazzite.md is gone.
• docs-drift green on main again — main's docs-drift job is red right now for two reasons: gate 3 matched its own comment (fixed in 1dd5df01, included here) and #338 introduced PUNKTFUNK_CORE_LOG_LEVEL (an Apple-client debug env knob) without documenting or baselining it — baselined here as deliberately internal. The rust job's OpenAPI diff (0.29.0 → 0.31.0) is also fixed by 1dd5df01.

Verified on the merged tree: check-docs-drift.sh + check-docs-links.sh green, docs-site bun run build + bun run lint green.

#340 was merged at 18:16Z — but its base was `worktree-docs-wp0-wp1-anti-drift`, which #337 had already merged into main at 16:22Z (with its original head), so WP2 and the #337 CI-fix commit (`1dd5df01`) landed on a dead branch, not on main. This PR carries exactly those commits to main (`a00c4d2a` = #340's merge, plus a merge of current main on top). What's in it beyond #340's description: - **Conflict resolution** — `bazzite.md` was rewritten as `bazzite.mdx` in WP2 and re-touched by #342 on main (the Gaming Mode takeover now idles the session with a user-level drop-in and no longer needs the `punktfunk` group). #342's fact is ported into `bazzite.mdx` and the four distro pages' controller step; the old `bazzite.md` is gone. - **docs-drift green on main again** — main's `docs-drift` job is red right now for two reasons: gate 3 matched its own comment (fixed in `1dd5df01`, included here) and #338 introduced `PUNKTFUNK_CORE_LOG_LEVEL` (an Apple-client debug env knob) without documenting or baselining it — baselined here as deliberately internal. The `rust` job's OpenAPI diff (`0.29.0` → `0.31.0`) is also fixed by `1dd5df01`. Verified on the merged tree: `check-docs-drift.sh` + `check-docs-links.sh` green, docs-site `bun run build` + `bun run lint` green.

enricobuehler added 4 commits 2026-08-19 18:22:56 +00:00

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

Two reds on #337's first CI run, both self-inflicted:

- Gate 3 greps every quoted "PUNKTFUNK_*" literal outside docs-site — including the gate's own
  explanatory comment, which spelled out ("PUNKTFUNK_X") as an example and so reported PUNKTFUNK_X
  as a new undocumented knob. Reworded the comment; the regex is unchanged.
- The `rust` job's regenerate-and-diff found `api/openapi.json` still saying `"version": "0.29.0"`
  while the crate is 0.31.0 — the only difference in the whole spec. Regenerated with
  `cargo run -p punktfunk-host -- openapi` (in the punktfunk-rust-ci image) and copied the
  docs-site snapshot.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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

WP2 of the docs-and-onboarding overhaul (punktfunk-planning design/docs-and-onboarding-overhaul.md),
stacked on #337 (WP0+WP1).

Nav (meta.json) is now Get started / Guides / Switching from Sunshine / Reference / Troubleshooting.

Get-started track, rewritten for someone with no Linux expertise — one task per page, happy path,
under two minutes each: quickstart (5 steps), install (a pick-your-system hub), ubuntu, debian,
fedora, arch, bazzite (+ a firewall step it was missing), a new nixos page (moved out of install),
pairing. Every distro page quotes its install snippet through a new <Install platform="…"/> MDX
component that reads docs-site/src/data/platforms.json — a byte-identical snapshot of
data/platforms.json (the Docker build context is docs-site/ alone, same arrangement as
openapi.json) which scripts/ci/check-docs-drift.sh now gates. <Ports/> renders the port table the
same way on a new reference page, ports.mdx, so the four distro pages stop restating port lists.

platforms.json itself was fixed while wiring it up: the apt snippet lacked the keyring lines, the
winget one lacked `winget source add`, the Arch repo-add is now idempotent (grep guard — the
documented double-append gotcha disappears at the source), names match the real floors (Ubuntu
26.04+, Windows 11 22H2+), a web-console port entry and the firewall profile names were added, and
client platforms (Windows MSIX, macOS, TestFlight, Play, Steam Deck) so the website can render its
cards from the same file.

Dense material moved down rather than deleted: build-from-source.md (the three distro appendices),
the Mint/LMDE/Cinnamon analysis → requirements.md, TOFU/`--open` → security.md, Secure Boot MOK
paths and the Arch libavcodec soname refusal → troubleshooting, sysext channels/rollback/rebase →
updating.md, the 0.28.1 cert note → windows-host.

New page switching-from-sunshine.md: coexistence via the 47990 move (PUNKTFUNK_MGMT_BIND), the
Windows display-topology overlap, detect-conflicts exit semantics (1 only for an active host — the
troubleshooting page said "non-zero if any"), what maps to what, migration steps. The
troubleshooting Sunshine section is tightened and points there.

The three facts whose only home was a README now live in troubleshooting — the ffmpeg-libs weak
dependency (no NVENC on Fedora), the pacman double-append error, the ds_inhibit SELinux storm with
DualSense pads on Bazzite — and packaging/bazzite + packaging/arch READMEs are pointers.

Stale claims corrected against the tree: the packaged unit runs the native-only `serve` and
GameStream is opt-in on every route (kde, hyprland, security, steamos-host said otherwise);
host.env is optional (EnvironmentFile=-); Fedora 43 uses the `bazzite` group; the iOS clipboard
bridge exists; PUNKTFUNK_GAMESCOPE_SDR_NITS defaults to 203.

Guides trimmed for verbosity (~5% by words — they are fact-dense; every heading, command, number,
env var and link target is preserved, verified by token-inventory diffs). Tooling: docs-site README
and CONTRIBUTING describe the platforms snapshot; input/uninstall/support-matrix links retargeted.

Verified: check-docs-drift.sh and check-docs-links.sh green, docs-site `bun run build` + `bun run
lint` green, and the built site served locally to confirm every cross-page anchor the rewrite
links to (37) renders, plus the <Install/> blocks and the <Ports/> table.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Merge pull request '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) from worktree-docs-wp2-rewrite into worktree-docs-wp0-wp1-anti-drift ... a00c4d2a6a

Reviewed-on: #340

Merge origin/main into the docs WP2 branch — bazzite.md was rewritten as bazzite.mdx here and re-touched by #342 there; #342's fact (the Gaming Mode takeover no longer needs the punktfunk group) is ported into bazzite.mdx and the four distro pages, and the Apple client's PUNKTFUNK_CORE_LOG_LEVEL (from #338) is baselined so docs-drift is green on main again. 60406c9d72

enricobuehler scheduled this pull request to auto merge when all checks succeed 2026-08-19 18:23:46 +00:00

enricobuehler merged commit 2a60f94f74 into main 2026-08-19 18:23:51 +00:00

enricobuehler referenced this issue from a commit 2026-08-19 23:24:27 +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#343