enricobuehlerandClaude Fable 5
dfcc530ee7
Phase 2 of the docs-and-onboarding overhaul (items 1-partial, 2 and 4 of the handoff): install.sh: --uninstall reverses step 1 + step 6 per family (user units off first, only the punktfunk packages actually installed, then the repo; config/groups/firewall stay, as /docs/uninstall states) — smoke-tested as a new installer-smoke step on all three families. The end-of-run check now catches the two NVIDIA silent failures on every family: no driver at all, and a module the kernel refused to load (Secure Boot) via an nvidia-smi probe pointing at the troubleshooting anchor; the Fedora ffmpeg-libs/NVENC warning folds into the same block. check-docs-drift.sh gate 7: the manual 16-file os-release matrix PR #345 was verified with, committed — every family's detection, its install line, its removal line and the four unsupported pointers run through the real script under --dry-run on every push (docs-drift's container gains curl, the script's own prerequisite). Screenshots (RFC: "screenshots over prose"): four console shots captured from the same storybook-fixture pipeline web-screenshots.yml runs — login and the armed Pairing page into quickstart.md, the Approve dialog (access level + expiry + guest fast-path) into pairing.md replacing the prose that described it, live status into web-console.md. Files under docs-site/public/img/, dark-theme, bundled+preloaded by the docs build (verified served). Still missing: a client host-list shot — linux-client-screenshots run 19546 built it, but its artifact isn't API-downloadable; add it when a browser session can fetch the zip. WP5 rider: the release-flow docs-freshness step now includes the website content look-over. NOT flipped: installer stays preview — the handoff gates the default flip on real-box mileage (Bazzite above all), which a Mac can't provide. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
punktfunk-docs
The Punktfunk documentation site: Fumadocs on TanStack Start (Vite + Nitro/bun preset).
Content lives in content/docs/ as .md/.mdx. This site is the source of truth
for the user-facing guides; design rationale lives in the internal punktfunk-planning repo, and
READMEs and the marketing site link here instead of restating anything — see "Where facts live" in
CONTRIBUTING.md. Pages serve one of two audiences, not both at once: the
get-started track (quickstart, install, pairing) assumes no Linux expertise — short pages, one
task each, happy path only; the reference track (configuration, CLI, API, per-compositor
pages) is allowed to be dense.
API reference
/api renders the host's management REST API as an interactive
Scalar reference (linked from the top nav, the docs
sidebar, and the landing page). It reads public/openapi.json — a
snapshot of the repo's generated spec. Refresh it after a management-API change:
# from the repo root — regenerate the spec, then copy the snapshot in:
cargo run -p punktfunk-host -- openapi > api/openapi.json
cp api/openapi.json docs-site/public/openapi.json
CI keeps the pair honest: the docs-drift job fails unless the snapshot is a byte-for-byte copy
of api/openapi.json, and the rust job regenerates the spec and diffs it against the committed
one — so a management-API change can't publish stale API docs any more, it fails CI until you run
the two commands above.
Install commands and ports
src/data/platforms.json is a byte-identical snapshot of the repo-root
data/platforms.json — the single source for install commands, repo
URLs, port facts and the Sunshine/Apollo/Vibeshine conflict facts. The <Install platform="…" />
and <Ports /> MDX components (src/components/platforms.tsx) render from it, so no page restates
a command or a port. It's a snapshot for the same reason as openapi.json (the Docker build context
is this directory alone), and the same docs-drift job fails unless it matches:
cp data/platforms.json docs-site/src/data/platforms.json # from the repo root, after editing the canonical file
Develop
bun install
bun run dev # http://localhost:3001 (docs at /docs)
CI gates every change on bun run build followed by bun run lint (the TypeScript typecheck), in
that order — the build emits the .source typegen the typecheck imports. Run both before you push.
Build & serve
bun run build
bun run start # serves .output/ via Bun
Layout
source.config.ts Fumadocs MDX collection (content/docs)
content/docs/ the docs content (.md/.mdx) + meta.json nav
src/
routes/
__root.tsx RootProvider + html shell
index.tsx landing page
docs/$.tsx catch-all docs renderer (Fumadocs DocsLayout)
api/index.tsx Scalar API reference (reads public/openapi.json)
api/search.ts Orama search endpoint
lib/source.ts Fumadocs loader over the generated collection
lib/layout.shared.tsx shared nav chrome
components/mdx.tsx MDX component map
styles/app.css Tailwind 4 + Fumadocs preset