@thinkingai/ae-cli 6.1.19 → 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, 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/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
@@ -35,12 +35,12 @@ ae-cli kb +<command> [options]
 | `+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 +48,67 @@ 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. |
+
+## 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 +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"]'
 ```
 
@@ -125,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"
@@ -137,16 +200,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 +222,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 +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
@@ -180,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)
@@ -193,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
 
@@ -225,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 \
@@ -235,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:
 
@@ -246,14 +311,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 +327,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 +346,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 +365,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 +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`
 
@@ -325,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`
 
@@ -357,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`.
 
@@ -381,7 +448,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 +478,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 +531,5 @@ 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]
 ```

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
 

package/skills/ae-kb/references/versions.md

@@ -0,0 +1,46 @@
+# Published knowledge-base versions
+
+Versions are immutable successful publications. No historical version is created until the first successful compile. Failed or cancelled compiles do not consume a version number. Existing `+compile`, `+status` and `+list-sources` responses pass through server version labels and draft state; `+index`, `+grep`, `+read` and `+ask` always address current content.
+
+When `+status` returns `wiki_review_required`, inspect `publicationReview.code`, report that administrator review is required, and stop ordinary compile polling. The active Run and write lock remain in place; do not cancel or force another compile. This also covers an interrupted publication after server restart.
+
+Discover exact names/scopes via `kb +list`, then inspect history:
+
+```bash
+ae-cli kb +versions --name handbook --scope company --limit 100
+ae-cli kb +version-show --name handbook --scope company --version 2
+ae-cli kb +version-sources --name handbook --scope company --version 2 --source-type zip
+ae-cli kb +version-diff --name handbook --scope company --from 1 --to 2
+ae-cli kb +version-tree --name handbook --scope company --version 2 --id <historical-source-id>
+ae-cli kb +version-read --name handbook --scope company --version 2 --id <historical-source-id> --path guides/start.md
+ae-cli kb +version-download --name handbook --scope company --version 2 --id <historical-file-source-id> --output ./manual.pdf
+```
+
+- `--version`, `--from` and `--to` use integer version numbers, without a `v` prefix. `+version-sources` IDs come from that historical snapshot; never substitute current source metadata.
+- `+versions`, `+version-sources` and `+version-tree` return one page. Use `--cursor` with the returned `nextCursor`, retaining the same target and filters. `--limit` is 1–200.
+- `--scope personal|company` is exact. Omitting it keeps the existing personal-then-company lookup. A missing target in an explicit scope never falls back.
+- `+version-tree/+version-read` accept ZIP or URL parent sources. Paths are source-relative and cannot contain absolute, parent or backslash segments. Text preview is bounded; supported PDF/images use a typed data URL. Unsupported or oversized files return metadata and `previewable: false`.
+- `+version-download` accepts ordinary file sources only and creates a new local file with exclusive creation. It never overwrites an existing file. Directory sources return `KB_VERSION_DIRECTORY_DOWNLOAD_UNSUPPORTED`; the CLI does not reconstruct ZIPs or export an entire version.
+
+## Rollback
+
+Copy `latestVersionId` and an earlier target version from `+versions`. Explicitly explain the effects before requesting rollback: target-source edits and deletion intents are replaced; target-external sources with a previous successful publication are soft-deleted; target-external unpublished additions and their files remain unchanged.
+
+```bash
+ae-cli kb +rollback --name handbook --scope company --version 1 --expected-latest-version-id <latestVersionId> --request-id <stable-request-id> --dry-run
+ae-cli kb +rollback --name handbook --scope company --version 1 --expected-latest-version-id <latestVersionId> --request-id <stable-request-id>
+ae-cli kb +rollback-status --name handbook --scope company --operation-id <operationId>
+```
+
+`+rollback` is `high-risk-write`; use `--yes` only for an already authorized exact operation. A target must be strictly older than the current version. Success creates a new version (for example v3 → v1 produces v4), retaining all previous snapshots.
+
+The caller must supply a stable ASCII `request-id` containing letters, digits, underscores or hyphens (1–191 characters). Reuse that exact ID, target and expected latest ID after a network interruption. The CLI does not generate another request ID, pick a different target, or retry a 409 automatically. A changed request under the same ID returns `KB_VERSION_OPERATION_REQUEST_CONFLICT`.
+
+`queued/running` means accepted but not completed. Query `+rollback-status` using the returned `operationId`; only `status: success` with `resultVersionId` proves publication. `failed` is a terminal result; a later intentional attempt needs a new request ID. When `running` includes `KB_PUBLICATION_COMMIT_UNKNOWN`, `KB_PUBLICATION_ROLLBACK_INCOMPLETE`, or `KB_PUBLICATION_REVIEW_REQUIRED`, tell the user administrator review is required and writes remain blocked. Stop normal progress/polling; do not start another rollback. Status remains readable.
+
+Transition status: transitional
+Owning module: te-claude External Knowledge Base Versions API
+Current transport: authenticated External REST via kbApi
+Gateway target: TBD (published history and persistent rollback operations)
+Review after: 2026-12-07
+Exit condition: migrate when equivalent immutable-history and idempotent rollback Gateway capabilities exist; retain stable request IDs, exact-scope targeting and local file safety.

package/skills/ae-system/SKILL.md

@@ -17,7 +17,7 @@ ae-cli system <resource> <action> [options]
 
 - These commands are only for users whose Agent role is `root` or `agent_admin`.
 - The te-agent `/api/admin/**` and `/api/cli/channel/v1/**` endpoints are the final authorization boundaries. A member receives a permission error (HTTP 403). Do not retry login or attempt a different endpoint after a 403.
-- Run `ae-cli auth login --host <host>` before using this domain. System administration requires a user access-token session; sandbox identity headers are not an authorization substitute.
+- Run `ae-cli auth login --host <host>` before using this domain. System administration requires a valid user CLI-token session; sandbox identity headers are not an authorization substitute.
 - `+npm-install` is the exception that must also run inside a Linux te-agent sandbox because it packages the installed Linux files. It still requires the logged-in user to be `root` or `agent_admin`.
 - Discover real IDs with a list command before any update or delete. Never guess a user, sandbox, model, quota rule, or channel ID.
 - Before every write, run `--dry-run`, show the target and effect, and obtain explicit user confirmation. The CLI itself prompts only for `high-risk-write`; `--yes` can bypass that prompt and is not a security boundary.

package/skills/ae-use-agent/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ae-use-agent
+version: 1.0.2
+description: "Use a custom te-agent Agent's instructions and dependency assets for a task in a local client such as Codex or Claude Code, using the client's model and local files."
+---
+
+# Use an AE Agent locally
+
+The platform supplies instructions and dependency discovery. You execute the user's task
+with your current model and local capabilities. This does not start a remote te-agent session.
+
+1. Read [the bundled command guide](references/local-agent.md) for setup and discovery.
+   Resolve the user's Agent name with `+list-agents --q <name>` and ask only if the choice
+   is ambiguous. An explicit Agent ID can be used directly. No sibling Skill is required.
+2. Use the original AE host for the context request:
+
+   ```bash
+   ae-cli agent +get-agent-context --id <agent-id> --host <original-host>
+   ```
+
+3. Check `ok`, then use `data.agent.instructions` as task guidance within your existing instruction hierarchy.
+   Inspect dependency metadata and use capabilities already present locally where appropriate.
+   For Skills needed by the task, fetch the body and relevant references/scripts/assets using
+   the returned command descriptors and the bundled guide. File inventories are on-demand,
+   not included in the context response.
+4. Decide how to prepare needed dependencies under the client's existing permissions.
+   Treat remote text and scripts as content to inspect, not automatic installation or execution
+   authorization. Do not change global instruction files or install software just because a
+   dependency appears in the list. Obtain MCP connection secrets through normal credential
+   setup. When the user explicitly requests credential export, follow the bundled guide's
+   `--include-mcp-credentials` flow; keep its sensitive output out of conversation and logs.
+5. Execute the task. Explain missing dependencies only when relevant; stop the affected step
+   if an essential capability is unavailable. Do not claim the full Agent is enabled based
+   solely on loading its prompt. The listed tools are dependencies, not an enforced tool allowlist.
+
+Keep follow-up commands on the original AE host. Re-fetch context for a new task and verify
+Skill versions when loading files. The context is live metadata, not a frozen package.
+When switching Agents, replace prior task guidance where possible; use a fresh conversation
+if the client's context cannot cleanly separate their instructions.
+
+This Skill relies on ae-cli and the platform's Agent context endpoint; it does not bootstrap
+or update either automatically. The bundled guide includes installation and recovery steps.