docs: document RBAC space roles and correct noun/verb defaults

[c1-dev-bot]

Summary

• Add Space Roles and Space Role Assignments to the Capabilities table as opt-in resource types
• Add a new "RBAC space roles" section documenting --use-rbac mode: what it does, the either/or relationship with granular permissions, and a troubleshooting warning for the 404 error when RBAC endpoints are unavailable on the Confluence instance
• Add BATON_USE_RBAC to the self-hosted Kubernetes secrets example
• Correct the noun/verb defaults section: the values pre-filled in the C1 config form are suggested values only — when no nouns/verbs are explicitly configured, the connector syncs all available nouns and verbs (5 nouns × 8 verbs), not just the subset shown in the form
• Add a cross-reference note linking the space permissions section to the RBAC section

Fixes: CXP-872

---

Automated PR Notice

This PR was automatically created by c1-dev-bot as a potential documentation update.

This documentation requires:

• Human review for accuracy and completeness
• Verification that it matches current product behavior
• Approval from the appropriate team before merging

[linear-code]

CXP-872

[github-actions]

🟡 Suggestion: The two resource types aren't gated the same way. spaceRoleBuilder is registered unconditionally (pkg/connector/connector.go:165) and its List runs regardless of useRbac (pkg/connector/space_roles.go:24-31) — Space Roles are gated only by the OptInRequired annotation (pkg/connector/helpers.go:25-30), not by --use-rbac. Only Space Role Assignments are --use-rbac-gated, via the ChildResourceType annotation added in spaces.go:224-228. Consider saying both types require C1-side opt-in and that --use-rbac is what enables role assignment sync and disables granular permissions.

[github-actions]

🟡 Suggestion: "built-in space roles" understates the scope — GetSpaceRoles returns custom roles too (see the comment at pkg/connector/space_role_assignments.go:39: "4 defaults + 10 custom"). Suggest "built-in and custom space roles".

[github-actions]

🟡 Suggestion: The comment reads "Optional: include to use RBAC..." but the key itself is commented out, unlike the other optional entries above (BATON_PROVISIONING, BATON_SKIP_PERSONAL_SPACES), which are live. Copy-pasting this block silently leaves RBAC off. Suggest matching the surrounding style.

Suggested change

	# Optional: include to use RBAC space roles instead of granular permissions
	# BATON_USE_RBAC: true
	# Optional: include to use RBAC space roles instead of granular permissions
	BATON_USE_RBAC: true

[github-actions]

Connector PR Review: docs: document RBAC space roles and correct noun/verb defaults

Blocking Issues: 0 | Suggestions: 3 | Threads Resolved: 0
Criteria: Criteria status: loaded .claude/skills/ci-review.md from trusted base 0cc063a354f5.
Review mode: full
View review run

Review Summary

Docs-only change to docs/connector.mdx (no Go, go.mod, or go.sum changes); the full PR diff was scanned for security and correctness. I verified the substantive claims against the code: the noun/verb correction is accurate (filterArgs in pkg/connector/connector.go:58-89 falls back to the full 5-noun/8-verb defaults when the flags are empty, while pkg/config/config.go:8-19 only supplies the smaller set as WithSuggestedValue), the listed nouns/verbs match defaultNouns/defaultVerbs exactly, the quoted Validate failure text matches pkg/connector/client/confluence.go:134-136, and the capabilities table matches the implementation (Space Roles sync-only; Space Role Assignments have working Grant/Revoke). Three non-blocking accuracy and consistency nits are noted below.

Security Issues

None found.

Correctness Issues

None found.

Suggestions

• docs/connector.mdx:35 — "Space Roles and Space Role Assignments resource types become active" is imprecise: spaceRoleBuilder is registered and lists unconditionally; only Space Role Assignments are gated on --use-rbac.
• docs/connector.mdx:33 — "built-in space roles" omits custom roles, which GetSpaceRoles also returns.
• docs/connector.mdx:210-211 — BATON_USE_RBAC is commented out in the Kubernetes secret example while the other optional keys are live, which is inconsistent for copy-paste use.

Prompt for AI agents

Verify each finding against the current code and only fix it if needed.

Suggestions:

In `docs/connector.mdx`:
- Around line 33: The RBAC bullet describes the mode as syncing "built-in space roles".
  GetSpaceRoles also returns customer-defined custom roles (see the comment in
  pkg/connector/space_role_assignments.go around line 39: "up to 14 roles, 4 defaults +
  10 custom roles"). Change the wording to "built-in and custom space roles".

- Around line 35: The sentence "When RBAC mode is enabled, granular space permissions are
  not synced, and the Space Roles and Space Role Assignments resource types become active"
  is not accurate for Space Roles. spaceRoleBuilder is registered unconditionally in
  pkg/connector/connector.go (ResourceSyncers), and its List method in
  pkg/connector/space_roles.go does not check useRbac, so space roles sync whenever the
  resource type is opted into in C1 (both types carry the OptInRequired annotation set in
  pkg/connector/helpers.go). Only Space Role Assignments are gated on --use-rbac, via the
  ChildResourceType annotation that spaceResource adds in pkg/connector/spaces.go only
  when useRbac is true. Rewrite so it says both resource types require opt-in in C1, and
  that --use-rbac is what turns off granular space permission entitlements and grants and
  turns on space role assignment sync under each space.

- Around lines 210-211: In the Kubernetes secrets YAML example, BATON_USE_RBAC is added as
  a commented-out line, even though its explanatory comment says "Optional: include to use
  RBAC space roles instead of granular permissions", while the other optional keys in the
  same block (BATON_PROVISIONING, BATON_SKIP_PERSONAL_SPACES) are live YAML. Uncomment the
  key so the block is internally consistent, or reword the comment to make clear the line
  must be uncommented to take effect.

[github-actions]

No blocking issues found.