pingdotgg · juliusmarminge · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/README.md b/README.md
@@ -46,11 +46,19 @@ We are very very early in this project. Expect bugs.
 
 We are not accepting contributions yet.
 
-Observability guide: [docs/observability.md](./docs/observability.md)
+Observability guide: [docs/operations/observability.md](./docs/operations/observability.md)
 
-Relay observability: [docs/relay-observability.md](./docs/relay-observability.md)
+Relay observability: [docs/operations/relay-observability.md](./docs/operations/relay-observability.md)
 
-T3 Cloud Clerk setup: [docs/t3-cloud-clerk.md](./docs/t3-cloud-clerk.md)
+T3 Cloud Clerk setup: [docs/cloud/t3-cloud-clerk.md](./docs/cloud/t3-cloud-clerk.md)
+
+## Documentation
+
+- [Getting started](./docs/getting-started/quick-start.md)
+- [Architecture overview](./docs/architecture/overview.md)
+- [Provider guides](./docs/providers/codex.md)
+- [Operations](./docs/operations/ci.md)
+- [Reference](./docs/reference/encyclopedia.md)
 
 ## If you REALLY want to contribute still.... read this first
 

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,11 @@
+# Documentation
+
+- [Getting started](./getting-started/quick-start.md)
+- [Architecture](./architecture/overview.md)
+- [Cloud](./cloud/t3-cloud-clerk.md)
+- [Integrations](./integrations/source-control-providers.md)
+- [Mobile](./mobile/app.md)
+- [Operations](./operations/ci.md)
+- [Providers](./providers/codex.md)
+- [Reference](./reference/encyclopedia.md)
+- [User guides](./user/keybindings.md)
diff --git a/.docs/architecture.md → docs/architecture/overview.md b/.docs/architecture.md → docs/architecture/overview.md
diff --git a/.docs/provider-architecture.md → docs/architecture/providers.md b/.docs/provider-architecture.md → docs/architecture/providers.md
diff --git a/.docs/remote-architecture.md → docs/architecture/remote.md b/.docs/remote-architecture.md → docs/architecture/remote.md
diff --git a/.docs/runtime-modes.md → docs/architecture/runtime-modes.md b/.docs/runtime-modes.md → docs/architecture/runtime-modes.md
diff --git a/docs/environment-auth.md → docs/cloud/environment-auth.md b/docs/environment-auth.md → docs/cloud/environment-auth.md
diff --git a/docs/t3-cloud-clerk.md → docs/cloud/t3-cloud-clerk.md b/docs/t3-cloud-clerk.md → docs/cloud/t3-cloud-clerk.md
diff --git a/docs/t3-code-cloud-auth-flow.html → docs/cloud/t3-code-cloud-auth-flow.html b/docs/t3-code-cloud-auth-flow.html → docs/cloud/t3-code-cloud-auth-flow.html
diff --git a/.docs/codex-prerequisites.md → docs/getting-started/codex-prerequisites.md b/.docs/codex-prerequisites.md → docs/getting-started/codex-prerequisites.md
diff --git a/.docs/quick-start.md → docs/getting-started/quick-start.md b/.docs/quick-start.md → docs/getting-started/quick-start.md
diff --git a/docs/source-control-providers.md → .../integrations/source-control-providers.md b/docs/source-control-providers.md → .../integrations/source-control-providers.md
diff --git a/apps/mobile/README.md → docs/mobile/app.md b/apps/mobile/README.md → docs/mobile/app.md
diff --git a/apps/mobile/modules/t3-terminal/README.md → docs/mobile/terminal-native-module.md b/apps/mobile/modules/t3-terminal/README.md → docs/mobile/terminal-native-module.md
diff --git a/.docs/ci.md → docs/operations/ci.md b/.docs/ci.md → docs/operations/ci.md
@@ -3,4 +3,4 @@
 - `.github/workflows/ci.yml` runs `bun run lint`, `bun run typecheck`, and `bun run test` on pull requests and pushes to `main`.
 - `.github/workflows/release.yml` builds macOS (`arm64` and `x64`), Linux (`x64`), and Windows (`x64`) desktop artifacts from a single `v*.*.*` tag and publishes one GitHub release.
 - The release workflow auto-enables signing only when secrets are present: Apple credentials for macOS and Azure Trusted Signing credentials for Windows. Without secrets, it still releases unsigned artifacts.
-- See `docs/release.md` for full release/signing setup checklist.
+- See [Release Checklist](./release.md) for the full release/signing setup checklist.
diff --git a/docs/effect-fn-checklist.md → docs/operations/effect-fn-checklist.md b/docs/effect-fn-checklist.md → docs/operations/effect-fn-checklist.md
diff --git a/docs/observability.md → docs/operations/observability.md b/docs/observability.md → docs/operations/observability.md
diff --git a/docs/relay-observability.md → docs/operations/relay-observability.md b/docs/relay-observability.md → docs/operations/relay-observability.md
diff --git a/docs/release.md → docs/operations/release.md b/docs/release.md → docs/operations/release.md
diff --git a/TODO.md → docs/project/todo.md b/TODO.md → docs/project/todo.md
diff --git a/.docs/encyclopedia.md → docs/reference/encyclopedia.md b/.docs/encyclopedia.md → docs/reference/encyclopedia.md
diff --git a/.docs/scripts.md → docs/reference/scripts.md b/.docs/scripts.md → docs/reference/scripts.md
diff --git a/.docs/workspace-layout.md → docs/reference/workspace-layout.md b/.docs/workspace-layout.md → docs/reference/workspace-layout.md
diff --git a/KEYBINDINGS.md → docs/user/keybindings.md b/KEYBINDINGS.md → docs/user/keybindings.md
@@ -13,7 +13,7 @@ The file must be a JSON array of rules:
 ]
 ```
 
-See the full schema for more details: [`packages/contracts/src/keybindings.ts`](packages/contracts/src/keybindings.ts)
+See the full schema for more details: [`packages/contracts/src/keybindings.ts`](../../packages/contracts/src/keybindings.ts)
 
 ## Defaults
 
@@ -31,7 +31,7 @@ See the full schema for more details: [`packages/contracts/src/keybindings.ts`](
 ]
 ```
 
-For most up to date defaults, see [`DEFAULT_KEYBINDINGS` in `apps/server/src/keybindings.ts`](apps/server/src/keybindings.ts)
+For most up to date defaults, see [`DEFAULT_KEYBINDINGS` in `apps/server/src/keybindings.ts`](../../apps/server/src/keybindings.ts)
 
 ## Configuration
 

diff --git a/REMOTE.md → docs/user/remote-access.md b/REMOTE.md → docs/user/remote-access.md