@thinkingai/ae-cli 6.1.19 → 6.1.21

package/skills/ae-generate-tracking-plan/SKILL.md

@@ -79,7 +79,7 @@ Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
 > CLI messages, and auto-track/i18n-owned labels must come from `src/tracking/i18n` via `AE_LANG=<user_lang>` and `draft.meta.lang`.
 > When a localized label is needed, inspect `src/tracking/i18n` and use the existing resource key/value; do not invent translations from the model.
 > If template business text needs localization and the CLI/i18n resources do not provide it, preserve the imported text and ask the user before rewriting business semantics.
-> Only identifier fields like `event_name`, `prop_name` remain in English snake_case (canonical format).
+> Only identifier fields like `event_name`, `prop_name` remain in English. Property names are `snake_case`; event names are lowercase by default, uppercase only when the user asks to preserve it.
 > This skill only cares about command behavior, not internal implementation.
 
 ---
@@ -111,7 +111,7 @@ If **not** in a sandbox environment, ask exactly:
 ```text
 Choose your source material (up to 2):
 
-1 - Product document (local path, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
+1 - Product document (local path, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/xlsx/pptx/URL/images (png/jpg/jpeg/webp)
 2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
 3 - Codebase (local project path; hidden in sandbox) — Analyze source code to extract events and properties
 4 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
@@ -126,7 +126,7 @@ If in a sandbox environment, ask exactly:
 ```text
 Choose your source material (up to 2):
 
-1 - Product document (sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp). You can attach/upload relevant files here.
+1 - Product document (sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/xlsx/pptx/URL/images (png/jpg/jpeg/webp). You can attach/upload relevant files here.
 2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
 3 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
 4 - Modify existing tracking plan (sandbox workspace path) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description, but NOT with Pre-built template
@@ -142,7 +142,7 @@ User can multi-select (max 2). Interpret numbers by the **visible list shown to
 
 Canonical source material options (non-sandbox numbering):
 
-1. **Product document** ****(****local path, sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
+1. **Product document** ****(****local path, sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/xlsx/pptx/URL/images (png/jpg/jpeg/webp)
 2. **Detailed description** (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
 3. **Codebase** (local project path; hidden in sandbox) — Analyze source code to extract events and properties
 4. **Pre-built template** (built-in industry and game genre templates) — Select a built-in template (run `AE_LANG=<user_lang> ae-cli tracking plan list-templates --json` to see available templates)
@@ -210,7 +210,7 @@ Based on user selection, determine source material type and record to `meta.sour
    | Severity | Examples | Handling | User Action |
    |---|---|---|---|
    | 🔧 **Minor** (auto-fixable) | `display_name` duplicate, `array_row` sub-property inconsistency, event name duplicate | `--fix` auto-fixes, writes to `draft.json`. Inform user of what was fixed. | None (informed) |
-   | ⚠️ **Medium** (needs confirmation) | snake_case violation, property name duplicate, invalid property type, nested property parent is not a composite type | List each issue with current value → suggested fix. User confirms item by item before writing to `draft.json`. | Confirm each fix |
+   | ⚠️ **Medium** (needs confirmation) | property name snake_case violation, property name duplicate, invalid property type, nested property parent is not a composite type | List each issue with current value → suggested fix. User confirms item by item before writing to `draft.json`. | Confirm each fix |
    | 🛑 **Severe** | File cannot be parsed, or events array is empty after import | Reject. Tell user the specific issue. User fixes **original file** and re-imports. | Fix original file |
 
    **Medium issue confirmation format**:
@@ -219,7 +219,7 @@ Based on user selection, determine source material type and record to `meta.sour
 
    | # | Issue | Location | Current | Suggested |
    |---|-------|----------|---------|------------|
-   | 1 | snake_case | event_name | UserLogin | user_login |
+   | 1 | snake_case | event_name | UserLogin | user_login (keep UserLogin only if the user asked to preserve case) |
    | 2 | snake_case | prop_name | vipLevel | vip_level |
    | 3 | invalid type | property "level" | integer | number |
 
@@ -242,7 +242,7 @@ Based on user selection, determine source material type and record to `meta.sour
    - **Events**: Player interaction actions (click/swipe/trigger), scene transitions, game state changes (start/pause/end), business flow nodes (purchase/upgrade/unlock)
    - **Event Properties**: Action parameters (bullet type/enemy level/item ID), state values (score/HP/coins), context (level ID/difficulty/mode)
    - **User Properties**: Persistent state (level/experience/VIP/cumulative spend)
-5. Map extracted results to AE naming conventions (`snake_case` event names + `display_name` in user's language)
+5. Map extracted results to AE naming conventions (event names lowercase by default, uppercase only on request; property names `snake_case`; + `display_name` in user's language)
 6. Confirm extracted results with user, supplement missing items
 
 **Business Dimension Confirmation**:
@@ -386,7 +386,7 @@ When the user selects the **Data sample / file profile** option (`source_type =
 3. **Column → property mapping draft**:
    - Identify system columns first: time field, `distinct_id` / `account_id`, event-name column, user-property-name column.
    - Map the remaining columns to event properties / user properties / super properties.
-   - Naming: `snake_case` event/property names + `display_name` + `desc` + `event_tag` (language follows the user's input).
+   - Naming: `snake_case` property names, event names lowercase by default (uppercase only on request) + `display_name` + `desc` + `event_tag` (language follows the user's input).
    - Type inference: CSV columns default to `string`; infer `number` / `bool` / `datetime` / enum from field name + value distribution + business doc/prompt priors. **Uncertain or conflicting columns are marked "to-confirm" and asked only inside the gate** (do not ask column-by-column beforehand).
 4. **Single confirmation gate** (replaces Phase 2, see below).
 5. **Merge with existing plan** (reuse Phase 4.1/4.2 conflict detection).
@@ -640,7 +640,7 @@ Draft
 }
 ```
 
-> `update_type` is one of: `user_set` (overwrite), `user_setOnce` (first-set-only), `user_add` (numeric accumulate).
+> `update_type` is one of: `user_set` (overwrite), `user_setOnce` (first-set-only), `user_add` (numeric accumulate), `user_append` (array append).
 
 **User identity fields (`meta.user_identity`)**:
 
@@ -656,7 +656,7 @@ Draft
 **Property types** (enum): `string` / `number` / `bool` / `datetime` /
 `object` (single object, with sub-properties) / `array_row` (object array, supports `parent.child` nesting) / `array_string` (string array)
 
-**Naming rules**: Event names / property names must be `snake_case`; use `display_name` field for human-readable names.
+**Naming rules**: Property names must be `snake_case`; event names are lowercase by default, and uppercase is kept only when the user asks to preserve it. Use `display_name` for human-readable names.
 
 ### 1.2 Merge Source Materials
 
@@ -674,9 +674,20 @@ Earlier sources take precedence — same-name events keep the earlier version, l
   - ⚠️ **No model-invented translations for template labels**: When replacing or explaining a localized template-owned label, use the exact value from `src/tracking/i18n` resources. If no corresponding resource exists, preserve the template text and ask the user before changing semantics.
   - ⚠️ **event_tag is not free-form model translation**: Do not manually map `业务事件`/`系统事件` to another language. Preserve template tags, or rely on `src/tracking/i18n` and autotrack generation for system labels when the CLI owns them.
 - **codebase**: Scan project source directory, extract events/properties from business logic; **same-name events merge prop_names without overwriting existing fields**; new items `source: "codebase"`
-- **prd**: Read all user-provided product documents (md / pdf / docx / URL / images), extract events and properties from each file; **same-name events merge prop_names without overwriting existing fields**; image files analyzed via multimodal interpretation of UI elements and interaction flows; all new items `source: "prd"`
+- **prd**: Read all user-provided product documents (md / pdf / docx / xlsx / pptx / URL / images), extract events and properties from each file; **same-name events merge prop_names without overwriting existing fields**; image files analyzed via multimodal interpretation of UI elements and interaction flows; all new items `source: "prd"`
+  - **Read each format with the table below.** Preferred tool first; when it is missing, fall back rather than fail the read.
+    | Format | Read via |
+    |---|---|
+    | md | read directly |
+    | docx | `pandoc -t markdown <file>`; fallback `markitdown <file>` (`pip install markitdown` if missing); last resort `unzip -p <file> word/document.xml` and read the text |
+    | pdf (text) | extract text (native Read or a PDF text extractor) |
+    | pdf (scanned) | render pages to images, then read with vision |
+    | xlsx | read rows/columns with a structure-preserving reader (`openpyxl` / `pandas`, `pip install` if missing); a tracking table's row/column layout carries meaning — do NOT rely on a flattened markdown dump |
+    | pptx | `markitdown <file>` (`pip install markitdown` if missing) |
+    | png/jpg/jpeg/webp | multimodal interpretation, analyze UI elements and interaction flows |
+  - **xlsx is a third source-material path, distinct from the two existing xlsx flows.** A human-readable tracking table (event / property / type rows) is read row-by-row here. An **AE-format tracking-plan xlsx** goes through `import-template`; a **CSV/Excel data sample** goes through the data path (`ae-cli data-integration inspect`). Never route one into another's flow.
   - **prd path is a folder**: Recursively scan all files in the directory:
-    - md/pdf/docx → read text content, extract events/properties
+    - md/pdf/docx/xlsx/pptx → read per the table above, extract events/properties
     - png/jpg/jpeg/webp → multimodal interpretation, analyze UI elements and interaction flows
     - subdirectories → recurse
     - other files → skip
@@ -817,7 +828,8 @@ AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae
 |---|---|---|
 | Display name uniqueness | Within same property pool, `display_name` must not repeat | ✅ Add distinguishing prefix |
 | Object array consistency | Same `array_row` across different events must have identical sub-properties | ✅ Fill missing sub-properties |
-| snake_case | Event/property names must match `^[a-z][a-z0-9_]*$` | ❌ Manual fix needed |
+| Property name snake_case | Property names must match `^[a-z][a-z0-9_]*$` | ❌ Manual fix needed |
+| Event name format | Event names match `^[A-Za-z][A-Za-z0-9_]*$`; lowercase by default, uppercase kept on request | ❌ Manual fix needed |
 | Property name uniqueness | Property names must not repeat | ❌ Manual fix needed |
 | Event name uniqueness | Event names must not repeat | ✅ Remove later duplicates |
 
@@ -1255,7 +1267,7 @@ Continue append (without fixing) / Modify draft / Switch to replace?
 
 #### Conflict Type B: Same-name events (advisory)
 
-AE merge-by-name: Same-name events are not overwritten; new-name events are added.
+AE merge-by-name: Same-name events are not overwritten; new-name events are added. Event names are case-sensitive (`Purchase` ≠ `purchase`) — changing only the case creates a new event, not a rename.
 
 **Detection logic**:
 
@@ -1347,7 +1359,7 @@ AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae
 #### Auto-fix Flow
 
 CLI auto-executes:
-1. Upload xlsx to TE
+1. Upload xlsx to AE
 2. Check if `eventErrorMap` has errors
 3. Fixable errors → auto-fix draft.json → regenerate xlsx → re-upload
 4. Loop up to 3 times; prompt user for manual intervention if exceeded

package/skills/ae-generate-tracking-plan/references/business-dimension-mapping.md

@@ -434,7 +434,7 @@
 
 - 必须有 ≥2 个自定义属性
 - 必须标注事件标签（模块归属）和采集端
-- 命名符合 snake_case
+- 命名符合 snake_case（事件名默认小写，用户要求保留大写时按用户要求）
 
 ---
 

package/skills/ae-generate-tracking-plan/references/te-api.md

@@ -124,6 +124,7 @@ Upload is a two-step capability-gateway flow:
 | `user_set` | 覆盖赋值 |
 | `user_setOnce` | 仅首次赋值 |
 | `user_add` | 数值累加 |
+| `user_append` | 列表追加 |
 
 ## v2（暂未实现）
 

package/skills/ae-generate-tracking-plan/references/xlsx-schema.md

@@ -119,10 +119,11 @@ A-E 在 writer 里用 `mergeCells` 合并。
 | `user_set` | 覆盖赋值（默认） |
 | `user_setOnce` | 仅首次赋值 |
 | `user_add` | 数值累加 |
+| `user_append` | 列表追加 |
 
 xlsx 里填写英文 canonical 值本身，不翻译。
 
-官方文档提及 `user_append`（字符串数组追加），样本中无实例，暂不实现。
+官方模板 `#用户数据` 隐藏说明行「更新方式：取值user_set、user_setOnce、user_add、user_append」已确认 `user_append` 在方案枚举内。`user_unset`（删除属性）不在方案枚举内——它是数据接入层 `#type` 的操作（见 data-rules.md），不是方案声明。
 
 ---
 
@@ -150,5 +151,5 @@ xlsx 里填写英文 canonical 值本身，不翻译。
 ## 开放问题（记一下，不影响 v1）
 
 1. ~~AE 后端是否区分 `object`（单对象）与 `array_row`（对象数组）~~ —— 已确认：AE 支持，wiki/te-docs/raw/preparations-before-data-ingestion.md 明确区分两种类型
-2. `user_append` updateType 是否真的可用 —— 待构造测试
+2. ~~`user_append` updateType 是否真的可用~~ —— 已确认：官方模板 `#用户数据` 隐藏说明行「更新方式：取值user_set、user_setOnce、user_add、user_append」，枚举含 `user_append`（`user_unset` 不在方案枚举内）
 3. 严格错误码 —— 所有校验失败目前都是 `return_code=0 success` + 静默丢弃，无法从响应区分成功/失败；UI 上传才显示错误文案

package/skills/ae-kb/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-kb
 version: 1.0.0
-description: 'AE/TE knowledge base CLI manual for creating, importing read-only compiled snapshots, querying, LLM-powered ask, listing accessible knowledge bases and their sources, deterministic index/grep/read retrieval, checking status, uploading, compiling, schema generation, URL sources, source deletion, and knowledge base deletion. Use when the user asks to manage TE/AE/ThinkingEngine knowledge bases, import a compiled Markdown ZIP snapshot, upload documents or URLs to a knowledge base, query knowledge, ask knowledge bases with an LLM, list accessible knowledge bases or source metadata, inspect knowledge base indexes, search knowledge base pages, read a specific knowledge base page, check knowledge base status, generate schemas, compile knowledge, remove sources, or delete a knowledge base. To choose which knowledge base is worth searching, use the ae-kb-discovery skill first; this skill runs the retrieval once a target is chosen. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source IDs, source display names, JSON payload shapes, or URL formats.'
+description: 'AE knowledge base CLI manual for creating, importing read-only compiled snapshots, querying, LLM-powered ask, listing accessible knowledge bases and their sources, deterministic index/grep/read retrieval, checking status, ZIP source upload and directory management, raw child-file reading, revision-checked child updates and deletion, compiling, schema generation, URL sources, source deletion, file/ZIP source draft replacement and restoration, and knowledge base deletion. Use when the user asks to manage AE (Agentic Engine) knowledge bases, import a compiled Markdown ZIP snapshot, upload documents or URLs to a knowledge base, query knowledge, ask knowledge bases with an LLM, list accessible knowledge bases or source metadata, inspect knowledge base indexes, search knowledge base pages, read a specific knowledge base page, check knowledge base status, generate schemas, compile knowledge, remove sources, or delete a knowledge base. To choose which knowledge base is worth searching, use the ae-kb-discovery skill first; this skill runs the retrieval once a target is chosen. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source IDs, source display names, JSON payload shapes, or URL formats.'
 ---
 
 # ae-kb
@@ -10,12 +10,14 @@ AE CLI (`ae-cli`) knowledge base commands are invoked through:
 
 ```bash
 ae-cli kb +<command> [options]
+ae-cli kb source <replace|restore|preview|commit|cancel|check-updates> [options]
 ```
 
 ## Global Rules
 
-- Use this skill for TE/AE knowledge base tasks: create, import a compiled snapshot, query, ask with LLM, list accessible knowledge bases and their sources, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
+- Use this skill for AE knowledge base tasks: create, import a compiled snapshot, query, ask with LLM, list accessible knowledge bases and their sources, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
 - **Searching a knowledge base for an answer is the most common task. If that is what you are doing, go straight to [Explore Knowledge Base Pages](#explore-knowledge-base-pages) and read [`references/query-workflow.md`](references/query-workflow.md) first — it is the retrieval procedure. The other commands below are for managing knowledge bases, not answering from them.**
+- **When retrieved pages will guide project-scoped business data analysis, read and follow [`references/analysis-workflow.md`](references/analysis-workflow.md) before running any data query. This is mandatory after a KB hit identifies a saved asset, definition, parameter, time rule, conflict, or decision boundary; do not jump directly to ad-hoc analysis or SQL.**
 - Read operations can run directly after required inputs are known. Write operations require explicit user intent and normally keep the confirmation prompt unless the user asks to bypass it.
 - Prefer `--dry-run` before destructive or broad writes when the user has not already validated the target.
 - Do not invent knowledge base names, scopes, source IDs, source display names, or JSON payloads. Ask the user or query known context when values are missing.
@@ -30,17 +32,18 @@ ae-cli kb +<command> [options]
 
 | Command | Risk | Purpose |
 |---|---:|---|
+| `source check-updates` | write | Check one compiled Feishu source with the scheduled detector; mark changes without compiling. |
 | `+ask` | read | LLM-powered Q&A over knowledge bases; for multi-page synthesis or multi-hop questions. |
 | `+ask-status` | read | Query the current status of an ask execution by `--execution-id` without polling. |
 | `+list` | read | List accessible knowledge bases filtered by buildStatus (default: compiled). |
 | `+list-sources` | read | List source metadata for one knowledge base so exact source identifiers can be discovered safely. |
 | `+index` | read | List accessible knowledge bases and their `index.md` navigation maps. |
-| `+grep` | read | Keyword-search knowledge base pages and return matched lines with context. |
+| `+grep` | read | Keyword-search knowledge base pages; returns a page-level results array (hitCount / pageKind / sections previews). |
 | `+read` | read | Read a full knowledge base page, a line window, or (with `--outline`) only the page heading tree. |
 | `+new` | write | Create a new personal or company knowledge base. |
-| `+import` | write | Import a compiled Markdown ZIP as a personal read-only snapshot. |
-| `+import-status` | read | Query one snapshot import task by `--request-id` without polling. |
-| `+add` | write | Upload local files, a non-recursive directory, or HTTP(S) pages converted to markdown. |
+| `+import` | write | Import a compiled Markdown ZIP as a personal or company read-only snapshot; `--scope` defaults to `personal`. |
+| `+import-status` | read | Query one snapshot import task by `--request-id` without polling; output includes the persisted `scope`. |
+| `+add` | write | Upload local files (including ZIP directory sources), a non-recursive directory, or HTTP(S) pages converted to markdown. |
 | `+url` | write | Upload a URL source directly with optional display name and parsing instruction. |
 | `+schema` | write | Generate the compile schema for a knowledge base. |
 | `+compile` | write | Compile a knowledge base in incremental or full mode. |
@@ -48,6 +51,81 @@ ae-cli kb +<command> [options]
 | `+rm-source` | high-risk-write | Delete one source from a knowledge base by stable ID; exact display name is legacy compatibility only. |
 | `+remove` | write | Delete an entire knowledge base. |
 
+## Published Version History
+
+Use the nine version commands described in [`references/versions.md`](references/versions.md) to inspect immutable published history, compare source changes, and explicitly roll back an earlier version as a new publication. These commands manage history; `+index/+grep/+read/+ask` continue to use current published content.
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `+versions` | read | List published versions and latestVersionId. |
+| `+version-show` | read | Show one version summary. |
+| `+version-sources` | read | Discover historical source IDs. |
+| `+version-diff` | read | Compare two versions. |
+| `+version-tree` | read | List a historical ZIP/URL source directory. |
+| `+version-read` | read | Preview a historical directory child file. |
+| `+version-download` | read | Save one ordinary historical file source; no directory download. |
+| `+rollback` | high-risk-write | Restore an earlier version and create a new version. |
+| `+rollback-status` | read | Query a persisted rollback Operation without polling. |
+
+## Source Draft Replacement and Restoration
+
+Use [`references/source-mutations.md`](references/source-mutations.md) for file/ZIP source replacement and restoration. These new commands use `kb source <action>`; `+rollback` remains a whole-KB publication operation.
+
+| Command | Risk | Purpose |
+|---|---|---|
+| `source replace` | write | Replace an ordinary file draft, or prepare a ZIP archive replacement preview. |
+| `source restore` | write | Restore a file draft from a published version, or prepare a ZIP source/child restore preview. |
+| `source preview` | read | Read a page of ZIP candidate changes before confirmation. |
+| `source commit` | high-risk-write | Confirm a reviewed ZIP candidate, including any deletions. |
+| `source cancel` | high-risk-write | Discard an uncommitted ZIP candidate. |
+
+Require exact `--name`, `--scope`, current `--id`, and a current `--expected-revision` for mutations. File replacements keep the original format but allow different filenames. ZIP requires `.zip`. URL/Feishu and deleted parent sources are not supported. Updates affect the draft only; publication still requires compilation. ZIP previews must not be auto-committed. Do not retry uncertain writes.
+
+## ZIP Directory Sources
+
+Use `+add --files '["./sources.zip"]'` to upload one ZIP as one editable parent source, preserving its internal hierarchy. Archive validation and limits are enforced by the server. This is different from `+import`, which creates a read-only compiled snapshot. Passing a local directory to `+add` still uploads only its immediate supported files; it does not recursively package that directory.
+
+Discover the exact parent ID with `+list-sources`. ZIP rows include `fileCount`, `sizeBytes`, `contentRevision`, and `updateStatus`.
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `+source-ls` | read | List one directory page with revision, current children and deleted paths relative to the successful baseline. |
+| `+source-read` | read | Read a child source file as UTF-8/base64, or save original bytes. |
+| `+source-put` | write | Add one local file or explicitly replace the exact ZIP-relative path. |
+| `+source-rm` | high-risk-write | Delete one child file or recursively delete a child directory. |
+
+```bash
+ae-cli kb +source-ls --name handbook --id <source-id> --path "" --limit 100
+ae-cli kb +source-ls --name handbook --id <source-id> --path "guides" --cursor <nextCursor>
+ae-cli kb +source-read --name handbook --id <source-id> --path "guides/intro.md"
+ae-cli kb +source-read --name handbook --id <source-id> --path "images/chart.png" --output ./chart.png
+ae-cli kb +source-read --name handbook --id <source-id> --path "images/chart.png" --encoding base64
+ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./new.md --action add --expected-revision 7 --dry-run
+ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./new.md --action add --expected-revision 7
+ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./revised.md --action replace --expected-revision 8
+ae-cli kb +source-rm --name handbook --id <source-id> --path "guides/new.md" --expected-revision 9
+ae-cli kb +source-rm --name handbook --id <source-id> --path "guides/obsolete" --recursive --expected-revision 10
+ae-cli kb +compile --name handbook --mode incremental
+```
+
+- Copy the source ID, paths and revision from current discovery. Names resolve personal then company, following the existing External API; no scope override is available on these commands.
+- `--path` is relative to the ZIP root, not a local filesystem or `raw/zip/...` path. Root listing uses an empty path. Nonempty paths cannot be absolute or contain empty, dot, parent or backslash segments.
+- Listing returns one page; continue using `nextCursor` and the same path. On a revision change, restart discovery before writing.
+- `+source-read` reads source bytes; `+read` reads compiled Wiki pages. Default UTF-8 output fails on invalid UTF-8. Base64 preserves binary data. `--output` creates a new local file and refuses to overwrite an existing file.
+- `+source-put` accepts one file up to 50 MB. Default `--action add` rejects an existing path; `--action replace` explicitly authorizes overwriting an existing child. There is no silent upsert. Dry-run shows metadata and redacts file content.
+- `--expected-revision` is mandatory for writes. A 409 conflict is returned with its server error code; the command never refreshes and retries the write automatically.
+- `+source-rm` keeps the parent source. Nonempty directory removal requires `--recursive`; deletion follows the CLI confirmation gate. Use `--yes` only when automated deletion of the exact target is already authorized. `+rm-source --id` deletes the entire parent.
+- A mutation marks the parent changed but does not start compilation or regenerate Schema. Run incremental compilation explicitly; wait for successful publication before the next test stage.
+- `+status` is the existing aggregate status query; it is not a per-run event or ZIP Diff reader. Do not interpret its compilation submission response as successful publication.
+- No Gateway equivalent is registered in the current KB implementation. These commands reuse the typed External source APIs.
+
+Transition status: transitional
+Owning module: te-claude External Knowledge Base Sources API
+Current transport: authenticated External REST via `kbApi` and multipart `kbUpload`.
+Gateway target: TBD (ZIP source directory and raw-file capabilities)
+Review after: 2026-12-06
+Exit condition: migrate when equivalent typed Gateway file, directory and revision-aware mutation capabilities exist; retain CLI file handling and explicit mutation semantics.
+
 ## Common Workflows
 
 ### Create a Knowledge Base
@@ -107,6 +185,7 @@ Use `+add` when sources are local files, local directories, or pages that should
 ```bash
 ae-cli kb +add \
   --name engineering-handbook \
+  --scope company \
   --files '["./README.md","./docs","https://example.com/guide"]'
 ```
 
@@ -125,6 +204,7 @@ Use `+url` when adding one URL source and optionally passing a display name or p
 ```bash
 ae-cli kb +url \
   --name engineering-handbook \
+  --scope company \
   --url https://example.com/guide \
   --display-name guide \
   --parse-instruction "Keep headings and code blocks"
@@ -137,16 +217,20 @@ ae-cli kb +url \
 Generate the schema first when the knowledge base needs a compile schema.
 
 ```bash
-ae-cli kb +schema --name engineering-handbook
+ae-cli kb +schema --name engineering-handbook --scope company
 ```
 
-Use `--force` only when `+status` reports `schema_generating` and the user explicitly wants to replace the current generation attempt. The replacement may consume additional tokens. Use `--model` only when the user provides the model display name.
+Use `--force` only when `+status` reports `schema_generating` and the user explicitly wants to replace the current generation attempt. The replacement may consume additional tokens.
+
+Schema and Compile accept the same optional model reference. Prefer the model record `id` returned by `ae-cli agent +list-models` (`Model.id`). Historical `modelId` and the unambiguous `modelId::scope` form remain compatible. A model `displayName` is presentation text, not a stable reference.
 
 To add one-time guidance for this generation without changing stored knowledge base metadata, pass `--custom-instructions`. The server trims the value, treats whitespace-only input as absent, and accepts up to 10,000 Unicode characters. Do not include secrets or credentials.
 
 ```bash
 ae-cli kb +schema \
   --name engineering-handbook \
+  --scope company \
+  --model <model-ref> \
   --custom-instructions "Prioritize troubleshooting workflows and preserve command examples"
 ```
 
@@ -155,7 +239,7 @@ Use `--dry-run` to inspect the request body before sending it. While generation
 Compile after sources and schema are ready:
 
 ```bash
-ae-cli kb +compile --name engineering-handbook --mode incremental
+ae-cli kb +compile --name engineering-handbook --scope company --mode incremental --model <model-ref>
 ```
 
 Valid compile modes are `incremental` and `full`; default is `incremental`.
@@ -165,14 +249,14 @@ Valid compile modes are `incremental` and `full`; default is `incremental`.
 Use `+status` to inspect the current status of a knowledge base.
 
 ```bash
-ae-cli kb +status --name engineering-handbook
+ae-cli kb +status --name engineering-handbook --scope company
 ```
 
 ### Ask Knowledge (LLM)
 
 Use `+ask` when the question requires synthesizing across multiple pages or multi-hop reasoning — a server-side agent runs the full retrieval loop and returns a synthesized answer with its source paths. Prefer `+index` -> `+grep` -> `+read` when deterministic retrieval is enough.
 
-The `+ask` command uses asynchronous submit/poll: by default, it automatically polls for completion (every 5s, up to 10 minutes) and prints the final answer. The output JSON is isomorphic to the previous synchronous response, so consumers require no changes.
+The `+ask` command uses asynchronous submit/poll: by default, it automatically polls for completion (every 5s, up to 10 minutes) and prints the final answer with its execution ID, sources, model usage, tool call count, and model ID.
 
 ```bash
 # Default: submit and poll for completion
@@ -180,7 +264,6 @@ ae-cli kb +ask \
   --question "How do we troubleshoot payment alerts?" \
   --sources '[{"scope":"company","name":"engineering-handbook"}]' \
   --model-id claude-sonnet-4-6 \
-  --max-turns 50 \
   --locale zh
 
 # Submit only, return executionId immediately (for batch processing)
@@ -193,10 +276,9 @@ ae-cli kb +ask-status --execution-id <id>
 - `--question`, alias `-q`: required natural-language question (1-2000 characters).
 - `--sources`: optional JSON array of knowledge base refs. Omit to search all accessible knowledge bases.
 - `--model-id`: optional LLM model ID. Omit to use the platform default.
-- `--max-turns`: optional agent turn limit (1-100, server default 50).
 - `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
 - `--no-wait`: optional boolean flag. Return immediately after submission with `{executionId, status}`, without polling.
-- **Failure handling**: If execution fails, the command exits non-zero and prints an error message on stderr prefixed with the typed error code, e.g. `[timeout] ...` / `[model_error] ...` / `[invalid_sources] ...` (followed by the executionId). Treat the bracketed code as the machine-readable failure type.
+- **Failure handling**: If execution fails, the command exits non-zero and prints the unified JSON error envelope on stderr: `{"ok":false,"error":{"type":"api","code":"<server-code>","message":"..."}}`. Stable server codes are `model_unavailable`, `sandbox_unavailable`, `agent_skill_unavailable`, `dispatch_auth_unavailable`, `provider_failed`, `retrieval_error`, `timeout`, and `process_restart`.
 
 ### List Accessible Knowledge Bases
 
@@ -225,7 +307,7 @@ ae-cli kb +index \
   --sources '[{"scope":"company","name":"engineering-handbook"}]'
 ```
 
-Then use `+grep` to locate likely pages and line numbers:
+Then use `+grep` to locate likely pages:
 
 ```bash
 ae-cli kb +grep \
@@ -235,7 +317,7 @@ ae-cli kb +grep \
   --top-k 10
 ```
 
-Each grep hit carries `path`, `line`, `breadcrumb`, a context snippet, and the section range of the matched line (`sectionStartLine` / `sectionEndLine`). `line` is the hit anchor; `sectionStartLine` / `sectionEndLine` are the enclosing heading-section boundaries. Choose the smallest reliable `--offset` / `--limit` window that preserves the needed evidence; use the section range when the answer needs whole-section context.
+The response is a page-level `results` array: each entry is one page with its full `hitCount`, a `pageKind` (`content` or `catalog`), up to 4 `sections` previews (breadcrumb, `sectionStartLine`/`sectionEndLine`, text preview), and `moreSections`. Use `hitCount` and the previews to decide which pages to read; `pageKind: "catalog"` marks a module directory page — treat its entries as detail-page navigation, not as an answer source. Read the section range with `--offset sectionStartLine` / `--limit sectionEndLine - sectionStartLine + 1`; when `moreSections > 0` and the answer is not in the previews, re-grep that single page to see all its hits.
 
 Use `+read --outline` when the current target page has no reliable grep range and headings are needed to choose a section:
 
@@ -246,14 +328,15 @@ ae-cli kb +read \
   --outline
 ```
 
-Then use `+read` to open the selected window, using the hit anchor, a section boundary from same-page or linked-page grep, or two adjacent outline headings:
+Then use `+read` to open the selected window, using a page-group section boundary or two adjacent outline headings:
 
 ```bash
 ae-cli kb +read \
   --source '{"scope":"company","name":"engineering-handbook"}' \
   --path "wiki/sandbox.md" \
   --offset 42 \
-  --limit 60
+  --limit 60 \
+  --expand block
 ```
 
 ### List Sources
@@ -261,7 +344,7 @@ ae-cli kb +read \
 List sources first to discover the stable identifier for the intended source:
 
 ```bash
-ae-cli kb +list-sources --name engineering-handbook
+ae-cli kb +list-sources --name engineering-handbook --scope company
 ```
 
 Copy the exact `id` from the response into `+rm-source`. Do not guess a source ID from a local filename, URL, display name, or an older upload response.
@@ -280,6 +363,7 @@ Use `+rm-source --id` with the exact ID returned by the current `+list-sources`
 ```bash
 ae-cli kb +rm-source \
   --name engineering-handbook \
+  --scope company \
   --id cm-source-id
 ```
 
@@ -298,7 +382,7 @@ If the user only gives a loose source name, do not guess a source ID. Run `+list
 Use `+remove` for deleting the entire knowledge base. Confirm the target name with the user if there is any ambiguity.
 
 ```bash
-ae-cli kb +remove --name engineering-handbook
+ae-cli kb +remove --name engineering-handbook --scope company
 ```
 
 ## Command Reference
@@ -306,17 +390,16 @@ ae-cli kb +remove --name engineering-handbook
 ### `+ask`
 
 ```bash
-ae-cli kb +ask --question "<question>" [--sources '[{"scope":"company","name":"kb-name"}]'] [--model-id claude-sonnet-4-6] [--max-turns 50] [--locale zh|en|ja|ko] [--no-wait]
+ae-cli kb +ask --question "<question>" [--sources '[{"scope":"company","name":"kb-name"}]'] [--model-id claude-sonnet-4-6] [--locale zh|en|ja|ko] [--no-wait]
 ```
 
 - `--question`, alias `-q`: required natural-language question (1-2000 characters).
 - `--sources`: optional JSON array of knowledge base refs. Omit to search all accessible knowledge bases.
 - `--model-id`: optional LLM model ID. Omit to use the platform default.
-- `--max-turns`: optional agent turn limit (1-100, server default 50).
 - `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
 - `--no-wait`: optional. Return immediately with `{executionId, status}` instead of polling.
 - When to use: multi-page synthesis or multi-hop questions. For simple factual lookups, prefer `+index` / `+grep` / `+read`.
-- Output: By default, polls and returns `{executionId, answer, sources, modelUsage, toolCallCount, maxTurns, modelId}` (same fields as the previous synchronous response, plus `executionId`). With `--no-wait`, returns `{executionId, status}` immediately. On failure, exits non-zero with a stderr message prefixed by the typed error code (`[timeout]`, `[model_error]`, `[invalid_sources]`, `[process_restart]`).
+- Output: By default, polls and returns `{executionId, answer, sources, modelUsage, toolCallCount, modelId}`. With `--no-wait`, returns `{executionId, status}` immediately. On failure, exits non-zero with the unified stderr envelope containing `error.type="api"`, the server `error.code` (`model_unavailable`, `sandbox_unavailable`, `agent_skill_unavailable`, `dispatch_auth_unavailable`, `provider_failed`, `retrieval_error`, `timeout`, or `process_restart`), and `error.message`.
 
 ### `+ask-status`
 
@@ -325,7 +408,7 @@ ae-cli kb +ask-status --execution-id <id>
 ```
 
 - `--execution-id`: required. The execution ID returned by `+ask` submission.
-- Output: Returns the current execution state: `{executionId, status, elapsedMs?, answer?, sources?, modelUsage?, toolCallCount?, error?}`. Does not poll; returns a single snapshot.
+- Output: Returns one successful CLI envelope snapshot. For a failed execution, the stable server code remains at `data.error.code`: `{"ok":true,"data":{"executionId":"...","status":"failed","error":{"code":"retrieval_error","message":"..."}}}`. Does not poll.
 
 ### `+list`
 
@@ -357,18 +440,19 @@ ae-cli kb +grep --query "<keywords>" --sources '[{"scope":"company","name":"kb-n
 - `--paths`: required JSON array of wiki pages or subdirectories **copied** from `+index`. A single page is still an array, e.g. `["wiki/sandbox.md"]`. Distinct from `+read --path` (one string).
 - `--top-k`: optional max number of hits, 1-50, default 10.
 - `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
-- Each hit includes `sectionStartLine` / `sectionEndLine`: the line range of the section (bounded by the nearest headings) containing the matched line. Use it as the `+read` window.
+- Each page entry in results carries `hitCount` (full match count), `pageKind`, and `sections` previews with `sectionStartLine` / `sectionEndLine` — use the section range as the `+read` window.
 
 ### `+read`
 
 ```bash
-ae-cli kb +read --source '{"scope":"company","name":"kb-name"}' --path "index.md" [--offset 1] [--limit 200] [--outline] [--locale zh|en|ja|ko]
+ae-cli kb +read --source '{"scope":"company","name":"kb-name"}' --path "index.md" [--offset 1] [--limit 200] [--expand block|none] [--outline] [--locale zh|en|ja|ko]
 ```
 
 - `--source`: required JSON object pointing to exactly one knowledge base.
 - `--path`: required page path relative to the knowledge base root, such as `index.md` or `wiki/concepts/data-model.md`.
-- `--offset`: optional 1-based start line.
-- `--limit`: optional max line count, 1-10000.
+- `--offset`: optional 1-based integer start line.
+- `--limit`: optional max line count, 1-2000.
+- `--expand`: optional Markdown block expansion mode. `block` lets the server include a complete Markdown block outside the requested line window; `none` keeps the exact offset/limit window. Omit it to use the server default, `block`.
 - `--outline`: optional. Return only the whole-page heading tree (`{level, heading, line}`) with empty content, independent of `--offset` / `--limit`. Use it on long pages to choose which section to read.
 - `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
 
@@ -381,7 +465,7 @@ ae-cli kb +new --name "<name>" [--scope personal|company] [--description "..."]
 ### `+add`
 
 ```bash
-ae-cli kb +add --name "<name>" --files '["./a.md","./docs","https://example.com/page"]'
+ae-cli kb +add --name "<name>" --files '["./a.md","./docs","https://example.com/page"]' [--scope personal|company]
 ```
 
 ### `+import`
@@ -411,46 +495,50 @@ ae-cli kb +import-status --request-id <requestId>
 ### `+url`
 
 ```bash
-ae-cli kb +url --name "<name>" --url "https://example.com/page" [--display-name "..."] [--parse-instruction "..."]
+ae-cli kb +url --name "<name>" --url "https://example.com/page" [--scope personal|company] [--display-name "..."] [--parse-instruction "..."]
 ```
 
 ### `+schema`
 
 ```bash
-ae-cli kb +schema --name "<name>" [--force] [--model "<model displayName>"] [--custom-instructions "<one-time guidance>"]
+ae-cli kb +schema --name "<name>" [--scope personal|company] [--force] [--model <model-ref>] [--custom-instructions "<one-time guidance>"]
 ```
 
 - `--custom-instructions`: Optional per-run schema-generation guidance. It is not persisted; whitespace-only input is omitted. The server allows at most 10,000 Unicode characters and rejects disallowed control characters. Do not include secrets or credentials.
 - `--force`: Replace the current attempt only when schema generation is already running and the user explicitly requests the replacement. The selected model and custom instructions apply to the new attempt, which may consume additional tokens.
 - `--dry-run`: Shows the same `customInstructions` request field that execution will send.
+- `--model`: Optional stable model reference. Prefer `Model.id` from `ae-cli agent +list-models`; historical `modelId` and `modelId::scope` remain compatible.
+- `--scope`: Optional exact knowledge-base scope. Omit it to retain the legacy personal-to-company lookup order.
 - Errors: `KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID` means the field failed validation. `KB_SCHEMA_GENERATION_IN_PROGRESS` means generation is active and a request without `--force` supplied a new model or effective custom instructions.
 
 ### `+compile`
 
 ```bash
-ae-cli kb +compile --name "<name>" [--mode incremental|full]
+ae-cli kb +compile --name "<name>" [--scope personal|company] [--mode incremental|full] [--model <model-ref>]
 ```
 
 ### `+status`
 
 ```bash
-ae-cli kb +status --name "<name>"
+ae-cli kb +status --name "<name>" [--scope personal|company]
 ```
 
 ### `+list-sources`
 
 ```bash
-ae-cli kb +list-sources --name "<name>"
+ae-cli kb +list-sources --name "<name>" [--scope personal|company]
 ```
 
 - `--name`: required knowledge base name.
-- Output: Safe source metadata including the stable `id` needed by `+rm-source`; raw paths, hashes, credentials, and source content are not returned.
+- Output: `items` contains effective sources with stable `id`. `pendingDeletions` contains soft-deleted sources still included in the current successful version. `deletionMaintenance` is separate and may report already-published deletions awaiting cleanup. Paths, hashes, credentials, and source content are not returned.
+- Check `deletionProjection.state` and its `baseline` before interpreting deletion lists. `ready` with `pendingDeletions: []` means no pending deletion at that baseline. `changing`, `review_required`, or `unavailable` with `pendingDeletions: null` means undetermined; display the `reasonCode`, never turn null into an empty list. Legacy libraries without a verifiable complete publication manifest return unavailable until a real version is published.
+- A rollback creates a new current version. An older deletion receipt cannot override membership in that version. A later source deletion needs publication again.
 - Copy the exact `id` from the current response before deleting a source; never guess it.
 
 ### `+rm-source`
 
 ```bash
-ae-cli kb +rm-source --name "<name>" --id "<source-id>"
+ae-cli kb +rm-source --name "<name>" --id "<source-id>" [--scope personal|company]
 ```
 
 - `--id`: preferred stable source identifier copied from `+list-sources`.
@@ -460,5 +548,27 @@ ae-cli kb +rm-source --name "<name>" --id "<source-id>"
 ### `+remove`
 
 ```bash
-ae-cli kb +remove --name "<name>"
+ae-cli kb +remove --name "<name>" [--scope personal|company]
+```
+
+## Check a Feishu source for updates
+
+```bash
+ae-cli kb source check-updates --name "Engineering Handbook" --id "<source-id>" --scope company --dry-run
+ae-cli kb source check-updates --name "Engineering Handbook" --id "<source-id>" --scope company
 ```
+
+Copy the ID from `kb +list-sources`. Requires source write permission. Only compiled, non-deleted Feishu URL sources are eligible. The API uses the same detector as the scheduled task, including existing pending-change skips and source-owner sandbox credentials. It never starts compilation or clears pending changes.
+
+The synchronous response contains `sourceId`, `scanned`, `updated`, `failed`, `urlChangeState`, and `updateStatus`. `scanned` counts candidates, not completed content comparisons; `updated` counts newly marked sources. Zero updates can mean unchanged content, an already pending change, unavailable old raw, or a concurrent state change. It must not be reported as proof that all content is identical. Failed checks return a non-2xx response and a CLI error. A timeout does not prove completion or cancellation; read `kb +list-sources` before deciding whether to retry.
+
+Transport: `POST /agent/api/external/knowledge-bases/sources/check-updates`, body `{name, sourceId, scope?}`. `--dry-run` only previews the request and does not authenticate or check remote permissions.
+
+### Admission record: source check-updates
+
+- Classification: Transitional (no Gateway equivalent for this new detector trigger).
+- Owning module: te-claude knowledge-base source management.
+- Current transport: KB external REST through `kbApi` and CLI token.
+- Gateway target: TBD; reuse an equivalent source update-check capability when available.
+- Review after: 2026-10-16.
+- Exit condition: once the Gateway exposes equivalent authorization and detector semantics, migrate the typed command to L2 or use L3 if it adds no value.