diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..62e887af2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,53 @@
+# Agent instructions — @prefabs.tech/fastify
+
+Humans and coding agents should **default to documentation** in this repo before reading or editing package source.
+
+**Published packages:** each `packages/<name>/` directory ships `AGENTS.md` and `docs/llm/**` on npm (see each `package.json` → `files`). When you add a package or change the public API, update the `<!-- docgen:packages:start -->` region in [docs/llm/REFERENCE.md](docs/llm/REFERENCE.md). When you change agent read-order for humans, update **both** the repo-root doc flow below **and** that package’s `AGENTS.md` and **For AI agents** section in its `README.md` (keep the GitHub `REFERENCE.md#<name>` URL consistent).
+
+## Read order
+
+**Published package directory only** (after `npm install` / build artifact: typically `README.md`, `AGENTS.md`, `docs/llm/`, `dist/`):
+
+1. `README.md` — **For AI agents** (routing stub; stay shallow).
+2. `AGENTS.md` — package agent entrypoint.
+3. `docs/llm/INDEX.md` → `docs/llm/EXAMPLES.md`.
+4. GitHub [`docs/llm/REFERENCE.md`](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md) — **only** the anchor for this package (URL in README / AGENTS).
+
+**Monorepo checkout** (this repository):
+
+1. [docs/llm/INDEX.md](docs/llm/INDEX.md) — workspace map and boundaries.
+2. **One** package: `packages/<name>/docs/llm/INDEX.md` (see table below), then `packages/<name>/docs/llm/EXAMPLES.md` (task → file).
+3. [docs/llm/REFERENCE.md](docs/llm/REFERENCE.md) — open **only** the section (anchor) for that package.
+4. Follow links from REFERENCE or `docs/llm/EXAMPLES.md` to GUIDE.md, tests, `src/index.ts`, and `src/plugin.ts`.
+
+## Escalation
+
+Open additional files **only** when they are linked from REFERENCE, from that package’s `docs/llm/EXAMPLES.md`, or from files you already opened through those links.
+
+## Fallback
+
+Broad search or full-tree reads under `packages/*/src/` are for when `docs/llm` is missing, incomplete, or known to be stale—never as the first step.
+
+## Package LLM entrypoints
+
+| Package | INDEX | Examples |
+|---------|--------|----------|
+| config | [INDEX](packages/config/docs/llm/INDEX.md) | [EXAMPLES](packages/config/docs/llm/EXAMPLES.md) |
+| error-handler | [INDEX](packages/error-handler/docs/llm/INDEX.md) | [EXAMPLES](packages/error-handler/docs/llm/EXAMPLES.md) |
+| swagger | [INDEX](packages/swagger/docs/llm/INDEX.md) | [EXAMPLES](packages/swagger/docs/llm/EXAMPLES.md) |
+| slonik | [INDEX](packages/slonik/docs/llm/INDEX.md) | [EXAMPLES](packages/slonik/docs/llm/EXAMPLES.md) |
+| graphql | [INDEX](packages/graphql/docs/llm/INDEX.md) | [EXAMPLES](packages/graphql/docs/llm/EXAMPLES.md) |
+| s3 | [INDEX](packages/s3/docs/llm/INDEX.md) | [EXAMPLES](packages/s3/docs/llm/EXAMPLES.md) |
+| mailer | [INDEX](packages/mailer/docs/llm/INDEX.md) | [EXAMPLES](packages/mailer/docs/llm/EXAMPLES.md) |
+| firebase | [INDEX](packages/firebase/docs/llm/INDEX.md) | [EXAMPLES](packages/firebase/docs/llm/EXAMPLES.md) |
+| user | [INDEX](packages/user/docs/llm/INDEX.md) | [EXAMPLES](packages/user/docs/llm/EXAMPLES.md) |
+
+## Conventions
+
+Public API: `packages/<name>/src/index.ts`. Fastify plugin implementation: `packages/<name>/src/plugin.ts`. Runnable usage examples: tests under `src/__test__` (linked from REFERENCE).
+
+Breaking changes and migrations for agent-facing notes: [docs/llm/CHANGES.md](docs/llm/CHANGES.md).
+
+## Keeping REFERENCE in sync
+
+The `<!-- docgen:packages:start -->` region in [docs/llm/REFERENCE.md](docs/llm/REFERENCE.md) is **maintained manually**. When you change public exports in `src/index.ts`, paths to tests, or the package list, edit that section in the same PR. Set **Last verified** in REFERENCE to the current `git` commit once the links match reality.
diff --git a/packages/config/AGENTS.md b/packages/config/AGENTS.md
new file mode 100644
index 000000000..1296b76dd
--- /dev/null
+++ b/packages/config/AGENTS.md
@@ -0,0 +1,16 @@
+# Agent instructions — @prefabs.tech/fastify-config
+
+Published **with the npm package**. Use **[README.md](./README.md)** first (see **For AI agents** there), then this file when the monorepo root isn’t available (for example under `node_modules`). The steps below minimize tokens and avoid broad `dist/`/`src/` scans.
+
+## Read order
+
+1. [docs/llm/INDEX.md](./docs/llm/INDEX.md) — package orientation and boundaries.
+2. [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md) — task → smallest source/test files.
+3. Workspace **[REFERENCE](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#config)** — deep links to GUIDE, `src/index.ts`, `plugin.ts`, and tests (**not** in this tarball).
+4. Workspace **[INDEX](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/INDEX.md)** — map of all packages.
+
+Open sources and tests **only** via links on the REFERENCE page. Avoid scanning the full monorepo or large compiled trees unless these docs are missing, incomplete, or obviously stale.
+
+## In this install
+
+Per `package.json` → `files`, you typically have `dist/`, `docs/llm/`, and this file. For full source and tests, use **repository** in `package.json`.
diff --git a/packages/config/README.md b/packages/config/README.md
index b87e44335..4adbd3af4 100644
--- a/packages/config/README.md
+++ b/packages/config/README.md
@@ -1,5 +1,9 @@
 # @prefabs.tech/fastify-config
 
+## For AI agents
+
+**Read order:** [AGENTS.md](./AGENTS.md) → [docs/llm/INDEX.md](./docs/llm/INDEX.md) → [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md). Deep links to source and tests: [REFERENCE (config)](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#config). Avoid scanning `dist/` or large trees unless those docs are stale or insufficient.
+
 A [Fastify](https://github.com/fastify/fastify) plugin that provides opinionated, typed configuration management for APIs.
 
 ## Why This Plugin?
diff --git a/packages/config/docs/llm/EXAMPLES.md b/packages/config/docs/llm/EXAMPLES.md
new file mode 100644
index 000000000..292286dc5
--- /dev/null
+++ b/packages/config/docs/llm/EXAMPLES.md
@@ -0,0 +1,10 @@
+# @prefabs.tech/fastify-config — task → file
+
+Compact routes to runnable tests and sources. Paths are relative to the package root (`packages/config/`).
+
+| Task | Open first | Why |
+|------|------------|-----|
+| Register plugin, `fastify.config` / `request.config` | [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts) | End-to-end registration and config access |
+| Parse env / JSON config helpers | [src/__test__/parse.test.ts](../../src/__test__/parse.test.ts) | `parse()` and coercion behavior |
+| Public exports | [src/index.ts](../../src/index.ts) | API surface |
+| Plugin implementation | [src/plugin.ts](../../src/plugin.ts) | Fastify registration |
diff --git a/packages/config/docs/llm/INDEX.md b/packages/config/docs/llm/INDEX.md
new file mode 100644
index 000000000..bf195c451
--- /dev/null
+++ b/packages/config/docs/llm/INDEX.md
@@ -0,0 +1,30 @@
+# @prefabs.tech/fastify-config — LLM index
+
+Typed Fastify configuration: `fastify.config` / `request.config` from env and optional JSON, with Ajv-backed schema validation and a small `parse()` helper for env coercion.
+
+## Task router
+
+- **Public API / exports** → [src/index.ts](../../src/index.ts)
+- **Plugin registration** → [src/plugin.ts](../../src/plugin.ts)
+- **Register + inject (smallest story)** → [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts)
+- **Parse / env helpers** → [src/__test__/parse.test.ts](../../src/__test__/parse.test.ts)
+
+## Examples
+
+Task-first table: [EXAMPLES.md](./EXAMPLES.md)
+
+## Read order
+
+This file → [workspace REFERENCE](../../../../docs/llm/REFERENCE.md#config) → [EXAMPLES.md](./EXAMPLES.md) → open only paths linked from REFERENCE or EXAMPLES (not a full `src/` scan).
+
+## Boundaries
+
+Do not scan all of `src/` unless REFERENCE or EXAMPLES links are missing or clearly stale; prefer tests after those links.
+
+| Capability | Notes |
+|----------|-------|
+| Instance + request config | `ApiConfig`, hostname helper |
+| Parsing | `parse()` for env values |
+| Validation | Schema + Ajv at plugin boundary |
+
+- **Human docs:** [README.md](../../README.md) · [GUIDE.md](../../GUIDE.md)
diff --git a/packages/config/package.json b/packages/config/package.json
index 45d83dcb1..010ff7481 100644
--- a/packages/config/package.json
+++ b/packages/config/package.json
@@ -20,7 +20,9 @@
   "module": "./dist/prefabs-tech-fastify-config.js",
   "types": "./dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs/llm",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly && mv dist/src dist/types",
diff --git a/packages/error-handler/AGENTS.md b/packages/error-handler/AGENTS.md
new file mode 100644
index 000000000..839c175b3
--- /dev/null
+++ b/packages/error-handler/AGENTS.md
@@ -0,0 +1,16 @@
+# Agent instructions — @prefabs.tech/fastify-error-handler
+
+Published **with the npm package**. Use **[README.md](./README.md)** first (see **For AI agents** there), then this file when the monorepo root isn’t available (for example under `node_modules`). The steps below minimize tokens and avoid broad `dist/`/`src/` scans.
+
+## Read order
+
+1. [docs/llm/INDEX.md](./docs/llm/INDEX.md) — package orientation and boundaries.
+2. [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md) — task → smallest source/test files.
+3. Workspace **[REFERENCE](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#error-handler)** — deep links to GUIDE, `src/index.ts`, `plugin.ts`, and tests (**not** in this tarball).
+4. Workspace **[INDEX](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/INDEX.md)** — map of all packages.
+
+Open sources and tests **only** via links on the REFERENCE page. Avoid scanning the full monorepo or large compiled trees unless these docs are missing, incomplete, or obviously stale.
+
+## In this install
+
+Per `package.json` → `files`, you typically have `dist/`, `docs/llm/`, and this file. For full source and tests, use **repository** in `package.json`.
diff --git a/packages/error-handler/README.md b/packages/error-handler/README.md
index 75c7b4ad9..5b1f24bf7 100644
--- a/packages/error-handler/README.md
+++ b/packages/error-handler/README.md
@@ -1,5 +1,9 @@
 # @prefabs.tech/fastify-error-handler
 
+## For AI agents
+
+**Read order:** [AGENTS.md](./AGENTS.md) → [docs/llm/INDEX.md](./docs/llm/INDEX.md) → [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md). Deep links to source and tests: [REFERENCE (error-handler)](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#error-handler). Avoid scanning `dist/` or large trees unless those docs are stale or insufficient.
+
 A [Fastify](https://github.com/fastify/fastify) plugin that provides a standardized, production-safe global error handler for APIs.
 
 ## Why This Plugin?
diff --git a/packages/error-handler/docs/llm/EXAMPLES.md b/packages/error-handler/docs/llm/EXAMPLES.md
new file mode 100644
index 000000000..b4fec57c0
--- /dev/null
+++ b/packages/error-handler/docs/llm/EXAMPLES.md
@@ -0,0 +1,11 @@
+# @prefabs.tech/fastify-error-handler — task → file
+
+Paths are relative to the package root (`packages/error-handler/`).
+
+| Task | Open first | Why |
+|------|------------|-----|
+| Plugin registration, schema, `stackTrace`, sensible | [src/__test__/registration.test.ts](../../src/__test__/registration.test.ts) | Smallest registration story |
+| `CustomError`, masking, stack traces | [src/__test__/errorHandling.test.ts](../../src/__test__/errorHandling.test.ts) | Response shape and `stackTrace` |
+| `preErrorHandler` (short-circuit, errors) | [src/__test__/preErrorHandler.test.ts](../../src/__test__/preErrorHandler.test.ts) | Third-party hook behavior |
+| Public exports | [src/index.ts](../../src/index.ts) | API surface |
+| Plugin implementation | [src/plugin.ts](../../src/plugin.ts) | `setErrorHandler` wiring |
diff --git a/packages/error-handler/docs/llm/INDEX.md b/packages/error-handler/docs/llm/INDEX.md
new file mode 100644
index 000000000..ed5e0416a
--- /dev/null
+++ b/packages/error-handler/docs/llm/INDEX.md
@@ -0,0 +1,31 @@
+# @prefabs.tech/fastify-error-handler — LLM index
+
+Central Fastify error handling: consistent error payloads, stack masking in production, and hooks such as `preParsing` integration for early failures.
+
+## Task router
+
+- **Public API / exports** → [src/index.ts](../../src/index.ts)
+- **Plugin + global handler** → [src/plugin.ts](../../src/plugin.ts)
+- **Registration, schema, `stackTrace`** → [src/__test__/registration.test.ts](../../src/__test__/registration.test.ts)
+- **Masking / `CustomError` / stacks** → [src/__test__/errorHandling.test.ts](../../src/__test__/errorHandling.test.ts)
+- **`preErrorHandler`** → [src/__test__/preErrorHandler.test.ts](../../src/__test__/preErrorHandler.test.ts)
+
+## Examples
+
+Task-first table: [EXAMPLES.md](./EXAMPLES.md)
+
+## Read order
+
+This file → [workspace REFERENCE](../../../../docs/llm/REFERENCE.md#error-handler) → [EXAMPLES.md](./EXAMPLES.md) → linked sources/tests from REFERENCE or EXAMPLES only.
+
+## Boundaries
+
+Do not scan full `src/` without going through REFERENCE/EXAMPLES first; nested helpers are implementation details.
+
+| Capability | Notes |
+|----------|-------|
+| Global errors | Unified shape, logging alignment |
+| Security | Stack traces hidden where configured |
+| Hooks | Registration order matters—see GUIDE |
+
+- **Human docs:** [README.md](../../README.md) · [GUIDE.md](../../GUIDE.md)
diff --git a/packages/error-handler/package.json b/packages/error-handler/package.json
index f8b34177b..88811cecb 100644
--- a/packages/error-handler/package.json
+++ b/packages/error-handler/package.json
@@ -20,7 +20,9 @@
   "module": "./dist/prefabs-tech-fastify-error-handler.js",
   "types": "./dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs/llm",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly && mv dist/src dist/types",
diff --git a/packages/firebase/AGENTS.md b/packages/firebase/AGENTS.md
new file mode 100644
index 000000000..3d176fe9e
--- /dev/null
+++ b/packages/firebase/AGENTS.md
@@ -0,0 +1,16 @@
+# Agent instructions — @prefabs.tech/fastify-firebase
+
+Published **with the npm package**. Use **[README.md](./README.md)** first (see **For AI agents** there), then this file when the monorepo root isn’t available (for example under `node_modules`). The steps below minimize tokens and avoid broad `dist/`/`src/` scans.
+
+## Read order
+
+1. [docs/llm/INDEX.md](./docs/llm/INDEX.md) — package orientation and boundaries.
+2. [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md) — task → smallest source/test files.
+3. Workspace **[REFERENCE](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#firebase)** — deep links to GUIDE, `src/index.ts`, `plugin.ts`, and tests (**not** in this tarball).
+4. Workspace **[INDEX](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/INDEX.md)** — map of all packages.
+
+Open sources and tests **only** via links on the REFERENCE page. Avoid scanning the full monorepo or large compiled trees unless these docs are missing, incomplete, or obviously stale.
+
+## In this install
+
+Per `package.json` → `files`, you typically have `dist/`, `docs/llm/`, and this file. For full source and tests, use **repository** in `package.json`.
diff --git a/packages/firebase/README.md b/packages/firebase/README.md
index 996312c1b..ec2161bb0 100644
--- a/packages/firebase/README.md
+++ b/packages/firebase/README.md
@@ -1,5 +1,9 @@
 # @prefabs.tech/fastify-firebase
 
+## For AI agents
+
+**Read order:** [AGENTS.md](./AGENTS.md) → [docs/llm/INDEX.md](./docs/llm/INDEX.md) → [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md). Deep links to source and tests: [REFERENCE (firebase)](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#firebase). Avoid scanning `dist/` or large trees unless those docs are stale or insufficient.
+
 A [Fastify](https://github.com/fastify/fastify) plugin that provides an easy integration of Firebase Admin in a fastify API.
 
 ## Why this plugin?
diff --git a/packages/firebase/docs/llm/EXAMPLES.md b/packages/firebase/docs/llm/EXAMPLES.md
new file mode 100644
index 000000000..119bf21d6
--- /dev/null
+++ b/packages/firebase/docs/llm/EXAMPLES.md
@@ -0,0 +1,11 @@
+# @prefabs.tech/fastify-firebase — task → file
+
+Paths are relative to the package root (`packages/firebase/`).
+
+| Task | Open first | Why |
+|------|------------|-----|
+| Register plugin | [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts) | Core registration |
+| Initialize Firebase app | [src/__test__/initializeFirebase.test.ts](../../src/__test__/initializeFirebase.test.ts) | Admin init patterns |
+| Service surface | [src/__test__/service.test.ts](../../src/__test__/service.test.ts) | Runtime service usage |
+| Public exports | [src/index.ts](../../src/index.ts) | API surface |
+| Plugin implementation | [src/plugin.ts](../../src/plugin.ts) | Fastify registration |
diff --git a/packages/firebase/docs/llm/INDEX.md b/packages/firebase/docs/llm/INDEX.md
new file mode 100644
index 000000000..6b0b1a682
--- /dev/null
+++ b/packages/firebase/docs/llm/INDEX.md
@@ -0,0 +1,31 @@
+# @prefabs.tech/fastify-firebase — LLM index
+
+Firebase Admin integration: app initialization, FCM, SQL-related factories, and GraphQL-oriented resolvers/helpers where applicable.
+
+## Task router
+
+- **Public API / exports** → [src/index.ts](../../src/index.ts)
+- **Plugin implementation** → [src/plugin.ts](../../src/plugin.ts)
+- **Register plugin** → [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts)
+- **Initialize app** → [src/__test__/initializeFirebase.test.ts](../../src/__test__/initializeFirebase.test.ts)
+- **Service usage** → [src/__test__/service.test.ts](../../src/__test__/service.test.ts)
+
+## Examples
+
+Task-first table: [EXAMPLES.md](./EXAMPLES.md)
+
+## Read order
+
+This file → [workspace REFERENCE](../../../../docs/llm/REFERENCE.md#firebase) → [EXAMPLES.md](./EXAMPLES.md) → [GUIDE.md](../../GUIDE.md) · [FEATURES.md](../../FEATURES.md) (human) → linked tests/source from REFERENCE or EXAMPLES.
+
+## Boundaries
+
+Do not scan all of `src/` without REFERENCE/EXAMPLES; feature surface is split across modules.
+
+| Capability | Notes |
+|----------|-------|
+| Init | Firebase app and options |
+| Messaging | FCM usage patterns |
+| Data layer | Factories and service surface |
+
+- **Human docs:** [README.md](../../README.md) · [GUIDE.md](../../GUIDE.md)
diff --git a/packages/firebase/package.json b/packages/firebase/package.json
index 35a64625a..6572ba423 100644
--- a/packages/firebase/package.json
+++ b/packages/firebase/package.json
@@ -20,7 +20,9 @@
   "module": "./dist/prefabs-tech-fastify-firebase.js",
   "types": "./dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs/llm",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly && mv dist/src dist/types",
diff --git a/packages/graphql/AGENTS.md b/packages/graphql/AGENTS.md
new file mode 100644
index 000000000..517bf115e
--- /dev/null
+++ b/packages/graphql/AGENTS.md
@@ -0,0 +1,16 @@
+# Agent instructions — @prefabs.tech/fastify-graphql
+
+Published **with the npm package**. Use **[README.md](./README.md)** first (see **For AI agents** there), then this file when the monorepo root isn’t available (for example under `node_modules`). The steps below minimize tokens and avoid broad `dist/`/`src/` scans.
+
+## Read order
+
+1. [docs/llm/INDEX.md](./docs/llm/INDEX.md) — package orientation and boundaries.
+2. [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md) — task → smallest source/test files.
+3. Workspace **[REFERENCE](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#graphql)** — deep links to GUIDE, `src/index.ts`, `plugin.ts`, and tests (**not** in this tarball).
+4. Workspace **[INDEX](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/INDEX.md)** — map of all packages.
+
+Open sources and tests **only** via links on the REFERENCE page. Avoid scanning the full monorepo or large compiled trees unless these docs are missing, incomplete, or obviously stale.
+
+## In this install
+
+Per `package.json` → `files`, you typically have `dist/`, `docs/llm/`, and this file. For full source and tests, use **repository** in `package.json`.
diff --git a/packages/graphql/README.md b/packages/graphql/README.md
index 350f3f0b5..e4d70e873 100644
--- a/packages/graphql/README.md
+++ b/packages/graphql/README.md
@@ -1,5 +1,9 @@
 # @prefabs.tech/fastify-graphql
 
+## For AI agents
+
+**Read order:** [AGENTS.md](./AGENTS.md) → [docs/llm/INDEX.md](./docs/llm/INDEX.md) → [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md). Deep links to source and tests: [REFERENCE (graphql)](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#graphql). Avoid scanning `dist/` or large trees unless those docs are stale or insufficient.
+
 A [Fastify](https://github.com/fastify/fastify) plugin that provides an easy integration of mercurius graphql server in a fastify API.
 
 The plugin is a thin wrapper around the [mercurius](https://mercurius.dev/#/) plugin.
diff --git a/packages/graphql/docs/llm/EXAMPLES.md b/packages/graphql/docs/llm/EXAMPLES.md
new file mode 100644
index 000000000..11f24fe7e
--- /dev/null
+++ b/packages/graphql/docs/llm/EXAMPLES.md
@@ -0,0 +1,11 @@
+# @prefabs.tech/fastify-graphql — task → file
+
+Paths are relative to the package root (`packages/graphql/`).
+
+| Task | Open first | Why |
+|------|------------|-----|
+| Register Mercurius plugin | [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts) | Default plugin setup |
+| `buildContext` / request context | [src/__test__/context.spec.ts](../../src/__test__/context.spec.ts) | GraphQL context patterns |
+| Base schema wiring | [src/__test__/baseSchema.test.ts](../../src/__test__/baseSchema.test.ts) | Shared schema behavior |
+| Public exports | [src/index.ts](../../src/index.ts) | API surface |
+| Plugin implementation | [src/plugin.ts](../../src/plugin.ts) | Fastify registration |
diff --git a/packages/graphql/docs/llm/INDEX.md b/packages/graphql/docs/llm/INDEX.md
new file mode 100644
index 000000000..75e27d267
--- /dev/null
+++ b/packages/graphql/docs/llm/INDEX.md
@@ -0,0 +1,31 @@
+# @prefabs.tech/fastify-graphql — LLM index
+
+Mercurius GraphQL for Fastify: schema registration, `buildContext`, and shared base schema patterns for API graphs.
+
+## Task router
+
+- **Public API / exports** → [src/index.ts](../../src/index.ts)
+- **Plugin implementation** → [src/plugin.ts](../../src/plugin.ts)
+- **Register Mercurius** → [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts)
+- **GraphQL context** → [src/__test__/context.spec.ts](../../src/__test__/context.spec.ts)
+- **Base schema** → [src/__test__/baseSchema.test.ts](../../src/__test__/baseSchema.test.ts)
+
+## Examples
+
+Task-first table: [EXAMPLES.md](./EXAMPLES.md)
+
+## Read order
+
+This file → [workspace REFERENCE](../../../../docs/llm/REFERENCE.md#graphql) → [EXAMPLES.md](./EXAMPLES.md) → context/schema tests linked from REFERENCE or EXAMPLES.
+
+## Boundaries
+
+Do not full-scan `src/` for resolvers; follow REFERENCE/EXAMPLES into `plugin.ts` and targeted tests first.
+
+| Capability | Notes |
+|----------|-------|
+| Mercurius | Plugin registration and options |
+| Context | Request-scoped GraphQL context |
+| Base schema | Shared types / wiring |
+
+- **Human docs:** [README.md](../../README.md) · [GUIDE.md](../../GUIDE.md)
diff --git a/packages/graphql/package.json b/packages/graphql/package.json
index 55131f2d4..81f7455b0 100644
--- a/packages/graphql/package.json
+++ b/packages/graphql/package.json
@@ -20,7 +20,9 @@
   "module": "./dist/prefabs-tech-fastify-graphql.js",
   "types": "./dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs/llm",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly && mv dist/src dist/types",
diff --git a/packages/mailer/AGENTS.md b/packages/mailer/AGENTS.md
new file mode 100644
index 000000000..21eeade06
--- /dev/null
+++ b/packages/mailer/AGENTS.md
@@ -0,0 +1,16 @@
+# Agent instructions — @prefabs.tech/fastify-mailer
+
+Published **with the npm package**. Use **[README.md](./README.md)** first (see **For AI agents** there), then this file when the monorepo root isn’t available (for example under `node_modules`). The steps below minimize tokens and avoid broad `dist/`/`src/` scans.
+
+## Read order
+
+1. [docs/llm/INDEX.md](./docs/llm/INDEX.md) — package orientation and boundaries.
+2. [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md) — task → smallest source/test files.
+3. Workspace **[REFERENCE](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#mailer)** — deep links to GUIDE, `src/index.ts`, `plugin.ts`, and tests (**not** in this tarball).
+4. Workspace **[INDEX](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/INDEX.md)** — map of all packages.
+
+Open sources and tests **only** via links on the REFERENCE page. Avoid scanning the full monorepo or large compiled trees unless these docs are missing, incomplete, or obviously stale.
+
+## In this install
+
+Per `package.json` → `files`, you typically have `dist/`, `docs/llm/`, and this file. For full source and tests, use **repository** in `package.json`.
diff --git a/packages/mailer/README.md b/packages/mailer/README.md
index f3d97f0e7..bfe98e4b5 100644
--- a/packages/mailer/README.md
+++ b/packages/mailer/README.md
@@ -1,5 +1,9 @@
 # @prefabs.tech/fastify-mailer
 
+## For AI agents
+
+**Read order:** [AGENTS.md](./AGENTS.md) → [docs/llm/INDEX.md](./docs/llm/INDEX.md) → [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md). Deep links to source and tests: [REFERENCE (mailer)](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#mailer). Avoid scanning `dist/` or large trees unless those docs are stale or insufficient.
+
 A [Fastify](https://github.com/fastify/fastify) plugin that when registered on a Fastify instance, will decorate it with a `mailer` object for email.
 
 ## Why this plugin?
diff --git a/packages/mailer/docs/llm/EXAMPLES.md b/packages/mailer/docs/llm/EXAMPLES.md
new file mode 100644
index 000000000..42d8f6ee3
--- /dev/null
+++ b/packages/mailer/docs/llm/EXAMPLES.md
@@ -0,0 +1,12 @@
+# @prefabs.tech/fastify-mailer — task → file
+
+Paths are relative to the package root (`packages/mailer/`).
+
+| Task | Open first | Why |
+|------|------------|-----|
+| Register mailer plugin | [src/__test__/registration.test.ts](../../src/__test__/registration.test.ts) | Plugin bootstrap |
+| HTTP test routes | [src/__test__/testRoute.test.ts](../../src/__test__/testRoute.test.ts) | Route surface |
+| Send mail / transport | [src/__test__/sendMail.test.ts](../../src/__test__/sendMail.test.ts) | Sending behavior |
+| Test config helper | [src/__test__/helpers/createMailerConfig.ts](../../src/__test__/helpers/createMailerConfig.ts) | Fixture-style config |
+| Public exports | [src/index.ts](../../src/index.ts) | API surface |
+| Plugin implementation | [src/plugin.ts](../../src/plugin.ts) | Fastify registration |
diff --git a/packages/mailer/docs/llm/INDEX.md b/packages/mailer/docs/llm/INDEX.md
new file mode 100644
index 000000000..4175724b2
--- /dev/null
+++ b/packages/mailer/docs/llm/INDEX.md
@@ -0,0 +1,31 @@
+# @prefabs.tech/fastify-mailer — LLM index
+
+Transactional email: Nodemailer + MJML templates, Fastify routes for testing or operational hooks, and recipient/configuration patterns.
+
+## Task router
+
+- **Public API / exports** → [src/index.ts](../../src/index.ts)
+- **Plugin implementation** → [src/plugin.ts](../../src/plugin.ts)
+- **Register plugin** → [src/__test__/registration.test.ts](../../src/__test__/registration.test.ts)
+- **HTTP routes** → [src/__test__/testRoute.test.ts](../../src/__test__/testRoute.test.ts)
+- **Send mail** → [src/__test__/sendMail.test.ts](../../src/__test__/sendMail.test.ts)
+
+## Examples
+
+Task-first table: [EXAMPLES.md](./EXAMPLES.md)
+
+## Read order
+
+This file → [workspace REFERENCE](../../../../docs/llm/REFERENCE.md#mailer) → [EXAMPLES.md](./EXAMPLES.md) → registration and route tests from REFERENCE or EXAMPLES.
+
+## Boundaries
+
+Do not enumerate every file under `src/`; use REFERENCE/EXAMPLES links first.
+
+| Capability | Notes |
+|----------|-------|
+| Sending | MJML → HTML, transport config |
+| Routes | Test or app-specific HTTP surface |
+| Config | Mailer options and helpers |
+
+- **Human docs:** [README.md](../../README.md) · [GUIDE.md](../../GUIDE.md)
diff --git a/packages/mailer/package.json b/packages/mailer/package.json
index e77152210..93f672186 100644
--- a/packages/mailer/package.json
+++ b/packages/mailer/package.json
@@ -20,7 +20,9 @@
   "module": "./dist/prefabs-tech-fastify-mailer.js",
   "types": "./dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs/llm",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly && mv dist/src dist/types",
diff --git a/packages/s3/AGENTS.md b/packages/s3/AGENTS.md
new file mode 100644
index 000000000..90324a63c
--- /dev/null
+++ b/packages/s3/AGENTS.md
@@ -0,0 +1,16 @@
+# Agent instructions — @prefabs.tech/fastify-s3
+
+Published **with the npm package**. Use **[README.md](./README.md)** first (see **For AI agents** there), then this file when the monorepo root isn’t available (for example under `node_modules`). The steps below minimize tokens and avoid broad `dist/`/`src/` scans.
+
+## Read order
+
+1. [docs/llm/INDEX.md](./docs/llm/INDEX.md) — package orientation and boundaries.
+2. [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md) — task → smallest source/test files.
+3. Workspace **[REFERENCE](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#s3)** — deep links to GUIDE, `src/index.ts`, `plugin.ts`, and tests (**not** in this tarball).
+4. Workspace **[INDEX](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/INDEX.md)** — map of all packages.
+
+Open sources and tests **only** via links on the REFERENCE page. Avoid scanning the full monorepo or large compiled trees unless these docs are missing, incomplete, or obviously stale.
+
+## In this install
+
+Per `package.json` → `files`, you typically have `dist/`, `docs/llm/`, and this file. For full source and tests, use **repository** in `package.json`.
diff --git a/packages/s3/README.md b/packages/s3/README.md
index 052dc6d5b..3c1fcff93 100644
--- a/packages/s3/README.md
+++ b/packages/s3/README.md
@@ -1,5 +1,9 @@
 # @prefabs.tech/fastify-s3
 
+## For AI agents
+
+**Read order:** [AGENTS.md](./AGENTS.md) → [docs/llm/INDEX.md](./docs/llm/INDEX.md) → [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md). Deep links to source and tests: [REFERENCE (s3)](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#s3). Avoid scanning `dist/` or large trees unless those docs are stale or insufficient.
+
 A [Fastify](https://github.com/fastify/fastify) plugin that provides an easy integration of S3 in a fastify API.
 
 ## Why this plugin?
diff --git a/packages/s3/docs/llm/EXAMPLES.md b/packages/s3/docs/llm/EXAMPLES.md
new file mode 100644
index 000000000..90fbdaba8
--- /dev/null
+++ b/packages/s3/docs/llm/EXAMPLES.md
@@ -0,0 +1,11 @@
+# @prefabs.tech/fastify-s3 — task → file
+
+Paths are relative to the package root (`packages/s3/`).
+
+| Task | Open first | Why |
+|------|------------|-----|
+| Register plugin | [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts) | Core registration |
+| S3 service usage | [src/__test__/service.test.ts](../../src/__test__/service.test.ts) | Client/service API |
+| GraphQL upload path | [src/plugins/__test__/graphqlUpload.test.ts](../../src/plugins/__test__/graphqlUpload.test.ts) | Upload plugin integration |
+| Public exports | [src/index.ts](../../src/index.ts) | API surface |
+| Plugin implementation | [src/plugin.ts](../../src/plugin.ts) | Fastify registration |
diff --git a/packages/s3/docs/llm/INDEX.md b/packages/s3/docs/llm/INDEX.md
new file mode 100644
index 000000000..15ae7eaf6
--- /dev/null
+++ b/packages/s3/docs/llm/INDEX.md
@@ -0,0 +1,31 @@
+# @prefabs.tech/fastify-s3 — LLM index
+
+AWS S3 client integration: uploads, object access, and Ajv-validated metadata; optional GraphQL upload paths.
+
+## Task router
+
+- **Public API / exports** → [src/index.ts](../../src/index.ts)
+- **Plugin implementation** → [src/plugin.ts](../../src/plugin.ts)
+- **Register plugin** → [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts)
+- **Service API** → [src/__test__/service.test.ts](../../src/__test__/service.test.ts)
+- **GraphQL upload** → [src/plugins/__test__/graphqlUpload.test.ts](../../src/plugins/__test__/graphqlUpload.test.ts)
+
+## Examples
+
+Task-first table: [EXAMPLES.md](./EXAMPLES.md)
+
+## Read order
+
+This file → [workspace REFERENCE](../../../../docs/llm/REFERENCE.md#s3) → [EXAMPLES.md](./EXAMPLES.md) → service and GraphQL upload tests from REFERENCE or EXAMPLES.
+
+## Boundaries
+
+Do not scan all plugins under `src/plugins/` unless REFERENCE points there; prefer linked test files.
+
+| Capability | Notes |
+|----------|-------|
+| S3 client | Configuration and service API |
+| Uploads | Routes / handlers as documented |
+| Validation | File metadata schemas |
+
+- **Human docs:** [README.md](../../README.md) · [GUIDE.md](../../GUIDE.md)
diff --git a/packages/s3/package.json b/packages/s3/package.json
index 98cfbe419..2753ecf08 100644
--- a/packages/s3/package.json
+++ b/packages/s3/package.json
@@ -20,7 +20,9 @@
   "module": "./dist/prefabs-tech-fastify-s3.js",
   "types": "./dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs/llm",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly && mv dist/src dist/types",
diff --git a/packages/slonik/AGENTS.md b/packages/slonik/AGENTS.md
new file mode 100644
index 000000000..3b02fc6d7
--- /dev/null
+++ b/packages/slonik/AGENTS.md
@@ -0,0 +1,16 @@
+# Agent instructions — @prefabs.tech/fastify-slonik
+
+Published **with the npm package**. Use **[README.md](./README.md)** first (see **For AI agents** there), then this file when the monorepo root isn’t available (for example under `node_modules`). The steps below minimize tokens and avoid broad `dist/`/`src/` scans.
+
+## Read order
+
+1. [docs/llm/INDEX.md](./docs/llm/INDEX.md) — package orientation and boundaries.
+2. [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md) — task → smallest source/test files.
+3. Workspace **[REFERENCE](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#slonik)** — deep links to GUIDE, `src/index.ts`, `plugin.ts`, and tests (**not** in this tarball).
+4. Workspace **[INDEX](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/INDEX.md)** — map of all packages.
+
+Open sources and tests **only** via links on the REFERENCE page. Avoid scanning the full monorepo or large compiled trees unless these docs are missing, incomplete, or obviously stale.
+
+## In this install
+
+Per `package.json` → `files`, you typically have `dist/`, `docs/llm/`, and this file. For full source and tests, use **repository** in `package.json`.
diff --git a/packages/slonik/README.md b/packages/slonik/README.md
index 6d16a18b5..c79916633 100644
--- a/packages/slonik/README.md
+++ b/packages/slonik/README.md
@@ -1,5 +1,9 @@
 # @prefabs.tech/fastify-slonik
 
+## For AI agents
+
+**Read order:** [AGENTS.md](./AGENTS.md) → [docs/llm/INDEX.md](./docs/llm/INDEX.md) → [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md). Deep links to source and tests: [REFERENCE (slonik)](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#slonik). Avoid scanning `dist/` or large trees unless those docs are stale or insufficient.
+
 A [Fastify](https://github.com/fastify/fastify) plugin that provides an easy integration of slonik in a fastify API.
 
 The plugin is a thin wrapper around the [`fastify-slonik`](https://github.com/spa5k/fastify-slonik) plugin.
diff --git a/packages/slonik/docs/llm/EXAMPLES.md b/packages/slonik/docs/llm/EXAMPLES.md
new file mode 100644
index 000000000..0dd7bf4c7
--- /dev/null
+++ b/packages/slonik/docs/llm/EXAMPLES.md
@@ -0,0 +1,13 @@
+# @prefabs.tech/fastify-slonik — task → file
+
+Paths are relative to the package root (`packages/slonik/`). Prefer these before broad `src/` scans.
+
+| Task | Open first | Why |
+|------|------------|-----|
+| Register DB plugin | [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts) | Default pool + decorators |
+| Query service API | [src/__test__/service.test.ts](../../src/__test__/service.test.ts) | Service usage |
+| Migrations (runner / plugin) | [src/__test__/migrate.test.ts](../../src/__test__/migrate.test.ts), [src/__test__/migrationPlugin.test.ts](../../src/__test__/migrationPlugin.test.ts) | Migration flows |
+| SQL helpers | [src/__test__/sql.test.ts](../../src/__test__/sql.test.ts), [src/__test__/sqlFactory.test.ts](../../src/__test__/sqlFactory.test.ts) | SQL utilities |
+| Filters / hooks | [src/__test__/filters.test.ts](../../src/__test__/filters.test.ts), [src/__test__/serviceWithHooks.test.ts](../../src/__test__/serviceWithHooks.test.ts) | Advanced usage |
+| Public exports | [src/index.ts](../../src/index.ts) | API surface |
+| Plugin implementation | [src/plugin.ts](../../src/plugin.ts) | Fastify registration |
diff --git a/packages/slonik/docs/llm/INDEX.md b/packages/slonik/docs/llm/INDEX.md
new file mode 100644
index 000000000..4ca3067ad
--- /dev/null
+++ b/packages/slonik/docs/llm/INDEX.md
@@ -0,0 +1,31 @@
+# @prefabs.tech/fastify-slonik — LLM index
+
+PostgreSQL via Slonik: connection pool, migrations plugin, and SQL helpers exposed on the Fastify instance for handlers and other plugins.
+
+## Task router
+
+- **Public API / exports** → [src/index.ts](../../src/index.ts)
+- **Plugin implementation** → [src/plugin.ts](../../src/plugin.ts)
+- **Register DB plugin** → [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts)
+- **Service API** → [src/__test__/service.test.ts](../../src/__test__/service.test.ts)
+- **Migrations** → [src/__test__/migrate.test.ts](../../src/__test__/migrate.test.ts), [src/__test__/migrationPlugin.test.ts](../../src/__test__/migrationPlugin.test.ts)
+
+## Examples
+
+Task-first table: [EXAMPLES.md](./EXAMPLES.md)
+
+## Read order
+
+This file → [workspace REFERENCE](../../../../docs/llm/REFERENCE.md#slonik) → [EXAMPLES.md](./EXAMPLES.md) → [GUIDE.md](../../GUIDE.md) · [feature.md](../../feature.md) (human) → REFERENCE-linked sources/tests.
+
+## Boundaries
+
+Do not walk the entire `src/` tree; Slonik and migration code paths are large—use REFERENCE/EXAMPLES deep links.
+
+| Capability | Notes |
+|----------|-------|
+| Database | Pool + query API |
+| Migrations | Optional migration plugin |
+| SQL helpers | See GUIDE and tests |
+
+- **Human docs:** [README.md](../../README.md) · [GUIDE.md](../../GUIDE.md)
diff --git a/packages/slonik/package.json b/packages/slonik/package.json
index 145f21321..7b9b3bf8d 100644
--- a/packages/slonik/package.json
+++ b/packages/slonik/package.json
@@ -20,7 +20,9 @@
   "module": "./dist/prefabs-tech-fastify-slonik.js",
   "types": "./dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs/llm",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly && mv dist/src dist/types",
diff --git a/packages/swagger/AGENTS.md b/packages/swagger/AGENTS.md
new file mode 100644
index 000000000..6a7c6b844
--- /dev/null
+++ b/packages/swagger/AGENTS.md
@@ -0,0 +1,16 @@
+# Agent instructions — @prefabs.tech/fastify-swagger
+
+Published **with the npm package**. Use **[README.md](./README.md)** first (see **For AI agents** there), then this file when the monorepo root isn’t available (for example under `node_modules`). The steps below minimize tokens and avoid broad `dist/`/`src/` scans.
+
+## Read order
+
+1. [docs/llm/INDEX.md](./docs/llm/INDEX.md) — package orientation and boundaries.
+2. [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md) — task → smallest source/test files.
+3. Workspace **[REFERENCE](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#swagger)** — deep links to GUIDE, `src/index.ts`, `plugin.ts`, and tests (**not** in this tarball).
+4. Workspace **[INDEX](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/INDEX.md)** — map of all packages.
+
+Open sources and tests **only** via links on the REFERENCE page. Avoid scanning the full monorepo or large compiled trees unless these docs are missing, incomplete, or obviously stale.
+
+## In this install
+
+Per `package.json` → `files`, you typically have `dist/`, `docs/llm/`, and this file. For full source and tests, use **repository** in `package.json`.
diff --git a/packages/swagger/README.md b/packages/swagger/README.md
index 2fdb9c6a4..cf6046ac5 100644
--- a/packages/swagger/README.md
+++ b/packages/swagger/README.md
@@ -1,5 +1,9 @@
 # @prefabs.tech/fastify-swagger
 
+## For AI agents
+
+**Read order:** [AGENTS.md](./AGENTS.md) → [docs/llm/INDEX.md](./docs/llm/INDEX.md) → [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md). Deep links to source and tests: [REFERENCE (swagger)](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#swagger). Avoid scanning `dist/` or large trees unless those docs are stale or insufficient.
+
 A [Fastify](https://github.com/fastify/fastify) plugin that provides an easy integration of swagger in fastify API.
 
 ## Why this plugin?
diff --git a/packages/swagger/docs/llm/EXAMPLES.md b/packages/swagger/docs/llm/EXAMPLES.md
new file mode 100644
index 000000000..abc904131
--- /dev/null
+++ b/packages/swagger/docs/llm/EXAMPLES.md
@@ -0,0 +1,9 @@
+# @prefabs.tech/fastify-swagger — task → file
+
+Paths are relative to the package root (`packages/swagger/`).
+
+| Task | Open first | Why |
+|------|------------|-----|
+| Register plugin, OpenAPI / UI wiring | [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts) | Primary integration test |
+| Public exports | [src/index.ts](../../src/index.ts) | API surface |
+| Plugin implementation | [src/plugin.ts](../../src/plugin.ts) | Fastify registration |
diff --git a/packages/swagger/docs/llm/INDEX.md b/packages/swagger/docs/llm/INDEX.md
new file mode 100644
index 000000000..4c2b750d0
--- /dev/null
+++ b/packages/swagger/docs/llm/INDEX.md
@@ -0,0 +1,29 @@
+# @prefabs.tech/fastify-swagger — LLM index
+
+OpenAPI spec exposure and Swagger UI wiring for Fastify, aligned with how routes and schemas are registered in consuming apps.
+
+## Task router
+
+- **Public API / exports** → [src/index.ts](../../src/index.ts)
+- **Plugin implementation** → [src/plugin.ts](../../src/plugin.ts)
+- **Registration + UI/spec (smallest story)** → [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts)
+
+## Examples
+
+Task-first table: [EXAMPLES.md](./EXAMPLES.md)
+
+## Read order
+
+This file → [workspace REFERENCE](../../../../docs/llm/REFERENCE.md#swagger) → [EXAMPLES.md](./EXAMPLES.md) → linked files from REFERENCE or EXAMPLES.
+
+## Boundaries
+
+Do not broad-scan `src/` unless docs are stale; UI and schema details live in GUIDE and tests linked from REFERENCE.
+
+| Capability | Notes |
+|----------|-------|
+| OpenAPI | Spec generation / exposure |
+| Swagger UI | Dev-facing documentation UI |
+| Integration | Depends on app route/schema setup |
+
+- **Human docs:** [README.md](../../README.md) · [GUIDE.md](../../GUIDE.md)
diff --git a/packages/swagger/package.json b/packages/swagger/package.json
index e588aace3..d08286a31 100644
--- a/packages/swagger/package.json
+++ b/packages/swagger/package.json
@@ -20,7 +20,9 @@
   "module": "./dist/prefabs-tech-fastify-swagger.js",
   "types": "./dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs/llm",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly && mv dist/src dist/types",
diff --git a/packages/user/AGENTS.md b/packages/user/AGENTS.md
new file mode 100644
index 000000000..d2930175f
--- /dev/null
+++ b/packages/user/AGENTS.md
@@ -0,0 +1,16 @@
+# Agent instructions — @prefabs.tech/fastify-user
+
+Published **with the npm package**. Use **[README.md](./README.md)** first (see **For AI agents** there), then this file when the monorepo root isn’t available (for example under `node_modules`). The steps below minimize tokens and avoid broad `dist/`/`src/` scans.
+
+## Read order
+
+1. [docs/llm/INDEX.md](./docs/llm/INDEX.md) — package orientation and boundaries.
+2. [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md) — task → smallest source/test files.
+3. Workspace **[REFERENCE](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#user)** — deep links to GUIDE, `src/index.ts`, `plugin.ts`, and tests (**not** in this tarball).
+4. Workspace **[INDEX](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/INDEX.md)** — map of all packages.
+
+Open sources and tests **only** via links on the REFERENCE page. Avoid scanning the full monorepo or large compiled trees unless these docs are missing, incomplete, or obviously stale.
+
+## In this install
+
+Per `package.json` → `files`, you typically have `dist/`, `docs/llm/`, and this file. For full source and tests, use **repository** in `package.json`.
diff --git a/packages/user/README.md b/packages/user/README.md
index 148644ee7..c768e2f25 100644
--- a/packages/user/README.md
+++ b/packages/user/README.md
@@ -1,5 +1,9 @@
 # @prefabs.tech/fastify-user
 
+## For AI agents
+
+**Read order:** [AGENTS.md](./AGENTS.md) → [docs/llm/INDEX.md](./docs/llm/INDEX.md) → [docs/llm/EXAMPLES.md](./docs/llm/EXAMPLES.md). Deep links to source and tests: [REFERENCE (user)](https://github.com/prefabs-tech/fastify/blob/main/docs/llm/REFERENCE.md#user). Avoid scanning `dist/` or large trees unless those docs are stale or insufficient.
+
 A [Fastify](https://github.com/fastify/fastify) plugin that provides an easy integration of user model (service, controller, resolver) in a fastify API.
 
 ## Why this plugin?
diff --git a/packages/user/docs/llm/EXAMPLES.md b/packages/user/docs/llm/EXAMPLES.md
new file mode 100644
index 000000000..8f7a4e4ca
--- /dev/null
+++ b/packages/user/docs/llm/EXAMPLES.md
@@ -0,0 +1,19 @@
+# @prefabs.tech/fastify-user — task → file
+
+Paths are relative to the package root (`packages/user/`).
+
+Structured, numbered capability list (routes, invitations, GraphQL ops): see [FEATURES.md](../../FEATURES.md) — e.g. items **24–25** (`/signup/admin`), the **Invitations** section (**45+**), and **73–74** (GraphQL user/invitation operations).
+
+| Task | Open first | Why |
+|------|------------|-----|
+| Register user / SuperTokens plugin | [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts) | Primary entry test |
+| Bootstrap first admin (REST `POST` / `GET /signup/admin`) | [src/model/users/handlers/adminSignUp.ts](../../src/model/users/handlers/adminSignUp.ts) | Handler body; routes registered alongside other user routes in [src/model/users/controller.ts](../../src/model/users/controller.ts) |
+| Bootstrap admin (`adminSignUp` mutation) | [src/model/users/graphql/resolver.ts](../../src/model/users/graphql/resolver.ts) | Mutation implementation; SDL in [src/model/users/graphql/schema.ts](../../src/model/users/graphql/schema.ts) |
+| Create invitation | [src/model/invitations/handlers/createInvitation.ts](../../src/model/invitations/handlers/createInvitation.ts) | Starts onboarding flow for additional users |
+| Accept invitation (token → SuperTokens account + session) | [src/model/invitations/handlers/acceptInvitation.ts](../../src/model/invitations/handlers/acceptInvitation.ts) | Completes onboarding after invite |
+| Invitation REST wiring | [src/model/invitations/controller.ts](../../src/model/invitations/controller.ts) | Registers invitation routes → handlers |
+| Product email/password sign-up (SuperTokens recipe) | [src/supertokens/recipes/config/third-party-email-password/emailPasswordSignUp.ts](../../src/supertokens/recipes/config/third-party-email-password/emailPasswordSignUp.ts) | Sign-up overrides; defaults merged in [src/supertokens/recipes/config/thirdPartyEmailPasswordRecipeConfig.ts](../../src/supertokens/recipes/config/thirdPartyEmailPasswordRecipeConfig.ts) |
+| Route/path constants (`ROUTE_SIGNUP_ADMIN`, etc.) | [src/constants.ts](../../src/constants.ts) | Canonical path strings |
+| Deeper behavior | [src/](../../src/) nested `**/__test__` | Only after plugin test; follow imports or workspace REFERENCE |
+| Public exports | [src/index.ts](../../src/index.ts) | API surface |
+| Plugin implementation | [src/plugin.ts](../../src/plugin.ts) | Fastify registration |
diff --git a/packages/user/docs/llm/INDEX.md b/packages/user/docs/llm/INDEX.md
new file mode 100644
index 000000000..546fe8fa2
--- /dev/null
+++ b/packages/user/docs/llm/INDEX.md
@@ -0,0 +1,31 @@
+# @prefabs.tech/fastify-user — LLM index
+
+Authentication and user model: SuperTokens integration, roles, sessions, and user-related Fastify decorators/context used by APIs.
+
+## Task router
+
+- **Public API / exports** → [src/index.ts](../../src/index.ts)
+- **Plugin implementation** → [src/plugin.ts](../../src/plugin.ts)
+- **Primary integration test** → [src/__test__/plugin.test.ts](../../src/__test__/plugin.test.ts)
+- **More behavior** → nested `**/__test__` under [src/](../../src/) only after the above
+- **User creation / bootstrap admin / invitations / SuperTokens sign-up** → task → file table in [EXAMPLES.md](./EXAMPLES.md)
+
+## Examples
+
+Task-first table: [EXAMPLES.md](./EXAMPLES.md)
+
+## Read order
+
+This file → [workspace REFERENCE](../../../../docs/llm/REFERENCE.md#user) → [EXAMPLES.md](./EXAMPLES.md) → plugin test, then nested tests only as needed.
+
+## Boundaries
+
+Do not recursively read all nested tests without cause; start with REFERENCE/EXAMPLES and the primary plugin test.
+
+| Capability | Notes |
+|----------|-------|
+| SuperTokens | Plugin and session lifecycle |
+| Roles / user | Decorators and types |
+| Integration | Often depends on `config` and `graphql` |
+
+- **Human docs:** [README.md](../../README.md) · [GUIDE.md](../../GUIDE.md) · [FEATURES.md](../../FEATURES.md)
diff --git a/packages/user/package.json b/packages/user/package.json
index 20c7f8702..a3cf83d2d 100644
--- a/packages/user/package.json
+++ b/packages/user/package.json
@@ -20,7 +20,9 @@
   "module": "./dist/prefabs-tech-fastify-user.js",
   "types": "./dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs/llm",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly && mv dist/src dist/types",