Conversation
Foundation for the docs overhaul tracked in CIP-3307: - IA.md: living migration checklist at the repo root (one checkbox per planned page; sections tick off as they land on this branch) - New `v2docs` collection (content/docs) served from the site root via a required catch-all route, alongside the legacy tree (content/stack) at /stack until every section migrates - Frontmatter facet model: Diátaxis `type`, `components`, `audience`, `integration` (category / setup / pairsWith), and review-tracking fields (`verifiedAgainst`, `reviewBy`) - Section scaffold: get-started, integrations (incl. the /integrations/supabase stub the Supabase listing links to), concepts, compare, guides, security, solutions, reference — meta.json + stubs - v2-redirects.mjs: full legacy→v2 map (85/85 pages covered), gated behind ENABLE_V2_REDIRECTS=1 so the preview serves both trees during migration; /quickstart vanity redirect ships ungated - scripts/validate-v2-redirects.ts wired into prebuild: CI fails if a legacy page has no v2 mapping - llms.txt, llms-full.txt, sitemap, and the .mdx raw-markdown mirror now cover both trees Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P
…rence/eql Two issues caught by smoke-testing the scaffold: - Stub descriptions containing ":" broke YAML frontmatter parsing (500s across the v2 tree) — descriptions are now quoted. - The AI-citation redirect "/reference/eql" → "/stack/reference/eql" shadowed the v2 /reference/eql page (redirects run before the filesystem); removed since the v2 page now serves that path. Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…t bare root Two fixes from preview review: - The bare domain root (Vercel preview URLs) 404'd because the app lives under the /docs basePath — added a basePath:false redirect / → /docs. In production only /docs/* reaches this app, so previews-only. - The /docs landing was a standalone (home) page disconnected from the v2 nav, with every link pointing at legacy /stack URLs. It's now content/docs/index.mdx rendered inside DocsLayout (sidebar + search), linking the v2 sections. The catch-all became optional ([[...slug]]) and the (home) route group is deleted (recoverable from history; CIP-3327 refines the landing content). - The landing's raw-markdown mirror serves at /docs/index.mdx (its URL is "/", which can't carry the .mdx suffix). Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P
Listing "index" explicitly in meta.json pages forced each section's index out as a separate child item with the same title as its folder (clicking "Get started" opened a sub-nav containing another "Get started"). With index unlisted, Fumadocs merges it into the folder row: the folder itself links to the page, and children are only real sub-pages (Integrations → Supabase, not Integrations → Integrations). The root meta.json keeps "index" — at tree root there is no folder row to merge into, so the landing needs its own sidebar item. Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P
Folders whose only page is their index still rendered as collapsible sidebar folders with a chevron pointing at nothing. getV2PageTree() now collapses such folders into plain page items (recursively, so guides/* and reference/* leaves flatten too); a section becomes a folder again automatically when its first real sub-page lands. Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P
MDX links (markdown and Card hrefs) render through the Link component, which prefixes the /docs basePath — hardcoded /docs/... links rendered as /docs/docs/... and 404'd. Convention (enforce via CIP-3349 lint): internal links in content are always basePath-relative. Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P
There was a problem hiding this comment.
Pull request overview
This PR scaffolds the “Docs V2” information architecture by introducing a new content/docs tree served from the site root (under the existing /docs basePath), while keeping the legacy content/stack tree available at /docs/stack during migration. It also adds a gated legacy→v2 redirect map plus CI validation to ensure legacy pages won’t become orphaned when redirects are enabled.
Changes:
- Add a new
v2docscollection +v2sourceloader, plus root catch-all routes/layout for the v2 docs tree. - Introduce a full legacy→v2 redirect map (
v2-redirects.mjs) gated byENABLE_V2_REDIRECTS=1, with a prebuild validation script to enforce coverage. - Scaffold v2 section stubs/meta and update sitemap + LLM surfaces (
llms.txt,llms-full.txt,.mdxraw mirror) to include the v2 tree first.
Reviewed changes
Copilot reviewed 65 out of 65 changed files in this pull request and generated 25 comments.
Show a summary per file
| File | Description |
|---|---|
| v2-redirects.mjs | Adds the full legacy /stack/* → v2 redirect mapping list (flag-gated in Next config). |
| next.config.mjs | Wires in gated v2 redirects, adds preview root redirect, and adds .mdx rewrite for v2 raw mirror; removes old /reference/eql redirect collision. |
| scripts/validate-v2-redirects.ts | Adds CI/prebuild gate to ensure every legacy content/stack page is covered by v2 redirects. |
| package.json | Adds validate-redirects script and runs it during prebuild. |
| source.config.ts | Defines the new v2docs collection and its frontmatter facet schema. |
| src/lib/source.ts | Adds v2source, v2 page tree shaping (flattenEmptyFolders), and broadens getLLMText typing for both trees. |
| src/app/[[...slug]]/layout.tsx | Adds the v2 docs layout (DocsLayout + v2 tree) at the root catch-all segment. |
| src/app/[[...slug]]/page.tsx | Adds the v2 docs page renderer, metadata generation, and markdown mirror URL generation. |
| src/app/llms.mdx/v2/[[...slug]]/route.ts | Adds the v2 raw-markdown mirror route for agent/LLM consumption. |
| src/app/llms.txt/route.ts | Lists v2 pages first, then legacy pages, in llms.txt. |
| src/app/llms-full.txt/route.ts | Emits the concatenated markdown for v2 pages first, then legacy pages. |
| src/app/sitemap.ts | Includes both v2 and legacy pages in sitemap (v2 first). |
| src/app/og/docs/[...slug]/route.tsx | Import ordering tweak only. |
| src/app/api/search/route.ts | Import ordering tweak only. |
| src/app/layout.tsx | Import ordering tweak only. |
| src/app/stack/layout.tsx | Import ordering tweak only. |
| src/app/stack/[[...slug]]/page.tsx | Import ordering tweak only. |
| src/proxy.ts | Import ordering tweak only. |
| src/lib/posthog/provider.tsx | Import ordering tweak only. |
| src/components/icons/supabase.tsx | Fixes missing semicolon in return statement. |
| src/app/(home)/page.tsx | Removes the standalone legacy docs landing page implementation. |
| src/app/(home)/layout.tsx | Removes the legacy home layout wrapper. |
| IA.md | Adds the migration checklist + branch workflow rules for the v2 overhaul. |
| content/docs/meta.json | Adds v2 root meta defining top-level section ordering. |
| content/docs/index.mdx | Adds the v2 docs landing page content (Cards + LLM surface links). |
| content/docs/get-started/meta.json | Adds v2 “Get started” section meta. |
| content/docs/get-started/index.mdx | Adds v2 “Get started” stub page. |
| content/docs/integrations/meta.json | Adds v2 “Integrations” section meta. |
| content/docs/integrations/index.mdx | Adds v2 “Integrations” stub page. |
| content/docs/integrations/supabase/meta.json | Adds v2 Supabase integration meta (custom icon). |
| content/docs/integrations/supabase/index.mdx | Adds v2 Supabase stub page with facet example. |
| content/docs/concepts/meta.json | Adds v2 “Concepts” section meta. |
| content/docs/concepts/index.mdx | Adds v2 “Concepts” stub page. |
| content/docs/compare/meta.json | Adds v2 “Comparisons” section meta. |
| content/docs/compare/index.mdx | Adds v2 “Comparisons” stub page. |
| content/docs/guides/meta.json | Adds v2 “Guides” section meta. |
| content/docs/guides/index.mdx | Adds v2 “Guides” stub page. |
| content/docs/guides/development/meta.json | Adds v2 “Development” guides meta. |
| content/docs/guides/development/index.mdx | Adds v2 “Development” stub page. |
| content/docs/guides/migration/meta.json | Adds v2 “Data migration” guides meta. |
| content/docs/guides/migration/index.mdx | Adds v2 “Data migration” stub page. |
| content/docs/guides/deployment/meta.json | Adds v2 “Deployment” guides meta. |
| content/docs/guides/deployment/index.mdx | Adds v2 “Deployment” stub page. |
| content/docs/guides/troubleshooting/meta.json | Adds v2 “Troubleshooting” guides meta. |
| content/docs/guides/troubleshooting/index.mdx | Adds v2 “Troubleshooting” stub page. |
| content/docs/security/meta.json | Adds v2 “Architecture & security” section meta. |
| content/docs/security/index.mdx | Adds v2 “Architecture & security” stub page. |
| content/docs/security/compliance/meta.json | Adds v2 “Compliance” meta under security. |
| content/docs/security/compliance/index.mdx | Adds v2 “Compliance” stub page. |
| content/docs/solutions/meta.json | Adds v2 “Solutions” section meta. |
| content/docs/solutions/index.mdx | Adds v2 “Solutions” stub page. |
| content/docs/reference/meta.json | Adds v2 “Reference” section meta. |
| content/docs/reference/index.mdx | Adds v2 “Reference” stub page. |
| content/docs/reference/eql/meta.json | Adds v2 “EQL” reference meta. |
| content/docs/reference/eql/index.mdx | Adds v2 “EQL” stub page. |
| content/docs/reference/stack/meta.json | Adds v2 “Stack SDK” reference meta. |
| content/docs/reference/stack/index.mdx | Adds v2 “Stack SDK” stub page. |
| content/docs/reference/proxy/meta.json | Adds v2 “Proxy” reference meta. |
| content/docs/reference/proxy/index.mdx | Adds v2 “Proxy” stub page. |
| content/docs/reference/cli/meta.json | Adds v2 “CLI” reference meta. |
| content/docs/reference/cli/index.mdx | Adds v2 “CLI” stub page. |
| content/docs/reference/auth/meta.json | Adds v2 “Auth” reference meta. |
| content/docs/reference/auth/index.mdx | Adds v2 “Auth” stub page. |
| content/docs/reference/workspace/meta.json | Adds v2 “Workspace & account” reference meta. |
| content/docs/reference/workspace/index.mdx | Adds v2 “Workspace & account” stub page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+26
to
+30
| <Card title="Integrations" href="/docs/integrations" description="Platforms, ORMs, frameworks, auth providers, and runtimes." /> | ||
| <Card title="Concepts" href="/docs/concepts" description="How searchable encryption, key management, and identity-aware encryption work." /> | ||
| <Card title="Guides" href="/docs/guides" description="Development workflow, data migration, deployment, and troubleshooting." /> | ||
| <Card title="Architecture & security" href="/docs/security" description="Trust model, components, availability, audit, and compliance — for security review." /> | ||
| <Card title="Solutions" href="/docs/solutions" description="PII protection, HIPAA, AI/RAG, data residency, and provable access." /> |
| <Card title="Guides" href="/docs/guides" description="Development workflow, data migration, deployment, and troubleshooting." /> | ||
| <Card title="Architecture & security" href="/docs/security" description="Trust model, components, availability, audit, and compliance — for security review." /> | ||
| <Card title="Solutions" href="/docs/solutions" description="PII protection, HIPAA, AI/RAG, data residency, and provable access." /> | ||
| <Card title="Reference" href="/docs/reference" description="EQL, the Stack SDK, Auth, the CLI, and Proxy — precise API documentation." /> |
Comment on lines
+20
to
+21
| - **Moving a page = ** move the file into `content/docs`, update its facets, | ||
| fix inbound links, confirm its `v2-redirects.mjs` entry, tick it here. |
Seven pages replacing the v2-era EQL reference, written against the eql_v3 branch of cipherstash/encrypt-query-language (3.0.0): - index: what EQL is, the v3 domain-variant model, install (single SQL script, idempotent), dbdev, Docker, migration/runtime permission split, managed-Postgres rationale - types: 10 scalar families × variants matrix; bool storage-only; _ord/_ord_ore twins; index terms per variant - operators: per-variant support matrix, typed-operand rule, no-LIKE, fail-loud blockers, query shapes, function-form equivalents - indexes: functional indexes on term extractors, engagement requirements, sort-key form for index-streamed ORDER BY, EXPLAIN checklist, large-table build guidance - json: ste_vec model, per-node-type terms (hm XOR oc), containment + GIN, field access, path queries, blocked native jsonb operators - functions: comparisons, extractors, min/max only (no SUM/AVG), version() - payload-format: v/i/c envelope (wire version still v:2), hm/ob/bf term keys, sv document shape, annotated examples (absorbs the legacy CipherCell page) Cross-page consistency verified against the shipped SQL: equality on _ord variants compares ORE terms (no hm in _ord payloads), and bare ORDER BY is correct but extractor-form sort keys stream from the index. Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P
coderdan
commented
Jul 2, 2026
| { | ||
| source: "/stack/quickstart", | ||
| destination: "/get-started/quickstart", | ||
| permanent: true, |
Contributor
Author
There was a problem hiding this comment.
We shouldn't make these permanent for now.
Contributor
Author
There was a problem hiding this comment.
Done in d0ccd7e — all 71 entries flipped to permanent: false, with a header note to revisit as part of CIP-3335 once the map has soaked post-merge.
EQL is an abstraction over SQL the way Tailwind is over CSS — the docs now follow the same shape: Install → Core concepts → type categories → Indexes → query patterns, increasing in complexity. Each type-category page is the complete reference for its types (variants, payload shape, operators/functions, example queries on one page). - index: trimmed to the Install page - core-concepts (new): the canonical home for shared mechanics — variant model, payload anatomy (v/i/c envelope + hm/ob/bf terms, absorbs payload-format/CipherCell), typed-operand rule, fail-loud blockers, ORE-equality on _ord, term-leakage pointer - numbers-and-dates, text, booleans (new) + json (reworked): category pages; text owns the no-LIKE treatment; json absorbs the sv payload shape; booleans framed as "every type has a storage-only variant — for bool it's the only one" - filtering, sorting, grouping-and-aggregates, joins (new): cross-type query patterns; joins headlines the same-keyset constraint - deleted: types.mdx, operators.mdx, functions.mdx, payload-format.mdx (content redistributed; URLs never shipped publicly, no redirect debt) - Anti-drift rule recorded in IA.md: mechanics live ONLY in core-concepts; category/query pages link, never restate - meta.json: flat URLs with ---Types---/---Indexes---/---Queries--- sidebar separators; legacy redirect map retargeted (queries → filtering, cipher-cell → core-concepts) Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P
…load v:3 Review feedback on the EQL section: - Variant tables: generic form first, then full enumeration of every concrete domain name (Tailwind-style); capability column made concise; "index term carried" column dropped — term internals live in core-concepts' payload anatomy - SEM specifiers documented as a concept in core-concepts: a trailing mechanism suffix (_ord_ore) pins WHICH searchable-encryption mechanism implements a capability; _ord tracks the default (currently ORE). Replaces the "twins" framing. Each orderable type page lists its specifiers under an "SEM specifiers" heading, noting the OPE specifier arriving for all orderable types (incl. text) in the v3 release - Payload `v` field documented as the EQL version (3) per team decision 2026-07-02; all payload examples updated from v:2 Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P
…perators and Functions Review feedback: - Dates & times split out of Numbers — same traits, distinct semantics; each page's examples now match its domain (payroll vs audit-event time windows / retention cutoffs / newest-first) - CREATE TABLE examples get an explicit "Example" sub-heading + lead-in - Operators and Functions are separate sections on every type page — operators as the per-variant support matrix, functions as the form-equivalents table (+ MIN/MAX, which only exist as functions) - IA.md: split reflected; query-performance follow-up added (CIP-3351 — the v3 branch already folded the v2 perf guide into database-indexes.md, which our indexes page absorbed) Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P
- indexes.mdx: cast query-shape example params to their EQL domain types, consistent with the typed-operand rule - numbers/dates-and-times/text: the fail-loud note now scopes to operators — ORDER BY on a variant without an ordering term doesn't raise, it silently returns a meaningless order (links Sorting)
- v2-redirects.mjs: all entries permanent: false while the IA settles (per review); flip to permanent post-merge soak (CIP-3335) - IA.md: fix unmatched bold around 'Moving a page' - add placeholder pages for /concepts/searchable-encryption (CIP-3333) and /guides/troubleshooting/query-performance (CIP-3351) so the EQL reference's forward links resolve instead of 404ing
# Conflicts: # v2-redirects.mjs
Contributor
Author
|
Review comments addressed in d0ccd7e:
|
Docs V2: EQL v3 reference section, Tailwind-shaped (CIP-3326)
PROTOTYPE for review. Generates /reference/cli from the shipped `stash` CLI so the reference can't drift from the actual command surface, and stamps every page with the CLI version it was generated from. - scripts/generate-cli-docs.ts — parses `stash --help` (captured to a fixture) into a manifest, then renders one page per top-level command (grouped Setup/Auth/Database/Schema/Encrypt/Deployment) with a "Generated from stash v0.16.0" banner, a verifiedAgainst.cli facet, and [cli] / [cli, eql] components per the content-model tagging rule. - `bun run generate-docs:cli` (package.json). - scripts/fixtures/stash-help-0.16.0.txt — captured input. - content/docs/reference/cli/* — generated output (10 command pages + index). Bootstrap note: `stash` 0.16.0 is a hand-rolled TS CLI with no machine-readable output and no per-command --help, so we parse the single top-level --help. Target: add `stash manifest --json` to the CLI, then swap loadManifest() to read it and delete the parser — the page format stays identical. Today's --help is thin (no args, no per-command examples, auth/encrypt subcommands undetailed); those gaps are exactly what the JSON manifest fills. Surfaces the drift too: 0.16.0 uses `db install` (not `eql install`) and has ~15 commands the hand-written pages never documented. Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
…build - Resolve the latest published version via `npm view stash version` and run that exact version live, so a new `stash` release refreshes the docs the next time the script runs (offline: falls back to the cached fixture). Removes the pinned CLI_VERSION constant. - Wire `generate-docs:cli` into `prebuild`, next to the EQL/TypeDoc generators, so every production build regenerates the CLI reference from the latest CLI. - Rename the fixture to a version-agnostic cache (scripts/fixtures/stash-help.txt). Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
…amples Adds a supplement hook to the CLI generator: an optional scripts/cli-supplements/<command>.md is merged after the generated reference (synopsis + flags), so the rich per-command narrative and curated examples the thin `stash --help` can't provide can be authored now, without waiting on the CLI. Supplements live outside content/ so they're never treated as pages or wiped by the clean step. Demonstrated on `auth` (device-code flow + keyset binding, grounded in the CLI source). Content-model direction: per-command reference detail (examples, flag help) should migrate into the CLI itself (long-help + examples, GitHub-CLI/cobra style) and be generated from there; cross-command conceptual narrative (the profile / workspace model) belongs in a linked CLI concept page. The supplement hook is the interim bridge and the seam for both. Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
stash CLI 0.17 ships the `manifest` command (structured, versioned command surface), so swap the generator off `--help` scraping onto `stash manifest --json` and delete the text parser — the realization of this PR's stated target. - loadManifest() now runs `npx stash@<version> manifest --json` and projects it onto the renderer's model; nav groups + order come straight from the CLI. - Per-command flags carry their `default` and `env` (folded into the flag description); examples come from the manifest. Pipes in flag values (`--eql-version <2|3>`) are escaped so the GFM table renders. - Fixture swapped from stash-help.txt to stash-manifest.json. - Regenerated against 0.17.0: new `eql` group (eql install/upgrade/status), new `doctor` + `manifest` pages, `db` no longer lists install/upgrade. types:check passes; generator lints clean (bar pre-existing noNonNullAssertion style warnings shared with the original).
Some customers still run EQL v2.2 (v2.3 is being withdrawn). The new
/reference/eql section documents EQL v3 only, so this adds a durable,
nested EQL v2 reference sourced from the v2.2 docs, surviving the
CIP-3335 deletion of the legacy /stack tree:
content/docs/reference/eql/v2/
index.mdx — EQL v2 overview (from reference/eql-guide.mdx)
indexes.mdx — index recipes, incl. the Supabase query forms
queries.mdx — equality / match / range query patterns
payload.mdx — the CipherCell v2.2 payload (b3, ocf/ocv)
Content is the v2.2 legacy docs, NOT the EQL 2.3 rewrites from #21/#22
(which no longer ship). Two grounded doc-bug fixes are carried in: the
eql-guide's fabricated index-extraction function names are corrected to
the real eql_v2.hmac_256 / bloom_filter / ore_block_u64_8_256 (verified
against the index recipes), and a stale cs_ste_vec_v2 name is aligned to
eql_v2.ste_vec.
Each page carries v2 facets (type: reference, components: [eql],
verifiedAgainst eql 2.2) and a version banner routing new projects to the
v3 reference. Wired into the EQL nav under a "Previous versions" separator.
Supersedes #21 and #22 for the v2 branch.
Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
The `auth regions --json` flag description is "Emit machine-readable
[{ slug, label }] ...". MDX parsed `{ slug, label }` as a JS expression,
so prerendering /reference/cli/auth threw `ReferenceError: slug is not
defined` and failed the build. (The earlier `<tt>` failure masked this;
it surfaced once #52 landed via rebase.)
Escape `{`/`}` (and stray `<`) in manifest-derived prose — flag
descriptions and summaries. Flag names/values stay in code spans, which
are literal, so they're untouched. Verified: `next build` prerenders all
355 pages, including /reference/cli/auth.
Vercel preview feedback on /reference/cli/auth: - Remove the "--supabase / --drizzle flags only tag the referrer" paragraph. - Convert the "Good to know" blockquote into a proper <Callout title=...>. Edited the auth supplement (the page is generated from it) and recast the em-dashes in the touched prose. Verified: next build prerenders all 355 pages.
- loadRawManifest: validate the JSON delimiters before slicing, throwing a clear error (which falls back to the fixture) instead of feeding garbage to JSON.parse. - Reconcile CLI_VERSION to the loaded manifest's version after loading, so pages are stamped with the version of the data actually used — including the fixture-fallback path, where npm-latest and the cached manifest can differ.
docs(v2): generate the CLI reference from `stash manifest --json`
The header comment carried an internal issue id; remove it so no private tracker reference lives in this public repo. Comment-only.
chore(cli-docs): drop the internal tracker ref from the generator header
docs(v2): add nested EQL v2 reference for existing v2.2 deployments
…-lint Consumes the eql-manifest.json the EQL repo emits from its Doxygen'd SQL (cipherstash/encrypt-query-language#364) to: - generate content/docs/reference/eql/functions.mdx — a version-stamped, drift-proof catalog of the eql_v3 function surface that the hand-written pedagogical pages link to (added to the EQL nav under "Reference"); - drift-lint the hand-written pages: every `eql_v3.<fn>(...)` they reference should exist in the manifest for the shipped EQL version. This is what would have caught the fabricated function names / stale payload that slipped into the v2 docs. Wired into prebuild. Reads an illustrative sample fixture today (so the format and lint are reviewable now); swaps to the real json/eql-manifest.json from the eql-docs release asset once #364 ships — generate-eql-docs.ts already downloads that tarball. The lint is report-only against the sample and becomes a failing gate once wired to the real manifest (STRICT). Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
…t to domains The generated functions.mdx now leads with the encrypted-domain variant matrix (domain × type × variant → capabilities → index terms), consumed from the manifest's new `domains` array (cipherstash/encrypt-query-language#364). The drift-lint now covers domain-type references too, not just function calls. Running it surfaced a real mismatch worth fixing: the hand-written v3 pages reference eql_v3.int4_*/int8_*/float4_*/float8_* domains, but the shipped SQL defines eql_v3.integer_*/bigint_*/real_*/double_* — so casts like $1::eql_v3.int8_ord would fail. Docs-vs-codegen naming needs reconciling; this is exactly the drift the lint exists to catch. Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
Matches the manifest change in encrypt-query-language#364: domains now come from the Rust catalog (`eql-codegen dump-catalog`), carrying authoritative type names and the exact `supportedOperators` per domain (replacing the CHECK-key-derived `terms`/`termFunctions`). The generated variant matrix renders an Operators column; the sample fixture is updated to match. Note `_ord` correctly shows equality + order now (ORE collapses to equality). Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
Matches encrypt-query-language#368 (stacked on #364): the manifest now carries the 3 jsonb (SteVec) domains and per-domain `termFunctions`. The variant matrix renders the jsonb domains (json capability), and the drift-lint adds each domain's extractor functions (eq_term / ord_term / match_term / ord_ope_term) to its known set — resolving those false-positives (61 → 57 unknowns on the sample). Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
Wires the v2 EQL reference to the corrected manifest (public. domains, eql_v3./eql_v3_internal. functions — cipherstash/encrypt-query-language#369) and turns the drift-lint into a real gate. - generate-eql-api-docs.ts: schema-aware drift-lint — matches public.<domain>, eql_v3.<fn>, eql_v3_internal.<fn> by schema AND name, so right-name/wrong-schema refs are caught, not just fabricated ones. Group public overloads by name (the raw 1680-function surface -> 39 functions); omit internal functions from the page (kept in the lint's known set). Manifest source: EQL_MANIFEST_PATH -> release cache -> sample, auto-strict against any real manifest. - generate-eql-docs.ts: extract json/eql-manifest.json from the release tarball to a gitignored cache the reference generator reads (best-effort; falls back to the sample until a release ships the manifest). - Swept content/docs/reference/eql/*.mdx (165 refs): domains -> public., internal ctors -> eql_v3_internal., PG aliases -> canonical catalog names (int4->integer, float8->double, bool->boolean, ste_vec_*->jsonb_*). - Updated the illustrative sample fixture to the corrected schema. Drift-lint verified green against a locally-generated corrected manifest; report-only against the committed sample until a release ships the manifest. Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
Follow-ups from reviewing the rendered preview: - Variant tables used the eql_v3.<T> placeholder (booleans, core-concepts, dates-and-times, grouping-and-aggregates, indexes, numbers) — the concrete- token sweep missed it. Now public.<T>. - core-concepts: new 'The three schemas' section — public (encrypted domain types, kept in an unversioned schema so EQL upgrades don't rewrite your column types), eql_v3 (user-callable functions/operators), eql_v3_internal (implementation, don't call). Fixed prose that placed the domains and the SEM index-term types in eql_v3 (they're public / eql_v3_internal). - index: domains are public not eql_v3; corrected the uninstall Callout — DROP SCHEMA eql_v3, eql_v3_internal CASCADE removes operators/functions but leaves the public.* types + columns (data survives), where the old text claimed dropping eql_v3 drops the columns. - Grammar: 'an public.*' -> 'a public.*' left over from the schema sweep. Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
EQL v3 moved the query-operand domains into the eql_v3 schema and renamed them to the query_<name> prefix, shipped in eql-3.0.0-alpha.3. The jsonb containment needle is now `eql_v3.query_jsonb`; `public.jsonb_query` no longer exists. Update the two hand-written pages (filtering.mdx, json.mdx) that cast `@>` operands to it. This clears the STRICT drift-lint, which (now that alpha.3 ships a real json/eql-manifest.json) correctly flagged public.jsonb_query as absent from the manifest. Verified: drift check passes and the build compiles all pages. functions.mdx regenerates from the manifest at build.
Every EQL v3 reference page carries a shared <EqlVersion> callout stating the EQL release it's generated/validated against, with a link to the retained EQL v2 reference (/docs/reference/eql/v2) for readers still on the older generation. The version is single-sourced from the EQL release manifest: generate-eql-api-docs.ts writes the manifest's own `version` to src/lib/eql-version.ts, which the component reads. No hardcoded version — whatever the built release reports (e.g. a bare "DEV" today) is what shows, on every page including functions.mdx.
docs(v2): consume the EQL manifest — generated function catalog + drift-lint
Replace the curl + psql manual install with the Stash CLI (`npx stash eql install --eql-version 3`), validated against the cipherstash/stack main branch. Covers DATABASE_URL / --database-url, idempotent re-runs, `eql status`/`eql upgrade`, and the CLI's no-superuser auto-fallback on managed Postgres.
Add a Configuration subsection covering the two defineConfig fields (databaseUrl / client), the resolveDatabaseUrl resolution chain, and the scaffolded template. Link the inline stash.config.ts mention to it.
docs(eql): install via `stash eql install` CLI
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Long-lived integration branch for the docs V2 overhaul, tracked in CIP-3307. Opened as a draft — it merges only when the migration completes (CIP-3335); section work stacks as PRs targeting this branch, and this PR's Vercel preview is the staging site for the whole overhaul.
What's in the scaffold (CIP-3325)
IA.md— living migration checklist at the repo root: one checkbox per planned page, ticked as sections land, with the branch's working rules (how to move a page, redirect flag, URL conventions)v2docscollection (content/docs) served from the site root (/docs/get-started/…,/docs/integrations/supabase, …) via a required catch-all route. The legacy tree still serves at/docs/stack/*— both trees coexist until every section migrates, then the legacy tree is deletedtype,components,audience,integration(category / setup / pairsWith), and review-tracking fields (verifiedAgainst,reviewBy)/docs/integrations/supabase(the Supabase listing's link target)v2-redirects.mjs— full legacy→v2 map (85/85 pages covered), gated behindENABLE_V2_REDIRECTS=1so previews serve both trees during migration; the flag flips on at merge.bun run validate-redirectsis wired into prebuild: a legacy page without a mapping fails CI/docs/quickstartvanity redirect (ungated — no legacy traffic on that path).mdxraw-markdown mirror all cover the v2 tree (listed first)/reference/eql → /stack/reference/eql— its source collided with (and shadowed) the v2 page at that pathHow to review the preview
/docs/get-started,/docs/integrations/supabase,/docs/security/compliance,/docs/reference/eql(stubs for now)/docs/stack/quickstartetc..mdxto any v2 page URL;/docs/llms.txtMerge checklist (CIP-3335, end of migration)
ENABLE_V2_REDIRECTS=1set for productioncontent/stack,/stackroutes, and the legacy loader deletedhttps://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P