# AGENTS.md

Repo-specific guidance for agents working in `react-virtuoso`.

Use this file for repo-specific navigation, validation, and documentation rules only. Keep it short, concrete, and limited to information that helps an agent make better decisions in this repository.

If a rule here appears to conflict with `package.json`, the actual filesystem, or a more specific instruction file in scope, trust the repo state and the more specific instruction.

## High-Signal Rules

- This is a `pnpm` workspaces monorepo. Prefer running commands from the repo root unless you need package-local scope.
- Root `pnpm lint` does **not** run type checking. Run `pnpm typecheck` separately when you need type validation.
- Internal working artifacts belong in Notion, not in repo markdown files.
  - Use Notion for PRPs, plans, clarifications, execution notes, verification notes, prompts, investigations, reports, audits, and exported findings that are not product docs.
  - Do not create or keep repo markdown artifacts in folders like `plans/`, `prompts/`, `reports/`, or similar ad hoc locations.
  - Create new internal artifacts from the shared Notion template at `https://www.notion.so/3461834d8eff81318a4cccaf19b0de51` instead of creating free-form pages from scratch.
  - The template's visual settings such as `Small text` and `Full width` are maintained manually in Notion. Preserve them by duplicating the template when possible.
  - If the user asks for a PRP workflow, create or update the artifact in Notion instead of creating `plans/*.md`.
  - If the user asks for a report or findings export, prefer a Notion page unless they explicitly ask for a repo file.
  - Set a page icon that matches the artifact type or content when creating the page. Prefer clear, stable icons such as `📗` for PRPs/plans, `📊` for reports, `🔎` for investigations, `✍️` for prompts, and `🛠️` for execution notes.
  - If an existing markdown file looks ambiguous, ask before deleting or migrating it.
- Never use `data-testid` as a styling hook. It is reserved for tests. Use semantic attributes such as `data-table-element-role` instead.

## NPM Registry Queries

This repo uses `devEngines.packageManager` with `"onFail": "error"` in the root `package.json`. `pnpm info` and `pnpm view` can fail because they delegate to npm and npm 11 rejects the request in this setup.

Use npm from outside the repo instead:

```bash
(cd /tmp && npm info <package> version)
```

## Workspace Layout

### Main packages

- `packages/data-table` - virtualized data table package; currently the most active package in this repo
- `packages/react-virtuoso` - main virtualization library
- `packages/message-list` - chat/message list package
- `packages/masonry` - masonry layout package
- `packages/gurx` - reactive state library used by older Virtuoso internals
- `packages/reactive-engine-*` - lower-level engine packages used by `data-table`

### Apps and examples

- `apps/virtuoso.dev` - Astro/Starlight docs site
- `examples` - separate workspace for shared Ladle/integration examples
- `packages/react-virtuoso/examples` - example pages used by `packages/react-virtuoso/e2e`

## Plugin Distribution

- This repo ships `virtuoso-skills` as a Claude Code plugin from `packages/virtuoso-skills/`, a Codex plugin from `plugins/virtuoso-skills/`, and a root `skills/` mirror for `npx skills`.
- After merge, public Codex plugin install is:

  ```bash
  codex plugin marketplace add petyosi/react-virtuoso --ref main --sparse .agents/plugins --sparse plugins/virtuoso-skills
  codex plugin add virtuoso-skills@virtuoso
  ```

- Source skill files live at `packages/virtuoso-skills/skills/<name>/SKILL.md`.
- Do not edit `packages/virtuoso-skills/skills/*/references/`, root `skills/`, or `plugins/virtuoso-skills/skills/` directly. They are generated by `pnpm build:skills`.
- Do not commit `.agents/skills/` for Codex/OpenCode/Cursor unless the cross-agent install plan changes. `npx skills` owns that target path.

## Commands

### Root

- `pnpm build` - build all workspaces
- `pnpm build:skills` - regenerate skill references and public skill mirrors
- `pnpm validate:skills` - validate Claude and Codex plugin manifests
- `pnpm typecheck` - run type checking across workspaces
- `pnpm lint` - run package lint scripts across workspaces
- `pnpm format` - format with `oxfmt`
- `pnpm format:check` - check formatting with `oxfmt`
- `pnpm test` - run workspace test scripts
- `pnpm e2e` - run workspace e2e scripts
- `pnpm lint:md` / `pnpm lint:md:fix` - markdown lint / fix
- `pnpm ci` - full CI sequence: setup, build, typecheck, lint, markdown lint, test, e2e
- `pnpm dev:docs` - start the docs site
- `pnpm changeset-add` - add a changeset

### `packages/data-table`

- `pnpm build` - `tsc && vite build`
- `pnpm typecheck` - `tsgo -b --noEmit`
- `pnpm lint` - `oxlint --type-aware --type-check`
- `pnpm test` - `vitest run --browser.headless`
- `pnpm check` - `format:check + lint + typecheck`
- `pnpm dev` - run Ladle serve mode
- `pnpm dev:build` / `pnpm dev:preview` - Ladle build / preview

### `packages/react-virtuoso`

- `pnpm build` - Vite build
- `pnpm typecheck` - `tsgo --noEmit`
- `pnpm lint` - `oxlint --type-aware --type-check`
- `pnpm test` - Vitest
- `pnpm test:watch` - Vitest watch
- `pnpm e2e` - Playwright
- `pnpm ladle` - preview examples in Ladle

### `apps/virtuoso.dev`

- `pnpm dev` - Astro dev server
- `pnpm build` - `shadcn build && astro build`
- `pnpm lint` - `oxlint --type-aware --type-check && astro check`
- `pnpm format` / `pnpm format:check` - `oxfmt` plus Prettier for `.astro`

## Documentation Workflow

The docs site contains generated package docs. Do not edit the generated content under:

- `apps/virtuoso.dev/src/content/docs/data-table/`
- `apps/virtuoso.dev/src/content/docs/react-virtuoso/`
- `apps/virtuoso.dev/src/content/docs/masonry/`
- `apps/virtuoso.dev/src/content/docs/gurx/`
- `apps/virtuoso.dev/src/content/docs/message-list/`

Edit the source docs in the package instead:

- `packages/data-table/README.md` and `packages/data-table/docs/*.md`
- `packages/react-virtuoso/README.md` and `packages/react-virtuoso/docs/*.md`
- `packages/message-list/README.md` and `packages/message-list/docs/*.md`
- `packages/masonry/README.md`
- `packages/gurx/README.md`

After product docs changes:

- run `pnpm lint:md` from the repo root
- if docs-site content or registry code changed, run `pnpm --filter @virtuoso.dev/virtuoso.dev lint`

## Validation Guidance

Choose the narrowest validation that matches the change:

- `packages/data-table` code changes: start with `pnpm check && pnpm test` in `packages/data-table`
- `packages/react-virtuoso` code changes: run `pnpm lint && pnpm typecheck && pnpm test`, add `pnpm e2e` when behavior changes
- docs-only markdown changes: run `pnpm lint:md`
- docs site or registry changes: run `pnpm --filter @virtuoso.dev/virtuoso.dev lint`
- broad cross-package changes: run root `pnpm typecheck && pnpm lint && pnpm test`

## Architecture Notes

- `packages/react-virtuoso` uses the custom `urx` stream/state system under `packages/react-virtuoso/src/urx`. If you touch its internals, follow existing `*System.ts` and `react-urx/` patterns.
- `packages/data-table` is a separate package built on the `reactive-engine-*` workspaces. When working there, prefer matching existing engine/cell/stream patterns instead of borrowing directly from `react-virtuoso` internals.

## Git Hooks

This repo uses `lefthook`. Pre-commit hooks format and lint staged files. If you need to skip them for a WIP commit:

```bash
LEFTHOOK=0 git commit -m "WIP: ..."
```