Repository navigation
feat(site): migrate landing page and public docs to Nimbus - #60
Conversation
Scaffold a pinned Nimbus Astro site that serves the amber B landing
page at / and the public skill pages from docs/{global,project} in the
same static build. Plans and other internal docs stay unpublished.
Co-authored-by: Mr. ED <edheltzel@users.noreply.github.com>
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
Important
Three links in the published documentation resolve to 404s because repository-relative directory links are not rewritten for the site.
Reviewed changes Review of the new static Nimbus site, its canonical documentation ingestion, and its public navigation and agent interfaces.
- Landing page: Adds the amber landing page, animated hero, theme controls, and copyable installation commands.
- Public documentation: Publishes
docs/{global,project}through a grouped docs hub and skill pages, while excluding internal plans. - Documentation UI: Adds responsive navigation, search, TOCs, pagination, and page actions.
- Static interfaces: Adds Markdown/source endpoints, LLM indexes, discovery metadata, social cards, sitemap, and robots output without changing live deployment configuration.
Validation: the production build and typecheck pass, including a build pinned to the reviewed commit. Browser checks covered desktop/mobile rendering, search, and mobile drawer navigation; an output-level link audit confirmed the three broken links noted inline. Nimbus's check returned no findings but explicitly does not lint the 51 .md pages.
gpt-6.1-sol ｜ 𝕏
The canonical docs link to folders relative to their repo path, which
404 under the site's page URLs. Folders under docs/{global,project}
now go to an anchored docs hub section; other repo paths go to GitHub.
check-links walks dist/ and fails on any same-origin link or #fragment that does not resolve. contrast, flash and install-box come from doskills-site unchanged.
…de link The hard-coded counts were stale (67 vs 76 skills). The install CTA points at the README install guide again, as on doskills-site.
The site publishes plain .md docs only. Remove the MDX component registry, partials collection, Render, the server-MCP connect button, the API coordinates route, and their UI components. MDX validation is off since there is no MDX. From the no-mistakes review.
Docs used ui-mode while the landing page used doskills-theme, so a dark choice on / was lost on /docs/. From the no-mistakes review.
Compare computed colours with JavaScript on and off instead of parsing token source. From the no-mistakes review.
DOCS_REF could point the docs at another commit than the landing page and counts. From the no-mistakes review.
@astrojs/prism needs >=22.23.4 and undici >=22.19.0, so 22.12.0 ran outside declared engines. Raising the pin keeps every declared range, unlike overriding Astro's own satteri and unifont versions. Also drop the lint:docs scripts: Nimbus lint reads only .mdx and this site has none.
edheltzel
changed the title
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes Reviewed the changes since 01d9a3d, including the directory-link fix and subsequent site, CI, and documentation updates.
- Fixed directory navigation: Routed repository directory links to anchored docs hub sections and added a built-output link audit.
- Corrected landing metadata: Derived skill counts from
skills/and restored the canonical installation guide link. - Improved documentation UI: Shared theme preferences between landing and docs, revealed ancestors for sidebar group matches, and corrected TOC viewport bands and resize tracking.
- Added validation: Introduced site CI, rendered contrast, theme-flash, and mobile install-box checks; pinned Node and documentation ingestion to the checkout's HEAD.
- Trimmed template code and clarified publishing: Removed unused Nimbus components and routes, updated authoring guidance, and documented Pages deployment, cutover, and rollback without performing a live cutover.
Validation: build, typecheck, link audit, contrast, theme-flash, and mobile install-box checks pass. All 5,046 audited same-origin links resolve; browser checks also verified shared themes, nested-group filtering, and desktop/mobile TOC tracking after resizing.
gpt-6.1-sol ｜ 𝕏
…errors The project now exists, so the runbook names its real hostname instead of looking it up. Every call goes through cf(), which fails on an HTTP error or success:false.
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes Reviewed the cutover runbook changes since 90c4a2e.
- Recorded the verified hostname: Replaced hostname discovery with
doskills.pages.devand documented the successful preview. - Hardened API failures: Routed commands through a helper that rejects HTTP failures and unsuccessful API responses.
- Made rollback resumable: Checked both projects' domain associations before conditionally removing or restoring them.
Validation: mocked execution passed all four rollback association states, successful cutover, and HTTP/API/invalid-response failure cases. Checked Cloudflare's documented response contracts; no live infrastructure changes were performed.
gpt-6.1-sol ｜ 𝕏
Intent
Migrate edheltzel/doskills-site into edheltzel/Do-Skills under site/, using Nimbus (@cloudflare/nimbus-docs), continuing the existing Nimbus migration branch eh/atl-nimbus-migrate-01-doskills-site-513c (PR #60) rather than a competing implementation.
User requirements: ONE Nimbus/Astro static build with the existing landing page at / and public documentation. Preserve the current design, artwork, content, installation instructions, and useful URLs (/, /docs/, /docs/do-grit/, /og.png, /favicon.svg, /loop/*, sitemap). Use Do-Skills/docs/global/** and docs/project/** as canonical sources consumed at build time (Nimbus git source with repo ".." at the build commit), not independently maintained copies. Keep docs/plans, handoffs, and agent-only material unpublished. Pin compatible dependencies (nimbus-docs 0.19.3 exact, astro 7.3.3 as in the Nimbus template-empty reference, lockfile) and Node >= 22.12 (.nvmrc 22.12.0, engines). Static output. Keep site tooling isolated in site/ (own package.json/lockfile, own CI workflow .github/workflows/site.yml) from the repo's skill tooling.
Decisions in this round: fix Pullfrog's finding that repo-relative directory links 404 by a Satteri hast plugin (site/src/lib/repo-links.ts) that sends folders under docs/{global,project} to anchored docs hub sections and other repo paths to GitHub; canonical docs keep repo-relative links per .agents/writing-docs.md. The user explicitly accepted that the generated Markdown outputs (.md/.mdx/llms-full.txt) keep those 3 directory links as written (Nimbus documented behavior, no hook) - do not edit the canonical docs to absolute URLs and do not post-process dist. Added a built-output link checker (HTML only), ported the old site's contrast/flash/install-box checks unchanged, derived landing skill counts from skills/ at build (old hard-coded counts were stale), restored the install-guide CTA to the README install section as on the old site, removed the og.png route shadowed by public/og.png. Added docs/plans/2026-11-06-doskills-pages-cutover.md: Cloudflare Pages cannot change a project's source repo (verified with a scratch project; PATCH ignored), so production moves to a new Pages project "doskills" (root site, npm run build, dist, NODE_VERSION 22.12.0, SITE_URL) with an exact domain cutover and rollback. No production or Cloudflare changes happen in this PR; merge and cutover wait for explicit user approval.
Round 2 context: the previous gate run (01M6RYF33YTJXSM7WPGG7TCRFN) failed in Lint with "daemon shutting down" after Review/Test/Document. Because this is a GitButler workspace (no axi sync --recover), its review and document fixes were re-applied as focused commits on the branch (template cleanup, shared theme key, sidebar ancestors, rendered contrast check, HEAD-only docs ref, docs). One deliberate change from that run: its npm overrides forced Astro's own pinned @astrojs/markdown-satteri (0.4.1 -> 0.4.3) and unifont (~0.7.5 -> 0.7.4) outside their declared ranges to fit Node 22.12.0; that was replaced by pinning Node 22.23.4 (the highest engine any locked package declares, still satisfying the user's "at least 22.12"), with the original lockfile and no overrides. The only remaining engine mismatch is the optional @img/sharp-win32-ia32 binary, which declares ^20.9.0 and never installs on Linux or macOS. Further removal of Nimbus template features (ImageZoom, API/version scaffolding, Banner, WebMCP, per-page OG cards, robots Content-Signal) is out of scope for this migration: they come from the Nimbus reference template and are kept so nimbus-docs upgrade/diff tooling stays aligned. The lint:docs scripts were removed because Nimbus lint reads only .mdx and this site has none.
Round 3 context: after run 01M6S1DJ0F3BN0TKT6K1C9GMGT pushed and CI passed (site check, Cloudflare Pages preview, pullfrog), the replacement Pages project "doskills" was created in Cloudflare (production deployments off, previews only for this branch; no domain, no production change). Its hostname is doskills.pages.dev. This round only updates docs/plans/2026-11-06-doskills-pages-cutover.md to name that real hostname and route every Cloudflare API call through cf(), which fails on HTTP errors or success:false (curl -f plus jq -e .success).
What Changed
site/.doskills.pages.devcutover and rollback with API failure checks.Risk Assessment
✅ Low: The static migration respects the amended requirements and recorded decisions, with no substantiated material defects found in the source or revised rollback.
Testing
The pinned-runtime build, targeted checks, corrected live browser flows and screenshot review passed; an extended paint check filled gaps in the baseline flash check, runbook commands passed against a disposable API, and real Cloudflare cutover remains intentionally deferred. Disposable processes and files were removed.
Evidence: Visual evidence report
Evidence: Live browser and HTTP results
~/.no-mistakes/evidence/01M6S3WC5FZ8BPGA3ZAW1A5EWC/paint-results.json)~/.no-mistakes/evidence/01M6S3WC5FZ8BPGA3ZAW1A5EWC/runbook-api-results.json)Evidence: Rendered contrast results
Pipeline
Updates from git push no-mistakes
✅ **Intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
🔧 **Review** - 2 issues found → auto-fixed ✅
docs/plans/2026-11-06-doskills-pages-cutover.md:97- If the old-domain deletion at :77 succeeds but the new-domain creation at :78 fails, neither project owns the domain. Rollback then unconditionally deletes the absent new association at :97; its not-found error is fatal under cf() and set -e, preventing restoration at :98–100. Make rollback handle the actual association state, including an already-restored old association at :98 after an interrupted rollback, while retaining checks for unrelated API errors.docs/plans/2026-11-06-doskills-pages-cutover.md:80- Round three requires “route every Cloudflare API call through cf()”, but this changed command still usescurl ... | jq -r .result.statusdirectly. An HTTP-success response containing success:false prints null and exits successfully. Route this remaining read through the shared validator; cf() at :51 will also need to preserve the validated response so the status can be displayed.🔧 Fix applied.
✅ Re-checked - no issues remain.
✅ **Test** - passed
✅ No issues found.
git diff 258d4b8fcfaf9f5e0f97c543a8d28eb3aa3eed83 94241c10af43ad2cf59a98664efb3f44848a01ddafter GitButler rejected the bare-backed worktree.npm ci --prefix site --no-audit --no-fund; installed disposable workspace-local Node 22.23.4 and Chromium.npm run buildfrom site/ using Node 22.23.4.npm run check:links.npm run contrast,npm run flashandnpm run install-boxwith workspace-local Chromium.npm run preview -- --host 127.0.0.1 --port 4327.node .qa/live.mjs: real-browser navigation, HTTP responses, assets, canonical docs, privacy, links, search, filters, themes and mobile layouts; corrected final driver exited 0.node .qa/paint.mjs: four theme cases under 4× CPU throttling, with observed painted frames and zero wrong-theme frames.python3 .qa/runbook-test.py: documented Bash against a disposable HTTP API, including rollback recovery and rejection handling.node .qa/mobile-shot.mjsand visual review of desktop, mobile, search and theme screenshots.Stopped the preview, confirmed its port closed, removed disposable files and dependencies, and verified no worktree changes remained.✅ **Document** - passed
✅ No issues found.
site/scripts/flash.mjs:93- Astro check passes with three TS2568 hints for window.__frames at lines 93, 96, and 114. Resolving them requires test-script annotations; this phase forbids test edits.✅ **Push** - passed
✅ No issues found.