docs(14.3-03): complete docs and landing page plan

2026-10-08 12:09:59 +02:00
parent e0640220f2
commit e2c8852b4c
1 changed files with 206 additions and 0 deletions
--- a/.planning/phases/14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new/14.3-03-SUMMARY.md
+++ b/.planning/phases/14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new/14.3-03-SUMMARY.md
@@ -0,0 +1,206 @@
+---
+phase: 14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new
+plan: 03
+subsystem: docs
+tags: [docs, summer-new, bootstrap, landing-page, nuxt, terminal-check, llms]
+
+requires:
+  - phase: 14.3-01
+    provides: "summer new with --framework, --no-plugin, --no-git; relative go.work paths from plugin:add"
+  - phase: 14.3-02
+    provides: "modules/sunrise new.sh, site GET /new, check-phase14.3.sh --acceptance-production"
+provides:
+  - "docs/setup/installation.md led by curl -fsSL https://summercms.io/new | bash -s -- demo"
+  - "go-modules-and-workspaces section Applications created by summer new"
+  - "console scaffolding section Creating an application (flags, files, first commit, naming)"
+  - "llms_notes entry for the one-command start; llms.txt and llms-full.txt carry it"
+  - "landing page Get started: one-liner, compose, build, migrate, serve (vue 6140750)"
+  - "terminal_check_test.go: terminalNewURL, SUMMERCMS_NEW_URL, terminalRunScript, reworked gated TestTerminalCommands (app d073cb9, 9539e90)"
+affects: [14.3-04 unit tests, v0.1.13 release, site redeploy]
+
+actuals:
+  tokens: 11499
+  tasks: 3
+  commits: 2
+plan_head_before: 0d117a3e57769f0b5082fb718e3d2fd755a9b406
+plan_head_after: e0640220f26fa1c25d3b1cc33e6c3e4ad5d5815b
+
+tech-stack:
+  added: []
+  patterns:
+    - "Gated shell check rewrites a blocking serve line into a background run, a bounded poll of the starter route and a stop of the app binary (pkill -P) before summer itself"
+    - "Unique COMPOSE_PROJECT_NAME plus t.Cleanup docker compose down -v in the directory the page's cd command names"
+
+key-files:
+  created:
+    - .planning/phases/14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new/14.3-03-SUMMARY.md
+  modified:
+    - docs/setup/installation.md
+    - docs/architecture/go-modules-and-workspaces.md
+    - docs/console/scaffolding.md
+    - docs/console/introduction.md
+    - docs/site.yaml
+    - README.md
+    - ../sm-summercmsio-app/vue-summercmsio-app/app/data/terminal.json
+    - ../sm-summercmsio-app/vue-summercmsio-app/i18n/locales/en.json
+    - ../sm-summercmsio-app/vue-summercmsio-app/tests/terminal.test.ts
+    - ../sm-summercmsio-app/terminal_check_test.go
+    - ../sm-summercmsio-app/README.md
+    - ../sm-summercmsio-app/CLAUDE.md
+    - ../sm-summercmsio-app/DEPLOY.md
+
+key-decisions:
+  - "The serve block stops the application binary first (pkill -P on the summer pid), because summer serve has no signal handling and killing summer alone would orphan the server on :8080"
+  - "tests/output.test.ts needed no change: it reads terminal.json and en.json instead of pinning old command literals"
+  - "The manual path in the installation guide uses go -C summercms install ./cmd/summer; verified on a fresh local clone without GOWORK=off"
+
+patterns-established:
+  - "A docs command line with summer new keeps flags after the name (summer new demo --framework <path>) so the docs command checker sees the command word"
+
+requirements-completed: [D-01, D-18, D-19, D-20, D-24, D-28]
+
+coverage:
+  - id: D1
+    description: "Landing page Get started shows and copies the six one-liner commands; every en.json string is rendered and no old terminal key remains"
+    requirement: D-19
+    verification:
+      - kind: unit
+        ref: "vue-summercmsio-app: pnpm generate && pnpm test (32 pass, 0 fail)"
+        status: pass
+      - kind: integration
+        ref: "SUMMERCMS_REQUIRE_BUILD=1 go -C plugins/golem15/summercms test -run TestTerminalCommandsInPage (after scripts/build.sh dev)"
+        status: pass
+    human_judgment: false
+  - id: D2
+    description: "Site checks pin the commands: TestLoadTerminal, TestTerminalScript (SUMMERCMS_NEW_URL rewrites only the curl command), TestTerminalEnv, TestTerminalRunScript"
+    requirement: D-19
+    verification:
+      - kind: unit
+        ref: "sm-summercmsio-app/terminal_check_test.go#TestLoadTerminal,TestTerminalScript,TestTerminalEnv,TestTerminalRunScript"
+        status: pass
+    human_judgment: false
+  - id: D3
+    description: "The six page commands run verbatim against the local script and framework HEAD and the backgrounded summer serve answers with \"plugin\":\"golem15.demo\"; the compose project is removed"
+    requirement: D-20
+    verification:
+      - kind: e2e
+        ref: "SUMMERCMS_TERMINAL_CHECK=1 SUMMERCMS_NEW_URL=file://<fw>/modules/sunrise/new.sh SUMMERCMS_REPO=<fw> SUMMERCMS_REF=<HEAD> go test -run TestTerminalCommands"
+        status: pass
+    human_judgment: false
+  - id: D4
+    description: "Installation, go modules and console docs plus the root README lead with the one-command start and document summer new as built; llms outputs include it"
+    requirement: D-18
+    verification:
+      - kind: unit
+        ref: "go test ./cmd/summer -run TestDocsTree|TestDocsBuildRealTree|TestDocsAIOutputsInSync|TestDocsRequiredPages|TestEveryModuleInSidebar"
+        status: pass
+      - kind: other
+        ref: "summer docs:build --check; docs:build --out <tmp> then grep llms-full.txt and llms.txt (LLMS-OK)"
+        status: pass
+    human_judgment: false
+  - id: D5
+    description: "Docs wording is accurate, readable and neutral (no consuming application named)"
+    requirement: D-18
+    verification:
+      - kind: other
+        ref: "grep -Eci 'fonoteka|p[lł]ytarium' on the four pages prints 0; docs:build --check forbidden-name rule"
+        status: pass
+    human_judgment: true
+    rationale: "Prose quality and the correctness of every behavioural sentence need a human read; checks only prove identifiers, links and names"
+  - id: D6
+    description: "Site framework require stays at v0.1.12; nothing pushed, tagged or deployed"
+    requirement: D-28
+    verification:
+      - kind: other
+        ref: "grep -c v0.1.12 sm-summercmsio-app/go.mod = 1 before and after"
+        status: pass
+    human_judgment: true
+    rationale: "Release, require bump and redeploy are user actions after the phase"
+
+duration: 9min
+completed: 2026-10-08
+status: complete
+---
+
+# Phase 14.3 Plan 03: Docs and landing page for the one-command start Summary
+
+**The installation guide, the console and go-modules docs, the root README and llms outputs now lead with `curl -fsSL https://summercms.io/new | bash -s -- demo` and document `summer new` as built. The summercms.io Get started card shows the six new commands, and a gated site test runs those commands verbatim until the starter route answers.**
+
+## Performance
+
+- **Duration:** 9 min
+- **Started:** 2026-10-08T10:00:04Z
+- **Completed:** 2026-10-08T10:09:15Z
+- **Tasks:** 3
+- **Files modified:** 13 (6 in summercms.go, 4 in sm-summercmsio-app, 3 in vue-summercmsio-app)
+
+## Accomplishments
+
+- `terminal.json`: groups `terminal.createApp` (the one-liner), `terminal.startDatabase` (`cd sm-demo-app`, `docker compose up -d --wait`) and `terminal.buildAndServe` (`summer build`, `summer migrate`, `summer serve`). The matching en.json strings replace `getFramework`, `installCli` and `buildExample`.
+- `terminal_check_test.go`: `terminalNewURL` and the `SUMMERCMS_NEW_URL` override (curl command only), `terminalRunScript` (background serve, 60 s poll, print body, stop), `terminalCdDir`, and `TestTerminalCommands` with a unique compose project, `t.Cleanup` down -v and the `"plugin":"golem15.demo"` assertion.
+- Gated run on this machine: the six commands passed in 17.5 s with output `{"message":"Hello from SummerCMS","plugin":"golem15.demo"}`. No `summercms-terminal-*` container or volume was left behind, port 8080 was free afterwards and no orphaned app binary remained.
+- Framework docs: the installation guide has the one-command section, what the script does (steps, refusals, three overrides), running the app, `summer new` without the script, and then the examples/hello walkthrough. The obsolete known-issues callout is gone; `summer build` in examples/hello now leaves main.go unchanged. The go-modules page has "Applications created by summer new", and `plugin:add` now adds a relative go.work path. Scaffolding has "Creating an application", introduction and site.yaml carry the llms note, and the root README has a new quick start.
+
+## Task Commits
+
+1. **Task 1: one-liner through terminal.json, site checks, installation guide**: vue `6140750` (feat), app `d073cb9` (feat, with the gitlink bump), framework `9058252` (docs)
+2. **Task 2: end-to-end run of the page commands and site docs**: app `9539e90` (feat)
+3. **Task 3: framework docs for summer new and llms outputs**: framework `e064022` (docs)
+
+Tracer gate after Task 1 (interactive, end-of-phase, automated-only verify): the verify chain was re-run green, so expansion continued.
+
+## Files Created/Modified
+
+- `docs/setup/installation.md`: one-command start first, then the manual path
+- `docs/architecture/go-modules-and-workspaces.md`: what summer new writes, the detection order and relative go.work paths
+- `docs/console/scaffolding.md`: Creating an application
+- `docs/console/introduction.md`: summer row and chapter list
+- `docs/site.yaml`: llms note
+- `README.md`: Requirements, Quick start, Using SummerCMS in an application
+- `sm-summercmsio-app/terminal_check_test.go`, `README.md`, `CLAUDE.md`, `DEPLOY.md`: the new check, its variables, `/new`, and step 4 of the deploy checklist
+- `vue-summercmsio-app/app/data/terminal.json`, `i18n/locales/en.json`, `tests/terminal.test.ts`: the landing page commands
+
+## Decisions Made
+
+- The serve stop kills summer's child (the app binary) before summer. `summer serve` delegates through `exec.CommandContext` and has no signal handler, so killing summer alone would leave the server running.
+- `tests/output.test.ts` was left unchanged because it derives everything from terminal.json and en.json.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] DEPLOY.md step 2 still referred to the page's `git clone` command**
+- **Found during:** Task 2
+- **Issue:** The page no longer shows a clone command, so step 2's reason for making the repository public was stale.
+- **Fix:** It now says the Source links and the bootstrap script behind the one-liner (which clones the repository) point at it.
+- **Files modified:** ../sm-summercmsio-app/DEPLOY.md
+- **Committed in:** 9539e90
+
+**2. [Rule 3 - Blocking] Frontmatter descriptions over 160 characters**
+- **Found during:** Task 3
+- **Issue:** `TestDocsTree` rejected the longer descriptions on three pages.
+- **Fix:** Shortened them while keeping the summer new mention.
+- **Committed in:** e064022
+
+---
+
+**Total deviations:** 2 auto-fixed (1 bug, 1 blocking). **Impact:** None on scope.
+
+## Issues Encountered
+
+None.
+
+## User Setup Required
+
+None in this plan. After the phase the user tags v0.1.13, bumps the site's require, redeploys, runs DEPLOY.md step 4 with no overrides and runs `scripts/check-phase14.3.sh --acceptance-production` (plan 04 lists these).
+
+## Next Phase Readiness
+
+- Plan 04 (unit tests) can proceed. Docs and site already describe `summer new` and the one-liner exactly as implemented.
+- Nothing was pushed, tagged or deployed. The site go.mod still requires v0.1.12 (D-28).
+
+---
+*Phase: 14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new*
+*Completed: 2026-10-08*
+
+## Self-Check: PASSED