cipherstash · coderdan · Jul 30, 2026 · Jul 2, 2026 · Jul 7, 2026 · Jul 7, 2026
diff --git a/IA.md b/IA.md
@@ -252,7 +252,6 @@ so it lives as facets and links, never as a tree section or a hub.
 | CTS | Identity service in the Platform | `platform` | `/security/cts`, `/reference/auth/*` |
 | `@cipherstash/auth` | Stack package (identity-aware encryption) | `[encryption, platform]` | `/reference/stack/auth` |
 | Proxy stack-auth | How auth works inside the Proxy | `[proxy, platform]` | `/reference/proxy/*`, `/security/proxy` |
-| Next.js adapter | Framework integration | `[encryption, platform]` | `/integrations/nextjs` |
 | Clerk / Auth0 / Okta | Auth-provider integrations | `[platform]` | `/integrations/*` (`category: auth-provider`) |
 
 None of these is filed under an "auth" section, because there isn't one. Each is
@@ -302,21 +301,20 @@ Two notes:
 ## 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
+- [x] `/integrations` index — category grid w/ setup badges
+- [x] `/integrations/supabase` — flagship tutorial (CIP-3328)
+- [x] `/integrations/supabase/database`
+- [x] `/integrations/supabase/auth`
+- [x] `/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`
+- [x] `/integrations/drizzle`
+- [x] `/integrations/prisma-next` — EQL v2 today; revisit when v3 support lands
 - [ ] `/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`
@@ -420,7 +418,7 @@ and the old `/compare/*` paths redirect there (`v2-redirects.mjs`).
 - [ ] `/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)
+- [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)
@@ -453,5 +451,9 @@ and the old `/compare/*` paths redirect there (`v2-redirects.mjs`).
       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
+- [ ] ⛔ Stack SDK Supabase-wrapper v3 alignment (CIP-3355, blocks CIP-3335) — the
+      Supabase section documents the 0.18 wrapper API with v3 wire semantics; the
+      wrapper itself is still v2 (composite type, `like` wire op, v2 payloads) and
+      the SDK's v3 branches don't touch `src/supabase/` yet
 - [ ] Flip `ENABLE_V2_REDIRECTS=1`, delete `content/stack` + `/stack` routes + legacy loader (CIP-3335)
 - [ ] Consistency sweep + Supabase listing v3 revision (CIP-3335)
diff --git a/content/docs/concepts/identity-aware-encryption.mdx b/content/docs/concepts/identity-aware-encryption.mdx
@@ -0,0 +1,9 @@
+---
+title: Identity-aware encryption
+description: "Lock contexts and CTS: binding encrypted values to a user identity so only that identity can decrypt them."
+type: concept
+---
+
+This page is being built as part of the docs V2 overhaul ([CIP-3330](https://linear.app/cipherstash/issue/CIP-3330)). 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/identity).
diff --git a/content/docs/get-started/choose-your-stack.mdx b/content/docs/get-started/choose-your-stack.mdx
@@ -44,7 +44,7 @@ Managed platforms usually block custom operator class creation. That's why the d
 | Query layer | Path | What it looks like |
 |---|---|---|
 | Drizzle | [Drizzle integration](/stack/cipherstash/encryption/drizzle) | An `encryptedType` column and typed query operators. Your Drizzle code keeps its shape. |
-| Supabase JS | [Supabase integration](/integrations/supabase) | `encryptedSupabase` wraps the client. `.eq()`, `.like()`, `.gt()` keep working. |
+| Supabase JS | [Supabase integration](/integrations/supabase) | `encryptedSupabase` wraps the client. `.eq()`, `.gt()`, `.order()` keep working. |
 | Prisma | [Prisma integration](/stack/cipherstash/encryption/prisma-next) | Encrypt in the data layer around Prisma calls. |
 | Raw SQL | [Quickstart](/get-started/quickstart) | Encrypt the value, insert it, cast the query operand. |
 | An ORM we don't list | The SDK | Encrypt before write, decrypt after read. Every ORM supports that. |

diff --git a/content/docs/get-started/quickstart.mdx b/content/docs/get-started/quickstart.mdx
@@ -5,8 +5,8 @@ type: tutorial
 components: [encryption, eql, cli, platform]
 audience: [developer]
 verifiedAgainst:
-  stack: "0.19.0"
-  cli: "0.17.1"
+  stack: "1.0.0-rc.0"
+  cli: "1.0.0-rc.0"
   eql: "3.0.0"
 ---
 
@@ -33,38 +33,20 @@ npx stash init
 This opens a browser for device-based authentication, so local development needs no environment variables and no shared secrets. `init` then:
 
 1. Connects to your workspace.
-2. Resolves your database connection and runs `stash eql install`, which installs [EQL](/reference/eql), the Postgres surface that makes encrypted columns queryable.
+2. Resolves your database connection and runs `stash eql install`, which installs [EQL](/reference/eql) v3, the Postgres surface that makes encrypted columns queryable.
 3. Installs `@cipherstash/stack` if it isn't already present.
 4. Scaffolds an encryption module at `src/encryption/index.ts`.
 5. Writes `.cipherstash/context.json` with what it detected about your project.
 
 See the [CLI reference](/reference/cli/init) for the flags, including `--supabase`, `--drizzle`, and `--prisma-next`.
 
-</Step>
-
-<Step>
-
-## Install EQL v3
-
-This guide, and the rest of the EQL reference, targets **EQL v3**. `stash init` installs EQL v2 by default today, so ask for v3 explicitly:
-
-```bash example-id="quickstart-eql-v3"
-npx stash eql install --eql-version 3 --force
-```
-
-`--force` reinstalls over the v2 schema that `init` just laid down. On a new database with no encrypted data, that is safe: there is nothing to migrate.
-
-Check what you ended up with:
+EQL v3 is the default, so `init` installs it directly against the database. Confirm what you ended up with:
 
-```bash
+```bash example-id="quickstart-eql-status"
 npx stash eql status
 ```
 
-<Callout type="info">
-`--eql-version` accepts `2` or `3` and **defaults to `2`** in `stash` 0.17.1. The default becomes `3` in a future release, at which point this step goes away. Pass the flag until then, so you know which generation you are on rather than inheriting a default that is about to change.
-
-v3 installs directly against the database, so the `--drizzle`, `--migration`, and `--latest` flags do not apply to it. See [installing EQL](/reference/eql) for the full options, including installing across several databases.
-</Callout>
+This guide, and the rest of the EQL reference, targets EQL v3.
 
 </Step>
 

diff --git a/content/docs/guides/deployment/index.mdx b/content/docs/guides/deployment/index.mdx
@@ -1,8 +1,95 @@
 ---
 title: Deployment
-description: "Deployment documentation — being built as part of the docs V2 overhaul."
+description: "Deploy CipherStash changes safely across environments, with explicit credential, migration, rollout, monitoring, and rollback gates."
+type: guide
+components: [encryption, eql, cli]
+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 deployments coordinate application code, database schema, and credentials. Treat each independently deployable stage as a release with its own verification and rollback gate.
 
-Until it lands, current documentation lives in the [existing docs](/stack).
+For the detailed dual-write, backfill, and cutover procedure for populated columns, follow [Encrypt existing data](/guides/migration/encrypt-existing-data). This page covers the production rollout around that migration.
+
+## Before the first deployment
+
+- Create a separate CipherStash workspace or machine credential set for each environment.
+- Store `CS_*` values in the environment's secret manager rather than copying a developer's local profile.
+- Confirm the production database connection used by migrations and backfills.
+- Test encryption, decryption, and the queries you rely on against a non-production database with the same EQL version.
+- Inventory all application versions and background workers that may remain live during a rolling deployment.
+- Decide who can approve backfill, read cutover, and plaintext removal.
+
+## Credentials at build and runtime
+
+An encryption client constructed at module load may authenticate when a build tool imports that module. In that case, `CS_WORKSPACE_CRN`, `CS_CLIENT_ID`, `CS_CLIENT_KEY`, and `CS_CLIENT_ACCESS_KEY` must be available during both the build and runtime phases.
+
+Do not let a local `stash auth login` session mask missing deployment credentials. Reproduce the production build in a clean environment that has only the secrets explicitly supplied by the deployment platform.
+
+Backfills must use credentials for the same workspace and keyset as the deployed application. `CS_*` environment variables take precedence over a local CipherStash profile.
+
+## Environment order
+
+Promote each stage through environments in this order:
+
+1. Local or ephemeral development database
+2. Shared development or test
+3. Staging with production-like data volume and connection behavior
+4. Production
+
+Run schema compatibility and application tests after each promotion. Do not use a successful local backfill as evidence that production credentials, row counts, locks, or query plans are safe.
+
+## Production rollout
+
+| Stage | Change | Verification gate | Rollback |
+| --- | --- | --- | --- |
+| Install EQL | Database-only, additive | EQL status and application connectivity | Leave installed |
+| Add encrypted mirrors | Nullable columns plus dual-writes | Every writer populates both columns | Revert writers; keep columns |
+| Backfill | Out-of-band data job | Zero uncovered rows and sampled decryptions match | Stop and resume later |
+| Build indexes | Database-only | Expected indexes engage under `EXPLAIN` | Drop or rebuild the index |
+| Cut reads over | Application-only | Known filters, ordering, nulls, and RLS behavior are correct | Revert reads to plaintext |
+| Remove plaintext | Application and destructive schema change | Soak complete; no old application versions remain | Restore or migrate from backup |
+
+Keep schema changes backward-compatible with both the old and new application version during rolling deployments. In particular, encrypted mirror columns must remain nullable until every historical row is covered.
+
+## Release gates
+
+### Before backfill
+
+- Dual-writes are deployed in every process that can mutate the table.
+- Known inserts, updates, upserts, imports, and background jobs populate both columns.
+- The backfill is using production's CipherStash credentials.
+- The primary key and chunk size are suitable for paging through the table.
+
+### Before read cutover
+
+- Coverage queries return zero missing encrypted values.
+- Encrypted indexes have been created and verified using [EQL indexes](/reference/eql/indexes).
+- Equality, range, ordering, null, and authorization tests pass against representative data.
+- The old plaintext read path remains deployable as a rollback.
+
+### Before dropping plaintext
+
+- The encrypted read path has soaked under real traffic.
+- No supported application version reads or writes the plaintext column.
+- Coverage has been checked again.
+- Required backups and restore procedures have been tested.
+- The destructive migration has a named approver and maintenance window where required.
+
+## Monitor after cutover
+
+Monitor ordinary database and application signals alongside encryption-specific failures:
+
+- Encryption and decryption errors
+- ZeroKMS request latency and availability
+- Query latency, sequential scans, and index use
+- Missing or unexpectedly null values
+- Authorization and Row Level Security regressions
+- Backfill progress, retry rate, and uncovered-row count
+
+Test the correctness of returned values, not only request success rates. An incorrectly scoped filter or ordering query may return plausible but incomplete data without raising an error.
+
+## Rollback principles
+
+Prefer application rollbacks while both plaintext and encrypted columns are being maintained. Before plaintext removal, a read cutover can be reversed without changing data: point reads back to the original columns and leave dual-writes running.
+
+After plaintext is dropped, rollback becomes a data-recovery operation. Avoid reaching that stage until operational evidence shows the encrypted path is stable and every supported application version has moved forward.
diff --git a/content/docs/guides/development/schema-design.mdx b/content/docs/guides/development/schema-design.mdx
@@ -0,0 +1,9 @@
+---
+title: Schema design
+description: "Choosing the right encrypted type and capability for each column."
+type: guide
+---
+
+This page is being built as part of the docs V2 overhaul ([CIP-3327](https://linear.app/cipherstash/issue/CIP-3327)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md).
+
+Until it lands, [EQL core concepts](/reference/eql/core-concepts) covers the capability model, and the per-type pages ([numbers](/reference/eql/numbers), [dates & times](/reference/eql/dates-and-times), [text](/reference/eql/text), [JSON](/reference/eql/json)) cover choosing variants.