Review: Doc: Auth architecture on project page

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- plan-wkq Phase 11
• [x] Repo -- forgejo_admin/basketball-api (docs only)
• [x] User Story -- platform operator wants auth architecture documented
• [x] Context -- explains hours lost rebuilding what Keycloak provides
• [x] File Targets -- pal-e-docs note project-westside-basketball
• [x] Acceptance Criteria -- 4 items
• [x] Test Expectations -- get_section check
• [x] Constraints -- pal-e-docs update only
• [x] Checklist -- present
• [x] Related -- references #132 and #144

Traceability

• [ ] story:WS-S1 label -- MISMATCH. WS-S1 is "As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable." This ticket documents auth architecture, not IaC. Better: story:WS-S3 (manage Keycloak realms) or story:WS-S12 (manage user accounts/reset passwords), or remove story label (foundational doc work).
• [x] arch:auth label -- present on board item. Maps to existing arch-auth-westside-basketball note.
• [x] Forgejo issue -- basketball-api #145, open

File Targets

• [ ] project-westside-basketball "add Auth Architecture section" -- WRONG TARGET. The project page Architecture section (block #12304) already links to a dedicated arch-auth-westside-basketball note with 8 subsections (Identity Provider, Roles, Two Auth Patterns, Keycloak Clients, Account Creation, API Auth, Token Flow, Related). The ticket should target updating arch-auth-westside-basketball with new subsections for: (a) auth management paths, (b) the Gmail OAuth decision. The project page needs no changes.

Repo Placement

Dependencies

• #132 (Password reset via Gmail OAuth) -- closed. Source for Gmail OAuth decision to document.
• #144 (Marcus admin access + account console links) -- closed. Source for account/admin console paths.
• #267 (Marcus admin + player self-service) -- done on board. Related auth management work.
• No blocking items. No items blocked by this ticket.

Acceptance Criteria

• "Auth Architecture section added to project-westside-basketball" -- MISLEADING. Section already exists as linked arch note. Rewrite to: "Auth management paths subsection added to arch-auth-westside-basketball"
• "Three auth paths documented (self-service reset, account console, admin console)" -- VALID. These are genuinely missing from the existing arch note. Testable.
• "Key URLs and roles documented" -- PARTIALLY DONE. Roles table and Keycloak URL exist. Missing: account console URL, admin console URL. Sharpen to list specific missing URLs.
• "Key decision recorded: all email = Gmail OAuth, custom forgot-password bypasses Keycloak SMTP" -- VALID. Not yet documented in arch note. Testable.
• Test expectation get_section(slug="project-westside-basketball", anchor_id="auth-architecture") -- WRONG SLUG. Should target arch-auth-westside-basketball with anchor for the new subsection (e.g., auth-management-paths).

Blast Radius

Decomposition

Recommendation

• [BODY] Fix file target: Change from "add Auth Architecture section to project-westside-basketball" to "add Auth Management Paths and Key Decisions subsections to existing arch-auth-westside-basketball note." The project page already links to this arch note.
• [LABEL] Fix story label: Change story:WS-S1 to story:WS-S3 (Keycloak realm management) or story:WS-S12 (user account management) on the board item.
• [BODY] Fix test expectation: Change get_section(slug="project-westside-basketball", anchor_id="auth-architecture") to get_section(slug="arch-auth-westside-basketball", anchor_id="auth-management-paths").