/uipath-knowledge-bundles

name: uipath-knowledge-bundles
description: "Read and publish UiPath knowledge bundles via `uip or kb` — versioned sets of markdown documents (Open Knowledge Format) that live in an Orchestrator folder and that an agent reads from as context. Download a version into a local workspace, read one file or a whole version, publish a directory as version 1, and ask what a local copy needs to match a published version. PREVIEW: these commands exist only on a prerelease `uip` build and only on tenants with the knowledge-bundles feature enabled — Step 0 below is how you find out, and a miss means stopping, not improvising. Changing published content goes through a reviewed change proposal: `uip or kb change-proposal` opens one from an edited workspace, carries the review comments, and merges it to publish the next version. For Orchestrator assets, queues, buckets, jobs→uipath-platform. For context grounding / semantic search indexes→uipath-platform. For `uip solution` lifecycle→uipath-solution."
when_to_use: "User says 'knowledge bundle', 'knowledge bundles', 'OKF', 'Open Knowledge Format', 'download the knowledge bundle', 'publish docs to Orchestrator', 'what version of the bundle', 'bundle manifest', 'change proposal on a bundle', 'open a change proposal', 'merge the proposal', 'review the bundle change', 'comment on the proposal', 'give the agent its knowledge', 'where does the agent read its documentation from'. Also when a task needs the documents an agent reads as context and those documents are said to live in Orchestrator rather than in the repo."
allowed-tools: Bash, Read, Write, Glob, Grep
user-invocable: true

UiPath Knowledge Bundles — `uip or kb`

A knowledge bundle is a folder-scoped Orchestrator entity holding a versioned tree of markdown documents. Versions are immutable and numbered (v1, v2, …); reads accept a number or the literal `latest`. Content is addressed by hash, so transfers move only what changed.

Critical Rules

1. **Preflight before anything else.** `uip or kb --help` decides whether this surface exists at all. `unknown command` means a stable build and no amount of retrying changes it; a command that runs but is refused by the platform means the tenant's feature flag is off. Both are stop conditions — say so and stop, never substitute bucket, asset or context-grounding commands. 2. **Every command needs a folder.** `--folder-path <path>` or `--folder-key <guid>` on all of them. There is no tenant-wide listing to fall back on. 3. **Bundle keys come from `list`, never from you.** Same for proposal ids, which come from `change-proposal list`. Do not construct, guess, or carry one over from another folder. 4. **`publish` and `create --input` only ever make version 1.** Every later version comes from merging a change proposal. A 409 means the bundle already has content — never delete and re-create to get around it, that destroys the version history and the review record. 5. **A 403 or a feature refusal is not a login problem.** Do not "fix" it by re-running `uip login`; only an administrator can change it. 6. **`diff` before `merge`.** A merge publishes a version that cannot be edited afterwards. 7. **Inside a workspace, omit the key and the folder** — but read the stderr line that says which workspace answered, and pass `--folder-path` explicitly after switching tenants. 8. **Paths are bundle-relative and cannot climb.** A `--path` or `--artifact` containing a `.` or `..` segment is refused before any request is sent; pass the path as the manifest lists it.

Step 0: Preflight — is this surface available?

Run once per session:

uip or kb --help

• **Succeeds** → continue.
• **`unknown command`** → the installed `uip` is a stable build. These commands register only on a prerelease build (`preview` / `dev` channel). Tell the user that plainly and stop — do not substitute bucket, asset or context-grounding commands, and do not guess an older command name.
• **A command runs but the platform refuses it** → the tenant does not have the knowledge-bundles feature enabled. Say so and stop; only an administrator can change it. A `403`/feature failure is not a login problem — never "fix" it by re-running `uip login`.

Every command is folder-scoped

Bundles live in a folder and are not addressable without one. Pass `--folder-path <path>` (or `--folder-key <guid>`) on **every** command — unless you are working inside a downloaded workspace, which answers for both (below).

`uip or folders list --all` finds one — its flags are its own (`--all`, `--path <prefix>`, `--name`), not `kb list`'s `--search`. Pass its `Path` field to `--folder-path` (a top-level folder is just `Shared`, a nested one `Shared/Finance`) or its `Key` to `--folder-key` — `Name` is the display name and is not what either option wants.

Bundles are identified by a GUID (`Key`). Get it from `list`, never construct it.

On `share`, the scope (`--folder-path`) is the folder that already holds the bundle; `--add-folders` and `--remove-folders` name the folders being changed, and both apply in one call.

`--search` matches the bundle's **`Name` only** — not its description, and not the `title` inside its documents. A bundle named `ops-handbook-7` can hold a document titled "Contoso Operations Handbook", so searching what the user called it often returns an empty `Data: []` that reads like "no such bundle". When a descriptive search comes up empty, list the folder unfiltered and look at the names and descriptions; page with `--limit` / `--offset` rather than trusting the first page. `versions`, `history`, `change-proposal list` and `change-proposal list-comments` take the same two options; for those three the window is cut from the whole answer rather than asked of the server, so `--offset` counts rows either way — and on those four `Pagination.Total` is exact and `HasMore` is false on the last window. On `kb list` the server reports no total, so `HasMore` there is a guess from a full pa