summercms/.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-CONTEXT.md

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

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

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

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

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

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