The `create-zudo-doc` generator CLI scaffolds new zudo-doc projects with various feature combinations. Testing it requires verifying that each combination builds, runs, and produces the correct files and config.

Two Claude Code skills automate this workflow:

| Skill | Purpose |
|-------|---------|
| `/l-generator-cli-tester <pattern>` | Test a single generation pattern |
| `/l-run-generator-cli-whole-test` | Run all 10 patterns, fix bugs, verify everything passes |

## Test Patterns

Each pattern enables a different feature combination:

| Pattern | Description |
|---------|-------------|
| `barebone` | Everything OFF — minimal project |
| `search` | Only search enabled |
| `i18n` | Only i18n enabled |
| `sidebar-filter` | Only sidebar filter enabled |
| `claude-resources` | Only Claude Resources enabled |
| `codex-resources` | Only Codex Resources enabled |
| `design-token-panel` | Only design token panel enabled (uses API) |
| `light-dark` | Light-dark color scheme mode |
| `lang-ja` | Japanese as default language |
| `all-features` | Everything ON |

## Running Tests

### Full test suite

Run all 10 patterns end-to-end, automatically fix any failures, and verify:

```
/l-run-generator-cli-whole-test
```

With headless browser rendering checks:

```
/l-run-generator-cli-whole-test --headless
```

### Single pattern

Test one pattern in isolation:

```
/l-generator-cli-tester barebone
/l-generator-cli-tester all-features --headless
```

## What Each Test Checks

Each pattern goes through these steps:

1. **Scaffold** — Run the generator CLI (or programmatic API) with pattern-specific flags
2. **Install** — `pnpm install` in the generated project
3. **Build** — `pnpm build` to verify static export succeeds
4. **Dev server** — Start `pnpm dev`, wait 8 seconds, verify the process is still running
5. **File verification** — Check expected files are present/absent based on enabled features
6. **Config verification** — Read the generated `zfb.config.ts` and confirm the `zudoDoc({ … })` call holds the expected fields (diff-from-defaults; there is no separate `settings.ts`)
7. **Showcase comparison** — Compare generated code against the main zudo-doc showcase
8. **Headless browser** (with `--headless`) — Render pages in a real browser, check for JS errors, verify visual elements (search icon, language switcher, appearance menu, etc.)

## The Bug-Fix Workflow

The `/l-run-generator-cli-whole-test` skill has a structured bug-fix phase:

1. **Phase 1** — Run all 10 patterns and collect results
2. **Phase 2** — For each failure: diagnose which step failed, read the relevant generator source file, apply a minimal fix, rebuild the CLI and re-test the failing pattern, then commit each fix individually
3. **Phase 3** — Re-run all 10 patterns from scratch to ensure no regressions
4. **Phase 4** — Output a summary report

### Common failure categories

| Failure | Likely cause | Fix location |
|---------|-------------|--------------|
| Missing module at build time | Dependency not in generated `package.json` | `scaffold.ts` — `generatePackageJson()` |
| Wrong/missing field in `zfb.config.ts` | `zudoDoc()` diff-from-defaults emitted incorrectly | `zfb-config-gen.ts` |
| Type error in generated config | Field mismatched against `ZudoDocConfig` | `zfb-config-gen.ts` |
| Feature file missing | Feature module not copying files (only the few features that still ship files) | `features/*.ts` or `templates/features/*/files/` |
| Anchor remnant in output | Injection anchor not cleaned up (`ANCHOR_FILES` is now empty) | `compose.ts` — `cleanAnchors()` |

## Key Generator Files

| File | Role |
|------|------|
| `packages/create-zudo-doc/src/scaffold.ts` | Orchestrates pipeline: copy base, generate config, compose features |
| `packages/create-zudo-doc/src/compose.ts` | Composition engine: injection system, anchor cleanup, feature resolution |
| `packages/create-zudo-doc/src/features/*.ts` | Feature modules — mostly settings-field emission now; only a few still copy files |
| `packages/create-zudo-doc/src/zfb-config-gen.ts` | The **single** config generator — emits `zfb.config.ts` as a `zudoDoc({ … })` diff-from-defaults call (the former `settings-gen.ts` is gone) |
| `packages/create-zudo-doc/src/preset.ts` | Feature-preset resolution shared across CLI and API |
| `packages/create-zudo-doc/src/claude-md-gen.ts` | Generates the project `CLAUDE.md` for the new project shape |
| `packages/create-zudo-doc/src/constants.ts` | Feature definitions, color scheme lists |
| `packages/create-zudo-doc/src/cli.ts` | CLI argument parsing |
| `packages/create-zudo-doc/src/api.ts` | Programmatic API |

## Notes

- Test directories are created under `__inbox/` (gitignored) to avoid polluting the repo
- The `barebone` pattern is the baseline — if it fails, fix it before testing others
- `designTokenPanel` is exposed as the `--design-token-panel` CLI flag, but patterns like `design-token-panel` and `all-features` drive it through the programmatic API for consistency with the other test patterns
- The `--headless` flag adds browser-level rendering checks on top of process-level checks
- Always rebuild the CLI (`pnpm build` in `packages/create-zudo-doc`) before testing and after each fix