Skip to content
Canonical

ID-118 {118.2} PRODUCT — Zone-grouped platform navigation + External-sources placement

ID-118 {118.2} PRODUCT — Platform navigation information architecture

Section titled “ID-118 {118.2} PRODUCT — Platform navigation information architecture”

Kind: PRODUCT ({118.2}) — formalises the ratified {118.1} RESEARCH (IA-MAP-s454.md) into numbered, testable behaviour invariants. Gates {118.3} TECH, {118.4} PLAN, and id-135 {135.10} (the Surface-A /search nav entry). Authored: 09/07/2026 · Task Planner (fresh dispatch). Ratification provenance: S454 owner ratification of all five open questions, recorded in the {118.1} journal (bun scripts/ledger-cli.ts journal 118.1) and IA-MAP-s454.md §4/§7: OQ-D = Option 1 zone-grouped nav; OQ-B = label “External sources” for /reference; OQ-A = “Research” is a relabel of the seated competitor_research application_type, not a new one; OQ-C = /activity keeps its own Governance entry; OQ-E = group headers “Applications / Knowledge / Governance”. This PRODUCT slice does not re-open any of those.

Empirical-verification note. This spec cites internal Canonical routes/components and ratified docs only — no external-library symbols. The pre-ratification import-and-call check is therefore N/A for this artefact.

Summary

Section titled “Summary”

Re-organise the platform’s top-level navigation from a flat, IMS-era link bar into three architecture-aligned zones — Applications, Knowledge, Governance — plus utilities (Home, global search, Settings). This gives every currently-homeless corpus surface a principled home; in particular it surfaces the id-111 reference reading UI (/reference) as a first-class “External sources” entry in the Knowledge zone — the original driver of Task ID-118 — and provides the consistent Knowledge-zone slot the id-135 Surface-A /search entry ({135.10}) must ship into. The relabel and regrouping are applied in lockstep across all three navigation surfaces so they stop disagreeing with each other.

Problem

Section titled “Problem”

References (/reference, /reference/[id]) shipped functionally complete under id-111 but were deliberately kept out of navigation (id-111 B-22) pending an IA decision — reachable only by deep-link. The nav they would join is itself IMS-era: a flat bar of bare verbs and stale terms (Browse, Workspaces, Bids) that predates the application abstraction (DR-038), the corpus reframe (DR-025), and the coverage retirement (DR-034). At the same time id-135 is building a net-new corpus /search surface whose nav entry ({135.10}) is explicitly blocked on this decision (id-135 BI-21). Placing one link without an IA would deepen the drift; the owner therefore ratified a product-wide zone model (Option 1) that this spec formalises.

Code-intelligence orientation (verbatim). Per the Planner code-intel binding rule; outputs cited verbatim from the tools, cross-checked against direct file reads.

  • gitnexus_query({query: 'site header top-level navigation links zones command palette', repo: 'canonical'}) → processes: []. Definitions surfaced the two mutation targets and their test harness: Function:components/shell/command-palette.tsx:CommandPalette (startLine 22, endLine 347, module Shell) + Function:components/shell/command-palette.tsx:runCommand (74–78); test harness Function:e2e/helpers/responsive.ts:navigateViaHeader (30–48) and Function:e2e/helpers/responsive.ts:searchFromHeader (97–117), both module Cluster_118; the separate OKF-bundle nav surface Function:lib/okf/parse-index.ts:parseBundleNav (55–103).
  • gitnexus_context({name: 'SiteHeader', repo: 'canonical', file_path: 'components/shell/site-header.tsx'}) → Function:components/shell/site-header.tsx:SiteHeader (startLine 68, endLine 230). incoming.calls: Function:components/shell/auth-aware-chrome.tsx:AuthAwareChrome (sole caller). outgoing.calls: SearchBar (components/browse/search-bar.tsx), BrandLogo, SignOutButton, ThemeSettings, Button, Separator, Sheet/SheetContent/SheetHeader/ SheetTitle/SheetDescription, useUserRole (hooks/use-user-role.ts), cn (lib/utils.ts). processes: [].
  • gitnexus_context({name: 'CommandPalette', repo: 'canonical', file_path: 'components/shell/command-palette.tsx'}) → Function:components/shell/command-palette.tsx:CommandPalette (startLine 22, endLine 347). incoming.calls: Function:app/layout.tsx:RootLayout (sole caller — the palette is mounted globally). outgoing.calls: runCommand, useUserRole. processes: [].

Load-bearing finding (confirmed by direct read): there is no shared nav registry. SiteHeader hardcodes a NAV_LINKS array (components/shell/site-header.tsx:33–67) that feeds both the desktop bar and the mobile drawer; CommandPalette hand-duplicates a separate Command.Group heading="Navigation" list (command-palette.tsx:130–300) that still says Workspaces and Bids. Any IA change is therefore a coordinated edit across three surfaces — desktop bar, mobile drawer, command palette — and is simultaneously a de-drift of the palette. Governing rulings this spec must respect (not re-litigate): DR-025 (corpus reframe: sources are evidence, “Evidence” is a backend term never shown to users), DR-038 (“workspace” is the wrong nav abstraction; application-type instances live under their application), DR-034 (content_items-era coverage retired; only template-completion + governance coverage survive), DR-040 (any new markdown-rendering surface uses Streamdown — informational here; nav renders no markdown).

Goals

Section titled “Goals”
  • Give every homeless corpus surface (references, search, answers, concepts) a principled, discoverable navigation home, surfaced identically to every authenticated user.
  • Ship the id-111 reference UI as the “External sources” Knowledge-zone entry (the ID-118 driver) and the consistent Knowledge-zone slot the id-135 /search entry lands in.
  • De-drift the three navigation surfaces so they agree on labels, membership, and destinations.

Non-goals

Section titled “Non-goals”
  • What /library renders. The IA reserves and points the “Answers” entry at /library as-is; the q_a_pair-viewer repoint and the answer deep-link destination are id-71 family / ID-59 / ID-69 work (RESEARCH §6.2).
  • The workspaces-table → activity-carried-ids data-model migration (DR-038/ID-130). This spec retires the nav label “Workspaces” and the /workspaces launcher route (BI-10, per the S457 owner ruling), but does not migrate or drop the shared workspaces table itself — it is the live store still read by the Intelligence app and procurement instances, migrated opportunistically under DR-038/ID-130. (A broader workspaces-table purge is out of scope — S457 owner ruling: launcher orphans only; the shared table’s migration remains DR-038/ID-130 work.)
  • The OKF human-editable review UI (DR-013 shape). The IA reserves the “Concepts” slot; the editing surface is id-132/id-138 follow-on (RESEARCH §6.4).
  • Retiring /item/new, /item/new/batch (content_items-era) — a backlog cleanup candidate, not decided here.
  • proxy.ts publicRoutes — unchanged. Every surface named here is authenticated (id-111 B-21, id-135 BI-1); no public-route edit is implied.
  • Delivery phasing. This spec defines the ratified target-state IA; whether {118.3}/{118.4} ship all zones in one pass or incrementally is a TECH/PLAN call. Every invariant below is testable against the shipped end-state.

Behavior

Section titled “Behavior”

Zone structure

Section titled “Zone structure”

  1. BI-1 (three zones + utilities). The top-level navigation is organised into exactly three named zones — Applications, Knowledge, Governance — plus the utility slots Home, global search, and Settings. No top-level navigation entry exists outside a zone or a utility slot. (RESEARCH IA-INV-1; OQ-D, OQ-E ratified.)

  2. BI-2 (zone headers). Each zone is presented under its ratified header label — “Applications”, “Knowledge”, “Governance” — on every navigation surface that groups entries (desktop bar and mobile drawer at minimum; the command palette uses the same three group headings for its navigation entries). Header strings are exactly these three words.

  3. BI-3 (membership is closed). Every navigable, user-facing route belongs to exactly one zone or is an explicit utility/contextual exception (BI-15). A route is never listed under two zones, and no zone contains a route that belongs to another zone’s concern.

Knowledge zone (the shared corpus)

Section titled “Knowledge zone (the shared corpus)”

  1. BI-4 (Knowledge membership). The Knowledge zone contains exactly these corpus surfaces, in this order: Search (/search), Answers (/library), External sources (/reference), Concepts (/okf landing — subject to BI-8). No content_items-era surface (/item/new, /browse) appears in the Knowledge zone. (RESEARCH IA-INV-2.)

  2. BI-5 (External sources = the id-111 reference UI). The “External sources” entry navigates to /reference and is the first-class navigation home for the id-111 reference reading UI. Selecting it lands the user on the reference browse/search list; the reference detail route /reference/[id] is reachable from that list. This entry is the ID-118 driver and its presence is the minimum acceptance for “references are surfaced”.

  3. BI-6 (Search = the id-135 Surface A). The “Search” entry navigates to /search and is the id-135 Surface-A corpus search entry ({135.10}). It is placed in the Knowledge zone with requiresEdit: false, satisfying id-135 TECH BI-21 (“ship consistently with whatever id-118 ratifies, never a divergent slot”) and id-135 BI-7. This is distinct from the persistent header search box (BI-16), which remains. (RESEARCH IA-INV-12.)

  4. BI-7 (Answers = /library, reserved slot). The “Answers” entry navigates to /library as it renders today. This spec reserves and labels the slot; it does not change what /library displays (Non-goals).

  5. BI-8 (Concepts entry is landing-conditional). The “Concepts” entry navigates to the OKF index/landing route. If an OKF index/landing route exists at implementation time, the Concepts entry ships in the Knowledge zone. If no such landing route exists (today only /okf/[bundleId] is routable, with no index), the Concepts slot is reserved — defined in the IA and in this spec, but not rendered — rather than blocking this Task on net-new route creation, which is id-132/id-138 territory (RESEARCH §6.4).

    • Resolved (S456 owner ruling, bun scripts/ledger-cli.ts journal 118.1): the reserved-slot treatment is ratified for this Task — the Concepts entry is defined in the IA but not rendered until a landing route exists. The replacement (a /okf landing, likely the next Streamdown surface per DR-040) is owned by the new id-132 investigation/spec subtask, not built here.

Applications zone (domain work)

Section titled “Applications zone (domain work)”

  1. BI-9 (Applications membership = live application_types). The Applications zone lists only live application_types. In v1 that is Procurement (/procurement) and Intelligence (/intelligence). It is the extension seam: a newly-live application_type adds one entry here and nowhere else (DR-038, RESEARCH IA-INV-3). “Research” is not a distinct new application_type — per OQ-A it is a future relabelling of competitor_research, so a “Research” entry appears here only if/when competitor_research comes online, under that label.

  2. BI-10 (Workspaces retired as a nav label — and the launcher route retired outright). The generic top-level “Workspaces” label is removed from every navigation surface. Application-specific instances (e.g. a procurement RFP/bid) are reached inside their owning application, never as a product-wide peer entry. “Workspaces” and “Bids” do not appear as labels anywhere (DR-038; RESEARCH IA-INV-4). Per the S457 owner ruling the /workspaces launcher route is retired outright (not merely de-linked): its four source references are removed (the three nav surfaces plus app/not-found.tsx), the app/workspaces/ route tree and its tests are deleted, and any orphaned launcher data is purgeable across all four DBs. The launcher’s function is superseded by the Applications zone; the shared workspaces table and its live Intelligence/procurement readers are not touched (that data-model migration remains DR-038/ID-130 work — see Non-goals).

Governance zone (curate / review / audit)

Section titled “Governance zone (curate / review / audit)”
  1. BI-11 (Governance membership). The Governance zone contains: Review (/review), Coverage (/coverage), Change reports (/change-reports), Activity (/activity), and (admin-only) Provenance (/provenance). /activity retains its own distinct Governance entry (OQ-C ratified — it does not fold into the home dashboard). The Coverage entry surfaces only the coverage that survives DR-034 (template-completion + governance coverage); it is not a rebuild of the retired content_items-era coverage.

Utilities

Section titled “Utilities”

  1. BI-12 (Home). The brand logo navigates to the home dashboard (/). The mobile drawer additionally shows an explicit “Home” entry above the zones. Home is not a member of any zone.

  2. BI-13 (global search box). The persistent header search box (SearchBar, compact variant) remains present and unchanged in placement/behaviour. It is a utility, distinct from the Knowledge-zone “Search” entry (BI-6).

  3. BI-14 (Settings). The Settings entry (icon in the desktop bar, labelled entry at the foot of the mobile drawer) remains a utility outside the three zones, with its existing active-state on /settings and /settings/*.

  4. BI-15 (contextual-only surfaces stay out of nav). Surface B (/documents/[id]) and its diff route (/documents/[id]/diff) have no top-level navigation slot in any zone; they are reached only contextually (from Search results and citations), preserving id-135 BI-22 / PRODUCT §4. Admin deep-tools (/admin/*) likewise remain out of the top-level nav.

Labels and cross-surface consistency

Section titled “Labels and cross-surface consistency”

  1. BI-16 (no IMS-era labels). No navigation label anywhere across the three surfaces is a bare verb or IMS artefact: “Browse”, “Workspaces”, “Bids”, “Evidence” never appear as user-facing labels. “Evidence” in particular is a backend-only term (DR-025) and is never shown to users. (RESEARCH IA-INV-6.)

  2. BI-17 (ratified label set). The user-facing labels are exactly: Search, Answers, External sources, Concepts (Knowledge); Procurement, Intelligence (Applications); Review, Coverage, Change reports, Activity, Provenance (Governance). “External sources” is the OQ-B-ratified label for /reference (chosen over “Sources” / “References” so future ingest connectors widen the class cleanly and it never conflates with the backend “source” term). (RESEARCH IA-INV-8 with the OQ-B amendment.)

  3. BI-18 (lockstep across three surfaces). The ratified membership, zone grouping, and labels are applied identically across components/shell/site-header.tsx (desktop bar and mobile drawer) and components/shell/command-palette.tsx. The three surfaces never disagree: the same route has the same label and sits in the same zone on each. In particular the command palette’s stale Workspaces entry is removed and its Bids → /procurement entry becomes Procurement under the Applications heading. (RESEARCH IA-INV-7; fixes the §1.3 palette drift.)

  4. BI-19 (command palette de-drift completeness). After this change the command palette’s navigation entries are a superset-consistent reflection of the zones: it exposes at least the Knowledge-zone entries it previously lacked (Search, Answers, External sources) alongside the de-drifted Applications and Governance entries, each routing to the same destination as its site-header counterpart.

Role-gating

Section titled “Role-gating”

  1. BI-20 (Knowledge zone is role-uniform). Every Knowledge-zone entry is read-only and role-uniform: it renders with requiresEdit: false and is visible identically to every authenticated user (admin, editor, reviewer, viewer). No Knowledge entry is hidden by canEdit. This inherits id-111 B-21 and id-135 BI-2. (RESEARCH IA-INV-9.)

  2. BI-21 (no silent audience change elsewhere). Existing per-entry role-gating for Governance and Applications entries is preserved exactly as it is today (e.g. Coverage, Intelligence, Review remain requiresEdit: true; Provenance remains admin-only). The IA change does not silently widen or narrow any entry’s audience except the deliberate Knowledge-zone uniformity in BI-20. (RESEARCH IA-INV-10.)

    • Resolved (S456 owner ruling, bun scripts/ledger-cli.ts journal 118.1): the new Applications-zone Procurement entry is visible to all authenticated users now; RBAC is applied later as its own change, not as a nav-gate here. (Procurement was reached via the old Workspaces link / palette “Bids”, which carried no role gate — so this preserves today’s audience rather than widening or narrowing it.)

Discovery surfaces

Section titled “Discovery surfaces”
  1. BI-22 (full discovery set). Every ratified, rendered navigation entry is reachable from the full discovery set: the desktop nav bar, the mobile drawer, and the Cmd+K command palette. The persistent header search box remains, and the home dashboard is reachable via the logo (all surfaces) plus the explicit mobile “Home” entry. The command palette is in scope as a real, globally-mounted surface, not a future affordance. (RESEARCH IA-INV-11.)

Active-state and accessibility

Section titled “Active-state and accessibility”

  1. BI-23 (leaf active-state). Active-state highlights the current entry using the existing machinery (pathname === href || pathname?.startsWith(href + '/'), site-header.tsx:102–103): /reference/[id] highlights External sources, /search highlights Search, /procurement/[id]/… highlights Procurement, and /documents/[id] highlights nothing at top level (it has no nav slot, BI-15). The active leaf carries aria-current="page". (RESEARCH IA-INV-13.)

  2. BI-24 (grouped-zone active affordance). When a zone is presented as a grouped/disclosure menu, the zone header shows an active affordance whenever any descendant route is active (a user on /reference sees the Knowledge zone marked active), while aria-current="page" remains on the specific active leaf, not the header. (RESEARCH IA-INV-14.)

  3. BI-25 (grouped-menu keyboard + a11y). Any grouped/disclosure zone control is fully keyboard-operable and screen-reader-legible: it is focusable, toggles open/closed with Enter/Space, exposes aria-expanded reflecting its state, moves focus through its members with the arrow keys, closes on Escape returning focus to the header, and closes on outside click or focus leaving the group. Zone members are reachable by keyboard without a pointer. (WCAG 2.1 AA; matches id-111 B-26.)

  4. BI-26 (mobile drawer structure). In the mobile drawer the same three zones appear as labelled sections (headers “Applications / Knowledge / Governance”) with their members listed beneath, preserving the existing explicit “Home” entry at the top and Settings + Sign-out at the foot. Selecting any entry closes the drawer and navigates.

  5. BI-27 (Warm Meridian, semantic tokens, WCAG AA). All new and changed navigation chrome — zone headers, disclosure controls, active/hover/focus states, icons — uses Warm Meridian semantic tokens only (no raw Tailwind colours). Meaning is never conveyed by colour alone: active and focus states carry a non-colour signal (weight/underline/aria-current and a visible focus ring). Contrast meets WCAG 2.1 AA. UK English throughout (labels, aria-labels).

Non-regression

Section titled “Non-regression”

  1. BI-28 (destinations preserved, with one ratified exception). Every route reachable from the old flat nav remains reachable after the change — no destination is dropped, only relabelled and regrouped — except the /workspaces launcher, which is deliberately retired outright per BI-10 / the S457 owner ruling (its function is superseded by the Applications zone). The e2e nav harness (e2e/helpers/responsive.ts:navigateViaHeader / searchFromHeader, Cluster_118) continues to resolve each retained destination.

  2. BI-29 (corpus surfaces unchanged in content). Regrouping and relabelling the nav does not alter what any corpus surface renders: /reference, /search, /library, /browse, /intelligence show the same content post-change as pre-change (id-111 B-22). The change is to navigation only.

  3. BI-30 (authentication unchanged). No surface named here becomes public: proxy.ts publicRoutes is not modified, and every zone entry remains behind authentication (id-111 B-21, id-135 BI-1).