@thinkingai/ae-cli 6.1.18 → 6.1.19

package/skills/ae-dataops/SKILL.md

@@ -20,6 +20,7 @@ The AE Data Development and Operations domain provides capabilities for data war
 | `dataops_flow` | Flow creation, node deletion, and orchestration | `dataops-flow-create` |
 | `dataops_flow` | Flow execution and monitoring | `dataops-flow-monitor` |
 | `dataops_operations` | Operations instance search, details, and task logs | `dataops-flow-monitor` |
+| `dataops_operations` | Backfill job creation, full draft update, deletion, execution, plans, stop, and rerun | `dataops-backfill` |
 | `dataops_ide` | Data exploration and SQL queries | `dataops-query` |
 | `dataops_integration` | Datasource and data integration | `dataops-integration` |
 
@@ -63,6 +64,7 @@ You must understand the following key concepts before use, otherwise errors are
 |----|--------|-------------|
 | **executeId** | Returned by `dataops_flow +execute_flow` | Early stop handle before the scheduler `flowInstanceId` is available |
 | **flowInstanceId** | Returned by `dataops_operations +search_flow_instances` | Operations perspective instance inspection and stop |
+| **jobId** | Returned by `dataops_operations +create_backfill_job` or `+search_backfill_jobs` | Persistent backfill job detail and lifecycle actions |
 
 ### Environment and Defaults
 
@@ -73,6 +75,8 @@ You must understand the following key concepts before use, otherwise errors are
 | `dataops_operations +get_flow_instance_detail` | Instance detail | Inspect one instance DAG and task statuses |
 | `dataops_operations +get_task_instance_detail` | Task detail/logs | Inspect one task and include logs only when needed |
 | `dataops_operations +stop_flow_instance` | Instance stop | Stop by exactly one of `executeId` or `flowInstanceId` |
+| `dataops_operations +list_backfill_flows` | Backfill source discovery | Returns eligible PROD flows and whether ST is required |
+| `dataops_operations +search_backfill_jobs` | Backfill job search | Filter persistent jobs and obtain `jobId` |
 
 ### Schema Naming Rules
 
@@ -92,6 +96,8 @@ You must understand the following key concepts before use, otherwise errors are
 Create DEV Flow → Create/Update DEV SQL, Integration, Workflow Instance Check, or Task Instance Check Tasks → Configure Dependencies/Schedule → Preview Release → Release to PROD → PROD Manual Execution / Operations Troubleshooting
 ```
 
+Backfill lifecycle: Discover eligible PROD flow → Create or fully update DRAFT job → Run explicitly → Search / inspect plans → Stop or rerun the complete job; delete only after target inspection
+
 ### CRON Format (6 fields)
 
 `second minute hour day month weekday` — Note: one more "second" field than standard 5-field format.
@@ -115,6 +121,7 @@ Choose the appropriate scenario skill based on user intent to get complete step-
 | Create flow, add or delete nodes, configure schedule, release | `dataops-flow-create` | create flow, new workflow, configure schedule, add task node, delete task node, release, cron, scheduled execution |
 | View execution status, troubleshoot failures, view logs | `dataops-flow-monitor` | execute flow, running instance, monitor, logs, stop, DAG, troubleshoot |
 | Search operation instances across a space | `dataops-flow-monitor` | operations instance, flow instance search, status statistics, owner statistics |
+| Create or operate a persistent multi-date backfill job | `dataops-backfill` | backfill, fill historical data, base date range, backfill plans, stop backfill, rerun backfill |
 | Create datasource, configure sync solution, execute sync | `dataops-integration` | datasource, sync, integration, field mapping, data ingestion, MySQL, ClickHouse, DatabricksJdbc |
 | Browse metadata, search tables, execute SQL queries | `dataops-query` | query, SQL, data exploration, search tables, view table structure, IDE, catalog, select |
 | Create tables and views | `dataops-table` | create table, table creation, view, data dictionary, table details, DDL |
@@ -155,13 +162,16 @@ Flow orchestration is divided into two scenario skills: **creation and configura
 
 **Lifecycle: DEV configuration and preview → Release to PROD → PROD manual execution and operations troubleshooting**
 
-Detailed creation/configuration commands live in [`references/dataops-flow-create.md`](references/dataops-flow-create.md). Detailed execution, monitoring, operation instance, task log, and stop commands live in [`references/dataops-flow-monitor.md`](references/dataops-flow-monitor.md).
+Detailed creation/configuration commands live in [`references/dataops-flow-create.md`](references/dataops-flow-create.md). Detailed execution, monitoring, operation instance, task log, and stop commands live in [`references/dataops-flow-monitor.md`](references/dataops-flow-monitor.md). Persistent multi-date backfill jobs live in [`references/dataops-backfill.md`](references/dataops-backfill.md).
 
 Key constraints:
 - Create and update tasks in DEV, preview/release before PROD execution.
 - Treat `+delete_task` as high-risk: verify the target with `+get_flow_overview`, preview with `--dry-run`, and use `--yes` only after explicit user confirmation. Deletion affects DEV; release the flow to apply it to PROD.
 - `+execute_flow` always runs PROD; it returns `executeId` for early stop.
 - Prefer `flowInstanceId` from operations search for stable inspection and troubleshooting.
+- A backfill job is persistent and batches multiple base dates; do not emulate it by looping `+execute_flow`.
+- Create and run backfill jobs as separate steps. `+rerun_backfill_job` reruns the complete job, not only failed plans.
+- `+update_backfill_job` replaces a DRAFT job's complete configuration; inspect the job first and do not treat it as a partial patch. Treat `+delete_backfill_job` as high-risk and preview it with `--dry-run` before confirmation.
 - Reference workspace parameters in task SQL as `${paramKey}`.
 
 ---

package/skills/ae-dataops/references/dataops-backfill.md

@@ -0,0 +1,135 @@
+---
+name: dataops-backfill
+version: 1.0.0
+description: "Backfill job lifecycle: discover eligible PROD flows, create or update drafts, delete jobs, run jobs, inspect plans, stop running jobs, and rerun complete jobs."
+metadata:
+  requires:
+    bins: ["ae-cli"]
+---
+
+# DataOps Backfill Jobs
+
+> **Prerequisites:** Read [`ae-dataops/SKILL.md`](../SKILL.md) for authentication, output, and safety rules.
+
+A backfill job is a persistent operations object that runs one PROD task flow for multiple base dates. It is not a single manual flow execution and is not a retry of an existing failed flow instance.
+
+## Lifecycle
+
+### 1. Discover an eligible PROD flow
+
+```bash
+ae-cli dataops_operations +list_backfill_flows --spaceCode "${spaceCode}"
+```
+
+Use only a returned flow whose `completeDataInfo.canRun` is true. When `completeDataInfo.hasSt` is true, pass `--stTime` while creating the job.
+
+### 2. Create a draft
+
+Always pass the backfill date range. For manual selection, also pass `--completeDates`; every selected date must be inside that inclusive range.
+
+```bash
+# Range mode
+ae-cli dataops_operations +create_backfill_job --spaceCode "${spaceCode}" \
+  --jobName "August backfill" --flowCode ${flowCode} \
+  --startDate "2026-08-01" --endDate "2026-08-07"
+
+# Custom-date mode
+ae-cli dataops_operations +create_backfill_job --spaceCode "${spaceCode}" \
+  --jobName "Selected dates" --flowCode ${flowCode} \
+  --startDate "2026-08-01" --endDate "2026-08-07" \
+  --completeDates '["2026-08-01","2026-08-03"]'
+```
+
+Creation returns a `DRAFT` job and does not run it. Defaults are `jobType=TASK_ALL`, `failureStrategy=END`, `parallel=true`, `reverse=false`, `step=1`, and `unit=DAY`. For `TASK_ONLY`, `TASK_PRE`, or `TASK_POST`, also pass `--startNode`.
+
+### 3. Update a draft when needed
+
+Update is a complete replacement, not a partial patch. Inspect the DRAFT job first, then pass `--jobId`, `--jobName`, `--flowCode`, and the complete date and strategy configuration just as for creation. Updating does not run the job.
+
+```bash
+ae-cli dataops_operations +update_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --jobName "Revised August backfill" --flowCode ${flowCode} \
+  --startDate "2026-08-01" --endDate "2026-08-10" \
+  --failureStrategy END --parallel true --reverse false
+```
+
+### 4. Run the draft explicitly
+
+```bash
+ae-cli dataops_operations +run_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+### 5. Search jobs and inspect plans
+
+```bash
+ae-cli dataops_operations +search_backfill_jobs --spaceCode "${spaceCode}" \
+  --status "RUNNING,FAIL,SUCCESS" --pageNum 1 --pageSize 20
+
+ae-cli dataops_operations +get_backfill_job_detail --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+Detail returns the job and its plans together. A draft has an empty plan list.
+
+### 6. Stop, rerun, or delete
+
+Stopping affects every unfinished plan in the running job. Inspect the job, preview the request, obtain explicit confirmation, and then pass `--yes`.
+
+```bash
+ae-cli dataops_operations +stop_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --dry-run
+# After explicit confirmation, execute the same target; the CLI prompts before dispatch.
+ae-cli dataops_operations +stop_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+Rerun applies to every plan only when the job is `FAIL` or `STOP`. A `SUCCESS` job cannot be rerun. Rerun reuses the same job and does not create a new backfill job. The CLI does not support rerunning only failed plans.
+
+```bash
+ae-cli dataops_operations +rerun_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --dry-run
+ae-cli dataops_operations +rerun_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+Deletion is high-risk. The server accepts only supported `DRAFT`, `FAIL`, or `SUCCESS` jobs. Inspect the exact target and preview the scoped request before confirmation; the CLI sends only `spaceCode` and `jobId` and does not pre-query or guess state.
+
+```bash
+ae-cli dataops_operations +delete_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --dry-run
+ae-cli dataops_operations +delete_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+## Command Reference
+
+| Command | Purpose | Flags |
+|---|---|---|
+| `+list_backfill_flows` | List eligible PROD flows | `--spaceCode` |
+| `+create_backfill_job` | Create a draft | `--spaceCode` `--jobName` `--flowCode` `--startDate` `--endDate`; optional in-range `--completeDates`, scope, failure, parallel, order, and ST flags |
+| `+update_backfill_job` | Replace a DRAFT job's complete configuration | `--spaceCode` `--jobId` `--jobName` `--flowCode` and the same complete configuration as create |
+| `+delete_backfill_job` | Delete a supported job | `--spaceCode` `--jobId`; high-risk, requires confirmation or `--yes` |
+| `+run_backfill_job` | Run a draft | `--spaceCode` `--jobId` |
+| `+search_backfill_jobs` | Search jobs | `--spaceCode` plus optional keyword, date, type, status, owner, sort, and paging filters |
+| `+get_backfill_job_detail` | Get job and plans | `--spaceCode` `--jobId` |
+| `+stop_backfill_job` | Stop a running job | `--spaceCode` `--jobId`; high-risk, requires confirmation or `--yes` |
+| `+rerun_backfill_job` | Rerun the complete job | `--spaceCode` `--jobId` |
+
+Statuses are `DRAFT`, `RUNNING`, `STOP`, `FAIL`, `SUCCESS`, and `READY_STOP`. Range units are `DAY`, `WEEK`, and `MONTH`. Custom dates must be a non-empty JSON array of unique `yyyy-MM-dd` strings inside the configured date range.
+
+## Transport Status
+
+Transition status: transitional
+
+Owning module: Gaia operations
+
+Current transport: DataOps CLI REST
+
+Covered tools: `operations_list_backfill_flows`, `operations_create_backfill_job`, `operations_update_backfill_job`, `operations_delete_backfill_job`, `operations_run_backfill_job`, `operations_search_backfill_jobs`, `operations_get_backfill_job_detail`, `operations_stop_backfill_job`, and `operations_rerun_backfill_job`
+
+Gateway target: TBD after the DataOps operations Capability Gateway schema review
+
+Review after: 2026-11-20
+
+Exit condition: Migrate these commands after Gaia exposes equivalent capabilities and the command contract tests pass against the Capability Gateway transport.

package/skills/ae-engage/SKILL.md

@@ -398,6 +398,8 @@ When the user wants to "create a flow / generate a flow canvas / save a flow", d
 3. Build condition-related nodes with semantic `targetDefinitionRequest` and
    `triggerDefinition` objects. Resolve real event and property names through Analysis metadata;
    do not create an intermediate cluster merely to obtain persisted QP.
+   For `ab_split_flow` indicators, use `indicatorsDef[].eventDefinition`; always provide the
+   aggregate `operator`/`value` and every event-property filter's `operator`/`values`.
 
 4. Before building touchpoint nodes such as `message_push`, `wechat_push`, or `webhook_push`, you must call:
 
@@ -585,6 +587,9 @@ For task draft creation or update, use this workflow:
    and every-completion events use count/eq/1. Completion target and experiment main-goal event
    filters must not use properties whose metadata `select_type` is `datetime`. Never construct
    persisted QP fields.
+   Select the audience by delivery side: server-side channels allow custom (`1`) or existing (`2`)
+   and reject all users (`3`); `client_push` (`channelType=3`) allows custom (`1`) or all users (`3`)
+   and rejects existing (`2`). Do not infer audience support from `triggerType` alone.
 4. `ae-cli engage-task task save --project-id <projectId> --req '{...}'`
 5. `ae-cli engage-task task submit-approval --project-id <projectId> --task-id <taskId>`
 

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

@@ -36,12 +36,16 @@ compounds when reusing `definition_request`; flattening them changes audience se
 For the second sequence step, omit `relative_to_first` or set it to `false`; use `true` only
 from the third step onward when its window must be measured from step 1.
 
-For existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
+For server-side existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
 
 ```bash
 ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<cluster_name>"]'
 ```
 
+Server-side channels allow custom (`1`) or existing (`2`) audiences and reject all users (`3`).
+`client_push` (`channelType=3`) allows custom (`1`) or all users (`3`) and rejects existing (`2`).
+Always pass `channelType` in `context` so the guide can validate this matrix.
+
 4. Build the final grouped `save_task.req`.
 5. Submit with `ae-cli engage-task task save --project-id <projectId> --req '{...}'`.
 

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

@@ -305,9 +305,45 @@ Fallback branch keeps only `branchId` + `branchType: 2`.
 #### `ab_split_flow`
 
 ```json
-{ "branchList": [ { "branchId": "<branchId>", "branchName": "Control Group", "branchType": 1, "order": 1, "percentageInExperiment": 34 }, { "branchId": "<branchId>", "branchName": "Experiment Group A", "branchType": 2, "order": 2, "percentageInExperiment": 33 } ], "indicatorsDef": [], "activateIndicatorsDef": null }
+{
+  "branchList": [
+    { "branchId": "control", "branchName": "Control Group", "branchType": 1, "order": 1, "percentageInExperiment": 50 },
+    { "branchId": "experiment_a", "branchName": "Experiment Group A", "branchType": 2, "order": 2, "percentageInExperiment": 50 }
+  ],
+  "indicatorsDef": [
+    {
+      "indicatorsUuid": "metric_1",
+      "name": "Maximum payment amount",
+      "desc": "",
+      "completionIndicatorType": 0,
+      "touch_cycle_num": 1,
+      "touch_cycle_num_unit": "day",
+      "eventDefinition": {
+        "type": "event",
+        "event": "payment",
+        "aggregation": "max",
+        "property": "pay_amount",
+        "operator": "gt",
+        "value": 0,
+        "filters": {
+          "relation": "and",
+          "items": [
+            { "field": "gold", "operator": "gt", "values": [20] }
+          ]
+        }
+      }
+    }
+  ],
+  "activateIndicatorsDef": null
+}
 ```
 
+Use `eventDefinition` for new Capability requests. Its top-level `operator` compares the aggregate
+result with `value`; each `filters.items[].operator` compares an event property with its `values`.
+Both comparison levels are explicit and must not be omitted. Do not construct persisted fields such
+as `event`, `taPropQuota`, `uceCalcuSymbol`, `num`, `filts`, or `calcuSymbol`; Hermes compiles them.
+Legacy `event` remains accepted temporarily for older clients, but never send both fields.
+
 #### `event_judge`
 
 ```json

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

@@ -245,6 +245,12 @@ Use the guide to decide which audience shape applies:
 - `targetClusterType=2`: existing cluster, requires `clusterKey`
 - `targetClusterType=3`: all users, forbids `definitionRequest` and `clusterKey`
 
+Audience availability depends on delivery side:
+
+- Server-side channels support `targetClusterType=1` (custom) and `2` (existing), but not `3` (all users).
+- `client_push` (`channelType=3`) supports `targetClusterType=1` (custom) and `3` (all users), but not `2` (existing).
+- Determine the delivery side from the selected real channel; do not infer audience support from `triggerType` alone.
+
 For a custom audience, pass the semantic definition directly. Do not create an intermediate
 cluster or copy persisted QP.
 

package/skills/ae-experiment/SKILL.md

@@ -33,10 +33,14 @@ Naming and response boundary:
   `targeting.definition_request`. Never generate or submit `targetConfig`.
 - Metric QP is semantic at the CLI boundary: write `metricDefinition`; read
   `metric_definition`. Never generate or submit `metricConfig`, `calcType`, or `Axxx` codes.
+- Event-property comparisons belong in `metricDefinition.filters`, using
+  `{relation,items:[{field,operator,values}]}`. Never put comparison fields directly on
+  `metricDefinition`, and never submit raw `filts`, `calcuSymbol`, or `ftv` fields.
 - For metric aggregations `sum` / `avg` / `max` / `distinct_count`, `metricDefinition.property`
   is **required** and must be a concrete available event property from Analysis metadata.
   Never create property aggregations without `property` (for example `metric_avg_no_property_*`).
-- Event-count aggregations `total_count` / `user_count` / `active_days` omit `property`.
+- Preset event aggregations `total_count` / `user_count` / `active_days` omit `property`.
+- Experiment metric creation does not support `avg_per_user` / `A105`.
 - Resolve event and property names with Analysis metadata before saving semantic definitions.
 - Lists return `data.items` and `data.total`; detail commands return `data.item`.
 - Readiness returns `data.readiness`; reports return `data.report`; save guides return `data.guide`; save dry-run validation returns `data.validation`; writes return `data.result`.
@@ -72,7 +76,7 @@ If an experiment save returns `error_code: METRIC_NOT_FOUND`, list metrics for t
 ```bash
 ae-cli experiment experiment get --project-id 1 --exp-id exp_123
 ae-cli experiment experiment save --project-id 1 --req '{"expName":"Demo"}' --dry-run
-ae-cli experiment metric save --project-id 1 --req '{"metricId":"login_users","metricName":"Login users","createType":"event","goalDirection":"up","metricDesc":"Users who logged in","metricDefinition":{"type":"event","event":"login","aggregation":"user_count"}}' --dry-run
+ae-cli experiment metric save --project-id 1 --req '{"metricId":"payment_gold_sum","metricName":"Payment gold sum","createType":"event","goalDirection":"up","metricDesc":"Gold sum for payments above 10","metricDefinition":{"type":"event","event":"payment","aggregation":"sum","property":"gold","filters":{"relation":"and","items":[{"field":"gold","operator":"gt","values":[10]}]}}}' --dry-run
 ae-cli experiment report metric-trend --project-id 1 --exp-id exp_123 --metric-id metric_1 --start-time 2026-07-01 --end-time 2026-07-07
 ```
 

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

@@ -21,9 +21,13 @@ See [`save_build_guide.md`](save_build_guide.md) / [`save_validate.md`](save_val
 - Supply metric QP as `req.metricDefinition`.
 - Never submit internal `metricConfig`, `calcType`, or an `Axxx` calculation code.
 - Experiment metrics currently accept event definitions only.
+- Event-property comparisons belong in `metricDefinition.filters`. Each item uses
+  `field`, `operator`, and `values`; do not place `operator` or `value` directly on
+  `metricDefinition`.
 - Supported aggregations:
-  - Event-count (no property): `total_count`, `user_count`, `active_days`
+  - Preset event metrics (omit `property`): `total_count`, `user_count`, `active_days`
   - Property-based (**`property` REQUIRED**): `sum`, `avg`, `max`, `distinct_count`
+- `avg_per_user` (`A105`) is not supported for experiment metric creation.
 
 ### Property rule (mandatory)
 
@@ -38,6 +42,12 @@ When `aggregation` is `sum`, `avg`, `max`, or `distinct_count`:
 
 When `aggregation` is `total_count`, `user_count`, or `active_days`, omit `property`.
 
+### Preset event metric example (no property)
+
+```bash
+ae-cli experiment metric save --project-id 1 --req '{"metricId":"payment_users","metricName":"Payment users","createType":"event","goalDirection":"up","metricDesc":"Users who triggered payment","metricDefinition":{"type":"event","event":"payment","aggregation":"user_count"}}'
+```
+
 ### Correct example (avg with property)
 
 ```bash
@@ -51,7 +61,11 @@ ae-cli experiment metric save --project-id 1 --req '{
     "type":"event",
     "event":"payment",
     "aggregation":"avg",
-    "property":"amount"
+    "property":"amount",
+    "filters":{
+      "relation":"and",
+      "items":[{"field":"amount","operator":"gt","values":[10]}]
+    }
   }
 }'
 ```
@@ -69,11 +83,9 @@ ae-cli experiment metric save --project-id 1 --req '{
 }
 ```
 
-### Event-count example (no property)
+Filters use the semantic `filters` tree with `relation=and|or` and items containing
+`field`, `operator`, and `values`. For the frontend example `gold > 10`, use:
 
-```bash
-ae-cli experiment metric save --project-id 1 --req '{"metricId":"purchase_users","metricName":"Purchase users","createType":"event","goalDirection":"up","metricDesc":"Unique purchasers","metricDefinition":{"type":"event","event":"purchase","aggregation":"user_count"}}'
+```json
+{"filters":{"relation":"and","items":[{"field":"gold","operator":"gt","values":[10]}]}}
 ```
-
-Filters use the semantic `filters` tree with `relation=and|or` and items containing
-`field`, `operator`, and `values`.

package/skills/ae-kb/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-kb
 version: 1.0.0
-description: "AE/TE knowledge base CLI manual for creating, querying, LLM-powered ask, listing accessible knowledge bases, deterministic index/grep/read retrieval, checking status, uploading, compiling, schema generation, URL sources, source deletion, and knowledge base deletion. Use when the user asks to manage TE/AE/ThinkingEngine knowledge bases, upload documents or URLs to a knowledge base, query knowledge, ask knowledge bases with an LLM, list accessible knowledge bases, inspect knowledge base indexes, search knowledge base pages, read a specific knowledge base page, check knowledge base status, generate schemas, compile knowledge, remove sources, or delete a knowledge base. To choose which knowledge base is worth searching, use the ae-kb-discovery skill first; this skill runs the retrieval once a target is chosen. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source display names, JSON payload shapes, or URL formats."
+description: 'AE/TE knowledge base CLI manual for creating, importing read-only compiled snapshots, querying, LLM-powered ask, listing accessible knowledge bases and their sources, deterministic index/grep/read retrieval, checking status, 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.'
 ---
 
 # ae-kb
@@ -14,11 +14,11 @@ ae-cli kb +<command> [options]
 
 ## Global Rules
 
-- Use this skill for TE/AE knowledge base tasks: create, query, ask with LLM, list accessible knowledge bases, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
+- Use this skill for TE/AE knowledge base tasks: create, import a compiled snapshot, query, ask with LLM, list accessible knowledge bases and their sources, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
 - **Searching a knowledge base for an answer is the most common task. If that is what you are doing, go straight to [Explore Knowledge Base Pages](#explore-knowledge-base-pages) and read [`references/query-workflow.md`](references/query-workflow.md) first — it is the retrieval procedure. The other commands below are for managing knowledge bases, not answering from them.**
 - Read operations can run directly after required inputs are known. Write operations require explicit user intent and normally keep the confirmation prompt unless the user asks to bypass it.
 - Prefer `--dry-run` before destructive or broad writes when the user has not already validated the target.
-- Do not invent knowledge base names, scopes, source display names, or JSON payloads. Ask the user or query known context when values are missing.
+- Do not invent knowledge base names, scopes, source IDs, source display names, or JSON payloads. Ask the user or query known context when values are missing.
 - When building a `--sources` ref (or `+read --source`), copy the exact `scope` and `name` from `+list` output — run `ae-cli kb +list` first when the scope of a named knowledge base is unknown.
 - JSON flags must be valid JSON strings, usually wrapped in single quotes in shell commands.
 - Successful commands return JSON by default. Use `--format table` only when a table is easier for a human to scan. Envelope may include optional `_notice.host_compat`.
@@ -33,16 +33,19 @@ ae-cli kb +<command> [options]
 | `+ask` | read | LLM-powered Q&A over knowledge bases; for multi-page synthesis or multi-hop questions. |
 | `+ask-status` | read | Query the current status of an ask execution by `--execution-id` without polling. |
 | `+list` | read | List accessible knowledge bases filtered by buildStatus (default: compiled). |
+| `+list-sources` | read | List source metadata for one knowledge base so exact source identifiers can be discovered safely. |
 | `+index` | read | List accessible knowledge bases and their `index.md` navigation maps. |
 | `+grep` | read | Keyword-search knowledge base pages and return matched lines with context. |
 | `+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. |
 | `+url` | write | Upload a URL source directly with optional display name and parsing instruction. |
 | `+schema` | write | Generate the compile schema for a knowledge base. |
 | `+compile` | write | Compile a knowledge base in incremental or full mode. |
 | `+status` | read | Query the current status of a knowledge base. |
-| `+rm-source` | write | Delete one source file from a knowledge base by display name. |
+| `+rm-source` | high-risk-write | Delete one source from a knowledge base by stable ID; exact display name is legacy compatibility only. |
 | `+remove` | write | Delete an entire knowledge base. |
 
 ## Common Workflows
@@ -67,6 +70,36 @@ Optional fields:
 - `--project-id`: optional project ID to bind.
 - `--project-name`: optional project display name.
 
+### Import a Compiled Snapshot
+
+Use `+import` only for a ZIP whose root contains `index.md` and at least one
+`wiki/**/*.md` page. The server validates all archive paths, limits, UTF-8 text, and Wiki links.
+
+```bash
+ae-cli kb +import \
+  --file ./knowledge-base.zip \
+  --name "Imported handbook" \
+  --description "Compiled documentation snapshot" \
+  --tags '["docs","handbook"]'
+
+# The submission returns requestId + queued. Query one snapshot later:
+ae-cli kb +import-status --request-id <requestId>
+```
+
+- The result is always a `personal` read-only snapshot; there is no `--scope`, `--force`, or replace option.
+- Imported snapshots support list, Index/Wiki reading, grep/read, Ask, and deletion. They do not expose source, Schema, usage, compile, member, settings, ownership-transfer, or company-publish operations.
+- The ZIP is limited to 50 MB and supports Markdown text only. Local images, attachments, other binaries, broken Wiki links, and ambiguous Wiki links are rejected by the server.
+- Submission returns `{requestId, status: "queued"}` immediately. It does not wait for ZIP validation or publication.
+- `+import-status` returns one of `queued`, `running`, `succeeded`, or `failed`; success includes `knowledgeBaseId`, and failure includes a stable error code/message.
+- If a `requestId` was returned, query it before retrying. If no request ID was received, run `ae-cli kb +list` before retrying the same name. A repeated same-name import is rejected.
+
+- Transition status: transitional
+- Owning module: te-claude External Knowledge Base Import API
+- Current transport: authenticated KB external REST through `kbUpload` for submission and `kbApi` for status lookup.
+- Gateway target: TBD (`kb.snapshot.import` proposed)
+- Review after: 2026-12-01
+- Exit condition: migrate to a typed Gateway capability when the equivalent multipart import capability is available, or remove this command if dynamic Gateway execution provides the same file-handling and output contract.
+
 ### Upload Files or Directories
 
 Use `+add` when sources are local files, local directories, or pages that should be fetched and converted to markdown before upload.
@@ -107,7 +140,17 @@ Generate the schema first when the knowledge base needs a compile schema.
 ae-cli kb +schema --name engineering-handbook
 ```
 
-Use `--force` only to recover a stuck `generating` status. Use `--model` only when the user provides the model display name.
+Use `--force` only when `+status` reports `schema_generating` and the user explicitly wants to replace the current generation attempt. The replacement may consume additional tokens. Use `--model` only when the user provides the model display name.
+
+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 \
+  --custom-instructions "Prioritize troubleshooting workflows and preserve command examples"
+```
+
+Use `--dry-run` to inspect the request body before sending it. While generation is running, a request without `--force` is idempotent only when it supplies no new model or effective custom instructions; otherwise it fails with `KB_SCHEMA_GENERATION_IN_PROGRESS`. With `--force`, the selected model and custom instructions apply to the replacement attempt. Invalid text fails with `KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID`.
 
 Compile after sources and schema are ready:
 
@@ -213,9 +256,34 @@ ae-cli kb +read \
   --limit 60
 ```
 
+### List Sources
+
+List sources first to discover the stable identifier for the intended source:
+
+```bash
+ae-cli kb +list-sources --name engineering-handbook
+```
+
+Copy the exact `id` from the response into `+rm-source`. Do not guess a source ID from a local filename, URL, display name, or an older upload response.
+
+- Transition status: transitional
+- Owning module: te-claude External Knowledge Base Sources API
+- Current transport: authenticated KB external REST through `kbApi`.
+- Gateway target: TBD (`kb.source.list` proposed)
+- Review after: 2026-12-03
+- Exit condition: migrate to a typed Gateway capability when an equivalent source-list capability is available, or remove this command if dynamic Gateway execution provides the same discoverability and safe output contract.
+
 ### Remove One Source
 
-Use `+rm-source` only when the source display name is known exactly.
+Use `+rm-source --id` with the exact ID returned by the current `+list-sources` response. This is a `high-risk-write`; keep the interactive confirmation unless the user has explicitly authorized `--yes`.
+
+```bash
+ae-cli kb +rm-source \
+  --name engineering-handbook \
+  --id cm-source-id
+```
+
+`--display-name` is retained for legacy compatibility only when a stable source ID is unavailable:
 
 ```bash
 ae-cli kb +rm-source \
@@ -223,7 +291,7 @@ ae-cli kb +rm-source \
   --display-name kb-1780046712-guide.md
 ```
 
-If the user only gives a loose source name, do not guess. Ask for the exact uploaded display name.
+If the user only gives a loose source name, do not guess a source ID. Run `+list-sources`, identify the intended row from returned metadata, and ask only when multiple rows remain ambiguous.
 
 ### Delete a Knowledge Base
 
@@ -316,6 +384,30 @@ ae-cli kb +new --name "<name>" [--scope personal|company] [--description "..."]
 ae-cli kb +add --name "<name>" --files '["./a.md","./docs","https://example.com/page"]'
 ```
 
+### `+import`
+
+```bash
+ae-cli kb +import --file "./knowledge-base.zip" --name "<name>" [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."]
+```
+
+- `--file`: required local `.zip` file.
+- `--name`: required personal knowledge-base name, up to 30 characters.
+- `--description`: optional, up to 200 characters.
+- `--tags`: optional JSON array, max 2 unique tags, each up to 15 characters.
+- `--project-id`: optional project binding.
+- Scope and terminal build state are generated by the server and cannot be supplied by the client.
+- Output: `{requestId, status: "queued"}`. Use `+import-status`; the command does not poll.
+
+### `+import-status`
+
+```bash
+ae-cli kb +import-status --request-id <requestId>
+```
+
+- `--request-id`: required ID returned by `+import`.
+- Output: `{requestId, status, knowledgeBaseId?, errorCode?, errorMessage?}`.
+- Returns a single snapshot and does not poll. A failed import is returned as `status: "failed"` with its stable error code/message; an unknown or inaccessible request exits non-zero.
+
 ### `+url`
 
 ```bash
@@ -325,9 +417,14 @@ ae-cli kb +url --name "<name>" --url "https://example.com/page" [--display-name
 ### `+schema`
 
 ```bash
-ae-cli kb +schema --name "<name>" [--force] [--model "<model displayName>"]
+ae-cli kb +schema --name "<name>" [--force] [--model "<model displayName>"] [--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.
+- 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
@@ -340,12 +437,26 @@ ae-cli kb +compile --name "<name>" [--mode incremental|full]
 ae-cli kb +status --name "<name>"
 ```
 
+### `+list-sources`
+
+```bash
+ae-cli kb +list-sources --name "<name>"
+```
+
+- `--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.
+- Copy the exact `id` from the current response before deleting a source; never guess it.
+
 ### `+rm-source`
 
 ```bash
-ae-cli kb +rm-source --name "<name>" --display-name "<uploaded source display name>"
+ae-cli kb +rm-source --name "<name>" --id "<source-id>"
 ```
 
+- `--id`: preferred stable source identifier copied from `+list-sources`.
+- `--display-name`: legacy compatibility selector used only when an ID is unavailable.
+- If both are supplied, `--id` wins. The command removes one source only.
+
 ### `+remove`
 
 ```bash