summercms/.planning/quick/260928-lf2-rewrite-module-readmes-and-root-readme-a/260928-lf2-SUMMARY.md

phase, plan, subsystem, status, tags, requires, provides, affects, tech-stack, key-files, decisions, metrics, actuals, plan_head_before, plan_head_after, commits

phase	plan	subsystem	status	tags	requires	provides	affects	tech-stack	key-files	decisions	metrics	actuals	plan_head_before	plan_head_after	commits
quick-260928-lf2	01	docs	complete	docs readme modules claude-md		18 app-agnostic module READMEs built from the real exported API Generic SummerCMS (Go) framework root README with an 18-row modules table CLAUDE.md Documentation rule keeping module READMEs current	README.md CLAUDE.md modules/*/README.md	added patterns Module README template: H1, summary, import line, Overview, Features, Usage, API reference, optional Configuration/CLI commands, Dependencies, Testing	created modified README.md CLAUDE.md modules/backpack/README.md modules/boardwalk/README.md modules/bonfire/README.md modules/bouncer/README.md modules/cabana/README.md modules/compass/README.md modules/festival/README.md modules/fetchguard/README.md modules/lagoon/README.md modules/pact/README.md modules/party/README.md modules/phrasebook/README.md modules/postcard/README.md modules/surf/README.md modules/tide/README.md modules/towel/README.md modules/wire/README.md modules/wristband/README.md	Root README quick start was verified end to end against a throwaway Postgres 16 container; it states the extra config the example needs instead of hiding it Known issues found while verifying (example body limits, pl-PL locale, stale generated main.go) are documented in the root README and left unfixed, since this is a docs-only task Module README commits were split per agent batch (three commits), as the approved design allows	completed tasks files 2026-09-28 3 20	tokens tasks commits 31800 3 5	cc584e906e	fafb12ff02	5

Phase quick-260928-lf2 Plan 01: Module READMEs, Generic Root README and Documentation Rule Summary

The 18 module READMEs were rewritten from each package's real exported API. The root README is now a generic framework README whose quick start was verified against a real Postgres. CLAUDE.md now requires module README updates in the same change as any module API, config, CLI or dependency change.

Commits

Task	Commit	Subject
1 (batch A)	1bd3494	docs(modules): rewrite cabana, wire, towel, festival, compass, backpack READMEs
1 (batch B)	3142aeb	docs(modules): rewrite lagoon, tide, pact, party, boardwalk, fetchguard READMEs
1 (batch C)	aaa892f	docs(modules): rewrite wristband, bouncer, surf, bonfire, phrasebook, postcard READMEs
2	70d3c39	docs: generic root README
3	fafb12f	docs(claude): require module README updates

No commit carries a co-author or other attribution trailer.

What was done

• Task 1 (done earlier, three batch commits): 18 module READMEs follow the locked template and name no consuming application. Every package-qualified identifier resolves through go doc.
• Task 2: The root README.md covers the nine outline items: what SummerCMS is, key concepts, requirements, a quick start on examples/hello, the repository layout, the modules table, module path plus local replace, development commands, and design notes. The modules table has 18 rows, and each purpose cell matches that module README's summary sentence exactly (checked by script). The notes section links only the four app-neutral notes.
• Task 3: ## Documentation sits between ## Commit rules and the first <!-- GSD:project-start --> marker. It has four bullets: the same-change README update rule, the standard structure plus a modules-table row for new modules, no consuming-application names, and go doc identifier checks. The change only adds lines (7 insertions, 0 deletions).

Quick start verification

Every command in the quick start was confirmed before it was written:

• go run ./cmd/summer --help and ./bin/hello --help list the quoted commands.
• summer build in examples/hello produces bin/hello.
• greeter:hello and key:generate run without a database.
• A throwaway postgres:16-alpine container, with a database created with ICU pl-PL, was used for the rest. With SUMMER_DATABASE__DSN, SUMMER_APP__KEY and SUMMER_STORAGE__UPLOADS__BUCKET_URL=mem:// set, and a temporary config/http.yaml holding the body limits, these all succeeded: migrate, migrate:status, route:list, and serve --addr (GET /items/1 returned {"id":1}).

Afterwards the temporary config file was removed, the regenerated main.go was restored and the container was stopped. git status --porcelain examples/ is empty.

Checks

Check	Result
Forbidden-name grep over README.md and modules/*/README.md	NAMES OK
Root README content (TABLE/MISSING/LAYOUT)	ROOT OK
Relative links in README.md and all module READMEs	LINKS OK
Module README structure (title, import, section order)	STRUCTURE OK
Package-qualified identifiers resolve via go doc	IDENTS OK
scripts/check-phase10.2.sh --readmes and --status	pass
git status --porcelain examples/ empty	pass
CLAUDE.md section placement, additions only	CLAUDE OK
go vet ./..., go test ./..., no .go changes since cc584e9, no co-author trailer	SANITY OK

The Task 1 executors reported that the plain ]( link check gives false positives on Go generics inside code blocks. The plan's check excludes (, # and whitespace from the target, and it reported no false positives on the final files.

Deviations from Plan

• Quick start content. The plan outline puts serve and migrate right after summer build. In practice they also need app.key, an uploads bucket URL, numeric http.body_limits values from a config file and an ICU pl-PL database. The README states these requirements and adds a Known issues subsection rather than leaving out steps. No Go code or example config was changed.
• Commits on master. They were made on master. The project config uses branching_strategy: none and no worktrees, and Task 1 and the orchestrator instructions follow the same practice.

Known Stubs

None.

Follow-ups (not fixed; docs-only task)

1. examples/hello lacks http.body_limits config. surf fails at boot with surf: config http.body_limits.default_bytes is required, which breaks serve, route:list and the example's TestTypedItemRoute (confirmed: cd examples/hello && go test ./... fails there). The root go test ./... does not cover the example module, so it stays green. Fix: add examples/hello/config/http.yaml with default_bytes/upload_bytes, then drop step 2 and the first Known issues bullet from the root README.
2. The SUMMER_ env overlay cannot set numeric keys that surf reads. SUMMER_HTTP__BODY_LIMITS__DEFAULT_BYTES=1048576 is rejected with must be numeric, got string. Either compass should coerce these values or surf should parse numeric strings.
3. surf validates http.body_limits.upload_bytes but never applies it.
4. lagoon hardcodes an application locale: lagoon.CheckLocale requires ICU pl-PL (requiredICULocale in modules/lagoon/connection.go). This should be configurable, with pl-PL as the application's setting.
5. wristband hardcodes application values: wristband.DefaultOptions().Resource is an application URL, and the scopes and /oauth/mcp/* paths are fixed. These should come from options or config.
6. The committed examples/hello/main.go is stale. It predates the generator's surf.RouteListCommand and cabana.RuntimeCommands wiring, so summer build and the example's TestBuiltBinary* tests leave it modified. Fix: regenerate and commit it.
7. key:generate prints a ✓ prefix before the key, so export SUMMER_APP__KEY=$(./bin/hello key:generate) produces an invalid key. The README tells readers to copy the value. Consider printing the bare key to stdout.
8. Application repository README: the removed application-specific run steps (database setup, admin path, cutover status) should be checked against the application repository's own README. It was not edited here, per the plan.

Self-Check: PASSED

• FOUND: README.md, CLAUDE.md, all 18 modules/*/README.md
• FOUND commits: 1bd3494, 3142aeb, aaa892f, 70d3c39, fafb12f