docs: surface turbo gen feature in AGENTS.md and CLAUDE.md

Wires the existing turbo gen feature generator into AGENTS.md (Adding
a Feature section, Key Commands, Specification & Guides) and
CLAUDE.md (Quick Start, Read First). Adds a fast-path callout at the
top of the manual walkthrough in docs/guides/adding-a-feature.md
pointing at scaffolding-a-feature.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -72,13 +72,16 @@ No other cross-package boundary deviations are permitted.
 
 ## Adding a Feature
 
-Start with `docs/guides/adding-a-feature.md` for a step-by-step walkthrough covering:
+**Fast path — use the generator.** `pnpm turbo gen feature` scaffolds a Lazar-conformant package under `packages/<name>/` (single entity, single `getX` use case) matching the `navigation` reference shape. It emits package files, entities, use case + controller (with input/output schemas + presenter), mock + real repositories (real one is a Phase-1 stub), DI container, both binders (`bind-production` / `bind-dev-seed`), tRPC procedures + router with tests, contract suite, dev seed, and an empty `ui/` barrel — all wired with the span + capture sandwich at bind time.
-- New feature scaffold (folder structure, `package.json`, `tsconfig.json`, `vitest.config.ts`)
+
-- Clean Architecture layers (entities, use cases, repositories, DI container, controllers)
+```bash
-- Payload integration (collections, hooks, Payload repository binding)
+pnpm turbo gen feature                                  # interactive
-- tRPC integration (routers, procedure binding)
+pnpm turbo gen feature --args widgets Widget widgets    # non-interactive: <name> <Entity> <entities-plural>
-- Core wiring (`core-api`, `core-cms`, path aliases, app bootstrap)
+```
-- Testing and lint validation
+
+The generator does NOT wire aggregators or emit Payload CMS templates / faker factories / multi-entity layouts. After running, hand-edit `apps/web-next/src/server/bind-production.ts`, `packages/core-api/src/root.ts`, and the two `package.json` files (the generator prints the exact checklist on success). See `docs/guides/scaffolding-a-feature.md` for the full reference.
+
+**Manual path.** When the generator's Phase-1 scope doesn't fit (multiple entities/use cases, custom layout, extending an existing feature), follow `docs/guides/adding-a-feature.md` — a step-by-step walkthrough covering folder structure, Clean Architecture layers, Payload + tRPC integration, core wiring, and testing / lint validation.
 
 ---
 
@@ -90,6 +93,7 @@ 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 test              # Run all unit + integration tests (Vitest)
 pnpm test:e2e          # Run e2e tests (Playwright across both apps)
 pnpm build             # Build all packages (Turborepo)
@@ -440,7 +444,8 @@ Feature packages MUST NOT `import "@sentry/*"`. Allowlist:
 - **Vertical Feature Spec** — `docs/architecture/vertical-feature-spec.md` — full design, rationale, decision log
 - **Architecture Overview** — `docs/architecture/overview.md` — package responsibilities, data flow
 - **Dependency Flow** — `docs/architecture/dependency-flow.md` — allowed directions and composition pattern
-- **Adding a Feature Guide** — `docs/guides/adding-a-feature.md` — step-by-step new feature walkthrough
+- **Scaffolding a Feature** — `docs/guides/scaffolding-a-feature.md` — `turbo gen feature` reference (fast path)
+- **Adding a Feature Guide** — `docs/guides/adding-a-feature.md` — step-by-step new feature walkthrough (manual path)
 - **Testing Strategy** — `docs/guides/testing-strategy.md` — test placement, Vitest per-package, Playwright e2e
 - **TDD Workflow** — `docs/guides/tdd-workflow.md` — red-green-refactor cycle, mocking decision tree, coverage targets
 

CLAUDE.md

@@ -3,12 +3,13 @@
 ## Quick Start
 
 ```bash
-pnpm install          # Install all dependencies
+pnpm install           # Install all dependencies
-pnpm dev              # Start all dev servers
+pnpm dev               # Start all dev servers
-pnpm build            # Build all packages
+pnpm build             # Build all packages
-pnpm test             # Run all tests
+pnpm test              # Run all tests
-pnpm turbo boundaries # Validate workspace dependency graph
+pnpm turbo boundaries  # Validate workspace dependency graph
-docker compose up -d  # Start PostgreSQL
+pnpm turbo gen feature # Scaffold a new feature package (see docs/guides/scaffolding-a-feature.md)
+docker compose up -d   # Start PostgreSQL
 ```
 
 ## TDD
@@ -31,7 +32,8 @@ Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`,
 - `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
+- `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)
 
 ## Key Conventions
 

docs/guides/adding-a-feature.md

@@ -4,6 +4,15 @@ A feature is a vertical slice: domain entities, use cases, repositories,
 tRPC router, CMS collection, DI container, and query builders — all owned
 by one package under `packages/<feature>/`.
 
+> **Prefer the generator.** `pnpm turbo gen feature` produces a
+> Lazar-conformant single-entity / single-use-case package matching the
+> `navigation` reference shape (DI, tRPC router with tests, span + capture
+> sandwich, dev seed, contract suite). See
+> [Scaffolding a Feature](./scaffolding-a-feature.md). Use this guide when
+> the generator's Phase-1 scope doesn't fit — multi-entity layouts, custom
+> shapes, or extending an existing feature — or when you need to understand
+> what the generator emits and why.
+
 **New feature or extension?** A new capability gets a new package (e.g.,
 `packages/comments`). Adding an operation to an existing feature (e.g.,
 a `publishArticle` procedure to `packages/blog`) means extending that