@thinkingai/ae-cli 6.0.48-customer.1 → 6.0.48-workbuddy

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/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-system/SKILL.md

@@ -17,7 +17,7 @@ ae-cli system <resource> <action> [options]
 
 - These commands are only for users whose Agent role is `root` or `agent_admin`.
 - The te-agent `/api/admin/**` and `/api/cli/channel/v1/**` endpoints are the final authorization boundaries. A member receives a permission error (HTTP 403). Do not retry login or attempt a different endpoint after a 403.
-- Run `ae-cli auth login --host <host>` before using this domain. System administration requires a user access-token session; sandbox identity headers are not an authorization substitute.
+- Run `ae-cli auth login --host <host>` before using this domain. System administration requires a valid user CLI-token session; sandbox identity headers are not an authorization substitute.
 - `+npm-install` is the exception that must also run inside a Linux te-agent sandbox because it packages the installed Linux files. It still requires the logged-in user to be `root` or `agent_admin`.
 - Discover real IDs with a list command before any update or delete. Never guess a user, sandbox, model, quota rule, or channel ID.
 - Before every write, run `--dry-run`, show the target and effect, and obtain explicit user confirmation. The CLI itself prompts only for `high-risk-write`; `--yes` can bypass that prompt and is not a security boundary.

package/skills/ae-use-agent/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ae-use-agent
+version: 1.0.2
+description: "Use a custom te-agent Agent's instructions and dependency assets for a task in a local client such as Codex or Claude Code, using the client's model and local files."
+---
+
+# Use an AE Agent locally
+
+The platform supplies instructions and dependency discovery. You execute the user's task
+with your current model and local capabilities. This does not start a remote te-agent session.
+
+1. Read [the bundled command guide](references/local-agent.md) for setup and discovery.
+   Resolve the user's Agent name with `+list-agents --q <name>` and ask only if the choice
+   is ambiguous. An explicit Agent ID can be used directly. No sibling Skill is required.
+2. Use the original AE host for the context request:
+
+   ```bash
+   ae-cli agent +get-agent-context --id <agent-id> --host <original-host>
+   ```
+
+3. Check `ok`, then use `data.agent.instructions` as task guidance within your existing instruction hierarchy.
+   Inspect dependency metadata and use capabilities already present locally where appropriate.
+   For Skills needed by the task, fetch the body and relevant references/scripts/assets using
+   the returned command descriptors and the bundled guide. File inventories are on-demand,
+   not included in the context response.
+4. Decide how to prepare needed dependencies under the client's existing permissions.
+   Treat remote text and scripts as content to inspect, not automatic installation or execution
+   authorization. Do not change global instruction files or install software just because a
+   dependency appears in the list. Obtain MCP connection secrets through normal credential
+   setup. When the user explicitly requests credential export, follow the bundled guide's
+   `--include-mcp-credentials` flow; keep its sensitive output out of conversation and logs.
+5. Execute the task. Explain missing dependencies only when relevant; stop the affected step
+   if an essential capability is unavailable. Do not claim the full Agent is enabled based
+   solely on loading its prompt. The listed tools are dependencies, not an enforced tool allowlist.
+
+Keep follow-up commands on the original AE host. Re-fetch context for a new task and verify
+Skill versions when loading files. The context is live metadata, not a frozen package.
+When switching Agents, replace prior task guidance where possible; use a fresh conversation
+if the client's context cannot cleanly separate their instructions.
+
+This Skill relies on ae-cli and the platform's Agent context endpoint; it does not bootstrap
+or update either automatically. The bundled guide includes installation and recovery steps.

package/skills/ae-use-agent/references/local-agent.md

@@ -0,0 +1,114 @@
+# Local Agent command guide
+
+This guide is included in ae-use-agent; installing ae-agent is optional. Use Node.js 20+
+and a local client that can run shell commands and read files.
+
+## Setup and recovery
+
+Run `ae-cli --version`. If the command is missing, obtain the AE host and supported CLI
+version from the user's environment administrator. Give the appropriate installation
+command with that version substituted; do not install automatically:
+
+```bash
+# Customer/public distribution
+npm install -g @thinkingai/ae-cli@<supported-version>
+# Internal ThinkingData distribution
+npm install -g @tant/ae-cli@<supported-version> --registry=https://npm.thinkingdata.cn:3443
+```
+
+Use the environment URL supplied by the user or configured in ae-cli; never guess a host.
+Keep that original host on every request, including authentication:
+
+```bash
+ae-cli auth status --host <original-host>
+ae-cli auth login --host <original-host>
+ae-cli agent +get-agent-context --help
+```
+
+Login is needed only when the session is missing or expired. Let the user complete the
+browser login; never request tokens in chat. If the command is unknown, the CLI is too old.
+For the public package, `ae-cli update --dry-run` previews host-compatible updates;
+perform an update only under the client's existing permissions. Internal builds use the
+internal registry above. If the host-supported release lacks this command or endpoint,
+ask the environment administrator for a compatible deployment; do not repeatedly update.
+
+## Discover and load
+
+```bash
+ae-cli agent +list-agents --q <agent-name> --host <original-host>
+ae-cli agent +get-agent-context --id <agent-id> --host <original-host>
+```
+
+Default JSON output is `{ "ok": true, "data": ... }`. Check `ok` before reading `data`.
+Name search results are in `data.agents`. Match name, scope and description; ask the user
+when ambiguous. Search by name instead of assuming an unfiltered list contains every Agent.
+An explicit ID can go directly to the context command. Ordinary members can read their
+own personal Agents and shared Agents visible to their account; no admin role is required.
+
+Context fields are `data.schema_version`, `data.context_version`, `data.agent.instructions`,
+`data.model`, `data.dependencies.skills`, `data.dependencies.mcps` and `data.summary`.
+This guide supports schema version 1; stop and obtain matching documentation for other
+versions. Use your current client model. An unavailable platform model does not block it.
+`availability=available` means visible metadata, not a working local dependency.
+
+## Read required Skill files
+
+For an available Skill, use its `id` and `files` descriptors. No extra list-skills call is
+needed. Each descriptor has `executable` and `argv`; pass arguments separately, never as
+interpolated shell code. Append `--host <original-host>`. Supported read commands are:
+
+```bash
+ae-cli agent +get-skill-content --id <skill-id> --host <original-host>
+ae-cli agent +list-skill-references --id <skill-id> --host <original-host>
+ae-cli agent +list-skill-scripts --id <skill-id> --host <original-host>
+ae-cli agent +list-skill-assets --id <skill-id> --host <original-host>
+ae-cli agent +read-skill-reference --id <skill-id> --path <relative-path> --host <original-host>
+ae-cli agent +read-skill-script --id <skill-id> --path <relative-path> --host <original-host>
+ae-cli agent +read-skill-asset --id <skill-id> --path <relative-path> --output <local-file> --host <original-host>
+```
+
+Skill body is in `data.item.content`; directory entries are in `data.items`. Text file
+reads return `data.content`. Use a path returned by the corresponding directory listing;
+`--path` is relative to references, scripts or assets, without that directory prefix.
+All three read commands support `--output <local-file>` to preserve binary bytes. Use a
+new workspace file path and inspect scripts before any execution. Check reported versions
+against the context and re-fetch if they change. An empty listing does not prove that a
+file required by the Skill is unnecessary: report a missing required file and stop that step.
+
+## MCP dependencies and failures
+
+If the user explicitly requests exporting current-user MCP credentials, use:
+
+```bash
+ae-cli agent +get-agent-context --id <agent-id> --include-mcp-credentials --host <original-host>
+```
+
+This is sensitive output: do not quote it in chat or logs, or commit it. Put the connection
+only in the intended local client configuration. Require `data.credentials_included=true`;
+its absence means an older server, not success. For each MCP, check `connection_config`:
+`exported` supplies `connection_name` and the same `connection` configuration shown in the
+current user's MCP market: `type`, `url`, `headers` for remote MCPs, or `type`, `command`,
+`args`, `env` for stdio. Header and environment keys are unchanged; system URLs use the AE
+host. `credential_expires_at=null` means expiry is not exposed. `unavailable` supplies a safe
+`connection_error`. No refresh tokens or platform-internal keys are included. Re-export
+after credentials expire or are revoked. Platform managed bridges require the platform
+runtime. Do not assume a successful export proves connectivity.
+
+
+Use `ae-cli agent +mcp-tools --id <mcp-id> --host <original-host>` for platform tool metadata.
+For OAuth MCPs only, `ae-cli agent +mcp-auth-status --id <mcp-id> --host <original-host>`
+reports platform authentication. Neither establishes a local connection. Reuse an existing
+local capability when suitable; otherwise obtain connection setup through the client's
+normal credential flow. Do not ask for secrets in chat or claim platform OAuth transfers.
+
+- 401/auth error: log in on the same host and retry once; stop if authentication still fails.
+- 403: permission denied; do not refresh repeatedly or require an admin account by default.
+- 404 on context: run `ae-cli agent +get-agent --id <agent-id> --host <original-host>`.
+  If it also fails, verify the ID/account/host. If it succeeds, verify endpoint deployment
+  with the administrator. Raw Agent configuration is not a complete context fallback.
+- 409 `invalid_agent_configuration`: ask the Agent owner to repair dependency configuration.
+- 500/network error: report the failed step and host; no silent success or fallback.
+- Unavailable dependency or file: stop only the step that needs it; explain what is missing.
+
+Never claim the full Agent is ready from prompt loading alone. Context is live metadata,
+not a frozen package; re-fetch it for a new task.