diff --git a/AGENTS.md b/AGENTS.md
index b42ebb5e32625f6823ead8b4d5715b398fb49e51..37a3c14991c3e33b5c2e34eb645a13420e87cdfa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,7 +26,8 @@ Long term maintainability is a core priority. If you add new functionality, firs
 
 - `apps/server`: Node.js WebSocket server. Wraps Codex app-server (JSON-RPC over stdio), serves the React web app, and manages provider sessions.
 - `apps/web`: React/Vite UI. Owns session UX, conversation/event rendering, and client-side state. Connects to the server via WebSocket.
-- `packages/contracts`: Shared effect/Schema schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types.
+- `packages/contracts`: Shared effect/Schema schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types. Keep this package schema-only — no runtime logic.
+- `packages/shared`: Shared runtime utilities consumed by both server and web. Uses explicit subpath exports (e.g. `@t3tools/shared/git`) — no barrel index.
 
 ## Codex App Server (Important)