@thinkingai/ae-cli 6.1.17 → 6.1.19

package/skills/ae-kb/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-kb
 version: 1.0.0
-description: "AE/TE knowledge base CLI manual for creating, querying, LLM-powered ask, listing accessible knowledge bases, deterministic index/grep/read retrieval, checking status, uploading, compiling, schema generation, URL sources, source deletion, and knowledge base deletion. Use when the user asks to manage TE/AE/ThinkingEngine knowledge bases, upload documents or URLs to a knowledge base, query knowledge, ask knowledge bases with an LLM, list accessible knowledge bases, inspect knowledge base indexes, search knowledge base pages, read a specific knowledge base page, check knowledge base status, generate schemas, compile knowledge, remove sources, or delete a knowledge base. To choose which knowledge base is worth searching, use the ae-kb-discovery skill first; this skill runs the retrieval once a target is chosen. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source display names, JSON payload shapes, or URL formats."
+description: 'AE/TE knowledge base CLI manual for creating, importing read-only compiled snapshots, querying, LLM-powered ask, listing accessible knowledge bases and their sources, deterministic index/grep/read retrieval, checking status, uploading, compiling, schema generation, URL sources, source deletion, and knowledge base deletion. Use when the user asks to manage TE/AE/ThinkingEngine knowledge bases, import a compiled Markdown ZIP snapshot, upload documents or URLs to a knowledge base, query knowledge, ask knowledge bases with an LLM, list accessible knowledge bases or source metadata, inspect knowledge base indexes, search knowledge base pages, read a specific knowledge base page, check knowledge base status, generate schemas, compile knowledge, remove sources, or delete a knowledge base. To choose which knowledge base is worth searching, use the ae-kb-discovery skill first; this skill runs the retrieval once a target is chosen. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source IDs, source display names, JSON payload shapes, or URL formats.'
 ---
 
 # ae-kb
@@ -14,11 +14,11 @@ ae-cli kb +<command> [options]
 
 ## Global Rules
 
-- Use this skill for TE/AE knowledge base tasks: create, query, ask with LLM, list accessible knowledge bases, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
+- Use this skill for TE/AE knowledge base tasks: create, import a compiled snapshot, query, ask with LLM, list accessible knowledge bases and their sources, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
 - **Searching a knowledge base for an answer is the most common task. If that is what you are doing, go straight to [Explore Knowledge Base Pages](#explore-knowledge-base-pages) and read [`references/query-workflow.md`](references/query-workflow.md) first — it is the retrieval procedure. The other commands below are for managing knowledge bases, not answering from them.**
 - Read operations can run directly after required inputs are known. Write operations require explicit user intent and normally keep the confirmation prompt unless the user asks to bypass it.
 - Prefer `--dry-run` before destructive or broad writes when the user has not already validated the target.
-- Do not invent knowledge base names, scopes, source display names, or JSON payloads. Ask the user or query known context when values are missing.
+- Do not invent knowledge base names, scopes, source IDs, source display names, or JSON payloads. Ask the user or query known context when values are missing.
 - When building a `--sources` ref (or `+read --source`), copy the exact `scope` and `name` from `+list` output — run `ae-cli kb +list` first when the scope of a named knowledge base is unknown.
 - JSON flags must be valid JSON strings, usually wrapped in single quotes in shell commands.
 - Successful commands return JSON by default. Use `--format table` only when a table is easier for a human to scan. Envelope may include optional `_notice.host_compat`.
@@ -33,16 +33,19 @@ ae-cli kb +<command> [options]
 | `+ask` | read | LLM-powered Q&A over knowledge bases; for multi-page synthesis or multi-hop questions. |
 | `+ask-status` | read | Query the current status of an ask execution by `--execution-id` without polling. |
 | `+list` | read | List accessible knowledge bases filtered by buildStatus (default: compiled). |
+| `+list-sources` | read | List source metadata for one knowledge base so exact source identifiers can be discovered safely. |
 | `+index` | read | List accessible knowledge bases and their `index.md` navigation maps. |
 | `+grep` | read | Keyword-search knowledge base pages and return matched lines with context. |
 | `+read` | read | Read a full knowledge base page, a line window, or (with `--outline`) only the page heading tree. |
 | `+new` | write | Create a new personal or company knowledge base. |
+| `+import` | write | Import a compiled Markdown ZIP as a personal read-only snapshot. |
+| `+import-status` | read | Query one snapshot import task by `--request-id` without polling. |
 | `+add` | write | Upload local files, a non-recursive directory, or HTTP(S) pages converted to markdown. |
 | `+url` | write | Upload a URL source directly with optional display name and parsing instruction. |
 | `+schema` | write | Generate the compile schema for a knowledge base. |
 | `+compile` | write | Compile a knowledge base in incremental or full mode. |
 | `+status` | read | Query the current status of a knowledge base. |
-| `+rm-source` | write | Delete one source file from a knowledge base by display name. |
+| `+rm-source` | high-risk-write | Delete one source from a knowledge base by stable ID; exact display name is legacy compatibility only. |
 | `+remove` | write | Delete an entire knowledge base. |
 
 ## Common Workflows
@@ -67,6 +70,36 @@ Optional fields:
 - `--project-id`: optional project ID to bind.
 - `--project-name`: optional project display name.
 
+### Import a Compiled Snapshot
+
+Use `+import` only for a ZIP whose root contains `index.md` and at least one
+`wiki/**/*.md` page. The server validates all archive paths, limits, UTF-8 text, and Wiki links.
+
+```bash
+ae-cli kb +import \
+  --file ./knowledge-base.zip \
+  --name "Imported handbook" \
+  --description "Compiled documentation snapshot" \
+  --tags '["docs","handbook"]'
+
+# The submission returns requestId + queued. Query one snapshot later:
+ae-cli kb +import-status --request-id <requestId>
+```
+
+- The result is always a `personal` read-only snapshot; there is no `--scope`, `--force`, or replace option.
+- Imported snapshots support list, Index/Wiki reading, grep/read, Ask, and deletion. They do not expose source, Schema, usage, compile, member, settings, ownership-transfer, or company-publish operations.
+- The ZIP is limited to 50 MB and supports Markdown text only. Local images, attachments, other binaries, broken Wiki links, and ambiguous Wiki links are rejected by the server.
+- Submission returns `{requestId, status: "queued"}` immediately. It does not wait for ZIP validation or publication.
+- `+import-status` returns one of `queued`, `running`, `succeeded`, or `failed`; success includes `knowledgeBaseId`, and failure includes a stable error code/message.
+- If a `requestId` was returned, query it before retrying. If no request ID was received, run `ae-cli kb +list` before retrying the same name. A repeated same-name import is rejected.
+
+- Transition status: transitional
+- Owning module: te-claude External Knowledge Base Import API
+- Current transport: authenticated KB external REST through `kbUpload` for submission and `kbApi` for status lookup.
+- Gateway target: TBD (`kb.snapshot.import` proposed)
+- Review after: 2026-12-01
+- Exit condition: migrate to a typed Gateway capability when the equivalent multipart import capability is available, or remove this command if dynamic Gateway execution provides the same file-handling and output contract.
+
 ### Upload Files or Directories
 
 Use `+add` when sources are local files, local directories, or pages that should be fetched and converted to markdown before upload.
@@ -97,7 +130,7 @@ ae-cli kb +url \
   --parse-instruction "Keep headings and code blocks"
 ```
 
-`--url` must be `http(s)`.
+`--url` must be `http(s)`. The server detects the platform from the URL automatically: URLs on a `*.feishu.cn` or `*.larksuite.com` subdomain are parsed with the Feishu pipeline (including sub-documents, using the server's own Feishu parsing instruction — `--parse-instruction` is ignored for them); all other URLs are fetched as regular web pages.
 
 ### Generate Schema and Compile
 
@@ -107,7 +140,17 @@ Generate the schema first when the knowledge base needs a compile schema.
 ae-cli kb +schema --name engineering-handbook
 ```
 
-Use `--force` only to recover a stuck `generating` status. Use `--model` only when the user provides the model display name.
+Use `--force` only when `+status` reports `schema_generating` and the user explicitly wants to replace the current generation attempt. The replacement may consume additional tokens. Use `--model` only when the user provides the model display name.
+
+To add one-time guidance for this generation without changing stored knowledge base metadata, pass `--custom-instructions`. The server trims the value, treats whitespace-only input as absent, and accepts up to 10,000 Unicode characters. Do not include secrets or credentials.
+
+```bash
+ae-cli kb +schema \
+  --name engineering-handbook \
+  --custom-instructions "Prioritize troubleshooting workflows and preserve command examples"
+```
+
+Use `--dry-run` to inspect the request body before sending it. While generation is running, a request without `--force` is idempotent only when it supplies no new model or effective custom instructions; otherwise it fails with `KB_SCHEMA_GENERATION_IN_PROGRESS`. With `--force`, the selected model and custom instructions apply to the replacement attempt. Invalid text fails with `KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID`.
 
 Compile after sources and schema are ready:
 
@@ -213,9 +256,34 @@ ae-cli kb +read \
   --limit 60
 ```
 
+### List Sources
+
+List sources first to discover the stable identifier for the intended source:
+
+```bash
+ae-cli kb +list-sources --name engineering-handbook
+```
+
+Copy the exact `id` from the response into `+rm-source`. Do not guess a source ID from a local filename, URL, display name, or an older upload response.
+
+- Transition status: transitional
+- Owning module: te-claude External Knowledge Base Sources API
+- Current transport: authenticated KB external REST through `kbApi`.
+- Gateway target: TBD (`kb.source.list` proposed)
+- Review after: 2026-12-03
+- Exit condition: migrate to a typed Gateway capability when an equivalent source-list capability is available, or remove this command if dynamic Gateway execution provides the same discoverability and safe output contract.
+
 ### Remove One Source
 
-Use `+rm-source` only when the source display name is known exactly.
+Use `+rm-source --id` with the exact ID returned by the current `+list-sources` response. This is a `high-risk-write`; keep the interactive confirmation unless the user has explicitly authorized `--yes`.
+
+```bash
+ae-cli kb +rm-source \
+  --name engineering-handbook \
+  --id cm-source-id
+```
+
+`--display-name` is retained for legacy compatibility only when a stable source ID is unavailable:
 
 ```bash
 ae-cli kb +rm-source \
@@ -223,7 +291,7 @@ ae-cli kb +rm-source \
   --display-name kb-1780046712-guide.md
 ```
 
-If the user only gives a loose source name, do not guess. Ask for the exact uploaded display name.
+If the user only gives a loose source name, do not guess a source ID. Run `+list-sources`, identify the intended row from returned metadata, and ask only when multiple rows remain ambiguous.
 
 ### Delete a Knowledge Base
 
@@ -316,6 +384,30 @@ ae-cli kb +new --name "<name>" [--scope personal|company] [--description "..."]
 ae-cli kb +add --name "<name>" --files '["./a.md","./docs","https://example.com/page"]'
 ```
 
+### `+import`
+
+```bash
+ae-cli kb +import --file "./knowledge-base.zip" --name "<name>" [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."]
+```
+
+- `--file`: required local `.zip` file.
+- `--name`: required personal knowledge-base name, up to 30 characters.
+- `--description`: optional, up to 200 characters.
+- `--tags`: optional JSON array, max 2 unique tags, each up to 15 characters.
+- `--project-id`: optional project binding.
+- Scope and terminal build state are generated by the server and cannot be supplied by the client.
+- Output: `{requestId, status: "queued"}`. Use `+import-status`; the command does not poll.
+
+### `+import-status`
+
+```bash
+ae-cli kb +import-status --request-id <requestId>
+```
+
+- `--request-id`: required ID returned by `+import`.
+- Output: `{requestId, status, knowledgeBaseId?, errorCode?, errorMessage?}`.
+- Returns a single snapshot and does not poll. A failed import is returned as `status: "failed"` with its stable error code/message; an unknown or inaccessible request exits non-zero.
+
 ### `+url`
 
 ```bash
@@ -325,9 +417,14 @@ ae-cli kb +url --name "<name>" --url "https://example.com/page" [--display-name
 ### `+schema`
 
 ```bash
-ae-cli kb +schema --name "<name>" [--force] [--model "<model displayName>"]
+ae-cli kb +schema --name "<name>" [--force] [--model "<model displayName>"] [--custom-instructions "<one-time guidance>"]
 ```
 
+- `--custom-instructions`: Optional per-run schema-generation guidance. It is not persisted; whitespace-only input is omitted. The server allows at most 10,000 Unicode characters and rejects disallowed control characters. Do not include secrets or credentials.
+- `--force`: Replace the current attempt only when schema generation is already running and the user explicitly requests the replacement. The selected model and custom instructions apply to the new attempt, which may consume additional tokens.
+- `--dry-run`: Shows the same `customInstructions` request field that execution will send.
+- Errors: `KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID` means the field failed validation. `KB_SCHEMA_GENERATION_IN_PROGRESS` means generation is active and a request without `--force` supplied a new model or effective custom instructions.
+
 ### `+compile`
 
 ```bash
@@ -340,12 +437,26 @@ ae-cli kb +compile --name "<name>" [--mode incremental|full]
 ae-cli kb +status --name "<name>"
 ```
 
+### `+list-sources`
+
+```bash
+ae-cli kb +list-sources --name "<name>"
+```
+
+- `--name`: required knowledge base name.
+- Output: Safe source metadata including the stable `id` needed by `+rm-source`; raw paths, hashes, credentials, and source content are not returned.
+- Copy the exact `id` from the current response before deleting a source; never guess it.
+
 ### `+rm-source`
 
 ```bash
-ae-cli kb +rm-source --name "<name>" --display-name "<uploaded source display name>"
+ae-cli kb +rm-source --name "<name>" --id "<source-id>"
 ```
 
+- `--id`: preferred stable source identifier copied from `+list-sources`.
+- `--display-name`: legacy compatibility selector used only when an ID is unavailable.
+- If both are supplied, `--id` wins. The command removes one source only.
+
 ### `+remove`
 
 ```bash

package/skills/ae-project-semantic/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: ae-project-semantic
+description: "Use when generating, testing, submitting, reviewing, or publishing governed project semantic candidates from AE/TE project asset packages. This skill owns progressive asset-scope consent, recommendation quality gates, evidence authority, topic-domain grouping, candidate JSON generation, CLI closed-loop validation, and frontend review acceptance. Do not use it for ordinary analysis questions that only consume already published semantics."
+---
+
+# ae-project-semantic
+
+Project semantics are governed L2 project-wide business concepts, rules, calculation conventions, and default asset-selection methods. They sit above dashboards and reports. Dashboards, reports, events, properties, and metrics are L1 evidence and execution assets; they are not project semantics by themselves.
+
+Use `ae-cli` only. Do not write the database directly for recommendations, approvals, or releases.
+
+## Boundary
+
+- Use this skill to generate or evaluate project semantic recommendations.
+- Use `ae-analysis` to consume already published project semantics during analysis tasks.
+- Frontend can review, edit, approve, reject, and publish candidates; it must not generate recommendations.
+- Start with governed authenticated dashboards/reports. Broader project assets may be inspected only after explicit user consent and must retain their lower authority in evidence and confidence. Events, properties, metrics, background documents, and notes can provide supporting evidence only, never the primary L2 candidate subject.
+
+## Required Workflow
+
+1. Resolve the project and host.
+2. Read both recommendation references before inspecting candidates:
+   - [`references/recommendation-quality.md`](references/recommendation-quality.md) for the governed L2 quality bar;
+   - [`references/query-routing-v5.md`](references/query-routing-v5.md) for the current query-routing, recall-shortcut, and analysis-playbook discovery protocol.
+3. Check existing published project semantics:
+
+```bash
+ae-cli project-semantic list --project-id <project_id>
+```
+
+4. Export governed authenticated project assets and semantic snapshot context by default:
+
+```bash
+ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <tmp>/project-semantic-assets --force
+```
+
+When `--host` points directly to a locally started Common service instead of the deployed analysis gateway, scope the empty gateway domain to that command so the request uses Common's native `/api/cli/v1` route. Do not export this override globally:
+
+```bash
+AE_CLI_CAPABILITY_GATEWAY_DOMAIN= ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <tmp>/project-semantic-assets --force --host http://127.0.0.1:8992
+```
+
+5. Inspect `asset_scope`, `exported_asset_count`, `authenticated_asset_count`, `unauthenticated_asset_count`, `truncated`, work-unit count, and definition-family count before scanning. If `truncated=true`, warn that the package hit a compatibility limit. If the governed package is too sparse to support useful problem frames, report the actual counts and ask whether to re-export active collaborative assets. Do not broaden automatically:
+
+```bash
+ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope collaborative --output <tmp>/project-semantic-assets --force
+```
+
+If that package is still too sparse, report its counts and ask separately whether to export all valid project dashboards/reports and their referenced metadata:
+
+```bash
+ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope all_visible --output <tmp>/project-semantic-assets --force
+```
+
+`governed` is authenticated + collaborative + active in the recent 90-day window. `collaborative` removes only the authentication requirement. `all_visible` removes authentication, collaboration, and recency filters while still excluding deleted, frozen, hidden, offline, or otherwise invalid assets. Export is project-administrator-only; no per-user visibility filtering is required inside `all_visible`. Asset authentication is a separate governance write and must never be changed implicitly by scanning.
+
+6. Read the package in this order:
+   - `manifest.json`, `.asset-package.json`, `catalog/published.jsonl`, `catalog/disabled.jsonl` when present, `catalog/active-candidates.jsonl`, and `catalog/rejected-candidates.jsonl` to build the exclusion and revision context;
+   - `indexes/work-units.jsonl` as the dashboard-first investigation queue, preserving its usage-priority order while rotating across distinct business themes;
+   - `indexes/definition-families.jsonl` and compact dashboard/report records to compare reusable definition variants;
+   - `indexes/asset-directory.jsonl` and `indexes/governance-coverage.jsonl` for supporting evidence;
+   - `details/normalized/**` only for candidate-bearing or conflicting families, and `details/raw/**` only when the normalized definition is insufficient.
+
+   The service owns deterministic parsing, key-field normalization, definition signatures, usage ordering, and catalog assembly. The Agent owns business topic discovery, evidence interpretation, counterexample review, and candidate wording. Display names, descriptions, and notes remain evidence for interpretation, but they never make two otherwise identical definitions distinct. Do not load every detail file into context up front or delegate business judgment to a project-specific keyword table or deterministic template generator.
+
+7. Compare the proposed behavior against published, disabled, active-candidate, and rejected catalogs. Disabled semantics are suppression context: do not consume, recreate, or update them through recommendation generation. A project administrator can explicitly enable them later. Produce `CREATE` only for a genuinely new semantic, `UPDATE` when an active semantic needs a material revision, and no candidate when the package is already covered. Zero new candidates is a valid successful recommendation result.
+
+8. Validate the Agent-authored file against the exact exported package. This command checks only deterministic contract rules such as required fields, supported enums, catalog conflicts, duplicate fingerprints, and resolvable evidence references. `passed=true` is not a semantic-quality approval:
+
+```bash
+ae-cli project-semantic candidate validate --asset-package <tmp>/project-semantic-assets --submit-file <tmp>/project-semantic-candidates.json
+```
+
+9. Perform a separate Agent quality-review pass over the unchanged candidate file and the evidence it cites. Apply the Hard Quality Bar and `references/recommendation-quality.md`; do not rely on the generation pass to approve its own wording. For every candidate, record `PASS`, `REVISE`, or `INSUFFICIENT_EVIDENCE` with concrete findings and evidence references. Revise and repeat both deterministic validation and Agent review until every submitted candidate is `PASS`. A successful empty recommendation is preferable to weak filler.
+
+10. Submit the unchanged validated and Agent-reviewed file. Use `.asset-package.json.snapshot_hash`, or the `snapshot_hash` returned by `candidate validate`:
+
+```bash
+ae-cli project-semantic candidate submit --project-id <project_id> --submit-file <tmp>/project-semantic-candidates.json --snapshot-hash <snapshot_hash>
+```
+
+11. Review and enable through CLI when validating the full closed loop:
+
+```bash
+ae-cli project-semantic candidate list --project-id <project_id>
+ae-cli project-semantic candidate get --project-id <project_id> --candidate-id <candidate_id>
+ae-cli project-semantic candidate enable --project-id <project_id> --candidate-ids '["candidate_1"]'
+ae-cli project-semantic get --project-id <project_id> --id <semantic_id> --mark-used
+```
+
+Lifecycle management is deliberately separate from recommendation review:
+
+```bash
+ae-cli project-semantic disable --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
+ae-cli project-semantic list --project-id <project_id> --status disabled
+ae-cli project-semantic delete-impact --project-id <project_id> --semantic-id <semantic_id>
+ae-cli project-semantic delete --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
+ae-cli project-semantic enable --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
+```
+
+Disable means “do not consume and do not recommend again.” From disabled state, either enable the same semantic or inspect impact and physically delete it. Physical deletion means the semantic is absent and may be rediscovered by a future scan. Never delete merely to regenerate recommendations.
+
+## Hard Quality Bar
+
+A candidate file is not acceptable unless all of these are true:
+
+- It starts from governed evidence, or records the explicitly approved broader scope and lowers confidence for claims that depend on unauthenticated assets.
+- It groups by L2 business topic domain before generating candidates.
+- Every topic group includes the submit-contract fields `topic_domain_key`, `topic_domain_title`, `topic_group_key`, and `topic_group_title`.
+- It does not create one candidate per asset.
+- It does not promote an event/property/metric name into a project semantic title.
+- Each candidate binds `resource_refs` with real asset names/types/ids or names from the package.
+- Each candidate explains what it means, where it applies, how to use it, and what it excludes.
+- Each candidate body covers business definition, applicable questions, decision or calculation rules, Agent usage, and boundaries or exceptions in the project's natural language. Exact headings are not a machine contract.
+- The concrete business judgment belongs in the decision or calculation content; asset names and counts belong in `resource_refs`, `evidence`, and `recommendation_reason`, not in the semantic body.
+- A batch fails review when candidates reuse the same body with only asset names or counts changed.
+- Each candidate includes evidence excerpts or source titles that show why it was recommended.
+- Each candidate changes how the Agent interprets a business question, selects default assets, or applies a project-wide rule.
+- Each candidate declares one of the evidence-backed recommendation kinds in `query-routing-v5.md`: `QUERY_ROUTING`, `RECALL_SHORTCUT`, or `ANALYSIS_PLAYBOOK`.
+- A formula, threshold, state, event, property, report, or asset name is supporting L1 evidence, never a standalone candidate.
+- A route must contain a meaningful asset-choice branch; a shortcut must contain a minimal bundle plus stop and fallback; a playbook must be note-backed or explicitly labeled as a structure-inferred recommended path.
+- Existing published and disabled semantics are checked before submission; disabled semantics suppress recreation.
+- An unauthenticated asset may support a route, shortcut, or playbook only when definitions, work-unit structure, usage, or notes provide corroboration. Never present it as a certified project rule solely because it was exported.
+- Sparse evidence is either skipped or marked lower confidence; do not inflate weak recommendations.
+
+## Generic Extraction Protocol
+
+The protocol must work unchanged for games, retail, finance, SaaS, operations, and unknown project domains.
+
+1. Inventory evidence without deciding themes. Separate authenticated and unauthenticated dashboards/reports, record the export scope and selection reason, and keep existing governed semantics and supporting L1 metadata distinct.
+2. Discover semantic families only from evidence that was actually read. Use these cross-domain dimensions as questions, not as prefilled answers:
+   - business object, state, and alias;
+   - analysis subject and deduplication grain;
+   - measure, aggregation, numerator, denominator, and transformation;
+   - inclusion, exclusion, and filter scope;
+   - query range, cohort window, observation window, and freshness;
+   - unit, currency, normalization, and attribution;
+   - default asset selection and relationships between assets;
+   - applicability, exception, and conflict boundaries.
+3. Compare definition variants inside each family. A candidate may state a default only when evidence shows one authoritative variant. Conflicting variants require a disambiguation rule or a warning, not an invented standard.
+4. Form a topic domain after the semantic families are understood. The domain title must come from the project's natural business language and explain why its candidates are reviewed together.
+5. Generate a candidate only when removing it would make a future Agent more likely to choose the wrong business object, asset, grain, formula, scope, unit, window, or exception.
+6. For every claim in the body, identify direct supporting evidence. Keep asset names and excerpts in `resource_refs`, `evidence`, and `recommendation_reason`; keep reusable business knowledge in `content`.
+7. Compare candidates by resulting Agent behavior. Merge candidates that lead to the same interpretation and execution; split candidates that answer independently searchable questions.
+8. Run a counterexample pass: inspect minority definitions and assets that may violate the proposed rule. Narrow or drop unsupported conclusions.
+9. Before wording candidates, form evidence-backed problem frames and assign asset roles. Use `query-routing-v5.md`; do not optimize for candidate count or one-candidate-per-asset coverage.
+10. Keep a decision ledger for discovered problem frames, including routed, shortcut, playbook, definition-only, and evidence-insufficient dispositions.
+
+## Anti-Overfitting Rule
+
+- Never encode a customer, project name, project ID, asset ID, expected topic title, expected candidate title, or expected candidate count in this skill or CLI generation code.
+- Never start from a fixed industry taxonomy or keyword dictionary. Keywords may locate evidence only after a semantic family is discovered; they must not determine the result.
+- A test package is an evaluation sample, not a source of reusable rules. Tune the protocol only when the change is defensible across unrelated domains.
+- Quality is measured by evidence support and changed Agent behavior, not by matching a previously approved list of topics.
+
+## User-Facing Recommendation Display
+
+When showing CLI recommendation results to a user, never flatten candidates into a single numbered list. The user-facing answer must use the same hierarchy as the candidate JSON and frontend review UI:
+
+```text
+Project semantic recommendation scan completed
+
+Summary:
+- Topic domains: <N>
+- Candidate semantics: <N>
+- Validation: passed | failed
+
+Topic domain: <topic_domain_title> (<candidate_count> semantics)
+- [<semantic_type>] <candidate title>
+  <one-sentence summary>
+  Evidence: <asset title 1>, <asset title 2>, ...
+```
+
+Rules:
+
+- Show topic domains first, then candidates under each domain.
+- Include each domain's semantic count.
+- Include each candidate's semantic type, title, short summary, and primary evidence asset titles.
+- If the CLI command returns `topic_groups`, use that field directly for the display order and counts.
+- Keep the full JSON path or submit command separate from the human summary.
+- Do not present a flat list like `1. semantic A 2. semantic B ...` unless the user explicitly asks for raw candidate order.
+
+## Output Discipline
+
+When reporting recommendation results, include:
+
+- commands run;
+- asset scope, exported/authenticated/unauthenticated asset counts, and snapshot hash;
+- topic domains, semantic counts per domain, and candidate titles grouped under each domain;
+- evidence assets per candidate;
+- quality warnings, if any;
+- problem-frame coverage and rejected shallow-opportunity warnings;
+- submit/review/release IDs after writes.

package/skills/ae-project-semantic/references/query-routing-v5.md

@@ -0,0 +1,165 @@
+# Project Semantic Query Routing V5
+
+Use this protocol when project asset packages contain asset definitions, work-unit membership, recent usage, authentication provenance, and optional notes, but do not contain historical user questions, query failures, or execution traces. Never claim that a structure-inferred path is a proven historical best practice.
+
+The only recommendation kinds are:
+
+- `QUERY_ROUTING`: choose the right dashboard/report for a question and distinguish nearby assets;
+- `RECALL_SHORTCUT`: reduce broad asset search to a minimal ordered bundle with stop and fallback conditions;
+- `ANALYSIS_PLAYBOOK`: execute a multi-step or branching analysis path supported by notes or strong complementary asset structure.
+
+Submission semantic types remain unchanged: routing and shortcuts normally use `asset_semantics`; playbooks normally use `business_rule`.
+
+## Evidence roles
+
+- Dashboard/report membership and work units show which assets jointly address a problem.
+- Normalized/raw definitions determine what each asset computes, filters, groups, and returns.
+- Display names, descriptions, notes, and dashboard memo text explain intended questions and explicit instructions, but never make otherwise identical definitions different.
+- Recent usage and recency may prioritize a default entry among otherwise suitable assets; they never establish a formula, causal rule, or business priority.
+- Definition families and conflicts distinguish alternatives, duplicates, misleading titles, and exception variants.
+- Published, active, and rejected catalogs provide exclusion and revision context.
+
+## Discover problem frames before candidates
+
+For every inspected work unit, create zero or more evidence-backed `problem_frames`. Do not require every work unit or asset to produce a candidate. Each frame records:
+
+- natural-language problem intent;
+- triggers and constraints;
+- business object and expected answer grain;
+- available assets and their roles;
+- decision points that change asset choice;
+- explicit note/memo guidance, when present;
+- usage/recency priority;
+- evidence gaps.
+
+Assign relevant assets one of these roles for the frame:
+
+- `DEFAULT_OVERVIEW`;
+- `CONDITIONAL_BRANCH`;
+- `DETAIL_DRILLDOWN`;
+- `COMPARISON_OR_COUNTEREXAMPLE`;
+- `FALLBACK`;
+- `UNSUITABLE_FOR_FRAME`.
+
+An asset may have different roles in different frames. Every role assignment must cite exact definition or note evidence.
+
+## QUERY_ROUTING gate
+
+Generate only when all are true:
+
+1. At least two plausible assets could be confused or selected for related questions.
+2. Object, grain, formula, scope, time, parameter, or output differences determine the correct asset.
+3. The candidate states:
+   - triggering question types;
+   - default asset or entry dashboard;
+   - branch conditions and target assets;
+   - assets that must not substitute for one another;
+   - required parameters or filters;
+   - drilldown and fallback.
+4. Removing the route would materially increase wrong-asset selection.
+
+A formula may explain why a branch is selected, but it is not a routing semantic by itself.
+
+## RECALL_SHORTCUT gate
+
+Generate only when all are true:
+
+1. A broad work unit contains more assets than a recurring query needs.
+2. Evidence supports a minimal ordered subset.
+3. The candidate states the first asset, continuation conditions, stop condition, safe fallback, and unrelated asset groups that can be skipped.
+4. Usage may prioritize between evidence-equivalent suitable entries, but cannot override definition fit.
+5. Search-space reduction is stated from package membership only; never claim measured latency improvement without runtime evidence.
+
+## ANALYSIS_PLAYBOOK gate
+
+### High-confidence playbook
+
+Requires an explicit note or memo stating an analysis goal, sequence, decision, or caveat, plus executable assets supporting the steps. If any required asset is unauthenticated, label the playbook lower confidence and require project-administrator review; do not present the path as certified.
+
+### Medium-confidence recommended analysis path
+
+Allowed without explicit notes only when all are true:
+
+- at least three complementary roles form an overview-to-branch-to-drilldown or measure-to-diagnose-to-verify path;
+- exact definitions establish branch conditions and prevent interchangeable use;
+- no causal claim, business priority, or mandatory sequence is invented;
+- the output is labeled `RECOMMENDED_ANALYSIS_PATH`;
+- boundaries state that the path is structurally inferred and requires review.
+
+Reject paths supported only by co-location, similar titles, independent metrics, or usage ranking.
+
+## Reject shallow candidates
+
+Reject a candidate that only provides:
+
+- one formula, threshold, state, event, property, report, dashboard, or asset name;
+- an inventory of related assets;
+- a topic summary without asset-choice decisions;
+- a broad umbrella listing measures without branches;
+- an inferred maturity hierarchy, causal explanation, or best practice absent from notes;
+- a route that does not reduce ambiguity or search.
+
+Simple formulas and states remain evidence inside routes and playbooks. They do not become standalone project semantics.
+
+## Candidate fields
+
+In addition to the governed submission fields, retain:
+
+- `candidate_kind`;
+- `problem_triggers`;
+- `default_route`;
+- `branch_rules`;
+- `do_not_use`;
+- `drilldown_path`;
+- `fallback`;
+- `asset_roles`;
+- `search_space_reduction`;
+- `evidence_strength`: `HIGH_NOTE_BACKED` or `MEDIUM_STRUCTURE_BACKED`;
+- `confidence_limit`;
+- `problem_frame_ids`.
+
+The candidate body must cover business definition, applicable questions, decision or calculation rules, Agent usage, and boundaries or exceptions. Use headings natural to the project's language when headings improve readability; exact localized wording is not part of the machine contract.
+
+Reusable decision knowledge belongs in `content`. Asset names, ids, counts, and excerpts belong in route fields, `resource_refs`, `evidence`, and `recommendation_reason`.
+
+## Decision ledger
+
+When producing recommendation artifacts, record:
+
+- work units and notes actually inspected;
+- discovered problem frames;
+- asset-role assignments and evidence;
+- routing/shortcut/playbook decisions;
+- rejected shallow opportunities and reasons;
+- candidate-to-frame mappings;
+- dispositions: `ROUTED`, `SHORTCUT`, `PLAYBOOK`, `DEFINITION_ONLY`, or `EVIDENCE_INSUFFICIENT`.
+
+Coverage is measured over supported problem frames, not raw asset or definition-signature counts. Every discovered frame needs a disposition, but not every work unit or asset needs a candidate.
+
+## Acceptance
+
+Candidate count and average prose score are not success metrics. Evaluate with evidence-grounded future-query probes and report:
+
+- primary asset or entry selection;
+- conditional branch selection;
+- prevention of plausible wrong-asset substitution;
+- minimal asset bundle;
+- stop and fallback completeness;
+- search-space reduction versus the work unit;
+- playbook step support;
+- unsupported causal or order claims;
+- problem-frame coverage;
+- formula-only or inventory-only candidate count, which must be zero.
+
+Before submit, require:
+
+- CLI validator `passed=true`;
+- no shallow formula/state-only candidate;
+- every route has a meaningful branch;
+- every shortcut has stop and fallback;
+- every playbook is note-backed or explicitly labeled structure-backed;
+- candidates materially choose or narrow assets better than an undifferentiated work-unit scan.
+
+## Anti-overfitting
+
+Never encode project names, project ids, asset ids, event names, expected topics, expected titles, expected routes, expected counts, or fixed industry dictionaries. The reusable mechanism is problem framing, asset-role classification, decision branching, minimal bundles, and evidence-bounded paths.