f832bce16d
Adds a checklist comment at the top of internal/router/rbac.go that
explains how to pick between the four role-only guards
(Viewer / Contributor / Admin / Owner) and the ownership-or-role
guards (OwnedKBOrAdmin and friends) when wiring a new route.
The two questions encoded here:
Q1. Does the resource have a creator?
YES → mutating routes use OwnedXxxOrAdmin
NO → tenant-wide infra → Admin()
ENTRY POINT (creating a brand-new owned resource) → Contributor()
Q2. Is the side effect "private to me" or "visible to others"?
PRIVATE → Contributor() is fine (e.g. POST /agents/:id/copy)
PUBLIC → OwnedXxxOrAdmin or Admin (sharing, transferring,
tenant-wide toggles)
The recurring failure mode caught in this PR — FAQ entries, tag CRUD,
KB share, agent share, /shared-agents/disabled all gated to plain
Contributor while the matrix demanded OwnedXxxOrAdmin — is the
"sub-resource drift" anti-pattern: someone wires a new sub-resource
with a freshly-invented gate instead of inheriting from the parent
KB/Agent's matrix.
Also documents the user-facing invariant the guards together produce
("Contributor in their own KB acts like Owner; Contributor in someone
else's KB acts like Viewer") so reviewers have a UX-level sanity check
beyond the role labels.