feat(studio): organize control plane navigation

Implement the information architecture in docs/specs/2026-08-18-harness-studio-information-architecture.md. Keep retained Inspector evidence separate from live AG-UI runs, expose honest foundation states, and preserve responsive experiment navigation without interaction overlays.

Validated with Harness Studio typecheck, 79 Vitest tests, 4 Playwright Chromium flows, 6 doc-link tests, and the root preview health and canvas-module smoke checks.

Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>

Author: phodal

docs/specs/2026-08-18-harness-studio-information-architecture.md

@@ -3,7 +3,7 @@
 ## Traceability
 
 - Spec ID: harness-studio-information-architecture
-- Status: Draft
+- Status: Implemented
 
 ## Intent
 
@@ -19,6 +19,42 @@ Workbench behavior remains authoritative. Studio may organize and embed those
 surfaces, but it must not merge their data models, turn observed associations
 into causal claims, or present roadmap capabilities as implemented.
 
+The supplied research report is treated as a product-direction brief, not as a
+source-backed competitor benchmark. Its useful organizing unit is retained:
+`Harness Revision x Task Suite x Runtime Envelope`; statistical evaluation,
+promotion, collaboration, and registry maturity remain unproven roadmap scope.
+
+## Information Architecture
+
+```mermaid
+flowchart TD
+  Studio["Harness Studio · local control plane"] --> Overview["Overview · operating model and loaded inputs"]
+  Studio --> Inspector["Inspector · Observe"]
+  Studio --> Harnesses["Harnesses · Compose · foundation"]
+  Studio --> Suites["Task Suites · Compose · foundation"]
+  Studio --> Experiments["Experiments · Validate"]
+  Studio --> Registry["Registry · Govern · foundation"]
+
+  Inspector --> Delivery["Delivery Workbench"]
+  Delivery --> Evidence["Capability or Date → Session → Commit or File"]
+  Delivery -. "sandboxed read-only document" .-> Report["HarnessInspectorReportV1 HTML"]
+
+  Experiments --> Bench["Harness Bench · design and comparison notebook"]
+  Experiments --> Live["Live trial · AG-UI observation"]
+  Experiments --> Results["Frozen evidence results"]
+
+  Harnesses -. "future contract" .-> Revision["Harness Revision"]
+  Suites -. "future contract" .-> TaskSuite["Task Suite"]
+  Revision -. "analysis unit" .-> Bench
+  TaskSuite -. "analysis unit" .-> Bench
+  Bench -. "fixed runtime envelope" .-> Runtime["Runtime Envelope"]
+  Results -. "future evidence bundle" .-> Registry
+```
+
+The navigation order follows the operating loop `Observe -> Compose ->
+Experiment -> Explain -> Promote`. `Builder`, `Run`, `Compare`, `Results`, and
+`Workbench` are modes within those durable objects, not peer applications.
+
 ## Acceptance Scenarios
 
 - AC-1: Studio has one persistent primary navigation with `Overview`,
@@ -34,12 +70,14 @@ into causal claims, or present roadmap capabilities as implemented.
   explicit CLI option and opened inside the `Inspector` workspace. The report
   remains read-only and authoritative behind a sandboxed document boundary;
   Studio does not duplicate its report model or rewrite its Workbench in React.
-  When no report is supplied, the UI names the missing input and preserves any
-  available Session Debugger entry.
+  When no report is supplied, the UI names the missing retained-evidence input.
+  A live AG-UI endpoint remains under `Experiments`; it must not make the
+  hard-coded Session Debugger fixture appear to be real Inspector evidence.
 - AC-4: Existing experiment Builder, checkpoint lock, Run/Cancel, synchronized
   comparison selection, Trace, Evidence, live AG-UI run, and frozen verdict
   behavior remain reachable. Their current request, reducer, comparison, and
-  evidence contracts are unchanged.
+  evidence contracts are unchanged; the recorded Session Debugger sample is
+  no longer a default Studio destination.
 - AC-5: `Harnesses`, `Task Suites`, and `Registry` pages expose the intended
   object hierarchy and the current implementation boundary. Unsupported source
   editing, suite curation, promotion, rollback, and revalidation controls are
@@ -94,9 +132,9 @@ into causal claims, or present roadmap capabilities as implemented.
 - AC-3/AC-8: server tests for `/api/config`, `/inspector`, missing-report 404,
   and CLI parsing; browser checks confirm the iframe loads the self-contained
   Workbench and remains sandboxed.
-- AC-4: existing Harness Studio Vitest and Playwright suites remain green,
-  including experiment locking/running, comparison selection, Session Debugger,
-  live AG-UI, and evidence rendering.
+- AC-4: existing Harness Studio model/server coverage remains green; built-app
+  browser checks cover experiment locking/running, comparison selection, live
+  AG-UI, Inspector drill-down, and evidence rendering.
 - AC-6: browser screenshots and measured document widths at 1440 by 900 and
   390 by 844, with console/page errors inspected.
 - Risk: primary navigation can imply unsupported products. Mitigation: every
@@ -109,3 +147,18 @@ into causal claims, or present roadmap capabilities as implemented.
 - Risk: the outer shell can reduce the space available to dense workbenches.
   Mitigation: use a compact rail on desktop, an overlay navigation on narrow
   screens, local scrolling, and direct desktop/narrow browser measurements.
+
+### Implementation evidence
+
+- `npm run build -w @qoder-ai/harness-studio` — passed.
+- `npm run typecheck -w @qoder-ai/harness-studio` — passed.
+- `npm test -w @qoder-ai/harness-studio` — 15 files / 79 tests passed.
+- `npx vitest run test/skills-docs/doc-link-graph.test.mjs` — 6 tests passed;
+  the routing graph was regenerated and remained unchanged.
+- `npm run test:browser -w @qoder-ai/harness-studio` — 4 Chromium flows passed,
+  including desktop and 390 px interaction and overflow checks.
+- In-app Playwright checks at 1440 x 900 and 390 x 844 exercised Overview,
+  primary navigation, Bench, the mobile Bench / Live trial switch, checkpoint
+  overlay, live-run composer, real Inspector Workbench, and Inspector session
+  drill-down. Measured document width matched viewport width and inspected
+  browser logs contained no errors or warnings.

packages/harness-studio/README.md

@@ -1,7 +1,13 @@
 # @qoder-ai/harness-studio
 
-A local React studio for [`@qoder-ai/harness`](../harness/README.md): one UI
-over the evidence and experiment surfaces the Harness toolchain produces.
+A local React control plane for [`@qoder-ai/harness`](../harness/README.md):
+durable Harness objects organize the evidence, inspection, live-run, and
+experiment surfaces the Harness toolchain produces.
+
+- **Harness control plane** — organizes work as `Overview`, `Inspector`,
+  `Harnesses`, `Task Suites`, `Experiments`, and `Registry`. Unimplemented
+  source, suite, and promotion capabilities stay visibly marked as foundations
+  instead of appearing as working controls.
 
 - **Inspector workspace** — embeds an explicitly supplied, self-contained
   Harness Inspector report behind a sandboxed, read-only document boundary.
@@ -32,7 +38,7 @@ npx @qoder-ai/harness-studio --evidence ./harness-readme-compare-evidence
 # Live runs only
 npx @qoder-ai/harness-studio --harness my-agent.harness
 
-# Both surfaces on one port
+# Combined control plane on one port
 npx @qoder-ai/harness-studio \
   --inspector ./harness-inspector.html \
   --harness my-agent.harness \
@@ -73,6 +79,8 @@ src/app/         components plus pure state modules:
                    agui-store.ts     AG-UI event → run view state reducer
                    compare-model.ts  verdict.json → table model
                    sse-client.ts     incremental SSE frame parser
+                   studio-shell-model.ts
+                                        config → IA/readiness projection
 src/server/      static host + /api/config + /api/evidence + embedded /agui
                  read-only /inspector + checkpoint history list/resolve
                  + durable experiment lock
@@ -94,4 +102,5 @@ GitHub Actions `Publish npm` workflow. Local commands only build, test, pack,
 or dry-run; do not publish this workspace from a developer machine.
 
 See the spec:
-[Harness UI and Studio](https://github.com/QoderAI/better-harness/blob/main/docs/specs/2026-08-15-harness-ui-studio.md).
+[Harness UI and Studio](https://github.com/QoderAI/better-harness/blob/main/docs/specs/2026-08-15-harness-ui-studio.md)
+and [Harness Studio information architecture](../../docs/specs/2026-08-18-harness-studio-information-architecture.md).

packages/harness-studio/src/app/App.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState, type ReactNode } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 import type { Icon } from "@phosphor-icons/react";
 import { ArrowRight } from "@phosphor-icons/react/ArrowRight";
 import { Binoculars } from "@phosphor-icons/react/Binoculars";
@@ -21,7 +21,6 @@ import {
   type StudioConfig,
   type StudioDestination,
   type StudioExperimentSurface,
-  type StudioInspectorSurface,
 } from "./studio-shell-model.js";
 
 const NAV_ICONS: Record<StudioArea, Icon> = {
@@ -52,10 +51,11 @@ const EMPTY_CONFIG: StudioConfig = {
 
 export function App(): React.JSX.Element {
   const [config, setConfig] = useState<StudioConfig | undefined>(undefined);
+  const [configFailure, setConfigFailure] = useState<string | null>(null);
   const [area, setArea] = useState<StudioArea>(areaFromHash);
   const [experimentSurface, setExperimentSurface] = useState<StudioExperimentSurface>("experiment");
-  const [inspectorSurface, setInspectorSurface] = useState<StudioInspectorSurface>("workbench");
   const [navigationOpen, setNavigationOpen] = useState(false);
+  const navigationToggleRef = useRef<HTMLButtonElement>(null);
 
   useEffect(() => {
     let cancelled = false;
@@ -65,12 +65,15 @@ export function App(): React.JSX.Element {
         if (!response.ok) throw new Error(`Studio config failed (${response.status}).`);
         const loaded = { ...EMPTY_CONFIG, ...(await response.json() as Partial<StudioConfig>) };
         if (!cancelled) {
+          setConfigFailure(null);
           setConfig(loaded);
           setExperimentSurface(experimentSurfaces(loaded)[0] ?? "experiment");
-          setInspectorSurface(inspectorSurfaces(loaded)[0] ?? "workbench");
         }
-      } catch {
-        if (!cancelled) setConfig(EMPTY_CONFIG);
+      } catch (error) {
+        if (!cancelled) {
+          setConfigFailure(error instanceof Error ? error.message : "Studio configuration is unavailable.");
+          setConfig(EMPTY_CONFIG);
+        }
       }
     })();
     return () => {
@@ -81,18 +84,42 @@ export function App(): React.JSX.Element {
   useEffect(() => {
     const onHashChange = (): void => setArea(areaFromHash());
     globalThis.addEventListener("hashchange", onHashChange);
-    return () => globalThis.removeEventListener("hashchange", onHashChange);
+    globalThis.addEventListener("popstate", onHashChange);
+    return () => {
+      globalThis.removeEventListener("hashchange", onHashChange);
+      globalThis.removeEventListener("popstate", onHashChange);
+    };
   }, []);
 
+  useEffect(() => {
+    if (!navigationOpen) return undefined;
+    const focusFrame = globalThis.requestAnimationFrame(() => {
+      document.querySelector<HTMLButtonElement>(".studio-primary-nav nav button")?.focus();
+    });
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key !== "Escape") return;
+      setNavigationOpen(false);
+      navigationToggleRef.current?.focus();
+    };
+    globalThis.addEventListener("keydown", onKeyDown);
+    return () => {
+      globalThis.cancelAnimationFrame(focusFrame);
+      globalThis.removeEventListener("keydown", onKeyDown);
+    };
+  }, [navigationOpen]);
+
   function openArea(next: StudioArea): void {
     setArea(next);
     setNavigationOpen(false);
-    globalThis.history.replaceState(null, "", `#/${next}`);
+    if (area !== next) globalThis.history.pushState(null, "", `#/${next}`);
   }
 
   if (config === undefined) {
     return <main className="studio-loading"><span className="studio-loading-mark"><GitBranch size={18} weight="bold" /></span><p>Loading Harness control plane…</p></main>;
   }
+  if (configFailure !== null) {
+    return <main className="studio-loading" role="alert"><span className="studio-loading-mark"><GitBranch size={18} weight="bold" /></span><strong>Cannot load Studio configuration.</strong><p>{configFailure}</p></main>;
+  }
 
   const destinations = studioDestinations(config);
   const current = destinations.find((destination) => destination.id === area) ?? destinations[0]!;
@@ -107,30 +134,23 @@ export function App(): React.JSX.Element {
       onSelect={setExperimentSurface}
     />
   );
-  const inspectorNavigation = (
-    <SurfaceNavigation
-      label="Inspector surfaces"
-      items={inspectorSurfaces(config).map((id) => ({
-        id,
-        label: id === "workbench" ? "Delivery" : "Session",
-      }))}
-      active={inspectorSurface}
-      onSelect={setInspectorSurface}
-    />
-  );
+  const contextNavigation = area === "experiments" && experimentSurfaces(config).length > 1
+    ? experimentNavigation
+    : null;
 
   return <div className={`studio-control-plane${navigationOpen ? " navigation-open" : ""}`}>
     <PrimaryNavigation destinations={destinations} current={area} onSelect={openArea} />
-    <button className="studio-nav-backdrop" type="button" aria-label="Close Studio navigation" onClick={() => setNavigationOpen(false)} />
+    <button className="studio-nav-backdrop" type="button" aria-label="Close Studio navigation" onClick={() => { setNavigationOpen(false); navigationToggleRef.current?.focus(); }} />
     <section className="studio-area">
-      <header className="studio-context-bar">
-        <button className="studio-nav-toggle" type="button" aria-label="Open Studio navigation" aria-expanded={navigationOpen} onClick={() => setNavigationOpen((value) => !value)}><SidebarSimple size={17} /></button>
-        <div className="studio-context-title"><small>{AREA_COPY[area].eyebrow}</small><strong>{AREA_COPY[area].title}</strong></div>
+      <header className={`studio-context-bar${contextNavigation ? " has-surface-navigation" : ""}`}>
+        <button ref={navigationToggleRef} className="studio-nav-toggle" type="button" aria-label={navigationOpen ? "Close Studio navigation" : "Open Studio navigation"} aria-expanded={navigationOpen} onClick={() => setNavigationOpen((value) => !value)}><SidebarSimple size={17} /></button>
+        <div className="studio-context-title"><small>{AREA_COPY[area].eyebrow}</small><h1>{AREA_COPY[area].title}</h1></div>
+        {contextNavigation && <div className="studio-context-navigation">{contextNavigation}</div>}
         <div className="studio-context-state"><span className={`availability-dot availability-${current.availability}`} /><strong>{current.status}</strong><span>Local control plane</span></div>
       </header>
       <div className={`studio-surface studio-surface-${area}`}>
         {area === "overview" && <Overview config={config} onOpen={openArea} />}
-        {area === "inspector" && <InspectorWorkspace config={config} surface={inspectorSurface} navigation={inspectorNavigation} />}
+        {area === "inspector" && <InspectorWorkspace config={config} />}
         {area === "harnesses" && <HarnessesWorkspace config={config} onOpen={openArea} />}
         {area === "task-suites" && <TaskSuitesWorkspace config={config} onOpen={openArea} />}
         {area === "experiments" && <ExperimentsWorkspace config={config} surface={experimentSurface} navigation={experimentNavigation} />}
@@ -166,8 +186,10 @@ function Overview(props: { config: StudioConfig; onOpen: (area: StudioArea) => v
   const summary = capabilitySummary(props.config);
   const nextArea: StudioArea = props.config.experimentEnabled
     ? "experiments"
-    : props.config.inspectorEnabled || props.config.aguiEnabled
+    : props.config.inspectorEnabled
       ? "inspector"
+      : props.config.aguiEnabled || props.config.evidenceEnabled
+        ? "experiments"
       : "harnesses";
   const inputs = [
     ["Inspector report", props.config.inspectorEnabled],
@@ -177,7 +199,7 @@ function Overview(props: { config: StudioConfig; onOpen: (area: StudioArea) => v
     ["History adapter", props.config.historyEnabled],
   ] as const;
   const loop = [
-    { step: "01", label: "Observe", detail: "Inspect retained delivery evidence", ready: props.config.inspectorEnabled || props.config.aguiEnabled },
+    { step: "01", label: "Observe", detail: "Inspect retained delivery evidence", ready: props.config.inspectorEnabled },
     { step: "02", label: "Compose", detail: "Name the Harness change", ready: props.config.aguiEnabled || props.config.experimentEnabled },
     { step: "03", label: "Experiment", detail: "Hold task and runtime constant", ready: props.config.experimentEnabled },
     { step: "04", label: "Explain", detail: "Compare outcome and trace evidence", ready: props.config.experimentEnabled || props.config.evidenceEnabled },
@@ -198,25 +220,18 @@ function Overview(props: { config: StudioConfig; onOpen: (area: StudioArea) => v
   </main>;
 }
 
-function InspectorWorkspace(props: {
-  config: StudioConfig;
-  surface: StudioInspectorSurface;
-  navigation: ReactNode;
-}): React.JSX.Element {
+function InspectorWorkspace(props: { config: StudioConfig }): React.JSX.Element {
   const available = inspectorSurfaces(props.config);
   if (available.length === 0) {
-    return <EmptyWorkspace eyebrow="Observed delivery" title="Connect an Inspector report" detail="Render a privacy-filtered Harness Inspector HTML report, then start Studio with --inspector <report.html>. Session inspection becomes available when a Harness runtime is loaded." command="--inspector ./harness-inspector.html" />;
-  }
-  if (props.surface === "session" && props.config.aguiEnabled) {
-    return <div className="debugger-mode"><RunView aguiEndpoint="agui" navigation={props.navigation} /></div>;
+    return <EmptyWorkspace eyebrow="Observed delivery" title="Connect an Inspector report" detail="Render a privacy-filtered Harness Inspector HTML report, then start Studio with --inspector <report.html>. Live runs remain under Experiments until Studio has a retained-session contract." command="--inspector ./harness-inspector.html" />;
   }
   if (props.config.inspectorEnabled) {
     return <section className="inspector-workspace" aria-label="Inspector workspace">
-      <header><div><strong>Inspector Workbench</strong><span>Cross-delivery evidence · read-only</span></div>{props.navigation}<p>Capability / Date → Session → Commit / File</p></header>
+      <header><div><strong>Inspector Workbench</strong><span>Cross-delivery evidence · read-only</span></div><p>Capability / Date → Session → Commit / File</p></header>
       <iframe title="Harness Inspector Workbench" src="inspector" sandbox="allow-scripts" referrerPolicy="no-referrer" />
     </section>;
   }
-  return <div className="debugger-mode"><RunView aguiEndpoint="agui" navigation={props.navigation} /></div>;
+  return <EmptyWorkspace eyebrow="Observed delivery" title="Connect an Inspector report" detail="Inspector requires retained, privacy-filtered evidence. It never substitutes the recorded Session Debugger fixture for a real workspace." command="--inspector ./harness-inspector.html" />;
 }
 
 function ExperimentsWorkspace(props: {