Luke UI agent guide #

• Use catalog: dependency versions in package.json. The catalog lives in pnpm-workspace.yaml. Do not add raw versions. See docs/DEPENDENCIES.md.
• Read docs/CONVENTIONS.md, docs/COMPONENTS.md, docs/DOCUMENTATION.md, docs/PUBLIC_API.md, docs/STYLING.md, and docs/TESTING.md before changing code, styles, docs, or tests.
• Read docs/TESTING.md before adding or changing tests. It is the only normative testing guide.
• Run tasks through Turbo from the repo root, for example pnpm run check or pnpm run build. Package-local scripts can skip Turbo generate dependencies, which can leave generated files missing.
• Scaffold components non-interactively: pnpm run generate:component --args <name> <docs-group>.
• Scaffold primitives non-interactively: pnpm run generate:primitive --args <name>.
• When you change code, update or delete the docs that describe it in the same change. This includes comments, JSDoc, MDX files in apps/docs/content/docs/, README.md, package READMEs, and files in docs/. See docs/DOCUMENTATION.md.
• docs/DOCUMENTATION.md is the only normative documentation guide. It decides what belongs in documentation as well as how to word MDX prose, JSDoc, and code comments.
• For JavaScript and TypeScript code style, follow docs/CONVENTIONS.md#code-style.

Dev loop #

• Run pnpm run check from the repo root before committing. check covers barrels, format, lint, types, and docs but not tests. Run pnpm run test separately. test.yml runs component, docs, and consumer tests. Visual regression has its own workflow.
• Run pnpm run test:consumer when a change touches the published package, its dependencies, or its exports. It packs the workspace build and installs it with npm outside the repository. Those installs need network access, so pnpm run test leaves it out.
• Component prose lives in MDX files in apps/docs/content/docs/, not .docs.md files in the package. Update the relevant MDX page in the same change as component code.
• Do not add or edit .docs.md files in packages/@luke-ui/react/src/.

Verification traps #

• A package-local check:* run is not what CI runs. Only the root pnpm run check runs check:format-root, which covers files outside packages such as docs/*.md, and knip (check:cycles, check:unused). If check:format-root fails on Markdown wrapping, run pnpm run fix:format-root. Do not re-wrap by hand.
• The Turbo cache is shared across worktrees, so FULL TURBO can replay another branch's result. For a real run, use TURBO_FORCE=true pnpm run test. Do not use pnpm run test -- --force, because the flag goes to the package script.
• publint runs on every build through publint: true in packages/@luke-ui/react/vite.config.ts. Do not add a check:publint script.
• Lint rules live in the lint block of the root vite.config.ts. A .oxlintrc.json file is ignored, and oxlint has no no-restricted-syntax rule. Two lint.overrides entries matching the same file and rule do not merge: the later entry wins.
• In apps/docs, a src/lib/ module imported by a client component must not import node:fs or node:path. If it does, the page returns HTTP 200 but its MDX body renders empty.

Turborepo #

• Turbo configuration, tasks, and CLI behaviour can vary with the installed version; do not rely on training data alone.
• Before changing Turbo config or commands, resolve the installed turbo package (for example node -p "require.resolve('turbo/package.json')" from a workspace that depends on turbo).
• Read that package's bundled docs/README.md and relevant files under docs/; those docs match the installed version and are available offline.