.cursorrules

# Build Trilemma (microproduct-lab) — Cursor Rules

## Tech stack

- **Site framework**: Docusaurus 3 (`@docusaurus/core`, `@docusaurus/preset-classic`)
- **UI**: React 19, TypeScript (extends `@docusaurus/tsconfig`)
- **Styling**: Docusaurus classic theme + project CSS in [`src/css/custom.css`](src/css/custom.css) (no Tailwind in this repo)
- **Quality**: `cspell`, `markdownlint-cli`, Node validation scripts (`scripts/*.mjs`), Jest + Testing Library + ts-jest
- **Hosting**: Static deploy (e.g. Vercel); see [`vercel.json`](vercel.json)

## Repository layout

```
├── docs/                 # Documentation (MD/MDX); split across multiple @docusaurus/plugin-content-docs instances
│   └── agents/human/    # Generated agent mirror of docs/human (do not edit; see scripts/generate-agent-docs.mjs)
├── src/
│   ├── pages/           # React pages (e.g. audience chooser)
│   ├── components/      # Shared React (e.g. ControlSurface, UniversityMarquee)
│   ├── theme/           # Swizzled theme pieces (e.g. Navbar)
│   ├── css/             # Global styles
│   ├── utils/           # Helpers
│   └── __mocks__/       # Jest mocks for @docusaurus/* and @theme/*
├── static/              # Served as-is at site root (e.g. AGENTS.md, llms.txt, registry.json — see .gitignore for generated llms-full.txt)
├── scripts/             # build helpers, validation, generate-agent-docs.mjs, generate-llms-full.mjs
├── product-templates/   # Copy-paste starter repos (each may include its own .github stub)
├── templates/           # Doc templates (frontmatter validated)
└── products/            # README only — explains product code usually lives in other repos
```

Config entry points: [`docusaurus.config.ts`](docusaurus.config.ts), [`sidebars.ts`](sidebars.ts), [`sidebars.agents.ts`](sidebars.agents.ts), [`siteUrl.ts`](siteUrl.ts).

## Routes (high level)

- **`/`** — Audience chooser (humans vs agents); implemented in [`src/pages/index.tsx`](src/pages/index.tsx)
- **`/agents`** — Agent-facing docs island (`docs/agents`, `routeBasePath: agents`)
- **Core docs** — Default docs plugin under `/docs/...` (e.g. intro, playbook)
- **Other doc islands** — `/showcase`, `/contribute`, `/templates`, `/archetypes`, `/standards` (see `docsIslandPlugins` in `docusaurus.config.ts`)
- **Custom pages** — e.g. [`src/pages/index.tsx`](src/pages/index.tsx)

Navbar/footer grouping for Humans vs Agents is configured in `themeConfig` in [`docusaurus.config.ts`](docusaurus.config.ts).

## npm scripts

- **`npm run dev`** / **`npm start`** — Local Docusaurus dev server (`predev` clears dev caches and runs `generate-agent-docs.mjs`)
- **`npm run build`** — Runs `generate-agent-docs.mjs`, `generate-llms-full.mjs`, `docusaurus build`, then `validate-build-artifacts.mjs`
- **`npm run check`** — typecheck, spellcheck, frontmatter + registry + playbook-tree validation, markdown lint, production build (includes link checks)
- **`npm test`** — Jest plus Node `node --test` for all `scripts/__tests__/*.test.mjs`
- **`npm run test:coverage`** — Jest with coverage thresholds (see [`jest.config.js`](jest.config.js)) plus Node tests above
- **`npm run clean`** — `docusaurus clear` and remove `build/` + `coverage/`

## Conventions

### TypeScript / React

- Use `import type` for type-only imports.
- Prefer explicit return types on exported functions where it helps readability.
- Functional components are typical; follow patterns already used in `src/pages/` and `src/components/`.
- For class names, this repo uses **`clsx`** in some components (runtime dependency).

### Testing

- Jest `moduleNameMapper`: `@site/*` → repo root, `@docusaurus/*` and `@theme/*` → `src/__mocks__/`.
- Coverage collectors and **100% global thresholds** are defined in [`jest.config.js`](jest.config.js) (some paths are excluded there intentionally, e.g. swizzled theme, UniversityMarquee).

### Content & agent surfaces

- **Machine-readable data**: [`static/registry.json`](static/registry.json) validated by `npm run validate:registry` (schema under `static/schemas/`).
- **Agent-oriented static files**: `static/AGENTS.md`, `static/llms.txt`; **`static/llms-full.txt`** is generated on `npm run build` (ignored by git).
- **Generated agent mirror**: `docs/agents/human/` is produced by `generate-agent-docs.mjs` from `docs/human/` (gitignored; edit human docs only).
- **MDX in docs**: When adding JSX or imports, remember `generate-llms-full.mjs` and the agent mirror strip MDX for plain-text bundles via [`scripts/llmsMdxUtils.mjs`](scripts/llmsMdxUtils.mjs).

### Do / don’t

- **Do** run **`npm run check`** and **`npm run test:coverage`** before pushing (matches [`.github/workflows/ci.yml`](.github/workflows/ci.yml)).
- **Do** keep changes to docs/plugins/registry in sync (broken links fail the build).
- **Don’t** assume Vite, React Router, Tailwind, Biome, or Google Sheets pipelines — those belong to other projects, not this repo.