docs: apply Codex doc-review findings for v1.58.0.0

Cross-model doc review (Codex, read-only) checked the v1.58.0.0 docs
against the shipped code. Fixes:

- howto + make-pdf SKILL: diagram source is preserved base64 in a
  data-gstack-source attribute, not an HTML comment (-- in mermaid
  arrows would corrupt a comment); fences must start at column 0;
  fence options example gains page=portrait; --to html "zero network
  refs" qualified (--allow-network deliberately keeps remote tags).
- /diagram description, README + docs/skills.md rows: the hand-drawn
  aesthetic belongs to the .excalidraw artifact; rendered SVG/PNG use
  mermaid's clean neutral theme (lib/diagram-render entry.ts pins
  theme: "neutral").
- CHANGELOG v1.58.0.0 wording: --strict coverage lists all five fatal
  classes (missing/remote/out-of-tree/oversized/non-regular); fences
  are vector SVG in pdf+html, 300dpi PNG in docx; hand-drawn claim
  scoped to the .excalidraw file.
- lib/diagram-render/README: Page API table gains __downscaleRaster.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CHANGELOG.md

@@ -10,15 +10,15 @@ vector diagram, fully offline, with the source preserved for round-trips. A brok
 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, and rendered SVG + PNG in the hand-drawn style. Images got the
+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 or out-of-tree images into hard
+links actually jump, and `--strict` turns missing, remote, out-of-tree, or
-CI failures.
+oversized images into hard CI failures.
 
 ### The numbers that matter
 
@@ -49,8 +49,8 @@ pasting screenshots of diagrams into documents. Run `/diagram` for the picture,
 ### Itemized changes
 
 #### Added
-- ` ```mermaid ` and ` ```excalidraw ` fences render as inline vector SVG in every
+- ` ```mermaid ` and ` ```excalidraw ` fences render as inline vector SVG in pdf
-  output format. Fence options: `title="..."` (caption + aria-label),
+  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,
@@ -67,8 +67,9 @@ pasting screenshots of diagrams into documents. Run `/diagram` for the picture,
 - 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, and
+- `--strict` for CI: missing images, remote images, out-of-tree image reads,
-  oversized files fail the run instead of degrading to placeholders.
+  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

README.md

@@ -207,7 +207,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
 | `/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, and rendered SVG/PNG. Hand-drawn aesthetic, zero network. Embed the source in markdown and `/make-pdf` renders it. |
+| `/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?
 

diagram/SKILL.md

@@ -22,7 +22,8 @@ triggers:
 ## When to invoke this skill
 
 on excalidraw.com,
-and rendered SVG + PNG. Hand-drawn excalidraw aesthetic, fully offline.
+and rendered SVG + PNG (clean mermaid style; the .excalidraw carries the
+hand-drawn aesthetic). Fully offline.
 Use when asked to "make a diagram", "draw the architecture", "create a
 flowchart", "diagram this", or "visualize this flow".
 

diagram/SKILL.md.tmpl

@@ -4,7 +4,8 @@ version: 1.0.0
 description: |
   Turn an English description (or mermaid source) into a diagram triplet:
   the source, an editable .excalidraw file you can open on excalidraw.com,
-  and rendered SVG + PNG. Hand-drawn excalidraw aesthetic, fully offline.
+  and rendered SVG + PNG (clean mermaid style; the .excalidraw carries the
+  hand-drawn aesthetic). Fully offline.
   Use when asked to "make a diagram", "draw the architecture", "create a
   flowchart", "diagram this", or "visualize this flow". (gstack)
 allowed-tools:

docs/howto-diagrams-and-formats.md

@@ -24,7 +24,10 @@ make-pdf generate doc.md out.pdf
 
 The fence renders as a **vector** diagram (crisp at any zoom, selectable
 text), with the `title` as caption and accessibility label. The raw mermaid
-source is preserved in an HTML comment inside the document for debugging.
+source is preserved base64-encoded in a `data-gstack-source` attribute on the
+figure for debugging and round-trips (an HTML comment would corrupt mermaid's
+`-->` arrows). One catch: the fence must start at **column 0** — indented
+fences (inside lists, for example) stay plain code blocks by design.
 
 **Fence options** (space-separated in the info string):
 
@@ -83,8 +86,10 @@ make-pdf generate doc.md out.docx --to docx
 ```
 
 - **`--to html`** writes ONE self-contained file: diagrams as inline SVG,
-  images as data URIs, zero network references, plus a screen-reading layer
+  images as data URIs, zero network references (under the default offline
-  (centered measure, padding). Email it, attach it, open it anywhere.
+  posture — `--allow-network` deliberately keeps remote image tags live),
+  plus a screen-reading layer (centered measure, padding). Email it, attach
+  it, open it anywhere.
 - **`--to docx`** is a content-fidelity export: headings, tables, code
   blocks, lists, and diagrams (embedded as 300dpi PNGs with alt text) carry
   over. Page-perfect layout does not — that's Word's job once it's open.

docs/skills.md

@@ -56,7 +56,7 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
 | [`/setup-deploy`](#setup-deploy) | **Deploy Configurator** | One-time setup for `/land-and-deploy`. Detects your platform, production URL, and deploy commands. |
 | [`/gstack-upgrade`](#gstack-upgrade) | **Self-Updater** | Upgrade gstack to the latest version. Detects global vs vendored install, syncs both, shows what changed. |
 | [`/make-pdf`](#make-pdf) | **PDF Generator** | Turn any markdown file into a publication-quality PDF. Proper margins, page numbers, cover pages, clickable TOC. Mermaid/excalidraw fences render as vector diagrams; `--to html\|docx` for other formats. |
-| [`/diagram`](#diagram) | **Diagram Maker** | English in, diagram out: mermaid source + editable `.excalidraw` (open it on excalidraw.com) + rendered SVG/PNG. Hand-drawn aesthetic, fully offline. |
+| [`/diagram`](#diagram) | **Diagram Maker** | English in, diagram out: mermaid source + editable `.excalidraw` (open it on excalidraw.com, hand-drawn style) + rendered SVG/PNG. Fully offline. |
 | [`/ios-qa`](#ios-qa) | **iOS QA Lead** | Live-device iOS QA via USB CoreDevice tunnel + embedded StateServer. Reads Swift source, codegens accessors, drives the real iPhone. Optionally exposes the device over Tailscale for remote agents. |
 | [`/ios-fix`](#ios-fix) | **iOS Autonomous Fixer** | Closes the find→fix→verify loop on a real iPhone. Captures a reproducing snapshot, fixes the source, rebuilds, redeploys, verifies. |
 | [`/ios-design-review`](#ios-design-review) | **iOS Designer's Eye** | 10-dimension Apple HIG audit on a real iPhone. Rates each screen, says what would make it a 10. |

gstack/llms.txt

@@ -26,7 +26,7 @@ Conventions:
 - [/design-review](design-review/SKILL.md): Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them.
 - [/design-shotgun](design-shotgun/SKILL.md): Design shotgun: generate multiple AI design variants, open a comparison board, collect structured feedback, and iterate.
 - [/devex-review](devex-review/SKILL.md): Live developer experience audit.
-- [/diagram](diagram/SKILL.md): Turn an English description (or mermaid source) into a diagram triplet: the source, an editable .excalidraw file you can open on excalidraw.com, and rendered SVG + PNG.
+- [/diagram](diagram/SKILL.md): Turn an English description (or mermaid source) into a diagram triplet: the source, an editable .excalidraw file you can open on excalidraw.com, and rendered SVG + PNG (clean mermaid style; the .excalidraw carries the hand-drawn aesthetic).
 - [/document-generate](document-generate/SKILL.md): Generate missing documentation from scratch for a feature, module, or entire project.
 - [/document-release](document-release/SKILL.md): Post-ship documentation update.
 - [/freeze](freeze/SKILL.md): Restrict file edits to a specific directory for the session.

lib/diagram-render/README.md

@@ -19,6 +19,7 @@ fails CI if `dist/` is edited by hand or falls out of sync with `BUILD_INFO.json
 | `__mermaidToExcalidraw(text)` | mermaid text → `.excalidraw` scene JSON (flowcharts fully; other types degrade upstream). |
 | `__excalidrawToSvg(sceneJson)` | scene JSON → SVG string (Excalifont embedded, offline). |
 | `__rasterize(svg, targetWidthPx)` | SVG → PNG data URL. Callers own DPI math: `targetWidthPx = placed width (in) × 300`. Throws on tainted canvas. |
+| `__downscaleRaster(dataUri, targetWidthPx, mime)` | raster data URI → smaller data URI at `targetWidthPx` (same mime). make-pdf uses it to normalize oversized photos to print resolution. |
 | `__mountForScreenshot(svg, px)` | taint-proof fallback: mounts SVG at `#raster-stage` for `browse screenshot --selector`. |
 | `__probeImage(src)` | data URI/URL → `{width, height}` JSON. |
 | `__bundleInfo` | `{ name, deps }` — pinned dependency versions baked at build. |

make-pdf/SKILL.md

@@ -600,8 +600,9 @@ $P generate --no-confidential memo.md memo.pdf
 
 ### Diagrams — mermaid and excalidraw fences render as pictures
 
-Any ` ```mermaid ` or ` ```excalidraw ` fence in the markdown renders as a
+A column-0 ` ```mermaid ` or ` ```excalidraw ` fence in the markdown renders
-crisp vector diagram, fully offline (vendored bundle, no CDN). A broken fence
+as a crisp vector diagram, fully offline (vendored bundle, no CDN). Indented
+fences (inside lists) stay plain code blocks by design. A broken fence
 produces a visible red diagnostic block with the parse error — never silent
 raw code.
 
@@ -611,6 +612,7 @@ Fence info-string options:
 ```mermaid title="Auth flow"        ← caption + aria-label
 ```mermaid render=false             ← keep it as a code block (today's behavior)
 ```mermaid page=landscape           ← force this diagram onto a landscape page
+```mermaid page=portrait            ← veto auto-landscape for this diagram
 ```
 
 A ` ```excalidraw ` fence contains a full .excalidraw scene file (what

make-pdf/SKILL.md.tmpl

@@ -96,8 +96,9 @@ $P generate --no-confidential memo.md memo.pdf
 
 ### Diagrams — mermaid and excalidraw fences render as pictures
 
-Any ` ```mermaid ` or ` ```excalidraw ` fence in the markdown renders as a
+A column-0 ` ```mermaid ` or ` ```excalidraw ` fence in the markdown renders
-crisp vector diagram, fully offline (vendored bundle, no CDN). A broken fence
+as a crisp vector diagram, fully offline (vendored bundle, no CDN). Indented
+fences (inside lists) stay plain code blocks by design. A broken fence
 produces a visible red diagnostic block with the parse error — never silent
 raw code.
 
@@ -107,6 +108,7 @@ Fence info-string options:
 ```mermaid title="Auth flow"        ← caption + aria-label
 ```mermaid render=false             ← keep it as a code block (today's behavior)
 ```mermaid page=landscape           ← force this diagram onto a landscape page
+```mermaid page=portrait            ← veto auto-landscape for this diagram
 ```
 
 A ` ```excalidraw ` fence contains a full .excalidraw scene file (what

scripts/proactive-suggestions.json

@@ -80,7 +80,7 @@
     },
     "diagram": {
       "lead": "Turn an English description (or mermaid source) into a diagram triplet: the source, an editable .excalidraw file you can open",
-      "routing": "on excalidraw.com,\nand rendered SVG + PNG. Hand-drawn excalidraw aesthetic, fully offline.\nUse when asked to \"make a diagram\", \"draw the architecture\", \"create a\nflowchart\", \"diagram this\", or \"visualize this flow\".",
+      "routing": "on excalidraw.com,\nand rendered SVG + PNG (clean mermaid style; the .excalidraw carries the\nhand-drawn aesthetic). Fully offline.\nUse when asked to \"make a diagram\", \"draw the architecture\", \"create a\nflowchart\", \"diagram this\", or \"visualize this flow\".",
       "voice_line": null
     },
     "document-generate": {