# V3 Navigation And Journey Contract

Status: active product contract  
Scope: canonical `/*` product surfaces. Historical `/v3/*` mock references are
not active product routes.

## Decision

V3 navigation is part of the product contract, not page decoration. Every migrated
surface must make the user's current scope, parent surface, sibling surfaces, and
next safe action obvious without relying on browser history.

## Navigation Layers

| Layer | Purpose | Implementation rule |
|---|---|---|
| Global shell | Move between top-level work modes: Workloads, Compute, Apps, Storage, Access, Account, Platform | Use the persistent left rail and top context selectors. Do not add separate top-level rails inside pages. |
| Family local nav | Move between sibling pages inside one surface family | Use `V3LocalNav` / family wrappers. Required for Platform, Access, Account, and any future family with 3+ sibling pages. |
| Resource header back link | Return from a detail/drill-down page to its parent workbench or owning resource | Use `ResourceHeader.backHref`. Do not rely on `history.back()` as the only way out. |
| Resource tabs | Move between views of the same resource | Use `SectionTabs`. Tabs must not change the parent resource identity. |
| Evidence pivots | Jump to audit, logs, tasks, traces, or correlated resources | Use explicit evidence/action links. They complement the parent back link; they do not replace it. |
| Wizard stepper | Move within a multi-step mutation | Previous steps must be clickable. Forward movement stays validation-gated. Cancel/close returns to the launch source. |

## Back-Link Rules

1. Workload detail backs to `/workloads`.
2. App detail backs to `/apps`.
3. Storage detail backs to `/storage`.
4. Platform node detail backs to `/platform/lifecycle/nodes`, the
   node inventory workbench, not the lifecycle family landing.
5. MAAS/provisioning workflow details back to the relevant lifecycle/provisioning workbench.
6. Task details back to the owning resource when `resource_href` is available; otherwise they back to `/workloads`.
7. User/IAM details back to the owning family page, for example `/platform/iam`.
8. Cross-family action links must be labeled by intent: `Open resource`, `Open evidence`, `Open ops`, `Open workflow`, not generic `Open`.

## Family Navigation Requirements

| Family | Required local nav |
|---|---|
| Platform | Overview, Ops, Lifecycle, Config, Evidence, Finance, IAM. Keep this nav visible on Platform detail/workflow pages so operators can move across families without returning to overview first. |
| Access | Overview, Memberships, Service accounts, Credentials, Entitlements, Connectivity, Identity, Audit |
| Account | Overview, Profile, Security, Billing, Sessions |
| Storage | Not required yet; bucket detail uses resource tabs. Add local nav if provider/admin sub-surfaces grow. |
| Apps | Not required yet; catalog/detail/launch are a linear flow. Add local nav if app administration grows. |
| Workloads | Not required yet; use workbench filters plus resource tabs. |

## Resource Lifecycle Requirement

Navigation and lifecycle are coupled: if a page lets the user drill into a
resource, the detail page must expose:

1. Current posture.
2. Lifecycle/activity history.
3. Evidence pivots.
4. A stable parent back link.

The lifecycle/evidence rendering pattern is defined in
`doc/product/V3_Resource_Lifecycle_Evidence_Pattern_v1.md`.

## E2E Expectations

The V3 E2E suite should assert:

1. Each family page with local nav renders the expected nav and marks only the current item active.
2. Each detail page renders `v3-resource-header` with a non-empty back link.
3. Task details with an owning resource use the resource as the back target.
4. Wizards allow backward step navigation and do not lose draft state.
5. Evidence/action links preserve the active user/project/platform context where the API supports it.

## Open Follow-Ups

1. Add `V3LocalNav` to any new family before adding its third subpage.
2. Add query-param tab deep links for high-value resource tabs once the tab state contract is settled.
3. Add breadcrumb support only if family nav + `ResourceHeader` still fails usability review; do not introduce a second navigation vocabulary prematurely.