From 08cc7ea5604abea239530a45992a8fec94042025 Mon Sep 17 00:00:00 2001
From: founder-OmniPA <founder@omnipa.ai>
Date: Wed, 27 May 2026 15:17:38 +0100
Subject: [PATCH] docs: add file placement and per-agent targeting guidance

---
 README.md | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8ce701e7..85d0e78e 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ Below is a minimal example of an AGENTS.md file:
 - Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
 - Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
 - Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
-- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
+- Check the name field inside each package/package.json to confirm the right name—skip the top-level one.
 
 ## Testing instructions
 - Find the CI plan in the .github/workflows folder.
@@ -32,10 +32,41 @@ Below is a minimal example of an AGENTS.md file:
 - Always run `pnpm lint` and `pnpm test` before committing.
 ```
 
+## File placement
+
+Place `AGENTS.md` at the root of your repository. Agents look for this file first when starting work in your codebase.
+
+For **monorepos**, you can place additional `AGENTS.md` files inside individual packages or directories. Agents that support nested discovery merge instructions based on proximity — package-level files take precedence over the root file for work happening in that subtree:
+
+```
+my-monorepo/
+├── AGENTS.md          # Root-level instructions (applies everywhere)
+├── packages/
+│   ├── api/
+│   │   └── AGENTS.md  # API-specific instructions (supplements or overrides root)
+│   └── web/
+│       └── AGENTS.md  # Web-specific instructions (supplements or overrides root)
+```
+
+## Per-agent targeting
+
+When running multiple agents in the same codebase, you may want to give different instructions to each one. The `AGENTS.[agent].md` naming convention lets you do this without fragmented config files:
+
+```
+AGENTS.md           # Shared baseline — read by all agents
+AGENTS.cursor.md    # Cursor-specific additions
+AGENTS.codex.md     # Codex-specific additions
+AGENTS.copilot.md   # GitHub Copilot-specific additions
+```
+
+Agents that support this convention read both `AGENTS.md` and their named override file, appending the per-agent instructions after the shared baseline. This keeps common context in one place while allowing per-tool customisation.
+
+> **Agent authors:** to opt in, look for `AGENTS.<your-tool-name-lowercase>.md` alongside `AGENTS.md` and append its contents to the shared context you load.
+
 ## Website
 
 This repository also includes a basic Next.js website hosted at https://agents.md/
-that explains the project’s goals in a simple way, and featuring some examples.
+that explains the project's goals in a simple way, and featuring some examples.
 
 ### Running the app locally
 1. Install dependencies: