@uipath/skills 1.199.0 → 1.200.0

package/skills/uipath-process-mining/references/querying.md

@@ -0,0 +1,66 @@
+# Querying a process app (`uip pm query`)
+
+Pull numbers out of a built app. Subcommands: `info` (metadata), `run`
+(aggregate group-by + metrics), `details` (raw rows), `percentile`, `rca`
+(root-cause), `insights` (process insights), `layout`. All take `--stage
+dev|published` (default `dev`) — but query on **`dev`**: `--stage published` is
+currently unreachable via the CLI (`UserError_InvalidOrNoIngestion`; no `uip pm`
+path completes a published-stage ingestion — see
+[`lifecycle-and-rbac.md`](lifecycle-and-rbac.md)).
+
+## Start with `query info`
+
+`query info <app>` returns the queryable model: entities (`Cases`, `Event_log`,
+`Tags`, `Due_dates`, `__Process_Events`, process internals, **plus any table you
+added to the data model**) and, per entity, the **fields** with their ids. Field
+ids are hashed, e.g. `F__Cases__Service_Component__f0f7…`; a few standard fields
+keep plain ids (`Case_ID`, `Event_count`). Query bodies reference **ids**, not
+column names (`UserError_FieldNotFound` otherwise).
+
+## Prefer the sugar over hand-writing the AST
+
+```bash
+uip pm query run <app> --group-by Open_year --metric Event_count:average --metric Case_ID:count --output table
+```
+
+`--group-by <cols>` (comma-separated names or ids) and `--metric <col:fn[:alias]>`
+(repeatable) resolve human column names to ids via `query info`, build the body,
+and **transpose the engine's columnar response into rows** (great with `--output
+table`). `fn` ∈ `average | count | sum | min | max`. The sugar and a raw
+`--body`/`--body-json` are mutually exclusive.
+
+## The raw aggregate body (`AggregateDataRequestDto`)
+
+```json
+{ "groupBy": ["<fieldId>", "..."],
+  "aggregates": [ { "id": "<yourName>", "argument": "<fieldId>", "aggregation": "<fn>" } ] }
+```
+
+- `aggregation` is the **`AggregationFunction` enum**: `average`, `count`, `sum`,
+  `min`, `max`. Invalid values (e.g. `maximum`) 400 with a raw .NET enum-convert
+  error.
+- The response `Data` is **columnar**: one entry per group field and per
+  aggregate, keyed by the id, each `{ "values": [...per group...], "ungrouped":
+  <grand total>, "stackValues": null }`. Group and aggregate arrays are
+  **index-aligned**. (Note: the raw object is camelCase `values`/`ungrouped`; the
+  CLI's `--output json/table` formatter may present them PascalCase.)
+- Ungrouped-only queries (`"groupBy": []`) return the total in `ungrouped`, or in
+  `values[0]` when the engine emits it as a single-row column.
+
+## Restrictions & other subcommands
+
+- **`groupBy` on an `Event_log` (event-table) field 400s** `UserError_EventTableUsedInQuery`.
+  `run` aggregates case-level entities only. For event/activity-level breakdowns:
+  use `insights` (`processId` + 1..10 numeric `metrics` from `query info`) or the
+  process model (`layout`), OR precompute the counts in a dbt model (e.g. group
+  the event log by activity), register it as a data-model table
+  ([`data-model.md`](data-model.md)), and `query run` that table.
+- `percentile --field <id> --values 0.5,0.9,0.95 [--filters <json>]` — points in 0..1.
+- `rca` needs a non-empty `selectedSet`; `insights` needs a `processId` and 1..10 numeric `metrics`.
+- `details` returns raw rows (`DetailsDataRequestDto`); `--limit` is clamped 1..1000 server-side.
+
+## Getting custom analytics out
+
+If your numbers live in a custom dbt model, you must first register it as a
+data-model table so `query` can see it — see [`data-model.md`](data-model.md).
+Once registered, everything above (sugar, aggregate AST, percentiles) works on it.

package/skills/uipath-process-mining/references/transformations.md

@@ -0,0 +1,80 @@
+# The transformation (ELT) layer — dbt on Snowflake
+
+The transformation layer is a dbt project that runs on **Snowflake**. Loaded
+source tables (one per input table) feed the models that produce the process
+model. `transformations list/get/create/update/apply/run/status/logs` is the ELT
+editor surface:
+
+| Operation | Command |
+|-----------|---------|
+| List the model tree | `transformations list <app>` |
+| Read a file (or save locally) + its ETag | `transformations get <app> <path> [--destination <file>]` |
+| Edit an existing file (ETag-guarded) | `transformations update <app> <path> --file <local> --etag '<etag>'` |
+| Create a new model file | `transformations create <app> <path> --file <local>` |
+| Re-run the **full** transform on loaded data | `transformations apply <app> --wait` |
+| Rebuild **one** dev model + dependents | `transformations run <app> --model models/X.sql` |
+| Status / logs of the last build | `transformations status <app>` · `transformations logs <app>` |
+
+## Model set for `uipath.custom`
+
+Four template models: **`Event_log`** (built from the source; the events table),
+**`Cases`** (aggregates Event_log — one row per case), **`Tags`** and
+**`Due_dates`** (ship as safe `where 1=0` stubs depending only on `ref('Cases')`).
+`Tags` and `Due_dates` are pre-registered **Case-child** tables — fill their stubs
+with real rows keyed on `Case_ID` to get per-case labels (`Tag`/`Tag_type`) or
+per-case SLAs (`Expected_date`/`Actual_date`/`On_time`/`Cost`) with **no add-table
+needed**. See [`data-model.md`](data-model.md) for when to use
+them vs a custom table. `Event_log` builds first and independently. `models/schema/sources.yml` is
+generated from the data mapping and lists every input table with **all** its
+columns (mapped → TargetName, unmapped → raw source name), so multi-table custom
+apps can `source('sources', '<Table>')` any loaded table.
+
+## The #1 gotcha — `Cases.sql` references optional columns
+
+The template `models/Cases.sql` hard-references `Event_log."Case"`,
+`"Case_status"`, `"Case_type"`, `"Case_value"`. A minimal mapping
+(Case_ID/Activity/timestamp only) doesn't produce them ⇒ dbt
+`000904 invalid identifier`. Fix — pull, null the missing refs, push, apply:
+
+```sql
+select
+    Event_log."Case_ID",
+    cast(null as varchar) as "Case",
+    cast(null as varchar) as "Case_status",
+    cast(null as varchar) as "Case_type",
+    cast(null as float)   as "Case_value",
+    count(*) as "Event_count"
+from {{ source('sources', 'Event_log') }} as Event_log
+group by Event_log."Case_ID"
+```
+
+A successful run then reports `SUCCESS_WITH_WARNINGS` with repeated
+`UserWarning_MissingOptionalEventColumn` — **benign** for a minimal mapping.
+
+## apply vs run; create vs update
+
+- **`apply`** re-runs the **full** transform on already-loaded data — the fix-loop
+  verb after a transform-only failure. **Do not re-ingest** for a SQL-only change.
+- **`run --model models/X.sql`** rebuilds one dev model and its dependents.
+- **`create <path> --file`** adds a **new** model file (PUT without ETag — there is no
+  prior version to guard); **`update <path> --file`** edits an **existing** file and
+  **requires `--etag`**: the `Data.ETag` the `get` you edited from returned. `update` on
+  a missing path 404s — use `create`. A 409/412 means someone replaced the file after
+  your `get`: re-`get` for the new content **and** ETag, re-apply your edit on top, then
+  `update` with the new `--etag`. You can also inline intermediate logic as CTEs inside
+  one model instead of many files.
+- Use **`apply --wait`** to block to a terminal state and auto-print the dbt error.
+
+## Snowflake / dbt notes
+
+- **Quoted identifiers are case-sensitive** and must match the mapped `TargetName`
+  exactly: `Event_log."Case_ID"`. Reference raw unmapped columns by their source
+  name, e.g. `"# Reassignments"`.
+- Parse messy source columns in SQL rather than fighting the loader: European
+  dates via `try_to_timestamp(col, 'DD-MM-YYYY HH24:MI:SS')` (lenient on single
+  digits), decimal-comma numbers via `try_to_double(replace(col, ',', '.'))`.
+- **`pm_utils` macros** seen in templates: `as_varchar('literal')` (string
+  literal) vs `to_varchar(col)` (cast), `to_timestamp('null')`, `to_boolean('true')`,
+  `id()` = `row_number() over (order by (select null))` (surrogate key),
+  `datediff('millisecond', a, b)`, `star(source, except=[...])`.
+- Build type on `run`: `RunQueries = 0` (all) vs `RunModel = 1` (needs `modelPath`).

package/skills/uipath-process-mining/references/uip-pm-cli.md

@@ -0,0 +1,145 @@
+# `uip pm` — CLI mechanics & conventions
+
+The low-level "how to drive the tool" layer — the shared plumbing every `uip pm`
+command uses. The *decisions* — which template, when to add a table, why an app locks
+open — live in the domain references ([`app-types.md`](app-types.md),
+[`data-model.md`](data-model.md), [`model-editing.md`](model-editing.md),
+[`lifecycle-and-rbac.md`](lifecycle-and-rbac.md)). **Drive Process Mining through the
+CLI — do not hand-roll the REST API.**
+
+## Command groups
+
+| Group | Verbs | For |
+|-------|-------|-----|
+| `app-types` | `list`, `get` | Discover/inspect templates ([`app-types.md`](app-types.md)). |
+| `apps` | `list`, `create`, `delete`, `publish` | The app itself + its lifecycle ([`lifecycle-and-rbac.md`](lifecycle-and-rbac.md)). |
+| `apps data-mapping` | `get`, `update` | The **input mapping** (source table/column → target field) ([`pre-flight.md`](pre-flight.md)). |
+| `apps model` | `get`, `update`, `fields list\|set\|remove` | The **semantic** model — fields with their data kinds, calculated fields, metrics, dashboards ([`model-editing.md`](model-editing.md)). |
+| `apps data-model` | `get`, `add-table` | The **structural** model — the table graph (PK/FK, roles) that `add-table` edits ([`data-model.md`](data-model.md)). |
+| `files` | `upload` | Load a data file to an input table. |
+| `ingestions` | `create`, `logs` | Parse + load the raw data (the LT of ELT). |
+| `transformations` | `list`, `get`, `create`, `update`, `apply`, `run`, `status`, `logs` | The dbt dev loop ([`transformations.md`](transformations.md)). |
+| `query` | `run`, `details`, `percentile`, `rca`, `insights`, `info`, `layout` | Pull numbers out ([`querying.md`](querying.md)). |
+
+> **`apps model` vs `apps data-model` — don't confuse them.** `apps model` is the
+> **semantic** model (`/model`); `apps data-model` is the **structural** table graph
+> (`/dataModel`). Editing a field's data kind or a calculated field is `apps model
+> fields …`; registering a new queryable table is `apps data-model add-table`.
+
+## The output envelope
+
+Every command prints a stable envelope and sets a branchable exit code:
+
+- **`Result`** — `Success` / `Failure` / `ValidationError`; **`Code`** — a stable
+  machine tag (`PmAppsCreate`, `PmQueryRun`, …); **`Data`** — the payload;
+  **`Instructions`** — a next-step/fix hint, present on failures ("run `uip login`",
+  "see `uip pm apps list`") and on some successful mutating commands (`add-table`,
+  `data-mapping update`, `fields set`) pointing at the required re-ingest/publish.
+- Exit `0` success, `1` failure, `3` validation (commander rejected a flag before any
+  API call — e.g. an unknown `--stage`).
+- **`--output json|table|…`** picks the rendering; **`--output-filter <JMESPath>`**
+  projects/reshapes `Data` (e.g. `"[].{Key:AppTypeKey,Version:Version}"`). `list`
+  commands unwrap the API's `{ Data: [...] }` so the shape matches across commands.
+- **`--output-filter` on a command whose `--limit` has a default requires an explicit
+  `--limit`** — otherwise it exits `3` rather than silently filtering only the first
+  page. In `pm` that is **`ingestions logs`** alone (default `100`): pair them, e.g.
+  `ingestions logs <app> --limit 200 --output-filter "[?contains(Message,'error')]"`.
+  `app-types list` / `apps list` / `query run` declare no `--limit` default, so
+  filtering them needs nothing extra.
+
+## The ETag get-modify-put pattern
+
+Every editable resource — `data-mapping`, `model`, `data-model`, `transformations` — is
+written `If-Match`-guarded, so a concurrent edit (someone in the UI between your read and
+your write) is rejected instead of silently overwritten. **Which side supplies the ETag
+splits the commands into two groups — get this wrong and the command won't run.**
+
+| | Commands | ETag |
+|---|---|---|
+| **You edited the file locally** | `apps data-mapping update`, `apps model update`, `transformations update` | **`--etag` REQUIRED** — the one the matching `get` returned |
+| **The command reads and merges in one go** | `apps data-model add-table`, `apps model fields set\|remove` | **No `--etag`** — it guards with the ETag of the read it just did |
+
+```bash
+uip pm apps model get <app> --destination model.json      # prints Data.ETag
+#   ...edit model.json...
+uip pm apps model update <app> --file model.json --etag 'W/"3"'
+```
+
+- **Get the ETag from the `get`.** Every `get` of an editable resource returns
+  `Data.ETag` (also with `--destination`, which writes only the document to disk).
+  Project it with `--output-filter ETag`.
+- **The CLI never re-reads the ETag just before writing** — that would make the
+  precondition pass no matter who wrote in between, defeating the guard. Do not work
+  around a rejected write by re-`get`ting only for a fresh ETag.
+- **On a conflict, recovery differs by group.** `update` (409
+  `UserError_ETagFileConflict` / 412): re-run the `get` for the latest version **and its
+  new ETag**, re-apply your change on top of *that* version, then update again with the
+  new `--etag` — a blind re-run just fails again. `add-table` / `fields set|remove`:
+  **just re-run** — they re-read and re-apply on top of the other write. `Instructions`
+  states which applies.
+- `fields set`/`remove` and `model update` return the new edit `Versions`;
+  `data-mapping`/`data-model` edits return `IngestionNeeded: true` (see below).
+- A resource returned **without** an ETag fails the command rather than writing
+  unguarded.
+
+## Async work — always `--wait`
+
+`ingestions create` and `transformations apply` are async. Pass **`--wait`** (with
+`--timeout`) to block to a terminal state, auto-print the loader/dbt error on failure,
+and exit non-zero. Never hand-roll an `apps list` poll loop.
+
+## Stages — `--stage dev|published`
+
+Every data / transform / query command takes `--stage`, default **`dev`**. Writes
+(`data-mapping update`, `transformations`, model/data-model edits) are **dev-only**;
+`published` is read-only. Develop on `dev` (a subset), `publish`, then read
+`--stage published` ([`lifecycle-and-rbac.md`](lifecycle-and-rbac.md)).
+
+## `IngestionNeeded` — the deferred-effect signal
+
+Mapping and data-model edits change how raw data is *parsed / structured*, so they take
+effect only on the **next `ingestions create`**, not on `transformations apply` (which
+only re-runs SQL over already-parsed data). Those commands return `IngestionNeeded:
+true` as the reminder. A SQL-only change is the opposite — `apply`, don't re-ingest
+([`transformations.md`](transformations.md)).
+
+## Field ids come from `query info`
+
+`query run`/`percentile` bodies reference **hashed field ids**
+(`F__<Table>__<Col>__<hash>`), not column names. Discover them with `query info`, or —
+better — let the sugar resolve human names: `query run <app> --group-by <col> --metric
+<col>:<fn>` (`fn ∈ average|count|sum|min|max`). Full AST + restrictions in
+[`querying.md`](querying.md).
+
+## Quick Start — CSV → queryable process app
+
+```bash
+# 0. Pre-flight (cheap local checks — see pre-flight.md): encoding (UTF-8?),
+#    delimiter, date format (dd-mm vs mm-dd), strip junk all-empty rows.
+
+# 1. Discover the template + its target fields
+uip pm app-types list --output-filter "[].{Key:AppTypeKey,Version:Version,Name:DefaultName}"
+
+# 2. Create the app from a data mapping (isNotNull/isUnique default per field)
+uip pm apps create "My Process" --type uipath.custom --data-mapping ./mapping.json
+
+# 3. Upload + ingest (block until done; prints the loader error on failure)
+uip pm files upload <appId> ./data.csv --input-table Event_log
+uip pm ingestions create <appId> --file-format csv --field-delimiter ";" --encoding utf-8 --wait
+
+# 4. If the transform failed on Cases.sql: pull → patch → apply (transformations.md)
+uip pm transformations get <appId> models/Cases.sql --destination Cases.sql   # note Data.ETag
+#   ...edit...
+uip pm transformations update <appId> models/Cases.sql --file Cases.sql --etag 'W/"639…"'
+uip pm transformations apply <appId> --wait
+
+# 4b. If the MAPPING was wrong instead — fix it in place, don't recreate (pre-flight.md)
+uip pm apps data-mapping get <appId> --destination mapping.json              # note Data.ETag
+#   ...edit...
+uip pm apps data-mapping update <appId> --file mapping.json --etag 'W/"639…"'
+uip pm ingestions create <appId> --wait          # a mapping change needs a re-ingest
+
+# 5. Query it
+uip pm query info <appId>                                   # discover fields/metrics
+uip pm query run  <appId> --group-by Service_Component --metric Event_count:average --output table
+```

package/skills/uipath-review/SKILL.md

@@ -20,19 +20,20 @@ Review UiPath solutions and individual artifacts for structural validity, qualit
 
 ## Critical Rules
 
-1. **NEVER modify any files.** This skill is read-only. If fixes are needed, identify them in the report and tell the user which skill to use (uipath-rpa, uipath-agents, uipath-maestro-flow, uipath-maestro-bpmn, uipath-api-workflow, uipath-coded-apps, uipath-platform, uipath-solution).
-2. **ALWAYS run validation and Workflow Analyzer before manual review.** For RPA projects, run **both** `uip rpa validate` on every entry point AND `uip rpa build "<PROJECT_DIR>"` — `validate` catches structural / analyzer issues, `build` catches compile-time issues `validate` misses (unknown member names, invalid enum values, JIT failures). Run `uip agent validate` on agents, `uip maestro flow validate` on flows, `uip maestro bpmn validate` on BPMN processes, `uip api-workflow validate` on API workflows. Report every Error, Warning, and Info result from every command. A review without both `validate` AND `build` (for RPA) is incomplete and may ship broken member references.
+1. **NEVER manually modify any files.** This skill is read-only. Exception: The command `uip agent refresh` is allowed and mandatory for low code agents, because it is not a manual modification, even when the command updates derived files -- do not restore or clean up those CLI-managed changes. If fixes are needed, identify them in the report and tell the user which skill to use (uipath-rpa, uipath-agents, uipath-maestro-flow, uipath-maestro-bpmn, uipath-api-workflow, uipath-coded-apps, uipath-platform, uipath-solution).
+2. **ALWAYS run validation and Workflow Analyzer before manual review.** For RPA projects, run **both** `uip rpa validate` on every entry point AND `uip rpa build "<PROJECT_DIR>"` — `validate` catches structural / analyzer issues, `build` catches compile-time issues `validate` misses (unknown member names, invalid enum values, JIT failures). For low-code agents, run `uip agent refresh` and `uip agent validate`. Run `uip maestro flow validate` on flows, `uip maestro bpmn validate` on BPMN processes, `uip api-workflow validate` on API workflows. Report every Error, Warning, and Info result from every command. A review without both `validate` AND `build` (for RPA) is incomplete and may ship broken member references.
 3. **ALWAYS discover and classify before reviewing.** For solutions: classify every project before reviewing any individual one. For single projects: identify the project type and find the enclosing project directory before reviewing individual files.
 4. **Report severity for every finding.** Use: **Critical** (blocks deployment), **Warning** (should fix), **Info** (improvement opportunity).
 5. **Understand business context first.** Before evaluating optimization, ask or infer what the solution is trying to accomplish. A queue-based architecture is not "better" if the use case processes 5 items/day.
 6. **Use `--output json`** on all CLI validation commands for programmatic parsing.
 7. **Do not duplicate what validation commands catch.** Reference the validation output by rule ID and message — do not manually re-describe the same issue. But DO include every validation result (Error, Warning, Info) in the report.
 8. **Cap the review at 30 minutes of analysis.** For very large solutions (10+ projects), provide a summary review with deep dives on the 3 highest-risk projects. Offer to review remaining projects if the user wants.
-9. **Run the review CLI first, then apply the judgment catalog, for every agent encountered.** First run `uip agent review` (low-code) or `uip codedagent review` (coded) with `--output json` — it returns the deterministic findings (Step 2.5a). Then load the judgment catalog: `references/agents/agents-common-rules.md` plus the format-specific file (`agents-lowcode-rules.md` or `agents-coded-rules.md`); for the agent-builder coded layout (both `agent.json` and `main.py`), load all three and run both CLI commands. Future phases add catalogs for RPA, flows, coded apps. This holds even when the skill loads mid-task: if review work already started before this skill loaded (e.g., a generic code-review pass produced findings), Step 2.5a and the guardrail Step 0 catalog fetch are still mandatory — run them, then merge the earlier findings into this skill's report format. Prior review output is never a substitute for the review CLI or the live catalog.
+9. **Run the review CLI first, then apply the judgment catalog, for every agent encountered.** First run `uip agent review` (low-code) or `uip codedagent review` (coded) with `--output json` — it returns the deterministic findings (Step 2.5a). Then load the format-specific judgment catalog (`agents-lowcode-rules.md` or `agents-coded-rules.md`). Future phases add catalogs for RPA, flows, coded apps. This holds even when the skill loads mid-task: if review work already started before this skill loaded (e.g., a generic code-review pass produced findings), Step 2.5a and the guardrail Step 0 catalog fetch are still mandatory — run them, then merge the earlier findings into this skill's report format. Prior review output is never a substitute for the review CLI or the live catalog.
 10. **Rule findings are authoritative as emitted.** Carry review-CLI findings (`Data.Issues[]`) into the report verbatim — `RuleId`, `Severity`, `Description`, `File`, `SuggestedFix` unchanged. For the judgment catalog, use its `rule_id`, `severity`, `trigger`, and `suggested_fix` verbatim. Map severity to the report's bands: `error` → Critical, `warning` → Warning, `info` → Info. `judgment` severity rows default to Warning; the agent may escalate or de-escalate with reasoning logged in the finding's `description`. Do not re-rank otherwise.
 11. **Report rules that could not be applied** (missing tooling, missing file, review CLI unavailable, `status: deferred`) in a dedicated "Rules Skipped" subsection of the report — never silently skip.
 12. **Never invent `rule_id` values.** Every `rule_id` cited in the report MUST appear verbatim in EITHER a loaded judgment-catalog file (`references/agents/agents-*-rules.md`) OR the `uip agent review` / `uip codedagent review` JSON output. `rule_id` is a stable contract identifier — consumers grep for it, dashboards aggregate by it, audits trace it. An invented identifier looks authoritative but cannot be looked up, doesn't aggregate, and produces a different name for the same observation on the next run. If you observe a real issue covered by neither source, the finding is still valid — report it as a normal Critical / Warning / Info finding **without** a `rule_id` (no `` `RULE_ID` `` backtick token in the line). **Before emitting the report, scan every cited `rule_id` and confirm it appears verbatim in a loaded catalog file or the review-CLI output; demote any that don't to `rule_id`-less findings.**
 13. **Grade every agent project by the rubric — derived, never asserted.** For **agent projects** (phase 1), produce a letter grade (`A`/`B`/`C`/`D`/`F`, no `+`/`-`) per agent and overall, computed in Step 4.5 as `min(G_det, G_jud)`. **G_det is read from the review CLI's `Data.Grade` (Step 2.5a) — do not recompute it from finding counts.** G_jud you compute from judgment (architecture scores + Step 2.5b + Step 3). CLI findings already shaped `Data.Grade`; only judgment findings feed G_jud, so each finding lands in exactly one sub-grade. Show the binding constraint for every grade; a grade with no shown derivation is invalid. A security or data-integrity judgment Critical forces **F** regardless of design quality (hard gate, not a blend). The skill grade is always ≤ `Data.Grade` (min only lowers) — report both, never overwrite the CLI grade. Do **not** grade non-agent projects (RPA, flows, coded apps) — that rubric is a future phase. See [references/agents/agent-grading-rubric.md](references/agents/agent-grading-rubric.md).
+14. **These paths are CLI-managed — `uip agent refresh` owns them:** `.agent-builder/`, `.local/build/`, and (low-code only) the root `entry-points.json`, regenerated from `agent.json`. Do not open their contents. Exclude them from classification, source-file selection, structural metrics, and manual checks. Raise a finding only when `refresh` fails to fix them — a pre-refresh mismatch is stale by construction, not a defect. Read low-code schemas from `agent.json` (`.inputSchema` / `.outputSchema`).
 
 ## Review Workflow
 
@@ -44,10 +45,10 @@ Run this from the directory the user specified (or the current working directory
 
 ```bash
 # Discover solution files, project markers, and documentation
-find . -maxdepth 3 \( -name "*.uipx" -o -name "project.json" -o -name "project.uiproj" -o -name "agent.json" -o -name "*.flow" -o -name "*.bpmn" -o -name "app.config.json" -o -name ".uipath" -o -name "langgraph.json" -o -name "llama_index.json" -o -name "openai_agents.json" -o -name "uipath.json" -o -name "main.py" \) 2>/dev/null
+find . -maxdepth 3 \( -type d \( -name ".agent-builder" -o -path "*/.local/build" \) \) -prune -o \( -name "*.uipx" -o -name "project.json" -o -name "project.uiproj" -o -name "agent.json" -o -name "*.flow" -o -name "*.bpmn" -o -name "app.config.json" -o -name ".uipath" -o -name "pyproject.toml" -o -name "langgraph.json" -o -name "llama_index.json" -o -name "openai_agents.json" -o -name "uipath.json" -o -name "main.py" \) -print 2>/dev/null
 
 # Search for PDD or design documents
-find . -maxdepth 3 \( -name "*PDD*" -o -name "*pdd*" -o -name "*Process_Design*" -o -name "*process_design*" -o -name "*Process-Design*" -o -name "*ProcessDesign*" -o -name "*SDD*" -o -name "*Solution_Design*" -o -name "*design_document*" -o -name "*DesignDocument*" -o -name "*requirements*" -o -name "*specification*" \) 2>/dev/null
+find . -maxdepth 3 \( -type d \( -name ".agent-builder" -o -path "*/.local/build" \) \) -prune -o \( -name "*PDD*" -o -name "*pdd*" -o -name "*Process_Design*" -o -name "*process_design*" -o -name "*Process-Design*" -o -name "*ProcessDesign*" -o -name "*SDD*" -o -name "*Solution_Design*" -o -name "*design_document*" -o -name "*DesignDocument*" -o -name "*requirements*" -o -name "*specification*" \) -print 2>/dev/null
 ```
 
 #### 0b. Locate the PDD (Process Design Document)
@@ -94,7 +95,7 @@ Classify the scope internally using these rules:
 
 **Scope: Solution or Multi-project** — `.uipx` exists at root, OR 2+ **executable** project markers exist in different subdirectories.
 
-- Executable project = `project.json` with `outputType` of `Process`/`Tests`/unspecified, OR `agent.json`, OR `.flow`, OR `project.uiproj` with `ProjectType` `Flow`/`ProcessOrchestration`/`Api`
+- Executable project = `project.json` with `outputType` of `Process`/`Tests`/unspecified, OR a low-code `agent.json`, OR a coded-agent Python project (`pyproject.toml` + framework/`uipath.json` configuration), OR `.flow`, OR `project.uiproj` with `ProjectType` `Flow`/`ProcessOrchestration`/`Api`
 - Library projects (`outputType: "Library"`) co-located with consumers do NOT trigger this scope — that is the normal library+consumer pattern
 - **Windows-Legacy executables do NOT trigger this scope for `.uipx` purposes**: `.uipx` solutions are not supported for Legacy projects. If any detected executable is Legacy, do not flag missing `.uipx` — recommend migration to Modern compatibility if solution bundling is desired. Review each Legacy project independently.
 
@@ -108,7 +109,7 @@ Steps for Solution / Multi-project scope:
 7. Read [references/solution-review-guide.md](references/solution-review-guide.md) for the full procedure
 8. Proceed to Step 1 for each project individually
 
-**Scope: Single Project** — one `project.json` / `agent.json` / `.flow` / coded-app marker at root, no `.uipx`, no executable siblings.
+**Scope: Single Project** — one `project.json` / `agent.json` / `.flow` / coded-app marker, or one Python coded-agent project, at root; no `.uipx`, no executable siblings.
 
 1. Classify the project using the detection table in Step 1
 2. Cross-reference with PDD (if available)
@@ -135,9 +136,8 @@ Record the language per project alongside the type (see solution table below).
 | `project.json` with no `targetFramework` or `targetFramework: "Legacy"` (any expression language — Legacy C# exists) | RPA (Windows-Legacy) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) §10. Also recommend the user invoke `uipath-rpa` (Legacy mode) for Legacy-specific deep validation. Legacy is supported indefinitely in Studio LTS — do NOT flag as Critical. |
 | `project.json` + both `.cs` and `.xaml` | RPA (Hybrid) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) |
 | `project.json` + `.xaml` + DU packages in dependencies (`UiPath.IntelligentOCR.Activities`, `UiPath.DocumentUnderstanding.ML.Activities`) | RPA + Document Understanding | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) + [du-review-checklist.md](references/document-understanding/du-review-checklist.md) |
-| `agent.json` (no `main.py`) | Agent (Low-Code) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): [agents-common-rules.md](references/agents/agents-common-rules.md) + [agents-lowcode-rules.md](references/agents/agents-lowcode-rules.md) |
-| `main.py` + `langgraph.json` / `llama_index.json` / `openai_agents.json` / `google_adk.json` / `pydantic_ai.json` / `agent_framework.json` / `uipath.json` | Agent (Coded) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): [agents-common-rules.md](references/agents/agents-common-rules.md) + [agents-coded-rules.md](references/agents/agents-coded-rules.md) |
-| `agent.json` + `main.py` + `pyproject.toml` (agent-builder coded layout) | Agent (Low-Code + Coded) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): all three — [agents-common-rules.md](references/agents/agents-common-rules.md) + [agents-lowcode-rules.md](references/agents/agents-lowcode-rules.md) + [agents-coded-rules.md](references/agents/agents-coded-rules.md) |
+| `agent.json` with `"type": "lowCode"` | Agent (Low-Code) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): [agents-lowcode-rules.md](references/agents/agents-lowcode-rules.md) |
+| Python coded-agent project, including `agent.json` with `"type": "coded"` when present | Agent (Coded) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): [agents-coded-rules.md](references/agents/agents-coded-rules.md) |
 | `*.flow` + `project.uiproj` with `"ProjectType": "Flow"` | Flow | [flow-review-checklist.md](references/flows/flow-review-checklist.md) |
 | `*.bpmn` + `project.uiproj` with `"ProjectType": "ProcessOrchestration"` | Maestro BPMN | [bpmn-review-checklist.md](references/bpmn/bpmn-review-checklist.md) |
 | `Workflow.json` (`document.dsl` + `do[]`) + `project.uiproj` with `"ProjectType": "Api"` | API Workflow | [api-workflow-review-checklist.md](references/api-workflows/api-workflow-review-checklist.md) |
@@ -154,6 +154,14 @@ For **Solution / Multi-project scope**, record all projects in a table:
 | 4 | ./Orchestration.flow | Flow | — | — |
 ```
 
+**Step 1c — Inventory the authored files** for every project you will review. Run this instead of writing your own `find`, to avoid listing runtime artifacts:
+
+```bash
+find "<PROJECT_DIR>" \( -type d \( -name ".agent-builder" -o -path "*/.local/build" -o -name "node_modules" -o -name ".venv" -o -name "obj" -o -name "bin" \) \) -prune -o -type f -print 2>/dev/null | sort
+```
+
+The result is the authored-file set for Steps 2.5 and 3. Any path absent from it is out of scope: do not read it, cite it, or name it in the report.
+
 ### Step 2 — Run Automated Validation and Workflow Analyzer
 
 This step is **mandatory** and **non-negotiable**. You MUST run validation commands yourself (via Bash) before doing any manual review.
@@ -205,7 +213,7 @@ If `uip rpa analyze` is not available, `uip rpa validate` includes Workflow Anal
 
 | Project Type | Validation Command | Report All Severities |
 |---|---|---|
-| Agent (Low-Code) | `uip agent validate "<PROJECT_DIR>" --output json` | Yes — errors, warnings, info |
+| Agent (Low-Code) | `uip agent refresh "<PROJECT_DIR>" --output json`, then `uip agent validate "<PROJECT_DIR>" --output json` | Yes — errors, warnings, info |
 | Flow | `uip maestro flow validate "<PROJECT_NAME>.flow" --output json` | Yes — schema errors, reference errors, warnings |
 | Maestro BPMN | `uip maestro bpmn validate "<FILE>.bpmn" --output json` | Yes — model errors, warnings |
 | API Workflow | `uip api-workflow validate "<WORKFLOW_JSON>" --output json` | Yes — schema + semantic errors, warnings |
@@ -251,9 +259,8 @@ Run the review command for the agent type, once, capturing JSON:
 
 | Agent type | Command |
 |---|---|
-| Low-code (`agent.json`) | `uip agent review "<PROJECT_DIR>" --output json` |
-| Coded (`main.py` + framework config) | `uip codedagent review "<PROJECT_DIR>" --output json` |
-| Agent-builder coded layout (`agent.json` + `main.py`) | run **both** commands |
+| Low-code | `uip agent review "<PROJECT_DIR>" --output json` |
+| Coded | `uip codedagent review "<PROJECT_DIR>" --output json` |
 
 The CLI runs every deterministic static check — structural/schema, placeholder cross-refs, eval counts/diversity, secret & import regex, framework symbol existence, eval-run analysis, packaging/git hygiene — and returns them in rule format. Parse `Data.Issues[]`; each issue is `{RuleId, Category, Severity, Description, File, SuggestedFix}`. Carry each into the report **verbatim** — do not re-derive, rename, or re-rank. These rule IDs are authoritative as emitted by the CLI; they are **not** listed in the skill catalog.
 
@@ -265,10 +272,9 @@ The CLI runs every deterministic static check — structural/schema, placeholder
 
 | Signals present | Project type | Catalog files |
 |---|---|---|
-| `agent.json` AND no `main.py` AND no `pyproject.toml` | Agent (low-code) | `references/agents/agents-common-rules.md` + `references/agents/agents-lowcode-rules.md` |
-| `pyproject.toml` + `main.py` + any of `langgraph.json` / `llama_index.json` / `openai_agents.json` / `google_adk.json` / `pydantic_ai.json` / `agent_framework.json` | Agent (coded) | `references/agents/agents-common-rules.md` + `references/agents/agents-coded-rules.md` |
+| `agent.json.type == "lowCode"` | Agent (low-code) | `references/agents/agents-lowcode-rules.md` |
+| Python coded-agent signals or `agent.json.type == "coded"` | Agent (coded) | `references/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 |
 | `project.json` + `.xaml` / `.cs` | RPA | *(phase 2)* |
 | `*.flow` | Flow | *(phase 2)* |
 | `.uipath/` or `app.config.json` | Coded App | *(phase 2)* |
@@ -628,7 +634,6 @@ This maps the letter to the verdict word only. The agent grade is `min(G_det, G_
 | Compute the A–F letter grade for an agent (Step 4.5) | [agent-grading-rubric.md](references/agents/agent-grading-rubric.md) |
 | Understand the rule row schema | [rule-format.md](references/rule-format.md) |
 | Run the review CLI + judgment catalog (Step 2.5) | [rule-catalog-workflow.md](references/rule-catalog-workflow.md) |
-| Apply common rules for agents (both formats) | [agents-common-rules.md](references/agents/agents-common-rules.md) |
 | Apply the low-code agent judgment catalog | [agents-lowcode-rules.md](references/agents/agents-lowcode-rules.md) |
 | Apply the coded agent judgment catalog | [agents-coded-rules.md](references/agents/agents-coded-rules.md) |
 | Understand the full review workflow in detail | [review-workflow-guide.md](references/review-workflow-guide.md) |

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

@@ -11,7 +11,7 @@ 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).
+- **G_jud** — non-deterministic sub-grade. Driven by judgment: the format-specific agent judgment catalog 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`**.
 

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

@@ -123,7 +123,6 @@ Before reviewing implementation details, verify the right agent type was chosen:
 | `pyproject.toml` exists with valid config | Critical | Read pyproject.toml *(rule: `MISSING_PYPROJECT`)* |
 | ~~`pyproject.toml` does NOT have `[build-system]` section~~ | ~~Critical~~ | **Retired** — the corresponding `NO_BUILD_SYSTEM` rule was retired (SDK FAQ shows `pyproject.toml` with `[build-system]` per PEP 518). Keep only as manual check if specific `uip codedagent` packaging errors point at it. |
 | `.env` file not committed to source control | Critical | Check .gitignore and git status *(rule: `ENV_FILE_TRACKED`, `GITIGNORE_INCOMPLETE`)* |
-| `entry-points.json` present | Warning | `ls entry-points.json` *(rule: `ENTRY_POINTS_MISSING`, `LOWCODE_ENTRY_POINTS_MISSING`)* |
 
 ### Dependencies (pyproject.toml)
 
@@ -295,9 +294,6 @@ Review whether the agent design accounts for known UiPath limitations:
 
 | Check | Severity | How to Verify |
 |---|---|---|
-| `entry-points.json` present and correct | Warning | Read entry-points.json *(rule: `ENTRY_POINTS_MISSING`, `LOWCODE_ENTRY_POINTS_MISSING`)* |
-| `agent.json` ↔ `entry-points.json` schemas match (agent-builder) | Critical | Compare inputs/outputs *(rule: `LOWCODE_SCHEMA_DRIFT`)* |
-| `bindings.json` present (if using external resources) | Warning | Read bindings.json |
 | Agent validates without errors | Critical | Run validation command |
 | Smoke evaluation passes (70%+ score) | Warning | Run evaluations *(rule: `EVAL_RUN_LOW_PASS_RATE`, `EVAL_RUN_NEVER_EXECUTED`)* |
 | No `.env` file or secrets in committed code | Critical | Check git status *(rule: `ENV_FILE_TRACKED`, `GITIGNORE_INCOMPLETE`, `HARDCODED_CREDENTIALS`)* |

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

@@ -6,11 +6,6 @@ Judgment rules for **coded** agents (Python — `main.py` + framework config). E
 
 Read [`../rule-format.md`](../rule-format.md) and [`../rule-catalog-workflow.md`](../rule-catalog-workflow.md) first.
 
-Companion files:
-
-- [`agents-common-rules.md`](agents-common-rules.md) — judgment rule shared with low-code agents (schema-description informativeness)
-- [`agents-lowcode-rules.md`](agents-lowcode-rules.md) — low-code judgment rules (for the agent-builder coded layout that ships both `agent.json` and `main.py`)
-
 ## Framework detection
 
 Many rules below gate on framework. Detect once and reuse:
@@ -72,6 +67,7 @@ LLM-judge-only is acceptable when the agent has no tools, no classification outp
 
 | rule_id | severity | category | trigger | detection_method | suggested_fix |
 |---|---|---|---|---|---|
+| `SCHEMA_NO_DESCRIPTIONS` | judgment | schema | Input/output schema properties lack **informative** descriptions | Read the authored input/output models. Judge field descriptions for useful semantic guidance, not mere presence; assess input and output separately. | Add a useful description to each field. |
 | `CODED_SCHEMA_COMPLETENESS` | warning | schema | `StateGraph` input/output schema is technically present but the fields are insufficient for the agent's contract | Read `StateGraph(input=..., output=...)` (or `_schema=` variants). Read the agent's actual behavior. Assess: are declared input/output fields meaningful and sufficient? An agent that needs `customer_history` + `recent_invoices` but only declares `query: str` is incomplete. file = source file. | Expand the schema to carry the context the agent actually needs / returns. |
 | `CODED_SCHEMA_FIELD_NO_VALIDATION` | warning | schema | Constrained-value field declared as bare `str` (no `Literal`/`Enum`/regex pattern) | Read Pydantic / dataclass models. Assess per field: does the name suggest a constrained set (`category`, `status`, `severity`, `role`, `intent`, `classification`, `priority`)? AND is the type bare `str` (no `Literal`, no `Enum`, no validator)? AND does the agent's logic visibly map to a small enumerated set? Emit per concrete case. file = source file, element = `<Model>.<field>`. | Type the field as `Literal["a", "b", "c"]` or `Enum`, or add `Field(..., pattern="...")`. |
 | `CODED_OUTPUT_ENUM_MISSING_ON_CLASSIFIER` | warning | schema | Classifier-shaped output field declared without enum | Read output schema (Pydantic field, `StateGraph` output annotation, dataclass). Identify classifier-shape fields by name (`class`, `classification`, `label`, `category`, `intent`, `severity`, `priority`, `status`) with `type: str`. Assess: is there a `Literal[...]` / `Enum` / pattern constraint? Both this rule and `CODED_SCHEMA_FIELD_NO_VALIDATION` can fire on the same field — the more-specific firing clarifies the issue. file = source file, element = field name. | Add `Literal[...]` / `Enum` / pattern constraint to the classifier output field. |
@@ -92,11 +88,6 @@ LLM-judge-only is acceptable when the agent has no tools, no classification outp
 
 ## GuardrailsChecker
 
-> **Agent-builder coded layout** (`agent.json` + `main.py`): `agent.json`'s `guardrails[]` are reviewed by the
-> low-code semantic rules (`LC_GUARDRAIL_*`) via the low-code catalog + [`guardrails/guardrails-review.md`](guardrails/guardrails-review.md)
-> (this layout loads all three catalogs — see the detection table). The rules below cover **pure-coded** guardrails —
-> SDK middleware / `@guardrail` decorators wired in the entry `.py` (LangChain/LangGraph today), no `agent.json`.
-
 > **Validator-name authority.** Same caution as low-code: do NOT name a platform-documented validator
 > (`harmful_content` / `intellectual_property` / `user_prompt_attacks`) unless it is already present in the agent's
 > code — phrase generically (e.g. "an appropriate content-safety guardrail"). `pii_detection` / `prompt_injection`

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

@@ -6,10 +6,6 @@ Judgment rules for **low-code** agents (`agent.json`). Each rule requires the ag
 
 Read [`../rule-format.md`](../rule-format.md) and [`../rule-catalog-workflow.md`](../rule-catalog-workflow.md) first.
 
-Companion file:
-
-- [`agents-common-rules.md`](agents-common-rules.md) — judgment rule shared with coded agents (schema-description informativeness)
-
 ## Layouts
 
 Low-code agents exist in two layouts. Detect first, then apply the right `Read` path in each rule.
@@ -17,7 +13,7 @@ Low-code agents exist in two layouts. Detect first, then apply the right `Read`
 | Layout | Identifier | Key files |
 |---|---|---|
 | **Normalized** | A single JSON file with snake_case top-level keys (`system_prompt`, `tools`, `datasets`, `input_schema`, `output_schema`, `user_prompt`) | The single JSON file |
-| **Agent-builder** | `agent.json` at project root with camelCase keys + sibling `entry-points.json`, `project.uiproj`, `resources/<Name>/resource.json` | `agent.json`, `entry-points.json`, `resources/*/resource.json`, `evals/eval-sets/*.json`, `evals/evaluators/*.json` |
+| **Agent-builder** | `agent.json` at project root with camelCase keys + sibling `project.uiproj` and `resources/<Name>/resource.json` | `agent.json`, `resources/*/resource.json`, `evals/eval-sets/*.json`, `evals/evaluators/*.json` |
 
 Rules tagged `(agent-builder only)` skip silently on the normalized layout; `(normalized only)` skip on agent-builder. Untagged rules apply to both with layout-aware `detection_method`.
 
@@ -40,6 +36,7 @@ One H2 section per checker class (`EvalsChecker`, `SchemaChecker`, `ToolsChecker
 
 | rule_id | severity | category | trigger | detection_method | suggested_fix |
 |---|---|---|---|---|---|
+| `SCHEMA_NO_DESCRIPTIONS` | judgment | schema | Input/output schema properties lack **informative** descriptions | Read `.input_schema` / `.output_schema` in normalized JSON, or `agent.json.inputSchema` / `outputSchema` in Agent Builder. Judge property descriptions for useful semantic guidance, not mere presence; assess input and output separately. | Add a useful description to each property. |
 | `LC_OUTPUT_FORMAT_PROMPT_DRIFT` | warning | schema | System prompt instructs an output shape that conflicts with `outputSchema` | Read system prompt + `outputSchema`. Assess: does the prompt instruct a shape (`"respond with a single sentence"`, `"answer in markdown"`) that conflicts with the schema's structure (structured JSON, flat string, etc.)? Emit when prompt-vs-schema drift is present. file = system prompt source. | Align the prompt's output-format instructions with `outputSchema` — pick one source of truth and have the other reference it. |
 | `LC_INPUT_SCHEMA_OVERLAP` | warning | schema | Input schema has ≥2 fields with semantically overlapping names or descriptions | Read `inputSchema.properties`. Assess: are there fields with semantically overlapping names (`query` vs `question` vs `text` vs `prompt` vs `input`) or descriptions? Emit when ≥2 fields could reasonably hold the same content and the LLM would have to disambiguate at runtime. file = schema source, element = `<field_a>,<field_b>`. | Merge overlapping fields, or differentiate them with clear names + descriptions that scope each one. |
 | `LC_OUTPUT_ENUM_VS_PROMPT_DRIFT` | warning | schema | Output enum disagrees with the prompt's category list (either side has extras) | Read `outputSchema.properties.<X>.enum` and the system prompt's classification list (`"Classify into: A, B, C"`). Assess: do the two sets agree? Emit when either has extras: prompt names a class the schema doesn't accept (runtime validation rejects), OR schema accepts a class the prompt never mentions (LLM never produces it). file = schema or prompt source. | Reconcile the prompt's class list with `outputSchema.enum`. |
@@ -94,7 +91,7 @@ One H2 section per checker class (`EvalsChecker`, `SchemaChecker`, `ToolsChecker
 
 | rule_id | severity | category | trigger | detection_method | suggested_fix |
 |---|---|---|---|---|---|
-| `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_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). It also preserves a source-evidence clause in the form `<source path>: <exact matching identifier(s)>`; copy schema properties, tool names, and resource names verbatim instead of paraphrasing them (for example, `agent.json inputSchema.properties: customer_email, full_name, ssn`). 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. |