docs(11.1-05): log the scaffolder gaps found while porting the walkthrough

- same-second migrations sort by name and can run out of order
- make:admin-controller output does not boot and names the model after
  the controller
- the DO NOT EDIT header on editable files, and commands that cannot reach
  the application

.planning/todos/pending/scaffold-generated-header-and-command-deps.md

@@ -0,0 +1,15 @@
+---
+title: Scaffolded files carry a DO NOT EDIT header, and make:command cannot reach the application
+date: 2026-09-30
+priority: medium
+area: summercms.go internal/build
+---
+
+Two scaffolder conventions that the porting walkthrough had to work around:
+
+1. **The generated-code header on files the developer edits.** Every file a `make:` command writes starts with `// Code generated by summer make. DO NOT EDIT.`, although models, migrations, commands and admin controllers are meant to be edited. `refreshRegistry` (`internal/build/registry.go`, `isGeneratedFile`) only lists files that carry that marker, so a developer who removes the misleading header silently drops the artifact from `registry.gen.go` on the next `make:` run. Linters such as golangci-lint also skip files with that header, so the edited code is never linted.
+2. **make:command's function takes no arguments.** The registry scanner accepts only exported, zero-parameter functions returning `bonfire.Command`, so a generated command cannot reach the database, the config or any published service. A command that needs them must take a parameter, which removes it from the generated accessor, and be returned from `Commands` by hand (the walkthrough's `blog:publish` does this with the plugin's `withDB`).
+
+Found while writing `docs/setup/porting-a-plugin.md` (Phase 11.1 plan 05). The page describes both as they are.
+
+Suggested fix: use a marker that does not claim the file is generated (for example a `//summer:make <kind>` directive) for editable artifacts, keep the `Code generated ... DO NOT EDIT.` header for `registry.gen.go` only, and accept the old header during a transition. For commands, let the scanner also accept `func(*backpack.App) bonfire.Command` and have `generatedCommands` take the app that `Commands` receives from the plugin (which keeps it from `Boot`). Update `docs/console/scaffolding.md`, `docs/console/writing-commands.md` and the porting page in the same change. `internal/build` is outside the docs phase boundary, so it is not changed in Phase 11.1.