From 4c7ccf9d1cbb1c9774670cd3168626d3ab77382f Mon Sep 17 00:00:00 2001
From: Danijel Martinek <danijel@fraqtal.xyz>
Date: Sat, 9 May 2026 13:23:37 +0200
Subject: [PATCH] docs: core-package generator reference + Quick Start entry

Adds docs/scaffolding/core-package-generator.md with usage, template
table, and drift-verification instructions. Updates CLAUDE.md Quick
Start and AGENTS.md Key Commands with the new pnpm turbo gen core-package
entry. Creates templates/core-package/.gitkeep placeholder for Phase 3+.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 AGENTS.md                                     |  3 +-
 CLAUDE.md                                     |  1 +
 docs/scaffolding/core-package-generator.md    | 40 +++++++++++++++++++
 .../templates/core-package/.gitkeep           |  0
 4 files changed, 43 insertions(+), 1 deletion(-)
 create mode 100644 docs/scaffolding/core-package-generator.md
 create mode 100644 turbo/generators/templates/core-package/.gitkeep

diff --git a/AGENTS.md b/AGENTS.md
index 6c0d62b..a06118c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -93,7 +93,8 @@ pnpm dev               # Start all dev servers (Next.js :3000, CMS :3001, Storyb
 pnpm typecheck         # Type-check all packages
 pnpm lint              # Lint all packages (ESLint boundaries enforced)
 pnpm turbo boundaries  # Validate workspace dependency graph (Turbo boundaries)
-pnpm turbo gen feature # Scaffold a new Lazar-conformant feature package (see docs/guides/scaffolding-a-feature.md)
+pnpm turbo gen feature       # Scaffold a new Lazar-conformant feature package (see docs/guides/scaffolding-a-feature.md)
+pnpm turbo gen core-package  # Scaffold an optional core package back (realtime, events, trpc, ui — see docs/scaffolding/core-package-generator.md)
 pnpm test              # Run all unit + integration tests (Vitest)
 pnpm test:e2e          # Run e2e tests (Playwright across both apps)
 pnpm build             # Build all packages (Turborepo)
diff --git a/CLAUDE.md b/CLAUDE.md
index 3453f06..e4b45a2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,6 +12,7 @@ pnpm turbo gen feature # Scaffold a new feature package (see docs/guides/scaffol
 pnpm turbo gen event   # Scaffold an event contract (publish) or handler (consume)
 pnpm turbo gen job     # Scaffold a background job
 pnpm turbo gen realtime # Scaffold a realtime channel or inbound handler
+pnpm turbo gen core-package # Scaffold an optional core package (see docs/scaffolding/core-package-generator.md)
 docker compose up -d   # Start PostgreSQL
 ```
 
diff --git a/docs/scaffolding/core-package-generator.md b/docs/scaffolding/core-package-generator.md
new file mode 100644
index 0000000..a4ebd57
--- /dev/null
+++ b/docs/scaffolding/core-package-generator.md
@@ -0,0 +1,40 @@
+# Core-package generator
+
+`pnpm turbo gen core-package` scaffolds an optional core package back into a slimmed template. Each name maps to a verbatim copy of the package as it shipped at the time the generator was added.
+
+## Usage
+
+```bash
+pnpm turbo gen core-package
+# → Which optional core package? (use arrow keys)
+#   ❯ realtime
+#     events
+#     trpc
+#     ui
+```
+
+The generator emits the package files, updates consuming-app config (e.g. `apps/web-next/next.config.mjs` `transpilePackages`), patches `packages/core-eslint/base.js` to re-add any package-specific lint rules, then prints the manual app/server wiring needed to bring the package fully online.
+
+## Available templates
+
+| Name | Description | Phase added |
+|---|---|---|
+| `realtime` | Socket.IO realtime layer (ADR-016) | Phase 3 |
+| `events` | Cross-feature event bus + Payload jobs adapter (ADR-015) | Phase 4 |
+| `trpc` | tRPC server setup | Phase 5 |
+| `ui` | Design-system package | Phase 6 |
+
+(Until Phases 3-6 land, the generator will list an empty choices array and reject any selection.)
+
+## Verifying an existing project
+
+If your project already has a core-* package and you want to verify the generator's template hasn't drifted from the shipped source, use the byte-identical reconstruction snapshot:
+
+```bash
+git stash -u
+pnpm turbo gen core-package <name>
+git diff packages/core-<name>/
+# Expect: zero diff (modulo .hbs strip + trailing-newline normalization)
+```
+
+Snapshots live at `turbo/generators/__snapshots__/core-package/<name>.snapshot.json` (added in Phases 3-6).
diff --git a/turbo/generators/templates/core-package/.gitkeep b/turbo/generators/templates/core-package/.gitkeep
new file mode 100644
index 0000000..e69de29