@inbeat/standards 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+## [0.7.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.6.1...standards-v0.7.0) (2026-10-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* consumers must drop the @inbeat registry line from .npmrc/bunfig and the NODE_AUTH_TOKEN setup.
+
+### Features
+
+* publish [@inbeat](https://github.com/inbeat) packages publicly on npm ([#27](https://github.com/Genoux/ib-toolkit/issues/27)) ([2bd9f53](https://github.com/Genoux/ib-toolkit/commit/2bd9f53c2d4dd030bdee037b8b1dce1e1bb828b5))
+
+## [0.6.1](https://github.com/Genoux/ib-toolkit/compare/standards-v0.6.0...standards-v0.6.1) (2026-10-01)
+
+
+### Bug Fixes
+
+* **standards:** ship template changes in standards releases ([#25](https://github.com/Genoux/ib-toolkit/issues/25)) ([176a543](https://github.com/Genoux/ib-toolkit/commit/176a543499eac56cc131595bb9c011c6664f06cc))
+
+## [0.6.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.5.0...standards-v0.6.0) (2026-10-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* remove app logic and finish the toolkit ([#21](https://github.com/Genoux/ib-toolkit/issues/21))
+
+### Bug Fixes
+
+* **config:** require biome 2.5 and accept biome.jsonc ([#19](https://github.com/Genoux/ib-toolkit/issues/19)) ([178dc95](https://github.com/Genoux/ib-toolkit/commit/178dc95b4c9a041970458526c3985f5a225a7caf))
+
+
+### Code Refactoring
+
+* remove app logic and finish the toolkit ([#21](https://github.com/Genoux/ib-toolkit/issues/21)) ([cecf25a](https://github.com/Genoux/ib-toolkit/commit/cecf25a670b2177f8b1e8cc3645023a1219a2626))
+
+## [0.5.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.4.0...standards-v0.5.0) (2026-10-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* **standards:** `ib add` is removed (use the vendor init CLIs); `ib check` now requires the shared config presets.
+
+### Features
+
+* **standards:** drop add-ons, add ib mcp, enforce shared presets ([#17](https://github.com/Genoux/ib-toolkit/issues/17)) ([9eb8410](https://github.com/Genoux/ib-toolkit/commit/9eb84108432dda5e2a2da312a7bc70299e09c0c9))
+
+## [0.4.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.3.0...standards-v0.4.0) (2026-09-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* **standards:** sync skills to .agents/skills only ([#15](https://github.com/Genoux/ib-toolkit/issues/15))
+
+### Features
+
+* **standards:** sync skills to .agents/skills only ([#15](https://github.com/Genoux/ib-toolkit/issues/15)) ([cd3e8a2](https://github.com/Genoux/ib-toolkit/commit/cd3e8a21f028790ad84c26dc1cc832475885c461))
+
+## [0.3.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.2.0...standards-v0.3.0) (2026-09-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* **standards:** create always makes the base app, add-ons only via ib add ([#13](https://github.com/Genoux/ib-toolkit/issues/13))
+
+### Features
+
+* **standards:** create always makes the base app, add-ons only via ib add ([#13](https://github.com/Genoux/ib-toolkit/issues/13)) ([5f7e0c3](https://github.com/Genoux/ib-toolkit/commit/5f7e0c38a49b0f5dafd3dd9ae6472df03067f830))
+* **standards:** point any ai tool at the guides and the brief ([#12](https://github.com/Genoux/ib-toolkit/issues/12)) ([b419b4a](https://github.com/Genoux/ib-toolkit/commit/b419b4ad8e11a60ee704b4435add702fd9bd78b2))
+
+## [0.2.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.1.2...standards-v0.2.0) (2026-09-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* **ui,next:** harden ui peers, csp and rate-limit ip ([#8](https://github.com/Genoux/ib-toolkit/issues/8))
+
+### Features
+
+* add ib create and ib add ([#9](https://github.com/Genoux/ib-toolkit/issues/9)) ([aef8b6e](https://github.com/Genoux/ib-toolkit/commit/aef8b6e161ac66167b69d67ae279983976b17b09))
+
+
+### Bug Fixes
+
+* **standards:** keep the version out of the managed block ([#11](https://github.com/Genoux/ib-toolkit/issues/11)) ([43efd08](https://github.com/Genoux/ib-toolkit/commit/43efd081446d8cd836b1de68f0049ecacf45d872))
+* **ui,next:** harden ui peers, csp and rate-limit ip ([#8](https://github.com/Genoux/ib-toolkit/issues/8)) ([4ad992c](https://github.com/Genoux/ib-toolkit/commit/4ad992c96181a21c3dbee0bb542d9afe32163deb))
+
+## [0.1.2](https://github.com/Genoux/ib-toolkit/compare/standards-v0.1.1...standards-v0.1.2) (2026-09-30)
+
+
+### Bug Fixes
+
+* resolve workspace ranges from manifests on publish ([#5](https://github.com/Genoux/ib-toolkit/issues/5)) ([0f4328e](https://github.com/Genoux/ib-toolkit/commit/0f4328eb0897501380880f429a952d9d228563a2))
+
+## [0.1.1](https://github.com/Genoux/ib-toolkit/compare/standards-v0.1.0...standards-v0.1.1) (2026-09-30)
+
+
+### Bug Fixes
+
+* ship compiled js from core and next ([#3](https://github.com/Genoux/ib-toolkit/issues/3)) ([8fef50a](https://github.com/Genoux/ib-toolkit/commit/8fef50aa87679bcf3c328fe4ca11a351434e2dda))

package/agents/app-section.md

@@ -0,0 +1,22 @@
+## This app
+
+### Product brief
+
+- 
+
+### Stack deltas
+
+- 
+
+### Deliberate deviations
+
+| What | Why | Owner |
+|---|---|---|
+
+### Known gaps
+
+- 
+
+### Learned facts
+
+- 

package/agents/standard.md

@@ -0,0 +1,114 @@
+## inBeat toolkit standard
+
+Stack: Next.js App Router, TypeScript strict, React 19, Drizzle + Neon, Clerk, Sentry, Vercel, Bun.
+Shared code comes from `@inbeat/*` (ui ships source via `transpilePackages`; core and next ship compiled JS). Never fork a toolkit
+file into the app; change it in ib-toolkit.
+
+### Before you build
+
+- If "Product brief" under "This app" is empty, write the user's brief there first (problem,
+  users, core flows), then build.
+- Read the matching guide before the work, whatever tool you are: `.agents/skills/ib-ui/SKILL.md`
+  (component catalog, UI rules) before any UI, `.agents/skills/ib-feature/SKILL.md` for a new
+  feature, `.agents/skills/ib-toolkit/SKILL.md` for actions, routes, auth, env and rate limits.
+- Read the version-matched Next.js docs in `node_modules/next/dist/docs/` before Next.js work.
+
+### Two tiers
+
+- **Required** (CI enforces): `@inbeat/config` presets (extend them: biome, tsconfig, dependency-cruiser, vitest; `ib check`
+  enforces it), the action/route error contract,
+  `securityHeaders()`, Sentry presets, rate limiting on public entry points, this block.
+- **Opt-in**: `@inbeat/ui` blocks, extra layer rules.
+- A deliberate departure is allowed when the app states it under **Deliberate deviations**
+  in its own section of this file (what, why, owner). Undeclared drift is a bug.
+
+### Layout
+
+```
+src/app/                    routes + composition; private pieces in _components/
+src/features/<f>/actions/   "use server" mutations, one per file, via action()
+src/features/<f>/queries/   server-only reads for Server Components
+src/features/<f>/server/    domain commands and policies ("server-only", no "use server")
+src/features/<f>/components/ hooks/ lib/ schemas.ts types.ts
+src/entities/               leaf: domain types, zod schemas, constants
+src/integrations/<vendor>/  external adapters
+src/shared/{components,config,lib,hooks}/
+src/db/schema/<table>.ts, src/db/migrations/
+```
+
+Layers (dependency-cruiser, `@inbeat/config/dependency-cruiser`): features never import each
+other; entities import nothing internal; db imports entities only; shared and integrations never
+import features or app.
+
+### Reads and writes
+
+| Need | Use |
+|---|---|
+| Page data | Server Component calls `queries/*` |
+| Mutation from own UI | `action()` from `@inbeat/next/action`, returns `Result` |
+| Client polling, infinite lists | `GET` via `route()`, React Query |
+| Webhooks, presign, redirects, cron | `route()` |
+
+Server actions are queued per client; never use them for reads.
+
+### Errors
+
+- Actions resolve to `{ ok: true, data } | { ok: false, error, code?, errorId? }`.
+  Routes answer `{ error, code, errorId? }` with the status from `APP_ERROR_STATUS`.
+- Throw `AppError(kind)` from `@inbeat/core/errors`; never `new Error("Forbidden")`.
+  Kinds: validation, auth, forbidden, not_found, conflict, rate_limited, db_transient,
+  db_query, timeout, external_service, unknown.
+- Unexpected errors are classified, reported once, and replaced with safe copy + `ERR_xxxx`.
+- Log with `createLogger()`; ids only, never emails, names or payloads. No `console.log`.
+
+### Auth
+
+- New apps start without authentication; set it up per "Integrations" in the `ib-toolkit` skill.
+- `authorize` is required on every `action()` and `route()`, and it is the app's own check
+  (session, roles, ownership). `publicAccess` is an explicit choice and must be rate limited.
+- Redirect targets go through `safeRedirectPath`. `APP_URL` comes from env, never `Host`.
+
+### Security baseline
+
+- `securityHeaders()` in `next.config.ts`; CSP report-only until a clean week, then enforce.
+- `createRateLimiter()` (Upstash in prod) on every unauthenticated entry, presign and LLM call.
+- Webhooks verify the sender's signature. Secrets only in Vercel env.
+- `import "server-only"` in every module touching secrets or the DB.
+- Env through `@t3-oss/env-nextjs` + `@inbeat/core/env` fragments; no `process.env` elsewhere.
+
+### Data
+
+- UUID PKs, `timestamp({ withTimezone: true })`, snake_case, one table per file.
+- Migrations are generated, reviewed, forward-only, expand then contract; they run after the
+  build resolves. Never run migrations or destructive SQL against production unless the user
+  says "apply migrations to prod".
+- Deletes that own storage objects collect keys in the transaction and delete after commit.
+
+### UI
+
+- UI comes only from `@inbeat/ui` (catalog in the `ib-ui` skill) plus layouts composed from it. If a
+  component or variant is missing, stop and flag it for ib-toolkit; never invent, copy or patch
+  one (a workaround needs the user's OK and a `// toolkit-gap:` comment).
+- Primitives and generic blocks from `@inbeat/ui/components/*`; tokens from
+  `@inbeat/ui/theme.css`. A block moves to the toolkit only once an app actually uses it.
+- Buttons are `rounded-full` with no destructive variant; destructive flows use
+  `DestructiveActionDialog` from `@inbeat/ui`. Icon-only buttons get a tooltip. Lists use
+  `DataTableShell` + `DataTable`; empty lists use `EmptyState`.
+- Radix via `radix-ui`; animation via `motion` only.
+
+### Simplicity
+
+- Reuse before writing: the `ib-ui` catalog, `@inbeat/*`, the stdlib, then the platform. No speculative abstractions, config or "for later" scaffolding.
+- Comments carry only what code cannot. A deliberate shortcut is marked `// shortcut: <ceiling>; <upgrade path>`.
+- Claude Code reads `AGENTS.md` only when the app has no `CLAUDE.md`; if one exists it must contain an `@AGENTS.md` line (`ib check` fails otherwise).
+
+### Tests and CI
+
+- Vitest colocated `*.test.ts` for every `server/` command, policy and `lib/` function;
+  `*.integration.test.ts` against a Neon branch; Playwright in `tests/e2e` against previews.
+- CI: biome, tsc, dependency-cruiser, vitest, migration check, `ib check`, gitleaks.
+
+### Commits
+
+Conventional commits, lowercase, present tense, title under 60 chars. No AI attribution.
+Never commit, push or open a PR unless explicitly asked.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@inbeat/standards",
+  "version": "0.7.0",
+  "description": "Agent standards for inBeat apps: managed AGENTS.md block, skills under .agents/skills, ib CLI",
+  "type": "module",
+  "bin": {
+    "ib": "./src/cli.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "agents",
+    "skills",
+    "template",
+    "!src/**/*.test.ts",
+    "!template/**/node_modules",
+    "!template/.next",
+    "!template/.turbo",
+    "!template/coverage",
+    "!template/.vercel",
+    "!template/next-env.d.ts",
+    "!template/*.tsbuildinfo",
+    "!template/**/.env",
+    "!template/**/.env.[!e]*"
+  ],
+  "exports": {
+    "./sync": "./src/sync.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun --bun vitest run"
+  },
+  "devDependencies": {
+    "@inbeat/config": "^0.7.0",
+    "vitest": "^4.1.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Genoux/ib-toolkit.git",
+    "directory": "packages/standards"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}

package/skills/ib-feature/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: ib-feature
+description: Scaffold or extend a feature slice in an inBeat app following the toolkit layout (actions, queries, server, components, schemas, tests). Use when adding a new feature, entity, page with data, or when the user mentions ib-feature or @ib-feature.
+---
+
+# ib-feature
+
+## Steps
+
+1. **Schema.** Table in `src/db/schema/<table>.ts` (uuid pk, `timestamp({ withTimezone: true })`,
+   snake_case). Export from `src/db/schema/index.ts`. `bun run db:generate`, then read the SQL.
+   Never apply to production unless the user says "apply migrations to prod".
+2. **Entities.** Shared types, zod schemas, constants in `src/entities/<name>.ts` if more than
+   one feature needs them; otherwise `src/features/<f>/schemas.ts` and `types.ts`.
+3. **Server.** `src/features/<f>/server/<verb>-<noun>-record.ts` with `import "server-only"`.
+   Pure DB/domain logic, takes validated input plus the viewer id, returns data or throws
+   `AppError`. Policies: `assert-can-<verb>.ts`.
+4. **Queries.** `src/features/<f>/queries/get-<noun>.ts` / `list-<nouns>.ts`, `import "server-only"`,
+   run the app's own authorize check first when the app has auth, called from Server Components.
+5. **Actions.** `src/features/<f>/actions/<verb>-<noun>.ts` with `"use server"` and `action()`.
+   One export per file. `revalidate` the pages that show the data.
+6. **Routes** only for client polling, infinite lists, webhooks, presign: `route()` in
+   `src/app/api/<f>/.../route.ts`.
+7. **UI.** Page in `src/app/.../page.tsx` (Server Component) renders feature components from
+   `src/features/<f>/components`. Client leaves call actions and handle `Result`.
+8. **Tests.** Colocated `*.test.ts` for every `server/` command and policy and every `lib/` helper, including `src/shared/lib`.
+9. **Check.** `bun run lint && bunx tsc --noEmit && bun run test && bun run lint:arch`.
+
+## Naming
+
+- Files kebab-case, one operation per file, named exports, no barrels (except `db/schema`).
+- Actions verb+noun (`createClient`), queries `get*`/`list*`, server `*Record`,
+  policies `assertCan*`, hooks `use-*`.
+- Indexes `<table>_<cols>_idx`, uniques `<table>_<cols>_unique`, FKs `*_user_id`.
+
+## Don't
+
+- Import another feature. Move the shared piece to `entities/` or `shared/`.
+- Read data through a server action.
+- Put `"use server"` on a file under `server/`.

package/skills/ib-toolkit/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: ib-toolkit
+description: Use the inBeat toolkit (@inbeat/core, @inbeat/next, @inbeat/config) correctly in an inBeat app. Use when writing server actions, route handlers, auth checks, env, rate limits, webhooks, Sentry or logging, or when the user mentions ib-toolkit or @ib-toolkit.
+---
+
+# ib-toolkit
+
+Read the "inBeat toolkit standard" block in `AGENTS.md` first. This skill is the how-to. Examples use `authorizeStaff` as a stand-in for the app's own `authorize` check; public endpoints use `publicAccess` plus a rate limiter.
+
+## Server action
+
+```ts
+"use server";
+import { ok } from "@inbeat/core/result";
+import { action } from "@inbeat/next/action";
+import { authorizeStaff } from "@/shared/lib/auth";
+import { createClientSchema } from "../schemas";
+import { createClientRecord } from "../server/create-client-record";
+
+export const createClient = action({
+  name: "clients.create",
+  schema: createClientSchema,
+  authorize: authorizeStaff,
+  run: async (input, viewer) => ok(await createClientRecord(input, viewer.userId)),
+  revalidate: () => ["/clients"],
+});
+```
+
+Client side: `const result = await createClient(values); if (!result.ok) toast.error(result.error);`
+
+Public action: `authorize: publicAccess`, then first thing in `run`:
+`await rateLimiter.enforce(\`apply:${clientIp(await headers())}\`, { limit: 5, window: "10 m" })`.
+The limiter is one shared instance in `src/shared/lib/rate-limit.ts` (`createRateLimiter({ prefix, upstash })`
+with the `upstashEnv` values) imported by every action and route. Get the IP only from `clientIp` in
+`@inbeat/next/rate-limit` (routes pass `request.headers`); never write your own header parsing.
+`clientIp` is reliable on Vercel only; self-hosted apps behind a proxy pass `{ trustedProxyHops: n }`,
+otherwise it returns `"unknown"`. Public forms using Turnstile without Clerk must add its hosts via
+`securityHeaders({ sources: { script: ["https://challenges.cloudflare.com"], frame: ["https://challenges.cloudflare.com"] } })`.
+
+## Route handler
+
+```ts
+import { route } from "@inbeat/next/route";
+export const GET = route({
+  name: "clients.list",
+  authorize: authorizeStaff,
+  query: z.object({ cursor: z.string().optional() }),
+  handler: async ({ query }) => listClients(query.cursor),
+});
+```
+
+## Errors
+
+- Deny: `throw new AppError("forbidden", "reason for logs")`. The user sees safe default copy.
+- Expected business failure: `return fail("That handle is taken", "conflict")`.
+- Anything else: let it throw. The wrapper classifies, reports to Sentry and returns `ERR_xxxx`.
+- Postgres: `isUniqueViolation(err)` from `@inbeat/core/errors`, never string matching.
+
+## Authorization
+
+`authorize` is the app's own check: it returns the viewer or throws `AppError("auth" | "forbidden")`. Roles, admin rules and ownership are app decisions; write them in the app (for example `src/shared/lib/auth.ts`) and pass them to `action()` and `route()`.
+
+## Integrations
+
+Sentry is already wired in the template.
+
+Run `ib mcp` to give your AI tool access to Vercel, GitHub, Sentry, Neon, Clerk, Cloudflare.
+
+### Auth (Clerk)
+
+1. Run `npx -y clerk@latest init` (works with `bunx`). It detects Next.js and applies Clerk's setup; `npx -y clerk@latest doctor` verifies it.
+2. In `proxy.ts`, exclude `/monitoring` (the Sentry tunnel) from the matcher, and keep `/api/health` and `/robots.txt` public.
+3. Pass `clerkFrontendApi(process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY)` to `securityHeaders` (the base `next.config.ts` already does).
+4. Add `clerkServerEnv` and `clerkClientEnv` from `@inbeat/core/env` to `src/shared/config/env.ts` (see Env below).
+
+Access pattern. Clerk's development and production instances are configured separately: apply every
+dashboard step to both.
+
+- Who gets in: a staff-only app turns on the Clerk allowlist (`*@inbeat.agency`, …). It only blocks
+  new sign-ups, so review existing users once after enabling it. Apps with external users keep
+  sign-ups open and rely on roles.
+- Roles: `publicMetadata.role`, assigned in the Clerk dashboard (users cannot edit it). Expose it
+  with the session token claim `{"metadata": "{{user.public_metadata}}"}`, read it from
+  `sessionClaims.metadata.role`. No role or an unknown one means no access.
+- Checks run on the server, twice: the proxy requires sign-in outside the public routes and blocks
+  role-gated areas; every role-gated page, action and route checks again (`authorize`). Hiding UI
+  is not access control.
+- Stays in the app: users table (if joins need it), ownership ("owner or admin"), rate limits,
+  maintenance mode.
+- Deviation: deriving a role from a verified email domain is allowed when the app documents it in
+  AGENTS.md "Deliberate deviations".
+
+### Database (Neon + Drizzle)
+
+1. Run `npx neon@latest init` to link the Neon project and install the agent tooling.
+2. Set up Drizzle per its Neon guide: `drizzle-orm`, `@neondatabase/serverless`, `drizzle-kit`, and a `drizzle.config.ts` with `dialect: "postgresql"`.
+3. Conventions from the standard's Data section: tables in `src/db/schema/<table>.ts`, UUID primary keys, migrations generated with `drizzle-kit generate` and reviewed, and never run migrations or destructive SQL against production.
+
+## Env
+
+```ts
+import { createEnv } from "@t3-oss/env-nextjs";
+import { clerkClientEnv, clerkServerEnv, dbEnv, upstashEnv } from "@inbeat/core/env";
+export const env = createEnv({
+  server: { ...dbEnv, ...clerkServerEnv, ...upstashEnv },
+  client: { ...clerkClientEnv },
+  experimental__runtimeEnv: { NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY },
+  emptyStringAsUndefined: true,
+});
+```
+
+## Other building blocks
+
+| Need | Import |
+|---|---|
+| Neon pool | `createDb` from `@inbeat/next/db` |
+| Clerk webhook | `createClerkWebhookHandler` from `@inbeat/next/clerk-webhook` |
+| Headers/CSP | `securityHeaders`, `clerkFrontendApi` from `@inbeat/next/security-headers` |
+| Sentry | `sentryServerOptions` from `@inbeat/next/sentry` (server, edge); `sentryClientOptions` from `@inbeat/next/sentry-client` (browser only) |
+| Redirect param | `safeRedirectPath` from `@inbeat/next/safe-redirect` |
+
+## Changing the toolkit
+
+Edit `~/Desktop/@inbeat/ib-toolkit`, run its tests, then `bun run sync <app-dir>` there to copy
+the sources into the app's `node_modules/@inbeat/*` (use `--watch` while iterating).

package/skills/ib-ui/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: ib-ui
+description: Build UI in an inBeat app with @inbeat/ui primitives and tokens. Use when creating or editing components, pages, dialogs, tables, forms, empty states, or when the user mentions ib-ui or @ib-ui.
+---
+
+# ib-ui
+
+## Before writing any UI
+
+Check the [Catalog](#catalog). Build pages and domain compositions only from catalog components
+and tokens. Icons are always `lucide-react`.
+
+**Allowed in the app**: page layouts and domain compositions (a `CreatorCard` from `Avatar` +
+`Badge`) in `src/shared/components/blocks` or the feature's `components/`. Different apps may
+compose different layouts.
+
+**Not allowed**: new generic primitives or variants (a local button, modal, select, table or
+toast), copying or restyling a toolkit component, faking a variant with override classes,
+installing another UI library, running `shadcn add`.
+
+**Missing component**: stop. Tell the user which component or variant is missing and why, and
+propose adding it to ib-toolkit (`packages/ui` plus its story). Only with the user's explicit
+agreement, use a workaround and mark it `// toolkit-gap: <what is missing>` so it is greppable.
+
+## Rules
+
+- Import `@inbeat/ui/components/<name>`; `cn` from `@inbeat/ui/lib/utils`.
+- Tokens only: `bg-background`, `text-muted-foreground`, `border-border`, `bg-primary`, radius
+  scale `rounded-{sm..4xl}`, shadows `shadow-hairline|subtle|elevated`. No hex colors, no
+  arbitrary spacing unless no token fits.
+- App shells: `AppShell` + `AppNav`, never Sidebar primitives. Links come in via `renderLink`;
+  app sidebar content goes in the `sidebar` slot. Products differ only through `AppShell` props
+  (`variant`, `collapsible`, `sidebarWidth`, `headerVariant`), never classes or local shell markup.
+- Variants are only the ones an app uses. `Button`: default, secondary, outline, ghost, link,
+  dots; sizes xs, sm, default, lg, icon*; always `rounded-full`, no destructive variant.
+  `Badge`: default, secondary, outline. `TabsList` is pills only.
+- Tabs: `Tabs` + `TabsList tabs={[{ value, label, count? }]}` + `TabsContent`; drop
+  `TabsContent` for a filter bar.
+- Destructive flows open `DestructiveActionDialog` (owns the confirm step; `variant="typed"`
+  makes the user type `DELETE <name>`). Confirm never closes it: call `onOpenChange(false)` on
+  success, so a pending or failed action keeps it open.
+- Action menus: `Button variant="dots"` + `DropdownMenu`. Inside an element with `data-row` it
+  reveals on row hover; elsewhere it stays visible.
+- Icon-only buttons are `IconButton` (required `label` = tooltip + `aria-label`), except `dots`.
+  It works as a `DropdownMenuTrigger asChild` child; with `asChild` it renders a link. Show/hide
+  toggles: `label="Show filters" pressedLabel="Hide filters" pressed={isOpen}`; `pressed` owns the
+  look. Menu and popover triggers are not toggles: static label, no `pressed`.
+- Labels are one to three words, no ids or emails.
+- Lists: `DataTableShell` + `DataTable`. With no data render `EmptyState` instead of the table;
+  DataTable's "No results." is only for an empty filter result.
+- Forms (client leaf): `schema.safeParse(values)` with the schema shared with the action; on
+  failure keep one message per field from `issues` (`issue.path[0]`). Per field:
+  `<Field data-invalid={Boolean(errors.name)}><Label/><Input aria-invalid={Boolean(errors.name)}
+  aria-describedby="name-error"/><FieldError id="name-error">{errors.name}</FieldError></Field>`.
+  On success `const result = await action(parsed.data)`; `if (!result.ok) toast.error(result.error)`
+  (`sonner`; `result.errorId` when present is the support reference).
+- Animation: `motion/react` only, respecting `prefers-reduced-motion`.
+- `page.tsx` stays a Server Component (title, layout, data loading); only the stateful leaf (a
+  table with dialogs, a form) is `"use client"`.
+
+## Catalog
+
+Every module of `@inbeat/ui`, imported as `@inbeat/ui/<path>`.
+
+### Actions
+- `components/button` — Button with variants, sizes and `buttonVariants` for link styling.
+- `components/icon-button` — icon-only Button with a required label, tooltip and toggle state.
+
+### Forms
+- `components/field` — Field, FieldLabel, FieldDescription, FieldError, FieldGroup, FieldSet and friends for form layout.
+- `components/label` — accessible form Label.
+- `components/input` — text Input.
+- `components/textarea` — multi-line Textarea.
+- `components/checkbox` — Checkbox.
+- `components/select` — single-choice Select.
+- `components/combobox` — searchable Combobox with chips for multiple values.
+- `components/multi-select-popover` — popover multi-select over a list of options.
+- `components/toggle-pills` — pill buttons toggling a set of string options, for filters.
+- `components/input-group` — Input or Textarea with inline addons, buttons and text.
+- `components/search-input` — controlled search Input with a loading state.
+- `components/calendar` — date Calendar (react-day-picker) in the toolkit style.
+
+### Display
+- `components/avatar` — Avatar, AvatarImage, AvatarFallback, AvatarGroup and AvatarGroupCount.
+- `components/person-identity` — PersonAvatar, PersonName and PersonIdentity for a person's image and name.
+- `components/member-avatar-stack` — overlapping avatars of up to three members plus a remainder count.
+- `components/badge` — Badge chip.
+- `components/number-dot` — small count pill, renders nothing at zero.
+- `components/labeled-field` — read-only label and value pair.
+- `components/empty-state` — EmptyState with icon, title, description and an optional labelled action.
+- `components/separator` — horizontal or vertical Separator.
+- `components/carousel` — Embla Carousel, CarouselContent and CarouselItem.
+- `components/collapsible-section` — animated CollapsibleSection with trigger and content.
+
+### Feedback
+- `components/alert` — Alert, AlertTitle and AlertDescription (default, destructive).
+- `components/sonner` — Toaster for `sonner` toasts; mount once in the root layout.
+- `components/spinner` — Spinner and SectionSpinner for loading states.
+- `components/skeleton` — Skeleton placeholder.
+- `components/progress` — Progress bar.
+- `components/platform-disclaimer` — dismissible notice whose dismissal is stored in a cookie.
+
+### Navigation
+- `components/app-nav` — sidebar navigation list driven by `items` and `renderLink`.
+- `components/nav-user` — sidebar user menu with name, email, avatar and dropdown.
+- `components/breadcrumb` — Breadcrumb trail.
+- `components/tabs` — Tabs, TabsList (pills from a `tabs` array) and TabsContent.
+- `components/sidebar` — Sidebar primitives that AppShell is built from; apps do not use them directly.
+
+### Overlays
+- `components/dialog` — modal Dialog.
+- `components/alert-dialog` — AlertDialog for interrupting confirmations.
+- `components/destructive-action-dialog` — confirm step for destructive actions, optionally typed.
+- `components/sheet` — side Sheet panel.
+- `components/popover` — Popover.
+- `components/dropdown-menu` — DropdownMenu.
+- `components/tooltip` — Tooltip and TooltipProvider.
+- `components/portal-container` — PortalContainerProvider and usePortalContainer to portal overlays into a chosen element.
+
+### Data
+- `components/data-table` — DataTable driven by TanStack `columns` and `data`.
+- `components/data-table-shell` — scrollable wrapper that holds a DataTable.
+- `components/data-table-sortable-header` — sortable column header for DataTable columns.
+- `components/table` — Table, TableHeader, TableBody, TableRow, TableHead and TableCell primitives.
+- `components/load-more-sentinel` — invisible marker that triggers infinite loading.
+
+### Layout
+- `components/app-shell` — AppShell page frame with sidebar and header, and AppShellLogo.
+
+### Hooks and lib
+- `hooks/use-mobile` — `useIsMobile()` breakpoint hook.
+- `lib/utils` — `cn()` class merging.
+- `lib/easing` — `EASING_FUNCTION` curves shared with motion animations.
+- `lib/initials` — `getInitials(name, fallback)`.
+
+## Setup in an app
+
+```css
+/* src/app/globals.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@inbeat/ui/theme.css";
+```
+
+`next.config.ts`: `transpilePackages: ["@inbeat/ui"]` (ui ships source; core and next ship compiled JS).
+The template installs every peer the catalog needs.
+
+## Adding or changing a component
+
+Do it in `ib-toolkit/packages/ui/src/components`, add or update its story in `packages/ui/stories`
+(`bun run storybook`; stories are grouped like the catalog, render every variant and size from a
+declared list, and use the neutral data in `stories/lib/fixtures.ts`), add it to the Catalog
+above (a test enforces this), then `bun run sync <app-dir>`. Domain compositions tied to one app's
+data stay in the app; once a second app needs one, promote it here.