Docs / macos / SCREENS.md

#macOS — Screen Specs

All 75 screens with the native macOS 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

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

macOS container: Separate Window scene (720×560, no sidebar)

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.

macOS container: Separate Window scene (720×560, no sidebar)

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.

macOS container: Separate Window scene (720×560, no sidebar)

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.

macOS container: Separate Window scene (720×560, no sidebar)

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.

macOS container: Separate Window scene (720×560, no sidebar)

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

macOS container: Separate Window scene (720×560, no sidebar)

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.

macOS container: Separate Window scene (720×560, no sidebar)

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.

macOS container: Detail column Form(.grouped); per-row save

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.

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: Detail column Form(.grouped); per-row save

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.

macOS container: Sheet with paged steps + Back/Continue

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.

macOS container: .confirmationDialog or sheet when it has fields

#ACC-07 — Privacy

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

macOS container: Detail column Form(.grouped); per-row save

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

macOS container: .confirmationDialog or sheet when it has fields

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.

macOS container: Detail column of NavigationSplitView, LazyVGrid

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.

macOS container: .popover or .inspector

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.

macOS container: NSWorkspace.open / ASWebAuthenticationSession

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.

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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.

macOS container: Content column (List(selection:)) + detail column

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.

macOS container: Detail column Form(.grouped); per-row save

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.

macOS container: Detail column Form(.grouped); per-row save

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.

macOS container: Content column (List(selection:)) + detail column

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.

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: Detail column; tabs as segmented Picker in toolbar principal

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

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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.

macOS container: .confirmationDialog or sheet when it has fields

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

macOS container: Tab content inside detail

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.

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: Detail column Form(.grouped); per-row save

#ORG-09 — Invitation

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

macOS container: .confirmationDialog or sheet when it has fields

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.

macOS container: Detail column with Table, inspector optional

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

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: Detail column; tabs as segmented Picker in toolbar principal

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.

macOS container: Tab content inside detail

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

macOS container: .confirmationDialog or sheet when it has fields

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.

macOS container: Tab content inside detail

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.

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: .confirmationDialog or sheet when it has fields

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.

macOS container: .popover or .inspector

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.

macOS container: Detail column with Table, inspector optional

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.

macOS container: Content column (List(selection:)) + detail column

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.

macOS container: Detail column; tabs as segmented Picker in toolbar principal

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.

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: Tab content inside detail

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.

macOS container: Content column (List(selection:)) + detail column

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.

macOS container: Sheet with paged steps + Back/Continue

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

macOS container: Detail column; tabs as segmented Picker in toolbar principal

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.

macOS container: Tab content inside detail

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

macOS container: Tab content inside detail

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

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: Tab content inside detail

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.

macOS container: Detail column with Table, inspector optional

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.

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: Sheet, interactiveDismissDisabled, sharingType = .none

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

macOS container: Detail column; tabs as segmented Picker in toolbar principal

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.

macOS container: Content column (List(selection:)) + detail column

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.

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: Detail column; tabs as segmented Picker in toolbar principal

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.

macOS container: .popover or .inspector

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

macOS container: Detail column Form(.grouped); per-row save

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.

macOS container: Tab content inside detail

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.

macOS container: NSWorkspace.open / ASWebAuthenticationSession

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.

macOS container: Detail column; tabs as segmented Picker in toolbar principal

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.

macOS container: Detail column with Table, inspector optional

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.

macOS container: .popover or .inspector

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.

macOS container: Content column (List(selection:)) + detail column

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.

macOS container: .popover or .inspector

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.

macOS container: Detail column Form(.grouped); per-row save

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.

macOS container: Sheet with paged steps + Back/Continue

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.

macOS container: Tab content inside detail

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.

macOS container: .sheet with Form(.grouped); ⌘↩ submits, Esc cancels

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

macOS container: Floating panel / toolbar popover

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

macOS container: — (sidebar replaces hubs)

#GLB-03 — System states

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

macOS container: Floating panel / toolbar popover

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