diagram playbook local only · no network smoke fixture

How does open-visual resolve a dual-read visual?

Agents write a portable HTML figure plus a sibling Markdown outline. Humans review the HTML; agents trust the outline as SSOT. The engine opener resolves that pair locally and can print tips without launching a browser.

try devrites-engine open-visual engine/testdata/visual/open-visual-smoke.html --no-open

Overview

One concept: HTML + outline → opener tips.

HTML fixture pairs with outline SSOT; open-visual prints tips locally 1 HTML visual *.html · human review surface dual-read pair 2 Outline SSOT *.outline.md · agent truth tips + resolved path 3 open-visual engine command · local only On conflict, outline wins until both regenerate --no-open prints tips · never launches the browser

What each step does

Same story as the figure, in readable prose.

  1. Ship a dual-read pair

    Write visual/<name>.html for humans and visual/<name>.outline.md for agents — same claim, two surfaces.

  2. Treat outline as SSOT

    Inventory, relationships, and citations live in the outline. If HTML and outline disagree, the outline wins.

  3. Resolve with open-visual

    The engine finds the HTML (path or workspace name), warns if the sibling outline is missing, prints agent tips, and optionally opens the OS browser.

Legend

Symbols and guarantees for this fixture.

Arrow
Local resolve / tip print only — no fetch, CDN, or remote I/O.
Outline SSOT
Agent-facing source of truth for ids, relationships, and citations.
--no-open
Smoke path: resolve + tips print; browser launch is skipped.
Playbook
This page follows the diagram visual playbook landmarks.

Open questions

Uncertainty left for humans; mirrored in the outline + JSON embed.

Id Question
q-json-ssot Should agents ever prefer #devrites-outline JSON over .outline.md when both exist?
confidence: high status: open outline.md wins
q-browser-ci Do all interactive review hosts have a usable OS opener, or is --no-open the default smoke path?
confidence: medium status: open

Citations

Claims on this page map to repo paths.

Claim Path
Opener implementation engine/internal/lib/open_visual.go
Playbook router pack/.claude/skills/devrites-lib/reference/visual-playbooks/index.md
Outline template pack/.claude/skills/devrites-lib/reference/visual-playbooks/outline-template.md
Explain tip hook pack/.claude/skills/rite-explain/SKILL.md

Fixture path: engine/testdata/visual/open-visual-smoke.html