Docs V2: new information architecture (CIP-3307)

IA.md

@@ -0,0 +1,192 @@
+# Docs V2 — Information Architecture & migration checklist
+
+Living checklist for the docs overhaul. Tracked in Linear under
+[CIP-3307](https://linear.app/cipherstash/issue/CIP-3307); the full IA rationale
+(design principles, audience doors, correctness strategy) lives in
+`CipherStash docs IA v1.md` in the content repo. **Tick items here as they land
+on the `v2` branch.** Legend: `[ ]` todo · `[x]` done · 🚧 stub exists · ⛔ blocked
+on a product decision (see CIP-3307 checklist).
+
+## How this branch works
+
+- New IA lives in `content/docs`, served from the site root (`/docs/<section>/…`).
+- The legacy tree (`content/stack`) is served alongside it at `/docs/stack/…`
+  until every section migrates, then deleted (CIP-3335).
+- The full legacy→v2 redirect map is `v2-redirects.mjs`, gated behind
+  `ENABLE_V2_REDIRECTS=1` (flipped on at merge). `bun run validate-redirects`
+  enforces that every legacy page has a mapping.
+- Frontmatter facets (`type`, `components`, `audience`, `integration`,
+  `verifiedAgainst`, `reviewBy`) are defined in `source.config.ts` (`v2docs`).
+- **Moving a page** = move the file into `content/docs`, update its facets,
+  fix inbound links, confirm its `v2-redirects.mjs` entry, tick it here.
+
+## URL conventions
+
+Lowercase, hyphens, no trailing slashes, no version numbers in paths.
+Integrations are **flat** (no category segment). Error pages (future, miette)
+live at `/docs/errors/<code>` — permanent, never restructured (CIP-3338).
+
+---
+
+## Get started — CIP-3327
+
+- [x] Section scaffold 🚧
+- [ ] `/get-started/what-is-cipherstash` — mental model, components map, audience router
+- [ ] `/get-started/quickstart` — rewritten on EQL v3 (fixes `cs_match_v1`, broken scaffold imports)
+- [ ] `/get-started/choose-your-stack` — static matrix v1 (platform × ORM × auth)
+- [ ] `/get-started/examples` — runnable example apps index
+- [ ] `/docs` landing page 🚧 — now `content/docs/index.mdx` rendered inside the docs
+      nav (the old standalone `(home)` route is deleted; recoverable from git history).
+      CIP-3327 refines the content (what-is + audience router)
+
+## Integrations — CIP-3328 (Supabase), CIP-3330 (auth), CIP-3336 (rest)
+
+- [x] Section scaffold 🚧 (index + supabase stub with facet exemplar)
+- [ ] `/integrations` index — category grid w/ setup badges
+- [ ] `/integrations/supabase` — flagship tutorial (CIP-3328)
+- [ ] `/integrations/supabase/database`
+- [ ] `/integrations/supabase/auth`
+- [ ] `/integrations/supabase/dashboard-experience` — Table Editor, expose eql schema
+- [ ] ⛔ `/integrations/supabase/edge-functions` — pending Deno/FFI answer
+- [ ] ⛔ `/integrations/supabase/realtime` — pending product verification
+- [ ] `/integrations/drizzle` — merge the two divergent Drizzle pages
+- [ ] `/integrations/prisma-next`
+- [ ] `/integrations/aws/rds-aurora` — Proxy path
+- [ ] `/integrations/aws/dynamodb`
+- [ ] `/integrations/clerk`
+- [ ] `/integrations/auth0` — end-to-end example (Clerk parity)
+- [ ] `/integrations/okta` — end-to-end example (Clerk parity)
+- [ ] `/integrations/nextjs`
+- [ ] `/integrations/typescript` — thin router to Stack SDK reference
+- [ ] `/integrations/serverless` — Vercel/Lambda, bundling, CS_CONFIG_PATH
+- [ ] `/integrations/docker`
+- [ ] ⛔ `/integrations/edge-workers` — pending Deno/workerd answer
+
+## Concepts — CIP-3333 (searchable-encryption), others per section tickets
+
+- [x] Section scaffold 🚧
+- [ ] `/concepts/privacy-first-design`
+- [ ] `/concepts/application-level-encryption` — vs TDE/pgcrypto/RLS
+- [ ] `/concepts/searchable-encryption` — REWRITE with honest leakage model (canonical leakage page)
+- [ ] `/concepts/eql` — the typed-column model (declare capability in the schema)
+- [ ] `/concepts/key-management` — per-value keys, rotation, crypto-shredding
+- [ ] `/concepts/identity-aware-encryption` — lock contexts, CTS (CIP-3330)
+- [ ] `/concepts/threat-modelling`
+
+## Comparisons — CIP-3333
+
+- [x] Section scaffold 🚧
+- [ ] `/compare/aws-kms` (port)
+- [ ] `/compare/fhe` (port)
+- [ ] `/compare/rls-and-tde` (new — expand the Supabase-listing RLS contrast)
+- [ ] `/compare/hashicorp-vault` (in flight on `docs/vault-comparison` branch — land there or here, then port)
+
+## Guides
+
+- [x] Section scaffold 🚧 (development, migration, deployment, troubleshooting)
+- [ ] `/guides/development/local-setup` — profiles, device auth, workspaces, keys
+- [ ] `/guides/development/schema-design` — which encrypted type/variant per column (CIP-3327)
+- [ ] `/guides/development/testing-and-ci` (port deploy/testing)
+- [ ] `/guides/development/team-onboarding` (port)
+- [ ] `/guides/migration/encrypt-existing-data` — the backfill guide, runnable (CIP-3329)
+- [ ] ⛔ `/guides/migration/upgrading-from-eql-v2` — REQUIRED; mechanics pending product answer (CIP-3329)
+- [ ] `/guides/migration/adopting-incrementally` (CIP-3329)
+- [ ] `/guides/migration/key-rotation-operations`
+- [ ] `/guides/deployment/going-to-production` (port)
+- [ ] `/guides/deployment/serverless-and-bundling` (merge bundling + sst)
+- [ ] `/guides/deployment/proxy-deployment` (merge proxy Docker + aws-ecs)
+- [ ] `/guides/troubleshooting` index — symptom-based router
+- [ ] `/guides/troubleshooting/query-performance` — seq-scan diagnosis, typed-operand gotcha
+- [ ] `/guides/troubleshooting/runtime-errors`
+- [ ] `/guides/troubleshooting/cli` (port)
+- [ ] `/guides/troubleshooting/proxy` (port)
+
+## Architecture & security — CIP-3331, CIP-3332 (compliance)
+
+- [x] Section scaffold 🚧
+- [ ] `/security/architecture` — ONE reconciled ZeroKMS mechanism story (kills the 3 conflicting accounts)
+- [ ] `/security/zerokms`
+- [ ] `/security/cts` — auth layer architecture (CIP-3330)
+- [ ] `/security/stack-sdk`
+- [ ] `/security/proxy`
+- [ ] `/security/threat-scenarios`
+- [ ] ⛔ `/security/availability-and-continuity` — DR (port) + SLA + exit story; pending SLA answer
+- [ ] ⛔ `/security/audit-logging` — pending retention answer
+- [ ] ⛔ `/security/key-ownership` — BYOK/self-hosted; pending product answer
+- [ ] `/security/compliance` index — framework mapping (port, good)
+- [ ] `/security/compliance/hipaa` — BAA scope, §164.312 mapping (CIP-3332)
+- [ ] `/security/compliance/soc2` — verify Type II report exists
+- [ ] `/security/compliance/gdpr`
+
+## Solutions
+
+- [x] Section scaffold 🚧
+- [ ] `/solutions/protecting-pii` (new)
+- [ ] `/solutions/healthcare-hipaa` (new; pairs with compliance/hipaa)
+- [ ] `/solutions/ai-and-rag` (port use-cases/ai-rag)
+- [ ] `/solutions/data-residency` (port)
+- [ ] `/solutions/provable-access` (port)
+
+## Reference
+
+- [x] Section scaffold 🚧 (eql, stack, auth, cli, proxy, workspace)
+- **EQL (v3 rewrite — CIP-3326; Tailwind-shaped: install → core concepts → type
+  categories → indexes → query patterns). Anti-drift rule: shared mechanics
+  (typed operands, blockers, envelope, variant model, ORE-equality) live ONLY in
+  core-concepts — category/query pages link, never restate:**
+- [x] `/reference/eql` — install (single SQL file, permissions split, dbdev, Docker)
+- [x] `/reference/eql/core-concepts` — variant model, payload anatomy (absorbs
+      cipher-cell), typed-operand rule, fail-loud blockers, term leakage pointer
+- [x] `/reference/eql/numbers` — int*/float*/numeric
+- [x] `/reference/eql/dates-and-times` — date/timestamp (same traits as numbers,
+      distinct semantics)
+- [x] `/reference/eql/text` — all six text variants; owns the no-LIKE treatment
+- [x] `/reference/eql/json` — ste_vec + sv payload shape + containment/path queries
+- [x] `/reference/eql/booleans` — storage-only variants (bool has only that one)
+- [x] `/reference/eql/indexes` — functional indexes on extractors; Supabase-compatible
+- [x] `/reference/eql/filtering` — =, IN, ranges, token match, containment
+- [x] `/reference/eql/sorting` — ORDER BY, extractor sort-key form, pagination
+- [x] `/reference/eql/grouping-and-aggregates` — GROUP BY/DISTINCT, min/max, no SUM/AVG
+- [x] `/reference/eql/joins` — equijoins, the same-keyset constraint
+- [ ] ⛔ `/reference/eql/query-performance` — port the EQL repo performance guide once
+      rewritten for v3 upstream (v3 branch folded it into database-indexes.md; verify
+      nothing from the v2 guide on main was lost) — see CIP-3351
+- **Stack SDK:**
+- [ ] `/reference/stack` — client + configuration (port encryption/* pages)
+- [ ] `/reference/stack/schema`
+- [ ] `/reference/stack/encrypt-decrypt` (+ bulk, models)
+- [ ] `/reference/stack/supabase` — THE canonical `encryptedSupabase` page, ONE signature (CIP-3328)
+- [ ] `/reference/stack/drizzle-operators`
+- [ ] `/reference/stack/errors` — port error-handling; miette catalog later (CIP-3338)
+- [ ] `/reference/stack/upgrading-from-protect` (retitled package-rename guide)
+- **Auth (CIP-3330):**
+- [ ] `/reference/auth/lock-contexts`
+- [ ] `/reference/auth/cts-tokens`
+- [ ] `/reference/auth/oidc-configuration`
+- [ ] `/reference/auth/access-keys` (+ clients)
+- **CLI / Proxy / Workspace:**
+- [ ] `/reference/cli/*` (port 9 pages)
+- [ ] `/reference/proxy/*` (configuration, message-flow, multitenant, errors)
+- [ ] `/reference/workspace/billing` + `/members` + `/configuration`
+- **Cross-cutting:**
+- [ ] `/reference/benchmarks` — listing numbers + methodology (CIP-3334)
+- [ ] `/reference/agent-skills` (port; expand per CIP-3339)
+- [ ] `/reference/glossary` (port)
+- [ ] Repoint `scripts/generate-docs.ts` TypeDoc output → `content/docs/reference/stack`
+
+## Infrastructure / final pass
+
+- [x] `v2` branch + this checklist
+- [x] `v2docs` collection + facet schema (`source.config.ts`)
+- [x] Root catch-all routes (`src/app/[...slug]`), llms.mdx mirror, sitemap/llms.txt include v2
+- [x] `v2-redirects.mjs` (flag-gated) + `validate-redirects` gate in prebuild
+- [x] `/quickstart` vanity redirect
+- [ ] OG images for v2 pages (route only covers legacy tree)
+- [ ] Correctness CI: snippet type-checking, SQL-vs-EQL-Docker, terminology lint (CIP-3337)
+- [ ] llms.txt curation + Cloudflare AI crawl policy + md-degradation check (CIP-3339)
+- [ ] ⛔ EQL 3.0.0 release alignment (CIP-3352, blocks CIP-3335) — the EQL reference
+      documents the release as decided, ahead of the eql_v3 branch: payload `v: 3`,
+      OPE SEM specifier, Docker tag `:17-3.0.0`, `version()` output, schema files.
+      Each must land upstream or be walked back in the docs before merge
+- [ ] Flip `ENABLE_V2_REDIRECTS=1`, delete `content/stack` + `/stack` routes + legacy loader (CIP-3335)
+- [ ] Consistency sweep + Supabase listing v3 revision (CIP-3335)

content/docs/compare/index.mdx

@@ -0,0 +1,9 @@
+---
+title: Comparisons
+description: "How CipherStash compares to other approaches to protecting data."
+type: concept
+---
+
+This section is being built as part of the docs V2 overhaul ([CIP-3307](https://linear.app/cipherstash/issue/CIP-3307)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, current documentation lives in the [existing docs](/stack).

content/docs/compare/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Comparisons",
+  "icon": "Scale",
+  "pages": ["..."]
+}

content/docs/concepts/index.mdx

@@ -0,0 +1,9 @@
+---
+title: Concepts
+description: "How CipherStash works and how to think about searchable encryption, keys, and identity."
+type: concept
+---
+
+This section is being built as part of the docs V2 overhaul ([CIP-3307](https://linear.app/cipherstash/issue/CIP-3307)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, current documentation lives in the [existing docs](/stack).

content/docs/concepts/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Concepts",
+  "icon": "Lightbulb",
+  "pages": ["..."]
+}

content/docs/concepts/searchable-encryption.mdx

@@ -0,0 +1,9 @@
+---
+title: Searchable encryption
+description: "How querying encrypted data works, and exactly what each index term reveals."
+type: concept
+---
+
+This page is being rewritten as part of the docs V2 overhaul ([CIP-3333](https://linear.app/cipherstash/issue/CIP-3333)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, the current version lives in the [existing docs](/stack/cipherstash/encryption/searchable-encryption).

content/docs/get-started/index.mdx

@@ -0,0 +1,9 @@
+---
+title: Get started
+description: "What CipherStash is, a 10-minute quickstart, and how to choose your integration path."
+type: tutorial
+---
+
+This section is being built as part of the docs V2 overhaul ([CIP-3307](https://linear.app/cipherstash/issue/CIP-3307)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, current documentation lives in the [existing docs](/stack).

content/docs/get-started/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Get started",
+  "icon": "Rocket",
+  "pages": ["..."]
+}

content/docs/guides/deployment/index.mdx

@@ -0,0 +1,8 @@
+---
+title: Deployment
+description: "Deployment documentation — being built as part of the docs V2 overhaul."
+---
+
+This section is being built as part of the docs V2 overhaul ([CIP-3307](https://linear.app/cipherstash/issue/CIP-3307)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, current documentation lives in the [existing docs](/stack).

content/docs/guides/deployment/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Deployment",
+  "pages": ["..."]
+}

content/docs/guides/development/index.mdx

@@ -0,0 +1,8 @@
+---
+title: Development
+description: "Development documentation — being built as part of the docs V2 overhaul."
+---
+
+This section is being built as part of the docs V2 overhaul ([CIP-3307](https://linear.app/cipherstash/issue/CIP-3307)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, current documentation lives in the [existing docs](/stack).

content/docs/guides/development/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Development",
+  "pages": ["..."]
+}

content/docs/guides/index.mdx

@@ -0,0 +1,9 @@
+---
+title: Guides
+description: "Task-oriented guides: development workflow, data migration, deployment, and troubleshooting."
+type: guide
+---
+
+This section is being built as part of the docs V2 overhaul ([CIP-3307](https://linear.app/cipherstash/issue/CIP-3307)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, current documentation lives in the [existing docs](/stack).

content/docs/guides/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Guides",
+  "icon": "Wrench",
+  "pages": ["..."]
+}

content/docs/guides/migration/index.mdx

@@ -0,0 +1,8 @@
+---
+title: Data migration
+description: "Data migration documentation — being built as part of the docs V2 overhaul."
+---
+
+This section is being built as part of the docs V2 overhaul ([CIP-3307](https://linear.app/cipherstash/issue/CIP-3307)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, current documentation lives in the [existing docs](/stack).

content/docs/guides/migration/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Data migration",
+  "pages": ["..."]
+}

content/docs/guides/troubleshooting/index.mdx

@@ -0,0 +1,8 @@
+---
+title: Troubleshooting
+description: "Troubleshooting documentation — being built as part of the docs V2 overhaul."
+---
+
+This section is being built as part of the docs V2 overhaul ([CIP-3307](https://linear.app/cipherstash/issue/CIP-3307)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, current documentation lives in the [existing docs](/stack).

content/docs/guides/troubleshooting/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Troubleshooting",
+  "pages": ["..."]
+}

content/docs/guides/troubleshooting/query-performance.mdx

@@ -0,0 +1,9 @@
+---
+title: Query performance
+description: "Diagnosing and fixing slow queries on encrypted columns."
+type: guide
+---
+
+This page is being built as part of the docs V2 overhaul ([CIP-3351](https://linear.app/cipherstash/issue/CIP-3351)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, the EQL reference covers the essentials: [Indexes](/reference/eql/indexes) walks through `EXPLAIN` verification and large-table index builds, and [Sorting](/reference/eql/sorting) covers extractor-form sort keys.

content/docs/index.mdx

@@ -0,0 +1,38 @@
+---
+title: CipherStash Docs
+seoTitle: CipherStash Docs — Searchable encryption for Postgres
+description: "Searchable field-level encryption, identity-bound keys, and cryptographic audit trails — built into your existing Postgres stack."
+type: concept
+audience: [developer, cto, ciso]
+---
+
+CipherStash encrypts your data at the field level. Every value gets its own
+key, bound to an identity — and the ciphertext stays queryable in Postgres.
+A breach, a compromised agent, a curious insider: they all see ciphertext
+with no key.
+
+## Start here
+
+<Cards>
+  <Card title="Get started" href="/get-started" description="What CipherStash is and your first encrypted fields in 10 minutes." />
+  <Card title="Quickstart" href="/stack/quickstart" description="Encrypt, store, query, and decrypt your first fields in any Postgres." />
+  <Card title="Supabase" href="/integrations/supabase" description="Searchable, application-level encryption for your Supabase project." />
+  <Card title="Agent skills" href="/stack/reference/agent-skills" description="CipherStash knowledge for Cursor, Copilot, and Claude Code." />
+</Cards>
+
+## Browse the docs
+
+<Cards>
+  <Card title="Integrations" href="/integrations" description="Platforms, ORMs, frameworks, auth providers, and runtimes." />
+  <Card title="Concepts" href="/concepts" description="How searchable encryption, key management, and identity-aware encryption work." />
+  <Card title="Guides" href="/guides" description="Development workflow, data migration, deployment, and troubleshooting." />
+  <Card title="Architecture & security" href="/security" description="Trust model, components, availability, audit, and compliance — for security review." />
+  <Card title="Solutions" href="/solutions" description="PII protection, HIPAA, AI/RAG, data residency, and provable access." />
+  <Card title="Reference" href="/reference" description="EQL, the Stack SDK, Auth, the CLI, and Proxy — precise API documentation." />
+</Cards>
+
+## AI-ready documentation
+
+Every page is available as clean markdown: append `.mdx` to any page URL, or
+fetch the whole corpus via [llms.txt](/llms.txt) and
+[llms-full.txt](/llms-full.txt).

content/docs/integrations/index.mdx

@@ -0,0 +1,9 @@
+---
+title: Integrations
+description: "Set up CipherStash with your platform, ORM, framework, auth provider, and runtime."
+type: tutorial
+---
+
+This section is being built as part of the docs V2 overhaul ([CIP-3307](https://linear.app/cipherstash/issue/CIP-3307)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, current documentation lives in the [existing docs](/stack).

content/docs/integrations/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Integrations",
+  "icon": "Blocks",
+  "pages": ["..."]
+}