AGENTS.md

1# packages/kit — cavekit, honesty-enforcing React surfaces (MIT, public)
2 
3Embeddable React surfaces that show Caveman savings **without ever lying about their
4provenance**. KIT1 scope: the locked attribution mark + the basis badge + a headless honesty
5core + the trial/usage-origin surface. Zero transport deps.
6 
7## Layout
8- `src/core.ts` — the React-free honesty core (importable via `@caveman/kit/core`): the `Basis` union + `normalizeBasis`/`isVerified`/`basisLabel`.
9- `src/badge.tsx` — `OptimizedByCaveman` (the locked OEM mark) + `BasisBadge`.
10- `src/trial.tsx` — the trial/usage-origin surface: `UsageOriginReport`, `QuotaBadge`, `TrialMoveList` (all basis-labeled).
11- `src/index.ts` — the package surface.
12- `tests/` — `types.test.tsx` (compile-time guards), `core.runtime.mjs` + `badge.runtime.mjs` + `trial.runtime.mjs` (node:test via react-dom/server).
13 
14## Honesty, enforced structurally
15- **basis is a required prop** on `BasisBadge` — omitting it is a compile error (proven by a `@ts-expect-error` in `types.test.tsx`).
16- **unknown basis fails closed** — a value outside the union renders the conservative "Inferred" and is marked `unverified`, never "Verified".
17- **the mark is locked** — `OptimizedByCaveman` has no `label`/`href` prop; a host can display it but not rebrand it.
18- **no monthly projection** — there is no projection API; provenance is shown as given.
19 
20## Conventions
21- Build/test: `make product-build PRODUCT=kit` / `make product-test PRODUCT=kit` (the test script builds first, then runs the type + runtime guards).
22- `verified` is a distinct provenance the kit only ever *renders when given* — it never manufactures it. The wider suite (SavingsCounter, CavePlan, hooks/transport) is deferred (PRD §12).
23 
24See ../../CLAUDE.md (root)
25