suites-dev · omermorad · May 26, 2026
diff --git a/docs/agents/index.mdx b/docs/agents/index.mdx
@@ -0,0 +1,106 @@
+---
+sidebar_position: 2
+title: AI Agents
+description: Suites ships version-matched LLM docs inside @suites/unit so AI coding agents read the current Suites API before writing tests.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+# Suites for AI Coding Agents
+
+Suites ships version-matched documentation inside `@suites/unit` so AI coding agents reference the current testing API instead of stale training data. An `AGENTS.md` file at your project root points the agent at the bundled docs in `node_modules/@suites/unit/dist/llm/knowledge/` before it writes tests.
+
+## How it works
+
+When an AI coding agent opens a test file in a Suites project, the flow is short:
+
+1. The agent reads `AGENTS.md` at the project root.
+2. `AGENTS.md` tells it to read `node_modules/@suites/unit/dist/llm/knowledge/index.md` first.
+3. `index.md` routes the agent to the right file for its task: `writing-tests.md`, `di-testing-with-suites.md`, `solitary-vs-sociable.md`, or `common-mistakes.md`.
+4. The agent reads version-matched guidance, then writes the test.
+
+## Install
+
+Prerequisite: `@suites/unit` must be installed. See [Installation](/docs/get-started/installation).
+
+### Step 1: Add `AGENTS.md` to your project root
+
+<Tabs groupId="agents-files">
+<TabItem value="agents" label="AGENTS.md" default>
+
+<CodeBlock language="md" showLineNumbers={false}>
+{`<!-- BEGIN:suites-agent-rules -->
+
+# Suites: read testing guidance before writing tests
+
+When writing or modifying tests in this project, first read the relevant doc
+in \`node_modules/@suites/unit/dist/llm/knowledge/\`. Start with \`index.md\`.
+
+These docs are version-matched to the installed \`@suites/*\` packages and
+override your training data.
+
+<!-- END:suites-agent-rules -->
+`}
+</CodeBlock>
+
+</TabItem>
+</Tabs>
+
+The block is marker-delimited. Add your own project-specific instructions outside the markers without worrying about future updates overwriting them.
+
+### Step 2: Add `CLAUDE.md` (Claude Code users only)
+
+<Tabs groupId="claude-files">
+<TabItem value="claude" label="CLAUDE.md" default>
+
+<CodeBlock language="md" showLineNumbers={false}>
+{`@AGENTS.md
+`}
+</CodeBlock>
+
+</TabItem>
+</Tabs>
+
+### Verify
+
+- Open your AI coding agent in the project root.
+- Ask it to write a test for a service that depends on `UserRepository`.
+- Watch the transcript for `node_modules/@suites/unit/dist/llm/knowledge/index.md` before it writes code.
+
+## Understanding the bundle
+
+After `npm install @suites/unit`, the kit is laid out at:
+
+```text
+node_modules/@suites/unit/dist/llm/
+├── knowledge/      # what agents read before writing tests
+├── skills/         # Agent Skills metadata (auto-trigger)
+└── templates/      # the AGENTS.md block and CLAUDE.md import
+```
+
+`knowledge/` contains five Markdown files: `index.md` (router), `writing-tests.md` (framework-agnostic discipline), `di-testing-with-suites.md` (the Suites v3 `TestBed` API), `solitary-vs-sociable.md` (mode selection and token boundaries), and `common-mistakes.md` (anti-patterns).
+
+`skills/` contains two `SKILL.md` files for tools that support task-specific skill loading. `skills/suites-test/SKILL.md` auto-triggers when the agent edits a file importing `@suites/*` or referencing `TestBed.`.
+
+`templates/` contains `agents-block.md` (the marker-delimited block above) and `claude-import.txt` (the one-line `CLAUDE.md` import).
+
+## Versioning
+
+When `@suites/unit` releases a new version, the bundled docs ship with it. There is no separate update step.
+
+The v3 docs describe the v3 testing surface: `TestBed.solitary()`, `TestBed.sociable()`, `.expose()`, `.mock(Dep).final()`, `.mock(Dep).impl()`, and `unitRef.get(Dep).method.mockReturnValue(...)`. If a future v4 changes the testing surface, the v4 package will ship rewritten docs at the same major bump.
+
+Suites follows the Vercel `next@16.2` precedent. Their evals show higher pass rates for many agents when bundled docs are available through `AGENTS.md`. See [Next.js AI agent evals](https://nextjs.org/evals).
+
+## Supported agents
+
+Most AI coding agents, including Claude Code, Cursor, GitHub Copilot, OpenAI Codex CLI, and Gemini CLI, read `AGENTS.md` automatically. Claude Code additionally reads `CLAUDE.md`, which is why the one-line import above exists.
+
+## Troubleshooting
+
+If the agent skips the docs, run `ls node_modules/@suites/unit/dist/llm/knowledge/` and confirm the files exist. Confirm `AGENTS.md` sits at the project root, not inside a package subdirectory.
+
+Check your agent's docs for the convention:
+[Codex](https://developers.openai.com/codex/guides/agents-md), [Cursor](https://cursor.com/docs/rules), [Claude Code](https://docs.anthropic.com/en/docs/claude-code/memory), [Copilot](https://docs.github.com/en/copilot/how-tos/copilot-cli/add-repository-instructions), or [Gemini CLI](https://google-gemini.github.io/gemini-cli/docs/cli/gemini-md.html).
diff --git a/docs/api-reference/index.md b/docs/api-reference/index.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 title: API Reference
 description: Complete API reference for Suites testing framework
 ---

diff --git a/docs/get-started/installation.mdx b/docs/get-started/installation.mdx
@@ -76,6 +76,8 @@ This installs three packages:
 
 **Suites will automatically detect the installed adapters and configure itself accordingly.**
 
+After installing, optionally [set up your AI coding agent](/docs/agents/#install) so it reads the version-matched Suites docs in `node_modules/@suites/unit/dist/llm/knowledge/` before writing tests.
+
 :::info Why reflect-metadata?
 `reflect-metadata` is required as a runtime dependency (not dev dependency) because TypeScript's decorator metadata is only emitted at compile time.
 Learn more in the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/decorators.html#metadata).

diff --git a/docs/get-started/why-suites.md b/docs/get-started/why-suites.md
@@ -268,6 +268,12 @@ const { unit, unitRef } = await TestBed.solitary(PaymentService).compile();
 
 Same API, same patterns across frameworks. All utilities are exported from a single entry point: `@suites/unit`
 
+:::tip Set this up for your AI agent
+Suites ships version-matched guidance for AI coding agents inside `@suites/unit`. After installation, add the project-level `AGENTS.md` block and one-line `CLAUDE.md` import so tools like Codex CLI, Claude Code, Cursor, Gemini CLI, and Copilot read `node_modules/@suites/unit/dist/llm/knowledge/` before writing tests.
+
+[Install Suites for AI agents](/docs/agents/#install)
+:::
+
 ## In Summary
 
 Suites replaces thousands of lines of brittle, manual test setup with a single, declarative call. Backend teams gain

diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 title: Guides
 description: Practical guides for testing with Suites
 toc_min_heading_level: 3

diff --git a/docs/guides/sociable.md b/docs/guides/sociable.md
@@ -11,7 +11,7 @@ import TabItem from '@theme/TabItem';
 
 > **What this covers:** Testing real component (class) interactions while controlling external dependencies \
 > **Time to read:** ~15 minutes \
-> **Prerequisites:** [Unit Testing Fundamentals](/docs/guides/fundamentals), [Solitary Unit Tests](./solitary), [Test Doubles](./test-doubles) \
+> **Prerequisites:** [Unit Testing Fundamentals](/docs/guides/fundamentals), [Solitary Unit Tests](/docs/guides/solitary), [Test Doubles](/docs/guides/test-doubles) \
 > **Best for:** Verifying components (classes) work together correctly, catching integration bugs while maintaining test speed
 
 Sociable unit tests verify how components interact with their real dependencies while keeping external I/O operations under control. This approach identifies bugs in how business logic components work together - bugs that solitary tests miss.
@@ -325,5 +325,6 @@ Sociable tests work alongside solitary tests to provide comprehensive coverage:
 
 After understanding sociable testing, explore these resources:
 
-- **[Test Doubles](./test-doubles)**: Core concepts of mocking and stubbing
+- **[Test Doubles](/docs/guides/test-doubles)**: Core concepts of mocking and stubbing
+- **[AI agent setup](/docs/agents/#install)**: Point your coding agent at the version-matched Suites docs before it writes sociable tests
 - **[Suites Examples Repository](https://github.com/suites-dev/examples)**: Working examples of sociable testing patterns
diff --git a/docs/migration-guides/from-automock.md b/docs/migration-guides/from-automock.md
@@ -81,6 +81,10 @@ npm install --save-dev @suites/doubles.sinon @suites/di.inversify
 Suites splits the doubles library and the DI integration into separate packages, so install one `@suites/doubles.*` and
 one `@suites/di.*` matching your stack.
 
+:::tip Use Suites with AI coding agents
+After installing the new packages, point your AI coding agent at the version-matched Suites docs so it stops writing old Automock patterns. [Set up for AI agents](/docs/agents/#install).
+:::
+
 ### Step 2: Update Imports
 
 Change all imports from Automock packages to the unified Suites import:

diff --git a/static/llms.txt b/static/llms.txt
@@ -4,6 +4,14 @@
 
 Suites supports NestJS and InversifyJS, integrates with Jest, Sinon, and Vitest, and offers a migration path from Automock.
 
+## For AI coding agents
+
+If you are working inside a project that has `@suites/unit` installed, read the bundled docs first:
+
+`node_modules/@suites/unit/dist/llm/knowledge/index.md`
+
+These docs are version-matched to the installed `@suites/*` packages and override your training data. Do not use pre-v3 Automock patterns or `Test.createTestingModule` boilerplate when the project uses Suites. See [AI Agents](https://suites.dev/docs/agents/) for the human-facing setup.
+
 ## Get started
 
 - [Get Started overview](https://suites.dev/docs/get-started/): entry point for new users