---

name: web description: "Guide agents modifying Observal's Vite/React/TanStack Router web frontend, query hooks, auth storage, registry/admin/traces/insights pages, theme tokens, type centralization, and UI verification." metadata: disco-role: operating disable-model-invocation: true license: Apache 2.0

Observal Web Frontend Router

Use this sub-skill when the task touches the Observal web UI: Vite/React route files, lazy page modules, shared UI components, TanStack Query hooks, auth/session storage, registry/admin/traces/insights pages, theme tokens, frontend type contracts, or Playwright/screenshot verification.

Do not use this sub-skill for CLI command semantics, FastAPI route/business logic, database migrations, harness adapter/session-parser behavior, telemetry hook delivery, release policy, or cross-repo contribution workflow. Route those to the owning sub-skill.

Route the request

• Architecture, route ownership, page/component layout, navigation, theme tokens: read references/frontend-architecture.md.
• API wrapper, TanStack Query hooks, auth storage/refresh, server-fetched harness data, type placement: read references/api-hooks-and-types.md.
• Verification commands, E2E selection, screenshot expectations, and expected signals: read references/ui-testing.md.
• Install, import, auth/API, config, optional dependency, telemetry/harness, and workflow failure recovery: read references/troubleshooting.md.

Non-negotiable rules

1. The frontend is a Vite SPA with React 19 and TanStack Router; it is not Next.js.
2. File routes live under web/src/routes/; complex routes usually lazy-load modules under web/src/pages/. Do not edit web/src/routeTree.gen.ts by hand.
3. Use TanStack Query hooks. Add reusable API calls to web/src/lib/api.ts, wrap them in the closest web/src/hooks/use-*-api.ts module, and export reusable hooks through web/src/hooks/use-api.ts when appropriate.
4. Do not hardcode harness lists or capabilities in frontend code. Use server data from /api/v1/config/harnesses through useHarnesses().
5. Keep shared API response types in web/src/lib/types.ts or one of the files it reexports. Avoid inline shared response types in components.
6. Auth storage is deliberately split: access token in sessionStorage, refresh token and cached profile fields in localStorage. Do not widen localStorage use unless the auth model is intentionally changed.
7. Use semantic OKLCH theme tokens from web/src/app.css and the theme provider. Do not add raw hex/rgb colors or external font CDNs to components.
8. For user-visible UI changes, provide targeted verification and screenshots for touched states before claiming completion.

Default work loop

1. Identify the owning route/page/component/hook from the architecture reference.
2. If new server data is needed, update API types, api.ts, query hook module, and query invalidation before wiring components.
3. Add or change route files with TanStack Router helpers and typed validateSearch where query params matter.
4. Use shared layout, loading, empty, error, table, registry, review, traces, and shadcn/ui primitives instead of one-off patterns.
5. Run the bundled static helper, then the smallest safe frontend checks for the change.
6. Escalate instead of patching around missing backend contracts, CLI command changes, harness telemetry gaps, or deployment policy decisions.