5vitl
diff --git a/‎.gitattributes‎
Lines changed: 6 additions & 0 deletions b/‎.gitattributes‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎.github/workflows/make-pdf-gate.yml‎
Lines changed: 3 additions & 1 deletion b/‎.github/workflows/make-pdf-gate.yml‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 0 deletions b/‎.gitignore‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎AGENTS.md‎
Lines changed: 1 addition & 0 deletions b/‎AGENTS.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 106 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 106 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 3 additions & 0 deletions b/‎README.md‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎TODOS.md‎
Lines changed: 38 additions & 0 deletions b/‎TODOS.md‎
Lines changed: 38 additions & 0 deletions
diff --git a/‎VERSION‎
Lines changed: 1 addition & 1 deletion b/‎VERSION‎
Lines changed: 1 addition & 1 deletion
@@ -37,3 +37,9 @@ bin/*        text eol=lf
 *.gif        binary
 *.ico        binary
 *.pdf        binary
+
+# The committed diagram-render bundle is hash-pinned (BUILD_INFO sha256);
+# a CRLF rewrite on Windows checkout would break the drift test and change
+# the content-addressed staged filename.
+lib/diagram-render/dist/*.html text eol=lf
+lib/diagram-render/dist/*.json text eol=lf
@@ -4,6 +4,8 @@ on:
     branches: [main]
     paths:
       - 'make-pdf/**'
+      - 'lib/diagram-render/**'
+      - 'test/diagram-render-drift.test.ts'
       - 'browse/src/meta-commands.ts'
       - 'browse/src/write-commands.ts'
       - 'browse/src/commands.ts'
@@ -81,7 +83,7 @@ jobs:
           which pdftotext && pdftotext -v 2>&1 | head -1 || true
 
       - name: Run make-pdf unit tests
-        run: bun test make-pdf/test/*.test.ts
+        run: bun test make-pdf/test/*.test.ts test/diagram-render-drift.test.ts
 
       - name: Run E2E gates (combined-features copy-paste + emoji render)
         env:
 
@@ -4,6 +4,9 @@ dist/
 browse/dist/
 design/dist/
 make-pdf/dist/
+# diagram-render ships its built bundle (offline-at-install premise, eng-review D2)
+!lib/diagram-render/dist/
+!lib/diagram-render/dist/**
 bin/gstack-global-discover*
 .gstack/
 .claude/skills/
 
@@ -104,6 +104,7 @@ End-to-end walkthrough: [docs/howto-ios-testing-with-gstack.md](docs/howto-ios-t
 | `/guard` | Activate both careful + freeze at once. |
 | `/unfreeze` | Remove directory edit restrictions. |
 | `/make-pdf` | Turn any markdown file into a publication-quality PDF. |
+| `/diagram` | English in, diagram out: mermaid source + editable .excalidraw + SVG/PNG, offline. |
 
 ## Build commands
 
 
@@ -1,5 +1,111 @@
 # Changelog
 
+## [1.58.0.0] - 2026-06-12
+
+## **Your documents grow diagrams. Mermaid and excalidraw fences render as real pictures,**
+## **and make-pdf now ships single-file HTML and Word output from the same markdown.**
+
+Put a ` ```mermaid ` fence in your markdown and `make-pdf` renders it as a crisp
+vector diagram, fully offline, with the source preserved for round-trips. A broken
+fence prints a loud red diagnostic block with the parse error, never silent raw
+code. The new `/diagram` skill goes the other way: describe a flow in English and
+get a triplet back, the mermaid source, an editable `.excalidraw` file you can open
+at excalidraw.com in the hand-drawn style, and rendered SVG + PNG. Images got the
+same care: local paths inline automatically and never truncate, phone photos
+downscale to print resolution instead of blowing up the file, and a wide small-text
+diagram promotes itself onto a vertically centered landscape page inside an
+otherwise portrait document. One markdown file now exports three ways:
+`--to pdf | html | docx`, where html is one self-contained file with zero network
+references. Type is bigger across the board (12pt body, 56pt cover titles), TOC
+links actually jump, and `--strict` turns missing, remote, out-of-tree, or
+oversized images into hard CI failures.
+
+### The numbers that matter
+
+Measured on this repo's README (5,940 words, lists, code, screenshots, one
+diagram fence) and the free gate suite. Reproduce: `make-pdf generate README.md
+--cover --toc` and `bun test make-pdf/test/`.
+
+| Metric | Before | After | Δ |
+|--------|--------|-------|---|
+| A mermaid fence in your PDF | raw code block | vector diagram | rendered |
+| Output formats from one markdown | 1 (pdf) | 3 (pdf, html, docx) | +2 |
+| Network requests at render time | up to 1 per remote image | 0 by default | sealed |
+| Wide-diagram handling | shrunk into portrait | own centered landscape page | rotated |
+| Free make-pdf gate tests | 121 | 189 | +68 |
+| README → 29-page PDF with diagram | n/a | 4.4s | one command |
+
+The sealed-network number is the one to notice: the mermaid and excalidraw
+runtimes are vendored into a 9.2MB sha-pinned bundle, so rendering works on a
+plane and a tracking pixel in pasted markdown fetches nothing.
+
+### What this means for your documents
+
+The diagram you describe in English stays editable forever: `/diagram` writes the
+source, you embed the source in markdown, and every export renders it fresh. Stop
+pasting screenshots of diagrams into documents. Run `/diagram` for the picture,
+` ```mermaid ` for the document, and `--to html` when the reader doesn't want a PDF.
+
+### Itemized changes
+
+#### Added
+- ` ```mermaid ` and ` ```excalidraw ` fences render as inline vector SVG in pdf
+  and html output (docx embeds them as 300dpi PNGs). Fence options: `title="..."` (caption + aria-label),
+  `render=false` (keep as code), `page=landscape|portrait` (orientation override).
+  Render failures produce a visible diagnostic block with the parse error.
+- `/diagram` skill: English in, editable triplet out (`.mmd` source,
+  `.excalidraw` scene, SVG + PNG). Flowcharts convert to fully editable
+  excalidraw scenes; other mermaid types render with an explicit limitation note.
+- `lib/diagram-render/`: vendored offline bundle (mermaid 11.12.2, excalidraw
+  0.18.0, exact pins), deterministic build, committed dist with sha256 + source
+  fingerprint, drift tests, THIRD-PARTY-LICENSES.
+- `--to pdf|html|docx` output formats. HTML is one self-contained file (inline
+  SVG diagrams, data-URI images, zero network refs, screen-readable). DOCX is a
+  content-fidelity export with diagrams embedded as 300dpi PNGs and alt text.
+- Per-image directives: `![x](a.png){width=full|50%|3in}` and
+  `{page=landscape|portrait}`.
+- Conservative auto-landscape: wide, small-text, diagram-like images get their
+  own vertically centered landscape page (aspect ≥ 1.8, width over ~2.5x the
+  content box, diagram-ish alt word). Directives override in both directions.
+- `--strict` for CI: missing images, remote images, out-of-tree image reads,
+  oversized files, and non-regular files fail the run instead of degrading to
+  placeholders.
+- `docs/howto-diagrams-and-formats.md`: the full walkthrough, fences to formats.
+
+#### Changed
+- Typography scale: 12pt body, 26pt h1, 56pt poster cover with 13pt meta, 12pt
+  TOC entries, larger code and tables. Auto-hyphenation is off so copy-paste
+  yields clean words.
+- Local images inline as data URIs with byte-probed dimensions and never
+  truncate; oversized photos downscale to print resolution at inline time;
+  repeated images are read once.
+- TOC links resolve in every format (headings get real anchor ids); the screen
+  layer hides print-only page-number dots in HTML output.
+- Remote images are blocked with a visible placeholder unless `--allow-network`
+  is passed; out-of-tree image reads (including via symlink) warn loudly.
+- `make-pdf preview` prints a note when the document contains fences or local
+  images that only `generate` renders fully.
+
+#### Fixed
+- Relative image paths render correctly in PDFs (previously resolved against the
+  wrong base and could show as broken boxes).
+- Fenced code inside lists survives the render byte-for-byte; indented fences
+  keep their list placement.
+- Documents containing `$&`-style sequences in diagram labels render exactly;
+  Windows drive-letter image paths resolve as local files; malformed
+  percent-encoded image URLs degrade gracefully instead of failing the run.
+- Per-side margins (`--margin-left` etc.) are honored on documents containing
+  landscape pages.
+
+#### For contributors
+- 68 new free-tier gates (fence extraction, image policy, landscape promotion
+  with negative fixtures, format contracts, bundle drift) plus a paid gate-tier
+  /diagram triplet test and a periodic authoring-quality judge.
+- make-pdf-gate CI now covers `lib/diagram-render/**` and the drift test; the
+  committed bundle is pinned to LF in .gitattributes.
+- Fixed the `operational-learning` E2E fixture (bin scripts now ship with the
+  lib module they import).
+
 ## [1.57.10.0] - 2026-06-10
 
 ## **Codex review now runs by default everywhere it matters.**
 
@@ -206,6 +206,8 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
 | `/autoplan` | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → eng review automatically with encoded decision principles. Surfaces only taste decisions for your approval. |
 | `/spec` | **Spec Author** | Turn vague intent into a precise, executable spec in five phases (why, scope, technical with mandatory code-reading, draft, file). Codex quality gate before file (blocks below 7/10), fail-closed secret redaction, dedupe against existing issues, archive to `$GSTACK_STATE_ROOT/projects/$SLUG/specs/` for team-corpus recall. `--execute` spawns `claude -p` in a fresh worktree; `/ship` auto-closes the source issue on merge. Plan-mode aware. |
 | `/learn` | **Memory** | Manage what gstack learned across sessions. Review, search, prune, and export project-specific patterns, pitfalls, and preferences. Learnings compound across sessions so gstack gets smarter on your codebase over time. |
+| `/make-pdf` | **Publisher** | Markdown in, publication-quality document out. Mermaid and excalidraw fences render as vector diagrams, fully offline. Images scale to the page and never truncate; wide diagrams get their own landscape page. `--to html` emits one self-contained file, `--to docx` a Word doc. |
+| `/diagram` | **Diagram Maker** | English in, editable diagram out. Emits a triplet: mermaid source, `.excalidraw` you can open and edit on excalidraw.com (hand-drawn style), and rendered SVG/PNG. Zero network. Embed the source in markdown and `/make-pdf` renders it. |
 
 ### Which review should I use?
 
@@ -429,6 +431,7 @@ Other references: [docs/gbrain-sync.md](docs/gbrain-sync.md) (sync-specific guid
 | Doc | What it covers |
 |-----|---------------|
 | [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill (includes Greptile integration) |
+| [Diagrams & Document Formats](docs/howto-diagrams-and-formats.md) | Mermaid/excalidraw fences in PDFs, image sizing and safety defaults, `--to html\|docx`, `/diagram` triplets |
 | [Builder Ethos](ETHOS.md) | Builder philosophy: Boil the Ocean, Search Before Building, three layers of knowledge |
 | [Using GBrain with GStack](USING_GBRAIN_WITH_GSTACK.md) | Every path, flag, bin helper, and troubleshooting step for `/setup-gbrain` |
 | [GBrain Sync](docs/gbrain-sync.md) | Cross-machine memory setup, privacy modes, troubleshooting |
 
@@ -2377,3 +2377,41 @@ Pre-existing in `auq-sdk-capture.ts` — affects `skill-e2e-ship-section-loading
 path to the fixture during the run.
 
 **Effort:** S (human ~3h, CC ~30min). **Depends on:** None.
+
+### P3: Content-hash diagram render cache for make-pdf
+
+**What:** Cache rendered diagram SVG/PNG in `~/.gstack/cache/diagram-render/`,
+keyed on `sha256(fence source + bundle version + render options)`, so repeat
+`make-pdf` runs skip the browse render tab for unchanged diagrams.
+
+**Why:** Every run currently re-renders every fence (~150-300ms each). Docs with
+10+ diagrams pay seconds per iteration during write-preview loops. Codex
+outside-voice flagged the missing cache story during the eng review of the
+diagram engine plan (2026-06-11, D7).
+
+**Context:** The diagram-render bundle ships a `BUILD_INFO.json` with a content
+hash (see `lib/diagram-render/`) — use that as the bundle-version cache key
+component so bundle bumps invalidate cleanly. Invalidation surface is the main
+risk: stale renders after a mermaid theme change must not survive. Only worth
+building once users hit multi-diagram docs; wedge perf is fine without it.
+
+**Effort:** S (human ~1d, CC ~30min). **Depends on:** diagram engine wedge
+shipping (lib/diagram-render bundle versioning).
+
+### P3: Dedupe the make-pdf e2e gate-test harness
+
+**What:** Five e2e files (`combined-gate`, `emoji-gate`, `diagram-gate`,
+`landscape-gate`, `format-gate`) each hand-roll the same prerequisite probe
+(binary/browse/poppler checks with CI hard-fail vs local skip), mkdtemp/rm
+lifecycle, and child-timeout constants. Extract a shared
+`make-pdf/test/e2e/helpers.ts` (prerequisites(), withWorkDir(), runGenerate()).
+
+**Why:** Review-army maintainability finding on v1.58.0.0 — the boilerplate
+diverges a little more with each new gate (diagram-gate now captures stderr
+via Bun.spawnSync while the others use execFileSync), and a future fix to the
+CI-hard-fail contract has to land five times.
+
+**Context:** Deferred at ship time (D8.2) because it's test-only churn across
+five green files at the tail of a release. Zero user-facing value; pure DRY.
+
+**Effort:** S (human ~3h, CC ~20min). **Depends on:** None.
@@ -1 +1 @@
-1.57.10.0
+1.58.0.0