@thinkingai/ae-cli 6.1.16 → 6.1.18

package/skills/ae-engage/references/save-task.md

@@ -426,6 +426,11 @@ When the guide points to event-based completion or experiment-driven main-goal r
 Read `fieldRules.blocks.controlConfig.completionIndicatorDef.filterPropertySelectTypes` and exclude
 every property type listed under `excluded` before constructing its `filters`.
 
+For a main goal (`completionIndicatorType=0`), always include `touch_cycle_num` and
+`touch_cycle_num_unit`. If the user does not request another completion window, use
+`touch_cycle_num=1` and `touch_cycle_num_unit="day"`. Static Capability validation may accept a
+main goal without these fields, but the Hermes save service rejects it.
+
 Important constraints that still apply:
 
 - `doNotDisturb.enableDoNotDisturb=true` requires `startTime` and `endTime` in `HH:mm`
@@ -444,6 +449,81 @@ compatibility field, and partial task updates preserve the existing server value
 client-side condition has no semantic field in the current contract, stop and report that it cannot
 be safely authored through this Capability.
 
+### 4.7 Verified A/B Task Template
+
+Use this shape as the starting point for a server-channel split experiment. Replace every
+placeholder with metadata discovered from the current project.
+
+```json
+{
+  "baseInfo": {
+    "taskName": "<taskName>",
+    "taskDesc": "<taskDescription>",
+    "tzOffset": "<projectTimezoneOrDefaultSentinel>"
+  },
+  "channelConfig": {
+    "channelType": 1,
+    "channelId": "<verifiedChannelId>",
+    "groupContentList": [
+      {
+        "expGroupName": "Control",
+        "expGroupType": 1,
+        "percentageInExperiment": 50,
+        "order": 0,
+        "contentList": [{ "pushLanguageCode": "default", "content": "<channelContentJsonString>" }]
+      },
+      {
+        "expGroupName": "Experiment A",
+        "expGroupType": 2,
+        "percentageInExperiment": 50,
+        "order": 1,
+        "contentList": [{ "pushLanguageCode": "default", "content": "<channelContentJsonString>" }]
+      }
+    ]
+  },
+  "targetConfig": {
+    "targetClusterType": 1,
+    "definitionRequest": "<semanticAudienceDefinition>"
+  },
+  "triggerConfig": { "triggerType": 2 },
+  "controlConfig": {
+    "completionIndicatorDef": {
+      "completionIndicators": [
+        {
+          "completionIndicatorType": 0,
+          "touch_cycle_num": 1,
+          "touch_cycle_num_unit": "day",
+          "eventDefinition": {
+            "type": "event",
+            "event": "<verifiedGoalEvent>",
+            "aggregation": "count",
+            "operator": "gte",
+            "value": 1
+          }
+        }
+      ]
+    },
+    "frequencyLimits": { "enableFrequencyLimits": false, "ruleList": [] }
+  },
+  "expConfig": {
+    "enableExp": true,
+    "expType": 1,
+    "percentageInLayer": 100,
+    "expIndicatorBizType": 1,
+    "controlGroupSkipPush": false,
+    "expGroupList": [
+      { "expGroupName": "Control", "expGroupType": 1, "percentageInExperiment": 50, "order": 0 },
+      { "expGroupName": "Experiment A", "expGroupType": 2, "percentageInExperiment": 50, "order": 1 }
+    ]
+  }
+}
+```
+
+The experiment group tuple (`expGroupName`, `expGroupType`, `percentageInExperiment`, `order`)
+must be identical between each `expConfig.expGroupList` entry and its corresponding
+`channelConfig.groupContentList` entry. Validate the final request, save it, then call `task get`
+and verify both persisted lists; a successful task ID alone is not sufficient verification.
+
 ---
 
 ## 5. Final Self-Check Before `engage-task task save`
@@ -461,6 +541,8 @@ Before submission, verify:
 9. No unsupported `triggerType=6` is used.
 10. Ordered steps contain `eventDefinition` and sequence metadata, not persisted aggregate fields.
 11. No placeholder IDs or fabricated resource names remain in the request.
+12. Every main goal includes `touch_cycle_num` and `touch_cycle_num_unit`.
+13. For experiments, `expGroupList` and `groupContentList` contain identical group tuples.
 
 ---
 

package/skills/ae-experiment/SKILL.md

@@ -56,6 +56,7 @@ Naming and response boundary:
    - `experiment feature save`
    - `experiment metric save`
 3. Create or patch the experiment draft with `experiment experiment save`.
+   Use `experiment experiment update-metrics` when replacing metric bindings or assigning guardrail roles.
 4. Check readiness with `experiment experiment ready-check`.
 5. For a non-mutex traffic layer, run `experiment experiment conflict-check` before submit (needs `feature_key_list` from context or `experiment get`).
 6. Move status with `experiment experiment manage`.
@@ -66,6 +67,7 @@ If an experiment save returns `error_code: METRIC_NOT_FOUND`, list metrics for t
 ## Parameter Conventions
 
 - Experiment save payloads distinguish two allocation fields: experiment-level `req.allocation` (**integer only; no decimals**) and group-level `req.groups[].allocation` (**integer only; sum must equal `100` exactly**).
+- Public experiment metric roles are `primary`, `secondary`, and `guardrail`. The internal `observation` role is currently unavailable for saves. Guardrail is a binding role; updating metrics replaces the full binding list.
 
 ```bash
 ae-cli experiment experiment get --project-id 1 --exp-id exp_123
@@ -92,7 +94,9 @@ Read [`save_build_guide.md`](references/save_build_guide.md) and
 
 ### Experiment
 
-`experiment experiment save`, `capability run experiment.experiment.save-submit`, `experiment experiment list`, `experiment experiment list-archived`, `experiment experiment get`, `experiment experiment ready-check`, `experiment experiment conflict-check`, `experiment experiment manage`, `experiment experiment update-group`, `experiment experiment batch-delete`, `experiment operation-log query`
+`experiment experiment save`, `experiment experiment update-metrics`, `capability run experiment.experiment.save-submit`, `experiment experiment list`, `experiment experiment list-archived`, `experiment experiment get`, `experiment experiment ready-check`, `experiment experiment conflict-check`, `experiment experiment manage`, `experiment experiment update-group`, `experiment experiment batch-delete`, `experiment operation-log query`
+
+Read [`manage_guardrail_metrics.md`](references/manage_guardrail_metrics.md) before assigning or replacing metric roles.
 
 ### Traffic Layer and Buckets
 
@@ -104,4 +108,6 @@ Read [`save_build_guide.md`](references/save_build_guide.md) and
 
 ### Metric and Feature
 
-`experiment metric save`, `experiment metric get`, `experiment metric list`, `experiment metric delete`, `experiment feature save`, `experiment feature update-status`, `experiment feature get`, `experiment feature list`, `experiment feature version-list`, `experiment feature operation-log query`, `experiment feature batch-delete`
+`experiment metric save`, `experiment metric get`, `experiment metric list`, `experiment metric delete`, `experiment feature save`, `experiment feature update-status`, `experiment feature get`, `experiment feature list`, `experiment feature version-list`, `experiment feature operation-log query`, `experiment feature batch-delete`, `experiment feature whitelist list`, `experiment feature whitelist save`, `experiment feature whitelist update-status`, `experiment feature whitelist batch-delete`
+
+Read [`manage_feature_whitelist.md`](references/manage_feature_whitelist.md) before querying or changing Feature whitelist rules.

package/skills/ae-experiment/references/manage_feature_whitelist.md

@@ -0,0 +1,66 @@
+# Feature Whitelist Rules
+
+List, create, modify, enable, disable, or delete explicit Feature whitelist rules.
+
+## List
+
+```bash
+ae-cli experiment feature whitelist list \
+  --project-id <id> --feature-key <feature_key>
+```
+
+The result contains only explicit whitelist rules for the Feature. Each item exposes `rule_id`,
+`feature_key`, `priority`, `status`, and a structured snake-case `whitelist` array. Use the returned
+`rule_id` for modification, status changes, or deletion.
+
+## Save
+
+```bash
+ae-cli experiment feature whitelist save \
+  --project-id <id> \
+  --feature-key <feature_key> \
+  --status enable \
+  --whitelist '[{"bucket_id":"#user_id","rules":[{"ids":["u1","u2"],"value":"on"}]}]'
+```
+
+Pass `--rule-id` to modify an existing whitelist rule. Omit it to create a rule. The Hermes
+Capability fixes the Atlas rule type to `targeting` and serializes the supplied buckets into the
+server's explicit whitelist rule configuration.
+
+Rules:
+
+- Resolve the Feature with `experiment feature get` before writing.
+- `bucket_id` is the split subject, such as `#user_id` or `#account_id`.
+- Each bucket contains one or more rows with a non-empty `ids` array and a string `value`.
+- An empty string Feature value is allowed. Bucket IDs cannot be empty or duplicated. IDs must be
+  unique within one bucket, while different buckets may use the same string ID.
+- The server validates each value against the Feature type and limits the total ID count.
+- Only one explicit whitelist rule can be enabled for the same Feature.
+- Enabling, modifying, disabling, or deleting an enabled whitelist rule immediately creates a new
+  version and syncs RCC when the Feature itself is online.
+
+## Status
+
+```bash
+ae-cli experiment feature whitelist update-status \
+  --project-id <id> --rule-id <rule_id> --status enable
+```
+
+Valid status transitions exposed by this command are `enable` and `disable`.
+
+## Delete
+
+```bash
+ae-cli experiment feature whitelist batch-delete \
+  --project-id <id> --rule-ids '["0001"]'
+```
+
+Deletion is high risk and requires confirmation. Enabled whitelist rules may be deleted; Hermes
+resynchronizes affected online Features afterward.
+
+All four commands use Capability Gateway with CLI-token authentication:
+
+- `experiment.feature_whitelist.list`
+- `experiment.feature_whitelist.save`
+- `experiment.feature_whitelist.update_status`
+- `experiment.feature_whitelist.batch_delete`

package/skills/ae-experiment/references/manage_guardrail_metrics.md

@@ -0,0 +1,26 @@
+# experiment experiment update-metrics
+
+Replace the metric bindings of an existing experiment draft and assign metric roles, including
+guardrail metrics.
+
+```bash
+ae-cli experiment experiment update-metrics \
+  --project-id <id> \
+  --exp-id <exp_id> \
+  --metrics '[{"metricId":"conversion","metricRole":"primary"},{"metricId":"error_rate","metricRole":"guardrail"}]'
+```
+
+## Contract
+
+- Discover every `metricId` with `experiment metric list`; never invent metric IDs.
+- `--metrics` must be a non-empty array. Each item requires camelCase `metricId` and `metricRole`.
+- `metricRole` is one of `primary`, `secondary`, or `guardrail`. Do not submit the internal
+  `observation` role; Hermes currently rejects it at save boundaries.
+- This command replaces all saved metric bindings because Hermes treats a non-empty `metrics` list
+  in a draft patch as a replacement. Include bindings that must remain, not only the new guardrail.
+- Guardrail is a binding role, not a separate metric type. Create the underlying metric first with
+  `experiment metric save` when it does not exist.
+- At least one `primary` metric is still required before readiness succeeds.
+
+Run with `--dry-run` first, then verify the persisted roles with `experiment experiment get` and
+run `experiment experiment ready-check`.

package/skills/ae-experiment/references/save_experiment.md

@@ -104,7 +104,7 @@ ae-cli experiment experiment save --project-id 1 --req '{"expId":"exp_123","allo
 - `expCycle.cycleType` can be `day` or `sample`; when `cycleType=day`, `dayNum` is `1..90`. Blank cycle defaults to day + 30.
 - Before readiness, `groups` must be non-empty, contain exactly one control group (`isControl=1`), group allocations must sum to exactly `100`, and each `expGroupValue` must be a non-empty JSON string array.
 - Feature experiments must bind `featureKeyList` before readiness. `featureKeyList` contains Feature key strings, not Feature objects. The MCP currently supports one `featureKey` for feature experiments.
-- Metrics use `metricRole=primary|secondary|guardrail|observation`; before readiness at least one primary metric is required.
+- Metrics use `metricRole=primary|secondary|guardrail`; the internal `observation` role is currently unavailable for saves. Before readiness at least one primary metric is required.
 - `targeting` replaces the saved targeting object when provided.
 - Custom audience QP must be supplied as the semantic object
   `targeting.definitionRequest`. Do not submit the internal `targeting.targetConfig`

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. |
@@ -95,7 +97,7 @@ ae-cli kb +url \
   --parse-instruction "Keep headings and code blocks"
 ```
 
-`--url` must be `http(s)`.
+`--url` must be `http(s)`. The server detects the platform from the URL automatically: URLs on a `*.feishu.cn` or `*.larksuite.com` subdomain are parsed with the Feishu pipeline (including sub-documents, using the server's own Feishu parsing instruction — `--parse-instruction` is ignored for them); all other URLs are fetched as regular web pages.
 
 ### Generate Schema and Compile
 
@@ -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).