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

docs(11.2): capture phase context for the Alpha 0.1 landing page

Browse Source
This commit is contained in:
Jakub Zych
2026-10-01 14:33:50 +02:00
parent 59122d53c1
commit 3cbc8d32d1
2 changed files with 244 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
.planning/phases/11.2-ready-to-share-summercms-io-website-and-newsletter-plugin/11.2-CONTEXT.md
View File

@@ -1,41 +1,179 @@
# Phase 11.2: Ready to share: summercms.io website and newsletter plugin - Context
# Phase 11.2: summercms.io Alpha 0.1 landing page on SummerCMS - Context
**Gathered:** 2026-09-29
**Updated:** 2026-10-01 (phase reshaped into the Alpha 0.1 landing page; newsletter moved to 11.3)
**Status:** Ready for planning
> **How to read this file.** Decision numbers are stable because ROADMAP.md cites them. The decisions that apply to 11.2 are D-01 to D-05 (three repos only), D-07, D-09 and D-12 from the 2026-09-29 discussion, plus D-23 to D-45 from 2026-10-01. D-06, D-08, D-10 and D-11 are superseded and kept only as one-line stubs. D-13 to D-22 belong to Phase 11.3 and are kept verbatim in the `<phase_11_3_handoff>` section at the end. The 11.2 planner ignores that section.
<domain>
## Phase Boundary
summercms.io becomes shareable. A Nuxt 4 landing site in English and Polish runs on a SummerCMS binary. Visitors subscribe for updates through a new `sm-newsletter-plugin`, a stub that collects emails with double opt-in and does not send newsletters. The Phase 11.1 docs are served at `/docs` and linked from the site. The work spans four new repos, laid out like a WinterCMS project (root app, Vue frontend, site plugin and a reusable plugin). The framework (`summercms.go`) changes only if a missing framework feature blocks the site.
summercms.io replaces its "Under construction" page with the Alpha 0.1 landing page from the claude.ai/design handoff in `design/`. The page is a Nuxt 4 static site, English only and i18n-ready. It is embedded in one SummerCMS binary that also serves the Phase 11.1 docs at `/docs`. It deploys to the `rome` server behind nginx and supervisor, following a documented and scripted procedure.
Three new repos: `sm-summercms-app`, `vue-summercms-app` and `sm-summercms-plugin`. The framework (`summercms.go`) gets three small, scoped changes: Postgres 15 support verified and documented (D-25), an optional docs-to-site link (D-41) and a `v0.1.0` tag (D-42).
Out of scope: newsletter signup, the Polish locale and the subscriber admin. These are Phase 11.3.
</domain>
<decisions>
## Implementation Decisions
### Repos and layout
- **D-01:** Four new repos follow the `sm-` naming convention (`oc-`/`wn-` in October/Winter):
### Repos and layout (2026-09-29, still in force)
- **D-01:** Three new repos follow the `sm-` naming convention (`oc-`/`wn-` in October/Winter):
- `sm-summercms-app` is the root app. It builds the binary, holds the other pieces and wires the plugins.
- `vue-summercms-app` is the Nuxt 4 site, held inside the root app as `vue-fonoteka-app` is in the fonoteka project.
- `sm-summercms-plugin` is the site plugin. It holds everything specific to summercms.io: serving the embedded Nuxt build at `/`, mounting the 11.1 docs output at `/docs`, and any site-specific data or routes. This is the proven WinterCMS pattern from `figs.org.pl` (`figs/website`) and golem15.com.
- `sm-newsletter-plugin` is the reusable signup plugin, with Go package `newsletter`.
Public static-site serving goes in `sm-summercms-plugin`, not in a new framework module. — **Reversibility:** costly — repo names and module paths are referenced by the go.work/replace wiring and every import.
- **D-02:** Go module paths live under `git.golem15.com/golem15/`, like the framework (`git.golem15.com/golem15/summercms`): for example `git.golem15.com/golem15/sm-newsletter-plugin`. — **Reversibility:** one-way — a published Go module path is baked into every importer.
- **D-03:** The root app wires the framework and both plugins the way `fonoteka.go` does today (a go.work workspace with a local replace during development).
Public static-site serving goes in `sm-summercms-plugin`, not in a new framework module. (The fourth repo, `sm-newsletter-plugin`, moved to 11.3.) — **Reversibility:** costly — repo names and module paths are referenced by the go.work/replace wiring and every import.
- **D-02:** Go module paths live under `git.golem15.com/golem15/`, like the framework (`git.golem15.com/golem15/summercms`): for example `git.golem15.com/golem15/sm-summercms-plugin`. — **Reversibility:** one-way — a published Go module path is baked into every importer.
- **D-03:** The root app wires the framework and the site plugin the way `fonoteka.go` does today (a go.work workspace with a local replace during development).
### Website build and hosting
- **D-04:** The site is Nuxt 4 with `nuxt generate` (static output), the same stack as `vue-fonoteka-app`. Every route is real prerendered HTML, so link previews and search engines see content. The signup widget hydrates as normal Vue.
- **D-05:** The generated site and the 11.1 docs output are embedded in the Go binary with `go:embed`. One binary serves `/`, `/docs` and the plugin API. The build order (nuxt generate, then `summer docs:build`, then `go build`) is documented and scripted in the root app.
- **D-06:** The site is in English and Polish (for example `/` and `/pl/`, via `@nuxtjs/i18n` as in `vue-fonoteka-app`). The confirmation and welcome mails are localized to the subscriber's locale through phrasebook/postcard. The 11.1 docs stay English-only.
### Website build and hosting (2026-09-29, still in force)
- **D-04:** The site is Nuxt 4 with `nuxt generate` (static output), the same stack as `vue-fonoteka-app`. Every route is real prerendered HTML, so link previews and search engines see content.
- **D-05:** The generated site and the 11.1 docs output are embedded in the Go binary with `go:embed`. One binary serves `/` and `/docs`. The build order (nuxt generate, then `summer docs:build`, then `go build`) is documented and scripted in the root app.
- **D-06:** *Superseded.* The site is English only for now (see D-33); Polish moves to 11.3.
- **D-07:** The site's served responses must be indexable. The admin-only `boardwalk` behaviour (`noindex, nofollow`, admin CSP, base-path rewrite) must not apply to the public site. The site plugin sets its own cache headers: immutable for hashed assets, no-cache for HTML.
### Landing page content
- **D-08:** The page has these sections: a hero with the email signup, "what it is" (plugins that extend each other, YAML admin forms and lists, scaffolding CLI, headless API, a single compiled binary), "Coming from WinterCMS" linking to the 11.1 concept map, and status and roadmap.
- **D-09:** The "Coming from WinterCMS" section tells the lineage as a seasons story: it started in October (OctoberCMS), went through Winter (WinterCMS), and now it's time for Summer. The seasons theme can carry through the copy and visuals.
- **D-10:** The page is clearly pre-release in tone. It says the project is early and asks people to subscribe for the first release.
- **D-11:** The page has no link to source repos yet. Subscribe is the call to action.
- **D-12:** A "Built by Golem15" footer credit links to golem15.com.
### Landing page content (2026-09-29)
- **D-08:** *Superseded* by the design handoff's section list: header, hero, Why, Features, From WinterCMS, Get started and footer.
- **D-09:** The "From WinterCMS" section carries the seasons lineage: it started in October (OctoberCMS), went through Winter (WinterCMS), and now it's time for Summer. The handoff's copy is final. The theme lives in the brand (sun, "A new dawn", "Something bright is here") and is not added as extra copy.
- **D-10:** *Superseded.* The tone is "Alpha 0.1 is out", per the handoff.
- **D-11:** *Superseded.* Source links are on the page (see D-38).
- **D-12:** A "Built by Golem15" credit links to golem15.com. It is an addition to the handoff's footer, styled as a footer link.
### Design handoff
- **D-23:** The handoff in `design/` (`README.md`, `SummerCMS Landing.dc.html`) is high fidelity. Colors, type, spacing, copy, breakpoints and the two interactions (scroll-spy and copy-to-clipboard) are matched exactly. The only copy deviations are those decided here: D-12 (credit), D-39 (clone line) and D-26 (the Postgres chip).
### Database at runtime
- **D-24:** The binary keeps the stock `summer serve` path, which opens Postgres unconditionally (`modules/surf/serve.go:40`). There is no framework change to make the DB optional. `rome` already runs PostgreSQL 15.19 (Debian 12).
- **D-25:** Verify the framework on PostgreSQL 15. Run the framework's database test suites (lagoon, conga and the rest that use `postgres:16-alpine`) against a `postgres:15` image. If they pass, change the documented requirement from "PostgreSQL 16" to "PostgreSQL 15 or newer" in the root `README.md`, `docs/setup/installation.md` and any other page that states it (the docs checker must stay green). **If any test fails on 15, stop and ask the user.** Do not quietly work around it or upgrade rome.
- **D-26:** The "PostgreSQL 16" chip in the Get started section follows D-25 and reads "PostgreSQL 15+".
- **D-27:** The app uses a dedicated Postgres role (`summercms`) that owns a dedicated database (`summercms_io`). The password lives in the app's config or env on the server, never in git. DEPLOY.md documents `createuser`/`createdb`, and every deploy runs the app's `migrate` command before restarting.
### Server and deploy flow
- **D-28:** The binary is built locally for linux/amd64 by a script in `sm-summercms-app` (nuxt generate, then `summer docs:build --base-url /docs`, then `go build`), then rsynced to rome with its config. The server needs neither Go nor Node.
- **D-29:** `/backend` and the admin API are not exposed publicly. nginx proxies only `/` and `/docs` to the binary and denies the admin paths. Nothing needs administering until 11.3.
- **D-30:** TLS uses rome's existing certbot / Let's Encrypt setup. DEPLOY.md shows the nginx server block with the certbot-managed certificate paths, HTTP to HTTPS redirect, gzip and proxy headers.
- **D-31:** Cutover replaces the existing summercms.io nginx server block in place. The current "Under construction" block is saved in DEPLOY.md (or alongside it) as the rollback.
- **D-32:** The binary runs under supervisor as a dedicated system user on a localhost-only port. The user, port and paths are Claude's discretion and are written down in DEPLOY.md and the supervisor program config.
### Design to Nuxt
- **D-33:** The site is i18n-ready. `@nuxtjs/i18n` is installed and configured with the single locale `en`, and all page copy lives in `locales/en.json`. 11.3 adds `pl.json` and a switcher without touching component markup.
- **D-34:** Roboto (300/400/500/700) and Roboto Mono (400/500) are self-hosted through `@nuxt/fonts`, the same module as `vue-fonoteka-app`. They are downloaded at build time and embedded, so visitors make no request to Google.
- **D-35:** Styles are plain CSS. The handoff tokens are CSS custom properties on `:root`, used by scoped component styles. No Tailwind.
- **D-36:** The sun artwork is the original from the live site, `http://summercms.io/logo.png` (746×744 transparent RGBA PNG, 513 KB). It replaces the handoff's `sun-crop.png` placeholder. Resized and compressed copies are made for the hero badge (180px), the header logo (30px), the favicon set and the OG image.
- **D-37:** SEO uses the full `@nuxtjs/seo` module, as `vue-fonoteka-app` does: meta, Open Graph and Twitter tags, OG image, schema.org, sitemap and robots. Whatever it generates must work with `nuxt generate` and be embedded (no runtime OG rendering in the Go binary).
- **D-45:** The prototype's `showRays` and `scrollSpy` flags become Nuxt app config, both defaulting to `true`.
### Get started accuracy
- **D-38:** Both Source links point to `https://git.golem15.com/golem15/summercms`. The repo currently requires login, so making it public is a launch checklist item in DEPLOY.md, done manually by the user before cutover. The link check (roadmap criterion 3) verifies anonymous access at cutover time.
- **D-39:** The terminal card gets a clone step so it works when pasted into a fresh shell: a `# get the framework` comment, then `$ git clone https://git.golem15.com/golem15/summercms` and `$ cd summercms`, before the existing `go install ./cmd/summer` group. The Copy button copies every command line in order (now six), without `$` or comments.
- **D-40:** A scripted check proves the terminal commands work verbatim. It runs them in a temp clone with a temp `GOBIN`, ending with `./bin/hello greeter:hello`. If that command needs a database or other setup, the check provides it, and the copy is not changed again without asking. The command list lives in one place shared by the page and the check, or the check asserts that the two match, so they cannot drift.
### Docs and release
- **D-41:** Framework change: an optional `site_url` key in `docs/site.yaml` adds a link back to the main site in the docs header (`internal/docsite/theme/templates/header.html`), for example "← summercms.io". When the key is unset, the output is unchanged. The change also updates the docs page that describes `site.yaml`, and `summer docs:build --check` and `TestDocsTree` stay green. summercms.io sets it to `/`.
- **D-42:** The framework is tagged `v0.1.0` (Alpha 0.1). `sm-summercms-app` requires `git.golem15.com/golem15/summercms v0.1.0` (with the local replace during development), and the embedded docs are built from that tag, so the page, the docs and the code agree. The user confirms before the tag is created and pushed. — **Reversibility:** one-way — a pushed Go module version tag is cached by proxies and cannot be reused.
- **D-43:** The new repos live as siblings of `summercms.go` in the meta repo directory (`summercms/sm-summercms-app/`, like `fonoteka.go`). `vue-summercms-app` and `sm-summercms-plugin` are submodules inside `sm-summercms-app`. Creating the remotes on git.golem15.com is a manual step the plan lists for the user.
- **D-44:** Every link on the page is verified against the built docs output (roadmap criterion 3), not assumed. As of 2026-10-01 all ten `/docs/...` targets in the handoff exist as pages in `docs/`.
### Claude's Discretion
- The system user, port and filesystem paths on rome (D-32).
- Whether the Nuxt build and the docs are embedded by `sm-summercms-plugin` or by the root app, and how the plugin mounts `/docs`.
- The 404 handling for unknown paths (for example Nuxt's generated `404.html` with a 404 status).
- Image formats and sizes derived from the sun artwork, and the OG image layout within the brand.
- Where the D-40 command check lives (root app script or test) and how it shares the command list with the page.
- How `prefers-reduced-motion` affects smooth scrolling.
</decisions>
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Phase scope and design
- `.planning/ROADMAP.md` § Phase 11.2: goal, repos, naming convention, design source and success criteria.
- `.planning/phases/11.2-ready-to-share-summercms-io-website-and-newsletter-plugin/design/README.md`: the high-fidelity handoff (layout, tokens, copy, interactions). **Must read.**
- `.planning/phases/11.2-ready-to-share-summercms-io-website-and-newsletter-plugin/design/SummerCMS Landing.dc.html`: the HTML design reference. Ignore its `support.js` runtime.
- `http://summercms.io/logo.png`: the original sun artwork (D-36).
### Docs build (Phase 11.1)
- `.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-CONTEXT.md`: how the docs are built (`summer docs:build`, static output, `internal/docsite`).
- `docs/site.yaml`: docs config (`base_url`, and the new `site_url` from D-41).
- `cmd/summer/docs.go` and `internal/docsite/load.go`: the `--base-url` flag and how it overrides `base_url`.
- `internal/docsite/theme/templates/header.html`: the docs header that D-41 changes.
### Framework touch points
- `modules/surf/serve.go`: `serve` opens the database unconditionally (D-24).
- `README.md`, `docs/setup/installation.md` and `docs/plugins/testing.md`: where "PostgreSQL 16" is stated (D-25).
- `modules/boardwalk/README.md`: the embedding and cache-header reference. Its admin security headers must not be reused (D-07).
- `examples/hello`: the app the terminal card builds and runs (D-40).
### App wiring and frontend references
- `../fonoteka.go` (`main.go`, `go.work`, `summer.yaml`, `config/`): the reference for app wiring (D-03).
- `/media/nvme/dev/golem15/fonoteka/vue-fonoteka-app` (`nuxt.config.ts`, `package.json`): Nuxt 4 with `@nuxt/fonts`, `@nuxtjs/i18n` v10 and `@nuxtjs/seo`, the setup to mirror (D-33, D-34, D-37). Note its comments about i18n on static builds (`_i18n/**/*.json`).
- `/media/nvme/dev/golem15/figs.org.pl/plugins/figs/website`: the WinterCMS site-plugin pattern (D-01).
</canonical_refs>
<code_context>
## Existing Code Insights
### Reusable Assets
- `boardwalk`: its `go:embed` handling and its hashed-asset versus HTML cache headers are a pattern to copy into `sm-summercms-plugin`. Its `noindex`, admin CSP and base-path rewrite are not.
- `summer docs:build --base-url /docs`: already emits docs with the right link prefix for mounting under `/docs`.
- `summer build`: generates the app's `main.go` and `plugins.gen.go` from `summer.yaml`, as in `fonoteka.go`.
- The 11.1 docs checker (`TestDocsTree`, `docs:build --check`): it already verifies internal links and commands across `docs/`, so the D-41 change must keep it green.
### Established Patterns
- Plugins are compiled Go modules registered at build time (no runtime loading).
- Every application repo is a go.work workspace that requires the framework with a local replace.
- Framework READMEs and docs never name a consuming application, so the D-41 docs use a neutral example URL, not summercms.io.
- Unit tests are the last plan of the phase. `go vet` and `go test ./...` stay green in every repo.
### Integration Points
- `sm-summercms-app` registers `sm-summercms-plugin`, and the plugin's routes serve `/` (Nuxt output) and `/docs` (docs output) from the surf mux.
- nginx on rome proxies `/` and `/docs` to the binary on localhost and denies the admin paths (D-29).
- Phase 11.2 depends on 11.1 being executed, because the docs build output feeds the embed step.
</code_context>
<specifics>
## Specific Ideas
- The page must look exactly like the handoff. "Final" means final, apart from the decided deviations (D-12, D-26, D-39).
- One visual identity across summercms.io, `/docs` and the admin: Direction C v2, dark navy and sunny yellow, with the sun.
- The terminal card must work when pasted into a fresh shell (D-39, D-40).
</specifics>
<deferred>
## Deferred Ideas
- Composing and sending newsletters, templates and the campaign CLI, ported from the PHP plugin in a later phase. That phase also merges confirmed subscribers with the user-based audience.
- CSV export of subscribers. It waits for a framework export or toolbar capability.
- Renaming `fonoteka.go` to `sm-fonoteka-app` is a separate task.
- Translating the docs into Polish.
- `go install git.golem15.com/golem15/summercms/cmd/summer@latest` as the install command. This needs the module path to be go-gettable (a public repo plus go-import meta).
- A CI pipeline that builds and publishes the binary, instead of local build and rsync.
- Making the database optional in `summer serve`, for apps without data.
### Reviewed Todos (not folded)
- "Nest framework packages under modules/" is already delivered by Phase 10.2.
- "Backend admin personal API tokens" is unrelated to the public site.
- "Extend fetchguard into a guarded outbound http.Client" is unrelated.
</deferred>
<phase_11_3_handoff>
## Carried to Phase 11.3: newsletter decisions (2026-09-29, verbatim, ignore when planning 11.2)
ROADMAP.md § Phase 11.3 points here. When 11.3 is discussed, these move into `11.3-CONTEXT.md`.
- **Repo:** `sm-newsletter-plugin` is the reusable signup plugin, with Go package `newsletter`, module path `git.golem15.com/golem15/sm-newsletter-plugin`.
- **D-06 (moved):** The site gains Polish (for example `/` and `/pl/`, via `@nuxtjs/i18n` as in `vue-fonoteka-app`). The confirmation and welcome mails are localized to the subscriber's locale through phrasebook/postcard. The 11.1 docs stay English-only.
### Signup and double opt-in
- **D-13:** Bot protection is a honeypot field, a minimum time-to-submit check and a per-IP `surf` rate-limit bucket. There is no captcha or third-party script.
@@ -54,93 +192,18 @@ summercms.io becomes shareable. A Nuxt 4 landing site in English and Polish runs
- **D-21:** An admin-added subscriber is created as pending with source=admin, and the normal confirmation mail is sent. Nobody lands on the list without their own confirmation.
- **D-22:** Composing and sending newsletters, templates and campaign CLI are out of scope.
### Claude's Discretion
- How long confirmation tokens stay valid and the resend throttle interval.
- Exact URL scheme for the API endpoints and localized result pages.
- Token format (random opaque token vs signed).
- Visual design within the Direction C v2 brand (dark navy + sunny yellow), copy wording and the exact page structure.
- How `sm-summercms-plugin` mounts the docs output, and whether the Nuxt build is embedded by the plugin or the root app.
### 11.3 discretion (from 2026-09-29)
- How long confirmation tokens stay valid and the resend throttle interval; token format (random opaque vs signed); exact URL scheme for the API endpoints and localized result pages.
</decisions>
### 11.3 references
- `/media/nvme/dev/golem15/horoskopia.eu/plugins/golem15/newsletter`: Golem15.Newsletter PHP (`github.com/golem15com/wn-newsletter-plugin`). Port source; do not modify.
- `/media/nvme/dev/golem15/figs.org.pl/plugins/figs/website`: working subscribe flow (`models/Subscriber.php`, `models/subscriber/{fields,columns}.yaml`, `components/subscribe/`, hash confirm/resign routes in `routes.php`).
- `modules/postcard`, `modules/phrasebook`, `modules/surf`, `modules/lagoon`, `modules/cabana`, `modules/pact` READMEs.
- 11.2 decision D-29 means `/backend` is not public yet. 11.3 must decide how the subscriber admin is reached (for example an IP allowlist or basic auth in nginx).
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Phase scope
- `.planning/ROADMAP.md` § Phase 11.2: goal, repos, naming convention, port source, success criteria.
- `.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-CONTEXT.md`: how the docs are built (`summer docs:build`, static output, `internal/docsite`). 11.2 serves that output at `/docs`.
- `.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-UI-SPEC.md`: the brand token values copied from the admin SPA. The site reuses the same palette.
### Port sources and references
- `/media/nvme/dev/golem15/horoskopia.eu/plugins/golem15/newsletter`: Golem15.Newsletter PHP (`github.com/golem15com/wn-newsletter-plugin`). It is the plugin identity and future sending model (`models/`, `classes/AudienceResolver.php`, `classes/UnsubscribeTokenGenerator.php`, `routes.php`). Do not modify it.
- `/media/nvme/dev/golem15/figs.org.pl/plugins/figs/website`: the site-plugin pattern (D-01). It also has a working subscribe flow: `models/Subscriber.php`, `models/subscriber/{fields,columns}.yaml`, `components/subscribe/`, and hash confirm/resign routes in `routes.php` that redirect to thank-you pages.
- `/media/nvme/dev/golem15/fonoteka/vue-fonoteka-app`: the Nuxt 4 + `@nuxtjs/i18n` setup to mirror for `vue-summercms-app`.
- `admin/src/styles/main.css` (`:root` and `.dark` blocks) and `.planning/phases/10-admin-vue-spa/design/README.md`: the Direction C v2 brand tokens.
### Framework modules used
- `modules/postcard/README.md`: confirmation and welcome mail templates.
- `modules/phrasebook/README.md`: EN and PL strings for mail and API messages.
- `modules/surf/README.md`: routes, named rate-limit buckets and body limits.
- `modules/lagoon/README.md`: per-plugin migrations and models.
- `modules/cabana/README.md`: YAML list and form for the subscribers admin.
- `modules/pact/README.md`: the plugin capability interfaces the two plugins implement.
- `modules/boardwalk/README.md`: the admin SPA handler. It is the reference for embedding and cache headers, and it must not be reused as-is for the public site (D-07).
- `../fonoteka.go`: the reference for app wiring (go.work, local replace, plugin registration).
</canonical_refs>
<code_context>
## Existing Code Insights
### Reusable Assets
- `postcard`: plugin-owned Markdown mail templates with memory, log and SMTP drivers. It covers the confirmation and welcome mails.
- `surf`: named rate buckets and trusted-proxy client IP. It covers the per-IP signup limit and gives the IP to store as consent evidence.
- `cabana` + admin SPA: YAML-driven list, form and filters. The subscriber admin needs no custom Vue.
- `lagoon`: GORM models, per-plugin gormigrate migrations and validation.
- `phrasebook`: namespaced EN and PL catalogs with fallback.
- `boardwalk`: its embed and cache-header handling is a pattern to copy into `sm-summercms-plugin`, but its admin security headers must not be.
### Established Patterns
- Plugins are compiled Go modules registered at build time (no runtime loading).
- Every application repo is a go.work workspace requiring the framework with a local replace, as `fonoteka.go` is.
- Framework READMEs never name a consuming application. The two new plugins are not framework modules, but `sm-newsletter-plugin` is reusable, so its README uses neutral examples too.
- Unit tests are the last plan of the phase. `go vet` and `go test ./...` stay green in every repo.
### Integration Points
- `sm-summercms-app` registers both plugins and serves `/`, `/docs`, `/backend` (admin) and the newsletter API from one mux.
- The Nuxt site calls the newsletter API with a same-origin fetch, so no CORS is needed.
- The 11.1 `summer docs:build` output feeds the embed step, so Phase 11.2 depends on 11.1 being executed.
</code_context>
<specifics>
## Specific Ideas
- The seasons lineage story: October, then Winter, now Summer (D-09).
- The site should feel like the admin and docs brand (Direction C v2: dark navy + sunny yellow), so summercms.io, `/docs` and `/backend` look like one product.
- Follow the figs.org.pl experience for confirmation: thank-you page, welcome mail and unsubscribe page.
</specifics>
<deferred>
## Deferred Ideas
- CSV export of subscribers. It waits for a framework export or toolbar capability; the user noted the framework doesn't have it ready.
- Composing and sending newsletters, templates and the campaign CLI, ported from the PHP plugin in a later phase. That phase also merges confirmed subscribers with the user-based audience.
- Renaming `fonoteka.go` to `sm-fonoteka-app` is a separate task, outside this phase.
- A source repo link on the landing page, once the repos are public.
- Translating the docs into Polish.
### Reviewed Todos (not folded)
- "Nest framework packages under modules/" is already delivered by Phase 10.2, and the match was keyword noise.
- "Backend admin personal API tokens" is unrelated to the public site.
- "Extend fetchguard into a guarded outbound http.Client" is unrelated, because the site makes no outbound fetches.
</deferred>
</phase_11_3_handoff>
---
*Phase: 11.2-ready-to-share-summercms-io-website-and-newsletter-plugin*
*Context gathered: 2026-09-29*
*Context gathered: 2026-09-29, updated 2026-10-01*

79
.planning/phases/11.2-ready-to-share-summercms-io-website-and-newsletter-plugin/11.2-DISCUSSION-LOG.md
View File

@@ -91,3 +91,82 @@
- Renaming fonoteka.go to sm-fonoteka-app.
- A source repo link on the landing page.
- Polish docs.
---
---
# Update 2026-10-01: Alpha 0.1 landing page
**Date:** 2026-10-01
**Phase:** 11.2, reshaped into "summercms.io Alpha 0.1 landing page on SummerCMS" (newsletter split into 11.3)
**Areas discussed:** Database at runtime, Server and deploy flow, Design to Nuxt, Get started accuracy, Docs and release
## Database at runtime
| Option | Description | Selected |
|--------|-------------|----------|
| Run Postgres on server | Stock serve path, no framework change | ✓ (already installed) |
| Make DB optional in framework | surf serve skips lagoon without DB config | |
| Site plugin's own serve cmd | DB-less command for / and /docs | |
**User's choice:** Postgres 15.19 is already installed and running on rome (Debian 12).
| Option | Description | Selected |
|--------|-------------|----------|
| Use PG 15 on rome as-is | Deploy against 15, docs keep 16 | |
| Upgrade rome to PG 16 | PGDG repo | |
| Verify on 15, then relax the docs | Run DB tests on 15, document "15 or newer" | ✓ |
| Option | Description | Selected |
|--------|-------------|----------|
| Dedicated role + database | `summercms` role, `summercms_io` DB, migrate per deploy | ✓ |
| Peer auth over Unix socket | No password, OS user = DB role | |
## Server and deploy flow
| Question | Options | Selected |
|----------|---------|----------|
| Build where | Locally + rsync / On rome from git / CI | Locally + rsync |
| /backend exposure | Not exposed / Exposed / Restricted | Not exposed |
| TLS | Existing certbot / Something else | Existing certbot |
| Cutover | Replace nginx block in place / Staging subdomain | Replace in place |
| Port and user | You decide / I'll specify | You decide |
## Design to Nuxt
| Question | Options | Selected |
|----------|---------|----------|
| Fonts | @nuxt/fonts self-host / Google CDN | @nuxt/fonts self-host |
| CSS | Plain CSS with tokens / Tailwind v4 | Plain CSS with tokens |
| Sun art | From live site / I'll provide / Placeholder | From live site: `http://summercms.io/logo.png` |
| i18n | @nuxtjs/i18n en only / Hardcoded | @nuxtjs/i18n en only |
| SEO | Basic meta + OG / Full @nuxtjs/seo / Meta only | Full @nuxtjs/seo (like fonoteka) |
| showRays/scrollSpy | Hardcode on / App config | App config |
## Get started accuracy
Finding: `git.golem15.com/golem15/summercms` requires login, and the terminal card had no clone step.
| Question | Options | Selected |
|----------|---------|----------|
| Source repo | Make public at launch / Hide links / Public mirror | Make public at launch |
| Terminal copy | Add a clone line / Keep verbatim / go install @latest | Add a clone line |
| Verify commands | Scripted check / Manual UAT | Scripted check |
## Docs and release
| Question | Options | Selected |
|----------|---------|----------|
| Docs → landing link | Optional `site_url` in site.yaml / Leave as-is | Optional `site_url` |
| Release tag | Tag framework v0.1.0 / Track master | Tag v0.1.0 |
| Repo home | Sibling of summercms.go / Also meta-repo submodule | Sibling of summercms.go |
## Claude's Discretion (2026-10-01)
- The port, system user and paths on rome; where the embeds live (plugin or root app); 404 handling; image derivatives and the OG layout; where the command check lives; reduced-motion handling.
## Deferred Ideas (2026-10-01)
- `go install ...@latest` as the install path (needs a go-gettable module path).
- A CI build pipeline.
- An optional DB in `summer serve`.