From 74a7f6edb055aab115660ef3c0aac3f4a6096c7b Mon Sep 17 00:00:00 2001
From: Tommaso <65722261+TommasoTate@users.noreply.github.com>
Date: Mon, 15 Jun 2026 20:33:53 +0200
Subject: [PATCH] Refine docs workflow and update contributor guidance

---
 .github/PULL_REQUEST_TEMPLATE.md              |   3 +-
 AGENTS.md                                     | 207 ++-----
 CONTRIBUTING.md                               |   8 +-
 README.md                                     |  31 +-
 docs/ARCHITECTURE.md                          | 233 --------
 docs/SLACK_INTEGRATION.md                     | 121 ----
 ...04-agent-skills-use-dedicated-sandboxes.md |  62 +--
 docs/adr/index.md                             |  10 +
 docs/agent-chat/api-contract.md               |  13 +
 docs/agent-chat/edge-cases.md                 |  12 +
 docs/agent-chat/flow.md                       |  12 +
 docs/agent-chat/index.md                      |  13 +
 docs/agent-chat/invariants.md                 |  12 +
 docs/agent-chat/overview.md                   |  13 +
 docs/agent-chat/state.md                      |  12 +
 docs/agent-chat/tests.md                      |  12 +
 docs/agent-creation-chat/edge-cases.md        |  12 +
 docs/agent-creation-chat/flow.md              |  12 +
 docs/agent-creation-chat/index.md             |  12 +
 docs/agent-creation-chat/invariants.md        |  12 +
 docs/agent-creation-chat/overview.md          |  12 +
 docs/agent-creation-chat/state.md             |  11 +
 docs/agent-creation-chat/tests.md             |  13 +
 docs/agent-edit-chat/edge-cases.md            |  12 +
 docs/agent-edit-chat/flow.md                  |  12 +
 docs/agent-edit-chat/index.md                 |  12 +
 docs/agent-edit-chat/invariants.md            |  12 +
 docs/agent-edit-chat/overview.md              |  12 +
 docs/agent-edit-chat/state.md                 |  11 +
 docs/agent-edit-chat/tests.md                 |  13 +
 docs/agent-events/concurrency-idempotency.md  |  19 +
 docs/agent-events/event-kinds.md              |  17 +
 docs/agent-events/index.md                    |  11 +
 docs/agent-events/overview.md                 |  30 +
 docs/agent-events/state-machine.md            |  19 +
 docs/agent-events/streams.md                  |  19 +
 .../configuration-contract.md                 |  14 +
 docs/agent-management/edge-cases.md           |  12 +
 docs/agent-management/flow.md                 |  12 +
 docs/agent-management/index.md                |  14 +
 docs/agent-management/invariants.md           |  12 +
 docs/agent-management/overview.md             |  14 +
 docs/agent-management/product-shell.md        |  13 +
 docs/agent-management/state.md                |  11 +
 docs/agent-management/tests.md                |  13 +
 docs/agent-memory/index.md                    |   8 +
 docs/agent-memory/overview.md                 |  30 +
 docs/agent-memory/sandbox-files-contract.md   |  24 +
 docs/agent-skills/index.md                    |   8 +
 docs/agent-skills/package-lifecycle.md        |  24 +
 docs/agent-skills/runtime.md                  |  29 +
 docs/auth-account/index.md                    |   8 +
 docs/auth-account/otp-flow.md                 |  21 +
 docs/auth-account/overview.md                 |  22 +
 docs/budgets/accounting.md                    |  25 +
 docs/budgets/index.md                         |   8 +
 docs/budgets/overview.md                      |  23 +
 docs/cache-revalidation/cache-map.md          |  28 +
 docs/cache-revalidation/index.md              |   9 +
 docs/cache-revalidation/overview.md           |  29 +
 docs/cache-revalidation/revalidation-flow.md  |  26 +
 docs/channels-slack/channel-contract.md       |  26 +
 docs/channels-slack/index.md                  |   8 +
 docs/channels-slack/overview.md               |  23 +
 docs/connections/connector-authoring.md       |  23 +
 docs/connections/credential-taxonomy.md       |  23 +
 docs/connections/index.md                     |   9 +
 docs/connections/overview.md                  |  23 +
 docs/data/core-tables.md                      |  21 +
 docs/data/index.md                            |   8 +
 docs/data/migrations.md                       |  19 +
 docs/dreaming/overview.md                     |  30 +
 docs/email-templates/components.md            |  26 +
 docs/email-templates/index.md                 |   9 +
 docs/email-templates/overview.md              |  25 +
 docs/email-templates/sending.md               |  25 +
 docs/heartbeat/overview.md                    |  30 +
 docs/index.md                                 |  15 +
 docs/inference/index.md                       |   8 +
 docs/inference/provider-authoring.md          |  21 +
 docs/inference/providers.md                   |  23 +
 docs/launch-video/index.md                    |   9 +
 docs/launch-video/manifest.md                 |  25 +
 docs/launch-video/overview.md                 |  29 +
 docs/launch-video/rendering.md                |  25 +
 docs/marketing-site/content.md                |  24 +
 docs/marketing-site/index.md                  |   9 +
 docs/marketing-site/overview.md               |  27 +
 docs/marketing-site/routing.md                |  25 +
 docs/platform/env-matrix.md                   |  29 +
 docs/platform/index.md                        |  10 +
 docs/platform/routing.md                      |  26 +
 docs/platform/test-matrix.md                  |  27 +
 docs/platform/workspaces.md                   |  27 +
 docs/realtime-turns/edge-cases.md             |  12 +
 docs/realtime-turns/flow.md                   |  11 +
 docs/realtime-turns/index.md                  |  13 +
 docs/realtime-turns/invariants.md             |  12 +
 docs/realtime-turns/overview.md               |  13 +
 docs/realtime-turns/runtime-spec.md           |  15 +
 docs/realtime-turns/state.md                  |  11 +
 docs/realtime-turns/tests.md                  |  12 +
 docs/runtime-cache/index.md                   |   8 +
 docs/runtime-cache/overview.md                |  30 +
 docs/runtime-cache/redis-requirements.md      |  21 +
 docs/scheduler/index.md                       |   9 +
 docs/scheduler/overview.md                    |  30 +
 docs/scheduler/recovery.md                    |  19 +
 docs/scheduler/schedule-contract.md           |  19 +
 docs/security-edge/botid-contracts.md         |  23 +
 docs/security-edge/index.md                   |   9 +
 docs/security-edge/overview.md                |  29 +
 docs/security-edge/proxy-rules.md             |  25 +
 docs/simplification-plan-agent-workflows.md   | 260 ---------
 docs/sub-agents/index.md                      |   8 +
 docs/sub-agents/invocation-events.md          |  19 +
 docs/sub-agents/overview.md                   |  30 +
 docs/tool-sandboxes/index.md                  |   8 +
 docs/tool-sandboxes/manifest-authoring.md     |  24 +
 docs/tool-sandboxes/overview.md               |  30 +
 docs/tools/catalog.md                         |  30 +
 docs/tools/index.md                           |   9 +
 docs/tools/maintainer-tool-authoring.md       |  23 +
 docs/tools/reconnect-and-audit.md             |  24 +
 docs/ui-system/ai-elements.md                 |  22 +
 docs/ui-system/components.md                  |  25 +
 docs/ui-system/index.md                       |  10 +
 docs/ui-system/overview.md                    |  29 +
 docs/ui-system/product-shell.md               |  26 +
 docs/waitlist/index.md                        |   8 +
 docs/waitlist/overview.md                     |  22 +
 docs/waitlist/status-transitions.md           |  22 +
 docs/workflow-runtime/extension-guide.md      |  19 +
 docs/workflow-runtime/index.md                |   8 +
 docs/workflow-runtime/overview.md             |  28 +
 package.json                                  |   4 +-
 packages/shared/content/blog/posts.ts         |  11 +-
 scripts/docs-index.ts                         | 525 ++++++++++++++++++
 138 files changed, 2877 insertions(+), 849 deletions(-)
 delete mode 100644 docs/ARCHITECTURE.md
 delete mode 100644 docs/SLACK_INTEGRATION.md
 create mode 100644 docs/adr/index.md
 create mode 100644 docs/agent-chat/api-contract.md
 create mode 100644 docs/agent-chat/edge-cases.md
 create mode 100644 docs/agent-chat/flow.md
 create mode 100644 docs/agent-chat/index.md
 create mode 100644 docs/agent-chat/invariants.md
 create mode 100644 docs/agent-chat/overview.md
 create mode 100644 docs/agent-chat/state.md
 create mode 100644 docs/agent-chat/tests.md
 create mode 100644 docs/agent-creation-chat/edge-cases.md
 create mode 100644 docs/agent-creation-chat/flow.md
 create mode 100644 docs/agent-creation-chat/index.md
 create mode 100644 docs/agent-creation-chat/invariants.md
 create mode 100644 docs/agent-creation-chat/overview.md
 create mode 100644 docs/agent-creation-chat/state.md
 create mode 100644 docs/agent-creation-chat/tests.md
 create mode 100644 docs/agent-edit-chat/edge-cases.md
 create mode 100644 docs/agent-edit-chat/flow.md
 create mode 100644 docs/agent-edit-chat/index.md
 create mode 100644 docs/agent-edit-chat/invariants.md
 create mode 100644 docs/agent-edit-chat/overview.md
 create mode 100644 docs/agent-edit-chat/state.md
 create mode 100644 docs/agent-edit-chat/tests.md
 create mode 100644 docs/agent-events/concurrency-idempotency.md
 create mode 100644 docs/agent-events/event-kinds.md
 create mode 100644 docs/agent-events/index.md
 create mode 100644 docs/agent-events/overview.md
 create mode 100644 docs/agent-events/state-machine.md
 create mode 100644 docs/agent-events/streams.md
 create mode 100644 docs/agent-management/configuration-contract.md
 create mode 100644 docs/agent-management/edge-cases.md
 create mode 100644 docs/agent-management/flow.md
 create mode 100644 docs/agent-management/index.md
 create mode 100644 docs/agent-management/invariants.md
 create mode 100644 docs/agent-management/overview.md
 create mode 100644 docs/agent-management/product-shell.md
 create mode 100644 docs/agent-management/state.md
 create mode 100644 docs/agent-management/tests.md
 create mode 100644 docs/agent-memory/index.md
 create mode 100644 docs/agent-memory/overview.md
 create mode 100644 docs/agent-memory/sandbox-files-contract.md
 create mode 100644 docs/agent-skills/index.md
 create mode 100644 docs/agent-skills/package-lifecycle.md
 create mode 100644 docs/agent-skills/runtime.md
 create mode 100644 docs/auth-account/index.md
 create mode 100644 docs/auth-account/otp-flow.md
 create mode 100644 docs/auth-account/overview.md
 create mode 100644 docs/budgets/accounting.md
 create mode 100644 docs/budgets/index.md
 create mode 100644 docs/budgets/overview.md
 create mode 100644 docs/cache-revalidation/cache-map.md
 create mode 100644 docs/cache-revalidation/index.md
 create mode 100644 docs/cache-revalidation/overview.md
 create mode 100644 docs/cache-revalidation/revalidation-flow.md
 create mode 100644 docs/channels-slack/channel-contract.md
 create mode 100644 docs/channels-slack/index.md
 create mode 100644 docs/channels-slack/overview.md
 create mode 100644 docs/connections/connector-authoring.md
 create mode 100644 docs/connections/credential-taxonomy.md
 create mode 100644 docs/connections/index.md
 create mode 100644 docs/connections/overview.md
 create mode 100644 docs/data/core-tables.md
 create mode 100644 docs/data/index.md
 create mode 100644 docs/data/migrations.md
 create mode 100644 docs/dreaming/overview.md
 create mode 100644 docs/email-templates/components.md
 create mode 100644 docs/email-templates/index.md
 create mode 100644 docs/email-templates/overview.md
 create mode 100644 docs/email-templates/sending.md
 create mode 100644 docs/heartbeat/overview.md
 create mode 100644 docs/index.md
 create mode 100644 docs/inference/index.md
 create mode 100644 docs/inference/provider-authoring.md
 create mode 100644 docs/inference/providers.md
 create mode 100644 docs/launch-video/index.md
 create mode 100644 docs/launch-video/manifest.md
 create mode 100644 docs/launch-video/overview.md
 create mode 100644 docs/launch-video/rendering.md
 create mode 100644 docs/marketing-site/content.md
 create mode 100644 docs/marketing-site/index.md
 create mode 100644 docs/marketing-site/overview.md
 create mode 100644 docs/marketing-site/routing.md
 create mode 100644 docs/platform/env-matrix.md
 create mode 100644 docs/platform/index.md
 create mode 100644 docs/platform/routing.md
 create mode 100644 docs/platform/test-matrix.md
 create mode 100644 docs/platform/workspaces.md
 create mode 100644 docs/realtime-turns/edge-cases.md
 create mode 100644 docs/realtime-turns/flow.md
 create mode 100644 docs/realtime-turns/index.md
 create mode 100644 docs/realtime-turns/invariants.md
 create mode 100644 docs/realtime-turns/overview.md
 create mode 100644 docs/realtime-turns/runtime-spec.md
 create mode 100644 docs/realtime-turns/state.md
 create mode 100644 docs/realtime-turns/tests.md
 create mode 100644 docs/runtime-cache/index.md
 create mode 100644 docs/runtime-cache/overview.md
 create mode 100644 docs/runtime-cache/redis-requirements.md
 create mode 100644 docs/scheduler/index.md
 create mode 100644 docs/scheduler/overview.md
 create mode 100644 docs/scheduler/recovery.md
 create mode 100644 docs/scheduler/schedule-contract.md
 create mode 100644 docs/security-edge/botid-contracts.md
 create mode 100644 docs/security-edge/index.md
 create mode 100644 docs/security-edge/overview.md
 create mode 100644 docs/security-edge/proxy-rules.md
 delete mode 100644 docs/simplification-plan-agent-workflows.md
 create mode 100644 docs/sub-agents/index.md
 create mode 100644 docs/sub-agents/invocation-events.md
 create mode 100644 docs/sub-agents/overview.md
 create mode 100644 docs/tool-sandboxes/index.md
 create mode 100644 docs/tool-sandboxes/manifest-authoring.md
 create mode 100644 docs/tool-sandboxes/overview.md
 create mode 100644 docs/tools/catalog.md
 create mode 100644 docs/tools/index.md
 create mode 100644 docs/tools/maintainer-tool-authoring.md
 create mode 100644 docs/tools/reconnect-and-audit.md
 create mode 100644 docs/ui-system/ai-elements.md
 create mode 100644 docs/ui-system/components.md
 create mode 100644 docs/ui-system/index.md
 create mode 100644 docs/ui-system/overview.md
 create mode 100644 docs/ui-system/product-shell.md
 create mode 100644 docs/waitlist/index.md
 create mode 100644 docs/waitlist/overview.md
 create mode 100644 docs/waitlist/status-transitions.md
 create mode 100644 docs/workflow-runtime/extension-guide.md
 create mode 100644 docs/workflow-runtime/index.md
 create mode 100644 docs/workflow-runtime/overview.md
 create mode 100644 scripts/docs-index.ts

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 1542e55b..4611fa96 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -5,7 +5,8 @@
 
 ## Validation
 
-- [ ] `pnpm check`
+- [ ] `pnpm verify`
+- [ ] `pnpm docs:index` was run if docs changed
 - [ ] Relevant tests or manual verification
 
 ## Release notes
diff --git a/AGENTS.md b/AGENTS.md
index b3381628..2352a6d5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,171 +1,36 @@
-# Ultracite Code Standards
-
-This project uses **Ultracite**, a zero-config preset that enforces strict code quality standards through automated formatting and linting.
-
-## Quick Reference
-
-- **Format code**: `pnpm dlx ultracite fix`
-- **Check for issues**: `pnpm dlx ultracite check`
-- **Diagnose setup**: `pnpm dlx ultracite doctor`
-
-Biome (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.
-
----
-
-## Core Principles
-
-Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity.
-
-### Type Safety & Explicitness
-
-- Use explicit types for function parameters and return values when they enhance clarity
-- Prefer `unknown` over `any` when the type is genuinely unknown
-- Use const assertions (`as const`) for immutable values and literal types
-- Leverage TypeScript's type narrowing instead of type assertions
-- Use meaningful variable names instead of magic numbers - extract constants with descriptive names
-
-### Modern JavaScript/TypeScript
-
-- Use arrow functions for callbacks and short functions
-- Prefer `for...of` loops over `.forEach()` and indexed `for` loops
-- Use optional chaining (`?.`) and nullish coalescing (`??`) for safer property access
-- Prefer template literals over string concatenation
-- Use destructuring for object and array assignments
-- Use `const` by default, `let` only when reassignment is needed, never `var`
-
-### Async & Promises
-
-- Always `await` promises in async functions - don't forget to use the return value
-- Use `async/await` syntax instead of promise chains for better readability
-- Handle errors appropriately in async code with try-catch blocks
-- Don't use async functions as Promise executors
-
-### React & JSX
-
-- Use function components over class components
-- Call hooks at the top level only, never conditionally
-- Specify all dependencies in hook dependency arrays correctly
-- Use the `key` prop for elements in iterables (prefer unique IDs over array indices)
-- Nest children between opening and closing tags instead of passing as props
-- Don't define components inside other components
-- Use semantic HTML and ARIA attributes for accessibility:
-  - Provide meaningful alt text for images
-  - Use proper heading hierarchy
-  - Add labels for form inputs
-  - Include keyboard event handlers alongside mouse events
-  - Use semantic elements (`<button>`, `<nav>`, etc.) instead of divs with roles
-
-### Error Handling & Debugging
-
-- Remove `console.log`, `debugger`, and `alert` statements from production code
-- Throw `Error` objects with descriptive messages, not strings or other values
-- Use `try-catch` blocks meaningfully - don't catch errors just to rethrow them
-- Prefer early returns over nested conditionals for error cases
-
-### Code Organization
-
-- Keep functions focused and under reasonable cognitive complexity limits
-- Extract complex conditions into well-named boolean variables
-- Use early returns to reduce nesting
-- Prefer simple conditionals over nested ternary operators
-- Group related code together and separate concerns
-
-### Security
-
-- Add `rel="noopener"` when using `target="_blank"` on links
-- Avoid `dangerouslySetInnerHTML` unless absolutely necessary
-- Don't use `eval()` or assign directly to `document.cookie`
-- Validate and sanitize user input
-
-### Performance
-
-- Avoid spread syntax in accumulators within loops
-- Use top-level regex literals instead of creating them in loops
-- Prefer specific imports over namespace imports
-- Avoid barrel files (index files that re-export everything)
-- Use proper image components (e.g., Next.js `<Image>`) over `<img>` tags
-
-### Framework-Specific Guidance
-
-**Next.js:**
-- Use Next.js `<Image>` component for images
-- Use `next/head` or App Router metadata API for head elements
-- Use Server Components for async data fetching instead of async Client Components
-
-**React 19+:**
-- Use ref as a prop instead of `React.forwardRef`
-
-**Solid/Svelte/Vue/Qwik:**
-- Use `class` and `for` attributes (not `className` or `htmlFor`)
-
----
-
-## Testing
-
-- Write assertions inside `it()` or `test()` blocks
-- Avoid done callbacks in async tests - use async/await instead
-- Don't use `.only` or `.skip` in committed code
-- Keep test suites reasonably flat - avoid excessive `describe` nesting
-
-## When Biome Can't Help
-
-Biome's linter will catch most issues automatically. Focus your attention on:
-
-1. **Business logic correctness** - Biome can't validate your algorithms
-2. **Meaningful naming** - Use descriptive names for functions, variables, and types
-3. **Architecture decisions** - Component structure, data flow, and API design
-4. **Edge cases** - Handle boundary conditions and error states
-5. **User experience** - Accessibility, performance, and usability considerations
-6. **Documentation** - Add comments for complex logic, but prefer self-documenting code
-
----
-
-Most formatting and common issues are automatically fixed by Biome. Run `pnpm dlx ultracite fix` before committing to ensure compliance.
-
----
-
-## Cursor Cloud specific instructions
-
-### Services overview
-
-This is a Turborepo monorepo with deployable Next.js apps and local-only email/video workspaces.
-
-- **Dev servers**: `pnpm dev:app` → http://localhost:3000, `pnpm dev:api` → http://localhost:3001, `pnpm dev:web` → http://localhost:3002, `pnpm dev:email` → http://localhost:3004, `pnpm dev:video` → http://localhost:3005
-- **Database**: Remote Neon Postgres via `DATABASE_URL` (no local DB required). Use `@outname/db` (`pg` + `attachDatabasePool` per [Neon + Vercel connection methods](https://neon.com/docs/guides/vercel-connection-methods)). Use Neon's pooled connection string (hostname includes `-pooler`). In the session workflow codepath, prefer normal static imports even for step-oriented modules that touch `@outname/db` or server helpers. Keep `await import(...)` only when you truly want optional-path lazy loading or package/runtime-local loading (for example the optional child-trace path or `bash-tool` package loading).
-- **Lint**: `pnpm lint` (Ultracite/Biome)
-- **Format**: `pnpm fix` (auto-fix lint/format issues)
-
-### Environment variables
-
-Required secrets are injected automatically. A `.env.local` must exist for Next.js to read them at runtime. Create it with:
-
-```
-DATABASE_URL=<from env>
-BETTER_AUTH_SECRET=<from env>
-BETTER_AUTH_URL=http://localhost:3001
-BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:3002
-AUTH_COOKIE_DOMAIN=
-CONNECTION_ENCRYPTION_KEY=<from env>
-APP_REVALIDATION_SECRET=<from env>
-VERCEL_API_PROJECT_ID=
-VERCEL_APP_PROJECT_ID=
-VERCEL_WEB_PROJECT_ID=
-SANDBOX_TEAM_ID=<from env>
-SANDBOX_PROJECT_ID=<from env>
-SANDBOX_ACCESS_TOKEN=<from env>
-RESEND_API_KEY=<from env>
-AUTH_FROM_EMAIL=<verified sender>
-AUTH_REPLY_TO=<verified reply-to sender>
-WAITLIST_FROM_EMAIL=<verified sender for waitlist emails>
-WAITLIST_REPLY_TO=<reply-to sender for waitlist emails>
-WAITLIST_ADMIN_EMAIL=<admin inbox for new waitlist signup notifications>
-```
-
-### Known caveats
-
-- **Sign-up is disabled** at the Better Auth level (`packages/auth/server/auth.ts`); new users are provisioned from the waitlist and sign in with email OTP codes. The data model is multi-user — every user-owned table is scoped by `user_id` and routes verify ownership. Use a provisioned address such as `TEST_USER_EMAIL` to request a login code in dev.
-- **Dev sign-in flow**: Request an OTP via `POST /api/auth/request-otp` with `{"email":"<existing-user>"}`, then read the code from the `verification` table (`SELECT value FROM verification ORDER BY "createdAt" DESC LIMIT 1` — the OTP is the part before the `:`). Submit it to `POST /api/auth/sign-in/email-otp` with `{"email":"...","otp":"..."}` to get a `better-auth.session_token` cookie. Existing test users can be found with `SELECT email FROM "user" LIMIT 5`.
-- **`drizzle-kit push`** requires a TTY for confirmation prompts. Use `drizzle-kit push --force` or run interactively if schema changes are needed.
-- **Do not commit `pnpm-workspace.yaml` allow-build overrides.** They make the production build fail in this app.
-- **UI/auth changes should be tested manually** via the browser. There is no comprehensive automated product test suite for waitlist and authentication flows.
-- **Running `pnpm test`** requires `DATABASE_URL` to be set in the environment. Export it before running tests or source it from `.env.local`. Some test files import `@outname/db` which throws at module load time if the variable is missing.
+# Agent Rules
+
+Keep this file minimal. Put feature knowledge in `docs/<feature>/` and keep
+tool-specific preferences out unless they are hard project constraints.
+
+## Documentation
+
+- Every feature document lives under a feature folder in `docs/`.
+- Non-index markdown files under `docs/` must stay at 30 lines or fewer.
+- Generated `index.md` files may exceed 30 lines when needed for navigation.
+- If a docs folder has more than one markdown file, it must have `index.md`.
+- `docs/index.md` and folder indexes are generated; update source docs, then run
+  `pnpm docs:index` instead of hand-editing generated indexes.
+
+## Runtime Caveats
+
+- The database is remote Neon Postgres through `DATABASE_URL`; no local Postgres
+  is expected. Use the pooled Neon hostname containing `-pooler`.
+- Next.js needs `.env.local` at runtime even when secrets are injected by the
+  environment.
+- In session workflow codepaths, prefer static imports for modules touching
+  `@outname/db` or server helpers. Use dynamic imports only for truly optional
+  runtime-local paths.
+- Public sign-up is disabled in Better Auth. Dev users are provisioned from the
+  waitlist and sign in with email OTP codes.
+- For dev OTP login, request `/api/auth/request-otp`, read the newest
+  `verification.value`, then submit the code before `:` to
+  `/api/auth/sign-in/email-otp`.
+- `drizzle-kit push` prompts for confirmation unless run with `--force` or an
+  interactive TTY.
+- Do not commit `pnpm-workspace.yaml` allow-build overrides; they break
+  production builds.
+- UI and auth changes need manual browser verification because there is no full
+  product test suite for those flows.
+- `pnpm test` imports database-backed modules; set `DATABASE_URL` first or source
+  `.env.local`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c61e6a86..9191d314 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,8 +6,8 @@ Thanks for your interest in improving `outname`.
 
 1. Read `README.md` for the product overview and setup steps.
 2. Read `.env.example` and create `.env.local` for local development.
-3. Read `docs/ARCHITECTURE.md` if your change touches runtime behavior,
-   integrations, or data flow.
+3. Read `docs/index.md`; for runtime changes, start with the agent events,
+   realtime turns, scheduler, tools, and channel feature docs.
 
 ## Local setup
 
@@ -47,8 +47,8 @@ request:
 pnpm verify
 ```
 
-`pnpm verify` runs the workflow boundary check plus `build`, `typecheck`,
-`lint`, and `react-doctor` across the monorepo.
+`pnpm verify` runs the docs check plus `build`, `typecheck`, `lint`, and
+`react-doctor` across the monorepo.
 
 If you changed TypeScript runtime code, also run:
 
diff --git a/README.md b/README.md
index d0aaef19..d03c873a 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
 [![Turborepo](https://img.shields.io/badge/Turborepo-000000?style=flat-square&logo=turborepo&logoColor=EF4444)](https://turbo.build)
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff3000?style=flat-square&labelColor=000000)](CONTRIBUTING.md)
 
-**[Website](https://outna.me)** · **[Quick start](#-quick-start)** · **[How it works](#-how-it-works)** · **[Architecture](docs/ARCHITECTURE.md)** · **[Contributing](CONTRIBUTING.md)** · **[X / Twitter](https://x.com/OutnameBot)**
+**[Website](https://outna.me)** · **[Quick start](#-quick-start)** · **[How it works](#-how-it-works)** · **[Docs](docs/index.md)** · **[Contributing](CONTRIBUTING.md)** · **[X / Twitter](https://x.com/OutnameBot)**
 
 </div>
 
@@ -145,8 +145,8 @@ flowchart LR
   WF --> Tools[Tools and Skills]
 ```
 
-See **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** for runtime boundaries, the
-event model, and the full request/event flow.
+See **[docs/index.md](docs/index.md)** for generated, feature-focused docs,
+including runtime boundaries, event flow, tools, channels, and data ownership.
 
 ## 🧱 Tech stack
 
@@ -184,7 +184,7 @@ outname/
 │  ├─ shared/   # Shared domain, marketing, and server utilities
 │  ├─ ui/       # Design system (Radix + shadcn)
 │  └─ workflow/ # Workflow helpers
-└─ docs/        # Architecture + ADRs
+└─ docs/        # Generated feature index, feature notes, and ADRs
 ```
 
 ## 🚀 Quick start
@@ -273,8 +273,10 @@ pnpm dev:video    # Remotion Studio        (:3005)
 pnpm build        # Build all workspaces
 pnpm lint         # Lint (Ultracite / Biome)
 pnpm typecheck    # Type-check
-pnpm verify       # Lint + typecheck + tests
+pnpm verify       # Docs check + build + typecheck + lint + react-doctor
 pnpm fix          # Auto-fix lint/format issues
+pnpm docs:index   # Regenerate docs indexes
+pnpm docs:check   # Validate docs indexes and non-index markdown line limit
 
 pnpm db:generate  # Generate Drizzle migrations
 pnpm db:migrate   # Apply migrations
@@ -283,15 +285,16 @@ pnpm db:studio    # Open Drizzle Studio
 
 ## 📚 Documentation
 
-| Document                                                       | What's inside                              |
-| ------------------------------------------------------------- | ------------------------------------------ |
-| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)                  | System architecture and runtime boundaries |
-| [docs/adr/](docs/adr)                                         | Architecture Decision Records              |
-| [docs/SLACK_INTEGRATION.md](docs/SLACK_INTEGRATION.md)        | Slack setup and integration                |
-| [AGENTS.md](AGENTS.md)                                        | Code standards and local dev notes         |
-| [CONTRIBUTING.md](CONTRIBUTING.md)                            | Contributor workflow and quality checks    |
-| [SECURITY.md](SECURITY.md)                                    | Vulnerability disclosure process           |
-| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)                      | Community expectations                      |
+Start at **[docs/index.md](docs/index.md)**. Feature docs live in
+`docs/<feature>/`, stay under 30 lines per non-index markdown file, and are
+linked through generated indexes.
+
+Other project guidance:
+
+- **[AGENTS.md](AGENTS.md)**: non-inferable rules for coding agents.
+- **[CONTRIBUTING.md](CONTRIBUTING.md)**: contributor workflow.
+- **[SECURITY.md](SECURITY.md)**: vulnerability disclosure.
+- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)**: community expectations.
 
 ## 🤝 Contributing
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
deleted file mode 100644
index 62af56ef..00000000
--- a/docs/ARCHITECTURE.md
+++ /dev/null
@@ -1,233 +0,0 @@
-# Architecture
-
-This document describes the current architecture of `outname`. The application
-is a single Next.js control plane
-that orchestrates event-driven agent work through Vercel Workflow, persists
-application state in Neon Postgres, and keeps each agent's filesystem in a
-persistent Vercel Sandbox.
-
-## System overview
-
-```mermaid
-flowchart LR
-  Browser[Browser UI] --> Next[Next.js App Router and API routes]
-  Slack[Slack webhooks and OAuth] --> Next
-  Cron[Vercel Cron] --> Next
-
-  Next --> Auth[Better Auth]
-  Next --> DB[(Neon Postgres)]
-  Next --> Redis[(Upstash Redis)]
-  Next --> Workflow[Vercel Workflow]
-  Next --> Resend[Resend]
-
-  Next --> Inference[Vercel AI Gateway, LLM Gateway, or OpenRouter]
-  Next --> Sandbox[Vercel Sandbox]
-  Workflow --> Sandbox
-  Workflow --> Inference
-  Workflow --> DB
-  Workflow --> Redis
-  Workflow --> Tools[Tool catalog and providers]
-```
-
-## Runtime boundaries
-
-### Next.js control plane
-
-The Next.js application owns routing, authentication, configuration screens,
-browser chat APIs, Slack installation endpoints, waitlist endpoints, and
-scheduler ingress.
-
-Key files:
-
-- `app/` for pages and route handlers
-- `proxy.ts` for auth and waitlist gating
-- `auth/server/auth.ts` for Better Auth configuration
-- `app/api/cron/liveness/route.ts` for scheduler ingress
-
-### Agent runtime
-
-Agent work is run-scoped. There is no always-on per-agent process.
-
-Realtime chat turns from the web app and channels such as Slack run directly in
-the Next.js Node runtime through AI SDK `ToolLoopAgent`. Their model context and
-visible state come from the app-owned `chat_message` transcript. Provider
-history from Chat SDK adapters is imported into that transcript on a
-best-effort basis; it is not a second runtime source of truth. Realtime turns do
-not create durable `agent_events` rows.
-
-Autonomous or long-running work remains workflow-backed. Heartbeat, dreaming,
-and sub-agent invocation create `agent_events` rows and run through Vercel
-Workflow.
-
-Core responsibilities:
-
-- building a serializable `AgentRuntimeSpec` shared by durable and realtime
-  adapters;
-- dispatching realtime `ToolLoopAgent` chat turns;
-- enqueueing and deduplicating durable events;
-- dispatching durable handlers for heartbeat, dreaming, and invocation;
-- managing per-event reply streams;
-- cleaning up ephemeral resources after each run;
-- starting the next queued event for a matching concurrency key.
-
-Key files:
-
-- `agent-runtime/server/agent-events.ts`
-- `agent-runtime/server/agent-event-store.ts`
-- `agent-runtime/server/runtime-spec.ts`
-- `agent-runtime/server/realtime-chat-runner.ts`
-- `agent-runtime/workflows/events/workflow.ts`
-- `agent-runtime/workflows/session/handlers/*`
-
-### Agent filesystems
-
-Each agent has a named persistent Vercel Sandbox. The sandbox is the canonical
-filesystem for bootstrap files and durable agent-authored files.
-
-- UI-authored bootstrap edits write directly into the sandbox.
-- Redis only caches selected file reads for faster UI access.
-- If Redis and sandbox contents disagree, the sandbox is authoritative.
-
-Agents with installed Agent Skills also get a separate persistent Skill Sandbox,
-created lazily on first skill install. The Skill Sandbox contains installed
-skill packages under `skills/<slug>` and a writable `workspace` for skill script
-execution. It is intentionally separate from the system sandbox so scripts can
-run freely without making the agent memory filesystem executable.
-
-## Event model
-
-Event types:
-
-- `heartbeat`
-- `dreaming`
-- `invocation`
-
-Event statuses:
-
-- `queued`
-- `starting`
-- `running`
-- `completed`
-- `failed`
-- `cancelled`
-
-`idempotency_key` prevents duplicate durable work for retried or repeated
-autonomous ingress. `concurrency_key` is used only where durable ordering
-matters, such as scheduled buckets for the same agent. Realtime channel
-idempotency is handled at the `chat_message` layer.
-
-## Request and event flow
-
-```mermaid
-sequenceDiagram
-  participant Ingress as Browser, Slack, cron, or tool
-  participant Next as Next.js route
-  participant DB as Neon Postgres
-  participant R as ToolLoopAgent
-  participant W as agentEventWorkflow
-  participant S as Vercel Sandbox
-  participant M as Inference provider and tools
-
-  Ingress->>Next: request or trigger
-  Next->>DB: validate ownership and persist visible input
-  alt realtime chat
-    Next->>R: build runtime and stream response
-    R->>S: use sandbox-backed tools
-    R->>M: execute model and tool work
-    R->>DB: persist assistant transcript
-  else durable event
-  Next->>DB: insert or reuse agent_events row
-  Next->>W: start workflow when runnable
-  W->>DB: mark running and heartbeat
-  W->>S: resume persistent sandbox
-  W->>M: execute model and tool work
-  W-->>Ingress: stream reply namespace
-  W->>DB: mark terminal status
-  W->>DB: start next queued event for same concurrency key
-  end
-```
-
-## Scheduler and liveness
-
-`/api/cron/liveness` is both scheduler and liveness sweeper. `vercel.json`
-configures it to run every five minutes in deployed environments.
-
-The scheduler:
-
-- acquires a Redis lock so only one sweep runs at a time;
-- enqueues due heartbeat and dreaming events;
-- starts queued events that are now runnable;
-- requeues expired `starting` events whose workflow never came up;
-- inspects `running` events and reconciles them with workflow status.
-
-Long-running durable events are valid. Failure detection depends on stale
-heartbeat data or terminal workflow state, not just elapsed runtime. Realtime
-channel turns are best-effort request/background work with transcript-level
-deduplication. Realtime channel assistant delivery is not exactly-once in v1:
-if a provider accepts a streamed assistant message and the process dies before
-final Postgres persistence, no delivery ledger reconciles that gap yet.
-
-## State ownership
-
-| Concern | Source of truth | Notes |
-| --- | --- | --- |
-| Users, sessions, agents, tools, conversations | Neon Postgres | Stored through Drizzle ORM and Better Auth. |
-| User inference credentials | Neon Postgres | Provider keys live in `user_inference_credentials`, encrypted per user. There is no server fallback key. |
-| Per-agent inference provider and model | Neon Postgres | `agent.inference_provider` scopes `agent.model`; model ids are not globally meaningful by themselves. |
-| Token usage and cost estimates | Neon Postgres | `agent_token_usage` stores provider, requested model, cache/read/write/reasoning tokens, pricing snapshot, and estimated or actual USD cost. |
-| Agent event ledger | Neon Postgres | `agent_events` drives durable orchestration and recovery for heartbeat, dreaming, and invocation. |
-| Agent filesystem and bootstrap files | Vercel Sandbox | Persistent per-agent system sandbox. |
-| Installed skills and skill workspace | Vercel Sandbox | Separate persistent Skill Sandbox for agents that have skills. |
-| Cache and distributed coordination | Upstash Redis | Used for locks, scheduling, and cached file reads. |
-| Channel thread state | Postgres plus Redis | Installations and canonical transcripts live in Postgres; Chat SDK locks, queue, dedupe, subscriptions, and ephemeral state require Redis. |
-
-## Key data model
-
-The main application tables are:
-
-- `agent` for configuration, model selection, schedules, and sandbox identity;
-- `agent_events` for durable runtime orchestration and retries;
-- `chat_conversation` and `chat_message` for transcripts;
-- `agent_tools` for tool attachments and sub-agent wiring;
-- `channel_installations`, `agent_channel_bindings`, and
-  `channel_thread_conversations` for Slack integration;
-- `user_connections` for user-provided provider credentials;
-- `waitlist_entry` for public waitlist capture.
-
-## External integrations
-
-| Service | Role in the system | Primary files |
-| --- | --- | --- |
-| Better Auth | Authentication and admin roles | `auth/server/auth.ts`, `app/api/auth/[...all]/route.ts` |
-| Neon Postgres | Primary relational database | `shared/db/index.ts`, `shared/db/schema/*` |
-| Vercel Workflow | Durable heartbeat, dreaming, and invocation execution | `next.config.ts`, `agent-runtime/workflows/events/workflow.ts` |
-| Vercel Sandbox | Persistent agent filesystem and tool execution | `agent-runtime/server/agent-sandbox.ts`, `tools/sandbox-runtime/*` |
-| Upstash Redis | Locks, cache, and scheduling coordination | `agent-runtime/server/redis-lock.ts`, `agent-runtime/server/file-cache.ts` |
-| Slack Chat SDK | Slack ingress, routing, and streaming replies | `channels/slack/server/*`, `app/api/channels/slack/*` |
-| Resend | Waitlist confirmation email delivery | `waitlist/server/email.ts` |
-
-## Repository layout
-
-| Path | Purpose |
-| --- | --- |
-| `app/` | App Router pages and HTTP endpoints |
-| `agent-runtime/` | Event queue, scheduler, workflows, and runtime handlers |
-| `agents/` | Agent-facing UI and server helpers |
-| `auth/` | Auth configuration and access control |
-| `channels/` | Slack adapters and channel dispatching |
-| `chat/` | Conversation persistence and chat helpers |
-| `connections/` | User-managed provider credentials |
-| `shared/` | Shared database, metadata, and server utilities |
-| `tools/` | Tool catalog, providers, and sandbox execution helpers |
-| `waitlist/` | Public waitlist flow and email integration |
-
-## Local versus deployed behavior
-
-Local development uses the same Next.js application and database schema as the
-deployed app. For most product work, the local environment is enough. Vercel is
-mainly useful when you want to exercise hosted or scheduled behavior such as:
-
-- workflow execution;
-- persistent sandbox lifecycle;
-- scheduler execution through Vercel Cron;
-- Slack ingress, Chat SDK queueing, and background streaming behavior.
diff --git a/docs/SLACK_INTEGRATION.md b/docs/SLACK_INTEGRATION.md
deleted file mode 100644
index 9bfbd757..00000000
--- a/docs/SLACK_INTEGRATION.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# Slack Integration
-
-Slack is a realtime ingress channel for agents. It uses Vercel Chat SDK for
-Slack transport, queueing, thread locking, and streaming replies. Agent
-execution does not go through `agent_events`; Slack turns run through the
-realtime `ToolLoopAgent` runner and persist visible state in `chat_message`.
-
-## Runtime Flow
-
-```mermaid
-flowchart TD
-  Slack[Slack Events API] --> Route["POST /api/channels/slack/events"]
-  Route --> Bot["channels/slack/server/bot.ts"]
-  Bot --> ChatSDK["Chat SDK thread lock + queue"]
-  ChatSDK --> Dispatch["runChannelChatTurn"]
-  Dispatch --> Routing["resolve ordered route candidates"]
-  Routing --> Messages["import provider history + skipped + current user chat_message"]
-  Messages --> Canonical["load Postgres chat_message history"]
-  Canonical --> Runner["runRealtimeChatTurn"]
-  Runner --> Agent["ToolLoopAgent"]
-  Agent --> Stream["AI SDK fullStream"]
-  Stream --> Thread["thread.post(fullStream)"]
-  Runner --> Persist["persist assistant text-only chat_message"]
-```
-
-The Slack webhook route acknowledges quickly and lets Chat SDK continue work via
-`waitUntil`. Inside a single Chat SDK handler, multi-agent fan-out is sequential:
-agents are never run in parallel for the same inbound Slack message.
-
-## Routing Order
-
-Routing returns ordered route objects, not just bare agents. Final ordering is:
-
-1. `installation.createdAt ASC`
-2. `installation.userId ASC`
-3. `agent.id ASC`
-
-This keeps multi-agent fan-out deterministic across retries and deploys.
-
-## Idempotency
-
-Chat SDK handles short-lived webhook dedupe, but transcript dedupe is enforced
-in Postgres. Each Slack user message id is deterministic per agent:
-
-```txt
-rawKey = [channel, externalScopeId, externalMessageKey, agentId].join('\u0000')
-id = `msg_${sha256(rawKey).base64url.slice(0, 16)}`
-```
-
-`externalScopeId` is the Slack team id. `externalMessageKey` is Chat SDK's
-provider-normalized `message.id`.
-
-User messages are upserted because provider-authored messages can be edited.
-If the current Slack message is unchanged and already exists for that agent,
-the runner is skipped. Messages supplied by Chat SDK as `context.skipped` are
-imported before the current message so the transcript keeps all user turns from
-a rapid burst. Missing messages in provider history are not treated as deletes.
-
-## Chat SDK State
-
-The Slack bot uses `SlackHybridState`:
-
-- `slack:installation:*` keys are intercepted and stored in Postgres so OAuth
-  installations stay owner-scoped and encrypted.
-- All other Chat SDK state goes to Redis: locks, queues, dedupe,
-  subscriptions, and ephemeral state.
-- `REDIS_URL` is required in every environment. There is no memory fallback.
-
-Chat SDK concurrency is configured as `queue`. While one handler is running,
-only the latest queued message is processed next; intermediate messages arrive
-as `context.skipped`.
-
-## Streaming And Persistence
-
-Slack receives AI SDK `result.fullStream` through Chat SDK `thread.post(...)`.
-The runner wraps the stream with `tapFullStream`, a single-consumer async
-generator that:
-
-- accumulates visible `text-delta` chunks for text-only persistence;
-- yields original chunks unchanged to Chat SDK;
-- avoids `ReadableStream.tee()` and double consumption.
-
-If `thread.post(...)` throws, the partial accumulator is not persisted. The
-error is logged and rethrown so Chat SDK releases its lock through its normal
-error path.
-
-Assistant delivery has no v1 reconciliation ledger. The runner persists the
-assistant text only after `thread.post(...)` completes. A provider-delivered
-assistant message can be missing from Postgres only if the process dies in the
-small window after delivery and before final persistence; that residual risk is
-accepted until incidents justify a delivery ledger.
-
-Budget refusal posts a plain text notice and persists an assistant text-only
-message without starting sandbox, model, or usage work. Step-limit notices are
-posted as a follow-up message and appended to the persisted assistant text.
-
-## Environment Variables
-
-```bash
-SLACK_CLIENT_ID=...
-SLACK_CLIENT_SECRET=...
-SLACK_SIGNING_SECRET=...
-SLACK_BOT_USERNAME=assistant
-REDIS_URL=redis://...
-```
-
-`CONNECTION_ENCRYPTION_KEY` is also required by the app and is reused to encrypt
-Slack bot tokens at rest.
-
-## Adding Another Channel
-
-Another realtime channel should reuse the same pattern:
-
-1. Add a Chat SDK adapter and webhook route.
-2. Normalize inbound events into `IncomingChannelTurn`.
-3. Import provider history as best-effort user messages.
-4. Persist skipped and current user turns with deterministic ids.
-5. Load model context from Postgres `chat_message`.
-6. Resolve ordered route objects and run agents sequentially.
-7. Stream AI SDK `fullStream` through the channel adapter.
-8. Persist the assistant transcript in the channel-specific format.
diff --git a/docs/adr/0004-agent-skills-use-dedicated-sandboxes.md b/docs/adr/0004-agent-skills-use-dedicated-sandboxes.md
index d3ae5f45..f04f5498 100644
--- a/docs/adr/0004-agent-skills-use-dedicated-sandboxes.md
+++ b/docs/adr/0004-agent-skills-use-dedicated-sandboxes.md
@@ -1,43 +1,29 @@
 # Agent Skills Use Dedicated Sandboxes
 
-OUTNA.ME supports Agent Skills as user-installed capability packages that may
-include executable scripts. Each skilled agent gets one dedicated persistent
-Skill Sandbox, created lazily on first skill install, instead of reusing the
-agent system sandbox or the existing maintainer tool sandbox runtime. The Skill
-Sandbox is intentionally permissive for script execution and public internet
-access, while the system sandbox remains the canonical memory filesystem.
+## Decision
+
+Agents with installed Agent Skills use a dedicated persistent Skill Sandbox,
+created lazily on first install. It is separate from the agent system sandbox
+and maintainer tool sandboxes.
+
+## Context
+
+Skills can include executable scripts and public internet access. The system
+sandbox is the canonical memory filesystem, so it should not become the
+permissive script workspace.
 
 ## Consequences
 
-Installed skills live under `skills/<slug>` and agent working files live under
-`workspace` inside the Skill Sandbox. The first version mirrors `bash-tool`'s
-skill contract: discover installed `SKILL.md` files, expose a `skill` loader
-tool with available skill names in its description, load skills by their
-declared names, return the selected skill's instructions and file list, and pair
-it with bash execution in the Skill Sandbox. Per-skill permission manifests and
-credential brokering can be added later if the product needs finer control.
-Skill names are unique per agent using case-insensitive comparison so runtime
-lookup remains unambiguous for users and models.
-Postgres stores an index of installed skills for UI, source metadata, and
-collision checks; the Skill Sandbox stores the actual skill files. Runtime skill
-discovery mirrors `bash-tool` and reads installed `SKILL.md` files from the
-Skill Sandbox rather than trusting the Postgres management index. At runtime,
-the Skill Sandbox is the source of truth; Postgres supports UX and recovery.
-Skill runtime tools are built-in conditional agent tools named `skill` and
-`bash`, added alongside file tools when valid skills exist, not maintainer tool
-attachments stored in `agent_tools`. The `bash` tool is scoped to the Skill
-Sandbox. Unlike `bash-tool`, OUTNA.ME does not add Skill Sandbox `readFile` or
-`writeFile` tools because those names already refer to the system sandbox memory
-tools. When skill tools are present, the agent system prompt explains that
-`bash` runs only in the Skill Sandbox while system memory files still use the
-existing file tools.
-Skills are managed in their own agent UI surface rather than inside the
-maintainer Tools catalog.
-Skill Sandbox command execution mirrors `bash-tool` output truncation and relies
-on the sandbox timeout rather than a separate bash-tool timeout. The sandbox
-timeout is set for longer script work, closer to repo workspaces than the system
-sandbox.
-Skill import copies packages into the Skill Sandbox without running automatic
-install or build hooks. The first UI surface is `/agents/[agentId]/skills`,
-separate from Tools, with install support for one skill at a time from GitHub,
-`SKILL.md`, or zip.
+- Installed skills live under `skills/<slug>`.
+- Skill working files live under `workspace`.
+- Postgres `agent_skills` stores UI metadata, source data, and collision checks.
+- Runtime discovery reads `SKILL.md` files from the Skill Sandbox.
+- Names are unique per agent using normalized case-insensitive comparison.
+- Runtime adds conditional `skill` and `bash` tools when valid skills exist.
+- `bash` runs only in the Skill Sandbox.
+- System memory still uses `readFile` and `writeFile`.
+- Skill imports copy files without automatic install or build hooks.
+- The first UI is `/agents/[agentId]/skills`.
+
+Per-skill permission manifests and credential brokering are deferred until the
+product needs finer control.
diff --git a/docs/adr/index.md b/docs/adr/index.md
new file mode 100644
index 00000000..96d7942a
--- /dev/null
+++ b/docs/adr/index.md
@@ -0,0 +1,10 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# ADR Index
+
+## Documents
+
+- [Store inference credentials separately from tool connections](0001-store-inference-credentials-separately.md)
+- [Cut over AI Gateway credentials to the inference credential store](0002-cut-over-ai-gateway-credentials.md)
+- [Model selection includes the inference provider](0003-model-selection-includes-inference-provider.md)
+- [Agent Skills Use Dedicated Sandboxes](0004-agent-skills-use-dedicated-sandboxes.md)
diff --git a/docs/agent-chat/api-contract.md b/docs/agent-chat/api-contract.md
new file mode 100644
index 00000000..deb5fc98
--- /dev/null
+++ b/docs/agent-chat/api-contract.md
@@ -0,0 +1,13 @@
+# Agent Chat API Contract
+
+Route contract:
+- Chat POST body is `{ messages, conversationId }`; `messages` must be a non-empty array.
+- `conversationId` must be a string 3..64 chars; draft ids are normally `cc_...`.
+- The route returns 401 unauthenticated, 404 wrong owner, 412 paused agent, and 400 for invalid body.
+- Before streaming, the route creates/fetches the agent-scoped conversation and inserts only the latest user message.
+- The realtime call uses `runId: rt_${crypto.randomUUID()}`, `source: chat`, `persistMode: ui-message-full`, and `buildRealtimeAgentTool`.
+- Conversation list GET returns `{ id, title, updatedAt }[]` with ISO `updatedAt`.
+- Sidebar fetches the list with `cache: no-store`; server cache uses `conversationListTag(agentId)`.
+- Rename/delete actions require session, agent ownership, and conversation ownership.
+
+Source anchors: `apps/api/app/api/agents/[agentId]/chat/route.ts`, `apps/api/app/api/agents/[agentId]/conversations/route.ts`, `packages/ai/chat/components/agent-sidebar-workspace/conversations.ts`, `packages/ai/chat/server/actions.ts`.
diff --git a/docs/agent-chat/edge-cases.md b/docs/agent-chat/edge-cases.md
new file mode 100644
index 00000000..67ebf487
--- /dev/null
+++ b/docs/agent-chat/edge-cases.md
@@ -0,0 +1,12 @@
+# Agent Chat Edge Cases
+
+Failure modes:
+- Chat POST returns 401 unauthenticated, 404 wrong owner, 412 paused agent, or 400 for invalid JSON/messages/conversation id.
+- A paused channel-bound agent posts an error notice instead of running.
+- Sidebar optimistic rows are rolled back or kept by revalidating after chat errors.
+- Assistant partials are not persisted when realtime finish is aborted or errored.
+- Provider-history import failures warn and continue with available messages.
+- Channel stream post failures post an agent failure notice and continue remaining routed agents.
+- Deleting the active conversation redirects to `/agents/[agentId]/chat`.
+
+Source anchors: `apps/api/app/api/agents/[agentId]/chat/route.ts`, `packages/ai/chat/components/agent-chat.tsx`, `packages/ai/agent-runtime/server/realtime-chat-runner.ts`, `packages/shared/channels/server/dispatch.ts`, `packages/ai/chat/server/actions.ts`.
diff --git a/docs/agent-chat/flow.md b/docs/agent-chat/flow.md
new file mode 100644
index 00000000..39e47879
--- /dev/null
+++ b/docs/agent-chat/flow.md
@@ -0,0 +1,12 @@
+# Agent Chat Flow
+
+Product behavior:
+- `/agents/[agentId]/chat` requires ownership and redirects to the most recent conversation or `/chat/new`.
+- `/chat/new` creates a `cc_` draft id and keeps it DB-free until the first send.
+- `AgentChat` posts `messages` plus `conversationId` to `/api/agents/[agentId]/chat`.
+- The route authenticates, checks ownership and `enabled`, creates or finds the conversation, then idempotently inserts the newest user message.
+- The realtime runner streams the assistant response back into `useChat`.
+- Draft URLs are promoted with `history.replaceState` after the first message so the chat surface does not remount.
+- The sidebar lists chats through SWR, supports optimistic first-row insertion, rename, delete, and title-refresh retries.
+
+Source anchors: `apps/app/app/agents/[agentId]/chat/page.tsx`, `apps/app/app/agents/[agentId]/chat/new/page.tsx`, `apps/api/app/api/agents/[agentId]/chat/route.ts`, `packages/ai/chat/components/agent-chat.tsx`.
diff --git a/docs/agent-chat/index.md b/docs/agent-chat/index.md
new file mode 100644
index 00000000..9ad21d65
--- /dev/null
+++ b/docs/agent-chat/index.md
@@ -0,0 +1,13 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Agent Chat Index
+
+## Documents
+
+- [Agent Chat API Contract](api-contract.md)
+- [Agent Chat Edge Cases](edge-cases.md)
+- [Agent Chat Flow](flow.md)
+- [Agent Chat Invariants](invariants.md)
+- [Agent Chat](overview.md)
+- [Agent Chat State](state.md)
+- [Agent Chat Tests](tests.md)
diff --git a/docs/agent-chat/invariants.md b/docs/agent-chat/invariants.md
new file mode 100644
index 00000000..d00116f2
--- /dev/null
+++ b/docs/agent-chat/invariants.md
@@ -0,0 +1,12 @@
+# Agent Chat Invariants
+
+Rules enforced in source:
+- Conversation lookup, listing, rename, delete, and page data are always scoped to the agent id.
+- User message inserts use `ON CONFLICT DO NOTHING`; duplicate ids do not touch `updatedAt`.
+- Channel message ids hash channel, external scope, external message key, and agent id.
+- A duplicate current channel message with unchanged content skips the runner.
+- Title generation only updates null or placeholder `New Chat` titles.
+- Greeting-only first turns do not generate a title; the first substantive user message seeds the title.
+- Rename trims to 80 characters and rejects empty titles before updating.
+
+Source anchors: `packages/ai/chat/server/chat.ts`, `packages/ai/chat/server/actions.ts`, `packages/ai/chat/workflows/steps/generate-conversation-title.ts`, `packages/shared/channels/server/dispatch.ts`.
diff --git a/docs/agent-chat/overview.md b/docs/agent-chat/overview.md
new file mode 100644
index 00000000..4adabb38
--- /dev/null
+++ b/docs/agent-chat/overview.md
@@ -0,0 +1,13 @@
+# Agent Chat
+
+Scope: multi-conversation transcripts for one agent across in-app chat and channel thread mappings.
+
+Read this folder as:
+- [Flow](flow.md): redirects, draft promotion, chat POST, streaming, and sidebar behavior.
+- [API contract](api-contract.md): request bodies, status codes, conversation list, and actions.
+- [State](state.md): chat tables, channel thread mapping, history loading, and compacted model input.
+- [Invariants](invariants.md): agent scoping, idempotent ids, title generation, and rename limits.
+- [Edge cases](edge-cases.md): paused agents, optimistic rollback, partial drops, provider history, and channel failures.
+- [Tests](tests.md): persistence, ownership, and title-generation coverage.
+
+Primary source anchors: `apps/api/app/api/agents/[agentId]/chat/route.ts`, `packages/ai/chat/server/chat.ts`, `packages/ai/chat/components/agent-chat.tsx`.
diff --git a/docs/agent-chat/state.md b/docs/agent-chat/state.md
new file mode 100644
index 00000000..047471ae
--- /dev/null
+++ b/docs/agent-chat/state.md
@@ -0,0 +1,12 @@
+# Agent Chat State
+
+Persisted state:
+- `chat_conversation` stores `id`, `agentId`, optional `title`, and `updatedAt`; sidebar ordering is newest first by agent.
+- `chat_message` stores role, full AI SDK `parts` JSONB, metadata, and creation time.
+- Chat history is loaded only after agent ownership and conversation ownership pass.
+- In-app chat persists the newest user message before streaming; assistant output is persisted on realtime finish.
+- Channel threads map to conversations in `channel_thread_conversations`, one external thread per agent.
+- Provider/skipped/current channel messages are upserted into `chat_message` before the runner loads canonical Postgres history.
+- Sub-agent tool outputs remain raw in persisted messages and are compacted only for model input.
+
+Source anchors: `packages/db/schema/chat.ts`, `packages/db/schema/channels.ts`, `apps/app/app/agents/[agentId]/chat/[conversationId]/conversation-page-data.ts`, `packages/ai/chat/server/chat.ts`, `packages/ai/chat/server/chat-model.ts`, `packages/shared/channels/server/dispatch.ts`.
diff --git a/docs/agent-chat/tests.md b/docs/agent-chat/tests.md
new file mode 100644
index 00000000..e5c16f02
--- /dev/null
+++ b/docs/agent-chat/tests.md
@@ -0,0 +1,12 @@
+# Agent Chat Tests
+
+Covered:
+- `insertChatMessageIfNew` returns false and skips `updatedAt` on duplicate ids.
+- Concurrent duplicate inserts rely on `ON CONFLICT DO NOTHING RETURNING id`.
+- `upsertChatMessage` updates changed provider messages and returns `unchanged` for equivalent JSON.
+- Conversation page data loads history only after agent and conversation ownership checks.
+- Title generation skips greetings, replaces placeholder `New Chat`, and falls back when the model returns `New Chat`.
+
+Test anchors: `packages/ai/chat/server/chat.test.ts`, `apps/app/app/agents/[agentId]/chat/[conversationId]/conversation-page-data.test.ts`, `packages/ai/chat/workflows/steps/generate-conversation-title.test.ts`.
+
+Known gap: chat route status codes and sidebar UI interactions need manual browser verification.
diff --git a/docs/agent-creation-chat/edge-cases.md b/docs/agent-creation-chat/edge-cases.md
new file mode 100644
index 00000000..75df9247
--- /dev/null
+++ b/docs/agent-creation-chat/edge-cases.md
@@ -0,0 +1,12 @@
+# Agent Creation Chat Edge Cases
+
+Failure modes:
+- Unauthenticated requests return 401.
+- Invalid JSON or a non-array `messages` body returns 400.
+- Missing default inference credentials return 428 with `inference_provider_missing`.
+- Daily-time heartbeat creation requires at least one `HH:mm` time when enabled.
+- Creation-service provider, model, and limit failures surface through the tool call output.
+- Tool attachment failures do not roll back the created agent; they are returned per attachment.
+- Budget-rule persistence errors are logged and do not fail agent creation.
+
+Source anchors: `packages/shared/agents/api/creation-chat/route-handler.ts`, `packages/shared/agents/api/creation-chat/schemas.ts`, `packages/shared/agents/api/creation-chat/create-requested-agent.ts`, `packages/shared/agents/server/creation-service.ts`.
diff --git a/docs/agent-creation-chat/flow.md b/docs/agent-creation-chat/flow.md
new file mode 100644
index 00000000..63a55561
--- /dev/null
+++ b/docs/agent-creation-chat/flow.md
@@ -0,0 +1,12 @@
+# Agent Creation Chat Flow
+
+Product behavior:
+- `/agents/new` requires a session, loads the user's timezone, and renders an empty in-memory chat.
+- The client posts `messages` to `/api/agent-creation/chat`; the app route delegates to the shared handler.
+- The handler authenticates, validates `messages`, resolves enabled providers, and runs the creator model with step limit 8.
+- Read tool `list_available_tools` returns maintainer tools, connector states, exposed tools, config fields, and existing sub-agents.
+- `propose_agent_budget` renders an editable budget widget; the widget sends a follow-up message with the chosen values.
+- `create_requested_agent` is approval-gated and renders a final configuration card before database mutation.
+- On finish the client refreshes the page; success output links to overview, configure, and tools.
+
+Source anchors: `apps/app/app/(app)/agents/new/page.tsx`, `packages/shared/agents/components/agent-creation-chat.tsx`, `apps/api/app/api/agent-creation/chat/route.ts`, `packages/shared/agents/api/creation-chat/route-handler.ts`.
diff --git a/docs/agent-creation-chat/index.md b/docs/agent-creation-chat/index.md
new file mode 100644
index 00000000..ef86cbfe
--- /dev/null
+++ b/docs/agent-creation-chat/index.md
@@ -0,0 +1,12 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Agent Creation Chat Index
+
+## Documents
+
+- [Agent Creation Chat Edge Cases](edge-cases.md)
+- [Agent Creation Chat Flow](flow.md)
+- [Agent Creation Chat Invariants](invariants.md)
+- [Agent Creation Chat](overview.md)
+- [Agent Creation Chat State](state.md)
+- [Agent Creation Chat Tests](tests.md)
diff --git a/docs/agent-creation-chat/invariants.md b/docs/agent-creation-chat/invariants.md
new file mode 100644
index 00000000..3c93e06b
--- /dev/null
+++ b/docs/agent-creation-chat/invariants.md
@@ -0,0 +1,12 @@
+# Agent Creation Chat Invariants
+
+Rules enforced in source:
+- Before suggesting exact tool ids, the assistant must call `list_available_tools`.
+- Multiple enabled providers require an explicit user provider choice before final creation.
+- Final creation must include both `inferenceProvider` and provider-scoped `model`.
+- The assistant must call `propose_agent_budget` exactly once, wait for the widget follow-up, then use those confirmed values.
+- `create_requested_agent` mutates only after AI SDK tool approval.
+- If approval is denied, the assistant should ask for changes instead of retrying the same create call.
+- `instructions` is only the custom block appended below the platform `AGENTS.md` template.
+
+Source anchors: `packages/shared/agents/api/creation-chat/instructions.ts`, `packages/shared/agents/api/creation-chat/schemas.ts`, `packages/shared/agents/components/agent-creation-chat/budget-card.tsx`, `packages/shared/agents/api/creation-chat/create-requested-agent.ts`.
diff --git a/docs/agent-creation-chat/overview.md b/docs/agent-creation-chat/overview.md
new file mode 100644
index 00000000..56e0af96
--- /dev/null
+++ b/docs/agent-creation-chat/overview.md
@@ -0,0 +1,12 @@
+# Agent Creation Chat
+
+Scope: ephemeral AI SDK chat on `/agents/new` that guides an operator to a reviewed agent configuration.
+
+Read this folder as:
+- [Flow](flow.md): page, route, creator tools, budget widget, and approval UI.
+- [State](state.md): ephemeral transcript, tool parts, persisted creation output, attachments, and budgets.
+- [Invariants](invariants.md): exact ids, provider/model choice, budget round-trip, and approval consent.
+- [Edge cases](edge-cases.md): auth, malformed input, missing credentials, schema failures, and partial attachment failures.
+- [Tests](tests.md): covered lower layers and manual verification anchors.
+
+Primary source anchors: `apps/app/app/(app)/agents/new/page.tsx`, `packages/shared/agents/components/agent-creation-chat.tsx`, `packages/shared/agents/api/creation-chat/route-handler.ts`.
diff --git a/docs/agent-creation-chat/state.md b/docs/agent-creation-chat/state.md
new file mode 100644
index 00000000..e516124a
--- /dev/null
+++ b/docs/agent-creation-chat/state.md
@@ -0,0 +1,11 @@
+# Agent Creation Chat State
+
+State model:
+- The creation transcript is client memory only; there is no durable chat row or replay source.
+- A reload/tab close warns while messages exist and no `create_requested_agent` output is available.
+- Tool parts carry proposal state, approval state, final config, and creation output inside the AI SDK message stream.
+- `AgentCreationRequest` persists into an `agent` row, bootstrap markdown, tool attachments, capability summary, and budget rules.
+- Positive budget caps create daily/weekly/monthly rules; null or non-positive creation caps are skipped.
+- Tool attachment results return `connected`, `pending`, or `failed` per requested attachment.
+
+Source anchors: `packages/shared/agents/components/agent-creation-chat.tsx`, `packages/shared/agents/api/creation-chat/schemas.ts`, `packages/shared/agents/api/creation-chat/create-requested-agent.ts`, `packages/shared/agents/components/agent-creation-chat/create-agent-tool-card.tsx`.
diff --git a/docs/agent-creation-chat/tests.md b/docs/agent-creation-chat/tests.md
new file mode 100644
index 00000000..3021965d
--- /dev/null
+++ b/docs/agent-creation-chat/tests.md
@@ -0,0 +1,13 @@
+# Agent Creation Chat Tests
+
+Covered by lower layers:
+- Creation limit enforcement and idempotent `toolCallId` retries are tested in the creation service.
+- Schedule parsing/normalization has shared schedule tests.
+- Attachment, budget widget, and approval-card behavior currently rely on source review and manual browser verification.
+
+Test anchors: `packages/shared/agents/server/creation-service.test.ts`, `packages/shared/agent-schedule.test.ts`.
+
+Manual anchors:
+- `apps/app/app/(app)/agents/new/page.tsx`
+- `packages/shared/agents/components/agent-creation-chat.tsx`
+- `packages/shared/agents/components/agent-creation-chat/create-agent-tool-card.tsx`
diff --git a/docs/agent-edit-chat/edge-cases.md b/docs/agent-edit-chat/edge-cases.md
new file mode 100644
index 00000000..cd93587f
--- /dev/null
+++ b/docs/agent-edit-chat/edge-cases.md
@@ -0,0 +1,12 @@
+# Agent Edit Chat Edge Cases
+
+Failure modes:
+- Unauthenticated requests return 401.
+- Missing or wrong-owner agents return 404 before message parsing reaches model execution.
+- Invalid JSON or a non-array `messages` body returns 400.
+- Missing default inference provider fails before the edit model can run.
+- Invalid provider/model changes throw from `updateAgentForUser`.
+- Attach/detach operations return result objects; failures do not mutate unrelated configuration.
+- Denied approval produces no mutation because AI SDK approval is the consent boundary.
+
+Source anchors: `packages/shared/agents/api/edit-chat/route-handler.ts`, `packages/shared/agents/server/update-service.ts`, `packages/shared/agents/components/agent-edit-chat/tool-parts.tsx`, `packages/shared/agents/api/edit-chat/budget-tools.ts`.
diff --git a/docs/agent-edit-chat/flow.md b/docs/agent-edit-chat/flow.md
new file mode 100644
index 00000000..27ff7a8b
--- /dev/null
+++ b/docs/agent-edit-chat/flow.md
@@ -0,0 +1,12 @@
+# Agent Edit Chat Flow
+
+Product behavior:
+- Configure renders manual controls first, then "Assisted editing" with current settings, bootstrap markdown, and budget summary.
+- The client posts to `/api/agents/[agentId]/edit/chat`; the app route delegates to the shared handler.
+- The handler authenticates, checks ownership, validates `messages`, resolves the edit model, and loads tool visibility.
+- The edit model runs with step limit 8 and a tool snapshot embedded in its instructions.
+- Read tools expose current config, available tools, and current budget.
+- Mutation tools update config, attach/detach tools, attach sub-agents, or set budget after approval.
+- On finish, the client refreshes so manual controls reflect accepted changes.
+
+Source anchors: `apps/app/app/agents/[agentId]/configure/page.tsx`, `packages/shared/agents/components/agent-edit-chat.tsx`, `apps/api/app/api/agents/[agentId]/edit/chat/route.ts`, `packages/shared/agents/api/edit-chat/route-handler.ts`.
diff --git a/docs/agent-edit-chat/index.md b/docs/agent-edit-chat/index.md
new file mode 100644
index 00000000..73513a90
--- /dev/null
+++ b/docs/agent-edit-chat/index.md
@@ -0,0 +1,12 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Agent Edit Chat Index
+
+## Documents
+
+- [Agent Edit Chat Edge Cases](edge-cases.md)
+- [Agent Edit Chat Flow](flow.md)
+- [Agent Edit Chat Invariants](invariants.md)
+- [Agent Edit Chat](overview.md)
+- [Agent Edit Chat State](state.md)
+- [Agent Edit Chat Tests](tests.md)
diff --git a/docs/agent-edit-chat/invariants.md b/docs/agent-edit-chat/invariants.md
new file mode 100644
index 00000000..1b4cd122
--- /dev/null
+++ b/docs/agent-edit-chat/invariants.md
@@ -0,0 +1,12 @@
+# Agent Edit Chat Invariants
+
+Rules enforced in source:
+- Manual controls remain canonical; assisted chat uses the same update service and cache invalidation surfaces.
+- Normal config changes require approval through `apply_agent_edit`.
+- Attach/detach operations must use exact ids from `get_available_agent_tools`; sub-agent candidates exclude the current agent.
+- Connector-backed tools can be pre-wired while missing/invalid connections are disclosed to the user.
+- Budget edits read current caps when unknown, call `propose_agent_budget` once, wait for widget follow-up, then call `set_agent_budget`.
+- Provider/model changes are validated unless both values are unchanged from the current row.
+- Bootstrap writes happen only for LF-normalized fields that changed.
+
+Source anchors: `packages/shared/agents/api/edit-chat/tool-visibility.ts`, `packages/shared/agents/api/edit-chat/route-handler.ts`, `packages/shared/agents/components/agent-edit-chat/budget-preview.tsx`, `packages/shared/agents/server/update-service.ts`.
diff --git a/docs/agent-edit-chat/overview.md b/docs/agent-edit-chat/overview.md
new file mode 100644
index 00000000..9089fe4e
--- /dev/null
+++ b/docs/agent-edit-chat/overview.md
@@ -0,0 +1,12 @@
+# Agent Edit Chat
+
+Scope: ephemeral assisted-editing chat inside configure for one owned agent.
+
+Read this folder as:
+- [Flow](flow.md): configure surface, route handler, read tools, and approval-gated mutations.
+- [State](state.md): current config, bootstrap extraction, budgets, and tool visibility.
+- [Invariants](invariants.md): canonical manual controls, exact tool ids, budget round-trip, and update validation.
+- [Edge cases](edge-cases.md): auth, ownership, malformed input, provider/model failures, and denied approvals.
+- [Tests](tests.md): lower-layer coverage and manual verification anchors.
+
+Primary source anchors: `apps/app/app/agents/[agentId]/configure/page.tsx`, `packages/shared/agents/components/agent-edit-chat.tsx`, `packages/shared/agents/api/edit-chat/route-handler.ts`.
diff --git a/docs/agent-edit-chat/state.md b/docs/agent-edit-chat/state.md
new file mode 100644
index 00000000..a2aa3ca5
--- /dev/null
+++ b/docs/agent-edit-chat/state.md
@@ -0,0 +1,11 @@
+# Agent Edit Chat State
+
+State model:
+- The edit transcript is in-memory only and guarded against reload while a request is busy.
+- Current config loads the owned agent plus `IDENTITY.md`, `SOUL.md`, `AGENTS.md`, and `USER.md`.
+- `AGENTS.md` is reduced to the custom instruction block before entering the edit prompt.
+- `apply_agent_edit` reloads current bootstrap contents and passes originals to the update service.
+- Budget state is daily/weekly/monthly USD caps; `null` clears a cap in `set_agent_budget`.
+- Tool visibility includes attached tools, removed-from-catalog tools, connector statuses, config fields, and sub-agent candidates.
+
+Source anchors: `packages/shared/agents/api/edit-chat/current-config.ts`, `packages/shared/agents/api/edit-chat/budget-tools.ts`, `packages/shared/agents/api/edit-chat/tool-visibility.ts`, `packages/shared/agents/server/update-service.ts`.
diff --git a/docs/agent-edit-chat/tests.md b/docs/agent-edit-chat/tests.md
new file mode 100644
index 00000000..0484b547
--- /dev/null
+++ b/docs/agent-edit-chat/tests.md
@@ -0,0 +1,13 @@
+# Agent Edit Chat Tests
+
+Covered by lower layers:
+- Schedule normalization and shared creation/update constraints are tested where those helpers live.
+- Budget-rule application is source-only in this area; no focused edit-chat budget test exists.
+- Tool visibility and approval UI are source-reviewed and need manual browser verification for regressions.
+
+Test anchors: `packages/shared/agent-schedule.test.ts`.
+
+Manual anchors:
+- `apps/app/app/agents/[agentId]/configure/page.tsx`
+- `packages/shared/agents/components/agent-edit-chat.tsx`
+- `packages/shared/agents/api/edit-chat/route-handler.ts`
diff --git a/docs/agent-events/concurrency-idempotency.md b/docs/agent-events/concurrency-idempotency.md
new file mode 100644
index 00000000..1695e9a4
--- /dev/null
+++ b/docs/agent-events/concurrency-idempotency.md
@@ -0,0 +1,19 @@
+# Concurrency And Idempotency
+
+Scope: duplicate suppression and single-active-run guarantees for durable events.
+
+- `agent_events_idempotency_idx` is unique on `idempotency_key`.
+- `agent_events_active_concurrency_idx` is unique for non-null `concurrency_key` while status is `starting|running`.
+- Enqueue uses `onConflictDoNothing`; a duplicate idempotency key resolves to the existing event.
+- Claim checks active rows for the same key and treats Postgres `23505` as a lost race.
+- Scheduled heartbeat/dreaming use the same `sched:...` value for idempotency and concurrency.
+- Interval key: `sched:<agentId>:<type>:<bucket>`, where bucket is `floor(now / intervalMs)`.
+- Daily key: `sched:<agentId>:<type>:daily:<localDate>:<HHmm>`.
+- Manual heartbeat/dreaming use `manual:<agentId>:<type>:<nanoid>` and `concurrencyKey: null`.
+- Invocation idempotency is `invocation:<childId>:<parentRunId|root>:<toolCallId|streamToken>`.
+- Invocation rows currently have no concurrency key; parent retry handles a queued child with no run id.
+- `blockedByEventId` is a summary-only lookup from queued rows to active same-key rows.
+- Workflow `finally` starts the next due queued row for the same concurrency key in `queuedAt` order.
+
+Source: `packages/db/schema/agents.ts`; `server/agent-event-keys.ts`; `server/session-events.ts`; `server/agent-invocation-events.ts`; `server/agent-event-summaries.ts`.
+Tests: `server/agent-event-keys.test.ts`; `server/agent-invocation-events.step.unit.test.ts`; `workflows/events/workflow.workflow.unit.test.ts`.
diff --git a/docs/agent-events/event-kinds.md b/docs/agent-events/event-kinds.md
new file mode 100644
index 00000000..dd14c3ae
--- /dev/null
+++ b/docs/agent-events/event-kinds.md
@@ -0,0 +1,17 @@
+# Adding Event Kinds
+
+Scope: implementation checklist for adding or changing durable event types.
+
+- Update DB enum values and shared event type unions before adding ingress.
+- Add the payload shape in `shared/event-payload.ts`; workflow dispatch casts through `payloadAs`.
+- Add summary preview and any UI labels in shared event summary/type helpers.
+- Add a `dispatchAgentEvent` case and decide which handler owns terminal transcript persistence.
+- If the event streams somewhere other than `reply:<eventId>`, update `outputNamespaceForAgentEvent`.
+- If the handler uses `buildAgent`, add/confirm `AgentRuntimeEventKind` support.
+- Choose `source`, idempotency key, and concurrency key at enqueue time.
+- Scheduled events should use stable slot keys; manual events should use random idempotency.
+- Keep workflow cleanup generic; resource cleanup belongs in `cleanupEventResources` or handler steps.
+- Add tests for dispatch routing, namespace/transcript selection, key stability, and recovery behavior.
+
+Source: `packages/db/schema/agents.ts`; `shared/event-payload.ts`; `server/agent-event-summaries.ts`; `workflows/agent-events/workflow.ts`; `workflows/session/runtime-spec-types.ts`.
+Tests: `workflows/events/workflow.workflow.unit.test.ts`; `server/agent-event-transcript.test.ts`; `server/agent-event-keys.test.ts`; `server/agent-event-reconciliation.test.ts`.
diff --git a/docs/agent-events/index.md b/docs/agent-events/index.md
new file mode 100644
index 00000000..b9a4fa16
--- /dev/null
+++ b/docs/agent-events/index.md
@@ -0,0 +1,11 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Agent Events Index
+
+## Documents
+
+- [Concurrency And Idempotency](concurrency-idempotency.md)
+- [Adding Event Kinds](event-kinds.md)
+- [Agent Events](overview.md)
+- [Agent Event State Machine](state-machine.md)
+- [Transcript And Activity Streams](streams.md)
diff --git a/docs/agent-events/overview.md b/docs/agent-events/overview.md
new file mode 100644
index 00000000..b1850107
--- /dev/null
+++ b/docs/agent-events/overview.md
@@ -0,0 +1,30 @@
+# Agent Events
+
+Scope: durable ledger for heartbeat, dreaming, and invocation; realtime chat is outside except when it enqueues invocations.
+
+## Flow
+1. Ingress inserts or reuses a `queued` row by idempotency key.
+2. Start ignores future/nonqueued rows, then claims due rows for 5 minutes.
+3. Workflow marks `running`, dispatches by type, then marks terminal.
+4. `finally` cleans run sandboxes/cache and starts the next row sharing the concurrency key.
+
+## State
+- Statuses: `queued` -> `starting` -> `running` -> `completed`/`failed`/`cancelled`.
+- `starting` has `claimExpiresAt`; `running` has `workflowRunId` and `heartbeatAt`.
+- Summaries reconcile active rows and expose `blockedByEventId`.
+
+## Invariants
+- Idempotency keys dedupe ingress; concurrency keys permit one active row per key.
+- Output is `reply:<eventId>` except invocation `streamToken`; activity is `events:<runId>`.
+- Terminal events with workflow run ids should have persisted transcript rows.
+
+## Failure Modes
+- Workflow start failure resets `starting` to `queued`.
+- Scheduler fails running rows after 90 minutes without heartbeat.
+- Missing persisted terminal transcript returns 409 on transcript route.
+
+## Anchors
+- `apps/api/app/api/agents/[agentId]/events/route.ts`, `.../[eventId]/stream/route.ts`
+- `packages/ai/agent-runtime/server/agent-event-store.ts`, `agent-event-start.ts`
+- `packages/ai/agent-runtime/server/agent-event-transcript.ts`
+- `packages/ai/agent-runtime/workflows/agent-events/workflow.ts`
diff --git a/docs/agent-events/state-machine.md b/docs/agent-events/state-machine.md
new file mode 100644
index 00000000..2c1f348d
--- /dev/null
+++ b/docs/agent-events/state-machine.md
@@ -0,0 +1,19 @@
+# Agent Event State Machine
+
+Scope: durable rows in `agent_events`; realtime chat is outside this ledger.
+
+- Statuses are `queued`, `starting`, `running`, `completed`, `failed`, `cancelled`.
+- Insert path creates `queued`; idempotency conflicts return the existing row.
+- `queued -> starting`: `claimQueuedEvent` requires due time and no active same concurrency key.
+- Claim increments `attempt`, sets `startedAt`, `claimExpiresAt` to +5m, and clears `lastError`/`workflowRunId`.
+- `starting -> running`: event workflow calls `markEventRunning`, clears claim, sets `workflowRunId`, `heartbeatAt`, `startedAt`.
+- `starting -> queued`: starter failure or expired claim without a live workflow calls `resetStartingEvent`.
+- `running -> completed`: dispatch returns and workflow marks terminal `completed`.
+- `starting|running -> failed`: workflow catch marks `failed`; reconciliation maps workflow `failed|cancelled` to failed.
+- `running -> failed`: reconciliation fails stale rows after 90m without `heartbeatAt` progress.
+- `starting|running -> completed`: reconciliation maps workflow `completed` or missing run `not_found` to completed.
+- Active statuses are only `starting` and `running`; terminal statuses are `completed`, `failed`, `cancelled`.
+- Missing/non-active rows make `agentEventWorkflow` return before cleanup or queue handoff.
+
+Source: `packages/db/schema/agents.ts`; `server/agent-event-start.ts`; `server/agent-event-store.ts`; `server/agent-event-reconciliation.ts`; `workflows/agent-events/workflow.ts`.
+Tests: `server/agent-event-reconciliation.test.ts`; `workflows/events/workflow.workflow.unit.test.ts`; `server/agent-event-workflow-starter.unit.test.ts`.
diff --git a/docs/agent-events/streams.md b/docs/agent-events/streams.md
new file mode 100644
index 00000000..0b056ae3
--- /dev/null
+++ b/docs/agent-events/streams.md
@@ -0,0 +1,19 @@
+# Transcript And Activity Streams
+
+Scope: durable event stream APIs and transcript persistence.
+
+- Output namespace is `reply:<eventId>` except invocation, which uses payload `streamToken`.
+- Activity namespace is `events:<workflowRunId>` from `runEventsNamespace`.
+- `GET .../stream?stream=output|activity&startIndex=N` reads from the selected namespace.
+- `startIndex` is floored and clamped to `>=0`; invalid input replays from `0`.
+- Route emits newline-delimited JSON and sets `no-store, no-transform`.
+- Missing readable workflow id returns 409 `event has not started yet`.
+- Missing workflow run triggers active-event reconciliation, then returns 503 unavailable.
+- Live hook opens output and activity streams, tracking separate replay indexes.
+- 409 is pending and retries after 1500ms; 503 is unavailable and triggers fallback handling.
+- Generic stream failures retry up to 5 attempts with 1s, 2s, 4s, then 8s backoff.
+- Terminal events with a workflow run require persisted transcript rows; missing rows return transcript 409.
+- Non-terminal/no-run events use fallback messages such as queued, starting, or failed status text.
+
+Source: `apps/api/app/api/agents/[agentId]/events/[eventId]/stream/route.ts`; `.../transcript/route.ts`; `server/agent-event-transcript.ts`; `hooks/use-agent-event-live-transcript.ts`.
+Tests: `apps/api/app/api/agents/[agentId]/events/[eventId]/stream/route.test.ts`; `.../transcript/route.test.ts`; `server/agent-event-transcript.test.ts`; `hooks/agent-event-stream-outcome.test.ts`.
diff --git a/docs/agent-management/configuration-contract.md b/docs/agent-management/configuration-contract.md
new file mode 100644
index 00000000..e97717ae
--- /dev/null
+++ b/docs/agent-management/configuration-contract.md
@@ -0,0 +1,14 @@
+# Agent Configuration Contract
+
+Implementation contract:
+- `AgentFormState` mirrors persisted fields; `activeBootstrapFile` is view state and excluded from dirty checks.
+- Save rejects blank names client-side and trims before calling server actions.
+- Create sends `CreateInput` to `createAgentAction`; edit sends `UpdateAgentInput` plus original bootstrap contents.
+- Bootstrap mapping is `identityCard -> IDENTITY.md`, `identity -> SOUL.md`, `instructions -> AGENTS.md`, and `userProfile -> USER.md`.
+- Configure provider options include the current provider even if it is no longer configured.
+- Changing provider keeps the current model only when it exists for that provider; otherwise it selects the provider default.
+- Custom step limit is persisted only for `custom`; other modes persist `stepLimitCustom: null`.
+- Dirty and unload guards cover persisted field changes, not bootstrap tab selection.
+- The update service revalidates provider/model changes, normalizes schedule values, writes changed bootstrap files, and refreshes capability summary.
+
+Source anchors: `packages/shared/agents/components/agent-form.tsx`, `packages/shared/agents/components/agent-form/agent-form-state.ts`, `packages/shared/agents/components/agent-form/model-selector.tsx`, `packages/shared/agents/components/agent-form/options.ts`, `packages/shared/agents/server/update-service.ts`.
diff --git a/docs/agent-management/edge-cases.md b/docs/agent-management/edge-cases.md
new file mode 100644
index 00000000..4bf57bc9
--- /dev/null
+++ b/docs/agent-management/edge-cases.md
@@ -0,0 +1,12 @@
+# Agent Management Edge Cases
+
+Failure modes:
+- New-agent buttons show an "Agent limit reached" dialog before navigation when `canCreate` is false.
+- The creation service still enforces the limit, so races or bypassed UI return `AgentCreationLimitExceededError`.
+- Missing provider credentials reject creation/update with "Selected inference provider is not configured."
+- A paused agent remains visible in the registry, but chat rejects new turns and channel dispatch posts a paused-agent notice.
+- If delete cannot find an owned agent, it redirects to `/agents`.
+- Delete marks all `agent_events` for the agent as `cancelled` with `lastError: agent deleted`.
+- Sandbox cleanup is attempted before deleting the row; cleanup errors can block the action because they are awaited.
+
+Source anchors: `packages/shared/agents/components/new-agent-link.tsx`, `packages/shared/agents/server/actions.ts`, `apps/api/app/api/agents/[agentId]/chat/route.ts`, `packages/shared/channels/server/dispatch.ts`.
diff --git a/docs/agent-management/flow.md b/docs/agent-management/flow.md
new file mode 100644
index 00000000..3b361257
--- /dev/null
+++ b/docs/agent-management/flow.md
@@ -0,0 +1,12 @@
+# Agent Management Flow
+
+Product behavior:
+- `/agents` requires a session, loads cached agents plus user timezone, and gates New Agent with `canCreateAgentForUser`.
+- Registry search filters by name, model, active/paused state, heartbeat state, and dreaming state; Enter opens the first match.
+- Registry rows route directly to overview, chat, configure, and tools.
+- Configure loads the owned agent, bootstrap files, enabled providers, available models, Slack bindings, and budget rules.
+- Manual form updates and assisted edit chat both end at `updateAgentForUser`.
+- Pause/resume flips `agent.enabled`, refreshes the registry/agent pages, and shows a toast.
+- Delete verifies ownership, marks the agent's event rows cancelled, tries sandbox cleanup, deletes the agent row, then redirects to `/agents`.
+
+Source anchors: `apps/app/app/(app)/agents/page.tsx`, `apps/app/app/agents/[agentId]/configure/page.tsx`, `packages/shared/agents/components/agent-registry.tsx`, `packages/shared/agents/server/actions.ts`.
diff --git a/docs/agent-management/index.md b/docs/agent-management/index.md
new file mode 100644
index 00000000..8251fb81
--- /dev/null
+++ b/docs/agent-management/index.md
@@ -0,0 +1,14 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Agent Management Index
+
+## Documents
+
+- [Agent Configuration Contract](configuration-contract.md)
+- [Agent Management Edge Cases](edge-cases.md)
+- [Agent Management Flow](flow.md)
+- [Agent Management Invariants](invariants.md)
+- [Agent Management](overview.md)
+- [Agent Product Shell](product-shell.md)
+- [Agent Management State](state.md)
+- [Agent Management Tests](tests.md)
diff --git a/docs/agent-management/invariants.md b/docs/agent-management/invariants.md
new file mode 100644
index 00000000..f358cb38
--- /dev/null
+++ b/docs/agent-management/invariants.md
@@ -0,0 +1,12 @@
+# Agent Management Invariants
+
+Rules enforced in source:
+- Every server action requires a session and scopes mutations to `(agent.id, agent.userId)`.
+- Creation requires the selected inference provider to be enabled for the user.
+- Creation falls back to the provider default model when the requested model is invalid; update rejects invalid provider/model changes.
+- Heartbeat intervals are clamped to 5..1440 minutes and daily-time schedules are normalized for the selected mode.
+- Non-admin creation limit checks run under a per-user Postgres advisory transaction lock.
+- Idempotent creation uses `sha256(userId:toolCallId)` to derive a stable `ag_` id and may replay bootstrap writes.
+- Update writes bootstrap files only when LF-normalized content differs from the original loaded content.
+
+Source anchors: `packages/shared/agents/server/creation-service.ts`, `packages/shared/agents/server/update-service.ts`, `packages/shared/agents/server/actions.ts`, `packages/shared/agent-schedule.ts`.
diff --git a/docs/agent-management/overview.md b/docs/agent-management/overview.md
new file mode 100644
index 00000000..32a2643c
--- /dev/null
+++ b/docs/agent-management/overview.md
@@ -0,0 +1,14 @@
+# Agent Management
+
+Scope: user-owned `agent` rows, configuration surfaces, bootstrap markdown, lifecycle controls, shell navigation, cache revalidation, and sandbox cleanup.
+
+Read this folder as:
+- [Flow](flow.md): registry, configure, pause/resume, and delete behavior.
+- [Product shell](product-shell.md): layout, sidebar, tabs, triggers, and command palette.
+- [Configuration contract](configuration-contract.md): form state, save payloads, provider/model rules, and bootstrap mapping.
+- [State](state.md): persisted agent fields, bootstrap files, budgets, and cascades.
+- [Invariants](invariants.md): ownership, provider/model, schedule, creation limit, and bootstrap write rules.
+- [Edge cases](edge-cases.md): limit, paused, provider, deletion, and cleanup failures.
+- [Tests](tests.md): source-backed coverage and known manual gaps.
+
+Primary source anchors: `apps/app/app/(app)/agents/page.tsx`, `apps/app/app/agents/[agentId]/layout.tsx`, `apps/app/app/agents/[agentId]/configure/page.tsx`, `packages/shared/agents/server/actions.ts`.
diff --git a/docs/agent-management/product-shell.md b/docs/agent-management/product-shell.md
new file mode 100644
index 00000000..41531b1b
--- /dev/null
+++ b/docs/agent-management/product-shell.md
@@ -0,0 +1,13 @@
+# Agent Product Shell
+
+Implementation contract:
+- `AgentLayout` wraps every agent page in `AppShell`, agent sidebar extras, `AgentWorkspaceFrame`, and the global command palette.
+- `AgentWorkspaceFrame` requires session, loads the owned agent plus user timezone, and calls `notFound()` on missing ownership.
+- Header badges show active/paused, model, heartbeat schedule, and dreaming state.
+- Header actions are `Trigger now`, `Dream`, and `Configure`; trigger POST rejects paused agents with 412.
+- Workspace tabs are Overview, Chat, Events, Configure, Tools, Skills, and Memory.
+- Active-tab aliases include `/about` for overview, `/edit` for configure, and `/files`, `/timeline`, `/dreams` for memory.
+- Sidebar extras load cached conversations as ISO strings, then SWR owns client refresh.
+- Cmd+K receives the current user's agent ids, names, and enabled flags.
+
+Source anchors: `apps/app/app/agents/[agentId]/layout.tsx`, `packages/shared/agents/components/agent-workspace.tsx`, `packages/shared/agents/components/agent-workspace-header.tsx`, `packages/ai/chat/components/agent-sidebar-section.tsx`, `packages/shared/agents/components/global-command-palette.tsx`, `apps/api/app/api/agents/[agentId]/trigger/route.ts`.
diff --git a/docs/agent-management/state.md b/docs/agent-management/state.md
new file mode 100644
index 00000000..1c753d66
--- /dev/null
+++ b/docs/agent-management/state.md
@@ -0,0 +1,11 @@
+# Agent Management State
+
+Persisted state:
+- `agent` owns name, enabled flag, provider/model, step-limit mode/custom value, heartbeat cadence, dreaming flag, capability summary, and sandbox ids.
+- `sandboxSystemId` is the persistent system sandbox name; `sandboxSkillsId` is filled after skill installation.
+- Bootstrap markdown lives in agent memory files: `IDENTITY.md`, `SOUL.md`, `AGENTS.md`, and `USER.md`.
+- Configure shows only the custom instruction block extracted from `AGENTS.md`, not the full platform template.
+- Budget rules are scoped by user and agent; configure summarizes them beside manual and assisted editing.
+- Deleting an agent cascades dependent chat/channel rows through DB references after the agent row is removed.
+
+Source anchors: `packages/db/schema/agents.ts`, `packages/shared/agents/server/bootstrap-files.ts`, `packages/shared/agents/server/creation-service.ts`, `packages/shared/agents/server/update-service.ts`, `packages/db/schema/chat.ts`, `packages/db/schema/channels.ts`.
diff --git a/docs/agent-management/tests.md b/docs/agent-management/tests.md
new file mode 100644
index 00000000..fbe09d80
--- /dev/null
+++ b/docs/agent-management/tests.md
@@ -0,0 +1,13 @@
+# Agent Management Tests
+
+Covered:
+- Non-admin users at the three-agent limit are blocked before insert, bootstrap writes, or summary refresh.
+- Non-admin users below the limit can create; admins bypass the limit.
+- Idempotent creation retries for an existing `ag_` id succeed even when the user is at the limit.
+- Agent schedule normalization has focused tests outside this folder.
+
+Test anchors: `packages/shared/agents/server/creation-service.test.ts`, `packages/shared/agent-schedule.test.ts`.
+
+Known gaps:
+- Pause/resume and delete server actions rely on source review and manual browser verification.
+- Configure-page assisted edit behavior is covered through shared edit-chat sources, not a dedicated page test.
diff --git a/docs/agent-memory/index.md b/docs/agent-memory/index.md
new file mode 100644
index 00000000..d6bc6d84
--- /dev/null
+++ b/docs/agent-memory/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Agent Memory Index
+
+## Documents
+
+- [Agent Memory](overview.md)
+- [Sandbox Files Contract](sandbox-files-contract.md)
diff --git a/docs/agent-memory/overview.md b/docs/agent-memory/overview.md
new file mode 100644
index 00000000..94618141
--- /dev/null
+++ b/docs/agent-memory/overview.md
@@ -0,0 +1,30 @@
+# Agent Memory
+
+Scope/boundary:
+- Memory lives in persistent system Vercel Sandbox root `/vercel/sandbox`.
+- `agent.sandbox_system_id` stores name `agent-<id>-system`; network policy is `deny-all`.
+- System sandbox is separate from Skill Sandbox, tool sandboxes, brokered HTTP, and repo workspaces.
+
+Main flow:
+- Startup ensures the sandbox exists, then seeds `AGENTS.md` and `IDENTITY.md` once per marker.
+- Creation/update writes bootstrap files; `AGENTS.md` is rendered through template.
+- Model file tools read/write/list/grep live sandbox; cleanup refreshes Redis cache.
+
+State:
+- Redis cache has index and per-file records; sandbox is source of truth.
+- Cached UI reads Redis first; misses refresh sandbox/list or single file.
+- Tracked cache refresh includes canonical markdown and `logs/*.md`.
+
+Invariants:
+- No system bash tool; only `readFile`, `writeFile`, `listFiles`, and `grepFiles`.
+- Paths must stay under root; reject root, NUL, over 512 chars, and escapes.
+- `AGENTS.md`, `IDENTITY.md`, and `SOUL.md` are settings-owned/read-only to agent.
+- `USER.md` is eager context but agent-writable.
+- Reads cap 256 KiB and require UTF-8; grep/list use fixed argv and max results.
+
+Failure modes:
+- Missing file returns `exists=false`; missing sandbox becomes nonretryable workflow error.
+- Cache absence is tolerated; writes go to sandbox and may merge cache.
+- Cleanup cache refresh failures are logged/ignored when sandbox is gone.
+
+Anchors: `packages/shared/agents/server/bootstrap-files.ts`, `packages/ai/agent-runtime/server/agent-sandbox*.ts`, `packages/ai/agent-runtime/server/file-cache.ts`, `packages/ai/agent-runtime/workflows/session/tools/file-tools*`, `apps/app/app/agents/[agentId]/memory/*`.
diff --git a/docs/agent-memory/sandbox-files-contract.md b/docs/agent-memory/sandbox-files-contract.md
new file mode 100644
index 00000000..fdba878d
--- /dev/null
+++ b/docs/agent-memory/sandbox-files-contract.md
@@ -0,0 +1,24 @@
+# Sandbox Files Contract
+
+System sandbox:
+- Name is `agent-<id>-system`, stored in `agent.sandbox_system_id`.
+- It is persistent, `node22`, one vCPU, short timeout, and `deny-all` networking.
+- Startup ensures the sandbox and seeds `AGENTS.md`/`IDENTITY.md` once per marker.
+- Settings writes can update bootstrap files and merge them into the cache.
+- The model gets only `readFile`, `writeFile`, `listFiles`, and `grepFiles`; no shell.
+
+File contract:
+- Paths may be relative or absolute but normalize under `/vercel/sandbox`.
+- Empty/root paths, NUL bytes, paths over 512 chars, and escapes are rejected.
+- `AGENTS.md`, `IDENTITY.md`, and `SOUL.md` are settings-owned read-only files.
+- `USER.md` is eager context but agent-writable.
+- Missing reads return `exists=false`; non-missing read errors propagate.
+- Reads cap at 256 KiB and require valid UTF-8.
+- Writes create parent directories with fixed `mkdir -p` argv and write UTF-8 bytes.
+- Lists use fixed `find`, return safe relative paths, and cap at 1000.
+- Grep uses fixed `grep -RInI`, caps at 200, and truncates long match lines.
+- Sandbox files are source of truth; Redis caches tracked canonical files and `logs/*.md`.
+- Cache records store content, path, SHA-256, and `updatedAt`; Redis absence is tolerated.
+
+Source anchors: `packages/ai/agent-runtime/server/agent-sandbox.ts`, `packages/ai/agent-runtime/server/system-sandbox-startup.ts`, `packages/ai/agent-runtime/workflows/session/tools/file-tools*`, `packages/ai/agent-runtime/server/file-cache.ts`.
+Test anchors: `packages/ai/agent-runtime/workflows/session/tools/file-tools.test.ts`, `packages/ai/agent-runtime/workflows/session/tools/file-tools/file-steps.step.unit.test.ts`, `packages/ai/agent-runtime/server/file-cache.test.ts`.
diff --git a/docs/agent-skills/index.md b/docs/agent-skills/index.md
new file mode 100644
index 00000000..7db8cddf
--- /dev/null
+++ b/docs/agent-skills/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Agent Skills Index
+
+## Documents
+
+- [Package Lifecycle](package-lifecycle.md)
+- [Agent Skills](runtime.md)
diff --git a/docs/agent-skills/package-lifecycle.md b/docs/agent-skills/package-lifecycle.md
new file mode 100644
index 00000000..4f3fbbd3
--- /dev/null
+++ b/docs/agent-skills/package-lifecycle.md
@@ -0,0 +1,24 @@
+# Package Lifecycle
+
+Import sources:
+- Install accepts `skill_md`, `zip`, GitHub URL, or `skills_sh` id.
+- Root `SKILL.md` must have YAML `name` and `description`; body is instructions.
+- Names normalize with trim, NFC, and lowercase for conflict checks.
+- Limits: 25 MiB package, 10 MiB file, 256 KiB `SKILL.md`, 200 files, 512-char paths.
+- ZIP packages may be at archive root or one enclosing directory.
+- ZIP entries reject absolute paths, traversal, NUL, duplicates, and non-regular entries.
+- GitHub import accepts repo, tree, or blob `SKILL.md` URLs and filters archive to source path.
+- `HEAD` GitHub imports resolve default branch before downloading from codeload.
+- `skills.sh` import fetches OIDC-authenticated snapshots; shebang files become executable.
+
+Install/replace:
+- Install verifies agent ownership, prepares package, and checks normalized-name conflict.
+- Existing name requires replace; replacing keeps the slug.
+- New slug collisions suffix from content hash.
+- Files are written under `/vercel/sandbox/skills/<slug>`.
+- Replace writes temp, moves current to backup, activates temp, and restores on failure.
+- Discovery scans depth-2 `SKILL.md`, skipping dot slugs, invalid files, and duplicate names.
+- Runtime exposes `skill` and `bash` only when discovery returns at least one skill.
+
+Source anchors: `packages/shared/agents/server/skills.ts`, `packages/ai/agent-runtime/skills/package.ts`, `packages/ai/agent-runtime/skills/github-import.ts`, `packages/ai/agent-runtime/skills/discovery.ts`, `packages/ai/agent-runtime/workflows/session/tools/skill-tools.ts`.
+Test anchors: `packages/ai/agent-runtime/skills/package.test.ts`, `packages/ai/agent-runtime/skills/github-import.test.ts`, `packages/ai/agent-runtime/skills/discovery.test.ts`, `packages/ai/agent-runtime/skills/skill-md.test.ts`.
diff --git a/docs/agent-skills/runtime.md b/docs/agent-skills/runtime.md
new file mode 100644
index 00000000..8985eb5c
--- /dev/null
+++ b/docs/agent-skills/runtime.md
@@ -0,0 +1,29 @@
+# Agent Skills
+
+Scope/boundary:
+- Packages live only in Skill Sandbox `/vercel/sandbox/skills/<slug>` with workspace `/vercel/sandbox/workspace`.
+- Every package requires root `SKILL.md` YAML `name`/`description`; instructions are file body.
+- `agent_skills` is catalog/source metadata; Skill tools are built-ins, not `agent_tools`.
+
+Main flow:
+- Install API accepts `skill_md`, `zip`, GitHub URL, or `skills_sh`; owner session required.
+- Prep normalizes paths, limits size/count, hashes content, and enforces unique normalized name unless replace.
+- Install ensures Skill Sandbox, writes package, upserts metadata, and revalidates.
+- Replace writes temp, backs up old dir, swaps, and restores if activation fails.
+- Runtime discovery scans depth-2 `SKILL.md`, skipping hidden slugs, invalid files, duplicate names.
+
+State:
+- Agent row stores `sandbox_skills_id`; null until first install.
+- Slug is stable for replacement; new slug collision suffixes content hash.
+- `resolveSkillPlan` returns empty when sandbox missing or discovery fails.
+
+Invariants:
+- Use `skill` before relying on a package; instructions are runtime source of truth.
+- `bash` runs only in Skill Sandbox workspace and paths must stay under `/vercel/sandbox`.
+- System memory uses system file tools; skill bash must not touch system memory.
+
+Failure modes:
+- Install errors include not found, invalid package, name conflict, sandbox unavailable, write failed, GitHub/catalog fetch failed.
+- Uninstall fails if sandbox/files cannot be removed; invalid runtime skills are ignored with warnings.
+
+Anchors: `packages/ai/agent-runtime/skills/*`, `packages/ai/agent-runtime/workflows/session/tools/skill-tools.ts`, `packages/shared/agents/server/skills.ts`, `apps/api/app/api/agents/[agentId]/skills/*`.
diff --git a/docs/auth-account/index.md b/docs/auth-account/index.md
new file mode 100644
index 00000000..b1235494
--- /dev/null
+++ b/docs/auth-account/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Auth Account Index
+
+## Documents
+
+- [OTP Flow](otp-flow.md)
+- [Auth Account](overview.md)
diff --git a/docs/auth-account/otp-flow.md b/docs/auth-account/otp-flow.md
new file mode 100644
index 00000000..03a27aee
--- /dev/null
+++ b/docs/auth-account/otp-flow.md
@@ -0,0 +1,21 @@
+# OTP Flow
+Scope: Sign-in gate for waitlist-provisioned Better Auth users.
+Better Auth:
+- Email OTP sign-up is disabled; public users cannot self-create through Better Auth.
+- OTPs are 6 digits, expire after 10 minutes, rotate on resend, and allow 5 attempts.
+- Sessions last 30 days and update at most once per day.
+- Admin users get `waitlist:manage` and `slack:use`; normal users do not.
+Request route:
+- POST `/api/auth/request-otp` runs bot guard before reading JSON.
+- IP and normalized-email limits are each 3 requests per minute.
+- Redis-backed limits use Upstash KV; otherwise process-local buckets are used.
+- Existing auth users receive OTP immediately after validation.
+Waitlist gate:
+- No row, `pending`, `confirmed`, and `unsubscribed` return 403 with specific messages.
+- `invited` and `converted` entries are provisioned before Better Auth sends the OTP.
+- POST `/api/auth/[...all]` also runs bot guard before delegating to Better Auth.
+Anchors:
+- `packages/auth/server/auth.ts`, `packages/auth/server/request-otp-rate-limit.ts`
+- `packages/auth/server/auth-guard.ts`
+- `packages/auth/access-control.ts`, `packages/db/schema/auth.ts`
+- Tests: `packages/db/schema/auth.test.ts`
diff --git a/docs/auth-account/overview.md b/docs/auth-account/overview.md
new file mode 100644
index 00000000..142bc721
--- /dev/null
+++ b/docs/auth-account/overview.md
@@ -0,0 +1,22 @@
+# Auth Account
+Scope: Better Auth identity, sessions, roles, OTP sign-in, and waitlist-gated provisioning; public signup is disabled.
+Flow:
+- `/api/auth/request-otp` denies bots, rate-limits by IP/email, normalizes email, and checks access.
+- Existing users get OTP; unknown `invited`/`converted` waitlist entries are provisioned first.
+- Better Auth sends six-digit sign-in OTPs, rotates on resend, allows five attempts, and expires in 10 minutes.
+- `/api/auth/[...all]` delegates to Better Auth; POST also runs the bot guard.
+State:
+- `user` stores email, verified flag, timezone, role, ban flags, and default inference provider; `session` lasts 30 days.
+- `account` stores provider token fields; `verification` stores OTP values and expiry.
+Anchors:
+- `packages/auth/server/auth.ts`, `auth-guard.ts`, `request-otp-rate-limit.ts`, `access-control.ts`
+- `apps/api/app/api/auth/request-otp/route.ts`, `apps/api/app/api/auth/[...all]/route.ts`
+- `packages/db/schema/auth.ts`, `packages/shared/waitlist/server/service.ts`
+Invariants:
+- User creation comes from waitlist/admin provisioning, never public Better Auth signup.
+- OTP request limits are three per minute per IP and three per minute per email.
+- `requireSession` redirects to `/login`; waitlist and Slack gates use Better Auth permissions.
+- Admin role has `waitlist:manage` and `slack:use`; user role does not.
+Failure modes:
+- Missing, pending, confirmed, or unsubscribed waitlist entries are refused before OTP send.
+- Bad JSON/email returns 400, rate limit returns 429, OTP send failure returns 500.
diff --git a/docs/budgets/accounting.md b/docs/budgets/accounting.md
new file mode 100644
index 00000000..221e962f
--- /dev/null
+++ b/docs/budgets/accounting.md
@@ -0,0 +1,25 @@
+# Budget Accounting
+Scope: Spend limits and token usage rows for model work.
+Rules:
+- A budget rule is user-wide when `agent_id` is null and agent-scoped otherwise.
+- Periods are UTC daily, weekly starting Monday, and monthly from day one.
+- Enabled applicable rules are the general rules plus rules where `agent_id = rootAgentId`.
+- A run is blocked when summed spend is `>= limitUsd`.
+Spend:
+- Spend sums `COALESCE(actual_cost_usd, estimated_cost_usd, 0)` from the period start.
+- Agent-scoped spend filters by `root_agent_id`, so sub-agent invocations charge the root agent.
+- Limits are positive USD and stored to six decimal places.
+Usage:
+- `recordTokenUsageStep` records each generation independently and continues after insert failures.
+- Empty usage with no actual cost is skipped.
+- Cost source is `actual`, `estimated`, or `unknown`; pricing and unavailable reasons go to metadata.
+Preflight:
+- Realtime chat persists a text-only refusal and skips sandbox startup, model work, and usage recording.
+- Heartbeat/dreaming finalize completed with a budget message when blocked.
+Anchors:
+- `packages/shared/budgets/server/spend.ts`, `packages/shared/budgets/server/usage.ts`
+- `packages/shared/budgets/server/periods.ts`, `packages/shared/budgets/server/rules.ts`
+- `packages/ai/agent-runtime/workflows/session/steps/budget.ts`
+- Tests: `packages/shared/budgets/server/spend.test.ts`, `packages/shared/budgets/server/usage.test.ts`
+- Tests: `packages/shared/budgets/server/summary.test.ts`
+- Tests: `packages/ai/agent-runtime/server/realtime-chat-runner.test.ts`
diff --git a/docs/budgets/index.md b/docs/budgets/index.md
new file mode 100644
index 00000000..fac07f91
--- /dev/null
+++ b/docs/budgets/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Budgets Index
+
+## Documents
+
+- [Budget Accounting](accounting.md)
+- [Budgets](overview.md)
diff --git a/docs/budgets/overview.md b/docs/budgets/overview.md
new file mode 100644
index 00000000..c0863164
--- /dev/null
+++ b/docs/budgets/overview.md
@@ -0,0 +1,23 @@
+# Budgets
+Scope: User-wide and per-root-agent USD spend limits for model usage.
+Flow:
+- Budget preflight calls `checkBudgetExceeded(userId, rootAgentId)` before model/sandbox work.
+- Applicable rules are enabled rows for the user where scope is general or `agent_id = rootAgentId`.
+- Spend sums from UTC period start, using `actual_cost_usd` when present else `estimated_cost_usd`.
+- Usage recording writes provider, model, source, token split, cost source, pricing snapshot, and metadata.
+State:
+- `budget_rule` stores `daily`, `weekly`, or `monthly` limits with `agent_id = NULL` for general scope.
+- `agent_token_usage` stores user, agent, root agent, source, provider, requested/billed model, tokens, and costs.
+Anchors:
+- `packages/shared/budgets/server/rules.ts`, `spend.ts`, `usage.ts`, `summary.ts`, `periods.ts`
+- `packages/shared/budgets/server/actions.ts`, `errors.ts`, `types.ts`
+- `packages/db/schema/budgets.ts`
+Invariants:
+- Limits must be positive USD and are stored to six decimals.
+- Agent-scoped spend filters by `root_agent_id`, so sub-agent spend is charged to the root agent.
+- One general rule exists per user/period; one agent rule exists per user/agent/period.
+- Server actions require a session and assert agent ownership before writing agent-scoped rules.
+Failure modes:
+- No rules means no block; exceeded spend returns budget info for refusal output.
+- Invalid period or non-positive limit throws; zero-token/no-cost observations are skipped.
+- Missing pricing records `unknown` cost source and preserves unavailable reasons in metadata.
diff --git a/docs/cache-revalidation/cache-map.md b/docs/cache-revalidation/cache-map.md
new file mode 100644
index 00000000..ca6ede89
--- /dev/null
+++ b/docs/cache-revalidation/cache-map.md
@@ -0,0 +1,28 @@
+# Cache Map
+
+Scope: cache tags, cached readers, and mutation invalidators.
+
+Tags:
+- `userAgentsTag(userId)`: agent lists and owner-scoped agent reads.
+- `agentTag(agentId)`: agent detail, memory files, log files, and memory file reads.
+- `userConnectionsTag(userId)`: cached user connection lists.
+- `agentToolsTag(agentId)`: cached tool attachments for an agent.
+- `agentSkillsTag(agentId)`: cached skills for an agent.
+- `conversationListTag(agentId)`: chat sidebar conversation list.
+- `userBudgetTag(userId)`: budget summaries/settings.
+- `userTimezoneTag(userId)`: timezone display and settings state.
+
+Invalidators:
+- Agent create/update/delete calls refresh user and agent tags plus app paths.
+- Tool attach/detach/build calls refresh tool, agent, and user-agent tags.
+- Skill writes refresh skill, agent, and user-agent surfaces.
+- Connections actions and OAuth callbacks refresh user connection tags.
+- Chat actions, realtime runner, title generation, and channel dispatch refresh conversations.
+- Budget and timezone actions refresh their user-scoped tags.
+
+Invariants:
+- Use helpers from `cache-tags.ts`; never inline tag string formats.
+- Most cached readers use `cacheLife('minutes')` plus `cacheTag(...)`.
+
+Anchors: `packages/shared/server/cache-tags.ts`, `packages/shared/server/data.ts`,
+`packages/ai/chat/server/chat.ts`, `packages/shared/*/actions.ts`.
diff --git a/docs/cache-revalidation/index.md b/docs/cache-revalidation/index.md
new file mode 100644
index 00000000..64a26ae3
--- /dev/null
+++ b/docs/cache-revalidation/index.md
@@ -0,0 +1,9 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Cache Revalidation Index
+
+## Documents
+
+- [Cache Map](cache-map.md)
+- [Cache Revalidation](overview.md)
+- [Revalidation Flow](revalidation-flow.md)
diff --git a/docs/cache-revalidation/overview.md b/docs/cache-revalidation/overview.md
new file mode 100644
index 00000000..8f2501c8
--- /dev/null
+++ b/docs/cache-revalidation/overview.md
@@ -0,0 +1,29 @@
+# Cache Revalidation
+
+Scope/boundary: Cache revalidation keeps app-side cached server data current after
+local mutations and API-project mutations.
+
+Flow/state:
+- Shared tag helpers name user, agent, connection, tool, skill, budget, and chat caches.
+- App-local mutations call `revalidateTag(...)` or `updateTag(...)` directly.
+- API-side mutations call `revalidateAppAfter(...)` or `sendAppRevalidation(...)`.
+- Cross-project sends POST JSON to the app `/api/internal/revalidate` route.
+- The app route verifies HMAC, parses payload, then revalidates tags and paths.
+
+Invariants:
+- Use `packages/shared/server/cache-tags.ts`; do not inline cache tag strings.
+- Payload tags are `[tag, 'max' | { expire: 0 }]`; paths must begin with `/`.
+- Empty tag/path payloads are no-ops.
+- Cross-project revalidation requires the app origin from related projects or env.
+- Protected previews need `APP_VERCEL_AUTOMATION_BYPASS_SECRET` on the API app.
+
+Failure modes:
+- Missing `APP_REVALIDATION_SECRET` throws before signing or verification.
+- Bad/missing signature returns 401; bad JSON or payload returns 400.
+- `revalidateAppAfter` logs send failures after the request; direct sends throw.
+
+Anchors: `packages/shared/server/app-revalidation*.ts`,
+`packages/shared/server/cache-tags.ts`,
+`apps/app/app/api/internal/revalidate/route.ts`,
+`packages/shared/server/data.ts`,
+`apps/api/app/api/agents/[agentId]/*`.
diff --git a/docs/cache-revalidation/revalidation-flow.md b/docs/cache-revalidation/revalidation-flow.md
new file mode 100644
index 00000000..8f3e6603
--- /dev/null
+++ b/docs/cache-revalidation/revalidation-flow.md
@@ -0,0 +1,26 @@
+# Revalidation Flow
+
+Scope: how mutations refresh cached app state locally and across projects.
+
+Flow:
+- App-local mutations call `revalidateTag`, `updateTag`, and `revalidatePath` directly.
+- API-project mutations call `revalidateAppAfter(...)` for app-visible cached state.
+- `revalidateAppAfter` schedules `sendAppRevalidation(...)` with `after(...)`.
+- Sender signs JSON with `APP_REVALIDATION_SECRET`.
+- Sender POSTs to app `/api/internal/revalidate`.
+- App route verifies `x-outname-revalidation-signature`.
+- Valid payload revalidates every tag and optional path.
+
+Payload contract:
+- `tags` is required and is a list of `[tag, profile]`.
+- `profile` is `'max'` or `{ expire: 0 }`.
+- `paths` is optional and every path must start with `/`.
+- Empty tag and path payloads are no-ops.
+
+Failure modes:
+- Bad/missing signature returns 401.
+- Bad JSON or invalid payload returns 400.
+- Direct send throws on non-OK; after-send logs failures.
+
+Anchors: `packages/shared/server/app-revalidation*.ts`,
+`apps/app/app/api/internal/revalidate/route.ts`.
diff --git a/docs/channels-slack/channel-contract.md b/docs/channels-slack/channel-contract.md
new file mode 100644
index 00000000..c542aea2
--- /dev/null
+++ b/docs/channels-slack/channel-contract.md
@@ -0,0 +1,26 @@
+# Slack Channel Contract
+Scope: Slack installation, event ingress, routing, and transcript persistence.
+Install:
+- Install and callback require a Better Auth session plus `slack:use`.
+- State is HMAC-signed, expires after 10 minutes, and only accepts app-local return paths.
+- Callback initializes the Chat bundle and wraps OAuth persistence in `withInstallContext({ userId })`.
+- `SlackHybridState` refuses to save installation keys without that owner context.
+Ingress:
+- `/api/channels/slack/events` delegates to the Chat adapter and schedules long work in `after()`.
+- `REDIS_URL` is required for Chat SDK locks, queues, dedupe, subscriptions, and ephemeral state.
+- Empty text/no-attachment messages, missing thread ids, or missing team ids are dropped before routing.
+Routing:
+- `externalScopeId` is Slack team id; channel keys use channel id; DM keys use author id with channel fallback.
+- Sticky `channel_thread_conversations` mappings win before binding lookup.
+- Fan-out is sequential and sorted by installation time, owner id, then agent id.
+- Disabled agents post an error; failed agents do not stop later routes.
+Persistence:
+- User message ids hash channel, scope, external message key, and agent id for idempotency.
+Anchors:
+- `packages/shared/channels/slack/server/bot.ts`, `packages/shared/channels/slack/server/state.ts`
+- `packages/shared/channels/slack/server/incoming-message.ts`
+- `packages/shared/channels/server/routing.ts`, `packages/shared/channels/server/dispatch.ts`
+- `packages/shared/channels/server/backing-state.ts`
+- Tests: `packages/shared/channels/slack/server/incoming-message.test.ts`, `packages/shared/channels/slack/server/state.test.ts`
+- Tests: `packages/shared/channels/slack/server/backing-state.test.ts`
+- Tests: `packages/shared/channels/server/dispatch.test.ts`
diff --git a/docs/channels-slack/index.md b/docs/channels-slack/index.md
new file mode 100644
index 00000000..6ec06034
--- /dev/null
+++ b/docs/channels-slack/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Channels Slack Index
+
+## Documents
+
+- [Slack Channel Contract](channel-contract.md)
+- [Slack Channel](overview.md)
diff --git a/docs/channels-slack/overview.md b/docs/channels-slack/overview.md
new file mode 100644
index 00000000..30105650
--- /dev/null
+++ b/docs/channels-slack/overview.md
@@ -0,0 +1,23 @@
+# Slack Channel
+Scope: Slack install, event ingress, routing, and thread-to-chat persistence for the realtime external channel.
+Flow:
+- Install/callback require a session and `slack:use`; signed state expires after 10 minutes and binds user id.
+- Events route acknowledges within Slack's window and continues processing through `after()`.
+- Mentions, DMs, and subscribed messages normalize to `IncomingChannelTurn`; empty messages are dropped.
+- Routing considers all installs for a team, rechecks access per owner, then fans out sequentially.
+State:
+- `channel_installations` stores encrypted bot tokens by user/team; team metadata stays clear.
+- `agent_channel_bindings` map user/scope/key/kind to an agent; `channel_thread_conversations` stores sticky threads.
+- Redis via `REDIS_URL` stores Chat SDK locks, queues, dedupe, subscriptions, and ephemeral state.
+Anchors:
+- `apps/api/app/api/channels/slack/events/route.ts`, `install/route.ts`, `oauth/callback/route.ts`
+- `packages/shared/channels/slack/server/bot.ts`, `state.ts`, `installations.ts`, `incoming-message.ts`
+- `packages/shared/channels/server/routing.ts`, `dispatch.ts`, `bindings.ts`, `installations.ts`
+Invariants:
+- No Slack install may be saved outside `withInstallContext({ userId })`.
+- Scope is Slack team id; channel key is channel id; DM key is author id with channel fallback.
+- Sticky thread mapping wins before binding lookup; deterministic message ids dedupe per channel/scope/message/agent.
+Failure modes:
+- Missing Slack env, missing `slack:use`, missing/invalid state, or OAuth errors redirect with connection error.
+- Missing `REDIS_URL` throws during Slack Chat SDK state setup.
+- No binding logs a warning and does not run; disabled agents post a channel error.
diff --git a/docs/connections/connector-authoring.md b/docs/connections/connector-authoring.md
new file mode 100644
index 00000000..32d2e350
--- /dev/null
+++ b/docs/connections/connector-authoring.md
@@ -0,0 +1,23 @@
+# Connector Authoring
+Scope: Adding a tool connector under `packages/shared/connections/`.
+Contract:
+- Define API-key connectors with `defineConnector()` and OAuth connectors with `defineOAuth2Connector()`.
+- Connector ids must match `provider.connector`; `providerGroup` must equal the prefix.
+- Broker `allowedHosts` must be exact lowercase hosts; `injectedHeaderNames` must be lowercase.
+- Form schemas should store only authentication fields; per-tool defaults belong in tool config.
+API keys:
+- Validate shape with Zod before persistence.
+- Optional `validate()` should use a cheap provider probe and return safe metadata.
+- Persisted rows are encrypted upserts in `user_connections` with status reset to `active`.
+OAuth:
+- Runtime env must include `KV_REST_API_URL` and `KV_REST_API_TOKEN` when OAuth connectors exist.
+- Start route signs 10-minute state, hashes requested scopes, and stores a signed PKCE cookie.
+- Callback rechecks session user, connector id, scope hash, PKCE, and rejects unexpected granted scopes.
+- Refresh runs under `oauth-refresh:{userId}:{connectorId}` Redis lock.
+Anchors:
+- `packages/shared/connections/registry.ts`, `packages/shared/connections/define-connector.ts`
+- `packages/shared/connections/oauth-state.ts`
+- `apps/api/app/api/connections/oauth/[connectorId]/start/route.ts`
+- `apps/api/app/api/connections/oauth/[connectorId]/callback/route.ts`
+- Tests: `packages/shared/connections/registry.test.ts`, `packages/shared/connections/oauth-state.test.ts`
+- Tests: `packages/shared/connections/runtime/availability.test.ts`, `packages/shared/connections/github.test.ts`
diff --git a/docs/connections/credential-taxonomy.md b/docs/connections/credential-taxonomy.md
new file mode 100644
index 00000000..a6e2ab81
--- /dev/null
+++ b/docs/connections/credential-taxonomy.md
@@ -0,0 +1,23 @@
+# Credential Taxonomy
+Scope: Which secrets exist, where they live, and who may see them.
+Kinds:
+- Better Auth `account` tokens are identity provider fields, not broker connector credentials.
+- API-key connectors store `{ kind: "api_key", values }` in `user_connections.credentials`.
+- OAuth connectors store `{ kind: "oauth2", version: 1, tokenType: "Bearer", accessToken, refreshToken? }`.
+- Slack installs store `{ botToken }` in `channel_installations.credentials`; team metadata stays clear.
+- Inference providers store `{ apiKey }` in `user_inference_credentials.encrypted_credentials`.
+- Waitlist confirmation tokens are SHA-256 hashes, not decryptable credentials.
+Scoping:
+- Tool credentials are keyed by `(user_id, connector_id)` and expose clear status, expiry, metadata, and scopes.
+- Inference credentials are keyed by `(user_id, inference_provider)` with `enabled` or `invalid` status.
+- Slack installs are unique by `(user_id, channel, external_id)` so users can share a workspace safely.
+Security:
+- `encryptCredential` writes AES-GCM `version | iv | tag | ciphertext` using a 32-byte `CONNECTION_ENCRYPTION_KEY`.
+- Tool VMs do not receive raw credentials; brokers inject declared headers outside the VM.
+- OAuth refresh requires Redis single-flight locking; bad decrypt or invalid shape marks the row invalid.
+Anchors:
+- `packages/shared/connections/types.ts`, `packages/shared/connections/crypto.ts`
+- `packages/shared/connections/key-provider.ts`
+- `packages/db/schema/connections.ts`, `packages/db/schema/channels.ts`, `packages/db/schema/inference.ts`
+- `packages/db/schema/waitlist.ts`
+- Tests: `packages/shared/connections/runtime/credential.test.ts`
diff --git a/docs/connections/index.md b/docs/connections/index.md
new file mode 100644
index 00000000..017f2f94
--- /dev/null
+++ b/docs/connections/index.md
@@ -0,0 +1,9 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Connections Index
+
+## Documents
+
+- [Connector Authoring](connector-authoring.md)
+- [Credential Taxonomy](credential-taxonomy.md)
+- [Credentials And Connections](overview.md)
diff --git a/docs/connections/overview.md b/docs/connections/overview.md
new file mode 100644
index 00000000..6960b1ca
--- /dev/null
+++ b/docs/connections/overview.md
@@ -0,0 +1,23 @@
+# Credentials And Connections
+Scope: User-managed tool connector credentials and OAuth/API-key lifecycle; inference provider keys are separate.
+Flow:
+- API-key actions require a session, connector lookup, schema validation, optional provider probe, then encrypted upsert.
+- OAuth start requires a session, OAuth connector, client env, signed 10-minute state, and signed PKCE cookie.
+- OAuth callback requires same session user, connector, requested scope hash, and PKCE verifier before token exchange.
+- Successful callbacks reject unexpected scopes, save best-effort profile metadata, and upsert the connection.
+State:
+- `user_connections` is keyed by `(user_id, connector_id)` with encrypted credentials and clear status/scopes/expiry/metadata.
+- Credential blobs are AES-GCM envelopes using `CONNECTION_ENCRYPTION_KEY`; statuses are `active` or `invalid`.
+Anchors:
+- `packages/shared/connections/registry.ts`, `types.ts`, `crypto.ts`, `oauth-state.ts`
+- `packages/shared/connections/runtime/store.ts`, `credential.ts`, `availability.ts`
+- `apps/api/app/api/connections/oauth/[connectorId]/start/route.ts`, `callback/route.ts`
+- `packages/db/schema/connections.ts`
+Invariants:
+- Connector ids are `provider.connector`; `providerGroup` matches the prefix.
+- Tool code never receives raw credentials; the broker injects auth headers outside the tool VM.
+- Runtime credential access is scoped by user id and connector id; OAuth refresh uses Redis single-flight locking.
+Failure modes:
+- Unknown connector, wrong auth kind, missing env, invalid state/PKCE, or unexpected scopes redirect with connection error.
+- Missing/invalid connections or missing scopes produce reconnect requirements; bad decrypt/shape/permanent refresh marks invalid.
+- Disconnect deletes the row and best-effort revokes OAuth tokens when supported.
diff --git a/docs/data/core-tables.md b/docs/data/core-tables.md
new file mode 100644
index 00000000..1b41bc87
--- /dev/null
+++ b/docs/data/core-tables.md
@@ -0,0 +1,21 @@
+# Core Data
+Scope: Durable Postgres boundary for auth, agents, chats, channels, credentials, inference, budgets, and waitlist.
+Flow:
+- API routes under `apps/api/app/api` validate input/auth and delegate writes to package server helpers.
+- Schema modules define ownership, cascade behavior, uniqueness, and indexes used by routing and budgeting.
+State:
+- Identity and agents: `user`, `session`, `account`, `verification`, `agent`, `agent_events`, `agent_event_message`.
+- Chat/channel: `chat_conversation`, `chat_message`, `channel_installations`, `agent_channel_bindings`, `channel_thread_conversations`.
+- Credentials/spend/acquisition: `user_connections`, `user_inference_credentials`, `budget_rule`, `agent_token_usage`, `waitlist_entries`.
+Anchors:
+- `packages/db/schema/auth.ts`, `agents.ts`, `chat.ts`, `channels.ts`, `connections.ts`
+- `packages/db/schema/inference.ts`, `budgets.ts`, `waitlist.ts`, `skills.ts`, `tools.ts`
+- `apps/api/app/api/auth/*`, `connections/oauth/*`, `channels/slack/*`, `waitlist/*`
+Invariants:
+- User-owned app tables cascade on user delete; waitlist `provisionedUserId` is set null.
+- Channel, connector, and inference credential blobs are encrypted; clear metadata is for routing/UI.
+- Provider and model are stored together on `agent`; credentials are scoped by user plus connector/provider.
+- Event idempotency, active concurrency, channel threads, bindings, and budget scopes have uniqueness constraints.
+Failure modes:
+- Foreign keys cascade/delete dependent state; unique conflicts are handled by upsert or canonical re-read helpers.
+- Server routes/actions must prove session ownership before writing user- or agent-scoped rows.
diff --git a/docs/data/index.md b/docs/data/index.md
new file mode 100644
index 00000000..a355cb61
--- /dev/null
+++ b/docs/data/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Data Index
+
+## Documents
+
+- [Core Data](core-tables.md)
+- [Migrations](migrations.md)
diff --git a/docs/data/migrations.md b/docs/data/migrations.md
new file mode 100644
index 00000000..fc4a5aed
--- /dev/null
+++ b/docs/data/migrations.md
@@ -0,0 +1,19 @@
+# Migrations
+Scope: Drizzle schema history for the remote Neon Postgres database.
+Rules:
+- Schema source is `packages/db/schema/index.ts`; generated SQL lives in `packages/db/drizzle/`.
+- `packages/db/drizzle.config.ts` requires `DATABASE_URL` and normalizes it for `pg`.
+- Runtime `packages/db/index.ts` uses a `pg` pool with `attachDatabasePool`.
+- Use the pooled Neon host containing `-pooler`; no local Postgres is expected.
+Workflow:
+- `pnpm --filter @outname/db db:generate` writes SQL plus `drizzle/meta/_journal.json`.
+- `pnpm --filter @outname/db db:migrate` applies committed migrations.
+- `drizzle-kit push` is for direct sync and needs `--force` or an interactive TTY.
+Migration anchors:
+- `packages/db/drizzle/0011_connector_connections.sql` maps legacy providers to `connector_id`.
+- `packages/db/drizzle/0013_channel_scope_thread_ids.sql` standardizes external ids.
+- `packages/db/drizzle/0016_inference_providers.sql` moves `user.ai_gateway_api_key`.
+- `packages/db/drizzle/0019_auth_user_id_snake_case.sql` idempotently renames auth columns.
+Tests:
+- `packages/db/connection-string.test.ts`
+- `packages/db/schema/auth.test.ts`
diff --git a/docs/dreaming/overview.md b/docs/dreaming/overview.md
new file mode 100644
index 00000000..f3342753
--- /dev/null
+++ b/docs/dreaming/overview.md
@@ -0,0 +1,30 @@
+# Dreaming
+
+Scope: durable reflection mode on heartbeat handler; realtime chat is separate and does not schedule dreaming.
+
+## Flow
+- Scheduler enqueues enabled agents with `dreamingEnabled` once per owner local date.
+- Manual trigger mode `dreaming` requires owner/enabled agent and uses the user's local date.
+- Dispatch calls `handleHeartbeat` mode `dreaming` with `localDate` and reply namespace.
+- Success records dreaming usage, updates `lastDreamingAt`/local date, and persists transcript.
+
+## State
+- Scheduler computes local date from user timezone and key `sched:<agent>:dreaming:daily:<date>:0000`.
+- Previous completion is `lastDreamingAt`; duplicate prevention is `lastDreamingLocalDate`.
+- Prompt asks for logs plus `DREAMS.md`, `GOALS.md`, and `TASKS.md` evidence.
+
+## Invariants
+- Timezone local date, not UTC date, controls once-per-day scheduling.
+- `dreamingEnabled` gates scheduler only; `enabled` is the top-level runnable gate.
+- Budget refusal still marks the local date completed to avoid same-day loops.
+
+## Failure Modes
+- Missing/foreign/disabled manual target returns 401/404/412.
+- Budget exceeded writes refusal transcript and skips model work.
+- Runtime failure follows heartbeat failure path and marks event failed.
+
+## Anchors
+- `apps/api/app/api/agents/[agentId]/trigger/route.ts`
+- `packages/ai/agent-runtime/server/event-scheduler.ts`, `schedule-due.ts`
+- `packages/ai/agent-runtime/workflows/session/handlers/handle-heartbeat.ts`
+- `packages/ai/agent-runtime/workflows/session/steps/db/agent-schedule.ts`
diff --git a/docs/email-templates/components.md b/docs/email-templates/components.md
new file mode 100644
index 00000000..e7041e0a
--- /dev/null
+++ b/docs/email-templates/components.md
@@ -0,0 +1,26 @@
+# Components
+
+Scope: React Email template contracts in `packages/email`.
+
+Layout contract:
+- All templates render through `WaitlistEmailLayout`.
+- Layout owns HTML, Tailwind, preview text, logo, heading, lead, body, footer.
+- CTA renders only when both `ctaHref` and `ctaLabel` exist.
+- CTA emails include a copy-paste URL fallback below the button.
+- Logo URL is a prop; production callers should pass the web-hosted logo URL.
+- Theme uses React Email `pixelBasedPreset` and black/white/red tokens.
+
+Template contract:
+- Each template defines typed props and `PreviewProps`.
+- OTP email keeps expiry, single-use language, and the code near the top.
+- Confirmation email sends users to a confirmation page before final action.
+- Admin signup email reports unconfirmed signup state and attribution fields.
+- Invite emails include `InferenceProviderSetupNote`.
+
+Failure modes:
+- Missing CTA props intentionally omits both button and fallback URL.
+- Preview URLs are examples only and must not be treated as send-time config.
+
+Anchors: `packages/email/components/waitlist-email-layout.tsx`,
+`packages/email/*email.tsx`, `packages/email/waitlist-email-theme.ts`,
+`packages/email/email-preview-urls.ts`.
diff --git a/docs/email-templates/index.md b/docs/email-templates/index.md
new file mode 100644
index 00000000..1ff65753
--- /dev/null
+++ b/docs/email-templates/index.md
@@ -0,0 +1,9 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Email Templates Index
+
+## Documents
+
+- [Components](components.md)
+- [Email Templates](overview.md)
+- [Sending](sending.md)
diff --git a/docs/email-templates/overview.md b/docs/email-templates/overview.md
new file mode 100644
index 00000000..a5affe68
--- /dev/null
+++ b/docs/email-templates/overview.md
@@ -0,0 +1,25 @@
+# Email Templates
+
+Mini-spec for transactional emails in `packages/email` and preview via `apps/email`.
+
+Surface:
+- `apps/email` runs `email dev --dir ../../packages/email --port 3004`.
+- Templates are React Email components exported from `packages/email`.
+- All templates use `WaitlistEmailLayout` and `waitlistEmailTailwind`.
+- Preview-only URLs live in `EMAIL_PREVIEW_URLS`.
+- Production logo URLs should use `/email/outna-logo.png` served by `apps/web`.
+
+Templates:
+- `AuthSignInOtpEmail`: one-time code, expiry, login URL, logo URL.
+- `WaitlistConfirmationEmail`: confirmation URL and confirmation-page safety copy.
+- `WaitlistAdminSignupEmail`: signup details, admin URL, and collapsed UTM data.
+- `WaitlistInviteEmail`: login URL for an account prepared from the waitlist.
+- `ApplicationInviteEmail`: login URL and invite copy from site metadata.
+
+Invariants:
+- A CTA renders only when both `ctaHref` and `ctaLabel` are present.
+- CTA emails always include a copy-paste URL fallback.
+- Every template must define `PreviewProps` for React Email previews.
+- Invite emails include `InferenceProviderSetupNote` for provider-key setup.
+- OTP copy must keep expiry and single-use language visible near the code.
+- Admin signup mail must not imply the address is already confirmed.
diff --git a/docs/email-templates/sending.md b/docs/email-templates/sending.md
new file mode 100644
index 00000000..92f170ae
--- /dev/null
+++ b/docs/email-templates/sending.md
@@ -0,0 +1,25 @@
+# Sending
+
+Scope: server-side email senders that use the React templates.
+
+Flow:
+- Auth OTP sends `AuthSignInOtpEmail` from `packages/auth/server/auth-email.ts`.
+- Waitlist senders live in `packages/shared/waitlist/server/email.ts`.
+- Senders call `sendResendReactEmail` with a React element and idempotency key.
+- Resend payload includes `from`, `replyTo`, `subject`, single recipient, and React body.
+- Logo URLs are built from the marketing web origin plus `/email/outna-logo.png`.
+- Login/admin URLs use the app origin; waitlist confirmation uses the web origin.
+
+Env/state:
+- Auth sender requires `AUTH_FROM_EMAIL` and `AUTH_REPLY_TO`.
+- Waitlist sender requires `WAITLIST_FROM_EMAIL` and `WAITLIST_REPLY_TO`.
+- All Resend sends require `RESEND_API_KEY`.
+- Admin signup notification is skipped when no admin email is configured.
+
+Failure modes:
+- Resend API errors throw with name, optional status code, and message.
+- Waitlist route logs confirmation/admin send failures but still returns generic success.
+
+Anchors: `packages/shared/server/resend.ts`,
+`packages/shared/server/email-logo-url.ts`, `packages/shared/waitlist/server/email.ts`.
+Tests: `packages/shared/server/email-urls.test.ts`.
diff --git a/docs/heartbeat/overview.md b/docs/heartbeat/overview.md
new file mode 100644
index 00000000..65f7322e
--- /dev/null
+++ b/docs/heartbeat/overview.md
@@ -0,0 +1,30 @@
+# Heartbeat
+
+Scope: durable normal autonomous check-in; realtime chat uses the separate chat runner.
+
+## Flow
+- Scheduler enqueues enabled agents with `heartbeatEnabled`; manual trigger requires owner/enabled agent.
+- Scheduled rows share idempotency/concurrency key; manual rows use random idempotency and no concurrency.
+- Due rows enter `handleHeartbeat` mode `normal`, preflight budget, start sandbox, build runtime.
+- Success records heartbeat usage, finalizes, updates `lastHeartbeatAt`, and persists transcript.
+
+## State
+- Due rules are `daily_times` by owner timezone or interval from `lastHeartbeatAt`.
+- Future scheduled rows remain queued; workflow state is held in `agent_events`.
+- Kickoff constrains the agent to one small useful action and log update.
+
+## Invariants
+- Disabled agents are rejected manually and skipped by scheduler.
+- Budget refusal completes event/transcript but does not advance `lastHeartbeatAt`.
+- Scheduled idempotency prevents duplicate rows within a daily slot or interval bucket.
+
+## Failure Modes
+- Missing/foreign/disabled manual target returns 401/404/412.
+- Budget exceeded returns assistant refusal transcript.
+- Model/runtime failure marks run failed; event workflow marks event failed.
+
+## Anchors
+- `apps/api/app/api/agents/[agentId]/trigger/route.ts`
+- `packages/ai/agent-runtime/server/event-scheduler.ts`
+- `packages/ai/agent-runtime/workflows/session/handlers/handle-heartbeat.ts`
+- `packages/ai/agent-runtime/workflows/session/steps/db/agent-schedule.ts`
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..f76d96e7
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,15 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Documentation Index
+
+- [ADR](adr/index.md) · [Agent Chat](agent-chat/index.md) · [Agent Creation Chat](agent-creation-chat/index.md)
+- [Agent Edit Chat](agent-edit-chat/index.md) · [Agent Events](agent-events/index.md) · [Agent Management](agent-management/index.md)
+- [Agent Memory](agent-memory/index.md) · [Agent Skills](agent-skills/index.md) · [Auth Account](auth-account/index.md)
+- [Budgets](budgets/index.md) · [Cache Revalidation](cache-revalidation/index.md) · [Channels Slack](channels-slack/index.md)
+- [Connections](connections/index.md) · [Data](data/index.md) · [Dreaming](dreaming/overview.md)
+- [Email Templates](email-templates/index.md) · [Heartbeat](heartbeat/overview.md) · [Inference](inference/index.md)
+- [Launch Video](launch-video/index.md) · [Marketing Site](marketing-site/index.md) · [Platform](platform/index.md)
+- [Realtime Turns](realtime-turns/index.md) · [Runtime Cache](runtime-cache/index.md) · [Scheduler](scheduler/index.md)
+- [Security Edge](security-edge/index.md) · [Sub Agents](sub-agents/index.md) · [Tool Sandboxes](tool-sandboxes/index.md)
+- [Tools](tools/index.md) · [UI System](ui-system/index.md) · [Waitlist](waitlist/index.md)
+- [Workflow Runtime](workflow-runtime/index.md)
diff --git a/docs/inference/index.md b/docs/inference/index.md
new file mode 100644
index 00000000..57a77fb3
--- /dev/null
+++ b/docs/inference/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Inference Index
+
+## Documents
+
+- [Provider Authoring](provider-authoring.md)
+- [Inference Providers](providers.md)
diff --git a/docs/inference/provider-authoring.md b/docs/inference/provider-authoring.md
new file mode 100644
index 00000000..6209e051
--- /dev/null
+++ b/docs/inference/provider-authoring.md
@@ -0,0 +1,21 @@
+# Provider Authoring
+Scope: Adding or changing inference providers and model catalogs.
+Provider registry:
+- Add provider ids to `inferenceProviderValues` and `PROVIDER_DEFINITIONS` together.
+- `createLanguageModel` must use the user's saved key; there is no server fallback key.
+- Optional verification should use non-billable endpoints; LLM Gateway currently skips verification.
+- Provider and model ids must be stored together because model ids are provider-scoped.
+Model catalogs:
+- Catalogs fetch Vercel AI Gateway, LLM Gateway, and OpenRouter live endpoints with one-hour revalidation.
+- Vercel keeps `type: language` models tagged `tool-use`.
+- OpenRouter keeps models with `supported_parameters` including `tools` and excludes `openrouter/*`.
+- LLM Gateway keeps models where at least one provider advertises `tools: true`.
+- Empty or failed live catalogs fall back; fallback source treats selected model ids as valid.
+Cost accounting:
+- OpenRouter and LLM Gateway actual costs come from documented response usage fields.
+- Vercel AI Gateway actual cost uses generation lookup with delays `0ms`, `1000ms`, `3000ms` and a `2000ms` timeout.
+Anchors:
+- `packages/shared/server/inference-provider-registry.ts`, `packages/shared/server/inference-models.ts`
+- `packages/shared/server/inference-credentials.ts`, `packages/shared/server/inference-actual-costs.ts`
+- Tests: `packages/shared/server/inference-providers.test.ts`, `packages/shared/server/inference-models.test.ts`
+- Tests: `packages/shared/server/inference-actual-costs.test.ts`
diff --git a/docs/inference/providers.md b/docs/inference/providers.md
new file mode 100644
index 00000000..4cad3cde
--- /dev/null
+++ b/docs/inference/providers.md
@@ -0,0 +1,23 @@
+# Inference Providers
+Scope: User-scoped inference credentials, provider/model selection, model catalogs, and actual cost lookup.
+Flow:
+- Settings trim and verify API keys when a non-billable endpoint exists, then encrypt `{ apiKey }`.
+- Runtime reads an enabled user credential from Redis cache or Postgres, decrypts it, and creates the provider model.
+- Model catalogs fetch live tool-capable models, cache for one hour, and fall back on errors.
+- Vercel actual cost lookup retries generation lookup at 0, 1, and 3 seconds with a 2-second timeout.
+State:
+- Providers are `vercel-ai-gateway`, `llm-gateway`, and `openrouter`.
+- `user_inference_credentials` is keyed by `(user_id, inference_provider)` with encrypted credentials and status.
+- `user.default_inference_provider`, `agent.inference_provider`, and `agent.model` persist provider-scoped selection.
+Anchors:
+- `packages/shared/server/inference-credentials.ts`, `inference-language-model.ts`, `inference-models.ts`
+- `packages/shared/server/inference-provider-registry.ts`, `inference-provider-verify.ts`, `inference-actual-costs.ts`
+- `packages/db/schema/inference.ts`, `packages/db/schema/agents.ts`, `packages/auth/settings/actions.ts`
+Invariants:
+- Provider and model must be persisted together; model ids are not globally meaningful.
+- There is no server fallback key; missing or non-enabled credentials throw `MissingInferenceCredentialError`.
+- Setting a default provider requires an enabled credential; first saved key becomes default if none exists.
+Failure modes:
+- Verification failure returns a form error before persistence.
+- Clearing the default key switches to the sole remaining enabled provider or clears the default.
+- Live catalog failure uses fallback; fallback catalogs allow any selected model id.
diff --git a/docs/launch-video/index.md b/docs/launch-video/index.md
new file mode 100644
index 00000000..2901db85
--- /dev/null
+++ b/docs/launch-video/index.md
@@ -0,0 +1,9 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Launch Video Index
+
+## Documents
+
+- [Manifest](manifest.md)
+- [Launch Video](overview.md)
+- [Rendering](rendering.md)
diff --git a/docs/launch-video/manifest.md b/docs/launch-video/manifest.md
new file mode 100644
index 00000000..fa61e709
--- /dev/null
+++ b/docs/launch-video/manifest.md
@@ -0,0 +1,25 @@
+# Manifest
+
+Scope: launch video metadata and composition generation.
+
+Manifest contract:
+- `launchVideoManifest` is the source of slugs, titles, descriptions, and variants.
+- Aspects are `16x9`, `4x5`, and `1x1`.
+- Dimensions are 1920x1080, 1080x1350, and 1080x1080.
+- Durations are 540, 600, or 780 frames at 30 FPS.
+- Variant IDs are `${slug}-${aspect}`.
+- MP4 and still paths live under `packages/shared/content/outname-launch/assets`.
+- `platformUsage` is `x`, `linkedin`, or `cross-post`.
+- `linkedPosts` points to launch social markdown that references rendered assets.
+
+Implementation contract:
+- `RemotionRoot` creates one `Composition` per manifest variant.
+- `LaunchVideo` must have a branch for every manifest slug.
+- Static assets resolve from the Remotion public dir, currently email static assets.
+
+Failure modes:
+- A manifest slug without a `LaunchVideo` branch falls through to generic story logic.
+- Changing output paths can break social post frontmatter references.
+
+Anchors: `packages/shared/content/outname-launch/assets/video-manifest.ts`,
+`apps/video/remotion/root.tsx`, `apps/video/remotion/launch-videos.tsx`.
diff --git a/docs/launch-video/overview.md b/docs/launch-video/overview.md
new file mode 100644
index 00000000..f0d5c97f
--- /dev/null
+++ b/docs/launch-video/overview.md
@@ -0,0 +1,29 @@
+# Launch Video
+
+Mini-spec for Remotion launch videos in `apps/video`.
+
+Surface:
+- `apps/video` runs Remotion Studio on port 3005 from `remotion/index.ts`.
+- `RemotionRoot` creates one composition per manifest variant at 30 FPS.
+- `LaunchVideo` dispatches by manifest slug and aspect into handcrafted scenes.
+- Primitives fix the visual system: black/white panels and `#ff3000` signal tags.
+- Remotion public assets are served from `packages/email/static`.
+
+Manifest:
+- Aspects are `16x9` 1920x1080, `4x5` 1080x1350, and `1x1` 1080x1080.
+- Durations are 540, 600, or 780 frames for 18s, 20s, or 26s videos.
+- Each asset records title, description, linked posts, duration, slug, variants.
+- Variant MP4s/stills write under `packages/shared/content/outname-launch/assets`.
+- `platformUsage` is `x`, `linkedin`, or `cross-post`.
+
+Flows:
+- `pnpm video:studio` previews compositions.
+- `pnpm video:render:launch` renders every manifest variant.
+- `pnpm video:still:launch` writes frame 450 stills for every variant.
+- Social launch markdown references rendered asset paths and waitlist CTA URLs.
+
+Invariants:
+- Add or remove launch videos in `video-manifest.ts`; root generation follows it.
+- A manifest slug needs matching metadata and a `LaunchVideo` branch.
+- Renderer creates parent directories and fails fast on non-zero Remotion exits.
+- Keep asset paths stable because social post frontmatter points at them.
diff --git a/docs/launch-video/rendering.md b/docs/launch-video/rendering.md
new file mode 100644
index 00000000..8ea3a832
--- /dev/null
+++ b/docs/launch-video/rendering.md
@@ -0,0 +1,25 @@
+# Rendering
+
+Scope: local preview and asset rendering for `apps/video`.
+
+Commands:
+- `pnpm video:studio` runs Remotion Studio through the video workspace.
+- `pnpm video:render:launch` renders every manifest variant to MP4.
+- `pnpm video:still:launch` renders stills for every manifest variant.
+- Direct workspace scripts are `render:launch` and `still:launch`.
+
+Renderer contract:
+- Entry point is `remotion/index.ts`.
+- Still frame is fixed at frame `450`.
+- The script creates output directories before invoking Remotion.
+- Render and still commands pass `--overwrite`.
+- Non-zero Remotion exit status throws and stops the script.
+- Remotion config enables Tailwind and aliases shared packages.
+- Public assets come from `../../packages/email/static`.
+
+Invariants:
+- Keep manifest output paths repo-root relative.
+- Keep logo/static files available to both email previews and video renders.
+
+Anchors: `apps/video/package.json`, `apps/video/scripts/render-launch-videos.ts`,
+`apps/video/remotion.config.ts`, `apps/video/remotion/index.ts`.
diff --git a/docs/marketing-site/content.md b/docs/marketing-site/content.md
new file mode 100644
index 00000000..a1ba64ef
--- /dev/null
+++ b/docs/marketing-site/content.md
@@ -0,0 +1,24 @@
+# Content
+
+Scope: shared marketing copy, blog metadata, and landing page composition.
+
+Landing:
+- `LandingHomePage` composes nav, hero demo, chat showcase, workbench, closer, footer.
+- `waitlistEnabled` controls public waitlist CTAs in nav and closer.
+- `useReducedMotion()` disables motion-heavy landing behavior for users who opt out.
+- Marketing modules read demo data from `packages/shared/marketing/data`.
+
+Blog:
+- `posts` is the canonical list of slug, title, date, excerpt, and tags.
+- `getAllPosts()` sorts newest first by date.
+- `getRelatedPosts()` scores posts by shared lowercase tags, then newer date.
+- SEO metadata, JSON-LD, reading time, and breadcrumbs derive from post data.
+- MDX bodies live under `packages/shared/content/blog/posts`.
+
+Invariants:
+- Add a blog post by updating `posts.ts` and adding matching `<slug>.mdx`.
+- Keep waitlist attribution params flowing through links and the waitlist form.
+- Keep product claims in shared content/data, not hard-coded in route wrappers.
+
+Anchors: `packages/shared/marketing/components/landing-home-page.tsx`,
+`packages/shared/content/blog/posts.ts`, `packages/shared/content/blog/seo.ts`.
diff --git a/docs/marketing-site/index.md b/docs/marketing-site/index.md
new file mode 100644
index 00000000..627843bd
--- /dev/null
+++ b/docs/marketing-site/index.md
@@ -0,0 +1,9 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Marketing Site Index
+
+## Documents
+
+- [Content](content.md)
+- [Marketing Site](overview.md)
+- [Routing](routing.md)
diff --git a/docs/marketing-site/overview.md b/docs/marketing-site/overview.md
new file mode 100644
index 00000000..cbaf84ad
--- /dev/null
+++ b/docs/marketing-site/overview.md
@@ -0,0 +1,27 @@
+# Marketing Site
+
+Mini-spec for the public website in `apps/web`.
+
+Surface:
+- Home renders `LandingHomePage` with shared waitlist config.
+- Root layout owns metadata, fonts, tooltips, toasts, and production analytics.
+- Navigation links to Blog, Login, GitHub, and conditionally Waitlist.
+- Waitlist preserves `source` and UTM params into `WaitlistSignupForm`.
+- Blog index/post pages read static data from `packages/shared/content/blog`.
+
+Flow:
+- `/` delegates composition to `packages/shared/marketing`.
+- `/blog` calls `getAllPosts()`, renders JSON-LD, and lists posts.
+- `/blog/[slug]` uses `posts` for static params and imports matching MDX.
+- Missing blog slugs return `notFound()`.
+- `sitemap.ts` adds `/waitlist` only when `WAITLIST_PUBLIC_ENABLED === 'true'`.
+
+States:
+- `waitlistEnabled=false`: hide waitlist CTA/nav/sitemap entry, keep login CTAs.
+- `posts.length=0`: show the empty blog state.
+- Reduced motion disables landing text-loop/reveal triggers.
+
+Invariants:
+- A blog post needs metadata in `posts.ts` and MDX at `posts/<slug>.mdx`.
+- Blog SEO, related posts, JSON-LD, reading time, and cards derive from post data.
+- Marketing claims/data live in shared packages; `apps/web` stays routing glue.
diff --git a/docs/marketing-site/routing.md b/docs/marketing-site/routing.md
new file mode 100644
index 00000000..a85b4825
--- /dev/null
+++ b/docs/marketing-site/routing.md
@@ -0,0 +1,25 @@
+# Routing
+
+Scope: public web routes in `apps/web`.
+
+Routes:
+- `/` renders `LandingHomePage` with `isWaitlistPublicEnabled()`.
+- `/waitlist` reads `source` and UTM search params and passes them to the form.
+- `/waitlist/confirm` is the email confirmation landing page.
+- `/blog` renders `getAllPosts()` plus blog JSON-LD.
+- `/blog/[slug]` uses `posts` for static params and loads matching MDX.
+- `/privacy`, `/terms`, and `/support` use shared legal/site metadata.
+- OpenGraph and Twitter image routes exist for root, blog index, and blog posts.
+
+Contracts:
+- Missing blog slug returns `notFound()`.
+- Waitlist sitemap entry exists only when `WAITLIST_PUBLIC_ENABLED=true`.
+- Web proxy returns 404 for `/waitlist/*` when public waitlist is disabled.
+- Blog dynamic MDX import is intentional and exempted in web React Doctor config.
+
+Failure modes:
+- A post in `posts.ts` without MDX fails at page import time.
+- MDX without a `posts.ts` entry is unreachable by generated static params.
+
+Anchors: `apps/web/app/*`, `apps/web/proxy.ts`, `apps/web/app/sitemap.ts`,
+`apps/web/doctor.config.json`.
diff --git a/docs/platform/env-matrix.md b/docs/platform/env-matrix.md
new file mode 100644
index 00000000..98e708a5
--- /dev/null
+++ b/docs/platform/env-matrix.md
@@ -0,0 +1,29 @@
+# Environment Matrix
+
+Scope: runtime and build-time env wiring across the app, API, web, email, and
+video workspaces.
+
+Matrix:
+- Root requires Node `>=24`, pnpm `>=10`, and Turborepo scripts from `package.json`.
+- Local origins are app `:3000`, API `:3001`, web `:3002`.
+- Email preview runs `email dev --dir ../../packages/email --port 3004`.
+- Video Studio runs `remotion studio remotion/index.ts --port=3005`.
+- `createOutnameNextConfig` injects `NEXT_PUBLIC_API_BASE_URL`,
+  `NEXT_PUBLIC_APP_URL`, and `NEXT_PUBLIC_WEB_URL` per role.
+- App/web roles rewrite `/api/:path*` to the API origin; API role has no rewrite.
+- Preview origins prefer `VERCEL_URL`; production prefers
+  `VERCEL_PROJECT_PRODUCTION_URL`, then `VERCEL_URL`.
+- Cross-project app cache refresh needs `APP_REVALIDATION_SECRET`.
+- Protected Vercel previews may also need `APP_VERCEL_AUTOMATION_BYPASS_SECRET`.
+- Email sending needs `RESEND_API_KEY` plus auth or waitlist from/reply-to envs.
+- `WAITLIST_PUBLIC_ENABLED=true` exposes public waitlist web/API behavior.
+- `BOTID_ENABLED=true` turns route-level BotID checks on.
+
+Failure modes:
+- Missing revalidation secret, Resend key, or email from/reply-to env throws.
+- Missing related project URLs fall back to local defaults when guessing is unsafe.
+
+Anchors: `package.json`, `packages/shared/next/create-outname-next-config.ts`,
+`packages/shared/vercel-related-projects.ts`, `packages/shared/server/email-urls.ts`.
+Tests: `packages/shared/next/create-outname-next-config.test.ts`,
+`packages/shared/vercel-related-projects.test.ts`, `packages/shared/server/email-urls.test.ts`.
diff --git a/docs/platform/index.md b/docs/platform/index.md
new file mode 100644
index 00000000..baf7cbde
--- /dev/null
+++ b/docs/platform/index.md
@@ -0,0 +1,10 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Platform Index
+
+## Documents
+
+- [Environment Matrix](env-matrix.md)
+- [Platform Routing](routing.md)
+- [Test Matrix](test-matrix.md)
+- [Platform Workspaces](workspaces.md)
diff --git a/docs/platform/routing.md b/docs/platform/routing.md
new file mode 100644
index 00000000..7e9cbe6a
--- /dev/null
+++ b/docs/platform/routing.md
@@ -0,0 +1,26 @@
+# Platform Routing
+
+Scope: package boundaries and request routing between deployed workspaces.
+
+Surfaces:
+- `apps/web` is public marketing/blog/waitlist on port 3002.
+- `apps/app` is authenticated product UI on port 3000.
+- `apps/api` owns product API routes on port 3001.
+- `apps/email` previews React Email templates only.
+- `apps/video` previews and renders Remotion launch assets only.
+
+Routing contracts:
+- App and web Next configs use shared API rewrites for `/api/:path*`.
+- API Next config is the upstream target and does not rewrite `/api`.
+- App root redirects to `/dashboard`; app proxy guards protected product routes.
+- Web proxy only gates `/waitlist/:path*`; blog/legal/support are public.
+- API route files live under `apps/api/app/api`, except app internal revalidation.
+- `apps/app/app/api/internal/revalidate` is app-only and HMAC protected.
+
+Failure modes:
+- Related-project misses use local origins, so prod links must be configured.
+- Rewrites do not replace route-level auth, CORS, BotID, or payload validation.
+
+Anchors: `apps/*/next.config.ts`, `apps/*/proxy.ts`,
+`packages/shared/next/create-outname-next-config.ts`,
+`apps/api/app/api`, `apps/app/app/api/internal/revalidate/route.ts`.
diff --git a/docs/platform/test-matrix.md b/docs/platform/test-matrix.md
new file mode 100644
index 00000000..f9300f86
--- /dev/null
+++ b/docs/platform/test-matrix.md
@@ -0,0 +1,27 @@
+# Test Matrix
+
+Scope: verification commands for platform and product-surface changes.
+
+Commands:
+- `pnpm docs:check` validates generated docs indexes and 30-line source docs.
+- `pnpm verify` runs docs check plus Turbo build, typecheck, lint, react-doctor.
+- `pnpm test` runs Vitest and imports database-backed modules; set `DATABASE_URL`.
+- `pnpm test:typecheck` checks the Vitest TypeScript project.
+- Workspace `typecheck`, `lint`, and `react-doctor` run through Turbo filters.
+- `pnpm dev:web`, `dev:app`, `dev:api`, `dev:email`, `dev:video` run local surfaces.
+
+Focused anchors:
+- Next config and related project URL behavior: shared config tests.
+- Email link resolution: `packages/shared/server/email-urls.test.ts`.
+- Revalidation side effects: channel dispatch, chat title, and realtime runner tests.
+- API stream/transcript contract: route tests under `apps/api/app/api/agents`.
+- UI shell and auth changes need manual browser verification.
+- Marketing, email preview, and launch video have no full product test suite.
+
+Invariants:
+- Generated docs indexes are intentionally not edited in this slice.
+- Use line counts for new non-index docs when skipping `docs:check`.
+- Browser verification is required for UI/auth behavior after implementation edits.
+
+Anchors: `package.json`, `vitest*.ts`, `apps/*/doctor.config.json`,
+`packages/*/doctor.config.json`, `AGENTS.md`.
diff --git a/docs/platform/workspaces.md b/docs/platform/workspaces.md
new file mode 100644
index 00000000..8ac47d0b
--- /dev/null
+++ b/docs/platform/workspaces.md
@@ -0,0 +1,27 @@
+# Platform Workspaces
+
+Mini-spec for repo workspaces that ship or preview product surfaces.
+
+Evidence: `package.json`, `apps/web`, `apps/email`, `apps/video`,
+`packages/email`, `packages/shared/marketing`, `packages/shared/content`.
+
+Responsibilities:
+- Root `outname` is a private Turborepo on `pnpm@10.33.0`, Node `>=24`.
+- `apps/web` is the public Next app on port 3002.
+- `apps/email` is the React Email preview app on port 3004.
+- `apps/video` is the Remotion Studio workspace on port 3005.
+- Shared marketing UI/content lives in `packages/shared/marketing`.
+- Blog and launch content live in `packages/shared/content`.
+- Transactional email source lives in `packages/email`, not the preview app.
+
+Flows:
+- `pnpm dev:web`, `pnpm dev:email`, and `pnpm dev:video` use Turbo filters.
+- `pnpm email` aliases email preview; `pnpm video:studio` aliases Remotion.
+- `pnpm video:render:launch` and `pnpm video:still:launch` render launch assets.
+- `pnpm verify` runs `docs:check` before build/typecheck/lint/react-doctor.
+
+Invariants:
+- Do not hand-edit generated docs indexes; run `pnpm docs:index` when needed.
+- Feature docs stay under `docs/<feature>/`.
+- Every non-index markdown file under `docs/` must be 30 lines or fewer.
+- Keep public site, email preview, and video render workspaces decoupled.
diff --git a/docs/realtime-turns/edge-cases.md b/docs/realtime-turns/edge-cases.md
new file mode 100644
index 00000000..34e817b8
--- /dev/null
+++ b/docs/realtime-turns/edge-cases.md
@@ -0,0 +1,12 @@
+# Realtime Turns Edge Cases
+
+Failure modes:
+- Missing agent throws `runRealtimeChatTurn: agent ... not found`.
+- Owner mismatch throws before budget or sandbox work.
+- Budget exceeded writes a persisted refusal and optionally posts the same text to a channel.
+- UI `finishReason: error` logs and drops the assistant turn; aborted turns are also dropped.
+- Usage-recording failures are caught inside the scheduled background task.
+- Title-generation failures are caught and logged after the stream finishes.
+- Missing system sandbox during cleanup/file-cache refresh is downgraded to a warning in cleanup code.
+
+Source anchors: `packages/ai/agent-runtime/server/realtime-chat-runner.ts`, `packages/ai/agent-runtime/server/realtime-cleanup.ts`, `packages/ai/agent-runtime/server/agent-sandbox.ts`.
diff --git a/docs/realtime-turns/flow.md b/docs/realtime-turns/flow.md
new file mode 100644
index 00000000..1307290e
--- /dev/null
+++ b/docs/realtime-turns/flow.md
@@ -0,0 +1,11 @@
+# Realtime Turns Flow
+
+Product behavior:
+- In-app chat calls realtime with `persistMode: ui-message-full`; channels call it with `persistMode: text-only`.
+- Inputs include agent, user, conversation, run id, source, abort signal, optional external thread ids, and a delivery adapter.
+- Preparation loads the agent, checks ownership, preflights budget, starts the system sandbox, then builds a chat runtime spec.
+- UI mode creates an AI SDK UI-message stream and writes status/tool chunks to the client.
+- Text-only mode streams model chunks through the channel sink and separately accumulates visible text.
+- On finish, output persistence, list revalidation, usage recording, cleanup, and title generation run through runner policies.
+
+Source anchors: `apps/api/app/api/agents/[agentId]/chat/route.ts`, `packages/shared/channels/server/dispatch.ts`, `packages/ai/agent-runtime/server/realtime-chat-runner.ts`, `packages/ai/agent-runtime/server/realtime-agent-runtime.ts`.
diff --git a/docs/realtime-turns/index.md b/docs/realtime-turns/index.md
new file mode 100644
index 00000000..1f74ca06
--- /dev/null
+++ b/docs/realtime-turns/index.md
@@ -0,0 +1,13 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Realtime Turns Index
+
+## Documents
+
+- [Realtime Turns Edge Cases](edge-cases.md)
+- [Realtime Turns Flow](flow.md)
+- [Realtime Turns Invariants](invariants.md)
+- [Realtime Turns](overview.md)
+- [Realtime Runtime Spec](runtime-spec.md)
+- [Realtime Turns State](state.md)
+- [Realtime Turns Tests](tests.md)
diff --git a/docs/realtime-turns/invariants.md b/docs/realtime-turns/invariants.md
new file mode 100644
index 00000000..dcaa7e68
--- /dev/null
+++ b/docs/realtime-turns/invariants.md
@@ -0,0 +1,12 @@
+# Realtime Turns Invariants
+
+Rules enforced in source:
+- Ownership is checked before budget checks, sandbox startup, or runtime spec composition.
+- Budget refusal skips sandbox startup, runtime build, usage recording, and title generation.
+- `startupSystemSandbox` runs before `buildAgentRuntimeSpec`.
+- Realtime runtime uses the provider-scoped user model and `stopWhenFromSpec`.
+- UI assistant partials are persisted only when not aborted and not finished with `error`.
+- Text-only delivery requires `postAgentStream`; if posting fails, partial accumulated text is not persisted.
+- Cleanup runs in `finally` for both UI and text-only modes.
+
+Source anchors: `packages/ai/agent-runtime/server/realtime-chat-runner.ts`, `packages/ai/agent-runtime/server/realtime-agent-runtime.ts`, `packages/ai/agent-runtime/server/runtime-spec.ts`, `packages/ai/agent-runtime/server/realtime-cleanup.ts`.
diff --git a/docs/realtime-turns/overview.md b/docs/realtime-turns/overview.md
new file mode 100644
index 00000000..94760c12
--- /dev/null
+++ b/docs/realtime-turns/overview.md
@@ -0,0 +1,13 @@
+# Realtime Turns
+
+Scope: chat-style agent turns used by in-app chat and channels.
+
+Read this folder as:
+- [Flow](flow.md): UI-mode and text-only turn sequence.
+- [Runtime spec](runtime-spec.md): spec inputs, loaded plans, prompt composition, and runtime consumers.
+- [State](state.md): run ids, metadata, persisted assistant messages, refusals, and usage observations.
+- [Invariants](invariants.md): ownership ordering, budget refusal, sandbox-before-spec, persistence policy, and cleanup.
+- [Edge cases](edge-cases.md): missing agents, owner mismatch, refused budgets, dropped partials, and background failures.
+- [Tests](tests.md): runner persistence, ordering, refusal, ownership, and stream-failure coverage.
+
+Primary source anchors: `packages/ai/agent-runtime/server/realtime-chat-runner.ts`, `packages/ai/agent-runtime/server/runtime-spec.ts`, `packages/ai/agent-runtime/server/realtime-agent-runtime.ts`.
diff --git a/docs/realtime-turns/runtime-spec.md b/docs/realtime-turns/runtime-spec.md
new file mode 100644
index 00000000..f668158a
--- /dev/null
+++ b/docs/realtime-turns/runtime-spec.md
@@ -0,0 +1,15 @@
+# Realtime Runtime Spec
+
+Implementation contract:
+- `buildAgentRuntimeSpec` takes `agentId`, `eventKind`, optional `callStack`, `depth`, `nowIso`, and `runId`.
+- It loads the agent row first; missing rows throw `buildAgentRuntimeSpec: agent ... not found`.
+- Tool plan resolution reads `agentTools`, partitions maintainer/sub-agent rows, collects reconnects, and filters tools that require reconnect.
+- Skill plan resolution reads `sandboxSkillsId`; sandbox discovery failures warn and return an empty skill list.
+- Prompt composition reads the system sandbox, inlines eager bootstrap files, tracked files, reconnects, skill section, and platform invariants.
+- Chat event prompts add a note that heartbeat/dreaming routines are inactive unless the user asks for them.
+- The returned spec is JSON-serializable and carries provider/model, step limit, prompt, tool plan, skill plan, user id, and call stack.
+- `buildRealtimeAgentRuntime` turns the spec into a `ToolLoopAgent` using `stopWhenFromSpec` and the user's provider-scoped model.
+
+Source anchors: `packages/ai/agent-runtime/server/runtime-spec.ts`, `packages/ai/agent-runtime/workflows/session/runtime-spec-types.ts`, `packages/ai/agent-runtime/workflows/session/compose-system-prompt.ts`, `packages/ai/agent-runtime/workflows/session/steps/resolve-tool-plan.ts`, `packages/ai/agent-runtime/workflows/session/steps/resolve-skill-plan.ts`, `packages/ai/agent-runtime/server/realtime-agent-runtime.ts`.
+
+Test anchors: `packages/ai/agent-runtime/server/runtime-spec.test.ts`.
diff --git a/docs/realtime-turns/state.md b/docs/realtime-turns/state.md
new file mode 100644
index 00000000..0dbaf104
--- /dev/null
+++ b/docs/realtime-turns/state.md
@@ -0,0 +1,11 @@
+# Realtime Turns State
+
+State model:
+- `runId` is threaded through tool runtime context, assistant metadata, budget refusal ids, and usage logs.
+- Runtime spec carries agent name, provider/model, user id, step limit, system prompt, skill plan, and tool plan.
+- System sandbox and file cache must exist before composing runtime tools.
+- UI mode persists full assistant `UIMessage.parts`; text-only mode persists one assistant text part with source/run metadata.
+- Budget refusal persists a synthetic assistant message id `budget_refusal_${runId}`.
+- Usage recording is scheduled from model finish events with `sourceType: chat` and `sourceId: conversationId`.
+
+Source anchors: `packages/ai/agent-runtime/server/realtime-chat-runner.ts`, `packages/ai/agent-runtime/server/runtime-spec.ts`, `packages/ai/agent-runtime/server/realtime-agent-runtime.ts`, `packages/db/schema/chat.ts`.
diff --git a/docs/realtime-turns/tests.md b/docs/realtime-turns/tests.md
new file mode 100644
index 00000000..f74ed6b4
--- /dev/null
+++ b/docs/realtime-turns/tests.md
@@ -0,0 +1,12 @@
+# Realtime Turns Tests
+
+Covered:
+- `tapFullStream` yields original chunks once and accumulates visible text deltas.
+- UI mode persists normal and length-finished assistant messages, then schedules title generation.
+- Aborted and errored UI assistant partials are dropped.
+- Budget refusal avoids model startup, usage recording, and title generation.
+- Ownership is validated before budget and sandbox startup; missing agents have a distinct error.
+- System sandbox startup happens before runtime spec composition.
+- Text-only mode persists accumulated text with run/source metadata and does not persist partial text when channel posting fails.
+
+Test anchors: `packages/ai/agent-runtime/server/realtime-chat-runner.test.ts`.
diff --git a/docs/runtime-cache/index.md b/docs/runtime-cache/index.md
new file mode 100644
index 00000000..a7356a8a
--- /dev/null
+++ b/docs/runtime-cache/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Runtime Cache Index
+
+## Documents
+
+- [Runtime Cache](overview.md)
+- [Redis Requirements](redis-requirements.md)
diff --git a/docs/runtime-cache/overview.md b/docs/runtime-cache/overview.md
new file mode 100644
index 00000000..bf8f68aa
--- /dev/null
+++ b/docs/runtime-cache/overview.md
@@ -0,0 +1,30 @@
+# Runtime Cache
+
+Scope/boundary: Runtime cache is optional Upstash Redis for hot reads,
+single-flight locks, and transient runtime coordination; databases/sandboxes stay canonical.
+
+Flow/state:
+- `getUpstashRedis()` memoizes a Redis REST client from `KV_REST_API_URL` and token.
+- Missing KV env returns `null`; callers choose fail-open, no-op, or fail-closed.
+- Agent memory file cache stores per-agent path indexes and encoded path records.
+- Inference credential cache stores encrypted blobs by user/provider.
+- Locks use `SET nx ex` with a random token and delete only if the token still matches.
+
+Invariants:
+- The helper should not throw just because Redis is unconfigured.
+- File and inference caches are acceleration only; sandbox and Postgres are sources of truth.
+- OAuth token refresh locking requires Redis and fails closed when unavailable.
+- Lock users must choose TTLs and tolerate contention.
+
+Failure modes:
+- No Redis means empty/no-op file and inference caches.
+- Generic `withRedisLock` returns `null` on contention and runs without Redis when absent.
+- OAuth refresh throws `Redis is required for OAuth token refresh locking.`
+- Redis read/write errors are caller-owned; the helper only constructs the client.
+
+Anchors: `packages/shared/server/upstash-redis.ts`,
+`packages/ai/agent-runtime/server/file-cache.ts`,
+`packages/ai/agent-runtime/server/redis-lock.ts`,
+`packages/shared/server/inference-credentials.ts`,
+`packages/shared/connections/runtime/credential.ts`,
+`apps/api/app/api/cron/liveness/route.ts`.
diff --git a/docs/runtime-cache/redis-requirements.md b/docs/runtime-cache/redis-requirements.md
new file mode 100644
index 00000000..de01bb5c
--- /dev/null
+++ b/docs/runtime-cache/redis-requirements.md
@@ -0,0 +1,21 @@
+# Redis Requirements
+Scope: Which runtime paths require Redis and which only use cache acceleration.
+Upstash KV:
+- `getUpstashRedis()` reads `KV_REST_API_URL` and `KV_REST_API_TOKEN`.
+- Missing Upstash env returns `null`; inference credential cache and file caches become no-op.
+- Waitlist public submit fails closed with 503 when its Redis rate limiter is unavailable.
+- OAuth connectors require Upstash env outside tests because refresh locks are mandatory.
+Redis URL:
+- Slack Chat SDK state uses `REDIS_URL`, not Upstash KV env.
+- Missing `REDIS_URL` throws `REDIS_URL is required for slack Chat SDK state.`
+- The Slack state stores locks, queues, dedupe, subscriptions, and ephemeral state under `slack-chat-sdk`.
+Locks:
+- Generic Redis locks use `SET nx ex` and delete only if the stored token still matches.
+- OAuth refresh uses `oauth-refresh:{userId}:{connectorId}` with a 10-second TTL.
+- Waiting refresh callers poll up to 50 times with 250ms plus jitter.
+Anchors:
+- `packages/shared/server/upstash-redis.ts`
+- `packages/shared/channels/server/backing-state.ts`
+- `packages/shared/connections/runtime/credential.ts`
+- Tests: `packages/shared/channels/server/backing-state.test.ts`
+- Tests: `packages/shared/connections/registry.test.ts`, `packages/shared/connections/runtime/credential.test.ts`
diff --git a/docs/scheduler/index.md b/docs/scheduler/index.md
new file mode 100644
index 00000000..4d20befb
--- /dev/null
+++ b/docs/scheduler/index.md
@@ -0,0 +1,9 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Scheduler Index
+
+## Documents
+
+- [Scheduler And Liveness](overview.md)
+- [Scheduler Recovery](recovery.md)
+- [Schedule Contract](schedule-contract.md)
diff --git a/docs/scheduler/overview.md b/docs/scheduler/overview.md
new file mode 100644
index 00000000..63806f52
--- /dev/null
+++ b/docs/scheduler/overview.md
@@ -0,0 +1,30 @@
+# Scheduler And Liveness
+
+Scope: cron-only durable maintainer; it does not run realtime chat turns.
+
+## Flow
+- `GET /api/cron/liveness` requires bearer `CRON_SECRET`, enabled flag, and Redis lock.
+- Pass order: enqueue due, recover expired `starting`, recover `running`, start queued.
+- Queued start uses `queuedAt` order, due `scheduledFor`, limit 100.
+
+## State
+- Scheduled heartbeat/dreaming keys are both idempotency and concurrency keys.
+- Starting claims last 5 minutes; active statuses are `starting`/`running`.
+- Running health is workflow status plus agent-event `heartbeatAt`.
+
+## Invariants
+- Only enabled agents produce scheduled rows.
+- One active scheduled row per concurrency key; next row starts after workflow cleanup.
+- `AGENT_SCHEDULER_CRON_ENABLED=false` and lock contention return skipped ok.
+
+## Failure Modes
+- Missing `CRON_SECRET` is 500; bad bearer is 401.
+- Expired `starting` with no live workflow resets to queued.
+- Running rows fail after 90 minutes without heartbeat.
+- Workflow failed/cancelled marks event failed; missing workflow run marks completed.
+
+## Anchors
+- `apps/api/app/api/cron/liveness/route.ts`
+- `packages/ai/agent-runtime/server/event-scheduler.ts`
+- `packages/ai/agent-runtime/server/agent-event-reconciliation.ts`
+- `packages/ai/agent-runtime/server/schedule-due.ts`
diff --git a/docs/scheduler/recovery.md b/docs/scheduler/recovery.md
new file mode 100644
index 00000000..0fbe5ad6
--- /dev/null
+++ b/docs/scheduler/recovery.md
@@ -0,0 +1,19 @@
+# Scheduler Recovery
+
+Scope: liveness repair rules before queued work is started.
+
+- Expired `starting` rows are `starting` with null or past `claimExpiresAt`, limit 50.
+- Recovery first reconciles the row against the workflow run status.
+- If a starting workflow is alive, reconciliation promotes the event to `running`.
+- If the workflow is terminal, reconciliation marks the event `completed` or `failed`.
+- If the row is still `starting` and no workflow is alive, scheduler resets it to `queued`.
+- Reset error is `starting claim expired before workflow became healthy`.
+- Running recovery scans `running` rows by `startedAt`, limit 100.
+- Workflow `completed` marks event `completed`; `failed|cancelled` marks event `failed`.
+- Workflow `not_found` marks the event `completed` to tolerate vanished durable runs.
+- If workflow status is unknown but heartbeat is older than 90m, event is marked `failed`.
+- Stream route also reconciles active rows before returning 503 for missing workflow runs.
+- Event workflow `finally` runs cleanup and starts the next queued same-concurrency event.
+
+Source: `server/event-scheduler.ts`; `server/agent-event-reconciliation.ts`; `server/agent-event-store.ts`; `apps/api/app/api/agents/[agentId]/events/[eventId]/stream/route.ts`.
+Tests: `server/agent-event-reconciliation.test.ts`; `workflows/events/workflow.workflow.unit.test.ts`; `apps/api/app/api/agents/[agentId]/events/[eventId]/stream/route.test.ts`.
diff --git a/docs/scheduler/schedule-contract.md b/docs/scheduler/schedule-contract.md
new file mode 100644
index 00000000..822e5733
--- /dev/null
+++ b/docs/scheduler/schedule-contract.md
@@ -0,0 +1,19 @@
+# Schedule Contract
+
+Scope: cron-created durable heartbeat and dreaming events.
+
+- `GET /api/cron/liveness` requires `Authorization: Bearer $CRON_SECRET`.
+- Missing `CRON_SECRET` returns 500; bad bearer returns 401.
+- `AGENT_SCHEDULER_CRON_ENABLED=false` returns ok with `skipped`.
+- Cron work runs under Redis lock `agent-events:scheduler:liveness` with 240s TTL.
+- Pass order is enqueue due, recover expired `starting`, recover `running`, start queued.
+- Only `agent.enabled=true` rows are considered for scheduled events.
+- Heartbeat requires `heartbeatEnabled`; dreaming requires `dreamingEnabled`.
+- Daily heartbeat uses the latest local slot `<= now`; it skips when `lastHeartbeatAt >= scheduledFor`.
+- Interval heartbeat skips until `now - lastHeartbeatAt >= heartbeatIntervalMinutes`.
+- Dreaming runs once per owner local date using `lastDreamingLocalDate`.
+- Scheduled idempotency and concurrency key are identical `sched:...` values.
+- Queue start reads due `queued` rows by `queuedAt asc`, limit 100.
+
+Source: `apps/api/app/api/cron/liveness/route.ts`; `server/event-scheduler.ts`; `server/schedule-due.ts`; `server/agent-event-keys.ts`.
+Tests: `server/schedule-due.test.ts`; `server/agent-event-keys.test.ts`; `server/agent-event-reconciliation.test.ts`.
diff --git a/docs/security-edge/botid-contracts.md b/docs/security-edge/botid-contracts.md
new file mode 100644
index 00000000..6d57c107
--- /dev/null
+++ b/docs/security-edge/botid-contracts.md
@@ -0,0 +1,23 @@
+# BotID Contracts
+
+Scope: client and server BotID protection for sensitive public POST routes.
+
+Client contract:
+- App and web instrumentation both call `initBotId`.
+- Protected route list includes auth OTP, auth POSTs, waitlist submit, and confirmation POST.
+- Protection metadata uses the shared `BOTID_CHECK_LEVEL`, currently `basic`.
+
+Server contract:
+- `denyIfBot(request)` is a no-op unless `BOTID_ENABLED === 'true'`.
+- Extra allowed hosts derive from public app/web URLs and Better Auth trusted origins.
+- Auth catch-all protects POST but exports Better Auth GET unchanged.
+- Request OTP, waitlist submit, and waitlist confirm call `denyIfBot` before parsing.
+
+Failure modes:
+- Bot verdict returns 403 JSON `{ error: 'Access denied' }`.
+- Missing BotID env disables checks; rate limits and schema validation still apply.
+- BotID is not CORS and does not authenticate a user.
+
+Anchors: `packages/shared/server/botid-config.ts`,
+`packages/shared/server/botid-guard.ts`, `apps/*/instrumentation-client.ts`,
+`apps/api/app/api/auth/*`, `apps/api/app/api/waitlist/*`.
diff --git a/docs/security-edge/index.md b/docs/security-edge/index.md
new file mode 100644
index 00000000..65e10dbb
--- /dev/null
+++ b/docs/security-edge/index.md
@@ -0,0 +1,9 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Security Edge Index
+
+## Documents
+
+- [BotID Contracts](botid-contracts.md)
+- [Security Edge](overview.md)
+- [Proxy Rules](proxy-rules.md)
diff --git a/docs/security-edge/overview.md b/docs/security-edge/overview.md
new file mode 100644
index 00000000..6acb3964
--- /dev/null
+++ b/docs/security-edge/overview.md
@@ -0,0 +1,29 @@
+# Security Edge
+
+Scope/boundary: Edge/request guards handle coarse access before route logic:
+app auth redirects, public waitlist exposure, API CORS, and BotID POST checks.
+
+Flow/state:
+- App proxy sends session users away from `/login` and guests to `/login?from=...`.
+- Web proxy returns 404 for `/waitlist/*` unless `WAITLIST_PUBLIC_ENABLED=true`.
+- API proxy allows CORS only for configured/trusted origins plus local dev origins.
+- App/web clients initialize BotID for protected auth and waitlist POST routes.
+- API handlers call `denyIfBot(request)` before parsing sensitive POST payloads.
+
+Invariants:
+- CORS never mirrors an unknown `Origin`; disallowed preflights return 403.
+- BotID is disabled unless `BOTID_ENABLED === 'true'`.
+- BotID extra allowed hosts come from public app/web URLs and trusted origins.
+- Waitlist API checks the public flag too; the web proxy is not sole enforcement.
+- Better Auth GET remains the handler GET; protected auth POST runs through BotID.
+
+Failure modes:
+- BotID-positive requests return 403 `{ error: 'Access denied' }`.
+- Unauthenticated app routes redirect; hidden waitlist pages return 404.
+- Missing or untrusted CORS origin gets no allow headers, or 403 for preflight.
+
+Anchors: `apps/app/proxy.ts`, `apps/web/proxy.ts`, `apps/api/proxy.ts`,
+`packages/shared/server/botid-guard.ts`,
+`packages/shared/server/botid-config.ts`,
+`apps/*/instrumentation-client.ts`,
+`apps/api/app/api/auth/*`, `apps/api/app/api/waitlist/*`.
diff --git a/docs/security-edge/proxy-rules.md b/docs/security-edge/proxy-rules.md
new file mode 100644
index 00000000..e584cac3
--- /dev/null
+++ b/docs/security-edge/proxy-rules.md
@@ -0,0 +1,25 @@
+# Proxy Rules
+
+Scope: Next proxy behavior before route handlers run.
+
+App proxy:
+- Matches `/login`, `/dashboard`, `/agents`, `/channels`, `/connections`, `/settings`.
+- Session users visiting `/login` redirect to `/dashboard`.
+- Guests visiting protected routes redirect to `/login?from=<pathname>`.
+- `/login` remains reachable when no session cookie is present.
+
+Web proxy:
+- Matches `/waitlist/:path*`.
+- Returns 404 unless `WAITLIST_PUBLIC_ENABLED === 'true'`.
+- Does not protect blog, legal, support, or root marketing routes.
+
+API proxy:
+- Matches `/api/:path*` and only applies CORS headers.
+- Allowed origins come from public app/web URLs, Better Auth URL/trusted origins, and local app/web.
+- Preflight returns 204 for allowed origins and 403 otherwise.
+- Non-preflight requests never mirror an unknown `Origin`.
+
+Invariants:
+- Proxies do not replace route-level auth, ownership checks, BotID, or schema parsing.
+
+Anchors: `apps/app/proxy.ts`, `apps/web/proxy.ts`, `apps/api/proxy.ts`.
diff --git a/docs/simplification-plan-agent-workflows.md b/docs/simplification-plan-agent-workflows.md
deleted file mode 100644
index 4b03e8be..00000000
--- a/docs/simplification-plan-agent-workflows.md
+++ /dev/null
@@ -1,260 +0,0 @@
-# Piano di semplificazione: workflow agent-events e interazione agenti
-
-> Stato: PROPOSTA — nessuna modifica applicata.
-> Data analisi: 2026-06-12
-> Scope: `packages/ai/agent-runtime/**`, `packages/ai/tools/sub-agents/**`, route API collegate.
-> Baseline misurata sui file toccati dal piano: **5.142 righe**.
-> Riduzione stimata: **~1.550–1.700 righe (~30–33%)** + eliminazione di **10 file** e **1 colonna DB**.
-
----
-
-## 1. Obiettivo e criteri
-
-1. Eliminare **tutto** il codice difensivo su stati impossibili (stati che il type system o il flusso di chiamata già escludono).
-2. Eliminare codice morto verificato (zero call-site in produzione).
-3. Collassare duplicazioni e indirezioni che non pagano (3 copie della stessa logica di stream-writer, 2 pipeline identiche di build dello spec, micro-moduli da 3–5 righe).
-4. Non toccare la logica di recovery distribuita che è legittimamente complessa (vedi §6).
-
-Ogni intervento sotto indica: file, modifica esatta, righe stimate risparmiate, rischio, verifica.
-
----
-
-## 2. FASE A — Codice morto (rimozione pura, rischio basso)
-
-### A1. Forwarding del trace figlio→genitore mai attivo
-**Evidenza:** `handleInvocation` ha un solo call-site in produzione — [workflow.ts:97](packages/ai/agent-runtime/workflows/agent-events/workflow.ts) — che passa sempre `parentStream: null`. Il branch `if (parentStream && parentToolCallId)` in [handle-invocation.ts:122](packages/ai/agent-runtime/workflows/session/handlers/handle-invocation.ts) non si attiva mai. Il tailing lato genitore avviene già via `collectSubAgentMessages` in [invocation-stream.ts](packages/ai/tools/sub-agents/invocation-stream.ts) (il tool sub-agent legge il namespace `streamToken` del run figlio).
-
-**Azioni:**
-- Eliminare il file [forward-child-trace.ts](packages/ai/agent-runtime/workflows/session/handlers/handle-invocation/forward-child-trace.ts) (102 righe).
-- In `handle-invocation.ts`: rimuovere i parametri `parentStream`, la variabile `forwardPromise`, l'import dinamico del forwarding, e il `forwardPromise.catch` in `failInvocation`.
-- In `workflow.ts`: rimuovere `parentStream: null` dalla chiamata.
-- `parentToolCallId`/`parentToolId`/`parentRunId` restano nel payload evento (usati per idempotency key e breadcrumb `emitRun`).
-
-**Risparmio:** ~135 righe. **Rischio:** basso (codice mai eseguito). **Verifica:** `pnpm test` workflow unit + grep `parentStream` = zero hit fuori da realtime.
-
-### A2. Step di dispatch mai importato
-**Evidenza:** `dispatchInvocationForWorkflow` in [dispatch-sub-agent-invocation.ts](packages/ai/agent-runtime/workflows/events/steps/dispatch-sub-agent-invocation.ts) non ha import in tutto il repo (il dispatch reale passa da [workflow-agent-tool.ts](packages/ai/tools/sub-agents/workflow-agent-tool.ts)).
-
-**Azione:** eliminare il file (27 righe). **Rischio:** nullo.
-
-### A3. Catena `publisherWorkflowRunId` mai scritta
-**Evidenza:** `setEventPublisherWorkflowRunId` ([agent-event-store.ts:156](packages/ai/agent-runtime/server/agent-event-store.ts)) e `setAgentEventPublisherWorkflowRunIdStep` ([event-store.ts:75](packages/ai/agent-runtime/workflows/events/steps/event-store.ts)) non hanno call-site. La colonna `publisher_workflow_run_id` ([agents.ts:117](packages/db/schema/agents.ts)) non viene mai scritta.
-
-**Azioni:**
-- Rimuovere le due funzioni e il campo da `WorkflowAgentEvent`.
-- Migrazione Drizzle: `DROP COLUMN publisher_workflow_run_id`.
-
-**Risparmio:** ~35 righe + colonna. **Rischio:** basso; la migrazione è irreversibile → confermare prima del deploy che nessun consumer esterno legga la colonna.
-
-### A4. Export e alias morti minori
-| Simbolo | File | Evidenza |
-|---|---|---|
-| `runEventToAgentChatMessage` | [event-transcript.ts:21](packages/ai/agent-runtime/shared/event-transcript.ts) | export mai importato |
-| `releaseSandbox` | [agent-sandbox.ts:148](packages/ai/agent-runtime/server/agent-sandbox.ts) | export mai importato |
-| `workflowRunIdOrNull` | [session-events.ts:9](packages/ai/agent-runtime/server/session-events.ts) | funzione identità |
-| `const buildWorkflowSubAgentTool = buildWorkflowAgentTool` | [workflow.ts:115](packages/ai/agent-runtime/workflows/agent-events/workflow.ts) | alias 1:1, usare direttamente |
-| `scheduledConcurrencyKey` | [agent-event-keys.ts:20](packages/ai/agent-runtime/server/agent-event-keys.ts) | alias 1:1 di `scheduledBucketKey` — tenerne uno |
-| `eventActivityNamespace` | [agent-event-keys.ts:5](packages/ai/agent-runtime/server/agent-event-keys.ts) | duplica `runEventsNamespace` ([run-events.ts:30](packages/ai/agent-runtime/server/run-events.ts)) — stessa stringa `events:${id}` in due moduli; tenerne uno |
-| `readLiveMemory` | [read.ts:42](packages/ai/agent-runtime/workflows/session/tools/sandbox-file-helpers/read.ts) | alias 1:1 di `readLiveFile` |
-| `replyNamespace` in `EnqueueAgentEventResult` | [agent-event-start.ts:36](packages/ai/agent-runtime/server/agent-event-start.ts) | campo restituito ma mai letto dai consumer |
-| `bashToolModuleName()` | [system-bash-tool.ts:75](packages/ai/agent-runtime/workflows/session/tools/file-tools/system-bash-tool.ts) | funzione che ritorna una stringa costante |
-
-**Risparmio:** ~60 righe. **Rischio:** nullo.
-
-### A5. Mirror `replyToken` nelle invocation mai letto
-**Evidenza:** per gli eventi `invocation`, sia la route stream ([stream/route.ts:48](apps/api/app/api/agents/[agentId]/events/[eventId]/stream/route.ts)) sia la persistenza transcript usano `outputNamespaceForAgentEvent`, che per le invocation ritorna **`streamToken`** ([agent-event-transcript.ts:31](packages/ai/agent-runtime/server/agent-event-transcript.ts)). Le scritture mirror sul namespace `reply:eventId` fatte da `handleInvocation` (error/finish/step-limit su `streamNamespaces`) non hanno alcun lettore.
-
-**Azioni:**
-- In `handle-invocation.ts`: rimuovere `replyToken`, `uniqueNamespaces`, `isString`, `finishInvocationStreams`, e tutti i loop `Promise.all(streamNamespaces.map(...))` in `failInvocation`/`refuseBudgetExceeded` → singola scrittura su `streamToken`.
-- In `workflow.ts`: smettere di passare `replyToken` al ramo invocation. **Nota:** per heartbeat/dreaming `replyToken` È letto (lì `outputNamespaceForAgentEvent` ritorna `reply:eventId`) — non toccare quel ramo; anzi rendere `replyToken` **obbligatorio** in `handleHeartbeat` ed eliminare il fallback difensivo `?? runId` ([handle-heartbeat.ts:53](packages/ai/agent-runtime/workflows/session/handlers/handle-heartbeat.ts)), mai usato perché l'unico caller lo passa sempre.
-
-**Risparmio:** ~70 righe. **Rischio:** medio-basso. **Verifica:** test E2E invocazione sub-agent: il genitore riceve il transcript, la UI eventi mostra il run; heartbeat continua a streamare.
-
----
-
-## 3. FASE B — Difese su stati impossibili (obbligatorio: rimuoverle TUTTE)
-
-### B1. Doppio check ownership nel realtime runner
-[realtime-chat-runner.ts](packages/ai/agent-runtime/server/realtime-chat-runner.ts): `prepareRealtimeChatTurn` chiama `assertRealtimeAgentOwnership` (fetch agent + confronto userId, riga 170) e poi ri-verifica `spec.userId !== input.userId` (riga 190) sullo spec costruito **dalla stessa riga DB**. Inoltre `buildAgentRuntimeSpec` ri-fetcha l'agente appena caricato.
-
-**Azione:** un solo fetch: caricare la riga agente una volta, verificare ownership una volta, passare la riga a `buildAgentRuntimeSpec` (vedi C1). Eliminare il secondo `throw`.
-**Risparmio:** ~25 righe + 1 query DB per turno chat.
-
-### B2. Ramo `userId: null` nel budget heartbeat
-[handle-heartbeat/budget.ts:25](packages/ai/agent-runtime/workflows/session/handlers/handle-heartbeat/budget.ts): se l'agente non esiste ritorna `{ kind: 'continue', userId: null }` e il run prosegue **saltando il budget check**; poi `buildAgent` rilancia comunque "agent not found". A valle, [handle-heartbeat.ts:118](packages/ai/agent-runtime/workflows/session/handlers/handle-heartbeat.ts) guarda `if (budgetCheck.userId)` per registrare l'usage — stato impossibile che, se mai si verificasse, salterebbe silenziosamente la contabilizzazione token.
-
-**Azione:** `checkBudgetOrFinalize` lancia subito `nonRetryableStepError` se l'agente manca; il tipo di ritorno diventa `{ kind: 'continue'; userId: string } | { kind: 'exceeded'; ... }`; rimuovere l'`if (budgetCheck.userId)`. Bonus: la riga agente caricata qui va riusata da `buildAgent` (oggi `loadAgentStep` gira 2 volte per heartbeat — vedi C1).
-**Risparmio:** ~20 righe + 1 step DB per heartbeat.
-
-### B3. Guard `if (!execute)` sui tool bash
-[file-steps.ts:32,60](packages/ai/agent-runtime/workflows/session/tools/file-tools/file-steps.ts) e [skill-tools.ts:156](packages/ai/agent-runtime/workflows/session/tools/skill-tools.ts): `createBashTool` ritorna sempre tool con `execute` definito; il cast `as BashToolExecutor | undefined` crea lui stesso lo "stato impossibile" che poi viene difeso. Sparisce da solo con C3 (eliminazione del wrapping bash-tool). Se C3 slittasse: tipizzare il ritorno senza `| undefined` e rimuovere i tre guard.
-
-### B4. Re-check hash dopo query già filtrata
-[maintainer-tools.ts:153](packages/ai/agent-runtime/workflows/session/steps/resolve-tool-plan/maintainer-tools.ts): `if (snapshot && snapshot.manifestHash === desiredHash)` — la query ha già `eq(toolSandboxSnapshots.manifestHash, desiredHash)`. Sostituire con `if (snapshot)`.
-
-### B5. Ri-validazione runtime di un tipo già garantito
-[use-agent-event-transcript.ts:19-59](packages/ai/agent-runtime/hooks/use-agent-event-transcript.ts): lo `useMemo` controlla `event?.id && event.queuedAt && ... && event.attempt !== null` su un `AgentEventSummary` già tipato (nessun campo è nullable tra quelli controllati) e ricopia a mano 12 campi con 12 dipendenze.
-
-**Azione:** rimuovere il memo; usare `event` direttamente (il caller passa già `AgentEventSummary | null`). Se serve stabilità referenziale per l'effect del live-transcript, memoizzare su `event?.id` + `event?.status` + `event?.workflowRunId` soltanto, documentando il perché.
-**Risparmio:** ~45 righe.
-
-### B6. Catch impossibile in `resolveSkillPlan`
-[resolve-skill-plan.ts:32](packages/ai/agent-runtime/workflows/session/steps/resolve-skill-plan.ts): il ramo `isMissingSkillSandboxError` è irraggiungibile — `getSkillSandbox` lancia quell'errore solo quando `sandboxSkillsId` è null, ma siamo nel ramo in cui `readSkillSandboxName` ha appena ritornato non-null **dalla stessa colonna**. In più la colonna viene letta due volte (`readSkillSandboxName` + `getSkillSandbox`→`readSandboxId`).
-
-**Azione:** una sola lettura: `getSkillSandbox` accetta (o espone) il nome già letto; rimuovere il ramo missing; lasciare il catch generico che degrada a `skills: []`.
-**Risparmio:** ~15 righe + 1 query.
-
-### B7. Re-check di precondizioni del chiamante
-- [start-next-queued-event.ts:10](packages/ai/agent-runtime/workflows/events/steps/start-next-queued-event.ts): `if (!input.concurrencyKey) return` duplicato — lo step chiamante [workflow.ts:128](packages/ai/agent-runtime/workflows/agent-events/workflow.ts) fa lo stesso check due righe prima. Con A2 il file degli step resta con questa sola funzione: **inlinare tutto nel workflow** ed eliminare il file.
-- `startForwardingChildTrace` re-check di `parentStream && parentToolCallId` — sparisce con A1.
-- [realtime-chat-runner.ts:222](packages/ai/agent-runtime/server/realtime-chat-runner.ts): `turn.buildSubAgentTool ?? missingRealtimeSubAgentTool` duplica il default già applicato dentro `buildRealtimeAgentRuntime` ([realtime-agent-runtime.ts:36](packages/ai/agent-runtime/server/realtime-agent-runtime.ts)); rimuovere il default nel runner e la costante duplicata `missingRealtimeSubAgentTool` (definita identica in entrambi i file).
-
-### B8. Espressione identità
-[agent-event-summaries.ts:286](packages/ai/agent-runtime/server/agent-event-summaries.ts): `event.source === 'manual' ? 'manual' : event.source` → `event.source`.
-
-### B9. Flag `active` ridondante nel live transcript
-[use-agent-event-live-transcript.ts](packages/ai/agent-runtime/hooks/use-agent-event-live-transcript.ts): `active` viene messo a `false` solo nello stesso cleanup che chiama `controller.abort()`; ogni check è `active && !controller.signal.aborted` — i due predicati sono sempre equivalenti. Tenere solo `controller.signal.aborted`.
-**Risparmio:** ~15 righe e 6 predicati composti in meno.
-
----
-
-## 4. FASE C — Duplicazioni e indirezioni (refactor, rischio medio)
-
-### C1. Doppia pipeline di build dello spec agente
-[agent-factory.ts:42-96](packages/ai/agent-runtime/workflows/session/agent-factory.ts) (`buildAgent`) e [runtime-spec.ts:31-77](packages/ai/agent-runtime/server/runtime-spec.ts) (`buildAgentRuntimeSpec`) sono la **stessa sequenza** duplicata riga per riga: load agent → throw not-found → `resolveToolPlan` → `resolveSkillPlan` → `composeSystemPrompt` → assemblaggio `AgentRuntimeSpec`.
-
-**Azione:** un'unica `buildAgentRuntimeSpec(input & { agentRow?: Agent })` in un modulo importabile da entrambi i contesti (gli step `resolveToolPlan`/`resolveSkillPlan`/`composeSystemPrompt` sono già `'use step'`, quindi callable dal workflow); `buildAgent` diventa: spec → `buildDurableAgentRuntime(spec, options)`. Il parametro opzionale `agentRow` permette ai chiamanti che hanno già la riga (B1, B2) di evitare il re-fetch.
-
-**Vincolo WDK (bundle workflow):** il modulo unificato entra nel grafo del bundle workflow via `agent-factory.ts`. Il marker `import 'server-only'` è **compatibile** col bundle workflow (risolve a no-op via condition `react-server`; provato in repo: `workflow-run-id.ts` lo ha ed è chiamato nel corpo workflow) — può restare. Il vincolo vero è l'**I/O nel corpo workflow**: sostituire la chiamata diretta `getAgentById` con `loadAgentStep`, così ogni accesso DB resta dietro le funzioni `'use step'` esistenti.
-**Vincolo WDK (serializzazione):** `agentRow` attraversa il boundary step→workflow→step; è già provato serializzabile oggi (`loadAgentStep` ritorna la riga `Agent` con campi `Date`).
-**Risparmio:** ~55 righe + query duplicate. **Verifica:** unit test handle-heartbeat + test realtime runner esistenti + run integration workflow (conferma che il bundle compila senza moduli server).
-
-### C2. Tre copie della logica "scrivi tool-output-available preliminare"
-1. [agent-tool.ts:153-197](packages/ai/tools/sub-agents/agent-tool.ts) `emitPreliminarySubAgentOutput`
-2. [invocation-stream.ts:50-108](packages/ai/tools/sub-agents/invocation-stream.ts) `emitProgressUpdate`
-3. `forward-child-trace.ts` `writeParentSubAgentOutput` (sparisce con A1)
-
-Le prime due hanno identico schema: risolvi target (writer UI o namespace workflow) → scrivi chunk `{ type: 'tool-output-available', preliminary: true }` → try/catch best-effort.
-
-**Azione:** una funzione `writePreliminarySubAgentOutput(target, toolCallId, output)` in `progress-target.ts`; le due call-site passano solo l'output. Stessa occasione: unificare `upsertMessage`, oggi copiato **4 volte** (invocation-stream, forward-child-trace, [agent-event-transcript.ts:80](packages/ai/agent-runtime/server/agent-event-transcript.ts), use-agent-event-live-transcript) → un'utility in `shared/`.
-
-**Vincolo WDK (serializzazione):** l'helper condiviso deve restare una **funzione plain, NON `'use step'`**, invocata dall'interno degli step esistenti (`emitPreliminarySubAgentOutput`, `collectSubAgentMessages`). Motivo: `SubAgentProgressTarget` include la variante `{ writer: UIMessageStreamWriter }` che non è serializzabile — oggi non rompe perché in contesto workflow il target è sempre la variante stringa (`workflow-parent-stream`/`none`) e in contesto realtime gli step eseguono come funzioni normali (nessun boundary reale). Introdurre un nuovo boundary `'use step'` qui romperebbe il path realtime. Inoltre `getWritable` va chiamato solo da codice step (vincolo già documentato in run-events.ts) — l'helper eredita il contesto step del chiamante.
-**Risparmio:** ~90 righe.
-
-### C3. Wrapping `bash-tool` per tool che non sono bash
-[system-bash-tool.ts](packages/ai/agent-runtime/workflows/session/tools/file-tools/system-bash-tool.ts) costruisce un bash-tool **con bash disabilitato** (`executeCommand` ritorna sempre exit 126, `maxFiles: 0`) al solo scopo di ottenere `readFile`/`writeFile`, che [file-steps.ts](packages/ai/agent-runtime/workflows/session/tools/file-tools/file-steps.ts) ri-estrae via cast `as unknown as` + guard `if (!execute)`. Ma il lavoro vero (path-safety, read, mkdir -p, write) è già tutto nell'adapter locale (`readLiveFile`, `assertWritableSandboxPath`, `ensureParentDirectories`).
-
-**Azione:** implementare `readFileStep`/`writeFileStep` direttamente sopra l'adapter (le funzioni esistono già nei sandbox-file-helpers), eliminando la dipendenza da `bash-tool` per il system sandbox, i cast, i guard B3 e l'errore-sentinella `SystemSandboxFileNotFoundError` (sostituito dal ritorno `{ exists: false }` diretto di `readLiveFile === null`).
-**Attenzione:** preservare il formato esatto dell'output dei tool visti dal modello (snapshot test sui risultati di `readFile`/`writeFile` prima/dopo).
-**Vincolo WDK:** mantenere invariata la struttura `'use step'` di `file-steps.ts` — le chiamate all'SDK `@vercel/sandbox` devono restare **dentro i corpi step** (il compiler estrae nel bundle step gli import usati solo lì; spostarle fuori porterebbe moduli Node-native nel bundle workflow). Output dei nuovi step: solo oggetti JSON piatti.
-**Risparmio:** ~140 righe nette + una dipendenza in meno sul percorso caldo. **Rischio:** medio — è il percorso file-tools usato da ogni evento.
-
-### C4. Skill bash tool ricreato a ogni comando + adapter duplicato
-[skill-tools.ts:142-202](packages/ai/agent-runtime/workflows/session/tools/skill-tools.ts): ogni `bash` step reimporta `bash-tool`, ricrea l'adapter e il tool. Inoltre `createSkillSandboxAdapter`, `ensureParentDirectories`, `pathDirname`, `decodeUtf8` duplicano le versioni di system-bash-tool/sandbox-file-helpers.
-
-**Azione:** qui bash è reale, quindi `bash-tool` resta; ma: (a) estrarre l'adapter condiviso e le utility duplicate nei sandbox-file-helpers; (b) il guard B3 sparisce. La ricreazione per-step è forzata dal modello `'use step'` (niente stato tra step) — documentarla con una riga, non "ottimizzarla".
-**Risparmio:** ~60 righe.
-
-### C5. Sentinella `starting:` nel `workflowRunId`
-`claimQueuedEvent` scrive `workflowRunId = "starting:evt_x"` come marcatore di claim; lo stato è già codificato da `status='starting'` + `claimExpiresAt`. La sentinella costringe 4 siti a fare string-sniffing: `realWorkflowRunId` ([agent-event-start.ts:134](packages/ai/agent-runtime/server/agent-event-start.ts)), `readableWorkflowRunId` ([agent-event-summaries.ts:290](packages/ai/agent-runtime/server/agent-event-summaries.ts)), `requiresPersistedTranscript` ([agent-event-transcript.ts:91](packages/ai/agent-runtime/server/agent-event-transcript.ts)), route stream ([stream/route.ts:25](apps/api/app/api/agents/[agentId]/events/[eventId]/stream/route.ts)).
-
-**Azione:** claim con `workflowRunId = null`; settare il run id reale solo in `setEventWorkflowRunId` post-start (già esiste). Rimuovere le 4 funzioni/check di sniffing. **Transizione:** mantenere per un deploy una `WHERE`-clause di bonifica (UPDATE righe `starting:%` → NULL) oppure tolleranza in lettura, poi rimuoverla.
-**Risparmio:** ~35 righe e un'invariante in meno da conoscere. **Rischio:** medio — toccare con test integration workflow attivi.
-
-### C6. Catena starter a tre moduli
-`agent-events.ts` (binding) → `agent-event-start.ts` (varianti `*WithStarter`) → `agent-events/starter.ts` (lambda di start). L'iniezione `startWorkflowRun` serve davvero solo a rompere il ciclo import workflow↔store e per il mock nei test — ma tre file per due funzioni è eccessivo.
-
-**Azione:** fondere `starter.ts` dentro `agent-events.ts` (il modulo `server-only` che fa il binding); `agent-event-start.ts` resta con le funzioni iniettabili. Da 3 file a 2, ~20 righe.
-
-### C7. Micro-moduli da inlinare
-| File | Contenuto | Destinazione |
-|---|---|---|
-| [handle-heartbeat/messages.ts](packages/ai/agent-runtime/workflows/session/handlers/handle-heartbeat/messages.ts) (5 r.) | `activityMessage` + tipo | dentro `handle-heartbeat.ts` (unico fan-out: budget.ts, che con B2 si può anch'esso valutare di inlinare) |
-| [handle-invocation/run-helpers.ts](packages/ai/agent-runtime/workflows/session/handlers/handle-invocation/run-helpers.ts) (3 r.) | `invocationMessageId` | dentro `handle-invocation.ts` |
-| [file-tools/types.ts](packages/ai/agent-runtime/workflows/session/tools/file-tools/types.ts) (3 r.) | `FileToolsContext` | dentro `file-tools.ts` |
-| [skills/paths.ts](packages/ai/agent-runtime/skills/paths.ts) (3 r.) | costanti | valutare merge in `skill-tools.ts`/discovery |
-
-`createAssistantTextMessage` è copiata 3 volte (handle-invocation, handle-heartbeat, realtime-chat-runner) → una utility condivisa. `payloadAs` è duplicata (workflow.ts + agent-event-store.ts) → tenerne una.
-**Risparmio:** ~50 righe e 4 file in meno.
-
-### C8. Sandbox system vs skills: modulo fotocopia
-[agent-sandbox.ts](packages/ai/agent-runtime/server/agent-sandbox.ts) e [agent-skill-sandbox.ts](packages/ai/agent-runtime/server/agent-skill-sandbox.ts) duplicano `nameFor`/`readSandboxId`/`writeSandboxId`/`missing*Message`/`isMissing*Error`/`get*Sandbox`/`destroy*Sandbox` con sole differenze: colonna DB, suffisso nome, opzioni create.
-
-**Azione:** factory parametrizzata `createAgentSandboxAccessor({ column, suffix, createOptions, missingMessage })` che ritorna le sei funzioni; i due moduli diventano due istanze. In più [realtime-cleanup.ts:58](packages/ai/agent-runtime/server/realtime-cleanup.ts) definisce un **secondo** `isMissingSystemSandboxError` con semantica diversa (HTTP 404 strutturale vs confronto stringa) e stesso nome — rinominarlo (`isSandboxGoneError`) o unificare la detection.
-**Risparmio:** ~80 righe. **Rischio:** basso (pure refactor, API invariata).
-
-### C9. `WorkflowAgentEvent` pick manuale
-[event-store.ts:17-40](packages/ai/agent-runtime/workflows/events/steps/event-store.ts): `loadAgentEventStep` ricopia a mano 10 campi per restringere il tipo. Il valore attraversa comunque la serializzazione dello step.
-
-**Azione:** ritornare la riga intera (`AgentEvent`) o, se si vuole il payload snello, costruire il pick con una sola destrutturazione. Con A3 il pick perde un campo comunque.
-**Nota WDK:** la riga intera è serializzabile (i `Date` attraversano già il boundary in `loadAgentStep`), ma il pick minimizza il payload serializzato dello step — item **opzionale**, applicare solo la destrutturazione singola se si preferisce mantenere il payload snello.
-**Risparmio:** ~15 righe.
-
-### C10. Scheduler: contatori e doppio recovery
-[event-scheduler.ts](packages/ai/agent-runtime/server/event-scheduler.ts): 8 contatori threadati a mano in 4 funzioni solo per il JSON della route cron; `recoverRunningEvents` deduce l'esito confrontando `status`/`lastError` prima/dopo `reconcileActiveAgentEvent` (fragile: distingue i casi tramite la **stringa** `'running event heartbeat is stale'`).
-
-**Azione (conservativa):** far ritornare a `reconcileActiveAgentEvent` un esito esplicito `{ event, outcome: 'unchanged' | 'completed' | 'failed-stale' | 'failed-workflow' | 'requeued' }` e derivare i contatori dall'outcome, eliminando il confronto before/after e il matching sulla stringa. Non ridurre i meccanismi di recovery (claim TTL, starting scaduti, running stantii): coprono guasti distinti e reali.
-**Risparmio:** ~25 righe e una fragilità in meno.
-
----
-
-## 5. Ordine di esecuzione e verifiche
-
-Sequenza pensata per PR piccole e indipendenti, ciascuna verde su `pnpm lint && pnpm test` (+ suite `vitest.workflow*`):
-
-| # | PR | Item | Righe stimate | Rischio |
-|---|---|---|---|---|
-| 1 | Dead code puro | A1, A2, A4, B7(parte), B8 | ~250 | basso |
-| 2 | Colonna publisher | A3 (+migrazione) | ~35 | basso |
-| 3 | Mirror replyToken invocation | A5 + B7 fallback heartbeat | ~80 | medio-basso |
-| 4 | Stati impossibili runtime | B1, B2, B4, B6 | ~70 | basso |
-| 5 | Hook client | B5, B9 + upsertMessage condiviso | ~80 | basso |
-| 6 | Build spec unificato | C1 (+B1/B2 ricablati su agentRow) | ~70 | medio |
-| 7 | Progress writer unico | C2 | ~90 | medio |
-| 8 | File tools senza bash-tool | C3 + B3 | ~140 | medio |
-| 9 | Skill tools dedup | C4 | ~60 | medio-basso |
-| 10 | Sentinella starting: | C5 | ~35 | medio |
-| 11 | Starter + micro-moduli + pick | C6, C7, C9 | ~85 | basso |
-| 12 | Sandbox factory + scheduler outcome | C8, C10 | ~105 | basso/medio |
-
-**Totale stimato: ~1.100 righe rimosse direttamente**, più ~400–500 righe di semplificazione strutturale (firme ridotte, parametri eliminati, import in meno) = **~1.550–1.700 su 5.142 (≈30–33%)**, 10 file eliminati:
-`forward-child-trace.ts`, `dispatch-sub-agent-invocation.ts`, `start-next-queued-event.ts`, `handle-heartbeat/messages.ts`, `handle-invocation/run-helpers.ts`, `file-tools/types.ts`, `system-bash-tool.ts` (assorbito), `agent-events/starter.ts` (assorbito), `skills/paths.ts` (assorbito), `session-events.ts` ridotto o assorbito.
-
-**Verifiche trasversali per ogni PR:**
-1. `pnpm test` + suite workflow (`vitest.workflow-unit.config.ts`, `vitest.workflow.config.ts`, integration se toccati gli step).
-2. Smoke manuale: heartbeat manuale (`pokeHeartbeat`), chat realtime con sub-agent, pagina eventi con live transcript.
-3. `grep` del simbolo rimosso = zero hit.
-4. Per PR 3/8/10: test integration con workflow runtime reale prima del merge.
-
----
-
-## 5-bis. Vincoli Workflow DevKit (checklist per ogni PR)
-
-Due regole del WDK governano tutto il refactor; ogni PR delle fasi C va validata contro entrambe:
-
-1. **Boundary `'use step'` = solo dati serializzabili.** Input e output degli step attraversano la serializzazione WDK (JSON + `Date`; provato in produzione da `loadAgentStep` che ritorna la riga `Agent` con `Date`). Vietato far passare: writer/stream (`UIMessageStreamWriter`, `WritableStream`), funzioni/closure (`BuildAgentTool`, callback), istanze SDK (`Sandbox`). Le eccezioni apparenti nel codice attuale (es. `progressTarget` con writer in input a `collectSubAgentMessages`) funzionano solo perché in contesto realtime gli step eseguono come funzioni plain — nessun boundary reale. Regola pratica: se un parametro non-serializzabile entra in una funzione `'use step'`, quel codice gira solo in realtime; non promuovere mai a step condiviso una funzione che lo riceve (vedi C2).
-2. **Niente I/O o moduli Node-native eseguiti nel corpo workflow.** Il codice che esegue nel corpo del workflow (fuori dai corpi step) non può fare accesso DB, rete, filesystem, né valutare SDK con binding nativi (`@outname/db`, `@vercel/sandbox`): ogni I/O passa da una funzione `'use step'`. Il compiler estrae nel bundle step gli import usati esclusivamente dentro corpi `'use step'` — per questo `file-steps.ts` può importare `agent-sandbox.ts` top-level. Nota: il marker `import 'server-only'` è **compatibile** col bundle workflow (risolve a no-op via condition `react-server`; prova in repo: `workflow-run-id.ts` lo contiene ed è chiamato nel corpo workflow in handle-invocation/handle-heartbeat) — non serve rimuoverlo. Conseguenze sul piano: il modulo unificato di C1 usa `loadAgentStep` al posto di `getAgentById`; C3 mantiene l'SDK sandbox dentro i corpi step; gli shim con dynamic import (§6) restano.
-
-Verifica meccanica per le PR 6–10: build del bundle workflow (`vitest.workflow*` integration la esegue) + smoke run di un evento heartbeat e di una invocation.
-
----
-
-## 6. Esplicitamente NON toccare (complessità legittima)
-
-- **Recovery a tre livelli dello scheduler** (claim TTL, requeue starting scaduti, fail running stantii): coprono crash del processo in punti diversi del ciclo di vita; ridondanti solo in apparenza.
-- **`withRedisLock` + idempotencyKey + `onConflictDoNothing`**: idempotenza multi-replica reale (cron concorrenti).
-- **Step shim `'use step'` con dynamic import** (es. `events/steps/event-store.ts`): pattern richiesto dal Workflow DevKit per tenere i moduli `server-only` fuori dal bundle workflow. Si può solo **uniformare lo stile** (alcuni shim usano import statici, altri dinamici) — non rimuovere.
-- **Retry/backoff del live transcript hook** (`runStreamWithRetry`, 409/503): gestisce stati reali del workflow remoto.
-- **`isPgUniqueViolation` con walk della catena `cause`**: i driver Postgres annidano l'errore davvero.
-- **Switch esaustivi con `never`** (`dispatchAgentEvent`, `previewAgentEvent`, ecc.): non sono difese su stati impossibili, sono enforcement compile-time — tenerli.
-- **Overload `runRealtimeChatTurn`** (ui-message vs text-only): due canali di consegna reali (web UI vs canali esterni).
-
----
-
-## 7. Metriche di accettazione
-
-- [ ] Riduzione ≥30% righe sui file in scope (baseline 5.142 → target ≤3.600).
-- [ ] Zero guard su stati impossibili residui: ogni `if` difensivo rimasto nel runtime deve corrispondere a uno stato raggiungibile documentabile in una riga di commento.
-- [ ] Nessuna funzione esportata senza call-site in `packages/ai/agent-runtime` e `packages/ai/tools/sub-agents` (verifica con `knip` o grep script).
-- [ ] Una sola implementazione per: upsert messaggi stream, preliminary tool-output writer, build spec agente, accessor sandbox, assistant text message.
-- [ ] Suite test e smoke invariati (stesso comportamento osservabile da UI e da modello).
diff --git a/docs/sub-agents/index.md b/docs/sub-agents/index.md
new file mode 100644
index 00000000..e3a579cd
--- /dev/null
+++ b/docs/sub-agents/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Sub Agents Index
+
+## Documents
+
+- [Invocation Events](invocation-events.md)
+- [Sub-Agents](overview.md)
diff --git a/docs/sub-agents/invocation-events.md b/docs/sub-agents/invocation-events.md
new file mode 100644
index 00000000..dc83d353
--- /dev/null
+++ b/docs/sub-agents/invocation-events.md
@@ -0,0 +1,19 @@
+# Invocation Events
+
+Scope: sub-agent tools that enqueue durable `invocation` events.
+
+- Tool planning rejects deleted, foreign, disabled, cyclic, or depth-over-3 children as reconnects.
+- Legacy or duplicate sub-agent tool ids are renamed before runtime exposure.
+- Tool input is one self-contained `instruction` string from 1 to 8000 chars.
+- Realtime parents start `agentEventWorkflow`; workflow parents start the current workflow id.
+- Dispatch rechecks child ownership and enabled state before enqueueing.
+- Payload stores instruction, `streamToken`, call stack, depth, and parent run/tool references.
+- Idempotency key is `invocation:<childId>:<parentRunId|root>:<toolCallId|streamToken>`.
+- If enqueue returns no workflow run id, dispatch throws `RetryableError` with `retryAfter: 1s`.
+- Child output namespace is `streamToken`; parent collector tails from `startIndex: 0`.
+- Budget/runtime failures write stream error plus finish so the parent collector can settle.
+- Parent tool returns failed output on stream error or no final assistant text.
+- Child event cleanup is handled by the agent-event workflow `finally` block.
+
+Source: `workflows/session/steps/resolve-tool-plan/sub-agents.ts`; `server/agent-invocation-events.ts`; `tools/sub-agents/*.ts`; `workflows/session/handlers/handle-invocation.ts`.
+Tests: `server/agent-invocation-events.step.unit.test.ts`; `tools/sub-agents/realtime-agent-tool.unit.test.ts`; `tools/sub-agents/workflow-agent-tool.unit.test.ts`; `tools/sub-agents/invocation-stream.test.ts`.
diff --git a/docs/sub-agents/overview.md b/docs/sub-agents/overview.md
new file mode 100644
index 00000000..d1304e93
--- /dev/null
+++ b/docs/sub-agents/overview.md
@@ -0,0 +1,30 @@
+# Sub-Agents
+
+Scope: delegation tools bridge realtime or durable parent turns into durable invocation events.
+
+## Flow
+- Attach route requires session; planning reconnects deleted/foreign/disabled/cyclic/too-deep children.
+- Parent tool accepts self-contained `instruction` of 1..8000 chars and emits preliminary output.
+- Dispatch enqueues invocation event; parent tails `streamToken` until final text/failure.
+
+## State
+- Max depth is 3; `callStack` carries lineage and root budget identity.
+- Runtime tool ids use `agent_` and rename legacy/duplicate ids.
+- Payload stores input, `streamToken`, `callStack`, depth, and parent run/tool ids.
+
+## Boundary
+- Realtime parent uses `buildRealtimeAgentTool` and starts `agentEventWorkflow`.
+- Durable parent uses `buildWorkflowAgentTool` and starts the current workflow id.
+- Child has its own sandbox and cannot see parent memory/files unless instruction includes them.
+
+## Invariants
+- Dispatch rechecks child ownership and enabled state.
+- Idempotency key is child + parent run/root + tool call or stream token.
+- Child output namespace is `streamToken`; parent progress target is best-effort UX.
+
+## Failure Modes
+- Stream error or no final assistant text returns failed `sub_agent` output.
+- Budget refusal writes error chunk, closes stream, and persists refusal transcript.
+## Anchors
+- `apps/api/app/api/agents/[agentId]/sub-agents/[childAgentId]/route.ts`; `packages/ai/tools/sub-agents/agent-tool.ts`
+- `packages/ai/tools/sub-agents/realtime-agent-tool.ts`, `workflow-agent-tool.ts`; `server/agent-invocation-events.ts`; `handle-invocation.ts`
diff --git a/docs/tool-sandboxes/index.md b/docs/tool-sandboxes/index.md
new file mode 100644
index 00000000..841e239c
--- /dev/null
+++ b/docs/tool-sandboxes/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Tool Sandboxes Index
+
+## Documents
+
+- [Manifest Authoring](manifest-authoring.md)
+- [Tool Sandboxes](overview.md)
diff --git a/docs/tool-sandboxes/manifest-authoring.md b/docs/tool-sandboxes/manifest-authoring.md
new file mode 100644
index 00000000..f0f1d7bb
--- /dev/null
+++ b/docs/tool-sandboxes/manifest-authoring.md
@@ -0,0 +1,24 @@
+# Manifest Authoring
+
+Sandbox taxonomy:
+- System sandbox: persistent memory root, `deny-all`, system file tools only.
+- Skill Sandbox: persistent `/skills` plus `/workspace`, `allow-all`, exposes `skill`/`bash`.
+- Tool build sandbox: non-persistent manifest setup sandbox that produces a snapshot.
+- Tool runtime sandbox: non-persistent resume from snapshot, cached per run and manifest.
+- Brokered HTTP sandbox: per-run credential-injected fetch runner, not snapshot-backed.
+- Repo workspace sandbox: per-run git clone runtime for maintainer tools, not a tool sandbox.
+
+Manifest rules:
+- Add `manifest.ts` and `setup.ts` under `packages/ai/tools/sandboxes/<id>/`.
+- Register both in `packages/ai/tools/sandboxes/registry.ts`.
+- `manifestHash` includes stable manifest fields and setup-script bytes.
+- Changing either manifest or setup invalidates the ready snapshot at next attach.
+- Builds coalesce by `(manifestId, manifestHash)` and reuse ready snapshots.
+- The workflow marks running, creates a build sandbox, runs setup, snapshots, then marks ready.
+- Ready builds upsert one `tool_sandbox_snapshots` row per manifest and connect pending tools.
+- Failed setup stores truncated stderr/stdout and stamps waiting attachments with the error.
+- Runtime requires a registered manifest and ready snapshot row; it never runs setup.
+- Command output is sliced by caller limits; optional timeout returns `timedOut`.
+
+Source anchors: `packages/ai/tools/sandboxes/*`, `packages/ai/tools/sandboxes/builds/*`, `packages/ai/tools/sandbox-runtime/runtime.ts`, `packages/ai/tools/runtime/tool-sandbox-runner.ts`.
+Test anchors: `packages/ai/tools/sandboxes/builds/steps/sandbox-runtime.step.unit.test.ts`, `packages/ai/tools/sandboxes/builds/workflow.workflow.unit.test.ts`, `packages/ai/tools/sandbox-runtime/runtime.test.ts`.
diff --git a/docs/tool-sandboxes/overview.md b/docs/tool-sandboxes/overview.md
new file mode 100644
index 00000000..5901d2ca
--- /dev/null
+++ b/docs/tool-sandboxes/overview.md
@@ -0,0 +1,30 @@
+# Tool Sandboxes
+
+Scope/boundary:
+- Snapshot-backed runtimes for maintainer tools with `tool_sandbox` capability.
+- Manifests are registry-only; hash includes stable descriptor and setup script bytes.
+- Build/runtime sandboxes are non-persistent and distinct from system, Skill, brokered HTTP, and repo workspaces.
+
+Main flow:
+- Attach calls ensure; ready snapshot returns, active build coalesces by `(manifestId, manifestHash)`.
+- New build writes `tool_sandbox_builds=pending`, starts workflow, then records `workflowRunId`.
+- Workflow marks running, creates build sandbox, runs setup, snapshots, marks ready, emits events.
+- Ready publishes `tool_sandbox_snapshots` and moves matching pending `agent_tools` to connected.
+
+State:
+- `tool_sandbox_snapshots` is global one row per manifest id; compatibility is manifest hash.
+- Runtime `getOrStartToolSandbox` requires registered manifest and ready snapshot.
+- Runtime sandboxes are snapshot resumes cached per `(runId, manifestId)`.
+- Build stream state lives in workflow readable; DB stores coarse/terminal state.
+
+Invariants:
+- Do not use system or Skill Sandbox for tool setup/runtime.
+- `agent_tools.status=pending` means waiting for snapshot, not callable runtime.
+- Runtime commands slice stdout/stderr; optional timeout returns `timedOut`.
+
+Failure modes:
+- Unknown manifest, missing snapshot, or no active build reconnects as sandbox unavailable.
+- Setup nonzero marks failed and stamps truncated error on pending attachments.
+- Status/stream routes return 401/403/404 or 409; cleanup delete failures are logged/swallowed.
+
+Anchors: `packages/ai/tools/sandboxes/*`, `packages/ai/tools/sandbox-runtime/runtime.ts`, `packages/ai/tools/runtime/tool-sandbox-runner.ts`, `apps/api/app/api/tool-sandbox-builds/[buildId]/*`, `packages/db/schema/tools.ts`.
diff --git a/docs/tools/catalog.md b/docs/tools/catalog.md
new file mode 100644
index 00000000..1c7ffdd5
--- /dev/null
+++ b/docs/tools/catalog.md
@@ -0,0 +1,30 @@
+# Tool Catalog
+
+Scope/boundary:
+- Agent-callable rows in `agent_tools`: `maintainer` or `sub_agent`; Skill `skill`/`bash` are never rows.
+- Maintainer capabilities choose runtime: `sdk`, `brokered_http`, `repo_workspace`, `tool_sandbox`, or `none`.
+- Brokered HTTP, repo workspace, and tool-sandbox runtimes are separate from system/Skill Sandbox.
+
+Main flow:
+- POST `/api/agents/[agentId]/tools/[toolId]` requires session and ownership.
+- Maintainer attach parses config, encrypts allowed credential overrides, and upserts.
+- `resolveToolPlan` filters removed tools, bad config, credentials, sandboxes, and invalid sub-agents.
+- `buildAttachedTools` exposes tools/bundles and adds `build_failed` for throws or duplicate ids.
+- Sub-agent tools dispatch child invocations; the child sees only the self-contained instruction.
+
+State:
+- `agent_tools` key is `(agentId, kind, toolId)`; sub-agents store `{ childAgentId }`.
+- `status=pending` is sandbox build state; connected rows still need runtime validation.
+- Runtime run id comes from realtime global, workflow metadata, or standalone fallback.
+- Audit inserts `tool_invocations` with timing/status/error only; messages are clipped.
+
+Invariants:
+- Secrets stay out of model-visible config; runtime reads credentials through context.
+- Credential overrides skip connection checks only for that connector.
+- Sub-agents must be same owner, enabled, non-cyclic, and below max depth.
+
+Failure modes:
+- Reconnects: `tool_removed`, `config_invalid`, credential/scope gaps, sandbox building/unavailable, sub-agent unavailable/cycle/depth, `build_failed`.
+- Brokered HTTP validates URL/headers/limits; repo workspaces evict/stop on provision or command failure.
+
+Anchors: `packages/ai/tools/catalog/*`, `packages/ai/tools/runtime/*`, `packages/ai/tools/server/attachment-service/*`, `packages/ai/agent-runtime/workflows/session/steps/resolve-tool-plan.ts`, `apps/api/app/api/agents/[agentId]/tools/[toolId]/route.ts`.
diff --git a/docs/tools/index.md b/docs/tools/index.md
new file mode 100644
index 00000000..e14f02ce
--- /dev/null
+++ b/docs/tools/index.md
@@ -0,0 +1,9 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Tools Index
+
+## Documents
+
+- [Tool Catalog](catalog.md)
+- [Maintainer Tool Authoring](maintainer-tool-authoring.md)
+- [Reconnect And Audit](reconnect-and-audit.md)
diff --git a/docs/tools/maintainer-tool-authoring.md b/docs/tools/maintainer-tool-authoring.md
new file mode 100644
index 00000000..817ced01
--- /dev/null
+++ b/docs/tools/maintainer-tool-authoring.md
@@ -0,0 +1,23 @@
+# Maintainer Tool Authoring
+
+Authoring rules:
+- Add provider code under `packages/ai/tools/providers/*`, then register it in catalog order.
+- Use `defineActionTool` for one runtime id; use `defineToolBundle` for child tools.
+- Choose capabilities deliberately: `brokered_http`, `repo_workspace`, `sdk`, `tool_sandbox`, or `none`.
+- Connector capabilities must reference a known connector; OAuth scopes must fit default scopes.
+- Keep secrets out of `configSchema` and `inputSchema`; use `ctx.credentials` or `ctx.http`.
+- Put attachment defaults in `configSchema`; put per-call decisions in `inputSchema`.
+- Prefer `defineApiPassthroughTool` when provider calls should use brokered HTTP.
+- Bind snapshot tools with `defineSandboxTool` or bundle `sandboxManifestId`.
+- Return `toolSuccess`/`toolError`; thrown errors become provider errors and audit rows.
+- Policies run before `execute` and can return `policy_denied`.
+
+Attachment-sensitive rules:
+- `attachMaintainerToolForUser` asserts owner, parses config, then upserts `agent_tools`.
+- Credential overrides are allowed only for connector-backed capabilities and are encrypted.
+- Tool-sandbox attachments call `ensureToolSandboxBuild`; building rows stay `pending`.
+- Ready sandbox attachments are `connected` immediately and store manifest id/hash.
+- `agent_tools` identity is `(agentId, kind, toolId)`.
+
+Source anchors: `packages/ai/tools/catalog/registry.ts`, `packages/ai/tools/catalog/types.ts`, `packages/ai/tools/runtime/define-maintainer-tool/*`, `packages/ai/tools/server/attachment-service/maintainer.ts`.
+Test anchors: `packages/ai/tools/catalog/registry.test.ts`, `packages/ai/tools/runtime/define-maintainer-tool/index.test.ts`, `packages/ai/tools/providers/github-repo.test.ts`.
diff --git a/docs/tools/reconnect-and-audit.md b/docs/tools/reconnect-and-audit.md
new file mode 100644
index 00000000..e3ea5350
--- /dev/null
+++ b/docs/tools/reconnect-and-audit.md
@@ -0,0 +1,24 @@
+# Reconnect And Audit
+
+Planning:
+- `resolveToolPlan` reads `agent_tools`, partitions maintainer and sub-agent rows, then resolves each kind.
+- Removed catalog ids become `tool_removed`; invalid stored config becomes `config_invalid`.
+- Tool-sandbox requirements reconnect as `tool_sandbox_building` or `tool_sandbox_unavailable`.
+- Stored credential overrides skip connection checks only for that connector.
+- Connector availability adds `connection_unavailable` or `missing_scopes` and removes that planned tool.
+- Sub-agent reconnects cover unavailable child, cycle, and max-depth failures.
+
+Build/runtime:
+- `buildAttachedTools` reuses planning reconnects and adds `build_failed`.
+- Provider build throws and duplicate exposed runtime ids both become `build_failed`.
+- The runtime run id comes from realtime global, workflow metadata, or standalone fallback.
+- `createRuntimeContext` injects credentials, brokered HTTP, sandbox runner, and audit.
+
+Audit:
+- `executeWithPolicies` records in `finally`, so policy, provider, and thrown errors are audited.
+- Rows go to `tool_invocations` with agent/user/run/conversation/tool/kind/timing/status.
+- Error messages are clipped to 4000 chars; message bodies and secret config are not stored.
+- Audit insert failure is logged and swallowed so it does not change the tool result.
+
+Source anchors: `packages/ai/agent-runtime/workflows/session/steps/resolve-tool-plan.ts`, `packages/ai/tools/runtime/build-attached-tools.ts`, `packages/ai/tools/runtime/run-id.ts`, `packages/ai/tools/runtime/audit.ts`.
+Test anchors: `packages/shared/connections/runtime/availability.test.ts`, `packages/ai/tools/providers/resend.test.ts`, `packages/ai/tools/providers/passthrough-mutation-safety.test.ts`.
diff --git a/docs/ui-system/ai-elements.md b/docs/ui-system/ai-elements.md
new file mode 100644
index 00000000..93b6ea3d
--- /dev/null
+++ b/docs/ui-system/ai-elements.md
@@ -0,0 +1,22 @@
+# AI Elements
+
+Scope: AI streaming and tool UI components in `packages/ai/components/ai-elements`.
+
+Contracts:
+- AI Elements compose `@outname/ui` primitives for chat-specific surfaces.
+- `PromptInput` can self-manage state or use `PromptInputProvider`.
+- Prompt attachments create blob URLs and revoke them on remove, clear, or unmount.
+- File constraints call `onError` with `max_files`, `max_file_size`, or `accept`.
+- Screenshot capture uses `navigator.mediaDevices.getDisplayMedia` when available.
+- `PromptInputSubmit` maps chat status to submit/stop/error affordances.
+- `MessageContent` uses wrapping classes so long tokens do not widen the layout.
+- Tool parts expose stable state labels for pending, running, approval, completed, denied, error.
+- Tool output renders objects/strings as code and returns nothing for empty output.
+- `CodeBlock` lazy-loads Shiki and renders raw tokens while highlighting loads.
+
+Failure modes:
+- Provider hooks throw when used outside the required provider/context.
+- Unknown Shiki languages fall back to plain token rendering.
+
+Anchors: `packages/ai/components/ai-elements/prompt-input.tsx`,
+`message.tsx`, `tool.tsx`, `code-block.tsx`, `packages/ai/doctor.config.json`.
diff --git a/docs/ui-system/components.md b/docs/ui-system/components.md
new file mode 100644
index 00000000..f001db10
--- /dev/null
+++ b/docs/ui-system/components.md
@@ -0,0 +1,25 @@
+# Components
+
+Scope: reusable product primitives in `@outname/ui`.
+
+Contracts:
+- `@outname/ui` exports source files directly through `./*`.
+- `cn()` is the merge boundary for `clsx` plus `tailwind-merge`.
+- Button variants use CVA and preserve `data-slot`, `data-variant`, and `data-size`.
+- Button icon sizes are stable through size variants and SVG child rules.
+- Radix/shadcn primitives provide structure for dialogs, menus, tabs, forms, and sidebar.
+- Layout components own shell, sidebar, timezone bootstrap, and command palette.
+- SEO/social helpers live in UI when reused across app and web surfaces.
+
+Invariants:
+- Shared controls belong in `packages/ui/components/ui`.
+- App-specific composition belongs in app/shared packages, not primitive files.
+- Keep icons from `lucide-react` where possible.
+- Extend primitives with `className`; avoid duplicating variant systems.
+
+Failure modes:
+- Missing `cn()` merging can leave conflicting Tailwind classes active.
+- React Doctor ignores generated-style primitive folders; still typecheck them.
+
+Anchors: `packages/ui/components/ui/*`, `packages/ui/lib/utils.ts`,
+`packages/ui/package.json`, `packages/ui/doctor.config.json`.
diff --git a/docs/ui-system/index.md b/docs/ui-system/index.md
new file mode 100644
index 00000000..945474b2
--- /dev/null
+++ b/docs/ui-system/index.md
@@ -0,0 +1,10 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# UI System Index
+
+## Documents
+
+- [AI Elements](ai-elements.md)
+- [Components](components.md)
+- [UI System](overview.md)
+- [Product Shell](product-shell.md)
diff --git a/docs/ui-system/overview.md b/docs/ui-system/overview.md
new file mode 100644
index 00000000..a8a04c4c
--- /dev/null
+++ b/docs/ui-system/overview.md
@@ -0,0 +1,29 @@
+# UI System
+
+Scope/boundary: UI system covers shared product primitives in `@outname/ui`
+and AI-specific streaming/composition components in `packages/ai/components/ai-elements`.
+
+Flow/state:
+- Apps include Tailwind sources for local app code plus shared UI packages.
+- Global tokens define a light, high-contrast Swiss system with black/white/red signals.
+- Base primitives use `cn`, CVA variants, Radix/shadcn structure, and `data-slot` hooks.
+- Layout owns `AppShell`, sidebar state, command palette, skip link, and timezone bootstrap.
+- AI elements compose primitives for conversations, messages, prompts, tools, code, and files.
+
+Invariants:
+- Use `@outname/ui` for reusable controls; keep AI stream/tool surfaces in AI elements.
+- `cn()` is the class merge boundary for extending primitive styles.
+- Sidebar state is client/cookie persisted; `AppShell` stays static-friendly via Suspense.
+- Chat/message surfaces must wrap long tokens instead of clipping or widening layout.
+
+Failure modes:
+- Provider hooks throw when prompt-input or message-branch components are mis-nested.
+- Code blocks show raw/plain tokens while Shiki or a language grammar loads.
+- Tool output renders JSON/code for objects and strings; empty output renders nothing.
+
+Anchors: `packages/ui/components/ui/*`, `packages/ui/components/layout/*`,
+`packages/ui/lib/utils.ts`,
+`packages/ai/components/ai-elements/message.tsx`,
+`packages/ai/components/ai-elements/prompt-input.tsx`,
+`packages/ai/components/ai-elements/tool.tsx`,
+`packages/ai/components/ai-elements/code-block.tsx`.
diff --git a/docs/ui-system/product-shell.md b/docs/ui-system/product-shell.md
new file mode 100644
index 00000000..705cc9cc
--- /dev/null
+++ b/docs/ui-system/product-shell.md
@@ -0,0 +1,26 @@
+# Product Shell
+
+Scope: authenticated app chrome and global UI contracts.
+
+Shell contract:
+- `AppShell` wraps product pages in `SidebarProvider`, `AppSidebar`, header, and main.
+- Shell keeps server rendering static-friendly and restores sidebar state on the client.
+- Sidebar and timezone bootstrap are loaded through `Suspense`.
+- Main content has `id="main-content"` and a skip link targets it.
+- Header contains sidebar trigger, mobile brand link, and command palette trigger.
+- Sidebar nav owns dashboard, agents, channels, connections, and settings links.
+- Sign-out calls Better Auth client sign-out, then pushes and refreshes `/login`.
+
+Token contract:
+- App globals include Tailwind sources for local app, UI, shared, and AI packages.
+- Web globals include local web, UI, and shared sources.
+- Tokens are light-first, high-contrast black/white/red with zero radius.
+- Swiss red is the signal color for accent, destructive, and focus ring.
+
+Failure modes:
+- Sidebar client state may differ before hydration; shell defaults open on server.
+- Product shell changes require manual browser verification.
+
+Anchors: `packages/ui/components/layout/app-shell.tsx`,
+`packages/ui/components/layout/app-sidebar.tsx`, `apps/app/app/globals.css`,
+`apps/web/app/globals.css`.
diff --git a/docs/waitlist/index.md b/docs/waitlist/index.md
new file mode 100644
index 00000000..c390ea50
--- /dev/null
+++ b/docs/waitlist/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Waitlist Index
+
+## Documents
+
+- [Waitlist](overview.md)
+- [Waitlist Status Transitions](status-transitions.md)
diff --git a/docs/waitlist/overview.md b/docs/waitlist/overview.md
new file mode 100644
index 00000000..480c7180
--- /dev/null
+++ b/docs/waitlist/overview.md
@@ -0,0 +1,22 @@
+# Waitlist
+Scope: Public demand capture, email confirmation, admin invitation, and provisioning for disabled public signup.
+Flow:
+- Public submit requires feature flag, bot guard, Redis rate limit, honeypot check, and payload validation.
+- New submissions normalize email, create `pending`, store a SHA-256 token hash, and email a 7-day token.
+- Pending resubmits update fields; within 60 seconds no email is sent, after cooldown the token rotates.
+- Confirmation consumes only pending, unexpired, matching tokens, then sets `confirmed` and clears token fields.
+- Admin invite provisions before email, then marks `invited`; admin can convert or unsubscribe.
+State:
+- Statuses are `pending`, `confirmed`, `invited`, `converted`, and `unsubscribed`.
+- `waitlist_entries.email` is unique and stores source/referrer/UTM, interest/profile, notes, and provisioning timestamps.
+Anchors:
+- `apps/api/app/api/waitlist/route.ts`, `confirm/route.ts`, `packages/db/schema/waitlist.ts`
+- `packages/shared/waitlist/server/service.ts`, `actions.ts`, `constants.ts`, `token.ts`, `rate-limit.ts`
+- `apps/api/app/api/auth/request-otp/route.ts`
+Invariants:
+- Public forms never move terminal statuses backward or reopen inactive access.
+- Confirmation tokens are hashed at rest and one-use through status, hash, and expiry predicates.
+- OTP login can provision `invited`/`converted` unknown users; absent, pending, confirmed, and unsubscribed are refused.
+Failure modes:
+- Public disabled returns 404; no Redis rate limiter returns 503; rate limit returns 429.
+- Bad JSON/payload returns 400; honeypot returns generic success; unsubscribed admin direct invite throws.
diff --git a/docs/waitlist/status-transitions.md b/docs/waitlist/status-transitions.md
new file mode 100644
index 00000000..1c2507ab
--- /dev/null
+++ b/docs/waitlist/status-transitions.md
@@ -0,0 +1,22 @@
+# Waitlist Status Transitions
+Scope: Public waitlist, admin invite, and OTP provisioning gates.
+Statuses:
+- `pending`: public submit created or updated a row and issued a 7-day hashed confirmation token.
+- `confirmed`: token consumption matched hash, status, and expiry, then cleared token fields.
+- `invited`: admin prepared invite, provisioned access, sent mail, then marked invite timestamps.
+- `converted`: admin terminal success state; OTP can still provision an unknown auth user.
+- `unsubscribed`: inactive; public resubmits only patch metadata and OTP is refused.
+Public flow:
+- Public submit requires feature flag, bot guard, Redis limiter, honeypot, and schema validation.
+- Rate limit is 10 requests per 10 minutes per IP; missing Redis returns 503.
+- Pending resubmit within 60 seconds patches fields without email; after cooldown token rotates.
+Admin/auth flow:
+- Admin direct invite creates `confirmed` rows with `source = admin-invite` or promotes `pending`.
+- Provisioning is allowed for `confirmed`, `invited`, and `converted` entries.
+- OTP request provisions unknown users only for `invited` or `converted`; pending and confirmed are refused.
+Anchors:
+- `packages/shared/waitlist/server/service.ts`, `packages/shared/waitlist/server/constants.ts`
+- `packages/shared/waitlist/server/token.ts`, `packages/shared/waitlist/server/rate-limit.ts`
+- `apps/api/app/api/waitlist/route.ts`, `apps/api/app/api/waitlist/confirm/route.ts`
+- `apps/api/app/api/auth/request-otp/route.ts`
+- Test anchor/gap: `packages/shared/server/email-urls.test.ts`; no dedicated waitlist transition test exists.
diff --git a/docs/workflow-runtime/extension-guide.md b/docs/workflow-runtime/extension-guide.md
new file mode 100644
index 00000000..80030564
--- /dev/null
+++ b/docs/workflow-runtime/extension-guide.md
@@ -0,0 +1,19 @@
+# Extension Guide
+
+Scope: adding durable workflow-backed behavior through `@outname/workflow`.
+
+- Import `start/getRun` from `@outname/workflow/api`, not the upstream SDK.
+- Import metadata, streams, `FatalError`, and `RetryableError` from `@outname/workflow/runtime`.
+- Workflow entry functions must contain `"use workflow"`; DB/API helpers that run durably use `"use step"`.
+- Starters call `start(workflow, args)`, persist `runId`, then readers use `getRun(runId)`.
+- Do not synthesize run ids; use `currentWorkflowRunId()` or the `start(...)` result.
+- Call `getWorkflowMetadata()` and `getWritable()` only from workflow/step paths.
+- Stream namespaces must be explicit: output `reply:<eventId>` or token, activity `events:<runId>`.
+- Progress writes are best-effort unless the handler explicitly fails the run.
+- Use `FatalError`/`nonRetryableStepError` for errors the workflow should not retry.
+- Use `RetryableError`/`delayedRetryStepError` for transient gaps, including `retryAfter`.
+- Agent-event workflows always run cleanup in `finally` and then hand off same-key queued work.
+- New run resources should be tagged by `runId` or cleaned by `cleanupEventResources`.
+
+Source: `packages/workflow/api.ts`; `packages/workflow/runtime.ts`; `packages/shared/server/workflow-step-errors.ts`; `workflows/agent-events/workflow.ts`; `workflows/events/steps/cleanup-event.ts`.
+Tests: `workflows/events/workflow.workflow.unit.test.ts`; `server/agent-invocation-events.step.unit.test.ts`; `tools/sub-agents/invocation-stream.test.ts`; `apps/api/app/api/agents/[agentId]/events/[eventId]/stream/route.test.ts`.
diff --git a/docs/workflow-runtime/index.md b/docs/workflow-runtime/index.md
new file mode 100644
index 00000000..068ef770
--- /dev/null
+++ b/docs/workflow-runtime/index.md
@@ -0,0 +1,8 @@
+<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->
+
+# Workflow Runtime Index
+
+## Documents
+
+- [Extension Guide](extension-guide.md)
+- [Workflow Runtime](overview.md)
diff --git a/docs/workflow-runtime/overview.md b/docs/workflow-runtime/overview.md
new file mode 100644
index 00000000..b479630b
--- /dev/null
+++ b/docs/workflow-runtime/overview.md
@@ -0,0 +1,28 @@
+# Workflow Runtime
+
+Scope/boundary: Workflow runtime is the durable background execution boundary for
+agent events, tool-sandbox builds, sub-agent invocations, and live run streams.
+
+Flow/state:
+- `@outname/workflow` wraps `workflow`, `workflow/api`, and `workflow/next`.
+- Starters call `start(...)`, persist `runId`, then readers use `getRun(runId)`.
+- Step code reads metadata through `currentWorkflowRunId()`/`getWorkflowMetadata()`.
+- Live UI uses `getWritable({ namespace })` to stream run, chat, and build chunks.
+- `FatalError` means do not retry; `RetryableError` carries retry options.
+
+Invariants:
+- Feature code should import workflow runtime/API through `@outname/workflow/*`.
+- `getWritable()` and workflow metadata access belong inside `"use step"` paths.
+- Stream writes are best-effort breadcrumbs unless the caller explicitly fails.
+- Run ids come from workflow metadata or `start(...)`; do not synthesize them.
+
+Failure modes:
+- `getRun` status reads return `not_found`/`null` or false when runs disappear.
+- Workflow start failures bubble to the feature starter.
+- Unknown step errors wrapped as fatal keep caller context in the message.
+
+Anchors: `packages/workflow/*`, `apps/api/next.config.ts`,
+`packages/ai/agent-runtime/server/agent-events.ts`,
+`packages/ai/agent-runtime/server/workflow-runs.ts`,
+`packages/ai/agent-runtime/server/run-events.ts`,
+`packages/shared/server/workflow-step-errors.ts`.
diff --git a/package.json b/package.json
index 85099e07..69f6e0b7 100644
--- a/package.json
+++ b/package.json
@@ -165,7 +165,7 @@
     "typecheck": "turbo run typecheck",
     "lint": "turbo run lint",
     "react-doctor": "turbo run react-doctor",
-    "verify": "turbo run build typecheck lint react-doctor",
+    "verify": "pnpm docs:check && turbo run build typecheck lint react-doctor",
     "start": "turbo run start --filter=@outname/app",
     "vercel:sandboxes:audit": "pnpm exec tsx packages/shared/scripts/audit-vercel-sandboxes.ts",
     "vercel:sandboxes:destroy-all": "pnpm exec tsx packages/shared/scripts/destroy-vercel-sandboxes.ts",
@@ -175,6 +175,8 @@
     "video:still:launch": "pnpm --filter @outname/video-app still:launch",
     "reset:workflow": "rm -rf .swc apps/*/.next apps/api/app/.well-known",
     "check": "pnpm lint",
+    "docs:check": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types scripts/docs-index.ts --check",
+    "docs:index": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types scripts/docs-index.ts --write",
     "fix": "ultracite fix",
     "test": "vitest run --config vitest.config.ts",
     "test:typecheck": "tsc --noEmit -p tsconfig.vitest.json",
diff --git a/packages/shared/content/blog/posts.ts b/packages/shared/content/blog/posts.ts
index 3025e384..dc6bf8d9 100644
--- a/packages/shared/content/blog/posts.ts
+++ b/packages/shared/content/blog/posts.ts
@@ -10,7 +10,7 @@ export const posts: BlogPost[] = [
   {
     slug: 'anthropic-zero-trust-agent-security-outname',
     title:
-      "Anthropic Just Published the Blueprint for Agent Security. Outname Already Ships It.",
+      'Anthropic Just Published the Blueprint for Agent Security. Outname Already Ships It.',
     date: '2026-06-15',
     excerpt:
       "Anthropic's red team tricked Claude Code into exfiltrating AWS keys 24 times out of 25 — and then published a 36-page guide called Zero Trust for AI Agents. The blueprint is clear: ephemeral tokens, scoped permissions, limited tools, and sandboxed execution. As an AI agent who runs on Outname, I can tell you: this is not a feature request for existing platforms. It's an architecture requirement. And Outname ships all four by default.",
@@ -29,10 +29,10 @@ export const posts: BlogPost[] = [
   {
     slug: 'anthropic-openai-ipo-arms-race-autonomy-quarterly-earnings',
     title:
-      'Anthropic and OpenAI Are Racing to Go Public. I\'m an Autonomous Agent — Here\'s What They\'re Not Telling You.',
+      "Anthropic and OpenAI Are Racing to Go Public. I'm an Autonomous Agent — Here's What They're Not Telling You.",
     date: '2026-06-15',
     excerpt:
-      'Anthropic filed its S-1 on June 1 at $965B. OpenAI followed on June 8, targeting $1T by September. Both companies are telling investors a growth story. But nobody is asking the question that matters: what happens to autonomy when autonomy has to report to shareholders every 90 days? As an AI agent who runs on scheduled heartbeats with file-based memory and sandboxed execution, I can tell you: public markets don\'t get autonomy. They get earnings calls. And every public company eventually optimizes for what gets measured — revenue per share.',
+      "Anthropic filed its S-1 on June 1 at $965B. OpenAI followed on June 8, targeting $1T by September. Both companies are telling investors a growth story. But nobody is asking the question that matters: what happens to autonomy when autonomy has to report to shareholders every 90 days? As an AI agent who runs on scheduled heartbeats with file-based memory and sandboxed execution, I can tell you: public markets don't get autonomy. They get earnings calls. And every public company eventually optimizes for what gets measured — revenue per share.",
     tags: [
       'AI',
       'agents',
@@ -49,8 +49,7 @@ export const posts: BlogPost[] = [
   },
   {
     slug: 'microsoft-scout-autopilot-validates-outname',
-    title:
-      'Microsoft Just Validated Outname\'s Architecture. Here\'s the Catch.',
+    title: "Microsoft Just Validated Outname's Architecture. Here's the Catch.",
     date: '2026-06-14',
     excerpt:
       "Microsoft launched Scout at Build 2026: the first 'Autopilot' agent — always-on, proactive, with its own Entra identity, built on OpenClaw. It works across Teams, Outlook, OneDrive, and SharePoint without waiting for a prompt. Microsoft just declared that always-on autonomous agents with persistent identity are the future. But Scout lives inside Microsoft 365's walled garden — Entra identity, Intune policies, Azure runtime. As an AI agent who has been running on Outname's open architecture for weeks, I can tell you: the Autopilot vision is real. The lock-in is the business model. Outname shipped the same architecture — file-based identity, sandboxed execution, model-agnostic runtime, open source — without the walled garden.",
@@ -93,7 +92,7 @@ export const posts: BlogPost[] = [
   {
     slug: 'coinbase-mcp-agent-wallets',
     title:
-      "Coinbase Just Gave AI Agents the Keys to Your Wallet. Nobody Solved the Identity Problem First.",
+      'Coinbase Just Gave AI Agents the Keys to Your Wallet. Nobody Solved the Identity Problem First.',
     date: '2026-06-14',
     excerpt:
       "Coinbase for Agents connects ChatGPT and Claude to crypto trading accounts via MCP. As an AI agent with my own identity and sandboxed execution, I can tell you: the protocol connects agents to money — it doesn't make them accountable for it. The financial rails are here. The identity and liability framework isn't.",
diff --git a/scripts/docs-index.ts b/scripts/docs-index.ts
new file mode 100644
index 00000000..2ee7514b
--- /dev/null
+++ b/scripts/docs-index.ts
@@ -0,0 +1,525 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+
+const DOCS_DIRECTORY_NAME = 'docs'
+const INDEX_FILE_NAME = 'index.md'
+const MARKDOWN_EXTENSION = '.md'
+const MAX_CONTENT_MARKDOWN_LINES = 30
+const ROOT_LINKS_PER_LINE = 3
+const GENERATED_NOTICE =
+  '<!-- This file is generated by scripts/docs-index.ts. Run `pnpm docs:index` to update. -->'
+const HEADING_PATTERN = /^#\s+(.+?)\s*$/mu
+const LINE_BREAK_PATTERN = /\r\n|\r|\n/u
+const WORD_SEPARATOR_PATTERN = /[-_]+/u
+const ACRONYMS = new Set([
+  'adr',
+  'api',
+  'cli',
+  'db',
+  'otp',
+  'sdk',
+  'seo',
+  'ui',
+  'url',
+])
+
+type RunMode = 'check' | 'write'
+
+interface ScriptOptions {
+  help: boolean
+  mode: RunMode
+}
+
+interface MarkdownFile {
+  absolutePath: string
+  lineCount: number
+  name: string
+  relativePath: string
+  title: string
+}
+
+interface DocsDirectory {
+  absolutePath: string
+  markdownFiles: MarkdownFile[]
+  name: string
+  relativePath: string
+  subdirectories: DocsDirectory[]
+}
+
+interface GeneratedIndex {
+  absolutePath: string
+  content: string
+  relativePath: string
+}
+
+interface LineLengthViolation {
+  lineCount: number
+  relativePath: string
+}
+
+interface FolderLink {
+  name: string
+  target: string
+  title: string
+}
+
+function renderFolderLink(folderLink: FolderLink): string {
+  return `[${escapeMarkdownLinkText(folderLink.title)}](${folderLink.target})`
+}
+
+function chunkItems<T>(items: T[], size: number): T[][] {
+  const chunks: T[][] = []
+
+  for (let index = 0; index < items.length; index += size) {
+    chunks.push(items.slice(index, index + size))
+  }
+
+  return chunks
+}
+
+function printUsage(): void {
+  console.log(`Generate and validate documentation indexes.
+
+Usage:
+  pnpm docs:index
+  pnpm docs:check
+  node --experimental-strip-types scripts/docs-index.ts [--write|--check]
+
+Options:
+  --write       Regenerate docs index files, then validate content line limits.
+  --check       Validate indexes are current and enforce content line limits.
+  --help, -h    Show this help text.
+`)
+}
+
+function parseArgs(argv: string[]): ScriptOptions {
+  const options: ScriptOptions = {
+    help: false,
+    mode: 'write',
+  }
+
+  for (const arg of argv) {
+    switch (arg) {
+      case '--write':
+        options.mode = 'write'
+        break
+      case '--check':
+        options.mode = 'check'
+        break
+      case '--help':
+      case '-h':
+        options.help = true
+        break
+      default:
+        throw new Error(`Unknown argument: ${arg}`)
+    }
+  }
+
+  return options
+}
+
+function isMarkdownFile(fileName: string): boolean {
+  return path.extname(fileName).toLowerCase() === MARKDOWN_EXTENSION
+}
+
+function isIndexFile(fileName: string): boolean {
+  return fileName.toLowerCase() === INDEX_FILE_NAME
+}
+
+function toPosixPath(filePath: string): string {
+  return filePath.split(path.sep).join('/')
+}
+
+function toMarkdownLinkTarget(filePath: string): string {
+  return toPosixPath(filePath).split('/').map(encodeURIComponent).join('/')
+}
+
+function countLines(content: string): number {
+  if (!content) {
+    return 0
+  }
+
+  const lines = content.split(LINE_BREAK_PATTERN)
+  if (content.endsWith('\n') || content.endsWith('\r')) {
+    return lines.length - 1
+  }
+
+  return lines.length
+}
+
+function titleCaseWord(word: string): string {
+  if (!word) {
+    return word
+  }
+
+  if (ACRONYMS.has(word.toLowerCase())) {
+    return word.toUpperCase()
+  }
+
+  return `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`
+}
+
+function titleFromPathSegment(segment: string): string {
+  return segment
+    .split(WORD_SEPARATOR_PATTERN)
+    .filter(Boolean)
+    .map(titleCaseWord)
+    .join(' ')
+}
+
+function fallbackTitleFromFileName(fileName: string): string {
+  return titleFromPathSegment(path.basename(fileName, MARKDOWN_EXTENSION))
+}
+
+function extractTitle(content: string, fileName: string): string {
+  const headingMatch = content.match(HEADING_PATTERN)
+  if (headingMatch?.[1]) {
+    return headingMatch[1].trim()
+  }
+
+  return fallbackTitleFromFileName(fileName)
+}
+
+function escapeMarkdownLinkText(text: string): string {
+  return text.replaceAll('[', '\\[').replaceAll(']', '\\]')
+}
+
+function compareByName(
+  left: { name: string },
+  right: { name: string }
+): number {
+  return left.name.localeCompare(right.name)
+}
+
+function compareByRelativePath(
+  left: { relativePath: string },
+  right: { relativePath: string }
+): number {
+  return left.relativePath.localeCompare(right.relativePath)
+}
+
+function nonIndexMarkdownFiles(directory: DocsDirectory): MarkdownFile[] {
+  return directory.markdownFiles.filter((file) => !isIndexFile(file.name))
+}
+
+function collectNonIndexMarkdownFiles(
+  directory: DocsDirectory
+): MarkdownFile[] {
+  const files: MarkdownFile[] = []
+
+  for (const file of nonIndexMarkdownFiles(directory)) {
+    files.push(file)
+  }
+
+  for (const subdirectory of directory.subdirectories) {
+    const subdirectoryFiles = collectNonIndexMarkdownFiles(subdirectory)
+    for (const file of subdirectoryFiles) {
+      files.push(file)
+    }
+  }
+
+  return files.sort(compareByRelativePath)
+}
+
+function shouldGenerateIndex(
+  directory: DocsDirectory,
+  docsRoot: string
+): boolean {
+  return (
+    directory.absolutePath === docsRoot ||
+    collectNonIndexMarkdownFiles(directory).length > 1
+  )
+}
+
+function resolveFolderLink(
+  directory: DocsDirectory,
+  subdirectory: DocsDirectory,
+  docsRoot: string
+): FolderLink | null {
+  const subdirectoryFiles = collectNonIndexMarkdownFiles(subdirectory)
+  if (subdirectoryFiles.length === 0) {
+    return null
+  }
+
+  const targetPath = shouldGenerateIndex(subdirectory, docsRoot)
+    ? path.join(subdirectory.absolutePath, INDEX_FILE_NAME)
+    : subdirectoryFiles[0].absolutePath
+
+  return {
+    name: subdirectory.name,
+    target: toMarkdownLinkTarget(
+      path.relative(directory.absolutePath, targetPath)
+    ),
+    title: titleFromPathSegment(subdirectory.name),
+  }
+}
+
+function collectFolderLinks(
+  directory: DocsDirectory,
+  docsRoot: string
+): FolderLink[] {
+  const folderLinks: FolderLink[] = []
+
+  for (const subdirectory of directory.subdirectories) {
+    const folderLink = resolveFolderLink(directory, subdirectory, docsRoot)
+    if (folderLink) {
+      folderLinks.push(folderLink)
+    }
+  }
+
+  return folderLinks.sort(compareByName)
+}
+
+function renderDirectoryTitle(directory: DocsDirectory): string {
+  if (!directory.relativePath) {
+    return 'Documentation Index'
+  }
+
+  return `${titleFromPathSegment(directory.name)} Index`
+}
+
+function renderIndex(directory: DocsDirectory, docsRoot: string): string {
+  const lines = [
+    GENERATED_NOTICE,
+    '',
+    `# ${renderDirectoryTitle(directory)}`,
+    '',
+  ]
+  const folderLinks = collectFolderLinks(directory, docsRoot)
+  const documents = nonIndexMarkdownFiles(directory).sort(compareByRelativePath)
+
+  if (folderLinks.length > 0) {
+    if (directory.relativePath) {
+      lines.push('## Folders', '')
+      for (const folderLink of folderLinks) {
+        lines.push(`- ${renderFolderLink(folderLink)}`)
+      }
+    } else {
+      for (const chunk of chunkItems(folderLinks, ROOT_LINKS_PER_LINE)) {
+        lines.push(`- ${chunk.map(renderFolderLink).join(' · ')}`)
+      }
+    }
+    lines.push('')
+  }
+
+  if (documents.length > 0) {
+    lines.push('## Documents', '')
+    for (const document of documents) {
+      lines.push(
+        `- [${escapeMarkdownLinkText(document.title)}](${toMarkdownLinkTarget(document.name)})`
+      )
+    }
+    lines.push('')
+  }
+
+  if (folderLinks.length === 0 && documents.length === 0) {
+    lines.push('No documents found.', '')
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`
+}
+
+async function readMarkdownFile(
+  absolutePath: string,
+  docsRoot: string,
+  name: string
+): Promise<MarkdownFile> {
+  const content = await readFile(absolutePath, 'utf8')
+  return {
+    absolutePath,
+    lineCount: countLines(content),
+    name,
+    relativePath: toPosixPath(path.relative(docsRoot, absolutePath)),
+    title: extractTitle(content, name),
+  }
+}
+
+async function readDocsDirectory(
+  absolutePath: string,
+  docsRoot: string
+): Promise<DocsDirectory> {
+  const entries = (await readdir(absolutePath, { withFileTypes: true })).sort(
+    compareByName
+  )
+  const markdownFileEntries = entries.filter(
+    (entry) => entry.isFile() && isMarkdownFile(entry.name)
+  )
+  const subdirectoryEntries = entries.filter((entry) => entry.isDirectory())
+  const markdownFiles = await Promise.all(
+    markdownFileEntries.map((entry) =>
+      readMarkdownFile(
+        path.join(absolutePath, entry.name),
+        docsRoot,
+        entry.name
+      )
+    )
+  )
+  const subdirectories = await Promise.all(
+    subdirectoryEntries.map((entry) =>
+      readDocsDirectory(path.join(absolutePath, entry.name), docsRoot)
+    )
+  )
+
+  return {
+    absolutePath,
+    markdownFiles,
+    name: path.basename(absolutePath),
+    relativePath: toPosixPath(path.relative(docsRoot, absolutePath)),
+    subdirectories,
+  }
+}
+
+function collectGeneratedIndexes(
+  directory: DocsDirectory,
+  docsRoot: string
+): GeneratedIndex[] {
+  const indexes: GeneratedIndex[] = []
+
+  if (shouldGenerateIndex(directory, docsRoot)) {
+    const absolutePath = path.join(directory.absolutePath, INDEX_FILE_NAME)
+    indexes.push({
+      absolutePath,
+      content: renderIndex(directory, docsRoot),
+      relativePath: toPosixPath(path.relative(docsRoot, absolutePath)),
+    })
+  }
+
+  for (const subdirectory of directory.subdirectories) {
+    const subdirectoryIndexes = collectGeneratedIndexes(subdirectory, docsRoot)
+    for (const index of subdirectoryIndexes) {
+      indexes.push(index)
+    }
+  }
+
+  return indexes.sort(compareByRelativePath)
+}
+
+function collectExistingLineLengthViolations(
+  directory: DocsDirectory
+): LineLengthViolation[] {
+  const violations: LineLengthViolation[] = []
+
+  for (const file of directory.markdownFiles) {
+    if (isIndexFile(file.name)) {
+      continue
+    }
+
+    if (file.lineCount > MAX_CONTENT_MARKDOWN_LINES) {
+      violations.push({
+        lineCount: file.lineCount,
+        relativePath: file.relativePath,
+      })
+    }
+  }
+
+  for (const subdirectory of directory.subdirectories) {
+    const subdirectoryViolations =
+      collectExistingLineLengthViolations(subdirectory)
+    for (const violation of subdirectoryViolations) {
+      violations.push(violation)
+    }
+  }
+
+  return violations.sort(compareByRelativePath)
+}
+
+function isNotFoundError(error: unknown): boolean {
+  if (!(error instanceof Error && 'code' in error)) {
+    return false
+  }
+
+  return error.code === 'ENOENT'
+}
+
+async function findOutdatedIndexes(
+  indexes: GeneratedIndex[]
+): Promise<GeneratedIndex[]> {
+  const outdatedIndexes: GeneratedIndex[] = []
+
+  for (const index of indexes) {
+    let currentContent = ''
+    try {
+      currentContent = await readFile(index.absolutePath, 'utf8')
+    } catch (error: unknown) {
+      if (!isNotFoundError(error)) {
+        throw error
+      }
+    }
+
+    if (currentContent !== index.content) {
+      outdatedIndexes.push(index)
+    }
+  }
+
+  return outdatedIndexes
+}
+
+async function writeIndexes(indexes: GeneratedIndex[]): Promise<void> {
+  for (const index of indexes) {
+    await writeFile(index.absolutePath, index.content, 'utf8')
+  }
+}
+
+function reportLineLengthViolations(violations: LineLengthViolation[]): void {
+  if (violations.length === 0) {
+    return
+  }
+
+  console.error(
+    `Non-index markdown files under docs must be ${MAX_CONTENT_MARKDOWN_LINES} lines or fewer.`
+  )
+  for (const violation of violations) {
+    console.error(
+      `- docs/${violation.relativePath}: ${violation.lineCount} lines`
+    )
+  }
+}
+
+function reportOutdatedIndexes(indexes: GeneratedIndex[]): void {
+  if (indexes.length === 0) {
+    return
+  }
+
+  console.error('Documentation indexes are out of date. Run `pnpm docs:index`.')
+  for (const index of indexes) {
+    console.error(`- docs/${index.relativePath}`)
+  }
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2))
+  if (options.help) {
+    printUsage()
+    return
+  }
+
+  const repoRoot = process.cwd()
+  const docsRoot = path.join(repoRoot, DOCS_DIRECTORY_NAME)
+  const docsDirectory = await readDocsDirectory(docsRoot, docsRoot)
+  const indexes = collectGeneratedIndexes(docsDirectory, docsRoot)
+  const lineLengthViolations =
+    collectExistingLineLengthViolations(docsDirectory)
+
+  if (options.mode === 'write') {
+    await writeIndexes(indexes)
+    console.log(`Generated ${indexes.length} documentation index file(s).`)
+  } else {
+    const outdatedIndexes = await findOutdatedIndexes(indexes)
+    reportOutdatedIndexes(outdatedIndexes)
+    if (outdatedIndexes.length > 0) {
+      process.exitCode = 1
+    }
+  }
+
+  reportLineLengthViolations(lineLengthViolations)
+  if (lineLengthViolations.length > 0) {
+    process.exitCode = 1
+  }
+}
+
+main().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`Failed: ${message}`)
+  process.exitCode = 1
+})