@thinkingai/ae-cli 6.0.52 → 6.0.54

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

@@ -1,23 +1,25 @@
 # Project Semantic Knowledge Base Wiki
 
-Requires `project_semantic_enable=on` for the target project. If export returns `PROJECT_SEMANTIC_DISABLED`, report that this project must enable `project_semantic_enable` and stop this workflow. Do not bypass the disabled entry point with other export, metadata, or capability commands.
+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
 
 When the user asks to build, update, refresh, rebuild, or sync a project semantic knowledge base from project assets, open this reference from `ae-analysis` and run the full loop here. Do not use this workflow for asset-certification or metric recommendations; those use `analysis-meta governance-recommendation export`.
 
-CLI Agent performs the main semantic precompilation: understand definitions and SQL, author complete asset meanings, domain relationships, recall boundaries, SQL business summaries, and evidence-backed conflicts, then render Markdown sources. Scripts only handle deterministic work: validation, IDs, links, packaging, source-tree diffs, and removal of parser/placeholder noise. They must not author business purpose, domain intent, SQL applicable questions, conflict interpretation, or visible rationale from templates. Upload those sources as an editable ZIP and let KB compile the final Wiki, integrate human context, maintain citations/navigation, and incrementally update affected pages. Never use `kb +import` for this workflow: a read-only snapshot cannot provide this source lifecycle.
+CLI Agent performs the main semantic precompilation: understand definitions and SQL, author a project-level business model, complete asset meanings, domain judgment models, domain relationships, recall boundaries, SQL business summaries, and evidence-backed conflicts, then render Markdown sources. Scripts only handle deterministic work: validation, IDs, links, packaging, source-tree diffs, and removal of parser/placeholder noise. They must not author business positioning, business objects, judgment chains, business purpose, domain intent, SQL applicable questions, conflict interpretation, or visible rationale from templates. Upload those sources as an editable ZIP and let KB compile the final Wiki, integrate human context, maintain citations/navigation, and incrementally update affected pages. Never use `kb +import` for this workflow: a read-only snapshot cannot provide this source lifecycle.
 
 ## Company-only target and permission boundary
 
@@ -34,7 +36,7 @@ The KB description is part of Agent auto-loading and source selection, not a cas
 For example, using a fictional project name:
 
 ```text
-示例项目的已认证资产语义知识库，帮助 Agent 在分析前查阅业务域、资产口径、SQL 报表含义和治理边界。
+示例项目已认证资产项目语义知识库，用于辅助 Agent 在分析前召回业务域、资产口径、SQL 报表语义和治理边界。
 ```
 
 ```bash
@@ -45,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
 
@@ -64,6 +87,11 @@ sources/
     reports/
     metrics/
     metadata/
+  personal-semantics/
+    background/
+    preference/
+    experience/
+    asset-context/
   business/
   meetings/
   decisions/
@@ -71,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 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. 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
@@ -103,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 asset meanings, SQL summaries, domains, conflicts, and recall cards. Business-domain sources must contain the short `Agent 使用摘要` for first-hop routing: primary analysis goals, preferred entries, main events, main metrics, drilldown dimensions, and boundaries. 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`, or raw SQL fragments. 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:
@@ -120,28 +162,45 @@ 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. 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 \
+  --asset-package <tmp>/project-assets-next \
+  --semantic-plan <previous-or-updated-semantic-plan.json> \
+  --output <next>/project-semantic-wiki \
+  --archive <next>/project-semantic-wiki.zip \
+  --project-name '<project_name>' \
+  --allow-semantic-plan-snapshot-drift
+```
 
 ```bash
 node skills/ae-analysis/scripts/project-semantic-knowledge-wiki/package-wiki-source-zip.mjs \
   --source-dir <next>-kb-upload-sources \
   --tree-output <next>-kb-source-tree \
   --manifest-output <next>-kb-source-tree-manifest.json \
-  --previous-manifest <previous>-kb-source-tree-manifest.json
+  --previous-refresh-state <remote-refresh-state.md> \
+  --embed-refresh-state-baseline \
+  --baseline-source-id <zip_source_id> \
+  --baseline-content-revision <current_content_revision> \
+  --baseline-published-version-id <published_version_id>
 ```
 
-The returned plan contains add/replace/remove actions and unchanged paths under `sources/...`, with `skip` or `incremental` compilation. Do not replace an existing ZIP parent. Before each write, verify the remote bytes still match the last applied local baseline; preserve unexpected manual edits and stop on conflicts. Retain unchanged baseline bytes and update the persisted source-tree manifest only after successful application. If interrupted, reconcile remote bytes before resuming. Compare by the stable ZIP-relative `sources/...` path; when the previous local files are unavailable, discover current paths with paginated `+source-ls` and compare via `+source-read`. 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 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. 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:
 
@@ -153,11 +212,11 @@ node "$KB_RUN" +source-rm --name '<company_kb_name>' --id <zip_source_id> \
   --path <removed-generated-path> --expected-revision <revision> --host <host>
 ```
 
-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.
+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 not list every report/dashboard file or bare numeric IDs. It should link to modules, business domains, recall cards, category indexes, governance/review pages, and a small set of representative titled entries only. 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
 
@@ -171,7 +230,7 @@ node "$KB_RUN" +grep --name '<company_kb_name>' --query '<business question or m
 node "$KB_RUN" +read --name '<company_kb_name>' --path '<path copied from index or grep>' --host <host>
 ```
 
-Do not assume the old local Wiki layout. Inspect actual server paths. Check asset IDs, SQL/calculation fidelity, certification, missing facts, cross-source conflict handling and provenance. Smoke-test a representative reusable asset. After refresh, verify additions, changed current definitions, removal of obsolete assertions and preservation of unchanged facts. Historical definitions may remain only when explicitly marked historical and evidenced. Publish statistics such as `reusedPages` are evidence; incremental mode alone does not prove lower model cost.
+Do not assume the old local Wiki layout. Inspect actual server paths. Check the project overview can answer: what business system this project observes, who uses it, what business objects exist, how objects relate, what decision chains exist, which assets attach to each chain, and what cannot be answered without live execution. Then check domain judgment models, asset IDs, SQL/calculation fidelity, certification, missing facts, cross-source conflict handling and provenance. Smoke-test a representative reusable asset. After refresh, verify additions, changed current definitions, removal of obsolete assertions and preservation of unchanged facts. Historical definitions may remain only when explicitly marked historical and evidenced. Publish statistics such as `reusedPages` are evidence; incremental mode alone does not prove lower model cost.
 
 Report target scope/name, requested model, ZIP source ID/revision, compile status/version, source counts and quality findings. Record observed compile duration and usage; small-sample success does not prove a full package will stay below turn limits.
 
@@ -190,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;
@@ -211,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,12 +1,52 @@
 # 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
 {
   "schema_version": "2.0",
   "source_snapshot_hash": "<asset package snapshot_hash>",
   "generation_method": "agent_semantic_synthesis",
+  "project_business_model": {
+    "business_positioning": "该项目观察的业务系统、服务对象和决策范围。必须从当前资产包证据归纳，不得写项目特化模板。",
+    "audience_roles": ["会使用这个项目做业务判断的角色"],
+    "business_objects": [
+      {
+        "object_id": "stable-object-id",
+        "name": "业务对象名称",
+        "meaning": "对象在本项目中的业务含义",
+        "evidence_refs": [
+          {"resource_type": "dashboard", "resource_key": "1234"}
+        ]
+      }
+    ],
+    "object_relationships": [
+      {
+        "from_object": "业务对象A",
+        "to_object": "业务对象B",
+        "relationship": "两个对象如何形成判断链路",
+        "evidence_refs": [
+          {"resource_type": "report", "resource_key": "5678"}
+        ]
+      }
+    ],
+    "decision_chains": [
+      {
+        "chain_id": "stable-chain-id",
+        "title": "业务判断链路名称",
+        "decision_question": "这条链路帮助用户判断什么",
+        "signals": ["判断信号、指标、状态或维度"],
+        "decision_steps": ["先看什么", "再看什么", "如何下钻或停止"],
+        "preferred_domain_ids": ["domain-id"],
+        "asset_refs": [
+          {"resource_type": "dashboard", "resource_key": "1234"}
+        ],
+        "requires_live_execution": true,
+        "boundaries": ["不能由知识库直接回答的边界"]
+      }
+    ],
+    "non_goals": ["本知识库不承载的内容"]
+  },
   "domains": [
     {
       "domain_id": "stable-lowercase-id",
@@ -19,6 +59,20 @@ The Agent authors exactly one plan per asset-package snapshot. The builder valid
       "drilldown_dimensions": [
         "Agent 总结的常用下钻维度、字段 key 和使用场景；不要写缺少业务解释的技术字段。"
       ],
+      "domain_judgment_model": {
+        "business_state_judged": "这个业务域判断什么业务状态",
+        "main_objects": ["涉及的业务对象"],
+        "signals": ["这个域使用的判断信号"],
+        "decision_path": ["域内判断步骤"],
+        "asset_attachment_logic": [
+          {
+            "asset_ref": {"resource_type": "dashboard", "resource_key": "1234"},
+            "role": "primary_entry | supporting_evidence | drilldown | exclusion",
+            "reason": "为什么这个资产挂在该业务判断链路上"
+          }
+        ],
+        "boundaries": ["这个域不能直接回答或必须实时执行的边界"]
+      },
       "merge_rationale": "跨物理空间归并或拆分的证据",
       "dashboard_ids": ["dashboard resource_key"],
       "recall_cards": [
@@ -34,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",
@@ -48,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",
@@ -82,7 +172,14 @@ The Agent authors exactly one plan per asset-package snapshot. The builder valid
 ## Rules
 
 - Every dashboard occurs exactly once across `domains[].dashboard_ids` and `appendices[].dashboard_ids`.
+- `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.
 - Every excluded ref names a concrete reason. A duplicate should name its canonical resource when known.
 - Every SQL report in the package has exactly one `sql_report_semantics` row. Unknown evidence is represented explicitly; it is never filled from the title.
@@ -90,4 +187,5 @@ The Agent authors exactly one plan per asset-package snapshot. The builder valid
 - `sql_report_semantics[].evidence_locator` exactly equals that report's packaged `source_detail_path`; never cite an external or guessed SQL definition.
 - A SQL report with `definition_state=valid` has at least one output field, one applicable question and one non-applicable question. Use `unknown` when those boundaries cannot be proven.
 - Visible SQL fields must use business names and meanings. Do not expose parser/debug terms such as `SQL 输出字段`, `来源表达式`, `${Selector:...}`, `${PartDate:...}`, `where 条件`, `order by`, or operator codes.
+- The generated Markdown must not expose build-process markers such as `CLI Agent 基于同一资产快照生成`, `摘要来源`, `semantic_plan`, parser fallback labels, or builder/debug terminology. Keep those only in local artifacts when needed for audit.
 - The plan contains no query results, customer rows, users, tokens, credentials, or conversation text.

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

@@ -13,7 +13,9 @@ ae-cli analysis-meta property export --project-id <project_id> --scope event --e
 
 Capability id: `metadata.property.export`.
 
-Input: the gateway receives `project_id` plus optional `table_type`, `scope`, `event_name`, `queries`, `fields`, and `authenticated_only`; `output` is local-only.
+Input: the gateway receives `project_id` plus optional `table_type`, `scope`, `event_name`, `queries`, `fields`, `authenticated_only`, and `certification_scope`; `output` is local-only.
+
+Use `--certification-scope project|certified|all` consistently with the corresponding list command. The default `project` follows the project switch; `certified` exports only certified assets; `all` exports every accessible asset. This scope never bypasses access permissions.
 
 Output: a successful response must prove `complete=true` and `total` equal to the row count before the CLI atomically publishes a private-mode `.json` array.
 

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

@@ -9,14 +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`.
 
-Output is the gateway envelope. `data` contains the created `report_id`, creation status, normalized `model_type`, AI QP `definition`, and optional resolution warnings.
+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`, 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.
 
@@ -33,3 +45,5 @@ ae-cli analysis report create --project-id <project_id> --report-name "Recent SQ
 After creation, keep the `report_id` returned by this exact create response. If the user also requests report data, call `analysis report-data run` directly with the requested value-only `--sql-params` overrides, or omit that flag to use saved defaults. Do not rebuild internal `sqlViewParams` or guess an ID.
 
 After any successful report create, call `analysis-meta asset url-get` with that returned `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.

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

@@ -25,6 +25,12 @@ ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001
 
 Input also accepts optional `cluster_query_scope` and conditional `slave_cluster_id`. Omit both for current-self data. Resolve allowed physical routes with `analysis query-cluster list`; SQL reports reject `GLOBAL`. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`.
 
+Path exports contain native graph node and link records. `record_type` distinguishes `node` and `link`; `step` is one-based, and `source`/`target` refer to native node IDs. The saved maximum steps and nodes per step still define the graph, including native More aggregation and wastage links. Export includes every computed node and link without the synchronous `preview_rows` cap.
+
+An empty path follows synchronous query semantics: native `PROJECT_NO_DATA` becomes an empty result. Other native failures, including identity and permission failures, still fail the export. JSONL uses `empty` when no data rows were produced, even when a native printer emitted only a header.
+
+Saved-report JSONL records (`schema`, `row`, `empty`, `error`) carry `report_id`; each report has an independent schema. CSV batches use `# report_id=...` boundary comments. Empty reports retain an explicit marker instead of disappearing from a mixed batch.
+
 The downloaded report-data artifact contains report rows and per-report markers, not `actual_cluster_query_scope` metadata. Therefore resolve an allowed route first, keep the submitted scope/ID with the run record, and do not infer route from row contents.
 
 Timezone contract is identical to `report-data run`: omit `--zone-offset` to match the current user's report UI timezone (falling back to the project default); use an enabled integer from `-12` through `14` for a fixed UTC offset; use `--zone-offset 99` for local-time mode, where rows are not converted to one fixed UTC offset. `99` is a mode identifier, not `UTC+99`, and the option is not persisted.

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

@@ -14,7 +14,13 @@ 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.
 
 For saved tag/cluster filters, `data.definition` preserves `field.type` and the persisted `cluster_date_policy`: `AUTO` means dynamic matching by analysis date, `LATEST` means the latest computed result, and `SPECIFIED` requires `specified_cluster_date`. Do not infer dynamic matching from the tag name or `field.type` alone; if a legacy report has no readable policy, state that the saved date semantics are unknown rather than claiming `AUTO`.
 

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

@@ -1,19 +1,19 @@
 # analysis report list
 
-Use when the user needs to find reports they can access in a project, with optional keyword search, semantic model filtering, field projection, and inline pagination.
+Use when the user needs a directory of reports they can edit or manage in a project, with optional keyword search, semantic model filtering, certification filtering, field projection, and inline pagination. The result includes both self-created and shared reports when effective report-edit permission is present; it excludes shared read-only reports.
 
-Do not use for report data execution or report definition writes. Use `report-data run/export` for data and `report create/update` for writes.
+Do not use for readable asset discovery: use `analysis asset search`, which includes shared read-only reports and dashboards. Do not use for report data execution or report definition writes. Use `report-data run/export` for data and `report create/update` for writes.
 
 Command:
 
 ```bash
-ae-cli analysis report list --project-id <project_id> [--queries '["growth","retention"]'] [--model-types '["event","sql","tag","revenue"]'] [--fields '["report_id","report_name","report_desc","report_model","version"]'] [--limit 50] [--offset 0]
+ae-cli analysis report list --project-id <project_id> [--queries '["growth","retention"]'] [--model-types '["event","sql","tag","revenue"]'] [--fields '["report_id","report_name","report_desc","report_model","version"]'] [--certification-scope project|certified|all] [--limit 50] [--offset 0]
 ```
 
-Input sends `project_id`, optional `queries`, `model_types`, `fields`, `limit`, and `offset` as snake_case gateway input. `queries` is a JSON array of 1 to 20 non-empty strings with OR semantics; matching rows include `matched_queries` and `matched_fields`. The legacy singular `query` is not accepted. `limit` defaults to 50 and must be 1..200; out-of-range values are rejected rather than silently clamped.
+Input sends `project_id`, optional `queries`, `model_types`, `fields`, `certification_scope`, `limit`, and `offset` as snake_case gateway input. `queries` is a JSON array of 1 to 20 non-empty strings with OR semantics; matching rows include `matched_queries` and `matched_fields`. The legacy singular `query` is not accepted. `limit` defaults to 50 and must be 1..200; out-of-range values are rejected rather than silently clamped.
 
 Output is the gateway envelope. `data` contains report summaries, `total`, effective `limit`, `offset`, `has_more`, and nullable `next_offset`. When `has_more` is true, use exactly `next_offset` for the next call; stop when it is false. Include `version` in `--fields` when the next step is `analysis report update`.
 
-When locating reports, group known names into one `--queries` call or narrow with `--model-types` before paging. Stop when the required reports are found; do not issue one list call per name.
+When locating manageable reports for an edit or management workflow, group known names into one `--queries` call or narrow with `--model-types` before paging. Stop when the required reports are found; do not issue one list call per name.
 
 Search matches report names and descriptions, not events inside definitions. Inspect a suitable candidate with `report get` when its definition is not already available; use [metadata resolution](metadata_resolution.md) for a business-measure lookup.