chore: add LLM and agent entry points (root and packages)

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.

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`.

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?

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 |

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)

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",

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`.

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?

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 |

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)

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",

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`.

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?

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 |

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)

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",

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`.

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.

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 |

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)