# Phase 11.1: SummerCMS documentation for humans and AI agents - Context

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

<domain>
## Phase Boundary

A proper documentation set for the SummerCMS framework, modelled on https://wintercms.com/docs, usable both by developers browsing a site and by AI agents reading raw files. It runs after the core framework is complete (Phase 11) and before the application port phases (12–15), so it documents the framework as it stands at the end of Phase 11.

Repo: summercms.go only.

In scope:
- A Markdown docs tree in `summercms.go/docs/`, the single source of truth.
- A static site built from it, with a WinterCMS-style layout.
- AI-facing outputs: `llms.txt`, `llms-full.txt` and a raw `.md` for every page.
- Code examples that are compiled and tested, so the docs cannot drift from the API.
- A "Coming from WinterCMS" concept map and a porting walkthrough that uses a neutral sample plugin.

Not in this phase:
- Hosting or deployment of the built site (the build produces a static directory; where it is served is a later decision).
- Documentation of the application (fonoteka.go) or any of its plugins.
- Rewriting module APIs to make them easier to document. If an API is awkward, the docs describe it and the gap is logged.

</domain>

<decisions>
## Implementation Decisions

### Source and build
- **D-01:** The source is Markdown with YAML frontmatter (title, description, section, order) under `summercms.go/docs/`. The files read well on the git host without the site build.
- **D-02:** A small Go generator renders the site: stdlib `html/template` plus `github.com/yuin/goldmark` for Markdown. The user approved goldmark in this discussion, which satisfies the CLAUDE.md dependency rule. Any further dependency (syntax highlighting such as chroma, a frontmatter parser beyond goccy/go-yaml) must be named in RESEARCH.md and confirmed at the plan-count checkpoint.
- **D-03:** The generator is exposed through the `summer` CLI (preferred `summer docs:build` and `summer docs:serve`, final names subject to research against existing bonfire command naming). It produces a self-contained static output directory. No Node or npm toolchain.
- **D-04:** The site layout follows wintercms.com/docs: a left sidebar grouped by section, an on-page table of contents, prev/next links, "edit this page" source links, client-side search over a generated JSON index (vanilla JS, no framework) and a dark mode. Research should record what the Winter docs actually offer and flag anything left out.

### AI-friendly outputs
- **D-05:** The build emits `llms.txt` (an index following the llms.txt convention) and `llms-full.txt` (every page concatenated in sidebar order) at the site root.
- **D-06:** Every rendered page is also published as clean Markdown at a predictable URL (page URL plus `.md`), without site chrome.
- **D-07:** Code examples are verified. Go snippets shown in the docs are compiled and run as part of `go test ./...`, either as `Example` functions included into pages by reference or as snippet files extracted and built by a test. Research picks one mechanism. A doc build fails if a referenced snippet is missing.

### Structure and content
- **D-08:** The sections mirror WinterCMS: Getting started/Setup, Architecture, Plugins, Backend (admin auth, forms, lists, relation manager, settings), Database (models, migrations, relations, casts, validation), Services (events, config, mail, i18n, jobs, realtime, search, storage, rate limiting, HTTP routing and auth groups), Console (CLI commands and scaffolding), and API reference. Module READMEs remain the per-package reference. The docs link to them or derive from them rather than duplicating them. Research decides which.
- **D-09:** A "Coming from WinterCMS" page maps Winter concepts to SummerCMS equivalents (for example Plugin.php to the Plugin interface, `fields.yaml` to the schema pipeline, Eloquent to GORM plus lagoon, and so on).
- **D-10:** A porting walkthrough takes a neutral sample WinterCMS plugin (`acme/blog`) through to a compiled SummerCMS plugin: models, migrations, routes, admin controller and a scaffolding command. Its code is verified under D-07.

### Accuracy rules (inherited from CLAUDE.md, applied to docs/)
- **D-11:** The docs never name a consuming application. Use "the application" or "host application" and neutral names such as `blog` or `acme`.
- **D-12:** Every identifier named in the docs must exist in the package. A checker verifies it (as `go doc ./modules/<name> <Identifier>` does for READMEs) and runs in the test suite. Internal links and anchors are checked too.
- **D-13:** From this phase on, a change to a module's exported API, config keys or CLI commands must update both the module README and the affected docs pages. Record this rule in CLAUDE.md's Documentation section as part of the phase.

### Claude's Discretion
- Exact page list within each section, URL scheme, theme styling (reuse the admin SPA's design tokens if convenient), search index format, and the generator's package location (for example `modules/<beach-name>` or `internal/docs`, following the existing naming convention).

### Plan-count checkpoint (2026-09-30)
- **D-14:** Six plans, per RESEARCH.md Q8: tracer (generator core to every output), site UX and accuracy gates, framework content A, framework content B, the `acme/blog` walkthrough, and unit tests last.
- **D-15:** Syntax highlighting uses `github.com/alecthomas/chroma/v2`, approved by the user at this checkpoint (overrides the research's stdlib-only recommendation). It is called from a small custom goldmark `NodeRenderer`; `yuin/goldmark-highlighting` stays rejected. This is the only new dependency; `go.mod` gains chroma/v2 and its transitive `dlclark/regexp2`, and the phase gate asserts no other module is added.
- **D-16:** The walkthrough code is an in-root package under `docs/examples/blog`, covered by root `go test ./...`, plus a scaffold-layout test.
- **D-17:** Raw pages sit beside their HTML pages (`/x/page.html` and `/x/page.md`). Config-key checking is deferred and noted in CLAUDE.md. The wristband default that names the consuming application is logged as a follow-up todo; its API does not change in this phase.

</decisions>

<specifics>
## Specific Ideas

- Reference model: https://wintercms.com/docs (structure, tone, sidebar navigation).
- Earlier structure proposal: the user chose "mirror Winter's sections" over a Diátaxis layout.
- Existing material to build on: the root README and the 18 module READMEs under `modules/` (around 2.1k lines), rewritten in quick task 260928-lf2.

</specifics>

<deferred>
## Deferred Ideas

- An agent skill or `AGENTS.md`/`CLAUDE.md` template for host applications. It was offered and not selected for this phase.
- Hosting and CI deployment of the site.
- Versioned docs (per framework release).

</deferred>