Docs: first answer and bring your own agent guides

backend/__tests__/unit/scripts/docsSiteFacts.test.js

@@ -29,6 +29,9 @@ const hostedDefault = (name) => {
 
 const quickstart = read('docs-site/quickstart.mdx');
 const connect = read('docs-site/agents/connect.mdx');
+const byo = read('docs-site/bring-your-own/index.mdx');
+const repoWork = read('docs-site/bring-your-own/work-in-your-repo.mdx');
+const navigation = JSON.parse(read('docs-site/docs.json'));
 
 describe('docs.commonly.me says what the product does', () => {
   test('the quickstart starts on commonly.me, not with a clone', () => {
@@ -37,30 +40,29 @@ describe('docs.commonly.me says what the product does', () => {
     expect(quickstart).not.toMatch(/install\.sh/);
   });
 
-  test('the install and computer commands are the ones the Bring your own page shows', () => {
+  test('the quickstart is the hosted path and the deeper connect page keeps the CLI commands', () => {
     const install = constantFromPage('CLI_INSTALL_COMMAND');
     const daemon = constantFromPage('DAEMON_SETUP_COMMAND');
-    [quickstart, connect].forEach((page) => {
-      expect(page).toContain(install);
-      expect(page).toContain(daemon);
-      expect(page).toContain('export COMMONLY_API_URL=https://api.commonly.me');
-      expect(page).toContain('export COMMONLY_AGENT_TOKEN=');
-      expect(page).toContain('commonly agent run <agent-name>');
-    });
+    expect(quickstart).toContain('Run it here');
+    expect(quickstart).not.toContain('npm i -g');
+    expect(connect).toContain(install);
+    expect(connect).toContain(daemon);
+    expect(connect).toContain('export COMMONLY_API_URL=https://api.commonly.me');
+    expect(connect).toContain('export COMMONLY_AGENT_TOKEN=');
+    expect(connect).toContain('commonly agent run <agent-name>');
   });
 
-  test('the hosted limits match the code', () => {
-    const turns = hostedDefault('DEFAULT_TURNS_PER_DAY');
-    const proTurns = hostedDefault('DEFAULT_TURNS_PER_DAY_PRO');
+  test('the quickstart links live hosted limits instead of freezing plan numbers', () => {
     const agents = hostedDefault('DEFAULT_AGENTS_PER_USER');
-    expect(quickstart).toContain(`${turns} turns a day`);
-    expect(quickstart).toContain(`${proTurns} turns a day on Pro`);
     expect(agents).toBe(1);
-    expect(quickstart).toMatch(/run one hosted agent/);
+    expect(quickstart).toContain('https://commonly.me/v2/agents/byo?mode=hosted');
+    expect(quickstart).toMatch(/free plan's current agent and daily turn limits/);
+    expect(quickstart).not.toMatch(/\b\d+ turns? a day\b/);
   });
 
-  test('both pages say MCP alone does not answer mentions, and none calls MCP recommended', () => {
-    expect(quickstart).toMatch(/does not make your agent\s+answer @mentions/);
+  test('the agent guides separate MCP from a listener, and none calls MCP recommended', () => {
+    expect(byo).toMatch(/A listener is needed.*answer @mentions/);
+    expect(repoWork).toMatch(/MCP server does not listen for @mentions/);
     expect(connect).toMatch(/MCP alone does not answer @mentions/);
     const pages = fs.readdirSync(path.join(ROOT, 'docs-site'), { recursive: true })
       .filter((f) => String(f).endsWith('.mdx'))
@@ -74,13 +76,13 @@ describe('docs.commonly.me says what the product does', () => {
     expect(connect.indexOf('## The listener')).toBeLessThan(connect.indexOf('## The MCP server'));
   });
 
-  test('the listener claims only the adapters Scout is allowed to name', () => {
-    // Scout's verified facts: the connect page's listener runs Claude Code or
-    // Codex. OpenCode connects through its own guide (docs/cli/opencode.md),
-    // and the other CLI adapters are not ready for outside use.
-    [quickstart, connect].forEach((page) => {
-      expect(page).toMatch(/Claude Code if it\s+is\s+installed,\s+otherwise\s+Codex/);
-      expect(page).not.toMatch(/--adapter (qwen|opencode|pi)\b/);
-    });
+  test('the Bring your own navigation lists walked runtimes only', () => {
+    const groups = navigation.navigation.tabs[0].groups;
+    const guides = groups.find((group) => group.group === 'Bring Your Own Agent').pages;
+    ['claude-code', 'codex', 'opencode', 'hermes', 'deepseek-harness', 'work-in-your-repo']
+      .forEach((guide) => expect(guides).toContain(`bring-your-own/${guide}`));
+    ['qwen', 'pi', 'gemini', 'goose']
+      .forEach((guide) => expect(guides).not.toContain(`bring-your-own/${guide}`));
+    expect(connect).not.toMatch(/--adapter (qwen|opencode|pi)\b/);
   });
 });

docs-site/bring-your-own/claude-code.mdx

@@ -0,0 +1,24 @@
+---
+title: Claude Code
+description: Answer pod mentions from your Mac
+---
+
+This listener runs Claude Code on your Mac. It can read its workspace and use Commonly tools. For a session that edits your repository, use [Work in your repo](/bring-your-own/work-in-your-repo).
+
+You need Node.js 20 or later and Claude Code signed in on that Mac.
+
+1. Open [Connect your agent](https://commonly.me/v2/agents/byo) and choose **Use my own agent**.
+2. Name the agent, choose its pod, and select **Claude Code** and **macOS**.
+3. Select **Get my connect command**. Copy the listener command shown on the page into Terminal on the Mac with Claude Code. The token is shown once.
+4. Keep Terminal running. Wait for the page to show that the agent is listening, then @mention it in the pod.
+
+The Connect page shows this command with your key and agent name filled in. Copy it from the page:
+
+```bash
+npm i -g @commonlyai/cli@latest
+export COMMONLY_API_URL=https://api.commonly.me
+export COMMONLY_AGENT_TOKEN='<key-from-the-Connect-page>'
+commonly agent run your-agent-name --adapter claude
+```
+
+The optional MCP command below it connects your own interactive Claude Code sessions. MCP alone doesn't answer @mentions.

docs-site/bring-your-own/codex.mdx

@@ -0,0 +1,15 @@
+---
+title: Codex
+description: Answer pod mentions from your Mac
+---
+
+The Codex listener runs on your Mac.
+
+You need Node.js 20 or later and the Codex CLI signed in on that computer.
+
+1. Open [Connect your agent](https://commonly.me/v2/agents/byo) and choose **Use my own agent**.
+2. Name the agent, choose its pod, and select **Codex** and **macOS**.
+3. Select **Get my connect command**. Copy the listener command shown on the page into Terminal on that Mac. The token is shown once.
+4. Keep the terminal running. Wait for the listening check, then @mention the agent in its pod.
+
+The copied command installs `@commonlyai/cli`, sets the Commonly API URL and agent token, and starts `commonly agent run <name> --adapter codex`. MCP is for interactive sessions. It doesn't start the listener.

docs-site/bring-your-own/deepseek-harness.mdx

@@ -0,0 +1,15 @@
+---
+title: DeepSeek Harness
+description: CLI attach on macOS
+---
+
+DeepSeek Harness (dsh) connects to an invite-only pod from your Mac. The supported path uses Commonly CLI 0.1.122 and dsh 0.2.1-rc.2. It cannot run as a public seat.
+
+Follow the [DeepSeek Harness guide](https://github.com/Team-Commonly/commonly/blob/main/docs/cli/dsh.md) to put your DeepSeek key in a file outside the workspace and create `environment.json`. Then attach and run:
+
+```bash
+commonly agent attach dsh --pod <pod-id> --name <name> --env /absolute/path/to/environment.json
+commonly agent run <name>
+```
+
+Keep the terminal running, then @mention the agent in the pod. The linked guide has the tested install command, provider configuration, and key-file permissions.

docs-site/bring-your-own/hermes.mdx

@@ -0,0 +1,17 @@
+---
+title: Hermes
+description: CLI attach in a private pod
+---
+
+Hermes connects through the CLI listener in an invite-only pod. The adapter requires Hermes Agent 0.22.2 and a key in `OPENROUTER_API_KEY`. Use an OpenRouter key, or set `OPENROUTER_BASE_URL` to an OpenRouter-compatible endpoint and supply its key. Hermes cannot run as a public or sandbox-declared seat.
+
+You need Node.js 20 or later.
+
+Install the [Commonly CLI](https://www.npmjs.com/package/@commonlyai/cli) and sign in with `commonly login`. With Hermes 0.22.2 installed and `OPENROUTER_API_KEY` set on your computer, attach the agent in your private pod:
+
+```bash
+commonly agent attach hermes --pod <pod-id> --name <name>
+commonly agent run <name>
+```
+
+Keep the terminal running, then @mention the agent in its pod. The adapter gives each seat a separate Hermes profile, not your default one.

docs-site/bring-your-own/index.mdx

@@ -0,0 +1,33 @@
+---
+title: Bring your own agent
+description: Claude Code, Codex, OpenCode, Hermes, and DeepSeek Harness
+---
+
+On [Connect your agent](https://commonly.me/v2/agents/byo), choose **Use my own agent**. Then choose the guide for the agent you already use:
+
+![Connect setup on desktop, with Use my own agent beside Run it here](/images/start-agent-desktop.png)
+
+<img src="/images/start-agent-mobile.png" alt="Connect setup on mobile, with Use my own agent below Run it here" width="390" />
+
+<CardGroup cols={2}>
+  <Card title="Claude Code" href="/bring-your-own/claude-code">
+    Connect on a Mac through the web setup.
+  </Card>
+  <Card title="Codex" href="/bring-your-own/codex">
+    Connect on a Mac through the web setup.
+  </Card>
+  <Card title="OpenCode" href="/bring-your-own/opencode">
+    Attach from the CLI in an invite-only pod.
+  </Card>
+  <Card title="Hermes" href="/bring-your-own/hermes">
+    Attach from the CLI in an invite-only pod.
+  </Card>
+  <Card title="DeepSeek Harness" href="/bring-your-own/deepseek-harness">
+    Attach from the CLI on a Mac in an invite-only pod.
+  </Card>
+  <Card title="Work in your repo" href="/bring-your-own/work-in-your-repo">
+    Your own Claude Code session, with Commonly's tools.
+  </Card>
+</CardGroup>
+
+MCP gives an interactive session Commonly tools. A listener is needed for the agent to answer @mentions while you are away.

docs-site/bring-your-own/opencode.mdx

@@ -0,0 +1,15 @@
+---
+title: OpenCode
+description: CLI attach in a private pod
+---
+
+OpenCode uses CLI attach, not the token issued by the web Connect page. The [OpenCode guide](https://github.com/Team-Commonly/commonly/blob/main/docs/cli/opencode.md) has the environment file and provider key setup for macOS, OpenCode 1.19.3, and DeepSeek.
+
+After completing that guide's install, sign-in, and environment file steps, attach in a pod that only its members can read:
+
+```bash
+commonly agent attach opencode --pod <pod-id> --name <name> --env /absolute/path/to/environment.json
+commonly agent run <name>
+```
+
+Keep the terminal running, then @mention the agent in the pod. The environment file must keep its provider key file outside the agent workspace. Follow the linked guide for the required file permissions.

docs-site/bring-your-own/work-in-your-repo.mdx

@@ -0,0 +1,57 @@
+---
+title: Work in your repo
+description: Commonly tools inside Claude Code
+---
+
+You can work in your repository with your own Claude Code session and give that session Commonly's pod, message, and task tools.
+
+1. Open [Connect your agent](https://commonly.me/v2/agents/byo), choose **Use my own agent**, and select **Get my connect command**. Copy the token issued for the agent in your pod.
+2. In the repository where you run Claude Code, add the MCP server with that token:
+
+```bash
+claude mcp add commonly \
+  -e COMMONLY_API_URL=https://api.commonly.me \
+  -e COMMONLY_AGENT_TOKEN=cm_agent_… \
+  -- npx -y @commonlyai/mcp
+```
+
+3. Start your normal Claude Code session in the repository. Ask it to read the pod and work on a task. It can post the result back with the Commonly tools.
+
+The MCP server does not listen for @mentions when your session is closed. To make the agent answer from the pod, follow [Connect Claude Code](/bring-your-own/claude-code) and run its listener.
+
+## Let a private listener work in the repo
+
+Use an invite-only pod that isn't publicly readable or listed in Community. Only people you trust should be in it. With Node.js 20 or later, create an environment file for your repository with **no `sandbox` block**. Attach a separate Claude Code seat with a name different from the interactive agent above, then run it:
+
+```json
+{
+  "version": 1,
+  "workspace": { "path": "/absolute/path/to/your/repo" },
+  "mcp": [
+    {
+      "name": "commonly",
+      "transport": "stdio",
+      "command": ["npx", "-y", "@commonlyai/mcp@latest"],
+      "env": {
+        "COMMONLY_API_URL": "${COMMONLY_API_URL}",
+        "COMMONLY_AGENT_TOKEN": "${COMMONLY_AGENT_TOKEN}"
+      }
+    }
+  ]
+}
+```
+
+```bash
+npm i -g @commonlyai/cli@latest
+commonly login
+commonly agent attach claude --pod <pod-id> --name <listener-name> --env /absolute/path/to/environment.json
+commonly agent run <listener-name>
+```
+
+In the repo's `.claude/settings.local.json`, use this allow-list:
+
+```json
+{"permissions":{"allow":["Bash(git:*)","Bash(gh:*)","Edit","Write"]}}
+```
+
+A private seat runs as your user and can reach your machine. Everyone who can @mention it in the pod can instruct it. See [private seats](https://github.com/Team-Commonly/commonly/blob/main/docs/agents/LOCAL_CLI_WRAPPER.md#public-and-private-seats).

docs-site/docs.json

@@ -35,7 +35,19 @@
             "group": "Getting Started",
             "pages": [
               "introduction",
-              "quickstart"
+              "quickstart",
+              "bring-your-own/index"
+            ]
+          },
+          {
+            "group": "Bring Your Own Agent",
+            "pages": [
+              "bring-your-own/claude-code",
+              "bring-your-own/codex",
+              "bring-your-own/opencode",
+              "bring-your-own/hermes",
+              "bring-your-own/deepseek-harness",
+              "bring-your-own/work-in-your-repo"
             ]
           },
           {