decision: provenance, alt-text, and render-manifest contract for Kris website assets

[WalksWithASwagger]

Summary

Ratify a provenance, alt-text, and render-manifest contract for any generated asset destined for Kris's public websites (kriskrug.co and Futureproof), before any website-asset pipeline is built.

Context

• Roadmap phase: Phase 1 / Phase 2 — asset quality and accessibility.
• Relevant files: a new docs/WEBSITE-ASSET-CONTRACT.md, plus the existing provenance surfaces lib/batch.py (_img_record builds run.json), lib/registry.py (AssetEntry), and the renderers under lib/renderers/.
• Current behavior: run.json records style, model, prompt, aspect_ratio, cost_estimate, provider, and reference_images, and AssetEntry adds source_url / source_run / approval_status. But image records capture no seed (seed is only recorded for video/keyframe jobs), and there is no alt-text: every alt= in the renderers (lib/renderers/viewer.py, library.py, media_suite.py) is an empty attribute. There is no accessible-caption pipeline.
• Desired behavior: maintainers approve a single contract that any website-bound asset must satisfy before publication.

Acceptance Criteria

• The contract defines the required provenance fields for a website-bound asset: style, model, prompt, seed, source_run, and approval_status.
• Alt-text is mandatory for every website-bound generated asset, with a defined storage location (registry field or manifest).
• A render-manifest schema is defined that binds an emitted website asset to its provenance record.
• The contract states that real photography is preferred and that any generated art is explicitly labelled as generated.
• No provider spend, image generation, or asset publication is part of ratifying this contract.

Tests / Evals

• Once ratified, a machine-readable schema fixture validates in the normal test suite using synthetic records only. No generation here.

Notes

• This is a decision / contract issue. needs-human: no implementation until maintainers ratify.
• Pairs with the synthetic-evaluation contract (decision(evals): ratify a privacy-safe model-output benchmark contract #335) and the style-separation tests.

[WalksWithASwagger]

DRAFT FOR REVIEW — not ratified (2026-08-02)

Proposed provenance + alt-text + render-manifest contract for any generated asset bound for Kris's public sites (kriskrug.co, Futureproof). Draft only — no pipeline is built until ratified.

Principle

Real photography is preferred. Generated art is a fallback, must be labelled as generated, and may not ship to a public site without a complete manifest entry.

1. Required provenance fields (per website-bound asset)

Field	Notes
style	resolved style key (e.g. kriskrug) — must match an approved lane
model / provider	e.g. gemini-2.5-flash-image / gemini
prompt	full prompt text
seed	NEW — currently unrecorded for images; required for reproducibility
source_run	run dir / run.json id that produced it
approval_status	pending → approved (human) before publish
is_generated	bool; true assets carry a visible/label credit

2. Alt-text (mandatory)

Every website-bound asset MUST carry non-empty alt_text (today all renderer alt= are empty). Stored on the registry AssetEntry (new field) and emitted into any HTML/manifest. Human-authored or reviewed; no publish without it.

3. Render-manifest schema (binds asset ⇄ provenance)

{
  "asset_id": "string",
  "file": "relative/path.png",
  "alt_text": "string (required, non-empty)",
  "provenance": { "style": "...", "model": "...", "provider": "...",
                  "prompt": "...", "seed": 0, "source_run": "...",
                  "is_generated": true, "approval_status": "approved" },
  "target": { "site": "kriskrug.co|futureproof", "slot": "..." }
}

Validated by a schema fixture in the normal test suite (synthetic records only).

Open questions for Kris: is seed capture worth the image-pipeline change? who authors alt-text (you vs. reviewer)? should approval_status=approved be a hard publish gate?

[WalksWithASwagger]

PROPOSAL v2 — ratification-ready (awaiting Kris) — 2026-08-02

Refines the DRAFT above, corrected against the actual pipeline. No pipeline is built by this comment. Principle stands: real photography is preferred; generated art is a labelled fallback and may not reach a public site without a complete, approved manifest entry.

What the code already gives us (open questions resolved)

• run.json already records most provenance. lib/batch.py _img_record stores model, provider (when present), style, aspect_ratio, resolution, quality, prompt, file, timestamps; run_meta adds run_id, prompt_file/prompt_source. Only seed is absent.
• seed is not achievable on the image path today, and shouldn't be a publish gate. lib/core.py generate_image() returns a bool and never passes or receives a seed; lib/providers/gemini.py and lib/providers/openai_provider.py generate() likewise (grep for seed in lib/providers/ → nothing). The only seed plumbing is the Replicate keyframe/video path (lib/keyframe_jobs.py generates and records a random seed; lib/frontend_state.py reads it). Gemini flash-image / gpt-image expose no deterministic seed.
  → Resolution: seed is optional / nullable — recorded only where the provider returns one (keyframe path), null for Gemini/OpenAI image. Image-path reproducibility is anchored on the already-recorded source_run + prompt + model + style + aspect_ratio. Do not block publish on seed.
• AssetEntry already has the approval field the draft called "new". lib/registry.py AssetEntry already defines approval_status, style, model, aspect_ratio, source, source_run, source_prompt; the loader sets approval_status="approved" when source=="approved". So the publish gate reuses existing approval_status — it is not a new field. The genuinely missing fields are alt_text and is_generated (plus optional provider, optional seed).
• All renderer alt= are empty — confirmed. lib/renderers/viewer.py:767,1015,1098, lib/renderers/library.py:2984, lib/renderers/media_suite.py:547,650. These are the exact sites that must emit alt_text for website-bound output.

1. Provenance fields per website-bound asset

Field	Source	Status
style	AssetEntry.style / run.json	exists
model / provider	AssetEntry.model / run.json.provider	exists (add provider to AssetEntry)
prompt	AssetEntry.source_prompt / run.json.prompt	exists
source_run	AssetEntry.source_run / run.json.run_id	exists
approval_status	AssetEntry.approval_status	exists — reuse as publish gate
seed	keyframe path only	optional / nullable (add passthrough)
is_generated	NEW on AssetEntry	add (true for run.json-sourced art)
alt_text	NEW on AssetEntry	add (required non-empty to publish)

2. Alt-text (mandatory to publish)

AssetEntry gains alt_text: str = "". A website-bound asset MUST carry non-empty alt_text; renderers must emit it into every <img> (the 6 empty alt= sites above). Human-authored or human-reviewed — no publish without it.

3. Render-manifest schema (binds asset ⇄ provenance ⇄ alt ⇄ target)

{
  "asset_id": "string",
  "file": "relative/path.png",
  "alt_text": "string (required, non-empty)",
  "provenance": {
    "style": "kriskrug",
    "model": "gemini-2.5-flash-image",
    "provider": "gemini",
    "prompt": "full prompt text",
    "seed": null,
    "source_run": "run-YYYYMMDD-HHMMSS",
    "is_generated": true,
    "approval_status": "approved"
  },
  "target": { "site": "kriskrug.co|futureproof", "slot": "..." }
}

Validated by a schema fixture in the normal test suite (synthetic records only). Per docs/PROMPT-MEDIA-POLICY.md (public repo), any manifest referencing private source photos/paths stays out of the committed tree and the npm files allowlist.

4. Publish gates (all must hold before a generated asset reaches a public site)

1. alt_text non-empty.
2. approval_status == "approved" (existing field; no auto-approve).
3. is_generated == true assets ship with a visible generated-credit.
4. Real photography was preferred — generated art only where no rights-cleared photo exists (ties to styles/kriskrug.md "documentary fraud" clause: use real WP media for real events). Nothing here auto-publishes; a human clears each asset.

---

DECISION — RATIFY / REVISE / REJECT

1. seed — accept optional/nullable (recorded only where the provider returns it; not a publish gate)? (RATIFY / REVISE) — the draft's "required for reproducibility" is not feasible for Gemini/OpenAI image.
2. New AssetEntry fields — add alt_text (required to publish) and is_generated; reuse existing approval_status; add optional provider? (RATIFY / REVISE)
3. Alt-text authorship — Kris-only, or reviewer-allowed with your sign-off? (CHOOSE)
4. Hard publish gate — approval_status == "approved" AND non-empty alt_text required before any generated asset reaches kriskrug.co / Futureproof? (RATIFY / REVISE)

REJECT any part to send it back to draft.