--- phase: 11.1-summercms-documentation-for-humans-and-ai-agents plan: 03 subsystem: docs tags: [docs, wintercms, concept-map, examples, console, architecture, plugins] requires: - phase: 11.1-02 provides: "identifier, link, command, forbidden, fence and callout checkers; the theme; docs:serve; scripts/check-phase11.1.sh" - phase: 11.1-01 provides: "internal/docsite generator, docs:build, docs:sync, src= snippet extraction and bonfire ExampleCall" provides: - "docs/setup: introduction, installation (rewritten), configuration, coming-from-wintercms" - "docs/architecture: introduction, go-modules-and-workspaces, application-lifecycle, request-lifecycle" - "docs/plugins: registration, scheduling, extending, testing" - "docs/console: introduction, setup-and-maintenance, scaffolding, writing-commands, utilities" - "site.yaml sections setup, architecture, plugins, console, api" - "Examples: party ExamplePlugin (with BlogPlugin in example_plugin_test.go), backpack ExampleApp_Publish, pact ExampleHasSchedule, festival ExampleBus_Fire, towel ExampleWithLocale, bonfire ExampleCatalog" - "cmd/summer TestDocsRequiredPages with 18 required page URLs" affects: [11.1-04, 11.1-05, 11.1-06] estimate_ref: "tokens 100000, tasks 3, confidence low" actuals: tokens: 23900 tasks: 3 commits: 4 plan_head_before: f77b1d868890ed8e2762d71e6a64c94274615edf plan_head_after: 8254fb91a92ae4a297ed536f8dac6145caa55372 tech-stack: added: [] patterns: - "A plugin type that a page shows in full lives in its own example_plugin_test.go and is referenced as a whole-file src= fence; the Example that exercises it is a separate #Example fence" - "Descriptions containing ': ' are double-quoted in frontmatter (goccy/go-yaml rejects them unquoted)" - "Commands in docs are written as summer or ./bin/acme so the command checker verifies them; ./bin/ placeholders are never used because the checker cannot see them" key-files: created: - docs/setup/introduction.md - docs/setup/configuration.md - docs/setup/coming-from-wintercms.md - docs/architecture/introduction.md - docs/architecture/go-modules-and-workspaces.md - docs/architecture/application-lifecycle.md - docs/architecture/request-lifecycle.md - docs/plugins/registration.md - docs/plugins/scheduling.md - docs/plugins/extending.md - docs/plugins/testing.md - docs/console/introduction.md - docs/console/setup-and-maintenance.md - docs/console/scaffolding.md - docs/console/writing-commands.md - docs/console/utilities.md - modules/party/example_test.go - modules/party/example_plugin_test.go - modules/backpack/example_test.go - modules/pact/example_test.go - modules/festival/example_test.go - modules/towel/example_test.go - .planning/todos/pending/bonfire-duplicate-command-names.md modified: - docs/site.yaml - docs/index.md - docs/setup/installation.md - modules/bonfire/example_test.go - cmd/summer/docs_test.go key-decisions: - "The Plugin.php-in-Go section shows the whole modules/party/example_plugin_test.go file, because a Go Example body cannot declare the four party.Plugin methods; ExamplePlugin is shown separately as the plan requires" - "Hand-written Go fences are never used: a GORM-callback sketch and a Commands() sketch were replaced by prose rather than shipping unverified Go" - "Pages describe bonfire as it is: command names are not checked for duplicates. The gap is logged as a todo; bonfire is not changed in this plan" - "serve's default --addr (:8080) is documented as listening on every interface, with loopback shown in every example" patterns-established: - "requiredPages in cmd/summer/docs_test.go is the list each content plan appends to" - "Example files use package _test and the neutral acme.* plugin IDs" requirements-completed: [DOCS-01, DOCS-04, DOCS-06] coverage: - id: D1 description: "Coming from WinterCMS maps WinterCMS concepts to 50 distinct checked pkg.Ident spans, lists what is not provided and shows Plugin.php next to a verified Go plugin" requirement: DOCS-06 verification: - kind: unit ref: "cmd/summer/docs_test.go#TestDocsTree" status: pass - kind: unit ref: "modules/party/example_test.go#ExamplePlugin" status: pass human_judgment: false - id: D2 description: "Setup, Architecture, Plugins and Console sections are in the sidebar in that order before API reference, and every page of this plan builds as .html and .md" requirement: DOCS-01 verification: - kind: unit ref: "cmd/summer/docs_test.go#TestDocsRequiredPages" status: pass - kind: unit ref: "cmd/summer/docs_test.go#TestDocsAIOutputsInSync" status: pass - kind: unit ref: "cmd/summer/docs_test.go#TestDocsBuildRealTree" status: pass human_judgment: false - id: D3 description: "Every Go fence in the new pages is a src= copy of an Example or test declaration that go test runs" requirement: DOCS-04 verification: - kind: unit ref: "modules/backpack/example_test.go#ExampleApp_Publish" status: pass - kind: unit ref: "modules/pact/example_test.go#ExampleHasSchedule" status: pass - kind: unit ref: "modules/festival/example_test.go#ExampleBus_Fire" status: pass - kind: unit ref: "modules/towel/example_test.go#ExampleWithLocale" status: pass - kind: unit ref: "modules/bonfire/example_test.go#ExampleCatalog" status: pass - kind: other ref: "go run ./cmd/summer docs:build --check" status: pass human_judgment: false - id: D4 description: "Console pages name only commands that exist; no page names a consuming application; examples bind loopback" requirement: DOCS-01 verification: - kind: other ref: "scripts/check-phase11.1.sh --docs and --forbidden" status: pass - kind: other ref: "! grep -rn '0\\.0\\.0\\.0' docs/setup docs/console" status: pass human_judgment: false - id: D5 description: "Pages read in WinterCMS docs tone and are useful to a WinterCMS developer" verification: [] human_judgment: true rationale: "Backstop truth in the plan: tone and usefulness are a reader's judgment" duration: 15min completed: 2026-09-30 status: complete --- # Phase 11.1 Plan 03: Framework content A (Setup, Architecture, Plugins, Console) Summary **Sixteen new or rewritten guide pages cover installation to serve, a WinterCMS concept map with 50 checked identifiers, the binary and request lifecycles, plugin registration, scheduling, extending and testing, and every `summer` and application command. Each Go block on them is a copy of an Example that `go test` runs.** ## Performance - **Duration:** about 15 min - **Started:** 2026-09-30T20:03:31Z - **Completed:** 2026-09-30T20:18Z - **Tasks:** 3 - **Files modified:** 28 ## Accomplishments - `docs/setup/coming-from-wintercms.md` has a 21-row concept table (WinterCMS, SummerCMS identifiers, module link), a "What is not provided" table (CMS pages, themes, components, AJAX and Snowboard, media manager, import/export, sorting, collections, behaviours, cache, session), and a "Plugin.php in Go" section with a PHP fence next to the verified Go plugin. - Architecture explains the single binary and headless model, the module map by concern, `summer` versus the application binary, go.mod `replace` and `go.work` workflows with `summer plugin:add`, the generated start-up sequence, Register-then-Boot, the typed container, `lagoon.OnDatabase`, and surf's wrapping order (read from `surf.Router.wrap`: CORS, recovery, locale, body limit, route middleware, constraints). - Plugins covers ID rules (from `pluginIDRe`), the capability interfaces, embedded config, lang and mail files, the scaffolded layout, schedule semantics and validation, leader election, `schedule:run --once` for cron, events with the three dispatch modes, services, optional dependencies, GORM callbacks and forking, and the test workflow including the ICU database requirement. - Console lists every runtime command with flags (migrations, key, serve, route:list, admin, queue, schedule, websockets), the seven commands `summer` delegates, what each `make:` command writes (from internal/build/artifact.go), the bonfire API for writing commands, and the parity and docs utilities with their flags and defaults. - Installation now walks from `go install` through `summer build`, the ICU database, `config/http.yaml`, `SUMMER_` variables with `` markers, `migrate`, `route:list` and `serve --addr 127.0.0.1:8080`, with the known issues as a `[!WARNING]` callout. Its ExampleCall section is kept. - `TestDocsRequiredPages` asserts all 18 required URLs load and build as `.html` and `.md`. ## Task Commits 1. **Task 1: Tracer, the concept map with a verified plugin example:** `d6003cd` (feat) 2. **Task 2: Architecture and Plugins sections:** `1f8f5e1` (feat) 3. **Task 3: Setup and Console sections:** `a896f3f` (feat) 4. **Todo for the bonfire duplicate command name gap:** `8254fb9` (docs) **Plan metadata:** the docs(11.1-03) commit that adds this file ## Files Created/Modified See `key-files` in the frontmatter. ## Decisions Made See `key-decisions` in the frontmatter. ## Deviations from Plan ### Auto-fixed Issues **1. [Rule 3 - Blocking] The plugin type could not live in the Example body** - **Found during:** Task 1 - **Issue:** The plan's `#ExamplePlugin` fence shows only the Example body, and Go methods cannot be declared inside a function. The "Plugin.php in Go" section needs the four `party.Plugin` methods to be visible. - **Fix:** `BlogPlugin` and its methods are in `modules/party/example_plugin_test.go`, shown as a whole-file `src=` fence. `ExamplePlugin` in `example_test.go` uses it and is shown as the planned `#ExamplePlugin` fence. - **Files modified:** modules/party/example_plugin_test.go (one file beyond the plan's list) - **Commit:** d6003cd **2. [Rule 1 - Bug] Frontmatter descriptions with a colon failed to parse** - **Found during:** Task 2 - **Issue:** Four descriptions contained `: ` and goccy/go-yaml rejected them (`mapping value is not allowed in this context`). - **Fix:** Those description values are double-quoted. - **Commit:** 1f8f5e1 **3. [Rule 1 - Accuracy] Claims corrected against the code before commit** - A statement that duplicate command names fail at start-up was false (bonfire has no duplicate check). The page now describes the real behaviour, and the gap is logged in `.planning/todos/pending/bonfire-duplicate-command-names.md`. - Two hand-written Go fences (a GORM callback in Boot and a `Commands()` method) were replaced by prose, because Go fences in docs pages must be `src=` copies. - The `wire` description was rewritten from its README (HTML characters unescaped, no trailing newline, `[]` for nil lists, Carbon timestamps). ### Notes - `registration.md` does not link the Console scaffolding page, because that page did not exist when Task 2 committed. It points at the `make:` commands in prose instead. - `gofmt -l modules/party` lists `registry_test.go`, which this plan did not touch. **Total deviations:** 2 auto-fixed (1 blocking, 1 bug) and 1 set of accuracy corrections. **Impact:** none on scope. ## Issues Encountered None. The in-flight Phase 11 review edits (`modules/lagoon/transaction*.go`, the check-phase10/11 scripts and the Phase 11 review files) were never staged or touched. `go test -short ./...` was green at every commit with them in the tree. ## Verification - `go vet ./...` and `go test -short ./...` are green. - All six new Examples and `ExampleCall` report `--- PASS`. - `TestDocsTree`, `TestDocsRequiredPages`, `TestDocsAIOutputsInSync` and `TestDocsBuildRealTree` pass. `docs:build` writes 40 pages. - `go run ./cmd/summer docs:build --check` reports no problems. `docs:sync` reports every snippet up to date. - `scripts/check-phase11.1.sh --docs` and `--forbidden` pass. - Every acceptance grep in the plan matches: 50 distinct identifiers on the concept map, 8 Architecture and Plugins pages, 4 Setup and 5 Console pages, `ICU_LOCALE` and the ExampleCall fence in installation.md, and no `0.0.0.0` in setup or console. ## Known Stubs None. ## User Setup Required None. ## Next Phase Readiness Plan 11.1-04 can add the Backend, Database and Services sections between Plugins and Console in site.yaml, link the concept map rows to its new guide pages, and append its pages to `requiredPages`. ## Self-Check: PASSED All created files exist. Commits d6003cd, 1f8f5e1, a896f3f and 8254fb9 are in the log.