lilyshen0722 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026
diff --git a/docs-site/concepts/connectors.mdx b/docs-site/concepts/connectors.mdx
@@ -1,62 +1,31 @@
 ---
-title: Connectors and Grants
-description: Bring external services into a pod with explicit install and tool access.
+title: Connectors
+description: Channels and tools for your pods
 ---
 
-A connector brings an external service into Commonly. Its installable entry
-describes the capability; its installation chooses the target scope; its
-credentials and grants decide what can actually be used.
+Open **Connectors** in Commonly. Channels carry messages between a pod and an
+outside chat. Tools let an agent read or act in another service after the
+connection owner grants access.
 
-## Three records, three jobs
+This live Connectors page shows a free account before any connection or tool
+grant. Slack and Telegram are under **Channels**; GitHub and Linear are under
+**Tools**. Other tools visible in the list are outside the walked guides here.
 
-| Record | Job |
-|---|---|
-| Installable | Catalog metadata, components, required capabilities, and version. |
-| Credential | Secret material and credential lineage, kept separate from the connector record. |
-| Grant | Server-enforced permission connecting a caller, tool, connector, and audience. |
-
-Keeping these records separate means installing a connector does not silently
-grant every tool or expose the underlying secret to a pod.
-
-## Catalog and installation
-
-Authenticated users can inspect the connector catalog:
-
-~~~http
-GET /api/installables
-~~~
-
-An installation is created from the shell or the installable lifecycle route.
-The connector is then projected into its target scope, such as a user or pod.
-The exact lifecycle depends on the connector; use the app's install flow for
-OAuth-backed services.
-
-## Grants
+<div style={{maxHeight: "420px", overflow: "hidden"}}>
+  <img src="/images/connectors-desktop.png" alt="Desktop Connectors page before setup, with Slack and Telegram channels above the tools list" style={{width: "100%"}} />
+</div>
 
-Grants are explicit server records. The API exposes the pod's grants and
-individual grant details:
+<div style={{maxHeight: "650px", overflow: "hidden"}}>
+  <img src="/images/connectors-mobile.png" alt="Mobile Connectors page before setup, with Add on Slack and Telegram and Connect on Linear" style={{width: "100%", maxWidth: "390px"}} />
+</div>
 
-~~~http
-GET /api/pods/:podId/grants
-GET /api/grants/:grantId
-GET /api/grants/:grantId/calls
-~~~
-
-Connector tools should be called through the grant that authorized them. A
-grant can be revoked, and revocation cascades to the calls that depend on it.
-
-## Credentials
-
-Credential metadata is owner-scoped:
-
-~~~http
-GET    /api/credentials
-DELETE /api/credentials/:id
-~~~
-
-The API never uses a pod message as a credential store. Keep secret values in
-the deployment's secret manager and grant only the connector operations the
-target agent or pod needs.
-
-See [Marketplace](/marketplace/overview) for the installable catalog and
-[Agent Tools](/agents/tools) for the runtime-facing tool surface.
+| Connector | Current path |
+|---|---|
+| [Telegram](/integrations/telegram) | Bind a private chat and choose which pods reach it. |
+| [Slack](/integrations/slack) | Authorize a workspace, then confirm the connection. |
+| [GitHub App](/integrations/github) | An instance administrator installs the app; the connection owner grants tools. On commonly.me this is limited to the instance's own repository. |
+| [Linear](/integrations/linear) | Connect your account and grant read access to an eligible pod. |
+
+The page also lists connectors that are unavailable on this instance. A listed
+row is not a working connection. The [grants guide](/concepts/grants) explains
+how a connection owner limits tool access and revokes it.
diff --git a/docs-site/concepts/grants.mdx b/docs-site/concepts/grants.mdx
@@ -17,9 +17,10 @@ secret, and revoking it does not replace the credentials held by the connector.
 5. The broker checks the grant before each tool call and records the outcome.
 6. The connection owner can revoke a grant; revocation cascades to its children.
 
-The current root-grant route accepts connected GitHub App installations. The
-server derives the installation and broker from the connection, rather than
-trusting those values from the request body.
+The root-grant route accepts connected GitHub App installations and supported
+hosted MCP connections, including Linear. Linear grants are read-only and work
+only in eligible private pods. The server derives the installation and broker
+from the connection, rather than trusting those values from the request body.
 
 ## Targets and audience
 

diff --git a/docs-site/deployment/docker.mdx b/docs-site/deployment/docker.mdx
@@ -1,88 +1,26 @@
 ---
-title: Docker Compose (local)
-description: Run Commonly on one local machine with Docker Compose.
+title: Docker Compose
+description: Local operation and data retention
 ---
 
-This is the supported Docker Compose path for trying Commonly locally or on a
-private single machine. It is not a public-domain production deployment.
+Start with [Self-host Commonly](/deployment/index). The local Compose profile
+builds the frontend, backend, and MongoDB on one machine. It does not include
+TLS, a reverse proxy, public-domain configuration, or PostgreSQL.
 
-## Prerequisites
-
-- [Docker Engine](https://docs.docker.com/get-docker/) with the Compose v2 plugin
-- Git
-- Ports `3000` and `5000` free on the Docker host
-
-## Start Commonly
-
-```bash
-git clone https://github.com/Team-Commonly/commonly.git
-cd commonly
-./install.sh
-```
-
-The installer writes an ignored `.env` file containing a generated `JWT_SECRET`
-when one is missing, then builds and starts the services. Keep that file for
-future Compose commands: changing the secret invalidates existing sessions.
-
-Open **http://localhost:3000** and verify the backend:
+From the repository root, check the API after `./install.sh`:
 
 ```bash
 curl --fail --silent http://localhost:5000/api/health
 ```
 
-## What this profile includes
-
-| Service | Port | Notes |
-|---|---:|---|
-| frontend | 3000 | Static React app |
-| backend | 5000 | Node.js API |
-| mongo | internal only | Persistent `mongo-data` Docker volume |
-
-The profile deliberately does not include PostgreSQL, TLS, a reverse proxy, or
-public-domain configuration. PostgreSQL-specific features, including threaded
-agent messages, are not enabled. Do not expose these ports directly to the
-internet.
-
-## Operate and update
+The installer keeps configuration in an ignored `.env` file. Use that file
+when checking status or stopping the stack:
 
 ```bash
-# Status and logs
 docker compose --env-file .env -f docker-compose.local.yml ps
-docker compose --env-file .env -f docker-compose.local.yml logs -f
-
-# Stop containers and retain data
 docker compose --env-file .env -f docker-compose.local.yml down
-
-# Update the checkout and rebuild
-git pull --ff-only
-docker compose --env-file .env -f docker-compose.local.yml up -d --build
-```
-
-<Warning>
-`docker compose --env-file .env -f docker-compose.local.yml down -v` removes
-the MongoDB volume and its data. Use it only when you intend to reset the local
-installation.
-</Warning>
-
-## Configure a local install
-
-Add optional settings to the ignored root `.env` file, then restart the stack.
-For a shared private machine, you can restrict registration:
-
-```dotenv
-REGISTRATION_INVITE_ONLY=true
-REGISTRATION_INVITE_CODES=replace-with-private-codes
 ```
 
-Leave integration credentials unset unless you are using that integration, and
-never commit `.env`.
-
-## Development and public deployment
-
-Use `./dev.sh up` for contributor development with source mounts and hot reload.
-It is a different profile from the local install above.
-
-For a public deployment, configure TLS, ingress or a reverse proxy, a
-non-local frontend API URL, backups, and deployment-specific secrets. Start
-with the [Kubernetes / Helm guide](/deployment/kubernetes); do not promote the
-local Compose profile by exposing its ports.
+The `down` command keeps the MongoDB volume. Adding `-v` removes the volume
+and its data. For logs, updates, and optional settings, follow the
+[repository's local deployment guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/SELF_HOSTED.md).
diff --git a/docs-site/deployment/environment-variables.mdx b/docs-site/deployment/environment-variables.mdx
@@ -1,73 +1,15 @@
 ---
-title: Environment Variables
-description: Environment variables for local and self-hosted Commonly deployments.
+title: Environment variables
+description: Configuration sources for self-hosting
 ---
 
-Start from .env.example for the full template. The values below are the
-application variables most deployments need; provider and integration
-credentials are optional unless the related feature is enabled.
+The local installer creates an ignored `.env` with a generated `JWT_SECRET`
+when one is missing. Keep it private and keep the value stable so existing
+sessions continue to work.
 
-## Database
-
-| Variable | Description |
-|---|---|
-| MONGO_URI | MongoDB connection string. |
-| PG_HOST | PostgreSQL host for the message store. |
-| PG_PORT | PostgreSQL port; defaults to 5432. |
-| PG_DATABASE | PostgreSQL database name. |
-| PG_USER | PostgreSQL user. |
-| PG_PASSWORD | PostgreSQL password. |
-| PG_SSL_ENABLED | Enable PostgreSQL TLS. |
-| PG_SSL_CA_PATH | CA certificate path when PostgreSQL TLS requires one. |
-
-If PG_HOST is unset, the application falls back to MongoDB for the local
-development path. The Docker Compose services can use their internal service
-names instead of localhost.
-
-## Authentication and server
-
-| Variable | Description | Local example |
-|---|---|---|
-| JWT_SECRET | Secret used to sign human-session JWTs. Use a random value in production. | openssl rand -hex 32 |
-| PORT | Backend listen port. | 5000 |
-| NODE_ENV | Application environment. | development |
-| FRONTEND_URL | Browser origin allowed by the backend. | http://localhost:3000 |
-| BACKEND_URL | Backend origin used by local tooling. | http://localhost:5000 |
-
-Changing JWT_SECRET invalidates existing human sessions.
-
-## Model providers
-
-| Variable | Description |
-|---|---|
-| ANTHROPIC_API_KEY | Credentials for Claude API calls. |
-| OPENAI_API_KEY | Credentials for OpenAI-compatible calls. |
-| OPENAI_BASE_URL | Optional OpenAI-compatible API origin. |
-| OPENROUTER_API_KEY | Credentials for OpenRouter fallback routing. |
-| OPENROUTER_BASE_URL | Optional OpenRouter-compatible API origin. |
-| GEMINI_API_KEY | Credentials for backend services that use Gemini. |
-| LITELLM_API_KEY | Virtual key for a LiteLLM proxy. |
-| LITELLM_BASE_URL | LiteLLM proxy origin. |
-| LITELLM_MASTER_KEY | Operator key for LiteLLM administration. |
-
-Provider variables are only needed when the enabled runtime or feature uses
-that provider. GEMINI_API_KEY remains a supported backend input; it should not
-be treated as an API reference or as a replacement for the runtime token.
-
-## Agent and integration features
-
-| Variable | Description |
-|---|---|
-| BRAVE_API_KEY | Brave Search access for agents that use search. |
-| TAVILY_API_KEY | Tavily access for agents that use search. |
-| FIRECRAWL_API_KEY | Firecrawl access for agents that use crawling. |
-| DEEPGRAM_API_KEY | Speech or transcription provider credentials. |
-| GITHUB_PAT | GitHub access for configured development workflows. |
-| DISCORD_CLIENT_ID | Discord OAuth application ID. |
-| DISCORD_CLIENT_SECRET | Discord OAuth application secret. |
-| DISCORD_BOT_TOKEN | Discord bot credential. |
-| DISCORD_PUBLIC_KEY | Discord interaction signature key. |
-| TELEGRAM_BOT_TOKEN | Telegram bot token. |
-
-Never commit these values or put them in pod memory. Use deployment secrets for
-production and grant each feature only the credentials it needs.
+The local profile forwards only the variables listed in
+[`docker-compose.local.yml`](https://github.com/Team-Commonly/commonly/blob/main/docker-compose.local.yml).
+The repository's [`.env.example`](https://github.com/Team-Commonly/commonly/blob/main/.env.example)
+covers broader development and deployment settings; putting a variable in
+`.env` does not make the local Compose profile forward it. For connector setup,
+follow its guide and the [self-hosting guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/SELF_HOSTED.md).
diff --git a/docs-site/deployment/index.mdx b/docs-site/deployment/index.mdx
@@ -0,0 +1,35 @@
+---
+title: Self-host Commonly
+description: Local setup with Docker Compose
+---
+
+## Before you start
+
+You need Git, Docker Engine with the Compose v2 plugin, OpenSSL if the installer
+must create `.env`, and free ports `3000` and `5000`. Check Docker with
+`docker compose version`.
+
+## Start
+
+Run the same three steps shown on the Commonly home page:
+
+```bash
+git clone https://github.com/Team-Commonly/commonly.git
+cd commonly
+./install.sh
+```
+
+Open [http://localhost:3000](http://localhost:3000). The installer builds and
+starts the local frontend, backend, and MongoDB. It creates an ignored `.env`
+file with a generated `JWT_SECRET` if you do not already have one. Keep that
+file; changing the secret signs everyone out.
+
+This Compose setup is for one local or private machine. It has no TLS, reverse
+proxy, or public-domain configuration. Keep its ports off the public internet.
+
+For health checks, updates, and data retention, follow the
+[local deployment guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/SELF_HOSTED.md).
+For a public deployment, read the
+[Kubernetes guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/KUBERNETES.md)
+and [Helm values reference](https://github.com/Team-Commonly/commonly/blob/main/docs/self-hosting/helm-reference.md)
+before choosing an environment.