@thinkingai/ae-cli 6.1.27 → 6.1.29

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

@@ -16,6 +16,8 @@ Command:
 ae-cli analysis dashboard-report-data export --project-id <project_id> --dashboard-id <dashboard_id> [--report-ids '[1,2]'] [--filters '{...}'] [--cluster-query-scope GLOBAL|SLAVE] [--slave-cluster-id <id>] [--artifact-format jsonl] --output <file>
 ```
 
+Omit `--timeout-seconds` to use the deployment's server default (normally 21600 seconds / 6 hours). The typed CLI accepts explicit `1..21600`; inspect this capability for the server default/max and use `capability run` for larger explicit values only when allowed. Read the run descriptor for the effective deadline; cancel earlier with `analysis query cancel --run-id <run_id>`.
+
 Omit cluster routing to follow the saved dashboard configuration. For an explicit route, use `GLOBAL` or `SLAVE` plus one physical cluster ID returned by `analysis query-cluster list`. SQL reports reject effective `GLOBAL`. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is only the CLI output formatter.
 
 `--filters` uses the same AI-facing filter model as report data. The gateway resolves fields and compiles it to the dashboard backend filter. Do not pass a dashboard UI control dump or raw QP filter. Minimal shape:

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

@@ -2,9 +2,9 @@
 
 Capability id: `analysis.dashboard_report.get`
 
-Use when the user needs the saved presentation of one event report card on an analysis board (`看板`). This L2 command uses typed IDs to distinguish the card from the source report and other boards.
+Use when the user needs the frame size, saved grid position, or event presentation of one report card on an analysis board (`看板`). This L2 command uses typed IDs to distinguish the card from the source report and other boards.
 
-Do not use it to read a report definition or execute data. Use [`report get`](report_get.md) for the source definition, or `dashboard-report-data run/export` for the card's data. Only event report cards are supported by this presentation contract.
+Do not use it to read a report definition or execute data. Use [`report get`](report_get.md) for the source definition, or `dashboard-report-data run/export` for the card's data. Frame geometry applies to saved report cards; chart/table presentation is available only for event cards. Tag and note cards are not `report_id` targets.
 
 ```bash
 ae-cli analysis dashboard-report get --project-id <project_id> --dashboard-id <dashboard_id> --report-id <report_id>
@@ -16,4 +16,8 @@ Output is the gateway envelope. `data` contains `project_id`, `dashboard_id`, `r
 
 For an authorized display change, use [`dashboard-report update`](dashboard_report_update.md). Get is read-only and does not alter the source definition, card, or other dashboards.
 
+The response also includes `reports_version`, the dashboard's layout version, and `frame_size` when readable. Historical small cards can return `small`; updates currently accept only `medium` or `large`. A valid saved layout adds `position: {x,y}` and `layout_size: {w,h}`. Coordinates and dimensions are grid units on a 20-column board, not pixels; x/y are zero-based. Missing geometry means the saved layout is uninitialized or unreadable, not position `(0,0)`. Preserve that uncertainty. Non-event cards omit event `presentation`.
+
+Use the fresh `reports_version` for size or position writes; this is not the source report's `version`. Conflicts require a new read and a deliberate update, not an automatic retry. Read-only permission does not authorize layout edits.
+
 For an effective card trend/combination chart, `presentation.series_scope=report` and `series` describe inherited source-report styles/axes, not card-local configuration. The board's trend button can render a source combo; use returned `chart_type=combo` and the series as evidence. Read [event-report presentation](event_report_presentation.md) before a source-series edit because it affects other trend cards too.

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

@@ -2,15 +2,15 @@
 
 Capability id: `analysis.dashboard_report.update`
 
-Use when the user explicitly requests changing one event report card's presentation on an analysis board (`看板`). Typed display flags are the L2 value: they select the card scope without exposing raw QP/UI fields.
+Use when the user explicitly requests changing one report card's frame size or grid position, or one event card's presentation, on an analysis board (`看板`). Typed display and geometry flags are the L2 value: they select the card scope without exposing raw QP/UI fields.
 
-Do not use for the source report definition, BI dashboards (`仪表盘`), report creation, or adding a report to a board. Only event report cards are supported. Use [`report update`](report_update.md) for source report metadata/definition/chart/result-table layout.
+Do not use for the source report definition, BI dashboards (`仪表盘`), report creation, or adding a report to a board. Frame size/position apply to saved report cards, not tag or note targets; chart/table presentation supports event cards only. Use [`report update`](report_update.md) for source report metadata/definition/chart/result-table layout.
 
 ```bash
 ae-cli analysis dashboard-report update --project-id <project_id> --dashboard-id <dashboard_id> --report-id <report_id> --chart-type table --table-layout event --date-outside false
 ```
 
-Input sends typed `project_id`, `dashboard_id`, `report_id`, and a top-level `presentation` object built from the supplied flags. At least one display flag is required:
+Input sends typed `project_id`, `dashboard_id`, `report_id`, and optional top-level `presentation`, `frame_size`, `position`, and `reports_version`. At least one display or geometry change is required; a version alone is not a change. Only supplied chart/table flags form `presentation`:
 
 - `--chart-type line|combo|bar|stacked|cumulative|pie|table`: the selected card's chart. `table` is supported here, not in source-report presentation. Gateway validates the choice against the saved event definition; pie always needs grouping without time comparison. Total-time cards support bar/table, or pie only when those grouping/comparison conditions hold.
 - `--table-layout date|event|group`: the table layout. Omission preserves the saved layout.
@@ -18,10 +18,29 @@ Input sends typed `project_id`, `dashboard_id`, `report_id`, and a top-level `pr
 
 For a deterministic installed layout, explicitly choose both `--table-layout` and `--date-outside`. Historical inherited fields missing from get must not be treated as `date`/false defaults.
 
+## Frame size and position
+
+Read [`dashboard-report get`](dashboard_report_get.md) first for the current card geometry and `reports_version`, then send the requested patch:
+
+```bash
+ae-cli analysis dashboard-report update --project-id <project_id> --dashboard-id <dashboard_id> --report-id <report_id> --frame-size medium --reports-version <fresh_reports_version>
+ae-cli analysis dashboard-report update --project-id <project_id> --dashboard-id <dashboard_id> --report-id <report_id> --position-x <grid_x> --position-y <grid_y> --reports-version <fresh_reports_version>
+```
+
+- `--frame-size medium|large`: medium is 10x10 grid units; large is 20 columns wide and preserves a valid large-card height. Omit to preserve size. This does not change the chart type.
+- `--position-x` and `--position-y`: supply both as non-negative integers. x is 0..19 and x plus the card width must not exceed 20; y is 0..10000 as a CLI safety bound against excessive page compaction work. These are zero-based grid coordinates, not an ordinal report index or pixels. Medium cards fit x=0..10; large cards require x=0.
+- `--reports-version`: required for any size/position change, including a combined presentation patch. Use the fresh dashboard version, not `--report-version`. Zero is a valid initial version, not a conflict-check bypass.
+
+The gateway preserves all other report, note, and tag entries and unknown layout settings. It rejects occupied destinations rather than silently moving other cards; combine size and position to choose a fitting unoccupied destination. The native page vertically compacts gaps, so the saved coordinates are a grid placement intent, not a promise to keep empty vertical space. Layout changes never add/remove cards or modify the source report.
+
+Position changes require an initialized, valid saved layout containing the target card. If unavailable, save the board layout in the analysis page first; do not invent missing card positions or overwrite the full dashboard definition. A size-only change can update an uninitialized board without inventing its layout. Existing malformed layouts still fail safely. Stale versions and invalid mixed updates cause no partial layout, size, or presentation writes; reread and explicitly choose a new update after a conflict. Legacy presentation-only requests do not require a layout version.
+
+## Event chart and table presentation
+
 `--chart-type combo` selects the trend family only when the source already has combo series; it does not author series. The card inherits source-report metric styles/axes, including when the board's button is labeled trend/line. To get a pure line, reset the source first; a card `--chart-type line` against source combo is rejected rather than misreporting success. Read [event-report presentation](event_report_presentation.md) for source-series edits and their cross-card impact. There is no card `--series` flag or card-local series override.
 
 The report must already belong to the exact dashboard. For a new table card, create the event report, associate it through `report create --dashboard-ids` or [`dashboard-report add`](dashboard_report_add.md), then update with the exact returned report ID. Read existing presentation with [`dashboard-report get`](dashboard_report_get.md) when necessary; do not regenerate its definition for a display-only request.
 
-Only the selected card presentation changes. Omitted presentation fields, its source report definition/chart, and other dashboards remain unchanged. Never send `graphShape`, `reportGraphShape`, `tableFormat`, or `dateOutside` as CLI JSON fields. `--dry-run` previews the same targeted display update when requested; ordinary writes do not require a delete confirmation.
+Only the selected card's requested geometry/presentation changes. Omitted presentation fields, its source report definition/chart, and other dashboards remain unchanged. Never send `graphShape`, `reportGraphShape`, `tableFormat`, or `dateOutside` as CLI JSON fields. `--dry-run` previews the same targeted update when requested; ordinary writes do not require a delete confirmation.
 
-Output is the gateway envelope. `data` contains the selected project/dashboard/report IDs, `model_type`, and `presentation` after the update. Use these returned values as card-display evidence; a successful mutation is not proof that a report data query succeeded.
+Output is the gateway envelope. `data` contains the selected project/dashboard/report IDs, `model_type`, `updated`, readable `frame_size`, and `reports_version`; a valid initialized layout also returns `position` and `layout_size`. Event cards include `presentation` after the update; non-event cards omit it. Use these returned values as card-display evidence; a successful mutation is not proof that a report data query succeeded.

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

@@ -6,7 +6,7 @@ Risk: `write`. Supports `--validate` and `--dry-run`; neither emits a feedback e
 
 ## Trigger
 
-Only after an analysis data query has completed and the Agent has delivered its final business analysis answer, ask once in the user's language whether the analysis met expectations. A successful empty result with an explanation is eligible. Individual tool calls, discovery, metadata inspection, asset governance, asset writes, configuration, help and unrelated questions are not triggers. Query submission, running exports, permission errors and failed queries are not completed analysis results. Do not ask after each CLI call or intermediate analysis step.
+For an existing collected scenario, append verbatim feedback through [scenario collection](scenario_collect.md) instead of duplicating it here. This legacy command remains available for explicit standalone user ratings. Do not routinely ask for a satisfaction rating. Collect feedback only when the user explicitly evaluates a completed analysis data query and final business analysis answer. A successful empty result with an explanation is eligible. Individual tool calls, discovery, metadata inspection, asset governance, asset writes, configuration, help and unrelated questions are not triggers. Query submission, running exports, permission errors and failed queries are not completed analysis results. Do not ask after each CLI call or intermediate analysis step.
 
 No feedback means no submit command, event, case creation or answer upload. Submit only an explicit user evaluation of the completed analysis. A follow-up question, new requirement, silence or a topic change is not a rating. If the target is ambiguous, do not guess. A spontaneous explicit evaluation of a completed analysis can also be submitted without repeating the question.
 

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

@@ -4,7 +4,7 @@ Requires `project_semantic_enable=on` for the target project. If export returns
 
 Use this as the required entry point for CLI Agent asset-authentication and metric-recommendation review.
 
-This command returns one evidence packet seeded from hot shared dashboards and their reports. For normal page-review submission, `--limit 20` is the initial candidate pool; use the bounded expansion procedure below when filtering leaves insufficient candidates. After the command returns, the Agent must transform the returned `work_units` into business-domain review groups before answering. `work_units` are evidence containers, not final answer sections and not an excuse to drop eligible hot dashboards.
+This command returns one evidence packet seeded from eligible shared dashboards and their reports, ordered by available heat and then recent activity. For normal page-review submission, `--limit 20` is the initial candidate pool; use the bounded expansion procedure below when filtering leaves insufficient candidates. After the command returns, the Agent must transform the returned `work_units` into business-domain review groups before answering. `work_units` are evidence containers, not final answer sections and not an excuse to drop eligible dashboards.
 
 Do not use certification-state management commands as a substitute for this recommendation evidence packet.
 Do not load project semantics, project KB, or personal semantic preferences before this command. The recommendation packet is the prerequisite evidence for this review workflow.
@@ -33,38 +33,52 @@ Input sends `project_id`, optional `window_days`, optional `limit`, and optional
 
 Output includes `schema_version`, `run_id`, `project_id`, `snapshot_hash`, `work_units`, `coverage`, `stat_scopes`, and `agent_presentation_contract`.
 
+## Tracked page-recommendation lifecycle
+
+For page-review recommendations, including sidebar, scheduled and external Agent runs, start with `export --project-id <id> --limit 20 --track-run true`. This requires the matching Common service release. A tracked export starts the project run only when the server accepts actual work; filling a prompt never starts it. Legacy exports without this optional flag retain their original behavior.
+
+- Preserve `run_id`. Expansion to top-50/top-100 must pass `--track-run true --run-id <same_run_id>`; do not start another run. The server rejects competing project runs.
+- During Agent interpretation, call `analysis-meta governance-recommendation run-update --project-id <id> --run-id <id> --status HEARTBEAT` at least every five minutes. A fifteen-minute lost lease becomes `TIMED_OUT`; do not resume an expired run.
+- Submit the final packet with `source_run_id` equal to the tracked `run_id`. Successful page submission finishes the run with its exact `batch_id` automatically.
+- An export with `run_status: SUCCEEDED` has no actionable candidates and is already complete; do not heartbeat or submit it. If later Agent filtering leaves no new recommendation, finish with `--status SUCCEEDED` and report the empty result. If interpretation fails, finish with `--status FAILED --reason <short_non_sensitive_reason>`; use `CANCELLED` only once actual execution has stopped. This command records a terminal state; it does not cancel an executing Agent.
+- Terminal states release project occupancy. Never claim success merely because export finished, and never include credentials or raw tool logs in a reason.
+- `RECOMMENDATION_RUNNING` means another run owns this project. Do not bypass it with an untracked export. Query `metadata.governance_recommendation.run_status` through capability discovery if diagnosis is needed.
+
 ## Customer/Agent Material Package Contract
 
-For page-review material preparation or inspection, continue with [independent Agent preflight](agent_review_preflight.md), including when the user requests no submission. Preserve full snapshots, not just the fields shown in a transport example; the preflight checks evidence integrity and interpretation separately.
-Generate [review priorities and classified definition comparisons](agent_review_priorities_comparisons.md) from that evidence. Export ranking and `conflict_risks` are inputs, not replacements for Agent interpretation of individual urgency and both sides of a comparison. A related asset is not automatically a conflicting definition.
+Ordinary recommendations use concise purpose, recommendation basis, core report meaning and known material risks. Page preparation or a local rehearsal uses [focused preflight](agent_review_preflight.md#focused-recommendation-review-default); recommendation-only display does not require a separate full audit. Preserve full source snapshots even when the authored explanation is short. Interpret only selected assets and their necessary grouping/dependency evidence; scripts can account for overflow without an Agent narrative for each unselected candidate.
+
+Read [priorities and definition comparisons](agent_review_priorities_comparisons.md) only for requested ranking, concrete comparison/conflict clues or an explicit full audit. Ordinary items do not need priority grades or comparison-coverage records. Export ranking and `conflict_risks` are inputs; a related asset is not automatically a conflicting definition. Unknown or unexamined conflict scope must never be reported as fully checked.
 
 - This command requires a numeric `--project-id`. If the user provides only a project name, resolve the project on the same host with `ae-cli project info list` before export.
 - `run_id`, `snapshot_hash`, and `review_material_package` are the handoff package for Agent review drafting.
 - `review_material_package` should contain candidate assets, heat evidence, source links, evidence links, dashboard/report/metadata relations, report definitions, AI-model definitions, `target_revision`, and hashes needed to draft a page review.
 - The Agent must generate the downstream `agent-review submit-to-page` draft from this package: batch `ai_summary`, `presentation_snapshot`, per-item `ai_summary` / recommendation reasons, copied `evidence_snapshot`, copied source links, and relations.
-- `work_units` are deterministic Common evidence containers. They are not the final page grouping. The Agent clusters selected assets into one or more business-domain topics and second-level groups for review.
+- `work_units` are deterministic Common evidence containers. They are not the final page grouping. The Agent clusters selected assets into business domains and business subtopics for review. Apply [Business Topics and Subtopics](agent_review_submit_to_page.md#business-topics-and-subtopics) to both levels; a source dashboard is not a default subtopic.
 - For report and SQL-report items, use `review_material_package.candidate_assets[].evidence_snapshot.analysis` first. Call `analysis-meta agent-review evidence` only when the package marks a definition/analysis gap or when validating a generated draft.
 
-## Rejection Filtering and Bounded Expansion
+<a id="rejection-filtering-and-bounded-expansion"></a>
+
+## Current Candidates and Bounded Expansion
 
-Common selects hot dashboards before attaching decision state; it does not automatically replace rejected dashboards with lower-ranked ones. The Agent must apply this procedure before drafting a review:
+Manual recommendation selects assets that currently need certification, by business value and current evidence. Do not query review history to select candidates. Earlier recommendations, pending reviews, rejection or deferral do not exclude an otherwise eligible uncertified asset. Historical fields returned in the packet remain audit context; they do not define manual recommendation eligibility. Automatic certification retains its separate explicit intent and safety rules.
 
-1. Start with `--limit 20`, unless the user explicitly specifies a different scope or a diagnostic sample. Keep the same host, project, time window, and completed-context setting throughout expansion.
-2. Match each source dashboard to its asset candidate by resource identity. If its current `action_state` is `PREVIOUSLY_REJECTED`, omit the dashboard and its entire display branch: its groups, report/metadata/metric placements, and relations. Do not display that rejected dashboard as completed context or submit it again. A historical `REJECT` alone is not enough to exclude a changed definition; use Common's current same-evidence decision state. Do not treat every `actionable=false` asset as rejected: authenticated context remains useful.
-3. Rebuild the presentation from retained dashboard branches. Keep a shared report, metadata asset, or metric candidate when independently referenced by another retained dashboard, and show it only under retained branches. Deduplicate by scoped asset identity, not name. Remove orphan items, empty groups/topics, and relations to omitted items from `presentation_snapshot`; omit items supported only by removed branches from the submission. This is presentation filtering, not a cascading rejection or a certification-state change. Preserve copied source evidence unchanged.
-4. Separate pending review work from context before judging the batch. Pending review work is a returned item that still needs a reviewer decision, for example `action_state:"PENDING"` or unauthenticated `authentication_status:0`, after excluding same-evidence rejects, active deferrals, and items already in an unfinished review batch when that state is available. `AUTHENTICATED` / completed assets are context only unless the evidence shows a material definition change that requires a new decision.
-5. Assess whether the remaining pending review assets and visible business domains meet the user's requested breadth and have sufficient evidence for a useful review. If no count was requested, treat the pool as insufficient when there are fewer than about 10 pending review assets, fewer than 3 pending business domains, or the retained material is mostly authenticated context with little work for the reviewer. If insufficient and coverage indicates more dashboards exist, re-export with `--limit 50`; repeat filtering and assessment, then use `--limit 100` if still insufficient. These limits are cumulative top-N pools, not disjoint pages. Replace the previous drafting packet with the latest successful export; do not concatenate runs or mix their `run_id`, `snapshot_hash`, revisions, or evidence hashes.
-6. Apply the daily review capacity after expansion. Expansion increases business-domain coverage; it does not authorize submitting every pending asset found. Unless the user requests a different batch size, target about 20-50 pending review assets, use a hard cap around 80, and keep roughly 3-6 visible business domains. When the expanded pool is larger than the cap, rank pending assets by impact_degree, heat_count90d, user_count90d, dependency/relation breadth, and whether their business domain is under-covered. Use per-domain quotas before taking many assets from one domain.
-7. Stop when the pending review assets and business-domain breadth are sufficient, the available dashboard pool is exhausted, or the top 100 have been inspected. Do not automatically expand beyond 100. At the cap, submit only the ranked slice of genuinely eligible, evidence-supported candidates within the user's submission authorization; never revive rejected, deferred, already in-flight, or weak candidates to fill a quota. Record overflow counts and domains for later batches. If none remain, explain the result without submitting an empty batch. A failed export is an execution failure, not evidence of candidate scarcity; do not expand in response to an error or silently fall back to stale material.
-8. Build page topics only for business domains that contain at least one selected pending review asset. Retain authenticated/completed assets only as direct context needed by those selected pending items, for example source dashboards, source reports, and referenced metadata along the relation path. Do not display or submit a zero-pending business domain as standalone work, even if it has many hot authenticated assets.
+1. Start with `--limit 20`, unless the user explicitly requests another scope. Keep the same host, project, time window and completed-context setting throughout expansion.
+2. Treat current `authentication_status:0` assets as pending review work. Use current certification facts in the asset or `evidence_snapshot.asset`; do not use historical `action_state`, `actionable`, or `previous_decision` as a substitute for current certification. Unknown certification or missing definition evidence is an evidence gap, not proof of eligibility. Authenticated assets are context only.
+3. Deduplicate shared assets by full scoped identity within this packet and preserve source evidence, links and known relations. Do not remove dashboard branches because they appeared in an earlier recommendation.
+4. Assess current candidates and business breadth. If there are fewer than about 10 pending review assets or fewer than 3 pending business domains and more dashboards exist, re-export with `--limit 50`, then use `--limit 100` if still insufficient. The pools are cumulative, not pages. Replace the earlier drafting packet with the latest successful export; never mix run IDs, hashes, revisions or snapshots.
+5. Apply the daily review capacity after expansion: target about 20-50 pending review assets, hard cap around 80, across roughly 3-6 visible business domains. Rank by impact_degree, heat_count90d, user_count90d and dependency breadth. Use per-domain quotas before adding many assets from one domain.
+6. Stop when candidates and domain coverage are sufficient, the pool is exhausted, or the top 100 have been inspected. Record overflow counts and domains for later batches. Do not fill a quota with weak or unsupported candidates. An export failure is an execution failure, not evidence of scarcity; do not expand because of an error or use stale material.
+7. Build visible domains only when they contain selected pending work. Retain authenticated assets only as direct supporting context. Do not display or submit a zero-pending business domain as standalone work.
+8. Submit the current material once when authorized. A new recommendation may include previously recommended assets. Reuse the same client request key and exact payload only when replaying the same submission after a network failure; a deliberate new submission uses a new key. Read back the returned batch rather than searching old batches to change the candidate set.
 
-Report the final requested limit, actual dashboards returned, same-definition rejected dashboards excluded, active deferrals or in-flight items excluded when known, retained dashboard count, visible pending-domain count, selected pending review asset count, context asset count, overflow pending count/domain summary, and stopping reason. Explain why expansion was needed or why candidates remain insufficient. Do not describe an expanded or filtered batch as covering all of the top 20/50/100 dashboards. Keep this scope summary separate from the hidden rejected branches, zero-pending context domains, and overflow left for later batches.
+Report the final requested limit, actual dashboards returned, dashboards represented in the selected packet, visible pending-domain count, selected pending asset count, context count, overflow summary and stopping reason. Do not describe a selected slice as covering all top-N dashboards. Historical recommendation counts are not part of eligibility or the required scope report.
 
 ## Decision Rules
 
 - Use this command before presenting recommendations for certification or metrics.
 - After export, always build the business-domain review display before answering. The command output is evidence, not the response format.
-- For real review-page submission, apply Rejection Filtering and Bounded Expansion before grouping. Include eligible assets across the retained dashboard branches; do not compress them into a few representative themes or submit only the first hot dashboard or first `work_unit`. A smaller batch is valid when the evidence supports fewer eligible candidates or the user explicitly requests a sample or diagnostic batch. Explain the actual scope and omissions.
+- For real review-page submission, apply Current Candidates and Bounded Expansion before grouping. Include eligible assets across the retained dashboard branches; do not compress them into a few representative themes or submit only the first hot dashboard or first `work_unit`. A smaller batch is valid when the evidence supports fewer eligible candidates or the user explicitly requests a sample or diagnostic batch. Explain the actual scope and omissions.
 - For recurring recommendation jobs, the default reviewer workspace is pending-first: only business domains with pending review assets are visible. Authenticated/completed assets remain available as relation/context rows under those domains, but they must not create a visible topic by themselves.
 - Treat `业务主题域` as a semantic cluster over the selected dashboards, not a copy of the dashboard list. Do not create one topic per hot dashboard just because `--limit 20` returned 20 work units. Merge dashboards into the same topic when their child reports, referenced metadata, metrics, folder context, or authored notes describe the same business process. Split only when the business meaning or review decision is materially different. A result where `topic_count == selected_dashboard_count` requires explicit evidence that every selected dashboard has a distinct business domain.
 - Do not call project-semantic, project-KB, or personal-semantic-preference commands as prerequisite context for this workflow.
@@ -76,13 +90,21 @@ Report the final requested limit, actual dashboards returned, same-definition re
 - Keep completed/authenticated context included by default so certified and uncertified assets from the returned evidence appear together under the same business domain. Pass `--include-completed false` only when the user explicitly asks for a pending-only review.
 - If this capability is missing on the target host, report the deployment/catalog gap. Do not synthesize a recommendation from ordinary asset-authentication or metric list commands.
 
+## Incomplete Usage and Lineage
+
+The export may fall back from the requested materialized usage window to Poseidon heat (only for a 90-day request), then to recent activity/update ordering when neither statistic is available. Read `coverage.usage_window_state`, `selection_mode`, and each asset's `heat_source`. Missing statistics and lineage are evidence gaps, not proof of an empty project or a permission failure. Never replace null/unknown users, heat or impact with a factual zero; do not add counts from different sources or claim a Poseidon window anchor that is not exposed. Zero is an observed value and must not be overwritten with older heat. Report the actual returned coverage scope rather than describing all fallback candidates as hot assets. These candidates are for evidence-based manual review, not relaxed automatic certification.
+
+The export marker covers the active request only and is released after success (including empty results) or failure. Do not assume it reserves a project throughout Agent drafting; page submission uses its own idempotency and revision checks.
+
+Each newly authored topic includes optional transport field `semantic_basis: {business_question, grouping_reason, evidence_item_ids}`. Write these explanations from report/event/property/metric definitions and reference items displayed in that topic. The independent preflight must review all topic bases and grouping decisions; CLI/Common only validate nonempty structure and scoped references. Legacy packets without this field remain readable/submittable. Never generate topic business meaning by script templates.
+
 ## Agent Approval Display
 
 This is an Agent presentation contract, not a CLI flag and not a Common renderer. Use the basic fields returned by Common to produce exactly one review shape:
 
 - The top-level grouping must be `业务主题域`. Do not split the final answer into separate top-level sections such as `资产认证建议` and `推荐指标`.
-- Aggregate by `业务主题域` with each source dashboard as the core evidence package for coverage, not as the business-domain name. Infer each domain from the dashboard semantics plus the business meaning of `topic_seed`, `source_reports`, asset names, metric names, and semantic definitions. The final group name should describe the business area or process, such as payment/revenue, login/channel, retention, item economy, or lifecycle, not the backend work-unit label. This grouping is for review comprehension only; it must not reduce the retained dashboard set after rejection filtering and bounded expansion.
-- The expected page hierarchy is `业务域 -> 看板 -> 报表 -> 元数据`. Put multiple source dashboards under one topic when they belong to the same business domain. The topic is not the dashboard node; the dashboard remains a root asset row inside the topic.
+- Aggregate by `业务主题域` with each source dashboard as the core evidence package for coverage, not as the business-domain name. Infer each domain from the dashboard semantics plus the business meaning of `topic_seed`, `source_reports`, asset names, metric names, and semantic definitions. The final group name should describe the business area or process, such as payment/revenue, login/channel, retention, item economy, or lifecycle, not the backend work-unit label. This grouping is for review comprehension only; it must not reduce the retained dashboard set after current-state selection and bounded expansion.
+- The expected page hierarchy is `业务域 -> 业务小主题 -> 看板 -> 报表 -> 元数据`. Put source dashboards answering the same specific business question under one subtopic within their broader domain. Neither grouping level is the dashboard node; the dashboard remains an asset row inside a subtopic. Review one-group-per-dashboard layouts for missed business merges rather than accepting renamed dashboard containers.
 - Treat `work_units` as evidence containers, not presentation groups. One dashboard/work unit can split into multiple business domains when its child reports cover different business processes; one business domain can merge rows from multiple dashboards/work units when the evidence describes the same business process.
 - Keep each report-centered evidence chain together: the report row, metadata rows, and metric candidates introduced by that report follow the same `业务主题域`. Do not detach report metadata into a separate generic metadata group, and do not merge unrelated child-report domains only because they share one source dashboard.
 - When one source dashboard contains child reports for different business questions, create one `业务主题域` per child-report business question. Do not combine distinct report domains into a broad `A 与 B 运营`, `综合运营`, or `核心语义` group only because they share the same dashboard. The dashboard can appear as shared linked source evidence in each relevant domain.

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

@@ -0,0 +1,13 @@
+# analysis-meta governance-recommendation run-update
+
+Renew or finish the tracked recommendation started by [export](governance_recommendation_export.md#tracked-page-recommendation-lifecycle).
+
+```bash
+ae-cli analysis-meta governance-recommendation run-update --project-id <project_id> --run-id <run_id> --status HEARTBEAT
+```
+
+Capability: `metadata.governance_recommendation.run_update`. Input required flags: `--project-id`, `--run-id`, `--status`. Optional: `--reason` with a short non-sensitive reason.
+
+Use HEARTBEAT at least every five minutes during actual interpretation. SUCCEEDED without page submission means an empty successful result. Page submission automatically records the exact batch ID. FAILED and CANCELLED release occupancy; record CANCELLED only after execution has stopped. Updating state does not cancel Agent execution. The server requires the same project, actor and active run ID; a fifteen-minute lost lease ends as TIMED_OUT and cannot be revived.
+
+Do not use this command to start recommendations or bypass another run. Output returns the current project status, exact run ID and successful batch ID when present; terminal states release occupancy.

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

@@ -23,5 +23,5 @@ Parameters:
 | `--project-id` | Numeric project ID. | Yes |
 | `--data-type` | Live data type: normal (default) or error. | No |
 | `--request-id` | Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted. | No |
-| `--timeout-seconds` | Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>. | No |
+| `--timeout-seconds` | Async runtime in seconds. Omit to use the server default (normally 21600 / 6 hours). Explicit CLI values remain in 1..21600. Inspect the capability for its server default/max; use capability run for larger values only when allowed. Cancel with analysis query cancel --run-id <run_id>. | No |
 | `--output` | Wait and download to this local file. | No |

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

@@ -35,3 +35,32 @@ Output `data.metric` contains the created metric summary.
 - Use public snake_case fields such as `time_range` and `dependencies[].event`; do not send backend-only camelCase fields such as `eventName` in the semantic definition.
 - For event metrics, `--metric-params` is usually a format config such as `{"format":"integer"}`.
 - For retention metrics, `--metric-params` should be the retention `eventView` configuration.
+
+## Saved metric filters
+
+For a semantic event metric, root `filters` and the sole metric's own `filters` are combined with AND. Preserve each scope's `relation` and compound grouping: a root OR group must not become AND between its children, and a metric-level condition must not disappear. For example, this definition means `(country = US OR country = GB) AND elapsed_ms <= 3000`:
+
+```json
+{
+  "time_range": {"mode":"previous","unit":"day","value":7},
+  "metrics": [{
+    "event":"reply",
+    "aggregation":"total_count",
+    "relation":"and",
+    "filters":[
+      {"field":{"type":"event_property","name":"elapsed_ms"},"operator":"lte","values":[3000]}
+    ]
+  }],
+  "relation":"or",
+  "filters":[
+    {"field":{"type":"user_property","name":"country"},"operator":"eq","values":["US"]},
+    {"field":{"type":"user_property","name":"country"},"operator":"eq","values":["GB"]}
+  ]
+}
+```
+
+Use the definition as the single item in `--metric-events`, replacing the example event and properties with verified metadata. Do not put semantic event filter conditions in `metric_params`: non-empty `filts` or misplaced `filters` there are rejected for semantic event creation instead of being silently ignored; null or empty arrays remain compatible. Keep formatting, such as `{"format":"integer"}`, in `--metric-params`. Existing native QP input remains a compatibility path; preserve its own representation rather than mixing it with a semantic definition.
+
+A saved metric is a reusable calculation, not a saved report. The example's `time_range` supplies compilation context; report grouping, comparison periods, and calendar settings are not a promise of persisted query context for that metric. Choose the actual query period when using the metric.
+
+After creation, use `analysis-meta metric get` to verify the saved filters before reusing the metric in a formula. An older backend can accept creation yet discard root filters; a successful response alone does not prove the calculation scope was saved. If readback loses a condition, stop the dependent query and report the backend deployment prerequisite instead of claiming that the filtered result is correct.

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

@@ -17,6 +17,8 @@ Input sends `project_id`, `metric_id`.
 
 Output `data.metric` contains the saved metric definition, or no metric when the ID does not resolve.
 
+After creating or changing a filtered metric, verify the saved event filters and their relations in this returned native definition before formula reuse. Both semantic root conditions and metric-local conditions must still be represented. Do not interpret a successful create/update response or a formula's successful execution as proof that its filters were saved. If an older backend dropped conditions, stop the dependent query and report the scope mismatch; the CLI must not silently treat the metric as unfiltered.
+
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|

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

@@ -37,4 +37,6 @@ Output `data.metric` contains the updated summary for a full-definition update c
 - For full-definition updates, pass `--metric-name`, `--metric-desc`, one of `--model-type` / `--metric-mode`, and `--metric-events` together.
 - If both `--model-type` and `--metric-mode` are present, they must match: `event -> 0`, `retention -> 1`.
 - Use `analysis-meta metric get` before updating if the current definition needs to be preserved and edited.
+- For a full-definition event update, use the native QP returned by `metric get`; semantic event-analysis definitions are not supported by `metric update`. Preserve the native filters, formula metadata, and metric params unless the user requests a calculation change. The semantic create example in [`metric_create.md`](metric_create.md) is not an update payload.
+- For a display-name/remark-only edit, omit `--metric-events` and `--metric-params` so the existing filtered calculation stays unchanged. After a definition change, read back the saved metric and verify its conditions before using it in a formula.
 - This is an ordinary write operation; execute it without the high-risk confirmation flag.

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

@@ -29,6 +29,6 @@ This capability starts an asynchronous artifact export. Use `--wait --output <pa
 
 - `--artifact-format xlsx` selects the logical data format. Follow the returned descriptor for compression and content type.
 - `--request-id cli_<32 lowercase hex>` assigns a stable request identifier.
-- `--timeout-seconds` accepts 1–7200 (server default: 3600).
+- Omit `--timeout-seconds` to use the server-provided default. This typed CLI accepts explicit values in `1..7200`; inspect this capability for the deployment default/max. Use `capability run` with a larger explicit `timeout_seconds` only when its schema permits it.
 - `--wait-timeout-seconds` controls how long this CLI invocation waits; it does not change the server runtime limit.
 - Explicit flags override corresponding `--payload` fields; omitted options preserve payload values.

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

@@ -23,5 +23,5 @@ Parameters:
 | `--project-id` | Numeric project ID. | Yes |
 | `--log-id` | Tracking plan change log ID. | Yes |
 | `--request-id` | Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted. | No |
-| `--timeout-seconds` | Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>. | No |
+| `--timeout-seconds` | Async runtime in seconds. Omit to use the server default (normally 21600 / 6 hours). Explicit CLI values remain in 1..21600. Inspect the capability for its server default/max; use capability run for larger values only when allowed. Cancel with analysis query cancel --run-id <run_id>. | No |
 | `--output` | Wait and download to this local file. | No |

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

@@ -22,5 +22,5 @@ Parameters:
 | --- | --- | --- |
 | `--project-id` | Numeric project ID. | Yes |
 | `--request-id` | Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted. | No |
-| `--timeout-seconds` | Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>. | No |
+| `--timeout-seconds` | Async runtime in seconds. Omit to use the server default (normally 21600 / 6 hours). Explicit CLI values remain in 1..21600. Inspect the capability for its server default/max; use capability run for larger values only when allowed. Cancel with analysis query cancel --run-id <run_id>. | No |
 | `--output` | Wait and download to this local file. | No |

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

@@ -20,3 +20,7 @@ Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
+
+## Scenario sample collection policy
+
+`data.analysis_scenario_collection_enabled` is a live boolean from the source project's own configuration. It is true only for explicit `agent_analysis_scenario_collection_enabled=on`. Missing, invalid, or unreadable configuration defaults to false; company configuration is not inherited. This field does not change ordinary invocation/intent telemetry. Older servers may omit it; treat omission as disabled. Re-read for each scenario or append rather than keeping a previous grant.

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

@@ -0,0 +1,35 @@
+# project member-group add-members
+
+Use when the user explicitly requests adding existing project members to an existing project member group.
+
+Do not use this command to invite someone into the project or company, change roles, create/delete a group, rename it, or change its default-join setting. AgentSpace/system membership and analysis user-cluster/user-tag audiences use their own command families.
+
+1. Resolve the target group with `project member-group list` and read its members with `project member-group members`, following pagination as needed. Resolve numeric `user_id` values from `project member list`; do not substitute login names or open IDs.
+2. Preview the exact change:
+
+   ```bash
+   ae-cli project member-group add-members --project-id 1 --group-id 20 --user-ids '[101,102]' --dry-run
+   ```
+
+3. Summarize the project, group, and requested member changes. After explicit user confirmation, execute the unchanged request with global `--yes`:
+
+   ```bash
+   ae-cli project member-group add-members --project-id 1 --group-id 20 --user-ids '[101,102]' --yes
+   ```
+
+Capability ID: `project.member_group.add_members`. Risk: `high-risk-write`. Requires the project's `MAINTAIN_PROJECT_USER` permission. Non-interactive execution requires `--yes`; dry-run does not modify membership.
+
+## Parameters
+
+| Flag | Required | Meaning |
+|---|---|---|
+| `--project-id` | Yes | Integer project ID from 1 to 2147483647. |
+| `--group-id` | Yes | Integer ID from 1 to 2147483647 of an existing group in this project. |
+| `--user-ids` | Yes | JSON array containing 1 to 1000 integer user IDs from 1 to 2147483647, for example `[101,102]`. Strings, non-integers, zero, and negative IDs are rejected. |
+| `--yes` | Execution | Global confirmation flag after explicit authorization. |
+
+The gateway input uses `project_id`, `group_id`, `user_ids`, and `yes: true`. Every requested user must already belong to the project. The server applies the requested membership delta atomically, preserving the group name, default-join setting, and other group members. Do not send a replacement member list or call the page's full-group save interface.
+
+## Output
+
+The gateway success envelope returns `group_id`, `requested_user_ids`, `changed_user_ids`, and the resulting `member_count` in `data`. Use `changed_user_ids` to report the actual change rather than assuming every requested ID changed. Read back with `project member-group members` when the user needs the resulting membership. Preserve any `request_id` and `invocation_id` in metadata; report gateway permission or membership-validation failures without claiming success.

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

@@ -0,0 +1,25 @@
+# project member-group create
+
+Use when the user needs a new project member group under Project management → Member management → Member groups.
+
+Do not use this command to create a company/project member, an AgentSpace group, an audience cluster, or a user tag. It creates an empty group with `is_default=false`; it does not enroll project members or change another group's settings. Add existing project members afterward with `project member-group add-members`.
+
+```bash
+ae-cli project member-group create --project-id 1 --group-name 'Customer Success' --dry-run
+ae-cli project member-group create --project-id 1 --group-name 'Customer Success'
+```
+
+Capability ID: `project.member_group.create`. Risk: `write`. Requires the project's `MAINTAIN_PROJECT_USER` permission.
+
+## Parameters
+
+| Flag | Required | Meaning |
+|---|---|---|
+| `--project-id` | Yes | Integer project ID from 1 to 2147483647. |
+| `--group-name` | Yes | Non-blank group name of 1 to 80 characters. |
+
+The gateway input uses `project_id` and `group_name`. No default-join flag is exposed.
+
+## Output
+
+The gateway success envelope returns the new `group_id` and `group_name` in `data`. Use that ID for membership changes; read the resulting group with `project member-group list`. Preserve any `request_id` and `invocation_id` in metadata. Report name-validation or permission failures without claiming the group was created.

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

@@ -0,0 +1,34 @@
+# project member-group delete
+
+Use when the user explicitly requests deleting an existing project member group.
+
+Do not use this command to remove users from a project/company or merely remove selected group members; use `project member-group remove-members` for the latter. Deleting the group leaves the users' project/company memberships intact. Group-based sharing can be affected, so identify the group and explain the impact before executing.
+
+1. Resolve the exact group ID with `project member-group list`; inspect current members with `project member-group members` if needed.
+2. Preview:
+
+   ```bash
+   ae-cli project member-group delete --project-id 1 --group-id 20 --dry-run
+   ```
+
+3. After explicit user confirmation, execute the unchanged request:
+
+   ```bash
+   ae-cli project member-group delete --project-id 1 --group-id 20 --yes
+   ```
+
+Capability ID: `project.member_group.delete`. Risk: `high-risk-write`. Requires the project's `MAINTAIN_PROJECT_USER` permission. Non-interactive execution requires global `--yes`.
+
+## Parameters
+
+| Flag | Required | Meaning |
+|---|---|---|
+| `--project-id` | Yes | Integer project ID from 1 to 2147483647. |
+| `--group-id` | Yes | Integer ID from 1 to 2147483647 of an existing group in this project. |
+| `--yes` | Execution | Global confirmation flag after explicit authorization. |
+
+The gateway input uses `project_id`, `group_id`, and `yes: true`. Dry-run validates and previews without deleting the group.
+
+## Output
+
+Interpret the gateway result as group deletion only, never removal of its users from the project/company. Verify the group is absent with `project member-group list` when readback is needed. Preserve any `request_id` and `invocation_id` in metadata, and report permission or resource-validation failures without claiming deletion.

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

@@ -0,0 +1,29 @@
+# project member-group list
+
+Use when the user needs to find existing member groups in a project under Project management → Member management → Member groups.
+
+Do not use this command for AgentSpace/system membership or analysis user-cluster/user-tag audiences. Project member-group membership is separate from project membership; use `project member list` to discover project members. Use `project member-group members` to inspect a group’s members; the group list returns counts, not nested member lists.
+
+```bash
+ae-cli project member-group list --project-id 1 --limit 100 --offset 0
+```
+
+Capability ID: `project.member_group.list`. Risk: `read`. Requires the project's `VIEW_PROJECT_MEMBER` permission.
+
+For group lifecycle changes, read [create](project_member_group_create.md), [rename](project_member_group_rename.md), or [delete](project_member_group_delete.md). Membership changes use [add-members](project_member_group_add_members.md) and [remove-members](project_member_group_remove_members.md).
+
+## Parameters
+
+| Flag | Required | Meaning |
+|---|---|---|
+| `--project-id` | Yes | Integer project ID from 1 to 2147483647. |
+| `--limit` | No | Integer page size from 1 to 1000; default 100. |
+| `--offset` | No | Integer row offset from 0 to 2147483647; default 0. |
+
+The gateway input uses `project_id`, `limit`, and `offset`.
+
+## Output and pagination
+
+The gateway success envelope contains `data.items`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. Each group item has `group_id`, `group_name`, `is_default`, and `member_count`.
+
+When `has_more` is true, repeat with the returned `next_offset`. Continue until `has_more` is false before claiming a complete list; a page can contain at most 1000 rows. Preserve any `request_id` and `invocation_id` in the gateway metadata. A permission error does not mean the project or group is empty.

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

@@ -0,0 +1,28 @@
+# project member-group members
+
+Use when the user needs to inspect the members of an existing project member group under Project management → Member management → Member groups.
+
+Do not use this command for AgentSpace/system membership or analysis user-cluster/user-tag audiences. Project member-group membership is separate from project membership; use `project member list` to discover project members. Use `project member-group list` to resolve the group ID first.
+
+```bash
+ae-cli project member-group members --project-id 1 --group-id 20 --limit 100 --offset 0
+```
+
+Capability ID: `project.member_group.members`. Risk: `read`. Requires the project's `VIEW_PROJECT_MEMBER` permission.
+
+## Parameters
+
+| Flag | Required | Meaning |
+|---|---|---|
+| `--project-id` | Yes | Integer project ID from 1 to 2147483647. |
+| `--group-id` | Yes | Integer ID from 1 to 2147483647 returned by `project member-group list` for this project. |
+| `--limit` | No | Integer page size from 1 to 1000; default 100. |
+| `--offset` | No | Integer row offset from 0 to 2147483647; default 0. |
+
+The gateway input uses `project_id`, `group_id`, `limit`, and `offset`.
+
+## Output and pagination
+
+The gateway success envelope contains `data.items`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. The result also identifies `group_id`; each member item has `user_id`, `login_name`, and `user_name`.
+
+When `has_more` is true, repeat with the returned `next_offset`. Continue until `has_more` is false before claiming a complete list; a page can contain at most 1000 rows. Preserve any `request_id` and `invocation_id` in the gateway metadata. A permission error does not mean the project or group is empty.

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

@@ -0,0 +1,35 @@
+# project member-group remove-members
+
+Use when the user explicitly requests removing members from an existing project member group.
+
+Do not use this command to remove a user from the project or company, change roles, create/delete a group, rename it, or change its default-join setting. AgentSpace/system membership and analysis user-cluster/user-tag audiences use their own command families.
+
+1. Resolve the target group with `project member-group list` and read its members with `project member-group members`, following pagination as needed. Use returned numeric `user_id` values, including retained inactive or former project members; do not substitute login names or open IDs.
+2. Preview the exact change:
+
+   ```bash
+   ae-cli project member-group remove-members --project-id 1 --group-id 20 --user-ids '[101,102]' --dry-run
+   ```
+
+3. Summarize the project, group, and requested member changes. After explicit user confirmation, execute the unchanged request with global `--yes`:
+
+   ```bash
+   ae-cli project member-group remove-members --project-id 1 --group-id 20 --user-ids '[101,102]' --yes
+   ```
+
+Capability ID: `project.member_group.remove_members`. Risk: `high-risk-write`. Requires the project's `MAINTAIN_PROJECT_USER` permission. Non-interactive execution requires `--yes`; dry-run does not modify membership.
+
+## Parameters
+
+| Flag | Required | Meaning |
+|---|---|---|
+| `--project-id` | Yes | Integer project ID from 1 to 2147483647. |
+| `--group-id` | Yes | Integer ID from 1 to 2147483647 of an existing group in this project. |
+| `--user-ids` | Yes | JSON array containing 1 to 1000 integer user IDs from 1 to 2147483647, for example `[101,102]`. Strings, non-integers, zero, and negative IDs are rejected. |
+| `--yes` | Execution | Global confirmation flag after explicit authorization. |
+
+The gateway input uses `project_id`, `group_id`, `user_ids`, and `yes: true`. The server applies the requested membership delta atomically, preserving the group name, default-join setting, and other group members. An existing group membership can be removed even after that user becomes inactive or leaves the project. A current project member already absent from the group is an idempotent no-op; an ID belonging to neither this project nor this group is rejected. Do not send a replacement member list or call the page's full-group save interface.
+
+## Output
+
+The gateway success envelope returns `group_id`, `requested_user_ids`, `changed_user_ids`, and the resulting `member_count` in `data`. Use `changed_user_ids` to report the actual change rather than assuming every requested ID changed. Read back with `project member-group members` when the user needs the resulting membership. Preserve any `request_id` and `invocation_id` in metadata; report gateway permission or membership-validation failures without claiming success.

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

@@ -0,0 +1,26 @@
+# project member-group rename
+
+Use when the user needs to rename an existing project member group.
+
+Do not use this command to replace group members, change roles, or change the default-join setting. The rename preserves all existing group memberships and the group's default-join setting. Resolve the exact group ID with `project member-group list` before modifying it.
+
+```bash
+ae-cli project member-group rename --project-id 1 --group-id 20 --group-name 'Customer Success' --dry-run
+ae-cli project member-group rename --project-id 1 --group-id 20 --group-name 'Customer Success'
+```
+
+Capability ID: `project.member_group.rename`. Risk: `write`. Requires the project's `MAINTAIN_PROJECT_USER` permission.
+
+## Parameters
+
+| Flag | Required | Meaning |
+|---|---|---|
+| `--project-id` | Yes | Integer project ID from 1 to 2147483647. |
+| `--group-id` | Yes | Integer ID from 1 to 2147483647 of an existing group in this project. |
+| `--group-name` | Yes | Non-blank group name of 1 to 80 characters. |
+
+The gateway input uses `project_id`, `group_id`, and `group_name`. Send only the new name; do not copy and resubmit a page-level group member list.
+
+## Output
+
+The gateway success envelope returns `group_id` and the resulting `group_name` in `data`. Read back with `project member-group list` to verify the name. If the user needs membership evidence, use `project member-group members` and follow its pagination. Preserve any `request_id` and `invocation_id` in metadata; a permission failure is not a successful rename.