geeklego: Instructions file for Codex

AGENTS.md — GeekLego (v2)

First Things

Read CLAUDE.md — it's the single source of truth for the v2 system: the 2-tier token model (primitives → standard ShadCN/Tailwind semantics), the ShadCN/Radix component pattern, the file layout, and all the "never" / "always" rules. The reference implementation is the Button slice at components/v2/Button/ — read it before building anything. AGENTS.md only adds operational detail that CLAUDE.md omits; where the two ever disagree, CLAUDE.md wins.

Package manager is pnpm. npm install is hard-blocked by a preinstall: only-allow pnpm guard (npm's installer crashes on this pnpm-built tree). Install deps with pnpm add <pkg> — never npm install. Running scripts works under either runner (pnpm run … ≡ npm run …).

Commands

pnpm run dev:all          # Token editor cockpit + Storybook side-by-side
pnpm run dev              # Token editor only (Vite, --config vite.config.mts, serves app/)
pnpm run storybook        # Storybook only (port 6006, .storybook/main.ts globs components/v2/**)
pnpm run build            # tsup bundle (components/index.ts, esm+cjs+dts) + build:css
pnpm run build:css        # Compile design-system/v2/index.css → dist/geeklego.css
pnpm run build-storybook  # Static Storybook site (passes — legacy stories/** are not globbed)
pnpm run lint             # ESLint, --max-warnings 0 (also enforces v2 import discipline)
pnpm run lint-css         # Stylelint over design-system/v2/**
pnpm run validate-tokens  # 2-tier chain check (primitive → semantic); must exit 0
pnpm run export-ir        # Export token IR
pnpm run export-design-md # Export design.md
npx tsc --noEmit          # Type-check
npx vitest run            # All tests (app/src/**/*.test.ts + scripts/**/*.test.ts)

There is no test script — run Vitest directly (npx vitest run).

Repo Structure

• vite.config.mts — app dev server + a live inline plugin that reads/writes design-system/v2/ and design-system/tokens.metadata.json (the cockpit's token-CRUD and /api/merge-metadata endpoints). There is no standalone token-api server.
• vitest.config.ts — single test project: app/src/**/*.test.ts + scripts/**/*.test.ts. (No separate Storybook/Playwright test project.)
• eslint.config.mjs — flat config. Enforces v2 import discipline via no-restricted-imports: bans **/{atoms,molecules,organisms}/** and direct design-system/geeklego.css imports. Baseline is 0 warnings under --max-warnings 0; any new warning fails the gate.
• .stylelintrc.mjs — stylelint config (scoped to design-system/v2/**).
• tsup — no config file; library build uses tsup defaults for the components/index.ts entry.
• design-system/v2/ is the only live stylesheet tree; design-system/geeklego.css was deleted in the 2-tier cut. design-system/v2-defaults/ holds the factory-reset baseline.