feat: reset blocks distribution and primitive documentation

.github/workflows/ci.yml

@@ -23,15 +23,17 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
-          node-version: '22'
+          node-version: '24'
           cache: pnpm
 
       - name: Install dependencies
@@ -48,13 +50,37 @@ jobs:
 
       - name: Upload visual failure artifacts
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: playwright-results
           path: |
             apps/blocks/playwright-report
             apps/blocks/test-results
           if-no-files-found: ignore
 
+  pages:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build and verify Pages artifact
+        run: pnpm build:pages
+
 # npm releases are intentionally manual. This workflow only validates package
 # tags; it contains no registry token, trusted-publishing step, or publish job.

.github/workflows/pages.yml

@@ -6,34 +6,31 @@ on:
   workflow_dispatch: {}
 
 concurrency:
-  group: pages
-  cancel-in-progress: true
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 jobs:
   build:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
-          node-version: '22'
+          node-version: '24'
           cache: pnpm
 
-      - name: Configure GitHub Pages
-        uses: actions/configure-pages@v5
-
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
@@ -43,34 +40,24 @@ jobs:
       - name: Build static Blocks site
         run: pnpm build:pages
 
-      - name: Assemble Pages artifact
-        run: |
-          rm -rf _site
-          mkdir -p _site/r
-          cp -R apps/blocks/out/. _site/
-          cp apps/registry/public/r/*.json _site/r/
-          test -f _site/index.html
-          test -f _site/blocks/index.html
-          test -f _site/r/registry.json
-          test -f _site/r/chat.json
-          test -f _site/r/schema-builder.json
-          grep -q '/blocks/_next/' _site/index.html
-          ! grep -R 'github.io/dashboard' _site
-
       - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
-          path: _site
+          path: .artifacts/pages
 
   deploy:
+    if: github.ref == 'refs/heads/main'
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Deploy GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5
 
 # npm publication is a maintainer-run local process and is intentionally absent.

.node-version

@@ -1 +1 @@
-22
+24

AGENTS.md

@@ -16,5 +16,5 @@ This public monorepo owns the Constructive Blocks documentation, the
 
 ## Verification
 
-Use Node 22 and pnpm 10.28.0, then run `pnpm check`, `pnpm build:pages`, and
+Use Node 24 LTS and pnpm 10.28.0, then run `pnpm check`, `pnpm build:pages`, and
 `pnpm pack:local` before release-related changes.

CLAUDE.md

@@ -27,4 +27,4 @@ pnpm build:storybook
 pnpm pack:local
 ```
 
-Use Node 22 and pnpm 10.28.0.
+Use Node 24 LTS and pnpm 10.28.0.

README.md

@@ -5,7 +5,7 @@ component documentation, and published React packages.
 
 ## Workspaces
 
-- `apps/blocks` — documentation, demos, flows, and canonical block source.
+- `apps/blocks` — primitive documentation and canonical block source.
 - `apps/registry` — private builder for the `@constructive` shadcn registry.
 - `packages/ui` — the `@constructive-io/ui` npm package and UI registry source.
 - `packages/schema-builder` — the shared schema-builder npm package and registry source.
@@ -14,6 +14,20 @@ The documentation site is published at
 <https://constructive-io.github.io/blocks/>. Registry JSON is served from
 `https://constructive-io.github.io/blocks/r/{name}.json`.
 
+The npm and registry distributions are independent. After mapping the
+`@constructive` namespace in `components.json`, either surface can be used on
+its own:
+
+```bash
+pnpm add @constructive-io/ui
+pnpm dlx shadcn@4.13.1 add @constructive/button
+```
+
+The package exposes its Tailwind foundation at
+`@constructive-io/ui/globals.css`. Registry installs copy the required UI
+source and Constructive theme into the consumer and do not install the npm
+package. Registry consumers require shadcn CLI 4.13.1 or newer.
+
 ## Development
 
 ```bash
@@ -23,6 +37,9 @@ pnpm build:pages
 pnpm pack:local
 ```
 
+Development and release verification use Node 24 LTS and pnpm 10.28.0. All
+first-party executable tooling is TypeScript and runs through `tsx`.
+
 `pnpm pack:local` builds the public packages and writes publishable tarballs to
 the ignored `.artifacts/npm` directory. Consume those tarballs from downstream
 projects before publishing so validation exercises the real package contents.

apps/blocks/README.md

@@ -1,59 +1,26 @@
-# Blocks
+# Blocks docs
 
-Docs and live-demo showcase for the **Constructive blocks registry** — the `@constructive` shadcn registry of data-bound blocks and UI primitives. Every block renders as a real, interactive demo next to its install command, props, and source.
+This Next.js app is the clean documentation surface for the Constructive UI foundation. It intentionally exposes only
+the landing page, setup guidance, and the 29 base primitive pages while the complete block catalog remains available
+through the public registry.
 
-Live: **https://constructive-io.github.io/blocks/** (GitHub Pages, static export under basePath `/blocks`).
+The same primitive implementation is shown through two distribution modes:
 
-## Develop
+- npm consumers import `@constructive-io/ui/<name>` and the package stylesheet.
+- shadcn consumers install `@constructive/<name>` as editable source without preinstalling the npm package.
+
+## Development
 
 ```bash
-pnpm --filter blocks dev      # Next.js + Turbopack on http://localhost:3005
+pnpm --filter blocks dev
+pnpm --filter blocks lint:types
+pnpm --filter blocks test
+pnpm --filter blocks build:pages
 ```
 
-`predev` regenerates artifacts first, so the dev server always reflects current content.
-
-## Content model
-
-Docs are **generated from source**, not hand-written per page. Authored inputs and the UI/schema package manifests feed two generators:
-
-| Authored input | Generator | Generated output (DO NOT EDIT) |
-|----------------|-----------|--------------------------------|
-| `src/content/blocks/*.md`, `catalog/blocks.json`, all three registry manifests, sidecar `scripts/*content*.mjs` | `scripts/generate-manifest.mjs` | `src/blocks-manifest.json`, `src/lib/docs/registry-data.ts` |
-| `scripts/flows-content.mjs`, `registry.json` | `scripts/generate-flows.mjs` | `src/flows/flows.json` |
-
-Run `pnpm gen` after changing any authored input. Never edit the generated files directly — `pnpm gen:check` re-runs the generators into a temp dir and fails on any drift. It runs in `prebuild` and in CI, so drift blocks the build.
-
-## Scripts
-
-| Script | Does |
-|--------|------|
-| `gen` | Regenerate manifest, docs data, and flows |
-| `gen:check` | Fail if generated files drift from their sources |
-| `check:flows` | Validate `flows.json`, namespaced installs, and pruned SDK fixtures |
-| `fixtures:refresh` | Refresh reachable SDK fixtures from an explicit generated source root |
-| `fixtures:check` | Fail when generated SDK imports drift from committed fixtures |
-| `check:selections` | Reject empty mutation selections in `src/blocks` |
-| `lint:types` | `tsc --noEmit` |
-| `test` | `vitest run` |
-| `test:visual` | Compare the static Pages site with the Playwright screenshot baselines |
-| `build:pages` | `BLOCKS_PAGES=1 next build` — static export for GitHub Pages |
-
-## Layout
-
-| Path | Role |
-|------|------|
-| `src/blocks` | Registry-shipped app block source (auth, org, user, chat, primitives, runtime, …) |
-| `src/generated` | Pruned, committed generated SDK fixtures used only by docs and tests |
-| `src/components/docs` | Docs site chrome — nav, preview frame, code surface, demos |
-| `src/app` | Next.js App Router routes |
-| `src/content/blocks` | Authored per-block markdown (generator input) |
-| `scripts` | Generators + drift/contract guards |
-
-`src/blocks` is the source shadcn ships to consumers; everything else is the site that documents it.
-
-## Deploy
+`src/lib/base-primitives.ts` is the single docs catalog. `pnpm gen:check` validates that every entry has an npm export,
+a registry item, and a preview that imports the npm subpath. The SDK fixture and mutation-selection checks remain in
+place for the canonical block source under `src/blocks`.
 
-`.github/workflows/ci.yml` runs the repository validation suite. On `main`,
-`.github/workflows/pages.yml` repeats the validated build, assembles `_site/` —
-the Blocks site plus registry JSON under `/r/` — and deploys it to GitHub Pages.
-Neither workflow publishes npm packages.
+The static Pages build uses `/blocks` as its deployment base path. Publishing npm packages remains a separate manual
+release step.