# Showcase Generation Guide

## 2026-07-25 Current Authority

`docs/index.html` remains the repo-owned showcase/docs-hub surface; do not
create a competing `docs/showcase/` root. Its evidence note now follows
`.agents/specs/uat-production-readiness-convergence/review.md`.

- Lead with user outcomes; do not expose internal database, tenant, framework,
  or proof-harness jargon in benefit copy.
- Do not retain stale Cloud SQL, certificate-pending, revision, or screenshot
  claims as current facts.
- Until the convergence review closes, describe current readiness as an active
  hardening program and link evaluators to the executive review.
- Maintain `docs/SHOWCASE_DRAFT.md` as bilingual copy SSOT and this guide as
  the generation memo for the existing `docs/index.html`.

## Goal

This guide records how to maintain the public showcase and docs-site presentation without mixing marketing, manual, and review audiences.

The current repo-owned showcase surfaces are:

- `docs/index.html` — the documentation hub / showcase website entry point for prospects, operators, and evaluators.
- the live `showcase` site/tenant referenced by the hub and manual as the canonical product exemplar.
- `docs/manual/{en,zh-TW}/index.html` and `docs/review/index.html` — supporting operator/evaluator artifacts that the showcase may link to, but must not copy in tone.

## Audience Split

- **Showcase / docs hub:** potential users and stakeholders. Use benefit-led, outcome-first language. Keep the page clear enough for a non-operator to understand why the platform matters.
- **Manual:** operators. Use task flow, route, source-manifest, and proof-tier language.
- **Review:** decision makers and evaluators. Use evidence, claim boundaries, gap analysis, and readiness tiers.

Do not move review-style `claim-cap` wording into the public showcase body unless the section is explicitly an evidence note. Do not move aspirational marketing copy into the manual/review proof sections.

## Source Manifest

Before refreshing the showcase or docs hub, inspect and cite the actual inputs used:

1. `.agents/specs/SPECS.md`
2. `.agents/specs/RTM.md`
3. `.agents/specs/NEXT_STEPS.md`
4. relevant active spec `requirements.md`, `design.md`, `tasks.md`, `review.md`, and `reports/*.md`
5. `docs/*FEATURE*.md` when present
6. `docs/*SPEC*.md` when present, as historical or secondary context unless it is the freshest authority
7. `docs/MANUAL_GENERATION_GUIDE.md`
8. `docs/REVIEW_GENERATION_GUIDE.md`
9. `docs/PROJECT_REVIEW_GUIDE.md`
10. existing `docs/index.html`, `docs/manual/**/index.html`, and `docs/review/index.html`

As of the 2026-07-11 reconciliation pass, this repo has no `docs/*FEATURE*.md` files. The matching `docs/*SPEC*.md` surface is historical/secondary; current spec and RTM artifacts remain the authority for readiness and claim boundaries.

## Copy Rules

- Lead with outcomes: what a site owner, NGO, operator, or evaluator can achieve.
- Keep the `showcase` tenant framed as a canonical exemplar, not as internal tenancy machinery.
- Use concrete capabilities already supported by the manual/review source manifests: page builder, AI content generation, content management, MCP/agent-friendly surfaces, agent skills, A2UI, messaging/social flow, payments, and tutoring/learning demos.
- Do not invent adoption metrics, customer quotes, production proof, or external-provider proof.
- Use relative links for committed docs. Do not hard-code production domains in repo-owned HTML.
- If a link points to manual or review artifacts, label the target by audience: "Operator Manual", "Executive Review", or equivalent.

## Refresh Checklist

1. Update the source copy first: this guide, manual/review generation notes, or a spec-local review/report when those are the true source.
2. Update `docs/index.html` as the public/docs-site showcase surface.
3. Update `docs/manual/{en,zh-TW}/index.html` only with operator-facing notes and source-manifest changes.
4. Update `docs/review/index.html` only with evaluator-facing notes and evidence boundaries.
5. Reconcile `README.md`, `docs/README.md`, and `AGENTS.md` so future agents can find the guide.
6. Reconcile `.agents/specs/NEXT_STEPS.md` and `.agents/specs/RTM.md` when the refresh changes durable governance state.
7. Validate with `git diff --check` and, for HTML-only changes, at least a lightweight tag/link sanity check.

## 2026-07-11 Note

This pass added the guide as the durable memo requested by the owner and updated the docs hub, manual HTML, review HTML, README indexes, `AGENTS.md`, `NEXT_STEPS.md`, and `RTM.md`.

Claim boundary: documentation/static-host tier only. No new screenshots, runtime probes, production deployment, or UAT proof were gathered in this pass.