@thinkingai/ae-cli 6.1.28 → 6.1.30

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

@@ -11,11 +11,12 @@ Everything below is server-side LLM-free.
 
 ## The loop
 
-This picks up **after** `ae-kb-discovery` has listed accessible knowledge bases
-and ranked candidates. Start here with a chosen candidate; scope every `+index`
-/ `+grep` / `+read` call to it with `--sources` / `--source`. If the candidate
-turns out not to cover the question, go back to `ae-kb-discovery` for the next
-candidate rather than searching everything blindly.
+This picks up **after** `ae-kb-discovery` has chosen a candidate from trusted active sources or `+list`.
+An explicit reference skips `+list` and stays within the referenced list, even when page evidence is insufficient.
+Preferred candidates are searched only when relevant; clearly unrelated candidates or evidence gaps can lead to `+list`.
+After `+list`, retrieve from at most three distinct newly discovered knowledge bases; count every new source in a multi-source `+ask` separately. Explicit references and preferred candidates do not consume that budget.
+Start here with a chosen candidate; scope every `+index` / `+grep` / `+read` call to it with `--sources` / `--source`. If the candidate turns out not to cover the question, go back to `ae-kb-discovery` for the next allowed candidate rather than searching everything blindly.
+When using `+ask` with explicit references or preferred candidates, always pass `--sources` containing only the relevant authorized sources from that active list; never omit it or include unrelated sources. For an explicit reference, insufficient evidence does not authorize expansion to another knowledge base.
 
 **Known-page fast path:** within the same host, identity, KB and published revision,
 reuse navigation and read evidence already obtained in this task. Copy exact
@@ -140,7 +141,20 @@ A revision or access-context change requires revalidation, not silent reuse.
 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`
+   section, plus the returned `readView.versionId/versionNumber` for snapshots).
+   For `version_pinned` results, describe consistency within that captured view.
+   Unchanged `versionId/readIdentity` proves that the reads used the same snapshot;
+   it does not establish whether a newer publication or rollback occurred outside
+   the execution. Claims about the latest formal version require separate current
+   publication evidence obtained through an authorized management workflow.
+   Preserve version identity with the reference; a fresh read of the same path is
+   not a historical citation read. For completed Ask sources with `reference`, use
+   `ae-cli kb +ask-status --execution-id <reference.executionId> --source-index <reference.sourceIndex>`
+   to reopen the original version under current permissions. An unversioned source
+   has no guaranteed historical snapshot; do not label its current content historical.
+   Historical source reads are rejected inside a required fixed-context execution;
+   never remove that context or fall back to an ordinary token to bypass its KB set.
+   If a gap remains, go back to step 2 with another set of `--paths`
    **copied** from current navigation, or return to discovery for the next candidate.
    For a knowledge-only question, missing evidence after the allowed search
    means "not covered by the knowledge base" — do not attach a confident fact

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

@@ -1,5 +1,6 @@
 ---
 name: ae-kb-discovery
+version: 1.0.0
 description: >
   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, or when ae-analysis sees an enabled KB auto-discovery company switch before choosing its query route. Use internal context 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.
 ---
@@ -32,9 +33,17 @@ Do not use this skill when:
 
 ## Discovery Workflow
 
-### 1. Get the List of Accessible Knowledge Bases
+### 1. Use Trusted Active Sources Before Discovery
 
-First, get the lightweight list of knowledge bases accessible to the current user:
+If the current turn's trusted system context supplies **explicitly referenced** knowledge bases with exact `scope` and display `name`, use only relevant references from that list. Hand them directly to `ae-kb` for scoped `+index` / `+grep` / `+read` retrieval; do not call `+list` or search an unreferenced knowledge base. If retrieved pages leave a gap, report it. A knowledge base named only in user text is not a trusted active reference.
+
+If trusted context instead supplies **preferred candidates**, compare their names, descriptions and bindings with the question. Search only relevant candidates first. If all are clearly unrelated, or their retrieved pages leave a gap, call `+list` for other accessible sources. Metadata never counts as answer evidence. Preferred candidates are not a search limit and do not consume the newly discovered source budget below.
+
+When no trusted active sources are supplied, discover accessible knowledge bases with `+list` as usual. Copy exact `scope` and display `name` from trusted context or `+list`; never derive a CLI `--sources` name from a slug alone.
+
+### 2. Get the List of Accessible Knowledge Bases When Needed
+
+When discovery is needed, get the lightweight list of knowledge bases accessible to the current user:
 
 ```bash
 ae-cli kb +list
@@ -44,7 +53,7 @@ Use the exact `scope` and knowledge base name returned by the command, together
 
 If `+list` is unavailable or fails, do not guess which knowledge bases exist. If the user explicitly requested a knowledge base search, explain that discovery cannot currently be completed. Otherwise, return to the original task and reassess the capabilities currently available.
 
-### 2. Rank Candidate Knowledge Bases
+### 3. Rank Candidate Knowledge Bases
 
 Rank candidates in this order:
 
@@ -54,9 +63,9 @@ Rank candidates in this order:
 
 Compare `targetId` with the corresponding current ID or code first. Use `targetName` only as a secondary signal when an ID or code is unavailable; do not replace a conflicting ID match with a name match. A candidate with no bindings or no current-context match remains eligible for semantic ranking. A binding to another project or space lowers implicit priority but does not exclude the candidate, and an explicit user choice still takes precedence.
 
-Select one preferred knowledge base by default. When several candidates are highly relevant, retain no more than three and try them one at a time in priority order. Do not read the indexes of all candidates in advance. A binding, name, description, tag, or language match only indicates that a knowledge base is worth searching; it does not prove a content match, grant access, or count as knowledge base evidence.
+Select one candidate to search at a time. After `+list`, retrieve from at most three distinct newly discovered knowledge bases in this task; stop when page evidence is sufficient. Every new source used by `+index`, `+grep`, `+read` or `+ask` counts once, including each source in a multi-source `+ask`. Explicit references and preferred candidates do not count toward this budget. Do not read the indexes of all candidates in advance. A binding, name, description, tag, or language match only indicates that a knowledge base is worth searching; it does not prove a content match, grant access, or count as knowledge base evidence.
 
-### 3. Hand Off to Retrieval
+### 4. Hand Off to Retrieval
 
 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.
 
@@ -98,7 +107,7 @@ When using internal context to explain data analysis results, anomalies, or tren
 When knowledge base evidence provides only partial coverage, is entirely absent, or retrieval fails:
 
 1. Stop repeating searches against the same candidate knowledge base.
-2. If ranked candidates remain, switch to the next candidate. Search no more than three knowledge bases in one task.
+2. If ranked candidates remain, switch to the next candidate. After `+list`, retrieve from no more than three distinct newly discovered knowledge bases; explicit references and preferred candidates do not consume that budget.
 3. When all candidates provide no coverage, return to the user's original request instead of remaining in the knowledge base retrieval subtask.
 4. Reassess the capabilities currently available and choose the next path that best serves the original task. Do not hard-code a fixed fallback.
 5. Retain verified background evidence when useful, but never attribute conclusions drawn from other sources to a knowledge base.

package/skills/ae-metadata/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-metadata
-version: 1.0.4
+version: 1.0.5
 description: "AE metadata capability-gateway CLI: list, inspect, create, update, delete and download metadata data tables; bind an existing dimension table to a property or create and bind a CSV dimension table. Local file upload and event/property discovery are separate prerequisite capabilities."
 ---
 
@@ -14,7 +14,7 @@ Use this skill for gateway-backed data-table and property dimension-table operat
 
 - Responsibilities: data-table management and dimension-table bindings through the commands below.
 - Inputs: verified project, table/property identifiers and operation-specific parameters; local CSV workflows need a valid uploaded input-file identifier and purpose.
-- Outputs: table/binding operation results, resource identifiers, or download run/artifact status. A submitted asynchronous download is not yet a completed file.
+- Outputs: table/binding operation results, resource identifiers, or download run/artifact status. Data-table get can include saved SQL definitions, parameters, and schedule configuration on supported servers; read its reference for availability and execution-value limits. A submitted asynchronous download is not yet a completed file.
 - Boundaries: local input-file upload, event/property detail and discovery, metric CRUD, virtual metadata, batch metadata, project configuration and tracking plans are separate capabilities.
 - Completion: the requested table or binding result is verified, or pending/blocked work and its remaining requirements are reported.
 

package/skills/ae-metadata/references/metadata_data_table_get.md

@@ -9,6 +9,8 @@ ae-cli metadata data-table get --project-id <project_id> --data-table-id <id>
 ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --include-preview true
 ```
 
+Use this command to inspect a metadata data table's columns, bindings, and saved SQL configuration. It requires the existing metadata view permission for the selected project. Reading a saved SQL definition does not authorize querying its upstream tables.
+
 ## Parameters
 
 | Parameter | Required | Description |
@@ -24,3 +26,36 @@ Each call to this capability's Gateway `execute` endpoint consumes one unit of t
 ```json
 { "project_id": 1, "data_table_id": 42, "include_preview": true }
 ```
+
+## Detail output
+
+Default JSON returns the complete server payload under `data`, including columns and bindings. `--include-preview true` additionally requests preview rows; it is not required to read saved SQL configuration.
+
+On servers that support SQL definition output, SQL tables add the following fields in both default and preview responses. Non-SQL tables omit them.
+
+| Field | Meaning |
+|---|---|
+| `create_qp` | Saved creation QP as a JSON object. |
+| `update_qp` | Saved update QP as a JSON object. |
+| `create_zone_offset` / `update_zone_offset` | Offset in hours used to parse SQL parameters for the corresponding QP. These are not the cron schedule timezone. |
+| `strategy` | Saved update strategy, such as `overwrite` or `insert`. |
+| `update_cron` | Saved update cron expression. Interpret it together with `update_conf_status`. |
+| `update_conf_status` | Schedule switch state: `NOT_SET`, `ENABLE`, or `DISABLE`. This is not task running status or evidence that an execution succeeded. |
+
+The wrapper fields use snake_case. QP objects retain the published model keys: SQL is at `taSqlVo.sql`, SQL parameters at `taSqlVo.sqlVoParams`, and view parameters at `taSqlView.sqlViewParams`. Preserve all nested keys and values, including extensions, when reading or reusing the definition. See [the SQL-write QP contract](metadata_data_table_sql_write.md#qp-contract-sqldatatabledef) before constructing a write.
+
+Parameter definitions and saved values describe configuration. Values containing expressions or placeholders may resolve differently during each execution. This response does not supply the actual resolved values of a specific execution; obtain execution evidence separately when those values are required.
+
+For SQL tables, unavailable configuration values are `null`; missing, invalid, or non-object historical QP values also produce `null` QP fields. Default get returns `null` configuration fields when the SQL definition record is missing. `--include-preview true` retains the server's existing preview behavior; missing definition records may still cause preview to fail on affected servers. A `null` QP does not establish that the SQL has no parameters. An empty parameter array is an explicit empty saved parameter list. Older servers may omit the new fields entirely, so missing fields alone do not prove that configuration is empty or that this server supports definition output. Inspect the selected server capability when availability matters.
+
+## Read the complete definition
+
+Use `--format json` to retain SQL configuration beside columns and bindings. Table format may render only the columns array. CLI `--jq` runs on the payload before envelope wrapping, so paths start at `.create_qp` or `.update_qp`, not `.data`.
+
+```bash
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --format json
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --jq '{create_qp, update_qp, create_zone_offset, update_zone_offset, strategy, update_cron, update_conf_status}'
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --jq '.update_qp.taSqlVo.sqlVoParams'
+```
+
+Choose the full response or a projection containing all required fields in one read. If the response is saved to a local file, inspect that file for additional paths instead of repeating the server request.