# for-agents INDEX

One-page jump table for the deep package + screen + flow guides. Read [`README.md`](./README.md) for layout + indexing; read [`conventions.md`](./conventions.md) for workspace-wide code conventions before editing any package. For assistant-discoverable screens/catalogs, use [`assistant-linkable-metadata.md`](./assistant-linkable-metadata.md). For broader internal onboarding, the generated package atlas, documentation map, and historical references, start at [`../internal/README.md`](../internal/README.md).

If a package you need isn't listed here, it doesn't exist yet — check `packages/` on disk before assuming.

## Packages (one doc each, six fixed sections)

### Contracts + foundation
- [os-core](./packages/os-core.md) — Zod schemas + event bus + error model (<25 KB gz).
- [os-contracts](./packages/os-contracts.md) — JSON-RPC contract registry + dispatcher.
- [os-log](./packages/os-log.md) — Logger + transports + structured fields.
- [os-capabilities](./packages/os-capabilities.md) — Abstract capability catalog for onboarding/vendor resolution.
- [os-control-plane](./packages/os-control-plane.md) — Pure control-plane context, entitlement, and policy resolvers.

### Runtime + flow
- [os-flow](./packages/os-flow.md) — DAG walker, HITL gates, run events.
- [os-runtime](./packages/os-runtime.md) — Handlers (agent/tool/human/condition/parallel), state machine, adapters.
- [os-runtime-agentskit](./packages/os-runtime-agentskit.md) — Adapter into the AgentsKit upstream provider/tools.
- [os-sandbox](./packages/os-sandbox.md) — Spawner + registry for code-exec sandboxes.
- [os-headless](./packages/os-headless.md) — Sidecar entrypoint + JSON-RPC transport.
- [os-cdc](./packages/os-cdc.md) — CDC trigger adapters, watermarks, and daemon primitives.
- [os-pipeline](./packages/os-pipeline.md) — Process/pipeline phase engine, approval gates, and bundles.

### Storage + observability
- [os-storage](./packages/os-storage.md) — SQLite + in-memory stores for every persistent surface.
- [os-audit](./packages/os-audit.md) — Append-only audit ledger.
- [os-observability](./packages/os-observability.md) — OTEL spans/metrics + incident model.
- [os-cost](./packages/os-cost.md) — Cost metering, budgets, spend policy, and alerts.
- [os-onboarding-telemetry](./packages/os-onboarding-telemetry.md) — Privacy-safe onboarding telemetry events.

### Security + collaboration
- [os-security](./packages/os-security.md) — Egress allowlist, RBAC, vault, firewall, PII.
- [os-collab](./packages/os-collab.md) — CRDT collab + sync gateway.
- [os-cloud-sync](./packages/os-cloud-sync.md) — Vault sync, share bundles, CRDT root.
- [os-license](./packages/os-license.md) — Envelope sign/verify + billing adapters.
- [os-tenant-config](./packages/os-tenant-config.md) — Tenant config + plan entitlements.
- [os-vault](./packages/os-vault.md) — Encrypted secret vault document, persistence, and backend dispatch.
- [os-oauth](./packages/os-oauth.md) — OAuth provider registry, PKCE lifecycle, tokens, and refresh scheduling.

### Knowledge + intelligence
- [os-rag](./packages/os-rag.md) — Loaders, embedder, reranker, vector store.
- [os-rag-adapters](./packages/os-rag-adapters.md) — Concrete RAG embedders, loaders, vector stores, and rerankers.
- [os-mcp-bridge](./packages/os-mcp-bridge.md) — MCP client manager.
- [os-copilot](./packages/os-copilot.md) — Copilot bootstrap + slash + mentions + session.
- [os-statechart](./packages/os-statechart.md) — Conversational state-machine primitive (assistant domain flows, ADR-0163).
- [os-coding-agents](./packages/os-coding-agents.md) — CLI coding-agent provider abstraction.
- [os-generative](./packages/os-generative.md) — Spec → flow draft generator.
- [os-command-palette](./packages/os-command-palette.md) — Cmd+K ranked search registry and handler factory.

### Workflow integrations
- [os-triggers](./packages/os-triggers.md) — Cron, webhook, CDC, file, integration triggers ([deep ref](./os-triggers.md)).
- [os-import](./packages/os-import.md) — LangChain/LangGraph/Flowise/Langflow/Dify/n8n importers.
- [os-marketplace](./packages/os-marketplace.md) — Bundle scanner, publish, install, signing.
- [os-dev-orchestrator](./packages/os-dev-orchestrator.md) — PRD→PR pipeline executor.
- [os-connectors](./packages/os-connectors.md) — Concrete outbound connection sender adapters.
- [os-integrations](./packages/os-integrations.md) — Upstream integration catalog projections into OS contracts.

### UI + product
- [os-ui](./packages/os-ui.md) — Reusable primitives (Button, Badge, Select, EmptyState, …).
- [os-desktop](./packages/os-desktop.md) — Facade/aggregate for the desktop-* cluster; hosts `App`, `hasTauri()`, telemetry sink.
- [os-notifications](./packages/os-notifications.md) — Notification store + routing + sidecar-event classifier + error-doc resolver (React glue at `/react`).
- [os-templates](./packages/os-templates.md) — Workspace templates + verticals.
- [os-whitelabel](./packages/os-whitelabel.md) — Brand kit + plan presets.
- [os-cli](./packages/os-cli.md) — `akos` (alias `agentskit-os`) terminal entry point; full cockpit command surface.
- [os-for-agents](./packages/os-for-agents.md) — In-app docs index for copilot retrieval.
- [os-oem](./packages/os-oem.md) — OEM tenants, brand kits, license verification, and domain packs.
- [os-flags-posthog](./packages/os-flags-posthog.md) — PostHog binding for feature flag evaluation.

### Desktop / web screen cluster (ADR-0108)

All `desktop-*` packages are framework-agnostic React. `apps/desktop` (Tauri) and `apps/console` (Vite browser host, ADR-0117) both render them — one screen codebase, two runtimes.

- [desktop-shell](./packages/desktop-shell.md) — App bootstrap: App root, AppShell, screens-registry, IoC wirers. Thin facade over os-desktop.
- [desktop-components](./packages/desktop-components.md) — Shared UI component layer wrapping os-ui primitives.
- [desktop-sidecar-bridge](./packages/desktop-sidecar-bridge.md) — Tauri JSON-RPC transport, sidecar request wrappers, Zustand stores, hooks (L2 binding, private).
- [desktop-platform-admin](./packages/desktop-platform-admin.md) — Dashboard, observe, traces, governance, compliance, security, oem, cost, pipelines, workspaces, break-glass, consent, config screens.
- [desktop-data-infra](./packages/desktop-data-infra.md) — Runs, assets, audit ledger, knowledge surfaces.
- [desktop-operations](./packages/desktop-operations.md) — Connections, marketplace, inbox, tools surfaces.
- [desktop-agent-workspace](./packages/desktop-agent-workspace.md) — Agents, coding, evals, copilot screens.
- [desktop-workflow-builder](./packages/desktop-workflow-builder.md) — FlowEditor, Flows, Triggers, Templates screens.
- [desktop-test-setup](./packages/desktop-test-setup.md) — Shared jsdom polyfills for desktop package tests.

#### Shared form components (`@agentskit/desktop-components`)

Cross-screen pickers used by the create/edit forms. Each is backed by a specific RPC or pure derivation. Every component doc includes a `## Human guide` pointing at the end-user screen that best explains where the control appears.

- [model-catalog-combobox](./components/model-catalog-combobox.md) — live 5244-model picker, server-side search via `models.catalog.list`.
- [catalog-combobox](./components/catalog-combobox.md) — generic listing-RPC typeahead with free-type fallback (secrets/flows/workspaces/connections).
- [file-path-input](./components/file-path-input.md) — native Tauri file/directory picker with browser `FileInput` fallback.
- [id-field](./components/id-field.md) — auto-generated slug ID preview + Advanced override (`autoGenerateId` / `useAutoId`).

#### Copilot inline render frames (`desktop-agent-workspace`)

Registered in `advisory-inline-components.tsx` and mirrored in
`packages/os-copilot/src/prompt.ts` (`RENDER_FRAME_GUIDE`).

- [tool-selection-step](./components/tool-selection-step.md) — onboarding tool/MCP picker (`ToolSelectionStep`).
- [configuration-plan-step](./components/configuration-plan-step.md) — per-tool setup plan after selection (`ConfigurationPlanStep`).

### Enterprise GA v1 — storage + infrastructure

- [os-store-postgres](./packages/os-store-postgres.md) — Postgres `RelationalDriver` + RLS migrations + `storeForOrg`.
- [os-rag-pgvector](./packages/os-rag-pgvector.md) — pgvector `VectorStore` with HNSW ANN index + org_id scoping.
- [os-sandbox-vercel](./packages/os-sandbox-vercel.md) — Vercel Firecracker µVM provider + caps-resolver + caps-enforcer + warm-pool + run-meter.
- [os-blob](./packages/os-blob.md) — `BlobStore` port re-export + `LocalFsDriver` (desktop/dev).
- [os-blob-s3](./packages/os-blob-s3.md) — AWS S3 `BlobStore` adapter + presigned URLs.
- [os-telemetry](./packages/os-telemetry.md) — Vendor-neutral OTel SDK wrapper + `initOtel` + `withScope`.
- [os-otel-grafana](./packages/os-otel-grafana.md) — Grafana Cloud OTLP exporter adapter.
- [os-email](./packages/os-email.md) — `EmailSender` port + template registry + console dev sink.
- [os-email-resend](./packages/os-email-resend.md) — Resend + React Email adapter.
- [os-pdf](./packages/os-pdf.md) — `PdfRenderer` port + `PdfDocument` tree + pdfkit adapter.
- [os-errors](./packages/os-errors.md) — `ErrorReporter` port + no-op / console / `RedactingReporter`.
- [os-errors-sentry](./packages/os-errors-sentry.md) — Sentry `ErrorReporter` adapter (PII-safe).
- [os-sealer-vault](./packages/os-sealer-vault.md) — HashiCorp Vault Transit `AsyncKeyRingSealer`.
- [os-egress-guard](./packages/os-egress-guard.md) — Per-org egress policy + hosted enforcer.
- [os-bot-signal](./packages/os-bot-signal.md) — `BotSignalPort` (bot/IP-reputation) + no-op adapter; vendor pluggable later.

### Contracts + structured outputs
- [agent-contracts](./packages/agent-contracts.md) — Versioned registry of Zod schemas for structured agent outputs.

### Vertical packs
- [pack-loader](./packages/pack-loader.md) — Runtime YAML parsing, schema validation, and materialisation of packs into sidecar stores.
- [os-vertical-store](./packages/os-vertical-store.md) — The one adapter bridging os-storage's vertical row store to os-whitelabel's typed registry port; shared by the sidecar and OEM admin.
- [pack-fixtures-reference](./packages/pack-fixtures-reference.md) — Reference YAML fixture packs for 5 verticals (coding, finance, healthcare, law, marketing). Data-only.
- [pkw-test-fixtures](./packages/pkw-test-fixtures.md) — Dev-only fixtures for pipeline/workflow confidence tests.

## Screens (desktop renderer)

- [agents](./screens/agents.md) · [assets](./screens/assets.md) · [audit](./screens/audit.md) · [break-glass](./screens/break-glass.md) · [bundles](./screens/bundles.md) · [coding](./screens/coding.md) · [compliance](./screens/compliance.md) · [config](./screens/config.md) · [connections](./screens/connections.md) · [copilot](./screens/copilot.md) · [cost](./screens/cost.md) · [dashboard](./screens/dashboard.md) · [evals](./screens/evals.md) · [flow-editor](./screens/flow-editor.md) · [flows](./screens/flows.md) · [governance](./screens/governance.md) · [inbox](./screens/inbox.md) · [knowledge](./screens/knowledge.md) · [marketplace](./screens/marketplace.md) · [mcp](./screens/mcp.md) · [observability](./screens/observability.md) · [observe](./screens/observe.md) · [oem](./screens/oem.md) · [pipelines-board](./screens/pipelines-board.md) · [plugins](./screens/plugins.md) · [runs](./screens/runs.md) · [sandbox](./screens/sandbox.md) · [sdlc](./screens/sdlc.md) · [security](./screens/security.md) · [teams](./screens/teams.md) · [templates](./screens/templates.md) · [tools](./screens/tools.md) · [topologies](./screens/topologies.md) · [traces](./screens/traces.md) · [triggers](./screens/triggers.md) · [whitelabel](./screens/whitelabel.md) · [workspaces](./screens/workspaces.md)

### Admin screens (Enterprise GA v1 — `apps/admin/`)

Overview: [admin-app](./screens/admin-app.md) — OEM control plane entry, nav groups, `surface-registry.ts`.

- [admin-dashboard](./screens/admin-dashboard.md) · [admin-tenants](./screens/admin-tenants.md) · [admin-tenant-detail](./screens/admin-tenant-detail.md) · [admin-catalogs](./screens/admin-catalogs.md) · [admin-onboarding](./screens/admin-onboarding.md) · [admin-onboarding-insights](./screens/admin-onboarding-insights.md) · [admin-license](./screens/admin-license.md) · [admin-members](./screens/admin-members.md) · [admin-brand](./screens/admin-brand.md) · [admin-whitelabel](./screens/admin-whitelabel.md) · [admin-verticals](./screens/admin-verticals.md) · [admin-pages-rbac](./screens/admin-pages-rbac.md) · [admin-rbac](./screens/admin-rbac.md) · [admin-governance](./screens/admin-governance.md) · [admin-distribution](./screens/admin-distribution.md) · [admin-audit](./screens/admin-audit.md) · [admin-compliance](./screens/admin-compliance.md) · [admin-compliance-telemetry](./screens/admin-compliance-telemetry.md) · [admin-scim-oversight](./screens/admin-scim-oversight.md) · [admin-billing-oversight](./screens/admin-billing-oversight.md) · [admin-preview-as](./screens/admin-preview-as.md) · [admin-sign-in](./screens/admin-sign-in.md)

## Apps (deployable surfaces)

Six deliverables under `apps/`. Each consumes packages but is not itself a published package — no for-agents doc; edits go straight in `apps/<name>/`.

| App | Path | Purpose |
|---|---|---|
| **admin** | `apps/admin/` | OEM tenancy console (whitelabel admins manage their tenants). |
| **console** | `apps/console/` | Vite + React 19 web console (ADR-0117). Mounts the *same* desktop app shell (`App` from `desktop-shell`/`os-desktop`) in the browser — no Tauri runtime, so the shared `sidecarRequest` transport resolves to the headless HTTP path (`/api/rpc`, overridable via `VITE_SIDECAR_URL`); `WEB_HOST_CAPABILITIES` hides desktop-only affordances via the `HostCapabilities` seam. The desktop UI is the single source of truth. |
| **cloud** | `apps/cloud/` | Control-plane HTTP server (vault, share bundles, sync gateway, license issuance bridge). Tenant-mutating routes derive `orgId` from a verified session via `resolveAuthContext` (api/request-context.ts, ENT-2 #1711) — never from request body; prod fails closed without `opts.auth`. Cloud-wide abuse controls via `api/rate-limit-middleware.ts` (ENT-4) — see `apps/cloud/README.md#abuse-controls-ent-4`. |
| **desktop** | `apps/desktop/` | Tauri shell that hosts the `os-desktop` renderer + spawns the headless sidecar. |
| **license-service** | `apps/license-service/` | Issues + verifies signed license envelopes for offline-capable installs. Admin routes use scoped, rotatable, expiring tokens with structured audit (#1712 — see app README). |
| **web** | `apps/web/` | Public marketing/docs plus authenticated multi-tenant web entry (`app.agentskit.io`, `*.app.agentskit.io`). Uses shared desktop/console surfaces where applicable; host/tenant parsing consumes `os-core` tenancy contracts and identity decisions come from cloud/control-plane, not UI state. |

Web deploy safety: use [`../web/authenticated-app-deploy-checklist.md`](../web/authenticated-app-deploy-checklist.md)
before promoting the authenticated app. `akos.agentskit.io` stays public
marketing/docs; `app.agentskit.io` and `*.app.agentskit.io` are the product app.
Use [`../web/runtime-modes.md`](../web/runtime-modes.md) before treating
Vite/5173 standalone, desktop local, hosted web, or self-host evidence as
equivalent.

## Flow recipes

All 14 flows map a `humanDoc` path in `pnpm docs:internal:query flow <id> --agent`.

- [prd-to-pr](./flows/prd-to-pr.md) — Killer demo: PRD bundle → drafted PR with HITL gate. Human: [`pipelines.mdx`](../../apps/web/content/docs/using-the-app/pipelines.mdx).
- [eval-suite](./flows/eval-suite.md) — Run an eval suite end-to-end. Human: [`evals.mdx`](../../apps/web/content/docs/using-the-app/evals.mdx).
- [trigger-to-run](./flows/trigger-to-run.md) — Webhook/cron → run dispatch. Human: [`triggers.mdx`](../../apps/web/content/docs/using-the-app/triggers.mdx).
- [install-marketplace-plugin](./flows/install-marketplace-plugin.md) — Marketplace install pipeline. Human: [`templates-and-marketplace.mdx`](../../apps/web/content/docs/using-the-app/templates-and-marketplace.mdx).
- [integration-setup-assistant](./flows/integration-setup-assistant.md) — Assistant-guided OAuth/app-install/secret setup. Human: [`integration-setup.mdx`](../../apps/web/content/docs/using-the-app/integration-setup.mdx).
- [public-automation-api](./flows/public-automation-api.md) — External webhooks/API keys → workflow dispatch. Human: [`public-automation-api.mdx`](../../apps/web/content/docs/using-the-app/public-automation-api.mdx).
- [assistant-knowledge-seed](./flows/assistant-knowledge-seed.md) — Ledger + rebuild path for assistant RAG. Human: [`knowledge.mdx`](../../apps/web/content/docs/using-the-app/knowledge.mdx).
- [control-plane-resolve](./flows/control-plane-resolve.md) — Canonical `ControlPlaneContext` before mutating work. Human: [`architecture-overview.md`](../enterprise-final/architecture-overview.md).

### Enterprise GA v1 cross-cutting flows

- [storage-migration](./flows/storage-migration.md) — Local SQLiteFs → cloud Postgres + S3. Human: [`migrating.mdx`](../../apps/web/content/docs/cli/migrating.mdx).
- [brand-publish](./flows/brand-publish.md) — Admin whitelabel editor → 4 sinks → web hot-load ≤ 60 s. Human: [`apps/admin/README.md`](../../apps/admin/README.md).
- [license-lifecycle](./flows/license-lifecycle.md) — Stripe checkout → provisioning → renewal → revoke. Human: [`renewal.md`](../enterprise-final/renewal.md).
- [dr-rehearsal](./flows/dr-rehearsal.md) — Quarterly DR drill. Human: [`runbook-dr.md`](../enterprise-final/runbook-dr.md).
- [hosted-sandbox-run](./flows/hosted-sandbox-run.md) — Vercel sandbox run + metering. Human: [`run-lifecycle.mdx`](../../apps/web/content/docs/how-it-works/run-lifecycle.mdx).
- [customer-onboarding](./flows/customer-onboarding.md) — Marketing CTA → first run → audit. Human: [`customer-onboarding-walkthrough.md`](../enterprise-final/customer-onboarding-walkthrough.md).

## Operations

- [backup-dr](./backup-dr.md) — full-state backup, encryption, offsite, restore drill (ENT-5 #1714).
- [ecosystem-maintenance](./ecosystem-maintenance.md) — CI/script inventory, cross-cutting ownership map, stale-doc rule, and package-addition checklist.

## Anchor files (outside this directory)

- [`../../AGENTS.md`](../../AGENTS.md) — package routing table (start here when you don't know which package to touch).
- [`../internal/README.md`](../internal/README.md) — generated internal docs hub, package atlas, docs map, DevEx guide, architecture map, and historical index.
- [`../content-catalog.generated.md`](../content-catalog.generated.md) — generated catalog of every tracked Markdown, MDX, and HTML documentation file.
- [`../../CLAUDE.md`](../../CLAUDE.md) — non-negotiables mirror.
- [`../../MANIFESTO.md`](../../MANIFESTO.md) — philosophy + the four rules.
- [`../adr/`](../adr/) — accepted architecture decisions; source of truth.
- [`../rfc/`](../rfc/) — in-flight RFCs.

## When to read what

| Task | Read first |
|---|---|
| Map a change to a package | [`../../AGENTS.md`](../../AGENTS.md) → routing table |
| Find any doc (agent or human) | `pnpm docs:internal:query search <term> --agent` → `screen` / `flow` / `component` / `package` handoff |
| Write code for a specific package | this INDEX → that package's `for-agents` doc |
| Touch a desktop screen | `pnpm docs:internal:query screen <id> --agent` or this INDEX → screen doc |
| End-user guide for a screen | `apps/web/content/docs/using-the-app/<screen>.mdx` (indexed when assistant-knowledge is seeded) |
| Reuse a workflow recipe | `pnpm docs:internal:query flow <id> --agent` or flows section above |
| End-user guide for a flow | All 14 flows return `humanDoc` in `flow --agent` handoff (see flows section above) |
| Touch a shared form component | `pnpm docs:internal:query component <id> --agent` or components section above |
| Add a new method / contract | [os-contracts](./packages/os-contracts.md) + the consumer package's doc |
| Add a new schema or error code | [os-core](./packages/os-core.md) |
| Persist new state | [os-storage](./packages/os-storage.md) |
| Backup / restore / DR | [backup-dr](./backup-dr.md) |
| Anything cross-cutting | [`conventions.md`](./conventions.md) |