From 0ede53998fd83950dfd2ef3b65eb7ce989bbd07d Mon Sep 17 00:00:00 2001
From: Danijel Martinek <danijel@fraqtal.xyz>
Date: Tue, 5 May 2026 09:59:08 +0200
Subject: [PATCH] docs(agents): add per-package AGENTS.md for eslint-config +
 typescript-config

---
 packages/eslint-config/AGENTS.md     | 67 ++++++++++++++++++++++++
 packages/typescript-config/AGENTS.md | 77 ++++++++++++++++++++++++++++
 2 files changed, 144 insertions(+)
 create mode 100644 packages/eslint-config/AGENTS.md
 create mode 100644 packages/typescript-config/AGENTS.md

diff --git a/packages/eslint-config/AGENTS.md b/packages/eslint-config/AGENTS.md
new file mode 100644
index 0000000..e64a563
--- /dev/null
+++ b/packages/eslint-config/AGENTS.md
@@ -0,0 +1,67 @@
+# AGENTS.md — eslint-config
+
+Shared ESLint 9 flat configs (rules, plugins, parser settings) consumed by all packages via `eslint.config.js`.
+
+## What it owns
+
+- **`base.js`** — Core ESLint rules: no `console`, no `debugger`, strict `@typescript-eslint` config
+- **`next.js`** — Next.js-specific rules: `"use client"` boundaries, `next/no-img-element`
+- **`react-internal.js`** — React library rules: component display names, hook rules
+- **`boundaries.js`** — `eslint-plugin-boundaries` config enforcing vertical feature architecture:
+  - Features may only import `core-*` and tooling packages
+  - Core packages may only import other core packages (with composition exceptions for `core-cms`, `core-api`)
+  - No cross-feature imports
+  - No deep source path imports (only public subpath exports)
+
+## How packages consume them
+
+Each package creates `eslint.config.js` at its root:
+
+```javascript
+// packages/blog/eslint.config.js
+import baseConfig from "@repo/eslint-config/base";
+import boundariesConfig from "@repo/eslint-config/boundaries";
+
+export default [
+  ...baseConfig,
+  ...boundariesConfig,
+  {
+    files: ["src/**/*.tsx"],
+    rules: {
+      "react/display-name": "off",
+    },
+  },
+];
+```
+
+Apps may add Next.js-specific rules:
+
+```javascript
+// apps/web-next/eslint.config.js
+import baseConfig from "@repo/eslint-config/base";
+import nextConfig from "@repo/eslint-config/next";
+import boundariesConfig from "@repo/eslint-config/boundaries";
+
+export default [
+  ...baseConfig,
+  ...nextConfig,
+  ...boundariesConfig,
+];
+```
+
+## Test conventions
+
+- No unit tests (config validation via lint pass/fail in other packages)
+- Verify at CI: `pnpm lint` succeeds across all packages
+- ESLint should catch boundary violations: `pnpm lint` fails on feature→feature imports or deep imports
+
+## Structure
+
+```
+src/
+  base.js                    # Core TypeScript + ESLint config
+  next.js                    # Next.js additions
+  react-internal.js          # React library rules
+  boundaries.js              # Feature boundaries + composition rules
+  index.js                   # Re-exports all configs
+```
diff --git a/packages/typescript-config/AGENTS.md b/packages/typescript-config/AGENTS.md
new file mode 100644
index 0000000..67ebb71
--- /dev/null
+++ b/packages/typescript-config/AGENTS.md
@@ -0,0 +1,77 @@
+# AGENTS.md — typescript-config
+
+Shared TypeScript base configs (`tsconfig.json` files) and Vitest base config, consumed by all packages.
+
+## What it owns
+
+- **`base.json`** — Base `tsconfig.json`: target ES2022, module ESM, `experimentalDecorators` + `emitDecoratorMetadata` for InversifyJS
+- **`nextjs.json`** — Next.js app config: extends base, adds `jsx: "preserve"`, Next.js lib types
+- **`react-library.json`** — React library config: extends base, adds `jsx: "react-jsx"`, DOM lib
+- **`vitest.base.ts`** — Vitest base config: globals, isolate modules, common ignore patterns
+
+## How packages consume them
+
+Packages extend the appropriate base:
+
+```json
+// packages/blog/tsconfig.json
+{
+  "extends": "@repo/typescript-config/base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist",
+    "lib": ["ES2022"]
+  },
+  "include": ["src/**/*"]
+}
+```
+
+Apps extend Next.js config:
+
+```json
+// apps/web-next/tsconfig.json
+{
+  "extends": "@repo/typescript-config/nextjs.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": ".next"
+  }
+}
+```
+
+Vitest configs import the base:
+
+```typescript
+// packages/blog/vitest.config.ts
+import { defineConfig } from "vitest/config";
+import path from "path";
+import { vitestBase } from "@repo/typescript-config";
+
+export default defineConfig({
+  ...vitestBase,
+  test: {
+    environment: "node",
+  },
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+});
+```
+
+## Test conventions
+
+- No unit tests (config validation via `pnpm typecheck` in other packages)
+- Verify at CI: `pnpm typecheck` succeeds across all packages
+- Type errors should propagate: `pnpm typecheck` fails on invalid source code
+
+## Structure
+
+```
+base.json                    # ES2022, ESM, decorators
+nextjs.json                  # Next.js-specific paths + lib
+react-library.json           # React JSX + DOM
+vitest.base.ts               # Vitest defaults (globals, isolate)
+package.json                 # Exports above files
+```