Docs / 00-shared / SCREEN-SPECS.md

#Screen Specs

Every screen in the Substratal Hub, identical across all six apps. Platform folders contain the same specs with native controls filled in (SCREENS.md).

Element kinds are defined in COMPONENTS.md. Archetypes: auth Unauthenticated full-screen form, outside the app shell; grid Top-level collection rendered as tiles; list Top-level searchable/filterable collection (rows); table Top-level dense collection with columns (desktop), rows (compact); detail Object detail with header + tabs/segments; tab A tab/segment inside a detail screen; form Create/edit form presented modally (sheet/dialog); settings Grouped settings form, edits save per-row; confirm Destructive or consequential confirmation (alert/dialog), optional reason field; secret One-time secret reveal, cannot be dismissed until acknowledged; wizard Multi-step modal flow; popover Lightweight anchored or half-height panel for explanation; handoff Leaves the app (browser / other app) and handles the return; overlay App-wide overlay (palette, inbox panel); hub Mobile hub list linking to sections.

Universal rules for every screen (not repeated below): Capabilities gating (INFORMATION-ARCHITECTURE §2), request conventions — Idempotency-Key on creates, If-Match on PATCH/DELETE, cursor pagination, error decoding (CLIENT-ARCHITECTURE §3), copy (COPY-AND-STATES), accessibility (ACCESSIBILITY).

#Index

#D1 · Sign-in & Identity

#AUTH-01 — Sign in

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.

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

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.

Entry points: AUTH-01 returned MfaChallenge

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.

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

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.

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

#AUTH-05 — Forgot password

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

#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.

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

#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.

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

#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.

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

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.

#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.

#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.

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

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.

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.

#ACC-07 — Privacy

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

#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.

Notes: 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).

#D3 · My Apps

#APP-01 — Home — My Apps

Domain: D3 My Apps · Route: / · Archetype: grid · Phase: MVP
Who: Signed in
Purpose: See every app you can use, its access status, and launch it.

Loads: GET /applications (catalog the caller can see; each has access_tier free|standard) · GET /users/me/entitlements?include_inactive=true · GET /users/me (plan, plan_sources) · GET /organizations?status=active (for pending invites) · GET /users/me/notifications/unread-count (bell badge)

States: 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

Notes: Resolved status per app: if any path active → Active; else precedence scheduled > disabled > expired > revoked > none (matches the API's resolved_entitlement_status). Use GET /users/me/apps/{appId}/effective-permissions for the authoritative answer when the user opens APP-02. Tile helper text by source of the active path: free → "Free"; subscription → "Standard" (or "Standard · via {org}"); developer grants as before. The Hub itself (app_hub) is hidden from the grid.

#APP-02 — App info

Domain: D3 My Apps · Route: /apps/:appId · Archetype: popover · Phase: MVP
Who: Signed in
Purpose: Explain an app's access status and how the user has access.

Loads: GET /applications/{appId} · GET /users/me/apps/{appId}/effective-permissions

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

#APP-03 — Launch app

Domain: D3 My Apps · Route: /apps/:appId/launch · Archetype: handoff · Phase: MVP
Who: Active entitlement
Purpose: Mint an app token (or authorization code) and open the app.

Notes: Record launch time locally for "recently launched" ordering.

#APP-04 — App profile

Domain: D3 My Apps · Route: /apps/:appId/profile · Archetype: form · Phase: Phase 2
Who: Self, active entitlement
Purpose: Per-app display handle and custom profile fields.

Loads: GET /users/me/apps/{appId}/profile

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

#APP-05 — Past apps

Domain: D3 My Apps · Route: /apps/past · Archetype: list · Phase: MVP
Who: Signed in
Purpose: Apps whose access was revoked or expired.

Loads: GET /users/me/entitlements?include_inactive=true&status=revoked,expired

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

#D4 · Settings

#SET-01 — Settings — Global

Domain: D4 Settings · Route: /settings · Archetype: settings · Phase: MVP
Who: Self
Purpose: Preferences that apply to every app.

Loads: GET /users/me/settings · GET /users/me/apps/app_hub/settings (theme choices)

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

#SET-02 — Settings — Per app

Domain: D4 Settings · Route: /settings/apps/:appId · Archetype: settings · Phase: Phase 2
Who: Self, active entitlement
Purpose: Override global settings and set app-specific preferences from the app's settings_schema.

Loads: GET /applications/{appId} (settings_schema) · GET /users/me/apps/{appId}/settings

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

#D5 · Organizations

#ORG-01 — Organizations

Domain: D5 Organizations · Route: /orgs · Archetype: list · Phase: MVP
Who: Signed in (all orgs with organizations.manage)
Purpose: Organizations you belong to, plus pending invitations.

Loads: GET /organizations

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

#ORG-02 — New organization

Domain: D5 Organizations · Route: /orgs/new · Archetype: form · Phase: MVP
Who: Any active user
Purpose: Create an organization; creator becomes org admin.

#ORG-03 — Organization — Members

Domain: D5 Organizations · Route: /orgs/:orgId/members · Archetype: detail · Phase: MVP
Who: Member (read), org_admin / organizations.manage (write)
Purpose: See and manage members and pending invitations.

Loads: GET /organizations/{id} · GET /organizations/{id}/members

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

#ORG-04 — Invite member

Domain: D5 Organizations · Route: /orgs/:orgId/members/invite · Archetype: form · Phase: MVP
Who: org_admin; organizations.manage may add by user_id
Purpose: Invite people by email (or add an existing user, staff only).

Notes: Existing Users also receive an account.organization_invitation platform alert (NTF-01, and a push where the Hub has a device).

#ORG-05 — Member actions

Domain: D5 Organizations · Route: /orgs/:orgId/members/:userId · Archetype: confirm · Phase: MVP
Who: org_admin / organizations.manage
Purpose: Change a member's role or remove them.

#ORG-06 — Organization — Apps & seats

Domain: D5 Organizations · Route: /orgs/:orgId/apps · Archetype: tab · Phase: Phase 2
Who: Member (read), org_admin (write)
Purpose: Org-wide app grants and who they include.

Loads: GET /organizations/{id}/entitlements

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

#ORG-07 — Grant app to organization / member scope

Domain: D5 Organizations · Route: /orgs/:orgId/apps/grant · Archetype: form · Phase: Phase 2
Who: entitlements.manage or app owner; scope edits by org_admin
Purpose: Create an org-wide grant or change who it includes.

#ORG-08 — Organization — Settings

Domain: D5 Organizations · Route: /orgs/:orgId/settings · Archetype: settings · Phase: MVP
Who: org_admin (rename), organizations.manage (suspend), any member (leave)
Purpose: Rename, leave, or (staff) suspend the organization.

#ORG-09 — Invitation

Domain: D5 Organizations · Route: /orgs/:orgId/invitation · Archetype: confirm · Phase: MVP
Who: Invited user
Purpose: Accept or decline an organization invitation.

Entry points: Invitation banner on APP-01; ORG-01 pending section; account.organization_invitation notification (NTF-01 / push action "Accept")

#D6 · Users

#USR-01 — Users

Domain: D6 Users · Route: /admin/users · Archetype: table · Phase: MVP
Who: users.list (write actions need users.manage)
Purpose: Find and manage user accounts.

Loads: GET /users?limit=50&cursor&status&q&application_id&organization_id&created_after&created_before

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

#USR-02 — Invite user

Domain: D6 Users · Route: /admin/users/new · Archetype: form · Phase: MVP
Who: users.manage
Purpose: Create a user and send an invitation (or create active).

#USR-03 — User — Overview

Domain: D6 Users · Route: /admin/users/:userId · Archetype: detail · Phase: MVP
Who: users.list (read), users.manage (write)
Purpose: One user's account state and administrative actions.

Loads: GET /users/{id} · GET /users/{id}/profile · GET /users/{id}/subscription (billing.manage only)

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

#USR-04 — User — Sessions

Domain: D6 Users · Route: /admin/users/:userId/sessions · Archetype: tab · Phase: MVP
Who: users.manage
Purpose: See and revoke a user's sessions.

Loads: GET /users/{id}/sessions

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

#USR-05 — Suspend user

Domain: D6 Users · Route: /admin/users/:userId/suspend · Archetype: confirm · Phase: MVP
Who: users.manage
Purpose: Suspend an account (signs them out everywhere).

Notes: Suspension revokes sessions and deactivates every push device the user holds; say so in the confirm body.

#D7 · Access

#ACX-01 — User — Access

Domain: D7 Access · Route: /admin/users/:userId/access · Archetype: tab · Phase: MVP
Who: users.list (read), entitlements.manage or app owner (write)
Purpose: Turn apps on or off for one person; see every path that grants access.

Loads: GET /users/{id}/entitlements?include_inactive=true · GET /applications

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

Notes: 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.

#ACX-02 — Grant access

Domain: D7 Access · Route: /admin/users/:userId/access/grant · Archetype: form · Phase: MVP
Who: entitlements.manage or app owner (own app)
Purpose: Give a person access to an app.

#ACX-03 — Turn off / edit access

Domain: D7 Access · Route: /admin/entitlements/:entId · Archetype: confirm · Phase: MVP
Who: entitlements.manage or app owner
Purpose: Confirm turning off access, or edit term/source.

Loads: GET /entitlements/{id}

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

#ACX-04 — Access check (Why?)

Domain: D7 Access · Route: /admin/users/:userId/apps/:appId/why · Archetype: popover · Phase: MVP
Who: users.list or app owner
Purpose: Explain exactly why a person can or can't use an app.

Loads: GET /users/{id}/apps/{appId}/effective-permissions

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

#ACX-05 — Access (all)

Domain: D7 Access · Route: /admin/access · Archetype: table · Phase: MVP
Who: entitlements.manage or app owner (confined to own apps)
Purpose: Every grant across users: audit expirations, trials, revocations.

Loads: GET /entitlements?application_id&status&source&user_id&organization_id&order_id&ends_before&include_inactive

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

#D8 · Roles & Permissions

#ROL-01 — Roles

Domain: D8 Roles & Permissions · Route: /admin/roles · Archetype: list · Phase: MVP
Who: users.list (read), roles.manage (write)
Purpose: Platform and app roles.

Loads: GET /roles?scope · GET /permissions (includes notifications.send)

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

#ROL-02 — Role detail

Domain: D8 Roles & Permissions · Route: /admin/roles/:roleId · Archetype: detail · Phase: MVP
Who: users.list (read), roles.manage (write)
Purpose: View or edit a role's permissions.

Loads: GET /roles/{id} · GET /permissions?scope

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

#ROL-03 — New role

Domain: D8 Roles & Permissions · Route: /admin/roles/new · Archetype: form · Phase: MVP
Who: roles.manage
Purpose: Define a custom role.

#ROL-04 — User — Roles

Domain: D8 Roles & Permissions · Route: /admin/users/:userId/roles · Archetype: tab · Phase: MVP
Who: users.list (read), roles.manage (write)
Purpose: Assign and remove roles for a user.

Loads: GET /users/{id}/roles

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

#D9 · Applications

#APL-01 — Applications

Domain: D9 Applications · Route: /dev/apps · Archetype: list · Phase: MVP
Who: Any (catalog), owner/applications.manage (manage)
Purpose: Applications you own or administer.

Loads: GET /applications?owned=true (staff: all, filter review_status)

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

#APL-02 — Register application

Domain: D9 Applications · Route: /dev/apps/new · Archetype: wizard · Phase: MVP
Who: applications.manage
Purpose: Register a new application.

#APL-03 — Application — Overview

Domain: D9 Applications · Route: /dev/apps/:appId · Archetype: detail · Phase: MVP
Who: Owner (configure), applications.manage (anything)
Purpose: Configure an application.

Loads: GET /applications/{id}

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

#APL-04 — Settings schema

Domain: D9 Applications · Route: /dev/apps/:appId/schema · Archetype: tab · Phase: Phase 2
Who: Owner / applications.manage
Purpose: Declare per-user settings the app stores in Substratal.

#APL-05 — Permissions & roles

Domain: D9 Applications · Route: /dev/apps/:appId/roles · Archetype: tab · Phase: Phase 2
Who: Owner / applications.manage
Purpose: Declare app permissions, available app roles and the default role.

#APL-06 — Review

Domain: D9 Applications · Route: /dev/apps/:appId/review · Archetype: form · Phase: Phase 3
Who: applications.manage
Purpose: Staff moderation of an application.

#APL-07 — Push credentials

Domain: D9 Applications · Route: /dev/apps/:appId/push · Archetype: tab · Phase: Phase 2
Who: Owner or applications.manage with a User token (write); app key / owner (read)
Purpose: Configure APNs, FCM and Web Push for an Application so it can send push notifications.

Loads: GET /applications/{id}/push-credentials

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

Notes: 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).

#D10 · Developer Credentials

#KEY-01 — API keys

Domain: D10 Developer Credentials · Route: /dev/keys · Archetype: table · Phase: MVP
Who: api_keys.manage or app owner
Purpose: Service and agent credentials.

Loads: GET /api-keys?scope&mode&intended_use&include_inactive

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

#KEY-02 — Create API key

Domain: D10 Developer Credentials · Route: /dev/keys/new · Archetype: form · Phase: MVP
Who: api_keys.manage or app owner (app-scoped)
Purpose: Create a key with least-privilege permissions.

#KEY-03 — Secret reveal

Domain: D10 Developer Credentials · Route: (modal) · Archetype: secret · Phase: MVP
Who: Creator
Purpose: Show a new API key secret, webhook signing secret, or recovery codes exactly once.

#KEY-04 — API key detail

Domain: D10 Developer Credentials · Route: /dev/keys/:keyId · Archetype: detail · Phase: MVP
Who: api_keys.manage or app owner
Purpose: Edit, rotate or revoke a key.

Loads: GET /api-keys/{id} · GET /audit-events?actor_id={id}

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

#WHK-01 — Webhooks

Domain: D10 Developer Credentials · Route: /dev/webhooks · Archetype: list · Phase: Phase 2
Who: webhooks.manage or app owner
Purpose: Endpoints that receive access-change events.

Loads: GET /webhooks?application_id

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

#WHK-02 — Add / edit webhook

Domain: D10 Developer Credentials · Route: /dev/webhooks/new · Archetype: form · Phase: Phase 2
Who: webhooks.manage or app owner
Purpose: Subscribe a URL to events.

#WHK-03 — Webhook — Deliveries

Domain: D10 Developer Credentials · Route: /dev/webhooks/:hookId · Archetype: detail · Phase: Phase 2
Who: webhooks.manage or app owner
Purpose: Delivery history, testing and secret rotation.

Loads: GET /webhooks/{id} · GET /webhooks/{id}/deliveries?status&since&event_id

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

#WHK-04 — Delivery detail

Domain: D10 Developer Credentials · Route: /dev/webhooks/:hookId/deliveries/:deliveryId · Archetype: popover · Phase: Phase 2
Who: webhooks.manage or app owner
Purpose: One delivery attempt in detail.

#D11 · Plan & Billing

#BIL-01 — My plan

Domain: D11 Plan & Billing · Route: /billing · Archetype: settings · Phase: Phase 2
Who: Self; billing.manage can view any User's (read-only)
Purpose: Free or Standard: what covers you, your own subscription, upgrade and manage billing.

Loads: GET /users/me/subscription

States: 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."

Notes: 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.

#BIL-02 — Organization subscription

Domain: D11 Plan & Billing · Route: /orgs/:orgId/subscription · Archetype: tab · Phase: Phase 2
Who: org_admin (manage); billing.manage (read + portal)
Purpose: An organization's Standard subscription and which members it covers.

Loads: GET /organizations/{id}/subscription · GET /organizations/{id}/members (for the member picker)

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

Notes: Members gained or lost take effect at once; say so before saving.

#BIL-03 — Checkout / billing portal

Domain: D11 Plan & Billing · Route: /billing/return · Archetype: handoff · Phase: Phase 2
Who: Self (individual); org_admin (org checkout); org_admin or billing.manage (org portal)
Purpose: Hand off to Stripe in the browser and confirm the result on return.

Notes: success_url / cancel_url / return_url must be https: use https://dashboard.substratalapps.com/billing/return… (Universal/App Links open the native app).

#BIL-04 — Tenant & infrastructure

Domain: D11 Plan & Billing · Route: /dev/tenant · Archetype: detail · Phase: Phase 2
Who: Tenant owner (read), tenants.manage (write)
Purpose: Where an Application owner's data lives, and support-run tier changes. Tenants aren't billed.

Loads: GET /tenants · GET /tenants/{id} · GET /tenants/{id}/tier-change-requests

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

#D12 · Audit Log

#AUD-01 — Audit log

Domain: D12 Audit Log · Route: /admin/audit · Archetype: table · Phase: MVP
Who: audit.view
Purpose: Who changed what, when.

Loads: GET /audit-events?since&until&actor_type&actor_id&action&target_type&target_id&target_user_id&application_id&organization_id&tenant_id

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

Notes: Hot window is one year for every Tenant; read the Audit-Hot-Window-Start response header and show it in an info caption. Export is Phase 3. New actions to group in the filter: subscription., push_credential., device.deleted.

#AUD-02 — Audit event

Domain: D12 Audit Log · Route: /admin/audit/:eventId · Archetype: popover · Phase: MVP
Who: audit.view
Purpose: One event with before/after diff.

Loads: GET /audit-events/{id}

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

#D13 · Notifications

#NTF-01 — Inbox

Domain: D13 Notifications · Route: /inbox · Archetype: list · Phase: Phase 2
Who: Self
Purpose: Every notification the person has received — from every app and from Substratal — with read and archived state.

Entry points: Bell in the toolbar / Inbox in the sidebar (desktop) / Inbox tab (compact); Tapping a push; Badges (app icon, Dock/taskbar, PWA)

Loads: GET /users/me/notifications?state&application_id&source&category&priority&created_after&created_before&include_inactive · GET /users/me/notifications/unread-count · GET /applications (names, icons)

States: 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)

Notes: 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 (app_hub) notifications and platform alerts.

#NTF-02 — Notification

Domain: D13 Notifications · Route: /inbox/:notificationId · Archetype: popover · Phase: Phase 2
Who: Self (users.list via NTF-05)
Purpose: One notification in full, with where it leads and how its push went.

Loads: GET /users/me/notifications/{notificationId}

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

#NTF-03 — Devices & notifications

Domain: D13 Notifications · Route: /account/devices · Archetype: settings · Phase: Phase 2
Who: Self
Purpose: Where push notifications reach this person, and controls for this device.

Loads: GET /users/me/devices?include_inactive=true · GET /users/me/settings (notifications.push)

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

Notes: Device tokens are never displayed (only token_hint).

#NTF-04 — Turn on notifications

Domain: D13 Notifications · Route: /account/devices/enable · Archetype: wizard · Phase: Phase 2
Who: Self
Purpose: Explain, request the OS permission, and register this install for push.

Entry points: 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

Notes: 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).

#NTF-05 — User — Notifications & devices

Domain: D13 Notifications · Route: /admin/users/:userId/notifications · Archetype: tab · Phase: Phase 2
Who: users.list (read), users.manage (delete devices)
Purpose: Support view of a person's inbox and push devices for investigations.

Loads: GET /users/{id}/notifications?include_inactive=true · GET /users/{id}/notifications/{notificationId} · GET /users/{id}/devices?include_inactive=true · GET /users/{id}/devices/{deviceId}

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

#NTF-06 — Send notification

Domain: D13 Notifications · Route: /admin/notifications/new · Archetype: form · Phase: Phase 2
Who: platform notifications.send
Purpose: Staff tool: send one notification to one person on behalf of an Application.

#G · Global / Shell

#GLB-01 — Command palette

Domain: G Global / Shell · Route: (overlay) · Archetype: overlay · Phase: MVP
Who: Signed in
Purpose: Jump anywhere and run any action by typing.

#GLB-02 — Manage hub

Domain: G Global / Shell · Route: /manage · Archetype: hub · Phase: MVP
Who: Any admin or developer permission
Purpose: Compact-layout landing list for the Administration and Developer sections.

#GLB-03 — System states

Domain: G Global / Shell · Route: (global) · Archetype: overlay · Phase: MVP
Who: —
Purpose: App-wide banners and blocking states.

Notes: POST /auth/oauth/token is called by the launched Application (PKCE exchange), never by the Hub.