visual-artifacts v1: PR 5 public docs framing

.github/workflows/lint.yml

@@ -3782,3 +3782,61 @@ jobs:
         run: ci/check-visual-artifact-templates.sh
       - name: End-to-end render contract
         run: ci/e2e-visual-artifacts.sh
+
+  visual-artifact-public-copy:
+    # Locks the public framing introduced in PR 5: visual artifacts are
+    # "inspectable local evidence", JSON canonical, HTML derived. No
+    # cloud/SaaS/certification language allowed inside any paragraph
+    # that mentions render-artifact.sh, visual artifacts, or
+    # .nanostack/visual.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Public copy is locally-framed and modest
+        run: |
+          set -e
+          # Files that may speak publicly about visual artifacts.
+          FILES=(README.md README.es.md llms.txt AGENTS.md reference/visual-artifact-contract.md)
+          # Words that misrepresent the local-only, optional nature of
+          # the renderer. The check pulls a 10-line window around every
+          # render-artifact / visual artifact mention so the lint only
+          # fires when the banned word actually appears in the context
+          # that frames the renderer publicly.
+          BAD_WORDS='cloud viewer|hosted viewer|SaaS viewer|cloud dashboard|cloud render|cloud-rendered|cloud-based viewer|attestation|certified release|enterprise[- ]grade'
+          fail=0
+          for f in "${FILES[@]}"; do
+            [ -f "$f" ] || continue
+            # Extract a 10-line window around every renderer mention.
+            window=$(grep -niE -A10 -B2 'render-artifact|visual artifact|\.nanostack/visual' "$f" 2>/dev/null || true)
+            if [ -z "$window" ]; then continue; fi
+            if printf '%s\n' "$window" | grep -niE -- "$BAD_WORDS" >/dev/null 2>&1; then
+              echo "FAIL: $f has a banned framing word in a visual-artifact paragraph."
+              printf '%s\n' "$window" | grep -niE -- "$BAD_WORDS"
+              fail=1
+            fi
+          done
+          [ "$fail" = "1" ] && exit 1
+          echo "OK: visual artifact public copy stays local-first and modest."
+
+      - name: Visual artifact section present in public surfaces
+        run: |
+          set -e
+          # The public surfaces must each at least *acknowledge* the
+          # renderer once so the docs do not drift back to JSON-only
+          # framing. Codex PR 5 anchor.
+          for pair in \
+              "README.md|render-artifact" \
+              "README.es.md|render-artifact" \
+              "llms.txt|render-artifact" \
+              "AGENTS.md|render-artifact" \
+              "reference/visual-artifact-contract.md|render-artifact"; do
+            file="${pair%|*}"
+            needle="${pair#*|}"
+            if ! grep -qF "$needle" "$file"; then
+              echo "FAIL: $file does not mention $needle. Update the public copy when PR 5 framing changes."
+              exit 1
+            fi
+          done
+          echo "OK: every public surface mentions render-artifact."

AGENTS.md

@@ -40,6 +40,10 @@ Custom stacks declare their own phases in `.nanostack/config.json` (`custom_phas
 
 Skills automatically save artifacts to `.nanostack/`. Downstream skills read upstream artifacts through `bin/resolve.sh`, which honors the artifact-trust contract (PR 2) and the routing contract for custom skills (PR 5). `/ship` generates a sprint journal. `bin/discard-sprint.sh` cleans up bad sessions.
 
+## Visual artifacts
+
+`bin/render-artifact.sh` produces local HTML views of any phase artifact, sprint journal, or custom stack DAG under `.nanostack/visual/`. JSON stays canonical; the HTML is a derived, deletable inspection layer. The renderer is offline (no external scripts, no fetch, no storage) and supports `--strict` for integrity-verified rendering plus `--interactive` for copy-only clipboard buttons on `/plan` and `/review`. Contract: `reference/visual-artifact-contract.md`.
+
 ## Usage
 
 Each skill's `SKILL.md` contains the full instructions. Read it and follow the process described. Supporting files (templates, references, checklists, scripts) live in subdirectories and are referenced from the SKILL.md when needed.

README.es.md

@@ -276,6 +276,28 @@ Un equipo de marketing arma `/audience` y `/campaign`. Un equipo de datos arma `
 
 Walkthrough completo: [`EXTENDING.md`](EXTENDING.md).
 
+## Artifactos visuales
+
+Cada artefacto de fase es JSON. El JSON es lo que leen los skills, lo que firma el hash de integridad y lo que agrega el sprint journal. Esa capa es la canónica.
+
+Encima de eso, `bin/render-artifact.sh` produce una vista HTML local de cualquier artefacto para que un humano pueda inspeccionar la misma evidencia en el navegador:
+
+```bash
+bin/render-artifact.sh plan --latest         # último /nano
+bin/render-artifact.sh review --latest       # /review con contadores de severidad
+bin/render-artifact.sh security --latest     # OWASP / STRIDE
+bin/render-artifact.sh journal --today       # timeline del sprint
+bin/render-artifact.sh stack compliance-release  # DAG del workflow custom
+```
+
+El output queda en `.nanostack/visual/` al lado del JSON que lo originó. Cada render escribe un manifest que registra path origen, integridad SHA-256, timestamp y versión del renderer. Podés borrar el HTML cuando quieras: el JSON no cambia y la vista se regenera.
+
+El renderer es offline: cada página trae su propio CSS, el Content-Security-Policy bloquea la red externa, no se cargan fonts ni scripts de CDN. El flag `--strict` falla si algún artefacto fuente tiene la integridad rota (`integrity_mismatch`) o sin firmar (`integrity_missing`).
+
+`--interactive` suma botones de copia en `/plan` y `/review` (copy as prompt, copy as Markdown, copy as JSON patch). Usan solo el clipboard local. Sin escrituras a disco, sin llamadas de red, sin form submission.
+
+Los artifactos visuales son una capa opcional de inspección. Nada depende de ellos: borrar `.nanostack/visual/` no cambia el comportamiento de ningún skill ni el estado del sprint. El contrato vive en `reference/visual-artifact-contract.md`.
+
 ## Privacidad
 
 Nanostack no tiene un servicio cloud propio. Guarda planes, artefactos, journals y know-how localmente en `.nanostack/`. No envía tu código, prompts, nombres de proyecto ni rutas de archivo a servidores de Nanostack. Tu proveedor de agente de IA puede procesar el contexto que le des; usá las opciones de privacidad de tu proveedor y tus propias políticas de datos para trabajo sensible.

README.md

@@ -668,6 +668,28 @@ When you run `/ship` and the PR lands, it automatically generates a sprint journ
 
 The journal reads every phase artifact from the sprint and writes one file with the full decision trail: what `/think` reframed, what `/nano` scoped, what `/review` found, how conflicts were resolved, what `/security` graded.
 
+### Visual artifacts
+
+Every phase artifact is JSON. JSON is what every skill reads, what trust verification hashes, what the sprint journal aggregates. That layer stays canonical.
+
+On top of it, `bin/render-artifact.sh` produces a local HTML view of any artifact so a human can inspect the same evidence in a browser:
+
+```bash
+bin/render-artifact.sh plan --latest         # render the latest plan
+bin/render-artifact.sh review --latest       # review with severity counters
+bin/render-artifact.sh security --latest     # OWASP / STRIDE breakdown
+bin/render-artifact.sh journal --today       # whole sprint timeline
+bin/render-artifact.sh stack compliance-release  # custom workflow DAG
+```
+
+Output lands under `.nanostack/visual/` next to the JSON it came from. Every render writes a companion manifest that records source path, source integrity, render timestamp, and renderer version. Delete a generated HTML file at any time; the JSON is unchanged and the view can be regenerated from it.
+
+The renderer is offline-only: every page ships its own CSS, the Content-Security-Policy header blocks external network, no fonts or scripts are loaded from a CDN. A `--strict` flag fails the render when any source artifact's SHA-256 integrity hash does not match (`integrity_mismatch`) or is missing (`integrity_missing`).
+
+`--interactive` adds copy-only buttons to `/plan` and `/review` views: copy as prompt, copy as Markdown, copy as JSON patch. The buttons use the local clipboard API only. No filesystem writes, no network calls, no form submission.
+
+Visual artifacts are an optional inspection layer. Nothing depends on them: removing `.nanostack/visual/` does not change skill behavior or sprint state. The contract lives in `reference/visual-artifact-contract.md`.
+
 ### Knowledge compounding on /compound
 
 After shipping, run `/compound` to document what you learned:

bin/about.sh

@@ -68,6 +68,7 @@ Local workflow framework for AI coding agents. The built-in sprint plus a framew
 | bin/sprint-metrics.sh | Git stats + cycle time (used by /think --retro and /nano). |
 | bin/doctor.sh | Know-how health check. |
 | bin/capture-failure.sh | Log what went wrong (no /compound needed). |
+| bin/render-artifact.sh <phase> | Render a local HTML view of any artifact under \`.nanostack/visual/\`. Optional, JSON stays canonical. |
 
 ## Custom workflow stacks
 
@@ -80,6 +81,7 @@ All data in \`.nanostack/\`:
 - Solutions: \`.nanostack/know-how/solutions/{bug,pattern,decision}/\`
 - Briefs: \`.nanostack/know-how/briefs/\`
 - Audit log: \`.nanostack/audit.log\`
+- Visual artifacts (optional): \`.nanostack/visual/\` (HTML views derived from JSON; safe to delete)
 
 There is no Nanostack cloud. Telemetry is opt-in and documented in \`TELEMETRY.md\`.
 

llms.txt

@@ -39,6 +39,10 @@ See `reference/custom-stack-contract.md` for the contract, `examples/custom-stac
 
 Every artifact written by `bin/save-artifact.sh` carries a SHA-256 integrity field. `bin/find-artifact.sh` has a `--require-integrity` flag for strict consumers, and `bin/resolve.sh` exposes per-upstream trust state in its `upstream_status` field (`verified`, `integrity_missing`, `integrity_mismatch`, `missing`, `not_applicable`).
 
+## Visual artifacts
+
+`bin/render-artifact.sh` produces a local HTML view of any phase artifact, sprint journal, or custom stack DAG. Output lands under `.nanostack/visual/` with a companion manifest recording the source artifact path, integrity, and renderer version. HTML is a derived, deletable view; JSON remains canonical. The renderer is offline (Content-Security-Policy locks every page, no external scripts or fonts). A `--strict` flag fails the render when any source has `integrity_missing` or `integrity_mismatch`. An `--interactive` flag adds copy-only clipboard buttons to `/plan` and `/review` (copy as prompt / Markdown / JSON patch); no filesystem writes, no network calls. The contract is in `reference/visual-artifact-contract.md`.
+
 ## Privacy
 
 There is no Nanostack cloud. Artifacts, journals, and analytics stay under `.nanostack/` on disk. Telemetry is opt-in and documented in `TELEMETRY.md`; the on-by-default behavior is no remote calls.