@thinkingai/ae-cli 6.1.18 → 6.1.20

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, querying, LLM-powered ask, listing accessible knowledge bases, 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, upload documents or URLs to a knowledge base, query knowledge, ask knowledge bases with an LLM, list accessible knowledge bases, 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 display names, JSON payload shapes, or URL formats."
+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, ZIP source upload and directory management, raw child-file reading, revision-checked child updates and deletion, 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.'
 ---
 
 # ae-kb
@@ -14,11 +14,11 @@ ae-cli kb +<command> [options]
 
 ## Global Rules
 
-- Use this skill for TE/AE knowledge base tasks: create, query, ask with LLM, list accessible knowledge bases, 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 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.
 - **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.**
 - 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 display names, or JSON payloads. Ask the user or query known context when values are missing.
+- 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.
 - When building a `--sources` ref (or `+read --source`), copy the exact `scope` and `name` from `+list` output — run `ae-cli kb +list` first when the scope of a named knowledge base is unknown.
 - JSON flags must be valid JSON strings, usually wrapped in single quotes in shell commands.
 - Successful commands return JSON by default. Use `--format table` only when a table is easier for a human to scan. Envelope may include optional `_notice.host_compat`.
@@ -33,18 +33,82 @@ ae-cli kb +<command> [options]
 | `+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. |
-| `+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. |
 | `+status` | read | Query the current status of a knowledge base. |
-| `+rm-source` | write | Delete one source file from a knowledge base by display name. |
+| `+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. |
+
+## 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
@@ -67,6 +131,36 @@ Optional fields:
 - `--project-id`: optional project ID to bind.
 - `--project-name`: optional project display name.
 
+### Import a Compiled Snapshot
+
+Use `+import` only for a ZIP whose root contains `index.md` and at least one
+`wiki/**/*.md` page. The server validates all archive paths, limits, UTF-8 text, and Wiki links.
+
+```bash
+ae-cli kb +import \
+  --file ./knowledge-base.zip \
+  --name "Imported handbook" \
+  --description "Compiled documentation snapshot" \
+  --tags '["docs","handbook"]'
+
+# The submission returns requestId + queued. Query one snapshot later:
+ae-cli kb +import-status --request-id <requestId>
+```
+
+- The result is always a `personal` read-only snapshot; there is no `--scope`, `--force`, or replace option.
+- Imported snapshots support list, Index/Wiki reading, grep/read, Ask, and deletion. They do not expose source, Schema, usage, compile, member, settings, ownership-transfer, or company-publish operations.
+- The ZIP is limited to 50 MB and supports Markdown text only. Local images, attachments, other binaries, broken Wiki links, and ambiguous Wiki links are rejected by the server.
+- Submission returns `{requestId, status: "queued"}` immediately. It does not wait for ZIP validation or publication.
+- `+import-status` returns one of `queued`, `running`, `succeeded`, or `failed`; success includes `knowledgeBaseId`, and failure includes a stable error code/message.
+- If a `requestId` was returned, query it before retrying. If no request ID was received, run `ae-cli kb +list` before retrying the same name. A repeated same-name import is rejected.
+
+- Transition status: transitional
+- Owning module: te-claude External Knowledge Base Import API
+- Current transport: authenticated KB external REST through `kbUpload` for submission and `kbApi` for status lookup.
+- Gateway target: TBD (`kb.snapshot.import` proposed)
+- Review after: 2026-12-01
+- Exit condition: migrate to a typed Gateway capability when the equivalent multipart import capability is available, or remove this command if dynamic Gateway execution provides the same file-handling and output contract.
+
 ### Upload Files or Directories
 
 Use `+add` when sources are local files, local directories, or pages that should be fetched and converted to markdown before upload.
@@ -74,6 +168,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"]'
 ```
 
@@ -92,6 +187,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"
@@ -104,15 +200,29 @@ 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 to recover a stuck `generating` status. 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"
+```
+
+Use `--dry-run` to inspect the request body before sending it. While generation is running, a request without `--force` is idempotent only when it supplies no new model or effective custom instructions; otherwise it fails with `KB_SCHEMA_GENERATION_IN_PROGRESS`. With `--force`, the selected model and custom instructions apply to the replacement attempt. Invalid text fails with `KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID`.
 
 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`.
@@ -122,14 +232,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
@@ -137,7 +247,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)
@@ -150,10 +259,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
 
@@ -182,7 +290,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 \
@@ -192,7 +300,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:
 
@@ -203,19 +311,46 @@ 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
+
+List sources first to discover the stable identifier for the intended source:
+
+```bash
+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.
+
+- Transition status: transitional
+- Owning module: te-claude External Knowledge Base Sources API
+- Current transport: authenticated KB external REST through `kbApi`.
+- Gateway target: TBD (`kb.source.list` proposed)
+- Review after: 2026-12-03
+- Exit condition: migrate to a typed Gateway capability when an equivalent source-list capability is available, or remove this command if dynamic Gateway execution provides the same discoverability and safe output contract.
+
 ### Remove One Source
 
-Use `+rm-source` only when the source display name is known exactly.
+Use `+rm-source --id` with the exact ID returned by the current `+list-sources` response. This is a `high-risk-write`; keep the interactive confirmation unless the user has explicitly authorized `--yes`.
+
+```bash
+ae-cli kb +rm-source \
+  --name engineering-handbook \
+  --scope company \
+  --id cm-source-id
+```
+
+`--display-name` is retained for legacy compatibility only when a stable source ID is unavailable:
 
 ```bash
 ae-cli kb +rm-source \
@@ -223,14 +358,14 @@ ae-cli kb +rm-source \
   --display-name kb-1780046712-guide.md
 ```
 
-If the user only gives a loose source name, do not guess. Ask for the exact uploaded display name.
+If the user only gives a loose source name, do not guess a source ID. Run `+list-sources`, identify the intended row from returned metadata, and ask only when multiple rows remain ambiguous.
 
 ### Delete a Knowledge Base
 
 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
@@ -238,17 +373,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`
 
@@ -257,7 +391,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`
 
@@ -289,18 +423,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`.
 
@@ -313,41 +448,88 @@ 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`
+
+```bash
+ae-cli kb +import --file "./knowledge-base.zip" --name "<name>" [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."]
+```
+
+- `--file`: required local `.zip` file.
+- `--name`: required personal knowledge-base name, up to 30 characters.
+- `--description`: optional, up to 200 characters.
+- `--tags`: optional JSON array, max 2 unique tags, each up to 15 characters.
+- `--project-id`: optional project binding.
+- Scope and terminal build state are generated by the server and cannot be supplied by the client.
+- Output: `{requestId, status: "queued"}`. Use `+import-status`; the command does not poll.
+
+### `+import-status`
+
+```bash
+ae-cli kb +import-status --request-id <requestId>
 ```
 
+- `--request-id`: required ID returned by `+import`.
+- Output: `{requestId, status, knowledgeBaseId?, errorCode?, errorMessage?}`.
+- Returns a single snapshot and does not poll. A failed import is returned as `status: "failed"` with its stable error code/message; an unknown or inaccessible request exits non-zero.
+
 ### `+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>"]
+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>" [--scope personal|company]
+```
+
+- `--name`: required knowledge base name.
+- 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>" --display-name "<uploaded source display name>"
+ae-cli kb +rm-source --name "<name>" --id "<source-id>" [--scope personal|company]
 ```
 
+- `--id`: preferred stable source identifier copied from `+list-sources`.
+- `--display-name`: legacy compatibility selector used only when an ID is unavailable.
+- If both are supplied, `--id` wins. The command removes one source only.
+
 ### `+remove`
 
 ```bash
-ae-cli kb +remove --name "<name>"
+ae-cli kb +remove --name "<name>" [--scope personal|company]
 ```

package/skills/ae-kb/references/query-workflow.md

@@ -20,7 +20,12 @@ candidate rather than searching everything blindly.
 1. **Index the candidate.** Call `+index --sources` with the discovery pick.
    Use `index.md` for navigation, a fit check, and **query wording** — the real
    terms in the index (product names, API identifiers, section titles) become
-   your `+grep` keywords.
+   your `+grep` keywords. The root index routes at module level only; when a
+   module is too coarse for your question (it has many detail pages), read that
+   module's catalog page (`wiki/modules/<module>/catalog.md`) — it groups
+   detail pages by topic with one-line summaries. **Copy** detail-page paths
+   from the catalog as additional `--paths` candidates; the catalog itself is
+   navigation, not an answer source.
 
    **Done when:** you have the candidate's `index.md`, and a list of `wiki/...`
    links you can **copy** (0 items still counts as done).
@@ -29,36 +34,52 @@ candidate rather than searching everything blindly.
    such as `wiki/sandbox.md`, or a subdirectory such as `wiki/guides`). Call
    `+grep` with the candidate `--sources` and the copied list as `--paths`. Search
    with the index terms. If the first grep misses, rewrite the query **once**
-   using different index terms — still with this same `--paths` — then stop
-   rewriting.
+   using different index terms **only** — never paraphrase the user's wording
+   from memory — still with this same `--paths`. If the rewrite also misses,
+   stop grepping entirely: `+read --outline` the index page whose title or
+   section name relates to the question and read the matching heading range
+   from it. A third rewrite of the same idea produces no new recall.
 
    **Done when:** you have hits, or you have rewritten once, or step 1 copied
    0 paths. Copied 0 paths → skip grep and `+read --outline` the likeliest
    title page, or go back to discovery for the next candidate.
 
-   A grep hit gives both a hit anchor and its enclosing section range:
-
-   - `line` is the exact matched line. Use it as the anchor when the evidence
-     is local.
-   - `sectionStartLine` / `sectionEndLine` are the enclosing heading-section
-     boundaries. Use them when the answer needs the whole section context, or
-     as the maximum boundary when choosing a smaller window.
+   **Reading the result — the page-level `results` view.** The response is a page-level
+   `results` array: each entry is one page with its full `hitCount`, a
+   `pageKind`, and up to 4 `sections` previews (each with its breadcrumb,
+   `sectionStartLine`/`sectionEndLine`, and a text preview). Read the top
+   relevant pages until every subquestion of the question is backed by
+   sections you have actually read. `hitCount` tells you how dense the matches
+   are on a page; `pageKind: "catalog"` marks a module directory page — its
+   previews are detail-page entries, so treat them as navigation: add the
+   detail-page paths you see there to your read list instead of reading the
+   catalog as an answer source. When a page has `moreSections > 0` and the
+   answer is not in the previews, re-grep that single page to see all its
+   hits.
+
+   Each page-group section preview carries its enclosing heading-section
+   boundaries:
+
+   - `sectionStartLine` / `sectionEndLine` are the section boundaries. Use
+     them as the read window (or as the maximum boundary when choosing a
+     smaller window under them).
    - `+read --offset` / `--limit` are the actual read window. Choose the
      smallest reliable window that preserves the needed evidence; do not
      shell-truncate with `| head`.
+   - `+read --expand block` may include the rest of a Markdown block just
+     outside the requested window. Use `+read --expand none` when the line
+     window must be exact. Omit the flag to keep the server default, `block`.
 
 3. **Choose the section locator.** Pick one locator for the current target
    page:
 
-   - **Same-page grep hit:** choose a read window from the hit. For narrow
-     fact/table/code evidence, read a bounded window anchored at `line`; stay
-     within `sectionStartLine`–`sectionEndLine`. For section-level meaning,
-     field definitions, caveats, or rows that depend on the heading context,
-     read the section range with
+   - **Section preview of a page group:** read the section range with
      `--offset sectionStartLine` and
-     `--limit sectionEndLine - sectionStartLine + 1`. If the first window is
-     too small, widen once up to the section range. Do not crawl by shifting
-     offsets line by line.
+     `--limit sectionEndLine - sectionStartLine + 1`. For narrow
+     fact/table/code evidence, narrow the window under the section boundary
+     once you see the preview text. If the window turns out too small, widen
+     once up to the section range. Do not crawl by shifting offsets line by
+     line.
    - **Linked or related page:** if you follow a catalog/detail/related link to
      a different page, the old grep range no longer applies. If you have
      concrete terms for that new page, run `+grep --paths '["<new-page>"]'`
@@ -78,32 +99,41 @@ candidate rather than searching everything blindly.
    page response.
 
 4. **Read the selected window.** Read the selected window in one call. Windows
-   come from the hit anchor, the grep hit's section boundaries, or two adjacent
-   outline headings (`heading.line` of the target section to `heading.line - 1`
-   of the next). If a window turns out too small, widen to the section boundary
-   in one more call.
+   come from a page-group section preview's boundaries or two adjacent outline
+   headings (`heading.line` of the target section to `heading.line - 1` of the
+   next). If a window turns out too small, widen to the section boundary in one
+   more call.
 
    **Done when:** the needed evidence is in context without shell truncation,
    or the page response is complete and untruncated.
 
+   **Read coverage:** read the relevant candidate pages from the page results
+   until every subquestion of the user's question is backed by sections you
+   have actually read — not until a page "looks like the answer". Do not stop
+   to compose the answer while any subquestion still has no read evidence
+   behind it, and do not pick a single page by surface similarity between the
+   question wording and the page/module name or hit line.
+
 5. **Assess coverage, then answer or iterate.** Map the user's question into
    subquestions and check each one against the sections you actually read. If a
    subquestion is covered, answer with citations (knowledge base + page path +
    section). If a gap remains, go back to step 2 with another set of `--paths`
    **copied** from the index, or return to discovery for the next candidate.
-   If the evidence is missing after the allowed search, say which subquestion is
-   not covered instead of filling it from memory.
+   If the evidence is missing after the allowed search, the only acceptable
+   output for that subquestion is "not covered by the knowledge base" — do not
+   attach a confident value from general knowledge, not even with a disclaimer
+   or a self-declared boundary.
 
    **Done when:** every answered subquestion is supported by read sections, or
    the remaining gaps are explicitly reported as missing evidence.
 
 ## Anti-pattern: same-page offset crawling
 
-The failure this workflow prevents: grep returns a line number, you `+read` a
-tiny window around it, it is cut mid-evidence, so you nudge the window one line
-at a time. That wastes calls and never shows page structure. Instead: use the
-hit anchor, widen once up to the section boundary, or open `--outline` and read
-the selected heading range.
+The failure this workflow prevents: reading a tiny window, finding it cut
+mid-evidence, and nudging the window one line at a time. That wastes calls and
+never shows page structure. Instead: read the page-group section range, widen
+once up to the section boundary, or open `--outline` and read the selected
+heading range.
 
 ## Related