@thinkingai/ae-cli 6.0.53 → 6.0.55

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

@@ -1,10 +1,10 @@
 # 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.
+project-scoped business data analysis. The knowledge base supplies candidate
+assets, verified definitions, and decision boundaries. Check their coverage of
+the user's original question before choosing execution. Current values still
+require an `ae-analysis` data query; a related KB page is not task completion.
 
 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.
@@ -89,25 +89,33 @@ pages actually read:
 | 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:
+Classify each candidate's coverage before querying. These states classify the
+asset, not completion of the original task:
 
 - `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.
+- `partially_executable`: evidence covers only some subquestions; execute the
+  applicable parts and retain their results, then continue discovery for the
+  uncovered parts.
+- `semantic_only`: read evidence supplies useful events, properties, or
+  limitations, but the candidate's definition cannot produce the requested
+  measure, entity, or scope. Retain that evidence and continue ordinary analysis.
 - `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.
+  time rule, or decision boundary is missing or conflicting; do not execute
+  that unsupported definition. Continue discovery for the affected requirement
+  when an independently verified, authorized path remains possible.
 
 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.
+a technically valid query. Resolve missing evidence through the ordinary
+analysis path below. If a material business choice remains ambiguous, request
+that choice once; if clarification is forbidden, disclose the unresolved part
+instead of choosing silently. Do not ask the user to authorize continuation of
+the same read-only data request merely because the KB covers only part of it.
 
 ## Execute the exact saved-asset chain
 
-An exact asset identified by a source page takes priority over fuzzy search and
-ad-hoc analysis:
+An exact, semantically applicable 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`,
@@ -116,6 +124,10 @@ ad-hoc analysis:
 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.
+   Definition inspection that establishes an unsuitable saved asset does not
+   require a data query to prove the mismatch. Record the incompatible fields
+   and continue ordinary discovery; do not execute a known wrong definition
+   merely to satisfy an attempt-first rule.
 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
@@ -131,9 +143,9 @@ ad-hoc analysis:
    `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.
+7. Use the saved-asset discovery procedure from `ae-analysis` when the KB
+   provides no suitable executable identity or leaves requirements uncovered.
+   A discovered candidate still requires semantic coverage, 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
@@ -142,9 +154,11 @@ 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.
+an exact, semantically applicable saved asset must be attempted first. It does
+not require executing a related but unsuitable asset, nor authorize skipping
+saved-asset discovery directly to SQL. If inspection establishes a mismatch or
+execution cannot produce the requested result, follow the 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.
@@ -173,9 +187,10 @@ 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:
+These conditions require the state-specific handling and ordinary-analysis
+checks below; none alone establishes a verified ad-hoc or SQL definition:
 
-- The exact saved asset has not yet been attempted.
+- An applicable 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.
@@ -200,8 +215,8 @@ Handle these states without changing the contract:
   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.
+  independently to each failed or semantically uncovered 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`
@@ -222,8 +237,9 @@ Handle these states without changing the contract:
   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.
+- Fixed historical window: do not extrapolate its values to the requested
+  period. If the window cannot be overridden, inspect alternatives through
+  ordinary analysis instead of presenting that window as the requested result.
 - 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.
@@ -234,25 +250,34 @@ 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:
+The KB path is preferred, not exclusive. If definition inspection establishes
+that the KB-selected asset cannot cover the request, or a real execution attempt
+cannot produce the requested live result, continue through the ordinary
+`ae-analysis` "Existing business asset before ad-hoc" workflow. Preserve the KB
+evidence and already verified definitions; do not restart from zero:
 
 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
+2. Compare live definitions with the original request, including distinctions
+   such as creation versus creation-and-editing, user versus customer, and
+   event count versus distinct entity count. A title match is not enough.
+3. Follow [`metadata_resolution.md`](../../ae-analysis/references/metadata_resolution.md)
+   for uncovered definitions. Reuse verified KB and live-asset evidence; discover
+   only missing metadata, filters, dimensions, or scope. A missing descriptive
+   field does not invalidate independently supported action counts.
+4. If no saved definition matches, use authorized 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
+5. 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.
+time or breakdown, semantically unsuitable, missing requested fields or
+submetrics, or persistently fails after the documented correction or retry
+path. Technical success with a partial or wrong definition is also a coverage
+gap, not a reason to stop. 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`.
@@ -274,6 +299,18 @@ 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.
 
+## Check task completion
+
+Before answering, check each requirement of the original question against the
+actual definition and returned data. Finish when it is answered, or when bounded
+discovery establishes a concrete unavailable prerequisite, authorization
+boundary, or material choice requiring clarification. An asset state of
+`semantic_only`, `partially_executable`, or `blocked` is not by itself a terminal
+task state. Do not label creation-and-editing totals as pure creation, substitute
+another entity, or stop at a KB limitation while verified metadata supports a
+remaining authorized query. Keep genuine unknown fields unknown and label
+partial results explicitly; do not broaden an empty result merely to get rows.
+
 ## Answer with traceable boundaries
 
 Make these three layers distinguishable in the final answer:

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

@@ -1,9 +1,9 @@
 # ae-kb deterministic query workflow
 
 How to answer a knowledge question with the deterministic retrieval primitives
-(`+list` / `+index` / `+grep` / `+read`) instead of `+ask`. Follow this order;
-it is designed to reach the right section in a few calls and to avoid crawling a
-page line by line.
+(`+list` / `+index` / `+grep` / `+read`) instead of `+ask`. Choose the next step
+from the evidence already returned; these are branches, not commands to run on
+every page. Reach relevant evidence without crawling a page line by line.
 
 Use `+ask` when the question requires synthesizing across multiple pages or
 multi-hop reasoning; simple factual lookups are served by the steps below.
@@ -17,7 +17,17 @@ and ranked candidates. Start here with a chosen candidate; scope every `+index`
 turns out not to cover the question, go back to `ae-kb-discovery` for the next
 candidate rather than searching everything blindly.
 
-1. **Index the candidate.** Call `+index --sources` with the discovery pick.
+**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
+links returned by `+index`, `+grep` or `+read`; go to step 3 for a relevant page
+whose path is known. Do not guess filenames. Once a path is known,
+do not repeat indexing or broad directory searches to rediscover it;
+only read a domain, catalog or parent page when its additional
+context is needed to resolve scope, applicability or an uncovered requirement.
+A revision or access-context change requires revalidation, not silent reuse.
+
+1. **Index the candidate.** If no usable navigation is in context, 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. The root index routes at module level only; when a
@@ -30,32 +40,33 @@ candidate rather than searching everything blindly.
    **Done when:** you have the candidate's `index.md`, and a list of `wiki/...`
    links you can **copy** (0 items still counts as done).
 
-2. **Grep copied paths.** Copy 1–3 `wiki/...` entries from the index (a page
+2. **Grep copied paths.** When no sufficiently specific page link is known,
+   copy 1–3 `wiki/...` entries from the navigation already returned (a page
    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 **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.
+   with the terms in the returned navigation. If the first grep misses, rewrite
+   the query **once** using different terms from that navigation, still with
+   the same `--paths`. If the rewrite also misses, choose the likeliest linked
+   page and use step 3, or return to discovery. 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.
+   0 paths. Copied 0 paths → skip grep and go back to discovery rather than
+   constructing a path from a title.
 
    **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
+   sections you have actually read (step 4 distinguishes business analysis
+   from knowledge-only coverage). `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.
+   answer is not in the previews, locate the missing evidence on that single
+   page using step 3 rather than searching its entire directory again.
 
    Each page-group section preview carries its enclosing heading-section
    boundaries:
@@ -73,6 +84,15 @@ candidate rather than searching everything blindly.
 3. **Choose the section locator.** Pick one locator for the current target
    page:
 
+   - **Short or unknown-length linked page:** for a focused recall card or
+     asset-definition page, read once with
+     `--offset 1 --limit 200 --expand none`; an outline is not a prerequisite.
+     If a response already shows a longer page or a precise relevant section,
+     use the section branches below instead. Check the returned coverage:
+     `startLine: 1`, `endLine: totalLines`, and `truncated: false` prove a
+     complete page. If partial, locate only the missing evidence on the same page
+     with scoped grep or an outline; a bounded prefix is not proof of full
+     coverage. Do not reuse a range from another page.
    - **Section preview of a page group:** read the section range with
      `--offset sectionStartLine` and
      `--limit sectionEndLine - sectionStartLine + 1`. For narrow
@@ -80,10 +100,10 @@ candidate rather than searching everything blindly.
      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>"]'`
-     scoped to that page and use the new hit range.
+   - **Linked or related page needing section localization:** if the direct
+     read branch does not apply and you have concrete terms for that new page,
+     run `+grep --paths '["<new-page>"]'` scoped to that page and use the new
+     hit range. An explicit child link needs no catalog or directory lookup.
    - **No reliable range:** if the new page has no concrete grep terms, its
      grep misses, or headings are needed to choose the right section, call
      `+read --outline` for that page. It returns only the heading tree
@@ -102,30 +122,44 @@ candidate rather than searching everything blindly.
    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.
+   more call. A completed direct read in step 3 needs no additional read or
+   outline. Independent, already identified pages may be read in parallel;
+   follow only links needed for the question, not every related page.
 
    **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.
+   **Read coverage:** for knowledge-only answers, read relevant candidate pages
+   until every answered subquestion is backed by sections actually read — not
+   until a page "looks like the answer". For business data analysis, read the
+   relevant definitions and boundaries, then hand off verified coverage and
+   remaining gaps in step 5; live values do not need KB text as their source.
+   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, 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.
+   **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
+   from general knowledge, even with a disclaimer. For business data analysis,
+   this is a KB coverage gap, not completion of the original task. Preserve the
+   read KB evidence and continue through `ae-analysis` using
+   [`analysis-workflow.md`](analysis-workflow.md): verify suitable saved assets,
+   resolve only missing metadata, and execute an independently supported,
+   authorized query. Never attribute that live result to unread KB content.
+
+   Once relevant definitions, parameters and boundaries are covered, proceed
+   to the analysis handoff. Do not keep navigating to validate already verified
+   links or to seek live numbers in a semantic snapshot. Return to KB retrieval
+   only for a concrete unresolved semantic question.
 
    **Done when:** every answered subquestion is supported by read sections, or
-   the remaining gaps are explicitly reported as missing evidence.
+   the remaining knowledge gaps are explicitly reported as missing evidence.
+   A business data request still requires the analysis handoff and its task
+   completion check; routing or definition-only coverage is not a live answer.
 
 ## Anti-pattern: same-page offset crawling
 

package/skills/ae-kb/references/schema-import.md

@@ -5,7 +5,7 @@
 | Command | Required flags | Purpose |
 | --- | --- | --- |
 | `+schema-download` | `--name --output` | Download original formal bytes |
-| `+schema-import` | `--name --file --request-id` | Upload Markdown; automatically validate |
+| `+schema-import` | `--name --file --request-id` | Upload Markdown with basic checks; AI validation is explicit |
 | `+schema-import-list` | `--name` | List pending candidates; `--cursor/--limit` |
 | `+schema-import-status` | `--import-id` | Read report, revision and receipt |
 | `+schema-import-content` | `--import-id` | Read full candidate; `--target/--output` |
@@ -14,7 +14,7 @@
 | `+schema-import-validate` | `--import-id --revision --request-id --hash` | Explicit validation |
 | `+schema-import-optimize` | `--import-id --revision --request-id --hash` | One repair and independent revalidation; repeat `--issue-id` |
 | `+schema-import-reject` | `--import-id --revision --request-id` | Restore latest repair input; no recursive undo |
-| `+schema-import-apply` | `--import-id --revision --request-id --hash --report-id` and exactly one of `--schema-hash/--schema-absent` | Explicit formal replacement |
+| `+schema-import-apply` | `--import-id --revision --request-id --hash` and exactly one of `--schema-hash/--schema-absent` | Explicit formal replacement; optional `--report-id` |
 | `+schema-import-abandon` | `--import-id --revision --request-id` | Abandon draft; high-risk write |
 
 Use `--scope personal|company` for name lookup. All subsequent operations use the returned import ID, never resolve a name again. Upload may explicitly replace one pending import with `--replaces-import-id/--replaced-revision`; otherwise it creates an additional draft.
@@ -23,7 +23,9 @@ Upload, validation, optimization and status support `--wait --timeout <seconds>`
 
 Before applying, read `+schema-import-diff --baseline current-schema`, the entire candidate and advisories. Use the returned formal hash. `KB_SCHEMA_IMPORT_BASE_CHANGED` requires reviewing a fresh diff and explicit confirmation; never refresh the hash and automatically replay apply. Revision/request conflicts preserve your file. `settlementPending/recoveryRequired` means an administrator must inspect the operation; it is not an applied success. Applying does not compile or create a published version. Existing Wiki content needs a later compilation.
 
-Candidates are shared between Web and CLI for the same user. Closing either client does not abandon saved work. Save makes a new human baseline only when bytes change. Failed/unavailable validation never permits apply. No automatic model retry loop exists.
+Normal initialization can apply a reviewed, release-accepted preset without a new AI report. Existing valid formal rules are reused on refresh without upload, application, generation or AI validation. Legacy callers may still pass `--report-id`; it is omitted from JSON when absent. Servers with an older mandatory-report contract reject this fast path; surface that incompatibility rather than invent a report or silently generate rules.
+
+Candidates are shared between Web and CLI for the same user. Closing either client does not abandon saved work. Save makes a new human baseline only when bytes change. Application admission follows the current server's basic checks and `canApply` response. AI validation is explicit and optional; it is recommended once when authoring a reusable preset. Keep its complete passing report and exact content hash before releasing that preset. No automatic model retry loop exists.
 
 ## Transitional transport
 

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

@@ -11,6 +11,8 @@ These commands require a host exposing the External KB source-mutation and previ
 
 All new commands use `kb source <action>`. Existing `+source-put`, `+source-rm` and whole-KB `+rollback` keep their original behavior.
 
+For ordinary `.md`, `.markdown` and `.txt` sources, [the text workflow](text-sources.md) also supports `replace --text` or `--stdin` using the complete text API and the same required revision. `--file` continues to use the original multipart replacement contract below.
+
 ## Replace a file source
 
 ```bash
@@ -88,8 +90,8 @@ Keep the structured `error.code` and `hint`. `SOURCE_CONTENT_REVISION_CONFLICT`,
 ## 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
+- Owning module: te-claude knowledge-base source management
+- Current transport: External Knowledge Base REST API
+- Gateway target: TBD
+- Review after: 2026-11-12
 - 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/text-sources.md

@@ -0,0 +1,53 @@
+# Ordinary text sources
+
+Use these commands for ordinary `.md`, `.markdown` and `.txt` sources, including existing uploads. Text is a content filter on `sourceType=file`, not a new source type. ZIP children and URL collection output use their original commands.
+
+## Create
+
+Copy the exact knowledge base name and `personal` or `company` scope from `kb +list`. Choose exactly one input:
+
+```bash
+ae-cli kb source create-text --name "Handbook" --scope company --text "Release notes" --dry-run
+ae-cli kb source create-text --name "Handbook" --scope company --title "Release notes" --file ./notes.md
+cat ./notes.txt | ae-cli kb source create-text --name "Handbook" --scope company --stdin
+```
+
+Each request creates one independent Markdown file source. `--file` reads one UTF-8 `.md`, `.markdown` or `.txt` file (case-insensitive); the server generates a title from the content unless `--title` is supplied, adds `.md`, and resolves duplicate names with a sequence number. To retain a local filename or upload other formats, use `kb +add`. The response `item` contains the final display name, stable ID, current `contentRevision` and pending compilation state.
+
+Transport: `POST /agent/api/external/knowledge-bases/sources/text`, JSON `{name, scope, content, title?, inputMethod:"text_input"}`.
+
+## Read and edit the same source
+
+```bash
+ae-cli kb +list-sources --name "Handbook" --scope company --content-type text
+ae-cli kb source read-text --name "Handbook" --scope company --id <source-id>
+ae-cli kb source read-text --name "Handbook" --scope company --id <source-id> --out ./original.md
+ae-cli kb source replace --name "Handbook" --scope company --id <source-id> \
+  --source-type file --expected-revision <contentRevision> --text "Revised notes"
+cat ./revised.md | ae-cli kb source replace --name "Handbook" --scope company --id <source-id> \
+  --source-type file --expected-revision <contentRevision> --stdin
+```
+
+`read-text` returns complete `{item, content, contentFormat}` in the standard JSON envelope. `item.contentRevision` corresponds to these exact bytes; `contentFormat` is `markdown` or `text`. `--out` exclusively creates a new local file and returns only `{item, contentFormat, out}`. Existing files and symlinks are never overwritten. A read does not establish write permission.
+
+Text replacement sends `PUT .../sources/<id>/text?name=...&scope=...` with `{content, expectedRevision, inputMethod:"text_input"}`. It preserves the existing source ID, name and format. The original `replace --file` path continues to send multipart data to `/raw` or prepare a ZIP preview, as described in [source mutations](source-mutations.md).
+
+Read after saving and compare the complete bytes and revision. An unchanged save reports `outcome=unchanged` without increasing the revision; a real change reports the actual mutation result and new revision. `SOURCE_CONTENT_REVISION_CONFLICT` exits nonzero: retain local input, read current content and explicitly resolve the conflict. The CLI never obtains a new revision or retries a write automatically.
+
+## Encoding, limits and outcomes
+
+- File and stdin input must be strict UTF-8. BOM, LF/CRLF/CR, mixed line endings and the presence or absence of a trailing newline are preserved. Quotes, backticks and Unicode remain business data. `--stdin` is explicit and requires a pipe; missing input never waits for interactive text.
+- Empty or whitespace-only text is rejected. The limit is 50 MiB (52,428,800 UTF-8 bytes), including BOM and newlines. Exactly the limit is allowed. JSON escaping overhead is separate; valid content is never truncated.
+- Creation and replacement are ordinary `write` commands without a second confirmation. A `--dry-run` validates local input and previews the request with content redacted, sends no business request, and cannot prove host permissions or a current revision.
+- Text flags are sensitive. Text input, full read responses and server error details are excluded from command and HTTP diagnostics; structured errors retain the server code and safe recovery guidance. Explicit `read-text` JSON or `--out` content is the requested business result.
+- An unsupported host fails explicitly; the CLI does not fall back to upload or delete/re-add. If the outcome is unknown, inspect `+list-sources` and read the source before deciding on another request; retrying creation can create another independent source.
+- Saving does not compile or publish. After reviewing all changes, explicitly use `kb +compile` and inspect `kb +status`. Failed compilation preserves prior published knowledge. Deletion uses existing `+rm-source` confirmation and publication semantics.
+
+## Admission record
+
+- Transition status: transitional
+- Owning module: te-claude knowledge-base source management
+- Current transport: External Knowledge Base REST API
+- Gateway target: TBD
+- Review after: 2026-11-12
+- Exit condition: when equivalent text and revision capabilities enter the Gateway, migrate the typed commands to the shared transport where their file, stdin, revision and output handling adds value, while preserving released command compatibility.

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

@@ -72,7 +72,7 @@ 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.
+For project-scoped business data analysis, the `analysis-workflow.md` handoff above is mandatory after relevant source pages have been read. Attempt an exact, semantically applicable saved asset first. If definition inspection proves it unsuitable, or execution cannot produce the requested result, continue ordinary analysis for the uncovered requirements without discarding verified KB evidence. A KB statement that current values require execution does not require running a known mismatching asset or asking the user to repeat the data request.
 
 When using internal context to explain data analysis results, anomalies, or trends:
 

package/skills/ae-team/SKILL.md

@@ -16,20 +16,22 @@ AE CLI (`ae-cli`) is the command-line tool for the AE (Agentic Engine) analysis
 
 Global parameters:
 
-| Parameter | Description |
-|---|---|
-| `--format <json\|table>` | Output format. Default is JSON. |
-| `--jq <expr>` | jq filter expression for JSON output. |
-| `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli team +<command> --host <url>`. |
-| `--yes` | Skip confirmation for `high-risk-write` (delete) operations. |
-| `--dry-run` | Show request details without executing. |
+| Parameter                | Description                                                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--format <json\|table>` | Output format. Default is JSON.                                                                                                             |
+| `--jq <expr>`            | jq filter expression for JSON output.                                                                                                       |
+| `--host <url>`           | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli team +<command> --host <url>`. |
+| `--yes`                  | Skip confirmation for `high-risk-write` (delete) operations.                                                                                |
+| `--dry-run`              | Show request details without executing.                                                                                                     |
 
 Output and errors:
+
 - Successful commands return machine-readable JSON by default. Envelope may include optional `_notice.host_compat`.
 - Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
 - **CRITICAL — Host compat (do this first):** If stderr or `_notice.host_compat` has a version warning, open the user reply with ⚠️ and **quote `npm i -g` / `npx skills add` (or update-cluster) lines verbatim**, then list projects/results. Never omit when summarizing. Soft tip; `ok: true` may still include the notice.
 
 Safety constraints:
+
 - Read commands (`+list`, `+list-templates`, `+list-projects`, `+run-result`, `+run-artifacts`, `+ai-generate`) can execute directly once required IDs are known.
 - Ordinary `write` commands require explicit user intent but no CLI confirmation. Only `high-risk-write` commands use the confirmation gate and may receive `--yes` after explicit user authorization.
 - Never invent team IDs, run IDs, `agentId` values, `mcpServerIds`, `skillIds`, `knowledgeBaseIds`, project IDs, or any resource identifiers. Discover them with list commands or accept them from the user.
@@ -81,16 +83,16 @@ ae-cli team +run-start --help
 
 ## TeamRun Status Reference
 
-| Status | Description |
-|---|---|
-| `pending` | Queued, waiting to start |
-| `running` | Actively executing |
-| `waiting_user` | Paused — `+run-watch` exits with code 2; read `pendingQuestion` from stdout, present to user, then call `+run-reply` |
-| `waiting_approval` | Paused — waiting for approval |
-| `paused` | Manually paused |
-| `completed` | Finished successfully |
-| `failed` | Execution failed |
-| `cancelled` | Cancelled by user |
+| Status             | Description                                                                                                          |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `pending`          | Queued, waiting to start                                                                                             |
+| `running`          | Actively executing                                                                                                   |
+| `waiting_user`     | Paused — `+run-watch` exits with code 2; read `pendingQuestion` from stdout, present to user, then call `+run-reply` |
+| `waiting_approval` | Paused — waiting for approval                                                                                        |
+| `paused`           | Manually paused                                                                                                      |
+| `completed`        | Finished successfully                                                                                                |
+| `failed`           | Execution failed                                                                                                     |
+| `cancelled`        | Cancelled by user                                                                                                    |
 
 Terminal statuses: `completed`, `failed`, `cancelled`. Poll `+run-result` until one of these is reached.
 
@@ -163,3 +165,7 @@ ae-cli team +create --name "我的分析团队" --config '<template_config>'
 ```bash
 ae-cli team --help
 ```
+
+## Automation lifecycle
+
+For Agent or team automation schedules, immediate execution, stop, retry, deletion, history and read-only results, use [ae-automation](../ae-automation/SKILL.md). Existing Agent automation aliases remain compatible.