From b2318467e5734c89061218792a7627b9148b0c2b Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Fri, 12 Jun 2026 11:24:38 -0700 Subject: [PATCH] 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 --- CHANGELOG.md | 15 ++++++++------- README.md | 2 +- diagram/SKILL.md | 3 ++- diagram/SKILL.md.tmpl | 3 ++- docs/howto-diagrams-and-formats.md | 11 ++++++++--- docs/skills.md | 2 +- gstack/llms.txt | 2 +- lib/diagram-render/README.md | 1 + make-pdf/SKILL.md | 6 ++++-- make-pdf/SKILL.md.tmpl | 6 ++++-- scripts/proactive-suggestions.json | 2 +- 11 files changed, 33 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2efd93899..2dd4b64a8 100644 --- a/CHANGELOG.md +++ b/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 -CI failures. +links actually jump, and `--strict` turns missing, remote, out-of-tree, or +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 - output format. Fence options: `title="..."` (caption + aria-label), +- ` ```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, @@ -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 - oversized files fail the run instead of degrading to placeholders. +- `--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 diff --git a/README.md b/README.md index 2a1335c97..4bb177c3a 100644 --- a/README.md +++ b/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? diff --git a/diagram/SKILL.md b/diagram/SKILL.md index b2df1cc45..1ea8fd1a2 100644 --- a/diagram/SKILL.md +++ b/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". diff --git a/diagram/SKILL.md.tmpl b/diagram/SKILL.md.tmpl index 545b8d8d7..9e19a52c6 100644 --- a/diagram/SKILL.md.tmpl +++ b/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: diff --git a/docs/howto-diagrams-and-formats.md b/docs/howto-diagrams-and-formats.md index b051a4c14..f591db726 100644 --- a/docs/howto-diagrams-and-formats.md +++ b/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 - (centered measure, padding). Email it, attach it, open it anywhere. + images as data URIs, zero network references (under the default offline + 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. diff --git a/docs/skills.md b/docs/skills.md index dfc25c703..8e8cb7adc 100644 --- a/docs/skills.md +++ b/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. | diff --git a/gstack/llms.txt b/gstack/llms.txt index 4df78b148..a330413e4 100644 --- a/gstack/llms.txt +++ b/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. diff --git a/lib/diagram-render/README.md b/lib/diagram-render/README.md index 397ad5e17..6950a369e 100644 --- a/lib/diagram-render/README.md +++ b/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. | diff --git a/make-pdf/SKILL.md b/make-pdf/SKILL.md index bef600ae6..252336d7e 100644 --- a/make-pdf/SKILL.md +++ b/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 -crisp vector diagram, fully offline (vendored bundle, no CDN). A broken fence +A column-0 ` ```mermaid ` or ` ```excalidraw ` fence in the markdown renders +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 diff --git a/make-pdf/SKILL.md.tmpl b/make-pdf/SKILL.md.tmpl index 3d54870c9..9133a711d 100644 --- a/make-pdf/SKILL.md.tmpl +++ b/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 -crisp vector diagram, fully offline (vendored bundle, no CDN). A broken fence +A column-0 ` ```mermaid ` or ` ```excalidraw ` fence in the markdown renders +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 diff --git a/scripts/proactive-suggestions.json b/scripts/proactive-suggestions.json index b0c1981df..a8fe22b3b 100644 --- a/scripts/proactive-suggestions.json +++ b/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": {