@teispace/next-maker 1.15.1 → 1.16.1

package/README.md

@@ -1,151 +1,283 @@
 # @teispace/next-maker
 
-A CLI that scaffolds Next.js 16+ applications (TypeScript, Tailwind v4, Biome, Pino, Zod, Redux Toolkit, next-intl, Vitest) and co-generates feature-based architecture — pages, components, hooks, Redux slices, API services, locales, and tests.
+A CLI that scaffolds Next.js 16+ applications (TypeScript, Tailwind v4, Biome, Pino, Zod, Redux Toolkit, next-intl, Vitest) and co-generates feature-based architecture — pages, layouts, components, hooks, Redux slices, API services, locales, providers, env vars, and tests. Ships a manifest-driven `doctor` and `remove` for ongoing maintenance.
 
 ## Installation
 
 ### Using npx (Recommended)
 
 ```bash
-npx @teispace/next-maker <command> [name] [options]
+npx @teispace/next-maker <command> [args] [options]
 ```
 
 ### Global Installation
 
 ```bash
 npm install -g @teispace/next-maker
-next-maker <command> [name] [options]
+next-maker <command> [args] [options]
 ```
 
-## Commands
+---
+
+## Commands at a glance
+
+| Category | Command | Purpose |
+| --- | --- | --- |
+| Lifecycle | `init [name]` | Create a new Next.js application |
+| Lifecycle | `setup [options]` | Add features to an existing project (retrofit) |
+| Lifecycle | `doctor [options]` | Diagnose drift against known feature manifests |
+| Lifecycle | `remove <feature>` | Reverse a feature install (uses the manifest) |
+| Routing | `page <name>` | Generate a page/route |
+| Routing | `layout <segment>` | Generate a nested layout.tsx |
+| UI | `component <name>` | Shared component with auto-wired barrel exports |
+| State | `feature <name>` | Full feature module (DDD) |
+| State | `slice <name>` | Redux Toolkit slice (auto-registers in rootReducer) |
+| State | `service <name>` | API service (axios/fetch, optional CRUD) |
+| State | `provider <name>` | Context provider with RootProvider auto-wiring |
+| Config | `env <NAME>` | Add an env var (schema + .env.example + .env) |
+| Config | `locale [code]` | Add a new language/locale |
+| Code | `hook <name>` | Custom React hook |
+| Code | `test <file>` | Sibling test stub for a component/hook/slice |
+
+Run `npx @teispace/next-maker <command> --help` for the full option list of any command.
 
-### 1. Create a New App
+---
 
-Generate a complete Next.js application with production-ready configuration.
+## Lifecycle commands
+
+### `init` — Create a New App
 
 ```bash
 npx @teispace/next-maker init [project-name]
 ```
 
-**Interactive Setup:**
+The starter at [`teispace/nextjs-starter`](https://github.com/teispace/nextjs-starter) is cloned via `degit` and trimmed to match your prompt answers. The `cleanup` step strips opted-out features so the generated project compiles end-to-end on first install.
 
-During initialization, you'll be prompted to configure:
+**Interactive prompts:**
 
-- **Package Manager** (npm, yarn, pnpm, bun)
-- **GitHub Repository** (optional - configures remote origin)
-- **HTTP Client** (axios, fetch, both, or none)
-- **Dark Mode** (@teispace/next-themes integration)
-- **Redux Toolkit** (with redux-persist)
-- **Internationalization** (next-intl)
-- **Testing** (Vitest + React Testing Library)
-- **React Compiler** (stable — on by default)
-- **Bundle Analyzer** (@next/bundle-analyzer — off by default)
-- **Community Files** (CODE_OF_CONDUCT, CONTRIBUTING, etc.)
-- **Docker** support
-- **CI/CD** configuration
-- **Pre-commit hooks** (Husky)
+| Section | Prompts |
+| --- | --- |
+| Identity | project name, description, author, version, support email, package manager, GitHub repo / issues / homepage |
+| Architecture | HTTP client (axios / fetch / both / none), dark mode, Redux Toolkit, i18n, testing, React Compiler, Bundle Analyzer |
+| Tooling | community files (CODE_OF_CONDUCT, CONTRIBUTING, SECURITY), README, Docker, CI/CD, pre-commit hooks (Husky/Commitlint/Lint-staged), Commitizen, copy `.env.example` → `.env` |
+| Templates | keep GitHub issue/PR templates? include `react-secure-storage`? |
 
-**Core Features (always shipped):**
+**Always shipped:**
 
 - Next.js 16+ with App Router
 - TypeScript (strict mode)
 - Tailwind CSS v4
-- Biome (single-tool lint + format; replaces ESLint + Prettier)
+- Biome (single-tool lint + format)
 - Pino structured logger with redaction
-- Zod-validated env schema
+- Zod-validated env schema in `src/lib/env/`
 - Feature-based DDD architecture
-- Result-based HTTP clients (axios / fetch)
+- Result-based HTTP clients (when enabled)
+- Hardened security headers in `next.config.ts`
+- `scripts/sync-env.ts` and `scripts/check-deprecated.ts` (used by the `validate` chain)
 
 ---
 
-### 2. Setup Additional Features
+### `setup` — Retrofit a feature
 
-Add features to your existing Next.js project after initialization.
+Add a feature to an existing project (one that wasn't generated by `init`, or one created before a feature existed).
 
 ```bash
 npx @teispace/next-maker setup [options]
 ```
 
-**Options:**
-
-- `--http-client` - Setup HTTP client (Interactive: axios|fetch|both)
-- `--dark-theme` - Setup dark theme support (@teispace/next-themes)
-- `--redux` - Setup Redux Toolkit with persistence
-- `--i18n` - Setup next-intl for internationalization
-- `--tests` - Setup testing (Vitest + React Testing Library)
-- `--react-compiler` - Enable the React Compiler
-- `--bundle-analyzer` - Add @next/bundle-analyzer
+| Flag | What it does |
+| --- | --- |
+| `--http-client` | Adds the axios and/or fetch Result-based clients under `src/lib/utils/http/` |
+| `--dark-theme` | Installs `@teispace/next-themes` and adds `CustomThemeProvider` |
+| `--redux` | Redux Toolkit + `react-redux` + `redux-persist`, `StoreProvider`, `src/store` |
+| `--i18n` | `next-intl` + `[locale]` routing + `proxy.ts` + `RootProvider` wiring |
+| `--tests` | Vitest + React Testing Library + jsdom + `test/test-utils.tsx` |
+| `--react-compiler` | `reactCompiler: true` in `next.config.ts` + `babel-plugin-react-compiler` |
+| `--bundle-analyzer` | Wraps the default export with `withBundleAnalyzer` and adds the `analyze` script |
+| `--security-headers` | Injects the hardened headers block into `next.config.ts` (DNS prefetch, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, X-XSS-Protection) |
+| `--validate-scripts` | Drops in `scripts/sync-env.ts` + `scripts/check-deprecated.ts` and wires `env:sync`, `check:deprecated`, `type-check`, and the `validate` chain (PM-aware) |
+| `--commitizen` | Writes `.czrc`, adds `commit` script, installs `commitizen` + `cz-conventional-changelog` |
 
-**Examples:**
+Run `setup` without flags for an interactive picker.
 
 ```bash
-# Interactive menu
+# Interactive
 npx @teispace/next-maker setup
 
-# Add specific features
-npx @teispace/next-maker setup --http-client
-npx @teispace/next-maker setup --dark-theme
+# Specific feature
 npx @teispace/next-maker setup --redux
-npx @teispace/next-maker setup --i18n
-npx @teispace/next-maker setup --tests
-npx @teispace/next-maker setup --react-compiler
-npx @teispace/next-maker setup --bundle-analyzer
+npx @teispace/next-maker setup --security-headers
+npx @teispace/next-maker setup --validate-scripts
 ```
 
+Every `setup` operation is **idempotent** — re-running is a no-op on already-installed parts and a fix-up on missing parts.
+
 ---
 
-### 3. Generate a Page
+### `doctor` — Drift detection
 
-Create a new page/route with locale-aware boilerplate, SEO metadata, and optional loading/error states.
+`doctor` walks every feature manifest, asks "is this installed?" and (if yes) "are all of its parts present?". Drift is reported per feature.
 
 ```bash
-npx @teispace/next-maker page <name> [options]
+npx @teispace/next-maker doctor [options]
 ```
 
-**Options:**
+| Flag | Behaviour |
+| --- | --- |
+| `--fix` | Re-runs `apply()` for every drifted feature (idempotent — safe to retry) |
+| `--feature <id>` | Only check one manifest (e.g. `redux`, `security-headers`) |
+| `--json` | Machine-readable output for CI |
 
-- `--dynamic <param>` - Create dynamic route (e.g., `--dynamic id` creates `[id]/page.tsx`)
-- `--loading` - Generate `loading.tsx`
-- `--error` - Generate `error.tsx`
+Exit code is `0` on a clean report and `1` when drift is found — `next-maker doctor --json` makes a useful CI gate.
 
-**What it generates:**
+```bash
+# Human report
+npx @teispace/next-maker doctor
 
-- `page.tsx` with full locale support (if i18n is set up), `generateMetadata`, `setRequestLocale`
-- Registers route in `src/lib/config/app-paths.ts`
-- Adds translation namespace to `en.json` (if i18n)
-- Optional `loading.tsx` and `error.tsx`
+# Fix everything that drifted
+npx @teispace/next-maker doctor --fix
+
+# CI
+npx @teispace/next-maker doctor --json > health.json
+```
+
+**Sample output:**
+
+```
+🩺 Project Doctor
+
+  ✓ Security Headers
+  ! Validation Scripts (2 issues)
+      • missing file: scripts/sync-env.ts
+      • missing script: validate
+  — Redux Toolkit (not installed)
+  ✓ Internationalization
+
+1 clean, 1 drifted, 1 not installed
+
+Run with --fix to re-apply drifted features.
+```
+
+Manifests live under `src/manifests/`; each one declares the files, packages, scripts, and code blocks the feature consists of. Adding a manifest for a new feature is a single file — `doctor` and `remove` automatically pick it up.
 
-**Examples:**
+---
+
+### `remove` — Reverse an install
+
+Symmetric to `setup`. Uses the feature manifest to compute the reversal: deletes generated files, strips code blocks (when a `removePattern` is recorded), removes scripts, uninstalls packages.
 
 ```bash
-# Simple page
-npx @teispace/next-maker page about
+npx @teispace/next-maker remove <feature> [options]
+```
 
-# Page with loading and error states
-npx @teispace/next-maker page dashboard --loading --error
+| Flag | Behaviour |
+| --- | --- |
+| `--dry-run` | Print the planned changes without writing |
+| `-y, --yes` | Skip the confirmation prompt |
+
+Anything the manifest can't safely undo (e.g. unwrapping an outer JSX wrap with multiple sibling providers) is reported as `manual cleanup` rather than guessed.
+
+`remove` will **never recursively delete a directory that may hold user-authored content** — `src/app/[locale]/` (your pages), `src/i18n/` (your translations), `src/store/` (your slices), `src/lib/utils/http/` (your service code), and `test/` (your helpers) are flagged in the manifest with `containsUserContent: true` and surface as manual-cleanup with a hint. Move what you want to keep, then `rm -rf` the rest by hand.
+
+```bash
+# Preview the effect
+npx @teispace/next-maker remove redux --dry-run
 
-# Dynamic route (e.g., /products/[id])
+# Apply with confirmation
+npx @teispace/next-maker remove security-headers
+
+# Non-interactive
+npx @teispace/next-maker remove validate-scripts --yes
+```
+
+**Sample plan:**
+
+```
+🗑  Remove Validation Scripts
+
+Planned changes:
+  - delete file: scripts/sync-env.ts
+  - delete file: scripts/check-deprecated.ts
+  - remove script: env:sync
+  - remove script: check:deprecated
+  - remove script: validate
+  - uninstall: tsx
+```
+
+---
+
+## Code generators
+
+### `page` — Generate a page/route
+
+```bash
+npx @teispace/next-maker page <name> [options]
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--dynamic <param>` | Dynamic segment (e.g. `--dynamic id` produces `[id]/page.tsx`) |
+| `--loading` | Generate `loading.tsx` |
+| `--error` | Generate `error.tsx` |
+
+**What it does:**
+
+- Writes `page.tsx` under `src/app/[locale]/<name>/` (i18n) or `src/app/<name>/`
+- When i18n is detected: `generateMetadata`, `setRequestLocale`, `getTranslations`
+- Registers route in `src/lib/config/app-paths.ts`
+- Adds translation namespace to `en.json`
+
+```bash
+npx @teispace/next-maker page about
+npx @teispace/next-maker page dashboard --loading --error
 npx @teispace/next-maker page products --dynamic id --loading --error
 ```
 
 ---
 
-### 4. Generate a Component
+### `layout` — Generate a nested layout
+
+```bash
+npx @teispace/next-maker layout <segment> [options]
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--group` | Wraps the segment in parens for a route group, e.g. `(marketing)` |
+| `--at <path>` | Places the layout under a nested path (kebab-case, slash-separated) |
+| `--no-locale` | Skip the locale wrapper even when i18n is detected |
 
-Create a shared component with automatic barrel export wiring across all index files.
+When i18n is detected the generated layout consumes `params: Promise<{ locale: string }>` and calls `setRequestLocale`. Otherwise it's a plain `({ children }) => <>{children}</>` shell.
 
 ```bash
-npx @teispace/next-maker component <name> [options]
+# /[locale]/dashboard/layout.tsx
+npx @teispace/next-maker layout dashboard
+
+# Route group: /[locale]/(marketing)/layout.tsx
+npx @teispace/next-maker layout marketing --group
+
+# Nested: /[locale]/dashboard/settings/preferences/layout.tsx
+npx @teispace/next-maker layout preferences --at dashboard/settings
 ```
 
-**Options:**
+Refuses to overwrite an existing `layout.tsx` — explicit error rather than silent loss.
+
+---
+
+### `component` — Shared component
+
+```bash
+npx @teispace/next-maker component <name> [options]
+```
 
-- `--client` - Add `'use client'` directive
-- `--i18n` - Add `useTranslations` hook
-- `--feature <path>` - Generate inside a feature directory
-- `--test` / `--no-test` - Co-generate a sibling `*.test.tsx` (default: on when tests are installed)
+| Flag | Effect |
+| --- | --- |
+| `--client` | Adds `'use client'` directive |
+| `--i18n` | Imports `useTranslations` |
+| `--feature <path>` | Generate inside a feature directory |
+| `--test` / `--no-test` | Co-generate a sibling `*.test.tsx` (default: on when Vitest is installed) |
 
-**Generated structure (shared):**
+**Generated structure:**
 
 ```
 src/components/common/MyButton/
@@ -155,347 +287,338 @@ src/components/common/MyButton/
 
 Auto-updates `src/components/common/index.ts` and `src/components/index.ts`.
 
-**Examples:**
-
 ```bash
-# Shared component
 npx @teispace/next-maker component data-table --client
-
-# Component with i18n
 npx @teispace/next-maker component nav-bar --client --i18n
-
-# Feature-specific component
 npx @teispace/next-maker component user-card --client --feature src/features/auth
 ```
 
 ---
 
-### 5. Generate a Feature Module
-
-Create a complete feature module following Domain-Driven Design principles.
+### `feature` — Full feature module
 
 ```bash
 npx @teispace/next-maker feature <name> [options]
 ```
 
-**Options:**
-
-- `--store <type>` - Generate Redux store (persist|no-persist)
-- `--skip-store` - Skip Redux store generation
-- `--service <client>` - Generate API service (axios|fetch)
-- `--skip-service` - Skip API service generation
-- `--path <path>` - Custom path (default: src/features)
+| Flag | Effect |
+| --- | --- |
+| `--store <type>` | Generate Redux store: `persist` or `no-persist` |
+| `--skip-store` | Skip Redux store |
+| `--service <client>` | API service: `axios` or `fetch` |
+| `--skip-service` | Skip API service |
+| `--path <path>` | Custom path (default `src/features`) |
 
 **Generated structure:**
 
 ```
 src/features/user-dashboard/
-├── components/
-│   └── UserDashboard.tsx
-├── hooks/
-│   └── useUserDashboard.ts
-├── types/
-│   └── user-dashboard.types.ts
-├── store/                    (optional)
-│   ├── user-dashboard.slice.ts
-│   ├── user-dashboard.selectors.ts
-│   ├── persist.ts            (optional)
-│   └── index.ts
-├── services/                 (optional)
-│   └── user-dashboard.service.ts
+├── components/UserDashboard.tsx
+├── hooks/useUserDashboard.ts
+├── types/user-dashboard.types.ts
+├── store/                  (optional)
+├── services/               (optional)
 └── index.ts
 ```
 
-**Examples:**
-
 ```bash
-# Full feature with Redux and API service
 npx @teispace/next-maker feature user-profile --store persist --service axios
-
-# Feature with Redux only
 npx @teispace/next-maker feature shopping-cart --store no-persist --skip-service
-
-# Feature in custom location
 npx @teispace/next-maker feature auth --store persist --service fetch --path src/modules
 ```
 
 ---
 
-### 6. Generate a Redux Slice
-
-Create a Redux Toolkit slice with persistence support.
+### `slice` — Redux slice
 
 ```bash
 npx @teispace/next-maker slice <name> [options]
 ```
 
-**Options:**
-
-- `--persist` - Enable redux-persist for this slice
-- `--no-persist` - Disable persistence
-- `--path <path>` - Custom path (default: create new feature)
-- `--test` / `--no-test` - Co-generate a sibling `*.slice.test.ts` (default: on when tests are installed)
+| Flag | Effect |
+| --- | --- |
+| `--persist` / `--no-persist` | Toggle redux-persist for this slice |
+| `--path <path>` | Custom path (default: new feature) |
+| `--test` / `--no-test` | Co-generate `*.slice.test.ts` (default: on when Vitest is installed) |
 
-**Auto-registers in rootReducer** with correct imports.
-
-**Examples:**
+Auto-registers in `rootReducer` with correct imports and persist config.
 
 ```bash
-# Create new feature with slice
 npx @teispace/next-maker slice auth --persist
-
-# Add slice to existing feature
 npx @teispace/next-maker slice user-settings --path features/auth/store
 ```
 
 ---
 
-### 7. Generate an API Service
-
-Create an API service with HTTP client integration. Supports both simple and full CRUD generation.
+### `service` — API service
 
 ```bash
 npx @teispace/next-maker service <name> [options]
 ```
 
-**Options:**
+| Flag | Effect |
+| --- | --- |
+| `--axios` / `--fetch` | Pick the HTTP client |
+| `--crud` | Generate full CRUD (`getAll`, `getById`, `create`, `update`, `delete`) |
+| `--path <path>` | Custom path |
 
-- `--axios` - Use AxiosClient
-- `--fetch` - Use FetchClient
-- `--crud` - Generate full CRUD service (getAll, getById, create, update, delete)
-- `--path <path>` - Custom path (default: create new feature)
+CRUD mode also generates `<Name>Summary` (list view) and `<Name>Detail` (detail view) types, `Create<Name>Dto`, `Update<Name>Dto`, and registers the endpoints in `app-apis.ts`.
 
-**CRUD mode** generates:
+```bash
+npx @teispace/next-maker service payment --axios
+npx @teispace/next-maker service users --fetch --crud
+npx @teispace/next-maker service orders --axios --crud --path features/products/services
+```
 
-- Service with 5 methods: `getAll`, `getById`, `create`, `update`, `delete`
-- `<Name>Summary` type for list responses (cards, tables) and `<Name>Detail` type for single-item responses (detail pages)
-- DTO types: `Create<Name>Dto`, `Update<Name>Dto`
-- Full API config with dynamic routes (`getById(id)`, `update(id)`, `delete(id)`)
+---
 
-**Examples:**
+### `provider` — Context provider
 
 ```bash
-# Simple service
-npx @teispace/next-maker service payment --axios
+npx @teispace/next-maker provider <name>
+```
 
-# Full CRUD service with types and endpoints
-npx @teispace/next-maker service users --fetch --crud
+Generates `src/providers/<Name>Provider.tsx` with:
 
-# CRUD service in existing feature
-npx @teispace/next-maker service orders --axios --crud --path features/products/services
+- `'use client'` directive
+- `createContext` + typed context value
+- `useX()` hook with non-null guard
+- `<XProvider>` component memoising the value with `useMemo`
+
+Then **two-tier auto-wiring**:
+
+1. Locates `RootProvider.tsx` — canonical path first (`src/providers/RootProvider.tsx`), heuristic scan as fallback (looks for the deepest `{children}` chain in `src/providers/*.tsx`).
+2. Wraps `{children}` with `<XProvider>` inside that chain, preserving indentation.
+3. Updates `src/providers/index.ts` barrel (re-exports kept sorted).
+
+If no candidate is found, the generator prints the snippet to wire manually rather than failing silently.
+
+```bash
+npx @teispace/next-maker provider auth        # → AuthProvider, useAuth
+npx @teispace/next-maker provider session     # → SessionProvider, useSession
+npx @teispace/next-maker provider analytics-provider   # already-suffixed names work
 ```
 
+The wrap is **idempotent** — running twice is a no-op.
+
 ---
 
-### 8. Add a Locale
+### `env` — Declare an env var
 
-Add a new language/locale to your internationalized project.
+Adds a new variable across the four files the starter keeps in sync, atomically and idempotently:
+
+1. `src/lib/env/schema.ts` — Zod entry with the right wrapper (`preprocess(emptyStringToUndefined, …)` for non-enum types)
+2. `.env.example` — `KEY=` placeholder with optional description comment and `# -public` marker
+3. `.env` — `KEY=<default>` line when the file exists
 
 ```bash
-npx @teispace/next-maker locale [code] [options]
+npx @teispace/next-maker env <NAME> [options]
 ```
 
-**Options:**
+| Flag | Effect |
+| --- | --- |
+| `--type <type>` | `string` (default), `url`, `number`, `boolean`, `enum` |
+| `--required` | Skips `.optional()` and `.default()` |
+| `--default <value>` | Adds `.default(value)` (mutually exclusive with `--required`) |
+| `--public` | Auto-prefixes `NEXT_PUBLIC_` if missing and tags `.env.example` with `# -public` |
+| `--describe <text>` | Adds `.describe()` and a comment line in `.env.example` |
+| `--enum <list>` | Comma-separated values, required when `--type=enum` |
 
-- `--copy-translations` - Copy English translations instead of empty values
+```bash
+# Optional URL
+npx @teispace/next-maker env SENTRY_DSN --type url --describe "Sentry endpoint"
 
-**What it does:**
+# Public default
+npx @teispace/next-maker env API_URL --type url --public --default "http://localhost:3000"
+
+# Required string (no default, no .optional)
+npx @teispace/next-maker env DATABASE_URL --type url --required
 
-- Creates `src/i18n/translations/<code>.json` (empty or copied from English)
-- Updates `SupportedLocale` type in `src/types/i18n.ts`
-- Adds entry to `src/lib/config/app-locales.ts` with name, flag, country
+# Enum
+npx @teispace/next-maker env LOG_LEVEL --type enum --enum debug,info,warn,error --default info
+
+# Coerced number
+npx @teispace/next-maker env PORT --type number --default 3000
+```
 
-**Examples:**
+The generator quote-escapes defaults and descriptions, mirrors the starter's house style, and is fully covered by tests against the `schema.ts`/`.env.example`/`.env` shapes.
+
+---
+
+### `locale` — Add a locale
 
 ```bash
-# Add Spanish (interactive prompts for name, country, flag)
-npx @teispace/next-maker locale es
+npx @teispace/next-maker locale [code] [options]
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--copy-translations` | Copy English translations as the starting point |
 
-# Add French with English translations as starting point
+Creates `src/i18n/translations/<code>.json`, updates `SupportedLocale`, and adds the entry to `src/lib/config/app-locales.ts` (name, flag, country).
+
+```bash
+npx @teispace/next-maker locale es
 npx @teispace/next-maker locale fr --copy-translations
 ```
 
 ---
 
-### 9. Generate a Hook
-
-Create a custom React hook with loading/error state boilerplate.
+### `hook` — Custom React hook
 
 ```bash
 npx @teispace/next-maker hook <name> [options]
 ```
 
-**Options:**
-
-- `--client` - Add `'use client'` directive (default: true)
-- `--feature <path>` - Generate in feature directory
-- `--test` / `--no-test` - Co-generate a sibling `*.test.ts` (default: on when tests are installed)
-
-**Examples:**
+| Flag | Effect |
+| --- | --- |
+| `--client` | Add `'use client'` directive (default true) |
+| `--feature <path>` | Generate inside a feature directory |
+| `--test` / `--no-test` | Co-generate `*.test.ts` |
 
 ```bash
-# Shared hook in src/hooks/
 npx @teispace/next-maker hook auth-session
-
-# Hook inside a feature
 npx @teispace/next-maker hook user-profile --feature src/features/auth
 ```
 
 ---
 
-### 10. Generate a Test
+### `test` — Retrofit a sibling test
 
-Scaffold a sibling `*.test.{ts,tsx}` next to an existing component, hook, or slice. Handy for retrofitting tests onto code that pre-dates the `--with-test` flag.
+Adds a `*.test.{ts,tsx}` next to existing code that pre-dates the `--test` flag.
 
 ```bash
 npx @teispace/next-maker test <file> [options]
 ```
 
-**Options:**
+| Flag | Effect |
+| --- | --- |
+| `--kind <kind>` | Override inferred kind: `component` / `hook` / `slice` |
+| `--force` | Overwrite an existing test file |
 
-- `--kind <kind>` - Override inferred kind: `component` | `hook` | `slice`
-- `--force` - Overwrite an existing test file
+Inference rules:
 
-**Inference rules:**
-
-- `*.slice.ts` → slice reducer test
-- `use*.ts` / content starts with `export function useX` → hook test (`renderHook`)
+- `*.slice.ts` → reducer test
+- `use*.ts` (or content starting with `export function useX`) → hook test (`renderHook`)
 - `*.tsx` → component test (`renderWithProviders`)
 
-The generated file imports `renderWithProviders` / `TestProviders` from `test/test-utils` using a path resolved relative to the source file, so tests work whether they're under `src/features/*/components/`, `src/hooks/`, or anywhere else in the tree.
-
-**Examples:**
-
 ```bash
 npx @teispace/next-maker test src/features/auth/components/LoginForm.tsx
-npx @teispace/next-maker test src/features/auth/hooks/useLogin.ts
 npx @teispace/next-maker test src/features/auth/store/auth.slice.ts
 npx @teispace/next-maker test src/hooks/use-debounce.ts --kind hook --force
 ```
 
-Requires testing to be installed (`next-maker setup --tests` if not).
+Requires `setup --tests` first.
 
 ---
 
-## Usage Examples
+## End-to-end examples
 
-### Quick Start - New Project
+### Quick start
 
 ```bash
-# Create a new Next.js app with interactive setup
 npx @teispace/next-maker init my-project
 cd my-project
 
-# Generate pages
+# Routes & layouts
 npx @teispace/next-maker page dashboard --loading --error
-npx @teispace/next-maker page settings --loading
+npx @teispace/next-maker layout dashboard
+npx @teispace/next-maker page products --dynamic id --loading --error
 
-# Generate features with CRUD
+# State + data
 npx @teispace/next-maker feature users --store persist --service fetch
 npx @teispace/next-maker service users --fetch --crud --path features/users/services
 
-# Add a locale
+# Providers & env
+npx @teispace/next-maker provider auth
+npx @teispace/next-maker env SENTRY_DSN --type url --describe "Sentry endpoint"
+
+# i18n
 npx @teispace/next-maker locale es
 
-# Start development
+# Health check before commit
+npx @teispace/next-maker doctor
+
 npm run dev
 ```
 
-### Feature-Based Development
+### Feature-driven workflow
 
 ```bash
-# E-commerce example
 npx @teispace/next-maker feature products --store persist --service axios
 npx @teispace/next-maker service products --axios --crud --path features/products/services
 npx @teispace/next-maker page products --dynamic id --loading --error
 npx @teispace/next-maker component product-card --client --feature src/features/products
+npx @teispace/next-maker layout products
 
 npx @teispace/next-maker feature cart --store persist --skip-service
 npx @teispace/next-maker page checkout --loading --error
 ```
 
-### Get Help
+### Maintenance — re-applying drifted features
 
 ```bash
-npx @teispace/next-maker --help
-npx @teispace/next-maker page --help
-npx @teispace/next-maker component --help
-npx @teispace/next-maker locale --help
-```
-
----
-
-## Key Features
-
-### Pages with Full Locale Support
-
-Auto-generates `generateMetadata`, `setRequestLocale`, typed Props, SEO metadata, and translation namespace. Supports dynamic routes with `--dynamic`.
-
-### Shared Components with Auto-Wiring
-
-Creates component in `src/components/common/<Name>/` and auto-updates all barrel exports so you can immediately `import { MyComponent } from '@/components'`.
+# What's drifted?
+npx @teispace/next-maker doctor
 
-### CRUD Service Generation
+# Fix in place
+npx @teispace/next-maker doctor --fix
 
-`--crud` flag generates a complete service with 5 REST methods, separate `Summary` and `Detail` response types (list vs detail views), typed DTOs, and full API config with dynamic route helpers.
-
-### Locale Management
-
-One command adds a new language: translation file, type update, and config entry. No manual file editing.
-
-### Feature-First Architecture
-
-All generators follow a feature-based DDD approach, organizing code by business domain rather than technical layers.
+# Pull a feature out cleanly
+npx @teispace/next-maker remove i18n --dry-run
+npx @teispace/next-maker remove i18n
+```
 
-### Smart Redux Integration
+---
 
-Auto-registers slices in `rootReducer` with correct import paths and optional redux-persist configuration.
+## Architecture
 
-### HTTP Client Support
+### Layers
 
-- **AxiosClient**: Result-based error handling
-- **FetchClient**: Same Result pattern with native fetch
-- Auto-detects available clients
+```
+src/
+├── commands/        # Commander definitions (one file per CLI command)
+├── prompts/         # Enquirer flows (one per command needing interactivity)
+├── generators/      # generate<X>(): writes files for a single artifact
+│   └── templates/   # Pure string-template functions (testable in isolation)
+├── modifiers/       # Pure functions that surgically edit existing files
+├── pipelines/       # PipelineStep[] composers for multi-step generators
+├── services/setup/  # Retrofit installers, one per feature
+├── manifests/       # Declarative feature footprints (drives doctor + remove)
+├── detection/       # "Is feature X installed?" detectors
+├── core/            # File I/O + package-manager helpers (yarn/npm/pnpm/bun)
+└── config/          # PROJECT_PATHS, PACKAGES, spinner, output, error handlers
+```
 
-### Intelligent Path Handling
+### The manifest pattern
 
-All commands support `--path` for custom locations. Relative paths like `features/auth` are resolved to `src/features/auth`.
+Each feature has a manifest in `src/manifests/<feature>.manifest.ts` describing:
 
-### Built-in Validations
+- **detect** — high-level "is this installed?"
+- **files** — paths the feature owns (with `generated: true/false` to control deletion safety)
+- **packages** — runtime/dev dependencies
+- **scripts** — `package.json` script entries (with optional exact-value match)
+- **injections** — code blocks in shared files (with `presence` and optional `removePattern`)
+- **apply** — the existing `setup<X>()` function (for `setup` and `doctor --fix`)
+- **remove** — optional custom remover (defaults to the generic reverser)
 
-- Checks for required dependencies (Redux, HTTP clients, i18n)
-- Prevents duplicate generation
-- Validates naming conventions (kebab-case)
+The manifest registry is consumed by:
 
-### Test Generation
+- `setup` — calls `apply()` directly
+- `doctor` — walks every manifest, reports drift via `checkManifest`
+- `remove` — runs `reverseManifest` (or a custom `remove`) and prints the plan
 
-- `component`, `hook`, and `slice` generators accept `--test` / `--no-test`; the default is **on** when Vitest is installed in the target project (detected via `vitest.config.ts` or the `vitest` dep).
-- Component tests use `renderWithProviders` and forward `messages: {}` / `preloadedState: {}` based on detected i18n / Redux.
-- Hook tests use `renderHook`; wrap with `TestProviders` when a Redux store is detected and the hook lives inside a feature.
-- Slice tests exercise the reducer directly (`setLoading`, `setError`, `resetState`, initial-state invariants) — no providers needed.
-- Standalone `test <file>` retrofits tests onto existing code, inferring kind from filename (`*.slice.ts`, `use*.ts`, `*.tsx`) and source content.
-- Import paths to `test/test-utils` are resolved relative to the source file, so co-generated tests compile no matter how deep in the tree they live.
+Adding a manifest for a new feature is a single file. The CLI commands don't need to know about it.
 
----
+### Modifier conventions
 
-## Command Reference
-
-| Command            | Description                                              |
-| ------------------ | -------------------------------------------------------- |
-| `init [name]`      | Create a new Next.js application                         |
-| `setup`            | Add features to an existing project                      |
-| `page <name>`      | Generate a new page/route                                |
-| `component <name>` | Generate a shared component (optional sibling test)      |
-| `feature <name>`   | Generate a feature module                                |
-| `slice <name>`     | Generate a Redux slice (optional sibling test)           |
-| `service <name>`   | Generate an API service                                  |
-| `locale [code]`    | Add a new locale/language                                |
-| `hook <name>`      | Generate a custom React hook (optional sibling test)     |
-| `test <file>`      | Generate a sibling test for a component/hook/slice       |
+- **Pure transformation modules** (e.g. `headers.ts`, `package-modifier.ts`, `env-var.modifier.ts`) take strings or JSON and return strings or JSON. No filesystem.
+- **Thin async wrappers** (`index.ts` per setup service, the modifier orchestrators) handle I/O and spinners.
+- **Idempotency** is required: re-running anything is a no-op when the target state is already reached. This is what makes `doctor --fix` safe.
 
 ---
 
-## Project Structure
+## Project structure (generated app)
 
 The full shape of a scaffolded app (branches marked `(opt)` are stripped when the matching prompt is declined during `init`):
 
@@ -526,11 +649,11 @@ my-project/
 │   │   ├── common/                    # Shared UI (auto-wired barrel exports)
 │   │   └── index.ts
 │   ├── providers/
-│   │   ├── RootProvider.tsx           # Composes Store → Theme → Intl
+│   │   ├── RootProvider.tsx           # Composes Store → Theme → Intl → custom
 │   │   ├── StoreProvider.tsx          # (opt, redux) useRef + PersistGate
 │   │   ├── CustomThemeProvider.tsx    # (opt, dark-mode) @teispace/next-themes
-│   │   └── index.ts
-│   ├── store/                         # (opt, redux) makeStore, rootReducer, typed hooks, SSR-safe storage
+│   │   └── index.ts                   # Barrel — `next-maker provider <name>` keeps it sorted
+│   ├── store/                         # (opt, redux) makeStore, rootReducer, typed hooks
 │   ├── services/
 │   │   ├── api/                       # API service barrel
 │   │   └── storage/                   # react-secure-storage wrapper
@@ -558,11 +681,12 @@ my-project/
 │   └── check-deprecated.ts            # fails build if @deprecated APIs are referenced
 ├── public/
 ├── biome.json                         # single-tool lint + format
-├── next.config.ts                     # headers, reactCompiler (opt), bundleAnalyzer (opt), withNextIntl (opt, i18n)
+├── next.config.ts                     # security headers, reactCompiler (opt), bundleAnalyzer (opt), withNextIntl (opt, i18n)
 ├── vitest.config.ts                   # (opt, tests)
 ├── postcss.config.mjs                 # @tailwindcss/postcss
 ├── tsconfig.json
 ├── .env.example
+├── .czrc                              # (opt, commitizen)
 ├── .husky/                            # (opt, pre-commit hooks)
 ├── .lintstagedrc.mjs                  # (opt, pre-commit hooks) runs `biome check --write`
 ├── commitlint.config.mjs              # (opt, pre-commit hooks)
@@ -573,19 +697,15 @@ my-project/
 └── package.json
 ```
 
-Features that have first-class opt-out prompts during `init`: `httpClient`, `darkMode`, `redux`, `i18n`, `tests`, `reactCompiler`, `bundleAnalyzer`, `docker`, `ci`, `preCommitHooks`, `commitizen`, `communityFiles`, `readme`. Each has a matching `setup --<feature>` command to re-add it later.
+Features that have first-class opt-out prompts during `init`: `httpClient`, `darkMode`, `redux`, `i18n`, `tests`, `reactCompiler`, `bundleAnalyzer`, `docker`, `ci`, `preCommitHooks`, `commitizen`, `communityFiles`, `readme`, `copyEnv`. Each opt-out has a matching `setup --<feature>` to re-add later. `doctor` and `remove` cover the whole installed footprint via manifests.
 
 ---
 
 ## Tech Stack
 
-**CLI:**
-
-- TypeScript, esbuild, Commander.js, Enquirer, Vitest
-
-**Generated Apps:**
+**CLI:** TypeScript, esbuild, Commander.js, Enquirer, Vitest, degit.
 
-- Next.js 16+, TypeScript, Tailwind CSS v4, Biome, Pino, Zod, Redux Toolkit, @teispace/next-themes, next-intl, Axios, Vitest + RTL, React Compiler
+**Generated apps:** Next.js 16+, TypeScript, Tailwind CSS v4, Biome, Pino, Zod, Redux Toolkit, `@teispace/next-themes`, next-intl, Axios, Vitest + RTL, React Compiler.
 
 ---
 
@@ -596,37 +716,56 @@ Features that have first-class opt-out prompts during `init`: `httpClient`, `dar
 ```bash
 git clone <repository-url>
 cd npm-packages/packages/next-maker
-npm install
+yarn install
 ```
 
 ### Build
 
 ```bash
-npm run build
+yarn build      # esbuild bundle + tsc --emitDeclarationOnly
 ```
 
 ### Test
 
 ```bash
-npm test
-npm run test:watch
+yarn test           # one-shot
+yarn test:watch
 ```
 
-### Test Locally
+The test suite covers every modifier, generator template, and manifest runner with deterministic string/JSON inputs. Generators that touch the filesystem are tested against `os.tmpdir()` directories.
+
+### Smoke-test the built CLI
 
 ```bash
 node dist/index.js init test-project
 cd test-project
+
+# Generators
 node ../dist/index.js page dashboard --loading --error
-node ../dist/index.js component sidebar --client          # co-generates Sidebar.test.tsx if tests installed
-node ../dist/index.js hook debounce                       # co-generates useDebounce.test.ts
-node ../dist/index.js slice filters --persist             # co-generates filters.slice.test.ts
-node ../dist/index.js feature auth --store persist --service axios
+node ../dist/index.js layout dashboard
+node ../dist/index.js component sidebar --client
+node ../dist/index.js hook debounce
+node ../dist/index.js provider auth
+node ../dist/index.js slice filters --persist
+node ../dist/index.js feature users --store persist --service axios
 node ../dist/index.js service users --fetch --crud
-node ../dist/index.js test src/hooks/useDebounce.ts --force   # retrofit sibling test
+node ../dist/index.js env SENTRY_DSN --type url --describe "Sentry"
 node ../dist/index.js locale es
+node ../dist/index.js test src/hooks/useDebounce.ts --force
+
+# Maintenance
+node ../dist/index.js doctor
+node ../dist/index.js remove redux --dry-run
 ```
 
+### Adding a new feature manifest
+
+1. Drop a file under `src/manifests/<feature>.manifest.ts` exporting a `FeatureManifest`.
+2. Append it to the `MANIFESTS` array in `src/manifests/index.ts`.
+3. (Optional) Add a `setup --<feature>` flag if you want a flag-based retrofit.
+
+`doctor` and `remove` will pick it up automatically.
+
 ---
 
 ## License
@@ -637,11 +776,11 @@ MIT
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome. Please open a PR.
 
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request