---

name: frontend-portal description: "React/TanStack Start frontend portal routes, API hooks, runtime configuration, and UI workflows for Open Wearables." disable-model-invocation: true metadata: disco-role: operating license: MIT

Frontend Portal

Use this sub-skill for Open Wearables frontend work in the React/TanStack Start portal: routes, protected pages, auth/session behavior, dashboard/users/detail screens, device pairing, provider coverage, sync monitoring, outgoing webhooks, settings tabs, API hooks/services/query keys, runtime API URL configuration, styling/components, and frontend test/lint/build workflows.

Route the task

• For page routing, layout, auth guards, sidebar navigation, settings tabs, user detail panels, coverage matrix, pairing flows, syncs, webhooks, and reusable UI components, read routes-and-components.md.
• For service modules, apiClient, API_ENDPOINTS, runtime VITE_API_URL resolution, TanStack Query hooks, query-key invalidation, uploads, OAuth connection helpers, and SSE state, read api-hooks-and-state.md.
• For local development commands, Node/pnpm requirements, environment variables, UI change checklists, and frontend verification commands, read workflows.md.
• For symptoms and fixes around auth redirects, stale queries, runtime API URL drift, SSR hydration, provider icons, webhook enablement, sync streams, Tailwind v4, pnpm/Corepack, lint, and build failures, read troubleshooting.md.
• Before or after frontend edits, run the safe metadata/source checker when a checkout is available: python skills/disco/open-wearables/sub-skills/frontend-portal/scripts/check_frontend_metadata.py --repo-root .. The script only reads package metadata and source text; it does not install packages, call the network, or write application files.

Boundaries

This sub-skill owns the portal-facing frontend contract. Route backend API implementation, database models, migrations, auth/token semantics, outgoing webhook delivery internals, and endpoint docs navigation to backend-core. Route provider OAuth strategy internals, coverage declarations, provider factory changes, import normalization, and provider webhook parsing to provider-integrations. Route MCP assistant tools and API-client behavior to mcp-server.

When a UI task spans boundaries, keep the frontend changes here but hand off server-side endpoint shape, permissions, provider capability truth, and docs/API-reference changes to the owning backend sub-skill.

Non-negotiable frontend rules

• Use TanStack Router file routes and centralized route constants from ROUTES / DEFAULT_REDIRECTS; do not add ad hoc path strings for new navigation.
• Use the shared API layer: API_ENDPOINTS, service modules under lib/api/services, apiClient, and TanStack Query hooks under hooks/api.
• Do not read import.meta.env.VITE_API_URL directly in application code. Use API_CONFIG.baseUrl, which is resolved by resolveApiUrl() and the runtime config script.
• Use the query-key factory in queryKeys for all server state and invalidate or update the exact affected keys after mutations.
• Preserve SSR-safe auth guards: browser-only session checks must handle typeof window === 'undefined'.
• Keep Tailwind CSS v4 CSS-first: design tokens live in styles.css; do not reintroduce a JavaScript Tailwind config.
• Prefer existing shadcn/ui primitives, common components, feature components, sonner toasts, and React Hook Form + Zod validation before adding one-off patterns.

Fast start for future agents

1. Classify the request as a route/component task, an API hook/state task, a workflow/tooling task, or a troubleshooting task.
2. Read the linked reference closest to that task; avoid reopening source files unless you are refreshing this generated skill or verifying drift.
3. For new UI backed by an endpoint, define the endpoint constant, service method, query key, hook, route/component usage, and mutation invalidation together.
4. For user-facing navigation, update ROUTES, the TanStack route file, and sidebar/settings tab wiring consistently.
5. Verify with the safe metadata checker, then run pnpm run test, pnpm run lint, pnpm run format:check, and pnpm run build when dependencies are available and the task warrants it.