Add one trustworthy workflow figure to the docs companion

PRD Summary

User

the technical operator reading the "Ship a repo change with review and gates" workflow before using or reviewing Harness Kit.

Problem

the workflow depends on delegation receipts, evidence, gates, and clean-tree closeout. In prose alone, that path is easy to skim past and hard to inspect quickly.

Why now

087 is shaping broader design-contract discipline. This ticket can prove the smaller docs-image primitive first.

UX enabled

the reader gets one visual map of the workflow, plus the same source-of-truth text in HTML and llms.txt.

Deliverable type

working code plus generated docs artifact.

Success signal

docs build and checker self-test prove the image is declared, copied, accessible, text-backed, size-bounded, and removable without any API call in CI.

Product Requirements

P0

add exactly one figure to the existing "Ship a repo change with review and gates" workflow page.

P0

keep text authoritative. The page must still explain the workflow without the image.

P0

keep builds deterministic and offline. CI validates committed files; it never calls an image-generation API.

P0

enforce alt text, a text-equivalent anchor, source policy, review note, file path, and a 250 KiB default size cap.

P0

fail on missing files, undeclared images, unused declarations, bad paths, missing alt/text/provenance, size overflow, stale output, and source/generated byte drift.

P1

record enough provenance for a future operator to regenerate or delete the figure without guessing.

Non-goals

no runtime generation, no new docs framework, no image across the catalog, no /design scaffold, no HTML-as-canonical-source doctrine change.

Technical Design

Chosen architecture

add one images entry to docs/copy/site.json, store one reviewed source asset under docs/copy/images/, copy it to docs/site/assets/images/, and render a <figure> with a nearby text-equivalent block.

Files/systems touched

docs/copy/site.json, docs/copy/images/, scripts/build-docs-site.py, scripts/check-docs-site.py, and generated docs/site/**.

Data/control flow

source JSON plus source image -> builder validation and byte copy -> generated workflow HTML, manifest.json, and llms.txt -> checker validation and stale-site comparison.

Build/check boundary

the builder validates shape and copies bytes; the checker owns negative fixtures, undeclared/unused detection, metadata completeness, byte equality, size/path budgets, and rollback proof.

ADR decision

not required for this slice because it extends the existing static docs companion. Require an ADR if image governance expands across many pages, HTML becomes source authority, runtime generation enters the build, or site.json stops being the docs-copy source.

Design X vs Y

choose a site.json image entry over Markdown-only, Mermaid-only, sibling manifest, runtime generation, and a full 087 merger. It is the smallest interface that proves the primitive and stays easy to delete.

Deliverable

Output

one manifest-declared source image, one generated workflow figure, one text-equivalent section, and builder/checker support.

Acceptance oracle

bash scripts/build-docs-site.sh, bash scripts/check-docs-site.sh --self-test, python3 scripts/check-agent-roster.py, and dagger call check --source=. pass.

Evidence artifacts

manifest row, source asset hash, generated page hash, generated manifest.json and llms.txt hashes, negative checker fixtures, and the browser-reviewed HTML PRD handoff.

Residual risk

the checker can prove contract coverage; a human still judges whether the figure is visually truthful and worth keeping.

Oracle

• [ ] docs/copy/site.json declares the single image with page target, purpose, source asset path, alt text, text-equivalent anchor, source policy, review note, max size, and regeneration reference.
• [ ] scripts/build-docs-site.py copies the committed source asset byte for byte and renders the figure plus text-equivalent block.
• [ ] scripts/check-docs-site.py --self-test fails for missing source files, undeclared <img> tags, unused declarations, empty alt text, missing text-equivalent anchors, missing source policy/review note, over-budget assets, invalid asset paths, stale output, and byte drift.
• [ ] Generated docs/site/manifest.json and docs/site/llms.txt still make the workflow understandable without the image.
• [ ] Removing the image entry and asset, rebuilding, and rerunning the docs check returns the page to a valid text-only form.
• [ ] bash scripts/build-docs-site.sh, bash scripts/check-docs-site.sh --self-test, python3 scripts/check-agent-roster.py, and dagger call check --source=. pass.