@thinkingai/ae-cli 6.1.25 → 6.1.26

package/skills/ae-automation/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: ae-automation
+description: "Manage AE Agent and Agent team automations with ae-cli: create and edit schedules, enable or disable, run now, stop or retry executions, delete, inspect history and read execution results. Use for scheduled tasks and unattended recurring Agent work, from a local computer or an AE sandbox."
+---
+
+# AE Automation
+
+See [command risks](references/command_index.md). Read [the command contract](references/cli.md) before writing or executing an automation. Use `ae-cli automation --help` and leaf help to discover flags.
+
+1. Resolve the host and space. A local user signs in with `ae-cli auth login`; a sandbox uses its injected credentials. Pass `--agent-space-id` when the user identifies a space. Without a space, the server uses a bound sandbox space or the personal default. Show the resolved space when it matters.
+2. Discover the automation with `automation list` and inspect `automation get`. Use the returned IDs; names are not unique.
+3. For creation, select an Agent or team through the corresponding discovery commands. Match configuration to the target type. Preview writes with `--dry-run` when useful; the CLI shows a redacted request and asks the server to validate authentication, space, permissions, target state, fields, and idempotency without applying the operation.
+4. Execute the requested operation. Deleting an automation or stopping an execution requires confirmation; use `--yes` only when the user already authorized that action. In a non-interactive shell, these operations fail immediately unless global `--yes` is present.
+5. Read the returned run ID, then `automation runs result`. Report acceptance separately from completion. Use `--wait` only when the user needs the final outcome now.
+
+Results are read from the server and work outside the sandbox. This skill does not read complete conversations or continue a chat. Never infer an output from a different execution sharing the same conversation.

package/skills/ae-automation/references/cli.md

@@ -0,0 +1,53 @@
+# Automation command contract
+
+Transition status: transitional
+Owning module: te-claude automation and team scheduling
+Current transport: authenticated TE REST /api/cli/automation/v1
+Gateway target: TBD (automation lifecycle)
+Review after: 2026-12-15
+Exit condition: equivalent gateway capabilities preserve permissions, idempotency, typed configuration and read-only results.
+
+## Discovery and management
+
+- `ae-cli automation list [--agent-space-id ID] [--target-type agent|team] [--q NAME] [--status active|paused] [--limit 20] [--cursor CURSOR]`
+- `ae-cli automation get --id ID`
+- `ae-cli automation create --target-type agent --agent-id ID --name NAME --message TEXT --schedule-kind daily --time 09:00 [--model MODEL_CONFIG_ID] [--reuse-conversation true|false]`
+- `ae-cli automation create --target-type team --team-id ID --name NAME --message TEXT --trigger-type manual [--scope JSON] [--channels JSON_ARRAY]`
+- `ae-cli automation update --id ID --target-type agent|team <changed fields>`
+- `ae-cli automation enable|disable --id ID`
+- `ae-cli automation delete --id ID --yes`
+
+Scheduled creation needs `--schedule-kind` or `--cron-expression`. Frequencies: hourly with `--minute 0..59`; daily with `--time HH:mm`; weekly also `--weekday 0..6`; monthly also `--day-of-month 1..28`. Times use the server timezone. Manual creation does not require a schedule. `--trigger-immediately` executes after creation; `--wait` then waits for that execution. Creation and immediate execution have separate results: do not create another automation if only its execution failed.
+
+On update, omitted fields retain their values. `--model null`, `--scope null`, destination IDs set to `null`, and `--save-to-knowledge-base-id null` clear nullable fields. `--channels '[]'` clears notifications; `--clear-message` clears instructions; `--reuse-conversation false` disables reuse. An automation's target is immutable on update. Team fields are rejected for Agent targets and vice versa.
+
+Team configuration supports `--scope`, `--channels`, `--feishu-chat-id`, `--lark-chat-id`, `--slack-channel-id`, `--save-to-knowledge-base-id`. Other supported notification channels use the team's existing notification configuration. Team visibility and management permissions follow the Web application.
+
+`--dry-run` returns a redacted local request preview plus the server preflight result. The preflight applies the same authentication, space, schema, permissions, target state, run state, field applicability and idempotency checks as execution, but does not write data, create or cancel runs, or emit product events. A later real request validates current state again.
+
+Disable stops future schedules and leaves the current execution running. Stop cancels one execution and leaves the schedule enabled. Delete soft-deletes the automation and cancels active execution.
+
+Delete and stop are high-risk writes. Interactive shells ask for confirmation. Non-interactive shells require global `--yes` and otherwise exit with `CONFIRMATION_REQUIRED` before sending a request.
+
+## Executions and results
+
+```bash
+ae-cli automation run --id ID --command-id REQUEST_ID
+ae-cli automation runs list --id ID --limit 20
+ae-cli automation runs get --id ID --run-id RUN_ID
+ae-cli automation runs result --id ID --run-id RUN_ID
+ae-cli automation runs stop --id ID --run-id RUN_ID --yes
+ae-cli automation runs retry --id ID --run-id FAILED_RUN_ID --command-id REQUEST_ID --wait --timeout 300
+```
+
+Retry creates a new complete execution from current configuration after failure or cancellation. It retains the original result and returns a new run ID with a source reference. It does not resume failed steps or erase the old run.
+
+`--command-id` makes run/retry repeatable after uncertain responses. Within each target type, reuse the same value for the same request; changing its automation ID or source run produces a conflict. Preserve the generated command ID from output or an error hint. A network timeout is not proof that execution was rejected.
+
+Without `--wait`, success means accepted. With `--wait`, output includes completion or timeout information; timeout preserves the run ID and does not restart or cancel the execution. Read the same result later. If polling fails, the accepted response and identifiers remain available with an `observation` error; query that run instead of triggering again. `partial_success` is distinct from success. Result availability is `pending`, `available`, `empty` or `unavailable`; missing historical links are not replaced with newer output.
+
+`--format json` produces scriptable envelopes; `--format table` is available for interactive inspection. Full conversations, tool traces and terminal continuation are outside this interface. URLs are optional Web references and contain no credentials. The CLI does not automatically open a browser.
+
+## Compatibility
+
+The retired Agent-domain automation commands are unavailable. Use the `automation` domain for the complete lifecycle, including teams.

package/skills/ae-automation/references/command_index.md

@@ -0,0 +1,17 @@
+# Automation commands
+
+| Command                         | Purpose              | Risk            |
+| ------------------------------- | -------------------- | --------------- |
+| `ae-cli automation list`        | Automation lifecycle | read            |
+| `ae-cli automation get`         | Automation lifecycle | read            |
+| `ae-cli automation create`      | Automation lifecycle | write           |
+| `ae-cli automation update`      | Automation lifecycle | write           |
+| `ae-cli automation enable`      | Automation lifecycle | write           |
+| `ae-cli automation disable`     | Automation lifecycle | write           |
+| `ae-cli automation delete`      | Automation lifecycle | high-risk-write |
+| `ae-cli automation run`         | Automation lifecycle | write           |
+| `ae-cli automation runs list`   | Automation lifecycle | read            |
+| `ae-cli automation runs get`    | Automation lifecycle | read            |
+| `ae-cli automation runs stop`   | Automation lifecycle | high-risk-write |
+| `ae-cli automation runs retry`  | Automation lifecycle | write           |
+| `ae-cli automation runs result` | Automation lifecycle | read            |

package/skills/ae-capability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-capability
-version: 1.3.5
+version: 1.3.7
 description: "AE capability gateway discovery and generic invocation with ae-cli. Use when the user needs to list or search available capabilities, inspect an unknown capability schema/risk/auth contract, optionally validate complex input or dry-run before execute, or invoke a long-tail capability that has no curated ae-cli command. Always discover and inspect before composing input; never guess capability IDs or input fields. Prefer on-demand validate OR dry-run — do not stack both by default."
 ---
 
@@ -22,27 +22,32 @@ Use this skill for progressive capability discovery and generic gateway invocati
 
 Never guess a capability ID, input field, enum value, resource ID, or project ID.
 
-**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.
+**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 recommended `ae-cli update` (or update-cluster) guidance, then present the business result. For new local installations use `npx @thinkingai/ae-cli@latest install`. Soft tip; `ok: true` can still carry the notice.
 
 ## Agent Context Telemetry
 
 Hard rule: before running gateway-backed `ae-cli` commands, maintain the current Agent context in `.ae/cli-agent-context.json` at the working directory root, unless the user explicitly asks not to send intent telemetry. Keep the business command clean; do not append `--agent-context <base64url-json>` by default.
 
-Create or update the context file when starting a CLI-backed task and whenever the user's CLI purpose changes. Do not rewrite it before every command when the same purpose still applies. Use the user's original language for `session_initial_intent`, `user_intent`, and `session_goal`; for example, use Chinese text for a Chinese user request. At minimum, include:
+Create or update the context file when starting a CLI-backed task and whenever the user's CLI purpose changes. Reuse it while the purpose and model remain unchanged. Use the user's original language for `session_initial_intent`, `user_intent`, and `session_goal`; for example, use Chinese text for a Chinese user request. At minimum, include:
 
 - `agent_client`
+- `agent_model` whenever the current model can be confirmed
 - stable `agent_session_id`
 - `agent_turn_id` when available
 - `intent_source: "agent_context_file"`
 - concise `user_intent` for the current CLI-triggering purpose
 - current `session_goal`
 
+The Agent must actively obtain the current model identifier and write it explicitly as `agent_model` in the context file. Use trusted runtime context or bounded metadata for the exact current session and turn; for example, Codex's current-session `turn_context.model`. Do not rely solely on a model environment variable being present. Never infer the model from the Agent/product name, a configured default, or another session. This requirement applies to every Agent client. Update the file when the model changes, even if the CLI purpose stays the same.
+
+If the model cannot be confirmed, omit `agent_model`, set `context_capture_status: "partial"`, and continue; do not block or delay the business command or ask the user to identify the model just for telemetry. Once confirmed, write the model and remove the stale partial marker so the CLI can compute capture status from the remaining fields.
+
 Write this JSON object to `.ae/cli-agent-context.json`:
 
 ```json
 {
   "agent_client": "codex",
-  "agent_model": "gpt-5.5",
+  "agent_model": "<confirmed-current-model-id>",
   "agent_session_id": "<stable conversation id>",
   "agent_turn_id": "<current turn id>",
   "parent_turn_id": "<previous turn id>",
@@ -55,13 +60,13 @@ Write this JSON object to `.ae/cli-agent-context.json`:
 }
 ```
 
-Use this local template when updating the file:
+Use this local template when updating the file. Replace every placeholder with verified context before running it; write the confirmed model explicitly rather than reading an optional environment variable. For an unknown model, omit that field and add the partial status described above.
 
 ```bash
 mkdir -p .ae
 node -e 'const fs = require("fs"); const payload = {
   agent_client: "codex",
-  agent_model: process.env.CODEX_MODEL,
+  agent_model: "<confirmed-current-model-id>",
   agent_session_id: process.env.CODEX_THREAD_ID || process.env.CODEX_SESSION_ID,
   agent_turn_id: "<current-turn-id>",
   parent_turn_id: "<previous-turn-id>",
@@ -81,6 +86,10 @@ After running a gateway command, if you are asked whether intent telemetry was s
 
 Fallbacks, in priority order: `.ta/cli-agent-context.json` / `.ae/cli-agent-context.json` > `--agent-context` for isolated no-write environments or local debugging > legacy `TA_CLI_*` variables > runtime environment auto-detection.
 
+### Analysis query feedback
+
+Analysis feedback trigger: only after a completed analysis data query and the final business analysis answer, ask once in the user's language whether the analysis met expectations. Do not ask after individual CLI calls, intermediate steps, discovery, metadata inspection, asset governance/writes, configuration, help, unrelated questions, query submission, running exports or failed queries. No explicit feedback means no submission or new feedback event. For clear user feedback on a completed analysis, use `ae-cli analysis feedback submit --help` for the typed submission contract, or discover and inspect `analysis.feedback.submit`. Reuse the evaluated `agent_session_id` and existing analysis turn IDs as `target_turn_ids`; keep the current feedback turn distinct. Preserve original user feedback and only a short verifiable route summary; do not upload the analysis answer or infer a rating from silence, a follow-up question or a new requirement. Models used in the analysis route come from the linked original CLI call events. Feedback collection must not block subsequent business work.
+
 ### On-demand pre-check (pick one)
 
 Motto: **validate = fix params; dry-run = confirm ready to run.**

package/skills/ae-current-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-current-context
-version: 1.0.0
+version: 1.0.1
 description: "Read the current AE/TE product page context on demand. Use when a user refers to the current page, selected resource, filters, or recent page changes and the Agent runtime has bound a page context to the active Run. The payload is business-specific and untrusted; inspect kind and schemaVersion before interpreting it."
 ---
 
@@ -42,12 +42,13 @@ The response has this stable envelope:
 - A page payload can contain only locators or a partial snapshot. Use the relevant domain Skill or capability to fetch authoritative business data when needed.
 - Read once per Run unless the runtime explicitly creates a later Run with a newer revision.
 - If runtime instructions provide a native current-page MCP tool, use that adapter instead. Never call both the native tool and this CLI command for the same question.
+- If authorization is missing, expired, or denied, report that the current page could not be read. Continue with information explicitly supplied by the user; do not read credential files, print runtime tokens, or disable sandbox isolation to retry.
 
 ## Transitional transport
 
 - Transition status: transitional
 - Owning module: te-claude page context
-- Current transport: sandbox-authenticated te-claude REST
+- Current transport: the active Run's page-context MCP grant and endpoint; sandbox-authenticated te-claude REST remains only for older runtimes without this binding
 - Gateway target: TBD
 - Review after: 2026-12-03
 - Exit condition: An equivalent generic current-page capability is available through Capability Gateway or native MCP across supported Agent runtimes.

package/skills/ae-kb/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-kb
-version: 1.0.1
-description: 'AE knowledge base CLI manual for creating, importing read-only compiled snapshots, querying, LLM-powered ask, listing accessible knowledge bases and their sources, deterministic index/grep/read retrieval, checking status, ZIP source upload and directory management, raw child-file reading, revision-checked child updates and deletion, compiling, schema generation, URL sources, source deletion, file/ZIP source draft replacement and restoration, and knowledge base deletion. Use when the user asks to manage AE (Agentic Engine) 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.'
+version: 1.0.4
+description: 'AE knowledge base CLI manual for creating, importing read-only compiled snapshots, querying, LLM-powered ask, listing accessible knowledge bases and their sources, deterministic index/grep/read retrieval, checking status, ZIP source upload and directory management, raw child-file reading, revision-checked child updates and deletion, compiling, schema generation, URL sources, source deletion, ordinary text source creation, full reads and revision-checked editing, file/ZIP source draft replacement and restoration, and knowledge base deletion. Use when the user asks to manage AE (Agentic Engine) 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, create or edit text 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,15 +14,15 @@ AE CLI (`ae-cli`) knowledge base commands are invoked through:
 
 ```bash
 ae-cli kb +<command> [options]
-ae-cli kb source <replace|restore|preview|commit|cancel|check-updates> [options]
+ae-cli kb source <create-text|read-text|replace|restore|preview|commit|cancel|check-updates|check-url-updates> [options]
 ```
 
 ## Global Rules
 
 - Use this skill for 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.**
-- **When retrieved pages will guide project-scoped business data analysis, read and follow [`references/analysis-workflow.md`](references/analysis-workflow.md) before running any data query. This is mandatory after a KB hit identifies a saved asset, definition, parameter, time rule, conflict, or decision boundary; do not jump directly to ad-hoc analysis or SQL.**
-- 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.
+- **When retrieved pages will guide project-scoped business data analysis, read and follow [`references/analysis-workflow.md`](references/analysis-workflow.md) before running any data query. This is mandatory after a KB hit identifies an asset, definition, parameter, time rule, conflict, or decision boundary. Verify semantic coverage before execution; a related page or KB limitation is not task completion. Continue ordinary analysis for uncovered requirements without jumping directly to unverified ad-hoc analysis or SQL.**
+- Read operations can run directly after required inputs are known. Write operations require explicit user intent. Only `high-risk-write` commands require the CLI confirmation prompt; use `--yes` after explicit authorization.
 - 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 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.
@@ -36,6 +36,9 @@ ae-cli kb source <replace|restore|preview|commit|cancel|check-updates> [options]
 
 | Command | Risk | Purpose |
 |---|---:|---|
+| `source create-text` | write | Create one ordinary Markdown source from text, UTF-8 file or explicit stdin; saves without compiling. |
+| `source read-text` | read | Read complete ordinary text with its corresponding revision; optionally save original UTF-8 bytes to a new file. |
+| `source check-url-updates` | write | Submit an asynchronous check for one compiled custom URL source; success means accepted only. |
 | `source check-updates` | write | Check one compiled Feishu source with the scheduled detector; mark changes without compiling. |
 | `+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. |
@@ -52,9 +55,30 @@ ae-cli kb source <replace|restore|preview|commit|cancel|check-updates> [options]
 | `+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. |
+| `usage list` | read | List one page of compilation usage logs, including elapsed time in milliseconds. |
 | `+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. |
 
+## Compilation Usage Logs
+
+```bash
+ae-cli kb usage list --name handbook --scope personal --page 1 --page-size 20
+ae-cli kb usage list --name handbook --jq '.items | map({createdAt, taskType, status, durationMs})' --format table
+```
+
+- Returns `{ items, total, page, pageSize }`. `--page` defaults to 1; `--page-size` defaults to 20 and accepts 1–100. Fetch each page explicitly.
+- `durationMs` is the usage log's `finishedAt - startedAt`, in milliseconds. A missing or invalid timestamp yields `null`; zero remains zero. Failed records can have duration even when `usageAvailable` is false.
+- Historical missing durations are not reconstructed from compile runs. `startedAt` and `finishedAt` are ISO timestamps or `null`.
+- Requires the same Schema-read permission as the Web compilation usage list. Imported snapshots do not expose usage. `--scope` selects exactly personal or company; omission keeps the existing personal-then-company lookup.
+- `--dry-run` previews the read without sending a request. Default output retains numeric/null values; use the existing `--jq` and `--format table` options for a compact table.
+
+Transition status: transitional
+Owning module: te-claude External Knowledge Base Usage API
+Current transport: authenticated External REST via `kbApi`
+Gateway target: TBD (compilation usage list)
+Review after: 2026-12-14
+Exit condition: migrate to the Gateway equivalent when available, preserving typed pagination and duration/null semantics.
+
 ## Published Version History
 
 Use the nine version commands described in [`references/versions.md`](references/versions.md) to inspect immutable published history, compare source changes, and explicitly roll back an earlier version as a new publication. These commands manage history; `+index/+grep/+read/+ask` continue to use current published content.
@@ -298,7 +322,7 @@ 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.
+**Before running a real query, read [`references/query-workflow.md`](references/query-workflow.md)** — it selects the next useful retrieval step without crawling. It covers candidate indexing, copied-path grep, direct bounded reads of linked short pages, same-page read windows, linked-page re-grep when needed, optional 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:
 
@@ -343,6 +367,10 @@ ae-cli kb +read \
   --expand block
 ```
 
+### Create, read or edit text sources
+
+Read [the text source workflow](references/text-sources.md) when collecting text, reading full editable source content, or updating an ordinary `.md`, `.markdown` or `.txt` source. It covers explicit scope, UTF-8/BOM/newline preservation, exclusive local output, revision conflicts, redacted dry-run and manual compilation. Web and CLI maintain the same source ID.
+
 ### List Sources
 
 List sources first to discover the stable identifier for the intended source:
@@ -354,10 +382,10 @@ ae-cli kb +list-sources --name engineering-handbook --scope company
 Copy the exact `id` from the response into `+rm-source`. Do not guess a source ID from a local filename, URL, display name, or an older upload response.
 
 - Transition status: transitional
-- Owning module: te-claude External Knowledge Base Sources API
-- Current transport: authenticated KB external REST through `kbApi`.
-- Gateway target: TBD (`kb.source.list` proposed)
-- Review after: 2026-12-03
+- Owning module: te-claude knowledge-base source management
+- Current transport: External Knowledge Base REST API
+- Gateway target: TBD
+- Review after: 2026-11-12
 - 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
@@ -441,7 +469,7 @@ ae-cli kb +grep --query "<keywords>" --sources '[{"scope":"company","name":"kb-n
 
 - `--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).
+- `--paths`: required JSON array of wiki pages or subdirectories **copied** from current `+index`, `+grep` or `+read` navigation links. Do not invent paths. 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 page entry in results carries `hitCount` (full match count), `pageKind`, and `sections` previews with `sectionStartLine` / `sectionEndLine` — use the section range as the `+read` window.
@@ -530,10 +558,11 @@ ae-cli kb +status --name "<name>" [--scope personal|company]
 ### `+list-sources`
 
 ```bash
-ae-cli kb +list-sources --name "<name>" [--scope personal|company]
+ae-cli kb +list-sources --name "<name>" [--scope personal|company] [--content-type all|text]
 ```
 
 - `--name`: required knowledge base name.
+- `--content-type`: defaults to `all`; `text` selects ordinary `.md`, `.markdown` and `.txt` sources (case-insensitive), excluding URL and ZIP sources. Scope remains optional for this list command.
 - Output: `items` contains effective sources with stable `id`. `pendingDeletions` contains soft-deleted sources still included in the current successful version. `deletionMaintenance` is separate and may report already-published deletions awaiting cleanup. Paths, hashes, credentials, and source content are not returned.
 - Check `deletionProjection.state` and its `baseline` before interpreting deletion lists. `ready` with `pendingDeletions: []` means no pending deletion at that baseline. `changing`, `review_required`, or `unavailable` with `pendingDeletions: null` means undetermined; display the `reasonCode`, never turn null into an empty list. Legacy libraries without a verifiable complete publication manifest return unavailable until a real version is published.
 - A rollback creates a new current version. An older deletion receipt cannot override membership in that version. A later source deletion needs publication again.
@@ -580,3 +609,24 @@ Transport: `POST /agent/api/external/knowledge-bases/sources/check-updates`, bod
 - Gateway target: TBD; reuse an equivalent source update-check capability when available.
 - Review after: 2026-10-16.
 - Exit condition: once the Gateway exposes equivalent authorization and detector semantics, migrate the typed command to L2 or use L3 if it adds no value.
+
+
+### Submit an ordinary URL update check
+
+```bash
+ae-cli kb source check-url-updates --name "Engineering Handbook" --id "<source-id>" --scope company --dry-run
+ae-cli kb source check-url-updates --name "Engineering Handbook" --id "<source-id>" --scope company
+```
+
+Only existing `sourceType=url`, `platform=custom`, compiled sources without pending updates qualify. The request is rejected while Wiki/Schema compilation or input preparation is active. Success returns `{accepted:true,sourceId}` and only means accepted. It has no final counts, task ID, checking state, wait mode or completion query. Read `kb +list-sources` for update markers; unchanged state cannot distinguish execution, no change, failure or a discarded result. When marked changed, explicitly run the existing incremental compile. Feishu continues to use synchronous `source check-updates`.
+
+Transport: `POST /agent/api/external/knowledge-bases/sources/check-url-updates`, body `{name,sourceId,scope?}`. Dry-run previews without sending a request. Submission errors preserve the server error code, details and nonzero exit.
+
+### Admission record: source check-url-updates
+
+- Transition status: transitional (this new KB external capability has no Gateway equivalent).
+- Owning module: te-claude knowledge-base source management.
+- Current transport: KB external REST through kbApi and CLI token.
+- Gateway target: TBD; reuse an equivalent asynchronous ordinary URL source-check capability.
+- Review after: 2026-10-24.
+- Exit condition: when the Gateway provides equivalent authorization and asynchronous submission semantics, migrate to L2 if typed flags add value, otherwise use L3.

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

@@ -1,10 +1,10 @@
 # Knowledge-guided analysis workflow
 
 Use this workflow after knowledge-base retrieval when the pages will guide a
-project-scoped business data analysis. The knowledge base determines which
-saved asset to execute, which business definition applies, and which
-conclusions are out of bounds. Current values still require an `ae-analysis`
-data query.
+project-scoped business data analysis. The knowledge base supplies candidate
+assets, verified definitions, and decision boundaries. Check their coverage of
+the user's original question before choosing execution. Current values still
+require an `ae-analysis` data query; a related KB page is not task completion.
 
 This workflow does not define knowledge-base compilation rules. Do not use it
 to create, upload, generate a schema for, compile, or delete a knowledge base.
@@ -89,25 +89,33 @@ pages actually read:
 | Decision boundaries | Case-only, frontend-only, adoption-only, not revenue, non-generalizable, expired, conflicting, or human-decision-required constraints |
 | KB evidence | Exact KB name, page path, and section actually read |
 
-Classify the contract before querying:
+Classify each candidate's coverage before querying. These states classify the
+asset, not completion of the original task:
 
 - `executable`: exact asset identity and semantics cover the question, with no
   unresolved conflict.
-- `partially_executable`: evidence covers only some subquestions; query and
-  answer only those parts.
+- `partially_executable`: evidence covers only some subquestions; execute the
+  applicable parts and retain their results, then continue discovery for the
+  uncovered parts.
+- `semantic_only`: read evidence supplies useful events, properties, or
+  limitations, but the candidate's definition cannot produce the requested
+  measure, entity, or scope. Retain that evidence and continue ordinary analysis.
 - `blocked`: a required asset, metric, aggregation, entity, filter, parameter,
-  time rule, or decision boundary is missing or conflicting; stop the affected
-  query and report the gap.
+  time rule, or decision boundary is missing or conflicting; do not execute
+  that unsupported definition. Continue discovery for the affected requirement
+  when an independently verified, authorized path remains possible.
 
 Do not fill a contract gap with general knowledge, a similarly named asset, or
-a technically valid query. When the task forbids clarification, return that the
-available evidence cannot answer the affected part instead of choosing an
-interpretation silently.
+a technically valid query. Resolve missing evidence through the ordinary
+analysis path below. If a material business choice remains ambiguous, request
+that choice once; if clarification is forbidden, disclose the unresolved part
+instead of choosing silently. Do not ask the user to authorize continuation of
+the same read-only data request merely because the KB covers only part of it.
 
 ## Execute the exact saved-asset chain
 
-An exact asset identified by a source page takes priority over fuzzy search and
-ad-hoc analysis:
+An exact, semantically applicable asset identified by a source page takes
+priority over fuzzy search and ad-hoc analysis:
 
 1. For a dashboard ID, call `analysis dashboard get` once with the verified
    project ID. Verify its name, child reports, `effective_settings`,
@@ -116,6 +124,10 @@ ad-hoc analysis:
 2. For a report ID, call `analysis report get` with the verified project ID.
    Verify its model, metric, aggregation, dimensions, filters, saved parameters,
    and time definition before querying data.
+   Definition inspection that establishes an unsuitable saved asset does not
+   require a data query to prove the mismatch. Record the incompatible fields
+   and continue ordinary discovery; do not execute a known wrong definition
+   merely to satisfy an attempt-first rule.
 3. Read the matching `ae-analysis` data-command reference before execution. Use
    [`report_data_run.md`](../../ae-analysis/references/report_data_run.md) for a
    bounded saved report result and
@@ -131,9 +143,9 @@ ad-hoc analysis:
    `ae-analysis`.
 6. For a metric or another saved asset, use its exact identity and corresponding
    command. Never replace it with a same-name object.
-7. Use the saved-asset discovery procedure from `ae-analysis` only when the KB
-   page provides no exact identity. A discovered candidate still requires
-   semantic equality, not title similarity.
+7. Use the saved-asset discovery procedure from `ae-analysis` when the KB
+   provides no suitable executable identity or leaves requirements uncovered.
+   A discovered candidate still requires semantic coverage, not title similarity.
 
 If the user asks for multiple groupings that one saved dynamic report supports,
 execute that same report once per required parameter variant. Keep the common
@@ -142,9 +154,11 @@ identical data command merely to inspect output that was locally truncated;
 capture or export the complete result through the supported data command.
 
 The statement "the KB contains definitions but not current values" means that
-the matched saved asset must be attempted first. It does not authorize jumping
-directly to a reconstructed SQL or ad-hoc query. If the attempt cannot produce
-a usable result, follow the explicit ordinary-analysis fallback below.
+an exact, semantically applicable saved asset must be attempted first. It does
+not require executing a related but unsuitable asset, nor authorize skipping
+saved-asset discovery directly to SQL. If inspection establishes a mismatch or
+execution cannot produce the requested result, follow the ordinary-analysis
+fallback below.
 
 When the live definition agrees with the KB, use the query result as data
 evidence and the KB page as routing, semantic, and boundary evidence.
@@ -173,9 +187,10 @@ definition or hide it with a replacement query.
 
 ## Fall back without hiding the knowledge-base result
 
-None of these conditions alone authorizes an ad-hoc or SQL reconstruction:
+These conditions require the state-specific handling and ordinary-analysis
+checks below; none alone establishes a verified ad-hoc or SQL definition:
 
-- The exact saved asset has not yet been attempted.
+- An applicable exact saved asset has not yet been attempted.
 - The exact saved asset returns an empty result.
 - The exact asset has a validation, transport, capability, or definition
   execution failure.
@@ -200,8 +215,8 @@ Handle these states without changing the contract:
   the input mapping allowed by its saved definition. Do not translate the report
   into SQL.
 - Partial success: retain successful saved-asset results and apply these rules
-  independently to each failed part. Do not discard valid sub-results or replace
-  the whole request with one reconstructed query.
+  independently to each failed or semantically uncovered part. Do not discard
+  valid sub-results or replace the whole request with one reconstructed query.
 - Permission denial: preserve the denied asset, error, and request ID. Do not
   retry the denied operation or use an undocumented lower-level API. The
   ordinary analysis fallback may still use another standard `ae-analysis`
@@ -222,8 +237,9 @@ Handle these states without changing the contract:
   may answer under a different, independently verified definition, but it must
   not claim to resolve the KB asset's conflict or present the result as
   definition-equivalent.
-- Fixed historical window: answer only for that window. If it cannot answer a
-  current-period question, state that it cannot be extrapolated.
+- Fixed historical window: do not extrapolate its values to the requested
+  period. If the window cannot be overridden, inspect alternatives through
+  ordinary analysis instead of presenting that window as the requested result.
 - Limited applicability: keep the conclusion within the declared scope. Do not
   expand adoption into revenue or intent, one module into the whole product, or
   one case into all customers.
@@ -234,25 +250,34 @@ applicable scope is not an equivalent validation.
 
 ## Degrade to the ordinary analysis path
 
-The KB path is preferred, not exclusive. If the exact KB-selected asset cannot
-produce the requested live result after a real attempt, continue as though no
-executable KB asset had been found and follow the ordinary `ae-analysis`
-"Existing business asset before ad-hoc" workflow:
+The KB path is preferred, not exclusive. If definition inspection establishes
+that the KB-selected asset cannot cover the request, or a real execution attempt
+cannot produce the requested live result, continue through the ordinary
+`ae-analysis` "Existing business asset before ad-hoc" workflow. Preserve the KB
+evidence and already verified definitions; do not restart from zero:
 
 1. Search for another accessible saved report or dashboard whose current live
    definition covers the request.
-2. Verify semantic equality before using it. A title match is not enough.
-3. If no saved definition matches, use ad-hoc analysis only when the normal
+2. Compare live definitions with the original request, including distinctions
+   such as creation versus creation-and-editing, user versus customer, and
+   event count versus distinct entity count. A title match is not enough.
+3. Follow [`metadata_resolution.md`](../../ae-analysis/references/metadata_resolution.md)
+   for uncovered definitions. Reuse verified KB and live-asset evidence; discover
+   only missing metadata, filters, dimensions, or scope. A missing descriptive
+   field does not invalidate independently supported action counts.
+4. If no saved definition matches, use authorized ad-hoc analysis only when the normal
    `ae-analysis` rules permit it and the required event, properties, metric,
    aggregation, entity, filters, time, and timezone can be established.
-4. Use only documented standard capabilities. Each fallback command remains
+5. Use only documented standard capabilities. Each fallback command remains
    subject to the backend's independent authorization checks.
 
 Fallback is available when the KB-selected asset is missing from the live
 project, inaccessible, empty for the requested scope, outside its supported
-time or breakdown, or persistently fails after the documented correction or
-retry path. The user does not need to restate the original data request merely
-to allow this ordinary fallback.
+time or breakdown, semantically unsuitable, missing requested fields or
+submetrics, or persistently fails after the documented correction or retry
+path. Technical success with a partial or wrong definition is also a coverage
+gap, not a reason to stop. The user does not need to restate the original data
+request merely to allow this ordinary fallback.
 
 Ad-hoc analysis must still satisfy the safety conditions below. SQL must also
 satisfy the additional SQL constraints in `ae-analysis`.
@@ -274,6 +299,18 @@ material difference from the KB-selected definition. Never claim that the KB
 asset produced a fallback result. An empty or denied KB result remains part of
 the audit record even when the fallback succeeds.
 
+## Check task completion
+
+Before answering, check each requirement of the original question against the
+actual definition and returned data. Finish when it is answered, or when bounded
+discovery establishes a concrete unavailable prerequisite, authorization
+boundary, or material choice requiring clarification. An asset state of
+`semantic_only`, `partially_executable`, or `blocked` is not by itself a terminal
+task state. Do not label creation-and-editing totals as pure creation, substitute
+another entity, or stop at a KB limitation while verified metadata supports a
+remaining authorized query. Keep genuine unknown fields unknown and label
+partial results explicitly; do not broaden an empty result merely to get rows.
+
 ## Answer with traceable boundaries
 
 Make these three layers distinguishable in the final answer: