Handbook

Studio route atlas

Use this page as the canonical token table. Deeper UX context lives in the focused guides below (shell, workspace, Docs Health UI, settings, Studio troubleshooting).

Concept · Updated

Focused guides

What it is

Forge Studio (lenses-enterprise React SPA) mounts at /studio/ from python3 -m lenses. Client routes come from lenses-enterprise/src/App.tsx (BrowserRouter + nested <Route> declarations). Each area fans out to JSON endpoints catalogued in http-api-and-routes.html (maintainer build) and summarized for builders in Schemas and API (builders).

When to read it

  • You need URL → API alignment for screenshots, support, or QA.
  • You extended Studio and must document new GET vs POST behavior.

Daily flow (swimlane)

Studio review swimlane

How operator handoff and client inspection align during a typical Studio review session.

  1. Daily flow (swimlane)Frames operator and Studio client responsibilities for one review pass.
  2. Lane AOperator track for initiating and closing the session.
  3. handoffOperator transfers review context into Studio.
  4. shared outcomeBoth lanes converge on a reviewable, agreed result.
  5. Lane BStudio client track for inspection and adaptation.
  6. inspect / adaptClient surfaces routes, APIs, and workspace state for review.
  7. feedbackFindings loop back to refine the handoff or escalate.
Browser routes call /api helpers; persistence lands under .lenses-local

Route families vs network hops

Studio route network hops

How Studio client routes fan out from one Lenses origin to API families and workspace state.

  1. Route families vs network hopsOverview of browser-to-API alignment across Studio surfaces.
  2. Root / intakeStudio mounts at /studio/ on the Lenses HTTP server.
  3. branch AOne route family with its typical JSON endpoints.
  4. branch BSibling family sharing the same origin and persistence model.
  5. branch CAnother family following the same local network hop pattern.
All Studio surfaces share the same Lenses origin; no separate Studio API host

Client route checklist (from App.tsx)

Paths below are relative to / studio / (spaces added to avoid accidental linkification in plain Markdown editors). Token text matches studio-route-doc-coverage.yaml for CI.

Area Path tokens (representative) Typical APIs Notes
Home overview/charts, projects, projects/:name, projects/:name/charts, projects/:name/strategy, projects/:name/branching, projects/:name/forge-run, projects/:name/docs-health, projects/:name/docs-health/master, projects/:name/docs-health/session/:sessionId workspace state, chart bundles, git proxies Project scoping is the busiest subtree.
Discovery search, chat search indices, assistant chat may be gated by LLM config.
Settings settings/llm, settings/fleet, settings/ux-insights, settings/agent-runtime LLM gateway, Fleet jobs, experiments fleet also appears in settings paths.
Governance governance/connectors, governance/audit governance APIs Distinct from methodology knowledge panes.
Productivity toolset, toolset/:name tool runner :name selects packaged automation.
Sites websites, websites/browse/:site blog + workspace markdown indexes Includes Forge SDLC blog surfaces.
Structure wbs, wbs/view WBS readers
Planning plan, plan/matrix, timeline, board, board/:id plan spine, matrix, boards plan/matrix is the matrix lens.
Learning tutorials guided content
Embedded view/docs/*, view/local-site/*, workspace-md, workspace-md/view static file proxies local-site serves selected static previews.
Content blog, blog/post/:slug, doc-management, doc-management/session/:sessionId /api/forgesdlc-blog/*, /api/doc-management/* Doc Management: Hydration v2 sessions (intake → run → approve → promote). See Studio — Doc Management.
Knowledge knowledge/methodology/evidence, knowledge/methodology/decisions, knowledge/methodology/record/:entityId, knowledge/methodology/readiness, knowledge/agentic-bridge methodology registries Includes evidence, decisions, record, readiness, and agentic-bridge.
Foundry foundry, foundry/runs/:runId Dark Factory bounded runs Bounded L1 draft runs with human promote; runs/:runId is a probe/deep-link surface.
Autonomy autonomy-maturity, projects/:name/autonomy-maturity /api/autonomy-maturity/*, /api/project/:name/autonomy-maturity Experimental (flag-gated, default off): observed autonomy level+grade and 0-100 maturity score per project. See Autonomy maturity.
Labs roadmap-section, feature-showcase experimental panes treat as optional / flag-gated.
Wizard blueprints/wizard, blueprints/wizard/session/:sessionId /api/blueprints/wizard/* Session deep links for debugging.

Decision: blank Studio shell

Blank Studio shell decision

Gate whether a blank shell is an API-origin problem or needs deeper troubleshooting.

  1. Decision: blank Studio shellEntry when Studio renders empty or static assets return 404.
  2. Current stateConfirm what the browser shows and which /studio/ URL loaded.
  3. Checkpoint / gateVerify API origin and asset paths before blaming Studio UI.
  4. refine or escalateFix origin, assets, or configuration when the gate fails.
  5. Continue flowProceed with route-family checks when origin and assets look correct.
Check API origin before assuming a Studio bug

Troubleshooting

See Studio — troubleshooting for blank shell, assets, and API-origin checks (includes the same steps formerly duplicated here).

  1. Watch Network while visiting each family above; compare methods to http-api-and-routes.html.
  2. Keep this table aligned with docs/strategy/studio-route-doc-coverage.yaml — CI asserts tokens stay documented.