docs(agent): document standalone LangBot CLI (#2571)

AGENTS.md

@@ -46,6 +46,7 @@ Run the narrowest useful test first, then broader checks when confidence is need
 - Dev environment guide: https://langbot.app/docs/zh/develop/dev-config.
 - Plugin runtime / CLI / SDK debugging: https://langbot.app/docs/zh/develop/plugin-runtime.
 - API-key auth: `docs/API_KEY_AUTH.md`.
+- Service API CLI: [`langbot-cli`](https://github.com/langbot-app/langbot-cli) (`lbctl`) manages running Workspaces; it is separate from the SDK's `lbp` CLI.
 - Box deep-dive notes: `docs/review/box-architecture.md` and related files.
 - In-repo skills: `skills/` is the single source of truth for LangBot agent skills.
 - SDK repo: `../langbot-plugin-sdk/` when changing shared entities, plugin APIs, action protocol, `lbp rt`, or `lbp box`.
@@ -83,6 +84,7 @@ Config keys to verify in `data/config.yaml` / `src/langbot/templates/config.yaml
 ## Change Rules
 
 - HTTP API changes that should be agent-accessible must update the matching MCP tool in `src/langbot/pkg/api/mcp/server.py` and the relevant skill under `skills/` in the same pass.
+- When changing Service API routes or capabilities used by `lbctl`, check compatibility with the separate `langbot-cli` repository.
 - New schema changes use Alembic under `src/langbot/pkg/persistence/alembic/versions/`. LangBot 4.x does not support upgrading 3.x databases.
 - New platform behavior belongs in platform adapters only for platform translation; pipeline/business logic belongs in `pkg/pipeline/` or services.
 - User-facing strings must support i18n (`en_US`, `zh_Hans`; include `ja_JP` where the repo already does).

ARCHITECTURE.md

@@ -23,6 +23,7 @@ LangBot is not a single-repo system.
 
 - `LangBot/` is the main product: backend, web UI, platform adapters, pipeline engine, HTTP API, MCP server, RAG, persistence, skills integration, and the bridge code that talks to runtimes.
 - `langbot-plugin-sdk/` is published as `langbot-plugin` and pinned in `LangBot/pyproject.toml`. It contains plugin developer APIs, shared entities, `lbp`, the Plugin Runtime (`lbp rt`), and the Box Runtime (`lbp box`).
+- [`langbot-cli`](https://github.com/langbot-app/langbot-cli) is a separately released `lbctl` client for managing a running Workspace through the HTTP Service API; it is not part of the LangBot server or the SDK's `lbp` CLI.
 - Plugins import SDK APIs from `langbot_plugin.*`; the LangBot main process imports the same package for shared entities and runtime protocols.
 
 This split matters. If a change modifies SDK entities, component APIs, action protocols, `lbp rt`, or `lbp box`, verify the sibling SDK repo and install the local SDK into LangBot's virtualenv when testing cross-repo behavior.
@@ -252,6 +253,7 @@ LangBot is deliberately agent-friendly. The agent-facing surfaces are part of th
 
 - `skills/` is the single source of truth for in-repo skills.
 - `pkg/api/mcp/server.py` exposes the LangBot MCP server at `/mcp`.
+- `lbctl` calls the authenticated HTTP Service API from a terminal; its source and releases live in `langbot-cli`.
 - `api.global_api_key` authenticates API/MCP access without a browser login.
 - `AGENTS.md` and `ARCHITECTURE.md` tell coding agents how the repo works.
 

README.md

@@ -164,6 +164,7 @@ docker compose --profile all up -d
 LangBot is **agent-friendly by design** — your coding agents (Claude Code, Codex, Copilot, Cursor, …) can operate, extend, and deploy LangBot with first-class support:
 
 - **MCP Server** — LangBot exposes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) endpoint at `/mcp`, mirroring the HTTP API so an agent can manage bots, pipelines, plugins, and models programmatically. Authenticate with the same API key (set a global key in `config.yaml` or use a per-user key) — no login flow required. Configure it in the Web panel's **API & MCP** tab.
+- **CLI (`lbctl`)** — The standalone [LangBot CLI](https://github.com/langbot-app/langbot-cli) lets agents manage a running LangBot Workspace from a terminal through the Service API. It uses an API key and supports bots, pipelines, knowledge bases, models, plugins, skills, and MCP servers. See the CLI repository for installation and commands.
 - **In-repo Skills** — The [`skills/`](skills/) directory is the **single source of truth** for working with LangBot: plugin development, core development, end-to-end testing, deployment, and operating the LangBot / LangBot Space MCP servers. Point your agent at this directory and it knows how to build.
 - **AGENTS.md** — Every repo ships an [`AGENTS.md`](AGENTS.md) (symlinked to `CLAUDE.md`) describing architecture, conventions, and the rule that API changes must keep the MCP server and skills in sync.
 - **`llms.txt`** — Machine-readable project context for LLMs is published on the website.

README_CN.md

@@ -180,6 +180,7 @@ docker compose --profile all up -d
 LangBot **从设计上就对 Agent 友好** —— 你的编码 Agent（Claude Code、Codex、Copilot、Cursor 等）可以一等公民般地操作、扩展和部署 LangBot：
 
 - **MCP Server** —— LangBot 内置 [Model Context Protocol](https://modelcontextprotocol.io/) 端点 `/mcp`，与 HTTP API 对齐，Agent 可编程式管理机器人、流水线、插件和模型。使用同一套 API Key 鉴权（可在 `config.yaml` 配置全局 Key，或使用用户 Key），无需登录流程。在 Web 面板的 **API 与 MCP** 标签页中配置。
+- **CLI（`lbctl`）** —— 独立的 [LangBot CLI](https://github.com/langbot-app/langbot-cli) 让 Agent 在终端通过 Service API 管理已运行实例中的 Workspace。它使用 API Key，支持管理机器人、流水线、知识库、模型、插件、Skill 和 MCP Server。安装方法和命令以 CLI 仓库为准。
 - **仓库内 Skills** —— [`skills/`](skills/) 目录是使用 LangBot 的**唯一事实来源**：插件开发、核心开发、端到端测试、部署，以及操作 LangBot / LangBot Space MCP Server。把 Agent 指向这个目录，它就知道如何动手。
 - **AGENTS.md** —— 每个仓库都提供 [`AGENTS.md`](AGENTS.md)（软链到 `CLAUDE.md`），描述架构、规范，以及「API 变更必须同步更新 MCP Server 和 skills」的约定。
 - **`llms.txt`** —— 面向 LLM 的机器可读项目上下文已发布在官网。

docs/API_KEY_AUTH.md

@@ -55,6 +55,11 @@ Behavior:
 
 ## Using API Keys
 
+The standalone [`lbctl` CLI](https://github.com/langbot-app/langbot-cli) uses
+these API keys to manage a running LangBot Workspace through the Service API.
+It can check the key's Workspace identity and server capabilities before
+managing resources. See the CLI repository for installation and commands.
+
 ### Authentication Headers
 
 Include your API key in the request header using one of these methods:

skills/skills/langbot-dev/SKILL.md

@@ -94,7 +94,9 @@ discovered by `importutil.import_modules_in_pkg`.
 3. **If the endpoint should be agent-accessible, add/adjust the matching MCP tool
    in `pkg/api/mcp/server.py` and update the `langbot-mcp-ops` skill.** API and
    MCP surface must stay aligned (see `AGENTS.md`).
-4. Update `docs/service-api-openapi.json` if you maintain the OpenAPI overview.
+4. If `lbctl` uses the route or capability, check the separate
+   [`langbot-cli`](https://github.com/langbot-app/langbot-cli) client for compatibility.
+5. Update `docs/service-api-openapi.json` if you maintain the OpenAPI overview.
 
 ## Database migrations (Alembic)
 
@@ -127,3 +129,4 @@ uv run python tests/manual/mcp_smoke.py    # MCP server e2e smoke
 - `langbot-testing` — WebUI/e2e QA harness (`bin/lbs`).
 - `langbot-deploy` — Docker/compose deployment + config.
 - `langbot-mcp-ops` — operating the LangBot MCP server.
+- [`langbot-cli`](https://github.com/langbot-app/langbot-cli) — `lbctl`, a standalone Service API client for managing running Workspaces.