owflow 0.1.4 → 0.1.5

package/dist/commands/diagrams-mermaid.md

@@ -0,0 +1,37 @@
+---
+name: diagrams-mermaid
+description: Generate Mermaid diagrams from natural language descriptions. Creates diagrams in markdown format with mermaid code fences. Supports flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, user journeys, Gantt charts, pie charts, and C4 diagrams.
+argument-hint: [diagram description]
+generated-from-skill: true
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the diagrams-mermaid skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "diagrams-mermaid"
+prompt: "$ARGUMENTS"
+
+DO NOT:
+
+- Analyze the task before invoking the skill
+- Decide the task is "straightforward" and skip the skill
+- Substitute your own approach or workflow
+- Execute any part of the workflow yourself
+
+WHY: The user explicitly chose this workflow by using /diagrams-mermaid.
+Invoke the skill now and let it orchestrate the complete workflow.
+
+---
+
+## About This Skill
+
+Generate Mermaid diagrams from natural language descriptions. Creates diagrams in markdown format with mermaid code fences. Supports flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, user journeys, Gantt charts, pie charts, and C4 diagrams.
+
+The skill handles:
+
+- Diagram type selection based on description
+- Mermaid syntax generation with proper formatting
+- Best practices and anti-patterns enforcement
+- Output in markdown format with mermaid code fences
+
+See `skills/diagrams-mermaid/SKILL.md` for complete documentation.

package/dist/commands/html-renderer.md

@@ -0,0 +1,37 @@
+---
+name: html-renderer
+description: Render a markdown plan, idea, RFC, or design note into a self-contained, share-ready HTML file using the warm editorial visual system. Output is a single .html file with all CSS inlined, written next to the source markdown file.
+argument-hint: [path to markdown file]
+generated-from-skill: true
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the html-renderer skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "html-renderer"
+prompt: "$ARGUMENTS"
+
+DO NOT:
+
+- Analyze the task before invoking the skill
+- Decide the task is "straightforward" and skip the skill
+- Substitute your own approach or workflow
+- Execute any part of the workflow yourself
+
+WHY: The user explicitly chose this workflow by using /html-renderer.
+Invoke the skill now and let it orchestrate the complete workflow.
+
+---
+
+## About This Skill
+
+Render a markdown plan, idea, RFC, or design note into a self-contained, share-ready HTML file using the warm editorial visual system. Output is a single .html file with all CSS inlined, written next to the source markdown file.
+
+The skill handles:
+
+- Markdown parsing and semantic HTML generation
+- Design system application with warm editorial styling
+- Mermaid diagram rendering via CDN (when present)
+- Self-contained output with inlined CSS
+
+See `skills/html-renderer/SKILL.md` for complete documentation.

package/dist/skills/development/SKILL.md

@@ -235,6 +235,15 @@ question - "UI mockups complete. Continue to Phase 5?"
 
 **SELF-CHECK**: Did you just invoke the Task tool with `specification-creator`? Or did you start writing spec.md yourself? If the latter, STOP immediately and invoke the Task tool instead.
 
+**Part D — Diagram Refinement (Skill, content-preserving)**:
+
+7. Invoke Skill tool: `diagrams-mermaid` to refine `implementation/spec.md`
+8. Add diagrams that clarify scope and communication (without replacing prose):
+   - `flowchart` for primary functional path,
+   - `sequenceDiagram` for key component interaction,
+   - optionally `C4Component` if internal module structure is required by scope.
+9. If required context is missing, add explicit open questions/assumptions section instead of inventing entities.
+
 **Output**: `analysis/technical-clarifications.md` (conditional), `analysis/requirements.md`, `implementation/spec.md`
 **State**: Update `task_context.tech_clarified`, `task_context.architecture_decision`, `phase_summaries.specification`
 
@@ -285,6 +294,12 @@ question - Display executive summary before asking. Read `verification/spec-audi
 
 **SELF-CHECK**: Did you just invoke the Task tool with `implementation-planner`? Or did you start writing implementation-plan.md yourself? If the latter, STOP immediately and invoke the Task tool instead.
 
+**Post-plan diagram refinement (Skill, content-preserving)**:
+
+- Invoke Skill tool: `diagrams-mermaid` for `implementation/implementation-plan.md`
+- Add a compact execution diagram (task-group dependency flow or phase/state view).
+- Keep implementation steps authoritative; diagrams are explanatory, not a replacement for task descriptions.
+
 → Pause
 
 question - Display executive summary before asking. Read `implementation/implementation-plan.md` and extract: number of task groups, total implementation steps, key dependencies between groups, estimated complexity. Format as brief overview then "Continue to implementation?"

package/dist/skills/diagrams-mermaid/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: diagrams-mermaid
+description: Creates Mermaid diagrams for planning flows, component communication, and architecture views with adaptive detail selection (including C4 levels). This skill should be used when the user asks for a workflow, interaction, or architecture visualization from provided task context.
+user-invocable: true
+---
+
+# Mermaid Diagram Builder
+
+Generate Mermaid diagrams from task context. Focus on visual structure and communication flow, not domain invention.
+
+## 🚨 Core Rules
+
+1. **Read `references/reference.md`** (located in the `references/` subdirectory of this skill) before generating any diagram.
+2. **Refine, don't replace** — use the current document or task artifact as source material; add visual precision on top of it and keep required narrative sections intact.
+3. **Never invent domain context** — if required facts are missing (actors, components, boundaries, protocols, decisions), ask targeted clarification questions before drawing the final diagram.
+4. **Output diagrams only as fenced `mermaid` blocks** (non-negotiable):
+   - ✅ Allowed: ` ```mermaid `
+   - ❌ Forbidden: ` ```c4plantuml `, ` ```plantuml `, ` ```puml `, ` ```graphviz `, ` ```dot `, ` ```d2 `, or any custom alias.
+   - This rule cannot be overridden by user preference, template defaults, or legacy examples.
+
+---
+
+## When to Use
+
+Use this skill when the user wants:
+
+- a planning flow diagram,
+- component communication visualization,
+- architecture-level mapping,
+- phase/state transitions in a workflow.
+
+---
+
+## Output Contract
+
+When producing a diagram, return:
+
+1. **Diagram Type + Detail Rationale** (1-3 lines)
+2. **Diagram in a fenced ` ```mermaid ` block (required)**
+3. **Open Questions** (only if context is incomplete)
+
+Validation requirement before returning output:
+
+- Every diagram block in the response uses the `mermaid` fence exactly. Any other fence language is a hard failure.
+
+If context is incomplete:
+
+- ask concise clarifying questions first,
+- or provide a **Draft diagram** clearly marked as provisional with explicit unknowns.
+
+---
+
+## Workflow
+
+### Step 1: Extract Context
+
+Extract only explicit facts from user input and referenced artifacts:
+
+- scope and objective,
+- participants/components,
+- boundaries (system/service/module),
+- key interactions or state transitions,
+- constraints and non-goals.
+
+If any required field is missing for the chosen diagram type, ask for it.
+
+### Step 2: Infer Diagram Goal
+
+Classify what the user needs:
+
+- **Process logic** -> `flowchart`
+- **Time-ordered communication** -> `sequenceDiagram`
+- **State transitions / phase gates** -> `stateDiagram-v2`
+- **Architecture landscape** -> C4 (`C4Context` / `C4Container` / `C4Component`)
+
+### Step 3: Infer Detail Level
+
+Choose the minimum sufficient detail:
+
+- **System-level**: external actors/systems only -> `C4Context`
+- **Service/container-level**: apps/services/datastores + interfaces -> `C4Container`
+- **Module/component-level**: internal components in one container -> `C4Component` (only when implementation-level planning needs it)
+
+Fallback rule:
+
+- If C4 is too ambiguous or unstable for the requested artifact, use `flowchart` or `sequenceDiagram`.
+
+### Step 4: Build Diagram
+
+Apply naming and structure rules:
+
+- Stable IDs, human-readable labels.
+- One concern per diagram (split large scope into multiple diagrams).
+- For branching logic, use explicit decisions.
+- For interactions, use `alt`, `opt`, `par` where needed.
+
+### Step 5: Validate Quality
+
+Run this checklist before final output:
+
+- Diagram type matches user intent.
+- Detail level matches planning need (not over/under detailed).
+- No speculative domain entities or links.
+- Labels are clear and consistent.
+- Syntax is parser-safe.
+- All diagram blocks are fenced with ` ```mermaid ` (no alternatives).
+
+---
+
+## Mermaid/C4 Best Practices
+
+1. **Goal-first, syntax-second**: pick the view before drawing nodes.
+2. **Small readable views**: split diagrams instead of creating one overloaded graph.
+3. **Consistent naming**: keep IDs stable and semantic.
+4. **Explicit branching/parallelism**: model alternatives and parallel flows clearly.
+5. **C4 discipline**: do not mix levels (context/container/component) in one diagram.
+6. **Parser safety**:
+   - quote labels with special characters,
+   - avoid reserved or fragile node IDs,
+   - avoid custom style/color directives unless explicitly required.
+
+---
+
+## Anti-Examples (What Not To Do)
+
+1. **Invented domain context (critical anti-pattern)**  
+   Adding components, protocols, or dependencies not present in provided context.
+
+2. **Mixed abstraction levels**  
+   Combining system landscape and low-level function internals in a single diagram.
+
+3. **Unreadable mega-diagram**  
+   Packing too many nodes/edges into one chart without decomposition.
+
+4. **Sequence without temporal semantics**  
+   Using `sequenceDiagram` while omitting real call order, branches, or optional paths.
+
+5. **Placeholder naming**  
+   IDs and labels like `A`, `B`, `step1` with no domain meaning.
+
+6. **Non-Mermaid diagram fence (hard failure)**  
+   Returning diagrams in ` ```c4plantuml `, ` ```plantuml `, or any other non-`mermaid` fenced format.
+
+When any anti-pattern appears, stop and refactor the output before returning it.
+
+---
+
+## C4 Detail Decision Matrix
+
+| Need                                            | Recommended Type | Minimum Inputs                                  |
+| ----------------------------------------------- | ---------------- | ----------------------------------------------- |
+| Who interacts with the system?                  | `C4Context`      | actors, external systems, system boundary       |
+| How services/data stores communicate?           | `C4Container`    | containers, interfaces, protocols/data flow     |
+| How one service/module is internally organized? | `C4Component`    | container scope, components, internal contracts |
+
+If minimum inputs are missing, ask questions instead of guessing.

package/dist/skills/diagrams-mermaid/references/reference.md

@@ -0,0 +1,148 @@
+# Mermaid Diagram Reference
+
+Quick reference for selecting and writing diagrams in planning workflows.
+
+Hard rule for output artifacts:
+- Every diagram must be emitted only in fenced ` ```mermaid ` blocks.
+- Any other fenced diagram format (for example ` ```c4plantuml ` or ` ```plantuml `) is not allowed.
+
+## Quick Type Selector
+
+```mermaid
+flowchart TD
+  inputTask[TaskContext] --> needTime{NeedTimeOrder}
+  needTime -->|yes| seq[sequenceDiagram]
+  needTime -->|no| needState{NeedStateTransitions}
+  needState -->|yes| state[stateDiagram-v2]
+  needState -->|no| needArch{NeedArchitectureView}
+  needArch -->|yes| c4level{RequiredC4Level}
+  c4level -->|system| c4context[C4Context]
+  c4level -->|service| c4container[C4Container]
+  c4level -->|module| c4component[C4Component]
+  needArch -->|no| flow[flowchart]
+```
+
+## Minimal Templates
+
+### flowchart
+
+```mermaid
+flowchart TD
+  start[Start] --> decision{"Condition?"}
+  decision -->|"yes"| nextA[PathA]
+  decision -->|"no"| nextB[PathB]
+  nextA --> done[Done]
+  nextB --> done
+```
+
+### sequenceDiagram
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant ServiceA
+  participant ServiceB
+  User->>ServiceA: Request
+  alt ValidInput
+    ServiceA->>ServiceB: FetchData
+    ServiceB-->>ServiceA: Data
+    ServiceA-->>User: Success
+  else InvalidInput
+    ServiceA-->>User: ValidationError
+  end
+```
+
+### stateDiagram-v2
+
+```mermaid
+stateDiagram-v2
+  [*] --> Draft
+  Draft --> Review: submit
+  Review --> Approved: accept
+  Review --> Draft: request_changes
+  Approved --> [*]
+```
+
+### C4Context
+
+```mermaid
+C4Context
+  Person(user, "User")
+  System(targetSystem, "TargetSystem")
+  System_Ext(extSystem, "ExternalSystem")
+  Rel(user, targetSystem, "Uses")
+  Rel(targetSystem, extSystem, "Calls")
+```
+
+### C4Container
+
+```mermaid
+C4Container
+  Person(user, "User")
+  System_Boundary(boundary, "TargetSystem") {
+    Container(webApp, "WebApp", "React", "UI")
+    Container(apiService, "APIService", "Node.js", "Business logic")
+    ContainerDb(mainDb, "MainDB", "PostgreSQL", "Persistent storage")
+  }
+  Rel(user, webApp, "Interacts with")
+  Rel(webApp, apiService, "Calls")
+  Rel(apiService, mainDb, "Reads/Writes")
+```
+
+## Anti-Patterns
+
+1. **Domain hallucination (critical)**  
+   Adding systems/components not present in supplied context.
+
+2. **Abstraction mixing**  
+   Example: C4 context and function-level call chain in one chart.
+
+3. **Unbounded complexity**  
+   One giant diagram instead of split views.
+
+4. **Ambiguous naming**  
+   Non-semantic IDs (`A`, `B`, `step1`) without readable labels.
+
+5. **Sequence misuse**  
+   Interaction diagram without meaningful order/branches.
+
+6. **Non-Mermaid fenced output (hard failure)**  
+   Emitting any diagram in a non-`mermaid` fenced block.
+
+## "Bad -> Better" Examples
+
+### Inventing missing context
+
+Bad:
+- "Assume we also have Kafka and Redis" (not provided by user/context)
+
+Better:
+- "Current context is missing messaging/storage components. Please confirm whether any queue/cache exists."
+
+### Mixed detail levels
+
+Bad:
+- One diagram contains external systems, services, and method-level internals.
+
+Better:
+- Diagram 1: C4 context/container; Diagram 2: sequence for one critical interaction.
+
+## Parser Safety Notes
+
+- Use quoted labels for text with special characters.
+- Avoid fragile IDs and reserved keywords.
+- Prefer clear ASCII names for IDs.
+- Keep one diagram focused on one communication concern.
+
+## Integration Candidates
+
+Integrated into:
+- `src/skills/flow-init/SKILL.md` - Phase 6 (architecture and tech-stack doc refinement)
+- `src/skills/development/SKILL.md` - Phase 5 (spec refinement), Phase 7 (plan refinement)
+- `src/skills/research/SKILL.md` - Phase 5 (high-level design refinement)
+- `src/skills/performance/SKILL.md` - Phase 3 (spec refinement), Phase 5 (plan refinement)
+- `src/skills/migration/SKILL.md` - Phase 3 (spec refinement), Phase 4 (plan refinement)
+
+Reference files:
+- `src/skills/flow-init/references/architecture-template.md`
+- `src/skills/orchestrator-framework/references/orchestrator-patterns.md`

package/dist/skills/flow-init/SKILL.md

@@ -146,6 +146,21 @@ Fill templates using:
 
 Write each file to `.owflow/docs/project/`.
 
+**Diagram refinement (content-preserving, do NOT replace prose):**
+
+- If Architecture doc is selected and `.owflow/docs/project/architecture.md` exists:
+  1. Invoke Skill tool: `diagrams-mermaid`
+  2. Pass context from analysis + generated architecture content
+  3. Add Mermaid sections that **refine** the document:
+     - `## Visual Architecture Context` (prefer `C4Context` or `C4Container`)
+     - `## Component Communication Flow` (prefer `sequenceDiagram` or `flowchart`)
+  4. Keep existing architecture narrative intact; diagrams must supplement, not replace sections.
+
+- If Tech Stack doc is selected and `.owflow/docs/project/tech-stack.md` exists:
+  1. Invoke Skill tool: `diagrams-mermaid`
+  2. Add one lightweight visual section (e.g., runtime/build dependency flow) only if context is sufficient
+  3. If context is insufficient, keep text-only output and list missing details (no invented dependencies).
+
 ---
 
 ## PHASE 7: Validate

package/dist/skills/html-renderer/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: html-renderer
+description: Render a markdown plan, idea, RFC, or design note into a self-contained, share-ready HTML file using the warm editorial visual system bundled under `references/`. Use this skill whenever the user asks to "render", "convert", "turn into HTML", "make a nice HTML version", "share this as a page", or "make this look good" for a markdown file containing a plan, proposal, idea, brief, RFC, design note, or pitch — even if they don't explicitly say "HTML". The output is a single .html file with all CSS inlined, written next to the source .md, that visually matches the reference layout in `references/index.html` and uses tokens from `references/tokens.json`.
+disable-model-invocation: true
+user-invocable: true
+---
+
+# HTML Renderer
+
+Turn a markdown plan/idea/RFC into a single self-contained HTML page that follows the warm editorial design system bundled in this skill.
+
+## When to use
+
+The user gives you a markdown file (or pastes markdown) describing a plan, idea, proposal, RFC, design note, or brief, and wants a clean HTML representation they can share. Output is *always* a portable single-file `.html` with the stylesheet inlined — no external assets, no JS.
+
+This skill is opt-in: it does not auto-trigger. The user invokes it explicitly.
+
+## Inputs and outputs
+
+- **Input**: path to a `.md` file (or raw markdown content). If raw markdown is provided, ask for a filename stem.
+- **Output**: write `<source-basename>.html` in the same directory as the source `.md`. If the source is `~/notes/q4-plan.md`, output is `~/notes/q4-plan.html`.
+- **Self-contained**: inline the full stylesheet inside a single `<style>` block in `<head>`. Do not link to external CSS, fonts (use the font stacks already in tokens — they fall back to system fonts), or images that aren't already in the source. The one allowed external script is Mermaid (see "Mermaid diagrams" below), and only when the source contains at least one ` ```mermaid ` fence.
+- **Title**: use the first `# H1` from the markdown as `<title>`; if none, fall back to the file's basename humanized.
+
+## Reference files (read these before writing output)
+
+The `references/` folder is the source of truth for the visual system. Read each file once at the start of a rendering task so the output matches:
+
+- `references/index.html` — canonical reference page showing every component (heading scale, text block, cards, table, diagram, quote, highlights). Use it as the structural template: the output should look like a variant of this page filled with the user's content.
+- `references/styles.css` — every `hr-*` class definition. **Copy this verbatim into the inlined `<style>` block** of the output. Do not paraphrase, rewrite, or trim it; the classes you emit in the HTML must resolve against these exact rules.
+- `references/tokens.json` — design tokens (colors, spacing, radius, typography). The CSS already consumes these via `:root` variables, so tokens.json is mostly informational — consult it only if the user asks to tweak colors/spacing or when you need to add a new component that should harmonize with existing tokens.
+
+Reuse existing classes and tokens before inventing anything. If the user asks for something genuinely new, declare any new CSS variables in `:root` using the same naming pattern, and keep class names prefixed with `hr-`.
+
+## Workflow
+
+1. **Resolve input**: confirm the source markdown path; read the file.
+2. **Load references**: read `references/index.html` (structure), `references/styles.css` (full CSS to inline), and `references/tokens.json` (only if you need token values).
+3. **Plan structure**: scan the markdown and decide how to group content into `<section class="hr-section hr-stack">` blocks. Each top-level `##` typically opens a new section.
+4. **Map elements** using the mapping table below.
+5. **Assemble** a single HTML document:
+   - `<!doctype html>` + `<html lang="en">` + `<head>` with `<meta charset>`, `<meta viewport>`, `<title>`, and a `<style>` block containing the *entire* contents of `references/styles.css`.
+   - `<body>` containing `<main class="hr-page">` wrapping the sectioned content.
+6. **Write** the file as `<basename>.html` next to the source.
+7. **Verify**: re-open the output and confirm every `class="hr-..."` you emitted exists in the inlined CSS.
+
+## Markdown → HTML mapping
+
+| Markdown | HTML |
+|---|---|
+| `# Title` (first one) | `<h1 class="hr-heading-h1">` (also sets `<title>`) |
+| `##`, `###`, `####` | `<h2 class="hr-heading-h2">`, `<h3 class="hr-heading-h3">`, `<h4 class="hr-heading-h4">` |
+| Eyebrow line (italic small intro before H1, e.g. `_Reference Base_`) | `<span class="hr-heading-eyebrow">` |
+| Paragraphs & lists in narrative flow | wrap in `<div class="hr-text-block hr-stack">` |
+| Short summary paragraph right under H1 | `<p class="hr-text-muted">` |
+| Unordered/ordered lists | plain `<ul>`/`<ol>` inside `hr-text-block` |
+| `**bold**` / `*italic*` | `<strong>` / `<em>` |
+| Inline `` `code` `` | `<code>` |
+| Links `[text](url)` | `<a href="url">text</a>` |
+| Horizontal rule `---` | new `<section class="hr-section hr-stack">` (prefer sectioning over `<hr>`) |
+| Tables | `<div class="hr-table-wrap"><table class="hr-table">…</table></div>` |
+| Blockquote `>` | `<blockquote class="hr-quote">`; if the last line starts with `— `, render as `<footer>` |
+| ` ```mermaid ` code fence | `<div class="hr-diagram"><div class="mermaid">…raw mermaid source, **not** HTML-escaped…</div></div>` (also include the Mermaid script described in "Mermaid diagrams" below) |
+| Any other fenced code | `<pre><code>…</code></pre>` (escape `<`, `>`, `&`) |
+| Admonitions — lines starting with `> [!NOTE]`, `> [!WARNING]`, `> [!IMPORTANT]` (GitHub-style) or sections prefixed `**Note:**`, `**Warning:**`, `**Important:**` | `<aside class="hr-highlight hr-highlight-{note\|warning\|important}">` with `<p class="hr-highlight-title">` for the label |
+| Card-like content — a bolded title followed by 1–3 lines, especially in a list of similar items | `<article class="hr-card">` with `<h3 class="hr-card-title">` and `<p class="hr-card-text">`. Wrap multiple cards in `<div class="hr-grid">` (auto-fit). For fixed layouts use `hr-grid-2`, `hr-grid-3`, `hr-grid-4`, `hr-grid-feature` (2fr/1fr/1fr with `hr-card-featured` first), or `hr-grid-sidebar` (2fr/1fr). Mark the most important card as `hr-card-featured`. |
+| Tags / labels (e.g. `[Priority]`, `[Default]`) | `<span class="hr-badge">` |
+
+When the markdown is ambiguous (e.g., "is this a card or a paragraph?"), prefer the simpler choice: text block first, cards only when the content is clearly a set of parallel small items.
+
+## Rendering rules
+
+1. Every class you emit must be prefixed `hr-` and must exist in `references/styles.css`. If you need a new one, also add its rule to the inlined `<style>` and (if it relies on a new token) extend `:root`.
+2. No inline `style="…"` attributes unless the user explicitly asks for a one-off override.
+3. Favor semantic tags (`section`, `article`, `aside`, `blockquote`, `table`, `figure`) and apply `hr-*` classes on top of them.
+4. Escape HTML special characters in content (`<`, `>`, `&`) so user prose never breaks the page.
+5. **Keep the output a single file with zero external dependencies** — it must render correctly when opened directly in a browser. The one exception is the Mermaid CDN script, which is only injected when ` ```mermaid ` fences are present; users will need network access to see those diagrams render (the raw mermaid source remains in the DOM as a graceful fallback).
+
+## Mermaid diagrams
+
+When the source markdown contains one or more ` ```mermaid ` fences:
+
+1. Render each fence as:
+   ```html
+   <div class="hr-diagram">
+     <div class="mermaid">
+   …raw mermaid source, preserved verbatim, NOT HTML-escaped…
+     </div>
+   </div>
+   ```
+   Mermaid replaces the inner text with an SVG at page load, so the content must stay as plain text (do not wrap it in `<pre><code>` and do not escape `<`, `>`, `&` — mermaid needs the original characters).
+2. Inject the Mermaid script + initializer immediately before `</body>`, exactly once per document:
+   ```html
+   <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+   <script>
+     window.mermaid &&
+       mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+   </script>
+   ```
+3. If the markdown has no ` ```mermaid ` fences, **do not** add the script — keep the output fully offline.
+
+## Minimal example
+
+Input (`idea.md`):
+```markdown
+# Lightweight RFC inbox
+
+A small daily ritual to capture half-formed ideas without losing them.
+
+## Why
+Ideas evaporate within a day if there's no easy capture path.
+
+## How
+- One markdown file per idea
+- Rendered to HTML on demand for sharing
+
+> [!NOTE]
+> This is intentionally low-tech: no database, no auth.
+```
+
+Output (`idea.html`, abbreviated):
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Lightweight RFC inbox</title>
+    <style>/* entire contents of references/styles.css inlined here */</style>
+  </head>
+  <body>
+    <main class="hr-page">
+      <section class="hr-section hr-stack">
+        <h1 class="hr-heading-h1">Lightweight RFC inbox</h1>
+        <p class="hr-text-muted">A small daily ritual to capture half-formed ideas without losing them.</p>
+      </section>
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Why</h2>
+        <div class="hr-text-block hr-stack">
+          <p>Ideas evaporate within a day if there's no easy capture path.</p>
+        </div>
+      </section>
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">How</h2>
+        <div class="hr-text-block hr-stack">
+          <ul>
+            <li>One markdown file per idea</li>
+            <li>Rendered to HTML on demand for sharing</li>
+          </ul>
+        </div>
+        <aside class="hr-highlight hr-highlight-note">
+          <p class="hr-highlight-title">Note</p>
+          <p>This is intentionally low-tech: no database, no auth.</p>
+        </aside>
+      </section>
+    </main>
+  </body>
+</html>
+```