docs(guardrails): document BYOG admin configuration [AL-513]

[apetraru-uipath]

What changed?

Split out of #2516 (agent-authoring side of bring-your-own guardrails) so this platform-owned reference doesn't need to ride on that PR's approvals.

• New: skills/uipath-platform/references/guardrails/byo-configurations.md — the tenant-admin side of BYOG: the full uip guardrails byo-configurations lifecycle (list/create/update/delete), mirroring the existing BYO LLM Gateway doc's structure.
• skills/uipath-platform/SKILL.md: frontmatter triggers, command table, references list wired to the new doc.

Key semantics documented:

• ValidatorName is unique per tenant and is the only value agents reference — no connection_id passed by the agent; the platform resolves the connection server-side.
• update has merge semantics; ValidatorName/ValidatorType are locked at creation (delete + re-create to change them).
• delete requires --force.
• 404 splits into ByoGuardrailsUnavailable (feature flag off) vs. ByoGuardrailConfigurationNotFound (bad id).
• The endpoint requires an org-admin user token and rejects application tokens.

#2516 already references this content only via the skill-level /uipath:uipath-platform link (never a literal file path), so it isn't blocked on this PR merging first — no cross-PR ordering dependency.

How has this been tested?

• scripts/check-skill-verbs.py: no hard-blocking (matched_prefix: null) findings against the current catalog (uip guardrails byo-configurations * resolves).
• scripts/check-task-driver.py: clean.
• SKILL.md frontmatter YAML parses correctly.
• This is a documentation-only change (no test task) — the agent-authoring behavior it enables is covered by byog_pinning in docs(guardrails): document bring-your-own (BYOG) guardrail configurations [AL-513] #2516.

Are there any breaking changes?

• None

[github-actions]

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

---

PR Review: docs(guardrails): document BYOG admin configuration

• Read review criteria and project conventions
• Read full diff and changed files
• Verify relative links resolve
• Check CODEOWNERS
• Check cross-skill references
• Check for secrets/tokens/personal paths
• Post review findings

---

Summary

Adds references/guardrails/byo-configurations.md documenting the uip guardrails byo-configurations CLI lifecycle (list/create/update/delete) and wires it into SKILL.md via frontmatter triggers, a command table entry, and the reference navigation list. Clean, well-structured reference that mirrors the existing BYO LLM doc's shape.

Change-by-Change Review

1. skills/uipath-platform/SKILL.md — frontmatter & body additions

Severity: High (description length)

The description field grew from 1001 → 1038 characters, exceeding the repo's 1024-character cap by 14 chars. This would fail hooks/validate-skill-descriptions.sh and the CI check.

The added text is , BYO guardrail (BYOG) configurations (37 chars) in the Covers ... clause. To fit, consider abbreviating — e.g. , BYOG guardrail configurations (saves 7 chars) — or trimming elsewhere in the description.

Fix this →

Body additions (lines 55, 177–178, 314) — OK. The new SKILL.md bullet (line 55), command-table rows, and reference-navigation entry are well-written bridge content: they summarize key semantics (validator-name uniqueness, merge semantics, --force, no get) and link to the reference without duplicating detail. Follows the Reference Pointer Discipline correctly. Cross-skill links use /uipath:uipath-agents skill-link syntax — no file-path references to other skills.

2. skills/uipath-platform/references/guardrails/byo-configurations.md (new file, 148 lines)

Severity: OK

High-quality reference doc:

• Structure: Subcommand surface table → per-verb sections with copy-paste CLI examples → error paths → agent-authoring bridge → diagnostics. Follows the BYO LLM reference pattern closely.
• Prescriptive: All CLI commands include --output json, required/optional flags are specified, error handling covers three distinct failure modes (feature unavailable, config not found, permission denied) with clear agent instructions for each.
• Placeholders: <is-connection-uuid>, <configuration-id>, <connection-id>, <new-uuid> use angle-bracket UPPER_SNAKE_CASE or self-describing kebab-case — consistent.
• Relative links: ../llmgateway/byo-connections.md and ../integration-service/connections.md both resolve. Cross-skill links (/uipath:uipath-agents, /uipath:uipath-troubleshoot) use skill-link syntax.
• Token optimization: Terse prose, no filler, code block comments stripped. Field table on list output is thorough without being verbose.
• No secrets/personal paths: Only documentation references to "token" in auth-requirement context.

What's Missing

• CODEOWNERS subdirectory entry: The existing pattern gives subdirectory-specific ownership to domain teams (e.g. /skills/uipath-platform/references/llmgateway/ → @denispetre et al., /skills/uipath-platform/references/integration-service/ → @chandusailella @baishalighosh). There is no /skills/uipath-platform/references/guardrails/ entry. The parent /skills/uipath-platform/ entry (line 26) still covers it — so this is a pattern-consistency suggestion, not a hard blocker. If guardrails has a dedicated team, add a matching line. Low.
• No test task for the new capability — acceptable for a docs-only reference; the PR description notes the agent-authoring behavior is covered by the byog_pinning task in docs(guardrails): document bring-your-own (BYOG) guardrail configurations [AL-513] #2516.

Area Ratings

Area	Status	Notes
Frontmatter	Issue	description is 1038 chars, 14 over the 1024-char limit
E2E Tests	OK	Docs-only change; agent behavior tested via #2516
Skill Body	OK	Bullet, table rows, and reference link are correct bridge content
References & Assets	OK	New reference is thorough, well-structured, and correctly linked
Repo Hygiene	OK	No secrets, no cross-skill file references, changes scoped to uipath-platform

Issues for Manual Review

• CLI command accuracy: Verify that uip guardrails byo-configurations subcommands (list/create/update/delete) and their flags match the actual CLI. The --force requirement on delete, --disabled/--enabled mutual exclusivity, and the merge semantics of update should be spot-checked against the implementation.
• Error code names: Confirm ByoGuardrailsUnavailable, ByoGuardrailConfigurationNotFound, ByoGuardrailConfigurationCreated, ByoGuardrailConfigurationUpdated, ByoGuardrailConfigurationDeleted, and ByoGuardrailConfigurationsList are the actual response codes.
• CODEOWNERS ownership: Decide whether /skills/uipath-platform/references/guardrails/ needs a dedicated entry for a guardrails-specific team, or whether the platform-team parent entry is intentionally correct.

Conclusion

One High issue: the frontmatter description exceeds the 1024-char repo cap by 14 characters — this needs trimming before merge to pass the validation hook. The reference document itself is clean and well-structured. Recommend fixing the description length and optionally adding a CODEOWNERS entry for the guardrails subdirectory.

---

[apetraru-uipath]

This file/doc moved here from #2516 (agent-authoring PR) so it doesn't need uipath-platform CODEOWNERS approval riding on that PR. Carrying forward review context from the threads on #2516, since they now point at a diff this PR no longer has:

1. byoConfigurationId is not a real field (valentinabojan) — fixed to ByoValidatorName, matching the coded-agent ByoValidator(<ValidatorName>) pattern. Both low-code and coded now reference a BYOG configuration the same way.
2. Need a CLI command to test/validate a configuration, like BYO LLM (valentinabojan) — confirmed against the CLI source: byo-configurations create/update run no server-side validate/probe today, unlike llm-configuration byo-connections' mandatory POST .../validate. That's a real feature gap needing a CLI change, not something this docs PR can add — added a "Known gap" section here documenting it and pointing at uip is connections ping as the closest partial check available now. Worth a follow-up ticket against guardrails-tool.
3. Task Navigation vs. References list duplication in SKILL.md (valentinabojan) — this matches the existing pattern for every other reference doc in the file (LLM Gateway, Traces, Integration Service, Data Fabric all appear in both places); kept for consistency rather than making BYOG the one exception.
4. "Do we need this skill?" (apetraru-uipath, original PR author) — still open, unanswered on docs(guardrails): document bring-your-own (BYOG) guardrail configurations [AL-513] #2516. Not something I'm resolving on your behalf — flagging it here so it doesn't get lost with the move.