feat(docs): prod-faithful dev loop, mermaid cache, favicon, doc fixes

[EricAndrechek]

Summary

Four change sets, one theme: the docs workflow now behaves like production, fast.

1. Production-faithful make dev-docs (docs/scripts/dev.mjs, new): astro dev skips everything the Cloudflare Worker adds in production — cloudflare-md-router content negotiation (.md twins), the pagefind search index, starlight-llm-tools outputs — so the de-facto workflow had become manually cycling make build-docs && make preview-docs. The dev loop now rebuilds on save (debounced; mid-build saves coalesce) into a .dev-dist/ staging dir, syncs into dist/ only on green builds (plain node fs — no rsync or other external tools), and serves through wrangler dev --live-reload on :4321 (DOCS_PORT overrides): the browser refreshes itself per build, and a failed build keeps serving the last good site (red banner + terminal bell). starlight-links-validator is skipped in watch builds so mid-edit dangling links don't block previewing (DOCS_WATCH_STRICT=1 keeps it on; CI and make build-docs enforce links unchanged). The raw HMR server stays available as pnpm run start.

2. Per-diagram Mermaid render cache: every build re-rendered all 17 diagrams through headless Chromium, diagrams changed or not. docs/astro.config.mjs now uses astro-themed-mermaid v0.2.0's rehypeMermaid export (released as part of this work) — rehype-mermaid behind a content-addressed per-diagram disk cache. Warm rebuilds drop 6–7s → ~3.7s, a single-diagram edit re-renders only its page, and output is byte-identical modulo SVG ids. Save → refreshed browser is ~4s end to end.

3. Theme-adaptive favicon that actually displays (commit 19e7a10): four stacked causes peeled — #193 dropped the sizes="any" SVG link (Chromium then picks the .ico); Chromium rasterizes an SVG favicon once and never re-renders on theme flip (crbug.com/1208277); in-place href mutation is honored only transiently; and Chromium's scorer commits an exact-size .ico over a sizes="any" SVG (verified against the profile Favicons SQLite, contradicting the standard blog advice). Fixed via the restored icon-link pair, statically-colored favicon-{light,dark}.svg brand-kit variants, and a Head.astro live-swap script (fresh link node per repaint, .ico removed from live candidates). No-JS and Safari ≤18 keep working fallbacks.

4. CI/review-automation docs refresh (commit 0b54c50): development.md §CI & review automation and CONTRIBUTING.md still described pr-title.yml/Validate, Check/Build checks, project-orchestrator.yml, and label.yml — all replaced by housekeeping.yml / the single CI job / native Projects v2 board workflows (May consolidation, #115). Rewritten against the live config, the 72-char title cap documented, and a Chromium misattribution corrected (starlight-links-validator needs no browser; only rehype-mermaid does).

Test plan

• Dev loop verified end-to-end in-session: wrangler hot-pickup of modified and new assets, Accept: text/markdown twin negotiation, /llms.txt, pagefind, failed builds keep serving the previous dist, file↔directory type-flip recovery in the sync, DOCS_WATCH_STRICT=1 fails loudly on a planted broken link, SIGINT/SIGTERM/pkill teardown leaves no orphans
• Mermaid cache profiled cold (5.8s, 17 entries harvested) and warm (~3.5s); cached output diffed byte-identical to uncached modulo ids; astro:build:done theme patch counts unchanged; v0.2.0 ships 12 unit tests covering hit/miss/harvest/re-id/corruption paths
• Favicon: Chromium profile Favicons DB ground truth, Playwright DOM swap checks both directions + across view transitions, manual Brave/Firefox/Safari
• Docs rewrite verified claim-by-claim against the live ruleset (gh api), housekeeping.yml, ci.yml, and admin-approval.yml by the pre-push review gate
• make ci green for every pushed tree (tree-keyed markers); both pre-push reviewers (code + docs) at ship_it for HEAD

Related issues

• Builds on the brand kit (feat(docs): rebuild site with wavehouse logo and design tokens #142) and head cleanup (fix(docs): final passes on docs before publish #193); favicon entry supersedes the wiring described in the branding-pipeline CHANGELOG entry
• Docs refresh closes out staleness introduced by the workflow consolidation (refactor(ci): remove orchestrator; reviewer-assign in housekeeping #115)

🤖 Generated with Claude Code

[coderabbitai]

Need the big picture first? Review this PR in Change Stack to see what changed before going file by file.

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR adds theme-adaptive favicon support (static light/dark SVGs + runtime swap), implements a production-faithful rebuild-on-save docs dev loop (new Node script + Wrangler serving), and updates config, tooling, docs, and changelog entries to reflect these changes.

Changes

Theme-Adaptive Favicon and Production-Faithful Docs Dev Loop

Layer / File(s)	Summary
Branding favicon asset generation docs/scripts/branding/generate.sh	Extended branding generation to emit static favicon-light.svg and favicon-dark.svg SVG files alongside the existing theme-swapping favicon; updated comments and output reporting.
Astro head and config favicon setup docs/astro.config.mjs	Removed direct rehype-mermaid import, updated Mermaid rehype plugin wiring to use mermaid.rehypeMermaid directly, added SVG favicon link to Starlight head with type="image/svg+xml" and sizes="any", and updated favicon option comment.
Runtime favicon theme swapping docs/src/components/Head.astro, CHANGELOG.md	Added inline script in Head.astro to listen for OS color-scheme changes and Astro page-swap events, dynamically updating the favicon link between light and dark SVG variants; recorded favicon fix in changelog.
Dev rebuild loop orchestration docs/scripts/dev.mjs	Introduced production-faithful development loop: watches src/, public/, and config files; debounces and manages concurrent rebuilds; syncs .dev-dist/ to served dist/ via prune/copy; spawns wrangler dev with live reload; implements coordinated shutdown via signals and exception handlers.
Configuration and tooling wiring docs/package.json, docs/astro.config.mjs, Makefile, .gitignore, .vscode/launch.json	Updated pnpm dev to invoke docs/scripts/dev.mjs; bumped astro-themed-mermaid to v0.2.0; made starlightLinksValidator conditional on watch mode; updated Makefile dev-docs, build-docs, branding-docs help text and clean targets to remove .dev-dist/; added .dev-dist/ to ignore rules; added VSCode launch configs for dev loop and HMR server.
Contributor documentation and script updates docs/src/content/docs/development.md, AGENTS.md, docs/scripts/screenshot.mjs, .github/workflows/admin-approval.yml	Updated contributor dev guide for make tools/Playwright/validator timing, expanded Conventional Commits breaking-change notation, documented admin-approval workflow rule, updated screenshot script to reference correct docs endpoint (:4321), and added docs targets to make help listing.
Changelog and homepage UI updates CHANGELOG.md, docs/src/components/Hero.astro, docs/src/content/docs/index.mdx	Added Unreleased changelog bullets covering contributor-doc consolidation, favicon theme adaptation, SDK ordering behavior, dev loop production-faithful rebuild, and mermaid render-cache optimization; updated Hero.astro comments and license label casing; reformatted homepage card grid indentation.

🎯 3 (Moderate) | ⏱️ ~25 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

📚 Docs preview is live: https://0a4f7e85-wavehouse-docs.wave-rf.workers.dev

Updated for commit 12a734c