@thinkingai/ae-cli 6.0.53 → 6.0.54

package/skills/ae-analysis/scripts/project-semantic-knowledge-wiki/refresh-state-parts.mjs

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { brotliCompressSync, brotliDecompressSync, constants } from 'node:zlib';
+import { createHash } from 'node:crypto';
+
+const PART_DATA_LENGTH = 15_000;
+const MAX_PART_BYTES = 16 * 1024;
+const MAX_PAYLOAD_BYTES = 64 * 1024 * 1024;
+const INDEX_MARKER = /<!-- pskb_refresh_state_index\n([^\n]+)\n-->/;
+
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+
+export function readLegacyRefreshState(content) {
+  const match = String(content).match(/<!-- pskb_refresh_state_base64\n([A-Za-z0-9_=\-\s]+)\n-->/);
+  if (!match) throw new Error('Refresh state payload is missing.');
+  return JSON.parse(Buffer.from(match[1].replace(/\s+/g, ''), 'base64url').toString('utf8'));
+}
+
+export function readRefreshStateIndex(content) {
+  const match = String(content).match(INDEX_MARKER);
+  if (!match) return null;
+  if (Buffer.byteLength(content) > MAX_PART_BYTES) throw new Error('Refresh state index exceeds 16 KiB.');
+  const index = JSON.parse(match[1]);
+  if (index.schema_version !== '2.0' || index.encoding !== 'brotli-base64url'
+      || !/^[a-f0-9]{64}$/.test(index.payload_sha256)
+      || !/^[a-f0-9]{64}$/.test(index.normalized_content_hash)
+      || !Number.isInteger(index.payload_bytes) || index.payload_bytes < 1 || index.payload_bytes > MAX_PAYLOAD_BYTES
+      || !Array.isArray(index.parts) || !index.parts.length) {
+    throw new Error('Invalid refresh state index.');
+  }
+  const seen = new Set();
+  for (const part of index.parts) {
+    if (!/^[-a-z0-9]+-refresh-state-part-\d{3}\.md$/.test(part.file)
+        || !/^[a-f0-9]{64}$/.test(part.sha256)
+        || !Number.isInteger(part.bytes) || part.bytes < 1 || part.bytes > MAX_PART_BYTES
+        || seen.has(part.file)) throw new Error('Invalid refresh state part metadata.');
+    seen.add(part.file);
+  }
+  return index;
+}
+
+export function encodeRefreshState(content, statePath, normalizedContentHash, baseline = null) {
+  if (!/^[a-f0-9]{64}$/.test(normalizedContentHash)) throw new Error('Invalid normalized refresh state hash.');
+  const payload = readLegacyRefreshState(content);
+  if (baseline) payload.source_tree_baseline = baseline;
+  const raw = Buffer.from(JSON.stringify(payload));
+  const encoded = brotliCompressSync(raw, { params: { [constants.BROTLI_PARAM_QUALITY]: 11 } }).toString('base64url');
+  const stem = path.posix.basename(statePath, '.md');
+  const parts = [];
+  for (let offset = 0; offset < encoded.length; offset += PART_DATA_LENGTH) {
+    const number = parts.length + 1;
+    const file = `${stem}-part-${String(number).padStart(3, '0')}.md`;
+    const data = encoded.slice(offset, offset + PART_DATA_LENGTH);
+    const partContent = `# Refresh State Part ${number}\n\nMachine state only. Do not compile as business evidence.\n\n<!-- pskb_refresh_state_part\n${data}\n-->\n`;
+    const bytes = Buffer.byteLength(partContent);
+    if (bytes > MAX_PART_BYTES) throw new Error('Refresh state part exceeds 16 KiB.');
+    parts.push({ file, path: path.posix.join(path.posix.dirname(statePath), file), content: partContent, sha256: sha256(partContent), bytes });
+  }
+  const index = {
+    schema_version: '2.0', encoding: 'brotli-base64url', payload_sha256: sha256(raw),
+    payload_bytes: raw.length, normalized_content_hash: normalizedContentHash,
+    parts: parts.map(({ file, sha256: hash, bytes }) => ({ file, sha256: hash, bytes })),
+  };
+  const indexContent = `# Refresh State\n\nMachine state index. Do not compile as business evidence. Read parts only with the CLI refresh-state reader.\n\n<!-- pskb_refresh_state_index\n${JSON.stringify(index)}\n-->\n`;
+  if (Buffer.byteLength(indexContent) > MAX_PART_BYTES) throw new Error('Refresh state index exceeds 16 KiB.');
+  return { indexContent, parts };
+}
+
+export function decodeRefreshState(content, indexFile) {
+  const index = readRefreshStateIndex(content);
+  if (!index) return { payload: readLegacyRefreshState(content), index: null };
+  const stem = path.basename(indexFile, '.md');
+  const chunks = index.parts.map((part, position) => {
+    if (part.file !== `${stem}-part-${String(position + 1).padStart(3, '0')}.md`) {
+      throw new Error(`Unexpected refresh state part name: ${part.file}.`);
+    }
+    const file = path.join(path.dirname(indexFile), part.file);
+    const data = fs.readFileSync(file);
+    if (data.length !== part.bytes || data.length > MAX_PART_BYTES || sha256(data) !== part.sha256) {
+      throw new Error(`Refresh state part checksum mismatch: ${part.file}.`);
+    }
+    const match = data.toString('utf8').match(/<!-- pskb_refresh_state_part\n([A-Za-z0-9_-]+)\n-->/);
+    if (!match) throw new Error(`Invalid refresh state part: ${part.file}.`);
+    return match[1];
+  });
+  const raw = brotliDecompressSync(Buffer.from(chunks.join(''), 'base64url'), { maxOutputLength: MAX_PAYLOAD_BYTES });
+  if (raw.length !== index.payload_bytes || sha256(raw) !== index.payload_sha256) {
+    throw new Error('Refresh state payload checksum mismatch.');
+  }
+  return { payload: JSON.parse(raw.toString('utf8')), index };
+}

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.