docs(site): add the Deco Blocks docs site (Home, Docs, Under the hood, Roadmap)

.cursor/skills/deco-site-memory-debugging/SKILL.md

@@ -74,7 +74,7 @@ process slowly accumulating garbage.
 
 1. **`exceededMemory` / `exceededCpu` outcomes**, captured 100% by the tail
    worker (`deco-otel-tail`) and landing in ClickHouse `otel_logs` with
-   `Attributes['_source'] = 'tail-worker'`. See `docs/observability.md`,
+   `Attributes['_source'] = 'tail-worker'`. See `notes/observability.md`,
    "Error capture — three-channel model".
 
    ```sql
@@ -91,7 +91,7 @@ process slowly accumulating garbage.
    ```
 
    Requires the site to have adopted the tail worker per
-   `docs/tail-worker-recipe.md` (check `tail_consumers` in the site's
+   `notes/tail-worker-recipe.md` (check `tail_consumers` in the site's
    `wrangler.jsonc` first). If it hasn't, this query returns nothing —
    either onboard the recipe or fall back to the Cloudflare dashboard's
    own per-Worker Metrics panel, which shows exceeded-limit invocation

.cursor/skills/deco-site-scaling-tuning/SKILL.md

@@ -21,15 +21,15 @@ description: LEGACY. Discover optimal autoscaling parameters for a Deno/Fresh De
 > stack that plays the role this skill's methodology (find the CPU/
 > concurrency inflection point, pick a scaling target) was built for — the
 > closest current concern, per-request CPU/memory limit exhaustion, is a
-> capacity/correctness problem handled via `docs/observability.md`'s
+> capacity/correctness problem handled via `notes/observability.md`'s
 > tail-worker error-capture path (`exceededCpu`/`exceededMemory` outcomes),
 > not a scaling-parameter tuning problem.
 >
 > If you're looking at a current `@decocms/tanstack` or `@decocms/nextjs`
 > site and traffic/latency/cost seems off, this skill's `kubectl`/Prometheus
 > commands will simply fail (no cluster, no namespace, no Knative CRDs) —
-> that is expected. Use `docs/observability.md` and
-> `docs/tail-worker-recipe.md` instead. Only use this skill if you are
+> that is expected. Use `notes/observability.md` and
+> `notes/tail-worker-recipe.md` instead. Only use this skill if you are
 > specifically debugging one of the remaining Deno/Kubernetes-hosted Deco
 > sites outside this package split.
 

.github/workflows/pages.yml

@@ -0,0 +1,105 @@
+name: Docs site
+
+# Builds the Deco Blocks docs site (docs/: TanStack Start + MDX, prerendered to static HTML,
+# with a Pagefind search index). docs/ is a standalone Bun package with its own bun.lock, so
+# every step runs in docs/.
+#
+# - Pull requests that touch docs/: check, build, then upload docs/dist/client as the workflow
+#   artifact "docs-site". It's built for the root path; to view it, unzip it and serve the
+#   folder with any static server that maps /x to x.html (or copy it into docs/dist/client and
+#   run `bun run preview`). Nothing is deployed.
+# - Pushes to main that touch docs/, and manual runs on main: check, build for the /blocks/
+#   base path GitHub Pages serves this repository under, then deploy docs/dist/client to
+#   GitHub Pages. Only decocms/blocks's main branch deploys (a manual run on another branch,
+#   or a fork, only builds). Needs Pages enabled with "GitHub Actions" as its source
+#   (Settings > Pages); until then the deploy job fails, and nothing else depends on it.
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/pages.yml"
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One deploy at a time, never cancelled midway; a newer push to a PR
+# cancels that PR's older preview build.
+concurrency:
+  group: ${{ github.event_name == 'pull_request' && format('docs-site-preview-{0}', github.ref) || 'docs-site-pages' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    env:
+      # Pages serves the repository at https://<owner>.github.io/blocks/; previews build for /.
+      BASE_PATH: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' && github.repository == 'decocms/blocks' && '/blocks/' || '/' }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      # `vite build` (and its prerender) runs under Node: the vite bin is `#!/usr/bin/env node`, and
+      # TanStack Start needs Node >= 22.12 (docs/package.json "engines"). Bun installs and runs
+      # the scripts; pin Node so the build doesn't depend on whatever the runner has.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      # Same Bun as the rest of the repo (package.json "packageManager").
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Install
+        run: bun install --frozen-lockfile
+
+      - name: Check (types, content, Roadmap data)
+        run: bun run check
+
+      # vite build (prerenders every page), then 404.html, the link check and the Pagefind index.
+      - name: Build docs/dist/client
+        run: bun run build
+
+      - name: Upload the preview (pull requests)
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-site
+          path: docs/dist/client
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Upload the Pages artifact
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' && github.repository == 'decocms/blocks'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/dist/client
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' && github.repository == 'decocms/blocks'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      # The build hardcodes the /blocks/ base path, so nothing uses this step's outputs; it
+      # checks Pages is set up before deploying.
+      - uses: actions/configure-pages@v6
+
+      - id: deployment
+        uses: actions/deploy-pages@v5

CLAUDE.md

@@ -90,7 +90,7 @@ Keys are **per deployment id** (commit sha), never a single mutable pointer —
 
 `decoVitePlugin` additionally stubs `blocks.gen` out of the server bundle so the KV copy is the isolate's only one, which is the fix for the decofile being resident three times (bundled graph + KV graph + escaped JSON string ≈ 27MB for a 9.2MB decofile, against a 128MB cap with no GC knob). **In that mode the bundled snapshot is not a fallback** — `ensureBlocksHydrated` 5xxs rather than serve an empty site the edge would cache. So it is gated on the deploy pipeline declaring it seeds `decofile:<id>` before activation (`DECO_SEEDED_DEPLOY`, default `fastDeploy: "auto"`); CF Workers Builds and a manual `wrangler deploy` never declare it and keep the bundled snapshot.
 
-This is deliberately **not** available in `@decocms/nextjs` — edge KV + Cloudflare Workers caching is a `tanstack`-specific concern, not something `next`'s Node/RSC target needs or should carry. Read path: `packages/blocks/src/cms/blockSource.ts`, `packages/blocks-admin/src/admin/decofile.ts` (`setFastDeployKVGetter` — dependency injection so `admin` doesn't need a hard KV dependency), `packages/tanstack/src/setupFastDeploy.ts`. Full guide + cross-repo contracts: [`docs/fast-deploy.md`](./docs/fast-deploy.md).
+This is deliberately **not** available in `@decocms/nextjs` — edge KV + Cloudflare Workers caching is a `tanstack`-specific concern, not something `next`'s Node/RSC target needs or should carry. Read path: `packages/blocks/src/cms/blockSource.ts`, `packages/blocks-admin/src/admin/decofile.ts` (`setFastDeployKVGetter` — dependency injection so `admin` doesn't need a hard KV dependency), `packages/tanstack/src/setupFastDeploy.ts`. Full guide + cross-repo contracts: [`notes/fast-deploy.md`](./notes/fast-deploy.md).
 
 ## Admin Protocol
 

FRAMEWORK_TODO.md

@@ -22,7 +22,7 @@ Issues and feature gaps discovered during real site migration work. Trimmed duri
 
 ### `useScript(fn)` hydration mismatch warning — still present
 - `useScript` calls `fn.toString()`, which produces different output in SSR vs. client builds (minification, variable renaming). The `[useScript] Using fn.toString() for "..."` warning still fires in real dev sessions (confirmed live in production storefront dev logs during the Next.js/split-package migration work).
-- **Ideal**: ship `inlineScript(str)` accepting a plain string constant, or make `useScript` stable across builds. See also `docs/next-steps-tanstack-native.md`'s proposal #2, which covers the same gap in more detail — don't build both independently.
+- **Ideal**: ship `inlineScript(str)` accepting a plain string constant, or make `useScript` stable across builds. See also `notes/next-steps-tanstack-native.md`'s proposal #2, which covers the same gap in more detail — don't build both independently.
 
 ### Route files are still boilerplate
 - `__root.tsx`, `index.tsx`, `$.tsx`, `deco/meta.ts`, `deco/invoke.$.ts`, `deco/render.ts` are scaffolded identically per site by the migration script.
@@ -74,7 +74,7 @@ Issues and feature gaps discovered during real site migration work. Trimmed duri
 
 ## Fast Deploy (KV-first content) — cross-repo follow-ups
 
-Framework + CI scripts for fast-deploy landed in this repo (see [`docs/fast-deploy.md`](./docs/fast-deploy.md)). Remaining work lives in **other** repos:
+Framework + CI scripts for fast-deploy landed in this repo (see [`notes/fast-deploy.md`](./notes/fast-deploy.md)). Remaining work lives in **other** repos:
 
 - **admin.deco.cx (Studio)**: publish a delta envelope to `/.decofile` + call `/_cache/purge`; gate on a per-site `fast_deploy_enabled` capability; dispatch the deco-sync-bot commit off the critical path.
 - **Site CI**: provision a KV namespace + `DECO_KV` binding; add a `sync-content-to-kv.yml` workflow; gate `deploy.yml` to code-only changes.