@thinkingai/ae-cli 6.0.55 → 6.0.57

package/skills/ae-evaluation/references/runs.md

@@ -0,0 +1,160 @@
+# Evaluation runs and results
+
+Commands use `ae-cli evaluation +<command>`. Read the shared endpoint, authentication, and mutation rules in [SKILL.md](../SKILL.md). Use command `--help` for optional flags.
+
+Run cancellation is a high-risk write and requires confirmation. Non-interactive cancellation requires explicit authorization and global `--yes`; use `--dry-run` to preview without cancelling.
+
+### Evaluation runs
+
+```bash
+ae-cli evaluation +list_runs [--search <text>] [--status <status>] [--cursor <cursor>] [--limit 50]
+ae-cli evaluation +get_run --id <run-uuid>
+ae-cli evaluation +create_run --name "<name>" \
+  [--dataset-id <uuid>] --dataset-version-id <dataset-version-uuid> \
+  [--execution-mode LIVE_AGENT|PRESET_RESULT] [--subject-type AGENT|MODEL] \
+  [--agent-config-id <uuid>] [--model-config-id <uuid>] \
+  [--report-to-te true] \
+  [--field-mapping-json '<json>'] [--result-filter-fields-json '<json>'] \
+  [--pass-threshold 0.8] [--case-sample-size 100] [--idempotency-key "<key>"]
+ae-cli evaluation +update_run --id <run-uuid> --name "<name>" [same optional fields as +create_run] --lock-version <n>
+ae-cli evaluation +delete_run --id <run-uuid> --lock-version <n>
+ae-cli evaluation +select_run_evaluators --id <run-uuid> --evaluator-ids '["<evaluator-uuid>"]' \
+  [--evaluator-versions-json '[{"evaluator_id":"<uuid>","version_id":"<uuid>"}]'] --lock-version <n>
+ae-cli evaluation +list_run_evaluators --id <run-uuid>
+ae-cli evaluation +update_run_field_mapping --id <run-uuid> --field-mapping-json '<json>' --lock-version <n>
+ae-cli evaluation +update_run_result_filter_fields --id <run-uuid> --result-filter-fields-json '{"fields":[],"schema_version":"RESULT_FILTER_FIELDS_V1"}' --lock-version <n>
+ae-cli evaluation +validate_run --id <run-uuid>
+ae-cli evaluation +start_run --id <run-uuid> --lock-version <n>
+ae-cli evaluation +cancel_run --id <run-uuid> --lock-version <n>
+ae-cli evaluation +retry_failed_run_cases --id <run-uuid> --lock-version <n>
+ae-cli evaluation +run_overview --id <run-uuid>
+ae-cli evaluation +run_distribution --id <run-uuid> [--run-evaluator-id <uuid>]
+ae-cli evaluation +run_cases --id <run-uuid> \
+  [--status <status>] [--evidence-completeness NONE|PARTIAL|COMPLETE|UNKNOWN] [--search <text>] \
+  [--evaluation-status <status>] [--score-status <status>] [--evaluator-id <uuid>] \
+  [--evaluator-ids '["<uuid>"]'] [--min-score 0.8] [--max-score 1] [--score-gte 0.2] [--score-lte 0.8] \
+  [--field-filters-json '[...]'] [--sort AVERAGE_SCORE] [--sort-evaluator-id <uuid>] [--order desc] \
+  [--cursor <cursor>] [--limit 50] [--offset 0]
+ae-cli evaluation +get_run_case --id <run-uuid> --case-run-id <case-run-uuid>
+ae-cli evaluation +get_run_case_trace --id <run-uuid> --case-run-id <case-run-uuid>
+ae-cli evaluation +retry_run_case_trace --id <run-uuid> --case-run-id <case-run-uuid>
+ae-cli evaluation +copy_run_case --id <run-uuid> --case-run-id <case-run-uuid>
+ae-cli evaluation +transfer_run_owner --id <run-uuid> --owner-user-id <user-uuid> --lock-version <n>
+ae-cli evaluation +list_project_members
+ae-cli evaluation +create_next_task_version_draft --id <run-uuid>
+ae-cli evaluation +list_evaluation_task_versions --task-id <task-uuid>
+ae-cli evaluation +export_run_results --id <run-uuid> [--export-format CSV|JSONL] --idempotency-key "<fresh-key>"
+ae-cli evaluation +export_run_low_scores --id <run-uuid> --max-score 0.5 [--min-score 0] [--status SUCCEEDED] [--export-format CSV|JSONL] --idempotency-key "<fresh-key>"
+ae-cli evaluation file download --id <file-uuid> --output ./results.csv
+ae-cli evaluation +get_file --id <file-uuid>
+```
+
+- Field mapping JSON follows the platform `FIELD_MAPPING_V*` contract (`FIELD_MAPPING_V5` adds `TEMPLATE` input and `AGENT_TOOL_SUMMARY` / `AGENT_ARTIFACT_SUMMARY` / `AGENT_EXECUTION_STATUS` evidence sources); result-filter-fields is `RESULT_FILTER_FIELDS_V1` with at most 5 fields. Do not guess shapes — inspect an existing run with `+get_run` for a working example.
+- `--case-sample-size` randomly selects 1-1000 cases when the run starts; omit it to run every case. Start fails with `RUN_SAMPLE_SIZE_EXCEEDS_CASES` when the requested sample exceeds the selected dataset version's case count.
+- Start prerequisites: bound evaluator(s) (`EVALUATOR_NOT_ACTIVE`), complete field mapping (`FIELD_MAPPING_INCOMPLETE`), and result filter fields — an explicit empty filter is required (`RESULT_FILTER_FIELD_UNAVAILABLE`).
+- Retry semantics: `+retry_failed_run_cases` requeues only Agent-stage `FAILED|BLOCKED|UNKNOWN` cases in the same immutable snapshot, bumps the execution epoch and recomputes aggregates. `+retry_run_case_trace` is ADMIN-only and only for retryable AI Monitor-backed captures.
+- `+create_next_task_version_draft` copies `case_sample_size` and selects the latest published evaluator versions for the new draft. Run and overview responses expose separate succeeded, failed, and cancelled case/score counts for progress tracking.
+
+### Create and run an evaluation
+
+1. Pick a published dataset version and create a draft run from it plus an agent or model:
+
+```bash
+ae-cli evaluation +list_dataset_versions --id <dataset-uuid>
+ae-cli evaluation +create_run \
+  --name "release-checkout-run" \
+  --dataset-id <dataset-uuid> \
+  --dataset-version-id <dataset-version-uuid> \
+  --execution-mode LIVE_AGENT \
+  --subject-type AGENT \
+  --agent-config-id <agent-uuid>
+```
+
+For scoring pre-stored dataset fields without calling an Agent/Model, use `--execution-mode PRESET_RESULT` (then omit `--agent-config-id` / `--model-config-id`).
+
+2. Configure the draft. Before `+start_run` the run needs: at least one ACTIVE evaluator (pin published evaluator versions when possible), a complete field mapping, and result filter fields (an explicit empty filter is fine). Each mutation consumes one lock_version — re-read with `+get_run` in between:
+
+```bash
+ae-cli evaluation +list_evaluator_versions --id <evaluator-uuid>
+ae-cli evaluation +select_run_evaluators --id <run-uuid> \
+  --evaluator-ids '["<evaluator-uuid>"]' \
+  --evaluator-versions-json '[{"evaluator_id":"<evaluator-uuid>","version_id":"<evaluator-version-uuid>"}]' \
+  --lock-version <n>
+ae-cli evaluation +get_run --id <run-uuid>
+ae-cli evaluation +update_run_field_mapping --id <run-uuid> \
+  --field-mapping-json '{"schema_version":"FIELD_MAPPING_V5","agent":{"input":{"field_key":"input","source_type":"DATASET_FIELD"}},"evaluators":{"<evaluator-uuid>":{"input":{"field_key":"input","source_type":"DATASET_FIELD"},"output":{"source_type":"AGENT_OUTPUT"}}}}' \
+  --lock-version <n>
+ae-cli evaluation +get_run --id <run-uuid>
+ae-cli evaluation +update_run_result_filter_fields --id <run-uuid> \
+  --result-filter-fields-json '{"fields":[],"schema_version":"RESULT_FILTER_FIELDS_V1"}' \
+  --lock-version <n>
+```
+
+3. Validate (optional, same preflight as start, no lock_version needed), then start:
+
+```bash
+ae-cli evaluation +validate_run --id <run-uuid>
+ae-cli evaluation +get_run --id <run-uuid>
+ae-cli evaluation +start_run --id <run-uuid> --lock-version <n>
+```
+
+4. Watch the results and drill into failures:
+
+```bash
+ae-cli evaluation +run_overview --id <run-uuid>
+ae-cli evaluation +run_distribution --id <run-uuid> --run-evaluator-id <run-evaluator-uuid>
+ae-cli evaluation +run_cases --id <run-uuid> --status FAILED --evaluation-status FAILED
+ae-cli evaluation +get_run_case --id <run-uuid> --case-run-id <case-run-uuid>
+ae-cli evaluation +get_run_case_trace --id <run-uuid> --case-run-id <case-run-uuid>
+ae-cli evaluation +retry_failed_run_cases --id <run-uuid> --lock-version <n>
+```
+
+### Export results and download
+
+```bash
+ae-cli evaluation +export_run_results --id <run-uuid> --export-format CSV --idempotency-key "export-$(date +%s)"
+ae-cli evaluation +export_run_low_scores --id <run-uuid> --max-score 0.5 --idempotency-key "low-$(date +%s)"
+# Poll the returned file until COMPLETED before downloading.
+ae-cli evaluation +get_file --id <file-uuid>
+ae-cli evaluation file download --id <file-uuid> --output ./results.csv
+```
+
+Traces are available only for LIVE_AGENT runs with subject AGENT. Capture status is independent of case/run success. Captures contain at most 500 spans and may be truncated; PARTIAL or reference-only evidence must not be described as complete. Never include hidden chain-of-thought, credentials, cookies, auth headers, or unredacted tool input/output in reports. Ownership transfer and project-member discovery require ADMIN.
+
+### Process evidence mapping (FIELD_MAPPING_V6)
+
+For LIVE_AGENT runs whose subject is AGENT, V6 adds `AGENT_EXECUTION_TRACE` and
+`AGENT_TOOL_CALLS`. Keep the existing V5 mappings for final-output-only scoring.
+Use real dataset field keys, evaluator IDs and a published evaluator version:
+
+```json
+{
+  "schema_version": "FIELD_MAPPING_V6",
+  "agent": {"input": {"source_type": "DATASET_FIELD", "field_key": "input"}},
+  "evaluators": {
+    "<evaluator-uuid>": {
+      "input": {"source_type": "DATASET_FIELD", "field_key": "input"},
+      "output": {"source_type": "AGENT_OUTPUT"},
+      "execution_trace": {"source_type": "AGENT_EXECUTION_TRACE"}
+    }
+  }
+}
+```
+
+An evaluator declaring `tool_calls` may map it to `{ "source_type": "AGENT_TOOL_CALLS" }`.
+Only map variables the evaluator declares. Send the complete mapping through
+`+update_run_field_mapping` with the latest lock version, validate, then start.
+
+The process projection is `PROCESS_EVIDENCE_V1`; TE Claude A2A tool artifacts use
+`TE_CLAUDE_TOOL_CALLS_V1`. Scoring requires a READY/COMPLETE/non-truncated snapshot
+from the current execution epoch and limits the projection to 64 KiB. Missing,
+pending or unusable evidence fails only the dependent score with a null score;
+Agent status stays independent and final-output evaluators can still score.
+
+Score `input_variables` holds resource references (`content_location=CASE_EXECUTION_TRACE`),
+not full tool payloads. Inspect `+get_run_case_trace` separately. TE Claude evidence
+covers recorded tool/sub-Agent calls and explicit parent-child relationships,
+not hidden model reasoning, delegated internal steps, timing or cost. Preserve
+redaction and completeness limits when reporting results.
+
+See [files.md](files.md) for authenticated downloads and file readiness checks.

package/skills/ae-evaluation/references/schedules.md

@@ -0,0 +1,31 @@
+# Scheduled evaluations
+
+Commands use `ae-cli evaluation +<command>`. Read the shared endpoint, authentication, and mutation rules in [SKILL.md](../SKILL.md). Use command `--help` for optional flags.
+
+### Schedules
+
+```bash
+ae-cli evaluation +list_schedules [--status PENDING|PROCESSING|COMPLETED|FAILED|CANCELLED] [--cursor <cursor>] [--limit 50]
+ae-cli evaluation +create_schedule --run-id <run-uuid> --frequency HOURLY|DAILY|WEEKLY|MONTHLY --time-zone <iana> \
+  [--minute-of-hour 0] [--hour-of-day 9] [--day-of-week 1] [--day-of-month 1]
+ae-cli evaluation +update_schedule --id <schedule-uuid> --frequency <freq> --time-zone <iana> \
+  [--minute-of-hour 0] [--hour-of-day 9] [--day-of-week 1] [--day-of-month 1] --lock-version <n>
+ae-cli evaluation +delete_schedule --id <schedule-uuid> --lock-version <n>
+```
+
+HOURLY runs at minute 0 and must omit `--minute-of-hour` (or send 0). DAILY/WEEKLY/MONTHLY require `--minute-of-hour`. Schedules pin published task versions.
+
+### Scheduled evaluations
+
+```bash
+ae-cli evaluation +list_schedules
+ae-cli evaluation +create_schedule \
+  --run-id <run-uuid> \
+  --frequency DAILY \
+  --time-zone Asia/Shanghai \
+  --hour-of-day 9 \
+  --minute-of-hour 0
+ae-cli evaluation +update_schedule --id <schedule-uuid> --frequency WEEKLY --time-zone Asia/Shanghai \
+  --day-of-week 1 --hour-of-day 9 --minute-of-hour 0 --lock-version <n>
+ae-cli evaluation +delete_schedule --id <schedule-uuid> --lock-version <n>
+```

package/skills/ae-kb/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-kb
-version: 1.0.4
+version: 1.0.8
 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.'
 ---
 
@@ -17,6 +17,10 @@ ae-cli kb +<command> [options]
 ae-cli kb source <create-text|read-text|replace|restore|preview|commit|cancel|check-updates|check-url-updates> [options]
 ```
 
+## Formal publication and pinned reads
+
+Read [Publication and read contexts](references/publication.md) for company approval, personal auto-publication, candidate inspection and changed-only approval previews (`kb candidate changes`), explicit published queries, or consistent multi-command retrieval. Compile success can mean a candidate awaiting approval; use `kb publication get` to verify formal publication. Never treat the working build status as proof that the formal version changed.
+
 ## 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.
@@ -41,7 +45,8 @@ ae-cli kb source <create-text|read-text|replace|restore|preview|commit|cancel|ch
 | `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. |
+| `+ask-status` | read | Query an ask execution, or revisit its original versioned citation with `--source-index`. |
+| `project-target get` | read | Resolve the authoritative company project semantic target by project ID, including tag conflicts, disabled and restricted states. |
 | `+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. |
@@ -59,6 +64,26 @@ ae-cli kb source <create-text|read-text|replace|restore|preview|commit|cancel|ch
 | `+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. |
 
+## Project Semantic Target
+
+```bash
+ae-cli kb project-target get --project-id <project_id> --host <host>
+ae-cli kb +new --scope company --name <name> --project-id <project_id> --purpose project-semantic
+```
+
+Use `project-target get` for project semantic maintenance; `+list` remains a visible catalog and cannot prove that a project target is missing. The server verifies project access and considers all undeleted company candidates bound to that project, without filtering by enabled state or build state. One candidate is reused for legacy compatibility. With several candidates, exactly one fixed business tag `项目语义` selects the target; zero returns `multiple/untagged`, several returns `multiple/tag_conflict`. With no binding, the authoritative exact name `<project_name> 项目语义知识库` without another project binding is the legacy fallback, using the same tag rule.
+
+`available` returns the exact target identity and access capabilities. `restricted`, `disabled`, and `multiple` stop maintenance; never select a different visible KB or create a replacement. Only `missing` permits creation. A query/auth failure or HTTP 404 from an older server is terminal; do not infer absence. Existing explicit target IDs, including stored automation targets, must not be silently switched.
+
+`+new --purpose project-semantic` is optional and company-only, requires one valid project ID, presets the fixed tag on both client and server, and rechecks the target under the server KB write lock. User tags are preserved within the existing total limit of two; overflow fails explicitly. A 409 means refresh the target, not retry with a different name. Ordinary creation without `--purpose` retains its existing behavior. The tag classifies purpose and never grants access. Deploy the supporting Agent API before using the new CLI/Skill path; old CLI requests remain accepted by the new server.
+
+Transition status: transitional
+Owning module: te-claude Project Semantic Knowledge Base API
+Current transport: authenticated Agent REST via `kbApi`
+Gateway target: TBD (project semantic target resolution and purpose-aware creation)
+Review after: 2027-01-27
+Exit condition: migrate when the KB Gateway equivalent exists, preserving target identity, project isolation, tag and state semantics.
+
 ## Compilation Usage Logs
 
 ```bash
@@ -81,7 +106,7 @@ Exit condition: migrate to the Gateway equivalent when available, preserving typ
 
 ## 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.
+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. Ordinary queries resolve formal published content; Agent/Ask executions and explicit read contexts keep the formal versions captured at the start of that execution or context. Use the returned `readView` to identify the content actually read.
 
 | Command | Risk | Purpose |
 | --- | --- | --- |
@@ -250,7 +275,7 @@ ae-cli kb +schema --name engineering-handbook --scope company
 
 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.
 
-Schema and Compile accept the same optional model reference. Prefer the model record `id` returned by `ae-cli agent +list-models` (`Model.id`). Historical `modelId` and the unambiguous `modelId::scope` form remain compatible. A model `displayName` is presentation text, not a stable reference.
+Schema and Compile accept the same optional model reference. By default, omit `--model` / `--model-id` and keep the existing KB default selection. Preserve an explicit choice from the user or task configuration. Never infer a model reference from the assistant's self-description. `company-auto` means the Company Auto routing policy, not a physical model; use the canonical reference `virtual:company-auto:v1` for compatibility with older servers. Prefer the model record `id` returned by `ae-cli agent +list-models` (`Model.id`). Historical `modelId` and the unambiguous `modelId::scope` form remain compatible. A model `displayName` is presentation text, not a stable reference.
 
 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.
 
@@ -258,7 +283,6 @@ To add one-time guidance for this generation without changing stored knowledge b
 ae-cli kb +schema \
   --name engineering-handbook \
   --scope company \
-  --model <model-ref> \
   --custom-instructions "Prioritize troubleshooting workflows and preserve command examples"
 ```
 
@@ -267,7 +291,7 @@ Use `--dry-run` to inspect the request body before sending it. While generation
 Compile after sources and schema are ready:
 
 ```bash
-ae-cli kb +compile --name engineering-handbook --scope company --mode incremental --model <model-ref>
+ae-cli kb +compile --name engineering-handbook --scope company --mode incremental
 ```
 
 Valid compile modes are `incremental` and `full`; default is `incremental`.
@@ -440,6 +464,9 @@ ae-cli kb +ask-status --execution-id <id>
 ```
 
 - `--execution-id`: required. The execution ID returned by `+ask` submission.
+- `--source-index`: optional zero-based `sourceIndex` from `sources[].reference`. Returns that saved page's `content`, `path`, and public `readView`, at the original published version even after a new publication. Uses your current user permissions; query credentials are not revived. Legacy or old sources without an immutable version return `KB_REFERENCE_UNVERSIONED`; do not replace this with a fresh `+read` and call it the original citation.
+- Completed Ask sources preserve `{knowledgeBaseKey, path, readView?, reference?}`. Keep `readView.versionId/versionNumber` when citing them. To revisit: `ae-cli kb +ask-status --execution-id <reference.executionId> --source-index <reference.sourceIndex>`.
+- Historical source reads are unavailable inside an execution that requires a fixed KB context (`KB_READ_CONTEXT_REFERENCE_FORBIDDEN`). Do not bypass this by removing execution context or using an ordinary token. Revisit outside that execution with current user credentials. Ordinary `+ask-status` polling without `--source-index` remains available.
 - Output: Returns one successful CLI envelope snapshot. For a failed execution, the stable server code remains at `data.error.code`: `{"ok":true,"data":{"executionId":"...","status":"failed","error":{"code":"retrieval_error","message":"..."}}}`. Does not poll.
 
 ### `+list`

package/skills/ae-kb/references/publication.md

@@ -0,0 +1,81 @@
+# Publication and read contexts
+
+Source-managed personal KBs publish automatically after a successful compile. Company KBs produce an immutable candidate and automatically submit `kb.version.publish@1`; an authorized current content editor (including the requester) approves through the existing approval workflow. Editing working sources after compilation does not change the candidate. Approval publishes that frozen candidate without overwriting working edits. No feature switch is required.
+
+## Inspect and manage
+
+| Command | Purpose | Risk |
+| --- | --- | --- |
+| `ae-cli kb publication get` | Formal version and candidate summary | read |
+| `ae-cli kb candidate get` | Candidate metadata | read |
+| `ae-cli kb candidate changes` | Changed sources, Wiki and Index; optional bounded text diff | read |
+| `ae-cli kb candidate read` | Immutable candidate file | read |
+| `ae-cli kb candidate discard` | Close a confirmed failed candidate | high-risk-write |
+| `ae-cli kb +rm-source` | Delete a source, optionally cancelling its pending candidate | high-risk-write |
+| `ae-cli kb read-context create` | Pin authorized formal views | read |
+| `ae-cli kb read-context release` | Release the current user's context | write |
+
+- `ae-cli kb publication get --name <verified-name> [--scope personal|company]`: formal version and active candidate summary.
+- `ae-cli kb candidate get --name <verified-name> [--scope ...] --candidate <id>`: candidate metadata.
+- `ae-cli kb candidate read --name <verified-name> [--scope ...] --candidate <id> --path <verified-path>`: immutable candidate index.md, CLAUDE.md or wiki Markdown. Candidate preview requires current content-write permission; it is not a formal query.
+- `ae-cli kb candidate discard --name <verified-name> [--scope ...] --candidate <id> --yes`: `high-risk-write`; discard a candidate after a confirmed retryable publication failure. Pending requests use approval cancel. A running or uncertain publication cannot be discarded.
+- When source deletion conflicts with a pending candidate, explicitly combine `ae-cli kb +rm-source --name <verified-name> --id <source-id> --cancel-candidate --expected-candidate-id <id> --yes`. This is `high-risk-write`; both flags are required. A changed candidate causes a conflict; inspect again instead of silently deleting it.
+
+## Review compilation changes
+
+```bash
+ae-cli kb candidate changes --name 'Verified KB' --scope company --candidate '<candidateId>'
+ae-cli kb candidate changes --name 'Verified KB' --scope company --candidate '<candidateId>' --entry-id '<entryId>'
+ae-cli kb candidate changes --name 'Verified KB' --scope company --candidate '<candidateId>' --entry-id '<entryId>' --file '<returned-member-path>' --context 3
+```
+
+The list returns `candidateId`, the fixed `baseline`, `status`, `firstPublication`, `entries` and `summary`. Only changed sources, Wiki pages and Index are included; compilation rules and historical comparison are outside this preview. Copy entry IDs and member paths from actual responses. `--file` requires `--entry-id`; `--context` is 0 (default, changes only) or 3 (adjacent unchanged lines).
+
+Entry details include changed source `fields`, changed `files`, `selectedFile`, `preview` and bounded `hunks`. The first changed file is selected by default; choose other returned members explicitly. Binary files return metadata; text over 1 MB or a complex diff has an explicit preview status. These states are not proof of unchanged contents. A legacy publication without a reconstructible frozen baseline returns `status=baseline_unavailable` and `summary=null`; missing/corrupt snapshots, forbidden access and invalid selections fail explicitly. Never substitute current working files. Successful first publication is shown entirely as added. The endpoint requires the same current content-write permission as candidate reads. Existing `candidate get/read` calls remain unchanged. Unsupported older Hosts return an error; do not fall back to comparing mutable content.
+
+`--dry-run` shows the GET path and validated selectors without remote access. This new command uses the same Transitional admission and migration exit below.
+
+## Query a stable formal view
+
+`ae-cli kb +list --view published` creates a temporary context, queries, then releases it. Old Hosts without context support fail explicitly. The legacy `kb +list` default remains `buildStatus=compiled`; published/contextual list omits only this implicit filter. Explicit `--build-status` still applies.
+
+For several related reads:
+
+```bash
+ae-cli kb read-context create --sources '[{"scope":"company","name":"Verified KB"}]'
+ae-cli kb +index --name 'Verified KB' --scope company --read-context '<readContextId>'
+ae-cli kb +read --name 'Verified KB' --scope company --path 'wiki/verified.md' --read-context '<readContextId>'
+ae-cli kb read-context release --id '<readContextId>'
+```
+
+Create accepts optional `--sources` array of `{scope,name}` and `--locale zh|en|ja|ko`. Omission discovers currently authorized formal KBs. Contexts last 15 minutes and bind list/index/grep/read to the selected formal versions. Sources, permissions, KB lifecycle and actor identity remain checked on every read. Release is owner-only and idempotent for an expired context. Do not manufacture version IDs, storage keys or context IDs.
+
+For an expired or mismatched context, stop the sequence. A new explicit sequence may create a new context, but must not mix its results with prior context results. New snapshot-mode KBs with no published version are unpublished; an inconsistent formal pointer fails rather than falling back to working files.
+
+Inside an Agent/Ask execution the runtime supplies a private execution context. The CLI automatically uses its scoped credential for the four query commands; do not read, print, copy or replace this credential. Missing/expired/mismatched runtime credentials fail closed, including on 401. Management commands continue using normal CLI authorization. Runtime capability negotiation is protocol validation, not a user feature toggle.
+
+## Copy and export
+
+A new company-copy approval freezes the current personal formal version when its Effect first executes. Retries reuse the same version and target identity. Later source changes do not alter the copy.
+
+`ae-cli agent resource-package export --view working|published ...` defaults to working. Working exports preserve editable sources/schema and omit stale generated wiki. Published exports use one frozen formal snapshot and matching source metadata. Export retries reuse the frozen dependency closure. Editable imports start with pending sources and no published version; read-only compiled imports keep their established serving behavior.
+
+## Command admission
+
+- Classification: Transitional.
+- Owning module: te-claude knowledge-base publication and query-context management; CLI owner: te-cli te-kb.
+- Current transport: authenticated External REST through `kbApi`; runtime query calls additionally require the scoped context credential and header.
+- Gateway target: an equivalent KB publication/candidate/read-context capability with the same current-editor checks, immutable candidates, idempotency, and fail-closed query binding; no equivalent is currently registered.
+- Review after: 2026-11-25.
+- Exit condition: when Gateway provides these semantics, migrate value-adding typed commands to L2 and simple wrappers to L3. Preserve existing command compatibility during migration.
+- Write safety: candidate discard and combined source deletion require explicit `--yes`, current write permission and candidate identity checks. Context release is owner-scoped and idempotent; request preview is local and does not claim remote validation.
+
+### Large change sets and first publication
+
+Use `kb candidate changes --group sources|wiki|index --search <name-or-path> --change added|modified|deleted --offset 0 --limit 50` for a bounded directory page. `summary` and `groups` describe all changes; `page.total` describes entries matching the filters. Omitting these flags preserves the existing full-list call. A detail request uses `--entry-id`; `--file-search`, `--file-offset` and `--file-limit` page the changed members. `--file` selects an exact changed member independent of member pagination.
+
+The first successful source-managed KB compilation now publishes automatically, including company KBs. Later company updates require approval. Empty version pointers alone do not prove a first publication: legacy formal content and historical versions still require review. Existing eligible first-publication pending requests are withdrawn by the server with a system audit and the same frozen candidate is published; do not approve or create another compilation to force this transition. Already decided requests are not converted. `publication get` and `candidate get` remain read-only and expose the current publication state; an automatically published candidate is still readable by its known ID.
+
+Text and Markdown members return changed hunks. Small, unambiguous CSV/TSV changes may additionally include `table` containing only changed rows. ZIP and URL/Feishu sources expose changed frozen members; PDF, Office, images, invalid UTF-8 and oversized content explicitly return metadata/limit status rather than a fabricated textual diff. No source URL is fetched during preview.
+
+Compatibility: deploy the matching server before using new paging flags. Old CLI requests continue to work on the new server. New flags against older servers fail explicitly with `KB_CANDIDATE_PAGING_UNSUPPORTED` when `page` or `filePage` is missing; the CLI never treats an unfiltered old response as a filtered result.

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

@@ -140,7 +140,20 @@ A revision or access-context change requires revalidation, not silent reuse.
 5. **Assess coverage, then answer or iterate.** Map the user's question into
    subquestions and check each one against the sections you actually read. If a
    subquestion is covered, answer with citations (knowledge base + page path +
-   section). If a gap remains, go back to step 2 with another set of `--paths`
+   section, plus the returned `readView.versionId/versionNumber` for snapshots).
+   For `version_pinned` results, describe consistency within that captured view.
+   Unchanged `versionId/readIdentity` proves that the reads used the same snapshot;
+   it does not establish whether a newer publication or rollback occurred outside
+   the execution. Claims about the latest formal version require separate current
+   publication evidence obtained through an authorized management workflow.
+   Preserve version identity with the reference; a fresh read of the same path is
+   not a historical citation read. For completed Ask sources with `reference`, use
+   `ae-cli kb +ask-status --execution-id <reference.executionId> --source-index <reference.sourceIndex>`
+   to reopen the original version under current permissions. An unversioned source
+   has no guaranteed historical snapshot; do not label its current content historical.
+   Historical source reads are rejected inside a required fixed-context execution;
+   never remove that context or fall back to an ordinary token to bypass its KB set.
+   If a gap remains, go back to step 2 with another set of `--paths`
    **copied** from current navigation, or return to discovery for the next candidate.
    For a knowledge-only question, missing evidence after the allowed search
    means "not covered by the knowledge base" — do not attach a confident fact

package/skills/ae-metadata/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-metadata
-version: 1.0.2
+version: 1.0.5
 description: "AE metadata capability-gateway CLI: list, inspect, create, update, delete and download metadata data tables; bind an existing dimension table to a property or create and bind a CSV dimension table. Local file upload and event/property discovery are separate prerequisite capabilities."
 ---
 
@@ -14,7 +14,7 @@ Use this skill for gateway-backed data-table and property dimension-table operat
 
 - Responsibilities: data-table management and dimension-table bindings through the commands below.
 - Inputs: verified project, table/property identifiers and operation-specific parameters; local CSV workflows need a valid uploaded input-file identifier and purpose.
-- Outputs: table/binding operation results, resource identifiers, or download run/artifact status. A submitted asynchronous download is not yet a completed file.
+- Outputs: table/binding operation results, resource identifiers, or download run/artifact status. Data-table get can include saved SQL definitions, parameters, and schedule configuration on supported servers; read its reference for availability and execution-value limits. A submitted asynchronous download is not yet a completed file.
 - Boundaries: local input-file upload, event/property detail and discovery, metric CRUD, virtual metadata, batch metadata, project configuration and tracking plans are separate capabilities.
 - Completion: the requested table or binding result is verified, or pending/blocked work and its remaining requirements are reported.
 
@@ -43,6 +43,7 @@ Safety:
 - **Before any command**, read the matching `references/<name>.md` (filename = command with spaces → underscores, e.g. `metadata data-table list` → `metadata_data_table_list.md`).
 - Never invent `project_id`, event/property names, `input_file_id`, or `data_table_id`. Reuse verified names or discover a metadata lookup capability; find data table IDs via `metadata data-table list`.
 - `metadata data-table download` is an async artifact command: plain invocation submits, `--wait` waits, and `--output <file>` waits then streams atomically. Resume with `analysis run wait`; local interruption never cancels the remote run.
+- The member's natural-day quota counts every Gateway capability `execute` call eligible for usage statistics (an identifiable user and statistics enabled), including metadata-only reads, previews, table/binding writes, asset exports, and downloads that submit work. It does not depend on database engine or business purpose. Cache hits, repeated calls, reused runs, and failures within `execute` count, including schema errors, permission denials, and unknown capability IDs. Gateway capability discovery (list/inspect), validate/dry-run, and separate run-status/artifact-download HTTP endpoints do not count; pagination and cancellation through capability execution do count. On `QUERY_DAILY_LIMIT_EXCEEDED` (HTTP 429), wait until reset or contact an administrator; `QUERY_QUOTA_UNAVAILABLE` fails explicitly. Do not switch identities to bypass these errors. Omit download `--timeout-seconds` to use the server default; inspect the selected capability for its current policy.
 
 ## When to Use
 

package/skills/ae-metadata/references/metadata_data_table_download.md

@@ -13,7 +13,7 @@ ae-cli metadata data-table download --project-id <project_id> --data-table-id <i
 | `--project-id` / `-p` | Yes | Numeric project ID. |
 | `--data-table-id` | Yes | Data table ID. |
 | `--request-id` | No | Optional `cli_<32 lowercase hex>` request ID. |
-| `--timeout-seconds` | No | Remote runtime in seconds, 1 to 21600. |
+| `--timeout-seconds` | No | Omit to use the server default (normally 21600 seconds / 6 hours). This CLI accepts explicit values in `1..21600`. Inspect this capability for the server default/max; use `capability run` with `timeout_seconds` for larger values only when its schema allows them. |
 | `--wait` | No | Wait for run `SUCCEEDED` and artifact `COMPLETED`. |
 | `--output` | No | Wait, then stream and atomically publish the artifact to this file. |
 | `--force` | No | Replace an existing `--output` file atomically; invalid without `--output`. |
@@ -23,3 +23,9 @@ invocation submits only. `--output` implies `--wait`; resume an interrupted
 wait with `ae-cli analysis run wait --run-id <run_id> [--output <file>]`.
 Local interruption never cancels the remote run. Do not use this command for
 inline data-table metadata; use `metadata data-table get` instead.
+
+Read the returned `effective_timeout_seconds`, `timeout_source`, and `deadline_at` for the actual lifecycle deadline. Local waiting has its own bound and can be resumed without resubmitting.
+
+Each Gateway `execute` call consumes one unit of the member's natural-day quota when the user is identifiable and usage statistics are enabled, regardless of database engine or business purpose. Cache hits and failures within `execute` count, including invalid input schemas, permission denials, unknown capability IDs, and accepted work that later fails or times out. Repeating the same input counts again even if a handler reuses an existing run; Gateway has no general `client_request_id` idempotency guarantee. Resume with `analysis run wait` or use `analysis artifact download`: their separate status/download HTTP endpoints do not count. Gateway capability discovery (list/inspect) and validate/dry-run do not count either. Pagination and cancellation do count when invoked through capability execution, such as `analysis.query.cancel`.
+
+`QUERY_DAILY_LIMIT_EXCEEDED` (HTTP 429) requires waiting until reset or contacting an administrator; a blocked call does not increase the used quota but remains eligible for failed-call usage auditing. `QUERY_QUOTA_UNAVAILABLE` fails explicitly. Usage persistence is asynchronous and best effort, so persisted usage-row totals need not equal quota counters. Do not switch identities to bypass quota enforcement.

package/skills/ae-metadata/references/metadata_data_table_get.md

@@ -9,6 +9,8 @@ ae-cli metadata data-table get --project-id <project_id> --data-table-id <id>
 ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --include-preview true
 ```
 
+Use this command to inspect a metadata data table's columns, bindings, and saved SQL configuration. It requires the existing metadata view permission for the selected project. Reading a saved SQL definition does not authorize querying its upstream tables.
+
 ## Parameters
 
 | Parameter | Required | Description |
@@ -17,8 +19,43 @@ ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --
 | `--data-table-id` | Yes | Data table ID from `metadata data-table list`. |
 | `--include-preview` | No | Include preview rows when true. |
 
+Each call to this capability's Gateway `execute` endpoint consumes one unit of the member's natural-day quota when the user is identifiable and usage statistics are enabled. This includes metadata-only reads (`include_preview` omitted or false), previews of any table type, cache hits, repeated calls, and failures within `execute`, including schema errors or permission denials. The database engine does not affect counting. Gateway capability-discovery list/inspect and validate/dry-run endpoints do not count. `QUERY_DAILY_LIMIT_EXCEEDED` (HTTP 429) requires waiting until reset or contacting an administrator; a blocked call does not increase the used quota but remains eligible for failed-call usage auditing. `QUERY_QUOTA_UNAVAILABLE` fails explicitly. Usage persistence is asynchronous and best effort, so persisted usage-row totals need not equal quota counters. Do not change identities to bypass quota enforcement.
+
 ## Request Body
 
 ```json
 { "project_id": 1, "data_table_id": 42, "include_preview": true }
 ```
+
+## Detail output
+
+Default JSON returns the complete server payload under `data`, including columns and bindings. `--include-preview true` additionally requests preview rows; it is not required to read saved SQL configuration.
+
+On servers that support SQL definition output, SQL tables add the following fields in both default and preview responses. Non-SQL tables omit them.
+
+| Field | Meaning |
+|---|---|
+| `create_qp` | Saved creation QP as a JSON object. |
+| `update_qp` | Saved update QP as a JSON object. |
+| `create_zone_offset` / `update_zone_offset` | Offset in hours used to parse SQL parameters for the corresponding QP. These are not the cron schedule timezone. |
+| `strategy` | Saved update strategy, such as `overwrite` or `insert`. |
+| `update_cron` | Saved update cron expression. Interpret it together with `update_conf_status`. |
+| `update_conf_status` | Schedule switch state: `NOT_SET`, `ENABLE`, or `DISABLE`. This is not task running status or evidence that an execution succeeded. |
+
+The wrapper fields use snake_case. QP objects retain the published model keys: SQL is at `taSqlVo.sql`, SQL parameters at `taSqlVo.sqlVoParams`, and view parameters at `taSqlView.sqlViewParams`. Preserve all nested keys and values, including extensions, when reading or reusing the definition. See [the SQL-write QP contract](metadata_data_table_sql_write.md#qp-contract-sqldatatabledef) before constructing a write.
+
+Parameter definitions and saved values describe configuration. Values containing expressions or placeholders may resolve differently during each execution. This response does not supply the actual resolved values of a specific execution; obtain execution evidence separately when those values are required.
+
+For SQL tables, unavailable configuration values are `null`; missing, invalid, or non-object historical QP values also produce `null` QP fields. Default get returns `null` configuration fields when the SQL definition record is missing. `--include-preview true` retains the server's existing preview behavior; missing definition records may still cause preview to fail on affected servers. A `null` QP does not establish that the SQL has no parameters. An empty parameter array is an explicit empty saved parameter list. Older servers may omit the new fields entirely, so missing fields alone do not prove that configuration is empty or that this server supports definition output. Inspect the selected server capability when availability matters.
+
+## Read the complete definition
+
+Use `--format json` to retain SQL configuration beside columns and bindings. Table format may render only the columns array. CLI `--jq` runs on the payload before envelope wrapping, so paths start at `.create_qp` or `.update_qp`, not `.data`.
+
+```bash
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --format json
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --jq '{create_qp, update_qp, create_zone_offset, update_zone_offset, strategy, update_cron, update_conf_status}'
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --jq '.update_qp.taSqlVo.sqlVoParams'
+```
+
+Choose the full response or a projection containing all required fields in one read. If the response is saved to a local file, inspect that file for additional paths instead of repeating the server request.

package/skills/ae-team/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-team
-version: 1.0.0
+version: 1.0.2
 description: "ThinkingAI AE (Agentic Engine) ae-cli manual for AI Agent Team tasks: managing teams (list, create, update, delete, AI-generate, templates) and executing TeamRuns (start, chat, cancel, reply, result, artifacts). Use when the user asks to find a team, run a team task, check run status, retrieve results or artifacts, or set up multi-agent workflows. Must use ae-cli, read the matching references/<command>.md before composing commands, and never guess team IDs, run IDs, config structures, or parameter formats."
 ---
 
@@ -113,7 +113,7 @@ ae-cli team +run-start --team-id <team_id> --input "分析上周用户留存数
 # 4. Stream until done (blocks; no polling needed)
 ae-cli team +run-watch --id <run_id>
 # exit 0 → completed/partial_success → go to step 5
-# exit 1 → failed/cancelled → inspect errorMessage in output, report to user
+# exit 1 → inspect the terminal entity or error; for connection errors, use +run-result before considering a new run
 # exit 2 → waiting_user → go to step 4a
 
 # 4a. Handle waiting_user: read pendingQuestion from stdout, get user's answer, reply, re-watch

package/skills/ae-team/references/run-start.md

@@ -16,6 +16,7 @@ Domain: **TeamRun execution / write**
 - `--notification` must be valid JSON if provided, e.g. `'{"channels":["feishu"],"feishuChatId":"..."}'`.
 - This is an ordinary `write` operation and does not require CLI confirmation.
 - After starting, capture the returned `id` (run ID) and use it to poll `+run-result`.
+- `--save-to-kb-id` accepts a personal or company knowledge base ID and maps to the API field `saveToKnowledgeBaseId`. After completion, check `savedKnowledgeBase` and read back the saved source; a successful start alone does not confirm saving.
 
 ## Command
 ```bash

package/skills/ae-team/references/run-watch.md

@@ -13,7 +13,8 @@ Domain: **TeamRun execution / read**
 - `--id` is required. Obtain the real run ID from a previous `+run-start` or `+run-chat` response.
 - Check the **exit code** to determine what happened — do not guess from output alone.
 - When exit code is `2` (`waiting_user`): read `pendingQuestion` from stdout, present it to the user, collect their answer, call `+run-reply`, then re-run `+run-watch`.
-- Network drops are handled automatically (up to 10 reconnects with 2s delay). Do NOT retry `+run-watch` on exit 1 unless you have confirmed the run itself failed via `+run-result`.
+- Connection failures, premature EOF, and SSE read failures share a maximum of 10 reconnects, with a 2s delay before each retry. Reconnects carry the last complete log timestamp in `afterLog`; an incomplete event is discarded. HTTP rejections and SSE `error` events exit immediately without reconnecting.
+- Exit 1 alone does not mean the server-side run failed. After a connection error or exhausted retries, check `+run-result --id <run_id>`. Resume watching the same run if it is still active; do not start a duplicate run merely because its stream disconnected.
 
 ## Command
 ```bash
@@ -37,16 +38,17 @@ ae-cli team +run-watch --id <run_id> --after-log <lastTimestamp>
 | Code | Meaning | Action |
 |---|---|---|
 | `0` | `completed` or `partial_success` | Proceed to `+run-artifacts` |
-| `1` | `failed`, `cancelled`, `stale`, or connection error | Inspect `errorMessage` in stdout JSON; report to user |
+| `1` | `failed`, `cancelled`, `stale`, or connection error | Inspect the terminal entity or error; for connection errors, check the same run with `+run-result` |
 | `2` | `waiting_user` | Read `pendingQuestion` from stdout JSON, present to user, then `+run-reply` → re-run `+run-watch` |
 
 ## Output
-stdout always receives the final `TeamRunEntity` as a standard JSON envelope:
+When a terminal or `waiting_user` event is received, stdout receives its `TeamRunEntity` as a standard JSON envelope:
 ```json
 { "ok": true, "data": { "id": "...", "status": "...", "pendingQuestion": "...", ... } }
 ```
 - Exit 0/1: the entity from the `final` SSE event (terminal state)
-- Exit 2: the entity from the `update` SSE event at the moment `waiting_user` was detected
+- Exit 2: the entity from the `snapshot` or `update` SSE event at the moment `waiting_user` was detected
+- Connection failures and SSE `error` events emit an error on stderr and may have no entity on stdout. A connection error does not cancel the run.
 
 stderr receives real-time log lines and status changes (suppressed with `--quiet`).
 
@@ -75,7 +77,7 @@ ae-cli team +run-watch --id <run_id>
 
 ## Next Steps on Failure
 - Exit 1 + `status = failed`: read `errorMessage` in the JSON output; ask user whether to retry with `+run-start`.
-- Connection drop before `final`: re-run `+run-watch --id <run_id> --after-log <lastTimestamp>`.
+- Connection error before `final`: let automatic reconnects finish. If the command exits 1, check `+run-result --id <run_id>` first. For an active run, resume with `+run-watch --id <run_id> --after-log <lastTimestamp>`; omit `--after-log` if no cursor was retained.
 
 ## Recommended Chaining
 - `+run-start` → `+run-watch` → exit 0 → `+run-artifacts`