diff --git a/CLAUDE.md b/CLAUDE.md
index 389e2e1ab..4b2b0e208 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -370,6 +370,16 @@ curl http://localhost:3007/api/favorites \
 | Presi    | Custom (same pattern)           | 3008 |
 | ManaDeck | `@mana-core/nestjs-integration` | 3009 |
 
+#### Adding a New App to SSO
+
+When adding a new app that should participate in cross-app SSO, update **all three** locations:
+
+1. `trustedOrigins` in `services/mana-core-auth/src/auth/better-auth.config.ts`
+2. `CORS_ORIGINS` for mana-auth in `docker-compose.macmini.yml`
+3. Run `pnpm test -- src/auth/sso-config.spec.ts` (from `services/mana-core-auth/`) to verify
+
+Missing any of these will silently break SSO for that app.
+
 ### Search Architecture
 
 Projects requiring web search and content extraction use **mana-search** as the central search service:
diff --git a/services/mana-core-auth/CLAUDE.md b/services/mana-core-auth/CLAUDE.md
index 2ba552729..cdf4e49c4 100644
--- a/services/mana-core-auth/CLAUDE.md
+++ b/services/mana-core-auth/CLAUDE.md
@@ -197,6 +197,11 @@ advanced: {
 - Production: `COOKIE_DOMAIN=.mana.how`
 - Development: Leave empty (cookies domain-specific)
 
+**Adding a new app to SSO** (all 3 steps required):
+1. Add `https://{app}.mana.how` to `trustedOrigins` in `better-auth.config.ts`
+2. Add `https://{app}.mana.how` to `CORS_ORIGINS` for mana-auth in `docker-compose.macmini.yml`
+3. Run `pnpm test -- src/auth/sso-config.spec.ts` to verify alignment (47 contract tests)
+
 ## Test Credentials (Production)
 
 For automated testing against `auth.mana.how`: