docs(salesforce): document PSG grant model for CXP-288

[carolinaroncaglia]

Summary

• Documents the two new grant types introduced in CXP-288 (PSG → User grants via PermissionSetAssignment, PSG → Permission Set grants via PermissionSetGroupComponent)
• Explains transitive access expansion behavior via GrantExpandable annotation
• Adds a note clarifying that PSG grants require PermissionSetAssignment records targeting a PSG

Related

• Linear: https://linear.app/ductone/issue/CXP-288
• PR: cxp-288 add psg user grants #105

[linear]

CXP-288 Salesforce: Sync Permission Set Group → User and Permission Set Group → Permission Set mappings

[github-actions]

Claude finished @carolinaroncaglia's task in 1m 35s —— View job

---

PR Review: docs(salesforce): document PSG grant model for CXP-288

• Gather context and read changed files
• Verify documentation against connector implementation
• Review documentation changes
• Post review feedback

---

Looks good! I verified all four claims in this documentation against the actual connector code:

Claim	Status	Source
PSG → User grants emitted as member	Verified	pkg/connector/permission_set_group.go:16, 84-112
PSG → Permission Set grants emitted as assigned	Verified	pkg/connector/permissions.go:19, 126-157
PSG is the principal in PSG → PS grants	Verified	pkg/connector/permissions.go:146-156
GrantExpandable annotation for transitive expansion	Verified	pkg/connector/permissions.go:153-156 + test at permissions_test.go:56-59

The Salesforce API object names (PermissionSetAssignment, PermissionSetGroupComponent) also match the client queries in pkg/connector/client/salesforce.go.

Minor observations (non-blocking)

1. Placement: The new section sits between an asterisk footnote (*You have the option to sync... at line 37) and the "Connector actions" heading. This is a reasonable spot — it's within the Capabilities area. Just noting that the asterisk footnote on line 37 isn't closed (pre-existing, not introduced by this PR).

2. Line length: Lines 43 and 45 are quite long (~200+ chars). This is fine for rendered MDX but could be harder to review in diffs. Totally optional to wrap — just mentioning it.

No bugs, no inaccuracies, no missing information. This is a clean, accurate documentation addition. Approve.

[github-actions]

🟡 Suggestion: The note opens scoped to "PSG → User grants" but closes with the broader "PSG grants will not appear", which contradicts the second bullet. PSG → Permission Set grants come from PermissionSetGroupComponent (GetPermissionSetGroupComponentsByPermissionSet in pkg/connector/client/salesforce.go:902) and are emitted regardless of whether any PermissionSetAssignment targets a PSG. Suggest narrowing the last sentence so it only covers user membership.

Suggested change

	PSG → User grants require at least one `PermissionSetAssignment` record in Salesforce where the target is a Permission Set Group. If your Salesforce instance assigns access only through individual Permission Sets, PSG grants will not appear.
	PSG → User grants require at least one `PermissionSetAssignment` record in Salesforce where the target is a Permission Set Group. If your Salesforce instance assigns access only through individual Permission Sets, PSG → User grants will not appear (PSG → Permission Set grants are unaffected, since they come from `PermissionSetGroupComponent` records).

[github-actions]

Connector PR Review: docs(salesforce): document PSG grant model for CXP-288

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

Review Summary

Scanned the full PR diff for security and correctness: this is a docs-only change adding a "Permission set group grants" section to docs/connector.mdx (12 additions, no code or dependency changes). I verified both documented grant paths against the implementation — the member entitlement and PermissionSetAssignment-derived PSG grants in pkg/connector/permission_set_group.go:69-107, and the assigned grant with the PSG principal plus GrantExpandable annotation in pkg/connector/permissions.go:126-167 — and both descriptions are accurate. One wording imprecision in the closing note is flagged as a non-blocking suggestion.

Security Issues

None found.

Correctness Issues

None found.

Suggestions

• docs/connector.mdx:60 — The note's final sentence generalizes to "PSG grants will not appear", which contradicts the PSG → Permission Set bullet above it; those grants derive from PermissionSetGroupComponent and are independent of PermissionSetAssignment records.

Prompt for AI agents

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

## Suggestions

In `docs/connector.mdx`:
- Around line 60: The <Note> block starts by scoping its requirement to "PSG → User grants"
  but ends with the broader claim "PSG grants will not appear". That contradicts the second
  bullet in the same section: PSG → Permission Set grants are derived from
  `PermissionSetGroupComponent` records (see GetPermissionSetGroupComponentsByPermissionSet in
  pkg/connector/client/salesforce.go and the Phase 2 branch of permissionBuilder.Grants in
  pkg/connector/permissions.go) and are emitted regardless of whether any
  PermissionSetAssignment targets a Permission Set Group. Change the final sentence to say
  "PSG → User grants will not appear" and note that PSG → Permission Set grants are unaffected
  because they come from PermissionSetGroupComponent records.

[github-actions]

No blocking issues found.