[lucasbraum]

Adds a docs site at /docs, built with Astro Starlight. The landing page at / is unchanged apart from a Docs link in its top bar and footer. The footer link is there because the top-bar nav is hidden on mobile.

Content

• Every build clones uptide-dev/uptide@main over anonymous HTTPS and uses its docs/ folder as the content collection (docs-site/scripts/fetch-docs.mjs). The checkout and the generated pages are gitignored; a test asserts no docs are committed here.
• Titles and descriptions: each page's front matter title/description is used as is. 23 pages (architecture, packs, the decision records, …) have no front matter, so they fall back to their first # heading and first paragraph. A leading Status: accepted (…) line is skipped. The first # is dropped because Starlight renders the title as the h1.
• Sidebar: built from the docs/README.md tables, "Using Uptide" first, then "Contributing and internals", in README order. decisions/ becomes a collapsed group, and CONTRIBUTING.md and SECURITY.md link to GitHub. A README without those two sections fails the build.
• Links: a link to another page under docs/ stays on the site (../concepts.md#exit-codes → /docs/concepts/#exit-codes). Links to anything else in the repository go to GitHub: ../CONTRIBUTING.md and ../packs/queue.json to blob/…; fixtures/repos/storefront and decisions/ to tree/….
• Edit links: each page's "Edit page" link opens the source file on GitHub.

Brand

• Tokens and fonts: the Uptide tokens are mapped onto Starlight's color scale for both themes (docs-site/src/styles/uptide.css). Space Grotesk, Instrument Sans and IBM Plex Mono load from the existing site/fonts files.
• Shape: square corners, 1px rules, no shadows.
• Code blocks: Expressive Code with a single dark theme on #131210 in both themes.
• Header: the two-blue mark and lowercase uptide wordmark link to /, with GitHub and npm icon links. Search is Starlight's built-in Pagefind.
• One deviation: light-mode dim text is #6A675F instead of the landing page's #76736B, which is just under 4.5:1 for small text on #F4F2EC.
• Meta tags: canonical URLs and og:image (the existing og.png) come from the same SITE_URL as the landing page.

Deploy

• Pages: pages.yml builds the docs, assembles site/ at the root and the docs under /docs into _site/, writes SITE_URL, checks links, and deploys. It triggers on every push to main, daily at 05:23 UTC (to pick up docs changes in uptide-dev/uptide), and on workflow_dispatch. It no longer filters on site/**, since the docs come from another repository.
• CI: a new site job in ci.yml runs the same build and link check on PRs.
• Versions: astro@7.3.8, @astrojs/starlight@0.42.6 and @astrojs/markdown-remark@7.3.2 are pinned exactly (save-exact). The lockfile is committed and Node 22.22.0 is pinned in docs-site/.node-version. Astro 7 no longer bundles the remark pipeline, which is why @astrojs/markdown-remark is a direct dependency.

Checks run locally

• Build: npm run build with the real anonymous clone gives 41 docs pages and the Pagefind index.
• Links: scripts/check-links.mjs checks 2,660 internal links and anchors across landing + docs; none are broken. I confirmed it fails when given a missing page or a missing #anchor.
• Lighthouse accessibility (13.5.0): 100 on /docs/ and /docs/commands/fix/, light and dark, with both the mobile and desktop presets. Dark runs used --force-dark-mode; Lighthouse's own screenshots show the dark background, so the dark theme really rendered.
• Tests: node --test 'test/*.test.mjs' passes 11 tests. New ones cover exact versions, nothing committed, title/description fallbacks, the sidebar, and link rewriting. The workflow tests were updated for the new triggers and _site artifact.

Screenshots

	Light	Dark
/docs/
/docs/commands/check/
Search: "telemetry"

The landing captures in docs/screenshots/site-landing/ are refreshed because the nav gained the Docs link.

Notes

• npm audit reports 10 moderate advisories, all through postcss-selector-parser <7.1.6. It is a build-time transitive dependency of Astro, and nothing from it ships to the browser. The only fix offered is npm audit fix --force with breaking changes, so I left it for an Astro update.
• There is no custom 404. GitHub Pages serves only a root 404.html, which the landing page doesn't have today.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VcwhsQvN6vtpRCe4uwfe8z

---

Generated by Claude Code