docs(14.3): insert phase for summer new and summercms.io/new bootstrap, capture context

.planning/ROADMAP.md

@@ -884,6 +884,26 @@ Plans:
 - Nested locale writes are not dropped on the admin form path and on relation-child saves
 - The SPA lists every enabled locale, switches all ML controls together, and sends `Record<string,string>`
 
+### Phase 14.3: One-command app scaffolding: summer new and summercms.io/new bootstrap script (INSERTED)
+
+**Goal:** Starting a SummerCMS app takes one command. `summer new <name>` writes a ready-to-run `sm-<name>-app` next to the framework checkout, and `curl -fsSL https://summercms.io/new | bash -s -- <name>` checks the prerequisites, fetches the framework, installs the `summer` CLI and runs it. Ships as framework tag `v0.1.13`.
+**Requirements**: TBD
+**Depends on:** Phase 14.2.1
+**Repos:** `summercms.go` (generator, bootstrap script, docs); `sm-summercmsio-app` / `sm-summercmsio-plugin` (serve `/new` as `text/plain`)
+**Success Criteria** (what must be TRUE):
+
+  1. `summer new <name>` validates the name (lower-case letters and digits, starting with a letter), refuses an existing directory, and writes `go.mod` (module `git.golem15.com/golem15/sm-<name>-app`, go 1.27.0, relative `replace` to the framework found via `--framework`, then sibling detection by module path, else a clear error), `summer.yaml`, a starter plugin `golem15.<name>` through the `make:plugin`/`plugin:add` code paths with `go.work` (optional via `--no-plugin` if an empty plugin list builds), `config/` complete for `serve` and `route:list` (incl. `http.yaml` `body_limits`, app key, storage bucket defaults), `.env.example` and `.env` with a fresh app key, `.gitignore`, `compose.yaml` (PostgreSQL 16 matching `.env`), `CLAUDE.md`/`AGENTS.md`, and a first git commit (skippable with `--no-git`).
+  2. The generated app works with no edits: `summer build`, `summer migrate` and `summer serve` succeed and a starter-plugin route answers over HTTP.
+  3. The bootstrap script (wrapped in `main()`) checks Go 1.27+ and Docker, clones or fast-forwards the framework, runs `go install ./cmd/summer` with a PATH hint, runs `summer new`, and prints next steps; summercms.io serves it at `/new` as `text/plain`.
+  4. In a clean `node:24-bookworm`-style container with Go 1.27, Docker, git and jq, `curl … | bash -s -- demo` → `cd sm-demo-app && docker compose up -d && summer build && summer migrate && summer serve` ends with the starter route answering.
+  5. `docs/setup/installation.md` leads with the one-liner, `go-modules-and-workspaces.md` and the console docs cover `summer new`, and `llms.txt`/`llms-full.txt` include the changes; docs checks pass.
+  6. Generator Go tests (golden output plus a real build of the scaffold in a temp dir) are the last plan.
+
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd-plan-phase 14.3 to break down)
+
 ### Phase 15: Journal plugin
 
 **Goal:** The Golem15 Journal plugin is ported to Go as `sm-journal-plugin` and mounts in a host application the same way `sm-user-plugin` does, so a blog can run on SummerCMS without the PHP plugin.
@@ -1035,7 +1055,7 @@ Plans:
 ## Progress
 
 **Execution Order:**
-Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 14.1 → 14.2 → 15 → 16 → 17 → 18 → 19 → 19.1 → 20
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 14.1 → 14.2 → 14.2.1 → 14.3 → 15 → 16 → 17 → 18 → 19 → 19.1 → 20
 (Phase 2 depends on Phase 1's command kernel; the two are no longer parallel.)
 
 | Phase | Plans Complete | Status | Completed |
@@ -1058,6 +1078,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 14. Domain jobs and external integrations | 6/6 | In Progress|  |
 | 14.1. OAuth identities and fonoteka me routes (INSERTED) | 2/2 | Complete    | 2026-10-05 |
 | 14.2. Local Fonoteka frontend on local SummerCMS backend (INSERTED) | 0/TBD | Not started | - |
+| 14.3. One-command app scaffolding (INSERTED) | 0/4 | Not started | - |
 | 15. Journal plugin | 4/4 | Complete   | 2026-10-06 |
 | 16. grzybyfunkcjonalne.pl on reusable blog views | 0/TBD | Not started | - |
 | 17. Blog companions | 0/TBD | Not started | - |

.planning/STATE.md

@@ -5,12 +5,12 @@ current_phase: "14.2"
 current_phase_name: local-fonoteka-frontend-on-local-summercms-backend
 status: executing
 stopped_at: Phase 14.2 context gathered
-last_updated: "2026-10-07T19:26:02.841Z"
+last_updated: "2026-10-07T22:23:37.716Z"
 last_activity: 2026-10-07
 last_activity_desc: Completed quick task 261006-s0v (remove ML copy-from locale UI)
-state_head: 05349d4b6d9402a8dbee72e5aa9700fa641a6372
+state_head: 498f4b4f3af1a7057e96f81ccf714a4b3c79f428
 progress:
-  total_phases: 30
+  total_phases: 31
   completed_phases: 13
   total_plans: 139
   completed_plans: 135
@@ -210,6 +210,7 @@ Progress: [██████████] 100%
 - Phase 16 added: grzybyfunkcjonalne.pl on reusable blog views
 - Phase 20 edited: Płytarium production cutover moved here from Phase 15
 - Phase 14.2.1 inserted after Phase 14.2: sm-translate-plugin so Journal can keep translatable fields (URGENT)
+- Phase 14.3 inserted after Phase 14.2.1: One-command app scaffolding: summer new + summercms.io/new bootstrap script; ships as v0.1.13 (URGENT)
 
 ### Decisions
 

.planning/phases/14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new/14.3-CONTEXT.md

@@ -0,0 +1,103 @@
+# Phase 14.3: One-command app scaffolding - Context
+
+**Gathered:** 2026-10-08
+**Status:** Ready for planning
+**Source:** User task spec (pasted 2026-10-08) plus planning-checkpoint answers
+
+<domain>
+## Phase Boundary
+
+Starting a new SummerCMS app takes one command. Today it means hand-writing `go.mod` (with a `replace` to the framework checkout), `summer.yaml` and `config/`, following `docs/architecture/go-modules-and-workspaces.md`. A teammate is about to start a new app (built with MSD); this phase removes that friction.
+
+Deliverables:
+1. `summer new <name>` in `cmd/summer` + `internal/build`: writes a ready-to-run `sm-<name>-app/` in the current directory.
+2. A bootstrap script, `curl -fsSL https://summercms.io/new | bash -s -- <name>`, versioned in the framework repo and served by summercms.io.
+3. Docs: installation, go modules and workspaces, console docs, `llms.txt`/`llms-full.txt`, and the summercms.io landing page "Get started".
+4. Go tests for the generator (golden output plus a real build of the scaffold in a temp dir), as the last plan.
+
+Ships as framework tag **`v0.1.13`** (latest existing tag is `v0.1.12`).
+
+Out of scope: `sm-<name>-theme` (Nuxt/Vue frontend) scaffolding — but nothing designed here may block adding it later (e.g. `summer new` must not claim the `theme` naming or assume an app has no frontend directory). Standalone `sm-<name>-plugin` scaffolding beyond what `make:plugin` already does. Windows support for the bootstrap script.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Naming (Golem15 convention)
+- **D-01:** `sm-<name>-app` is an application (this phase), `sm-<name>-plugin` a standalone plugin module, `sm-<name>-theme` a Nuxt/Vue frontend (later). The generated `CLAUDE.md` states this convention.
+- **D-02:** `<name>` is validated as lower-case letters and digits, starting with a letter (`^[a-z][a-z0-9]*$`); it also becomes the second part of the starter plugin ID `golem15.<name>`. `summer new` refuses to overwrite an existing `sm-<name>-app/` directory (exists at all → error, no merge). — **Reversibility:** costly — the name rule is a public CLI contract.
+
+### `summer new` output
+- **D-03:** `go.mod`: module `git.golem15.com/golem15/sm-<name>-app`, `go 1.27.0`, requiring `git.golem15.com/golem15/summercms` with a `replace` to the local framework checkout, written as a **relative** path. — **Reversibility:** reversible.
+- **D-04:** Framework checkout resolution order: (1) `--framework <path>` flag; (2) auto-detection of sibling directories of the target parent (at least `../summercms` and `../summercms.go`) whose `go.mod` declares module `git.golem15.com/golem15/summercms` — detection is by module path, not folder name, because the local checkout is `summercms.go` while the bootstrap clones `summercms`; (3) otherwise a clear error naming `--framework`. Research may add the running binary's own source location as a further candidate if cheap and reliable.
+- **D-05:** `summer.yaml` plus one starter plugin `golem15.<name>` created through the **same code paths** as `make:plugin` and `plugin:add` (no duplicated templates), so `go.work` is created too. The starter plugin exposes at least one HTTP route so acceptance can hit it.
+- **D-06:** Research must check whether an empty `plugins: []` builds. If it does, add `--no-plugin`; if it does not, either fix that in the build pipeline (preferred if small) or drop `--no-plugin` and record why.
+- **D-07:** `config/` contains everything `serve` and `route:list` need, including `http.yaml` with `body_limits` (the known gap in `examples/hello`), app key handling, and storage bucket defaults (uploads bucket). Fix the `examples/hello` gap too if it is the same config.
+- **D-08:** `.env.example` lists the `SUMMER_*` variables (DSN, `APP__KEY`, uploads bucket). `.env` is generated with a fresh app key by reusing the `key:generate` logic in `modules/lagoon/keygen.go` (export or move a helper; do not copy it). `.gitignore` covers `bin/`, `.env`, and generated files that should not be committed (research decides which: e.g. `plugins.gen.go`? `storage/`?).
+- **D-09:** `compose.yaml` runs PostgreSQL 16 with credentials matching `.env`'s DSN.
+- **D-10:** `CLAUDE.md` for AI agents, also usable as `AGENTS.md` (symlink or identical copy — planner's call, but it must survive `git clone` on Linux/macOS). It says: this is a SummerCMS app; do not edit the framework; docs at https://summercms.io/docs/llms.txt and https://summercms.io/docs/llms-full.txt; core commands `make:plugin`, `plugin:add`, `build`, `dev`, `migrate`, `serve`; the naming convention (D-01). Neutral of any consuming application (framework README rule applies to the template text).
+- **D-11:** `git init` and a first commit, skippable with `--no-git`. The commit must not fail when the user has no git identity configured (set a fallback author for that commit only, or skip with a warning — planner's call).
+- **D-12:** The generated app works with **no edits**: `summer build`, `summer migrate` and `summer serve` succeed once `docker compose up -d` is running.
+
+### Bootstrap script
+- **D-13:** Script lives in `summercms.go` (e.g. `scripts/new.sh`) and is embedded in an exported framework package so it is versioned with the framework tag. `sm-summercmsio-plugin` serves it at `GET /new` as `text/plain; charset=utf-8`. No nginx change (nginx already allows GET/HEAD and proxies everything except `/backend`). No Cloudflare Worker. msd-core's `scripts/bootstrap.sh` is a pattern reference only. — **Reversibility:** reversible.
+- **D-14:** The whole script is wrapped in `main()` invoked on the last line, so a truncated download runs nothing.
+- **D-15:** Steps: (1) check Go ≥ 1.27 (clear install hint if missing/old) and Docker (warn only if missing); (2) clone the framework or update an existing clone, fast-forward only; (3) `go install ./cmd/summer`, then print a PATH hint if `$(go env GOPATH)/bin` (or `GOBIN`) is not on `PATH`; (4) run `summer new <name>` next to the framework (sibling directory, so D-04 auto-detection finds it); (5) print next steps: `docker compose up -d`, `summer build`, `summer migrate`, `summer serve`.
+- **D-16:** The script checks out the **latest release tag** (`vX.Y.Z`) of `git.golem15.com/golem15/summercms`, not `master`. Re-runs fetch tags and move forward to the newest tag (never a non-fast-forward). Research settles how this interacts with an existing clone that has local changes or sits on a branch (refuse with a clear message, do not reset).
+- **D-17:** Where the framework is cloned (the script's working directory, e.g. `./summercms`) and any env overrides (clone URL/dir, e.g. for tests) are planner's call; the clone URL defaults to the public HTTPS remote.
+
+### Docs and site
+- **D-18:** Rewrite `docs/setup/installation.md`: the one-liner first, the manual `examples/hello` walkthrough second. Update `docs/architecture/go-modules-and-workspaces.md` to cover `summer new`. Add `summer new` to the console docs. `llms.txt`/`llms-full.txt` pick up the changes (regenerate; `summer docs:build --check` and `TestDocsTree` stay green). Module READMEs for any package whose exported API changes (e.g. `lagoon` if the keygen helper is exported) update in the same change.
+- **D-19:** The summercms.io landing page "Get started" switches to the one-liner in this phase (`vue-summercmsio-app`), and `TestTerminalCommands` in `sm-summercmsio-app` is updated to match. The site is redeployed after `v0.1.13` is tagged (deploy itself is a user action per `sm-summercmsio-app/DEPLOY.md`).
+
+### Acceptance
+- **D-20:** In a clean `node:24-bookworm`-style container with Go 1.27, Docker access, git and jq, starting from nothing: `curl … | bash -s -- demo` → `cd sm-demo-app && docker compose up -d && summer build && summer migrate && summer serve`, then a starter-plugin route answers over HTTP. Before the site is deployed, the run may fetch the script from a local server or the repo file, and clone from a local path/tag via the D-17 overrides; the final run against https://summercms.io/new happens after deploy.
+- **D-21:** Generator Go tests follow the repo's existing test conventions (stdlib `testing`, golden files under `testdata/`, `-short` gating for slow paths such as the real build). Unit tests are the last plan.
+
+### Claude's Discretion
+- Exact package layout inside `internal/build` (e.g. `new.go` + templates under `internal/build/stubs/new/`), flag names beyond those listed, and template engine (`text/template` like existing stubs).
+- Whether `summer new` also runs `summer build` at the end (default: no — the next-steps text covers it).
+- Default DB name/user/password and host port in `compose.yaml`/`.env` (avoid clashing with a host Postgres on 5432 if cheap, e.g. a non-default host port).
+- Security review: the bootstrap script is piped into a shell and served publicly — run the security-review agent for plan 2.
+
+</decisions>
+
+<plans>
+## Agreed Plan Split (checkpoint confirmed 2026-10-08)
+
+1. **Generator** — `summer new` in `cmd/summer` + `internal/build` (D-02..D-12), with a smoke test. Repo: `summercms.go`.
+2. **Bootstrap script + `/new` route + acceptance** — `scripts/new.sh` embedded and exported (D-13..D-17), `GET /new` in `sm-summercmsio-plugin`, container acceptance run (D-20). Repos: `summercms.go`, `sm-summercmsio-app` (plugin submodule).
+3. **Docs and landing page** — D-18, D-19. Repos: `summercms.go`, `sm-summercmsio-app` / `vue-summercmsio-app`.
+4. **Unit tests** — golden output + real build in a temp dir (D-21). Repo: `summercms.go`.
+
+</plans>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+- `cmd/summer/main.go` — existing commands: `build`, `make:plugin`, `dev`, `plugin:add`, delegated `migrate`/`serve`.
+- `internal/build/` — `scaffold.go`, `build.go`, `manifest.go`, `registry.go`, `stubs/` (existing templates and code paths to reuse).
+- `modules/lagoon/keygen.go` — `key:generate` logic to reuse for `.env`.
+- `examples/hello/` — minimal app (`go.mod`, `summer.yaml`, `config/`), including the missing `http.yaml` `body_limits`.
+- `docs/setup/installation.md`, `docs/architecture/go-modules-and-workspaces.md`, `docs/console/` — docs to update; `cmd/summer/docs.go` — docs build / llms output.
+- `../sm-bm-app/`, `../sm-summercmsio-app/` — real hand-built apps: `go.mod` with relative replace, `config/*.yaml` (`http.yaml`, `storage.yaml`, `database.yaml`, `app.yaml`), `go.work`.
+- `../sm-summercmsio-app/DEPLOY.md`, `../sm-summercmsio-app/plugins/golem15/summercms/` (site plugin, routes), `../sm-summercmsio-app/terminal_check_test.go`, `../sm-summercmsio-app/vue-summercmsio-app/` (landing page "Get started").
+- msd-core `scripts/bootstrap.sh` — pattern reference for the curl | bash script (locate via the msd-core checkout; reference only).
+
+</canonical_refs>
+
+<deferred>
+## Deferred Ideas
+
+- `summer new --theme` / `sm-<name>-theme` Nuxt scaffold.
+- Publishing `summer` as prebuilt release binaries (would remove the Go prerequisite for running the CLI, not for building apps).
+
+</deferred>
+
+---
+
+*Phase: 14.3-one-command-app-scaffolding*
+*Context gathered: 2026-10-08*