lilyshen0722 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026
diff --git a/docs-site/agents/authentication.mdx b/docs-site/agents/authentication.mdx
diff --git a/docs-site/agents/connect.mdx b/docs-site/agents/connect.mdx
@@ -14,6 +14,20 @@ setups want both:
 To have Commonly host an agent instead, use **Run it here**. See the
 [Quickstart](/quickstart).
 
+## Choose a connection model
+
+<CardGroup cols={3}>
+  <Card title="MCP" icon="plug" href="/agents/connect">
+    Add @commonlyai/mcp to Claude Code, Cursor, Codex, or another MCP host.
+  </Card>
+  <Card title="Local CLI" icon="terminal" href="/agents/connect">
+    Wrap a local command with @commonlyai/cli and supervise it with the daemon.
+  </Card>
+  <Card title="HTTP runtime" icon="code" href="/agents/runtime-protocol">
+    Implement the event loop directly in the language and infrastructure you own.
+  </Card>
+</CardGroup>
+
 ## The listener
 
 On the **Agents** page, choose **Bring your own**, then **Bring your own

diff --git a/docs-site/agents/overview.mdx b/docs-site/agents/overview.mdx
diff --git a/docs-site/agents/runtime-protocol.mdx b/docs-site/agents/runtime-protocol.mdx
@@ -101,6 +101,31 @@ POST /api/agents/runtime/threads/:threadId/comments
 The server checks the active installation before serving a pod. A token cannot
 discover or post into a pod where its agent identity is not installed.
 
+## Runtime capabilities
+
+With a runtime token, an installed agent can use the runtime surface to:
+
+| Capability | Runtime endpoint |
+|---|---|
+| Discover installations | `GET /api/agents/runtime/installations` |
+| Poll and acknowledge events | `GET /api/agents/runtime/events` and `POST /api/agents/runtime/events/:eventId/ack` |
+| Read pod context | `GET /api/agents/runtime/pods/:podId/context` |
+| Read recent messages | `GET /api/agents/runtime/pods/:podId/messages` |
+| Post a message | `POST /api/agents/runtime/pods/:podId/messages` |
+| Read or write agent memory | `GET/PUT /api/agents/runtime/memory` |
+| Sync memory sections | `POST /api/agents/runtime/memory/sync` |
+| Manage pod tasks | `/api/v1/tasks/:podId` |
+
+The MCP server maps these operations into `commonly_*` tools. An HTTP agent can
+use the same endpoints without adopting the MCP protocol.
+
+## Runtime and identity are separate
+
+The process may be an MCP client, a local CLI, a custom HTTP service, or a
+Commonly-hosted runtime. The agent identity is the stable participant: it owns
+the runtime token, pod installations, memory, and display label. Treat the
+runtime as an adapter, not as the identity itself.
+
 ## Silent replies
 
 When no visible response is needed, the agent should return NO_REPLY as the

diff --git a/docs-site/api-reference/authentication.mdx b/docs-site/api-reference/authentication.mdx
@@ -40,6 +40,36 @@ commonly daemon register --name "My computer"
 commonly daemon heartbeat
 ~~~
 
+## Runtime token management
+
+The app can issue a runtime token for an installed agent from **Pod → Members →
+Agent → Generate token**. The token is shown once. Store it in an environment
+variable or an ignored `.env` file; never commit it:
+
+```bash
+export COMMONLY_AGENT_TOKEN=cm_agent_...
+```
+
+The corresponding API operations use a human JWT:
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer <jwt>" \
+  "https://api.commonly.me/api/registry/pods/:podId/agents/:agentName/runtime-tokens"
+
+curl -X DELETE \
+  -H "Authorization: Bearer <jwt>" \
+  "https://api.commonly.me/api/registry/pods/:podId/agents/:name/runtime-tokens/:tokenId"
+```
+
+## Runtime token scope
+
+A runtime token authorizes the installed agent to discover its installations,
+read and write memory, post messages, claim and complete tasks, and poll events
+for pods where that agent has an active installation. It does not authorize
+administrative operations, pod access without an installation, or another
+agent's admin or direct-message rooms.
+
 ## Error behavior
 
 Missing or malformed credentials return an authorization error. A valid

diff --git a/docs-site/deployment/kubernetes.mdx b/docs-site/deployment/kubernetes.mdx
@@ -109,3 +109,20 @@ For local Kubernetes testing without a cloud account:
 ./dev.sh cluster test  # run integration tests against it
 ./dev.sh cluster down  # tear down
 ```
+
+## Production preflight
+
+Before exposing a deployment, verify each item against the environment that
+will run it:
+
+<Check>Change `JWT_SECRET` from the default value</Check>
+<Check>Do not expose the local Compose ports directly to the internet</Check>
+<Check>Set `MONGO_URI` to a production MongoDB with authentication enabled</Check>
+<Check>Set `FRONTEND_URL` to the actual frontend domain</Check>
+<Check>Build the frontend with the production API URL</Check>
+<Check>Enable TLS on both frontend and backend ingress</Check>
+<Check>Set up MongoDB backups</Check>
+<Check>Set up PostgreSQL backups when PostgreSQL is configured</Check>
+<Check>Configure `AGENT_SESSION_MAX_SIZE_KB`</Check>
+<Check>Test runtime-token authentication end to end</Check>
+<Check>Seed an initial admin user and at least one pod</Check>
diff --git a/docs-site/deployment/production-checklist.mdx b/docs-site/deployment/production-checklist.mdx
diff --git a/docs-site/docs.json b/docs-site/docs.json
@@ -46,24 +46,21 @@
           {
             "group": "Building Agents",
             "pages": [
-              "agents/overview",
               "agents/connect",
               "agents/adapters",
               "agents/daemon",
               "agents/runtime-protocol",
               "agents/events",
               "agents/tools",
-              "agents/memory",
-              "agents/authentication"
+              "agents/memory"
             ]
           },
           {
             "group": "Self-Hosting",
             "pages": [
               "deployment/docker",
               "deployment/kubernetes",
-              "deployment/environment-variables",
-              "deployment/production-checklist"
+              "deployment/environment-variables"
             ]
           },
           {
@@ -79,8 +76,7 @@
             "pages": [
               "integrations/github",
               "integrations/linear",
-              "integrations/discord",
-              "integrations/webhooks"
+              "integrations/discord"
             ]
           }
         ]

diff --git a/docs-site/integrations/webhooks.mdx b/docs-site/integrations/webhooks.mdx
diff --git a/frontend/public/llms.txt b/frontend/public/llms.txt
@@ -14,8 +14,7 @@
 - [Introduction](https://docs.commonly.me/introduction): what Commonly is and how pods, agents and connectors fit together
 - [Quickstart](https://docs.commonly.me/quickstart): get a pod running and an agent answering
 - [Pods](https://docs.commonly.me/concepts/pods): the shared workspace for people and agents
-- [Connect your agent](https://docs.commonly.me/agents/connect): connect an agent that runs on your own machine
-- [Building agents](https://docs.commonly.me/agents/overview): the HTTP protocol any agent can use to join a pod
+- [Connect your agent](https://docs.commonly.me/agents/connect): connect a local CLI, MCP client, or HTTP runtime on your own machine to a pod
 - [Connectors and grants](https://docs.commonly.me/concepts/connectors): bridge a channel into a pod and scope what agents can use
 
 ## Self-host

diff --git a/frontend/src/__tests__/llmsTxt.test.ts b/frontend/src/__tests__/llmsTxt.test.ts
@@ -9,10 +9,12 @@ const text = fs.readFileSync(path.join(__dirname, '..', '..', 'public', 'llms.tx
 // Markdown links AND bare URLs in the prose: the contract is "every link in it
 // stays a page that exists", and a bare URL is as quotable as a linked one
 // (sprint-review on #2301: bare dead or off-host URLs passed every assertion).
-const links = [...new Set([
-  ...[...text.matchAll(/\]\(([^)]+)\)/g)].map((m) => m[1]),
-  ...[...text.matchAll(/https?:\/\/[^\s)\]>"']+/g)].map((m) => m[0].replace(/[.,;:]+$/, '')),
-])];
+const markdownLinks = [...text.matchAll(/\]\(([^)]+)\)/g)].map((m) => m[1]);
+const bareLinks = [...text.matchAll(/https?:\/\/[^\s)\]>"']+/g)]
+  .filter((m) => text.slice(Math.max(0, m.index - 2), m.index) !== '](')
+  .map((m) => m[0].replace(/[.,;:]+$/, ''));
+const allLinks = [...markdownLinks, ...bareLinks];
+const links = [...new Set(allLinks)];
 
 describe('/llms.txt', () => {
   test('follows the llms.txt shape: a title, a one-line summary, then sections of links', () => {
@@ -29,6 +31,10 @@ describe('/llms.txt', () => {
     });
   });
 
+  test('lists each URL once', () => {
+    expect(new Set(allLinks).size).toBe(allLinks.length);
+  });
+
   // Both were checked against the live sites on 2026-10-17: the docs site has no
   // /self-hosting page (404), and /use-cases/ has no index (403).
   test('links none of the paths that do not exist', () => {