docs(agents): add per-package AGENTS.md for all core-* packages

packages/core-api/AGENTS.md

@@ -0,0 +1,48 @@
+# AGENTS.md — core-api
+
+**Composition-only package** that aggregates feature tRPC routers into a single root `appRouter`. It does not define procedures; instead, it imports them from feature packages.
+
+## Responsibilities
+
+- **Compose tRPC appRouter** — merges feature routers into `t.router({ ... })`
+- **Type export** — exports `AppRouter` type for frontend type safety
+- **No procedure definitions** — all routers owned by their respective features (`@repo/auth`, `@repo/blog`, etc.)
+- **No business logic** — purely structural assembly
+
+## Allowed imports
+
+- **`@repo/<feature>/api`** subpath exports only (to get tRPC routers)
+  - e.g., `import { authRouter } from "@repo/auth/api"`
+  - e.g., `import { blogRouter } from "@repo/blog/api"`
+  - e.g., `import { navigationRouter } from "@repo/navigation/api"`
+- `@repo/core-shared/trpc/init` — for `t.router()` builder
+
+## Must NOT import
+
+- Any feature's root package or other subpaths (e.g., NOT `@repo/blog/di`, NOT `@repo/blog/entities`)
+- Any app package
+- `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui`
+
+## Public exports
+
+From `package.json`:
+- `.` — `appRouter` and `AppRouter` type
+
+Example usage:
+```typescript
+import { appRouter, type AppRouter } from "@repo/core-api";
+```
+
+## Test conventions
+
+- No unit tests (composition layer)
+- Verify at app boot: `pnpm dev --filter @repo/web-next` succeeds and tRPC client fetches data
+- Run router health check: `pnpm typecheck` confirms `AppRouter` type is valid
+
+## Structure
+
+```
+src/
+  root.ts                    # t.router({ ... }) aggregating all feature routers
+  index.ts                   # re-exports appRouter + type
+```