@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-ixp/references/label-documents-guide.md

@@ -0,0 +1,207 @@
+# Label Documents Guide
+
+Reusable workflow for labelling documents in an IXP project. Used by:
+
+- [Project Setup](project-setup-guide.md) — initial labelling after creating a project
+- [Improve Prompts](improve-prompts-guide.md) — reviewing predictions during optimization
+
+Claude acts as a **reviewer** — IXP generates predictions, Claude validates them field-by-field against the document. Only fields that are correct get confirmed. Fields that are wrong are left unannotated. Fields where the prediction found the right location but the value is OCR-mangled get corrected.
+
+## Step 1 — Get Documents and Taxonomy
+
+```bash
+mkdir -p /tmp/ixp/<project-name>/{docs,text,taxonomies,prompts}
+uip ixp documents list <project-name> --output json
+uip ixp projects get-taxonomy <project-name> --output json
+```
+
+Save the taxonomy to `/tmp/ixp/<project-name>/taxonomies/v1.json` (increment the version on each re-fetch).
+
+From the taxonomy (raw snake_case: field groups/fields under `Data.dataset.label_groups`, types under `Data.dataset.entity_defs`), review the field groups and field types so you understand what each predicted field represents.
+
+## Step 2 — Process Each Document
+
+For each document from the list, process one at a time: get predictions, download image/text, review, confirm.
+
+### 2a. Get predictions for this document
+
+```bash
+uip ixp labellings get-predictions <project-name> <document-id> --output json
+```
+
+This returns `Data: { ProjectName, TotalDocuments, DocumentsWithPredictions, Predictions[] }`. Each `Predictions[]` entry is `{ DocumentId, Labels[] }` (for a single-document call, `Predictions[0]`). Each label is `{ Name, Occurrence, Fields[] }`, and each field has `FieldId`, `FieldName`, `FormattedValue`. `Occurrence` is the explicit 0-based index used for `--occurrence`/`--updates`.
+
+### 2b. Download the document file
+
+- **If the file already exists** in `/tmp/ixp/<project-name>/docs/` from a previous session, reuse it — do NOT re-download.
+- **Otherwise, download:**
+
+```bash
+uip ixp documents download <project-name> <document-id> -o /tmp/ixp/<project-name>/docs/<document-id> --output json
+```
+
+Use the document ID as the filename. Pass `-o` **without an extension** — the CLI detects the actual format (PDF, PNG, JPG, …) from the file content and appends the correct extension. Read the resolved `Path` from the response and use that for the next step. Files persist across sessions — check for existing files before downloading.
+
+### 2c. Review predictions field-by-field
+
+Use the **Read tool** to view the document file (read the whole document in one call, no `pages` parameter — a full Read returns text + image natively for digital and scanned PDF/PNG/JPG docs; no PDF tools to install), then review each predicted field against the document:
+
+1. **Look at the document** to understand the layout and where field values appear.
+2. **For each predicted field**, assign one of four verdicts:
+   - **CONFIRMED** — the predicted value matches what is in the document. Minor OCR-level differences (capitalization, whitespace) are acceptable.
+   - **CORRECTED** — **OCR-mangled values only.** The prediction found the right field in the right location, the bytes-on-page are correct, but the text was garbled in transcription (e.g., `MSIÓÓÓ601020/` instead of `MSI0601020`, `lNGRAM` instead of `INGRAM`). The reference is correct, only the literal characters need fixing. Do NOT use CORRECTED for booleans that came back with the wrong answer, inferred/computed values that came back wrong, or any case where IXP picked the wrong source on the page — those are NOT CONFIRMED.
+   - **MISSING** — IXP predicted **no value** (empty `FormattedValue`) AND the field is genuinely absent from the document. Both conditions must hold. If IXP predicted a value but the field isn't actually in the document, that's NOT CONFIRMED, not MISSING — Critical Rule 12 forbids overriding a non-empty prediction with "missing".
+   - **NOT CONFIRMED** — the prediction is wrong for any reason other than OCR mangling. Covers: wrong literal value on the right field, wrong-source extraction, hallucinated value, boolean came back with the wrong answer, inferred/computed value came back wrong, predicted a value the document doesn't contain. Left unannotated. Do NOT try to "fix" these with `--corrections` — `--corrections` is OCR-only (see Critical Rule 8). Improve the prompt instead.
+3. **Report your verdict for every field.** Print a table per document:
+
+```text
+Document: <document-id>
+
+Field                    | Verdict       | Reason
+-------------------------|---------------|-----------------------------------------------
+Invoice Number           | CORRECTED     | OCR mangled "MSIÓÓÓ601020/" → "MSI0601020", top-right of page 1
+Invoice Date             | CONFIRMED     | Predicted "2018-02-28" matches document
+Vendor Address           | NOT CONFIRMED | Predicted "123 Main St" but actual is "456 Oak Ave", top-left of page 1
+Has Signature            | NOT CONFIRMED | Predicted "false" but signature visible bottom-right (boolean came back wrong — NOT CORRECTED)
+Total After Tax          | NOT CONFIRMED | Predicted "$1100.00" but Subtotal+Tax = "$1210.00" (inferred value wrong — NOT CORRECTED)
+Terms of Payment         | MISSING       | IXP predicted no value AND field not visible in document
+Discount                 | MISSING       | IXP predicted no value AND no discount section on the page
+Line Items > Description | CONFIRMED     | Predicted "Widget A" matches row 1 in the table
+```
+
+**Repeatable field groups produce one extraction per row.** `get-predictions` returns one label per row, each with an explicit 0-based `Occurrence` — `Line Items` on a multi-line invoice has N entries indexed 0..N-1 (read `Occurrence` directly; it equals document order). When validation differs across rows, give per-occurrence verdicts:
+
+```text
+Line Items > Description (occurrence 0) | CONFIRMED     | "Widget A" matches line 1
+Line Items > Description (occurrence 1) | CONFIRMED     | "Widget B" matches line 2
+Line Items > Description (occurrence 3) | NOT CONFIRMED | Predicted "Widget D" but line 4 shows "Widget Z"
+```
+
+For **CORRECTED** fields: state the mangled predicted value, the corrected value, and where it appears. The mistake must be at the character level — same field, same location, garbled bytes.
+For **MISSING** fields: state that the prediction was empty AND describe how you verified the field is absent (e.g., "no payment-terms section anywhere in the document").
+For **NOT CONFIRMED** fields: state the predicted value, the actual value (if visible) and location. Includes any non-OCR mistake — wrong source, wrong boolean, wrong inferred value, hallucination, value the document doesn't contain. **Do NOT use `--corrections` to fix these** — improve the field's prompt instructions instead.
+
+4. **Build two lists from the table:**
+   - **Submit field IDs** — all CONFIRMED + CORRECTED + MISSING fields (one combined list — the CLI applies the right semantic per field based on IXP's prediction)
+   - **Corrections JSON** — only CORRECTED fields: `[{"field_id":"...","value":"corrected text"}]`
+
+### 2d. Confirm and correct
+
+Submit confirmed, corrected, and missing fields for this document — all in one `confirm` call.
+
+**If there are corrections:**
+
+```bash
+uip ixp labellings confirm <project-name> <document-id> \
+  --fields "<all_submitted_ids>" \
+  --corrections '[{"field_id":"<id>","value":"<corrected_value>"}]' \
+  --output json
+```
+
+The `--fields` list includes CONFIRMED, CORRECTED, and MISSING field IDs together — the CLI writes the right annotation per field based on IXP's prediction (content → confirm, content with override → correct, empty → missing marker). The `--corrections` JSON overrides the predicted value for corrected fields while keeping their document references (bounding boxes).
+
+**If there are no corrections (all approved fields are exact matches):**
+
+```bash
+uip ixp labellings confirm <project-name> <document-id> \
+  --fields "<field_id_1>,<field_id_2>,<field_id_3>" --output json
+```
+
+If ALL predicted fields for a document are correct with no corrections needed, you can omit `--fields` to confirm every predicted field on **that one document** in a single call:
+
+```bash
+uip ixp labellings confirm <project-name> <document-id> --output json
+```
+
+This per-document form is fine **once you've reviewed the document and every field is correct** (2c). What you must NOT do is run `confirm` **without a `<document-id>`** — that confirms every document in the project at once, bypassing the per-document review loop. Confirming unreviewed predictions bakes wrong values into the labels, and because F1 compares predictions against those labels, **the metric reports 1.00 even when the confirmed values are wrong**. F1 alone is never evidence the values are correct.
+
+**If there are missing fields**, include their IDs in the same `--fields` list as the CONFIRMED and CORRECTED IDs. The `confirm` command applies one uniform rule per listed field: if IXP predicted content, the content is confirmed; if IXP predicted nothing, a missing marker is written. No separate call needed.
+
+```bash
+uip ixp labellings confirm <project-name> <document-id> \
+  --fields "<confirmed_id>,<corrected_id>,<missing_id_1>,<missing_id_2>" \
+  --corrections '[{"field_id":"<corrected_id>","value":"<corrected_value>"}]' \
+  --output json
+```
+
+**Only include a field in the `--fields` list for the MISSING case when IXP itself predicted nothing for it** — see Critical Rule 12. If IXP predicted a wrong value, omit the field entirely (don't list it).
+
+Use `labellings mark-missing <project-name> <document-id> --fields <ids>` to record a genuinely-missing field. It marks the listed fields directly, so it also handles the case where `confirm --fields` no-ops — a field with a prior annotation that the current prediction no longer includes (e.g., model behavior changed after a retrain), which `confirm` can't reach. Either records the missing marker; only do so when `get-predictions` shows IXP predicted no value for the field — never to override a wrong prediction.
+
+**Per-occurrence confirm for repeatable groups.** When a repeatable group's verdicts differ across occurrences (some lines correct, some not), `confirm --fields a7c3e9105f2b4d86` is the wrong shape — it confirms `a7c3e9105f2b4d86` in **every** occurrence, including the wrong ones. Target each correct occurrence by index:
+
+```bash
+# All predicted fields in occurrence 0:
+uip ixp labellings confirm <project-name> <document-id> \
+  --group "Line Items" --occurrence 0 --output json
+
+# Just Quantity in occurrence 2:
+uip ixp labellings confirm <project-name> <document-id> \
+  --group "Line Items" --occurrence 2 --fields c4e1907a3b8f25d6 --output json
+```
+
+Occurrences not targeted carry forward whatever annotation they already had (so wrong predictions in untouched occurrences stay unannotated). For batching many occurrences in one call, use `--updates '[…]'` — see [CLI Reference § Labellings](cli-reference.md#labellings). See Critical Rule 13.
+
+**Per-occurrence unconfirm.** `unconfirm` takes the same `--group`/`--occurrence`/`--updates` flags, so a wrong confirmation can be rolled back at the same granularity. `unconfirm --fields a7c3e9105f2b4d86` (no `--group`) removes `a7c3e9105f2b4d86` from **every** occurrence; scope it to one line with `--group "Line Items" --occurrence 2`, or several at once with `--group "Line Items" --updates '[…]'`, using the same 0-based indices. Without `--fields`, every annotated field in the targeted occurrence(s) is rolled back; with `--fields`, only those. See Critical Rule 14.
+
+```bash
+# Roll back only occurrence 2 of Line Items (every field in that line):
+uip ixp labellings unconfirm <project-name> <document-id> \
+  --group "Line Items" --occurrence 2 --output json
+```
+
+### 2e. Move to the next document
+
+Repeat steps 2a–2d for all documents in the list.
+
+### Removing a document from the project
+
+If a document is unusable (wrong document type, corrupted, duplicate), delete it instead of confirming or skipping:
+
+```bash
+uip ixp documents delete <project-name> <document-id> -y --output json
+```
+
+`-y/--yes` is required (the CLI never prompts). `<document-id>` is the `DocumentId` from `documents list` (e.g., `3453547f3538febd.1fc885607f2aac621f8f2d3ef1847f22`). Pass it whole. Do NOT pass the AttachmentRef or the Filename.
+
+**Finding the DocumentId:**
+
+| You have | How to get the DocumentId |
+|----------|---------------------------|
+| Filename (e.g., `invoice-001.pdf`) | `uip ixp documents list <project-name> --output json --output-filter "Documents[?Filename=='invoice-001.pdf'].DocumentId \| [0]" --output plain` (rows are under `Documents` — the list is a paged envelope) |
+| A distinctive predicted field value (e.g., Invoice Number `MSI0601020`) | Run `uip ixp labellings get-predictions <project-name> --output json`, find the entry in `Predictions[]` whose `Labels[].Fields[].FormattedValue` matches, take its `DocumentId` |
+| Nothing — need to find by content | `uip ixp documents list <project-name> --output json`, then `documents download` candidates and read with the Read tool |
+
+`documents list` returns `Filename` alongside `DocumentId` (the original upload filename, or `null` if none was sent at upload time). When filenames aren't unique within the project, the JMESPath filter returns multiple IDs — review them with `documents download` before deleting.
+
+Deletion is irreversible and triggers a model retrain. Do NOT use deletion to skip documents you simply don't want to label — leave those unconfirmed instead.
+
+## Step 3 — Summary
+
+After processing all documents, track progress and errors:
+
+- Do NOT stop on the first error — continue with remaining documents
+- If a download or text fetch fails, skip the document and note the failure
+- If confirmation fails, log the error and UID, then continue
+
+At the end, report a full summary:
+
+```text
+Labelling complete.
+
+Documents: N processed, M confirmed, K skipped (no predictions)
+Fields: X confirmed, Y corrected, W marked missing, Z not confirmed
+
+OCR Corrections Applied:
+  Doc <uid-1>: Invoice Number "MSIÓÓÓ601020/" → "MSI0601020"
+  Doc <uid-1>: Vendor Name "INGRAM NTCRO INC" → "INGRAM MICRO INC"
+  Doc <uid-3>: Bill-To Address "123 Mam St" → "123 Main St"
+
+Marked Missing (IXP predicted empty AND field absent from document):
+  Doc <uid-2>: Terms of Payment
+  Doc <uid-4>: Discount
+
+Not Confirmed (skipped):
+  Doc <uid-3>: Total Amount — predicted "500.00" but actual is "5000.00" (bottom-right, page 1)
+  Doc <uid-5>: Vendor Address — predicted "123 Main St" but actual is "456 Oak Ave"
+```

package/skills/uipath-ixp/references/project-setup-guide.md

@@ -0,0 +1,90 @@
+# Project Setup Guide
+
+Complete workflow for creating a **new** IXP project, labelling all documents, and getting initial metrics. Run all steps end-to-end automatically.
+
+> **Wrong page if the project already exists.** Use `uip ixp documents upload <project-name> <file>` — see [CLI Reference § Uploading documents](cli-reference.md#uploading-documents-to-an-existing-project).
+
+## Step 1 — Create the Project
+
+If the user provides a name, use it. If not, generate a temporary name (e.g., `ixp_project_NNNN` with a random number) — the project will be renamed in Step 3 after the taxonomy reveals the document type.
+
+`<folder-path>` is filtered to supported document files — see [CLI Reference § Supported document files](cli-reference.md#supported-document-files).
+
+**Option A — Auto-suggest taxonomy (default):**
+
+```bash
+uip ixp projects create "<name>" <folder-path> --output json
+```
+
+If the user specified what to extract, add `-d` for a better taxonomy suggestion:
+
+```bash
+uip ixp projects create "<name>" <folder-path> -d "<what to extract>" --output json
+```
+
+This uploads documents and auto-suggests a taxonomy based on the document content (and the description if provided).
+
+**Option B — Blank project + import taxonomy from file:**
+
+If the user provides a taxonomy file, create a blank project and import separately:
+
+```bash
+uip ixp projects create "<name>" <folder-path> --skip-taxonomy --output json
+uip ixp projects import-taxonomy <project-name> <taxonomy-file> --output json
+```
+
+The taxonomy file can be in either format — the CLI auto-detects based on which keys are present:
+
+- `{ "field_types": [...], "label_group": {...} }` — use when importing a taxonomy suggested by a previous `project create` run
+- `{ "entity_defs": [...], "label_groups": [...] }` — use when importing a taxonomy file provided by the user, or cloning from an existing project. `projects get-taxonomy` returns these under a `dataset` wrapper (`{ status, dataset: { entity_defs, label_groups } }`); `import-taxonomy` reads `entity_defs`/`label_groups` at the **top level**, so pass the inner `dataset` object (e.g. `jq .Data.dataset`), not the whole response
+
+Use the `ProjectName` from the create output for all subsequent commands. This is the lowercase slug with UUID and `-ixp` suffix (e.g., `my_invoices-f1afa9ef-ixp`), NOT the Title.
+
+Create the working directory using the returned `ProjectName`:
+
+```bash
+mkdir -p /tmp/ixp/<project-name>/{docs,text,taxonomies,prompts}
+```
+
+## Step 2 — Configure the Model
+
+Before labelling, configure the extraction model based on what the documents look like. Download 2-3 sample document images and view them:
+
+```bash
+uip ixp documents list <project-name> --output json
+uip ixp documents download <project-name> <document-id> -o /tmp/ixp/<project-name>/docs/sample --output json
+```
+
+View with the **Read tool** — one full Read per document, **no `pages` parameter** (returns text + image natively). Then decide:
+
+| Document characteristics | Pre-processing | Model |
+|--------------------------|---------------|-------|
+| Simple documents, no tables | `none` | `gemini_2_5_flash` |
+| Documents with simple tables or multiple tables | `table_mini` | `gemini_2_5_flash` |
+| Complex nested tables, merged cells, multi-page tables | `table` | `gemini_2_5_flash` |
+| Very long documents (100+ pages) | `none` or `table_mini` | `gemini_2_5_pro` |
+
+Apply the configuration:
+
+```bash
+uip ixp projects configure-model <project-name> \
+  --model gemini_2_5_flash \
+  --preprocessing <none|table_mini|table> \
+  --output json
+```
+
+**Default recommendation:** `--model gemini_2_5_flash --preprocessing table_mini` — works well for most invoice/document types.
+
+## Step 3 — Name the Project
+
+Based on the taxonomy from Step 1 (e.g., if it has "Invoice Details", "Line Items", "Bill-To" → it's an invoices project), give the project a descriptive title:
+
+```bash
+uip ixp projects update-title <project-name> "Vendor Invoices" --output json
+```
+
+Skip this step if the user already provided a meaningful name in Step 1.
+
+## Step 4 — Label All Documents
+
+Follow the [Label Documents Guide](label-documents-guide.md) to label every document in the project.

package/skills/uipath-maestro-bpmn/SKILL.md

@@ -1,75 +1,174 @@
 ---
 name: uipath-maestro-bpmn
-description: "Always invoke for `.bpmn`, `project.uiproj`, `entry-points.json`, `operate.json`, `bindings_v2.json`, or `package-descriptor.json` files. UiPath Maestro BPMN / Process Orchestration — author, inspect, validate, package, operate, diagnose. Model writes BPMN skeleton + non-IS UiPath XML; CLI owns Integration Service nodes/templates and generated package files. For .flow JSON→uipath-maestro-flow. For XAML/coded workflows→uipath-rpa. For Python agents→uipath-agents. For Case plans→uipath-maestro-case."
+description: "UiPath Maestro BPMN / Process Orchestration: author (registry-driven), validate, package, operate, and diagnose .bpmn projects. For .flow use uipath-maestro-flow; for case plans use uipath-maestro-case."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
 ---
 
-# UiPath Maestro BPMN Skill
-
-Guide for authoring, inspecting, validating, packaging, operating, and diagnosing UiPath Maestro BPMN Process Orchestration projects. BPMN XML is the source of record. Generated JSON package files and Integration Service details are owned by CLI tooling.
-
-## When to use this skill
-
-**Author** - creating or editing local BPMN project source. Read [references/author/CAPABILITY.md](references/author/CAPABILITY.md).
-
-- Create a Maestro BPMN project skeleton
-- Edit `.bpmn` XML for process structure, variables, mappings, timers, messages, gateways, subprocesses, script tasks, and documented non-Integration-Service UiPath extensions
-- Plan where Integration Service activities/triggers require CLI enrichment instead of model-authored XML
-- Validate XML, diagrams, entry points, bindings, and generated package metadata locally
-
-**Operate** - packaging, uploading, publishing, running, or managing cloud lifecycle. Read [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md).
-
-- Package a BPMN Process Orchestration project
-- Upload to Studio Web or publish/deploy when explicitly requested
-- Run/debug a process instance only after explicit user consent
-- Manage jobs, instances, incidents, variables, and lifecycle actions
-
-**Diagnose** - investigating failed or misbehaving runs. Read [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md).
-
-- Fetch incidents, variables, element executions, and deployed BPMN assets
-- Correlate runtime failures back to BPMN element IDs and local XML
-- Identify authoring, packaging, binding, and Integration Service enrichment failures
-
-## Capability router
-
-| I want to... | Read |
+# UiPath Maestro BPMN
+
+Work with UiPath Maestro (Process Orchestration) `.bpmn` projects across their
+lifecycle: author, validate, package, operate, and diagnose. **Authoring is
+registry-driven**: every `uipath:*` extension payload comes from a template the
+registry serves; the structural BPMN that holds those nodes together (process
+scaffold, sequence flows, gateways, events, boundary events, containers,
+multi-instance markers, and the diagram) is authored from the documented spec +
+canvas contract. Packaging, operating (upload, publish, run, manage), and
+diagnosing are driven through the UiPath CLI, covered in the capability
+references below.
+
+## When to use
+
+- Create a Maestro `.bpmn` from a description.
+- Edit `.bpmn` structure: gateways, events, boundary events, subprocesses, call
+  activities, multi-instance loops, sequence-flow conditions, variables.
+- Add a UiPath extension node (RPA job, agent, HITL, queue, business rule, API
+  workflow, Integration Service connector, internal message, timer).
+- Validate a `.bpmn` against the canvas rules before import.
+- Package, upload, publish, or run a project, and manage its jobs and instances.
+- Diagnose a failed or misbehaving run.
+
+### Editing an existing `.bpmn` (preserve what you did not author)
+
+The skill can edit an existing file. Make **surgical** edits and preserve
+content you did not author: unknown `uipath:*` elements, `uipath:migrationVersion`,
+tags, imported Integration Service payloads, and stable element IDs. Do not
+regenerate the whole file or drop extension data the skill does not recognize —
+preserve-only structures (see the blocklist in
+[references/structural-bpmn.md](references/structural-bpmn.md)) round-trip
+untouched.
+
+For `.flow` JSON use `uipath-maestro-flow`; for XAML/coded workflows use
+`uipath-rpa`; for Python agents use `uipath-agents`; for Case plans use
+`uipath-maestro-case`.
+
+## The model
+
+Two halves make a valid Maestro `.bpmn`:
+
+1. **`uipath:*` payloads — registry-owned.** Each node's extension XML
+   (`uipath:activity` / `uipath:event` / `uipath:mapping`, its `context`,
+   `input`, `output`, and `bindingInfo`) comes from
+   `uip maestro bpmn registry get <type>`'s `xmlTemplate`. **Never hand-author a
+   `uipath:*` element from prose.**
+2. **Structural BPMN — spec/canvas-owned.** The registry emits no
+   `<bpmn:definitions>`/`<bpmn:process>`, no sequence flows, no gateway
+   conditions/defaults, no event-definition payloads, no boundary-event
+   attributes, no subprocess/loop structure, and no diagram. Author all of these
+   from [references/structural-bpmn.md](references/structural-bpmn.md), which is
+   grounded in the registry spec and the Studio Web canvas serializer.
+
+## Workflow
+
+Work the four steps quickly and author early — do not pre-read every reference
+before writing. Read a reference only when you reach the structure it covers.
+
+1. **Discover.** `uip maestro bpmn registry pull` **once** (cached for the
+   session — do not re-pull), then `list` / `search` to map intent to extension
+   types; `uip is connections list --all-folders` for live connections (always
+   `--all-folders` — a folder-scoped list silently misses connections). Confirm
+   every selection with the user (use AskUserQuestion). Never fabricate an identifier.
+   See [references/registry-workflow.md](references/registry-workflow.md).
+2. **Get templates.** `uip maestro bpmn registry get <type> --output json` for
+   each chosen node. Enrich `Intsvc.*` connector nodes with
+   `--connection-id`/`--object-name`.
+3. **Assemble.** Author directly from the complete minimal file in
+   [references/structural-bpmn.md](references/structural-bpmn.md#a-complete-minimal-file-author-from-this-not-from-fixtures)
+   plus each node's `xmlTemplate` (fill placeholders only). That skeleton already
+   shows variables, the entry point, a branch, and the diagram. **Do not read the
+   validator's `test/fixtures/` to infer the pattern** — it is the top reason
+   authoring runs out of time. Add only the structural pieces your process needs
+   (extra gateways, events, boundary events, containers, multi-instance markers),
+   then generate one `BPMNShape`/`BPMNEdge` per node and flow.
+4. **Validate.** There is **no** `uip maestro bpmn validate` CLI command. Run the
+   bundled validator — it reconstructs the canvas model and runs every
+   PO.Frontend rule:
+
+   ```bash
+   cd skills/uipath-maestro-bpmn/validator && npm install --silent
+   node validate-bpmn.mjs <file.bpmn>   # prints VALID (exit 0) or the errors (exit 1)
+   ```
+
+   A well-formed-XML parse is the secondary fallback if Node is unavailable. See
+   [references/structural-bpmn.md#validation](references/structural-bpmn.md#validation).
+   Validate once; fix only ERROR-severity findings (warnings do not block import).
+   Do not re-validate in a loop chasing warnings.
+
+## Operate and diagnose
+
+Beyond authoring, this skill packages, ships, runs, and diagnoses Maestro
+projects through the UiPath CLI.
+
+- **Package and operate** (package a project, upload to Studio Web, publish or
+  deploy, run or debug instances, and manage jobs, instances, incidents, and
+  lifecycle actions): see [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md).
+- **Diagnose** (fetch incidents, variables, and element executions, and trace a
+  failed run back to its BPMN element): see [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md).
+
+Any cloud-side change (upload, publish, deploy, run, pause, resume, cancel,
+retry, migrate) requires explicit user consent, and local validation should pass
+first.
+
+## Structural coverage
+
+This skill teaches authoring of the full surface the canvas supports. What the
+registry serves a template for vs. what you author by hand:
+
+| Structure | Source |
+| --- | --- |
+| Node `uipath:*` payloads (RPA, agent, HITL, queue, business rule, API workflow, IS connector, internal message, timer, script, variables) | **Registry** `xmlTemplate` |
+| `<bpmn:definitions>`/`<bpmn:process>` scaffold + namespaces | Authored (registry gap) |
+| Sequence flows, `conditionExpression`, gateway `default` | Authored (registry gap) |
+| Gateways: exclusive, parallel, inclusive, event-based (complex is preserve-only) | Authored (registry gap) |
+| Events + event-definition matrix: message, timer, error, terminate (end-only). Signal/escalation/conditional/link/compensate/cancel/multiple are preserve-only | Authored (registry gap); payload per canvas serializer |
+| Boundary events: `attachedToRef`, interrupting/non-interrupting (`cancelActivity`) | Authored (registry gap) |
+| Subprocess, event subprocess (`triggeredByEvent`), call activity | Authored (registry gap); call-activity payloads from registry |
+| Multi-instance / loop characteristics | Authored from canvas contract — **registry exposes no template (registry gap)** |
+| `bpmndi:BPMNDiagram` (shape per node, edge per flow) | Always generated — **registry emits none (registry gap)** |
+
+Flagged registry gaps: the registry serves no template for structural BPMN,
+sequence-flow conditions, event-definition payloads, boundary-event attributes,
+multi-instance markers, or the diagram. These are authored from the spec +
+canvas contract in [references/structural-bpmn.md](references/structural-bpmn.md)
+and honestly surfaced to the user as gaps when asked.
+
+## Rules
+
+1. **Registry owns every `uipath:*` payload.** Author from
+   `registry get` templates; never hand-write `uipath:` XML from prose.
+2. **Never fabricate an identifier.** Connection IDs, process/queue/connector
+   keys, app IDs, folder ids/paths come from discovery or the user.
+3. **Structural BPMN is authored, not invented.** Follow the spec/canvas
+   contract in [references/structural-bpmn.md](references/structural-bpmn.md);
+   flag honestly what the registry does not expose.
+4. **Confirm before authoring.** Confirm the chosen connector/connection/process
+   and the process structure with the user (AskUserQuestion).
+5. **The diagram is mandatory.** Import is diagram-driven — every node needs a
+   `BPMNShape`, every flow a `BPMNEdge`, or it will not appear on the canvas.
+6. **Node type is a child element, never an attribute.** Every `uipath:activity`
+   / `uipath:event` / `uipath:mapping` declares its type as
+   `<uipath:type value="<Type>" version="v1" />` inside the wrapper. Never write
+   `<uipath:activity type="…">` — the canvas will not recognize the node.
+7. **No `--` in XML comments.** XML forbids `--` (double-hyphen) inside
+   `<!-- … -->`, so never paste CLI commands or flags (`--output`,
+   `--connection-id`, `--object-name`) into a comment — it makes the file
+   unparseable. Keep comments minimal.
+8. **Use `--output json` for parsed CLI calls.**
+9. **Public-safe always.** No customer XML, tenant URLs, real IDs, or private
+   names — see [references/public-safety.md](references/public-safety.md).
+10. **Confirm before any cloud change.** Upload, publish, deploy, run, pause,
+   resume, cancel, retry, and migrate require explicit user consent; validate
+   locally first.
+
+## References
+
+| Topic | Read |
 | --- | --- |
-| Create or edit BPMN source | [references/author/CAPABILITY.md](references/author/CAPABILITY.md) |
-| Package, upload, publish, run, or manage lifecycle | [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md) |
+| Discover → template → bind → assemble loop | [references/registry-workflow.md](references/registry-workflow.md) |
+| Structural BPMN, event matrix, boundary events, containers, multi-instance, diagram, validation | [references/structural-bpmn.md](references/structural-bpmn.md) |
+| Runtime expressions, `vars.`/`bindings.`/`iterator.`, `=js:` (Jint) syntax | [references/expression-authoring.md](references/expression-authoring.md) |
+| CLI conventions and the side-effect boundary | [references/cli-conventions.md](references/cli-conventions.md) |
+| Keeping content public-safe | [references/public-safety.md](references/public-safety.md) |
+| Bundled offline validator (every PO.Frontend rule) | [validator/README.md](validator/README.md) |
+| Package, upload, publish, run, or manage instances | [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md) |
 | Diagnose a failed or misbehaving run | [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md) |
-| Understand project layout and package files | [references/shared/project-layout.md](references/shared/project-layout.md) |
-| Regenerate or verify local package metadata | [references/shared/local-metadata-regeneration-guide.md](references/shared/local-metadata-regeneration-guide.md) |
-| Understand BPMN XML authoring boundaries | [references/shared/bpmn-xml-contract.md](references/shared/bpmn-xml-contract.md) |
-| Copy minimal XML shells per supported wrapper | [references/shared/wrapper-shells.md](references/shared/wrapper-shells.md) |
-| Understand variables, bindings, entry points, and expressions | [references/shared/variables-bindings-expressions.md](references/shared/variables-bindings-expressions.md) |
-| Author lint-compatible runtime expressions | [references/shared/expression-authoring.md](references/shared/expression-authoring.md) |
-| Author Maestro retry and error handling | [references/shared/error-handling.md](references/shared/error-handling.md) |
-| Understand CLI conventions and side-effect boundaries | [references/shared/cli-conventions.md](references/shared/cli-conventions.md) |
-| Keep examples and commits public-safe | [references/shared/public-safety.md](references/shared/public-safety.md) |
-
-## Critical rules (universal)
-
-1. **BPMN XML is the source of record** - edit `.bpmn` for process structure; treat generated package JSON as derived unless a CLI contract explicitly says otherwise.
-2. **Model owns skeleton and documented non-IS XML only** - generate BPMN control flow, diagram coordinates, root variables, mappings, entry point IDs, script tasks, retry/error metadata, and documented non-Integration-Service UiPath extensions. Do not invent undocumented UiPath extension payloads.
-3. **Use two-pass authoring for substantial changes** - write the standard BPMN skeleton first, get operator confirmation of the process shape, then fill model-owned UiPath extension XML.
-4. **CLI owns Integration Service enrichment** - Integration Service activities/triggers, connection bindings, connector metadata, dynamic schemas, trigger properties, and generated output templates must come from registry-backed CLI enrichment or validation.
-5. **Never use private source material in skill content** - no exported customer BPMN, tenant URLs, folder keys, connection IDs, user names, process names, local paths, screenshots, or temporary mission notes. Examples must be synthetic.
-6. **Use JSON output for parsed CLI calls** - whenever CLI output is parsed programmatically, request JSON output from the CLI and preserve the raw command result in the local transcript or a sanitized report.
-7. **Do not run debug or deployed process execution without explicit user consent** - debug/run can trigger real side effects in external systems.
-8. **Ask before cloud-side mutations** - upload, publish, deploy, run, pause, resume, cancel, retry, migrate, and move-cursor operations require a clear user decision.
-9. **Do not automatically invoke sibling skills** - when BPMN references an RPA process, agent, app, API workflow, or case asset that is missing, identify the dependency and provide handoff instructions.
-10. **Validate before operate** - run local XML/project/package validation before upload, publish, or debug. Treat validation warnings about CLI-owned enrichment as blockers for real runs when the target element can execute.
-11. **Preserve unknown extension payloads unless normalizing explicitly** - do not delete or rewrite user-authored or imported UiPath extension XML just because the skill cannot fully interpret it.
-
-## Anti-patterns (universal)
-
-- **Do not hand-author Integration Service connection details** - connection IDs, resource keys, connector labels, trigger property bindings, and generated schemas are CLI-owned.
-- **Do not rely on BPMN without diagrams for Studio Web import** - a valid diagram and plane are required, and visible elements need shapes or waypoints.
-- **Do not edit derived package files as the primary fix** - fix the BPMN source or rerun the CLI generator/enricher unless the package file itself is the documented source for that field.
-- **Do not include real exported XML snippets in docs or examples** - summarize patterns using public-safe synthetic IDs and placeholder values.
-- **Do not use validation fixtures as greenfield templates** - fixtures are
-  coverage examples, not the authoring source of truth. Use capability docs,
-  shared contracts, wrapper shells, and the specific plugin or task recipe
-  instead.
-
-> Trouble? Send public-safe product feedback through the repository's normal feedback path.
+| Project layout and generated package files | [references/shared/project-layout.md](references/shared/project-layout.md) |

package/skills/uipath-maestro-bpmn/references/cli-conventions.md

@@ -0,0 +1,47 @@
+# CLI Conventions (authoring)
+
+This reference covers the **authoring-side** CLI surface only: the read-only
+registry discovery commands used to produce a valid, importable Maestro `.bpmn`
+file. The registry commands below never mutate cloud state. Operate and diagnose
+use different CLI commands — see
+[operate/CAPABILITY.md](operate/CAPABILITY.md) and
+[diagnose/CAPABILITY.md](diagnose/CAPABILITY.md).
+
+## Discovery commands (read-only, authoring-safe)
+
+All commands below are discovery/read-only. None mutate cloud state.
+
+| Command | Purpose |
+| --- | --- |
+| `uip maestro bpmn registry pull [-f\|--force]` | Sync and cache the registry. Without login, only OOTB extension types are synced; login adds discovered connectors and processes. |
+| `uip maestro bpmn registry list [--limit <n\|-1>]` | List cached extension types (and discovered connectors/processes). Default 30; use `--limit -1` for all. |
+| `uip maestro bpmn registry search <keyword>` | Find entries by keyword across extension type, label, connector name, process name. |
+| `uip maestro bpmn registry get <extensionType> [--connection-id <id>] [--object-name <name>]` | Get the full spec for one extension type: `xmlTemplate`, `contextFields`, `bindingInfo`, input/output patterns. `--connection-id`/`--object-name` add live Integration Service field metadata for `Intsvc.*` connector types. |
+| `uip is connections list --all-folders` | List live Integration Service connections (id + state) across all folders. Always pass `--all-folders`; a folder-scoped list silently misses connections. |
+
+These are the **only** commands the skill verifies against the CLI source
+(`packages/maestro-tool/src/commands/registry.ts`). Do not invent flags. In
+particular, there is **no** `uip maestro bpmn validate` command — see
+[Validation](structural-bpmn.md#validation). Validation is done with the bundled
+offline validator, not a CLI.
+
+## Output parsing
+
+Whenever a CLI result is parsed programmatically, pass `--output json`. If a
+command does not support JSON, do not silently scrape human text; keep the step
+manual and tell the user.
+
+## Login boundary
+
+Local source authoring and the bundled validator work without login. Registry
+discovery of **connectors and processes** (and Integration Service field
+enrichment) requires `uip login`. Without login, `registry pull` still returns
+the built-in (OOTB) extension types.
+
+## Never fabricate an identifier
+
+Connection IDs, `releaseKey`/process keys, queue keys, connector keys, app IDs,
+folder IDs/paths — every concrete identifier comes from discovery
+(`registry get`, `registry search`, `uip is connections list`) or from the user.
+Never invent one. When a required identifier is unknown, leave the placeholder
+in place, flag it as a draft binding, and ask the user.

package/skills/uipath-maestro-bpmn/references/diagnose/CAPABILITY.md

@@ -7,7 +7,7 @@ deployed BPMN asset correlation, element executions, cursors, generated package
 > **Where you came from / where to go next.** Diagnose is downstream of Operate (a debug or deployed run failed, hung,
 > or behaved unexpectedly) and points back to Author for source fixes.
 > Running and lifecycle live in [operate/CAPABILITY.md](../operate/CAPABILITY.md);
-> source fixes live in [author/CAPABILITY.md](../author/CAPABILITY.md).
+> source fixes live in [registry-workflow.md](../registry-workflow.md).
 >
 > **Inherits universal rules from [SKILL.md](../../SKILL.md).** BPMN source is model-authored; generated package files
 > and Integration Service enrichment are CLI-owned.
@@ -62,10 +62,10 @@ deployed BPMN asset correlation, element executions, cursors, generated package
 | Diagnose binding or generated JSON issues | [failure modes](references/failure-modes.md), [project layout](../shared/project-layout.md) |
 | Diagnose Integration Service runtime issues | [failure modes](references/failure-modes.md) |
 | Decide whether retry is safe | [troubleshooting guide](references/troubleshooting-guide.md), [manage guide](../operate/references/manage.md) |
-| Fix the source | [author/CAPABILITY.md](../author/CAPABILITY.md) |
+| Fix the source | [registry-workflow.md](../registry-workflow.md) |
 
 For Integration Service enrichment details, read
-[author/references/plugins/integration-service/impl.md](../author/references/plugins/integration-service/impl.md).
+[registry-workflow.md](../registry-workflow.md).
 
 ## Anti-patterns
 
@@ -85,7 +85,7 @@ For Integration Service enrichment details, read
 
 ### Cross-capability
 
-- [shared/bpmn-xml-contract.md](../shared/bpmn-xml-contract.md) - XML authoring and validation boundaries
+- [shared/bpmn-xml-contract.md](../structural-bpmn.md) - XML authoring and validation boundaries
 - [shared/project-layout.md](../shared/project-layout.md) - generated files and package shape
-- [shared/variables-bindings-expressions.md](../shared/variables-bindings-expressions.md) - mappings and binding expressions
-- [shared/public-safety.md](../shared/public-safety.md) - redaction and sanitization
+- [shared/variables-bindings-expressions.md](../expression-authoring.md) - mappings and binding expressions
+- [shared/public-safety.md](../public-safety.md) - redaction and sanitization