@thinkingai/ae-cli 6.1.19 → 6.1.21

package/skills/ae-kb/references/analysis-workflow.md

@@ -0,0 +1,292 @@
+# Knowledge-guided analysis workflow
+
+Use this workflow after knowledge-base retrieval when the pages will guide a
+project-scoped business data analysis. The knowledge base determines which
+saved asset to execute, which business definition applies, and which
+conclusions are out of bounds. Current values still require an `ae-analysis`
+data query.
+
+This workflow does not define knowledge-base compilation rules. Do not use it
+to create, upload, generate a schema for, compile, or delete a knowledge base.
+
+Asset-authentication and metric-recommendation review is a separate workflow.
+For requests to recommend authentication assets or metrics, use
+`analysis-meta governance-recommendation export|submit|decisions` without
+project-KB retrieval as a prerequisite.
+
+## Establish source evidence
+
+1. Apply the `ae-analysis` project gate before any project-scoped analysis
+   command. Verify the host and exact project ID; a KB name, binding, or display
+   name does not prove the live project identity. Do not probe a default or
+   previously used project while resolving the requested one.
+2. Use `ae-kb-discovery` to select the candidate. An explicitly named KB wins;
+   otherwise prefer a compiled KB whose `bindings.targetType` is `project` and
+   whose `targetId` exactly matches the verified project ID.
+3. Follow the deterministic `+index -> +grep -> +read` procedure in
+   [`query-workflow.md`](query-workflow.md). Only source-page content actually
+   returned by `+read` counts as a KB hit. A list item, index title, grep
+   snippet, or `+ask` synthesis alone is not enough to drive execution.
+4. If `+ask` helps locate or synthesize multiple pages, read its cited source
+   pages before executing data queries. Verify asset IDs, definitions, dynamic
+   parameters, time rules, and limitations in the source text.
+5. Search with the business object, metric, product area, and time wording from
+   the user's question. Prefer a section that contains both an asset chain and
+   its semantic definition; do not substitute an asset merely because its
+   title is similar.
+
+A compiled KB is a snapshot, not a live data source. Use it for routing,
+semantics, and decision boundaries. Verify current asset existence, the current
+saved definition, and current data with `ae-analysis`.
+
+## Choose the most specific executable asset
+
+A recall card's primary dashboard is a routing prior, not automatically the
+final executable asset. Before building the execution contract, compare the
+question with the linked asset pages and choose the smallest saved asset chain
+that covers the requested output.
+
+When a recall card points to a broad dashboard but the user requests a concrete
+ranking, table, member/customer list, breakdown, or parameterized result, make
+one targeted `+grep` call against the relevant detail-asset directory copied
+from the KB index, such as `wiki/reports`. Search with the user's business
+object, requested dimensions, measure, and output form. Read the best exact
+candidate page before executing anything.
+
+Rank candidates by semantic coverage, not by primary/backup position alone:
+
+1. Prefer a page whose "questions answered", purpose, grain, dimensions,
+   measures, and output fields directly cover every requested subquestion.
+2. Prefer one parameterized saved report that produces all requested variants
+   under one definition over several generic reports with different definitions.
+3. Prefer an asset that exposes the requested business-facing dimensions and
+   fields directly. Do not substitute an account ID when the question asks for
+   member display names if a matching saved report exposes those names.
+4. Then apply authority, certification, definition-state, and runtime-policy
+   evidence. A certified broad dashboard does not outrank an equally governed
+   report whose stated question and output are a more exact match.
+5. Treat the recall card's primary order as mandatory only when the card
+   explicitly states that alternatives must not be used for this question.
+
+If two candidates encode materially different meanings of the same phrase,
+such as one-way events versus combined inbound and outbound events, do not
+blend them. Select the candidate whose stated question, output shape, and grain
+best match the request, and disclose the chosen definition.
+
+## Build the analysis execution contract
+
+Before calling a data-query command, extract and retain this contract from the
+pages actually read:
+
+| Contract field | Required evidence |
+|---|---|
+| Business question | Metric, entity, dimensions, filters, comparison, and requested output |
+| Asset chain | Exact type, ID, name, and parent-child relation for dashboards, reports, metrics, or other saved assets |
+| Statistical definition | Event or metric, aggregation, distinct entity, dimensions, and filters |
+| Saved parameters | Exact parameter names, value domains, defaults, selectors, and the requested overrides |
+| Time contract | Fixed or dynamic window, inclusion of today, timezone, and whether an override is supported |
+| Authored context | Folder, dashboard name, remarks, notes, and business filters, with their applicable scope |
+| Decision boundaries | Case-only, frontend-only, adoption-only, not revenue, non-generalizable, expired, conflicting, or human-decision-required constraints |
+| KB evidence | Exact KB name, page path, and section actually read |
+
+Classify the contract before querying:
+
+- `executable`: exact asset identity and semantics cover the question, with no
+  unresolved conflict.
+- `partially_executable`: evidence covers only some subquestions; query and
+  answer only those parts.
+- `blocked`: a required asset, metric, aggregation, entity, filter, parameter,
+  time rule, or decision boundary is missing or conflicting; stop the affected
+  query and report the gap.
+
+Do not fill a contract gap with general knowledge, a similarly named asset, or
+a technically valid query. When the task forbids clarification, return that the
+available evidence cannot answer the affected part instead of choosing an
+interpretation silently.
+
+## Execute the exact saved-asset chain
+
+An exact asset identified by a source page takes priority over fuzzy search and
+ad-hoc analysis:
+
+1. For a dashboard ID, call `analysis dashboard get` once with the verified
+   project ID. Verify its name, child reports, `effective_settings`,
+   `filter_config`, remarks, and notes, then execute the child report identified
+   by the KB evidence.
+2. For a report ID, call `analysis report get` with the verified project ID.
+   Verify its model, metric, aggregation, dimensions, filters, saved parameters,
+   and time definition before querying data.
+3. Read the matching `ae-analysis` data-command reference before execution. Use
+   [`report_data_run.md`](../../ae-analysis/references/report_data_run.md) for a
+   bounded saved report result and
+   [`dashboard_report_data_run.md`](../../ae-analysis/references/dashboard_report_data_run.md)
+   when dashboard execution context is required. Use the corresponding export
+   reference only for complete, unknown-size, over-limit, or long-running output.
+4. For an SQL report, use `analysis report-data run` with only names present in
+   the live report's `definition.params`, passed through `--sql-params`. Date
+   changes must use the saved date/time parameter. Dashboard generic filter or
+   time overrides do not apply to SQL reports.
+5. For a non-SQL report, use the saved report or dashboard-report data command
+   and only the supported filter, grouping, and time overrides documented by
+   `ae-analysis`.
+6. For a metric or another saved asset, use its exact identity and corresponding
+   command. Never replace it with a same-name object.
+7. Use the saved-asset discovery procedure from `ae-analysis` only when the KB
+   page provides no exact identity. A discovered candidate still requires
+   semantic equality, not title similarity.
+
+If the user asks for multiple groupings that one saved dynamic report supports,
+execute that same report once per required parameter variant. Keep the common
+metric, time, environment, and other filters identical. Do not repeat an
+identical data command merely to inspect output that was locally truncated;
+capture or export the complete result through the supported data command.
+
+The statement "the KB contains definitions but not current values" means that
+the matched saved asset must be attempted first. It does not authorize jumping
+directly to a reconstructed SQL or ad-hoc query. If the attempt cannot produce
+a usable result, follow the explicit ordinary-analysis fallback below.
+
+When the live definition agrees with the KB, use the query result as data
+evidence and the KB page as routing, semantic, and boundary evidence.
+
+## Preserve authored parameter semantics
+
+- Copy exact saved parameter names and allowed values from `analysis report get`.
+  Map the user's requested time, environment, member/company grouping, and
+  limit to those parameters without renaming or reinterpreting them.
+- A saved selector, lookup table, user group, or dashboard filter is part of the
+  definition. Do not replace it with a convenient event property or a guessed
+  equivalent. For example, a saved "formal environment" selector backed by a
+  lookup table cannot be replaced with `is_dev=false` unless the KB or current
+  saved definition explicitly establishes that equivalence.
+- If a dependency used by the saved report is not expanded in the KB snapshot,
+  execute the saved report as authored. Do not rebuild that dependency from
+  partial KB text.
+- Inspect the returned effective time, route, warnings, partial failures, and
+  pagination/truncation signals before computing or presenting results.
+
+If the live asset differs from the KB snapshot, determine whether the difference
+affects the question. A difference in metric, aggregation, distinct entity,
+filter, saved parameter, time window, or applicable scope is a conflict: stop
+the affected conclusion, show the conflict, and do not silently choose one
+definition or hide it with a replacement query.
+
+## Fall back without hiding the knowledge-base result
+
+None of these conditions alone authorizes an ad-hoc or SQL reconstruction:
+
+- The exact saved asset has not yet been attempted.
+- The exact saved asset returns an empty result.
+- The exact asset has a validation, transport, capability, or definition
+  execution failure.
+- Only part of a multi-report or multi-variant request succeeds.
+- Its definition contains a semantic conflict, label mismatch, or disagreement
+  between the metric name and aggregation.
+- It has a fixed historical window while the user asks about the current period,
+  a recent period, or another date range.
+- The page limits the evidence to one case, frontend behavior, adoption, one
+  customer, or one version.
+- The result is unexpected, while another similar asset would be easier to run.
+- A direct SQL or ad-hoc query appears faster or easier to parameterize.
+
+Handle these states without changing the contract:
+
+- Empty result: report that the saved asset is empty under its complete saved
+  context. Recheck effective parameters, time, warnings, and cache behavior on
+  that asset when useful. A diagnostic query may explain the empty result, but
+  it must be labeled separately and must not replace the empty saved-asset
+  result.
+- Validation or parameter error: re-read `analysis report get` and correct only
+  the input mapping allowed by its saved definition. Do not translate the report
+  into SQL.
+- Partial success: retain successful saved-asset results and apply these rules
+  independently to each failed part. Do not discard valid sub-results or replace
+  the whole request with one reconstructed query.
+- Permission denial: preserve the denied asset, error, and request ID. Do not
+  retry the denied operation or use an undocumented lower-level API. The
+  ordinary analysis fallback may still use another standard `ae-analysis`
+  capability, whose permission is independently enforced by the backend.
+  Permission denial on a dashboard or report is not, by itself, a prohibition
+  on ad-hoc analysis. If the required events, metrics, properties, metadata,
+  and ad-hoc capability are accessible through their documented commands, the
+  fallback may query them under a separately stated temporary definition.
+- Capability unavailable: report a capability gap only after the saved command
+  actually returns the corresponding unavailable-capability evidence. Do not
+  infer the gap from documentation or skip the attempt. A temporary fallback is
+  possible only under the explicit entry and equivalence rules below.
+- Transport or transient failure: retry the same saved-asset command only when
+  the error contract recommends retry. If the failure persists, preserve its
+  evidence and apply the explicit fallback rules below rather than switching
+  paths silently.
+- Semantic conflict: show the conflicting fields and their impact. A fallback
+  may answer under a different, independently verified definition, but it must
+  not claim to resolve the KB asset's conflict or present the result as
+  definition-equivalent.
+- Fixed historical window: answer only for that window. If it cannot answer a
+  current-period question, state that it cannot be extrapolated.
+- Limited applicability: keep the conclusion within the declared scope. Do not
+  expand adoption into revenue or intent, one module into the whole product, or
+  one case into all customers.
+
+Technical success is not semantic correctness. A query that changes the
+contract's event, metric, aggregation, entity, filter, parameter, time, or
+applicable scope is not an equivalent validation.
+
+## Degrade to the ordinary analysis path
+
+The KB path is preferred, not exclusive. If the exact KB-selected asset cannot
+produce the requested live result after a real attempt, continue as though no
+executable KB asset had been found and follow the ordinary `ae-analysis`
+"Existing business asset before ad-hoc" workflow:
+
+1. Search for another accessible saved report or dashboard whose current live
+   definition covers the request.
+2. Verify semantic equality before using it. A title match is not enough.
+3. If no saved definition matches, use ad-hoc analysis only when the normal
+   `ae-analysis` rules permit it and the required event, properties, metric,
+   aggregation, entity, filters, time, and timezone can be established.
+4. Use only documented standard capabilities. Each fallback command remains
+   subject to the backend's independent authorization checks.
+
+Fallback is available when the KB-selected asset is missing from the live
+project, inaccessible, empty for the requested scope, outside its supported
+time or breakdown, or persistently fails after the documented correction or
+retry path. The user does not need to restate the original data request merely
+to allow this ordinary fallback.
+
+Ad-hoc analysis must still satisfy the safety conditions below. SQL must also
+satisfy the additional SQL constraints in `ae-analysis`.
+
+1. The event, properties, metric, aggregation, distinct entity, filters, time
+   window, and timezone must be established independently from readable KB
+   evidence, another verified saved asset, or verified metadata. Do not infer
+   hidden selectors or dependencies from the failed asset.
+2. Do not describe a different definition as equivalent when metric,
+   aggregation, entity, filter, parameter, time, or scope differs.
+3. Do not use fallback to modify, repair, certify, or overwrite the KB-selected
+   asset.
+4. Do not use an undocumented API or suppress permission, conflict, empty-result,
+   warning, or failure evidence from the KB path.
+
+Present the KB path and fallback path separately. State why fallback occurred,
+which alternative asset or ad-hoc definition produced the data, and every
+material difference from the KB-selected definition. Never claim that the KB
+asset produced a fallback result. An empty or denied KB result remains part of
+the audit record even when the fallback succeeds.
+
+## Answer with traceable boundaries
+
+Make these three layers distinguishable in the final answer:
+
+1. **Query result:** saved asset used, actual time window, metric value, filter
+   scope, and effective execution settings.
+2. **Knowledge basis:** KB name, page path, and section used, plus the asset,
+   parameter, and semantic choices it constrained.
+3. **Limits and unresolved issues:** fixed windows, limited applicability,
+   definition conflicts, permissions, warnings, partial failures, or data gaps,
+   and the questions they prevent you from answering.
+
+Cite at least the KB name and page path for knowledge evidence. Use the asset
+name and available link for data evidence rather than presenting a raw ID as the
+primary label. Never present historical values copied from a KB page as a
+current query result, and never present an inference as verified fact.

package/skills/ae-kb/references/query-workflow.md

@@ -20,7 +20,12 @@ candidate rather than searching everything blindly.
 1. **Index the candidate.** Call `+index --sources` with the discovery pick.
    Use `index.md` for navigation, a fit check, and **query wording** — the real
    terms in the index (product names, API identifiers, section titles) become
-   your `+grep` keywords.
+   your `+grep` keywords. The root index routes at module level only; when a
+   module is too coarse for your question (it has many detail pages), read that
+   module's catalog page (`wiki/modules/<module>/catalog.md`) — it groups
+   detail pages by topic with one-line summaries. **Copy** detail-page paths
+   from the catalog as additional `--paths` candidates; the catalog itself is
+   navigation, not an answer source.
 
    **Done when:** you have the candidate's `index.md`, and a list of `wiki/...`
    links you can **copy** (0 items still counts as done).
@@ -29,36 +34,52 @@ candidate rather than searching everything blindly.
    such as `wiki/sandbox.md`, or a subdirectory such as `wiki/guides`). Call
    `+grep` with the candidate `--sources` and the copied list as `--paths`. Search
    with the index terms. If the first grep misses, rewrite the query **once**
-   using different index terms — still with this same `--paths` — then stop
-   rewriting.
+   using different index terms **only** — never paraphrase the user's wording
+   from memory — still with this same `--paths`. If the rewrite also misses,
+   stop grepping entirely: `+read --outline` the index page whose title or
+   section name relates to the question and read the matching heading range
+   from it. A third rewrite of the same idea produces no new recall.
 
    **Done when:** you have hits, or you have rewritten once, or step 1 copied
    0 paths. Copied 0 paths → skip grep and `+read --outline` the likeliest
    title page, or go back to discovery for the next candidate.
 
-   A grep hit gives both a hit anchor and its enclosing section range:
-
-   - `line` is the exact matched line. Use it as the anchor when the evidence
-     is local.
-   - `sectionStartLine` / `sectionEndLine` are the enclosing heading-section
-     boundaries. Use them when the answer needs the whole section context, or
-     as the maximum boundary when choosing a smaller window.
+   **Reading the result — the page-level `results` view.** The response is a page-level
+   `results` array: each entry is one page with its full `hitCount`, a
+   `pageKind`, and up to 4 `sections` previews (each with its breadcrumb,
+   `sectionStartLine`/`sectionEndLine`, and a text preview). Read the top
+   relevant pages until every subquestion of the question is backed by
+   sections you have actually read. `hitCount` tells you how dense the matches
+   are on a page; `pageKind: "catalog"` marks a module directory page — its
+   previews are detail-page entries, so treat them as navigation: add the
+   detail-page paths you see there to your read list instead of reading the
+   catalog as an answer source. When a page has `moreSections > 0` and the
+   answer is not in the previews, re-grep that single page to see all its
+   hits.
+
+   Each page-group section preview carries its enclosing heading-section
+   boundaries:
+
+   - `sectionStartLine` / `sectionEndLine` are the section boundaries. Use
+     them as the read window (or as the maximum boundary when choosing a
+     smaller window under them).
    - `+read --offset` / `--limit` are the actual read window. Choose the
      smallest reliable window that preserves the needed evidence; do not
      shell-truncate with `| head`.
+   - `+read --expand block` may include the rest of a Markdown block just
+     outside the requested window. Use `+read --expand none` when the line
+     window must be exact. Omit the flag to keep the server default, `block`.
 
 3. **Choose the section locator.** Pick one locator for the current target
    page:
 
-   - **Same-page grep hit:** choose a read window from the hit. For narrow
-     fact/table/code evidence, read a bounded window anchored at `line`; stay
-     within `sectionStartLine`–`sectionEndLine`. For section-level meaning,
-     field definitions, caveats, or rows that depend on the heading context,
-     read the section range with
+   - **Section preview of a page group:** read the section range with
      `--offset sectionStartLine` and
-     `--limit sectionEndLine - sectionStartLine + 1`. If the first window is
-     too small, widen once up to the section range. Do not crawl by shifting
-     offsets line by line.
+     `--limit sectionEndLine - sectionStartLine + 1`. For narrow
+     fact/table/code evidence, narrow the window under the section boundary
+     once you see the preview text. If the window turns out too small, widen
+     once up to the section range. Do not crawl by shifting offsets line by
+     line.
    - **Linked or related page:** if you follow a catalog/detail/related link to
      a different page, the old grep range no longer applies. If you have
      concrete terms for that new page, run `+grep --paths '["<new-page>"]'`
@@ -78,32 +99,41 @@ candidate rather than searching everything blindly.
    page response.
 
 4. **Read the selected window.** Read the selected window in one call. Windows
-   come from the hit anchor, the grep hit's section boundaries, or two adjacent
-   outline headings (`heading.line` of the target section to `heading.line - 1`
-   of the next). If a window turns out too small, widen to the section boundary
-   in one more call.
+   come from a page-group section preview's boundaries or two adjacent outline
+   headings (`heading.line` of the target section to `heading.line - 1` of the
+   next). If a window turns out too small, widen to the section boundary in one
+   more call.
 
    **Done when:** the needed evidence is in context without shell truncation,
    or the page response is complete and untruncated.
 
+   **Read coverage:** read the relevant candidate pages from the page results
+   until every subquestion of the user's question is backed by sections you
+   have actually read — not until a page "looks like the answer". Do not stop
+   to compose the answer while any subquestion still has no read evidence
+   behind it, and do not pick a single page by surface similarity between the
+   question wording and the page/module name or hit line.
+
 5. **Assess coverage, then answer or iterate.** Map the user's question into
    subquestions and check each one against the sections you actually read. If a
    subquestion is covered, answer with citations (knowledge base + page path +
    section). If a gap remains, go back to step 2 with another set of `--paths`
    **copied** from the index, or return to discovery for the next candidate.
-   If the evidence is missing after the allowed search, say which subquestion is
-   not covered instead of filling it from memory.
+   If the evidence is missing after the allowed search, the only acceptable
+   output for that subquestion is "not covered by the knowledge base" — do not
+   attach a confident value from general knowledge, not even with a disclaimer
+   or a self-declared boundary.
 
    **Done when:** every answered subquestion is supported by read sections, or
    the remaining gaps are explicitly reported as missing evidence.
 
 ## Anti-pattern: same-page offset crawling
 
-The failure this workflow prevents: grep returns a line number, you `+read` a
-tiny window around it, it is cut mid-evidence, so you nudge the window one line
-at a time. That wastes calls and never shows page structure. Instead: use the
-hit anchor, widen once up to the section boundary, or open `--outline` and read
-the selected heading range.
+The failure this workflow prevents: reading a tiny window, finding it cut
+mid-evidence, and nudging the window one line at a time. That wastes calls and
+never shows page structure. Instead: read the page-group section range, widen
+once up to the section boundary, or open `--outline` and read the selected
+heading range.
 
 ## Related
 

package/skills/ae-kb/references/source-mutations.md

@@ -0,0 +1,95 @@
+# Replace and Restore Source Drafts
+
+These commands require a host exposing the External KB source-mutation and preview APIs. They do not compile or publish. Do not substitute `+add`, delete/re-add a source, or use whole-KB `+rollback` when the host lacks these routes.
+
+## Discover the exact target
+
+1. Use `kb +list` to copy the exact knowledge base name and `personal` or `company` scope.
+2. Use `kb +list-sources --name "<name>" --scope <scope>` to copy the current source `id`, `sourceType`, and `contentRevision`.
+3. For restoration, use `kb +versions` and `kb +version-sources` to select a published version containing this source. To discard unpublished changes, use the latest published **version number**, not `latestVersionId`.
+4. The source must still exist. URL/Feishu sources and deleted parent sources cannot use these commands. Never guess IDs, revisions or historical paths.
+
+All new commands use `kb source <action>`. Existing `+source-put`, `+source-rm` and whole-KB `+rollback` keep their original behavior.
+
+## Replace a file source
+
+```bash
+ae-cli kb source replace --name "<name>" --scope personal --id <source-id> \
+  --source-type file --expected-revision <contentRevision> --file ./revised.md --dry-run
+
+ae-cli kb source replace --name "<name>" --scope personal --id <source-id> \
+  --source-type file --expected-revision <contentRevision> --file ./revised.md
+```
+
+- Sends multipart `PUT /agent/api/external/knowledge-bases/sources/<id>/raw?name=...&scope=...` with `file` and `expectedRevision`.
+- Different filenames are allowed, but the extension must match the current source's format. The host enforces this against the actual source. A `.pdf` cannot replace `.md`; ZIP cannot replace an ordinary file.
+- At most 50 MB. Supported ordinary extensions: `.md`, `.markdown`, `.txt`, `.csv`, `.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`, `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.bmp`, `.svg`.
+- Updates the existing source draft immediately, preserving source ID, display name and raw path. Response `kind=mutation` reports the actual outcome and current revision; identical content may return `outcome=unchanged`.
+- Dry-run validates local metadata but sends no request and does not disclose file content. It cannot prove host permissions, current format, revision or archive validity.
+
+## Replace a ZIP archive
+
+```bash
+ae-cli kb source replace --name "<name>" --scope personal --id <zip-source-id> \
+  --source-type zip --expected-revision <contentRevision> --file ./revised.zip
+```
+
+Sends multipart `POST .../sources/<id>/directory/previews` with `file`, `expectedRevision`, and `mode=archive`. Only `.zip` is accepted (case-insensitive); the host validates archive contents and limits. This prepares a candidate, not a source update. Whole-archive replacement can remove children missing from the uploaded archive.
+
+If `kind=preview` is returned, retain the `previewId` and `expectedRevision`. Read the preview pages and review additions, replacements and deletions before committing. If `kind=mutation` and `outcome=unchanged` is returned, there is nothing to commit. Do not invent a preview ID.
+
+## Restore one source or ZIP child
+
+```bash
+# Ordinary file: restores its draft immediately.
+ae-cli kb source restore --name "<name>" --scope personal --id <source-id> \
+  --source-type file --version <version-number> --expected-revision <contentRevision>
+
+# Whole ZIP: prepares a preview.
+ae-cli kb source restore --name "<name>" --scope personal --id <zip-source-id> \
+  --source-type zip --version <version-number> --expected-revision <contentRevision>
+
+# One historical ZIP file: prepares a preview; copy path from +version-tree.
+ae-cli kb source restore --name "<name>" --scope personal --id <zip-source-id> \
+  --source-type zip --version <version-number> --expected-revision <contentRevision> \
+  --path "guides/intro.md"
+```
+
+Sends `POST .../versions/<version>/sources/<id>/restore`. Ordinary files send only `expectedRevision`. ZIP sends `target=source`, or `target=file` plus `path`. ZIP directory-level restoration is not supported. A historical deleted ZIP child can be restored if its parent source still exists and the host accepts the candidate.
+
+This restores the selected source draft from immutable published bytes; it does not create a published version, restore an unpublished intermediate draft, or roll back other sources. Ordinary-file format compatibility and all historical snapshot checks remain enforced by the host.
+
+## Review, commit or cancel a ZIP preview
+
+```bash
+ae-cli kb source preview --name "<name>" --scope personal --id <zip-source-id> \
+  --preview-id <preview-id> --limit 100
+# Follow nextCursor, if present, with --cursor <nextCursor>.
+
+ae-cli kb source commit --name "<name>" --scope personal --id <zip-source-id> \
+  --preview-id <preview-id> --expected-revision <preview-expectedRevision>
+
+ae-cli kb source cancel --name "<name>" --scope personal --id <zip-source-id> \
+  --preview-id <preview-id>
+```
+
+- `preview`: `GET .../directory/previews/<previewId>`, cursor up to 4096 characters, limit 1–200. Reading a preview does not update the source.
+- `commit`: `POST .../directory/previews/<previewId>/commit` with `expectedRevision` and `confirmed=true`. This can delete files and is `high-risk-write`; obtain explicit user intent, then use `--yes` for authorized non-interactive execution. It updates the draft only.
+- `cancel`: `DELETE .../directory/previews/<previewId>`, expects HTTP 204 and returns `{previewId, cancelled:true}`. It discards an uncommitted candidate without changing the source. Also requires confirmation (`--yes` only after explicit authorization).
+- The candidate belongs to the caller and source, has an expiry, and can be replaced by a newer preparation. Never automatically prepare or confirm another candidate after expiry, a revision conflict or an uncertain result.
+- All five commands support `--dry-run`; it performs no server calls. `replace` includes local file metadata with redacted content; the others show the exact request.
+
+After a successful draft change, re-read `+list-sources`, then run `+compile` only when requested to publish it. Historical versions remain unchanged.
+
+## Errors and retry boundaries
+
+Keep the structured `error.code` and `hint`. `SOURCE_CONTENT_REVISION_CONFLICT`, format mismatch, missing/expired/replaced preview, permissions and damaged historical snapshot errors must not trigger delete/re-add or whole-KB rollback fallbacks. Commands do not automatically retry writes, including authentication failures. For `COMMIT_UNKNOWN`, `UNCERTAIN`, `REVIEW_REQUIRED`, or a lost response, inspect current source revision/state and the same candidate before deciding whether another write is safe; do not report failure as proof that nothing changed.
+
+## Transitional admission
+
+- Transition status: transitional
+- Owning module: te-claude External Knowledge Base source mutation/version APIs
+- Current transport: authenticated external REST through `kbApi` / `kbUpload`, using only the standard CLI token
+- Gateway target: TBD; no equivalent typed source replacement/restore capability is registered in the current backend implementation
+- Review after: 2026-12-15
+- Exit condition: migrate to equivalent Gateway capabilities while retaining typed file handling, revision guards, preview confirmation and stable outcomes, or remove redundant wrappers when dynamic invocation provides the same contract

package/skills/ae-kb/references/versions.md

@@ -0,0 +1,46 @@
+# Published knowledge-base versions
+
+Versions are immutable successful publications. No historical version is created until the first successful compile. Failed or cancelled compiles do not consume a version number. Existing `+compile`, `+status` and `+list-sources` responses pass through server version labels and draft state; `+index`, `+grep`, `+read` and `+ask` always address current content.
+
+When `+status` returns `wiki_review_required`, inspect `publicationReview.code`, report that administrator review is required, and stop ordinary compile polling. The active Run and write lock remain in place; do not cancel or force another compile. This also covers an interrupted publication after server restart.
+
+Discover exact names/scopes via `kb +list`, then inspect history:
+
+```bash
+ae-cli kb +versions --name handbook --scope company --limit 100
+ae-cli kb +version-show --name handbook --scope company --version 2
+ae-cli kb +version-sources --name handbook --scope company --version 2 --source-type zip
+ae-cli kb +version-diff --name handbook --scope company --from 1 --to 2
+ae-cli kb +version-tree --name handbook --scope company --version 2 --id <historical-source-id>
+ae-cli kb +version-read --name handbook --scope company --version 2 --id <historical-source-id> --path guides/start.md
+ae-cli kb +version-download --name handbook --scope company --version 2 --id <historical-file-source-id> --output ./manual.pdf
+```
+
+- `--version`, `--from` and `--to` use integer version numbers, without a `v` prefix. `+version-sources` IDs come from that historical snapshot; never substitute current source metadata.
+- `+versions`, `+version-sources` and `+version-tree` return one page. Use `--cursor` with the returned `nextCursor`, retaining the same target and filters. `--limit` is 1–200.
+- `--scope personal|company` is exact. Omitting it keeps the existing personal-then-company lookup. A missing target in an explicit scope never falls back.
+- `+version-tree/+version-read` accept ZIP or URL parent sources. Paths are source-relative and cannot contain absolute, parent or backslash segments. Text preview is bounded; supported PDF/images use a typed data URL. Unsupported or oversized files return metadata and `previewable: false`.
+- `+version-download` accepts ordinary file sources only and creates a new local file with exclusive creation. It never overwrites an existing file. Directory sources return `KB_VERSION_DIRECTORY_DOWNLOAD_UNSUPPORTED`; the CLI does not reconstruct ZIPs or export an entire version.
+
+## Rollback
+
+Copy `latestVersionId` and an earlier target version from `+versions`. Explicitly explain the effects before requesting rollback: target-source edits and deletion intents are replaced; target-external sources with a previous successful publication are soft-deleted; target-external unpublished additions and their files remain unchanged.
+
+```bash
+ae-cli kb +rollback --name handbook --scope company --version 1 --expected-latest-version-id <latestVersionId> --request-id <stable-request-id> --dry-run
+ae-cli kb +rollback --name handbook --scope company --version 1 --expected-latest-version-id <latestVersionId> --request-id <stable-request-id>
+ae-cli kb +rollback-status --name handbook --scope company --operation-id <operationId>
+```
+
+`+rollback` is `high-risk-write`; use `--yes` only for an already authorized exact operation. A target must be strictly older than the current version. Success creates a new version (for example v3 → v1 produces v4), retaining all previous snapshots.
+
+The caller must supply a stable ASCII `request-id` containing letters, digits, underscores or hyphens (1–191 characters). Reuse that exact ID, target and expected latest ID after a network interruption. The CLI does not generate another request ID, pick a different target, or retry a 409 automatically. A changed request under the same ID returns `KB_VERSION_OPERATION_REQUEST_CONFLICT`.
+
+`queued/running` means accepted but not completed. Query `+rollback-status` using the returned `operationId`; only `status: success` with `resultVersionId` proves publication. `failed` is a terminal result; a later intentional attempt needs a new request ID. When `running` includes `KB_PUBLICATION_COMMIT_UNKNOWN`, `KB_PUBLICATION_ROLLBACK_INCOMPLETE`, or `KB_PUBLICATION_REVIEW_REQUIRED`, tell the user administrator review is required and writes remain blocked. Stop normal progress/polling; do not start another rollback. Status remains readable.
+
+Transition status: transitional
+Owning module: te-claude External Knowledge Base Versions API
+Current transport: authenticated External REST via kbApi
+Gateway target: TBD (published history and persistent rollback operations)
+Review after: 2026-12-07
+Exit condition: migrate when equivalent immutable-history and idempotent rollback Gateway capabilities exist; retain stable request IDs, exact-scope targeting and local file safety.

package/skills/ae-kb-discovery/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-kb-discovery
 description: >
-  Discover which AE/TE/ThinkingEngine knowledge bases accessible to the current user are worth searching, and decide whether to search at all, through read-only operations. Use when the user explicitly asks to search knowledge bases, internal documentation, or company materials. Also use when a task requires internal facts or business context, including product design and rules, events, campaign or operations calendars, release and iteration records, workflows, policies, and terminology; use it as well when this context is needed to explain data analysis results, anomalies, or trends and form evidence-backed conclusions. Do not use if the user explicitly asks not to access knowledge bases. This skill covers discovery and candidate selection; run the actual `+index` / `+grep` / `+read` / `+ask` retrieval with the `ae-kb` skill.
+  Discover which AE (Agentic Engine) knowledge bases accessible to the current user are worth searching, and decide whether to search at all, through read-only operations. Use when the user explicitly asks to search knowledge bases, internal documentation, or company materials. Also use when a task requires internal facts or business context, including product design and rules, events, campaign or operations calendars, release and iteration records, workflows, policies, and terminology; use it as well when this context is needed to explain data analysis results, anomalies, or trends and form evidence-backed conclusions. Do not use if the user explicitly asks not to access knowledge bases. This skill covers discovery and candidate selection; run the actual `+index` / `+grep` / `+read` / `+ask` retrieval with the `ae-kb` skill.
 ---
 
 # Knowledge Base Discovery
@@ -55,6 +55,8 @@ Select one preferred knowledge base by default. When several candidates are high
 
 Once a preferred knowledge base is selected, hand off to the `ae-kb` skill and follow its `references/query-workflow.md` for the entire retrieval procedure — including when `+ask` is appropriate.
 
+If the retrieved source pages will guide project-scoped business data analysis, also read and follow the `ae-kb` skill's [`references/analysis-workflow.md`](../ae-kb/references/analysis-workflow.md) before running data queries. It converts exact saved-asset identity, definitions, parameters, time rules, conflicts, and decision boundaries into an execution contract; do not jump directly from a KB hit to an ad-hoc or SQL reconstruction.
+
 ## Assess Coverage
 
 - Full coverage: The page content read supports the key conclusions required for the information request or analysis.
@@ -65,6 +67,8 @@ A candidate returned by `+list`, navigation returned by `+index`, a successful c
 
 ## Use Knowledge Base Evidence in Analysis
 
+For project-scoped business data analysis, the `analysis-workflow.md` handoff above is mandatory after relevant source pages have been read. In particular, a KB statement that current values require live execution means attempting the matched saved asset first. If that attempt cannot produce a usable result, the workflow permits a traceable fallback to ordinary analysis.
+
 When using internal context to explain data analysis results, anomalies, or trends:
 
 1. First state what the analysis itself demonstrates, including the metric change, time range, affected entity, and magnitude.

package/skills/ae-metadata/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-metadata
 version: 1.0.1
-description: "AE/TE metadata capability-gateway CLI: metadata data-table management and property dimension-table binding. Metadata CLI routes through the analysis gateway. Input-file upload and event/property detail belong to ae-analysis."
+description: "AE metadata capability-gateway CLI: metadata data-table management and property dimension-table binding. Metadata CLI routes through the analysis gateway. Input-file upload and event/property detail belong to ae-analysis."
 ---
 
 # ae-metadata