@thinkingai/ae-cli 6.1.25 → 6.1.27

package/skills/ae-analysis/references/metadata_resolution.md

@@ -2,6 +2,15 @@
 
 Reuse verified assets, canonical names and business meanings in the current project. Use this workflow for missing definitions or metadata; discovery is complete when the requested measure can be constructed or a specific business choice needs the user's reply.
 
+After a KB semantic-only or partial-coverage handoff, retain the read KB evidence
+and live definitions already verified. Search for a suitable saved definition
+for the uncovered requirement, then discover only missing metadata. A related
+asset that merges actions or lacks a requested filter is not an equivalent
+answer. When the remaining definition is verified, continue authorized ad-hoc
+analysis under its actual scope; disclose differences from the KB-selected
+asset. Do not ask for continuation of the same read-only request. A genuine
+unconfirmed business mapping still follows the confirmation rule below.
+
 ## Find a reusable definition
 
 For an unknown business measure, search relevant saved metrics and readable analysis assets. A named asset needs only its own family; already known definitions go directly to execution. Read the selected [metric](metric_list.md) and [asset search](asset_search.md) command references together, then issue independent searches in the same model turn:
@@ -55,6 +64,12 @@ A new project uses its own filename. An explicit environment/account change or a
 
 ## Confirm and bind
 
+Verifying canonical fields, types, or filter values for an already explicit or
+confirmed business meaning is evidence completion, not automatically a new
+business mapping. Reuse the established meaning and continue when metadata
+supports it without a material choice. If verification exposes an ambiguous
+entity, scope, or definition, the business mapping still needs confirmation.
+
 Confirm a selected business mapping once, even if only one candidate is suitable. Present its meaning and any unresolved semantics. Reuse mappings already confirmed in this task. User confirmation selects the business definition; it does not verify an unknown asset formula. If the confirmation tool cannot obtain a reply, present the same choices in text and wait. A failed tool call is not confirmation. Rejected candidates are discarded; seek a different candidate for that choice using the relevant search above.
 
 After the reply, fill the confirmed canonical name, aggregation, property and other required model parameters, then execute the complete definition. Use `--resolutions` only when binding unresolved wording retained at a compiler-reported path. Bindings select metadata; they do not fill model parameters. Their `raw_value` must match the wording at that path.

package/skills/ae-analysis/references/personal_semantic_preference_review.md

@@ -0,0 +1,9 @@
+# Review personal semantic preferences
+
+Use `ae-cli personal-semantic-preference review` only for an explicit project review decision by an authorized reviewer. Capability: `business_semantics.personal_context.review`; risk: write. Do not use this to publish a KB or change asset certification.
+
+An authorized project reviewer may adopt or reject an unsubmitted (`none`) preference directly; a separate submit step is optional. Pending preferences can also be reviewed.
+
+Required flags: `--project-id`, `--ids` (JSON array of 1–100 preference IDs from review-list), `--action` (`adopt` or `reject`). Optional: `--project-review-note`, `--request-id` (reuse on retries). Validate or dry-run checks input without applying the decision.
+
+The result contains `action`, reviewed `items`, and `reviewed_count`. Adoption makes the reviewed preference eligible for future project KB refresh; it does not confirm a successful KB compile or publication. Reload after a review-state conflict before deciding again.

package/skills/ae-analysis/references/personal_semantic_preference_review_list.md

@@ -0,0 +1,7 @@
+# List personal semantic preferences for project review
+
+Use `ae-cli personal-semantic-preference review-list` for the authorized project review queue. Capability: `business_semantics.personal_context.review_list`; risk: read. Do not use this instead of the user's personal preference list.
+
+Required flag: `--project-id`. Optional filters: `--project-review-status` (`none`, `pending`, `adopted`, `rejected`), `--owner` (user name, login name, or user ID; open_id is not accepted), `--context-type` (`preference`, `asset_context`, `experience`, `background`), `--keyword`, `--limit`, and `--offset`.
+
+The result includes `items`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. Use the returned identifiers for an explicit adopt/reject decision; listing does not change review status or refresh a KB. Project reviewer permissions are required.

package/skills/ae-analysis/references/personal_semantic_preference_submit.md

@@ -0,0 +1,7 @@
+# Submit a personal semantic preference for project review
+
+Use `ae-cli personal-semantic-preference submit` only when the user wants an existing personal preference reviewed for project use. Capability: `business_semantics.personal_context.submit`; risk: write. Do not use this to certify an asset or publish a KB.
+
+Required flags: `--project-id`, `--id` (the existing preference identifier). Optional: `--project-review-note`, `--request-id` (reuse on retries). Use `--validate` or `--dry-run` to check the input without submitting.
+
+The result includes `submitted` and the refreshed `preference`. Submission changes eligible NONE/REJECTED records to PENDING; an already submitted record does not imply a new submission. Review and KB compilation are separate steps.

package/skills/ae-analysis/references/project_semantic_knowledge_wiki.md

@@ -2,17 +2,17 @@
 
 Asset-package export requires access to the target project. Neither the retired `project_semantic_enable` project switch nor the company switch for automatic knowledge-base discovery gates an explicit build or refresh. If project access or company KB permission is denied, report the error and stop; do not switch to a different project, scope, or export path.
 
-Build one server-consumable project semantic source Wiki from one immutable Common asset-package snapshot and prove that the KB-compiled knowledge base can be browsed and consumed correctly. The asset package is the raw truth source. Default to a governed package; use an `all_visible` package only when the user explicitly asks for all assets or for uncertified assets to be included. The Agent summarizes the asset semantics once into editable Markdown sources; KB owns schema generation, final compilation, source lifecycle, and incremental maintenance.
+Build one server-consumable project semantic source Wiki from one immutable Common asset-package snapshot and prove that the KB-compiled knowledge base can be browsed and consumed correctly. The asset package is the raw truth source. Default to a governed package; use an `all_visible` package only when the user explicitly asks for all assets or for uncertified assets to be included. The Agent summarizes the asset semantics once into editable Markdown sources; KB owns formal rule application, final compilation, source lifecycle, and incremental maintenance.
 
 The first product goal is not an asset directory. The Wiki must teach the user and Agent how this project observes business: what business system it covers, who uses it, what business objects exist, how those objects relate, which judgment chains users follow, and which assets play primary, supporting, drilldown, or exclusion roles in those chains. Asset pages, report formulas and metadata pages hang under that business judgment model. A Wiki that only lists domains, reports, metrics, dimensions, recall cards, counts, or source containers is an incomplete project semantic KB even if it compiles.
 
 ## Boundary
 
-- This command reference covers asset-package download, one Agent semantic-planning pass, deterministic Wiki-source rendering, validation, editable ZIP source upload, schema generation, compilation, server readback, and retrieval acceptance.
+- This command reference covers asset-package download, one Agent semantic-planning pass, deterministic Wiki-source rendering, validation, editable ZIP source upload, preset initialization/reuse, compilation, server readback, and retrieval acceptance.
 - The default source scope is `governed`. If and only if the user explicitly requests all assets, use `all_visible`; keep uncertified assets visible but marked `certification_state=uncertified`, and do not present uncertified or conflicting assets as governed definitions.
 - The retired governed project-semantic candidate/review/enable/release lifecycle is not part of this workflow. A retrieval taxonomy or Wiki page is not automatically a governed project semantic.
 - The generated Wiki is a retrieval and evidence layer. Current counts, recent customers, and live usage still require report execution.
-- Do not use `kb +import` for this loop. `kb +import` imports an already compiled read-only snapshot; this workflow needs source upload followed by `kb +schema` and `kb +compile`.
+- Do not use `kb +import` for this loop. `kb +import` imports an already compiled read-only snapshot; this workflow needs editable source upload, valid formal rules, and `kb +compile`. Do not generate Schema in the normal build/refresh path.
 
 
 ## Usage and Intake Gate
@@ -47,11 +47,32 @@ node "$KB_RUN" +new --name '<company_kb_name>' \
   --project-id <project_id> --project-name '<project_name>' --host <host>
 ```
 
-The wrapper executes the installed `ae-cli`. Directory APIs lack a scope parameter, so it verifies the ZIP source belongs to the company KB before mutation. Permission denial stops the flow. An explicitly requested personal test uses the project CLI directly with `--scope personal` on scope-aware commands; this is never a permission fallback. Personal test KB creation follows the same description rule and must still use a business-facing description.
+The wrapper executes the matching project/package CLI when present; standalone installed Skills retain `ae-cli` from PATH. Directory APIs lack a scope parameter, so it verifies the ZIP source belongs to the company KB before mutation. Permission denial stops the flow. An explicitly requested personal test uses the project CLI directly with `--scope personal` on scope-aware commands; this is never a permission fallback. Personal test KB creation follows the same description rule and must still use a business-facing description.
+
+## Preset initialization, reuse and release acceptance
+
+The canonical directly uploadable rules are `scripts/project-semantic-knowledge-wiki/default-compile-schema.md`. Maintain this user-visible document in Chinese while retaining literal paths and protocol field names. It defines durable compilation behavior, not project-specific facts. Review and AI-validate the exact preset bytes once before releasing a preset version; keep its hash and report as acceptance evidence. Do not run AI validation for every KB initialization or source refresh. Retain deterministic format, revision, content-hash, permissions and current-formal-hash checks.
+
+`prepare-compile-schema.mjs` never applies rules or compiles. It returns `reuse` only after status and downloaded formal bytes agree that rules are valid. A pending new KB can contain a default placeholder even when no effective rules exist; preparation uploads the preset as a candidate and returns `review_import` with `compile_ready=false`. Download errors other than explicit missing-file errors, busy/recovery/review states and invalid established rules are terminal. Use a stable `--request-id` when resuming the same initialization; do not create a second candidate after an uncertain write.
+
+For `review_import`, use the returned stable candidate ID with the project/package CLI. Read the entire candidate, full current-schema diff and any advisories. Then explicitly apply using the current revision, candidate hash and formal hash from that diff:
+
+```bash
+ae-cli kb +schema-import-content --import-id <returned_id> --host <host>
+ae-cli kb +schema-import-diff --import-id <returned_id> --baseline current-schema --host <host>
+ae-cli kb +schema-import-apply --import-id <returned_id> --revision <current_revision> \
+  --hash <candidate_hash> --schema-hash <formal_hash_from_diff> --request-id <apply_id> --host <host>
+```
+
+Only if the diff reports formal absence use `--schema-absent` instead of `--schema-hash`. New KB placeholders are present files and require their actual hash. `--report-id` is optional; old callers may still supply it. A successful application must have `status=applied` with no settlement/recovery pending. Read status and formal bytes again before compilation. `BASE_CHANGED` requires a fresh review, never automatic hash refresh/replay. Do not overwrite valid custom rules just because their hash differs from the preset.
+
+Preset release acceptance explicitly uses `ae-cli kb +schema-import-validate --import-id <id> --revision <revision> --hash <hash> --request-id <validation_id> --host <host>`, followed by `+schema-import-status` until the exact candidate has a complete passing report. Validate changed preset bytes again; do not carry a report across hashes. Keep this authoring check separate from the normal KB lifecycle. Test a first full publication and a real changed-source incremental publication with unchanged formal bytes.
+
+Compatibility: existing explicit `company-kb.mjs +schema --custom-instructions-file default-compile-rules.md` remains supported for user-requested rule generation. `default-compile-rules.md` is legacy generation guidance, not the normal preset input. Old commands, scopes and model parameters are retained; no new Skill is introduced. Servers that still require per-candidate AI reports cannot use the fast application path and must be reported as unsupported until their contract is upgraded; do not silently fall back to generation.
 
 ## User-selected model
 
-Resolve the requested model with `ae-cli agent +list-models --host <host>` and retain its exact Model.id. Pass the same `--model <model_ref>` to Schema and compile, including incremental refreshes. Stop if the requested model is unavailable or ambiguous.
+Resolve the requested model with `ae-cli agent +list-models --host <host>` and retain its exact Model.id. Pass the same `--model <model_ref>` to compilation, including incremental refreshes. AI rule validation is a separate preset-release acceptance step and accepts a model only when explicitly requested. Stop if the requested model is unavailable or ambiguous.
 
 ## Source directory contract
 
@@ -66,6 +87,11 @@ sources/
     reports/
     metrics/
     metadata/
+  personal-semantics/
+    background/
+    preference/
+    experience/
+    asset-context/
   business/
   meetings/
   decisions/
@@ -73,26 +99,40 @@ sources/
   references/
 ```
 
-CLI-managed asset facts go only under `sources/assets/**`. Human material goes under the other top-level categories. Asset refreshes may add, replace, or remove files owned by the generated asset package; they must not delete user material in `project/`, `business/`, `meetings/`, `decisions/`, `corrections/`, or `references/`.
+CLI-managed asset facts go only under `sources/assets/**`. Adopted personal semantics exported by Common go under `sources/personal-semantics/**` by their `context_type`: `background`, `preference`, `experience`, or `asset_context` (`asset-context` path). Human material goes under the other top-level categories. Asset refreshes may add, replace, or remove files owned by the generated asset package under `sources/assets/**` and `sources/personal-semantics/**`; they must not delete user material in `project/`, `business/`, `meetings/`, `decisions/`, `corrections/`, or `references/`.
 
 The intended compiled Wiki is organized by consumption, not by raw file shape:
 
 ```text
 index.md
-wiki/project/
+wiki/project-overview.md
+wiki/common/
 wiki/domains/
-wiki/semantics/
-wiki/assets/
-wiki/decisions/
-wiki/review/
+wiki/asset-index/
+wiki/event-map/
+wiki/governance/
 ```
 
 The source tree only classifies material. Authority still comes from explicit facts: decisions require confirmer, status, date, and scope; corrections require target, corrected content, reason, date, and scope.
 
 ## First build: precompiled Markdown sources and KB compilation
 
-1. Export one complete schema 3.0 governed asset package with `ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <package> --host <host>`. Require `truncated=false` and authenticated entry/dependency closure. Use `all_visible` only on explicit user request.
-2. Preserve the local planning and rendering stages. Read the compact knowledge indexes, including dashboard notes, and only the normalized details needed for project positioning, business objects, object relationships, judgment chains, ambiguous grouping, conflicts, SQL semantics, and recall-card choices. Author one snapshot-bound plan using [`project_semantic_knowledge_wiki_plan_schema.md`](project_semantic_knowledge_wiki_plan_schema.md). This is the run's only Agent synthesis pass. Do not create the plan with a generic script. Do not hardcode project names, business domains, asset IDs, event names, metric names, or example decision chains into the workflow; examples are illustrative only, and the Agent must derive the current project's model from the current package. If many summaries share the same template with only names or fields changed, discard the plan and have the Agent reread the relevant asset definitions.
+1. Export one complete schema 3.0 governed asset package with `ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <package> --host <host>`. Require `truncated=false` and authenticated entry/dependency closure. Use `all_visible` only on explicit user request. The export always includes current `ADOPTED` personal semantics for this project in `sources/adopted-personal-semantics.jsonl`; do not add a switch to exclude them and do not run a second personal-semantic export.
+   If the governed dashboard, report, and metric catalogs and adopted personal semantics are all empty, this is a valid new-project initialization. Do not ask the user to choose between an empty skeleton and all visible assets. Do not switch to `all_visible` or invent business facts. Run the empty-skeleton builder below, upload its ZIP through the same company-only wrapper, prepare/apply the preset as described below, compile full, and read back the project overview and governance boundary. Skip the semantic planning and normal builder steps below in this case. Resolve the model and company KB target as usual before upload.
+
+   ```bash
+   node skills/ae-analysis/scripts/project-semantic-knowledge-wiki/build-empty-skeleton.mjs \
+     --asset-package <tmp>/project-assets --output <tmp>/empty-skeleton \
+     --project-name '<project_name>'
+   node "$KB_RUN" +add --name '<company_kb_name>' \
+     --files '["<tmp>/empty-skeleton/empty-skeleton.zip"]' --host <host>
+   node skills/ae-analysis/scripts/project-semantic-knowledge-wiki/prepare-compile-schema.mjs \
+     --name '<company_kb_name>' --host <host> --output '<new-formal-rules-file>' --request-id '<initialization-id>'
+   # If review_import is returned, review and apply the candidate below before compilation.
+   # Wait for generated Schema status, then compile.
+   node "$KB_RUN" +compile --name '<company_kb_name>' --mode full --model <model_ref> --host <host>
+   ```
+2. Preserve the local planning and rendering stages. Read the compact knowledge indexes, including dashboard notes, the adopted personal semantic source file, and only the normalized details needed for project positioning, business objects, object relationships, judgment chains, ambiguous grouping, conflicts, SQL semantics, personal context fusion, and recall-card choices. Author one snapshot-bound plan using [`project_semantic_knowledge_wiki_plan_schema.md`](project_semantic_knowledge_wiki_plan_schema.md). This is the run's only Agent synthesis pass. Do not create the plan with a generic script. Do not hardcode project names, business domains, asset IDs, event names, metric names, personal-semantic conclusions, or example decision chains into the workflow; examples are illustrative only, and the Agent must derive the current project's model from the current package. If many summaries share the same template with only names or fields changed, discard the plan and have the Agent reread the relevant asset definitions.
 3. Render the locally precompiled material for review and generate Markdown sources. The review ZIP is a local artifact; upload the source ZIP from the next step:
 
    ```bash
@@ -105,7 +145,7 @@ The source tree only classifies material. Authority still comes from explicit fa
    ```
 
    When the exported package is `asset_scope=all_visible`, pass `--allow-all-visible` to the builder. Do not pass this flag unless the user explicitly requested all visible assets.
-4. Review the local project business model, domain judgment models, asset meanings, SQL summaries, domains, conflicts, and recall cards. The project overview must start with business positioning, business objects, object relationships, judgment chains, and non-goals; asset counts and snapshot metadata come later. Business-domain sources must contain the judgment model plus the short `Agent 使用摘要` for first-hop routing: business state judged, objects, signals, decision path, asset roles, primary analysis goals, preferred entries, main events, main metrics, drilldown dimensions, and boundaries. Non-SQL report summaries must not repeat the same generated sentence as both purpose and applicable question; they should expose the report's business use, usable questions, metrics/outputs, drilldown dimensions, filters and boundaries from structured asset evidence, and use "return to source report to confirm" wording for missing fields instead of parser-style `未识别/未发现` placeholders. SQL report sources must also use one `Agent 使用摘要`, but that single section must contain the complete Agent-authored SQL semantics: purpose, parameters, output fields, grain, filters, limits, question boundaries, and evidence locator. This section must be business language an Agent can use directly, not parser labels such as `SQL 输出字段`, `来源表达式`, `${Selector:...}`, `${PartDate:...}`, `C00`, raw SQL fragments, or visible build-process phrases such as `CLI Agent 基于同一资产快照生成`, `摘要来源`, `semantic_plan`, `builder`, `parser fallback`. All business analysis should be completed here; missing evidence remains explicitly unknown. Precompile affected assets and their dependent domains/cards only on refresh; reuse unchanged semantic plan entries.
+4. Review the local project business model, domain judgment models, asset meanings, SQL summaries, adopted personal-semantic fusion, domains, conflicts, and recall cards. The project overview must start with business positioning, business objects, object relationships, judgment chains, and non-goals; asset counts and snapshot metadata come later. Business-domain sources must contain the judgment model plus the short `Agent 使用摘要` for first-hop routing: business state judged, objects, signals, decision path, asset roles, primary analysis goals, preferred entries, main events, main metrics, drilldown dimensions, and boundaries. Adopted personal semantics must be fused by type: `background` can enrich project background and domain context, `preference` can shape preferred routing and answer style, `experience` can add proven analysis heuristics and caveats, and `asset_context` can annotate concrete reports/dashboards/metrics only when the referenced asset still exists. Preserve the source person's display name and source/update time from the payload in the local source page provenance; never expose backend identifiers such as `open_id` in KB Markdown. Non-SQL report summaries must not repeat the same generated sentence as both purpose and applicable question; they should expose the report's business use, usable questions, metrics/outputs, drilldown dimensions, filters and boundaries from structured asset evidence, and use "return to source report to confirm" wording for missing fields instead of parser-style `未识别/未发现` placeholders. SQL report sources must also use one `Agent 使用摘要`, but that single section must contain the complete Agent-authored SQL semantics: purpose, parameters, output fields, grain, filters, limits, question boundaries, and evidence locator. This section must be business language an Agent can use directly, not parser labels such as `SQL 输出字段`, `来源表达式`, `${Selector:...}`, `${PartDate:...}`, `C00`, raw SQL fragments, or visible build-process phrases such as `CLI Agent 基于同一资产快照生成`, `摘要来源`, `semantic_plan`, `builder`, `parser fallback`. All business analysis should be completed here; missing evidence remains explicitly unknown. Precompile affected assets, personal-semantic source pages, and their dependent domains/cards only on refresh; reuse unchanged semantic plan entries.
 5. Package the builder's Markdown sources. Raw JSON indexes and raw SQL remain in the local review/evidence package; the KB input contains the precompiled meanings and structured calculation facts.
 
 Package the builder's prepared Markdown sources into the source tree:
@@ -122,18 +162,19 @@ Then upload and run KB compilation:
 
 ```bash
 node "$KB_RUN" +add --name '<company_kb_name>' --files '["<new-archive>.zip"]' --host <host>
-node "$KB_RUN" +schema --name '<company_kb_name>' --model <model_ref> \
-  --custom-instructions-file skills/ae-analysis/scripts/project-semantic-knowledge-wiki/default-compile-rules.md --host <host>
-node "$KB_RUN" +status --name '<company_kb_name>' --host <host>
-# Run only after schema generation succeeds.
+node skills/ae-analysis/scripts/project-semantic-knowledge-wiki/prepare-compile-schema.mjs \
+  --name '<company_kb_name>' --host <host> --output '<new-formal-rules-file>' --request-id '<initialization-id>'
+# review_import requires full candidate/diff review and explicit application; reuse is already compile-ready.
 node "$KB_RUN" +compile --name '<company_kb_name>' --mode full --model <model_ref> --host <host>
 ```
 
-Poll `+status`; never poll by resubmitting Schema. Schema/compile failure stops the flow; do not switch to snapshot import. Start with a few representative assets before attempting the complete package.
+Poll `+status`; never poll by generating Schema again. Rule initialization or compilation failure stops the flow; do not switch to snapshot import. Start with a few representative assets before attempting the complete package.
 
 ## Refresh: update changed Markdown sources
 
-Regenerate the local Wiki using the existing semantic-plan contract. On refresh, reuse unchanged semantic-plan entries instead of asking the Agent to rewrite them. The builder persists the reusable semantic plan and fragment-level state in `sources/project/<namespace>-refresh-state.md`, and records each Markdown source's fragment dependencies. A changed recall card, SQL summary, domain model, appendix, or project model affects only sources that reference that fragment; never treat the whole semantic-plan file hash as a full-source rewrite trigger. When the asset package snapshot hash changes but the existing plan is intentionally reused, pass `--allow-semantic-plan-snapshot-drift`; the builder still validates current project, domain, asset, recall-card and SQL-report references against the new package and stops if the closure no longer matches. Do not use this flag for first build or to bypass real asset additions/removals. Use normalized content hashes from the builder's upload manifests so snapshot-only header changes do not rewrite every asset:
+When refreshing an empty skeleton, export a fresh governed package first. If both source classes are still empty, do not rewrite or recompile an unchanged skeleton. If governed entry assets have appeared, synthesize the first evidence-based semantic plan and run the normal builder. Read the skeleton's remote `sources/project/<namespace>-refresh-state.md` and pass it to the source-tree packager as `--previous-refresh-state`. Its taxonomy version intentionally differs from the populated Wiki, so the packager requests `compile_mode=full` and explicit rule-compatibility review. Reuse valid compatible rules; do not regenerate Schema. Apply the resulting add/replace/remove actions to the existing company ZIP with revision checks, including removal of obsolete empty-state sources; preserve human sources and unrelated ZIP paths. Never create a second KB or reuse the empty skeleton's unknown statements as business facts. If only adopted personal semantics appear while entry assets remain empty, do not run the asset builder or claim the skeleton is current; report that the personal-only source path is not yet supported.
+
+Regenerate the local Wiki using the existing semantic-plan contract. On refresh, reuse unchanged semantic-plan entries and unchanged adopted-personal-semantic fusion entries instead of asking the Agent to rewrite them. The builder persists the reusable semantic plan and fragment-level state in `sources/project/<namespace>-refresh-state.md`, and records each Markdown source's fragment dependencies. A changed recall card, SQL summary, domain model, adopted personal semantic, appendix, or project model affects only sources that reference that fragment; never treat the whole semantic-plan file hash as a full-source rewrite trigger. When the asset package snapshot hash changes but the existing plan is intentionally reused, pass `--allow-semantic-plan-snapshot-drift`; the builder still validates current project, domain, asset, adopted personal semantic, recall-card and SQL-report references against the new package and stops if the closure no longer matches. Do not use this flag for first build or to bypass real asset additions/removals. Use normalized content hashes from the builder's upload manifests so snapshot-only header changes do not rewrite every asset:
 
 ```bash
 node skills/ae-analysis/scripts/project-semantic-knowledge-wiki/build-project-semantic-wiki.mjs \
@@ -157,9 +198,9 @@ node skills/ae-analysis/scripts/project-semantic-knowledge-wiki/package-wiki-sou
   --baseline-published-version-id <published_version_id>
 ```
 
-The normal refresh baseline is remote managed state, not the local filesystem. Read `+list-sources` once to get the ZIP source ID and current `contentRevision`, then read only `sources/project/<namespace>-refresh-state.md`. The refresh state hidden payload contains the previous semantic plan, fragment state, source-tree manifest, source ID, content revision, published version ID, and manifest hash. If `contentRevision` matches the saved baseline, use `--previous-refresh-state` and compare against the saved source-tree manifest; do not page through every remote file and do not run full `+source-read` over the ZIP. If it differs, treat the baseline as potentially stale but still start from `--previous-refresh-state`; verify only paths that would be written or removed before mutating them, and escalate to a full source-tree read only when the refresh state is missing, corrupt, or cannot explain the required conflict check. A local `<previous>-kb-source-tree-manifest.json` with `--previous-manifest` is a compatibility fallback for manual repair runs, not the scheduled path.
+The normal refresh baseline is remote managed state, not the local filesystem. Read `+list-sources` once to get the ZIP source ID and current `contentRevision`, then read the small `sources/project/<namespace>-refresh-state.md` index. For schema `2.0`, read each listed `-part-NNN.md` into the same local directory using the exact filenames; never read the whole ZIP or concatenate the parts in an Agent tool response. The packager verifies each part, the complete payload, and the stored manifest before planning changes. A legacy single-file base64 state remains readable. The state contains the previous semantic plan, fragment state, source-tree manifest, source ID, content revision, published version ID, and manifest hash. If `contentRevision` matches the saved baseline, use `--previous-refresh-state` and compare against the saved source-tree manifest; do not page through every remote file and do not run full `+source-read` over the ZIP. A machine-state-only migration can advance the ZIP revision without changing business sources. If the revision differs, treat the baseline as potentially stale but still start from `--previous-refresh-state`; verify only paths that would be written or removed before mutating them, and escalate to a full source-tree read only when the refresh state is missing, corrupt, or cannot explain the required conflict check. A local `<previous>-kb-source-tree-manifest.json` with `--previous-manifest` is a compatibility fallback for manual repair runs, not the scheduled path.
 
-The returned plan contains add/replace/remove actions and unchanged paths under `sources/...`, with `skip` or `incremental` compilation. `--previous-tree-root` lets a repair run re-hash the last applied local baseline with the current normalizer, so harmless compiler/normalization-rule changes do not create a one-time false delta. Do not replace an existing ZIP parent. Before each write, verify the target remote bytes still match the saved source-tree manifest hash for that path; preserve unexpected manual edits and stop on conflicts. After successful writes, replace the managed refresh-state source with the new payload produced by `--embed-refresh-state-baseline` so the next run remains independent of local state. Compare by the stable ZIP-relative `sources/...` path. Do not replace the ZIP parent or re-upload every file. Do not run the old flat-source uploader or `plan-kb-source-sync.mjs`.
+The returned plan contains add/replace/remove actions and unchanged paths under `sources/...`, with `skip` or `incremental` compilation. Adopted personal semantics use the same source-tree manifest, stable ZIP-relative paths, content hashes, conflict checks, and add/replace/remove actions as asset sources; do not maintain a separate personal-semantic delta file or a second upload flow. When a previously adopted personal semantic is edited, its review status becomes `NONE`, it disappears from the next adopted source export, and the next refresh removes or rewrites only the generated paths whose fragment dependency points to that source. `--previous-tree-root` lets a repair run re-hash the last applied local baseline with the current normalizer, so harmless compiler/normalization-rule changes do not create a one-time false delta. Do not replace an existing ZIP parent. Before each write, verify the target remote bytes still match the action's `previous_content_hash`; for the v2 index and part files this is the raw file SHA-256, while legacy sources use the existing normalized content hash. Preserve unexpected manual edits and stop on conflicts. Apply the index and every listed part action; a machine-state-only change keeps `compile_mode=skip`. Compare by the stable ZIP-relative `sources/...` path. Do not replace the ZIP parent or re-upload every file. Do not run the old flat-source uploader or `plan-kb-source-sync.mjs`.
 
 For each changed path, obtain the current revision and perform one existing command through the wrapper:
 
@@ -173,9 +214,9 @@ node "$KB_RUN" +source-rm --name '<company_kb_name>' --id <zip_source_id> \
 
 Only remove files owned by this generated asset package. Preserve unrelated source material and unexpected manual edits; stop on conflicts. Keep deletion confirmation unless the exact refresh deletion scope is already authorized. Execute sequentially using returned revisions; a 409 requires fresh discovery and review, not blind retry. Failed writes stop compilation. On resume, compare current remote bytes again so already successful writes are not replayed. Unchanged files are not written. Apply changed Markdown manifest/index sources from the plan too; keep the JSON sync manifest local. A refresh-state-only baseline update is a managed-state write and does not by itself require compilation.
 
-After all source-tree changes succeed, call `+compile --mode incremental --model <model_ref>` exactly once. Reuse the existing Schema. Do not force full compilation based only on file count or percentage. No file changes means skip compilation unless the user explicitly requests rebuilding or compiler rules have changed. Schema/authority/taxonomy rule changes require an explicit rebuild decision; normal source updates do not.
+After all source-tree changes succeed, use the source-tree packager's `compile_mode`. `skip` needs no preparation, upload, AI validation or compilation unless explicitly requested. Otherwise run `prepare-compile-schema.mjs` with a fresh output path: valid formal rules return `schema_action=reuse` and `compile_ready=true` without generation, upload, application or AI validation. Call `+compile --mode incremental --model <model_ref>` once for `incremental`, or `+compile --mode full --model <model_ref>` once for `full`. A full rebuild, source-change volume or navigation migration does not trigger Schema generation. `navigation_taxonomy_migration.requires_schema_review=true` requires checking that the formal rules support the new navigation; an incompatible older preset needs an explicit reviewed rule upgrade, never automatic replacement. The legacy `requires_schema_force` field remains false; legacy `schema_force_reasons` explain full-build reasons only. Preserve human sources and unrelated ZIP paths. Normal content updates still use incremental mode.
 
-Compiled navigation must stay decision-oriented. The generated Wiki homepage should first point to the project business model, then business domains, recall cards, category indexes, governance/review pages, and a small set of representative titled entries only. It should not list every report/dashboard file or bare numeric IDs. Individual assets belong in their category index or domain context, with title-first link text and IDs as supporting identity.
+Compiled navigation must follow the five layers: project overview, shared project knowledge, business domains, event and asset catalog, and governance with provenance. Recall cards belong under domains. The homepage should contain a small set of representative titled entries only, not every report/dashboard file or bare numeric IDs. Individual assets belong in their category index or domain context, with title-first link text and IDs as supporting identity. Public event groups are lookup indexes, not business domains.
 
 ## Acceptance and readback
 
@@ -208,13 +249,13 @@ canonical_asset_id: report:1234 | null
 
 - `authenticated=true` maps only to `certification_state=certified`; it never overrides a definition conflict. In explicit `all_visible` mode, unauthenticated assets remain visible as `certification_state=uncertified` and must not be described as approved/governed semantics.
 - A detectable conflict always yields `runtime_policy=block` and `standalone_recall=false` until reviewed.
-- An unauthenticated child retained through a certified parent is `dependency_only`; it can support its parent but cannot independently become the answer.
+- An unauthenticated child retained through a certified parent is `dependency_only`; its verified definition and dependencies may answer definition or relationship questions. It cannot independently establish a business state or current number. When direct retrieval is unavailable, inspect the authorized parent and state the remaining gap.
 - Technical appendix, duplicate, demo, reproduction, and targeted-diagnostic assets are blocked from standalone recall.
 - Ranking order is: project/permission/status filter -> recall card -> canonical and valid assets -> certification -> semantic relevance and usage. Raw evidence never participates in first-round broad recall.
 
 ## SQL report rules
 
-Every SQL report requires structured semantics grounded in the packaged SQL and parameters. The compiled Wiki must include one CLI Agent-authored `## Agent 使用摘要` for every SQL report. That single section is the primary SQL business source; do not create a second SQL-specific summary section. The local review retains `sql_semantic_facts` and raw SQL for audit. KB consumes the precompiled meanings and only reopens analysis for concrete inconsistencies or new human evidence. Apply `default-compile-rules.md` to preserve:
+Every SQL report requires structured semantics grounded in the packaged SQL and parameters. The compiled Wiki must include one CLI Agent-authored `## Agent 使用摘要` for every SQL report. That single section is the primary SQL business source; do not create a second SQL-specific summary section. The local review retains `sql_semantic_facts` and raw SQL for audit. KB consumes the precompiled meanings and only reopens analysis for concrete inconsistencies or new human evidence. Apply the durable `default-compile-schema.md` preset to preserve:
 - business purpose;
 - input parameters and their meaning;
 - output fields;
@@ -229,4 +270,4 @@ The builder rejects a plan that omits any SQL report or contains mechanically ge
 
 ## Existing flat-source knowledge bases
 
-Do not automatically migrate existing flat sources or read-only snapshots. Keep existing user material and resolve a separate migration scope when necessary. Source-tree refresh uses the recorded ZIP source ID and directory mutations above.
+For an existing managed source-tree knowledge base, `navigation_taxonomy_version` missing or below `2.0` triggers the full Wiki rebuild on its next refresh. Source-tree refresh uses the recorded ZIP source ID and directory mutations above; it never deletes human-authored sources. Read-only snapshots and unmanaged flat sources have no verified managed baseline and must be reviewed separately before migration.

package/skills/ae-analysis/references/project_semantic_knowledge_wiki_plan_schema.md

@@ -1,6 +1,6 @@
 # Project semantic knowledge Wiki plan
 
-The Agent authors exactly one plan per asset-package snapshot. The builder validates every referenced asset against the package.
+The Agent authors exactly one plan per asset-package snapshot. The builder validates every referenced asset against the package. New plans must fill `recall_cards[].routing` from verified evidence. Older 2.0 plans without routing still compile with a conservative domain fallback; branches may only target assets already listed in that card's preferred or fallback references.
 
 ```json
 {
@@ -88,6 +88,21 @@ The Agent authors exactly one plan per asset-package snapshot. The builder valid
             }
           ],
           "fallback_asset_refs": [],
+          "routing": {
+            "applicable_when": "问法、对象与范围何时适用本卡",
+            "answer_grain": "答案对象与统计粒度",
+            "required_parameters": ["时间范围或过滤参数"],
+            "branches": [
+              {
+                "when": "满足哪种已核验的问法和口径",
+                "asset_refs": [{"resource_type": "dashboard", "resource_key": "1234", "reason": "分支采用该资产的证据"}],
+                "reason": "为什么该分支使用这些资产"
+              }
+            ],
+            "stop_when": "何时已取得足够且权威的最小证据",
+            "fallback_when_unavailable": "无匹配、冲突、权限不可用时如何回到域内筛选或说明缺口",
+            "evidence_boundary": "不可互替口径、当前数值执行与证据强度边界"
+          },
           "excluded_asset_refs": [
             {
               "resource_type": "report",
@@ -102,6 +117,27 @@ The Agent authors exactly one plan per asset-package snapshot. The builder valid
       ]
     }
   ],
+  "personal_semantic_integrations": [
+    {
+      "integration_id": "stable-personal-semantic-integration-id",
+      "context_type": "background | preference | experience | asset_context",
+      "source_ids": ["personal_semantic:42"],
+      "title": "融合后的项目语义标题",
+      "project_usage": "这组个人语义如何被项目知识库消费",
+      "integration_target": {
+        "target_type": "project | domain | asset | recall_card",
+        "target_id": "project, domain_id, resource_key, or card_id"
+      },
+      "source_people": [
+        {
+          "owner_name": "source owner display name from payload",
+          "updated_at": "source update time from payload"
+        }
+      ],
+      "conflict_policy": "compatible | scoped | blocked",
+      "boundaries": ["适用范围、冲突或必须回源确认的边界"]
+    }
+  ],
   "appendices": [
     {
       "appendix_id": "technical-or-temporary-assets",
@@ -139,6 +175,9 @@ The Agent authors exactly one plan per asset-package snapshot. The builder valid
 - `project_business_model` is required. It must explain how the project observes business before listing assets: positioning, audience roles, business objects, object relationships, decision chains, and non-goals.
 - `project_business_model` and every `domain_judgment_model` must be derived from current asset-package evidence. Do not hardcode project names, business domains, asset IDs, event names, metric names, or example decision chains into the workflow.
 - Every business object, object relationship and decision chain must cite concrete `dashboard`, `report`, or `metric` refs from the current package. A decision chain must reference existing domain IDs and explain when live execution is required.
+- Adopted personal semantic integrations must cite concrete `personal_semantic:<id>` source IDs from `sources/adopted-personal-semantics.jsonl`. Group and fuse them by `context_type`: `background`, `preference`, `experience`, and `asset_context`.
+- `asset_context` integrations must target an existing dashboard, report, metric, domain, or recall card. If the referenced asset no longer exists, do not attach the personal semantic to a live asset page; mark the integration as blocked or scoped historical context.
+- Personal semantic integrations are project context, routing preferences, heuristics, or asset annotations. They do not override governed project semantic records, current asset definitions, SQL/calculation facts, or live query results unless an explicit correction/decision source gives that authority.
 - Domain titles represent business retrieval topics, not physical dashboard-space names.
 - Every domain has one `domain_judgment_model` describing the business state judged, objects, signals, decision path, asset roles and boundaries. A domain that only lists questions, events, metrics, dimensions and assets is not acceptable.
 - Every domain has at least one recall card. Preferred and fallback refs must belong to that domain's dashboard/report closure or be a reusable metric directly referenced by it.

package/skills/ae-analysis/references/report_create.md

@@ -9,16 +9,26 @@ Read [`ai_models.md`](ai_models.md) for the single AI-facing model registry. Rep
 Command:
 
 ```bash
-ae-cli analysis report create --project-id <project_id> --report-name "Demo" --model-type event --definition '{...}' [--resolutions '<confirmed_resolution_json>'] [--report-desc "..."] [--dashboard-ids "[1001]"]
+ae-cli analysis report create --project-id <project_id> --report-name "Demo" --model-type event --definition '{...}' [--presentation '{"chart_type":"line","table_layout":"date"}'] [--resolutions '<confirmed_resolution_json>'] [--report-desc "..."] [--dashboard-ids "[1001]"]
 ```
 
 When the caller supplies an existing snapshot, optional `--intent-snapshot` accepts `schema_version: 1`, non-empty `requirement`, `definition` and `model_type`. The CLI checks that its definition and model match the submitted values locally; the snapshot is never sent to Gateway.
 
-Input sends `project_id`, `report_name`, `model_type`, `definition`, optional user-confirmed `resolutions`, `report_desc`, `cache_seconds`, `query_duration_ms`, and `dashboard_ids`. `--resolutions` is not supported with `--model-type tag`.
+Input sends `project_id`, `report_name`, `model_type`, `definition`, optional top-level `presentation`, user-confirmed `resolutions`, `report_desc`, `cache_seconds`, `query_duration_ms`, and `dashboard_ids`. `--resolutions` is not supported with `--model-type tag`.
+
+Omitting `--report-desc` or passing `--report-desc ""` sends `report_desc: ""`, matching analysis-page creation. This default applies only to creation: [`report update`](report_update.md) preserves the saved description when `--report-desc` is omitted, and clears it when explicitly empty.
+
+## Event-report presentation
+
+For `model_type=event`, optional `presentation` is separate from `definition`. `chart_type` accepts `line`, `combo`, `bar`, `stacked`, `cumulative`, or `pie`; `table_layout` accepts `date`, `event`, or `group` for the analysis page's result table. The gateway checks compatibility with the saved definition; pie always requires grouping without time comparison. A total-time report supports bar, or pie only when those grouping/comparison conditions hold. Omission leaves page-default/inherited settings. This contract does not expose presentation writes for other models.
+
+For `combo`, explicitly set a requested non-total `definition.time_particle_size` such as `day` (omission defaults to `total`), and supply report-level `presentation.series` with metric indexes and bar/line + primary/secondary axes. Read [event-report presentation](event_report_presentation.md) for the version-bound metric binding, subset/reset contract, examples and impact on inherited dashboard trends. It also distinguishes combo from cumulative and corrects the event pie mapping; never use raw graph codes.
+
+A table card is a dashboard-level display, not `presentation.chart_type=table` on the source report. To create a table card, create the event report, associate it through `--dashboard-ids` or [`dashboard-report add`](dashboard_report_add.md), then call [`dashboard-report update`](dashboard_report_update.md) with the returned report ID, exact dashboard ID, and `--chart-type table`. Do not insert `graphShape`, `byType`, `reportGraphShape`, or other raw QP/UI fields into the definition or presentation.
 
 Saved report definitions follow the filter write boundary in [`ai_models.md`](ai_models.md): one compound group level with leaf-only, non-empty `items`. A deeper tree or empty group is rejected by the capability schema as `INVALID_CAPABILITY_INPUT`; use the returned field path or schema keyword to correct it, and never flatten a deeper tree.
 
-Output is the gateway envelope. `data` contains the created `report_id`, creation status, normalized `model_type`, AI QP `definition`, and optional resolution warnings.
+Output is the gateway envelope. `data` contains the created `report_id`, creation status, normalized `model_type`, AI QP `definition`, event-report `presentation`, and optional resolution warnings. Card presentation is read separately with `dashboard-report get`.
 
 Report creation and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves the full structured error array. No report is created on this failure; follow [`metadata_resolution.md`](metadata_resolution.md), keep each bound field's path and original wording, fill confirmed model parameters, and pass `--resolutions` only after user confirmation.
 

package/skills/ae-analysis/references/report_get.md

@@ -14,7 +14,11 @@ Input sends `project_id` and `report_id`.
 
 This command reads saved definition metadata and deliberately has no `--use-cache` option. Cache selection applies to `report-data run/export`, not to definition reads.
 
-Output is the gateway envelope. `data` contains `version`, `model_type`, `definition`, report metadata, and dashboard membership in snake_case. Use `data.version` as `--report-version` when updating the same report. Raw frontend `events`, `event_view`, `visual_view`, and raw QP are not returned.
+Output is the gateway envelope. `data` contains `version`, `model_type`, `definition`, report metadata, and dashboard membership in snake_case. Event reports additionally expose separate `presentation` with `chart_type` and `table_layout`. Use `data.version` as `--report-version` when updating the same report. Raw frontend `events`, `event_view`, `visual_view`, and raw QP are not returned.
+
+`presentation.chart_type` describes the source report's effective chart under the current definition. `presentation.table_layout` describes its persisted result-table layout when readable; a legacy report without a persisted layout omits it because that setting can be inherited from the browser, not because it is necessarily `date`. For a table card on a specific analysis board, read [`dashboard-report get`](dashboard_report_get.md) with the exact dashboard ID. A raw chart code such as `L0` can coexist with a displayed result table or a dashboard table card; it is not proof of a read failure. Use the semantic response fields, and state unknown/null presentation fields as inherited/unknown rather than inventing values.
+
+For an effective trend, presentation also returns `series_scope=report` and per-metric `series` including default styles/axes. Non-default series can make `chart_type=combo` despite native `graphShape=L0`. Match each 1-based series index to this response's `definition.metrics` order, and use its current version for a subsequent source-series write. Read [event-report presentation](event_report_presentation.md) before interpreting or editing combination styles/axes.
 
 Reads preserve historical filter trees without flattening, including definitions deeper than the current analysis page can author. Follow the read/write boundary in [`ai_models.md`](ai_models.md): omit `definition` for metadata-only changes, and never feed an unsupported historical tree back as a definition update.
 

package/skills/ae-analysis/references/report_update.md

@@ -1,6 +1,6 @@
 # analysis report update
 
-Use when the user explicitly wants to update saved report metadata or replace its AI QP definition.
+Use when the user explicitly wants to update saved report metadata, replace its AI QP definition, or change an event report's chart/result-table layout.
 
 Do not use raw QP, `qp`, `report_model`, or `analysis_query`. When changing the definition, pass `model_type` and AI QP `definition` together.
 
@@ -11,15 +11,26 @@ Command:
 ```bash
 ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --report-name "New name"
 ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --model-type event --definition '{...}' [--resolutions '<confirmed_resolution_json>']
+ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --presentation '{"table_layout":"event"}'
 ```
 
 When the caller supplies an existing snapshot, optional `--intent-snapshot` accepts `schema_version: 1`, non-empty `requirement`, `definition` and `model_type`. The CLI checks that its definition and model match the submitted values locally; the snapshot is never sent to Gateway. Metadata-only updates use no definition snapshot.
 
-Input sends `project_id`, `report_id`, `version` from CLI `--report-version`, and at least one of `report_name`, `report_desc`, or `definition`. Read `version` from `analysis report get` before updating. `model_type` is required when `definition` is provided; `resolutions` is allowed only when a definition is provided and is not supported with `model_type=tag`.
+Input sends `project_id`, `report_id`, `version` from CLI `--report-version`, and at least one of `report_name`, `report_desc`, `definition`, or top-level `presentation`. Read `version` from `analysis report get` before updating. `model_type` is required when `definition` is provided; `resolutions` is allowed only when a definition is provided and is not supported with `model_type=tag`.
+
+## Preserve display settings
+
+For same-model definition updates, omit `presentation` to preserve the saved event-report chart and result-table layout. For a display-only change, send `--presentation` without `--definition` or `--model-type`, using the current version. Only supplied presentation fields change; omitted fields are retained. Supported only for event reports: `chart_type=line|combo|bar|stacked|cumulative|pie`, `table_layout=date|event|group`, and report-level `series`. The gateway validates the effective presentation against the saved definition; pie always requires grouping without time comparison. Total-time reports support bar, or pie only when those grouping/comparison conditions hold. A model change uses the target model's display defaults unless an allowed event presentation is supplied.
+
+For combination styles/axes, read [event-report presentation](event_report_presentation.md) before updating. Series is a subset patch; `[]` is an explicit reset, and `chart_type=line` resets all series to primary-axis lines. Metric positions are tied to the current returned `definition.metrics` and report version. Changing source series also affects its other trend (`L0`) cards; card updates cannot override series locally. During definition changes, the server preserves uniquely matched technical metrics and rejects unsafe non-default series loss with `SERIES_PRESERVATION_CONFLICT`; follow its reset guidance instead of silently carrying old indexes into new metrics.
+
+Non-empty series-only updates require an existing compatible trend. Empty `series: []` also clears retained series on a compatible non-trend chart without changing that chart type. When changing from another chart, use explicit `chart_type=combo` with non-empty series; do not attach non-empty series to an explicit bar/pie/cumulative/line choice. If a definition change invalidates a previously valid chart, implicit preservation fails before writing; follow its compatible-chart guidance rather than promising an unchanged invalid display.
+
+To change a table card on an analysis board, use [`dashboard-report update`](dashboard_report_update.md) with `--chart-type table`, not report presentation. The source report, the analysis page's result table, and a dashboard card are separate display scopes. Raw `graphShape`, `byType`, `reportGraphShape`, `tableFormat`, and `dateOutside` are not authoring fields.
 
 Definition replacement follows the filter write boundary in [`ai_models.md`](ai_models.md): one compound group level with leaf-only, non-empty `items`. A deeper historical tree remains readable, but a deeper tree or empty group submitted for writing is rejected by the capability schema as `INVALID_CAPABILITY_INPUT`; use the returned field path or schema keyword to correct it. Omit `definition` for metadata-only changes and never flatten it.
 
-Output is the gateway envelope. `data` contains update status, `report_id`, and the normalized AI QP definition when a definition was updated.
+Output is the gateway envelope. `data` contains update status, `report_id`, and the normalized AI QP definition when a definition was updated, plus event-report `presentation`. It does not represent any dashboard card's display.
 
 When a definition is supplied, update and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves the full structured error array. The report is not changed on this failure; follow [`metadata_resolution.md`](metadata_resolution.md), keep each bound field's path and original wording, fill confirmed model parameters, and retry with `--resolutions` only after confirmation.
 
@@ -29,6 +40,6 @@ For a SQL `part_date` parameter, `use_timezone` is a boolean saved definition fi
 
 After a successful update, call `analysis-meta asset url-get` with the updated `report_id` and output its `markdown_link`.
 
-The capability schema includes model-specific nested definition validation. Unknown fields, including nested filter/time-range fields and diagnostic backing fields, are rejected instead of silently ignored. Use canonical snake_case keys and aggregation names such as `user_count`; event report metrics may additionally carry `display_name`. Inspect the report capability itself for the full saved-report definition schema.
+The capability schema includes model-specific nested definition validation. Unknown fields, including nested filter/time-range fields and diagnostic backing fields, are rejected instead of silently ignored. Use canonical snake_case keys and aggregation names such as `user_count`; event report metrics and funnel `steps[]` may additionally carry `display_name`. When replacing a funnel definition, preserve every step's returned `display_name` so custom labels survive the round trip. Inspect the report capability itself for the full saved-report definition schema.
 
 Use `--report-desc ""` to clear an existing description. Omitting `--report-desc` preserves the saved description. Clearing only the description is a valid metadata-only update.

package/skills/ae-analysis/references/system_query_monitor_overview.md

@@ -12,6 +12,8 @@ ae-cli system query-monitor overview --company-id <company-id> --cluster-names '
 
 Capability id: `system.query_monitor.overview`.
 
+Selected project IDs and space codes must belong to the supplied company. A different company's scope is rejected before chart data is read.
+
 The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
 
 ## Parameters

package/skills/ae-analysis/references/system_query_task_cancel.md

@@ -13,6 +13,8 @@ ae-cli system query-task cancel --company-id <company-id> --task-id <task-id> --
 
 Capability id: `system.query_task.cancel`.
 
+The task must belong to `--company-id` by project or workspace. A foreign-company or missing task ID is rejected before cancellation.
+
 Run `--dry-run` first, summarize the affected target and impact, then wait for explicit user confirmation before rerunning the unchanged command with global `--yes`.
 
 The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.

package/skills/ae-analysis/references/system_query_task_export.md

@@ -12,6 +12,10 @@ ae-cli system query-task export --company-id <company_id> --start-time '2026-07-
 
 Capability id: `system.query_task.export`.
 
+Selected project IDs and space codes must belong to the supplied company. A different company's scope is rejected before an export is submitted.
+
+The time range has the same completion-time semantics as [`query-task list`](system_query_task_list.md): inclusive boundary seconds, including milliseconds within the end second, and a maximum 31-day window. The CSV `start_time` is task initiation time, not the timestamp used for range filtering.
+
 If the required filter mappings are unknown, call `ae-cli system query-task options --company-id <company_id>` once. Reuse verified mappings within the same company/project scope; do not guess filter codes or cluster names.
 
 Use `--output` to wait and download the completed artifact. If interrupted, resume with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the same export response. See [`run_wait.md`](run_wait.md).
@@ -25,8 +29,8 @@ The response uses `ok`, `data`, and `meta`. Empty task data is a successful expo
 | Parameter | Required | Description |
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
-| `--start-time` | Yes | Inclusive range start in `yyyy-MM-dd HH:mm:ss`. |
-| `--end-time` | Yes | Inclusive range end in `yyyy-MM-dd HH:mm:ss`. |
+| `--start-time` | Yes | Inclusive completion-time range start in `yyyy-MM-dd HH:mm:ss`. |
+| `--end-time` | Yes | Inclusive completion-time range end, including the entire second, in `yyyy-MM-dd HH:mm:ss`. |
 | `--status-codes` | Yes | Non-empty task status-code JSON array. |
 | `--content-codes` | Yes | Non-empty query content-code JSON array. |
 | `--task-type-codes` | Yes | Non-empty query task-type-code JSON array. |

package/skills/ae-analysis/references/system_query_task_get.md

@@ -12,6 +12,8 @@ ae-cli system query-task get --company-id <company-id> --task-id <task-id>
 
 Capability id: `system.query_task.get`.
 
+The task must belong to `--company-id` by project or workspace. A foreign-company or missing task ID is rejected before details are read.
+
 The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
 
 ## Parameters

package/skills/ae-analysis/references/system_query_task_list.md

@@ -1,6 +1,6 @@
 # system query-task list
 
-Use when the user needs to list query-monitor tasks within a mandatory bounded time range.
+Use when the user needs historical query logs within a mandatory bounded time range. For the realtime monitoring tab, use `ae-cli system query-task realtime-list` instead.
 
 Do not use it outside the system query-task operation or with fields absent from the inspected capability schema.
 
@@ -14,6 +14,10 @@ Capability id: `system.query_task.list`.
 
 If the required filter mappings are unknown, call `ae-cli system query-task options --company-id <company_id>` once. Reuse verified mappings within the same company/project scope; do not guess filter codes or cluster names.
 
+Project IDs and workspace codes must belong to `--company-id`; foreign-company values are rejected before querying. The global system-project ID `-1` cannot be selected as a company-scoped project.
+
+The range filters query **completion time**, not the returned `start_time` (task initiation time). Both boundary seconds are inclusive, including milliseconds within the end second. A task started before the window can appear if it completed inside it. Compare list and export using the same completion-time window; do not reject rows solely because `start_time` is outside it. The range must not exceed 31 days.
+
 The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
 
 ## Parameters
@@ -21,8 +25,8 @@ The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `
 | Parameter | Required | Description |
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
-| `--start-time` | Yes | Inclusive lower bound in `yyyy-MM-dd HH:mm:ss`. |
-| `--end-time` | Yes | Inclusive upper bound in `yyyy-MM-dd HH:mm:ss`. |
+| `--start-time` | Yes | Inclusive completion-time lower bound in `yyyy-MM-dd HH:mm:ss`. |
+| `--end-time` | Yes | Inclusive completion-time upper bound, including the entire second, in `yyyy-MM-dd HH:mm:ss`. |
 | `--project-ids` | Conditional | Non-empty project IDs or space codes are required. |
 | `--space-codes` | Conditional | Non-empty space codes or project IDs are required. |
 | `--status-codes` | Yes | Task status-code JSON array. |

package/skills/ae-analysis/references/system_query_task_options.md

@@ -1,6 +1,6 @@
 # system query-task options
 
-Use before query-task list or export to discover every valid filter value exposed by the current environment.
+Use before query-task list, realtime-list, or export to discover valid filter values exposed by the current environment.
 
 Command:
 
@@ -18,7 +18,7 @@ The response maps:
 - `projects[].project_id` and `workspaces[].space_code` to display names.
 - `clusters[].cluster_name` to its query engine metadata.
 
-Use the returned codes and names unchanged in `query-task list` or `query-task export`. Do not infer codes from UI labels or examples.
+Project and workspace options are limited to `--company-id`; status, content, task type, and cluster codes remain discoverable. Use the returned codes and names unchanged in `query-task list`, `query-task realtime-list`, or `query-task export`. Discovery does not authorize a project or workspace; execution still checks company ownership. Do not infer codes from UI labels or examples.
 
 ## Parameters