@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-review/references/agents/agent-grading-rubric.md

@@ -0,0 +1,133 @@
+# Agent Review — Letter Grade (A–F)
+
+How the review computes the letter grade for **agent projects** (low-code `agent.json` and coded `main.py`). Run this in **Step 4.5**, after agent validation (Step 2), the review CLI + judgment catalog (Step 2.5), manual review (Step 3), and optimization + architecture scoring (Step 4) — the grade is a function of those outputs, never a fresh judgment.
+
+> Scope: agents only, matching the skill's phase-1 model (the Step 2.5 judgment catalog is agent-only today; RPA, flows, and coded apps are future phases). Do **not** grade non-agent projects with this rubric. When a solution mixes agents with other types, grade the agent projects and leave the others ungraded (note "grading: agents only, phase 1").
+
+The grade has two sub-grades, computed independently, then gated:
+
+```
+Final grade = min(G_det, G_jud)
+```
+
+- **G_det** — deterministic sub-grade. **Read it directly from the review CLI** — do not recompute it. `uip agent review` / `uip codedagent review` returns `Data.Grade`, the grade it assigns to its own deterministic checks. That letter **is** G_det.
+- **G_jud** — non-deterministic sub-grade. Driven by judgment: the agent judgment catalog ([agents-common-rules.md](agents-common-rules.md) + the format file) read in Step 2.5b, the manual agent checklist ([agent-review-checklist.md](agent-review-checklist.md)) in Step 3, and the architecture-principle scores (1–5) from [architecture-assessment-guide.md §4](../architecture-assessment-guide.md).
+
+`min()` means an agent cannot earn an A from a clean CLI grade if its prompt, tools, and error handling are weak (G_jud gates it down), and cannot earn an A from strong design if the CLI's deterministic grade is poor (G_det gates it down). The grade is bounded by the weaker dimension. Because `min` only ever lowers the CLI grade, the **skill grade is always ≤ `Data.Grade`**.
+
+## G_det — read it from the review CLI, never recompute
+
+`uip agent review` / `uip codedagent review` already runs every deterministic check (structural/schema, placeholder cross-refs, eval counts/diversity, secret & import regex, framework symbol existence, packaging/git hygiene) and grades them. Read the grade from the JSON response and use it verbatim:
+
+```
+G_det = <response>.Data.Grade        # e.g. "B"
+```
+
+The response also carries `Data.Verdict` (PASS/FAIL) and `Data.Score`; `Data.Grade` is the letter to use.
+
+**Do not tally `Data.Issues[]` and re-derive a grade.** Recomputing duplicates work the CLI already did and risks drifting from the CLI's own grade — the exact inconsistency this design avoids. The deterministic findings (`Data.Issues[]`) are still carried into the report verbatim (Step 2.5a), but the *grade* comes from `Data.Grade`, not from counting them.
+
+If `Data.Grade` is missing or the CLI is unavailable, see [Edge cases](#edge-cases).
+
+## G_jud — the judgment sub-grade you compute
+
+This is the only sub-grade the agent computes, because no CLI can grade it reliably.
+
+**Step 1 — Architecture-average base.** Average the applicable principle scores (1–5) from [architecture-assessment-guide.md §4](../architecture-assessment-guide.md): Modularity, Resilience, Maintainability, Security, Governance. **Scalability is usually N/A for a single agent** — exclude it (and any other principle that does not apply) and average the rest; **state which were excluded** in the report. Score against agent-appropriate evidence: Modularity = prompt/tool decomposition, Resilience = error handling around LLM/tool calls, Maintainability = prompt and tool clarity + eval coverage, Security = secret handling + guardrails, Governance = tracing + eval sets + versioning.
+
+| Architecture average | base G_jud |
+|---|---|
+| 4.5 – 5.0 | **A** |
+| 3.5 – 4.49 | **B** |
+| 2.5 – 3.49 | **C** |
+| 1.5 – 2.49 | **D** |
+| 1.0 – 1.49 | **F** |
+
+**Step 2 — Judgment-finding cap.** The principle scores already absorb most judgment findings (a "no error handling around `llm.ainvoke`" finding is why Resilience scored 2). Apply only one additional cap, to catch a blocking design flaw the averaged scores understate:
+
+- Any **unmitigated judgment Critical** caps G_jud at **D**.
+- A judgment Critical with **security or data-integrity** impact (prompt-injection exposure, secret leak into tool args, no guardrail on a destructive tool) caps G_jud at **F**.
+
+Do not apply further per-Warning deductions — that double-counts against the principle scores.
+
+> Findings from the review CLI (`Data.Issues[]`) already shaped `Data.Grade` = G_det — do **not** also let them cap G_jud. Only **judgment** findings (Step 2.5b catalog + Step 3 manual) feed G_jud. This keeps each finding in exactly one sub-grade.
+
+## Final grade and rationale
+
+`Final = min(G_det, G_jud)` where `G_det = Data.Grade`. Always report the **binding constraint** in one line so the grade is auditable:
+
+```
+Agent Grade: B — gated by G_det (CLI Data.Grade B). Design is strong (G_jud A, arch avg 4.5).
+```
+
+Map the letter to the verdict word (this is the only place the letter→word mapping lives; the bands that produce each letter live above / in the CLI):
+
+| Grade | Verdict label |
+|---|---|
+| **A** / **B** | Good |
+| **C** / **D** | Needs Improvement |
+| **F** | Critical Issues |
+
+## Per-agent vs overall
+
+- **Per-agent grade:** read `Data.Grade` (G_det) and compute G_jud for the agent; grade = `min`. Report in the Per-Project Summary table (Step 5) for each agent row; leave non-agent rows ungraded (`—`).
+- **Single-agent review:** the overall Agent Grade IS the agent's grade.
+- **Solution with multiple agents:** the overall Agent Grade = the **worst** per-agent grade. A solution is only as deployable as its weakest agent — do not average grades. Non-agent projects do not contribute a grade (phase 1).
+
+## Edge cases
+
+| Situation | Handling |
+|---|---|
+| **`Data.Grade` absent** (older CLI returns only `Data.Verdict` / `Data.Score`) | Map what the CLI gives you: `Data.Verdict = FAIL` → G_det = F; otherwise translate `Data.Score` to the nearest A–F using the same band widths the CLI documents. Note the substitution in "Rules Skipped". |
+| **Review CLI unavailable** (no `agent review` / `codedagent review`) | No `Data.Grade` to read. Report the grade as **G_jud alone**, explicitly flagged: "G_det unavailable — review CLI not installed; grade reflects judgment only." Do not fabricate a deterministic grade by counting `agent validate` output. |
+| **`uip agent validate` (Step 2) reports a blocking Error** not reflected in `Data.Grade` | A project that fails validation is not deployable — floor the final grade at **F** regardless of `Data.Grade`, and cite the validate Error as the binding constraint. |
+| **No PDD available** | Business-logic alignment is ungraded. Compute the grade from technical quality only and add: "Grade reflects technical quality; business-logic alignment unverified (no PDD)." |
+| **No eval set present** | Governance/Maintainability scores lose their eval-coverage signal — score the remaining evidence and note the eval gap rather than forcing a low score. |
+
+## Alignment with the review CLI's `Data.Grade`
+
+Because **G_det = `Data.Grade`** and the final grade is `min(G_det, G_jud)`:
+
+- The skill grade **equals** `Data.Grade` when G_jud ≥ `Data.Grade` (judgment/design does not drag it down).
+- The skill grade is **lower** than `Data.Grade` when G_jud is worse (weak prompt/tool design, a judgment Critical) — the skill adds the judgment dimension the CLI does not assess.
+- The skill grade is **never higher** than `Data.Grade` (min only lowers).
+- Report both, and state the gap in one line when they differ: "CLI Data.Grade A (deterministic checks); skill grade C — G_jud gated by thin prompt/tool design (arch avg 3.2)."
+
+## Determinism contract
+
+- **G_det is reproducible because it is the CLI's deterministic grade** — same agent, same `Data.Grade`, every run. The skill does not recompute it.
+- **G_jud is reproducible given the principle scores** — reason from the same evidence (architecture-assessment-guide.md §4 criteria + the judgment catalog) in the same order so the scores, and therefore the grade, are stable run-to-run.
+- The grade is **derived, never asserted.** Every grade must trace to `Data.Grade` (G_det), the G_jud average, and the `min()` binding constraint. A grade with no shown derivation is invalid.
+- Do not introduce grade values outside `A` / `B` / `C` / `D` / `F`. No `+`/`-` modifiers, no `A*`, no numeric-only grade.
+
+## Worked examples
+
+**Example 1 — clean CLI grade, average design.**
+- G_det = `Data.Grade` = **B** (read from `uip codedagent review`).
+- G_jud: arch avg = (Modularity 4 + Resilience 4 + Maintainability 4 + Security 4 + Governance 3) / 5 = 3.8 (Scalability N/A) → **B**. No judgment Critical.
+- Final = min(B, B) = **B — Good.** Binding: both.
+
+**Example 2 — strong CLI grade, but thin prompt and no error handling.**
+- G_det = `Data.Grade` = **A**.
+- G_jud: arch avg = (Modularity 2 + Resilience 2 + Maintainability 2 + Security 3 + Governance 2) / 5 = 2.2 → **D**.
+- Final = min(A, D) = **D.** Binding: G_jud — prompt/tool/error-handling quality (arch avg 2.2). A clean CLI grade does not rescue a weak design.
+
+**Example 3 — strong design, but a tool description leaks a secret into args.**
+- G_det = `Data.Grade` = **A** (the CLI's regex did not catch this semantic leak).
+- G_jud: arch avg 4.3 → **B**, but a judgment Critical with secret-leak (data-integrity) impact → cap at **F**.
+- Final = min(A, F) = **F.** Binding: G_jud security cap — a secret-leak Critical blocks deployment regardless of design.
+
+**Example 4 — CLI grade diverges from skill grade.**
+- G_det = `Data.Grade` = **A** (deterministic checks pass).
+- G_jud: arch avg over applicable principles (Scalability excluded) = (Modularity 3 + Resilience 3 + Maintainability 3 + Security 4 + Governance 3) / 5 = 3.2 → **C**. One judgment Warning on prompt quality (no cap).
+- Final = min(A, C) = **C.** Report: "CLI Data.Grade A (deterministic); skill grade C — G_jud gated by thin prompt/tool design (arch avg 3.2). Scalability excluded (N/A for low-code agent)."
+
+## Anti-patterns
+
+1. **Do not recompute G_det from finding counts.** Read `Data.Grade` from the review CLI. Recomputing risks disagreeing with the CLI's own grade.
+2. **Do not grade non-agent projects with this rubric.** It is agent-scoped (phase 1). RPA, flows, and coded apps get a grade when their rubric is authored.
+3. **Do not let a deterministic blocker average away.** This is a hard gate (`min`), not a weighted blend — a security/data-integrity judgment Critical forces F regardless of `Data.Grade`.
+4. **Do not double-count a finding.** CLI findings already shaped `Data.Grade` (G_det); only judgment findings feed G_jud.
+5. **Do not invent `+`/`-` or numeric grades.** Five letters only: A / B / C / D / F.
+6. **Do not average per-agent grades** for the overall solution grade — take the worst.
+7. **Do not restate the CLI's `Data.Grade` as the skill grade.** They differ whenever G_jud is lower; report both.

package/skills/uipath-review/references/agents/agent-review-checklist.md

@@ -97,13 +97,33 @@ Before reviewing implementation details, verify the right agent type was chosen:
 
 | Check | Severity | How to Verify |
 |---|---|---|
-| PII detection configured (if handling personal data) | Warning | Check guardrails array *(rule: `LC_GUARDRAIL_PII_MISSING`)* |
-| Prompt injection guardrails enabled (if user-facing) | Warning | Check guardrails config *(rule: `LC_GUARDRAIL_INJECTION_MISSING`)* |
+| Recommended guardrails present for the agent's use cases — e.g. PII detection when it handles personal data, injection protection for free-text input, content-safety for generated content, a tool audit-log for sensitive tools | Info | Compare agent context vs catalog use cases; the finding names the recommended scope and action (a blocking/escalating action for protection, a log action for audit) *(rule: `LC_GUARDRAIL_RECOMMENDED`)* |
+| No guardrail misapplied to an agent that shouldn't have it (e.g. PII on a generate-only agent) | Warning | Compare guardrail vs agent purpose / catalog `when_not_to_use` *(rule: `LC_GUARDRAIL_MISAPPLIED`)* |
 | Each guardrail has `name` and `description` | Warning | Walk guardrails *(rule: `GUARDRAIL_NO_NAME`, `GUARDRAIL_NO_DESCRIPTION`)* |
 | Tool resources have `guardrail.policies` array (Studio Web rejects without it) | Critical | Walk tool resources *(rule: `LOWCODE_TOOL_GUARDRAIL_FIELD_MISSING`)* |
 | Tool-scoped guardrails reference existing tools | Critical | Walk Tool-scope guardrails *(rule: `LOWCODE_GUARDRAIL_TOOL_REF_NONEXISTENT`, `GUARDRAIL_TOOL_SCOPE_NO_MATCHNAMES`)* |
 | Custom tool guardrails for destructive operations | Info | Check tool guardrail rules |
-| Guardrail actions appropriate (Log/Block/Escalate) | Info | Review action types |
+| Guardrail action fits its scope — a blocking/escalating action at scopes meant to prevent a violation (Agent, Llm), a log action only for an audit trail (e.g. on a tool that legitimately needs the data). A log action at a prevention scope (Agent or Llm) is ineffective: it records the violation but does not stop it. | Warning | Review action vs scope vs catalog `when_not_to_use` *(rule: `LC_GUARDRAIL_ACTION_INEFFECTIVE`)* |
+
+**Guardrail format (built-in validators).** These run in `uip agent review`, which fetches the live validator catalog (`uip agent guardrails list`) when a built-in guardrail is present and validates each one against it. They are skipped (not failed) when the catalog can't be fetched (offline / not authed) — note that in "Rules Skipped" if relevant.
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| `validatorType` is a real validator in the catalog | Critical | *(rule: `GUARDRAIL_UNKNOWN_VALIDATOR`)* |
+| Scope is one the validator allows | Critical | *(rule: `GUARDRAIL_SCOPE_NOT_ALLOWED`)* |
+| Required `validatorParameters` are present | Critical | *(rule: `GUARDRAIL_MISSING_REQUIRED_PARAM`)* |
+| No unknown parameters (incl. params on a validator that takes none) | Warning | *(rule: `GUARDRAIL_UNKNOWN_PARAM`)* |
+| Parameter `$parameterType` matches the validator's type | Critical | *(rule: `GUARDRAIL_PARAM_TYPE_MISMATCH`)* |
+| Parameter values are legal (enum options / map keys / number range) | Critical | *(rule: `GUARDRAIL_PARAM_VALUE_INVALID`)* |
+
+**Guardrail format (custom guardrails).** Pure static — validated against the fixed custom-rule schema, no catalog needed.
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Discriminators present (`$ruleType`, `$selectorType`, `$actionType`) | Critical | *(rule: `GUARDRAIL_CUSTOM_BAD_DISCRIMINATOR`)* |
+| Operator valid for the rule type | Critical | *(rule: `GUARDRAIL_CUSTOM_BAD_OPERATOR`)* |
+| Value type matches the rule type | Critical | *(rule: `GUARDRAIL_CUSTOM_BAD_VALUE`)* |
+| `Tool` scope only, with exactly one tool in `matchNames` | Critical | *(rule: `GUARDRAIL_CUSTOM_SCOPE_INVALID`)* |
 
 ### Memory Management
 

package/skills/uipath-review/references/agents/agents-coded-rules.md

@@ -92,6 +92,13 @@ LLM-judge-only is acceptable when the agent has no tools, no classification outp
 
 ## GuardrailsChecker
 
+> **Agent-builder coded layout** (`agent.json` + `main.py`): the low-code semantic guardrail rules
+> (`LC_GUARDRAIL_RECOMMENDED` / `LC_GUARDRAIL_ACTION_INEFFECTIVE` / `LC_GUARDRAIL_MISAPPLIED`) apply against
+> `agent.json`'s `guardrails[]` via the low-code catalog + [`guardrails/guardrails-review.md`](guardrails/guardrails-review.md)
+> (this layout loads all three catalogs — see the detection table). Guardrail effectiveness/recommendation for
+> **pure-coded** agents (SDK decorators/middleware in `main.py`, no `agent.json`) is future work; use the bucket
+> below for any coded guardrail/policy observation a specific rule doesn't cover.
+
 | rule_id | severity | category | trigger | detection_method | suggested_fix |
 |---|---|---|---|---|---|
 | `CODED_GUARDRAILS_ISSUE` | warning | guardrails | Guardrails / safety / PII observation that no specific rule fits | Use ONLY when no specific rule fits. Coded agents have most safety concerns covered under `## SecurityChecker` (`CODED_PROMPT_USER_INPUT_UNSANITIZED`, `CODED_PII_IN_TRACES`) and the deterministic secret/`.env` checks in the review CLI. Reach here only for guardrail / policy observations none of those cover. | (Defined per finding.) |

package/skills/uipath-review/references/agents/agents-lowcode-rules.md

@@ -81,12 +81,22 @@ One H2 section per checker class (`EvalsChecker`, `SchemaChecker`, `ToolsChecker
 > | `intellectual_property` | Agent generates code or text | Agent, Llm only | PostExecution only |
 > | `user_prompt_attacks` | User-facing agent, jailbreak risk | Llm only | PreExecution only |
 >
-> When recommending the three "platform-documented" types, do NOT cite them by name unless the specific validator is already present in the project's `guardrails` array or agent-builder schema. Instead say: *"Add an appropriate content-safety guardrail supported by this agent layout."*
+> When recommending the three "platform-documented" types, do NOT cite them by name unless the specific validator is already present in the project's `guardrails` array or agent-builder schema. Instead say: *"Add an appropriate content-safety guardrail supported by this agent layout."* This applies to `LC_GUARDRAIL_RECOMMENDED` below.
+
+> **Apply these via the structured workflow.** The guardrail rules below are applied through
+> [`guardrails/guardrails-review.md`](guardrails/guardrails-review.md) — Step 0 (fetch the live
+> `uip agent guardrails catalog` + `list`, 30-min cache) → **Audit Mode** (effectiveness/relevance of existing
+> guardrails) + **Recommend Mode** (missing-guardrail recommendations) — modeled on the `uipath-agents` recommend
+> capability and driven by the same live catalog. **Boundary:** the review CLI (Step 2.5a) owns all
+> FORMAT/SCHEMA/SET-MEMBERSHIP checks (`GUARDRAIL_*` / `GUARDRAIL_CUSTOM_*` / `LOWCODE_*GUARDRAIL*`); the rules
+> below fire only on format-valid guardrails and never re-flag a CLI format finding. If the catalog is
+> unavailable, defer the Audit-Mode rows (Rules Skipped) — see the workflow's Step 0.
 
 | rule_id | severity | category | trigger | detection_method | suggested_fix |
 |---|---|---|---|---|---|
-| `LC_GUARDRAIL_PII_MISSING` | warning | guardrails | Agent processes personal data but has no `pii_detection` guardrail | Read `inputSchema`, `outputSchema`, system prompt. Assess: does the agent process personal data? Infer from field names + descriptions (names, emails, addresses, IDs, health info, financial info). When yes, check `.guardrails[]` for `pii_detection`. Emit when absent. file = `agent.json` (or normalized JSON). | Add a `pii_detection` guardrail (SDK-confirmed; cite by name). |
-| `LC_GUARDRAIL_INJECTION_MISSING` | warning | guardrails | User-facing free-text input but no `prompt_injection` guardrail | Read `inputSchema`. Assess: does it have free-text string fields users can fill with arbitrary content? When yes, check guardrails for `prompt_injection`. Emit when absent. Do NOT recommend `user_prompt_attacks` by name unless already present in the project's config — see validator authority note above. file = `agent.json`. | Add a `prompt_injection` guardrail (SDK-confirmed) or an appropriate injection-protection guardrail supported by this agent layout. |
+| `LC_GUARDRAIL_RECOMMENDED` | info | guardrails | A guardrail is recommended for a use case the agent matches but doesn't cover (one finding per missing guardrail; specifics in the message) | Apply `guardrails/guardrails-review.md` **Recommend Mode**: fetch the live catalog (Step 0); for each catalog entry whose `when_to_use` / `use_cases` / `security_risk_addressed` match the agent (system prompt, schemas, tools) and which is absent from `.guardrails[]`, emit one finding. The message names the guardrail / `security_category`, the matched use case, the recommended scope, and the recommended **action** — **block/escalate** when protection is really needed (PII that must not enter, injection, harmful content) or **log** for audit only (a tool legitimately handles sensitive data). De-dup by `security_category`. Do NOT name a platform-documented validator unless already present (see note above). file = `agent.json` (or normalized JSON). | Add the named guardrail at the catalog-recommended scope/action (cite `examples[].config`): block/escalate for protection, log for audit. |
+| `LC_GUARDRAIL_ACTION_INEFFECTIVE` | judgment | guardrails | A format-valid guardrail's action is ineffective or counterproductive for its scope | Apply `guardrails/guardrails-review.md` **Audit Mode → Actionability**: for each format-valid guardrail (skip ones the review CLI flagged), compare `validator` + `selector.scopes` + action `$actionType` against the catalog entry's `when_not_to_use` / `examples[].config` action for that scope. Emit when counterproductive — a security-critical guardrail at `log` where the example uses `block`; `pii_detection` `Block`/`Filter` at Tool on a tool that needs the PII; `pii_detection` `Log` at Agent/Llm. Name the recommended action. file = `agent.json`, element = guardrail name. | Set the action the catalog recommends for that scope, or move the guardrail to a scope where the action is effective. |
+| `LC_GUARDRAIL_MISAPPLIED` | judgment | guardrails | A guardrail is present but the agent matches the validator's `when_not_to_use` | Apply `guardrails/guardrails-review.md` **Audit Mode → Relevance**: establish the agent's context (system prompt, schemas, tools); for each format-valid guardrail read the catalog entry's `when_not_to_use` / `NOT_recommended_for`. Emit when the agent matches a disqualifying condition (e.g. a generate-only agent with no user input carrying a PII guardrail). Cite the matched clause. file = `agent.json`, element = guardrail name. | Remove the misapplied guardrail, or document why the agent's context differs from the `when_not_to_use` condition. |
 | `LC_GUARDRAIL_EVALS_CONSISTENCY` | judgment | guardrails | `enabledForEvals: true` may interfere with the eval set's intent | Read guardrails. For each with `enabledForEvals: true`, read the eval set. Assess: is the eval set testing guardrail behavior (intentional) or testing agent behavior (where guardrails may interfere)? Emit when intent unclear; reason in the description. file = guardrail source, element = guardrail name. | Set `enabledForEvals: false` for agent-behavior tests, or document that the eval set is specifically testing guardrail behavior. |
 
 ---

package/skills/uipath-review/references/agents/guardrails/guardrails-review.md

@@ -0,0 +1,198 @@
+# Guardrail Review — LLM-as-judge (audit + recommend)
+
+The read-only **review** counterpart of the `uipath-agents` guardrail recommend/validate capability. It powers
+the guardrail judgment rules in [`../agents-lowcode-rules.md`](../agents-lowcode-rules.md) §GuardrailsChecker.
+Run it during a low-code agent review (SKILL.md Step 2.5b) **after** `uip agent review` (Step 2.5a). Two modes:
+
+- **Audit Mode** — the agent already has guardrails → are they *effective and appropriate*? (emits **defects**)
+- **Recommend Mode** — the agent is missing guardrails for use cases it matches → which should it add? (emits
+  **Info recommendations**)
+
+This is **review only** — never write, fix, or `uip agent validate`. The reviewer emits findings; the user
+(or the `uipath-agents` skill) applies them.
+
+> **Boundary with `uip agent review` — do not double-flag.** The review CLI owns every FORMAT / SCHEMA /
+> SET-MEMBERSHIP guardrail check and emits them as `GUARDRAIL_*` / `GUARDRAIL_CUSTOM_*` / `LOWCODE_*GUARDRAIL*`
+> rule IDs (unknown validator, scope-not-allowed, missing/unknown/type-mismatch/value-invalid parameters,
+> custom-rule discriminators/operator/value/scope, tool-ref existence, missing name/description). The rules here
+> fire **only on guardrails the CLI found format-valid**, and judge only what code cannot decide: whether a valid
+> action actually protects at its scope, whether a valid guardrail belongs on this agent at all, and whether a
+> guardrail the agent should have is missing. A format-invalid guardrail is skipped here until it is fixed — do
+> not re-describe its format problem.
+
+Like the recommend capability, this is **live-catalog driven** — the catalog's authored fields (`when_to_use`,
+`use_cases`, `security_risk_addressed`, `when_not_to_use`, `security_category`, `examples[].config`) drive every
+decision. Do not hardcode which guardrail fits which agent.
+
+---
+
+## Step 0 — Fetch Catalog and Available Validators
+
+Run this once when the low-code `agent.json` has a non-empty `guardrails[]` **or** the agent matches any catalog
+use case (so Recommend Mode can run). Same fetch the `uipath-agents` guardrail modes use.
+
+### Catalog (cacheable — 30-minute TTL)
+
+```bash
+python3 -c "
+import os, time
+cache = '.guardrails-catalog-cache.json'
+if os.path.exists(cache) and (time.time() - os.path.getmtime(cache)) < 1800:
+    print('CACHE_HIT')
+else:
+    print('CACHE_MISS')
+"
+```
+
+- **CACHE_HIT**: read `.guardrails-catalog-cache.json` directly.
+- **CACHE_MISS**: fetch and save: `uip agent guardrails catalog --output json > .guardrails-catalog-cache.json`
+  (the CLI writes both success and error JSON to stdout — do not add `2>&1`).
+
+### Guardrails List (NEVER cached — tenant-specific)
+
+```bash
+uip agent guardrails list --output json
+```
+
+Build a `{ validatorId: status }` lookup from the `Data` array (use only `Status == "Available"`).
+
+### If the catalog is unavailable
+
+If the catalog output contains `"Code": "GuardrailCatalogUnavailable"` (or the CLI is unavailable), **do not
+guess**:
+
+- **Audit Mode** (`LC_GUARDRAIL_ACTION_INEFFECTIVE`, `LC_GUARDRAIL_MISAPPLIED`) depends on the catalog → record
+  these rules under the report's "Rules Skipped" subsection with reason `"guardrails catalog unavailable"`
+  (SKILL.md Critical Rule 11). Do not emit catalog-grounded effectiveness/relevance verdicts without it.
+- **Recommend Mode** (`LC_GUARDRAIL_RECOMMENDED`) can still detect a missing guardrail from `agent.json` alone
+  (schema/prompt/tool inference); when the catalog is absent, phrase the recommended scope/action generically
+  and note "catalog-limited" in the message.
+
+---
+
+## Audit Mode — existing guardrails (findings are defects)
+
+For each guardrail in `agent.json`'s `guardrails[]` that the review CLI did **not** flag format-invalid, read
+its `validator`, `selector.scopes`, and action `$actionType`, then run two checks.
+
+### Actionability Check → `LC_GUARDRAIL_ACTION_INEFFECTIVE`
+
+A format-valid guardrail's **action** can be ineffective or counterproductive for its **scope**. Compare the
+configured action against the catalog entry's `when_not_to_use` and its representative `examples[].config`
+action for the chosen scope. Emit when the action is in that scope's invalid set. Canonical cases:
+
+- A **security-critical** guardrail (`security_category` `adversarial_input` / `content_safety`) set to `log`
+  where the catalog example uses `block` — it looks protected but isn't (recommend capability Step 5: *never
+  silently downgrade block → log*).
+- `pii_detection` with `Block` / `Filter` at **Tool** scope on a tool that legitimately needs the PII — the
+  catalog's `when_not_to_use` says *"Do not use at Tool scope with Block or Filter action if the tool requires
+  PII to function (e.g., a SendEmail tool needs the recipient email address)"*; blocking breaks the tool.
+- `pii_detection` with `Log` at **Agent** / **Llm** scope — Log there does **not** prevent PII from entering or
+  reaching the LLM (recommend the blocking action the catalog example uses).
+
+In the description, name the catalog-recommended action for that scope. Severity is `judgment` — a guardrail
+that breaks the agent or leaves a security gap can be Critical; a milder ineffectiveness is Warning/Info.
+
+### Relevance Check → `LC_GUARDRAIL_MISAPPLIED`
+
+Establish the agent's real context (system prompt, `inputSchema`, `outputSchema`, tool resources). Read the
+catalog entry's `when_not_to_use` / `NOT_recommended_for`. Emit when the agent matches a disqualifying condition
+— the guardrail doesn't belong on this agent. Example: a generate-only agent with no user input carrying a PII
+guardrail (PII `pattern_a`: the agent's PII output is the intended product; the guardrail adds no protection and
+may block legitimate output). Cite the matched `when_not_to_use` clause in the description.
+
+---
+
+## Recommend Mode — missing guardrails (findings are Info recommendations)
+
+Reuse the recommend capability's reasoning, but emit findings instead of writing config. **All missing-guardrail
+recommendations use one rule_id — `LC_GUARDRAIL_RECOMMENDED` (Info)** — emitted **once per missing guardrail**,
+with the specifics in the **message**.
+
+### R1 — Read agent context
+
+From `agent.json`: system prompt text, `inputSchema` / `outputSchema` property names + descriptions, tool
+resource names + descriptions (`resources/`), and the existing `guardrails[]` (to avoid recommending what's
+already there).
+
+### R2 — Catalog-driven analysis
+
+For each catalog entry, read `when_to_use`, `use_cases`, `description`, `security_risk_addressed`, and reason:
+does the agent's purpose / data / threat model match? Read `when_not_to_use` and skip the entry if the agent
+matches a disqualifying condition. Cross-reference the Step 0 status lookup — only recommend `Available`
+validators (mention `Unauthorised` ones so the user can ask their admin; skip ones absent from the list).
+
+### R3 — De-duplicate by `security_category`
+
+Group matched candidates by `security_category` + scope + stage. For a group with more than one candidate, drop
+catalog-deprecated entries, keep the single best fit, and mention the alternative in the message. Derive grouping
+and deprecation from the catalog's own fields — do not hardcode validator names.
+
+### R4 — Recommended scope (block as early as possible)
+
+Recommend the outermost PRE scope the validator's `AllowedScopes` permits for input protection (**Agent** > Llm
+> Tool), Agent · POST for output protection, Tool scope only for a genuinely tool-specific concern.
+
+### R5 — Recommended action (the protection-vs-audit signal)
+
+Default to the catalog example's `action_type`, and state which of the two the recommendation is:
+
+- **block / escalate — protection really needed:** security-critical use cases (PII that must not enter,
+  prompt-injection / jailbreak on free-text input, harmful content / IP on generated output). Recommend a
+  blocking/escalating guardrail; say so plainly.
+- **log — audit only:** a tool legitimately handles sensitive data, or the user wants observe-first. Recommend a
+  Tool-scope **log** guardrail for an audit trail — **not** a block that would break the tool.
+
+### Emit the finding
+
+One `LC_GUARDRAIL_RECOMMENDED` (Info) per missing guardrail. The message must carry: which guardrail /
+`security_category`, why (the matched `when_to_use` / `use_cases` item or the data flow), the recommended scope,
+and the recommended action with the protection-vs-audit signal. Cite the catalog's `examples[].config` in the
+fix. Examples:
+
+- *"Recommend a PII-detection guardrail at Agent scope with a **block** action — the input schema carries
+  `customer_email` / `ssn` (data_privacy); blocking at Agent · PRE stops unexpected PII before the LLM.
+  Protection needed: block."*
+- *"Recommend a Tool-scope **log** guardrail on `SendCustomerEmail` for an audit trail — the tool legitimately
+  handles the recipient email; use log (not block) so the tool keeps working. Audit only."*
+
+**Validator-name caution (carry over from the catalog/registry note):** do NOT name a platform-documented
+validator (`harmful_content`, `intellectual_property`, `user_prompt_attacks`) unless it is already present in the
+project's config — phrase generically (e.g. "an appropriate content-safety guardrail supported by this agent
+layout"). `pii_detection` and `prompt_injection` are SDK-confirmed and may be named.
+
+---
+
+## Report
+
+Merge findings into the Step 5 "Rule Findings" subsection (SKILL.md Step 2.5b), canonical line format:
+
+```
+[<prefix><n>] `<rule_id>` — <file> — <message>. Fix: <suggested_fix>.
+```
+
+- Recommendations (`LC_GUARDRAIL_RECOMMENDED`) → **`I-D-` (Info)** — the lowest grade; they are improvements, not
+  failures. The action signal (block/escalate vs log) lives in the message, not the severity.
+- Defects (`LC_GUARDRAIL_ACTION_INEFFECTIVE`, `LC_GUARDRAIL_MISAPPLIED`) → the `judgment` band; pick
+  Critical/Warning/Info by impact and show the reasoning.
+- `file` = `agent.json` (or the normalized JSON); `element` = the guardrail name (defects) or the
+  `security_category` (recommendations).
+
+---
+
+## Critical Rules
+
+1. **Run after `uip agent review` (Step 2.5a)** and only on format-valid guardrails — never double-flag a
+   `GUARDRAIL_*` format finding.
+2. **Catalog-driven, not hardcoded** — every audit verdict and recommendation cites a catalog field
+   (`when_not_to_use`, `when_to_use` / `use_cases`, `examples[].config.action_type`).
+3. **Catalog unavailable → defer Audit Mode** (Rules Skipped), keep Recommend Mode's `agent.json`-only detection
+   with generic wording. Never guess effectiveness/relevance without the catalog.
+4. **Recommendations are one Info rule** (`LC_GUARDRAIL_RECOMMENDED`), one finding per missing guardrail, details
+   in the message; signal **block/escalate** (protection) vs **log** (audit).
+5. **Never silently downgrade block → log** — a security-critical guardrail at `log` is a defect
+   (`LC_GUARDRAIL_ACTION_INEFFECTIVE`), not an acceptable choice, unless the catalog/agent shows a stated reason.
+6. **Do not name platform-documented validators** (`harmful_content` / `intellectual_property` /
+   `user_prompt_attacks`) unless already present — phrase generically. `pii_detection` / `prompt_injection` may
+   be named.
+7. **Review only** — emit findings; never write guardrails, fix `agent.json`, or run `uip agent validate`.

package/skills/uipath-review/references/architecture-assessment-guide.md

@@ -105,6 +105,8 @@ Verify that the solution has proper environment isolation for safe deployment.
 
 Score each principle on a 1-5 scale. Report scores in the review.
 
+> Score these six principles for any project type to inform the optimization review (Step 4). For **agent projects**, their average is also the primary input to **G_jud**, the non-deterministic half of the Step 4.5 agent letter grade — the average maps to a base letter (`4.5–5.0`→A … `1.0–1.49`→F); see [agent-grading-rubric.md](agents/agent-grading-rubric.md). Exclude a principle only when it genuinely does not apply (e.g. queue-style Scalability for a single agent) and state the exclusion. Score honestly — for agents, a generous score here inflates the grade.
+
 ### Modularity (1-5)
 
 | Score | Criteria |

package/skills/uipath-review/references/review-workflow-guide.md

@@ -312,6 +312,7 @@ The review report follows a fixed markdown structure. Produce it in chat — do
 
 ### Summary
 - **Overall Quality:** Good / Needs Improvement / Critical Issues
+- **Agent Grade:** <A–F> — <verdict label> (<binding constraint>) — *agent projects only; see SKILL.md Step 4.5 + [agent-grading-rubric.md](agents/agent-grading-rubric.md). Omit if no agent projects.*
 - **Business Value:** <1-2 sentence description of what this solution does>
 - **Project Types Found:** <list with counts>
 - **Validation Status:** <pass/fail per project>
@@ -342,10 +343,11 @@ The review report follows a fixed markdown structure. Produce it in chat — do
 2. [I-002] ...
 
 ### Per-Project Summary
-| Project | Type | Validation | Quality | Key Findings |
-|---|---|---|---|---|
-| ProjectA | RPA (Coded) | Pass | Good | W-001 |
-| ProjectB | Flow | 2 errors | Needs Work | C-001, W-002 |
+| Project | Type | Validation | Quality | Grade | Key Findings |
+|---|---|---|---|---|---|
+| ClassifierAgent | Agent (Coded) | Pass | Good | B | W-D-002 |
+| ProjectA | RPA (Coded) | Pass | Good | — | W-001 |
+| ProjectB | Flow | 2 errors | Critical Issues | — | C-001, W-002 |
 
 ### Recommended Next Steps
 1. Fix [C-001] using `uipath-rpa` skill
@@ -358,11 +360,13 @@ The review report follows a fixed markdown structure. Produce it in chat — do
 - Transaction handling: <observation and recommendation>
 ```
 
-**Overall Quality determination:**
+**Overall Quality determination** (all project types):
 - **Good** — 0 Critical findings, 0-3 Warnings
 - **Needs Improvement** — 0 Critical findings, 4+ Warnings OR 1 Critical with clear fix
 - **Critical Issues** — 2+ Critical findings OR 1 Critical with security implications
 
+**Agent Grade** (agent projects only): the A–F letter is `min(G_det, G_jud)` computed in SKILL.md Step 4.5 — full rubric, bands, edge cases, and worked examples in [agent-grading-rubric.md](agents/agent-grading-rubric.md). It maps to the same verdict labels (A/B = Good, C/D = Needs Improvement, F = Critical Issues). Non-agent projects carry the Quality verdict only (grading for RPA / flows / coded apps is a future phase).
+
 ## Optimization Evaluation Framework
 
 ### When to Recommend Queues

package/skills/uipath-review/references/rule-catalog-workflow.md

@@ -29,7 +29,7 @@ Parse the JSON. Findings live under `Data.Issues[]`; each issue is:
 }
 ```
 
-The response also carries `Data.Verdict` (PASS/FAIL), `Data.Score`, `Data.Grade`, and `Data.Stats` — report the verdict/score if useful, but the `Issues[]` are the findings. Carry each issue into the report **verbatim**; do not re-derive, rename, or re-rank. These `RuleId`s are authoritative as the CLI emits them and are **not** duplicated in the skill catalog.
+The response also carries `Data.Verdict` (PASS/FAIL), `Data.Score`, `Data.Grade`, and `Data.Stats` — report the verdict/score if useful, but the `Issues[]` are the findings. `Data.Grade` is also consumed as **G_det**, the deterministic half of the Step 4.5 agent letter grade (read it from here, never recompute) — see [agents/agent-grading-rubric.md](agents/agent-grading-rubric.md). Carry each issue into the report **verbatim**; do not re-derive, rename, or re-rank. These `RuleId`s are authoritative as the CLI emits them and are **not** duplicated in the skill catalog.
 
 If the review command is unavailable (CLI not installed, or a version without `agent review` / `codedagent review`), record one line in the report's "Rules Skipped" subsection with `reason: "uip agent review / codedagent review CLI not available"`, then continue with 2.5b.
 
@@ -53,10 +53,10 @@ Maps project signals to the judgment catalog files that must be loaded. Extend t
 
 | Signals present | Project type | Catalog files |
 |---|---|---|
-| `agent.json` AND no `main.py` AND no `pyproject.toml` | Agent (low-code) | `agents/agents-common-rules.md` + `agents/agents-lowcode-rules.md` |
+| `agent.json` AND no `main.py` AND no `pyproject.toml` | Agent (low-code) | `agents/agents-common-rules.md` + `agents/agents-lowcode-rules.md` (+ `agents/guardrails/guardrails-review.md` when `guardrails[]` is present or a guardrail use case matches — see Step 2.5b item 3) |
 | `pyproject.toml` + `main.py` + any framework config (`langgraph.json` / `llama_index.json` / `openai_agents.json` / `google_adk.json` / `pydantic_ai.json` / `agent_framework.json`) | Agent (coded) | `agents/agents-common-rules.md` + `agents/agents-coded-rules.md` |
 | `pyproject.toml` + `main.py` + `uipath.json[functions]` only (no framework config) | Agent (coded — Simple Function) | same as Agent (coded) |
-| `agent.json` + `pyproject.toml` + `main.py` (agent-builder coded layout) | Agent (low-code + coded) | all three: common + lowcode + coded; tag each finding with its source file |
+| `agent.json` + `pyproject.toml` + `main.py` (agent-builder coded layout) | Agent (low-code + coded) | all three: common + lowcode + coded; tag each finding with its source file; also `agents/guardrails/guardrails-review.md` for the `agent.json` guardrails |
 | `project.json` + `.xaml` / `.cs` | RPA | *(phase 2 — catalog not yet authored)* |
 | `*.flow` + `project.uiproj` with `ProjectType: "Flow"` | Flow | *(phase 2)* |
 | `.uipath/` or `app.config.json` | Coded App | *(phase 2)* |

package/skills/uipath-rpa/SKILL.md

@@ -39,11 +39,13 @@ Before doing any work, check if `.claude/rules/project-context.md` exists in the
 **If the file does NOT exist** → run the discovery flow below.
 
 **Discovery flow** (used for both missing and stale context):
-1. Trigger the `uipath-project-discovery-agent` and wait for it to complete
+1. Spawn the project discovery agent and wait for it to complete. Its definition lives inside this skill at [`agents/uipath-project-discovery-agent.md`](agents/uipath-project-discovery-agent.md). Use whichever spawn mechanism your host supports:
+   - **Host registers plugin agents by name** (e.g., Claude Code) → trigger the registered `uipath-project-discovery-agent` agent.
+   - **Host only spawns its own predefined subagents** (e.g., UiPath Autopilot) → spawn a read-only subagent and pass it that file (relative to this skill) as its instructions / custom skill.
 2. The agent returns the generated context document as its response
 3. Write the returned content to **both**:
    - `.claude/rules/project-context.md` (create `.claude/rules/` directory if needed) — auto-loaded by Claude Code in future sessions
-   - `AGENTS.md` at project root — read by UiPath Autopilot in Studio Desktop. If `AGENTS.md` already exists, look for `<!-- PROJECT-CONTEXT:START -->` / `<!-- PROJECT-CONTEXT:END -->` markers and replace only between them; if no markers exist, append the fenced block at the end
+   - `AGENTS.md` at project root — the shared cross-agent context convention (read by UiPath Autopilot in Studio Desktop and other AGENTS.md-aware hosts). If `AGENTS.md` already exists, look for `<!-- PROJECT-CONTEXT:START -->` / `<!-- PROJECT-CONTEXT:END -->` markers and replace only between them; if no markers exist, append the fenced block at the end
 4. Then proceed with the skill workflow
 
 ## Step 0: Resolve PROJECT_DIR
@@ -92,8 +94,6 @@ If target configuration is unavailable, fall back to the documented UIA indicati
 
 The full prohibited-tool list, the UIA-only exploration requirement, and the `InvokeJS`/`InjectJsScript` exception scope are in [ui-automation-guide.md](references/ui-automation-guide.md) § Mandatory: Generate Targets Before Writing Any UI Code — read it in full per Rule 7 before any UIA work.
 
-**Running a UIA workflow.** Use `uip rpa debug start` throughout development, not `run` — a debug session pauses on error and leaves the UI state inspectable. During capture, advance app state with the UIA interact CLI, never `run` (a finishing `run` can close the target app). Switch to `run --skip-build` only as the final, non-interactive smoke test once the workflow is stable and `build` has passed. The full procedure — window baseline → `debug start` → cancel → window diff → selector-failure recovery — is in [ui-automation-guide.md](references/ui-automation-guide.md) § Running UI Automation Workflows.
-
 ### Placeholder-Selector Stub Pattern (when live app access is unavailable)
 
 When generating a UI automation workflow **without** live app access (target capture cannot be run because the app is not installed, the agent has no UI, or the user explicitly deferred capture to a developer), emit **real UIA activities with placeholder selectors and `TODO Indicate` markers** — never `Log` stubs.
@@ -199,6 +199,10 @@ uip rpa activities find --query log --output json > /dev/null 2>&1 &
 - "Feels expensive", "many tool calls used", "natural pause point", "partial result looks usable", and "too complex to continue in one session" are **NOT** Stop conditions. Only the concrete hard blockers in the plan's `Stop conditions` section count.
 - Plan decisions already made are authoritative. Do not `AskUserQuestion` about structure, file count, selector strategy, or capture approach when the plan specifies them — those questions belonged to the planner.
 
+### Error Handling (Both Modes)
+
+**Wrap external interactions (UI, file, network, DB) in Try/Catch and classify failures — `BusinessRuleException` for bad input data (no retry; needs a human), system exceptions for transient faults (retry then escalate).** Don't blanket-wrap pure logic, don't leave a Catch empty, and `Rethrow` (never `Throw New Exception(ex.Message)`) to preserve the stack trace. For exception taxonomy, Retry Scope count/interval semantics, ContinueOnError suppression, screenshot-on-error, the Global Exception Handler recipe (scaffold + `project.json` registration + verdict logic), and the resilience patterns — recovering to a known app state before retrying, per-item transaction boundaries, idempotent/compensating writes to avoid **duplicate creates** and partial writes, sensitive-data redaction, and **retry ownership** across queue/Retry-Scope/GEH/job layers — read [references/error-handling-guide.md](references/error-handling-guide.md) in full before adding resilience to a workflow.
+
 ### Call Batching (Both Modes)
 
 **Batch independent tool calls into one assistant message — minimize model round-trips.** Two points in a new-project build serialize needlessly by default; collapse each into a single message.
@@ -234,7 +238,7 @@ uip rpa activities find --query log --output json > /dev/null 2>&1 &
 17. **[XAML] MUST understand project structure** — read `project.json`, check expression language, scan existing patterns. NEVER generate XAML blind.
 18. **[XAML] Start minimal, iterate to correct** — build one activity at a time, validate after each addition.
 19. **[XAML] Fix errors by category** — Package → Structure → Type → Activity Properties → Logic.
-20. **[XAML] ViewState handling depends on the operation.** When editing existing files, do NOT modify ViewState on nodes you are not changing. When generating new Flowchart/StateMachine/ProcessDiagram workflows, generate ViewState for each node (see [canvas-layout-guide.md](references/xaml/canvas-layout-guide.md)). For Sequences, ViewState is optional.
+20. **[XAML] Flowchart node structure + ViewState both decide whether a Flowchart renders.** **Structure first:** every `FlowStep`/`FlowDecision`/`FlowSwitch` MUST be a direct child of `<Flowchart>` (only direct children are added to the `Flowchart.Nodes` collection), wired through `Flowchart.StartNode`/`FlowStep.Next`/branches with `<x:Reference>`+`x:Name`. NEVER build the flow as a nested chain — one `FlowStep` physically nested inside the previous one's `<FlowStep.Next>` — because nested-only steps are absent from `Flowchart.Nodes` and the designer renders almost nothing, regardless of ViewState. **Then ViewState:** when generating new Flowchart/StateMachine/ProcessDiagram workflows, per-node ViewState is MANDATORY — `ShapeLocation`+`ShapeSize` on every node (`ConnectorLocation` optional, Studio auto-routes). Without it Studio stacks every node at (0,0) so they overlap into what looks like a single node, and Studio does NOT auto-arrange on open (see [canvas-layout-guide.md](references/xaml/canvas-layout-guide.md)). When editing existing files, do NOT modify ViewState on nodes you are not changing. For Sequences, ViewState is optional.
 21. **[XAML] Reading `<Activity>.md` from `{PROJECT_DIR}/.local/docs/packages/...` is a precondition for `activities get-default-xaml` — for every activity not on the common-activity card.**
     - **Card-listed activities:** check [references/common-activity-card.md](references/common-activity-card.md) first; if the activity is on the card, author from the card entry alone — skip `activities find`, skip `activities get-default-xaml`, skip the per-activity MD read.
     - **All other activities:** (1) `activities find` → class name, (2) **read `<Activity>.md` first** and extract a property checklist (required + use-case-relevant), (3) `activities get-default-xaml` → starter element, (4) **diff your checklist against the starter and add what's missing** — an empty checklist means you skipped step 2, go back.
@@ -263,14 +267,19 @@ uip rpa activities find --query log --output json > /dev/null 2>&1 &
 | **Use mock testing** | XAML | [testing-guide.md § Mock Testing (WIP)](references/testing-guide.md) — requires CLI command not yet available |
 | **Use XAML test activities** | XAML | [testing-guide.md § XAML Test Activities](references/testing-guide.md) |
 | **Use execution templates** | XAML | [testing-guide.md § Execution Templates](references/testing-guide.md) |
+| **Set up Test Manager for the project** (server URL + default project) | Both | [cli-reference.md § Test Manager](references/cli-reference.md) — `uip rpa tm connect` / `set-default-project` |
 | **Create/edit XAML workflow** | XAML | [xaml/workflow-guide.md](references/xaml/workflow-guide.md) → [xaml/xaml-basics-and-rules.md](references/xaml/xaml-basics-and-rules.md) |
+| **Add error handling / resilience** (Try/Catch, Retry Scope, BusinessRuleException, ContinueOnError, screenshot-on-error, Global Exception Handler, recover app state, transaction boundary, idempotency / avoid duplicate creates, queue vs local retry ownership) | Both | [error-handling-guide.md](references/error-handling-guide.md) |
 | **Use a common activity** (`Sequence` / `If` / `Switch<T>` / `TryCatch` / `While` / `DoWhile` / `ForEach<T>` / `Assign` / `LogMessage` / `WriteLine` / `Delay` / `Throw` / `Rethrow`) | XAML | [common-activity-card.md](references/common-activity-card.md) |
-| **Create Flowchart/StateMachine** | XAML | [xaml/workflow-guide.md](references/xaml/workflow-guide.md) → [xaml/canvas-layout-guide.md](references/xaml/canvas-layout-guide.md) |
+| **Create/edit Flowchart** | XAML | [xaml/flowchart-guide.md](references/xaml/flowchart-guide.md) → [xaml/canvas-layout-guide.md](references/xaml/canvas-layout-guide.md) |
+| **Create StateMachine** | XAML | [xaml/workflow-guide.md](references/xaml/workflow-guide.md) → [xaml/canvas-layout-guide.md](references/xaml/canvas-layout-guide.md) |
 | **Create/edit Long Running Workflow (ProcessDiagram)** | XAML | [xaml/long-running-workflow-guide.md](references/xaml/long-running-workflow-guide.md) → [xaml/canvas-layout-guide.md](references/xaml/canvas-layout-guide.md) |
 | **Write UI automation** | Both | [ui-automation-guide.md](references/ui-automation-guide.md) → [uia-configure-target-workflows.md](references/uia-configure-target-workflows.md) |
 | **Build multi-screen UIA XAML workflow** | XAML | [ui-automation-guide.md](references/ui-automation-guide.md) → [uia-configure-target-workflows.md § Multi-Step UI Flows](references/uia-configure-target-workflows.md) |
 | **Share Object Repository selectors across projects (UI Library)** | Both | [ui-automation-guide.md § Object Repository as a Published UI Library](references/ui-automation-guide.md) |
+| **Drive a captured control** (date inputs, native vs custom dropdowns, buttons disabled during async) | Both | [ui-automation-guide.md § Control-Specific Interaction Patterns](references/ui-automation-guide.md) → [uia-elements-interaction-guide.md](references/uia-elements-interaction-guide.md) |
 | **Use Excel/Word/Mail/etc.** | Both | Service table below → `.local/docs/packages/{PackageId}/` → fallback: `references/activity-docs/{PackageId}/{closest}/` |
+| **Manipulate data (DataTable/LINQ, strings, RegEx, DateTime, collections, JSON)** | Both | [data-manipulation-guide.md](references/data-manipulation-guide.md) |
 | **Use Data Fabric entities** | XAML | [xaml/workflow-guide.md](references/xaml/workflow-guide.md) → [activity-docs overview](references/activity-docs/UiPath.DataService.Activities/overview.md) |
 | **Query Data Fabric with filters** | XAML | [data-service-filter-builder-guide.md](references/activity-docs/UiPath.DataService.Activities/guides/data-service-filter-builder-guide.md) → [QueryEntityRecords](references/activity-docs/UiPath.DataService.Activities/activities/QueryEntityRecords.md) |
 | **Call an IS connector (coded)** | Coded | [coded/integration-service-guide.md](references/coded/integration-service-guide.md) |
@@ -387,9 +396,12 @@ The XAML file anatomy template (namespace declarations, root Activity element, b
 
 - [xaml/xaml-basics-and-rules.md](references/xaml/xaml-basics-and-rules.md) — XAML anatomy, safety rules, editing operations (read before any XAML work)
 - [xaml/common-pitfalls.md](references/xaml/common-pitfalls.md) — Activity gotchas, scope requirements, property conflicts
+- [data-manipulation-guide.md](references/data-manipulation-guide.md) — DataTable LINQ (filter/sort/group/join/diff), strings, RegEx, DateTime, type conversion, collections, JSON; VB + C# forms
+- [error-handling-guide.md](references/error-handling-guide.md) — Modern-mode error handling & resilience: exception taxonomy, Try/Catch discipline, Retry Scope, ContinueOnError, Throw/Rethrow, screenshot-on-error, Global Exception Handler (scaffold + registration + verdict logic), state recovery before retry, transaction boundaries, idempotent/compensating writes (duplicate-create safety), sensitive-data redaction, and retry ownership across layers
 - [reframework-guide.md](references/reframework-guide.md) — REFramework execution modes, SetTransactionStatus queue-guard fix, Config.xlsx leftover trap
 - [xaml/csharp-activity-binding-guide.md](references/xaml/csharp-activity-binding-guide.md) — Canonical C# binding forms per common activity property (LogMessage, GetText, StartProcess, …) — flat lookup table + recipes
 - [xaml/csharp-expression-pitfalls.md](references/xaml/csharp-expression-pitfalls.md) — C#-specific expression failures (attribute-form VB JIT, ThrowIfNotInTree, OutArgument parse errors)
+- [xaml/flowchart-guide.md](references/xaml/flowchart-guide.md) — Flowchart node vocabulary, structure & wiring, node registration, forbidden nested-chain pattern, condition expressions
 - [xaml/canvas-layout-guide.md](references/xaml/canvas-layout-guide.md) — Flowchart, State Machine, and Long Running Workflow canvas layout with ViewState
 - [xaml/long-running-workflow-guide.md](references/xaml/long-running-workflow-guide.md) — LRW package dependency, node vocabulary, gateway patterns, suspend/resume persistence
 - [xaml/jit-custom-types-schema.md](references/xaml/jit-custom-types-schema.md) — JIT custom type discovery