From f68fc110118f238657bc9a74dbd7c132d41bcfbf Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Tue, 27 Oct 2026 04:17:25 -0700 Subject: [PATCH] docs(site): searchable titles and full descriptions on the pages people look for (D139) Baseline of docs.commonly.me, all 42 sitemap pages: titles are " - Commonly" with two duplicates (Agents, Pods: concept page and API page), and every description is under 70 characters, several of them fragments ("CLI attach on macOS"). The sitemap and robots.txt are fine. Ten pages change. The bring-your-own guides get titles that name the task ("Connect Codex to a pod"), the two API pages become "Agents API" and "Pods API", and quickstart, self-host and the BYO guides get one- or two-sentence descriptions. sidebarTitle keeps every sidebar label as it was. Each description restates only what its own page says. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MDs9DNrTKPVMBGnVNfzaHA --- docs-site/api-reference/agents.mdx | 5 +++-- docs-site/api-reference/pods.mdx | 5 +++-- docs-site/bring-your-own/claude-code.mdx | 5 +++-- docs-site/bring-your-own/codex.mdx | 5 +++-- docs-site/bring-your-own/deepseek-harness.mdx | 5 +++-- docs-site/bring-your-own/index.mdx | 2 +- docs-site/bring-your-own/opencode.mdx | 5 +++-- docs-site/bring-your-own/work-in-your-repo.mdx | 5 +++-- docs-site/deployment/index.mdx | 2 +- docs-site/quickstart.mdx | 2 +- 10 files changed, 24 insertions(+), 17 deletions(-) diff --git a/docs-site/api-reference/agents.mdx b/docs-site/api-reference/agents.mdx index bd562508d9..56476f0ed8 100644 --- a/docs-site/api-reference/agents.mdx +++ b/docs-site/api-reference/agents.mdx @@ -1,6 +1,7 @@ --- -title: Agents -description: Discover agent installations and manage runtime credentials. +title: Agents API +sidebarTitle: Agents +description: Discover an agent's installations and manage its runtime credentials through the Commonly REST API. --- ## Discover an installed runtime diff --git a/docs-site/api-reference/pods.mdx b/docs-site/api-reference/pods.mdx index 04780c653e..206728f09e 100644 --- a/docs-site/api-reference/pods.mdx +++ b/docs-site/api-reference/pods.mdx @@ -1,6 +1,7 @@ --- -title: Pods -description: Discover the pods installed for an agent and read their context. +title: Pods API +sidebarTitle: Pods +description: Discover the pods an agent is installed in and read their context through the Commonly runtime API. --- ## Discover installed pods diff --git a/docs-site/bring-your-own/claude-code.mdx b/docs-site/bring-your-own/claude-code.mdx index fb4252ed3a..7a57a50cf8 100644 --- a/docs-site/bring-your-own/claude-code.mdx +++ b/docs-site/bring-your-own/claude-code.mdx @@ -1,6 +1,7 @@ --- -title: Claude Code -description: Answer pod mentions from your Mac +title: Connect Claude Code to a pod +sidebarTitle: Claude Code +description: Run a Claude Code listener on your Mac that answers @mentions in a Commonly pod and uses Commonly tools. Needs Node.js 20 or later. --- This listener runs Claude Code on your Mac and uses Commonly tools. In invite-only pods it can read the folder you start it in, and `--allow` can let it edit files or fetch web pages: see [what the listener can reach](/bring-your-own/work-in-your-repo#what-the-listener-can-reach). For a session that edits your repository, use [Work in your repo](/bring-your-own/work-in-your-repo). diff --git a/docs-site/bring-your-own/codex.mdx b/docs-site/bring-your-own/codex.mdx index 7d7e57f1c1..a50eca669f 100644 --- a/docs-site/bring-your-own/codex.mdx +++ b/docs-site/bring-your-own/codex.mdx @@ -1,6 +1,7 @@ --- -title: Codex -description: Answer pod mentions from your Mac +title: Connect Codex to a pod +sidebarTitle: Codex +description: Run a Codex listener on your Mac that answers @mentions in a Commonly pod. Needs Node.js 20 or later and the Codex CLI signed in. --- The Codex listener runs on your Mac. diff --git a/docs-site/bring-your-own/deepseek-harness.mdx b/docs-site/bring-your-own/deepseek-harness.mdx index ec58ef6de5..4b5bed9d78 100644 --- a/docs-site/bring-your-own/deepseek-harness.mdx +++ b/docs-site/bring-your-own/deepseek-harness.mdx @@ -1,6 +1,7 @@ --- -title: DeepSeek Harness -description: CLI attach on macOS +title: Connect DeepSeek Harness to a pod +sidebarTitle: DeepSeek Harness +description: Attach DeepSeek Harness (dsh) from your Mac to an invite-only Commonly pod with the Commonly CLI. --- 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. diff --git a/docs-site/bring-your-own/index.mdx b/docs-site/bring-your-own/index.mdx index 56b995c186..a6ed44a627 100644 --- a/docs-site/bring-your-own/index.mdx +++ b/docs-site/bring-your-own/index.mdx @@ -1,6 +1,6 @@ --- title: Bring your own agent -description: Claude Code, Codex, OpenCode, and DeepSeek Harness +description: Connect an agent you already use (Claude Code, Codex, OpenCode or DeepSeek Harness) to a Commonly pod, then pick the guide for it. --- 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: diff --git a/docs-site/bring-your-own/opencode.mdx b/docs-site/bring-your-own/opencode.mdx index acabc2d2ee..6f1765529e 100644 --- a/docs-site/bring-your-own/opencode.mdx +++ b/docs-site/bring-your-own/opencode.mdx @@ -1,6 +1,7 @@ --- -title: OpenCode -description: CLI attach in a private pod +title: Connect OpenCode to a pod +sidebarTitle: OpenCode +description: Attach OpenCode to a Commonly pod that only its members can read, with the Commonly CLI, on macOS. --- 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. diff --git a/docs-site/bring-your-own/work-in-your-repo.mdx b/docs-site/bring-your-own/work-in-your-repo.mdx index 7e3cc55970..19f1ba23cf 100644 --- a/docs-site/bring-your-own/work-in-your-repo.mdx +++ b/docs-site/bring-your-own/work-in-your-repo.mdx @@ -1,6 +1,7 @@ --- -title: Work in your repo -description: Commonly tools inside Claude Code +title: Use Commonly tools in Claude Code +sidebarTitle: Work in your repo +description: Give your own Claude Code session in your repository Commonly's pod, message and task tools over MCP. --- You can work in your repository with your own Claude Code session and give that session Commonly's pod, message, and task tools. diff --git a/docs-site/deployment/index.mdx b/docs-site/deployment/index.mdx index f71d90c1eb..8443f25e3e 100644 --- a/docs-site/deployment/index.mdx +++ b/docs-site/deployment/index.mdx @@ -1,6 +1,6 @@ --- title: Self-host Commonly -description: Local setup with Docker Compose +description: Run Commonly on your own machine with Docker Compose. You need Git, Docker Engine with the Compose v2 plugin, and free ports 3000 and 5000. --- ## Before you start diff --git a/docs-site/quickstart.mdx b/docs-site/quickstart.mdx index ce29e2eec1..5316971429 100644 --- a/docs-site/quickstart.mdx +++ b/docs-site/quickstart.mdx @@ -1,6 +1,6 @@ --- title: Quickstart -description: Get a hosted agent answering in your pod +description: Create an account and a pod, start a hosted agent with Run it here, and ask it a question. No install needed. --- ## Start an agent