docs(11.1): insert documentation phase with context and validation strategy
This commit is contained in:
Jakub Zych
@@ -0,0 +1,72 @@
|
||||
# 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).
|
||||
|
||||
</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>
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
phase: "11.1"
|
||||
slug: "summercms-documentation-for-humans-and-ai-agents"
|
||||
# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6)
|
||||
# audit-milestone §5.5 distinguishes NOT-VALIDATED (draft) from PARTIAL (validated + nyquist_compliant: false) (#2117)
|
||||
status: draft
|
||||
nyquist_compliant: false
|
||||
wave_0_complete: false
|
||||
created: "2026-09-28"
|
||||
---
|
||||
|
||||
# Phase 11.1 — Validation Strategy
|
||||
|
||||
> Per-phase validation contract for feedback sampling during execution.
|
||||
|
||||
---
|
||||
|
||||
## Test Infrastructure
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Framework** | go test (stdlib `testing`) |
|
||||
| **Config file** | none. Tests locate `docs/` and `modules/` via relative paths from `internal/docsite` |
|
||||
| **Quick run command** | `go test -short ./internal/docsite/... ./cmd/summer/... ./docs/examples/...` |
|
||||
| **Full suite command** | `go vet ./... && go test ./...` (Docker required for walkthrough and lagoon DB tests) |
|
||||
| **Phase gate** | `scripts/check-phase11.1.sh --all` |
|
||||
| **Estimated runtime** | ~60 seconds (quick), several minutes (full with Docker) |
|
||||
|
||||
---
|
||||
|
||||
## Sampling Rate
|
||||
|
||||
- **After every task commit:** Run `go vet ./... && go test -short ./...`
|
||||
- **After every plan wave:** Run `go test ./...` plus `scripts/check-phase11.1.sh --docs --forbidden`
|
||||
- **Before `/gsd-verify-work`:** `scripts/check-phase11.1.sh --all` must be green, then manual UAT of search and dark mode
|
||||
- **Max feedback latency:** 60 seconds
|
||||
|
||||
---
|
||||
|
||||
## Per-Task Verification Map
|
||||
|
||||
Filled in by the planner once PLAN.md files exist. Requirement → test mapping from RESEARCH.md:
|
||||
|
||||
| Requirement | Behavior | Test Type | Automated Command | File Exists | Status |
|
||||
|-------------|----------|-----------|-------------------|-------------|--------|
|
||||
| DOCS-01 / SC1 | Strict frontmatter, section/dir match, unique order, H1 == title, every module in sidebar | unit | `go test ./internal/docsite -run 'TestContentTree\|TestEveryModuleInSidebar'` | ❌ W0 | ⬜ pending |
|
||||
| DOCS-02 / SC2 | Build emits html with sidebar, TOC, prev/next, edit link, search, theme toggle; assets embedded; no Node | unit + smoke | `go test ./internal/docsite -run TestBuildSite && go test ./cmd/summer -run TestToolCommandNames` | ❌ W0 | ⬜ pending |
|
||||
| DOCS-02 / SC2 | `go.mod` direct requires unchanged | gate | `scripts/check-phase11.1.sh --deps` | ❌ W0 | ⬜ pending |
|
||||
| DOCS-03 / SC3 | nav pages == html == md == llms.txt links == llms-full sources, in sidebar order; llms.txt spec shape | unit | `go test ./internal/docsite -run TestAIOutputsInSync` | ❌ W0 | ⬜ pending |
|
||||
| DOCS-04 / SC4 | Every go fence has `src=`, bodies equal sources, referenced Examples have Output, missing ref fails | unit | `go test ./internal/docsite -run TestSnippets` | ❌ W0 | ⬜ pending |
|
||||
| DOCS-04 / SC4 | Examples compile and run with valid names | toolchain | `go vet ./... && go test ./modules/...` | ❌ W0 | ⬜ pending |
|
||||
| DOCS-05 / SC4 | Identifier, link/anchor, CLI-name, forbidden-name checkers fail on planted violations and pass on the real tree | unit | `go test ./internal/docsite -run 'TestIdentifiers\|TestLinks\|TestCommands\|TestForbidden'` | ❌ W0 | ⬜ pending |
|
||||
| DOCS-06 / SC5 | "Coming from WinterCMS" page exists and its identifiers pass | unit | covered by `TestContentTree` + `TestIdentifiers` | ❌ W0 | ⬜ pending |
|
||||
| DOCS-07 / SC5 | `acme/blog` walkthrough compiles, registers, serves routes, migrates up/down, matches the scaffold layout | unit + integration | `go test ./docs/examples/...` | ❌ W0 | ⬜ pending |
|
||||
| DOCS-08 | CLAUDE.md carries the D-13 docs-update rule | gate | `scripts/check-phase11.1.sh --claude` | ❌ W0 | ⬜ pending |
|
||||
|
||||
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
|
||||
|
||||
---
|
||||
|
||||
## Wave 0 Requirements
|
||||
|
||||
- [ ] `internal/docsite/` package with test scaffolding and a `testdata/` planted-violation corpus
|
||||
- [ ] `modules/bonfire/example_test.go` — first verified snippet (tracer)
|
||||
- [ ] `docs/site.yaml`, `docs/index.md`, `docs/setup/installation.md`
|
||||
- [ ] `cmd/summer/docs.go` + `TestToolCommandNames` extension
|
||||
- [ ] `scripts/check-phase11.1.sh` with `--self-test`
|
||||
- [ ] `/site/` in `.gitignore`
|
||||
|
||||
---
|
||||
|
||||
## Manual-Only Verifications
|
||||
|
||||
| Behavior | Requirement | Why Manual | Test Instructions |
|
||||
|----------|-------------|------------|-------------------|
|
||||
| Client-side search returns relevant pages | DOCS-02 | No JS test runner without a Node toolchain | `summer docs:serve`, search for a module name and a CLI command, confirm results link correctly |
|
||||
| Dark mode toggles and persists | DOCS-02 | Visual | `summer docs:serve`, toggle theme, reload, confirm persistence and contrast per UI-SPEC |
|
||||
|
||||
---
|
||||
|
||||
## Validation Sign-Off
|
||||
|
||||
- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
|
||||
- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
|
||||
- [ ] Wave 0 covers all MISSING references
|
||||
- [ ] No watch-mode flags
|
||||
- [ ] Feedback latency < 60s
|
||||
- [ ] `nyquist_compliant: true` set in frontmatter
|
||||
|
||||
**Approval:** pending
|
||||
Reference in New Issue
Block a user