Docs V2: new information architecture (CIP-3307) by coderdan · Pull Request #37 · cipherstash/docs

coderdan · 2026-07-02T07:24:20Z

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)
New v2docs collection (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 deleted
Frontmatter facet model: Diátaxis type, components, audience, integration (category / setup / pairsWith), and review-tracking fields (verifiedAgainst, reviewBy)
All 8 sections scaffolded with nav + stubs, including /docs/integrations/supabase (the Supabase listing's link target)
v2-redirects.mjs — full legacy→v2 map (85/85 pages covered), gated behind ENABLE_V2_REDIRECTS=1 so previews serve both trees during migration; the flag flips on at merge. bun run validate-redirects is wired into prebuild: a legacy page without a mapping fails CI
/docs/quickstart vanity redirect (ungated — no legacy traffic on that path)
llms.txt / llms-full.txt / sitemap / .mdx raw-markdown mirror all cover the v2 tree (listed first)
Removed the AI-citation redirect /reference/eql → /stack/reference/eql — its source collided with (and shadowed) the v2 page at that path

How to review the preview

New tree: /docs/get-started, /docs/integrations/supabase, /docs/security/compliance, /docs/reference/eql (stubs for now)
Legacy tree unchanged: /docs/stack/quickstart etc.
Agent surface: append .mdx to any v2 page URL; /docs/llms.txt

Merge checklist (CIP-3335, end of migration)

All IA.md sections ticked; every redirect destination resolves
ENABLE_V2_REDIRECTS=1 set for production
content/stack, /stack routes, and the legacy loader deleted
Final consistency sweep + Supabase listing revision

https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

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

vercel · 2026-07-02T07:24:26Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
public-docs	Ready	Preview, Comment	Jul 2, 2026 8:42am

…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

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

Copilot

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 v2docs collection + v2source loader, plus root catch-all routes/layout for the v2 docs tree.
Introduce a full legacy→v2 redirect map (v2-redirects.mjs) gated by ENABLE_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, .mdx raw 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.

+  <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." />


+- **Moving a page = ** move the file into `content/docs`, update its facets,
+  fix inbound links, confirm its `v2-redirects.mjs` entry, tick it here.


coderdan added 2 commits July 2, 2026 17:17

vercel Bot deployed to Preview July 2, 2026 07:44 View deployment

docs(v2): note landing-page state in IA.md checklist

5c34cef

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

vercel Bot deployed to Preview July 2, 2026 07:46 View deployment

vercel Bot deployed to Preview July 2, 2026 07:55 View deployment

vercel Bot deployed to Preview July 2, 2026 08:34 View deployment

coderdan requested a review from Copilot July 2, 2026 08:40

Copilot started reviewing on behalf of coderdan July 2, 2026 08:40 View session

vercel Bot deployed to Preview July 2, 2026 08:42 View deployment

Copilot AI reviewed Jul 2, 2026

View reviewed changes

coderdan mentioned this pull request Jul 2, 2026

Docs V2: EQL v3 reference section (CIP-3326) #38

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Docs V2: new information architecture (CIP-3307)#37

Docs V2: new information architecture (CIP-3307)#37
coderdan wants to merge 7 commits into
mainfrom
v2

coderdan commented Jul 2, 2026

Uh oh!

vercel Bot commented Jul 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		- Moving a page = move the file into `content/docs`, update its facets,
		fix inbound links, confirm its `v2-redirects.mjs` entry, tick it here.

Uh oh!

Conversation

coderdan commented Jul 2, 2026

What's in the scaffold (CIP-3325)

How to review the preview

Merge checklist (CIP-3335, end of migration)

Uh oh!

vercel Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented Jul 2, 2026 •

edited

Loading