ADR-0032: Navigation Reorganization¶

Status: Proposed Date: 2026-05-23 Related: ADR-0031 (entity header pattern lands inside this nav structure)

Related update: This ADR's navigation structure (Dashboard | Work | Library | Admin) is preserved. ADR-0039 introduces knowledge as a "lens" pattern rather than a top-level nav section — knowledge surfaces contextually on entity detail pages (Run detail, Show detail) and via search/command palette. Promotion to top-level nav is deferred until curation workflows exist; this ADR's structure remains canonical for v1.

Context¶

Studio's top navigation today lists ten entity types as siblings at the same visual weight (see apps/studio/frontend/components/Shell.tsx:15):

Projects | Schedules | Playbooks | Agents | Plugins | Shows | Invocations | Runs | Teams | Admin

There is no Dashboard entry in the live nav — / renders the dashboard, but it is reachable only via the project chip or by typing the URL.

This mirrors the backend ontology accurately. But operationally, the ten items are not equivalent — they answer different questions and are visited at different cadences. The current flat structure gives "Plugins" (browsed weekly) the same visual prominence as "Runs" (opened many times per day). The cost is scan time on every page load, plus the dashboard's invisibility.

1. Flat nav is not grouped by intent¶

The user thinks in workflows: check the queue → open a failing run → inspect the show that spawned it → maybe edit a playbook. Not: navigate to the seventh item in the bar. Grouping by operational intent (work / library / admin) lets the operator predict where to click without reading every label.

2. Schedules is mis-located if we keep flat nav¶

Schedules was added in ADR-0027 as a CRUD page for cron / interval / github-poll triggers that fire agent runs. Schedules belong with work (they create work) — not with admin (DB health, prune, vacuum). The current flat nav doesn't force a decision; a grouped nav does.

3. "Observability" looks tempting but is a junk drawer today¶

The ChatGPT review proposed an Observability top-level group for logs, traces, metrics, artifacts. Studio has none of these as first-class surfaces yet. Traces are not modelled; logs live on individual runs; metrics are inline on the dashboard; artifacts are already split between runs/<id>/artifacts/ and the artifacts table (ADR-0021). Creating an Observability group now would either be empty or would silo features that already live (correctly) on their parent entity. Defer.

4. Power users still need direct URLs¶

The current routes (/runs, /shows, /schedules, ...) are stable and bookmarkable. A nav redesign must not change the underlying routes — only how they are grouped in the menu.

Decision¶

Replace the flat top nav with a four-group structure:

Dashboard | Work ▾ | Library ▾ | Admin ▾

Observability is not created. Projects is the project selector (top-right or persistent global filter), not a nav item — see Section 4.

1. Group rationale¶

Dashboard: single most-visited surface. Stays at the top level. This is where the Attention Queue (ADR-0030) lives.

Work: things currently happening or recently happened.

• Shows — orchestrated multi-play workflows
• Runs — individual agent runs / sessions
• Teams — collaborative multi-agent sessions
• Invocations — skill-level groupings of runs
• Schedules — definitions that produce future runs (ADR-0027). They belong here because their output is work. The contrast: pruning is admin; producing is work.

Library: capabilities, not instances. Browse-mode surfaces.

• Playbooks — reusable orchestration definitions
• Agents — reusable agent role profiles
• Plugins — marketplace plugins
• Skills — individual skill files from plugins

Admin: maintenance and system health. Lower frequency, higher consequence.

• Health — DB health, phantom sessions, WAL pressure
• Maintenance — checkpoint, vacuum, prune, classify

2. Visual treatment¶

The four groups render as top-level menu items with hover-to-expand submenus (or click-to-expand on touch devices). The current tabs + icon layout is replaced with a thinner nav row:

┌─ Dashboard ─ Work ▾ ─ Library ▾ ─ Admin ▾ ─────────── [project: lionagi ▾] ─ [≡]
│
│  (Page header / breadcrumb here, e.g. Work › Shows › sweep)
│
│  page content...

Submenu items reveal on hover (200ms delay) or click. The expanded group is highlighted, the current page is bolded. The visual styling otherwise matches the existing nav (same fonts, same colors, same icons per item — borrowed from ADR-0025's color tokens for the hover-active states).

Breadcrumbs above the page content show Group › Section › Item (e.g., Work › Runs › e288a6e2493f), giving an always-visible "where am I" that the flat nav currently lacks.

3. Route changes¶

Most direct URLs are unchanged; two need transitions:

Two real route changes:

1. /admin splits. The combined page becomes two routes (/admin/health and /admin/maintenance). A 308 redirect from /admin → /admin/health lives in next.config.mjs for one release; the redirect can be removed in the release after.
2. /skills becomes nav-promoted. The page already exists, so this is not a new route — only a nav visibility change.

All other URLs are byte-stable. Bookmarks and CLI URL output continue to work without changes.

4. Projects: chip, not nav item¶

/projects becomes the project list page (existing), but the nav slot it currently occupies disappears. The active project is represented as a chip in the top-right corner of the nav bar:

[project: lionagi ▾]

Clicking the chip opens a project switcher (popover with project list + "View all projects" link to /projects). The chosen project becomes a global filter applied to list pages (/runs, /shows, etc.).

This matches the operator mental model: project is context, not navigation. You don't navigate to a project — you work within a project and navigate to its work / library / admin.

5. Skills promoted to nav-level¶

/skills already exists as a page (apps/studio/frontend/app/skills/page.tsx) but is not currently reachable from the top nav — users find skills via /plugins/<name> detail pages. Promoting Skills to a sibling of Plugins matches the user mental model (skills are the thing they invoke; plugins are the delivery mechanism).

This ADR is a nav change, not a new page. The existing Skills list keeps its current behaviour (read-only listing of SKILL.md files from ~/.claude/plugins/ and the marketplace directory). CRUD is owned by the marketplace plugin tooling, not Studio.

6. Admin: separate Health from Maintenance¶

The Admin page today bundles DB health (size, WAL, phantom sessions) with maintenance actions (prune, checkpoint, vacuum) on one screen. Split:

• /admin/health — read-only view of current system state. Renders the DB health strip and a read-only phantom sessions table (no checkboxes, no action buttons). Includes a "Manage in Maintenance →" link to the mutating surface.
• /admin/maintenance — actions that mutate state (prune selected, prune all phantom), each gated by a window.confirm() dialog per the ADR-0031 EntityAction.requires_confirm pattern.

The split clarifies which surface is "look" vs "act". Today the bundle makes routine inspection feel risky (the prune button is right there).

Scope clarification (v1): Only prune lands as a maintenance action in v1 because the backend admin router currently exposes only POST /api/admin/prune. checkpoint and vacuum are deferred to a follow-up that first adds POST /api/admin/checkpoint and POST /api/admin/vacuum endpoints (today these operations exist as li state checkpoint / li state vacuum CLI subcommands, not as HTTP endpoints). When those endpoints land, this ADR is amended in place and the corresponding buttons join the Maintenance page with the same confirmation pattern.

7. Mobile / narrow-viewport behavior¶

The nav collapses into a hamburger menu (≡) on viewports under 768px. The four groups become a vertical accordion in the drawer. This matches the existing dashboard responsive breakpoint.

This is not a fully-designed mobile experience — Studio is desktop-first (ADR-0008 §"Studio v1 scope"). The hamburger ensures nothing is unreachable on a narrow viewport, not that the experience is delightful.

8. File map¶

Modified files:

apps/studio/frontend/components/nav/TopNav.tsx          # group structure
apps/studio/frontend/components/nav/NavGroup.tsx        # new: group with submenu
apps/studio/frontend/components/nav/ProjectChip.tsx     # new: top-right chip
apps/studio/frontend/components/nav/Breadcrumb.tsx      # new: above page content
apps/studio/frontend/components/nav/types.ts            # NavGroup, NavItem types
apps/studio/frontend/components/Shell.tsx               # consume new nav structure
apps/studio/frontend/app/layout.tsx                     # nav composition
apps/studio/frontend/app/admin/page.tsx                 # delete: replaced by 308 redirect
apps/studio/frontend/app/admin/health/page.tsx          # new: extracted health view
apps/studio/frontend/app/admin/maintenance/page.tsx     # new: extracted maintenance view
apps/studio/frontend/app/skills/page.tsx                # existing — no code change,
                                                        # only nav-level promotion
apps/studio/frontend/next.config.mjs                    # add 308 (permanent) redirect:
                                                        #   /admin -> /admin/health
                                                        # (remove the redirect one
                                                        #  release later)

No backend changes.

9. Effort¶

One PR, 1-2 days. The Skills page is the only net-new surface; it's a file-listing component that reads from the marketplace directory and renders SKILL.md frontmatter — similar to the existing Playbooks page.

Consequences¶

Positive

• Operators scan a 4-item top bar instead of an 11-item bar. The cognitive scan cost drops on every page navigation.

• Schedules sits with its operational siblings (Runs, Shows) instead of among system maintenance.

• Admin splits cleanly into "look" (Health) and "act" (Maintenance), reducing accidental-click risk on the maintenance actions.

• The project chip pattern matches industry convention (GitHub, Linear, Stripe) and frees the top nav for what to do, not whose project you're in.

• Skills become discoverable in the nav for the first time (the page itself already exists).

• No backend changes; entirely a frontend reshuffle.

• Most direct URLs are byte-stable. The only exception is /admin, which 308-redirects to /admin/health for one release before being removed. Bookmarks and CLI URL output continue to work.

Negative

• Hover-expand submenus are a new interaction on Studio. Need to ensure click-to-expand also works (accessibility, touch devices).

• The breadcrumb adds a row of vertical pixels above every page. Roughly 24px taller content area on every page. Acceptable.

• The four-group taxonomy is opinionated. Some users might want Schedules in Admin or Invocations in its own slot. The grouping is reversible — promote / demote a section if usage data shows it's wrong.

• Splitting Admin requires URL changes for /admin → /admin/health

• /admin/maintenance. Old /admin URL needs a redirect to /admin/health for one release.

Alternatives Considered¶

Non-Goals¶

• No command palette in v1. Keyboard-driven navigation (Cmd+K) is a separate, larger design. Defer.

• No saved views / filtering UI. "My failed runs", "schedules I own", etc. — deferred until the basic structure is in place.

• No customizable nav. Operators cannot rearrange groups or pin items in v1.

• No notification badges on nav items. Attention Queue surfaces counts; nav stays clean.

• No tabs within the page header above the breadcrumb. Existing page-level tabs (e.g., Summary / Timeline / Artifacts on Run detail) stay intact below the breadcrumb.

• No multi-project filtering. The project chip selects exactly one project at a time (matches existing /api/...?project=X filter behavior).

• No mobile-first redesign. Mobile gets a working hamburger; the desktop layout is the primary target.

References¶

• ADR-0008 — Studio is single-user, desktop-first.
• ADR-0026 — Project is per-session context; the chip pattern matches this model.
• ADR-0027 — Schedules feature being relocated under Work.
• ADR-0030 — Attention Queue lives at the top of the Dashboard.
• ADR-0031 — Entity headers render inside the page body, below the breadcrumb.
• ChatGPT frontend design review (external) — proposed the 4-group structure; this ADR adopts it with the Observability deferral, project-as-chip, and Admin split.

Prior art¶

• GitHub navigation (Code / Issues / Pull requests / Actions / Projects / Wiki / Security / Insights / Settings) — nine top-level items, but visually grouped by frequency. Studio's four-group approach achieves the same end with less width.

• Linear navigation — left sidebar with Inbox / My Issues / Active / Backlog (work) and Views / Projects / Members (library). Same intent split.

• Stripe Dashboard — Home / Payments / Customers / Products / Reports / More with a workspace switcher chip in the top-right. Direct precedent for the project chip pattern.