docs(04-01): complete CLI scaffolding plan

Tasks completed: 3/3
- Prove and create the compiling Winter-shaped plugin path
- Generate model, migration, and command slices
- Generate jobs and admin controllers, then enforce model imports

SUMMARY: .planning/phases/04-cli-scaffolding-i18n-and-mail/04-01-SUMMARY.md
Co-authored-by: Cursor <cursoragent@cursor.com>

.planning/phases/04-cli-scaffolding-i18n-and-mail/04-01-SUMMARY.md

@@ -0,0 +1,147 @@
+---
+phase: 04-cli-scaffolding-i18n-and-mail
+plan: 01
+subsystem: cli
+tags: [scaffold, make, registry, gormigrate, bonfire, pact, wintercms]
+
+requires:
+  - phase: 01-framework-kernel-foundation
+    provides: make:plugin, plugin:add, summer build, party.Plugin, pact capabilities
+provides:
+  - six make commands that emit compiling Winter-shaped plugin artifacts
+  - generated per-plugin registry.gen.go accessors
+  - models-leaf sibling-import check in summer build
+  - pact Job, AdminController, HasLang, and HasMailTemplates contracts
+affects: [04-02-i18n, 04-03-mail, 04-04-tests, plugin-porting]
+
+tech-stack:
+  added: []
+  patterns:
+    - embedded text/template stubs under internal/build/stubs
+    - atomic registry.gen.go refresh from generated leaf constructors
+    - models/ is a leaf package enforced at build time
+
+key-files:
+  created:
+    - internal/build/registry.go
+    - internal/build/leaf.go
+    - internal/build/artifact.go
+    - internal/build/stubs/plugin.tmpl
+    - internal/build/stubs/registry.tmpl
+    - internal/build/stubs/artifacts.tmpl
+  modified:
+    - internal/build/scaffold.go
+    - internal/build/build.go
+    - internal/build/build_test.go
+    - cmd/summer/main.go
+    - cmd/summer/main_test.go
+    - pact/capabilities.go
+    - bonfire/command.go
+    - bonfire/root.go
+
+key-decisions:
+  - "registry.gen.go is regenerated by scanning Code generated by summer make files, not by rewriting plugin.go"
+  - "make:model table names are vendor_plugin_plural_snake with explicit gormigrate CREATE/DROP TABLE"
+  - "models sibling-import check runs in build.App before go build and reports plugin ID, file, and import"
+
+patterns-established:
+  - "Generated plugin.go calls generatedModels/Migrations/Commands/Jobs/AdminControllers; handwritten plugins get a one-time accessor hint"
+  - "Stub sources render from named embedded templates and pass go/format before write"
+
+requirements-completed: [CLI-02]
+
+duration: 11 min
+completed: 2026-09-18
+---
+
+# Phase 4 Plan 01: CLI scaffolding Summary
+
+**Six `summer make:*` commands emit Winter-shaped, vet-clean plugin artifacts wired through `registry.gen.go`, and `summer build` rejects `models/` sibling imports by plugin ID, file, and path**
+
+## Performance
+
+- **Duration:** 11 min
+- **Started:** 2026-09-18T11:29:54Z
+- **Completed:** 2026-09-18T11:41:29Z
+- **Tasks:** 3
+- **Files modified:** 14
+
+## Accomplishments
+- `make:plugin` now scaffolds the Winter directory shape: root `plugin.go`/`routes.go`, leaf `doc.go` packages, embeddable `config/`, `lang/en/`, and `views/mail/` assets, plus empty `registry.gen.go` accessors
+- `make:model`, `make:migration`, `make:command`, `make:job`, and `make:admin-controller` write compiling stubs, infer plugin ID from `plugin.go`, refuse duplicates, and refresh sorted registry slices without touching handwritten `plugin.go`
+- `summer build` inspects each manifest plugin's `models/` imports before `go build` and fails when a sibling package is imported
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Prove and create the compiling Winter-shaped plugin path** - `1edf9d7` (feat)
+2. **Task 2: Generate model, migration, and command slices** - `d8c5650` (feat)
+3. **Task 3: Generate jobs and admin controllers, then enforce model imports** - `c87bbc3` (feat)
+
+**Plan metadata:** (this commit)
+
+## Files Created/Modified
+- `pact/capabilities.go` - Job, AdminController, HasLang, HasMailTemplates contracts
+- `internal/build/stubs/plugin.tmpl` - named templates for plugin.go, routes.go, leaf doc.go, go.mod
+- `internal/build/stubs/registry.tmpl` - generated registry accessors
+- `internal/build/stubs/artifacts.tmpl` - model, migration, command, job, admin controller, YAML templates
+- `internal/build/scaffold.go` - template-driven MakePlugin Winter layout
+- `internal/build/registry.go` - deterministic atomic registry.gen.go generation and scan
+- `internal/build/artifact.go` - MakeModel/Migration/Command/Job/AdminController
+- `internal/build/leaf.go` - models sibling-import enforcement
+- `internal/build/build.go` - runs the leaf check before go build
+- `cmd/summer/main.go` - five new make commands plus --no-migration
+- `bonfire/command.go`, `bonfire/root.go` - Bare flags so --no-migration needs no value
+- `internal/build/build_test.go` - smoke, core artifacts, all-six, and leaf rejection tests
+
+## Decisions Made
+- Registry ownership stays in generated files marked `Code generated by summer make`; handwritten `plugin.go` is never rewritten and existing plugins receive an accessor hint
+- Model tables are `{vendor}_{plugin}_{plural_snake}` with timestamps and an explicit gormigrate create/drop migration; `--no-migration` omits only that file
+- Job stubs implement `pact.JobArgs.Kind` and `pact.Job.Work` with an unexpected-type error and no River import
+- Admin stubs implement ID/ModelName/ConfigDir and write `controllers/<name>/fields.yaml` plus `columns.yaml`
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Bare flag support for --no-migration**
+- **Found during:** Task 2 (make:model --no-migration)
+- **Issue:** bonfire only registered cobra string flags, so `--no-migration` required a value and could not match D-13
+- **Fix:** Added `Flag.Bare` and cobra `NoOptDefVal=true` so `--no-migration` is a valueless true flag
+- **Files modified:** `bonfire/command.go`, `bonfire/root.go`, `cmd/summer/main.go`
+- **Verification:** `TestScaffoldCoreArtifacts` omits only the model migration; `go test ./bonfire` still green
+- **Committed in:** `d8c5650` (Task 2 commit)
+
+**2. [Rule 2 - Missing Critical] Artifact helpers live in artifact.go**
+- **Found during:** Task 2
+- **Issue:** Plan listed Make* work on `scaffold.go`; adding five generators there would bury path validation and registry refresh
+- **Fix:** Keep MakePlugin in `scaffold.go` and put make:model/migration/command/job/admin-controller in `internal/build/artifact.go`
+- **Files modified:** `internal/build/artifact.go`
+- **Verification:** All make tests pass through the exported Make* APIs used by cmd/summer
+- **Committed in:** `d8c5650` / `c87bbc3`
+
+---
+
+**Total deviations:** 2 auto-fixed (1 blocking, 1 missing critical)
+**Impact on plan:** No behavior divergence from D-10–D-17. Bare flags were required for the documented `--no-migration` UX.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+Ready for 04-02 (phrasebook / i18n). Generated plugins already implement `pact.HasLang` and `pact.HasMailTemplates` with embeddable assets. Unit-test coverage remains the last plan (04-04).
+
+## Verification
+
+- `go test ./internal/build ./cmd/summer -run 'TestScaffoldPluginSmoke|TestScaffoldCoreArtifacts|TestScaffoldAllArtifacts|TestModelsLeaf|TestToolCommandNames' -short -count=1` — PASS
+- `go vet ./... && go test ./...` — PASS
+
+## Self-Check: PASSED
+
+---
+*Phase: 04-cli-scaffolding-i18n-and-mail*
+*Completed: 2026-09-18*