packages/README.md

packages/ — the single source of truth

Status: design-only. This folder documents the shared-package catalog; the packages are not implemented yet. Standing them up is additive (Phase M1) and breaks nothing. Full design: ../docs/design/MONOREPO_AND_WAVE_B.md.

Every app in ../apps/* (and the legacy ../frontend, ../desktop) consumes these internal packages via the workspace protocol ("@homepilot/x": "workspace:*"), so there is no version drift — a change here propagates to web, desktop, and mobile on their next build.

Catalog

Package	Owns	Representative exports
@homepilot/types	Shared DTOs	Persona, Job, JobEvent, Artifact, ComputeStatus, Device, SupplierPolicy, CreditsWallet
@homepilot/config	Env, constants, client feature flags	getBaseUrl(), flags.sharingTiers, flags.computeModeDefault
@homepilot/api-client	Base HTTP (auth header, retries, errors, transport port)	createClient({ baseUrl, tokenProvider, fetchImpl })
@homepilot/auth	Login, sessions, device pairing, token-storage port	signIn, signOut, useSession, startPairing, TokenStorage
@homepilot/compute-client	Jobs, progress, devices, policy, credits	createImageJob, createVideoJob, editImage, getJobStatus, subscribeToJobEvents, getComputeStatus, listUserDevices, getDevicePolicy, setDevicePolicy, getWallet
@homepilot/core	Domain/product logic	personas, generation-request builders, zod validation, analytics events
@homepilot/ui	Design tokens (+ optional primitives)	tokens (color/spacing/type/motion)

Golden rules

1. No platform APIs in packages. Declare a port (interface); each app injects the adapter (TokenStorage, fetchImpl, EventTransport, Notifier). This keeps shared code pure, testable, and identical across platforms.
2. Types flow down, never up. Apps import @homepilot/types; packages never import from apps.
3. compute-client is the Wave A/B heart. Job creation, progress handling, the compute-status pill data, and Batch 8's device/policy logic live here once and are shared by all apps.