ae-kb

Cross-skill collaboration

When remaining work is outside this skill's scope, or a necessary prerequisite needs another capability, follow the collaboration protocol. Choose from the skills available in this run by capability, preserve verified context, and continue the remaining task. Reuse this protocol if already loaded.

AE CLI (ae-cli) knowledge base commands are invoked through:

ae-cli kb +<command> [options]
ae-cli kb source <create-text|read-text|replace|restore|preview|commit|cancel|check-updates|check-url-updates> [options]

Global Rules

• Use this skill for AE knowledge base tasks: create, import a compiled snapshot, query, ask with LLM, list accessible knowledge bases and their sources, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
• Searching a knowledge base for an answer is the most common task. If that is what you are doing, go straight to Explore Knowledge Base Pages and read references/query-workflow.md first — it is the retrieval procedure. The other commands below are for managing knowledge bases, not answering from them.
• When retrieved pages will guide project-scoped business data analysis, read and follow references/analysis-workflow.md before running any data query. This is mandatory after a KB hit identifies an asset, definition, parameter, time rule, conflict, or decision boundary. Verify semantic coverage before execution; a related page or KB limitation is not task completion. Continue ordinary analysis for uncovered requirements without jumping directly to unverified ad-hoc analysis or SQL.
• Read operations can run directly after required inputs are known. Write operations require explicit user intent. Only high-risk-write commands require the CLI confirmation prompt; use --yes after explicit authorization.
• Prefer --dry-run before destructive or broad writes when the user has not already validated the target.
• Do not invent knowledge base names, scopes, source IDs, source display names, or JSON payloads. Ask the user or query known context when values are missing.
• When building a --sources ref (or +read --source), copy the exact scope and name from +list output — run ae-cli kb +list first when the scope of a named knowledge base is unknown.
• JSON flags must be valid JSON strings, usually wrapped in single quotes in shell commands.
• Successful commands return JSON by default. Use --format table only when a table is easier for a human to scan. Envelope may include optional _notice.host_compat.
• --host <url> overrides the active AE host. It is available on every command and may be placed after the subcommand, e.g. ae-cli kb +<command> --host <url>.
• CRITICAL — Host compat (do this first): After each ae-cli run, check stderr and _notice.host_compat. If either is present, open the user reply with a short ⚠️ version warning and quote the npm i -g / npx skills add (or update-cluster) lines verbatim, then present the business result. Soft tip; ok: true can still carry the notice.
• Retrieval (+index / +grep / +read) is deterministic and server-side LLM-free; use it for simple factual lookups. Use +ask when the question requires synthesizing across multiple pages or multi-hop reasoning.

Commands

Compilation Usage Logs

ae-cli kb usage list --name handbook --scope personal --page 1 --page-size 20
ae-cli kb usage list --name handbook --jq '.items | map({createdAt, taskType, status, durationMs})' --format table

• Returns { items, total, page, pageSize }. --page defaults to 1; --page-size defaults to 20 and accepts 1–100. Fetch each page explicitly.
• durationMs is the usage log's finishedAt - startedAt, in milliseconds. A missing or invalid timestamp yields null; zero remains zero. Failed records can have duration even when usageAvailable is false.
• Historical missing durations are not reconstructed from compile runs. startedAt and finishedAt are ISO timestamps or null.
• Requires the same Schema-read permission as the Web compilation usage list. Imported snapshots do not expose usage. --scope selects exactly personal or company; omission keeps the existing personal-then-company lookup.
• --dry-run previews the read without sending a request. Default output retains numeric/null values; use the existing --jq and --format table options for a compact table.

Transition status: transitional Owning module: te-claude External Knowledge Base Usage API Current transport: authenticated External REST via kbApi Gateway target: TBD (compilation usage list) Review after: 2026-12-14 Exit condition: migrate to the Gateway equivalent when available, preserving typed pagination and duration/null semantics.

Published Version History

Use the nine version commands described in references/versions.md to inspect immutable published history, compare source changes, and explicitly roll back an earlier version as a new publication. These commands manage history; +index/+grep/+read/+ask continue to use current published content.

Source Draft Replacement and Restoration

Use references/source-mutations.md for file/ZIP source replacement and restoration. These new commands use kb source <action>; +rollback remains a whole-KB publication operation.

Require exact --name, --scope, current --id, and a current --expected-revision for mutations. File replacements keep the original format but allow different filenames. ZIP requires .zip. URL/Feishu and deleted parent sources are not supported. Updates affect the draft only; publication still requires compilation. ZIP previews must not be auto-committed. Do not retry uncertain writes.

ZIP Directory Sources

Use +add --files '["./sources.zip"]' to upload one ZIP as one editable parent source, preserving its internal hierarchy. Archive validation and limits are enforced by the server. This is different from +import, which creates a read-only compiled snapshot. Passing a local directory to +add still uploads only its immediate supported files; it does not recursively package that directory.

Discover the exact parent ID with +list-sources. ZIP rows include fileCount, sizeBytes, contentRevision, and updateStatus.

ae-cli kb +source-ls --name handbook --id <source-id> --path "" --limit 100
ae-cli kb +source-ls --name handbook --id <source-id> --path "guides" --cursor <nextCursor>
ae-cli kb +source-read --name handbook --id <source-id> --path "guides/intro.md"
ae-cli kb +source-read --name handbook --id <source-id> --path "images/chart.png" --output ./chart.png
ae-cli kb +source-read --name handbook --id <source-id> --path "images/chart.png" --encoding base64
ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./new.md --action add --expected-revision 7 --dry-run
ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./new.md --action add --expected-revision 7
ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./revised.md --action replace --expected-revision 8
ae-cli kb +source-rm --name handbook --id <source-id> --path "guides/new.md" --expected-revision 9
ae-cli kb +source-rm --name handbook --id <source-id> --path "guides/obsolete" --recursive --expected-revision 10
ae-cli kb +compile --name handbook --mode incremental

• Copy the source ID, paths and revision from current discovery. Names resolve personal then company, following the existing External API; no scope override is available on these commands.
• --path is relative to the ZIP root, not a local filesystem or raw/zip/... path. Root listing uses an empty path. Nonempty paths cannot be absolute or contain empty, dot, parent or backslash segments.
• Listing returns one page; continue using nextCursor and the same path. On a revision change, restart discovery before writing.
• +source-read reads source bytes; +read reads compiled Wiki pages. Default UTF-8 output fails on invalid UTF-8. Base64 preserves binary data. --output creates a new local file and refuses to overwrite an existing file.
• +source-put accepts one file up to 50 MB. Default --action add rejects an existing path; --action replace explicitly authorizes overwriting an existing child. There is no silent upsert. Dry-run shows metadata and redacts file content.
• --expected-revision is mandatory for writes. A 409 conflict is returned with its server error code; the command never refreshes and retries the write automatically.
• +source-rm keeps the parent source. Nonempty directory removal requires --recursive; deletion follows the CLI confirmation gate. Use --yes only when automated deletion of the exact target is already authorized. +rm-source --id deletes the entire parent.
• A mutation marks the parent changed but does not start compilation or regenerate Schema. Run incremental compilation explicitly; wait for successful publication before the next test stage.
• +status is the existing aggregate status query; it is not a per-run event or ZIP Diff reader. Do not interpret its compilation submission response as successful publication.
• No Gateway equivalent is registered in the current KB implementation. These commands reuse the typed External source APIs.

Transition status: transitional Owning module: te-claude External Knowledge Base Sources API Current transport: authenticated External REST via kbApi and multipart kbUpload. Gateway target: TBD (ZIP source directory and raw-file capabilities) Review after: 2026-12-06 Exit condition: migrate when equivalent typed Gateway file, directory and revision-aware mutation capabilities exist; retain CLI file handling and explicit mutation semantics.

Common Workflows

Create a Knowledge Base

Use +new with name. --scope is optional and defaults to company; valid scopes are personal and company.

ae-cli kb +new \
  --scope company \
  --name engineering-handbook \
  --description "Engineering handbook" \
  --tags '["engineering","handbook"]'

Optional fields:

• --scope: scope, defaults to company.
• --description: description, up to 200 characters.
• --tags: JSON array, max 2 tags, each up to 15 characters.
• --project-id: optional project ID to bind.
• --project-name: optional project display name.

Import a Compiled Snapshot

Use +import only for a ZIP whose root contains index.md and at least one wiki/**/*.md page. The server validates all archive paths, limits, UTF-8 text, and Wiki links.

ae-cli kb +import \
  --file ./knowledge-base.zip \
  --name "Imported handbook" \
  --description "Compiled documentation snapshot" \
  --tags '["docs","handbook"]'

# The submission returns requestId + queued. Query one snapshot later:
ae-cli kb +import-status --request-id <requestId>

• The result is always a personal read-only snapshot; there is no --scope, --force, or replace option.

• Imported snapshots support list, Index/Wiki reading, grep/read, Ask, and deletion. They do not expose source, Schema, usage, compile, member, settings, ownership-transfer, or company-publish operations.

• The ZIP is limited to 50 MB and supports Markdown text only. Local images, attachments, other binaries, broken Wiki links, and ambiguous Wiki links are rejected by the server.

• Submission returns {requestId, status: "queued"} immediately. It does not wait for ZIP validation or publication.

• +import-status returns one of queued, running, succeeded, or failed; success includes knowledgeBaseId, and failure includes a stable error code/message.

• If a requestId was returned, query it before retrying. If no request ID was received, run ae-cli kb +list before retrying the same name. A repeated same-name import is rejected.

• Transition status: transitional

• Owning module: te-claude External Knowledge Base Import API

• Current transport: authenticated KB external REST through kbUpload for submission and kbApi for status lookup.

• Gateway target: TBD (kb.snapshot.import proposed)

• Review after: 2026-12-01

• Exit condition: migrate to a typed Gateway capability when the equivalent multipart import capability is available, or remove this command if dynamic Gateway execution provides the same file-handling and output contract.

Upload Files or Directories

Use +add when sources are local files, local directories, or pages that should be fetched and converted to markdown before upload.

ae-cli kb +add \
  --name engineering-handbook \
  --scope company \
  --files '["./README.md","./docs","https://example.com/guide"]'

Input rules:

• --files must be a JSON array of strings.
• Local directory reading is non-recursive.
• URL entries must start with http:// or https://.
• Supported extensions include markdown/text, office documents, PDFs, spreadsheets, presentations, and common images. Local files are uploaded as multipart file blobs; HTTP(S) pages are fetched and converted to markdown before upload.
• Duplicate filenames are automatically suffixed as name-1.ext, name-2.ext, etc.

Add a URL Source

Use +url when adding one URL source and optionally passing a display name or parsing instruction.

ae-cli kb +url \
  --name engineering-handbook \
  --scope company \
  --url https://example.com/guide \
  --display-name guide \
  --parse-instruction "Keep headings and code blocks"

--url must be http(s). The server detects the platform from the URL automatically: URLs on a *.feishu.cn or *.larksuite.com subdomain are parsed with the Feishu pipeline (including sub-documents, using the server's own Feishu parsing instruction — --parse-instruction is ignored for them); all other URLs are fetched as regular web pages.

Generate Schema and Compile

Generate the schema first when the knowledge base needs a compile schema.

ae-cli kb +schema --name engineering-handbook --scope company

Use --force only when +status reports schema_generating and the user explicitly wants to replace the current generation attempt. The replacement may consume additional tokens.

Schema and Compile accept the same optional model reference. Prefer the model record id returned by ae-cli agent +list-models (Model.id). Historical modelId and the unambiguous modelId::scope form remain compatible. A model displayName is presentation text, not a stable reference.

To add one-time guidance for this generation without changing stored knowledge base metadata, pass --custom-instructions. The server trims the value, treats whitespace-only input as absent, and accepts up to 10,000 Unicode characters. Do not include secrets or credentials.

ae-cli kb +schema \
  --name engineering-handbook \
  --scope company \
  --model <model-ref> \
  --custom-instructions "Prioritize troubleshooting workflows and preserve command examples"

Use --dry-run to inspect the request body before sending it. While generation is running, a request without --force is idempotent only when it supplies no new model or effective custom instructions; otherwise it fails with KB_SCHEMA_GENERATION_IN_PROGRESS. With --force, the selected model and custom instructions apply to the replacement attempt. Invalid text fails with KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID.

Compile after sources and schema are ready:

ae-cli kb +compile --name engineering-handbook --scope company --mode incremental --model <model-ref>

Valid compile modes are incremental and full; default is incremental.

Check Knowledge Base Status

Use +status to inspect the current status of a knowledge base.

ae-cli kb +status --name engineering-handbook --scope company

Ask Knowledge (LLM)

Use +ask when the question requires synthesizing across multiple pages or multi-hop reasoning — a server-side agent runs the full retrieval loop and returns a synthesized answer with its source paths. Prefer +index -> +grep -> +read when deterministic retrieval is enough.

The +ask command uses asynchronous submit/poll: by default, it automatically polls for completion (every 5s, up to 10 minutes) and prints the final answer with its execution ID, sources, model usage, tool call count, and model ID.

# Default: submit and poll for completion
ae-cli kb +ask \
  --question "How do we troubleshoot payment alerts?" \
  --sources '[{"scope":"company","name":"engineering-handbook"}]' \
  --model-id claude-sonnet-4-6 \
  --locale zh

# Submit only, return executionId immediately (for batch processing)
ae-cli kb +ask --question "..." --no-wait

# Query execution status later
ae-cli kb +ask-status --execution-id <id>

• --question, alias -q: required natural-language question (1-2000 characters).
• --sources: optional JSON array of knowledge base refs. Omit to search all accessible knowledge bases.
• --model-id: optional LLM model ID. Omit to use the platform default.
• --locale: optional locale: zh, en, ja, or ko.
• --no-wait: optional boolean flag. Return immediately after submission with {executionId, status}, without polling.
• Failure handling: If execution fails, the command exits non-zero and prints the unified JSON error envelope on stderr: {"ok":false,"error":{"type":"api","code":"<server-code>","message":"..."}}. Stable server codes are model_unavailable, sandbox_unavailable, agent_skill_unavailable, dispatch_auth_unavailable, provider_failed, retrieval_error, timeout, and process_restart.

List Accessible Knowledge Bases

Use +list when you only need accessible knowledge base metadata without loading index.md navigation maps. Omit --build-status to default to compiled; pass idle / pending / compiling / compiled / failed to filter by a specific status (system knowledge bases are always listed regardless of status):

ae-cli kb +list
ae-cli kb +list --locale zh
ae-cli kb +list --build-status compiled

Explore Knowledge Base Pages

Use the deterministic retrieval primitives when an agent needs to explore knowledge base content like a code repository. These endpoints do not call an LLM on the server side.

Before running a real query, read references/query-workflow.md — it selects the next useful retrieval step without crawling. It covers candidate indexing, copied-path grep, direct bounded reads of linked short pages, same-page read windows, linked-page re-grep when needed, optional outline-derived ranges, and coverage assessment. This section below is the per-command reference the workflow draws on.

Start with +list or +index to discover accessible knowledge bases. Use +index when you also need navigation maps:

ae-cli kb +list

ae-cli kb +index \
  --sources '[{"scope":"company","name":"engineering-handbook"}]'

Then use +grep to locate likely pages:

ae-cli kb +grep \
  --query "sandbox configuration" \
  --sources '[{"scope":"company","name":"engineering-handbook"}]' \
  --paths '["wiki/sandbox.md"]' \
  --top-k 10

The response is a page-level results array: each entry is one page with its full hitCount, a pageKind (content or catalog), up to 4 sections previews (breadcrumb, sectionStartLine/sectionEndLine, text preview), and moreSections. Use hitCount and the previews to decide which pages to read; pageKind: "catalog" marks a module directory page — treat its entries as detail-page navigation, not as an answer source. Read the section range with --offset sectionStartLine / --limit sectionEndLine - sectionStartLine + 1; when moreSections > 0 and the answer is not in the previews, re-grep that single page to see all its hits.

Use +read --outline when the current target page has no reliable grep range and headings are needed to choose a section:

ae-cli kb +read \
  --source '{"scope":"company","name":"engineering-handbook"}' \
  --path "wiki/sandbox.md" \
  --outline

Then use +read to open the selected window, using a page-group section boundary or two adjacent outline headings:

ae-cli kb +read \
  --source '{"scope":"company","name":"engineering-handbook"}' \
  --path "wiki/sandbox.md" \
  --offset 42 \
  --limit 60 \
  --expand block

Create, read or edit text sources

Read the text source workflow when collecting text, reading full editable source content, or updating an ordinary .md, .markdown or .txt source. It covers explicit scope, UTF-8/BOM/newline preservation, exclusive local output, revision conflicts, redacted dry-run and manual compilation. Web and CLI maintain the same source ID.

List Sources

List sources first to discover the stable identifier for the intended source:

ae-cli kb +list-sources --name engineering-handbook --scope company

Copy the exact id from the response into +rm-source. Do not guess a source ID from a local filename, URL, display name, or an older upload response.

• Transition status: transitional
• Owning module: te-claude knowledge-base source management
• Current transport: External Knowledge Base REST API
• Gateway target: TBD
• Review after: 2026-11-12
• Exit condition: migrate to a typed Gateway capability when an equivalent source-list capability is available, or remove this command if dynamic Gateway execution provides the same discoverability and safe output contract.

Remove One Source

Use +rm-source --id with the exact ID returned by the current +list-sources response. This is a high-risk-write; keep the interactive confirmation unless the user has explicitly authorized --yes.

ae-cli kb +rm-source \
  --name engineering-handbook \
  --scope company \
  --id cm-source-id

--display-name is retained for legacy compatibility only when a stable source ID is unavailable:

ae-cli kb +rm-source \
  --name engineering-handbook \
  --display-name kb-1780046712-guide.md

If the user only gives a loose source name, do not guess a source ID. Run +list-sources, identify the intended row from returned metadata, and ask only when multiple rows remain ambiguous.

Delete a Knowledge Base

Use +remove for deleting the entire knowledge base. Confirm the target name with the user if there is any ambiguity.

ae-cli kb +remove --name engineering-handbook --scope company

Command Reference

+ask

ae-cli kb +ask --question "<question>" [--sources '[{"scope":"company","name":"kb-name"}]'] [--model-id claude-sonnet-4-6] [--locale zh|en|ja|ko] [--no-wait]

• --question, alias -q: required natural-language question (1-2000 characters).
• --sources: optional JSON array of knowledge base refs. Omit to search all accessible knowledge bases.
• --model-id: optional LLM model ID. Omit to use the platform default.
• --locale: optional locale: zh, en, ja, or ko.
• --no-wait: optional. Return immediately with {executionId, status} instead of polling.
• When to use: multi-page synthesis or multi-hop questions. For simple factual lookups, prefer +index / +grep / +read.
• Output: By default, polls and returns {executionId, answer, sources, modelUsage, toolCallCount, modelId}. With --no-wait, returns {executionId, status} immediately. On failure, exits non-zero with the unified stderr envelope containing error.type="api", the server error.code (model_unavailable, sandbox_unavailable, agent_skill_unavailable, dispatch_auth_unavailable, provider_failed, retrieval_error, timeout, or process_restart), and error.message.

+ask-status

ae-cli kb +ask-status --execution-id <id>

• --execution-id: required. The execution ID returned by +ask submission.
• Output: Returns one successful CLI envelope snapshot. For a failed execution, the stable server code remains at data.error.code: {"ok":true,"data":{"executionId":"...","status":"failed","error":{"code":"retrieval_error","message":"..."}}}. Does not poll.

+list

ae-cli kb +list [--build-status compiled] [--locale zh|en|ja|ko]

• --build-status: optional; one of idle / pending / compiling / compiled / failed. Omit to default to compiled (system knowledge bases are always listed regardless of status).
• --locale: optional locale: zh, en, ja, or ko.
• Response items include buildStatus.

+index

ae-cli kb +index [--sources '[{"scope":"company","name":"kb-name"}]'] [--locale zh|en|ja|ko]

• --sources: optional JSON array of knowledge base refs. Omit to list all accessible knowledge bases.
• --locale: optional locale: zh, en, ja, or ko.

+grep

ae-cli kb +grep --query "<keywords>" --sources '[{"scope":"company","name":"kb-name"}]' --paths '["wiki/page.md"]' [--top-k 10] [--locale zh|en|ja|ko]

• --query, alias -q: required keywords to search.
• --sources: required JSON array of knowledge base refs.
• --paths: required JSON array of wiki pages or subdirectories copied from current +index, +grep or +read navigation links. Do not invent paths. A single page is still an array, e.g. ["wiki/sandbox.md"]. Distinct from +read --path (one string).
• --top-k: optional max number of hits, 1-50, default 10.
• --locale: optional locale: zh, en, ja, or ko.
• Each page entry in results carries hitCount (full match count), pageKind, and sections previews with sectionStartLine / sectionEndLine — use the section range as the +read window.

+read

ae-cli kb +read --source '{"scope":"company","name":"kb-name"}' --path "index.md" [--offset 1] [--limit 200] [--expand block|none] [--outline] [--locale zh|en|ja|ko]

• --source: required JSON object pointing to exactly one knowledge base.
• --path: required page path relative to the knowledge base root, such as index.md or wiki/concepts/data-model.md.
• --offset: optional 1-based integer start line.
• --limit: optional max line count, 1-2000.
• --expand: optional Markdown block expansion mode. block lets the server include a complete Markdown block outside the requested line window; none keeps the exact offset/limit window. Omit it to use the server default, block.
• --outline: optional. Return only the whole-page heading tree ({level, heading, line}) with empty content, independent of --offset / --limit. Use it on long pages to choose which section to read.
• --locale: optional locale: zh, en, ja, or ko.

+new

ae-cli kb +new --name "<name>" [--scope personal|company] [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."] [--project-name "..."]

+add

ae-cli kb +add --name "<name>" --files '["./a.md","./docs","https://example.com/page"]' [--scope personal|company]

+import

ae-cli kb +import --file "./knowledge-base.zip" --name "<name>" [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."]

• --file: required local .zip file.
• --name: required personal knowledge-base name, up to 30 characters.
• --description: optional, up to 200 characters.
• --tags: optional JSON array, max 2 unique tags, each up to 15 characters.
• --project-id: optional project binding.
• Scope and terminal build state are generated by the server and cannot be supplied by the client.
• Output: {requestId, status: "queued"}. Use +import-status; the command does not poll.

+import-status

ae-cli kb +import-status --request-id <requestId>

• --request-id: required ID returned by +import.
• Output: {requestId, status, knowledgeBaseId?, errorCode?, errorMessage?}.
• Returns a single snapshot and does not poll. A failed import is returned as status: "failed" with its stable error code/message; an unknown or inaccessible request exits non-zero.

+url

ae-cli kb +url --name "<name>" --url "https://example.com/page" [--scope personal|company] [--display-name "..."] [--parse-instruction "..."]

+schema

ae-cli kb +schema --name "<name>" [--scope personal|company] [--force] [--model <model-ref>] [--custom-instructions "<one-time guidance>"]

• --custom-instructions: Optional per-run schema-generation guidance. It is not persisted; whitespace-only input is omitted. The server allows at most 10,000 Unicode characters and rejects disallowed control characters. Do not include secrets or credentials.
• --force: Replace the current attempt only when schema generation is already running and the user explicitly requests the replacement. The selected model and custom instructions apply to the new attempt, which may consume additional tokens.
• --dry-run: Shows the same customInstructions request field that execution will send.
• --model: Optional stable model reference. Prefer Model.id from ae-cli agent +list-models; historical modelId and modelId::scope remain compatible.
• --scope: Optional exact knowledge-base scope. Omit it to retain the legacy personal-to-company lookup order.
• Errors: KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID means the field failed validation. KB_SCHEMA_GENERATION_IN_PROGRESS means generation is active and a request without --force supplied a new model or effective custom instructions.

+compile

ae-cli kb +compile --name "<name>" [--scope personal|company] [--mode incremental|full] [--model <model-ref>]

+status

ae-cli kb +status --name "<name>" [--scope personal|company]

+list-sources

ae-cli kb +list-sources --name "<name>" [--scope personal|company] [--content-type all|text]

• --name: required knowledge base name.
• --content-type: defaults to all; text selects ordinary .md, .markdown and .txt sources (case-insensitive), excluding URL and ZIP sources. Scope remains optional for this list command.
• Output: items contains effective sources with stable id. pendingDeletions contains soft-deleted sources still included in the current successful version. deletionMaintenance is separate and may report already-published deletions awaiting cleanup. Paths, hashes, credentials, and source content are not returned.
• Check deletionProjection.state and its baseline before interpreting deletion lists. ready with pendingDeletions: [] means no pending deletion at that baseline. changing, review_required, or unavailable with pendingDeletions: null means undetermined; display the reasonCode, never turn null into an empty list. Legacy libraries without a verifiable complete publication manifest return unavailable until a real version is published.
• A rollback creates a new current version. An older deletion receipt cannot override membership in that version. A later source deletion needs publication again.
• Copy the exact id from the current response before deleting a source; never guess it.

+rm-source

ae-cli kb +rm-source --name "<name>" --id "<source-id>" [--scope personal|company]

• --id: preferred stable source identifier copied from +list-sources.
• --display-name: legacy compatibility selector used only when an ID is unavailable.
• If both are supplied, --id wins. The command removes one source only.

+remove

ae-cli kb +remove --name "<name>" [--scope personal|company]

Import and replace compilation rules

Use schema import commands to upload, validate, edit, repair, review and apply a Markdown compilation rule candidate. These actions do not generate rules from sources or import a compiled snapshot.

Check a Feishu source for updates

ae-cli kb source check-updates --name "Engineering Handbook" --id "<source-id>" --scope company --dry-run
ae-cli kb source check-updates --name "Engineering Handbook" --id "<source-id>" --scope company

Copy the ID from kb +list-sources. Requires source write permission. Only compiled, non-deleted Feishu URL sources are eligible. The API uses the same detector as the scheduled task, including existing pending-change skips and source-owner sandbox credentials. It never starts compilation or clears pending changes.

The synchronous response contains sourceId, scanned, updated, failed, urlChangeState, and updateStatus. scanned counts candidates, not completed content comparisons; updated counts newly marked sources. Zero updates can mean unchanged content, an already pending change, unavailable old raw, or a concurrent state change. It must not be reported as proof that all content is identical. Failed checks return a non-2xx response and a CLI error. A timeout does not prove completion or cancellation; read kb +list-sources before deciding whether to retry.

Transport: POST /agent/api/external/knowledge-bases/sources/check-updates, body {name, sourceId, scope?}. --dry-run only previews the request and does not authenticate or check remote permissions.

Admission record: source check-updates

• Classification: Transitional (no Gateway equivalent for this new detector trigger).
• Owning module: te-claude knowledge-base source management.
• Current transport: KB external REST through kbApi and CLI token.
• Gateway target: TBD; reuse an equivalent source update-check capability when available.
• Review after: 2026-10-16.
• Exit condition: once the Gateway exposes equivalent authorization and detector semantics, migrate the typed command to L2 or use L3 if it adds no value.

Submit an ordinary URL update check

ae-cli kb source check-url-updates --name "Engineering Handbook" --id "<source-id>" --scope company --dry-run
ae-cli kb source check-url-updates --name "Engineering Handbook" --id "<source-id>" --scope company

Only existing sourceType=url, platform=custom, compiled sources without pending updates qualify. The request is rejected while Wiki/Schema compilation or input preparation is active. Success returns {accepted:true,sourceId} and only means accepted. It has no final counts, task ID, checking state, wait mode or completion query. Read kb +list-sources for update markers; unchanged state cannot distinguish execution, no change, failure or a discarded result. When marked changed, explicitly run the existing incremental compile. Feishu continues to use synchronous source check-updates.

Transport: POST /agent/api/external/knowledge-bases/sources/check-url-updates, body {name,sourceId,scope?}. Dry-run previews without sending a request. Submission errors preserve the server error code, details and nonzero exit.

Admission record: source check-url-updates

• Transition status: transitional (this new KB external capability has no Gateway equivalent).
• Owning module: te-claude knowledge-base source management.
• Current transport: KB external REST through kbApi and CLI token.
• Gateway target: TBD; reuse an equivalent asynchronous ordinary URL source-check capability.
• Review after: 2026-10-24.
• Exit condition: when the Gateway provides equivalent authorization and asynchronous submission semantics, migrate to L2 if typed flags add value, otherwise use L3.