@uipath/skills 1.197.2 → 1.198.0-preview.21

package/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails.md

@@ -37,7 +37,7 @@ installed/published SDK documentation does not currently support HITL guardrail
 
 ## Check Tenant Availability (mandatory for built-in AI validators)
 
-For built-in AI validators (PII, harmful content, user prompt attacks, IP), confirm the validator is enabled on this tenant **before authoring** — run:
+For built-in AI validators (PII, harmful content, user prompt attacks, IP, LLM as Judge), confirm the validator is enabled on this tenant **before authoring** — run:
 
 ```bash
 uip agent guardrails list --output json
@@ -47,6 +47,8 @@ If the requested validator has `Status != "Available"` → tell the user and sto
 
 **Skip this step only for deterministic guardrails** — they run locally with no backend dependency.
 
+> **LLM as Judge also requires LLM Gateway.** If the target is `llm_as_judge`, confirm with the user that a model is configured in their LLM Gateway before proceeding. Ask the user which model ID to use for the `model` parameter — the available values depend on the LLM Gateway configuration in their tenant.
+
 ---
 
 ## Step 1 — Style Choice
@@ -337,7 +339,9 @@ On resume: **Approve** continues (with the reviewer's optional edit applied); **
 
 ---
 
-## Verify Guardrails Are Actually Wired (mandatory after writing)
+## Verify Guardrails Are Actually Wired (mandatory after writing for LangChain ML guardrails)
+
+> **Skip this entire section for deterministic guardrails** (`UiPathDeterministicGuardrailMiddleware` / `CustomValidator`). They run inline with no adapter registration and no LLM wrapping. For deterministic guardrails, grep-verify the class name and rule keyword are present in the file — that is sufficient.
 
 **Syntactically valid ≠ active.** Because importing from the wrong module bypasses the framework adapter and makes guardrails silently no-op (see [Imports Pattern](#imports-pattern)), `ast.parse` passing tells you nothing about whether a single guardrail will ever fire. After writing, prove the wiring at runtime.
 
@@ -379,7 +383,7 @@ For non-LangChain frameworks, there is no published adapter yet, so the decorato
 6. **Respect scope and stage constraints from the docs** — each middleware class has specific allowed scopes and stages; never apply a guardrail at a scope or stage the docs say it doesn't support.
 7. **Only add imports you use** — merge new names into any existing `from uipath_langchain.guardrails import (...)` block (LangChain) or `from uipath.platform.guardrails import (...)` block (every other framework).
 8. **For LangChain / LangGraph agents, import guardrail symbols from `uipath_langchain.guardrails`, not `uipath.platform.guardrails`.** Both expose the same names, but only `uipath_langchain.guardrails` registers the LangChain adapter as an import side effect; without it the decorator/middleware never wraps the LLM/tool/agent and every guardrail silently no-ops with no error or log. For any other framework (LlamaIndex, OpenAI Agents, plain Python), import from `uipath.platform.guardrails` — no framework adapter is published yet. See [Imports Pattern](#imports-pattern).
-9. **Verify wiring at runtime after writing (LangChain only)** — confirm the LangChain adapter is registered (`len(_adapters) >= 1`) and the decorated object is wrapped (`type(llm).__name__ == "_GuardedLLM"`, or `_GuardedTool` for tools). `ast.parse` is not enough; a silently-unwrapped guardrail passes syntax but never fires. For frameworks without an adapter, this wrap-check does not apply — invoke the validator directly to confirm it runs. See [Verify Guardrails Are Actually Wired](#verify-guardrails-are-actually-wired-mandatory-after-writing).
+9. **Verify wiring at runtime after writing (LangChain only)** — confirm the LangChain adapter is registered (`len(_adapters) >= 1`) and the decorated object is wrapped (`type(llm).__name__ == "_GuardedLLM"`, or `_GuardedTool` for tools). `ast.parse` is not enough; a silently-unwrapped guardrail passes syntax but never fires. For frameworks without an adapter, this wrap-check does not apply — invoke the validator directly to confirm it runs. **For `UiPathDeterministicGuardrailMiddleware` / `CustomValidator`, skip both runtime checks — grep-verify the class name and rule keyword are present in the file instead.** See [Verify Guardrails Are Actually Wired](#verify-guardrails-are-actually-wired-mandatory-after-writing-for-langchain-ml-guardrails).
 10. **Entity/threshold values must match the docs exactly** — use enum member names, not raw strings; use only allowed threshold values.
 11. **Deterministic guardrails run locally** — no backend API call, no tenant availability check needed.
 12. **Do not duplicate existing guardrails** — read the agent code first and skip if the same guardrail is already configured.
@@ -387,4 +391,4 @@ For non-LangChain frameworks, there is no published adapter yet, so the decorato
 14. **`EscalateAction` must come from the fetched SDK docs** — if the docs do not expose the class or constructor parameters, stop and report that HITL guardrail escalation is not available in the current SDK docs/runtime. Never invent the class, import path, or arguments.
 15. **`EscalateAction` requires a deployed Action App** referenced by `app_name` + `app_folder_path` and declared as an `app` resource in **`bindings.json`** — discover it with `uip solution resources list --kind App`, resolve duplicate names by folder, pass the literal name/folder in code (not env vars), and sync bindings with [../../lifecycle/bindings-reference.md](../../lifecycle/bindings-reference.md). Route the task with `TaskRecipient` when the user names a reviewer. See [Escalation action (HITL)](#escalation-action-human-in-the-loop).
 16. **Verify the escalation app schema when tenant access is available** — the app must expose the guardrail review inputs/outputs/outcomes listed in the prerequisite section. If the schema cannot be verified in a local smoke task, say that runtime readiness is unverified.
-17. **A HITL guardrail suspends, it doesn't block.** On violation `EscalateAction` suspends via `interrupt(CreateEscalation(...))`; it terminates **only on Reject** (Approve resumes). Verify by confirming the run suspends + a task is created — never expect a "block" for an escalation guardrail (Rule for the [verification step](#verify-guardrails-are-actually-wired-mandatory-after-writing)).
+17. **A HITL guardrail suspends, it doesn't block.** On violation `EscalateAction` suspends via `interrupt(CreateEscalation(...))`; it terminates **only on Reject** (Approve resumes). Verify by confirming the run suspends + a task is created — never expect a "block" for an escalation guardrail (Rule for the [verification step](#verify-guardrails-are-actually-wired-mandatory-after-writing-for-langchain-ml-guardrails)).

package/skills/uipath-agents/references/coded/embedding-in-flows.md

@@ -92,7 +92,7 @@ uip maestro flow registry list --local --output json
 uip maestro flow registry get "uipath.core.agent.<resourceKey>" --local --output json
 ```
 
-The second command's `Data.Node` object is what the flow skill pastes into the flow's `definitions[]`. For the node instance shape and top-level `bindings[]` entries, see [agent/impl.md § In-solution variant](../../../uipath-maestro-flow/references/plugins/agent/impl.md#node-instance-inside-nodes--in-solution-variant).
+The second command's `Data.Node` object is what the flow skill pastes into the flow's `definitions[]`. For the node instance shape and top-level `bindings[]` entries, see the uipath-maestro-flow skill agent-plugin reference (In-solution variant).
 
 Without `--local`, `registry list`/`get` query the tenant registry (Orchestrator-published resources only) and will not surface the sibling project.
 

package/skills/uipath-agents/references/coded/flow-integration.md

@@ -10,7 +10,7 @@ The coded agent lives as a sibling folder inside the same solution as the flow.
 
 - **Agent-side scaffolding:** [embedding-in-flows.md](embedding-in-flows.md)
 - **Wiring the agent's inputs:** [embedding-in-flows.md § Wiring the Agent's Inputs](embedding-in-flows.md#wiring-the-agents-inputs)
-- **Flow node JSON shape + top-level `bindings[]` + `definitions[]` entry:** [agent/impl.md § In-solution variant](../../../uipath-maestro-flow/references/plugins/agent/impl.md#node-instance-inside-nodes--in-solution-variant)
+- **Flow node JSON shape + top-level `bindings[]` + `definitions[]` entry:** uipath-maestro-flow skill, agent-plugin reference (In-solution variant)
 
 The node-type's `{key}` is the local `resource.key` minted by `uip solution project add` (written to `resources/solution_folder/process/agent/<name>.json`) and surfaced by `uip maestro flow registry list --local`.
 
@@ -36,7 +36,7 @@ Fallback discovery paths if the deploy output is unavailable or unparseable, **t
 
 If all paths return empty / 404, the deploy command's stdout JSON is authoritative — re-run the deploy and capture its output rather than chasing post-hoc discovery endpoints.
 
-For the flow node JSON shape, see [agent/impl.md § Published variant](../../../uipath-maestro-flow/references/plugins/agent/impl.md#node-instance-inside-nodes--published-variant). `model.section` is `"Published"`.
+For the flow node JSON shape, see the uipath-maestro-flow skill agent-plugin reference (Published variant). `model.section` is `"Published"`.
 
 ---
 

package/skills/uipath-agents/references/coded/lifecycle/build.md

@@ -8,7 +8,6 @@ Read **only** the reference matching the selected framework. Do NOT load other f
 
 | Framework | Reference |
 |-----------|-----------|
-| Coded Function | `../frameworks/coded-function-agents.md` + `../frameworks/agent-patterns.md` |
 | LangGraph | `../frameworks/langgraph-integration.md` |
 | LlamaIndex | `../frameworks/llamaindex-integration.md` |
 | OpenAI Agents | `../frameworks/openai-agents-integration.md` |

package/skills/uipath-agents/references/coded/lifecycle/setup.md

@@ -14,7 +14,6 @@ Pick the framework before starting. The package installed in the Workflow determ
 
 | Agent Type | `<FRAMEWORK_PACKAGE>` | Framework config | Guide |
 |---|---|---|---|
-| Coded Function | `uipath` | `uipath.json` | [coded-function-agents.md](../frameworks/coded-function-agents.md) |
 | LangGraph | `"uipath-langchain"` | `langgraph.json` | [langgraph-integration.md](../frameworks/langgraph-integration.md) |
 | LlamaIndex | `uipath-llamaindex` | `llama_index.json` | [llamaindex-integration.md](../frameworks/llamaindex-integration.md) |
 | OpenAI Agents | `uipath-openai-agents` | `openai_agents.json` | [openai-agents-integration.md](../frameworks/openai-agents-integration.md) |

package/skills/uipath-agents/references/coded/quickstart.md

@@ -47,7 +47,7 @@ Use `uip codedagent <cmd>`, not `uv run uipath <cmd>`. The wrapper injects sessi
 - **Auth MUST be an interactive question only when needed and values are missing.** If the session check fails and the user did not provide all of environment / organization / tenant, your ENTIRE response must be a single direct question. Do NOT wrap it in bullet points, "Next Steps" headers, or status summaries. Just ask and stop:
 
   > What is your UiPath **environment** (cloud/staging/alpha), **organization name**, and **tenant name**?
-- **In a flow, coded agents are referenced via the [`agent`](../../../uipath-maestro-flow/references/plugins/agent/) plugin** — node type `uipath.core.agent.{key}`, `Orchestrator.StartAgentJob`. See [flow-integration.md](flow-integration.md) for the three patterns: in-solution sibling folder, Orchestrator-published, tool resource.
+- **In a flow, coded agents are referenced via the `agent` plugin (uipath-maestro-flow skill)** — node type `uipath.core.agent.{key}`, `Orchestrator.StartAgentJob`. See [flow-integration.md](flow-integration.md) for the three patterns: in-solution sibling folder, Orchestrator-published, tool resource.
 
 ## Lifecycle Stages
 

package/skills/uipath-agents/references/lowcode/agent-definition.md

@@ -271,7 +271,7 @@ For conversational, typically general behavior and steps to respond to users. Sh
 
 ### User Message
 
-For autonomous agents, templates input fields into the prompt using `{{input.fieldName}}`. For `job-attachment` fields the token renders metadata only (see § File Attachments).
+For autonomous agents, templates input fields into the prompt using `{{input.fieldName}}`, and agent resources/outputs using `@{ }` expressions (see § contentTokens Construction). For `job-attachment` fields the token renders metadata only (see § File Attachments).
 
 ```json
 {
@@ -292,10 +292,15 @@ For conversational agents, the user-message should be ignored after initializati
 
 Every message needs both `content` (string) and `contentTokens` (array). Keep them in sync.
 
+Three token types: `simpleText`, `variable`, `expression`.
+
 **Rules:**
-1. Text outside `{{ }}` → `{ "type": "simpleText", "rawString": "<text>" }`
-2. Text inside `{{ }}` → `{ "type": "variable", "rawString": "input.fieldName" }` (strip delimiters)
-3. Every segment including whitespace gets its own entry
+1. Text outside `{{ }}` and `@{ }` → `{ "type": "simpleText", "rawString": "<text>" }`
+2. Text inside `{{ }}` → `{ "type": "variable", "rawString": "input.fieldName" }` (strip delimiters; input-field reference)
+3. Text inside `@{ }` → `{ "type": "expression", "rawString": "<expr>" }` (strip delimiters; Studio expression referencing an agent resource or output — see families below)
+4. Every segment including whitespace gets its own entry
+
+`@{ }` (`expression`) references an agent resource or output by family + name — `tools.<Name>`, `contexts.<Name>`, `escalations.<Name>`, or `output.<path>` — with the inner text verbatim as `rawString` (e.g. `@{contexts.Knowledge}` → `rawString: "contexts.Knowledge"`). `{{ }}` (`variable`) is for `inputSchema` fields only; `@{ }` targets are runtime-resolved and must never be declared under `inputSchema.properties`.
 
 **Example — adjacent variables:**
 
@@ -309,9 +314,23 @@ Content: `"{{input.field1}} {{input.field2}}"`
 ]
 ```
 
+**Example — resource reference (`@{ }` expression):**
+
+Reference an agent resource by family + name, e.g. a context (`resources/<Name>/resource.json`) with `@{contexts.<Name>}`.
+
+Content: `"Extract information from the @{contexts.Test} context"`
+
+```json
+"contentTokens": [
+  { "type": "simpleText", "rawString": "Extract information from the " },
+  { "type": "expression", "rawString": "contexts.Test" },
+  { "type": "simpleText", "rawString": " context" }
+]
+```
+
 **Common mistakes:**
 - Forgetting to update contentTokens after editing content
-- Including `{{` or `}}` in the variable rawString
+- Including `{{`/`}}` or `@{`/`}` in the rawString
 - Missing whitespace tokens between adjacent variables
 
 ## entry-points.json

package/skills/uipath-agents/references/lowcode/capabilities/built-in-tools/batch-transform/planning.md

@@ -11,7 +11,7 @@ Pick this when:
 
 Confirm BatchTransform is the right mode first — see [../../../../context-grounding-patterns.md](../../../../context-grounding-patterns.md).
 
-For coded agents (Python, LangGraph) → [../../../coded/capabilities/batch-transform/planning.md](../../../coded/capabilities/batch-transform/planning.md).
+For coded agents (Python, LangGraph) → [../../../../coded/capabilities/batch-transform/planning.md](../../../../coded/capabilities/batch-transform/planning.md).
 
 ## Inputs You Need Before Building
 

package/skills/uipath-agents/references/lowcode/capabilities/built-in-tools/deeprag/planning.md

@@ -11,7 +11,7 @@ Pick this when:
 
 Confirm DeepRAG is the right mode first — see [../../../../context-grounding-patterns.md](../../../../context-grounding-patterns.md).
 
-For coded agents (Python, LangGraph) → [../../../coded/capabilities/deeprag/planning.md](../../../coded/capabilities/deeprag/planning.md).
+For coded agents (Python, LangGraph) → [../../../../coded/capabilities/deeprag/planning.md](../../../../coded/capabilities/deeprag/planning.md).
 
 ## Inputs You Need Before Building
 

package/skills/uipath-agents/references/lowcode/capabilities/context/attachments.md

@@ -25,6 +25,7 @@ For other context variants, see [context.md](context.md).
   "description": "",
   "contextType": "attachments",
   "indexName": "<ContextName>",          // same as name for attachments
+  "folderPath": "solution_folder",
   "attachments": {
     "description": "Array of files, documents, images to process."
   },

package/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails-recommend.md

@@ -227,3 +227,4 @@ If the user asks to fix identified issues: apply corrections to `agent.json`, ru
 11. **Do not create separate guardrails per scope** — combine multiple scopes into a single guardrail's `scopes` array.
 12. **All map-enum keys must exactly match the corresponding enum-list values** — no extra or missing keys. This is the most common correctness error.
 13. **Read [guardrails.md](guardrails.md) before writing any JSON** — discriminator fields, PascalCase constraints, and parameter shapes are specified there and cannot be safely inferred.
+14. **Do NOT use TaskCreate, TaskUpdate, or other task-tracking tools for guardrail edits.** Edit `agent.json` directly — task management tools add bookkeeping turns without benefit and push runs over their turn budget.

package/skills/uipath-api-workflow/references/cli-reference.md

@@ -353,7 +353,7 @@ Requires `uip login`. The SDK resolves folder keys via Resource Catalog Service;
 
 **Idempotency.** Import-only by design. First run for a binding triggers `addOrUpdateResourceToSolutionAsync` (status `Added`); subsequent runs skip the binding because its key is already in the solution. Re-running is safe and a no-op when nothing changed.
 
-Lives in `solution-tool`, not `api-workflow-tool`. Full details in the [solution skill](../uipath-platform).
+Lives in `solution-tool`, not `api-workflow-tool`. Full details in the uipath-solution skill.
 
 ## `uip is resources describe`
 

package/skills/uipath-api-workflow/references/connector-activity-discovery.md

@@ -247,7 +247,7 @@ Sample for Outlook `getNewestEmail`:
 
 **Heuristic:** when the stub returns empty `queryParameters`, `pathParameters`, or `bodyParameters` for a non-trivial vendor operation, it's almost certainly the bug — verified-real endpoints (CRUD operations on real objects) very rarely have zero required inputs.
 
-Well-known folder-name shortcuts (e.g. MS Graph's `"inbox"`, `"sentitems"`, `"drafts"`) work for `parentFolderId`-style fields at runtime, but the StudioWeb FolderPicker only displays the friendly name if the value matches a real folder ID from the lookup cache. For exact UI fidelity, fetch the real ID once via `uip is resources execute <connector-key> list <object-name> --connection-id <uuid>` against the `lookup.path` (e.g. `/MailFolders`).
+Well-known folder-name shortcuts (e.g. MS Graph's `"inbox"`, `"sentitems"`, `"drafts"`) work for `parentFolderId`-style fields at runtime, but the StudioWeb FolderPicker only displays the friendly name if the value matches a real folder ID from the lookup cache. For exact UI fidelity, fetch the real ID once via `uip is resources run list <connector-key> <object-name> --connection-id <uuid>` against the `lookup.path` (e.g. `/MailFolders`).
 
 ### Step 4 — Drop into the workflow, replace placeholders, validate
 

package/skills/uipath-api-workflow/references/troubleshooting.md

@@ -500,7 +500,7 @@ These are issues that surface only when a workflow is opened or run in **StudioW
     }
   }
   ```
-- **Well-known shortcuts.** MS Graph accepts well-known folder names (`"inbox"`, `"sentitems"`, `"drafts"`) as `parentFolderId`. They run, but StudioWeb's FolderPicker only displays the friendly folder name when the value matches an ID from its lookup cache. For exact UI fidelity, fetch the real ID via `uip is resources execute <connector-key> list <object-name> --connection-id <uuid>` against the field's `lookup.path` (often `/MailFolders`, `/Folders`, etc.).
+- **Well-known shortcuts.** MS Graph accepts well-known folder names (`"inbox"`, `"sentitems"`, `"drafts"`) as `parentFolderId`. They run, but StudioWeb's FolderPicker only displays the friendly folder name when the value matches an ID from its lookup cache. For exact UI fidelity, fetch the real ID via `uip is resources run list <connector-key> <object-name> --connection-id <uuid>` against the field's `lookup.path` (often `/MailFolders`, `/Folders`, etc.).
 - **Heuristic:** when the stub returns empty `queryParameters` / `pathParameters` / `bodyParameters` for a non-trivial vendor operation, treat it as the bug. Real endpoints (CRUD on real objects, list-with-filters operations) almost never have zero required inputs.
 - **Upstream:** the stub IS surfacing the metadata it has — `metadata.configuration` contains the full `inputFields` list — so this is a CLI-side fix where the stub should populate defaults/placeholders from `required: true` fields, not a missing-data issue. Until that ships, the cross-check is mandatory per skill rule 16 step 4.
 - **See also:** [connector-activity-discovery.md — Required-field cross-check](connector-activity-discovery.md#required-field-cross-check--the-stub-drops-required-true-request-fields).

package/skills/uipath-automation-discovery/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-automation-discovery
-description: "UiPath automation discovery — mines Slack/email/wikis/CRM/HRIS/ERP for repetitive work, SPOFs, and replicable models; produces a 4-tier prioritized opportunity report with UiPath implementation paths. Use to discover automation opportunities, find what to automate, or run an internal automation audit across an organization. For building a specific automation→uipath-rpa, authoring a Flow→uipath-maestro-flow, working with agents→uipath-agents."
+description: "UiPath automation discovery — mines Slack/email/wikis/CRM/HRIS/ERP for repetitive work, SPOFs, and replicable models; produces a 4-tier prioritized opportunity report with UiPath implementation paths, then sizes build effort (complexity band → pack-hours → contingency). Use to discover automation opportunities, find what to automate, estimate/size a delivery, or run an internal automation audit across an organization. For building a specific automation→uipath-rpa, authoring a Flow→uipath-maestro-flow, working with agents→uipath-agents."
 ---
 
 # Automation Discovery
@@ -15,6 +15,7 @@ UiPath-ready backlog with recommended implementation paths.
 - User wants to **find manual work to automate** and build a UiPath implementation backlog
 - User asks "what should we automate?" while working with UiPath tools
 - User wants an **internal automation audit** to feed into UiPath Automation Hub or a UiPath pipeline
+- User asks to **estimate / size / cost** discovered opportunities — pack-hours, delivery effort, complexity bands, contingency
 - User explicitly invokes `/uipath-automation-discovery`
 
 ## Critical Rules
@@ -24,6 +25,7 @@ UiPath-ready backlog with recommended implementation paths.
 3. **Verify access before mining.** Test each data source with a minimal read-only operation. If access fails, note it and move on — don't block discovery.
 4. **Evidence over opinion.** Every opportunity (Tiers 1-3) must cite a specific source, quantitative metric, and affected role or team. No unsupported claims. If a source yields fewer than 5 signals, mark all findings from that source as low-confidence. Do not promote low-confidence findings above Tier 3, except per Rule 5.
 5. **Replication is always Tier 1.** A proven model backed by a working automation that could replicate elsewhere is the highest-value finding — this overrides Rule 4's Tier 3 cap. If the replicable model's source has fewer than 5 signals, classify as Tier 1 with a low-confidence flag until corroborated by a second source. Always lead with replicable models. Never skip the replicable-model search (Phase 2C).
+6. **Never invent pack-hours or complexity thresholds (Phase 4.5).** When estimating build effort, the band→hours numbers and matrix thresholds come from the user-supplied Core RPA / Agentic complexity matrices and Pack-Hours catalogue. Do NOT recall or fabricate them — if they are not supplied, STOP and ask. Adjustment-factor and contingency percentages are `[CALIBRATE]` defaults the user confirms against actuals. Fabricated numbers recreate the estimation error this phase exists to prevent.
 
 ## Workflow Overview
 
@@ -33,6 +35,7 @@ Phase 1: MINE      → Gather raw data from all verified sources
 Phase 2: ANALYZE   → Extract patterns, SPOFs, replicable models, gaps
 Phase 3: REFLECT   → Layer on business strategy for strategic gaps
 Phase 4: REPORT    → Produce prioritized report with 4 tiers
+Phase 4.5: ESTIMATE→ Size build effort (band → pack-hours → contingency) — on request
 Phase 5: HANDOFF   → Map opportunities to UiPath implementation skills
 ```
 
@@ -189,6 +192,25 @@ tier definitions, evidence standards, and platform-specific guidance.
 - ROI benchmarks from existing projects included
 - Strategic analysis ties to real financials
 
+## Phase 4.5: ESTIMATE (optional — on request)
+
+Run only when the user wants build-effort sizing (pack-hours, delivery
+estimate, complexity bands, contingency). Sizes each prioritized opportunity:
+opportunity → complexity band → pack-hours → adjustment factors → contingency →
+total. This is delivery/pre-sales sizing — distinct from the ROI/hours-saved
+impact already in the report.
+
+The band→hours numbers and matrix thresholds are **authoritative references the
+user supplies** (Core RPA + Agentic complexity matrices, Pack-Hours catalogue) —
+never invented (Critical Rule 6). Ask for them if absent. The method adds the
+pieces that were missing: an above-ceiling/decompose rule (>7 apps / >8
+variations), a multi-entity redeploy factor, an existing-automation rebuild
+discount, confidence-tiered contingency, and one unified band→hours mapping that
+resolves the Tool vs Process-Automation grain.
+
+See [references/estimation-guide.md](references/estimation-guide.md) and
+[assets/templates/estimation-worksheet-template.md](assets/templates/estimation-worksheet-template.md).
+
 ## Phase 5: HANDOFF
 
 Map each Tier 1-2 opportunity to a UiPath implementation path. Add a
@@ -223,6 +245,7 @@ each phase with a brief summary and ask if the user wants to adjust scope.
 - [references/intake-guide.md](references/intake-guide.md) — Phase 0 detailed steps (company context, tool inventory, access verification, privacy)
 - [references/mining-guide.md](references/mining-guide.md) — Per-source search guidance (load during Phase 1)
 - [references/report-template.md](references/report-template.md) — Output structure, tier definitions, and evidence standards (load during Phase 4)
+- [references/estimation-guide.md](references/estimation-guide.md) — Estimation accelerator: opportunity → band → pack-hours → contingency (load during Phase 4.5, on request)
 
 ## Anti-patterns
 
@@ -232,3 +255,5 @@ each phase with a brief summary and ask if the user wants to adjust scope.
 - **Promising ROI without source citations.** Every ROI estimate must reference an existing project benchmark or explicit data point.
 - **Skipping the replicable-model search.** The highest-value findings are always proven models that can replicate. Never skip Phase 2C.
 - **Speculating from insufficient evidence.** Below signal threshold → mark low confidence. Insufficient evidence → don't promote to Tier 1-3.
+- **Fabricating pack-hours or matrix thresholds (Phase 4.5).** The band→hours numbers are authoritative user-supplied references. Guessing them recreates the estimation error the accelerator exists to prevent — stop and ask for the catalogue and matrices.
+- **Clamping oversized opportunities at "High".** A cluster over the matrix ceiling (>7 apps / >8 variations) must be decomposed and summed, not sized as a single "High" unit — this was the largest source of under-estimation.

package/skills/uipath-automation-discovery/assets/templates/estimation-worksheet-template.md

@@ -0,0 +1,80 @@
+# Estimation Worksheet — <ENGAGEMENT / CUSTOMER>
+
+Generated by: uipath-automation-discovery
+
+> **Numbers below marked `[FROM CATALOGUE]` come from the user-supplied
+> Pack-Hours catalogue and complexity matrices — never invented.** Values marked
+> `[CALIBRATE]` are default assumptions to confirm against actuals before the
+> estimate is treated as final. See
+> [references/estimation-guide.md](../../references/estimation-guide.md).
+
+## 1. Sources
+
+| Artifact | Provided? | Reference / path |
+|---|---|---|
+| Opportunity register | | <path or Phase 4 report> |
+| Core RPA complexity matrix | | <path> |
+| Agentic complexity matrix | | <path> |
+| Pack-Hours catalogue | | <path> |
+| Benchmark (Delivery Summary) | | <path, if any> |
+
+## 2. Unified band→hours mapping
+
+Filled from the Pack-Hours catalogue. One row per band × grain.
+
+| Complexity band | Grain | Core RPA hours | Agentic add-on hours | Catalogue source |
+|---|---|---|---|---|
+| Simple | Process-Automation | `[FROM CATALOGUE]` | `[FROM CATALOGUE]` | <ref> |
+| Simple | Tool | `[FROM CATALOGUE]` | — | <ref> |
+| Medium | Process-Automation | `[FROM CATALOGUE]` | `[FROM CATALOGUE]` | <ref> |
+| Medium | Tool | `[FROM CATALOGUE]` | — | <ref> |
+| High | Process-Automation | `[FROM CATALOGUE]` | `[FROM CATALOGUE]` | <ref> |
+| High | Tool | `[FROM CATALOGUE]` | — | <ref> |
+
+## 3. Per-opportunity estimate
+
+| # | Opportunity | Grain | Band | Base hours (source) | Redeploy factor | Rebuild discount | Confidence | Contingency % | Total hours |
+|---|---|---|---|---|---|---|---|---|---|
+| 1 | <name> | <Process / Tool> | <band> | <hrs> (`[FROM CATALOGUE]`) | <×N entities> | <−%> | <H/M/L> | `[CALIBRATE]` | <total> |
+| 2 | | | | | | | | | |
+
+Show the math per row: `total = (base ± factors) × (1 + contingency)`.
+
+## 4. Above-ceiling decomposition log
+
+For any opportunity > 7 apps or > 8 variations, decomposed and summed.
+
+| Parent opportunity | Trigger (apps / variations) | Sub-unit | Grain | Band | Hours |
+|---|---|---|---|---|---|
+| <name> | <e.g. 11 apps> | <sub-automation> | <grain> | <band> | <hrs> |
+| | | <sub-automation> | | | |
+| | | **Parent subtotal** | | | <sum> |
+
+## 5. Calibration register
+
+Every assumption the user must confirm before the estimate is final.
+
+| Assumption | Default used | Confirmed value | Basis |
+|---|---|---|---|
+| Multi-entity redeploy increment | `[CALIBRATE ~15-30%]` per extra entity | | |
+| Existing-automation rebuild discount | `[CALIBRATE ~20-40%]` | | |
+| Contingency — High confidence | `[CALIBRATE ~10-15%]` | | |
+| Contingency — Medium confidence | `[CALIBRATE ~20-30%]` | | |
+| Contingency — Low confidence | `[CALIBRATE ~40%+]` | | |
+
+## 6. Scenario roll-up
+
+| Scenario | Assumptions | Portfolio total (h) |
+|---|---|---|
+| Option 1 — conservative full-build | no decomposition reuse, high contingency | <sum> |
+| Option 2 — decomposition + reuse + redeploy | rebuild discount + redeploy factor applied | <sum> |
+
+## 7. Benchmark reconciliation (if a benchmark exists)
+
+| Line | Hours |
+|---|---|
+| This worksheet (chosen scenario) | <sum> |
+| Benchmark (Delivery Summary) | <hrs> |
+| **Delta** | <diff> |
+
+**Delta drivers:** <attribute each material gap to a band, factor, or decomposition decision>

package/skills/uipath-automation-discovery/references/estimation-guide.md

@@ -0,0 +1,104 @@
+# Estimation Accelerator
+
+Size the **build effort** of a prioritized opportunity register: opportunity →
+complexity band → pack-hours → adjustment factors → contingency → total. Runs
+after Phase 4 (the report already carries the register + per-opportunity
+confidence). This is delivery/pre-sales sizing, not the ROI/hours-saved impact
+in the report.
+
+Load when the user asks to estimate, size, cost, or produce pack-hours /
+effort / a delivery estimate for discovered opportunities.
+
+## Hard rule — never invent pack-hours
+
+The band→hours numbers and the complexity-matrix thresholds are **authoritative
+UiPath references the user supplies** — the Core RPA complexity matrix, the
+Agentic complexity matrix, and the Pack-Hours catalogue. Do NOT recall,
+approximate, or fabricate them. Unverified numbers are the exact failure this
+accelerator exists to prevent.
+
+1. If the user has not supplied the Pack-Hours catalogue and the complexity
+   matrices, STOP and ask for them (file paths or pasted tables). Do not
+   proceed with guessed hours.
+2. Every band→hours value written to the worksheet cites its catalogue source.
+3. Adjustment-factor and contingency percentages below are **not** authoritative
+   — they are `[CALIBRATE]` defaults the user tunes against the org's actuals
+   before the estimate is final.
+4. Show the math for every opportunity (base → factors → contingency → total)
+   so each number is auditable.
+
+## Inputs
+
+| Input | Source | Notes |
+|---|---|---|
+| Opportunity register | Phase 4 report, or user `.xlsx` | Per opportunity: apps touched, variations / decision points, data & exception complexity, agentic vs deterministic, rebuild-of-existing?, deploy entity count |
+| Core RPA complexity matrix | **User-supplied** | Band thresholds (apps, variations, data, exceptions) |
+| Agentic complexity matrix | **User-supplied** | Band thresholds for reasoning steps, tools, autonomy, HITL |
+| Pack-Hours catalogue | **User-supplied** | Band × grain → hours |
+| Benchmark (optional) | Delivery Summary / official estimate | For reconciliation |
+
+## Procedure — per opportunity
+
+1. **Determine grain.** Is the unit a **Process-Automation** (end-to-end
+   process) or a **Tool** (reusable component / pack invoked by processes)?
+   Price at the matching grain — a decomposed sub-unit is often Tool-grain.
+   Grain ambiguity was a root cause of the estimate divergence; resolve it
+   explicitly and record it.
+2. **Classify complexity** on the matrix dimensions: deterministic RPA work →
+   Core RPA matrix; agentic/reasoning components → Agentic matrix. A hybrid
+   opportunity carries both a Core RPA band and an Agentic add-on.
+3. **Assign band** (Simple / Medium / High) from the matrix — unless the
+   above-ceiling rule fires.
+4. **Above-ceiling / decompose rule.** If an opportunity exceeds the matrix
+   ceiling — **> 7 applications OR > 8 variations / decision points** — do NOT
+   clamp it to "High". Decompose into sub-automations (by sub-process or
+   application cluster), classify and size each at its own grain, and sum.
+   Record the decomposition. Clamping oversized clusters at "High" is the
+   single largest source of under-estimation — this rule is the primary fix.
+5. **Map band → base pack-hours** from the supplied catalogue at the resolved
+   grain. Cite the catalogue row.
+6. **Apply adjustment factors** (`[CALIBRATE]` defaults — confirm against
+   actuals):
+   - **Multi-entity redeploy:** same automation deployed across N legal
+     entities / regions → do NOT count each as a full build. `base + (N-1) ×
+     [CALIBRATE ~15-30%] × base` per additional entity; raise it when per-entity
+     localization or regulatory variation is significant.
+   - **Existing-automation rebuild discount:** rebuilding / migrating an
+     automation that already exists (known logic, documented process) →
+     `[CALIBRATE ~20-40%]` reduction vs greenfield, scaled by reuse and
+     documentation quality.
+7. **Add confidence-tiered contingency**, keyed to the opportunity's discovery
+   confidence: High `[CALIBRATE ~10-15%]`, Medium `[~20-30%]`, Low / ambiguous
+   scope / unknown systems `[~40%+]`.
+8. **Total** = (base ± factors) × (1 + contingency). Write base, each factor,
+   contingency, and total to the worksheet.
+
+## Unified band→hours mapping (ask #3)
+
+Replace the disconnected matrix-image + catalogue pair with one table so band,
+grain, and hours live together. Fill values from the user's catalogue:
+
+| Complexity band | Grain | Core RPA hours | Agentic add-on hours | Catalogue source |
+|---|---|---|---|---|
+| Simple | Process-Automation | `[FROM CATALOGUE]` | `[FROM CATALOGUE]` | `<ref>` |
+| Simple | Tool | `[FROM CATALOGUE]` | — | `<ref>` |
+| Medium | … | … | … | … |
+| High | … | … | … | … |
+| Above-ceiling | (decompose) | sum of sub-units | sum of sub-units | — |
+
+## Scenarios & reconciliation
+
+- Produce ≥ 2 scenarios (e.g. **Option 1** conservative full-build; **Option 2**
+  with decomposition + rebuild discount + redeploy factor applied). The source
+  engagement delivered three (16.2k / 12.1k / 10.7k h) — the spread comes from
+  these factors, not from different base numbers.
+- When a benchmark estimate exists, reconcile the portfolio total against it and
+  attribute each material delta to a band, factor, or decomposition decision.
+
+## Output
+
+Use [assets/templates/estimation-worksheet-template.md](../assets/templates/estimation-worksheet-template.md):
+per-opportunity estimate table, the unified band→hours mapping, the
+decomposition log, the calibration register (every `[CALIBRATE]` value awaiting
+confirmation), and the scenario roll-up. Append an **Estimation** section to the
+Phase 4 report, or emit a standalone worksheet.

package/skills/uipath-connector-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-connector-builder
-description: "UiPath Integration Service connector authoring (REST+JSON) on disk via `uip is connectors builder`. Triggers on `element.json`, `element-metadata.json`, `standard-resources/*.json`, a `periodic-uipath-*`/`periodic-design-*` connector repo, or any request to build/edit an IS connector: init the connector shell, configure auth (14 types via `auth set`), add activities with fields/params/methods/hooks, wire polling/webhook triggers, add auth-system resources, inspect, validate, and surgically read/write files via state. Import + publish live on the parent `uip is connectors` (need `uip login`). NOT for operating a published connector — connections, ping, run an activity→uipath-platform; NOT for `.flow` connector nodes→uipath-maestro-flow."
+description: "UiPath Integration Service connector authoring (REST+JSON) on disk via `uip is connectors builder`. Triggers on `element.json`, `element-metadata.json`, `standard-resources/*.json`, a `periodic-uipath-*`/`periodic-design-*` connector repo, or any request to build/edit an IS connector: init the connector shell, configure auth (19 types via `auth set`, incl. jwtOauth claims, FPS, none), add activities with fields/params/methods/hooks, wire polling/webhook triggers, add auth-system resources, inspect, validate, and surgically read/write files via state. Import + publish live on the parent `uip is connectors` (need `uip login`). NOT for operating a published connector — connections, ping, run an activity→uipath-platform; NOT for `.flow` connector nodes→uipath-maestro-flow."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
 ---
 
@@ -25,7 +25,7 @@ Author UiPath Integration Service connectors on disk with `uip is connectors bui
 3. **`auth set` owns all authentication.** It writes the config entries, `authentication.type` / `typeOauth` / `authenticationTypes`, and the token-refresh resource in one call. Define scopes here too (`--scope`, `--scope-options`, `--required-scopes`, `--preselected-scopes`) — there is no separate scope command. `init --auth oauth2|customApiKey` is inline sugar for the create-time common case; everything else goes through `auth set`. Never hand-roll auth via `state patch`.
 4. **`activity create` writes both sides in one call** — the standard-resource file AND one `element.json` entry per method. Re-running on an existing activity appends/merges. Pass `--skip-sr` (or use `auth system create`) only for system resources that need no SR file. Model `GETBYID`/`PATCH`/`PUT`/`DELETE` only for TRUE by-id endpoints — never for search. The `/{primaryKey}` path param is added automatically: ALWAYS for `GETBYID`, and for `PATCH`/`PUT`/`DELETE` only when the activity is CRUD (it also has a `GET`/`GETBYID`); a write-only/action activity keeps its base path.
 5. **`state patch` REPLACES the whole node at a pointer (no merge).** To change one field: `state query` the entry, edit it, then `state patch` the COMPLETE object back. `element-metadata.json` has no addressable sub-paths — round-trip the whole file. Activity paths in pointers are URL-encoded: `/contacts` → `%2Fcontacts`. Use the dedicated authoring verbs for creation, not `state patch`.
-6. **Connector targeting.** Builder verbs walk up from the cwd, then scan immediate subdirectories — run from inside the connector dir, or pass `--connector-dir <PATH>` to target one explicitly (required when multiple connectors are nearby). `import` reads `--connector-dir` the same way (the connector root holding `app/element/element.json`); on `download` it instead names the OUTPUT directory to write the pulled connector into. **Exception — `init` does NOT scan subdirectories** (it would otherwise resolve a SIBLING connector and silently EDIT/rename it): to CREATE, run `init` from a fresh/empty directory (a dir that merely *contains* connector subdirs — e.g. `/tmp` — creates a new connector, it will not dive into a child to edit it); to EDIT, run from inside the connector or pass `--connector-dir`.
+6. **Connector targeting.** Builder verbs walk up from the cwd, then scan immediate subdirectories, then fall back to the `.uip-connector.json` marker `init` writes in the directory it ran from — so follow-up commands from that same directory hit the last-init connector automatically, even next to other connector dirs. Pass `--connector-dir <PATH>` to override or when working from elsewhere. `import` reads `--connector-dir` the same way (the connector root holding `app/element/element.json`); on `download` it instead names the OUTPUT directory to write the pulled connector into. **Exception — `init` does NOT scan subdirectories** (it would otherwise resolve a SIBLING connector and silently EDIT/rename it): to CREATE, run `init` from a fresh/empty directory (a dir that merely *contains* connector subdirs — e.g. `/tmp` — creates a new connector, it will not dive into a child to edit it); to EDIT, run from inside the connector or pass `--connector-dir`.
 7. **Output is the `{Result, Code, Data}` envelope.** Add `--output json` to parse it. Failures exit non-zero. Never suppress stderr.
 8. **`import` / `download` / `publish` — and `init` when CREATING — need `uip login`.** Authenticate before any tenant pull/push. A NEW connector's key `design-{org}-{slug}` takes its org from your logged-in session, so `init` create ERRORS when you're not logged in. Let it derive the org; do NOT pass a guessed `--organization` (a wrong org bakes into the key and only surfaces, mismatched, at import/publish) — `--organization <slug>` is only for offline/CI builds with a known org.
 9. **Never echo, log, or hard-code a secret.** Secret config keys (client secret, API key, password, token) are written by `auth set` ENCRYPTED (`encrypt: true`) — most as `PASSWORD` fields, though some (OAuth tokens, a service-account JSON) are encrypted `TEXTFIELD`/`TEXTAREA`. End users supply real credentials at connection time; the connector holds only the auth TYPE + endpoint URLs + scopes. Use placeholders in every example command.
@@ -39,6 +39,7 @@ Decide how each per-connection value reaches the request BEFORE scaffolding —
 - **One config drives the host — not three URLs.** When the base, token, and authorize hosts share a per-connection part (an instance name, region, datacenter, or workspace), surface ONE config and template it into every URL: `init --base-url 'https://{instance}.../api'` + `auth set --token-url 'https://{instance}.../token' --authorization-url 'https://{instance}.../authorize'`. The CLI auto-seeds a single fillable `{instance}` field that resolves all three ([references/configuration.md](references/configuration.md) §Templated hosts). Do NOT expose `base.url`/`oauth.token.url`/`oauth.authorization.url` as separate connection fields.
 - **Open value → TEXTFIELD; fixed set → COMBO.** A free-form instance/workspace/account name is the auto-seeded templated TEXTFIELD — that is a legitimate, common shape, not a smell. Only a genuinely fixed datacenter/environment list becomes a COMBO (`state patch` the seeded entry to `type:COMBO` with `options`, whose `value` can be the host fragment itself).
 - **Derive or discover before you ask.** If a per-connection value (the API host, an org/account id) is returned in the token response or is discoverable via an authenticated call, capture it instead of adding a manual field — but ONLY when it is genuinely needed AND obtainable; a single templated config is the simpler default, so don't over-engineer discovery where a plain field suffices. Token-response host → a `postRequest` hook that validates (https + allowlisted host, never log the token) and persists via `done({configuration})` — recipe: [references/hooks.md](references/hooks.md) §"Pattern: base URL …". Discoverable id → an `onProvision` system resource that calls the lookup at connection time ([references/system-resources.md](references/system-resources.md)).
+- **User-facing configs need guidance.** Every `configScreenType:"pre"` or `"pre-optional"` field should have `hintText` with an example or where to find the value. give every visible connection-form field a hint (`validate` does not currently check this) for instance/workspace IDs, tenant hosts, and token-type-specific credentials.
 - **Multi-datacenter OAuth:** the accounts/token host itself varies by region — template the region config into `--token-url`/`--authorization-url` too, not just the base URL.
 
 ## Workflows
@@ -117,6 +118,7 @@ uip is connectors builder validate
 
 ### Customize a curated activity
 `activity create` auto-curates every method into a standalone Studio activity by default (opt out with `--no-curate`). Use `method curate` only to override the generated name/displayName, or to curate a `--no-curate` method.
+Generic CRUD activities are always present separately from curated activities: List/Get/Create/Update/Delete Records let the user choose any object that supports that method. Do not remove them or report them as pollution when you add a curated/list-capable object; author the curated service action alongside the generic object picker.
 ```bash
 uip is connectors builder activity method curate --resource cases --method GET \
   --display-name 'Get Support Request'
@@ -134,7 +136,7 @@ uip is connectors builder state patch element.json/configuration/oauth.token.url
   --value '<full entry from the query above, with defaultValue corrected>'
 uip is connectors builder validate
 ```
-For a derived base URL (e.g. Salesforce `instance_url` from the token response): a `postRequest` hook VALIDATES the URL (https + allowlisted host) and persists it with `done({configuration})` — NOT `state patch`, which baking-time-edits one org's URL into every connection. Full recipe: [references/hooks.md](references/hooks.md) §"Pattern: base URL …"; investigation checklists: [references/debugging.md](references/debugging.md).
+For a base URL or id derived at connection time: use a token-response `postRequest` hook when the value is returned by the token call, or an `onProvision` system resource when it must be discovered after auth. Validate the value, then persist it with `done({configuration})` — NOT `state patch`, which baking-time-edits one connection's value into every connection. Full recipe: [references/hooks.md](references/hooks.md) §"Pattern: base URL …"; investigation checklists: [references/debugging.md](references/debugging.md).
 
 ## Command Map
 
@@ -171,7 +173,7 @@ Depth lives in `references/` — each self-contained. SKILL.md owns the workflow
 | element.json internals: top-level fields, resources[], parameters[], value interpolation, hook order | [references/element-json.md](references/element-json.md) |
 | Standard-resource files: linking, metadata.method, curated, fields (visibility/design/searchable) | [references/standard-resources.md](references/standard-resources.md) |
 | configuration[] entries: widget types, screen types, per-auth key sets, pagination + event keys | [references/configuration.md](references/configuration.md) |
-| Authentication setup: all 14 auth types and the OAuth/JWT scope surface | [references/auth.md](references/auth.md) |
+| Authentication setup: all 19 auth types (incl. JWT Bearer claims, FPS, none) and the OAuth/JWT scope surface | [references/auth.md](references/auth.md) |
 | Auth-system resources: auth-validation, onProvision/onDelete, OAuth token overrides | [references/system-resources.md](references/system-resources.md) |
 | When to write a hook vs use a built-in (decision table + good/avoidable patterns), execution order, context vars, done(), naming | [references/hooks.md](references/hooks.md) |
 | Polling and webhook triggers: config keys, event.poller.configuration schema | [references/events.md](references/events.md) |