From d89e18bc8eb9716a612ea10ea5e21722d3150ed1 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Wed, 30 Sep 2026 21:41:11 +0200 Subject: [PATCH] docs(11.1): record the docs update rule and the wristband default todo - CLAUDE.md: API, config-key and CLI changes update the affected docs pages; the docs checkers are named; config-key checking is deferred - todo: wristband's default resource URL and comments name a consuming application --- .../pending/wristband-neutral-resource-default.md | 14 ++++++++++++++ CLAUDE.md | 4 +++- 2 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 .planning/todos/pending/wristband-neutral-resource-default.md diff --git a/.planning/todos/pending/wristband-neutral-resource-default.md b/.planning/todos/pending/wristband-neutral-resource-default.md new file mode 100644 index 0000000..a1912ef --- /dev/null +++ b/.planning/todos/pending/wristband-neutral-resource-default.md @@ -0,0 +1,14 @@ +--- +title: Neutral default resource URL in wristband.DefaultOptions +date: 2026-09-30 +priority: medium +area: summercms.go wristband +--- + +`wristband.DefaultOptions()` ships a `Resource` default (the RFC 8707 resource indicator) whose URL names a consuming application, and the comments around it name that application too: the `Resource` field comment and the default in `modules/wristband/server.go`, the package comment at the top of `server.go`, and comments in `stores.go` and `client_issue.go`. + +A framework default should be empty or neutral. The host application sets its own resource URL from config, the way it already sets `Issuer`. Change the default to `""` or to a neutral placeholder (check first how authorize treats an empty `Resource`), and reword the comments to say "the host application". + +Until then, docs pages must not quote the default value or the comments, and any `src=` region taken from wristband must exclude them; the Phase 11.1 forbidden-name check fails the build if one leaks. + +The wristband API is unchanged in Phase 11.1 (a module API change is outside the docs phase boundary). Changing the default is a behaviour change for the host application, which must then set `Resource` explicitly. diff --git a/CLAUDE.md b/CLAUDE.md index a702cb1..5114fad 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,7 +29,9 @@ These rules apply to every GSD phase in this project and override defaults: - Any change to a package under `modules/` that touches its exported API, config keys, CLI commands or dependencies must update that module's `README.md` in the same change (the same commit or PR). - A new module ships with a `README.md` that follows the standard structure: H1 name, one-sentence summary, import line, then Overview, Features, Usage, API reference, the optional Configuration and CLI commands sections, Dependencies and Testing. It also gets a row in the root `README.md` modules table, whose purpose text reuses the summary sentence. - Framework READMEs never name a consuming application. Say "the application" or "host application", and use neutral example names such as `blog` or `acme`. -- Every identifier named in a README must exist in the package; check it with `go doc ./modules/ `. +- Every identifier named in a README or a docs page must exist in the package. The docs checker verifies this automatically; `go doc ./modules/ ` remains the manual check. +- A change to a module's exported API, config keys or CLI commands also updates the affected pages under `docs/` in the same change. `go test ./cmd/summer -run TestDocsTree` and `summer docs:build --check` check identifiers, internal links and anchors, `src=` snippets, command names and consuming-application names across `docs/` and every module README. +- Config keys named in README or docs pages are not checked automatically yet (deferred in Phase 11.1); review them by hand. ## Project