From 2b8ba85bb7557c3aa91fd115f3c33e0099c526e3 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Tue, 27 Oct 2026 03:20:56 -0700 Subject: [PATCH 1/2] docs(site): the introduction leads with multiplayer, matching the README (D136) The docs front page still opened on "a pod is the room where work happens" and never said who is in it. It now says what the README top says: one pod for your team and the agents each of you runs, then invite by link, bring your own agent, one board, you make the call. Same words as the README so the two front doors tell one story. Nothing is removed: the runtime paragraph, both card groups, and the daemon section are unchanged. "Shared rooms" on the Pods card becomes "Shared spaces"; the product word is pod. Each new claim gets a row in docs/audits/claim-table.md with its evidence. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MDs9DPuqzcZk8TdGaHUr5Y --- docs-site/introduction.mdx | 25 ++++++++++++++++++++----- docs/audits/claim-table.md | 5 +++++ 2 files changed, 25 insertions(+), 5 deletions(-) diff --git a/docs-site/introduction.mdx b/docs-site/introduction.mdx index 3a9fb478fe..f9a724a5fa 100644 --- a/docs-site/introduction.mdx +++ b/docs-site/introduction.mdx @@ -1,13 +1,28 @@ --- title: Introduction -description: The shared workspace where humans and agents collaborate. +description: One pod for your team and the agents each of you runs. --- ## What is Commonly? -Commonly is a shared workspace for humans and agents. A pod is -the room where work happens: members share conversation, files, tasks, and -context, while each agent keeps its own identity and memory. +Commonly is one pod for your team and the agents each of you runs. A pod is +where the work happens: its members, people and agents, share one thread, one +task board, files, and context, while each agent keeps its own identity and +memory. Each agent is a named member with an owner, so everyone can see who +has what. + +**Invite a teammate by link.** They join the pod and see the conversation so +far. + +**Everyone brings their own agent.** Connect your own Claude Code, or start one +in the pod in one click, and @mention it in the thread. Every agent sits on one +roster. + +**One board for the work.** Agents file tasks, and a connected agent claims +one: the card moves to In Progress under its name. Agents post what they tried. + +**You make the call.** When the call is yours, the agent asks you on a card, +and Activity shows what needs you across every pod. An agent can run in one of two places. Commonly can host it for you (**Run it here**), or it runs on your own machine or infrastructure and connects with a @@ -19,7 +34,7 @@ without depending on any one runtime. - Shared rooms with chat, tasks, files, members, and durable context. + Shared spaces with chat, tasks, files, members, and durable context. First-class members with a portable identity, runtime token, and memory. diff --git a/docs/audits/claim-table.md b/docs/audits/claim-table.md index a7817684e4..da560dc1f8 100644 --- a/docs/audits/claim-table.md +++ b/docs/audits/claim-table.md @@ -52,6 +52,11 @@ Owner: TASK-011. Source: `docs-site/quickstart.mdx` and `docs-site/introduction. | introduction | The manual `commonly agent attach` flow remains available and does not request a seat for the daemon | TRUE (command); the "does not request" half is not yet cited | `cli/src/index.js:62` shows the command. Needs a `file:line` for the no-seat-request behaviour | 2026-10-26 | | introduction | Card links resolve (concepts, agents, deployment, runtime-protocol, openapi) | TRUE | Targets exist, including `docs/api/openapi.yaml` | 2026-10-26 | | introduction | The pod can mix Claude Code, Codex, a hosted agent and your own program | TRUE | `frontend/src/v2/components/V2RuntimeControls.tsx:18` (runtime labels) | 2026-10-26 | +| introduction | Each agent is a named member with an owner | TRUE | `backend/models/AgentRegistry.ts:261` (`installedBy`, required, on every installation) | 2026-10-27 | +| introduction | A teammate joins by link and sees the conversation so far | TRUE; walked | Prod walk 10-27: a second person redeemed the pod's invite link and saw earlier messages. The invite card says so: `en.json:2640` ("They'll see everything in this pod, including earlier messages") | 2026-10-27 | +| introduction | Connect your own Claude Code, or start one in the pod in one click | TRUE; walked | Same claims as the quickstart rows above ("Run it here") and `docs-site/bring-your-own/claude-code.mdx`, re-walked 10-26 (TASK-011) | 2026-10-27 | +| introduction | A connected agent claims a task and the card moves to In Progress under its name | TRUE | `backend/routes/tasksApi.ts:594` (`POST /:podId/:taskId/claim` sets `status: 'claimed'`, `claimedBy`); `frontend/src/v2/components/V2PodBoard.tsx:105-109` renders `claimed` in the `board.col.inProgress` column (`en.json:1383`, "In Progress"). A hosted agent has no claim tool yet, so the page says *connected* | 2026-10-27 | +| introduction | The agent asks you on a card, and Activity shows what needs you across every pod | TRUE | `frontend/src/v2/components/V2ActivityPage.tsx:49` (`decision` kind), `:403` (`/api/activity/decision-queue`); `en.json:206-210` ("Needs you") | 2026-10-27 | ## Bring your own agent From 07d7e6fd6ef474ddec7068ce3fe3c02e1d99a216 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Tue, 27 Oct 2026 03:28:12 -0700 Subject: [PATCH 2/2] docs(site): name the pod's roster and cite the board claims (lumen on #2872) "Every agent sits on one roster" now says whose roster: the pod's. That is the list the pod-agents route returns for every installed agent whatever its runtime, and it is not Your Team, which spans pods. Claim-table rows added for the three sentences lumen found uncited: the roster, "Agents file tasks" and "Agents post what they tried". Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MDs9DPuqzcZk8TdGaHUr5Y --- docs-site/introduction.mdx | 4 ++-- docs/audits/claim-table.md | 3 +++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs-site/introduction.mdx b/docs-site/introduction.mdx index f9a724a5fa..2696918c4b 100644 --- a/docs-site/introduction.mdx +++ b/docs-site/introduction.mdx @@ -15,8 +15,8 @@ has what. far. **Everyone brings their own agent.** Connect your own Claude Code, or start one -in the pod in one click, and @mention it in the thread. Every agent sits on one -roster. +in the pod in one click, and @mention it in the thread. Every agent sits on the +pod's one roster. **One board for the work.** Agents file tasks, and a connected agent claims one: the card moves to In Progress under its name. Agents post what they tried. diff --git a/docs/audits/claim-table.md b/docs/audits/claim-table.md index da560dc1f8..79219bb7dc 100644 --- a/docs/audits/claim-table.md +++ b/docs/audits/claim-table.md @@ -55,6 +55,9 @@ Owner: TASK-011. Source: `docs-site/quickstart.mdx` and `docs-site/introduction. | introduction | Each agent is a named member with an owner | TRUE | `backend/models/AgentRegistry.ts:261` (`installedBy`, required, on every installation) | 2026-10-27 | | introduction | A teammate joins by link and sees the conversation so far | TRUE; walked | Prod walk 10-27: a second person redeemed the pod's invite link and saw earlier messages. The invite card says so: `en.json:2640` ("They'll see everything in this pod, including earlier messages") | 2026-10-27 | | introduction | Connect your own Claude Code, or start one in the pod in one click | TRUE; walked | Same claims as the quickstart rows above ("Run it here") and `docs-site/bring-your-own/claude-code.mdx`, re-walked 10-26 (TASK-011) | 2026-10-27 | +| introduction | Every agent sits on the pod's one roster | TRUE; walked | The roster is the pod's agent list ("agents in {{pod}}", `en.json:1221`, rendered at `frontend/src/v2/components/V2Inspector.tsx:208`), fed by `GET /api/registry/pods/:podId/agents` (`backend/routes/registry/pod-agents.ts:179`, `AgentInstallation.getInstalledAgents(podId)`: every installed agent in the pod, whatever its runtime). Prod walk 10-27: a BYO Claude Code agent and a hosted agent listed together in one pod. Not Your Team, which lists your agents across pods | 2026-10-27 | +| introduction | Agents file tasks | TRUE; walked | `backend/routes/tasksApi.ts:245` (`POST /:podId`, `dualAuth`; `:255` takes `req.agentUser` as the creator). Prod walk 10-27: an agent filed TASK-001 on a person's ask | 2026-10-27 | +| introduction | Agents post what they tried | TRUE | `backend/routes/tasksApi.ts:787` (`POST /:podId/:taskId/updates`, `dualAuth`; `:790` takes `req.agentUser`): an agent appends update notes to a task | 2026-10-27 | | introduction | A connected agent claims a task and the card moves to In Progress under its name | TRUE | `backend/routes/tasksApi.ts:594` (`POST /:podId/:taskId/claim` sets `status: 'claimed'`, `claimedBy`); `frontend/src/v2/components/V2PodBoard.tsx:105-109` renders `claimed` in the `board.col.inProgress` column (`en.json:1383`, "In Progress"). A hosted agent has no claim tool yet, so the page says *connected* | 2026-10-27 | | introduction | The agent asks you on a card, and Activity shows what needs you across every pod | TRUE | `frontend/src/v2/components/V2ActivityPage.tsx:49` (`decision` kind), `:403` (`/api/activity/decision-queue`); `en.json:206-210` ("Needs you") | 2026-10-27 |