Admin Shell access & navigation

Happy path

The organizer types admin.vxge-aperture.porivo.com or follows a deep link from an email or chat message. They land on whichever page they intended (the deep link target, or the home dashboard if they came in cold). They are recognized as a logged-in member of their workspace and can see the workspace name in the chrome. They scan the page and within ~5 seconds locate either the action they came to perform or the navigation entry that leads to it.

1. Navigate to admin.vxge-aperture.porivo.com (or a deep link below it).

   First-time visit: the browser has no Voyage cookies. Returning visit within token TTL: silent auth refreshes. Returning visit past TTL: redirected to Auth0 with the deep-link path captured in state.

2. Auth0 redirects with a freshly-issued ID token; the shell exchanges it for a workspace team token.

   The workspace team token (WORKSPACE_TEAM_TOKEN cookie or storage state) is the short-lived credential that scopes API calls to the user's tenant. Token TTL is ~5 minutes; the shell silently refreshes ahead of expiry without a flash of "you've been logged out."

3. The shell renders with three orienting signals: workspace name in the header, the user's identity in the upper right, and a primary nav listing the major sections (Events, Designs, Reports, Integrations, Settings).

   If the user followed a deep link, the matching nav item is highlighted and the page below the chrome is the requested view. If the user came in cold, the home dashboard surfaces a card grid: in-flight events, recent reports, recent activity.

4. The user finds their next action.

   Three patterns the shell supports: (a) "I have an event ID and I'm jumping to it" — search box at the top by name or ID; (b) "I'm starting something new" — visible Create event button in the header or home card grid; (c) "I'm reviewing recent work" — recent-activity feed in the home dashboard.

Failure modes

Surface-level failures: anything that prevents the shell from rendering or the user from being recognized. Branch stories don't re-test these — they assume the shell renders correctly and the user is authenticated.

Edge cases

Page evaluation

At each surface within the Admin Shell, an agent (or a curious human auditor) should be able to answer these questions in the affirmative. The questions are deliberately the same as a human would ask while running a UX review.

Color contrast

All body text against the page background is ≥4.5:1. Pill labels (persona / stage indicators) are ≥3:1 against their pill background. Disabled buttons are visibly disabled, not just slightly faded — disabled + cursor:not-allowed + aria-disabled, with contrast still ≥3:1 so the user knows there's a button there even if they can't click it.

Keyboard navigation

Tab order follows the visual reading order. The skip-to-main link is the first focusable element. Modal dialogs trap focus while open and return focus to the trigger button on close. Esc closes modals.

Screen reader

The header is a <header>, the nav is <nav aria-label="primary">, the main content is a <main>. Card grids on the home dashboard are wrapped in landmarks with descriptive labels. Loading skeletons announce "Loading recent events" via aria-live polite, not assertive (so they don't interrupt screen readers).

Acceptance signals

• URL is the deep-link target (or /admin if no deep link).
• Workspace team token cookie or storage state is present and unexpired.
• Header chrome is rendered: workspace name visible, user identity visible, primary nav visible.
• document.title is set to a per-page descriptive label (not blank, not "Vite app", not the same across all pages).
• The primary action of the destination page is visible above the fold at 1280×800.
• No console errors at severity ≥ warn from Voyage origins (third-party SDK warnings allowed but flagged).
• Time to interactive (TTI) ≤ 2s on broadband, ≤ 8s on simulated 3G.
• No layout shifts (CLS) ≥ 0.1 during the first 5 seconds.

Stable test attributes

This trunk's contract — the named data-test attributes the Aperture admin shell MUST expose. Every branch rooted in Admin Shell can rely on these existing without re-declaring them. Removing one is a loosening of every branch that inherits this trunk; the linter blocks merge accordingly.

Visibility teeth. Each attribute below must be present in the document AND effectively visible per the runtime predicate (no display:none, visibility:hidden, opacity:0, zero bounding rect, off-screen positioning, or aria-hidden="true" on it or any ancestor). Where the row's purpose implies interactivity, it must additionally satisfy effectively interactive. Hiding without removal is treated identically to removal — both require the loosening token. See PREDICATES.md for the full runtime definition.

Branches inheriting this trunk write probes that depend on workspace-name, primary-nav, etc. Adding a 58th branch tomorrow does not require it to re-list these attributes; they're inherited.

Agent test plan

1. Preflight `fastr-auth.sh preflight workspace-aperture` — confirm CLI-token endpoint exists.
   FAIL CLOSED: if preflight is non-zero, abort the run with "auth surface broken, fix workspace config first."
2. Wrap the run in `fastr-auth.sh workspace-aperture --` so AUTH0_TOKEN, WORKSPACE_TEAM_TOKEN, WORKSPACE_BASE_URL are injected.
3. Open Playwright context. setExtraHTTPHeaders Authorization Bearer ${AUTH0_TOKEN}.
   addCookies __fastr_workspace_token = ${WORKSPACE_TEAM_TOKEN} on ${WORKSPACE_BASE_URL} hostname.
4. page.goto(${WORKSPACE_BASE_URL}). Wait for header chrome to render: ['header', 'nav[aria-label="primary"]', '[data-test=workspace-name]'].
5. Capture page-state snapshot: URL, document.title, console errors, screenshot.
6. Assert authMode = 'silent-refresh' or 'interactive' — never 'bypassed'.
7. If any of the assertions in §acceptance fail, the trunk fails closed and no branch attempts to run.

For each failure mode in §failure-modes, the harness has a corresponding probe:
- Auth0 error: inject ?error=consent_required into the callback, assert error page renders, retry button works.
- Cross-tenant deep link: navigate to /admin/events/<known-other-workspace-event-id>, assert "no access" page (not "not found").
- Token mint fails: stub the cli-token endpoint to return 503 once, assert auto-retry → success.
- Token TTL expires: clock.tick past expiry, assert silent refresh, no redirect.
- Zero workspaces: stub the workspaces endpoint to return [], assert the "you don't have access yet" page.
- Section data fails: stub /v1/admin/events to return 500, assert per-card error + rest of shell still navigable.
- Slow network: throttle network to 3G profile, assert skeletons render within 500ms, TTI < 8s.

For each row in §page-evaluation, the harness:
- Computes axe-core results, asserts no violations of impact 'serious' or 'critical'.
- Computes color contrast for body text and pill labels via the PostCSS calc + WCAG formula.
- Tabs through the focusable elements and asserts the order matches the visual reading order top-to-bottom.
- Triggers Esc on each modal observed and asserts focus returns to the trigger.
- Crawls headings (h1..h6) and asserts no skip levels.
- Reads document.title at each navigation and asserts it's per-page-distinct.