@thinkingai/ae-cli 6.0.44 → 6.0.45

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. 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, 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."
 ---
 
 # ae-kb
@@ -15,25 +15,27 @@ 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.
+- **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.
+- 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`.
 - `--host <url>` overrides the active AE host. It is available on every command and may be placed after the subcommand, e.g. `ae-cli kb +<command> --host <url>`.
 - **CRITICAL — Host compat (do this first):** After each `ae-cli` run, check stderr and `_notice.host_compat`. If either is present, open the user reply with a short ⚠️ version warning and **quote the `npm i -g` / `npx skills add` (or update-cluster) lines verbatim**, then present the business result. Soft tip; `ok: true` can still carry the notice.
-- For external-agent retrieval, prefer the deterministic flow `+index` -> `+grep` -> `+read`: inspect navigation, locate candidate pages, then open the exact page or line window. Use `+ask` only when the user wants an LLM-synthesized answer and accepts token consumption.
+- Retrieval (`+index` / `+grep` / `+read`) is deterministic and server-side LLM-free; use it for simple factual lookups. Use `+ask` when the question requires synthesizing across multiple pages or multi-hop reasoning.
 
 ## Commands
 
 | Command | Risk | Purpose |
 |---|---:|---|
-| `+query` | read | Query one or more knowledge bases with a natural-language question. |
-| `+ask` | read | LLM-powered Q&A over knowledge bases. Consumes platform tokens. |
+| `+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). |
 | `+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. |
-| `+read` | read | Read a full knowledge base page or a line window. |
+| `+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. |
 | `+url` | write | Upload a URL source directly with optional display name and parsing instruction. |
@@ -123,34 +125,26 @@ Use `+status` to inspect the current status of a knowledge base.
 ae-cli kb +status --name engineering-handbook
 ```
 
-### Query Knowledge
-
-Use `+query` with a natural-language question. Optionally scope to specific knowledge bases or tune result count and locale.
-
-```bash
-ae-cli kb +query \
-  --query "How do we release a dashboard?" \
-  --sources '[{"scope":"company","name":"engineering-handbook"}]' \
-  --top-k 10 \
-  --locale zh
-```
-
-When `--sources` is provided, each entry requires:
-
-- `scope`: knowledge base scope such as `personal` or `company`.
-- `name`: knowledge base name.
-
 ### Ask Knowledge (LLM)
 
-Use `+ask` when the user wants an LLM-synthesized answer. This endpoint calls a large language model and **consumes platform tokens**. Prefer `+index` -> `+grep` -> `+read` when deterministic retrieval is enough.
+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.
 
 ```bash
+# Default: submit and poll for completion
 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)
+ae-cli kb +ask --question "..." --no-wait
+
+# Query execution status later
+ae-cli kb +ask-status --execution-id <id>
 ```
 
 - `--question`, alias `-q`: required natural-language question (1-2000 characters).
@@ -158,10 +152,12 @@ ae-cli kb +ask \
 - `--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.
 
 ### List Accessible Knowledge Bases
 
-Use `+list` when you only need accessible knowledge base metadata without loading `index.md` navigation maps. By default it returns knowledge bases with `buildStatus: compiled`:
+Use `+list` when you only need accessible knowledge base metadata without loading `index.md` navigation maps. Omit `--build-status` to default to `compiled`; pass `idle` / `pending` / `compiling` / `compiled` / `failed` to filter by a specific status (system knowledge bases are always listed regardless of status):
 
 ```bash
 ae-cli kb +list
@@ -173,6 +169,8 @@ ae-cli kb +list --build-status compiled
 
 Use the deterministic retrieval primitives when an agent needs to explore knowledge base content like a code repository. These endpoints do not call an LLM on the server side.
 
+**Before running a real query, read [`references/query-workflow.md`](references/query-workflow.md)** — it is the step-by-step procedure for turning a question into an answer without crawling. It covers candidate indexing, copied-path grep, same-page read windows, linked-page re-grep, outline-derived ranges, and coverage assessment. This section below is the per-command reference the workflow draws on.
+
 Start with `+list` or `+index` to discover accessible knowledge bases. Use `+index` when you also need navigation maps:
 
 ```bash
@@ -190,26 +188,30 @@ Then use `+grep` to locate likely pages and line numbers:
 ae-cli kb +grep \
   --query "sandbox configuration" \
   --sources '[{"scope":"company","name":"engineering-handbook"}]' \
+  --paths '["wiki/sandbox.md"]' \
   --top-k 10
 ```
 
-Finally use `+read` to open the exact page, optionally with a line window:
+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.
+
+Use `+read --outline` when the current target page has no reliable grep range and headings are needed to choose a section:
 
 ```bash
 ae-cli kb +read \
   --source '{"scope":"company","name":"engineering-handbook"}' \
   --path "wiki/sandbox.md" \
-  --offset 1 \
-  --limit 200
+  --outline
 ```
 
-Retrieval rules:
+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:
 
-- `+list` accepts optional `--build-status` (default `compiled`) and `--locale`. Returns accessible knowledge base metadata including `buildStatus`, without `index.md` navigation maps.
-- `+index` accepts optional `--sources` and `--locale`; omit `--sources` to list all accessible knowledge bases.
-- `+grep` requires `--query` / `-q`; optional `--sources`, `--top-k` (1-50, default 10), and `--locale`.
-- `+read` requires `--source` pointing to exactly one knowledge base and `--path` relative to the knowledge base root; optional `--offset`, `--limit` (1-10000), and `--locale`.
-- Do not guess a `--path`; get it from `+index` or `+grep` results.
+```bash
+ae-cli kb +read \
+  --source '{"scope":"company","name":"engineering-handbook"}' \
+  --path "wiki/sandbox.md" \
+  --offset 42 \
+  --limit 60
+```
 
 ### Remove One Source
 
@@ -233,29 +235,29 @@ ae-cli kb +remove --name engineering-handbook
 
 ## Command Reference
 
-### `+query`
+### `+ask`
 
 ```bash
-ae-cli kb +query --query "<question>" [--sources '[{"scope":"company","name":"kb-name"}]'] [--top-k 10] [--locale zh|en|ja|ko]
+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]
 ```
 
-- `--query`, alias `-q`: required natural-language question.
+- `--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.
-- `--top-k`: optional max number of hits, 1-50, default 10.
+- `--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]`).
 
-### `+ask`
+### `+ask-status`
 
 ```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]
+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`.
-- **Token cost**: this command invokes an LLM on the server and consumes platform tokens. Prefer `+index` -> `+grep` -> `+read` for token-free deterministic retrieval.
+- `--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.
 
 ### `+list`
 
@@ -263,7 +265,7 @@ ae-cli kb +ask --question "<question>" [--sources '[{"scope":"company","name":"k
 ae-cli kb +list [--build-status compiled] [--locale zh|en|ja|ko]
 ```
 
-- `--build-status`: optional build status filter (default: `compiled`).
+- `--build-status`: optional; one of `idle` / `pending` / `compiling` / `compiled` / `failed`. Omit to default to `compiled` (system knowledge bases are always listed regardless of status).
 - `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
 - Response items include `buildStatus`.
 
@@ -279,24 +281,27 @@ ae-cli kb +index [--sources '[{"scope":"company","name":"kb-name"}]'] [--locale
 ### `+grep`
 
 ```bash
-ae-cli kb +grep --query "<keywords>" [--sources '[{"scope":"company","name":"kb-name"}]'] [--top-k 10] [--locale zh|en|ja|ko]
+ae-cli kb +grep --query "<keywords>" --sources '[{"scope":"company","name":"kb-name"}]' --paths '["wiki/page.md"]' [--top-k 10] [--locale zh|en|ja|ko]
 ```
 
-- `--query`, alias `-q`: required keywords to search across knowledge bases.
-- `--sources`: optional JSON array of knowledge base refs. Omit to search all accessible knowledge bases.
+- `--query`, alias `-q`: required keywords to search.
+- `--sources`: required JSON array of knowledge base refs.
+- `--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.
 
 ### `+read`
 
 ```bash
-ae-cli kb +read --source '{"scope":"company","name":"kb-name"}' --path "index.md" [--offset 1] [--limit 200] [--locale zh|en|ja|ko]
+ae-cli kb +read --source '{"scope":"company","name":"kb-name"}' --path "index.md" [--offset 1] [--limit 200] [--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.
+- `--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`.
 
 ### `+new`

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

@@ -0,0 +1,112 @@
+# ae-kb deterministic query workflow
+
+How to answer a knowledge question with the deterministic retrieval primitives
+(`+list` / `+index` / `+grep` / `+read`) instead of `+ask`. Follow this order;
+it is designed to reach the right section in a few calls and to avoid crawling a
+page line by line.
+
+Use `+ask` when the question requires synthesizing across multiple pages or
+multi-hop reasoning; simple factual lookups are served by the steps below.
+Everything below is server-side LLM-free.
+
+## The loop
+
+This picks up **after** `ae-kb-discovery` has listed accessible knowledge bases
+and ranked candidates. Start here with a chosen candidate; scope every `+index`
+/ `+grep` / `+read` call to it with `--sources` / `--source`. If the candidate
+turns out not to cover the question, go back to `ae-kb-discovery` for the next
+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.
+
+   **Done when:** you have the candidate's `index.md`, and a list of `wiki/...`
+   links you can **copy** (0 items still counts as done).
+
+2. **Grep copied paths.** Copy 1–3 `wiki/...` entries from the index (a page
+   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.
+
+   **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.
+   - `+read --offset` / `--limit` are the actual read window. Choose the
+     smallest reliable window that preserves the needed evidence; do not
+     shell-truncate with `| head`.
+
+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
+     `--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.
+   - **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>"]'`
+     scoped to that page and use the new hit range.
+   - **No reliable range:** if the new page has no concrete grep terms, its
+     grep misses, or headings are needed to choose the right section, call
+     `+read --outline` for that page. It returns only the heading tree
+     (`{level, heading, line}`), independent of any offset/limit window, with
+     empty content.
+
+   A bare `+read` without `--offset` / `--limit` is only acceptable after the
+   response proves the whole page was returned (`startLine: 1`,
+   `endLine: totalLines`, and `truncated: false`).
+
+   **Done when:** you have a reliable range from the same-page grep hit, a new
+   page grep hit, an outline-derived heading range, or a complete untruncated
+   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.
+
+   **Done when:** the needed evidence is in context without shell truncation,
+   or the page response is complete and untruncated.
+
+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.
+
+   **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.
+
+## Related
+
+- Command flags and JSON shapes: see the `+grep` / `+read` sections in
+  [`../SKILL.md`](../SKILL.md).
+- Use `+ask` for multi-page synthesis or multi-hop questions. Default `+ask` submits then polls until the answer is ready; `--no-wait` and `+ask-status` are for batch submit/retrieve. See the `+ask` section in [`../SKILL.md`](../SKILL.md).

package/skills/ae-kb-discovery/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ae-kb-discovery
+description: >
+  Discover which AE/TE/ThinkingEngine knowledge bases accessible to the current user are worth searching, and decide whether to search at all, through read-only operations. Use when the user explicitly asks to search knowledge bases, internal documentation, or company materials. Also use when a task requires internal facts or business context, including product design and rules, events, campaign or operations calendars, release and iteration records, workflows, policies, and terminology; use it as well when this context is needed to explain data analysis results, anomalies, or trends and form evidence-backed conclusions. Do not use if the user explicitly asks not to access knowledge bases. This skill covers discovery and candidate selection; run the actual `+index` / `+grep` / `+read` / `+ask` retrieval with the `ae-kb` skill.
+---
+
+# Knowledge Base Discovery
+
+Treat knowledge bases as an optional source of internal facts and business context. Keep the user's original goal unchanged; knowledge base retrieval is a supporting workflow, not the task itself.
+
+This skill decides **whether** to use a knowledge base and **which** knowledge base is worth searching. The retrieval procedure itself — inspecting the index, grep, reading sections, and optional LLM synthesis — lives in the `ae-kb` skill (`references/query-workflow.md`). Discover here, then hand off to `ae-kb` to execute.
+
+## Decide Whether to Use This Skill
+
+Use this skill when:
+
+- The user explicitly asks to search a knowledge base, internal documentation, or company materials.
+- The task requires organization-specific facts or context, such as product design and rules, events, campaign or operations calendars, release and iteration records, workflows, policies, or terminology.
+- Internal context is needed to explain data analysis results, anomalies, or trends and form evidence-backed conclusions.
+- The knowledge base context currently available does not cover the question, and discovering other accessible sources has clear value.
+
+Do not use this skill when:
+
+- The user explicitly asks not to use knowledge bases.
+- The task only requires querying real-time state or performing an operation and does not need document context.
+- General knowledge is sufficient for a reliable answer and internal evidence would not materially improve it.
+
+## Discovery Workflow
+
+### 1. Get the List of Accessible Knowledge Bases
+
+First, get the lightweight list of knowledge bases accessible to the current user:
+
+```bash
+ae-cli kb +list
+```
+
+Use the exact `scope` and knowledge base name returned by the command, together with available metadata such as description, tags, language, and `bindings`. A binding identifies an associated context through `targetType`, `targetId`, and optional `targetName`. Do not guess a name, scope, or binding. Treat metadata returned by `+list` only as input for candidate selection, not as evidence from knowledge base content.
+
+If `+list` is unavailable or fails, do not guess which knowledge bases exist. If the user explicitly requested a knowledge base search, explain that discovery cannot currently be completed. Otherwise, return to the original task and reassess the capabilities currently available.
+
+### 2. Rank Candidate Knowledge Bases
+
+Rank candidates in this order:
+
+1. Prefer a knowledge base explicitly named by the user. Use the exact name and scope returned by `+list`, regardless of whether it has a matching binding.
+2. Prefer candidates whose bindings exactly match the current session context. Match `targetType: project` against the current analysis project ID, `targetType: space` against the current community space ID, and `targetType: dwSpace` against the current digital workspace code.
+3. For the remaining candidates, compare the user's request with the knowledge base name, description, and tags. Use language only as a preference between candidates with similar relevance; language alone does not establish relevance.
+
+Compare `targetId` with the corresponding current ID or code first. Use `targetName` only as a secondary signal when an ID or code is unavailable; do not replace a conflicting ID match with a name match. A candidate with no bindings or no current-context match remains eligible for semantic ranking. A binding to another project or space lowers implicit priority but does not exclude the candidate, and an explicit user choice still takes precedence.
+
+Select one preferred knowledge base by default. When several candidates are highly relevant, retain no more than three and try them one at a time in priority order. Do not read the indexes of all candidates in advance. A binding, name, description, tag, or language match only indicates that a knowledge base is worth searching; it does not prove a content match, grant access, or count as knowledge base evidence.
+
+### 3. Hand Off to Retrieval
+
+Once a preferred knowledge base is selected, hand off to the `ae-kb` skill and follow its `references/query-workflow.md` for the entire retrieval procedure — including when `+ask` is appropriate.
+
+## Assess Coverage
+
+- Full coverage: The page content read supports the key conclusions required for the information request or analysis.
+- Partial coverage: The page content read provides only background, definitions, or partially relevant facts and cannot independently support the required conclusions.
+- No coverage: No suitable candidate knowledge base exists, or `+grep` and `+read` return no content that can support the conclusions.
+
+A candidate returned by `+list`, navigation returned by `+index`, a successful command, a tool call, or a metadata match does not count as a knowledge base hit. Only relevant page content that has actually been read can serve as knowledge base evidence.
+
+## Use Knowledge Base Evidence in Analysis
+
+When using internal context to explain data analysis results, anomalies, or trends:
+
+1. First state what the analysis itself demonstrates, including the metric change, time range, affected entity, and magnitude.
+2. Search using the affected entity, metric, time range, campaign or event name, product area, and release or version name.
+3. Verify that the retrieved evidence:
+   - Applies to the same entity, product area, or business scope.
+   - Overlaps with the time range covered by the analysis.
+   - Records an event, rule, release, or change that actually took effect.
+   - Uses a version and effective date that remained valid during the analysis period.
+4. Distinguish planned activities from completed events. A calendar or roadmap does not prove that an activity or release occurred unless the retrieved content confirms execution.
+5. Combine analytical facts with retrieved internal evidence and state directly what the evidence supports. Do not list possible causes that lack evidence.
+6. Use causal language such as "caused" or "led to" only when the available evidence establishes causality. Otherwise, say that the evidence supports a factor as a key explanation or that the factor is consistent with the observed change.
+7. If the evidence is insufficient, state clearly that the cause cannot be determined from the available evidence. Do not fill evidence gaps with speculation.
+8. When appropriate, organize the final answer in this order:
+   - Conclusion.
+   - Analytical evidence.
+   - Knowledge base evidence and relevant page paths.
+   - Necessary limitations of the evidence.
+
+## Handle Partial or No Coverage
+
+When knowledge base evidence provides only partial coverage, is entirely absent, or retrieval fails:
+
+1. Stop repeating searches against the same candidate knowledge base.
+2. If ranked candidates remain, switch to the next candidate. Search no more than three knowledge bases in one task.
+3. When all candidates provide no coverage, return to the user's original request instead of remaining in the knowledge base retrieval subtask.
+4. Reassess the capabilities currently available and choose the next path that best serves the original task. Do not hard-code a fixed fallback.
+5. Retain verified background evidence when useful, but never attribute conclusions drawn from other sources to a knowledge base.
+6. Do not report an unsuccessful knowledge base search unless the retrieval failure itself affects the user's decision.
+
+Knowledge base information must not replace required business operations. If the original task also requires real-time data or an action, complete that part through the appropriate available capability.
+
+## Safety Boundaries
+
+- Limit knowledge base access to the read-only retrieval primitives (`+list`, `+index`, `+grep`, `+read`, and `+ask` when the question requires multi-page synthesis or multi-hop reasoning). Do not create, upload, compile, or delete knowledge bases.
+- Respect existing scope, tenant, and membership permissions. Do not attempt to bypass an inaccessible knowledge base.
+- Do not expose internal root paths, access tokens, or raw permission metadata.
+- For protected knowledge bases, provide only summaries and synthesized conclusions allowed by the current permissions. Do not export complete source text or extensive verbatim excerpts.