Working in Headroom

Headroom is a self-hosted web dashboard for AI account allowances, balances and usage. This repository contains the working application and its specification and research.

• Read docs/README.md for the document map and current implementation status.
• Before implementing a provider, read its dossier in docs/providers/ and the validation plan.
• Read ADR 0001 before changing architecture: an official CLI may run once for sign-in; refresh and collection are always direct HTTP from TypeScript.
• For account linking, persistence or security, read the connection design and the data model. Use its enumerations by name; do not invent state names in dossiers or code.
• Keep provider credentials, cookies, authorization codes, personal account identifiers and raw account responses out of source, fixtures, logs and shared artifacts. Use synthetic fixtures.
• Require a separate connection identity and credential boundary for every linked account. A folder path alone is not tenant isolation.
• Treat an unavailable metric as unknown, not zero. Keep monetary balances, credits, percentages and reset inventories in separate units.
• Preserve evidence labels: documented, source-inspected, prior observation, validated, and unvalidated. Label every metric official or private. A successful login does not prove quota access.
• Monitoring must not generate model requests, redeem resets or purchase credits. A mutating account action needs an explicit owner action: a confirmed press in the dashboard, or a rule the owner configured or kept at its owner-approved default, such as use-before-expiry (ADR 0003). Every rule still needs "Allow Account Actions". Agents never enable a rule or run a mutation with real credentials.
• Zed is outside the current scope. A laptop helper is not part of the connection design. Headroom is personal self-hosted software and must not be designed as a hosted multi-user service.
• Run mise run check before claiming any change is done; it covers docs, format, type-aware lint, typecheck, Knip and tests. Use mise run <task> or mise exec -- <command>, never a global Bun. Update the docs index when adding a document.
• Enumerations live in packages/core/src/enums.ts. Add a state there and in the data model together, never in only one place.
• Before changing the Mac app API (packages/view-model/src/app-feed.ts, apps/server/src/routes/app.ts, scripts/app-contract.ts), Mac code that reads a server, or a supported version, follow the app API compatibility skill.
• Start every commit subject with a Conventional Commit type (feat:, fix:, docs: and so on). Release-please sets the version from it; see Releases.
• Pin every dependency to an exact version. Fix a lint or type error at its cause; do not add a disable directive without a one-line reason.
• Before opening or updating a pull request that changes web or Mac views or server, connector, package or HeadroomKit behaviour, follow the PR showcase skill.
• Before changing, adding or reviewing a provider connector, follow the provider connector skill.
• After changing apps/web/src, see the change on screen with the verify web skill.
• Before calling a pull request green or ready, or when its CI fails, stalls or falls behind main, follow the PR CI skill.
• Do not add copied global skills or speculative infrastructure. Record material implementation choices in docs/decisions/.