@thinkingai/ae-cli 6.1.27 → 6.1.29

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-experiment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-experiment
-version: 1.0.2
+version: 1.0.5
 description: "Use when managing Atlas AB or external experiments, traffic layers, Features, metrics, buckets, and experiment reports through ae-cli"
 ---
 
@@ -65,6 +65,12 @@ Naming and response boundary:
 5. Check readiness with `experiment experiment ready-check`.
 6. For a non-mutex traffic layer, run `experiment experiment conflict-check` before submit (needs `feature_key_list` from context or `experiment get`).
 7. Move status with `experiment experiment manage`.
+   For a scheduled Feature start, save `startTime` (or use `--start-time`), then
+   submit with `--target-status pending`. Saving a draft does not submit it; `running`
+   starts immediately. Read [Feature timing](references/save_experiment.md#feature-timing)
+   before configuring a schedule or starting it early.
+   To resume `paused` to `running`, call `manage` directly and verify the status
+   with `get`; do not use the pre-launch `ready-check` as a resume prerequisite.
 8. Query reports with `experiment report summary`, `experiment report sample-size`, and `experiment report metric-trend`.
 
 If an experiment save returns `error_code: METRIC_NOT_FOUND`, list metrics for the same project. Create and verify the metric before retrying; never retry with another invented ID. Metric deletion returns `error_code: METRIC_IN_USE` while an active experiment binding exists.

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

@@ -12,6 +12,23 @@ Flags:
 - `--target-status`: One of `draft`, `testing`, `pending`, `running`, `paused`, `ended`, `archive`.
 - `--remark`: Optional operation remark.
 
-When target status is `pending`, `testing`, or `running`, Hermes performs a ready check before changing status.
+When target status is `pending`, `testing`, or `running`, Hermes performs a ready
+check before changing status, except when resuming `paused` to `running`.
+Resume uses the shared status transition service, which checks permissions,
+deadline, and audience readiness and re-enables the Feature rules and RCC sync.
+It preserves the first start time and the existing day-based or fixed deadline.
+Do not run the standalone `ready-check` as a prerequisite for resuming a paused
+experiment; that command accepts only pre-launch states.
+
+For Feature scheduling, save `startTime` first and use `pending` to submit. The
+server checks submitted experiments every half hour. `running` starts immediately;
+read fresh detail and disclose `start_time_adjustment_required=true` before an
+early manual start. No extra confirmation field is required. See
+[Feature timing](save_experiment.md#feature-timing) for lifecycle and deadline rules.
 
 Response shape: the operation or blocking readiness result is in `data.result`, with object keys recursively converted to snake_case.
+
+An outer `ok=true` does not mean the status changed when `data.result.valid=false`.
+Report the returned issues and read `experiment experiment get` to confirm the
+actual status. A successful resume normally returns `data.result=true`; do not
+report the experiment as running until an independent read confirms it.

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

@@ -12,6 +12,13 @@ Flags:
 
 Response shape: the experiment is in `data.item`, with recursively snake_case keys such as `exp_id` and `feature_key_list`.
 
+Feature timing is exposed as `start_time`, `end_time`, and `exp_cycle` (including
+`cycle_type`, `fixed_end_time`, and planned `end_time`). The top-level `end_time`
+records actual completion. Check `scheduled_start_error` for an expired pending
+window and `start_time_adjustment_required` before starting a scheduled experiment
+early. Use returned `status` to verify execution; a successful save or submission
+does not mean the experiment is running.
+
 When targeting contains reversible QP, it is returned as
 `targeting.definition_request` with `targeting.definition_status=AVAILABLE`.
 An absent definition is `NOT_APPLICABLE`; a historical unsupported definition is

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

@@ -3,12 +3,14 @@
 Progressively create or patch an experiment draft.
 
 ```bash
-ae-cli experiment experiment save --project-id <id> --req '<json>'
+ae-cli experiment experiment save --project-id <id> --req '<json>' [--start-time <timestamp>] [--fixed-end-time <timestamp>]
 ```
 
 Flags:
 - `--project-id`, `-p`: Project ID.
 - `--req`: Experiment save request JSON object.
+- `--start-time`: Optional Feature start timestamp in ISO-8601 format with timezone offset. Overrides `req.startTime`.
+- `--fixed-end-time`: Optional Feature deadline in the same format. Sets `req.expCycle.cycleType=time` and overrides `req.expCycle.fixedEndTime`, preserving other supplied cycle fields. These timing flags are for Feature experiments; external experiments use `external-experiment save-submit`.
 
 ## Contract
 
@@ -64,6 +66,7 @@ Optional while drafting:
 - `isExpSharing`
 - `bucketId`
 - `expCycle`
+- `startTime`
 - `groups`
 - `featureKeyList`
 - `metrics`
@@ -101,7 +104,7 @@ ae-cli experiment experiment save --project-id 1 --req '{"expId":"exp_123","allo
 - `isExpSharing=0` uses exclusive traffic with `bucketId`; select the bucket with `experiment bucket list`.
 - `allocation` (experiment-level) is the experiment's share of the traffic layer. It is optional during draft construction, but before readiness it must be greater than `0` and no more than `100`. **Integer only** (for example `20`); decimals such as `20.5` are rejected at the CLI interface.
 - `groups[].allocation` (group-level): **integer only; sum must equal `100` exactly**. Example for 3 groups: `34 + 33 + 33 = 100`. Decimals such as `33.33` are rejected at the CLI interface before save.
-- `expCycle.cycleType` can be `day` or `sample`; when `cycleType=day`, `dayNum` is `1..90`. Blank cycle defaults to day + 30.
+- `expCycle.cycleType` can be `day`, `sample`, or `time`; when `cycleType=day`, `dayNum` is `1..90`. `time` requires `fixedEndTime`. Blank cycle defaults to day + 30.
 - Before readiness, `groups` must be non-empty, contain exactly one control group (`isControl=1`), group allocations must sum to exactly `100`, and each `expGroupValue` must be a non-empty JSON string array.
 - Feature experiments must bind `featureKeyList` before readiness. `featureKeyList` contains Feature key strings, not Feature objects. The MCP currently supports one `featureKey` for feature experiments.
 - Metrics use `metricRole=primary|secondary|guardrail`; the internal `observation` role is currently unavailable for saves. Before readiness at least one primary metric is required.
@@ -142,6 +145,61 @@ Semantic audience example:
 }
 ```
 
+## Feature Timing
+
+Feature start time is optional. Use ISO-8601 timestamps with an explicit offset,
+for example `2026-11-01T16:00:00+08:00`. Prefer minutes `00` or `30` to align
+with the server's half-hour scheduling checks. The CLI forwards timestamps;
+the server clears seconds and milliseconds on configured Feature start times.
+
+Save timing on a new draft or patch an existing experiment:
+
+```bash
+ae-cli experiment experiment save --project-id 1 --req '{"expName":"Scheduled CTA"}' --start-time '2026-11-01T16:00:00+08:00' --fixed-end-time '2026-11-08T16:00:00+08:00' --dry-run
+ae-cli experiment experiment save --project-id 1 --req '{"expId":"exp_123"}' --start-time '2026-11-01T16:00:00+08:00' --fixed-end-time '2026-11-08T16:00:00+08:00'
+```
+
+The second command produces the same native request as:
+
+```json
+{"expId":"exp_123","startTime":"2026-11-01T16:00:00+08:00","expCycle":{"cycleType":"time","fixedEndTime":"2026-11-08T16:00:00+08:00"}}
+```
+
+Saving does not submit or start the experiment. Complete the remaining Feature,
+group, traffic, and metric configuration, check readiness, and check traffic
+conflicts for a non-mutex layer before submitting:
+
+```bash
+ae-cli experiment experiment ready-check --project-id 1 --exp-id exp_123
+ae-cli experiment experiment manage --project-id 1 --exp-id exp_123 --target-status pending
+ae-cli experiment experiment get --project-id 1 --exp-id exp_123
+```
+
+Only submitted `pending` Feature experiments with a configured start time are
+eligible for automatic start. A draft never starts automatically; a pending
+experiment without a start time waits for manual start. The server checks every
+half hour, so a successful submission is not evidence that the experiment is
+already running. Verify `data.item.status`, `start_time`, and
+`scheduled_start_error` with `get` (or `list`). An expired pending window remains
+pending and reports an error; fix the timing instead of reporting a start.
+
+Timing changes follow server lifecycle rules:
+
+- Start time can change while draft or pending. Omission or `null` preserves a
+  saved start time; neither clears it. After the first run, start time is locked.
+- `day` ends after start plus `dayNum` times 24 hours. `time` uses the absolute
+  `expCycle.fixedEndTime`, which must be later than start. The top-level `endTime`
+  is the actual end time, not the Feature deadline configuration.
+- Submitted end conditions must keep their cycle type and may only be extended.
+  The server validates existing state and the effective time window.
+- Manual `running` starts immediately. Read fresh detail first and disclose any
+  `start_time_adjustment_required=true` to the user: an early start uses current
+  server time, recalculates a day-based deadline, and keeps a fixed deadline.
+  Do not add an extra confirmation field to the request.
+- Pause/resume keeps the original start and deadline. Running and paused
+  experiments are checked for expiry every half hour; deadlines between checks
+  are handled by a subsequent check.
+
 ## Payload Examples
 
 Patch a Feature binding. `featureKeyList` is a string array:
@@ -168,6 +226,22 @@ Patch metrics. `metrics` is an object array:
 ae-cli experiment experiment save --project-id 2 --req '{"expId":"e024","metrics":[{"metricId":"payment","metricRole":"primary"}]}'
 ```
 
+## Timing Validation Errors
+
+Atlas business time checks return `error.type=validation`, a specific code,
+`error.details.field`, and a correction hint. Examples:
+
+| Code | Field | Correction |
+| --- | --- | --- |
+| `EXPERIMENT_END_TIME_INVALID` | `req.expCycle.fixedEndTime` (related: `req.startTime`) | Make the deadline strictly later than the start; submission or start also requires an unexpired window. |
+| `EXPERIMENT_END_TIME_REQUIRED` | `req.expCycle.fixedEndTime` | Supply a timestamp with timezone offset when `cycleType=time`. |
+
+Fix the reported field before retrying. The error preserves `meta.invocation_id`
+for investigation. These checks do not save the invalid configuration; use `get`
+to verify the existing timing. Older backends may still return
+`CAPABILITY_EXECUTION_FAILED`; changing CLI arguments cannot repair a missing
+server-side exception translator.
+
 ## Dry-run Limitation
 
 `--dry-run` calls the Capability Gateway preview endpoint. It validates the outer input contract but does not guarantee that every nested DTO business rule will pass execution.

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

@@ -14,3 +14,10 @@ internal `targetConfig` field or hand-write `Cxx`/`Axxx` codes.
 Response shape: `data.result`, with object keys recursively converted to snake_case.
 
 Prefer `experiment experiment save` for progressive draft construction.
+
+Feature requests may include optional `req.startTime` and
+`req.expCycle={"cycleType":"time","fixedEndTime":"2026-11-08T16:00:00+08:00"}`.
+Use ISO-8601 timestamps with timezone offsets. Submitting a Feature draft
+places it in `pending`; with a start time, the server checks it every half hour
+for automatic start. See [Feature timing](save_experiment.md#feature-timing) for
+the draft, submission, manual-start, and deadline boundaries.

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`
@@ -610,7 +637,6 @@ Transport: `POST /agent/api/external/knowledge-bases/sources/check-updates`, bod
 - 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

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