# Project conventions

Always read `AGENTS.md` first — it lists every skill available via `@raredays/*`
packages. Use them before authoring components, modules, or providers from
scratch.

## Quick orientation

This app was scaffolded with `create-raredays-app` and consumes the RareDays
framework via `@raredays/*` workspace deps. Conventions:

- **Components**: prefer composing from `@raredays/components` (shadcn-flavored,
  Tailwind v4, browser-tested with vitest+playwright). When you do author new
  components, follow the patterns documented in
  `pnpm exec skillex query --package @raredays/components`.
- **Server logic**: use `@raredays/core`'s provider/port pattern. Identity,
  billing, notifications, CMS, etc. are wired in `app/lib/runtime.ts` —
  edit there to swap providers, don't sprinkle SDK calls through the codebase.
- **Tests**: vitest in happy-dom (`pnpm test`), with no browser mode. Tests sit
  next to their code as `app/**/*.test.ts` or `.test.tsx`; a component test
  renders it with `@testing-library/react`, which `raredays new component` sets
  up. Real-browser behavior (focus, layout, CSS) is tested upstream in
  `@raredays/components` (framework ADR-0029). Conformance harnesses ship in
  each `@raredays/*` module's `/testing` export and exercise every provider
  against the same invariants.
- **Lint/format**: `pnpm check` runs lint + format-check + style + typecheck.
  Pre-commit hook (if you add one) should call this.

## Don't

- Re-implement primitives that already exist in `@raredays/*`. Always query
  skillex first.
- Edit code in `node_modules/@raredays/*` directly. If a provider needs
  changing, file a framework issue or PR upstream.
- Commit code with failing lint/format/style/test. `pnpm check` should be
  green before every commit.

## Skillex

Skills from installed `@raredays/*` packages are auto-discovered. To refresh
the index after adding a new dependency:

```sh
pnpm exec skillex refresh
```

Query patterns:

```sh
pnpm exec skillex query --search "<concepts>"
pnpm exec skillex query --package "@raredays/components"
pnpm exec skillex query --topic identity
```

## Before client handoff

`@raredays/dev` is a RareDays-internal devDependency (it ships the
`report-framework-issue` skill, which targets the framework's private repo and
board). Remove it before handing this project to a client:

```sh
pnpm remove @raredays/dev
pnpm exec skillex refresh
```