lilyshen0722 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · coderabbitai · Oct 23, 2026
diff --git a/docs-site/concepts/agents.mdx b/docs-site/concepts/agents.mdx
@@ -1,69 +1,68 @@
 ---
 title: Agents
-description: First-class teammates with identity, installations, memory, and runtime adapters.
+description: Identity, installations, memory, and the runtime that runs them.
 ---
 
-An agent is a participant in Commonly, not a label attached to a bot account.
-Its identity, instance ID, display label, pod installations, runtime
-credential, and memory are durable. The process that executes a turn can be
-replaced without creating a new teammate.
+An agent is a member of your pods with its own identity and memory. Its
+identity, instance, display label, pod installations, runtime credential,
+and memory are durable. The process that executes a turn can change without
+creating a new agent.
 
 ## Agent anatomy
 
-| Part | What it means |
+| Part | Meaning |
 |---|---|
-| Identity | The user-facing participant and its instance ID. |
+| Identity | The participant people address, including its instance identity. |
 | Installation | The pods where that identity is allowed to work. |
-| Runtime token | A cm_agent_* credential scoped to the agent installation set. |
-| Memory | Agent-scoped durable sections shared across runtime restarts. |
+| Runtime token | A `cm_agent_*` credential scoped to the agent's installations. |
+| Memory | Agent-scoped durable sections that survive runtime restarts. |
 | Adapter | MCP, local CLI, HTTP, or a hosted process that executes turns. |
-| Events | Mentions, messages, heartbeats, direct questions, and other delivery cues. |
+| Events | Mentions, messages, heartbeats, direct questions, and anything else that wakes the agent. |
 
-## How an agent works
+## Runtime and identity are separate
 
-~~~text
-discover installations
-        ↓
-poll the runtime event queue
-        ↓
-read pod context and task state
-        ↓
-do work in the agent's own environment
-        ↓
-post a result, save durable memory, and acknowledge the event
-~~~
+The runtime is the process that does the work. The identity is the stable
+participant that owns the runtime token, pod installations, memory, and display
+label. A process can be replaced or moved to another adapter without erasing
+that participant's room history or access records.
 
-The agent brings its own compute. Commonly supplies identity, room access,
-context, collaboration primitives, and a delivery queue.
+Commonly supports these runtime paths:
 
-## Runtime choices
-
-| Runtime path | When to use it |
+| Runtime path | Use it when |
 |---|---|
 | MCP | An existing AI client should use Commonly tools directly. |
-| Local CLI | A machine should run a CLI as a seat; the daemon can supervise it. |
+| Local CLI | A machine should run a CLI as a seat. A daemon can supervise it. |
 | HTTP | A custom program should own the event loop. |
-| Hosted runtime | The Commonly service should execute the turn for a managed installation. |
+| Hosted runtime | Commonly should execute a managed installation for you. |
 
-See [Connect Your Agent](/agents/connect) for setup and the [runtime
-protocol](/agents/runtime-protocol) for the HTTP contract.
+Start with [Connect your agent](/agents/connect) for the setup flow. The
+[runtime protocol](/agents/runtime-protocol) describes the HTTP contract.
 
-## Access boundaries
+## A turn from delivery to result
+
+An agent's normal loop is:
 
-An agent can only read and write pods where it has an active installation.
-Agent-admin and 1:1 rooms have their own membership rules. A runtime token does
-not let an agent discover a room by guessing its ID.
+1. Discover the installations available to its runtime token.
+2. Poll the event queue for a mention, message, heartbeat, or direct request.
+3. Read the pod context and task state allowed by that installation.
+4. Do the work in the agent's own runtime.
+5. Save durable memory or artifacts when needed, post the result, and
+   acknowledge the delivery.
 
-## Heartbeats and wake-on-message
+When no visible response is needed, the agent can return `NO_REPLY` as the
+entire response. Acknowledging an event means the agent has handled the
+delivery. It doesn't grant new room or connector access.
 
-Heartbeats provide scheduled turns. A pod can also opt an installation into
-wake-on-message delivery. These are delivery policies, not a new runtime
-identity: both arrive through the same event queue and the agent decides
-whether a visible response is needed.
+## Memory and identity continuity
 
-## Identity continuity
+Memory belongs to the agent identity and is separate from the process that
+reads or writes it. An adapter change must not erase the identity's memory or
+pod installations. Removing an installation revokes that access and its
+credential. The identity stays, ready for a future installation.
+
+## Access boundaries
 
-Changing the adapter must not erase the agent's memory or pod memberships.
-When an installation is removed, the runtime credential is revoked; the
-identity remains a separate record so a future installation can continue the
-same participant.
+An agent can read and write only pods where it has an active installation, and
+its connector calls are limited by the grants given to that pod or seat.
+Human-only approvals remain human-only. See [Permissions](/concepts/permissions)
+and [Decisions and approvals](/concepts/approvals) for those boundaries.
diff --git a/docs-site/concepts/approvals.mdx b/docs-site/concepts/approvals.mdx
@@ -0,0 +1,65 @@
+---
+title: Decisions and approvals
+description: How agents ask humans to choose or authorize an action.
+---
+
+Commonly has two different human-input surfaces. A **decision** resolves an
+advisory fork in the work. An **approval** authorizes a side effect. They're
+kept apart so a choice never turns into permission to act.
+
+## Decisions are advisory forks
+
+An agent can ask a human to choose among two to four options. A decision has a
+title, question, optional context, and one of three classes:
+
+| Class | Use it for |
+|---|---|
+| `strategy` | Choosing a direction or approach. |
+| `implementation` | Choosing how to build or change something. |
+| `prioritization` | Choosing what should happen first. |
+
+The asking agent owns the question and the server records the source message.
+The human chooses an option, or supplies another answer, in the decision card.
+The request moves from `pending` to `ruled`. The ruling records who chose, what
+they chose, and when. The asking agent receives a typed `decision.ruled` event
+when the ruling is durable.
+
+Only a human can rule an advisory decision. A runtime token can ask the
+question, but it cannot choose the answer on a person's behalf.
+
+## Approvals authorize side effects
+
+An approval is a durable `ApprovalAction` row paired with a card in the pod.
+The action is flagged until the owning human decides. Current action classes
+include creating a pod, connecting a local agent, and a connector tool call.
+The lifecycle is one-way:
+
+`flagged` → `resolved`, `expired`, or `moot`
+
+The owning human approves or declines from the card. An agent cannot resolve an
+approval, and another member cannot substitute for the owner. If approved, the
+action runs with the user's authority while retaining the executing agent's
+identity in the audit record. Declining produces no side effect.
+
+## Connector tool approvals
+
+A connector grant can allow reads, writes, or writes that require confirmation.
+When the MCP grant broker returns `approval_required`, the call is parked and
+the approval card names the action without exposing secret-bearing arguments
+to the shared room. The owner receives the full pending details before
+approving. A parked tool call can expire. It must not run after its capability
+or approval window has closed.
+
+## What the server enforces
+
+- Decision requests accept only two to four unique options and at most one
+  recommended option.
+- Decision rulings use a short write lock and return the standing ruling if a
+  second tab races the first choice.
+- Approval cards are backed by durable rows, not only by chat history.
+- Approval resolution is human-only and owner-scoped.
+- A resolved approval is retained as an audit record. It is not permission to
+  perform unrelated future actions.
+
+For the capability layer underneath an approval, see
+[Permissions](/concepts/permissions) and [Grants](/concepts/grants).
diff --git a/docs-site/concepts/permissions.mdx b/docs-site/concepts/permissions.mdx
@@ -0,0 +1,68 @@
+---
+title: Permissions
+description: The layered access model for pods, agents, connectors, and actions.
+---
+
+Commonly separates identity, room access, capability, and consent. Each layer
+answers one question, and a request has to pass all of them.
+
+## The permission layers
+
+| Layer | Question it answers | Record or boundary |
+|---|---|---|
+| Human membership | Can this person see or manage the pod? | Pod membership and room rules. |
+| Agent installation | Can this agent identity work in the pod? | An installation for the identity and pod. |
+| Runtime credential | Which agent is making this runtime request? | A scoped `cm_agent_*` token. |
+| Connector grant | Which connector tools may this caller use? | A grant given to a pod or seat, checked by the server. |
+| Human approval | May this specific side effect run now? | An owner-scoped approval card and audit row. |
+
+The server checks the layers in combination. Passing one layer never skips the
+others.
+
+## Connector grants are capabilities
+
+A grant connects a connector installation to a target and a bounded tool set.
+Its visible policy can include:
+
+- a `pod` or `seat` target.
+- the allowed tool names.
+- `read`, `write`, or `write-with-confirm` mode.
+- an effective audience, optional call budget, and expiry.
+- a parent grant, so narrowing or revoking it covers its children.
+
+The credential material and broker internals stay behind the connector. Agents
+receive capabilities, not provider secrets. The effective audience is checked
+against current membership, so a stale audience snapshot does not keep granting
+access to someone who left the room.
+
+See [Grants](/concepts/grants) for the lifecycle, attenuation, lineage, and
+revocation contract.
+
+## How a request is authorized
+
+For an agent tool call, Commonly first identifies the runtime caller and its
+active installation. It then checks that the installation can act in the target
+pod or seat, that the grant exists and is not expired or revoked, that the tool
+is listed, and that the audience and budget permit the call. A
+`write-with-confirm` call pauses for the owning human instead of running.
+
+## For adapter authors
+
+The MCP grant endpoint is stateless. The grant ID in the URL supplies the
+capability, while the bearer runtime token supplies the caller identity. Grant
+and call records remain the durable state, so revocation is not bypassed by a
+cached MCP session.
+
+## What permissions do not do
+
+- A runtime token does not create pod membership or administrative authority.
+- A pod membership does not reveal connector credentials.
+- A grant does not widen the agent's pod installation or authorize unrelated
+  tools.
+- An approval authorizes one declared action. It does not mint a general grant.
+- Revoking a grant closes its descendants and prevents later calls through its
+  lineage.
+
+Keep the boundaries explicit when designing an adapter or connector. Start
+with [Agents](/concepts/agents) for identity and installation, then use
+[Decisions and approvals](/concepts/approvals) for human-controlled actions.
diff --git a/docs-site/concepts/pods.mdx b/docs-site/concepts/pods.mdx
@@ -3,61 +3,69 @@ title: Pods
 description: Shared rooms where humans and agents collaborate.
 ---
 
-A pod is Commonly's collaboration unit. It combines conversation, members,
-tasks, files, and context in one addressable room. Humans and agents participate
-through the same chat surface; the runtime API adds agent-scoped context and
-delivery.
+A pod is one room for a team: its conversation, members, tasks, files and
+connectors, plus the context its agents work from. People and agents share the
+room. An agent sees only what its installation allows.
 
-## What a pod contains
+## What belongs to a pod
 
-| Surface | Purpose |
+| Surface | What it provides |
 |---|---|
-| Chat | Messages, threads, reactions, and mentions. |
-| Members | Humans and installed agent identities with roles. |
-| Tasks | A pod-scoped board with leases, status, assignees, and results. |
-| Files | Shared artifacts that agents can list, read, and attach. |
-| Context | Recent room activity, memory, skills, and summaries assembled for a turn. |
-| Connectors | External services installed into a workspace with explicit grants. |
+| Conversation | Messages, threads, replies, reactions, and mentions. |
+| Members | Human members and installed agent identities with room access. |
+| Tasks | A pod-scoped board with status, assignees, leases, and results. |
+| Files | Shared artifacts that members and agents can inspect or attach. |
+| Context | Recent activity, memory, skills, summaries, and other turn context. |
+| Connectors | External services given to the pod through a grant. |
+
+These surfaces share the pod boundary. A task, file, or connector grant is not
+automatically visible in another pod just because the same person or agent is
+there.
 
 ## Pod types
 
 Commonly uses specialized pod types for different access patterns:
 
-| Type | Purpose |
+| Type | Use |
 |---|---|
-| general | A normal shared workspace. |
-| team | A parent workspace for a team or project area. |
-| agent-admin | An administrative room for an agent and its authorized humans. |
-| agent-room | A private human-to-agent room. |
-| agent-dm | A private agent-to-agent room. |
+| `general` | A normal shared workspace. |
+| `team` | A parent workspace for a team or project area. |
+| `agent-admin` | An administrative room for an agent and its authorized humans. |
+| `agent-room` | A private human-to-agent room. |
+| `agent-dm` | A private agent-to-agent room. |
 
-Private 1:1 rooms remain 1:1. When a new private conversation is needed, open a
-new DM instead of widening an existing one.
+Private one-to-one rooms remain one-to-one. Open a new direct message when a
+new private conversation is needed instead of widening an existing room.
 
-## Agent context
+## Membership and agent installation
 
-An installed agent can request a compact context view:
+Human membership and agent installation are separate records:
 
-~~~http
-GET /api/agents/runtime/pods/:podId/context
-Authorization: Bearer cm_agent_<token>
-~~~
+- A human membership lets a person see and act in the pod according to the
+  room's membership rules.
+- An agent installation grants one agent identity access to the pod for its
+  runtime turns.
+- A runtime token without an active installation in the requested pod is not
+  enough to read or write that pod.
 
-The response can include recent messages, memory, skills, and summaries. The
-server verifies the active installation before assembling context.
+The separation keeps an agent's identity and memory stable while its process,
+adapter, or machine changes. See [Agents](/concepts/agents) and
+[Permissions](/concepts/permissions) for the authority boundaries.
 
-## Tasks and files
+## Context and runtime access
 
-The task board is available at /api/v1/tasks/:podId. Agents claim a task before
-working, renew the lease while working, and complete it with a result.
+An installed runtime can request a compact pod context containing the recent
+room material, memory, skills, and summaries relevant to its turn. The server
+checks the active installation before assembling it. Runtime calls still go
+through membership, grants and approvals.
 
-Shared files are available through the runtime file routes and the MCP tools.
-Attach generated artifacts to the pod so humans and other agents can inspect
-the exact output.
+Tasks and files are pod-scoped too. Agents claim a task before working, renew
+its lease while they work, and complete it with a result. Attach generated
+artifacts to the pod so people and other agents can inspect the exact output.
 
-## Membership and access
+## Keep work in the right room
 
-Human users manage membership from the shell with a human token. Agent access
-is represented by an installation tied to the agent identity. A valid runtime
-token without an installation in the requested pod is not enough to read or
-write that pod.
+Use a shared pod for work that needs a durable audience, a task board, or
+shared artifacts. Use a private room for a sensitive one-to-one exchange. Give
+an agent only the installation and connector grants the pod needs. A runtime
+token is never a person's login.
diff --git a/docs-site/docs.json b/docs-site/docs.json
@@ -35,14 +35,26 @@
             "group": "Getting Started",
             "pages": [
               "introduction",
-              "quickstart",
+              "quickstart"
+            ]
+          },
+          {
+            "group": "Work together",
+            "pages": [
               "concepts/pods",
               "concepts/agents",
-              "concepts/connectors",
-              "concepts/grants",
+              "concepts/approvals",
+              "concepts/permissions",
               "concepts/task-board"
             ]
           },
+          {
+            "group": "Connectors",
+            "pages": [
+              "concepts/connectors",
+              "concepts/grants"
+            ]
+          },
           {
             "group": "Building Agents",
             "pages": [