diff --git a/AGENTS.md b/AGENTS.md
index a7dbde3ac4..5d960e83b5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -192,6 +192,23 @@ import { User } from "@prisma/client";
 import { Button } from "@calcom/ui";
 ```
 
+### API v2 Imports (apps/api/v2)
+
+When importing from `@calcom/features` or `@calcom/trpc` into `apps/api/v2`, **do not import directly** because the API v2 app's `tsconfig.json` doesn't have path mappings for these modules, which causes "module not found" errors.
+
+Instead, re-export from `packages/platform/libraries/index.ts` and import from `@calcom/platform-libraries`:
+
+```typescript
+// Step 1: In packages/platform/libraries/index.ts, add the export
+export { ProfileRepository } from "@calcom/features/profile/repositories/ProfileRepository";
+
+// Step 2: In apps/api/v2, import from platform-libraries
+import { ProfileRepository } from "@calcom/platform-libraries";
+
+// Bad - Direct import causes module not found error in apps/api/v2
+import { ProfileRepository } from "@calcom/features/profile/repositories/ProfileRepository";
+```
+
 ## PR Checklist
 
 - [ ] Title follows conventional commits: `feat(scope): description`