flowbook 0.2.1 → 0.2.3

package/README.md

@@ -36,7 +36,6 @@ flowbook skill <agent> [-g]  Install AI agent skill & /flowbook command
 ### `flowbook init`
 
 - Adds `"flowbook"` and `"build-flowbook"` scripts to your `package.json`
-- Creates `flows/example.flow.md` as a starter template
 
 ### `flowbook dev`
 

package/dist/cli.js

@@ -1,26 +1,9 @@
 #!/usr/bin/env node
 
 // src/node/init.ts
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { readFileSync, writeFileSync, existsSync } from "fs";
 import { resolve } from "path";
 import { execSync } from "child_process";
-var EXAMPLE_FLOW = `---
-title: Example Flow
-category: Getting Started
-tags: [example]
-order: 1
-description: An example flowchart to get you started
----
-
-\`\`\`mermaid
-flowchart TD
-    A[Start] --> B{Decision}
-    B -->|Yes| C[Action A]
-    B -->|No| D[Action B]
-    C --> E[End]
-    D --> E
-\`\`\`
-`;
 async function initFlowbook() {
   const cwd = process.cwd();
   const pkgPath = resolve(cwd, "package.json");
@@ -55,15 +38,6 @@ async function initFlowbook() {
   } else {
     console.log("  \u2713 Scripts already exist in package.json");
   }
-  const flowsDir = resolve(cwd, "flows");
-  const examplePath = resolve(flowsDir, "example.flow.md");
-  if (!existsSync(examplePath)) {
-    mkdirSync(flowsDir, { recursive: true });
-    writeFileSync(examplePath, EXAMPLE_FLOW);
-    console.log("  \u2713 Created flows/example.flow.md");
-  } else {
-    console.log("  \u2713 Example flow already exists");
-  }
   const gitignorePath = resolve(cwd, ".gitignore");
   if (existsSync(gitignorePath)) {
     const gitignore = readFileSync(gitignorePath, "utf-8");
@@ -235,7 +209,7 @@ async function buildStatic(options) {
 }
 
 // src/node/skill.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, copyFileSync } from "fs";
+import { existsSync as existsSync2, mkdirSync, copyFileSync } from "fs";
 import { resolve as resolve3, dirname as dirname2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { homedir } from "os";
@@ -357,7 +331,7 @@ function resolveAgents(agentArg) {
 function installFile(src, destDir, destFilename) {
   const dest = resolve3(destDir, destFilename);
   if (existsSync2(dest)) return false;
-  mkdirSync2(destDir, { recursive: true });
+  mkdirSync(destDir, { recursive: true });
   copyFileSync(src, dest);
   return true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowbook",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "bin": {
     "flowbook": "./dist/cli.js"

package/src/node/init.ts

@@ -1,26 +1,7 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { execSync } from "node:child_process";
 
-
-const EXAMPLE_FLOW = `---
-title: Example Flow
-category: Getting Started
-tags: [example]
-order: 1
-description: An example flowchart to get you started
----
-
-\`\`\`mermaid
-flowchart TD
-    A[Start] --> B{Decision}
-    B -->|Yes| C[Action A]
-    B -->|No| D[Action B]
-    C --> E[End]
-    D --> E
-\`\`\`
-`;
-
 export async function initFlowbook() {
   const cwd = process.cwd();
   const pkgPath = resolve(cwd, "package.json");
@@ -64,18 +45,6 @@ export async function initFlowbook() {
     console.log("  ✓ Scripts already exist in package.json");
   }
 
-  // 3. Create example flow file
-  const flowsDir = resolve(cwd, "flows");
-  const examplePath = resolve(flowsDir, "example.flow.md");
-
-  if (!existsSync(examplePath)) {
-    mkdirSync(flowsDir, { recursive: true });
-    writeFileSync(examplePath, EXAMPLE_FLOW);
-    console.log("  ✓ Created flows/example.flow.md");
-  } else {
-    console.log("  ✓ Example flow already exists");
-  }
-
   // 4. Add flowbook-static to .gitignore
   const gitignorePath = resolve(cwd, ".gitignore");
   if (existsSync(gitignorePath)) {

package/src/skills/flowbook/SKILL.md

@@ -275,6 +275,37 @@ flowchart TD
     I[\Output\]             %% Reverse parallelogram: response
 ```
 
+#### Label Quoting Rules (MANDATORY)
+
+Node labels containing special characters **MUST** be wrapped in double quotes to prevent Mermaid parse errors.
+
+**Characters that REQUIRE quoting:**
+
+| Character | Why it breaks | Unquoted (BROKEN) | Quoted (CORRECT) |
+|-----------|--------------|-------------------|------------------|
+| `()` | Conflicts with `([...])` stadium and `(...)` rounded shapes | `A([Agent run() Start])` | `A(["Agent run() Start"])` |
+| `{}` | Conflicts with `{...}` diamond shape | `B{tokio::select!{}}` | `B{"tokio::select!{}"}` |
+| `[]` | Conflicts with `[...]` rectangle shape | `C[arr[0] value]` | `C["arr[0] value"]` |
+| `::` | Interpreted as Mermaid class/namespace syntax | `D[std::io::Error]` | `D["std::io::Error"]` |
+| `#` | Interpreted as Unicode escape or comment | `E[Issue #42]` | `E["Issue #42"]` |
+| `&` | Interpreted as HTML entity start | `F[A & B]` | `F["A & B"]` |
+
+**Rule: When in doubt, quote it.** Quoting a label that doesn't need it causes no harm. Unquoted special characters WILL break rendering.
+
+**Examples of correct quoting by node shape:**
+
+```mermaid
+flowchart TD
+    A(["fn main() entry"])         %% Stadium with parens
+    B["process_data(input)"]       %% Rectangle with parens
+    C{"is_valid(x)?"}              %% Diamond with parens
+    D[["handle_error(err)"]]       %% Subroutine with parens
+    E{{"validate(req)"}}           %% Hexagon with parens
+    F["Config::new()"]             %% Rectangle with double colon
+```
+
+**NEVER generate unquoted labels containing `()`, `{}`, `[]`, `::`, `#`, or `&`.**
+
 #### Edge Labels
 
 ```mermaid
@@ -369,7 +400,7 @@ description: POST /api/auth/login — validates credentials and returns JWT toke
 ```mermaid
 flowchart TD
     A([POST /api/auth/login]) --> B[/Parse Request Body/]
-    B --> C{{Validate Email & Password}}
+    B --> C{{"Validate Email & Password"}}
     C -->|Invalid| D[\400 Bad Request/]
     C -->|Valid| E[(Find User by Email)]
     E -->|Not Found| F[\401 Unauthorized/]
@@ -402,6 +433,16 @@ For each generated `.flow.md` file:
 1. Verify YAML frontmatter is valid (title, category present)
 2. Verify mermaid code block is properly fenced (``` mermaid ```)
 3. Verify mermaid syntax has no obvious errors (matched brackets, valid node IDs)
+4. **Special Character Validation (CRITICAL)**: Scan ALL node labels for unquoted special characters:
+   - `()` inside any node shape → MUST be quoted: `A(["label()"])` not `A([label()])`
+   - `{}` inside any node shape → MUST be quoted: `A{"label{}"}` not `A{label{}}`
+   - `[]` inside any node shape → MUST be quoted: `A["label[]"]` not `A[label[]]`
+   - `::` anywhere in labels → MUST be quoted: `A["std::io"]` not `A[std::io]`
+   - `#` anywhere in labels → MUST be quoted: `A["Issue #1"]` not `A[Issue #1]`
+   - `&` anywhere in labels → MUST be quoted: `A["A & B"]` not `A[A & B]`
+   - If ANY unquoted special characters are found, fix them BEFORE proceeding to build
+5. Verify all node IDs are unique within each diagram
+6. Verify subgraph labels don't contain special characters
 
 ### 5.2 Build Verification
 
@@ -483,6 +524,12 @@ Build: ✅ / ❌
 ### Mermaid syntax errors
 - **Brackets**: Every `[`, `{`, `(` must be closed
 - **Special characters in labels**: Wrap in double quotes: `A["User's Input"]`
+- **Parentheses in labels** (MOST COMMON): `A([run() Start])` → Parse error. Fix: `A(["run() Start"])`
+- **Double colons in labels**: `A[std::io::Error]` → Interpreted as class syntax. Fix: `A["std::io::Error"]`
+- **Curly braces in labels**: `B{select!{}}` → Conflicts with diamond shape. Fix: `B{"select!{}"}` 
+- **Square brackets in labels**: `C[arr[0]]` → Conflicts with rectangle shape. Fix: `C["arr[0]"]`
+- **Hash in labels**: `D[Issue #42]` → Unicode escape. Fix: `D["Issue #42"]`
+- **Ampersand in labels**: `E[A & B]` → HTML entity. Fix: `E["A & B"]`
 - **Arrow syntax**: Use `-->` for solid, `-.->` for dotted, `==>` for thick
 - **Node ID reuse**: Each node ID must be unique per diagram. Reuse ID to reference same node.
 - **Subgraph naming**: Subgraph labels cannot contain special characters