/dashboard

name: dashboard
description: Use this skill when contributing to InsForge's shared dashboard package. This is for maintainers editing `packages/dashboard`, which ships in `self-hosting` and `cloud-hosting` modes, and the local `frontend/` shell used for `self-hosting` in this repo.

InsForge Dev Dashboard

Use this skill for dashboard work in the InsForge repository.

Scope

• `packages/dashboard/src/**`
• `packages/dashboard/package.json`
• `packages/dashboard/README.md`
• `packages/dashboard/*.config.*`
• `frontend/src/**`
• `frontend/package.json`

Working Rules

1. Respect the shared-package versus host-app boundary.

• This dashboard is built with React and TypeScript.
• `packages/dashboard/` is the source of truth for the dashboard product.
• The package must support both `self-hosting` and `cloud-hosting` modes.
• Keep self-hosting-only bootstrap, local env defaults, and shell styling in `frontend/`.
• Do not let `packages/dashboard/` depend on `frontend/`.
• If both modes need a capability, define it in the package API first.

2. Preserve dashboard data-flow conventions.

• Follow the flow `service -> hook -> UI`.
• Use `apiClient` for HTTP calls so auth refresh and error handling stay consistent.
• Put request logic in services, data fetching and mutation state in hooks, and rendering/orchestration in UI components and pages.
• Reuse existing contexts, host abstractions, and hooks before creating new global state.

3. Reuse the existing component layers.

• Use `@insforge/ui` for generic primitives.
• Use shared dashboard components when the pattern is already present.
• Keep reusable dashboard UI in `packages/dashboard/`.
• Only add UI to `frontend/` when it is specific to the local self-hosting shell.
• Keep package styles scoped to the dashboard container.

4. Keep the package surface aligned with shared contracts.

• Import cross-package types and Zod-derived shapes from `@insforge/shared-schemas`.
• When backend payloads change, update the related services, hooks, UI, and exported types together.
• Keep `packages/dashboard/src/index.ts` and `packages/dashboard/src/types` aligned with the public package API.
• Never use the TypeScript `any` type. Prefer precise prop, state, API, and hook result types.

Frontend Testing

Use the lowest test layer that covers the risk. Add one focused regression test for bug fixes when practical.

| Change type | Test layer | Location | Command | | --- | --- | --- | --- | | Pure helper, parser, formatter, state reducer | Unit | `packages/dashboard/src/**/__tests__/*.test.ts` | `npm --workspace @insforge/dashboard run test:unit` | | React component behavior, forms, dialogs, conditional rendering | Component | `packages/dashboard/src/**/__tests__/*.test.tsx` | `npm --workspace @insforge/dashboard run test:component` | | Routing, auth redirects, host-mode integration, browser-only behavior | UI smoke | `packages/dashboard/tests/ui/*.spec.ts` | `npm --workspace @insforge/dashboard run test:ui` |

Conventions:

• `npm --workspace @insforge/dashboard run test` runs the full Vitest suite: unit plus component.
• GitHub Actions splits dashboard checks into unit, component, and UI jobs in `.github/workflows/frontend-tests.yml`. Update the workflow when adding or renaming test scripts.
• Unit tests should avoid React rendering and network mocking. Test data transformations directly.
• Component tests use Testing Library with `packages/dashboard/src/test/setup.ts`. Mock hooks, services, and host context at the package boundary; assert user-visible behavior and callback effects, not implementation details or CSS class strings.
• UI smoke tests use Playwright against the local `frontend/` shell. Mock backend API routes in `packages/dashboard/tests/ui/fixtures/`; every mocked route must either fulfill, fallback, or abort. Do not leave requests pending after a test branch.
• Prefer one clear test per user-observable behavior over broad snapshot tests. Avoid brittle assertions tied to copy that is not part of the behavior being protected.

Local debug: viewing cloud-hosting-only UI in self-hosting

**Use when** previewing UI gated on `useIsCloudHostingMode()`, `isInsForgeCloudProject()`, or a PostHog feature flag (e.g. the CTest dashboard variant, `dashboard-v3-experiment === 'c_test'`, the CLI connect panel) while running the local `frontend/` self-hosting shell.

The lowest-friction approach is to **temporarily hardcode** the three gates below to `true`/the new branch, then restart the Vite dev server. These edits bypass real host/project detection and MUST be fully reverted before committing — landing them breaks both self-hosting and cloud-hosting users.

Hardcodes

1. `packages/dashboard/src/lib/config/DashboardHostContext.tsx` — `useIsCloudHostingMode()` → `return true;` (was `useDashboardHost().mode === 'cloud-hosting'`). 2. `packages/dashboard/src/lib/utils/utils.ts` — `isInsForgeCloudProject()` → `return true;` (was the `.insforge.app` hostname check). 3. If the UI is also feature-flag-gated, hardcode the consumer. For CTest: `AppRoutes.tsx` → `const DashboardHomePage = CTestDashboardPage;` and, if relevant, the matching branch in `AppLayout.tsx` for `<ConnectDialogV2>`.

Mark every hardcode with a trailing `// LOCAL DEBUG: <original expression>` comment so revert is a mechanical search.

Revert checklist — run all before committing

1. `git grep -n "LOCAL DEBUG" packages/dashboard/src/` returns zero matches. 2. Each gate is restored to its **original expression**, not just an equivalent value (the `mode === 'cloud-hosting'` comparison, the hostname check, the `getFeatureFlag(...)` call must all be back). 3. Any imports deleted during debug (commonly `DashboardPage`, `getFeatureFlag`, `ConnectDialog`) are restored. 4. `cd packages/dashboard && npm run lint && npm run typecheck` both pass. 5. `git diff` of the four files above shows only intended changes — no `return tru