Docs web SCREENS.md

Web (PWA) — Screen Specs

All 75 screens with the native Web (PWA) container and controls for each element. Behavior, data and copy are identical to shared/SCREEN-SPECS.md; construction rules for this platform are in PLATFORM-SPEC.md.

Container per archetype

Archetype	Container
auth	Standalone route outside the app shell, centered card ≥ 768 px, full-bleed on phone
grid	Main pane, CSS grid (auto-fill minmax 160px)
list	List pane (resizable) + detail pane ≥ 768 px; single pane < 768 px
table	Virtualized grid table ≥ 1024 px; card rows below
detail	Detail pane with header, tablist, toolbar; full page < 768 px
tab	`tabpanel` (route segment)
form	Modal `<dialog>` ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px
settings	Grouped settings rows in main pane
confirm	`<dialog role=alertdialog>`; bottom sheet < 768 px
secret	Modal `<dialog>`, `cancel` prevented, no Esc
wizard	Dialog/sheet with step indicator; each step a URL hash
popover	Popover ≥ 1024 px; side panel 768–1023; bottom sheet < 768
handoff	`window.open` (new tab) / same-tab redirect for PKCE
overlay	Top-layer `<dialog>` / popover
hub	Bottom-nav destination list < 768 px

Domain: D1 Sign-in & Identity · Route: /sign-in · Archetype: auth · Phase: MVP
Who: Unauthenticated
Purpose: Exchange email + password for a session, or start an MFA challenge.

Web (PWA) container: Standalone route outside the app shell, centered card ≥ 768 px, full-bleed on phone

Entry points: App launch with no stored session; Session expired / revoked (preserves ?next= destination); Sign out

Element	Kind	Web (PWA) control	Data / API	Rules
Email	email-field		body.email	required; RFC 5322; trim; autofill username
Password	password-field	+ reveal	body.password	required; reveal toggle; autofill current-password
Sign in	primary-button		POST /auth/login	disabled until both fields non-empty
Forgot password?	link	/	→ AUTH-05
Create an account	link	/	→ AUTH-03
Continue with SSO	button		POST /auth/sso/{provider}/callback	hidden behind flag `sso` (API returns 501 today)
Sign in with a passkey	button		—	hidden behind flag `passkeys`; reserved for when the API supports WebAuthn

Action	Call	Result handling
Sign in	`POST /auth/login`	200 AuthSession → store tokens → go to `next` or APP-01. 200 MfaChallenge → AUTH-02 with mfa_token.
—		401 → inline form error "Email or password is incorrect." (never reveal which). 403 → account suspended/locked message. 429 → disable button, countdown from Retry-After.

States: Submitting: button spinner, fields read-only; Locked out (5 failures / 15 min): explain wait time

Notes: test_mode is never exposed in end-user UI; developer builds may show a hidden toggle (long-press logo / ⌥-click) for test-mode sign-in. The horizontal logo lockup (BrandLockup, brand/BRAND.md) sits above the form.

AUTH-02 — Two-factor challenge

Domain: D1 Sign-in & Identity · Route: /sign-in/mfa · Archetype: auth · Phase: MVP
Who: Holder of mfa_token
Purpose: Complete sign-in with a TOTP code or a recovery code.

Web (PWA) container: Standalone route outside the app shell, centered card ≥ 768 px, full-bleed on phone

Entry points: AUTH-01 returned MfaChallenge

Element	Kind	Web (PWA) control	Data / API	Rules
Code	otp-field		body.code	6 digits; paste fills all; auto-submit on 6th digit; OS one-time-code autofill
Use a recovery code	link	/	swaps to Recovery code field	only if `methods` includes recovery_code
Recovery code	text-field		body.recovery_code	format xxxx-xxxx; case-insensitive
Expiry countdown	caption		MfaChallenge.expires_in	announce at 60 s and 10 s
Verify	primary-button		POST /auth/mfa/verify

Action	Call	Result handling
Verify	`POST /auth/mfa/verify`	200 → same as AUTH-01 success. 401 → "That code didn't work." clear field. Expired → back to AUTH-01 with message. 429 → countdown.

States: Challenge expired

AUTH-03 — Create account

Domain: D1 Sign-in & Identity · Route: /sign-up · Archetype: auth · Phase: MVP
Who: Unauthenticated
Purpose: Self-service signup with email and password.

Web (PWA) container: Standalone route outside the app shell, centered card ≥ 768 px, full-bleed on phone

Entry points: AUTH-01 link; Marketing/app deep link with optional application_id

Element	Kind	Web (PWA) control	Data / API	Rules
Display name	text-field		body.display_name	optional; ≤ 100
Email	email-field		body.email	required
Password	password-field	+ reveal	body.password	required; strength meter; autofill new-password; show policy hint
Create account	primary-button		POST /auth/signup
Terms / Privacy	links		external

Action	Call	Result handling
Create account	`POST /auth/signup`	201 AuthSession → AUTH-04 (verify pending) then APP-01. 409 email_taken → "An account with this email may already exist. Sign in or reset your password." (with details.reason invitation_pending the API re-sends the invitation: say "Check your email for your invitation.") 422 → field errors.

Notes: Pass application_id through when signup started from an app's link; it is recorded as signup_application_id. Every new User starts on the Free plan and receives platform-managed free Entitlements to every free Application, including the Hub itself (app_hub). No plan choice at signup; upgrading is BIL-01.

AUTH-04 — Verify your email

Domain: D1 Sign-in & Identity · Route: /verify-email · Archetype: auth · Phase: MVP
Who: Signed in (unverified) or token holder
Purpose: Tell the user to check email; complete verification from the emailed link.

Web (PWA) container: Standalone route outside the app shell, centered card ≥ 768 px, full-bleed on phone

Entry points: After signup; Persistent banner on APP-01 while email_verified is false; Deep link /verify-email?token=…

Element	Kind	Web (PWA) control	Data / API	Rules
Instruction	text		User.email	"We sent a link to {email}."
Resend email	button		POST /auth/email/verify/resend	30 s cooldown after each send
Continue to Substratal	button		→ APP-01	unverified users may continue
Change email	link	/	→ ACC-02

Action	Call	Result handling
Deep link opened	`POST /auth/email/verify {token}`	204 → success state, refresh User. 400 → "This link has expired." + Resend.
Resend email	`POST /auth/email/verify/resend`	Always 202 → toast "If that address needs verifying, we sent a new link."

AUTH-05 — Forgot password

Domain: D1 Sign-in & Identity · Route: /forgot-password · Archetype: auth · Phase: MVP
Who: Unauthenticated
Purpose: Request a password-reset email.

Web (PWA) container: Standalone route outside the app shell, centered card ≥ 768 px, full-bleed on phone

Element	Kind	Web (PWA) control	Data / API	Rules
Email	email-field		body.email	prefilled from AUTH-01
Send reset link	primary-button		POST /auth/password/forgot

Action	Call	Result handling
Send reset link	`POST /auth/password/forgot`	Always 202 → confirmation "If an account exists for {email}, we sent a reset link." 429 → countdown.

AUTH-06 — Set a new password

Domain: D1 Sign-in & Identity · Route: /reset-password · Archetype: auth · Phase: MVP
Who: Reset-token holder
Purpose: Choose a new password from the emailed reset link.

Web (PWA) container: Standalone route outside the app shell, centered card ≥ 768 px, full-bleed on phone

Entry points: Deep link /reset-password?token=…

Element	Kind	Web (PWA) control	Data / API	Rules
New password	password-field	+ reveal	body.new_password	strength meter; autofill new-password
Confirm password	password-field	+ reveal	client only	must match
Notice	caption			"You'll be signed out on all devices."
Save password	primary-button		POST /auth/password/reset

Action	Call	Result handling
Save password	`POST /auth/password/reset`	204 → clear local session → AUTH-01 with success banner. 400 → expired link + link to AUTH-05. 422 → field errors.

AUTH-07 — Accept invitation

Domain: D1 Sign-in & Identity · Route: /invite · Archetype: auth · Phase: MVP
Who: Invitation-token holder
Purpose: Activate an account an admin created: set password and sign in.

Web (PWA) container: Standalone route outside the app shell, centered card ≥ 768 px, full-bleed on phone

Entry points: Deep link /invite?token=… from the invitation email

Element	Kind	Web (PWA) control	Data / API	Rules
Display name	text-field		body.display_name	optional
Password	password-field	+ reveal	body.password	strength meter
Accept and continue	primary-button		POST /auth/invitations/accept

Action	Call	Result handling
Accept and continue	`POST /auth/invitations/accept`	200 AuthSession → APP-01. 400 → "This invitation is no longer valid. Ask your admin to resend it."

D2 · Account & Security

ACC-01 — Account & profile

Domain: D2 Account & Security · Route: /account · Archetype: settings · Phase: MVP
Who: Self
Purpose: View and edit the signed-in user's global profile.

Web (PWA) container: Grouped settings rows in main pane

Loads: GET /users/me · GET /users/me/profile

Element	Kind	Web (PWA) control	Data / API	Rules
Avatar	image-picker	+ paste + drop	Profile.avatar_url	camera / photo library / file / paste; client uploads to app asset storage then PATCHes URL*
Display name	text-field		Profile.display_name	required; ≤ 100; save on blur/Return
Email	row → ACC-02	row link	User.email + email_verified + pending_email	shows "Pending: {pending_email}" when set
User ID	id-chip	`+ copy button`	User.id	copy
Contact email	email-field		Profile.contact_email	optional
Contact phone	phone-field		Profile.contact_phone	optional; E.164 formatting by locale
Plan	row → BIL-01	row link	User.plan free\|standard + plan_sources	"Free" or "Standard · via {org}" / "Standard · your subscription"
Member since / last sign-in	caption		User.created_at, last_login_at	locale formatted
Sign out	button		POST /auth/logout	always visible at the bottom of Account (mobile) / account menu (desktop)

Action	Call	Result handling
Edit field	`PATCH /users/me/profile (If-Match)`	Save per field; 409 version_conflict → reload prompt; 422 → field error.
Sign out	`POST /auth/logout`	best effort; always wipe local credentials and cache → AUTH-01

States: Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES

Notes: *The API stores avatar_url only. Upload target is a client-side decision (spec gap — see OPEN-QUESTIONS).

ACC-02 — Change email

Domain: D2 Account & Security · Route: /account/email · Archetype: form · Phase: MVP
Who: Self
Purpose: Start an email change; the new address must be verified.

Web (PWA) container: Modal <dialog> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px

Element	Kind	Web (PWA) control	Data / API	Rules
New email	email-field		body.email	required; differs from current
Save	primary-button		PATCH /users/me

Action	Call	Result handling
Save	`PATCH /users/me {email}`	200 → User.pending_email set; show AUTH-04-style "check your new inbox". 409 not_unique → "That email is already in use."

ACC-03 — Change password

Domain: D2 Account & Security · Route: /account/security/password · Archetype: form · Phase: MVP
Who: Self
Purpose: Change password knowing the current one.

Web (PWA) container: Modal <dialog> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px

Element	Kind	Web (PWA) control	Data / API	Rules
Current password	password-field	+ reveal	body.current_password	autofill current-password
New password	password-field	+ reveal	body.new_password	strength meter; autofill new-password
Save	primary-button		POST /users/me/password

Action	Call	Result handling
Save	`POST /users/me/password`	204 → toast "Password changed". 401 → "Current password is incorrect." 422 → policy errors.

ACC-04 — Security

Domain: D2 Account & Security · Route: /account/security · Archetype: settings · Phase: MVP
Who: Self
Purpose: Password, two-factor and active sessions in one place.

Web (PWA) container: Grouped settings rows in main pane

Loads: GET /users/me · GET /users/me/sessions

Element	Kind	Web (PWA) control	Data / API	Rules
Password	row → ACC-03	row link		"Change…"
Two-factor authentication	toggle		User.mfa_enabled	on → ACC-05; off → ACC-06
Sessions	list	virtualized list	Session[]: user_agent → device name/icon, ip_address → approximate location*, last_seen_at, current	current session marked "This device" and not revocable here
Sign out	row-button	trailing button	DELETE /users/me/sessions/{sessionId}	per non-current row
Sign out of all other sessions	destructive-button		DELETE /users/me/sessions/{sessionId} for each non-current session	confirm first; also stops push to those sessions' devices
Devices & notifications	row → NTF-03	row link	count of active devices

Action	Call	Result handling
Revoke one	`DELETE /users/me/sessions/{sessionId}`	Optimistic remove; 404 → already gone, refresh.
Sign out everywhere else	`DELETE each non-current session`	Confirm first (COPY). Uses per-session deletes so the current session survives; `logout all_sessions` signs this device out too. Revoking a session deactivates the push devices it registered.

States: Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES

Notes: *IP → city lookup is client-side/optional; never show the raw IP to non-staff unless the user expands details.

ACC-05 — Turn on two-factor

Domain: D2 Account & Security · Route: /account/security/2fa/enable · Archetype: wizard · Phase: MVP
Who: Self
Purpose: Enroll an authenticator app (TOTP) and save recovery codes.

Web (PWA) container: Dialog/sheet with step indicator; each step a URL hash

Element	Kind	Web (PWA) control	Data / API	Rules
Step 1 — Scan	qr + secret		POST /users/me/mfa/totp → otpauth_uri, secret	QR, "Copy setup key", "Open in authenticator" (otpauth:// link on mobile)
Step 2 — Confirm	otp-field		body.code	6 digits
Step 3 — Recovery codes	secret-list	SecretReveal + download/print/share	confirm response: 10 recovery codes	Copy all · Save as file · Print · Share (mobile); "I've saved these" checkbox gates Done

Action	Call	Result handling
Start	`POST /users/me/mfa/totp`	409 → already enabled; close.
Confirm	`POST /users/me/mfa/totp/confirm`	200 → step 3. 401 → wrong code.

States: Cancel before confirm leaves MFA off (no server cleanup needed)

ACC-06 — Turn off two-factor

Domain: D2 Account & Security · Route: /account/security/2fa/disable · Archetype: confirm · Phase: MVP
Who: Self
Purpose: Disable TOTP with a current code or a recovery code.

Web (PWA) container: <dialog role=alertdialog>; bottom sheet < 768 px

Element	Kind	Web (PWA) control	Data / API	Rules
Code or recovery code	otp-field / text-field		body.code \| body.recovery_code
Turn off	destructive-button		POST /users/me/mfa/totp/disable

Action	Call	Result handling
Turn off	`POST /users/me/mfa/totp/disable`	204 → toggle off, toast. 401 → wrong code. 429 → countdown.

ACC-07 — Privacy

Domain: D2 Account & Security · Route: /account/privacy · Archetype: settings · Phase: MVP
Who: Self
Purpose: Export personal data and delete the account.

Web (PWA) container: Grouped settings rows in main pane

Element	Kind	Web (PWA) control	Data / API	Rules
Download my data	button		GET /users/me/export	saves `substratal-export-{date}.json` via save dialog / share sheet / download
Delete account	destructive-row → ACC-08	row button (destructive)

Action	Call	Result handling
Download	`GET /users/me/export`	200 → save file. 429 → "You can export again in {n} minutes."

ACC-08 — Delete account

Domain: D2 Account & Security · Route: /account/privacy/delete · Archetype: confirm · Phase: MVP
Who: Self
Purpose: Request erasure: deactivate now, erase after 7 days.

Web (PWA) container: <dialog role=alertdialog>; bottom sheet < 768 px

Element	Kind	Web (PWA) control	Data / API	Rules
What happens	text			list: signed out everywhere; apps lose access; erased on {date}; support can cancel within 7 days
Reason	text-area	</td> <td>body.reason</td> <td>optional</td> </tr> <tr> <td>Type DELETE</td> <td>text-field</td> <td><input type=text></td> <td>client only</td> <td>must equal localized confirm word</td> </tr> <tr> <td>Delete account</td> <td>destructive-button</td> <td><button class=destructive></td> <td>POST /users/me/erasure-requests</td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Delete account</td> <td><code>POST /users/me/erasure-requests</code></td> <td>202 ErasureRequest → clear local data → AUTH-01 with "Your account is scheduled for deletion on {scheduled_for}."</td> </tr> </tbody></table></div> <p><strong>Notes:</strong> If the User has an individual Standard subscription, warn first and link to "Manage billing" (BIL-03) — erasure doesn't cancel Stripe billing by itself (see OPEN-QUESTIONS).</p> <h2 id="d3--my-apps"><a class="anchor" href="#d3--my-apps" aria-hidden="true" tabindex="-1">#</a>D3 · My Apps</h2> <h3 id="app-01--home--my-apps"><a class="anchor" href="#app-01--home--my-apps" aria-hidden="true" tabindex="-1">#</a>APP-01 — Home — My Apps</h3> <p><strong>Domain:</strong> D3 My Apps · <strong>Route:</strong> <code>/</code> · <strong>Archetype:</strong> grid · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Signed in<br><strong>Purpose:</strong> See every app you can use, its access status, and launch it.</p> <p><strong>Web (PWA) container:</strong> Main pane, CSS grid (auto-fill minmax 160px)</p> <p><strong>Loads:</strong> <code>GET /applications (catalog the caller can see; each has access_tier free\|standard)</code> · <code>GET /users/me/entitlements?include_inactive=true</code> · <code>GET /users/me (plan, plan_sources)</code> · <code>GET /organizations?status=active (for pending invites)</code> · <code>GET /users/me/notifications/unread-count (bell badge)</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Search</td> <td>search</td> <td><input type=search role=searchbox></td> <td>client filter on name/description</td> <td></td> </tr> <tr> <td>Grid / List</td> <td>segmented</td> <td>role=radiogroup segmented buttons</td> <td>client preference</td> <td>persisted locally</td> </tr> <tr> <td>Invitation banner</td> <td>banner</td> <td>role=region banner</td> <td>Organization.my_membership_status = pending</td> <td>"{org} invited you…" → ORG-09</td> </tr> <tr> <td>Verify-email banner</td> <td>banner</td> <td>role=region banner</td> <td>User.email_verified = false</td> <td>→ AUTH-04</td> </tr> <tr> <td>Your apps</td> <td>tile-grid</td> <td>CSS grid of tiles (role=list)</td> <td>join Application × resolved entitlement per app</td> <td>tile = icon, name, StatusBadge, helper text (COPY); order: recently launched, then A–Z; pin to top (local)</td> </tr> <tr> <td>Included with Standard</td> <td>tile-grid</td> <td>CSS grid of tiles (role=list)</td> <td>standard apps with status none while User.plan = free</td> <td>badge "Standard"; tap → upsell sheet → BIL-01 ("Get every app for $6/month")</td> </tr> <tr> <td>Available</td> <td>tile-grid</td> <td>CSS grid of tiles (role=list)</td> <td>other public apps with status none</td> <td>"Get access" → app support/launch page</td> </tr> <tr> <td>Inbox bell</td> <td>toolbar button + count</td> <td>toolbar (role=toolbar)</td> <td>NotificationUnreadCount.unread_count</td> <td>→ NTF-01</td> </tr> <tr> <td>Past apps</td> <td>row → APP-05</td> <td>row link</td> <td>count of revoked/expired</td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Open tile (active)</td> <td><code>→ APP-03</code></td> <td>Launch</td> </tr> <tr> <td>Open tile (other status)</td> <td><code>→ APP-02</code></td> <td>Explain status</td> </tr> <tr> <td>Context menu / long-press</td> <td></td> <td>Open · App settings (SET-02) · App profile (APP-04) · Pin · Copy app ID</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES; Empty: "No apps yet" (COPY); Offline: show cached grid read-only, launch disabled</p> <p><strong>Notes:</strong> Resolved status per app: if any path active → Active; else precedence scheduled > disabled > expired > revoked > none (matches the API's resolved_entitlement_status). Use <code>GET /users/me/apps/{appId}/effective-permissions</code> for the authoritative answer when the user opens APP-02. Tile helper text by source of the active path: <code>free</code> → "Free"; <code>subscription</code> → "Standard" (or "Standard · via {org}"); developer grants as before. The Hub itself (<code>app_hub</code>) is hidden from the grid.</p> <h3 id="app-02--app-info"><a class="anchor" href="#app-02--app-info" aria-hidden="true" tabindex="-1">#</a>APP-02 — App info</h3> <p><strong>Domain:</strong> D3 My Apps · <strong>Route:</strong> <code>/apps/:appId</code> · <strong>Archetype:</strong> popover · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Signed in<br><strong>Purpose:</strong> Explain an app's access status and how the user has access.</p> <p><strong>Web (PWA) container:</strong> Popover ≥ 1024 px; side panel 768–1023; bottom sheet < 768</p> <p><strong>Loads:</strong> <code>GET /applications/{appId}</code> · <code>GET /users/me/apps/{appId}/effective-permissions</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Header</td> <td>icon + name + StatusBadge</td> <td>img + heading + badge</td> <td>Application, EffectivePermissions.entitlement_status</td> <td></td> </tr> <tr> <td>Description</td> <td>text</td> <td><p></td> <td>Application.description</td> <td></td> </tr> <tr> <td>Access paths</td> <td>list</td> <td>virtualized list</td> <td>EffectivePermissions.access_paths[]: source, status, organization_id, member_decision</td> <td>"Free", "Standard · your subscription", "Standard · via Northwind", "Personal · Granted by admin", "Via Northwind (seat)"; member_decision excluded explained</td> </tr> <tr> <td>Tier</td> <td>badge</td> <td>StatusBadge pill</td> <td>Application.access_tier</td> <td>"Free" or "Standard"</td> </tr> <tr> <td>Your roles</td> <td>chips</td> <td>toggle-button chip row</td> <td>EffectivePermissions.roles</td> <td>Phase 2</td> </tr> <tr> <td>Primary action</td> <td>button</td> <td><button></td> <td></td> <td>Active → Open; none + standard tier + plan free → Upgrade to Standard (BIL-01); none+public → Get access; disabled/expired/revoked → Contact support (support_url)</td> </tr> <tr> <td>Notification settings</td> <td>row → SET-02</td> <td>row link</td> <td>resolved notifications.push for this app</td> <td>"Push notifications: On/Off"</td> </tr> <tr> <td>App settings / App profile</td> <td>rows</td> <td>list rows</td> <td>→ SET-02, APP-04</td> <td>only when active</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="app-03--launch-app"><a class="anchor" href="#app-03--launch-app" aria-hidden="true" tabindex="-1">#</a>APP-03 — Launch app</h3> <p><strong>Domain:</strong> D3 My Apps · <strong>Route:</strong> <code>/apps/:appId/launch</code> · <strong>Archetype:</strong> handoff · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Active entitlement<br><strong>Purpose:</strong> Mint an app token (or authorization code) and open the app.</p> <p><strong>Web (PWA) container:</strong> <code>window.open</code> (new tab) / same-tab redirect for PKCE</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Progress</td> <td>inline spinner on tile</td> <td>spinner on tile (aria-busy)</td> <td></td> <td>≤ 1 s target</td> </tr> <tr> <td>Organization picker</td> <td>menu</td> <td>menu button (role=menu)</td> <td>body.organization_id</td> <td>only when the user has access via >1 org and the app needs org context</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Embedded launch</td> <td><code>POST /auth/app-tokens {application_id, organization_id?}</code></td> <td>200 AppToken (5-min JWT) → open launch_url with token per app contract; never cache the token. 403 → refresh status, show APP-02. 409 → choose org.</td> </tr> <tr> <td>Hosted launch (Phase 3)</td> <td><code>POST /auth/oauth/authorization-codes (PKCE S256)</code></td> <td>201 → open redirect_uri?code=…&state=… in system browser / auth session</td> </tr> </tbody></table></div> <p><strong>Notes:</strong> Record launch time locally for "recently launched" ordering.</p> <h3 id="app-04--app-profile"><a class="anchor" href="#app-04--app-profile" aria-hidden="true" tabindex="-1">#</a>APP-04 — App profile</h3> <p><strong>Domain:</strong> D3 My Apps · <strong>Route:</strong> <code>/apps/:appId/profile</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Self, active entitlement<br><strong>Purpose:</strong> Per-app display handle and custom profile fields.</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <p><strong>Loads:</strong> <code>GET /users/me/apps/{appId}/profile</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Display handle</td> <td>text-field</td> <td><input type=text></td> <td>AppProfile.display_handle</td> <td>optional; shows effective_display_name as placeholder</td> </tr> <tr> <td>Custom fields</td> <td>key/value editor</td> <td>repeating key/value inputs + Add</td> <td>AppProfile.custom</td> <td>only keys the app documents; null removes a key</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Save</td> <td><code>PATCH /users/me/apps/{appId}/profile (If-Match)</code></td> <td></td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="app-05--past-apps"><a class="anchor" href="#app-05--past-apps" aria-hidden="true" tabindex="-1">#</a>APP-05 — Past apps</h3> <p><strong>Domain:</strong> D3 My Apps · <strong>Route:</strong> <code>/apps/past</code> · <strong>Archetype:</strong> list · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Signed in<br><strong>Purpose:</strong> Apps whose access was revoked or expired.</p> <p><strong>Web (PWA) container:</strong> List pane (resizable) + detail pane ≥ 768 px; single pane < 768 px</p> <p><strong>Loads:</strong> <code>GET /users/me/entitlements?include_inactive=true&status=revoked,expired</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Rows</td> <td>list</td> <td>virtualized list</td> <td>Application name/icon, status, ended/revoked date, source</td> <td>tap → APP-02</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h2 id="d4--settings"><a class="anchor" href="#d4--settings" aria-hidden="true" tabindex="-1">#</a>D4 · Settings</h2> <h3 id="set-01--settings--global"><a class="anchor" href="#set-01--settings--global" aria-hidden="true" tabindex="-1">#</a>SET-01 — Settings — Global</h3> <p><strong>Domain:</strong> D4 Settings · <strong>Route:</strong> <code>/settings</code> · <strong>Archetype:</strong> settings · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Self<br><strong>Purpose:</strong> Preferences that apply to every app.</p> <p><strong>Web (PWA) container:</strong> Grouped settings rows in main pane</p> <p><strong>Loads:</strong> <code>GET /users/me/settings</code> · <code>GET /users/me/apps/app_hub/settings</code> (theme choices)</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Language</td> <td>select</td> <td><select> / listbox popover</td> <td>Settings.locale</td> <td>BCP 47; default = OS language; changing re-localizes the UI live</td> </tr> <tr> <td>Time zone</td> <td>searchable select</td> <td>combobox with filter</td> <td>Settings.timezone</td> <td>IANA; default = OS zone; "Use device time zone" option</td> </tr> <tr> <td>Appearance</td> <td>segmented</td> <td>role=radiogroup segmented buttons</td> <td>Settings.theme light/dark/system</td> <td>Light · Dark · Match system (default). Applies instantly; Match system follows OS changes live. See THEMES.md</td> </tr> <tr> <td>Light theme</td> <td>swatch picker</td> <td>role=radiogroup grid of swatch radios (arrow keys move, Space selects)</td> <td><code>app_hub</code> setting <code>appearance.light_theme</code></td> <td>5 themes: Teal Ledger, Indigo Root, <strong>Moss Paper (default)</strong>, Coral Clay, Spore Pink. Each swatch previews background, sidebar, accent and text; selected swatch shows a check and accent ring; accessible name "{name} light theme, selected"</td> </tr> <tr> <td>Dark theme</td> <td>swatch picker</td> <td>role=radiogroup grid of swatch radios (arrow keys move, Space selects)</td> <td><code>app_hub</code> setting <code>appearance.dark_theme</code></td> <td>5 themes: Night Soil, Deep Teal, Graphite Spore, <strong>Forest Floor (default)</strong>, Ember Clay. Same behaviour as Light theme</td> </tr> <tr> <td>Push notifications</td> <td>toggle</td> <td><button role=switch></td> <td>Settings.notifications.push (missing = on)</td> <td>global master switch for push from every app; inbox still fills (NTF-01). Shows OS permission state beneath: "Allowed in system settings" / "Blocked — Open system settings"</td> </tr> <tr> <td>Email notifications</td> <td>toggle</td> <td><button role=switch></td> <td>Settings.notifications.email</td> <td></td> </tr> <tr> <td>SMS notifications</td> <td>toggle</td> <td><button role=switch></td> <td>Settings.notifications.sms</td> <td>disabled until Profile.contact_phone set</td> </tr> <tr> <td>Share usage analytics</td> <td>toggle</td> <td><button role=switch></td> <td>client preference</td> <td>default per platform policy; see CLIENT-ARCHITECTURE §10</td> </tr> <tr> <td>Scope list</td> <td>list</td> <td>virtualized list</td> <td>Global + each app with active access</td> <td>→ SET-02 (desktop: middle column)</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Change any row</td> <td><code>PATCH /users/me/settings (If-Match)</code></td> <td>Optimistic; revert + toast on error.</td> </tr> <tr> <td>Choose a light or dark theme</td> <td><code>PATCH /users/me/apps/app_hub/settings (If-Match)</code> with <code>appearance.light_theme</code> / <code>appearance.dark_theme</code></td> <td>Apply instantly, cache locally, then sync; 409 → refetch and re-apply; 422 → revert + toast "Couldn't save your theme. Try again."</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="set-02--settings--per-app"><a class="anchor" href="#set-02--settings--per-app" aria-hidden="true" tabindex="-1">#</a>SET-02 — Settings — Per app</h3> <p><strong>Domain:</strong> D4 Settings · <strong>Route:</strong> <code>/settings/apps/:appId</code> · <strong>Archetype:</strong> settings · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Self, active entitlement<br><strong>Purpose:</strong> Override global settings and set app-specific preferences from the app's settings_schema.</p> <p><strong>Web (PWA) container:</strong> Grouped settings rows in main pane</p> <p><strong>Loads:</strong> <code>GET /applications/{appId} (settings_schema)</code> · <code>GET /users/me/apps/{appId}/settings</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Schema form</td> <td>generated rows</td> <td>SchemaForm</td> <td>settings_schema properties × AppSettingsResolved.resolved</td> <td>string+enum → select; string → text; string date-time → date-time picker; boolean → toggle; integer/number with min/max → stepper/number; object/array → read-only JSON preview</td> </tr> <tr> <td>Source caption</td> <td>caption per row</td> <td><small></td> <td>AppSettingsResolved.sources[key]</td> <td>app_override → "Changed for this app · Reset"; global → "Using your global setting"; app_default → "App default"</td> </tr> <tr> <td>Reset</td> <td>link per overridden row</td> <td>row link</td> <td>PATCH overrides {key:null}</td> <td></td> </tr> <tr> <td>Push notifications for this app</td> <td>toggle</td> <td><button role=switch></td> <td>resolved notifications.push; override via overrides.notifications.push</td> <td>source caption as other rows; Reset clears the override</td> </tr> <tr> <td>Stale overrides</td> <td>banner</td> <td>role=region banner</td> <td>AppSettingsResolved.stale_overrides</td> <td>"Some saved settings no longer apply" → Clear</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Change row</td> <td><code>PATCH /users/me/apps/{appId}/settings {overrides:{key:value}} (If-Match)</code></td> <td>422 → field error from details (enum_mismatch, out_of_range, undeclared_key).</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h2 id="d5--organizations"><a class="anchor" href="#d5--organizations" aria-hidden="true" tabindex="-1">#</a>D5 · Organizations</h2> <h3 id="org-01--organizations"><a class="anchor" href="#org-01--organizations" aria-hidden="true" tabindex="-1">#</a>ORG-01 — Organizations</h3> <p><strong>Domain:</strong> D5 Organizations · <strong>Route:</strong> <code>/orgs</code> · <strong>Archetype:</strong> list · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Signed in (all orgs with organizations.manage)<br><strong>Purpose:</strong> Organizations you belong to, plus pending invitations.</p> <p><strong>Web (PWA) container:</strong> List pane (resizable) + detail pane ≥ 768 px; single pane < 768 px</p> <p><strong>Loads:</strong> <code>GET /organizations</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Pending invitations</td> <td>section</td> <td><section></td> <td>my_membership_status = pending</td> <td>Accept / Decline inline → ORG-09</td> </tr> <tr> <td>Rows</td> <td>list</td> <td>virtualized list</td> <td>Organization: name, member_count, my_role, status</td> <td>suspended orgs show badge</td> </tr> <tr> <td>Search</td> <td>search</td> <td><input type=search role=searchbox></td> <td>q</td> <td>server-side when > 50</td> </tr> <tr> <td>New organization</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>→ ORG-02</td> <td></td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="org-02--new-organization"><a class="anchor" href="#org-02--new-organization" aria-hidden="true" tabindex="-1">#</a>ORG-02 — New organization</h3> <p><strong>Domain:</strong> D5 Organizations · <strong>Route:</strong> <code>/orgs/new</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Any active user<br><strong>Purpose:</strong> Create an organization; creator becomes org admin.</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Name</td> <td>text-field</td> <td><input type=text></td> <td>body.name</td> <td>required; ≤ 100</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Create</td> <td><code>POST /organizations (Idempotency-Key)</code></td> <td>201 → ORG-03. 429 → rate limited.</td> </tr> </tbody></table></div> <h3 id="org-03--organization--members"><a class="anchor" href="#org-03--organization--members" aria-hidden="true" tabindex="-1">#</a>ORG-03 — Organization — Members</h3> <p><strong>Domain:</strong> D5 Organizations · <strong>Route:</strong> <code>/orgs/:orgId/members</code> · <strong>Archetype:</strong> detail · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Member (read), org_admin / organizations.manage (write)<br><strong>Purpose:</strong> See and manage members and pending invitations.</p> <p><strong>Web (PWA) container:</strong> Detail pane with header, tablist, toolbar; full page < 768 px</p> <p><strong>Loads:</strong> <code>GET /organizations/{id}</code> · <code>GET /organizations/{id}/members</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Header</td> <td>avatar + name + id-chip + status</td> <td><code> + copy button</td> <td>Organization</td> <td>my_role shown as caption</td> </tr> <tr> <td>Tabs</td> <td>tabs</td> <td>role=tablist</td> <td>Members · Apps & seats · Subscription · Activity · Settings</td> <td>Subscription tab = BIL-02 (org_admin / billing.manage only)</td> </tr> <tr> <td>Filter</td> <td>chips</td> <td>toggle-button chip row</td> <td>role, membership_status</td> <td></td> </tr> <tr> <td>Rows</td> <td>list</td> <td>virtualized list</td> <td>OrganizationMember: display_name/email, role, membership_status, joined_at/invited_at</td> <td>pending rows show Invited badge + invited date</td> </tr> <tr> <td>Invite</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>→ ORG-04</td> <td>org_admin only</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Row menu</td> <td><code>→ ORG-05</code></td> <td>Change role · Remove · Withdraw invitation</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="org-04--invite-member"><a class="anchor" href="#org-04--invite-member" aria-hidden="true" tabindex="-1">#</a>ORG-04 — Invite member</h3> <p><strong>Domain:</strong> D5 Organizations · <strong>Route:</strong> <code>/orgs/:orgId/members/invite</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> MVP<br><strong>Who:</strong> org_admin; organizations.manage may add by user_id<br><strong>Purpose:</strong> Invite people by email (or add an existing user, staff only).</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Emails</td> <td>token-field</td> <td>token input (chips in input)</td> <td>body.email (one request per address)</td> <td>paste a list separated by commas/newlines</td> </tr> <tr> <td>Role</td> <td>radio-group</td> <td><fieldset> radios</td> <td>body.role org_admin \| member</td> <td>default member</td> </tr> <tr> <td>Add existing user</td> <td>user-picker</td> <td>combobox multi-select</td> <td>body.user_id</td> <td>organizations.manage only</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Send invitations</td> <td><code>POST /organizations/{id}/members × n</code></td> <td>Per-address results summary; 409 → "already a member" per address. Responses look identical whether or not the address has an account (by design).</td> </tr> </tbody></table></div> <p><strong>Notes:</strong> Existing Users also receive an <code>account.organization_invitation</code> platform alert (NTF-01, and a push where the Hub has a device).</p> <h3 id="org-05--member-actions"><a class="anchor" href="#org-05--member-actions" aria-hidden="true" tabindex="-1">#</a>ORG-05 — Member actions</h3> <p><strong>Domain:</strong> D5 Organizations · <strong>Route:</strong> <code>/orgs/:orgId/members/:userId</code> · <strong>Archetype:</strong> confirm · <strong>Phase:</strong> MVP<br><strong>Who:</strong> org_admin / organizations.manage<br><strong>Purpose:</strong> Change a member's role or remove them.</p> <p><strong>Web (PWA) container:</strong> <code><dialog role=alertdialog></code>; bottom sheet < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Role</td> <td>radio-group</td> <td><fieldset> radios</td> <td>body.role</td> <td></td> </tr> <tr> <td>Remove from organization</td> <td>destructive-button</td> <td><button class=destructive></td> <td>DELETE …/members/{userId}</td> <td>COPY confirm</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Change role</td> <td><code>PATCH /organizations/{id}/members/{userId}</code></td> <td>409 → last admin can't be demoted (explain).</td> </tr> <tr> <td>Remove</td> <td><code>DELETE /organizations/{id}/members/{userId}</code></td> <td>409 → last admin can't leave/remove.</td> </tr> </tbody></table></div> <h3 id="org-06--organization--apps--seats"><a class="anchor" href="#org-06--organization--apps--seats" aria-hidden="true" tabindex="-1">#</a>ORG-06 — Organization — Apps & seats</h3> <p><strong>Domain:</strong> D5 Organizations · <strong>Route:</strong> <code>/orgs/:orgId/apps</code> · <strong>Archetype:</strong> tab · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Member (read), org_admin (write)<br><strong>Purpose:</strong> Org-wide app grants and who they include.</p> <p><strong>Web (PWA) container:</strong> <code>tabpanel</code> (route segment)</p> <p><strong>Loads:</strong> <code>GET /organizations/{id}/entitlements</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Rows</td> <td>list</td> <td>virtualized list</td> <td>Entitlement (org): app, status, source (org_seat \| subscription), member_scope, included_member_count, starts_at/ends_at</td> <td>AccessSwitch for status (org_admin with rights); <code>subscription</code> rows read "Included with the organization's Standard subscription" and their scope is edited in BIL-02</td> </tr> <tr> <td>Grant app</td> <td>button</td> <td><button></td> <td>→ ORG-07</td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Toggle</td> <td><code>PATCH /entitlements/{id} {status}</code></td> <td>Off requires confirm (COPY). On platform-managed rows only active ⇄ disabled is allowed; anything else 409 entitlement_platform_managed.</td> </tr> <tr> <td>Edit scope</td> <td><code>→ ORG-07 (org_seat) / BIL-02 (subscription)</code></td> <td></td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="org-07--grant-app-to-organization--member-scope"><a class="anchor" href="#org-07--grant-app-to-organization--member-scope" aria-hidden="true" tabindex="-1">#</a>ORG-07 — Grant app to organization / member scope</h3> <p><strong>Domain:</strong> D5 Organizations · <strong>Route:</strong> <code>/orgs/:orgId/apps/grant</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> entitlements.manage or app owner; scope edits by org_admin<br><strong>Purpose:</strong> Create an org-wide grant or change who it includes.</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>App</td> <td>select</td> <td><select> / listbox popover</td> <td>body.application_id</td> <td>create only</td> </tr> <tr> <td>Who gets access</td> <td>radio-group</td> <td><fieldset> radios</td> <td>member_scope all_members \| allowlist \| denylist</td> <td>COPY labels</td> </tr> <tr> <td>Members</td> <td>member-picker</td> <td>combobox multi-select</td> <td>member_overrides</td> <td>visible for allowlist/denylist</td> </tr> <tr> <td>Starts / Ends</td> <td>date-fields</td> <td><input type=date\|datetime-local></td> <td>starts_at, ends_at</td> <td>optional</td> </tr> <tr> <td>Order ID</td> <td>text-field</td> <td><input type=text></td> <td>order_id</td> <td>optional; staff/app owner</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Grant</td> <td><code>POST /organizations/{id}/entitlements (Idempotency-Key)</code></td> <td>409 entitlement_already_exists → already granted (view it). 422 → field errors.</td> </tr> <tr> <td>Save scope</td> <td><code>PATCH /entitlements/{id} {member_scope, member_overrides}</code></td> <td></td> </tr> </tbody></table></div> <h3 id="org-08--organization--settings"><a class="anchor" href="#org-08--organization--settings" aria-hidden="true" tabindex="-1">#</a>ORG-08 — Organization — Settings</h3> <p><strong>Domain:</strong> D5 Organizations · <strong>Route:</strong> <code>/orgs/:orgId/settings</code> · <strong>Archetype:</strong> settings · <strong>Phase:</strong> MVP<br><strong>Who:</strong> org_admin (rename), organizations.manage (suspend), any member (leave)<br><strong>Purpose:</strong> Rename, leave, or (staff) suspend the organization.</p> <p><strong>Web (PWA) container:</strong> Grouped settings rows in main pane</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Name</td> <td>text-field</td> <td><input type=text></td> <td>Organization.name</td> <td></td> </tr> <tr> <td>Leave organization</td> <td>destructive-row</td> <td>row button (destructive)</td> <td>DELETE …/members/me</td> <td></td> </tr> <tr> <td>Suspend / Reactivate</td> <td>destructive-row</td> <td>row button (destructive)</td> <td>PATCH {status, reason}</td> <td>staff only; reason required</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Rename</td> <td><code>PATCH /organizations/{id} {name}</code></td> <td></td> </tr> <tr> <td>Leave</td> <td><code>DELETE /organizations/{id}/members/me</code></td> <td>409 last admin</td> </tr> </tbody></table></div> <h3 id="org-09--invitation"><a class="anchor" href="#org-09--invitation" aria-hidden="true" tabindex="-1">#</a>ORG-09 — Invitation</h3> <p><strong>Domain:</strong> D5 Organizations · <strong>Route:</strong> <code>/orgs/:orgId/invitation</code> · <strong>Archetype:</strong> confirm · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Invited user<br><strong>Purpose:</strong> Accept or decline an organization invitation.</p> <p><strong>Web (PWA) container:</strong> <code><dialog role=alertdialog></code>; bottom sheet < 768 px</p> <p><strong>Entry points:</strong> Invitation banner on APP-01; ORG-01 pending section; <code>account.organization_invitation</code> notification (NTF-01 / push action "Accept")</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Org name + inviter</td> <td>text</td> <td><p></td> <td>Organization</td> <td></td> </tr> <tr> <td>Accept</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td></td> <td></td> </tr> <tr> <td>Decline</td> <td>button</td> <td><button></td> <td></td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Accept</td> <td><code>POST /organizations/{id}/members/me/accept</code></td> <td>200 → ORG-03; apps granted via org (and the org's Standard subscription, if it covers the member) appear on APP-01. Mark the related notification read.</td> </tr> <tr> <td>Decline</td> <td><code>DELETE /organizations/{id}/members/me</code></td> <td></td> </tr> </tbody></table></div> <h2 id="d6--users"><a class="anchor" href="#d6--users" aria-hidden="true" tabindex="-1">#</a>D6 · Users</h2> <h3 id="usr-01--users"><a class="anchor" href="#usr-01--users" aria-hidden="true" tabindex="-1">#</a>USR-01 — Users</h3> <p><strong>Domain:</strong> D6 Users · <strong>Route:</strong> <code>/admin/users</code> · <strong>Archetype:</strong> table · <strong>Phase:</strong> MVP<br><strong>Who:</strong> users.list (write actions need users.manage)<br><strong>Purpose:</strong> Find and manage user accounts.</p> <p><strong>Web (PWA) container:</strong> Virtualized grid table ≥ 1024 px; card rows below</p> <p><strong>Loads:</strong> <code>GET /users?limit=50&cursor&status&q&application_id&organization_id&created_after&created_before</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Search</td> <td>search</td> <td><input type=search role=searchbox></td> <td>q (name, email, ID prefix usr_)</td> <td>debounced 300 ms; exact ID jumps to USR-03</td> </tr> <tr> <td>Status filter</td> <td>chips</td> <td>toggle-button chip row</td> <td>status active \| invited \| suspended \| deleted</td> <td>deleted visible to users.manage only</td> </tr> <tr> <td>More filters</td> <td>menu</td> <td>menu button (role=menu)</td> <td>application_id, organization_id, created range</td> <td></td> </tr> <tr> <td>Columns</td> <td>table</td> <td>role=grid virtualized table</td> <td>display name + email, status, id, last_login_at, created_at</td> <td>sortable client-side within loaded page; server order = created_at desc</td> </tr> <tr> <td>Multi-select</td> <td>selection</td> <td><select> / listbox popover</td> <td></td> <td>bulk: Suspend, Resend invitation, Export CSV (client-side of loaded rows)</td> </tr> <tr> <td>Invite user</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>→ USR-02</td> <td>users.manage</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Open row</td> <td><code>→ USR-03</code></td> <td></td> </tr> <tr> <td>Row menu</td> <td></td> <td>Suspend · Reactivate · Resend invitation · Copy ID · Copy email</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="usr-02--invite-user"><a class="anchor" href="#usr-02--invite-user" aria-hidden="true" tabindex="-1">#</a>USR-02 — Invite user</h3> <p><strong>Domain:</strong> D6 Users · <strong>Route:</strong> <code>/admin/users/new</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> MVP<br><strong>Who:</strong> users.manage<br><strong>Purpose:</strong> Create a user and send an invitation (or create active).</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Email</td> <td>email-field</td> <td><input type=email autocomplete=username></td> <td>body.email</td> <td>required</td> </tr> <tr> <td>Display name</td> <td>text-field</td> <td><input type=text></td> <td>body.display_name</td> <td>optional</td> </tr> <tr> <td>Send invitation email</td> <td>toggle</td> <td><button role=switch></td> <td>body.send_invitation</td> <td>default on</td> </tr> <tr> <td>Create as active</td> <td>toggle</td> <td><button role=switch></td> <td>body.status active\|invited</td> <td>default off (invited)</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Invite</td> <td><code>POST /users (Idempotency-Key)</code></td> <td>201 → USR-03. 409 → "A user with that email exists" + link.</td> </tr> </tbody></table></div> <h3 id="usr-03--user--overview"><a class="anchor" href="#usr-03--user--overview" aria-hidden="true" tabindex="-1">#</a>USR-03 — User — Overview</h3> <p><strong>Domain:</strong> D6 Users · <strong>Route:</strong> <code>/admin/users/:userId</code> · <strong>Archetype:</strong> detail · <strong>Phase:</strong> MVP<br><strong>Who:</strong> users.list (read), users.manage (write)<br><strong>Purpose:</strong> One user's account state and administrative actions.</p> <p><strong>Web (PWA) container:</strong> Detail pane with header, tablist, toolbar; full page < 768 px</p> <p><strong>Loads:</strong> <code>GET /users/{id}</code> · <code>GET /users/{id}/profile</code> · <code>GET /users/{id}/subscription (billing.manage only)</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Header</td> <td>avatar, display name, email, id-chip, StatusBadge</td> <td><code> + copy button</td> <td>User + Profile</td> <td></td> </tr> <tr> <td>Tabs</td> <td>tabs</td> <td>role=tablist</td> <td>Overview · Access · Roles · Sessions · Notifications · Activity</td> <td>Activity = AUD-01 filtered target_user_id; Notifications = NTF-05</td> </tr> <tr> <td>Facts</td> <td>key-value list</td> <td><dl></td> <td>email_verified, pending_email, mfa_enabled, plan, plan_sources, created_at, last_login_at, signup_application_id, test_mode</td> <td>plan_sources link to the org or to BIL-01 subscription view (billing.manage)</td> </tr> <tr> <td>Actions</td> <td>toolbar/menu</td> <td>menu button (role=menu)</td> <td></td> <td>Suspend (USR-05) · Reactivate · Resend invitation · Reset two-factor · Export data · Delete · Restore · Cancel scheduled erasure</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Reactivate / Restore</td> <td><code>PATCH /users/{id} {status:active} (If-Match)</code></td> <td></td> </tr> <tr> <td>Resend invitation</td> <td><code>POST /users/{id}/invitation</code></td> <td>202 toast; 409 → not in invited state</td> </tr> <tr> <td>Reset two-factor</td> <td><code>DELETE /users/{id}/mfa/totp</code></td> <td>confirm</td> </tr> <tr> <td>Export</td> <td><code>GET /users/{id}/export</code></td> <td>save file</td> </tr> <tr> <td>Delete</td> <td><code>DELETE /users/{id}</code></td> <td>confirm</td> </tr> <tr> <td>Cancel erasure</td> <td><code>DELETE /users/{id}/erasure-requests/current</code></td> <td>visible during 7-day window</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="usr-04--user--sessions"><a class="anchor" href="#usr-04--user--sessions" aria-hidden="true" tabindex="-1">#</a>USR-04 — User — Sessions</h3> <p><strong>Domain:</strong> D6 Users · <strong>Route:</strong> <code>/admin/users/:userId/sessions</code> · <strong>Archetype:</strong> tab · <strong>Phase:</strong> MVP<br><strong>Who:</strong> users.manage<br><strong>Purpose:</strong> See and revoke a user's sessions.</p> <p><strong>Web (PWA) container:</strong> <code>tabpanel</code> (route segment)</p> <p><strong>Loads:</strong> <code>GET /users/{id}/sessions</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Rows</td> <td>list</td> <td>virtualized list</td> <td>Session: user_agent, ip_address, amr, created_at, last_seen_at, expires_at</td> <td>staff see full IP</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Revoke</td> <td><code>DELETE /users/{id}/sessions/{sessionId}</code></td> <td></td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="usr-05--suspend-user"><a class="anchor" href="#usr-05--suspend-user" aria-hidden="true" tabindex="-1">#</a>USR-05 — Suspend user</h3> <p><strong>Domain:</strong> D6 Users · <strong>Route:</strong> <code>/admin/users/:userId/suspend</code> · <strong>Archetype:</strong> confirm · <strong>Phase:</strong> MVP<br><strong>Who:</strong> users.manage<br><strong>Purpose:</strong> Suspend an account (signs them out everywhere).</p> <p><strong>Web (PWA) container:</strong> <code><dialog role=alertdialog></code>; bottom sheet < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Reason</td> <td>text-area</td> <td><textarea></td> <td>body.reason</td> <td>optional, written to audit</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Suspend</td> <td><code>POST /users/{id}/suspend</code></td> <td>200 → badge Suspended. 409 → already suspended.</td> </tr> </tbody></table></div> <p><strong>Notes:</strong> Suspension revokes sessions and deactivates every push device the user holds; say so in the confirm body.</p> <h2 id="d7--access"><a class="anchor" href="#d7--access" aria-hidden="true" tabindex="-1">#</a>D7 · Access</h2> <h3 id="acx-01--user--access"><a class="anchor" href="#acx-01--user--access" aria-hidden="true" tabindex="-1">#</a>ACX-01 — User — Access</h3> <p><strong>Domain:</strong> D7 Access · <strong>Route:</strong> <code>/admin/users/:userId/access</code> · <strong>Archetype:</strong> tab · <strong>Phase:</strong> MVP<br><strong>Who:</strong> users.list (read), entitlements.manage or app owner (write)<br><strong>Purpose:</strong> Turn apps on or off for one person; see every path that grants access.</p> <p><strong>Web (PWA) container:</strong> <code>tabpanel</code> (route segment)</p> <p><strong>Loads:</strong> <code>GET /users/{id}/entitlements?include_inactive=true</code> · <code>GET /applications</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Rows (one per app)</td> <td>list</td> <td>virtualized list</td> <td>resolved status per app + paths (personal Entitlement, org grants)</td> <td>StatusBadge + AccessSwitch on the personal path</td> </tr> <tr> <td>Paths disclosure</td> <td>expandable</td> <td><details></td> <td>Entitlement.granted_via, source, subscription_id, organization_id, member_decision, starts_at/ends_at, disabled_reason</td> <td>platform-managed paths (<code>free</code>, <code>subscription</code>) show a "Managed by Substratal" caption; developer grants and platform rows can coexist</td> </tr> <tr> <td>Org-only access</td> <td>caption + link</td> <td><small></td> <td></td> <td>switch replaced by "Via {org}" → ORG-06</td> </tr> <tr> <td>Grant access</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>→ ACX-02</td> <td></td> </tr> <tr> <td>Why?</td> <td>button</td> <td><button></td> <td>→ ACX-04</td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Switch off</td> <td><code>→ ACX-03 confirm → PATCH /entitlements/{id} {status:disabled, disabled_reason}</code></td> <td>Optimistic with Undo (PATCH status:active) for 10 s</td> </tr> <tr> <td>Switch on</td> <td><code>PATCH /entitlements/{id} {status:active}</code></td> <td>No confirm</td> </tr> <tr> <td>Remove grant made in error</td> <td><code>DELETE /entitlements/{id}</code></td> <td>Only developer grants with no order_id and < 24 h old; never on <code>free</code>/<code>subscription</code> rows (409 entitlement_platform_managed); 409 otherwise</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <p><strong>Notes:</strong> The switch on a platform-managed row only disables / re-enables it (the platform never re-enables a row an admin disabled). Term, source and scope edits are hidden for those rows.</p> <h3 id="acx-02--grant-access"><a class="anchor" href="#acx-02--grant-access" aria-hidden="true" tabindex="-1">#</a>ACX-02 — Grant access</h3> <p><strong>Domain:</strong> D7 Access · <strong>Route:</strong> <code>/admin/users/:userId/access/grant</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> MVP<br><strong>Who:</strong> entitlements.manage or app owner (own app)<br><strong>Purpose:</strong> Give a person access to an app.</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>App</td> <td>select</td> <td><select> / listbox popover</td> <td>body.application_id</td> <td>app owners see only their apps</td> </tr> <tr> <td>Type</td> <td>radio-group</td> <td><fieldset> radios</td> <td>body.source purchase \| trial \| admin_grant</td> <td><code>free</code> and <code>subscription</code> are never offered — the platform grants them</td> </tr> <tr> <td>Order ID</td> <td>text-field</td> <td><input type=text></td> <td>body.order_id</td> <td>required feel for purchase</td> </tr> <tr> <td>Starts</td> <td>date-time</td> <td><input type=date\|datetime-local></td> <td>body.starts_at</td> <td>default now</td> </tr> <tr> <td>Ends</td> <td>date-time</td> <td><input type=date\|datetime-local></td> <td>body.ends_at</td> <td>optional; required for trial</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Grant</td> <td><code>POST /users/{id}/entitlements (Idempotency-Key, required)</code></td> <td>201 → row Active. 409 entitlement_already_exists → "Already has access — view it". A platform-managed row doesn't block a grant (they coexist).</td> </tr> </tbody></table></div> <h3 id="acx-03--turn-off--edit-access"><a class="anchor" href="#acx-03--turn-off--edit-access" aria-hidden="true" tabindex="-1">#</a>ACX-03 — Turn off / edit access</h3> <p><strong>Domain:</strong> D7 Access · <strong>Route:</strong> <code>/admin/entitlements/:entId</code> · <strong>Archetype:</strong> confirm · <strong>Phase:</strong> MVP<br><strong>Who:</strong> entitlements.manage or app owner<br><strong>Purpose:</strong> Confirm turning off access, or edit term/source.</p> <p><strong>Web (PWA) container:</strong> <code><dialog role=alertdialog></code>; bottom sheet < 768 px</p> <p><strong>Loads:</strong> <code>GET /entitlements/{id}</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Title</td> <td>text</td> <td><p></td> <td></td> <td>"Turn off {app} for {name}?"</td> </tr> <tr> <td>Reason</td> <td>text-field</td> <td><input type=text></td> <td>body.disabled_reason</td> <td>optional; audit</td> </tr> <tr> <td>Edit term (advanced)</td> <td>disclosure</td> <td><details></td> <td>ends_at, source trial→purchase, order_id</td> <td>hidden for platform-managed rows</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Turn off</td> <td><code>PATCH /entitlements/{id} {status:disabled, disabled_reason} (If-Match)</code></td> <td>409 version_conflict → reload and re-apply</td> </tr> <tr> <td>Save changes</td> <td><code>PATCH /entitlements/{id}</code></td> <td></td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="acx-04--access-check-why"><a class="anchor" href="#acx-04--access-check-why" aria-hidden="true" tabindex="-1">#</a>ACX-04 — Access check (Why?)</h3> <p><strong>Domain:</strong> D7 Access · <strong>Route:</strong> <code>/admin/users/:userId/apps/:appId/why</code> · <strong>Archetype:</strong> popover · <strong>Phase:</strong> MVP<br><strong>Who:</strong> users.list or app owner<br><strong>Purpose:</strong> Explain exactly why a person can or can't use an app.</p> <p><strong>Web (PWA) container:</strong> Popover ≥ 1024 px; side panel 768–1023; bottom sheet < 768</p> <p><strong>Loads:</strong> <code>GET /users/{id}/apps/{appId}/effective-permissions</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Verdict</td> <td>banner</td> <td>role=region banner</td> <td>allowed</td> <td>"Dana can use Timetrack" / "can't" + first failing reason (user_status, entitlement_status)</td> </tr> <tr> <td>Checks</td> <td>checklist</td> <td><ul> with status icons</td> <td>user_status, entitlement_status, access_paths[], roles, effective_permissions</td> <td>each with pass/fail icon</td> </tr> <tr> <td>Computed at</td> <td>caption</td> <td><small></td> <td>computed_at</td> <td></td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="acx-05--access-all"><a class="anchor" href="#acx-05--access-all" aria-hidden="true" tabindex="-1">#</a>ACX-05 — Access (all)</h3> <p><strong>Domain:</strong> D7 Access · <strong>Route:</strong> <code>/admin/access</code> · <strong>Archetype:</strong> table · <strong>Phase:</strong> MVP<br><strong>Who:</strong> entitlements.manage or app owner (confined to own apps)<br><strong>Purpose:</strong> Every grant across users: audit expirations, trials, revocations.</p> <p><strong>Web (PWA) container:</strong> Virtualized grid table ≥ 1024 px; card rows below</p> <p><strong>Loads:</strong> <code>GET /entitlements?application_id&status&source&user_id&organization_id&order_id&ends_before&include_inactive</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Filters</td> <td>chips/menus</td> <td>toggle-button chip row</td> <td>app, status, source, ends before (Expiring in 7/30 days presets)</td> <td></td> </tr> <tr> <td>Columns</td> <td>table</td> <td>role=grid virtualized table</td> <td>user, app, status, source (incl. free / subscription), subscription_id, starts_at, ends_at, order_id, granted_via</td> <td>source filter defaults to developer grants; "Show platform-managed" chip adds free/subscription rows</td> </tr> <tr> <td>Multi-select</td> <td>selection</td> <td><select> / listbox popover</td> <td></td> <td>bulk Turn off (confirm, one PATCH per row, progress + per-row result)</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Open row</td> <td><code>→ ACX-01 for that user</code></td> <td></td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h2 id="d8--roles--permissions"><a class="anchor" href="#d8--roles--permissions" aria-hidden="true" tabindex="-1">#</a>D8 · Roles & Permissions</h2> <h3 id="rol-01--roles"><a class="anchor" href="#rol-01--roles" aria-hidden="true" tabindex="-1">#</a>ROL-01 — Roles</h3> <p><strong>Domain:</strong> D8 Roles & Permissions · <strong>Route:</strong> <code>/admin/roles</code> · <strong>Archetype:</strong> list · <strong>Phase:</strong> MVP<br><strong>Who:</strong> users.list (read), roles.manage (write)<br><strong>Purpose:</strong> Platform and app roles.</p> <p><strong>Web (PWA) container:</strong> List pane (resizable) + detail pane ≥ 768 px; single pane < 768 px</p> <p><strong>Loads:</strong> <code>GET /roles?scope</code> · <code>GET /permissions (includes notifications.send)</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Scope</td> <td>segmented</td> <td>role=radiogroup segmented buttons</td> <td>scope platform \| {application_id}</td> <td>app picker when App</td> </tr> <tr> <td>Rows</td> <td>list</td> <td>virtualized list</td> <td>Role: name, scope, seed, assignment_count, description</td> <td>seed → lock icon</td> </tr> <tr> <td>New role</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>→ ROL-03</td> <td>roles.manage</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="rol-02--role-detail"><a class="anchor" href="#rol-02--role-detail" aria-hidden="true" tabindex="-1">#</a>ROL-02 — Role detail</h3> <p><strong>Domain:</strong> D8 Roles & Permissions · <strong>Route:</strong> <code>/admin/roles/:roleId</code> · <strong>Archetype:</strong> detail · <strong>Phase:</strong> MVP<br><strong>Who:</strong> users.list (read), roles.manage (write)<br><strong>Purpose:</strong> View or edit a role's permissions.</p> <p><strong>Web (PWA) container:</strong> Detail pane with header, tablist, toolbar; full page < 768 px</p> <p><strong>Loads:</strong> <code>GET /roles/{id}</code> · <code>GET /permissions?scope</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Header</td> <td>name, id-chip, scope, assignment_count</td> <td><code> + copy button</td> <td></td> <td></td> </tr> <tr> <td>Description</td> <td>text-field</td> <td><input type=text></td> <td>Role.description</td> <td>read-only when seed</td> </tr> <tr> <td>Permissions</td> <td>checkbox-list grouped by prefix</td> <td>grouped checkbox list</td> <td>Role.permissions ⊂ Permission[].key</td> <td>read-only when seed; show Permission.description</td> </tr> <tr> <td>Holders</td> <td>link</td> <td><a> / <button class=link></td> <td>→ USR-01 filtered</td> <td>Phase 2 if API adds filter; else hidden</td> </tr> <tr> <td>Delete role</td> <td>destructive-button</td> <td><button class=destructive></td> <td>DELETE /roles/{id}</td> <td>only non-seed with assignment_count 0</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Save</td> <td><code>PATCH /roles/{id} {description, permissions} (If-Match)</code></td> <td></td> </tr> <tr> <td>Delete</td> <td><code>DELETE /roles/{id}</code></td> <td>409 → still assigned</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="rol-03--new-role"><a class="anchor" href="#rol-03--new-role" aria-hidden="true" tabindex="-1">#</a>ROL-03 — New role</h3> <p><strong>Domain:</strong> D8 Roles & Permissions · <strong>Route:</strong> <code>/admin/roles/new</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> MVP<br><strong>Who:</strong> roles.manage<br><strong>Purpose:</strong> Define a custom role.</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Name</td> <td>text-field</td> <td><input type=text></td> <td>body.name</td> <td>^[a-z][a-z0-9_]{1,40}$; live validation</td> </tr> <tr> <td>Scope</td> <td>select</td> <td><select> / listbox popover</td> <td>body.scope</td> <td>platform or an application</td> </tr> <tr> <td>Description</td> <td>text-area</td> <td><textarea></td> <td>body.description</td> <td></td> </tr> <tr> <td>Permissions</td> <td>checkbox-list</td> <td>grouped checkbox list</td> <td>body.permissions</td> <td>≥ 1</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Create</td> <td><code>POST /roles</code></td> <td>409 → name taken in scope</td> </tr> </tbody></table></div> <h3 id="rol-04--user--roles"><a class="anchor" href="#rol-04--user--roles" aria-hidden="true" tabindex="-1">#</a>ROL-04 — User — Roles</h3> <p><strong>Domain:</strong> D8 Roles & Permissions · <strong>Route:</strong> <code>/admin/users/:userId/roles</code> · <strong>Archetype:</strong> tab · <strong>Phase:</strong> MVP<br><strong>Who:</strong> users.list (read), roles.manage (write)<br><strong>Purpose:</strong> Assign and remove roles for a user.</p> <p><strong>Web (PWA) container:</strong> <code>tabpanel</code> (route segment)</p> <p><strong>Loads:</strong> <code>GET /users/{id}/roles</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Rows</td> <td>list</td> <td>virtualized list</td> <td>UserRoleAssignment: role, application_id, assigned_at, assigned_by, implicit</td> <td>implicit → "Granted with app access", not removable</td> </tr> <tr> <td>Assign role</td> <td>button → role picker</td> <td>combobox multi-select</td> <td></td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Assign</td> <td><code>POST /users/{id}/roles/{roleId}</code></td> <td>idempotent; 200 already held</td> </tr> <tr> <td>Remove</td> <td><code>DELETE /users/{id}/roles/{roleId}</code></td> <td>409 → implicit role</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h2 id="d9--applications"><a class="anchor" href="#d9--applications" aria-hidden="true" tabindex="-1">#</a>D9 · Applications</h2> <h3 id="apl-01--applications"><a class="anchor" href="#apl-01--applications" aria-hidden="true" tabindex="-1">#</a>APL-01 — Applications</h3> <p><strong>Domain:</strong> D9 Applications · <strong>Route:</strong> <code>/dev/apps</code> · <strong>Archetype:</strong> list · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Any (catalog), owner/applications.manage (manage)<br><strong>Purpose:</strong> Applications you own or administer.</p> <p><strong>Web (PWA) container:</strong> List pane (resizable) + detail pane ≥ 768 px; single pane < 768 px</p> <p><strong>Loads:</strong> <code>GET /applications?owned=true (staff: all, filter review_status)</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Rows</td> <td>list</td> <td>virtualized list</td> <td>ApplicationSummary: icon, name, slug, visibility, review_status</td> <td></td> </tr> <tr> <td>Register app</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>→ APL-02</td> <td>applications.manage (Phase 3: self-service)</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="apl-02--register-application"><a class="anchor" href="#apl-02--register-application" aria-hidden="true" tabindex="-1">#</a>APL-02 — Register application</h3> <p><strong>Domain:</strong> D9 Applications · <strong>Route:</strong> <code>/dev/apps/new</code> · <strong>Archetype:</strong> wizard · <strong>Phase:</strong> MVP<br><strong>Who:</strong> applications.manage<br><strong>Purpose:</strong> Register a new application.</p> <p><strong>Web (PWA) container:</strong> Dialog/sheet with step indicator; each step a URL hash</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Name</td> <td>text-field</td> <td><input type=text></td> <td>name</td> <td></td> </tr> <tr> <td>Slug</td> <td>text-field</td> <td><input type=text></td> <td>slug</td> <td>^[a-z][a-z0-9-]{1,63}$; 'platform' reserved; immutable — warn</td> </tr> <tr> <td>Launch URL</td> <td>url-field</td> <td><input type=url></td> <td>launch_url</td> <td>https</td> </tr> <tr> <td>Redirect URIs</td> <td>url-list</td> <td>repeating <input type=url> rows + Add</td> <td>redirect_uris</td> <td></td> </tr> <tr> <td>Visibility</td> <td>radio-group</td> <td><fieldset> radios</td> <td>visibility public \| invite_only \| internal</td> <td></td> </tr> <tr> <td>Access tier</td> <td>radio-group</td> <td><fieldset> radios</td> <td>access_tier free \| standard (default standard)</td> <td>applications.manage only; explains who gets access</td> </tr> <tr> <td>Owner</td> <td>select</td> <td><select> / listbox popover</td> <td>owner_user_id \| owner_organization_id</td> <td></td> </tr> <tr> <td>Icon</td> <td>image-picker</td> <td><input type=file accept=image/* capture> + paste + drop</td> <td>icon_url</td> <td></td> </tr> <tr> <td>Support URL</td> <td>url-field</td> <td><input type=url></td> <td>support_url</td> <td></td> </tr> <tr> <td>Email from name</td> <td>text-field</td> <td><input type=text></td> <td>email_from_name</td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Register</td> <td><code>POST /applications (Idempotency-Key)</code></td> <td>409 slug taken; 422 field errors. Registration grants the platform-managed Entitlements its access_tier calls for.</td> </tr> </tbody></table></div> <h3 id="apl-03--application--overview"><a class="anchor" href="#apl-03--application--overview" aria-hidden="true" tabindex="-1">#</a>APL-03 — Application — Overview</h3> <p><strong>Domain:</strong> D9 Applications · <strong>Route:</strong> <code>/dev/apps/:appId</code> · <strong>Archetype:</strong> detail · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Owner (configure), applications.manage (anything)<br><strong>Purpose:</strong> Configure an application.</p> <p><strong>Web (PWA) container:</strong> Detail pane with header, tablist, toolbar; full page < 768 px</p> <p><strong>Loads:</strong> <code>GET /applications/{id}</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Header</td> <td>icon, name, id-chip, review StatusBadge</td> <td><code> + copy button</td> <td></td> <td></td> </tr> <tr> <td>Tabs</td> <td>tabs</td> <td>role=tablist</td> <td>Overview · Settings schema · Permissions & roles · Push · Keys · Webhooks · Access · Activity</td> <td>Push = APL-07; Keys/Webhooks/Access = KEY-01/WHK-01/ACX-05 filtered to app</td> </tr> <tr> <td>Fields</td> <td>settings rows</td> <td>settings rows</td> <td>name, description, launch_url, redirect_uris, support_url, email_from_name, icon_url (owner); visibility, access_tier (applications.manage)</td> <td>slug read-only with lock</td> </tr> <tr> <td>Platform alerts</td> <td>toggle</td> <td><button role=switch></td> <td>receives_platform_notifications</td> <td>owner-writable; explain that security/account alerts will push under this app's name and icon</td> </tr> <tr> <td>Review notes</td> <td>banner</td> <td>role=region banner</td> <td>review_status rejected/suspended + review_notes</td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Save field</td> <td><code>PATCH /applications/{id} (If-Match)</code></td> <td>422 → field errors</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="apl-04--settings-schema"><a class="anchor" href="#apl-04--settings-schema" aria-hidden="true" tabindex="-1">#</a>APL-04 — Settings schema</h3> <p><strong>Domain:</strong> D9 Applications · <strong>Route:</strong> <code>/dev/apps/:appId/schema</code> · <strong>Archetype:</strong> tab · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Owner / applications.manage<br><strong>Purpose:</strong> Declare per-user settings the app stores in Substratal.</p> <p><strong>Web (PWA) container:</strong> <code>tabpanel</code> (route segment)</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Properties</td> <td>list</td> <td>virtualized list</td> <td>settings_schema.properties: key, type, enum, default, min/max, maxLength</td> <td>add/edit via form</td> </tr> <tr> <td>JSON editor</td> <td>code-editor</td> <td>CodeMirror 6 (JSON)</td> <td>settings_schema</td> <td>JSON validation; diff before save</td> </tr> <tr> <td>Preview</td> <td>rendered SET-02 form</td> <td>SchemaForm preview</td> <td></td> <td>shows exactly what users will see</td> </tr> <tr> <td>Stats</td> <td>caption</td> <td><small></td> <td>settings_schema_stats</td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Save</td> <td><code>PATCH /applications/{id} {settings_schema}</code></td> <td>422 → schema rule errors</td> </tr> </tbody></table></div> <h3 id="apl-05--permissions--roles"><a class="anchor" href="#apl-05--permissions--roles" aria-hidden="true" tabindex="-1">#</a>APL-05 — Permissions & roles</h3> <p><strong>Domain:</strong> D9 Applications · <strong>Route:</strong> <code>/dev/apps/:appId/roles</code> · <strong>Archetype:</strong> tab · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Owner / applications.manage<br><strong>Purpose:</strong> Declare app permissions, available app roles and the default role.</p> <p><strong>Web (PWA) container:</strong> <code>tabpanel</code> (route segment)</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Permissions</td> <td>editable list</td> <td>role=grid virtualized table</td> <td>permissions[] {key, description}</td> <td>key app.<slug>.</td> </tr> <tr> <td>Available app roles</td> <td>token list</td> <td>token input (chips in input)</td> <td>available_app_roles (≤ 20)</td> <td></td> </tr> <tr> <td>Default app role</td> <td>select</td> <td><select> / listbox popover</td> <td>default_app_role</td> <td>held implicitly by everyone with access</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Save</td> <td><code>PATCH /applications/{id}</code></td> <td></td> </tr> </tbody></table></div> <h3 id="apl-06--review"><a class="anchor" href="#apl-06--review" aria-hidden="true" tabindex="-1">#</a>APL-06 — Review</h3> <p><strong>Domain:</strong> D9 Applications · <strong>Route:</strong> <code>/dev/apps/:appId/review</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> Phase 3<br><strong>Who:</strong> applications.manage<br><strong>Purpose:</strong> Staff moderation of an application.</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Review status</td> <td>radio-group</td> <td><fieldset> radios</td> <td>review_status</td> <td></td> </tr> <tr> <td>Notes</td> <td>text-area</td> <td><textarea></td> <td>review_notes</td> <td>visible to owner</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Save</td> <td><code>PATCH /applications/{id} {review_status, review_notes}</code></td> <td></td> </tr> </tbody></table></div> <h3 id="apl-07--push-credentials"><a class="anchor" href="#apl-07--push-credentials" aria-hidden="true" tabindex="-1">#</a>APL-07 — Push credentials</h3> <p><strong>Domain:</strong> D9 Applications · <strong>Route:</strong> <code>/dev/apps/:appId/push</code> · <strong>Archetype:</strong> tab · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Owner or applications.manage with a User token (write); app key / owner (read)<br><strong>Purpose:</strong> Configure APNs, FCM and Web Push for an Application so it can send push notifications.</p> <p><strong>Web (PWA) container:</strong> <code>tabpanel</code> (route segment)</p> <p><strong>Loads:</strong> <code>GET /applications/{id}/push-credentials</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Providers</td> <td>list</td> <td>virtualized list</td> <td>PushCredential per provider apns \| fcm \| web_push: status active\|failed, failure_reason, failed_at, last_used_at; apns team_id/key_id/topic; fcm project_id/client_email; web_push subject + vapid_public_key</td> <td>one row per provider with Add / Edit / Remove; failed → warning banner with reason and Fix</td> </tr> <tr> <td>Add APNs</td> <td>form</td> <td><dialog> form / bottom sheet</td> <td>POST body: provider apns, team_id (10), key_id (10), topic (bundle id), private_key (.p8)</td> <td>file picker / drop / paste for the .p8; key never shown again</td> </tr> <tr> <td>Add FCM</td> <td>form</td> <td><dialog> form / bottom sheet</td> <td>POST body: provider fcm, service_account (JSON file)</td> <td>drop/pick the downloaded JSON; validate shape client-side</td> </tr> <tr> <td>Add Web Push</td> <td>form</td> <td><dialog> form / bottom sheet</td> <td>POST body: provider web_push, subject (mailto:/https:)</td> <td>platform generates VAPID keys; show vapid_public_key with Copy for the web client</td> </tr> <tr> <td>Rotate / fix</td> <td>form</td> <td><dialog> form / bottom sheet</td> <td>PATCH /applications/{id}/push-credentials/{provider} {key material \| status: active}</td> <td>web_push can't rotate in place — explain delete + recreate</td> </tr> <tr> <td>Remove</td> <td>destructive-button</td> <td><button class=destructive></td> <td>DELETE /applications/{id}/push-credentials/{provider}</td> <td>confirm; web_push removal deactivates every browser subscription</td> </tr> <tr> <td>Platform alerts</td> <td>toggle</td> <td><button role=switch></td> <td>Application.receives_platform_notifications</td> <td>mirror of APL-03 toggle</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Add</td> <td><code>POST /applications/{id}/push-credentials</code></td> <td>201; 409 push_credential_exists → Edit; 422 invalid_push_credential → field error; 400 user_token_required never happens in the Hub (User token)</td> </tr> <tr> <td>Fetch one</td> <td><code>GET /applications/{id}/push-credentials/{provider}</code></td> <td>on Edit</td> </tr> <tr> <td>Save</td> <td><code>PATCH /applications/{id}/push-credentials/{provider}</code></td> <td>409 invalid_status_transition</td> </tr> <tr> <td>Remove</td> <td><code>DELETE /applications/{id}/push-credentials/{provider}</code></td> <td>204</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <p><strong>Notes:</strong> To prove a credential end to end, the owner registers a device of their own app and uses its device test (NTF-03 lists only devices the owner holds).</p> <h2 id="d10--developer-credentials"><a class="anchor" href="#d10--developer-credentials" aria-hidden="true" tabindex="-1">#</a>D10 · Developer Credentials</h2> <h3 id="key-01--api-keys"><a class="anchor" href="#key-01--api-keys" aria-hidden="true" tabindex="-1">#</a>KEY-01 — API keys</h3> <p><strong>Domain:</strong> D10 Developer Credentials · <strong>Route:</strong> <code>/dev/keys</code> · <strong>Archetype:</strong> table · <strong>Phase:</strong> MVP<br><strong>Who:</strong> api_keys.manage or app owner<br><strong>Purpose:</strong> Service and agent credentials.</p> <p><strong>Web (PWA) container:</strong> Virtualized grid table ≥ 1024 px; card rows below</p> <p><strong>Loads:</strong> <code>GET /api-keys?scope&mode&intended_use&include_inactive</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Filters</td> <td>chips</td> <td>toggle-button chip row</td> <td>mode live\|test, intended_use, include revoked</td> <td>TEST pill on test keys</td> </tr> <tr> <td>Columns</td> <td>table</td> <td>role=grid virtualized table</td> <td>name, scope, secret_hint, mode, intended_use, restrict_destructive, last_used_at, expires_at, status(revoked_at)</td> <td></td> </tr> <tr> <td>Create key</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>→ KEY-02</td> <td></td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="key-02--create-api-key"><a class="anchor" href="#key-02--create-api-key" aria-hidden="true" tabindex="-1">#</a>KEY-02 — Create API key</h3> <p><strong>Domain:</strong> D10 Developer Credentials · <strong>Route:</strong> <code>/dev/keys/new</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> MVP<br><strong>Who:</strong> api_keys.manage or app owner (app-scoped)<br><strong>Purpose:</strong> Create a key with least-privilege permissions.</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Name</td> <td>text-field</td> <td><input type=text></td> <td>name</td> <td></td> </tr> <tr> <td>Scope</td> <td>select</td> <td><select> / listbox popover</td> <td>scope platform \| application</td> <td>owners: own apps only</td> </tr> <tr> <td>Mode</td> <td>segmented</td> <td>role=radiogroup segmented buttons</td> <td>mode live \| test</td> <td>fixed after creation — say so</td> </tr> <tr> <td>Used by</td> <td>radio-group</td> <td><fieldset> radios</td> <td>intended_use service \| agent</td> <td>agent defaults restrict_destructive on</td> </tr> <tr> <td>Block destructive operations</td> <td>toggle</td> <td><button role=switch></td> <td>restrict_destructive</td> <td></td> </tr> <tr> <td>Permissions</td> <td>checkbox-list</td> <td>grouped checkbox list</td> <td>permissions</td> <td>filtered by scope via GET /permissions; app-scoped keys offer the five app-confined platform permissions incl. notifications.send</td> </tr> <tr> <td>Expires</td> <td>date-field</td> <td><input type=date\|datetime-local></td> <td>expires_at</td> <td>optional; presets 30/90/365 days</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Create</td> <td><code>POST /api-keys</code></td> <td>201 ApiKeyWithSecret → KEY-03</td> </tr> </tbody></table></div> <h3 id="key-03--secret-reveal"><a class="anchor" href="#key-03--secret-reveal" aria-hidden="true" tabindex="-1">#</a>KEY-03 — Secret reveal</h3> <p><strong>Domain:</strong> D10 Developer Credentials · <strong>Route:</strong> <code>(modal)</code> · <strong>Archetype:</strong> secret · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Creator<br><strong>Purpose:</strong> Show a new API key secret, webhook signing secret, or recovery codes exactly once.</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code>, <code>cancel</code> prevented, no Esc</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Secret</td> <td>monospace selectable text</td> <td><code> with user-select:all</td> <td>secret</td> <td>never logged, never persisted, excluded from screenshots where the OS allows</td> </tr> <tr> <td>Copy</td> <td>button</td> <td><button></td> <td>clipboard (sensitive)</td> <td>auto-clear after 60 s where supported</td> </tr> <tr> <td>Acknowledge</td> <td>checkbox</td> <td><input type=checkbox></td> <td>client</td> <td>gates Done; modal not dismissible until checked</td> </tr> </tbody></table></div> <h3 id="key-04--api-key-detail"><a class="anchor" href="#key-04--api-key-detail" aria-hidden="true" tabindex="-1">#</a>KEY-04 — API key detail</h3> <p><strong>Domain:</strong> D10 Developer Credentials · <strong>Route:</strong> <code>/dev/keys/:keyId</code> · <strong>Archetype:</strong> detail · <strong>Phase:</strong> MVP<br><strong>Who:</strong> api_keys.manage or app owner<br><strong>Purpose:</strong> Edit, rotate or revoke a key.</p> <p><strong>Web (PWA) container:</strong> Detail pane with header, tablist, toolbar; full page < 768 px</p> <p><strong>Loads:</strong> <code>GET /api-keys/{id}</code> · <code>GET /audit-events?actor_id={id}</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Fields</td> <td>settings rows</td> <td>settings rows</td> <td>name, permissions, restrict_destructive (editable); scope, mode, intended_use, expires_at, created_by, last_used_at (read-only)</td> <td></td> </tr> <tr> <td>Rotate</td> <td>button</td> <td><button></td> <td>POST /api-keys/{id}/rotate</td> <td>confirm: no overlap</td> </tr> <tr> <td>Revoke</td> <td>destructive-button</td> <td><button class=destructive></td> <td>DELETE /api-keys/{id}</td> <td>confirm</td> </tr> <tr> <td>Recent activity</td> <td>list</td> <td>virtualized list</td> <td>audit events by this key</td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Save</td> <td><code>PATCH /api-keys/{id}</code></td> <td></td> </tr> <tr> <td>Rotate</td> <td><code>POST …/rotate</code></td> <td>200 → KEY-03</td> </tr> <tr> <td>Revoke</td> <td><code>DELETE /api-keys/{id}</code></td> <td>204 → row shows Revoked</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="whk-01--webhooks"><a class="anchor" href="#whk-01--webhooks" aria-hidden="true" tabindex="-1">#</a>WHK-01 — Webhooks</h3> <p><strong>Domain:</strong> D10 Developer Credentials · <strong>Route:</strong> <code>/dev/webhooks</code> · <strong>Archetype:</strong> list · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> webhooks.manage or app owner<br><strong>Purpose:</strong> Endpoints that receive access-change events.</p> <p><strong>Web (PWA) container:</strong> List pane (resizable) + detail pane ≥ 768 px; single pane < 768 px</p> <p><strong>Loads:</strong> <code>GET /webhooks?application_id</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Rows</td> <td>list</td> <td>virtualized list</td> <td>Webhook: url, events count, status healthy\|unhealthy\|disabled, consecutive_failures, last_delivery_at, scope</td> <td></td> </tr> <tr> <td>Add webhook</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>→ WHK-02</td> <td></td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="whk-02--add--edit-webhook"><a class="anchor" href="#whk-02--add--edit-webhook" aria-hidden="true" tabindex="-1">#</a>WHK-02 — Add / edit webhook</h3> <p><strong>Domain:</strong> D10 Developer Credentials · <strong>Route:</strong> <code>/dev/webhooks/new</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> webhooks.manage or app owner<br><strong>Purpose:</strong> Subscribe a URL to events.</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>URL</td> <td>url-field</td> <td><input type=url></td> <td>url</td> <td>https required</td> </tr> <tr> <td>Events</td> <td>checkbox-list grouped</td> <td>grouped checkbox list</td> <td>events (WebhookEvent enum: access.<em>, entitlement.</em>, role.<em>, user.</em>, organization.<em>, application.</em>, device., notification.push_failed, push_credential.failed, webhook.test)</td> <td>presets: Access changes (access.granted, access.revoked) · Push health (notification.push_failed, push_credential.failed, device.deactivated)</td> </tr> <tr> <td>Description</td> <td>text-field</td> <td><input type=text></td> <td>description</td> <td></td> </tr> <tr> <td>Scope</td> <td>select</td> <td><select> / listbox popover</td> <td>scope</td> <td></td> </tr> <tr> <td>API version</td> <td>select</td> <td><select> / listbox popover</td> <td>api_version</td> <td>edit only</td> </tr> <tr> <td>Enabled</td> <td>toggle</td> <td><button role=switch></td> <td>status disabled ↔ healthy</td> <td>edit only (re-enable)</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Create</td> <td><code>POST /webhooks</code></td> <td>201 WebhookWithSecret → KEY-03</td> </tr> <tr> <td>Save</td> <td><code>PATCH /webhooks/{id}</code></td> <td></td> </tr> </tbody></table></div> <h3 id="whk-03--webhook--deliveries"><a class="anchor" href="#whk-03--webhook--deliveries" aria-hidden="true" tabindex="-1">#</a>WHK-03 — Webhook — Deliveries</h3> <p><strong>Domain:</strong> D10 Developer Credentials · <strong>Route:</strong> <code>/dev/webhooks/:hookId</code> · <strong>Archetype:</strong> detail · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> webhooks.manage or app owner<br><strong>Purpose:</strong> Delivery history, testing and secret rotation.</p> <p><strong>Web (PWA) container:</strong> Detail pane with header, tablist, toolbar; full page < 768 px</p> <p><strong>Loads:</strong> <code>GET /webhooks/{id}</code> · <code>GET /webhooks/{id}/deliveries?status&since&event_id</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Header actions</td> <td>toolbar</td> <td>toolbar (role=toolbar)</td> <td></td> <td>Send test · Rotate secret · Edit · Delete</td> </tr> <tr> <td>Filter</td> <td>chips</td> <td>toggle-button chip row</td> <td>status pending\|succeeded\|failed</td> <td></td> </tr> <tr> <td>Rows</td> <td>table</td> <td>role=grid virtualized table</td> <td>WebhookDelivery: status, response_status, event_type, event_id, attempt, duration_ms, created_at, next_retry_at, error</td> <td>failed → Redeliver</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Send test</td> <td><code>POST /webhooks/{id}/test</code></td> <td>202 → new pending row appears on refresh (poll 2 s × 5)</td> </tr> <tr> <td>Rotate secret</td> <td><code>POST /webhooks/{id}/rotate-secret</code></td> <td>confirm (24 h overlap) → KEY-03</td> </tr> <tr> <td>Redeliver</td> <td><code>POST /webhooks/{id}/deliveries/{deliveryId}/redeliver</code></td> <td>202 toast; same event_id</td> </tr> <tr> <td>Delete</td> <td><code>DELETE /webhooks/{id}</code></td> <td>confirm</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="whk-04--delivery-detail"><a class="anchor" href="#whk-04--delivery-detail" aria-hidden="true" tabindex="-1">#</a>WHK-04 — Delivery detail</h3> <p><strong>Domain:</strong> D10 Developer Credentials · <strong>Route:</strong> <code>/dev/webhooks/:hookId/deliveries/:deliveryId</code> · <strong>Archetype:</strong> popover · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> webhooks.manage or app owner<br><strong>Purpose:</strong> One delivery attempt in detail.</p> <p><strong>Web (PWA) container:</strong> Popover ≥ 1024 px; side panel 768–1023; bottom sheet < 768</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Facts</td> <td>key-value</td> <td><dl></td> <td>all WebhookDelivery fields</td> <td></td> </tr> <tr> <td>Redeliver</td> <td>button</td> <td><button></td> <td></td> <td></td> </tr> </tbody></table></div> <h2 id="d11--plan--billing"><a class="anchor" href="#d11--plan--billing" aria-hidden="true" tabindex="-1">#</a>D11 · Plan & Billing</h2> <h3 id="bil-01--my-plan"><a class="anchor" href="#bil-01--my-plan" aria-hidden="true" tabindex="-1">#</a>BIL-01 — My plan</h3> <p><strong>Domain:</strong> D11 Plan & Billing · <strong>Route:</strong> <code>/billing</code> · <strong>Archetype:</strong> settings · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Self; billing.manage can view any User's (read-only)<br><strong>Purpose:</strong> Free or Standard: what covers you, your own subscription, upgrade and manage billing.</p> <p><strong>Web (PWA) container:</strong> Grouped settings rows in main pane</p> <p><strong>Loads:</strong> <code>GET /users/me/subscription</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Plan card</td> <td>card</td> <td><section class=card></td> <td>UserSubscription.plan free\|standard</td> <td>Free: "Free apps and services"; Standard: "Every app and service"</td> </tr> <tr> <td>Covered by</td> <td>list</td> <td>virtualized list</td> <td>plan_sources[]: {type user\|organization, id}</td> <td>"Your subscription" / "Northwind Survey Co." (→ ORG-03); both listed when doubly covered</td> </tr> <tr> <td>Double coverage tip</td> <td>banner</td> <td>role=region banner</td> <td>plan_sources has both user and organization</td> <td>"Your organization already covers you. You can cancel your own subscription in Manage billing." (no automatic refund)</td> </tr> <tr> <td>Your subscription</td> <td>key-value</td> <td><dl></td> <td>Subscription.status, current_period_end, cancel_at_period_end, unit_amount, currency</td> <td>status badge via status-semantics; past_due → warning banner (Stripe retries ~3 weeks)</td> </tr> <tr> <td>Upgrade to Standard</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>→ BIL-03 checkout</td> <td>when no covering subscription, or own subscription is incomplete/incomplete_expired/canceled/unpaid; price "$6 per month" from unit_amount when known, else from pricing config; store flags on iOS/Android</td> </tr> <tr> <td>Manage billing</td> <td>button</td> <td><button></td> <td>→ BIL-03 portal</td> <td>when the user has completed a checkout (own subscription exists and isn't incomplete)</td> </tr> <tr> <td>What Standard includes</td> <td>link</td> <td><a> / <button class=link></td> <td>standard apps from GET /applications?access_tier=standard</td> <td>count + list</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES; After return from checkout: poll GET /users/me/subscription every 2 s (max 30 s) until plan = standard, showing "Finishing up…"; Downgraded: "Your Standard access ended on {date}. Your data is kept."</p> <p><strong>Notes:</strong> Business/Enterprise aren't offered (422 plan_requires_sales); show "Contact sales" link only. Annual plans and a Standard trial are undecided in the API (DECISIONS #31) — no UI for them.</p> <h3 id="bil-02--organization-subscription"><a class="anchor" href="#bil-02--organization-subscription" aria-hidden="true" tabindex="-1">#</a>BIL-02 — Organization subscription</h3> <p><strong>Domain:</strong> D11 Plan & Billing · <strong>Route:</strong> <code>/orgs/:orgId/subscription</code> · <strong>Archetype:</strong> tab · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> org_admin (manage); billing.manage (read + portal)<br><strong>Purpose:</strong> An organization's Standard subscription and which members it covers.</p> <p><strong>Web (PWA) container:</strong> <code>tabpanel</code> (route segment)</p> <p><strong>Loads:</strong> <code>GET /organizations/{id}/subscription</code> · <code>GET /organizations/{id}/members (for the member picker)</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Plan card</td> <td>card</td> <td><section class=card></td> <td>OrganizationSubscription.plan + Subscription.status, current_period_end, cancel_at_period_end</td> <td></td> </tr> <tr> <td>Billed users</td> <td>key-value</td> <td><dl></td> <td>quantity.current (live), quantity.last_synced + last_synced_at, unit_amount</td> <td>"31 covered · 30 billed on next invoice (synced daily)"</td> </tr> <tr> <td>Who's covered</td> <td>radio-group</td> <td><fieldset> radios</td> <td>member_scope all_members \| allowlist \| denylist</td> <td>COPY labels</td> </tr> <tr> <td>Members</td> <td>member-picker</td> <td>combobox multi-select</td> <td>member_overrides (active members only)</td> <td>visible for allowlist/denylist</td> </tr> <tr> <td>Subscribe the organization</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>→ BIL-03 org checkout (member_scope optional)</td> <td>org_admin; when no subscription or not in force</td> </tr> <tr> <td>Manage billing</td> <td>button</td> <td><button></td> <td>→ BIL-03 org portal</td> <td>org_admin or billing.manage</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Save coverage</td> <td><code>PATCH /organizations/{id}/subscription {member_scope, member_overrides} (If-Match)</code></td> <td>effective immediately (access.granted/revoked); billed from next daily sync. 422 member_override_not_a_member → mark rows. 404 subscription_not_found → show Subscribe.</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <p><strong>Notes:</strong> Members gained or lost take effect at once; say so before saving.</p> <h3 id="bil-03--checkout--billing-portal"><a class="anchor" href="#bil-03--checkout--billing-portal" aria-hidden="true" tabindex="-1">#</a>BIL-03 — Checkout / billing portal</h3> <p><strong>Domain:</strong> D11 Plan & Billing · <strong>Route:</strong> <code>/billing/return</code> · <strong>Archetype:</strong> handoff · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Self (individual); org_admin (org checkout); org_admin or billing.manage (org portal)<br><strong>Purpose:</strong> Hand off to Stripe in the browser and confirm the result on return.</p> <p><strong>Web (PWA) container:</strong> <code>window.open</code> (new tab) / same-tab redirect for PKCE</p> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Upgrade (individual)</td> <td><code>POST /users/me/billing/checkout-sessions {plan:standard, success_url, cancel_url} (Idempotency-Key)</code></td> <td>201 {url, expires_at} → open url externally. 409 subscription_exists → open portal instead. 409 test_mode_billing_unavailable / 503 billing_unavailable → explain.</td> </tr> <tr> <td>Manage billing (individual)</td> <td><code>POST /users/me/billing/portal-sessions {return_url}</code></td> <td>201 → open url externally. 409 no_billing_account → hide button.</td> </tr> <tr> <td>Subscribe organization</td> <td><code>POST /organizations/{id}/billing/checkout-sessions {plan:standard, success_url, cancel_url, member_scope?, member_overrides?} (Idempotency-Key)</code></td> <td>as individual</td> </tr> <tr> <td>Manage organization billing</td> <td><code>POST /organizations/{id}/billing/portal-sessions {return_url}</code></td> <td>as individual</td> </tr> <tr> <td>Return</td> <td><code>deep link /billing/return?checkout=success\|cancelled (or /orgs/:orgId/subscription?…)</code></td> <td>success: poll the matching GET …/subscription until plan = standard (coverage starts when Stripe's webhook lands, usually seconds); cancelled: toast "Checkout cancelled"</td> </tr> </tbody></table></div> <p><strong>Notes:</strong> success_url / cancel_url / return_url must be https: use <a href="https://dashboard.substratalapps.com/billing/return…" rel="noopener">https://dashboard.substratalapps.com/billing/return…</a> (Universal/App Links open the native app).</p> <h3 id="bil-04--tenant--infrastructure"><a class="anchor" href="#bil-04--tenant--infrastructure" aria-hidden="true" tabindex="-1">#</a>BIL-04 — Tenant & infrastructure</h3> <p><strong>Domain:</strong> D11 Plan & Billing · <strong>Route:</strong> <code>/dev/tenant</code> · <strong>Archetype:</strong> detail · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Tenant owner (read), tenants.manage (write)<br><strong>Purpose:</strong> Where an Application owner's data lives, and support-run tier changes. Tenants aren't billed.</p> <p><strong>Web (PWA) container:</strong> Detail pane with header, tablist, toolbar; full page < 768 px</p> <p><strong>Loads:</strong> <code>GET /tenants</code> · <code>GET /tenants/{id}</code> · <code>GET /tenants/{id}/tier-change-requests</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Facts</td> <td>key-value</td> <td><dl></td> <td>Tenant: tier, region, status, owner, application_count</td> <td>status migrating → banner, writes may 503</td> </tr> <tr> <td>Tier change requests</td> <td>list</td> <td>virtualized list</td> <td>TenantTierChangeRequest: from→requested tier/region, status, scheduled_for, reason, notes</td> <td></td> </tr> <tr> <td>Request change</td> <td>button</td> <td><button></td> <td>→ form: requested_tier, requested_region, reason</td> <td>tenants.manage only; owners see "isolated and dedicated-region tiers come with business pricing — contact sales"</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Open request</td> <td><code>POST /tenants/{id}/tier-change-requests</code></td> <td>422/409 errors</td> </tr> <tr> <td>Open request detail</td> <td><code>GET /tenants/{id}/tier-change-requests/{requestId}</code></td> <td>polls every 30 s while visible</td> </tr> <tr> <td>Advance request</td> <td><code>PATCH /tenants/{id}/tier-change-requests/{requestId} {status, scheduled_for, notes} (If-Match)</code></td> <td>staff only; status scheduled → in_progress → completed, or cancelled</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h2 id="d12--audit-log"><a class="anchor" href="#d12--audit-log" aria-hidden="true" tabindex="-1">#</a>D12 · Audit Log</h2> <h3 id="aud-01--audit-log"><a class="anchor" href="#aud-01--audit-log" aria-hidden="true" tabindex="-1">#</a>AUD-01 — Audit log</h3> <p><strong>Domain:</strong> D12 Audit Log · <strong>Route:</strong> <code>/admin/audit</code> · <strong>Archetype:</strong> table · <strong>Phase:</strong> MVP<br><strong>Who:</strong> audit.view<br><strong>Purpose:</strong> Who changed what, when.</p> <p><strong>Web (PWA) container:</strong> Virtualized grid table ≥ 1024 px; card rows below</p> <p><strong>Loads:</strong> <code>GET /audit-events?since&until&actor_type&actor_id&action&target_type&target_id&target_user_id&application_id&organization_id&tenant_id</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Filters</td> <td>search + menus</td> <td><input type=search role=searchbox></td> <td>time range (presets 1h/24h/7d/custom), actor type, action (grouped by prefix, wildcard), resource</td> <td>filters encoded in URL/state for sharing</td> </tr> <tr> <td>Rows</td> <td>table</td> <td>role=grid virtualized table</td> <td>timestamp, actor (type icon + name/id), action, target (type + link), app/org</td> <td>relative time with absolute on hover/long-press</td> </tr> <tr> <td>Inspector</td> <td>side panel</td> <td>resizable side panel</td> <td>→ AUD-02</td> <td>desktop: trailing pane; compact: push</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <p><strong>Notes:</strong> Hot window is one year for every Tenant; read the <code>Audit-Hot-Window-Start</code> response header and show it in an info caption. Export is Phase 3. New actions to group in the filter: subscription.<em>, push_credential.</em>, device.deleted.</p> <h3 id="aud-02--audit-event"><a class="anchor" href="#aud-02--audit-event" aria-hidden="true" tabindex="-1">#</a>AUD-02 — Audit event</h3> <p><strong>Domain:</strong> D12 Audit Log · <strong>Route:</strong> <code>/admin/audit/:eventId</code> · <strong>Archetype:</strong> popover · <strong>Phase:</strong> MVP<br><strong>Who:</strong> audit.view<br><strong>Purpose:</strong> One event with before/after diff.</p> <p><strong>Web (PWA) container:</strong> Popover ≥ 1024 px; side panel 768–1023; bottom sheet < 768</p> <p><strong>Loads:</strong> <code>GET /audit-events/{id}</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Facts</td> <td>key-value</td> <td><dl></td> <td>action, actor, target, target_user_id, application_id, organization_id, tenant_id, request_id, timestamp</td> <td>each id links to its screen</td> </tr> <tr> <td>Diff</td> <td>diff view</td> <td><pre> diff with ins/del</td> <td>before / after</td> <td>JSON diff, changed keys highlighted</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h2 id="d13--notifications"><a class="anchor" href="#d13--notifications" aria-hidden="true" tabindex="-1">#</a>D13 · Notifications</h2> <h3 id="ntf-01--inbox"><a class="anchor" href="#ntf-01--inbox" aria-hidden="true" tabindex="-1">#</a>NTF-01 — Inbox</h3> <p><strong>Domain:</strong> D13 Notifications · <strong>Route:</strong> <code>/inbox</code> · <strong>Archetype:</strong> list · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Self<br><strong>Purpose:</strong> Every notification the person has received — from every app and from Substratal — with read and archived state.</p> <p><strong>Web (PWA) container:</strong> List pane (resizable) + detail pane ≥ 768 px; single pane < 768 px</p> <p><strong>Entry points:</strong> Bell in the toolbar / Inbox in the sidebar (desktop) / Inbox tab (compact); Tapping a push; Badges (app icon, Dock/taskbar, PWA)</p> <p><strong>Loads:</strong> <code>GET /users/me/notifications?state&application_id&source&category&priority&created_after&created_before&include_inactive</code> · <code>GET /users/me/notifications/unread-count</code> · <code>GET /applications (names, icons)</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Filter</td> <td>segmented</td> <td>role=radiogroup segmented buttons</td> <td>Unread · All · Archived (state)</td> <td>default All (unarchived)</td> </tr> <tr> <td>App filter</td> <td>menu</td> <td>menu button (role=menu)</td> <td>application_id, source=platform ("Substratal")</td> <td>per-app unread counts from unread-count.applications[]</td> </tr> <tr> <td>Rows</td> <td>list</td> <td>virtualized list</td> <td>Notification: app icon (or Substratal mark for source=platform), title, body (2 lines), category, priority high → "Important" marker, created_at relative, unread dot</td> <td>grouped Today / Yesterday / Earlier; high priority security.* rows show a shield icon</td> </tr> <tr> <td>Mark all as read</td> <td>button</td> <td><button></td> <td>POST /users/me/notifications/mark-read {before: newest loaded created_at, application_id?}</td> <td>respects current app filter; uses <code>before</code> so items arriving now aren't swept</td> </tr> <tr> <td>Multi-select</td> <td>selection</td> <td><select> / listbox popover</td> <td></td> <td>bulk Mark read / Mark unread / Archive (one PATCH per row)</td> </tr> <tr> <td>Row actions</td> <td>row-button</td> <td>trailing button</td> <td>PATCH /users/me/notifications/{notificationId} {state}</td> <td>swipe/hover: Read ⇄ Unread, Archive</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Open row</td> <td><code>→ NTF-02 and PATCH {state:read}</code></td> <td>optimistic; badge decrements</td> </tr> <tr> <td>Archive</td> <td><code>PATCH /users/me/notifications/{notificationId} {state:archived}</code></td> <td>toast with Undo (PATCH state:read)</td> </tr> <tr> <td>Mark read / unread</td> <td><code>PATCH /users/me/notifications/{notificationId} {state}</code></td> <td></td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES; Empty: "You're all caught up"; Feature off (501 not_implemented): hide Inbox entry points; badges fall back to none; Retention: items older than 90 days disappear (caption in empty Archived view)</p> <p><strong>Notes:</strong> The Inbox shows notifications from every Application plus platform alerts, but push banners for another app's notifications arrive through that app's own install — the Hub only pushes its own (<code>app_hub</code>) notifications and platform alerts.</p> <h3 id="ntf-02--notification"><a class="anchor" href="#ntf-02--notification" aria-hidden="true" tabindex="-1">#</a>NTF-02 — Notification</h3> <p><strong>Domain:</strong> D13 Notifications · <strong>Route:</strong> <code>/inbox/:notificationId</code> · <strong>Archetype:</strong> popover · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Self (users.list via NTF-05)<br><strong>Purpose:</strong> One notification in full, with where it leads and how its push went.</p> <p><strong>Web (PWA) container:</strong> Popover ≥ 1024 px; side panel 768–1023; bottom sheet < 768</p> <p><strong>Loads:</strong> <code>GET /users/me/notifications/{notificationId}</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Header</td> <td>icon + app name + time</td> <td>img + heading + badge</td> <td>application_id / source, created_at</td> <td></td> </tr> <tr> <td>Title & body</td> <td>text</td> <td><p></td> <td>title, body</td> <td>full text</td> </tr> <tr> <td>Open</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>action_url</td> <td>Hub route → navigate in-app; https → open in browser / installed app (Universal/App Link); private scheme → hand to OS; hidden when null</td> </tr> <tr> <td>Contextual actions</td> <td>buttons</td> <td><button></td> <td>by category</td> <td>security.new_sign_in → "Review sessions" (ACC-04) · security.password_changed / email_changed / mfa_disabled / session_reuse_detected → "Secure my account" (ACC-04) · account.organization_invitation → Accept / Decline (ORG-09) · account.access_granted → Open app (APP-03)</td> </tr> <tr> <td>Delivery</td> <td>disclosure</td> <td><details></td> <td>push.status, devices_targeted/sent/failed, skip_reason, deliveries[] (30 days)</td> <td>plain-language: "Pushed to 2 devices", "Not pushed — notifications are off for this app"</td> </tr> <tr> <td>Mark unread / Archive</td> <td>toolbar</td> <td>toolbar (role=toolbar)</td> <td>PATCH {state}</td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Opened</td> <td><code>PATCH /users/me/notifications/{notificationId} {state:read}</code></td> <td>on open if unread</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="ntf-03--devices--notifications"><a class="anchor" href="#ntf-03--devices--notifications" aria-hidden="true" tabindex="-1">#</a>NTF-03 — Devices & notifications</h3> <p><strong>Domain:</strong> D13 Notifications · <strong>Route:</strong> <code>/account/devices</code> · <strong>Archetype:</strong> settings · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Self<br><strong>Purpose:</strong> Where push notifications reach this person, and controls for this device.</p> <p><strong>Web (PWA) container:</strong> Grouped settings rows in main pane</p> <p><strong>Loads:</strong> <code>GET /users/me/devices?include_inactive=true</code> · <code>GET /users/me/settings (notifications.push)</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>This device</td> <td>card</td> <td><section class=card></td> <td>Hub Device for this install (matched by stored device id)</td> <td>status, "Notifications are on" / off / blocked by OS; button Turn on (→ NTF-04) or Turn off</td> </tr> <tr> <td>Push notifications (all apps)</td> <td>toggle</td> <td><button role=switch></td> <td>Settings.notifications.push</td> <td>same control as SET-01</td> </tr> <tr> <td>Devices</td> <td>list</td> <td>virtualized list</td> <td>Device: name, application_id (app icon), provider, environment, status, inactive_reason, last_registered_at, last_delivery_at, token_hint</td> <td>grouped by app; inactive rows dimmed with reason ("Signed out", "Not opened in 9 months"…)</td> </tr> <tr> <td>Rename</td> <td>row-button</td> <td>trailing button</td> <td>PATCH /users/me/devices/{deviceId} {name}</td> <td></td> </tr> <tr> <td>Send test notification</td> <td>row-button</td> <td>trailing button</td> <td>POST /users/me/devices/{deviceId}/test</td> <td>Hub devices only; shows provider result inline (sent / failed + error) within 10 s</td> </tr> <tr> <td>Remove</td> <td>row-button</td> <td>trailing button</td> <td>DELETE /users/me/devices/{deviceId}</td> <td>confirm; that install stops receiving pushes until it registers again</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Turn off on this device</td> <td><code>DELETE /users/me/devices/{deviceId}</code></td> <td>and stop re-registering until the user turns it back on</td> </tr> <tr> <td>Test</td> <td><code>POST /users/me/devices/{deviceId}/test</code></td> <td>429 → "Try again later (10 tests per hour)"; 409 push_not_configured → "Push isn't set up for this app yet"</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <p><strong>Notes:</strong> Device tokens are never displayed (only token_hint).</p> <h3 id="ntf-04--turn-on-notifications"><a class="anchor" href="#ntf-04--turn-on-notifications" aria-hidden="true" tabindex="-1">#</a>NTF-04 — Turn on notifications</h3> <p><strong>Domain:</strong> D13 Notifications · <strong>Route:</strong> <code>/account/devices/enable</code> · <strong>Archetype:</strong> wizard · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> Self<br><strong>Purpose:</strong> Explain, request the OS permission, and register this install for push.</p> <p><strong>Web (PWA) container:</strong> Dialog/sheet with step indicator; each step a URL hash</p> <p><strong>Entry points:</strong> First time a notification-worthy moment happens (org invite, first launch after sign-in on mobile, enabling in NTF-03/SET-01) — never on cold start before sign-in</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Primer</td> <td>text + illustration</td> <td><p></td> <td></td> <td>what you'll get: security alerts, invitations, access changes; "You can change this anytime"</td> </tr> <tr> <td>Turn on</td> <td>primary-button</td> <td><button class=primary type=submit></td> <td>OS permission prompt</td> <td>platform API per PLATFORM-SPEC</td> </tr> <tr> <td>Not now</td> <td>button</td> <td><button></td> <td></td> <td>snooze 14 days</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Permission granted</td> <td><code>POST /users/me/devices {application_id: app_hub, provider, token \| subscription, environment (apns), name, app_version}</code></td> <td>201 new / 200 refresh → store device id; 403 entitlement_required → Hub access disabled for this user: show inbox-only mode; 422 invalid_device_token → log + retry next launch</td> </tr> <tr> <td>Token rotated by OS</td> <td><code>PATCH /users/me/devices/{deviceId} {token \| subscription}</code></td> <td></td> </tr> <tr> <td>Permission denied</td> <td><code>—</code></td> <td>Settings shows "Blocked — Open system settings" deep link</td> </tr> </tbody></table></div> <p><strong>Notes:</strong> Re-register on launch at most once a day (keeps the device from going stale after 270 days). Windows and Linux have no supported push provider in the API: this screen is replaced by an in-app explanation and local notifications from polling (see their PLATFORM-SPEC).</p> <h3 id="ntf-05--user--notifications--devices"><a class="anchor" href="#ntf-05--user--notifications--devices" aria-hidden="true" tabindex="-1">#</a>NTF-05 — User — Notifications & devices</h3> <p><strong>Domain:</strong> D13 Notifications · <strong>Route:</strong> <code>/admin/users/:userId/notifications</code> · <strong>Archetype:</strong> tab · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> users.list (read), users.manage (delete devices)<br><strong>Purpose:</strong> Support view of a person's inbox and push devices for investigations.</p> <p><strong>Web (PWA) container:</strong> <code>tabpanel</code> (route segment)</p> <p><strong>Loads:</strong> <code>GET /users/{id}/notifications?include_inactive=true</code> · <code>GET /users/{id}/notifications/{notificationId}</code> · <code>GET /users/{id}/devices?include_inactive=true</code> · <code>GET /users/{id}/devices/{deviceId}</code></p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Inbox</td> <td>table</td> <td>role=grid virtualized table</td> <td>Notification: created_at, application/source, category, priority, title, state, push.status, skip_reason</td> <td>read-only; never mark the user's items read</td> </tr> <tr> <td>Delivery detail</td> <td>side panel</td> <td>resizable side panel</td> <td>deliveries[]: provider, status, attempts, error, sent_at</td> <td></td> </tr> <tr> <td>Devices</td> <td>table</td> <td>role=grid virtualized table</td> <td>Device: app, provider, environment, status, inactive_reason, name, app_version, last_registered_at, last_delivery_at</td> <td></td> </tr> <tr> <td>Delete device</td> <td>destructive-button</td> <td><button class=destructive></td> <td>DELETE /users/{id}/devices/{deviceId}</td> <td>users.manage; audited (device.deleted)</td> </tr> </tbody></table></div> <p><strong>States:</strong> Loading: skeleton after 300 ms; Error: inline with Retry; codes per COPY-AND-STATES</p> <h3 id="ntf-06--send-notification"><a class="anchor" href="#ntf-06--send-notification" aria-hidden="true" tabindex="-1">#</a>NTF-06 — Send notification</h3> <p><strong>Domain:</strong> D13 Notifications · <strong>Route:</strong> <code>/admin/notifications/new</code> · <strong>Archetype:</strong> form · <strong>Phase:</strong> Phase 2<br><strong>Who:</strong> platform notifications.send<br><strong>Purpose:</strong> Staff tool: send one notification to one person on behalf of an Application.</p> <p><strong>Web (PWA) container:</strong> Modal <code><dialog></code> ≥ 768 px; bottom sheet (drag handle, snap points) < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Recipient</td> <td>picker</td> <td>combobox multi-select</td> <td>user (GET /users?q)</td> <td>must have active access to the chosen app</td> </tr> <tr> <td>Application</td> <td>select</td> <td><select> / listbox popover</td> <td>body.application_id</td> <td>required for platform senders</td> </tr> <tr> <td>Category</td> <td>text-field</td> <td><input type=text></td> <td>body.category</td> <td>^[a-z][a-z0-9_]<em>(.[a-z0-9_]+)</em>$; security./account./billing. reserved (422 reserved_category)</td> </tr> <tr> <td>Priority</td> <td>segmented</td> <td>role=radiogroup segmented buttons</td> <td>body.priority normal \| high</td> <td>high explains provider throttling</td> </tr> <tr> <td>Title</td> <td>text-field</td> <td><input type=text></td> <td>body.title</td> <td>1–120</td> </tr> <tr> <td>Body</td> <td>text-area</td> <td><textarea></td> <td>body.body</td> <td>≤ 1,000</td> </tr> <tr> <td>Data</td> <td>key/value editor</td> <td>repeating key/value inputs + Add</td> <td>body.data</td> <td>≤ 20 string pairs, 2 KB; key <code>substratal</code> reserved</td> </tr> <tr> <td>Open link</td> <td>url-field</td> <td><input type=url></td> <td>body.action_url</td> <td>https or private scheme ≤ 2,048</td> </tr> <tr> <td>Advanced</td> <td>disclosure</td> <td><details></td> <td>push (bool), badge, sound default\|silent, collapse_key, ttl_seconds</td> <td></td> </tr> <tr> <td>Payload size</td> <td>meters</td> <td><meter></td> <td>client estimate of the 4 KB push payload</td> <td>422 notification_too_large → details.bytes/max</td> </tr> <tr> <td>Preview</td> <td>card</td> <td><section class=card></td> <td>lock-screen style preview per platform</td> <td>warns: lock screens show title/body — keep sensitive content out</td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Send</td> <td><code>POST /users/{id}/notifications (Idempotency-Key)</code></td> <td>201 → result panel with push.status / skip_reason; 403 entitlement_required → recipient has no access; 429 scope sender\|recipient → countdown</td> </tr> </tbody></table></div> <h2 id="g--global--shell"><a class="anchor" href="#g--global--shell" aria-hidden="true" tabindex="-1">#</a>G · Global / Shell</h2> <h3 id="glb-01--command-palette"><a class="anchor" href="#glb-01--command-palette" aria-hidden="true" tabindex="-1">#</a>GLB-01 — Command palette</h3> <p><strong>Domain:</strong> G Global / Shell · <strong>Route:</strong> <code>(overlay)</code> · <strong>Archetype:</strong> overlay · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Signed in<br><strong>Purpose:</strong> Jump anywhere and run any action by typing.</p> <p><strong>Web (PWA) container:</strong> Top-layer <code><dialog></code> / popover</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Query</td> <td>search</td> <td><input type=search role=searchbox></td> <td></td> <td>Cmd/Ctrl+K (desktop), search button (touch)</td> </tr> <tr> <td>Results</td> <td>grouped list</td> <td>grouped listbox</td> <td>Navigation, Apps (launch), Users (GET /users?q), Orgs, Inbox (recent notifications), Actions (Invite user, Create key, Upgrade to Standard, Mark all read…)</td> <td>permission-filtered; recent items first; ID prefixes resolve directly</td> </tr> </tbody></table></div> <h3 id="glb-02--manage-hub"><a class="anchor" href="#glb-02--manage-hub" aria-hidden="true" tabindex="-1">#</a>GLB-02 — Manage hub</h3> <p><strong>Domain:</strong> G Global / Shell · <strong>Route:</strong> <code>/manage</code> · <strong>Archetype:</strong> hub · <strong>Phase:</strong> MVP<br><strong>Who:</strong> Any admin or developer permission<br><strong>Purpose:</strong> Compact-layout landing list for the Administration and Developer sections.</p> <p><strong>Web (PWA) container:</strong> Bottom-nav destination list < 768 px</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Administration</td> <td>list</td> <td>virtualized list</td> <td>Users, Access, Roles, Audit Log, Send notification — those the caller may open, each with a live count</td> <td>section hidden when no rights</td> </tr> <tr> <td>Developer</td> <td>list</td> <td>virtualized list</td> <td>Applications, API Keys, Webhooks, Tenant — with counts and health (unhealthy webhooks, failed push credentials)</td> <td>section hidden when no rights</td> </tr> </tbody></table></div> <h3 id="glb-03--system-states"><a class="anchor" href="#glb-03--system-states" aria-hidden="true" tabindex="-1">#</a>GLB-03 — System states</h3> <p><strong>Domain:</strong> G Global / Shell · <strong>Route:</strong> <code>(global)</code> · <strong>Archetype:</strong> overlay · <strong>Phase:</strong> MVP<br><strong>Who:</strong> —<br><strong>Purpose:</strong> App-wide banners and blocking states.</p> <p><strong>Web (PWA) container:</strong> Top-layer <code><dialog></code> / popover</p> <div class="table-wrap"><table> <thead> <tr> <th>Element</th> <th>Kind</th> <th>Web (PWA) control</th> <th>Data / API</th> <th>Rules</th> </tr> </thead> <tbody><tr> <td>Offline</td> <td>banner</td> <td>role=region banner</td> <td>network status</td> <td>reads from cache, writes disabled with explanation</td> </tr> <tr> <td>Maintenance / tenant migrating</td> <td>banner</td> <td>role=region banner</td> <td>503 service_unavailable + Retry-After</td> <td>countdown, auto-retry reads</td> </tr> <tr> <td>Session ended</td> <td>modal → AUTH-01</td> <td>dialog → /sign-in</td> <td>401 after failed refresh</td> <td>preserve destination</td> </tr> <tr> <td>Forbidden</td> <td>inline state</td> <td>spinner on tile (aria-busy)</td> <td>403</td> <td>COPY</td> </tr> <tr> <td>Not built yet</td> <td>inline state</td> <td>spinner on tile (aria-busy)</td> <td>501 not_implemented (Notifications today)</td> <td>hide the feature behind its flag; never show an error to end users</td> </tr> <tr> <td>Update required</td> <td>blocking screen</td> <td>full-page route</td> <td>API version deprecation header (if present)</td> <td></td> </tr> </tbody></table></div> <div class="table-wrap"><table> <thead> <tr> <th>Action</th> <th>Call</th> <th>Result handling</th> </tr> </thead> <tbody><tr> <td>Silent token refresh</td> <td><code>POST /auth/token/refresh</code></td> <td>single-flight; rotate refresh token atomically (CLIENT-ARCHITECTURE §2)</td> </tr> <tr> <td>Connectivity probe</td> <td><code>GET /health</code></td> <td>used after offline/503 to decide when to clear the banner</td> </tr> <tr> <td>Forced sign-out</td> <td><code>POST /auth/logout</code></td> <td>on session_revoked or user request; the server deactivates this session's push devices</td> </tr> <tr> <td>Badge refresh</td> <td><code>GET /users/me/notifications/unread-count</code></td> <td>on launch, foreground, after a push arrives, and every 60 s while visible (Windows/Linux: also in background) → app icon/Dock/taskbar/PWA badge</td> </tr> </tbody></table></div> <p><strong>Notes:</strong> <code>POST /auth/oauth/token</code> is called by the launched Application (PKCE exchange), never by the Hub.</p> </article> <aside class="toc" aria-label="On this page"><p class="toc-title">On this page</p><ul><li class="d2"><a href="#container-per-archetype">Container per archetype</a></li><li class="d2"><a href="#d1--sign-in--identity">D1 · Sign-in & Identity</a></li><li class="d3"><a href="#auth-01--sign-in">AUTH-01 — Sign in</a></li><li class="d3"><a href="#auth-02--two-factor-challenge">AUTH-02 — Two-factor challenge</a></li><li class="d3"><a href="#auth-03--create-account">AUTH-03 — Create account</a></li><li class="d3"><a href="#auth-04--verify-your-email">AUTH-04 — Verify your email</a></li><li class="d3"><a href="#auth-05--forgot-password">AUTH-05 — Forgot password</a></li><li class="d3"><a href="#auth-06--set-a-new-password">AUTH-06 — Set a new password</a></li><li class="d3"><a href="#auth-07--accept-invitation">AUTH-07 — Accept invitation</a></li><li class="d2"><a href="#d2--account--security">D2 · Account & Security</a></li><li class="d3"><a href="#acc-01--account--profile">ACC-01 — Account & profile</a></li><li class="d3"><a href="#acc-02--change-email">ACC-02 — Change email</a></li><li class="d3"><a href="#acc-03--change-password">ACC-03 — Change password</a></li><li class="d3"><a href="#acc-04--security">ACC-04 — Security</a></li><li class="d3"><a href="#acc-05--turn-on-two-factor">ACC-05 — Turn on two-factor</a></li><li class="d3"><a href="#acc-06--turn-off-two-factor">ACC-06 — Turn off two-factor</a></li><li class="d3"><a href="#acc-07--privacy">ACC-07 — Privacy</a></li><li class="d3"><a href="#acc-08--delete-account">ACC-08 — Delete account</a></li><li class="d2"><a href="#d3--my-apps">D3 · My Apps</a></li><li class="d3"><a href="#app-01--home--my-apps">APP-01 — Home — My Apps</a></li><li class="d3"><a href="#app-02--app-info">APP-02 — App info</a></li><li class="d3"><a href="#app-03--launch-app">APP-03 — Launch app</a></li><li class="d3"><a href="#app-04--app-profile">APP-04 — App profile</a></li><li class="d3"><a href="#app-05--past-apps">APP-05 — Past apps</a></li><li class="d2"><a href="#d4--settings">D4 · Settings</a></li><li class="d3"><a href="#set-01--settings--global">SET-01 — Settings — Global</a></li><li class="d3"><a href="#set-02--settings--per-app">SET-02 — Settings — Per app</a></li><li class="d2"><a href="#d5--organizations">D5 · Organizations</a></li><li class="d3"><a href="#org-01--organizations">ORG-01 — Organizations</a></li><li class="d3"><a href="#org-02--new-organization">ORG-02 — New organization</a></li><li class="d3"><a href="#org-03--organization--members">ORG-03 — Organization — Members</a></li><li class="d3"><a href="#org-04--invite-member">ORG-04 — Invite member</a></li><li class="d3"><a href="#org-05--member-actions">ORG-05 — Member actions</a></li><li class="d3"><a href="#org-06--organization--apps--seats">ORG-06 — Organization — Apps & seats</a></li><li class="d3"><a href="#org-07--grant-app-to-organization--member-scope">ORG-07 — Grant app to organization / member scope</a></li><li class="d3"><a href="#org-08--organization--settings">ORG-08 — Organization — Settings</a></li><li class="d3"><a href="#org-09--invitation">ORG-09 — Invitation</a></li><li class="d2"><a href="#d6--users">D6 · Users</a></li><li class="d3"><a href="#usr-01--users">USR-01 — Users</a></li><li class="d3"><a href="#usr-02--invite-user">USR-02 — Invite user</a></li><li class="d3"><a href="#usr-03--user--overview">USR-03 — User — Overview</a></li><li class="d3"><a href="#usr-04--user--sessions">USR-04 — User — Sessions</a></li><li class="d3"><a href="#usr-05--suspend-user">USR-05 — Suspend user</a></li><li class="d2"><a href="#d7--access">D7 · Access</a></li><li class="d3"><a href="#acx-01--user--access">ACX-01 — User — Access</a></li><li class="d3"><a href="#acx-02--grant-access">ACX-02 — Grant access</a></li><li class="d3"><a href="#acx-03--turn-off--edit-access">ACX-03 — Turn off / edit access</a></li><li class="d3"><a href="#acx-04--access-check-why">ACX-04 — Access check (Why?)</a></li><li class="d3"><a href="#acx-05--access-all">ACX-05 — Access (all)</a></li><li class="d2"><a href="#d8--roles--permissions">D8 · Roles & Permissions</a></li><li class="d3"><a href="#rol-01--roles">ROL-01 — Roles</a></li><li class="d3"><a href="#rol-02--role-detail">ROL-02 — Role detail</a></li><li class="d3"><a href="#rol-03--new-role">ROL-03 — New role</a></li><li class="d3"><a href="#rol-04--user--roles">ROL-04 — User — Roles</a></li><li class="d2"><a href="#d9--applications">D9 · Applications</a></li><li class="d3"><a href="#apl-01--applications">APL-01 — Applications</a></li><li class="d3"><a href="#apl-02--register-application">APL-02 — Register application</a></li><li class="d3"><a href="#apl-03--application--overview">APL-03 — Application — Overview</a></li><li class="d3"><a href="#apl-04--settings-schema">APL-04 — Settings schema</a></li><li class="d3"><a href="#apl-05--permissions--roles">APL-05 — Permissions & roles</a></li><li class="d3"><a href="#apl-06--review">APL-06 — Review</a></li><li class="d3"><a href="#apl-07--push-credentials">APL-07 — Push credentials</a></li><li class="d2"><a href="#d10--developer-credentials">D10 · Developer Credentials</a></li><li class="d3"><a href="#key-01--api-keys">KEY-01 — API keys</a></li><li class="d3"><a href="#key-02--create-api-key">KEY-02 — Create API key</a></li><li class="d3"><a href="#key-03--secret-reveal">KEY-03 — Secret reveal</a></li><li class="d3"><a href="#key-04--api-key-detail">KEY-04 — API key detail</a></li><li class="d3"><a href="#whk-01--webhooks">WHK-01 — Webhooks</a></li><li class="d3"><a href="#whk-02--add--edit-webhook">WHK-02 — Add / edit webhook</a></li><li class="d3"><a href="#whk-03--webhook--deliveries">WHK-03 — Webhook — Deliveries</a></li><li class="d3"><a href="#whk-04--delivery-detail">WHK-04 — Delivery detail</a></li><li class="d2"><a href="#d11--plan--billing">D11 · Plan & Billing</a></li><li class="d3"><a href="#bil-01--my-plan">BIL-01 — My plan</a></li><li class="d3"><a href="#bil-02--organization-subscription">BIL-02 — Organization subscription</a></li><li class="d3"><a href="#bil-03--checkout--billing-portal">BIL-03 — Checkout / billing portal</a></li><li class="d3"><a href="#bil-04--tenant--infrastructure">BIL-04 — Tenant & infrastructure</a></li><li class="d2"><a href="#d12--audit-log">D12 · Audit Log</a></li><li class="d3"><a href="#aud-01--audit-log">AUD-01 — Audit log</a></li><li class="d3"><a href="#aud-02--audit-event">AUD-02 — Audit event</a></li><li class="d2"><a href="#d13--notifications">D13 · Notifications</a></li><li class="d3"><a href="#ntf-01--inbox">NTF-01 — Inbox</a></li><li class="d3"><a href="#ntf-02--notification">NTF-02 — Notification</a></li><li class="d3"><a href="#ntf-03--devices--notifications">NTF-03 — Devices & notifications</a></li><li class="d3"><a href="#ntf-04--turn-on-notifications">NTF-04 — Turn on notifications</a></li><li class="d3"><a href="#ntf-05--user--notifications--devices">NTF-05 — User — Notifications & devices</a></li><li class="d3"><a href="#ntf-06--send-notification">NTF-06 — Send notification</a></li><li class="d2"><a href="#g--global--shell">G · Global / Shell</a></li><li class="d3"><a href="#glb-01--command-palette">GLB-01 — Command palette</a></li><li class="d3"><a href="#glb-02--manage-hub">GLB-02 — Manage hub</a></li><li class="d3"><a href="#glb-03--system-states">GLB-03 — System states</a></li></ul></aside> </div> </main> <footer class="footer"> <div class="footer-inner"> <p><strong>Substratal Hub — application specifications</strong> · targets the <a href="https://compositecode.github.io/substratalapps.com/">Substratal Apps Platform API v1.4.0</a>.</p> <p><a href="https://github.com/CompositeCode/substratalapps-applications-specs/blob/main/substratal-application-specs/web/SCREENS.md">Edit this page on GitHub</a> · <a href="https://github.com/CompositeCode/substratalapps-applications-specs">Repository</a> · <a href="https://github.com/CompositeCode/substratalapps-applications-specs/blob/main/LICENSE">MIT License</a></p> </div> </footer> <script src="../../assets/site.js" defer></script> </body> </html>

#Web (PWA) — Screen Specs

#Container per archetype

#D1 · Sign-in & Identity

#AUTH-01 — Sign in

#AUTH-02 — Two-factor challenge

#AUTH-03 — Create account

#AUTH-04 — Verify your email

#AUTH-05 — Forgot password

#AUTH-06 — Set a new password

#AUTH-07 — Accept invitation

#D2 · Account & Security

#ACC-01 — Account & profile

#ACC-02 — Change email

#ACC-03 — Change password

#ACC-04 — Security

#ACC-05 — Turn on two-factor

#ACC-06 — Turn off two-factor

#ACC-07 — Privacy

#ACC-08 — Delete account

Web (PWA) — Screen Specs

Container per archetype

D1 · Sign-in & Identity

AUTH-01 — Sign in

AUTH-02 — Two-factor challenge

AUTH-03 — Create account

AUTH-04 — Verify your email

AUTH-05 — Forgot password

AUTH-06 — Set a new password

AUTH-07 — Accept invitation

D2 · Account & Security

ACC-01 — Account & profile

ACC-02 — Change email

ACC-03 — Change password

ACC-04 — Security

ACC-05 — Turn on two-factor

ACC-06 — Turn off two-factor

ACC-07 — Privacy

ACC-08 — Delete account