docs(guardrails): document bring-your-own (BYOG) guardrail configurations [AL-513]

[apetraru-uipath]

What changed?

Documents the new bring-your-own guardrail (BYOG) feature across every guardrail area of the skills repo, mirroring the existing BYO LLM Gateway doc convention:

• New: skills/uipath-platform/references/guardrails/byo-configurations.md — admin-side reference for uip guardrails byo-configurations list (list-only today; registration is Admin UI only). Wired into uipath-platform/SKILL.md (frontmatter, command table, references list) and CODEOWNERS.
• uipath-agents (low-code + coded guardrails, guardrails-recommend — 4 files): explains the BYOG concept, the --byo filter, IsByo/Byo* fields, that Validator is not unique once a BYOG config exists, how to pin a low-code guardrail to one (byoConfigurationId), how a coded agent wires one in (fetch SDK docs first — never hardcode ByoValidator(...) from memory), and a disambiguation fix so recommend/validate lookups don't collide a built-in and BYO entry sharing the same name.
• uipath-review (2 files): same disambiguation note, plus a callout that a BYO entry's Status: Disabled is a tenant config switch, not a schema defect.
• uipath-troubleshoot: added BYOG as a possible cause of a guardrail violation, a step to cross-check BYOG health, and a resolution path for a dead connection or disabled config.

Ticket: AL-513.

How has this been tested?

Ran scripts/check-skill-verbs.py against every touched file. All findings are either pre-existing soft-stale placeholder noise already present in this repo, or the expected hard-stale hits on uip guardrails byo-configurations list (7 occurrences) — that command isn't in the published CLI catalog snapshot yet because it ships on the CLI's feat/al-512-agent-guardrails-byo-configurations branch, not yet merged/published. The CLI Verb Gate check on this PR is expected to fail until that CLI change merges and assets/uip-catalog-snapshot.json is refreshed — this is a doc-vs-CLI sequencing issue, not a documentation error. No new automated coder-eval test fixtures were added this round (BYOG configs have no CLI create/update/delete verb, so a task can't provision one reliably yet); revisit once the CLI adds BYOG CRUD.

Are there any breaking changes?

• None

[github-actions]

Claude finished @apetraru-uipath's task in 4m 8s —— View job

---

PR Review: docs(guardrails): document bring-your-own (BYOG) guardrail configurations AL-513

• Read review criteria and project conventions
• Read full diff and existing PR conversation
• Read all changed files in full context
• Check skill-specific rules (links, cross-references, CODEOWNERS, secrets)
• Post review findings

---

Summary

Documents the new bring-your-own guardrail (BYOG) feature across the uipath-platform, uipath-agents, uipath-review, and uipath-troubleshoot skills. Adds a new reference file for uip guardrails byo-configurations list, updates CODEOWNERS, and threads BYOG disambiguation into coded/lowcode guardrail authoring, review audit, and troubleshooting playbooks. Well-structured change that mirrors the existing BYO LLM pattern.

Change-by-Change Review

1. CODEOWNERS

Severity: OK
New entry /skills/uipath-platform/references/guardrails/ @apetraru-uipath @valentinabojan @ctiliescuuipath correctly scoped to the new directory.

2. skills/uipath-platform/SKILL.md

Severity: Medium — description field now at 1038 characters, exceeding the 1024-char repo cap (was 1001 on main). The addition of BYO guardrail (BYOG) configurations pushed it over. Combined description + when_to_use is 2551 chars (Claude Code truncates at 1536). The when_to_use was already over 1024 before this PR, but the description going over the cap is new.

The new command table rows, trigger bullet, and references-list entry are all well-placed and link-correct. The #diagnostics anchor in the task navigation table resolves to a valid heading in byo-configurations.md:80.

Fix this →

3. skills/uipath-platform/references/guardrails/byo-configurations.md (new file)

Severity: OK
Excellent new reference. Clean structure: command, output shape with field table, error case, cross-skill delegation via /uipath: syntax, diagnostics section. The relative link to ../integration-service/connections.md resolves correctly. The JSON example is realistic. The "list-only today" callout is a good guardrail against agents trying non-existent verbs.

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

Severity: OK
New ## BYO (bring-your-own) validators section is well-placed between Step 0 and Step 1. The "do not hardcode" posture mirrors EscalateAction (Critical Rule 14) — consistent and safe. Discovery steps are prescriptive with copy-paste CLI commands. New Critical Rule 18 correctly summarizes the section. Fragment link #byo-bring-your-own-validators matches the heading.

5. skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md

Severity: OK
Three insertions: (1) Validator not-unique note at lookup-build step, (2) built-in-vs-BYO default recommendation policy, (3) disambiguation in correctness-check prose, (4) new Critical Rule 16. All link to guardrails.md#byo-bring-your-own-validators which resolves correctly. The "default to built-in" policy is a sound agent-safety decision.

6. skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md

Severity: OK
Adds two new rows to the field mapping table (IsByo, ByoConfigurationId), a ## BYO (bring-your-own) guardrails section, and Critical Rule 21. Content is scoped to low-code JSON authoring (not coded Python) — no overlap with the coded twin beyond the shared concept. Fragment link #byo-bring-your-own-guardrails matches the heading.

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

Severity: OK
Same pattern as the coded recommend twin: lookup disambiguation, default-to-built-in policy, correctness-check update, Critical Rule 15. Links to guardrails.md#byo-bring-your-own-guardrails (lowcode heading) — correct.

8. skills/uipath-review/references/agents/guardrails/coded-guardrails-review.md

Severity: OK
Two additions: (1) Validator not-unique note at the lookup step with review-specific context (match by ByoValidatorName/connection id when code wires a BYO construct), (2) Status: "Disabled" is a config switch, not a wiring bug — appropriate for review context. Both delegate to /uipath:uipath-agents for detail.

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

Severity: OK
Same pattern as the coded review twin but scoped to low-code audit mode: lookup disambiguation note and disabled-config callout. Links to /uipath:uipath-agents — correct.

10. skills/uipath-troubleshoot/references/products/agents/playbooks/guardrail-violation.md

Severity: OK
Three additions: (1) BYOG as a root-cause bullet in "What can cause it", (2) a conditional diagnostic step (check BYOG health when IsByo: true), (3) a resolution paragraph for dead connection / disabled config. The --output-filter JMESPath is syntactically valid and consistent with existing usage in this playbook. The link to /uipath:uipath-platform for connection repair is a proper cross-skill delegation.

What's Missing

• description field exceeds 1024-char repo cap (1038 chars). Needs trimming by ~14 characters to pass the validation hook. This is the only actionable item.
• No coder-eval test tasks for the new uip guardrails byo-configurations list command. The PR author explains this is because BYOG has no CLI create/update/delete verb yet, making reliable test provisioning impossible. Acknowledged as a valid sequencing constraint — revisit when BYOG CRUD lands.
• The uip guardrails byo-configurations list command isn't in the published CLI catalog snapshot yet (acknowledged in the PR body — expected CLI verb gate failure until the CLI branch merges).

Area Ratings

Area	Status	Notes
Frontmatter	Issue	description at 1038 chars, over the 1024-char repo cap
E2E Tests	N/A	No CLI CRUD verbs to test against yet — acknowledged
Skill Body	OK	Well-structured additions across all four skills
References & Assets	OK	New file is clean; all links resolve; no orphaned files
Repo Hygiene	OK	CODEOWNERS updated; no secrets; no cross-skill file dependencies; scoped changes

Issues for Manual Review

• CLI command accuracy: uip guardrails byo-configurations list, uip agent guardrails list --byo, and the --output-filter JMESPath expressions cannot be verified without a live tenant. The author confirms these ship on a pending CLI branch.
• SDK construct ByoValidator(<ValidatorName>, connection_id=<ConnectionId>): referenced in byo-configurations.md:47 and the coded guardrails section — verify this matches the actual Python SDK once the docs publish.
• Output shape fields (Id, ConnectionId, ValidatorName, ValidatorType, FallbackOnUiPath, Enabled, ValidConnection, etc.): verify against the actual API response once the CLI merges.

Conclusion

Clean, well-structured documentation PR that consistently threads BYOG awareness across four skills without introducing structural cross-skill dependencies. The only actionable finding is the description field exceeding the 1024-char repo cap (Medium) — a ~14-character trim resolves it. Everything else (section placement, anchor links, reference pointer discipline, cross-skill delegation syntax, CODEOWNERS) is correct.

---