ChatCRS 0.2.2__tar.gz → 0.2.4__tar.gz

chatcrs-0.2.4/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev,docs]"
+      - run: python -m pytest -q
+      - run: python -m mkdocs build --strict
+      - run: python -m build

chatcrs-0.2.4/.github/workflows/deploy-docs.yml

@@ -0,0 +1,31 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[docs]"
+      - name: Build strict docs
+        run: python -m mkdocs build --strict
+      - name: Deploy stable docs
+        run: python -m mkdocs gh-deploy --force

chatcrs-0.2.4/.github/workflows/preview-docs.yml

@@ -0,0 +1,64 @@
+name: Preview Docs
+
+on:
+  pull_request:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: ${{ !github.event.pull_request.head.repo.fork }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[docs]"
+      - name: Build strict docs
+        run: python -m mkdocs build --strict
+      - name: Deploy preview docs
+        run: |
+          git fetch origin gh-pages || true
+          mike deploy dev -p --allow-empty
+          site_url=$(python - <<'PY'
+          from pathlib import Path
+          for line in Path("mkdocs.yml").read_text(encoding="utf-8").splitlines():
+              if line.startswith("site_url:"):
+                  print(line.split(":", 1)[1].strip().rstrip("/"))
+                  break
+          else:
+              raise SystemExit("mkdocs.yml is missing site_url")
+          PY
+          )
+          preview_url="${site_url}/dev/"
+          echo "CHATCRS_PREVIEW_URL=${preview_url}" >> "$GITHUB_ENV"
+          echo "Preview URL: ${preview_url}" >> "$GITHUB_STEP_SUMMARY"
+      - name: Comment PR with preview link
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const marker = '<!-- chatcrs-docs-preview -->';
+            const previewLink = process.env.CHATCRS_PREVIEW_URL;
+            const body = `${marker}\nPreview Docs: ${previewLink}`;
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.pull_request.number;
+            const comments = await github.rest.issues.listComments({ owner, repo, issue_number, per_page: 100 });
+            const existing = comments.data.find(comment => comment.body && comment.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+            } else {
+              await github.rest.issues.createComment({ owner, repo, issue_number, body });
+            }

chatcrs-0.2.4/.github/workflows/publish.yml

@@ -0,0 +1,97 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Resolve package version
+        id: meta
+        run: |
+          python - <<'PY'
+          import ast
+          import os
+          from pathlib import Path
+
+          module = ast.parse(Path("src/chatcrs/__init__.py").read_text(encoding="utf-8"))
+          for stmt in module.body:
+              if not isinstance(stmt, ast.Assign):
+                  continue
+              if any(isinstance(target, ast.Name) and target.id == "__version__" for target in stmt.targets):
+                  version = ast.literal_eval(stmt.value)
+                  break
+          else:
+              raise SystemExit("__version__ not found in src/chatcrs/__init__.py")
+
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output:
+              print(f"version={version}", file=output)
+              print(f"tag=v{version}", file=output)
+          PY
+      - name: Check release ref matches package version
+        env:
+          RELEASE_TAG: ${{ steps.meta.outputs.tag }}
+        run: |
+          if [ "${GITHUB_REF_TYPE}" != "tag" ]; then
+            echo "Release workflow must run from tag ${RELEASE_TAG}; got ${GITHUB_REF_TYPE}:${GITHUB_REF_NAME}."
+            exit 1
+          fi
+          if [ "${GITHUB_REF_NAME}" != "${RELEASE_TAG}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match package version ${RELEASE_TAG}."
+            exit 1
+          fi
+      - name: Check PyPI version
+        id: pypi
+        env:
+          PACKAGE_NAME: "ChatCRS"
+          PACKAGE_VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          python - <<'PY'
+          import os
+          import urllib.error
+          import urllib.parse
+          import urllib.request
+
+          package = os.environ["PACKAGE_NAME"]
+          version = os.environ["PACKAGE_VERSION"]
+          url = f"https://pypi.org/pypi/{urllib.parse.quote(package)}/{urllib.parse.quote(version)}/json"
+          exists = "false"
+          try:
+              urllib.request.urlopen(url, timeout=10)
+          except urllib.error.HTTPError as exc:
+              if exc.code != 404:
+                  raise
+          else:
+              exists = "true"
+
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output:
+              print(f"exists={exists}", file=output)
+          PY
+      - name: Stop when version is already on PyPI
+        if: steps.pypi.outputs.exists == 'true'
+        run: echo "ChatCRS ${{ steps.meta.outputs.version }} is already on PyPI; skipping publish."
+      - name: Build distribution
+        if: steps.pypi.outputs.exists == 'false'
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Publish to PyPI
+        if: steps.pypi.outputs.exists == 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1

{chatcrs-0.2.2 → chatcrs-0.2.4}/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 2026-08-11 - 0.2.4
+
+### Added
+
+- Add a runtime CRS Admin session token store under `~/.chatarch/tokens/CRS/<profile>.json`, parallel to `envs/CRS/<profile>.env`.
+- Add `chatcrs admin token status`, `chatcrs admin token refresh`, and `chatcrs admin token clear` commands with redacted JSON output and dry-run deletion by default.
+- Add `chatcrs admin login --save-token` for explicitly saving a fresh login-derived Admin session token.
+
+### Changed
+
+- Admin HTTP requests now prefer the runtime token file over legacy `CRS_ACCESS_TOKEN`, fall back to username/password login when needed, and retry once after a 401 by refreshing the token file.
+- Document Env-vs-token state separation so stable CRS configuration stays in ChatEnv while short-lived Admin session tokens live in the token store.
+
+## 2026-08-10 - 0.2.3
+
+### Added
+
+- Add runtime-generated `chatcrs --tree` support backed by the registered Click command tree.
+- Cover `--help`, `--tree`, representative command groups, and template `hello` absence in CLI tests.
+
+### Changed
+
+- Rework the MkDocs navigation into top-level documentation sections and make the homepage a card-based hub for management, configuration, operations, and development entry points.
+- Sync README and bilingual CLI docs with the runtime `chatcrs --tree` output.
+- Tighten ChatArch internal dependency windows for the 0.2.3 patch release.
+
 ## 2026-08-06 - 0.2.2
 
 ### Changed
@@ -9,9 +35,8 @@
 - Replace the host-bound remote service lifecycle wrapper with local-only
   `chatcrs service ...` commands that run on the CRS server itself and never use
   remote execution transport.
-- Keep one canonical CRS ChatEnv namespace under `~/.chatarch/envs/CRS/` with
-  `CRS_API_BASE`, `CRS_API_KEY`, `CRS_USERNAME`, `CRS_PASSWORD`, and
-  `CRS_ACCESS_TOKEN`.
+- Keep one canonical CRS ChatEnv namespace for the HTTP base URL, caller API key,
+  admin identity, admin password, and admin bearer/session token categories.
 - Document `service` as a server-local lifecycle/install/update/status surface,
   while keeping verify/image/debug/Nginx/cutover task surfaces removed.
 - Add a CLI-to-HTTP/local interface map that ties every registered CLI leaf to its

{chatcrs-0.2.2 → chatcrs-0.2.4}/MANIFEST.in

@@ -1,4 +1,6 @@
+include README.md
 include CHANGELOG.md
 include README.en.md
 include mkdocs.yml
 recursive-include docs *.md
+recursive-include .github/workflows *.yml

chatcrs-0.2.4/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: ChatCRS
+Version: 0.2.4
+Summary: HTTP/API-first CRS management helpers for ChatArch.
+Author-email: ChatArch <1073853456@qq.com>
+License-Expression: MIT
+Project-URL: Homepage, https://arch.gh.wzhecnu.cn/ChatCRS/
+Project-URL: Documentation, https://arch.gh.wzhecnu.cn/ChatCRS/
+Project-URL: Repository, https://github.com/ChatArch/ChatCRS
+Keywords: chatcrs,chatarch,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9.0,>=8.1
+Requires-Dist: chatstyle<0.2.0,>=0.1.1
+Requires-Dist: chatenv<0.3.0,>=0.2.3
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2.0,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material<10.0,>=9.5; extra == "docs"
+Requires-Dist: mkdocs-static-i18n<2.0,>=1.2; extra == "docs"
+Requires-Dist: mike<3.0,>=2.0; extra == "docs"
+Dynamic: license-file
+
+<div align="center">
+    <a href="https://pypi.python.org/pypi/ChatCRS">
+        <img src="https://img.shields.io/pypi/v/ChatCRS.svg" alt="PyPI version" />
+    </a>
+    <a href="https://github.com/ChatArch/ChatCRS/actions/workflows/ci.yml">
+        <img src="https://github.com/ChatArch/ChatCRS/actions/workflows/ci.yml/badge.svg" alt="Tests" />
+    </a>
+</div>
+
+<div align="center">
+
+[English](README.en.md) | [简体中文](README.md)
+</div>
+
+# ChatCRS
+
+ChatCRS 是 ChatArch 的 CRS 管理 CLI。外部管理面优先使用 CRS HTTP/Admin API；`service` 域是 server-local surface，只在 CRS 服务器本机 shell 里操作本机 CRS checkout / Node runtime / `crs` executable。
+
+Images 验收、debug runtime、Nginx/edge、release/cutover 等花哨/任务型能力不作为当前包内命令暴露；这些属于代理站维护、专项验收或运维 runbook，后续需要时单独设计。
+
+## 安装与开发
+
+```bash
+python -m pip install -e '.[dev,docs]'
+chatcrs --help
+chatcrs --version
+python -m pytest -q
+python -m mkdocs build --strict
+python -m build
+```
+
+完整文档使用 MkDocs，本地预览：
+
+```bash
+python -m mkdocs serve
+```
+
+线上文档：https://arch.gh.wzhecnu.cn/ChatCRS/
+
+## CLI 树
+
+```text
+chatcrs  # CRS HTTP/API helpers plus server-local service commands for ChatArch.
+├── --help  # Show this help message.
+├── --version  # Show the installed package version.
+├── --tree  # Print the registered command tree.
+├── health [--base-url <BASE-URL>] [--json-output]  # Verify the CRS /health endpoint.
+├── admin  # Remote CRS administrator operations via HTTPS Admin API.
+│   ├── login [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--username <USERNAME>] [--password <PASSWORD>] [--admin-token <ADMIN-TOKEN>] [--timeout <TIMEOUT>] [--json-output]  # Verify CRS admin login without printing the session token.
+│   ├── accounts  # Inspect or refresh remote CRS account state via HTTP Admin API.
+│   │   ├── usage [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--username <USERNAME>] [--password <PASSWORD>] [--admin-token <ADMIN-TOKEN>] [--timeout <TIMEOUT>] [--json-output]  # List OpenAI/Codex account usage and scheduling metadata.
+│   │   └── refresh-status <ACCOUNT-ID> [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--username <USERNAME>] [--password <PASSWORD>] [--admin-token <ADMIN-TOKEN>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Reset a CRS OpenAI account status after transient failures.
+│   └── keys  # Inspect remote CRS API keys with admin privileges.
+│       ├── list [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--username <USERNAME>] [--password <PASSWORD>] [--admin-token <ADMIN-TOKEN>] [--timeout <TIMEOUT>] [--include-stats] [--time-range <TIME-RANGE>] [--json-output]  # List CRS API key metadata, optionally including usage stats.
+│       └── show <KEY-ID> [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--username <USERNAME>] [--password <PASSWORD>] [--admin-token <ADMIN-TOKEN>] [--timeout <TIMEOUT>] [--include-stats/--no-include-stats] [--time-range <TIME-RANGE>] [--json-output]  # Show one CRS API key by id or name.
+├── key  # CRS API-key-only operations that do not require admin login.
+│   └── info [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--timeout <TIMEOUT>] [--path <INFO-PATH>] [--json-output]  # Query CRS key-info using only a CRS API key.
+└── service  # Local CRS service lifecycle commands for the current server.
+    ├── install [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs install` on this server.
+    ├── update [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs update` on this server.
+    ├── start [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs start` on this server.
+    ├── stop [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs stop` on this server.
+    ├── restart [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs restart` on this server.
+    ├── status [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--json-output]  # Execute local `crs status` on this server.
+    ├── switch-branch <BRANCH> [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs switch-branch <branch>` on this server.
+    └── update-pricing [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs update-pricing` on this server.
+```
+
+运行 `chatcrs --tree` 可从实际 Click 注册表回读同一棵命令树。
+
+
+## HTTP/Admin 与 API key
+
+```bash
+chatcrs health --base-url https://crs.example.com --json-output
+chatcrs admin login --profile admin --json-output
+chatcrs admin accounts usage --profile admin --json-output
+chatcrs admin accounts refresh-status <account_id> --profile admin --json-output
+chatcrs admin accounts refresh-status <account_id> --profile admin --execute --json-output
+chatcrs admin keys list --profile admin --include-stats --json-output
+chatcrs admin keys show <key_id_or_name> --profile admin --json-output
+chatcrs key info --profile admin --json-output
+```
+
+## Server-local service
+
+这些命令应安装在目标 CRS 服务器上，并在该服务器本机执行：
+
+```bash
+chatcrs service status --app-dir /path/to/crs --json-output
+chatcrs service update --app-dir /path/to/crs --json-output
+chatcrs service update --app-dir /path/to/crs --execute --json-output
+chatcrs service restart --app-dir /path/to/crs --execute --json-output
+```
+
+`status` 默认执行本机只读 `crs status`。其它 service mutation 默认 dry-run，需要 `--execute` 才执行。
+
+## 配置
+
+ChatCRS 使用一套 CRS ChatEnv profile；默认 profile 是 `admin`，也可以用 `--profile` 指定其它 profile。公开文档只描述字段类别，不写具体 secret 文件路径或 secret-bearing env key 名。
+
+Canonical 字段类别：
+
+```text
+HTTP base URL
+caller API key
+admin username
+admin password
+admin bearer/session token
+```
+
+Service-local 目标不进入第二套 ChatEnv namespace；用当前工作目录或 `--app-dir` / `--crs-command` 指定本机 checkout 和 executable。
+
+敏感字段只应存在于 ChatEnv 或进程环境中，不进入命令行参数、文档、PR body 或日志输出。Profile 文件应使用 `0600` 权限。
+
+## 生产安全
+
+外部管理只能使用 HTTP/Admin API；没有 HTTP lifecycle 接口时，不用远端执行补洞。要么新增 CRS API/host-agent，要么在目标服务器本机运行 `chatcrs service ...`。
+
+更多内容见：
+
+- `docs/cli.md`
+- `docs/interfaces.md`
+- `docs/configuration.md`
+- `docs/production-maintenance.md`

chatcrs-0.2.4/README.en.md

@@ -0,0 +1,125 @@
+<div align="center">
+    <a href="https://pypi.python.org/pypi/ChatCRS">
+        <img src="https://img.shields.io/pypi/v/ChatCRS.svg" alt="PyPI version" />
+    </a>
+    <a href="https://github.com/ChatArch/ChatCRS/actions/workflows/ci.yml">
+        <img src="https://github.com/ChatArch/ChatCRS/actions/workflows/ci.yml/badge.svg" alt="Tests" />
+    </a>
+</div>
+
+<div align="center">
+
+[English](README.en.md) | [简体中文](README.md)
+</div>
+
+# ChatCRS
+
+ChatCRS is ChatArch's CRS management CLI. Outside-server management is HTTP/Admin API-first. The `service` namespace is a server-local surface: it runs only inside the CRS server shell and operates on that server's CRS checkout / Node runtime / `crs` executable.
+
+Image acceptance, debug runtimes, Nginx/edge work, release/cutover workflows, and similar task-specific surfaces are not package commands today. They belong to proxy-site maintenance, special acceptance, or operations runbooks and should be designed separately when scoped.
+
+## Install and develop
+
+```bash
+python -m pip install -e '.[dev,docs]'
+chatcrs --help
+chatcrs --version
+python -m pytest -q
+python -m mkdocs build --strict
+python -m build
+```
+
+Serve the complete MkDocs site with:
+
+```bash
+python -m mkdocs serve
+```
+
+Documentation: https://arch.gh.wzhecnu.cn/ChatCRS/
+
+## CLI tree
+
+```text
+chatcrs  # CRS HTTP/API helpers plus server-local service commands for ChatArch.
+├── --help  # Show this help message.
+├── --version  # Show the installed package version.
+├── --tree  # Print the registered command tree.
+├── health [--base-url <BASE-URL>] [--json-output]  # Verify the CRS /health endpoint.
+├── admin  # Remote CRS administrator operations via HTTPS Admin API.
+│   ├── login [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--username <USERNAME>] [--password <PASSWORD>] [--admin-token <ADMIN-TOKEN>] [--timeout <TIMEOUT>] [--json-output]  # Verify CRS admin login without printing the session token.
+│   ├── accounts  # Inspect or refresh remote CRS account state via HTTP Admin API.
+│   │   ├── usage [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--username <USERNAME>] [--password <PASSWORD>] [--admin-token <ADMIN-TOKEN>] [--timeout <TIMEOUT>] [--json-output]  # List OpenAI/Codex account usage and scheduling metadata.
+│   │   └── refresh-status <ACCOUNT-ID> [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--username <USERNAME>] [--password <PASSWORD>] [--admin-token <ADMIN-TOKEN>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Reset a CRS OpenAI account status after transient failures.
+│   └── keys  # Inspect remote CRS API keys with admin privileges.
+│       ├── list [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--username <USERNAME>] [--password <PASSWORD>] [--admin-token <ADMIN-TOKEN>] [--timeout <TIMEOUT>] [--include-stats] [--time-range <TIME-RANGE>] [--json-output]  # List CRS API key metadata, optionally including usage stats.
+│       └── show <KEY-ID> [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--username <USERNAME>] [--password <PASSWORD>] [--admin-token <ADMIN-TOKEN>] [--timeout <TIMEOUT>] [--include-stats/--no-include-stats] [--time-range <TIME-RANGE>] [--json-output]  # Show one CRS API key by id or name.
+├── key  # CRS API-key-only operations that do not require admin login.
+│   └── info [--profile <PROFILE>] [--base-url <BASE-URL>] [--api-key <API-KEY>] [--timeout <TIMEOUT>] [--path <INFO-PATH>] [--json-output]  # Query CRS key-info using only a CRS API key.
+└── service  # Local CRS service lifecycle commands for the current server.
+    ├── install [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs install` on this server.
+    ├── update [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs update` on this server.
+    ├── start [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs start` on this server.
+    ├── stop [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs stop` on this server.
+    ├── restart [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs restart` on this server.
+    ├── status [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--json-output]  # Execute local `crs status` on this server.
+    ├── switch-branch <BRANCH> [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs switch-branch <branch>` on this server.
+    └── update-pricing [--app-dir <APP-DIR>] [--crs-command <CRS-COMMAND>] [--timeout <TIMEOUT>] [--execute] [--json-output]  # Plan or execute local `crs update-pricing` on this server.
+```
+
+Run `chatcrs --tree` to read back the same command tree from the live Click registry.
+
+
+## HTTP/Admin and API key
+
+```bash
+chatcrs health --base-url https://crs.example.com --json-output
+chatcrs admin login --profile admin --json-output
+chatcrs admin accounts usage --profile admin --json-output
+chatcrs admin accounts refresh-status <account_id> --profile admin --json-output
+chatcrs admin accounts refresh-status <account_id> --profile admin --execute --json-output
+chatcrs admin keys list --profile admin --include-stats --json-output
+chatcrs admin keys show <key_id_or_name> --profile admin --json-output
+chatcrs key info --profile admin --json-output
+```
+
+## Server-local service
+
+These commands should be installed on and executed from the target CRS server itself:
+
+```bash
+chatcrs service status --app-dir /path/to/crs --json-output
+chatcrs service update --app-dir /path/to/crs --json-output
+chatcrs service update --app-dir /path/to/crs --execute --json-output
+chatcrs service restart --app-dir /path/to/crs --execute --json-output
+```
+
+`status` runs local read-only `crs status` by default. Other service mutations are dry-run by default and require `--execute`.
+
+## Configuration
+
+ChatCRS uses one CRS ChatEnv profile namespace. The default profile is `admin`; use `--profile` for another profile. Public docs describe field categories only and intentionally omit concrete secret-file paths or secret-bearing env key names.
+
+Canonical field categories:
+
+```text
+HTTP base URL
+caller API key
+admin username
+admin password
+admin bearer/session token
+```
+
+Service-local targets do not create a second ChatEnv namespace; use the current working directory or `--app-dir` / `--crs-command` for the local checkout and executable.
+
+Sensitive fields should live only in ChatEnv or the process environment, never in command arguments, documentation, PR bodies, or logs. Profile files should use `0600` permissions.
+
+## Production safety
+
+Outside-server management must use HTTP/Admin API. If no HTTP lifecycle endpoint exists, do not fill the gap with remote execution. Add a CRS API/host-agent, or run `chatcrs service ...` on the target server itself.
+
+See:
+
+- `docs/cli.md`
+- `docs/interfaces.md`
+- `docs/configuration.md`
+- `docs/production-maintenance.md`