chore: update baton-admin doc files

Author: baton-admin[bot]

.claude/skills/connector/patterns-error-handling.md

@@ -38,6 +38,51 @@ if err != nil {
 
 ---
 
+## Wrapping Errors with uhttp.WrapErrors
+
+Use `uhttp.WrapErrors` when returning errors from HTTP calls that did **not** go through `uhttp.BaseHttpClient` — for example, SDK library errors, raw `http.Client` calls, or errors you infer yourself (e.g., "status 200 but body indicates failure").
+
+**Why it matters:** The SDK inspects the gRPC status code on errors to decide whether to retry, log, or surface the error to the operator. Without wrapping, the SDK treats all errors as opaque and cannot act appropriately.
+
+**Signature:**
+```go
+func WrapErrors(preferredCode codes.Code, statusMsg string, errs ...error) error
+```
+
+- `preferredCode` — a gRPC status code (from `google.golang.org/grpc/codes`), not an HTTP status code
+- `statusMsg` — human-readable message describing the error
+- `errs` — original errors to join into the result
+
+**Common gRPC code mappings:**
+
+| Situation | gRPC code |
+|-----------|-----------|
+| Auth failure (401) | `codes.Unauthenticated` |
+| Permission denied (403) | `codes.PermissionDenied` |
+| Not found (404) | `codes.NotFound` |
+| Rate limited (429) | `codes.ResourceExhausted` |
+| Server error (5xx) | `codes.Internal` |
+
+```go
+// SDK library error — wrap with appropriate gRPC code:
+if err != nil {
+    return nil, uhttp.WrapErrors(codes.Internal, "baton-myservice: failed to list users", err)
+}
+
+// Developer-inferred error from response body or status code:
+if resp.StatusCode == http.StatusForbidden {
+    return nil, uhttp.WrapErrors(
+        codes.PermissionDenied,
+        fmt.Sprintf("baton-myservice: access denied to %s", endpoint),
+        fmt.Errorf("HTTP %d", resp.StatusCode),
+    )
+}
+```
+
+**When NOT to use it:** If you're using `uhttp.BaseHttpClient` for all requests, uhttp handles wrapping automatically. Only wrap manually when bypassing uhttp.
+
+---
+
 ## Retryable vs Fatal Errors
 
 | Error Type | Retryable? | Action |

.claude/skills/connector/review-breaking-changes.md

@@ -4,6 +4,20 @@ Breaking change detection rules for connector reviews.
 
 ---
 
+## What Counts as a Breaking Change
+
+- Resource type name change
+- Entitlement slug change
+- Resource ID format change
+- Removed resource type or entitlement
+- Changed parent hierarchy
+- Changed trait type
+- **New API endpoint added to an existing sync path** — even if the code change looks additive, it may require a new scope or permission that existing installations don't have
+- **New required OAuth scope or permission** — existing installations lose functionality until reconfigured
+- Any drastic change in existing feature behavior
+
+---
+
 ## What Breaks Downstream
 
 When a connector changes, these break C1 sync:
@@ -13,6 +27,7 @@ When a connector changes, these break C1 sync:
 | Resource type name change | Existing grants orphaned | Critical |
 | Entitlement slug change | Grant matching fails | Critical |
 | Resource ID format change | Duplicate resources created | Critical |
+| New API endpoint (new scope required) | Existing installs lose data | High |
 | Removed resource type | Grants disappear | High |
 | Changed parent hierarchy | Relationships break | High |
 | Removed entitlement | Grants can't be revoked | High |
@@ -240,12 +255,17 @@ These are NOT breaking:
 
 ---
 
-## Migration Guidance
+## Process for Breaking Changes
 
-If a breaking change is necessary:
+If a breaking change is necessary, all of the following are required before merging:
 
-1. **Document the break** in PR description
-2. **Coordinate with C1 team** for sync timing
-3. **Consider dual-emit** temporarily (old + new IDs)
-4. **Plan grant re-sync** after deployment
-5. **Update any hardcoded references** in C1 config
+1. **Gate behind a config flag** — breaking behavior must be opt-in; never default-on
+2. **Lead approval required** — get explicit sign-off before merging to main
+3. **Document in the PR description** — clearly state what breaks and why
+4. **Coordinate with C1 team** for sync timing
+5. **Update `docs/connector.mdx`** to reflect new scopes, auth requirements, or behavioral changes
+6. **File a DOCS ticket** to track the doc update if not done in the same PR
+7. **Note it in the Jira issue** so it's visible to the full team
+8. **Consider dual-emit** temporarily (old + new IDs) to smooth migration
+9. **Plan grant re-sync** after deployment
+10. **Update any hardcoded references** in C1 config

.claude/skills/connector/review-checklist.md

@@ -55,6 +55,9 @@ if resp.NextPage == "" {
 return resources, resp.NextPage, nil, nil
 ```
 
+**Testing:**
+- [ ] Verified pagination works by temporarily setting `page_size=1` during development (catches off-by-one and early-termination bugs that full-page tests miss)
+
 ---
 
 ## HTTP Safety Check
@@ -156,6 +159,7 @@ Look for:
 - [ ] README shows example usage
 - [ ] Complex logic has comments explaining WHY (not what)
 - [ ] No TODO comments for critical functionality
+- [ ] `docs/connector.mdx` updated if capabilities, auth requirements, or required scopes changed
 
 ---
 

.claude/skills/connector/review-connector.md

@@ -88,7 +88,7 @@ Return a JSON array. Empty array if no issues. Only findings with confidence >=
 - R1: List methods return []*Type (pointer slices)
 - R2: No unused function parameters
 - R3: Clear variable names (groupMember not gm)
-- R4: Errors use %w (not %v), include baton-{service}: prefix, use uhttp.WrapErrors
+- R4: Errors use %w (not %v), include baton-{service}: prefix; use uhttp.WrapErrors(codes.Code, msg, err) for errors from non-uhttp HTTP calls, SDK library errors, or developer-inferred errors so the SDK can inspect the gRPC status code and decide whether to retry
 - R5: Use StaticEntitlements for uniform entitlements
 - R6: Use Skip annotations (SkipEntitlementsAndGrants, etc.) appropriately
 - R7: Missing API permissions = degrade gracefully, don't fail sync
@@ -110,7 +110,7 @@ Return a JSON array. Empty array if no issues. Only findings with confidence >=
 - H4: No error swallowing (log.Println + continue = silent data loss)
 - H5: No secrets in logs (apiKey, password, token values)
 
-## BREAKING CHANGES (B1-B8) — Check in diffs:
+## BREAKING CHANGES (B1-B9) — Check in diffs:
 - B1: Resource type Id: field changes = CRITICAL (grants orphaned)
 - B2: Entitlement slug changes in NewAssignmentEntitlement/NewPermissionEntitlement = CRITICAL
 - B3: Resource ID derivation changes (user.ID→user.Email) = CRITICAL
@@ -119,6 +119,7 @@ Return a JSON array. Empty array if no issues. Only findings with confidence >=
 - B6: Trait type changes (NewUserResource→NewAppResource) = MEDIUM
 - B7: New required OAuth scopes = breaking
 - B8: SAFE: display name changes, adding new types, adding trait options, adding pagination
+- B9: New API endpoint added to an existing resource's sync path = breaking (requires scope change or different permissions)
 
 ## TOP BUG DETECTION PATTERNS
 1. Pagination: `return resources, "", nil, nil` without conditional = stops after page 1