golem15/summercms
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(33): record D-70, SC-3, H1 scope and research defaults; resolve open questions

Browse Source
This commit is contained in:
Jakub Zych
2026-10-28 13:55:52 +01:00
parent 88fbfb7b39
commit 1173f35f80
2 changed files with 22 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
View File

@@ -48,6 +48,15 @@ The split of responsibility from 32-CONTEXT still holds: the backend plugins own
- **Plan list confirmed (Jakub, 2026-10-28): 14 plans**, following the "Suggested Plan Breakdown" in 33-RESEARCH.md with the 2026-10-28 amendments above added to 33-02 (Journal H1 setting), 33-05 (`links_new_tab`) and 33-09 (`postTitleTag`, `journal.breadcrumbs`, htmlGate following the Journal setting).
- **Release cadence (Jakub, 2026-10-28): all tags in 33-14.** No plugin or layer tag is pushed mid-phase. Plans 33-12 and 33-13 work against local links (`replace`, pnpm `link:`/workspace paths or patches, as 32-05 did); 33-14 tags every repo in release order and re-pins the apps.
- **Image formats (Jakub, 2026-10-28; D-85, RESEARCH Open Question 3): WebP now, in Go.** `github.com/gen2brain/webp` encodes a WebP variant once per thumbnail size, in a conga job (not in the upload request), stored next to the existing thumbnails; the layers emit `srcset` with WebP and the original format as fallback. AVIF is deferred. The dependency needs a decision note in `.planning/notes/` before `go.mod` changes. Benchmark (2026-10-28, 1200 px from a 2592×1754 photo): WebP 78 KB against JPEG q80 133 KB; about 90 ms with system libwebp (loaded through purego, no cgo), about 510 ms in the WASM fallback; AVIF only about 6% smaller than WebP at 1.3× to 20× the CPU.
- **Rendered comparison (Jakub, 2026-10-28; D-70, RESEARCH Open Question 2): optional chromedp.** The crawler's raw-HTML checks always run. The raw-versus-rendered comparison (content and links that appear only after JavaScript) runs when a Chrome path is configured (setting or config key); without one the crawler reports that the comparison was skipped. `github.com/chromedp/chromedp` needs a decision note in `.planning/notes/` before `go.mod` changes.
- **Success criterion 3 reading (Jakub, 2026-10-28; RESEARCH Open Question 4):** every data issue names the MCP tool that fixes it; an issue caused by template code carries `fix: code` instead (UI-SPEC C23).
- **H1 conversion scope (Jakub, 2026-10-28; D-50):** when the Journal H1 setting is on, the H1 to H2 conversion covers every Journal rich-text write path, post content and category pillar text alike; `journal:fix-headings` covers both.
- **Remaining research defaults accepted (Jakub, 2026-10-28):**
- Sitemap site URL precedence: sitemap setting, then `golem15.sitemap.site_url`, then `app.url` (Open Question 5).
- Related posts: opt-in in Journal, current behaviour as default (Open Question 6).
- summercms.io: pin bumps and the build guard only (Open Question 7).
- Auth pages are marked through route meta; no user layer (Open Question 10).
- The new-tab hint is on by default while new tab is on (UI-SPEC Q-8).
### Decisions implemented entirely in Phase 33
Section numbers refer to 32-CONTEXT.md.

24
.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
View File

@@ -729,26 +729,28 @@ export function autolink(html: string, links: { phrase: string; url: string }[],
| A12 | GSC for grzyby has `/sitemap.xml` submitted | Runtime State | None if index stays at the same URL |
| A13 | Optional Go modules gen2brain/webp, gen2brain/avif, chromedp are legitimate and maintained | Package audit | Supply-chain risk; gated behind checkpoint + decision note |
## Open Questions
## Open Questions (RESOLVED)
1. **Release cadence for a 10-repo phase.**
All resolved on 2026-10-28; the decisions are recorded in 33-CONTEXT.md, Planning section.
1. **Release cadence for a 10-repo phase. RESOLVED: all tags in 33-14 (CONTEXT, release cadence)**
- Known: apps pin plugins by Go tag and layers by pnpm git tag; Phase 32 tagged only in its last plan and staged the demo mount as a patch.
- Unclear: whether Jakub allows intermediate pushes and tags. Plugin tags after 33-03..06, layer tags after 33-08/09.
- Recommendation: allow intermediate tags, each behind a `checkpoint:human-verify` "push and tag" step. Otherwise 33-12 and 33-13 can only produce patches applied in 33-14, as 32-05 did.
2. **D-70 "rendered" HTML.**
2. **D-70 "rendered" HTML. RESOLVED: optional chromedp when a Chrome path is configured (CONTEXT, rendered comparison)**
- Known: a no-JS comparison needs no browser; a rendered DOM needs headless Chromium (chromedp + Chrome on the server). Chromium 154 exists on this dev machine; production servers unknown.
- Recommendation (MVP): the raw HTML is checked against CMS expectations (descriptor title in H1, word count vs `Words`, CMS-known links present). Rendered comparison deferred, or optional when a Chrome path is configured.
3. **D-85 WebP/AVIF/srcset.**
3. **D-85 WebP/AVIF/srcset. RESOLVED: WebP now in Go via gen2brain/webp, AVIF deferred (CONTEXT, image formats)**
- Known: `lagoon/attach` decodes webp but cannot encode it ("a webp thumbnail holds JPEG bytes") [VERIFIED: modules/lagoon/attach/thumb.go:22-24]. Encoding needs a new dependency.
- Options: (a) gen2brain/webp+avif in a plugin (WASM, no cgo); (b) Nuxt image pipeline (new npm deps, sharp native); (c) defer formats, ship srcset widths from existing JPEG/PNG thumbs plus alt/filename rules.
- Recommendation: (c) for MVP, with (a) as a follow-up decision note.
4. **Success criterion 3 vs layout issues.** Some crawler findings (two H1 from a layout, a missing breadcrumb component) are frontend code, not data. Recommendation: issue kinds carry either a `tool` or `fix: "code"`. The criterion then reads as: every data issue has a tool. Confirm with Jakub and Dawid.
5. **Site URL in the sitemap plugin.** Sitemap cannot read `golem15.seo.site_url` (D-95). Recommendation: a sitemap setting or config `golem15.sitemap.site_url` defaulting to `app.url`; the SEO plugin reports a mismatch as an issue.
6. **Related posts (D-82)** changes Journal API semantics (today: same category, limit 3, `published_at DESC`) [VERIFIED: sm-journal-plugin/controllers/api/posts_helpers.go:152-172]. Recommendation: opt-in config in Journal (count 3–6, tag+category scoring), default = current behaviour (porting contract).
7. **summercms.io scope.** It is a `nuxt generate` site with no sitemap or SEO plugin mounted, and it uses `@nuxtjs/seo` for its own sitemap. Recommendation: Phase 33 only bumps its Journal and layer pins and checks the build guard; a full move is deferred.
8. **D-80 vs D-81 "read more".** D-80 says only the title is a text link; D-81 allows "read more" carrying the title. Recommendation: no separate read-more anchor in the layer component.
9. **D-20c "layer routes reading their patterns from the CMS".** Nuxt routes are build-time. Recommendation: build-time options stay, plus a startup drift check against CMS patterns (logged, and reported by the crawler), rather than a build-time network fetch.
10. **"The user plugin's auth layer" (D-23)** does not exist as a Nuxt layer today; there are only vue-journal, menu, FAQ and paymentgateway layers. Recommendation: the SEO layer honours `definePageMeta({ requiresAuth: true })` / `seo: { robots }`; apps mark their auth pages; a user layer is out of scope.
4. **Success criterion 3 vs layout issues. RESOLVED: data issues name an MCP tool, code issues carry fix: code (CONTEXT)** Some crawler findings (two H1 from a layout, a missing breadcrumb component) are frontend code, not data. Recommendation: issue kinds carry either a `tool` or `fix: "code"`. The criterion then reads as: every data issue has a tool. Confirm with Jakub and Dawid.
5. **Site URL in the sitemap plugin. RESOLVED: setting, then config, then app.url (CONTEXT, defaults)** Sitemap cannot read `golem15.seo.site_url` (D-95). Recommendation: a sitemap setting or config `golem15.sitemap.site_url` defaulting to `app.url`; the SEO plugin reports a mismatch as an issue.
6. **Related posts (D-82) RESOLVED: opt-in, current behaviour default (CONTEXT, defaults)** changes Journal API semantics (today: same category, limit 3, `published_at DESC`) [VERIFIED: sm-journal-plugin/controllers/api/posts_helpers.go:152-172]. Recommendation: opt-in config in Journal (count 3–6, tag+category scoring), default = current behaviour (porting contract).
7. **summercms.io scope. RESOLVED: pin bumps and build guard only (CONTEXT, defaults)** It is a `nuxt generate` site with no sitemap or SEO plugin mounted, and it uses `@nuxtjs/seo` for its own sitemap. Recommendation: Phase 33 only bumps its Journal and layer pins and checks the build guard; a full move is deferred.
8. **D-80 vs D-81 "read more". RESOLVED: no read-more anchor (UI-SPEC L5, Q-11)** D-80 says only the title is a text link; D-81 allows "read more" carrying the title. Recommendation: no separate read-more anchor in the layer component.
9. **D-20c "layer routes reading their patterns from the CMS". RESOLVED: build-time options plus startup drift check (UI-SPEC L3)** Nuxt routes are build-time. Recommendation: build-time options stay, plus a startup drift check against CMS patterns (logged, and reported by the crawler), rather than a build-time network fetch.
10. **"The user plugin's auth layer" (D-23) RESOLVED: route meta, no user layer (CONTEXT, defaults)** does not exist as a Nuxt layer today; there are only vue-journal, menu, FAQ and paymentgateway layers. Recommendation: the SEO layer honours `definePageMeta({ requiresAuth: true })` / `seo: { robots }`; apps mark their auth pages; a user layer is out of scope.
## Environment Availability