update-polykybd-docs

name

update-polykybd-docs

description

When you add or change a USER-FACING feature in the firmware or host — a new HID command / PROTOCOL_VERSION, a polyctl subcommand, a host setting or tray menu item, a keyboard feature (glyph script, idle style, brightness, font pack), or a language/layout — also extend the public documentation site (the polykybd-docs repo). Use whenever a change would make an existing docs page wrong or leave a new capability undocumented, at the end of feature work, or when the session-retro skill flags a docs gap. ALSO use when an existing page turns out to be wrong or stale for an ALREADY-SHIPPED feature — a user hit a documented step that no longer works, a default flipped in an earlier release, or a page still recommends a path that has since been gated off; the change that broke the page need not be one you just made. NOT for internal-only refactors, bug fixes with no user-visible change, or the firmware/host code change itself.

Extend the PolyKybd docs when a feature lands

PolyKybd's user documentation is a separate Astro Starlight site in the polykybd-docs repo (published at https://www.polykybd.org). A feature is not "done" until the docs describe it — otherwise the site silently drifts (e.g. the HID reference sat at PROTOCOL_VERSION 3 while the firmware was at 11, and glyph scripts / font packs shipped undocumented for months).

This skill is the checklist for keeping the docs in lockstep. It is cross-repo: the docs change is its own branch + PR in polykybd-docs, never part of the firmware/host PR.

When it applies (and when it doesn't)

Update the docs when the change is user-visible:

• A new / changed HID command or a PROTOCOL_VERSION bump.
• A new polyctl subcommand or flag.
• A new host setting, tray menu entry, daemon behaviour, or install/startup step.
• A new keyboard feature (idle style, glyph script, brightness/sensor, font pack, overlay behaviour, multi-machine).
• A new language / layout (the add-polykybd-language skill covers the firmware side; this covers the docs mention).
• Any change that makes an existing docs statement wrong (renamed thing, changed default, removed option).

Skip it for internal refactors, bug fixes with no user-visible effect, or firmware/host build-plumbing.

Where the docs live

Sibling checkout ../polykybd-docs (clone thpoll83/polykybd-docs if absent). Default branch main. Astro Starlight; pages are Markdown/MDX under src/content/docs/<section>/<page>.{md,mdx}. The URL is the file path (using/glyph-scripts.mdx → /using/glyph-scripts/).

Sections (nav order): Introduction · Assembly · Setup · Using the Keyboard · Host Software · Firmware · Development · Reference. The sidebar is hand-curated in astro.config.mjs (sidebar: [...], slug-based) — a new page must be added there or it won't appear in the nav.

Feature → page map (where to write)

You changed…	Update these pages
HID command / PROTOCOL_VERSION	reference/hid-protocol.mdx — the command table and the per-version history list. Bump the "current" version.
A polyctl subcommand	software/cli.mdx (subcommand table)
Host setting / daemon / startup	software/usage.mdx, software/architecture.mdx, or setup/installation.mdx
Keyboard feature (glyph script, idle, brightness, font pack, overlays)	the matching page under using/ or firmware/ (add a new page if it's a new feature area)
A new language / layout	using/languages.mdx
New term worth defining	reference/glossary.mdx
Anything genuinely new	add a page and a sidebar entry in astro.config.mjs; consider a cross-link from a related page so it's discoverable

Match the site's voice: user-facing, friendly, <Aside> callouts and tables, no internal debugging detail. If you move/rename a page, add a redirects entry in astro.config.mjs for the old URL.

Procedure

1. Get the docs repo current: git -C ../polykybd-docs fetch origin main && git -C ../polykybd-docs checkout -B claude/docs-<feature-slug> origin/main. (Docs are their own PR — do this even mid-firmware-work.)
2. Find the affected page(s) from the map above; grep the docs for the old fact if you're correcting drift (grep -rn "PROTOCOL_VERSION 3" src/).
3. Edit / add the page(s). For a new page, add the slug to the sidebar in astro.config.mjs; add a cross-link from a related page.
4. Verify (see below).
5. Commit + push the docs branch and open a PR in polykybd-docs (base main). Keep it separate from the firmware/host PR; note the companion PR in both descriptions.

Verify

Cheap checks first (no build needed):

cd ../polykybd-docs
# every internal /section/page link resolves to a file:
grep -rhoE '\]\(/[a-z0-9-]+/[a-z0-9-]+' src/content/docs --include='*.md' --include='*.mdx' \
  | sed -E 's/^\]\(//' | sort -u \
  | while read -r l; do [ -f "src/content/docs$l.mdx" ] || [ -f "src/content/docs$l.md" ] || echo "BROKEN: $l"; done

Then a full build. Try plain npm ci first — it works, and sharp installs:

npm ci --no-audit --no-fund
npx astro build                    # expect "N page(s) built", no errors

⚠️ The --ignore-scripts + passthroughImageService workaround below is a FALLBACK, not the default — an earlier version of this skill presented it as mandatory ("npm ci fails because sharp can't fetch its prebuilt binary, HTTP 403"). That was environment-specific and no longer holds (verified 2026-08: plain npm ci installed sharp and the build emitted real WebP).

Never use the fallback when the change involves images. Passthrough disables resizing and WebP conversion entirely, so the build no longer reflects what the site serves — any check of an image's dimensions or weight silently measures the source file instead of the emitted asset, and reads as a pass.

Only if npm ci genuinely fails on sharp's postinstall:

npm ci --ignore-scripts            # installs deps, skips sharp's postinstall
# temporarily swap in a passthrough image service so the build needs no sharp:
cp astro.config.mjs /tmp/ac.bak
node -e 'let s=require("fs").readFileSync("astro.config.mjs","utf8");
 s=s.replace("import mermaid from \x27astro-mermaid\x27;","import mermaid from \x27astro-mermaid\x27;\nimport { passthroughImageService } from \x27astro/config\x27;");
 s=s.replace("export default defineConfig({","export default defineConfig({\n  image: { service: passthroughImageService() },");
 require("fs").writeFileSync("astro.config.mjs",s);'
node_modules/.bin/astro build      # expect "N page(s) built", no errors
cp /tmp/ac.bak astro.config.mjs    # RESTORE — never commit the passthrough tweak

If you added heading anchors in links, confirm each target heading exists (Starlight slugs headings as lowercase, non-alphanumerics dropped, spaces→-; an em-dash "—" between words yields a double hyphen).

Pitfalls

• Keep the HID protocol reference authoritative. On any command / version change, update BOTH the command table and the version history, and the "current version" wording. This is the page most prone to silent drift.
• A new page needs a sidebar entry in astro.config.mjs — Starlight won't auto-add it, and an orphan page is invisible.
• Docs are a separate PR in polykybd-docs (base main) — do not bury a docs edit inside a firmware/host PR; they merge on different branches.
• Never commit the passthrough image-service tweak — it's only a fallback for a broken sharp install; restore astro.config.mjs before committing. And never reach for it at all on an image change: it turns off resize + WebP, so the build stops reflecting what the site serves.
• User voice, not dev notes. These pages are for keyboard owners; put deep mechanism in the firmware/host CLAUDE.md or the development/ section, not the user pages.
• Add a redirect when you move/rename a page (old bookmarks are live).