feat: migrate from Starlight to Nimbus documentation framework

.changeset/brave-nimbus-docs.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/polystella": patch
+---
+
+Document the requirement to add a Changesets entry for package-affecting changes and record the docs migration to Nimbus.

.github/workflows/docs.yml

@@ -27,7 +27,7 @@ concurrency:
 
 jobs:
   build:
-    name: Build Starlight site
+    name: Build Nimbus docs site
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:

AGENTS.md

@@ -29,6 +29,7 @@ section numbers. Inserting new sections never breaks links.
 | `pnpm test:watch`        | Vitest in watch mode.                                                                                                                                                                                        |
 | `pnpm build`             | Compile `src/` → `dist/` via `tsc -p tsconfig.build.json` (mirrored layout, `.js` + `.d.ts` + sourcemaps + declaration maps). Produces the standalone `polystella` CLI at `dist/cli.js` and library entries. |
 | `pnpm exec tsc --noEmit` | Typecheck against the root `tsconfig.json` (which includes tests). The build config (`tsconfig.build.json`) sets `noEmit: false` and narrows `include` to `src/**`.                                          |
+| `pnpm changeset`         | Add a Changesets entry for package-affecting work. Use `pnpm changeset add --empty` only for changes that intentionally do not need a package release.                                                       |
 
 No lint step yet.
 
@@ -85,6 +86,12 @@ to the explanatory section when adding code that touches one.
 ### Always
 
 - Run `pnpm test` before pushing. Tests must stay green.
+- Add a Changesets entry for every change that affects the published
+  package, its documented behaviour, or release-facing contributor
+  guidance. Use `pnpm changeset` for release notes; use
+  `pnpm changeset add --empty` only when the change deliberately does
+  not require a package release (for example, docs-site-only or CI-only
+  maintenance).
 - Bump the package version in `package.json` only — `POLYSTELLA_VERSION`
   (in `src/version.ts`) reads it at module-load time via a JSON
   import attribute, so the constant flows automatically through to

CONTRIBUTING.md

@@ -43,7 +43,7 @@ Required:
 | `pnpm exec tsc --noEmit`              | Typecheck the package.                                          |
 | `pnpm build`                          | Compile `src/` → `dist/` (library + CLI, JS + `.d.ts`).         |
 | `pnpm build:llms`                     | Regenerate `llms-full.txt` from canonical agent docs.           |
-| `pnpm --filter polystella-docs dev`   | Run the Starlight docs site locally.                            |
+| `pnpm --filter polystella-docs dev`   | Run the Nimbus docs site locally.                               |
 | `pnpm --filter polystella-docs build` | Build the docs site (includes auto-generated config reference). |
 | `pnpm --filter polystella-docs check` | Astro check over docs content.                                  |
 

README.md

@@ -88,7 +88,7 @@ collection APIs.
 
 ## Documentation
 
-Full documentation lives at the Starlight docs site (under `docs/` in this repo):
+Full documentation lives at the Nimbus docs site (under `docs/` in this repo):
 
 - [Getting started](https://polystella-docs.pcx-team.workers.dev/getting-started/install/) — install, quick start, mental model
 - [Concepts](https://polystella-docs.pcx-team.workers.dev/concepts/how-it-works/) — pipeline, cache, overrides, runtime bridge

docs/.nimbus/lint.json

@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "rules": {
+    "nimbus/frontmatter-shape": "error",
+    "nimbus/internal-link": "error"
+  },
+  "collections": {},
+  "site": "https://polystella-docs.pcx-team.workers.dev"
+}

docs/.nimbus/routes.json

@@ -0,0 +1,50 @@
+{
+  "version": 1,
+  "base": "/",
+  "knownRoutes": [
+    "/",
+    "/404",
+    "/adapters/custom-loader",
+    "/adapters/markdown",
+    "/adapters/mdx",
+    "/adapters/toml",
+    "/cli",
+    "/cli/audit-mdx",
+    "/cli/check-ui",
+    "/cli/sync-ui",
+    "/cli/translate",
+    "/cli/translate-ui",
+    "/concepts/ai-marker",
+    "/concepts/glossaries",
+    "/concepts/how-it-works",
+    "/concepts/mode-boundary",
+    "/concepts/overrides",
+    "/concepts/r2-cache",
+    "/concepts/runtime-bridge",
+    "/configuration",
+    "/configuration/reference",
+    "/cookbook/locale-picker",
+    "/getting-started/install",
+    "/getting-started/mental-model",
+    "/getting-started/quick-start",
+    "/operations/branch-dispatch",
+    "/operations/ci",
+    "/operations/preview-isolation",
+    "/providers/anthropic",
+    "/providers/batching",
+    "/providers/model-selection",
+    "/providers/permanent-errors",
+    "/providers/workers-ai",
+    "/reference/breaking-changes",
+    "/reference/exports",
+    "/roadmap",
+    "/routing/configuration",
+    "/routing/shims",
+    "/runtime-api/explicit-imports",
+    "/runtime-api/locals",
+    "/runtime-api/middleware",
+    "/runtime-api/react-hooks",
+    "/troubleshooting/missing-translations"
+  ],
+  "opaqueNamespaces": []
+}

docs/astro.config.ts

@@ -0,0 +1,94 @@
+import { defineConfig } from "astro/config";
+import icon from "astro-icon";
+import nimbus, { defineConfig as defineNimbusConfig } from "nimbus-docs";
+
+const nimbusConfig = defineNimbusConfig({
+  site: "https://polystella-docs.pcx-team.workers.dev",
+  title: "PolyStella",
+  description: "AI-driven content localization for Astro",
+  locale: "en",
+  github: "https://github.com/cloudflare/polystella",
+  editPattern: "https://github.com/cloudflare/polystella/edit/main/docs/{path}",
+  socialImageAlt: "PolyStella documentation preview",
+  sidebar: {
+    items: [
+      {
+        label: "Getting started",
+        items: ["getting-started/install", "getting-started/quick-start", "getting-started/mental-model"],
+      },
+      {
+        label: "Concepts",
+        items: [
+          "concepts/how-it-works",
+          "concepts/r2-cache",
+          "concepts/glossaries",
+          "concepts/overrides",
+          "concepts/mode-boundary",
+          "concepts/runtime-bridge",
+          "concepts/ai-marker",
+        ],
+      },
+      {
+        label: "Configuration",
+        items: ["configuration", "configuration/reference"],
+      },
+      {
+        label: "Adapters",
+        items: ["adapters/markdown", "adapters/mdx", "adapters/toml", "adapters/custom-loader"],
+      },
+      {
+        label: "Providers",
+        items: [
+          "providers/workers-ai",
+          "providers/anthropic",
+          "providers/model-selection",
+          "providers/batching",
+          "providers/permanent-errors",
+        ],
+      },
+      {
+        label: "Routing",
+        items: ["routing/shims", "routing/configuration"],
+      },
+      {
+        label: "Runtime API",
+        items: ["runtime-api/locals", "runtime-api/middleware", "runtime-api/explicit-imports", "runtime-api/react-hooks"],
+      },
+      {
+        label: "CLI",
+        items: ["cli", "cli/translate", "cli/check-ui", "cli/sync-ui", "cli/translate-ui", "cli/audit-mdx"],
+      },
+      {
+        label: "Operations",
+        items: ["operations/ci", "operations/branch-dispatch", "operations/preview-isolation"],
+      },
+      { label: "Cookbook", autogenerate: { directory: "cookbook" } },
+      {
+        label: "Troubleshooting",
+        autogenerate: { directory: "troubleshooting" },
+      },
+      {
+        label: "Reference",
+        items: ["reference/exports", "reference/breaking-changes"],
+      },
+      "roadmap",
+    ],
+  },
+});
+
+export default defineConfig({
+  output: "static",
+  prefetch: {
+    prefetchAll: true,
+    defaultStrategy: "hover",
+  },
+  integrations: [
+    icon(),
+    nimbus(nimbusConfig, {
+      rules: {
+        "nimbus/frontmatter-shape": "error",
+        "nimbus/internal-link": "error",
+      },
+    }),
+  ],
+});

docs/package.json

@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
-  "description": "Starlight-based documentation site for PolyStella.",
+  "description": "Nimbus-based documentation site for PolyStella.",
   "scripts": {
     "dev": "pnpm prebuild && astro dev",
     "start": "pnpm prebuild && astro dev",
@@ -17,12 +17,24 @@
     "deploy": "wrangler deploy"
   },
   "dependencies": {
-    "@astrojs/starlight": "^0.41.3",
+    "@fontsource-variable/inter": "^5.2.8",
+    "@fontsource-variable/jetbrains-mono": "^5.2.8",
+    "@iconify-json/ph": "^1.2.0",
     "astro": "^7.0.0",
+    "astro-icon": "^1.1.0",
+    "astro-og-canvas": "^0.13.0",
+    "canvaskit-wasm": "^0.41.1",
+    "clsx": "^2.1.1",
+    "nimbus-docs": "^0.1.22",
+    "shiki": "^4.2.0",
+    "tailwind-merge": "^3.5.0",
     "sharp": "^0.35.3"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",
+    "@tailwindcss/postcss": "^4.1.4",
+    "pagefind": "^1.5.2",
+    "tailwindcss": "^4.1.4",
     "@types/node": "^26.1.0",
     "tsx": "^4.19.0",
     "typescript": "^6.0.3",

docs/postcss.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};

docs/public/_headers

@@ -4,8 +4,8 @@
 #
 # Syntax: https://developers.cloudflare.com/workers/static-assets/headers/
 #
-# CSP is intentionally omitted: Starlight ships inline
-# `<script type="module">` blocks (sidebar persistence, mobile TOC)
+# CSP is intentionally omitted: Nimbus ships inline
+# scripts for theme setup, sidebar persistence, and mobile navigation
 # that would break under a `script-src 'self'` policy. Adding CSP
 # requires per-build script hashing — a separate task.