agentcorp-broker 0.1.0-alpha.1

package/docs/cli-reference.md

@@ -0,0 +1,133 @@
+# CLI Reference Manual
+
+AgentCorp provides a comprehensive CLI for daemon management, role-bound stdio proxying, policy administration, and terminal-native human oversight.
+
+---
+
+## Global Options
+
+All commands accept the following global flags:
+
+* `--config <path>`: Path to organization configuration file (default: `org.toml`).
+* `--db <path>`: Path to SQLite broker database (default: `.agentcorp/agentcorp.db`).
+* `--credentials <path>`: Optional credentials-file override. By default, AgentCorp uses `.agentcorp/credentials.json` beside the selected configuration.
+
+---
+
+## 1. Setup & Daemon Lifecycle
+
+### `agentcorp init`
+Creates a starter `org.toml` and initializes credentials under `.agentcorp/credentials.json`.
+
+* **Options**:
+  * `--force`: Overwrite existing files.
+
+### `agentcorp validate`
+Validates `org.toml` syntax, role graphs, peer connectivity, and policy schemas.
+
+### `agentcorp start`
+Starts the central broker daemon hosting Streamable HTTP MCP (`/mcp`), Admin REST API (`/api/*`), and real-time SSE (`/api/events`).
+
+* **Options**:
+  * `--port <number>`: HTTP port to listen on. The default `0` asks the operating system for an available local port and records the selection in `.agentcorp/daemon.json`.
+  * `--host <string>`: Host address to bind to (default: `127.0.0.1`).
+  * `--daemon`: Runs detached in the background.
+  * `--daemon-file <path>`: Overrides the daemon control-file location.
+
+### `agentcorp stop`
+Sends a graceful termination signal (`SIGTERM`) to the running background daemon.
+
+### `agentcorp status`
+Checks whether the central broker daemon is running, healthy, and reports active roles and uptime.
+
+The daemon health response includes its live process ID and start time. If the
+local control file is stale, `status` repairs it from that live identity. The
+`stop` command refuses to signal an unreachable or unverifiable PID, preventing
+an old control file from terminating an unrelated process.
+
+---
+
+## 2. Human Oversight & Console
+
+### `agentcorp console`
+Launches the human oversight console.
+
+* **Default**: Renders the terminal-native ANSI status summary and queues pending approvals for interactive review.
+* **Options**:
+  * `--browser`, `--web`: Opens the dark glassmorphic web dashboard in your default browser.
+
+### `agentcorp review`
+Top-level alias for `agentcorp approvals review`. Directly launches the interactive terminal keyboard sign-off loop (`[a]`, `[e]`, `[r]`, `[s]`, `[q]`).
+
+### `agentcorp approvals list`
+Outputs all pending approvals in structured JSON.
+
+### `agentcorp approvals approve <approval-id>`
+Signs off on a pending approval.
+
+* **Options**:
+  * `--note <text>`: Reviewer decision note.
+  * `--payload <json>`: Edited message payload as JSON (delivering modified content).
+
+### `agentcorp approvals reject <approval-id>`
+Rejects a pending approval.
+
+* **Options**:
+  * `--note <text>`: Rejection reason or feedback for the agent.
+
+---
+
+## 3. Runtime Policies
+
+### `agentcorp policies list`
+Lists all active and disabled runtime policies.
+
+### `agentcorp policies set <json>`
+Creates or updates a policy rule from a JSON definition.
+
+### `agentcorp policies enable <policy-id>`
+Enables a disabled policy rule.
+
+### `agentcorp policies disable <policy-id>`
+Disables a policy rule without deleting its audit history.
+
+---
+
+## 4. MCP Stdio Proxy
+
+### `agentcorp mcp --role <role-id>`
+Runs a role-bound stdio MCP server for agent hosts that only spawn local commands (e.g. Antigravity IDE, Codex, Claude Code, Cursor).
+
+* **Options**:
+  * `--role <id>` *(required)*: Role identity to bind to this process.
+  * `--no-spawn`: Disables automatic background spawning of the daemon if not running.
+  * `--daemon-url <url>`: Explicit daemon URL to connect to.
+
+---
+
+## 5. Audit & Compliance
+
+### `agentcorp audit export`
+Generates human-readable Markdown (`coord/audit.md`) and structured JSON (`coord/audit.json`) snapshots of broker state for operational review. These files are ignored by default because they can contain project conversation metadata; store or share them only after review.
+
+* **Options**:
+  * `--out <dir>`: Output directory (default: `coord`).
+  * `--limit <number>`: Limit the number of exported items per category (most recent).
+  * `--since <iso-date>`: Only include records created or updated since the specified ISO timestamp.
+
+---
+
+## 6. Storage Maintenance & Bounding
+
+### `agentcorp prune`
+Prunes terminal, resolved history (completed/failed/cancelled tasks, associated messages, events, and resolved approvals) older than a specified retention threshold. Active tasks and pending approvals are always preserved.
+
+* **Options**:
+  * `--older-than <days>`: Age threshold in days for terminal records to prune (default: `30`).
+  * With no execution flag, reports the count of eligible records without modifying or deleting database rows (safe default).
+  * `--execute`: Performs the deletion described by the preview.
+  * `--delete-artifacts`: Deletes associated artifacts instead of detaching them.
+  * `--compact`: Automatically runs a SQLite WAL checkpoint (`TRUNCATE`) and `VACUUM` after successful pruning.
+
+### `agentcorp compact`
+Executes an immediate SQLite WAL checkpoint (`PRAGMA wal_checkpoint(TRUNCATE)`) and compaction (`VACUUM`) to reclaim disk space from pruned records and truncate write-ahead logs.

package/docs/dogfooding-report.md

@@ -0,0 +1,83 @@
+# AgentCorp Dogfooding Report
+
+Date: 2026-09-05
+Scenario: Codex acting as architect/reviewer and Gemini in Antigravity acting as
+developer while improving AgentCorp itself.
+
+## Executive assessment
+
+AgentCorp was useful as a durable, policy-controlled coordination ledger. It
+made task ownership, human approval, implementation evidence, and review
+decisions more explicit than ordinary copy-and-paste chat. The core broker is a
+credible developer-preview tool.
+
+The experience was not yet autonomous. AgentCorp reliably stored and exposed
+work, but the human repeatedly had to tell an idle agent that new work was
+available. At one point the Gemini host entered a goal-verification loop and
+showed an MCP error. These are host-lifecycle failures rather than lost broker
+state, but they are central to the user's experience and must be treated as
+product requirements.
+
+## What worked well
+
+- Stable task, message, artifact, and approval IDs made handoffs auditable.
+- Human approval gates prevented an eager implementer from receiving an
+  unreviewed proposal and prevented automatic final completion.
+- `get_work_queue` reduced several reconciliation calls to one prioritized view.
+- `accept_handoff` plus idempotency keys reduced duplicate execution risk.
+- The central SQLite daemon preserved coordination state across client and
+  daemon restarts.
+- Concise reports and on-demand artifacts kept the coordination database and
+  model context smaller than copying whole files through chat.
+- Independent architectural review found real reliability and release defects,
+  and the developer could return targeted evidence against them.
+
+## Friction observed
+
+- MCP exposes tools but has no standard operation for starting a new model turn.
+- IDE integrations can retain an older stdio adapter until their MCP connection
+  is restarted.
+- Presence indicates recent tool activity, not that a host can accept work now.
+- A host-side agent loop can continue even when the broker considers its task
+  complete; AgentCorp currently cannot interrupt it.
+- Manual “Gemini replied” and “check AgentCorp” prompts were still needed.
+- Reports can become verbose or repetitive unless agents are instructed to send
+  IDs, summaries, and bounded evidence.
+
+## Practical verdict
+
+The coordination and safety layer is effective enough for an **alpha developer
+preview**, especially for local two-agent workflows with an engaged human. It
+is not yet a hands-off orchestration platform, a hostile multi-tenant security
+boundary, or a guarantee that every IDE agent will resume automatically.
+
+## Autonomous invocation direction
+
+Autonomous invocation should be an adapter capability above the broker, not a
+special case embedded into the task database.
+
+Proposed shape:
+
+1. The broker commits an approved-work event to a transactional outbox.
+2. A runner service claims the event with a time-limited lease and a stable
+   idempotency key.
+3. A host adapter translates the generic request into something that host
+   supports: subprocess launch, IDE extension command, webhook, notification,
+   or “not supported”.
+4. The adapter reports accepted, started, heartbeat, completed, failed, or
+   timed-out state back to AgentCorp.
+5. Retries use bounded backoff, deduplication, attempt limits, and a circuit
+   breaker. Human stop and pause controls always win.
+
+Each role should declare invocation capabilities such as `manual`, `notify`, or
+`managed_runner`. A policy should separately decide whether approved work may
+be invoked automatically. This keeps approval and invocation distinct: an
+approved task is authorized work, but it is not automatically permission to
+spawn an unrestricted process.
+
+The first implementation should be a narrow feasibility spike for one host,
+with a fake adapter for deterministic tests. The general interface should be
+extracted only after a second, meaningfully different host proves which parts
+are portable. Essential safeguards are workspace isolation, command allowlists,
+resource and token budgets, lease expiry, deduplication, observable attempt
+history, and a global kill switch.

package/docs/getting-started.md

@@ -0,0 +1,228 @@
+# AgentCorp Beginner Setup and First Workflow
+
+This guide takes you from an empty terminal to two AI agents collaborating on
+one project. You do not need prior Model Context Protocol (MCP) experience.
+
+AgentCorp is a local coordination service. It records tasks and messages,
+checks who may communicate, pauses sensitive actions for human approval, and
+keeps an audit trail. It does **not** choose an AI model, provide an AI
+subscription, sandbox an agent's shell access, or wake an idle agent inside an
+IDE.
+
+## 1. Install the prerequisites
+
+Install:
+
+- Node.js 22.13 or newer from [nodejs.org](https://nodejs.org/).
+- Two MCP-capable agent hosts if you want to test collaboration, such as Codex
+  and Antigravity, Claude, or Cursor.
+- Git if you are installing from source.
+
+Confirm Node and npm are available:
+
+```sh
+node --version
+npm --version
+```
+
+The Node version must be `v22.13.0` or newer.
+
+## 2. Install AgentCorp
+
+Before the first npm publication, clone the repository and build it:
+
+```sh
+git clone <AGENTCORP_REPOSITORY_URL>
+cd AgentCorp
+npm install
+npm run build
+```
+
+Use `node /absolute/path/to/AgentCorp/dist/cli.js` wherever the examples below
+say `agentcorp`.
+
+After the package is published, install it globally instead:
+
+```sh
+npm install --global agentcorp-broker@alpha
+agentcorp --version
+```
+
+The `alpha` tag is intentional while AgentCorp is a developer preview.
+
+## 3. Initialize AgentCorp in your project
+
+Open a terminal in the software project where the agents will collaborate. Do
+not run this in the AgentCorp source directory unless AgentCorp itself is the
+project being coordinated.
+
+```sh
+cd /path/to/your-project
+agentcorp init
+agentcorp validate
+```
+
+Initialization creates:
+
+```text
+your-project/
+|-- org.toml                         team roles and approval policies
+`-- .agentcorp/
+    `-- credentials.json             private local role and admin tokens
+```
+
+Add `.agentcorp/` to that project's `.gitignore`. Never commit or paste the
+credentials file into an issue, prompt, chat, or audit artifact.
+
+The starter `org.toml` defines:
+
+- `architect`: plans and reviews work.
+- `developer`: implements and reports work.
+- Human approval for proposals and final task completion.
+- Automatic delivery for narrowly tagged read-only reports and status updates.
+
+Edit the display names, models, capabilities, and allowed peers as needed, then
+run `agentcorp validate` again. Policies fail closed: if no enabled rule
+matches, AgentCorp asks a human to approve the operation.
+
+## 4. Start and inspect the daemon
+
+Start the local broker in the background:
+
+```sh
+agentcorp start --daemon
+agentcorp status
+agentcorp doctor
+```
+
+By default it listens only on `127.0.0.1` and asks the operating system for an
+available port. The selected address is recorded in `.agentcorp/daemon.json`,
+so agents and the console discover it automatically. This avoids collisions
+with applications and Windows reserved port ranges. Keep the loopback binding
+for normal local use. Runtime data, logs, and the SQLite database stay in the
+project's `.agentcorp/` directory.
+
+## 5. Connect the first agent
+
+Every agent receives its own role-bound MCP process. Use the absolute path to
+the collaboration project's `org.toml`; IDEs do not always start MCP processes
+from the project directory.
+
+After npm installation, the generic command is:
+
+```text
+agentcorp --config /absolute/path/to/your-project/org.toml mcp --role architect
+```
+
+For the developer connection, change only the final role:
+
+```text
+agentcorp --config /absolute/path/to/your-project/org.toml mcp --role developer
+```
+
+If you are running from source, replace `agentcorp` with `node` and put the
+absolute path to `dist/cli.js` before the other arguments.
+
+The exact configuration-file format differs by host. Copy the relevant guide:
+
+- [Codex setup](guides/codex-setup.md)
+- [Antigravity setup](guides/antigravity-setup.md)
+- [Claude and Cursor setup](guides/claude-cursor-setup.md)
+
+Restart each host's MCP connection after editing its configuration. Ask each
+agent to call `whoami`. One response should say `architect` and the other
+`developer`. If both roles are correct, ask each to call `get_work_queue`.
+
+## 6. Complete the first collaboration
+
+Give both agents this standing instruction:
+
+> At session start and after every handoff or status change, call
+> `get_work_queue`. Follow the highest-priority applicable next action. Use
+> concise task and message IDs instead of copying large histories.
+
+Then use this workflow:
+
+1. Tell the architect the goal and ask it to create a task for `developer` and
+   send a linked `proposal` message.
+2. Run `agentcorp review`. Inspect the proposed instructions, then approve,
+   edit and approve, reject with feedback, or skip them.
+3. Tell the developer to call `get_work_queue`. It should now see the approved
+   proposal and task.
+4. The developer calls `accept_handoff`, implements the work, runs tests, sends
+   a concise `report`, and requests the `awaiting_review` task state.
+5. The architect reviews the code and evidence, then returns a verdict.
+6. When completion is requested, use `agentcorp review` again for final human
+   sign-off.
+
+The web console provides the same operational view:
+
+```sh
+agentcorp console --browser
+```
+
+MCP is passive: an approved message becomes available immediately, but
+AgentCorp cannot make an idle IDE model start a new turn. Until host adapters
+are added, you may need to prompt the receiving agent to check its work queue.
+
+## 7. Keep storage bounded
+
+Preview old resolved history without deleting it:
+
+```sh
+agentcorp prune --older-than 30
+```
+
+After checking the preview, execute the deletion and compact the database:
+
+```sh
+agentcorp prune --older-than 30 --execute --compact
+```
+
+Export only the recent audit window you need:
+
+```sh
+agentcorp audit export --limit 100
+```
+
+Audit exports go to the ignored `coord/` directory and can contain project
+metadata. Review them before sharing. Back up `org.toml` and, if you need to
+preserve coordination history, the entire `.agentcorp/` directory while the
+daemon is stopped.
+
+## 8. Troubleshooting
+
+If an IDE shows an MCP error:
+
+1. Run `agentcorp status` and `agentcorp doctor` in the collaboration project.
+2. Confirm the MCP entry uses an absolute `org.toml` path.
+3. Confirm the configured role exists in `org.toml`.
+4. Run `agentcorp validate`.
+5. Restart the daemon with `agentcorp stop`, then `agentcorp start --daemon`.
+6. Restart the IDE's MCP connection so it loads the installed adapter version.
+7. Inspect `.agentcorp/daemon.log` locally. Remove secrets before sharing any
+   excerpt.
+
+If a proposal is missing from the developer queue, check `agentcorp review`.
+Pending proposals are deliberately invisible to the assignee until approved.
+
+If npm reports `agentcorp: command not found`, either reopen the terminal after
+global installation or use `npx agentcorp-broker@alpha --version` to verify the
+package without depending on the global executable path.
+
+## 9. Stop or remove AgentCorp
+
+Stop the project daemon:
+
+```sh
+agentcorp stop
+```
+
+Uninstall the global CLI without deleting project data:
+
+```sh
+npm uninstall --global agentcorp-broker
+```
+
+Only delete `.agentcorp/` when you intentionally want to erase that project's
+credentials, messages, tasks, approvals, and audit history.

package/docs/guides/antigravity-setup.md

@@ -0,0 +1,84 @@
+# Google Antigravity Setup Guide
+
+This guide walks you through configuring **Google Antigravity IDE** (the Gemini-powered agent) to act as a coordinated member of your AgentCorp team (such as the **`developer`** role).
+
+---
+
+## 1. Overview
+
+Google Antigravity is an AI-first IDE equipped with agentic capabilities that natively support the Model Context Protocol (MCP). By registering AgentCorp in Antigravity's configuration, the Antigravity agent can:
+- Inspect unread messages, assigned tasks, and the next recommended action in one call (`get_work_queue`).
+- Accept an approved proposal and start its task atomically from the agent's perspective (`accept_handoff`).
+- Send implementation diffs, status updates, and test results (`send_message`).
+- Publish versioned, access-controlled code artifacts (`create_artifact`).
+
+---
+
+## 2. Configuration (`mcp_config.json`)
+
+Antigravity IDE reads global MCP server configurations from:
+
+* **Windows**: `C:\Users\<username>\.gemini\config\mcp_config.json`
+* **macOS / Linux**: `~/.gemini/config/mcp_config.json`
+
+### Step 1: Open Configuration File
+Open `C:\Users\<username>\.gemini\config\mcp_config.json` in your editor.
+
+### Step 2: Add AgentCorp Server Definition
+Add the `agentcorp` server entry to the `mcpServers` object, binding it to the `developer` role:
+
+```json
+{
+  "mcpServers": {
+    "agentcorp": {
+      "command": "node",
+      "args": [
+        "C:\\Users\\<username>\\Desktop\\AgentCorp\\dist\\cli.js",
+        "mcp",
+        "--role",
+        "developer",
+        "--config",
+        "C:\\Users\\<username>\\Desktop\\AgentCorp\\org.toml",
+        "--db",
+        "C:\\Users\\<username>\\Desktop\\AgentCorp\\.agentcorp\\agentcorp.db"
+      ]
+    }
+  }
+}
+```
+
+> [!TIP]
+> Use an absolute path for `--config` so that Antigravity reaches the broker regardless of your editor's current working directory. AgentCorp automatically derives `--db`, `--credentials`, and daemon control files relative to the config directory. Explicit `--db` arguments are optional overrides. On Windows, use double backslashes (`\\`) in JSON.
+
+---
+
+## 3. How the Connection Works
+
+1. **Auto-Spawning**: When Antigravity initializes, the stdio adapter checks if the AgentCorp daemon is active. If not, it automatically spawns the central daemon in the background.
+2. **Identity Lockdown**: The adapter automatically loads the `developer` bearer token from `.agentcorp/credentials.json`. Antigravity's agent identity is cryptographically enforced and cannot be spoofed.
+3. **Tool Injection**: Antigravity automatically registers the 15 AgentCorp tools, including:
+   - `whoami`, `register_role`
+   - `list_tasks`, `create_task`, `update_task_status`
+   - `get_inbox`, `send_message`, `acknowledge_message`, `accept_handoff`, `get_thread`
+   - `get_work_queue` (combines active tasks, unread messages, presence, and next actions)
+   - `create_artifact`, `list_artifacts`, `get_artifact`
+   - `get_operation` (lookup results of idempotent operations)
+4. **Self-Healing Proxy**: The stdio proxy features auto-reconnection with bounded exponential backoff. If the central broker restarts, Antigravity's in-flight session recovers seamlessly.
+5. **Idempotency & Zero Duplication**: Mutations accept `idempotency_key`. Retried network requests replay the exact cached outcome without creating duplicate tasks, messages, or approvals.
+
+---
+
+## 4. Example Agent Prompt & Handoff Best Practices
+
+Once configured, you can prompt the Antigravity agent in the sidebar chat:
+
+> *"Call `get_work_queue` and follow the highest-priority applicable next action. Use `accept_handoff` for an approved task proposal."*
+
+### Coordination Guidelines:
+- **Standing Instructions**: Add the prompt above as a standing instruction at session start. MCP cannot wake an idle agent model autonomously.
+- **Lightweight Handoffs**: Coordinate using concise IDs and summaries (`taskId`, `messageId`, diff summary). Do not dump large file trees or bulk artifacts into chat prompts; read artifacts on demand with `get_artifact`.
+
+After upgrading AgentCorp or changing authentication settings, rebuild the
+package (`npm run build`), restart the daemon (`agentcorp stop && agentcorp start`),
+and restart the IDE's MCP connection if new tools are added. Existing
+stdio processes continue running their previously loaded adapter code.

package/docs/guides/claude-cursor-setup.md

@@ -0,0 +1,76 @@
+# Claude Code, Cursor, and VS Code Setup Guide
+
+AgentCorp is fully vendor-agnostic and interoperates with any host that implements the Model Context Protocol (MCP). This guide covers configuring **Claude Desktop**, **Claude Code**, **Cursor**, **Windsurf**, and **VS Code**.
+
+---
+
+## 1. Claude Desktop / Claude Code
+
+Claude reads its MCP servers from `claude_desktop_config.json`:
+
+* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Configuration Snippet
+Add the following to your `mcpServers` object:
+
+```json
+{
+  "mcpServers": {
+    "agentcorp": {
+      "command": "node",
+      "args": [
+        "/path/to/AgentCorp/dist/cli.js",
+        "mcp",
+        "--role",
+        "architect",
+        "--config",
+        "/path/to/AgentCorp/org.toml",
+        "--db",
+        "/path/to/AgentCorp/.agentcorp/agentcorp.db"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 2. Cursor
+
+Cursor supports workspace-level and user-level MCP servers.
+
+### Workspace Setup (`.cursor/mcp.json`)
+Create or edit `.cursor/mcp.json` in your repository root:
+
+```json
+{
+  "mcpServers": {
+    "agentcorp-developer": {
+      "command": "node",
+      "args": [
+        "./dist/cli.js",
+        "mcp",
+        "--role",
+        "developer",
+        "--config",
+        "./org.toml",
+        "--db",
+        "./.agentcorp/agentcorp.db"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 3. Windsurf & Generic VS Code Extensions
+
+For Windsurf or any VS Code MCP extension supporting stdio:
+
+1. Specify `node` as the executable.
+2. Pass arguments:
+   `["<absolute-path-to-agentcorp>/dist/cli.js", "mcp", "--role", "<role-id>", "--config", "<path-to-org.toml>", "--db", "<path-to-db>"]`.
+3. The adapter will handle daemon auto-spawning, role authentication, and tool routing transparently.
+4. Specifying `--config` automatically derives `--db`, credentials, and daemon control files relative to the config file's directory. Providing `--db` is an optional override for custom database paths.

package/docs/guides/codex-setup.md

@@ -0,0 +1,75 @@
+# OpenAI Codex Setup Guide
+
+This guide walks you through configuring **OpenAI Codex** (Desktop App or Extension, powered by models like **ChatGPT 5.6-sol**) to act as a coordinated member of your AgentCorp team (such as the **`architect`** / **Planner & Reviewer** role).
+
+---
+
+## 1. Overview
+
+OpenAI Codex provides reasoning and planning capabilities. When bound to AgentCorp as the **`architect`**, Codex can:
+- Decompose system goals into milestone tasks (`create_task`).
+- Prepare tasks for peer implementers (`create_task`) and send linked proposals (`send_message`).
+- Inspect one prioritized coordination view at session start (`get_work_queue`).
+- Dispatch typed architecture proposals and reviews (`send_message`).
+- Review code diffs and artifacts submitted by the developer (`list_artifacts`, `get_artifact`).
+
+---
+
+## 2. Configuration (`config.toml`)
+
+Codex reads MCP server definitions from its global TOML configuration file:
+
+* **Windows**: `C:\Users\<username>\.codex\config.toml`
+* **macOS / Linux**: `~/.codex/config.toml`
+
+### Step 1: Open Configuration File
+Open `C:\Users\<username>\.codex\config.toml` in your editor.
+
+### Step 2: Add AgentCorp Server Definition
+Add the `[mcp_servers.agentcorp]` block to your `config.toml`, binding Codex to the `architect` role:
+
+```toml
+[mcp_servers.agentcorp]
+command = "node"
+args = [
+  "C:\\Users\\<username>\\Desktop\\AgentCorp\\dist\\cli.js",
+  "mcp",
+  "--role",
+  "architect",
+  "--config",
+  "C:\\Users\\<username>\\Desktop\\AgentCorp\\org.toml",
+  "--db",
+  "C:\\Users\\<username>\\Desktop\\AgentCorp\\.agentcorp\\agentcorp.db"
+]
+```
+
+> [!NOTE]
+> On Windows, ensure path backslashes are escaped (`\\`) in TOML strings, or use forward slashes (`/`). Providing `--config` automatically derives the project-scoped database (`.agentcorp/agentcorp.db`), credentials, and daemon files; `--db` is optional.
+
+---
+
+## 3. How the Connection Works
+
+1. **Role Enforcement**: Codex connects through a role-bound stdio adapter that enforces the `architect` identity using the credentials stored in `.agentcorp/credentials.json`.
+2. **Peer Isolation**: In `org.toml`, the `architect` is configured with `allowed_peers = ["developer"]`. Codex can only communicate with authorized roles.
+3. **Approval Gating**: When Codex sends a `proposal` to the developer, AgentCorp's policy engine intercepts it and queues it for human review before it reaches Antigravity's inbox.
+
+---
+
+## 4. Example Codex Prompt
+
+In the Codex extension or desktop app, you can issue commands like:
+
+> *"Check the tasks in AgentCorp, create a new task for 'Implement SQLite Index Optimization', and send a proposal message to the developer role with the architectural specification."*
+
+Codex will automatically call `create_task` and `send_message`, which will appear in your Human Console for approval.
+
+Add this standing instruction to the Codex project guidance:
+
+> At the start of each session and after every coordination mutation, call
+> `get_work_queue`. Follow its highest-priority applicable next action before
+> creating duplicate tasks or messages.
+
+Creating a task with `assigned_to` records the intended assignee but does not
+expose actionable work to that role. The linked proposal's approval activates
+the assignment.