# Public Site Content Workflow

The public site is a generated documentation surface. The source of truth stays
in versioned documentation, while React renders a compact generated content
module.

## Source Of Truth

- `docs/site-manifest.json` defines the public-site navigation, source
  documents, section headings, launch links, and role labels used by the site.
- `README.md` and focused documents under `docs/` provide the public copy that
  appears on the site.
- `scripts/generate-site-content.js` reads the manifest and referenced
  markdown, validates headings, extracts concise public copy, and writes
  `site/src/generated-site-content.js`.
- `site/src/App.jsx` consumes `siteContent` from the generated module. It should
  not own long-form public copy, command lists, launch links, persona labels, or
  documentation summaries directly.

This keeps docs and site copy aligned. To change public site wording, update the
authoritative markdown or the manifest structure, then regenerate the site
content.

## Diagram Contract

The architecture diagram has two public sources that must stay aligned:

- `site/public/architecture.mmd` is the Mermaid file served by the React + Vite
  site.
- `docs/architecture.md` embeds the same Mermaid diagram for markdown readers
  and links back to the served source.

When the site diagram changes, update both files in the same task and validate
the rendered site. Diagram changes should follow the reusable quality rules in
`docs/diagrams/diagram-master-prompt.md`: readable labels, visible connector
endpoints, contained text, balanced spacing, and a whole-canvas recheck after
each correction.

## Local Commands

Regenerate generated site content:

```bash
npm run site:content
```

Build the public site:

```bash
npm run site:build
```

Run the local public site:

```bash
npm run site:dev
```

The `site` workspace also regenerates content before `npm run dev` and
`npm run build`, so local preview and production builds use the same generated
content path.

## Required Review

Use Technical Writer review for work that touches user-facing documentation or
site copy. The existing `technical_writer` role owns user docs, technical docs,
runbooks, release notes, help content, support-facing copy, and documentation
blocking authority.

Technical Writer review is required when a task changes:

- `README.md`;
- public docs under `docs/`;
- changelog or release notes;
- public site copy, launch links, command examples, or persona labels;
- help content, runbooks, migration guidance, or support-facing docs.

The workflow phase planner recommends `docs_review` for docs, README,
changelog, public site, site copy, and help-content changes. The review should
confirm audience fit, source-of-truth ownership, link correctness, command
accuracy, generated-content alignment, and whether release notes are needed.

## QA Evidence

For public site or docs-driven content changes, attach evidence for:

- `npm run site:build`;
- `npm run lint` when code, generated files, or docs formatting are touched;
- `npm run build` when package-level build contracts may be affected;
- Playwright screenshots for desktop and mobile when layout, diagrams, or
  visible site content changes;
- manual visual review of responsive spacing, text wrapping, diagram rendering,
  and horizontal overflow.

If a visual issue is found, fix it, regenerate content if needed, re-render, and
capture fresh screenshots before handoff.