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

# Phase 11.2: Ready to share: summercms.io website and newsletter plugin - Context

**Gathered:** 2026-09-29
**Status:** Ready for planning

<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.

</domain>

<decisions>
## Implementation Decisions

### Repos and layout
- **D-01:** Four 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).

### 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.
- **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.

### 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.
- **D-14:** A required consent checkbox ("I agree to receive SummerCMS updates") links to a privacy note. The plugin stores the consent timestamp, IP and locale with the subscriber as GDPR evidence.
- **D-15:** Every signup gets the same neutral "check your inbox" response, and the response never reveals list membership:
  - pending: resend the confirmation, throttled
  - unsubscribed: new confirmation cycle
  - confirmed: no mail
- **D-16:** The confirm link is tokenized. On success it redirects to a localized thank-you page on the site and sends a welcome mail with the unsubscribe link, as `figs.org.pl` does. Invalid or expired tokens redirect to a localized error page.
- **D-17:** Unsubscribe is a tokenized link in every mail. It marks the subscriber unsubscribed and redirects to a localized "unsubscribed" page.

### Plugin shape
- **D-18:** Subscribers are standalone: the plugin has its own subscribers table and no dependency on the user plugin. Merging confirmed subscribers with a user-based audience (as the PHP `AudienceResolver` does) belongs to the later sending phase.
- **D-19:** The stub ships only the subscribers table, but with the fields sending will need: email, status (pending, confirmed, unsubscribed), locale, confirmation and unsubscribe tokens, `confirmed_at`, `unsubscribed_at`, source (form or admin), consent timestamp and IP, and timestamps. The newsletter, template and recipient tables are ported from PHP in the sending phase. — **Reversibility:** costly — the migration shape becomes the base that the sending phase extends.
- **D-20:** The admin backend (cabana YAML list and form) supports list, search, filters (status, locale), view, add, edit and delete. Delete is the GDPR erasure path.
- **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.

</decisions>

<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.2-ready-to-share-summercms-io-website-and-newsletter-plugin*
*Context gathered: 2026-09-29*