diff --git a/CLAUDE.md b/CLAUDE.md
index e4b45a2..10d64d9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -29,7 +29,7 @@ See `docs/guides/tdd-workflow.md` for the full cycle.
 
 ## Project Overview
 
-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. Two tooling packages (`core-eslint`, `core-typescript`) provide shared configs. Workspace boundaries are enforced by ESLint (lint-time) and Turborepo (build-graph time). 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. Must-have core packages (`core-shared`, `core-cms`, `core-api`) provide foundation; four optional core packages (`core-realtime`, `core-events`, `core-trpc`, `core-ui`) scaffold on demand via `pnpm turbo gen core-package <name>` (see `docs/architecture/template-tiers.md`). Two tooling packages (`core-eslint`, `core-typescript`) provide shared configs. Workspace boundaries are enforced by ESLint (lint-time) and Turborepo (build-graph time). Supports Next.js and TanStack Start as frontend frameworks, Payload CMS for content management, and comprehensive agent-optimized documentation.
 
 ## Read First
 
@@ -38,8 +38,9 @@ Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`,
 - `docs/architecture/vertical-feature-spec.md` — Design spec with rationale and decision log
 - `docs/guides/scaffolding-a-feature.md` — `turbo gen feature` reference (fast path; prefer this over the manual walkthrough)
 - `docs/guides/adding-a-feature.md` — End-to-end new feature walkthrough (manual path; for cases the generator's Phase-1 scope doesn't cover)
-- `docs/guides/events-and-jobs.md` — publish/consume/schedule cookbook (cross-feature events + background jobs)
-- `docs/guides/realtime.md` — Socket.IO channels, broadcasts, handlers
+- `docs/guides/events-and-jobs.md` — publish/consume/schedule cookbook (cross-feature events + background jobs; *requires `gen core-package events`*)
+- `docs/guides/realtime.md` — Socket.IO channels, broadcasts, handlers (*requires `gen core-package realtime`*)
+- `docs/architecture/template-tiers.md` — must-have vs optional packages and how to scaffold the optionals
 
 ## Key Conventions
 
diff --git a/docs/architecture/dependency-flow.md b/docs/architecture/dependency-flow.md
index 006ecc5..69c61a2 100644
--- a/docs/architecture/dependency-flow.md
+++ b/docs/architecture/dependency-flow.md
@@ -74,7 +74,7 @@ import { ArticleNotFoundError } from "@repo/blog";   // ❌ core → feature
                                                      // constructors as args from features —
                                                      // core-shared never imports them)
 
-// in packages/core-trpc
+// in packages/core-shared (or any non-composition core package)
 import { someBlogThing } from "@repo/blog";          // ❌ core → feature (only core-api/core-cms have exception)
 
 // in apps (using the wrong subpath)
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 5bee287..9099da2 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -94,11 +94,13 @@ Both use the same five-tag model; see "Five tags" section below.
 The workspace is organized into five mutually exclusive tags:
 
 - **app** (4 packages): `apps/cms`, `apps/web-next`, `apps/web-tanstack`, `apps/storybook`
-- **core-composition** (3 packages): `packages/core-api`, `packages/core-cms`, `packages/core-trpc`
-- **core** (2 packages): `packages/core-shared`, `packages/core-ui`
+- **core-composition** (2 must-have): `packages/core-api`, `packages/core-cms`. Plus `packages/core-trpc` when scaffolded via `pnpm turbo gen core-package trpc` (optional).
+- **core** (1 must-have): `packages/core-shared`. Plus `packages/core-ui`, `packages/core-realtime`, `packages/core-events` when scaffolded via `pnpm turbo gen core-package <name>` (optional).
 - **feature** (5 packages): `packages/auth`, `packages/blog`, `packages/media`, `packages/marketing-pages`, `packages/navigation`
 - **tooling** (2 packages): `packages/core-eslint`, `packages/core-typescript`
 
+See `docs/architecture/template-tiers.md` for the must-have/optional split and the scaffold commands.
+
 **Allowed dependency directions:**
 
 | Tag | May depend on |