docs: add Cloudflare Nimbus documentation site

.codacy.yaml

@@ -10,3 +10,11 @@
 # matching eslint ignore.
 exclude_paths:
   - 'npm/**'
+  # Exclude the whole Nimbus docs site. Its TS/Astro source is scaffold-owned
+  # code written by `@cloudflare/create-nimbus-docs` and kept aligned with the
+  # upstream template (so `nimbus-docs diff` stays clean), and its MDX content
+  # is linted by `nimbus-docs lint`, which Codacy has no MDX-aware tool for. The
+  # site has its own gate (`astro check` + `nimbus-docs check/lint`) and, like
+  # npm/, is excluded from the JS app's static analysis. See the matching
+  # `docs/**` ignore in eslint.config.ts.
+  - 'docs/**'

.github/workflows/docs.yml

@@ -0,0 +1,93 @@
+name: Docs
+
+# Builds the Nimbus docs site (docs/) on every PR that touches it, and
+# deploys it to Cloudflare (Workers static assets, docs/wrangler.jsonc) on main.
+#
+# Deploy needs two repository secrets:
+#   CLOUDFLARE_API_TOKEN  — "Edit Cloudflare Workers" template. The custom
+#                            domain route in wrangler.jsonc also needs
+#                            Zone:DNS:Edit on the pleaseai.dev zone.
+#   CLOUDFLARE_ACCOUNT_ID
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - .github/workflows/docs.yml
+  pull_request:
+    paths:
+      - 'docs/**'
+      - .github/workflows/docs.yml
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      # CI runs no git hooks, so skip the cargo:hk source build (matches ci.yml).
+      MISE_DISABLE_TOOLS: cargo:hk
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - name: Setup mise (node, bun)
+        uses: jdx/mise-action@e6a8b3978addb5a52f2b4cd9d91eafa7f0ab959d # v4.2.0
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Build
+        run: bun run build
+
+      - name: Nimbus preflight
+        run: bun run check
+
+      - name: Upload site
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: docs-dist
+          path: docs/dist
+          retention-days: 7
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: docs
+      url: https://code-search.pleaseai.dev
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - name: Download site
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: docs-dist
+          path: docs/dist
+
+      - name: Deploy to Cloudflare
+        uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          workingDirectory: docs
+          command: deploy

.gitignore

@@ -58,3 +58,8 @@ bun.lockb
 
 # Generated npm platform packages (release artifact)
 npm/dist/
+
+# Docs site (Cloudflare Nimbus / Astro / Wrangler) build state
+docs/.astro/
+docs/.nimbus/
+docs/.wrangler/

CLAUDE.md

@@ -38,6 +38,10 @@ The implementation is **Rust** (a Cargo workspace). A thin Node/Bun toolchain re
 - **JS tooling** (no TS implementation): Bun ≥1.3.10 / Node ≥22 (the `engines` floor; `mise.toml` pins 1.3.14 / 24 for dev + CI). `@pleaseai/eslint-config` (wraps `@antfu/eslint-config`) lints `npm/` JS + `eslint.config.ts`; `tsc --noEmit` typechecks. No semicolons, single quotes, 2-space indent.
 - **Toolchain manager**: `mise.toml` pins `node`/`bun` + `hk` (the git hook manager); the Rust channel stays owned by `rust-toolchain.toml`. `mise install` provisions tools and runs `hk install --mise`, wiring git hooks from `hk.pkl` (pre-commit: eslint on `npm/` JS + `rustfmt` on staged `.rs`; commit-msg: conventional-commit check). `mise run check` is the full local gate. On Intel macOS hk is pinned via the `cargo:` backend (aqua has no darwin-amd64).
 
+### Docs site (`docs/`)
+
+`docs/` is a standalone [Cloudflare Nimbus](https://nimbus-docs.com) site (Astro 7 + Tailwind v4, `@cloudflare/nimbus-docs` pinned at `0.12.0`) published at `https://code-search.pleaseai.dev`. Content lives in `docs/src/content/docs/*.mdx` (flat slugs; the sidebar groups are declared in `docs/astro.config.ts`), shared snippets in `docs/src/content/partials/`. It has its own `bun.lock` and gate (`bun run typecheck && bun run build && bun run check` inside `docs/`, or `mise run docs:build`); root eslint ignores `docs/**` so scaffold-owned files stay diffable via `nimbus-docs diff`. Deploys as Workers static assets through `.github/workflows/docs.yml` (`wrangler deploy` on `main`). Pages mirror the README, so a README change that touches user-facing behavior should update the matching page too.
+
 ## Commands
 
 ```bash

docs/.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+dist/
+.astro/
+.wrangler/
+
+.env
+.env.local
+.env.*.local
+.env.production
+.dev.vars
+.dev.vars.*
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+.DS_Store
+.idea/
+.vscode/*
+!.vscode/extensions.json

docs/AGENT.md

@@ -0,0 +1,109 @@
+# This Nimbus docs site
+
+Astro-based docs. The `nimbus-docs` package handles content schemas, sidebar/TOC, MDX→markdown, build hooks, and the `nimbus` CLI. Everything in `src/` is yours to edit.
+
+## File layout
+
+```
+astro.config.ts              # imports nimbus + defineNimbusConfig
+src/
+├── components.ts            # MDX globals registry — every component used in .mdx must be listed
+├── components/              # AgentDirective, Header, Render + ui/<slug>/
+├── content/
+│   ├── docs/*.mdx
+│   └── partials/*.mdx       # referenced via <Render file="..." />
+├── content.config.ts        # registers docsCollection() + partialsCollection()
+├── layouts/                 # BaseLayout (NimbusHead), DocsLayout (sidebar/TOC/breadcrumbs)
+├── lib/cn.ts                # Tailwind className merger
+├── pages/
+│   ├── [...slug].astro
+│   ├── [...slug]/index.md.ts   # per-page markdown alternate
+│   ├── llms.txt.ts
+│   ├── og.png.ts                # site-level OG card
+│   ├── og/
+│   │   ├── _og-card-config.ts   # shared OG theme tokens (underscore = not a route)
+│   │   └── [...slug].ts         # per-page OG cards
+│   └── robots.txt.ts
+└── styles/                  # globals.css, prose.css
+```
+
+Cloudflare deploys also have `wrangler.jsonc` at the project root.
+
+## Writing docs
+
+Frontmatter validates against `docsSchema` (`nimbus-docs/schemas`). Required: `title`.
+
+```mdx
+---
+title: My page
+description: One-line summary.
+---
+
+Content here. The page H1 comes from `title` — don't repeat it in the body.
+
+## Section heading
+```
+
+Rules:
+
+- **Components must be PascalCase and registered in `src/components.ts`.** A pre-build validator catches typos with a "did you mean" hint.
+- **Partials use `<Render file="..." />`.** Don't import `.mdx` directly. Shared content lives in `src/content/partials/<slug>.mdx`.
+- **Icons use `astro-icon` + Phosphor.** `<Icon name="ph:<glyph>" class="w-4 h-4" />` from `astro-icon/components`. Glyphs: [phosphoricons.com](https://phosphoricons.com).
+- **Don't remove `<AgentDirective />` from `BaseLayout.astro`.** It points agents at `/llms.txt`.
+
+## Adding things
+
+| Goal | Action |
+|---|---|
+| New doc page | Create `src/content/docs/<slug>.mdx`. Sidebar picks it up. |
+| New partial | Create `src/content/partials/<slug>.mdx`. Use via `<Render file="<slug>" />`. |
+| UI from registry | `bun run nimbus-docs add <slug>`. Register in `src/components.ts` if used in MDX. |
+| Feature recipe | `bun run nimbus-docs add <feature-slug>`. Pipe the printed brief to your agent. |
+| Check it builds | `bun run nimbus-docs check` — build-free preflight (env + structure + authoring + types). `--json` for an agent loop, `--fix` to repair what's safe. |
+| Custom page route | Add a file under `src/pages/`. |
+| Custom OG style | Edit `src/pages/og/_og-card-config.ts`. |
+| Check for updates | `bun run nimbus-docs outdated` — starter files behind their tag + registry components behind. |
+| Upgrade a starter file | `bun run nimbus-docs diff <file>` to review, `diff --apply <file>` to pull a clean upstream change. |
+| Upgrade a registry component | `bun run nimbus-docs add <slug> --overwrite`, then review with `git diff`. |
+
+List installable items: `bun run nimbus-docs list`.
+
+## Audit this site
+
+Start with `bun run nimbus-docs check --json`. It runs the environment, structural, authoring, and type checks build-free — config validity, `site` placeholder, route collisions, MDX component resolution, the lint rules, and a `tsc` type-check — and returns three top-level signals plus per-scope detail:
+
+- **`status`** (`passed` | `failed` | `partial`) and **`readiness`** (`buildable` | `blocked` | `unknown`) are the primary signals. `status` is the whole-run verdict; `readiness` answers "does env + structure say it builds?". `ok` (=== zero errors) is kept for back-compat only.
+- **`findings[{scope,code,severity,file,line,message,fixable,fix}]`** are problems we evaluated. Apply each `fix` (or `check --fix`).
+- **`scopes[].notes[{code,reason,requiresBuild?,requiresInput?}]`** are checks we *couldn't* evaluate yet (e.g. types before a build). A note is never a finding and never carries a `fix` — you resolve it by making the missing thing exist (usually a build), not by `--fix`. `summary.notes` counts them.
+
+Loop terminates on `status !== "failed" && summary.fixable === 0` — a `partial` run with nothing left to fix is a **stop** (optionally build, then re-check), not a `--fix` retry. Exit is `1` only when `status` is `"failed"`. For full coverage (types + link-checking) run a build first, then `check` again.
+
+Then walk the categories below for what `check` doesn't cover yet — route-file existence, registry hygiene, the AI surface, post-build search, and Cloudflare config. Emit findings as:
+
+```
+- [error|warn|info] FILE:LINE — what + why + fix.
+```
+
+End with `Summary: N errors, N warnings.`
+
+- **Config** — `astro.config.ts` calls `nimbus(defineNimbusConfig({ ... }))`; `site` is set; `editPattern` (if set) contains `{path}`; `output:` matches the deploy target.
+- **Content** — `content.config.ts` registers `docsCollection()` (and `partialsCollection()` if used); every `.mdx` is inside a registered collection; frontmatter validates.
+- **Sidebar** — every sidebar ref resolves to a content entry; no orphans; no slug collisions.
+- **MDX** — every PascalCase component in `*.mdx` is registered; every `<Render file=...>` resolves; code-fence languages are valid.
+- **Routes** — `llms.txt.ts`, `robots.txt.ts`, `[...slug]/index.md.ts`, `og.png.ts`, `og/[...slug].ts` all exist.
+- **Registry hygiene** — every `src/components/ui/<slug>/` is either MDX-registered or imported in `src/`; transitive deps (`lib/cn.ts`, etc.) exist.
+- **AI surface** — `<AgentDirective />` renders in `BaseLayout.astro`; doc `<head>` has `<link rel="alternate" type="text/markdown" ...>`.
+- **Search** — `data-pagefind-body` is on the docs main wrapper; after `bun run build`, `dist/pagefind/` exists with ≥1 indexed page.
+- **Cloudflare** (if applicable) — `wrangler.jsonc` has `name`, `compatibility_date`, `assets.directory = "./dist"`, `not_found_handling`.
+
+## Don't
+
+- Hand-add components under `src/components/ui/` that exists in the nimbus-docs registry — use `nimbus-docs add` so deps resolve.
+- Import `.mdx` files directly — use `<Render file="..." />`.
+- Attach remark/rehype plugins via `mdx({ remarkPlugins })` — Sätteri silently drops them. Framework-side transformations run as content passes.
+- Remove `<AgentDirective />` unless asked.
+- Edit `src/components.ts` to bypass registration — if a component is used in `.mdx`, register it.
+
+## Project home
+
+[nimbus-docs.com](https://nimbus-docs.com)

docs/astro.config.ts

@@ -0,0 +1,73 @@
+import { defineConfig } from "astro/config";
+import tailwindcss from "@tailwindcss/vite";
+import nimbus, {
+  defineConfig as defineNimbusConfig,
+} from "@cloudflare/nimbus-docs";
+import { tableScroll } from "@cloudflare/nimbus-docs/markdown";
+
+const nimbusConfig = defineNimbusConfig({
+  // Canonical origin — the repository homepage. Drives canonical URLs,
+  // absolute OG image URLs, robots.txt, sitemap, and the links in /llms.txt.
+  site: "https://code-search.pleaseai.dev",
+  title: "csp",
+  description:
+    "Code Search Please — fast and accurate hybrid code search for agents. A Rust port of MinishLab/semble.",
+  locale: "en",
+  github: "https://github.com/pleaseai/code-search",
+  editPattern: "https://github.com/pleaseai/code-search/edit/main/docs/{path}",
+  socialImageAlt: "csp — Code Search Please documentation",
+  sidebar: {
+    // The content directory is flat (clean URLs like /installation); the
+    // rail is grouped here instead. Array position is the rail order.
+    items: [
+      {
+        label: "Get started",
+        items: ["introduction", "installation", "quickstart"],
+      },
+      {
+        label: "Agent setup",
+        items: ["mcp-server", "plugin", "agents-md", "sub-agent"],
+      },
+      {
+        label: "Reference",
+        items: ["cli", "library", "how-it-works", "development"],
+      },
+    ],
+  },
+});
+
+export default defineConfig({
+  // nimbus:adapter
+  output: "static",
+  // Tailwind v4 via its Vite plugin (the integration Astro recommends for
+  // Tailwind v4 — replaces the PostCSS plugin, which doesn't build under
+  // Astro 7's Vite 8 bundler).
+  vite: {
+    plugins: [tailwindcss()],
+  },
+  // Hover-prefetch link targets so full-page navigations feel instant without
+  // a client-side router.
+  prefetch: {
+    prefetchAll: true,
+    defaultStrategy: "hover",
+  },
+  integrations: [
+    nimbus(nimbusConfig, {
+      // Authoring rules are opt-in by design — your repo, your taste. The
+      // two below are the load-bearing pair: frontmatter has to validate
+      // against the content schema for the page to render properly, and
+      // broken internal links are 404s for your readers. Add the others
+      // (heading hierarchy, code-block language, style, etc.) when you're
+      // ready to enforce them — see `nimbus-docs lint --help`.
+      rules: {
+        "nimbus/frontmatter-shape": "error",
+        "nimbus/internal-link": "error",
+      },
+      // Wrap wide tables so they scroll instead of overflowing the page
+      // (styled by `.nb-table-scroll` in src/styles/prose.css).
+      markdown: {
+        hastPlugins: [tableScroll()],
+      },
+    }),
+  ],
+});