docs: apply loop 6 review fixes

- roles-and-acl.md: define system_admin (string value, AdminUser model, domain-hash auth, /internal/admin/ scope)
- roles-and-acl.md: clarify org.customRole is derived from primary team (no independent org-scope custom role model)
- roles-and-acl.md: add SCIM GET /Groups/:id endpoint to endpoint list
- roles-and-acl.md: add SCIM PATCH /Groups/:id RFC 7644 Operations[] format spec (add/remove member, rename)
- roles-and-acl.md: standardize group-mapping endpoints to /internal/admin/ path (resolves path conflict with api-changes-rebac.md)
- roles-and-acl.md: add first-member UOA role rule for SCIM auto-created teams (first = admin, rest = member)
- roles-and-acl.md: add soft-deprovision always retains overrides (scim_override_retention only affects hard-delete)
- roles-and-acl.md: add name collision rule for SCIM group auto-create (skip if team name exists)
- api-changes-rebac.md: clarify OrgClaim.customRole is derived convenience field, not separately stored
- api-changes-rebac.md: update customRole derivation comment in OrgClaim interface
- apps.md: add kill switch entry CRUD endpoints (POST/GET/PATCH/DELETE /org/:orgId/apps/:appId/killswitches)
- apps.md: add activatesIn response schema for future-scheduled kill switches
- feature-flags.md: add GET/POST/PATCH/DELETE response schemas for flag definition endpoints
- feature-flags.md: add GET/PUT/DELETE response schemas for per-user override endpoints with source annotation
- feature-flags.md: fix plain-member terminology in tiebreaker (not a valid enum value)
- feature-flags.md: fix flag key format decision (remove redundant leading underscore sentence)
- brief.md: add max_flags_per_app and scim_override_retention to org_features JSON, table, and Zod schema
- techstack.md + architecture-api.md: fix Express/Fastify → Fastify (Fastify is the chosen framework)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: rafiki270

Docs/Auth/architecture-api.md

@@ -127,7 +127,7 @@ For the full product spec, see [brief.md](./brief.md). For tech stack, see [tech
     /unit                     — Unit tests per service
     /integration              — API endpoint integration tests
   server.ts                   — Server entry point
-  app.ts                      — Express/Fastify app setup and middleware registration
+  app.ts                      — Fastify app setup and middleware registration
 ```
 
 ---

Docs/Requirements/apps.md

@@ -184,6 +184,22 @@ Kill switches belong to an App. A kill switch entry defines a version range and
 
 iOS apps provide `versionName` (CFBundleShortVersionString) and `buildNumber` (CFBundleVersion). Android apps provide `versionName` and `versionCode`. The kill switch entry specifies which field to compare against.
 
+### Kill switch entry management API
+
+All endpoints require org `admin` or `owner` UOA role (domain-hash auth + config JWT verification).
+
+```
+POST   /org/:orgId/apps/:appId/killswitches          — create a kill switch entry
+GET    /org/:orgId/apps/:appId/killswitches          — list all entries for an App (paginated, cursor-based)
+GET    /org/:orgId/apps/:appId/killswitches/:id      — get a single entry
+PATCH  /org/:orgId/apps/:appId/killswitches/:id      — update entry fields (all fields except id, appId, createdAt)
+DELETE /org/:orgId/apps/:appId/killswitches/:id      — delete an entry
+```
+
+`POST` body accepts all kill switch entry fields (`platform`, `type`, `versionField`, `versionValue`, `versionMax`, `versionScheme`, `name`, `titleKey`, `title`, `messageKey`, `message`, `primaryButtonKey`, `primaryButton`, `secondaryButtonKey`, `secondaryButton`, `latestVersion`, `active`, `activateAt`, `deactivateAt`, `priority`, `testUserIds`, `cacheTtl`). `platform`, `type`, `versionField`, `versionValue`, and `type` are required; all others are optional. Returns HTTP 201 on creation with the full entry.
+
+`DELETE` is idempotent — deleting a non-existent entry returns HTTP 404.
+
 ### Kill switch query API
 
 **Authentication:** This endpoint is intentionally public (no bearer token required). It identifies the app by `appIdentifier` (a registered, non-secret identifier). Optionally the SDK may attach the domain-hash bearer token for the org's domain if available, but it is not required. The `userId` param, if provided, must be a valid user ID — it is not authenticated here (used only for test mode targeting).
@@ -220,6 +236,18 @@ Response when blocked:
 }
 ```
 
+Response when a kill switch has a future `activateAt` (not yet blocking, but approaching):
+
+```json
+{
+  "status": "ok",
+  "activatesIn": 540,
+  "cacheTtl": 540
+}
+```
+
+`activatesIn` is the number of seconds until the nearest pending kill switch activates. When `activatesIn ≤ 900` (15 minutes), `cacheTtl` is capped to `activatesIn` so the SDK re-polls before activation. The kill switch entry is not present in the response until it activates.
+
 Response when clear:
 
 ```json

Docs/Requirements/feature-flags.md

@@ -45,7 +45,7 @@ When a consuming app queries a flag for a user, resolution proceeds in order and
 
 The global missing-flag default means consuming apps never get an error for an undefined flag — they always get a boolean.
 
-**Multi-team context:** A user may have different `customRole` values on different teams within the same org, producing different role flag values. The flag query must specify a team context (`teamId` param) when a user has more than one team membership. If no `teamId` is provided and the user has exactly one team membership, that team's role is used. If no `teamId` is provided and the user has multiple memberships, the tiebreaker is applied in this order: (1) highest UOA system role on that team (`owner > admin > plain-member`), (2) if equal, earliest `createdAt` on the `TeamMember` record (the team the user joined first). This tiebreaker uses the effective UOA role (including org-level inheritance).
+**Multi-team context:** A user may have different `customRole` values on different teams within the same org, producing different role flag values. The flag query must specify a team context (`teamId` param) when a user has more than one team membership. If no `teamId` is provided and the user has exactly one team membership, that team's role is used. If no `teamId` is provided and the user has multiple memberships, the tiebreaker is applied in this order: (1) highest UOA system role on that team (`owner > admin`, with users having no named UOA role ranking lowest), (2) if equal, earliest `createdAt` on the `TeamMember` record (the team the user joined first). This tiebreaker uses the effective UOA role (including org-level inheritance). Note: "no named UOA role" (plain member) is not a valid enum value — it simply means neither `owner` nor `admin` is assigned.
 
 ### Flag query API
 
@@ -174,6 +174,20 @@ PATCH  /apps/:appId/flags/definitions/:flagKey     — update a flag  (body: { d
 DELETE /apps/:appId/flags/definitions/:flagKey     — delete a flag (cascades: role assignments, user overrides)
 ```
 
+`GET` response (HTTP 200):
+```json
+[
+  { "key": "dark_mode", "description": "Dark mode UI", "defaultState": "disabled", "createdAt": "2024-01-15T10:00:00Z" },
+  { "key": "new_checkout", "description": "New checkout flow", "defaultState": "enabled", "createdAt": "2024-01-16T08:30:00Z" }
+]
+```
+
+`POST` response (HTTP 201): same shape as a single element from the `GET` response array. Returns HTTP 400 with `{ "error": "Request failed" }` if the key is invalid format, already exists, or the App's `max_flags_per_app` cap is reached.
+
+`PATCH` response (HTTP 200): updated flag object. `PATCH` with an empty body `{}` returns HTTP 400. Unknown fields in body return HTTP 400.
+
+`DELETE` response: HTTP 204 (no body).
+
 ### Role matrix API endpoints
 
 ```
@@ -192,6 +206,21 @@ DELETE /apps/:appId/flags/overrides/:userId/:flagKey  — remove a specific over
 DELETE /apps/:appId/flags/overrides/:userId        — remove all overrides for a user
 ```
 
+`GET` response (HTTP 200):
+```json
+{
+  "dark_mode": { "value": true, "source": "override" },
+  "new_checkout": { "value": false, "source": "role" },
+  "beta_access": { "value": false, "source": "default" }
+}
+```
+
+Source values: `"override"` (explicit per-user assignment), `"role"` (from role matrix), `"default"` (flag's `defaultState`). An unknown `userId` or a `userId` not belonging to this org's App returns HTTP 200 with `{}` (no overrides, no information leak).
+
+`PUT` response (HTTP 200): the updated resolved flag map for the user, same shape as above.
+
+`DELETE` (single flag) response: HTTP 204. `DELETE` (all overrides) response: HTTP 204.
+
 ### Feature flags service enablement
 
 Feature flags are enabled per **App** (not per-org globally). Two fields control availability:
@@ -207,7 +236,7 @@ Feature flags are enabled per **App** (not per-org globally). Two fields control
 
 ## Resolved decisions
 
-1. **Flag key format** — **decided: lowercase letters, digits, and underscores only; must start with a letter** (`[a-z][a-z0-9_]*`). Examples: `dark_mode`, `can_publish`, `beta_access`. Enforced at creation. Validation rejects any other format with a 400 error. This applies to all flags across all Apps. Leading underscores are not allowed.
+1. **Flag key format** — **decided: must start with a lowercase letter, followed by lowercase letters, digits, or underscores** (regex: `[a-z][a-z0-9_]*`). Examples: `dark_mode`, `can_publish`, `beta_access`. Enforced at creation. Validation rejects any other format with HTTP 400. This applies to all flags across all Apps.
 2. **Token flag inclusion** — **decided: all flags for the App are included in the token at login time**, regardless of whether they differ from the default. This keeps token consumption simple (no server-side re-resolution needed on read). Orgs with many flags should use `max_flags_per_app` config to cap token size (default 100; see `org_features` in brief.md).
 3. **Real-time flag changes** — **decided: poll only**. The token embeds flag state at login. Mid-session changes are visible only via `/apps/:appId/flags` query endpoint calls. The SDK polls on foreground resume (default interval: 5 minutes, minimum 60 seconds, configurable per App). No push mechanism.
 4. **SCIM flag sync / override retention** — **decided: soft-deprovision by default**. When a SCIM user is deprovisioned (`active: false`), their per-user flag overrides are **retained** and are re-linked when the user is re-provisioned (matched by email or SCIM `externalId`). Overrides are only deleted when a user is hard-deleted (`DELETE /scim/v2/Users/:id` with `?hardDelete=true` query param, or when the org is deleted). This is the default; orgs can configure `scim_override_retention: "retain" | "clear"` in their `org_features`.

Docs/Requirements/roles-and-acl.md

@@ -15,7 +15,7 @@ These control who can administer the UOA backend itself — the org and team str
 
 Users who are neither `owner` nor `admin` have no named UOA system role — they are plain members whose significance is defined entirely by their custom role.
 
-`system_admin` is a separate global role for UOA's own admin panel operators and is not visible to org/team users.
+`system_admin` is a separate global role for UOA's own admin panel operators and is not visible to org/team users. It is stored as the string value `"system_admin"` on the internal `AdminUser` model (separate from `OrgMember`/`TeamMember`). System admin identity is verified via domain-hash auth against the admin domain + the UOA `SHARED_SECRET` (same mechanism as other internal routes). Endpoints under `/internal/admin/` require system admin auth and bypass all org/team permission middleware.
 
 ### 2. Consumer-defined roles (external, custom)
 
@@ -140,10 +140,10 @@ On rename: existing `TeamMember.customRole` records with the old name are update
 - `method` — the authentication method used: `"email"`, `"google"`, `"github"`, `"microsoft"`
 - `uoaRole` — `owner`, `admin`, or omitted if neither (plain member has no named UOA role)
 - `uoaRoleInherited` — `true` if derived from org-level role rather than explicit team assignment; omitted if `false`
-- `customRole` (org level) — the consuming app's role label for this user at the org level. Since org-level custom roles are independent of team roles, this reflects any role explicitly set at the org scope. Omitted if none assigned at org level.
+- `customRole` (org level) — a convenience field. Derived from the user's primary team `customRole` using the same tiebreaker as flag resolution (highest UOA system role → earliest `TeamMember.createdAt`). There is no separately stored org-level custom role — this field is computed, not read from a separate org-scope data model. Omitted if no team has a `customRole` set for this user.
 - `customRole` (team level) — the consuming app's single role label for this user on this specific team membership. Omitted if no custom role is assigned on that team.
 
-**`org.customRole` when the user has multiple team memberships:** The org-level `customRole` is set explicitly (not derived from team roles). If the user has no explicit org-level custom role, `org.customRole` is omitted. Team-level `customRole` values are always per-team in the `teams[]` array and are never aggregated to the org level. See decision in the role model section below.
+**`org.customRole` when the user has multiple team memberships:** Always derived from the primary team's `customRole` using the standard multi-team tiebreaker. It is never independently set or stored at org scope. Custom roles are team-only constructs.
 
 ---
 
@@ -220,14 +220,15 @@ GET    /scim/v2/Users/:id      — read user
 PATCH  /scim/v2/Users/:id      — update user attributes / active status
 DELETE /scim/v2/Users/:id      — deprovision user (see deprovisioning behavior below)
 GET    /scim/v2/Groups         — list groups/teams (paginated, cursor-based)
+GET    /scim/v2/Groups/:id     — read a single group/team
 POST   /scim/v2/Groups         — create team via IdP
 PATCH  /scim/v2/Groups/:id     — add/remove members, rename team
 DELETE /scim/v2/Groups/:id     — delete team
 ```
 
 **SCIM bearer token:** An opaque UUID token issued per org via the admin panel. It has no expiry by default (long-lived). A single org may have multiple active tokens (for rolling rotation or multiple IdP integrations). Tokens are stored hashed; plain value shown only at creation. Revoked via admin panel (`DELETE /internal/admin/orgs/:orgId/scim-tokens/:tokenId`). Scoped to a single org — cannot be used across orgs.
 
-**Group → team mapping:** SCIM Groups map to UOA teams. Mapping is stored explicitly: a `ScimGroupMapping` record links an IdP `externalGroupId` to a UOA `teamId`. Endpoints for managing mappings: `GET/POST/DELETE /org/:orgId/scim/group-mappings`. If a SCIM Group arrives with no mapping, UOA auto-creates a new team with the group `displayName` as the team name, and creates a mapping automatically. Deleting a mapping does not delete the team — only severs the auto-sync link.
+**Group → team mapping:** SCIM Groups map to UOA teams. Mapping is stored explicitly: a `ScimGroupMapping` record links an IdP `externalGroupId` to a UOA `teamId`. Endpoints for managing mappings (system admin auth required): `GET/POST/DELETE /internal/admin/orgs/:orgId/scim/group-mappings` (see also `api-changes-rebac.md §6`). If a SCIM Group arrives with no mapping, UOA auto-creates a new team with the group `displayName` as the team name (if a team with that name already exists in the org, auto-creation is skipped and the SCIM operation continues without team assignment for that group), and creates a mapping automatically. When a SCIM group auto-creates a team, the first member added in the provisioning request receives `admin` UOA team role; all subsequent members receive `member`. Deleting a mapping does not delete the team — only severs the auto-sync link.
 
 **User attribute mapping:**
 - `userName` → UOA `email` (UPN format like `alice@ford.com`)
@@ -289,8 +290,18 @@ SCIM endpoints are authenticated with the per-org SCIM bearer token (see above).
 
 **SCIM `GET /scim/v2/Users` pagination:** Uses SCIM standard `startIndex` (1-based, default 1) and `count` (page size, default 100, max 200) params. Supports `filter=userName eq "alice@acme.com"` and `filter=externalId eq "<idp-id>"` per RFC 7644 §3.4.2.2. Response includes `totalResults`, `startIndex`, `itemsPerPage`, and a `Resources` array of User objects.
 
+**SCIM `GET /scim/v2/Groups/:id` response:** Returns a SCIM Group object including `id`, `displayName`, `externalId` (IdP group ID), and a `members[]` array of `{ "value": "<scimUserId>", "display": "<userName>" }` objects for current team members.
+
+**SCIM `PATCH /scim/v2/Groups/:id` format:** Uses RFC 7644 §3.5.2 `Operations[]` array format. Three supported operations:
+- Add member: `{ "op": "Add", "path": "members", "value": [{"value": "<userId>"}] }`
+- Remove member: `{ "op": "Remove", "path": "members[value eq \"<userId>\"]" }`
+- Rename team: `{ "op": "Replace", "path": "displayName", "value": "New Team Name" }`
+Multiple operations may appear in a single PATCH body. Operations are applied atomically. Team rename via SCIM is authoritative — if a UOA admin renamed the team, the next SCIM PATCH with a `displayName` replace will overwrite it.
+
 **SCIM `GET /scim/v2/Groups` pagination:** Uses SCIM standard `startIndex` (1-based, default 1) and `count` (page size, default 100, max 200) params. Supports `filter=displayName eq "Engineering"` per RFC 7644 §3.4.2.2. Response includes `totalResults`, `startIndex`, `itemsPerPage`.
 
+**Override retention on soft-deprovision:** Per-user flag overrides are **always retained** on soft-deprovision (`PATCH { active: false }` or `DELETE` without `?hardDelete=true`), regardless of the `scim_override_retention` org config. The `scim_override_retention` config only controls what happens on hard-delete (`DELETE?hardDelete=true`).
+
 **SCIM bearer token management endpoints** (system admin auth required):
 ```
 GET    /internal/admin/orgs/:orgId/scim-tokens          — list all tokens (id, label, createdAt, lastUsedAt; plain token never returned after creation)

Docs/Research/api-changes-rebac.md

@@ -315,7 +315,7 @@ interface OrgClaim {
   id: string;
   slug: string;
   uoaRole?: 'owner' | 'admin';         // omitted if plain member
-  customRole?: string;                  // consuming app's role label; omitted if none
+  customRole?: string;                  // the customRole from the user's primary team (tiebreaker: highest UOA system role → earliest TeamMember.createdAt); omitted if no team customRole is set. This is a convenience field derived from the teams[] array — it is NOT a separately stored org-level role. There is no org-scoped custom role data model.
   teams: TeamClaim[];
 }
 

Docs/brief.md

@@ -581,7 +581,9 @@ The claim is optional and defaults to disabled. The object shape and defaults ar
   "max_members_per_team": 200,
   "max_members_per_group": 500,
   "max_team_memberships_per_user": 50,
-  "org_roles": ["owner", "admin", "member"]
+  "org_roles": ["owner", "admin", "member"],
+  "max_flags_per_app": 100,
+  "scim_override_retention": "retain"
 }
 ```
 
@@ -597,6 +599,8 @@ The claim is optional and defaults to disabled. The object shape and defaults ar
 | `max_members_per_group` | integer | `500` | Maximum members per group (max 5000) |
 | `max_team_memberships_per_user` | integer | `50` | Maximum teams a single user can belong to — also caps JWT size (max 200) |
 | `org_roles` | string[] | `["owner", "admin", "member"]` | Allowed org-level roles. Must always contain `"owner"`. |
+| `max_flags_per_app` | integer | `100` | Maximum feature flag definitions per App (max 500). Enforced at creation; existing flags unaffected if cap is lowered. |
+| `scim_override_retention` | `"retain"` \| `"clear"` | `"retain"` | Controls per-user flag override retention on SCIM hard-delete (`DELETE /scim/v2/Users/:id?hardDelete=true`). `"retain"` keeps overrides; `"clear"` deletes them. Soft-deprovision always retains overrides regardless of this setting. |
 
 * `enabled = false` (or omitted): all `/org/*` and `/internal/org/*` endpoints return `404`, access tokens omit `org` claims.
 * `groups_enabled = false`: group read/write paths return `404`.
@@ -620,12 +624,15 @@ org_features: z.object({
     (roles) => roles.includes('owner'),
     { message: 'org_roles must include "owner"' }
   ).default(['owner', 'admin', 'member']),
+  max_flags_per_app: z.number().int().positive().max(500).default(100),
+  scim_override_retention: z.enum(['retain', 'clear']).default('retain'),
 }).optional().default({
   enabled: false, groups_enabled: false, user_needs_team: false,
   max_teams_per_org: 100, max_groups_per_org: 20,
   max_members_per_org: 1000, max_members_per_team: 200,
   max_members_per_group: 500, max_team_memberships_per_user: 50,
   org_roles: ['owner', 'admin', 'member'],
+  max_flags_per_app: 100, scim_override_retention: 'retain',
 })
 ```
 

Docs/techstack.md

@@ -30,7 +30,7 @@ The API is the central OAuth/auth server. It handles:
 
 ```
 /API
-  /routes          — Express/Fastify route handlers
+  /routes          — Fastify route handlers
   /routes/org      — User-facing org/team routes
   /routes/internal/org — Internal org-team-group admin routes
   /middleware       — Auth, config verification, error handling