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

Merged

enricobuehler merged 1 commits from worktree-docs-wp2-rewrite into worktree-docs-wp0-wp1-anti-drift 2026-08-19 18:16:31 +00:00

Conversation 0 Commits 1 Files Changed 57

+2713 -3239

enricobuehler commented 2026-08-19 17:09:03 +00:00

Owner

Copy Link

Copy Source

WP2 of the docs-and-onboarding overhaul (punktfunk-planning design/docs-and-onboarding-overhaul.md). Stacked on #337 (base is that branch; retarget to main once it merges). The website half is punktfunk-website PR #3, which links the /docs/switching-from-sunshine and /docs/nixos pages introduced here.

Nav

meta.json → Get started / Guides / Switching from Sunshine / Reference / Troubleshooting. Per-compositor pages, configuration, CLI, ports, security, how-it-works, build-from-source live under Reference; the feature pages under Guides.

Get-started track (rewritten for someone with no Linux expertise)

One task per page, happy path only, each under two minutes: quickstart (5 steps: install → start → console → pair → stream), install (pick-your-system hub), ubuntu / debian / fedora / arch / bazzite (4 numbered steps each: GPU driver → install → controllers → start + firewall → "continue at Quick Start step 3"), a new nixos page (moved out of install), pairing (approve-from-console first, PIN second).

• Every distro page quotes its install snippet through a new <Install platform="…"/> MDX component (docs-site/src/components/platforms.tsx) that reads docs-site/src/data/platforms.json — a byte-identical snapshot of data/platforms.json, because the docs Docker build context is docs-site/ alone (same arrangement as openapi.json), and check-docs-drift.sh gate 5 now fails if it diverges. <Ports/> renders the port table the same way on a new reference page ports.mdx, so the four distro pages stop restating port lists. Bazzite gained the firewall step it was missing.
• platforms.json fixed while wiring it: apt snippet lacked the keyring lines; winget lacked winget source add; the Arch repo-add is now idempotent (grep -q guard — the documented double-append gotcha disappears at the source); names match the real floors (Ubuntu 26.04+, Windows 11 22H2+); web-console port + firewall profile names added; client platforms added so the website renders its cards from the same file.

Dense material moved down, not deleted

build-from-source.md (the three distro appendices) · Mint/LMDE/Cinnamon analysis → requirements.md · TOFU/--open → security.md · Secure Boot MOK paths per distro + Arch libavcodec.so soname refusal → troubleshooting · sysext channels/rollback/rebase → updating.md · the 0.28.1 cert note → windows-host.

New: Switching from Sunshine / Apollo / Vibeshine

Coexistence via the 47990 move (PUNKTFUNK_MGMT_BIND, boot-race explanation, IP-added-host and firewall caveats), the Windows display-topology overlap, detect-conflicts exit semantics (1 only for an active host — troubleshooting said "non-zero if any"), what-maps-to-what table, migration steps. The troubleshooting Sunshine section is tightened and points there.

README-only facts migrated (the WP2 markers)

ffmpeg-libs weak dependency (no NVENC on Fedora), the pacman database already registered double-append, the ds_inhibit SELinux storm with DualSense pads — all in troubleshooting now; packaging/bazzite and packaging/arch READMEs are pointers.

Stale claims corrected against the tree

The packaged unit runs 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 trim

~5% by words. The handoff asked for more, but the Guides turned out fact-dense — every heading, command, number, env var and link target is preserved (token-inventory diffs against HEAD); going further means dropping facts, which is a call for a human.

Verified

check-docs-drift.sh + check-docs-links.sh green · docs-site bun run build + bun run lint green · served the bundle and confirmed all 37 cross-page anchors the rewrite links to render, plus the <Install/> blocks and the <Ports/> table.

Net: 57 files, +2728 / −3254, four new pages.

WP2 of the docs-and-onboarding overhaul (punktfunk-planning `design/docs-and-onboarding-overhaul.md`). **Stacked on #337** (base is that branch; retarget to `main` once it merges). The website half is punktfunk-website PR #3, which links the `/docs/switching-from-sunshine` and `/docs/nixos` pages introduced here. ## Nav `meta.json` → **Get started / Guides / Switching from Sunshine / Reference / Troubleshooting**. Per-compositor pages, configuration, CLI, ports, security, how-it-works, build-from-source live under Reference; the feature pages under Guides. ## Get-started track (rewritten for someone with no Linux expertise) One task per page, happy path only, each under two minutes: **quickstart** (5 steps: install → start → console → pair → stream), **install** (pick-your-system hub), **ubuntu / debian / fedora / arch / bazzite** (4 numbered steps each: GPU driver → install → controllers → start + firewall → "continue at Quick Start step 3"), a new **nixos** page (moved out of install), **pairing** (approve-from-console first, PIN second). - Every distro page quotes its install snippet through a new **`<Install platform="…"/>`** MDX component (`docs-site/src/components/platforms.tsx`) that reads `docs-site/src/data/platforms.json` — a byte-identical **snapshot** of `data/platforms.json`, because the docs Docker build context is `docs-site/` alone (same arrangement as `openapi.json`), and `check-docs-drift.sh` gate 5 now fails if it diverges. **`<Ports/>`** renders the port table the same way on a new reference page **ports.mdx**, so the four distro pages stop restating port lists. Bazzite gained the firewall step it was missing. - `platforms.json` fixed while wiring it: apt snippet lacked the keyring lines; winget lacked `winget source add`; the Arch repo-add is now idempotent (`grep -q` guard — the documented double-append gotcha disappears at the source); names match the real floors (Ubuntu 26.04+, Windows 11 22H2+); web-console port + firewall profile names added; client platforms added so the website renders its cards from the same file. ## Dense material moved down, not deleted `build-from-source.md` (the three distro appendices) · Mint/LMDE/Cinnamon analysis → `requirements.md` · TOFU/`--open` → `security.md` · Secure Boot MOK paths per distro + Arch `libavcodec.so` soname refusal → troubleshooting · sysext channels/rollback/rebase → `updating.md` · the 0.28.1 cert note → `windows-host`. ## New: Switching from Sunshine / Apollo / Vibeshine Coexistence via the 47990 move (`PUNKTFUNK_MGMT_BIND`, boot-race explanation, IP-added-host and firewall caveats), the Windows display-topology overlap, `detect-conflicts` exit semantics (**1 only for an active host** — troubleshooting said "non-zero if any"), what-maps-to-what table, migration steps. The troubleshooting Sunshine section is tightened and points there. ## README-only facts migrated (the WP2 markers) ffmpeg-libs weak dependency (no NVENC on Fedora), the pacman `database already registered` double-append, the ds_inhibit SELinux storm with DualSense pads — all in troubleshooting now; `packaging/bazzite` and `packaging/arch` READMEs are pointers. ## Stale claims corrected against the tree The packaged unit runs 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 trim ~5% by words. The handoff asked for more, but the Guides turned out fact-dense — every heading, command, number, env var and link target is preserved (token-inventory diffs against HEAD); going further means dropping facts, which is a call for a human. ## Verified `check-docs-drift.sh` + `check-docs-links.sh` green · docs-site `bun run build` + `bun run lint` green · served the bundle and confirmed all 37 cross-page anchors the rewrite links to render, plus the `<Install/>` blocks and the `<Ports/>` table. Net: 57 files, +2728 / −3254, four new pages.

enricobuehler added 1 commit 2026-08-19 17:09:04 +00:00

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>

enricobuehler merged commit a00c4d2a6a into worktree-docs-wp0-wp1-anti-drift 2026-08-19 18:16:31 +00:00

enricobuehler deleted branch worktree-docs-wp2-rewrite 2026-08-19 18:16:34 +00:00

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

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#340