Reorganize Stack and Supabase API references

.github/workflows/docs.yml

@@ -42,13 +42,16 @@ jobs:
 
       - 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.
+      # The TypeDoc references under the V2 integration/reference sections are
+      # gitignored and built from a clone of cipherstash/stack. Links point
+      # into them, so without this step those targets report as missing.
       # `prebuild` generates before validating for the same reason.
       - name: Generate the SDK reference
         run: bun run generate-docs
 
+      - name: Generate the Supabase reference
+        run: bun run generate-docs:supabase
+
       - name: Generate the Prisma reference
         run: bun run generate-docs:prisma
 

.gitignore

@@ -39,6 +39,10 @@ content/stack/reference/drizzle/latest/
 content/stack/reference/drizzle/v*/
 content/docs/integrations/prisma/api-reference/*
 !content/docs/integrations/prisma/api-reference/meta.json
+content/docs/integrations/supabase/api-reference/*
+!content/docs/integrations/supabase/api-reference/meta.json
+content/docs/reference/stack/api-reference/*
+!content/docs/reference/stack/api-reference/meta.json
 .tmp-*
 .env.local
 

IA.md

@@ -415,13 +415,9 @@ and the old `/compare/*` paths redirect there (`v2-redirects.mjs`).
       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)
-- [x] `/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)
+- [x] `/reference/stack` — core package overview and usage
+- [x] `/reference/stack/api-reference` — generated `@cipherstash/stack` API
+- [x] `/integrations/supabase/api-reference` — generated `@cipherstash/stack-supabase` API (CIP-3328)
 - **Auth (CIP-3330):**
 - [ ] `/reference/auth/lock-contexts`
 - [ ] `/reference/auth/cts-tokens`

content/docs/concepts/compare/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Comparisons
+navTitle: Overview
 description: "How CipherStash compares to other approaches to protecting data."
 type: concept
 ---

content/docs/concepts/compare/meta.json

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

content/docs/concepts/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Concepts
+navTitle: Overview
 description: "How CipherStash works and how to think about searchable encryption, keys, and identity."
 type: concept
 ---

content/docs/concepts/meta.json

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

content/docs/guides/deployment/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Deployment
+navTitle: Overview
 description: "Deploy CipherStash changes safely across environments, with explicit credential, migration, rollout, monitoring, and rollback gates."
 type: guide
 components: [encryption, eql, cli]

content/docs/guides/deployment/meta.json

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

content/docs/guides/development/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Development
+navTitle: Overview
 description: "Development documentation — being built as part of the docs V2 overhaul."
 ---
 

content/docs/guides/development/meta.json

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

content/docs/guides/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Guides
+navTitle: Overview
 description: "Task-oriented guides: development workflow, data migration, deployment, and troubleshooting."
 type: guide
 ---

content/docs/guides/meta.json

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

content/docs/guides/migration/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Data migration
+navTitle: Overview
 description: "Safely introduce CipherStash encryption to existing schemas and populated production data."
 type: guide
 components: [encryption, eql, cli]

content/docs/guides/migration/meta.json

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

content/docs/guides/troubleshooting/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Troubleshooting
+navTitle: Overview
 description: "Troubleshooting documentation — being built as part of the docs V2 overhaul."
 ---
 

content/docs/guides/troubleshooting/meta.json

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

content/docs/integrations/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Integrations
+navTitle: Overview
 description: "Every CipherStash integration, by category: the Postgres platforms encrypted data lives in, and the query layers that read and write it."
 type: concept
 components: [encryption, eql, platform]

content/docs/integrations/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Integrations",
   "icon": "Blocks",
-  "pages": ["!index", "supabase", "prisma", "..."]
+  "pages": ["index", "supabase", "prisma", "..."]
 }

content/docs/integrations/supabase/api-reference/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "API reference",
+  "pages": ["index"]
+}

content/docs/integrations/supabase/auth.mdx

@@ -76,7 +76,7 @@ Federation authenticates *as* the user. **Lock context** goes further: it bakes
 Lock context requires the client to be authenticated with `OidcFederationStrategy` (above). It cannot be used with `AccessKeyStrategy`, which authenticates a *service*, not a user — there is no user `sub` claim to bind to. Lock context also requires a Business or Enterprise workspace plan.
 </Callout>
 
-Attach a lock context to any [`encryptedSupabase`](/reference/stack/supabase) query with `.withLockContext()`. `sub` is the Supabase user's UUID:
+Attach a lock context to any [`encryptedSupabase`](/integrations/supabase/api-reference) query with `.withLockContext()`. `sub` is the Supabase user's UUID:
 
 ```typescript
 import { db } from "./lib/db"
@@ -120,7 +120,7 @@ Both federation and lock context surface failures as values, not throws.
 | Provider not registered with the workspace | Federation fails — register the Supabase OIDC issuer first |
 | Expired or invalid Supabase session | `getJwt` throws / returns no session; federation cannot proceed |
 | CipherStash token expired mid-request | Strategy re-federates automatically via `getJwt` |
-| Decrypting another user's locked value | `encryptionError` on the [query response](/reference/stack/supabase#responses-and-errors) |
+| Decrypting another user's locked value | `encryptionError` on the [query response](/integrations/supabase/supabase-js#responses-and-errors) |
 
 The strategy's own factory and token errors follow the `@cipherstash/auth` `Result` shape (`failure.type`); see the [auth reference](/reference/auth).
 
@@ -133,7 +133,7 @@ The strategy's own factory and token errors follow the `@cipherstash/auth` `Resu
   <Card title="Edge Functions" href="/integrations/supabase/edge-functions">
     Run the federation strategy server-side in Supabase Edge Functions.
   </Card>
-  <Card title="encryptedSupabase reference" href="/reference/stack/supabase">
+  <Card title="encryptedSupabase reference" href="/integrations/supabase/api-reference">
     `.withLockContext()` and `.audit()` on the query builder.
   </Card>
   <Card title="Auth reference" href="/reference/auth">

content/docs/integrations/supabase/index.mdx

@@ -22,19 +22,19 @@ Unlike ordinary application-level encryption, protected columns remain queryable
 CipherStash has two parts:
 
 1. [Encrypt Query Language (EQL)](/reference/eql) adds encrypted column types, operators, and functions to your Supabase Postgres database.
-2. [`encryptedSupabase`](/reference/stack/supabase) wraps the Supabase JavaScript client and performs encryption and decryption in your application.
+2. [`encryptedSupabase`](/integrations/supabase/api-reference) wraps the Supabase JavaScript client and performs encryption and decryption in your application.
 
 The EQL type assigned to a column declares what can be queried. For example, an equality column supports `.eq()` and `.in()`, while an ordered column also supports ranges and `.order()`. Choose only the capabilities you need, because searchable encryption has defined leakage characteristics. See [EQL core concepts](/reference/eql/core-concepts) for the complete model.
 
-With EQL 3.0.4, the Supabase wrapper supports encrypted equality, range, and ordering queries. Encrypted free-text and JSON queries require an adapter such as Drizzle or Prisma ORM 8 because PostgREST cannot express the typed operands those operations require. The [wrapper reference](/reference/stack/supabase#free-text-and-json-need-a-different-adapter) documents the limitation.
+With EQL 3.0.4, the Supabase wrapper supports encrypted equality, range, and ordering queries. Encrypted free-text and JSON queries require an adapter such as Drizzle or Prisma ORM 8 because PostgREST cannot express the typed operands those operations require. The [supabase-js guide](/integrations/supabase/supabase-js#free-text-and-encrypted-json-queries) documents the limitation.
 
 ## Choose your path
 
 | What you want to do | Start here |
 | --- | --- |
 | Encrypt and query your first Supabase column | [Supabase Quickstart](/integrations/supabase/quickstart) |
 | Use the Supabase JavaScript client | [supabase-js guide](/integrations/supabase/supabase-js) |
-| Look up the complete wrapper API | [`encryptedSupabase` reference](/reference/stack/supabase) |
+| Look up the complete wrapper API | [`encryptedSupabase` API reference](/integrations/supabase/api-reference) |
 | Bind decryption to the signed-in user | [Supabase Auth](/integrations/supabase/auth) |
 | Encrypt inside Supabase Edge Functions | [Edge Functions](/integrations/supabase/edge-functions) |
 | Choose local or deployment credentials | [Workspace credentials](/reference/workspace/configuration#credentials) |

content/docs/integrations/supabase/meta.json

@@ -1,5 +1,12 @@
 {
   "title": "Supabase",
   "icon": "Supabase",
-  "pages": ["index", "quickstart", "supabase-js", "auth", "edge-functions"]
+  "pages": [
+    "index",
+    "quickstart",
+    "supabase-js",
+    "auth",
+    "edge-functions",
+    "api-reference"
+  ]
 }

content/docs/integrations/supabase/quickstart.mdx

@@ -159,7 +159,7 @@ The Table Editor cannot decrypt or meaningfully filter the encrypted value becau
 ## Next steps
 
 - Learn the supported mutations, filters, ordering, response types, and errors in the [supabase-js guide](/integrations/supabase/supabase-js).
-- Use the complete [`encryptedSupabase` API reference](/reference/stack/supabase) when you need method-level detail.
+- Use the complete [`encryptedSupabase` API reference](/integrations/supabase/api-reference) when you need method-level detail.
 - Add functional indexes when the table reaches meaningful row counts by following [EQL indexes](/reference/eql/indexes).
 - For a populated table, follow the safe dual-write and backfill process in [Encrypt existing data](/guides/migration/encrypt-existing-data).
 - To use a direct Postgres ORM connection, continue with [Drizzle](/integrations/drizzle) or [Prisma ORM 8](/integrations/prisma).

content/docs/integrations/supabase/supabase-js.mdx

@@ -229,7 +229,7 @@ Chain `.throwOnError()` when the surrounding code prefers exceptions. Chain `.au
   <Card title="Edge Functions" href="/integrations/supabase/edge-functions">
     Run encryption in Deno with the WebAssembly build.
   </Card>
-  <Card title="Supabase wrapper reference" href="/reference/stack/supabase">
+  <Card title="Supabase wrapper API reference" href="/integrations/supabase/api-reference">
     The complete query-builder API, response types, and implementation details.
   </Card>
 </Cards>

content/docs/reference/auth/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Auth
+navTitle: Overview
 description: "Auth documentation — being built as part of the docs V2 overhaul."
 ---
 

content/docs/reference/auth/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Auth",
-  "pages": ["..."]
+  "pages": ["index", "..."]
 }

content/docs/reference/cli/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: CLI
+navTitle: Overview
 description: "Command reference for the stash CLI, generated from v0.17.0."
 type: reference
 components: [cli]

content/docs/reference/cli/meta.json

@@ -1,6 +1,7 @@
 {
   "title": "CLI",
   "pages": [
+    "index",
     "---Setup & workflow---",
     "init",
     "plan",

content/docs/reference/eql/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: EQL
+navTitle: Overview
 description: "Encrypt Query Language (EQL) installs encrypted column types and operators into Postgres as plain SQL — encryption itself happens in your client."
 type: reference
 components: [eql]

content/docs/reference/eql/meta.json

@@ -1,6 +1,7 @@
 {
   "title": "EQL",
   "pages": [
+    "index",
     "core-concepts",
     "---Types---",
     "numbers",

content/docs/reference/eql/v2/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: EQL v2
+navTitle: Overview
 description: PostgreSQL types, operators, and functions for querying encrypted data with EQL v2 (v2.2) — the eql_v2_encrypted type and searchable index types.
 type: reference
 components: [eql]

content/docs/reference/eql/v2/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "EQL v2",
-  "pages": ["indexes", "queries", "payload"]
+  "pages": ["index", "indexes", "queries", "payload"]
 }

content/docs/reference/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Reference
+navTitle: Overview
 description: "Precise API documentation for EQL, the Stack SDK, Auth, the CLI, and Proxy."
 type: reference
 ---

content/docs/reference/proxy/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Proxy
+navTitle: Overview
 description: "Configuration, message flow, multitenant operation, and error reference for CipherStash Proxy."
 type: reference
 components: [proxy]

content/docs/reference/stack/api-reference/meta.json

@@ -0,0 +1,17 @@
+{
+  "title": "API reference",
+  "pages": [
+    "index",
+    "Package-exports",
+    "adapter-kit",
+    "dynamodb",
+    "encryption",
+    "encryption.v3",
+    "eql.v3",
+    "errors",
+    "identity",
+    "schema",
+    "types-public",
+    "wasm-inline"
+  ]
+}

content/docs/reference/stack/index.mdx

@@ -1,8 +1,33 @@
 ---
-title: Stack SDK
-description: "Stack SDK documentation — being built as part of the docs V2 overhaul."
+title: Overview
+description: "The core @cipherstash/stack package for client-side encryption, searchable schemas, identity controls, and encrypted query operands."
+type: reference
+components: [encryption, eql]
+audience: [developer]
 ---
 
-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).
+`@cipherstash/stack` is the core TypeScript SDK for CipherStash. It encrypts and decrypts values in your application, defines the searchable capabilities of encrypted columns, and creates encrypted operands for queries against [EQL](/reference/eql).
 
-Until it lands, current documentation lives in the [existing docs](/stack).
+Database and framework wrappers are separate packages. Use the [Supabase](/integrations/supabase), [Prisma ORM 8](/integrations/prisma), or [Drizzle](/integrations/drizzle) integration when you want encryption built into that library's query flow.
+
+## What the package provides
+
+| Area | Purpose |
+| --- | --- |
+| Encryption client | Encrypt and decrypt individual values, batches, and models. |
+| Schema builders | Describe tables, columns, value types, and searchable capabilities. |
+| Query encryption | Produce typed encrypted operands for equality, range, and search queries. |
+| Identity controls | Bind encryption and decryption to federated identity claims. |
+| DynamoDB helpers | Encrypt and decrypt DynamoDB attributes and expressions. |
+| Error types | Inspect operation failures without parsing error messages. |
+
+## Start here
+
+<Cards>
+  <Card title="Usage" href="/reference/stack/usage">
+    Install the package, define an encrypted schema, and encrypt, query, and decrypt a value.
+  </Card>
+  <Card title="API reference" href="/reference/stack/api-reference">
+    Browse the generated functions, classes, interfaces, and type aliases exported by the package.
+  </Card>
+</Cards>

content/docs/reference/stack/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Stack SDK",
-  "pages": ["..."]
+  "pages": ["index", "usage", "api-reference"]
 }