visual-artifacts v1: PR 5 public docs framing#221
Merged
Conversation
Adds a "Visual artifacts" section to every public surface that
describes Nanostack, and locks the framing with a new
visual-artifact-public-copy lint job. Last PR of the round.
Updated files:
- README.md: new "Visual artifacts" subsection inside the Know-how
block, after "Sprint journal on /ship". Frames the renderer as an
optional, local, deletable inspection layer. JSON canonical, HTML
derived.
- README.es.md: matching Spanish section ("Artifactos visuales")
with the same shape and CLI examples.
- llms.txt: new "Visual artifacts" paragraph for AI-facing
discovery surfaces.
- AGENTS.md: new "Visual artifacts" entry in the inventory.
- bin/about.sh: render-artifact.sh listed in the Key Scripts table;
visual artifacts mentioned in the State block.
Framing locks:
- Renderer is offline (CSP blocks external network, no fetch).
- --strict fails on integrity_missing / integrity_mismatch.
- --interactive is copy-only on /plan and /review.
- The HTML is optional inspection; removing .nanostack/visual/
does not change skill behavior or sprint state.
CI lock (.github/workflows/lint.yml: visual-artifact-public-copy):
- Bans cloud / SaaS / hosted-viewer / attestation /
certified-release / enterprise-grade framing in any paragraph
that mentions render-artifact, visual artifact, or
.nanostack/visual. The check uses a 10-line window around each
mention so legitimate uses elsewhere in the file are not affected
(e.g. README's pre-existing "not a compliance certification"
paragraph about the compliance-release example).
- Requires every public surface (README, README.es, llms.txt,
AGENTS, reference contract) to mention render-artifact.sh so the
docs cannot drift back to JSON-only framing.
Codex PR 5 pass 1 finding (P2). reference/visual-artifact-contract.md was written during PR 1 and never updated, so the public README's new "Visual artifacts" section linked to a doc that still listed journal --today (PR 3), stack <name> (PR 3), and --interactive (PR 4) as "reserved" with exit 2. Readers following the link saw contradictory CLI instructions. Rewrite the contract document end to end: - CLI section now documents the three forms (phase, journal, stack) and the live behavior of every flag. - Exit codes drop the stale "reserved" rows and add the actual failure modes (unsafe output, malformed stack name). - Store layout adds the stack/<name>/ directory and the PID suffix in filenames. - Manifest schema reflects the synthetic-source convention for invalid/not-found stack renders and the multi-source aggregation for journal/stack kinds. - New sections: multi-store trust scope (project-local vs shared), stack graph validation (6-step jq + bash check), interactive copy-only contract (forbidden APIs, < -> < escape). - Determinism section captures the PID-stem collision fix and the lexical path normalization that defeats symlink-+-.. attacks. No code changes; doc-only update so the contract matches the shipped behavior.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Last PR of the Visual Artifacts v1 round. Adds a "Visual artifacts" section to every public surface that describes Nanostack, refreshes
reference/visual-artifact-contract.mdto reflect the shipped behavior, and locks the framing with a new CI job.What changed
Public framing
README.md: new "Visual artifacts" subsection inside the Know-how block (after "Sprint journal on /ship"). Frames the renderer as an optional, local, deletable inspection layer with the four key examples (phase / journal / stack / --interactive).README.es.md: matching Spanish section "Artifactos visuales" with the same shape and CLI examples.llms.txt: new "Visual artifacts" paragraph for AI-facing discovery surfaces.AGENTS.md: new "Visual artifacts" entry in the inventory.bin/about.sh:render-artifact.shlisted in the Key Scripts table; visual artifacts mentioned in the State block.reference/visual-artifact-contract.md: rewritten end-to-end so it reflects PR 2-4 reality (journal/stack live, --interactive copy-only). The old PR 1 version still listed them as "reserved" with exit 2.Framing locks (
visual-artifact-public-copyjob in.github/workflows/lint.yml)cloud viewer,hosted viewer,SaaS viewer,cloud dashboard,attestation,certified release,enterprise-gradeetc. inside any paragraph that mentionsrender-artifact,visual artifact, or.nanostack/visual.render-artifact.shso the docs cannot drift back to JSON-only framing.Codex review trail (2 passes, clean)
reference/visual-artifact-contract.mdend to endTest plan
python3 -c "import yaml; yaml.safe_load(open('.github/workflows/lint.yml'))"passesrender-artifact.shbin/about.sh --printshows the new row cleanly (no escape artifacts)