Docs V2: new information architecture (CIP-3307)

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+# Blocking documentation checks for pull requests.
+#
+# `validate-links` also runs inside `prebuild`, so a broken link already fails
+# the Vercel build. This job exists to make that a fast, named status check
+# that branch protection can require, rather than a failure buried in a
+# deploy log.
+name: Docs
+
+on:
+  pull_request:
+    # v2 is the live documentation line. `main` is deliberately excluded: it
+    # trails v2 by ~100 commits and its bun.lock is out of sync with its
+    # package.json, so `--frozen-lockfile` fails there for reasons that have
+    # nothing to do with links. Add `main` here once #37 lands and makes it
+    # current.
+    branches: [v2]
+  push:
+    branches: [v2]
+  workflow_dispatch:
+
+# A PR that gets pushed to twice shouldn't queue behind its own stale run.
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  links:
+    name: Internal links
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          # Pinned rather than `latest` so a bun release can't turn a
+          # required check red on its own.
+          bun-version: 1.3.13
+
+      - run: bun install --frozen-lockfile
+
+      # The TypeDoc reference under content/stack/reference/stack/latest/ is
+      # gitignored and built from a clone of cipherstash/stack. Roughly 18
+      # links point into it, so without this step they all report as missing.
+      # `prebuild` generates before validating for the same reason.
+      - name: Generate the SDK reference
+        run: bun run generate-docs
+
+      - name: Validate internal links and anchors
+        run: bun run validate-links

.gitignore

@@ -39,3 +39,8 @@ content/stack/reference/drizzle/latest/
 content/stack/reference/drizzle/v*/
 .tmp-*
 .env.local
+
+# serena (local MCP tooling state)
+.serena/
+# EQL release manifest extracted by generate-eql-docs.ts (see generate-eql-api-docs.ts)
+.eql-manifest.release.json

CLAUDE.md

@@ -102,46 +102,3 @@ Fumadocs UI theme with custom purple primary color (`hsl(269, 70%, 45%)`). Dark
 ## Formatting
 
 Biome handles both linting and formatting. 2-space indentation. Biome organizes imports automatically. Run `bun run format` before committing.
-
-## Required Skills
-
-Always use the following agent skills when working in this repository. These skills contain the canonical API references and must be consulted to ensure documentation accuracy.
-
-### CipherStash Product Skills
-
-Use these skills whenever writing or editing documentation about the corresponding product area. They contain the complete, up-to-date API surface, code examples, and type signatures.
-
-| Skill | Use when editing docs in |
-|---|---|
-| `encryption` | `content/docs/encryption/` — Schema definition, encrypt/decrypt, searchable encryption, bulk operations, identity-aware encryption, error handling, migration |
-| `secrets` | `content/docs/secrets/` — Secrets SDK (`set`/`get`/`getMany`/`list`/`delete`), `stash` CLI usage, environment isolation |
-| `drizzle` | `content/docs/encryption/drizzle.mdx` — `encryptedType` column, `extractEncryptionSchema`, `createEncryptionOperators`, encrypted query operators, batched and/or, EQL migrations |
-| `supabase` | `content/docs/encryption/supabase.mdx` — `encryptedSupabase` wrapper, transparent encrypt/decrypt on insert/update/select, query filters (eq, like, gt, in, or, match), identity-aware encryption |
-| `dynamodb` | `content/docs/encryption/dynamodb.mdx` — `encryptedDynamoDB` helper, `__source`/`__hmac` attribute naming, encrypted partition/sort keys, bulk operations, audit logging |
-
-### Documentation Update Skill
-
-Use the `update-docs` skill whenever:
-- Creating new documentation pages
-- Updating existing documentation based on code changes
-- Reviewing documentation completeness for a PR
-- Scaffolding docs for a new feature
-
-The `update-docs` skill enforces the following workflow:
-
-1. **Analyze changes** — Diff the branch to identify affected files
-2. **Map to docs** — Use the code-to-docs mapping to find which MDX files need updates
-3. **Review each doc** — Walk through updates with user confirmation before editing
-4. **Validate** — Run `bun run lint` to check formatting
-5. **Commit** — Stage documentation changes
-
-#### Documentation Validation Checklist
-
-Before committing documentation changes, verify:
-
-- Frontmatter has `title` and `description`
-- Code blocks have `filename` attribute
-- TypeScript examples come first, with `switcher` and a JS variant where appropriate
-- Props/options tables are properly formatted
-- Notes use the `> **Good to know**:` callout pattern
-- `bun run lint` passes