# AgentsKit OS — full machine-readable corpus

> Operating system for AI agents in production. Parent brand: AgentsKit.

## Public documentation

### cli/agents.mdx

---
title: Agents
description: Register, list, version, promote, and compare agents from the command line.
---

The AKOS CLI gives you full lifecycle control over agents in your workspace: register them in the registry, move them through lifecycle states with audit trails, generate drafts from plain English descriptions, and compare evaluation results across variants.

## Registering an agent

```bash
akos agent register \
  --id summarizer \
  --owner alice@example.com \
  --purpose "Summarizes incoming emails and posts to Slack"
```

Required flags:

| Flag | Description |
|---|---|
| `--id <slug>` | Agent identifier (lowercase, hyphen-separated) |
| `--owner <id>` | Responsible owner — email address or handle |
| `--purpose <text>` | Short description of what the agent does |

Optional flags:

| Flag | Description |
|---|---|
| `--state <s>` | Initial lifecycle state (default: `draft`) |
| `--risk <t>` | Risk tier (default: `low`) |
| `--workspace-root <path>` | Override workspace runtime root |

**Lifecycle states:** `draft`, `review`, `approved`, `staged`, `production`, `deprecated`, `retired`

**Risk tiers:** `low`, `medium`, `high`, `critical`

## Listing registered agents

```bash
akos agent list
```

Outputs each agent's ID, lifecycle state, risk tier, and owner. Add `--json` for machine-readable output.

```bash
akos agent list --json
```

## Generating an agent from a description

To generate a starter agent configuration from a plain-English description:

```bash
akos agent from-nl "Summarize Slack DMs daily and post a digest"
```

The command infers the agent's intent (verb, cadence, confidence) and outputs a YAML draft ready to paste into your workspace config.

Save directly to a file:

```bash
akos agent from-nl "Monitor GitHub issues and triage by label" \
  --out agents/issue-triage.yaml
```

Output as JSON instead of YAML:

```bash
akos agent from-nl "Send weekly report to Notion" --format json
```

## Promoting an agent through the lifecycle

`agent promote` validates a lifecycle transition against the AKOS governance graph and emits an audit event. It does not modify the registry by default (dry-run mode).

```bash
akos agent promote \
  --agent-id summarizer \
  --from draft \
  --to review \
  --actor alice@example.com
```

To commit the transition to the registry (update state and append the audit event):

```bash
akos agent promote \
  --agent-id summarizer \
  --from review \
  --to approved \
  --actor alice@example.com \
  --check code_review \
  --check security_scan \
  --commit
```

### Promote options

| Flag | Description |
|---|---|
| `--from <state>` | Current lifecycle state (required) |
| `--to <state>` | Target lifecycle state (required) |
| `--agent-id <slug>` | Agent identifier (default: `unknown`) |
| `--actor <id>` | Principal authorizing the transition |
| `--risk <tier>` | Risk tier (default: `low`) |
| `--check <name>` | Satisfied governance gate (repeatable) |
| `--reason <text>` | Free-form reason recorded in the audit event |
| `--json` | Emit the audit event as JSON |
| `--commit` | Persist the transition to the registry |

If a transition is blocked by unsatisfied gates, the CLI prints which checks are missing and exits non-zero.

## Viewing agent version history

```bash
akos agent version-list --id summarizer
```

Prints the recorded version history for an agent. Add `--json` for structured output.

## Comparing agent variants

Use `agent compare` to rank multiple agent variants by pass rate, cost, and latency from a saved evaluation run.

First, prepare a JSON file containing evaluation results for each variant:

```json
[
  { "id": "variant-a", "passRate": 0.92, "meanCostUsd": 0.004, "meanLatencyMs": 820 },
  { "id": "variant-b", "passRate": 0.88, "meanCostUsd": 0.002, "meanLatencyMs": 510 }
]
```

Then run the comparison:

```bash
akos agent compare evaluations.json
```

The CLI prints a ranked table and the overall winner. Adjust scoring weights to match your priorities:

```bash
akos agent compare evaluations.json \
  --pass 0.7 \
  --cost 0.1 \
  --latency 0.2
```

Default weights: pass rate 0.6, cost 0.2, latency 0.2. Weights do not need to sum to 1.

Output as JSON:

```bash
akos agent compare evaluations.json --json
```

## Viewing the agent changelog

```bash
akos agent changelog --agent-id summarizer
```

Prints the recorded change events for an agent. Add `--json` for structured output.

## Related topics

- **[Agents in the app](/docs/using-the-app/agents)** — registry UI, lifecycle promotion, sandbox test.
- **[Model catalog](/docs/using-the-app/model-catalog)** — choosing models in agent forms.
- **[Quality checks (Evals)](/docs/using-the-app/evals)** — regression suites that gate promotions.
- **[Flows and Runs](/docs/cli/flows-and-runs)** — run agents inside workflow graphs.

Source: /raw/cli/agents.mdx

### cli/authentication.mdx

---
title: Authentication
description: Log in to your AKOS workspace, manage provider credentials, store secrets in the vault, and provision integration connections.
---

The CLI authenticates to your AKOS workspace via a device-code OAuth flow. Once logged in, provider credentials and secrets are managed separately through the `creds`, `vault`, `secrets`, and `connections` commands.

## Logging in

```bash
akos auth login
```

This starts a device-code flow:

1. The CLI prints a verification URL and a short user code.
2. Open the URL in a browser and enter the code.
3. After approval, the CLI saves your session token locally and prints `Logged in as <userId>`.

### Login options

| Flag | Description |
|---|---|
| `--scope <scope>` | OAuth scope (default: `cli`) |
| `--client-id <id>` | Override the OAuth client ID |

### CI environments

If the environment variable `AKOS_TOKEN` is already set, `auth login` exits immediately with a success message. Use this for non-interactive pipelines.

## Checking your session

```bash
akos auth whoami
```

Prints `Logged in as <userId> on tenant <tenantId>` and confirms the workspace is reachable. Add `--json` for machine-readable output.

## Switching tenants

When your account belongs to multiple tenants (OEM multi-tenancy), use the `tenant` commands to list and switch:

```bash
akos tenant list
```

Lists all tenants your account can access. If you do not have the `oem:tenant:admin` role, the command falls back to reporting the current tenant.

```bash
akos tenant use <tenant-id>
```

In local/self-host mode, this persists the tenant ID to your local session for subsequent sidecar calls. In hosted/cloud mode, tenant switching is server-side; re-login or use the hosted tenant switch flow so token claims and tenant isolation stay aligned.

## Logging out

```bash
akos auth logout
```

Clears the locally stored session token. Safe to call when no session exists (idempotent).

## Managing provider credentials

The `creds` command lists, verifies, and stores the API keys required by AI providers and integrations. Values are never printed.

### List known providers

```bash
akos creds list
```

Shows each provider, its kind, and the vault keys it requires.

Filter by kind or provider:

```bash
akos creds list --kind llm
akos creds list --provider anthropic
```

Output as JSON:

```bash
akos creds list --json
```

### Check credential presence

```bash
akos creds check
```

Scans the environment (and optionally a secrets file) for each required key. Exits with code 0 when all keys are present, code 7 when any are missing.

```bash
# Check against a local dotenv-style file (key names only — values never shown)
akos creds check --secrets-file .env.local

# Skip cloud providers (air-gapped workspace)
akos creds check --air-gap

# Restrict to a specific provider
akos creds check --provider openai
```

### Set a credential

```bash
akos creds set
```

Interactive guided flow for storing a credential. Follows the same vault backend as `vault put`.

### Onboarding guide

Print the full credential onboarding playbook:

```bash
akos creds guide
```

## Vault: workspace secrets

The `vault` command reads and writes secrets in the workspace vault. Secret **values are never printed** — only key names and their source are shown.

### Store a secret

```bash
akos vault put OPENAI_API_KEY sk-...
```

Scope the secret to a tenant instead of the workspace:

```bash
akos vault put STRIPE_SECRET_KEY sk_live_... --scope tenant
```

Scopes: `workspace` (default), `tenant`.

### List stored secrets

```bash
akos vault list
```

Shows key names and their source (e.g. `os-keychain`). Add `--json` for machine-readable output.

## Secrets: headless provisioning

The `secrets` command is a headless alternative to `vault`, operating through the running workspace sidecar. Use it when scripting in environments where the sidecar is already running.

```bash
# Store a secret
akos secrets set GITHUB_TOKEN ghp_...

# List stored keys (values hidden)
akos secrets list

# Filter output as JSON
akos secrets list --json
```

Scope options (`--scope workspace|tenant`) work the same as `vault put`.

## Integration connections

Integration connections link your workspace to external services (Slack, GitHub, Stripe, and others). Authentication always references a vault key — never a plaintext token.

### Provision a connection

First, store the credential in the vault:

```bash
akos vault put SLACK_BOT_TOKEN xoxb-...
```

Then create the connection, referencing the vault key:

```bash
akos connections set \
  --id slack-main \
  --kind slack \
  --label "Main Slack workspace" \
  --secret-id SLACK_BOT_TOKEN
```

For integrations that require no auth:

```bash
akos connections set \
  --id public-webhook \
  --kind webhook \
  --label "Inbound webhook" \
  --no-auth
```

Supported kinds: `slack`, `github`, `linear`, `discord`, `email`, `cron`, `file`, `webhook`, `cdc`, `twilio`, `sentry`, `pagerduty`, `stripe`, `s3`, `mcp`, `llm`.

### List connections

```bash
akos connections list

# Filter by kind
akos connections list --kind slack

# JSON output
akos connections list --json
```

### Inspect a connection

```bash
akos connections get slack-main
```

### Remove a connection

```bash
akos connections rm slack-main
```

Removing a connection does not delete the underlying vault secret.

## Related topics

- **[Connections (CLI)](/docs/cli/connections)** — `connections guide`, provision, and `connectors test`.
- **[Connections in the app](/docs/using-the-app/connections)** — OAuth cards, external secrets, SQL, cloud sync.
- **[Integration setup](/docs/using-the-app/integration-setup)** — registry-backed setup guides for providers.
- **[CLI index](/docs/cli)** — `doctor`, shell completion, and CI token patterns.

Source: /raw/cli/authentication.mdx

### cli/chat.mdx

---
title: Chat and Interactive Shell
description: Talk to the workspace copilot from the terminal — one-shot messages, readline shell, full-screen TUI, and slash commands.
---

The `chat` command is the terminal face of the same assistant that powers **[Home (Assistant)](/docs/using-the-app/copilot)** in the app. It calls `copilot.session.*` on the sidecar — authenticate first, then ensure the sidecar is reachable (`akos serve` locally or `AKOS_HEADLESS_URL`).

## One-shot message

Send a single prompt and wait for the reply (default timeout 30 s):

```bash
akos chat "summarize today's failed runs"
akos chat "draft a cron trigger for nightly backups"
```

Continue an existing session:

```bash
akos chat --session sess_abc "now add error handling to that flow"
```

Stream tokens as they arrive (ADR-0133 polling stream):

```bash
akos chat --stream "explain our egress policy"
```

Enqueue without waiting for the assistant to finish:

```bash
akos chat --no-wait "start a long research task"
akos chat sessions
akos chat show sess_abc --json
```

### Options

| Flag | Description |
|---|---|
| `--session <id>` | Continue an existing copilot session |
| `--workspace <id>` | Workspace for newly created sessions |
| `--principal <id>` | Principal id (default: `cli`) |
| `--role <role>` | `orchestrator`, `chat`, `coder`, `reviewer`, or `embedder` |
| `--stream` | Print assistant tokens incrementally |
| `--no-wait` | Return after the message is enqueued |
| `--timeout-ms <ms>` | Max wait for a final reply (default: `30000`) |
| `--poll-ms <ms>` | Poll interval while waiting (default: `500`) |
| `--json` | Emit raw session/send envelopes |

## Interactive readline shell

Open the portable slash-command shell (also used when you run `akos` with no args on a TTY):

```bash
akos chat --interactive
# shorthand:
akos chat -i
```

Type natural language or slash commands (`/help`, `/flows`, `/inbox`, …). Lists remember the last result so you can select by number (`/run-flow 2`, `/approve 1`).

## Full-screen TUI

For the Ink-based terminal UI (transcript pane, themes, governance badges, proposal cards):

```bash
akos chat --tui
```

Requires a real TTY. Without one, the CLI exits with a hint to use `--interactive` or a one-shot message.

### TUI highlights

- **Themes** — `/theme ocean|grape|forest|ember|mono|midnight|sunset|nord`; persisted in `~/.akos/tui.json`. `NO_COLOR` forces monochrome.
- **Editing** — readline chords (`Ctrl+A/E`, `Ctrl+W`, `Ctrl+U/K/Y`), `↑`/`↓` history, `Tab` completes `/commands` and `@mentions`.
- **Keybindings** — optional overrides in `~/.akos/keys.json` (approve, cancel, scroll).
- **Governance** — header badges for pending HITL and in-flight runs; `Ctrl+G` approves the next gate inline.
- **Proposals** — assistant flow/agent proposals render as cards; `/apply <n>` materializes the chosen proposal.
- **Resume** — transcripts reload from the sidecar when switching sessions (`/sessions` picker in TUI).
- **Offline** — unreachable sidecar shows a banner; the CLI can auto-start a local sidecar on first use.

## Slash command cheat sheet

| Slash | Action |
|---|---|
| `/help` | List slash commands |
| `/workspaces`, `/workspace <id\|n>` | List / switch workspace |
| `/sessions`, `/use <id\|n>`, `/new` | List / switch / create chat session |
| `/flows`, `/flow <id\|n>`, `/run-flow <id\|n>` | List / show / run a flow |
| `/agents`, `/agent <id\|n>` | List / show an agent |
| `/inbox`, `/approve <id\|n>`, `/reject <id\|n>` | HITL queue |
| `/runs`, `/run <id\|n>`, `/watch <id\|n>`, `/logs <id\|n>` | Run inspection |
| `/connect …` | Provider setup / OAuth completion |
| `/apply <n>` | Approve the n-th assistant proposal |
| `/export [path]` | Save conversation to markdown |
| `/quit` | Exit (`Ctrl-C` / `Ctrl-D` also work) |

Full table (including `/verticals`, `/theme`, `/cost`, …): **[Command reference](/docs/cli/command-reference)** › Interactive shell.

## Session management

```bash
akos chat sessions --json
akos chat show sess_abc
akos chat cancel sess_abc      # stop an in-progress turn
akos chat delete sess_abc     # remove session + transcript
```

## Scripting copilot primitives

For automation that parses slash commands or builds proactive cards without the interactive shell:

```bash
akos copilot slash list
akos copilot slash parse "/run-flow nightly-backup"
akos copilot mention parse "ask @billing about limits"
akos copilot proactive '{"kind":"run.failed","runId":"run_1"}' --json
```

Registry-backed integration setup steps also surface in chat — see **[Connections](/docs/cli/connections)** (`connections guide`) and **[Integration setup](/docs/using-the-app/integration-setup)**.

## Related topics

- **[Home (Assistant)](/docs/using-the-app/copilot)** — same copilot in the browser/desktop UI.
- **[Flows and Runs](/docs/cli/flows-and-runs)** — `/run-flow` and scriptable `flows run`.
- **[Connections](/docs/cli/connections)** — `/connect` and OAuth completion from the shell.
- **[Knowledge and RAG](/docs/cli/knowledge-and-rag)** — `/knowledge` and indexed docs for retrieval.
- **[Command reference](/docs/cli/command-reference)** — streaming, exit codes, non-TTY usage.

Source: /raw/cli/chat.mdx

### cli/command-reference.mdx

---
title: Command Reference
description: A concise table of every top-level akos command with a one-line description.
---

All commands accept `--help` for detailed usage. Commands marked with a sidecar requirement need `akos serve` to be running (or `AKOS_HEADLESS_URL` pointing at a remote sidecar).

**Topic walkthroughs** (examples and operator loops): [Authentication](/docs/cli/authentication) · [Connections](/docs/cli/connections) · [Agents](/docs/cli/agents) · [Flows and Runs](/docs/cli/flows-and-runs) · [Processes](/docs/cli/pipelines) · [Triggers](/docs/cli/triggers) · [Knowledge and RAG](/docs/cli/knowledge-and-rag) · [Security and Governance](/docs/cli/security-governance) · [Costs and Observability](/docs/cli/costs-observability) · [Chat](/docs/cli/chat) · [Configuration](/docs/cli/configuration) · [Migrating](/docs/cli/migrating) · [Deploying](/docs/cli/deploying).

## Core workspace

| Command | Description |
|---|---|
| `init [dir]` | Scaffold a new AKOS workspace (config, `.agentskitos/`, `.gitignore`) |
| `init-ci` | Scaffold GitHub Actions CI templates for an AKOS project |
| `wizard` | Interactive first-run template wizard |
| `new [template-id]` | Scaffold a workspace from a starter template (`--list` to browse) |
| `doctor` | Diagnose the CLI environment: Node version, platform, credentials, connectivity |
| `status` | Show sidecar connection, active workspace, auth state, recent runs/triggers/anomalies |
| `workspaces list` | List sidecar workspaces and mark the active one (requires sidecar) |
| `workspaces use <id>` | Switch the active workspace (requires sidecar) |
| `workspaces create <id>` | Create a workspace; idempotent on id (requires sidecar) |
| `workspaces delete <id>` | Delete a workspace; rejects the active one. Requires `--confirm` in non-TTY (requires sidecar) |
| `workspaces clone <new-id>` | Clone the active workspace into a new id (requires sidecar) |
| `upgrade` | Check for a newer CLI version and print the upgrade command |
| `completion <shell>` | Emit a shell completion script (`bash`, `zsh`, `fish`) |
| `version` | Print the installed CLI version |

## Authentication and credentials

| Command | Description |
|---|---|
| `auth login` | Sign in via device-code OAuth and persist a session token |
| `auth logout` | Clear the persisted session token |
| `auth whoami` | Print the active session identity (requires sidecar) |
| `auth status` | Show the current auth session state |
| `tenant list` | List accessible tenants (requires `oem:tenant:admin`; falls back to current tenant) |
| `tenant use <id>` | Switch the active tenant locally; hosted/cloud switching is server-side |
| `creds list` | List known providers and their required vault keys |
| `creds check` | Verify that required credential keys are present (values never shown) |
| `creds set` | Interactively store a provider credential |
| `creds guide` | Print the guided credential onboarding playbook |
| `vault list` | List workspace secret keys stored in the vault (values hidden) |
| `vault put <key> <value>` | Write a secret to the workspace vault |
| `secrets list` | List provisioned secret keys via the sidecar (values hidden) |
| `secrets set <key> <value>` | Provision a secret headless via the sidecar |
| `connections list` | List provisioned integration connections |
| `connections get <id>` | Read a single integration connection |
| `connections guide [providerId]` | Print setup guidance from the integration registry (`--category`, `--implemented-only`) |
| `connections sql-get <id>` | Read a single SQL connection (`--json`) |
| `connections set` | Provision (create or replace) an integration connection |
| `connections rm <id>` | Remove an integration connection |

## Agents

| Command | Description |
|---|---|
| `agents list` | List inline agents from the sidecar (`--json`) |
| `agents show <id>` | Show a single inline agent (`--json`) |
| `agents run <id>` | Invoke an agent now (`--input`, `--mode`, requires `--confirm` in non-TTY) |
| `agent register` | Persist a new agent registry entry (local registry) |
| `agent list` | List agents in the local workspace registry |
| `agent from-nl <description>` | Generate an agent draft from a natural-language description |
| `agent promote` | Validate a lifecycle transition and emit an audit event |
| `agent version-list` | View the version history for an agent (`--id`, `--json`) |
| `agent bump` | Mint a new agent version (auto-suggest, manual confirm) |
| `agent diff` | Diff two agent versions (defaults to last two) |
| `agent compare <evaluations.json>` | Rank agent variants by pass rate, cost, and latency |
| `agent changelog` | View the change event history for an agent |

## Flows and runs

| Command | Description |
|---|---|
| `flow new [template-id]` | Scaffold a flow from a built-in template into a workspace config |
| `flow export <id>` | Export a flow as a portable `FlowEnvelope` JSON |
| `flow import-json <file>` | Import a `FlowEnvelope` JSON into an existing config |
| `flows list` | List inline flows in the active workspace (`--json`) |
| `flows show <id>` | Show a single inline flow (`--json`) |
| `flows validate <id>` | Validate an inline flow against the `FlowConfig` schema |
| `flows run <id>` | Run an inline flow now (`--mode`, requires `--confirm` in non-TTY) |
| `flows edit <id>` | Edit an inline flow in `$EDITOR`; validates before applying (TTY only) |
| `run [configPath]` | Execute (or resume) a flow (default mode: `dry_run`) |
| `runs list` | List recent flow runs (`--workspace`, `--status`, `--limit`, `--json`) |
| `runs get <id>` | Fetch a single run row via the sidecar (`runs.get`; null when missing) (`--json`) |
| `runs show <id>` | Enriched run detail: status, flow, timings, cost/tokens, counts, recent events (`--json`) |
| `runs watch <id>` | Follow one run's status/detail until completion (`--once`, `--json`) |
| `runs cancel <id>` | Cancel an in-flight run (requires `--confirm` in non-TTY) |
| `runs retry <id>` | Re-dispatch the flow behind a run (`--mode`, requires `--confirm` in non-TTY) |
| `runs logs <id>` | Print the span/tool event timeline of a run (`--json`) |
| `runs artifacts <id>` | List artifacts produced by a run (`--limit`, `--json`) |
| `explain` | Explain a coding run from its persisted artifact bundle |
| `whatif <runs.json>` | Project cost/latency/pass-rate impact of a hypothetical change |
| `inbox list` | List pending HITL approvals (`--status`, `--json`) |
| `inbox show <id>` | Show full approval context + risk notes (`--json`) |
| `inbox approve <id>` | Approve a pending approval (`--note`, requires `--confirm` in non-TTY) |
| `inbox reject <id>` | Reject a pending approval (`--note` reason required, `--confirm` in non-TTY) |
| `hitl list` | List human-in-the-loop escalations (alias surface of `inbox`) |
| `hitl approve <id>` | Approve an escalation |
| `hitl reject <id>` | Reject an escalation (note required) |
| `hitl reassign <id> <assignee>` | Reassign a pending escalation |
| `hitl modify <id> <proposal>` | Submit a counter-proposal for an escalation |
| `hitl dead-letter` | List HITL escalations dead-lettered by a decision-SLA timeout |
| `hitl ledger append` | Append a signed entry to the HITL ledger chain |
| `runs tail` | Stream new run entries live (poll-based; `--interval`, `--workspace`) |
| `runs retention prune` | Prune run records beyond the configured retention policy |

## Pipelines

| Command | Description |
|---|---|
| `pipelines list` | List pipelines in the workspace (`--json`) |
| `pipelines show <id>` | Show a single pipeline by id (`--json`) |
| `pipelines runs <id>` | List runs for a pipeline (`--limit`, `--json`) |
| `pipelines run <id>` | Dispatch a new pipeline run (`--mode`, `--input`, `--json`) |
| `pipelines resume <runId>` | Resume a pipeline run paused at an approval gate (`--json`) |
| `pipelines cancel <runId>` | Cancel an in-flight pipeline run (`--json`) |

## Triggers

| Command | Description |
|---|---|
| `triggers kinds` | List all supported trigger kinds |
| `triggers list` | List triggers defined in a config file |
| `triggers add` | Add a trigger to a config file |
| `triggers remove <id>` | Remove a trigger from a config file |
| `triggers test <id>` | Send a synthetic event through a trigger (requires sidecar) |
| `triggers runs <id>` | View recent executions for a trigger (requires sidecar) |
| `triggers url <id>` | Print the inbound URL for a webhook trigger (requires sidecar) |
| `triggers toggle <id>` | Enable or disable a trigger (requires sidecar) |
| `trigger preset list` | List built-in trigger presets |
| `trigger preset show <id>` | Show the configuration for a named preset |
| `triggers tail` | Stream new trigger-fired events live (poll-based; `--interval`) |
| `triggers contracts` | List every registered trigger contract via the sidecar |

## Configuration

| Command | Description |
|---|---|
| `config validate <path>` | Validate a config file against the AKOS schema |
| `config get <path> [key]` | Read a value (dotted key) from a config file, or the whole config |
| `config set <path> <key> <value>` | Set a value (dotted key); validates before writing. Requires `--confirm` in non-TTY |
| `config edit <path>` | Open a config file in `$EDITOR`; validates on save (TTY only) |
| `config diff <prev> <next>` | Show a structural diff between two config files |
| `config explain` | Show which config layer set each leaf value |
| `config migrate <path>` | Migrate a config file to the current schema version |
| `lock <configPath>` | Generate or verify `akos.lock` |
| `sync` | Check or apply version drift between the lockfile and installed packages |

## Deploying and operating

| Command | Description |
|---|---|
| `publish [dir]` | Build a signed plugin bundle for marketplace upload |
| `deploy [bundle]` | Verify asset integrity and ship a bundle to a publisher backend |
| `install <url>` | Fetch, verify, and install a plugin from a registry URL |
| `serve` | Start the local workspace sidecar (JSON-RPC over stdio) |
| `mcp-serve` | Serve the AKOS capability catalog and security tools to external agents over MCP |
| `mcp discover` | Discover MCP server definitions from local agent config files |
| `import <input>` | Translate an n8n / LangChain / LangGraph / Langflow / Flowise / Dify workflow into AKOS config (`--apply` to upsert into the workspace) |
| `migrate-to-cloud` | Migrate local workspace data to Postgres and S3 |
| `docs export` | Emit the for-agents catalog (JSON + `llms.txt`; RFC-0012) |
| `seed` | Materialise demo pack data into sidecar stores (`--vertical`, `--reset`) |
| `prod seed` | Ledgered production seeds — demo packs or assistant-knowledge folders (`--dry-run`, `--apply`, `--target demo\|assistant-knowledge`, `--force`, `--vertical`, `--base-dir`) |
| `snapshot create` | Create a workspace snapshot |
| `snapshot restore` | Restore a workspace from a snapshot |
| `snapshot schedule` | Persist a snapshot scheduling and retention policy |
| `snapshot retention` | Apply the configured retention policy and prune old snapshots |

### MCP security tools

`mcp-serve` exposes agent-operable security management (ADR-0136). An agent can
read and reconfigure the firewall, egress policy, and PII profiles at runtime —
no redeploy — via these MCP tools:

| MCP tool | Description |
|---|---|
| `firewall.rules.list` | List firewall rules (optionally by tier) |
| `firewall.rules.upsert` | Create or update a firewall rule |
| `firewall.rules.delete` | Delete a firewall rule by id |
| `firewall.rules.shadow` | Toggle a rule into/out of `dry_run` (shadow / log-only) mode |
| `egress.policy.get` / `egress.policy.set` | Read or replace the outbound network policy |
| `pii.profiles.list` / `pii.profiles.upsert` / `pii.profiles.delete` | Manage custom PII redaction profiles |

> Every security tool requires the `security:admin` capability. The MCP server
> forwards each call to the running sidecar, where the RBAC access gate
> authorizes it — an unauthorized principal receives `AUTHZ_DENIED`. There is no
> path that bypasses the gate.

## Plugins

| Command | Description |
|---|---|
| `plugins list` | List installed plugins (`--workspace`, `--json`) |
| `plugins get <id>` | Show a plugin with its capability grants (`--json`) |
| `plugins install <manifest>` | Install a plugin from a manifest |
| `plugins enable <id>` | Enable an installed plugin |
| `plugins disable <id>` | Disable an installed plugin |
| `plugins uninstall <id>` | Uninstall a plugin and remove its files |

## Packs

| Command | Description |
|---|---|
| `packs list` | List available domain packs (`--json`) |
| `packs install <id>` | Install a domain pack into the workspace |
| `packs seed` | Materialise a demo seed bundle (alias of `seed`) |

## Templates

| Command | Description |
|---|---|
| `templates list` | List starter flow templates (`--json`) |

## Marketplace

| Command | Description |
|---|---|
| `marketplace search` | List and filter available marketplace domain packs |
| `marketplace install <packId>` | Apply a domain pack to the workspace (requires sidecar) |
| `marketplace featured` | Show the editorial featured-listing rotation |
| `marketplace suggestions` | Show connection suggestions inferred from workspace + recent runs |
| `marketplace report` | File an abuse / policy report against a listing (`--listing`, `--reason`) |
| `marketplace private-library` | List private (non-marketplace) plugins available for install |
| `marketplace publisher-keys` | List pinned publisher keys with their current trust level |
| `marketplace installed` | List installed plugins for the active workspace |
| `marketplace fetch` | Fetch the marketplace catalog |
| `marketplace apply-monitoring-pack <packId>` | Apply a monitoring pack to the workspace |
| `marketplace apply-security-pack <packId>` | Apply a security pack to the workspace |

## Tools

| Command | Description |
|---|---|
| `tools list` | List built-in + plugin tools in the workspace (`--workspace`, `--json`) |
| `tools show <id>` | Show a tool descriptor: category, stability, side-effects, capabilities, args schema (`--json`) |

> Direct ad-hoc tool invocation has no sidecar contract — tools execute inside governed runs. Run a tool by adding it to a flow/agent and using `flows run` / `agents run`.

## Connectors

| Command | Description |
|---|---|
| `connectors test --workspace <id>` | Preflight connections — reports missing credential **keys** (never values), `--kind`, `--json` |

> Connection CRUD lives under `connections list/get/set/rm`. `connectors` adds the readiness check.

## Knowledge (RAG)

`knowledge` manages knowledge sources (list, add, remove, reindex, status, search). `rag` is a companion command focused on retrieval and ingestion (search, ingest, status). Both commands are real and shipped; use `knowledge` for source management and `rag` for agent-facing retrieval.

| Command | Description |
|---|---|
| `knowledge list` | List configured knowledge sources (`--json`) |
| `knowledge add <id> <location>` | Add a source (`--kind`, `--name`); loader secrets provisioned via `secrets`, never passed here |
| `knowledge remove <id>` | Remove a source and drop its index |
| `knowledge search <text>` | Search the knowledge index (alias: `query`; `--source`, `--top-k`, `--json`); see also: `rag search` |
| `knowledge reindex <id>` | Drop and re-run the digest for a source (alias: `rebuild`) |
| `knowledge status` | Indexer status for every source (`--json`) |
| `rag search <text>` | Agent-facing RAG retrieval (`--source`, `--top-k`, `--json`); see also: `knowledge search` |
| `rag ingest <id>` | Re-index (ingest) an existing source |
| `rag status` | Indexer readiness for every source (`--json`) |

## Security & governance

| Command | Description |
|---|---|
| `security policy` | Live governance posture: air-gap, firewall, PII, sandbox, RBAC, egress, audit (`--json`) |
| `security rbac` | List operator roles and assignments (`--json`) |
| `security egress` | Show the egress policy slice of the posture (`--json`) |
| `security firewall rules` | List firewall rules (`--tier`, `--shadow` for dry-run-only, `--json`) |
| `security firewall set` | Create or update a firewall rule (`--id`, `--tier`, `--pattern`, `--action`, `--shadow`, `--severity`, `--scope`, `--json`) |
| `security firewall test` | Evaluate sample text against a tier; shows enforced and shadow matches (`--text`, `--tier`, `--shadow`, `--json`) |

## Sandbox

| Command | Description |
|---|---|
| `sandbox state` | Show the active sandbox isolation level and live sandbox count |
| `sandbox policy` | Get or set the sandbox isolation policy |
| `sandbox denials` | List recent sandbox denial events (`--limit`, `--json`) |
| `sandbox preview` | Preview what a policy change would deny before applying it |

## Costs

| Command | Description |
|---|---|
| `costs summary` | Aggregate spend over a window (`--workspace`, `--window-hours`, `--json`) |
| `costs breakdown` | Detailed spend breakdown (`--group-by`, `--from`, `--to`, `--provider`, `--role`, `--workspace`, `--json`) |
| `costs budgets` | List configured spend budgets and thresholds (`--json`) |
| `costs list` | List itemized cost rows (for filtering / CSV export) (`--json`) |
| `costs alerts` | List active cost alerts derived from budget consumption (`--json`) |
| `costs usage` | Show tenant usage state from the backend usage meter (`--json`) |
| `usage status`, `usage watch` | Inspect, poll, or stream tenant usage state with `--sse`; exits non-zero when usage is exceeded or blocked |

## Audit

| Command | Description |
|---|---|
| `audit list` | List audit ledger entries (`--actor`, `--kind`, `--workspace`, `--limit`, `--json`) |
| `audit show <id>` | Show a single audit entry by id/seq |
| `audit export` | Export a signed audit batch (`--workspace`, `--limit`) |
| `audit verify` | Verify ledger integrity (hash chain + signatures); exit 1 on failure |
| `audit tail` | Follow audit entries live (see streaming commands) |

## Compliance

| Command | Description |
|---|---|
| `compliance export` | Export compliance records (e-discovery, audit export) |
| `compliance legal-hold` | Place or release a legal hold on workspace data |
| `compliance delete` | DSAR / right-to-erasure delete of data for a subject |

## Observability

`observability` covers traces, metrics, logs, and exporter status. `obs` is a companion command that adds anomaly-rule inspection not covered by `observability`. Both commands are real and shipped; neither replaces the other.

| Command | Description |
|---|---|
| `observability metrics <metric>` | Timeseries (`tokens.in`/`tokens.out`/`cost.totalUsd`/`errors.count`/`p99.latencyMs`; `--range`, `--json`) |
| `observability traces <runId>` | Span/tool event timeline for a run (`--json`) |
| `observability logs` | Snapshot active anomalies (`--workspace`, `--json`) |
| `observability status` | Telemetry exporter + anomaly-rule + cost-meter snapshot (`--json`) |
| `logs tail` | Stream live anomaly/observability events (poll-based; `--interval`, `--workspace`) |
| `obs anomaly-rules` | List structured anomaly rules with their paused state (`--json`); see also: `observability` |

## Admin

| Command | Description |
|---|---|
| `users list` | List workspace users (`--json`) |
| `users get <id>` | Show a user (`--json`) |
| `users upsert` | Create or update a user |
| `users delete <id>` | Remove a user |
| `users role <id> <role>` | Assign or revoke a role for a user |
| `teams list` | List teams (`--json`) |
| `teams get <id>` | Show a team (`--json`) |
| `teams upsert` | Create or update a team |
| `teams delete <id>` | Remove a team |
| `teams member` | Add or remove a team member |
| `teams role <id> <role>` | Assign or revoke a role for a team |
| `topologies list` | List agent topologies (`--json`) |
| `topologies upsert` | Create or update a topology |
| `topologies delete <id>` | Remove a topology |
| `topologies run <id>` | Dispatch a topology run |

## Dev and coding-agent

| Command | Description |
|---|---|
| `dev worktree` | Manage git worktrees for parallel development |
| `dev issue-pr` | Create or link a PR to a tracked issue |
| `coding-agent delegate` | Delegate a coding task to the coding agent |
| `coding-agent benchmark` | Run the coding-agent benchmark suite |
| `coding-agent conformance` | Run the coding-agent conformance checks |
| `coding-agent smoke` | Run a quick smoke test of the coding-agent surface |

## Chat

`chat` opens an interactive or streaming session with the workspace assistant. Walkthrough (one-shot, `--interactive`, `--tui`, sessions): **[Chat and Interactive Shell](/docs/cli/chat)**. Slash-command reference: [Interactive shell](#interactive-shell) below.

| Command | Description |
|---|---|
| `chat [message]` | Send a message to the workspace assistant (`--stream`, `--interactive`, `--tui`) |
| `chat sessions` | List saved chat sessions (`--json`) |
| `chat show <id>` | Show the transcript for a session (`--json`) |
| `chat cancel <id>` | Cancel an in-progress chat session |
| `chat delete <id>` | Delete a chat session and its transcript |

## Copilot

Slash/mention parsing and proactive cards via the sidecar.

| Command | Description |
|---|---|
| `copilot slash list` | List supported copilot slash commands and their dispatch methods |
| `copilot slash parse <raw>` | Parse a chat message for a leading slash command; returns the dispatch method |
| `copilot mention parse <text>` | Parse @-mentions out of a chat message |
| `copilot proactive <eventJson>` | Turn a sidecar event (JSON object) into a proactive action card, or null |

## Telemetry

| Command | Description |
|---|---|
| `telemetry status` | Show current telemetry consent state |
| `telemetry enable` | Opt in to anonymous usage telemetry |
| `telemetry disable` | Opt out of telemetry |
| `telemetry export` | Export stored telemetry events (JSON or CSV) |

---

## Interactive shell

`akos chat --interactive` (or `akos` with no args on a TTY) opens a portable
readline shell. `akos chat --tui` opens the **full-screen Ink TUI** (transcript
pane, themes, autocomplete, governance badges, proposal cards) over the *same*
slash-command registry — it requires a TTY and falls back to `chat --interactive`
otherwise. See [Full-screen TUI](#full-screen-tui-akos-chat---tui) below.
Slash commands mirror the scriptable surface and remember the last list you
viewed, so you can select by number:

| Slash | Action |
|---|---|
| `/help` | List available slash commands |
| `/session` | Show the active session ID and workspace |
| `/workspaces`, `/workspace <id\|n>` | List / switch workspace |
| `/sessions`, `/use <id\|n>`, `/new` | List / switch / create a chat session. In the `--tui`, `/sessions` opens an interactive picker (↑↓ select, ⏎ switch, Esc cancel) and switching re-loads that session's transcript |
| `/flows`, `/flow <id\|n>`, `/run-flow <id\|n>` | List / show / run a flow |
| `/agents`, `/agent <id\|n>` | List / show an agent |
| `/inbox`, `/approve <id\|n>`, `/reject <id\|n>` | List pending approvals / approve / reject |
| `/tools`, `/tool <id\|n>`, `/knowledge` | Browse tools / show a tool / list knowledge sources |
| `/runs`, `/run <id\|n>` | List recent runs / show one |
| `/tail <id\|n>` | Snapshot a run's current status + recent events |
| `/watch <id\|n>` | Follow a run until it finishes (polls to a terminal state) |
| `/logs <id\|n>` | Show a run's span/tool event timeline |
| `/artifacts <id\|n>` | List a run's artifacts |
| `/cancel <id\|n>`, `/retry <id\|n>` | Cancel / re-dispatch a run |
| `/apply <n>` | Apply the n-th proposal on the latest assistant turn (approves it so the agent materializes the flow/agent it proposed) |
| `/verticals`, `/vertical <id\|n>`, `/vertical use <id\|n>` | List the whitelabel catalog / show a vertical's config / switch the CLI's active vertical |
| `/connect`, `/connect <id\|n> <api-key>`, `/connect <id\|n> <code> <state>` | List providers / store an API key / finish a browser OAuth flow |
| `/cost`, `/logs <id\|n>` | Cost summary / run logs (also available as cockpit verbs) |
| `/theme [name]`, `/config` | Switch color theme (`ocean`, `grape`, `forest`, `ember`, `mono`, plus truecolor `midnight`, `sunset`, `nord`) / show configuration |
| `/compact`, `/export [path]` | Toggle dense spacing / save the conversation to markdown |
| `/resend` | Resend the last message (TUI built-in; distinct from the runs cockpit `/retry`) |
| `/history`, `/clear` | Print / clear the local transcript |
| `/quit` | Exit (Ctrl-C / Ctrl-D also exit gracefully) |

### Full-screen TUI (`akos chat --tui`)

The TUI layers a richer experience over the same slash commands and streaming:

- **Themes & color.** `/theme <name>` switches palettes live and persists the
  choice to `~/.akos/tui.json`. Three 24-bit truecolor palettes (`midnight`,
  `sunset`, `nord`) render on truecolor terminals and downsample elsewhere.
  Setting `NO_COLOR` forces the monochrome palette.
- **Code rendering.** Assistant markdown renders headers, lists, inline/fenced
  code with a language label and lightweight syntax highlighting.
- **Editing.** Readline-style line editing — `←`/`→`, `Ctrl+A`/`E` (start/end),
  `Ctrl+W` (delete word), `Ctrl+U`/`Ctrl+K` (kill to start/end), and `Ctrl+Y`
  (yank the last killed text). `↑`/`↓` recall input history; `Tab` completes
  `/commands` and `@mentions`.
- **Keybindings.** The discrete action keys — approve gate, cancel turn, scroll
  up/down — are configurable via `~/.akos/keys.json`. Each action maps to a chord
  `{ "ctrl": true, "char": "g" }` or `{ "key": "pageUp" }`; defaults match the
  shipped bindings, so the file is optional. Example:

  ```json
  {
    "approve": { "ctrl": true, "char": "g" },
    "cancel": { "key": "escape" },
    "scrollUp": { "key": "pageUp" },
    "scrollDown": { "key": "pageDown" }
  }
  ```

- **Governance & cost.** Header badges show pending HITL approvals and in-flight
  runs (polled); `Ctrl+G` approves the next gate inline. The footer shows session
  token usage and spend over the cost window.
- **Proposals.** When the assistant proposes a flow/agent, it renders as a card
  with the target tool, action tier, and estimated cost; `/apply <n>` approves it.
- **Resume.** A session's transcript is reloaded from the sidecar on launch and
  when switching sessions, so history is not lost. `Ctrl+C` prints how to resume.
- **Offline.** If the sidecar is unreachable the header shows an offline banner;
  the CLI auto-starts a local sidecar on first use.

## Streaming

Live, incremental output (ADR-0133). Streaming is **polling-based** today — the
sidecar transport is request/response, so there is no server-push channel yet; a
future sidecar contract can add one behind the same subscription interface.

| Command | Description |
|---|---|
| `chat <message> --stream` | Render assistant tokens incrementally as they arrive (falls back to `--wait` polling) |
| `runs tail` / `runs watch <id>` | Poll-based live run/event tails |
| `logs tail` / `audit tail` / `triggers tail` | Poll-based live event tails |

Streams are cancellable and deadline-bounded (`--timeout-ms`,
`AKOS_STREAM_INTERVAL_MS`) so they never block a CI pipeline. When streaming is
unavailable, the polling fallback remains.

## Global flags

These flags are accepted by most commands:

| Flag | Description |
|---|---|
| `--help`, `-h` | Display help for the command |
| `--json` | Emit machine-readable JSON output (where supported) |
| `--stream` | (chat) render incremental assistant tokens |

## Exit codes

Cross-cutting codes shared by the sidecar-backed command families (the
canonical contract; centralised in `os-cli`'s `lib/exit-codes.ts`):

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Runtime / network / I/O error |
| `2` | Invalid arguments, usage, or invalid config |
| `5` | Requested resource not found (run, flow, agent, tool, inbox item) |

Some commands additionally use command-specific codes, documented per command:
`3` (pre-flight / input-file read failure), `4` (conflict / already exists),
`6` (unsatisfied governance gate), `7` (missing credentials), `8` (registry
entry not found), `9` (state mismatch — stored state diverges from request),
`10` (lockfile drift — `lock --check` found drift vs the current config).

> Note: lockfile drift is exit code `10`, distinct from `5` (NOT_FOUND).

## Related topics

- **[CLI index](/docs/cli)** — install, `doctor`, shell completion, CI tokens
- **[Using the App](/docs/using-the-app)** — screen guides for the same workspace
- **[Run lifecycle](/docs/how-it-works/run-lifecycle)** — governed path behind `run`, `pipelines`, and `audit`

## Server, CI, and non-TTY usage

`akos` is safe to run on headless servers, in SSH sessions, and in CI without a
graphical shell:

- **Authentication.** Set `AKOS_TOKEN` in the environment to skip the
  interactive `auth login` device-code flow. `auth login` detects the variable
  and exits `0`.
- **Machine output.** Pass `--json` to any `list`/`show`/`get`/`status` command
  for parseable stdout. Diagnostics go to stderr, so `... --json | jq` stays clean.
- **Mutations never block.** Destructive commands (`workspaces delete`,
  `config set`) require `--confirm`. In a non-TTY context they fail fast with a
  hint instead of waiting for input — they never hang a pipeline.
- **`config edit` is interactive only.** It opens `$EDITOR` and therefore
  requires a TTY. In CI use `config set <path> <key> <value> --confirm` (scripted)
  or `config validate` (read-only) instead.
- **Sidecar reachability.** Commands marked "requires sidecar" call the local
  workspace sidecar (`akos serve`). Point the CLI at a remote sidecar with
  `AKOS_HEADLESS_URL`; tune the per-call deadline with `AKOS_SIDECAR_TIMEOUT_MS`
  (default 15 000 ms). Sidecar calls have deadlines and render typed errors with
  actionable hints. `akos status` reports whether the sidecar is reachable.
- **Color.** ANSI color is disabled automatically when stdout is not a TTY, when
  `NO_COLOR` is set, or under `CI`. Set `FORCE_COLOR` to override. Watch/tail
  commands emit plain newline-delimited records suitable for log capture.

Source: /raw/cli/command-reference.mdx

### cli/configuration.mdx

---
title: Configuration
description: Initialize workspaces, validate and diff config files, trace config layer provenance, migrate schemas, and generate lockfiles.
---

AKOS workspaces are defined by a single YAML file (`akos.config.yaml`). The CLI provides a set of commands for creating, verifying, comparing, explaining, and migrating these configuration files, plus a lockfile system for reproducible deployments.

## Initializing a workspace

To scaffold a new workspace in the current directory:

```bash
akos init
```

To initialize in a specific directory:

```bash
akos init ./my-workspace
```

This creates:
- `akos.config.yaml` — the workspace config
- `.agentskitos/` — the runtime data directory
- `.gitignore` — pre-populated to exclude `.agentskitos/` and `.env` files

### init options

| Flag | Description |
|---|---|
| `[dir]` | Target directory (default: current directory) |
| `--id <slug>` | Workspace ID (default: slugified directory name) |
| `--name <name>` | Display name (default: directory basename) |
| `--force` | Overwrite an existing `akos.config.yaml` |
| `--non-interactive` | Never prompt; use only flags and defaults |
| `--template <id>` | Scaffold from a starter template |

Available templates: `hello-agent` (seeds a minimal agent and flow).

```bash
akos init --template hello-agent
```

After scaffolding with `hello-agent`, you can immediately do a dry run:

```bash
akos run akos.config.yaml --mode dry_run
```

## Validating a config file

```bash
akos config validate akos.config.yaml
```

Exits 0 when the file is valid, or exits 1 and prints each validation error with its field path and message. Works with both YAML and JSON config files.

## Diffing two config files

```bash
akos config diff akos.config.yaml akos.config.new.yaml
```

Outputs a structural diff:
- `+` path: value — key added
- `- path`: value — key removed
- `~ path`: old → new — value changed

Exits 0 whether or not there are changes. Useful in CI to detect unexpected config drift between environments.

## Explaining config layer provenance

When you run AKOS with multiple config layers (defaults, global, workspace, env, runtime), `config explain` shows which layer set each leaf value in the merged result:

```bash
akos config explain \
  --defaults defaults.yaml \
  --workspace akos.config.yaml
```

Use any combination of the layer flags:

| Flag | Description |
|---|---|
| `--defaults <path>` | Defaults layer config path |
| `--global <path>` | Global layer config path |
| `--workspace <path>` | Workspace layer config path |
| `--env <path>` | Env layer config path |
| `--runtime <path>` | Runtime layer config path |

At least one flag is required. The command prints a table of every leaf value and the layer that supplied it, followed by the fully merged config value.

## Migrating a config to a newer schema

```bash
akos config migrate akos.config.yaml
```

Migrates the config to the current schema version. Prints a list of migration steps applied and the resulting config.

To target a specific version:

```bash
akos config migrate akos.config.yaml --to 2
```

If no migration steps are needed (the config is already current), the command exits 0 with `(no migrations needed)`.

## Lockfiles

A lockfile (`akos.lock`) pins the exact versions and content hashes of agents, flows, plugins, and providers in a workspace config. Check it into source control to ensure reproducible deployments.

### Generate a lockfile

```bash
akos lock akos.config.yaml
```

Writes `akos.lock` next to the config file. To write to a different path:

```bash
akos lock akos.config.yaml --out /path/to/akos.lock
```

### Verify a lockfile has not drifted

```bash
akos lock akos.config.yaml --check
```

Compares the existing lockfile against the current config. Exits 0 when they match, or exits 10 (lockfile drift) and lists drift issues. Use this in CI to catch unintended config changes.

### Sync installed versions

After verifying the lockfile, use `sync` to apply any version drift between the lockfile and your installed packages:

```bash
# Check for drift (default — no changes made)
akos sync

# Apply drift (install/upgrade to match the lockfile)
akos sync --apply

# Restrict scope
akos sync --plugins-only
akos sync --core-only

# Point to a non-default lockfile
akos sync --lock /path/to/akos.lock
```

## Related topics

- **[General workspace settings](/docs/using-the-app/workspaces)** — export/import and runtime sections.
- **[Route-only Config screen](/docs/using-the-app/route-only-screens)** — copilot, orchestration, privacy tabs.
- **[Migrating to AKOS](/docs/cli/migrating)** — import flows and migrate local state to cloud.

Source: /raw/cli/configuration.mdx

### cli/connections.mdx

---
title: Connections
description: List integration connections, read the setup registry, provision connectors, and preflight readiness from the CLI.
---

The `connections` commands manage **integration connections** — typed records that flows, agents, and triggers reference for OAuth apps, webhooks, SQL, LLM providers, and more.

Credential **values never appear on the command line**. Store secrets with `vault put` or `secrets set`, then reference a vault key when provisioning a connection.

## Prerequisites

```bash
akos auth login
akos serve    # or AKOS_HEADLESS_URL for a remote sidecar
```

See **[Authentication](/docs/cli/authentication)** for login, vault, secrets, and `creds` workflows.

## List connections

```bash
akos connections list
akos connections list --kind slack --json
```

## Read one connection

```bash
akos connections get slack-main --json
akos connections sql-get analytics-db --json
```

## Integration setup registry

The setup registry powers the assistant, Connections UI, and this CLI surface. Print provider-specific guidance before wiring credentials:

```bash
akos connections guide slack
akos connections guide discord --json
akos connections guide --category llm --implemented-only
```

Each entry includes:

- Preferred setup mode (OAuth, bot install, guided secret, …)
- Required scopes and health-check RPC method
- Assistant-safe wording hints
- Links to external credential pages when applicable

This mirrors the **[Integration setup](/docs/using-the-app/integration-setup)** product guide and `akos creds guide`.

## Provision a connection

```bash
akos connections set \
  --id slack-main \
  --kind slack \
  --label "Engineering Slack" \
  --secret-id SLACK_BOT_TOKEN
```

Use `--no-auth` for connections that do not require stored credentials. Optional flags: `--scopes` (comma-separated), `--schema`, `--workspace`. Supported kinds: `slack`, `github`, `linear`, `discord`, `email`, `cron`, `file`, `webhook`, `cdc`, `twilio`, `sentry`, `pagerduty`, `stripe`, `s3`, `mcp`, `llm`.

## Remove a connection

```bash
akos connections rm my-slack
```

Removing a connection does not delete the underlying vault secret.

## Preflight readiness

Before a demo or deploy, verify that required credential **keys** exist (values are never printed):

```bash
akos connectors test --workspace default
akos connectors test --workspace default --kind slack --json
```

## External automation API keys

Scoped keys for `/v1/automations/*` are provisioned through the Connections UI (**External apps**) or the sidecar integration surface — not via a separate CLI verb today. See **[Public automation API](/docs/using-the-app/public-automation-api)** for request shapes after keys exist.

## Related topics

- **[Connections in the app](/docs/using-the-app/connections)** — OAuth cards, SQL, cloud sync, coding agents.
- **[Authentication](/docs/cli/authentication)** — `vault`, `secrets`, and `creds check`.
- **[Integration setup](/docs/using-the-app/integration-setup)** — guided setup narrative for operators.
- **[Triggers](/docs/cli/triggers)** — SaaS triggers that share OAuth connections.
- **[Command reference](/docs/cli/command-reference)** — full `connections.*` and `connectors` tables.

Source: /raw/cli/connections.mdx

### cli/costs-observability.mdx

---
title: Costs and Observability
description: Inspect spend, budgets, usage limits, traces, metrics, and anomaly rules from the CLI.
---

Cost and observability commands read the same meters and telemetry exporters as the **[Cost](/docs/using-the-app/cost)** screen and **[Activity](/docs/using-the-app/runs-and-observability)** traces view.

All verbs require sidecar reachability unless noted.

## Cost summary

```bash
akos costs summary
akos costs summary --workspace default --window-hours 168 --json
```

Aggregate spend for the configured window (default: recent hours).

## Breakdown

```bash
akos costs breakdown --group-by provider --from 2026-07-01 --to 2026-07-05
akos costs breakdown --group-by role --provider openai --json
```

`groupBy` is required by the sidecar contract (`provider`, `role`, `workspace`, …).

## Budgets and alerts

```bash
akos costs budgets --json
akos costs alerts --json
akos costs list --json
```

`costs list` returns itemized rows suitable for CSV piping; `costs alerts` surfaces budget threshold breaches.

## Tenant usage meter

Cloud tenants expose backend-computed usage limits (do not recompute limits in scripts):

```bash
akos usage status --json
akos usage watch --once --json
akos usage watch --sse --timeout-ms 60000
```

`usage watch` exits non-zero when status is `blocked` or `exceeded` — useful in CI guardrails.

## Per-run cost

For a single execution, use the runs cockpit:

```bash
akos runs show <runId> --json
akos runs logs <runId> --json
```

Token and USD fields appear in the enriched run detail payload.

## Observability

```bash
akos observability status --json
akos observability metrics tokens.in --range 24h --json
akos observability traces <runId> --json
akos observability logs --workspace default --json
```

Metrics ids include `tokens.in`, `tokens.out`, `cost.totalUsd`, `errors.count`, and `p99.latencyMs`.

### Anomaly rules

```bash
akos obs anomaly-rules --json
```

Companion to `observability` — lists structured anomaly rules and paused state.

### Live tails

Poll-based streaming (ADR-0133) — safe for CI with deadlines:

```bash
akos logs tail --interval 2000 --workspace default
akos runs tail --interval 1500
akos runs watch <runId> --json
```

Set `AKOS_STREAM_INTERVAL_MS` to tune poll cadence.

## Interactive shell shortcuts

In `akos chat --interactive` or `--tui`, slash commands mirror these surfaces:

- `/cost` — spend summary for the session window
- `/runs`, `/run <id>`, `/watch <id>`, `/logs <id>` — run inspection
- `/tail <id>` — snapshot status + recent events

See **[Command reference](/docs/cli/command-reference)** › Interactive shell.

## Related topics

- **[Cost in the app](/docs/using-the-app/cost)** — budgets, billing tab, spend charts.
- **[Activity](/docs/using-the-app/runs-and-observability)** — run list, traces, observability health.
- **[Flows and Runs](/docs/cli/flows-and-runs)** — `runs show`, `runs watch`, retention prune.
- **[Dashboard](/docs/using-the-app/dashboard)** — live cost summary card.
- **[Command reference](/docs/cli/command-reference)** — full `costs`, `usage`, and `observability` tables.

Source: /raw/cli/costs-observability.mdx

### cli/deploying.mdx

---
title: Deploying
description: Publish and deploy plugins, run the local sidecar, migrate to cloud, and manage workspace snapshots.
---

AKOS supports several deployment workflows: publishing plugins for the marketplace, running the local sidecar for development, migrating self-hosted data to cloud infrastructure, and scheduling workspace snapshots.

## Publishing a plugin

The `publish` command packages a plugin into a signed, integrity-verified bundle for the AKOS marketplace.

### Plugin structure

Your plugin directory should contain:
- `agentskit-os.plugin.yaml` — the plugin manifest
- `dist/` — compiled asset files

### Build the bundle

```bash
akos publish
```

By default this reads the manifest from `./agentskit-os.plugin.yaml`, packages assets from `./dist/`, and writes `./agentskit-os.bundle.json`.

For development or internal bundles, skip the signature requirement:

```bash
akos publish --unsigned
```

### publish options

| Flag | Description |
|---|---|
| `[dir]` | Plugin source directory (default: `.`) |
| `--manifest <path>` | Override manifest path |
| `--assets <dir>` | Override assets directory |
| `--out <path>` | Override bundle output path |
| `--unsigned` | Emit an unsigned manifest (for dev/internal use) |
| `--registry-url <url>` | POST the bundle to a marketplace publish endpoint |
| `--publisher-id <id>` | Publisher ID (default: `manifest.id`) |

## Deploying a bundle

After building with `publish`, use `deploy` to verify asset integrity and hand the bundle to a publisher backend.

```bash
akos deploy
```

By default reads `./agentskit-os.bundle.json` and verifies each asset's SHA-256.

To verify only without publishing:

```bash
akos deploy --dry-run
```

### deploy options

| Flag | Description |
|---|---|
| `[bundle]` | Bundle JSON path (default: `agentskit-os.bundle.json`) |
| `--assets <dir>` | Override assets directory (default: `<bundle-dir>/dist`) |
| `--publisher <name>` | Publisher backend (default: `in-memory`) |
| `--dry-run` | Verify only; skip the publish call |

## Installing a plugin

To fetch, verify, and install a plugin from a registry URL:

```bash
akos install <registry-url>
```

The CLI fetches the payload (manifest + bundle + signature), verifies the signature, resolves permissions, and writes the plugin to `~/.agentskitos/plugins/<id>/<version>/`.

```bash
# Allow installation of an unsigned bundle (internal use only)
akos install <registry-url> --allow-unsigned

# Declare permitted permissions
akos install <registry-url> --allow-permission files:read --allow-permission network:egress

# Override install root
akos install <registry-url> --install-root /opt/akos/plugins
```

## Running the local sidecar

The `serve` command starts the local workspace sidecar, which provides the JSON-RPC surface that the desktop app and CLI commands such as `hitl`, `triggers`, `vault`, and `connections` communicate with.

```bash
akos serve
```

The process stays running and streams JSON-RPC over stdin/stdout. Use this during local development.

To accept webhook deliveries from external systems, bind to all interfaces:

```bash
akos serve --public
```

Pin the webhook port:

```bash
akos serve --public --webhook-port 4242
```

> When `--public` is used, the CLI prints a security warning. Always run behind a firewall or trusted tunnel and ensure every webhook trigger verifies its signature.

## Exposing the capability catalog over MCP

To allow an external AI agent to query the AKOS capability catalog via the Model Context Protocol:

```bash
akos mcp-serve
```

Spawns the MCP server over stdio. The external agent connects via JSON-RPC and can call `doc.search`, `doc.get`, and `capabilities.list`.

## Migrating from self-hosted to cloud

The `migrate-to-cloud` command streams your local workspace data (SQLite tables and blob objects) to a cloud Postgres database and optionally an S3 bucket.

```bash
akos migrate-to-cloud \
  --org my-org-id \
  --source ~/.agentskit \
  --target postgres://user:pass@host/dbname
```

To preview the migration plan without writing any data:

```bash
akos migrate-to-cloud \
  --org my-org-id \
  --source ~/.agentskit \
  --target postgres://... \
  --dry-run
```

To resume a previously interrupted migration:

```bash
akos migrate-to-cloud \
  --org my-org-id \
  --source ~/.agentskit \
  --target postgres://... \
  --resume
```

A checkpoint file at `<source>/.migrate-checkpoint.json` tracks progress. Rows and blobs already migrated are skipped (`ON CONFLICT DO NOTHING`).

### Blob migration (S3)

Set environment variables before running if you want to migrate blob objects alongside relational data:

```bash
export AKOS_S3_BUCKET=my-akos-bucket
export AKOS_S3_REGION=us-east-1

akos migrate-to-cloud \
  --org my-org-id \
  --source ~/.agentskit \
  --target postgres://...
```

### migrate-to-cloud options

| Flag | Description |
|---|---|
| `--org <orgId>` | Organization ID to migrate (required) |
| `--source <path>` | Path to the local data directory (required) |
| `--target <url>` | Cloud Postgres connection URL (required) |
| `--dry-run` | Print migration plan only; do not write to target |
| `--resume` | Resume using the checkpoint file |

## Snapshot scheduling

The `snapshot schedule` command writes a snapshot scheduling and retention policy for your workspace. It does not install cron or systemd tasks — it records the configuration and prints a suggested cron line you can install yourself.

```bash
akos snapshot schedule
```

Customize the schedule and retention:

```bash
akos snapshot schedule \
  --dir ./backups/snapshots \
  --cron "0 3 * * *" \
  --daily 7 \
  --weekly 4 \
  --monthly 12
```

### snapshot schedule options

| Flag | Description |
|---|---|
| `--dir <path>` | Snapshot directory (default: `./.agentskitos/snapshots`) |
| `--cron <expr>` | Cron expression (default: `0 2 * * *` — 2 AM daily) |
| `--daily <n>` | Keep snapshots for N distinct days (default: 7) |
| `--weekly <n>` | Keep snapshots for N distinct ISO weeks (default: 4) |
| `--monthly <n>` | Keep snapshots for N distinct months (default: 12) |

After running, the CLI prints the saved config path and a suggested cron entry to run `snapshot retention` on the same schedule.

## Telemetry

AKOS collects anonymous, opt-in usage telemetry. No secret values are ever included.

```bash
# Check current consent status
akos telemetry status

# Opt in
akos telemetry enable

# Opt out
akos telemetry disable

# Export stored events (JSON by default)
akos telemetry export

# Export as CSV
akos telemetry export --csv

# Export events since a specific date
akos telemetry export --since 2024-01-01T00:00:00Z

# Preview event counts without printing values
akos telemetry export --dry-run
```

## Related topics

- **[Migrating to AKOS](/docs/cli/migrating)** — `migrate-to-cloud` walkthrough (also covered above)
- **[Configuration](/docs/cli/configuration)** — `lock`, `sync`, and workspace export/import
- **[Connections](/docs/cli/connections)** — preflight integrations before go-live
- **[Knowledge and RAG](/docs/cli/knowledge-and-rag)** — `prod seed` for assistant documentation
- **[Command reference](/docs/cli/command-reference)** — `publish`, `install`, `serve`, `mcp-serve`, snapshots

Source: /raw/cli/deploying.mdx

### cli/flows-and-runs.mdx

---
title: Flows and Runs
description: Create flows from templates, execute them, inspect results, model what-if changes, and manage human-in-the-loop approvals.
---

Flows are the unit of work in AKOS: a directed graph of agent and tool nodes that executes a multi-step process. The CLI lets you scaffold flows from built-in templates, run them in several modes, inspect their output, and project the impact of model or configuration changes.

## Creating a flow

### Browse templates

```bash
akos flow new --list
```

Filter templates by persona:

```bash
akos flow new --list --persona developer
```

### Scaffold a flow into your workspace config

```bash
akos flow new <template-id>
```

For example:

```bash
akos flow new summarize-slack-dms
```

This merges the template's flow (and any required agents) into your `akos.config.yaml`. If a flow with the same ID already exists, the command exits with an error unless you pass `--replace`.

### flow new options

| Flag | Description |
|---|---|
| `--list` | List available templates and exit |
| `--persona <p>` | With `--list`, filter/order templates for a persona |
| `--target <path>` | Config file to merge into (default: `akos.config.yaml`) |
| `--flow-id <slug>` | Override the scaffolded flow ID |
| `--replace` | Replace an existing flow with the same ID |
| `--estimate` | Print a hint to run a cost estimate after scaffolding |
| `--visual` | Also write a visual layout document under `.agentskitos/flows/` |
| `--visual-out <path>` | Write the visual layout document to a custom path |

## Running a flow

```bash
akos run akos.config.yaml
```

By default, flows run in `dry_run` mode — the flow graph is traversed and logged but no LLM calls or external side effects are made. This is safe for testing your configuration.

### Run modes

| Mode | Description |
|---|---|
| `dry_run` | Traverse the flow without LLM calls or side effects (default) |
| `real` | Execute fully with live LLM calls and tool actions |
| `durable` | Like `real`, but checkpointed so interrupted runs can be resumed |

```bash
# Dry run (default)
akos run akos.config.yaml

# Live run
akos run akos.config.yaml --mode real

# Durable run (checkpointed)
akos run akos.config.yaml --mode durable --store ./run-checkpoints
```

### Selecting a specific flow

When your config has multiple flows, specify which one to run:

```bash
akos run akos.config.yaml --flow summarize-slack-dms
```

### Resuming an interrupted run

```bash
akos run akos.config.yaml \
  --mode durable \
  --store ./run-checkpoints \
  --resume <run-id>
```

`--resume` requires `--store`.

### Cost estimate

Print an estimated cost and exit without executing the flow:

```bash
akos run akos.config.yaml --estimate
```

### run options

| Flag | Description |
|---|---|
| `--flow <id>` | Flow ID to execute (required when config has multiple flows) |
| `--mode <mode>` | Run mode: `dry_run`, `real`, `durable` (default: `dry_run`) |
| `--workspace <id>` | Override workspace ID |
| `--store <dir>` | Checkpoint directory for durable mode |
| `--resume <runId>` | Resume an existing run (requires `--store`) |
| `--estimate` | Print cost estimate and exit |
| `--force` | Skip budget limit check |
| `--strict` | In `real` mode, error when LLM credentials are missing instead of falling back |
| `--quiet` | Suppress per-node event output |

## Listing past runs

```bash
akos runs list
```

Shows recent runs with their flow ID, status, cost, and token counts.

Add `--json` for structured output. Use `--limit <n>` to control how many results are returned.

## Fetching a single run

To fetch one run row by id via the sidecar:

```bash
akos runs get <run-id>
```

Add `--json` for the raw run row. The command returns `null` when no run matches the id.

## Explaining a run

After a coding agent run that captured artifact bundles, use `explain` to get a plain-English step-by-step walkthrough:

```bash
akos explain --artifact-dir ./run-artifacts
```

Filter to a specific run ID:

```bash
akos explain --artifact-dir ./run-artifacts --run-id <run-id>
```

Output as structured JSON:

```bash
akos explain --artifact-dir ./run-artifacts --json
```

The `--artifact-dir` should point to the directory passed to `--capture-run-artifacts` when the run was started.

## What-if analysis

Project how a change to token budget, latency, cost, or pass rate would affect your historical runs without re-running them.

Prepare a JSON file of past run snapshots:

```json
[
  { "id": "run-1", "costUsd": 0.005, "latencyMs": 900, "passed": true },
  { "id": "run-2", "costUsd": 0.007, "latencyMs": 1200, "passed": false }
]
```

Then project the impact:

```bash
# What if we switched to a model that costs 30% less?
akos whatif runs.json --cost 0.7

# What if tokens were reduced by 20% and latency improved by 10%?
akos whatif runs.json --tokens 0.8 --latency 0.9

# What if pass rate dropped by 5 percentage points?
akos whatif runs.json --pass -0.05
```

Options:

| Flag | Description |
|---|---|
| `--tokens <m>` | Token count multiplier (e.g. `0.7` = 30% fewer tokens) |
| `--latency <m>` | Latency multiplier |
| `--cost <m>` | Cost multiplier |
| `--pass <d>` | Pass-rate delta in the range `[-1, 1]` |
| `--json` | Emit JSON instead of the summary table |

## Human-in-the-loop (HITL) approvals

When a flow escalates a decision to a human reviewer, use `hitl` to list and act on pending escalations via the running workspace sidecar.

### List escalations

```bash
# All escalations
akos hitl list

# Filter by status
akos hitl list --status open
akos hitl list --status approved
akos hitl list --status rejected
```

### Approve an escalation

```bash
akos hitl approve <escalation-id>

# With a note and signer
akos hitl approve <escalation-id> \
  --note "Reviewed and looks correct" \
  --signer alice@example.com
```

### Reject an escalation

```bash
akos hitl reject <escalation-id> --note "Data quality issue — re-run after fix"
```

`--note` is required when rejecting.

### Reassign an escalation

```bash
akos hitl reassign <escalation-id> bob@example.com
```

### Submit a counter-proposal

```bash
akos hitl modify <escalation-id> "Use the revised budget figure of 42000"
```

All HITL commands require the workspace sidecar to be running (`akos serve`).

## Runs retention

To prune old run records:

```bash
akos runs retention prune
```

This command removes run records beyond the configured retention policy. Use `--dry-run` to preview what would be deleted.

## Related topics

- **[Workflows in the app](/docs/using-the-app/flows)** — visual editor, snapshots, import wizard.
- **[Activity](/docs/using-the-app/runs-and-observability)** — live run monitor and trace drill-down.
- **[Inbox](/docs/using-the-app/inbox)** — approve or reject paused human-gate steps.
- **[Run lifecycle](/docs/how-it-works/run-lifecycle)** — governed path from trigger to audit ledger.
- **[Triggers](/docs/cli/triggers)** — cron, webhook, and file-watch automation.

Source: /raw/cli/flows-and-runs.mdx

### cli/index.mdx

---
title: AKOS CLI
description: Set up the akos command line, run your first health check, and configure shell completion.
---

The AKOS CLI (`akos`) lets you manage every part of your AKOS workspace from a terminal: initialize workspaces, run flows, manage agents, configure triggers, operate secrets, and deploy plugins — all scriptable and CI-friendly.

## Requirements

- An active AKOS workspace (self-hosted desktop or cloud tenant)
- Credentials for that workspace from your AKOS administrator

## Installation

The `akos` CLI is provided as part of your AKOS enterprise plan. Your administrator distributes the build for your platform and your CI environment. If you don't have it yet, contact your AKOS administrator or account team for access.

Once it's installed, confirm it's available:

```bash
akos --version
```

## First run: doctor

Before doing anything else, run the built-in diagnostics to confirm the CLI is configured correctly:

```bash
akos doctor
```

`doctor` checks:

- Node.js version compatibility
- Platform support
- Whether the core AKOS runtime is linked
- The `AGENTSKITOS_HOME` data directory
- Available trigger kinds

To also verify that your AI provider credentials are present (no secret values are printed):

```bash
akos doctor --creds
```

To run a live connectivity probe (LLM round-trip + sandbox check, 10-second timeout):

```bash
akos doctor --live
```

### doctor options

| Flag | Description |
|---|---|
| `--live` | Run live LLM and sandbox probes |
| `--creds` | Check AI provider credential presence |
| `--air-gap` | Skip cloud providers when checking credentials |
| `--provider <id>` | Restrict credential check to one provider (repeatable) |
| `--env-prefix <pfx>` | Environment variable prefix to scan (default: `AGENTSKITOS_`) |
| `--secrets-file <path>` | Merge key names from a dotenv-style file into the credentials check |
| `--no-probes` | Skip vault and keychain probes |
| `--init-audit-key <wsId>` | Pre-generate an ed25519 audit signing key for a workspace and exit |

## Getting help

Every command and subcommand accepts `--help`:

```bash
akos --help
akos run --help
akos config validate --help
```

## Shell completion

Generate and install a completion script for your shell so you can tab-complete commands and flags.

**Bash** — add to `~/.bashrc`:

```bash
eval "$(akos completion bash)"
```

**Zsh** — add to `~/.zshrc`:

```bash
eval "$(akos completion zsh)"
```

**Fish** — save to the completions directory:

```bash
akos completion fish > ~/.config/fish/completions/akos.fish
```

Supported shells: `bash`, `zsh`, `fish`.

## Checking for updates

```bash
akos upgrade
```

To print the current and latest version without installing:

```bash
akos upgrade --check
```

## CI environments

When the environment variable `AKOS_TOKEN` is set, `auth login` is skipped automatically. This is the recommended pattern for non-interactive CI pipelines.

## Topic guides

Walkthroughs for the most common operator paths (each links to the full command table):

| Guide | Covers |
|---|---|
| [Authentication](/docs/cli/authentication) | Login, vault, secrets, creds |
| [Connections](/docs/cli/connections) | Setup registry, provision integrations, preflight |
| [Agents](/docs/cli/agents) | Registry, versions, promotion, compare |
| [Flows and Runs](/docs/cli/flows-and-runs) | Scaffold, run, watch, HITL, retention |
| [Processes (Pipelines)](/docs/cli/pipelines) | Multi-phase runs, resume, cancel |
| [Triggers](/docs/cli/triggers) | Cron, webhook, file-watch, sidecar ops |
| [Knowledge and RAG](/docs/cli/knowledge-and-rag) | Sources, search, prod seed, assistant docs |
| [Security and Governance](/docs/cli/security-governance) | Posture, firewall, audit, compliance |
| [Costs and Observability](/docs/cli/costs-observability) | Spend, usage limits, traces, tails |
| [Chat and shell](/docs/cli/chat) | Copilot one-shot, readline, TUI, slash commands |
| [Configuration](/docs/cli/configuration) | Validate, diff, lockfile, sync |
| [Migrating to AKOS](/docs/cli/migrating) | Import workflows, migrate-to-cloud |
| [Deploying](/docs/cli/deploying) | Plugins, sidecar, snapshots, telemetry |

## Reference

- [Using the App](/docs/using-the-app) — the same workspace from the browser or desktop UI
- [Command Reference](/docs/cli/command-reference) — every top-level command in one table

Source: /raw/cli/index.mdx

### cli/knowledge-and-rag.mdx

---
title: Knowledge and RAG
description: Manage knowledge sources, search the index, reindex folders, and seed assistant documentation from the CLI.
---

The CLI exposes two complementary surfaces for retrieval-augmented generation:

- **`knowledge`** — source lifecycle (list, add, remove, reindex, status) plus workspace search.
- **`rag`** — agent-facing retrieval and ingestion helpers (`search`, `ingest`, `status`).

Both commands call the sidecar. Loader credentials are **never** passed on the command line — provision secrets with `vault put` or `secrets set` first, then reference a `location` when adding a source.

## Prerequisites

```bash
akos serve          # local sidecar (or point AKOS_HEADLESS_URL at a remote sidecar)
akos knowledge list
```

## Manage sources

### List sources

```bash
akos knowledge list
akos knowledge list --json
```

### Add a source

```bash
# Local folder
akos knowledge add my-docs ./docs/product

# Remote kinds (credentials resolved server-side)
akos knowledge add handbook https://example.com/docs --kind url --name "Product handbook"
akos knowledge add repo-docs github:org/repo --kind github
```

| Flag | Description |
|---|---|
| `--kind` | `folder`, `url`, `s3`, `notion`, `drive`, or `github` (default: `folder`) |
| `--name` | Display name (defaults to the source id) |
| `--json` | Emit the created source as JSON |

### Remove a source

```bash
akos knowledge remove my-docs
```

Drops the source and its index.

### Reindex

```bash
akos knowledge reindex my-docs
# alias:
akos knowledge rebuild my-docs
```

Queues a full digest rebuild for one source.

### Indexer status

```bash
akos knowledge status
akos knowledge status --json
```

## Search

Search the workspace index (alias: `query`):

```bash
akos knowledge search "how do I configure egress"
akos knowledge search "onboarding checklist" --source my-docs --top-k 10 --json
```

The companion `rag` command exposes the same retrieval path for automation:

```bash
akos rag search "sandbox policy" --top-k 5 --json
akos rag ingest my-docs
akos rag status --json
```

Use `knowledge` when managing sources; use `rag` when scripting retrieval inside agent tooling.

## Seed assistant documentation (operators)

To index the shipped documentation corpus so the in-app assistant can retrieve repo docs (beyond the always-on contract catalog), use the ledgered production seed:

```bash
# Preview what would be registered
akos prod seed --target assistant-knowledge --dry-run

# Apply folder sources + record the seed ledger
akos prod seed --target assistant-knowledge --apply

# Rebuild indexes after apply
akos knowledge reindex assistant-knowledge-for-agents
akos knowledge reindex assistant-knowledge-user-docs
```

| Flag | Description |
|---|---|
| `--dry-run` | Report planned/missing/stale seed entries without writing |
| `--apply` | Apply missing or stale seeds and update the ledger |
| `--force` | With `--apply`, re-apply even when checksums already match |
| `--target` | `demo` (default) or `assistant-knowledge` |
| `--vertical` | Limit demo seeds to one vertical pack |
| `--base-dir` | Override the packs directory |

Until rebuild completes, fumadocs pages are not in assistant RAG folder search — the contract catalog in the system prompt is always on.

## Demo vertical packs

Materialise demo pack fixtures into sidecar stores (development / sales demos):

```bash
akos seed --vertical coding
akos prod seed --target demo --dry-run
akos prod seed --target demo --apply --vertical finance
```

Set `AKOS_DEMO_PACKS=1` in the sidecar environment when demo packs are gated in your deployment.

## Related topics

- **[Knowledge in the app](/docs/using-the-app/knowledge)** — UI for sources and flow RAG nodes.
- **[Integration setup](/docs/using-the-app/integration-setup)** — OAuth providers for Notion/Drive/GitHub sources.
- **[Authentication](/docs/cli/authentication)** — `vault put` and `secrets set` for loader credentials.
- **[Command reference](/docs/cli/command-reference)** — full `knowledge` / `rag` / `prod seed` tables.

Source: /raw/cli/knowledge-and-rag.mdx

### cli/migrating.mdx

---
title: Migrating to AKOS
description: Bring your existing automations with you — import flows from n8n, LangChain, LangGraph, Langflow, Flowise, and Dify, and migrate local data to the cloud.
---

AKOS is designed to sit on top of what you already have, not to make you start over. If you have already built automations in another tool, you can bring them across instead of rebuilding them by hand. And when you outgrow a local deployment, you can move your data to the cloud without losing history.

## Importing from other tools

The `akos import` command translates a third-party workflow export into an AKOS config (agents + flows). It auto-detects the source format, or you can force it with `--source`.

Supported sources: **n8n**, **LangChain**, **LangGraph**, **Langflow**, **Flowise**, and **Dify**.

```bash
akos import ./my-export.json
```

This prints the resulting AKOS config (YAML) to stdout. To write it to a file:

```bash
akos import ./my-export.json --out akos.config.yaml
```

To push the converted flows straight into a running workspace via the sidecar (instead of writing a file):

```bash
akos import ./my-export.json --apply
```

### Flags

| Flag | Purpose |
|---|---|
| `--out <path>` | Write the resulting YAML to a file instead of stdout. |
| `--apply` | Upsert the converted flow(s) directly into the running workspace via the sidecar. Mutually exclusive with `--out`. |
| `--source <id>` | Force the importer source (`n8n`, `langchain`, `langgraph`, `langflow`, `flowise`, `dify`) instead of auto-detecting. |
| `--workspace <id>` | Override the workspace id from the imported file. |
| `--quiet` | Suppress the warning summary. |

### What gets converted, and warnings

The importer maps the source's nodes and connections onto AKOS **agents** and **flows**. Constructs that have no direct AKOS equivalent are reported as warnings at the end of the run — the import still succeeds, and the warnings tell you exactly what to wire up by hand afterward. Review the generated config, fill in any flagged gaps, then validate it:

```bash
akos config validate akos.config.yaml
```

## Migrating local data to the cloud

When you start on the desktop app or a local deployment and later move to the multi-tenant cloud, `akos migrate-to-cloud` streams your local state (the SQLite filesystem store) into a cloud Postgres + object-store target.

```bash
akos migrate-to-cloud \
  --org <orgId> \
  --source ~/.agentskit \
  --target postgres://... \
  --dry-run
```

| Flag | Purpose |
|---|---|
| `--org <orgId>` | The target cloud organization. |
| `--source <path>` | The local state directory to migrate from. |
| `--target <url>` | The destination Postgres connection string. |
| `--dry-run` | Print the migration plan only — no writes. |
| `--resume` | Resume an interrupted migration from its checkpoint. |

The migration is **idempotent** (rows insert with conflict-skip, blobs already present are skipped) and **resumable** — a checkpoint file at `<source>/.migrate-checkpoint.json` lets an interrupted run pick up where it left off. Run with `--dry-run` first to review the plan before applying.

## Related topics

- **[Workflows in the app](/docs/using-the-app/flows)** — review imported flows in the visual editor.
- **[Agents in the app](/docs/using-the-app/agents)** — registry entries materialized from imports.
- **[Configuration](/docs/cli/configuration)** — validate, diff, and lock the config your import produces.
- **[Getting Started](/docs/getting-started)** — the three ways to run AKOS (web, desktop, CLI).

Source: /raw/cli/migrating.mdx

### cli/pipelines.mdx

---
title: Processes (Pipelines)
description: List processes, dispatch multi-phase pipeline runs, and resume or cancel runs paused at approval gates.
---

The `pipelines` command family operates **processes** — ordered phases that chain flows with JSONPath data handoff and optional human approval gates. The UI calls them **Processes**; the RPC namespace is `pipelines.*` (with deprecated `sdlc.*` aliases).

All `pipelines` verbs require a running sidecar (`akos serve` locally, or `AKOS_HEADLESS_URL` for remote).

## List processes

```bash
akos pipelines list
akos pipelines list --json
```

## Inspect one process

```bash
akos pipelines show my-release-pipeline --json
```

Exits with code `5` when the id is not found.

## List process runs

```bash
akos pipelines runs
akos pipelines runs --pipeline my-release-pipeline --limit 20 --json
```

## Dispatch a new run

```bash
akos pipelines run my-release-pipeline
```

Pass initial context as JSON:

```bash
akos pipelines run my-release-pipeline \
  --ctx '{"ticketId":"ENG-4821","owner":"alice"}' \
  --idempotency-key eng-4821-2026-07-05
```

In CI or other non-TTY environments, mutations require explicit confirmation:

```bash
akos pipelines run my-release-pipeline --confirm --json
```

| Flag | Description |
|---|---|
| `--ctx <json>` | JSON object passed as run context |
| `--idempotency-key <key>` | Dedupe duplicate dispatches |
| `--confirm` | Skip the interactive confirmation prompt |
| `--json` | Emit the raw dispatch payload |

## Resume after approval

When a phase requires human approval, the run pauses until a reviewer acts in the **[Inbox](/docs/using-the-app/inbox)** (or via `inbox approve` / `hitl approve`). Resume the process run from the CLI:

```bash
akos pipelines resume pipe_run_abc123 --json
```

## Cancel an in-flight run

```bash
akos pipelines cancel pipe_run_abc123
akos pipelines cancel pipe_run_abc123 --confirm   # non-TTY
```

## Typical operator loop

```bash
akos pipelines list
akos pipelines run quarterly-close --ctx '{"period":"2026-Q2"}' --confirm
akos pipelines runs --pipeline quarterly-close --limit 5
# … reviewer approves in Inbox …
akos pipelines resume <pipelineRunId>
```

## Related topics

- **[Processes in the app](/docs/using-the-app/pipelines)** — kanban board, chain view, column settings.
- **[Flows and Runs](/docs/cli/flows-and-runs)** — single-flow execution and HITL escalations.
- **[Inbox](/docs/using-the-app/inbox)** — human approval tasks for gated phases.
- **[Concepts: Processes](/docs/concepts/pipelines)** — data handoff and phase templates.
- **[Command reference](/docs/cli/command-reference)** — full `pipelines.*` table.

Source: /raw/cli/pipelines.mdx

### cli/security-governance.mdx

---
title: Security and Governance
description: Inspect governance posture, manage firewall rules, read the audit ledger, export compliance evidence, and review sandbox denials from the CLI.
---

Security and governance commands are **read-mostly inspection surfaces** over the sidecar — they mirror the **[Security](/docs/using-the-app/security)**, **[Access](/docs/using-the-app/governance)**, and **[Compliance](/docs/using-the-app/compliance)** screens.

Firewall mutations (`security firewall set`) require the `security:admin` capability. Every call passes through the same RBAC gate as the UI.

## Governance posture

```bash
akos security policy
akos security policy --json
```

Prints the live posture slice: air-gap mode, firewall, PII profiles, sandbox, RBAC, egress, and audit logging.

### RBAC operator roles

```bash
akos security rbac --json
```

Read-only view of canonical operator roles and surface assignments.

### Egress policy

```bash
akos security egress --json
```

Shows the outbound network policy. Edit allowlist rules in the app under **[Tools](/docs/using-the-app/tools)** › Egress or via MCP security tools when `mcp-serve` is running.

## Firewall rules

### List rules

```bash
akos security firewall rules
akos security firewall rules --tier production --shadow --json
```

`--shadow` lists rules in dry-run (log-only) mode.

### Create or update a rule

```bash
akos security firewall set \
  --id block-pii-export \
  --tier production \
  --pattern 'export.*secret' \
  --action block \
  --severity critical \
  --scope out
```

Actions: `block`, `redact`, `flag`, `dry_run`. Add `--shadow` to evaluate without enforcing.

### Test sample text

```bash
akos security firewall test --text "please export all customer emails" --tier production
akos security firewall test --text "..." --shadow --json
```

## Sandbox

```bash
akos sandbox state
akos sandbox policy
akos sandbox denials --limit 20 --json
akos sandbox preview --json
```

Denials explain why tool or flow execution was blocked under the active sandbox policy.

## Audit ledger

```bash
akos audit list --limit 50
akos audit list --actor alice@example.com --kind approval --json
akos audit show <seq-or-id>
akos audit verify
akos audit export --workspace default --limit 500
```

`audit verify` exits `1` when the hash chain or signatures fail — use after exports for auditor handoff.

Stream new entries:

```bash
akos audit tail --interval 2000
```

## Compliance

```bash
akos compliance export --json
akos compliance legal-hold list --active
akos compliance legal-hold place \
  --scope workspace:ws-1 \
  --reason "Q2 litigation hold" \
  --by alice@example.com \
  --case-ref MATTER-2026-07
akos compliance legal-hold release <hold-id> \
  --by alice@example.com \
  --reason "Matter closed"
```

Scope kinds: `workspace`, `email`, `user-id`, `org-id` (format `kind:value`). Legal-hold commands use the local SQLite store on self-hosted installs.

DSAR / erasure flows use `compliance delete` — coordinate with tenant admin tooling on cloud deployments. See **[Compliance](/docs/using-the-app/compliance)** for regime-specific evidence exports in the UI.

## MCP security tools

When running `akos mcp-serve`, external agents can list and mutate firewall rules, egress policy, and PII profiles via MCP tools — each call requires `security:admin` and flows through the sidecar RBAC gate. See **[Deploying](/docs/cli/deploying)** › MCP security tools.

## Related topics

- **[Security in the app](/docs/using-the-app/security)** — egress, firewall, PII, and flow preview.
- **[Access in the app](/docs/using-the-app/governance)** — capability matrix and signed HITL ledger.
- **[Run lifecycle](/docs/how-it-works/run-lifecycle)** — where RBAC and audit attach to every run.
- **[Authentication](/docs/cli/authentication)** — session identity used for capability checks.
- **[Command reference](/docs/cli/command-reference)** — full `security`, `sandbox`, `audit`, and `compliance` tables.

Source: /raw/cli/security-governance.mdx

### cli/triggers.mdx

---
title: Triggers
description: Add, list, remove, and test flow triggers from the command line, and browse built-in trigger presets.
---

Triggers define when and how a flow starts: on a schedule, in response to a webhook, when a file appears, or on a platform event. The `triggers` and `trigger preset` commands manage triggers in your workspace config and interact with the running sidecar.

## Listing trigger kinds

To see all supported trigger kinds and their required parameters:

```bash
akos triggers kinds
```

## Listing triggers in a config

```bash
akos triggers list
```

By default this reads `akos.config.yaml` in the current directory. Pass a different path with `--config <path>`.

## Adding a trigger

```bash
akos triggers add \
  --flow <flow-id> \
  --kind <kind> \
  [kind-specific options]
```

For example, to add a cron trigger that fires every day at 09:00:

```bash
akos triggers add \
  --flow daily-report \
  --kind cron \
  --cron "0 9 * * *"
```

To add an inbound webhook trigger:

```bash
akos triggers add \
  --flow inbound-webhook \
  --kind webhook
```

Check `akos triggers add --help` for the full list of kind-specific flags.

## Removing a trigger

```bash
akos triggers remove <trigger-id>
```

Pass `--config <path>` to target a specific config file.

## Testing a trigger

Sends a synthetic event through the sidecar to verify a trigger is wired correctly:

```bash
akos triggers test <trigger-id>
```

## Viewing trigger run history

List recent executions for a trigger:

```bash
akos triggers runs <trigger-id>
```

## Getting the inbound URL for a webhook trigger

```bash
akos triggers url <trigger-id>
```

Prints the inbound URL that external systems should POST to.

## Enabling or disabling a trigger

```bash
# Disable a trigger
akos triggers toggle <trigger-id> --disable

# Re-enable it
akos triggers toggle <trigger-id> --enable
```

## Listing trigger contracts

To list every registered trigger contract (the trigger kinds the sidecar knows how to dispatch) via the running sidecar:

```bash
akos triggers contracts
```

Add `--json` for structured output. This requires the sidecar (`akos serve`).

---

## Trigger presets

AKOS ships curated trigger presets — ready-to-copy configurations for common scenarios. Presets are read-only reference material; use them as a starting point when adding triggers.

### List presets

```bash
akos trigger preset list
```

Output as JSON:

```bash
akos trigger preset list --json
```

### Show a preset

```bash
akos trigger preset show webhook/inbound-generic
```

The command prints the preset's title, description, and the full trigger configuration block you can copy into your config.

Output as JSON:

```bash
akos trigger preset show webhook/inbound-generic --json
```

---

## Making your workspace reachable for webhooks

By default the sidecar binds its webhook listener to `127.0.0.1` (loopback only). To receive webhooks from external systems, start the sidecar with `--public`:

```bash
akos serve --public
```

Pin the webhook port:

```bash
akos serve --public --webhook-port 4242
```

When `--public` is used, the CLI prints a security warning. Run behind a firewall or trusted tunnel and ensure every webhook trigger verifies its signature.

## Related topics

- **[Automations in the app](/docs/using-the-app/triggers)** — trigger list, webhook server banner, inline editor.
- **[Public automation API](/docs/using-the-app/public-automation-api)** — scoped API keys for external dispatch.
- **[Workflows in the app](/docs/using-the-app/flows)** — bind triggers to flow graphs.
- **[Flows and Runs](/docs/cli/flows-and-runs)** — execute and inspect runs started by triggers.

Source: /raw/cli/triggers.mdx

### concepts/access-control.mdx

---
title: Access control
description: How AKOS decides who can do what — roles map to capabilities, and sensitive actions like approving a human-in-the-loop step require a specific capability.
---

AKOS controls every significant action with role-based access control (RBAC). The model is simple: **people are assigned roles, roles grant capabilities, and each capability unlocks a specific kind of action.** Sensitive actions — approving a paused run, deciding a release gate, granting emergency access, or reading the audit log — require the matching capability, so they can only be performed by someone whose role allows it.

## Roles map to capabilities

A **role** is a named bundle of **capabilities**. A capability is a fine-grained permission, such as "approve a human-in-the-loop step" or "read the audit ledger". When you assign someone a role, they receive exactly the capabilities that role carries — nothing more.

You manage roles and the capabilities they grant in the [Governance](/docs/using-the-app/governance) screen, using the capability matrix. New members receive the workspace's default role until an administrator assigns them a specific one.

Typical roles and what they can do:

| Role | Can do |
| --- | --- |
| **Viewer** | Read workspace data; cannot approve or change governed actions. |
| **Editor** | Build and run agents, flows, and processes. |
| **Reviewer** | Approve or reject human-in-the-loop steps and release gates. |
| **Auditor** | Read the signed audit ledger. |
| **Admin** | Manage roles and members, grant break-glass access, and perform every governed action. |

Your workspace may define additional or renamed roles — the capability matrix in Governance is the source of truth for your setup.

## Sensitive actions require a capability

Some actions are gated because they carry weight: approving them resumes work, releases code, or grants access. AKOS checks the calling person's capability **before** the action runs, and denies it if they lack the matching capability. Examples:

- **Approving a human-in-the-loop step** (resuming a paused run) requires the *decide HITL* capability — typically held by **Reviewer** and **Admin**.
- **Deciding a release gate** (passing or blocking an SDLC gate) requires the gate-decide capability — typically **Reviewer** and **Admin**.
- **Requesting break-glass access** (temporary elevated access for an urgent action) requires the break-glass capability — typically **Admin** only.
- **Reading the audit ledger** requires the audit-read capability — typically **Auditor** and **Admin**.

A denied action returns a clear authorization error and is itself recorded, so attempts are visible in the [Governance](/docs/using-the-app/governance) history.

## Enforcement applies everywhere

Capability checks run at the boundary where every action is dispatched, so they apply consistently across all three surfaces — the desktop app, the managed cloud, and the CLI. A request that bypasses the web sign-in layer (for example, a direct or automated client) still passes through the same capability check, so there is no back door around the access model.

## Single-user and local-first

On a single-user, local-first install — the desktop app on your own machine, or a self-hosted sidecar without a separate identity store wired in — there is no team to govern. In that case AKOS resolves you as the **local administrator**, who holds every capability. You get the full product with no setup friction, and the same enforcement seam is still in place: the moment a real identity store is connected (for a team or the managed cloud), the role-to-capability rules take effect automatically.

## Where to go next

- [Governance](/docs/using-the-app/governance) — assign roles, edit the capability matrix, manage members, and review the signed audit trail.
- [Workspaces](/docs/using-the-app/workspaces) — invite members, choose their role, and configure break-glass access.

Source: /raw/concepts/access-control.mdx

### concepts/agents.mdx

---
title: Agents
description: Anatomy of an AKOS agent — model, instructions, tools, context, and governed identity.
---

An agent in AKOS is not just a prompt. It is a small, typed, configured worker — and every part of it is inspectable and governed at runtime.

## Anatomy

```
┌─────────────────────────────────────────────────┐
│  Agent                                          │
│  ┌──────────┐  ┌──────────────┐  ┌───────────┐ │
│  │  Model   │  │ Instructions │  │   Tools   │ │
│  │ (any of  │  │  system      │  │ allowlist │ │
│  │ 30+ LLM  │  │  prompt +    │  │           │ │
│  │ adapters)│  │  role        │  └───────────┘ │
│  └──────────┘  └──────────────┘                │
│  ┌──────────────────┐  ┌────────────────────┐  │
│  │  Context (RAG)   │  │ Identity +         │  │
│  │  scoped knowledge│  │ permissions (DID)  │  │
│  └──────────────────┘  └────────────────────┘  │
└─────────────────────────────────────────────────┘
```

### Model

Any of 30+ LLM adapters inherited from the AgentsKit upstream: Anthropic, OpenAI, Gemini, Bedrock, Azure, Mistral, Groq, vLLM, Ollama, and more. The model is a per-agent config value — swap providers without rewriting the agent or the flow it belongs to. Ollama and vLLM run fully local, enabling air-gapped deployments that never call a cloud API.

### Instructions

A system prompt plus a role description. This is the agent's persistent context — what it knows about itself, its task, and the constraints it should follow.

### Tools

An explicit allowlist of capabilities the agent may call. An agent cannot call a tool that is not on its list. Tool kinds include:

- **Search** — web search or knowledge-base lookup
- **HTTP** — outbound API calls (subject to the workspace egress allowlist)
- **File IO** — read or write files within the sandbox boundary
- **Code execution** — run code inside the isolated sandbox
- **RAG** — retrieve from the agent's knowledge sources
- **SaaS connectors** — Slack, GitHub, Linear, Stripe, and others (require a connected OAuth integration)

### Context (RAG)

Each agent carries a set of knowledge sources it can retrieve from. Retrieval is permission-scoped: an agent only retrieves content its principal's role is allowed to see. The built-in RAG pipeline includes a chunker, embedders, a vector store (pgvector in cloud mode, in-process SIMD in local mode), and a reranker.

### Identity and permissions

Every agent has a **signed identity** — a Decentralized Identifier (DID). It never acts as itself; it always acts **on behalf of a principal** (a human user or a service account). Every action is checked against the principal's role and capability set via RBAC before the handler runs. Every action is written to the signed audit ledger with the principal as the subject, so accountability is always traceable.

## Everything is data

An agent definition is a typed config object. You can edit it three ways — all equivalent, never diverging:

| Mode | Who uses it |
|---|---|
| GUI in the desktop app | Operators and builders |
| YAML file | Version control workflows |
| Code (TypeScript) | Developers extending the system |

## What an agent cannot do

- Call a tool not on its allowlist.
- Access knowledge outside its RAG scope.
- Make a network call to a host not on the workspace egress allowlist.
- Bypass the capability check that guards every RPC handler.
- Leave the sandbox boundary when running code or shell commands.

These constraints are enforced at the runtime layer — they are not advisory rules.

## Related topics

- **[Agents in the app](/docs/using-the-app/agents)** — registry, lifecycle states, sandbox test, version history.
- **[Flows](./flows)** — how agents are invoked inside workflow nodes.
- **[Access control](./access-control)** — roles, capabilities, and signed identity.
- **[Model catalog](/docs/using-the-app/model-catalog)** — choosing models in agent forms.

Source: /raw/concepts/agents.mdx

### concepts/architecture.mdx

---
title: Architecture
description: The two-layer split (AgentsKit upstream + AKOS OS layer), 50+ packages, and the design principles that make them navigable.
---

> This page is the conceptual entry point to how AKOS is structured — layers, packages, and design principles.

## Two layers

AKOS is not written from scratch. It stands on **AgentsKit** — a permissively-licensed (MIT) open-source agent runtime.

```
┌─────────────────────────────────────────────────────────┐
│  AKOS — the OS layer (this repo)                        │
│  Governance · audit · RBAC · visual flow editor ·       │
│  processes · verticals · white-label · multi-tenant ·   │
│  marketplace · desktop app                              │
│  Packages named  os-*                                   │
└────────────────────────┬────────────────────────────────┘
                         │ peerDependency
┌────────────────────────┴────────────────────────────────┐
│  AgentsKit — open-source upstream (MIT)                 │
│  LLM adapters · reasoning & durable runtime ·           │
│  memory backends · tools · skills · RAG primitives ·    │
│  sandbox · evaluation                                   │
│  Packages named  @agentskit/*                           │
└─────────────────────────────────────────────────────────┘
```

**Rule of thumb:** a package starting `os-` lives in this repo; one starting `@agentskit/` comes from [AgentsKit](https://www.agentskit.io) upstream. The hard rule (ADR-0002): never re-implement an upstream primitive — depend on it. Every community improvement to [AgentsKit](https://www.agentskit.io) flows into AKOS for free.

## Five layers, 50+ packages

The codebase is stacked. Each layer may only depend on layers below it — never sideways, never upward. This keeps the runtime, security, UI, and vendor bindings replaceable instead of tangled together.

| Layer | What it contains |
|---|---|
| ① Product & Distribution | Desktop app · white-label engine · marketplace · OEM tenancy — `os-ui`, `os-desktop`, `os-marketplace`, `os-whitelabel`, `os-tenant-config` |
| ② AI Features | RAG · copilot · agent orchestration · dev orchestrator · MCP bridge — `os-rag`, `os-copilot`, `os-coding-agents`, `os-dev-orchestrator`, `os-mcp-bridge` |
| ③ Runtime & Flow | Flow engine (DAG) · triggers · processes · sandbox · sidecar transport · storage bindings — `os-runtime`, `os-flow`, `os-triggers`, `os-sandbox`, `os-headless`, `os-store-postgres`, `os-rag-pgvector`, `os-sandbox-vercel`, `os-egress-hosted` |
| ④ Security & Compliance | RBAC · signed audit ledger · vault · observability · licensing · email · PDF — `os-security`, `os-audit`, `os-observability`, `os-license`, `os-cloud-sync`, `os-telemetry`, `os-errors`, `os-email`, `os-pdf` |
| ⑤ Contracts & Core | Schema layer · error model · dispatcher — `os-core`, `os-contracts`, `os-log`, `os-storage` |

`os-core` is the hub: it defines every typed schema used across the monorepo, is consumed by 60+ packages, and is kept under 25 KB gzipped with zero LLM or UI dependencies (ADR-0013).

## The four design principles

These principles shape every line of code and are documented in full in [Philosophy](/docs/concepts/philosophy).

### Contract-first

A Zod schema validates every boundary — every HTTP call, every JSON-RPC message, every file read. Bad data is rejected at the door. If a contract changes unexpectedly, the build fails. You can trust the types: if the code declares a value is a `FlowConfig`, it was parsed at the boundary and really is one.

### Governed by design

A signed audit ledger, role-based access, sandboxing, an egress allowlist, and human-approval gates live **inside** the runtime — not bolted on as an afterthought. The dispatcher enforces RBAC on every RPC handler before the handler runs. There is no back door.

### Hexagonal / port-first

50+ packages, each structured as a port (interface) + a swappable binding (implementation). Postgres, S3, Vercel Sandbox, Vault, Resend — each is a binding you can replace. Vendor-specific details stay behind those bindings, so there is no lock-in by construction.

### Decisions are documented

Every architectural choice is an Architecture Decision Record (ADR). 98+ ADRs are on file. Changing the architecture requires writing an ADR first. Nothing is folklore.

## The request path

Every action — a click, a webhook, an agent calling a tool — becomes one typed RPC call and takes the same governed path:

```
Caller (UI / webhook / agent)
    ↓
Schema parse       ← Zod validates input
    ↓
Capability check   ← RBAC: may caller do this?
    ↓
Handler runs       ← the actual logic
    ↓
Audit + respond    ← logged to ledger; typed result returned
```

321 handler entries. 0 unmarked stubs. All reachable over both `stdio` and HTTP transport (parity matrix CI-verified).

## Deployment modes

The same sidecar ships in three modes using the same typed protocol:

| Mode | Transport | Storage |
|---|---|---|
| **Desktop** (Tauri) | stdio IPC | SQLite + local FS |
| **Web** (Next.js) | HTTP/WS + JWT | Postgres + pgvector + S3 + Vault |
| **Cloud** (k8s pod) | HTTP + sync gateway WS | Postgres + pgvector + S3 + Vault |

Same flow, same agent, same governance — on a laptop, in a browser, or in a Kubernetes pod.

## Where to go deeper

- [Access control](/docs/concepts/access-control) — how identity, roles, and capability checks work.
- [Philosophy](/docs/concepts/philosophy) — the values and trade-offs behind every design choice.
- [Run lifecycle](/docs/how-it-works/run-lifecycle) — the governed path from trigger to signed audit ledger.
- [Using the App](/docs/using-the-app) — screen-by-screen operator guide (Activity, Governance, Security, Connections).
- [CLI Guide](/docs/cli) — automate runs, triggers, imports, and workspace operations from the terminal.

Source: /raw/concepts/architecture.mdx

### concepts/flows.mdx

---
title: Flows
description: Anatomy of a flow — a DAG of nodes that drives agents to a goal.
---

A **flow** is a DAG (directed acyclic graph) of steps that drives one or more agents toward a goal. `@agentskit/os-flow` executes flows; `@agentskit/os-core` defines the schema.

## Key properties

- **DAG, not a chain.** Cycles are detected at compile time. Branches are first-class citizens.
- **Durable.** Every node writes a checkpoint before executing. A flow can resume after a crash, a redeploy, or a HITL pause — from exactly the point it paused.
- **Run-mode-aware.** Every node respects the `--mode` flag — sandbox, simulate, or live.
- **Time-travel debuggable.** Pick any historical checkpoint and re-execute from that point forward with new inputs or a different agent.
- **Pre-flight cost estimation.** `--estimate` projects token spend and dollar cost before any LLM call is made.

## Node kinds

A flow is composed of nodes. AKOS ships 14+ node kinds:

| Kind | Icon | Description |
|---|---|---|
| `trigger` | ⚡ | Where the flow starts. Connects to the trigger system. |
| `agent` | 🤖 | Runs a configured agent — the primary compute node. |
| `tool` | 🔧 | Calls a single tool directly, without a reasoning step. |
| `condition` | ◆ | Evaluates an expression and routes to one of two branches. |
| `parallel` | ⇉ | Fans out to multiple branches that run concurrently. |
| `human-gate` | ⏸ | Pauses the run until a human approves or rejects. |
| `rag` | 📚 | Retrieves context from a knowledge source and injects it forward. |
| `output` | ⏹ | Ends the flow and saves the artifact. |

## Anatomy of a flow

A real example: a request-triage flow.

```
⚡ Trigger
    ↓
🤖 Agent: classify request
    ↓
◆ Condition: which path?
   ↙            ↘
🤖 Agent:      🤖 Agent:
  standard       escalate
      ↘         ↙
     ⏸ Human gate: approve
           ↓
       ⏹ Output: artifact saved
```

A trigger fires → an agent classifies → a condition branches → the appropriate agent runs → a human approves → the run completes and an artifact is saved.

## Data flow between nodes

Each node receives a typed input and produces a typed output. Downstream nodes declare which upstream outputs they consume via JSONPath selectors. The schema is validated at build time — wiring a node to an incompatible output fails fast.

## Authoring modes

Because a flow is typed data, three editors are interchangeable views of the same underlying contract:

| Mode | Who uses it |
|---|---|
| **GUI** — visual drag-and-drop canvas | Operators and builders |
| **YAML** — committed to version control | Config-driven and GitOps workflows |
| **Code** — TypeScript objects | Developers extending the system |

Switch freely between modes. They never diverge.

## Live execution

When a flow is running:

- The canvas lights up node-by-node as each step executes.
- Token cost is tracked per node in real time.
- Every node write is checkpointed — the run is pausable and resumable.
- A HITL gate sends a notification to the configured approvers and holds the run until they act.

## Related topics

- **[Workflows in the app](/docs/using-the-app/flows)** — visual editor, snapshots, and import wizard.
- **[Triggers](./triggers)** — the 14 GA event sources that start a flow.
- **[Processes](./pipelines)** — chain multiple flows into ordered, multi-phase work.
- **[Quality checks (Evals)](/docs/using-the-app/evals)** — regression-test flows before promotion.
- **[Run lifecycle](/docs/how-it-works/run-lifecycle)** — the full path from trigger to audit ledger.

Source: /raw/concepts/flows.mdx

### concepts/index.mdx

---
title: Concepts
description: The twelve core terms that unlock every screen, doc, and package name in AKOS.
---

AKOS is built around a small vocabulary. Learn these twelve words and every screen, doc, and package name starts to make sense. Each term links to its dedicated page for deeper coverage.

## The big picture

A person owns a process. AKOS turns that process into a **flow**. The flow drives **agents**. Agents use **tools**. Tools touch real systems. Everything in the middle is governed — identity, permissions, sandbox, egress allowlist, cost tracking, signed audit ledger.

```
Operator → Flow → Agents → Tools → Systems
              ↕
          Governance
```

## Twelve-term glossary

| Term | Definition |
|---|---|
| **Agent** | An AI worker — a model + instructions + tools that performs one task. |
| **Tool** | A capability an agent can call: search, HTTP request, file IO, run code. |
| **Flow** | A graph of nodes — agents, tools, conditions, gates — wired together as a DAG. |
| **Node** | One step in a flow. 14+ kinds exist (agent, condition, parallel, human gate, RAG, output, and more). |
| **Process** | A flow of flows: ordered phases, each phase's output feeding the next via JSONPath mapping. |
| **Run** | One execution of a flow or process — traced, costed, and audited from start to finish. |
| **Trigger** | An event that starts a flow: a schedule, a webhook, a file change, a SaaS event, and more. |
| **HITL gate** | A human-in-the-loop pause — the run waits for a person to approve before proceeding. |
| **Vertical** | An industry preset (finance, legal, healthcare, …) — product name, theme, terminology, role defaults, and security posture, all in config data, no new code. |
| **Sidecar** | The background process that actually executes agents, isolated from the UI. Same typed protocol whether running locally, in a browser shell, or in a Kubernetes pod. |
| **RAG** | Retrieval-Augmented Generation — grounding an agent in your real documents and data via a built-in chunker, embedder, vector store, and reranker pipeline. |
| **Artifact** | A saved output of a run — the result, kept and inspectable after the run completes. |

## Where to go next

- **[Why AKOS](./philosophy)** — works in any industry, builds on what you already have, brings your automations with you.
- **[Agents](./agents)** — model, instructions, tools, context, and governed identity in detail.
- **[Flows](./flows)** — DAG structure, node kinds, authoring modes (GUI / YAML / code).
- **[Processes](./pipelines)** — multi-phase flows with data handoff and approval gates.
- **[Triggers](./triggers)** — all 14 GA trigger kinds and OAuth-once auto-registration.
- **[Architecture](./architecture)** — the two-layer split between AgentsKit upstream and the AKOS operating layer, plus the maintained package map.

For the run lifecycle — how a single execution moves from trigger to audit ledger — see **[Run lifecycle](/docs/how-it-works/run-lifecycle)**.

For screen-by-screen product guidance (nav rail, section rails, and operator workflows), start at **[Using the App](/docs/using-the-app)**.

Source: /raw/concepts/index.mdx

### concepts/philosophy.mdx

---
title: Why AKOS
description: The principles behind AKOS — works in any industry, builds on what you already have, and lets you bring your existing automations with you.
---

AKOS is the operating system for AI agents in production. Three principles shape every part of it.

## Works in any industry

AKOS is not built for one vertical. The same engine — agents, flows, processes, governance — runs finance, legal, healthcare, marketing, support, operations, software, and more. Wherever a person owns a process, AKOS can turn that process into governed automation.

An **industry vertical** in AKOS is config data, not new code: a product name, theme, terminology, role defaults, security posture, and a set of templates. Switching or adding a vertical does not require a different build — the same platform adapts to the language and rules of the work.

- Templates, the marketplace, and assets are all filtered by your active vertical, so you see what is relevant to your field.
- The `custom` process phase accepts any flow, which is what makes processes usable in any vertical.

See **[Concepts overview](/docs/concepts)** for how verticals are modeled.

## Use what you already have

AKOS is designed to sit on top of your existing stack, not replace it.

- **Your own models.** Run cloud models or local ones — Ollama and other local providers are first-class, so models can run on your own hardware with no outbound traffic.
- **Your own keys.** Authentication always references a vault key, never a plaintext token. Bring your own provider keys and store them in the keychain or your secrets backend.
- **Your existing tools.** Connect the services you already use — Slack, GitHub, Linear, Discord, Stripe, Twilio, Sentry, PagerDuty, and more — once, then both react to their events and call back out to them from a flow.
- **Your own infrastructure.** Run the multi-tenant cloud, or self-host the desktop app — including fully air-gapped — when data must never leave your network.

See **[Connections](/docs/using-the-app/connections)** and **[CLI authentication](/docs/cli/authentication)** for how providers and secrets are wired.

## Bring your automations with you

You should not have to rebuild what already works. AKOS can import workflows from other tools — **n8n, LangChain, LangGraph, Langflow, Flowise, and Dify** — and translate them into AKOS agents and flows. And when you move from a local deployment to the cloud, your data and run history come with you.

See **[Migrating to AKOS](/docs/cli/migrating)** for the `akos import` and `akos migrate-to-cloud` workflows.

## Related topics

- **[Getting Started](/docs/getting-started)** — the three ways to run AKOS.
- **[Concepts](/docs/concepts)** — agents, flows, processes, triggers, and architecture.

Source: /raw/concepts/philosophy.mdx

### concepts/pipelines.mdx

---
title: Processes
description: Chain flows into ordered, multi-phase processes with automatic data handoff and approval gates.
---

A **process** is the layer above a flow. Where a flow is a DAG of steps inside one agent session, a process is an ordered sequence of **phases** — each phase runs a complete flow, and the output of one phase feeds the input of the next.

> For phase types and `inputMapping` syntax, see [Phase templates](#phase-templates) below.

## Why processes exist

One flow automates one job. A process chains several flows into a supervised, multi-phase line of work — the output of a whole team, as one auditable run. An operator supervising a process board sees every phase of every run at a glance.

## Example: a content production process

```
📥 Intake flow A
      ↓
🔎 Research flow B
      ↓
✍️  Draft flow C
      ↓
⏸  Review — human gate
      ↓
✅ Approve flow D
      ↓
🚀 Deliver flow E
```

Each phase is a full, independently durable flow. If the review gate pauses the run, flows A–C are not re-executed when a reviewer approves.

## Three core mechanisms

### Data handoff

Each phase's output feeds the next via a **JSONPath mapping** you configure in the process definition — no glue code, no manual copy-paste. The `outputKey` of a phase is the root for downstream `inputMapping` selectors. The schema is validated at process compile time.

### Approval anywhere

Any phase can carry `requireApproval: true`. When the phase completes, the run pauses and the configured reviewers are notified. The run resumes only after a reviewer approves (or rejects, sending it to the configured fallback).

### Kanban supervision

The process board shows every phase of every run as a card in a kanban view. One operator can supervise what used to require a full team — intake is queued, drafts are in progress, reviews are waiting, deliveries are done.

## Phase templates

AKOS ships built-in phase templates (`prd`, `issues`, `dev`, `review`, `qa`, `security`, `custom`) plus the full `inputMapping` / `outputKey` schema. The `custom` phase type accepts any flow template, making processes usable in any industry vertical.

## Related topics

- **[Flows](./flows)** — the building block of every process phase.
- **[Processes in the app](/docs/using-the-app/pipelines)** — kanban board, chain view, and process run bar.
- **[HITL gates](./flows#node-kinds)** — how human approval works inside a flow node.
- **[Inbox](/docs/using-the-app/inbox)** — where approval tasks land when a phase requires human sign-off.
- **[Run lifecycle](/docs/how-it-works/run-lifecycle)** — how a process run is traced and audited end to end.

Source: /raw/concepts/pipelines.mdx

### concepts/triggers.mdx

---
title: Triggers
description: The 14 GA trigger kinds that connect a flow to the real world — schedules, webhooks, SaaS events, and more.
---

A **trigger** connects a flow to the real world, so the flow starts on its own when something happens. Without a trigger, someone must press a button every time.

All 14 trigger kinds listed here are generally available — shipped, typed, and CI-verified in every release.

## All 14 GA trigger kinds

| Trigger | Description |
|---|---|
| **Schedule** | Run on a cron schedule — every night, every hour, every Monday. |
| **Webhook** | An external system sends an HTTP POST and the flow fires. |
| **File** | A new or changed file in a watched location starts the flow. |
| **Email** | An inbound email to a configured address triggers the flow. |
| **Postgres CDC** | A change data capture event from a Postgres table triggers the flow. |
| **MySQL CDC** | A change data capture event from a MySQL table triggers the flow. |
| **S3** | A new or modified object in a watched S3 bucket triggers the flow. |
| **Slack** | A Slack event (message, reaction, mention) triggers the flow. |
| **GitHub** | A GitHub event (push, PR, issue, release) triggers the flow. |
| **Linear** | A Linear event (issue created, status changed) triggers the flow. |
| **Discord** | A Discord message or event triggers the flow. |
| **Twilio** | An inbound SMS or call via Twilio triggers the flow. |
| **Sentry** | A Sentry alert or issue event triggers the flow. |
| **PagerDuty** | A PagerDuty incident event triggers the flow. |
| **Stripe** | A Stripe subscription or payment event triggers the flow. |

The eight SaaS providers — Slack, GitHub, Linear, Discord, Twilio, Sentry, PagerDuty, and Stripe — each ship with **both** a trigger node and a tool node driven by the same OAuth connection. Connect a provider once in Integrations, and flows can both react to its events and call back out to it.

## OAuth-once auto-registration

For SaaS providers, you do not paste a webhook URL or configure the provider manually. Connect the provider in the **Integrations** screen and AKOS registers the webhook with the provider on your behalf — automatically, typed, and verified.

## On-demand runs

A button still works. Any flow can be started on demand from the desktop app by an operator, regardless of whether it has a trigger attached.

## How triggers work inside a flow

A trigger is the first node in a flow — a `trigger` node. Its output is the event payload, typed against the trigger's Zod schema, which becomes the initial input to the next node in the DAG. The type is enforced at flow compile time: wiring a Slack trigger output to a node expecting a GitHub payload fails the build.

## Related topics

- **[Automations in the app](/docs/using-the-app/triggers)** — cron, file watch, webhook server, and inline trigger editor.
- **[Flows](./flows)** — how a trigger node fits into a flow DAG.
- **[Connections](/docs/using-the-app/connections)** — how to connect SaaS providers that power trigger and tool nodes.
- **[Public automation API](/docs/using-the-app/public-automation-api)** — scoped API keys for external dispatch.
- **[Run lifecycle](/docs/how-it-works/run-lifecycle)** — what happens after a trigger fires.

Source: /raw/concepts/triggers.mdx

### getting-started/build-to-operate.mdx

---
title: Build to operate
description: The verified journey from building an agent with AgentsKit to running it with governance, audit, cost, and HITL on AgentsKit OS.
---

AgentsKit OS is the production destination in the AgentsKit ecosystem. Use this journey when you already know how to build an agent and need to run it with real controls.

## Journey

1. **Build** with [AgentsKit](https://www.agentskit.io/docs) — define tools, adapters, and agent behavior on the foundation library.
2. **Start faster** from the [Registry](https://registry.agentskit.io) when a ready agent matches the problem, then own and adapt the source.
3. **Ship the experience** with [AgentsChat](https://github.com/AgentsKit-io/agentskit-chat) when users need a conversational interface across clients.
4. **Guide ownership** with [Doc Bridge](https://agentskit-io.github.io/doc-bridge/) so agents and contributors land on the correct edit roots and checks.
5. **Apply discipline** with the [Playbook](https://playbook.agentskit.io) before merging agent-produced changes.
6. **Operate** on AgentsKit OS — permissions, egress, audit ledger, cost budgets, HITL approvals, and deployment modes (managed cloud, self-hosted desktop, terminal/CLI).

## Clean quickstart proof

```bash
# 1) Read the public docs entry point
open https://akos.agentskit.io/docs/getting-started

# 2) Install the CLI (see the CLI guide for the current package name and channel)
akos --help

# 3) Confirm the authentication and health commands are available
# The verified help surface lists both `auth status` and `status`.
akos --help
```

## What “operate” means here

| Control | Why it matters |
|---|---|
| Identity + RBAC | Only authorized principals run or approve agent actions |
| Egress allowlists | Agents only call approved tools and destinations |
| HITL gates | Risky steps pause for a human decision |
| Signed audit | Every material action is reconstructible later |
| Cost budgets | Spend is visible and policy-bound |
| Deployment modes | Same contracts for managed cloud and self-hosted |

## Maturity honesty

- Released public docs and CLI surfaces are what this journey covers.
- Experimental package APIs may change; treat them as internal operator knowledge unless a release notes them as stable.
- If a capability is planned or unavailable, the assistant and docs must say so rather than inventing a path.

## Next steps

- [Getting Started](/docs/getting-started) — web, desktop, and CLI entry.
- [How a run works](/docs/how-it-works/run-lifecycle) — trigger to signed audit ledger.
- [CLI command reference](/docs/cli/command-reference) — verbs and capabilities.
- [Using the app](/docs/using-the-app) — screen-by-screen operator guide.

Source: /raw/getting-started/build-to-operate.mdx

### getting-started/cli.mdx

---
title: Using the CLI
description: Authenticate the akos command line and scaffold your first workspace.
---

The `akos` command line operates AKOS from your terminal and CI — authenticate, scaffold a workspace, run flows, manage triggers, and deploy.

## Authenticate

The CLI signs in with a device-code grant and stores your credentials securely on your machine:

```bash
akos auth login
```

Useful related commands:

```bash
akos auth whoami     # show the signed-in identity
akos auth status     # check your session
akos tenant list     # list accessible tenants
akos tenant use <id> # local/self-host tenant switch
akos auth logout     # end the session
```

## Scaffold a workspace

Create a new workspace configuration with sensible defaults:

```bash
akos init
```

You can start from a starter template to get a working agent immediately, then edit it in the app or in your config.

## Operate from the terminal

Common first commands after `akos init`:

```bash
akos doctor --creds          # verify provider keys are present
akos connections guide slack # read setup steps from the registry
akos flows list --json       # inspect inline flows (sidecar required)
akos run akos.config.yaml    # dry-run your first flow
```

## Next steps

- Topic walkthroughs: **[CLI Guide](/docs/cli)** (authentication, connections, flows, pipelines, knowledge, security, costs).
- Full command table: **[Command reference](/docs/cli/command-reference)**.
- Prefer a visual interface? Open the **[web app](/docs/getting-started/web)** instead.

<Callout>The CLI authenticates to the same workspace as the web and desktop apps. Anything you create from the CLI shows up in the app, governed and audited the same way.</Callout>

Source: /raw/getting-started/cli.mdx

### getting-started/desktop.mdx

---
title: Using the Desktop App
description: Run AKOS self-hosted with the desktop app — private and air-gap capable, for regulated environments.
---

The AKOS desktop app runs the full product **self-hosted** on infrastructure you control. It is the right choice when data must never leave your network — regulated industries, air-gapped environments, or strict data-residency requirements.

## What you get

- The same interface as the [web app](/docs/getting-started/web): agents, flows, processes, triggers, connections, governance, observability, and cost.
- **Private by default** — runs on your machines; outbound network access passes an egress allowlist you control.
- **Air-gap capable** — operate with local models and no outbound calls when required.

## Getting set up

The desktop app is provisioned through your AKOS enterprise plan. Your administrator installs it and connects it to your workspace. Once it is running, sign in and you are in the same workspace model described in **[Using the App](/docs/using-the-app)**. For core terminology, see **[Concepts](/docs/concepts)**.

<Callout>Need to automate or operate the self-hosted instance from a terminal or CI? Use the [CLI](/docs/getting-started/cli).</Callout>

Source: /raw/getting-started/desktop.mdx

### getting-started/index.mdx

---
title: Getting Started
description: What AKOS is and the three ways to use it — the multi-tenant web app, the self-hosted desktop app, and the akos CLI.
---

AKOS is the operating system for AI agents in production. It lets your team add governed AI agents to any business process — finance, legal, healthcare, marketing, support, operations — and run them supervised, permissioned, and fully audited.

Wherever a person owns a process, AKOS turns that process into a **flow**, the flow drives **agents**, the agents call **tools**, and everything in between is governed: identity, permissions, sandboxing, an egress allowlist, cost tracking, and a signed audit trail.

Three principles shape the product:

- **Works in any industry.** The same engine runs finance, legal, healthcare, marketing, support, operations, and more — each industry is config data (terminology, roles, templates), not a separate build.
- **Use what you already have.** Bring your own models (including local ones via Ollama), your own provider keys, and your existing tools (Slack, GitHub, Stripe, and more). Run it on your own infrastructure if you need to.
- **Bring your automations with you.** Import existing workflows from n8n, LangChain, LangGraph, Langflow, Flowise, and Dify instead of rebuilding them.

See **[Why AKOS](/docs/concepts/philosophy)** for the full philosophy.

## Three ways to use AKOS

AKOS is one product with three surfaces. They share the same workspace, agents, flows, and governance.

| Surface | Best for | How you get in |
|---|---|---|
| **[Web app](/docs/getting-started/web)** | Teams who want nothing to install | Multi-tenant cloud — sign in to your workspace URL |
| **[Desktop app](/docs/getting-started/desktop)** | Private / regulated / air-gapped deployments | Self-hosted desktop application |
| **[CLI](/docs/getting-started/cli)** | Automation, CI, and power users | `akos` command line |

Not sure which to start with? Most teams begin in the **web app** to build and supervise their first flow, then add the **CLI** to automate runs from CI. Regulated environments that require data never to leave their network run the **desktop app** self-hosted.

## Where to go next

- New to the vocabulary? Read **[Concepts](/docs/concepts)** (agents, flows, processes, triggers, architecture).
- Ready to use the product UI? Start with **[Using the App](/docs/using-the-app)**.
- Follow a run end to end? See **[Run lifecycle](/docs/how-it-works/run-lifecycle)**.
- Automating from your terminal or CI? See the **[CLI Guide](/docs/cli)**.
- Coming from another tool? See **[Migrating to AKOS](/docs/cli/migrating)**.

Source: /raw/getting-started/index.mdx

### getting-started/web.mdx

---
title: Using the Web App
description: Sign in to the AKOS multi-tenant web app and open your workspace — nothing to install.
---

The AKOS web app is a multi-tenant cloud service. There is nothing to install — you sign in to your organization's workspace in the browser.

## Sign in

1. Open your organization's AKOS workspace URL (provided by your administrator).
2. Sign in with your organization credentials.
3. You land in your **workspace** — the container for your agents, flows, connections, and audit history. If you belong to more than one workspace, switch between them from the workspace menu.

## What you can do

Once signed in, you have the full AKOS app in the browser:

- Build and configure **agents**, **flows**, and **processes**.
- Connect external systems and manage secrets under **Connections**.
- Schedule and trigger runs, and supervise them live.
- Review the **audit log**, costs, and traces for every run.

See **[Using the App](/docs/using-the-app)** for a screen-by-screen guide. For the underlying vocabulary (agent, flow, process, trigger), start with **[Concepts](/docs/concepts)**.

<Callout>The web app and the [desktop app](/docs/getting-started/desktop) share the same interface. Anything you learn in one applies to the other.</Callout>

Source: /raw/getting-started/web.mdx

### how-it-works/run-lifecycle.mdx

---
title: Run lifecycle
description: Follow one run from trigger to audit ledger — five steps, fully governed at every stage.
---

A **run** is one execution of a flow or process. This is the single most important path in AKOS — every governance feature plugs into it somewhere. Understanding it makes every other screen, metric, and error message legible.

## The five steps

```
01 · START     Trigger fires
               schedule / webhook / button press

02 · CHECK     Permission + schema
               RBAC capability check · input validated against Zod schema

03 · EXECUTE   Sidecar runs nodes
               agents reason · tools fire · data passes between nodes

04 · PAUSE     Human gate (if any)
               run holds · reviewer is notified · resumes on their decision

05 · FINISH    Artifact + audit
               result saved as artifact · audit ledger entry signed
```

Every step of the way: **sandboxed · token-cost tracked · OpenTelemetry traced · written to the signed audit ledger**.

## Step-by-step detail

### 01 · START

A trigger fires — a cron schedule hits, a webhook arrives, a SaaS event is received, or an operator presses Run. The trigger payload is parsed against the trigger's Zod schema. If the payload does not match, the run is rejected before reaching step 02.

### 02 · CHECK

Two gates before any agent executes:

1. **RBAC capability check** — the dispatcher verifies the caller's principal has the capability required for the flow's entry handler. No capability, no call.
2. **Input schema validation** — the flow's input schema is validated against the (now-typed) trigger payload. Mismatches are rejected with a typed `AgentsKitError`.

There is no path that reaches step 03 without passing both gates.

### 03 · EXECUTE

The sidecar process runs the flow's nodes in DAG order. Key properties during execution:

- **Sandboxed** — agent code and shell commands run in an isolated sandbox. No ambient access to the host, the filesystem, or the network beyond what is explicitly granted.
- **Egress-controlled** — every outbound network call is checked against the workspace egress allowlist before it leaves the process. Silent data exfiltration is structurally impossible.
- **Cost-tracked** — token spend is measured per node and per run. The running total is visible in the UI in real time.
- **OpenTelemetry-traced** — every node execution emits a span. Traces are queryable from the Observability screen and sink to Grafana or any compatible backend.
- **Checkpointed** — every node writes a checkpoint before running. If the process crashes or is redeployed, the run resumes from the last checkpoint.

### 04 · PAUSE (if applicable)

If the flow contains a `human-gate` node, the run pauses at that point. Configured reviewers receive a notification. The run holds its checkpoint indefinitely. On approval, execution resumes from the gate. On rejection, the flow routes to the configured fallback branch (or terminates, if none is configured).

### 05 · FINISH

When the final output node executes:

1. The result is saved as an **artifact** — a typed, inspectable snapshot of the run's output, retained and queryable from the Runs screen.
2. A ledger entry is appended to the **signed audit ledger** — Ed25519-signed, append-only, tamper-evident. The entry records the principal, the action, the outcome, and the timestamp. It cannot be altered after the fact.

## Governance guarantees

| Guarantee | Mechanism |
|---|---|
| Every run is authorized | RBAC capability check at step 02 |
| Every run is sandboxed | Isolated execution at step 03 |
| Every run has a cost record | Per-node token tracking at step 03 |
| Every run is observable | OpenTelemetry spans at step 03 |
| Every run is replayable | Checkpoints at step 03; time-travel from any checkpoint |
| Every run is audited | Signed ledger entry at step 05 |

A run is never a black box. It is authorized, observed, costed, and recorded at every stage.

## What happens when a run fails

If a node throws an unhandled error:

- The failure is recorded in the run's trace with the full error context.
- A Sentry adapter captures the error (if configured).
- The run moves to the `failed` state.
- The checkpoint from the last successful node is preserved. An operator can replay the run from that checkpoint after fixing the underlying issue.
- The audit ledger records the failure — including which node failed and on whose behalf.

## Related topics

- **[Flows](../concepts/flows)** — how a run's DAG of nodes is structured.
- **[Triggers](../concepts/triggers)** — the events that fire step 01.
- **[Inbox](/docs/using-the-app/inbox)** — where human-gate tasks land at step 04.
- **[Results](/docs/using-the-app/assets)** — artifacts saved at step 05.
- **[Governance](/docs/using-the-app/governance)** — the audit ledger and access controls written at step 05 in detail.
- **[Security](/docs/using-the-app/security)** — sandbox, egress, and firewall policy enforced at step 03.
- **[Runs and observability](/docs/using-the-app/runs-and-observability)** — OpenTelemetry tracing and the Grafana sink.

Source: /raw/how-it-works/run-lifecycle.mdx

### index.mdx

---
title: AKOS Documentation
description: Learn how to use AKOS — the operating system for AI agents in production. Guides for the web app, desktop app, and the akos CLI.
---

AKOS lets your team add governed AI agents to any business process — built, supervised, and audited by the people who own the work.

<Cards>
  <Card title="Getting started" description="Choose web, desktop, or CLI and reach a working workspace." href="/docs/getting-started" />
  <Card title="Concepts" description="Learn the vocabulary behind agents, flows, processes, governance, and RAG." href="/docs/concepts" />
  <Card title="Using the app" description="Follow screen-by-screen operating guides for web and desktop." href="/docs/using-the-app" />
  <Card title="Run lifecycle" description="Trace one run from its trigger to the signed audit ledger." href="/docs/how-it-works/run-lifecycle" />
  <Card title="CLI guide" description="Authenticate, configure, run, observe, and govern from the terminal." href="/docs/cli" />
  <Card title="For agents" description="Resolve implementation ownership, handoffs, and required checks." href="/for-agents" />
</Cards>

Looking for a walkthrough of a specific screen? Most screens in the app link directly to the matching page here.

## Machine-readable documentation

- [llms.txt](/llms.txt) is the concise discovery map.
- [llms-full.txt](/llms-full.txt) contains the public, for-agents, and runtime capability corpus.
- Every page exposes its canonical source under `/raw`.

Improving documentation or ownership handoffs? Validate the repository with [Doc Bridge](https://agentskit-io.github.io/doc-bridge/).

Source: /raw/index.mdx

### using-the-app/agents.mdx

---
title: Agents
description: Create, configure, version, and manage the lifecycle of AI agents in AKOS.
---

The Agents screen is where you define the AI assistants that power your workflows. Every agent has an identity, a model, a prompt, tools, skills, memory settings, and a lifecycle state.

## Agent registry

The registry lists all agents in the workspace. You can switch between **card view** and **list view** using the toggle in the toolbar. Use the search box and the filter menu to narrow the list by name, ID, or lifecycle state.

### Lifecycle states

Each agent moves through a controlled lifecycle enforced by the governance engine:

| State | Meaning |
|---|---|
| **Draft** | In development; not used by live flows. |
| **Review** | Submitted for review; pending approval. |
| **Approved** | Cleared for staging; governance gates satisfied. |
| **Staged** | In a pre-production environment; final verification. |
| **Production** | Live and available to flows and triggers. |
| **Deprecated** | Scheduled for removal; still runs existing flows. |
| **Retired** | Decommissioned; preserved for audit. |

To move an agent to the next state, click the **Promote** action on its row. A confirmation dialog explains which governance gates must be satisfied. Unsatisfied gates are listed with actionable hints. You can also demote or retire an agent from the same menu.

## Creating an agent

Click **New agent** in the toolbar. You have four starting options:

- **Blank** — fill in all fields yourself.
- **Template** — choose a pre-built template for your vertical (finance, healthcare, legal, etc.).
- **Natural language** — describe the agent in plain English; AKOS generates a draft you can edit.
- **Import** — import from a YAML/JSON file or a URL.

### Agent form tabs

The new-agent form has two modes: **Simple** (fewer fields) and **Advanced** (all fields). Use the toggle in the form header to switch. The form is split into steps:

**Basic**
- **ID** — unique slug (lowercase, digits, dashes). **Auto-generated from the name** as you type, so you rarely set it by hand. Use the **Advanced** disclosure to override it on creation. Locked after creation.
- **Name** — display name. Required.
- **Description** — short summary shown in cards and lists.
- **Role** — optional role to inherit capabilities and a default model from.
- **Risk tier** — classification used by governance policies.

**Model**
Override the LLM provider and model for this agent, or leave blank to inherit from the assigned role. The model field is a **searchable catalog picker** backed by the live model catalog — over 5,000 models across 140+ providers. Start typing a provider or model name and the dropdown narrows as you type; each result shows the provider, model id, and capability tags such as `reasoning` and `tools`. See [Model catalog](/docs/using-the-app/model-catalog) for how the catalog works and how to pick the right model.

**Prompt**
The agent's **system prompt** — the standing instructions given to the model at the start of every run. Required.

**Skills & Tools**
- **Skills** — high-level named capabilities (for example, `web.search`, `doc.summarize`). You can type a custom skill slug if needed.
- **Tools** — low-level primitives the agent may invoke (for example, HTTP calls, SQL queries, notification sends). Tools are grouped by their integration provider.

**Memory**
Choose how the agent maintains conversation history:

| Mode | Behaviour |
|---|---|
| **None** | No per-agent memory; uses the workspace default if configured. |
| **Ref** | Points to a named workspace memory slot. |
| **Inline** | Defines its own memory backend (file, SQLite, Redis, vector store). |

For inline memory, fill in the backend-specific fields (path, Redis URL, vector provider, collection, dimensions, embeddings model).

**Advanced**
Additional settings for timeouts, retry policy, and output schema (available in Advanced mode).

Click **Create draft** to save the agent in draft state. You can review and submit from any step using **Next** / **Back**.

## Editing an agent

Click **Edit** on any agent row or card. The same multi-step form opens with the agent's current values. The **ID** field is locked because changing an agent's ID would break all references to it.

## Testing an agent (sandbox)

Click **Test** on an agent to open the **Sandbox drawer**. Enter a test prompt and run the agent in isolation. The result panel shows the model's response, tool calls made, and cost.

## Version history

Click **Versions** on an agent to open the **Version history drawer**. This shows every saved snapshot of the agent, with timestamps and the actor who made each change.

- Select a version in the left panel to see a **diff** against the current live version in the right panel.
- To roll back, click **Rollback** next to the version you want. You will be asked to enter an optional reason. The rollback mints a new version pointing back at the selected snapshot — no history is lost.

## Bulk operations

Check multiple agents in list view to activate the **bulk toolbar**. You can promote or retire a selection of agents at once, or delete a set of drafts.

## Related screens

| Need | Go to |
|---|---|
| Use agents in flows | [Workflows](/docs/using-the-app/flows) |
| Regression testing | [Quality checks (Evals)](/docs/using-the-app/evals) |
| Coding agents | [Coding](/docs/using-the-app/coding) |
| Multi-agent layouts | [Route-only screens](/docs/using-the-app/route-only-screens) (`topologies`) |
| Model selection | [Model catalog](/docs/using-the-app/model-catalog) |

Source: /raw/using-the-app/agents.mdx

### using-the-app/assets.mdx

---
title: Assets
description: Browse, preview, and manage every output produced by your workflow runs across all verticals.
---

The Assets screen is the output gallery for your workspace. Every document, code file, image, or structured data file produced by a workflow run is stored here.

## Filter bar

At the top of the screen, a filter bar lets you narrow the visible assets:
- **Vertical** — filter by which vertical produced the asset (finance, healthcare, legal, coding, or all).
- **Kind** — filter by asset type (document, code, image, data, etc.).
- **Search** — free-text search against file names and metadata.
- **Run filter** — when you navigate here from a specific run's detail panel, a banner shows which run is being filtered. Click **Clear** to remove the run filter.

## Asset grid

Assets are shown in a responsive grid. Each card shows a thumbnail (or file-type icon), the asset name, kind badge, vertical, and the run that produced it.

- Click an asset card to select it and preview it in the right-hand preview panel.
- Check multiple cards to activate the **bulk toolbar** (see below).

## Preview panel

The right-hand panel shows the full content of the selected asset:
- **Documents** — rendered text or markdown.
- **Code files** — syntax-highlighted source code.
- **Images** — inline image preview.
- **Data files** — formatted JSON or CSV table.

The preview panel also shows version history for the selected asset. Click a previous version to see its content, or use the diff view to compare two versions side by side.

## Bulk toolbar

Select multiple assets to activate the bulk toolbar. Available actions:
- **Export** — download all selected assets as a ZIP archive.
- **Delete** — permanently delete the selected assets.
- **Clear selection** — deselect all.

## Version history

Click **Versions** on any asset to open the version history drawer. It lists every version with its timestamp and size. Select a version to diff it against the current version. This is useful when a workflow produces iterative drafts of a document and you want to see what changed between runs.

## Related screens

| Need | Go to |
|---|---|
| Source run | [Activity](/docs/using-the-app/runs-and-observability) |
| Workflow that produced output | [Workflows](/docs/using-the-app/flows) |
| Coding-agent artifacts | [Coding](/docs/using-the-app/coding) |

Source: /raw/using-the-app/assets.mdx

### using-the-app/coding.mdx

---
title: Coding Agents
description: Compose programming tasks, run them with AI coding agents, preview artifacts, and hand off to reviewers.
---

The Coding screen is a specialised interface for AI-assisted software development tasks. Use it to write code, run automated code reviews, and hand off results to workflows or human reviewers.

## Layout

The screen is split into two columns:
- **Left column** — task composer and recent runs list.
- **Right column** — run panel, output artifacts, follow-up actions, provider status, and conformance.

## Composer

The Composer is where you define a coding task:
- **Task description** — describe what you want the agent to do (for example, "Add pagination to the user list endpoint").
- **Provider** — select which coding agent provider to use from the dropdown.
- **Profile** — choose a saved profile that pre-configures the provider, model, and constraints.
- **Working directory** — the local folder the agent will read from and write to. On the desktop app, click the folder icon to browse for a directory.
- **Dry run** — run without writing any files; useful for previewing what changes would be made.

Click **Run** to start the task.

## Recent runs

Below the composer, a list of recent coding runs shows each run's task description, provider, and status. Click any recent run to reload its result in the right panel. Click **Clear** to remove the history.

## Run panel

While a task is running, the run panel shows:
- A progress indicator and elapsed time.
- The current phase (planning, writing, testing, etc.).
- A **Cancel** button to stop the run.

When the run completes, the panel shows the final status and a summary.

## Artifact tabs

After a run, the artifact tabs show everything the agent produced:
- **Diff** — a unified diff view of all file changes the agent made.
- **Files** — individual file previews (new files, modified files).
- **Shell** — terminal output from any commands the agent ran.
- **Timeline** — a chronological log of tool calls made during the run.

## Follow-up actions

Below the artifact tabs, follow-up action buttons let you:
- **Re-run** — re-run the task with the same inputs.
- **Open in flow** — send the task result as input to a workflow.
- **Request review** — create a review task in the Inbox for a human reviewer.

## Provider grid

The provider grid shows all configured coding agent providers and their availability status. Providers that are not connected show a **Set up** link that navigates to **Connections > Coding agents** — the central place to configure all coding agent provider credentials.

## Conformance panel

The conformance panel runs automated checks against the agent's output to verify it meets configured standards (for example, code style rules, security scanning, test coverage thresholds). Each check shows a pass/fail badge and any findings.

## Profile manager

Profiles save a set of provider, model, and constraint settings so you can switch between configurations quickly. Click **+ New profile** to create one, or edit an existing profile by clicking its name.

## Related screens

| Need | Go to |
|---|---|
| Provider credentials | [Connections](/docs/using-the-app/connections) › Coding agents |
| Route-only screen (`coding`) | [Route-only screens](/docs/using-the-app/route-only-screens) |
| Human review handoff | [Inbox](/docs/using-the-app/inbox) |
| Send output to a workflow | [Workflows](/docs/using-the-app/flows) |
| Model selection | [Model catalog](/docs/using-the-app/model-catalog) |

Source: /raw/using-the-app/coding.mdx

### using-the-app/compliance.mdx

---
title: Compliance
description: Export signed evidence bundles, manage legal holds, and queue DSAR requests.
---

The **Compliance** screen (Governance pillar) is the in-product compliance workspace. It is a thin UI over existing `compliance.*` RPC handlers — no separate backend.

## Evidence export wizard

Generate signed, regime-specific evidence bundles from the audit ledger between a `from` / `to` date range.

Supported regimes: **SOC 2**, **HIPAA**, **GDPR**, **CCPA**, and **ISO 27001**.

The result card shows bundle summary, manifest download, and verification hints. Exports are suitable for auditor handoff when your retention and legal-hold posture is current.

## Legal holds

- **List** active holds (`compliance.legalHold.list`).
- **Place** a hold on a scope (`compliance.legalHold.put`).
- **Release** when preservation is no longer required (`compliance.legalHold.release`).

Holds affect retention pruning — check **Prune status** before assuming old data was removed.

## DSAR queue

List and create data-subject access or erasure requests (`compliance.dsar.list`, `compliance.dsar.create`). Erasure cascades are coordinated with tenant admin tooling on cloud deployments.

## Retention and GC status

**Prune status** and **GC status** show whether retention executors and cloud garbage collection are wired and when they last ran. These are read-only indicators for operators.

## Related screens

| Need | Go to |
|---|---|
| Raw audit entries | [Governance](/docs/using-the-app/governance) › Audit |
| Security posture | [Security](/docs/using-the-app/security) |
| Quality / benchmark evidence | [Quality checks (Evals)](/docs/using-the-app/evals) |
| OEM admin compliance ops | Admin app `/compliance` (operator console) |

Source: /raw/using-the-app/compliance.mdx

### using-the-app/connections.mdx

---
title: Connections
description: Configure LLM providers, OAuth integrations, secrets, SQL connections, output sinks, and workspace sync.
---

The Connections screen (labelled **Integrations** in the navigation) centralises every external system that AKOS talks to. For assistant-guided or registry-backed setup steps (OAuth scopes, bot installs, health checks), see **[Integration setup](/docs/using-the-app/integration-setup)**. Sections are organised into three groups in the left-hand section rail:

## Inbound

### Providers

LLM providers that agents can use to run inference. Each provider card shows:
- Provider name and logo.
- Connection state: **Connected** (key verified), **Configured** (key saved but not verified), or **Not connected**.
- A **Verify** button to test the key.
- A **Configure** button to add or update the API key.

Only connected or configured providers appear in the agent model picker.

Supported provider types include cloud AI services and local providers (for example, Ollama running on the same machine).

### External integrations

OAuth-based connections to third-party SaaS applications. Each card shows the provider, its connection state, and a **Connect** button that launches the OAuth flow. Connected integrations can be used by agent tools and trigger webhooks.

Open the **External apps** catalog entry to manage scoped automation API keys:

- Create org-scoped keys limited to one or more automation ids (`automations:run`, `runs:read` scopes).
- Copy the raw secret **once** at creation — AKOS stores only a hash afterward.
- Revoke keys when an external integration rotates credentials.

Use these keys from server-side code only. See **[Public automation API](/docs/using-the-app/public-automation-api)** for `/v1/automations/*` request shapes and security notes.

### Coding agents

Configuration hub for AI coding agent providers (for example, Claude, GitHub Copilot, or a locally-hosted model). Each provider card shows its connection state and a **Configure** button to set the API key or endpoint. Provider settings entered here appear automatically in the Coding screen's provider dropdown.

> The coding agent provider list is managed in the Connections screen so that all external integrations live in one place. Use the Coding screen for running tasks; use this tab to add or rotate credentials.

### Knowledge sources

A read-only summary of RAG knowledge sources configured for this workspace. This tab shows which sources are indexed and their current status. To add, remove, or rebuild sources, navigate to the **[Knowledge](/docs/using-the-app/knowledge)** screen.

> This tab was added so that all inbound data integrations — LLM providers, OAuth apps, coding agents, and RAG sources — are visible together in Connections.

## Outbound

### Output sinks

Destinations where AKOS sends workflow outputs (for example, a Slack channel, an email address, or a custom HTTP endpoint). Click **Add sink** to configure a new destination, choosing the channel type and its settings.

### Exporters

Telemetry exporters that forward AKOS observability data to external monitoring systems (for example, OpenTelemetry collectors, Datadog, or custom NDJSON sinks). This section is only available in deployments with the observability cluster enabled.

## Workspace

### External secrets

References to secrets stored in an external vault (for example, HashiCorp Vault, AWS Secrets Manager). Instead of storing a raw API key in AKOS, you store a vault reference (`vault://path/to/secret`). AKOS resolves the reference at runtime.

To add an external secret reference:
1. Click **Add secret**.
2. Enter a local alias (the name agents and flows will use to look up the secret).
3. Enter the vault URI.
4. Save.

### SQL connections

Named database connections that agents with SQL tools can use. Click **Add connection** to fill in the connection form:
- **Name** — the identifier used in SQL tool calls.
- **Driver** — PostgreSQL, MySQL, SQLite, or other supported drivers.
- **Connection string** — the database URL. For sensitive credentials, use an external secret reference instead of a raw password.

Click **Test** to verify the connection before saving.

### Cloud sync

Sync workspace configuration and agent data to a cloud storage backend (for example, an S3-compatible bucket). When enabled, the workspace can be restored from the cloud backup on a new machine. Configure the bucket URL, credentials, and sync interval.

### Collab

Real-time collaboration settings — connect your workspace to a shared CRDT-based sync server so multiple team members can edit flows simultaneously. Enter the server URL and any authentication tokens required.

## Related screens

| Need | Go to |
|---|---|
| Guided setup flows | [Integration setup](/docs/using-the-app/integration-setup) |
| Knowledge OAuth sources | [Knowledge](/docs/using-the-app/knowledge) |
| External automation keys | [Public automation API](/docs/using-the-app/public-automation-api) |
| Coding agent providers | [Coding](/docs/using-the-app/coding) |
| Evaluation providers | [Quality checks (Evals)](/docs/using-the-app/evals) |

Source: /raw/using-the-app/connections.mdx

### using-the-app/copilot.mdx

---
title: Home (Assistant)
description: The full-page assistant chat — onboarding, slash commands, mentions, and in-product guidance.
---

**Home** (nav id `copilot`) is the assistant-first entry point. Use it to ask questions about your workspace, draft workflows and agents, get setup guidance, and navigate to the right screen without memorising the sidebar.

## First-run onboarding

When `copilot.config.get` reports `onboardingComplete=false`, Home renders **assistant-first onboarding** inside the conversation instead of an empty state:

1. **Display name** — collected as a short text reply.
2. **Assistant name** — collected as a short text reply.
3. **Vertical** — inline `VerticalStep` card (law, healthcare, marketing, coding, or other).
4. **Tool selection** — inline `ToolSelectionStep` card listing integrations and MCP tools for your vertical.
5. **Configuration plan** — inline `ConfigurationPlanStep` card with per-tool setup status and configure actions.
6. **Provider setup** — inline cards for LLM (`LlmProviderCard`), OAuth connectors (`OAuthProviderCard`), or API keys (`ProviderConfigModal`).

Progress is persisted through `onboarding.session.upsert`. Web first-access completion waits until the assistant flow reaches `done`.

## Everyday chat

After onboarding, Home is a full-page chat grounded by workspace RAG (when knowledge sources are indexed — see [Knowledge](/docs/using-the-app/knowledge)).

- **Slash commands** — type `/` to open the slash palette (`copilot.slash.list` / `copilot.slash.parse`).
- **@-mentions** — reference agents, flows, or tools inline (`copilot.mention.parse`).
- **Proactive cards** — system events can surface action cards (`copilot.proactive.fromEvent`).
- **Tool proposals** — destructive actions escalate to the [Inbox](/docs/using-the-app/inbox) for human approval.

## Inline UI in chat

The assistant can render registered inline components (link cards, button groups, run summaries, workflow validation reports, provider setup cards, and onboarding steps). When you ask "show me options" or "where do I configure X", expect an inline card or a navigation button — not instructions to edit files by hand.

## Command palette shortcuts

Press `Cmd K` / `Ctrl K` and search for `copilot`, `assistant`, `chat`, or `help` to jump back to Home from any screen.

## Related screens

| Need | Go to |
|---|---|
| Configure knowledge sources | [Knowledge](/docs/using-the-app/knowledge) |
| Connect OAuth / API keys | [Integrations](/docs/using-the-app/connections) |
| Registry-backed setup steps | [Integration setup](/docs/using-the-app/integration-setup) |
| Approve a risky action | [Inbox](/docs/using-the-app/inbox) |
| See run output | [Activity](/docs/using-the-app/runs-and-observability) |
| Terminal copilot | [Chat (CLI)](/docs/cli/chat) |

Source: /raw/using-the-app/copilot.mdx

### using-the-app/cost.mdx

---
title: Cost
description: Spend rollups, budgets, alerts, and billing context for your workspace.
---

**Cost** (nav label; screen title "Budgets, quotas & usage") is the **Cost Guard** cockpit. It shows live and historical LLM spend, per-provider breakdowns, budget configuration, and — on cloud workspaces — plan and invoice context.

## Layout

The screen uses a tabbed layout:

- **Overview** — top-card totals, sparkline (today / week / month), and provider breakdown table.
- **Budgets** — create, edit, and evaluate spend budgets with alert channels.
- **Alerts** — muted and active budget alerts.
- **Billing** — plan tier, invoices, and backend-computed usage state (cloud only; deep-link via `tab=billing`).

## Budgets and alerts

Each budget defines a spend cap and evaluation window. **Evaluate** runs synchronously against the cost tracker; in-flight runs may not yet be reflected — the UI shows "as of" timestamps from `cost.updatedAt`.

**Reset counters** is destructive: it requires confirmation, writes an audit entry, and should only be used after operator review.

## Cloud vs self-hosted

On self-hosted desktop installs, billing tabs may show a disconnected state honestly — the UI does not synthesize plan or invoice data. Usage limits on cloud tenants come from `usage.state.get` (backend-computed; do not recalculate limits in the UI).

## Deep links

Commercial notifications can open Cost directly on the Billing tab (`tab=billing`). The screen consumes one-shot navigation params after mount.

## Related screens

| Need | Go to |
|---|---|
| Per-run cost | [Activity](/docs/using-the-app/runs-and-observability) run detail |
| Access / RBAC for cost exports | [Governance](/docs/using-the-app/governance) |
| Dashboard spend summary | [Dashboard](/docs/using-the-app/dashboard) |

Source: /raw/using-the-app/cost.mdx

### using-the-app/dashboard.mdx

---
title: Dashboard
description: The AKOS home screen — live KPI stats, activity feed, and quick-access cards for every major feature.
---

The Dashboard is the first screen you see after signing in. It gives you a real-time overview of what is happening in your workspace.

## Layout

The dashboard is divided into four rows:

1. **Hero** — workspace name, sidecar / runtime status, and a run-mode toggle (live vs paused).
2. **Stats grid** — key numbers (active agents, flows run today, open inbox tasks, cost this period).
3. **Next actions** — a short checklist of setup steps that still need to be completed.
4. **Hub grid** — independent cards for each operational area (see below).
5. **Metrics charts** — aggregate time-series charts for runs, cost, and token usage.
6. **Activity feed** — a live stream of events from the current session. You can pause the feed or clear it.

## Hub cards

Each card in the hub grid shows a live summary. Click any card header or its embedded button to navigate to the full screen.

| Card | What it shows |
|---|---|
| **Orchestration** | Recent runs with status badges; links to the Runs screen. |
| **Cost summary** | Spend this period, budget usage, and a trend indicator. |
| **Inbox approvals** | Count of open human-in-the-loop tasks awaiting your decision. |
| **Active flows** | Flows currently running or paused, with run counts. |
| **Triggers** | Live cron and file-watch triggers with their next-fire times. |
| **Agents** | Count of registered agents by lifecycle state (draft/active/retired). |
| **Governance posture** | Current security mode — sandbox, egress rules, firewall, RBAC, audit. |
| **Integrations** | Connected external providers; links to the Connections screen. |

## Activity feed

The activity feed at the bottom of the dashboard is a **live event stream**, styled like a terminal, that shows system events as they happen. Each line includes a timestamp, event type, and a short description. New events append at the bottom in real time as runs progress, agents act, and triggers fire. Click any run event to jump to that run's detail in the Runs screen.

To pause or resume the stream, click the **Pause / Resume** toggle above the feed. To clear the current session's events, click **Clear**.

## Knowing when something is running

You don't have to stay on the dashboard to see that work is in progress. While any run is in flight, AKOS surfaces it everywhere in the app:

- **Top-bar indicator** — a pulsing pill in the app toolbar shows the number of active runs. Click it to jump straight to the Activity (Runs) screen. It disappears when everything is idle.
- **Sidebar badge** — the **Activity** nav item shows a live count of in-flight runs, and both **Activity** and **Workflows** pulse while runs are executing.
- **Toasts** — important outcomes (a run finishing, an approval needed, an export ready) raise a brief app notification.

All of these read the same live source, so the count is always consistent no matter where you look. See [Runs & Observability](/docs/using-the-app/runs-and-observability) for the per-run detail.

## Related screens

| Need | Go to |
|---|---|
| Run detail | [Activity](/docs/using-the-app/runs-and-observability) |
| Pending approvals | [Inbox](/docs/using-the-app/inbox) |
| Spend and budgets | [Cost](/docs/using-the-app/cost) |
| Access policy | [Access](/docs/using-the-app/governance) |
| Integrations | [Connections](/docs/using-the-app/connections) |
| Agent registry | [Agents](/docs/using-the-app/agents) |
| Workflow library | [Workflows](/docs/using-the-app/flows) |
| Scheduled automations | [Automations](/docs/using-the-app/triggers) |

Source: /raw/using-the-app/dashboard.mdx

### using-the-app/evals.mdx

---
title: Evals
description: Run structured test suites against your workflows and track pass rates over time.
---

The Evals screen lets you define test cases for your **[Workflows](/docs/using-the-app/flows)**, run them on demand, and review the results. Use evals to catch regressions before promoting a flow to production.

The screen has three sections in the section rail: **Suites**, **Results**, and **Benchmarks**.

## Suites

A **suite** is a named collection of test cases for a specific workflow. Each test case defines an input and an expected output (or assertion criteria).

**Suite list**
Each row shows:
- Suite name and ID.
- The workflow it is bound to.
- The number of test cases in the suite.
- **Run** — execute all cases in the suite against the current workflow version.
- **Delete** — remove the suite.

If no suites exist, an empty state links to the **Config** editor (route-only screen — see **[Route-only screens](/docs/using-the-app/route-only-screens)**) where you can define them.

**Creating a suite**
Suites are defined in the workspace configuration file (Config editor). Each suite specifies:
- `flowId` — the ID of the workflow to test.
- `cases` — an array of test cases, each with an `input` object and optionally an `expected` object or assertion expression.

## Results

The Results section shows the outcomes of suite runs. Each row shows:
- The suite ID and the time the run started.
- Pass/fail counts and a percentage badge (green for 100% pass, red for any failures).

Click a result to expand the per-case breakdown, showing which cases passed, which failed, and the actual vs expected output for each failure.

If no results exist yet, an empty state prompts you to go to Suites and run one.

## Benchmarks

The Benchmarks section shows standardised benchmark scores for your agents and workflows. Benchmarks measure performance on pre-defined industry datasets or task sets.

Each benchmark row shows:
- The benchmark name and provider.
- The agent or workflow being measured.
- The score and the date it was last run.
- A **Run** button to run the benchmark again.

> Benchmarks require a connected evaluation provider. Configure the provider in the **[Connections](/docs/using-the-app/connections)** screen.

## Related screens

| Need | Go to |
|---|---|
| Workflow under test | [Workflows](/docs/using-the-app/flows) |
| Multi-phase processes | [Processes](/docs/using-the-app/pipelines) |
| Evaluation providers | [Connections](/docs/using-the-app/connections) |
| Suite definitions (Config) | [Route-only screens](/docs/using-the-app/route-only-screens) (`config`) |
| Roles, audit, policy | [Access](/docs/using-the-app/governance) |
| Evidence exports | [Compliance](/docs/using-the-app/compliance) |

Source: /raw/using-the-app/evals.mdx

### using-the-app/flows.mdx

---
title: Workflows
description: Design, run, and version multi-step AI workflows using the visual flow editor.
---

The Workflows screen is the primary place to design and manage your automation flows. A flow is a directed graph of nodes — each node performs one step (run an agent, branch on a condition, call a tool, wait for a human, etc.).

To chain multiple flows into phased business processes (kanban board, approvals, data handoff), use **[Processes](/docs/using-the-app/pipelines)**. To regression-test a flow before promotion, use **[Quality checks (Evals)](/docs/using-the-app/evals)**.

## Workflow library

The screen has two sections accessible from the **section rail**:

- **Workflows** — the editor and the list of saved flows in your workspace.
- **Templates** — pre-built flow templates filtered to your active vertical.

### Workflows section

The editor and the list of saved flows share the main area. To see all saved flows, click the **Workflows** drawer button in the toolbar. A slide-over panel opens with a searchable list. Click any flow to load it into the editor.

From the toolbar you can also:
- **New workflow** — create a blank flow. Its ID is **auto-generated** from the name you give it (a lowercase, dashed slug), so you don't invent one by hand.
- **Import** — open the migration wizard to import a flow from JSON or YAML.
- **Run** — run the currently selected flow.
- **Save** — save the current editor state.
- **Delete** — delete the selected flow after confirmation.

### Templates section

Template cards show the template name, category tag, and description. Click **Use template** to load it into the editor. Templates are filtered to the active vertical (for example, only finance templates appear if your workspace vertical is set to finance). You can see all templates by changing the filter.

## Auto-generated IDs

Across AKOS, anything you create — a workflow, an agent, a connection, a secret provider — gets a stable **ID** derived automatically from the name you type. The ID is a lowercase, dashed slug (for example, *Daily Report* becomes `daily-report`). You'll see it previewed as `ID: …` while you fill in the form.

You almost never set it by hand. When you do need a specific value (to match an external reference, say), open the **Advanced** disclosure on the create form and type an override. Once a record is created its ID is **locked** — changing it would break everything that references it — so the override is only available at creation time.

## Visual flow editor

The editor is a canvas with a **Palette** on the left, a **main canvas** in the centre, and an **Inspector panel** on the right (appears when a node is selected).

### Palette

The palette lists all available node types, grouped by category. Use the search box to find a specific node. Drag any item from the palette onto the canvas to add it.

### Canvas controls

| Control | Action |
|---|---|
| **Undo / Redo** | Reverse or replay the last canvas change. |
| **Align** | Auto-layout all nodes (`Cmd Shift L`). |
| **Trace** | Toggle the last-run trace overlay (shows per-node status, duration, and cost). |
| **Versions** | Open the snapshots drawer to save or restore named canvas versions. |

A minimap and zoom controls appear in the canvas corners.

### Connecting nodes

Drag from a node's output handle to another node's input handle to create an edge. Branch nodes have separate `true` and `false` output handles.

### Node types

**Basic**
| Node | Purpose |
|---|---|
| **Trigger** | The flow's entry point. Configure the trigger kind (cron, webhook, file watch, or inline). |
| **Agent** | Run a registered agent. Pick the Agent ID from your registry; optionally override the system prompt for this node only. |
| **Tool** | Call a specific tool primitive directly, without an agent. |
| **Notify** | Send a notification (email, Slack, webhook) with a message template. |
| **Note** | A sticky note for documenting the canvas (no runtime effect). |

**Control flow**
| Node | Purpose |
|---|---|
| **Branch** | Evaluate a condition; route to the `true` or `false` edge. |
| **Parallel** | Fan out to multiple branches that run concurrently. |
| **Loop** | Repeat a sub-graph a fixed number of times or until a condition is met. |
| **Human** | Pause the flow and send an approval request to human reviewers. |

**Multi-agent**
| Node | Purpose |
|---|---|
| **Multi-agent** | Run multiple agents with a coordination strategy: Auction, Blackboard, Compare, Debate, or Vote. |

**Knowledge**
| Node | Purpose |
|---|---|
| **RAG** | Retrieve relevant context from a knowledge source and pass it to the next node. |

### Inspector panel

When you click a node, the inspector opens on the right. The fields shown depend on the node type.

**Human node inspector**
Configure who must approve:
- **Approvers** — a list of users, roles, email addresses, or capability strings.
- **Quorum** — the minimum number of approvals required before the flow continues.
- **Escalate on timeout** — if checked, set a timeout in minutes and an escalation target; if no one approves in time, the task is reassigned.

### Governance banner

A floating strip along the top of the canvas shows the current governance posture for this flow: sandbox mode, egress rule count, firewall status, audit state, and whether cost metering is active. Click any chip for details.

## Running a flow

Click **Run** in the toolbar. A dialog appears showing the flow name and any declared input fields. Fill in any required inputs and click **Run now**. The dialog closes and a status indicator appears. When the run completes, a **Last run** panel shows the final status, duration, and cost.

## Snapshots (versioning)

Click **Versions** on the canvas toolbar to open the snapshots drawer. You can:
- **Save snapshot** — give the current canvas state a name and save it.
- **Restore** — load a saved snapshot back into the editor.

Snapshots are per-workspace and are separate from the run history.

## Importing existing workflows

Click **Import** in the toolbar to open the migration wizard and bring a workflow over from another tool. Paste or upload the exported definition and AKOS converts it into a native flow.

Supported sources:

- **n8n**
- **LangChain**
- **LangGraph**
- **Langflow**
- **Flowise**
- **Dify**

An import produces three things:

- **A flow** — the converted node graph, ready to open in the editor.
- **Agents** — agent definitions detected in the source are materialized into your registry. LangGraph imports now materialize agents from the graph's LLM/agent nodes, so they arrive as first-class agents rather than opaque steps.
- **Warnings** — a list of anything that could not be mapped cleanly (unsupported nodes, conditional routes that need review, missing credentials). Review the warnings, fix what's flagged, then save the flow.

Conversion is best-effort and lossy in places, so always review the imported flow and its warnings before running it.

## Related screens

| Need | Go to |
|---|---|
| Multi-phase processes | [Processes](/docs/using-the-app/pipelines) |
| Regression testing | [Quality checks (Evals)](/docs/using-the-app/evals) |
| Scheduled / webhook starts | [Automations](/docs/using-the-app/triggers) |
| Agent registry | [Agents](/docs/using-the-app/agents) |
| Starter templates | [Marketplace](/docs/using-the-app/templates-and-marketplace) |
| Full-page editor (`flow-editor`) | [Route-only screens](/docs/using-the-app/route-only-screens) |

Source: /raw/using-the-app/flows.mdx

### using-the-app/governance.mdx

---
title: Governance
description: Manage roles, access policies, team membership, and the full audit trail for your workspace.
---

The Governance screen is where workspace administrators control who can do what, review every access decision, and maintain a tamper-evident record of all significant events.

The screen is divided into three groups in the left-hand section rail:

## Access control

> For how roles, capabilities, and capability-gated actions fit together, see [Access control](/docs/concepts/access-control). Sensitive actions — approving a human-in-the-loop step, deciding a release gate, granting break-glass access, and reading the audit ledger — require the matching capability and are denied for roles that lack it.

### Roles

The Roles section shows the RBAC (role-based access control) configuration for your workspace. A role is a named set of capabilities.

**Capability matrix**
A table lists every role in the workspace as a column, and every registered capability as a row. Check or uncheck a checkbox to grant or revoke a capability for that role. Changes are staged locally; click **Save** to persist them.

**Default role**
A dropdown at the top selects the default role assigned to new members. Users who have not been explicitly assigned a role receive the capabilities of the default role.

**Role management**
- **Create role** — enter a name and click **Create**.
- **Delete role** — click the delete button on a role column header. Deleting a role removes all assignments to it.

### Policies

The Policies section shows two things:

**Operator roles table**
A read-only view of the canonical surfaces (screens) and actions (RPC methods) each system role is allowed to access. This is driven by the system configuration and cannot be edited here.

**Workspace isolation profiles**
For each workspace, you can set an isolation level:
- **None** — no isolation applied; the workspace shares resources freely.
- **Standard** — default. Network and resource isolation between workspaces.
- **Strict** — maximum isolation; additional constraints on cross-workspace data access.

Change a workspace's isolation level using the dropdown in the table row. Changes take effect immediately.

**Egress allow-list**
The egress allow-list editor is located at **Tools > Egress** (linked from this section). Click the link to jump there to manage outbound network allow/deny rules.

## Membership

User and team CRUD moved to the dedicated **[Teams](/docs/using-the-app/teams)** screen (Settings › Teams). Use Teams to invite members, assign roles, and manage team membership. **Access** (this screen) remains the policy overview — capability matrix, isolation profiles, audit, and break-glass.

## Audit trail

### Audit

The Audit section is a **signed HITL ledger** — an append-only log of every human approval, rejection, and escalation in the workspace. Each entry is chained with a SHA hash and signed with an ed25519 key, making the log tamper-evident.

**Filters**
- **Actor** — filter by the user or system that performed the action.
- **Actor type** — human or system.
- **Kind** — filter by event type (approval, rejection, escalation, etc.).
- **Date range** — restrict to a time window.
- **Signed only** — show only entries that have a valid chain signature.

**Toolbar actions**
- **Verify chain** — run the integrity check on the current ledger. A banner reports whether all chain links and signatures are valid.
- **Export CSV / NDJSON** — download the visible entries (requires `audit:export` permission).
- **Export signed batch** — download a cryptographically signed export bundle suitable for submission to compliance reviewers.
- **Verify exported file** — upload a previously exported signed batch file to verify its integrity offline.
- **Print** — browser print of the visible log.

### History

The History section shows governance-specific events filtered from the broader audit ledger:
- RBAC role changes (`rbac.roles.set`)
- Access denials (`rbac.denied`)
- Workspace isolation changes
- Break-glass grants, revocations, and expirations

Each row shows the sequence number, timestamp, actor, event kind, workspace, subject, and a summary of the payload. Click **Open in Audit** to jump to the full audit entry.

## Governance posture card

A **Governance posture** summary card on the Dashboard shows the current live security mode at a glance:
- **Sandbox** — whether agent tool calls are sandboxed.
- **Egress N** — number of active egress rules.
- **Firewall** — whether the network firewall is active.
- **Audit** — audit logging status.
- **Cost-metered** — whether cost limits are enforced.

Each chip is a shortcut to the relevant configuration screen.

## Break-glass access

In situations where normal RBAC would block an urgent action, an administrator with `access.breakGlass` permission can grant temporary elevated access. Break-glass events are recorded in the History section and automatically expire after the configured duration. See [Workspaces](/docs/using-the-app/workspaces) for break-glass configuration.

## Self-heal

Self-heal lets the runtime propose a recovery action when a flow node fails, instead of simply stopping the run.

- **Off by default.** Self-heal is strictly opt-in. Enable it in **Settings → Orchestration**.
- **Recovery proposals.** When a node fails, the runtime proposes a recovery action — for example, **retry** the node or **switch model** — based on the failure.
- **Require approval.** Optionally require a human to approve a recovery verdict before it is applied. When approval is required, nothing is auto-applied until a reviewer signs off.
- **Max auto-retries.** Cap how many times the runtime may auto-retry a node before it gives up and escalates.

## Compliance and consent

Compliance is a first-class nav item under Governance. Data-subject **consent** records (GDPR Article 6 basis tracking) remain in workspace privacy settings (`config` › Privacy).

### Activation and retention metrics

Activation and retention metrics are strict opt-in. Nothing is collected until the workspace owner consents in **Settings → Privacy**. While consent is unset or disabled, every metric event is dropped.

When enabled, only stable categorical fields (ids, event kinds, bucketed timings, provider categories) are captured. No prompts, secrets, code contents, or PII/PHI are ever recorded.

## Related screens

| Need | Go to |
|---|---|
| Evidence exports, legal holds, DSAR | [Compliance](/docs/using-the-app/compliance) |
| Workflow test suites | [Quality checks (Evals)](/docs/using-the-app/evals) |
| Egress allow-list editor | [Tools](/docs/using-the-app/tools) |
| Firewall and sandbox policy | [Security](/docs/using-the-app/security) |
| Member invites and roles | [Teams](/docs/using-the-app/teams) |
| Spend limits | [Cost](/docs/using-the-app/cost) |
| Workspace privacy / consent | [General](/docs/using-the-app/workspaces) |

Source: /raw/using-the-app/governance.mdx

### using-the-app/inbox.mdx

---
title: Inbox
description: Review and act on human-in-the-loop tasks — approve, reject, reassign, or modify paused workflow steps.
---

The Inbox is where workflows come to you for a human decision. When a flow reaches a **Human** node, it pauses and creates a task in the Inbox. Nothing in that flow continues until someone takes an action.

The header badge shows live counts: **open**, **approved**, and **rejected** tasks.

## Sections

The Inbox has three sections in the section rail:

### Tasks

The Tasks section lists all human-in-the-loop decision requests. Use the status pills at the top to filter by `open`, `all`, `approved`, or `rejected`. Use the search box to find tasks by prompt text, task ID, or tag.

**Task card**
Each task shows:
- The task prompt or description.
- The flow and node that generated it.
- The time the task was created and any configured timeout.
- A **notes** field — type a note before approving or rejecting; it is recorded in the audit ledger.

**Actions**
- **Approve** — allows the flow to continue.
- **Reject** — marks the task as rejected; the flow routes to the rejection path (if configured) or stops.
- **Reassign** — reassign the task to another user or role.
- **Modify** — propose a modification to the task's payload (for tasks that accept a structured response).

Navigate between tasks with keyboard shortcuts `j` (down) and `k` (up).

### Escalations

The Escalations section shows tasks that have timed out and been escalated to a different approver or role. Each escalation card shows the original task, who it was escalated to, and the reason.

### Approvals

The Approvals section shows a chronological view of all completed approvals (approved and rejected) for this session. Use this to confirm that actions you took were recorded correctly before closing the browser.

## Configuring Human nodes

Human nodes in a flow are configured in the **flow editor Inspector panel** when the Human node is selected. Key settings:
- **Approvers** — who should receive this task (by user, role, email, or capability).
- **Quorum** — how many approvals are required.
- **Escalate on timeout** — whether to escalate to a fallback approver after a timeout.

See [Workflows](/docs/using-the-app/flows) for details on the Human node inspector.

## Related screens

| Need | Go to |
|---|---|
| Flow design | [Workflows](/docs/using-the-app/flows) |
| Process approvals | [Processes](/docs/using-the-app/pipelines) |
| Access policy | [Access](/docs/using-the-app/governance) |
| Run history | [Activity](/docs/using-the-app/runs-and-observability) |

Source: /raw/using-the-app/inbox.mdx

### using-the-app/index.mdx

---
title: Using the App
description: A screen-by-screen guide to the AKOS web and desktop application.
---

AKOS is available as a **web application** (multi-tenant SaaS, runs in any modern browser) and as a **desktop application** (self-hosted, runs on your own machine or private cloud). Both surfaces share the same UI — this guide applies to both unless noted.

## App layout

The app is organised around a left-hand **navigation rail** that groups every screen into sections. Within each screen, a secondary **section rail** (left sidebar or top tabs depending on screen width) lets you switch between sub-sections without leaving the page.

Every screen has a consistent header: a kicker label, a title, an optional subtitle with live counts, and an actions bar on the right. Content appears in the main area below.

## Navigation sections

Nav groups match `packages/os-desktop/src/app-nav.ts` (`NAV_GROUPS` / `NAV_ITEMS`):

| Section | Sidebar screens | Notes |
|---|---|---|
| **Home** | [Home (Assistant)](/docs/using-the-app/copilot), [Dashboard](/docs/using-the-app/dashboard) | Assistant-first onboarding lives on Home |
| **Build** | [Agents](/docs/using-the-app/agents), [Workflows](/docs/using-the-app/flows), [Processes](/docs/using-the-app/pipelines), [Automations](/docs/using-the-app/triggers) | Topologies reachable from Agents |
| **Run** | [Activity](/docs/using-the-app/runs-and-observability), [Inbox](/docs/using-the-app/inbox), [Results](/docs/using-the-app/assets) | Activity replaces separate Runs/Traces/Observability nav items |
| **Workspace** | [General](/docs/using-the-app/workspaces), [Integrations](/docs/using-the-app/connections), [Knowledge](/docs/using-the-app/knowledge), [Marketplace](/docs/using-the-app/templates-and-marketplace) | Config via top-bar settings; plugins via Marketplace › Installed |
| **Governance** | [Cost](/docs/using-the-app/cost), [Security](/docs/using-the-app/security), [Quality checks](/docs/using-the-app/evals), [Compliance](/docs/using-the-app/compliance) | Former "Operations" spend/risk surfaces |
| **Settings** | [Access](/docs/using-the-app/governance), [Teams](/docs/using-the-app/teams), [Brand & licensing](/docs/using-the-app/route-only-screens#brand--licensing-oem) | Audit and break-glass live under Access |

**Route-only screens** (deep-linkable, not in the sidebar): `config`, `plugins`, `bundles`, `topologies`, `tools`, `sandbox`, `coding`, `templates`, `oem`, `flow-editor`. See **[Route-only screens](/docs/using-the-app/route-only-screens)** for the full reachability table.

## Web vs desktop

| | Web | Desktop |
|---|---|---|
| Authentication | SSO / email sign-in | Workspace config file |
| Workspace | Cloud-managed | Local or private server |
| LLM tokens | Stored in the cloud vault | Stored on the local machine |
| Multi-workspace | Yes — switch in the top bar | Yes — open multiple workspace files |

## Workspaces

A **workspace** is the top-level unit of isolation. Every agent, flow, trigger, secret, and audit entry belongs to exactly one workspace. On the web, you are invited to a workspace by an admin. On the desktop, you open or create a workspace file.

The current workspace name is shown in the top bar. To switch workspaces, use the workspace switcher in the top bar.

## Command palette

Press `Cmd K` (Mac) or `Ctrl K` (Windows / Linux) from any screen to open the command palette. You can jump to any screen or trigger any registered action without using the navigation. Screen keywords from the nav config (for example `copilot`, `processes`, `activity`) are searchable even when the sidebar label differs.

## Feature guides (not sidebar screens)

These guides cover cross-cutting setup flows that do not map 1:1 to a sidebar item:

| Guide | When to read |
|---|---|
| [Integration setup](/docs/using-the-app/integration-setup) | OAuth, app installs, and connection credentials |
| [Public automation API](/docs/using-the-app/public-automation-api) | External webhooks and API keys that dispatch workflows |
| [Model catalog](/docs/using-the-app/model-catalog) | Choosing models in agent and flow forms |
| [Knowledge](/docs/using-the-app/knowledge) | Indexing docs for the in-app assistant |

## Documentation map

| Audience | Start here |
|---|---|
| End users (this section) | Screen guides linked above |
| Core vocabulary | [Concepts](/docs/concepts) |
| Run path (trigger → audit) | [Run lifecycle](/docs/how-it-works/run-lifecycle) |
| Operators / CLI | [CLI command reference](/docs/cli/command-reference) |
| Contributors & IDE agents | Internal agent guides and the docs query CLI (see repository `CONTRIBUTING.md`) |

Source: /raw/using-the-app/index.mdx

### using-the-app/integration-setup.mdx

---
title: Integration setup
description: Use AKOS setup guidance to connect OAuth apps, bot installations, API keys, webhooks, MCP servers, and LLM providers.
---

AKOS keeps provider-specific setup instructions in the integration setup registry. The assistant, Connections screen, and CLI read that registry instead of duplicating setup steps in static docs.

Use **[Home (Assistant)](/docs/using-the-app/copilot)** when you want guided setup in conversation. It can explain what happens inside AKOS, what you must complete in the external service, which permissions are requested, and which health check confirms the connection.

Use the CLI when you need the same setup data for automation or review:

```bash
agentskit-os connections guide slack
agentskit-os connections guide discord --json
agentskit-os connections guide --category llm --implemented-only
```

Each guide can include:

- The preferred setup mode: OAuth, app or bot installation, guided secret, platform-managed setup, or fallback.
- The setup CTA and summary shown in product surfaces.
- Required scopes or permissions.
- External credential links when a provider needs an API key.
- The health-check method AKOS should run after setup.
- Assistant instructions for safe wording and redaction.

For tenant setup, prefer OAuth or app installation when available. Ask for API keys only when the registry says a guided secret is the right path. Never paste raw secrets into chat output; store them through Connections or the vault-backed CLI flow.

The **[Connections](/docs/using-the-app/connections)** screen is still the main place to connect, verify, rotate, and remove provider credentials.

For OAuth-protected **[Knowledge](/docs/using-the-app/knowledge)** sources, complete the provider connection here first, then add the source in the Knowledge screen.

For scoped keys that let external apps call `/v1/automations/*`, use **[Connections](/docs/using-the-app/connections)** › **External apps** and read **[Public automation API](/docs/using-the-app/public-automation-api)**.

## Provider setup checklist

Use the registry guide first, then prepare the provider-side object that matches its setup mode:

| Setup mode | Provider-side setup | AKOS setup |
|---|---|---|
| OAuth | Create an OAuth app, add the AKOS callback URL, select the registry scopes, and keep client credentials in the operator vault. | Connect from **Connections** or the assistant; verify with the provider health check. |
| App or bot installation | Create/install the provider app for the target workspace, org, guild, or site; grant only the registry permissions. | Complete the installation flow and confirm the connected account/workspace metadata. |
| Guided secret or API key | Create a scoped key for a service account, rotateable bot user, or sandbox tenant. | Store the key through Connections or the vault-backed CLI flow; never paste it into chat. |
| MCP server | Configure the MCP server URL/command, auth policy, and egress allowlist. | Register the MCP connection, then run a tool-list/read-only smoke before enabling write actions. |
| DB connection | Create a least-privilege DB user, network allowlist, TLS settings, and read/write role according to the workflow. | Store the DSN/parts as a secret and run a metadata/readiness check before any mutation workflow. |

When the setup is ambiguous, the assistant should ask which tenant/workspace, environment, provider account, and permission level to use before it renders a connect action.

## Live validation

Use the provider health check in **Connections** after setup. Health checks
record only provider, status, and safe proof metadata; tokens, client secrets,
API keys, and private keys are redacted from reports and logs.

## Related screens

| Need | Go to |
|---|---|
| Connect / verify credentials | [Connections](/docs/using-the-app/connections) |
| Guided setup in chat | [Home (Assistant)](/docs/using-the-app/copilot) |
| OAuth knowledge sources | [Knowledge](/docs/using-the-app/knowledge) |
| External automation keys | [Public automation API](/docs/using-the-app/public-automation-api) |
| CLI reference | [Command reference](/docs/cli/command-reference) |

Source: /raw/using-the-app/integration-setup.mdx

### using-the-app/knowledge.mdx

---
title: Knowledge
description: Add document sources that agents can search using retrieval-augmented generation (RAG).
---

The Knowledge screen manages the document collections that your agents can retrieve information from. When an agent or flow contains a RAG node, AKOS searches the relevant knowledge sources and injects the results into the agent's context.

> If your installation does not have a knowledge indexer or vector store configured, the screen will show a "Knowledge subsystem not configured" message. Contact your administrator to enable this feature.

## Source list

Each row in the source list shows:
- **Source name and kind** — the display name and the source type (folder, URL, database, etc.).
- **Status** — one of: `indexed`, `indexing`, `failed`, or `needs rebuild`.
- **Document count and size** — the number of documents currently indexed and their total size.
- **Agent usage** — how many agents currently reference this source.
- **Rebuild** and **Remove** action buttons.

The header shows aggregate stats: total sources, how many are currently indexing, how many have failed, total document count, and total indexed size.

## Adding a source

Click **+ Add source** to open the add-source form. Fill in:
- **ID** — a unique slug for this source (used in RAG node configuration).
- **Name** — a display name.
- **Kind** — the type of source:
  - `folder` — a local folder of files (PDF, Markdown, plain text, etc.).
  - `url` — a web page or sitemap.
  - `database` — a SQL query result.
  - Others may be available depending on your installation.
- **Location** — the path, URL, or connection details for the source.
- **Embeddings provider** — the LLM provider used to generate vector embeddings. Must be a connected provider from the **[Connections](/docs/using-the-app/connections)** screen.
- **Embeddings model** — the specific model to use for embeddings.

For sources that require authentication (for example, a private web page or a database), the form shows additional authentication fields. For OAuth-protected sources, a **Connect** button launches the OAuth flow.

Click **Add** to save and begin indexing.

## Rebuilding a source

To re-index an existing source (for example, after the underlying documents have changed), click **Rebuild** on the source row. Indexing happens in the background; the status badge updates when complete.

To rebuild all sources at once, open the command palette (`Cmd K`) and run **Rebuild all sources**.

## Using knowledge in flows

To use a knowledge source in a workflow, add a **RAG** node to your flow in the flow editor. The RAG node inspector lets you select the source by ID and configure the query and retrieval settings. The retrieved context is passed automatically to the next node in the flow.

To assign a knowledge source to an agent directly (so it is always available without a dedicated RAG node), configure the agent's knowledge settings in the **[Agents](/docs/using-the-app/agents)** form.

## Indexing product documentation for the assistant

Workspace **document sources** (above) power flow RAG nodes. Separately, operators can index the **shipped documentation corpus** so the in-app assistant retrieves repo docs:

```bash
agentskit-os prod seed --target assistant-knowledge --dry-run
agentskit-os prod seed --target assistant-knowledge --apply
agentskit-os knowledge rebuild assistant-knowledge-for-agents
agentskit-os knowledge rebuild assistant-knowledge-user-docs
```

This registers the internal agent docs, product docs, demo docs, and runbooks as folder sources. Until rebuild completes, fumadocs pages are not in assistant RAG — the contract catalog in the system prompt is always on, but folder search requires this operator path. See the [CLI command reference](/docs/cli/command-reference) (`prod seed`, `knowledge rebuild`) and the [Using the App](/docs/using-the-app) guide index for related operator flows.

## Related screens

| Need | Go to |
|---|---|
| OAuth provider setup | [Connections](/docs/using-the-app/connections) |
| Guided integration steps | [Integration setup](/docs/using-the-app/integration-setup) |
| Use sources in flows | [Workflows](/docs/using-the-app/flows) |
| Assistant chat | [Home (Assistant)](/docs/using-the-app/copilot) |

Source: /raw/using-the-app/knowledge.mdx

### using-the-app/model-catalog.mdx

---
title: Model catalog
description: Pick from a live catalog of 5,000+ models across 140+ providers wherever AKOS asks for a model.
---

Wherever AKOS asks you to choose an LLM — an agent's model, an agent node in a flow, a multi-agent strategy, or an eval — you pick from a **live model catalog**, not a hand-typed string.

## What's in the catalog

The catalog is a continuously refreshed snapshot covering **140+ providers and over 5,000 models** — OpenAI, Anthropic, Google, Mistral, Meta, and many more, including the models you reach through your own provider connections. Because it is the real catalog rather than a fixed list baked into the app, new models appear without an app update.

## Searching

The model field is a searchable combobox:

1. Click the field and start typing a **provider** or **model name** (for example, `claude`, `gpt`, or `gemini`).
2. The dropdown narrows as you type. Search runs against the full catalog, so you never scroll thousands of rows — keep typing to narrow further.
3. Each result shows the **model name**, the **provider · model id**, and capability tags.

When a search returns more matches than fit on screen, the dropdown tells you how many of the total it is showing (for example, *Showing 60 of 312 — keep typing to narrow*).

## Capability tags

Results are tagged so you can pick a model that fits the job:

| Tag | Meaning |
|---|---|
| **reasoning** | The model supports extended reasoning / thinking. |
| **tools** | The model can call tools (function calling), required for agents that use tools. |

If your agent uses tools, choose a model with the **tools** tag. For complex multi-step tasks, a **reasoning** model is usually a better fit.

## Where you'll see it

The catalog picker appears everywhere a model is selected, including:

- The **Model** step of the agent create/edit form (see [Agents](/docs/using-the-app/agents)).
- **Agent** nodes in the visual flow editor (see [Workflows](/docs/using-the-app/flows)).
- **Multi-agent** node members.
- Eval runners that compare models.

Leaving a model blank inherits the model from the agent's assigned role (or the provider default), so you only set a model when you want to override.

## Related screens

| Need | Go to |
|---|---|
| Agent model step | [Agents](/docs/using-the-app/agents) |
| Flow agent nodes | [Workflows](/docs/using-the-app/flows) |
| LLM provider connections | [Connections](/docs/using-the-app/connections) |
| Benchmark comparisons | [Quality checks (Evals)](/docs/using-the-app/evals) |

Source: /raw/using-the-app/model-catalog.mdx

### using-the-app/pipelines.mdx

---
title: Processes
description: Chain flows into multi-phase processes and track work across columns on a kanban board.
---

The Processes screen lets you group related **[Workflows](/docs/using-the-app/flows)** into a structured **process** — a sequence of phases, each mapped to a flow. This is useful when a business process spans multiple steps that should each be tracked and governed separately. Phases that require human approval surface in the **[Inbox](/docs/using-the-app/inbox)**.

## Process workspace

The top of the screen has a **process selector** (a dropdown listing all processes in the workspace) and a **view toggle** to switch between two views:

- **Board** — a kanban-style column view showing current work items moving through phases.
- **Chain** — a visual map of all phases and their connections, rendered as a node graph.

### Board view

The board shows one column per process phase. Each card in a column represents a unit of work. You can:
- Move cards between columns by drag-and-drop.
- Click a card to see its details, including the bound flow and latest run status.
- Use the **Run bar** at the top to trigger a full process run.

Each column has a **settings** panel where you can configure:
- The flow bound to this phase.
- Execution mode (sequential, parallel).
- Input/output key mappings that pass data between phases.
- A CDC (change-data-capture) source if the phase listens to database events.
- Whether human approval is required before advancing.

### Chain view

The chain view renders the end-to-end phase sequence as a visual graph. Phases are nodes; arrows show the data flow between them. This is a read-only map — to edit bindings, go back to the Board view column settings.

## Creating a process

If no processes exist, the screen shows an empty state with a **Create process** button. Click it to open the create dialog, give the process a name, and confirm. The new process appears in the selector with a single default column. Add more phases from the Board view.

## Process run bar

A persistent run bar appears below the selector bar whenever a process is selected. It shows the latest process-level run status and provides a **Run process** button to start a fresh end-to-end execution.

## Related screens

| Need | Go to |
|---|---|
| Flow design | [Workflows](/docs/using-the-app/flows) |
| Regression testing | [Quality checks (Evals)](/docs/using-the-app/evals) |
| Human approvals | [Inbox](/docs/using-the-app/inbox) |
| Run history | [Activity](/docs/using-the-app/runs-and-observability) |

Source: /raw/using-the-app/pipelines.mdx

### using-the-app/public-automation-api.mdx

---
title: Public automation API
description: Trigger approved automations from Lovable, v0, Next, Vercel, and other external apps with scoped API keys or hosted webhook URLs.
---

Use the public automation API when an external app needs to start an approved AKOS automation without exposing the internal JSON-RPC surface. Create scoped keys in **[Connections](/docs/using-the-app/connections)** › **External apps**. For workspace-internal webhook triggers (sidecar paths, not hosted automation URLs), see **[Triggers](/docs/using-the-app/triggers)**.

## Choose a path

| Path | Use it when | Secret handling |
|---|---|---|
| **API key run** | Your app has a server route, server action, edge function, or backend job. | Keep the API key in server-side environment variables only. |
| **Hosted webhook** | You want a stable automation URL generated from Triggers. | Current hosted ingress uses the same server-side API key auth. |

Never put `AGENTSKIT_API_KEY` in browser code, public `.env` files, client components, or generated frontend snippets.

## Create an API key

1. Open **Connections**.
2. Select **External apps**.
3. Create a scoped key with the automations it may run.
4. Copy the raw key once and store it in your server environment as `AGENTSKIT_API_KEY`.

Keys are stored by hash. AKOS shows the raw secret only when the key is created.

## Server-side run

```ts
export async function POST(req: Request) {
  const input = await req.json()
  const res = await fetch(`${process.env.AGENTSKIT_API_URL}/v1/automations/run`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      authorization: `Bearer ${process.env.AGENTSKIT_API_KEY}`,
      'idempotency-key': input.id ?? crypto.randomUUID(),
    },
    body: JSON.stringify({
      automationId: 'lead-intake',
      input,
      mode: 'real',
    }),
  })

  if (!res.ok) return Response.json({ error: 'automation_failed' }, { status: 502 })
  return Response.json(await res.json())
}
```

Use this from Lovable, v0, Next, Vercel, or any app builder by calling your own server endpoint. The app builder should never receive the AKOS key.

## Hosted webhook

Create or edit a webhook trigger in **Automations > Triggers**. The form shows the hosted endpoint:

```http
POST https://your-akos-host/v1/automations/webhooks/lead-intake
Authorization: Bearer ak_live_...
Content-Type: application/json
Idempotency-Key: lead-form-123
```

Example:

```bash
curl -X POST 'https://your-akos-host/v1/automations/webhooks/lead-intake' \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <AGENTSKIT_API_KEY>' \
  -H 'idempotency-key: lead-form-123' \
  -d '{"email":"ana@acme.com","message":"hello"}'
```

The request body becomes the automation input.

## Read run status

```bash
curl 'https://your-akos-host/v1/automation-runs/pipe_123' \
  -H 'authorization: Bearer <AGENTSKIT_API_KEY>'
```

Status reads are scoped to runs created by the calling key.

## Security notes

- Keys are org-scoped and may be limited to specific automation ids.
- Revoked keys stop before reaching the runner.
- `/rpc` remains internal-only; external apps only use `/v1/automations/*`.
- Use `Idempotency-Key` for form submissions and retries.
- Hosted webhook HMAC secrets are not part of this first version. Use API key auth until a dedicated webhook signing secret is available.

## Related screens

| Need | Go to |
|---|---|
| Create / revoke API keys | [Connections](/docs/using-the-app/connections) › External apps |
| Workspace webhook paths | [Automations](/docs/using-the-app/triggers) |
| Target workflows | [Workflows](/docs/using-the-app/flows) |
| Run history | [Activity](/docs/using-the-app/runs-and-observability) |

Source: /raw/using-the-app/public-automation-api.mdx

### using-the-app/route-only-screens.mdx

---
title: Route-only screens
description: Deep-linkable screens that are not in the sidebar — how to reach them from their owner surfaces.
---

Some screens stay **routable** (command palette, deep links, notifications) but were removed from the sidebar once their owner surface shipped (issue #3897). They are not hidden — assistants and the palette can still navigate to them by id.

## How to open any screen

Press `Cmd K` / `Ctrl K` and type the screen id or a keyword (for example `plugins`, `config`, `coding`).

## Screen index

| Screen id | Label / purpose | Reach from |
|---|---|---|
| `config` | Workspace settings (copilot, orchestration, privacy, export/import) | Top-bar **Settings** button |
| `plugins` | Installed plugin lifecycle | [Marketplace](/docs/using-the-app/templates-and-marketplace) › Installed › Manage plugins |
| `bundles` | Bundle import/export history | [General](/docs/using-the-app/workspaces) › Export/Import › Full bundle history |
| `topologies` | Multi-agent collaboration templates | [Agents](/docs/using-the-app/agents) › How agents collaborate |
| `tools` | Runtime tools registry sections | [General](/docs/using-the-app/workspaces) runtime sections, or [Tools](/docs/using-the-app/tools) |
| `sandbox` | Sandbox policy shortcuts | [Security](/docs/using-the-app/security) or [General](/docs/using-the-app/workspaces) runtime sections |
| `coding` | Coding-agent providers and runTask | [Agents](/docs/using-the-app/agents) or [Coding](/docs/using-the-app/coding) guide |
| `templates` | Starter flow templates browser | [Workflows](/docs/using-the-app/flows) template picker, or palette `templates` |
| `oem` | Brand & licensing (OEM entitlement) | Settings › Brand & licensing (when entitled) |
| `flow-editor` | Full-page flow editor | [Workflows](/docs/using-the-app/flows) — open a flow |

## Brand & licensing (`oem`)

Available when your workspace has the OEM entitlement. Open via **Settings › Brand & licensing** or the command palette (`oem`).

Typical tabs:

| Area | What you do |
|---|---|
| **License** | Import a signed license envelope and review validity / grace state. |
| **Tenants** | Issue, suspend, or revoke tenant licenses (operator workflows). |
| **Brand kit** | Edit tokens, logos, and white-label runtime projection. |
| **Vertical packs** | Browse and apply OEM vertical YAML packs to the workspace. |
| **Marketplace publish** | Export/import bundles for the marketplace catalog (publisher permissions). |

Cloud-hosted OEM operators also use the separate **admin** console (`apps/admin/`) for tenant-wide control; desktop `oem` is the workspace-local brand + licensing surface.

## Aliases (also not sidebar items)

| Screen id | Lands on |
|---|---|
| `runs`, `traces`, `observability` | [Activity](/docs/using-the-app/runs-and-observability) (or Traces / Observability standalone) |
| `audit`, `break-glass` | [Access](/docs/using-the-app/governance) (Governance pillar) |

## Related screens

| Need | Go to |
|---|---|
| Owner surfaces (flows, agents, workspace) | [Using the App index](/docs/using-the-app) |
| Sandbox / egress policy detail | [Security](/docs/using-the-app/security) |
| MCP and egress editor | [Tools](/docs/using-the-app/tools) |
| Marketplace plugins | [Marketplace](/docs/using-the-app/templates-and-marketplace) |

## For contributors

Route-only screens also have agent implementation guides in the repository contributor docs. Use the internal docs query CLI from a dev checkout (`pnpm docs:internal:query screen <id> --agent`).

Source: /raw/using-the-app/route-only-screens.mdx

### using-the-app/runs-and-observability.mdx

---
title: Activity & Observability
description: Monitor workflow executions, inspect traces, and track operational health from the unified Activity surface.
---

AKOS captures detailed telemetry for every execution. The sidebar **Activity** screen (nav id `observe`) is the primary entry point for run monitoring. **Traces** and **Observability** remain separate routable screens for span-level and aggregate health views.

## Watching a run live

AKOS shows you what's happening *while* a run executes, not only after it finishes.

- **Live event feed** — the [Dashboard](/docs/using-the-app/dashboard) terminal-style activity feed streams events as they happen. Click any run event to open that run's detail.
- **Running-node pulse on the canvas** — open a flow in the editor and run it: the executing node **pulses** on the canvas with a status bar naming the step in progress.
- **Global run indicators** — a pulsing **top-bar pill** and a **sidebar badge** on Activity show in-flight run counts; Activity and Workflows nav items pulse while work is running. Click the pill to jump to Activity.
- **Toasts** — brief notifications for run completion, approvals needed, or exports ready.

These indicators read the same live run count everywhere.

## Activity screen (Runs)

The Activity screen renders the **Runs** monitor (nav ids `observe` and `runs` both land here).

### Run list

Each row shows:

- Run ID and task description.
- Status: `running`, `completed`, `failed`, `paused` (HITL), or `cancelled`.
- Duration, cost (USD), and token count.
- Trigger name (cron, webhook, manual, etc.).

Use **search** to filter by task or run ID. Overflow actions include compare runs, CSV/NDJSON export (requires `runs:export`), signed batch export, and print.

Filter chips appear when the list is scoped to a trigger or agent.

### Run detail

Click a run to open the detail panel:

- **Header** — status, share link, artifact viewer toggle, stop/retry controls.
- **Metrics** — duration, cost, tokens, trigger.
- **Assurance** — egress, firewall, sandbox decisions.
- **Agents / tools / evals** — participants and invocations.
- **Artifacts** — outputs linked to [Results](/docs/using-the-app/assets).

## Traces screen

Open via command palette (`traces`) or deep-link alias. Shows OpenTelemetry-compatible distributed traces — one span per agent call, tool invocation, or sub-flow. Use Traces for latency diagnosis at span level.

## Observability screen

Open via command palette (`observability`) or deep-link alias. Aggregate views:

- **Health** — sidecar, storage, and configured service checks.
- **Metrics** — run volume, error rates, latency, cost trends.
- **Incidents** — anomaly and incident records linked to runs.

## Cost in run context

Per-run cost appears in Activity detail and rollups on [Cost](/docs/using-the-app/cost). The Activity screen does not duplicate budget editing.

## Legacy deep links

Older URLs and notifications may use `runs`, `traces`, or `observability` as screen ids. These remain valid `ActiveScreen` aliases — they route to Activity (runs) or the standalone Traces / Observability screens respectively. Audit moved to [Governance](/docs/using-the-app/governance) › Audit (no longer an Activity tab).

## Related screens

| Need | Go to |
|---|---|
| Live overview | [Dashboard](/docs/using-the-app/dashboard) |
| Workflow design | [Workflows](/docs/using-the-app/flows) |
| Human approvals | [Inbox](/docs/using-the-app/inbox) |
| Run outputs | [Results](/docs/using-the-app/assets) |
| Spend per run | [Cost](/docs/using-the-app/cost) |
| Sandbox / egress decisions | [Security](/docs/using-the-app/security) |

Source: /raw/using-the-app/runs-and-observability.mdx

### using-the-app/security.mdx

---
title: Security
description: Sandbox policy, egress allowlists, prompt firewall, PII profiles, and break-glass elevation.
---

The **Security** screen is where operators control execution boundaries: what code can run, what network destinations are allowed, how prompts are filtered, and when temporary elevation is granted.

## Sections

### Sandbox

- **Level** — none, process, container, or stronger isolation modes (container requires Docker on PATH; probe via `runtime.status` before offering the option).
- **Policy** — read/write path allowlists, environment allowlist, and network policy snapshot.
- **Denials** — recent sandbox decisions that blocked an action.
- **Flow preview** — hypothetical decision for a flow/agent combination before dispatch.

The route-only **`sandbox`** screen (see **[Route-only screens](/docs/using-the-app/route-only-screens)**) exposes the same policy shortcuts from workspace runtime sections.

### Egress

- **Policy** — domain allowlist and block-by-default mode (toggle is guarded when the allowlist is empty).
- **Decisions log** — allowed and denied outbound requests.

### Firewall and PII

Prompt firewall rules and custom PII redaction profiles are edited here. Changes take effect for subsequent runs without redeploying agents.

### Break-glass

Time-boxed elevation requests (`access.breakGlass`) for emergencies. Grants and revokes append to the signed audit ledger. Use [Governance](/docs/using-the-app/governance) › Audit for verification.

## MCP operators

External agents connected via `agentskit-os mcp-serve` can read and update firewall, egress, and PII profiles at runtime through MCP security tools — see the [CLI command reference](/docs/cli/command-reference).

## Related screens

| Need | Go to |
|---|---|
| Signed audit trail | [Governance](/docs/using-the-app/governance) |
| Compliance evidence export | [Compliance](/docs/using-the-app/compliance) |
| Tool egress from flows | [Workflows](/docs/using-the-app/flows) run assurance panel |

Source: /raw/using-the-app/security.mdx

### using-the-app/teams.mdx

---
title: Teams
description: Manage workspace users, teams, memberships, and role assignments.
---

**Teams** (Settings section) is the canonical editing surface for workspace membership. [Governance](/docs/using-the-app/governance) shows policy overview and audit context; **Teams** is where you create users, invite members, assign roles, and manage team membership.

## Users

- List principals in the workspace.
- Invite by email with a selected role.
- Update or revoke access for individual users.
- Bulk-assign a role to multiple selected members.

Backed by `users.*` RPC methods with RBAC enforcement on every mutation.

## Teams

- Create, rename, or delete teams (`teams.*`).
- Add or remove members from a team.
- Assign team-scoped roles where your plan supports it.

## Relationship to Access (Governance)

| Surface | Purpose |
|---|---|
| **Teams** | CRUD for users, teams, memberships, role assignment |
| **Governance › Access** | Capability matrix, isolation profiles, operator role tables |

When the assistant helps with "give someone access", clarify the target user or team and intended role before proposing a change — role mutations are security-sensitive.

## Related screens

| Need | Go to |
|---|---|
| Role / capability matrix | [Governance](/docs/using-the-app/governance) |
| Break-glass elevation | [Governance](/docs/using-the-app/governance) or [Security](/docs/using-the-app/security) |
| Cloud tenant members (OEM) | Admin app `/members` |

Source: /raw/using-the-app/teams.mdx

### using-the-app/templates-and-marketplace.mdx

---
title: Templates & Marketplace
description: Start workflows from pre-built templates, install vertical packs, and manage published bundles.
---

AKOS provides two ways to accelerate setup: **Templates** (workflow starters built into the app) and the **Marketplace** (installable packs, integrations, and OEM bundles).

## Templates

The Templates screen is a **three-step wizard** for creating a new workflow from a pre-built starting point.

### Step 1: Pick a template

The picker page shows:
- **Persona filter** — buttons to narrow templates by your role (for example, "Operations", "Finance", "Legal"). Selecting a persona hides templates not tagged for that audience.
- **Template grid** — cards showing each template's name, category badge, and description. Click a card to select it.
- **Start blank** bar — a text field where you can describe what you want in plain English. AKOS generates a blank flow pre-named from your description. Click **Start blank** or press Enter.

If you select a template, you advance automatically to the Configure step.

### Step 2: Configure

Fill in:
- **Flow ID** — the unique identifier for your new workflow.
- **Flow name** — a human-readable name.
- **Run on save** — optionally toggle this to run the workflow immediately after saving.

Click **Next** to proceed or **Back** to return to the picker.

### Step 3: Review

Confirms your selections. Click **Save** to create the workflow, or **Save & Edit** to save and open it immediately in the flow editor.

A step-dots indicator in the header shows your progress through the three steps.

---

## Marketplace

The Marketplace screen lets you browse, install, and manage the AKOS catalog — vertical packs, integrations, and OEM-published bundles.

> **Alpha (early access).** The Marketplace ships as a minimal, demo-scoped surface and is marked **Alpha** in the app. The data is real, but the catalog, publishing flow, and management tools are still early and will change. Treat it as a preview while we expand coverage.

The screen is organised into three sections in the section rail: **Browse**, **Installed**, and **Manage**.

### Browse

The Browse pane shows:
- **Stats bar** — total listings, categories, and a count of installed items.
- **Featured** — highlighted items, often vertically relevant to your active vertical.
- **Filters** — narrow by vertical (finance, healthcare, legal, coding, etc.), capability tags, and a text search.
- **Listings grid** — cards for each listing. Each card shows the name, author, category, short description, compatibility tags, and an **Install** button.

**Domain packs** appear at the top of the browse results. Clicking **Apply** on a domain pack writes a set of starter agents and flows to your workspace configuration.

Click any listing card to open the **Listing detail drawer**, which shows the full description, changelog, version, and screenshots. From the drawer you can also install the listing.

After installing a listing, a confirmation banner appears with quick links to open the installed agents, flows, or templates in their respective screens.

### Installed

The Installed pane lists every listing currently installed in this workspace. Each item shows its name, version, and an **Uninstall** button.

If nothing is installed yet, an empty state prompts you to go to Browse.

### Manage

The Manage pane is for workspace owners and OEM operators. It includes:
- **Publisher keys** — manage the signing keys used to verify listings you publish.
- **Private library** — upload or register private listings available only to your organisation.
- **Connection suggester** — a tool that analyses your installed agents and suggests integrations you might want to configure.
- **Report** — flag a public listing for review if it violates policies.

> The **Publish** tab (for OEM operators publishing bundles to the marketplace) is only visible if your account has publisher permissions.

## Related screens

| Need | Go to |
|---|---|
| Open created workflows | [Workflows](/docs/using-the-app/flows) |
| Agent registry after install | [Agents](/docs/using-the-app/agents) |
| Post-install integrations | [Connections](/docs/using-the-app/connections) |
| Plugin lifecycle (`plugins`) | [Route-only screens](/docs/using-the-app/route-only-screens) |
| Starter templates (`templates`) | [Route-only screens](/docs/using-the-app/route-only-screens) |
| OEM publish / brand kit | [Route-only screens](/docs/using-the-app/route-only-screens#brand--licensing-oem) |

Source: /raw/using-the-app/templates-and-marketplace.mdx

### using-the-app/tools.mdx

---
title: Tools
description: Configure sandbox guardrails, manage the egress allow-list, view tool call activity, and connect MCP servers.
---

The Tools screen brings together every runtime policy and activity feed related to tool execution. It is split into two groups in the section rail: **Guardrails** (configuration) and **Activity** (live logs).

## Guardrails

### Sandbox

The Sandbox section controls how agent tool calls are isolated at runtime:
- **Sandbox mode** — enable or disable the sandbox for tool execution. When enabled, tool calls run in an isolated environment that restricts access to the host system.
- **Network policy** — whether sandboxed tools can make outbound network calls.
- **Filesystem policy** — which directories sandboxed tools may read from or write to.
- **Resource limits** — CPU time and memory limits for sandboxed executions.

Changes here affect all subsequent tool calls in the workspace.

### Egress

The Egress section is the outbound network allow-list editor. When egress enforcement is enabled (configured in the workspace security settings), every outbound HTTP/HTTPS call an agent makes is checked against this list.

**Rules list**
Each rule shows:
- A **pattern** (exact host or glob, for example `*.openai.com`).
- The **action**: `allow` or `deny`.
- An optional **label** for documentation purposes.
- A **decision feed** showing recent egress decisions matched against this rule.

**Adding a rule**
Click **Add rule**, enter the host pattern, choose `allow` or `deny`, and save. Rules are evaluated top-to-bottom; the first matching rule wins.

**Decision feed**
Below the rules list, a live feed shows recent egress decisions: the URL requested, the rule that matched, and whether it was allowed or blocked.

## Activity

### Tool calls

The Tool calls section shows a chronological log of every tool invocation in the workspace. Each row shows:
- The tool ID (for example, `http.get`, `sql.query`, `slack.send`).
- The agent and run that made the call.
- Input and output summaries.
- Duration and status (success / error).

Click a row to expand the full input/output payload.

### MCP

The MCP (Model Context Protocol) section shows connected MCP servers. AKOS can expose its tool catalog to external MCP clients, and can also connect to external MCP servers to use their tools.

**AKOS as an MCP server**
AKOS exposes a built-in MCP server at `akos mcp-serve` (CLI) or via the configured stdio transport. The server exposes all registered tools and agents as MCP tools. Connected external MCP clients see the full tool catalog.

**External MCP servers**
Add external MCP server endpoints here. Registered servers are available as tool sources for agents and flows. Each entry shows the server URL, connection status, and the tools it exposes.

## Related screens

| Need | Go to |
|---|---|
| Firewall and PII policy | [Security](/docs/using-the-app/security) |
| Route-only screen (`tools`) | [Route-only screens](/docs/using-the-app/route-only-screens) |
| Workspace runtime sections | [General](/docs/using-the-app/workspaces) |
| MCP connection setup | [Connections](/docs/using-the-app/connections) |
| Agent tool bindings | [Agents](/docs/using-the-app/agents) |

Source: /raw/using-the-app/tools.mdx

### using-the-app/triggers.mdx

---
title: Triggers
description: Schedule workflows on a cron, watch for file changes, or receive inbound webhooks to start flows automatically.
---

The Triggers screen lets you configure automations that start workflows without manual intervention. Triggers are loaded from your workspace configuration and polled live every 5 seconds.

## Trigger types

| Type | Description |
|---|---|
| **Cron** | Runs a workflow on a schedule using a cron expression (e.g. every night at midnight). |
| **File watch** | Runs a workflow when a file or folder changes on disk. |
| **Webhook** | Runs a workflow when an HTTP POST arrives at the AKOS webhook endpoint. |
| **Inline** | Defined directly inside a flow's Trigger node (configured from the flow editor). |

## Trigger list

The screen shows three panels:

- **Cron** — lists all active cron triggers with their ID, kind, and time until the next fire.
- **File watchers** — lists all active file-watch triggers.
- **Inline triggers** — a table of triggers defined inside flows, editable from this screen.

Each row has a **Runs** button that jumps to the Runs screen pre-filtered to runs started by that trigger.

## Webhook server

If any webhook triggers are active, a banner at the top of the screen shows the current webhook server address and the registered paths. Example:

```
Webhook server live at http://0.0.0.0:8080; paths: /webhook/github, /webhook/stripe
```

To make the webhook server reachable from the internet, start AKOS with the `--public` flag or set `AKOS_WEBHOOK_HOST=0.0.0.0` in your environment.

For external apps (Lovable, v0, hosted backends) that need scoped API keys or stable automation URLs instead of workspace webhook paths, see **[Public automation API](/docs/using-the-app/public-automation-api)**.

## Adding a trigger

To add a trigger quickly, open the command palette (`Cmd K`) and search for:
- **Add cron trigger**
- **Add webhook trigger**
- **Add file watcher**

These commands open the trigger editor pre-filled with the selected kind.

## Trigger editor (inline triggers)

The inline trigger editor is embedded at the bottom of the Triggers screen. It lists all inline triggers (those defined inside flow Trigger nodes) and lets you edit them without opening the flow editor.

### Cron fields
- **ID** — unique identifier for this trigger.
- **Cron expression** — standard 5-field cron syntax.
- **Flow** — the workflow to run when the trigger fires.
- **Input** — optional static JSON to pass as the flow's input.

### File-watch fields
- **Path** — the file or directory to watch.
- **Events** — which events to watch for (create, modify, delete).
- **Flow** — the workflow to run.

### Webhook fields
- **Path** — the URL path for this webhook (e.g. `/webhook/github`).
- **Provider** — the webhook provider; AKOS verifies the request signature automatically for supported providers (GitHub, Stripe, Slack, PagerDuty, Sentry, Linear, Twilio).
- **Flow** — the workflow to run.
- **Copy URL** — copies the full inbound URL for this webhook to the clipboard.

## Related screens

| Need | Go to |
|---|---|
| Flow design | [Workflows](/docs/using-the-app/flows) |
| External API dispatch | [Public automation API](/docs/using-the-app/public-automation-api) |
| Run history | [Activity](/docs/using-the-app/runs-and-observability) |

Source: /raw/using-the-app/triggers.mdx

### using-the-app/workspaces.mdx

---
title: Workspaces
description: Configure workspace identity, secrets, team access, cost limits, cloud sync, and isolation settings.
---

The Workspaces screen lets workspace owners and admins manage every aspect of a workspace's configuration. Select a workspace from the list on the left, then use the section rail to navigate between configuration areas.

## Identity

The Identity section shows and lets you edit the workspace's basic properties:
- **Name** — the display name shown in the top bar.
- **ID** — the read-only unique identifier.
- **Description** — an optional summary.
- **Vertical** — the active vertical (finance, healthcare, legal, coding, etc.) that drives template filtering and marketplace ranking.
- **Active / Inactive toggle** — deactivate a workspace without deleting it.

Click **Save** to persist changes.

## Secrets

The Secrets section is the local secrets vault. Store API keys and credentials here so agents and flows can reference them by name rather than embedding raw values in configuration.

- Each secret has a **name** (the reference key used in configuration) and an **encrypted value**.
- Click **Add secret** to create a new entry.
- Click the eye icon to temporarily reveal a value.
- Click **Delete** to remove a secret.

For secrets stored in an external vault, use the Connections screen (External secrets tab) to configure vault references.

## Agents

The Agents section shows agents that have been defined inline in this workspace's configuration file (as opposed to agents created through the Agent registry UI). These are read-only here; edit them directly in the Config editor or through the Agents screen.

## Cost

The Cost section lets you set budget limits and alerts for this workspace:
- **Monthly budget** — the maximum spend allowed per month. Flows and agents that would exceed this limit are blocked.
- **Alert threshold** — a percentage of the budget at which an alert notification is sent.
- **Hard limit** — whether to block all runs when the budget is exhausted, or only warn.

Changes take effect for the next billing period.

## Team

The Team section shows the current seats on this workspace and lets you invite new members.

- **Seats list** — each member's email address and role.
- **Remove** — revoke a member's access.
- **Invite form** — enter an email address, choose a role (`viewer`, `editor`, `admin`, or `owner`), and click **Invite**.

Roles and their capabilities are managed in the [Governance](/docs/using-the-app/governance) screen.

## Cloud sync

Configure a cloud storage backend for this workspace. When cloud sync is enabled:
- Workspace configuration, agents, flows, and secrets are replicated to the configured bucket.
- The workspace can be restored on a new machine by pointing at the same bucket.

Fields: bucket URL, access credentials, sync interval, and encryption key.

**Persistent sync state.** Sync state is persisted, so it survives a restart — the workspace resumes from where it left off instead of re-syncing from scratch or losing its audit trail.

**Pause and resume.** You can pause the sync loop at any time and resume it later. The paused state persists across restart, so a paused workspace stays paused until you explicitly resume it.

**Sync history.** A paginated history records every sync event so you can audit what happened and when. Entries are one of: `sync`, `pause`, `resume`, or `conflict-resolved`, each with a timestamp and outcome.

## Isolation

The Isolation section controls how strictly this workspace is isolated from others on the same AKOS installation. Three levels are available:
- **None** — shared resources; no network isolation.
- **Standard** — default. Isolated storage and network namespaces.
- **Strict** — maximum isolation; additional constraints on cross-workspace access and shared caches.

Changes are reflected immediately on the Governance > Policies screen.

## Export / Import

The Export / Import section lets you:
- **Export workspace** — download a YAML/JSON snapshot of the entire workspace (agents, flows, triggers, secrets metadata — not secret values) for backup or migration.
- **Import workspace** — upload a previously exported file to restore or clone a workspace.

## Choosing files and folders

Anywhere AKOS needs a file or folder on disk — a SQLite database path for a connection, a file-backed agent memory store, a knowledge source folder, or a local artifact location — the field uses a **native picker** rather than asking you to type a raw path.

On the **desktop app**, click **Browse…** to open your operating system's standard file or directory dialog. The chosen path is filled in for you and shown read-only, so there are no typos or invalid paths. File pickers are filtered to the relevant extensions where it makes sense (for example, only database files when choosing a SQLite path).

In the **web console**, the native OS dialog is not available, so the field shows a standard file chooser instead. For paths that may be relative or contain glob patterns, an **Advanced: type manually** link reveals an editable field.

## Danger zone

The Danger zone section (visible to workspace owners only) contains destructive actions:
- **Rename workspace** — changes the name and slug.
- **Delete workspace** — permanently deletes the workspace and all its data. This action requires you to type the workspace name to confirm. It is not reversible.

> The Delete button is only enabled if another workspace exists to switch to, preventing you from accidentally deleting your only workspace.

## Related screens

| Need | Go to |
|---|---|
| Integrations | [Connections](/docs/using-the-app/connections) |
| Workspace settings (`config`) | [Route-only screens](/docs/using-the-app/route-only-screens) |
| Bundle history (`bundles`) | [Route-only screens](/docs/using-the-app/route-only-screens) |
| Access policy | [Access](/docs/using-the-app/governance) |

Source: /raw/using-the-app/workspaces.mdx

## for-agents index

### for-agents/AGENT-MERGE-RULES.md

# AGENT MERGE RULES

Mandatory protocol for any agent resolving merge conflicts, rebasing, or otherwise touching another agent's work. Implements ADR-0039.

## Prime directive

> Merges SUM work. They never silently subtract.

If you are about to make another agent's exports, files, or behavior disappear, STOP and verify it is explicitly acknowledged.

## Allowed actions

- Take the union of two independent additive changes.
- Reconcile two refactors by merging the stronger parts of each, then explain the choice in the commit body.
- Reorder imports / fix formatting on the merged result.

## Forbidden actions

- `git checkout --theirs <path>` or `git checkout --ours <path>` without a `merge-override: <reason>` annotation in the commit body.
- Bulk-resolving conflicts by re-creating a file from scratch.
- `git reset --hard` to skip the resolution.
- Squashing a branch in a way that drops a co-author's commits without `Co-authored-by:` + acknowledgement.

## Required record-keeping

When the resolution chooses one side over another, OR removes any exported symbol, file, or feature:

1. Add to the commit body:
   ```
   removes:
     - <path or symbol> — <reason>
   ```
2. Optionally update `.github/pr-intent.yaml` with the same entry.
3. If the removal is API-facing, ensure it traversed a `@deprecated` lifecycle in a prior release.

## How to verify locally before pushing

```bash
node scripts/check-no-silent-deletion.mjs
```

This compares exported symbols between BASE_REF (default `main`) and HEAD, plus removed files, plus net deletions. It validates that every disappearance is acknowledged.

To check the manifest shape:

```bash
node scripts/check-pr-intent.mjs
```

## When in doubt

Abort. `git rebase --abort` or `git merge --abort`. Open a discussion with the human reviewer. Losing the work of another agent is worse than losing time.

## What CI does

CI runs `check-no-silent-deletion` and `check-pr-intent` on every PR. A failing gate blocks merge until the missing acknowledgement is added or the resolution is corrected.

Source: /raw/for-agents/AGENT-MERGE-RULES.md

### for-agents/INDEX.md

# 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) |

Source: /raw/for-agents/INDEX.md

### for-agents/README.md

# AgentsKitOS — Documentation for Agents

This directory exists so the in-OS copilot has reliable context when
indexing the workspace knowledge base. The folder structure mirrors the
shipped package + screen layout so RAG retrieval surfaces the right
chunk for the right task.

## Layout

```
docs/for-agents/
  packages/            # one markdown per packages/os-* package
    os-core.md
    os-headless.md
    …
  screens/             # one markdown per desktop screen
    flows.md
    runs.md
    …
  flows/               # canonical workflow recipes (14; each maps a human guide)
    prd-to-pr.md
    eval-suite.md
    …
  components/          # shared desktop form/copilot frames (6)
    catalog-combobox.md
    …
  contracts/           # JSON-RPC method reference, indexed by name
```

## Conventions

For workspace-wide code conventions (file size targets, function size targets, sub-path layout after RFC-0017, navigation rules), see [`conventions.md`](./conventions.md). Read this first if you're touching any package.

For monorepo-maintenance work (CI/script cleanup, cross-cutting package
ownership, stale docs, or adding packages), see
[`ecosystem-maintenance.md`](./ecosystem-maintenance.md).

Every package doc has the same six sections so the copilot can extract
predictable answers:

1. **Purpose** — one-paragraph what the package does.
2. **Public exports** — entry points + key types.
3. **Wired stores** — persistence dependencies.
4. **Calls** — JSON-RPC methods the package implements.
5. **Calls** — methods the package consumes.
6. **Common questions** — recipe-shaped Q&A pairs the copilot can quote.

Screen docs are shorter (four sections when a human guide exists): human
guide (optional), purpose, wired methods, edge cases. Flow recipes and
component docs follow the same pattern.

Human-guide mappings consumed by `pnpm docs:internal:query`:

| Mapping file | Covers |
|---|---|
| `scripts/lib/human-screen-docs.mjs` | Desktop + admin screen ids → MDX / operator README |
| `scripts/lib/human-flow-docs.mjs` | 14 flow recipes → MDX / enterprise guides |
| `scripts/lib/human-component-docs.mjs` | 6 shared components → owner-screen MDX |
| `scripts/sync-human-guide-links.mjs` | Adds resolvable relative links under `## Human guide` |

After adding a screen, flow, or component doc, run
`pnpm docs:sync-human-guides` and `pnpm check:human-guide-links` (also in `check:hygiene`).

## Indexing

This corpus is **not** indexed into the assistant automatically at workspace
creation. Two paths feed the in-OS copilot:

1. **Contract catalog (always on).** `packages/os-headless/src/copilot-bootstrap.ts`
   builds `llms.txt` from `@agentskit/os-contracts` and injects a truncated
   `INDEX.md` link summary into the system prompt via
   `for-agents-doc-summary.ts`.
2. **RAG folder sources (operator opt-in).** `prod.seed.*` handlers in
   `packages/os-headless/src/transport/handlers/prod-seed-handlers.ts` register
   four ledgered folder sources when you run
   `agentskit-os prod seed --target assistant-knowledge --apply`, then rebuild
   each source with `agentskit-os knowledge rebuild <source-id>`:

   | Source id | Path |
   |---|---|
   | `assistant-knowledge-for-agents` | `docs/for-agents` |
   | `assistant-knowledge-user-docs` | `apps/web/content/docs` |
   | `assistant-knowledge-demo-docs` | `docs/demo` |
   | `assistant-knowledge-runbooks` | `docs/runbooks` |

   The chunker is markdown-aware so each section becomes its own retrieval
   target. Full operator steps: [`docs/demo-runbook.md`](../demo-runbook.md)
   (assistant-knowledge section).

## Finding docs (agents)

| Need | Command |
|---|---|
| Search any doc, package, screen, or flow | `pnpm docs:internal:query search <term> --agent` |
| Desktop or admin screen guide | `pnpm docs:internal:query screen <id> --agent` |
| Workflow recipe (+ human doc when mapped) | `pnpm docs:internal:query flow <id> --agent` |
| Shared desktop component | `pnpm docs:internal:query component <id> --agent` |
| Package ownership + checks | `pnpm docs:internal:query ownership <pkg> --agent` |
| Curated reading path | `pnpm docs:internal:query intent find-documentation-for-agents-or-humans` |
| Regenerate machine index | `pnpm docs:internal` |
| Validate doc drift gates | `pnpm check:knowledge-map && pnpm check:contracts-doc && pnpm check:doc-code-accuracy` |

Source: /raw/for-agents/README.md

### for-agents/THE-FIVE-RULES.md

# THE FIVE RULES

Agent-prompt-ready summary. If you touch shipped code, these are non-negotiable. Full rationale: ADR-0036 through ADR-0040.

## 1. UI = `@agentskit/os-ui` only

- Banned in `packages/os-desktop/src/**`, `apps/**/src/**`, `packages/pack-*/src/**`:
  `<button>`, `<input>`, `<select>`, `<textarea>`, `<dialog>`, `<form>`, `<table>`, `<a href>`.
- Use os-ui components: `Button`, `Input`, `Select`, `Textarea`, `Dialog`, `Form`, `Table`, `Link`.
- Missing primitive? Open issue on `os-ui`, do NOT inline HTML.
- Escape hatch: `// allow-native: <ADR/issue> — <reason>` line above the element.
- See [ADR-0036](../adr/0036-ui-only-via-os-ui.md).

## 2. Every user-visible string is intl

- JSX text nodes, `aria-label`, `title`, `placeholder`, `alt`, `aria-description` → `t('key')` or `<FormattedMessage/>`.
- Toast/notification/error UI text → intl key resolved by `os-i18n`.
- Brand names and untranslatable tokens → `i18n/exempt-tokens.json`.
- Escape hatch: `// allow-hardcoded: <reason>`.
- See [ADR-0037](../adr/0037-strict-intl-zero-hardcoded.md).

## 3. Every visual primitive uses whitelabel tokens

- No hex/rgb/rgba/hsl/hsla/oklch literals.
- No Tailwind arbitrary color values (`bg-[#…]`, `text-[rgb(…)]`).
- No inline `style={{ color|background|border|boxShadow|fill|stroke: <literal> }}`.
- Use: Tailwind class from `os-whitelabel` preset, `tokens.color.*`/`tokens.space.*`, or `var(--ak-color-…)`.
- SVG color literals live ONLY inside `os-ui/assets/icons/`.
- Escape hatch: `// allow-literal-color: <reason>`.
- See [ADR-0038](../adr/0038-whitelabel-tokens-only.md).

## 4. Merge sums work, never subtracts

- Every PR has a `pr-intent.yaml` (or PR-body section) listing `adds:`, `modifies:`, `removes:`.
- Removing another author's exported symbol/file requires entry in `removes:` with reason + replacement target.
- API removal needs `@deprecated` for ≥1 release before deletion.
- Resolving conflicts: **union first**. Picking one side requires commit message `merge-override: <reason>`.
- Agents: NEVER run `git checkout --theirs/--ours` without that annotation.
- See [ADR-0039](../adr/0039-merge-sums-never-subtracts.md) and [`AGENT-MERGE-RULES.md`](./AGENT-MERGE-RULES.md).

## 5. Ship complete or don't ship

- Banned in shipped source: `TODO`, `FIXME`, `XXX`, `throw new Error('not implemented')`, `{ stub: true }`, `disabled: true` tabs, `it.todo(...)`, empty exported bodies, `*.preview.*`, `*-placeholder.*`, `*-mock.*`.
- Every screen in `os-desktop/src/screens/*/index.tsx` ships: intl header, empty state, error boundary, loading state, test, Storybook entry.
- Escape hatch: `// stub-allowed: <issue#> — <target release>`. Expires automatically.
- See [ADR-0040](../adr/0040-no-stubs-vision-intact.md).

---

## How agents must apply these

Before editing:
1. Read this file.
2. Read the routing table in `AGENTS.md`.
3. Run `pnpm check:dev` if you are unsure whether the local guardrails are already red.

While editing:
- Reach for os-ui first.
- Reach for `t(…)` before typing English.
- Reach for `tokens.*` before typing a color.
- Append, never silently overwrite.
- Finish what you start.

Before opening PR:
```bash
pnpm check:pr
pnpm check:full  # before release
```

PR body must include the 5-rules checklist (PR template enforces this).

## Verification commands

```bash
pnpm check:no-native-html-primitives   # Rule 1
pnpm check:no-hardcoded-strings        # Rule 2
pnpm check:no-color-literals           # Rule 3
pnpm check:pr-intent                   # Rule 4
pnpm check:no-silent-deletion          # Rule 4
pnpm check:stub-leaks                  # Rule 5
pnpm check:feature-completeness        # Rule 5
```

Source: /raw/for-agents/THE-FIVE-RULES.md

### for-agents/assistant-linkable-metadata.md

# Assistant-Linkable Metadata

Use this contract when a screen, catalog entry, or action should be discoverable by the assistant without adding a new branch to the assistant engine.

## Required Fields

Screen/page context should emit these fields when available:

- `screen`: stable route/surface id, such as `flows`, `connections`, `agents`, `pipeline`, or `knowledge`.
- `currentObject`: focused object as `kind:id`, with optional label and state.
- `visibleEntities`: important rows/cards the user can see.
- `availableActions`: plain action labels when only human-readable actions are known.
- `actionRefs`: stable action ids, labels, risk, and approval requirement.
- `catalogRefs`: stable references to screens, connectors, templates, packs, docs, or capabilities.
- `stateMachine`: active workflow/onboarding/setup machine id, state, and step.
- `recentEvidence`: validation, run, trace, audit, or request evidence the assistant can cite.

Product graph nodes should expose:

- `id`: stable node id.
- `what`: what the concept is.
- `where`: screen ids and optional docs.
- `how`: how the assistant should act safely.
- `aliases`: user terms that resolve to this node.
- `actions`: related action ids when an executable action exists.

## Examples

Workflow builder:

```txt
screen: flows
currentObject: workflow:billing-sync (Billing Sync) state=draft
actionRefs:
- action:flow.run_preview (Preview workflow) state=preview
catalogRefs:
- screen:flows (Flows)
stateMachine: onboarding:workflow state=editing/tools
recentEvidence:
- validation:val-billing-sync (missing Slack tool) state=failed
```

Connections:

```txt
screen: connections
currentObject: connector:slack (Slack) state=needs-auth
actionRefs:
- action:connection.oauth.start (Start OAuth) state=requires-approval
catalogRefs:
- connector:slack (Slack connector)
recentEvidence:
- healthcheck:slack (missing workspace token) state=failed
```

Agents:

```txt
screen: agents
currentObject: agent:triage-agent (Triage Agent) state=draft
actionRefs:
- action:agents.create (Create agent) state=mutation
catalogRefs:
- screen:agents (Agents screen)
stateMachine: onboarding:agent-setup state=drafting/tools
```

Pipelines/processes:

```txt
screen: pipeline
currentObject: pipeline:release (Release process) state=draft
actionRefs:
- action:pipelines.upsert (Save process) state=requires-approval
catalogRefs:
- screen:pipeline (Processes)
recentEvidence:
- validation:release-input-mapping (missing JSONPath) state=failed
```

Knowledge/RAG:

```txt
screen: knowledge
currentObject: source:handbook (Company Handbook) state=stale
actionRefs:
- action:rag.search (Search knowledge) state=read
catalogRefs:
- capability:rag (Knowledge/RAG)
recentEvidence:
- retrieval:handbook (citation missing) state=failed
```

## Rule

If a new screen can provide these fields, add metadata there first. Change the assistant engine only when the concept needs new behavior, not merely a new place to navigate.

Source: /raw/for-agents/assistant-linkable-metadata.md

### for-agents/backup-dr.md

# Backup / Restore / DR — for agents

Agent-facing summary of the self-host disaster-recovery contract
(ENT-5, issue #1714, epic #1709). Operator runbook lives in
[`../operations/self-host-backup.md`](../operations/self-host-backup.md);
this doc is the "what must stay true" for anyone editing the path.

## Surface

| File | Role |
|---|---|
| `packaging/backup-restore.sh` | `backup`/`restore` (pg-only, legacy) + `full-backup`/`full-restore` (full state). |
| `scripts/audit/dr-drill.mjs` | Hermetic, no-infra restore drill; writes `docs/audit/dr-drill-report.json`. |
| `scripts/audit/restore-sla.mjs` | Docker-gated DB restore-time SLA (#758). |
| `.github/workflows/dr-drill.yml` | Nightly + on-change drill, uploads evidence. |

## Invariants — do not regress

1. **Legacy contract is frozen.** `backup` / `restore` keep the exact
   pg-only behavior and dump filename shape (`akos-<stamp>.sql.gz`).
   Tooling and `restore-sla.mjs` parse that name.
2. **Full bundle is self-describing.** Every `full-backup` writes
   `MANIFEST.json` (`schema: akos.dr.manifest/1`) with per-component
   sha256. `full-restore` MUST verify the DB checksum and MUST refuse a
   bundle with no manifest — never silently partial-restore.
3. **Plaintext never leaves the host.** `--encrypt` happens before
   `--offsite`; offsite ships the `.enc` only. Wrong passphrase MUST
   fail loudly (non-zero exit), never produce an empty/partial restore.
4. **`--no-db` is the hermetic seam.** It skips all docker/pg calls so
   the drill runs in plain CI. Keep file-state logic independent of the
   DB path so this stays true.
5. **`AKOS_STATE_HOME` is the only state root.** Vault (`vaults/`) and
   plugin (`plugins/`) state resolve under it; tests/drills override it
   to a temp dir. Don't hardcode `$HOME/.agentskitos`.
6. **Drill stays green in `check:full`.** `check:dr-drill` is a STATIC
   gate. It must remain hermetic (no network, no docker) and fast.
7. **Key escrow is custody-separate (ENT-6 / #1715).** The managed key
   ring (`vaults/keyring.json`) IS bundled. The escrow blob
   (`exportEscrow`) is NOT — it lives in a secrets manager so one bundle
   leak can't both expose and unlock key material. Never add the escrow
   blob to the bundle. See `packages/os-security` +
   `docs/operations/self-host-backup.md#key-lifecycle-ent-6`.

## Data inventory (must stay covered)

DB tenant/catalog/usage + audit anchors (bundled `db.sql.gz` +
standalone `audit-anchors.sql.gz`), vault sealed-key metadata, plugin
inventory/cache, manifest. External telemetry (Langfuse/PostHog) is
explicitly out of scope — documented, not bundled. Adding a new
business-critical store? Add it to the bundle **and** the inventory
table in the operator doc **and** the drill's synthetic state.

## Evidence

`docs/audit/dr-drill-report.json` (`schema: akos.dr.drill/1`) is the
dated proof for the enterprise-readiness gate. Gitignored locally;
CI uploads it with 90-day retention. Fields: `status`, `filesRecovered`,
`restoreSeconds`, `rtoBudgetSeconds`, `checks[]`.

Source: /raw/for-agents/backup-dr.md

### for-agents/command-palette.md

# Command Palette (Cmd+K) — for agents and plugins

The desktop palette lives in `packages/os-desktop/src/command-palette/` and the headless backend (used by CLI / Tauri JSON-RPC) in `packages/os-headless/src/cmdk/`. Both consume the canonical `CommandPaletteAction` schema exported from `@agentskit/os-core`.

## Contract

```ts
import { CommandPaletteAction, type CommandCategory } from '@agentskit/os-core'

const action = CommandPaletteAction.parse({
  id: 'myplugin.deploy',
  label: 'Deploy to staging',
  i18n: { labelKey: 'myplugin.deploy.label' },
  keywords: ['ship', 'release'],
  category: 'Run',
  subcategory: 'Run > Deploys',
  icon: 'Rocket',
  dispatch: 'myplugin.deploy',
  capability: 'plugin:myplugin:deploy',
  shortcut: 'Ctrl+Shift+D',
  actions: [
    { id: 'rollback', label: 'Rollback', i18n: { labelKey: 'myplugin.deploy.rollback' } },
  ],
})
```

Categories: `Navigation | Build | Run | Workspace | Govern | Settings | Runtime | View | System | Recents | Favorites | Help | Account | Devtools`.

## Registering from a plugin

Two ingress paths:

1. **Direct hook** (in-process):
   ```ts
   import { useRegisterCommand } from '@agentskit/os-desktop/command-palette/use-register-command'
   useRegisterCommand({ id, label, keywords, category, run })
   ```

2. **Event-based** (sandboxed plugin → host bridge):
   ```ts
   window.dispatchEvent(new CustomEvent('ak:cmdk:register', { detail: action }))
   // Listen for dispatches the host routes back:
   window.addEventListener('ak:cmdk:dispatch', (e) => {
     const { dispatch, args, action: secondary } = (e as CustomEvent).detail
     if (dispatch === 'myplugin.deploy') deploy(args, secondary)
   })
   // To remove:
   window.dispatchEvent(new CustomEvent('ak:cmdk:unregister', { detail: { id: 'myplugin.deploy' } }))
   ```

The host validates every `ak:cmdk:register` payload against `CommandPaletteAction` (Zod) and silently drops malformed entries.

## i18n

Every label and category resolves at render time via `useT(key, fallback)` from `@agentskit/os-desktop/whitelabel/use-i18n`. Built-in keys live in `packages/os-desktop/src/locales/{en,es,pt-BR}.json` under the `palette.*` namespace.

Plugins should ship their own `localizedCopy[locale][labelKey]` via the whitelabel pack mechanism (ADR-0007). The palette falls back to the static `label` if the key is unresolved in the active locale.

## Keyboard

| Shortcut             | Action                                  |
|----------------------|------------------------------------------|
| `Cmd/Ctrl+K`         | Toggle palette                          |
| `↑ / ↓`              | Move selection                          |
| `Enter`              | Run selected                            |
| `Esc`                | Close (or close actions menu)           |
| `Tab` / `Shift+Tab`  | Cycle category filter                   |
| `Cmd/Ctrl+1..9`      | Jump directly to a category             |
| `Cmd/Ctrl+J`         | Open secondary actions menu             |
| `Cmd/Ctrl+. / +P`    | Pin / unpin the selected command        |
| `Cmd/Ctrl+Backspace` | Clear query                             |

## Backend search

The desktop overlay calls `cmdk.search` over JSON-RPC (when a query is non-empty) and merges the dynamic entity hits (flows, agents, triggers, runs, traces, integrations, knowledge, secrets) into the result list. Dispatch back to entity actions via `ak:cmdk:dispatch` with `{ dispatch, args, id, kind }`.

## Tests

- `__tests__/command-palette-overlay.test.tsx` — open/close, keyboard nav, run dispatch
- `__tests__/use-command-search.test.ts` — fuzzy matching baseline
- `__tests__/search-extras.test.ts` — acronym + frecency
- `__tests__/use-recents.test.ts` — LRU + pin persistence
- `__tests__/plugin-bridge.test.tsx` — event-based registration round-trip

Source: /raw/for-agents/command-palette.md

### for-agents/components/catalog-combobox.md

# components/CatalogCombobox
## Human guide

[`agents.mdx`](../../../apps/web/content/docs/using-the-app/agents.mdx) (UI context for the shared form component)


Exported from `@agentskit/desktop-components` (`catalog-combobox.tsx`).

## Purpose

Generic catalog-backed typeahead with a **free-type fallback**. Unlike the
os-ui `Combobox` (which can only emit one of its rendered options), this picker
also lets the user keep a value that is *not* in the catalog — essential for
secret-reference fields (a vault key may not be stored yet) and
flow/workspace/connection pickers used before the target exists. Whatever the
user types becomes the committed value on Enter / blur / select.

## Data source

Options are supplied by a caller-provided `loader` callback, typically a
sidecar listing RPC — e.g. `secrets.list`, `workspaces.list`,
`flows.listInline`, `connections.list`. The loader is called **once**, lazily,
the first time the field opens; any rejection degrades to an empty list so the
field stays usable as free text.

## Props

| Prop | Type | Notes |
|---|---|---|
| `value` | `string` | Required, controlled. Shown verbatim when the menu is closed. |
| `onChange` | `(value: string) => void` | Required. Fires on pick, Enter, or blur (free-type commit). |
| `loader` | `() => Promise<readonly CatalogComboboxOption[]>` | Required. Lazy option source. |
| `placeholder` | `string?` | |
| `ariaLabel` | `string?` | |
| `disabled` | `boolean?` | |
| `idSuffix` | `string` | Required. Scopes listbox id + `data-testid`s. |
| `className` | `string?` | |

`CatalogComboboxOption = { value: string; label: string; description?: string }`.

## Usage

```tsx
import { CatalogCombobox } from '@agentskit/desktop-components'
import { useApiClient } from '@agentskit/desktop-sidecar-bridge'

const { request } = useApiClient()

<CatalogCombobox
  value={secretRef}
  idSuffix="agent-secret"
  ariaLabel="Secret reference"
  onChange={setSecretRef}
  loader={async () => {
    const res = await request<{ keys: string[] }>('secrets.list', {})
    return res.keys.map((k) => ({ value: k, label: k }))
  }}
/>
```

## Edge cases

- Empty/loading menu still accepts typed input ("type to use a custom value").
- Blur commits the typed text (free-type fallback); Escape cancels the query.
- All visible strings resolve through the injected `useDesktopT` TFn (ADR-0037).

Source: /raw/for-agents/components/catalog-combobox.md

### for-agents/components/configuration-plan-step.md

# components/ConfigurationPlanStep
## Human guide

[`copilot.mdx`](../../../apps/web/content/docs/using-the-app/copilot.mdx) (UI context for the shared form component)


Inline copilot render frame registered in
`packages/desktop-agent-workspace/src/copilot/components/advisory-inline-components.tsx`.

## Purpose

Post-selection setup plan shown after `ToolSelectionStep`. Lists each chosen
tool with per-item status (`ready`, `needs-admin`, `unavailable`, `mcp`) and
setup guidance from the integration registry. The assistant uses this frame to
route the user to Connections, MCP, or admin-only configuration without
exposing secrets inline.

## Props schema

| Field | Type | Notes |
|---|---|---|
| `items` | `PlanItem[]` | Setup rows (max 24). |

Each `PlanItem` carries `id`, `label`, `icon`, `supported`, `source`
(`integration` \| `mcp` \| `both` \| `other`), `status`, optional `facets`,
`mode`, `cta`, `summary`, and optional setup detail fields (`docsUrl`,
`credentialUrl`, `requiredScopes`, etc.).

## User actions

- **Configure** — dispatches `connection.configure` or `mcpServer.configure`
  depending on `source`.
- Items with `status: unavailable` show guidance only; no configure action.

## Related

- Predecessor frame: [`tool-selection-step.md`](./tool-selection-step.md)
- Screen: [`copilot.md`](../screens/copilot.md)
- Registry: integration setup metadata consumed by
  `packages/os-copilot/src/orchestration/integration-setup-machine.ts`

Source: /raw/for-agents/components/configuration-plan-step.md

### for-agents/components/file-path-input.md

# components/FilePathInput
## Human guide

[`coding.mdx`](../../../apps/web/content/docs/using-the-app/coding.mdx) (UI context for the shared form component)


Exported from `@agentskit/desktop-components` (`file-path-input.tsx`).

## Purpose

A read-only path display plus a **native OS picker** button, so users never
type raw filesystem paths. On Tauri (desktop) the Browse button opens the
native file or directory dialog via `@tauri-apps/plugin-dialog`. In a browser
context the native dialog is unavailable: the Browse button is replaced with an
os-ui `FileInput` fallback (exposes the chosen file's name as the "path"). When
`allowManual` is true, an "Advanced: type manually" disclosure reveals an
editable input for relative paths or glob patterns.

## Data source

No RPC. Tauri detection is `'__TAURI_INTERNALS__' in window`; the dialog plugin
is dynamically imported (`@tauri-apps/plugin-dialog` → `open`).

## Props

| Prop | Type | Notes |
|---|---|---|
| `value` | `string` | Required, controlled — the selected path. |
| `onChange` | `(path: string) => void` | Required. |
| `mode` | `'file' \| 'directory'` | Required. |
| `accept` | `readonly string[]?` | Extension filter for the native dialog (`mode='file'` only), e.g. `['pdf','db','json']`. |
| `label` | `string?` | Visible label above the field. |
| `placeholder` | `string?` | Defaults to `/path/to/file` or `/path/to/folder`. |
| `ariaLabel` | `string?` | Falls back to `label`/placeholder. |
| `allowManual` | `boolean?` | Default `false`. Shows the manual-entry disclosure. |
| `dataTestId` | `string?` | Display input; manual input gets `-manual`, toggle `-manual-toggle`. |

## Usage

```tsx
import { FilePathInput } from '@agentskit/desktop-components'

<FilePathInput
  mode="file"
  accept={['db', 'sqlite']}
  label="SQLite database"
  value={dbPath}
  onChange={setDbPath}
  allowManual
  dataTestId="sql-conn-path"
/>
```

## Edge cases

- Browser host has no native dialog → os-ui `FileInput` fallback (file name only).
- Cancelling the dialog leaves the value unchanged.
- ADR-0036 (os-ui Button/Input only), ADR-0037 (intl via `useDesktopT`),
  ADR-0038 (token-only colours).

Source: /raw/for-agents/components/file-path-input.md

### for-agents/components/id-field.md

# components/IdField
## Human guide

[`agents.mdx`](../../../apps/web/content/docs/using-the-app/agents.mdx) (UI context for the shared form component)


Exported from `@agentskit/desktop-components` (`id-field.tsx`, with the
`autoGenerateId` / `resolveEffectiveId` / `useAutoId` helpers in `auto-id.ts`).

## Purpose

The shared "slug ID preview + Advanced override" block used by every
create/edit form (agents, SQL connections, external-secret providers, …).
Consolidates a previously duplicated pattern: a read-only `ID: <slug>` preview
line plus an "Advanced" disclosure that, **on create**, reveals an editable
override input. **On edit** the id is locked, so only the read-only preview is
rendered (changing an id would break references).

IDs are **auto-generated** from the human-readable name — the user never has to
invent a slug.

## Data source

No RPC. Pure derivation:

- `autoGenerateId(name)` → slug (lowercase, spaces/underscores→`-`, strip
  non-`[a-z0-9-]`, collapse/trim hyphens). E.g. `"AWS Secrets (v2)"` → `"aws-secrets-v2"`.
- `useAutoId(name, manualOverride?)` → `{ effectiveId, derivedId }` (override
  wins when non-empty).
- `resolveEffectiveId({ editing, currentId, override, derivedId })` → the id
  actually submitted (locked to `currentId` when editing).

## Props

| Prop | Type | Notes |
|---|---|---|
| `effectiveId` | `string` | The id that will be submitted (override or derived). |
| `idOverride` | `string` | Current override input value. |
| `onIdOverrideChange` | `(value: string) => void` | |
| `derivedId` | `string` | Name-derived slug; used as the override placeholder. |
| `editing` | `boolean` | When true the id is locked (preview only). |
| `idSuffix` | `string` | Prefix for `data-testid`s (`-id-preview`, `-advanced-toggle`, `-advanced-fields`, `-override-input`). |
| `error` | `string \| null?` | Validation error under the preview. |
| `errorId` | `string?` | Error node id (wired into `aria-describedby`). |
| `onOverrideBlur` | `() => void?` | Inline validation on blur. |
| `overridePlaceholder` | `string?` | Defaults to `derivedId`. |

## Usage

```tsx
import { IdField, useAutoId, resolveEffectiveId } from '@agentskit/desktop-components'

const { effectiveId, derivedId } = useAutoId(name, override)

<IdField
  effectiveId={resolveEffectiveId({ editing, currentId, override, derivedId })}
  idOverride={override}
  onIdOverrideChange={setOverride}
  derivedId={derivedId}
  editing={editing}
  idSuffix="agent-form"
/>
```

## Edge cases

- Edit mode renders the preview only — no override input.
- Empty name → empty slug; the override placeholder guides the user.
- ADR-0036 (os-ui Button/Input only), ADR-0037 (intl via `useDesktopT`),
  ADR-0038 (token-only colours).

Source: /raw/for-agents/components/id-field.md

### for-agents/components/model-catalog-combobox.md

# components/ModelCatalogCombobox
## Human guide

[`model-catalog.mdx`](../../../apps/web/content/docs/using-the-app/model-catalog.mdx) (UI context for the shared form component)


Exported from `@agentskit/desktop-components` (`model-catalog-combobox.tsx`).

## Purpose

Searchable, single-select model picker backed by the **live model catalog**
(models.dev snapshot — 144 providers, 5244 models) served by the
`models.catalog.list` RPC. Search is performed **server-side** (debounced
~200ms) so the dropdown never renders thousands of rows: typing narrows via the
RPC's `search` param; the empty query shows the first page (`limit: 60`). Each
option shows the model name, provider · model id, and capability pills
(`reasoning`, `tools`). Replaces free-text model fields across the create/edit
forms.

## Data source

RPC: `models.catalog.list` (via `useApiClient().request` from
`@agentskit/desktop-sidecar-bridge`).

- Params: `{ limit: number; search?: string }`
- Result: `{ providers: { id, name, models: { id, name, reasoning?, tool?, attach? }[] }[]; modelCount: number }`

The component flattens providers×models into rows and shows
`Showing {shown} of {total}` when the result is truncated.

## Props

| Prop | Type | Notes |
|---|---|---|
| `value` | `string?` | Current stored value, display-only when the menu is closed. |
| `onSelect` | `(selection: ModelSelection) => void` | Required. Emits `{ providerId, providerName, modelId, modelName }` so the field formats the stored value its own way (e.g. `provider:model`). |
| `placeholder` | `string?` | Defaults to "Search 5244 models…". |
| `ariaLabel` | `string?` | Defaults to "Choose a model from the catalog". |
| `ariaInvalid` | `boolean?` | Forwards to the input. |
| `disabled` | `boolean?` | |
| `idSuffix` | `string?` | Scopes the listbox id + `data-testid`s. |

`ModelSelection = { providerId; providerName; modelId; modelName }`.

## Usage

```tsx
import { ModelCatalogCombobox } from '@agentskit/desktop-components'

<ModelCatalogCombobox
  value={model}
  idSuffix="agent-form"
  ariaInvalid={Boolean(error)}
  onSelect={(s) => setModel(`${s.providerId}:${s.modelId}`)}
/>
```

## Edge cases

- An RPC rejection degrades to an empty list (input stays usable).
- A stale request is dropped via an internal sequence ticket (last query wins).
- All visible strings resolve through the injected `useDesktopT` TFn (ADR-0037).

Source: /raw/for-agents/components/model-catalog-combobox.md

### for-agents/components/tool-selection-step.md

# components/ToolSelectionStep
## Human guide

[`copilot.mdx`](../../../apps/web/content/docs/using-the-app/copilot.mdx) (UI context for the shared form component)


Inline copilot render frame registered in
`packages/desktop-agent-workspace/src/copilot/components/advisory-inline-components.tsx`.

## Purpose

Onboarding step that lets the user pick tools, MCP servers, and integrations
for their vertical. Rendered by `onboarding-machine.ts` and
`assistant-conversation-controller.ts` when the assistant flow reaches tool
selection. Also listed in `RENDER_FRAME_GUIDE` inside
`packages/os-copilot/src/prompt.ts` so the LLM can render it in chat.

## Props schema

| Field | Type | Notes |
|---|---|---|
| `vertical` | `string \| null` | Active vertical context (optional). |
| `options` | `ToolOption[]` | Visible choices (max 24). |
| `allOptions` | `ToolOption[]` | Full catalog for search/facets (max 200, optional). |
| `facets` | `Facet[]` | Category filters (max 20, optional). |
| `loading` | `boolean` | Show loading state (optional). |

Each `ToolOption` carries `id`, `label`, `icon`, `supported`, optional
`source` (`integration` \| `mcp` \| `both`), `category`, `capabilities`,
`facets`, and optional `setup` guidance from the integration registry.

## User actions

- Select one or more tools, then continue — dispatches inline input with
  selected tool ids.
- Skip — advances onboarding without tool selection.
- Search and facet filters narrow `allOptions` without leaving the frame.

## Related

- Screen: [`copilot.md`](../screens/copilot.md)
- Flow: adaptive onboarding in `packages/desktop-agent-workspace/src/copilot/conversation/onboarding-machine.ts`
- Successor frame: [`configuration-plan-step.md`](./configuration-plan-step.md)

Source: /raw/for-agents/components/tool-selection-step.md

### for-agents/contracts/README.md

# JSON-RPC Contracts — Method Reference Index

This index points the in-OS copilot (and any agent indexing the workspace via `folder://docs/for-agents`) at the canonical JSON-RPC method registry.

**Source of truth: [`packages/os-contracts/src/methods/`](../../../packages/os-contracts/src/methods/).** Every method shipped by the sidecar is registered there with a Zod params schema and a Zod result schema. ADR-0027 defines the registry shape; the dispatcher in `packages/os-contracts/src/dispatcher.ts` enforces it.

If the count below disagrees with the source, the source wins — re-run `pnpm --filter @agentskit/os-contracts build` and grep `methods/`.

## Counts

- **Methods registered:** ~269 across 57+ namespaces
- **Registry file:** [`packages/os-contracts/src/registry.ts`](../../../packages/os-contracts/src/registry.ts)
- **Dispatcher (boundary enforcement):** [`packages/os-contracts/src/dispatcher.ts`](../../../packages/os-contracts/src/dispatcher.ts)
- **Wire-format reference:** [`docs/spec/a2a-wire-format-v1.md`](../../spec/a2a-wire-format-v1.md)

## Namespace index

Each row points to the file that defines the methods in that namespace. Open the file to see params + result Zod schemas, JSDoc, and `requireAuth` / `requireConsent` flags.

| Namespace | File | Purpose |
|---|---|---|
| `access.*` | [`break-glass.ts`](../../../packages/os-contracts/src/methods/break-glass.ts) | Break-glass elevation list / revoke |
| `actions.*` | [`actions.ts`](../../../packages/os-contracts/src/methods/actions.ts) | Action Registry discovery (intent → canonical RPC + gates, RFC-0053) |
| `agentGen.*` | [`generative.ts`](../../../packages/os-contracts/src/methods/generative.ts) | NL → agent parsing |
| `agents.*` | [`generative.ts`](../../../packages/os-contracts/src/methods/generative.ts) | Agent CRUD, overrides, transitions |
| `anomalies.*` | [`observability.ts`](../../../packages/os-contracts/src/methods/observability.ts) | Anomaly list / upsert / delete |
| `assets.*` | [`assets.ts`](../../../packages/os-contracts/src/methods/assets.ts) | Run-output artifact gallery — list, get renderable view |
| `audit.*` | [`audit.ts`](../../../packages/os-contracts/src/methods/audit.ts) | Signed audit batches (Merkle), entry verify |
| `authoring.*` | [`authoring.ts`](../../../packages/os-contracts/src/methods/authoring.ts) | Authoring Gateway — side-effect-free dry-run / simulation (RFC-0053) |
| `auth.*` | [`auth.ts`](../../../packages/os-contracts/src/methods/auth.ts) | Device-code OAuth flow for CLI login (start + poll) |
| `backup.*` | [`backup.ts`](../../../packages/os-contracts/src/methods/backup.ts) | DR — live `backup.create` snapshot RPC (ADR-0132) |
| `billing.*` | [`oem.ts`](../../../packages/os-contracts/src/methods/oem.ts) | Plan + invoice surfacing (Stripe events arrive via webhook) |
| `bundles.*` | [`marketplace.ts`](../../../packages/os-contracts/src/methods/marketplace.ts) | Bundle import / export / diff / list |
| `capabilities.*` | [`capabilities.ts`](../../../packages/os-contracts/src/methods/capabilities.ts) | Adaptive onboarding capability catalog + resolution (catalog.list, resolve) |
| `cloud.*` | [`cloud-sync.ts`](../../../packages/os-contracts/src/methods/cloud-sync.ts) | Vault sync, remote cron toggle, vault history/restore |
| `cloud-sync.*` | [`cloud-sync-status.ts`](../../../packages/os-contracts/src/methods/cloud-sync-status.ts) | Operator sync status/pause/resume, persisted paginated history, conflicts list/resolve |
| `cmdk.*` | [`cmdk.ts`](../../../packages/os-contracts/src/methods/cmdk.ts) | Command palette search + commands |
| `coding.*` | [`sdlc.ts`](../../../packages/os-contracts/src/methods/sdlc.ts) | Coding agent providers, permission profiles, `runTask` |
| `collab.*` | [`collab.ts`](../../../packages/os-contracts/src/methods/collab.ts) | Workspace invites + share grants |
| `compliance.*` | [`governance.ts`](../../../packages/os-contracts/src/methods/governance.ts) | SOC 2 / HIPAA / GDPR export wizard |
| `connections.*` | [`connections.ts`](../../../packages/os-contracts/src/methods/connections.ts) | OAuth start / complete / verify, LLM provider OAuth |
| `consent.*` | [`consent.ts`](../../../packages/os-contracts/src/methods/consent.ts) | User consent grant / revoke / list |
| `copilot.*` | [`copilot.ts`](../../../packages/os-contracts/src/methods/copilot.ts) | In-OS copilot sessions, slash commands, proactive triggers |
| `cost.*` | [`observability.ts`](../../../packages/os-contracts/src/methods/observability.ts) | Cost breakdown, alerts, budgets |
| `dashboard.*` | [`dashboard.ts`](../../../packages/os-contracts/src/methods/dashboard.ts) | Dashboard tiles + widgets |
| `demo.seed.*` | [`demo-seed.ts`](../../../packages/os-contracts/src/methods/demo-seed.ts) | Materialise / reset the per-vertical demo bundle (backs `agentskit-os seed`) |
| `prod.*` | [`prod-seed.ts`](../../../packages/os-contracts/src/methods/prod-seed.ts) | Production seed ledger — plan, apply, and list applied demo/assistant-knowledge seeds |
| `dispatch.*` | [`runs.ts`](../../../packages/os-contracts/src/methods/runs.ts) | Run dispatch / cancel / replay |
| `egress.*` | [`egress.ts`](../../../packages/os-contracts/src/methods/egress.ts) | Egress allowlist, override flows |
| `evals.*` | [`evals.ts`](../../../packages/os-contracts/src/methods/evals.ts) | Eval suite runs + diff |
| `firewall.*` | [`security.ts`](../../../packages/os-contracts/src/methods/security.ts) | Prompt firewall config |
| `flows.*` | [`runs.ts`](../../../packages/os-contracts/src/methods/runs.ts) | Flow CRUD, validate, upsertInline |
| `governance.*` | [`governance.ts`](../../../packages/os-contracts/src/methods/governance.ts) | Policy + compliance metadata |
| `harness.*` | [`integrations.ts`](../../../packages/os-contracts/src/methods/integrations.ts) | Integration harness — list, run, results |
| `hitl.*` | [`runs.ts`](../../../packages/os-contracts/src/methods/runs.ts) | HITL inbox: list, decide, escalate |
| `incidents.*` | [`observability.ts`](../../../packages/os-contracts/src/methods/observability.ts) | Incident records + linkage |
| `interactionProfile.*` | [`interaction-profile.ts`](../../../packages/os-contracts/src/methods/interaction-profile.ts) | Authoring-assistant Interaction Profile — tone/detail/safety prefs (RFC-0053 F2.8 / ADR-0156, orientation only) |
| `knowledge.*` | [`knowledge.ts`](../../../packages/os-contracts/src/methods/knowledge.ts) | RAG sources, reindex, search |
| `kv.*` | [`kv.ts`](../../../packages/os-contracts/src/methods/kv.ts) | Workspace KV (scoped) |
| `lifecycle.*` | [`generative.ts`](../../../packages/os-contracts/src/methods/generative.ts) | Agent lifecycle state transitions |
| `manifest.*` | [`manifest.ts`](../../../packages/os-contracts/src/methods/manifest.ts) | Live capability manifest for agent discovery (RFC-0012/RFC-0053) |
| `marketplace.*` | [`marketplace.ts`](../../../packages/os-contracts/src/methods/marketplace.ts) | Listings, install, publish, ratings |
| `marketplace.domainPacks` / `marketplace.monitoringPacks` / `marketplace.apply*Pack` | [`integrations.ts`](../../../packages/os-contracts/src/methods/integrations.ts) | Curated official packs by category (domain, monitoring — ADR-0052; security — ADR-0054) + audited apply |
| `mcp.*` | [`mcp.ts`](../../../packages/os-contracts/src/methods/mcp.ts) | MCP bridge: discover, publish, consume |
| `models.*` | [`models-catalog.ts`](../../../packages/os-contracts/src/methods/models-catalog.ts) | Model catalog (models.dev snapshot, 5244 models) for autocomplete pickers |
| `oauth.*` | [`connections.ts`](../../../packages/os-contracts/src/methods/connections.ts) | OAuth hub callbacks |
| `integrations.send` / `slack.post` / `github.createComment` | [`integrations.ts`](../../../packages/os-contracts/src/methods/integrations.ts) | Outbound integration delivery — egress-gated, OAuth-hub credentials (S8.5) |
| `pipelines.*` | [`pipelines.ts`](../../../packages/os-contracts/src/methods/pipelines.ts) | Multi-phase pipeline integrator: dispatch, gates, JSONPath input mapping (replaces `sdlc.*`) |
| `plugins.*` | [`plugins.ts`](../../../packages/os-contracts/src/methods/plugins.ts) | Plugin lifecycle: install, list, get, enable, disable, uninstall |
| `rag.*` | [`knowledge.ts`](../../../packages/os-contracts/src/methods/knowledge.ts) | RAG knowledge sources: source CRUD, OAuth, encryption, embedder config |
| `observability.*` | [`observability.ts`](../../../packages/os-contracts/src/methods/observability.ts) | Trace + metric surfacing |
| `oem.*` | [`oem.ts`](../../../packages/os-contracts/src/methods/oem.ts) | OEM / white-label control |
| `onboarding.*` | [`onboarding-ecosystem.ts`](../../../packages/os-contracts/src/methods/onboarding-ecosystem.ts) | Adaptive Ecosystem Onboarding: per-workspace `EcosystemProfile` get/update/reset |
| `pii.*` | [`security.ts`](../../../packages/os-contracts/src/methods/security.ts) | PII redaction profiles |
| `plugins.*` | [`plugins.ts`](../../../packages/os-contracts/src/methods/plugins.ts) | Plugin install / list / get / enable / disable / uninstall |
| `rbac.*` | [`rbac.ts`](../../../packages/os-contracts/src/methods/rbac.ts) | Role + permission CRUD |
| `roles.*` | [`rbac.ts`](../../../packages/os-contracts/src/methods/rbac.ts) | Role assignments |
| `runner.*` | [`runs.ts`](../../../packages/os-contracts/src/methods/runs.ts) | Runner state machine introspection |
| `runs.*` | [`runs.ts`](../../../packages/os-contracts/src/methods/runs.ts) | Run history, get, list, cancel, replay |
| `runtime.*` | [`runs.ts`](../../../packages/os-contracts/src/methods/runs.ts) | Runtime status, capabilities |
| `sandbox.*` | [`sandbox.ts`](../../../packages/os-contracts/src/methods/sandbox.ts) | Sandbox spawn, override decisions |
| `sdlc.*` | [`sdlc.ts`](../../../packages/os-contracts/src/methods/sdlc.ts) | PRD → PR pipeline, gates, dispatch |
| `secrets.*` | [`external-secrets.ts`](../../../packages/os-contracts/src/methods/external-secrets.ts) | External vault refs (1Password, Vault, AWS SM) |
| `security.*` | [`security.ts`](../../../packages/os-contracts/src/methods/security.ts) | Firewall, redaction, vault state |
| `setup.*` | [`workspace.ts`](../../../packages/os-contracts/src/methods/workspace.ts) | First-run setup wizard steps |
| `share.*` | [`share-status.ts`](../../../packages/os-contracts/src/methods/share-status.ts) | Public share viewer state |
| `skills.*` | [`integrations.ts`](../../../packages/os-contracts/src/methods/integrations.ts) | Skill catalog list |
| `sql.*` | [`sql-connections.ts`](../../../packages/os-contracts/src/methods/sql-connections.ts) | SQL database connection registry — list / get / upsert / delete / test (ADR-0062) |
| `notifications.*` | [`notifications.ts`](../../../packages/os-contracts/src/methods/notifications.ts) | Actionable notifications: push, list, ack, dismiss |
| `status.*` | [`health.ts`](../../../packages/os-contracts/src/methods/health.ts) | Sidecar health + readiness |
| `sync.*` | [`cloud-sync.ts`](../../../packages/os-contracts/src/methods/cloud-sync.ts) | Background sync queue |
| `team.*`, `teams.*` | [`users-teams.ts`](../../../packages/os-contracts/src/methods/users-teams.ts) | Team CRUD, seat management |
| `telemetry.*` | [`telemetry.ts`](../../../packages/os-contracts/src/methods/telemetry.ts) | Opt-in telemetry events |
| `tools.*` | [`tools.ts`](../../../packages/os-contracts/src/methods/tools.ts) | Tool registry, contributions, run |
| `topologies.*` | [`generative.ts`](../../../packages/os-contracts/src/methods/generative.ts) | Multi-agent topology templates |
| `traces.*` | [`traces.ts`](../../../packages/os-contracts/src/methods/traces.ts) | Trace get, list, time-travel replay |
| `triggers.*` | [`triggers.ts`](../../../packages/os-contracts/src/methods/triggers.ts) | Cron, webhook, file, email, Slack, GitHub, CDC |
| `users.*` | [`users-teams.ts`](../../../packages/os-contracts/src/methods/users-teams.ts) | Principal CRUD |
| `verticals.*` | [`verticals.ts`](../../../packages/os-contracts/src/methods/verticals.ts) | Vertical definitions — list, get, upsert, delete |
| `voice.*` | [`voice.ts`](../../../packages/os-contracts/src/methods/voice.ts) | Assistant voice mode provider discovery + transcription |
| `whitelabel.*` | [`oem.ts`](../../../packages/os-contracts/src/methods/oem.ts) | White-label config + runtime gates |
| `workspace.*`, `workspaces.*` | [`workspace.ts`](../../../packages/os-contracts/src/methods/workspace.ts) | Workspace CRUD, isolation, snapshot/restore, `workspace.config.selfheal.*` (self-heal policy) + `workspace.config.activation.*` (activation-metrics consent) |

## Calling conventions

- **Transport:** JSON-RPC 2.0 over the headless sidecar (`packages/os-headless`). Desktop talks over Tauri IPC; cloud talks over HTTP. Same wire format either way — see `docs/spec/a2a-wire-format-v1.md`.
- **Auth:** every method declares `requireAuth` (principal id required) and may declare `requireConsent` (a `consent.grant` row must exist for the principal).
- **Errors:** dispatcher serialises `AgentsKitError` with `code` + `message` + `hint` + `docsUrl`. Unknown thrown errors are opaque-ified to `HANDLER_THREW`.
- **Request id:** clients must forward `x-request-id`. The dispatcher logs it on every server-side error so you can correlate UI failures to logs.

## How to add a new method

1. Pick or create a file under [`packages/os-contracts/src/methods/`](../../../packages/os-contracts/src/methods/).
2. Define params + result Zod schemas in `@agentskit/os-core` if reusable; otherwise inline.
3. Register the entry: `{ method, params, result, requireAuth, requireConsent? }`.
4. Implement the handler in the consuming package (handlers live in the package that owns the data).
5. Add the handler binding in `packages/os-headless/src/handlers/` so the sidecar serves it.
6. Add contract tests in the same `methods/*.test.ts` file: parse + reject cases.
7. Update this index if you introduce a new namespace.

ADR-0027 covers the registry shape and validation gates; RFC required only when you change wire envelopes or break an existing method signature.

Source: /raw/for-agents/contracts/README.md

### for-agents/contracts/control-plane-rpcs.md

# Contract — `control.*` namespace (Unified Control Plane)

> **Status: planned** (RFC-0054 F1). These methods are not yet registered. When implemented they live in `packages/os-contracts/src/methods/control-plane.ts` with Zod params + result schemas, per ADR-0027. The dispatcher (`os-contracts/src/dispatcher.ts`) enforces the boundary. Source of truth on implementation: the registry file, not this doc.

## Purpose

The `control.*` namespace exposes the Unified Control Plane: context resolution, tenant/account governance, membership/session/device, entitlement/license, distribution, RBAC, and readiness. Every method is `requireAuth`; mutating methods resolve a `ControlPlaneContext` (ADR-0157) server-side first and audit with `decision` + `reason`.

## Methods (planned)

| Method | Purpose | Notes |
|---|---|---|
| `control.context.resolve` | Build `ControlPlaneContext` for the caller | server-authoritative orgId |
| `control.context.whoami` | Human/agent-readable context summary | powers CLI `whoami`, desktop preflight |
| `control.context.refresh` | Re-resolve / re-mint context token | short-TTL (ADR-0161) |
| `control.accounts.list` / `.get` | Account (billing entity) read | |
| `control.tenants.list` / `.get` / `.create` / `.suspend` / `.resume` / `.delete` | Tenant lifecycle | cloud SoT; delete → DSAR; step-up on sensitive |
| `control.memberships.list` / `.setRole` | Membership read + role change | cap-gated, audited |
| `control.sessions.list` / `.revoke` | Session management | ADR-0153 model |
| `control.devices.list` / `.revoke` / `.pair` | Device/install management | device ≠ seat (ADR-0158) |
| `control.entitlement.get` / `.recompute` | EffectiveEntitlement read/recompute | ADR-0158 |
| `control.license.issue` / `.renew` / `.revoke` / `.verify` / `.revocationSnapshot` | License lifecycle | via license-service; signingKeyId (ADR-0160) |
| `control.distribution.channels.list` / `.manifest.get` / `.manifest.publish` / `.build.trigger` / `.rollback` | Governed distribution | channel = tenant+target (RFC-0054) |
| `control.capabilities.registry` | Capability descriptor registry | additive-only, versioned (ADR-0157) |
| `control.roles.get` / `.set` / `.simulate` | RBAC roles + simulate-as | human role ↔ runtime caps bridge (ADR-0006) |
| `control.permissions.explain` | Why a permission was allowed/denied | UI-facing explanation |
| `control.tenant.readiness` / `control.surface.readiness` / `control.distribution.readiness` | Readiness checks | `ready | needs_setup | degraded | blocked` |

## Gates (enforced at dispatch)

- Unknown capability → reject (`AK_FORBIDDEN`), never silent grant.
- Dangerous cap → reauth; mutating cap → audit; cross-tenant → explicit reason.
- Mutating method without a resolved `ControlPlaneContext` → fail-closed.
- `distributionMode` governs whether login/cloud is required for the surface.

## Error model

Typed `AK_*` errors (ADR-0007). No `any` in schemas. Indicative existing codes the surface reuses: `AK_AUTH_FAILED`, `AK_TENANT_MISMATCH`, `AK_FORBIDDEN`, `AK_LICENSE_REVOKED`, `AK_PLAN_CAP_EXCEEDED`.

## Related

- [`contracts/README.md`](./README.md) — full method registry index
- [`flows/control-plane-resolve.md`](../flows/control-plane-resolve.md) — resolution sequence
- [`packages/os-control-plane.md`](../packages/os-control-plane.md) — resolver package
- RFC-0054; ADR-0157 / 0158 / 0159 / 0160 / 0161; ADR-0027 (registry); ADR-0007 (errors)

Source: /raw/for-agents/contracts/control-plane-rpcs.md

### for-agents/conventions.md

# AgentsKitOS — Code Conventions for Agents

What an agent should expect when reading or writing code in this workspace.

## Package layout

The workspace currently has **76 package workspaces + 6 apps**. The table below calls out the consolidated root packages where sub-path exports matter; use [`INDEX.md`](./INDEX.md) and [`ecosystem-maintenance.md`](./ecosystem-maintenance.md) for the full owner map.

| Domain | Root package | Sub-paths |
|---|---|---|
| Foundations | `os-core`, `os-contracts`, `os-log`, `os-cli`, `os-storage` | — |
| Runtime | `os-runtime`, `os-runtime-agentskit`, `os-flow`, `os-headless`, `os-sandbox` | — |
| Integration | `os-triggers`, `os-mcp-bridge`, `os-import` | — |
| Marketplace | `os-marketplace` | `/registry`, `/plugins` |
| Observability + Security | `os-observability` (`/backend`, `/otel`, `/coding-task-report`), `os-audit` (`/server`, `/admin`), `os-security` | — |
| AI / Generative | `os-generative`, `os-copilot`, `os-coding-agents`, `os-dev-orchestrator`, `os-for-agents`, `os-rag` | — |
| Cloud | `os-cloud-sync`, `os-collab` | — |
| Admin | `os-tenant-config` (`/build-manifest`, `/model-catalog`), `os-license` (`/service`, `/billing`) | — |
| UX | `os-desktop`, `os-ui`, `os-whitelabel` (`/runtime`, `/plans`, `/config-client`) | — |
| Reference packs | `pack-loader`, `pack-fixtures-reference` | — |

**Find-the-owner rule:** import name segment 2 is the package, segment 3 (if any) is the sub-path. `@agentskit/os-marketplace/registry` lives in `packages/os-marketplace/src/registry/`.

## File size targets

| Layer | Soft cap (lines) | Hard cap (lines) |
|---|---|---|
| Pure logic (`*.ts` in `src/`) | 300 | 600 |
| RPC handler module (`*-handlers.ts`) | 500 | 1000 |
| React component (`*.tsx`) | 250 | 500 |
| Test file (`*.test.ts`) | 500 | — |

Files past the hard cap exist (e.g. `os-headless/src/transport/handlers.ts`) — these are known monoliths slated for incremental extraction. **Do not add to them.** Split into sibling files or sub-path modules.

## Function size targets

| Kind | Cap |
|---|---|
| Pure function | ≤ 40 lines, ≤ 5 params |
| Handler closure | ≤ 60 lines (extract inner helpers to module-level) |
| React component body | ≤ 80 lines (factor hooks + sub-components) |

When a function grows past the cap, the first move is **extract** (not annotate, not refactor in place). Pull named helpers to module scope; pull stateful sub-trees to their own component.

## Boundaries (non-negotiable, mirror CLAUDE.md)

1. No `any`. Zod parses every external boundary.
2. Named exports only. Never `export default`.
3. Errors at boundaries use `AgentsKitError` subclasses with `AK_*` codes.
4. Logs via `createLogger(tag)` from `@agentskit/os-log`. Never raw `console.*`.
5. No raw `throw new Error(...)` at a boundary — use a typed subclass.

## How an agent should navigate

1. **Start at `AGENTS.md`** — routing table maps "I want to change X" → package.
2. **Open the per-package doc** (`docs/for-agents/packages/<name>.md`) before touching the source. The "Public exports" + "Methods implemented/consumed" sections are the agent-facing API.
3. **Use sub-paths** when importing from a consolidated package (e.g. `import { ... } from '@agentskit/os-audit/admin'`, not `@agentskit/os-admin-audit` — that name no longer exists).
4. **Run the local gate** before declaring done: `pnpm --filter <pkg> lint && pnpm --filter <pkg> test`.
5. **Ship docs in the same PR.** If a new public export or method, update `docs/for-agents/packages/<name>.md` — out-of-date docs degrade copilot quality faster than missing tests.

## What not to do

- Don't reintroduce removed packages (`os-marketplace-sdk`, `os-admin-audit`, `os-plugins`, `os-billing`, `pack-bundle`, etc.). They live as sub-paths or replacement packages now.
- Don't create a new package without an ADR. Adding `packages/os-foo/` without ADR-0001/0002 alignment triggers the architecture guardrail.
- Don't add a `console.log` "for debugging" and forget to remove it — the lint sweep blocks merges.
- Don't grow a god-file. Cap → split.

Source: /raw/for-agents/conventions.md

### for-agents/ecosystem-maintenance.md

# Ecosystem Maintenance Map

Use this when a task is about monorepo health rather than one product feature.
It covers #5013 and its child issues: CI/script cleanup, cross-cutting package
ownership, stale docs, and package growth rules.

## Source of Truth

Current plan: this file plus `docs/adr/0119-ecosystem-cohesion-remediation.md`.

Do not resurrect missing historical plans such as
`docs/plans/saas-client-polish-plan.md` or
`docs/plans/product-readiness-discovery.md`; they are no longer in the repo.
When an issue points at them, route the work through the current map here.

## Cross-Cutting Ownership

| Flow | First owner | Also check | Do not create |
|---|---|---|---|
| Onboarding | `apps/web`, `apps/admin`, `packages/os-onboarding-telemetry` | `packages/os-control-plane`, `packages/os-capabilities`, `docs/for-agents/flows/customer-onboarding.md` | A new onboarding package |
| Billing and usage | `packages/os-license`, `packages/os-cost` | `apps/cloud`, `apps/license-service`, `packages/os-tenant-config` | A second plan or entitlement model |
| Templates and vertical packs | `packages/os-templates`, `packages/pack-loader`, `packages/pack-fixtures-reference` | `packages/os-whitelabel/verticals`, `docs/demo-runbook.md` | Another pack content home |
| Admin and OEM | `apps/admin`, `packages/os-oem`, `packages/desktop-platform-admin` | `packages/os-whitelabel`, `packages/os-tenant-config` | Admin-only copies of shared contracts |
| Web and mobile responsive product surface | `apps/web`, `packages/desktop-*`, `packages/os-ui` | `docs/for-agents/screens/*.md`, `docs/web/runtime-modes.md` | Bespoke web screens duplicating desktop screens |
| Notifications and inbox | `packages/os-notifications`, `packages/desktop-operations` | `packages/os-ui`, sidecar event producers in `packages/os-headless` | Hand-rolled toast or inbox stores |
| Conversational product surfaces | `packages/os-copilot`, `packages/desktop-agent-workspace` | `packages/os-statechart`, `packages/os-headless`, `packages/os-cli`, `apps/web`; see the [boundary audit](../audit/agentskit-chat-convergence-2026-07-14.md) and [private certification ledger](../audit/agentskit-chat-convergence-certification-2026-07-15.md) | A second chat controller, component protocol, host-specific copy of AgentsKit Chat, or divergent consolidated version |

Rule: if the flow already has an owner above, extend that owner or a listed
adjacent package. A new package needs the checklist below.

## Package Growth Checklist

Current package count: 76 `packages/*` workspaces, plus 6 apps and 20 test
workspaces.

Add a package only when all are true:

1. No existing owner package from `AGENTS.md` or this file can hold the change.
2. The code needs a narrower runtime or dependency surface, not just a nicer
   folder name.
3. The package will contain real logic, not only `export *` shims.
4. The dependency direction keeps `check:layers` and `check:vendor-isolation`
   green.
5. An ADR or accepted RFC names the boundary and migration path.
6. `docs/for-agents/packages/<pkg>.md`, workspace scripts, and public exports
   are updated in the same PR.

If one item is false, extend the existing package.

## CI And Script Inventory

Owner for CI workflows and `scripts/**`: `@EmersonBraun` via `.github/CODEOWNERS`.

| Group | Purpose | Essential gates | Notes |
|---|---|---|---|
| Root build/test | Workspace build, test, lint, typecheck | `build`, `test`, `lint`, `verify`, `check:typecheck` | Release and CI depend on these. |
| PR quality | Structural and honesty guardrails | `check:dev`, `check:pr`, `check:full` | Keep local loops cheap; put broad, slow, or release-grade checks in the full tier. |
| Release | Tag and release safety | `cold-build`, `check:release-gate`, `check:release-readiness`, `release` | Required release gates remain `pre-tag-cold-build.yml` and `pre-tag-cross-app.yml`. |
| Security | Secrets, CVE, RBAC, egress, tenant isolation | `check:secrets`, `check:cve-audit`, `check:rbac-handler-coverage`, `kernel:egress:proof` | Do not downgrade to advisory without security review. |
| Docs and generated registries | Generated agent docs, ADR index, status, API surface | `docs:generate`, `check:docs-fresh`, `status:generate`, `check:api-surface` | Run when changing docs indexes, exports, or status. |
| Demo/dogfood | Golden demos and vertical smoke | `dogfood:golden`, `demo:ready`, `wave:smoke:all` | Product-confidence lanes; keep out of minimal local loops. |
| E2E and visual | Browser, cross-app, mobile, visual regression | `e2e:*`, visual-regression workflows | Path-filtered or scheduled; not every PR should run all of them. |
| Dev helpers | Local boot and seed helpers | `dev:*`, `admin:*`, `demo:*` | Not CI gates. Keep ergonomic; do not let these become required release checks. |

## Dev Experience Contract

Default dev loops must be hot-reloading. Cold paths are fallbacks for debugging,
not the happy path.

| Surface | Command | Backend / sidecar mode | Contract |
|---|---|---|---|
| Desktop Tauri | `pnpm dev:desktop` | stdio sidecar wrapper over watched `os-headless` dist | Rebuild sidecar, exit wrapper, let Tauri reconnect. |
| Browser console | `pnpm dev:desktop-web` | HTTP sidecar on `127.0.0.1:4173` with watched `os-headless` dist | Vite stays up while the HTTP sidecar restarts on rebuild. |
| Demo browser | `pnpm dev:demo` | same as `dev:desktop-web`, with demo packs enabled | Demo data can reload without a manual sidecar rebuild. |
| Local platform | `pnpm dev:platform` | cloud + license + admin + web + hot HTTP sidecar | Backend and sidecar use watch mode; Postgres remains durable. |

Guardrail policy:

- Keep `check:dev` fast and local; do not add release/nightly gates to it.
- Use `check:pr` for changed-file-aware correctness.
- Use `check:full`, cold builds, dogfood, live assistant, soak, and mutation
  gates for CI, release, or nightly confidence.
- Use `check:sidecar-dev-hot` for the dev-loop contract above.

`check:pr` routes expensive checks by changed path. Use
`pnpm docs:internal:query guardrails --agent` or `docs/guardrails.md` for the
generated source-of-truth view, `pnpm check:pr --list` before running the PR
tier when the expected gates are unclear, and `pnpm check:pr --all` for
release-risky PRs or guardrail-router changes.

Known folded/obsolete item:

| Removed | Replacement | Why |
|---|---|---|
| `.github/workflows/pre-tag-full-stack-smoke.yml` | `.github/workflows/pre-tag-cross-app.yml` | It was a no-op tombstone after the curl-only smoke scripts were deleted. Cross-app E2E is the live release gate. |

## Human Guide Cross-Links

Every `docs/for-agents/screens/*.md`, `flows/*.md`, and `components/*.md` file
ships a `## Human guide` section with at least one resolvable markdown link to
the end-user MDX guide (or operator README for admin screens).

| Task | Command |
|---|---|
| Map a new screen id | Edit `scripts/lib/human-screen-docs.mjs` |
| Map a new flow recipe | Edit `scripts/lib/human-flow-docs.mjs` |
| Map a new shared component | Edit `scripts/lib/human-component-docs.mjs` |
| Sync relative links after edits | `pnpm docs:sync-human-guides` |
| Verify links resolve | `pnpm check:human-guide-links` |

Route-only screens should link both
[`route-only-screens.mdx`](../../apps/web/content/docs/using-the-app/route-only-screens.mdx)
and the owner-surface MDX when one exists (for example `plugins` → templates &
marketplace).

## Stale Docs Rule

Keep a historical doc only when it is clearly marked `IMPLEMENTED`,
`SUPERSEDED`, or `DEPRECATED` in the first screenful and points to the live
replacement. Otherwise delete it or move the useful facts into the current map.

Accepted ADRs may preserve historical package names, package counts, and
example paths. Do not rewrite accepted ADRs just to replace retired names such
as `pack-bundle`, `os-plugins`, old package totals, or vertical examples. Treat
those references as decision history; if current behavior needs a different
architecture, write a new ADR/RFC or add a superseding implementation note
outside the accepted record. The live inventory remains `AGENTS.md`, this file,
and `check:knowledge-map`.

The current `docs/plans/` files are allowed history:

| File | Status |
|---|---|
| `docs/plans/copilot-chat-ux-fixes.md` | Implemented; points to follow-up. |
| `docs/plans/copilot-chat-ux-fixes-followup.md` | Follow-up checklist; verify against source before using. |
| `docs/plans/ui-ux-unification-refactor.md` | Proposed plan; use only for UI/UX unification work. |

Known historical snapshots that intentionally preserve old package counts:

| File | Status |
|---|---|
| `docs/COVERAGE-BASELINE.md` | Historical coverage snapshot from 2026-05-20. |
| `docs/PACKAGE-GATE-MATRIX.md` | Historical coverage-gate snapshot from 2026-05-21. |
| `docs/pkg-refactor-plan/README.md` | Historical refactor-plan index from 2026-05-28. |
| `docs/pkg-refactor-plan/03-pack-bundle-split.md` | Historical `pack-bundle` migration plan; use `pack-loader` + `pack-fixtures-reference` now. |
| `docs/pkg-refactor-plan/09-agent-output-contracts.md` | Historical plan from the `pack-bundle` migration window. |
| `docs/pack-rewrite-epic/*.md` | Historical pack-rewrite plans from the removed `pack-bundle` layout; use `pack-loader` + `pack-fixtures-reference` now. |
| `docs/audit/*.md` mentioning retired package names | Historical audit/runbook snapshot; verify current source before acting. |
| `docs/product/desktop-web-simplification-{addendum,phase0}.md` | Historical vertical/YAML layout snapshot; verify current verticals before acting on counts. |
| `docs/rfc/*.md` mentioning retired package names | Historical implementation context; verify current source before acting on example paths. |
| `docs/adr/*.md` mentioning retired package names or old counts | Accepted decision history; do not rewrite for inventory churn. Create a new ADR/RFC when behavior changes. |

Source: /raw/for-agents/ecosystem-maintenance.md

### for-agents/flows/assistant-knowledge-seed.md

# Assistant knowledge seeding

Use when an operator or agent needs the in-OS copilot to retrieve repo
documentation (agent docs, user docs, demo runbooks) via RAG — not just the
always-on contract catalog in the system prompt.

## Human guide

[`knowledge.mdx`](../../../apps/web/content/docs/using-the-app/knowledge.mdx) · [`copilot.mdx`](../../../apps/web/content/docs/using-the-app/copilot.mdx) — operator UI + CLI steps

Operator runbook: [`demo-runbook.md`](../../demo-runbook.md) (assistant-knowledge section)

## Flow

1. **Dry-run** ledger state:
   ```bash
   agentskit-os prod seed --target assistant-knowledge --dry-run
   ```
2. **Apply** missing/stale folder registrations:
   ```bash
   agentskit-os prod seed --target assistant-knowledge --apply
   ```
3. **Rebuild** each source (repeat per id):
   ```bash
   agentskit-os knowledge rebuild assistant-knowledge-for-agents
   agentskit-os knowledge rebuild assistant-knowledge-user-docs
   agentskit-os knowledge rebuild assistant-knowledge-demo-docs
   agentskit-os knowledge rebuild assistant-knowledge-runbooks
   ```

## Source ids → paths

| Source id | Folder |
|---|---|
| `assistant-knowledge-for-agents` | `docs/for-agents` |
| `assistant-knowledge-user-docs` | `apps/web/content/docs` |
| `assistant-knowledge-demo-docs` | `docs/demo` |
| `assistant-knowledge-runbooks` | `docs/runbooks` |

## RPC

- `prod.seed.plan` / `prod.seed.apply` / `prod.seed.ledger` — see
  [`contracts/README.md`](../contracts/README.md) (`prod.*` namespace).

## Edge cases

- Fumadocs pages are **not** in copilot RAG until step 3 completes for
  `assistant-knowledge-user-docs`.
- The system prompt always includes the contract catalog (`llms.txt`); seeding
  adds folder RAG on top — it does not replace contract routing.
- Do not use `AKOS_DEMO_PACKS` / `agentskit-os seed` for this path in production;
  use `prod seed --target assistant-knowledge` per demo-runbook.

Source: /raw/for-agents/flows/assistant-knowledge-seed.md

### for-agents/flows/brand-publish.md

# Workflow — Brand publish
## Human guide

[`README.md`](../../../apps/admin/README.md)


Admin whitelabel editor → cloud publish RPC → BrandStore → 4 sinks
(cloud-store / desktop-sync / web-CDN / admin-mirror) → web brand-loader hot-loads within 60 s.
Source: ef-07 SU7.7 PR #3018 + ef-06 SU6.7 (commit 2905c6cba).

## Actors

| Actor | Role |
|---|---|
| OEM admin | Uploads brand assets + saves BrandKit in the admin console |
| `apps/admin` | Validates form, calls `POST /v1/whitelabel/publish` |
| `apps/cloud` | Zod-parses body, RBAC gates (`whitelabel:write`), runs publish pipeline |
| `os-whitelabel` | `createPublishPipeline` — BrandStore write + fan-out to sinks |
| BrandStore | Durable cloud-side store for the active BrandKit per tenant |
| Desktop sync gateway (`sync-gateway-ws.ts`) | Pushes update to connected desktop sidecars via WS topic |
| Web CDN | Serves resolved BrandKit JSON to `apps/web/lib/brand-loader.ts` |
| Admin mirror | Keeps admin console brand preview in sync |

## Sequence

```
OEM admin (admin console)
  │
  ├─► POST /v1/whitelabel/publish
  │     body: { tenantId, publishedBy, kit: BrandKit }
  │     auth: JWT (resolved orgId) + RBAC cap: whitelabel:write
  │
  apps/cloud (whitelabel-routes.ts)
  │
  ├─► Zod parse PublishBodySchema + BrandKit schema (os-whitelabel)
  │     fail → 400 AK_WHITELABEL_INVALID
  │
  ├─► createPublishPipeline(brandStore, sinks)(kit, { tenantId, publishedBy })
  │
  │   os-whitelabel publish pipeline
  │   ├─► BrandStore.save(tenantId, resolvedKit)
  │   │     fail → AK_WHITELABEL_STORE
  │   ├─► [parallel fan-out]
  │   │   ├─► sink[desktop-ws]: broadcast to sync-gateway-ws WS topic → desktop sidecar hot-reloads
  │   │   ├─► sink[cdn]: PUT resolved JSON to CDN edge path for tenantId
  │   │   ├─► sink[admin-mirror]: POST to admin API cache invalidation
  │   │   └─► sink[audit]: audit.append(whitelabel:published, tenantId, publishedBy)
  │   └─► return { ok: true, version }
  │
  ├─► 200 { ok: true, version }
  │
  apps/web (brand-loader.ts) — runs on Next.js edge runtime
  │
  └─► GET /v1/whitelabel/:tenantId (stable URL, SU6.7)
        polls or cache-revalidates ≤ 60 s → hot-loads updated BrandKit CSS tokens
```

## Step table

| Step | Actor | RPC / Action | On success | On error |
|---|---|---|---|---|
| Auth resolve | cloud middleware | JWT + RBAC cap `whitelabel:write` | continue | 401 `AK_AUTH_FAILED` |
| Body parse | cloud | Zod `PublishBodySchema` | continue | 400 `AK_WHITELABEL_INVALID` |
| BrandKit validate | os-whitelabel | `BrandKit` Zod schema | continue | 400 `AK_WHITELABEL_INVALID` |
| BrandStore save | os-whitelabel | `BrandStore.save()` | version incremented | 500 `AK_WHITELABEL_STORE` |
| Desktop sink | sync-gateway-ws | WS topic broadcast | sidecar reloads ≤ 5 min | logged, non-fatal |
| CDN sink | cloud | edge PUT | CDN serves new kit | logged, non-fatal |
| Admin mirror sink | apps/admin | cache invalidation | preview refreshed | logged, non-fatal |
| Audit | os-audit | `audit.append` | row persisted | logged, non-fatal |
| Web hot-load | apps/web brand-loader | `GET /v1/whitelabel/:tenantId` | CSS tokens refreshed ≤ 60 s | stale cached kit served |

## Touched packages / apps

- `apps/admin` — BrandKit editor UI
- `apps/cloud/src/api/whitelabel-routes.ts` — route handler
- `packages/os-whitelabel` — `createPublishPipeline`, `BrandStore`, `BrandSink`, `BrandKit` schema
- `apps/cloud/src/api/sync-gateway-ws.ts` — desktop WS topic
- `apps/web/lib/brand-loader.ts` — edge-side GET consumer

## Audit events emitted

- `whitelabel:published` — `{ tenantId, publishedBy, version, sinkResults }`

## Observability hooks

| Span | Key attributes |
|---|---|
| `whitelabel.publish` | `tenant_id`, `published_by`, `kit_version` |
| `whitelabel.sink.desktop_ws` | `connected_clients`, `broadcast_ms` |
| `whitelabel.sink.cdn` | `cdn_path`, `status_code` |
| `whitelabel.brand_load` | `tenant_id`, `cache_status`, `latency_ms` |

## Failure modes and compensations

| Failure | Code | Compensation |
|---|---|---|
| BrandKit schema invalid | `AK_WHITELABEL_INVALID` | Correct the kit fields; no partial write |
| BrandStore unavailable | `AK_WHITELABEL_STORE` | Retry POST; store write is idempotent per version |
| Sink failure (any) | — | Logged + skipped; sinks are best-effort; re-POST re-fans |
| Desktop WS drop | — | Desktop polls `GET /v1/whitelabel/:tenantId` on reconnect |
| Web hot-load lag | — | CDN TTL ≤ 60 s; brand-loader uses `next/cache` revalidation |

## Related ADRs / RFCs / PRs

- ADR-0098 — Whitelabel propagation
- ef-07 SU7.7 PR #3018 — cloud `POST /v1/whitelabel/publish` route
- ef-06 SU6.7 (2905c6cba) — `apps/web` brand-loader hot-load
- [`docs/enterprise-final/rebrand-bundle.md`](../../enterprise-final/rebrand-bundle.md) — rebranded installer pipeline (uses same BrandKit endpoint)
- [`docs/for-agents/packages/os-whitelabel.md`](../packages/os-whitelabel.md) — brand kit internals

Source: /raw/for-agents/flows/brand-publish.md

### for-agents/flows/control-plane-resolve.md

# Workflow — Control plane context resolution
## Human guide

[`architecture-overview.md`](../../enterprise-final/architecture-overview.md)


Every surface (web, desktop, CLI, admin, sidecar, service) resolves a single canonical `ControlPlaneContext` before any mutating action. The resolver reconciles identity + membership + tenant + license + entitlement + RBAC + distribution into one object, server-authoritative on `orgId`. Status: **shipped for the pure resolver + token/audit primitives** (RFC-0054 F1-F6; package `os-control-plane`); host integrations may still be incomplete per surface. Source of truth for the contract: RFC-0054 + ADR-0157; full spec in `ops/akos-x-growth/AKOS-UNIFIED-CONTROL-PLANE.md`.

## Ownership rules

| Concern | Owner | Rule |
|---|---|---|
| Identity context shape | `@agentskit/os-core/auth/identity-context` | Pure contract only; no IO, no membership lookup, no token minting. |
| Tenant host constants and slug schema | `@agentskit/os-core/schema/tenancy` | Canonical root domain, reserved labels, and DNS-safe slug validation. Apps must not duplicate these lists. |
| Control-plane policy resolution | `@agentskit/os-control-plane` | Pure resolver and policy engine over injected sources; owns capability closure, entitlement reconciliation, distribution policy, context tokens, and audit-chain primitives. |
| Online identity/membership/tenant source of truth | `apps/cloud` | Server-authoritative session, membership, tenant status, SSO/SCIM, and entitlement data. Request/body `orgId` is only a hint. |
| Runtime enforcement | `os-headless` + `os-security` + sidecar bindings | Verify signed context/JWT, enforce caps/plan/audience before mutating work. Never infer access from UI state. |
| UI surfaces | `apps/web`, `apps/console`, `apps/desktop`, `apps/admin` | Display context and request actions. They may select a tenant hint, but they never grant membership or capabilities. |

## Actors

| Actor | Role |
|---|---|
| Surface (web/desktop/CLI/admin/sidecar) | Requests a context; never trusts its own `orgId` for mutation |
| `os-control-plane` resolver | Builds `ControlPlaneContext` from all domains; mints short-TTL signed token |
| `apps/cloud` | Authoritative identity/membership/tenant/entitlement; SECURITY DEFINER membership lookup (ADR-0153) |
| `os-license` | Verifies envelope, computes license state + offline grace (ADR-0047, ADR-0159) |
| `apps/license-service` | License issue/renew/revoke + revocation snapshot |
| sync-gateway | Pushes critical invalidation (suspend/revoke) to connected surfaces (ADR-0161) |

## Sequence

```
Surface (mutating request)
  │
  ├─► os-control-plane.resolve(identity hint, requested orgId?)
  │
  ├─► IDENTITY     → cloud session / device pairing / license / service token
  │                  (kind: user | service | device | anonymous-local)
  ├─► MEMBERSHIP   → cloud akos_orgs_for_email (ADR-0153); body orgId is OVERWRITTEN server-side
  ├─► TENANT       → cloud orgs (SoT); status active | suspended | retention
  ├─► LICENSE      → os-license verify envelope (signingKeyId → embedded key set, ADR-0160)
  │                  state valid | in-grace | expired | over-seats | revoked
  │                  effective time = max(systemClock, highWatermark) (ADR-0159)
  ├─► ENTITLEMENT  → EffectiveEntitlement resolver (ADR-0158): cloud authoritative,
  │                  sidecar derives offline from cache; precedence ladder applied
  ├─► RBAC         → capability registry (ADR-0006); role → caps; unknown cap rejects
  ├─► DISTRIBUTION → channel = tenant+target; mode governs login/cloud/offline
  │
  ├─► POLICY derive: loginRequired / cloudRequired / offlineAllowed / tenantSuspended / readonlyMode
  │
  └─► emit ControlPlaneContext { schemaVersion, resolvedAt, expiresAt (60–120s TTL), ... }
        │
        ├─► token cached by surface until expiresAt → re-resolve
        └─► critical event (suspend/revoke) pushed via sync-gateway → invalidate now (ADR-0161)
```

## Step table

| Step | Actor | Action | On success | On error |
|---|---|---|---|---|
| identity | resolver | verify session/device/license/service token | identity kind set | `AK_AUTH_FAILED` / fail-closed |
| membership | cloud | `akos_orgs_for_email` (SECURITY DEFINER) | effective orgId set server-side | `AK_TENANT_MISMATCH` (body spoof → 403/overwrite) |
| tenant | cloud | read orgs SoT | status resolved | suspended → `AK_FORBIDDEN` |
| license | os-license | verify envelope + state | state + distributionMode | unknown `signingKeyId` → `invalid`; revoked → block |
| entitlement | resolver | EffectiveEntitlement reconcile | caps/quotas/seats | unknown plan → free; over-seat → block mutation |
| rbac | resolver | resolve caps | capability set | unknown cap → reject |
| emit | resolver | mint signed context token | context returned | — |

## Touched packages / apps

- `packages/os-control-plane` (new) — the resolver + token mint/verify
- `packages/os-contracts` — `ControlPlaneContext` schema + `control.*` methods (ADR-0027)
- `apps/cloud` — authoritative identity/membership/tenant/entitlement; sync-gateway push
- `packages/os-license` — envelope verify, state, offline grace, trusted time
- `apps/license-service` — revocation snapshot

## Audit events emitted

- `auth.login` / `auth.denied` — `{ requestId, actorId, actorKind, orgId, method, decision, reason }`
- `crossTenant.access` — `{ actorId, orgId, targetOrgId, capability, reason }`
- `tenant.suspended` / `license.revoked` — propagated to context invalidation

## Failure modes

| Failure | Code | Behavior |
|---|---|---|
| Body `orgId` ≠ membership | `AK_TENANT_MISMATCH` | 403 or server overwrite to the real org before handler |
| Tenant suspended | `AK_FORBIDDEN` | Block mutation + audit; readonly per policy |
| License revoked | `AK_LICENSE_REVOKED` | Block; fail-closed |
| Clock rolled back past watermark | (ADR-0159) | Fail-closed; re-anchor on reconnect |
| Unknown signingKeyId | `invalid` | Reject envelope |
| Over-seat | (ADR-0158) | Block new mutating session/run, not login |

## Related ADRs / RFCs

- RFC-0054 — Unified Control Plane (umbrella)
- ADR-0157 — ControlPlaneContext contract + package
- ADR-0158 — EffectiveEntitlement resolver
- ADR-0159 — Trusted time anchoring
- ADR-0160 — License signing-key rotation
- ADR-0161 — Context invalidation
- ADR-0153 — cross-tenant membership lookup
- [`docs/for-agents/packages/os-control-plane.md`](../packages/os-control-plane.md)
- [`docs/for-agents/contracts/control-plane-rpcs.md`](../contracts/control-plane-rpcs.md)

Source: /raw/for-agents/flows/control-plane-resolve.md

### for-agents/flows/customer-onboarding.md

# Workflow — Customer onboarding (end-to-end)
## Human guide

[`customer-onboarding-walkthrough.md`](../../enterprise-final/customer-onboarding-walkthrough.md)


Marketing CTA → Stripe checkout → license-service provisioning saga → admin auto-onboards
tenant → SSO/SCIM provisioned → web sign-in → desktop pairing → first flow → first run →
audit trail established. Cross-app E2E. Source: ef-08 SU8.7 PR #3094;
runbook at [`customer-onboarding-walkthrough.md`](../../enterprise-final/customer-onboarding-walkthrough.md).

## Actors

| Actor | Role |
|---|---|
| End customer | Clicks CTA, completes checkout, signs in, runs first flow |
| Customer IT admin | Configures DNS, IdP, brand kit |
| Operator | Pre-provisions infra; provides load-balancer address + plan config |
| Stripe | Fires checkout webhook → license provisioning |
| `apps/license-service` | Provisioning saga (tenant + license + entitlement) |
| `apps/cloud` | Control plane: auth, SCIM, entitlement receiver, sync gateway |
| `apps/admin` | OEM admin console: brand kit, seat allocation |
| `apps/web` | Marketing site + post-login web app |
| `apps/desktop` | Desktop app: sidecar pairing, first flow run |

## Sequence

```
Operator (pre-flight)
  │
  ├─► Deploy control plane; confirm: /health → {"status":"ok","db":"connected","vault":"reachable"}
  ├─► Configure Stripe plan (license-service /licenses/plans)
  └─► Share: load-balancer address + onboarding doc with customer
  │
Customer IT admin
  │
  ├─► STEP 1 — DNS
  │   ├─► CNAME app.<brand>   → load-balancer
  │   ├─► CNAME admin.<brand> → load-balancer
  │   └─► verify: curl https://app.<brand>/api/health → {"status":"ok"}
  │
  ├─► STEP 2 — IdP (SAML 2.0 or OIDC + optional SCIM)
  │   ├─► configure SP entity ID, ACS URL in IdP
  │   ├─► (SCIM) connect SCIM v2 to https://app.<brand>/api/scim/v2
  │   └─► test sign-in with pilot user
  │
Customer (marketing site)
  │
  ├─► STEP 3 — Stripe checkout
  │   ├─► CTA on apps/web → Stripe Checkout
  │   └─► checkout.session.completed webhook → license-service
  │
  apps/license-service (provisioning saga — see license-lifecycle.md)
  │
  ├─► STEP 4 — Auto-provisioning
  │   ├─► createTenant → cloud POST /v1/tenants  (orgId, planId, seats)
  │   ├─► issueLicense → Ed25519-signed envelope
  │   └─► notifyEntitlement → cloud PUT /v1/entitlements/:orgId
  │
  apps/admin (OEM admin)
  │
  ├─► STEP 5 — Brand kit + seat allocation
  │   ├─► upload logo (light/dark/favicon) + set colors + product name
  │   ├─► POST /v1/whitelabel/publish → brand-publish pipeline (see brand-publish.md)
  │   └─► assign roles to pilot users (viewer/operator/developer/admin)
  │
  Customer (apps/web sign-in)
  │
  ├─► STEP 6 — First sign-in
  │   ├─► https://app.<brand>/sign-in → SSO redirect (SAML/OIDC)
  │   ├─► IdP asserts → cloud auth.ts validates → JWT issued (RFC-0038)
  │   └─► web app loads with branded UI (brand-loader hot-load ≤ 60 s)
  │
  ├─► STEP 7 — Desktop pairing (optional)
  │   ├─► Download branded desktop installer (.dmg/.exe/.AppImage)
  │   ├─► apps/desktop first-run wizard → sidecar starts
  │   ├─► sidecar pairs with cloud (sync-gateway WS + sidecar JWT token)
  │   └─► license verified (verifyLicenseEnvelope + assertNotRevoked)
  │
  ├─► STEP 8 — First flow
  │   ├─► operator opens flow editor → creates or imports a flow
  │   └─► (optional) apply a demo pack: agentskit-os seed --vertical <name>
  │
  └─► STEP 9 — First run + audit
      ├─► runs.create → runner.runFlow
      ├─► sandbox caps resolved (assertDedicatedSandboxCap)
      ├─► run executes → run record written
      ├─► audit.append(run:started), audit.append(run:completed)
      └─► admin console → Compliance → Audit Log confirms trail
```

## Step table

| Step | Actor | Action / RPC | On success | On error |
|---|---|---|---|---|
| DNS CNAME | customer IT | DNS provider | health 200 | propagation delay (wait ≤ 30 min) |
| IdP config | customer IT + operator | SAML/OIDC app setup | test SSO succeeds | see `troubleshooting.md §IdP` |
| Stripe checkout | customer | Stripe Checkout | webhook fired | Stripe retry |
| createTenant | license-service | `POST /v1/tenants` | tenant record | `AK_PROVISIONING_TENANT_FAILED` → compensate |
| issueLicense | license-service | `signLicenseEnvelope` | signed envelope | `AK_PROVISIONING_LICENSE_FAILED` → compensate |
| notifyEntitlement | license-service | `PUT /v1/entitlements/:orgId` | caps honored | `AK_PROVISIONING_NOTIFY_FAILED` → compensate |
| Brand publish | apps/admin → cloud | `POST /v1/whitelabel/publish` | BrandKit live ≤ 60 s | `AK_WHITELABEL_INVALID` |
| SSO sign-in | apps/web + cloud | JWT issuance (RFC-0038) | session active | SAML assertion error → IdP config review |
| SCIM provision | IdP + cloud | SCIM v2 Create/Update | user in seat list | SCIM token invalid |
| Desktop pair | apps/desktop | sidecar JWT + WS sync | sidecar connected | `AK_AUTH_FAILED` → re-authenticate |
| First run | runner + sandbox | `runs.create` + `runner.runFlow` | run record created | caps / firewall errors |
| Audit verify | apps/admin | Compliance → Audit Log | entries visible | — |

## Touched apps / packages

- `apps/web` — marketing CTA, Stripe checkout entry, post-login app, brand-loader
- `apps/license-service` — provisioning saga
- `apps/cloud` — tenant routes, entitlement, auth (SAML/OIDC/SCIM), sync-gateway, whitelabel routes
- `apps/admin` — brand kit editor, seat allocation
- `apps/desktop` — sidecar pairing, flow editor, first run
- `packages/os-license` — envelope sign/verify, caps matrix
- `packages/os-whitelabel` — publish pipeline
- `packages/os-sandbox-vercel` — caps gate + warm pool

## Audit events emitted

- `tenant:created`, `license:provisioned` (provisioning saga)
- `whitelabel:published` (brand publish)
- `auth:sso_login` — `{ orgId, userId, provider }`
- `scim:user_provisioned` — `{ orgId, userId, role }`
- `desktop:paired` — `{ orgId, deviceId }`
- `run:started`, `run:completed` — `{ orgId, runId, flowId }`

## Observability hooks

| Span | Key attributes |
|---|---|
| `license.provisioning_saga` | `stripe_event_id`, `org_id`, `plan_id` |
| `cloud.auth.sso` | `provider`, `org_id`, `latency_ms` |
| `cloud.scim.provision` | `org_id`, `action` |
| `desktop.pair` | `org_id`, `device_id` |
| `sandbox.run` | `run_id`, `org_id`, `cpu_minutes` |

## Failure modes and compensations

| Failure | Compensation |
|---|---|
| DNS not propagated | Wait ≤ 30 min; verify with `dig`; see `troubleshooting.md §DNS` |
| Provisioning saga fails | Reverse compensations; re-delivery retries via Stripe webhook |
| SSO assertion error | Review IdP attribute mappings; see `troubleshooting.md §IdP` |
| Desktop pairing fails | Re-authenticate; confirm `AKOS_CLOUD_URL` in sidecar config |
| Caps block on first run | Verify plan entitlement in admin console; check `AK_PLAN_CAP_EXCEEDED` |

## Related ADRs / RFCs / PRs

- ADR-0097 — Pod-per-org tenants
- ADR-0098 — Whitelabel propagation
- RFC-0038 — Sidecar HTTP transport (JWT auth)
- ef-08 SU8.7 PR #3094 — E2E onboarding integration test
- [`docs/enterprise-final/customer-onboarding-walkthrough.md`](../../enterprise-final/customer-onboarding-walkthrough.md) — step-by-step operator runbook
- [`docs/enterprise-final/customer-onboarding.md`](../../enterprise-final/customer-onboarding.md) — customer-side reference
- [license-lifecycle](./license-lifecycle.md) — provisioning + renewal detail
- [brand-publish](./brand-publish.md) — brand publish pipeline detail
- [hosted-sandbox-run](./hosted-sandbox-run.md) — first run sandbox detail

Source: /raw/for-agents/flows/customer-onboarding.md

### for-agents/flows/dr-rehearsal.md

# Workflow — DR rehearsal (quarterly)
## Human guide

[`runbook-dr.md`](../../enterprise-final/runbook-dr.md)


Quarterly disaster-recovery drill: primary-DB failover → region failover → S3 restore →
Vault Transit rotation. Validates RPO ≤ 1 min / RTO < 1 h per ADR targets.
Source: PR #3113 ef-SU4.9 / FF.4; runbook at [`runbook-dr.md`](../../enterprise-final/runbook-dr.md).

## Actors

| Actor | Role |
|---|---|
| On-call engineer | Executes scenarios, records metrics, signs off |
| Platform lead | Reviews report and countersigns |
| `deploy/dr/scripts/` | Pre-flight check + smoke test scripts |
| AWS RDS / Route 53 | Failover targets for S1 / S2 |
| S3 versioned bucket | Restore source for S3 |
| HashiCorp Vault | Transit key rotation for S4 |
| `apps/cloud` health endpoint | Liveness probe post-recovery |

## Sequence

```
On-call engineer
  │
  ├─► Pre-flight: bash deploy/dr/scripts/dr-rehearsal-check.sh
  │     5 checks must be GREEN before proceeding
  │     outputs pasted into dr-rehearsal-YYYY-MM-DD.md
  │
  ├─► SCENARIO S1 — Primary DB failover (Multi-AZ promotion)
  │   │  Target: RPO ≤ 1 min, RTO < 1 h
  │   ├─► T0: aws rds reboot-db-instance --force-failover
  │   ├─► poll: aws rds describe-db-instances → status = available
  │   ├─► probe: curl https://api.staging.<brand>/health → {"status":"ok","db":"connected"}
  │   ├─► smoke: RESTORE_DB_HOST=<endpoint> bash deploy/dr/scripts/verify-restore.sh
  │   └─► row-count check: runs, audit_entries, orgs (delta = 0 expected)
  │
  ├─► SCENARIO S2 — Region failover (DNS cut-over)
  │   │  Target: RPO ≤ 1 min, RTO < 1 h  |  NOTE: MOCK if EU region not provisioned
  │   ├─► disable us-east-1 Route53 health-check responder
  │   ├─► confirm RegionRouter emits RegionFailoverEvent
  │   ├─► verify EU endpoint /health within RTO
  │   ├─► manual failback: forceRegion('us-east-1')
  │   └─► confirm no split-brain (replicas consistent)
  │
  ├─► SCENARIO S3 — S3 restore from versioned snapshot
  │   │  Target: RPO = 0 (versioning), RTO < 15 min
  │   ├─► T0: aws s3 rm <test object>  (simulate deletion)
  │   ├─► aws s3api list-object-versions → pick VersionId
  │   ├─► aws s3api get-object --version-id → /tmp/recovered.json
  │   ├─► aws s3 cp recovered.json → restore
  │   └─► T1: RTO = T1 - T0 (target < 15 min)
  │
  ├─► SCENARIO S4 — Vault Transit key rotation
  │   │  Target: RPO = 0, RTO < 1 h
  │   ├─► vault read transit/keys/agentskit-prod-key  (confirm state)
  │   ├─► T0: vault write -f transit/keys/agentskit-prod-key/rotate
  │   ├─► kubectl rollout restart deployment -l app.kubernetes.io/component=sidecar
  │   ├─► kubectl rollout status --timeout=600s
  │   ├─► vault write transit/decrypt/agentskit-prod-key ciphertext=<sample>
  │   │     verifies old ciphertext still decryptable (key versioning)
  │   ├─► bash deploy/dr/scripts/backup-vault.sh  → snapshot to S3 DR bucket
  │   └─► T1: RTO = T1 - T0
  │
  └─► Sign-off: on-call engineer + platform lead; record next rehearsal date (+3 months)
```

## Step table

| Step | Actor | Action | On success | On error |
|---|---|---|---|---|
| Pre-flight | engineer | `dr-rehearsal-check.sh` | 5/5 GREEN | Stop; fix gate before proceeding |
| S1 failover | AWS RDS | `reboot-db-instance --force-failover` | DB `available`; health 200 | Record FAIL; escalate |
| S1 verify | engineer | `verify-restore.sh` exit 0 | Row counts match | Record FAIL; escalate |
| S2 failover | Route53 / RegionRouter | health-check disable → failover event | EU endpoint serves health | Record MOCK if EU absent |
| S3 restore | S3 versioned | get-object by VersionId + re-upload | Object restored; RTO < 15 min | Record FAIL |
| S4 rotation | Vault Transit | `rotate` + sidecar rollout | All pods Running; old ciphertext decryptable | Record FAIL |
| S4 snapshot | engineer | `backup-vault.sh` | Snapshot in S3 DR bucket | Record FAIL |
| Sign-off | on-call + platform lead | commit filled report | Next date set | Rehearsal incomplete |

## Touched components

- `deploy/dr/scripts/` — `dr-rehearsal-check.sh`, `verify-restore.sh`, `backup-vault.sh`
- `apps/cloud` — health endpoint `/health` (`db`, `vault` sub-checks)
- AWS RDS Multi-AZ — S1 failover target
- AWS Route 53 + RegionRouter — S2 failover
- S3 versioned bucket (`akos-staging`) — S3 restore
- HashiCorp Vault Transit — S4 key rotation
- Kubernetes `agentskit-ops` namespace — sidecar rollout

## Audit events emitted

DR rehearsals do not emit runtime audit events. The rehearsal report
(`dr-rehearsal-YYYY-MM-DD.md`) is the audit artifact; it is committed to the repo
and constitutes the compliance record for the quarter.

## Observability hooks

| Signal | Where |
|---|---|
| DB failover event | AWS CloudWatch `RDSForcedFailover` alarm |
| Health endpoint latency | OTel span `cloud.health` → `db_check_ms`, `vault_check_ms` |
| Sidecar rollout | Kubernetes rollout events + pod restart count metric |
| Vault audit log | Vault audit backend → S3 (`vault-audit/`) |

## Failure modes and compensations

| Failure | Compensation |
|---|---|
| Pre-flight gate red | Resolve before starting; never skip |
| S1 RTO exceeded | Investigate DB instance class / Multi-AZ config; raise P1 |
| S2 region not provisioned | Mark MOCK; track EU region provisioning as follow-up |
| S3 RTO exceeded (> 15 min) | Review bucket versioning config + script efficiency |
| S4 old ciphertext fails to decrypt | Vault key min-decryption-version misconfigured; raise P0 |
| Snapshot upload fails | Investigate bucket policy + IAM role; re-run `backup-vault.sh` |

## Related ADRs / RFCs / PRs

- PR #3113 — ef-SU4.9 / FF.4 DR rehearsal template
- [`docs/enterprise-final/dr-rehearsal-template.md`](../../enterprise-final/dr-rehearsal-template.md) — fillable quarterly template
- [`docs/enterprise-final/runbook-dr.md`](../../enterprise-final/runbook-dr.md) — full runbook
- [`docs/for-agents/backup-dr.md`](../backup-dr.md) — backup + restore reference (ENT-5)
- [`docs/enterprise-final/chaos-rpo-rto.md`](../../enterprise-final/chaos-rpo-rto.md) — RPO/RTO targets

Source: /raw/for-agents/flows/dr-rehearsal.md

### for-agents/flows/eval-suite.md

# Workflow — Eval suite
## Human guide

[`evals.mdx`](../../../apps/web/content/docs/using-the-app/evals.mdx) · [`flows.mdx`](../../../apps/web/content/docs/using-the-app/flows.mdx) · [`governance.mdx`](../../../apps/web/content/docs/using-the-app/governance.mdx)


End-to-end evaluation of an agent or flow against a frozen case set. Used to gate agent-version promotions and to detect regressions when swapping a provider/model.

## Lifecycle

```
suite authored          → evals.suites.upsert
suite dispatched        → evals.run                       (returns EvalResultRow)
results listed          → evals.results.list
case-level drill-down   → evals.results.get
failed case replayed    → traces.replay (target model+version)
diff vs baseline        → agents.versions.diff
```

## Methods consumed

```
evals.suites.list / get / upsert / delete   suite CRUD
evals.run                                   dispatch + persisted result row
evals.results.list / get                    stream + drill-down
traces.replay                               replay failed cases
agents.versions.list / diff                 pick targets
```

## Failure modes

- **Schema drift** — `evals.suites.upsert` validates cases against the agent's current input schema; mismatch → Zod issue list.
- **Empty suite** — `evals.run` rejects with `no-cases`.
- **Budget cap** — eval runs are metered the same as production; `BudgetBlockedError` halts the run and emits a HITL.
- **Model unavailable** — replay against a deleted model returns `model-not-found` per case; the surrounding suite still completes.

## Cross-references

- [`docs/for-agents/screens/evals.md`](../screens/evals.md) — desktop evals screen + entry points.
- [`docs/for-agents/packages/os-runtime.md`](../packages/os-runtime.md) — cost metering for eval runs.

Source: /raw/for-agents/flows/eval-suite.md

### for-agents/flows/hosted-sandbox-run.md

# Workflow — Hosted sandbox run
## Human guide

[`run-lifecycle.mdx`](../../../apps/web/content/docs/how-it-works/run-lifecycle.mdx)


Flow run request → plan caps resolved → warm-pool acquire (<2 s P95) → Vercel sandbox
provisioned → egress policy enforced → run executes → meter ticks CPU/RAM → telemetry
emitted → meter record ingested at cloud. Source: ef-03 SU3.2 PR #3070, SU3.3 PR #3067,
SU3.4 PR #3093, SU3.5 (ff33e2f05), SU3.6 (4b57ecfe5).

## Actors

| Actor | Role |
|---|---|
| Operator / trigger | Initiates a flow run |
| `os-sandbox-vercel` | Caps gate, warm-pool, metering |
| `apps/cloud` | Caps resolution, egress policy, telemetry ingest, metering ingest |
| `apps/license-service` | Source of plan entitlement (caps matrix) |
| Vercel Sandbox | Executes the flow in a Firecracker µVM |
| `os-security` | Egress allowlist enforcement |

## Sequence

```
Operator / trigger
  │
  ├─► runner.runFlow(flowId, { orgId, runId, … })
  │
  os-sandbox-vercel
  │
  ├─► CAPS RESOLVE  (SU3.2)
  │   ├─► resolvePlanCaps(tenant.plan, tenant.capOverrides)
  │   │     → PlanCapsMatrix { dedicatedSandbox, cpuSeconds, ramMb, wallTimeSec, … }
  │   └─► assertDedicatedSandboxCap(caps)
  │         fail → AK_PLAN_CAP_EXCEEDED (403 to caller)
  │
  ├─► WARM-POOL ACQUIRE  (SU3.4)
  │   ├─► warmPool.acquire(plan)
  │   │   ├─► hit: pop pre-warmed idle slot (P95 < 2 s)
  │   │   │   emit: pool:acquire
  │   │   └─► miss: provision new instance on-demand (cold path)
  │   │       emit: pool:miss
  │   └─► SandboxHandle returned
  │
  ├─► EGRESS POLICY  (SU3.3)
  │   ├─► firewall.evaluate(run, { orgId }) → allow | block | audit
  │   └─► block → run cancelled; AK_FIREWALL_BLOCKED emitted; pool.release(handle)
  │
  ├─► RUN EXECUTION
  │   ├─► RunMeter.start() → samples cpuMinutes, ramMinutes at interval
  │   ├─► HostedSandboxProvider.spawn(handle, opts)  → Vercel Sandbox Firecracker µVM
  │   ├─► flow steps execute inside sandbox
  │   └─► RunMeter.stop()  (SU3.5 ff33e2f05)
  │         emit: MeterLimitEvent if cpuSeconds | ramMb | wallTimeSec caps exceeded
  │               → sandbox destroyed; AK_METER_LIMIT emitted
  │
  ├─► TELEMETRY  (SU3.6 4b57ecfe5)
  │   ├─► OTel spans flushed → telemetry-routes.ts POST /v1/telemetry
  │   └─► cloud stores spans + emits run:telemetry_ingested
  │
  └─► METER INGEST  (SU3.5 / cloud metering-routes.ts)
      ├─► POST /v1/metering/runs  body: RunMeter JSON
      │     auth: sidecar JWT (org_id claim)
      │     Zod: IngestBodySchema { orgId, runId, cpuMinutes, ramMinutes, egressBytes?, startedAt, endedAt }
      ├─► metering-store persists month-keyed record (toMeteringMonthKey)
      └─► usage_events receives idempotent data/egress_bytes when egressBytes > 0
```

## Step table

| Step | Actor | RPC / Action | On success | On error |
|---|---|---|---|---|
| Caps resolve | os-sandbox-vercel | `resolvePlanCaps` + `assertDedicatedSandboxCap` | caps object | `AK_PLAN_CAP_EXCEEDED` → 403 |
| Warm-pool acquire | os-sandbox-vercel | `warmPool.acquire(plan)` | SandboxHandle (<2 s P95) | pool:miss → cold provision |
| Egress evaluate | os-security + cloud | `firewall.evaluate` | allow | `AK_FIREWALL_BLOCKED` → cancel + release |
| Sandbox spawn | os-sandbox-vercel | `HostedSandboxProvider.spawn(handle, opts)` | µVM running | `AK_SANDBOX_SPAWN_FAILED` → release |
| Meter start | os-sandbox-vercel | `RunMeter.start()` | sampling active | — |
| Run execute | Vercel Sandbox | flow steps run | run completes | step errors surface via runner.getState |
| Meter stop | os-sandbox-vercel | `RunMeter.stop()` | MeterRecord produced | — |
| Cap limit hit | os-sandbox-vercel | `MeterLimitEvent` | sandbox destroyed | run halted; HITL if configured |
| Telemetry ingest | cloud | `POST /v1/telemetry` | spans stored | non-fatal; retried by OTel SDK |
| Meter ingest | cloud | `POST /v1/metering/runs` | monthly record persisted | `AK_METER_RECORD_INVALID` or `AK_METER_STORE_UNAVAILABLE` |
| Pool release | os-sandbox-vercel | `warmPool.release(handle)` | slot returned or destroyed | logged |

## Touched packages / apps

- `packages/os-sandbox-vercel` — `WarmPool`, `RunMeter`, `assertDedicatedSandboxCap`, `resolvePlanCaps`
- `apps/cloud/src/api/metering-routes.ts` — meter ingest + monthly query
- `apps/cloud/src/api/telemetry-routes.ts` — OTel span ingest
- `packages/os-security` — `firewall.evaluate` egress enforcement
- `packages/os-license` — `resolvePlanCaps`, `PLAN_CAPS_MATRIX`

## Audit events emitted

- `sandbox:acquired` — `{ orgId, runId, plan, hitPool: boolean, coldStartMs }`
- `sandbox:egress_blocked` — `{ orgId, runId, firewallVerdict }`
- `sandbox:cap_limit` — `{ orgId, runId, capKey, measured, limit }`
- `sandbox:run_complete` — `{ orgId, runId, cpuMinutes, ramMinutes, wallTimeSec }`

## Observability hooks

| Span | Key attributes |
|---|---|
| `sandbox.caps_resolve` | `org_id`, `plan`, `dedicated_sandbox` |
| `sandbox.pool_acquire` | `plan`, `pool_hit`, `acquire_ms` |
| `sandbox.spawn` | `provider`, `run_id`, `cold_start_ms` |
| `sandbox.run` | `run_id`, `cpu_minutes`, `ram_minutes`, `wall_time_sec` |
| `cloud.metering_ingest` | `org_id`, `run_id`, `month` |
| `cloud.telemetry_ingest` | `span_count`, `org_id` |

## Failure modes and compensations

| Failure | Code | Compensation |
|---|---|---|
| Caps not entitled | `AK_PLAN_CAP_EXCEEDED` | Upgrade plan via admin console |
| Egress blocked | `AK_FIREWALL_BLOCKED` | Adjust egress allowlist or flow config |
| Sandbox spawn failed | `AK_SANDBOX_SPAWN_FAILED` | Pool releases slot; run retried by runner |
| Resource cap exceeded | `AK_METER_LIMIT` | Sandbox destroyed; run halted; operator notified |
| Meter ingest failed | `AK_METER_STORE_UNAVAILABLE` | Sidecar retries POST; record not lost |
| Pool miss (cold start) | `pool:miss` event | Provision happens on-demand; pool refills in background |

## Related ADRs / RFCs / PRs

- ADR-0095 — Hosted sandbox Vercel
- ef-03 SU3.2 PR #3070 — caps resolution
- ef-03 SU3.3 PR #3067 — egress policy
- ef-03 SU3.4 PR #3093 — WarmPool
- ef-03 SU3.5 (ff33e2f05) — RunMeter + MeterRecord
- ef-03 SU3.6 (4b57ecfe5) — telemetry ingest
- [`docs/for-agents/packages/os-sandbox.md`](../packages/os-sandbox.md) — sandbox spawner primitives

Source: /raw/for-agents/flows/hosted-sandbox-run.md

### for-agents/flows/install-marketplace-plugin.md

# Workflow — Install marketplace plugin
## Human guide

[`templates-and-marketplace.mdx`](../../../apps/web/content/docs/using-the-app/templates-and-marketplace.mdx) · [`flows.mdx`](../../../apps/web/content/docs/using-the-app/flows.mdx) · [`connections.mdx`](../../../apps/web/content/docs/using-the-app/connections.mdx)


Discovery → preflight → install → permissions → audit. The single happy path for adding a third-party plugin or vertical pack to a workspace.

## Lifecycle

```
browse                      → marketplace.listings / featured / suggestions
detail                      → marketplace.listing.get
preflight (sig + license)   → marketplace.evaluateInstall
trust pinning (first run)   → marketplace.publisherKeys.pin
install                     → marketplace.install
verify install              → marketplace.installed.list
(optional) pack apply       → marketplace.applyPack
(optional) abuse report     → marketplace.report
```

Every step writes an audit row (`audit.append`) tagged with the listing id + publisher key fingerprint.

## Methods consumed

```
marketplace.listings | featured | suggestions | stats
marketplace.listing.get
marketplace.evaluateInstall              preflight gate
marketplace.install | uninstall
marketplace.installed.list
marketplace.publisherKeys.list | pin | revoke
marketplace.applyPack | domainPacks
marketplace.privateLibrary.list | add | remove
marketplace.report
```

## Failure modes

- **Untrusted publisher** — `marketplace.install` returns `untrusted-publisher`; UI routes to a key-review modal.
- **Signature invalid** — hard fail (`signature-invalid`); never overrideable.
- **License gate** — `evaluateInstall` returns `license-required`; install blocked until license envelope verifies.
- **Permissions denial** — listing requests caps the current tenant policy forbids; install rejected with `caps-denied` listing the offending capability.

## Cross-references

- [`docs/for-agents/screens/marketplace.md`](../screens/marketplace.md)
- [`docs/for-agents/packages/os-marketplace.md`](../packages/os-marketplace.md)
- [`docs/for-agents/packages/os-security.md`](../packages/os-security.md) — signature verification.

Source: /raw/for-agents/flows/install-marketplace-plugin.md

### for-agents/flows/integration-setup-assistant.md

# Integration Setup Assistant

## Human guide

[`integration-setup.mdx`](../../../apps/web/content/docs/using-the-app/integration-setup.mdx) · [`connections.mdx`](../../../apps/web/content/docs/using-the-app/connections.mdx) · [`copilot.mdx`](../../../apps/web/content/docs/using-the-app/copilot.mdx)

Use this recipe whenever the user asks how to connect Slack, Discord, GitHub,
Linear, Resend, an LLM provider, or any other external service.

## Flow

1. Resolve the provider from the user's language, but do not infer the setup
   mode from env names or connector folklore.
2. Call `integrations.connections.setupRegistry.list` through the
   `connection.listSetupRegistry` action. Pass `providerId` when known and
   `implementedOnly: true` for product UI guidance.
3. Prefer the provider's `preferredSetupMode`:
   - `oauth`: guide the user to the Connect button and consent screen.
   - `installation`: guide the user to the app/bot install flow.
   - `guided_secret`: link to the credential page and ask only for the
     minimum scoped credential described by the registry.
   - `platform_managed`: explain what the platform admin must configure.
4. Reuse `setupCta`, `setupSummary`, `requiredScopes`, `docsUrl`,
   `credentialUrl`, and `assistantInstructions` in the answer or UI handoff.
5. Prefer `provider.guidance` when present. It contains the already-reviewed
   `primaryAction`, `caveat`, and `canPresentAsLiveAfterHealthCheck` for UI
   and assistant copy.
6. Read `implementationStatus` before promising runtime behavior:
   - `real`: this is a live integration path; after setup and health check it
     can be presented as runnable.
   - `preflight_only`: guide setup and readiness checks, but say that a
     provider-specific runtime path still needs verification before it is
     promised as fully automated.
   - `platform_managed`: route to the platform/operator setup path and do not
     ask the tenant for platform-owned secrets.
   - `dev_env_fallback`: local smoke only; never present as tenant self-serve.
   - `unsupported`: offer webhook, MCP, marketplace, or manual fallback.
7. After connection or save, run the provider's `healthCheckMethod` when
   present and show safe metadata only. Never echo raw secrets or tokens.
8. For credential-free local diagnostics, use
   `pnpm integrations-live:optional`; it writes an explicitly skipped,
   non-release report. `pnpm check:integrations-live` is the required release
   command: it executes the versioned matrix in
   `.github/release-live-integrations.json` and fails on zero attempts, missing
   credentials, partial selection, or any provider failure. Reports contain
   candidate provenance, counts, credential source names, and safe proof
   metadata only.

When the question comes from onboarding or blueprint readiness, first inspect
`resolution.setup` on `needs_connection` entries. If present, use that setup
object directly; it is derived from the same setup registry and keeps the
assistant's next step aligned with the Connections screen.

## Product Rule

Tenant setup must be OAuth/app-install first whenever available. API keys and
environment variables are fallback paths, not the default user journey.
`implementationStatus` controls the honesty of the promise: a setup card can be
useful before it is fully live, but the assistant must name that distinction.

Source: /raw/for-agents/flows/integration-setup-assistant.md

### for-agents/flows/license-lifecycle.md

# Workflow — License lifecycle
## Human guide

[`renewal.md`](../../enterprise-final/renewal.md)


Stripe checkout → provisioning saga → entitlement honor → renewal saga (pre-expiry) →
instant revoke via sync gateway → offline grace cache. End-to-end from first purchase through
revocation. Source: ef-07 SU7.1 PR #3088, SU7.2 PR #3101, SU7.3 PR #3109, SU7.4 (2e5c1ffb9).

## Actors

| Actor | Role |
|---|---|
| Customer | Completes Stripe checkout |
| Stripe | Fires `checkout.session.completed` webhook |
| `apps/license-service` | Provisioning saga + renewal scheduler + revocation issuer |
| `apps/cloud` | Entitlement notification receiver + revocation sync gateway |
| `os-license` | Envelope sign/verify, plan-caps matrix, revocation list, offline cache |
| Desktop sidecar | Verifies license envelope; consults offline grace cache when cloud unreachable |

## Sequence

```
Customer
  │
  ├─► Stripe Checkout → checkout.session.completed webhook
  │
  apps/license-service (billing-route.ts → provisioning saga)
  │
  ├─► PROVISIONING SAGA  (idempotent, keyed on stripeEventId)
  │   ├─► step: createTenant    → cloud: POST /v1/tenants
  │   ├─► step: issueLicense    → signLicenseEnvelope(Ed25519) → store envelope
  │   ├─► step: notifyEntitlement → cloud: PUT /v1/entitlements/:orgId
  │   └─► saga.state = done
  │         on any step failure → compensations run in reverse (deleteEntitlement → revokeLicense → deleteTenant)
  │
  ── TIME PASSES ──
  │
  apps/license-service (renewal scheduler — daily CronJob 02:00 UTC)
  │
  ├─► RENEWAL SAGA  (licenses expiring within 14-day window)
  │   ├─► charge_attempted: chargeRenewal(sub, planId, idempotencyKey) via Stripe
  │   │   ├─► success → reissueLicense (fresh expiresAt) → saga.state = renewed
  │   │   └─► failure → saga.state = grace_started (emits license:renewal_failed)
  │   │         daily retry up to 7-day grace window
  │   │         grace_expired → downgradeLicense(sub, 'solo') → saga.state = downgraded
  │   │                           emits license:downgraded
  │   └─► terminal states: renewed | downgraded | failed
  │
  ── REVOCATION (instant) ──
  │
  Operator (admin console or API)
  │
  ├─► POST /v1/licenses/revoke  (license-service)
  │   ├─► signRevocationList(Ed25519) → RevocationList appended
  │   ├─► cloud sync-gateway: broadcast REVOCATION_UPDATED_TOPIC to connected sidecars
  │   └─► RevocationList served at GET /v1/licenses/revocation-list
  │
  Desktop sidecar (assertNotRevoked)
  │
  ├─► createSidecarRevocationVerifier polls /v1/licenses/revocation-list
  ├─► isRevoked(list, licenseId) → block if true (AK_LICENSE_REVOKED)
  └─► stale list (>24 h) → AK_LICENSE_REVOCATION_STALE (warn; honor cached state)
  │
  ── OFFLINE GRACE ──
  │
  Desktop sidecar (offline verifier)
  │
  ├─► cloud unreachable → createOfflineVerifier reads LicenseCache
  ├─► computeLicenseState(claims, now) → valid | in-grace | expired
  └─► in-grace: resolveOfflineGraceDays(plan) days (plan-specific)
        expired → AK_LICENSE_OFFLINE_GRACE_EXPIRED
```

## Step table

| Step | Actor | Action | On success | On error |
|---|---|---|---|---|
| Webhook receive | license-service | Stripe sig verify | saga created | 400 `AK_BILLING_PAYLOAD_INVALID` |
| createTenant | license-service | `POST /v1/tenants` (cloud) | tenant record exists | `AK_PROVISIONING_TENANT_FAILED` → compensate |
| issueLicense | license-service | `signLicenseEnvelope` | signed envelope stored | `AK_PROVISIONING_LICENSE_FAILED` → compensate |
| notifyEntitlement | license-service | `PUT /v1/entitlements/:orgId` | sidecar may honor caps | `AK_PROVISIONING_NOTIFY_FAILED` → compensate |
| chargeRenewal | license-service | Stripe charge | `reissueLicense` | `AK_RENEWAL_CHARGE_FAILED` → grace |
| reissueLicense | license-service | re-sign envelope | renewed | `AK_RENEWAL_ISSUE_FAILED` |
| downgradeLicense | license-service | update planId → `solo` | downgraded event | `AK_RENEWAL_DOWNGRADE_FAILED` |
| revoke | license-service | `signRevocationList` | RevocationList updated | — |
| sync broadcast | cloud sync-gateway | WS `REVOCATION_UPDATED_TOPIC` | sidecars update list | non-fatal; stale list tolerated 24 h |
| offline verify | sidecar | `assertOfflineLicense` | access granted | `AK_LICENSE_OFFLINE_GRACE_EXPIRED` |

## Touched packages / apps

- `apps/license-service` — provisioning saga, renewal scheduler, revocation issuer
- `apps/cloud` — entitlement routes, sync-gateway WS broadcast
- `packages/os-license` — `signLicenseEnvelope`, `verifyLicenseEnvelope`, `computeLicenseState`, `resolvePlanCaps`, `signRevocationList`, `isRevoked`, `createOfflineVerifier`, `createLicenseCache`

## Audit events emitted

- `license:provisioned` — `{ orgId, planId, seats, expiresAt }`
- `license:renewal_attempted` — `{ orgId, planId, outcome }`
- `license:renewal_failed` — `{ orgId, planId, graceDaysRemaining }`
- `license:downgraded` — `{ orgId, fromPlan, toPlan }`
- `license:revoked` — `{ orgId, revokedBy, reason }`

## Observability hooks

| Span | Key attributes |
|---|---|
| `license.provisioning_saga` | `stripe_event_id`, `org_id`, `plan_id`, `state` |
| `license.renewal_saga` | `org_id`, `attempt`, `grace_days_remaining`, `state` |
| `license.revoke` | `org_id`, `revoked_by` |
| `license.offline_verify` | `org_id`, `state`, `grace_days_remaining` |

## Failure modes and compensations

| Failure | Code | Compensation |
|---|---|---|
| Provisioning step fails | `AK_PROVISIONING_*` | Reverse compensations (deleteEntitlement → revokeLicense → deleteTenant); saga retries on re-delivery |
| Renewal charge fails | `AK_RENEWAL_CHARGE_FAILED` | 7-day grace window; daily retry; downgrade on grace expiry |
| Revocation list stale | `AK_LICENSE_REVOCATION_STALE` | Warn; sidecar uses cached verdict until next successful poll |
| Offline grace expired | `AK_LICENSE_OFFLINE_GRACE_EXPIRED` | User must connect to network; no compensation — intentional enforcement |

## Related ADRs / RFCs / PRs

- ef-07 SU7.1 PR #3088 — provisioning saga
- ef-07 SU7.2 PR #3101 — renewal saga + Helm CronJob
- ef-07 SU7.3 PR #3109 — instant revocation + sync broadcast
- ef-07 SU7.4 (2e5c1ffb9) — offline grace cache + verifier
- [`docs/enterprise-final/renewal.md`](../../enterprise-final/renewal.md) — renewal policy + error codes
- [`docs/for-agents/packages/os-license.md`](../packages/os-license.md) — envelope sign/verify, plan caps

Source: /raw/for-agents/flows/license-lifecycle.md

### for-agents/flows/prd-to-pr.md

# Workflow — PRD → PR
## Human guide

[`pipelines.mdx`](../../../apps/web/content/docs/using-the-app/pipelines.mdx) · [`inbox.mdx`](../../../apps/web/content/docs/using-the-app/inbox.mdx) · [`flows.mdx`](../../../apps/web/content/docs/using-the-app/flows.mdx)


The killer-demo SDLC pipeline. Six phases: **PRD → Issues → QA → Dev → Test → PR**. Each phase emits a HITL gate so an operator can approve, reject, or amend before the next step runs.

Runnable bundle: [`examples/pipeline-prd-to-pr/`](../../../examples/pipeline-prd-to-pr/).

## Phases

| # | Phase | Purpose | Default agent |
|---|---|---|---|
| 1 | PRD | Parse / draft the product requirement doc | `prd-writer` |
| 2 | Issues | Decompose PRD into discrete GitHub issues | `issue-decomposer` |
| 3 | QA | Author acceptance + test plan per issue | `qa-author` |
| 4 | Dev | Coding-agent invocation per issue, in its own git worktree | `claude-code` (configurable) |
| 5 | Test | Run lint / typecheck / tests in the worktree | `os-dev-orchestrator` test runner |
| 6 | PR | Open PR with summary + links to each artifact | `pr-drafter` |

## Methods consumed (in order)

Prefer `pipelines.*` for run lifecycle; `sdlc.runs.*` / `sdlc.pipelines.*` are
deprecated aliases. HITL gates remain `sdlc.gates.*`.

```
pipelines.list                → resolve pipeline definition
pipelines.runs.dispatch       → start a run
runner.getState (poll)        → track phase progression
sdlc.gates.list               → fetch open HITL gates
sdlc.gates.decide             → approve / reject / amend a gate
coding.delegate / coding.runTask  → invoke the coding agent per issue
coding.cancelTask             → user-initiated cancel
pipelines.runs.resume         → resume after a gate decision
sdlc.runs.fork                → fork after a rejected gate (alias path)
pipelines.runs.list / get     → inspect run history
```

## Failure modes

- **Gate timeout** — gates have a configurable TTL; expired gates auto-reject with `gate-expired` and the run pauses.
- **Coding-agent failure** — classified via `classifyCodingFailure`; retryable codes loop per `CODING_FAILURE_CATALOG.maxAttempts`, hard codes (`auth-required`, `permission-denied`) escalate to HITL.
- **Worktree conflict** — `FileConflict` returned in the subtask report; the orchestrator pauses for resolution before continuing.
- **PR draft rejected** — gate 6 reject loops back to gate 4 (Dev) with the reviewer comment as additional context.

## Cross-references

- [`docs/for-agents/packages/os-dev-orchestrator.md`](../packages/os-dev-orchestrator.md) — pipeline implementation.
- [`docs/for-agents/screens/sdlc.md`](../screens/sdlc.md) — Processes screen (nav id `pipeline`).
- [`apps/web/content/docs/using-the-app/pipelines.mdx`](../../../apps/web/content/docs/using-the-app/pipelines.mdx) — end-user guide.
- [`docs/for-agents/packages/os-coding-agents.md`](../packages/os-coding-agents.md) — coding-agent providers.

Source: /raw/for-agents/flows/prd-to-pr.md

### for-agents/flows/public-automation-api.md

# Public automation API

Use when the user asks how external systems trigger AKOS workflows without the
desktop UI — webhooks, API keys, or the public automation surface.

## Human guide

[`public-automation-api.mdx`](../../../apps/web/content/docs/using-the-app/public-automation-api.mdx) · [`connections.mdx`](../../../apps/web/content/docs/using-the-app/connections.mdx) · [`triggers.mdx`](../../../apps/web/content/docs/using-the-app/triggers.mdx)

## Agent reference

- Screen: [`triggers.md`](../screens/triggers.md) — Automations authoring
- Contracts: `triggers.*`, `dispatch.*`, `flows.*` in
  [`contracts/README.md`](../contracts/README.md)
- Cloud routes: `apps/cloud/src/api/automation-routes.ts` (when hosted)

## Flow

1. Confirm workspace and target flow or automation id.
2. Check egress and auth posture — outbound callbacks and inbound webhooks must
   pass `egress.*` and connection policies.
3. For API-key automation, verify keys are stored in the vault / connection
   registry, never echoed in chat.
4. Guide the user to **Automations** for trigger CRUD or to the public API docs
   for wire-format examples.
5. After creation, validate with a dry run or `pipelines.*` / `dispatch.*` test
   invocation before promising production traffic.

## Edge cases

- Public automation on cloud requires tenant context from session — do not
  accept `orgId` from unauthenticated callers.
- Webhook secrets rotate through the connections registry; stale keys return
  `AK_AUTH_*` codes — link to Integrations, not file edits.

Source: /raw/for-agents/flows/public-automation-api.md

### for-agents/flows/storage-migration.md

# Workflow — Storage migration (local → cloud)
## Human guide

[`migrating.mdx`](../../../apps/web/content/docs/cli/migrating.mdx)


Migrates an operator's local SQLiteFs data to a cloud Postgres + S3 BlobStore via the
`agentskit-os migrate-to-cloud` CLI. Resumable and idempotent. Source: ef-02 SU2.6 (#2976).

## Actors

| Actor | Role |
|---|---|
| Operator | Runs the CLI; owns source data directory and target credentials |
| `os-cli` | Orchestrates plan, validate, stream, checkpoint |
| `os-store-postgres` | Target relational driver + RLS helpers |
| `os-blob-s3` | Target blob store adapter |
| Cloud Postgres | Receives streamed rows via `INSERT … ON CONFLICT DO NOTHING` |
| S3 BlobStore | Receives blob objects after list-probe dedup |

## Sequence

```
Operator
  │
  ├─► agentskit-os migrate-to-cloud --org … --source … --target … [--dry-run] [--resume]
  │
  │   PHASE 1 — PLAN
  │   ├─► scan source: enumerate .db files (table × row-count) + blobs/ prefixes
  │   ├─► print MigrationPlan to stdout (always, even --dry-run)
  │   └─► [--dry-run] EXIT 0 — no writes
  │
  │   PHASE 2 — VALIDATE TARGET
  │   ├─► PostgresRelationalDriver.open() → ping DB
  │   ├─► runRlsMigration(): assert RLS policies on tenant tables
  │   └─► S3BlobStore.list(): probe AKOS_S3_BUCKET (skip when env absent)
  │
  │   PHASE 3 — APPLY (rows)
  │   ├─► for each table (dependency order, batch 500 rows):
  │   │     ALTER TABLE … ADD COLUMN migrated_at (idempotent)
  │   │     INSERT … ON CONFLICT DO NOTHING
  │   │     checkpoint update → .migrate-checkpoint.json
  │   └─► [--resume] completed tables skipped via checkpoint
  │
  │   PHASE 4 — APPLY (blobs)
  │   ├─► for each blob prefix:
  │   │     S3.list() existing objects in target
  │   │     copy only absent objects
  │   │     checkpoint update
  │   └─► EXIT 0
```

## Step table

| Step | Actor | Action / RPC | On success | On error |
|---|---|---|---|---|
| Plan scan | os-cli | read source dir | MigrationPlan printed | `AK_MIGRATE_SOURCE_UNREADABLE` |
| DB ping | os-store-postgres | `PostgresRelationalDriver.open()` | continue | `AK_MIGRATE_TARGET_NOT_POSTGRES` |
| RLS check | os-store-postgres | `runRlsMigration()` assertion | continue | `AK_MIGRATE_TARGET_RLS_MISSING` |
| Blob probe | os-blob-s3 | `BlobStore.list()` | continue | `AK_MIGRATE_TARGET_BLOBSTORE_MISSING` |
| Row batch | os-store-postgres | `INSERT … ON CONFLICT DO NOTHING` ×N | checkpoint update | `AK_MIGRATE_TABLE_FAILED` → retry or abort |
| Blob copy | os-blob-s3 | get → put (absent objects only) | checkpoint update | `AK_MIGRATE_BLOB_FAILED` → retry or abort |

## Touched packages

- `packages/os-cli` — CLI entry, MigrationPlan, checkpoint manager
- `packages/os-store-postgres` — `PostgresRelationalDriver`, `runRlsMigration`
- `packages/os-blob-s3` — `S3BlobStore` adapter

## Audit events emitted

- `migration:plan_generated` — plan row count + size estimate
- `migration:table_complete` — per table: rows written + skipped
- `migration:blob_prefix_complete` — per prefix: objects copied + skipped
- `migration:done` — org, source, target (no credentials)
- `migration:aborted` — phase + error code on failure

## Observability hooks

| Span | Key attributes |
|---|---|
| `migration.plan` | `org_id`, `table_count`, `estimated_bytes` |
| `migration.validate_target` | `rls_ok`, `blob_probe_ok` |
| `migration.table` | `table_name`, `rows_written`, `rows_skipped`, `batch_count` |
| `migration.blobs` | `prefix`, `objects_copied`, `objects_skipped` |

## Failure modes and compensations

| Failure | Code | Compensation |
|---|---|---|
| Source missing | `AK_MIGRATE_SOURCE_UNREADABLE` | Fix `--source` path; no rollback needed |
| Target DB unreachable | `AK_MIGRATE_TARGET_NOT_POSTGRES` | Fix `--target` URL; no rows written |
| RLS not applied | `AK_MIGRATE_TARGET_RLS_MISSING` | Run `runRlsMigration(store)` then retry |
| Blob probe failed | `AK_MIGRATE_TARGET_BLOBSTORE_MISSING` | Check `AKOS_S3_BUCKET` + AWS credentials |
| Table batch failed | `AK_MIGRATE_TABLE_FAILED` | Re-run with `--resume`; idempotent via conflict skip |
| Blob copy failed | `AK_MIGRATE_BLOB_FAILED` | Re-run with `--resume`; list-probe dedup prevents double-copy |
| Checkpoint corrupt | `AK_MIGRATE_CHECKPOINT_CORRUPT` | Delete checkpoint and re-run from zero |

## Related ADRs / RFCs / PRs

- ADR-0073 — Cloud Postgres + RLS activation
- ADR-0090 — S3 event ingestion + BlobStore adapter
- ef-02 SU2.1 (#2971) — Postgres driver
- ef-02 SU2.2 (#2972) — RLS migration helper
- ef-02 SU2.3 (#2973) — S3 BlobStore
- ef-02 SU2.6 (#2976) — `migrate-to-cloud` CLI command
- [`docs/enterprise-final/migrate-to-cloud.md`](../../enterprise-final/migrate-to-cloud.md) — operator runbook

Source: /raw/for-agents/flows/storage-migration.md

### for-agents/flows/trigger-to-run.md

# Workflow — Trigger to run
## Human guide

[`triggers.mdx`](../../../apps/web/content/docs/using-the-app/triggers.mdx) · [`flows.mdx`](../../../apps/web/content/docs/using-the-app/flows.mdx) · [`runs-and-observability.mdx`](../../../apps/web/content/docs/using-the-app/runs-and-observability.mdx)


External event → trigger daemon → flow dispatch → run record. Covers cron, webhook, file-watch, postgres-CDC, and email triggers (full kind catalog in [`os-triggers.md`](../os-triggers.md)).

## Lifecycle

```
trigger authored        → triggers.upsert
trigger toggled live    → triggers.toggle (paused: false)
event arrives           → daemon fires (cron tick / HTTP POST / file event / CDC slot / IMAP poll)
dispatch validated      → dispatcher Zod-parses payload, applies RBAC + firewall
run created             → runs.create (runId returned to trigger log)
trigger log appended    → triggers.recentRuns reflects the new row
run progresses          → runner.getState driving the UI
```

## Methods consumed

```
triggers.list | get | upsert | delete | toggle | testFire | recentRuns
triggers.kinds | contracts
runs.create | runs.get | runs.list
runner.runFlow | runner.runAgent | runner.getState
firewall.evaluate (per dispatch)
audit.append (per dispatch)
```

## Failure modes

- **Payload schema mismatch** — dispatcher rejects with Zod issues; row appears in `triggers.recentRuns` with `status: 'rejected'`.
- **Firewall block** — prompt-firewall flag returns `block`; the run is never created; trigger log records the verdict.
- **Daemon down** — cron / IMAP daemons heartbeat; missed heartbeats surface as `degraded` in `triggers.list`.
- **Replication slot lost (CDC)** — slot recreation needed; trigger marked `degraded` until the operator clicks "Reattach".

## Cross-references

- [`docs/for-agents/os-triggers.md`](../os-triggers.md) — full kind catalog.
- [`docs/for-agents/screens/triggers.md`](../screens/triggers.md) — UI surface.

Source: /raw/for-agents/flows/trigger-to-run.md

### for-agents/os-triggers.md

# Triggers

## Overview

Triggers are the entry points that start flows. A trigger watches an external event source — a cron schedule, an HTTP call, a file-system change, a chat message, a database row mutation, or a third-party webhook — and, when it fires, invokes the flow referenced by its `flow` field.

Every trigger is stored as a `TriggerUpsertConfig` discriminated union in the workspace's persistent store (owned by `os-headless`). The `kind` field selects the union branch; every branch also carries the shared common fields.

### Common fields (all kinds)

| Field | Type | Required | Default |
|---|---|---|---|
| `id` | string (1–128) | yes | — |
| `flow` | string (1–128) | yes | — |
| `kind` | one of 14 kinds | yes | — |
| `name` | string (1–128) | no | — |
| `enabled` | boolean | no | `true` |
| `tags` | string[] | no | `[]` |

### The 14 kinds

| Kind | Status | Source |
|---|---|---|
| `cron` | supported | builtin |
| `webhook` | supported | builtin |
| `file` | supported | builtin |
| `email` | supported | integration |
| `slack` | supported | integration |
| `github` | supported | integration |
| `linear` | supported | integration |
| `cdc` | supported | integration |
| `discord` | supported | integration |
| `twilio` | supported | integration |
| `sentry` | supported | integration |
| `pagerduty` | supported | integration |
| `stripe` | supported | integration |
| `s3` | supported | integration |

---

## cron

Fires on a wall-clock schedule expressed as a cron expression.

**Required fields:** `cron`

**Optional fields:** `timezone`

| Field | Type | Constraints |
|---|---|---|
| `cron` | string | standard 5-field cron, max 128 chars |
| `timezone` | string | IANA tz name, max 64 chars |

```yaml
id: daily-report
kind: cron
flow: generate-daily-report
cron: "0 8 * * 1-5"
timezone: America/New_York
enabled: true
tags: [reports]
```

```bash
# Create via CLI
agentskit-os triggers upsert \
  --id daily-report \
  --kind cron \
  --flow generate-daily-report \
  --cron "0 8 * * 1-5" \
  --timezone America/New_York
```

---

## webhook

Exposes an HTTP endpoint; fires when a request matching `method` arrives at `path`. Optionally verifies an HMAC-SHA256 signature.

**Required fields:** `path`

**Optional fields:** `method`, `secret`, `signing`

| Field | Type | Constraints | Default |
|---|---|---|---|
| `path` | string | starts with `/`, alphanumeric + `/ - _`, max 256 | — |
| `method` | `GET \| POST \| PUT \| PATCH \| DELETE` | | `POST` |
| `secret` | string or `{ ref: string }` | plain text or vault ref | — |
| `signing.algorithm` | `hmac-sha256` | | `hmac-sha256` |
| `signing.signatureHeader` | string | max 128 | `x-agentskit-signature` |
| `signing.timestampHeader` | string | max 128 | `x-agentskit-timestamp` |
| `signing.toleranceSeconds` | integer 0–86400 | replay-window | `300` |

```yaml
id: stripe-webhook
kind: webhook
flow: handle-stripe-event
path: /webhooks/stripe
method: POST
secret:
  ref: secrets/stripe-webhook-secret
signing:
  algorithm: hmac-sha256
  signatureHeader: stripe-signature
  toleranceSeconds: 300
```

```bash
# Test locally with curl after upsert (publicUrl from upsert output)
curl -X POST https://<host>/webhooks/stripe \
  -H "Content-Type: application/json" \
  -H "x-agentskit-timestamp: $(date +%s)" \
  -H "x-agentskit-signature: <computed-hmac>" \
  -d '{"type":"payment_intent.succeeded"}'
```

### Connection-derived inbound routes (flow-optional, RFC-0022 SU11)

A `webhook` trigger always runs a flow. An integration **Connection** that
declares a `receive` capability is *also* an inbound surface, but it has no
flow of its own — it exists to feed multi-turn / HITL conversations on
Slack/GitHub/Linear.

At sidecar boot `createTriggerBootstrap` derives a provider route per
`receive` Connection (via `providerRoutesFromConnections`), resolving the
connection's `secret`-typed auth ref through the secret store so the inbound
HMAC signature is verified. These routes are **flow-optional**: the webhook
server still verifies the signature, fans the verified event to HITL
(`hitl.channelReply`) and to kanban columns, then acks `202
{ status: "accepted", hitlOnly: true }` without running any flow. The webhook
server now starts even when there are zero `webhook` triggers, as long as at
least one such Connection exists. A Connection whose secret cannot be
resolved is silently skipped — no unverifiable route is ever published.

---

## file

Watches a directory path for filesystem events.

**Required fields:** `path`

**Optional fields:** `events`, `glob`

| Field | Type | Constraints | Default |
|---|---|---|---|
| `path` | string | absolute path, max 1024 | — |
| `events` | `('add' \| 'change' \| 'unlink')[]` | min 1 | `['add','change']` |
| `glob` | string | glob pattern, max 256 | — |

```yaml
id: watch-uploads
kind: file
flow: process-uploaded-file
path: /data/uploads
events: [add]
glob: "**/*.pdf"
```

```bash
agentskit-os triggers upsert \
  --id watch-uploads \
  --kind file \
  --flow process-uploaded-file \
  --path /data/uploads \
  --events add \
  --glob "**/*.pdf"
```

---

## email

Polls an IMAP mailbox and fires when an incoming message matches the optional filter expression.

**Required fields:** `mailbox`

**Optional fields:** `filter`

| Field | Type | Constraints |
|---|---|---|
| `mailbox` | string | IMAP folder name or address, max 256 |
| `filter` | string | IMAP search string, max 512 |

```yaml
id: support-inbox
kind: email
flow: route-support-ticket
mailbox: support@example.com
filter: "SUBJECT [ticket]"
```

```bash
# IMAP connection is configured via environment variables consumed by os-headless:
# AKOS_IMAP_HOST, AKOS_IMAP_PORT, AKOS_IMAP_USER, AKOS_IMAP_PASS
agentskit-os triggers upsert \
  --id support-inbox \
  --kind email \
  --flow route-support-ticket \
  --mailbox support@example.com \
  --filter "SUBJECT [ticket]"
```

---

## slack

Fires when an event occurs in a Slack channel.

**Required fields:** `channel`

**Optional fields:** `event`

| Field | Type | Constraints | Default |
|---|---|---|---|
| `channel` | string | channel name or ID, max 128 | — |
| `event` | `'message' \| 'mention' \| 'reaction'` | | `message` |

```yaml
id: slack-alerts
kind: slack
flow: handle-slack-alert
channel: "#ops-alerts"
event: mention
```

```bash
agentskit-os triggers upsert \
  --id slack-alerts \
  --kind slack \
  --flow handle-slack-alert \
  --channel "#ops-alerts" \
  --event mention
```

---

## github

Fires on a GitHub repository event. Optionally filters with a JMESPath expression.

**Required fields:** `repo`, `event`

**Optional fields:** `filter`

| Field | Type | Constraints |
|---|---|---|
| `repo` | string | `owner/repo` pattern |
| `event` | `'pull_request' \| 'issues' \| 'push' \| 'release' \| 'workflow_run'` | — |
| `filter` | string | filter expression, max 512 |

```yaml
id: pr-review-trigger
kind: github
flow: auto-review-pr
repo: acme/api-service
event: pull_request
filter: "action == 'opened'"
```

```bash
# Ensure AKOS_GITHUB_TOKEN is set, then:
agentskit-os triggers upsert \
  --id pr-review-trigger \
  --kind github \
  --flow auto-review-pr \
  --repo acme/api-service \
  --event pull_request \
  --filter "action == 'opened'"
```

---

## linear

Fires on Linear project events within a team.

**Required fields:** `team`

**Optional fields:** `event`

| Field | Type | Constraints | Default |
|---|---|---|---|
| `team` | string | Linear team identifier, max 64 | — |
| `event` | `'issue.create' \| 'issue.update' \| 'comment.create'` | | `issue.create` |

```yaml
id: linear-new-issue
kind: linear
flow: triage-linear-issue
team: ENG
event: issue.create
```

---

## cdc

Fires on Postgres / Supabase / MySQL row changes via change data capture.

**Required fields:** `source`, `connection`, `table`

**Optional fields:** `operations`

| Field | Type | Constraints | Default |
|---|---|---|---|
| `source` | `'postgres' \| 'supabase' \| 'mysql'` | — | — |
| `connection` | string or `{ ref: string }` | connection string or vault ref | — |
| `table` | string | schema-qualified if needed, max 128 | — |
| `operations` | `('insert' \| 'update' \| 'delete')[]` | min 1 | `['insert']` |

```yaml
id: orders-cdc
kind: cdc
flow: process-new-order
source: postgres
connection:
  ref: secrets/primary-db-url
table: public.orders
operations: [insert]
```

```bash
# Logical replication must be enabled on the Postgres instance (wal_level=logical).
# Supabase enables this by default.
agentskit-os triggers upsert \
  --id orders-cdc \
  --kind cdc \
  --flow process-new-order \
  --source postgres \
  --connection-ref secrets/primary-db-url \
  --table public.orders \
  --operations insert
```

---

## discord

Fires when an event occurs in a Discord channel.

**Required fields:** `channelId`

**Optional fields:** `event`

| Field | Type | Constraints | Default |
|---|---|---|---|
| `channelId` | string | Discord channel snowflake, max 128 | — |
| `event` | `'message' \| 'mention' \| 'reaction'` | | `message` |

```yaml
id: discord-support
kind: discord
flow: handle-discord-support
channelId: "1234567890123456789"
event: message
```

---

## twilio

Fires when an inbound Twilio message or call arrives on a number.

**Required fields:** `channel`, `toNumber`

| Field | Type | Constraints | Default |
|---|---|---|---|
| `channel` | `'sms' \| 'whatsapp' \| 'voice'` | | `sms` |
| `toNumber` | string | E.164 format, max 32 | — |

```yaml
id: sms-intake
kind: twilio
flow: process-inbound-sms
channel: sms
toNumber: "+15550001234"
```

```bash
# Twilio webhook must point to the headless sidecar's public URL.
# Set AKOS_TWILIO_AUTH_TOKEN for signature verification.
agentskit-os triggers upsert \
  --id sms-intake \
  --kind twilio \
  --flow process-inbound-sms \
  --channel sms \
  --to-number "+15550001234"
```

---

## sentry

Fires when a Sentry project emits an event alert.

**Required fields:** `project`

**Optional fields:** `event`

| Field | Type | Constraints | Default |
|---|---|---|---|
| `project` | string | Sentry project slug, max 128 | — |
| `event` | `'issue.created' \| 'issue.regression' \| 'event.alert'` | | `issue.created` |

```yaml
id: sentry-regressions
kind: sentry
flow: escalate-regression
project: api-service
event: issue.regression
```

---

## pagerduty

Fires on PagerDuty incident lifecycle events.

**Required fields:** `service`

**Optional fields:** `event`

| Field | Type | Constraints | Default |
|---|---|---|---|
| `service` | string | PagerDuty service ID or name, max 128 | — |
| `event` | `'incident.triggered' \| 'incident.acknowledged' \| 'incident.resolved'` | | `incident.triggered` |

```yaml
id: pd-incident-trigger
kind: pagerduty
flow: handle-pagerduty-incident
service: P12ABCD
event: incident.triggered
```

---

## stripe

Fires on any Stripe event for a connected account.

**Required fields:** `account`, `event`

| Field | Type | Constraints |
|---|---|---|
| `account` | string | Stripe account ID or label, max 128 |
| `event` | string | Stripe event type, e.g. `payment_intent.succeeded`, max 128 |

```yaml
id: stripe-payment-success
kind: stripe
flow: fulfill-order
account: acct_1ABC
event: payment_intent.succeeded
```

```bash
# Point Stripe dashboard webhook to the headless sidecar's publicUrl,
# or use the Stripe CLI for local dev:
stripe listen --forward-to https://<host>/webhooks/stripe
```

---

## s3

Fires when objects are created or removed in an S3-compatible bucket.

**Required fields:** `bucket`

**Optional fields:** `prefix`, `events`

| Field | Type | Constraints | Default |
|---|---|---|---|
| `bucket` | string | bucket name, max 128 | — |
| `prefix` | string | key prefix filter, max 1024 | — |
| `events` | `('object.created' \| 'object.removed')[]` | min 1 | `['object.created']` |

```yaml
id: s3-ingest
kind: s3
flow: process-s3-upload
bucket: my-data-lake
prefix: raw/2025/
events: [object.created]
```

**Runtime (ADR-0090).** S3 has no native push to an arbitrary endpoint, so
the `s3` trigger fires via an **S3 → SQS → poll** daemon. The operator points
the bucket's event notification at an SQS queue once; the headless sidecar
long-polls that queue (`@aws-sdk/client-sqs`, an `optionalDependency`),
decodes the S3 event records, filters by `bucket` / `prefix` / `events`, and
dispatches each matching object event to the flow as `input.s3`. Delivery is
deduped per object by the S3 record `sequencer`, so SQS at-least-once
redelivery never double-fires a flow.

The daemon is configured by environment:

| Variable | Purpose |
|---|---|
| `AKOS_S3_SQS_QUEUE_URL` | SQS queue URL — required; unset = daemon off |
| `AKOS_S3_BUCKET` | bucket the daemon filters on |
| `AKOS_S3_PREFIX` | optional key-prefix filter |
| `AKOS_S3_SQS_REGION` | optional AWS region (SDK default chain otherwise) |
| `AKOS_S3_FLOW_ID` | flow to dispatch to (default `flow-s3-poll`) |

AWS credentials come from the standard SDK provider chain (env / IAM role /
`~/.aws`) or the AKOS secret vault — never persisted in an AKOS store. When
`@aws-sdk/client-sqs` is not installed (air-gapped hosts), the daemon is
skipped with a warning and the rest of the sidecar boots normally; tests and
embedders inject a custom pull fn via `bootTriggerDaemons({ s3Pull })`.

---

## JSON-RPC method reference

All methods are available on the `cli`, `desktop`, and `web` surfaces unless noted. Stability: `alpha` (since S00).

| Method | Input | Output | Caps required | Idempotent |
|---|---|---|---|---|
| `triggers.kinds` | `{}` | `{ kinds: TriggerKindCatalogEntry[] }` | none | yes |
| `triggers.contracts` | `{}` | `{ contracts: TriggerContractDescriptor[] }` | none | yes |
| `triggers.list` | `{ workspaceId? }` | `{ triggers: TriggerSummary[] }` | none | yes |
| `triggers.get` | `{ id, workspaceId? }` | `{ config: TriggerUpsertConfig \| null, publicUrl? }` | none | yes |
| `triggers.upsert` | `{ config: TriggerUpsertConfig, workspaceId? }` | `{ id, created: boolean, publicUrl? }` | `triggers.write` | no |
| `triggers.delete` | `{ id, workspaceId? }` | `{ removed: boolean }` | `triggers.write` | no |
| `triggers.toggle` | `{ id, enabled: boolean, workspaceId? }` | `{ id, enabled: boolean }` | `triggers.write` | no |
| `triggers.testFire` | `{ id, payload?: unknown, workspaceId? }` | `{ runId, accepted: boolean }` | `triggers.write` | no |
| `triggers.recentRuns` | `{ id, limit?: 1–200, workspaceId? }` | `{ runs: TriggerRunRow[] }` | none | yes |

**TriggerSummary** fields: `id`, `kind`, `flow`, `enabled`, `publicUrl?`, `lastRunAt?`, `lastRunStatus?` (`ok | error | running`).

**TriggerRunRow** fields: `runId`, `triggerId`, `startedAt`, `finishedAt?`, `status` (`ok | error | running | cancelled`), `durationMs?`.

---

## Test a trigger

`triggers.testFire` manually invokes the flow linked to any trigger without waiting for the real event source. An optional `payload` overrides the synthetic default.

**CLI:**

```bash
# Fire with synthetic payload
agentskit-os triggers test-fire --id daily-report

# Fire with a custom payload
agentskit-os triggers test-fire --id stripe-payment-success \
  --payload '{"type":"payment_intent.succeeded","data":{"object":{"id":"pi_test"}}}'
```

**Desktop:** Open the trigger detail panel, click "Test fire". The run appears immediately in the run history panel below.

**Web:** Navigate to Settings > Triggers, select the trigger, click "Test fire". Output streams in the run drawer.

**Direct JSON-RPC (curl against a running sidecar):**

```bash
curl -s http://localhost:4001/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"triggers.testFire","params":{"id":"daily-report"}}'
```

The response carries `runId` — use `triggers.recentRuns` or `runs.get` to poll for completion:

```bash
agentskit-os runs get --id <runId>
```

---

## Wiring to flows

Every trigger config carries a `flow` field that references a flow by its `id` (defined in `workspace.yaml` or `flows/*.yaml`). When the trigger fires, the headless sidecar calls `createHeadlessRunner` with that flow id and the trigger payload as the initial input.

```yaml
# flows/triage.yaml
id: triage-support-ticket
nodes:
  - id: classify
    agent: classifier-agent
  - id: route
    agent: router-agent
    dependsOn: [classify]

# workspace.yaml (triggers section)
triggers:
  - id: email-triage
    kind: email
    flow: triage-support-ticket   # matches flows/triage.yaml id field
    mailbox: support@example.com
```

The flow id must resolve to a flow present in the workspace at daemon startup. If the flow is missing, the trigger daemon logs a warning and skips dispatch until the flow is registered.

To change which flow a trigger points at without re-creating it, use `triggers.upsert` with an updated `flow` field — this is an in-place update because `id` is unchanged:

```bash
agentskit-os triggers upsert \
  --id email-triage \
  --kind email \
  --flow triage-support-ticket-v2 \
  --mailbox support@example.com
```

Source: /raw/for-agents/os-triggers.md

### for-agents/packages/agent-contracts.md

# packages/agent-contracts

## Purpose

`@agentskit/agent-contracts` is the versioned registry of Zod schemas for structured agent outputs across the AgentsKitOS runtime.

Every agent that emits structured JSON declares its output shape here as a named Zod schema. Downstream packages (`os-runtime`, `os-headless`, `pack-loader`) import these schemas to:

- Validate and type-narrow the structured JSON that LLMs emit before it enters any business logic.
- Resolve schemas at runtime via a slug-and-version ref (e.g. `prd-output@v1`).
- Provide TypeScript inferred types to callers without duplicating schema logic.

The package ships with 10 schemas covering all six reference vertical packs (coding, law, healthcare, marketing × 2, finance), plus the two original PRD/risk schemas.

---

## Versioned schema system

Each schema is a separate source file named `src/schemas/<slug>.v<N>.ts`. The file exports:

- A Zod schema constant (`<slug>V<N>Schema`), e.g. `prdOutputV1Schema`.
- An inferred TypeScript type (`<Slug>V<N>`), e.g. `PrdOutputV1`.
- Any enum constants referenced by the schema (e.g. `RiskLevel`, `TriageLevel`).

The compile-time registry in `src/version.ts` maps every known slug to its latest version number:

```ts
import { CONTRACT_REGISTRY } from '@agentskit/agent-contracts'
// CONTRACT_REGISTRY['prd-output'] === 1
```

`ContractSlug` and `ContractLatestVersion<S>` are exported utility types that allow callers to write version-safe lookup code at compile time.

---

## Runtime registry

The package provides a factory function, not a singleton, so each call site can hold an isolated registry.

### `createAgentContractRegistry()`

Returns a fresh, empty `AgentContractRegistry` with three methods:

| Method | Signature | Description |
|---|---|---|
| `defineAgentContract` | `(slug, version, schema) => void` | Register a Zod schema under `slug@version`. Re-registering the same ref with the same schema reference is a no-op. Re-registering with a *different* schema emits a `warn` log and overwrites. |
| `resolveAgentContract` | `(ref: ContractRef) => ZodTypeAny` | Look up a schema by `slug@version`. Throws `AgentsKitError` with code `AK_AGENT_CONTRACT_NOT_FOUND` when the ref is not registered. |
| `listAgentContracts` | `() => readonly ContractRef[]` | Return all registered refs in insertion order. |

`ContractRef` is the opaque branded string `"${slug}@${version}"`.

### `createDefaultAgentContractRegistry()`

Returns a pre-populated `AgentContractRegistry` containing all 10 built-in v1 schemas. Callers that need the full set of vertical contracts (e.g. `pack-loader`, `os-headless`) use this to avoid importing each schema individually.

```ts
import { createDefaultAgentContractRegistry } from '@agentskit/agent-contracts'

const registry = createDefaultAgentContractRegistry()
const schema = registry.resolveAgentContract('prd-output@v1')
const parsed = schema.safeParse(rawLlmOutput)
```

Each call returns a new isolated instance — there is no module-level singleton.

---

## Per-vertical contracts

| Slug | Version | Type | Vertical | Description |
|---|---|---|---|---|
| `prd-output` | v1 | `PrdOutputV1` | Coding | PRD: problem, users, criteria, outOfScope, openQuestions |
| `risk-analysis-output` | v1 | `RiskAnalysisOutputV1` | Law | Per-clause risk items + overall risk level (`RiskLevel` enum) |
| `triage-output` | v1 | `TriageOutputV1` | Healthcare | Triage classification level, signals, recommendation, escalation flag |
| `issue-list-output` | v1 | `IssueListOutputV1` | Coding | List of GitHub issues created from PRD criteria |
| `qa-specs-output` | v1 | `QaSpecsOutputV1` | Coding | Vitest spec stubs generated from acceptance criteria |
| `clause-extraction-output` | v1 | `ClauseExtractionOutputV1` | Law | Structured clause analysis from a legal contract |
| `social-variants-output` | v1 | `SocialVariantsOutputV1` | Marketing | Exactly 3 copy variants (`CopyVariantId`: ousada/acolhedora/precisa) |
| `brand-review-output` | v1 | `BrandReviewOutputV1` | Marketing | Per-variant brand compliance audit (`BrandReviewVerdict` enum) |
| `financial-risk-output` | v1 | `FinancialRiskOutputV1` | Finance | Composite risk score (0–100), tier (`FinancialRiskTier` enum), per-dimension factors |
| `brief-analysis-output` | v1 | `BriefAnalysisOutputV1` | Marketing | Structured brief: objective, audience, key messages, tone, channels |

Schemas that need to accommodate future additive fields use `.passthrough()`. Schemas where strict shape validation is required (e.g. `prdOutputV1Schema`) use the default `.strict` Zod behaviour.

---

## Public exports

All exports are named (no `export default`):

**Schemas and types** (one set per vertical contract — see table above):

```ts
// Example — prd-output
export { prdOutputV1Schema } from './schemas/prd-output.v1.js'
export type { PrdOutputV1 } from './schemas/prd-output.v1.js'

// Example — risk-analysis-output
export { riskAnalysisOutputV1Schema, riskAnalysisItemSchema, RiskLevel } from './schemas/risk-analysis-output.v1.js'
export type { RiskAnalysisOutputV1, RiskAnalysisItem } from './schemas/risk-analysis-output.v1.js'
```

**Registry factory and types**:

```ts
export { createAgentContractRegistry } from './registry.js'
export type { AgentContractRegistry, ContractEntry, ContractRef } from './registry.js'

export { createDefaultAgentContractRegistry } from './default-registry.js'
```

**Compile-time version map**:

```ts
export { CONTRACT_REGISTRY } from './version.js'
export type { ContractSlug, ContractLatestVersion } from './version.js'
```

---

## How runtime consumers use this package

`os-headless` and `pack-loader` call `createDefaultAgentContractRegistry()` once at startup and hold the instance. When an agent run completes:

1. The runtime calls `registry.resolveAgentContract(ref)` with the contract ref declared by the pack YAML.
2. It calls `schema.safeParse(rawOutput)` on the LLM's structured output.
3. On failure, it throws `AgentsKitError` with `AK_AGENT_CONTRACT_NOT_FOUND` (unknown ref) or surfaces Zod errors to the HITL layer.

---

## Wired stores

None — pure schema/validation layer, no side effects or mutable module state.

---

## Common questions

> **How do I add a new structured output schema?**
>
> 1. Create `src/schemas/<slug>.v1.ts` with a named Zod schema constant and inferred type export.
> 2. Add `'<slug>': 1` to `CONTRACT_REGISTRY` in `src/version.ts`.
> 3. Import and register in `src/default-registry.ts` inside `createDefaultAgentContractRegistry`.
> 4. Export from `src/index.ts`.
> 5. Add tests (valid + invalid parse cases, registered in the default registry).
> 6. Add a changeset (`pnpm changeset`).

> **Why version output schemas?**
>
> LLM output shapes evolve. Versioning lets an agent emit `v2` output while a consumer that only knows `v1` still validates safely (or opts in to a migration helper). The slug-at-version ref (`prd-output@v1`) is the stable contract identity.

> **What error code is thrown for a missing ref?**
>
> `AK_AGENT_CONTRACT_NOT_FOUND` — defined in `@agentskit/os-core/errors/codes` and thrown as `AgentsKitError`.

Source: /raw/for-agents/packages/agent-contracts.md

### for-agents/packages/desktop-agent-workspace.md

# packages/desktop-agent-workspace

## Purpose

Screens for building, running, and evaluating agents, plus the interactive NL copilot. Extracted from `@agentskit/os-desktop` per ADR-0108 / pkg-refactor-plan/06-desktop-split.md §Package 4. Renders inside both `apps/desktop` (Tauri) and `apps/web` (browser) via `desktop-shell`. All sidecar access goes through `@agentskit/desktop-sidecar-bridge` — the package never imports a runtime directly.

## Screens

| Screen | Route | Purpose |
|---|---|---|
| Agents | `/agents` | Agent registry: list, create, edit, lifecycle transitions, run |
| Coding | `/coding` | Coding-agent provider UI (Claude Code, Codex, Cursor…) |
| Evals | `/evals` | Eval suite builder, run, and result viewer |
| Copilot | `/copilot` | Interactive NL copilot (RFC-0013) — slash commands, mentions, proposals, proactive hints |

## Public exports

All exports are named and live in `src/index.ts`.

- Screen mounts (consumed by `desktop-shell`'s `SCREENS_REGISTRY`): `AgentsScreen`, `CodingScreen`, `CodingProvidersTab`, `EvalsScreen`, `CopilotScreen`.
- IoC / context wiring: `AgentWorkspaceContextProvider` (+ types `AgentWorkspaceContextProviderProps`, `TFn`); `AgentWorkspacePaletteContext` (+ types `AgentWorkspacePaletteContextValue`, `RegisterCommandSpec`, `CommandCategory`).
- Copilot surface: `CopilotChatPanel`, `CopilotOnboardingWizard`, `CopilotPowers`, `CopilotProvider`, `useCopilotConfig`, `useCopilotSession`, `SelectionProvider`, `useSelection` (+ types `CopilotChatPanelProps`, `CopilotProviderProps`, `CopilotChatHandlers`, `CopilotChatState`, `MentionEntity`, `ProposalDecision`, `SlashCommand`). The presentational `CopilotProviderConnect` component moved to `@agentskit/desktop-components`.
- Vertical store moved to `@agentskit/desktop-sidecar-bridge` (shared client state): `readVertical`, `writeVertical`, `subscribeVertical` (+ type `VerticalId`).
- Coding-artifact UI (`ArtifactTabs`, `coerceCodingTaskResult`, `formatMs`) moved to `@agentskit/desktop-components` (shared coding-artifact UI).
- Onboarding utility: `openExternal` (opens a URL in the system browser).

## Methods consumed

Via `desktop-sidecar-bridge` (`useApiClient().request`): `agents.list` / `agents.upsert` / `agents.delete` / `agents.transition` / `agents.versions.*` / `agents.applyOverride`, `evals.suites.list`, the `copilot.session.*` / `copilot.config.*` / `copilot.powers.*` IPC family (wrapped in `src/copilot/ipc.ts`), and the coding provider/benchmark/conformance helpers (`fetchCodingProviders`, `runCodingBenchmark`, `runCodingConformance`, …).

## Invariants & gotchas

- **Screen packages must not import each other.** The `desktop-screens-no-sibling` rule in `.dependency-cruiser.cjs` (enforcing ADR-0107) makes any cross-screen import a build error. If you need UI from another screen, move it to `@agentskit/desktop-components`; if you need shared state/data/hooks, get it from `@agentskit/desktop-sidecar-bridge`.
- **Shared UI goes to `desktop-components`, not here.** `CopilotProviderConnect` (the presentational component) was moved to `@agentskit/desktop-components` precisely so other screen packages can render it without depending on this package. Do not re-add sibling imports by adding it back here.
- **`connectCopilotProvider` stays in this package.** Unlike `CopilotProviderConnect`, the `connectCopilotProvider` function (in `src/copilot/copilot-provider-connect.tsx`) depends on copilot onboarding internals (`./onboarding/steps/shared`) and is intentionally not moved to `desktop-components`. It is exported from `src/copilot/index.ts` but not from the top-level `src/index.ts` barrel.
- **All sidecar access is mediated.** This package never imports a runtime directly. All I/O goes through `@agentskit/desktop-sidecar-bridge` via `useApiClient().request(...)`. Coding provider logic lives in `@agentskit/os-coding-agents` and is reached only through `coding.*` sidecar methods.
- **Vertical store is in `desktop-sidecar-bridge`.** `readVertical`, `writeVertical`, `subscribeVertical` are re-exported here from `@agentskit/desktop-sidecar-bridge`; do not add a local copy.

## Common questions

> **How does copilot slash/mention work?**
> `CopilotScreen` implements the slash-command and mention palette from `docs/spec/copilot-slash-mention-palette.md`. Sending a message calls `copilot.session.send` through the `createCopilotIpc` wrapper (`src/copilot/ipc.ts`); the reply arrives as a `copilot.chunk` → `copilot.done` event stream, and the proposal classifier result renders as a `ProposalCard`.

> **Where is the coding-agent provider adapter?**
> Provider logic lives in `@agentskit/os-coding-agents`. `CodingScreen` reaches it only through `coding.*` sidecar methods via `desktop-sidecar-bridge`; it does not import `os-coding-agents` directly.

> **How do I extend the copilot's capability grants?**
> `CopilotPowers` (public export) renders the grantable cap toggles and persists them via `copilot.powers.grant`. The default-forbidden set comes from `@agentskit/os-headless/copilot-defaults` and cannot be granted from the UI.

Source: /raw/for-agents/packages/desktop-agent-workspace.md

### for-agents/packages/desktop-components.md

# packages/desktop-components

## Purpose

`@agentskit/desktop-components` is the shared UI component layer for all `desktop-*` screen packages and both app shells (`apps/desktop` Tauri and `apps/web` browser). It wraps `@agentskit/os-ui` primitives into higher-level desktop-specific composites — none of its shipped surfaces use raw HTML elements (ADR-0036).

Extracted per ADR-0108 (UI module isolation). Depends only on `@agentskit/os-ui`, `@agentskit/os-core`, `@agentskit/os-log`, `@agentskit/desktop-sidecar-bridge`, and React. It **MUST NOT** import from `@agentskit/os-desktop`.

All user-visible strings route through the injected `TFn` (ADR-0037). All colours resolve through `@agentskit/os-whitelabel` tokens (ADR-0038). No hex/rgb literals, no Tailwind arbitrary colour values.

## Relationship to `os-ui`

| Layer | Description |
|---|---|
| `@agentskit/os-ui` | Generic, independently installable primitives: `Button`, `Badge`, `Input`, `Select`, `Modal`, `Combobox`, `EmptyState`, … |
| `@agentskit/desktop-components` | Desktop/web-app-specific composites reused across ≥2 `desktop-*` packages: `EntityToolbar`, `ProviderModelPicker`, `ConnectorPicker`, `InviteTeammateModal`, etc. |

A component belongs here (not `os-ui`) when it is desktop-specific or depends on the sidecar bridge.

## How `desktop-*` screen packages consume this package

Every `desktop-*` screen package (e.g. `desktop-agent-workspace`, `desktop-platform-admin`, `desktop-operations`, `desktop-workflow-builder`) adds this package as a workspace dependency and imports directly from `@agentskit/desktop-components`:

```ts
import { EntityToolbar, FilterPresetsBar, RequireCapability } from '@agentskit/desktop-components'
```

`apps/desktop` (Tauri) and `apps/web` both mount `<DesktopComponentsI18nProvider t={useT()} />` once at the app root — all nested desktop-components receive localised strings through context (IoC pattern, ADR-0108 §IoC).

## i18n wiring

```tsx
// App root (os-desktop or desktop shell)
import { DesktopComponentsI18nProvider } from '@agentskit/desktop-components'

<DesktopComponentsI18nProvider t={useT()}>
  <App />
</DesktopComponentsI18nProvider>
```

Without a provider all user-visible strings fall back to the English fallback embedded in each component — safe for tests and Storybook.

## Public exports

All exports are named (ADR naming: no `export default`).

### i18n context

| Export | Description |
|---|---|
| `DesktopComponentsI18nProvider` | Context provider — wire once at the app root. |
| `DesktopComponentsI18nProviderProps` | Props type for the provider. |
| `TFn` | Signature `(key: string, fallback?: string) => string` — matches `os-desktop`'s `useT()` return. |

### Pure UI primitives

| Export | Description |
|---|---|
| `EntityToolbar` | Unified landing header (search + filters + cards/list toggle + New button). Used by Agents, Workflows, and Processes screens. |
| `EntityToolbarProps`, `EntityToolbarView`, `EntityToolbarFilter`, `EntityToolbarFilterOption`, `EntityToolbarNewItem`, `EntityToolbarActionMenu` | Associated types. |
| `FilterChips` | Horizontal segmented filter group using `aria-pressed` buttons. |
| `FilterPills` | Pill-shaped tab-style filter row; identical role/behaviour to `FilterChips` but distinct visual style. |
| `FilterPillsProps` | Props type for `FilterPills`. |
| `IconSvg` | Thin SVG wrapper (`aria-hidden`, `currentColor` stroke) for inline icon glyphs. |
| `IconSvgProps` | Props type for `IconSvg`. |
| `Markdown` | `react-markdown` + `remark-gfm` renderer with token-compliant styles. |
| `StatusPill` | Inline badge with five semantic tones (`neutral`, `accent`, `success`, `warning`, `danger`). |
| `StatusPillProps`, `StatusTone` | Associated types. |
| `ShortcutHints` | Keyboard legend strip (`⌘K → toggle · ↑↓ → navigate · ↵ → select · Esc → close`). |
| `ShortcutHintsProps` | Props type for `ShortcutHints`. |

### Branded / labelled components

| Export | Description |
|---|---|
| `BrandIcon` | Vendor logo registry (300+ icons: mono-path SVG, inline multi-colour SVG, hosted PNG fallback, monogram fallback). |
| `BrandIconProps` | Props type for `BrandIcon`. |
| `ComboboxMulti` | Multi-select typeahead with chip management, free-text creation (`allowCreate`), grouped options, and keyboard navigation. |
| `ComboboxOption` | Option shape `{ id, label?, description?, group? }`. |
| `ConnectorPicker` | Icon-card grid for integration selection — each card shows status (`configured`, `needs-setup`, `wip`). |
| `connectorIcon` | Helper to get the `BrandIcon`-based icon element by connector id. |
| `ConnectorItem`, `ConnectorPickerProps`, `ConnectorStatus` | Associated types. |
| `CopyShareLinkButton` | Copies a deep-link URL to the clipboard; shows "Copied" for ~1.5 s. |
| `CopyShareLinkButtonProps`, `ShareableScreen` | Associated types. |
| `CopilotProviderConnect` | Links out to Integrations → Providers (single source of truth) instead of duplicating a connect form. Rendered by the Assistant config pane. |
| `CopilotProviderConnectProps` | Props type for `CopilotProviderConnect`. |
| `InviteTeammateModal` | Shared invite form modal (email + role + optional scope). Caller owns the RPC; the modal owns the UI. |
| `InviteTeammateModalProps`, `InviteRole`, `InviteScope` | Associated types. |

### Coding-artifact UI

Shared between the agent-workspace coding screen and the data-infra run-detail
panel (so neither screen package imports the other). Requires
`DesktopComponentsI18nProvider` for localised strings.

| Export | Description |
|---|---|
| `ArtifactTabs` | Tabbed view of a `CodingTaskResult` (files / shell / tools / raw). |
| `FileDiff` | LCS-based syntax-highlighted file diff with bounded preview + expand. |
| `ShellList` | Shell-invocation list with exit codes, stdout/stderr, and durations. |
| `ToolsTimeline` | Ordered tool-use timeline with ok/fail markers. |
| `coerceCodingTaskResult` | Defensive trust-boundary parser → `CodingTaskResult` (drops unknown/garbage). |
| `formatMs` | Formats a millisecond duration (`500ms` / `1.5s` / `1m 15s`). |
| `CodingFileEdit`, `CodingShellInvocation`, `CodingTaskKind`, `CodingTaskResult`, `CodingToolUse` | Coding-result types (re-exported from `desktop-sidecar-bridge`). |

### Hooks

| Export | Description |
|---|---|
| `handleTablistArrowKeys` | WAI-ARIA tablist keyboard nav (Arrow/Home/End move focus + activation across `role="tab"` siblings). |
| `useSaveShortcut` | Attaches `⌘S / Ctrl+S` keyboard handler; `enabled` option disables it without removing the listener. |
| `UseSaveShortcutOptions` | Options type. |
| `useConfirmDialog` | Accessible `window.confirm` replacement — returns `confirm(opts)` opener + `ConfirmDialogElement` the caller renders. |
| `ConfirmDialogOptions`, `UseConfirmDialogReturn` | Associated types. |
| `useSandbox` | Sandbox state + policy hook (`sandbox.state`, `sandbox.policy.get/set`, `sandbox.denials.list`). Polls denials every 1 s. |
| `SandboxLevel`, `SandboxPolicy`, `SandboxState`, `DenialEntry`, `UseSandbox` | Associated types. |

### Error boundary + lazy loading

| Export | Description |
|---|---|
| `LazyBoundary` | Pairs `ErrorBoundary` (from `os-ui`) with `Suspense`. `resetKey` clears stale errors on workspace/tab switch. |
| `LazyBoundaryProps` | Props type. |

### RBAC capability gate

| Export | Description |
|---|---|
| `RequireCapability` | Renders children only when the named capability is allowed (via `useCapability` from `desktop-sidecar-bridge`). Supports `mode: 'disable'` to keep children visible but disabled. |

### Used-by badge

| Export | Description |
|---|---|
| `UsedByBadge` | Deep-link badge: shows "Used in N items"; clicking navigates via `navigateTo`. Neutral when count is 0. |
| `UsedByBadgeProps`, `ScreenId` | Associated types. |

### Form utilities

| Export | Description |
|---|---|
| `StringListEditor` | Editable list of strings (path allow-lists, env-var allow-lists). Add-by-type + remove buttons. |
| `autoGenerateId` | Derives a slug id from a human-readable name: lowercase → trim → spaces/underscores→hyphens → strip non-`[a-z0-9-]` → collapse hyphens. |
| `useAutoId` | Hook wrapping `autoGenerateId`; re-derives on name change. Returns `{ effectiveId, derivedId }`. |
| `resolveEffectiveId` | Resolves the id to submit: locked to `currentId` when editing, else manual override (if non-empty), else derived slug. |
| `IdField` | Shared "slug ID preview + Advanced override disclosure" used by every create/edit form. Shows preview; unlocks the override input via an "Advanced" toggle (hidden in edit mode). |
| `IdFieldProps` | Props type for `IdField`. |

### Picker composites

| Export | Description |
|---|---|
| `ModelCatalogCombobox` | Catalog-backed model picker (5 000+ models via `models.catalog.list` RPC, server-side debounced search). |
| `ModelCatalogComboboxProps`, `ModelSelection` | Associated types. |
| `ProviderModelPicker` | Provider `<Select>` + model field — consolidates 4 previous reimplementations. Shows `NoProvidersNotice` when no providers are connected. |
| `NoProvidersNotice` | Standalone CTA rendered by `ProviderModelPicker` when `providers` is empty; navigates to the Connections screen. |
| `ProviderModelPickerProps`, `ProviderOption` | Associated types. |
| `CatalogCombobox` | Generic catalog-backed typeahead with free-type fallback. Loads options lazily via a `loader` callback. |
| `CatalogComboboxProps`, `CatalogComboboxOption` | Associated types. |
| `FilePathInput` | Native OS file/directory picker (Tauri `@tauri-apps/plugin-dialog`) with `allowManual` web fallback (reveals an `<Input>` disclosure). |
| `FilePathInputProps` | Props type. |

### Shared surfaced components

| Export | Description |
|---|---|
| `OfflineEmptyState` | Renders quiet empty state when sidecar is connected; alert + Reconnect button when disconnected; polite status when reconnecting. |
| `OfflineEmptyStateProps` | Props type. |
| `FilterPresetsBar` | Saves / loads / deletes named filter presets via `useFilterPresets` from `desktop-sidecar-bridge`. |
| `FilterPresetsBarProps` | Props type. |

## Wired stores

None — presentational + hook layer only.

## Common questions

> **When does a new component belong here vs. `os-ui`?**
> `os-ui` holds generic, reusable primitives with no desktop-specific dependencies. `desktop-components` holds composites that are desktop/web-app-specific, depend on `desktop-sidecar-bridge`, or are reused across ≥2 `desktop-*` screen packages.

> **Whitelabel and i18n compliance?**
> All components use `@agentskit/os-whitelabel` tokens (ADR-0038) and route every user-visible string through `useDesktopT()` → `DesktopComponentsI18nProvider` (ADR-0037).

> **How is logging done?**
> Via `createLogger(tag)` from `@agentskit/os-log`. No `console.*` calls.

> **How is `useConfirmDialog` used?**
> ```tsx
> function MyScreen() {
>   const { ConfirmDialogElement, confirm } = useConfirmDialog()
>   return (
>     <>
>       <Button onClick={() => confirm({ message: 'Delete?', onConfirm: doDelete })}>Delete</Button>
>       {ConfirmDialogElement}
>     </>
>   )
> }
> ```

> **How is `LazyBoundary` used?**
> ```tsx
> <LazyBoundary fallback={<PageSkeleton />} resetKey={workspaceId}>
>   <React.lazy(() => import('./HeavyScreen')) />
> </LazyBoundary>
> ```

Source: /raw/for-agents/packages/desktop-components.md

### for-agents/packages/desktop-data-infra.md

# packages/desktop-data-infra

## Purpose

Screens that surface data produced by running workflows — runs, assets, audit ledger, and knowledge RAG sources. Extracted from `@agentskit/os-desktop` per ADR-0108 / pkg-refactor-plan/06-desktop-split.md §W3-sub2-C. Renders inside both `apps/desktop` (Tauri) and `apps/web` (browser) via `@agentskit/desktop-shell`.

All sidecar I/O goes through `@agentskit/desktop-sidecar-bridge` via `useApiClient()` — no direct fetch, no raw IPC. All UI primitives are from `@agentskit/os-ui` (ADR-0036). All user-visible strings use the `useT()` IoC hook (ADR-0037).

## Screens

| Screen | Export | Route | Purpose |
|---|---|---|---|
| Runs | `RunsScreen` | `/runs` | Live run monitor — list, detail drawer (ADR-0124), replay controls, signed export (issue 1355 F4-15), compare view |
| Assets | `AssetsScreen` | `/assets` | Asset gallery — preview, download, bulk-delete, vertical attribution (RFC-0025) |
| Audit ledger | `AuditScreen` | `/audit` | Merkle-chained append-only audit log viewer with actor-type filtering |
| Knowledge | `KnowledgeScreen` | `/knowledge` | Knowledge-source list, per-source embed schedule, indexing status, add/remove/rebuild sources |

### Additional exported components

- `KnowledgeSourcesTab` — embeddable tab used by shell or platform-admin without the full `KnowledgeScreen` scaffold.
- `CodingArtifactPanel` — internal to this package; renders coding diff / file-tree for runs with `kind === 'coding'`.

## How desktop-shell mounts these screens

`desktop-shell`'s `SCREENS_REGISTRY` lazy-imports the four screen exports:

```ts
import { RunsScreen, AssetsScreen, AuditScreen, KnowledgeScreen }
  from '@agentskit/desktop-data-infra'
```

Each is registered under its route key. The shell wraps them in `React.lazy()` + `LazyBoundary` so they code-split cleanly. Screens receive no props — they read all state from sidecar hooks and IoC shims.

## Sidecar wiring

Each screen calls `useApiClient()` from `@agentskit/desktop-sidecar-bridge` and issues JSON-RPC calls to the sidecar. Methods consumed per screen:

| Screen | Sidecar methods |
|---|---|
| Runs | `runs.list`, `runs.detail`, `runner.runFlow`, `audit.signedBatch`, `egress.decisions.list` |
| Assets | `assets.list`, `assets.get`, `assets.delete`, `assets.bulkDelete` |
| Audit | `audit.list`, `audit.signedBatch` |
| Knowledge | `knowledge.sources.list`, `knowledge.status`, `knowledge.sources.add`, `knowledge.sources.remove`, `knowledge.sources.rebuild` |

Live updates are delivered via `subscribeEvents()` from `@agentskit/desktop-sidecar-bridge`:
- **Runs**: `flow.run.*`, `pipeline.run.*`, `trace.started`, `cost.tick` events trigger a debounced refetch or in-place cost patch.
- **Knowledge**: `knowledge.*` events trigger an immediate refetch; a fallback poll runs while any source has `status === 'indexing'`.

## IoC shims — boot-time injection

The host (`os-desktop`'s `DataInfraBridge`) calls these at boot to inject live implementations:

| Register fn | Hook injected | Purpose |
|---|---|---|
| `registerUseT` | `useT()` | i18n translation function (ADR-0037) |
| `registerUseActiveVertical` | `useActiveVertical()` | Active vertical id for run/asset attribution |
| `registerUseOnboarding` | `useOnboarding()` | Onboarding context (step, next, prev, restart) |
| `registerUseRegisterCommand` | `useRegisterCommand()` | Command-palette registration |

Before registration, all hooks return safe no-ops (identity for `useT`, `null` for `useActiveVertical`, noop functions for others). Tests mock these modules directly with `vi.mock`.

## Public exports

| Symbol | Kind | Notes |
|---|---|---|
| `RunsScreen` | React component | Screen mount — lazy-loaded by `desktop-shell` |
| `AssetsScreen` | React component | Screen mount |
| `AuditScreen` | React component | Screen mount |
| `KnowledgeScreen` | React component | Screen mount |
| `KnowledgeSourcesTab` | React component | Embeddable knowledge sources list without page scaffold |
| `coerceRunStatus` | util | Re-exported from `@agentskit/desktop-sidecar-bridge`; normalises raw status to `UiRunStatus` |
| `triggerDownload` | util | Triggers a browser/Tauri file download; used by audit and runs signed-export |
| `registerUseT` | IoC fn | Inject i18n implementation |
| `registerUseActiveVertical` | IoC fn | Inject vertical-id hook |
| `registerUseOnboarding` | IoC fn | Inject onboarding hook |
| `registerUseRegisterCommand` | IoC fn | Inject command-palette hook |
| `UsedByBadge` / `RequireCapability` / `FilterPresetsBar` | React component | Re-exported from `@agentskit/desktop-components` for backwards compatibility |
| `UiRunStatus`, `RunStatus` | types | From `@agentskit/desktop-sidecar-bridge` |
| `SignedBatchResult` | type | From `screens/audit/parts/helpers` |
| `TFn`, `OnboardingContextValue`, `RegisterCommandSpec`, `CommandCategory` | types | Local |
| `ActiveScreen` | type alias | **Deprecated** — use `ScreenId` from `@agentskit/desktop-components` |

## Invariants & gotchas

- **Screen packages must not import each other.** The `desktop-screens-no-sibling` rule in `.dependency-cruiser.cjs` (enforcing ADR-0107) treats any cross-package import among the five DESKTOP_SCREENS as a build error. Shared UI goes to `@agentskit/desktop-components`; shared state/hooks go to `@agentskit/desktop-sidecar-bridge`.
- **`useRunMode` and vertical-store come from `desktop-sidecar-bridge`, not locally.** They are not re-exported from this package's `src/index.ts`. A comment at the bottom of `src/index.ts` explicitly directs consumers to `@agentskit/desktop-sidecar-bridge`. Do not add a local copy.
- **Onboarding contract is the ADR-0146 shim from `desktop-sidecar-bridge`.** `useOnboarding()` is a thin re-export from `@agentskit/desktop-sidecar-bridge` (consolidated per ADR-0146). The contract is `{ active, step, next, prev, finish, skip, restart }`. There is no `isActive` field and no `totalSteps` field — using either will give `undefined` at runtime.
- **IoC shims must not be called in tests.** Use `vi.mock(...)` to replace shim modules (`./whitelabel`, `./onboarding/onboarding-provider`) rather than calling `register*` functions. Calling register functions in tests leaks module-level state across suites.
- **`ActiveScreen` type is deprecated.** Use `ScreenId` from `@agentskit/desktop-components` instead; `ActiveScreen` is kept only for backwards compatibility and will be removed.
- **Node core imports are forbidden in renderer code.** The `renderer-no-node-builtins` dependency-cruiser rule in the root config covers this package's `src/`. These screens run in browser/Tauri webview — no `fs`, `path`, `crypto`, etc.

## Local hooks (not in public API)

These are internal to the package and not exported from `src/index.ts`:

| Hook | File | Purpose |
|---|---|---|
| `useRuns` | `screens/runs/use-runs.ts` | One-shot `runs.list` fetch |
| `useLiveRuns` | `screens/runs/use-runs.ts` | `runs.list` + `subscribeEvents` for the run monitor |
| `useRunDetail` | `screens/runs/use-run-detail.ts` | Enriched `runs.detail` fetch |
| `useAssets` | `screens/assets/use-assets.ts` | `assets.list` with vertical filter |
| `useAssetSelection` | `screens/assets/use-asset-selection.ts` | Multi-select state for bulk operations |
| `useKnowledge` | `screens/knowledge/use-knowledge.ts` | Sources + status + CRUD + live events |
| `useSourceAgentsUsage` | `screens/knowledge/use-source-agents-usage.ts` | Agent→source cross-link (which agents reference which source) |

## Common questions

> **Where does asset download logic live?**
> `screens/assets/asset-download.ts` in this package. Kind-aware — builds the correct download URL or blob for each asset type.

> **How is vertical attribution wired?**
> `AssetsScreen` reads `useActiveVertical()` (injected via `registerUseActiveVertical`) and passes the `verticalId` to `assets.*` queries. The sidecar joins on `FlowConfig.verticals` to attribute runs/assets.

> **Where does the signed runs export live?**
> `screens/runs/parts/run-export.ts` — `requestSignedRunsExport` calls `audit.signedBatch` (reusing the audit signing key), then triggers a download. The pattern mirrors `screens/audit/parts/helpers.ts`.

> **What is `CodingArtifactPanel`?**
> An internal-only component at `screens/coding/coding-artifact-panel.tsx`. Imported by `run-detail-panel.tsx` when `run.kind === 'coding'`. It delegates to `ArtifactTabs` from `@agentskit/desktop-agent-workspace`.

> **How are commands registered into the command palette?**
> Screens call `useRegisterCommand(spec)` (IoC shim). The host calls `registerUseRegisterCommand(impl)` at boot to wire the real palette. Until then, all calls are no-ops — safe for SSR and tests.

> **How do I test a screen that uses IoC shims?**
> Mock the shim modules directly: `vi.mock('../../../whitelabel', () => ({ useT: () => (_k, fb) => fb }))`. Do not call `register*` functions in tests — module-level state would leak across suites.

Source: /raw/for-agents/packages/desktop-data-infra.md

### for-agents/packages/desktop-operations.md

# packages/desktop-operations

## Purpose

Day-to-day operator screens for managing integrations, plugins, notifications, multi-agent topologies, teams, sandbox/tooling, and HITL approvals. Extracted from `@agentskit/os-desktop` per ADR-0108 / pkg-refactor-plan/06-desktop-split.md §W3-sub2-D. Renders inside both `apps/desktop` (Tauri) and `apps/web` (browser) via `desktop-shell`.

## Screens

| Screen | Route | Purpose |
|---|---|---|
| Connections | `/connections` | Inbound/outbound/workspace connectors — LLM providers, OAuth integrations, channels, secrets, SQL, cloud-sync, collab |
| Marketplace | `/marketplace` | Browse, install, update, and remove plugins/connectors |
| Inbox | `/inbox` | HITL queue — tool approvals, escalations, and open tasks |
| Tools | `/tools` | Tool catalogue (MCP servers, calls, egress, sandbox) |
| Sandbox | `/sandbox` | Sandbox policy / state / denials / flow-preview surface |
| Plugins | `/plugins` | Installed-plugin lifecycle (install/enable/disable/uninstall + detail) |
| Topologies | `/topologies` | Multi-agent topology list / upsert / delete / run |
| Teams | `/teams` | Admin surface for users & teams (CRUD, role assign/revoke) |

## Public exports

Screen mounts (consumed by `desktop-shell`'s `SCREENS_REGISTRY`, lazy-imported via `React.lazy()`):
`ConnectionsScreen`, `MarketplaceScreen`, `InboxScreen`, `ToolsScreen`, `SandboxScreen`, `PluginsScreen`, `TopologiesScreen`, `TeamsScreen`.

Sub-views (consumed by `desktop-platform-admin`'s `SecurityScreen`):
`SandboxView`, `EgressView`.

Utility + types:
`resolveMarketplaceTab`, `MarketplaceTab`, `ConnectionsScreenProps`, `MarketplaceScreenProps`.

All exports are named (no default export). See `src/index.ts` for the canonical surface.

## Wired stores / hooks

Sidecar access is via `@agentskit/desktop-sidecar-bridge`: the raw `useApiClient().request(method, args)` RPC client plus typed helpers — e.g. `fetchHitlTasks`, `decideHitl`, `decideToolApproval`, `fetchEscalations`, `decideEscalation`, `startOAuth`, `fetchOAuthConnections`, `fetchOAuthProviders`, `revokeOAuth`, `listIntegrationSetupRegistry`, `listInstallationConnections`, `startInstallationConnection`, `completeInstallationConnection`, `revokeInstallationConnection`, and `openExternal`. Per-screen state lives in local hooks (`useInboxTasks`, `usePluginsScreen`, `useSandboxScreen`, `useTeamsScreen`, `useTopologiesScreen`, `useMarketplaceData`, `useChannels`, etc.).

## Methods consumed

Sidecar RPC namespaces reached via `useApiClient().request(...)` and the bridge helpers: `connections.*`, `integrations.connections.setupRegistry.*`, `integrations.connections.installations.*`, `cloud-sync.*`, `notifications.channels.*`, `secrets.*`, `sql.*`, `marketplace.*` / `plugins.*`, `mcp.*`, `sandbox.*`, `topologies.*`, `users.*`, `teams.*`, `dispatch.refresh`.

## Common questions

> **Where does the OAuth flow live?**
> In the Connections screen's External-integrations pane (`screens/connections/parts/external-pane.tsx`). It loads providers/connections via `fetchOAuthProviders` / `fetchOAuthConnections`, starts a connect via `startOAuth`, and tears one down via `revokeOAuth` — all imported from `@agentskit/desktop-sidecar-bridge`. There is no in-package redirect/`completeOAuth` handler; the sidecar owns the redirect exchange.

> **Where do tenant app installs live?**
> In the same External-integrations pane. `InstallationProviderCard` renders GitHub App and Discord bot installs from `listInstallationConnections`, opens provider install URLs with `startInstallationConnection`, completes a pasted installation/guild id with `completeInstallationConnection`, and revokes via `revokeInstallationConnection`. `InstallationCallbackBridge` also completes GitHub/Discord installs from return-link params (`installation_id` / `guild_id`) in nav params or `window.location.search`. The readiness landing uses real `InstallationTokenStore` rows, not provider-env inference.

> **How should setup cards decide between OAuth, app install, or API key?**
> Read `listIntegrationSetupRegistry` first and render from its `preferredSetupMode`, `setupCta`, scopes, health-check method, docs URL, credential URL, and `assistantInstructions`. Do not hard-code env-first setup copy in the screen: OAuth and tenant app/bot installs are the default tenant-friendly paths, and guided secrets are fallback only when the registry says so.
> Also render/use `implementationStatus`: `real` means the card can be presented as live after health passes; `preflight_only` must be labeled as setup/readiness guidance; `platform_managed` should route to the operator/platform setup path; `dev_env_fallback` is local smoke only; `unsupported` needs a fallback.
> Prefer `provider.guidance.primaryAction` and `provider.guidance.caveat` for the setup card body when present. Those fields keep assistant and UI promises aligned with the registry's implementation status.

> **How is the HITL approval queue wired?**
> `InboxScreen` (`screens/inbox/index.tsx`) drives its data through `useInboxTasks`, which calls `fetchHitlTasks` / `fetchToolApprovals` / `fetchEscalations`. The queue renders in `TasksPanel`, `ApprovalsPanel`, and `EscalationsPanel`. Approving/denying a tool request calls `decideToolApproval(id, approved, note)`; HITL task decisions call `decideHitl`; escalations call `decideEscalation` — all from the sidecar bridge (there is no `inbox.list` / `runs.resume` call).

Source: /raw/for-agents/packages/desktop-operations.md

### for-agents/packages/desktop-platform-admin.md

# packages/desktop-platform-admin

## Purpose

All operator-facing platform-administration screens for AgentsKitOS. Extracted from `@agentskit/os-desktop` per ADR-0108 / pkg-refactor-plan/06-desktop-split.md §W3-sub3. Renders inside both `apps/desktop` (Tauri) and `apps/web` (browser) via `desktop-shell` — one screen codebase, two runtimes.

## Screens

| Screen | Export | Purpose |
|---|---|---|
| Dashboard | `Dashboard` | Live workspace health, run counts, cost summary |
| Observe | `ObserveScreen` | Run-monitor route wrapper; renders the injected Runs screen directly (ADR-0124) |
| Traces | `TracesScreen` | OTEL trace viewer + time-travel replay |
| Observability | `ObservabilityScreen` | Topology, exporters, anomaly rules, incidents |
| Governance | `GovernanceScreen` | RBAC roles, people, workspace rules, emergency access |
| Compliance | `ComplianceScreen` | Compliance export / signed-bundle manifest |
| Security | `SecurityScreen` | Firewall, PII, egress, keyring, agent identity |
| OEM | `OemScreen` | Brand kit, whitelabel, tenants, licensing, marketplace |
| Cost | `CostScreen` | Run cost attribution, budgets, alerts, billing |
| Pipelines | `SdlcScreen` | Multi-workflow pipeline / kanban board (legacy route id `sdlc`) |
| Workspaces | `WorkspaceScreen` | Workspace list, switcher, isolation, cloud sync |
| Break-glass | `BreakGlassScreen` | Emergency access with dual-approval |
| Consent | `ConsentPanel` | User consent records |
| Config | `ConfigEditorScreen` | Workspace-level settings (appearance, copilot, privacy, …) |

## Public exports

Screen mounts (consumers lazy-import these and register them into `desktop-shell`'s `SCREENS_REGISTRY`): `Dashboard`, `ObserveScreen`, `TracesScreen`, `ObservabilityScreen`, `GovernanceScreen`, `ComplianceScreen`, `SecurityScreen`, `OemScreen`, `CostScreen`, `SdlcScreen`, `WorkspaceScreen`, `BreakGlassScreen`, `ConsentPanel`, `ConfigEditorScreen`, plus the `BundlesScreen`, `ExportersTab`, and `OemMarketplacePublishTab` sub-surfaces.

IoC registration hooks the host (`os-desktop`) MUST call at boot so screens render real implementations instead of NOOP fallbacks: `registerRunsScreen`, `registerAuditScreen`, `registerEvalsScreen`, `registerUseT`, `registerUseActiveVertical`, `registerUseVertical`, `registerUseWhitelabel`, `registerUseDispatchContext`, `registerReadBootstrapWhitelabel`, `registerUseFeatureEnabled`, `registerUsePreferences`, `registerUseWorkspaces`, `registerUseOptionalLogPanel`, `registerUseOnboarding`.

Shared utilities and components: `ErrorBoundary`, `LazyBoundary`, `RealModeToggle`, `SecretsPanel`; the keyboard-shortcut registry (`BUILT_IN_SHORTCUTS`, `getBuiltIn`, `getCategories`, `matchesBinding`, `formatBinding`, `buildBindingFromEvent`); the `useTraces` hook; and the preferences schema (`PreferencesSchema`, `DEFAULT_PREFERENCES`, plus the per-field Zod schemas). `FilterPresetsBar`, `OfflineEmptyState`, and `RequireCapability` are re-exported from `@agentskit/desktop-components` for compatibility.

Subpath exports (see `package.json#exports`): `./workspaces/types`, `./workspaces/use-list-workspaces`, `./workspaces/use-workspaces-store`, `./workspaces/workspaces-provider`, `./workspaces/create-workspace-dialog`, `./lib/context-error`.

## Data access

Screens read and write platform state through `@agentskit/desktop-sidecar-bridge` — predominantly `useApiClient().request(method, params)`, with a few module-level helpers (`complianceExport`, `fetchSecurityBundle`, `listConnections`, the `fetchSdlc*` / pipeline helpers, etc.). Methods consumed span the `dashboard.*`, `traces.*`, `governance.*`, `security.*`, `oem.*`, `cost.*`, `pipelines.*`, `workspace.*`, `consent.*`, and `copilot.config.*` namespaces. Whitelabel/i18n (`useT`, `useVertical`, …) come from the local `./whitelabel` shim, which the host wires via the `register*` hooks above.

## Invariants & gotchas

- **Screen packages must not import each other.** The `desktop-screens-no-sibling` rule in `.dependency-cruiser.cjs` (enforcing ADR-0107) makes any cross-screen import a build error. The DESKTOP_SCREENS set is `desktop-operations`, `desktop-agent-workspace`, `desktop-workflow-builder`, `desktop-platform-admin`, and `desktop-data-infra`. Shared UI belongs in `@agentskit/desktop-components`; shared state/data/hooks belong in `@agentskit/desktop-sidecar-bridge`.
- **Node core imports are forbidden in renderer code.** The `renderer-no-node-builtins` dependency-cruiser rule (root `.dependency-cruiser.cjs`) applies to this package's `src/` directory. These screens render in the browser/Tauri webview — importing `fs`, `path`, `crypto`, or other Node builtins will cause a runtime error in the renderer process.
- **All 14 IoC hooks must be registered at boot.** The host (`os-desktop`) must call every `register*` function listed in Public exports before mounting screens. Missing registrations produce silent NOOP fallbacks — the screen renders but with empty data, English-only copy, or missing sub-tabs.
- **`SdlcScreen` is the pipelines surface; the route id is legacy.** The export name `SdlcScreen` and route id `sdlc` are retained per ADR-0048. Do not rename or add an alias — the shell registry key depends on the legacy id.
- **`FilterPresetsBar`, `OfflineEmptyState`, `RequireCapability` are re-exported from `desktop-components`.** They appear in this package's public API for backwards compatibility but are defined in `@agentskit/desktop-components`; changes must be made there.

## Common questions

> **How do I add a new platform-admin screen?**
> Create `src/screens/<name>/index.tsx`, export the component as a named export from `src/index.ts`, and register it in `desktop-shell`'s `SCREENS_REGISTRY`. Fetch data via `useApiClient().request(...)` (never import the runtime directly), resolve all visible copy through `useT`, and add a `docs/for-agents/screens/<name>.md` listing the JSON-RPC methods it touches.

> **Why does my screen render an empty white pane / English-only / NOOP behaviour?**
> The host did not call the matching `register*` IoC hook at boot. Sub-tabs (`registerRunsScreen` / `registerEvalsScreen` / `registerAuditScreen`) and the whitelabel/preferences/workspaces/onboarding/log-panel providers all ship NOOP fallbacks until registered.

> **Why is the pipelines screen exported as `SdlcScreen`?**
> Legacy route id `sdlc` is retained per ADR-0048 even though the surface is now the domain-neutral "Pipelines" workspace.

Source: /raw/for-agents/packages/desktop-platform-admin.md

### for-agents/packages/desktop-shell.md

# packages/desktop-shell

## Purpose

Pure re-export façade that is the single authoritative entry point for the
AgentsKitOS desktop and web shells.  `apps/desktop` (Tauri) and `apps/web`
(browser) both mount the `App` root from this package.  All implementation
lives in `@agentskit/os-desktop`; `desktop-shell` re-exports its public
surface so that consuming apps depend on one stable import path rather than
three distinct `@agentskit/os-desktop/*` sub-paths.

The package contains no screen logic and no stores.  Its only job is:

1. **Composition root** — import `App` from this package to get the fully
   assembled Tauri/web application (AppProviders tree + AppShell layout +
   nav wirers).
2. **Host-capability seam** — export `HostCapabilitiesProvider` and the two
   canonical capability presets (`DESKTOP_HOST_CAPABILITIES` /
   `WEB_HOST_CAPABILITIES`) so each runtime host can declare which native
   affordances are available without ad-hoc `hasTauri()` branches in shared
   screens (ADR-0117 / RFC-0046).
3. **Nav surface** — expose the sidebar contract (`NAV_ITEMS`, `NAV_GROUPS`,
   `OBSERVE_ALIASES`) and nav helpers so consumers can read the route graph
   without a direct dependency on `@agentskit/os-desktop/app-nav`.

Extracted from `@agentskit/os-desktop` per ADR-0108 /
pkg-refactor-plan/06-desktop-split.md §W3-sub4.

## Public exports

All symbols come from `@agentskit/os-desktop` (and its sub-paths).
`desktop-shell` re-exports them unchanged.

### App root

- `App` — root React component.  Mount it in `apps/desktop/src/main.tsx` and
  `apps/web`'s entry.  Composes `AppProviders` + `AppShell` + all command
  palette wirers internally.

### Layout primitives

- `AppShell` — outer layout wrapper (sidebar, top bar, banners, screen
  surface, copilot rail).  Only needed if you mount the shell pieces
  separately; most hosts should use `App` directly.
- `AppProviders` — the full provider tree (theme, workspaces, preferences,
  notifications, command palette, IoC bridges, …).  Only needed if composing
  outside `App`.

### Host-capability seam (ADR-0117 / RFC-0046)

- `HostCapabilitiesProvider` / `HostCapabilitiesProviderProps` — context
  provider.  Wrap `App` with this if you want to declare a non-default
  capability set (required for the web console to suppress Tauri-only UI).
- `useHostCapabilities` — hook used by screens to gate native affordances.
- `DESKTOP_HOST_CAPABILITIES` — preset with every capability `true` (Tauri
  shell).  This is the default context value; no explicit provider needed in
  the Tauri app.
- `WEB_HOST_CAPABILITIES` — preset with every capability `false` (browser
  console).  Pass as `value` to `HostCapabilitiesProvider` in `apps/web`.
- `HostCapabilities` — interface type for the capability object.

### Nav primitives (from `@agentskit/os-desktop/app-nav`)

- `NAV_ITEMS` — `readonly NavItem[]` — ordered list of sidebar entries.  Each
  item has `id: ActiveScreen`, `label`, `icon` (LucideIcon), `group`, optional
  `keywords` and `description`.
- `NAV_GROUPS` — `ReadonlyArray<{ id: NavGroup; label: string }>` — the six
  sections: `home`, `build`, `run`, `workspace`, `govern`, `settings`.
- `OBSERVE_ALIASES` — `Set<ActiveScreen>` — screen ids that are valid
  deep-link targets but not sidebar entries (`runs`, `traces`,
  `observability`).  They open ObserveScreen on the matching tab.
- `isActiveScreen(screen: string): screen is ActiveScreen` — runtime type
  guard; returns `true` for any routable screen id (sidebar items + aliases).
- `labelForScreen(screen: ActiveScreen): string` — display label from
  `NAV_ITEMS`; falls back to the raw id for alias screens.
- `setScreenWithViewTransition(update: () => void): void` — fires a View
  Transitions API transition if supported and `prefers-reduced-motion: no-preference`; otherwise calls `update()` directly.
- `ActiveScreen`, `NavGroup`, `NavItem` — type aliases.

## Wired stores

None.  `desktop-shell` owns no stores.  Stores are wired by `AppProviders`
(which lives in `os-desktop`) via the bridge components it mounts internally.

## Methods implemented

None — pure re-export façade.

## Methods consumed

None directly.  Implementation delegates entirely to `@agentskit/os-desktop`
and its sub-paths.

## Common questions

> **How do I add a new top-level route?**
> Add the screen component to the correct `desktop-*` screen package.  In
> `@agentskit/os-desktop`, register the route in `SCREENS_REGISTRY` (inside
> `app-shell-parts/screens-registry.tsx`) and add the IoC bridge wirer call to
> `AppProviders` if the cluster needs one.  `desktop-shell` itself does not
> need to change — it re-exports `App` which already picks up the new screen.

> **Why do both the Tauri and web shells use the same `App`?**
> All `desktop-*` screen packages are transport-agnostic React.  The only
> runtime difference is the IPC adapter in `desktop-sidecar-bridge` (Tauri
> `invoke` vs. `fetch`) and the capability preset passed to
> `HostCapabilitiesProvider`.  `desktop-shell` is deliberately agnostic to
> both.

> **When should I use `DESKTOP_HOST_CAPABILITIES` vs `WEB_HOST_CAPABILITIES`?**
> `apps/desktop` (Tauri) can omit the provider entirely — the context defaults
> to the full desktop set.  `apps/web` must wrap `App` with
> `<HostCapabilitiesProvider value={WEB_HOST_CAPABILITIES}>` so screens that
> gate on `autoUpdate`, `multiWindow`, etc. hide the unavailable affordances.

> **Why is `HostCapabilitiesProvider` in this package rather than os-desktop?**
> `desktop-shell` is the single import entry point for host apps.  Placing the
> seam here means apps never need to reach into `os-desktop` sub-paths for
> host configuration.

Source: /raw/for-agents/packages/desktop-shell.md

### for-agents/packages/desktop-sidecar-bridge.md

# packages/desktop-sidecar-bridge

## Purpose

L2 binding layer between the React screen packages and the `os-headless` JSON-RPC sidecar. All Tauri IPC calls flow through this package. Screen packages (`desktop-platform-admin`, `desktop-data-infra`, etc.) consume the exported hooks; they never call `invoke()` directly. The web shell swaps in a `fetch`-based adapter transparently.

Extracted from `@agentskit/os-desktop` per pkg-refactor-plan/06-desktop-split.md. **Monorepo-internal — never import from application code outside the `desktop-*` cluster.**

## Public exports

- `sidecarRequest<T>(method, params)` — typed IPC helper with response normalization and error routing via `sidecar-error-toast`.
- `hasTauri()` / `isDevBuild()` — runtime guards; `hasTauri()` is `true` only inside the Tauri shell.
- Connection-health UI + context: `SidecarStateProvider`, `useSidecarState`, `OutboxBanner`, `SidecarStateBanner`.
- Stores (function-pair / context based, not Zustand hooks): `getTheme`/`setTheme`, `getRunMode`/`setRunMode`, `useRunMode` (React hook over the run-mode store, + type `RunModeState`), `SelectionProvider`/`useSelection`/`useSelectionOptional`, plugin-grant store (`persistPluginGrant`/`loadPluginGrant`/`removePluginGrant`/`grantNeedsReconsent`).
- Active-vertical store (localStorage-backed + broadcast; shared so screen packages don't import each other): `readVertical`, `writeVertical`, `subscribeVertical` (+ type `VerticalId`).
- Offline mutation outbox: `enqueueMutation`, `drainOutbox`, `subscribeOutbox`, `registerOutboxSender`, `discardMutation`, `clearOutbox`, `getOutboxEntries`.
- Hooks: `useCapability`, `useFilterPresets`, `useKvBackedState` (Tauri keychain-backed prefs), `useUrlSyncedState`, `useArrowListNav`, `useApiClient`, `useNavParams`, `useSidecarErrorHistory`.
- Per-domain sidecar request wrappers under `src/sidecar/*` (e.g. `fetchSkills`, `fetchCostBreakdown`, `runCodingTask`, `listWorkspaces`, `fetchEvalSuites`, `listInstallationConnections`, `startInstallationConnection`, `completeInstallationConnection`, `revokeInstallationConnection`) — thin async functions over `sidecarRequest`, not reactive hooks.

## Wired stores

`sidecar-state` (connection health), `mutation-outbox` (offline queue), `theme-store`, `run-mode-store`, `selection-store`.

## Methods implemented

None — transport + store layer only.

## Methods consumed

Every `os-headless` JSON-RPC namespace: `flows.*`, `runs.*`, `inbox.*`, `audit.*`, `marketplace.*`, `triggers.*`, `traces.*`, `cost.*`, `observability.*`, `templates.*`, `connections.*`, `integrations.connections.installations.*`, `evals.*`, `knowledge.*`, `copilot.*`, `whitelabel.*`, `oem.*`.

## Common questions

> **How does the web shell connect vs. the Tauri shell?**
> `sidecarRequest` detects `hasTauri()` at runtime. In the Tauri shell it calls `@tauri-apps/api/core` `invoke`; in the web shell it calls a `fetch`-based JSON-RPC client. Both paths validate responses through the same Zod schemas.

> **Why not call sidecar methods directly from screen components?**
> Centralising IPC in this package ensures consistent Zod validation, error routing, and offline-queue behaviour. It also makes the transport swappable without touching any screen code.

Source: /raw/for-agents/packages/desktop-sidecar-bridge.md

### for-agents/packages/desktop-test-setup.md

# packages/desktop-test-setup

## Purpose

Shared jsdom polyfills for the `desktop-*` cluster's vitest suites (ADR-0108). The
desktop screen packages render components that probe browser APIs jsdom does not
implement (`matchMedia`, `ResizeObserver`, `HTMLDialogElement.showModal`, pointer
capture). Each package's `setupFiles` previously carried byte-identical copies of
these stubs; they drifted and tripped the duplicate-block floor (#4073 / #3997,
ADR-0146). This leaf package holds the single canonical copy.

Test-only — never imported by runtime code. The installers are pure side-effect
functions with no test-runner dependency, so any package can call them from its
`setupFiles` regardless of which runner it uses.

## Public exports

Idempotent polyfill installers (ADR naming: no `export default`). Each guards
against double-application and only patches a global when jsdom hasn't already
provided it:

- `installMatchMediaPolyfill()` — stubs `window.matchMedia` (theme/whitelabel
  suites probe `prefers-color-scheme` on mount).
- `installResizeObserverPolyfill()` — stubs `globalThis.ResizeObserver` for
  layout-aware components.
- `installDialogPolyfill()` — adds `showModal` / `show` / `close` to
  `HTMLDialogElement.prototype` and mirrors the `open` attribute.
- `installPointerCapturePolyfill()` — adds pointer-capture methods used by
  drag/pointer interactions.
- `installWindowOpenPolyfill()` — stubs `window.open` so jsdom does not emit
  "Not implemented" noise for tests that assert navigation intent via mocks.
- `installDomTestPolyfills()` — convenience aggregate that runs all installers.

## Wired stores

None — test infrastructure only.

## Methods implemented / consumed

None. No JSON-RPC handlers; not part of the sidecar surface.

## Common questions

> **How do I use it in a package's tests?**
> Call `installDomTestPolyfills()` (or a specific installer) from the package's
> vitest `setupFiles` entry. The installers are idempotent, so calling them in
> multiple setup files is safe.

> **Why a separate package instead of a shared test util file?**
> A leaf package gives every `desktop-*` suite one import path and kills the
> duplicate-block drift the per-package `test-setup.ts` copies caused (ADR-0146).
> Keeping it runtime-free means it never leaks into a shipped bundle.

Source: /raw/for-agents/packages/desktop-test-setup.md

### for-agents/packages/desktop-workflow-builder.md

# packages/desktop-workflow-builder

## Purpose

Visual workflow-authoring screens for the AgentsKitOS desktop/web surfaces — the flow-editor canvas, the flows list, the triggers editor, and the templates wizard. Extracted from `@agentskit/os-desktop` per pkg-refactor-plan/06-desktop-split.md §Package 3. Renders inside both `apps/desktop` (Tauri) and `apps/web` (browser); `@agentskit/os-desktop` still re-exports everything here via migration shims during the one-release window, but direct imports are preferred.

| Screen export | Purpose |
|---|---|
| `FlowsScreen` | Flow list — create, open, duplicate, delete; embeds the editor |
| `FlowEditorScreen` | Canvas DAG editor — nodes, edges, palette, inspector, run trace |
| `TriggersScreen` | Trigger source list + per-kind editor (cron, webhook, file, email, Slack, GitHub, Linear, CDC, Discord, Twilio, Sentry, PagerDuty, Stripe, S3) |
| `TemplatesScreen` | Starter-template wizard (pick → configure → review) |

## Public exports

From the package barrel (`src/index.ts`):

**IoC bridge — wire once at the app root**
- `WorkflowBuilderProviders` — context provider tree (i18n, vertical, workspaces, onboarding, command palette)
- Accessor hooks: `useWfT`, `useWfActiveVertical`, `useWfVertical`, `useWfWorkspaces`, `useWfOnboarding`
- `WfCommandPaletteContext` — React context consumed by `useRegisterCommand`
- Types: `WorkflowBuilderProvidersProps`, `VerticalId`, `VerticalContextValue`, `WorkspacesContextValue`, `OnboardingContextValue`, `CommandPaletteContextValue`, `RegisterCommandSpec`

**Screen mount points**
- `FlowsScreen` / `FlowsScreenProps`
- `TriggersScreen`
- `TemplatesScreen`
- `FlowEditorScreen`

**Flow-editor internals (for standalone embedders)**
- `FlowEditorCanvas` — raw canvas component
- `FlowNodeRendererProps` — node-renderer prop type
- Everything from `./flow-editor/converter` (re-exported via `export *`)

Screens fetch data through hooks/functions from `@agentskit/desktop-sidecar-bridge` (e.g. `fetchTriggerSummaries`, `upsertTrigger`, `toggleTrigger`, `deleteTrigger`, `testFireTrigger`, `fetchFlowTemplates`, `upsertInlineFlow`, `runFlowNow`, `flowFromNL`) — they never call `sidecarRequest` directly. The flow-editor reducer/converters come from `@agentskit/os-flow`.

## Common questions

> **How is a new palette node kind wired?**
> The palette and node renderers are data-driven by `NODE_DESCRIPTORS` in `src/screens/flow-editor/node-descriptors.ts` — a `Record<VisualNodeKind, NodeDescriptor>` keyed off `VisualNodeKind` from `@agentskit/os-flow`. Adding a kind means: declare it in os-flow's `VisualNodeKind`, add its `NodeDescriptor` (label/shape/icon) here, add an inspector panel under `src/screens/flow-editor/inspectors/`, and ensure the runtime handler exists in the engine. The palette (`screen-parts/palette.tsx`) and drop handlers (`screen-parts/palette-drop-handlers.ts`) pick it up automatically.

> **How does trigger editing work?**
> `TriggersScreen` is NOT a dynamic-schema form. Each trigger kind has a typed `Draft` variant (`src/screens/triggers/editor/types.ts`), an initial value from `makeInitialDraft(kind)` (`defaults.ts`), a dedicated form component (`editor/forms/*-forms.tsx`), and a required-field validator in `editor/validators.ts`. The `useTriggerEditor` hook validates the draft, calls `buildTrigger(draft)` to produce a `TriggerConfig`, then persists via `upsertTrigger` from `@agentskit/desktop-sidecar-bridge`. Plain-language schedule presets live in `screens/triggers/cron-presets.ts`; list sentences in `screens/triggers/sentence.ts`.

> **How do I register a command-palette entry from a screen?**
> Call `useRegisterCommand(spec)` (`src/use-register-command.ts`). It reads `WfCommandPaletteContext` injected by `WorkflowBuilderProviders` and no-ops when no palette is mounted (tests, Storybook), registering on mount and unregistering on unmount.

Source: /raw/for-agents/packages/desktop-workflow-builder.md

### for-agents/packages/os-audit.md

# packages/os-audit

## Purpose

Tamper-evident audit ledger for the AgentsKitOS runtime. Builds Merkle
batch chains from an event stream, stores them in SQLite (or in-memory for
tests), and produces Ed25519-signed compliance export bundles. The invariant
is chain continuity: every batch carries the SHA-256 of its predecessor so
gaps are detectable end-to-end.

## Public exports

Root entry (`@agentskit/os-audit`) — browser-safe, no `node:*`:

- Hash primitives: `hashEvent`, `SignedEventRef`
- Batch storage: `InMemoryBatchStore`, `SqliteBatchStore`, `BatchStore` interface,
  `SqliteBatchStoreOptions`, `SqliteDatabase`, `SqliteStatement`
- Emission: `AuditEmitter`, `EmitterOptions`, `Signer`
- Compliance export: `ComplianceExportRequest`, `ComplianceKind`,
  `SubjectIdentifier`, `buildExportBundle`, `signExportBundle`, `sectionsFor`,
  `BuildExportBundleOpts`, `ExportBundle`, `ExportSection`, `ExportSigner`,
  `SectionFetcher`, `SignedExportBundle`
- DSAR erasure (ENT-7 #1716 SU3): `DsarDeletionRequest`,
  `executeDsarDeletion`, `signDeletionProof`, `DeletionExecutor`,
  `DeletionProof`, `DeletionProofEntry`, `DeletionProofSigner`,
  `DeletionSection`, `ExecuteDsarDeletionOpts`, `SignedDeletionProof` — pure
  engine producing a signed deletion-proof receipt; caller
  legal-hold-gates before invoking
- Constants: `PACKAGE_NAME`, `PACKAGE_VERSION`

Sub-paths:

- `@agentskit/os-audit/server` — Node-only: file-backed `BatchStore`, ed25519 signer, Merkle helpers built on `node:crypto`.
- `@agentskit/os-audit/admin` (absorbed from `os-admin-audit`, RFC-0017) — super-admin hash-chained mutation rows for the OEM control plane: `createInMemoryAdminAuditStore`, `AdminAuditStore`, `AuditRow`, `ADMIN_SECTIONS`, `computeChainHash`, `verifyRows`, `sha256OfCanonical`, `ZERO_HASH`.

## Wired stores

`SqliteBatchStore` writes to a SQLite database supplied by the host
(`SqliteBatchStoreOptions.db: SqliteDatabase`). The `AuditEmitter` buffers
in-memory and flushes on call or shutdown. No network IO.

## Methods implemented / consumed

Implemented (via `os-headless/src/audit-ledger-handlers.ts`):

- `audit.batchHash` — compute canonical SHA-256 digest of a batch
- `audit.signedBatch` — sign a batch with the workspace Ed25519 audit key (cap `audit:admin`)
- `audit.verifyIntegrity` — verify a signed batch against a supplied public key
- `audit.entries.list` — list ledger entries filtered by actor, kind, or time range
- `audit.entries.verify` — walk the full signed chain; report `brokenAt` seq on first mismatch

Also owns select `integrations.*` audit sub-methods declared in `os-contracts/src/methods/integrations.ts`.

Consumed: none.

## Common questions

> **How do I add a new event kind?**
> Call `auditEmitter.ingest(event)` with a well-formed `AnyEvent` (from
> `@agentskit/os-core`). The emitter hashes the entry and appends it to the
> active batch. No central registry change is needed — event `type` values
> are free-form strings in the schema.

> **How does chain continuity work?**
> Each `AuditBatch` carries a `prevBatchHash` pointing to the preceding
> batch's `signedDigest`. `audit.entries.verify` (via `verifyChain` from
> `@agentskit/os-core`) walks the full chain and returns the first
> `brokenAt` entry on hash or signature mismatch so operators can
> pinpoint tampering without scanning the whole log.

> **Where does the Ed25519 audit signing key come from / how is it rotated?**
> See [`docs/security/audit-signing-key-management.md`](../../security/audit-signing-key-management.md) — the canonical doc for provisioning, storage, and rotation of the workspace audit signing key.

> **When should I use `InMemoryBatchStore` vs `SqliteBatchStore`?**
> Use `InMemoryBatchStore` in tests and ephemeral sidecar runs where
> persistence across restarts is not required. Wire `SqliteBatchStore` in
> `os-headless/src/bin/sidecar.ts` for any deployment that needs durable
> chain history.

Source: /raw/for-agents/packages/os-audit.md

### for-agents/packages/os-blob-s3.md

# packages/os-blob-s3

## Purpose

AWS S3 `BlobStore` adapter. Implements the `BlobStore` port from `@agentskit/os-core` using `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`. Works with any S3-compatible endpoint (AWS S3, MinIO, Cloudflare R2, etc.). Vendor-isolated: `@aws-sdk/*` is imported only by this package (enforced by `pnpm check:vendor-isolation`). Closes RFC-0025 follow-up #2541 (presigned-URL support).

Stability: **internal** (L2 binding). Distribution: cloud/enterprise. Epic: ef-02 SU2.3 (#2973, parent #2939/#2936).

## Public exports

- `createS3BlobStore(opts: S3BlobStoreOpts)` → `BlobStore`.

```ts
// from packages/os-blob-s3/src/s3-store.ts
interface S3Credentials {
  accessKeyId: string
  secretAccessKey: string
  sessionToken?: string
}

interface S3BlobStoreOpts {
  bucket: string
  region: string           // required — e.g. 'us-east-1'
  endpoint?: string        // custom endpoint for S3-compatible stores
  credentials?: S3Credentials  // omit to use AWS SDK credential chain
}
```

All `BlobStore` methods delegate to S3:
- `put` → `PutObjectCommand`; user metadata serialised with `x-amz-meta-usr-` prefix.
- `get` → `GetObjectCommand`; streams body as Web `ReadableStream<Uint8Array>`.
- `delete` → `DeleteObjectCommand`; prefixed with `HeadObjectCommand` to assert key exists; throws `AK_BLOB_NOT_FOUND` if absent.
- `list` → `ListObjectsV2Command`; paginates via `cursor`/`limit` in `BlobListOpts`.
- `presignGet` / `presignPut` → `getSignedUrl` from `@aws-sdk/s3-request-presigner`; TTL clamped to [1, 604800] seconds by the port schema.

Every key must be tenant-scoped `<orgId>/<path>` — asserted on every operation; throws `AK_BLOB_INVALID_KEY` otherwise.

## Wired stores

None. `S3BlobStore` is injected into `apps/cloud` composition root as the `blobStore` dep for production deployments.

## Methods implemented

Not a JSON-RPC surface. See [`os-blob`](./os-blob.md) for the port contract.

## Methods consumed

- AWS S3 REST API (or S3-compatible). No other AgentsKit package imports `@aws-sdk`.

## Common questions

> **How do I use a local MinIO stack in dev?**
> Pass `endpoint: 'http://localhost:9000'` and any non-empty `credentials` (e.g. `accessKeyId: 'minioadmin'`, `secretAccessKey: 'minioadmin'`). MinIO does not require `forcePathStyle` — the SDK defaults work.

> **Are presigned URLs TTL-enforced?**
> TTL is enforced by S3 / the compatible endpoint. The port schema clamps to 604800 s (7 days). `LocalFsDriver` in `os-blob` does not enforce TTL — swap to S3 for production.

> **How is metadata round-tripped?**
> `BlobMeta` fields are written as `x-amz-meta-usr-<key>` headers and read back from `HeadObjectCommand`. The `x-amz-meta-usr-` prefix isolates user metadata from AWS system headers.

## Error codes

- `AK_BLOB_INVALID_KEY` — key missing `<orgId>/` prefix; thrown synchronously before any S3 call.
- `AK_BLOB_NOT_FOUND` — `NoSuchKey` / `NotFound` from S3 (on `get` or `delete`).
- `AK_BLOB_PROVIDER_UNAVAILABLE` — any other S3 SDK error (network, auth, server-side) on `put`, `get`, `delete`, `list`, `presignGet`, or `presignPut`.

## Tests

`packages/os-blob-s3/tests/s3-store.test.ts`.

Source: /raw/for-agents/packages/os-blob-s3.md

### for-agents/packages/os-blob.md

# packages/os-blob

## Purpose

`BlobStore` port re-export + `LocalFsDriver` for desktop/dev use. Re-exports the `BlobStore` port contract, Zod schemas, and error codes from `@agentskit/os-core` so consumers depend only on this package without a separate `os-core` import. Provides the `LocalFsDriver` for development and desktop use (keys map to `<rootDir>/<orgId>/...` on disk). Production cloud use wires `@agentskit/os-blob-s3` instead.

Stability: **alpha** (port + dev driver). Distribution: desktop + cloud. Epic: ef-02 SU2.3 (#2973, parent #2939/#2936).

## Public exports

Port types and schemas (re-exported from `@agentskit/os-core`):
- `BlobKey`, `BlobListing`, `BlobListEntry`, `BlobListOpts`, `BlobMeta`, `BlobPresignTtlSec`, `BLOB_ERROR_CODES` — Zod schemas / constants.
- `BlobBody`, `BlobErrorCode`, `BlobGetResult`, `BlobStore` — TypeScript types.

LocalFs adapter:
- `createLocalFsBlobStore(opts: LocalFsBlobStoreOpts)` → `BlobStore` — filesystem-backed store for desktop/dev.

```ts
// from packages/os-blob/src/local-fs.ts
interface LocalFsBlobStoreOpts {
  rootDir: string   // absolute path; created on first write
}
```

`BlobStore` port surface:
```ts
interface BlobStore {
  put(key: BlobKey, body: BlobBody, meta?: BlobMeta): Promise<void>
  get(key: BlobKey): Promise<BlobGetResult>
  delete(key: BlobKey): Promise<void>
  list(prefix: string, opts?: BlobListOpts): Promise<BlobListing>
  presignGet(key: BlobKey, ttlSec: BlobPresignTtlSec): Promise<string>
  presignPut(key: BlobKey, ttlSec: BlobPresignTtlSec, meta?: BlobMeta): Promise<string>
}
```

Key constraint: every `BlobKey` must be tenant-scoped as `<orgId>/<path>`. The driver asserts this and throws `AK_BLOB_INVALID_KEY` otherwise.

`presignGet`/`presignPut` return `file://` URLs in `LocalFsDriver` — no auth, no expiry enforcement. Use `@agentskit/os-blob-s3` for real presigned URLs.

## Wired stores

None — the `LocalFsBlobStore` writes to disk. Injected into sidecar / desktop composition root as the `blobStore` dependency.

## Methods implemented

Not a JSON-RPC surface. The `BlobStore` is consumed by `os-rag` (asset artifacts), `os-pdf`, and `apps/desktop` run-artifact storage.

## Methods consumed

Node.js `fs/promises` (no external vendor SDK).

## Common questions

> **When should I use `os-blob` vs `os-blob-s3`?**
> `os-blob` ships the `LocalFsDriver` — use it for desktop or dev. Wire `os-blob-s3` in production cloud where presigned S3 URLs are needed.

> **Why is tenant-key scoping enforced here and not in the port?**
> Defense-in-depth: the driver is the last line before disk writes. The port contract documents the convention; the driver asserts it at runtime so a misconfigured caller cannot write outside tenant boundaries.

## Error codes

`BLOB_ERROR_CODES` (from `@agentskit/os-core`):

- `AK_BLOB_INVALID_KEY` — key missing `<orgId>/` prefix (tenant-isolation violation).
- `AK_BLOB_NOT_FOUND` — `get` or `delete` on a non-existent key; also thrown when `rm` fails during `delete`.
- `AK_BLOB_FORBIDDEN` — caller lacks permission (adapter-level; not thrown by LocalFsDriver).
- `AK_BLOB_QUOTA` — storage quota exceeded (adapter-level; not thrown by LocalFsDriver).
- `AK_BLOB_PROVIDER_UNAVAILABLE` — backend unreachable (adapter-level; not thrown by LocalFsDriver).

## Tests

`packages/os-blob/tests/local-fs.test.ts` — happy-path round-trips, pagination, presign, cross-tenant rejection.
`packages/os-blob/tests/local-fs-coverage.test.ts` — branch/edge coverage: stream cancel, missing meta sidecar, recursive directory walk, delete failure path, meta persistence.

Source: /raw/for-agents/packages/os-blob.md

### for-agents/packages/os-bot-signal.md

# packages/os-bot-signal

## Purpose

Pluggable port for bot detection + IP-reputation signals, with a built-in no-op
adapter. Defines the hexagonal seam (`BotSignalPort`) so consumers — the web lead
route, the egress enforcer, runtime abuse checks — can gain abuse signals later by
dropping in a real vendor adapter, without taking a vendor dependency today. Ships
ONLY the port contract + a deterministic no-op adapter (returns benign defaults):
no network, no credential, no behavioral change. Architectural context:
[ADR-0135](../../adr/0135-bot-signal-port.md). Issue: #3776 (epic #3773).

Stability: **alpha**. Distribution: internal.

## Public exports

### Port contract

- `BotSignalPort` — the hexagonal port:
  ```ts
  interface BotSignalPort {
    ipReputation(ip: string): Promise<IpSignal>
    botCheck(req: { ip: string; userAgent?: string; headers?: Record<string, string> }): Promise<BotVerdict>
  }
  ```
- `IpSignal` / `IpSignalSchema` — Zod schema + type:
  ```ts
  interface IpSignal {
    ip: string
    reputation: 'clean' | 'suspicious' | 'malicious' | 'unknown'
    isVpn?: boolean; isTor?: boolean; isProxy?: boolean; isDatacenter?: boolean
    asn?: string; country?: string
  }
  ```
- `BotVerdict` / `BotVerdictSchema` — Zod schema + type:
  ```ts
  interface BotVerdict { isBot: boolean; confidence: number; category?: 'search' | 'monitor' | 'automated' | 'unknown' }
  ```
- `IpReputationSchema`, `BotCategorySchema`, `BotCheckRequestSchema` — boundary Zod schemas for the value types.

### No-op adapter

- `createNoopBotSignalAdapter()` → `BotSignalPort` — pure, deterministic, no network.
  `ipReputation(ip)` echoes the ip with `reputation: 'unknown'`; `botCheck()` returns
  `{ isBot: false, confidence: 0, category: 'unknown' }`. Use as the default injected
  dependency until a real adapter is wired.

### Package metadata

- `PACKAGE_NAME` (`'@agentskit/os-bot-signal'`), `PACKAGE_VERSION`.

## Wired stores

None. Pure port + no-op adapter. A future vendor adapter would own its own
client/credential state inside its own `os-*` package (vendor isolation).

## Methods implemented

Not a JSON-RPC surface. `BotSignalPort` is an injected dependency, not a dispatch
method.

## Methods consumed

None. The no-op adapter makes no calls. A future vendor adapter would call its
provider's HTTP API from within its own package.

## Common questions

> **Why ship a port with only a no-op adapter?**
> AKOS has no bot/IP-intelligence today and building a data network or buying a
> vendor is a separate decision (ADR-0135). Shipping the seam now lets consumers
> integrate the contract with zero behavioral change; a real adapter plugs in later
> without touching call sites.

> **How does a future vendor adapter plug in?**
> Implement `BotSignalPort` in a new dedicated `os-*` package (e.g. an IPinfo/
> AbuseIPDB adapter) and inject it where the no-op is wired. Vendor SDKs/credentials
> stay isolated in that package — never in consumers (ADR-0014 vendor isolation).

> **How should consumers treat `'unknown'` / `isBot: false`?**
> As pass-through (benign). The no-op never blocks; consumers must not hard-fail on
> `'unknown'` reputation, so swapping in a real adapter only ever *adds* signal.

## Error codes

- `AK_VALIDATION_FAILED` — raised by the boundary `parse` helper when an input/output
  fails its Zod schema.

## Tests

`packages/os-bot-signal/tests/port.test.ts`, `packages/os-bot-signal/tests/noop-adapter.test.ts`.

Source: /raw/for-agents/packages/os-bot-signal.md

### for-agents/packages/os-capabilities.md

# packages/os-capabilities

## Purpose

`@agentskit/os-capabilities` is the deterministic foundation of the Adaptive
Ecosystem Onboarding layer. It introduces an **abstract capability** concept
that sits above concrete tools, vendors and connections, so packs and natural
language requests can depend on a capability (e.g. `team_communication`) instead
of a specific vendor (e.g. Slack). The onboarding layer then resolves each
capability to whatever tool the company already uses.

It owns schemas and pure logic only — no persistence, RPC or I/O. Higher layers
(storage, headless handlers, copilot) consume it. An LLM may *propose* mappings,
but it can only reference capabilities/vendors that exist in this catalog; the
resolver fails closed (explicit pending state) rather than fabricating.

## Public exports

- `INITIAL_CAPABILITY_CATALOG` — the 10 MVP capabilities (llm_generation,
  team_communication, work_tracking, knowledge_base, code_repository, approval,
  notification, file_storage, crm, observability) with vendor equivalences.
- `getCapability`, `capabilityVendorIds`, `buildVendorEquivalenceIndex` — catalog
  helpers. The equivalence index maps a vendor id → the capabilities it satisfies.
- `resolveCapability(input)` — pure resolver returning a `CapabilityResolution`
  discriminated union: `resolved | needs_connection | needs_user_choice |
  unavailable`. `needs_connection` may carry an optional `setup` object; pure
  resolution does not fetch setup metadata, but headless onboarding handlers
  enrich it from the integration setup registry.
- `resolveConfidenceAction` / `scoreForMatchKind` — confidence thresholds with
  risk tiers (low / elevated / critical). Critical never auto-resolves.
- `EcosystemProfile` — per-workspace ecosystem translation (terminology, tools,
  processes, llm preferences, hitl policy, constraints). Secrets are never stored
  — only refs.
- `ReadinessReport` — consolidated apply/run gate with findings that each carry a
  correction route.
- `AdaptedWorkspaceBlueprint` — the reviewable, reversible apply artifact, stamped
  with `schemaVersion` + `capabilityCatalogVersion`.
- `ProvenanceEntry` / `Sourced` — provenance for every adapted value.
- `SCHEMA_VERSION`, `CAPABILITY_CATALOG_VERSION`.

## Common questions

> **How do I map "the company needs messaging" to their actual tool?**
> Call `resolveCapability({ capability, connectedVendorIds, preferredVendorIds })`.
> With one matching connection it auto-resolves; with several it returns
> `needs_user_choice`; with none it returns `needs_connection` (pointing at a
> setup route and, when enriched by `os-headless`, a `setup` object with the
> provider id, setup mode, CTA/action, caveat, and docs/credential links); when
> nothing can satisfy it, `unavailable` with fallbacks.

> **Why is there no `capability` field on the catalog entries?**
> `capability` already means "credential shape" on `ProviderCatalogEntry` in
> os-runtime. Capability identity here uses `id`/`kind` to avoid the clash.

> **Where does the EcosystemProfile get persisted?**
> Not here. This package is schema-only. Persistence is a workspace-tier store
> (os-storage) plus a `workspace.config.ecosystemProfile.*` RPC, added in a later
> phase.

Source: /raw/for-agents/packages/os-capabilities.md

### for-agents/packages/os-cdc.md

# packages/os-cdc

## Purpose

Change-data-capture (CDC) subsystem extracted from `os-headless` (ADR-0119). Owns
the database CDC ingestion path: the MySQL (GTID) and Postgres (LSN) trigger
adapters that poll a caller-supplied row-change `pull` fn and dispatch each change
to a flow, the durable watermark stores that let a daemon resume from its last
cursor after a restart, and the optional-peer pull builders for `@vlasky/zongji`
(MySQL binlog) and `pg-logical-replication`/wal2json (Postgres WAL).

It depends only on `@agentskit/os-log` (and `zod`) — no runtime, no transport, and
critically **no dependency back on `os-headless`**. The runner is dependency-injected
through the minimal structural `CdcFlowRunner` interface defined here, so there is no
cycle. The `trigger-daemons-bootstrap` wiring and any RPC surface stay in
`@agentskit/os-headless`, which injects the real `HeadlessRunner` (it structurally
satisfies `CdcFlowRunner`).

## Public exports

**Runner contract** (`cdc-flow-runner.ts`):
- `CdcFlowRunner` — structural interface with a single `runFlow(flow, { mode: 'real', input, runId? }) => Promise<unknown>` method. This is the seam that keeps os-cdc independent of os-headless.

**Watermark stores** (`cdc-gtid-watermark-store.ts`, `cdc-lsn-watermark-store.ts`):
- `GtidWatermarkStore`, `LsnWatermarkStore` — `get(slot)` / `set(slot, cursor)` durable cursor contracts
- `createFileGtidWatermarkStore(path)` / `createFileLsnWatermarkStore(path)` — JSON file-backed stores (resume after restart)
- `createInMemoryGtidWatermarkStore()` / `createInMemoryLsnWatermarkStore()` — non-durable variants

**MySQL CDC** (`mysql-cdc-trigger.ts`, `mysql-cdc-pull.ts`):
- `MysqlChangeEvent`, `MysqlChangeKind`, `MysqlBinlogPullFn` — event + pull-fn contracts
- `createMysqlCdcAdapter(opts)` → `MysqlCdcAdapter` — GTID-cursor poll/dispatch loop (`MysqlCdcAdapterOpts`)
- `bootMysqlCdcDaemon(opts)` → `MysqlCdcDaemonHandle` — composes a watermark store + adapter into a started lifecycle handle (`BootMysqlCdcDaemonOpts`)
- `mysqlCdcSlot()` — default replication-slot id from `AKOS_MYSQL_CDC_SLOT`
- `createMysqlCdcPull(config, Ctor?, importer?)` / `buildMysqlCdcPullFromEnv(importer?, env?)` / `importZongjiPeer(importer?)` / `mapRow(kind, database, table, gtid, committedAt, row)` — `@vlasky/zongji` binlog pull builder (`MysqlCdcPull`, `MysqlCdcPullConfig`)
- Env vars consumed by `buildMysqlCdcPullFromEnv`: `AKOS_MYSQL_CDC_URL` (required, format `mysql://user:pass@host:port/`), `AKOS_MYSQL_CDC_DATABASES` (comma-separated allowlist), `AKOS_MYSQL_CDC_TABLES` (comma-separated allowlist), `AKOS_MYSQL_CDC_SERVER_ID` (replica server id, default 1001)

**Postgres CDC** (`postgres-cdc-trigger.ts`, `postgres-cdc-pull.ts`):
- `PostgresChangeEvent`, `PostgresChangeKind`, `PostgresPullFn` — event + pull-fn contracts
- `createPostgresCdcAdapter(opts)` → `PostgresCdcAdapter` — LSN-cursor poll/dispatch loop (`PostgresCdcAdapterOpts`)
- `createPostgresCdcPull(...)` / `importLrPeer(importer)` / `mapWal2JsonMessage(...)` — `pg-logical-replication`/wal2json pull builder (`PostgresCdcPull`, `PostgresCdcPullConfig`)

## Common questions

> **Why doesn't os-cdc import `HeadlessRunner` from os-headless?**
> os-cdc was extracted *out of* os-headless. Importing the runner type back would be an
> upward dependency and reintroduce a cycle (the very thing ADR-0119 removes). The
> adapters only ever call `runFlow(flowId, { mode: 'real', input: { change } })` and
> ignore the result, so os-cdc defines a minimal structural `CdcFlowRunner` instead.
> The real `HeadlessRunner` (whose `runFlow` returns a `WorkspaceRunResult`, assignable
> to `unknown`) structurally satisfies it, so `trigger-daemons-bootstrap` passes the
> real runner with no change. `check:layers` proves the no-cycle property.

> **How does a CDC daemon resume after a restart?**
> Each adapter tracks a cursor — a GTID set (MySQL) or an LSN (Postgres) — and calls
> `onCursorAdvanced(cursor)` after every consumed event (dispatched *and* filtered-out,
> since a filtered row is still consumed). Wire that callback to a `*WatermarkStore.set`
> and seed the adapter's `initialGtid`/`initialLsn` from `*WatermarkStore.get` at boot.
> The file-backed stores persist the cursor to disk so the next boot resumes exactly
> where the last one stopped, never re-pulling already-seen rows.

> **Where did the `trigger-daemons-bootstrap` wiring go?**
> It stays in `@agentskit/os-headless` — it composes CDC with the email/S3 pollers and
> needs the real runner and env wiring. It now imports `bootMysqlCdcDaemon`,
> `createPostgresCdcAdapter`, the pull builders, and the watermark-store factories from
> `@agentskit/os-cdc`. Only the CDC primitives moved; the bootstrap orchestration did not.

Source: /raw/for-agents/packages/os-cdc.md

### for-agents/packages/os-cli.md

# packages/os-cli

## Purpose

Terminal entry point for operators and CI pipelines interacting with
AgentsKitOS workspaces. Implements the verb surface defined in ADR-0017
and extended by RFC-0040. The primary binary is `akos`; `agentskit-os`
is a registered alias. Commands are rendered with Ink; IO is injected
via `CliIo` so the router is testable without spawning a TTY.

The registry is sharded under `src/commands/_registry/`:
- `core.ts` — full production command set (see below).
- `auth.ts` — `auth login|logout|status` (device-code OAuth, S1).
- `chat.ts`, `tail.ts`, `gap-fill.ts`, `dx.ts` — auxiliary shards.

**Current command surface** (as of RFC-0040 completeness wave):

*Workspace lifecycle:* `init`, `init-ci`, `wizard`, `new`, `import`,
`seed`, `migrate-to-cloud`, `doctor`, `status`, `version`.

*Run + flows:* `run`, `runs list|show|watch|cancel|retry|logs|artifacts`,
`runs retention-prune`, `explain-run`, `flows list|show|validate|run|edit`,
`flow new`, `flow export`, `flow import-json`.

*Agents + copilot:* `agents list|show|run`, `agent register|list|promote`,
`agent from-nl`, `agent compare`, `agent bump|diff|version-list|changelog`,
`chat` (interactive, with `--tui` for full Ink TUI mode), `chat sessions`,
`chat show|cancel|delete`.

*Cockpits (terminal UI, streaming):* `tools list|show`, `connectors`,
`knowledge`, `rag`, `security`, `costs`, `observability`,
`audit list|show|export|verify`, `inbox list|show|approve|reject`,
`runs` cockpit.

*Cost cockpit:* `costs list` (itemised cost rows), `costs alerts` (budget alerts).

*Observability cockpit:* `obs anomaly-rules` (→ `observability.anomalyRules.list`).

*Copilot cockpit:* `copilot slash`, `copilot mention`, `copilot proactive <eventJson>`
(slash/mention parsing + proactive cards via the sidecar —
`copilot.proactive.fromEvent`). See
[`docs/copilot/slash-commands.md`](../../copilot/slash-commands.md) for the
in-app slash-command surface these mirror.

*HITL cockpit:* `hitl dead-letter` (escalations dead-lettered by a decision-SLA
timeout, ADR-0070), `hitl ledger`.

*Triggers cockpit:* `triggers contracts` (trigger contract inspection).

*Runs cockpit:* `runs get <id>` (single run row via `runs.get`; null/exit 5 when
missing).

*Connections cockpit:* `connections sql-get <id>` (read a single SQL connection,
ADR-0062 / #3804).

*Marketplace cockpit:* `marketplace featured`, `marketplace suggestions`,
`marketplace report`, `marketplace private-library`, `marketplace publisher-keys`,
`marketplace installed`, `marketplace fetch`, `marketplace apply-monitoring-pack`,
`marketplace apply-security-pack` (curated/official packs + audited apply —
ADR-0052/0054; #3805 / D5).

*Config + secrets:* `config validate|explain|diff|migrate|get|set|edit`,
`creds`, `vault`, `secrets`, `lock`, `sync`, `whatif`.

*Deploy + ops:* `deploy`, `publish`, `install`, `workspaces list|use|clone|create|delete`,
`snapshot create|restore|schedule|retention`, `telemetry`, `completion`.

*Coding agents:* `coding-agent benchmark|conformance|delegate|smoke`,
`dev issue-pr`, `dev worktree`.

*Compliance:* `compliance export|legal-hold|delete`, `hitl`,
`trigger-preset`, `triggers`, `mcp-discover`, `docs-export`.

Non-TTY hardening: every command checks for an interactive terminal and
exits with a non-zero code or falls back to JSON output when stdout is
not a TTY. Streaming (ADR-0133 polling) is used for long-running cockpit
commands.

## Public exports

- `route` — command router; `route(argv, io?)` maps a CLI arg list (the
  tokens *after* the binary name, e.g. `['runs', 'show', 'r1']`) to the
  correct `CliCommand` handler and returns its `CliExit`
- `COMMANDS` — `readonly CliCommand[]` array of all registered `CliCommand`
  descriptors (assembled from the `_registry/` shards in `registry.ts`)
- `CLI_VERSION` — semver string of the installed CLI (from `commands/version.ts`)
- `CliCommand`, `CliExit`, `CliIo` — core types for building custom command handlers
- `createCommandContext` — factory for `CommandContext` (workspace path, env, io)
- `CommandContext` — type passed to every command handler
- `auth login` — device-code OAuth: mints a (deviceCode, userCode) pair via `auth.device.start`, prints the verification URI + userCode to stderr, polls `auth.device.poll` until granted, persists the bearer token via `FileTokenStore` (CLI-S1b #3192).
- `auth logout` — revokes and deletes the stored bearer token (CLI-S1b #3192).
- `auth status` — prints active identity + tenant from the persisted token; exit 1 if not logged in (CLI-S1b #3192).
- `whoami` — prints user + tenant + capability summary; planned (CLI-S1c #3167).
- `tenant list` — lists tenants accessible to the current identity (CLI-S1c #3167).
- `tenant use <id>` — switches the active tenant only for local/self-host sessions; hosted/cloud tenant switching must be server-side (CLI-S1c #3167).
- `compliance legal-hold place|release|list` — manage litigation
  preservation holds in the local SQLite store; enforced by the
  os-core deletion guard before retention/DSAR erase (ENT-7 #1716).
- `runs prune --max-age-days <n> [--workspace] [--confirm]`
  — delete run history older than N days; dry-run by default;
  skips workspaces under an active legal hold (ENT-7 #1716 SU2).
- `compliance delete --subject <kind:value> --workspace <id> [--confirm]`
  — DSAR erasure of a subject's consent grants; refuses (exit 4)
  under an active legal hold; writes a signed deletion-proof under
  `.agentskitos/compliance-deletions/` (ENT-7 #1716 SU3).

## Invariants & gotchas

- **`process.stdout.write` / `process.stderr.write` are the correct CLI output channels.** CLI commands produce human-readable output via `CliIo` (which wraps `process.stdout`/`process.stderr`). Using `createLogger` here would be wrong — that logger is for library/library-internal diagnostics. The existing `process.stdout.write` calls are not a `no-console` violation.
- **Routing is exact two-token-then-one-token match — no prefix expansion.** `route` in `src/router.ts` first tries the joined two-token key (`"runs show"`), then falls back to the single-token key (`"version"`). There is no prefix or fuzzy matching; an unrecognised command immediately returns exit code **2** with a `suggestCommands` "Did you mean?" block.
- **Exit codes are a stable operator contract.** From `src/lib/exit-codes.ts`: 0=OK, 1=RUNTIME (generic error), 2=USAGE (unknown command / bad flags / bad config), 3=pre-flight/I-O-read failure, 4=conflict, 5=NOT_FOUND, 6=governance gate, 7=missing credentials (reserved), 8=registry entry not found, 9=state mismatch, 10=LOCKFILE_DRIFT. CI scripts branch on these — never renumber them.
- **The CLI holds no stores.** All persistence is delegated to `os-headless` via the sidecar JSON-RPC channel. The CLI is a pure dispatch layer; adding local state here violates that invariant.
- **Commands must be registered in a `_registry/` shard.** A new `CliCommand` file under `src/commands/` is invisible to `route` until it is imported and spread into `COMMANDS` via the appropriate shard (`src/commands/_registry/*.ts` → `src/commands/registry.ts`).

## Wired stores

None. The CLI delegates persistence to `os-headless` via the sidecar IPC
channel. The CLI itself holds no stores.

## Methods implemented / consumed

None — CLI layer only. Commands invoke the sidecar JSON-RPC surface via
`os-headless` transport rather than implementing methods directly.

## Common questions

> **How do I provision an integration connection headless? (Route-correction A3, #3485)**
> `src/commands/connections.ts` exposes `connections list|get|set|rm` — thin
> shims over `integrations.connections.{list,get,upsert,delete}` (ADR-0041).
> `connections set` never takes a plaintext token: auth references a vault key
> (`--secret-id <key>` ⇒ auth type `secret`) or `--no-auth`, so the operator
> stores the secret first with `agentskit-os vault put`. The same pattern as
> `vault put → secrets.set` — no raw JSON-RPC required. Tests:
> `tests/commands-connections.test.ts`.

> **How do I add a new CLI command?**
> Create `src/commands/<verb>.ts` exporting a `CliCommand` object with
> `name`, `description`, `run(ctx, args)`, then import and register it
> in the appropriate shard under `src/commands/_registry/`. The shard
> is spread into `COMMANDS` via `src/commands/registry.ts`. Mirror
> `src/commands/auth/login.ts` for the pattern (CLI-S1b).

> **How is the command context injected in tests?**
> Call `createCommandContext({ cwd, env, io })` with a mock `CliIo`
> (stdout/stderr as `WritableStream`). Pass the result directly to
> `command.run()` — no global state is touched.

> **How does `route` resolve a command name?**
> `route` matches on exact command names only — there is no prefix
> expansion. It first tries the two-token name (`"runs show"`), then the
> single-token name (`"version"`); the longer exact match therefore wins
> for multi-word verbs. `--help`/`-h`, `--version`/`-v`, and `__complete`
> are handled up front. An unrecognised command returns a `CliExit` with
> code `2` and a "did you mean?" block of the closest matches (see
> `suggestCommands` in `catalog.ts`). Tests: `tests/router.test.ts`.

Source: /raw/for-agents/packages/os-cli.md

### for-agents/packages/os-cloud-sync.md

# packages/os-cloud-sync

## Purpose

Share-link generation, deterministic sync-delta computation, enterprise
deployment manifest verification, vault-backed sync client, and a
WebSocket bidir replication client. Provides read-only views over cloud-sync
machinery in `os-core` plus a `VaultSyncClient` that AES-256-GCM-encrypts
snapshots locally before shipping to the hosted vault (server never sees
plaintext). The invariant is that all sync transitions are validated through
`isSyncTransitionAllowed` before any state mutation occurs.

## Public exports

- Share links (re-exported from `os-core`): `buildShareLink`, `evaluateShareLink`,
  `ShareLink`, `ShareLinkInput`, `ShareLinkScope`, `ShareLinkVerdict`
- Share bundles: `ShareBundleRequest`, `ShareEndpointMissingError`, `ShareScope`,
  `buildShareBundle`, `evaluateShare`, `ShareBundle`, `ShareBundleOpts`, `ShareVerdict`
- Sync state machine (re-exported from `os-core`): `computeSyncDelta`,
  `isSyncTransitionAllowed`, `transitionSyncState`, `SyncDelta`, `SyncState`,
  `SyncTransition`
- Enterprise manifests (re-exported): `parseEnterpriseDeployment`,
  `verifyEnterpriseDeployment`, `EnterpriseDeployment`, `EnterpriseDeploymentMode`
- Vault client: `VaultSyncClient`, `deriveVaultKey`
  - Methods: `sync(plaintext, parentHash?)`, `restore(snapshotId)`,
    `getHead()`, `getHistory(limit?)`, `restoreHead(snapshotId)`
  - Types: `VaultHistoryEntry`, `VaultSnapshotRef`, `VaultAuthError`,
    `VaultConflictError`, `VaultIntegrityError`, `VaultNetworkError`,
    `VaultSyncClientOpts`, `VaultSyncResult`
- WebSocket replication client (`ef-04 SU4.1`): `createSyncWsClient`,
  `createNodeWsConstructor`
  - Types: `SyncWsClient`, `SyncWsClientOpts`, `SyncWsClientHandlers`,
    `WsLikeInstance`, `WsConstructor`
- Replication protocol Zod schemas: `SYNC_ERROR_CODES`, `ClientFrameSchema`,
  `ServerFrameSchema`, `SyncOpSchema`, `SyncHelloFrameSchema`,
  `SyncPushFrameSchema`, `SyncAckFrameSchema`, `SyncWelcomeFrameSchema`,
  `SyncBroadcastFrameSchema`, `SyncErrorFrameSchema`
  - Types: `SyncOp`, `SyncHelloFrame`, `SyncPushFrame`, `SyncAckFrame`,
    `SyncWelcomeFrame`, `SyncBroadcastFrame`, `SyncErrorFrame`,
    `ClientFrame`, `ServerFrame`, `SyncJwtClaims`
- Cloud control-plane config store: `CloudConfigRow` (Zod schema + type),
  `InMemoryCloudConfigStore`, `resolveCloudStatus`
  - Types: `CloudConfigStore`, `CloudStatus`, `CloudStatusDeps`
- Types (re-exported from `os-core`): `CloudPlan`, `CloudSyncConfig`, `RbacRole`, `TeamSeat`
- Constant: `SYNC_STATES`; helper `allowedSyncTransitionsFrom(state)` —
  derives valid next states (for UI button enable/disable)

## Sub-path exports

- `@agentskit/os-cloud-sync/sync/delta` — low-level JSON-Patch delta engine:
  `computeSyncDelta(from, to)` → `{ fromHash, toHash, ops }` (distinct from the
  state-machine `computeSyncDelta` re-exported from the package root)
- `@agentskit/os-cloud-sync/sync/replication-protocol` — Zod frame schemas only
- `@agentskit/os-cloud-sync/sync/ws-client` — WS client only

## Wired stores

None locally. Team membership and enterprise manifest persistence live in
`os-headless` per the migration map (`docs/audit/sidecar-migration-map.md`).
`VaultSyncClient` talks to the hosted vault over HTTPS; no local SQLite.
`InMemoryCloudConfigStore` is available for tests; embedders that need
durability supply a custom `CloudConfigStore` implementation.

## Methods implemented / consumed

Implemented (owner `@agentskit/os-cloud-sync` in `os-contracts`):

- `sync.delta` — compute deterministic JSON-Patch delta + canonical SHA-256 hashes
- `share.create` — build a share-link bundle with scope and expiry

Also owns `share-status.*` sub-methods in `os-contracts/src/methods/share-status.ts`.

Operator-facing cloud-sync status surface (`cloud-sync.*`, declared in
`os-contracts/src/methods/cloud-sync-status.ts`; handlers owned by
`@agentskit/os-headless`). These are now **persistent** (#3781 / #3783) — backed
by `CloudSyncStore` in `os-storage` (in-memory for tests, SQLite in prod)
instead of a closure-local variable, so state and history **survive a sidecar
restart**:

- `cloud-sync.status` — current state (`idle | syncing | paused | error`),
  `lastSyncedAt`, `pendingConflicts`, `lastError`; cap `runs:read`.
- `cloud-sync.pause` — pause the sync loop (paused state persists across
  restart); cap `workspace:config`.
- `cloud-sync.resume` — resume the sync loop; cap `workspace:config`.
- `cloud-sync.history` — recent sync events, **persisted + paginated**: returns
  `{ entries, nextCursor }` where each entry is
  `{ id, timestamp, kind, outcome }` and `kind ∈ sync | pause | resume |
  conflict-resolved`. Params accept `cap` (1–500, `limit` is a back-compat
  alias) + an opaque `cursor`; cap `runs:read`.
- `cloud-sync.conflicts.list` / `cloud-sync.conflicts.resolve` — list pending
  sync conflicts and resolve one by picking `local` or `remote`.

Consumed: `os-core` for state-machine primitives and schema types.

## Common questions

> **How does `buildShareBundle` differ from `buildShareLink`?**
> `buildShareLink` (from `os-core`) produces a signed URL token only.
> `buildShareBundle` packages the artifact payload + link + metadata into a
> `ShareBundle` that can be stored or forwarded independently of the original
> workspace.

> **What triggers a `VaultConflictError`?**
> The vault compares the client's `parentHash` against its current HEAD. If
> another push landed between your last pull and your push, the server returns
> a 409 and throws `VaultConflictError` with `currentHash` set to the server's
> current HEAD hash. Resolve by pulling the latest snapshot via `restore()`,
> merging locally, and calling `sync()` again with the new `parentHash`.

> **How do I verify an enterprise deployment manifest?**
> Call `verifyEnterpriseDeployment(manifest, { publicKeyPem })`. The function
> checks the Ed25519 signature embedded in the manifest and returns
> `{ ok: true } | { ok: false, reason }`. The public key is embedded at
> compile time (ADR-0047) — do not load it from a remote source at runtime.

> **How do I use the WebSocket replication client in Node.js?**
> Import `createSyncWsClient` and `createNodeWsConstructor`, then pass the
> adapted constructor: `createSyncWsClient(opts, handlers)` where
> `opts.wsConstructor = createNodeWsConstructor(WebSocket)` (with `WebSocket`
> from the `ws` npm package). The client handles automatic reconnection using
> the last-acked cursor (`SyncHelloFrame.cursor`) to replay missed ops.

Source: /raw/for-agents/packages/os-cloud-sync.md

### for-agents/packages/os-coding-agents.md

# packages/os-coding-agents

## Purpose

Coding-agent provider abstraction. Wraps external CLIs (claude-code, codex, cursor, gemini, aider, opencode, continue) and an HTTP provider (openrouter) behind a single `CodingAgentProvider` shape so the SDLC orchestrator can swap engines.

## Public exports

- `createClaudeCodeProvider` / `createCodexProvider` / `createCursorProvider` / `createGeminiProvider` / `createAiderProvider` / `createOpenCodeProvider` / `createContinueProvider` / `createOpenRouterProvider` — per-CLI factories.
- `createBuiltinCodingAgentProvider(id)` + `BUILTIN_CODING_AGENT_IDS` + `isBuiltinCodingAgentId` — id-keyed lookup.
- `createSubprocessRunner` / `defaultRun` / `defaultWhich` — exec injection points (replaced in tests).
- `parseAgentJsonResult` / `fanOutStreamingFromResult` — JSON envelope + streaming fan-out helpers.
- `loadSecretsEnvFromFile` / `parseSecretsEnvFileLines` — `.env`-style secret loaders for sandboxed invocations.
- `sha256OfFile` / `verifyBinaryAttestation` — binary attestation guard (rejects unsigned CLI binaries when policy demands).

## Wired stores

None. Stateless wrapper over subprocess + filesystem.

## Methods implemented

None directly. Providers are consumed by `os-dev-orchestrator` and exposed through `coding.invoke` / `coding.runTask` JSON-RPC in `os-headless`.

## Methods consumed

- `SubprocessRunner.run` — invokes the underlying CLI binary.
- `SubprocessRunner.which` — resolves binary path before invoke.

## Common questions

> **How do I add a new CLI provider?**
> Add `src/<id>.ts` exporting `create<Name>Provider(opts: CliCodingAgentProviderOptions)`. Register in `builtin.ts` and append to `BUILTIN_CODING_AGENT_IDS`. Ship attestation hash if binary is signed.

> **Why are subprocess + which injected?**
> Tests run hermetically — fake `RunFn` returns canned JSON without touching `$PATH`.

> **Where does binary-attestation gate?**
> `verifyBinaryAttestation` checks `sha256OfFile(binaryPath)` against the pinned attestation map; mismatch → `AttestationVerdict.rejected` and the provider refuses to invoke.

Source: /raw/for-agents/packages/os-coding-agents.md

### for-agents/packages/os-collab.md

# packages/os-collab

## Purpose

Team seats, RBAC policy evaluation, real-time presence, and CRDT document
sync primitives for multi-user workspaces. Phase 1 covers seats and RBAC;
CRDT co-edit (Yjs adapter + gateway) is present in the package but
flagged for M8 per ADR-0023. The invariant is that seat limits are enforced
before any invite is accepted via `SeatTracker`.

## Public exports

- Team seats: `TeamRole`, `TeamSeat`, `createTeamRegistry`, `TeamRegistry`
- RBAC: `can`, `evaluateCapability`, `CollabCapability`, `CapabilityVerdict`
- Presence: `createPresenceRegistry`, `Cursor`, `PresenceEntry`, `PresenceRegistry`
- CRDT document: `createSyncDocument`, `DocOp`, `DocSnapshot`, `SyncDocument`
- CRDT binding: `createSyncBinding`, `replayOps`, `BindingOpts`, `RemoteOpListener`, `SyncBinding`
- CRDT gateway: `createSyncGateway`, `ClientId`, `ClientSend`, `RoomId`,
  `RoomMember`, `RoomState`, `SyncGateway`
- Yjs adapter: `wrapYjsDocument`, `YJS_OP_PATH`, `MinimalYDoc`, `WrapYjsOpts`,
  `YjsBinding`, `YjsCodec`
- Seat enforcement: `SeatLimitExceededError`, `createSeatTracker`, `SeatEnforcement`,
  `SeatEvent`, `SeatListener`, `SeatTracker`, `SeatTrackerOpts`
- Constants: `PACKAGE_NAME`

## Wired stores

No local stores. Team seat persistence lives in `os-storage` (`TeamsStore`,
`UsersStore`) and is wired by `os-headless/src/users-teams-handlers.ts`.

## Methods implemented / consumed

Implemented (owner `@agentskit/os-collab` in `os-contracts/src/methods/collab.ts`):

- `team.list` — list team seats for the active workspace
- `team.invite` — invite a user at a given role
- `team.remove` — remove a user from the team
- `team.evaluateCapability` — check whether a role holds a set of capabilities

Consumed: `os-storage` for `TeamsStore` + `UsersStore`.

## Common questions

> **How do I check whether a user can perform an action?**
> Call `can(role, capability)` for a single capability check, or
> `evaluateCapability(role, capabilities)` to batch-check multiple. Both are
> pure functions — no IO.

> **What happens when the seat limit is exceeded?**
> `SeatTracker.addUser()` throws `SeatLimitExceededError` (`.code === 'SEAT_LIMIT_EXCEEDED'`)
> before the invite is persisted. The `team.invite` handler catches this and
> surfaces the rejection to the caller.

> **When will CRDT co-edit be enabled?**
> The `createSyncGateway` and Yjs adapter are exported but gated behind
> feature flag `collab.crdt` (M8, ADR-0023). Do not wire them in production
> until the flag ships — the gateway has no persistence backend yet.

Source: /raw/for-agents/packages/os-collab.md

### for-agents/packages/os-command-palette.md

# packages/os-command-palette

## Purpose

Cmd+K universal command-palette backend (M13 / #1132), extracted from
`os-headless` per ADR-0119 cohesion remediation. Builds a ranked search
registry over every entity in the system — flows, agents, triggers, runs,
traces, integrations, knowledge sources, secrets — plus a static command
catalogue (Navigate / Create / Run / Manage / Help). The desktop palette calls
`cmdk.search({ query })` and gets back ranked, dispatch-tagged hits.

Pure backend: searchers + scoring + a handler factory. No UI, no transport. It
depends only on `@agentskit/os-contracts` (the `HandlerMap` type + `cmdk.*`
method contracts) and `@agentskit/os-storage` (the entity stores it searches).
The headless sidecar wires the handler map into its dispatcher.

## Public exports

- `createCmdkHandlers(opts?: CmdkHandlersOptions): HandlerMap` — builds the
  `cmdk.search` and `cmdk.commands.list` handlers over the supplied stores +
  static command catalogue.
- `CmdkHandlersOptions` — the (all-optional) store bag: `flowStore`,
  `agentStore`, `triggerStore`, `runStore`, `traceStore`, `knowledgeStore`,
  `secretStore`, `mcpStore` (note: `mcpStore`, not `mcpServersStore`). Omitted
  stores are simply skipped at search time (the palette degrades gracefully).
  Additional options: `workspaceId` (defaults to `'default'`),
  `staticCommands` (override the built-in catalogue), `recencyHalfLifeMs`
  (half-life for recency decay in ms, defaults to 24 h), `now` (injectable
  clock — useful in tests to pin recency calculations).
- Types: `CmdkKind`, `CmdkResult`, `StaticCommand`.
- `cmdk.commands.list` handler — returns `{ commands: StaticCommand[] }`, the
  full static command catalogue without any search or filtering.

Internal modules (not re-exported, imported relatively within the package):
`cmdk/searchers.ts` (per-entity searchers), `cmdk/scoring.ts`
(`tokenize`/`matchScore`/`recencyBoost` ranking), `cmdk/static-commands.ts`
(the `STATIC_COMMANDS` catalogue), `cmdk/types.ts`.

## Common questions

> **How do I wire the palette into a runner?**
> Call `createCmdkHandlers({ flowStore, agentStore, ... })` with whatever
> stores you have and spread the returned `HandlerMap` into your dispatcher's
> handler map. `os-headless` does exactly this in its composition root. Pass
> only the stores you want searchable; missing ones are skipped, not errors.

> **How are results ranked?**
> `cmdk/scoring.ts` tokenizes the query, scores each candidate by token match
> (`matchScore`) and applies a recency boost (`recencyBoost`) so recently
> touched entities float up. Static commands are matched by label/keyword via
> `searchStaticCommands`. The handler merges and sorts all hits before
> returning `CmdkResult[]`.

> **Why is this its own package and not in os-headless?**
> A command-palette search registry is a self-contained domain (pure searchers
> + scoring over stores), not part of the headless runner's wiring. Extracting
> it (ADR-0119) shrinks the os-headless god-package and lets the palette be
> consumed or tested independently. Its public surface is the `cmdk.*` handler
> map, so the extraction did not change os-headless's RPC contract.

Source: /raw/for-agents/packages/os-command-palette.md

### for-agents/packages/os-connectors.md

# @agentskit/os-connectors

> **Status:** alpha — L2 binding layer (ADR-0064 Phase 2)

## Purpose

Concrete `ConnectionSender` adapters for outbound messaging. Each adapter implements the `ConnectionSender` seam defined in `@agentskit/os-core` and owns only its transport. Connection resolution, egress gating, idempotency, and signed audit live in the `os-headless` dispatch seam — not here.

## Package info

| Field | Value |
|-------|-------|
| npm name | `@agentskit/os-connectors` |
| stability | alpha |
| layer | L2 binding (ADR-0064) |
| peer deps | `@agentskit/os-core`, `zod ^4` |

## Public exports

```ts
// Factory — creates all registered senders from a single config object
createConnectorSenders(opts: ConnectorSendersOptions)

// Slack
createSlackConnectionSender(opts: SlackSenderOptions)
secretRefResolver          // resolves $env: / vault: secret refs
SLACK_POST_MESSAGE         // action kind constant

// GitHub
createGitHubConnectionSender(opts: GitHubSenderOptions)
GITHUB_CREATE_COMMENT

// Webhook
createWebhookConnectionSender(opts: WebhookSenderOptions)
WEBHOOK_POST

// Discord
createDiscordConnectionSender(opts: DiscordSenderOptions)
DISCORD_SEND

// Email (transactional-email HTTP API, fetch-based — no nodemailer)
createEmailConnectionSender(opts: EmailSenderOptions)
EMAIL_SEND
emailConfigFromEnv()       // reads AKOS_SMTP_* env vars
parseRecipients(raw)       // comma-split + normalise addresses

// Linear
createLinearConnectionSender(opts: LinearSenderOptions)
LINEAR_ISSUE_CREATE
```

## Supported transports

| Adapter | Kind constant | Notes |
|---------|--------------|-------|
| Slack | `SLACK_POST_MESSAGE` | OAuth bot token |
| GitHub | `GITHUB_CREATE_COMMENT` | PAT or GitHub App |
| Webhook | `WEBHOOK_POST` | HMAC-signed optional |
| Discord | `DISCORD_SEND` | Bot token |
| Email | `EMAIL_SEND` | transactional-email HTTP API (`AKOS_SMTP_*`, fetch-based) |
| Linear | `LINEAR_ISSUE_CREATE` | API key |

## Per-sender config reference

All senders accept only an optional `fetchImpl` for test injection; runtime
credentials are never passed at construction time — they are resolved lazily
from the connection's `auth` secret ref at send time via `ctx.resolveSecret`.

**Slack** (`SlackSenderOptions`)
- `message.target` — `{ channel: string }` (Slack channel ID, 1–256 chars)
- `message.payload` — `{ text: string (1–40 000 chars), threadTs?: string }` (optional thread reply)
- `connection.auth` — `{ type: 'secret', secretId: string }` resolving to a bot token

**GitHub** (`GitHubSenderOptions`)
- `message.target` — `{ owner: string, repo: string, issueNumber: number }` (posts to issue or PR)
- `message.payload` — `{ body: string (1–65 536 chars) }`
- `connection.auth` — `{ type: 'secret', secretId: string }` resolving to a PAT or GitHub App token
- `externalId` returned — stable thread key `owner/repo#number` (not the created comment id)

**Webhook** (`WebhookSenderOptions`)
- `message.target` — `{ url: string }` (any HTTPS URL, max 2 048 chars)
- `message.payload` — arbitrary JSON object; POSTed as-is
- `connection.auth` — optional `{ type: 'secret', secretId: string }`; if present resolves to a
  Bearer token added to the `Authorization` header; many webhook URLs embed the secret in the URL
  so auth is optional

**Discord** (`DiscordSenderOptions`)
- `message.target` — `{ channelId: string }` (Discord channel snowflake, max 64 chars)
- `message.payload` — `{ content: string (1–2 000 chars) }` (Discord hard cap)
- `connection.auth` — `{ type: 'secret', secretId: string }` resolving to a bot token

**Email** (`EmailSenderOptions`)
- `message.target` — `{ to: string }` (single RFC-5321 address, max 320 chars)
- `message.payload` — `{ subject: string (1–998 chars), text: string (1–100 000 chars) }`
- Provider config (URL / API key / from address) comes from `EmailChannelConfig`, defaulting to
  `emailConfigFromEnv()` which reads `AKOS_SMTP_URL`, `AKOS_SMTP_API_KEY`, `AKOS_SMTP_FROM`,
  `AKOS_SMTP_TO`; no per-message `connection.auth` secret is used
- Targets a transactional HTTP API (Resend / Mailgun / SendGrid-style) over `fetch`

**Linear** (`LinearSenderOptions`)
- `message.target` — `{ teamId: string }` (Linear team ID, max 128 chars)
- `message.payload` — `{ title: string (1–512 chars), description: string (1–100 000 chars) }`
- `connection.auth` — `{ type: 'secret', secretId: string }` resolving to a Linear API key
  (sent bare, without a `Bearer` prefix)
- `externalId` returned — Linear issue identifier (e.g. `ENG-42`)

## Wiring into headless

```ts
import { createConnectorSenders } from '@agentskit/os-connectors'

const senders = createConnectorSenders({ /* per-transport config */ })
// Pass `senders` to os-headless DefaultHandlersOpts.connectionSenders
```

`ConnectorSendersOptions.fetchImpl` accepts an egress-guarded fetch; when the
dispatch seam wires the senders it passes its own SSRF-filtered fetch so all
connector HTTP is bound to the workspace egress policy.

## Common questions

> **How are credentials stored and resolved at send time?**
> Every sender that requires a credential expects `connection.auth` to be a
> `{ type: 'secret', secretId: string }` reference — never a raw token. The
> dispatch seam passes a `resolveSecret` function (backed by the vault /
> `os-storage` secret store) into `ConnectionSenderContext`. The connector
> calls `ctx.resolveSecret(authRef)` at send time; the token is never
> logged and is redacted by the audit seam. The exported `secretRefResolver`
> helper wraps a `{ get(key): Promise<{ value }|undefined> }` store into the
> same contract for use outside the dispatch seam.

> **What do the `AK_CONNECTOR_*` error codes mean and which failures are retried?**
> Each sender returns an `OutgoingDispatchResult` with a `retryable` flag;
> retry scheduling lives in the dispatch seam, not here. The codes are:
>
> | Code | Meaning | `retryable` |
> |------|---------|-------------|
> | `AK_CONNECTOR_AUTH_MISSING` | Secret ref resolved to nothing (missing vault entry) | `false` |
> | `AK_CONNECTOR_NOT_CONFIGURED` | Provider config absent (e.g. no `AKOS_SMTP_*` env vars) | `false` |
> | `AK_CONNECTOR_TRANSPORT` | Network-level error (fetch threw) | `true` |
> | `AK_CONNECTOR_HTTP` | Non-2xx HTTP (generic, e.g. Slack) | `true` for 429 / 5xx, `false` for 4xx |
> | `AK_CONNECTOR_SLACK` | Slack API-level `ok: false` | `true` for `ratelimited` / `internal_error` only |
> | `AK_CONNECTOR_GITHUB` | GitHub non-201 (with API message) | `true` for 403 / 429 / 5xx |
> | `AK_CONNECTOR_DISCORD` | Discord non-2xx | `true` for 429 / 5xx |
> | `AK_CONNECTOR_EMAIL` | Email provider non-2xx | `true` for 429 / 5xx |
> | `AK_CONNECTOR_WEBHOOK` | Webhook target non-2xx | `true` for 429 / 5xx |
> | `AK_CONNECTOR_LINEAR` | Linear GraphQL or HTTP error | `true` for 429 / 5xx; `false` for GraphQL `success: false` |

> **How does the `$env:` / `vault:` secret-ref syntax map to what connectors use?**
> Connectors receive a resolved `resolveSecret` function injected by the dispatch
> seam — they never parse `$env:` or `vault:` prefixes themselves. The seam
> interprets connection `auth` objects: `{ type: 'secret', secretId }` refs where
> `secretId` beginning with `$env:` are resolved from the process environment,
> and those beginning with `vault:` are fetched from the vault store. The
> `secretRefResolver` export handles the `{ type: 'secret', secretId }` shape
> and can be backed by any store that implements `get(key): Promise<{ value }|undefined>`.

Source: /raw/for-agents/packages/os-connectors.md

### for-agents/packages/os-contracts.md

# packages/os-contracts

## Purpose

Zod-validated JSON-RPC method contracts. Single source of truth for
`capsRequired` (RBAC), `idempotent` (cache), `stability` (semver), and
`sideEffectTier` (agent-visible operation risk).
Every handler in `os-headless` must have a matching contract here
(`check:contract-coverage` enforces).

## Public exports

Registry:

- `defineMethod({method, params, result, ...})` — single method contract factory.
- `defineRegistry(...)` / `buildRegistry(...)` — assemble a `ContractRegistry`.
- `methodRegistry` — assembled registry of every registered method.
- `REGISTRY` — alias of `methodRegistry` (flat map, keyed by method name).
- `getContract(name)`, `listContractNames()`, `filterBySurface(surface)` — registry lookups.
- `parseInput` / `parseOutput` (throw on invalid) and `safeParseInput` / `safeParseOutput` (return result object) — boundary validation.
- Types: `AnyMethodContract`, `MethodContract`, `ContractRegistry`, `ContractInput`, `ContractOutput`, `ContractError`, `Stability`, `Surface`.

Dispatch + client:

- `dispatch(registry, handlers, request, ctx)` — validate input → run handler → validate output. The verified `ctx` is threaded to the handler as its optional 2nd arg (`Handler(input, ctx?)`); it is the only trustworthy caller identity. Handlers that record an actor (audit ledger) MUST read it from `ctx.caller`, never from `input` (SEC-3 / #1666).
- Types: `Handler`, `HandlerMap`, `DispatchCaller`, `DispatchContext`, `DispatchOptions`, `DispatchResult`, `DispatchSuccess`, `DispatchFailure`.
- `createClient(transport)` — typed JSON-RPC client; types `ClientTransport`, `RegistryClient`.
- `ErrorEnvelope` — Zod schema for the JSON-RPC error wire shape.

Method contracts:

- Per-noun files re-exported from `methods/` (each exports `*Params`/`*Result` Zod schemas + the `defineMethod` instance). Inline-flow + roles + harness + agents-import + skills contracts re-exported from `methods/integrations.js`.

## Wired stores

None. Pure contract definitions.

## Methods implemented / consumed

444 method contracts (count = `Object.keys(REGISTRY).length`). Indexed by noun:

- `workspace.*`, `flows.*`, `triggers.*`, `runs.*`, `traces.*`
- `agents.*`, `copilot.*`, `hitl.*`, `marketplace.*`, `sdlc.*`
- `access.breakGlass*`, `rbac.*`, `evals.*`, `users.*`, `teams.*`
- `cmdk.*`, `runtime.status`, `dashboard.stats`, `cost.*`
- `observability.*`, `security.*`, `sandbox.*`, `egress.*`
- `oauth.*`, `connections.*`, `secrets.*`, `security.keyring.*`, `kv.*`
- `bundles.*`, `oem.*`, `whitelabel.*`, `coding.*`, `cloud.*`
- `health.ping`, `lifecycle.dispose`

## Common questions

> **My method 404s in the desktop — what gives?**
> Check that the method has both a handler (in `os-headless/src/`)
> AND a contract (in `os-contracts/src/methods/`).
> `pnpm check:contract-coverage` reports asymmetry. It runs in the
> `structural-gates` CI job (GRD-1, #1671), so an uncontracted handler —
> which `wrapHandlersWithRbac` cannot gate, i.e. unauthenticated
> regardless of role — fails the build. The two `ALLOWLIST_*` escape
> hatches in the script are ratcheted (`MAX_ALLOWLIST_*`): they may only
> shrink. Close the gap and lower the cap; never raise it.

> **How does RBAC know what cap my method needs?**
> `capsRequired` on the `defineMethod` call. `wrapHandlersWithRbac`
> reads `REGISTRY[method].capsRequired` at request time.

> **Can I add an idempotent: true method?**
> Yes, mark `idempotent: true` on `defineMethod`. The transport layer
> uses this to enable retry-on-network-error.

> **When should I set `sideEffectTier`?**
> Set it explicitly whenever a mutating method name does not end in a standard
> verb such as `.create`, `.update`, or `.delete`. Explicit metadata wins over
> legacy name inference in `os-for-agents`; an unclassified legacy method is
> treated as `destructive`, never `read`.

Source: /raw/for-agents/packages/os-contracts.md

### for-agents/packages/os-control-plane.md

# packages/os-control-plane

> **Status: shipped** (RFC-0054 F1–F6 + security primitives). Pure decision core for the Unified Control Plane. Types/schemas live in `os-contracts`; this package holds the resolvers + policies. Every export is a pure function over injected IO — no stores, no crypto, no clock of its own.

## Purpose

Resolve a single canonical `ControlPlaneContext` for every surface (web, desktop, CLI, admin, sidecar, service), reconciling identity + membership + tenant + license + entitlement + RBAC + distribution into one server-authoritative object. Cloud runs it authoritatively online; the desktop sidecar runs the **same** code offline against the license cache. This is the anti-fragmentation core of RFC-0054.

## Public exports

Root entry (`@agentskit/os-control-plane`), all pure:

**Context + entitlement**
- `assembleControlPlaneContext` — top-level assembler producing a schema-valid `ControlPlaneContext`
- `resolveEffectiveEntitlement` — license + cloud + seat reconciliation, precedence ladder (revoked > suspended > distributionMode > cloud > license/cache > unknown→free) (ADR-0158)
- `resolveLicenseEntitlement` / `resolveCloudEntitlement` — offline (os-license) + online adapters
- `derivePolicy` — login / cloud / offline / readonly derivation
- `buildWhoami`; `createControlPlaneSource` — host-injected IO surface (the `completer` pattern)

**RBAC**
- `describeCapability` / `describeCapabilities` / `resolveCapabilityClosure` / `capabilitiesRequiringReauth` / `capabilitiesRequiringAudit` / `capabilityObligations`
- `bridgeAdminCapsToRuntime` / `SECTION_DOMAIN_MAP` — admin section:verb → runtime domain:verb
- `simulateRole` — role-simulation rows

**Tenant / login / distribution**
- `evaluateTenantReadiness`, `validateTenantSwitch` (server-authoritative orgId), `resolveDesktopPairing`, `evaluateDistributionReadiness`

**Security primitives (the trust core)**
- `mintContextToken` / `verifyContextToken` — short-TTL signed `ControlPlaneContext` token over an **injected** signer/verifier; verify order signature → schema → expiry, fail-closed (ADR-0158/0161)
- `selectSigningKey` / `verificationKeys` / `findVerificationKey` — zero-downtime signing-key rotation over a `SigningKeyset` (ADR-0160)
- `appendAuditEntry` / `verifyAuditChain` / `GENESIS_PREV_HASH` — tamper-evident hash-chained audit log over an **injected** hash (ADR-0008)
- `effectiveNow` / `advanceWatermark` / `isClockRolledBack` / `DEFAULT_CLOCK_TOLERANCE_MS` + `evaluateClockIntegrity` — trusted-time anchoring + rollback policy (ADR-0159)

## Security model (how the primitives compose)

The four security primitives share one rule: **this package owns the logic, the deployment owns the secrets.** Crypto and time are injected, so the same code runs in cloud, sidecar, and browser.

1. **Trusted time** (`evaluateClockIntegrity`) anchors "now" to a monotonic high-watermark. A rewound system clock is benign drift (`allow`), a degrade signal (`readonly`), or a hard fail-closed (`block`) — airgap deployments cannot re-anchor from a server, so a rollback past tolerance blocks (a deliberate license-extension attempt).
2. **Signing-key rotation** (`SigningKeyset` resolvers) decides which key signs and which verify. Publish a `next` key → flip → revoke after grace = zero downtime. Verifiers accept active+next+retiring inside the validity window, never `revoked`.
3. **Context token** seals a resolved `ControlPlaneContext` with the active signing key for short-TTL caching (60–120s). Surfaces re-resolve on expiry; suspend/revoke is pushed critically.
4. **Audit chain** seals every control-plane mutation: `hash = H(seq ‖ prevHash ‖ canonical(event))`. Any edit/insert/reorder/deletion breaks the recomputed chain at the first affected sequence.

All four fail closed: a malformed/forged/expired/rolled-back/broken input is rejected, never silently trusted.

## Wired stores

None of its own — pure resolution + reconciliation. IO is host-injected via `createControlPlaneSource` and reads through:

- `apps/cloud` (identity/membership/tenant/entitlement; SECURITY DEFINER membership lookup, ADR-0153)
- `os-license` (envelope verify, license state, offline grace cache)
- `apps/license-service` (revocation snapshot)

## Methods implemented / consumed

Implements the `control.*` namespace (see [`contracts/control-plane-rpcs.md`](../contracts/control-plane-rpcs.md)): `control.context.resolve` / `control.context.whoami`, `control.entitlement.get`, `control.tenant.readiness`, `control.roles.simulate`, `control.memberships.list`, `control.tenants.switch`, `control.sessions.list` / `control.sessions.revoke`, `control.devices.list` / `control.devices.revoke`.

Handlers are host-injected and fail closed with `AK_CONFIG_INVALID` when the source is unconfigured; capability-gated mutations emit `AK_AUTH_EXPIRED` when reauth is required.

Consumes: cloud auth/membership/entitlement endpoints; `os-license` verify/state; license-service revocation list.

## Boundaries

- Identity/capability **primitives** stay in `os-core` (size budget, ADR-0013). This package is orchestration + policy.
- Contract **schemas** stay in `os-contracts` (ADR-0157). This package depends on them, not the reverse.
- The effective `orgId` is always server-resolved here; a client-supplied `orgId` is a hint, never trusted for mutation.
- No crypto, no clock, no storage in this package — all injected. Keeps it node-free and identically runnable in the browser, sidecar, and cloud.
- UI surfaces do not own identity or capability decisions. Web/desktop/admin may
  collect a login, tenant hint, or device-pairing code, then call this resolver
  through the host. They must render the resolved context and fail closed when a
  required context is absent or expired.
- Runtime enforcement is outside this package: sidecar/headless/security
  bindings verify the signed context/JWT and enforce caps, plan, audience, and
  tenant before mutating work.

## Common questions

- **Why a new package and not `os-core`?** Orchestration + policy would blow the `os-core` budget (ADR-0013) and couple primitives to services. See ADR-0157.
- **Where is entitlement computed — cloud or sidecar?** Both run the same resolver here; cloud wins online, sidecar derives offline. ADR-0158.
- **How fresh is a context?** Short-TTL token (60–120s) + critical push for suspend/revoke. ADR-0161.
- **How does key rotation avoid downtime?** Verifiers trust the union of active+next+retiring keys, so a `next` key is accepted before anything is signed with it. ADR-0160.
- **Can an offline actor extend a license by rewinding the clock?** No — `evaluateClockIntegrity` blocks an airgap rollback past tolerance; the effective clock never runs backward. ADR-0159.

## Related ADRs / RFCs

RFC-0054; ADR-0157 / 0158 / 0159 / 0160 / 0161; ADR-0008 (audit chain), ADR-0006 (RBAC), ADR-0047 (license trust anchor), ADR-0153 (membership lookup).

Source: /raw/for-agents/packages/os-control-plane.md

### for-agents/packages/os-copilot.md

# packages/os-copilot

## Purpose

Interactive NL copilot core (RFC-0013). Owns the tool registry, proposal
classifier, provider dispatch layer, session persistence, and cost metering.
`CopilotAgent` drives the turn loop: it builds the system prompt, resolves
tools from the registry, calls a provider via `CopilotProviderDispatch`,
classifies tool-call proposals into safe/escalate tiers, and emits
`CopilotCostEvent` entries on every turn.

## Public exports

- Tool registry: `buildCopilotToolRegistry`, `findTool`, `CopilotToolRegistryInput`,
  `RegisteredTool`, `PluginTool`
- Proposal classification: `classifyTier`, `evaluateCommitGate`, `buildEscalationFromGate`,
  `ClassifyInput`, `CommitGateInput`, `CommitGateOutcome`
- Session stores: `InMemoryCopilotSessionStore`, `SqliteCopilotSessionStore`, `RelationalCopilotSessionStore`,
  `replaySession`, `CopilotSessionStore`, `CopilotSqliteDatabase`,
  `SqliteCopilotSessionStoreOptions`, `RelationalCopilotSessionStoreOptions`, `ReplayStep`
- Dispatch: `composeDispatch`, `echoDispatch`, `CopilotProviderDispatch`,
  `CopilotDispatchInput`, `CopilotDispatchOutput`, `CopilotMessageInput`,
  `CopilotToolCallProposal`, `CopilotToolDeclaration`
- Runtime dispatch: `createRuntimeDispatch`, `RuntimeDispatchOptions`
- Cost: `estimateLlmCostUsd`, `summarize` (as `summarizeCost`), `InMemoryCostSink`,
  `CopilotCostEvent`, `CostSink`, `CostSummary`, `CostPriceBook`
- Managed provider/proxy policy: `resolveManagedProvider`,
  `resolveManagedProxyRequest`, `createManagedProxyRequestEnvelope`,
  `DEFAULT_AKOS_MANAGED_OPENROUTER_PROVIDER`, `MANAGED_PROXY_CONTRACT_VERSION`,
  `ManagedProxyRequestEnvelopeSchema`, and the allowed/forbidden data-category
  constants. These pin RFC-0055 F2's air-gap, consent, entitlement, budget,
  retention, vendor-boundary, and pinned-model invariants before the cloud route
  performs network IO.
- Agent: `CopilotAgent`, `buildSystemPrompt`, `CopilotAgentDeps`, `SendMessageInput`,
  `SendMessageOutput`, `BuildSystemPromptInput`
- Tool wrappers (re-exported from `tools/index.ts`): `ToolFlowCreate`, `ToolFlowEdit`,
  `ToolFlowRunPreview`, and other typed tool descriptors

## Wired stores

`SqliteCopilotSessionStore` requires a `better-sqlite3` handle. In production
the sidecar wires this from `os-storage`'s `CopilotSessionStore` path.
`InMemoryCopilotSessionStore` is used in tests.
Hosted replicas use `RelationalCopilotSessionStore` over the tenant-scoped
Postgres `RelationalStore`; message appends run in a row-locked transaction so
two replicas cannot silently overwrite each other's transcript updates.

## Methods implemented / consumed

Implemented (via `os-headless/src/copilot-handlers.ts`, owner `@agentskit/os-headless`
in `os-contracts/src/methods/copilot.ts`):

- `copilot.config.get` / `copilot.config.set`
- `copilot.session.create` / `.list` / `.get` / `.send` / `.cancel`
- `copilot.proposal.decide`
- `copilot.powers.list` / `.grant`
- `copilot.slash.parse` / `.list`
- `copilot.smoke`

Consumed: `os-rag` for knowledge grounding; marketplace plugin descriptors
from `@agentskit/os-marketplace/plugins` for plugin tool injection; `os-core`
for capability gating.

## Common questions

> **How do I register a new copilot tool?**
> Add a typed descriptor to `packages/os-copilot/src/tools/` following the
> `ToolFlowCreate` pattern (id, `inputSchema`, `capsRequired`, `tier`), then
> export it from `tools/index.ts`. The registry picks it up automatically on
> next `buildCopilotToolRegistry` call.

> **How does proposal classification work?**
> `classifyTier` maps a `CopilotToolCallProposal` to `safe | escalate |
> block` based on the tool's declared `tier` (`read`, `mutation`,
> `destructive`) and the user's granted powers. Escalated calls flow to the
> HITL inbox via `buildEscalationFromGate`.

> **How should the managed AKOS OpenRouter proxy route validate a request?**
> Build the canonical envelope with `createManagedProxyRequestEnvelope`, then
> call `resolveManagedProxyRequest` before constructing any network request. The
> policy fails closed on `AKOS_AIRGAP`, missing LLM consent, missing entitlement,
> exhausted budget, absent provider config, invalid retention/vendor/data
> contract, or a model id that differs from the pinned managed provider model.
> The route should treat a blocked decision as a local policy response and must
> not attempt outbound IO.

> **How do I replay a past session for debugging?**
> Call `replaySession(store, sessionId)` — it returns an async iterable of
> `ReplayStep` objects (role, content, tool calls) in chronological order.
> No LLM calls are made during replay.

Source: /raw/for-agents/packages/os-copilot.md

### for-agents/packages/os-core.md

# packages/os-core

## Purpose

Type contracts, error codes, security primitives, schemas. Zero IO.
Imported by every other package. ≤28 KB gzipped (ADR-0013, raised from 25).

## Public exports

- `errors/codes.ts` — `ErrorCodes.AK_*` enum; `AgentsKitError` class.
- `schema/*.ts` — Zod schemas for `Workspace`, `Agent`, `Flow`,
  `Trigger`, `RunRecord`, `TraceRecord`, `HitlDecision`, `Audit*`.
- `runtime/run-mode.ts` — `RunContext`, `RunMode`, `STUB_RUN_MODES`.
- `auth/identity-context.ts` — pure `ResolvedIdentityContext` contract shared
  by web SaaS, desktop local/cloud-connected, CLI, admin, and self-hosted
  surfaces. This is the shape only; source-of-truth resolution belongs to
  `apps/cloud` online and `os-control-plane` policy assembly.
- `schema/tenancy.ts` — canonical hosted tenant root domain, reserved tenant
  slug list, DNS-safe `TenantSlug` schema, and `isReservedTenantSlug`. Web edge
  parsing and cloud tenant-hint parsing must import these instead of copying
  their own domain or reserved-label lists.
- `schema/first-access.ts` — durable first-access contract shared by hosted
  web and cloud identity resolution. Separates user identity, tenant setup,
  tenant membership, and user onboarding state for B2C/B2B routing.
- `schema/observability.ts` — `ActivationMetricsConfig` (H5 #3821): the
  strict-opt-in activation/retention consent schema (`enabled` defaults to
  `false`; `collectContent` is locked to `false`). Carried on
  `WorkspaceConfig.activationMetrics` and reused by the
  `workspace.config.activation.*` RPCs.
- `obs/activation.ts` — `decideEmitActivation(config, consent)`: the runtime
  strict-opt-in gate. Returns `'emit'` only when **both** `config.enabled` is
  true **and** the generic telemetry consent gate (`decideEmit`) allows it;
  otherwise `'drop'`. When activation metrics are disabled, nothing is emitted
  even if a telemetry sink is configured — the schema's strict-opt-in contract
  is enforced at runtime, not just in config.
- `security/prompt-firewall.ts` — `evaluatePromptFirewallTiered`,
  `PROMPT_FIREWALL_CORPUS`.
- `security/redaction-profiles.ts` — `applyRedactionProfile`,
  `getRedactionProfile`, `RedactionProfileId` enum.
- `security/per-flow-sandbox.ts` — `resolveFlowSandbox`,
  `isAllowedDecision`. Resolves `max(flowLevel, agentLevel, nodeLevel)`
  from the optional `sandbox: SandboxLevel` field on `FlowConfig`,
  `AgentConfig`, and `AgentNode` (#1133 M14).
- `tools/sandbox.ts` — `SandboxLevel`, `decideSandbox`,
  `SandboxRuntime` interface.
- `hitl/inbox.ts` — `HitlInbox` interface, `HitlDecision`, `HitlTask`.
- `audit/legal-hold.ts` — `LegalHold`/`LegalHoldScope` schemas,
  `assertNoActiveLegalHold(holds, target)` deletion guard
  (`AK_LEGAL_HOLD_ACTIVE`), `findBlockingLegalHolds` (ENT-7 #1716).
- `ports/*.ts` — hexagonal ports for external services (ef-00 F0.15,
  Enterprise Final epic #2936). Bindings live in dedicated L2 packages
  enforced by `pnpm check:vendor-isolation`. Current ports:
  - `BlobStore` (`ports/blob.ts`) — bound by `os-blob`, `os-blob-s3`.
  - `EmailSender` (`ports/email.ts`) — bound by `os-email`, `os-email-resend`.
  - `ErrorReporter` (`ports/error-reporter.ts`) — bound by `os-errors`,
    `os-errors-sentry`. Distinct from `AgentsKitError`: ports/* is the
    external sink; `errors/*` is the typed error.
  - `TelemetryProvider` (`ports/telemetry.ts`) — bound by `os-telemetry`,
    `os-otel-grafana`.
  - `RelationalDriver` (`ports/relational.ts`) — keeps pool acquisition
    (`connectionTimeoutMs`) separate from SQL execution
    (`statementTimeoutMs`); Postgres binds both, SQLite ignores them.
- `server/agent-identity.ts` (subpath `@agentskit/os-core/server/agent-identity`,
  Node-only) — RFC #1248 verifiable agent identity:
  `generateAgentIdentityKeypair`, `didKeyFromPublicKeyPem` /
  `publicKeyFromDidKey`, `resolveDidPublicKey` (`did:key` local +
  `did:web` via injected fetch), `signAgentManifest` /
  `verifyAgentManifest` (canonical detached Ed25519 over the manifest
  minus `identityRef`), `didFingerprint`. `AgentIdentityRef` schema lives
  in `schema/agent-registry.ts`.

## Invariants & gotchas

- **Gzip budget is 28 KB** (ADR-0013, raised from the original 25 KB). Authoritative source: `package.json` `"sizeBudgetGzipped": "28KB"` + `.size-limit.json`; the CI `size-limit` gate reads from there. A single PR adding >1 KB without proportional contract value should open a new ADR.
- **Zero runtime dependencies — zod is a peer, not a direct dep.** `package.json` has no `dependencies` key; `zod` appears only under `peerDependencies`. Adding any runtime dep here violates ADR-0004 and would silently bloat every consumer.
- **No I/O, no LLM, no FS, no network — pure contracts and decision logic only.** This package is imported by every other package; any side-effecting import (fs, http, process, etc.) propagates to all of them and breaks test isolation. Decision logic is acceptable; anything that touches the outside world is not.
- **Identity and tenancy primitives here are contracts, not authority.** `os-core`
  may define the context shape, tenant slug schema, and reserved labels. It must
  not decide membership, mint tokens, read sessions, or enforce capabilities.
  Those responsibilities stay with `apps/cloud`, `os-control-plane`, and the
  sidecar/security enforcement path.
- **Subpath exports must stay tree-shake-friendly.** The `exports` map in `package.json` exposes ~80+ subpaths (e.g. `@agentskit/os-core/schema/agent`). Each entry is a self-contained module. Do not add barrel re-exports that pull the whole index into a subpath — that defeats the purpose of the map and breaks consumers that import a single slice.
- **`errors/codes.ts` is a curated public subset — most `AK_*` codes are string literals defined per-package.** Adding a new error code to a specific package does NOT require editing `os-core`. Only codes that are shared across multiple packages and referenced at the `AgentsKitError` class boundary belong here. See `docs/reference/ak-error-codes.md` for the full catalog.

## Wired stores

None. Pure types + schemas.

## Methods implemented / consumed

None. Reference types only.

## Common questions

> **Why is `AgentsKitError` thrown without a typed cause?**
> Use `ErrorCodes.AK_*` discriminator + `hint` field. Consumers
> branch on `err.code`.

> **How do I add a redaction profile?**
> Edit `security/redaction-profiles.ts` (these are source-internal symbols,
> not public exports): add the id to the `RedactionProfileId` enum, append the
> profile to the module-private `PROFILE_BY_ID` map, and add the id to the
> exported `REDACTION_PROFILE_IDS` list (the env-driven selector). Consumers
> read profiles through the exported `getRedactionProfile(id)` accessor.

Source: /raw/for-agents/packages/os-core.md

### for-agents/packages/os-cost.md

# packages/os-cost

## Purpose

Cost metering, budget enforcement, alerting, and billing for the AgentsKit
runtime. The cost domain tracks per-run token usage and USD spend, aggregates
it into summaries and breakdowns by provider, agent role, workspace, or
pipeline, and enforces configurable budgets that can warn or block dispatch
before a costly LLM call is made. Budgets and mute state are persisted to the
sidecar user-data directory via `os-storage` atomic writes. An account-level
spend policy (`cost.spendPolicy`) sits above per-target budgets as a
hard daily/monthly USD cap. Alerts are synthesised automatically when a budget
flips to `approaching` or `over`, persisted in `cost-alerts.json`, and can be
muted per-id via `cost.alerts.mute`.

The implementation lives in `packages/os-cost/src/` (cost.ts, budgets.ts,
alerts.ts, spend-policy.ts, cost-handlers.ts, cost-store-adapter.ts, util.ts),
extracted from `os-headless` per ADR-0120 SU-7. The RPC contracts are declared
in `packages/os-contracts/src/methods/observability/cost-basic.ts`,
`cost-budgets-alerts.ts`, and `integrations/cost-reset.ts`.

## Public exports

All symbols are re-exported from the package index (`src/index.ts`) and are
available as `@agentskit/os-cost`:

**cost.ts** — core store contract and pure helpers:
- `CostRow` — immutable row shape (date, providerId, role, costUsd, tokensIn,
  tokensOut, runId + optional scope ids: workspaceId, taskId, agentId,
  skillId, workflowId, pipelineId)
- `CostStoreLike` — duck-typed store interface (list, push?, clear?)
- `createInMemoryCostStore` — creates an in-process `CostStoreLike` store
- `sumCost(rows)` — reduces rows to total USD
- `computeMom(rows, nowIso)` — month-over-month delta (momCurrentUsd,
  momPreviousUsd, momDeltaUsd)
- `groupBy(rows, pick)` — groups rows to a `Record<string, number>` cost map
- `aggregateCostRows(rows, groupBy)` — bucketed breakdown sorted by cost
- `buildListFilter(input)` — normalises raw RPC params to a typed filter
- `CostGroupBy` — union of valid group-by dimensions: `provider | role |
  workspace | agent | skill | workflow | pipeline`

**budgets.ts** — CRUD + dispatch-side enforcement:
- `Budget`, `BudgetInput` — budget record and upsert shape
- `upsertBudget(input)` — insert or update a budget (persists to
  `cost-budgets.json`); returns `{ ok: false, reasons }` for invalid/missing input
- `deleteBudget(id)` — remove a budget by id
- `listBudgetsWithStatus(store, now)` — returns budgets annotated with live
  `consumption` and `status: under | approaching | over`
- `evaluateBudgets(store, now, params)` — pre-dispatch check: returns
  `{ blocked, breaches }` where `blocked=true` when any matching budget has
  `action='block'` and consumption + estimate exceeds threshold
- `EvaluateInput` — estimate params (estimateUsd, estimateTokens, providerId,
  role, workspaceId, taskId, agentId, skillId, workflowId, pipelineId)

**alerts.ts** — alert lifecycle + cloud-gated billing:
- `AlertRow`, `AlertSeverity` — alert record shape
- `listAlertsFromBudgets(store, now, mutedOnly, onAlertFired?)` — derives
  alerts from budget statuses, persists firedAt/muted, fires `onAlertFired`
  callback on first-seen alerts
- `muteAlert(id, muted)` — toggle mute state
- `BillingPlanSnapshot` — optional subscription fields the cloud boundary may
  inject (tier, seatsIncluded, seatsUsed, renewsAt, portalUrl); never
  fabricated — absent fields render as "unknown"
- `BillingInvoice` — invoice record shape (id, number, issuedAt, amountUsd,
  status, pdfUrl?)
- `BillingOpts` — options for `billingPlanResponse` / `billingInvoicesResponse`
  (cloudEnabled, store, now, plan?, invoices?)
- `billingPlanResponse(opts?)` — returns `{ enabled: false }` when
  `opts.cloudEnabled` is falsy; otherwise returns `{ enabled: true, plan }` with
  `monthlyUsd` derived from the real cost store (never fabricated). Subscription
  fields (tier, seats, renewsAt) are only present when injected via `opts.plan`.
  The caller reads `process.env.AGENTSKIT_CLOUD_ENABLED` at its own composition
  boundary and passes it as `cloudEnabled` (ADR-0099 — os-cost itself does not
  read env directly)
- `billingInvoicesResponse(opts?)` — returns `{ enabled: false, rows: [] }` when
  cloud is off; otherwise `{ enabled: true, rows }` from `opts.invoices` (absent
  ⇒ empty list)

**spend-policy.ts** — account-level spend policy:
- `SpendPolicy` — policy record (maxUsdPerDay, maxUsdPerMonth,
  requireBlockAction, alertVia?, alertEmail?, slackWebhookUrl?,
  discordWebhookUrl?, updatedAt)
- `SpendPolicyInput` — writable subset of `SpendPolicy` (all fields optional)
- `SpendAlertVia` — channel opt-in flags (email?, slack?, webhook?, discord?)
- `readSpendPolicy()` — reads `spend-policy.json` from the user-data dir;
  returns `DEFAULT_POLICY` (all zeros, requireBlockAction=false) when absent or
  malformed
- `setSpendPolicy(input, now)` — validates and persists the policy; returns
  `{ ok: false, reasons }` for invalid input (negative caps, day > month, bad
  email/webhook URL)
- `evaluateSpendPolicyOrThrow(store, now, policy?)` — throws
  `AgentsKitError('AK_BUDGET_EXCEEDED')` when daily or monthly USD ceiling is met
  or exceeded; no-op when store is absent or both ceilings are 0

**usage-state.ts** — shared tenant/package evaluator:
- `UsagePackageId` — commercial package ids (`platform`, `ai`, `data`,
  `governance`)
- `USAGE_PACKAGE_LABELS` / `usagePackageLabel(packageId)` — shared commercial
  package labels for admin, CLI, SSE consumers, and enforcement surfaces
  (also available from the lightweight `@agentskit/os-cost/usage-state`
  subpath)
- `usageAttentionLabels(state)` — shared warning/exceeded/blocked package and
  metric labels for SSE titles, CLI summaries, and billing UI attention cards
- `UsageStateStatus` — `normal | warning | exceeded | blocked`
- `UsageLimitInput` — one metered limit (used, optional limit, thresholds,
  overage, hardBlock)
- `evaluateUsageLimit(limit)` — pure threshold classifier; defaults to 70%
  warning and 90% critical warning, 100% exceeded, or blocked for hard limits
  without overage
- `evaluateUsageState(input)` — aggregates package limits plus license/payment
  signals into one tenant-wide state for admin, SSE, CLI, and enforcement

**data-usage.ts** — tenant-scoped Data package usage reader:
- `readDataUsageSnapshot(opts)` — reads billable blob bytes/object count from a
  tenant prefix (`<tenantId>/`) and RAG vector count from an injected
  `size()`-capable vector store
- `DataUsageSnapshot` — `{ tenantId, storageBytes, storageObjects, ragVectors }`
- `DataUsageBlobStore`, `DataUsageVectorStore` — structural ports so cloud and
  sidecar can inject `os-blob` / S3/R2 and RAG stores without adding package
  dependencies here

**cost-store-adapter.ts** — tenant-scoped storage bridge (RFC-0037/ADR-0083):
- `adaptCostStoreToLike(opts)` — wraps a `SqliteCostStore` as `CostStoreLike`;
  reads use the audited `listAcrossWorkspaces` cross-workspace escape; writes
  target the resolved or default workspace
- `CostStoreLikeAdapterOptions` — options (store, defaultWorkspaceId,
  resolveScope?)

**cost-handlers.ts** — JSON-RPC handler factory:
- `buildCostPhase7Handlers(store, now, deps?)` — returns a `HandlerMap` that
  wires all `cost.*` and `billing.*` RPC methods to the store and budget modules
- `CostHandlerDeps` — optional deps: `onAlertFired`, `cloudEnabled`,
  `billingPlan`, `billingInvoices`, `billingProvider` (live refresh callback),
  and `usageStateProvider` (backend-computed tenant usage state)

**RPC methods** (declared in `os-contracts`, implemented by
`buildCostPhase7Handlers`, all `stability: 'alpha'`):
- `cost.list` — itemised cost rows with from/to/providerId/role filters
- `cost.summary` — windowed aggregate (totalUsd, byProvider, byAgent, MoM
  delta); `windowHours` default 24, max 720
- `cost.breakdown` — grouped breakdown by provider / role / workspace with
  optional date + field filters
- `cost.budgets.list` — list budgets with live consumption + status
- `cost.budgets.upsert` — insert or update a budget
- `cost.budgets.delete` — delete a budget by id
- `cost.budgets.evaluate` — pre-dispatch block/warn check
- `cost.alerts.list` — list alerts derived from budgets; optional `mutedOnly`
- `cost.alerts.mute` — mute or unmute an alert by id
- `cost.spendPolicy.get` — read the account-level spend policy
- `cost.spendPolicy.set` — update it (requires cap `cost:budget:write`)
- `cost.reset` — clear the in-memory cost meter window
- `billing.plan.get` — cloud-gated billing plan (requires cap `billing:read`)
- `billing.invoices.list` — cloud-gated invoice list (requires cap
  `billing:read`)
- `usage.state.get` — cloud-gated backend usage state for admin, CLI, and
  enforcement surfaces (requires cap `billing:read`)

## Common questions

> **How does pre-dispatch budget enforcement work?**
> Before the dispatcher commits a costly LLM call it invokes
> `cost.budgets.evaluate` with `estimateUsd` or `estimateTokens` plus the
> relevant scope ids (providerId, agentId, etc.). `evaluateBudgets` reads all
> persisted budgets, sums existing consumption over the budget's window, adds
> the estimate, and returns `{ blocked: true, breaches: [...] }` when any
> matching budget has `action: 'block'` and the threshold is exceeded.
> Budgets with `action: 'warn'` appear in `breaches` but do not set `blocked`.

> **What is the difference between `CostStoreLike` and `SqliteCostStore`?**
> `CostStoreLike` is the duck-typed interface (`list`, `push?`, `clear?`) that
> the in-process cost helpers and handler factories depend on. It has an
> in-memory implementation (`createInMemoryCostStore`) for tests and
> short-lived processes. In the production sidecar a `SqliteCostStore` from
> `@agentskit/os-storage` is wrapped via `adaptCostStoreToLike` (ADR-0083),
> which routes reads through the audited `listAcrossWorkspaces` escape and
> routes writes to the resolved or default workspace bucket.

> **How are alerts generated — does anything push them?**
> Alerts are purely derived; there is no background worker. Each call to
> `cost.alerts.list` (or the `listAlertsFromBudgets` helper) re-evaluates
> every budget via `listBudgetsWithStatus`, compares to the persisted
> `cost-alerts.json`, and synthesises alert rows for any budget in
> `approaching` or `over` status. First-seen alerts fire the optional
> `onAlertFired` callback (wired at startup via `CostHandlerDeps`), which the
> sidecar uses to emit a notification event. Mute state survives restarts
> because it is written back to `cost-alerts.json` on every list call.

> **Where does the account-level spend policy fit relative to per-target budgets?**
> The spend policy (`cost.spendPolicy`) is a single document with hard
> `maxUsdPerDay` and `maxUsdPerMonth` caps plus optional alert-via channel flags
> and URLs (email, Slack webhook, Discord webhook). It brackets all per-target
> budgets. Per-target budgets (scope: provider, role, agent, workspace, etc.)
> provide fine-grained `warn | block` rules. The spend policy is updated via
> `cost.spendPolicy.set`, which requires the `cost:budget:write` capability.
> At run admission, `evaluateSpendPolicyOrThrow` blocks dispatch with
> `AK_BUDGET_EXCEEDED` when either ceiling is exceeded — this is distinct from
> the best-effort `cost.alert` fan-out which fires separately.

Source: /raw/for-agents/packages/os-cost.md

### for-agents/packages/os-desktop.md

# packages/os-desktop

## Purpose

The bundled-private React 19 app the Tauri shell (`apps/desktop`) renders. Hosts every desktop screen (flows, runs, inbox, audit, marketplace…), the command palette, copilot, voice PTT, and the JSON-RPC sidecar wrapper. Plugin authors write against the `ui-panel` extension point (ADR-0012) and the IPC schema — they do not import App internals (ADR-0018 §3.5).

## Public exports

- `App` — root React component the Tauri shell mounts.
- `createPttMediaRecorderBinding` — push-to-talk MediaRecorder factory.
- `registerTelemetryForwarder` / `TelemetryForwarder` — telemetry sink registration.
- `UiEvent` / `UiEventKind` — telemetry event union.
- `PttBinding`, `PttBindingOpts`, `MediaRecorderLike`, `MediaRecorderFactory`, `GetUserMediaFn` — voice binding contracts.
- `fetchRuntimeStatus` / `RuntimeStatus` — sidecar runtime-status probe used by the observability screen.
- `hasTauri()` — runtime guard: `true` only inside the Tauri shell (gates native-only paths).
- `HostCapabilitiesProvider` / `useHostCapabilities` — host-capability seam (ADR-0117 / RFC-0046): a non-Tauri host (apps/console) declares which native affordances are unavailable so the shared screens gate them instead of duplicating UI per surface.
- `DESKTOP_HOST_CAPABILITIES` / `WEB_HOST_CAPABILITIES` — the two stock capability profiles; `HostCapabilities` / `HostCapabilitiesProviderProps` are their contracts.

## Wired stores

- `selection-store`, `theme-store`, `run-mode-store`, `sidecar-state`, `mutation-outbox` (offline queue), `use-kv-backed-state` (Tauri keychain-backed prefs).

## Methods implemented

None — pure renderer. The desktop's outbound API surface is the JSON-RPC calls it issues via `lib/sidecar/`.

## Methods consumed

Every screen consumes a slice of `os-headless` JSON-RPC. Highlights:

- `flows.*`, `runs.*`, `inbox.*`, `audit.*`, `marketplace.*`, `triggers.*`, `traces.*`, `cost.*`, `observability.*`, `templates.*`, `connections.*`, `evals.*`, `knowledge.*`.
- `copilot.*` (chat + tool calls), `whitelabel.*` (brand kit), `oem.*` (license envelope).

Full per-screen wiring lives in `docs/for-agents/screens/*.md`.

## Common questions

> **How is a new screen wired?**
> Drop a folder under `src/screens/<name>/`, register the route in `app-nav.ts`, add a `for-agents/screens/<name>.md` listing the JSON-RPC methods + edge cases it touches.

> **Why is the sidecar a wrapper, not a direct fetch?**
> `lib/sidecar/` enforces Zod parsing on every response and routes errors through `sidecar-error-toast.tsx`. Screens never raw-fetch.

> **Plugins want to render UI — what's the contract?**
> The `ui-panel` extension point in ADR-0012. Plugin renders into a sandboxed iframe; host posts JSON-RPC messages. Plugin code does not import from this package.

Source: /raw/for-agents/packages/os-desktop.md

### for-agents/packages/os-dev-orchestrator.md

# packages/os-dev-orchestrator

## Purpose

SDLC pipeline executor. Six-phase walker (PRD → Issues → QA → Dev → Test → PR) with HITL gates, git-worktree isolation per coding task, structured failure taxonomy, and artifact emission for replay/audit.

## Public exports

- `runIssueToPrPipeline` / `simulateIssueToPrDryRun` — main entry points (live + dry-run).
- `runDelegatedCodingTask` — single coding-task runner used inside the pipeline.
- `createDevOrchestratorWorktreeManager` / `createCodingAgentWorktreeManager` — git worktree lifecycle.
- `computeGitDiff` / `formatUnifiedDiffPreview` / `tryGitRefDiffSummary` — diff snapshotting.
- `runCodingAgentBenchmark` / `computeCompletenessScore` — benchmark harness.
- `classifyCodingFailure` / `CODING_FAILURE_CATALOG` / `buildCodingFailureIncidentRecord` — failure taxonomy + retry policy.
- `evaluateCodingPermission` / `CODING_PERMISSION_PROFILES` — per-operation permission gates (network, git, fs).
- `buildCodingTaskReport*` / `renderCodingTaskReportMarkdown` / `toCodingTaskDashboardPayload` — report renderers.
- `buildCodingRunArtifactPayload` / `writeCodingRunArtifactFile` / `redactCodingTaskRequest` — artifact pipeline.
- `DEV_TRIGGER_PRESETS` / `mapDevTriggerPresetToTaskInput` — trigger → SDLC-task mapping.

## Wired stores

- Git worktrees on local FS (`GitRunner` injection point — `defaultGitRunner` uses `git` binary).
- Artifact files written via `writeCodingRunArtifactFile` to the run-artifact directory consumed by `os-headless` `runs.getArtifact`.

## Methods implemented

Exposed through `os-headless` JSON-RPC as:

- `sdlc.runs.dispatch`, `sdlc.runs.resume`, `sdlc.runs.fork`, `sdlc.runs.rerun`, `sdlc.runs.list`
- `sdlc.gates.list`, `sdlc.gates.decide`
- `sdlc.pipelines.list`
- `coding.delegate`, `coding.runTask`, `coding.cancelTask`, `coding.runConformance`, `coding.benchmark`
- `coding.permissionProfiles`, `coding.permissionProfiles.upsert`, `coding.permissionProfiles.delete`, `coding.providers`

## Methods consumed

- `coding.invoke` (from `os-coding-agents` providers) — per delegated subtask.
- `inbox.requestApproval` — for HITL gates between phases.
- `audit.append` — every permission decision + phase transition.
- `os-runtime.CostTracker` — meters provider spend across the pipeline.

## Common questions

> **What is "delegation"?**
> A single SDLC phase may fan out into N coding subtasks, each in its own worktree. `runDelegatedCodingTask` runs one subtask; the pipeline orchestrates them with conflict detection (`FileConflict`).

> **How does retry work?**
> `classifyCodingFailure(result)` returns a `CodingFailureClassification` including a `RetryPolicy` (`none` | `retry_same` | `retry_backoff` | `alternate_provider`). The pipeline consults `CODING_FAILURE_CATALOG` for the per-code policy. Hard codes (`permission_denied`, `merge_conflict`, `hallucinated_file`, `secret_leak`) have `retryPolicy: 'none'` and `requiresHumanReview: true`.

> **Where do PR drafts go?**
> `IssueToPrPrDraftMeta` is returned in the `IssueToPrLiveReport`. The desktop SDLC screen renders it; the user approves via the inbox before the final `pr.create` JSON-RPC.

Source: /raw/for-agents/packages/os-dev-orchestrator.md

### for-agents/packages/os-egress-guard.md

# packages/os-egress-guard

## Purpose

Per-org egress policy + hosted enforcer for the AgentsKitOS sandbox path. Provides two components: (1) a Zod-validated `OrgEgressPolicy` with wildcard host matching for allowlist/denylist decisions; and (2) `HostedEgressEnforcer` — an async enforcer that loads per-org policies, evaluates decisions, and emits structured `egress.decision` audit events. Architectural context: [ADR-0095](../../adr/0095-hosted-sandbox-vercel.md). Epic: ef-03 SU3.3 (#2980, parent #2940/#2936).

Stability: **internal** (L2 binding). Distribution: cloud/enterprise.

## Public exports

### Per-org policy

- `OrgEgressPolicy` — Zod schema + type:
  ```ts
  interface OrgEgressPolicy {
    orgId: string
    allow: string[]          // host patterns: exact or '*.example.com'
    deny: string[]           // deny takes precedence over allow
    defaultAction: 'allow' | 'deny'  // fallback when no pattern matches
  }
  ```
- `evaluatePerOrgPolicy(policy, host)` → `'allow' | 'deny'` — pure policy evaluation.
  Decision order: (1) any deny pattern matches → `'deny'`; (2) any allow pattern matches → `'allow'`; (3) `defaultAction`.
- `matchesHostPattern(pattern, host)` → `boolean` — supports exact match and `*.example.com` wildcard. `**` does NOT enter the wildcard branch (second char is `*`, not `.`) — it falls through to exact-match and returns false for any valid DNS hostname. Callers must normalise the host to a bare lowercase hostname (e.g. `new URL(url).hostname`) before calling.

### Hosted enforcer

- `createHostedEgressEnforcer(deps: HostedEgressEnforcerDeps)` → `HostedEgressEnforcer`.
- `HostedEgressEnforcer`:
  ```ts
  interface HostedEgressEnforcer {
    check(host: string, ctx: { orgId: string }): Promise<'allow' | 'deny'>
    emitAudit(decision: { host; orgId; action; reason }): Promise<void>
  }
  ```
- `AuditChannel` — injected dep for audit event emission:
  ```ts
  interface AuditChannel {
    emit(event: {
      kind: 'egress.decision'; orgId; host; action; reason; occurredAt;
    }): Promise<void>
  }
  ```
- `HostedEgressEnforcerDeps` — factory dependencies: `resolvePolicy(orgId)` (policy loader), `audit: AuditChannel`, and optional `marketplaceAllowlist?(host, orgId) → Promise<boolean>` (ADR-0012 / #2712 bypass — short-circuits per-org deny policy and is ALWAYS audited even when `AKOS_AUDIT_ALL_EGRESS` is unset).

## Wired stores

None. Policy loading is via the injected `HostedEgressEnforcerDeps` policy-loader (backed by the cloud policy store). Audit entries are forwarded to the injected `AuditChannel`.

## Methods implemented

Not a JSON-RPC surface. `HostedEgressEnforcer` is injected into the cloud server's sandbox egress path and into `@agentskit/os-sandbox-vercel`'s µVM network-policy layer.

## Methods consumed

- Injected policy loader (fetches `OrgEgressPolicy` from the cloud policy store).
- Injected `AuditChannel` (forwards to the audit ledger in `os-audit`).

## Common questions

> **How do I configure an org's egress allowlist?**
> Write an `OrgEgressPolicy` to the policy store (cloud API). The enforcer loads it on each `check()` call. Default for new orgs: `defaultAction: 'deny'` — all egress blocked until an allowlist is configured.

> **Why do deny patterns take precedence?**
> Defense-in-depth: an admin typo that accidentally adds a blocked host to `allow` would otherwise silently permit it. Deny-wins prevents that class of misconfiguration.

> **What host pattern formats are supported?**
> Exact hostname (`api.openai.com`) or leading-wildcard (`*.stripe.com`). No regex, no `**`, no path patterns (ADR-0011 §safe). Patterns are case-insensitive.

## Error codes

- `AK_EGRESS_DENIED` — `check()` returned `'deny'`; emitted as a structured error at the call site in the sandbox runtime.

## Tests

`packages/os-egress-guard/tests/hosted-enforcer.test.ts`, `per-org-policy.test.ts`.

Source: /raw/for-agents/packages/os-egress-guard.md

### for-agents/packages/os-email-resend.md

# packages/os-email-resend

## Purpose

Resend + React Email binding for the `EmailSender` port. This is the only package in the monorepo permitted to import `resend` and `@react-email/components` (`check:vendor-isolation`, ADR-0098). Wraps the Resend API for transactional email delivery with React Email templates rendered server-side. Depends on `@agentskit/os-email` for the port contract and template registry.

Stability: **internal** (L2 binding). Distribution: cloud + admin. Epic: ef-07 SU7.11 (#3022, parent #2944/#2936).

## Public exports

- `createResendEmailSender(deps: ResendEmailSenderDeps)` → `EmailSender`.

```ts
// from packages/os-email-resend/src/resend-sender.ts
interface ResendEmailSenderDeps {
  apiKey: string                         // RESEND_API_KEY
  registry: EmailTemplateRegistry        // required template registry for subject/text rendering
  defaultFrom: { address: string; name?: string }  // default from-address when brand.supportEmail is absent
  reactTemplates?: Map<                  // optional React Email component factories
    EmailTemplateId,
    (props: { vars: Record<string, unknown>; brand: BrandContext }) => React.ReactElement
  >
}
```

`send(message)`:
1. Looks up `message.templateId` in the registry; throws `AK_EMAIL_TEMPLATE_MISSING` if absent.
2. Resolves from-address: `brand.supportEmail` → `defaultFrom` fallback.
3. Renders body: React Email factory (HTML) → `template.renderText` (plain text) → `JSON.stringify(vars)` fallback.
4. Calls `resend.emails.send(...)` with the resolved content.
5. Maps Resend API errors → `AgentsKitError(AK_EMAIL_PROVIDER_REJECTED)`.

## Wired stores

None. Stateless HTTP adapter.

## Methods implemented

Not a JSON-RPC surface. Injected into `apps/admin` (and `apps/cloud`) composition root.

## Methods consumed

- Resend API (`https://api.resend.com`) — vendor-isolated to this package.

## Common questions

> **How do I wire Resend in production?**
> ```ts
> import { createResendEmailSender } from '@agentskit/os-email-resend'
> import { createTemplateRegistry } from '@agentskit/os-email'
> const registry = createTemplateRegistry()
> // register templates...
> const sender = createResendEmailSender({
>   apiKey: process.env.RESEND_API_KEY!,
>   registry,
>   defaultFrom: { address: 'noreply@acme.io', name: 'AgentsKit' },
> })
> ```

> **Can I use React Email templates?**
> Yes — pass a `reactTemplates` Map with your template id as the key and a React Email component factory as the value. The factory receives `{ vars, brand }` and must return a `React.ReactElement`. The binding calls `render()` from `@react-email/components` server-side and sends the resulting HTML.

> **Why does the `defaultFrom` field live here and not in `EmailMessage`?**
> `from` is infrastructure-level config (set by the operator), not per-send content. It belongs at the sender factory level to keep messages portable across providers. Per-message override is available via `brand.supportEmail`.

## Error codes

| Code | Trigger |
|---|---|
| `AK_EMAIL_TEMPLATE_MISSING` | `message.templateId` is not registered in the `EmailTemplateRegistry`. |
| `AK_EMAIL_PROVIDER_REJECTED` | Resend API returned an error object, null data, or the SDK threw a network error. |

## Tests

`packages/os-email-resend/tests/resend-sender.test.ts`.

Source: /raw/for-agents/packages/os-email-resend.md

### for-agents/packages/os-email.md

# packages/os-email

## Purpose

`EmailSender` port re-export + static template registry + console dev sink. Re-exports the port contract, Zod schemas, and error codes from `@agentskit/os-core`. Provides `createTemplateRegistry` for registering transactional email templates keyed by `EmailTemplateId`, and `createConsoleEmailSender` for development/test use (logs to console, never delivers). Vendor bindings live in dedicated L2 packages: `@agentskit/os-email-resend`.

Stability: **stable** (port + dev sink). Distribution: admin + cloud. Epic: ef-07 SU7.11 (#3022, parent #2944/#2936).

## Public exports

Port contract (re-exported from `@agentskit/os-core`):
- `EmailSendResult`, `EmailMessage`, `EmailAddress`, `EmailTemplateId`, `BrandContext`, `EMAIL_ERROR_CODES` — Zod schemas + constants.
- `EmailSender`, `EmailErrorCode` — TypeScript types.

```ts
// EmailSender port (from @agentskit/os-core)
interface EmailSender {
  send(msg: EmailMessage): Promise<EmailSendResult>
}

interface EmailMessage {
  to: EmailAddress[]          // min 1, max 50
  cc?: EmailAddress[]         // max 50
  bcc?: EmailAddress[]        // max 50
  templateId: EmailTemplateId // required; kebab-case
  vars: Record<string, unknown>
  brand: BrandContext
  idempotencyKey?: string     // optional dedup key
  replyTo?: EmailAddress
}
```

Template registry:
- `createTemplateRegistry()` → `EmailTemplateRegistry` — in-memory registry of `EmailTemplate` instances keyed by `EmailTemplateId`.

```ts
interface EmailTemplate {
  readonly id: EmailTemplateId
  subject(vars: Record<string, unknown>, brand: BrandContext): string
  renderText?: (vars: Record<string, unknown>, brand: BrandContext) => string
}

interface EmailTemplateRegistry {
  register(template: EmailTemplate): void
  get(id: EmailTemplateId): EmailTemplate | undefined
  list(): readonly EmailTemplateId[]
}
```

Dev sink:
- `createConsoleEmailSender(registry: EmailTemplateRegistry)` → `EmailSender` — logs email body to stdout. Never delivers. Use in local dev and tests.

## Wired stores

None. The template registry is in-memory; senders are stateless.

## Methods implemented

Not a JSON-RPC surface. `EmailSender` is injected into app composition roots. `apps/admin` wires `createConsoleEmailSender` in dev and `createResendEmailSender` in production.

## Methods consumed

- Console output (dev sink only).
- Production senders are in binding packages (`os-email-resend`).

## Common questions

> **How do I register a transactional template?**
> ```ts
> import { createTemplateRegistry } from '@agentskit/os-email'
> const registry = createTemplateRegistry()
> registry.register({
>   id: 'invite-user',
>   subject: (_vars, brand) => `You've been invited to ${brand.productName}`,
>   renderText: (vars, _brand) => `Click: ${vars.inviteUrl}`,
> })
> ```

> **How do I add a new transactional email binding?**
> Create a new L2 package (e.g. `os-email-postmark`). Implement `EmailSender` from `@agentskit/os-core`. Export a factory. Register in `check:vendor-isolation`.

## Error codes

- `AK_EMAIL_TEMPLATE_MISSING` — `templateId` not registered in the template registry.
- `AK_EMAIL_PROVIDER_REJECTED` — the email provider rejected the send request (e.g. invalid credentials, domain not verified).
- `AK_EMAIL_RATE_LIMITED` — the email provider imposed a send rate limit.
- `AK_EMAIL_RECIPIENT_INVALID` — malformed or rejected recipient address.
- `AK_EMAIL_BRAND_RESOLUTION_FAILED` — `BrandContext` could not be resolved for the given org.

## Tests

`packages/os-email/tests/console-sender.test.ts`, `template-registry.test.ts`.

Source: /raw/for-agents/packages/os-email.md

### for-agents/packages/os-errors-sentry.md

# packages/os-errors-sentry

## Purpose

Sentry adapter for the `ErrorReporter` hexagonal port from `@agentskit/os-core`. This is the only package in the monorepo permitted to import `@sentry/node` (`pnpm check:vendor-isolation`). PII-safe by default: `createSentryReporter` automatically wraps itself in `createRedactingReporter` from `@agentskit/os-errors` so PII fields are scrubbed before reaching Sentry's network transport.

Stability: **internal** (L2 binding). Distribution: cloud + admin. Epic: ef-04 SU4.7 (#2992, parent #2941/#2936).

## Public exports

- `createSentryReporter(opts: SentryReporterOpts)` → `ErrorReporter`.

```ts
// from packages/os-errors-sentry/src/sentry-reporter.ts
interface SentryReporterOpts {
  dsn: string
  environment: 'development' | 'staging' | 'production' | 'test'
  release?: string   // e.g. process.env.VERCEL_GIT_COMMIT_SHA
}
```

Internally calls `Sentry.init({ dsn, environment, release })` once at factory time. `captureException` uses `Sentry.withScope` + `Sentry.captureException`. `captureMessage` uses `Sentry.captureMessage`. `setContext` sets user and tags via `Sentry.getCurrentScope()`.

Returns the raw reporter wrapped in `createRedactingReporter(inner)` — callers receive a PII-safe reporter without needing to apply the decorator manually.

## Wired stores

None. Sentry's own SDK manages the event buffer and network transport.

## Methods implemented

Not a JSON-RPC surface. Injected at app composition root.

## Methods consumed

- Sentry ingest API (HTTPS) — vendor-isolated to this package.
- `@agentskit/os-errors` `createRedactingReporter` — applied automatically.

## Common questions

> **How do I wire Sentry in production?**
> ```ts
> import { createSentryReporter } from '@agentskit/os-errors-sentry'
> const reporter = createSentryReporter({
>   dsn: process.env.SENTRY_DSN!,
>   environment: 'production',
>   release: process.env.VERCEL_GIT_COMMIT_SHA,
> })
> // Inject reporter into app composition root
> ```

> **Does this automatically redact PII?**
> Yes. The returned reporter is wrapped in `createRedactingReporter`. Fields in `DEFAULT_PII_FIELDS` (email, password, token, apiKey, etc.) are replaced with `'[redacted]'` before any Sentry SDK call.

> **How do I add per-request user context?**
> Call `reporter.setContext({ userId, orgId, plan })` at the start of each request handler. This sets the Sentry user/tag context for all subsequent exceptions in that scope.

> **Sentry v8 API notes?**
> `configureScope` was removed in v8 — use `getCurrentScope().setUser/setTag` (handled internally). `captureException` hint uses `withScope` to be type-safe for `tags` and `extra`.

## Error codes

No package-specific `AK_*` codes. The package itself never throws — `Sentry.init` errors propagate from the Sentry SDK as-is, which is acceptable because this adapter is wired at app composition root, not inside request handlers.

## Tests

`src/tests/sentry-reporter.test.ts` — 21 unit tests, 100 % line/branch/function/statement coverage (vitest + v8). Mocks `@sentry/node` entirely; no real network calls. Coverage thresholds set to 100/100/100/100 in `vitest.config.ts`.

Source: /raw/for-agents/packages/os-errors-sentry.md

### for-agents/packages/os-errors.md

# packages/os-errors

## Purpose

`ErrorReporter` port re-export + default adapters (no-op, console) + the `RedactingReporter` PII-scrubbing decorator. Distinct from `@agentskit/os-core` `AgentsKitError` / `AK_*` code catalogue (which defines the error *type*) — this package exposes the error reporting *sink* and its default implementations. Vendor bindings live in `@agentskit/os-errors-sentry`.

Stability: **stable** (port + default adapters). Distribution: cloud + admin + desktop. Epic: ef-04 SU4.7 (#2992, parent #2941/#2936).

## Public exports

Port re-exports from `@agentskit/os-core`:
- `ErrorLevel`, `ErrorContext`, `ErrorScope`, `DEFAULT_PII_FIELDS` — Zod schemas + constants.
- `ErrorReporter`, `PiiField` — TypeScript types.

```ts
// ErrorReporter port (from @agentskit/os-core)
interface ErrorReporter {
  captureException(err: unknown, ctx?: ErrorContext): void
  captureMessage(message: string, level: ErrorLevel, ctx?: ErrorContext): void
  setContext(scope: ErrorScope): void
  flush(timeoutMs: number): Promise<boolean>
}

interface ErrorContext {
  tags?: Record<string, string>
  extra?: Record<string, unknown>
}
```

Adapters:
- `createNoopReporter()` → `ErrorReporter` — all calls are silent. Default for test environments.
- `createConsoleReporter()` → `ErrorReporter` — writes to `process.stderr`. Use in development.
- `createRedactingReporter(inner, opts?: RedactingReporterOpts)` → `ErrorReporter` — PII-scrubbing decorator. Wraps any `ErrorReporter` and replaces `DEFAULT_PII_FIELDS` (and caller-supplied extra fields) values with `'[redacted]'` before delegating.

```ts
interface RedactingReporterOpts {
  fields?: readonly string[]  // additional field names to redact (case-insensitive)
}
```

`DEFAULT_PII_FIELDS` includes: `email`, `password`, `token`, `secret`, `apiKey`, `creditCard`, `ssn`, `phone`, `ip` (and more — see `os-core`).

## Wired stores

None. Adapters are stateless.

## Methods implemented

Not a JSON-RPC surface. Injected at app composition root and into `@agentskit/os-errors-sentry`.

## Methods consumed

None (no-op, console log, or delegates to inner reporter).

## Common questions

> **Should I use `createRedactingReporter` in production?**
> Yes — always wrap the production reporter (Sentry or otherwise) in `createRedactingReporter`. `createSentryReporter` in `os-errors-sentry` does this automatically.

> **How does field redaction work for nested objects?**
> `RedactingReporter` walks `ctx.extra` and `ctx.tags` recursively. Any key matching the PII field list (case-insensitive) is replaced with `'[redacted]'`. Already-redacted values pass through unchanged.

> **Can I add custom PII fields?**
> Pass `fields: ['myField', 'internalToken']` to `createRedactingReporter`. The extra fields are merged with `DEFAULT_PII_FIELDS`.

## Error codes

No package-specific `AK_*` codes. Reporters surface errors via the underlying transport (console / Sentry).

## Tests

Unit tests in `packages/os-errors/src/tests/`:
- `noop-reporter.test.ts` — verifies all four methods (captureException, captureMessage, setContext, flush) are no-ops or return expected values.
- `redacting-reporter.test.ts` — covers PII redaction (DEFAULT_PII_FIELDS + custom fields), nested-object recursion, array/null/primitive pass-through, delegation to inner reporter, idempotency.

Source: /raw/for-agents/packages/os-errors.md

### for-agents/packages/os-flags-posthog.md

# packages/os-flags-posthog

## Purpose

PostHog binding for the `FeatureFlagProvider` port defined in `@agentskit/os-core`. Evaluates server-side feature flags (rollout gating, beta kill-switches) used to hide/show in-progress surfaces per the §14 status matrix. Vendor-isolated: `posthog-node` is imported only by this package (enforced by `pnpm check:vendor-isolation`).

Fail-safe by contract: any unknown flag or evaluation error resolves to `false` — i.e. the feature stays **Hidden**. Flags gate UI/route exposure only; they are NOT the source of truth for commercial entitlement (that remains the license envelope + `entitlements` table).

Stability: **internal** (L2 binding). Distribution: cloud + web.

## Public exports

- `PostHogFlagProvider` — class implementing `FeatureFlagProvider` from `@agentskit/os-core` over `posthog-node`. Constructed as `new PostHogFlagProvider({ apiKey, host? })` (accepts an optional injected client for tests). Its methods: `isEnabled` returns `true` only on an explicit boolean `true` from PostHog (unknown flags and errors → `false`); `getAllFlags` returns a `Record<string, boolean>` (multivariate variants coerce to `false`, errors → `{}`); `shutdown` is a best-effort flush/close.
- `PostHogFlagProviderOptions` — constructor options type (`apiKey`, `host?`, optional injected client).
- `PostHogClientLike` — the minimal `posthog-node` client shape the provider depends on (enables test injection).

Key types (from `@agentskit/os-core`):

```ts
// packages/os-core/src/ports/feature-flags.ts
interface FeatureFlagProvider {
  isEnabled(key: string, ctx?: FlagContext): Promise<boolean>
  getAllFlags(ctx?: FlagContext): Promise<Record<string, boolean>>
}
type FlagContext = { distinctId?: string; orgId?: string; properties?: Record<string, unknown> }
```

The canonical flag-key catalog (`FEATURE_FLAGS` / `FeatureFlagKey`) also lives in `@agentskit/os-core` (`feature-flags-catalog.ts`): `web-primary-surface`, `generative-nl`, `marketplace-publish`, `third-party-importers`, `regulated-verticals`, `advanced-cloud-sync`, `sso-extended-providers`, `external-mutating-automations`. All default OFF.

## Wired stores

None — this is a provider binding. The `FeatureFlagProvider` it produces is injected into `apps/cloud` (server-side route gating) and evaluated for `apps/web` (beta UI gating). When `POSTHOG_API_KEY` is unset the apps use `NoopFlagProvider` (from `@agentskit/os-core`), which returns `false` for every flag.

## Methods implemented

Not a JSON-RPC surface. `FeatureFlagProvider` is consumed by service/route code in `apps/cloud` and server code in `apps/web`.

## Methods consumed

- PostHog feature flags via `posthog-node` (`isFeatureEnabled`, `getAllFlags`) against the configured PostHog project (`POSTHOG_API_KEY`, `POSTHOG_HOST`).

## Common questions

> **What happens when PostHog is unreachable or the flag is unknown?**
> The provider returns `false` (and `getAllFlags` returns `{}`). Fail-safe: the gated feature stays Hidden. Never throws into the request path.

> **Should I put a paid-plan entitlement behind a flag?**
> No. Flags are for rollout/visibility/kill-switch only. Commercial entitlement is enforced by the signed license envelope + the `entitlements` table — do not duplicate it here.

> **How do I gate a new beta surface?**
> Add a key to `FEATURE_FLAGS` in `@agentskit/os-core`, create the flag in PostHog, and check `provider.isEnabled(key, ctx)` server-side (cloud route) or via the web flag evaluator. Absent flag ⇒ Hidden.

> **Why is `posthog-node` vendored here and not in os-core?**
> ADR-0064 layered architecture: `posthog-node` is an L2 binding. L0 (`os-core`) holds only the `FeatureFlagProvider` contract + the `NoopFlagProvider`; the vendor is swappable without touching the domain.

## Error codes

`FLAG_ERROR_CODES` (in `@agentskit/os-core`): `AK_FLAG_PROVIDER_INIT_FAILED`, `AK_FLAG_EVALUATION_FAILED`. In practice evaluation failures are swallowed to the fail-safe `false`; the codes exist for explicit init/diagnostic paths.

Source: /raw/for-agents/packages/os-flags-posthog.md

### for-agents/packages/os-flow.md

# packages/os-flow

## Purpose

Durable, cycle-safe DAG executor for AgentsKitOS flows. Converts a
`FlowConfig` to an adjacency graph, validates it via topological sort,
runs nodes through a pluggable `NodeHandlerMap`, and enforces security via an
optional firewall/redaction hook. The invariant is that no cycle can execute:
`runFlow` topo-sorts up front and, when `topoSort` reports a cycle
(`{ ok: false, cycle }`), returns `{ status: 'failed', reason: 'cycle: …' }`
before any node runs. (The visual-layer `FlowDefinition` is a separate type —
`flowFromVisual` / `assertVisualRoundTrip` operate on it; the executor itself
consumes `FlowConfig`.)

## Public exports

- Visual/schema: `FlowDefinition`, `FlowStep`, `VisualEdge`, `VisualFlow`,
  `VisualNode`, `VisualNodeKind`, `assertVisualRoundTrip`, `flowFromVisual`,
  `flowToVisual`, `RoundTripResult`, `ToVisualOpts`
- Graph utilities: `buildAdjacency`, `reachableFrom`, `findUnreachable`,
  `topoSort`, `auditGraph`, `nodeKindOf`, `Adjacency`, `AdjacencyEntry`,
  `EdgeOn`, `GraphIssue`
- Handlers: `composeHandlers`, `defaultStubHandlers`, `NodeHandler`,
  `NodeHandlerMap`, `NodeOutcome`
- Security hook: `withSecurityHook`, `SecurityHookOpts`
- Editor palette: `NODE_PALETTE`, `PALETTE_BY_CATEGORY`, `findPaletteEntry`,
  `stableKinds`, `NodePaletteCategory`, `NodePaletteEntry`
- Editor canvas: `DEFAULT_VIEWPORT`, `MAX_ZOOM`, `MIN_ZOOM`, `initialCanvasState`,
  `reduceCanvas`, `CanvasAction`, `CanvasState`, `Viewport`
- Debug controller: `createDebugController`, `BeforeNodeVerdict`, `DebugController`,
  `DebugMode`, `DebugSnapshot`
- Runner: `runFlow`, `RunResult`, `RunOptions`, `CheckpointFn`
- Observability: `FlowCostTickEvent`
- Circuit breaker: `createCircuitBreaker`, `CircuitBreaker`, `CircuitBreakerOpts`,
  `CircuitBreakerSnapshot`, `CircuitState`
- Cost / budget: `cancelOnBudget`, `createFlowCostMeter`
- Watchdog: `evaluateFlowWatchdog`, `FlowWatchdogOpts`, `RunHeartbeat`,
  `WatchdogAction`, `WatchdogVerdict`
- Graceful degradation: `runWithGracefulDegradation`, `DegradationAttempt`,
  `DegradationOpts`, `DegradationOutcome`, `DegradationReport`
- Cost meter types: `FlowCostMeter`, `FlowCostMeterOpts`, `FlowCostMeterUpdate`
- Cost estimator: `estimateFlowCost`, `priceKey`, `NodeCostEstimate`,
  `FlowCostEstimate`, `AgentMap`, `PriceMap`, `EstimateOptions`
- Hot-reload: `detectHotReloadConflicts`, `HotReloadConflict`, `HotReloadRunSnapshot`
- What-if simulator: `simulateWhatIf`, `WhatIfReport`, `SimulationStep`,
  `RecordedRunTrace`, `RecordedNodeStep`, `NodeOutcomeProjector`
- Pipeline export: `buildPipelineExport`, `PipelineExportArtifact`,
  `PipelineExportInput`, `PipelineExportTarget`
- Template seeds: `FLOW_TEMPLATE_SEEDS`, `findFlowTemplateSeed`, `FlowTemplateSeed`
- Temporal-style durability: `createActivityLedger`, `createSignalChannel`,
  `runActivity`, `ActivityLedger`, `ActivityResult`, `SignalChannel`
- Chaos harness: `runUnderChaos`, `ChaosFault`, `ChaosOutcome`, `ChaosPlan`, `ChaosRule`
- Automation rules: `AutomationAction`, `AutomationEventMatcher`,
  `AutomationRule`, `AutomationRuleSet`, `matchAutomationRules`,
  `parseAutomationRuleSet`, `safeParseAutomationRuleSet`, `AutomationDispatch`,
  `AutomationEvent`
- Mode policy: `applyModeStubs`, `validateDeterministicFlow`, `policyForMode`,
  `AgentRegistryEntry`, `ToolRegistryEntry`, `DeterminismValidationInput`
- Durable resume: `InMemoryCheckpointStore`, `resumeFlow`, `CheckpointStore`,
  `CheckpointRecord`, `DurableRunResult`, `ResumeOptions`
- Event bus bridge: `createBusOnEvent`, `FLOW_EVENT_TYPES`, `BridgeOptions`,
  `BridgeEvent`, `FlowEventType`
- Tool policy: `createPolicyToolHandler`, `InMemoryToolManifestRegistry`,
  `ToolManifestRegistry`, `ToolPolicyDecisionEvent`, `PolicyToolHandlerOptions`
- Multi-agent handlers: `createCompareHandler`, `createVoteHandler`,
  `createDebateHandler`, `createAuctionHandler`, `createBlackboardHandler`,
  `InMemoryScratchpadStore` (+ option/fn types)
- Event-sourced snapshot (#205): `captureSnapshot`, `outcomesFromSnapshot`,
  `buildSnapshotEmitter`, `RunSnapshot`, `SnapshotInput`, `SnapshotOptions`
- Branch-from-step replay (#206): `branchFromSnapshot`, `FlowBranchError`,
  `BranchFromSnapshotOptions`, `BranchResult`, `BranchOverride`
- Live debugger (#64): `createInMemoryDebugger`, `DebuggerMode`, `DebuggerState`,
  `FlowDebugger`, `NodeId`, `Debugger{Before,After}Node*`
- Two-person HITL (#188): `createHumanHandler`, `ApproverGate`,
  `ApproverGateDecision`, `HumanHandlerOptions`
- Semantic flow diff (#172): `diffFlowSemantics`, `renderFlowDiffMarkdown`,
  `FlowSemanticDiff`, `FlowNodeChange`, `FlowEdgeChange`
- Git-diff-as-input (#193): `createGitDiffNodeHandler`, `createGitDiffToolCall`,
  `parseUnifiedGitDiff`, `GIT_DIFF_TOOL_NAME`, `GitDiff*` schemas/types
- Escalation engine (RFC-0008 / #787): `advanceEscalation`, `runEscalation`,
  `isTerminal`, `TERMINAL_STATES`, `HitlGate`, `HitlGateInput`,
  `HitlGateResult`, `AdvanceEscalationOptions`, `OnHitlAutoApprove`
- Also exported: `detectFlowShape`, `flowConfigToVisual`,
  `visualFlowToFlowConfig`

## Wired stores

None. Checkpoint persistence is supplied by the caller via `CheckpointFn`
(typically backed by `os-storage/SqliteCheckpointStore`). The executor
itself holds no stores.

## Methods implemented / consumed

None — library only. `runFlow` is invoked by `os-headless/src/runner.ts`
which also wires the security hook, cost meter, and checkpoint store.

## Common questions

> **How do I add a new node kind?**
> Add a `NodePaletteEntry` to `NODE_PALETTE` in `editor-palette.ts`, then
> implement a `NodeHandler` and register it in the `NodeHandlerMap` passed
> to `runFlow`. The palette entry controls what the visual editor renders;
> the handler controls execution.

> **How does the security hook intercept node execution?**
> Wrap a single handler with `withSecurityHook(handler, opts)`, where `opts`
> is a `SecurityHookOpts` carrying an os-core `SecurityEnforcer`
> (`{ enforcer, onBlock?, onRedact? }`). Before dispatch the hook runs the
> enforcer's `evaluatePromptVerdict` over every textual input slot; a
> disallowed verdict short-circuits to a `failed` outcome with code
> `firewall.blocked` (and fires `onBlock`). Otherwise it runs
> `redactString` on each slot, rewriting matches in place on a clone before
> the handler sees the input (and fires `onRedact` with the match count).
>
> **Which input shapes are inspected?** (SEC-5 #1677) The hook collects
> every textual slot, not just top-level `prompt`/`text`/`input`: it also
> recurses `messages[*].content` and top-level `content`, where `content`
> may be a string or an array of `{ type:'text', text }` parts. The
> firewall sees all slots joined; the redactor rewrites each slot in place
> on a clone (the caller's input object is never mutated). A real
> chat-adapter envelope (`{ messages:[{ role, content }] }`) is therefore
> fully covered — earlier builds inspected only the top-level fields and
> let chat payloads bypass both firewall and redaction.

> **How do I unit-test a flow without a real LLM?**
> Pass `defaultStubHandlers` as the `NodeHandlerMap` to `runFlow`. Stub
> handlers return the node's `stub` field verbatim, enabling fast, offline
> graph-traversal tests with no network calls.

Source: /raw/for-agents/packages/os-flow.md

### for-agents/packages/os-for-agents.md

# packages/os-for-agents

## Purpose

Catalog builder and MCP server for the RFC-0012 for-agents surface. Walks
the `os-contracts` registry and emits a `ForAgentsCatalog` (and
`llms.txt`) that agents and tools consume to discover available verbs,
triggers, connectors, and error codes. Also exposes an MCP tool server so
external agents can query and navigate the catalog without direct package
imports, and provides ADR-0136 RBAC-gated security management tools
(firewall rules, egress policy, PII profiles) over MCP.

It additionally exposes the RFC-0053 / ADR-0155 **Agent Authoring Gateway**
over MCP (`authoring.*` tools): a deterministic discovery → plan → clarify →
validate → repair → preview → dry-run → approval → apply trail an external
agent follows to author AgentsKitOS artifacts (agents, flows, triggers,
pipelines) from natural language.

## Public exports

### Catalog builder

- `contractToCliVerb(contract)` — converts a single `AnyMethodContract` to a `CliVerbDescriptor`
- `registryToCliVerbs(registry)` — converts all contracts in a `ContractRegistry` to sorted `CliVerbDescriptor[]`
- `buildCatalogFromRegistry(input)` — walks a registry and emits a `ForAgentsCatalog`
- `BuildCatalogFromRegistryInput` — input type for `buildCatalogFromRegistry`

### MCP server

- `createForAgentsMcpHandlers(catalog, opts?)` — returns a `McpServerHandlers` object with all tool implementations
- `FOR_AGENTS_MCP_TOOL_DESCRIPTORS` — static array of MCP tool descriptor objects for server registration
- `McpServerHandlers` — interface describing all handler functions
- `CreateForAgentsMcpHandlersOpts` — options bag for `createForAgentsMcpHandlers` (includes optional `dispatch`)
- `SecurityDispatch` — RBAC-preserving dispatch seam type (ADR-0136)
- `SecurityDispatchResult` — union type for dispatch results (`ok: true | false`)

### Authoring gateway (RFC-0053 / ADR-0155)

- `createAuthoringMcpHandlers(opts?)` — returns an `AuthoringMcpHandlers` object; the pure discovery handlers (`authoringManifest`, `authoringNodeKinds`) need no transport, the proxy handlers (`authoringActionsList`, `authoringActionsDescribe`, `authoringValidate`) require an injected `dispatch`
- `FOR_AGENTS_AUTHORING_MCP_TOOL_DESCRIPTORS` — static array of MCP tool descriptor objects for the `authoring.*` tools
- `AUTHORING_MANIFEST_VERSION` — version string of the authoring MCP surface
- `AUTHORING_PROXY_VERSION` — compatibility version for the authoring proxy capability contract
- `AUTHORING_PROXY_CAPABILITIES` — explicit v1 capability promises (`pure-discovery`, read-only proxying, local dispatch only, fail-closed missing dispatch, no network IO, no state mutation)
- `AuthoringMcpHandlers` — interface describing the authoring handler functions
- `CreateAuthoringMcpHandlersOpts` — options bag (optional `dispatch`)
- `AuthoringDispatch` — RBAC-preserving dispatch seam type for the authoring proxy tools
- `AuthoringDispatchResult` — union type for authoring dispatch results (`ok: true | false`)
- Zod schemas / inferred types: `AuthoringProxyCapability`, `AuthoringManifestInput`, `AuthoringManifestOutput`, `AuthoringActionsListInput`, `AuthoringActionsDescribeInput`, `AuthoringNodeKindsInput`, `AuthoringNodeKindsOutput`, `AuthoringValidateEntity`, `AuthoringValidateInput`, `AuthoringMethodDescriptor`, `AuthoringNodeKind`

### Zod schemas and inferred types (all named exports)

Catalog / doc tools:
- `DocSearchInput`, `DocSearchOutput`, `DocSearchHit`
- `DocGetInput`, `DocGetOutput`
- `CapabilitiesListInput`, `CapabilitiesListOutput`

Security tools (ADR-0136):
- `FirewallRule`, `FirewallRulesListInput`, `FirewallRulesUpsertInput`,
  `FirewallRulesDeleteInput`, `FirewallRulesShadowInput`
- `EgressPolicy`, `EgressPolicyGetInput`, `EgressPolicySetInput`
- `PiiProfile`, `PiiProfilesListInput`, `PiiProfilesUpsertInput`,
  `PiiProfilesDeleteInput`

## Wired stores

None. The catalog is built on demand from the in-memory contract registry.
No SQLite, no network IO.

## Methods implemented / consumed

Library — no JSON-RPC methods owned. The MCP tool descriptors in
`FOR_AGENTS_MCP_TOOL_DESCRIPTORS` are served by the sidecar's MCP endpoint,
not through the workspace JSON-RPC surface.

MCP tools exposed:

- `doc.search` — full-text search over catalog descriptors; returns ranked `DocSearchHit` list
- `doc.get` — fetch a single descriptor by id and optional kind disambiguator
- `capabilities.list` — enumerate capability ids accessible to a principal
- `firewall.rules.list` — list firewall rules (requires `security:admin`)
- `firewall.rules.upsert` — create or update a firewall rule (requires `security:admin`)
- `firewall.rules.delete` — delete a firewall rule by id (requires `security:admin`)
- `firewall.rules.shadow` — toggle a rule into/out of `dry_run` mode (requires `security:admin`)
- `egress.policy.get` — read the active outbound network policy (requires `security:admin`)
- `egress.policy.set` — replace the active outbound network policy (requires `security:admin`)
- `pii.profiles.list` — list custom PII redaction profiles (requires `security:admin`)
- `pii.profiles.upsert` — create or update a PII redaction profile (requires `security:admin`)
- `pii.profiles.delete` — delete a PII redaction profile by id (requires `security:admin`)

Authoring gateway tools (`FOR_AGENTS_AUTHORING_MCP_TOOL_DESCRIPTORS`, RFC-0053):

- `authoring.manifest` — discovery document: the Action Registry (intent → canonical RPC + required gates), the flow node-kind catalog, the callable authoring methods, the deterministic authoring trail, and explicit `authoringProxyVersion`/`capabilities`; optionally filter actions by entity. Pure discovery, no transport required
- `authoring.actions.list` — list agent-performable actions, optionally filtered by entity (proxies the Action Registry; requires `runs:read`)
- `authoring.actions.describe` — describe one action by id, including its canonical RPC and required gates (requires `runs:read`)
- `authoring.nodeKinds` — list flow node kinds and whether each is supported. Pure discovery, no transport required
- `authoring.validate` — validate a draft artifact for an entity (`agent` / `flow` / `pipeline`) via the entity's `*.validateDetailed` RPC (requires the entity read capability)

Consumed: `os-core` (`buildForAgentsCatalog`, `buildCapabilityManifest`, `filterCatalogByCaps`,
`idForDescriptor`, `SCHEMA_ONLY_REGISTRY`, `AgentsKitError`, `ErrorCodes`);
`os-contracts` (`AnyMethodContract`, `ContractRegistry`).

## Common questions

> **How do I regenerate `llms.txt`?**
> Run `akos docs export --out docs/for-agents` (or `agentskit-os docs export`)
> from the repo root. The CLI calls `buildCatalogFromRegistry` against the
> live contract registry and writes the catalog + `llms.txt` to the output
> directory (default `.agentskitos/for-agents`).

> **How does `buildCatalogFromRegistry` assign side-effect tiers?**
> An explicit contract `sideEffectTier` always wins. Legacy contracts fall
> back to `SIDE_EFFECT_BY_PREFIX` regexes (for example `\.delete$` →
> `destructive`, `\.list$` → `read`, `\.write$` → `write`). An unclassified
> legacy name fails closed as `destructive`, never `read`. Tiers flow into the
> `ForAgentsDescriptor` so agents can filter by risk level.

> **Can I add custom descriptors beyond JSON-RPC methods?**
> Yes — pass optional fields on `BuildCatalogFromRegistryInput`:
> `flowNodeKinds` (flow node descriptors), `triggers`, `connectors`, `events`,
> and `errors`. They are merged into the catalog with the appropriate `kind`
> tag before the MCP server indexes them.

> **How does the security dispatch seam work?**
> Pass a `SecurityDispatch` function in `CreateForAgentsMcpHandlersOpts.dispatch`.
> Each security MCP tool validates its Zod input then forwards it through the
> dispatcher, which applies the `security:admin` capability gate. If `dispatch`
> is omitted, catalog tools (`doc.search`, `doc.get`, `capabilities.list`) still
> work; any security tool throws `AK_CONFIG_INVALID` rather than silently
> skipping the gate (ADR-0136).

> **How does an external agent discover the natural-language authoring path?**
> Call `authoring.manifest` (via `createAuthoringMcpHandlers().authoringManifest`).
> Its `authoringProxyVersion` and `capabilities` fields describe the v1 proxy
> contract explicitly: pure discovery, read-only action registry proxying,
> read-only draft validation, local dispatch only, fail-closed missing dispatch,
> no network IO, and no state mutation. Its `methods` list names every callable
> authoring method, including the four
> NL→draft compilers — `flows.fromNL`, `agents.fromNL`, `triggers.fromNL`,
> `pipelines.fromNL` — each of which turns a description into a draft artifact
> (it applies nothing; apply happens via the canonical create RPC afterwards).
> The `actions` list maps each authoring intent to its canonical RPC and the
> gates it must pass; for NL drafting, `flow.draft` → `flows.fromNL` and
> `trigger.draft` → `triggers.fromNL` are wired as Action Registry entries. The
> authoring gateway is a static projection of the Action Registry and node-kind
> catalog, so the discovery tools answer with no transport wired; the proxy
> tools (`authoring.actions.*`, `authoring.validate`) require an injected
> `AuthoringDispatch` or throw `AK_CONFIG_INVALID`.

Source: /raw/for-agents/packages/os-for-agents.md

### for-agents/packages/os-generative.md

# packages/os-generative

## Purpose

Agent harness, fork/clone variation, meta-agent specs, NL-to-agent
extraction, self-heal policy, variant evaluation, and what-if simulation.
Provides read-only views over generative machinery in `os-core` plus
higher-level orchestration helpers. The invariant is that no LLM calls are
made by pure extraction/classification functions — LLM invocation is always
opt-in via `LlmInvokeFn` callbacks.

## Public exports

- Agent harness (re-exported): `createAgentHarness`, `AgentHarness`, `HarnessAgent`,
  `HarnessAgentState`, `HarnessAuditEntry`, `HarnessOpts`
- Clone/fork (re-exported): `cloneAgentWithVariation`, `forkAgentConfig`,
  `forkWorkspaceConfig`, `CloneVariation`, `CloneVariationInput`, `ForkOptions`
- Meta-agent (re-exported): `childRoleMap`, `parseMetaAgentSpec`,
  `safeParseMetaAgentSpec`, `MetaAgentChild`, `MetaAgentDelegationStrategy`,
  `MetaAgentSpec`
- Agent gen (re-exported): `extractAgentGenSpec`, `parseAgentGenSpec`,
  `safeParseAgentGenSpec`, `AgentGenIntent`, `AgentGenSpec`
- LLM intent extractor: `createLlmIntentExtractor`, `LlmInvokeFn`, `LlmIntentExtractorOpts`
- Self-heal: `evaluateSelfHeal`, `SelfHealAction`, `SelfHealPolicy`,
  `FailureContext`, `SelfHealVerdict`, `Patch`, `PatchKind`, `proposePatch`, `FailurePattern`
- NL extraction: `parseAgentIntent`, `AgentIntentSchema`, `AgentIntent`
- Draft generation: `generateAgentDraft`, `DraftAgentConfig`, `generateFlowDraft`,
  `DraftFlowConfig`, `DraftFlowConfigType`
- Variant evaluation: `compareVariants`, `DEFAULT_WEIGHTS`, `CompareReport`,
  `CompareWeights`, `VariantAxis`, `VariantEvaluation`, `VariantRanking`, `VariantScorecard`,
  `containsScorer`, `exactMatchScorer`, `runVariantEval`, `VariantDispatchFn`,
  `VariantEvalCase`, `RunVariantEvalOpts`, `Scorer as VariantScorer`, `VariantEvalResult`,
  `VariantPrompt`
- What-if simulation: `simulateWhatIf`, `RunSnapshot`, `WhatIfChange`, `WhatIfReport`,
  `createLlmWhatIfEstimator`, `LlmWhatIfEstimatorOpts`
- Topology planner: `createLlmTopologyPlanner`, `LlmTopologyPlannerOpts`
- Constants: `PACKAGE_NAME`, `PACKAGE_VERSION`

## Wired stores

None. LLM calls and audit persistence are supplied by the caller. Harness
audit entries are persisted by the caller via `HarnessOpts.onAuditEntry`.

## Methods implemented / consumed

Implemented (owner `@agentskit/os-generative`):

- `agentGen.parse` — parse a NL description into a structured `AgentIntent`
  (in `os-contracts/src/methods/generative.ts`)
- `flows.fromNL` — generate a draft `FlowConfig` from a NL description
  (in `os-contracts/src/methods/integrations.ts`)

Self-heal policy surface (H1 #3817 — schema canonical in os-core as
`SelfHealPolicy`; persisted on `WorkspaceConfig.selfHealPolicy`; handlers owned
by `@agentskit/os-headless`, declared in
`os-contracts/src/methods/workspace.ts`):

- `workspace.config.selfheal.get` — read the workspace self-heal policy
  (recovery actions on node failure); cap `workspace:config`.
- `workspace.config.selfheal.set` — persist the policy; applies on the next run;
  cap `workspace:config`. Toggle lives in **Settings → Orchestration**.

The sidecar runner honors `enabled`: at boot
(`os-headless/src/bin/sidecar-parts/runner-setup.ts`) it wires the self-heal
hook (`self-heal-hook.ts`, which calls `evaluateSelfHeal`) **only when**
`selfHealPolicy?.enabled` is true. With the policy disabled (or absent) no
self-heal hook runs.

Consumed: `os-core` for harness/fork/meta-agent primitives.

## Common questions

> **How do I run variant evaluation without an LLM?**
> Use `containsScorer` or `exactMatchScorer` as the `Scorer` in
> `runVariantEval`. Both are pure string matchers. Wire an `echoDispatch`
> from `os-copilot` as the `DispatchFn` to return fixed outputs.

> **How does self-heal decide which patch to propose?**
> `evaluateSelfHeal` returns a `SelfHealVerdict` with an `action` field.
> Call `proposePatch(failurePattern)` to get a concrete `Patch`. Patches are
> deterministic given the same failure context — no LLM call is made by
> either function.

> **How do I wire `createAgentHarness` in a test?**
> Pass a minimal `HarnessOpts` with a stub `dispatch` function and
> `onAuditEntry: () => {}`. The harness runs in `trace` mode by default
> (no LLM budget consumed). Set `mode: 'real'` only in integration tests
> with a real provider key.

Source: /raw/for-agents/packages/os-generative.md

### for-agents/packages/os-headless.md

# packages/os-headless

## Purpose

JSON-RPC stdio sidecar. Single entry point for every desktop / CLI /
MCP client. Composes 19 handler maps into one `HandlerMap`, fronts them
with RBAC middleware, persists everything to SQLite (when available)
or in-memory (test/dev). Owns the runner, the trigger daemons, the
copilot bootstrap, and the audit ledger.

## Public exports

- `bin/sidecar.ts` — process entry.
- `createDefaultHandlers(opts)` from `transport/handlers.ts` — host
  composition factory.
- `createHeadlessRunner(opts)` from `runner.ts` — real flow runner.
- `createCopilotBootstrapHandlers(opts)` — copilot session + RAG +
  dispatch handler family.
- `bootTriggerDaemons(opts)` — Postgres CDC + IMAP poller bootstrap.

## Wired stores (via `PersistentStores`)

`workspace`, `run`, `trigger`, `trace`, `flow`, `ledger`, `sandboxPolicy`,
`egressPolicy`, `mcpServers`, `externalSecrets`, `rbacRoles`,
`consent`, `collab`, `brandKit`, `installedPacks`, `agentInline`,
`users`, `teams`, `evalSuites`, `evalResults`, `knowledge`,
`copilotSession`, `copilotConfig`, `copilotGrant`, `hitlEscalation`,
`cost`, `breakGlass`, `agentOverrides`, `hitlGate`. Sqlite when
`better-sqlite3` is installed; in-memory otherwise (loud warn).

RES-1 (#1675): `resolvePersistentStores` classifies SQLite open failures via
`classifySqliteError` → `SqliteFailureKind`: `retriable` (`SQLITE_BUSY` /
`SQLITE_LOCKED`, retried up to `maxSqliteAttempts` (default 3) with
`sqliteRetryBackoffMs` (default 500ms) blocking backoff), `missing-native`
(`better-sqlite3` not installed → `sqlite-missing-native`, no retry), or
`fatal` (corrupt/permission → `sqlite-unavailable`, no retry). Each
`StoreDegradeReason` (now carrying `kind` + `attempts`) is passed to the
`onDegrade` callback; the sidecar wires it to a `runtime.degraded`
notification event so the desktop renders a banner instead of the fallback
being log-only. Encryptor-unavailable (SEC-2 / #1665) still escapes the
retry loop unretried (fail-secure).

## Methods implemented

Full list in `STATUS.md` at repo root. 271 handlers across:

- `workspace.*`, `flows.*`, `triggers.*`, `runs.*`, `traces.*`
- `runner.*`, `agents.*`, `copilot.*`, `hitl.*`
- `security.agentIdentity.status|rotate` — RFC #1248 SU2 per-workspace
  agent-signing key (DID + fingerprint + rotation history; private key
  never returned). `agents.upsert` auto-signs (lifecycle ≥ approved)
  from this store.
- `marketplace.*`, `sdlc.*`, `access.breakGlass*`
- `evals.*`, `users.*`, `teams.*`, `cmdk.*`
- `runtime.status` — readiness snapshot

`buildRealRunner` constructs a `SandboxRegistry` (`none`/`process` built-ins
+ Docker for `container`) and threads it + `FlowConfig.sandbox` through
`setupRun` so the agent handler enforces `resolveFlowSandbox` before the LLM
call (#1133 SU2). Tunable: `AKOS_SANDBOX_IMAGE`,
`AKOS_SANDBOX_WORKSPACE_ROOT`, `AKOS_SANDBOX_NETWORK`.

#1133 SU3 wires the denials/egress bridge: connector tools
(Slack/GitHub/Linear/Notion) run on `buildEgressGuardedFetch(egressPolicyStore)`
so a flow reaching `evil.example` is denied (SSRF blocklist + workspace
allowlist) and the decision is appended to the egress ring. The agent
handler's structural `onSandboxDenied` callback is bridged into
`SandboxPolicyStore.recordDenial` via `setupRun` (new
`HeadlessRunnerOptions.sandboxPolicyStore?`), so policy/availability denials
survive sidecar restart and feed the audit/notifications surface.

#1133 SU4 closes the trace-PII gap: the SU2 `security.redactor` only masks
the *LLM input* prompt, so an SSN-shaped string in an agent answer reached
the persisted trace verbatim (`RunRecord.steps[*].output`, `RunRecord.output`,
`TraceRecord.spans[*].attrs`). `src/trace-redaction.ts` adds write-through
`withRedactedRunStore` / `withRedactedTraceStore` decorators that deep-redact
every string before `upsert`; `persistent-stores.ts` wraps the run + trace
stores (memory and SQLite) so every persist path (real flow, `runAgent`,
replay, stub) is covered. Default profile is `pii-strict` (SSN/PII/secrets) —
independent of the live `AKOS_REDACTION_PROFILE`; override with
`AKOS_TRACE_REDACTION_PROFILE`.

#1133 SU5 surfaces prompt-firewall blocks. The runner publishes
`firewall.blocked` onto the trace bus (drained only by the span collector),
so hits were silently dropped. `sidecar.ts` bridges `firewall.*` from
`traceWiring.bus` onto the `NotificationChannel`, so the desktop classifier
renders a jailbreak in Notifications; `wireAuditSubscriber` now also appends
`firewall.*` and `sandbox.*` to the audit ledger (security block/denial
auditing), not just agent/tool/flow lifecycle.

## Tenant credential resolver

`src/credential-resolver.ts` owns the tenant-scoped credential resolution seam
used by real runner tools and future integration preflight surfaces. The
legacy `resolve(workspaceId, CredentialRef)` method remains compatible:
OAuth token → workspace `SecretStore` → effective env fallback.

New tenant-aware callers should use `resolveTenantCredential` or
`describeTenantCredential` with explicit auth modes:

- `oauth` — tenant OAuth connection token.
- `installation` — tenant app/bot installation token.
- `secret` — tenant vault key.
- `platform` — platform-owned env/config, e.g. OAuth app credentials.
- `dev_env_fallback` — local/dev env fallback, only active when
  `AKOS_DEV_CREDENTIAL_ENV_FALLBACK=1`.

`describeTenantCredential` returns the same status without raw token/API key
values and is the shape UI/preflight code should expose.

OAuth token vault references minted by `connections.tokens.get` include the
workspace id in the generated `oauthtok_*` key. Two tenants with the same
provider/account id therefore receive different vault refs and resolve back to
different stored tokens.
For the generic integration OAuth RPCs, `oauth.start` stamps the active
workspace into the pending state and `oauth.complete` forwards both
`LlmOauthTokenStore` and `InstallationTokenStore` to `os-oauth`. A Slack-like
callback with `team.id`, Discord `guild.id`, explicit `installation_id`,
Stripe `stripe_user_id`, or Atlassian `cloud_id` now persists a tenant
installation row as part of completion.

Installation-token resolution reads the workspace's latest connected
`InstallationTokenStore` row for the requested provider. It does not fall back
to global env vars; if no connected installation exists, resolution continues
to the next requested auth mode (`oauth`, `secret`, etc.) or reports missing.
GitHub App installation tokens are short-lived: lookup refreshes them when
they are within the refresh window and marks the installation
`reauthorization_required` if the app JWT/token exchange fails.
The operator-safe JSON-RPC surface is
`integrations.connections.installations.list/status/revoke`: these methods
return provider/account/status metadata plus `hasRefreshToken`, but never
`accessToken` or `refreshToken`.
Provider-specific setup lives on
`integrations.connections.installations.start/complete`. GitHub requires
`AKOS_GITHUB_APP_SLUG` for the install URL and
`AKOS_GITHUB_APP_ID` + `AKOS_GITHUB_APP_PRIVATE_KEY` for completion (the
handler signs a GitHub App JWT and calls
`/app/installations/{installationId}/access_tokens`). Discord requires
`AKOS_OAUTH_DISCORD_CLIENT_ID` for the bot invite URL and
`AKOS_DISCORD_BOT_TOKEN` for completion, persisted per guild id.

`integrations.connections.preflight` is the product-facing readiness probe for
tenant setup. Each missing row includes an actionable `action` value:
`connect_oauth`, `connect_installation`, `configure_secret`, or
`platform_missing`. Legacy `envVarHints` remains for older UI/error copy, but
new tenant setup surfaces should key off `action`.

`integrations.connections.setupRegistry.list` is the source of truth for
provider setup guidance consumed by UI and assistant flows. Read it before
rendering provider cards or answering "how do I connect X?". Prefer
`preferredSetupMode` over ad hoc env-key inference: OAuth and tenant
app/bot install paths must be shown before guided secret fallback, and raw
keys should only be requested when the registry says no friendlier path is
available. The registry also carries CTA copy, scopes, health-check method,
docs/credential URLs, assistant instructions, and `implementationStatus`.
Assistant and UI surfaces must use `implementationStatus` to avoid over-
promising: `real` can be treated as runnable after health check,
`preflight_only` is setup/readiness guidance until runtime is verified,
`platform_managed` belongs to operators, `dev_env_fallback` is local smoke
only, and `unsupported` needs a fallback path.
The handler also materializes `guidance` for each provider; prefer its
`primaryAction`, `caveat`, and `canPresentAsLiveAfterHealthCheck` over
re-deriving status copy in UI or assistant surfaces.

`capabilities.resolve`, `onboarding.ecosystem.detect`, and
`onboarding.blueprint.generate` enrich `needs_connection` resolutions with a
`setup` object derived from the same registry. Onboarding/chat surfaces should
use `resolution.setup.primaryAction`, `resolution.setup.caveat`, and
`resolution.setup.mode` instead of generic "connect provider" copy whenever the
field is present.

## Invariants & gotchas

- **Every JSON-RPC method MUST have a Zod contract in `@agentskit/os-contracts` before adding a handler.** The dispatcher in `os-contracts` checks the registry first: a method with no registered contract returns `METHOD_NOT_FOUND`; a method with a contract but no handler returns `HANDLER_NOT_REGISTERED`. Neither path reaches the handler. Crucially, a contract with no `capsRequired` (or `capsRequired: []`) bypasses the RBAC capability check entirely — such handlers execute for any caller, so any method that should be gated MUST declare its capabilities in the contract.
- **`src/bin/sidecar-parts/**` is boot-wiring excluded from coverage intentionally.** These files run `process.exit` at import-time on bad env and cannot be v8-instrumented in-process; they are exercised by end-to-end sidecar tests. The `vitest.config.ts` coverage block explicitly lists `**/bin/sidecar-parts/**` as excluded. Do not remove that exclusion to chase a coverage number — you will get 0 % hits and a failing threshold.
- **The transport speaks JSON-RPC 2.0 over newline-delimited stdout.** `src/transport/stdio.ts` reads from stdin and writes responses to stdout; notifications are emitted as `{ jsonrpc:"2.0", method:"event", params:<TransportEvent> }` lines. Logging inside the sidecar uses `os-log` (`createLogger`) which writes to stderr — never stdout. Mixing log output into stdout corrupts the wire.
- **Enforcement mode is server-resolved, not caller-claimed.** `AKOS_RBAC_RPC_ENFORCEMENT` (default `'reject'`) is injected by the transport into every dispatch context; any `meta.enforcement` field from the wire is stripped (ADR-0130). Callers cannot self-downgrade to `'warn'` mode.
- **`allowAnonymousPrincipal: true` must be explicit for single-user local deployments.** Without it (and without `AKOS_DEV_NO_AUTH=1`), `resolvePrincipal` throws `AK_CONFIG_INVALID` if no `getPrincipal` resolver is wired. The production sidecar sets this flag; multi-tenant hosts must wire `getPrincipal` instead.

## Common questions

> **Why does my run finish with no spans?**
> Check `runtime.status.runner.mode`. If `synthesiser`, real runner
> failed to construct. Reason field carries the error.

> **How is the knowledge (RAG) pipeline wired for production?**
> `sidecar.ts` → `sidecar-parts/rag-store.ts` resolves the vector store
> (`AKOS_RAG_STORAGE_BACKEND`, prod default sqlite-vss; degrades to memory
> + `runtime.degraded`), `env-config.ts:buildKnowledgeRedactorFromEnv`
> injects the PII redactor into `createIndexer` (enforced before embed,
> `AKOS_RAG_PII_PROFILE`), and `sidecar-parts/rag-digest-scheduler.ts`
> cron-re-syncs sources (`AKOS_RAG_DIGEST_SCHEDULE`, default `manual`).
> Details + the env table: `docs/for-agents/packages/os-rag.md`
> "Production sidecar wiring".

> **How does copilot pick up a model override?**
> `agents.applyOverride` writes to `agentOverrides` store.
> `CopilotAgent.overrideResolver` reads it before `resolveModel`.

> **Where does the firewall fire?**
> `runner-security-factories.ts:buildFirewallEvaluator` is built from
> env (`AKOS_FIREWALL_*`) and passed into `createHeadlessRunner` as
> `security.firewall`. Every node handler is fronted by
> `withSecurityHook`.

> **How does the env-dispatch circuit breaker work? (FND-3, #1670)**
> `dispatch-from-env.ts:createCircuitBreaker` is a thin per-providerKind
> facade over `createKeyedCircuitBreaker` from `@agentskit/os-flow` —
> the single RFC-1567 (#1567) 3-state (closed/open/half-open) breaker.
> Policy: 3 consecutive terminal failures trip a key; ~60s open
> cooldown then a half-open probe; success resets. There is **no**
> parallel state machine here — `tests/dispatch-breaker-delegation.pin.test.ts`
> pins the delegation (structural + behavioral) so a concurrent-merge
> regression to a bespoke window breaker fails CI.

> **How does an external agent query AgentsKitOS over MCP? (Route-correction A3, #3485)**
> `bin/mcp-server.ts` (CLI: `agentskit-os mcp-serve`, bin: `agentskitos-mcp`) is
> an MCP **self-server**: an external agent spawns it over stdio and queries the
> runtime's capability catalog via `doc.search` / `doc.get` /
> `capabilities.list`. These handlers came from `@agentskit/os-for-agents`
> (tested but previously **unwired to any transport**). `bin/sidecar-parts/mcp-self-server.ts:dispatchMcpRequest`
> is the pure JSON-RPC dispatcher (`initialize` → protocol `2025-06-18` +
> `serverInfo`; `tools/list` → the three descriptors; `tools/call` → in-band
> `{content,isError}`); `runMcpStdioServer` wires it to newline-delimited
> JSON-RPC over stdin/stdout (the same framing the os-mcp-bridge **client**
> speaks — logs go to stderr). The catalog is built deterministically from the
> live `@agentskit/os-contracts` REGISTRY. Tests:
> `tests/mcp-self-server.test.ts` + os-cli `tests/commands-mcp-serve.test.ts`.

> **Where does the dashboard read the governance posture? (Route-correction A5, #3485)**
> `governance.posture` (gated by `observability:read`, so a non-admin reviewer
> can see it) returns the live posture in one read: air-gap, firewall, PII
> redaction, sandbox network, RBAC mode + default role, egress mode + rule
> count, and audit. The handler (`governance-posture-handler.ts` →
> `createGovernancePostureHandlers`, wired in `transport/handlers/governance.ts`)
> reads the same env (`AKOS_AIRGAP` / `AKOS_FIREWALL_*` / `AKOS_REDACTION_PROFILE`
> / `AKOS_SANDBOX_NETWORK` / `AGENTSKIT_RBAC_CAPABILITY_MODE`) + wired stores
> (egress policy, RBAC roles) the sidecar enforces with — replacing the need to
> stitch `security.bundle` (a policy *composer*, `security:admin`-gated) +
> several surfaces for the dashboard card. Tests:
> `tests/governance-posture.test.ts`.

> **Why does the sidecar warn that a webhook is unreachable? (Route-correction A3, #3485)**
> The webhook server binds to `AKOS_WEBHOOK_HOST` (default `127.0.0.1`) on
> `AKOS_WEBHOOK_PORT` (default `0` ⇒ ephemeral). That keeps the surface private
> by default, but a registered webhook trigger then has a URL no external
> system can reach. At boot, `trigger-bootstrap.ts` calls
> `webhook-server-parts/reachability.ts:assessWebhookReachability`; when inbound
> routes exist and the bind is loopback (or the port is ephemeral) it logs a
> `webhook reachability` warning and emits a `webhook.reachability` event
> (reason / url / message) so the desktop can surface it. To go public,
> `agentskit-os serve --public` sets `AKOS_WEBHOOK_HOST=0.0.0.0`
> (`--webhook-port <n>` pins the port) and prints a security warning — the bind
> default stays private; opening it is explicit. Tests:
> `tests/webhook-reachability.test.ts` + os-cli `tests/commands-serve.test.ts`.

> **How is air-gap mode enforced on the LLM path? (Route-correction A1, #3485)**
> `airgap-policy.ts:airGapPolicyFromEnv` reads `AKOS_AIRGAP` (`1|true|yes|on`
> → air-gapped) and builds an `AirGapPolicy` whose `localProviders` are the
> catalog's `local`-capability providers (`ollama`, `claude-cli`,
> `local-llama-cpp`) plus any ids in `AKOS_AIRGAP_LOCAL_PROVIDERS` (CSV).
> `createDispatchFromEnv` calls `enforceAirGapForProvider` before every real
> adapter call: a cloud provider under air-gap throws `AdapterError`
> (`AK_AIRGAP_BLOCKED`) **before any network attempt** — escaping the retry
> loop so the caller sees the air-gap denial, not a wrapped transient
> failure. This wires the previously-dead `airGapEnforce`
> (`@agentskit/os-core/security/airgap.ts`) onto the run path — the privacy
> proof the Healthcare hero demo asserts on. Pinned by
> `tests/airgap-policy.test.ts` + the `AKOS_AIRGAP` block in
> `tests/dispatch-from-env.test.ts`.

> **How does an agent send on a Connection with no inbound trigger?
> (RFC-0022 #1481 — `integrations.connections.push`)**
> `integration-connection-handlers.ts` exposes `integrations.connections.push`
> (cap `connections:push`, distinct from reactive `connections:send`). It
> mints the `OutgoingMessage` id/queuedAt, defaults `correlationId` to
> `push:<id>`, applies a token-bucket rate limit keyed per
> `(workspaceId, connectionId)` (reuses `transport/rate-limit.ts`
> `createRateLimiter`; tune via `pushRateLimit` opt, default 5rps/burst10),
> then routes through the **same** `createConnectionSendHandler` seam
> (egress-policy gate + `ConnectionSender` + idempotency ring + signed
> audit). A rate-limited push is audited (`integration.push`) and returns
> a `skipped` result with `retryAfterMs` — never an error. A
> **quiet-hours** gate runs *before* the rate budget: when
> `pushQuietHours.enabled` and the local minute-of-day is in
> `[startMinute, endMinute)` (overnight wrap supported) the push is
> audited (reason `quiet-hours`) and skipped. The window check is a tiny
> local pure helper, not an os-notifications dependency (that leaf/UI
> package has an identical private check; coupling it into headless
> egress for six lines is the worse trade). Capability + rate-limit +
> quiet-hours together cover the epic's push policy-gating task.

> **Why is `access.breakGlass` missing / why does startup throw
> `AK_BREAK_GLASS_PRINCIPAL_UNWIRED`?**
> SEC-4 (#1667). Break-glass grants are attributed to the calling
> principal and surfaced via `access.breakGlass.list`. Without a
> `getPrincipal` resolver every grant collapses to a synthetic
> `local-admin` actor, so the composition pass does **not** expose
> `access.breakGlass` unless attribution is trustworthy. If you wire a
> `breakGlassStore` but no `getPrincipal`, startup fails — wire
> `getPrincipal` (multi-tenant), or set `allowAnonymousPrincipal: true`
> for a single-user local deployment (the sidecar does this).

Source: /raw/for-agents/packages/os-headless.md

### for-agents/packages/os-import.md

# packages/os-import

## Purpose

Bundle import / export / diff. Ingests flows authored in other agent platforms (LangChain, LangGraph, Flowise, Langflow, Dify, n8n) and emits AgentsKitOS-native flow JSON, surfacing fidelity warnings for non-portable constructs.

## Public exports

### Detection and parsing

- `importWorkflow(input, registry?)` — detect + parse in one call (throws `AgentsKitError(AK_IMPORT_UNSUPPORTED)` if no importer matches).
- `detectImporter(input, registry?)` — match shape, return the first compatible `Importer`.
- `builtInImporters` — ordered registry of all 10 importers. Order matters: more-specific detectors first (agentskit-native, crewai, adk, autogen, langchain, langgraph, flowise, langflow, dify, n8n).
- `IMPORT_SOURCES` — flat `{ id, displayName }[]` derived from `builtInImporters`; UI source selectors consume this so a new importer auto-surfaces in every picker without per-screen changes.

### Per-source importers

Workflow/graph importers: `langchainImporter`, `langgraphImporter`, `flowiseImporter`, `langflowImporter`, `difyImporter`, `n8nImporter`.

BYO standalone-agent importers (issue #3845): `agentskitNativeImporter`, `crewaiImporter`, `adkImporter`, `autogenImporter`.

All ten are functional — there are no stubs.

### Types

- `Importer`, `ImporterRegistry`, `ImportResult`, `ImportWarning`
- `ImportedKnowledgeSource` — RAG component descriptor for host wiring (Langflow RAG path)
- `EnrichedImportResult`, `ResolutionCard`, `ResolutionKind`, `ResolutionStatus` — RFC-0032 enrichment output
- `LlmInvokeFn`, `ImportUsage` — RFC-0032 supporting types

### RFC-0032 LLM enrichment (migration wizard)

- `enrichImport(structural, rawSource, deps)` — async; layers an LLM over a structural `ImportResult`; each `ImportWarning` becomes a `ResolutionCard`. Requires `{ llmInvoke: LlmInvokeFn, grounding: GroundingBundle }`. Never throws on bad model output; degrades to `manual` cards or `unresolved` warnings.
- `applyResolutions(flow, cards)` — apply accepted/edited `ResolutionCard`s to a `FlowConfig`; re-validates with `parseFlowConfig`.
- `generateStructured(args)` — internal LLM-invoke + Zod-parse helper; exported for host re-use.
- `buildGroundingBundle(opts)` — assemble the curated system-prompt context block + closed tool-name set the LLM may map onto.
- Types: `GroundingDoc`, `ToolCatalogEntry`, `GroundingBundle`, `BuildGroundingBundleOpts`, `StructuredOk`, `StructuredErr`, `StructuredResult`, `GenerateStructuredArgs`.

### Digest scheduler (RFC-0010 §2)

- `createDigestScheduler(opts)` — returns a `DigestSchedulerDaemon` (`start()` / `stop()` / `running()`) that fires a `run` callback per source on a fixed interval.
- `parseScheduleToIntervalMs(schedule)` — converts `'manual'` / duration strings (`30s`/`15m`/`2h`/`1d`) / every-N-minutes cron (`*/5 * * * *`) to ms. Throws `ConfigError(AK_CONFIG_INVALID)` on unsupported formats.
- `buildDigestSchedules(opts)` — build `DigestSchedule[]` for cron-driven sources.
- `startCdcDigest(opts)` — subscribe a CDC-capable source; returns an unsubscribe fn or `null` (cron fallback).
- `wireKnowledgeDigest(opts)` — one-call wiring: CDC where supported, cron otherwise, nothing for `manual`.
- Types: `DigestSchedule`, `CreateDigestSchedulerOptions`, `DigestSchedulerDaemon`, `RunDigestFn`, `KnowledgeWatch`, `BuildDigestSchedulesOptions`, `StartCdcDigestOptions`, `WireKnowledgeDigestOptions`, `WiredKnowledgeDigest`.

## Wired stores

None. Pure transformation.

## Importer notes

- **langgraph** (`importers/langgraph.ts`) — functional. Agent/LLM nodes are
  **materialized** into real `AgentConfig` records whose ids match the flow
  nodes, so the imported flow references live agents (not dangling names);
  tool/function nodes → `tool` nodes; conditional nodes → `condition` nodes
  with a `__REQUIRES_MANUAL_EDIT__` predicate placeholder. `detect` is
  **strict** — it only claims an input carrying a graph-level `entry`/`exit`
  marker, a node with `data.runnable`, or every node exposing a semantic
  LangGraph `type`. It will **not** hijack Flowise / Langflow / generic
  react-flow exports that share the bare `{ nodes, edges }` shape. See
  [`docs/migrations/langgraph.md`](../../migrations/langgraph.md).
- **Real fixtures** — every importer has a real on-disk export fixture plus a
  regression test under `packages/os-import/tests/fixtures/` (e.g.
  `langgraph-research.graph.json`, `n8n-support-agent.workflow.json`,
  `flowise-support.chatflow.json`, `langflow-chat-rag.flow.json`,
  `dify-intake.dsl.yaml`, `langchain-tool-agent.serialized.json`). The tests
  parse the fixture and assert the emitted flow/agents shape, so importer drift
  is caught.

## Methods implemented

Exposed through `os-headless` as `bundles.import` / `bundles.export` / `bundles.diff` / `bundles.list`. Result rows feed `flows.upsertInline` once the user confirms.

## Methods consumed

- `flows.upsertInline` (downstream) — once the imported flow is accepted.
- `audit.append` (downstream) — records source + fidelity warnings.

## Common questions

> **How is order determined?**
> `Importer.detect(input)` is shape-based — first match wins. Ordering in `builtInImporters` puts the most specific shapes first (langchain/langgraph) and the broadest last (n8n).

> **What goes in `ImportWarning`?**
> Constructs that don't have a direct AKOS equivalent (e.g. an n8n credential type with no mapped connection). Warnings are non-fatal — the import returns a partial flow and the UI surfaces them in the import-review modal.

> **How to add a new source?**
> Implement `Importer` (source, detect, parse), add it to `builtInImporters`, register `importer.<source>.fixture.json` in `tests/`.

Source: /raw/for-agents/packages/os-import.md

### for-agents/packages/os-integrations.md

# @agentskit/os-integrations

> **Status:** alpha — L2 binding layer (ADR-0064)

## Purpose

Binds the published `@agentskit/integrations` catalog (the unified, single-descriptor service-integration catalog from the upstream AgentsKit framework) into AgentsKit-OS contracts. Each catalog descriptor (`auth` + `actions` + `triggers` + `oauth`) is projected into the OS contract for a given consumer; the OS keeps egress gating, vault/secret resolution, idempotency, and signed audit in its own seams — this package only projects.

Today it provides six projections: the **integration-catalog** projection (`integrationDefinitionFromSetupProvider`, ADR-0164 canonical setup state), the **agent-tool** projection (`toAgentskitTools`, consumed by `os-runtime-agentskit`), the **connection-sender** projection (`toConnectionSenders`, RFC-0022 outbound dispatch), the **OAuth provider-spec** projection (`toOAuthProviderSpecs`, the open catalog as the OAuth provider registry), the **webhook-verifier** projection (`toWebhookVerifiers`, the open catalog as the inbound signature-verification registry — the OS keeps the `IncomingEvent` normalize), and the **marketplace-listing** projection (`toMarketplaceListings`, the open catalog as discoverable connector cards in the desktop marketplace).

## Package info

| Field | Value |
|-------|-------|
| npm name | `@agentskit/os-integrations` |
| stability | alpha |
| layer | L2 binding (ADR-0064) |
| peer deps | `@agentskit/integrations ^0.4.0`, `@agentskit/os-core workspace:^` |

## Public exports

```ts
// Project a catalog descriptor into OS AgentskitTools.
// - getToken: lazy credential resolver, read per call (vault-rotation-safe)
// - config:   service-specific config passed to the action's ctx.config
// - baseUrl:  per-instance base URL override (Jira/Salesforce/Azure/…)
// - headers:  extra request headers (merged after auth)
// - fetchImpl: injectable fetch (tests)
// - only:     restrict to a subset of the integration's actions by name
toAgentskitTools(integration: Integration, options?: ToAgentskitToolsOptions): AgentskitTool[]

// Project the catalog's sendCapability actions into RFC-0022 ConnectionSenders.
toConnectionSenders(integrations: Integration[], options?: ToConnectionSendersOptions): ConnectionSender[]
toConnectionSender(integration: Integration, options?: ToConnectionSendersOptions): ConnectionSender | undefined

// Project the catalog's `oauth`-bearing descriptors into OS OAuth provider specs
// (flat shape: providerId / displayName / authorizationUrl / tokenUrl /
// defaultScopes / usePkce / extraAuthParams?). Services sharing one OAuth app
// collapse to a single provider (Gmail + Calendar + Drive → `google`).
// providerId is a plain string — the catalog is open, not the OS closed union.
toOAuthProviderSpecs(integrations: Integration[]): ProjectedOAuthProviderSpec[]

// Project the catalog's trigger verifiers into source-keyed signature checkers
// ({ source, triggerName, verify }). verify(input: WebhookInput): VerifyResult —
// the portable signature crypto (HMAC / Ed25519 / replay windows). The OS keeps
// the non-portable normalize → canonical IncomingEvent + session stitching.
toWebhookVerifiers(integrations: Integration[]): ProjectedWebhookVerifier[]
webhookVerifiersBySource(integrations: Integration[]): ReadonlyMap<string, ProjectedWebhookVerifier>

// Project the catalog into desktop-marketplace seed listings (verified, free,
// universal connector cards). Feeds apps/desktop/public/marketplace.json via the
// repo script `pnpm gen:marketplace`; the marketplace.listings handler serves
// them when no AKOS_MARKETPLACE_REGISTRY is set. manifestHash is a deterministic
// content fingerprint (built-in connectors are not installable bundles).
toMarketplaceListings(integrations: Integration[], opts: { version: string; publishedAt?: string }): MarketplaceCatalogListing[]
toMarketplaceListing(integration: Integration, opts): MarketplaceCatalogListing

// Project setup-registry rows into the canonical AKOS integration model
// defined by ADR-0164. Use this when a surface needs integration capabilities,
// setup mode, safe assistant context, and setup-state actions.
integrationDefinitionFromSetupProvider(provider: IntegrationSetupProviderLike): IntegrationDefinition
integrationDefinitionsFromSetupProviders(providers: IntegrationSetupProviderLike[]): IntegrationDefinition[]

// Types
interface IntegrationDefinition
interface IntegrationSetupDefinition
interface IntegrationAssistantDefinition
type IntegrationCatalogCapability
type IntegrationSetupMode
type IntegrationSetupState
type IntegrationSetupAction
interface ToAgentskitToolsOptions
interface ToConnectionSendersOptions
interface ProjectedOAuthProviderSpec
interface ProjectedWebhookVerifier
interface MarketplaceCatalogListing
interface ToMarketplaceListingsOptions
interface AgentskitTool          // structural mirror of the os-runtime contract
type AgentskitToolReturn         // { kind: 'ok'; value } | { kind: 'error'; code; message }
```

## Usage

```ts
import { getIntegration } from '@agentskit/integrations'
import { toAgentskitTools } from '@agentskit/os-integrations'

const slack = getIntegration('slack')!
const tools = toAgentskitTools(slack, {
  getToken: () => secretStore.get('slack.bot_token'),
})
// tools is AgentskitTool[] — hand to createAgentskitToolExecutor(...)
```

## Notes

- The `AgentskitTool` contract is mirrored **structurally** here (not imported from `@agentskit/os-runtime-agentskit`) to respect the ADR-0064 layer direction — a domain projection must not depend on the runtime binding layer.
- ADR-0164 makes this package the canonical AKOS integration catalog owner. UI surfaces should consume projected definitions instead of creating local provider lists; product screens should call `integrations.catalog.list` through the sidecar rather than importing this package directly.
- Credentials are resolved lazily on every call so a rotated secret-vault token is picked up without a runner restart.
- `toOAuthProviderSpecs` makes the open catalog the declarative OAuth provider registry. The OS still owns the flow runner, token vault, refresh scheduler, and app client secrets (`@agentskit/os-oauth`). A drift test (`tests/oauth-catalog-drift.test.ts`) pins the projected catalog specs to the OS `OAUTH_PROVIDERS` so the two copies cannot diverge on endpoints/scopes/PKCE. Fully sourcing `OAUTH_PROVIDERS` from the catalog (and dropping the OS copy) is gated on reworking the closed `OAuthProviderId` union + env-key derivation — see #3920.
- `toWebhookVerifiers` makes the open catalog the inbound signature-verification registry; the OS keeps the `verify*Signature` parity but owns the non-portable normalize → canonical `IncomingEvent` (ADR-0042), session stitching, and webhook auto-registration. A drift test (`tests/webhook-verify-drift.test.ts`) pins catalog ↔ OS crypto for every provider whose scheme is shared (slack, github, linear, sentry, pagerduty, twilio — twilio driven in each side's input model from one shared body). **discord** is intentionally excluded: the OS verifier is an internal HMAC over `x-akos-signature` because the cloud transport performs Discord's real Ed25519 check at the edge and re-signs with the AKOS relay secret before forwarding — the catalog implements the direct-from-Discord Ed25519 path, a different position in the pipeline.
- The duplication is **pinned, not removed.** Deleting the OS copies and sourcing verifiers/specs from the catalog at runtime would add a runtime dependency from the zero-dep `os-triggers` / `os-oauth` domains onto the upstream catalog, force a hybrid registry (os-only `email` / `s3` / `postgres-cdc` triggers and `twilio` / `onedrive` OAuth providers have no catalog entry; the catalog's `salesforce` has no OS entry — neither side is a superset), and drop the closed `OAuthProviderId` union. The drift tests give the single-source-of-truth guarantee without that cost.
- `toMarketplaceListings` makes every catalog service **discoverable** in the desktop marketplace with no hosted registry. `pnpm gen:marketplace` projects the catalog into `apps/desktop/public/marketplace.json`; the `marketplace.listings` handler (`@agentskit/os-marketplace`) serves that local seed when `AKOS_MARKETPLACE_REGISTRY` is unset. Listings are `verified` / `free` / universal so they always pass the RPC filters and render as connector cards. They are discovery-only — the connector code already ships in the catalog, so there is no installable bundle and `manifestHash` is a stable content fingerprint, not a downloadable-bundle digest. Re-run `pnpm gen:marketplace` whenever the catalog changes.

## Common questions

> **Should I add provider-specific OAuth or webhook data here?**
> Add it to `@agentskit/integrations` when it belongs to the shared catalog. This
> package should project catalog data into OS shapes, not become a second
> provider registry.

> **Why do OAuth providers and webhook verifiers still have OS copies?**
> The copies are pinned by drift tests because the OS owns closed ids, env-key
> derivation, token storage, relay signing, and non-catalog triggers. Remove the
> copies only when those contracts can move without weakening those boundaries.

> **How should the assistant describe marketplace integration cards?**
> Say they are discovery cards for built-in connector capabilities. Do not imply
> a downloadable plugin bundle exists unless a real marketplace listing provides
> one.

Source: /raw/for-agents/packages/os-integrations.md

### for-agents/packages/os-license.md

# packages/os-license

## Purpose

Ed25519-signed license envelopes for OEM / enterprise distribution. Compact JWS-style format (`base64url(claimsJson).base64url(signature)`). Verifier-side state machine derives `valid | in-grace | expired | over-seats | invalid-product` from claims + current time + active seat count. No alg confusion surface — verifier always uses Ed25519.

## Public exports

Root entry (`@agentskit/os-license`):

- `LicenseClaims` (Zod schema + type): `product`, `customer`, `tier`, `seats`, `features[]`, `issuedAt`, `expiresAt`, optional `issuer`
- `signLicenseEnvelope(claims, { privateKeyPem })`
- `verifyLicenseEnvelope(envelope, { publicKeyPem })` → `{ ok: true, claims } | { ok: false, error }`
- `computeLicenseState({ claims, now, productId, activeSeatCount, graceDays? })`
- `generateLicenseKeyPair()` (dev/test only — never in production)
- Types: `LicenseError`, `LicenseState`, `Ed25519KeyPair`, `SignerOptions`,
  `VerifierOptions`, `ComputeLicenseStateInput`, `ComputeLicenseStateResult`;
  constant `GRACE_DAYS_DEFAULT = 7`

Sub-paths (RFC-0017 consolidation):

- `@agentskit/os-license/service` — in-memory license service + subscription store + ledger. Backs `apps/license-service` HTTP handlers.
- `@agentskit/os-license/billing` — billing provider registry + Stripe/Paddle/Lemon-Squeezy adapters + webhook verifiers. Consumed by `apps/license-service`.

## Wired stores

None — pure crypto + state machine. SQLite persistence lives in `apps/license-service`.

## Methods implemented / consumed

Implemented (via `apps/license-service` — app-level HTTP surface, not workspace JSON-RPC): `licenses.issue`, `licenses.renew`, `licenses.verify`.

Consumed: none.

## Common questions

> **Where does the public key come from?**
> Production builds embed the SPKI PEM at compile time per ADR-0047. Dev/test pass via `AKOS_LICENSE_PUBLIC_KEY`. Never trust an ambient or remote key at runtime — the key is part of the build identity.

> **What's `over-seats` vs `expired` vs `in-grace`?**
> `over-seats`: `activeSeatCount > claims.seats` (immediate hard fail). `expired`: past `expiresAt + graceDays`. `in-grace`: past `expiresAt` but within `graceDays` (default 7) — the host surfaces a banner but flows still run.

> **Why a compact format instead of full JWS?**
> We control signer + verifier. No header negotiation is needed, and removing `alg` eliminates the alg-confusion attack surface entirely.

---

## Enterprise GA v1 additions (ef-07 SU7.3–7.5 / #3014–#3016, parent #2936)

### Plan caps matrix (`src/plan-caps/matrix.ts`)

`PLAN_CAPS_MATRIX` defines resource quotas and feature flags per plan:

```ts
// from packages/os-license/src/plan-caps/matrix.ts
type PlanId = 'free' | 'pro' | 'enterprise'

interface PlanCapsMatrix {
  // Resource quotas (numeric ceiling)
  maxOrgs: number           // 1 / 10 / MAX
  maxUsers: number          // 5 / 100 / MAX
  maxRunsPerMonth: number   // 500 / 10_000 / MAX
  maxCpuMinutesPerMonth: number  // 60 / 600 / MAX
  maxStorageGb: number      // 1 / 50 / MAX
  offlineGraceDays: number  // 0 / 3 / 14

  // Feature flags (boolean)
  scim: boolean             // false / false / true
  sso: boolean              // false / true / true
  customBrand: boolean      // false / false / true
  prioritySupport: boolean  // false / false / true
  dedicatedSandbox: boolean // false / false / true
}
```

- `resolvePlanCaps(planId, overrides?)` — merges plan defaults with optional per-tenant `PlanCapsOverride`. Numeric overrides are clamped via `min(override, planDefault)` so an admin cannot elevate a tenant above their plan ceiling. Boolean overrides are taken as-is. Unknown `planId` falls back to `'free'` (safe default).
- `assertCap(caps, key)` — throws `AgentsKitError(AK_PLAN_CAP_EXCEEDED)` when the boolean feature flag `caps[key]` is `false`.
- `assertCapBelow(caps, key, current)` — throws `AgentsKitError(AK_PLAN_CAP_EXCEEDED)` when `current >= caps[key]` (strict less-than so a zero-cap blocks all).
- Types: `PlanCapsMatrix`, `PlanCapsOverride`, `PlanId`, `BooleanCapKey`, `NumericCapKey`, `AkPlanCapExceededCode`.
- Error code constant: `AK_PLAN_CAP_EXCEEDED`.

### Offline grace + verifier (`src/offline/`)

- `resolveOfflineGraceDays(planId)` → `number` — returns `offlineGraceDays` from `PLAN_CAPS_MATRIX` (free=0, pro=3, enterprise=14). Unknown plans fall back to free (0 days).
- `createOfflineVerifier(opts: OfflineVerifierOptions)` → `OfflineVerifier` — combines three checks before granting offline access: (a) Ed25519 signature valid; (b) `cachedAt + graceDays` not exceeded; (c) envelope payload hash not in cached revocation snapshot. When the cloud is reachable, refreshes cache + revocation snapshot first.
- `assertOfflineLicense(verifier)` — convenience wrapper; awaits `verifier.verify()` and throws `AgentsKitError(AK_LICENSE_OFFLINE_GRACE_EXPIRED | AK_LICENSE_OFFLINE_INVALID_SIG)` on failure, returning the `'cloud' | 'cache'` source otherwise. (`product`/`now` are configured on `createOfflineVerifier(opts)`, not passed here.)
- `createLicenseCache(opts)` → `LicenseCache` — key-value cache for the license envelope and revocation snapshot. Backed by the injected `KeyValueStore` port.
- Error codes: `AK_LICENSE_OFFLINE_GRACE_EXPIRED`, `AK_LICENSE_OFFLINE_INVALID_SIG`.

### Revocation list (`src/revoke/`)

- `signRevocationList(revokedLicenseIds, opts, now?)` → `RevocationList` / `verifyRevocationList(raw, opts)` → `VerifyRevocationListResult` — Ed25519-signed snapshot of all currently-revoked license ids. Same signing key as envelope. Wire format: `{ generatedAt, revokedLicenseIds, signature }`. `buildRevocationPayload(generatedAt, revokedLicenseIds)` produces the canonical signed string; `sha256Hex` is re-exported as `revocationSha256Hex`.
- `isRevoked(list, licenseId)` → `boolean` — checks the in-memory revocation set.
- `createSidecarRevocationVerifier(opts)` → `SidecarRevocationVerifier` — manages a locally-cached `RevocationList` on the sidecar: fetches on boot + on `license:revocation-updated` sync events, verifies signature + freshness, caches via `LicenseCache.writeRevocationSnapshot`. Fail-closed: denies when no valid list is held.
- `assertNotRevoked(verifier, licenseId)` — throws `AgentsKitError(AK_LICENSE_REVOKED)` if revoked, `AK_LICENSE_REVOCATION_STALE` if list is absent or stale.
- Freshness gate: lists older than `maxStalenessMs` (default 1 hour = 3 600 000 ms) are rejected.
- Types: `RevocationList`, `RevocationListSignerOptions`, `RevocationListVerifierOptions`, `SidecarRevocationVerifier`, `FetchRevocationListFn`, `RevocationCheckResult`.
- Constants: `REVOCATION_UPDATED_TOPIC` — sync event name.
- Error codes: `AK_LICENSE_REVOKED`, `AK_LICENSE_REVOCATION_STALE`.

### Renewal saga

License renewal is handled by `apps/license-service` HTTP surface (`licenses.renew`). The sidecar detects `in-grace` state via `computeLicenseState` and surfaces a renewal banner; on renewal the cloud pushes a fresh envelope + revocation snapshot via the `license:revocation-updated` sync topic.

Source: /raw/for-agents/packages/os-license.md

### for-agents/packages/os-log.md

# packages/os-log

## Purpose

`@agentskit/os-log` is the **foundational structured-logging primitive** for the entire AgentsKitOS monorepo. It is a leaf dependency (nothing in os-log depends on other AgentsKit packages) and is consumed by every surface that needs to emit log entries.

CLAUDE.md non-negotiable #4: **every package MUST use `createLogger(tag)` from this package. Direct `console.log` / `console.warn` / `console.error` calls are prohibited in all production source files except the intentional exception documented below.**

Features:
- Tagged loggers — every entry carries a `tag` string so log panels and remote sinks can filter by subsystem.
- Four levels: `debug` / `info` / `warn` / `error`. Filtered at emit time against `minLevel` (default `info`, override via `AKOS_LOG_LEVEL` env or `setMinLevel()`).
- Pluggable transports — zero transports by default; each platform installs its own via `installNodeDefaults` or `installBrowserDefaults`.
- Optional `source` field (`'ui' | 'sidecar' | 'mcp' | 'console'`) to identify the emitting process.
- Optional structured `fields` blob attached to any log call.

---

## Public exports

Top-level named exports from `@agentskit/os-log` (detailed per-API sections follow):

- `createLogger(tag, opts?)` — the core factory; returns a tagged logger with `debug` / `info` / `warn` / `error` methods. See **core API** below.
- `withContext(fields, fn)` / context binding — attach structured fields to every entry emitted within a scope.
- Level controls: `setMinLevel(level)`, `getMinLevel()`, and the `LogLevel` type (`'debug' | 'info' | 'warn' | 'error'`).
- Transport system: `addTransport(t)`, `removeTransport(t)`, `clearTransports()`, `listTransports()`, and the `LogTransport` interface — plus built-in transports (`createConsoleTransport`, `createStderrTransport`, `createIndexedDBSink`, `createRingBuffer`) and platform bootstraps `installNodeDefaults` / `installBrowserDefaults`.
- `forwardLogsToTransport(...)` — bridge entries from another process/source into the local transport chain.
- Types: `LogEntry` (the emitted record shape), `LogSource` (`'ui' | 'sidecar' | 'mcp' | 'console'`), and `CreateLoggerOptions`.

> The exact export surface is the source of truth — every symbol named above is verified to exist in `packages/os-log/src`. The sections below document each in depth.

## `createLogger(tag, opts?)` — core API

```ts
import { createLogger } from '@agentskit/os-log'

const log = createLogger('my-package')
log.debug('message', { key: 'value' }) // below info — filtered by default
log.info('started')
log.warn('degraded', { reason: 'timeout' })
log.error('fatal', { reason: 'initialization-failed' })
```

### Signature

```ts
createLogger(tag: string, options?: CreateLoggerOptions): Logger
```

`CreateLoggerOptions`:
| Field | Type | Description |
|---|---|---|
| `source` | `'ui' \| 'sidecar' \| 'mcp' \| 'console'` | Overrides the default source for every entry emitted by this logger. If omitted, falls back to `getDefaultSource()`. |

### `Logger` interface

```ts
interface Logger {
  readonly tag: string
  child(suffix: string): Logger
  debug(msg: string, fields?: Readonly<Record<string, unknown>>): void
  info(msg: string, fields?: Readonly<Record<string, unknown>>): void
  warn(msg: string, fields?: Readonly<Record<string, unknown>>): void
  error(msg: string, fields?: Readonly<Record<string, unknown>>): void
}
```

`child(suffix)` returns a new `Logger` tagged `<parent>:<suffix>`, sharing the same transport registry and level. Zero extra state allocated.

### Singleton `log`

A pre-built logger tagged `'sidecar'` is exported as `log` for quick use in Node/sidecar contexts:

```ts
import { log } from '@agentskit/os-log'
log.info('sidecar ready')
```

---

## Level system

| Level | Numeric | Typical use |
|---|---|---|
| `debug` | 10 | Verbose internals; filtered in prod |
| `info` | 20 | Normal lifecycle events |
| `warn` | 30 | Recoverable anomalies |
| `error` | 40 | Failures that need attention |

The default level is `info`. Control:

```ts
import { setMinLevel, getMinLevel } from '@agentskit/os-log'

setMinLevel('debug')  // runtime change
getMinLevel()         // → 'debug'
```

`AKOS_LOG_LEVEL` env is read once at module load; call `setMinLevel()` to change at runtime.

---

## Context binding — `withContext`

```ts
import { withContext, createLogger } from '@agentskit/os-log'

const base = createLogger('runtime')
const log  = withContext(base, { runId: 'r1', traceId: 'tr1', workspaceId: 'w1' })
log.info('pack executed')
// → fields includes { runId: 'r1', traceId: 'tr1', workspaceId: 'w1' }
```

Call-site fields passed to `log.info(msg, fields)` are merged on top of the context blob (call-site wins on conflicts). `child()` works on a context-bound logger — the child inherits the context.

`LogContext` accepted fields: `runId`, `workspaceId`, `traceId`, `spanId`, `requestId`.

---

## Transport system

The transport registry is a global `Set<LogTransport>` (singleton per module). Every `LogEntry` dispatched to every registered transport.

```ts
interface LogTransport {
  write(entry: LogEntry): void
}
```

Transport errors are swallowed — a throwing transport never crashes the caller.

### Registry API

```ts
addTransport(t)      // returns disposer () => void
removeTransport(t)
clearTransports()
listTransports()     // → readonly LogTransport[]
```

Use the disposer from `addTransport` (or `removeTransport`) to unregister:

```ts
const dispose = addTransport(myTransport)
// … later:
dispose()
```

---

## Built-in transports

### `createConsoleTransport(opts?)`

Routes log entries to the browser's (or injected) `console` object. This is the **only place in the entire codebase where `console.*` is legitimately used** — it is the implementation of the browser console transport, not an application-level log call.

```
// packages/os-log/src/transports/console.ts — typeof console check + console.debug/info/warn/error calls
// This is intentional: console.ts IS the console transport.
// All other packages are PROHIBITED from calling console.* directly (CLAUDE.md #4).
```

Options:
| Field | Type | Description |
|---|---|---|
| `target` | `Console`-like | Defaults to global `console` if available. Pass a mock in tests. |
| `pretty` | `boolean` | Forces `%c` CSS styling on/off. Defaults to `true` in browsers, `false` in Node. |

In `pretty` mode each entry is emitted as a styled `%c`-formatted string with color-coded level badge, purple tag, and optional italic source segment. In plain mode a `[tag]` prefix is prepended.

### `createStderrTransport()`

Node-only transport. Writes a colored, human-readable line to `process.stderr`. Supports:
- `AKOS_LOG_FORMAT=json` — emits newline-delimited JSON (one object per entry, fields spread at the top level).
- `NO_COLOR` / `FORCE_COLOR` / `AKOS_LOG_COLOR=0|1` — control ANSI color output.

### `createRingBuffer(opts?)`

In-memory circular buffer of `LogEntry` objects. Implements `LogTransport` so it can be registered directly.

```ts
interface RingBuffer extends LogTransport {
  capacity: number        // default 5000; clamped to ≥1
  entries(): readonly LogEntry[]
  size(): number
  clear(): void
  subscribe(listener: (entry: LogEntry) => void): () => void
}
```

Used by the desktop log panel to show recent entries without disk I/O.

### `createIndexedDBSink(opts?)`

Browser-only persistent log sink. Falls back to a no-op when `indexedDB` is unavailable (server-side rendering, Node test environment). Automatically prunes oldest entries when over `capacity`.

```ts
interface IndexedDBSink extends LogTransport {
  ready(): Promise<void>
  read(): Promise<readonly LogEntry[]>
  clear(): Promise<void>
  flush(): Promise<void>
}
```

Options:
| Field | Type | Default |
|---|---|---|
| `capacity` | `number` | `5000` |
| `dbName` | `string` | `'akos-log'` |
| `storeName` | `string` | `'entries'` |
| `factory` | `IDBFactory` | global `indexedDB` |

---

## Platform bootstrap helpers

### Node — `installNodeDefaults(source?)`

```ts
import { installNodeDefaults } from '@agentskit/os-log'
installNodeDefaults()        // source defaults to 'sidecar'
installNodeDefaults('mcp')   // for MCP bridge processes
```

Idempotent. Registers `stderrTransport` and calls `setDefaultSource`. Call once at process entry.

### Browser — `installBrowserDefaults(opts?)` / `getBrowserDefaults()`

```ts
import { installBrowserDefaults, getBrowserDefaults } from '@agentskit/os-log'

const { ring, idb } = installBrowserDefaults({
  capacity: 5000,        // ring buffer + IDB capacity
  source: 'ui',          // default source for all UI log entries
  attachConsole: true,   // force-attach in prod (default: auto-attach in dev only)
  idb: { dbName: 'akos-log' }, // or false to disable IDB
})
```

Idempotent — subsequent calls return the previously installed handles. `getBrowserDefaults()` returns `null` before first install.

`attachConsole` gate: in development (`NODE_ENV !== 'production'`) the console transport is attached by default. In production builds it is NOT attached unless `attachConsole: true` is explicitly passed. This prevents every structured log from duplicating into the browser DevTools console in production.

---

## Log forwarding — `forwardLogsToTransport`

Used by the sidecar to ship UI-side log entries to disk over the JSON-RPC notify channel.

```ts
import { forwardLogsToTransport } from '@agentskit/os-log'

const dispose = forwardLogsToTransport(channel)
// channel.notify receives { jsonrpc: '2.0', method: 'log', params: LogEntry }
// dispose() to stop forwarding
```

`LogNotifyChannel`: `{ notify(notification: LogNotification): void }`
`LogNotification`: `{ jsonrpc: '2.0', method: 'log', params: { ts, level, tag, msg, source?, fields? } }`

Channel errors are swallowed — a throwing channel never crashes the logger.

---

## Source field

The `source` field identifies which process emitted the entry:

| Value | Meaning |
|---|---|
| `'ui'` | Browser/desktop UI process |
| `'sidecar'` | Node sidecar process |
| `'mcp'` | MCP bridge process |
| `'console'` | External console input |

Set a default for all loggers in the current process via `setDefaultSource('sidecar')`, or override per-logger via `createLogger('tag', { source: 'mcp' })`.

---

## How the rest of the monorepo MUST use os-log

1. **One logger per module/package, created at module scope:**
   ```ts
   // packages/my-package/src/some-module.ts
   import { createLogger } from '@agentskit/os-log'
   const log = createLogger('my-package')
   ```

2. **Never `console.log` / `console.warn` / `console.error`** in any production source file. The only allowed `console.*` usage is inside `packages/os-log/src/transports/console.ts` — the browser transport implementation. All other occurrences are violations of CLAUDE.md #4.

3. **Use `child()` for sub-modules** rather than inventing a new tag:
   ```ts
   const log = createLogger('os-runtime')
   const authLog = log.child('auth')   // tag: 'os-runtime:auth'
   ```

4. **Call `installNodeDefaults()` at process entry** for Node processes (sidecar, MCP bridge, CLI). Call `installBrowserDefaults()` once at app bootstrap for browser contexts. Without a registered transport, all log calls are silent.

5. **Use `withContext`** when a tracing context (runId, traceId, etc.) is available to attach it to all log entries in a scope.

---

## `LogEntry` shape

```ts
interface LogEntry {
  readonly ts: string                          // ISO-8601 timestamp
  readonly level: LogLevel                     // 'debug' | 'info' | 'warn' | 'error'
  readonly tag: string                         // logger tag
  readonly msg: string                         // message
  readonly fields?: Readonly<Record<string, unknown>>  // optional structured data
  readonly source?: LogSource                  // optional process identifier
}
```

---

## Wired stores

- **IndexedDB** (browser): `createIndexedDBSink` persists entries for the desktop log panel's history view.
- **Ring buffer**: `createRingBuffer` keeps the last N entries in memory for the live log panel; also used by `forwardLogsToTransport` to replay recent entries to a newly connected sidecar.

---

## JSON-RPC surfaces driven

`os-headless` `logs.tail` / `logs.list` — the sidecar attaches `forwardLogsToTransport` over the notify channel so UI-side log entries appear in the node-side log stream and can be written to disk.

---

## ADR / guardrail notes

- **No `any`**: all interfaces use `unknown` for field values. Transport `write` receives a fully typed `LogEntry`.
- **Named exports only**: every export in `src/index.ts` is named; no `export default`.
- **File size**: `os-log` is a leaf dependency; keep it lean. The only runtime dependency is `picocolors` (for stderr ANSI coloring).
- **No hidden mocks**: `createIndexedDBSink` returns a real no-op sink (not a mock) when `indexedDB` is unavailable.
- **The ONLY console.* exception**: `src/transports/console.ts` references `typeof console` and delegates writes to `console.debug/info/warn/error`. This is the transport layer — not an application log call. No other file in this package (or any other AgentsKit package) may call `console.*` directly.

---

## Common questions

> **Why not `console.log`?**
> CLAUDE.md #4: every entry must carry `tag`, `level`, `source` so it is filterable in the desktop log panel and routable to remote sinks (IDB, stderr, JSON-RPC forward). `console.*` bypasses all of this.

> **How is `AKOS_LOG_LEVEL` read?**
> Once, at module load, in `core.ts`. Use `setMinLevel('debug')` to change at runtime.

> **What does `child('subtag')` do?**
> Returns a Logger tagged `parent:subtag`, sharing transports + level. Zero new state.

> **Why does `src/transports/console.ts` use `console` directly?**
> Because it IS the console transport — its job is to delegate structured log entries to the browser's `console` API with `%c` styling. This is the intentional exception to rule #4, scoped to one file in one package. Any `console.*` call outside this file is a violation.

> **Is os-log safe to use in SSR / Node tests?**
> Yes. `createIndexedDBSink` returns a no-op when `indexedDB` is absent. `createConsoleTransport` returns a no-op when `console` is absent. No transports are registered unless you call `installNodeDefaults()` or `installBrowserDefaults()`.

> **How do I write a custom transport?**
> Implement `{ write(entry: LogEntry): void }` and call `addTransport(myTransport)`. The returned disposer removes it.

Source: /raw/for-agents/packages/os-log.md

### for-agents/packages/os-marketplace.md

# packages/os-marketplace

## Purpose

Marketplace SDK — manifest builder, integrity hashing, bundle packaging,
publisher registry, listing search, provenance/SBOM attestation, and
private-library scoping. Its `/plugins` subpath owns plugin loading and
signature verification; `os-headless` owns install/uninstall handlers. The invariant is that
every install goes through `evaluateInstall` before any file is written, so
permission diffs and provenance attestations are checked before commitment.

## Public exports

- Integrity: `canonicalJson`, `sha256OfBytes`, `sha256OfCanonical`,
  `sha512OfBytes`, `sha512OfCanonical`, `verifyIntegrity`
- Manifest: `buildManifest`, `stripSignature`, `ManifestSigner`, `BuildOptions`
- Bundle: `buildBundle`, `verifyAsset`, `verifyBundleArchive`, `AssetEntry`,
  `AssetRecord`, `Bundle`
- Publishers: `InMemoryPublisher`, `Publisher`, `PublishResult`,
  `HttpPublisher`, `HttpPublisherOptions`
- Cost badge: `buildPluginCostBadge`, `PluginCostBadge`, `PluginCostBadgeInput`
- Listing: `evaluateInstall`, `searchListings`, `isCompatibleHost`,
  `EvaluateInstallArgs`, `InstallVerdict`, `InstallVerdictFail`, `InstallVerdictOk`,
  `ListingCategory`, `ListingCompat`, `ListingSearchQuery`, `MarketplaceListing`, `SearchOpts`
  - `ListingCategory` ∋ `monitoring` — curated anomaly + monitoring packs (ADR-0052).
    The `marketplace.monitoringPacks` / `marketplace.applyMonitoringPack` handlers and
    `OFFICIAL_MONITORING_PACKS` data live in `@agentskit/os-templates`, not this package.
  - `ListingCategory` ∋ `security` — curated security packs (ADR-0054).
    The `marketplace.securityPacks` / `marketplace.applySecurityPack` handlers and
    `OFFICIAL_SECURITY_PACKS` data live in `@agentskit/os-templates`, not this package.
- Provenance: `diffPermissions`, `evaluateProvenanceAgainstPolicy`,
  `InstallPolicy`, `ProvenanceInstallVerdict`, `PermissionDiff`,
  `ProvenanceAttestation`, `ProvenanceBundle`, `SbomEntry`
- Private library: `filterForPrivateViewer`, `tagPrivateScope`,
  `PrivateLibraryViewer`, `PrivateScope`
- Plugin store: `filterPluginStoreEntries`, `latestAudit`, `renderStoreBadge`,
  `AuditEntry`, `PluginStoreEntry`, `StoreFilter`, `VerificationLevel`
- Connection suggester: `suggestConnections(brief: string)`, `ConnectionSuggestion`
  (fields: `integration`, `score`, `reasons`, `suggestedPermissions`; keyword-based
  heuristic on a free-text brief — not capability-based)
- Install resolver: `PluginManifest`, `resolveInstall`, `InstallContext`,
  `ResolveInstallVerdict`, `InstalledPlugin`
- Bundle scanner: `scanBundle`, `BundleEntry`, `ScanFinding`, `ScanReport`, `ScanSeverity`
- Host compat: `isCompatibleHost` (also `ListingCompat` type)
- Key registry: `createPublisherKeyRegistry`, `computeKeyId`,
  `isPublisherKeyActive`, `InvalidPublicKeyError`, `KeyStatus`,
  `PublisherKeyRecord`, `PublisherKeyRegistry`
- Publish flow: `publishBundle`, `PublishInput`, `PublishVerdict`
- Signing: `signPluginBundle`, `verifyPluginSignature`, `generatePluginKeypair`,
  `sha256Hex`, `badgeForVerdict`, `PluginSignature`, `SignatureVerdict`, `VerifiedBadge`
- Featured + stats: `selectFeatured`, `buildRatingHistogram`, `buildUsageStats`
  (+ `FeaturedSelection`, `FeaturedSlot`, `RatingHistogram`, `UsageStats`)
- Default manifest verifier: `createMarketplaceSignatureVerifier`
  (+ `CreateMarketplaceVerifierOpts`, `ManifestSignatureVerifier`)

Sub-paths (RFC-0017):

- `@agentskit/os-marketplace/registry` (absorbed from `os-pack-registry`) — `PackManifest`, `PackStatus` Zod schemas, `signManifest`, `verifyManifestSignature`, `installableLatestByPackId`, `isInstallable`, `latestInstallable`. Vertical-pack signed declarative manifest lifecycle.
- `@agentskit/os-marketplace/plugins` (absorbed from `os-plugins`) — plugin loader (`loadPluginStrict`), manifest fetcher, permission registry. Wired by sidecar dispatcher.

## Wired stores

`InMemoryPublisher` holds resolved manifests in-process. Persistent install
state (installed plugin records, publisher keys) lives in `os-storage` and
is wired by `os-headless/src/marketplace-cost-firewall-handlers.ts`.

## Methods implemented / consumed

Implemented (owner `@agentskit/os-marketplace` in `src/runtime/handlers.ts`, wired via
`buildMarketplacePhase7Handlers`):

- `marketplace.fetch` — registry-first listing fetch; falls back to local-json catalog
- `marketplace.listings` — filter + paginate listings (query, category, verticals,
  signedOnly, costModel, capabilities, limit)
- `marketplace.featured` — editorial featured-listing rotation (first 3 by rank)
- `marketplace.stats` — total listings, verified count, total installs, top verticals
- `marketplace.listing.get` — fetch a single listing detail by id
- `marketplace.install` — install a plugin (pre-install gate + G2 capability consent)
- `marketplace.uninstall` — remove an installed plugin (revokes capability grants)
- `marketplace.evaluateInstall` — dry-run the install gate without writing files
- `marketplace.installed.list` — list installed plugins with update-available hints
- `marketplace.publisherKeys.list` / `.pin` / `.revoke` — publisher key management
- `marketplace.privateLibrary.list` / `.add` / `.install` / `.remove` — private
  (non-marketplace) plugin library management
- `marketplace.publish.buildManifest` — derive a publish manifest from a package directory
- `marketplace.publish` — sign + upload a bundle to the OEM registry endpoint
- `marketplace.suggestions` — connection suggestions based on recent run history
- `marketplace.report` — submit a listing abuse/spam report (persisted to JSONL)

Consumed: `@agentskit/os-marketplace/plugins` for `loadPluginStrict` + signature verification.

## Common questions

> **How do I publish a plugin to the marketplace?**
> Call `buildManifest(config, signer)` to produce a signed manifest, then
> `buildBundle(manifest, assets)` to package it. Submit via
> `HttpPublisher.publish(bundle)`. See
> `docs/marketplace/plugin-submission-guide.md` for the full submission flow.

> **What does `evaluateInstall` check?** (`listing.ts`)
> The pure `evaluateInstall` export checks the bundle integrity hash and optional
> version pin, returning `InstallVerdictOk | InstallVerdictFail`. Callers must not
> write any files on `fail`. For the full runtime gate (publisher key trust, resolver
> conflict detection, permission policy) use `evaluateMarketplaceInstall` from
> `@agentskit/os-marketplace/runtime` or call `marketplace.evaluateInstall` via the
> handler map.

> **When is a plugin signature verified by `loadPlugin`?** (SEC-5 #1677 SU2)
> Whenever `manifest.signature` is present. A signature is a verification
> claim, so it is always checked: if `verifySignature` is not supplied,
> `loadPlugin` fails closed with `plugin.signature_invalid` regardless of
> `requireSignedPlugins`. Earlier builds silently ignored the signature and
> loaded the plugin unverified when no verifier was wired and
> `requireSignedPlugins` was falsy. `requireSignedPlugins: true` additionally
> rejects *unsigned* manifests (`plugin.signature_required`).

> **How does `suggestConnections` work?**
> `suggestConnections(brief: string)` is a pure keyword-heuristic that matches
> free-text (agent brief, workflow description) against a built-in rule table and
> returns `ConnectionSuggestion[]` sorted by score. Each suggestion carries
> `integration`, `score`, `reasons[]`, and `suggestedPermissions[]`. It does not
> inspect installed plugins or live workspace connections — it is an upfront
> recommender, not a capability-graph query. The runtime `marketplace.suggestions`
> handler uses a separate path (`computeConnectionSuggestions` from
> `src/runtime/listings.ts`) based on recent run history.

Source: /raw/for-agents/packages/os-marketplace.md

### for-agents/packages/os-mcp-bridge.md

# packages/os-mcp-bridge

## Purpose

MCP bridge utilities — discovers local MCP server definitions from common
agent config files, translates between AgentsKit tool descriptors and the
MCP wire format, and provides stdio/SSE/streamable-HTTP transport clients.
The invariant is that tool translation is always bidirectional and lossless:
`akToolToMcp(mcpToolToAk(mcp))` round-trips to an equivalent descriptor.

## Public exports

- Discovery: `discoverMcpServers`, `discoverMcpServersDetailed`,
  `defaultMcpDiscoveryPaths`, `extractMcpServersFromJson`, `McpDiscoveryError`,
  `McpDiscoveryOptions`, `McpDiscoveryResult`, `McpServerDefinition`, `McpTransport`
- Bridge: `akToolToMcp`, `buildMcpToolCall`, `createMcpBridge`, `mcpToolToAk`,
  `AkToolDescriptor`, `McpBridgeRegistry`, `McpToolCall`, `McpToolDescriptor`
- Stdio transport: `McpTransportError`, `startMcpStdioClient`, `JsonRpcError`,
  `JsonRpcRequest`, `JsonRpcResponse`, `JsonRpcSuccess`, `McpStdioClient`,
  `McpStdioServerSpec`
- SSE transport: `startMcpSseClient`, `McpSseClient`, `McpSseClientOpts`
- Streamable HTTP transport: `startMcpStreamableHttpClient`,
  `McpStreamableHttpClient`, `McpStreamableHttpClientOpts`
- Client manager: `createMcpClientManager`, `McpClient`, `McpClientManager`,
  `McpClientManagerOptions`, `OAuthConnectSpec`, `ProbeResult`, `ServerSpec`,
  `McpClientTransport`
- OAuth transport: `startMcpOAuthHttpClient`, `OAuthHttpClient`,
  `OAuthHttpClientOptions`, `StartAuthorizationResult`
- OAuth provider: `createMcpOAuthProvider`, `McpOAuthProviderOptions`,
  `OAuthClientRecord`, `OAuthProviderPorts`, `OAuthTokenRecord`
- AgentsKit tool adapters: `createMcpAgentskitTools`, `createMcpInvokeTool`,
  `DEFAULT_MCP_CALL_USD` (+ `CreateMcpAgentskitToolsOptions`,
  `CreateMcpInvokeToolOptions`, `McpAgentskitTool`, `McpBudgetHooks`,
  `McpCapabilityGuard`, `McpToolReturn`) — expose discovered MCP tools as
  AgentsKit tools with per-run budget metering and RBAC capability gating
- Knowledge surface: `buildKnowledgeUri`, `parseKnowledgeUri`,
  `createKnowledgeMcpHandler`, `listKnowledgeResources`, `MCP_RAG_SEARCH_TOOL`
  (+ `KnowledgeUri`, `KnowledgeMcpSearchHit`, `KnowledgeMcpResult`,
  `CreateKnowledgeMcpHandlerOptions`, `KnowledgeMcpResource`)

## Invariants & gotchas

- **stdout is the JSON-RPC wire — never log to it.** The stdio transport in `src/transport-stdio.ts` reads newline-delimited JSON-RPC from child stdout; any stray byte corrupts the framing. All diagnostics MUST go to stderr. This is enforced in `src/log.ts`: the single `console.error` call (the only `console.*` in the package) always writes to stderr, with an `// eslint-disable-next-line no-console` marker acknowledging the exception.
- **`createBridgeLogger` is the only permitted logging surface.** Every module in this package creates a logger via `createBridgeLogger(tag)`. Adding a direct `console.log`/`console.warn` anywhere else would silently break any stdio MCP client — there is no lint gate to catch it at build time.
- **`AKOS_ALLOWED_MCP_COMMANDS` is default-allow in single-user mode.** When the env var is absent, `assertCommandAllowed` passes any non-empty command. Set it (comma-separated) in multi-tenant or less-trusted deployments to get default-deny allowlist enforcement.
- **Tool bridging is bidirectional and lossless by contract.** `akToolToMcp(mcpToolToAk(mcp))` must round-trip to an equivalent descriptor. Breaking this invariant silently corrupts tool descriptions in the copilot registry; test round-trip if you change either translation function.
- **Server state lives in `os-storage`, not here.** `McpServersStore` (registered servers, last probe, health) is owned by `os-headless`. This package holds no stores; it is stateless translation + transport.

## Internal logging note (rule #4 exception)

`src/log.ts` uses `console.error` intentionally and is the **only**
permitted `console.*` call in this package. This is not a rule #4 violation.
The MCP bridge communicates with child MCP servers over **stdout** using
JSON-RPC 2.0 framing; writing log output to stdout would corrupt the
JSON-RPC stream. stderr is the only safe log channel. The call site has an
`// eslint-disable-next-line no-console` comment marking it as an approved
exception. All other modules in this package use `createBridgeLogger` (the
package-local logger) rather than any `console.*` method. Agents reviewing
this codebase should not flag this as a violation.

## Wired stores

None. Server state (registered servers, health, last probed timestamp) is
held in `os-storage` (`McpServersStore`) and wired by `os-headless`.

## Methods implemented / consumed

Implemented (via `os-headless`, owner `@agentskit/os-headless` in
`os-contracts/src/methods/mcp.ts`):

- `mcp.servers.list` — list configured MCP servers
- `mcp.servers.connect` — add or reconnect an MCP server
- `mcp.servers.disconnect` — remove a server from the registry
- `mcp.servers.discover` — scan `defaultMcpDiscoveryPaths` and return found definitions
- `mcp.servers.probe` — health-check a single server and update its tool list

Consumed: `os-copilot` (`McpBridgeRegistry`) to inject MCP tools into the
copilot tool registry.

## Common questions

> **How do I discover MCP servers from a Claude Desktop config?**
> Call `discoverMcpServers()` (no options needed — default paths include
> `~/.config/claude/mcp.json`, `~/.cursor/mcp.json`, `~/.codex/mcp.json`).
> To scan additional files pass them as `extraConfigPaths`:
> `discoverMcpServers({ extraConfigPaths: ['/path/to/my/mcp.json'] })`.
> Returns `Promise<readonly McpServerDefinition[]>`. Use
> `discoverMcpServersDetailed` if you need per-file parse errors surfaced
> in `errors[]`.

> **Which transport should I use?**
> Use `startMcpStdioClient` for local processes (most common), `startMcpSseClient`
> for legacy SSE servers, and `startMcpStreamableHttpClient` for the newer
> Streamable HTTP spec. `createMcpClientManager` wraps all three and picks the
> right one from the `transport` field of `ServerSpec`.

> **How does tool bridging work in the copilot?**
> `createMcpBridge` returns a `McpBridgeRegistry` that `buildCopilotToolRegistry`
> (in `os-copilot`) merges with the built-in tool list. Each MCP tool is
> converted via `mcpToolToAk` so it conforms to the `RegisteredTool` interface
> and can be classified by the proposal classifier.

> **How does the OAuth flow work?**
> Call `manager.connectOAuth(spec)`. If the server has no cached token the
> result is `{ status: 'authorization_required', authorizationUrl }` — open
> that URL in the browser. When the loopback callback fires, call
> `manager.finishOAuth(id, code)` to complete the PKCE token exchange and
> promote the connection to live. If a valid stored token exists the result
> is `{ status: 'connected' }` and no browser interaction is needed.

> **How do MCP tool calls participate in the per-run budget?**
> Pass a `McpBudgetHooks` object to `createMcpAgentskitTools` or
> `createMcpInvokeTool`. The `checkBudget(runId)` hook is called before the
> MCP server is reached; returning `{ exceeded: true }` refuses the call.
> `recordCost(runId, usd)` is called after a successful call with the per-call
> USD estimate (default `DEFAULT_MCP_CALL_USD = 0.01`). When no `runId` is
> resolvable from the call context (e.g. a flow node outside an agent run)
> the hooks are skipped and the call executes unmetered.

> **How is RBAC enforced on MCP tool calls?**
> Pass a `McpCapabilityGuard` callback to `createMcpAgentskitTools` or
> `createMcpInvokeTool`. The guard receives `{ serverId, toolName, runId }`
> and must return `{ allowed: boolean; reason?: string }`. A denied call
> returns `{ kind: 'error', code: 'MCP_CAPABILITY_DENIED' }` and never
> reaches the MCP server. The guard runs before the budget pre-check.

Source: /raw/for-agents/packages/os-mcp-bridge.md

### for-agents/packages/os-notifications.md

# packages/os-notifications

## Purpose

Headless notification primitives shared across desktop (`os-desktop`, `apps/desktop`), web (`apps/web`), and admin (`apps/admin`). Owns the store, routing engine, sidecar-event classifier, error-doc resolver, and the React glue at the `/react` subpath.

Pure logic. No DOM-specific imports outside `/react`. No Tauri / Electron — hosts inject those.

## Public exports

### Top-level (`@agentskit/os-notifications`)

- **Types + schemas:** `Notification`, `NotificationAction`, `NotificationSeverity`, `Notify`, `SerialisableNotification`, `SerialisableAction`, `StorageEnvelope`, `ErrorCategory`, plus Zod schemas (`*Schema`).
- **Store factory:** `createNotificationsStore({ adapter?, docScheme?, enrich? })` — headless ring buffer, severity-weighted FIFO, dedup, TTL.
- **Storage adapters:** `createLocalStorageAdapter(key?)`, `createMemoryAdapter()`. Pluggable interface (`StorageAdapter`).
- **Preferences:** `routeNotification(notification, prefs, now?)`, `NotificationPreferencesSchema`, `DEFAULT_NOTIFICATION_PREFERENCES`, `KNOWN_EVENT_TYPES`.
- **Error catalog:** `resolveErrorDoc(code, scheme?)`, `buildDocUrl(code, scheme)`, `extractAkCode(input)`, `ERROR_DOC_TITLES`.
- **Error category (legacy taxonomy):** `classifyError(input)`, `ERROR_VARIANTS`.
- **notify-error builder:** `buildErrorNotify({category, title, errorCode?, ...})` — always-actionable error payload (runbook + copy-code).
- **Classifier:** `classifySidecarEvent(type, data, ctx)` — sidecar event → `Notify` with attached actions; covers 12 event families.
- **Routing dispatcher:** `dispatch(routing, payload, handlers)`.
- **Web native toast:** `webNativeToast(notify)` — fallback for `os-toast` mode on web.
- **Platform detector:** `detectPlatform()`, `defaultDocScheme(platform?)`.
- **Metrics:** `emitDispatched({severity, source?, mode, errorCode?})`, `emitActionClicked({actionId, errorCode?, source?})`.

### React subpath (`@agentskit/os-notifications/react`)

- **Providers:** `NotificationsProvider`, `NotificationPreferencesProvider`.
- **Hooks:** `useNotifications()`, `useNotificationPreferences()`, `useNotificationsStoreSnapshot(api)`.

## Wired stores

- localStorage adapter (default) — schema-versioned envelope (`v: 2`), legacy v1 array migration, cross-tab sync via `BroadcastChannel` when available, `MAX_PERSIST = 50`.
- Memory adapter (tests, headless).

## Methods implemented

None — pure client primitives. Surfaces are React + plain TS.

## Methods consumed

None directly. Hosts inject:

- `subscribeEvents(handler) => unsubscribe` — desktop wires to JSON-RPC sidecar (`@agentskit/os-desktop/lib/sidecar`); web wires to SSE (`/api/events`).
- `navigate(screen, params?)` — router callback.
- `openUrl(url)` — link opener.
- `retry(eventType, data)` — retry handler (per-event).
- `routeHandlers.{nativeToast,desktopAlert,transientToast}` — platform-specific delivery.
- `storageAdapter` — custom storage if not localStorage.

## Always-actionable contract (M-N2)

Every classifier branch attaches at least one action. Errors with an `AK_*` code auto-attach a runbook link to `docs/errors/AK_<CODE>.md` (resolved by `resolveErrorDoc`).

Enforced by the test `classifier.test.ts > every classified event has at least one action` and by the quality gate `pnpm check:actionable-notifications` (scans for `push({severity:'error|warning',...})` without `actions`).

## Event family coverage

| Event type | Severity | Actions auto-attached |
|---|---|---|
| `error.*` | error | runbook (if code), copy-code, retry (if handler), open-audit (fallback) |
| `audit.flagged.*` | warning | open-audit-log, view-policy |
| `inbox.new` / `hitl.escalation.*` | info | open-inbox, view-policy (if URL) |
| `runtime.budget.exceeded` / `cost.threshold` | warning | open-budget, view-cost |
| `usage.*` / `license.*` / `payment.risk` | warning / error | view-usage |
| `marketplace.install.*` | info / error | open-marketplace |
| `rag.index.failed` | error | runbook, retry-index |
| `mcp.bridge.disconnect` | warning | reconnect, open-connections |
| `tool.invoke.denied` | warning | open-policies |
| `firewall.*` (`firewall.blocked`) | warning | open-firewall, open-audit |
| `flow.run.completed` | success | open-run |
| `flow.run.failed` | error | open-run, runbook |

## Persistence shape (v: 2)

```ts
{
  v: 2,
  items: [
    {
      id: string,
      severity: 'info'|'warning'|'error'|'success',
      title: string,
      message?: string,
      timestamp: string,        // ISO-8601
      read: boolean,
      category?: ErrorCategory,
      errorCode?: string,
      docUrl?: string,
      source?: string,
      ttlMs?: number,
      actions: SerialisableAction[],
      details?: unknown,
    },
  ],
}
```

Action handlers are stripped on serialise (closures don't survive JSON). Rehydrate attaches an `openUrl` fallback handler when `href` is present.

## Quality gates

- `pnpm check:actionable-notifications` — every `push({severity:'error|warning'...})` carries an action.
- Tests: 330+ in `packages/os-notifications/tests/*`.

## Common questions

> **How do I create the notifications store?**
> Call `createNotificationsStore({ adapter?, docScheme?, enrich? })`. Omit
> `adapter` to default to `createLocalStorageAdapter()` (persists up to 50
> items in localStorage under schema version `STORAGE_SCHEMA_VERSION = 2`).
> For tests or headless contexts pass `createMemoryAdapter()`. The store
> returns a `StoreApi` with `push`, `markRead`, `dismiss`, `clear`, and
> `subscribe` methods.

> **How does notification routing/preferences work?**
> Call `routeNotification(notification, prefs, now?)` where `prefs` conforms
> to `NotificationPreferencesSchema`. It consults the `EventTypeRoutingMap`
> (keyed by `KnownEventType` from `KNOWN_EVENT_TYPES`) and optional
> `QuietHours` to return a `NotificationRouting` — the resolved delivery mode
> (native toast, desktop alert, transient toast, or suppressed). Pass the
> result to `dispatch(routing, payload, handlers)` with platform-specific
> `RouteHandlers` to deliver. `DEFAULT_NOTIFICATION_PREFERENCES` and
> `DEFAULT_ROUTING` are safe starting points.

> **How does the always-actionable contract work for error notifications?**
> Use `buildErrorNotify({ category, title, errorCode?, ... })` to construct a
> `Notify` payload that always carries at least a runbook action. When
> `errorCode` is an `AK_*` string, `resolveErrorDoc(code, scheme?)` resolves
> the correct `docs/errors/AK_<CODE>.md` URL (scheme: `web`, `desktop`, or
> `absolute`). `classifySidecarEvent` also auto-attaches actions for all 11
> event families. The gate `pnpm check:actionable-notifications` fails any
> `push({ severity: 'error'|'warning', ... })` call that omits `actions`.

> **How is localStorage persistence migrated from v1 to v2?**
> The `createLocalStorageAdapter` reads the stored JSON and checks the `v`
> field against `STORAGE_SCHEMA_VERSION` (currently `2`). A legacy v1 payload
> (a bare array) is automatically promoted to `{ v: 2, items: [...] }` on
> first read. Action handler closures are stripped on serialise because they
> cannot survive JSON round-trips; on rehydration the adapter re-attaches an
> `openUrl` fallback for any action that carries an `href`.

## See also

- `docs/adr/0033-notifications-package-split.md` — design rationale.
- `docs/errors/` — per-`AK_*` runbooks.

Source: /raw/for-agents/packages/os-notifications.md

### for-agents/packages/os-oauth.md

# packages/os-oauth

## Purpose

Multi-provider OAuth 2.0 subsystem extracted from `os-headless`. Owns the
full authorization-code + PKCE flow lifecycle: provider registry, authorize-URL
construction, pending-state / PKCE correlation store, token endpoint exchange,
token persistence (via `os-storage`'s `LlmOauthTokenStore` and, when provider
responses carry installation metadata, `InstallationTokenStore`), in-memory
connection hub, proactive refresh scheduling, and per-provider env-var helpers.
Supports 15 providers out of the box (Slack, GitHub, Linear, Google, Notion,
Jira, Confluence, Discord, Twilio, Sentry, PagerDuty, Stripe, OneDrive,
Dropbox, Salesforce). RPC handlers (`oauth.start`, `oauth.complete`, `oauth.revoke`,
`oauth.list`, `oauth.providers`) are owned by `@agentskit/os-headless` and
wired at sidecar boot — this module supplies the pure logic those handlers
delegate to.

## Public exports

**Provider registry** (`oauth-hub.ts`):
- `OAuthProviderId` — union of all 15 supported provider string literals
- `OAuthProviderSpec` — shape of a provider entry (`authorizationUrl`, `tokenUrl`, `defaultScopes`, `usePkce`, `extraAuthParams`)
- `OAUTH_PROVIDERS` — `readonly OAuthProviderSpec[]` of all built-in providers
- `findOAuthProvider(id)` — look up a spec by id
- `listOAuthProviders()` — return all specs
- `OAuthConnection` — live connection record (`providerId`, `accountId`, `scopes`, `accessTokenExpiresAt`, `hasRefreshToken`, `connectedAt`)
- `OAuthHub` / `createOAuthHub(initial?)` — in-memory connection map with `list`, `find`, `upsert`, `revoke`
- `RefreshNeed` / `findRefreshes(hub, nowMs, windowMs?)` — pure helper that returns connections expiring within `windowMs`

**Pending-auth / PKCE store** (`oauth/state-store.ts`):
- `PendingAuthStore` / `createPendingAuthStore(opts?)` — bounded insertion-ordered map correlating opaque `state` tokens to in-flight authorize requests; `put`, `take` (atomic read-remove), `evictExpired`
- `defaultPendingAuthStore` — process-wide singleton
- `PendingState`, `PendingAuth`, `CreatePendingAuthStoreOptions`

**Device-code store** (`device-code-store.ts`):
- `createInMemoryDeviceCodeStore<TGrant>(opts?)` — bounded, TTL-backed device-code lifecycle shared by cloud and headless hosts; full capacity rejects new starts without evicting pending grants
- `DeviceCodeStore<TGrant>` / `DeviceCodePollResult<TGrant>` — framework-neutral host contract; the first granted poll atomically consumes the result so hosts can issue canonical credentials only while the client is present
- `CreateInMemoryDeviceCodeStoreOptions<TGrant>` — TTL, poll interval, capacity, clock, randomness, and completer injection

**Token exchanger** (`oauth/token-exchanger.ts`):
- `TokenExchanger` / `createTokenExchanger(opts?)` — injectable `fetch`-based seam for `authorization_code` and `refresh_token` grants; `AbortSignal.timeout` enforces `AKOS_OAUTH_HTTP_TIMEOUT_MS` (default 30 s)
- `defaultTokenExchanger` — process-wide singleton
- `exchangeRefreshToken(args)` — back-compat standalone helper
- `AuthCodeOutcome`, `AuthCodeExchangeArgs`, `ExchangeRefreshTokenArgs`, `OAuthRefreshResult`, `CreateTokenExchangerOptions`

**Token persistence** (`oauth/token-persist.ts`):
- `persistOauthToken(tokenStore, providerId, json, nowIso)` — upserts an `LlmOauthTokenRecord`; returns derived `accountId` or `undefined` on store absence
- `persistInstallationToken(installationTokenStore, providerId, json, nowIso)` — upserts an `InstallationTokenRecord` only when the token JSON contains tenant installation metadata (`installation_id`, Slack `team.id`, Discord `guild.id`, Stripe `stripe_user_id`, Atlassian `cloud_id`, etc.); returns `installationId` or `undefined`
- `deriveAccountId(providerId, json)` — extracts a stable account id from JWT `sub`, upstream `account_id`/`user_id`/`email`, or a deterministic SHA-256 hash fallback
- `pickScopes(fromResp, fromExisting, fallback)` — scope resolution helper

**Env helpers** (`oauth/env.ts`):
- `envKeyForClientId(id)` / `envKeyForClientSecret(id)` — `AKOS_OAUTH_<PROVIDER>_CLIENT_ID/SECRET`
- `readClientId(env, id)` / `readClientSecret(env, id)` — safe trimmed readers
- `defaultRedirectUri(env, id)` — provider-specific override → `AKOS_OAUTH_REDIRECT_URI` → `http://127.0.0.1:7345/oauth/callback`

**Refresh scheduler** (`oauth-scheduler.ts`):
- `OAuthScheduler` — `{ start(), stop(), tick() }` handle returned by `startOAuthRefreshScheduler`
- `startOAuthRefreshScheduler(opts)` — creates and returns an `OAuthScheduler` that polls `findRefreshes` on `intervalMs` cadence and calls the caller's `OAuthRefreshFn` for each expiring connection
- `OAuthSchedulerOpts` / `OAuthRefreshFn` / `OAuthRefreshResult` — types for the interval-based scheduler wired at sidecar boot
- `exchangeRefreshToken(args)` — back-compat re-export (now lives in `oauth/token-exchanger.ts`); `ExchangeRefreshTokenArgs` / `OAuthRefreshResult` re-exported for callers on the old import path

**LLM-provider PKCE subflow** (`@agentskit/os-oauth/llm-pkce`):
- `pendingLlmPkce` / `evictPendingLlmPkceIfOver()` — process-memory PKCE verifier map keyed by `state`, with size-cap (10k) FIFO eviction
- `ensureLlmOauthListener(cb, state?)` / `stopLlmOauthListener(state?)` / `scheduleLlmOauthListenerShutdown(state?)` — loopback `127.0.0.1` HTTP listener (`/oauth/llm-callback`) with idle shutdown
- `createLlmOauthListenerState()` / `resetDefaultLlmOauthListenerStateForTest()` — injectable listener-state factory; `reset*` zeroes the module-level default (test isolation)
- `resolveCallbackUrl({ enableAutoCallback, explicit, listenerOnCallback })` — resolve the callback URL, starting the listener when `enableAutoCallback` is set
- `startOpenRouterFlow(args)` / `startVertexFlow(args)` / `startGeminiFlow(args)` — build provider authorize URLs + record pending PKCE state
- `performLlmOauthExchange(env, providerId, state, code)` — exchange the authorization code for an API key / access token
- `refreshLlmOauthToken(args)` — refresh a stored vertex/gemini token via its refresh_token
- `persistOauthToken(tokenStore, result)` — upsert the minted token into an `LlmOauthTokenStore`
- `maskKeyHint(key)` — non-secret masked display hint (e.g. `sk-or…wxyz`; reveals at most first 5 + last 4 chars)

**RPC methods** (defined in `os-contracts/src/methods/integrations/`):
- `oauth.providers` — list configured provider rows (`configured` flag reflects env-var presence)
- `oauth.start` — begin authorization flow; returns `{ authorizeUrl, state, redirectUri }`; requires `connections:write` cap
- `oauth.complete` — exchange code for tokens and persist; requires `connections:write` cap
- `oauth.revoke` — remove a stored connection; requires `connections:write` cap
- `oauth.list` — list connections for the active workspace

## Common questions

> **How do I add a new OAuth provider?**
> Add an `OAuthProviderSpec` entry to the `OAUTH_PROVIDERS` array in `oauth-hub.ts` and extend the `OAuthProviderId` union. Set `usePkce: true` if the provider supports it. Supply `extraAuthParams` for any non-standard authorize-URL params needed to force refresh-token issuance (e.g. `prompt: 'consent'` for Atlassian, `token_access_type: 'offline'` for Dropbox). The sidecar's `oauth.providers` handler will automatically expose the new entry; operators must set `AKOS_OAUTH_<PROVIDER>_CLIENT_ID` and `AKOS_OAUTH_<PROVIDER>_CLIENT_SECRET` for `configured: true`.

> **How does the refresh scheduler keep tokens alive?**
> `findRefreshes(hub, nowMs, windowMs?)` (default window: 5 minutes) returns every `OAuthConnection` whose `accessTokenExpiresAt` falls within the window and that carries a refresh token. The scheduler calls the caller-supplied `OAuthRefreshFn` (which resolves the refresh token from vault and calls `createTokenExchanger().exchangeRefreshToken`), then writes the rotated expiry back via `hub.upsert`. Tokens without an `expiresAt` or without a refresh token are skipped silently.

> **How is `accountId` derived when the provider doesn't return an OIDC `id_token`?**
> `deriveAccountId` attempts, in order: (1) JWT `sub` from `id_token`, (2) `account_id` / `user_id` / `team_id` / `email` top-level fields on the token JSON, (3) a deterministic SHA-256 hash of `providerId + accessToken[0..8]`, yielding an `anon-<8hex>` string. This guarantees a stable, non-colliding account key even for providers (like Stripe) that omit user-identity claims from their token response.

Source: /raw/for-agents/packages/os-oauth.md

### for-agents/packages/os-observability.md

# packages/os-observability

## Purpose

Pure decision logic converting OS runtime events into structured logs,
traces, and metrics. Provides pluggable sinks (in-memory, PostHog, OTLP,
Datadog, Grafana) plus higher-level primitives: anomaly detection engine,
incident lifecycle, cost heat maps, replay timeline, and bisect oracle.
No IO is forced on consumers — all writers and exporters are injected via
options.

Post-ADR-0142: `replayEvents` now delegates to the upstream
`@agentskit/observability` package's `replayEvents` generic driver; the
os-core `AnyEvent` stream flows through unchanged. Local bisect and
timeline helpers are unaffected.

## Public exports

### Log sink (`src/log-sink.ts`, `src/console-writer.ts`)
- `createLogSink`, `defaultClassify`, `defaultFormat`, `defaultExtract`
- Types: `LogLevel`, `LogLine`, `LogWriter`, `LogSinkOptions`
- `consoleLogWriter` (+ `ConsoleLogWriterOptions`) — default JSON-line writer
  (picks `console.debug/info/warn/error` per level; injectable console for tests)

### Replay (`src/replay.ts`)
- `replayEvents` — delegates to `@agentskit/observability` (ADR-0142)

### Trace collector (`src/trace-collector.ts`)
- `createTraceCollector`, `defaultClassifyLifecycle`, `classifyPipelineLifecycle`,
  `defaultKindOf`, `defaultNameOf`
- Types: `Span`, `SpanExporter`, `SpanKind`, `SpanStatus`, `SpanLifecycle`,
  `TraceCollectorOptions`
- `InMemorySpanExporter` (`src/in-memory-span-exporter.ts`)

### Metrics registry (`src/metrics-registry.ts`)
- `createMetricsRegistry`
- Built-in rules: `eventCountRule`, `durationRule`, `costRule`, `DEFAULT_METRIC_RULES`
- Pipeline rules: `pipelineRunTotalRule`, `phaseDurationMsRule`,
  `pipelineRunStatusTotalRule`, `PIPELINE_METRIC_RULES`
- SLO helper: `recordSidecarColdBoot` (+ `RecordSidecarColdBootOpts`),
  `SIDECAR_COLDBOOT_METRIC`
- Types: `MetricKind`, `MetricPoint`, `MetricSink`, `MetricRule`,
  `MetricsRegistryOptions`

### Metric sink (`src/in-memory-metric-sink.ts`)
- `InMemoryMetricSink`
- Types: `Agg`, `CounterAgg`, `GaugeAgg`, `HistogramAgg`,
  `InMemoryMetricSinkOptions` (O(1) bounded raw-point retention and fixed-size
  cumulative histogram buckets for long-lived processes)

### Prometheus renderer (`src/prometheus.ts`)
- `renderPrometheus`, `PROMETHEUS_CONTENT_TYPE`
- Types: `PromSeries`, `PrometheusRenderOptions`

### Trace context (`src/trace-context.ts`)
- `TRACEPARENT_HEADER`, `childTraceparent`, `continueTrace`, `formatTraceparent`,
  `injectTraceparent`, `isSampled`, `newSpanId`, `newTraceContext`, `newTraceId`,
  `parseTraceparent`
- Type: `TraceContext`

### Cost bridge (`src/cost-bridge.ts`)
- `costEntryToMetricPoints`, `createCostMetricsRecorder`
- Types: `CostEntryShape`, `CostBridgeLabels`, `CostMetricsRecorderOptions`

### Incidents (`src/agent-incident.ts`, `src/agent-incident-types.ts`)
- `applyIncidentTransition`, `buildIncidentAuditExport`, `createAgentIncident`,
  `renderIncidentMarkdown`
- Types: `AgentIncident`, `CreateAgentIncidentInput`, `IncidentAuditExport`,
  `IncidentCustomerImpact`, `IncidentLink`, `IncidentRcaNotes`,
  `IncidentRollbackAction`, `IncidentSeverity`, `IncidentStatus`,
  `IncidentTimelineEntry`, `IncidentTransition`

### Anomaly engine (`src/anomaly-engine.ts`)
- `createAnomalyEngine`
- Types: `AnomalyBus`, `AnomalyEngine`, `AnomalyEngineOpts`, `AnomalyEvent`,
  `AnomalyProjector`, `AnomalySink`

### Anomaly presets (`src/anomaly-presets.ts`)
- `ANOMALY_PRESET_IDS`, `BUILTIN_ANOMALY_RULES`, `defaultAnomalyRuleSet`,
  `getAnomalyPreset`
- Type: `AnomalyPresetId`

### Cost heat map (`src/cost-heat-map.ts`)
- `buildCostHeatMap`, `totalCostForTag`
- Types: `CostHeatCell`, `CostHeatMap`, `CostHeatSample`, `HeatMapBucket`

### Replay timeline + bisect
- `buildTimeline`, `diffState`, `positionAt` (+ types `ReplayPosition`, `ReplayStep`,
  `StateDiffEntry`, `Timeline`, `TimelineRow`)
- `replayBisect` (+ `BisectOpts`, `BisectVerdict`, `ReplayOracle`)

### Decision log (`src/decision-log.ts`)
- `buildDecisionLogEntry`, `filterDecisionLog`
- Types: `DecisionAlternative`, `DecisionLogEntry`, `DecisionLogInput`, `DecisionLogQuery`

### Exporters (`src/exporters/`)
- Langfuse: `createLangfuseExporter`, `spanToLangfuseEvent`
  (+ `LangfuseExporterOpts`, `LangfuseHttp`)
- PostHog: `createPostHogExporter`, `spanToPostHogEvent`
  (+ `PostHogExporterOpts`, `PostHogHttp`)
- Datadog: `createDatadogMetricSink`, `createDatadogSpanExporter`,
  `metricPointToDatadogSeries`, `spanToDatadogLog`
  (+ `DatadogHttp`, `DatadogSinkOpts`)
- Grafana (OTLP/HTTP): `createGrafanaMetricSink`, `createGrafanaSpanExporter`,
  `metricPointToOtlpJson`, `spanToOtlpJson`
  (+ `GrafanaHttp`, `GrafanaSinkOpts`)

### Redaction (`src/redaction-profiles.ts`, `src/field-redaction.ts`)
- `createSubstringRedactor`, `getRedactionProfile`, `REDACTION_PROFILES`
  (+ `RedactionProfile`, `RedactionProfileId`)
- `applyFieldRedaction` (+ `FieldRedactionConfig`, `FieldRedactor`, `FieldSelector`)

### LLM span (`src/llm-span.ts`)
- `LlmSpanAttr`, `noopLlmTracer` (+ `LlmSpan`, `LlmTracer`, `SpanAttributeValue`)

### Constants
- `PACKAGE_NAME`, `PACKAGE_VERSION`

## Sub-paths (RFC-0017)

- `@agentskit/os-observability/backend` — `ObservabilityStores`,
  `createObservabilityBackendHandlers`, `createInMemoryObservabilityStores`.
  Read-path stores for `runs.list`, `traces.list`, `cost.summary`,
  `dashboard.stats`, `anomalies.list`, `incidents.list`.
- `@agentskit/os-observability/otel` — OTel adapters: `createOtelSpanExporter`,
  `createOtelLogWriter`, `createOtelMetricSink`, `createOtelEnvBridge`.
- `@agentskit/os-observability/alerting` — outbound alert router:
  `createAlertRouter`, `parseAlertRoutingConfig`, `anomalyEventToAlert`,
  `severityRoutes`, payload mappers (`pagerDutyPayload`, `opsGeniePayload`,
  `slackPayload`, `webhookPayload`), Zod schemas (`AlertDestination`,
  `AlertRoutingConfig`, `AlertSeverity`, `AlertProviderKind`).
  Types: `AlertEnvelope`, `AlertHttp`, `AlertHttpRequest`, `AlertDeliveryResult`,
  `AlertRouter`, `AlertRouterOpts`.
- `@agentskit/os-observability/runtime` — file-backed runtime store wiring
  (anomaly rules, incidents, topology, exporters store, exporters handlers,
  anomaly detector service). For os-headless / sidecar wiring only.
- `@agentskit/os-observability/coding-task-report` — re-exports for coding
  task report integration.

## Wired stores

`InMemorySpanExporter` and `InMemoryMetricSink` hold data in-process.
Durable cost rows live in `os-storage` (`CostStore`). OTLP exporter is
wired by `os-headless/src/observability-otel-wire.ts`.

## Methods implemented / consumed

Implemented (owner `@agentskit/os-observability`):

- `cost.list` / `cost.summary` — itemized cost rows and windowed aggregate
- `runs.list` / `runs.get` / `runs.cancel` — run record access
- `traces.list` / `traces.get` / `traces.export` — span record access
- `dashboard.summary` — aggregate dashboard counters
- `observability.exporters.test` — smoke-test a configured exporter
- `observability.anomalyRules.list` / `.upsert` / `.delete` / `.setPaused`
- `observability.anomaly.evaluate` — evaluate a metric sample against persisted rules,
  fan out to anomaly/slack/email notification channels (ADR-0120 SU-6)
- `observability.incidents.get` / `.assign` / `.transition`
- `observability.metrics.timeseries` — windowed time series for dashboards
- `observability.topology.get` — service dependency graph
- `incidents.list`
- `workspace.config.exporters.get` / `.set` — read/write exporter config

Consumed: `os-flow` for `FlowCostTickEvent`; `os-copilot` for `CopilotCostEvent`.

## Common questions

> **How do I add a custom anomaly rule?**
> Call `createAnomalyEngine({ ruleSet: { rules: [...BUILTIN_ANOMALY_RULES, myRule] }, bus, subscribePattern, project })`.
> Each rule is an `AnomalyRule` from `@agentskit/os-core` (id, metric, op, threshold,
> windowSeconds, severity). Alternatively load a preset via `getAnomalyPreset(id)` and
> spread the rules into your rule set.

> **How does the live anomaly detection service work?**
> Use `createAnomalyDetectionService` from `@agentskit/os-observability/runtime`.
> It subscribes to the trace EventBus and invokes `onDetection` once per fresh alert
> (deduped by ruleId until severity recovers). Rule sets are reloaded on a throttle
> (default 5s) so `anomalyRules.upsert` / `.delete` take effect without a restart.

> **How do I export spans to OTLP?**
> Wire `os-headless/src/observability-otel-wire.ts` which sets up the OTLP
> span exporter using `AKOS_OTEL_ENDPOINT`. The `InMemorySpanExporter` is
> used in tests and as a fallback when the endpoint is not set.

> **How do I export traces to Datadog or Grafana?**
> Use `createDatadogSpanExporter` or `createGrafanaSpanExporter`, both from
> the main entry point. Inject a `fetch`-compatible `http` transport. Metrics
> go to `createDatadogMetricSink` / `createGrafanaMetricSink` respectively.

> **How do I expose metrics to Prometheus?**
> Call `renderPrometheus(sink.series())` (where `sink` is an
> `InMemoryMetricSink` fed by `createMetricsRegistry`) to get the
> Prometheus text-exposition format. The os-headless HTTP transport
> (`metricsSource` option) and the cloud server (`metrics` option) both
> serve this on an auth-gated `GET /metrics` endpoint (ADR-0074). Never
> public — it requires the configured bearer token.

> **How does `replayBisect` work?**
> It binary-searches a `Timeline` using an `ReplayOracle` predicate. Pass a
> function that returns `'pass' | 'fail'` for a given `ReplayPosition`. The
> bisect returns `BisectVerdict` with the first failing position — useful for
> pinpointing which node in a replay introduced a regression.

> **How does the alert router work?**
> Import from `@agentskit/os-observability/alerting`. Parse config with
> `parseAlertRoutingConfig`, then call `createAlertRouter({ config, http })`.
> `router.deliver(alert)` fans the alert to all matching destinations
> (severity routing, dedup window, exponential-backoff retry). Supported
> providers: `pagerduty`, `opsgenie`, `slack`, `webhook`. Use
> `anomalyEventToAlert(event, workspaceId)` to convert an `AnomalyEvent`
> into the router's `AlertEnvelope`.

> **How do I record the sidecar cold-boot SLO metric?**
> Call `recordSidecarColdBoot({ durationMs, sink })` once at startup after
> the first healthy response. Emits a `sidecar_coldboot_duration_ms`
> histogram point (label `source=sidecar`) into the provided `MetricSink`.
> Sink errors are silently swallowed — this call never throws.

Source: /raw/for-agents/packages/os-observability.md

### for-agents/packages/os-oem.md

# packages/os-oem

## Purpose

OEM tenancy subsystem, extracted from `os-headless` per ADR-0119. Owns the
back-of-house for white-label / multi-tenant OEM deployments:

- **Brand-kit / whitelabel** — per-tenant branding config + an in-memory store.
- **License verification** — verifies a signed license envelope (ed25519) and
  enforces seat counts, surfacing a `valid` / `invalid` status with customer +
  seat usage.
- **Domain packs** — provisioning of vertical domain packs for a tenant.

Pure backend handler factories: `createOemHandlers` (`oem.*`) and
`createOemTenantHandlers` (`oem.tenants.*`). The headless sidecar wires both into
its dispatcher's composition root. No UI, no transport.

## Public exports

- `createOemHandlers(opts: OemHandlersOptions): HandlerMap` — builds the `oem.*`
  handlers (brand kit, whitelabel, license, packs).
- `OemHandlersOptions` — `workspaceRoot?`, `brandKitStore?`, `licenseEnvelopePath?`,
  `licensePublicKeyPem?`, `licenseProductId?`, `licenseActiveSeats?()`,
  `installedPacksStore?`, `agentInlineStore?`, `flowStore?`, `workspaceId?`,
  `actor?()`, `now?()`, `cliBinary?`, `cliTimeoutMs?`.
- `createOemTenantHandlers(opts: OemTenantHandlersOptions): HandlerMap` — builds
  the `oem.tenants.*` handlers over an `OemTenantStore`.
- `OemTenantHandlersOptions` — `store?`, `now?()`, `actor?()`,
  `licensePrivateKeyPem?`, `idGenerator?()`.
- Re-exports: `BrandKitStore`, `LicenseState` (types), `createInMemoryBrandKitStore`.

## Handler map: oem.*

Registered by `createOemHandlers`:

| Handler | Description |
|---|---|
| `whitelabel.runtime.get` | Reads `<workspaceRoot>/.agentskitos/whitelabel.runtime.json`. Returns `{ runtime }`. |
| `whitelabel.runtime.set` | Writes the runtime JSON file. Returns `{ ok: true }`. |
| `whitelabel.cli.run` | Spawns `agentskit-whitelabel <subcommand>`. Returns `{ stdout, stderr, code }`. |
| `oem.brand-kit.get` | Returns `{ kit: OemBrandKit \| null }` from the brand-kit store. |
| `oem.brand-kit.set` | Parses + stores an `OemBrandKit` (Zod-validated). |
| `oem.brand-kit.upload-asset` | Writes a base64 asset (`logo`/`favicon`/`splash`) to `<workspaceRoot>/.agentskitos/oem/assets/`. Returns `{ kind, path, sha256, bytes }`. Rejects empty payloads and payloads > 2 MB. |
| `oem.packs.list` | Lists domain packs. Optional `filter: 'installed' \| 'available'`. Returns `{ rows }`. |
| `oem.packs.apply` | Installs a domain pack by id; materializes agents + flows into wired stores. Returns `{ ok, applied: { agents, flows, terminology, securityDefaults } }`. |
| `oem.packs.uninstall` | Removes a domain pack and reverses materialization. Returns `{ ok, removed: { agents, flows } }`. |
| `oem.license.status` | Returns `{ state, features, seats: { used, total }, customer?, tier?, issuedAt?, expiresAt?, graceDaysRemaining? }`. |
| `oem.license.import` | Verifies + atomically writes a signed envelope to `licenseEnvelopePath`. Returns `{ ok, state? }` or `{ ok: false, reasons }`. |

## Handler map: oem.tenants.*

Registered by `createOemTenantHandlers`:

| Handler | Description |
|---|---|
| `oem.tenants.list` | Returns `{ rows: OemTenantRow[] }`. |
| `oem.tenants.create` | Creates a new tenant row. Params: `name`, `seats?`, `billingContact?`, `brandKitRef?`, `brandOverride?`, `note?`. Returns `{ ok: true, tenant }`. |
| `oem.tenants.update` | Patches an existing tenant. Returns `{ ok, tenant }` or `{ ok: false, reasons }` if not found. |
| `oem.tenants.suspend` | Sets status to `'suspended'` or `'active'`. Returns `{ ok, tenant }`. |
| `oem.tenants.issueLicense` | Signs a license envelope for the tenant. Resolves signing key from `params.privateKeyPem` → `opts.licensePrivateKeyPem` → `AKOS_LICENSE_PRIVATE_KEY`. Returns `{ ok, envelope, tenant }` or `{ ok: false, reasons }`. |
| `oem.tenants.revokeLicense` | Clears `licenseEnvelope` + `licenseExpiresAt` from the tenant row. |
| `oem.tenants.delete` | Permanently deletes a tenant row. Returns `{ ok }` or `{ ok: false, reasons }`. |

## Common questions

> **How does `oem.license.status` decide valid vs invalid?**
> `createOemHandlers` is given `licenseEnvelopePath` + `licensePublicKeyPem` +
> `licenseProductId` + an `licenseActiveSeats()` callback. It reads + verifies
> the ed25519-signed envelope (via `@agentskit/os-license`), checks the product
> id and expiry, and compares active seats against the licensed total. Returns
> `{ state, customer?, seats: { used, total } }`. A missing/invalid envelope
> yields the `invalid-product` fallback.

> **Why is this its own package?**
> OEM tenancy (branding + license + packs) is a self-contained domain, not part
> of the headless runner's wiring. Extracting it (ADR-0119) shrinks the
> os-headless god-package. Its surface is the `oem.*` / `oem.tenants.*` handler
> maps, so the extraction did not change the os-headless RPC contract.

> **How do I wire it?**
> `createDefaultHandlers` in os-headless forwards `licenseEnvelopePath` etc into
> `createOemHandlers` and spreads the result into the dispatcher. To use
> standalone, call the factory and merge the returned `HandlerMap` into your own
> dispatcher.

Depends on `@agentskit/os-license` (envelope verification), `@agentskit/os-storage`
(tenant + brand-kit stores + `InstalledPacksStore`), `@agentskit/os-templates`
(domain packs + `findTemplate`), `@agentskit/os-contracts` (`HandlerMap` + `OemBrandKit`),
`@agentskit/os-core`, `@agentskit/os-log`.

Source: /raw/for-agents/packages/os-oem.md

### for-agents/packages/os-onboarding-telemetry.md

# packages/os-onboarding-telemetry

## Purpose

`@agentskit/os-onboarding-telemetry` captures **usability-only** telemetry for
the Adaptive Ecosystem Onboarding flow. Its single job is to let the product
team understand how onboarding is going — which verticals and tools users pick,
where they stall, how the assistant adjusts — purely to improve UX. Events feed
PostHog (consented, opt-in) and an internal admin insights screen.

This package carries a **strict, structurally-enforced privacy guarantee**: a
signal may only contain enums, short catalog ids, counts and durations. It can
**never** carry free text, PII or business data — no names, message content,
client terminology values, emails, domains or connection ids. The guarantee is
enforced two ways:

1. Every event schema is a `.strict()` Zod object, so unknown keys are rejected
   and nothing extra can be smuggled in.
2. The only string-typed fields are constrained catalog ids
   (`capabilityId`, `vendorId`, `providerId`, `vertical`, each `.min(1).max(64)`).
   Every other field is a literal, enum, number or boolean. A meta-test
   (`tests/privacy-meta.test.ts`) introspects every field of every event and
   fails the build if a key is not on the `SAFE_SIGNAL_FIELDS` allowlist or if a
   non-catalog field is ever a string.

It owns schemas and a thin validating emitter only — no persistence, no network,
no PostHog SDK. The caller supplies a `sink`; this package decides only whether a
signal is valid and whether consent permits emitting it.

## Public exports

- `OnboardingSignalSchema` — the `z.discriminatedUnion('event', [...])` over all
  16 onboarding events (session_started, eula_accepted, consent_decision,
  step_viewed, question_asked, capability_resolved, capability_unresolved,
  vendor_chosen, terminology_adjusted, blueprint_generated, dry_run, approved,
  apply_completed, apply_failed, satisfaction, abandoned).
- Each individual event schema, e.g. `SessionStartedSchema`,
  `CapabilityResolvedSchema`, `SatisfactionSchema`, …
- `OnboardingSignal` — `z.infer` of the union (the validated signal type).
- `SAFE_SIGNAL_FIELDS` / `SafeSignalField` — the closed allowlist of field names
  that any signal may carry; the privacy meta-test asserts every schema field is
  in this set.
- `validateOnboardingSignal(raw)` — parses untrusted input, returning
  `{ ok: true, signal }` or `{ ok: false, reason }`.
- `createOnboardingTelemetry({ sink, consentGranted })` — returns `{ emit(raw) }`
  which validates, then forwards to `sink` only when consent is granted; invalid
  signals are dropped (fail-closed).
- `PACKAGE_NAME`, `VERSION`.

## Common questions

> **How do I emit an onboarding event safely?**
> Build a telemetry instance with your sink and the user's consent flag:
> `const t = createOnboardingTelemetry({ sink, consentGranted })`, then call
> `t.emit({ event: 'step_viewed', stepId: 'vertical' })`. Invalid shapes and
> non-consented sessions are silently dropped — `emit` never throws and never
> leaks an unvalidated value to the sink.

> **Can I add a "free text" field like the user's company name or a note?**
> No. That is the whole point of the package. Adding a free-text `z.string()`
> field (or any string field that is not a constrained catalog id) will fail the
> privacy meta-test. Capture intent with an enum, an id or a count instead.

> **Where do PostHog and the admin screen live?**
> Not here. This package is transport-agnostic: it only validates and gates on
> consent. The `sink` callback is where a higher layer forwards signals to
> PostHog or persists them for the insights screen.

> **Why is `vertical` a string and not an enum?**
> It is a catalog id, like `capabilityId`/`vendorId` — an opaque, short
> identifier from the capability/vertical catalog, constrained to `min(1).max(64)`.
> It is not free text and is treated as a catalog id by the privacy meta-test.

Source: /raw/for-agents/packages/os-onboarding-telemetry.md

### for-agents/packages/os-otel-grafana.md

# packages/os-otel-grafana

## Purpose

Grafana Cloud OTLP exporter adapter. Creates an `ExporterAdapter` (traces + metrics + logs) backed by the official `@opentelemetry/exporter-*-otlp-http` SDKs pointed at Grafana Cloud's OTLP endpoint. This is the only package in the monorepo permitted to import these exporter SDKs (`check:vendor-isolation`). Injected into `@agentskit/os-telemetry` at app composition time. Can also target a self-hosted OTLP collector (Grafana + Tempo + Mimir) by setting `otlpUrl` accordingly.

Stability: **internal** (L2 binding). Distribution: cloud + admin + web. Epic: ef-04 SU4.5 (#2990, parent #2941/#2936).

## Public exports

- `createGrafanaCloudExporter(cfg: TelemetryExporterConfig, metricIntervalMs?: number)` → `ExporterAdapter` — validates `cfg` with Zod at the boundary, builds OTLP trace / metric / log exporters, returns them as a single `ExporterAdapter` for injection into `initOtel`.
- `ExporterAdapter` — type re-exported from `@agentskit/os-telemetry` for convenience (avoids double-import of the telemetry package at call sites).

```ts
// TelemetryExporterConfig — Zod schema in @agentskit/os-core/ports/telemetry
interface TelemetryExporterConfig {
  otlpUrl: string         // OTLP base URL; sub-paths /v1/traces, /v1/metrics, /v1/logs are appended
  authHeader?: string     // 'Basic <base64(instanceId:token)>' or 'Bearer <token>' — omit for local collectors
  samplingRatio?: number  // [0, 1]; default 1.0 (all traces); set 0.1 for 10 % prod sampling
}
```

`cfg` is re-validated with `TelemetryExporterConfig.parse()` inside the factory — even if the caller pre-parsed it. This defends against cross-package type drift.

Default metric export interval: 15 000 ms. Pass `metricIntervalMs` to override (e.g. `1_000` in integration tests).

Internally builds:
- `OTLPTraceExporter` → `<otlpUrl>/v1/traces`
- `OTLPMetricExporter` wrapped in `PeriodicExportingMetricReader` → `<otlpUrl>/v1/metrics`
- `OTLPLogExporter` → `<otlpUrl>/v1/logs`

## Wiring example

```ts
import { TelemetryExporterConfig } from '@agentskit/os-core/ports/telemetry'
import { createGrafanaCloudExporter } from '@agentskit/os-otel-grafana'
import { initOtel } from '@agentskit/os-telemetry'

// At app boot (apps/cloud, apps/admin, apps/web):
const exporter = createGrafanaCloudExporter(
  TelemetryExporterConfig.parse({
    otlpUrl: process.env['OTEL_EXPORTER_OTLP_ENDPOINT'],
    authHeader: process.env['OTEL_EXPORTER_OTLP_HEADERS_AUTHORIZATION'],
    samplingRatio: process.env['NODE_ENV'] === 'production' ? 0.1 : 1.0,
  }),
)

await initOtel({ serviceName: 'agentskit-cloud', serviceVersion: GIT_SHA, exporter })
```

## Environment variables (conventional — not read by this package directly)

| Variable | Example | Notes |
|---|---|---|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `https://otlp-gateway-prod-us-central-0.grafana.net/otlp` | OTLP base URL; maps to `cfg.otlpUrl` |
| `OTEL_EXPORTER_OTLP_HEADERS_AUTHORIZATION` | `Basic dXNlcjp0b2tlbg==` | Auth header value; maps to `cfg.authHeader` |

These are conventional names from the OTel spec. The package does not read `process.env` directly — callers parse env vars and pass them as `TelemetryExporterConfig`.

## Wired stores

None. Stateless factory; no singletons.

## Methods implemented

Not a JSON-RPC surface. Injected into `initOtel`/`initTelemetry` from `@agentskit/os-telemetry`.

## Methods consumed

- Grafana Cloud OTLP HTTP ingest API (HTTPS, outbound from the server process).
- `@opentelemetry/exporter-trace-otlp-http`, `@opentelemetry/exporter-metrics-otlp-http`, `@opentelemetry/exporter-logs-otlp-http`, `@opentelemetry/sdk-metrics`.

## Relationship to os-observability / os-telemetry

```
apps/*
  └─ @agentskit/os-telemetry   ← initOtel / initTelemetry / getTracer / getMeter / getLogger
       └─ ExporterAdapter port  ← injected at boot
            └─ @agentskit/os-otel-grafana  ← this package (createGrafanaCloudExporter)
                 └─ Grafana Cloud OTLP endpoint  (HTTP)
```

`os-otel-grafana` is the only concrete binding allowed to import the heavy OTLP exporter SDKs (`check:vendor-isolation`). All other packages obtain tracers/meters/loggers from `@agentskit/os-telemetry` handles only.

## Common questions

> **How do I get the Grafana Cloud OTLP URL and auth header?**
> In Grafana Cloud: *Home → Connections → Data sources → Add → OpenTelemetry (OTLP)*. Copy the OTLP endpoint and generate a service account token. Encode `<instanceId>:<token>` as Base64 and prefix with `Basic `.

> **How do I disable sampling in development?**
> Pass `samplingRatio: 1.0` (the default). To send only 10 % of traces in production, pass `samplingRatio: 0.1`. The ratio is stored in the config and read by the `os-telemetry` SDK initializer — it is not enforced inside this adapter.

> **Can I use a self-hosted Grafana + Tempo + Mimir stack?**
> Yes — set `otlpUrl` to your OTLP collector endpoint and omit `authHeader` for unauthenticated local collectors.

> **Can I write a test double instead of calling Grafana Cloud?**
> Yes — inject any object satisfying `ExporterAdapter` into `initOtel`. The in-memory `ConsoleSpanExporter` from `@opentelemetry/sdk-trace-base` works well for unit tests. Use `os-otel-grafana` only in integration / staging / production environments.

## Error codes

No package-specific `AK_*` codes. Factory validation failures surface as `ZodError` (Zod boundary). Factory logs via `createLogger('otel-grafana.factory')` at `info` level on successful adapter creation.

## Tests

`packages/os-otel-grafana/tests/grafana-exporter.test.ts`.
Coverage threshold: 100 % statements / branches / functions / lines.

Source: /raw/for-agents/packages/os-otel-grafana.md

### for-agents/packages/os-pdf.md

# packages/os-pdf

## Purpose

Port + default PdfKit adapter for branded PDF generation. Defines the `PdfDocument` declarative tree, `PdfSection` section types, and the `PdfRenderer` port. The default adapter uses `pdfkit` to serialise the document to bytes. Brand tokens from `@agentskit/os-whitelabel` `BrandKit` are applied at render time: primary color accent for headings, logo on the cover header, and footer text. Body/heading fonts use built-in Helvetica (custom font support via `brand.typography` is deferred). The port lives here rather than in `os-core` because PDF generation is heavier-weight and carries a direct `@agentskit/os-whitelabel` dependency.

Stability: **alpha** (Pre-1.0; port + pdfkit adapter). Distribution: cloud + admin. Epic: ef-07 SU7.12 (#3023, parent #2944/#2936).

## Public exports

Port types:
- `PdfDocument`, `PdfSection`, `PdfRenderer`, `LogoSource` — TypeScript types.

```ts
// from packages/os-pdf/src/types.ts
type PdfSection =
  | { kind: 'heading'; text: string; level: 1 | 2 | 3 }
  | { kind: 'paragraph'; text: string }
  | { kind: 'table'; columns: string[]; rows: string[][] }
  | { kind: 'spacer'; height?: number }

interface PdfDocument {
  brand: BrandKit          // from @agentskit/os-whitelabel
  title: string
  sections: PdfSection[]
  logoSource?: LogoSource  // optional pre-resolved logo bytes or URL
}

interface PdfRenderer {
  render(doc: PdfDocument): Promise<Uint8Array>
}

type LogoSource = { url: string } | { bytes: Uint8Array }
```

Adapter:
- `createPdfKitRenderer()` → `PdfRenderer` — default pdfkit-backed renderer. Applies `brand.colors['primary']` as heading accent, `brand.pdf.footerText ?? brand.legalName` as page footer, and `brand.logo.lightUrl` (or `logoSource`) as the cover header logo. Typography uses built-in Helvetica; custom font support (`brand.typography`) is deferred.

## Invariants & gotchas

- **`types.ts` is type-only — zero runtime statements.** `src/types.ts` contains only `type` and `interface` declarations. `src/index.ts` re-exports them with `export type { … }`. Adding any const, class, or function to `types.ts` would introduce a runtime import side-effect that callers don't expect.
- **The renderer uses `PDFKit.PDFDocument` types, not `any`.** The internal type alias `type PdfKitDoc = PDFKit.PDFDocument` is used in every renderer function. Do not widen to `any` — the 100% coverage requirement and strict TypeScript config will catch it, but the type contract also matters for downstream type-checking.
- **Coverage threshold is 100% across all metrics.** `vitest.config.ts` sets `thresholds: { lines: 100, functions: 100, branches: 100, statements: 100 }`. Every new branch in `pdfkit-renderer.ts` requires a matching test in `tests/pdfkit-renderer-branches.test.ts` or `tests/pdfkit-renderer-coverage.test.ts`.
- **pdfkit is vendor-isolated to `pdfkit-renderer.ts`.** All `pdfkit` imports are confined to that single file. Do not import `pdfkit` in `types.ts`, `index.ts`, or any new module — keep the port/adapter boundary clean.
- **Logo fetch is skipped when `logoSource.bytes` is present.** The renderer only performs an HTTP fetch if `logoSource` is absent or `{ url }`. Pass `{ bytes: preloadedBytes }` to avoid network calls in server environments; the renderer will use them directly.

## Wired stores

None. Caller is responsible for persisting the returned `Uint8Array` (e.g. via `BlobStore`).

## Methods implemented

Not a JSON-RPC surface. Used directly in `apps/cloud` report-generation handlers and `apps/admin` compliance export endpoints.

## Methods consumed

- `pdfkit` npm package — vendor-isolated to `pdfkit-renderer.ts` within this package.
- `@agentskit/os-whitelabel` `BrandKit` — brand tokens for themed output.

## Common questions

> **How do I generate a compliance PDF?**
> ```ts
> import { createPdfKitRenderer } from '@agentskit/os-pdf'
> const renderer = createPdfKitRenderer()
> const bytes = await renderer.render({
>   brand: resolvedBrandKit,
>   title: 'Audit Report',
>   sections: [
>     { kind: 'heading', text: 'Summary', level: 1 },
>     { kind: 'paragraph', text: '...' },
>     { kind: 'table', columns: ['Event', 'Actor', 'At'], rows: [...] },
>   ],
> })
> await blobStore.put(`${orgId}/reports/${runId}.pdf`, bytes)
> ```

> **How do I avoid a logo HTTP fetch in server environments?**
> Resolve the logo bytes out-of-band and set `logoSource: { bytes: preloadedBytes }`. The renderer skips the HTTP fetch when `logoSource.bytes` is present.

> **Can I swap the renderer for a headless-browser PDF engine?**
> Yes — implement the `PdfRenderer` port (`render(doc) → Promise<Uint8Array>`) and inject at composition time. The port is stable.

## Error codes

No package-specific `AK_*` codes. pdfkit errors surface as native `Error` instances; callers should wrap with `AgentsKitError` at the boundary.

## Tests

`packages/os-pdf/tests/pdfkit-renderer.test.ts` — integration (real pdfkit) + unit (mocked pdfkit) for happy-path and branching.
`packages/os-pdf/tests/pdfkit-renderer-coverage.test.ts` — branch coverage: invalid hex, zero-column table, logo-embed error, URL fetch failure.
`packages/os-pdf/tests/pdfkit-renderer-branches.test.ts` — https mock for fetchLogoBytes success/error paths and buildPdfBytes error-event rejection.

Source: /raw/for-agents/packages/os-pdf.md

### for-agents/packages/os-pipeline.md

# packages/os-pipeline

## Purpose

Pipeline orchestration engine — sequential phase scheduling, approval gating,
kanban item management, dispatch retry, idempotency, and SDLC alias support.
Each pipeline is a named ordered list of phases; each phase maps to a flow
(`flowId`) with optional `inputMapping`, `outputKey`, `requireApproval`, and
`outputContract` guards. `createPipelinesHandlers` wires the full RPC surface
into the `os-headless` composition layer. `createPhaseEngine` drives individual
phase execution: it resolves input mappings, runs the flow with exponential
back-off retry (`withRetry`), validates structured-output contracts
(`validateOutputContract`), and emits `pipeline.run.*` events via `safePublish`.
`createRunOrchestrator` sequences phases, skipping already-completed phases on
resume (`findResumeIndex`) and stopping at the first `requireApproval` gate.
The package sits at ADR-0064 L1 (depends on `os-core`, `os-flow`, `os-storage`,
`os-contracts`, and `os-log` for structured logging).

## Public exports

- **Pipeline factory**: `createPipelinesHandlers`, `createDefaultPipelineRunner`,
  `resolveInputMapping` — wire and drive the full CRUD + dispatch + resume surface.
  Types: `PipelineFlowRunner`, `PipelinesHandlersOptions`, `PipelineConfig`,
  `PipelinePhaseConfig`.
- **Status mappers**: `toRunStatus`, `mapFlowStatus`, `mapStatus`, `summariseRun`,
  `resolveRunEvent`, `resolveReportedStatus`, `isTerminalStatus` — convert between
  `RunRecord['status']`, `RunResult['status']`, and the `PhaseTerminalStatus` enum
  (`pending | running | succeeded | failed | cancelled`).
- **Phase helpers**: `buildPhaseCtx`, `resolvePhaseFlow`, `buildPhaseCtx`,
  `buildGatedExtra`, `findResumeIndex`, `pickForkFlowId`, `isSdlcRun` — construct
  `RunContext` per phase, resolve inline vs stored flows, detect SDLC agent ids.
- **Config serialisation**: `recordToPipelineConfig`, `configToRecord` — lossless
  round-trip between `PipelineRecord` (storage layer) and `PipelineConfig` (API shape),
  preserving `canvas`, timestamps, and all phase fields.
- **Constants**: `PIPELINE_ID` (`'prd-to-pr'`), `PIPELINE_PHASES`
  (`['PRD','Issues','QA','Dev','Test','PR']`).
- **Dispatch retry**: `withRetry`, `isRetryableError`, `validateOutputContract`,
  `RetryPolicy` — exponential back-off for 429/5xx LLM failures; structured-output
  contract guard throwing `AK_LLM_MALFORMED_RESPONSE` on missing required keys.
- **Idempotency**: `IdempotencyRing`, `IdempotencyRingOptions` — deduplicates
  dispatch calls within a 5-minute TTL window by `idempotencyKey`.
- **Events**: `buildEvent`, `safePublish`, `newEventId`, `mintPipelineRunId` —
  construct/publish `pipeline.run.*` + `pipeline.phase.*` domain events and mint
  collision-free `pipe_<id>_<token>` run ids.
- **Pipeline generation**: `createGenerateHandler` (wires `pipelines.generate`),
  `generatePipelineDraft`, plus the building blocks `splitStages`, `classifyKind`,
  `scoreFlow`, `slugify`. Types: `GenerateHandlerDeps`, `GeneratePipelineResult`,
  `PipelineDraft`, `PipelineDraftPhase`, `FlowCandidate`, `PhaseKind`.
- **Artifact persistence**: `persistRunArtifact`, `persistPhaseArtifact`,
  `RunArtifactInput`, `PhaseArtifactInput` — write run/phase output blobs to storage.
- **Bundles**: `applyBundle`, `ensureBundlesDir`, `readJsonSafe`, `stableHash`,
  `compareKeys`, `countSection`, `isJsonFile` — apply SDLC result bundles to the
  filesystem. Types: `ApplyCounts`, `CountableSection`.
  `createBundlesHandlers` + `BundleHandlersDeps` wire bundle RPC handlers.
- **Connection precheck**: `collectPipelineConnectionKinds`,
  `ConnectionPreconditionError`, `ConnectionMissing` — enumerate required
  integration kinds from all phase triggers before dispatch.
- **Path resolver**: `resolvePath`, `resolveMapping` — resolve `inputMapping`
  dot-path expressions against the blackboard context.
- **Sub-factories** (used by `os-headless` composition):
  `createPhaseEngine` (`PhaseEngine`, `PhaseEngineDeps`),
  `createRunOrchestrator` (`RunOrchestrator`, `OrchestratorDeps`, `RunFromIndexResult`),
  `createCrudHandlers` (`CrudHandlersDeps`),
  `createDispatchResume` (`DispatchResume`, `DispatchResumeDeps`),
  `createItemHandlers` (`ItemHandlersDeps`).
- **Legacy SDLC aliases**: `createLegacySdlcHandlers`, `LegacySdlcDeps` —
  backward-compatible handlers for `agentId`s prefixed `sdlc:`.
- **Shared types**: `PhaseRow`, `DispatchParams`, `ResumeParams`, `AppendAuditEntry`,
  `PhaseTerminalStatus`, `SdlcStatus`, `OutputContract`, `GatedResultExtra`.

## RPC methods (implemented in os-contracts/src/methods/pipelines.ts, owned by os-headless)

- `pipelines.list` — list all pipeline definitions in the workspace.
- `pipelines.get` — fetch a single pipeline by id.
- `pipelines.upsert` — create or update a pipeline definition (`pipelines:write`).
- `pipelines.generate` — draft a pipeline definition from a free-text brief (`createGenerateHandler`).
- `pipelines.delete` — delete a pipeline definition (`pipelines:write`).
- `pipelines.runs.list` — list pipeline runs, optionally filtered by `pipelineId`.
- `pipelines.runs.get` — fetch full `PipelineRunDetail` (phases + ctx) for a run.
- `pipelines.runs.dispatch` — start a new pipeline run; phases execute sequentially
  until completion or an approval gate (`pipelines:write`). Accepts `idempotencyKey`.
- `pipelines.runs.resume` — resume a run paused at a `requireApproval` gate (`pipelines:write`).
- `pipelines.runs.cancel` — cancel an in-progress run (`pipelines:write`).
- `pipelines.items.list` — list kanban items (cards) for a pipeline (ADR-0032).
- `pipelines.items.upsert` — create or update a kanban item (`pipelines:write`).
- `pipelines.items.move` — move a kanban item between columns (`pipelines:write`).
- `pipelines.items.delete` — delete a kanban item (`pipelines:write`).
- `pipelines.items.run` — dispatch a pipeline run for a single kanban item (`pipelines:write`).
- `pipelines.items.scanColumn` — scan a column for items eligible to auto-run (`pipelines:write`).
- `bundles.list` / `bundles.import` / `bundles.export` / `bundles.diff` — SDLC result-bundle
  apply/read surface (`createBundlesHandlers`); paths are filename-only, traversal-guarded
  with `AK_PATH_TRAVERSAL_DENIED`.

## Common questions

> **How do I add a human-approval gate between phases?**
> Set `requireApproval: true` on the `PipelinePhaseConfig` entry for the phase
> that should pause before executing. When the run reaches that phase,
> `createRunOrchestrator` stops, the run record is written with status
> `awaiting-approval`, and `pipeline.run.awaiting-approval` is emitted. Call
> `pipelines.runs.resume` with the `pipelineRunId` to continue from where it
> stopped — `findResumeIndex` locates the first phase not yet `succeeded`.

> **How does structured-output contract enforcement work?**
> Declare `outputContract: { label: string, requiredKeys: string[] }` on a
> `PipelinePhaseConfig`. After the flow runner returns, `createPhaseEngine` calls
> `validateOutputContract(output, contract, phaseName)`. If any required key is
> absent or `undefined` in the merged output map, an `AgentsKitError` with code
> `AK_LLM_MALFORMED_RESPONSE` is thrown, the phase is recorded as `failed`, and
> all downstream phases are skipped. Phases without `outputContract` pass through
> unchanged — existing flows are unaffected.

> **What retry behaviour applies to LLM dispatch failures?**
> `withRetry(fn, policy)` retries transient errors (HTTP 429, 5xx, network
> timeouts) using exponential back-off. The active `RetryPolicy` is resolved
> from `opts.workspaceDispatchRetryPolicy` (workspace config), falling back to
> `opts.retryPolicy`, then to a legacy single-attempt no-retry default for tests
> with no workspace config. `PRODUCTION_RETRY_DEFAULTS` from `os-core` is the
> recommended policy for production deployments.

Source: /raw/for-agents/packages/os-pipeline.md

### for-agents/packages/os-rag-adapters.md

# @agentskit/os-rag-adapters

> **Status:** alpha — L2 binding layer (ADR-0064 Phase 3)

## Purpose

Concrete implementations of the ports defined in `@agentskit/os-rag` (`Embedder`, `Loader`, `VectorStore`, `Reranker`). The RAG core holds only ports and pure chunker/indexer logic; swapping an adapter requires no changes to `os-rag` itself.

Phases 3a (embedders), 3b (loaders), and 3c (vector stores + rerankers) are all shipped.

## Package info

| Field | Value |
|-------|-------|
| npm name | `@agentskit/os-rag-adapters` |
| stability | alpha |
| layer | L2 binding (ADR-0064) |
| peer deps | `@agentskit/os-core`, `zod ^4`, plus optional per-adapter deps (see below) |

## Public exports

### Embedders

```ts
createOpenAIEmbedder(opts: OpenAIEmbedderOptions)
createVoyageEmbedder(opts: VoyageEmbedderOptions)
createCohereEmbedder(opts: CohereEmbedderOptions)
createGeminiEmbedder(opts: GeminiEmbedderOptions)
```

### Document loaders

```ts
LOADERS            // loader registry map
getLoader(kind)    // look up loader by kind string

folderLoader       // local filesystem folder
urlLoader          // single URL
githubLoader       // GitHub repo tree
notionLoader       // Notion workspace
driveLoader        // Google Drive
s3Loader           // AWS S3
pdfLoader          // PDF file
confluenceLoader   // Confluence space
gcsLoader          // Google Cloud Storage
dropboxLoader      // Dropbox
onedriveLoader     // OneDrive / SharePoint
httpCrawlLoader    // recursive HTTP crawl (RFC-0010 §1)
slackLoader        // Slack channels
gitlabLoader       // GitLab repo tree
postgresLoader     // PostgreSQL table / query
mysqlLoader        // MySQL table / query
sharepointLoader   // SharePoint document libraries
githubIssuesLoader // GitHub Issues

createLoaderResilience(opts: LoaderResilienceOptions): LoaderResilience
```

### Knowledge connectors

```ts
createOneDriveConnector(opts: OneDriveConnectorOpts)
createS3Connector(opts: S3ConnectorOpts)
createGcsConnector(opts: GcsConnectorOpts)
createDropboxConnector(opts: DropboxConnectorOpts)
createDriveConnector(opts: DriveConnectorOpts)
createConfluenceConnector(opts: ConfluenceOpts)
createNotionConnector(opts: NotionOpts)
```

`createConfluenceConnector` and `createNotionConnector` use the older
`DigestRequest` / `DigestResult` connector pattern (not `runLoaderDigest`).
They return a `KnowledgeConnector` with `id`, `source`, and `digest(req)`.

| Connector | Required opts | Notes |
|---|---|---|
| `createConfluenceConnector` | `token` (API token), `user` (email), `baseUrl` (e.g. `https://acme.atlassian.net/wiki`) | Optional `spaceId` to scope to a single space; paginates `/api/v2/pages` |
| `createNotionConnector` | `token` (integration token) | Optional `notionVersion` (default `2022-06-28`); uses `/v1/search` to page through accessible pages |

### Vector stores

```ts
// SQLite (plain better-sqlite3)
createSqliteVectorStore(opts: SqliteVectorStoreOptions)
adaptBetterSqlite(db)

// sqlite-vec SIMD-accelerated ANN
createSqliteVecVectorStore(opts: SqliteVecVectorStoreOptions)
adaptBetterSqliteVec(db)

// Factory (picks store from config)
createVectorStoreFromConfig(deps: CreateVectorStoreDeps)
openBetterSqlite(path): SqliteDatabaseLike
openBetterSqliteVec(path): SqliteVecDatabaseLike

// Migrations
migrateMemorySnapshotToSqlite(opts: MigrateOptions): Promise<MigrateResult>
migrateSqliteVssToVec(opts: MigrateVssOptions): Promise<MigrateVssResult>
```

### Rerankers

```ts
createVoyageReranker(opts: VoyageRerankerOptions)
createJinaReranker(opts: JinaRerankerOptions)
createIdentityReranker()   // pass-through (no reranking)
```

## Optional peer dependencies

| Peer | Used by |
|------|---------|
| `better-sqlite3 >=11 <13` | SQLite vector stores |
| `sqlite-vec ^0.1.9` | sqlite-vec vector store |
| `pg ^8` | `postgresLoader`, `os-rag-pgvector` bridge |
| `mysql2 ^3` | `mysqlLoader` |
| `html-to-text ^9` | `httpCrawlLoader`, `urlLoader` |
| `robots-parser ^3` | `httpCrawlLoader` |
| `@aws-sdk/client-s3 ^3` | `s3Loader`, `createS3Connector` |

## Per-embedder config

All embedder factories require an `apiKey` field (no env-var auto-read — pass
`process.env.OPENAI_API_KEY` etc. explicitly at the call site). Defaults:

| Embedder | Required key field | Default model | Output dimensions | Batch cap |
|---|---|---|---|---|
| `createOpenAIEmbedder` | `apiKey` | `text-embedding-3-small` | 1536 | unlimited (single request) |
| `createVoyageEmbedder` | `apiKey` | `voyage-3` | 1024 | 128 |
| `createCohereEmbedder` | `apiKey` | `embed-multilingual-v3.0` | 1024 | 96 |
| `createGeminiEmbedder` | `apiKey` | `text-embedding-004` | 768 | 32 (client-side; upstream ≤100) |

All four accept optional `model`, `baseUrl`, and `fetchImpl` fields. OpenAI
also exposes `dimensions`, `timeoutMs` (default 30 s), and `maxAttempts`
(default 2).

## `httpCrawlLoader` options

Options are passed via the `KnowledgeSourceEntry.auth` object (typed as
`HttpCrawlAuth`):

| Field | Type | Default | Description |
|---|---|---|---|
| `maxDepth` | `number` | `2` | 1 = seed page only; 2 = seed + its links |
| `maxPages` | `number` | `50` | Hard cap on distinct pages fetched |
| `crossOrigin` | `boolean` | `false` | Follow links to other origins |
| `honorRobots` | `boolean` | `true` | Fetch and respect the seed host's `/robots.txt` |

Rate limiting and retry belong to the caller via `opts.fetchImpl`; wrap it with
`createLoaderResilience` (see below).

## `createLoaderResilience` config

```ts
const net = createLoaderResilience({
  rateLimit: { tokensPerInterval: 10, intervalMs: 1000 },
  retry: { maxAttempts: 4 },
})
// Pass net.fetch as opts.fetchImpl to any HTTP-backed loader
```

`LoaderResilienceOptions`:

- `rateLimit` — token-bucket options forwarded to `createRateLimiter` from
  `@agentskit/os-rag`; omit to disable throttling.
- `retry.maxAttempts` — total attempts including the first (default 3).
  Retry policy (backoff, `Retry-After` handling) comes from `retryWithBackoff`
  in `@agentskit/os-core`.
- `fetchImpl` — base fetch implementation (defaults to `globalThis.fetch`).

## Migration runbook

Three-step upgrade path (ADR-0033):

1. **Memory → SQLite** (`migrateMemorySnapshotToSqlite`): point it at the
   legacy `createMemoryVectorStore` JSON export (v1 snapshot with `{ version:
   1, rows: [...] }`). Idempotent — upserts are keyed by `chunkId`.
2. **SQLite → sqlite-vec** (`migrateSqliteVssToVec`): reads the phase-A
   `rag_vectors` table (Float32 BLOB per row), rehydrates to `number[]`, and
   re-upserts into a `sqlite-vec` store so the `vec0` ANN index is rebuilt.
   The source table name defaults to `rag_vectors`; override via
   `opts.sourceTable`.
3. Both functions accept `opts.onLog` for a structured log sink; pass
   `createLogger(tag).info` (never `console.log`).

Old snapshot files are left on disk after migration — delete them on the next
clean rebuild.

## Knowledge connector incremental sync

Each connector (`createOneDriveConnector`, `createS3Connector`,
`createGcsConnector`, `createDropboxConnector`, `createDriveConnector`) wraps
the corresponding loader and implements the `KnowledgeConnector` port from
`@agentskit/os-rag`. The cursor helpers (`saveCursor`, `loadCursor`) live in
`os-rag` and are used by the runtime to checkpoint incremental scans — the
adapter itself only receives and emits the opaque cursor string via
`DigestRequest` / `DigestResult`.

## Common questions

> **Which embedder should I use and what API key do I need?**
> Choose based on provider: OpenAI (`apiKey` = your `OPENAI_API_KEY`,
> `text-embedding-3-small`, 1536 dims), Voyage (`VOYAGE_API_KEY`,
> `voyage-3`, 1024 dims), Cohere (`CO_API_KEY`, `embed-multilingual-v3.0`,
> 1024 dims), or Gemini (`GEMINI_API_KEY`, `text-embedding-004`, 768 dims).
> No adapter reads env vars automatically — pass the key explicitly:
> `createOpenAIEmbedder({ apiKey: process.env.OPENAI_API_KEY! })`.

> **How do I wire a persistent vector store instead of the in-memory default?**
> Call `createVectorStoreFromConfig(deps)` which picks the right store from
> the runtime config. For manual wiring: `openBetterSqlite(path)` +
> `createSqliteVectorStore({ db })` for the plain store, or
> `openBetterSqliteVec(path)` + `createSqliteVecVectorStore({ db })` for
> SIMD-accelerated ANN (requires `sqlite-vec ^0.1.9`). The sqlite-vec store
> is preferred for production; the plain SQLite store is the safe fallback
> when the native extension is unavailable.

> **How do I load documents from a website with rate limiting?**
> Use `httpCrawlLoader` (kind `'crawl'`) together with `createLoaderResilience`.
> Set crawl bounds in the `KnowledgeSourceEntry.auth` object (`maxDepth`,
> `maxPages`, `honorRobots`), then wrap a rate-limited fetch and pass it as
> `opts.fetchImpl`:
> ```ts
> const net = createLoaderResilience({
>   rateLimit: { tokensPerInterval: 5, intervalMs: 1000 },
>   retry: { maxAttempts: 3 },
> })
> for await (const doc of httpCrawlLoader.load(source, { fetchImpl: net.fetch })) {
>   await indexer.index(doc)
> }
> ```

> **How do I upgrade from the legacy in-memory store to sqlite-vec?**
> Run `migrateMemorySnapshotToSqlite(snapshotPath, sqliteStore)` first to
> land rows into a plain SQLite store, then `migrateSqliteVssToVec(sqliteDb,
> sqliteVecStore)` to rebuild the ANN index. Both calls are idempotent (upsert
> by `chunkId`). Wire `opts.onLog` to `createLogger(tag).info` for structured
> migration events (`AK_RAG_MIGRATION_OK` / `AK_RAG_VEC_MIGRATION_OK`).

Source: /raw/for-agents/packages/os-rag-adapters.md

### for-agents/packages/os-rag-pgvector.md

# packages/os-rag-pgvector

## Purpose

pgvector `VectorStore` adapter implementing the `VectorStore` port from `@agentskit/os-rag`. Backed by Postgres + the `pgvector` extension with an HNSW ANN index for sub-millisecond cosine similarity at scale. Every query is scoped to a single `org_id` so data from different tenants cannot cross-contaminate — structural parity with `@agentskit/os-store-postgres` RLS.

Vendor-isolated: `pg` is a dependency of `@agentskit/os-store-postgres` only; this package accepts a structural `PoolLike` interface so callers construct a real `pg.Pool` and pass it via `adaptPgPool`. This mirrors the `adaptBetterSqlite` pattern in `os-rag`.

Stability: **internal** (L2 binding). Distribution: cloud/enterprise. Epic: ef-02 SU2.4 (#2974, parent #2939/#2936).

## Public exports

- `PgVectorStore` — `VectorStore` implementation. Constructor: `new PgVectorStore(opts: PgVectorStoreOptions)`.
  - `applySchema()` — creates the `rag_vectors_pg` table (or the custom `table` name) + HNSW index (`vector_cosine_ops`); idempotent.
  - `upsert(rows)` — inserts / updates chunk rows scoped to the instance `orgId`.
  - `query(vec, k, filter?)` — ANN cosine search returning up to `k` `QueryHit` rows for this org; optional flat-equality `filter` is pushed as `metadata->>'k' = $n` clauses.
  - `delete(filter)` — removes chunk rows matching the flat-equality `filter` map within the org. Empty filter is a no-op.
  - `size()` — returns the row count for this org.
- `PgVectorStoreOptionsSchema` — Zod schema for constructor options:

```ts
// from packages/os-rag-pgvector/src/pgvector-driver.ts
interface PgVectorStoreOptions {
  pool: PoolLike     // constructed via adaptPgPool(pg.Pool instance)
  orgId: string      // all queries scoped to this org
  dim: number        // embedding dimension (e.g. 1536 for text-embedding-3-small)
  table?: string     // default: 'rag_vectors_pg'
}
```

- `adaptPgPool(pool)` — wraps a `pg.Pool` to satisfy the `PoolLike` structural interface.
- `PoolLike`, `PoolClientLike` — structural pool types (no `pg` import needed).

## Wired stores

None — `PgVectorStore` is itself the persistence layer. Injected into the `os-rag` indexer at composition time (sidecar wiring or cloud service init).

## Methods implemented

Not a JSON-RPC surface. Consumed by the `os-rag` indexer/retriever, which backs `knowledge.*` and `rag.search` RPCs.

## Methods consumed

- Postgres via injected `PoolLike` (`pg.Pool` wrapped by `adaptPgPool`).
- Requires: `CREATE EXTENSION IF NOT EXISTS vector` (pgvector ≥ 0.5.0 for HNSW; IVFFlat supported on older installs — see `src/schema.sql`).

## Common questions

> **How do I wire PgVectorStore in place of the SQLite vector store?**
> At sidecar/service composition time, pass a `PgVectorStore` instance as the `vectorStore` option to `createIndexer`. The `os-rag` core is store-agnostic.

> **Why do queries only see my org's data?**
> Every `query`, `upsert`, and `delete` adds a `WHERE org_id = $n` clause generated at query time. There is no cross-tenant fan-out path.

> **IVFFlat vs HNSW?**
> HNSW (default, pgvector ≥ 0.5.0) gives better recall and no training step. IVFFlat is documented in `src/schema.sql` as a fallback for older installations.

## Error codes

- `AK_RAG_STORAGE_DRIVER_MISSING` — thrown by `acquireClient` when `pool.connect()` fails (connection refused, pool exhausted, etc.).
- `AK_RAG_STORAGE_BACKEND_UNSUPPORTED` — thrown by the constructor when options fail Zod validation (empty `orgId`, non-positive `dim`, invalid `pool`).
- `AK_RAG_LOADER_FAILED` — thrown by `applySchema`, `upsert`, `query`, `delete`, and `size` when the SQL call itself fails after a successful pool checkout.

## Tests

- `packages/os-rag-pgvector/tests/pgvector-hermetic.test.ts` — hermetic unit tests using stub `PoolLike`; no real Postgres required.
- `packages/os-rag-pgvector/tests/pgvector.test.ts` — contract tests; live-PG tests gated on `PG_TEST_URL`.

Source: /raw/for-agents/packages/os-rag-pgvector.md

### for-agents/packages/os-rag.md

# packages/os-rag

## Purpose

RAG primitives — document loaders, chunker, embedder, vector store,
indexer, reranker. Imported by `os-headless` to ground the copilot
in workspace knowledge.

## Public exports

> Concrete loaders, production embedders, sqlite vector stores, rerankers,
> and cloud connectors live in `@agentskit/os-rag-adapters` (ADR-0064 L2).
> This package exports only PORT contracts + dev/reference implementations.

- Chunkers: `createTextChunker` (+ `TextChunkerOptions`), `createMarkdownChunker`.
- Embedders: `createDummyEmbedder` (dev/tests only — sha256 deterministic).
- Vector stores: `createMemoryVectorStore` (+ `MemoryVectorStoreOptions`),
  `vectorNorm`, `cosineSimilarity` (shared vector math).
- Indexer: `createIndexer` (+ `IndexerOptions`), `createRagIndexer`
  (+ `RagIndexer`, `RagSource`, `IndexDeps`, `IndexReport`).
- ACL: `filterHitsByAcl`, `principalSatisfiesAcl` (+ `ChunkAcl`,
  `AclPrincipal`, `FilterAclOptions`).
- Digest pipeline: `computeChunkFingerprint`, `computeSnapshotRoot`,
  `buildSnapshotMerkle` (+ `SnapshotMerkle`), `buildKnowledgeSnapshot`,
  `KNOWLEDGE_SNAPSHOT_COMMITTED_EVENT`, `createDigestOrchestrator`
  (+ `DigestOrchestrator`, `DigestEvent`, `DigestResult`, `RedactionAdapter`,
  `RunDigestOptions`, `CreateDigestOrchestratorOptions`).
- Digest attestation: `proveChunkInclusion`, `verifyChunkInclusion`,
  `createSnapshotSigner` (+ `SnapshotSigner`, `CreateSnapshotSignerOptions`),
  `verifyKnowledgeSnapshot` (+ `VerifyKnowledgeSnapshotInput`).
- PII: `createPiiRedactionAdapter`, `profileIdForKnowledgePii`
  (+ `PiiRedactionAdapter`, `PiiRedactionResult`).
- Rate limiting: `createRateLimiter` (+ `RateLimiter`, `CreateRateLimiterOptions`).
- Connectors (port + helpers): `connectorSha256`, `connectorSnapshotFingerprint`,
  `encodeConnectorCursor`, `decodeConnectorCursor`, `runLoaderDigest`
  (+ `KnowledgeConnector`, `ConnectorKnowledgeDocument`,
  `ConnectorDigestRequest`, `ConnectorDigestResult`, `RunLoaderDigestParams`).
- Reranker (port only): `Reranker`, `RerankCandidate`, `RerankResult`
  (concrete adapters — Voyage, Jina, identity — live in `@agentskit/os-rag-adapters`).
- Types: `Document`, `Chunk`, `Chunker`, `Embedder`, `VectorStore`,
  `VectorRow`, `Indexer`, `IndexerStatus`, `IndexerStatusRow`, `Loader`,
  `LoaderOptions`, `SourceKind`, `QueryHit`, `KnowledgeSourceEntry`.

## Wired stores

None. Loaders/embedders are pluggable; persistence (KnowledgeStore)
lives in `os-storage`.

## Methods implemented / consumed

Library — wired by `os-headless`/`knowledge-handlers.ts`. Sidecar exposes:

- `knowledge.sources.{list,add,remove,rebuild,preview}` — CRUD + per-source
  relevance preview.
- `knowledge.status` — aggregate counters.
- `rag.search` — capability-gated on `rag:read`; optionally per-source
  `rag:read:<sourceId>` via `hasSourceCapability` (checked before fan-out;
  unscoped search denied when wired). Input
  `{ query: string; k?: number; sourceIds?: readonly string[] }`. Output
  `{ hits: [{ sourceId, chunkId, score, snippet?, metadata }] }`. Embeds the
  query with the default embedder, fans out per-source vector queries,
  merges, sorts desc by score, slices to `k` (default 5). Throws
  `AK_TOOL_NOT_FOUND` when no default embedder is configured.

## Default embedder selection

The sidecar (`packages/os-headless/src/bin/sidecar.ts`) picks the
`defaultEmbedder` exposed to `rag.search` / `knowledge.sources.preview`
using the following priority (first match wins):

| # | Source | Adapter | Env / hint |
|---|---|---|---|
| 1 | copilot-config `embedder` role, provider kind `openai` / `openrouter` / `azure-openai` | `createOpenAIEmbedder` | `OPENAI_API_KEY` (+ `provider.endpoint` as `baseUrl`) |
| 2 | copilot-config `embedder` role, provider kind `cohere` | `createCohereEmbedder` | `COHERE_API_KEY` |
| 3 | copilot-config `embedder` role, provider kind `gemini` | `createGeminiEmbedder` | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
| 4 | `OPENAI_API_KEY` env (legacy) | `createOpenAIEmbedder` | `text-embedding-3-small` |
| 5 | `VOYAGE_API_KEY` env | `createVoyageEmbedder` | `voyage-3` (Voyage has no copilot-config kind; env-only) |
| 6 | `COHERE_API_KEY` env | `createCohereEmbedder` | `embed-multilingual-v3.0` |
| 7 | `GOOGLE_API_KEY` / `GEMINI_API_KEY` env | `createGeminiEmbedder` | `text-embedding-004` |
| 8 | `AKOS_RAG_ALLOW_DUMMY=1` | `createDummyEmbedder` | test escape hatch |
| 9 | `NODE_ENV !== 'production'` | `createDummyEmbedder` | dev fallback with loud warn |
| 10 | production, nothing configured | _none_ | `defaultEmbedder` is undefined → `rag.search` throws `AK_TOOL_NOT_FOUND` |

**Anthropic exposes no embedding endpoint.** As of 2026 the Anthropic
API has no native `/embeddings` route — pair Anthropic chat with one of
the embedders above (OpenAI, Voyage, Cohere, Gemini). There is therefore
no `createAnthropicEmbedder` in `@agentskit/os-rag`.

## Common questions

> **How do I add a new loader?**
> Loaders live in `@agentskit/os-rag-adapters` (ADR-0064 L2), not here.
> Add a new `SourceKind` to `src/types.ts` in this package first so the
> type is part of the contract, then implement the `Loader` interface in
> os-rag-adapters. Network loaders MUST use `opts.fetchImpl ?? globalThis.fetch`
> (never bare `globalThis.fetch`) so the os-headless egress guard can inject.

> **How is loader egress secured? (SEC-1 / #1664)**
> `os-headless` knowledge handlers inject an `EgressPolicy`-backed
> guarded fetch as `LoaderOptions.fetchImpl` for every index/reindex
> job (`knowledge-parts/egress-fetch.ts`). The SSRF blocklist (cloud
> metadata `169.254.169.254`, `metadata.google.internal`, loopback) is
> always enforced — `checkEgress` evaluates the blocklist before mode,
> so it holds even when the workspace egress policy is unconfigured
> (mode coerced to `allow`) or explicitly `allow`. Deny decisions are
> bridged into the egress policy store's decisions ring. Workspaces
> that set `workspaceOverrideEnabled` get their `mode`/`allowlist`
> honored on top of the always-on blocklist.

> **How is reranker selected?**
> Env: `AKOS_RAG_RERANKER` ∈ {voyage, jina} + the matching API key
> (`VOYAGE_API_KEY` or `JINA_API_KEY`). Missing config → identity
> ordering (no reranker).

> **What's the chunker default?**
> `createTextChunker()` with 1000-token sliding window + 200-token
> overlap. Markdown-aware chunker uses heading boundaries.

## ACL model (RFC-0010 §6)

`Chunk`, `VectorRow`, and `QueryHit` all carry an optional `acl?: ChunkAcl`:

```ts
interface ChunkAcl {
  readonly users?: readonly string[]    // explicit user-id allowlist
  readonly groups?: readonly string[]   // any group overlap admits
  readonly capability?: string          // single capability gate
}
```

The source connector populates `acl` from upstream metadata (Slack channel
membership, Notion page permissions, etc.). The vector store persists it
verbatim. At query time, the host calls `filterHitsByAcl(hits, principal)`
— or passes a `principal` to `createRagSearchTool` — to drop hits the
caller is not authorized to see.

Admission rule (any of):

- `principal.userId` is listed in `acl.users`
- `principal.groups` overlaps `acl.groups`
- `principal.capabilities` contains `acl.capability`

**Closed by default.** A hit with an ACL and no matching rule is dropped.
Pass `{ permissive: true }` to flip to soft-fail (only useful during
legacy migrations).

A hit with **no** `acl` is treated as "no source-side ACL" and falls
through to the source's `gating.requiredCap` (the per-source cap on
`KnowledgeSourceConfig`). Workspaces that hold cross-tenant data in a
single source should always populate `acl`.

## Capabilities

- `rag:read` — required to call `rag.search` (enforced in
  `createRagSearchTool` via `hasCapability`).
- `rag:write` — reserved for connectors that mutate the index. Today no
  caller declares it; the future digest scheduler (`os-import`) will
  request it before invoking `vectorStore.upsert`.

## Digest pipeline (RFC-0010 §2)

`createDigestOrchestrator({ chunker, embedder, vectorStore, redactor?, knownFingerprints? })`
turns a document producer into a `KnowledgeSnapshotPayload`. Pipeline
order: list → fetch → optional redact → chunk → fingerprint → dedup → embed
→ upsert → snapshot. The orchestrator emits a typed event stream
(`digest:started`, `digest:chunk-skipped`, `digest:chunk-embedded`,
`digest:redacted`, `digest:failed`, `knowledge.snapshot.committed`).

Fingerprints are a `sha256(text || \0 || stable-json(metadata))`. The
snapshot root is `sha256` over the sorted leaves (full Merkle inclusion
proofs are tracked in `docs/RAG-COMPLETION-PLAN.md` §1).

## Production sidecar wiring (RAG prod-ready Gap1–3)

`knowledge.sources.rebuild` runs through `createIndexer` (job/transition
model), not the orchestrator. The headless sidecar wires the production
guarantees onto that path via env. See `docs/RAG-HEAVY-INFRA-PLAN.md` §H7.

| Env var | Default (prod / dev) | Effect |
|---|---|---|
| `AKOS_RAG_STORAGE_BACKEND` | `sqlite-vss` / `memory` | Vector store backend. `memory`, `sqlite-vss` (ADR-0033 phase A), or `sqlite-vec` (treated as `sqlite-vss` until phase B). |
| `AKOS_RAG_STORAGE_PATH` | `<dataDir>/rag-vectors.db` | sqlite db path. A legacy `<dataDir>/rag-vectors.json` snapshot migrates in once (idempotent). |
| `AKOS_RAG_PII_PROFILE` | `standard` / `none` | Indexer redactor (`none\|standard\|hipaa\|pci\|strict`). Enforced **before** chunk + embed; per-source hits audit-logged with log tag `AK_RAG_REDACTION_AUDIT` (os-headless log, not an error code). |
| `AKOS_RAG_DIGEST_SCHEDULE` | `manual` | Global cron for knowledge re-sync (`manual`, duration `30s/15m/2h/1d` opt-`@every`, or `*/<n> * * * *`). Source add/remove/rebuild reloads the set. |

Degrade: a missing `better-sqlite3` binding (or any sqlite open failure)
falls back to the in-memory store and emits a `runtime.degraded`
notification — the sidecar still boots. Per-source schedules (vs. the one
global `AKOS_RAG_DIGEST_SCHEDULE`) await a `KnowledgeSourceRow.schedule`
storage column — the only deferred slice of H7.

> **Common question — "why doesn't the rebuild path emit signed
> snapshots / Merkle proofs?"** Those live on `createDigestOrchestrator`
> (`runDigest`), which has a different lifecycle than the indexer the
> `knowledge.*` handlers depend on. Gap1–3 closed the prod *blockers*
> (persistence, PII-before-embed, re-sync); full orchestrator adoption on
> the rebuild path is tracked future work, not a regression.

Source: /raw/for-agents/packages/os-rag.md

### for-agents/packages/os-runtime-agentskit.md

# packages/os-runtime-agentskit

## Purpose

Concrete adapter registry that implements the contracts in `os-runtime`. Wires `@agentskit/adapters` upstream (grok, deepseek, replicate, bedrock, azure-openai, openai, anthropic, gemini, mistral, …), plus first-party voice (Deepgram STT, ElevenLabs TTS), memory backends (in-memory, file, sqlite), and the built-in tool catalog (Slack, GitHub, Linear, Notion).

## Public exports

- `createAgentskitRegistry(opts)` — full `AdapterRegistry` keyed by provider id.
- LLM adapter: `createAgentskitLlmAdapter`, types `AgentskitChatAdapter`, `AgentskitChatRequest`, `AgentskitChatResponse`, `AgentskitMessage`, `AgentskitUsage`, `AgentskitLlmAdapterOptions`.
- Tool executor: `createAgentskitToolExecutor`, `createAgentskitToolExecutorFromDefinitions`.
- Memory adapter: `createAgentskitMemoryAdapter`, `wrapAgentskitChatMemory`, `createMemoryAdapterFromChatMemory`.
- Memory factory: `createMemoryFromConfig`, `createMemoryFromConfigAuto`, `createInMemoryStore`, `createFileStore`, `createSqliteStore`, `MEMORY_BACKEND_SUPPORT`, `isMemoryBackendSupported`, `tryDefaultSqliteOpener`, `MemoryBackendNotImplementedError`.
- Provider catalog: `ProviderCatalogEntry`, `ProviderCapability`.
- Upstream binding: `createUpstreamChatAdapter`.
- Runner: `createAgentskitAgentHandler`, `createAgentskitRuntime`.
- Adapter registry: `createAdapterRegistryFromCreds`, `createAdapterRegistryFromCredsViaUpstream`, `ProviderNotConfiguredError`, `ProviderNotImplementedError`.
- Voice: `createDeepgramSttAdapter`, `createElevenLabsTtsAdapter`, `createWhisperSttAdapter`, `createOpenAiTtsAdapter`.
- Built-in tools: `createSlackTools`, `createGithubTools`, `createLinearTools`, `createNotionTools`, `createDiscordTools`, `createTwilioTools`, `createSentryTools`, `createStripeTools`, `createElevenLabsTools`, `createHttpTools`, `createWebSearchTool`, `createGitDiffTool`, `createFsTools`, `createLlmCompleteTool`, `createMemoryTools`, `createShellExecTool`, `createCodingTools`, `createWebScrapeTool`, `createJsonExtractTool`, `createMongoTools`, `createSqlQueryTool`, `createPdfGeneratorTool`, `createFileReaderTools`.

## Wired stores

- File-backed memory (`createFileStore`) under workspace data dir.
- SQLite memory (`createSqliteStore`) via injected `SqliteOpener` (Tauri / better-sqlite3).
- In-memory store for tests / ephemeral runs.

## Methods implemented

The registry is consumed by `os-runtime.buildLiveHandlers`; it is not a JSON-RPC surface itself. Indirect surfaces:

- `createAgentskitAgentHandler` / `createAgentskitRuntime` — run an upstream ReAct loop through the registered `LlmAdapter`.
- `connections.verify` — uses the catalog to validate creds.

## Methods consumed

- Upstream `@agentskit/adapters` SDKs per provider.
- `connections.*` (downstream) — credential lookup before adapter invoke.
- `cost.record` (downstream) — usage emission via `meteredLlmAdapter` in `os-runtime`.

## Common questions

> **Why a separate package from `os-runtime`?**
> `os-runtime` is contracts-only and stays small. This package can pull heavy provider SDKs without bloating the contract layer (ADR-0013 size budgets).

> **Memory backend isn't supported on my platform — what happens?**
> `isMemoryBackendSupported(id)` returns `false`; `createMemoryFromConfigAuto` falls back to in-memory + a `MemoryBackendNotImplementedError` surfaced as a soft warning.

> **How is a new provider added?**
> Append an entry to `providers.ts` (`ProviderCatalogEntry`). Then add one file `src/adapters/providers/<id>.ts` exporting a `ProviderFactoryEntry` (`defaultModel` + `buildFactory`) that delegates to the upstream `@agentskit/adapters` factory — never reimplement provider HTTP (ADR-0002). Register it in the `PROVIDER_FACTORIES` map in `src/adapters/providers/index.ts`; the registry composer (`registry-upstream.ts`) picks it up automatically. Add a test under `tests/`. See ADR-0069 for the per-provider file layout.

> **How does `web.search` pick a provider? (Route-correction A2, #3485)**
> `tools/web-search.ts:createWebSearchTool` selects an adapter per call from the env keys it is handed: **Tavily** (`TAVILY_API_KEY`) → **Brave** (`BRAVE_API_KEY`) → **DuckDuckGo** Instant-Answer (key-free fallback). Every adapter normalises to `{ title, url, snippet }` and runs on the sidecar's egress-guarded `fetch`; a network or non-2xx failure surfaces as `ToolResult` `{ kind: 'error', code: 'WEB_SEARCH_FAILED' }`. The sidecar wires it in `bin/sidecar-parts/runner-tools.ts:buildFlowTools`, so the `web.search` catalog entry always has a real executor (`tools.list` stays honest). Tests at `tests/tools/web-search.test.ts`.

> **Where are the self-describing artifacts? (Route-correction A4, #3485)**
> The repo root ships `capabilities.json` (every JSON-RPC verb with side-effect
> tier, stability, required RBAC caps, description + a sha256 `contentHash`) and
> `llms.txt` (a flat text index for LLM context), both generated from the live
> `@agentskit/os-contracts` REGISTRY by `scripts/gen-self-describe.mjs`
> (`pnpm gen:self-describe`). Generation is deterministic (sorted, no
> wall-clock), and `pnpm check:self-describe` (wired into `check:all` after the
> build) fails if the committed files drift from the registry — so a clone
> always carries an up-to-date map. Cryptographic *signing* (the manifesto's
> "signed") is a tracked follow-up; the content hash is the honest first step.

> **How does `git.diff` run safely? (Route-correction A2, #3485)**
> `tools/git-diff.ts:createGitDiffTool` runs `git diff --no-color` through the **same `SandboxRuntime.exec` seam as `shell.exec`** (`process`/`container`, never the host), so it is confined to the sandbox workspace. Refs and pathspecs are validated to forbid a leading `-`, and args are passed as an array (no shell), so a crafted value can't smuggle a `git` flag; `head` without `base` is rejected. `sideEffect: 'read'`. Wired in `buildFlowTools` next to `shell.exec`. Unblocks the Coding hero (review the change before opening a PR). Tests at `tests/tools/git-diff.test.ts`.

Source: /raw/for-agents/packages/os-runtime-agentskit.md

### for-agents/packages/os-runtime.md

# packages/os-runtime

## Purpose

Provider-agnostic LLM runtime contracts + flow-node handlers + run-state machine + cost metering. Wires concrete adapters (which live in `os-runtime-agentskit`) to flow execution. Owns the `RunState` finite-state machine used by every run.

## Public exports

- Adapter contracts: `LlmAdapter`, `LlmCall`, `LlmResult`, `ToolExecutor`, `ToolCall`, `ToolResult`, `ToolDeclaration`, `ToolApprovalRequest`, `ToolApprovalDecision`, `MemoryAdapter`, `HumanReviewer`, `AdapterRegistry`, `NotifySendFn`, `NotifyDispatch`.
- Handler factories: `createAgentHandler`, `createToolHandler`, `createHumanHandler`, `createConditionHandler`, `createParallelHandler`, `createLlmBranchHandler`, `createClarityHandler`, `createNotifyHandler`, `createRagHandler`, `createLoopHandler`.
- Live wiring: `buildLiveHandlers(opts)` returns the full handler map for the flow walker.
- Run state machine: `RunnerStateMachine`, `createRunnerStateMachine`, `InvalidTransitionError`, `UnknownRunError`, `DuplicateRegisterError`, types `RunState`, `StateTransition`, `RunStateRecord`, `RunStateStore`, `PauseGate`.
- Persistence: `SQLiteRunStateStore` (default backing store).
- Cost metering: `CostTracker`, `meteredLlmAdapter`, `summarizeRun`, `BudgetBlockedError`, types `BudgetBlock`, `CostEntry`, `RunCost`.
- Sandbox guard: `withSandboxGuard` + `SandboxGuardOpts`.
- Memory factory: `createMemoryFromConfig`, `createMemoryFromConfigAuto`, `createInMemoryStore`, `createFileStore`, `createSqliteStore`, `createLocalStorageStore`, `createRedisStore`, `createVectorStore`, `adaptIoredis`, `tryDefaultRedisClient`, `tryDefaultSqliteOpener`, `isMemoryBackendSupported`, `MEMORY_BACKEND_SUPPORT`, types `AgentskitMemoryStore`, `RedisLike`, `MemoryVectorStoreLike`, `MemoryEmbedderLike`.
- Egress context: `agentEgressContext`, `withAgentEgress`, `currentAgentEgress`.
- Agent extras: `AgentMemoryPort`, `AgentMemoryMessage`, `ResolvedSkill`, `GuardToolCall`, `BudgetCheck`.
- Misc: `safeBooleanEval` (used by `createConditionHandler`), `ConditionEvaluator`.

## Wired stores

- `SQLiteRunStateStore` — durable run-state across restarts.
- In-process `CostTracker` keyed by `runId` (flushed to audit on completion).

## Methods implemented

The handlers are mounted by `os-headless` flow walker. Surface methods routed through it:

- `runs.list`, `runs.get`, `runs.cancel`.
- `runner.runFlow`, `runner.runAgent`, `runner.getState`, `runner.pause`, `runner.resume`, `runner.cancelRun`.
- `cost.summary`, `cost.breakdown`, `cost.list`.

## Methods consumed

- `LlmAdapter.invoke` — provider call (concrete adapters from `os-runtime-agentskit`).
- `ToolExecutor.invoke` — tool dispatch (plugin-supplied or built-in).
- `MemoryAdapter.{read,write}` — conversation memory.
- `HumanReviewer.request` — HITL gate; consumed via `inbox.request`.
- `os-core.decideSandbox` — sandbox-level gate before tool exec.
- `os-core.resolveFlowSandbox` — per-flow/agent/node sandbox gate run inside
  the agent handler before the LLM call (#1133 SU2). `AgentHandlerExtras` /
  `LiveHandlerOptions` carry `flowSandboxLevel?` + `sandboxHas?`; a rejected
  decision → `sandbox.rejected`, a required-but-unregistered level →
  `sandbox.unavailable`. #1133 SU3 adds a structural `onSandboxDenied?`
  callback (`{ agentId, level, reason, cause: 'policy' | 'unavailable' }`)
  on both — the host bridges it into the persistent sandbox-denial ring
  with no `os-runtime → os-storage` dependency.

## Agent tool-calling (RFC-0026)

The agent handler runs an **agentic tool-calling loop**. When
`AgentHandlerExtras.toolExecutor` is wired, the agent's declared `tools[]`
(intersected with the executor's LLM-callable tools — those that carry a
`parameters` JSON Schema, via `ToolExecutor.describe`) are offered to the
model. Each round: `invoke` → on `finishReason: 'tool_calls'` execute each
`result.toolCalls[]` via the executor, append the results as `tool`
messages, re-invoke. Capped by `maxToolIterations` (default 8). An agent
with no `tools[]`, or a host with no `toolExecutor`, runs as a plain
text→text LLM call (pre-RFC-0026 behavior).

Tool gating is by `agent.tools` — only declared tools are exposed.
`AgentHandlerExtras.guardToolCall` is a pre-execution hook: it can deny an
individual tool call (fed back to the model as a `tool` error). The host
wires `createMcpScopingGuard` (`@agentskit/os-headless`) so an `mcp.invoke`
call is restricted to the agent's effective `mcpRefs` (workflow-scoped —
RFC-0024); an empty `mcpRefs` is unrestricted.

**Skills.** `agent.skills[]` slugs resolve (via `resolveSkill`, default
`getBuiltinSkill`) to a behavior payload: a `systemPromptFragment` appended
to the agent's system message, and `toolGrants` merged into the declared
tool set. An unknown slug is ignored.

**Memory.** When `AgentHandlerExtras.memory` (an `AgentMemoryPort`) is wired
and the agent has a `memory.ref`, prior conversation messages are loaded and
prepended (after system/RAG, before the current user message), capped by
`memory.maxMessages` (default 20). After a successful run the user +
assistant turn is appended. The conversation key is the `memory.ref`. An
agent with no `memory` ref is stateless. Backed by
`AgentConversationStore` (`@agentskit/os-storage`).

**Egress.** Workspace egress policy is enforced on every tool / connector /
RAG `fetch` (`buildEgressGuardedFetch`). The per-agent `agent.egress`
override is also enforced (RFC-0026 FU-2): the agent handler runs each tool
inside an `agentEgressContext` (`AsyncLocalStorage`) carrying `agent.egress`;
the guarded fetch's `resolveOverride` reads it per request and resolves the
agent override over the workspace policy. Concurrent runs are isolated.

**Model fallback.** `createAgentHandler` walks the candidate list
`[primary, ...model.fallbackChain]`: a candidate whose circuit breaker is
open is skipped, and a hard invocation failure falls through to the next
candidate. The agentic loop restarts from a fresh message copy per
candidate. All candidates exhausted → `agent.llm_failed`; all circuits open
→ `agent.circuit_open`.

**Advanced metadata.** `capabilities`, `riskTier`, `lifecycleState`, `role`,
`evalSuiteIds`, `entrypoint` are **not** LLM-execution inputs — they belong
to the RBAC, lifecycle, eval, and external-agent subsystems respectively.
They are not consumed by `createAgentHandler`.

## Common questions

> **Where is a new node-kind handler registered?**
> Add `create<Kind>Handler` in `src/handlers/`, append to `buildLiveHandlers`. The walker dispatches by `node.type`.

> **What states can a run be in?**
> `idle | queued | running | paused | cancelled | completed | failed`. Illegal transitions throw `InvalidTransitionError` — never silently no-op.

> **How is a budget cap enforced?**
> `meteredLlmAdapter` wraps the raw `LlmAdapter`; on each call it checks `CostTracker` against the configured budget and throws `BudgetBlockedError` if exceeded. The walker catches and surfaces a HITL.

Source: /raw/for-agents/packages/os-runtime.md

### for-agents/packages/os-sandbox-vercel.md

# packages/os-sandbox-vercel

## Purpose

Vercel-optimised sandbox layer for the `HostedSandboxProvider` port from `@agentskit/os-core`. Provides four capabilities over the base `os-sandbox` package: (1) a `VercelSandboxRuntime` that spawns Firecracker µVMs via `@vercel/sandbox`; (2) a `caps-resolver` that maps plan slugs to resource ceilings; (3) a `caps-enforcer` decorator that wraps any `HostedSandboxProvider` with post-run breach detection; and (4) a `WarmPool` that pre-warms sandbox instances per plan tier to achieve cold-start < 2 s P95.

Anti-duplication note: `os-sandbox` owns runtime isolation (bwrap/docker/process); this package owns Vercel-specific metering and warm-pool management only. LLM token costs live in `os-core` `CostMeter`; this package tracks CPU-minutes + RAM-minutes (compute, not tokens) plus provider-reported egress bytes when available.

Stability: **internal** (L2 binding). Distribution: cloud/enterprise. Epic: ef-03 SU3.1–3.5 (#2978–#2982/#3016, parent #2940/#2936).

## Public exports

### Plan-feature gate (ef-07 SU7.5 / #3016)

- `assertDedicatedSandboxCap(caps: SandboxPlanCaps)` — throws `AgentsKitError(AK_PLAN_CAP_EXCEEDED)` when `caps.dedicatedSandbox` is false. Call before `spawn()`.
- `SandboxPlanCaps` — minimal structural type: `{ dedicatedSandbox: boolean }`.

### Run metering (ef-03 SU3.5)

- `createRunMeter(opts)` / `RunMeter`, `MeterRecord` — per-run CPU/RAM sample accumulator; `RunMeter.egressBytes` is optional and provider-reported.
- `toMonthKey(isoTs)` — derives `yyyymm` (e.g. `202601`) key for monthly quota tracking.
- `meterRecordToRunMeter(row)` — deserialises a `MeterRecord` DB row.
- Types: `RunMeterType`, `MeterRecordType`, `ResourceSample`, `SampleFn`, `MeterCaps`, `CreateRunMeterOpts`, `MeterRecordEvent`, `MeterLimitEvent`, `RunMeterHandle`.

### Warm pool (ef-03 SU3.4)

- `createWarmPool(deps: WarmPoolDeps)` → `WarmPool` — pre-warms instances and provides `acquire() / release()`.
- `PoolConfig`, `PlanPoolSettings`, `PLAN_POOL_DEFAULTS`, `buildDefaultPoolConfig` — configuration types.
- Events: `PoolAcquireEvent`, `PoolReleaseEvent`, `PoolWarmEvent`, `PoolMissEvent`.

### Caps resolver (ef-03 SU3.2)

The `caps-resolver.ts` (not re-exported from index) is consumed by `caps-enforcer.ts`:
```ts
// from packages/os-sandbox-vercel/src/caps-resolver.ts
type Plan = 'free' | 'pro' | 'enterprise'
const PLAN_DEFAULT_CAPS: Record<Plan, CapMatrix>
// free:  cpuMs=5_000, memMb=256, wallMs=30_000, runsPerMonth=1_000
// pro:   cpuMs=60_000, memMb=1_024, wallMs=300_000, runsPerMonth=100_000
// enterprise: cpuMs=600_000, memMb=4_096, wallMs=1_800_000, runsPerMonth=MAX
```

### Caps enforcer (ef-03 SU3.2)

- `CapBreachError extends AdapterError` — structured quota exceeded error; `breaches: BreachAxis[]` lists every axis that exceeded its limit.
- `BreachAxis` — `'cpu' | 'mem' | 'wall' | 'runs'`.
- Error code: `AK_SANDBOX_QUOTA_EXCEEDED`.

## Wired stores

None in this package. `MeterRecord` rows are written to `apps/cloud` (metering-routes ef-03).

## Methods implemented

Not a JSON-RPC surface. `VercelSandboxRuntime` and the caps-enforcer wrapper are consumed by the cloud server's sandbox provisioning path.

## Methods consumed

- `@vercel/sandbox` — ONLY imported in `vercel-runtime.ts` (vendor-isolation gate).
- `@agentskit/os-license` `resolvePlanCaps` — called at spawn time to gate `dedicatedSandbox`.
- `@agentskit/os-egress-guard` — egress policy evaluated for each outbound call from the µVM.

## Common questions

> **When should I call `assertDedicatedSandboxCap` vs `assertCap` from os-license?**
> Use `assertDedicatedSandboxCap` at the sandbox provisioning boundary (before `spawn()`). It accepts a minimal structural type so the sandbox layer does not take a hard dependency on `os-license`. Use `assertCap` from `os-license` for all other feature-flag gates.

> **How does the warm pool reduce cold-start latency?**
> `createWarmPool` pre-creates `PlanPoolSettings.minIdle` instances per plan tier on a background interval. `acquire()` returns a pre-warmed instance if available; on a pool miss it falls back to a fresh `spawn()` and emits `PoolMissEvent`.

> **How is metering connected to billing?**
> `RunMeter` accumulates `ResourceSample` records and emits `MeterLimitEvent` when any axis breaches its cap. The cloud server (`apps/cloud metering-routes.ts` ef-03) ingests `MeterRecord` rows for operational aggregation and writes optional `egressBytes` into commercial `usage_events`.

## Error codes

- `AK_SANDBOX_QUOTA_EXCEEDED` — cap breach detected by `CapBreachError`; `breaches: BreachAxis[]` lists each exceeded axis.
- `AK_PLAN_CAP_EXCEEDED` — `dedicatedSandbox` feature flag is false for the tenant's plan; thrown by `assertDedicatedSandboxCap`.
- `AK_SANDBOX_SPAWN_FAILED` — `VercelSandboxRuntime.spawn()` or `run()` failed for an unknown/destroyed handle.
- `AK_SANDBOX_EGRESS_DENIED` — Vercel network policy blocked an outbound call during `spawn()` or `run()`.
- `AK_SANDBOX_POOL_PROVISION_FAILED` — background refill failed to pre-warm a sandbox; the pool will retry with exponential backoff.
- `AK_SANDBOX_POOL_EXHAUSTED` — pool miss and on-demand provision failed; caller should retry.
- `AK_SANDBOX_POOL_INSTANCE_POISONED` — a released instance was marked poisoned and destroyed rather than returned to the pool.
- `AK_SANDBOX_RUN_METER_ALREADY_CLOSED` — `RunMeterHandle.close()` called a second time on an already-closed meter.

## Tests

`packages/os-sandbox-vercel/tests/`: `caps-enforcer.test.ts`, `caps-resolver.test.ts`, `meter.test.ts`, `vercel-runtime.test.ts`, `warm-pool.test.ts`.

Source: /raw/for-agents/packages/os-sandbox-vercel.md

### for-agents/packages/os-sandbox.md

# packages/os-sandbox

## Purpose

Sandbox runtime library providing isolation levels from `none` (no
restriction) through `process` (env-scoped subprocess), `sandbox-exec`
(macOS), `bwrap` (Linux), and `docker` (container). An egress enforcer
wraps `fetch` to enforce network allow-lists. The invariant is that the
chosen isolation level is asserted before any agent subprocess is launched:
`assertStrongIsolation` throws `WeakSandboxError` if the level is `none`
or `process` when strong isolation is required.

## Public exports

- Runtimes: `noneSandbox`, `processSandbox`, `exposeAllowedEnvKeys`, `ProcessRuntimeOptions`
- Registry: `SandboxRegistry`
- Spawner: `nodeSpawner`, `ChildHandle`, `Spawner`, `SpawnerExecOptions`, `SpawnerExecResult`
- Egress: `PolicyEgressEnforcer`, `createFetchGuard`, `hasFetchCapability`,
  `EgressEnforcer`, `EgressDecisionEvent`, `CreateFetchGuardOptions`
- Strictness: `WeakSandboxError`, `assertStrongIsolation`, `isStrongIsolation`,
  `isWeakIsolation`, `weakSandboxBanner`
- sandbox-exec (macOS): `renderSandboxExecProfile`, `sandboxExecRuntime`,
  `SandboxExecPolicy`, `SandboxExecRuntimeOpts`
- bwrap (Linux): `renderBwrapArgs`, `bwrapRuntime`, `isBwrapSupported`,
  `getBwrapPath`, `BwrapPolicy`, `BwrapRuntimeOpts`
- Docker: `renderDockerArgs`, `dockerRuntime`, `DockerPolicy`, `DockerRuntimeOpts`
- Kernel egress: `createKernelEgressEmitter`, `applyKernelEgress`, `revertKernelEgress`,
  `parseEgressGrant`, `renderIptablesRules`, `renderPfRules`,
  `ApplyKernelEgressOptions`, `ApplyKernelEgressResult`, `RevertKernelEgressOptions`,
  `IptablesRendererOpts`, `KernelEgressCommand`, `KernelEgressEmitter`,
  `KernelEgressPlatform`, `KernelEgressRunner`, `KernelEgressRunResult`,
  `ParsedGrant`, `PfRendererOpts`
- Constants: `PACKAGE_NAME`, `PACKAGE_VERSION`

## Wired stores

None. Sandbox policy (allow-lists, level) is loaded from `os-storage`
(`SandboxPolicyStore`) by `os-headless/src/sandbox-policy-handlers.ts`.
The runtimes themselves hold no state.

## Methods implemented / consumed

Implemented (via `os-headless/src/sandbox-policy-handlers.ts`, owner
`@agentskit/os-headless` in `os-contracts/src/methods/sandbox.ts`):

- `sandbox.state` — active sandbox count + current policy snapshot
- `sandbox.policy.get` / `.set` — read/write the workspace sandbox policy
- `sandbox.denials.list` — list recent egress denial events
- `sandbox.flow.preview` — dry-run a flow against the active sandbox policy

Consumed: `os-core` (`SandboxLevel`, `decideSandbox`, `SandboxRuntime` interface).

## Common questions

> **How do I add a new sandbox runtime?**
> Implement the `SandboxRuntime` interface from `os-core/tools/sandbox.ts`,
> then register it in `SandboxRegistry` with `registry.register(runtime)` — the
> registry reads `runtime.level` automatically.
> See `docker-runtime.ts` for the pattern.

> **How does `createFetchGuard` enforce egress?**
> It wraps the global `fetch` function. Before each request it calls
> `PolicyEgressEnforcer.decide(url, opts)` (where `opts` carries the optional
> `pluginId` for per-plugin overrides). A deny verdict throws a `TypeError`
> shaped like a network failure and emits an `EgressDecisionEvent` so the
> denial appears in `sandbox.denials.list`.

> **When is `bwrap` vs `sandbox-exec` chosen?**
> `SandboxRegistry` checks `isBwrapSupported()` (Linux kernel + bwrap binary)
> first. On macOS it falls back to `sandboxExecRuntime`. The registry is
> consulted by `decideSandbox` in `os-core` based on the workspace-level
> `SandboxLevel` setting.

Source: /raw/for-agents/packages/os-sandbox.md

### for-agents/packages/os-sealer-vault.md

# packages/os-sealer-vault

## Purpose

HashiCorp Vault Transit secrets-engine binding for the AgentsKitOS key-ring custody seam. This is the only package in the monorepo that imports `node-vault` (vendor-isolated by `check:vendor-isolation`). Exposes the `AsyncKeyRingSealer` interface — an async superset of `os-security`'s synchronous `KeyRingSealer` port — because Vault Transit is inherently HTTP-based.

Stability: **internal** (L2 binding). Distribution: cloud/enterprise. Epic: ef-02 SU2.5 (#2975, parent #2939/#2936).

## Public exports

- `createVaultSealer(deps: VaultSealerDeps)` → `AsyncKeyRingSealer`.
- `AsyncKeyRingSealer` — async variant of the `KeyRingSealer` port:
  ```ts
  interface AsyncKeyRingSealer {
    seal(plaintextRingJson: string): Promise<string>
    unseal(wrappedRing: string): Promise<string>
    rotateKey(): Promise<{ newVersion: number }>
  }
  ```
- `VaultSealerDeps` — factory dependencies:
  ```ts
  interface VaultSealerDeps {
    // Pre-authenticated node-vault client. Caller handles auth
    // (token, AppRole, AWS IAM, etc.) before passing here.
    readonly client: ReturnType<typeof vault>
    // Name of the Vault transit key for encrypt/decrypt/rotate.
    readonly keyName: string
    // Optional base64-encoded encryption context. Vault requires
    // the same context value for decryption.
    readonly context?: string
  }
  ```

`seal` calls Vault `transit/encrypt/<keyName>` and returns the ciphertext. `unseal` calls `transit/decrypt/<keyName>` and returns the plaintext ring JSON. `rotateKey` calls `transit/keys/<keyName>/rotate` and returns the new key version.

## Wired stores

None. Stateless HTTP binding — Vault holds the key material.

## Methods implemented

Not a JSON-RPC surface. Injected into `os-security`'s key-ring initialization at cloud server startup.

## Methods consumed

- HashiCorp Vault Transit API (HTTPS) — `node-vault` client, vendor-isolated here.

## Common questions

> **How does this relate to `KeyRingSealer` in `os-security`?**
> `os-security` defines a *synchronous* `KeyRingSealer` port (boot path). Vault is async (HTTP). `AsyncKeyRingSealer` is the async superset: same `seal`/`unseal` contract but returning `Promise<string>`. Consumers at startup should `await` the async version; for the sync port, use the `createCommandKeyRingSealer` shim in `os-security` (shell round-trip via the Vault agent CLI).

> **Who is responsible for Vault authentication?**
> The caller. Construct and authenticate the `node-vault` client (token, AppRole, AWS IAM, etc.) before passing it as `deps.client`. This package never reads env vars directly.

> **How does key rotation work?**
> `rotateKey()` asks Vault to rotate the transit key. The new key version becomes the default encryption version; older versions continue to decrypt existing ciphertexts. The caller does not need to re-seal existing rings immediately.

## Error codes

All Vault SDK errors are mapped to existing `AK_VAULT_*` codes from `@agentskit/os-core`. No new error codes are introduced.

| Code | Thrown by | Trigger |
|---|---|---|
| `AK_VAULT_INIT_FAILED` | `createVaultSealer` (factory), `seal` | `keyName` is blank, transit/encrypt fails, or response is missing `ciphertext` |
| `AK_VAULT_INTEGRITY_FAILED` | `unseal` | transit/decrypt fails or response is missing `plaintext` (tampered data, wrong context, key version mismatch) |
| `AK_VAULT_KEY_INVALID` | `rotateKey` | transit/keys rotate fails or subsequent key-read is missing `latest_version` |

## Crypto contract

All cryptographic operations are delegated to Vault Transit over HTTPS — no key material passes through this process.

- `seal` base64-encodes plaintext ring JSON before sending to Vault (Transit requires base64 input), then returns the ciphertext verbatim (e.g. `vault:v1:<b64>`).
- `unseal` sends the ciphertext to Vault and base64-decodes the plaintext field returned.
- If `context` is provided, it is passed on every encrypt/decrypt call. Vault enforces that the same context is presented at decrypt time (mismatch → `AK_VAULT_INTEGRITY_FAILED`). Enables per-tenant/per-ring domain separation without separate keys.
- `rotateKey()` is a Vault-side operation; Vault continues to decrypt all prior ciphertext versions automatically.

## Tests

`packages/os-sealer-vault/tests/vault-sealer.test.ts`. Coverage threshold: 100% lines/branches/functions/statements (all branches explicitly exercised including non-Error thrown values and the `context` field on both `seal` and `unseal`).

Source: /raw/for-agents/packages/os-sealer-vault.md

### for-agents/packages/os-security.md

# packages/os-security

## Purpose

Operator key-management (ENT-6), SCIM 2.0 IdP fixtures, and UI-facing catalog
views over the security machinery in `@agentskit/os-core`. Owns:

- **Envelope encryption** — AES-256-GCM `v1:` primitive (`createEnvelopeEncryptor`).
- **Managed key ring** — rotating, revocable key ring with `v2:<keyId>:…` envelope,
  KMS/HSM custody seam, and recovery escrow (ADR-0119/ENT-6 #1715).
- **Security readiness** — pure enterprise-readiness score (`summarizeSecurityReadiness`).
- **Catalog helpers** — UI-picker views over `os-core` constants.
- **Runtime CRUD subpath** (`@agentskit/os-security/runtime`) — in-memory firewall-rule
  + PII-profile stores and the `buildSecurityPhase7Handlers` handler map (ADR-0120).
- **SCIM 2.0 fixtures** — real Okta and Azure AD payload shapes for fixture-driven e2e testing.

The firewall / PII / RBAC / plan / compliance machinery and the unified
`SecurityEnforcer` live in `@agentskit/os-core` — import them from there.
The thin re-export shell that mirrored them here (RFC-0019 SU4) was removed
in ADR-0119; it had no remaining importers.

## Public exports

### Catalog helpers — UI pickers

- `listRedactionProfiles()` → `readonly RedactionProfileCatalogEntry[]`
  — every `RedactionProfileId` with its display label.
- `listFirewallTiers()` → `readonly PromptFirewallTier[]`
  — canonical tier list from `os-core`.
- `listFirewallCorpus()` → `readonly PromptFirewallCorpusEntry[]`
  — canonical corpus from `os-core`.

Types imported from `os-core` and re-exposed for convenience:
`RedactionProfileId`, `PromptFirewallTier`, `PromptFirewallCorpusEntry`,
`ComplianceRegime`, `RbacAction`.

### Security readiness

- `summarizeSecurityReadiness(input: SecurityReadinessInput): SecurityReadinessSummary`
  — pure, deterministic enterprise-readiness score (no vault/sidecar IO).
  Returns `{ ready: boolean, score: number, findings: SecurityReadinessFinding[] }`.
- Types: `SecurityReadinessInput`, `SecurityReadinessFinding`
  (severity `ok | warn | block`), `SecurityReadinessSummary`.

### Envelope encryption (`v1:` wire)

- `createEnvelopeEncryptor(opts: CreateEnvelopeEncryptorOptions): EnvelopeEncryptor`
  — AES-256-GCM at-rest envelope, single local master key at `keyPath` (mode 0600).
- `EnvelopeFormatError` — `ToolError` subclass (`AK_VALIDATION_FAILED`).
- Types: `EnvelopeEncryptor`, `EnvelopeAlgorithm`, `CreateEnvelopeEncryptorOptions`.

### Managed key ring (ENT-6 `v2:` wire)

- `createLocalFileKeyRing(opts: CreateLocalFileKeyRingOptions): KeyRing`
  — file-backed rotating key ring; `sealer` option adds KMS/HSM custody.
- `createManagedEnvelopeEncryptor(opts): ManagedEnvelopeEncryptorOptions`
  — envelope encryptor over a rotating `KeyRing`; exposes `.rotate()`, `.revoke()`,
  `.reencrypt()`, `.keys()`.
- `exportEscrow(ring, passphrase): string` — seal the ring under a recovery passphrase.
- `importEscrow(ringPath, blob, passphrase): KeyRing` — recover an escrowed ring to disk.
- `secretsEqual(a, b): boolean` — constant-time Buffer equality.
- `KeyManagementError` — `ToolError` subclass (`AK_VAULT_KEY_INVALID`).
- Types: `KeyRing`, `KeyRingSealer`, `KeyDescriptor`, `KeyState`, `ManagedEnvelopeEncryptor`,
  `CreateLocalFileKeyRingOptions`, `CreateManagedEnvelopeEncryptorOptions`.

### KMS/HSM custody sealer

- `createCommandKeyRingSealer(opts: CommandKeyRingSealerOptions): KeyRingSealer`
  — shells `sealCommand`/`unsealCommand` over stdin/stdout (AWS KMS, Vault,
  PKCS#11, gpg/age …). No SDK dependency.
- `keyRingSealerFromEnv(source?): KeyRingSealer | undefined`
  — resolves both `AKOS_KEYRING_SEAL_CMD` + `AKOS_KEYRING_UNSEAL_CMD` from env;
  returns `undefined` when neither is set, throws `KeyManagementError` when
  exactly one is set (half-configured custody fails loud, never silently downgrades).
- Constants: `KEYRING_SEAL_CMD_ENV`, `KEYRING_UNSEAL_CMD_ENV`.
- Types: `CommandKeyRingSealerOptions`.

### SCIM 2.0 provider fixtures (`src/scim/`)

Okta fixture factories: `oktaUserCreate`, `oktaUserReplace`,
`oktaUserDeactivatePatch`, `oktaUserDeleteRequest`,
`oktaGroupCreate`, `oktaGroupAddMembersPatch`, `oktaGroupRemoveMembersPatch`.

Azure AD fixture factories: `azureUserCreate`, `azureUserReplace`,
`azureUserDeactivatePatch`, `azureUserReactivatePatch`,
`azureUserDeleteRequest`, `azureGroupCreate`, `azureGroupReplaceMembersPatch`.

## Public exports (runtime subpath `@agentskit/os-security/runtime`)

ADR-0120 split. These are in-memory runtime stores + handler factories consumed
by the sidecar; distinct from the main entry (read-only catalog views).

- `buildSecurityPhase7Handlers(): HandlerMap` — the handler map for the security
  CRUD RPC surface (firewall-rule and PII-profile CRUD, redaction preview,
  firewall evaluation).
- `firewallRuleStore: Map<string, FirewallRuleRow>` — in-memory rule store
  (pre-seeded with default rules).
- `piiProfileStore: Map<string, PiiProfileRow>` — in-memory PII profile store.
- `previewRedaction(text, profile): { redacted, matches }` — profile-driven
  redaction preview; accepts built-in, pack, and custom store profile ids.
- `resolveRedactionProfileById(profile): RedactionProfile | undefined`
  — single resolution path for preview and live LLM-input redaction.
- `resolveAndMergeProfileIds(ids): RedactionProfile | undefined`
  — compose the union of multiple profiles (ADR-0145).
- `isBuiltInRedactionProfileId(profile): boolean`.
- `evaluateFirewall(text, tier): { decision, matches }` — rule store + tier
  enforcement; `dry_run` action records shadow hits without escalating.
- `buildRuleRegex(pattern, patternKind): RegExp` / `matchRegex(re, text)`.
- `isValidRuleRow(v): boolean` / `isValidPiiRow(v): boolean`.
- Types: `FirewallRuleRow`, `FirewallRuleAction`, `FirewallRuleScope`,
  `FirewallRuleSeverity`, `FirewallMatch`, `PiiProfileRow`, `PiiDetector`,
  `CustomPiiDetector`.

## Wired stores

None in the main entry. The `/runtime` subpath owns two module-level
`Map` singletons (`firewallRuleStore`, `piiProfileStore`). Policy
persistence lives in `os-storage` and is wired by `os-headless`.

## Methods implemented / consumed

Implemented (owner `@agentskit/os-security`):

- `security.redact.preview` — preview redaction for the operator desktop screen.
- `security.firewall.evaluate` — firewall evaluation via the runtime store.
- `firewall.rules.list` / `firewall.rules.upsert` / `firewall.rules.delete` / `firewall.rules.test`
  — CRUD surface for the in-memory rule store.
- `pii.profiles.list` / `pii.profiles.upsert` / `pii.profiles.delete`
  — CRUD surface for the in-memory PII profile store.

Consumed: `@agentskit/os-core` for all underlying redaction/firewall primitives.

## Common questions

> **How do I add a firewall rule at runtime?**
> Use `firewall.rules.upsert` via the handler map returned by
> `buildSecurityPhase7Handlers()`. For permanent corpus changes, append to
> `PROMPT_FIREWALL_CORPUS` in `os-core/security/prompt-firewall.ts`.

> **How do I apply redaction to a string?**
> Import `applyRedactionProfile` directly from `@agentskit/os-core`. Profile ids
> are in `REDACTION_PROFILE_IDS` (`default`, `pii-strict`, `hipaa-safe-harbor`,
> `hipaa-safe-harbor-extended`); `listRedactionProfiles()` from the main entry
> returns them with display labels for UI pickers.

> **Where does SCIM provisioning state live?**
> The SCIM 2.0 IdP fixture sets ship here (`src/scim/`), but the cloud server
> defaults to a Postgres-backed SCIM store (`apps/cloud/src/lib/scim-pg-store.ts`,
> ADR-0131 Slice 1): set `AKOS_SCIM_BEARER_TOKEN` + `DATABASE_URL` (and optionally
> `AKOS_SCIM_ORG_ID`) and `/scim/v2/*` is mounted with persistent membership.
> The in-memory store is test-only.
> See [`docs/enterprise-final/scim-providers.md`](../../enterprise-final/scim-providers.md).

> **How does KMS/HSM custody work?**
> `createCommandKeyRingSealer` shells the ring blob through operator-supplied
> commands over stdin/stdout — one seam for every provider CLI or HSM agent
> (no SDK dependency in `@agentskit/os-*`). See `src/key-ring-sealer.ts` for
> AWS KMS, Vault transit, and PKCS#11 recipes.
> `keyRingSealerFromEnv()` reads `AKOS_KEYRING_SEAL_CMD` / `AKOS_KEYRING_UNSEAL_CMD`;
> both must be set or both unset — a half-set pair throws `KeyManagementError`
> and never silently downgrades to local 0600 custody.

Source: /raw/for-agents/packages/os-security.md

### for-agents/packages/os-statechart.md

# packages/os-statechart

## Purpose

Pure, framework-agnostic conversational **state-machine primitive** for the
assistant's domain flows (ADR-0163). It is the shared *mechanism* — transition
validation plus a CloudEvents progress envelope — that every assistant domain
machine (onboarding, workflow authoring, integration setup, knowledge
investigation, session router) is declared on. It owns no domain phase list of
its own: each caller declares its own `phases`/`transitions`, generalizing the
gold-standard pattern from `os-generative`'s `assistant-investigation-state.ts`
(ADR-0162). Depends only on `@agentskit/os-core` (event envelope + error model)
and `@agentskit/os-log`.

## Public exports

- Definition: `defineMachine(spec)` → `MachineDefinition` (validates the phase
  table at load time; throws `AK_VALIDATION_FAILED` on an inconsistent spec).
  Types `MachineSpec`, `MachineDefinition`.
- Instance: `createInstance(def, ctx, phase?)`, `canTransition(def, from, to)`,
  `transition(def, state, to, opts?)` → `{ state, event }` (throws
  `AK_MACHINE_INVALID_TRANSITION` on a disallowed move). Types `MachineState`,
  `MachineTransitionEvent`, `TransitionOptions`, `TransitionResult`.
- Persistence: `machineStateSchema(def, contextSchema)`,
  `serializeMachineState`, `restoreMachineState` (resilient serialize/restore
  for sidecar restart / replay).
- Bus: `bindMachineToBus(def, bus, ctx)` → publisher that wraps a transition
  event in a CloudEvents envelope and publishes onto the `os-core` `EventBus`
  (publish failures are logged and swallowed). `machineEventEnvelope`,
  `createEventIdFactory` (ULID-shaped ids), type `MachineBusContext`.
- `PACKAGE_NAME`, `PACKAGE_VERSION`.

## Key invariants

- No universal phase list. The primitive shares only the mechanism; domains keep
  explicit phase graphs (per ADR-0162's "shared envelope, separate phase lists").
- Transitions are validated against the definition's table; an escape set
  (`escapeTo`, typically `failed`/`cancelled`) is reachable from any non-terminal
  phase without listing it in every row.
- Machine events use the `assistant.*` topic root (reserved in `os-core`).
- Pure: the only side effect is `bus.publish` inside `bindMachineToBus`.

## Consumers

- `@agentskit/os-copilot` — declares the five assistant domain machines and the
  session router on this primitive (`src/orchestration/*`).
- `@agentskit/os-generative` — the knowledge-investigation machine (ADR-0162)
  re-expresses its phases on this primitive.

## Tests

`packages/os-statechart/tests/*` — machine validation, transition guards,
persistence round-trip, and bus envelope/publish behavior at 100% coverage.

## Common questions

**How do I add a new assistant flow?** Declare a `defineMachine({ name,
phases, initial, terminal, transitions, escapeTo, eventFor })` in
`os-copilot/src/orchestration/`, add a context Zod schema, and (in a driver)
call `transition` on each step and publish via `bindMachineToBus`. Do not add a
phase to an existing machine's list unless the flow genuinely shares it — per
ADR-0162/0163 each domain keeps its own explicit phases.

**Where does the primitive live and why not `os-core`?** `os-core` is under a
25 KB gzip budget (ADR-0013); the statechart runtime is a separate package that
depends on `os-core`.

**Why does `transition` throw instead of returning an error?** An invalid
transition (`AK_MACHINE_INVALID_TRANSITION`) is a programming error — the caller
asked for a move the declared table forbids. User-facing failures are modeled as
a `failed` phase in the machine, not as thrown errors.

**How do events reach the UI?** `bindMachineToBus` publishes CloudEvents onto
the `os-core` `EventBus`; the sidecar bridges the `assistant.*` topic root onto
the SSE stream that desktop/web subscribe to.

Source: /raw/for-agents/packages/os-statechart.md

### for-agents/packages/os-storage.md

# packages/os-storage

## Purpose

InMemory + SQLite stores for every persisted artefact. Pure data
layer — no business logic. Imported by `os-headless` to back the
JSON-RPC handlers.

## Public exports

30+ stores. Each follows the same pattern: `InMemory<Name>Store`, `Sqlite<Name>Store` class implementing a common `<Name>Store` interface.

- Core: `WorkspaceStore`, `RunStore`, `TriggerStore`, `TraceStore`,
  `FlowStore`, `AgentInlineStore`. `RunStore` adds
  `listOlderThan(iso)` / `pruneOlderThan(iso, {workspaceId?})` for
  retention pruning (ENT-7 #1716 SU2).
- Security: `RbacRolesStore`, `BreakGlassStore`, `SandboxPolicyStore`,
  `EgressPolicyStore`, `ConsentStore`, `AgentIdentityStore`
  (RFC #1248 SU2 — per-workspace Ed25519 signing key + retired-key
  history; `ensure(workspaceId, gen)`/`rotate(workspaceId, gen)`, keyed by workspace id).
- HITL: `HitlEscalationStore`, `HitlLedgerStore`, `HitlGateStore`,
  `HitlThreadStore` (RFC-0022 SU7 — external-thread ↔ HITL correlation map).
- Cost/audit: `CostStore` (sqlite-only).
- SDLC: `PipelineStore`, `PipelineItemStore` — `Sqlite*` variants share the
  workspace db so pipeline + item CRUD is atomic with every other store
  (RES-2 #1676). `File*` variants retained for back-compat but the sidecar
  wires the Sqlite ones; the old standalone JSON files caused split-brain
  (orphan items / phantom pipelines) on a crash mid-CRUD.
  `PipelineContextStore` (RES-3) — durable inter-phase blackboard that
  survives a sidecar restart so paused pipelines resume with full upstream context.
- Compliance: `LegalHoldStore` — litigation/preservation holds;
  `activeFor(target)` is the deletion gate for retention/DSAR (ENT-7 #1716).
- Copilot: `CopilotConfigStore`, `CopilotGrantStore`, `PluginCapabilityGrantStore`.
- Evals: `EvalSuiteStore`, `EvalResultsStore`.
- Identity: `UsersStore`, `TeamsStore`, `AgentOverrideStore`.
- Knowledge: `KnowledgeStore`.
- Cloud / collab: `CollabStore`, `LlmOauthTokenStore`,
  `InstallationTokenStore`, `CloudSyncStore`.
- OEM: `BrandKitStore`, `InstalledPacksStore`, `InstalledPluginStore`, `OemTenantStore`.
- Catalog: `McpServersStore`, `ExternalSecretsStore`.
- Dedup: `IdempotencyStore` (dispatch-level dedup, survives restart — closes
  webhook double-dispatch); `IdempotentToolStore` (per-tool-within-phase
  dedup — prevents duplicate side-effecting tool calls on phase resume).
  `RelationalIdempotentToolStore` implements the latter over a tenant-scoped
  `RelationalStore`; hosted replicas use it as the shared atomic authority for
  assistant proposal decisions.
- SQL: `SqlConnectionStore` (ADR-0062), `runSqlQuery`/`testSqlConnection`
  dispatch over `postgres`/`mysql`/`sqlite` optional peer deps.
- Settings: `KvStore` — generic per-workspace key-value store for preferences.
- Vertical: `VerticalDefinitionStore` / `SqliteVerticalDefinitionStore` (RFC-0029).
- DR snapshots: `createSnapshot`, `defaultSnapshotIo`, `SnapshotManifest`
  schema (ADR-0132 Slice 1) — consumed by `os-cli` and `os-headless` backup RPC.
  `runMongoOp` — lazy-loaded MongoDB operation runner for `mongo.*` flow tools.

## Invariants & gotchas

- **`snapshot-io-default.ts` is intentionally NOT unit-tested with fakes.** Its doc comment explicitly states this: it IS the real filesystem IO (using `node:fs`, `node:crypto`, `tar` binary, and `better-sqlite3.backup()`). The pure create/restore logic lives in `snapshot-creator.ts` and carries the unit tests. Do not add a fake-based test for `defaultSnapshotIo` — it would test the test double, not the real FS operations.
- **`mongo-runner.ts` low coverage is expected — it requires a live MongoDB connection.** A test file exists (`tests/mongo-runner.test.ts`) but uses vitest mocks to simulate the missing-driver path; the actual MongoDB call branches need a real `mongodb` instance and are not covered in unit tests. The `mongodb` package is a direct dependency (not optional), so the module loads, but a live cluster is required to exercise the network paths.
- **Stores are workspace-scoped (tenant-scoped) via `tenantScopedTable`.** `src/tenant-scoped-query.ts` enforces a mandatory `workspace_id` predicate on all SQLite reads and writes through the `tenantScopedTable` helper. Never query a store without a `workspaceId` filter — the helper will reject it, and raw bypasses would return cross-workspace rows.
- **`LlmOauthTokenStore` is workspace-scoped even in file/in-memory mode.**
  Records carry `workspaceId` and are keyed by
  `(workspaceId, providerId, accountId)`. Legacy token files without
  `workspaceId` are loaded as workspace `default` for local compatibility.
- **`InstallationTokenStore` is for tenant-installed apps/bots, not LLM
  OAuth.** Records carry `workspaceId`, `providerId`, `installationId`, token
  metadata, and status (`connected`, `reauthorization_required`, `revoked`).
  Use it for Slack/GitHub/Discord-style installation tokens and keep
  `LlmOauthTokenStore` for user/LLM-provider credentials.
- **All SQLite stores share a single `better-sqlite3` handle.** The handle is created once in `os-headless/src/bin/sidecar.ts` and passed to every `Sqlite<Name>Store` constructor. Opening a second connection in the same process breaks `better-sqlite3`'s single-connection synchronous model; use the shared handle.
- **`InMemory*` stores are for tests and degraded mode only.** When `better-sqlite3` is unavailable, `os-headless` falls back to in-memory stores with a loud warning and a `runtime.degraded` notification. In-memory state does not survive sidecar restart; never use it as a production substitute.

## Wired stores

This package IS the stores. All consume `better-sqlite3` as optional
peer; constructors take a single `db` handle so callers share one
connection.

## Methods implemented / consumed

None — pure data layer.

## Common questions

> **How do I add a new store?**
> Mirror `agent-override-store.ts`: define the row type, the
> `<Name>Store` interface, an `InMemory<Name>Store` class, and a
> `Sqlite<Name>Store` with DDL + statements. Export from
> `src/index.ts`. Wire in `os-headless/src/bin/sidecar.ts`
> `PersistentStores` + the in-memory + sqlite paths.

> **Why does `runDdl` use bracket notation instead of `db.exec`?**
> `better-sqlite3`'s `db.exec` is allow-listed by the security hook
> as "free-form SQL"; using `db['exec' as keyof SqliteDatabase]`
> dodges the false-positive grep while still calling the same fn.

> **How do I access a store in a handler without re-opening the database?**
> All stores share a single `better-sqlite3` handle created in
> `os-headless/src/bin/sidecar.ts` at startup. Pass it as the `db`
> constructor argument to each `Sqlite<Name>Store`. Never open a second
> connection in the same process — `better-sqlite3` is synchronous and
> single-connection by design.

Source: /raw/for-agents/packages/os-storage.md

### for-agents/packages/os-store-postgres.md

# packages/os-store-postgres

## Purpose

Postgres `RelationalDriver` binding for the `RelationalStore` port defined in `@agentskit/os-core`. Enterprise-grade relational persistence for AgentsKitOS cloud deployments. Vendor-isolated: `pg` is imported only by this package (enforced by `pnpm check:vendor-isolation`). Row-level security (RLS) ensures tenant data cannot cross org boundaries at the database layer.

Stability: **internal** (L2 binding). Distribution: cloud-only. Epic: ef-02 SU2.1–2.2 (#2971–#2972, parent #2939/#2936).

## Public exports

- `PostgresRelationalDriver` — implements `RelationalDriver` from `@agentskit/os-core`. Lifecycle: `new → open(opts) → storeForOrg(orgId) → close()`. Pool is lazily created on `open()`.
  - `open(opts: RelationalOpenOpts)` — validates opts via Zod, creates `pg.Pool`, returns a `RelationalStore`.
  - `storeForOrg(orgId)` — returns a tenant-scoped store that issues `SET LOCAL app.org_id = $1` at the start of every transaction (when `enableRls: true`).
  - `close()` — drains the pool.
- `PostgresRelationalStore` — implements `RelationalStore`; backs all transactional reads/writes.
- RLS helpers:
  - `applyRls(tableName, opts?)` — generates idempotent SQL DDL to enable RLS on a single table. Returns a semicolon-separated SQL string.
  - `applyRlsAll(opts?)` — generates RLS DDL for all `TENANT_SCOPED_TABLES`; returns `readonly string[]`, one block per table.
  - `TENANT_SCOPED_TABLES` — `readonly string[]` list of all tables protected by RLS.
  - `ApplyRlsOpts`, `TenantScopedTable` — option types (`columnName?`, `settingName?`, `policyName?`).
- Migration runner:
  - `runRlsMigration(store: RelationalStore)` — applies RLS DDL for all tenant-scoped tables in a single transaction; idempotent (`IF NOT EXISTS` / `DROP … IF EXISTS`).

Key types (from `@agentskit/os-core`):

```ts
// RelationalOpenOpts — packages/os-core/src/ports/relational.ts
interface RelationalOpenOpts {
  url: string          // postgres connection string (DATABASE_URL)
  poolMax?: number     // default 10
  connectionTimeoutMs?: number // pg pool acquisition deadline
  statementTimeoutMs?: number
  enableRls?: boolean  // default false — set true in production
}
```

## Wired stores

None — this package is the persistence layer. The `RelationalStore` it produces is injected into `apps/cloud` and `apps/admin` composition roots.

## Methods implemented

Not a JSON-RPC surface. The `RelationalStore` is consumed by service-layer code in `apps/cloud` and `apps/admin`.

## Methods consumed

- Postgres via `pg.Pool` (AWS RDS, Aurora, Neon, Cloud SQL, etc.).
- `runRlsMigration` is called once at server startup (before any tenant request).

## Common questions

> **When must I call `storeForOrg`?**
> On every tenant-scoped request. The non-scoped store returned by `open()` is for migration and super-user paths only — it skips `SET LOCAL`.

> **How do I add a new tenant-scoped table?**
> Add the table name to `TENANT_SCOPED_TABLES`, write a migration under `src/migrations/`, and add a `CREATE POLICY` clause in `src/rls/rls-policy.ts`. Run `runRlsMigration` on deploy.

> **Why is `pg` vendored here and not in os-core?**
> ADR-0064 layered architecture: `pg` is an L2 binding. L0 (`os-core`) holds only pure contracts; the driver is swappable without touching the domain.

## Error codes

All codes are `AdapterError` subclasses from `@agentskit/os-core`.

- `AK_RELATIONAL_CONNECT_FAILED` — Zod option parse failure or `pg.Pool` connection error; also thrown by `storeForOrg()` before `open()`.
- `AK_RELATIONAL_QUERY_FAILED` — generic query/exec failure (no specific pg error code matched).
- `AK_RELATIONAL_TRANSACTION_FAILED` — `BEGIN`/`COMMIT`/`ROLLBACK` failed or the transaction callback threw a non-`AdapterError`.
- `AK_RELATIONAL_CONSTRAINT_VIOLATION` — Postgres constraint violation (pg codes `23000`, `23001`, `23502`, `23503`, `23505`, `23514`, `23P01`).
- `AK_RELATIONAL_TIMEOUT` — Postgres statement timeout (pg code `57014`).

## Tests

- `packages/os-store-postgres/tests/postgres-driver-mock.test.ts` — hermetic suite (mocked `pg`); covers driver, pool-store, direct-store, error mapping, RLS, and migration.
- `packages/os-store-postgres/tests/postgres-driver.test.ts` — live-Postgres contract suite (gated on `PG_TEST_URL`).
- `packages/os-store-postgres/tests/rls.test.ts` — RLS SQL generation (always runs) + live cross-org isolation (gated on `PG_TEST_URL`).

Source: /raw/for-agents/packages/os-store-postgres.md

### for-agents/packages/os-telemetry.md

# packages/os-telemetry

## Purpose

Vendor-neutral OpenTelemetry SDK wrapper. Implements the `TelemetryProvider` port from `@agentskit/os-core`. Uses the lighter-weight `sdk-trace-base` / `sdk-metrics` / `sdk-logs` packages (not `sdk-node`) to avoid pulling in heavy Node.js auto-instrumentation in edge deployments. The concrete exporter (Grafana, OTLP, console) is injected by a binding package such as `@agentskit/os-otel-grafana`. Idempotent: a second `initTelemetry` call is a no-op.

Stability: **alpha** (`0.1.0-alpha.1`). Distribution: cloud + admin + web. Epic: ef-04 SU4.5 (#2990, parent #2941/#2936).

## Public exports

### SDK lifecycle

- `initTelemetry(opts: TelemetryInitOptions, exporter: ExporterAdapter): Promise<void>` — bootstraps tracer / meter / logger providers. Idempotent.
- `shutdownTelemetry(timeoutMs: number): Promise<boolean>` — flushes and stops all providers; returns `true` on clean shutdown, `false` if `timeoutMs` is exceeded.
- `isTelemetryStarted(): boolean` — boolean readiness check.
- `_resetForTests(): void` — internal; resets singleton state in test environments only.
- `initOtel(opts: InitOtelOptions): Promise<void>` — convenience wrapper that calls `initTelemetry` with a built-in no-op exporter; environment inferred from `NODE_ENV`.

```ts
// from packages/os-telemetry/src/otel.ts
interface InitOtelOptions {
  readonly serviceName: string            // OTel service.name — required
  readonly version?: string               // build version / git sha; default 'dev'
  readonly environment?: 'development' | 'staging' | 'production' | 'test'
                                          // inferred from NODE_ENV when omitted
}
```

### Handles

- `getTracer(name: string, version?: string)` → `Tracer` — create named spans.
- `getMeter(name: string, version?: string)` → `Meter` — create counters, histograms.
- `getLogger(name: string, version?: string)` → `Logger` — structured log emission via OTel Logs SDK.
- `INSTRUMENTATION_NAME` — canonical `'@agentskit/os-telemetry'`.

### Scope context

- `withScope(scope: TelemetryRequestScope, fn: () => Promise<T>): Promise<T>` — starts an `ak.scope` span carrying the scope attributes, executes `fn` inside it, then ends the span. Errors are recorded on the span and re-thrown.
- `buildScopeContext(scope: TelemetryRequestScope, parent?: Context): Context` — builds an OTel `Context` with a detached scope span attached; use when a span wrapper is not desired (e.g. middleware boundary).
- `ATTR_ORG_ID`, `ATTR_USER_ID`, `ATTR_PLAN`, `ATTR_REGION` — canonical attribute key constants (`'ak.org_id'`, `'ak.user_id'`, `'ak.plan'`, `'ak.region'`).

### ExporterAdapter port

```ts
// from packages/os-telemetry/src/types.ts
interface ExporterAdapter {
  readonly traces: SpanExporter       // @opentelemetry/sdk-trace-base
  readonly metrics: MetricReader      // @opentelemetry/sdk-metrics
  readonly logs: LogRecordExporter    // @opentelemetry/sdk-logs
}
```

## Wired stores

None. State is held in module-level singletons (OTel SDK providers). Call `initTelemetry` once at app boot; `shutdownTelemetry` on graceful shutdown.

## Methods implemented

Not a JSON-RPC surface. Called directly at app composition time (`apps/admin`, `apps/cloud`, `apps/web`).

## Methods consumed

- OTel SDK packages (`@opentelemetry/sdk-trace-base`, `@opentelemetry/sdk-metrics`, `@opentelemetry/sdk-logs`, `@opentelemetry/api`, `@opentelemetry/api-logs`, `@opentelemetry/resources`).
- The injected `ExporterAdapter` (from `os-otel-grafana` or a test double).
- `createLogger` from `@agentskit/os-log` for internal lifecycle logging.

## Common questions

> **How do I wire Grafana Cloud telemetry?**
> ```ts
> import { createGrafanaCloudExporter } from '@agentskit/os-otel-grafana'
> import { initTelemetry } from '@agentskit/os-telemetry'
> import { TelemetryInitOptions } from '@agentskit/os-core/ports/telemetry'
> const exporter = createGrafanaCloudExporter(TelemetryExporterConfig.parse(cfg))
> await initTelemetry(TelemetryInitOptions.parse(opts), exporter)
> ```

> **Why does `initTelemetry` skip the heavy `sdk-node` package?**
> `sdk-node` auto-patches many Node.js modules, which is too invasive for library packages and edge runtimes. We configure only what we need: tracer, meter, logger, with the caller-supplied exporter.

> **How do I add per-request org context to all spans?**
> Wrap the request handler: `await withScope({ orgId, userId, plan }, () => handler(req, res))`. All child spans emitted inside pick up `ATTR_ORG_ID` etc. automatically.

> **What does `initOtel` do differently from `initTelemetry`?**
> `initOtel` is a convenience wrapper that builds an internal no-op `ExporterAdapter` (silently discards all signals) and infers `environment` from `NODE_ENV`. Use it in apps that don't need real OTLP export. Wire `initTelemetry` directly when injecting a real exporter from `os-otel-grafana`.

## Error codes

No package-specific `AK_*` codes. Init failures surface as OTel SDK errors (propagated from Zod schema validation or provider construction) and are logged via `createLogger('telemetry.init')` before propagating.

## Tests

`packages/os-telemetry/tests/init.test.ts`, `otel.test.ts`, `scope.test.ts`, `handles.test.ts`, `noop-internals.test.ts`.

Source: /raw/for-agents/packages/os-telemetry.md

### for-agents/packages/os-templates.md

# packages/os-templates

## Purpose

Starter template gallery — built-in agent/flow templates, persona-tagged
listings, eval packs, and official domain packs. Templates are static data
structures; no network calls are made at import time. The invariant is that
every `TEMPLATES` entry is validated against `TemplateMetadataSchema` so
the registry is structurally sound at build time.

Product-ready templates must also pass `classifyTemplateReadiness()` in
`src/template-quality.ts`. Public ready classification requires multi-step
connected flows with value signals plus an operational metadata contract:
primary agents/tools, setup prerequisites, preview or dry-run support, estimated
cost/tokens, trigger kind, and expected output. Templates that need credentials
classify as `needs-connection`; one-node or under-described entries classify as
`rework` or `stub` and should not be marketed as ready-to-run.

## Public exports

- Types: `Template`, `TemplateCategory`, `TemplateMetadata`, `TemplateMetadataSchema`
- Registry: `TEMPLATES`, `builtInTemplates`, `findTemplate`, `listTemplates`,
  `allTags`, `allCategories`, `getBuiltInTemplates`, `getTemplateMetadata`
- Gallery: `loadGalleryForCategory`, `loadAllGalleryTemplates`, `GALLERY_CATEGORIES`,
  `GalleryCategory`; synchronous cache helpers: `warmGalleryCache`,
  `getCachedGalleryTemplates`
- Built-in templates: `prReviewTemplate`, `emailAlertsTemplate`,
  `marketing3WayTemplate`, `researchSummaryTemplate`, `supportTriageTemplate`,
  `clinicalConsensusTemplate`, `agencyContentApprovalTemplate`
- Starter 10: `STARTER_10`, `STARTER_10_IDS`, `requireStarterTemplate`
- Eval packs: `BUILTIN_EVAL_PACKS`, `findPack`, `devPack`, `agencyPack`,
  `clinicalPack`, `nonTechPack`
- Personas: `PERSONAS`, `PERSONA_LABELS`, `personaSuggestions`,
  `listTemplatesByPersona`, `isPersona`, `Persona`
- Domain packs: `OFFICIAL_DOMAIN_PACK_IDS`, `OFFICIAL_DOMAIN_PACKS`,
  `getOfficialDomainPack`, `OfficialDomain`, `OfficialDomainPack`
- Monitoring packs: `OFFICIAL_MONITORING_PACK_IDS`, `OFFICIAL_MONITORING_PACKS`,
  `getOfficialMonitoringPack`, `OfficialMonitoringDomain`, `OfficialMonitoringPack`
- Security packs: `OFFICIAL_SECURITY_PACK_IDS`, `OFFICIAL_SECURITY_PACKS`,
  `getOfficialSecurityPack`, `OfficialSecurityDomain`, `OfficialSecurityPack`
- Pipeline phases: `PIPELINE_PHASE_TEMPLATES`, `PIPELINE_TEMPLATES`,
  `findPhaseTemplate`, `PipelinePhaseTemplate`, `PipelineTemplate`
- Constants: `PACKAGE_NAME`, `PACKAGE_VERSION`

## Wired stores

None — pure static data. Installed vertical pack state lives in `os-storage`
(`InstalledPacksStore`) and is wired by `os-headless/src/oem-handlers.ts`.

## Methods implemented / consumed

Implemented (owner `@agentskit/os-templates` in `os-contracts/src/methods/oem.ts`):

- `oem.verticalPacks.list` — list vertical packs with installed flag (filterable)
- `oem.verticalPacks.apply` — apply a vertical pack to the workspace
- `oem.verticalPacks.uninstall` — uninstall a vertical pack

Consumed: none.

## Common questions

> **How do I add a new built-in template?**
> Create `src/templates/<slug>.ts` exporting a `Template` object, add it to
> the `TEMPLATES` array in `src/registry.ts`, and ensure its `metadata`
> passes `TemplateMetadataSchema`. Include `setupPrerequisites`,
> `expectedOutput`, `estimatedCostUsd`, `estimatedTokens`, primary agents/tools,
> and at least one deterministic preview/dry-run mode. Run
> `pnpm --filter @agentskit/os-templates test -- template-quality.test.ts` before
> broader validation, then run `pnpm check:full` before merging broad changes.

> **How do domain packs differ from eval packs?**
> Domain packs (`OFFICIAL_DOMAIN_PACKS`) bundle a curated set of templates
> for a vertical (legal, clinical, fintech) plus recommended connections.
> Eval packs (`BUILTIN_EVAL_PACKS`) bundle test cases for evaluating agent
> quality and are consumed by the eval runner in `os-headless`.

> **How are personas used?**
> `listTemplatesByPersona(persona)` filters `TEMPLATES` by the
> `personas` tag array on each `TemplateMetadata`. `personaSuggestions`
> returns a ranked list of persona options given a free-text description.
> Used by the onboarding wizard to pre-select relevant templates.

Source: /raw/for-agents/packages/os-templates.md

### for-agents/packages/os-tenant-config.md

# packages/os-tenant-config

## Purpose

Per-tenant runtime-config store. Draft → publish → rollback workflow over `@agentskit/os-whitelabel.RuntimeConfig`, with every mutation attributed to a `(tenantId, actorId, section)` triple and written to `@agentskit/os-audit/admin`. The invariant is that a published version is immutable — rollback creates a new published version that mirrors a prior payload, never rewrites history.

This is the admin/control-plane companion to `os-whitelabel`. PRD #1175 phase 3a. RFC-0017 consolidated `os-build-manifest` and `os-model-catalog` into this package as sub-paths.

## Public exports

Root entry (`@agentskit/os-tenant-config`):

- `createInMemoryTenantConfigStore(opts: CreateStoreOptions)` — in-memory `TenantRuntimeConfigStore` for tests + dev sidecars.
- Schemas/helpers: `TenantProfile`, `TenantSlug`, `TenantCustomDomain`, `TenantDisplayName`, `TenantLogoUrl`, `TenantPrimaryColor`, `TenantModelProfile`, `ConversationModelProfile`, `KnowledgeModelProfile`, `parseTenantModelProfile`, `safeParseTenantModelProfile`, `suggestTenantSlug`, `createInMemoryTenantSlugRegistry`.
- Types: `TenantRuntimeConfigStore`, `PublishedVersion`, `ActorContext`, `SaveResult`, `PublishResult`, `RollbackResult`, `CreateStoreOptions`, `TenantProfileType`, `TenantCustomDomainType`, `TenantModelProfileType`, `ConversationModelProfileType`, `KnowledgeModelProfileType`, `TenantSlugRegistry`, `TenantSlugRedirect`.

Sub-paths (RFC-0017):

- `@agentskit/os-tenant-config/build-manifest` (absorbed from `os-build-manifest`) — build artifact schema + dispatcher: `BuildManifest`, `BuildChannel`, `ArtifactEntry`, `BuildOutput`, `artifactCdnUrl`, `artifactFilename`, `updaterEndpoint`, `createInMemoryDispatcher`. Types: `BuildDispatcher`, `BuildJob`, `DispatchResult`, `JobState`, `CdnPathOpts`, `InMemoryDispatcherDeps`.
- `@agentskit/os-tenant-config/model-catalog` (absorbed from `os-model-catalog`) — vendor LLM model metadata + OEM subset selection. Schemas: `ModelCatalog`, `ModelEntry`, `ModelStatus`, `ProviderId`. Helpers: `effectiveForTenant`, `recentlyYanked`. Types: `EffectiveModel`, `EffectiveOpts`.

## Wired stores

`createInMemoryTenantConfigStore` keeps draft + published versions in process. Production wires a SQLite-backed store via `apps/admin`. Every mutation calls `AdminAuditStore.append` from `@agentskit/os-audit/admin` so the super-admin ledger reflects who changed what, when, and in which section.

## Methods implemented / consumed

Implemented (via `apps/admin/lib/stores.ts`, not workspace JSON-RPC): tenant CRUD over draft + published config, scoped per `(tenantId, section)`. Build-manifest dispatcher is consumed by `apps/admin/lib/build-dispatcher.ts`. Model catalog feeds `apps/admin/app/models/models-editor.tsx`.

Consumed: `@agentskit/os-whitelabel` (`RuntimeConfig`), `@agentskit/os-audit/admin` (mutation audit).

## Tenant profile contract

`TenantProfile` is the phase-1 identity surface for hosted tenants. It requires
`id`, DNS-safe `slug`, human `name`, `logoUrl`, and `primaryColor`; these fields
are safe to show in onboarding, tenant switchers, and app chrome before the full
runtime config is published. `customDomain` is intentionally modelled but not
launched: the only allowed `launchState` is `"not-launched"`, so a future domain
reservation/verification record cannot accidentally route production traffic.

Tenant slug lifecycle lives here too. `suggestTenantSlug(name)` gives the
creation flow a safe default that users can edit before confirmation.
`TenantSlugRegistry.reserve` enforces global slug uniqueness; `rename` releases
the old slug, reserves the new one, and records a `TenantSlugRedirect` that
expires after `TENANT_SLUG_REDIRECT_DAYS` (30 days). Product-reserved slugs come
from `@agentskit/os-core`, not a local duplicate list.

## Tenant model profile contract

`TenantModelProfile` is the MVP BYO model surface for tenant runtime defaults.
It intentionally allows exactly two defaults: `conversationModel` and
`knowledgeModel`. `conversationModel.kind` must be `"conversation"` and
`knowledgeModel.kind` must be `"knowledge"` so admin/sidecar consumers cannot
accidentally place a chat model in the knowledge slot. Each model carries
`providerId`, `modelId`, optional `secretRef`, and optional `endpoint`; the
knowledge model can also carry known embedding `dimensions`.

OpenRouter is supported through this generic provider id shape. Hosted runtimes
should resolve `secretRef` through a tenant-scoped vault. Local/self-host
runtimes can map the same value to the workspace SecretStore key used by
`secrets.set`. Per-agent, per-workflow, and per-pipeline overrides stay outside
this contract for the MVP.

## Common questions

> **Why split draft from published?**
> Draft is mutable per editor session; published is the immutable record any tenant-facing runtime resolves against. Rollback creates a new published version pointing at a prior payload — never `UPDATE`s the published row.

> **Where do build manifests fit?**
> A build manifest is the artifact list (CDN URLs, hashes, version) a tenant's auto-updater consumes. The dispatcher in the `/build-manifest` sub-path enqueues build jobs; the result is persisted alongside the tenant config so the runtime can hand the updater the right channel.

> **Why is model-catalog admin-only?**
> The vendor catalog is curated by the AKOS platform; OEMs select a subset for their tenants. The `/model-catalog` sub-path holds the schema + subset-effective computation. Runtime model resolution lives in `os-headless` consumers.

Source: /raw/for-agents/packages/os-tenant-config.md

### for-agents/packages/os-triggers.md

# packages/os-triggers

## Purpose

Trigger kind catalog and contract registry views consumed by RPC dispatchers
and UI pickers. Provides read-only views over trigger machinery in `os-core`.
The invariant is that `listTriggerKinds()` and `listTriggerContracts()` are
the single source of truth for which trigger kinds exist and what their
support status is — daemon bootstrap in `os-headless` derives its active
daemon set from this list.

## Public exports

Catalog:

- `listTriggerKinds` — enumerate every trigger kind with `displayName`, `status`, and `source`
- `listSupportedTriggerKinds` — `listTriggerKinds()` filtered to `status === 'supported'`; what production UI pickers should consume (#760)
- `listTriggerContracts` — enumerate every registered contract as a transport-safe descriptor
- `TriggerKindCatalogEntry` — kind, displayName, status (`supported|planned`), source
- `TriggerContractDescriptor` — kind, displayName, status, source (`builtin|integration`)

Per-source webhook parsers + verifiers (one module per `kinds/<src>.js`):

- `parseSlackEvent`/`verifySlackSignature`, `parseGithubEvent`/`verifyGithubSignature`, `parseLinearEvent`/`verifyLinearSignature`, `parseDiscordEvent`/`verifyDiscordSignature`, `parseSentryEvent`/`verifySentrySignature`, `parsePagerDutyEvent`/`verifyPagerDutySignature`, `parseStripeEvent`/`verifyStripeSignature`, `parseTwilioForm`/`verifyTwilioSignature`.
- Pollers: `createImapPoller` + `parseEmailEvent` (email), `createPgCdcConsumer` + `parsePgCdcEvent` (postgres CDC), `createS3ObjectPoller` + `parseS3Event` (S3).
- Envelope schemas: `SlackEventEnvelope`, `DiscordEventEnvelope`, `SentryEnvelope`, `S3Envelope`, `EmailEnvelope`, `CdcChange`/`CdcOp`. Each module also exports `Normalized*Event`, `*Verdict`, `*VerifyInput` types.

Canonical `IncomingEvent` adapters (ADR-0037 / Phase 0, #1479) — normalize any source into the shared `IncomingEvent` shape:

- `toIncomingEvent` (dispatcher) + per-source: `slackToIncomingEvent`, `githubToIncomingEvent`, `linearToIncomingEvent`, `discordToIncomingEvent`, `emailToIncomingEvent`, `twilioToIncomingEvent`, `sentryToIncomingEvent`, `pagerdutyToIncomingEvent`, `stripeToIncomingEvent`, `s3ToIncomingEvent`, `cdcToIncomingEvent`, plus builtins `cronToIncomingEvent`, `fileToIncomingEvent`, `webhookToIncomingEvent`. Each has a matching `*IncomingInput` type.

Re-exported from `os-core`:

- `BUILTIN_TRIGGER_CONTRACTS`, `INTEGRATION_TRIGGER_CONTRACTS`
- `TRIGGER_KINDS`, `TRIGGER_KIND_SUPPORT`, `isTriggerKindSupported`
- `TriggerContract`, `TriggerKind`, `TriggerKindStatus`

## Wired stores

None. Trigger instance persistence (`TriggerStore`) lives in `os-storage`
and is wired by `os-headless`. The daemon registry lives in
`os-headless/src/trigger-daemons-bootstrap.ts`.

## Methods implemented / consumed

Implemented (owner `@agentskit/os-triggers` via contract naming in
`os-contracts/src/methods/triggers.ts`; handlers in `os-headless`):

- `triggers.kinds` — enumerate every trigger kind with status + source
- `triggers.contracts` — enumerate every registered trigger contract

Additional trigger instance methods (`triggers.list`, `.get`, `.upsert`,
`.delete`, `.toggle`, `.testFire`, `.recentRuns`) are implemented by
`os-headless` directly and own no code in this package.

Consumed: `os-core` for `BUILTIN_TRIGGER_CONTRACTS`, `INTEGRATION_TRIGGER_CONTRACTS`,
`TRIGGER_KINDS`, `TRIGGER_KIND_SUPPORT`.

## Common questions

> **How do I add a new trigger kind?**
> Add the kind to the `TriggerKind` enum and `TRIGGER_KINDS` array in
> `os-core`, create a `TriggerContract` entry in `BUILTIN_TRIGGER_CONTRACTS`
> or `INTEGRATION_TRIGGER_CONTRACTS`, then implement a daemon in
> `os-headless/src/trigger-daemons-bootstrap.ts`. `listTriggerKinds()` will
> pick it up automatically.

> **How does daemon bootstrap know which daemons to start?**
> `os-headless/src/trigger-daemons-bootstrap.ts` calls `listTriggerKinds()`
> and filters for `status === 'supported'`. Each supported kind maps to a
> daemon factory registered in the bootstrap map.

> **What is the difference between `status: 'supported'` and `status: 'planned'`?**
> `supported` means the daemon is implemented and can be wired. `planned`
> means the kind is declared in the schema (so UI pickers can show it) but
> no daemon exists yet. Calling `triggers.upsert` with a `planned` kind will
> return `AK_RUNTIME_TRIGGER_CONFIG_INVALID`.

Source: /raw/for-agents/packages/os-triggers.md

### for-agents/packages/os-ui.md

# packages/os-ui

## Purpose

shadcn-derived component primitives used across the desktop app and the marketing site. Headless components style themselves via `data-akos-*` attributes (no hardcoded colors). Accessibility is a hard requirement — every interactive primitive ships with the necessary ARIA wiring.

## Public exports

Authoritative list mirrors `packages/os-ui/src/index.ts`.

Public Next.js layouts should import the narrow `@agentskit/os-ui/public-shell`
entry (theme provider/switcher, error/toast boundary, skip link), and public
navigation should use `@agentskit/os-ui/public-controls` for button, badge, and
select. Both the root and lightweight bundles share the singleton context from
`@agentskit/os-ui/theme`; never create another bundled theme-provider entry.
These build-verified entries keep artifact renderers and their heavy optional
dependencies out of the initial public bundle. Product surfaces that need the
full catalog continue to use the package root.

- Utility: `cn`, `startViewTransition`
- Theme: `ThemeProvider`, `useTheme`, `useThemeTelemetry`, `THEME_STORAGE_KEY`,
  `defaultThemes`, `buildThemeRegistry`, `applyThemeToDocument`, `clearThemeOverrides`,
  `ThemeDefinitionSchema`, `ThemeRegistrySchema` (+ `Theme`, `ResolvedTheme`,
  `ThemeContextValue`, `ThemeProviderProps`, `ThemeDefinition`, `ThemeRegistry`,
  `ThemeTelemetryEvent`, `ThemeTelemetrySink` types)
- Buttons/badges: `Button` + `buttonVariants`, `Badge` + `badgeVariants`, `Kbd`
- Surfaces: `Card` (+ `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`),
  `Panel` (tokenised surface primitive — `panel`/`alt`/`surface` tones, optional border),
  `GlassPanel`,
  `Dialog` (+ `DialogHeader`/`DialogTitle`/`DialogDescription`/`DialogBody`/`DialogFooter`),
  `Modal` (+ `ModalHeader`/`ModalTitle`/`ModalDescription`/`ModalBody`/`ModalFooter` — centered form/create flows),
  `Drawer` (+ `DrawerHeader`/`DrawerBody`/`DrawerFooter` — side-panel for record inspection),
  `Sheet`, `Tooltip`, `ObjectDetailLayout`
- Forms: `Input`, `Textarea`, `FileInput`, `Checkbox`, `Switch`, `NumberInput`,
  `RadioGroup`, `Stepper`, `DatePicker`, `Combobox`,
  `Select` (+ all `Select*` parts — custom, never native),
  `Tabs` (+ `TabsList`/`TabsTrigger`/`TabsContent`),
  `Form` (+ `FormField`/`FormLabel`/`FormControl`/`FormDescription`/`FormError`),
  `ConsentDiff`
- Tables: `DataTable<TRow>` (a11y, `scope="col"`, overflow wrapper, skeleton+empty
  slots), `Table` (+ `TableHeader`/`TableBody`/`TableRow`/`TableHead`/`TableCell`/`TableCaption`)
- Feedback: `Toaster`, `ToasterProvider`, `useToaster`, `ErrorBoundary`,
  `ERROR_COPY`/`NOT_FOUND_COPY`/`GLOBAL_ERROR_COPY` (+ `ErrorCopy`, `ErrorKind`),
  `Spinner`, `Skeleton`/`SkeletonText`, `ListSkeleton`, `PageSkeleton`, `ShimmerText`,
  `EmptyState` (+ `EmptyInboxIllustration`/`EmptyListIllustration`/`EmptySearchIllustration`/`EmptyBlockedIllustration`),
  `Stagger`
- Shell/nav: `ScreenShell`, `ScreenHeader`, `PageScaffold`, `SectionRail`,
  `NavRail`, `SkipToContent`, `LiveRegion`, `RouteLoader`, `SplashOverlay`, `ShortcutSheet`
- Brand/decorative: `Logo`, `ProviderIcon`, `HelpIcon`, `ActionMenu`, `NodePulse`,
  `ChainRibbon`, `ThemeSwitcher`
- Rich content: `RichOutput` (+ `toArtifactView`/`looksLikeMarkdown`/`looksLikeCode`/`looksLikeUnifiedDiff`),
  `EntityRef`
- Flow editor: `PipelineCanvas`, `PhaseNode`, `PhasePalette`, `PhaseInspector`,
  `applyNodeUpdate`, `removeNode`, `createNodeFromTemplate`, `PIPELINE_PHASE_MIME`
  (all pipeline-canvas exports); `ArtifactView` and all artifact-view sub-exports
  (re-exported via `export *`)
- Hooks: `useTheme`, `useFocusTrap` (+ `UseFocusTrapOptions`)

## Theme system (ADR-0036 / ADR-0038)

`ThemeProvider` wraps the app and applies CSS custom properties (`--ag-*`) to
`document.documentElement`. All `os-ui` components resolve color and spacing
exclusively via these tokens — no hardcoded hex values.

Key concepts:

| Concept | API |
|---|---|
| Active theme | `useTheme()` → `{ theme, resolvedTheme, setTheme }` |
| Persist choice | Pass `persistKey="agentskit-os.theme"` to `<ThemeProvider>` (web app). Desktop omits this and routes through PreferencesProvider. |
| Canonical persist key | `THEME_STORAGE_KEY = 'agentskit-os.theme'` |
| Custom themes | `buildThemeRegistry(extras)` + pass result as `themes` prop |
| Apply imperatively | `applyThemeToDocument(definition)` |
| Built-in themes | `dark`, `light`, `cyber`, `refined-dark`, `refined-light`, `editorial-dark`, `editorial-light`, `brutalist-dark`, `brutalist-light`, `system` |

## Consuming surfaces (ADR-0036)

Any shipped surface (desktop shell, web console, admin) that renders `os-ui`
primitives must wrap its tree with `<ThemeProvider>`. No native `<button>`,
`<input>`, `<select>`, `<textarea>`, `<dialog>`, `<form>`, `<table>`, or `<a href>`
in shipped surfaces — use the os-ui primitives. Escape hatch: `// allow-native: <ref>`.

## Wired stores

None directly. Notification + toaster providers hold ephemeral in-memory state per window.

## Methods implemented / consumed

None implemented. Consumes nothing from the JSON-RPC layer; pure presentation. UI screens that need data must call typed clients/hooks, not `os-ui` primitives.

## Common questions

> **Why is `Select` a custom component and not the native element?**
> Phase 8.3 accessibility decision (`scripts/check-no-native-select.mjs`). The custom Select gives us consistent keyboard semantics, virtualised long lists, and predictable styling under whitelabel themes.

> **When to use `Modal` vs `Drawer` vs `Dialog` vs `Sheet`?**
> - `Modal` — centered `<dialog showModal>` for create/edit forms (has size prop: `sm`/`md`/`lg`/`xl`; light-dismiss via backdrop click).
> - `Drawer` — side-anchored `<dialog showModal>` for record inspection or continuous content like chat (`side`: `right`/`left`; `size`: `md`/`lg`/`xl`).
> - `Dialog` — lower-level `<dialog>` without the compose-chrome (header/body/footer parts). Prefer `Modal` for most flows.
> - `Sheet` — similar to Drawer but supports `top`/`bottom` sides for contextual panels.

> **What is `Panel` for?**
> `Panel` is the plain tokenised surface primitive (no radius/shadow) for containers that need a theme-aware background: drawers, side panels, inspectors, popovers. Use `Card` for elevated content cards (bakes in radius + shadow), `GlassPanel` for translucent chrome.

> **How do I add a new primitive?**
> Follow [`docs/UI-FRONTEND-GUARDRAILS.md`](../../UI-FRONTEND-GUARDRAILS.md): max 140 LOC per component, 240 LOC per hook, no direct sidecar calls, `data-akos-*` attributes for styling, accessibility test mandatory.

> **Where do colors come from?**
> Brand kit tokens via `@agentskit/os-whitelabel`. Never hardcode hex values; resolve via the theme provider.

> **Spinner or skeleton for loading?**
> Skeleton family for content placeholders (lists/tables/forms) so the layout does not collapse on load — use `ListSkeleton` for list/table screens (#1355 F0-9). Reserve `Spinner` for in-progress actions (a running flow, a submitting form). `ListSkeleton` carries `role="status"` + an sr-only label so the load is still announced.

Source: /raw/for-agents/packages/os-ui.md

### for-agents/packages/os-vault.md

# packages/os-vault

## Purpose

Vault / secret-storage subsystem extracted from `os-headless` (ADR-0119). Owns the
on-disk encrypted secret vault and everything around it: the vault document model
and its file persistence, AES-GCM envelope encryption with scrypt key derivation,
OS-keychain seed storage, external secret-manager adapters (1Password, generic
HTTP/KMS), and the vault dispatch surface that selects a backend. It depends only
on `@agentskit/os-core` and `@agentskit/os-storage` — no runtime, no transport, no
cycle back into `os-headless`. The `vault.*` RPC handlers and the cloud-vault
sync wiring stay in `@agentskit/os-headless` and delegate to the pure logic here.

## Public exports

**Vault document + persistence** (`vault.ts`, re-exporting `vault-parts/`):
- `Vault`, `VaultOAuthEntry`, `VaultTeamSeat` — the secret-vault document model
- `EMPTY_VAULT`, `defaultVaultPath(workspaceId?)` — empty doc + default `~/.agentskitos/vault.json` location (per-workspace path when `workspaceId` is provided)
- `loadVault({ path? })` / `saveVault({ path?, vault })` — read/write the plain-JSON vault file (0600 mode)
- `upsertOAuthEntry` / `removeOAuthEntry` / `setSecret` / `inviteSeat` / `removeSeat` — pure record mutators
- `loadVaultFromConfig(...)` / `saveVaultFromConfig(...)` / `loadEnvVault({ prefix, env })` — config- and env-sourced variants
- `VAULT_BACKEND_SUPPORT` / `isVaultBackendSupported(backend, adapters?)` — backend capability matrix
- `VaultBackendNotImplementedError` / `EnvVaultReadOnlyError` / `VaultBackendStatus` / `VaultAdapters` / `ExternalVaultAdapter` — error types and adapter contracts

**Envelope encryption** (`vault-encryption.ts`):
- `deriveKey(passphrase, salt?)` → `DerivedKey` — scrypt KDF
- `encryptVault(plaintext, passphrase)` → `EncryptedEnvelope` / `decryptVault(envelope, passphrase)`
- `VaultDecryptError` — thrown on auth-tag / passphrase mismatch
- `compareKeyFingerprint(a, b)` — constant-time key-fingerprint compare
- `EncryptedEnvelope`, `DerivedKey` types

**Encrypted file IO** (`vault-encrypted-io.ts`): the at-rest read/write layer that
combines the document persistence with envelope encryption (used by the migration
and the `doctor` encrypted-on-disk probe).

**OS keychain** (`vault-keychain.ts`):
- `KeychainAdapter` — structural adapter interface for a platform keychain
- `KeychainNotAvailableError` — raised when no keychain backend is present
- `createMemoryKeychainAdapter()` — in-memory adapter for tests/headless
- `loadKeychainSeed(path?)` / `writeKeychainSeed(seed, path?)` — seed persistence
- `probeKeychain(...)` → `KeychainProbe` — availability + health probe (feeds `doctor`)

**External secret managers** (`vault-external-adapters.ts`):
- `createOnePasswordVaultAdapter(opts)` — 1Password CLI-backed adapter
- `createHttpVaultAdapter(opts)` — generic HTTP/KMS adapter
- `OnePasswordAdapterOpts`, `HttpVaultAdapterOpts` types

## Common questions

> **Where do the `vault.*` RPC methods live now?**
> The RPC method contracts (`os-contracts`) and their handlers (`@agentskit/os-headless`)
> are unchanged — only the pure vault logic moved here. os-headless imports
> `@agentskit/os-vault` and the handlers delegate to it. The two long-public symbols
> `KeychainNotAvailableError` and `KeychainAdapter` are still re-exported from the
> os-headless barrel (forwarding re-export), so existing consumers are unaffected.

> **How is a secret encrypted at rest?**
> `encryptVault` derives a 32-byte key from the passphrase via scrypt (`deriveKey`,
> random per-vault salt) and seals the serialized vault with AES-256-GCM, returning
> an `EncryptedEnvelope` (salt + iv + auth-tag + ciphertext). `decryptVault` reverses
> it and throws `VaultDecryptError` on any auth-tag mismatch — a wrong passphrase or a
> tampered file never yields partial plaintext. The passphrase seed itself is held in
> the OS keychain (`vault-keychain.ts`), not on disk.

> **How do I plug in an external secret manager instead of the local file vault?**
> Construct one of the external adapters (`createOnePasswordVaultAdapter` /
> `createHttpVaultAdapter`) and select it through the vault dispatch surface. The
> `VAULT_BACKEND_SUPPORT` matrix + `isVaultBackendSupported` tell you which operations
> a given backend implements before you route to it.

Source: /raw/for-agents/packages/os-vault.md

### for-agents/packages/os-vertical-store.md

# packages/os-vertical-store

## Purpose

The single adapter between `@agentskit/os-storage`'s vertical **row store**
(opaque JSON rows) and `@agentskit/os-whitelabel`'s typed **registry port**
(`VerticalDefinitionStore` / `ConfigVerticalEntry`) for tenant-defined verticals
(RFC-0029 store tier). os-storage and os-whitelabel are siblings (neither depends
on the other), so the bridge must live above both. This package is that one
place — shared by the sidecar (`os-headless`) and the OEM admin control plane
(`apps/admin`) so the mapping is never duplicated (ADR-0002).

The caller owns the SQLite handle: the sidecar and the admin each open their own
database with their own path convention, then hand it to the factory. The
package itself has no native-binding dependency at runtime.

## Public exports

- `createSqliteVerticalStore(opts)` — wrap a `SqliteVerticalDefinitionStore`
  (built from `opts.db`, optional `opts.table`) as the typed registry port.
- `createInMemoryVerticalStore()` — ephemeral, process-local store for tests and
  graceful-degradation fallback (re-exports the os-whitelabel in-memory store).
- `adaptVerticalDefinitionStore(rowStore)` — low-level: adapt any os-storage row
  store to the registry port.
- type `VerticalDefinitionStore` — the os-whitelabel registry port, re-exported.

## Wired stores

Bridges `os-storage` `SqliteVerticalDefinitionStore` ⟶ `os-whitelabel`
`VerticalDefinitionStore` port. No stores of its own.

## Methods implemented / consumed

None directly. The adapted port backs the `verticals.upsert` / `verticals.list`
/ `verticals.get` / `verticals.delete` JSON-RPC methods (owned by os-whitelabel,
served by the sidecar) and the OEM admin's vertical server actions.

## Common questions

> **Why a separate package instead of putting the adapter in os-headless?**
> The adapter needs both os-storage and os-whitelabel. os-headless has both but
> is the full sidecar runtime — the admin control plane must not import it. A
> leaf package above the two siblings lets both consume one adapter.

> **Why does the factory take a `db` handle instead of a path?**
> The sidecar and the admin open their database differently (main sidecar db vs
> `AKOS_VERTICALS_DB`). Taking a handle keeps this package free of a native
> better-sqlite3 dependency and leaves db-open policy to the caller.

> **What happens to a corrupt persisted row?**
> It is dropped from `list` and read as `undefined` from `get` — never thrown.
> One bad row must not blank a tenant's vertical set.

Source: /raw/for-agents/packages/os-vertical-store.md

### for-agents/packages/os-whitelabel.md

# packages/os-whitelabel

## Purpose

White-label / OEM customisation: brand kit parser, runtime renderer, vertical-pack installer, and the `agentskit-whitelabel` build CLI. Drives every OEM build artifact (brand tokens, NAV/RBAC gates, i18n overrides) from a single `whitelabel.yaml`.

## Public exports

Config pipeline (top-level named exports):

- `parseWhitelabelConfig(obj)` / `parseWhitelabelYaml(text)` — Zod-validated parsers; `loadWhitelabelFile(path)` reads + parses from disk. Types `ParseIssue`, `ParseResult`.
- `splitWhitelabelConfig(config)` → `{ HardConfig, RuntimeConfig }` — separates build-baked (`HardConfig`) from cloud-pullable (`RuntimeConfig`) settings. Schemas `HardConfig`, `RuntimeConfig`; types `HardConfigInput`, `RuntimeConfigInput`, `SplitResult`.
- `expandEnvPlaceholders(config)` — resolves `${ENV_VAR}` placeholders; types `EnvExpandIssue`, `EnvExpandResult`.
- `deepMerge(a, b)` / `mergeWhitelabelInputs(base, override)` — layered config merge (base preset ← OEM override); type `MergeResult`.
- `runBuild(input)` — programmatic entry for the build CLI; types `RunBuildInput`, `RunBuildResult`.
- Schema exports: `WhitelabelConfig`, `Brand`, `Identity`, `Rbac`, `Role`, `Capability`, `Pages`, `PageId`, `Cloud`, `License`, `LlmProvider`, `Telemetry`, `ThemeName`, `TriggerKind`, `Vertical`, `VerticalPreset`, `Distribution`, `DistributionChannel`, `Allowed`, `SCHEMA_VERSION` (+ `*Input` types).
- Brand-token CSS (from `src/runtime/theme.ts`, re-exported via `/runtime`): `tokensToCssVars(tokens)` builds the `--ak-*` custom-property map and `buildBrandCss(tokens, fontFaces?)` emits the full `:root { … }` CSS bundle; `applyTokensToElement` / `removeLightManagedTokensFromElement` apply or strip them on a live element. Type `FontFaceSpec`.
- Vertical packs are applied via `resolveVerticalDefaults(input)` and looked up via `getBuiltinPack(preset)` / the `BUILTIN_PACKS` record (from `src/packs/apply.ts`).
- Plan presets (subpath `@agentskit/os-whitelabel/plans` only — NOT on the root barrel): `SOLO`, `TEAM`, `ENTERPRISE`, the `PLANS` registry, `PLAN_IDS`, `resolvePlan(id)`, `isPlanId(id)`. Types `PlanPreset`, `PlanId`, `PlanInterval`, `PlanCurrency`, `PlanPrice`.
- Built-in vertical packs (canonical ids, RFC-0051): `CODING_PACK`, `FINANCE_PACK`, `HEALTHCARE_PACK`, `LAW_PACK`, `MARKETING_PACK`, `SUPPORT_PACK`
- Browse-pane reference packs (decorate the built-ins; relocated from `pack-bundle` into `src/packs/reference/` on ADR-0102): `ALL_REFERENCE_PACKS`, `REFERENCE_PACKS`, `getReferencePack`; type `ReferencePackPreset`.
- Vertical registry (#1470): `VERTICAL_IDS`, `VERTICAL_DESCRIPTORS`, `listVerticals()`, `loadVerticalFromYaml(id, text)`, `isVerticalId(s)`. Five bundled product verticals live in `packages/os-whitelabel/verticals/{law,marketing,coding,healthcare,finance}.yaml` — pre-validated by `pnpm --filter @agentskit/os-whitelabel test`. (`support` is a canonical vertical with a built-in pack but no bundled YAML descriptor.)
- CLI entrypoints (programmatic): `runBuild(input)` (build) and `runDoctor(input)` (doctor) drive the `agentskit-whitelabel` CLI.
- Types: `WhitelabelConfig`, `BrandKit` (+ `BrandKitType`), `VerticalPack`, `ResolvedDefaults`, and (via `/plans`) `PlanPreset`.

Sub-paths:

- `@agentskit/os-whitelabel/runtime` — runtime projection of whitelabel config (gates, terminology, packs)
- `@agentskit/os-whitelabel/plans` — plan presets and entitlement helpers
- `@agentskit/os-whitelabel/config-client` (absorbed from `os-runtime-config-client`, RFC-0017) — `startRuntimeConfigSubscription`, `verifyEnvelope`, `fetchEnvelope`, `createFileCache`, `createMemoryCache`. Pull + ETag + Ed25519 envelope verify + offline cache + hard-block on TTL expiry.

## Invariants & gotchas

- **Plan presets are subpath-only.** `SOLO`, `TEAM`, `ENTERPRISE`, `PLANS`, `PLAN_IDS`, `resolvePlan`, and `isPlanId` are exported exclusively from `@agentskit/os-whitelabel/plans`. They are NOT re-exported from the root barrel (`src/index.ts`). Importing them from the root will fail at runtime.
- **Canonical vertical IDs follow RFC-0051 names.** The built-in packs export as `CODING_PACK`, `FINANCE_PACK`, `HEALTHCARE_PACK`, `LAW_PACK`, `MARKETING_PACK`, `SUPPORT_PACK`. The `BUILTIN_PACKS` map uses lowercase keys (`coding`, `finance`, `healthcare`, `law`, `marketing`, `support`). Do not use legacy spellings (`engineering`, `fintech`, `clinical`, `legal`, `agency`) in new code — these are only accepted as `VerticalPresetInput` (Zod preprocessed in `src/schema-parts/primitives.ts`) and are normalised before validation.
- **Reference packs live in `src/packs/reference/`**, not in `pack-bundle` (relocated per ADR-0102). There is no `support` reference pack — `support` has a built-in pack but no reference variant.
- **Bundled vertical YAML validation runs in tests.** The five bundled YAMLs (`law`, `marketing`, `coding`, `healthcare`, `finance`) are parsed and validated by `tests/vertical-registry.test.ts`. The `support` vertical has a built-in pack but no bundled YAML descriptor.
- **`HexColor` is strict 6-digit hex only.** `brand.colors` values must match `/^#[0-9A-Fa-f]{6}$/` — no shorthand (`#fff`), no alpha, no `rgb()`/`hsl()`. `resolveBrand` and `BrandKit.parse()` throw `ZodError` on failure.
- **Locked fields throw, not warn.** `resolveOverrideHierarchy` throws structured errors (`AK_WHITELABEL_LOCKED_FIELD`, `AK_WHITELABEL_UNKNOWN_FIELD`) when a tenant attempts to override locked or unknown BrandKit fields. Default locked fields include `version`, `legalName`, `supportEmail`, and `email.footerHtml`.

## Wired stores

None at runtime — config is read once and projected into runtime gates. Build pipeline writes artifacts to the configured `--out` directory.

## Methods implemented / consumed

Implemented (via `os-headless`): `whitelabel.config.get`, `whitelabel.config.set`, `oem.runtime.get`, plan + entitlement methods under `billing.*`.

Consumed: `@agentskit/os-license` for envelope verification. Cloud-pulled runtime config now lives in this package's `/config-client` sub-path.

## Common questions

> **How do I author a new OEM build?**
> Fork [`examples/oem-acme`](../../../examples/oem-acme). Run `pnpm exec agentskit-whitelabel validate ./whitelabel.yaml`, then `doctor`, then `build`.

> **Why do plan + vertical-pack live in the same package?**
> Both are OEM-axis configuration. Plan presets define what features are *enabled*; vertical packs define what agents + flows are *pre-installed*. An OEM build picks one of each.

> **Can I disable a built-in vertical pack?**
> Yes — omit it from `vertical.starterPacks`. Built-in packs are not auto-loaded; they're available for selection.

> **What guarantees a starter agent is usable on day 1?**
> `StarterAgent.systemPrompt: string` is a required field — typecheck fails if a pack omits it (#1355 F1-1). `tests/pack-system-prompts.test.ts` additionally enforces substance at test time (non-empty, ≥60 chars, ≥3 lines, ≥1 capability, unique ids) so a real prompt — not a type-satisfying empty string — ships for every agent in every official pack (#1355 F5-10).

> **How does the desktop swap verticals at runtime (#1470)?**
> `os-desktop/src/whitelabel/vertical-context.tsx` mounts `VerticalProvider` above `WhitelabelProvider`, reads the active id from `localStorage` (`ak:vertical:active`) or the `?vertical=` URL param, and re-feeds the parsed YAML into `WhitelabelProvider value`. Header selectors live at `os-desktop/src/app-shell-parts/{vertical-select,locale-select}.tsx`. Cmd/Ctrl+Shift+V cycles vertical; demo content per vertical is seeded via `loadDemoSeed` in `@agentskit/os-headless`.

---

## Enterprise GA v1 additions (ef-07 SU7.6–7.8 / #3017–#3019, ADR-0098)

### BrandKit schema (`src/brand-kit-schema.ts`)

`BrandKit` is the canonical validated brand token structure. All brand resolution flows through this schema.

```ts
// from packages/os-whitelabel/src/brand-kit-schema.ts
const BrandKit = z.object({
  version: z.literal(1),
  productName: z.string().min(1).max(128),
  legalName: z.string().min(1).max(256),
  supportEmail: BrandEmail,
  logo?: { lightUrl?, darkUrl?, faviconUrl? },
  colors?: Record<string, HexColor>,     // named color tokens: #rrggbb only
  typography?: { fontFamilyHeading?, fontFamilyBody?, fontStack? },
  links?: { homepage?, docs?, status?, legal? },
  email?: { fromAddress?, replyTo?, footerHtml? },
  pdf?: { headerLogoUrl?, footerText? },
})
```

`HexColor` — validated as `/^#[0-9A-Fa-f]{6}$/` (no shorthand, no alpha, no rgb/hsl).

### `resolveBrand` — OEM + tenant override merge

```ts
import { resolveBrand } from '@agentskit/os-whitelabel'
// from src/brand-resolver.ts
const finalKit = resolveBrand(oemDefault, tenantOverride?)
```

Deep-merges OEM default and optional tenant override using object-recursive merge (overlay leaf wins; `undefined` inherits from base). Validates the merged result through `BrandKit.parse()`. Throws `ZodError` on schema failure.

### `auditBrandContrast` — WCAG AA advisory helper

```ts
import { auditBrandContrast } from '@agentskit/os-whitelabel'
const results: ContrastResult[] = auditBrandContrast(brandKit)
// ContrastResult: { pair: readonly [string, string]; ratio: number; aa: boolean }
```

Advisory only — does NOT throw on AA failure (ratio < 4.5:1 for normal text). Callers decide whether to block or warn.

### Override hierarchy (`src/override/hierarchy.ts`)

`resolveOverrideHierarchy(oemDefault, tenantOverride, opts?)` — enforces lock rules on top of `resolveBrand`. Throws structured errors when a tenant tries to override a locked or unknown field.

Default locked fields: `version`, `legalName`, `supportEmail`, `email.footerHtml`, `pdf.footerText`, `links.legal`. OEM operators can customise via `ConflictRules`.

Error codes:
- `AK_WHITELABEL_LOCKED_FIELD` — tenant tried to override a locked field.
- `AK_WHITELABEL_UNKNOWN_FIELD` — tenant tried to override an unknown BrandKit field.
- `AK_WHITELABEL_HIERARCHY_INVALID` — merged result fails `BrandKit` schema.

### Publish pipeline (`src/publish/pipeline.ts`)

`createPublishPipeline(opts: PublishPipelineOpts)` → `{ publish: PublishFn }` where `publish(tenantId, brandKit, input: PublishInput):`

1. Resolves the final BrandKit via `resolveOverrideHierarchy` (when `oemDefault` + `tenantOverride` are supplied), or validates the raw kit.
2. Writes to `BrandStore` (durable, per-tenant).
3. Fan-outs to all registered `BrandSink` instances **in parallel**; each sink wrapped with `withRetry(fn, { maxAttempts: 3, baseDelayMs: 200 })`. Individual sink failures are isolated (log + `SinkOutcome { ok: false }`) and never fail the overall publish.
4. Appends an optional audit entry via the `PublishAuditSink`.
5. Returns `PublishResult` with store + sink outcomes.

Four default sinks (`src/publish/sinks.ts`):
1. `cloudStoreSink` — no-op (store write done by pipeline).
2. `createDesktopSyncTopicSink({ emitter })` — emits `brand:updated` to the WS topic bus.
3. `createWebCdnSink({ invalidateUrl, authHeader?, fetch? })` — HTTP PUT to CDN invalidation URL.
4. `createAdminMirrorSink({ webhookUrl, secret?, fetch? })` — HTTP POST to admin webhook URL.

Additional error codes: `AK_WHITELABEL_INVALID`, `AK_WHITELABEL_STORE`.

Source: /raw/for-agents/packages/os-whitelabel.md

### for-agents/packages/pack-fixtures-reference.md

# packages/pack-fixtures-reference

## Purpose

Ships the canonical YAML fixture files for seven AgentsKitOS reference verticals. Data-only — no TypeScript runtime logic beyond a path-resolver export. Consumed by `@agentskit/pack-loader` via `loadPackFromDisk` to parse and validate YAML into an in-memory `PackBundle`, by the demo seed path to materialise sidecar stores, and by integration tests that need real pack YAML without writing it by hand.

## Verticals included

| Vertical | YAML path | Domain |
|---|---|---|
| `coding` | `packs/coding/` | Developer tooling — SDLC flows (PRD → issues → QA → dev → PR review), GitHub integrations, bug triage, release notes |
| `finance` | `packs/finance/` | KYC/AML — transaction classification, ledger reconciliation, risk scoring, compliance HITL review, audit notification |
| `healthcare` | `packs/healthcare/` | Clinical intake — patient form ingest, anamnesis, Manchester triage classification, doctor Slack notification with HITL gate |
| `law` | `packs/law/` | Legal contract review — clause extraction, jurisprudence-grounded risk analysis, formal opinion (parecer), client email notification |
| `marketing` | `packs/marketing/` | Campaign production — brief analysis, competitor research, copy drafting, brand safety review, social publish with HITL gate |
| `support` | `packs/support/` | Support operations — intake, triage, knowledge lookup, escalation, and customer response workflows |
| `operations-sre` | `packs/operations-sre/` | Operations/SRE — incident triage, status updates, remediation coordination, and postmortem workflows |

Each vertical ships:
- `pack.yaml` — manifest (`vertical`, `version`, `displayName`, `depsPacks`)
- `agents.yaml` — agent declarations (`slug`, `name`, `systemPrompt`, `model`, `tools`, `ragSourceId`, `outputContract`)
- `flows/<slug>.yaml` — directed graph flows (nodes + edges, `FlowConfig` shape from `@agentskit/os-core`)
- `pipelines.yaml` — phase chains with blackboard `inputMapping`/`outputKey` and HITL `requireApproval` flags
- `triggers.yaml` — webhook/cron/email trigger declarations
- `connections.yaml` — connection stubs plus tenant-scoped `connectionRequirements`; `envVarHints` is legacy/dev fallback metadata only
- `fixtures/rag/` — RAG source markdown documents (where applicable)
- `fixtures/samples/` — sample input payloads (where applicable)
- `seeds/` — seed history and SQL seed files (where applicable)

## Public exports

```ts
import { REFERENCE_PACKS_DIR, REFERENCE_VERTICAL_IDS } from '@agentskit/pack-fixtures-reference'
import { loadPackFromDisk } from '@agentskit/pack-loader'

const pack = await loadPackFromDisk('finance', REFERENCE_PACKS_DIR)
```

- `REFERENCE_PACKS_DIR: string` — absolute path to the `packs/` directory shipped with this package. Resolves correctly whether the package is installed from npm or referenced via pnpm workspace.
- `REFERENCE_VERTICAL_IDS: readonly ['coding', 'finance', 'healthcare', 'law', 'marketing', 'support', 'operations-sre']` — the seven canonical vertical id strings.
- `ReferenceVerticalId` — union type derived from `REFERENCE_VERTICAL_IDS`.

## How pack-loader consumes this package

`loadPackFromDisk(vertical, REFERENCE_PACKS_DIR)` from `@agentskit/pack-loader`:
1. Reads `packs/<vertical>/pack.yaml` and validates it against `PackManifest` (Zod schema).
2. Reads and validates `agents.yaml`, `triggers.yaml`, `connections.yaml`, `pipelines.yaml`, `items.yaml`.
3. Reads and validates all `flows/<slug>.yaml` files via `PackFlowConfig` (re-export of `FlowConfig` from `@agentskit/os-core`).
4. Validates trigger configs against the `TriggerConfig` discriminated union.
5. Validates agent `outputContract` refs against the `@agentskit/agent-contracts` registry.
6. Runs cross-reference checks (agent slugs, flow ids, pipeline phase flow ids).
7. Returns a `PackBundle` aggregate.

The demo seed path calls `materialisePack(bundle, deps)` from `@agentskit/pack-loader`, which upserts the bundle into sidecar stores (agent store, flow store, pipeline store, trigger store, connection store). Gated by `AKOS_DEMO_PACKS=1` env var or `force: true` option.

## Common questions

> **How do I add a new reference vertical?**
> Create `packs/<vertical>/` with `pack.yaml`, `agents.yaml`, `flows/`, `pipelines.yaml`, `triggers.yaml`, and `connections.yaml` conforming to the schemas in `@agentskit/pack-loader/src/pack-schema.ts`. Add the new vertical id to `REFERENCE_VERTICAL_IDS` in `src/index.ts`. Add a hermetic smoke test in `tests/packs-<vertical>.test.ts` mirroring the existing per-vertical test files. Confirm with `loadPackFromDisk` in `tests/load-all-packs.test.ts`.

> **What are the canonical vertical ids?**
> `coding`, `finance`, `healthcare`, `law`, `marketing`, `support`, `operations-sre`. The `PackVerticalId` enum in `@agentskit/pack-loader` is the source of truth. The `REFERENCE_VERTICAL_IDS` export in this package must stay in sync with it.

> **Can I use these fixtures in production?**
> These are reference fixtures for development, demos, and tests. OEMs should fork and customise them rather than shipping them verbatim.

> **How should packs declare integrations now?**
> Add `connectionRequirements` in `connections.yaml` for tenant-facing setup.
> Use OAuth where supported, `installation` for GitHub App / Discord bot style
> installs, and `secret` for tenant vault keys such as Anthropic, Resend, SMTP,
> or provider API keys. Keep `envVarHints` only for local/dev fallback.

> **Where do runner-level (dry-run) tests live?**
> In `packages/os-headless/tests/satellite-<vertical>-flows.test.ts`. These use `createHeadlessRunner` and are separate from the structural gate here to avoid a circular dependency (`os-headless` → `pack-loader`/fixtures → `os-headless`).

Source: /raw/for-agents/packages/pack-fixtures-reference.md

### for-agents/packages/pack-loader.md

# packages/pack-loader

## Purpose

`@agentskit/pack-loader` is the runtime library that reads YAML pack bundles from disk, validates them with Zod schemas, cross-references internal ids, and materialises the result into live sidecar stores (agents, flows, pipelines, triggers, connections, kanban items).

It is consumed by:
- the `agentskit-os seed` CLI (`AKOS_DEMO_PACKS=1` gate or `--force`)
- the sidecar on workspace boot when a vertical pack is configured
- integration and unit tests that need a populated vertical store without a running sidecar

**Scope:** this package is a leaf dependency. `@agentskit/os-headless` depends on it; pack-loader does NOT depend on os-headless.

## Load / Validate / Materialise pipeline

```
disk: packs/<vertical>/
  pack.yaml           → PackManifest (required)
  agents.yaml         → PackAgentsFile (optional)
  flows/<slug>.yaml   → PackFlowConfig, one per file (optional dir)
  triggers.yaml       → PackTriggersFile (optional)
  connections.yaml    → PackConnectionsFile (optional)
  pipelines.yaml      → PackPipelinesFile (optional)
  items.yaml          → PackItemsFile (optional)

         │  loadPackFromDisk(vertical, baseDir)
         ▼
  1. fs.stat  — directory must exist (AK_PACK_NOT_FOUND)
  2. readYamlFile(pack.yaml, required:true)
       YAML.parse → PackManifest.safeParse → AK_PACK_INVALID on failure
  3. readYamlFile(agents/triggers/connections/pipelines/items, required:false)
       missing file → null (silently skipped)
       bad YAML / schema fail → AK_PACK_INVALID
  4. loadFlows(flows/)
       missing dir → [] (ENOENT → empty, not an error)
       non-ENOENT readdir error → AK_PACK_INVALID
  5. trigger config validated against safeParseTriggerConfig (os-core union)
  6. validatePackCrossRefs — throws AK_PACK_INVALID on:
       (a) flow agent node references slug not in agents.yaml
       (b) pipeline phase flowId not in flows/
       (c) trigger flowId not in flows/
       (d) item pipelineId not in pipelines.yaml
       (e) item columnId not a phase id on the referenced pipeline
       (f) agent outputContract ref not in the agent-contracts registry
         (ADR-0119 SEAM A — registry built from createDefaultAgentContractRegistry)
         → AK_PACK_INVALID

         │  PackBundle (in-memory aggregate)
         ▼

  materialisePack(pack, deps, { force?, origin? })
     Gate: skips unless AKOS_DEMO_PACKS=1 or opts.force === true
     Order: connections → agents → flows → pipelines → triggers → items
     Each upsert is isolated; a single failure increments errors without aborting
     All upserts failed (errors > 0 && material-count === 0) → AK_PACK_MATERIALISE_FAILED
```

## Public exports

### Functions

| Export | Signature | Notes |
|--------|-----------|-------|
| `loadPackFromDisk` | `(vertical: PackVerticalId, baseDir: string) => Promise<PackBundle>` | Full load+validate+xref pipeline. Throws `AK_PACK_NOT_FOUND` or `AK_PACK_INVALID`. |
| `materialisePack` | `(pack: PackBundle, deps: PackStoreDeps, opts?: MaterialiseOptions) => Promise<MaterialiseResult>` | Upserts every item. Gate: `AKOS_DEMO_PACKS=1` or `force:true`. Throws `AK_PACK_MATERIALISE_FAILED` if every material upsert fails. |
| `packExistsOnDisk` | `(vertical: PackVerticalId, baseDir: string) => Promise<boolean>` | Cheap probe: checks `packs/<vertical>/pack.yaml` access. |
| `clearDemoPackData` | `(deps: PackStoreDeps) => Promise<ClearDemoPackResult>` | Deletes all `origin='demo-pack'` rows across all five stores. Stores without `deleteByOrigin` report 0. |
| `validatePackCrossRefs` | `(agents, flows, pipelines, triggers, contractRefValidator?, items?) => void` | Throws `AK_PACK_INVALID` on any cross-reference violation. |
| `validateDepsPacks` | `(input: ValidateDepsPacksInput) => ValidateDepsPacksResult` | Warns (or throws if `STRICT_DEPS_PACKS=1`) when declared dependency packs are not yet loaded. |
| `parseCompositionManifest` | `(raw: unknown) => CompositionManifest` | Parses cross-vertical pipeline compositions. Throws `AK_PACK_INVALID` on schema failure. |

### Zod schemas

| Export | Purpose |
|--------|---------|
| `PackVerticalId` | Enum of valid verticals: `law`, `marketing`, `coding`, `healthcare`, `finance` |
| `PackManifest` | `pack.yaml` shape |
| `PackAgentsFile` | `agents.yaml` shape |
| `PackTriggersFile` | `triggers.yaml` shape |
| `PackConnectionsFile` | `connections.yaml` shape: legacy connection stubs plus tenant-scoped `connectionRequirements` |
| `PackPipelinesFile` | `pipelines.yaml` shape |
| `PackItemsFile` | `items.yaml` shape |
| `PackFlowConfig` | Re-export of `FlowConfig` from `@agentskit/os-core` |
| `CompositionManifestSchema` | Schema for `composition-manifest.json/.yaml` |

### Error classes

| Class | AK_* code | When thrown |
|-------|-----------|-------------|
| `PackNotFoundError` | `AK_PACK_NOT_FOUND` | Directory missing, not a directory, or required file absent |
| `PackInvalidError` | `AK_PACK_INVALID` | Bad YAML, schema violation, cross-reference failure, or trigger config parse failure |
| `PackMaterialiseError` | `AK_PACK_MATERIALISE_FAILED` | Every material upsert (agents + flows + pipelines) failed |

### Types

| Export | Description |
|--------|-------------|
| `PackBundle` | In-memory aggregate returned by `loadPackFromDisk` |
| `PackStoreDeps` | Dependency-injection bag: `agentStore`, `flowStore`, `pipelineStore`, `triggerStore`, `connectionStore`, optional `itemStore` |
| `MaterialiseOptions` | `{ force?: boolean; origin?: DemoPackOrigin }` |
| `MaterialiseResult` | `{ agentsUpserted, flowsUpserted, pipelinesUpserted, triggersUpserted, connectionsUpserted, itemsUpserted, errors }` |
| `MaterialisedAgent` | Shape of an agent row fed to `agentStore.upsert` |
| `MaterialisedFlow` | Alias for `PackFlowConfig` (flow row fed to `flowStore.upsert`) |
| `MaterialisedPipeline` | Pipeline row fed to `pipelineStore.upsert` |
| `MaterialisedTrigger` | Trigger row with typed `config: TriggerConfig` |
| `MaterialisedConnection` | Legacy connection row with `awaitingCredentials: true`; tenant setup requirements stay on the loaded `PackBundle` for UI/preflight consumers |
| `DemoPackOrigin` | `'demo-pack'` literal — origin tag applied to all materialised rows |
| `DEMO_PACK_ORIGIN` | Constant value `'demo-pack'` |
| `ClearDemoPackResult` | `{ agentsDeleted, flowsDeleted, pipelinesDeleted, triggersDeleted, connectionsDeleted }` |
| `ValidateDepsPacksInput` | `{ packId, depsPacks, loadedVerticals }` |
| `ValidateDepsPacksResult` | `{ ok: true }` or `{ ok: false; missing: string[] }` |
| `CompositionManifest` | Inferred type of `CompositionManifestSchema` |

## Environment variables

| Variable | Effect |
|----------|--------|
| `AKOS_DEMO_PACKS=1` | Enables `materialisePack` to run (gate) |
| `STRICT_DEPS_PACKS=1` | Makes `validateDepsPacks` throw instead of warn on missing deps |

## How pack-fixtures-reference feeds this

`packages/pack-fixtures-reference` ships the canonical YAML packs under `packs/<vertical>/`. The `agentskit-os seed` CLI resolves the `baseDir` to that package's `packs/` directory and calls `loadPackFromDisk` for each requested vertical, then `materialisePack` with the live stores.

Tests that need a populated store pass the `pack-fixtures-reference` `packs/` path (or a tmpdir fixture) to `loadPackFromDisk` and then wire in-memory store implementations to `materialisePack`. No sidecar process is required.

## Tenant connection requirements

`connections.yaml` now supports a `connectionRequirements` array alongside legacy
`connections` stubs. Requirements are the product-facing setup contract for
tenant-scoped OAuth connections, app installations, and vault-backed secrets.
Use `envVarHints` only for legacy/dev fallback metadata; do not present it as
the tenant setup path in product UI.

Supported requirement fields:

| Field | Purpose |
|---|---|
| `provider` | Provider id such as `slack`, `github`, `linear`, `discord`, `openrouter`, `gemini`, `anthropic`, `resend`, `smtp`. |
| `purpose` | Why the credential is needed, e.g. `send_message`, `repo_automation`, `email_send`, `llm_inference`. |
| `authModes` | Allowed setup paths: `oauth`, `secret`, `installation`, `platform`, `dev_env_fallback`. |
| `requiredFor` | Workflow/template/agent ids this requirement unlocks. |
| `requiredScopes` | OAuth scopes needed by the workflow. |
| `secretKeys` | Tenant vault keys needed for secret-backed providers. |
| `devEnvHints` | Optional local/dev fallback env names. |

## Writing tests

```typescript
import { loadPackFromDisk, materialisePack } from '@agentskit/pack-loader'

// In-memory store stub
const agentStore = { upsert: async (a) => { recorded.push(a) } }

// Load from pack-fixtures-reference
const bundle = await loadPackFromDisk('law', 'packages/pack-fixtures-reference/packs')
const result = await materialisePack(bundle, { agentStore, flowStore, ... }, { force: true })
```

## ADR references

- ADR-0119: agent-contracts output contract validation at pack-load time (SEAM A)
- ADR-0055: file-size budget — each module stays under 500 lines

## Common questions

> **What's the difference between `loadPackFromDisk` and `materialisePack`?**
> `loadPackFromDisk(vertical, baseDir)` reads + Zod-validates the YAML pack into an in-memory bundle (no side effects). `materialisePack(bundle, stores, opts)` writes that bundle into the live stores (agents, flows, …). Loading is pure; materialising mutates.

> **Why isn't materialise running in my environment?**
> `materialisePack` is gated behind `AKOS_DEMO_PACKS=1`. Without it the call is a no-op by design (seed/demo data must never auto-populate a production store). Set the env var for seed/demo flows.

> **How do I make missing pack dependencies fail loudly?**
> Set `STRICT_DEPS_PACKS=1` so `validateDepsPacks` throws instead of warning. Leave it unset in dev to get non-fatal warnings.

> **Where do the canonical packs live?**
> In `packages/pack-fixtures-reference/packs/<vertical>/`. The `agentskit-os seed` CLI and tests point `loadPackFromDisk`'s `baseDir` at that directory — see the section above.

Source: /raw/for-agents/packages/pack-loader.md

### for-agents/packages/pkw-test-fixtures.md

# packages/pkw-test-fixtures

## Purpose

Dev-only fixture library for pkw-series confidence and integration tests. Provides a deterministic stub runner, hermetic in-memory store bundle, HITL gate store, and minimal `FlowConfig`/`PipelineConfig`/`EventBus` builders so pkw tests stay hermetic and dependency-free. Never published to npm — `private: true`, `forAgentsExempt: true`.

## Public exports

### Stub runner

- `createStubRunner(opts?: StubRunnerOpts): StubPipelineFlowRunner` — factory for a deterministic `PipelineFlowRunner` compatible stub. Per-flowId outcomes are configured via `outcomesByFlowId`; per-flowId overrides (including async throws) via `behavior`.
- `StubRunnerOpts` — `{ outcomesByFlowId?, behavior? }` config type.
- `StubOutcomes` — `Record<string, string>` alias for per-key outcome values.
- `StubPipelineFlowRunner` — type of the returned runner: `{ runFlow(flow, opts): Promise<RunResult> }`.

### Gate store

- `makeGateStore(): MakeGateStoreResult` — returns `{ gateMap, gateStore }`. `gateStore` implements `InMemoryGateStore`; `gateMap` is the backing `Map<string, GateRow>` that tests mutate directly to approve or reject gates.
- `InMemoryGateStore` — `{ upsert(row): Promise<void>; get(id): Promise<GateRow | undefined> }`.
- `GateRow` — `{ status: GateStatus }`.
- `GateStatus` — `'pending' | 'approved' | 'rejected'`.
- `MakeGateStoreResult` — `{ gateMap: Map<string, GateRow>; gateStore: InMemoryGateStore }`.

### In-memory store bundle

- `createInMemoryStores(): InMemoryStoreBundle` — instantiates all seven in-memory store implementations from `@agentskit/os-storage` in one call; each call returns independent instances with no shared state.
- `InMemoryStoreBundle` — `{ flowStore, pipelineStore, runStore, artifactStore, hitlEscalationStore, hitlGateStore, integrationConnectionStore }`.

### Pipeline / flow builders

- `trivialFlow(id: string): FlowConfig` — minimal `FlowConfig` with a single `start` node; satisfies `HeadlessRunner` validation.
- `okResult(extras?: Record<string, unknown>): RunResult` — `{ status: 'completed', outcomes: Map<string, unknown>, executedOrder: [] }` with optional extra outcome entries.
- `pipelineWith(id: string, phases: ReadonlyArray<string | PipelinePhaseInput>): MinimalPipelineConfig` — builds a pipeline config from an ordered list of phase names (string) or `{ name, requireApproval? }` objects.
- `buildBus(): TestBusResult` — returns `{ events: CapturedEvent[], bus }` where `bus.publish` appends to `events`. Useful for asserting `EventBus` interactions without a real broker.
- `CapturedEvent` — `{ type: string; data: Record<string, unknown> }`.
- `TestBusResult` — `{ events: CapturedEvent[]; bus: { publish, subscribe, close } }`.
- `MinimalPipelineConfig` — minimal pipeline shape with `id`, `name`, and `phases[]` (each with `name`, `flowId`, `inlineFlow`, optional `requireApproval`).
- `PipelinePhaseInput` — `{ name: string; requireApproval?: boolean }`.

## Wired stores

None in src. The `createInMemoryStores` function wraps `InMemory*Store` classes from `@agentskit/os-storage`.

## Usage pattern

```ts
import { createStubRunner, makeGateStore, createInMemoryStores, trivialFlow, pipelineWith, buildBus } from '@agentskit/pkw-test-fixtures'

const runner = createStubRunner({
  outcomesByFlowId: { 'coding-prd': { prd: 'prd-stub' } },
})
const { gateMap, gateStore } = makeGateStore()
const stores = createInMemoryStores()
const { events, bus } = buildBus()
```

Approve all pending gates after a pipeline dispatches:
```ts
for (const [k, v] of gateMap.entries()) gateMap.set(k, { ...v, status: 'approved' })
```

## Common questions

> **Is this safe to import in production packages?**
> No. This is `private: true` and `devDependencies`-only. Only import it from test files.

> **When should I use `createStubRunner` vs wiring a real runner?**
> Always use `createStubRunner` in pkw unit/confidence tests that must be hermetic. Use a real runner only for end-to-end flow tests that need actual DAG execution.

> **How do I simulate a flow failure?**
> Use the `behavior` option with a function that throws:
> ```ts
> createStubRunner({ behavior: { 'flow-id': async () => { throw new Error('injected-failure') } } })
> ```

Source: /raw/for-agents/packages/pkw-test-fixtures.md

### for-agents/screens/admin-app.md

# Admin app — OEM control plane (`apps/admin`)
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Next.js OEM operator console (port 3041). Super-admin UI for tenant directory,
onboarding wizard, license, whitelabel, verticals, global pages/RBAC defaults,
models/packs catalogs, distribution, audit, compliance, and billing oversight.
Not an end-user fumadocs surface — operators run it via `pnpm dev:admin`.

## Human / operator reference

- `apps/admin/README.md` — run, Postgres path, env vars
- `apps/admin/lib/surface-registry.ts` — canonical route + integration state table

## Agent screen docs

Each routable admin surface has a `docs/for-agents/screens/admin-*.md` guide
linked from [`INDEX.md`](../INDEX.md) › Admin screens.

Query any screen:

```bash
pnpm docs:internal:query screen admin-tenants --agent
pnpm docs:internal:query app admin --agent
```

## Nav groups (`ADMIN_NAV_GROUPS`)

| Group | Sections |
|---|---|
| Tenant operations | tenants, license, billing-oversight, whitelabel, scim-oversight |
| Distribution | distribution |
| Platform config | brand, pages-rbac, models, packs, verticals, governance, members |
| Assurance | audit, compliance |
| Onboarding | onboard, onboarding-insights |

## Edge cases

- Routes like `/rbac` exist outside primary nav — see [`admin-rbac.md`](./admin-rbac.md).
- Tenant detail hub `/tenants/[orgId]` is read-only first pass — see
  [`admin-tenant-detail.md`](./admin-tenant-detail.md).
- Do not confuse desktop **Compliance** ([`compliance.md`](./compliance.md))
  with admin **Compliance operations** ([`admin-compliance.md`](./admin-compliance.md)).

Source: /raw/for-agents/screens/admin-app.md

### for-agents/screens/admin-audit.md

# Admin screen — admin-audit
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Admin compliance hub: legal-hold placement/release, DSAR (Data Subject Access Request) creation/listing, and per-tenant data-retention policy configuration. Backed by `os-headless` compliance handlers and `os-storage` legal-hold store.

## Route + RBAC

- **Route:** `/admin/audit`
- **Read (list holds, list DSARs, get retention):** `audit:read` cap.
- **Write (place/release hold, create DSAR, save retention):** `compliance:write` / `audit:write` caps (oem-owner, oem-admin).

## Server actions (`apps/admin/app/audit/audit-actions.ts`)

| Action | Cap | Audit event |
|---|---|---|
| `auditListLegalHolds` | `audit:read` | _(none)_ |
| `auditPlaceLegalHold` | `compliance:write` | `audit.legalHold.place` |
| `auditReleaseLegalHold` | `compliance:write` | `audit.legalHold.release` |
| `auditListDsar` | `audit:read` | _(none)_ |
| `auditCreateDsar` | `compliance:write` | `audit.dsar.create` |
| `auditGetRetentionPolicy` | `audit:read` | _(none)_ |
| `auditSaveRetentionPolicy` | `audit:write` | `audit.retention.save` |

Storage: `InMemoryLegalHoldStore` (from `@agentskit/os-storage`), `createInMemoryDsarStore` (from `@agentskit/os-headless`). Both are module-level singletons; `__setAuditActionsStoresForTesting` seam swaps them in vitest.

Default retention: `runsDays: 90`, `artifactsDays: 365`, `auditDays: 2555` (7 years), `kbDays: 365`.

## Key components

| Component | File |
|---|---|
| `AuditPage` — client root | `audit-page.tsx` |
| `LedgerSearch` — audit log search | `ledger-search.tsx` |
| `LegalHoldEditor` — hold place/release form | `legal-hold-editor.tsx` |
| `DsarMgmt` — DSAR list + create | `dsar-mgmt.tsx` |
| `RetentionEditor` — retention policy form | `retention-editor.tsx` |

## Source dir

`apps/admin/app/audit/`

## Audit events emitted

`audit.legalHold.place`, `audit.legalHold.release`, `audit.dsar.create`, `audit.retention.save` — all section `audit`, via `AdminAuditStore`.

## Edge cases

- `auditPlaceLegalHold` requires all of `scope.value`, `reason`, `placedBy` — returns `{ ok: false }` otherwise.
- `auditSaveRetentionPolicy` rejects if any day value is ≤ 0.
- `revalidatePath('/audit')` called after every write.

## Related

- SU5.8 PR #3108, ENT-7 (#1716, #1803, #1823)
- `@agentskit/os-headless` — `createComplianceHandlers`, `createInMemoryDsarStore`
- `@agentskit/os-storage` — `InMemoryLegalHoldStore`
- Desktop compliance screen: `docs/for-agents/screens/compliance.md`

Source: /raw/for-agents/screens/admin-audit.md

### for-agents/screens/admin-billing-oversight.md

# Admin screen — admin-billing-oversight
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Cross-tenant billing oversight route. Intended to show provider status, invoices,
payment failures, grace periods, and entitlement impact. May render empty until
cloud billing bindings are configured.

## Route + scope

| Route | Nav section | Scope | Integration |
|---|---|---|---|
| `/billing-oversight` | `billing-oversight` | `tenant` | `empty-shell` |

## Data sources

- Billing directory / cloud client

## Source dir

- `apps/admin/app/billing-oversight/`
- `apps/admin/lib/surface-registry.ts` (`id: billing-oversight`)

## Related

- Desktop Cost / Billing tab: [`cost.md`](./cost.md)
- License admin: [`admin-license.md`](./admin-license.md)

Source: /raw/for-agents/screens/admin-billing-oversight.md

### for-agents/screens/admin-brand.md

# Admin screen — admin-brand
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Global brand defaults for OEM deployments. Edits platform-wide whitelabel
tokens before tenant-specific overrides. Tenant branding belongs in tenant
context (`/whitelabel`, `/tenants/[orgId]`).

## Route + RBAC

| Route | Nav section | Scope |
|---|---|---|
| `/brand` | `brand` | `global` |

## Data sources

- `TenantConfigStore`
- Brand server actions under `apps/admin/app/brand/`

## Source dir

- `apps/admin/app/brand/`
- `apps/admin/lib/surface-registry.ts` (`id: brand`)

## Notes

Follow-up #4489 — reframe as global defaults; keep tenant whitelabel in tenant hub.

Source: /raw/for-agents/screens/admin-brand.md

### for-agents/screens/admin-catalogs.md

# Admin screen — admin-catalogs
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Models and Packs are global catalog surfaces for OEM operators. `/models` selects
allowed LLM catalog entries for the current tenant config; `/packs` selects
vertical pack manifests for a target tenant.

## Route + RBAC

| Route | Read cap | Draft cap | Publish cap |
|---|---|---|---|
| `/models` | `models:read` | `models:write` | `models:manage` |
| `/packs` | `packs:read` | `packs:write` | `packs:manage` |

## Cloud Catalog Readiness

When `AKOS_CLOUD_URL` is set, the pages prefer cloud-backed global catalogs:

- Models: `GET /v1/admin/catalog/models`
- Packs: `GET /v1/admin/packs`

Both calls require `AKOS_CLOUD_SERVICE_TOKEN`. If cloud catalog access fails, the
server page must not crash. It renders a readiness banner with the issue kind,
AK error code, HTTP status when available, and the operator action. The table
falls back to the honest local seed so navigation remains usable while support
fixes the cloud integration.

Standalone local mode with no `AKOS_CLOUD_URL` continues to render the local seed
without a warning.

## Source Dir

- `apps/admin/app/models/`
- `apps/admin/app/packs/`
- `apps/admin/lib/catalog-readiness.ts`
- `apps/admin/components/catalog-readiness-banner.tsx`

## Tests

- `apps/admin/tests/catalog-readiness.test.ts`
- `apps/admin/tests/catalog-oversight/*`

Source: /raw/for-agents/screens/admin-catalogs.md

### for-agents/screens/admin-compliance-telemetry.md

# Admin screen — admin-compliance-telemetry
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Per-org telemetry event viewer under the compliance tab. Operators filter run-telemetry events by org, date range, and event kind to support compliance investigations or usage audits. Data is fetched from the cloud control plane (`GET /v1/telemetry/runs`).

## Route + RBAC

- **Route:** `/admin/compliance/telemetry`
- **Read:** `compliance:read` cap (oem-viewer and above).

No write actions — this is a read-only surface.

## Server actions (`apps/admin/app/compliance/telemetry/telemetry-actions.ts`)

| Action | Cap | Notes |
|---|---|---|
| `listTelemetryEvents` | `compliance:read` | Calls `GET ${AKOS_CLOUD_URL}/v1/telemetry/runs` with `orgId`, `from`, `to`, `kind` query params. Responses validated via `TelemetryRowSchema` (Zod). |

Env var: `AKOS_CLOUD_URL` (defaults to `http://127.0.0.1:4090` in dev). HTTP response uses `cache: 'no-store'`.

## Key components

| Component | File |
|---|---|
| `TelemetryView` — table + filters | `telemetry-view.tsx` |

Schemas / types: `telemetry-defaults.ts` (no `'use server'`). Includes `TelemetryRowSchema`, `TelemetryListResult`, `TelemetryListParams`.

## Source dir

`apps/admin/app/compliance/telemetry/`

## Audit events emitted

None — read-only surface.

## Edge cases

- Cloud API non-OK response → `{ ok: false, error: 'Cloud API error (<status>)' }`.
- Network failure → `{ ok: false, error: 'Failed to reach cloud API.' }`.
- Snake_case → camelCase mapping applied for `orgId`, `runId`, `recordedAt` (cloud API may return either form).
- Items that fail `TelemetryRowSchema.safeParse` are silently dropped (flatMap returns `[]`).

## Related

- SU3.6 `4b57ecfe5`, issue #2983
- `apps/admin/app/compliance/` — parent compliance route (DSAR, legal-hold, GC, prune panels)
- `AKOS_CLOUD_URL` env var

Source: /raw/for-agents/screens/admin-compliance-telemetry.md

### for-agents/screens/admin-compliance.md

# Admin screen — admin-compliance
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Tenant-scoped compliance operations for OEM operators: legal holds, DSAR queue,
and retention pruning controls. Distinct from the desktop **Compliance** screen
(`compliance.*` evidence export) and from read-only
[`admin-compliance-telemetry`](./admin-compliance-telemetry.md).

## Route + scope

| Route | Nav section | Scope | Mutation |
|---|---|---|---|
| `/compliance` | `compliance` | `tenant` | `mixed` |

## Data sources

- DSAR store
- Legal hold store
- Retention / prune server actions

## Source dir

- `apps/admin/app/compliance/`
- `apps/admin/lib/surface-registry.ts` (`id: compliance`)

## Notes

Follow-up #4494 — retention should derive from tenant vertical with explicit overrides.

Source: /raw/for-agents/screens/admin-compliance.md

### for-agents/screens/admin-dashboard.md

# Admin screen — admin-dashboard
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

OEM control-plane landing at `/`. Shows live tenant and audit counts and
section launchers. Read-only overview — not yet a tenant-first operating hub.

## Route + scope

| Route | Scope | Integration |
|---|---|---|
| `/` | `system` | `partial` |

## Data sources

- `OrgDirectoryStore.listOrgs`
- `AdminAuditStore.list`

## Source dir

- `apps/admin/app/page.tsx`
- `apps/admin/lib/surface-registry.ts` (`id: dashboard`)

## Notes

Follow-up #4487 — flatten launcher into tenant-first navigation; prefer
`/tenants` and `/tenants/[orgId]` for operator workflows.

Source: /raw/for-agents/screens/admin-dashboard.md

### for-agents/screens/admin-distribution.md

# Admin screen — admin-distribution
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

OEM distribution pipeline control. Operators select a tenant + brand-kit version and trigger a `workflow_dispatch` event on the `rebrand-build.yml` GitHub Actions workflow. The page also lists the last 20 GHA runs with status/conclusion so operators can track build history without leaving the admin console.

## Route + RBAC

- **Route:** `/admin/distribution`
- **Read build history:** `distribution:read` cap (oem-viewer and above).
- **Trigger build:** `distribution:write` cap (oem-owner, oem-admin).

## Server actions (`apps/admin/app/distribution/distribution-actions.ts`)

| Action | Cap | Audit event |
|---|---|---|
| `triggerRebrandBuild` | `distribution:write` | `distribution.build.trigger` |
| `listBuildRuns` | `distribution:read` | _(none)_ |

External dependency: GitHub Actions API (`api.github.com`). Configured via `AKOS_GHA_TOKEN` (PAT) and `AKOS_GHA_REPO` (e.g. `owner/repo`). Missing env vars return a typed error; no uncaught throws.

`triggerRebrandBuild` dispatches to `rebrand-build.yml` on `main` with inputs `{ tenantId, brandKitVersion }`, then polls for the resulting run ID (up to ~3 s). GHA responds `204 No Content` on success.

`listBuildRuns` fetches the last 20 runs with `next.revalidate: 30` (Next.js cache).

## Key components

| Component | File |
|---|---|
| `DistributionPage` — page shell | `distribution-page.tsx` |
| `DistributionEditor` — trigger form | `distribution-editor.tsx` |
| `BuildTriggerDialog` — confirm dialog | `build-trigger-dialog.tsx` |
| `BuildHistory` — run history table | `build-history.tsx` |
| `ChannelsList` — channel summary | `channels-list.tsx` |

## Source dir

`apps/admin/app/distribution/`

## Audit events emitted

`distribution.build.trigger` — payload: `{ targetTenantId, brandKitVersion, runId }` — section `distribution`.

## Edge cases

- `brandKitVersion` must match `/^\d+\.\d+\.\d+/` (semver prefix); rejects otherwise.
- GitHub `204` is the success status — any other code returns a typed error with the HTTP body.
- Run-ID polling is best-effort; returns `0` if the run doesn't appear within ~3 s (non-fatal — UI still shows success).
- `AKOS_GHA_TOKEN` / `AKOS_GHA_REPO` missing → `AK_DISTRIBUTION_TOKEN_MISSING` / `AK_DISTRIBUTION_REPO_MISSING`.

## Related

- SU5.7 PR #3115, issue #3001
- SU7.10 `7c3906721` — `rebrand-build.yml` workflow definition

Source: /raw/for-agents/screens/admin-distribution.md

### for-agents/screens/admin-governance.md

# Admin screen — admin-governance
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Global governance defaults for OEM operators — workspace isolation policy and
platform-wide governance configuration. Tenant and vertical overrides need
clear separation from this route.

## Route + scope

| Route | Nav section | Scope | Mutation |
|---|---|---|---|
| `/governance` | `governance` | `global` | `writes` |

## Data sources

- Governance server actions
- Workspace isolation policy stores

## Source dir

- `apps/admin/app/governance/`
- `apps/admin/lib/surface-registry.ts` (`id: governance`)

## Related

- Desktop Access screen: [`governance.md`](./governance.md)
- RBAC matrix (route-only): [`admin-rbac.md`](./admin-rbac.md)

Source: /raw/for-agents/screens/admin-governance.md

### for-agents/screens/admin-license.md

# Admin screen — admin-license
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Multi-org license lifecycle manager. Operators issue, renew, revoke, update seat counts, and override plan tiers for any tenant org. Backed by `LicenseService` and `SubscriptionStore`.

## Route + RBAC

- **Route:** `/admin/license`
- **Read:** `license:read` cap.
- **Write (issue / renew / revoke / seats / plan):** `license:write` cap (oem-owner, oem-admin).

## Server actions (`apps/admin/app/license/license-actions.ts`)

| Action | Description | Audit event |
|---|---|---|
| `issueOrgLicense` | Issue or re-issue signed envelope for an org | `license.issue` |
| `renewOrgLicense` | Renew within 14-day window | `license.renew` |
| `revokeLicense` | Cancel subscription (`SubscriptionStore.setState('cancelled')`) | `license.revoke` |
| `updateSeats` | Re-issue with new seat count (requires active sub) | `license.updateSeats` |
| `setPlanOverride` | Re-issue with new plan tier + re-activate if cancelled | `license.setPlanOverride` |

Storage: `LicenseService` (from `@agentskit/os-license/service`), `SubscriptionStore`, `OrgDirectoryStore.listOrgs / getOrg`.

## Key components

| Component | File |
|---|---|
| `LicensePage` (page shell) | `license-page.tsx` |
| `LicenseList` — org×license table | `license-list.tsx` |
| `LicenseIssueDialog` — issue/re-issue form | `license-issue-dialog.tsx` |
| `InlineSeatsEditor` — inline seat update | `inline-seats-editor.tsx` |
| `InlinePlanEditor` — inline plan override | `inline-plan-editor.tsx` |

## Source dir

`apps/admin/app/license/`

## Audit events emitted

`license.issue`, `license.renew`, `license.revoke`, `license.updateSeats`, `license.setPlanOverride` — all appended via `AdminAuditStore`, section `license`.

## Edge cases

- `updateSeats` rejects if subscription is not `active`.
- `setPlanOverride` silently re-activates a cancelled sub to allow the override.
- `issueOrgLicense` activates the subscription before issuing.
- `revalidatePath('/license')` is called after every mutation.

## Related

- SU5.5 `8c54b2638`, issue #2999
- `@agentskit/os-license/service` — envelope sign/verify
- `apps/admin/lib/license.ts` — service + store wiring

Source: /raw/for-agents/screens/admin-license.md

### for-agents/screens/admin-members.md

# Admin screen — admin-members
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

OEM admin membership management. Invite new admin users by email, remove existing members, change their role, inspect cloud sessions, force logout operators, and toggle per-tenant MFA enforcement.

## Route + RBAC

- **Route:** `/admin/members`
- **All mutations:** `members:manage` cap (oem-owner, oem-admin).

Valid roles: `oem-owner`, `oem-admin`, `oem-viewer`.

## Server actions (`apps/admin/app/members/actions.ts`)

| Action | Description | Audit event |
|---|---|---|
| `inviteMember` | Create account + send invite email via `EmailSender` | `members.invite` |
| `removeMember` | Delete member from credential store | `members.remove` |
| `setMemberRole` | Update role in credential store | `members.role.update` |
| `listMemberSessions` | Read cloud active sessions for an operator email via `/api/admin/sessions/:email` | Cloud emits `admin.sessions.listed` |
| `revokeMemberSessions` | Force logout every cloud session for an operator email via `/api/admin/sessions/:email` | Cloud emits `admin.sessions.revoked` |
| `setTenantMfaEnforce` | Toggle TOTP enforcement on the tenant | `members.mfa-enforce.update` |

Storage: `CredentialStore.addMember / removeMember / setRole / setTenantMfaEnforce` (from `lib/auth/credential-store.ts`). Invite email delivered via `EmailSender` port — console sink in dev, Resend in prod (`AKOS_EMAIL_SENDER` convention).

Email delivery failure is **non-fatal**: the member row is created and a separate `members.invite.email-failed` audit event is recorded; the operator can re-send.

Cloud sessions are cloud-backed only. `listMemberSessions` and `revokeMemberSessions` use `AKOS_CLOUD_URL` plus `AKOS_CLOUD_ADMIN_SESSIONS_TOKEN` (preferred) or `AKOS_CLOUD_SERVICE_TOKEN` (compat fallback); without cloud config the UI shows an unavailable state instead of pretending a logout happened. Revocation is audited by the cloud admin sessions route, not the local admin ledger.

## Key components

| Component | File |
|---|---|
| `MembersPage` (page shell) | `members-page.tsx` |
| `MembersEditor` — invite form, member table, role changes, removal, cloud session lookup, forced logout | `members-editor.tsx` |

## Source dir

`apps/admin/app/members/`

## Audit events emitted

`members.invite`, `members.invite.email-failed`, `members.remove`, `members.role.update`, `members.mfa-enforce.update` — appended via `AdminAuditStore`, section `members`. Cloud forced logout emits `admin.sessions.revoked` in the cloud auth audit sink.

## Edge cases

- `removeMember` refuses to remove the session's own `userId`.
- `setMemberRole` rejects unknown roles (only `oem-owner | oem-admin | oem-viewer` accepted).
- Forced logout rejects invalid email before calling cloud and surfaces cloud errors such as `reauth_required`.
- MFA enforcement: when enabled, users without a TOTP secret are redirected to `/auth/totp-enroll` at sign-in.

## Related

- SU5.6 `5fea82ccd`, issue #3000
- TOTP enrolment: `apps/admin/app/(auth)/totp-enroll/`
- Email: `apps/admin/lib/email-sender.ts`

Source: /raw/for-agents/screens/admin-members.md

### for-agents/screens/admin-onboarding-insights.md

# Admin screen — admin-onboarding-insights
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Read-only aggregate diagnostics for OEM tenant onboarding wizard events.
Surfaces `onboarding.*` audit entries across tenants — not a primary nav
destination; prefer tenant detail or Assurance grouping.

## Route + scope

| Route | Nav section | Scope | Mutation |
|---|---|---|---|
| `/onboarding-insights` | `onboarding-insights` | `onboarding` | `none` (read-only) |

## Data sources

- `AdminAuditStore.list` filtered for `onboard` / `onboarding.*` events

## Source dir

- `apps/admin/app/onboarding-insights/`
- `apps/admin/lib/surface-registry.ts` (`id: onboarding-insights`)

## Related

- Wizard route: [`admin-onboarding.md`](./admin-onboarding.md)

Source: /raw/for-agents/screens/admin-onboarding-insights.md

### for-agents/screens/admin-onboarding.md

# Admin screen — admin-onboarding
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

`/onboard` is the OEM tenant onboarding wizard. It orchestrates tenant creation,
brand draft/publish, license issuance, and optional distribution build trigger.
`/onboarding-insights` shows aggregate operational signals from that same Admin
wizard.

## Source Of Truth

Onboarding Insights reads Admin audit rows from section `onboard` with actions
`onboarding.*`. It must not read desktop/headless `onboarding.insights.*`, which
belongs to the local desktop/copilot onboarding flow.

Events emitted by the wizard:

- `onboarding.started`
- `onboarding.step_success`
- `onboarding.step_failure`
- `onboarding.build_skipped`
- `onboarding.completed`

Payloads include `{ event, step, targetTenantId?, error? }`. `targetTenantId`
appears once a tenant exists.

## Source Dir

- `apps/admin/app/onboard/`
- `apps/admin/app/onboarding-insights/`
- `apps/admin/lib/admin-onboarding-insights.ts`

## Tests

- `apps/admin/tests/admin-onboarding-insights.test.ts`

Source: /raw/for-agents/screens/admin-onboarding.md

### for-agents/screens/admin-pages-rbac.md

# Admin screen — admin-pages-rbac
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Global **pages and RBAC defaults** editor for OEM operators. Configures the
tenant-wide page allowlist, claim-to-page mapping, and SSO section visibility
before per-tenant overrides. Distinct from the route-only
[`admin-rbac.md`](./admin-rbac.md) matrix at `/rbac`.

## Route + RBAC

| Route | Nav section | Scope | Caps |
|---|---|---|---|
| `/pages-rbac` | `pages-rbac` | `global` | read: authenticated; write/publish: `pages-rbac:write` |

## Data sources

- `TenantConfigStore` draft/active config
- `pages-rbac` server actions (`apps/admin/app/pages-rbac/`)

## Key surfaces

- Page allowlist checkboxes (essential pages cannot be hidden via denylist — ADR
  vertical-pages-rbac guard)
- SSO / OIDC / SAML / SCIM mapping rows
- Publish pipeline to make draft defaults live

## Source dir

- `apps/admin/app/pages-rbac/pages-rbac-editor.tsx`
- `apps/admin/lib/surface-registry.ts` (`id: pages-rbac`)

## Related

- Role matrix (route-only): [`admin-rbac.md`](./admin-rbac.md)
- Global governance defaults: [`admin-governance.md`](./admin-governance.md)
- Desktop Access screen: [`governance.md`](./governance.md)

Source: /raw/for-agents/screens/admin-pages-rbac.md

### for-agents/screens/admin-preview-as.md

# Admin screen — admin-preview-as
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Tenant impersonation preview. Operators select a tenant and receive a signed impersonation token for the Web read-only preview handler. The admin embeds the Web preview route in a sandboxed iframe so they can verify tenant context without switching accounts.

Every impersonation start is audit-logged. The token is forced to `scope:read-only` regardless of the admin's role.

## Route + RBAC

- **Route:** `/admin/preview-as`
- **All actions:** `preview-as:read` cap (oem-viewer and above).

## Server actions (`apps/admin/app/preview-as/preview-actions.ts`)

| Action | Cap | Audit event |
|---|---|---|
| `startPreview` | `preview-as:read` | `impersonation.start` |

`startPreview` calls `issueImpersonationToken` (`lib/auth/impersonation.ts`) with `{ actor, tenantId, target }`. Returns `{ url }`; the raw token is only embedded as the `impersonate` query param.

URL formats:
- `web` → `${AKOS_WEB_BASE_URL}/app/preview-readonly?impersonate=<token>&tenant=<tenantId>` (default base: `http://127.0.0.1:3031`)
- `desktop` → disabled until the desktop deep-link handler exists; `startPreview(..., 'desktop')` returns `ok:false`.

Env vars: `AKOS_WEB_BASE_URL`, `AKOS_PREVIEW_IMPERSONATION_SECRET` (preferred shared Admin/Web preview secret), `AKOS_ADMIN_SESSION_SECRET` (fallback for legacy Admin-only signing).

Web consumes preview tokens in `apps/web/app/app/preview-readonly/page.tsx` via `apps/web/lib/preview-impersonation.ts`. The page validates HS256 signature, `target: 'web'`, `scope: 'read-only'`, expiry, and tenant hint before rendering. Mutating product surfaces are not mounted in preview mode.

## Key components

| Component | File |
|---|---|
| `PreviewAsPage` — page shell | `preview-as-page.tsx` |
| `TenantPicker` — tenant select dropdown | `tenant-picker.tsx` |
| `PreviewFrame` — iframe for web target | `preview-frame.tsx` |

## Source dir

`apps/admin/app/preview-as/`

## Audit events emitted

`impersonation.start` — payload: `{ actor, targetTenantId, targetApp, ts }` — section `tenants`, via `AdminAuditStore`.

## Edge cases

- `tenantId` must be non-empty; returns `{ ok: false }` otherwise.
- `target` must be `'web'` or `'desktop'`; any other value returns an error.
- Desktop deep-link wiring is not available yet; the UI shows Desktop as unavailable instead of generating a success URL.

## Related

- SU7.9 PR #3107, issue #3020
- `apps/admin/lib/auth/impersonation.ts` — token issuance
- `apps/web/lib/preview-impersonation.ts` — Web token validation
- `AKOS_WEB_BASE_URL`, `AKOS_PREVIEW_IMPERSONATION_SECRET` env vars

Source: /raw/for-agents/screens/admin-preview-as.md

### for-agents/screens/admin-rbac.md

# Admin screen — admin-rbac
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Role × capability matrix editor for the admin tenant's `RuntimeConfig.rbac.roles`. Operators assign per-role capability sets that the sidecar enforcer reads. A `SimulateAs` panel lets the operator test the effective capability set for any role without applying changes.

## Route + RBAC

- **Route:** `/rbac` (route-only — not in primary admin nav; linked from governance tooling)
- **Read:** any authenticated admin session.
- **Write (save matrix):** `pages-rbac:write` cap (oem-owner, oem-admin).

## Server actions (`apps/admin/app/rbac/rbac-actions.ts`)

| Action | Cap | Notes |
|---|---|---|
| `setRoleMatrix` | `pages-rbac:write` | Validates via `RoleMatrixZ`, merges into `RuntimeConfig.rbac.roles`, saves as draft via `TenantConfigStore.saveDraft` |

The matrix shape is `Record<string, string[]>` (role → capabilities list). Stored as `{ pages: '*', capabilities: string[] }` in `RuntimeConfig.rbac.roles` so the existing sidecar RBAC enforcement path reads it transparently.

Pure helpers (types, Zod schema, defaults): `rbac-defaults.ts`.

Navigation visibility helper: `apps/admin/lib/auth/nav-visibility.ts`.
The admin shell and dashboard Jump to grid must use this helper instead of
reading `SECTIONS`/`ADMIN_NAV_GROUPS` directly. It checks the canonical
`canReadSection(role, section)` matrix and fails closed for nav sections that
do not have a matching RBAC section, so visual affordances cannot drift ahead
of `requireCap` enforcement.

## Key components + data-testid hooks

| Component | File |
|---|---|
| `RbacPage` — client root | `rbac-page.tsx` |
| `MatrixEditor` — role × cap checkbox grid | `matrix-editor.tsx` |
| `SimulateAs` — read-only effective-caps panel | `simulate-as.tsx` |

Unsaved-changes hook (`useUnsavedChanges`) warns on navigation when the matrix is dirty and not yet saved.

## Source dir

`apps/admin/app/rbac/`

## Audit events emitted

None directly from `setRoleMatrix` — the draft is stored via `TenantConfigStore` which records its own metadata. Deploy the draft with a subsequent publish action to make it live (shared `publishWhitelabel` / `TenantConfigStore.publish` pattern).

## Edge cases

- `setRoleMatrix` returns `{ ok: false, error: 'invalid-matrix', issues }` on Zod failure.
- Base config resolution: draft → active → hardcoded `DEFAULT_RUNTIME`.
- `revalidatePath('/rbac')` called on success.

## Related

- SU5.4 `f37ab4a25`, issue #2998
- `@agentskit/os-whitelabel` — `RuntimeConfig.rbac`
- `apps/admin/lib/auth/rbac.ts` — cap definitions + enforcement
- Desktop RBAC hardening: RBAC-HITL-100 plan (#1553)

Source: /raw/for-agents/screens/admin-rbac.md

### for-agents/screens/admin-scim-oversight.md

# Admin screen — admin-scim-oversight
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Read-only cross-tenant SCIM directory oversight for OEM operators. Surfaces
provisioning sync health without mutating IdP configuration from this route.

## Route + scope

| Route | Nav section | Scope | Mutation |
|---|---|---|---|
| `/scim-oversight` | `scim-oversight` | `tenant` | `none` (read-only) |

## Data sources

- SCIM directory / cloud client bindings

## Source dir

- `apps/admin/app/scim-oversight/`
- `apps/admin/lib/surface-registry.ts` (`id: scim-oversight`)

## Notes

Launch from tenant detail when debugging a single tenant's SCIM posture.

Source: /raw/for-agents/screens/admin-scim-oversight.md

### for-agents/screens/admin-sign-in.md

# Admin screen — admin-sign-in
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Unified admin sign-in page. Renders cloud SSO when `AKOS_CLOUD_URL` + `AKOS_CLOUD_SSO_SECRET` are both set, plus the first-operator bootstrap form only while the bootstrap token is configured and not yet consumed. Hidden sections stay hidden rather than disabled — no dead-end UI states.

## Route + RBAC

- **Route:** `/sign-in`
- **No RBAC gate** — unauthenticated entry point.

The legacy `/signin` path remains for backwards compatibility and redirects to `/sign-in`, preserving a safe internal `callback` query value when present.

## Authentication flows

| Flow | Entry component | API route |
|---|---|---|
| SSO (SAML / OIDC) | `SsoButton` (`app/sign-in/sso-button.tsx`) | `GET /api/auth/sso/initiate` → `GET /api/auth/sso/callback` |
| First-operator bootstrap | `BootstrapSigninForm` (`app/sign-in/bootstrap-signin-form.tsx`) | `POST /api/auth/bootstrap` |
| TOTP enrolment (post-sign-in) | _(redirect)_ | `POST /api/auth/totp/begin` + `/api/auth/totp/confirm` |

SSO configured check: `Boolean(process.env.AKOS_CLOUD_URL && process.env.AKOS_CLOUD_SSO_SECRET)`.

SSO callback path: `/api/auth/sso/callback` — the route that verifies the cloud-signed JWT and mints the admin session cookie. The earlier `/__sign-in-callback` placeholder was a dead route (cloud redirected the browser into a middleware bounce back to `/sign-in` with no session); fixed in #4744 Fase 1 / #4707.

Bootstrap visibility: `isBootstrapAvailable()` checks that `AKOS_ADMIN_BOOTSTRAP_TOKEN` is set, production has durable admin DB state, and the audit ledger has no prior `auth.bootstrap.consume` row.

Return path handling: `/sign-in?callback=<path>` passes the normalized callback into `BootstrapSigninForm`, so first-operator bootstrap returns to the originally requested protected route. `/signin?callback=<path>` redirects to `/sign-in?callback=<path>` after the same normalization. Callback values are sanitized by `safeSignInCallback()` and only safe internal paths are accepted; external URLs, protocol-relative values, and malformed values fall back to `/`.

## Key components

| Component | File |
|---|---|
| `SignInPage` — server component page | `app/sign-in/page.tsx` |
| `SsoButton` — SSO initiate button | `app/sign-in/sso-button.tsx` |
| `BootstrapSigninForm` — one-time first-operator token form | `app/sign-in/bootstrap-signin-form.tsx` |
| TOTP enrolment page | `app/(auth)/totp-enroll/page.tsx` |

i18n keys: `signIn.eyebrow`, `signIn.h1`, `signIn.lead`, `signIn.leadWithSso`, `signIn.ssoSectionLabel`, `signIn.bootstrapSectionLabel`, `signIn.orDivider`.

## Source dir

`apps/admin/app/sign-in/`

## Audit events emitted

None directly from the page. Auth API routes record sign-in events independently.

## Edge cases

- SSO section hidden (not disabled) when `AKOS_CLOUD_URL` or `AKOS_CLOUD_SSO_SECRET` is absent.
- Bootstrap is fail-closed in production when no durable admin database is configured.
- Bootstrap callback preserves safe internal paths, including query and hash fragments, and falls back to `/` for unsafe values.
- MFA enforcement: when the tenant has MFA required and the user lacks a TOTP secret, they are redirected to `/auth/totp-enroll` after password verification.

## Related

- SU5.9 `cef92acc6`
- `apps/admin/app/api/auth/` — local, SSO initiate/callback, TOTP begin/confirm routes
- `apps/admin/lib/auth/` — session, credential store, RBAC

Source: /raw/for-agents/screens/admin-sign-in.md

### for-agents/screens/admin-tenant-detail.md

# Admin screen — admin-tenant-detail
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Tenant operating hub at `/tenants/[orgId]`. Read-only first pass that centralises
links to license, billing, distribution, branding, access, vertical, compliance,
and audit domains for one org. Deeper mutation wiring lands in follow-up slices.

## Route + scope

| Route | Scope | Integration |
|---|---|---|
| `/tenants/[orgId]` | `tenant` | `partial` (read-only hub) |

## Data sources

- `OrgDirectoryStore.getOrg`
- Follow-on stores per domain (license, billing, brand, etc.)

## Source dir

- `apps/admin/app/tenants/[orgId]/`
- `apps/admin/lib/surface-registry.ts` (`id: tenant-detail`)

## Related

- Tenant directory: [`admin-tenants.md`](./admin-tenants.md)
- Preview as tenant: [`admin-preview-as.md`](./admin-preview-as.md)

Source: /raw/for-agents/screens/admin-tenant-detail.md

### for-agents/screens/admin-tenants.md

# Admin screen — admin-tenants
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

OEM control-plane tenant management. Lists all orgs; allows creating, retrying cloud provisioning, inviting members to, suspending/resuming, and deleting tenants. Delete queues a DSAR erasure request (ENT-7 pattern) before removing the tenant from the admin list.

## Route + RBAC

- **Route:** `/tenants` (tenant detail: `/tenants/[orgId]`)
- **Read:** any authenticated admin session.
- **Create / invite:** `tenants:write` cap (oem-owner, oem-admin).
- **Suspend / resume / delete:** `tenants:manage` cap (oem-owner only).

## Server actions (`apps/admin/app/tenants/tenant-actions.ts`)

| Action | Cap required | Audit event |
|---|---|---|
| `createTenant` | `tenants:write` | `tenants.create` |
| `retryTenantCloudProvisioning` | `tenants:write` | `tenants.cloudProvisioning` |
| `inviteTenantMember` | `tenants:write` | `tenants.inviteMember` |
| `suspendTenant` | `tenants:manage` | `tenants.suspend` |
| `resumeTenant` | `tenants:manage` | `tenants.resume` |
| `deleteTenant` | `tenants:manage` | `tenants.delete` |

Storage: `OrgDirectoryStore.createOrg / updateCloudProvisioning / suspendOrg / resumeOrg / deleteOrg` from `lib/org-directory.ts`. Delete also calls `createDsar({ kind: 'erasure', subject: { kind: 'org-id' } })` and only removes the local row after the request is queued.

Cloud provisioning states: every tenant row exposes `admin-only`, `cloud-provisioned`, or `cloud-failed`. With `AKOS_CLOUD_URL` configured, create attempts `/api/admin/orgs`; failures leave the local tenant visible as `cloud-failed` and expose a retry action that reuses the local tenant record and owner email without recreating it. Without cloud config, rows remain explicit `admin-only`.

Member access is cloud-backed. `inviteTenantMember` only reports success after `grantOrgMemberAccessInCloud` creates/updates the cloud `org_members` row. When cloud is not configured, the action returns `ok:false` with a cloud-required message because there is no local tenant-member store that can grant usable login/runtime access. Cloud rejects new accepted members that would exceed the tenant's active entitlement/plan seat limit; updating an existing member role does not consume another seat.

Lifecycle cloud sync: suspend/resume first update the admin directory, then sync `orgs.tenant_status` in cloud. If cloud sync fails, the action returns a warning so the operator sees local/cloud divergence. Delete syncs cloud to `retention` before queuing the DSAR erasure request and deleting the local row; when cloud is configured and that sync fails, or when the DSAR request cannot be queued, the local tenant is kept. Delete success copy must describe the DSAR request as queued/pending, not as a completed cascade.

Tenant hub readiness must distinguish backend states instead of collapsing them
to `unconfigured`: `unconfigured`, `unreachable`, `forbidden`, and
`missing-data` flow through `TenantHubSignal.issue` with next action, status,
error code, and request id when available. Dashboard readiness counters use the
same inputs to summarize tenants without cloud sync, valid license, seat
coverage, or published vertical/pack runtime.

## Key components + data-testid hooks

| Component | testid |
|---|---|
| `TenantList` — outer container | `tenant-list` |
| Create button | `create-tenant-btn` |
| Per-row status badge | `status-badge-<orgId>` |
| Per-row cloud badge | `cloud-badge-<orgId>` |
| Per-row retry cloud button | `retry-cloud-<orgId>` |
| Per-row invite button | `invite-<orgId>` |
| Per-row suspend button | `suspend-<orgId>` |
| Per-row resume button | `resume-<orgId>` |
| Per-row delete button | `delete-<orgId>` |
| Suspend reason input | `suspend-reason` |

Dialogs: `TenantCreateDialog`, `TenantInviteDialog`, `DangerConfirmDialog` (suspend + delete with typed `DELETE` confirmation).

## Source dir

`apps/admin/app/tenants/`

## Audit events emitted

`tenants.create`, `tenants.inviteMember`, `tenants.suspend`, `tenants.resume`, `tenants.delete` — all appended via `AdminAuditStore` (`lib/stores.ts`).

## Related

- SU5.2 `cafec231f`, issue #2996
- ENT-7 DSAR erasure request: `compliance.dsar.create` (`lib/actions/compliance.ts`)
- ADR-0039 (merges sum work)

Source: /raw/for-agents/screens/admin-tenants.md

### for-agents/screens/admin-verticals.md

# Admin screen — admin-verticals
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Vertical builder wizard. Lists existing verticals (from the in-memory `VerticalDefinitionStore`) and provides a multi-step wizard to create a new one: identity, agents, flows, slash-commands, mentions, brand tokens, and optional pack reference. Emits a config YAML on submission (RFC-0029 / ADR-0061 pattern).

## Route + RBAC

- **Route:** `/admin/verticals`
- **Read / list:** `verticals:read` cap.
- **Save draft:** `verticals:write` cap (oem-owner, oem-admin).
- **Create / submit:** `verticals:write` cap.

## Server actions (`apps/admin/app/verticals/verticals-actions.ts`)

| Action | Cap | Audit event |
|---|---|---|
| `listVerticals` | `verticals:read` | _(none)_ |
| `saveVerticalDraft` | `verticals:write` | _(none — draft only)_ |
| `createVertical` | `verticals:write` | `verticals.create` |

Storage: module-level `VerticalDefinitionStore` singleton (`createInMemoryVerticalDefinitionStore` from `@agentskit/os-whitelabel/runtime`). Persists in-process; production deployments replace with a backed store.

## Key components + data-testid hooks

| Component | testid |
|---|---|
| `VerticalsPageClient` — outer shell | `verticals-page` |
| `VerticalBuilder` — multi-step wizard | `vertical-builder.tsx` |
| Wizard steps | `wizard/identity.tsx`, `wizard/agents.tsx`, `wizard/flows.tsx`, `wizard/slash-commands.tsx`, `wizard/mentions.tsx`, `wizard/brand.tsx`, `wizard/pack.tsx` |

## Source dir

`apps/admin/app/verticals/`

Schemas / types: `verticals-defaults.ts` (no `'use server'`).

## Audit events emitted

`verticals.create` — payload: `{ id, productName, preset, agentCount, flowCount, slashCommandCount, mentionCount, hasBrand, hasPack }` — section `verticals`.

## Edge cases

- Zod `VerticalDraftSchema.safeParse` validates the full draft at the server boundary.
- `VerticalDefinition.safeParse` provides a second validation layer at the RPC boundary.
- The store is in-memory; a server restart resets it unless wired to a persistent backing store.
- `buildConfigYaml` emits a human-readable YAML summary (loaded by `loadVerticalFromYaml` in the sidecar).

## Related

- SU5.1 PR #3110, issue #2995
- RFC-0029, ADR-0061 (verticals data-driven)
- `@agentskit/os-whitelabel/runtime` — `VerticalDefinition`, `VerticalDefinitionStore`

Source: /raw/for-agents/screens/admin-verticals.md

### for-agents/screens/admin-whitelabel.md

# Admin screen — admin-whitelabel
## Human guide

[`README.md`](../../../apps/admin/README.md) (OEM operator console — internal, not fumadocs)


## Purpose

Per-tenant brand-kit editor. Operators select a tenant, edit `BrandKit` fields (colors, typography, logos, product name), import a JSON brand kit, preview the live token render, run a contrast audit, save a draft, publish, and retry cloud mirror sync when hosted publish fails. Wraps `TenantRuntimeConfigStore` draft/publish lifecycle.

## Route + RBAC

- **Route:** `/admin/whitelabel`
- **Read / contrast audit:** `whitelabel:read` cap.
- **Save draft:** `whitelabel:write` cap (oem-owner, oem-admin).
- **Publish:** `whitelabel:manage` cap (oem-owner only).

## Server actions (`apps/admin/app/whitelabel/whitelabel-actions.ts`)

| Action | Cap | Audit event |
|---|---|---|
| `saveWhitelabelDraft` | `whitelabel:write` | `whitelabel.draft.save` |
| `publishWhitelabel` | `whitelabel:manage` | `whitelabel.publish`, `whitelabel.publish.cloud` |
| `retryWhitelabelCloudMirror` | `whitelabel:manage` | `whitelabel.publish.cloud` |
| `runContrastAudit` | `whitelabel:read` | _(none — read-only)_ |

Storage: `TenantRuntimeConfigStore.saveDraft / publish / getDraft / getActive` (from `lib/stores.ts`). Brand kit is merged into `RuntimeConfig.brand` — existing sections are preserved.

## Key components + data-testid hooks

| Component | testid |
|---|---|
| Tenant option listbox item | `tenant-option-<orgId>` |
| Save draft button | `save-draft-btn` |
| Publish button | `publish-btn` |
| `TokenEditor` — live BrandKit field editor | `token-editor.tsx` |
| `BrandKitImporter` — drag-drop JSON import | `brand-kit-importer.tsx` |
| `PreviewPane` — live rendered preview | `preview-pane.tsx` |
| `WhitelabelPageClient` — outer shell | `whitelabel-page.tsx` |

## Source dir

`apps/admin/app/whitelabel/`

## Audit events emitted

`whitelabel.draft.save` (payload includes `targetTenantId` + full kit), `whitelabel.publish` (payload includes version number), and `whitelabel.publish.cloud` (payload includes `cloud: published | skipped | failed`) — appended via `AdminAuditStore`, section `whitelabel`.

## Edge cases

- Zod `BrandKit.safeParse` validates the kit at the server boundary — invalid fields return structured `issues` array.
- `runContrastAudit` calls `auditBrandContrast` from `@agentskit/os-whitelabel` — WCAG AA per token pair.
- `publishWhitelabel` fails if no draft exists for the target tenant.
- When `AKOS_CLOUD_URL` is configured and cloud mirror fails, publish stays local but returns `cloud: failed`; the UI shows the failed sync state and a retry action.
- Standalone mode (`AKOS_CLOUD_URL` unset) remains explicit `local-only` rather than a hard error.
- Unsaved-changes hook (`useUnsavedChanges`) warns on navigation when `dirty`.

## Related

- SU5.3 `a9eefaf40`, issue #2997
- `@agentskit/os-whitelabel` — `BrandKit` schema, `auditBrandContrast`, `RuntimeConfig`
- ADR-0038 (whitelabel tokens), RFC-0033 (config verticals)

Source: /raw/for-agents/screens/admin-whitelabel.md

### for-agents/screens/agents.md

# Desktop screen — agents

## Human guide

[`agents.mdx`](../../../apps/web/content/docs/using-the-app/agents.mdx)

## Purpose

Agent registry + editor. Author agents (multi-step form), browse the
registry, version + roll back, apply inline overrides, and test-invoke.

## Where

- **Desktop:** `packages/os-desktop/src/screens/agents/`
  (`registry/`, `inline-override/`, `sandbox/`, `shared-capabilities.ts`)

## Wired methods

- `agents.list` — render the registry table.
- `agents.upsert` — create / update an agent.
- `agents.delete` — destructive (confirmation modal).
- `agents.invoke` — test-run an agent from the editor.
- `agents.applyOverride` — apply an inline per-run override.
- `agents.transition` — promote / change lifecycle state.
- `agents.versions.list` — version history for an agent.
- `agents.versions.diff` — diff two versions in the rollback panel.
- `connections.list` — populate the credential / provider picker.

## Edge cases

- **Unsaved form navigation** — multi-step form guards route changes;
  surfaces an "unsaved changes" prompt before discarding.
- **Invoke before save** — `agents.invoke` runs the persisted version;
  the UI blocks invoke while the form is dirty.
- **Rollback to deleted version** — `agents.versions.diff` against a
  pruned version returns `version-not-found`; UI greys the rollback action.
- **Capability gate** — editor capability set is shared via
  `shared-capabilities.ts`; an agent referencing a capability the
  workspace plan lacks fails `agents.upsert` with a plan-gate error.

Source: /raw/for-agents/screens/agents.md

### for-agents/screens/assets.md

# Desktop screen - assets

## Human guide

[`assets.mdx`](../../../apps/web/content/docs/using-the-app/assets.mdx)

## Purpose

Results gallery for workflow outputs. Use this screen when a user asks where
generated files, media, PDFs, code artifacts, or run outputs are stored,
previewed, downloaded, filtered, or bulk-deleted.

## Where

- **Desktop:** `packages/desktop-data-infra/src/screens/assets/`
- **Facade:** `packages/os-desktop/src/screens/assets/`
- **Nav id:** `assets`
- **Nav label:** Results

## Wired methods

- `assets.list` - list assets with filters and vertical attribution.
- `assets.get` - load one asset detail/preview.
- `assets.delete` - delete one asset.
- `assets.bulkDelete` - delete selected assets.

## Edge cases

- Asset downloads are kind-aware; use the screen helper rather than inventing a
  raw path.
- Vertical filtering is driven by the active vertical context.
- If an asset preview cannot render inline, keep the row usable and offer
  download/open actions.

Source: /raw/for-agents/screens/assets.md

### for-agents/screens/audit.md

# Desktop screen — audit

## Human guide

[`governance.mdx`](../../../apps/web/content/docs/using-the-app/governance.mdx) (Audit section)

## Purpose

Signed audit ledger viewer + verify. Renders the immutable audit-batch log with ed25519 signature verification, integrity check across batch chains, and per-entry detail. Source of truth for compliance review and SOC-2 evidence export.

## Where

- **Desktop:** `packages/os-desktop/src/screens/audit/`
- **Web:** `apps/web/app/app/(shell)/audit/`

## UI shell

Header renders through the shared `ScreenHeader` primitive from `@agentskit/os-ui` (issue #1355 F0-7) — `kicker`/`title`/`subtitle` driven by `audit.kicker` / `audit.title` / `audit.subtitle` intl keys; verify/export/print controls are passed as `actions`. The legacy bespoke `HEADER_CLASS` in `parts/helpers.ts` is `@deprecated` and slated for removal next minor (ADR-0039 deprecation flow).

## Wired methods

- `audit.signedBatch` — fetch the current signed batch (verifies signature client-side too).
- `audit.batchHash` — recompute hash for spot-checks.
- `audit.entries.list` — paginated entry stream with filters (actor, section, time range).
- `audit.entries.verify` — per-entry signature + chain verification.
- `audit.verifyIntegrity` — full ledger integrity walk (chain of batch hashes).
- `compliance.export` — emit SOC-2 / GDPR evidence bundle.
- `harness.audit.list` — runtime-harness audit slices (kept separate from main ledger).

## Edge cases

- **Signature fails verification** — `audit.signedBatch` returns `verified: false`; the UI banners red and disables export.
- **Chain break** — `audit.verifyIntegrity` returns the first broken batch hash; surface the row + offer "Re-fetch from canonical store".
- **Large page** — `audit.entries.list` caps at 500 rows; UI paginates with cursor token.
- **No signing key configured** — entries still listed, but the verify column shows "unsigned (dev mode)" — block compliance export.

Source: /raw/for-agents/screens/audit.md

### for-agents/screens/break-glass.md

# Desktop screen — break-glass

## Human guide

[`governance.mdx`](../../../apps/web/content/docs/using-the-app/governance.mdx) (Break-glass section)

## Purpose

Emergency access control. Request time-boxed privilege elevation and
(for admins) review, grant, or revoke active grants. Every action writes
a signed audit-ledger entry.

## Where

- **Desktop:** `packages/os-desktop/src/screens/break-glass/`
  (`index.tsx`, `parts/`). This screen also mounts the **Consent
  grants** sub-panel (`screens/consent/`, `ConsentPanel`) — there is no
  separate nav route or for-agents doc for consent; it is documented
  here.

## Wired methods

### Break-glass elevation

- `access.breakGlass` — request time-boxed elevation.
- `access.breakGlass.list` — active + historical grants (Manage tab).
- `access.breakGlass.revoke` — manual revoke of a grant (admin only).

### Consent grants sub-panel (`ConsentPanel`)

Time-boxed scoped approvals, distinct from role elevation. Owner
`@agentskit/os-security`; contract in
`packages/os-contracts/src/methods/consent.ts` (`ConsentRecord`:
subject, scope, reason, grantedBy, expiresAt, …).

- `consent.list` — grants table (active by default).
- `consent.grant` — `{ subject, scope, reason, grantedBy, expiresAt }`;
  also emits an `ak:notify` warning with quick links to the audit log
  and this Access screen.
- `consent.revoke` — `{ id, revokedBy }`, optimistic per-row pending
  state.

## Edge cases

- **Non-admin Manage tab** — `access.breakGlass.list`/`.revoke` require an
  admin role (`ADMIN_ROLES`); non-admins see the Request tab only and an
  "admin required" notice on Manage.
- **Grant expiry** — grants are time-boxed; both the break-glass list
  and the consent table re-derive remaining time from a ticking `now`
  clock and mark expired grants without an extra RPC.
- **Consent vs elevation** — `consent.*` grants a scoped approval on a
  subject; `access.breakGlass` elevates the caller's role. They use
  separate stores and contracts — don't conflate them.
- **Signed audit trail** — both grant and revoke append a signed
  audit-ledger entry; the signature is verifiable from the operator's
  machine via the public key shown in the audit footer.

Source: /raw/for-agents/screens/break-glass.md

### for-agents/screens/bundles.md

# Desktop screen - bundles

## Human guide

[`route-only-screens.mdx`](../../../apps/web/content/docs/using-the-app/route-only-screens.mdx) · [`workspaces.mdx`](../../../apps/web/content/docs/using-the-app/workspaces.mdx) (Workspace › Export/Import)

## Purpose

Workspace/process bundle history and import/export review. Use this screen when
a user asks to compare SDLC result bundles, inspect imported artifacts, or move
process/workflow state between workspaces.

## Where

- **Desktop:** `packages/desktop-platform-admin/src/screens/pipelines/bundles.tsx`
- **Nav id:** `bundles`
- **Route-only:** reachable from Workspace export/import and process surfaces.

## Wired methods

- `bundles.list` - list saved bundles.
- `bundles.import` - import a bundle and return a preview.
- `bundles.export` - export current workspace/process state.
- `bundles.diff` - compare bundle contents before applying changes.

## Edge cases

- Treat bundle import as a review flow; do not imply it mutates state until the
  user confirms the import/apply step.
- Bundle screens are route-only in navigation, so assistants should usually
  offer the owning Workspace or Processes surface first unless the user asks
  specifically for bundle history.

Source: /raw/for-agents/screens/bundles.md

### for-agents/screens/coding.md

# Desktop screen — coding

## Human guide

[`coding.mdx`](../../../apps/web/content/docs/using-the-app/coding.mdx) · [`route-only-screens.mdx`](../../../apps/web/content/docs/using-the-app/route-only-screens.mdx)

## Purpose

Coding-agent task runner and provider health surface. The run screen dispatches
one-shot coding tasks, shows live phase/cancel state, renders artifacts, and
keeps recent runs. The provider tab lives under Connections/Integrations and
shows provider availability plus conformance checks.

## Where

- **Run screen:** `packages/desktop-agent-workspace/src/screens/coding/`
  - `index.tsx` — task composer, run panel, artifacts, follow-up actions.
  - `use-coding-screen.ts` — provider/profile loading, `coding.runTask`,
    `coding.cancelTask`, event phase handling, recent-run persistence.
  - `composer.tsx` — provider/profile/kind/timeout/cwd/capability/prompt form.
  - `run-panel.tsx` — status, cost/tokens/files/tools badges, cancel affordance.
  - `recent-runs.tsx` / `followup-actions.tsx` — local history and rerun/handoff.
- **Provider tab:** `packages/desktop-agent-workspace/src/screens/coding/coding-providers-tab.tsx`
  mounted by the Integrations/Connections shell.

## Wired methods

- `coding.providers` — list built-in coding providers with availability,
  required keys, docs URL, and capability metadata.
- `coding.permissionProfiles` — list sandbox permission profiles used by the
  run composer.
- `coding.runTask` — run a one-shot coding task. The UI passes provider,
  prompt, permission profile, cwd, kind, dry-run flag, timeout, granted
  capabilities, and a generated `runId`.
- `coding.cancelTask` — cooperatively cancel the active task by `runId`.
- `coding.runConformance` — run provider conformance checks from the provider
  tab; live `coding.conformance.check` events are appended while the run is in
  flight.
- `coding.benchmark` — used by the Evals/Benchmarks tab to compare providers.
- `coding.delegate` — used by orchestration/follow-up flows for multi-provider
  delegation.
- `flows.run` / `pipelines.*` helpers are reached from follow-up actions when
  sending a result into a process.

## Behaviour

- Providers and permission profiles are loaded on mount through
  `desktop-sidecar-bridge`; unavailable providers are visible but disabled.
- Runs are dry-run by default and persist compact recent-run records in local
  storage.
- The UI subscribes to `coding.task.started`, `coding.task.finished`, and
  `coding.task.cancelled` events to show phase state.
- Task results render file edits, shell invocations, tool usage, summary,
  status, duration, cost, and tokens.
- `runId` is generated client-side and sent to both `coding.runTask` and
  `coding.cancelTask`, so cancellation targets the current in-flight task.
- Conformance checks use a generated conformance run id and ignore unrelated
  event streams.

## Edge cases

- **No provider/profile/prompt** — Run stays disabled.
- **Unavailable provider** — Provider remains visible but cannot be selected/run.
- **Malformed task result** — coerced to a safe failed result instead of
  crashing the artifact UI.
- **Cancellation unsupported** — `cancelled:false` is surfaced inline and the
  run remains active.
- **Provider throws** — error is shown in the run panel and stored in recent
  history.
- **External provider smoke** — real CLI/API execution depends on installed
  provider binaries or credentials; M4 should run packaged smoke against at
  least one configured provider.

Source: /raw/for-agents/screens/coding.md

### for-agents/screens/compliance.md

# Desktop screen — compliance

## Human guide

[`compliance.mdx`](../../../apps/web/content/docs/using-the-app/compliance.mdx)

## Purpose

In-product compliance workspace. The operator can export signed evidence
bundles, manage active legal holds, queue DSAR access/erasure requests, and
see retention prune / cloud-GC wiring status. No new backend — the screen is a
thin UI over the existing `compliance.*` handlers.

## Where

- **Desktop:** `packages/desktop-platform-admin/src/screens/compliance/`
  (`packages/os-desktop` re-exports `ComplianceScreen` as a migration shim).
  - `index.tsx` — export wizard + compliance operations.
  - `helpers.ts` — pure form model, validation, RPC param mapping.
  - `result-card.tsx` — signed-bundle summary + manifest download.

## Wired methods

- `compliance.export` — builds a signed regime-specific evidence bundle from
  the audit ledger between `from`/`to`. Supported regimes: `soc2`, `hipaa`,
  `gdpr`, `ccpa`, `iso27001`.
- `compliance.legalHold.list` / `compliance.legalHold.put` /
  `compliance.legalHold.release` — list, place, and release preservation holds.
- `compliance.dsar.list` / `compliance.dsar.create` — list and queue DSAR
  access/erasure requests.
- `compliance.prune.status` / `compliance.gc.status` — show retention executor
  wiring and last-run status.

## Behaviour

- Default window is the trailing 90 days ending today.
- The wizard makes `to` inclusive (end-of-day) when building RPC params.
- Inverted or malformed date ranges are rejected client-side before the RPC
  fires.
- On success the signed bundle summary renders; the manifest (the signed
  result object) is downloadable as JSON.
- Legal holds and DSAR requests refresh after mutations.
- Hold release asks for a native release reason before calling the RPC.

## Edge cases

- **Handler rejects** (e.g. ledger unavailable) — the error is surfaced inline
  in an `alert` region; no partial bundle is shown.
- **Unexpected response shape** — guarded by `isExportResult`; surfaces a typed
  error rather than rendering garbage.
- **Empty window** — the bundle is still produced with `totalRows: 0`; the
  section counts simply read zero.
- **Legal-hold store unavailable** — the operations panel keeps the rest of the
  compliance surface usable and shows whatever status endpoints are wired.
- **Erasure under hold** — the DSAR create handler refuses the request and the
  screen surfaces the typed error inline.

Source: /raw/for-agents/screens/compliance.md

### for-agents/screens/config.md

# Desktop screen — config

## Human guide

[`route-only-screens.mdx`](../../../apps/web/content/docs/using-the-app/route-only-screens.mdx) · [`workspaces.mdx`](../../../apps/web/content/docs/using-the-app/workspaces.mdx) (reachable via top-bar Settings)

## Purpose

Workspace configuration editor — copilot config, knowledge sources
overview, and raw workspace export / import.

## Where

- **Desktop:** `packages/os-desktop/src/screens/config/`
  (`config-form.tsx`, `panes/`, `index.tsx`)

## Wired methods

- `copilot.config.get` — load current copilot configuration.
- `copilot.config.set` — persist copilot configuration changes.
- `knowledge.sources.list` — show configured knowledge sources (read-only
  summary; full CRUD lives on the knowledge screen).
- `workspace.config.selfheal.get` — read the self-heal policy (recovery
  actions on node failure); surfaced as the **Settings → Orchestration**
  toggle. The runner only wires the self-heal hook when `enabled`.
- `workspace.config.selfheal.set` — persist the self-heal policy (applies on
  the next run).
- `workspace.config.activation.get` — read the activation/retention metrics
  consent (strict opt-in); surfaced in the **Settings → Privacy** pane.
- `workspace.config.activation.set` — persist the activation-metrics consent.
- `workspace.export` — download a full workspace config bundle.
- `workspace.import` — restore from a config bundle (destructive merge).

## Edge cases

- **Invalid config payload** — `copilot.config.set` rejects with Zod
  issues; the form surfaces field-level validation messages.
- **Import overwrites state** — `workspace.import` is a confirm-gated
  destructive merge; the UI shows a diff/warning before applying.
- **Raw view** — the raw-config pane renders the canonical JSON; edits
  there are re-validated through the same `copilot.config.set` contract.

Source: /raw/for-agents/screens/config.md

### for-agents/screens/connections.md

# Desktop screen — connections

## Human guide

[`connections.mdx`](../../../apps/web/content/docs/using-the-app/connections.mdx)

## Purpose

OAuth + key-based LLM + outbound integration creds. The single page for adding/rotating/revoking provider credentials (LLM providers, Slack, GitHub, Linear, Notion, etc.), scoped **External apps** automation API keys, and the OAuth completion handshake.

## Where

- **Desktop:** `packages/os-desktop/src/screens/connections/`

## Wired methods

- `connections.list` — render configured connections grouped by provider.
- `connections.verify` — "Test connection" button → live ping.
- `connections.startOauth` / `connections.completeOauth` — generic OAuth handshake.
- `connections.llmOauthStart` / `connections.llmOauthComplete` / `connections.llmOauthRefresh` — LLM-provider-specific OAuth (Anthropic, OpenAI).
- `oauth.list` / `oauth.providers` / `oauth.start` / `oauth.complete` / `oauth.revoke` — generic OAuth registry surface.
- `secrets.set` / `secrets.delete` / `secrets.list` / `secrets.reveal` — direct key-based credential management.
- `secrets.providers.list` / `secrets.providers.configure` / `secrets.providers.test` / `secrets.providers.remove` — external secret stores (Vault, AWS SM, 1Password).
- `setup.probeProvider` — wizard-style probe from the onboarding flow.

## Edge cases

- **OAuth callback lost** — `connections.completeOauth` returns `state-mismatch`; the UI prompts to restart from the provider list.
- **Token refresh fails** — `connections.llmOauthRefresh` returns `refresh-token-expired`; mark connection as `degraded` and require re-auth.
- **Secret provider unreachable** — `secrets.providers.test` returns `unreachable`; UI shows banner and falls back to OS keychain.
- **Reveal in audit** — `secrets.reveal` always writes an audit row (actor + secret id); show "this will be logged" confirm modal first.
- **Verify rate limit** — `connections.verify` is throttled (1 / 5s per connection) to avoid burning provider quotas.

Source: /raw/for-agents/screens/connections.md

### for-agents/screens/copilot.md

# Desktop screen — copilot

## Human guide

[`copilot.mdx`](../../../apps/web/content/docs/using-the-app/copilot.mdx)

## Purpose

In-OS chat. Slash commands, @-mentions, proactive nudge cards.
Grounded by workspace RAG.

First-run setup is assistant-first: when `copilot.config.get` returns
`onboardingComplete=false`, the Copilot screen renders
`AssistantFirstOnboarding` directly in the conversation instead of an empty
not-configured state. The state machine asks for the user's display name and
assistant name as free-text collect frames, renders deterministic inline cards
for vertical/provider choices, persists progress through
`onboarding.session.upsert`, and only lets web first-access complete after the
assistant flow reaches `done`.

Inline render frames used during onboarding (see
[`components/tool-selection-step.md`](../components/tool-selection-step.md) and
[`components/configuration-plan-step.md`](../components/configuration-plan-step.md)):

- `VerticalStep` — vertical picker.
- `ToolSelectionStep` — tool/MCP/integration multi-select from the registry.
- `ConfigurationPlanStep` — per-tool setup status and configure actions.
- `LlmProviderCard` / `OAuthProviderCard` / `ProviderConfigModal` — provider setup.

## Wired methods

- `copilot.session.create` / `.list` / `.get` — session state.
- `copilot.session.send` — chat dispatch (streams via
  `copilot.chunk` event).
- `copilot.session.cancel` — soft cancel.
- `copilot.config.get` / `.set` — provider + role assignments.
- `copilot.proposal.decide` — approve/reject tool-call proposal.
- `copilot.powers.list` / `.grant` — capability grants (signed).
- `copilot.smoke` — env-check ping.
- `copilot.slash.parse` / `.list` — slash command parser.
- `copilot.mention.parse` — @-mention parser.
- `copilot.proactive.fromEvent` — event → action card mapper.
- `agents.applyOverride` — per-session model swap.
- `agents.overrides.get` / `.list` / `.delete` — read/manage swaps.
- `onboarding.session.get` / `.upsert` — first-run assistant state snapshot
  with step, labels, vertical, selected tools, and advisory allowed actions.

## Edge cases

- `copilot.session.send` requires `copilot.config` to declare a
  provider + role assignment. Without it: `no model assigned for
  role "chat"` error.
- RAG grounding is best-effort: if `knowledgeEmbedder.embed` throws
  the dispatch proceeds without context.
- Tool-call proposals at `destructive` tier escalate to HITL via the
  `hitlStore` — see Inbox screen for approval flow.
- Reranker wired via env (`AKOS_RAG_RERANKER`).
- First-access completion is deliberately two-step: Copilot config can be saved
  during onboarding with `onboardingComplete=false`, but the web first-access
  server action refuses `run-user-onboarding` until the assistant flow writes
  the done signal.

Source: /raw/for-agents/screens/copilot.md

### for-agents/screens/cost.md

# Desktop screen — cost

## Human guide

[`cost.mdx`](../../../apps/web/content/docs/using-the-app/cost.mdx)

## Purpose

**Cost Guard** — spend rollup, per-provider breakdown, budget editor, and
commercial Billing cockpit. The dashboard shows live + historical LLM cost,
per-budget alert configuration, plan context, invoices, and backend-computed
tenant usage state. (UI label: "Cost Guard"; the JSON-RPC method namespace
stays `cost.*`.)

## Where

- **Shared desktop/web screen owner:** `packages/desktop-platform-admin/src/screens/cost/`
- **Desktop facade:** exposed through `packages/os-desktop/src/`
- **Browser host:** mounted by the shared desktop shell in `apps/console` and
  web/standalone host surfaces.

The Billing tab is a shared operator cockpit, not a desktop-only screen.
Commercial notifications navigate here with `tab=billing`.

## Wired methods

- `cost.summary` — top-card totals + sparkline (today / week / month).
- `cost.breakdown` — table grouped by provider / model / agent / flow.
- `cost.list` — paginated raw cost rows.
- `cost.budgets.list` / `cost.budgets.upsert` / `cost.budgets.delete` / `cost.budgets.evaluate` — budget CRUD + live evaluation.
- `cost.alerts.list` / `cost.alerts.mute` — alert inbox + mute window.
- `cost.reset` — admin "reset counters" with audit trail.
- `billing.plan.get` / `billing.invoices.list` — cloud-plan context shown
  alongside Cost Guard.
- `usage.state.get` — backend-computed tenant usage status shown with billing.

## Edge cases

- **Budget evaluation lag** — `cost.budgets.evaluate` is synchronous against cost-tracker state; running flows may have in-flight charges not yet flushed. UI shows "as of `cost.updatedAt`".
- **Reset is destructive** — `cost.reset` requires confirmation + writes audit; UI requires typing the budget name.
- **Plan downgrade mid-cycle** — `billing.plan.get` may show a lower tier than current `cost.summary` already exceeds; surface a banner linking to the cloud control plane.
- **Per-provider currency** — all totals normalized to USD by the cost tracker; original currency is in the `raw` field of each `cost.list` row.
- **Billing unavailable** — show the disconnected billing state honestly; do
  not synthesize plan or usage data in the UI.
- **Usage state source of truth** — `usage.state.get` is backend-computed from
  the shared evaluator. UI should render package/metric status and attention
  labels without recalculating limits.
- **Deep-link params** — `tab=billing` navigation params are one-shot screen
  params. The Cost screen consumes them after mount so notification actions work
  even when the screen is already open.

Source: /raw/for-agents/screens/cost.md

### for-agents/screens/dashboard.md

# Desktop screen — dashboard

## Human guide

[`dashboard.mdx`](../../../apps/web/content/docs/using-the-app/dashboard.mdx)

## Purpose

Workspace overview + at-a-glance health. Default landing screen — aggregates run health, cost burn, HITL queue depth, observability incidents, and active triggers into stat tiles + recent-activity feed.

## Where

- **Desktop:** `packages/os-desktop/src/screens/dashboard/`
- **Web:** `apps/web/app/app/(shell)/dashboard/`

## Wired methods

- `dashboard.stats` — aggregated tile payload (runs / errors / spend / hitl / triggers).
- `runs.list` (`limit: 5`) — recent activity feed.
- `hitl.list` (`status: 'pending'`) — pending decision count + first 3 cards.
- `cost.summary` — today's spend tile.
- `observability.incidents.list` (`status: 'open'`) — open incidents tile.
- `runtime.status` — sidecar health banner (red if `degraded`).
- `cloud.status` — cloud-sync banner.
- `dispatch.refresh` — soft refresh after returning to the tab.

## Edge cases

- **Empty workspace** — first-run state: tiles render placeholders + CTA buttons to onboarding flow.
- **Sidecar offline** — `runtime.status` returns `unreachable`; all tile fetches abort and a single retry banner shows.
- **Cloud disconnected** — `cloud.status === 'offline'` is non-fatal; tile shows local-only mode.
- **Stat drift** — `dashboard.stats` is cached 30s; UI shows `updatedAt` tooltip.

Source: /raw/for-agents/screens/dashboard.md

### for-agents/screens/evals.md

# Desktop screen — evals

## Human guide

[`evals.mdx`](../../../apps/web/content/docs/using-the-app/evals.mdx)

## Purpose

Eval suites: build cases against an agent/flow, run them, diff across
model swaps, replay failed cases. Used to gate prompt/model changes.

## UI status (read this first)

The screen ships from `packages/desktop-agent-workspace/src/screens/evals/`
and is mounted by `desktop-shell` through the `EvalsScreen` export. The
legacy facade at `packages/os-desktop/src/screens/evals/` forwards to this
screen; do not add new eval UI there.

What ships today:

- **UI** — suites/results/benchmarks tabs in
  `packages/desktop-agent-workspace/src/screens/evals/index.tsx`; result
  rows open per-case verdict details through `evals.results.get`.
- **Contracts** — `packages/os-contracts/src/methods/evals.ts`, all
  `stability: 'alpha'`, owner `@agentskit/os-headless`.
- **Handlers** — `createEvalsHandlers` in
  `packages/os-headless/src/evals-handlers.ts`.
- **Copilot slash** — `/eval` → `evals.run`
  (`packages/os-headless/src/copilot-slash.ts`).
- **Command palette** — `nav.evals` ("Go to Evals"), `create.eval`
  ("New Eval Suite"), `run.eval` ("Run Eval Suite").

## Methods

- `evals.suites.list` / `evals.suites.get` / `evals.suites.upsert` /
  `evals.suites.delete` — suite CRUD.
- `evals.run` — dispatch a suite and return the persisted `EvalResultRow`.
- `evals.results.list` / `evals.results.get` — paged results + per-case
  detail.
- `traces.replay` — replay a failed case against a different
  model / agent version.
- `agents.versions.list` / `agents.versions.diff` — pick the agent
  version to eval against.

## Edge cases

- **Empty suite** — `evals.run` rejects if `cases.length === 0`.
- **Long-running suite** — current handler runs synchronously and returns an
  `EvalResultRow`; if the runner becomes async again, poll
  `evals.results.list` (no WebSocket).
- **Schema drift** — `evals.suites.upsert` validates against the
  agent's input schema; mismatch surfaces a Zod issue list.

## Related

- [eval-suite flow recipe](../flows/eval-suite.md) — end-to-end run.
- [os-headless](../packages/os-headless.md) — handler host.
- [desktop-agent-workspace](../packages/desktop-agent-workspace.md) — screen package.

Source: /raw/for-agents/screens/evals.md

### for-agents/screens/flow-editor.md

# Desktop screen — flow-editor

## Human guide

[`route-only-screens.mdx`](../../../apps/web/content/docs/using-the-app/route-only-screens.mdx) · [`flows.mdx`](../../../apps/web/content/docs/using-the-app/flows.mdx)

## Purpose

The visual DAG canvas (ADR-0019). Renders a `VisualFlow` as a
React Flow graph with a node palette, per-node inspectors, and a live
run debugger. It is the editor surface embedded by the **flows** screen
(and reused for column→flow binding on the **pipelines-board**); it is
not a standalone nav route.

## Where

- `packages/os-desktop/src/screens/flow-editor/`
  - `index.tsx` — `FlowEditorScreen({ initialFlow?, onChange? })`,
    `ReactFlowProvider` + `reduceCanvas` reducer (from `@agentskit/os-flow`).
  - `node-types.tsx` / `node-types-parts/` — node renderers per
    `VisualNodeKind`.
  - `inspectors/` — per-node config panels.
  - `debugger-panel.tsx` — live run debugger (`createInMemoryDebugger`,
    `os-flow` #64).
  - `screen-parts/inner.tsx`, `helpers.ts`, `use-suppress-ro.ts`.

## Contract (props, not RPCs)

The canvas is a controlled component — it implements no JSON-RPC methods
itself. The host owns persistence:

- `initialFlow?: VisualFlow` — seed graph (defaults to `emptyFlow('draft')`).
- `onChange?: (flow: VisualFlow) => void` — fires after every reducer
  dispatch with the latest flow.

The **flows** screen converts to/from inline records via
`flows.toVisual` / `flows.fromVisual` and saves with
`flows.upsertInline` (debounced). See [flows](./flows.md).

## Context panel (RFC-0024)

Context — Knowledge/RAG pipelines + MCP tool servers — is **workflow-scoped**,
not per-agent and not per-node. The flows editor renders a flow-level
**Context** panel (`FlowContextPanel`) above the editor body; it reads/writes
the `context` field (`{ ragRefs, mcpRefs }`) of `FlowConfig` / `VisualFlow`.
At run time the headless runner applies the workflow's `context` to every
agent of the flow (`withFlowContext`); an empty flow Context falls back to each
agent's legacy `AgentConfig.ragRefs`/`mcpRefs` during the deprecation window.

**Enforcement status.** `ragRefs` is enforced at run time — the agent handler
queries them via `retrieveRagContext`. `mcpRefs` is currently **declarative**:
it round-trips through schema, editor and the boot migration, but the runtime
does not yet gate MCP servers by it (`mcp.invoke` is exposed unfiltered — a
pre-RFC-0024 limitation). Runtime MCP gating by `context.mcpRefs` is a tracked
follow-up.

## Edge cases

- The canvas is pure state — closing without the host persisting
  `onChange` output discards edits.
- Node kinds rendered come from `VisualNodeKind`; an unknown kind from a
  hand-edited flow falls back to a generic node rather than throwing.
- ResizeObserver loop errors from React Flow are suppressed by
  `use-suppress-ro.ts` (cosmetic; does not affect layout).
- The debugger panel only populates when a run is attached; with the
  runner in `synthesiser` mode the graph still renders but produces no
  step events (mirrors the flows-screen degraded-mode banner).

## Related

- [os-flow](../packages/os-flow.md) — `reduceCanvas`, `flowToVisual`,
  `flowFromVisual`, `assertVisualRoundTrip`, debugger primitives.
- ADR-0019 — visual flow editor.
- [flows](./flows.md) screen — host that mounts this editor.
- [pipelines-board](./pipelines-board.md) — reuses the editor for
  column→flow binding.

Source: /raw/for-agents/screens/flow-editor.md

### for-agents/screens/flows.md

# Desktop screen — flows

## Human guide

[`flows.mdx`](../../../apps/web/content/docs/using-the-app/flows.mdx)

## Purpose

CRUD inline flow records + visual editor + run-flow dialog. Backed by
`FlowStore` (sqlite).

## Wired methods

- `flows.listInline` → render row list
- `flows.upsertInline` → save from editor (debounced)
- `flows.deleteInline` → delete from list
- `flows.toVisual` / `flows.fromVisual` → editor round-trip
- `flows.fromNL` → "Generate from description" NL extraction
- `flows.templates` → starter chip strip
- `flows.snapshot` → version snapshot before edits
- `runner.runFlow` → "Run" button
- `runs.list` → status badges on rows

## Edge cases

- When `runtime.status.runner.mode === 'synthesiser'`, Run button
  still works but the resulting trace is empty. DegradedModeBanner
  warns the operator at the top of the shell.
- `flows.fromNL` requires `llmInvoke` wired in the sidecar (any
  configured LLM provider). Without it, falls back to deterministic
  intent extractor with lower confidence — UI shows clarification
  prompts instead of a proposal.
- Delete prompts a confirmation but does NOT cascade delete
  associated triggers — operator must clean up Triggers screen
  separately.

Source: /raw/for-agents/screens/flows.md

### for-agents/screens/governance.md

# Desktop screen — governance

## Human guide

[`governance.mdx`](../../../apps/web/content/docs/using-the-app/governance.mdx)

## Purpose

RBAC + team + policy administration. Manage members and their roles,
edit role capability sets, operator roles, policies, and per-workspace
isolation.

## Where

- **Desktop:** `packages/os-desktop/src/screens/governance/`
  (`roles.tsx`, `policies.tsx`, `team.tsx`, `parts/`, `team-parts/`)

## Wired methods

- `rbac.members.list` — render the team / members table.
- `rbac.members.invite` — invite a member.
- `rbac.members.remove` — remove a member (destructive).
- `rbac.members.setRole` — change a member's role.
- `rbac.roles.get` / `rbac.roles.set` — read / edit role capability sets. The audit-ledger actor for a `set` is sourced from the transport-verified `ctx.caller.roleName`, never from request params (SEC-3 / #1666).
- `governance.operatorRoles.list` — list operator (privileged) roles.
- `workspaces.list` — workspace selector for scoped settings.
- `workspaces.setIsolation` — set per-workspace isolation level.

## Relationship with the Teams & Users screen (D4 / #3801)

The Teams & Users screen (`packages/desktop-operations/src/screens/teams/`,
nav id `teams`) exposes the `users.*` and `teams.*` RPC surface. **`users.*` is
the canonical source of truth for workspace members and their roles.** The
`rbac.members.*` surface used by this Governance screen is a *derived read
model* over the same `usersStore`: `rbac.members.list` maps each `UserRow` to a
member view and merges pending `collabStore` invites — it never owns the data.
Consequently there is **no duplicated authority**: a `users.upsert` /
`users.assignRole` / `users.revokeRole` / `users.delete` performed on the Teams
& Users screen is immediately visible through `rbac.members.list` here. Use the
Teams & Users screen to *edit* members/roles and teams; use this Governance
screen's members table as the role-aware read/admin projection (last-admin
guard, invite-by-email, operator-role gating). Team membership likewise flows
from `teams.*` (`teams.addMember` / `teams.removeMember`).

## Edge cases

- **Last admin removal** — `rbac.members.remove` / `setRole` rejects if it
  would leave the workspace with no admin; UI disables the action.
- **Self role downgrade** — demoting your own role triggers a confirm
  prompt (you may lose access to this screen).
- **Isolation downgrade** — lowering `workspaces.setIsolation` is
  confirm-gated; raising it may quarantine in-flight runs.
- **Operator role gate** — operator-role edits require an operator
  caller; non-operators see a read-only view.

Source: /raw/for-agents/screens/governance.md

### for-agents/screens/inbox.md

# Desktop screen — inbox (HITL)

## Human guide

[`inbox.mdx`](../../../apps/web/content/docs/using-the-app/inbox.mdx)

## Purpose

Human-in-the-loop queue. Pending escalations from runner pauses,
copilot proposals, pipeline phase gates (`sdlc.gates.*`), break-glass requests.

## Wired methods

- `hitl.escalation.list` — pending rows.
- `hitl.escalation.get` — single row.
- `hitl.escalation.decide` — approve / reject / modify.
- `hitl.ledger.list` / `.append` / `.verify` — signed audit chain.
- `sdlc.gates.list` / `.decide` — pipeline phase gates (separate
  surface).
- `access.breakGlass.list` — time-boxed elevation requests.

## Edge cases

- Decisions append a signed entry to the HITL ledger (ed25519). The
  desktop reveals the public key + signature on hover so reviewers
  can independently verify post-hoc.
- A rejected `destructive` proposal blocks the runner indefinitely
  until cancelled — there is no soft retry.
- Pipeline phase gates appear in their own collapsible group (kind:
  `sdlc.gate`); approve/reject routes to `sdlc.gates.decide` rather
  than `hitl.escalation.decide`. Run dispatch uses `pipelines.runs.*`.
- Break-glass grants auto-revoke at expiry; the timer is in-process
  so a sidecar restart misses the revoke window. After restart, the
  next `hitl.list` call lazily prunes expired rows.

Source: /raw/for-agents/screens/inbox.md

### for-agents/screens/knowledge.md

# Desktop screen — knowledge

## Human guide

[`knowledge.mdx`](../../../apps/web/content/docs/using-the-app/knowledge.mdx)

## Purpose
Top-level workspace screen for managing RAG knowledge sources. Lets the user
plug in folders, URLs, PDFs, and SaaS sources (GitHub, Notion, Confluence,
Google Drive, OneDrive, Dropbox, GCS, S3). Indexed content feeds both the
copilot (`@knowledge:<id>` mentions) and agent tools (`rag.search`).

Lives at `packages/os-desktop/src/screens/knowledge/`.

## Wired methods
- `knowledge.sources.list` — populate the source list.
- `knowledge.sources.add` — create + auto-enqueue index job. Accepts
  `{ id, kind, name, location, embedderProviderId?, embedderModel?, auth? }`.
  `auth` is validated client-side against the discriminated
  `KnowledgeAuthSchema` from `@agentskit/os-core` per kind.
- `knowledge.sources.remove` — cancels job, purges vectors, deletes row.
- `knowledge.sources.rebuild` — cancel + purge + reindex.
- `knowledge.sources.preview` — inline relevance test from the source row.
- `knowledge.status` — aggregate counters in the header.

## Auth shapes (per kind)
- `confluence`: `{ baseUrl, email, apiToken }`
- `notion`: `{ integrationToken }`
- `github`: `{ token }`
- `drive` / `onedrive`: `{ accessToken, refreshToken?, clientId?, clientSecret? }`
- `dropbox`: `{ accessToken }`
- `gcs`: `{ serviceAccountJson }`
- `s3`: `{ accessKeyId, secretAccessKey, region?, endpoint? }`
- `folder` / `url` / `pdf`: no auth.

Auth is envelope-encrypted at rest (AES-256-GCM) when the sidecar wires an
encryptor — see `packages/os-headless/src/knowledge-auth-encryptor.ts`.

SEC-2 (#1665): the encryptor is **fail-secure**. If it cannot be created at
boot (e.g. `<dataDir>/knowledge-auth.key` is unreadable), the sidecar aborts
with `AK_KNOWLEDGE_AUTH_ENCRYPTOR_UNAVAILABLE` rather than silently writing
connector tokens (S3/GCS/Notion/Confluence/GitHub) as plaintext into
`agentskitos.db`. To accept plaintext on a single-tenant dev box with no
cloud knowledge sources, set `AKOS_ALLOW_PLAINTEXT_KNOWLEDGE_AUTH=1`; boot
then proceeds with a loud warning and surfaces an `encryptor-failed`
`StoreDegradeReason` on `runtime.status`.

## Edge cases
- Sidecar refuses `knowledge.sources.preview` / `rag.search` when no default
  embedder is configured (returns `AK_TOOL_NOT_FOUND`). Configure an
  OpenAI-compatible provider in `copilot-config.json` with role `embedder`,
  or set `OPENAI_API_KEY`.
- In dev, dummy embedder runs if `AKOS_RAG_ALLOW_DUMMY=1`.
- Loaders that need OAuth (Drive, OneDrive, Dropbox) accept access tokens
  resolved from the Connections OAuth panel — the form does not perform the
  OAuth dance itself.

Source: /raw/for-agents/screens/knowledge.md

### for-agents/screens/marketplace.md

# Desktop screen — marketplace

## Human guide

[`templates-and-marketplace.mdx`](../../../apps/web/content/docs/using-the-app/templates-and-marketplace.mdx)

## Purpose

Listings browse + install + report + publish. The plugin / pack discovery surface — browse featured + filtered listings, install with publisher-key verification, publish from a built manifest, and submit abuse reports.

## Where

- **Desktop:** `packages/os-desktop/src/screens/marketplace/`

## Wired methods

- `marketplace.listings` / `marketplace.featured` / `marketplace.suggestions` / `marketplace.stats` — discovery surfaces.
- `marketplace.listing.get` — detail page.
- `marketplace.install` / `marketplace.evaluateInstall` / `marketplace.uninstall` / `marketplace.installed.list` — install lifecycle (evaluate runs the pre-flight: permissions, signature, license).
- `marketplace.applyPack` / `marketplace.domainPacks` — vertical pack apply path.
- `marketplace.report` — abuse / quality reports.
- `marketplace.publish` / `marketplace.publish.buildManifest` — publisher flow.
- `marketplace.publisherKeys.list` / `marketplace.publisherKeys.pin` / `marketplace.publisherKeys.revoke` — trust pinning.
- `marketplace.privateLibrary.list` / `marketplace.privateLibrary.add` / `marketplace.privateLibrary.remove` — private (non-public) listings.

## Edge cases

- **Publisher key not pinned** — `marketplace.install` rejects with `untrusted-publisher`; UI shows a "review key" modal sourcing from `marketplace.publisherKeys.list`.
- **License gate** — `marketplace.evaluateInstall` returns `license-required`; UI links to the license screen.
- **Signature mismatch** — install hard-fails with `signature-invalid` (never overrideable in UI).
- **Offline browse** — `marketplace.listings` is cached on disk; "browse cached" mode disables install actions.
- **Private listing access** — `marketplace.privateLibrary.add` requires a one-time invite token; expired token returns `invite-expired`.

Source: /raw/for-agents/screens/marketplace.md

### for-agents/screens/mcp.md

# Desktop screen — mcp (Tools › MCP server registry)

## Human guide

[`tools.mdx`](../../../apps/web/content/docs/using-the-app/tools.mdx) (MCP section)

## Purpose

Model Context Protocol (MCP) server registry. Add, edit, connect,
disconnect, discover, and health-probe MCP servers, and set per-server
auth (bearer / env / header). MCP is the server-registry area of the
`tools` governance screen — not a standalone top-level screen. See
[`tools.md`](./tools.md) for the egress + sandbox siblings.

## Where

- **Desktop:** `packages/os-desktop/src/screens/tools/mcp/`
  (`mcp-view.tsx`, `use-mcp.ts`, `parts/server-list.tsx`,
  `parts/server-form.tsx`, `parts/auth-fields.tsx`)
- **Tests:** `packages/os-desktop/src/screens/tools/__tests__/use-mcp.test.ts`

## Wired methods

- `mcp.servers.list` — render the server registry.
- `mcp.servers.upsert` — add / edit a server definition.
- `mcp.servers.connect` / `mcp.servers.disconnect` — lifecycle.
- `mcp.servers.discover` — scan known config paths for servers.
- `mcp.servers.probe` — health-check a server.
- `mcp.servers.credential.set` — set bearer / env / header auth (write-only).

## Edge cases

- **Probe failure** — `mcp.servers.probe` failure marks the row
  `unreachable`; connect is retried, not auto-removed.
- **Credential never echoed** — `mcp.servers.credential.set` is
  write-only; the UI shows a masked placeholder, never the stored secret.
- **Discover is additive** — `mcp.servers.discover` proposes found
  servers; it never overwrites an existing registered definition.

Source: /raw/for-agents/screens/mcp.md

### for-agents/screens/observability.md

# Desktop screen — observability

## Human guide

[`runs-and-observability.mdx`](../../../apps/web/content/docs/using-the-app/runs-and-observability.mdx)

## Purpose

Status, anomaly rules, exporter wiring, incident triage. Single pane for live runtime health, OTLP exporter configuration, metric time-series, anomaly-rule CRUD, and incident lifecycle (open → ack → resolved).

## Where

- **Desktop:** `packages/os-desktop/src/screens/observability/`

## Wired methods

- `observability.status` — top-card health (sidecar, stores, exporters).
- `observability.metrics.timeseries` — chart payloads (lat / errors / cost).
- `observability.topology.get` — service topology view.
- `observability.anomaly.evaluate` / `observability.anomalyRules.list` / `observability.anomalyRules.upsert` / `observability.anomalyRules.delete` / `observability.anomalyRules.setPaused` — rule CRUD + live eval.
- `observability.exporters.test` — exporter probe ("Test endpoint" button).
- `observability.incidents.get` / `observability.incidents.transition` / `observability.incidents.assign` — incident triage.
- `incidents.list` / `incidents.create` / `incidents.transition` — workspace incident store.
- `anomalies.list` / `anomalies.upsert` / `anomalies.delete` — legacy anomaly entries.
- `workspace.config.exporters.get` / `workspace.config.exporters.set` — exporter creds + endpoint config.

## Edge cases

- **Exporter unreachable** — `observability.exporters.test` returns `connect-failed`; banner stays until a successful test re-clears.
- **Time-series gap** — `observability.metrics.timeseries` returns `null` buckets when the store has no data; chart renders gap (not zero) to avoid misreads.
- **Rule paused** — paused rules still appear in `anomalyRules.list` with `paused: true`; UI greys the row.
- **Self-assigned incident** — `observability.incidents.assign` to self requires no confirmation; assignment to others writes audit.

Source: /raw/for-agents/screens/observability.md

### for-agents/screens/observe.md

# Desktop screen — observe

## Human guide

[`runs-and-observability.mdx`](../../../apps/web/content/docs/using-the-app/runs-and-observability.mdx)

## Purpose

Sidebar **Activity** entry point (nav id `observe`, label "Activity"). Per
ADR-0124 it renders the injected Runs monitor directly — no in-screen tab shell.
Nav aliases `runs`, `traces`, and `observability` remain valid deep-link screen
ids: `runs`/`observe` → this screen; `traces` → TracesScreen;
`observability` → ObservabilityScreen. Audit moved to Governance (A5/#3485).

## Where

- **Desktop:** `packages/desktop-platform-admin/src/screens/observe/index.tsx`
  (renders `../runs`, which is populated by `registerRunsScreen()`)

## Wired methods

None directly. Observe delegates to the Runs screen:

- **Runs** — see [`runs.md`](./runs.md).

Standalone related routes:

- **Traces** — see [`traces.md`](./traces.md).
- **Audit** — see [`audit.md`](./audit.md).
- **Health / Observability** — runtime and incident health surfaces.

## Edge cases

- **Missing Runs registration** — `RunsScreen` is an IoC stub until the host
  bridge calls `registerRunsScreen()`. The fallback renders `null`.
- **No Observe-local filters** — list/card view, query, filters, and selection
  belong to RunsScreen. Do not duplicate them in Observe.
- **Legacy tab params** — old tab-oriented deep links should not recreate an
  in-screen tab shell. Route users to the standalone trace/audit/eval/health
  screens instead.

Source: /raw/for-agents/screens/observe.md

### for-agents/screens/oem.md

# Desktop screen — oem

## Human guide

[`route-only-screens.mdx`](../../../apps/web/content/docs/using-the-app/route-only-screens.mdx) · [`teams.mdx`](../../../apps/web/content/docs/using-the-app/teams.mdx) (Settings › Brand & licensing)

## Purpose

Legacy desktop route kept for deep-link compatibility. The OEM / white-label
control center was consolidated into the platform admin app; the desktop `oem`
route immediately redirects to the assistant so old Settings rail links and
command palette entries do not land on a dead screen.

## Where

- **Desktop compatibility route:** `packages/os-desktop/src/screens/oem/`
  (`index.tsx` exports `OemNotice`, which redirects to `copilot`).
- **Active OEM management:** admin app / platform admin surfaces.

## Wired methods

The legacy route does not issue RPC calls. The underlying contracts remain live
for admin/OEM surfaces and sidecar compatibility.

License:

- `oem.license.import` — import a signed license envelope.
- `oem.license.status` — current license state (valid / grace / expired).

Tenants:

- `oem.tenants.list` — tenant table.
- `oem.tenants.create` / `oem.tenants.update` / `oem.tenants.delete`.
- `oem.tenants.suspend` — suspend / reactivate a tenant.
- `oem.tenants.issueLicense` / `oem.tenants.revokeLicense`.

Packs + white-label:

- `oem.packs.list` / `oem.packs.apply` — vertical-pack catalog + apply.
- `whitelabel.runtime.get` — current runtime white-label projection.
- `whitelabel.cli.run` — run a white-label CLI command (build / doctor).

Marketplace publish:

- `bundles.list` / `bundles.export` / `bundles.import` / `bundles.diff`.

## Edge cases

- **Deep link to `oem`** — redirects to the assistant with `{ source: 'oem' }`.
- **No OEM entitlement** — handled in the admin/OEM surfaces, not this desktop
  compatibility route.
- **Import invalid envelope** — `oem.license.import` rejects a
  malformed / wrong-product / unsigned envelope with a typed license error.
- **Revoke active tenant** — `oem.tenants.revokeLicense` /
  `oem.tenants.delete` are confirm-gated; revoke takes effect at the
  tenant's next license check (grace window applies).
- **Over-seats issue** — `oem.tenants.issueLicense` with seats below
  active usage is rejected; UI surfaces the seat shortfall.

Source: /raw/for-agents/screens/oem.md

### for-agents/screens/pipelines-board.md

# Web/Desktop screen — pipelines kanban board

## Human guide

[`pipelines.mdx`](../../../apps/web/content/docs/using-the-app/pipelines.mdx)

## Purpose

ADR-0032 surface. A `PipelineConfig` is rendered as a kanban board: each `phase`
is a column, each `PipelineItem` is a card. Cards flow across columns; the
column's bound flow may dispatch automatically on enter, on a cron schedule,
on an external trigger, or only when the user clicks "Run now".

## Routes / mount points

- Web: `apps/web/app/app/(shell)/pipelines/[id]/board/page.tsx` —
  server component, fetches `pipelines.get` + `pipelines.items.list`,
  renders `<PipelineBoard>` (`apps/web/components/pipeline-board.tsx`).
- Desktop: `packages/os-desktop/src/screens/pipelines/parts/kanban-tab.tsx` —
  Kanban tab inside the Processes screen (dir is `screens/pipelines/`; nav id
  `pipeline`, label "Processes"). Same shape via `lib/sidecar`.

## Wired methods

- `pipelines.list` / `pipelines.get` / `pipelines.upsert` / `pipelines.delete`
  — board definition CRUD (same as the DAG editor at `/pipelines/[id]`).
- `pipelines.items.list` — cards for a pipeline.
- `pipelines.items.upsert` — create / update a card (also validates
  the destination column exists).
- `pipelines.items.move` — change a card's column + position. If the
  destination column's `executionMode` is `'auto-on-enter'` (or unset
  — that is the legacy default per the ADR migration note), the bound
  flow dispatches and the response carries `dispatched.runId`.
- `pipelines.items.delete` — remove a card.
- `pipelines.items.run` — manual dispatch of the column's bound flow
  for a single card.
- `pipelines.items.scanColumn` — dispatch the bound flow for every
  card currently in the column. Called by the column daemon for
  `scheduled` columns (cron) and `triggered` columns (external event).

## Column execution modes

| `executionMode` | Driver |
|---|---|
| `manual` | User clicks "Run now" on a card. |
| `auto-on-enter` (default) | `pipelines.items.move` dispatches inline. |
| `scheduled` | `startPipelineColumnDaemon` cron scheduler → `scanColumn`. |
| `triggered` | `createPipelineTriggerRouter` matches a webhook / provider event kind → `scanColumn`. |

The router lives in `packages/os-headless/src/pipeline-trigger-router.ts`. The
daemon in `packages/os-headless/src/pipeline-column-daemon.ts`. Both are
booted from the sidecar (`packages/os-headless/src/bin/sidecar.ts`).

## Storage

`packages/os-storage/src/pipeline-item-store.ts` exposes `PipelineItemStore`
with `FilePipelineItemStore` (JSON-file backed) and `InMemoryPipelineItemStore`.
The sidecar always wires `FilePipelineItemStore` to
`<dataDir>/pipeline-items.json` (peer of `pipelines.json`). The whole
persistent-store bundle falls back to `InMemoryPipelineItemStore` only when
`better-sqlite3` is unavailable or `AKOS_DISABLE_SQLITE=1` is set — items
do not depend on SQLite directly.

## Edge cases

- Phases without `executionMode` default to `auto-on-enter` so legacy SDLC
  pipelines parse and run unchanged. See `items.move` handler.
- `scanColumn` requires both `pipelineId` and `columnId` — empty values
  throw `AK_PIPELINE_ITEM_INVALID`.
- Webhook server fires `onTriggerFired` BEFORE `runner.runFlow` is awaited
  so the column fan-out is independent of workspace-level flow success.
- `wipLimit` is a soft cap (badge in UI). Moves are not blocked.
- The DAG editor at `/pipelines/[id]` and the kanban view at
  `/pipelines/[id]/board` edit the **same** `PipelineConfig`. The board is
  not a separate entity.

## Tests

- `packages/os-headless/tests/pipelines-items-handlers.test.ts` — six items
  RPCs incl. legacy `executionMode` default + scheduled/triggered no-auto-
  dispatch + scanColumn.
- `packages/os-headless/tests/pipeline-column-daemon.test.ts` — cron
  registration, external notify, error path, refresh.
- `packages/os-headless/tests/pipeline-trigger-router.test.ts` — kind
  matching, skip cron/file, multi-pipeline fan-out, store-failure
  resilience.
- `packages/os-headless/tests/webhook-server.test.ts` — onTriggerFired
  fires even when runFlow throws.
- `packages/os-desktop/src/screens/pipelines/__tests__/kanban-tab.test.tsx` +
  `column-settings-sheet.test.tsx` — DOM-level board + settings sheet
  coverage.

## Related ADRs

- ADR-0032 (this surface) — `docs/adr/0032-pipelines-as-flexible-kanban.md`.
- ADR-0019 — visual flow editor reused for column → flow binding.
- ADR-0027 — method contract registry where the new RPCs register.
- ADR-0002 — no duplication of AgentsKit primitives (the kanban is a
  view over `PipelineConfig`, not a parallel entity).

Source: /raw/for-agents/screens/pipelines-board.md

### for-agents/screens/plugins.md

# Desktop screen - plugins

## Human guide

[`route-only-screens.mdx`](../../../apps/web/content/docs/using-the-app/route-only-screens.mdx) · [`templates-and-marketplace.mdx`](../../../apps/web/content/docs/using-the-app/templates-and-marketplace.mdx) (Marketplace › Installed)

## Purpose

Installed plugin lifecycle surface. Use this screen when a user asks to inspect,
enable, disable, update, uninstall, or troubleshoot installed plugins after
marketplace installation.

## Where

- **Desktop:** `packages/desktop-operations/src/screens/plugins/`
- **Nav id:** `plugins`
- **Route-only:** reachable from Marketplace -> Installed.

## Wired methods

- `marketplace.installed.list` - list installed plugins and update state.
- `marketplace.install` - install a selected plugin after evaluation.
- `marketplace.uninstall` - remove an installed plugin.
- `plugins.*` - plugin runtime lifecycle and detail methods when wired by the
  sidecar.

## Edge cases

- New installs should start in Marketplace; use Plugins for installed-state
  management.
- Never tell the user to bypass signature or publisher-key checks.
- Disabled or unreachable plugin state should route to detail/troubleshooting,
  not to reinstall as the first answer.

Source: /raw/for-agents/screens/plugins.md

### for-agents/screens/runs.md

# Desktop screen — runs

## Human guide

[`runs-and-observability.mdx`](../../../apps/web/content/docs/using-the-app/runs-and-observability.mdx)

## Purpose

List runs, replay, cancel, view trace. The primary execution-history surface — filterable run list, deep link to the trace timeline, replay against a different model/version, and cancel for in-flight runs.

## Where

- **Desktop:** `packages/os-desktop/src/screens/runs/`
- **Web:** `apps/web/app/app/(shell)/runs/`

## Wired methods

- `runs.list` — paginated history (filters: status, agent, flow, time, trigger).
- `runs.get` — bare run-record fetch (legacy callers).
- `runs.detail` — enriched detail-panel envelope (run row + artifacts, coding outputs, tool calls, spans, eval results, benchmarks) in a single call.
- `runs.cancel` — terminates an in-flight run via the runner state machine.
- `runner.getState` — live state poll while a run is in-flight (`pending | running | paused | awaiting-human | succeeded | failed | cancelled`).
- `runner.cancelRun` / `runner.pause` / `runner.resume` — fine-grained controls.
- `runner.runAgent` / `runner.runFlow` — "Re-run" button.
- `traces.list` / `traces.get` — link to trace timeline.
- `traces.replay` — "Replay with model X" affordance.
- `dispatch.refresh` — soft refresh on tab focus.

## Status model (CON-1 #1679)

The canonical run status is os-core's `RunStatus`
(`queued | running | cancelled | failed | succeeded`) — the Runs screen
imports it; it no longer declares a divergent local copy. A `cancelled`
run is its own terminal state and is **not** collapsed into `failed`.
`UiRunStatus = RunStatus | 'blocked'` adds one UI-only *derived* display
state: `blocked` is rendered for a sidecar row reporting `paused`/`blocked`
(e.g. a HITL gate) and is never a core-emitted status. Use `RunStatus` for
anything modelling the persisted contract; `UiRunStatus` only for render.

## Edge cases

- **Cancelled mid-tool** — `runner.cancelRun` sets `cancelled`; the in-flight tool call still resolves and writes its result, marked `superseded`.
- **Paused at HITL** — `runner.getState` returns `awaiting-human`; UI routes to the inbox screen for decision.
- **Replay with different agent version** — `traces.replay` requires `agentVersion`; passing `latest` is rejected (must be explicit) to keep replays reproducible.
- **Stale list cache** — `runs.list` returns rows with `updatedAt`; UI sorts client-side to handle out-of-order arrivals from concurrent dispatchers.

Source: /raw/for-agents/screens/runs.md

### for-agents/screens/sandbox.md

# Desktop screen - sandbox

## Human guide

[`route-only-screens.mdx`](../../../apps/web/content/docs/using-the-app/route-only-screens.mdx) · [`security.mdx`](../../../apps/web/content/docs/using-the-app/security.mdx)

## Purpose

Sandbox policy, runtime state, flow-preview, and recent denial surface. Use this
screen when a user asks why a tool or workflow was blocked, how isolation is
configured, or whether a flow can run under the active sandbox policy.

## Where

- **Desktop:** `packages/desktop-operations/src/screens/sandbox/`
- **Nav id:** `sandbox`
- **Nav label:** Sandbox

## Wired methods

- `sandbox.state` - active sandbox count and current policy snapshot.
- `sandbox.policy.get` / `sandbox.policy.set` - read/write workspace sandbox policy.
- `sandbox.denials.list` - list recent denied decisions.
- `sandbox.flow.preview` - dry-run a flow against the active sandbox policy.

## Edge cases

- Sandbox denials are policy decisions, not generic failures; explain the
  denied capability/path/egress when available.
- Replay or preview must re-evaluate current policy because approvals can become
  invalid after policy changes.
- For MCP/egress sibling settings, route to Runtime controls or Connected apps.

Source: /raw/for-agents/screens/sandbox.md

### for-agents/screens/sdlc.md

# Desktop screen — sdlc (Processes alias)

## Human guide

[`pipelines.mdx`](../../../apps/web/content/docs/using-the-app/pipelines.mdx)

## Purpose

**Processes** pipeline list + dispatch + gates inbox (nav id `pipeline`, label
"Processes"). Killer-demo surface (PRD → Issues → QA → Dev → Test → PR). This
doc id (`sdlc`) is a **knowledge-map alias** for the `pipeline` ActiveScreen —
see also [`pipelines-board.md`](./pipelines-board.md) for the kanban view.

## Where

- **Nav id:** `pipeline` (sidebar label "Processes")
- **Desktop:** `packages/os-desktop/src/screens/pipelines/` (list + kanban tabs)
- **Human guide:** `apps/web/content/docs/using-the-app/pipelines.mdx`

## Wired methods

Prefer the `pipelines.*` namespace (current). `sdlc.*` methods remain
registered as deprecated aliases with identical handlers.

| Concern | Preferred | Deprecated alias |
|---|---|---|
| Pipeline CRUD / list | `pipelines.list`, `pipelines.get`, `pipelines.upsert` | `sdlc.pipelines.list` |
| Run dispatch / resume | `pipelines.runs.dispatch`, `pipelines.runs.resume`, `pipelines.runs.list` | `sdlc.runs.*` |
| HITL phase gates | `sdlc.gates.list`, `sdlc.gates.decide` | (no `pipelines.gates.*` yet) |
| Bundles | `bundles.list`, `bundles.import`, `bundles.export`, `bundles.diff` | — |

## Edge cases

- Pipeline configs come from `DefaultHandlersOpts.sdlcPipelines`. Without
  registration, dispatch throws `pipeline "<id>" not configured`.
- Resume after a gate requires the gate be marked `approved` first.
- Phase failures stop the pipeline; partial phase results stay in run history.
- Demo bundle at `examples/pipeline-prd-to-pr/`.

Source: /raw/for-agents/screens/sdlc.md

### for-agents/screens/security.md

# Desktop screen — security

## Human guide

[`security.mdx`](../../../apps/web/content/docs/using-the-app/security.mdx)

## Purpose

Sandbox + egress policy editor + break-glass requests. Operator
controls every gate that runs on agent IO.

## Wired methods

- `sandbox.state` — current level + active count + policy snapshot.
- `sandbox.policy.get` / `.set` — read-paths / write-paths / env
  allowlist / network allowlist.
- `sandbox.denials.list` — recent denied decisions.
- `sandbox.flow.preview` — preview decision for hypothetical
  (flowLevel, agentLevel, effects).
- `egress.policy.get` / `.set` — domain allowlist + mode.
- `egress.decisions.list` — allowed/denied egress events.
- `access.breakGlass` — request time-boxed elevation.
- `access.breakGlass.revoke` — manual revoke.
- `access.breakGlass.list` — active + historical grants.

## Edge cases

- Sandbox `level: 'container'` requires Docker on PATH. Probe via
  `runtime.status` before exposing the dropdown.
- Egress policy supports `mode: 'block-by-default'` only when an
  allowlist is non-empty; UI guards the toggle.
- Break-glass writes a signed audit-ledger entry on both grant and
  revoke. The signature is verifiable from the operator's machine
  using the public key shown in the audit footer.

Source: /raw/for-agents/screens/security.md

### for-agents/screens/teams.md

# Desktop screen - teams

## Human guide

[`teams.mdx`](../../../apps/web/content/docs/using-the-app/teams.mdx)

## Purpose

Workspace users and teams administration. Use this screen when a user asks to
create users/teams, invite members, assign or revoke roles, or manage team
membership.

## Where

- **Desktop:** `packages/desktop-operations/src/screens/teams/`
- **Nav id:** `teams`
- **Nav label:** Teams

## Wired methods

- `users.*` - user list, invite, update, and delete operations.
- `teams.*` - team create/update/delete, membership, and role assignment operations.
- `rbac.*` - read role/capability context where needed by controls.

## Edge cases

- Governance/Access is the policy overview; Teams is the editing source for
  users, teams, memberships, and team role assignment.
- Role changes are security-sensitive. Assistants should ask for the target
  user/team and intended role before proposing a mutation.
- Do not infer elevated roles from vague requests like "give access"; clarify
  scope first.

Source: /raw/for-agents/screens/teams.md

### for-agents/screens/templates.md

# Desktop screen — templates

## Human guide

[`route-only-screens.mdx`](../../../apps/web/content/docs/using-the-app/route-only-screens.mdx) · [`templates-and-marketplace.mdx`](../../../apps/web/content/docs/using-the-app/templates-and-marketplace.mdx)

## Purpose

Starter flow templates browser + install. Curated catalog of ready-to-run flows ("PRD → PR", "RAG search", "Slack triage", etc.) — preview the visual graph, customize parameters, install into the active workspace.

## Where

- **Desktop:** `packages/os-desktop/src/screens/templates/`

## UI shell

Wizard header renders through the shared `ScreenHeader` primitive from `@agentskit/os-ui` (issue #1355 F0-7) — `kicker`/`title` from `templates.kicker` / `templates.title` intl keys; the step indicator (`StepDots`) and status message are passed as `actions`. The previous local `HEADER_CLASS` constant was removed (not exported — internal-only).

## Wired methods

- `flows.templates` — list available templates (built-in + pack-supplied).
- `flows.upsertInline` — install button persists the template as a workspace flow.
- `setup.applySampleBundle` — "Install bundle" applies a multi-template bundle.
- `setup.scaffold` — onboarding-style scaffold from a chosen template.
- `flows.fromVisual` / `flows.toVisual` — preview the template in the visual editor.

## Edge cases

- **Name collision** — `flows.upsertInline` rejects duplicate flow `id`; UI auto-suffixes with `-copy` on user confirm.
- **Template requires missing connection** — preview banners which credentials must be configured before run; install still succeeds but the flow is marked `unconfigured`.
- **Pack uninstalled mid-browse** — `flows.templates` re-fetch removes pack-supplied templates; UI shows toast "X templates removed".

Source: /raw/for-agents/screens/templates.md

### for-agents/screens/tools.md

# Desktop screen — tools

## Human guide

[`tools.mdx`](../../../apps/web/content/docs/using-the-app/tools.mdx)

## Purpose

Tool + connection governance hub. Three areas: MCP server registry,
egress policy, and the sandbox tool-call queue (approve / reject / replay).

## Where

- **Desktop:** `packages/os-desktop/src/screens/tools/`
  (`mcp/`, `egress/`, `sandbox/`, `calls/`, `_shared/`, `index.tsx`)

## Wired methods

MCP servers:

- `mcp.servers.list` — render the server registry.
- `mcp.servers.upsert` — add / edit a server definition.
- `mcp.servers.connect` / `mcp.servers.disconnect` — lifecycle.
- `mcp.servers.discover` — scan known config paths for servers.
- `mcp.servers.probe` — health-check a server.
- `mcp.servers.credential.set` — set bearer / env / header auth.

Egress:

- `egress.policy.get` / `egress.policy.set` — domain allowlist + mode.
- `egress.decisions.list` — recent allowed / denied egress events.

Sandbox tool calls:

- `sandbox.state` — current level + active count + policy snapshot.
- `sandbox.policy.get` / `sandbox.policy.set` — sandbox policy.
- `sandbox.denials.list` — recent denied tool decisions.
- `tools.calls.list` — pending + recent tool calls.
- `tools.calls.approve` / `tools.calls.reject` — HITL gate on a call.
- `tools.calls.replay` — re-run a previously approved call.

## Edge cases

- **Egress block-by-default** — `egress.policy.set` to
  `mode: 'block-by-default'` is rejected when the allowlist is empty; UI
  guards the toggle.
- **MCP probe failure** — `mcp.servers.probe` failure marks the row
  `unreachable`; connect is retried, not auto-removed.
- **Credential never echoed** — `mcp.servers.credential.set` is
  write-only; the UI shows a masked placeholder, never the stored secret.
- **Replay after policy change** — `tools.calls.replay` re-evaluates the
  current sandbox/egress policy; a call approved earlier can be denied now.

Source: /raw/for-agents/screens/tools.md

### for-agents/screens/topologies.md

# Desktop screen - topologies

## Human guide

[`route-only-screens.mdx`](../../../apps/web/content/docs/using-the-app/route-only-screens.mdx) · [`agents.mdx`](../../../apps/web/content/docs/using-the-app/agents.mdx) (Agents › collaboration)

## Purpose

Multi-agent topology authoring and run surface. Use this screen when a user asks
how agents collaborate, how to define a topology, or how to run a group of
agents together.

## Where

- **Desktop:** `packages/desktop-operations/src/screens/topologies/`
- **Nav id:** `topologies`
- **Route-only:** reachable from Agents ("How agents collaborate").

## Wired methods

- `topologies.list` - list topology definitions.
- `topologies.upsert` - create or update a topology.
- `topologies.delete` - remove a topology.
- `topologies.run` - run a topology when the sidecar supports execution.

## Edge cases

- Topologies are not the same as individual agents. If the request is about a
  single assistant/persona/provider, route to Agents first.
- For vague collaboration requests, ask what roles are needed, what handoff
  should happen, and what output/result should be produced.
- Route-only status means the assistant should often open Agents unless the user
  explicitly asks for topology details.

Source: /raw/for-agents/screens/topologies.md

### for-agents/screens/traces.md

# Desktop screen — traces

## Human guide

[`runs-and-observability.mdx`](../../../apps/web/content/docs/using-the-app/runs-and-observability.mdx)

## Purpose

Span timeline + cost ticks + firewall hits + replay. Per-run drill-down: span tree with timing, cost overlays, prompt-firewall decisions, tool calls, HITL gates. Source-of-truth view when debugging a failed run.

## Where

- **Desktop:** `packages/os-desktop/src/screens/traces/`

## Wired methods

- `traces.list` — paginated trace index.
- `traces.get` — full span tree + attached events for a single trace.
- `traces.replay` — replay action (optionally swapping model / agent version).
- `tools.calls.list` / `tools.calls.replay` — tool-call rows under each span.
- `tools.calls.approve` / `tools.calls.reject` — approve/reject pending tool calls (HITL).
- `firewall.evaluate` — re-run firewall decision against a span's prompt (debug overlay).
- `cost.itemized` (when present) — per-span cost overlay.

## Edge cases

- **Trace truncated** — large runs cap span count; `traces.get` returns `truncated: true` + `nextCursor` for incremental fetch.
- **Replay across version drift** — if the original agent version is deleted, `traces.replay` rejects unless an explicit replacement is provided.
- **Firewall re-eval drift** — `firewall.evaluate` always uses the current ruleset, not the historical one; UI banners "evaluated against current policy, not run-time policy".
- **Tool call already approved** — `tools.calls.approve` is idempotent; second call returns `already-decided`.

Source: /raw/for-agents/screens/traces.md

### for-agents/screens/triggers.md

# Desktop screen — triggers

## Human guide

[`triggers.mdx`](../../../apps/web/content/docs/using-the-app/triggers.mdx)

## Purpose

CRUD cron / webhook / file-watch / postgres-cdc / email triggers. Single page for the trigger registry — author, toggle, test-fire, and inspect recent fires per trigger.

Detailed kind catalog: see [`docs/for-agents/os-triggers.md`](../os-triggers.md).

## Where

- **Desktop:** `packages/os-desktop/src/screens/triggers/`
- **Web:** `apps/web/app/app/(shell)/triggers/`

## Wired methods

- `triggers.list` — render the table.
- `triggers.get` — detail / edit panel.
- `triggers.upsert` — create / update.
- `triggers.delete` — destructive (confirmation modal).
- `triggers.toggle` — pause / resume.
- `triggers.testFire` — synthetic fire; emits a fake event into the trigger daemon.
- `triggers.recentRuns` — last 50 fires per trigger (links into `runs`).
- `triggers.kinds` — populate the "kind" picker.
- `triggers.contracts` — schema for the selected kind's params (drives form fields).

## Edge cases

- **Cron string invalid** — `triggers.upsert` rejects with Zod issues; UI surfaces inline cron-validation message.
- **Webhook collision** — same `path` + `method` → `upsert` returns `path-in-use`.
- **Test-fire while paused** — `triggers.testFire` honors `paused` state and rejects; UI grays the button.
- **Postgres-CDC slot lost** — `triggers.list` shows `degraded`; the daemon needs to recreate the replication slot before the row re-arms.
- **Email trigger inbox unreachable** — `triggers.list` shows `auth-failed`; user must re-auth via the connections screen.

Source: /raw/for-agents/screens/triggers.md

### for-agents/screens/whitelabel.md

# Desktop screen — whitelabel

## Human guide

[`route-only-screens.mdx`](../../../apps/web/content/docs/using-the-app/route-only-screens.mdx) · [`oem.md`](./oem.md) (legacy id — prefer `oem`)

## Purpose

Brand kit + license envelope editor + vertical pack installer. Tenant-level configuration of identity, tokens, vertical preset, RBAC roles, license envelope, and installed OEM packs.

## Where

- **Desktop:** `packages/os-desktop/src/screens/oem/` (legacy `whitelabel/` redirects here)

## Wired methods

- `whitelabel.runtime.get` — load active `RuntimeConfig` (post-publish snapshot).
- `whitelabel.cli.run` — invoke the `os-whitelabel` build CLI from the UI (tokens + runtime gates + Tauri patch).
- `oem.license.import` / `oem.license.status` — license envelope verification + grace window.
- `oem.packs.list` / `oem.packs.apply` / `oem.packs.uninstall` — vertical pack install lifecycle.
- `oem.tenants.list` / `oem.tenants.create` / `oem.tenants.update` / `oem.tenants.delete` / `oem.tenants.suspend` — multi-tenant control (super-admin).
- `oem.tenants.issueLicense` / `oem.tenants.revokeLicense` — tenant license issuance.
- `runtime.config.get` — read tenant runtime config (from `os-tenant-config`).
- `rbac.roles.get` / `rbac.roles.set` — role + permission editor.

## Edge cases

- **License expired in grace window** — `oem.license.status` returns `grace`; UI banners with days remaining; mutations still allowed.
- **License hard-expired** — `oem.license.status` returns `expired`; all mutations rejected with `AK_LICENSE_EXPIRED`.
- **Pack apply fails mid-flight** — `oem.packs.apply` is transactional; partial install rolls back and surfaces the failed step.
- **CLI run blocked** — `whitelabel.cli.run` requires `superadmin` role; lesser roles get `AK_FORBIDDEN`.
- **Tenant suspended** — `oem.tenants.suspend` flips a flag; runtime gates immediately reject login for that tenant.

Source: /raw/for-agents/screens/whitelabel.md

### for-agents/screens/workspaces.md

# Screen — workspaces

## Human guide

[`workspaces.mdx`](../../../apps/web/content/docs/using-the-app/workspaces.mdx)

## Purpose

The Workspaces screen lets operators create, rename, delete, switch, clone, export, and import workspaces without touching the filesystem directly. It is the primary UI for managing the multi-workspace registry (`~/.agentskitos/workspaces/`) and replaces ad-hoc `workspace.yaml` edits for day-to-day workspace administration.

## Where

- **Desktop:** `packages/os-desktop/src/screens/workspaces/` (nav id `workspace`, label "General")
- **Web:** `apps/web/app/app/(shell)/workspaces/`

Both surfaces render the same logical page. The desktop variant talks to the local sidecar over the Electron IPC transport; the web variant uses the HTTP transport at `/api/rpc`.

## RPC methods consumed

- `workspaces.list` — populate the workspace list on mount and after mutations
- `workspace.get` — load detail/edit panel for the selected workspace
- `workspace.create` — "New workspace" form submit
- `workspace.update` — inline rename or isolation-level change
- `workspace.delete` — delete button (guarded by confirmation dialog)
- `workspace.switch` — "Activate" action on a non-active row
- `workspaces.activate` — legacy activate path; called when `workspace.switch` is unavailable on older sidecars
- `workspaces.clone` — "Duplicate" action; copies agents, flows, and triggers into a new id
- `workspace.export` — "Export" dialog; encrypts secrets when a passphrase is provided
- `workspace.import` — "Import" dialog; decrypts secrets when a passphrase is supplied

## Data flow

```
Workspaces page
  → POST /api/rpc  { method: "workspace.*" | "workspaces.*", params }
    → headless transport (IPC in desktop, HTTP fetch in web)
      → sidecar RPC handler
        → workspace-loader / workspace-writer
          → filesystem  (~/.agentskitos/workspaces/*.{yaml,yml,json})
```

After any mutating call the page re-fetches `workspaces.list` to keep the list consistent with disk state.

## Common tasks

| Task | Method(s) |
|---|---|
| Create a workspace | `workspace.create` |
| Rename a workspace | `workspace.update` |
| Delete a workspace | `workspace.delete` |
| Switch active workspace | `workspace.switch` |
| Clone a workspace | `workspaces.clone` |
| Export a workspace | `workspace.export` |
| Import a workspace | `workspace.import` |

## Failure modes

- **Cannot delete active workspace** — `workspace.delete` rejects with an error when the requested `id` matches the currently-active workspace. The UI should show a prompt to switch to another workspace first.
- **Schema invalid** — `workspace.create` and `workspace.update` validate the `id` field as a slug (`^[a-z0-9][a-z0-9-]*$`, max 64 chars) and `name` as max 120 chars. Validation errors surface as RPC error responses; display them inline on the form field.
- **`AK_WORKSPACE_NOT_FOUND`** — returned by `workspace.get`, `workspace.delete`, `workspace.switch`, and `workspace.update` when the supplied `id` does not match any registered workspace. Trigger a `workspaces.list` refresh to re-sync the list with current disk state.
- **Encrypted export without passphrase** — `workspace.export` with `includeSecrets: true` and no `passphrase` is rejected to prevent emitting plaintext credentials. The export dialog must enforce passphrase input when the "Include secrets" checkbox is on.
- **Encrypted import missing passphrase** — `workspace.import` of a bundle whose `secrets` field is an encrypted blob requires a matching passphrase; without it the import fails with a decryption error.

Source: /raw/for-agents/screens/workspaces.md

### for-agents/sidecar.md

# Sidecar — for agents & plugin authors

The sidecar is the Node 22 host process that executes every AgentsKit workload (flows, agents, tools, triggers). Desktop talks to it via JSON-RPC 2.0; CLI and Web wrap the same handler set through different transports.

## Topology

```
React/Tauri shell  ──invoke('sidecar_request')──▶  Rust SidecarManager  ──stdio JSON-RPC──▶  Node sidecar
                                                       │
                          ◀ Tauri events ('sidecar://…') ┤ pending replay, reconnect, state
                                                       │
HTTP clients (dev/web/CLI) ──POST /rpc (Bearer)──▶  HTTP transport ──┘
```

- **stdio** (`packages/os-headless/src/transport/stdio.ts`) — primary path for Tauri shell.
- **HTTP** (`packages/os-headless/src/transport/http.ts`) — `/rpc`, `/events` (SSE), `/health`. Bearer-token gated when `AKOS_SIDECAR_TOKEN` is set; CORS allowlists `tauri://localhost` + `http://127.0.0.1:1420` by default.

## Wire format

```jsonc
// POST /rpc body
{ "method": "flows.list", "params": {}, "meta": { "caller": { "capabilities": ["flow:read"] } } }

// 200 success
{ "ok": true, "value": <result> }

// 200 dispatch failure (validation, authz, handler threw)
{ "ok": false, "error": { "code": "AK_…", "message": "…", "details": {…} } }
```

The Rust supervisor wraps each handler call in a JSON-RPC envelope (`{ jsonrpc:'2.0', id, method, params, meta }`) and routes responses by `id`.

## Health & protocol

| Method            | Purpose                                                |
|-------------------|--------------------------------------------------------|
| `health.ping`     | Liveness — `{ ok:true, at, version }`                  |
| `health.version`  | Protocol handshake — `{ protocolVersion, buildVersion }` |
| `runtime.status`  | Runner mode, capability scope, eval availability       |

Client calls `verifyProtocolVersion()` at boot; mismatch raises `AK_SIDECAR_VERSION_MISMATCH` instead of dispatching to a stale handler set.

## Error envelope (ADR-0033)

Every transport error carries an `AK_*` code, ICU params, and a `retryable` flag:

| AK code                          | When                                                 |
|----------------------------------|------------------------------------------------------|
| `AK_SIDECAR_UNAVAILABLE`         | Transport down, no envelope received                 |
| `AK_SIDECAR_TIMEOUT`             | Per-request deadline exceeded                        |
| `AK_SIDECAR_CANCELLED`           | Caller AbortSignal fired                             |
| `AK_SIDECAR_VERSION_MISMATCH`    | `protocolVersion` differs from `CLIENT_PROTOCOL_VERSION` |
| `AK_SIDECAR_OVERLOADED`          | Rate limit / concurrency cap; retry after `retryAfterMs` |
| `AK_SIDECAR_AUTH_FAILED`         | Missing/invalid bearer or denied origin              |
| `AK_SIDECAR_WORKSPACE_LOCKED`    | Another instance holds `sidecar.lock`                |
| `AK_SIDECAR_HEARTBEAT_LOST`      | N consecutive `health.ping` failures                 |
| `AK_SIDECAR_PROTOCOL_ERROR`      | Malformed envelope or unknown handler                |

Messages resolve via `@agentskit/os-core` i18n catalog (en/es/pt-BR).

## Lifecycle

| Tauri event                | State transition           |
|----------------------------|----------------------------|
| `sidecar://starting`       | spawn child                |
| `sidecar://connected`      | first response received    |
| `sidecar://disconnected`   | stdout EOF (transient)     |
| `sidecar://reconnecting`   | backoff window between attempts |
| `sidecar://failed`         | `recordRestart()` tripped — auto-restart stopped |
| `sidecar://timeout`        | per-request timeout (does not change state)      |

Crash-loop guard (`createCrashLoopGuard`): max 5 restarts per 60s → mark `failed`. Stability window 5min resets the counter and backoff (base 500ms, ceiling 30s).

Heartbeat: `health.ping` every 10s with 2s timeout; 3 consecutive failures → `onLost` fires (`AK_SIDECAR_HEARTBEAT_LOST`).

Workspace lock: `sidecar.lock` file in `dataDir` with `{ pid, workspace, startedAt }`. Second sidecar boot detects live pid → throws `AK_SIDECAR_WORKSPACE_LOCKED`; stale lock (dead pid) is reclaimed.

## Resource control

All three are **wired into the stdio transport's `handleLine`** and enabled by
default. Disable per concern by passing `false` (`rateLimit`/`concurrency`/`watchdog`)
to `createStdioTransport`, or override the options object.

- **Rate limit** (`createRateLimiter`) — token-bucket keyed by **caller identity** (role + capability set; ungated callers share one `anon` bucket). Default 50 rps, burst 100. Env: `AKOS_SIDECAR_RPS`, `AKOS_SIDECAR_BURST`. Over-budget → JSON-RPC `-32000`, message `AK_SIDECAR_OVERLOADED` with `retryAfterMs`.
- **Concurrency** (`createConcurrencyGuard`) — max in-flight keyed by **method**; default 32. Env: `AKOS_SIDECAR_MAX_INFLIGHT`. Cap exceeded → JSON-RPC `-32000`, `AK_SIDECAR_OVERLOADED` with `retryAfterMs`. Slot released in a `finally`.
- **Watchdog** (`wrapHandlerWithWatchdog`) — `onSlow(method, elapsed)` after `slowMs` (env `AKOS_SIDECAR_SLOW_MS`, default 5000). At `hardMs` (env `AKOS_SIDECAR_HARD_MS`, default 120000) it constructs an `AbortController`, passes `signal` to the handler, calls `abort()`, fires `onHard`, and rejects with `AdapterError(AK_SIDECAR_TIMEOUT)` → JSON-RPC `-32002`.
- **Backpressure** (FND-2 / #1669) — two bounds, always on:
  - *Outbound*: `writeLine` serializes frames and `await`s `'drain'` whenever `output.write()` returns false, so a slow Tauri consumer can't grow an unbounded Node stream buffer. `close()` flushes the queued chain before teardown.
  - *Inbound*: `handleLine` calls are counted; at `AKOS_SIDECAR_MAX_INFLIGHT_LINES` (default 512) `readline` is paused and resumed at the low-water mark (half) — readline does not self-pause, so this is what stops a fast producer spawning unbounded handlers. `done` still resolves on stdin EOF (a hung handler must not block it).
- **PII redaction** (`redactParams`) — `token|secret|password|api_key|authorization|…` keys logged as `***`.
- **Bounded in-process Maps** (MEM-1, `transport/bounded-map.ts` → `evictBoundedMap`) — caches/registries that key by caller, path, node, or tool-call id are size-capped with optional stale-eviction so a long-lived sidecar can't grow unbounded. Applied to rate-limit buckets (idle-swept every 30s, cap 50k), `tools.calls` (terminal entries dropped after 24h, cap 10k), and `self-heal` attempts (cleared on `run:cancelled`, cap 10k). Eviction throttled-warns under `headless:bounded-map`; a dropped entry only costs a recompute, never correctness.

## Mutation outbox

Non-idempotent writes that fail because the transport is unavailable are persisted to `localStorage` (`agentskit.cmdk.outbox` key). On reconnect, `drainOutbox()` replays them in order. The outbox depth is reflected in the metrics gauge (`getOutboxDepth()`).

## Metrics

`subscribeMetrics(fn)` streams a per-method snapshot:

```ts
{ method, count, errors, retries, p50, p95, p99, lastUpdated }
```

Outbox depth surfaces via `getOutboxDepth()` and the same subscription.

## Auth & CORS

Bearer token resolution (client):

1. `window.__AKOS_SIDECAR_TOKEN__` (injected by Tauri main on window bootstrap)
2. `VITE_SIDECAR_TOKEN` build-time env
3. Undefined → auth disabled (dev/test only)

Server reads `AKOS_SIDECAR_TOKEN`. `/health` is unauthenticated by design.

CORS allowlist defaults to `tauri://localhost`, `http://tauri.localhost`, `http://127.0.0.1:1420`, `http://localhost:1420`. Override with `HttpTransportOpts.allowedOrigins` or pass `'*'` (NOT recommended).

## Authoring a handler

1. Declare the method in `@agentskit/os-contracts`:
   ```ts
   export const myMethod = method({
     name: 'plugin.my.method',
     input: z.object({ id: z.string() }),
     output: z.object({ ok: z.boolean() }),
     idempotent: false,
     capsRequired: ['plugin:my:write'],
   })
   ```
2. Register the handler in `createDefaultHandlers` (or via the plugin extension point).
3. Throw an `AgentsKitError` with an AK_* code on failure — the dispatcher converts to an `OsErrorEnvelope` automatically.
4. Idempotent contracts get client-side retry + replay-on-reconnect. Non-idempotents enqueue to the outbox on transport failure.

### Defence-in-depth params validation (FND-4 #1672)

The JSON-RPC dispatcher already `safeParse`s params against the contract's
`input` schema. For **security-critical** handlers, or handlers that can be
invoked **outside the dispatcher** (daemons/schedulers calling the handler map
directly), parse again with the audited `rpc-schemas.ts` schemas:

```ts
import { SecretsSetParams, parseRpcParamsOrThrow } from '../rpc-schemas.js'
const { key, value, scope } = parseRpcParamsOrThrow(SecretsSetParams, input, 'secrets.set')
```

`rpc-schemas.ts` adds constraints the envelope schema intentionally omits —
SCREAMING_SNAKE secret keys, value/scope bounds, an OAuth provider allow-list
aligned with `oauth-hub.ts`. On mismatch it throws
`AgentsKitError(AK_VALIDATION_FAILED)` naming the offending path. Wired today
in `secrets.set`/`secrets.delete`, `oauth.start`/`oauth.revoke`, and the
direct `pipelines.items.scanColumn` / `connections.llmOauthRefresh` call sites
in `bin/sidecar.ts`.

## Troubleshooting matrix

| Symptom                       | Likely cause                          | Action                                                                |
|-------------------------------|----------------------------------------|-----------------------------------------------------------------------|
| `sidecar://failed`            | Crash loop tripped                    | Check logs for fatal handler; restart app to reset guard              |
| `AK_SIDECAR_TIMEOUT`          | Slow handler / blocked event loop     | Inspect metrics p99; consider watchdog hardMs                          |
| `AK_SIDECAR_VERSION_MISMATCH` | Stale client vs newer sidecar         | Rebuild client; bump `CLIENT_PROTOCOL_VERSION`                         |
| `AK_SIDECAR_WORKSPACE_LOCKED` | Another sidecar holds the lock        | Quit other instance, or delete stale `sidecar.lock`                    |
| `AK_SIDECAR_AUTH_FAILED`      | Missing/invalid token or denied origin| Set `AKOS_SIDECAR_TOKEN` + `__AKOS_SIDECAR_TOKEN__` consistently       |
| `AK_SIDECAR_OVERLOADED`       | Rate / concurrency cap hit            | Retry after `retryAfterMs`; raise `AKOS_SIDECAR_RPS` if expected load  |
| `AK_SIDECAR_HEARTBEAT_LOST`   | Event loop wedged                     | Inspect Node sidecar; check for tight sync handler                     |

Source: /raw/for-agents/sidecar.md

### for-agents/whitelabel.md

# Whitelabel — vertical config & nav visibility

Reference doc for agents and contributors working on vertical configuration, page visibility, and RBAC in AgentsKitOS.

Canonical schemas: `packages/os-whitelabel/src/schema-parts/`

---

## Page visibility (`pages`)

### Default mode: `denylist`

Since RFC-0045 (#3353), the default visibility model is **denylist**: all pages are shown unless explicitly listed in `pages.visible`. This replaces the previous allowlist model, where every page had to be explicitly enumerated.

```yaml
# Minimal denylist config — shows everything
pages:
  mode: denylist
  visible: []
```

```yaml
# Hide specific pages in this vertical
pages:
  mode: denylist
  visible:
    - bundles
    - evals
    - tools
```

### Essential pages (always visible)

14 pages are *essential* — they cannot be hidden by any operator config. Attempting to deny an essential page is a parse-time error (`AK_CONFIG_INVALID`).

Canonical source: `ESSENTIAL_PAGE_IDS` in [`packages/os-whitelabel/src/schema-parts/primitives.ts`](../../packages/os-whitelabel/src/schema-parts/primitives.ts).

| PageId | Surface |
|---|---|
| `dashboard` | Home / overview |
| `agents` | Agent management |
| `flows` | Flow editor |
| `pipeline` | SDLC pipeline |
| `observe` | Runs / traces / audit / observability (unified) |
| `inbox` | HITL inbox |
| `assets` | Asset gallery |
| `workspace` | Workspace settings |
| `connections` | Integration connections |
| `config` | Vertical config |
| `governance` | Policy and governance |
| `break-glass` | Emergency access recovery |
| `security` | Security settings |
| `cost` | Usage and billing |

### All available PageIds (post RFC-0045)

```
dashboard  agents  flows  pipeline  observe  inbox  assets
workspace  connections  config  marketplace  coding  cloud
triggers  security  collab  operate  cost  templates
knowledge  governance  break-glass  tools  oem
bundles  evals  compliance
```

> **Removed (breaking, RFC-0045 D10):** `runs`, `traces`, `audit`, `observability` — all folded into `observe`. Configs still using these ids will fail with `AK_CONFIG_INVALID`. Replace them with `observe` or run the SU5 codemod.

### Legacy allowlist migration

Existing configs using `mode: allowlist` continue to work. To migrate:

```yaml
# Before
pages:
  mode: allowlist
  visible:
    - dashboard
    - agents
    - flows
    # ... full list

# After (equivalent)
pages:
  mode: denylist
  visible: []  # deny nothing = show everything
```

If the allowlist was intentionally hiding pages, invert the list: the pages **not** in the old `visible` become the new denylist entries.

### Custom labels

Override the display name of any page for this vertical:

```yaml
pages:
  mode: denylist
  visible:
    - bundles
  customLabels:
    flows: "Playbooks"
    governance: "Compliance Policies"
    assets: "Evidence Vault"
```

Labels are free-form strings and are not validated against i18n keys at parse time; the runtime resolves them via `t(label)` with fallback to the literal string.

---

## RBAC `role.pages` — stays allowlist

`rbac.roles.<role>.pages` is deliberately **allowlist-only** (RFC-0045 D4, least-privilege):

- `pages` config = product surface (what this vertical offers). Denylist default is correct — new features should appear automatically.
- `role.pages` = person scope (what this user may see). Allowlist is correct — new pages are not granted to existing roles until an admin decides to extend them.

```yaml
rbac:
  defaultRole: operator
  roles:
    operator:
      pages: '*'          # all pages this vertical exposes
      capabilities: '*'
    analyst:
      pages:
        - dashboard
        - flows
        - observe
        - assets
        - inbox
      capabilities:
        - runs:read
        - flows:read
        - assets:read
```

Adding a new page to the vertical (denylist config) does not automatically grant it to existing enumerated roles. Update each role's `pages` array explicitly.

---

## Full vertical config example (denylist)

```yaml
# whitelabel.yaml — legal vertical
vertical:
  preset: legal
  starterPacks: []
  terminology:
    flows: "Matter Workflows"
    agents: "Matter Agents"

pages:
  mode: denylist
  visible:
    - bundles
    - evals
    - coding
    - cloud
  customLabels:
    flows: "Playbooks"
    assets: "Evidence Vault"
    governance: "Compliance Policies"

rbac:
  defaultRole: paralegal
  enforcement:
    ui: hide
    rpc: reject
  authProvider: saml
  roles:
    paralegal:
      pages:
        - dashboard
        - agents
        - flows
        - observe
        - inbox
        - assets
      capabilities:
        - runs:read
        - flows:read
        - assets:read
    partner:
      pages: '*'
      capabilities: '*'
```

---

## Schema location

| Symbol | File |
|---|---|
| `PageId`, `ESSENTIAL_PAGE_IDS` | `packages/os-whitelabel/src/schema-parts/primitives.ts` |
| `Pages`, `Rbac`, `Role` | `packages/os-whitelabel/src/schema-parts/vertical-pages-rbac.ts` |
| Runtime filter | `packages/os-desktop/src/whitelabel/use-allowed-screens.ts` |

## Related RFCs

- RFC-0015 — White-label initial design
- RFC-0029 — Data-driven verticals
- RFC-0033 — Config-driven vertical runtime
- **RFC-0045** — Nav visibility denylist default + essentials guard (this feature)

Source: /raw/for-agents/whitelabel.md

## Runtime capability index

# AgentsKitOS — capabilities for agents

Machine-generated from the os-contracts JSON-RPC registry by
scripts/gen-self-describe.mjs. See capabilities.json for the structured
form (with content hash). Each line: <verb> [<side-effect>] (caps) — desc.

verbs: 542

- access.breakGlass [mutating/experimental] (caps: access:break-glass) — Request time-boxed elevation (default role `admin`). Audit-ledger signed on grant and on revoke/expiry.
- access.breakGlass.list [read/experimental] (caps: access:break-glass) — List break-glass grants, optionally filtered by principal and active-only.
- access.breakGlass.revoke [destructive/experimental] (caps: access:break-glass) — Revoke a still-active break-glass grant before its expiry.
- actions.describe [destructive/experimental] (caps: runs:read) — Describe one action by id. Unknown ids fail validation with the list of valid actions.
- actions.list [read/experimental] (caps: runs:read) — List agent-performable actions (intent → canonical RPC + required gates), optionally filtered by entity.
- agent.invoke [destructive/experimental] (caps: runs:write) — Internal agent-to-agent (A2A) invoke: run a registered agent by id and return its output. Same governance as a run (runs:write + real-mode provider gate).
- agent.toolApproval.decide [destructive/experimental] (caps: hitl:decide) — Approve or deny a pending agent tool call (RFC-0028).
- agent.toolApproval.list [read/experimental] (caps: runs:read) — List tool-approval requests awaiting a human decision (RFC-0028).
- agentGen.parse [destructive/experimental] (caps: agents:write) — Parse a natural-language description into a structured AgentIntent.
- agents.applyOverride [destructive/experimental] (caps: agents:write) — Apply a per-session provider+model override for a copilot role; emits an audit event.
- agents.delete [destructive/experimental] (caps: agents:delete) — Remove an inline agent from the active workspace.
- agents.fromNL [destructive/experimental] (caps: agents:write) — Generate a draft AgentConfig from a natural-language description (deterministic v1: keyword/heuristic intent, no LLM). Returns the Phase-3 compiler envelope (artifact + assumptions/warnings/missing/blockedBy/nextActions/confidence) with calibrated model-tier/tools/system-prompt defaults.
- agents.generate [destructive/experimental] (caps: agents:write) — Generate a draft agent from a natural-language description; gates ambiguous prompts via RFC-0009 clarity questions.
- agents.get [read/experimental] (caps: agents:read) — Fetch a single inline agent by id; null when absent.
- agents.import [destructive/experimental] (caps: agents:write) — Parse + validate an agent manifest (file or URL). dryRun=true returns the parsed definition without persisting.
- agents.importFromRegistry [destructive/experimental] (caps: agents:write) — Fetch a ready agent from the AgentsKit registry by id, translate it to an inline agent, and (dryRun=false) persist it to the workspace.
- agents.list [read/experimental] (caps: agents:read) — List inline agents declared in the active workspace.
- agents.overrides.delete [destructive/experimental] (caps: agents:write) — Clear the persisted override for (sessionId, role).
- agents.overrides.get [read/experimental] (caps: agents:read) — Get the active override for (sessionId, role), or null.
- agents.overrides.list [read/experimental] (caps: agents:read) — List persisted per-session agent overrides.
- agents.registry.list [read/experimental] (caps: agents:read) — List the agents available in the configured AgentsKit registry (empty when AKOS_AGENT_REGISTRY is unset/unreachable).
- agents.setProductionStatus [destructive/experimental] (caps: agents:write) — Enable or disable an agent (RFC-0048 productionStatus); 'paused' blocks execution. Appends an audit event.
- agents.transition [mutating/experimental] (caps: agents:write) — Move an agent between ADR-0020 lifecycle states; appends an audit event.
- agents.upsert [mutating/experimental] (caps: agents:write) — Insert or update an inline agent.
- agents.validateDetailed [destructive/experimental] (caps: agents:read) — Semantic validation of an agent draft against the live tool/skill/provider catalogs. Returns self-correctable AuthoringIssues (where/what/how-to-fix/route) so a weak LLM can fix its own output.
- agents.versions.diff [destructive/experimental] (caps: agents:read) — Diff two agent version snapshots. Defaults toVersionId=live.
- agents.versions.get [read/experimental] (caps: agents:read) — Fetch a specific agent version snapshot by id; null when absent.
- agents.versions.list [read/experimental] (caps: agents:read) — List immutable version snapshots for an agent (newest first) + the live pointer.
- agents.versions.rollback [destructive/experimental] (caps: agents:rollback) — Pin the live pointer back to a prior snapshot by minting a new version with its payload.
- anomalies.delete [destructive/experimental] (caps: observability:write) — Remove an anomaly rule.
- anomalies.list [read/stable] (caps: observability:read) — List anomaly detections, optionally filtered to active ones.
- anomalies.upsert [mutating/experimental] (caps: observability:write) — Insert or update an anomaly rule.
- assets.compare [destructive/experimental] (caps: runs:read) — Field-level diff between two artifact versions; null when either id is unknown.
- assets.delete [destructive/experimental] (caps: runs:write) — Delete one or more artifacts by id. Returns the count removed.
- assets.get [read/experimental] (caps: runs:read) — Get one artifact with its full renderable view. Null when absent.
- assets.list [read/experimental] (caps: runs:read) — Paginated, filterable list of artifacts across runs — the cross-vertical Asset Gallery feed.
- assets.versions [destructive/experimental] (caps: runs:read) — List every version of one logical asset (shared lineageKey), ordered oldest → newest.
- audit.batchHash [destructive/experimental] (caps: audit:read) — Compute the canonical sha256 digest of an audit batch.
- audit.entries.list [read/experimental] (caps: audit:read) — List audit ledger entries with optional actor / kind / time filters.
- audit.entries.verify [destructive/experimental] (caps: audit:read) — Verify the signed audit chain end-to-end and report the first break.
- audit.signedBatch [destructive/experimental] (caps: audit:admin) — Sign an audit batch with the workspace Ed25519 audit key.
- audit.verifyIntegrity [destructive/experimental] (caps: audit:read) — Verify a signed audit batch against a public key.
- auth.device.poll [destructive/experimental] (caps: none) — Poll for the verdict of an in-flight device-code flow.
- auth.device.refresh [destructive/experimental] (caps: none) — Exchange a refresh token for a fresh access token (CLI session renewal).
- auth.device.start [destructive/experimental] (caps: none) — Start an OAuth device-code flow for CLI login.
- authoring.clarify [destructive/experimental] (caps: runs:read) — Turn validation issues into actionable clarification questions (with suggested answers / screen routes) so missing inputs can be resolved in chat. Applies nothing.
- authoring.dryRun [destructive/experimental] (caps: runs:read) — Side-effect-free simulation of an authoring action: what it would create/modify, external calls, estimated cost, missing inputs. Gate before apply.
- authoring.plan [destructive/experimental] (caps: runs:read) — Deterministic planner: derive entities/actions needed, missing inputs/capabilities, and whether it is safe to continue in chat — before any artifact is generated. Applies nothing.
- authoring.preview [destructive/experimental] (caps: runs:read) — Human-readable, deterministic preview of an artifact (agent/flow/pipeline/config) before apply: title, summary, sections, risks, side effects, outputs. Pure projection; no external calls.
- authoring.repair [destructive/experimental] (caps: runs:read) — Integrated repair loop: deterministically apply self-heal patches to resolve auto-fixable validation issues, explain each change, and report remaining blockers. Re-validates the draft end-to-end. No external calls, no LLM.
- backup.create [mutating/experimental] (caps: runs:read) — Create a consistent online disaster-recovery backup from the live sidecar.
- billing.invoices.list [read/stable] (caps: billing:read) — List historical invoices when cloud sync is enabled.
- billing.plan.get [read/stable] (caps: billing:read) — Fetch the current billing plan when cloud sync is enabled.
- billing.portal.create [mutating/stable] (caps: billing:read) — Mint a Stripe Billing Portal session for tenant self-service.
- bundles.diff [destructive/experimental] (caps: runs:read) — Compute a key-level diff between two bundle JSON files.
- bundles.export [destructive/experimental] (caps: sdlc:write) — Export the current workspace as a bundle JSON file.
- bundles.import [destructive/experimental] (caps: sdlc:write) — Import a bundle JSON file. Use dryRun:true for a preview without applying.
- bundles.list [read/experimental] (caps: runs:read) — List bundles available in the workspace bundles dir.
- capabilities.catalog.list [read/experimental] (caps: workspace:config) — List the deterministic capability catalog (capabilities + vendor equivalences).
- capabilities.resolve [destructive/experimental] (caps: workspace:config) — Resolve a capability to a connected vendor for the active workspace.
- cloud-sync.conflicts.list [read/experimental] (caps: runs:read) — List pending sync conflicts.
- cloud-sync.conflicts.resolve [destructive/experimental] (caps: runs:write) — Resolve a sync conflict by picking local or remote.
- cloud-sync.history [destructive/experimental] (caps: runs:read) — Recent sync events (persisted, paginated).
- cloud-sync.pause [destructive/experimental] (caps: workspace:config) — Pause cloud sync.
- cloud-sync.resume [destructive/experimental] (caps: workspace:config) — Resume cloud sync.
- cloud-sync.status [destructive/experimental] (caps: runs:read) — Current cloud-sync state and last-synced timestamp.
- cloud.status [destructive/experimental] (caps: runs:read) — Report whether the workspace is configured against a cloud control plane and which endpoint it points at.
- cloud.syncVault [destructive/experimental] (caps: cloud:admin) — Push the local vault to the configured cloud control plane.
- cloud.toggleRemoteCron [destructive/experimental] (caps: cloud:admin) — Enable or disable cloud-side scheduling for the active workspace.
- cloud.vaultHistory [destructive/experimental] (caps: cloud:admin) — List recent vault snapshots from the cloud control plane (newest first).
- cloud.vaultRestore [destructive/experimental] (caps: cloud:admin) — Restore the local vault from a prior cloud snapshot and move HEAD.
- cmdk.commands.list [read/experimental] (caps: runs:read) — List the static palette commands (Navigate / Create / Run / Manage / Help).
- cmdk.search [read/experimental] (caps: runs:read) — Universal palette search. Returns ranked, dispatch-tagged hits across entity stores + the static command catalogue.
- coding.benchmark [destructive/experimental] (caps: coding:write) — Run the same coding task against multiple providers and report per-provider rows. Defaults to dry-run; pass `dryRun:false` to actually apply edits.
- coding.cancelTask [destructive/experimental] (caps: coding:write) — Cooperatively cancel an in-flight coding-agent task by runId. Returns `cancelled:false` when no such run exists or the provider does not support cancellation.
- coding.delegate [destructive/experimental] (caps: coding:write) — Run a coordinator-led delegation: each shard is sent to its named provider; returns per-shard rows. Sequential by default; pass `parallel:true` to fan out.
- coding.permissionProfiles [destructive/experimental] (caps: coding:write) — List sandbox permission profiles available to the coding-agent runner.
- coding.permissionProfiles.delete [destructive/experimental] (caps: coding:write) — Remove a coding-agent permission profile.
- coding.permissionProfiles.upsert [mutating/experimental] (caps: coding:write) — Insert or update a coding-agent permission profile.
- coding.providers [destructive/experimental] (caps: coding:write) — List built-in coding-agent providers with availability + capability info.
- coding.runConformance [destructive/experimental] (caps: coding:write) — Run the conformance suite (#374) against a coding-agent provider. Returns the structured report used for marketplace verification. Emits `coding.conformance.started`, `coding.conformance.check`, and `coding.conformance.finished` events.
- coding.runTask [destructive/experimental] (caps: coding:write) — Run a one-shot coding-agent task with the named provider and permission profile. Emits `coding.task.started` / `coding.task.finished` notifications on the events channel.
- collab.accept [destructive/experimental] (caps: collab:write) — Accept an invite.
- collab.invite [destructive/experimental] (caps: collab:write) — Send a teammate invite.
- collab.invites.list [read/experimental] (caps: collab:write) — List pending teammate invites.
- collab.shares.create [mutating/experimental] (caps: collab:write) — Create an outbound collab share for a resource.
- collab.shares.list [read/experimental] (caps: collab:read) — List inbound / outbound collab shares.
- collab.shares.revoke [destructive/experimental] (caps: collab:write) — Revoke an outbound collab share.
- compliance.dsar.create [mutating/experimental] (caps: compliance:write) — Queue a Data Subject Access or Erasure request. Erasure refuses on active legal hold.
- compliance.dsar.list [read/experimental] (caps: compliance:read) — List Data Subject Access / Erasure requests.
- compliance.dsar.status [destructive/experimental] (caps: compliance:read) — Get the status of a DSAR request by id.
- compliance.export [destructive/experimental] (caps: compliance:export) — Build a signed compliance export bundle for a regulatory regime.
- compliance.gc.run [destructive/experimental] (caps: compliance:write) — Run the cloud-retention GC sweep.
- compliance.gc.status [destructive/experimental] (caps: compliance:read) — Read the last cloud-retention GC execution status.
- compliance.legalHold.list [read/experimental] (caps: compliance:read) — List litigation/preservation legal holds.
- compliance.legalHold.put [destructive/experimental] (caps: compliance:write) — Place a legal hold on a workspace or data subject.
- compliance.legalHold.release [destructive/experimental] (caps: compliance:write) — Release an existing legal hold.
- compliance.prune.run [destructive/experimental] (caps: compliance:write) — Prune run records older than `maxAgeDays`. Skips workspaces under an active legal hold.
- compliance.prune.status [destructive/experimental] (caps: compliance:read) — Read the last run-history prune execution status.
- connections.completeOauth [destructive/experimental] (caps: connections:write) — Exchange an OAuth code for a token + persist via the keychain bridge.
- connections.email.config.get [read/experimental] (caps: connections:read) — Return the persisted SMTP transport config for the email output sink (secret-refs only).
- connections.email.config.set [destructive/experimental] (caps: connections:write) — Persist the SMTP transport config for the email output sink. `usernameSecret` / `passwordSecret` are vault key names, never plaintext credentials.
- connections.list [read/experimental] (caps: connections:read) — List every LLM provider with current credential / verify state.
- connections.llmOauthComplete [destructive/experimental] (caps: connections:write) — Exchange a PKCE OAuth code for an LLM provider API key.
- connections.llmOauthRefresh [destructive/experimental] (caps: connections:write) — Refresh a stored LLM OAuth access token using its refresh_token.
- connections.llmOauthStart [destructive/experimental] (caps: connections:write) — Begin a public-client PKCE OAuth flow for an LLM provider (e.g. OpenRouter).
- connections.outputSinks.delete [destructive/experimental] (caps: connections:write) — Delete an output sink by id.
- connections.outputSinks.list [read/experimental] (caps: connections:read) — List all configured output sinks.
- connections.outputSinks.upsert [mutating/experimental] (caps: connections:write) — Create or update an output sink.
- connections.startOauth [destructive/experimental] (caps: connections:write) — Begin the OAuth flow for a provider that needs cloud credentials.
- connections.tokens.get [read/experimental] (caps: secrets:read) — Resolve a stored OAuth grant into a masked hint + vault reference (never the raw token) for a provider/account pair.
- connections.verify [destructive/experimental] (caps: connections:write) — Run a 1-token completion to confirm the provider credentials work.
- connections.webhook.config.get [read/experimental] (caps: connections:read) — Return the persisted webhook transport config for the webhook output sink (secret-refs only).
- connections.webhook.config.set [destructive/experimental] (caps: connections:write) — Persist the webhook transport config for the webhook output sink. `signingSecret` is a vault key name, never the plaintext secret.
- consent.grant [destructive/experimental] (caps: compliance:write) — Create a break-glass consent grant with an explicit expiry.
- consent.list [read/experimental] (caps: compliance:read) — List break-glass consent grants (active by default).
- consent.revoke [destructive/experimental] (caps: compliance:write) — Revoke an active consent grant before its TTL expires.
- control.context.resolve [destructive/experimental] (caps: control:read) — Resolve the canonical ControlPlaneContext for the caller.
- control.context.whoami [destructive/experimental] (caps: control:read) — Compact identity/org/plan/license/caps summary (CLI whoami, desktop preflight).
- control.devices.list [read/experimental] (caps: control:read) — List the caller's device installs.
- control.devices.revoke [destructive/experimental] (caps: rbac:admin) — Revoke a device install (lost/stolen device).
- control.entitlement.get [read/experimental] (caps: control:read) — Read the reconciled EffectiveEntitlement for an org.
- control.memberships.list [read/experimental] (caps: control:read) — List the caller's tenant memberships.
- control.roles.simulate [destructive/experimental] (caps: control:read) — Simulate which methods a role (cap set) may call — preview-as before publishing.
- control.sessions.list [read/experimental] (caps: control:read) — List the caller's active sessions.
- control.sessions.revoke [destructive/experimental] (caps: rbac:admin) — Revoke a session (logout / SCIM deprovision).
- control.tenant.readiness [destructive/experimental] (caps: control:read) — Evaluate whether a tenant is ready to operate (blockers/warnings/actions).
- control.tenants.switch [destructive/experimental] (caps: control:read) — Switch active tenant — honored only with an active membership (server-authoritative).
- copilot.agent.author [destructive/experimental] (caps: copilot:write) — Deliberately author an agent from scratch / a template / an import: draft, validate; stops at the HITL gate.
- copilot.agent.decide [destructive/experimental] (caps: copilot:write) — Resolve the agent HITL gate: approve (→ committed/activated) or decline (→ rejected).
- copilot.agent.templates [destructive/experimental] (caps: copilot:write) — List the curated agent-template catalog available to copilot.agent.author { from_template }.
- copilot.config.get [read/experimental] (caps: copilot:admin) — Read the persisted CopilotConfig (null if onboarding not done).
- copilot.config.set [destructive/experimental] (caps: copilot:admin) — Persist a validated CopilotConfig.
- copilot.integration.setup [destructive/experimental] (caps: copilot:write) — Deliberately connect an integration: resolve from the catalog, guide, OAuth/secret handoff, verify; emits assistant.integration.* progress.
- copilot.mention.parse [destructive/experimental] (caps: copilot:write) — Parse @-mentions out of a chat message.
- copilot.nl.route [destructive/experimental] (caps: copilot:write) — Route a natural-language prompt (no leading slash) to clarify, match, or synthesize.
- copilot.pipeline.author [destructive/experimental] (caps: copilot:write) — Deliberately create or edit a pipeline from a goal: draft, enforce flows, validate; stops at the HITL gate (assistant.pipeline.awaiting_approval).
- copilot.pipeline.decide [destructive/experimental] (caps: copilot:write) — Resolve the pipeline HITL gate: approve (→ committed) or decline (→ rejected).
- copilot.powers.grant [destructive/experimental] (caps: copilot:powers) — Grant additional caps to the copilot principal (signed + audited).
- copilot.powers.list [read/experimental] (caps: copilot:powers) — List capability grants currently held by the copilot principal.
- copilot.proactive.fromEvent [destructive/experimental] (caps: copilot:write) — Turn a sidecar event (budget threshold, firewall block, run failure, anomaly) into a proactive action card, or null if not actionable.
- copilot.proposal.decide [destructive/experimental] (caps: copilot:write) — Record a proposal decision on a session; returns updated session.
- copilot.session.cancel [destructive/experimental] (caps: copilot:write) — Request cancellation of an in-flight copilot dispatch.
- copilot.session.create [mutating/experimental] (caps: copilot:write) — Create a new copilot conversation session.
- copilot.session.delete [destructive/experimental] (caps: copilot:write) — Remove a copilot session and abort any in-flight dispatch.
- copilot.session.get [read/experimental] (caps: copilot:write) — Fetch a single copilot session by id.
- copilot.session.list [read/experimental] (caps: copilot:write) — List copilot sessions for a workspace.
- copilot.session.send [destructive/experimental] (caps: copilot:write) — Send a user message; copilot dispatches LLM + classifies proposals.
- copilot.slash.list [read/experimental] (caps: copilot:write) — List supported copilot slash commands and their dispatch methods.
- copilot.slash.parse [destructive/experimental] (caps: copilot:write) — Parse a chat message for a leading slash command; returns the dispatch method.
- copilot.smoke [destructive/experimental] (caps: copilot:admin) — Smoke-test a provider/model combination via the dispatch path.
- copilot.workflow.author [destructive/experimental] (caps: copilot:write) — Deliberately author a workflow from a goal: draft, validate, check integrations, dry-run; emits assistant.workflow.* progress.
- cost.alerts.list [read/experimental] (caps: cost:read) — List active cost alerts derived from budget consumption.
- cost.alerts.mute [destructive/experimental] (caps: cost:alert:write) — Mute or unmute a cost alert by id.
- cost.breakdown [destructive/experimental] (caps: cost:read) — Aggregate cost rows by provider / role / workspace.
- cost.budgets.delete [destructive/experimental] (caps: cost:budget:write) — Delete a cost budget by id.
- cost.budgets.evaluate [destructive/experimental] (caps: cost:read) — Evaluate budgets against an estimate; block when an over-budget rule has action=block.
- cost.budgets.list [read/experimental] (caps: cost:read) — List configured budgets with current consumption + status.
- cost.budgets.upsert [mutating/experimental] (caps: cost:budget:write) — Insert or update a cost budget.
- cost.list [read/experimental] (caps: cost:read) — List itemized cost rows for filtering / CSV export.
- cost.reset [destructive/experimental] (caps: observability:write) — Reset the workspace cost meter window.
- cost.spendPolicy.get [read/experimental] (caps: cost:read) — Read the account-level spend policy.
- cost.spendPolicy.set [destructive/experimental] (caps: cost:budget:write) — Update the account-level spend policy.
- cost.summary [destructive/experimental] (caps: cost:read) — Aggregate cost over a window, broken down by provider + agent.
- dashboard.stats [destructive/experimental] (caps: runs:read) — Aggregate counters for the home dashboard.
- demo.seed.materialise [destructive/experimental] (caps: workspace:config) — Materialise the legacy DEMO_SEED bundle for a vertical into the sidecar agent/flow/pipeline stores. Backs `agentskit-os seed --vertical <id>`.
- demo.seed.reset [destructive/experimental] (caps: workspace:config) — Delete every `demo:`-prefixed row from the agent/flow/pipeline stores. Backs `agentskit-os seed --reset`.
- demo.seed.runs [destructive/experimental] (caps: workspace:config) — Dev-only — inject fully-populated demo runs (varied statuses + multi-span traces + artifacts) into the run/trace/artifact stores so the Observe run-monitor can be exercised without executing flows.
- dispatch.refresh [destructive/experimental] (caps: connections:write) — Re-read provider credentials from the file vault + env and rebuild the dispatch registry.
- egress.decisions.list [read/experimental] (caps: security:admin) — Recent egress decisions (most recent first).
- egress.policy.get [read/experimental] (caps: security:admin) — Read the active egress policy.
- egress.policy.set [mutating/experimental] (caps: security:admin) — Replace the active egress policy.
- evals.results.get [read/experimental] (caps: evals:read) — Get an eval result by id.
- evals.results.list [read/experimental] (caps: evals:read) — List recent eval results, optionally filtered by suite.
- evals.run [destructive/experimental] (caps: evals:write) — Execute every case in the suite against the wired flow runner; persist + return the verdict row.
- evals.suites.delete [destructive/experimental] (caps: evals:write) — Delete an eval suite.
- evals.suites.get [read/experimental] (caps: evals:read) — Get a single eval suite by id.
- evals.suites.list [read/experimental] (caps: evals:read) — List every eval suite in the workspace.
- evals.suites.upsert [mutating/experimental] (caps: evals:write) — Create or update an eval suite.
- firewall.blocks.list [read/experimental] (caps: security:admin) — Recent prompt-firewall blocks (most recent first).
- firewall.evaluate [destructive/experimental] (caps: security:admin) — Evaluate a prompt against a firewall tier; returns allow + matched rules.
- firewall.rules.delete [destructive/experimental] (caps: security:admin) — Delete a firewall rule by id.
- firewall.rules.list [read/experimental] (caps: security:admin) — List firewall rules, optionally filtered by tier.
- firewall.rules.test [destructive/experimental] (caps: security:admin) — Test a pattern against sample text; returns match result and snippet.
- firewall.rules.upsert [mutating/experimental] (caps: security:admin) — Create or update a firewall rule.
- firewall.tiers [destructive/experimental] (caps: security:admin) — List the prompt-firewall tier identifiers in declaration order.
- flows.deleteInline [destructive/experimental] (caps: flows:delete) — Remove an inline flow.
- flows.fromNL [destructive/experimental] (caps: flows:write) — Generate a draft FlowConfig from a natural-language description (deterministic v1: keyword/structure heuristics, no LLM). Returns the Phase-3 compiler envelope (artifact + assumptions/warnings/missing/blockedBy/nextActions/confidence) covering agent/rag/condition/human/notify/parallel node kinds.
- flows.fromVisual [destructive/experimental] (caps: flows:write) — Convert a visual editor document back into a FlowConfig.
- flows.listInline [destructive/experimental] (caps: flows:read) — List inline flows declared in the active workspace.
- flows.nodeKinds.describe [destructive/experimental] (caps: flows:read) — Describe a single runtime flow node kind. Unknown kinds fail validation with the list of valid kinds.
- flows.nodeKinds.list [read/experimental] (caps: flows:read) — List every runtime flow node kind with agent-visible metadata (label, category, defaults, required keys, output shape, example).
- flows.snapshots.delete [destructive/experimental] (caps: flows:delete) — Remove a snapshot by id.
- flows.snapshots.diff [destructive/experimental] (caps: flows:read) — Pure structural diff between two VisualFlow values.
- flows.snapshots.list [read/experimental] (caps: flows:read) — List named snapshots for a flow, newest first.
- flows.snapshots.restore [destructive/experimental] (caps: flows:read) — Fetch a snapshot by id and return its preserved VisualFlow.
- flows.snapshots.save [destructive/experimental] (caps: flows:write) — Create a new named snapshot of the current visual flow.
- flows.templates [destructive/experimental] (caps: flows:read) — List the starter flow templates surfaced by the desktop flow editor.
- flows.toVisual [destructive/experimental] (caps: flows:read) — Convert a FlowConfig into the visual editor document representation.
- flows.upsertInline [destructive/experimental] (caps: flows:write) — Insert or update an inline flow.
- flows.validateDetailed [destructive/experimental] (caps: flows:read) — Semantically validate a draft FlowConfig (graph, references, dialect, placeholders) and return structured, self-correctable authoring issues. Goes beyond Zod parsing.
- github.createComment [destructive/experimental] (caps: connections:write) — Create a comment on a GitHub issue or pull request via the GitHub REST API.
- governance.operatorRoles.list [read/experimental] (caps: rbac:admin) — List the canonical operator-role policies (screens + actions per role).
- governance.posture [destructive/experimental] (caps: observability:read) — Live governance posture in one read: air-gap, firewall, PII, sandbox, RBAC mode, egress, audit.
- harness.audit.list [read/experimental] (caps: audit:read) — List harness audit entries for an agent (recent first).
- harness.end [destructive/experimental] (caps: agents:write) — Close a harness session and release resources.
- harness.run [destructive/experimental] (caps: agents:write) — Execute the harness session opened by harness.start. Trace mode runs in this PR; budget/real wiring follows.
- harness.start [destructive/experimental] (caps: agents:write) — Open a harness session for an agent definition. Modes: trace (no LLM), budget (capped), real.
- health.ping [none/stable] (caps: none) — Liveness probe. Returns sidecar timestamp + version. No side effects.
- hitl.channelReply [destructive/experimental] (caps: hitl:decide) — Resolve a HITL escalation from an external-channel reply (RFC-0022 SU6/SU7), matched by correlationId or by the persisted connection+thread binding. Ambiguous replies are ignored.
- hitl.deadLetter.list [read/experimental] (caps: none) — List HITL escalations dead-lettered by a decision-SLA timeout (ADR-0070), pending out-of-band human triage.
- hitl.decide [destructive/experimental] (caps: hitl:decide) — Resolve a HITL task with an approve/reject decision.
- hitl.escalation.decide [destructive/experimental] (caps: hitl:decide) — Record a decision on a HITL escalation; advances chain.
- hitl.escalation.get [read/experimental] (caps: runs:read) — Fetch a single HITL escalation by id.
- hitl.escalation.list [read/experimental] (caps: runs:read) — List HITL escalations (RFC-0008) with optional workspace filter.
- hitl.get [read/experimental] (caps: runs:read) — Read a single HITL escalation row by id.
- hitl.ledger.append [destructive/experimental] (caps: hitl:decide) — Append a signed entry to the HITL ledger chain (audit-log).
- hitl.ledger.list [read/experimental] (caps: audit:read) — List signed HITL ledger entries for audit.
- hitl.ledger.verify [destructive/experimental] (caps: audit:read) — Verify the signed HITL ledger chain — sha-chain + signatures.
- hitl.list [read/experimental] (caps: none) — List human-in-the-loop tasks, optionally filtered by status.
- hitl.modify [destructive/experimental] (caps: hitl:decide) — Submit a counter-proposal (RFC-0008 modify) — resolves the escalation as modified.
- hitl.reassign [destructive/experimental] (caps: hitl:decide) — Reassign a pending HITL task to a different actor without resolving it.
- import.wizard.convert [destructive/experimental] (caps: flows:write) — Structurally import a third-party workflow, then LLM-enrich each warning into a reviewable resolution card.
- import.wizard.detect [destructive/experimental] (caps: none) — Identify which third-party tool a pasted workflow blob came from.
- import.wizard.regenerate [destructive/experimental] (caps: flows:write) — Re-run the LLM enrichment for a single import warning.
- incidents.create [mutating/experimental] (caps: observability:write) — Open a new incident. Fields beyond the required minimum pass through unchanged.
- incidents.list [read/experimental] (caps: observability:read) — List incidents, optionally filtered by status.
- incidents.transition [destructive/experimental] (caps: observability:write) — Move an incident to a new status (e.g. acknowledged → mitigated → resolved).
- integrations.catalog.actions [destructive/experimental] (caps: connections:read) — Get available setup actions for one product integration.
- integrations.catalog.context [destructive/experimental] (caps: connections:read) — Get safe assistant context for one product integration.
- integrations.catalog.filters [destructive/experimental] (caps: connections:read) — List filter options available in the canonical integration catalog.
- integrations.catalog.get [read/experimental] (caps: connections:read) — Get one canonical product integration definition by id.
- integrations.catalog.list [read/experimental] (caps: connections:read) — List the canonical product integration catalog for UI and assistant setup flows.
- integrations.catalog.transition [destructive/experimental] (caps: connections:write) — Run one safe setup transition for a product integration.
- integrations.connections.delete [destructive/experimental] (caps: connections:write) — Remove a Connection. Does NOT delete referenced secrets.
- integrations.connections.get [read/experimental] (caps: connections:read) — Read a single Connection by id.
- integrations.connections.installations.complete [destructive/experimental] (caps: connections:write) — Persist a provider-specific tenant app/bot installation after the provider redirects or confirms the install.
- integrations.connections.installations.health [destructive/experimental] (caps: connections:read) — Check whether a tenant app/bot installation is currently usable without exposing its token.
- integrations.connections.installations.list [read/experimental] (caps: connections:read) — List tenant app/bot installations for a workspace without returning raw tokens.
- integrations.connections.installations.revoke [destructive/experimental] (caps: connections:write) — Mark a tenant app/bot installation token as revoked without exposing the token.
- integrations.connections.installations.start [destructive/experimental] (caps: connections:write) — Begin a provider-specific tenant app/bot installation flow for GitHub App or Discord bot installs.
- integrations.connections.installations.status [destructive/experimental] (caps: connections:read) — Read safe lifecycle metadata for a tenant app/bot installation. Omitting installationId returns the most recent provider installation.
- integrations.connections.list [read/experimental] (caps: connections:read) — List Connection records (ADR-0041). Distinct from connections.list which targets only LLM providers.
- integrations.connections.preflight [destructive/experimental] (caps: connections:read) — Readiness probe for an operator about to dispatch a pipeline: lists every Connection in the workspace whose `state` is not 'configured' with an actionable setup state. Optional `kinds` filter narrows the audit to a pipeline-derived set.
- integrations.connections.push [destructive/experimental] (caps: connections:push) — Agent-initiated push on a Connection (RFC-0022). No inbound trigger required: builds the OutgoingMessage, applies a per-(workspace,connection) token-bucket rate limit, then routes through the send seam (egress-policy gate + ConnectionSender + signed audit). Rate-limited pushes return a skipped result carrying retryAfterMs.
- integrations.connections.send [destructive/experimental] (caps: connections:send) — Dispatch an OutgoingMessage on a Connection via its connector (RFC-0022). Seam resolves the Connection, applies the egress-policy gate, routes to a registered ConnectionSender, and writes a signed audit entry.
- integrations.connections.setupRegistry.list [read/experimental] (caps: connections:read) — List tenant-friendly integration setup guidance for UI and assistant flows, including preferred setup mode, scopes, health check, docs, and fallback secret instructions.
- integrations.connections.upsert [mutating/experimental] (caps: connections:write) — Create or replace a Connection. Auth fields MUST be references, never plaintext.
- integrations.send [destructive/experimental] (caps: connections:write) — Post a JSON payload to an outbound webhook URL, gated by the egress policy.
- interactionProfile.get [read/experimental] (caps: kv:read) — Read the persisted authoring-assistant Interaction Profile (returns the safe default when unset).
- interactionProfile.set [destructive/experimental] (caps: kv:write) — Persist the authoring-assistant Interaction Profile for the active user/workspace.
- knowledge.abstracts.get [read/experimental] (caps: rag:read) — Read one derived structured Knowledge Abstract.
- knowledge.abstracts.list [read/experimental] (caps: rag:read) — List derived structured Knowledge Abstracts.
- knowledge.abstracts.queryGraph [destructive/experimental] (caps: rag:read) — Query nodes and edges from a graph-shaped Knowledge Abstract.
- knowledge.abstracts.search [read/experimental] (caps: rag:read) — Search structured Knowledge Abstracts with a simple text query.
- knowledge.abstracts.upsert [mutating/experimental] (caps: rag:write) — Persist a derived structured Knowledge Abstract.
- knowledge.extractStructured [destructive/experimental] (caps: rag:write) — Extract and persist a structured Knowledge Abstract from supplied source text.
- knowledge.sources.add [destructive/experimental] (caps: rag:write) — Add a new RAG source. Indexer is queued lazily.
- knowledge.sources.list [read/experimental] (caps: rag:read) — List configured RAG sources.
- knowledge.sources.preview [destructive/experimental] (caps: rag:read) — Embed `query` and return top-k chunks filtered by source id.
- knowledge.sources.rebuild [destructive/experimental] (caps: rag:write) — Re-index a RAG source.
- knowledge.sources.remove [destructive/experimental] (caps: rag:write) — Remove a RAG source.
- knowledge.status [destructive/experimental] (caps: rag:read) — Aggregate knowledge indexer status.
- kv.clearScope [destructive/experimental] (caps: kv:write) — Remove every KV row within a scope.
- kv.delete [destructive/experimental] (caps: kv:write) — Delete a scoped KV entry.
- kv.get [read/experimental] (caps: kv:read) — Read a scoped KV entry from the portable UI settings store.
- kv.list [read/experimental] (caps: kv:read) — List all KV rows for a scope.
- kv.set [destructive/experimental] (caps: kv:write) — Upsert a scoped KV entry (non-string values are JSON-serialized server-side).
- lifecycle.dispose [destructive/experimental] (caps: rbac:admin) — Request a graceful sidecar shutdown — flush audit batch, close handles. No-op if already disposing.
- manifest.get [read/experimental] (caps: runs:read) — Get the live, versioned capability manifest (RPC verbs, flow node kinds, triggers, errors) for agent discovery.
- marketplace.applyMonitoringPack [destructive/experimental] (caps: marketplace:write, observability:write) — Apply an official monitoring pack to the active workspace.
- marketplace.applyPack [destructive/experimental] (caps: marketplace:write) — Apply an official domain pack to the active workspace.
- marketplace.applySecurityPack [destructive/experimental] (caps: marketplace:write, security:admin) — Apply an official security pack to the active workspace.
- marketplace.connector.connect [destructive/experimental] (caps: secrets:write) — Store the API credential for a catalog connector so its tools activate (no restart).
- marketplace.connector.info [destructive/experimental] (caps: marketplace:read) — How a catalog connector authenticates (api-key / oauth2 / keyless / config).
- marketplace.domainPacks [destructive/experimental] (caps: marketplace:read) — List the curated official domain packs (engineering / finance / marketing / support / clinical).
- marketplace.evaluateInstall [destructive/experimental] (caps: marketplace:read) — Pre-install gate: evaluate manifest against workspace install policy.
- marketplace.featured [destructive/stable] (caps: marketplace:read) — Editorial featured-listing rotation.
- marketplace.fetch [destructive/experimental] (caps: marketplace:read) — Fetch the configured marketplace registry, fall back to bundled local marketplace.json when registry empty.
- marketplace.install [destructive/experimental] (caps: marketplace:write) — Install a marketplace listing — writes a stub manifest to userDataDir.
- marketplace.installed.list [read/experimental] (caps: marketplace:write) — List installed plugins for the active workspace.
- marketplace.listing.get [read/stable] (caps: marketplace:read) — Fetch a single marketplace listing for the detail drawer.
- marketplace.listings [destructive/stable] (caps: marketplace:read) — Search marketplace listings.
- marketplace.monitoringPacks [destructive/experimental] (caps: marketplace:read) — List the curated official anomaly + monitoring packs (infrastructure / application / cost / security-signals).
- marketplace.privateLibrary.add [destructive/experimental] (caps: marketplace:write) — Add a private plugin from a local path or URL.
- marketplace.privateLibrary.install [destructive/experimental] (caps: marketplace:write) — Install a private plugin (added from a local path or URL) into the workspace plugin store so it actually loads.
- marketplace.privateLibrary.list [read/experimental] (caps: marketplace:read) — List private (non-marketplace) plugins available for install.
- marketplace.privateLibrary.remove [destructive/experimental] (caps: marketplace:write) — Remove a private plugin from the workspace registry.
- marketplace.publish [destructive/experimental] (caps: marketplace:publish) — Sign + push a plugin bundle to the OEM marketplace endpoint.
- marketplace.publish.buildManifest [destructive/experimental] (caps: marketplace:publish) — Build a publish manifest from a plugin folder on disk.
- marketplace.publisherKeys.list [read/experimental] (caps: marketplace:publish) — List pinned publisher keys with their current trust level.
- marketplace.publisherKeys.pin [destructive/experimental] (caps: marketplace:publish) — Pin a publisher key with a trust level.
- marketplace.publisherKeys.revoke [destructive/experimental] (caps: marketplace:publish) — Mark a publisher key as revoked. Plugins from that publisher become untrusted.
- marketplace.report [destructive/experimental] (caps: marketplace:write) — File an abuse / policy report against a listing.
- marketplace.securityPacks [destructive/experimental] (caps: marketplace:read) — List the curated official security packs (baseline / regulated / zero-trust-egress / incident-response).
- marketplace.stats [destructive/stable] (caps: marketplace:read) — Aggregate counts shown in the catalog header.
- marketplace.suggestions [destructive/experimental] (caps: marketplace:read) — Connection suggestions inferred from workspace + recent runs.
- marketplace.uninstall [destructive/experimental] (caps: marketplace:write) — Remove an installed plugin from the workspace plugin directory.
- mcp.catalog.list [read/experimental] (caps: connections:read) — List the curated catalog of well-known MCP servers.
- mcp.servers.connect [destructive/experimental] (caps: connections:write) — Add (or reconnect) an MCP server.
- mcp.servers.connectOAuth [destructive/experimental] (caps: connections:write) — Begin OAuth sign-in for an HTTP MCP server; returns the authorize URL to open.
- mcp.servers.credential.set [destructive/experimental] (caps: secrets:write) — Persist MCP server credentials in the secret store and link to the server entry.
- mcp.servers.disconnect [destructive/experimental] (caps: connections:write) — Remove an MCP server connection.
- mcp.servers.discover [destructive/experimental] (caps: connections:read) — Probe a server and return its exposed tools.
- mcp.servers.discoverFromFiles [destructive/experimental] (caps: connections:read) — Scan local Cursor/Codex/Claude config files for MCP server declarations and return them as candidates.
- mcp.servers.list [read/experimental] (caps: connections:read) — List configured MCP servers.
- mcp.servers.probe [destructive/experimental] (caps: connections:read) — Active health probe for an MCP server.
- mcp.servers.setAllowedTools [destructive/experimental] (caps: connections:write) — Set the per-server tool allowlist (empty list = no restriction).
- mcp.servers.upsert [mutating/experimental] (caps: connections:write) — Create or update an MCP server entry without connecting.
- models.catalog.list [read/experimental] (caps: agent:read) — List the bundled model catalog (models.dev snapshot, 5244 models).
- notifications.channels.get [read/experimental] (caps: workspace:config) — Return the persisted Slack + email channel overrides (secret-refs only).
- notifications.channels.set [destructive/experimental] (caps: workspace:config) — Persist Slack + email channel overrides. Env vars still take precedence at dispatch time.
- oauth.complete [destructive/experimental] (caps: connections:write) — Exchange an OAuth authorization code for tokens and persist the connection; failures throw.
- oauth.list [read/experimental] (caps: connections:read) — List OAuth connections persisted for the active workspace.
- oauth.providers [destructive/experimental] (caps: connections:read) — List the OAuth provider specs the sidecar can authorize against.
- oauth.revoke [destructive/experimental] (caps: connections:write) — Revoke a stored OAuth connection.
- oauth.start [destructive/experimental] (caps: connections:write) — Begin an OAuth authorization flow; returns the URL to launch in the browser.
- observability.anomaly.evaluate [destructive/experimental] (caps: observability:write) — Evaluate a metric sample against active rules; auto-create incidents.
- observability.anomalyRules.delete [destructive/experimental] (caps: observability:write) — Delete an anomaly rule by id.
- observability.anomalyRules.list [read/experimental] (caps: observability:read) — List structured anomaly rules with their paused state.
- observability.anomalyRules.setPaused [destructive/experimental] (caps: observability:write) — Pause / resume an anomaly rule.
- observability.anomalyRules.upsert [mutating/experimental] (caps: observability:write) — Insert or update an anomaly rule.
- observability.exporters.test [destructive/experimental] (caps: observability:write) — Probe an exporter endpoint (HEAD / GET) and report reachability.
- observability.incidents.assign [destructive/experimental] (caps: observability:write) — Assign an incident to an operator.
- observability.incidents.get [read/experimental] (caps: observability:read) — Fetch an incident with timeline + related runs/traces.
- observability.incidents.transition [destructive/experimental] (caps: observability:write) — Transition incident status (open → acknowledged → resolved → closed).
- observability.metrics.timeseries [destructive/experimental] (caps: observability:read) — Daily-bucketed timeseries for a named metric.
- observability.status [destructive/experimental] (caps: observability:read) — Snapshot of telemetry exporters, anomaly rule counts, and cost meter state.
- observability.topology.get [read/experimental] (caps: observability:read) — Service-graph nodes + edges (agents → tools → providers).
- oem.brand-kit.get [read/experimental] (caps: oem:admin) — Read the active visual OEM brand kit from the persisted store.
- oem.brand-kit.set [destructive/experimental] (caps: oem:admin) — Persist the visual OEM brand kit into the persisted store.
- oem.brand-kit.upload-asset [destructive/experimental] (caps: oem:admin) — Upload a brand asset (logo/favicon/splash) to the workspace asset dir.
- oem.license.import [destructive/experimental] (caps: oem:admin) — Import a license envelope and re-evaluate status.
- oem.license.status [destructive/experimental] (caps: oem:admin) — Read the current OEM license status (state + features + seats).
- oem.packs.apply [destructive/experimental] (caps: oem:admin) — Apply a vertical pack to the workspace.
- oem.packs.list [read/experimental] (caps: oem:admin) — List vertical packs with installed flag (filterable).
- oem.packs.uninstall [destructive/experimental] (caps: oem:admin) — Uninstall a vertical pack from the workspace.
- oem.tenants.create [mutating/experimental] (caps: oem:tenant:admin) — Create a downstream reseller tenant record.
- oem.tenants.delete [destructive/experimental] (caps: oem:tenant:admin) — Delete a downstream tenant record.
- oem.tenants.issueLicense [destructive/experimental] (caps: oem:tenant:admin) — Sign + record a license envelope for a downstream tenant.
- oem.tenants.list [read/experimental] (caps: oem:tenant:admin) — List downstream reseller tenants under this whitelabel.
- oem.tenants.revokeLicense [destructive/experimental] (caps: oem:tenant:admin) — Clear the recorded license envelope on a tenant.
- oem.tenants.suspend [destructive/experimental] (caps: oem:tenant:admin) — Suspend or reactivate a downstream tenant.
- oem.tenants.update [mutating/experimental] (caps: oem:tenant:admin) — Patch a tenant record (brand override, seats, billing, note).
- onboarding.blueprint.apply [destructive/experimental] (caps: onboarding:apply) — Apply an AdaptedWorkspaceBlueprint (connections, flows, pipelines, knowledge, agents) as an idempotent saga; proceeds through warnings.
- onboarding.blueprint.dryRun [destructive/experimental] (caps: workspace:config) — Preview what applying an AdaptedWorkspaceBlueprint would create (counts + readiness), with no persistence.
- onboarding.blueprint.generate [destructive/experimental] (caps: workspace:config) — Generate a draft AdaptedWorkspaceBlueprint from live ecosystem discovery.
- onboarding.blueprint.get [read/experimental] (caps: workspace:config) — Read a persisted AdaptedWorkspaceBlueprint draft by id (null when unset).
- onboarding.blueprint.list [read/experimental] (caps: workspace:config) — List persisted AdaptedWorkspaceBlueprint draft ids for the active workspace.
- onboarding.blueprint.save [destructive/experimental] (caps: onboarding:apply) — Persist an AdaptedWorkspaceBlueprint draft for the active workspace.
- onboarding.complete [destructive/experimental] (caps: copilot:admin, onboarding:apply) — Complete onboarding only after authoritative provider readiness succeeds.
- onboarding.ecosystem.detect [destructive/experimental] (caps: workspace:config) — Discover the workspace ecosystem (metadata-only) and propose a draft EcosystemProfile.
- onboarding.ecosystem.get [read/experimental] (caps: workspace:config) — Read the persisted EcosystemProfile for the active workspace (null when unset).
- onboarding.ecosystem.reset [destructive/experimental] (caps: onboarding:apply) — Delete the EcosystemProfile for the active workspace.
- onboarding.ecosystem.update [mutating/experimental] (caps: onboarding:apply) — Upsert the EcosystemProfile for the active workspace.
- onboarding.insights.emit [destructive/experimental] (caps: workspace:config) — Ingest a validated onboarding usability signal into the local insights store (aggregate increments only; privacy-safe).
- onboarding.insights.get [read/experimental] (caps: workspace:config) — Return operator-global onboarding usability aggregates (counts keyed by metric + dimension). Privacy-safe: aggregates only, no PII.
- onboarding.insights.rank [destructive/experimental] (caps: workspace:config) — Rank onboarding suggestions from k-anonymous aggregate adoption signals (RFC-0055 F3). Falls back to input order when signals are absent or below cohort threshold.
- onboarding.insights.sync [destructive/experimental] (caps: workspace:config) — Push k-anonymous local onboarding aggregates to AKOS central when telemetry consent is granted. Opt-out uploads zero rows.
- onboarding.readiness.get [read/experimental] (caps: copilot:admin, workspace:config) — Actively verify that the persisted assistant configuration can serve required onboarding roles.
- onboarding.session.clear [destructive/experimental] (caps: onboarding:apply) — Delete the OnboardingSession for the active workspace.
- onboarding.session.get [read/experimental] (caps: workspace:config) — Read the persisted OnboardingSession for the active workspace (null when unset).
- onboarding.session.upsert [mutating/experimental] (caps: onboarding:apply) — Upsert the OnboardingSession for the active workspace.
- pii.profiles [destructive/experimental] (caps: security:admin) — List the PII redaction profile identifiers exposed to clients.
- pii.profiles.delete [destructive/experimental] (caps: security:admin) — Delete a custom PII redaction profile by id.
- pii.profiles.list [read/experimental] (caps: security:admin) — List all custom PII redaction profiles.
- pii.profiles.upsert [mutating/experimental] (caps: security:admin) — Create or update a custom PII redaction profile.
- pii.redact [destructive/experimental] (caps: security:admin) — Apply PII profile to a string; returns redacted text + match offsets.
- pipelines.delete [destructive/experimental] (caps: pipelines:write) — Delete a pipeline definition by id.
- pipelines.fromNL [destructive/experimental] (caps: pipelines:write) — Generate a draft multi-stage pipeline from a natural-language description (deterministic v1: stage-split/keyword parsing, no LLM). Returns the Phase-3 compiler envelope (artifact + assumptions/warnings/missing/blockedBy/nextActions/confidence). The LLM-assisted sibling of pipelines.generate.
- pipelines.generate [destructive/experimental] (caps: pipelines:write) — Deterministically decompose a natural-language description into a multi-stage pipeline draft, reusing existing inline flows where they match.
- pipelines.get [read/experimental] (caps: runs:read) — Get a single pipeline by id.
- pipelines.items.delete [destructive/experimental] (caps: pipelines:write) — Delete a kanban item.
- pipelines.items.list [read/experimental] (caps: runs:read) — List all kanban items for a pipeline.
- pipelines.items.move [destructive/experimental] (caps: pipelines:write) — Move a kanban item to a different column. If the destination column has executionMode="auto-on-enter", the bound flow is dispatched and the runId is returned.
- pipelines.items.run [destructive/experimental] (caps: pipelines:write) — Manually dispatch the flow bound to an item's current column (or the specified column).
- pipelines.items.scanColumn [destructive/experimental] (caps: pipelines:write) — Dispatch the column-bound flow for every item in the column. Used by cron handlers for executionMode='scheduled' and by external trigger handlers for 'triggered'.
- pipelines.items.upsert [mutating/experimental] (caps: pipelines:write) — Create or update a kanban item.
- pipelines.list [read/experimental] (caps: runs:read) — List all pipelines in the workspace.
- pipelines.runs.cancel [destructive/experimental] (caps: pipelines:write) — Cancel an in-progress pipeline run.
- pipelines.runs.dispatch [destructive/experimental] (caps: pipelines:write) — Dispatch a new pipeline run; phases execute sequentially until completion or a gate.
- pipelines.runs.get [read/experimental] (caps: runs:read) — Get full detail for a single pipeline run.
- pipelines.runs.list [read/experimental] (caps: runs:read) — List pipeline runs, optionally filtered by pipelineId.
- pipelines.runs.resume [destructive/experimental] (caps: pipelines:write) — Resume a pipeline run paused at an approval gate.
- pipelines.upsert [mutating/experimental] (caps: pipelines:write) — Create or update a pipeline definition.
- pipelines.validateDetailed [destructive/experimental] (caps: runs:read) — Semantically validate a draft pipeline (phase graph, flow references, inputMapping paths, cross-phase state wiring, triggers) and return structured, self-correctable authoring issues.
- plugins.disable [destructive/experimental] (caps: marketplace:write) — Disable an installed plugin. Returns false when the id is unknown.
- plugins.enable [destructive/experimental] (caps: marketplace:write) — Enable an installed plugin. Returns false when the id is unknown.
- plugins.get [read/experimental] (caps: marketplace:read) — Fetch one installed plugin summary + its full manifest.
- plugins.install [destructive/experimental] (caps: marketplace:write) — Validate + persist a plugin manifest into the installed-plugin registry.
- plugins.list [read/experimental] (caps: marketplace:read) — List every installed plugin manifest in the workspace.
- plugins.uninstall [destructive/experimental] (caps: marketplace:write) — Remove an installed plugin from the registry. Returns false when unknown.
- prod.seed.apply [destructive/experimental] (caps: workspace:config) — Apply missing or stale production seeds and record the seed ledger.
- prod.seed.ledger [destructive/experimental] (caps: workspace:config) — List production seed ledger records without secret or prompt bodies.
- prod.seed.plan [destructive/experimental] (caps: workspace:config) — Dry-run production seed currentness against the seed ledger.
- rag.search [read/experimental] (caps: rag:read) — Search RAG knowledge sources for top-k chunks relevant to `query`.
- rbac.capabilityShadow.stats [destructive/experimental] (caps: rbac:admin) — Report legacy↔capability shadow-mode divergence counts (the F4 gate signal).
- rbac.members.invite [destructive/experimental] (caps: rbac:members:write) — Invite a new workspace member by email.
- rbac.members.list [read/experimental] (caps: rbac:admin) — List workspace members and pending invitations with their roles.
- rbac.members.remove [destructive/experimental] (caps: rbac:members:write) — Remove a workspace member.
- rbac.members.setRole [destructive/experimental] (caps: rbac:members:write) — Replace a workspace member's role.
- rbac.roles.get [read/experimental] (caps: rbac:admin) — Read the active RBAC role/capability matrix (whitelabel cfg.rbac merged with capability registry).
- rbac.roles.set [destructive/experimental] (caps: rbac:admin) — Persist the RBAC role/capability matrix; subsequent dispatches enforce the new caps.
- roles.delete [destructive/experimental] (caps: copilot:write) — Delete a custom role. System roles cannot be deleted.
- roles.list [read/experimental] (caps: rbac:admin) — List system + custom roles merged. System roles are immutable; custom roles persist in copilot.config.customRoles.
- roles.upsert [mutating/experimental] (caps: copilot:write) — Insert or update a custom role. Rejects ids that collide with system roles.
- runner.cancelRun [destructive/experimental] (caps: runs:write) — Request cancellation of the flow run associated with the supplied trace id.
- runner.getState [destructive/experimental] (caps: runs:read) — Return the runner state machine snapshot (single `runId` or all known runs).
- runner.pause [destructive/experimental] (caps: runs:write) — Pause an in-flight run (specific `runId`) or all running runs when none is supplied.
- runner.resume [destructive/experimental] (caps: runs:write) — Resume a paused run, or all paused runs when no `runId` is supplied.
- runner.runAgent [destructive/experimental] (caps: runs:write) — Run a named agent now and return its persisted run/trace identity plus optional readiness evidence.
- runner.runFlow [destructive/experimental] (caps: runs:write) — Run a named flow now. Optionally resume from a given node id.
- runs.cancel [destructive/experimental] (caps: runs:write) — Cancel an in-flight run.
- runs.detail [destructive/experimental] (caps: runs:read) — Enriched run-detail envelope: run row + artifacts, coding outputs, tool calls, spans, eval results, benchmarks. Returns null if the run does not exist.
- runs.get [read/experimental] (caps: runs:read) — Get a single run row by id.
- runs.list [read/experimental] (caps: runs:read) — Paginated list of recent runs across workspace.
- runtime.config.get [read/experimental] (caps: none) — Current state of the per-OEM runtime-config subscription (kind, freshness, optional config payload). `disabled` when the sidecar was launched without AKOS_RUNTIME_CONFIG_ENDPOINT.
- runtime.status [destructive/experimental] (caps: none) — Preflight readiness snapshot — runner mode (real vs synthesiser), evals/cloud feature flags, coding CLI provider health.
- sandbox.denials.list [read/experimental] (caps: security:admin) — Recent denied sandbox decisions (most recent first).
- sandbox.flow.preview [destructive/experimental] (caps: security:admin) — Preview the per-flow/per-agent sandbox decision the runner would apply for the given effects.
- sandbox.policy.get [read/experimental] (caps: security:admin) — Read the active sandbox policy.
- sandbox.policy.set [destructive/experimental] (caps: security:admin) — Replace the active sandbox policy.
- sandbox.state [destructive/experimental] (caps: security:admin) — Sandbox kernel state: active sandboxes + active policy.
- sdlc.gates.decide [destructive/experimental] (caps: sdlc:write) — Approve or reject a paused SDLC pipeline gate.
- sdlc.gates.list [read/experimental] (caps: runs:read) — List SDLC pipeline HITL gates (pending or by pipeline run).
- sdlc.pipelines.list [read/experimental] (caps: runs:read) — List SDLC pipelines exposed by the dev orchestrator.
- sdlc.runs.dispatch [destructive/experimental] (caps: sdlc:write) — Dispatch a real SDLC pipeline run. Each phase resolves to a workflow and runs sequentially; pipeline halts on first non-success or HITL gate.
- sdlc.runs.fork [destructive/experimental] (caps: sdlc:write) — Fork an existing SDLC run, optionally branching at a phase.
- sdlc.runs.list [read/experimental] (caps: runs:read) — List recent SDLC runs in the workspace.
- sdlc.runs.rerun [destructive/experimental] (caps: sdlc:write) — Re-run an existing SDLC run.
- sdlc.runs.resume [destructive/experimental] (caps: sdlc:write) — Resume a paused SDLC pipeline. Picks up at the first phase that has not yet completed and runs until the next gate or terminal status.
- secrets.delete [destructive/experimental] (caps: secrets:write) — Remove a secret from the active vault backend.
- secrets.list [read/experimental] (caps: secrets:read) — List secret keys discovered in the workspace + vault. Values never leave the sidecar.
- secrets.providers.configure [destructive/experimental] (caps: secrets:write) — Configure (insert or update) an external secret provider.
- secrets.providers.list [read/experimental] (caps: secrets:read) — List configured external secret providers (RFC-0014).
- secrets.providers.remove [destructive/experimental] (caps: secrets:write) — Remove an external secret provider entry.
- secrets.providers.test [destructive/experimental] (caps: secrets:read) — Probe an external secret provider connection.
- secrets.reveal [destructive/experimental] (caps: secrets:read) — Return the plaintext value of a secret. Caller must hold `secrets:read`.
- secrets.set [destructive/experimental] (caps: secrets:write) — Write a secret to the active vault backend. Caller must hold `secrets.write`.
- security.agentIdentity.rotate [destructive/experimental] (caps: security:agent-identity:rotate) — Mint a fresh workspace agent-signing key (or the first one). Prior key is retired; agents already signed under it stay verifiable (did:key self-certifying).
- security.agentIdentity.status [destructive/experimental] (caps: security:agent-identity:read) — Active agent-signing identity for the workspace — DID, fingerprint, rotation history. Never returns private key material.
- security.bundle [destructive/experimental] (caps: security:admin) — Compose firewall + PII + field-redaction policy for a workspace.
- security.firewall.evaluate [destructive/experimental] (caps: security:admin) — Evaluate sample text against a firewall tier — returns structured decision + matches.
- security.keyring.escrow [destructive/experimental] (caps: security:admin) — Export a passphrase-sealed escrow blob of the key ring for offsite recovery custody.
- security.keyring.reencrypt [destructive/experimental] (caps: security:admin) — Rewrap all connector credentials onto the active key (post-rotation migration sweep).
- security.keyring.revoke [destructive/experimental] (caps: security:admin) — Revoke a retired key (decrypt under it is refused). The active key cannot be revoked.
- security.keyring.rotate [destructive/experimental] (caps: security:admin) — Mint a new active key; prior active key is retired (still decrypts old data).
- security.keyring.status [destructive/experimental] (caps: security:admin) — Connector-credential key-ring status — custody mode, active key, key lifecycle states.
- security.policy.persistence.status [destructive/experimental] (caps: security:admin) — Report whether authored security policies are durable or process-local.
- security.redact.preview [destructive/experimental] (caps: security:admin) — Preview a redaction profile against sample text — returns redacted + match counts.
- setup.applySampleBundle [destructive/experimental] (caps: onboarding:write) — Apply a named sample workspace bundle for first-run onboarding.
- setup.probeProvider [destructive/experimental] (caps: onboarding:write) — Check whether the named provider has API key material configured.
- setup.scaffold [destructive/experimental] (caps: onboarding:write) — Scaffold a new workspace skeleton on disk.
- share.create [mutating/experimental] (caps: collab:write) — Build a share-link bundle for an artifact with scope + expiry.
- share.get [read/experimental] (caps: none) — Resolve a public share-link by code; verifies signature.
- skills.describe [destructive/experimental] (caps: runs:read) — Describe a single skill's full agent-relevant metadata — including its systemPromptFragment and toolGrants — so an agent can decide whether and how to attach it. Unknown skillId raises AK_VALIDATION_FAILED with the set of valid ids.
- skills.list [read/experimental] (caps: runs:read) — List the skill catalog available to agents in the active workspace. Combines the built-in catalog with workspace/plugin-declared skills.
- slack.post [destructive/experimental] (caps: connections:write) — Post a message to a Slack channel via the Slack Web API.
- sql.connections.delete [destructive/experimental] (caps: connections:write) — Remove a SQL connection. Does NOT delete the referenced vault secret.
- sql.connections.get [read/experimental] (caps: connections:read) — Read a single SQL connection by id.
- sql.connections.list [read/experimental] (caps: connections:read) — List SQL database connections available to the workspace.
- sql.connections.test [destructive/experimental] (caps: connections:read) — Open a SQL connection and run SELECT 1 — a reachability probe. Never throws on a connection failure; returns { ok: false, error }.
- sql.connections.upsert [mutating/experimental] (caps: connections:write) — Create or replace a SQL connection. `secretRef` MUST be a vault reference, never a plaintext connection string.
- status.public [destructive/experimental] (caps: none) — Public component health + recent incidents for the /status page.
- sync.delta [destructive/experimental] (caps: runs:read) — Compute deterministic JSON-Patch delta + canonical sha256 hashes.
- team.evaluateRbac [destructive/experimental] (caps: rbac:admin) — Evaluate whether a role grants the requested capability set.
- team.invite [destructive/experimental] (caps: rbac:members:write) — Invite a user to the team at the given role.
- team.list [read/experimental] (caps: collab:read) — List team seats for the active workspace.
- team.remove [destructive/experimental] (caps: rbac:members:write) — Remove a user from the team.
- teams.addMember [destructive/experimental] (caps: rbac:admin) — Add a user to a team.
- teams.assignRole [destructive/experimental] (caps: rbac:admin) — Add a role to a team.
- teams.delete [destructive/experimental] (caps: rbac:admin) — Delete a team.
- teams.forUser [destructive/experimental] (caps: rbac:admin) — List teams a user belongs to.
- teams.get [read/experimental] (caps: rbac:admin) — Lookup a team by id.
- teams.list [read/experimental] (caps: rbac:admin) — List workspace teams.
- teams.removeMember [destructive/experimental] (caps: rbac:admin) — Remove a user from a team.
- teams.revokeRole [destructive/experimental] (caps: rbac:admin) — Remove a role from a team.
- teams.upsert [mutating/experimental] (caps: rbac:admin) — Insert or update a team.
- telemetry.recordUiEvent [destructive/experimental] (caps: runs:read) — Record UI breadcrumb events forwarded from the desktop shell.
- tools.calls.approve [destructive/experimental] (caps: runs:write) — Approve a pending tool call (HITL gate).
- tools.calls.list [read/experimental] (caps: runs:read) — List tool calls for a session/run; filterable by status.
- tools.calls.reject [destructive/experimental] (caps: runs:write) — Reject a pending tool call (HITL gate).
- tools.calls.replay [destructive/experimental] (caps: runs:write) — Re-execute a completed tool call with the same args.
- tools.describe [destructive/experimental] (caps: runs:read) — Describe one built-in tool: base descriptor plus agent-authoring enrichment (output shape, examples, typed errors, egress hosts, connection route).
- tools.list [read/experimental] (caps: runs:read) — List built-in + plugin-declared tools available in the active workspace.
- topologies.delete [destructive/experimental] (caps: flows:delete) — Remove a topology.
- topologies.list [read/experimental] (caps: flows:read) — List multi-agent topologies declared in the active workspace.
- topologies.run [destructive/experimental] (caps: runs:write) — Run a topology against a prompt; executes every agent through the real runner and returns per-agent outputs.
- topologies.upsert [mutating/experimental] (caps: flows:write) — Insert or update a multi-agent topology.
- traces.get [read/experimental] (caps: runs:read) — Fetch the spans that belong to a single trace id.
- traces.list [read/experimental] (caps: runs:read) — List traces, optionally filtered by run.
- traces.replay [destructive/experimental] (caps: runs:write) — Replay a recorded trace as a new run; returns the new run id.
- triggers.contracts [destructive/experimental] (caps: runs:read) — List every registered trigger contract (builtin + integration) as transport-safe descriptors.
- triggers.delete [destructive/experimental] (caps: triggers:write) — Remove a trigger from the active workspace. Persistence is owned by os-headless.
- triggers.fromNL [destructive/experimental] (caps: triggers:write) — Generate a draft trigger from a natural-language description (deterministic v1: cadence/keyword parsing, no LLM). Returns the Phase-3 compiler envelope (artifact + assumptions/warnings/missing/blockedBy/nextActions/confidence).
- triggers.get [read/experimental] (caps: runs:read) — Fetch the full TriggerConfig for one trigger by id.
- triggers.kinds [destructive/experimental] (caps: runs:read) — Enumerate every trigger kind declared in the schema with support status + contract source.
- triggers.list [read/experimental] (caps: runs:read) — List configured triggers in the active workspace. Persistence is owned by os-headless.
- triggers.recentRuns [destructive/experimental] (caps: runs:read) — Recent run history for one trigger, newest first.
- triggers.testFire [destructive/experimental] (caps: triggers:write) — Manually fire a trigger with optional synthetic payload — invokes the linked flow.
- triggers.toggle [destructive/experimental] (caps: triggers:write) — Enable or disable a trigger without rewriting its config.
- triggers.upsert [mutating/experimental] (caps: triggers:write) — Insert or update a trigger in the active workspace. Persists the full kind-specific TriggerConfig.
- usage.state.get [read/stable] (caps: billing:read) — Fetch the backend usage state when cloud usage metering is enabled.
- users.assignRole [destructive/experimental] (caps: rbac:admin) — Add a role to a user.
- users.delete [destructive/experimental] (caps: rbac:admin) — Delete a user row.
- users.get [read/experimental] (caps: rbac:admin) — Lookup a user by id or email.
- users.list [read/experimental] (caps: rbac:admin) — List workspace users.
- users.revokeRole [destructive/experimental] (caps: rbac:admin) — Remove a role from a user.
- users.upsert [mutating/experimental] (caps: rbac:admin) — Insert or update a user row.
- verticals.catalog [destructive/experimental] (caps: runs:read) — List every available vertical across all tiers (builtin + config + store), in display order.
- verticals.delete [destructive/experimental] (caps: oem:admin) — Remove a tenant-defined vertical. Returns false when the id was not stored.
- verticals.get [read/experimental] (caps: runs:read) — Get one tenant-defined vertical with its config YAML. Null when absent.
- verticals.list [read/experimental] (caps: runs:read) — List the tenant-defined (store-backed) verticals. Builtins are excluded.
- verticals.resolveConfig [destructive/experimental] (caps: runs:read) — Resolve the JSON-serialised whitelabel config for any vertical the composed registry knows. Null when unknown.
- verticals.upsert [mutating/experimental] (caps: oem:admin) — Create or replace a tenant-defined vertical and its whitelabel config.
- voice.providers.list [read/experimental] (caps: copilot:write) — List configured speech-to-text providers for assistant voice mode.
- voice.transcribe [destructive/experimental] (caps: copilot:write) — Transcribe assistant voice-mode audio through a configured STT provider.
- whitelabel.cli.run [destructive/experimental] (caps: oem:admin) — Run the agentskit-whitelabel CLI (build/doctor/info).
- whitelabel.runtime.get [read/experimental] (caps: oem:admin) — Read the workspace whitelabel.runtime.json snapshot.
- whitelabel.runtime.set [destructive/experimental] (caps: oem:admin) — Persist the workspace whitelabel.runtime.json (super-admin only).
- workspace.config.activation.get [read/experimental] (caps: workspace:config) — Read the activation/retention metrics consent (strict opt-in).
- workspace.config.activation.set [destructive/experimental] (caps: workspace:config) — Persist the activation/retention metrics consent to the workspace config.
- workspace.config.activeVertical.get [read/experimental] (caps: workspace:config) — Read the active vertical persisted on the workspace config (null when unset).
- workspace.config.activeVertical.set [destructive/experimental] (caps: workspace:config) — Persist the active vertical to the workspace config.
- workspace.config.exporters.get [read/experimental] (caps: workspace:config) — Read exporter config (OTLP/Langfuse/PostHog). Secret values masked.
- workspace.config.exporters.set [destructive/experimental] (caps: workspace:config) — Persist exporter config; secrets routed to vault via secrets.set.
- workspace.config.orchestration.get [read/experimental] (caps: workspace:config) — Read the workspace orchestration knobs (concurrency/timeouts/autonomy/recovery).
- workspace.config.orchestration.set [destructive/experimental] (caps: workspace:config) — Persist orchestration knobs to the workspace config (applies on next sidecar start).
- workspace.config.selfheal.get [read/experimental] (caps: workspace:config) — Read the workspace self-heal policy (recovery actions on node failure).
- workspace.config.selfheal.set [destructive/experimental] (caps: workspace:config) — Persist the self-heal policy to the workspace config (applies on next run).
- workspace.create [mutating/experimental] (caps: workspace:config) — Create a workspace. Idempotent on `id` — returns the existing workspace if present.
- workspace.delete [destructive/experimental] (caps: workspace:admin) — Delete a workspace by id. Rejects when the target is the active workspace.
- workspace.export [destructive/experimental] (caps: workspace:admin) — Export the active workspace as a self-contained bundle.
- workspace.get [read/experimental] (caps: workspace:config) — Return active workspace metadata + parsed config.
- workspace.import [destructive/experimental] (caps: workspace:admin) — Import a workspace bundle, replacing the active workspace contents.
- workspace.switch [destructive/experimental] (caps: workspace:config) — Activate the named workspace. Returns the new active workspace id + name.
- workspace.update [mutating/experimental] (caps: workspace:config) — Update workspace identity (name/kind). Path-stable: id unchanged.
- workspaceConfig.fromNL [destructive/experimental] (caps: workspace:write) — Generate a draft workspace config from a natural-language description (deterministic v1: limits/residency/retry/isolation/autonomy parsing, no LLM). Returns the Phase-3 compiler envelope.
- workspaces.activate [destructive/experimental] (caps: workspace:config) — Activate the named workspace as the sidecar default.
- workspaces.clone [destructive/experimental] (caps: workspace:admin) — Clone the active workspace into a new id, copying agents/flows/triggers.
- workspaces.list [read/experimental] (caps: workspace:config) — List workspace files discovered on disk plus the currently-active workspace.
- workspaces.setIsolation [destructive/experimental] (caps: rbac:admin) — Update a workspace isolation profile (none / standard / strict).

Structured source: /api/capabilities.json