@margay/ccl-core 1.4.0-beta.0 → 1.4.5-rc.0

package/docs/gateway-quickstart.md

@@ -0,0 +1,122 @@
+# CCL Gateway Quick Start
+
+This is the current gateway setup guide for Margay CCL.
+
+Use a Margay gateway when you want CCL to run gateway-managed models such as
+DeepSeek, Kimi, GLM, or organization-provided Claude/OpenAI-compatible models.
+
+## 1. Install CCL
+
+```bash
+npm install -g @margay/ccl-core
+ccl --version
+# 1.3.1 (CCL)
+```
+
+From a source checkout:
+
+```bash
+npm install
+npm run build
+node dist/cli.js --version
+```
+
+## 2. Register
+
+Use this when you have an invite code but no existing gateway token.
+
+```text
+ccl
+/gateway register <GATEWAY_URL> <INVITE_CODE> [username] [email] [phone]
+```
+
+Registration accepts the returned Gateway JWT only after same-origin
+`/auth/me` validation, saves typed issuer-bound state to
+`~/.ccl/gateway.json`, and updates the current CCL process. A legacy `api_key`
+field is not accepted because an upstream provider key must never be mistaken
+for a Gateway credential.
+
+## 3. Login Or Switch Gateway
+
+Use this when you already have a gateway token, or when you need to switch the
+current gateway.
+
+```text
+ccl
+/gateway login <GATEWAY_URL> <GATEWAY_TOKEN>
+/gateway doctor
+/gateway status
+```
+
+`/gateway login` validates the endpoint before it writes local state and marks
+the result as a verified Gateway credential. If validation fails, it leaves the
+previous working config intact. Never supply a DeepSeek, Kimi, Alibaba, xAI, or
+other upstream provider API key here.
+
+## 4. Understand Config Precedence
+
+CCL reads *admitted* gateway config in this order:
+
+1. A complete environment tuple: `CCL_GATEWAY_URL`, `CCL_GATEWAY_KEY`,
+   `CCL_GATEWAY_CREDENTIAL_TYPE`, and `CCL_GATEWAY_ISSUER`.
+2. Typed `~/.ccl/gateway.json` state written by `/gateway login` or
+   `/gateway register`.
+3. A legacy untyped config only when its credential has the structural form of
+   a compact JWT; it is admitted in memory without rewriting the file.
+
+Untyped opaque values and issuer mismatches are quarantined before any network
+request. If `/gateway doctor` reports a mismatch or quarantine, clear the full
+environment tuple and log in again:
+
+```bash
+unset CCL_GATEWAY_URL CCL_GATEWAY_KEY CCL_GATEWAY_CREDENTIAL_TYPE CCL_GATEWAY_ISSUER
+```
+
+or open a new terminal / reload your shell rc file.
+
+## 5. Use Gateway Models
+
+```bash
+ccl --model deepseek-v4-pro
+ccl --model kimi-for-coding
+ccl -p "summarize this repository" --model deepseek-v4-pro
+```
+
+Inside CCL:
+
+```text
+/model
+/priority cost
+/priority quality
+/effort high
+/endpoint
+```
+
+The actual model list is defined by the connected gateway. Use `/model` in the
+TUI or the gateway's model-list API if your deployment exposes one.
+
+## 6. Troubleshooting
+
+| Symptom | Action |
+|---|---|
+| Login fails | Check `<GATEWAY_URL>`, `<GATEWAY_TOKEN>`, network access, and token validity |
+| Gateway credential quarantined | Clear all four `CCL_GATEWAY_*` variables, then use `/gateway login` or `/gateway register` |
+| A new shell still uses the old gateway | Clear or update the complete exported Gateway tuple |
+| Gateway is reachable but model fails | Check `/model`, `/endpoint`, and the gateway model list |
+| CCL uses Claude direct instead of gateway | Confirm `CCL_GATEWAY_URL` and `CCL_GATEWAY_KEY` are present in the CCL process |
+| Debug needed | Start with `ccl --debug --verbose` or write logs with `--debug-file <path>` |
+
+## 7. Admin Notes
+
+Do not publish admin tokens, shared test tokens, production IPs, or real user
+tokens in docs. Examples should use placeholders:
+
+```text
+<GATEWAY_URL>
+<GATEWAY_TOKEN>
+<INVITE_CODE>
+<ADMIN_TOKEN>
+```
+
+Historical gateway migration reports under `docs/` are not current setup
+instructions unless [docs/index.md](./index.md) links them as authoritative.

package/docs/index.md

@@ -0,0 +1,98 @@
+# CCL Official Documentation Index
+
+This index defines the current authoritative documentation set for CCL
+`1.3.1`. If another markdown file disagrees with the files linked here, treat
+the linked file or the source code as authoritative and update the stale file.
+
+## Authority Order
+
+1. Runtime source and generated CLI output: `package.json`, `dist/cli.js
+   --help`, command sources under `commands/`, SDK sources under `sdk/`.
+2. Current official docs linked from this page.
+3. Historical reports under `docs/` that are not linked here.
+
+Historical reports can explain past decisions, but they are not current setup
+instructions.
+
+## Start Here
+
+| Need | Document |
+|---|---|
+| First install and first session | [QUICKSTART.md](../QUICKSTART.md) |
+| Full package entry point and feature map | [README.md](../README.md) |
+| Gateway setup | [docs/gateway-quickstart.md](./gateway-quickstart.md) |
+| Source checkout validation | [docs/dev-quickstart.md](./dev-quickstart.md) |
+| Legacy intent gateway migration note | [INTENT-GATEWAY-GUIDE.md](../INTENT-GATEWAY-GUIDE.md) |
+| SDK overview | [sdk/README.md](../sdk/README.md) |
+| SDK API contract | [sdk/API.md](../sdk/API.md) |
+| Documentation inventory and classification | [docs/official-docs-coverage-matrix.json](./official-docs-coverage-matrix.json) |
+
+## Feature Coverage Map
+
+| Feature Area | Current Source |
+|---|---|
+| Package version, install, runtime requirements | [README.md](../README.md), [QUICKSTART.md](../QUICKSTART.md), `package.json` |
+| Interactive TUI and slash commands | [README.md](../README.md), `commands/` |
+| Non-interactive CLI, `--print`, JSON and stream JSON | [README.md](../README.md), `dist/cli.js --help` |
+| Authentication: gateway, OAuth, API key | [README.md](../README.md), [QUICKSTART.md](../QUICKSTART.md), [docs/gateway-quickstart.md](./gateway-quickstart.md) |
+| Gateway registration, login, status, doctor, logout | [docs/gateway-quickstart.md](./gateway-quickstart.md), `commands/gateway/` |
+| Model, endpoint, priority, effort controls | [README.md](../README.md), [QUICKSTART.md](../QUICKSTART.md), `commands/model/`, `commands/endpoint/`, `commands/priority/`, `commands/effort/` |
+| Permissions and tool allow/deny controls | [README.md](../README.md), `commands/permissions/`, CLI help |
+| Session resume, continue, fork, compact, rewind, clear | [README.md](../README.md), CLI help, `commands/resume/`, `commands/compact/`, `commands/rewind/`, `commands/clear/` |
+| Workflows | [README.md](../README.md), `commands/workflows/`, CLI `workflow` command |
+| MCP, plugins, skills, hooks | [README.md](../README.md), `commands/mcp/`, `commands/plugin/`, `commands/skills/`, `commands/hooks/` |
+| Agents, subagents, buddy, branch/fork | [README.md](../README.md), `commands/agents/`, `commands/buddy/`, `commands/branch/` |
+| Remote control, remote sessions, remote env | [README.md](../README.md), `commands/bridge/`, `commands/session/`, `commands/remote-env/` |
+| IDE, Chrome, desktop, mobile, terminal and web setup | [README.md](../README.md), matching command sources under `commands/` |
+| Review, security review, PR comments, commit helpers | [README.md](../README.md), `commands/review*`, `commands/security-review.ts`, `commands/pr_comments/`, `commands/commit*` |
+| Usage, cost, stats, rate limits, extra usage | [README.md](../README.md), matching command sources under `commands/` |
+| SDK query, permission interception, pending approvals, resume, usage store | [sdk/README.md](../sdk/README.md), [sdk/API.md](../sdk/API.md), `sdk/` |
+| Developer build and validation | [docs/dev-quickstart.md](./dev-quickstart.md), `package.json` scripts |
+
+## Agent Instruction Files
+
+The following files affect agent behavior and must be treated as documentation,
+but with different audiences:
+
+| File | Classification | Audience |
+|---|---|---|
+| `AGENTS.md` | internal agent/runtime instruction | Agents operating in this repository |
+| `CLAUDE.md` | compatibility instruction | Claude-family agents and RLL role routing |
+| `CODEX.md` | compatibility instruction | Codex-family agents and RLL role routing |
+| `CCL.md` | project-local memory/instruction candidate | Agents operating in this checkout |
+
+Public user docs should link to these only when explaining repository-local
+agent operation. They are not end-user setup guides.
+
+## Safety And Staleness Policy
+
+Current official docs must not contain:
+
+- Real API keys, gateway tokens, shared team keys, or admin tokens.
+- Concrete production IP addresses unless explicitly approved for public docs.
+- Legacy endpoint strings presented as current setup.
+- Version claims that disagree with `package.json`.
+
+Use placeholders:
+
+```text
+<GATEWAY_URL>
+<GATEWAY_TOKEN>
+<ANTHROPIC_API_KEY>
+<INVITE_CODE>
+```
+
+## Coverage Matrix
+
+The machine-readable inventory is
+[docs/official-docs-coverage-matrix.json](./official-docs-coverage-matrix.json).
+Each markdown file in the official audit scope is classified as one of:
+
+- `keep`
+- `rewrite`
+- `split`
+- `archive`
+- `delete`
+
+The matrix is a planning and audit artifact. It does not make archived reports
+authoritative.

package/docs/peer-development-review.md

@@ -0,0 +1,60 @@
+# 轻量双 Agent 开发与审查
+
+> npm 包的公开命令为 `margay`。下文带日期、提交号和本机 `~/.local/bin/ccl` 的记录属于历史验收；该本机入口不是 npm 安装保证提供的命令，也不代表当前候选已通过回归。
+
+> P1 已完成开发、Lisa 代码与修复审核，以及 C1–C12 全部门禁。验收范围见 源码检出中的历史实施与验证记录 `docs/ccl-peer-dual-agent-p1-validation.md`（不随 npm 包分发）。
+
+在 CCL 的一个界面中，由两个保留独立上下文的 Agent 完成「开发 → 审查 → 修改或完成」。本文的受保护模式是 `/buddy --peer-review`：开发者写代码，审查者检查独立提交副本、运行测试并给出结论。开发者可以质疑结论，但不能自行覆盖审查者的否决。Duo 的当前 v2 审核者则可在普通工作区检查，完成还需执行者核查并接受当前 PASS 和双模型实际请求；详见 [Duo 指南](ccl-duo-agent.md)。
+
+## 普通 Buddy
+
+普通 `/buddy <任务>` 是提示展开：主 Agent 先调用 TeamCreate 创建或复用团队，随后用 TeamCreate 实际返回的团队名与成员名调用 Agent。默认团队名为 `buddy-team`、成员名为 `reviewer`；`--team` 和 `--name` 可覆盖。若主 Agent 已带领另一团队，应报告冲突，不应替换它。成员名包含 `reviewer` 或 `critic` 时，提示会加入审查职责。仅有提示文本不证明队友已启动，请核对 Team 和 Agent 的真实结果。
+
+## 启动
+
+先用 `/model` 选择开发者的明确模型 ID，再执行：
+
+```text
+/buddy --peer-review --reviewer-model <审查者模型ID> 修复解析器遗漏最后一个 token 的问题，并补回归测试
+```
+
+两个角色可以使用不同模型，也可以使用同一模型；两者仍有各自上下文。`auto`、`smart`、模型池或继承等动态模型选择不能用于固定角色绑定。模型不可用或供应商明确报告使用了另一个模型时，协作会拒绝继续该请求，不会悄悄换模型。
+
+可选命名：
+
+```text
+/buddy --peer-review --reviewer-model <模型ID> --team parser-fix --name reviewer 修复解析器
+```
+
+省略 `--team` 时自动生成新名称。显式名称须对应新团队；历史审查记录不会因同名重建而消失。
+
+普通 `/buddy <任务>` 和原有 Team 入口仍可照常使用。这是按需开启的模式。
+
+## 你会看到什么
+
+1. CCL 创建一个受保护的开发任务，并启动审查者。
+2. 开发者实现后提交当前内容。审查者收到消息，在独立副本中检查与测试。
+3. 审查发现问题时，双方通过现有团队消息说明证据，开发者修改后重新提交。
+4. 当前提交获得审查者 PASS，任务才标记完成。旧 PASS 不能批准后来修改的内容；项目已配置的 TaskCompleted hooks 仍可阻止完成。
+
+任务状态可能是等待审查者、开发中、审查中、需要修改、通过、暂停或取消。暂停和取消都不表示目标已完成。默认最多 5 轮提交，每份提交最多 2 次正式挑战；达到限制后保留记录，交由用户决定下一步。
+
+可以用自然语言要求 CCL 查看任务、解释争议或取消协作。正常结束时，CCL 向审查者发送关闭请求。当前不承诺进程重启后自动恢复正在进行的双 Agent 协作。团队运行资源与审查记录分别处理：终态任务与提交副本保留，不会随团队清理而删除。
+
+## 为什么旧 PASS 不能继续使用
+
+每份提交记录文件路径、内容和可执行位的摘要。审查结论绑定这份提交和审查者的真实执行身份。开发者改动内容、提交新版本，或换了同名审查实例，都不能继续使用原判定。普通任务的 owner、metadata、completed 或删除操作也不能代替审查动作。
+
+## 审查副本与边界
+
+当前支持 Git 工作目录，覆盖已跟踪文件、未被忽略的新文件以及删除、重命名和未提交改动。每轮创建独立文件副本；存在 `node_modules` 时独立复制依赖，不自动安装依赖。审查测试产生的输出留在副本，改动被审查输入会使该份测试证据失效。
+
+副本不包含 Git 元信息；依赖 Git 历史、子模块或越界符号链接的项目可能需要调整测试方式。缺失依赖或无法执行测试必须明确报告，不能当作测试通过。
+
+这是正常工具调用的权限与测试副作用隔离，不是操作系统沙箱；同一用户权限下的恶意任意 Shell 命令或直接修改原始状态文件，不在其强制保护范围内。
+
+供应商未报告实际模型时，记录为 unknown；供应商自报身份也不构成密码学证明。
+
+## 范围
+
+这一模式复用 CCL 现有 Team 通信、任务和 Agent 生命周期，不要求专业开发者经历完整 RLL 的方案/共识/级联门禁。IDE 可先使用集成终端运行 CCL；专用 IDE 面板、完整版 RLL 接入、SDK 多用户服务不属于本轮交付。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@margay/ccl-core",
-  "version": "1.4.0-beta.0",
+  "version": "1.4.5-rc.0",
   "description": "Core runtime extracted from Claude Code (ccl) for Margay integration",
   "license": "SEE LICENSE IN README.md",
   "type": "module",
@@ -11,7 +11,15 @@
     "dist",
     "README.md",
     "QUICKSTART.md",
-    "INTENT-GATEWAY-GUIDE.md"
+    "INTENT-GATEWAY-GUIDE.md",
+    "docs/index.md",
+    "docs/gateway-quickstart.md",
+    "docs/dev-quickstart.md",
+    "docs/ccl-duo-agent.md",
+    "docs/ccl-ide-usage.md",
+    "docs/peer-development-review.md",
+    "sdk/README.md",
+    "sdk/API.md"
   ],
   "engines": {
     "node": ">=20.0.0"