docs: agents.md refactor

Author: mdjastrzebski

AGENTS.md

@@ -1,62 +1,20 @@
 # Test Renderer for React
 
-## Project Overview
+`test-renderer` is a lightweight React 19 test renderer built on `react-reconciler`.
 
-**Test Renderer for React** is a lightweight, pure JavaScript testing library for React 19. It replaces the deprecated `react-test-renderer`. Built with `react-reconciler`, it outputs to a lightweight, traversable object structure (`TestInstance`) for snapshot testing and asserting component output without a browser environment (DOM) or native dependencies.
+Use Bun for repository scripts.
 
-### Key Features
+Core commands:
 
-- **React 19 Ready:** Supports modern React features, including concurrent rendering.
-- **Lightweight & Universal:** No DOM or native dependencies. Runs in any JavaScript environment (Node.js, Bun, etc.).
-- **Type-Safe:** Written in strict TypeScript.
-- **Snapshot Friendly:** Produces JSON output for Jest/Vitest snapshots.
+- `bun run build`
+- `bun run typecheck`
+- `bun run test`
+- `bun run validate`
 
-### Architecture
+Project docs:
 
-- **`src/index.ts`**: The public entry point that exports `createRoot` from `renderer.ts`.
-- **`src/renderer.ts`**: Contains the main implementation. Exports `createRoot` which initializes the custom React reconciler.
-- **`src/reconciler.ts`**: Implements the `react-reconciler` host config, translating React updates into operations on the internal tree.
-- **`src/test-instance.ts`**: Defines `TestInstance`, a wrapper around the internal fiber nodes with a DOM-like API (e.g., `children`, `props`, `parent`).
-- **`src/render-to-json.ts`**: Handles the serialization of `TestInstance` trees into JSON format for snapshots.
-
-## Building and Running
-
-The project uses **Bun** for development scripts, but you can install it via npm.
-
-### Prerequisites
-
-- Node.js (for consumption)
-- Bun (for development scripts)
-
-### Key Commands
-
-| Command                | Description                                                    |
-| :--------------------- | :------------------------------------------------------------- |
-| `bun run build`        | Builds the project using `tsup` into `dist/` (CJS and ESM).    |
-| `bun run dev`          | Runs the build in watch mode.                                  |
-| `bun run test`         | Runs the test suite using `jest`.                              |
-| `bun run lint`         | Runs `eslint` to check code style.                             |
-| `bun run typecheck`    | Runs `tsc` to verify types.                                    |
-| `bun run validate`     | Runs typechecking, tests, linting, and formatting in sequence. |
-| `bun run validate:fix` | Runs validate with auto-fix for formatting and linting issues. |
-
-## Development Conventions
-
-- **Language:** Strict TypeScript.
-- **Styling:** Code formatting is enforced by Prettier (configured via npm scripts, no explicit config file, uses defaults).
-- **Testing:** Unit tests are located in `src/__tests__/`. Tests use `jest` and `ts-jest`.
-- **Linting:** ESLint is used for static analysis.
-- **Git:** Commits seem to follow standard conventions (implied by `release-it`).
-- **Versioning:** See `docs/versioning.md` for the `1.x` compatibility-line policy for React / React Reconciler support.
-
-## Directory Structure
-
-- `src/`: Source code.
-  - `__tests__/`: Unit tests.
-  - `test-utils/`: Utilities used within project tests.
-- `dist/`: Compiled output (generated by build).
-- `.github/`: GitHub Actions workflows for CI.
-
-## Rules
-
-- Avoid adding unnecessary comments
+- [Project Overview](./docs/agents/project-overview.md)
+- [Architecture](./docs/agents/architecture.md)
+- [Development Conventions](./docs/agents/development-conventions.md)
+- [Commands](./docs/agents/commands.md)
+- [Versioning](./docs/versioning.md)

docs/agents/architecture.md

@@ -0,0 +1,15 @@
+# Architecture
+
+Key files:
+
+- `src/index.ts` is the public entry point and exports `createRoot`.
+- `src/renderer.ts` creates renderer roots and coordinates public rendering APIs.
+- `src/reconciler.ts` defines the `react-reconciler` host config and tree updates.
+- `src/test-instance.ts` defines `TestInstance`, the main wrapper around rendered host nodes.
+- `src/to-json.ts` serializes rendered output into the snapshot-friendly JSON format.
+- `src/query-all.ts` contains tree traversal helpers used for querying.
+- `src/performance.ts` contains optional performance instrumentation.
+
+When changing renderer behavior, start with `src/renderer.ts` and `src/reconciler.ts`.
+
+When changing output shape or snapshot behavior, check `src/test-instance.ts` and `src/to-json.ts`.

docs/agents/commands.md

@@ -0,0 +1,14 @@
+# Commands
+
+Use Bun to run repository scripts.
+
+- `bun run build` builds the package with `tsup` into `dist/`.
+- `bun run dev` runs the build in watch mode.
+- `bun run typecheck` runs `tsc --noEmit`.
+- `bun run test` runs the Jest test suite.
+- `bun run test:ci` runs tests with coverage.
+- `bun run lint` runs ESLint.
+- `bun run prettier` checks formatting.
+- `bun run prettier:fix` writes formatting changes.
+- `bun run validate` runs typecheck, test, lint, and formatting checks.
+- `bun run validate:fix` runs formatting and lint fixes, then typecheck and tests.

docs/agents/development-conventions.md

@@ -0,0 +1,8 @@
+# Development Conventions
+
+- Use strict TypeScript.
+- Tests live in `src/__tests__/`.
+- Project tests use `jest` with `ts-jest`.
+- Linting uses ESLint.
+- Formatting uses Prettier through package scripts.
+- Avoid adding unnecessary comments.

docs/agents/project-overview.md

@@ -0,0 +1,12 @@
+# Project Overview
+
+`test-renderer` is a lightweight, JavaScript-only replacement for the deprecated `react-test-renderer`.
+
+It is built on `react-reconciler` and produces a traversable object tree based on `TestInstance`, so tests can inspect rendered output without a DOM or native runtime.
+
+Relevant source layout:
+
+- `src/` contains the implementation.
+- `src/__tests__/` contains unit tests.
+- `src/test-utils/` contains helpers used by project tests.
+- `dist/` contains generated build output.