diff --git a/CLAUDE.md b/CLAUDE.md
index d8e080a..1171dc1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,13 +12,23 @@ docker compose up -d  # Start PostgreSQL
 
 ## Project Overview
 
-Turborepo + pnpm monorepo based on Clean Architecture (Uncle Bob / Lazar Nikolov). Supports Next.js and TanStack Start as frontend frameworks, Payload CMS for content management, and comprehensive agent-optimized documentation.
+Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`, `blog`, `media`, `marketing-pages`, `navigation`) owns its Clean Architecture layers. Core packages (`core-shared`, `core-cms`, `core-api`, `core-trpc`, `core-ui`) provide foundation. Supports Next.js and TanStack Start as frontend frameworks, Payload CMS for content management, and comprehensive agent-optimized documentation.
 
 ## Read First
 
-- `AGENTS.md` — Monorepo structure, dependency flow, hard rules
-- `docs/architecture/overview.md` — High-level architecture
-- `docs/guides/adding-a-feature.md` — End-to-end walkthrough
+- `AGENTS.md` — Package map, boundary rules, per-package conventions
+- `docs/architecture/overview.md` — High-level architecture and package responsibilities
+- `docs/architecture/vertical-feature-spec.md` — Design spec with rationale and decision log
+- `docs/guides/adding-a-feature.md` — End-to-end new feature walkthrough
+
+## Key Conventions
+
+- **Relative imports in `src/`** — Source files use relative paths (`../repositories/...`), not `@/` alias
+- **`@/` alias in tests** — Test files (`*.test.ts`) use `@/` to import from `src/`
+- **`vitest.config.ts`** — Every package must define `resolve.alias: { "@": path.resolve(__dirname, "./src") }`
+- **`tsconfig.json` rootDir** — Set `"rootDir": "."` so TypeScript finds both `src/` and test files
+- **Payload repositories via constructor** — Feature packages receive Payload config at constructor time, not as a direct dependency
+- **App bootstrap** — Each app calls `bindProduction*()` per feature at startup to wire Payload into InversifyJS containers
 
 ## MCP Servers