diff --git a/content/docs/agents.mdx b/content/docs/engine/agents/index.mdx
similarity index 99%
rename from content/docs/agents.mdx
rename to content/docs/engine/agents/index.mdx
index fdcccb4..31c979d 100644
--- a/content/docs/agents.mdx
+++ b/content/docs/engine/agents/index.mdx
@@ -3,7 +3,6 @@ title: Agents
 description: 40 agents across 4 tiers — from captain to specialists
 ---
 
-# Agents
 
 40 specialized agents organized in a 4-tier hierarchy. The top 9 leadership agents manage business, product, and technical strategy. The bottom 31 specialist agents handle execution across stack, design, UI, DevOps, VCS, and domain expertise.
 
diff --git a/content/docs/engine/agents/meta.json b/content/docs/engine/agents/meta.json
new file mode 100644
index 0000000..1e773ce
--- /dev/null
+++ b/content/docs/engine/agents/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Agents",
+  "pages": ["index"]
+}
diff --git a/content/docs/claude-md.mdx b/content/docs/engine/claude-md.mdx
similarity index 99%
rename from content/docs/claude-md.mdx
rename to content/docs/engine/claude-md.mdx
index 07a1103..d201641 100644
--- a/content/docs/claude-md.mdx
+++ b/content/docs/engine/claude-md.mdx
@@ -3,7 +3,6 @@ title: CLAUDE.md
 description: Project instructions that shape every response — the 3-layer hierarchy
 ---
 
-# CLAUDE.md
 
 The most powerful configuration primitive in Claude Code. A markdown file that shapes every response, every agent, every workflow. Kun uses a 3-layer hierarchy that cascades from global preferences down to repo-specific operations.
 
diff --git a/content/docs/commands.mdx b/content/docs/engine/commands.mdx
similarity index 99%
rename from content/docs/commands.mdx
rename to content/docs/engine/commands.mdx
index 786aa51..ea5338d 100644
--- a/content/docs/commands.mdx
+++ b/content/docs/engine/commands.mdx
@@ -3,7 +3,6 @@ title: Commands
 description: Slash commands for rapid workflows
 ---
 
-# Commands
 
 Type `/command` in Claude Code to trigger a complete workflow. Commands are markdown templates in `~/.claude/commands/` that expand into full prompts with agent routing and MCP integration.
 
diff --git a/content/docs/hooks.mdx b/content/docs/engine/hooks.mdx
similarity index 99%
rename from content/docs/hooks.mdx
rename to content/docs/engine/hooks.mdx
index 93af356..3f59d43 100644
--- a/content/docs/hooks.mdx
+++ b/content/docs/engine/hooks.mdx
@@ -3,7 +3,6 @@ title: Hooks
 description: Lifecycle automations that trigger on events
 ---
 
-# Hooks
 
 5 hooks that automate repetitive actions across the development lifecycle. They fire on specific events — before a tool runs, after a file changes, when a session ends.
 
diff --git a/content/docs/keywords.mdx b/content/docs/engine/keywords.mdx
similarity index 97%
rename from content/docs/keywords.mdx
rename to content/docs/engine/keywords.mdx
index 8de6f00..f6771dc 100644
--- a/content/docs/keywords.mdx
+++ b/content/docs/engine/keywords.mdx
@@ -3,7 +3,6 @@ title: The Standard Book of Spells
 description: 114 incantations that bend code to your will — the complete Kun spellbook
 ---
 
-# The Standard Book of Spells
 
 > *"It does not do to dwell on documentation and forget to ship."*
 
diff --git a/content/docs/mcp.mdx b/content/docs/engine/mcp.mdx
similarity index 99%
rename from content/docs/mcp.mdx
rename to content/docs/engine/mcp.mdx
index b4cc3ca..af3c538 100644
--- a/content/docs/mcp.mdx
+++ b/content/docs/engine/mcp.mdx
@@ -3,7 +3,6 @@ title: MCP
 description: 18 MCP servers connecting Claude Code to external services
 ---
 
-# MCP Servers
 
 18 Model Context Protocol servers that connect Claude Code to external services — from design tools to databases to deployment platforms.
 
diff --git a/content/docs/memory.mdx b/content/docs/engine/memory.mdx
similarity index 99%
rename from content/docs/memory.mdx
rename to content/docs/engine/memory.mdx
index 4bf67fa..b0ba9b0 100644
--- a/content/docs/memory.mdx
+++ b/content/docs/engine/memory.mdx
@@ -3,7 +3,6 @@ title: Memory
 description: Persistent files that carry context across sessions
 ---
 
-# Memory
 
 6 memory files that persist across conversations. They store component registries, team profiles, and project state — so Claude never forgets what was built, who's on the team, or what patterns exist.
 
diff --git a/content/docs/engine/meta.json b/content/docs/engine/meta.json
new file mode 100644
index 0000000..6faa79d
--- /dev/null
+++ b/content/docs/engine/meta.json
@@ -0,0 +1,14 @@
+{
+  "title": "Engine",
+  "pages": [
+    "claude-md",
+    "agents",
+    "skills",
+    "commands",
+    "mcp",
+    "hooks",
+    "rules",
+    "memory",
+    "keywords"
+  ]
+}
diff --git a/content/docs/rules.mdx b/content/docs/engine/rules.mdx
similarity index 99%
rename from content/docs/rules.mdx
rename to content/docs/engine/rules.mdx
index 3099f71..249b39f 100644
--- a/content/docs/rules.mdx
+++ b/content/docs/engine/rules.mdx
@@ -3,7 +3,6 @@ title: Rules
 description: Path-scoped rules that activate on file touch
 ---
 
-# Rules
 
 8 rules that auto-activate when you touch specific file patterns. Each rule injects domain knowledge and constraints for its area — authentication, i18n, database, styling, testing, deployment.
 
diff --git a/content/docs/skills.mdx b/content/docs/engine/skills.mdx
similarity index 99%
rename from content/docs/skills.mdx
rename to content/docs/engine/skills.mdx
index 6d50097..45b2784 100644
--- a/content/docs/skills.mdx
+++ b/content/docs/engine/skills.mdx
@@ -3,7 +3,6 @@ title: Skills
 description: 25 reusable skills with keyword triggers
 ---
 
-# Skills
 
 25 slash commands that trigger complete workflows. Say a keyword or type `/command` — the engine handles the rest.
 
diff --git a/content/docs/index.mdx b/content/docs/index.mdx
index 1260b0d..6fe62f4 100644
--- a/content/docs/index.mdx
+++ b/content/docs/index.mdx
@@ -3,7 +3,6 @@ title: Introduction
 description: Kun (كن) — The Databayt Engine
 ---
 
-# Kun (كن)
 
 > The optimal configuration that makes Claude Code, Claude Desktop, Cowork, and the Agent SDK work together as a single engine running both the technical and business sides of **Databayt**.
 
diff --git a/content/docs/claude-code.mdx b/content/docs/installation/claude-code.mdx
similarity index 100%
rename from content/docs/claude-code.mdx
rename to content/docs/installation/claude-code.mdx
diff --git a/content/docs/onboarding.mdx b/content/docs/installation/index.mdx
similarity index 92%
rename from content/docs/onboarding.mdx
rename to content/docs/installation/index.mdx
index ba3bba5..ecafa31 100644
--- a/content/docs/onboarding.mdx
+++ b/content/docs/installation/index.mdx
@@ -3,7 +3,6 @@ title: Onboarding
 description: Install Cowork, let it do the rest
 ---
 
-# Onboarding
 
 > One install, one paste, one watch. Cowork drives every other step.
 
@@ -151,19 +150,19 @@ For hogwarts, your team contact shares the `.env` out-of-band (no `.env.example`
 | Open a GitHub issue | `c "/issue"` |
 | Verify a production deploy | `c "/watch"` |
 
-Full keyword list: [keywords](/docs/keywords).
+Full keyword list: [keywords](/docs/engine/keywords).
 
 ---
 
 ## Reference
 
 - [Computer use in Desktop](https://code.claude.com/docs/en/desktop#let-claude-use-your-computer)
-- [Claude Code — install detail](/docs/claude-code)
-- [Captain — decisions and delegation](/docs/captain)
-- [Cowork ↔ Code bridge](/docs/cowork)
-- [Connectors — MCP catalog](/docs/connectors)
+- [Claude Code — install detail](/docs/installation/claude-code)
+- [Captain — decisions and delegation](/docs/operations/captain)
+- [Cowork ↔ Code bridge](/docs/operations/cowork)
+- [Connectors — MCP catalog](/docs/operations/connectors)
 - [Anthropic Directory](https://claude.ai/directory)
-- [Keywords — full vocabulary](/docs/keywords)
-- [Team — roles](/docs/team)
-- [Repositories — full org map](/docs/repositories)
+- [Keywords — full vocabulary](/docs/engine/keywords)
+- [Team — roles](/docs/operations/team)
+- [Repositories — full org map](/docs/reference/repositories)
 - [Contributing — github-workflow rule](https://github.com/databayt/kun/blob/main/.claude/rules/github-workflow.md)
diff --git a/content/docs/installation/meta.json b/content/docs/installation/meta.json
new file mode 100644
index 0000000..bde1477
--- /dev/null
+++ b/content/docs/installation/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Installation",
+  "pages": ["index", "claude-code", "self-hosting"]
+}
diff --git a/content/docs/self-hosting.mdx b/content/docs/installation/self-hosting.mdx
similarity index 98%
rename from content/docs/self-hosting.mdx
rename to content/docs/installation/self-hosting.mdx
index 115bbfe..f217c74 100644
--- a/content/docs/self-hosting.mdx
+++ b/content/docs/installation/self-hosting.mdx
@@ -3,7 +3,6 @@ title: Self-Hosting
 description: Optional infrastructure for air-gapped or dedicated server deployments
 ---
 
-# Self-Hosting (Optional)
 
 > **Status**: Optional appendix. Anthropic-native products handle 90%+ of use cases.
 > **When relevant**: Air-gapped environments, data residency, or dedicated server preference.
diff --git a/content/docs/meta.json b/content/docs/meta.json
index 2579331..146d8b6 100644
--- a/content/docs/meta.json
+++ b/content/docs/meta.json
@@ -2,43 +2,15 @@
   "title": "Documentation",
   "pages": [
     "index",
+    "---Getting Started---",
+    "installation",
     "---Engine---",
-    "claude-md",
-    "agents",
-    "skills",
-    "commands",
-    "mcp",
-    "hooks",
-    "rules",
-    "memory",
+    "engine",
     "---Operations---",
-    "captain",
-    "team",
-    "onboarding",
-    "dispatch",
-    "context",
-    "cowork",
-    "voice",
-    "credentials",
-    "connectors",
-    "apps",
-    "issue",
+    "operations",
     "---Reference---",
-    "keywords",
-    "tips",
-    "tweets",
-    "configuration",
-    "architecture",
-    "workflows",
-    "products",
-    "prd",
-    "epics",
-    "claude-code",
-    "secrets",
-    "slack",
-    "stack",
-    "repositories",
-    "projects",
-    "self-hosting"
+    "reference",
+    "---Resources---",
+    "resources"
   ]
 }
diff --git a/content/docs/apps.mdx b/content/docs/operations/apps.mdx
similarity index 99%
rename from content/docs/apps.mdx
rename to content/docs/operations/apps.mdx
index b2419d0..79827c3 100644
--- a/content/docs/apps.mdx
+++ b/content/docs/operations/apps.mdx
@@ -3,7 +3,6 @@ title: Apps
 description: Claude in Slack, Figma, and Asana
 ---
 
-# Claude Apps
 
 Anthropic's native integrations that bring Claude directly into the tools your team already uses.
 
diff --git a/content/docs/captain.mdx b/content/docs/operations/captain.mdx
similarity index 99%
rename from content/docs/captain.mdx
rename to content/docs/operations/captain.mdx
index 36d1ac4..3e5e866 100644
--- a/content/docs/captain.mdx
+++ b/content/docs/operations/captain.mdx
@@ -3,7 +3,6 @@ title: Captain
 description: CEO brain — delegates across 40 agents and 4 humans
 ---
 
-# Captain
 
 The apex agent. Captain is Databayt's CEO brain — it knows every product, every person, every dollar, every deadline. It makes the calls: what to build, who works on what, when to ship, when to cut scope.
 
diff --git a/content/docs/connectors.mdx b/content/docs/operations/connectors.mdx
similarity index 99%
rename from content/docs/connectors.mdx
rename to content/docs/operations/connectors.mdx
index 07d00b2..94a1936 100644
--- a/content/docs/connectors.mdx
+++ b/content/docs/operations/connectors.mdx
@@ -3,7 +3,6 @@ title: Connectors
 description: GitHub, Figma, Slack, Linear and service integrations
 ---
 
-# Connectors
 
 Service integrations that connect Kun to external platforms. Each connector is backed by an MCP server and triggered by keywords.
 
diff --git a/content/docs/context.mdx b/content/docs/operations/context.mdx
similarity index 99%
rename from content/docs/context.mdx
rename to content/docs/operations/context.mdx
index 5c45ef3..50e93f1 100644
--- a/content/docs/context.mdx
+++ b/content/docs/operations/context.mdx
@@ -3,7 +3,6 @@ title: Context
 description: Cloud tag control room — sprint-aware, contributor-aware keyword dispatch for all 4 team members
 ---
 
-# Context
 
 Cloud tag UI where any team member clicks a keyword and dispatches a workflow. The cloud adapts to who's viewing and what stories are active — keywords grow or shrink based on relevance.
 
diff --git a/content/docs/cowork.mdx b/content/docs/operations/cowork.mdx
similarity index 99%
rename from content/docs/cowork.mdx
rename to content/docs/operations/cowork.mdx
index a67b438..56c53b4 100644
--- a/content/docs/cowork.mdx
+++ b/content/docs/operations/cowork.mdx
@@ -3,7 +3,6 @@ title: Cowork
 description: Same brain, two modes — one thinks, one acts
 ---
 
-# Cowork
 
 Cowork and Claude Code are two modes of the same brain. They share everything in `~/.claude/` — agents, memory, settings, rules. The difference is posture.
 
diff --git a/content/docs/credentials.mdx b/content/docs/operations/credentials.mdx
similarity index 99%
rename from content/docs/credentials.mdx
rename to content/docs/operations/credentials.mdx
index a9c5b63..a2da360 100644
--- a/content/docs/credentials.mdx
+++ b/content/docs/operations/credentials.mdx
@@ -3,7 +3,6 @@ title: Credentials
 description: Keychain-based API key management for 18 services
 ---
 
-# Credentials
 
 macOS Keychain-based credential management. API keys stored encrypted, retrieved via the `security` command, never in plain text files.
 
diff --git a/content/docs/dispatch.mdx b/content/docs/operations/dispatch.mdx
similarity index 99%
rename from content/docs/dispatch.mdx
rename to content/docs/operations/dispatch.mdx
index 70cc6c6..0980ba4 100644
--- a/content/docs/dispatch.mdx
+++ b/content/docs/operations/dispatch.mdx
@@ -3,7 +3,6 @@ title: Dispatch
 description: Apple Notes async communication — 3 channels for team coordination
 ---
 
-# Dispatch
 
 Async communication via Apple Notes. Three notes in a Dispatch folder, synced via iCloud to all Apple devices. Captain writes updates, Cowork bridges think/do, Abdout leaves instructions.
 
diff --git a/content/docs/issue.mdx b/content/docs/operations/issue.mdx
similarity index 99%
rename from content/docs/issue.mdx
rename to content/docs/operations/issue.mdx
index 25aade3..3fed2b6 100644
--- a/content/docs/issue.mdx
+++ b/content/docs/operations/issue.mdx
@@ -3,7 +3,6 @@ title: Issue
 description: Issue pipeline — from user report to auto-fix, including Report an Issue dialog, report agent, and scheduled automation
 ---
 
-# Issue
 
 The issue pipeline connects user-reported bugs to automated fixes. Users click "Report an Issue" in the UI, a GitHub issue is created, and the report agent processes it.
 
diff --git a/content/docs/operations/meta.json b/content/docs/operations/meta.json
new file mode 100644
index 0000000..1c6f257
--- /dev/null
+++ b/content/docs/operations/meta.json
@@ -0,0 +1,15 @@
+{
+  "title": "Operations",
+  "pages": [
+    "captain",
+    "team",
+    "dispatch",
+    "context",
+    "cowork",
+    "voice",
+    "credentials",
+    "connectors",
+    "apps",
+    "issue"
+  ]
+}
diff --git a/content/docs/team.mdx b/content/docs/operations/team.mdx
similarity index 99%
rename from content/docs/team.mdx
rename to content/docs/operations/team.mdx
index 6e7a587..7c8a8d7 100644
--- a/content/docs/team.mdx
+++ b/content/docs/operations/team.mdx
@@ -3,7 +3,6 @@ title: Team
 description: 4 roles with tailored MCP configs and agent indexes
 ---
 
-# Team
 
 4 humans with tailored tools. Each role gets a specific MCP config, skill set, and agent index — so everyone has exactly the tools they need, nothing more.
 
diff --git a/content/docs/voice.mdx b/content/docs/operations/voice.mdx
similarity index 99%
rename from content/docs/voice.mdx
rename to content/docs/operations/voice.mdx
index fcd8442..4cc2746 100644
--- a/content/docs/voice.mdx
+++ b/content/docs/operations/voice.mdx
@@ -3,7 +3,6 @@ title: Voice
 description: Speak commands instead of typing them
 ---
 
-# Voice
 
 Voice input across all Anthropic surfaces — Claude Desktop, iOS, and system-level dictation. Say what you want, Claude does it.
 
diff --git a/content/docs/architecture.mdx b/content/docs/reference/architecture.mdx
similarity index 99%
rename from content/docs/architecture.mdx
rename to content/docs/reference/architecture.mdx
index 374d6d8..9e06240 100644
--- a/content/docs/architecture.mdx
+++ b/content/docs/reference/architecture.mdx
@@ -3,7 +3,6 @@ title: Architecture
 description: 5-layer Anthropic-native engine architecture for Databayt
 ---
 
-# Architecture
 
 Kun is a **configuration engine** — not a server. It sits as the configuration layer on top of Anthropic's product suite, running both technical and business sides of **Databayt**.
 
diff --git a/content/docs/configuration.mdx b/content/docs/reference/configuration.mdx
similarity index 99%
rename from content/docs/configuration.mdx
rename to content/docs/reference/configuration.mdx
index fce57d7..73f23fe 100644
--- a/content/docs/configuration.mdx
+++ b/content/docs/reference/configuration.mdx
@@ -3,7 +3,6 @@ title: Configuration
 description: The engine blueprint — every setting, agent, skill, hook, MCP, rule, and memory
 ---
 
-# Configuration Blueprint
 
 This IS the engine. Every setting, agent, skill, hook, MCP server, rule, and memory file that transforms Anthropic's products into Databayt's operating system.
 
diff --git a/content/docs/epics.mdx b/content/docs/reference/epics.mdx
similarity index 99%
rename from content/docs/epics.mdx
rename to content/docs/reference/epics.mdx
index d7deb77..5712fd8 100644
--- a/content/docs/epics.mdx
+++ b/content/docs/reference/epics.mdx
@@ -3,7 +3,6 @@ title: Epics
 description: 57 stories across 12 epics with sprint plan for April-June 2026
 ---
 
-# Epics & Stories
 
 57 stories across 12 epics, organized by phase. Sprints run April-June 2026.
 
diff --git a/content/docs/reference/meta.json b/content/docs/reference/meta.json
new file mode 100644
index 0000000..8814e15
--- /dev/null
+++ b/content/docs/reference/meta.json
@@ -0,0 +1,16 @@
+{
+  "title": "Reference",
+  "pages": [
+    "configuration",
+    "architecture",
+    "workflows",
+    "products",
+    "prd",
+    "epics",
+    "repositories",
+    "projects",
+    "stack",
+    "slack",
+    "secrets"
+  ]
+}
diff --git a/content/docs/prd.mdx b/content/docs/reference/prd.mdx
similarity index 99%
rename from content/docs/prd.mdx
rename to content/docs/reference/prd.mdx
index dfc34be..93dc684 100644
--- a/content/docs/prd.mdx
+++ b/content/docs/reference/prd.mdx
@@ -3,7 +3,6 @@ title: PRD
 description: Configuration requirements by phase for the Kun engine
 ---
 
-# Product Requirements
 
 Requirements for Kun — the configuration engine running Databayt's operations across a 4-person team, 14 repositories, and 5 products.
 
diff --git a/content/docs/products.mdx b/content/docs/reference/products.mdx
similarity index 99%
rename from content/docs/products.mdx
rename to content/docs/reference/products.mdx
index fa80ec2..a2acdcb 100644
--- a/content/docs/products.mdx
+++ b/content/docs/reference/products.mdx
@@ -3,7 +3,6 @@ title: Anthropic Products
 description: Complete product catalog mapped to Databayt's team and operations
 ---
 
-# Anthropic Product Catalog
 
 Every Anthropic product mapped to its role in Databayt's operations — who uses what and why.
 
diff --git a/content/docs/projects.mdx b/content/docs/reference/projects.mdx
similarity index 99%
rename from content/docs/projects.mdx
rename to content/docs/reference/projects.mdx
index 4a69cb0..dd6f32c 100644
--- a/content/docs/projects.mdx
+++ b/content/docs/reference/projects.mdx
@@ -3,7 +3,6 @@ title: Projects
 description: Browse and clone open projects from the databayt organization
 ---
 
-# Open Projects
 
 All projects in the [databayt](https://github.com/databayt) organization are available for team development.
 
diff --git a/content/docs/repositories.mdx b/content/docs/reference/repositories.mdx
similarity index 100%
rename from content/docs/repositories.mdx
rename to content/docs/reference/repositories.mdx
diff --git a/content/docs/secrets.mdx b/content/docs/reference/secrets.mdx
similarity index 99%
rename from content/docs/secrets.mdx
rename to content/docs/reference/secrets.mdx
index 1c46996..8691e92 100644
--- a/content/docs/secrets.mdx
+++ b/content/docs/reference/secrets.mdx
@@ -3,7 +3,6 @@ title: Secrets
 description: API keys, tokens, and environment setup for the Kun engine
 ---
 
-# Secrets & Environment
 
 Secrets needed for the Kun engine's MCP servers and Anthropic products.
 
diff --git a/content/docs/slack.mdx b/content/docs/reference/slack.mdx
similarity index 99%
rename from content/docs/slack.mdx
rename to content/docs/reference/slack.mdx
index bcf15f0..fff1cee 100644
--- a/content/docs/slack.mdx
+++ b/content/docs/reference/slack.mdx
@@ -3,7 +3,6 @@ title: Slack
 description: Team communication setup — workspace, channels, MCP integration
 ---
 
-# Slack
 
 Team communication hub for Databayt. Connected to Claude Code via MCP for notifications, dispatch, and collaboration.
 
diff --git a/content/docs/stack.mdx b/content/docs/reference/stack.mdx
similarity index 99%
rename from content/docs/stack.mdx
rename to content/docs/reference/stack.mdx
index 7b4a716..e186a7f 100644
--- a/content/docs/stack.mdx
+++ b/content/docs/reference/stack.mdx
@@ -3,7 +3,6 @@ title: Stack
 description: Unified technology stack across all Databayt repositories
 ---
 
-# Stack
 
 The unified technology stack across all 14 Databayt repositories.
 
diff --git a/content/docs/workflows.mdx b/content/docs/reference/workflows.mdx
similarity index 99%
rename from content/docs/workflows.mdx
rename to content/docs/reference/workflows.mdx
index fad6985..d71deeb 100644
--- a/content/docs/workflows.mdx
+++ b/content/docs/reference/workflows.mdx
@@ -3,7 +3,6 @@ title: Workflows
 description: How keywords chain together — from morning start to production deploy
 ---
 
-# Workflows
 
 How keywords chain together into complete operations. Single words are charms. Sequences are rituals.
 
diff --git a/content/docs/resources/meta.json b/content/docs/resources/meta.json
new file mode 100644
index 0000000..0a6fd72
--- /dev/null
+++ b/content/docs/resources/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Resources",
+  "pages": ["tips", "tweets"]
+}
diff --git a/content/docs/tips.mdx b/content/docs/resources/tips.mdx
similarity index 99%
rename from content/docs/tips.mdx
rename to content/docs/resources/tips.mdx
index 303555b..930d657 100644
--- a/content/docs/tips.mdx
+++ b/content/docs/resources/tips.mdx
@@ -3,7 +3,6 @@ title: Tips
 description: Master-level techniques and advanced workflows
 ---
 
-# Tips
 
 Advanced techniques for getting the most out of Claude Code and the Kun engine.
 
diff --git a/content/docs/tweets.mdx b/content/docs/resources/tweets.mdx
similarity index 99%
rename from content/docs/tweets.mdx
rename to content/docs/resources/tweets.mdx
index 643b525..4cc0c09 100644
--- a/content/docs/tweets.mdx
+++ b/content/docs/resources/tweets.mdx
@@ -3,7 +3,6 @@ title: Tweets
 description: Track Claude Code updates and tips on X
 ---
 
-# Tweets
 
 Key voices and accounts to follow for Claude Code updates, tips, and announcements.
 
diff --git a/next.config.ts b/next.config.ts
index b4d984b..8ed2ccd 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -1,11 +1,57 @@
 import type { NextConfig } from "next";
 import { createMDX } from "fumadocs-mdx/next";
 
+// Old flat slug → new nested slug. Flat docs were restructured into shadcn-style sections.
+// Keep these as 307 (permanent: false) for ~7 days, then flip to 301 once external referrers settle.
+const DOCS_REDIRECTS: Array<[string, string]> = [
+  ["onboarding", "installation"],
+  ["claude-code", "installation/claude-code"],
+  ["self-hosting", "installation/self-hosting"],
+  ["claude-md", "engine/claude-md"],
+  ["agents", "engine/agents"],
+  ["skills", "engine/skills"],
+  ["commands", "engine/commands"],
+  ["mcp", "engine/mcp"],
+  ["hooks", "engine/hooks"],
+  ["rules", "engine/rules"],
+  ["memory", "engine/memory"],
+  ["keywords", "engine/keywords"],
+  ["captain", "operations/captain"],
+  ["team", "operations/team"],
+  ["dispatch", "operations/dispatch"],
+  ["context", "operations/context"],
+  ["cowork", "operations/cowork"],
+  ["voice", "operations/voice"],
+  ["credentials", "operations/credentials"],
+  ["connectors", "operations/connectors"],
+  ["apps", "operations/apps"],
+  ["issue", "operations/issue"],
+  ["configuration", "reference/configuration"],
+  ["architecture", "reference/architecture"],
+  ["workflows", "reference/workflows"],
+  ["products", "reference/products"],
+  ["prd", "reference/prd"],
+  ["epics", "reference/epics"],
+  ["repositories", "reference/repositories"],
+  ["projects", "reference/projects"],
+  ["stack", "reference/stack"],
+  ["slack", "reference/slack"],
+  ["secrets", "reference/secrets"],
+  ["tips", "resources/tips"],
+  ["tweets", "resources/tweets"],
+];
+
 const nextConfig: NextConfig = {
   typescript: {
     ignoreBuildErrors: true,
   },
   reactStrictMode: false,
+  async redirects() {
+    return DOCS_REDIRECTS.flatMap(([from, to]) => [
+      { source: `/docs/${from}`, destination: `/docs/${to}`, permanent: false },
+      { source: `/:lang/docs/${from}`, destination: `/:lang/docs/${to}`, permanent: false },
+    ]);
+  },
 };
 
 const withMDX = createMDX();
diff --git a/package.json b/package.json
index 64874f2..e5e3b88 100644
--- a/package.json
+++ b/package.json
@@ -9,6 +9,7 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
+    "docs:check": "node scripts/check-docs-links.mjs",
     "postinstall": "fumadocs-mdx",
     "setup:phase1": "bash scripts/phase1/setup.sh",
     "setup:phase2": "sudo bash scripts/phase2/setup.sh",
diff --git a/scripts/check-docs-links.mjs b/scripts/check-docs-links.mjs
new file mode 100644
index 0000000..5053252
--- /dev/null
+++ b/scripts/check-docs-links.mjs
@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { join, relative } from "node:path"
+
+const ROOT = "content/docs"
+
+function walk(dir, files = []) {
+  for (const e of readdirSync(dir)) {
+    const p = join(dir, e)
+    if (statSync(p).isDirectory()) walk(p, files)
+    else if (p.endsWith(".mdx")) files.push(p)
+  }
+  return files
+}
+
+const files = walk(ROOT)
+
+// Build the set of valid /docs/* slugs from disk
+const slugs = new Set(["/docs"])
+for (const f of files) {
+  const rel = relative(ROOT, f).replace(/\\/g, "/")
+  const slug = "/docs/" + rel.replace(/\/index\.mdx$/, "").replace(/\.mdx$/, "")
+  // Root index.mdx → /docs (already added)
+  if (slug === "/docs/index") {
+    continue
+  }
+  slugs.add(slug)
+}
+
+// Scan each file for markdown links to /docs/*
+const LINK_RE = /\]\((\/docs\/[^)\s#]*)/g
+let broken = 0
+for (const f of files) {
+  const content = readFileSync(f, "utf8")
+  for (const m of content.matchAll(LINK_RE)) {
+    const target = m[1].replace(/\/$/, "")
+    if (!slugs.has(target)) {
+      console.log(`BROKEN ${f}: ${target}`)
+      broken++
+    }
+  }
+}
+
+if (broken > 0) {
+  console.error(`\n${broken} broken docs link${broken === 1 ? "" : "s"}.`)
+  process.exit(1)
+}
+console.log(`OK: ${files.length} files, ${slugs.size} slugs, 0 broken links.`)
diff --git a/src/components/docs/docs-sidebar.tsx b/src/components/docs/docs-sidebar.tsx
index 6a72b58..53c305b 100644
--- a/src/components/docs/docs-sidebar.tsx
+++ b/src/components/docs/docs-sidebar.tsx
@@ -21,53 +21,64 @@ type DocSection = { title: string; items: DocEntry[] }
 
 const DOCS_NAV: (DocEntry | DocSection)[] = [
   { href: "/docs", label: "Introduction" },
+  {
+    title: "Getting Started",
+    items: [
+      { href: "/docs/installation", label: "Installation" },
+      { href: "/docs/installation/claude-code", label: "Claude Code" },
+      { href: "/docs/installation/self-hosting", label: "Self-Hosting" },
+    ],
+  },
   {
     title: "Engine",
     items: [
-      { href: "/docs/claude-md", label: "CLAUDE.md" },
-      { href: "/docs/agents", label: "Agents" },
-      { href: "/docs/skills", label: "Skills" },
-      { href: "/docs/commands", label: "Commands" },
-      { href: "/docs/mcp", label: "MCP" },
-      { href: "/docs/hooks", label: "Hooks" },
-      { href: "/docs/rules", label: "Rules" },
-      { href: "/docs/memory", label: "Memory" },
+      { href: "/docs/engine/claude-md", label: "CLAUDE.md" },
+      { href: "/docs/engine/agents", label: "Agents" },
+      { href: "/docs/engine/skills", label: "Skills" },
+      { href: "/docs/engine/commands", label: "Commands" },
+      { href: "/docs/engine/mcp", label: "MCP" },
+      { href: "/docs/engine/hooks", label: "Hooks" },
+      { href: "/docs/engine/rules", label: "Rules" },
+      { href: "/docs/engine/memory", label: "Memory" },
+      { href: "/docs/engine/keywords", label: "Keywords" },
     ],
   },
   {
     title: "Operations",
     items: [
-      { href: "/docs/captain", label: "Captain" },
-      { href: "/docs/team", label: "Team" },
-      { href: "/docs/dispatch", label: "Dispatch" },
-      { href: "/docs/context", label: "Context" },
-      { href: "/docs/cowork", label: "Cowork" },
-      { href: "/docs/voice", label: "Voice" },
-      { href: "/docs/credentials", label: "Credentials" },
-      { href: "/docs/connectors", label: "Connectors" },
-      { href: "/docs/apps", label: "Apps" },
-      { href: "/docs/issue", label: "Issue" },
+      { href: "/docs/operations/captain", label: "Captain" },
+      { href: "/docs/operations/team", label: "Team" },
+      { href: "/docs/operations/dispatch", label: "Dispatch" },
+      { href: "/docs/operations/context", label: "Context" },
+      { href: "/docs/operations/cowork", label: "Cowork" },
+      { href: "/docs/operations/voice", label: "Voice" },
+      { href: "/docs/operations/credentials", label: "Credentials" },
+      { href: "/docs/operations/connectors", label: "Connectors" },
+      { href: "/docs/operations/apps", label: "Apps" },
+      { href: "/docs/operations/issue", label: "Issue" },
     ],
   },
   {
     title: "Reference",
     items: [
-      { href: "/docs/keywords", label: "Keywords" },
-      { href: "/docs/tips", label: "Tips" },
-      { href: "/docs/tweets", label: "Tweets" },
-      { href: "/docs/configuration", label: "Configuration" },
-      { href: "/docs/architecture", label: "Architecture" },
-      { href: "/docs/workflows", label: "Workflows" },
-      { href: "/docs/products", label: "Products" },
-      { href: "/docs/prd", label: "PRD" },
-      { href: "/docs/epics", label: "Epics" },
-      { href: "/docs/claude-code", label: "Claude Code" },
-      { href: "/docs/secrets", label: "Secrets" },
-      { href: "/docs/slack", label: "Slack" },
-      { href: "/docs/stack", label: "Stack" },
-      { href: "/docs/repositories", label: "Repositories" },
-      { href: "/docs/projects", label: "Projects" },
-      { href: "/docs/self-hosting", label: "Self-Hosting" },
+      { href: "/docs/reference/configuration", label: "Configuration" },
+      { href: "/docs/reference/architecture", label: "Architecture" },
+      { href: "/docs/reference/workflows", label: "Workflows" },
+      { href: "/docs/reference/products", label: "Products" },
+      { href: "/docs/reference/prd", label: "PRD" },
+      { href: "/docs/reference/epics", label: "Epics" },
+      { href: "/docs/reference/repositories", label: "Repositories" },
+      { href: "/docs/reference/projects", label: "Projects" },
+      { href: "/docs/reference/stack", label: "Stack" },
+      { href: "/docs/reference/slack", label: "Slack" },
+      { href: "/docs/reference/secrets", label: "Secrets" },
+    ],
+  },
+  {
+    title: "Resources",
+    items: [
+      { href: "/docs/resources/tips", label: "Tips" },
+      { href: "/docs/resources/tweets", label: "Tweets" },
     ],
   },
 ]