summercms/.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-03-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, estimate_ref, actuals, plan_head_before, plan_head_after, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, coverage, duration, completed, status

phase	plan	subsystem	tags	requires	provides	affects	estimate_ref	actuals	plan_head_before	plan_head_after	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	coverage	duration	completed	status
11.1-summercms-documentation-for-humans-and-ai-agents	03	docs	docs wintercms concept-map examples console architecture plugins	phase provides 11.1-02 identifier, link, command, forbidden, fence and callout checkers; the theme; docs:serve; scripts/check-phase11.1.sh phase provides 11.1-01 internal/docsite generator, docs:build, docs:sync, src= snippet extraction and bonfire ExampleCall	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	11.1-04 11.1-05 11.1-06	tokens 100000, tasks 3, confidence low	tokens tasks commits 23900 3 4	f77b1d8688	8254fb91a9	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 <name> or ./bin/acme <name> so the command checker verifies them; ./bin/<app> placeholders are never used because the checker cannot see them	created modified 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 docs/site.yaml docs/index.md docs/setup/installation.md modules/bonfire/example_test.go cmd/summer/docs_test.go	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	requiredPages in cmd/summer/docs_test.go is the list each content plan appends to Example files use package <m>_test and the neutral acme.* plugin IDs	DOCS-01 DOCS-04 DOCS-06	id description requirement verification human_judgment D1 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 DOCS-06 kind ref status unit cmd/summer/docs_test.go#TestDocsTree pass kind ref status unit modules/party/example_test.go#ExamplePlugin pass false id description requirement verification human_judgment D2 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 DOCS-01 kind ref status unit cmd/summer/docs_test.go#TestDocsRequiredPages pass kind ref status unit cmd/summer/docs_test.go#TestDocsAIOutputsInSync pass kind ref status unit cmd/summer/docs_test.go#TestDocsBuildRealTree pass false id description requirement verification human_judgment D3 Every Go fence in the new pages is a src= copy of an Example or test declaration that go test runs DOCS-04 kind ref status unit modules/backpack/example_test.go#ExampleApp_Publish pass kind ref status unit modules/pact/example_test.go#ExampleHasSchedule pass kind ref status unit modules/festival/example_test.go#ExampleBus_Fire pass kind ref status unit modules/towel/example_test.go#ExampleWithLocale pass kind ref status unit modules/bonfire/example_test.go#ExampleCatalog pass kind ref status other go run ./cmd/summer docs:build --check pass false id description requirement verification human_judgment D4 Console pages name only commands that exist; no page names a consuming application; examples bind loopback DOCS-01 kind ref status other scripts/check-phase11.1.sh --docs and --forbidden pass kind ref status other ! grep -rn '0.0.0.0' docs/setup docs/console pass false id description verification human_judgment rationale D5 Pages read in WinterCMS docs tone and are useful to a WinterCMS developer true Backstop truth in the plan: tone and usefulness are a reader's judgment	15min	2026-09-30	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 <secret> 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.