Route Intelligence Graph
Prox OS is now a Runtime-first Web OS with public community surfaces,
Purpose
Prox OS is now a Runtime-first Web OS with public community surfaces, owner-scoped Runtime and Studio routes, app registry routes, developer tools, and iframe-backed apps. A per-app screenshot list is no longer enough because the shell, Studio registry, app registry, and public route model together define what a user or agent can open.
The Route Intelligence Graph provides one global front-route inventory that can be read by humans, tools, and future AI-assisted UI capture workflows.
Inventory Sources
The v0 inventory is generated by pnpm route:extract and merges:
- TanStack Router path declarations from
apps/os-shell/src/router.tsx. - App manifests from
packages/apps/*and iframe templates frompackages/runtime/app-registry. - Owner-scoped Runtime and Studio routes from
@prox-os/studio-registryand extracted Studio Engine definition files. - Shell-owned public surfaces such as Launchpad, Settings, Notifications, Community, Studio AI Entry, and Universe.
- Developer app surfaces such as
/app-dev/developer-route-map. - Runtime route patterns such as
/spaces/$spaceId, marked as manual capture because they require an in-memory Space id.
Some sources are still a v0 bridge. Manifest modules are evaluated to collect their typed route metadata, while router patterns remain static route nodes with example paths where they are safe. Future work can replace more manual entries with generated route-tree and registry adapters.
Artifacts
pnpm route:extract writes:
artifacts/route-graph/front-routes.jsonapps/os-shell/src/generated/route-graph/frontRoutes.generated.ts
pnpm route:graph writes:
artifacts/route-graph/front-routes.mmd
The JSON artifact is the machine-readable source. The generated TS module lets the OS Shell render the Developer Route Map without fetching root artifacts at runtime.
Capture Presets
Route intelligence now feeds two capture layers:
- V1 route inventory capture can still visit every capture-enabled route.
- V2 Full Snapshot Preset builds a curated visual checklist from the route inventory plus known shell, Studio, Settings, modal, and external surfaces.
The full preset is explicit-only. AI coding sessions must not run
pnpm capture:full, pnpm capture:preset:full, pnpm capture:routes, or
pnpm capture:changed during ordinary development unless the maintainer
explicitly asks for screenshots. The preset writes grouped local artifacts under
.prox-captures/YYYY-MM-DD_HH-mm-ss/, which remains git ignored.
The v2 preset records mismatches when the current registry differs from expected milestone counts. For example, it records a mismatch instead of inventing missing Site Studio pages, onboarding steps, or future OS Studio dev routes.
Developer Surface
/app-dev/developer-route-map is the Route Intelligence Graph surface. It shows:
- total route count;
- kind distribution;
- capture-enabled count;
- dynamic route warnings;
- grouped route graph cards;
- route rows with path, kind, title, capture priority, and source.
The surface intentionally uses a lightweight grouped graph in v0. React Flow is
available inside @prox-os/flow-studio-engine, but importing it directly into
the Shell route graph would widen the Shell dependency surface for a developer
tool. A future graph-specific package or Flow Studio projection can upgrade the
visualization once the route graph interaction model is stable.
Route Scope
Current Studio screenshots use owner-scoped routes:
/@esmadrider/runtime/os/@esmadrider/studios/ops/dev/studios/device/app-dev/developer-route-map
The route graph treats /@user/runtime/:runtimeSlug and
/@user/studios/:studioSlug as canonical product route patterns.
Boundary
The graph is developer intelligence for the shell and monorepo. It does not add
backend state, database tables, API worker endpoints, or a runtime
packages/os-capture package. Runtime app launching still flows through
existing manifests and shell routing behavior.