templates.ContentSite/README.md

# Content Site (Blog / Docs) — W4C project template

A W4C **project template**. Creating a project from it generates a private copy of this
repository in your namespace and starts the **Startup Creator** agent, which drives the build
from this brief.

This repository is deliberately a **brief, not a finished app**: it ships the product
specification, the project metadata and the seed assets; the tech stack chosen in the creation
dialog decides the scaffold. Read [`SPEC.md`](SPEC.md) for the full product contract — roles,
routes, content model, flows, functional and non-functional requirements, and the acceptance
criteria the work is checked against.

## What ships in this repository

| Path | Purpose |
|------|---------|
| `README.md` | This file: how the template is wired and how to work in the project. |
| `SPEC.md` | The product specification and acceptance criteria — the contract to build. |
| `.gitignore` | Default ignores for dependencies, build output, local secrets and editor/OS cruft. |
| `.editorconfig` | Shared editor defaults (UTF-8, LF, indentation) for the generated project. |
| `.w4c/template.json` | Template manifest: dialog fields, starter prompt, element list (templates only). |
| `.w4c/project.json` | Project metadata committed with the repository. |
| `.w4c/diagrams/` | Excalidraw architecture diagram. |
| `.w4c/boards/roadmap.json` | Board columns and the seed tasks for the build. |
| `.w4c/workflows/` | The CI workflow to import into the workflows module. |

See [`.w4c/README.md`](.w4c/README.md) for the full `.w4c/` contract.

## Stack

The creation dialog records the chosen stack (and its skill pair `stack-*` +
`stack-*-quality`). Scaffold with those skills and hold the work to their conventions and
quality gates. The stack is not fixed here on purpose: the same brief is built on Astro,
Nuxt 3, Next.js, Vue 3 + Quasar, Phoenix, … without changing `SPEC.md`. Prefer a stack that can
emit **static output** for the published routes.

## Build order

Work **top-down**, one layer at a time, and verify each layer before starting the next:

1. **Scaffold** the stack and get the empty shell running (install → dev server → commit).
2. **Content model + typed validation** — `SPEC.md` §4; a bad entry must fail the build.
3. **Layouts + navigation** from seeded content (§3).
4. **SEO / feed / sitemap** — metadata, canonical URLs, JSON-LD, sitemap, RSS, OG images.
5. **Search & related content.**
6. **Authoring workflow** — `<cms>` wiring, roles, draft → review → publish, scheduling.
7. **Quality / performance** — tests, CI, README quickstart, `.env.example`, Lighthouse budget,
   accessibility.

The full rationale and the acceptance criteria live in `SPEC.md` §8–§9.

## Working rules

- One concern per commit, conventional messages (`feat:`, `fix:`, `chore:`, `docs:`, `test:`).
- The content model is the source of truth: validate front-matter at build time and fail loudly,
  never render an entry that does not match its `ContentType`.
- Never ship draft, in-review or scheduled entries to production, the sitemap or the feed.
- Every route gets a unique title, description and absolute canonical URL.
- Keep published routes static and free of client JavaScript unless the page is interactive.
- Never commit secrets — document them in `.env.example` instead.
- Keep `docs/PLAN.md`, the board and `.w4c/project.json` in sync as the project evolves.