@tekyzinc/gsd-t 4.18.10 → 4.19.11

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.19.11] - 2026-07-07
+
+### Fixed — `/gsd-t-stories` diagrams: semantic coloring + fit-to-page
+
+The command's flow diagrams were rendering as flat single-color and overflowing the page. Diagram generation now mandates **role-based semantic coloring** (green=action/go, orange=decision, red=destructive, blue-dashed=new/optional, purple=screen, white=terminal, via a `classDef` block) and **fit-to-page** layout (prefer `flowchart LR` for long linear flows, `subgraph` lanes or a part-1/2 split for large ones, explicit render sizing, and a verify-not-clipped-then-re-render step). Same rules mirrored into the bundled format reference. Also reconciled the backlog (removed 14 shipped/superseded items, renumbered survivors 1..46, fixed 4 number collisions).
+
+- `commands/gsd-t-stories.md`: Step 4 → 4a (semantic coloring) / 4b (fit-to-page) / 4c (render).
+- `templates/playbooks/tekyz-user-stories-format.md`: coloring + fit rules.
+- `.gsd-t/backlog.md`: 55 headings → 46 contiguous items.
+
+## [4.19.10] - 2026-07-07
+
+### Added — `/gsd-t-stories`: dev-team handoff user stories in the Tekyz format
+
+New standalone command that generates a development-team handoff document in the Tekyz user-stories format from any source — a scan register, a requirements doc, a design contract, or a reverse-engineered codebase. Reverse-engineered from the Tekyz Compass sample PRD: front matter → Application Flow Overview → User Stories grouped under Epics (id, story, workflow, grouped acceptance criteria, per-story flow diagram, mapped test-case table) → Scope Summary. Diagrams are authored as Mermaid but embedded as rendered PNGs (matching the sample's embedded-image flow charts), via `@mermaid-js/mermaid-cli`; output to `share/<Repo>-user-stories.md` (+ optional `.docx` via pandoc).
+
+- `commands/gsd-t-stories.md`: the new command (input classification, epic/story decomposition, Mermaid→PNG→embed pipeline, markdown + optional docx output).
+- `templates/playbooks/tekyz-user-stories-format.md`: bundled format reference (the exact structure + wording conventions).
+- `commands/gsd-t-help.md`, `README.md`, `templates/CLAUDE-global.md`: command reference + standalone-list ripple.
+- `test/filesystem.test.js`: command counts 52→53, gsdt 46→47.
+
+Distinct from `/gsd-t-prd` (which writes the internal `docs/prd.md`) — this is an external client/dev deliverable. Suite 2631/2631.
+
 ## [4.18.10] - 2026-07-03
 
 ### Added — Scan Consolidation Opportunities + type-grouped register; init-scan-setup repo adoption

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.18.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.19.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.
@@ -187,6 +187,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/gsd-t-gap-analysis` | Requirements gap analysis — spec vs. existing code | Manual |
 | `/gsd-t-promote-debt` | Convert techdebt items to milestones | Manual |
 | `/gsd-t-estimate` | Turn any work doc (scan, requirements, feature/app spec) into a Tekyz client estimate (Google Sheet: T-Shirt Size + Team Mix) + matching PRD — supervised, with an operator-arbitrated Estimate Red Team | Manual |
+| `/gsd-t-stories` | Generate a dev-team handoff doc in the Tekyz user-stories format (stories + workflows + acceptance criteria + Mermaid flow diagrams + mapped test cases) from any source | Manual |
 | `/gsd-t-populate` | Auto-populate docs from existing codebase | Manual |
 | `/gsd-t-design-decompose` | Decompose design into element/widget/page contracts | Manual |
 

package/commands/gsd-t-help.md

@@ -364,6 +364,12 @@ Use these when user asks for help on a specific command:
 - **Updates**: the Tekyz estimate Google Sheet + `share/<Repo>-PRD-*.md` (and, if renumbered, the source doc/docs/scan files) + optional `share/<Repo>-estimate-redteam-notes.md`
 - **Use when**: You need a client-facing paid estimate + PRD (T-shirt sizing, dollar range, sign-off) from a scan OR a requirements/feature/app spec. **SUPERVISED** — judgment phases (sizing, adjustments, PRD, Red Team) pause for your review; **you are the final arbiter** of an Estimate Red Team that challenges the numbers. Rate + sheet template + factors are parameterized (default Tekyz). Encodes the Tekyz playbook (`~/.claude/playbooks/tekyz-estimation-and-prd-playbook.md`)
 
+### stories
+- **Summary**: Generate a dev-team handoff document in the Tekyz user-stories format — discrete user stories with workflows, grouped acceptance criteria, per-story flow diagrams (Mermaid rendered to embedded images), and mapped test-case tables — from any source (scan register, requirements doc, design contract, or a reverse-engineered codebase)
+- **Auto-invoked**: No
+- **Updates**: new deliverable `share/<Repo>-user-stories.md` (+ optional `.docx` via pandoc) + `share/media/*.png` (rendered diagrams) + `.gsd-t/user-stories/diagrams/*.mmd`
+- **Use when**: You need to hand a development team discrete, testable user stories in the Tekyz handoff style. Distinct from `/gsd-t-prd` (which writes the INTERNAL `docs/prd.md`) — this is an EXTERNAL client/dev deliverable. Diagrams are authored as Mermaid but embedded as rendered images (needs `@mermaid-js/mermaid-cli`). Format reference: `~/.claude/playbooks/tekyz-user-stories-format.md`
+
 ### populate
 - **Summary**: Auto-populate all living docs from existing codebase analysis
 - **Auto-invoked**: No

package/commands/gsd-t-stories.md

@@ -0,0 +1,97 @@
+# GSD-T: Stories — Dev-Handoff User Stories (Tekyz format) from any source
+
+You are generating a **development-team handoff document** in the Tekyz user-stories format: discrete user stories with workflows, grouped acceptance criteria, per-story flow diagrams (Mermaid rendered to embedded images), and mapped test cases. Input can be a GSD-T **scan register**, a **requirements doc**, a **design contract**, or an **existing codebase** (reverse-engineered). `$ARGUMENTS` may carry `--input <path>`, `--source <scan|requirements|design|code>`, `--prefix <PREFIX>`, `--phase-filter <MVP|...>`, `--docx`.
+
+**Canonical format reference (READ FIRST):** `~/.claude/playbooks/tekyz-user-stories-format.md` if present, else the bundled `templates/playbooks/tekyz-user-stories-format.md` in the GSD-T package. It encodes the exact structure + wording conventions reverse-engineered from the Tekyz sample (`Compass_Sample_PRD_2.docx`). This command FILLS that format from the real input.
+
+> **Client/dev-team deliverable — distinct from `/gsd-t-prd`.** `/gsd-t-prd` writes the INTERNAL `docs/prd.md` that feeds the GSD-T pipeline. THIS command emits an EXTERNAL, dev-ready handoff doc in the Tekyz user-story style, saved to `share/`.
+
+## Step 0: Inputs + Source Classification
+
+1. **Resolve the input** (from `$ARGUMENTS --input`, else auto-detect in priority order): `.gsd-t/techdebt.md` (scan) → `docs/requirements.md` → `.gsd-t/contracts/design-contract.md` / `.gsd-t/contracts/design/` → the codebase itself. If none usable → ask the user what to document.
+2. **Classify the source** so the extraction method matches:
+   - **scan register** → stories derive from the functional gaps/features implied by findings (each cluster of related TDs → a story; Reqs cross-ref the TD-N ids).
+   - **requirements doc** → each requirement / requirement-group → a story (Reqs cross-ref R-N/FR-N).
+   - **design contract** → each screen/widget/flow → a story.
+   - **codebase (reverse-engineer)** → walk real features (routes, pages, flows) and reverse-engineer the discrete user stories + test cases from what's built. **Use the code graph** (`gsd-t graph cluster` / `who-imports` / `who-calls`) to find feature clusters and real interaction paths — do NOT grep-guess the architecture.
+3. **Derive the story-id `PREFIX`** from the product name (Compass→`CMPS`, NiceNote→`NN`, Newman Avatar→`NAV`) unless `--prefix` is given. Confirm with the user.
+4. **Confirm scope** — which phases/epics to include — before generating.
+
+## Step 1: Application Flow Overview (§1)
+
+Produce the numbered end-to-end user journey (1..N major steps, plain language). Then author the **app-flow chart** as a single Mermaid flowchart of the whole journey and render+embed it (Step 4). This is the reader's map before the story detail.
+
+## Step 2: Decompose into Epics + Stories (§2)
+
+Group functionality into **Epics** (`EP-NN: <name>`), each with a `Phase:`. Under each epic, emit discrete stories. **A story is ONE coherent capability a user exercises** — not a whole feature area, not a single UI control. Right granularity = the sample's (e.g. "Avatar renders full-screen with state indicators" is one story; "Session controls: pause/resume/end" is another).
+
+For EACH story, author in EXACTLY this order (per the format reference):
+
+1. **`<PREFIX>-NNN — <Story Title>`** (sequential, zero-padded).
+2. **Meta line** — `*Phase: … | Reqs: <source ids> | Test Cases: <N>*`. `Reqs:` cross-references the source (TD-N / R-N / FR-N); `Test Cases:` = row count of this story's table.
+3. **Story:** `*As a <role>, I want <capability>, so that <benefit>.*` (strict template, one sentence.)
+4. **Workflow:** numbered concrete interaction steps (user action → system response), present tense.
+5. **Acceptance Criteria:** bulleted, **grouped by sub-area** with a bold sub-heading per group; include error/edge/recovery groups. Each bullet one testable assertion.
+6. **Flow Diagram:** a per-story Mermaid flowchart of THIS story's workflow → rendered PNG → embedded (Step 4).
+7. **Mapped Test Cases:** table `TC ID | Type | Test Title | Expected Result`. `TC-NNN` sequential across the whole doc; `Type` ∈ {Positive, Negative, Edge}; cover happy-path + failure + boundary; every acceptance-criteria group represented by ≥1 test case.
+
+**No confabulation** (`feedback_no_confabulated_examples`): every story, workflow step, and test case must trace to something in the actual input source. If the source is silent on a needed detail, mark it a `[TODO: confirm with client]` — never invent product specifics.
+
+## Step 3: Scope Summary (§3)
+
+A table mapping every story → phase → epic: `| Story ID | Title | Phase | Epic |`. Gives the team the MVP-vs-later-phase picture at a glance.
+
+## Step 4: Diagrams — Mermaid rendered to EMBEDDED images (MANDATORY method)
+
+Per the standing directive, diagrams are authored as Mermaid but **embedded as rendered images** (matching the sample's `<img>` flow charts) — NOT left as raw Mermaid text.
+
+### 4a. Semantic coloring (MANDATORY — never flat single-color)
+
+Every diagram MUST use **intelligent, role-based coloring** — NOT mermaid's default flat purple. Assign each node a `class` by its ROLE and define matching `classDef`s. Standard palette (green=go/success, orange=decision, red=destructive, blue=new/optional, purple=screen/state, grey=terminal):
+
+```mermaid
+%% put at the TOP of every flowchart:
+classDef start     fill:#fff,stroke:#333,color:#000;                         %% start/end terminals (ellipse)
+classDef decision  fill:#fdebc8,stroke:#e8a33d,color:#7a4f00;               %% decisions (diamonds)
+classDef screen    fill:#ece9fb,stroke:#8b7fd6,color:#2d2160;              %% screens / states
+classDef action    fill:#d4f4dd,stroke:#4caf72,color:#0f5132;             %% success / go / user actions
+classDef destructive fill:#fde2e2,stroke:#e06666,color:#7a1f1f;           %% end / delete / irreversible
+classDef newfeat   fill:#e2f0fb,stroke:#5b9bd5,color:#1f4e79,stroke-dasharray:4 3; %% NEW / optional (dashed)
+```
+
+- **Decisions** are diamonds `{...}` classed `decision`; **terminals** (start/end) are stadium/round `([...])` classed `start`; **screens/states** classed `screen`; **success/go paths** classed `action`; **destructive/irreversible** (End, Delete) classed `destructive`; **new/optional** classed `newfeat` (dashed).
+- Label decision-branch edges (`-->|Yes|`, `-->|Returning User|`).
+- Reference the sample styling in `~/.claude/playbooks/tekyz-user-stories-format.md`.
+
+### 4b. Fit-to-page (MANDATORY — the whole diagram must fit)
+
+A long top-down flow overflows the page (the failure the user flagged). Keep EVERY diagram fully on one page:
+
+- **Prefer `flowchart LR`** (left-to-right) for long linear flows — wide pages fit more than tall ones. Use `TD` only for short (≤6-node) flows.
+- For a flow with many nodes, **break into logical lanes with `subgraph`s**, or split into a "part 1 / part 2" pair of diagrams rather than one that runs off-page.
+- Render with an explicit width/scale and padding so nothing is clipped: `mmdc -i <src>.mmd -o share/media/<name>.png --width 1600 --backgroundColor white --scale 2 --padding 20` (a mermaid config `{ "flowchart": { "useMaxWidth": true } }` via `-c` also helps).
+- **After rendering, VERIFY the image isn't clipped** — check the PNG's dimensions are sane and, if a node count is high, that the layout direction kept it on-page. If a diagram still overflows, switch direction (`TD`→`LR`) or split it, and re-render. Do NOT ship a clipped diagram (`feedback_no_silent_degradation`).
+
+### 4c. Render pipeline
+
+1. Write each diagram's Mermaid source (with the `classDef` block + role classes + fit-appropriate direction) to `.gsd-t/user-stories/diagrams/<name>.mmd` (app-flow = `app-flow`, per-story = `<PREFIX>-NNN-flow`).
+2. Render each to PNG: `mmdc -i <src>.mmd -o share/media/<name>.png --width 1600 --backgroundColor white --scale 2 --padding 20` (Mermaid CLI `@mermaid-js/mermaid-cli`; fall back to `npx @mermaid-js/mermaid-cli …`).
+3. **If `mmdc` is unavailable → HALT** and tell the user to install it (`npm i -g @mermaid-js/mermaid-cli`). Do NOT silently ship raw Mermaid where an embedded image is expected (`feedback_no_silent_degradation`).
+4. Embed each rendered PNG in the markdown at its `Flow Diagram:` / §1 position: `![Flow Diagram](media/<name>.png)`.
+5. Keep the `.mmd` source (editable, version-controllable) alongside the PNG.
+
+## Step 5: Assemble + Deliver
+
+1. Assemble front matter (product, "Prepared by Tekyz Inc.", version, source-of-truth note; SAMPLE disclaimer only if illustrative) + §1 + §2 + §3.
+2. **Write the markdown** to `share/<Repo>-user-stories.md`, with rendered diagram PNGs in `share/media/`.
+3. **If `--docx`** (or the user wants Word): convert with `pandoc share/<Repo>-user-stories.md -o share/<Repo>-user-stories.docx` — pandoc embeds the PNGs as real Word images, matching the handoff sample. Report if pandoc is missing (don't fail the markdown).
+4. **Report:** story count, epic count, total test cases, diagram count, and the output paths.
+
+## Document Ripple
+
+- New deliverable(s): `share/<Repo>-user-stories.md` (+ `.docx` if requested) + `share/media/*.png` + `.gsd-t/user-stories/diagrams/*.mmd`.
+- No living-doc changes (this is an external handoff artifact) — but log a `.gsd-t/progress.md` Decision Log entry noting the deliverable + source.
+
+## ▶ Next Up
+
+Standalone command — no auto-successor. After generating, hand the `share/<Repo>-user-stories.md` (or `.docx`) to the development team.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.18.10",
+  "version": "4.19.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -460,7 +460,7 @@ Add `**Also available:**` with `- /gsd-t-{alt} — {desc}` lines if alternatives
 | `setup` | `status` | |
 | `design-decompose` | `design-build` | `partition` (if domains needed first) |
 
-Commands with no successor (standalone): `quick`, `debug`, `brainstorm`, `status`, `help`, `resume`, `prompt`, `log`, `health`, `pause`, `estimate`, backlog commands.
+Commands with no successor (standalone): `quick`, `debug`, `brainstorm`, `status`, `help`, `resume`, `prompt`, `log`, `health`, `pause`, `estimate`, `stories`, backlog commands.
 
 Skip the hint if auto-advancing (Level 3 mid-wave) — only show when the user needs to manually invoke the next step.
 

package/templates/playbooks/tekyz-user-stories-format.md

@@ -0,0 +1,156 @@
+# Tekyz User-Stories / Dev-Handoff PRD Format
+
+> The canonical format for a Tekyz **development-team handoff** document: discrete user
+> stories with workflows, grouped acceptance criteria, per-story flow diagrams, and mapped
+> test cases. Reverse-engineered from `Compass_Sample_PRD_2.docx` (the sample Tekyz uses to
+> illustrate its requirements-documentation process). `/gsd-t-user-stories` emits THIS format.
+>
+> This is a REFERENCE for structure + exact wording conventions — not the content. The
+> command fills it from the actual input source (scan / requirements / design / codebase).
+
+---
+
+## Document skeleton (in order)
+
+```
+FRONT MATTER
+1. Application Flow Overview        (numbered end-to-end journey + app-flow chart)
+2. User Stories — Detailed Requirements
+     EP-NN: <Epic Name>            (epic grouping)
+       Phase: <MVP | Phase 1 | ...>
+       <PREFIX>-NNN — <Story Title>
+         meta line
+         Story:                    (As a … I want … so that …)
+         Workflow:                 (numbered steps)
+         Acceptance Criteria:      (grouped by sub-area, bulleted)
+         Flow Diagram:             (rendered Mermaid PNG, embedded as <img>)
+         Mapped Test Cases:        (table)
+3. <Phase> vs <Phase> Scope Summary  (story→phase→epic table)
+```
+
+---
+
+## FRONT MATTER (verbatim conventions)
+
+```
+**<PRODUCT NAME>**
+
+<one-line product descriptor>
+
+Product Requirements Document
+
+**Prepared by Tekyz Inc.**
+
+Version <X.Y> — <source-of-truth note, e.g. "Design file v2.x as source of truth">
+```
+
+If the doc is illustrative/sample, include the italic SAMPLE DOCUMENT disclaimer block.
+
+---
+
+## §1 — Application Flow Overview
+
+A numbered list (1..N) naming each major step of the end-to-end user journey in plain
+language (e.g. "First-Time User Launch: App opens directly into … onboarding"). Follow with:
+- an **app-flow chart** — a single Mermaid flowchart of the whole journey, rendered to PNG
+  and embedded (`![Application Flow](media/app-flow.png)`), matching the sample's companion chart.
+- the italic note that a complete flow chart accompanies the document.
+
+---
+
+## §2 — User Stories (the core; repeat per story)
+
+Group stories under **Epics**: `**EP-01: <Epic Name>**` then `**Phase: <phase>**`.
+
+Each story, in EXACTLY this order:
+
+**Story ID + title:** `**<PREFIX>-NNN — <Story Title>**`
+- `<PREFIX>` is a per-project story-id prefix (Compass used `CMPS`). Derive from the product
+  name (e.g. NiceNote → `NN`, Newman Avatar → `NAV`). Sequential, zero-padded to 3.
+
+**Meta line** (italic, pipe-separated):
+`*Phase: <phase> | Reqs: <R-… list> | Test Cases: <N>*`
+- `Reqs:` cross-references source requirement ids (from a scan register's TD-N, a requirements
+  doc's R-N/FR-N, or synthesized ids). `Test Cases:` = count of rows in the Mapped Test Cases table.
+
+**Story:** one sentence, italic, strict template:
+`*As a <role>, I want <capability>, so that <benefit>.*`
+
+**Workflow:** numbered steps (1..N) describing the concrete interaction sequence — what the
+user does and what the system does in response. Present tense, specific.
+
+**Acceptance Criteria:** bulleted, **grouped by sub-area** with a bold sub-heading per group
+(e.g. `**Talking State:**`, `**Error and Recovery:**`). Each bullet is a single testable
+assertion (state changed / content shown / constraint met). Include error/edge/recovery groups.
+
+**Flow Diagram:** a per-story Mermaid flowchart of THIS story's workflow, rendered to PNG and
+embedded (`![Flow Diagram](media/<PREFIX>-NNN-flow.png)`) — matching the sample's per-story `<img>`.
+
+**Mapped Test Cases:** a markdown table with columns **TC ID | Type | Test Title | Expected Result**.
+- `TC ID`: `TC-NNN` sequential across the whole document.
+- `Type`: one of **Positive | Negative | Edge**.
+- Cover the happy path (Positive), failure modes (Negative), and boundaries (Edge). Every
+  acceptance-criteria group should be represented by at least one test case.
+
+---
+
+## §3 — Scope Summary
+
+A table mapping every story to its phase + epic, so a team sees MVP vs later-phase scope at a glance:
+
+`| Story ID | Title | Phase | Epic |`
+
+---
+
+## Diagram pipeline (Mermaid → embedded image)
+
+Per the user directive, diagrams are **authored as Mermaid but EMBEDDED as rendered images**
+(like the sample's `<img>` flow charts) — not left as raw Mermaid text.
+
+### Semantic coloring (MANDATORY — never flat single-color)
+
+Every diagram uses **role-based coloring**, never mermaid's default flat purple. Put a
+`classDef` block at the top of each flowchart and class each node by ROLE:
+
+```
+classDef start       fill:#fff,stroke:#333,color:#000;                            %% start/end terminal
+classDef decision    fill:#fdebc8,stroke:#e8a33d,color:#7a4f00;                  %% decision diamond
+classDef screen      fill:#ece9fb,stroke:#8b7fd6,color:#2d2160;                 %% screen / state
+classDef action      fill:#d4f4dd,stroke:#4caf72,color:#0f5132;                %% success / go / action
+classDef destructive fill:#fde2e2,stroke:#e06666,color:#7a1f1f;               %% end / delete / irreversible
+classDef newfeat     fill:#e2f0fb,stroke:#5b9bd5,color:#1f4e79,stroke-dasharray:4 3; %% NEW / optional (dashed)
+```
+
+Green = go/success/action · Orange = decision · Red = destructive/irreversible · Blue(dashed)
+= new/optional · Purple = screen/state · White = terminal. Decisions are diamonds `{...}`;
+terminals are round `([...])`; label decision-branch edges (`-->|Yes|`).
+
+### Fit-to-page (MANDATORY — the whole diagram must fit)
+
+A long top-down flow overflows the page. Keep EVERY diagram fully on one page:
+- Prefer `flowchart LR` (left-to-right) for long linear flows; use `TD` only for ≤6-node flows.
+- For many nodes, break into `subgraph` lanes or split into part-1/part-2 diagrams.
+- Render with explicit sizing so nothing clips, then VERIFY the PNG isn't clipped; if it is,
+  switch direction or split and re-render. Never ship a clipped diagram.
+
+### Render
+
+1. Write each diagram's Mermaid source (classDef block + role classes + fit-appropriate
+   direction) to `.gsd-t/user-stories/diagrams/<name>.mmd`.
+2. Render to PNG: `mmdc -i <name>.mmd -o media/<name>.png --width 1600 --backgroundColor white
+   --scale 2 --padding 20` (`@mermaid-js/mermaid-cli`; fall back to `npx @mermaid-js/mermaid-cli`).
+   If `mmdc` is unavailable, HALT and tell the user to install it — do NOT silently ship raw
+   Mermaid where an embedded image is expected (no-silent-degradation).
+3. Embed the PNG in the markdown: `![Flow Diagram](media/<name>.png)`.
+4. On `.docx` conversion, pandoc embeds these PNGs as real Word images — matching the sample.
+
+Keep the `.mmd` source (version-controllable, editable) alongside the rendered PNG.
+
+---
+
+## Output
+
+- Markdown deliverable → `share/<Repo>-user-stories.md` (GSD-T share convention), with a
+  `media/` dir of rendered diagram PNGs beside it.
+- Optional `.docx` (matching the handoff sample) via `pandoc share/<Repo>-user-stories.md
+  -o share/<Repo>-user-stories.docx` — embeds the PNGs as Word images.