@aliyunrds/ctxdb 1.0.6 → 1.0.8-beta.0

package/README.internal.md

@@ -0,0 +1,59 @@
+# @ali/ctxdb-internal
+
+ContextDB 集团内部版 CLI。它通过浏览器或 Device Code 登录选择 Workspace，自动
+取得当前 Member 的连接凭据，并为 Qoder、QoderWork、QwenWork、Codex、Claude
+Code、OpenCode 和 Hermes 配置 hooks、skills 或插件。
+
+## 安装
+
+推荐使用 ContextDB Web 提供的安装命令。手动安装时执行：
+
+```sh
+npm install -g @ali/ctxdb-internal@latest \
+  --registry https://registry.anpm.alibaba-inc.com
+```
+
+## 登录与配置 Agent
+
+有浏览器的本机终端：
+
+```sh
+ctxdb login --server https://contextdb.alibaba-inc.com --agent codex
+```
+
+SSH、远程或无头终端：
+
+```sh
+ctxdb login --server https://contextdb.alibaba-inc.com \
+  --agent codex --device-code
+```
+
+登录成功后检查当前连接：
+
+```sh
+ctxdb auth status --json
+```
+
+一个本地安装只保留一条当前连接，一个 API Key 只属于一个 Workspace。切换
+Workspace 时重新执行 `ctxdb login`；新连接完成后会原子替换本地凭据，并尝试
+吊销由上一次 CLI 登录签发的 Key。
+
+## 本地文件
+
+- `~/.ctxdb/credentials.json`：当前连接凭据，仅当前用户可读；
+- `~/.ctxdb/ctxdb.json`：Agent 行为配置，不写入 API Key；
+- `~/.ctxdb/logs/`：运行日志与 recall trace，不记录 API Key。
+
+不要把 `credentials.json`、API Key、授权码或登录回调 URL 复制到聊天、日志或代码
+仓库。内部版不接受 `ctxdb setup --api-key` 或 `ctxdb setup --base-url`；凭据和
+DATA API 地址均由登录服务提供。
+
+## 退出与升级
+
+```sh
+ctxdb logout
+ctxdb update
+```
+
+`logout` 会吊销当前 CLI 签发的 Key 并删除本地凭据。`update` 会从 Ali NPM 检查
+并安装 `@ali/ctxdb-internal` 的新版本，然后刷新 Agent 集成。

package/README.md

@@ -11,11 +11,55 @@ Unified access layer for RDS ContextDatabase. One `ctxdb` CLI (memory + KB ops),
 | **claude** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.claude/skills/ctxdb/` | hooks-driven (auto capture/recall) |
 | **opencode** | Plugin shim (`~/.config/opencode/plugins/ctxdb.ts`) | `~/.config/opencode/skills/` | in-process plugin (auto capture/recall + KB catalog injection) |
 | **hermes** | ✅ `pre_llm_call` + `post_llm_call` | `~/.hermes/skills/` | shell hooks (auto capture/recall + first-turn warmup) |
+| **workbuddy** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.workbuddy/skills/ctxdb/` | hooks-driven (auto capture/recall); Claude-Code-isomorphic (exec form) |
 
-Config and logs live under `~/.ctxdb/`. `~/.ctxdb/ctxdb.json` is one file, but runtime config is isolated per agent under `agents.qoder`, `agents.qoderwork`, `agents.qwenwork`, `agents.codex`, `agents.claude`, `agents.opencode`, and `agents.hermes`. (Pre-2026-05-23 installs used `~/.ctxdb.json` at the home root; running `ctxdb setup --agent <name>` migrates the file into the selected agent section.)
+Config and logs live under `~/.ctxdb/`. `~/.ctxdb/ctxdb.json` is one file, but runtime config is isolated per agent under `agents.qoder`, `agents.qoderwork`, `agents.qwenwork`, `agents.codex`, `agents.claude`, `agents.opencode`, `agents.hermes`, and `agents.workbuddy`. (Pre-2026-05-23 installs used `~/.ctxdb.json` at the home root; running `ctxdb setup --agent <name>` migrates the file into the selected agent section.)
 
 ## Install
 
+### Internal browser-login distribution
+
+The same source also builds `@ali/ctxdb-internal`. That artifact alone
+adds `ctxdb login --server <url>`, `ctxdb login --device-code`, `ctxdb logout`,
+and `ctxdb auth status`. The default login uses a browser loopback callback;
+`--device-code` supports remote or headless terminals. Both methods discover a
+provider-neutral protocol and use PKCE. The selected Workspace is represented
+by the returned API key, so the CLI does not persist a separate Workspace id.
+
+Internal login stores its single active connection in owner-only
+`~/.ctxdb/credentials.json`. It then runs the normal Agent setup lifecycle
+without writing an `api_key` field into the Agent or default profile; an
+existing field in either updated profile is removed. At runtime this managed
+credential overrides the API key and DATA URL in the existing v2
+`~/.ctxdb/ctxdb.json`; `CTXDB_API_KEY` and `CTXDB_BASE_URL` remain the highest
+priority overrides. Re-login replaces the active connection and revokes the
+previous key after setup succeeds. The public `@aliyunrds/ctxdb` build does not
+contain or advertise these commands and continues to use `ctxdb setup` and the
+v2 config exactly as before. Build the internal staging package with
+`pnpm build:internal`.
+
+The distinction is a compile-time distribution manifest, not a runtime
+environment-variable or file-existence check. The `public` manifest disables
+`interactiveLogin` and `managedCredentials`; the `internal` manifest enables
+both. The CLI hooks and the separately bundled OpenCode plugin receive the
+same manifest, so installing a public build on a machine that happens to have
+`~/.ctxdb/credentials.json` does not make that build consume the file.
+
+Internal users install the package from Ali NPM. The internal version is
+managed independently in `internal-release.json`; it does not inherit the
+public package version.
+
+```sh
+npm install -g @ali/ctxdb-internal@latest \
+  --registry https://registry.anpm.alibaba-inc.com
+ctxdb login --server https://contextdb.alibaba-inc.com --agent codex
+ctxdb auth status --json
+```
+
+The internal tarball bundles `@aliyunrds/ctxdb-shared`, so users install only
+one ContextDB package. `semver` and `yaml` remain normal registry dependencies.
+Maintainers should follow [`INTERNAL_PUBLISH.md`](./INTERNAL_PUBLISH.md).
+
 ### Recommended: console-generated installer command
 
 The customer console supplies the selected Agent and API key to one of two
@@ -164,9 +208,9 @@ ctxdb setup --agent codex --api-key 'ctxdb-new-...'
 ctxdb status --agent codex --json
 ```
 
-Setup first checks that the target agent home exists (`~/.qoder`, `~/.qoderwork`, `~/.qwenwork`, `~/.codex`, or `~/.claude`; the declared CN variant home also satisfies this check). Setup writes hooks and skills only into homes that already exist, so a CN-only install does not create the international product home, and vice versa. If no home exists, install or start that agent once before running `ctxdb setup --agent <name>`. OpenCode and Hermes are config-dir style: setup creates `~/.config/opencode` / `~/.hermes` when they are missing.
+Setup first checks that the target agent home exists (`~/.qoder`, `~/.qoderwork`, `~/.qwenwork`, `~/.codex`, `~/.claude`, or `~/.workbuddy`; the declared CN variant home also satisfies this check). Setup writes hooks and skills only into homes that already exist, so a CN-only install does not create the international product home, and vice versa. If no home exists, install or start that agent once before running `ctxdb setup --agent <name>`. OpenCode and Hermes are config-dir style: setup creates `~/.config/opencode` / `~/.hermes` when they are missing.
 
-For **qoder**, **qoderwork**, **qwenwork**, **codex**, and **claude**, restart the harness (CLI: just exit + restart; app: Cmd+R or quit/relaunch) so it picks up the new hooks/skill. For **codex**, setup also writes `[features].hooks = true` into `~/.codex/config.toml` (creating the file if missing) — Codex won't fire any hook entries without it. On first use Codex may prompt you to trust the new hook commands. For **opencode**, restart OpenCode so it loads `~/.config/opencode/plugins/ctxdb.ts`. For **hermes**, setup also checks `~/.hermes/shell-hooks-allowlist.json`; it reports setup as incomplete until both ctxdb hook commands are approved.
+For **qoder**, **qoderwork**, **qwenwork**, **codex**, **claude**, and **workbuddy**, restart the harness (CLI: just exit + restart; app: Cmd+R or quit/relaunch) so it picks up the new hooks/skill. For **codex**, setup also writes `[features].hooks = true` into `~/.codex/config.toml` (creating the file if missing) — Codex won't fire any hook entries without it. On first use Codex may prompt you to trust the new hook commands. For **opencode**, restart OpenCode so it loads `~/.config/opencode/plugins/ctxdb.ts`. For **hermes**, setup also checks `~/.hermes/shell-hooks-allowlist.json`; it reports setup as incomplete until both ctxdb hook commands are approved.
 
 Hermes owns this security allowlist, so ctxdb only checks it and never writes approvals. Approve the ctxdb `pre_llm_call` and `post_llm_call` hooks with:
 
@@ -211,15 +255,15 @@ ctxdb setup
 
 ## What it does
 
-For **qoder**, **qoderwork**, **qwenwork**, **codex**, and **claude**, hooks fire automatically:
+For **qoder**, **qoderwork**, **qwenwork**, **codex**, **claude**, and **workbuddy**, hooks fire automatically:
 
 | Trigger | Hook | What runs |
 |---|---|---|
 | Session starts | `SessionStart` | Build a short cwd/git-signal query, recall relevant memories, and inject warm-up context as `additionalContext` |
 | User submits a prompt | `UserPromptSubmit` | Search `/v3/memories/search/`, format a `<recalled-memories>` block, inject as additional context. **By default only memory is recalled.** Set `recall_knowledge: true` in the selected agent config to also pull KB context into an `<external-knowledge>` block; graph synthesis and document evidence are labeled separately inside that wrapper. Otherwise the recommended path for KB is the agent calling `ctxdb kb search --agent <name>` explicitly when the user asks (see SKILL.md) |
-| Agent finishes its turn | `Stop` | Read transcript, detect KB-upload turns and skip capture (so uploaded content doesn't bleed into long-term memory), slice the current turn, sanitize the input, POST to memory store |
+| Agent finishes its turn | `Stop` | Read transcript, detect KB create/update turns and skip capture (so document content doesn't bleed into long-term memory), slice the current turn, sanitize the input, POST to memory store |
 
-Implementation note: qoder/Claude consume the JSON `hookSpecificOutput.additionalContext` shape; Codex has been verified on this machine through `~/.codex/hooks.json`, `[features].hooks = true`, and hook audit logs, where non-empty stdout from `UserPromptSubmit`/`SessionStart` is treated as injected context. The same hook core is shared; setup passes `--agent=<name>` so each hook reads its own config section.
+Implementation note: qoder/Claude/WorkBuddy consume the JSON `hookSpecificOutput.additionalContext` shape; Codex has been verified on this machine through `~/.codex/hooks.json`, `[features].hooks = true`, and hook audit logs, where non-empty stdout from `UserPromptSubmit`/`SessionStart` is treated as injected context. The same hook core is shared; setup passes `--agent=<name>` so each hook reads its own config section.
 
 For **opencode**, `ctxdb setup --agent opencode` copies the self-contained plugin bundle to `~/.config/opencode/plugins/ctxdb-bundle.js` and writes a re-export shim at `~/.config/opencode/plugins/ctxdb.ts` referencing it via the relative path `./ctxdb-bundle.js` (Bun on Windows can't resolve absolute-path specifiers from a .ts shim). `ctxdb upgrade --agent opencode` re-copies the bundle + refreshes the shim.
 
@@ -227,15 +271,16 @@ For **hermes**, `ctxdb setup --agent hermes` writes two shell hooks under `~/.he
 
 - `pre_llm_call` maps to recall on each user prompt and first-turn warmup. Hermes does not persist hook context into conversation history, so ctxdb re-injects the KB catalog on every user turn even when `kb_catalog_injection` keeps its default `"session_start"` value; this prevents the catalog from disappearing after turn one.
 - stdout uses Hermes' `{"context":"..."}` protocol.
-- `post_llm_call` captures `extra.user_message` + `extra.assistant_response` without a transcript file, while `extra.conversation_history` supplies current-turn tool calls for the B-3c KB-upload guard.
+- `post_llm_call` captures `extra.user_message` + `extra.assistant_response` without a transcript file, while `extra.conversation_history` supplies current-turn tool calls for the B-3c KB create/update guard.
 
 ## CLI
 
 `ctxdb` ships grouped non-interactive commands:
 
 - **Top-level**: `setup` / `status` / `ping` / `debug` / `uninstall` / `update` (`upgrade` alias)
-- **Memory**: `memory add|search|list|get|update|delete`
-- **KB**: `kb upload-text|upload-file|list|documents-list|document-get|search`
+- **Memory**: `memory add|search|list|get|update|delete`, plus the `memory promotion` subgroup (记忆成文): `memory promotion generate|list|get|approve|reject|batch-action|batch-delete|resolve-doubts` and the `memory promotion template list|create|get|update|delete|set-default|clear-default` / `memory promotion settings get|update` sub-subgroups
+- **KB**: `kb upload-text|upload-file|update-text|update-file|list|documents-list|document-get|search`, plus the `kb review` subgroup: `kb review list|get|action|resolve-conflicts|batch-action|batch-delete|delete`, `kb review template list|create|update|delete|get|set-default|clear-default`, `kb review settings get|update`
+
 
 See `ctxdb --help`.
 
@@ -267,7 +312,7 @@ restores it. `ctxdb status` reports `debug` (effective), `debug_configured`,
 `debug_forced`, and `debug_reason` (`non_production_base_url` when forced).
 
 Effective debug writes full-fidelity recall records for qoder, qoderwork,
-qwenwork, codex, claude, opencode, and hermes to
+qwenwork, codex, claude, opencode, hermes, and workbuddy to
 `~/.ctxdb/logs/recall-trace.jsonl`. The trace contains the complete query,
 complete returned memory/KB candidates, local selected/excluded outcome, and
 the exact context injected into the model. **This can contain sensitive project
@@ -286,17 +331,72 @@ not be interpreted as a completed `timeout`. Disabling debug stops future
 writes but leaves existing trace files available for replay; `ctxdb uninstall
 --purge-logs` removes them.
 
-`setup` without `--agent` writes `agents.default` in `~/.ctxdb/ctxdb.json` (CLI-only, no hooks or skills); with `--agent <qoder|qoderwork|qwenwork|codex|claude|opencode|hermes>` it writes agent config and installs hooks/plugins + skills for that harness. Rerunning it repairs integration artifacts and may replace the selected Agent's API key. Memory and KB commands also accept `--agent <name>` so agents use their own config section; when omitted, `CTXDB_AGENT` env wins, otherwise `agents.default` is used. `uninstall` without `--agent` loops every supported agent; with `--agent <name>` it targets just that one. `teardown` is an alias for `uninstall`.
+`setup` without `--agent` writes `agents.default` in `~/.ctxdb/ctxdb.json` (CLI-only, no hooks or skills); with `--agent <qoder|qoderwork|qwenwork|codex|claude|opencode|hermes|workbuddy>` it writes agent config and installs hooks/plugins + skills for that harness. Rerunning it repairs integration artifacts and may replace the selected Agent's API key. Memory and KB commands also accept `--agent <name>` so agents use their own config section; when omitted, `CTXDB_AGENT` env wins, otherwise `agents.default` is used. `uninstall` without `--agent` loops every supported agent; with `--agent <name>` it targets just that one. `teardown` is an alias for `uninstall`.
 
 `memory add … --no-infer` stores the text verbatim (skips server-side LLM
 fact-extraction). Use it when the user explicitly asks for a verbatim
 memory ("记住 / 请记忆 / 原文记下"); without `--no-infer` the server may
 rewrite, merge, or skip details.
 
-### KB upload completion mode
+### Memory promotion (记忆成文)
+
+The promotion commands live under the Memory group (`ctxdb memory promotion ...`) and cover the server's memory promotion pipeline: turn
+accumulated memories into reviewed knowledge-base documents.
 
-**Breaking change:** `kb upload-text` and `kb upload-file` now return as soon
-as the service accepts the document. The returned document may still have
+```sh
+# Task lifecycle
+ctxdb memory promotion generate "<topic>" [--knowledge-base-id=<kb-id>]
+ctxdb memory promotion list [--status=pending_review] [--page=N] [--page-size=N] \
+                     [--sort-by=quality_score] [--sort-order=asc|desc]
+ctxdb memory promotion get <promotion-id>
+ctxdb memory promotion approve --promotion-id=<id> --knowledge-base-id=<kb-id>
+ctxdb memory promotion reject --promotion-id=<id> [--reason=<text>]
+ctxdb memory promotion batch-action --action=<approve|reject> --ids=<id1,id2,...> \
+                             [--knowledge-base-id=<kb-id>] [--reason=<text>]
+ctxdb memory promotion batch-delete --ids=<id1,id2,...>        # rejected tasks only
+ctxdb memory promotion resolve-doubts --promotion-id=<id> \
+    --resolutions-json='[{"index":0,"choice":"<label>","comment":"..."}]' \
+    [--title=<title>] [--content=<markdown>]
+
+# Document templates (up to 5 per member)
+ctxdb memory promotion template list
+ctxdb memory promotion template create --name=<name> \
+    --sections-json='[{"title":"...","guidance":"...","level":1}]' [--is-default]
+ctxdb memory promotion template get|update|delete|set-default <template-id>
+ctxdb memory promotion template clear-default
+
+# Auto-ingest settings (current Member in the current Workspace)
+ctxdb memory promotion settings get
+ctxdb memory promotion settings update [--auto-ingest-enabled=<true|false>] \
+    [--auto-ingest-threshold=<0..1>] [--default-kb-id=<kb-id> | --clear-default-kb]
+```
+
+Notes:
+
+- Routes, methods, and parameter names mirror `openapi/data-api.yaml`
+  (`/v1/memory_promotions/**`). Batch requests accept at most 50 ids.
+- `approve` and `batch-action --action=approve` require an explicit
+  `--knowledge-base-id`; rejecting does not require a target KB.
+- Batch commands print every result and exit 1 if any item failed.
+- `--clear-default-kb` sends an empty `default_kb_id` string, which the
+  server interprets as clearing the target (null means unchanged). If
+  auto-ingest is enabled, also pass `--auto-ingest-enabled=false` to clear it.
+- Write commands validate required identifiers (promotion/template id,
+  batch ids, action) locally and exit 2 without sending a request when
+  arguments are missing or invalid.
+- Default output is a compact agent-friendly view (`list` keeps
+  decision-relevant row fields; `template list` drops rendered markdown
+  and guidance text). `--raw` returns successful server envelopes verbatim
+  but still rejects business errors, including string error codes;
+  `--json` pretty-prints whichever view is active.
+- `template` / `settings` are second-level subgroups: running
+  `ctxdb memory promotion` or `ctxdb memory promotion template` without a subcommand
+  lists the available subcommands and exits 2.
+
+### KB create/update completion mode
+
+`kb upload-text`, `kb upload-file`, `kb update-text`, and `kb update-file`
+return as soon as the service accepts the document. The returned document may still have
 `ingest_status: "processing"`; acceptance does not mean ingestion succeeded.
 
 - Add `--wait` when a script needs the previous behavior: poll until ingestion
@@ -309,23 +409,110 @@ Scripts that relied on implicit terminal polling must migrate to:
 ```sh
 ctxdb kb upload-text <kb-name> <doc-name> --text="<body>" --wait
 ctxdb kb upload-file <kb-name> <local-path> --wait
+ctxdb kb update-text <document-id> --text="<body>" --wait
+ctxdb kb update-file <document-id> <local-path> --wait
 ```
 
+### Explicit KB document updates
+
+Create and update are separate operations. `upload-text` / `upload-file` use
+create-only POST routes, so an existing logical document produces HTTP 409 and
+is never silently overwritten. `update-text` / `update-file` use PUT and accept
+exactly one locator family: the canonical document ID (preferred), or an
+explicit knowledge-base name + logical document name + optional normalized
+`--file-path`.
+
+```sh
+# Preferred: no KB/name/path lookup or reconstruction
+ctxdb kb update-text <document-id> --text="<new-body>"
+ctxdb kb update-file <document-id> <local-path>
+
+# Alternative when the exact document ID is unavailable
+ctxdb kb update-text --kb-name=<kb-name> --doc-name=<logical-name> --text="<new-body>" [--file-path=<logical-parent>]
+ctxdb kb update-file <local-path> --kb-name=<kb-name> [--doc-name=<existing-logical-name>] [--file-path=<logical-parent>]
+```
+
+Do not combine a positional document ID with `--kb-name`, `--doc-name`, or
+`--file-path`. ID mode derives the existing document's KB and logical metadata
+on the server; a replacement file's basename remains only its physical upload
+filename. Logical-key file mode defaults `--doc-name` to that basename, so pass
+the existing logical name when the replacement basename differs.
+
+Every successful update returns the canonical `document.id` and
+`document.knowledge_base_id`. Changed content can replace the input ID, while
+same-content updates may reuse it. Callers must retain the returned ID for the
+next update; `--wait` also polls the returned ID/KB pair rather than caller input.
+
+### Knowledge review commands
+
+`kb review` covers the Knowledge Review DATA APIs: review-queue handling
+(single/batch actions, conflict resolution, deletion), review-rewrite
+templates, and per-knowledge-base review settings. Every command accepts `--agent`
+(`CTXDB_AGENT`) and `--json`; list/detail commands follow the three-tier
+projection (`kb search` discipline): default prints a minimal agent view,
+`--verbose` adds sourcing/audit fields, `--raw` ships the server envelope
+verbatim. Missing or illegal arguments print usage and exit 2 before any
+request is sent.
+
+```sh
+# Review queue (filters are optional; sort by quality score)
+ctxdb kb review list --knowledge-base-id=<kb-id> --review-status=pending --sort-by=confidence_score
+ctxdb kb review get <review-id> [--content-page=N] [--verbose|--raw]
+
+# Human actions: confirm | force_accept | accept_rewrite | reject | reject_reupload
+ctxdb kb review action <review-id> --action=confirm
+ctxdb kb review action <review-id> --action=accept_rewrite --edited-content=<text>
+ctxdb kb review resolve-conflicts <review-id> \
+  --resolutions='[{"conflict_id":"<id>","resolution":"use_new|keep_old|merge|annotate_divergence"}]'
+
+# Batch (up to 50 ids per request; batch-action supports confirm|reject)
+ctxdb kb review batch-action --action=confirm --ids=<id1>,<id2>
+ctxdb kb review batch-delete --ids=<id1>,<id2>
+ctxdb kb review delete <review-id>
+
+# Review-rewrite templates (per knowledge base, max 5 per KB)
+ctxdb kb review template list <kb-id>
+ctxdb kb review template create <kb-id> --name=<name> --sections-file=sections.json [--default]
+ctxdb kb review template update <kb-id> <template-id> [--name=<name>] [--sections=<json>] [--default|--no-default]
+ctxdb kb review template get <kb-id> <template-id> [--verbose|--raw]
+ctxdb kb review template set-default <kb-id> <template-id>
+ctxdb kb review template clear-default <kb-id>
+ctxdb kb review template delete <kb-id> <template-id>
+
+# Review settings for one knowledge base
+ctxdb kb review settings get <kb-id>
+ctxdb kb review settings update <kb-id> --review-enabled --high-threshold=0.85 --rewrite-enabled --max-rewrite-iterations=3
+```
+
+`--sections` / `--sections-file` take a JSON array
+(`[{"level": 1, "title": "...", "guidance": "..."}]`, `level` optional 1-3,
+max 15 sections). `accept_rewrite` falls back to the server-rendered rewrite
+when `--edited-content` is omitted. `kb review template get` on a missing
+template reports `{"found": false}` instead of erroring, matching the server
+contract.
+
 ### KB file upload policy and large files
 
-`kb upload-file` does not maintain a client-side format allowlist or file-size
+`kb upload-file` and `kb update-file` do not maintain a client-side format allowlist or file-size
 table. It validates only that the local path exists, is a readable regular
 file, then lets the service decide whether the format, per-type size, quota,
 and logical document identity are acceptable. Unknown extensions are sent as
 `application/octet-stream`.
 
 File bytes are streamed from disk with a known multipart size; the CLI does
-not read the complete file into a Buffer. It always attempts the ordinary
-upload endpoint first. If the service returns the dedicated
+not read the complete file into a Buffer. Each command attempts its ordinary
+direct endpoint first. If the service returns the dedicated
 `KNOWLEDGE_DIRECT_UPLOAD_REQUIRES_CHUNK` error (`errorCode=6001`) or an
-unstructured HTTP 413, the CLI resolves the KB ID and automatically uses the
-chunk init/part/complete protocol. `--doc-name` and `--file-path` have the same
-logical meaning in both modes.
+unstructured HTTP 413, the CLI automatically uses the chunk init/part/complete
+protocol. Create init uses POST and update init uses PUT; parts, complete, and
+abort stay on POST. Document-ID update init sends the ID and physical filename
+without resolving a KB. Logical-key update init resolves the KB and sends the
+same KB/name/path identity as direct mode.
+
+Chunk init and complete accept the release_pre bare response objects. Create
+also accepts the previous `Box.data` init/complete shape during rolling
+deployment; part and abort responses remain Box-wrapped. This response-shape
+compatibility does not fall back from logical-key PUT to an older update contract.
 
 The first chunk-routing release intentionally sends init, each part, and
 complete only once. It does not automatically retry timeout, connection-loss,
@@ -397,7 +584,7 @@ Lives at `~/.ctxdb/ctxdb.json` (co-located with logs at `~/.ctxdb/logs/`). Schem
 }
 ```
 
-Agent selection is driven by `--agent <qoder|qoderwork|qwenwork|codex|claude|opencode|hermes|default>` on every CLI invocation, falling back to `CTXDB_AGENT` env, then to `default`. There is no `default_agent` field — older installs that have one written get it dropped on the next save.
+Agent selection is driven by `--agent <qoder|qoderwork|qwenwork|codex|claude|opencode|hermes|workbuddy|default>` on every CLI invocation, falling back to `CTXDB_AGENT` env, then to `default`. There is no `default_agent` field — older installs that have one written get it dropped on the next save.
 
 Field reference:
 
@@ -414,7 +601,7 @@ Field reference:
 | `knowledge_top_k` | int | `6` | KB chunks pulled per recall (only effective when `recall_knowledge: true`) |
 | `debug` | bool | `false` | Configured preference for verbose hook logging and full recall tracing. Effective debug is forced on for every final `base_url` outside the exact official-production allowlist; see “Debug control and recall replay”. General logs go to `~/.ctxdb/logs/ctxdb.log`, structured full-content recall records to `~/.ctxdb/logs/recall-trace.jsonl` |
 
-Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID` / `CTXDB_AGENT_ID` / `CTXDB_APP_ID`. The last two default to unset — the request body omits `agent_id`/`app_id` entirely; set them only when you want per-agent / per-app scope isolation on the server.
+Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID` / `CTXDB_AGENT_ID` / `CTXDB_APP_ID`. The internal login command additionally reads `CTXDB_LOGIN_SERVER` as its provider-neutral login endpoint. The last two default to unset — the request body omits `agent_id`/`app_id` entirely; set them only when you want per-agent / per-app scope isolation on the server.
 
 Hook/plugin escape hatch: set `CTXDB_SKIP_HOOKS=TRUE` on the agent process to make all ctxdb hook entrypoints exit immediately before reading config or calling the API. Direct `ctxdb memory` / `ctxdb kb` / `ctxdb setup` CLI commands are unchanged.
 
@@ -475,7 +662,7 @@ ctxdb uninstall --purge-logs     # also deletes ~/.ctxdb/logs/
 
 ### What uninstall does (and doesn't) touch
 
-- **Hook entries in `~/.qoder/settings.json`, `~/.qoderwork/settings.json`, `~/.qwenwork/settings.json`, `~/.codex/hooks.json`, `~/.claude/settings.json`, and `~/.hermes/config.yaml`**: stripped precisely by marker (`_ctxdb = @aliyunrds/ctxdb`, plus legacy keys `_ctxdbQoder` / `_ctxdbPackage` and the legacy `@aliyunrds/ctxdb-qoder` value for installs predating the unified marker). Any hooks you added yourself stay. A timestamped `*.bak-ctxdb-<TS>` is written before each modification (rotation keeps the 5 most recent).
+- **Hook entries in `~/.qoder/settings.json`, `~/.qoderwork/settings.json`, `~/.qwenwork/settings.json`, `~/.codex/hooks.json`, `~/.claude/settings.json`, `~/.workbuddy/settings.json`, and `~/.hermes/config.yaml`**: stripped precisely by marker (`_ctxdb = @aliyunrds/ctxdb`, plus legacy keys `_ctxdbQoder` / `_ctxdbPackage` and the legacy `@aliyunrds/ctxdb-qoder` value for installs predating the unified marker). Any hooks you added yourself stay. A timestamped `*.bak-ctxdb-<TS>` is written before each modification (rotation keeps the 5 most recent).
 - **Skill directories**: `~/.<agent>/skills/ctxdb/` for each set-up agent, plus legacy dirs (`ctxdb-qoder`, `rds-ctxdb-qoder`, `qoder-ctxdb`) under `~/.qoder/skills/` from older package names.
 - **`~/.ctxdb/` state**: only with `--purge-config` / `--purge-logs` / `--purge-all`. Defensive: `--purge-all` removes the `~/.ctxdb/` root only if it's empty after the named files are deleted (won't blanket-rm an unknown directory).
 - **`~/.codex/config.toml` `[features].hooks`**: **NOT** reverted. Setup adds `hooks = true` so Codex will fire ctxdb's hook entries; uninstall leaves the flag alone because (a) the user may have wanted it on for non-ctxdb hooks, and (b) it's harmless when `~/.codex/hooks.json` is empty. If you want it off, edit the file by hand.

package/dist/{chunk-BHRWAU3E.js → chunk-24CNB3XJ.js}

@@ -2,10 +2,10 @@
 import {
   fetchKbCatalogBlock,
   recallTurn
-} from "./chunk-VHNHVMCA.js";
+} from "./chunk-WSMZOFZQ.js";
 import {
   debug
-} from "./chunk-ARZX2RLR.js";
+} from "./chunk-AAZLOCVB.js";
 
 // src/lib/warmup-recall.ts
 import { execSync } from "child_process";