mirror of
https://github.com/garrytan/gstack.git
synced 2026-06-23 18:20:00 +02:00
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>
This commit is contained in:
Garry Tan
+8
-7
@@ -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
|
||||
|
||||
@@ -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?
|
||||
|
||||
|
||||
+2
-1
@@ -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".
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
|
||||
+1
-1
@@ -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. |
|
||||
|
||||
+1
-1
@@ -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.
|
||||
|
||||
@@ -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. |
|
||||
|
||||
+4
-2
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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": {
|
||||
|
||||
Reference in New Issue
Block a user