obc-cli2 0.2.3 → 0.2.6

package/.next/standalone/.openboard/excalidraw-guide.md

@@ -1,314 +1,314 @@
-# openboard — Excalidraw JSON Guide for Claude
-
-openboard stores the shared whiteboard at `.openboard/board.json`.
-You can read and write this file directly with your file tools.
-The browser polls every 1 second and reflects your changes automatically.
-
----
-
-## board.json structure
-
-```json
-{
-  "elements": [ ...ExcalidrawElement ],
-  "files": {}
-}
-```
-
-Never include `appState` — `appState.collaborators` is a Map and breaks JSON serialization.
-
----
-
-## Design principles
-
-**Always produce rich, visually structured diagrams.** A board that uses only rectangles and plain text is a bad board. Apply these principles every time:
-
-1. **Use diverse shapes** — choose the shape that best matches the semantic meaning (see shape guide below).
-2. **Express hierarchy clearly** — title size > section label > body text; use indentation, grouping, and color zones.
-3. **Be detailed** — include enough text that the user understands without asking follow-up questions. Prefer more cards over less.
-4. **Use color intentionally** — assign a consistent color per zone/category across the whole board.
-5. **Connect related elements** — use arrows to show flow, dependency, or sequence.
-
----
-
-## Shape semantics — when to use what
-
-| Shape | `type` | Best used for |
-| --- | --- | --- |
-| Rectangle | `"rectangle"` | General containers, cards, sections, lists |
-| Diamond | `"diamond"` | Decision points, key choices, branch nodes |
-| Ellipse / Circle | `"ellipse"` | States, actors, start/end nodes, highlights |
-| Arrow | `"arrow"` | Flow, dependency, sequence, causation |
-| Line | `"line"` | Visual dividers, separators, axis |
-| Text (free) | `"text"` | Labels, annotations, titles outside containers |
-
-> **Do not use only rectangles.** Vary shapes to make the diagram scannable at a glance.
-
----
-
-## Visual hierarchy — font sizes
-
-Use these sizes consistently to establish hierarchy:
-
-| Level | Role | `fontSize` |
-| --- | --- | --- |
-| H1 | Board title / section heading | `36` |
-| H2 | Sub-section label | `24` |
-| H3 | Card title | `20` |
-| Body | Content inside cards | `16` |
-| Caption | Small annotations | `13` |
-
----
-
-## Font families
-
-| `fontFamily` | Appearance | Use for |
-| --- | --- | --- |
-| `1` | Virgil — hand-drawn | General diagrams, informal notes |
-| `2` | Helvetica — clean sans-serif | Professional / polished layouts |
-| `3` | Cascadia — monospace | Code, file paths, technical values |
-| `4` | Nunito — rounded | Friendly UI mockups |
-
----
-
-## Color palette guide
-
-Pick one background color per semantic zone and use it consistently.
-
-| Zone | Suggested `backgroundColor` | `strokeColor` |
-| --- | --- | --- |
-| Info / Overview | `"#dbeafe"` (blue-100) | `"#1d4ed8"` |
-| Success / Done | `"#dcfce7"` (green-100) | `"#15803d"` |
-| Warning / In-progress | `"#fef9c3"` (yellow-100) | `"#a16207"` |
-| Danger / Blocked | `"#fee2e2"` (red-100) | `"#b91c1c"` |
-| Neutral / Context | `"#f3f4f6"` (gray-100) | `"#374151"` |
-| Purple / Special | `"#ede9fe"` (violet-100) | `"#6d28d9"` |
-
----
-
-## Required fields for every element
-
-| field | notes |
-| --- | --- |
-| `type` | `"rectangle"` / `"text"` / `"arrow"` / `"ellipse"` / `"diamond"` / `"line"` |
-| `id` | unique string across all elements |
-| `x`, `y` | position (numbers) |
-| `width`, `height` | size (numbers) |
-| `index` | `"a0"`, `"a1"`, `"a2"` … unique and ascending |
-| `version` | `1` |
-| `versionNonce` | any integer |
-| `updated` | `Date.now()` integer |
-| `isDeleted` | `false` |
-| `fillStyle` | `"solid"` |
-| `strokeWidth` | `2` |
-| `strokeStyle` | `"solid"` |
-| `roughness` | `1` |
-| `opacity` | `100` |
-| `angle` | `0` |
-| `strokeColor` | hex string e.g. `"#1e1e1e"` |
-| `seed` | any integer |
-| `groupIds` | `[]` |
-| `frameId` | `null` |
-| `roundness` | `null` (or `{"type":3}` for rounded corners) |
-| `boundElements` | `[]` |
-| `link` | `null` |
-| `locked` | `false` |
-
----
-
-## Element reference
-
-### rectangle
-
-```json
-{
-  "type": "rectangle",
-  "backgroundColor": "#dbeafe",
-  "strokeColor": "#1d4ed8",
-  "roundness": {"type": 3}
-}
-```
-
-- Use `roundness: {"type": 3}` for modern rounded cards.
-- `backgroundColor` is the fill; `strokeColor` is the border.
-
-### ellipse
-
-```json
-{
-  "type": "ellipse",
-  "width": 120,
-  "height": 60,
-  "backgroundColor": "#dcfce7",
-  "strokeColor": "#15803d"
-}
-```
-
-- For a perfect circle, set `width === height`.
-
-### diamond
-
-```json
-{
-  "type": "diamond",
-  "width": 160,
-  "height": 100,
-  "backgroundColor": "#fef9c3",
-  "strokeColor": "#a16207"
-}
-```
-
-### line (divider)
-
-```json
-{
-  "type": "line",
-  "points": [[0, 0], [400, 0]],
-  "strokeColor": "#d1d5db",
-  "strokeWidth": 1,
-  "startBinding": null,
-  "endBinding": null,
-  "startArrowhead": null,
-  "endArrowhead": null
-}
-```
-
-### text (standalone label)
-
-```json
-{
-  "type": "text",
-  "text": "Section Title",
-  "originalText": "Section Title",
-  "fontSize": 24,
-  "fontFamily": 1,
-  "textAlign": "left",
-  "verticalAlign": "top",
-  "containerId": null,
-  "autoResize": true,
-  "lineHeight": null
-}
-```
-
-- **`fontSize` is mandatory** — text is invisible without it.
-- **`backgroundColor` has NO effect on text.** Use a rectangle + `containerId` to show a background color.
-
-### text inside a rectangle (card pattern)
-
-```json
-[
-  {
-    "type": "rectangle",
-    "id": "card-bg",
-    "x": 40, "y": 40, "width": 300, "height": 180,
-    "backgroundColor": "#dbeafe",
-    "strokeColor": "#1d4ed8",
-    "roundness": {"type": 3},
-    "boundElements": [{"type": "text", "id": "card-text"}],
-    "index": "a0",
-    "version": 1, "versionNonce": 1, "updated": 1700000000000,
-    "isDeleted": false, "fillStyle": "solid", "strokeWidth": 2,
-    "strokeStyle": "solid", "roughness": 1, "opacity": 100,
-    "angle": 0, "seed": 1, "groupIds": [], "frameId": null,
-    "link": null, "locked": false
-  },
-  {
-    "type": "text",
-    "id": "card-text",
-    "x": 52, "y": 52, "width": 276, "height": 156,
-    "containerId": "card-bg",
-    "text": "Card title\n\nBody content here",
-    "originalText": "Card title\n\nBody content here",
-    "fontSize": 16,
-    "fontFamily": 1,
-    "textAlign": "left",
-    "verticalAlign": "top",
-    "autoResize": true,
-    "lineHeight": null,
-    "index": "a1",
-    "version": 1, "versionNonce": 2, "updated": 1700000000000,
-    "isDeleted": false, "fillStyle": "solid", "strokeWidth": 2,
-    "strokeStyle": "solid", "roughness": 1, "opacity": 100,
-    "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "transparent",
-    "seed": 2, "groupIds": [], "frameId": null, "roundness": null,
-    "boundElements": [], "link": null, "locked": false
-  }
-]
-```
-
-- Text `x`/`y` = rectangle `x`/`y` + 12px inset on each side.
-- Text `width` = rectangle `width` − 24, `height` = rectangle `height` − 24.
-- Rectangle `boundElements` must list the text id.
-
-### arrow
-
-```json
-{
-  "type": "arrow",
-  "points": [[0, 0], [160, 0]],
-  "startBinding": null,
-  "endBinding": null,
-  "startArrowhead": null,
-  "endArrowhead": "arrow",
-  "strokeColor": "#374151",
-  "elbowed": false
-}
-```
-
-- To attach to shapes, set `startBinding` / `endBinding`:
-
-```json
-"startBinding": { "elementId": "shape-a", "focus": 0, "gap": 6 },
-"endBinding":   { "elementId": "shape-b", "focus": 0, "gap": 6 }
-```
-
-- `endArrowhead`: `"arrow"` (default) / `"triangle"` / `"dot"` / `"bar"` / `null` (no head).
-- `startArrowhead`: same options (use for bidirectional).
-
----
-
-## Layout patterns
-
-### Hierarchical tree (top → down)
-- Board title as large standalone `text` at top-left (`fontSize: 36`).
-- Section headers as `text` labels (`fontSize: 24`) above each group.
-- Cards (`rectangle` + `text`) arranged in rows with ~20px gap.
-- `arrow` elements pointing downward between levels.
-
-### Flow diagram (left → right)
-- `ellipse` for start/end nodes.
-- `rectangle` (rounded) for process steps.
-- `diamond` for decision branches.
-- Horizontal `arrow` elements connecting each step.
-
-### Zone-based overview (color blocks)
-- Large background `rectangle` per zone (low opacity or light color) as a backdrop.
-- Cards layered on top within each zone.
-- Zone label as a bold `text` element at the top of each zone.
-- Use different `backgroundColor` per zone (see color palette above).
-
----
-
-## Common mistakes
-
-| mistake | fix |
-| --- | --- |
-| `backgroundColor` on a `text` element | Use `rectangle` + `containerId` pattern |
-| Missing `fontSize` on text | Add `"fontSize": 16` (minimum) |
-| Missing `index` field | Add unique ascending `"a0"`, `"a1"`, … |
-| Duplicate `id` values | Every element needs a globally unique `id` |
-| Saving `appState` | Never include `appState` in board.json |
-| `files` key missing | Always include `"files": {}` |
-| Only using rectangles | Use diamonds, ellipses, lines, and arrows too |
-| All text the same size | Use H1/H2/H3/Body hierarchy (36/24/20/16) |
-| No color differentiation | Assign one color per zone/category |
-
----
-
-## Workflow
-
-1. **Read** `.openboard/board.json` to understand the current board state.
-2. **Plan** the layout: identify zones, hierarchy levels, and element types needed.
-3. **Write** the complete updated JSON back to `.openboard/board.json`.
-4. The browser reflects changes within 1 second automatically.
-5. Always read before writing — the user may have made edits in the browser.
+# openboard — Excalidraw JSON Guide for Claude
+
+openboard stores the shared whiteboard at `.openboard/board.json`.
+You can read and write this file directly with your file tools.
+The browser polls every 1 second and reflects your changes automatically.
+
+---
+
+## board.json structure
+
+```json
+{
+  "elements": [ ...ExcalidrawElement ],
+  "files": {}
+}
+```
+
+Never include `appState` — `appState.collaborators` is a Map and breaks JSON serialization.
+
+---
+
+## Design principles
+
+**Always produce rich, visually structured diagrams.** A board that uses only rectangles and plain text is a bad board. Apply these principles every time:
+
+1. **Use diverse shapes** — choose the shape that best matches the semantic meaning (see shape guide below).
+2. **Express hierarchy clearly** — title size > section label > body text; use indentation, grouping, and color zones.
+3. **Be detailed** — include enough text that the user understands without asking follow-up questions. Prefer more cards over less.
+4. **Use color intentionally** — assign a consistent color per zone/category across the whole board.
+5. **Connect related elements** — use arrows to show flow, dependency, or sequence.
+
+---
+
+## Shape semantics — when to use what
+
+| Shape | `type` | Best used for |
+| --- | --- | --- |
+| Rectangle | `"rectangle"` | General containers, cards, sections, lists |
+| Diamond | `"diamond"` | Decision points, key choices, branch nodes |
+| Ellipse / Circle | `"ellipse"` | States, actors, start/end nodes, highlights |
+| Arrow | `"arrow"` | Flow, dependency, sequence, causation |
+| Line | `"line"` | Visual dividers, separators, axis |
+| Text (free) | `"text"` | Labels, annotations, titles outside containers |
+
+> **Do not use only rectangles.** Vary shapes to make the diagram scannable at a glance.
+
+---
+
+## Visual hierarchy — font sizes
+
+Use these sizes consistently to establish hierarchy:
+
+| Level | Role | `fontSize` |
+| --- | --- | --- |
+| H1 | Board title / section heading | `36` |
+| H2 | Sub-section label | `24` |
+| H3 | Card title | `20` |
+| Body | Content inside cards | `16` |
+| Caption | Small annotations | `13` |
+
+---
+
+## Font families
+
+| `fontFamily` | Appearance | Use for |
+| --- | --- | --- |
+| `1` | Virgil — hand-drawn | General diagrams, informal notes |
+| `2` | Helvetica — clean sans-serif | Professional / polished layouts |
+| `3` | Cascadia — monospace | Code, file paths, technical values |
+| `4` | Nunito — rounded | Friendly UI mockups |
+
+---
+
+## Color palette guide
+
+Pick one background color per semantic zone and use it consistently.
+
+| Zone | Suggested `backgroundColor` | `strokeColor` |
+| --- | --- | --- |
+| Info / Overview | `"#dbeafe"` (blue-100) | `"#1d4ed8"` |
+| Success / Done | `"#dcfce7"` (green-100) | `"#15803d"` |
+| Warning / In-progress | `"#fef9c3"` (yellow-100) | `"#a16207"` |
+| Danger / Blocked | `"#fee2e2"` (red-100) | `"#b91c1c"` |
+| Neutral / Context | `"#f3f4f6"` (gray-100) | `"#374151"` |
+| Purple / Special | `"#ede9fe"` (violet-100) | `"#6d28d9"` |
+
+---
+
+## Required fields for every element
+
+| field | notes |
+| --- | --- |
+| `type` | `"rectangle"` / `"text"` / `"arrow"` / `"ellipse"` / `"diamond"` / `"line"` |
+| `id` | unique string across all elements |
+| `x`, `y` | position (numbers) |
+| `width`, `height` | size (numbers) |
+| `index` | `"a0"`, `"a1"`, `"a2"` … unique and ascending |
+| `version` | `1` |
+| `versionNonce` | any integer |
+| `updated` | `Date.now()` integer |
+| `isDeleted` | `false` |
+| `fillStyle` | `"solid"` |
+| `strokeWidth` | `2` |
+| `strokeStyle` | `"solid"` |
+| `roughness` | `1` |
+| `opacity` | `100` |
+| `angle` | `0` |
+| `strokeColor` | hex string e.g. `"#1e1e1e"` |
+| `seed` | any integer |
+| `groupIds` | `[]` |
+| `frameId` | `null` |
+| `roundness` | `null` (or `{"type":3}` for rounded corners) |
+| `boundElements` | `[]` |
+| `link` | `null` |
+| `locked` | `false` |
+
+---
+
+## Element reference
+
+### rectangle
+
+```json
+{
+  "type": "rectangle",
+  "backgroundColor": "#dbeafe",
+  "strokeColor": "#1d4ed8",
+  "roundness": {"type": 3}
+}
+```
+
+- Use `roundness: {"type": 3}` for modern rounded cards.
+- `backgroundColor` is the fill; `strokeColor` is the border.
+
+### ellipse
+
+```json
+{
+  "type": "ellipse",
+  "width": 120,
+  "height": 60,
+  "backgroundColor": "#dcfce7",
+  "strokeColor": "#15803d"
+}
+```
+
+- For a perfect circle, set `width === height`.
+
+### diamond
+
+```json
+{
+  "type": "diamond",
+  "width": 160,
+  "height": 100,
+  "backgroundColor": "#fef9c3",
+  "strokeColor": "#a16207"
+}
+```
+
+### line (divider)
+
+```json
+{
+  "type": "line",
+  "points": [[0, 0], [400, 0]],
+  "strokeColor": "#d1d5db",
+  "strokeWidth": 1,
+  "startBinding": null,
+  "endBinding": null,
+  "startArrowhead": null,
+  "endArrowhead": null
+}
+```
+
+### text (standalone label)
+
+```json
+{
+  "type": "text",
+  "text": "Section Title",
+  "originalText": "Section Title",
+  "fontSize": 24,
+  "fontFamily": 1,
+  "textAlign": "left",
+  "verticalAlign": "top",
+  "containerId": null,
+  "autoResize": true,
+  "lineHeight": null
+}
+```
+
+- **`fontSize` is mandatory** — text is invisible without it.
+- **`backgroundColor` has NO effect on text.** Use a rectangle + `containerId` to show a background color.
+
+### text inside a rectangle (card pattern)
+
+```json
+[
+  {
+    "type": "rectangle",
+    "id": "card-bg",
+    "x": 40, "y": 40, "width": 300, "height": 180,
+    "backgroundColor": "#dbeafe",
+    "strokeColor": "#1d4ed8",
+    "roundness": {"type": 3},
+    "boundElements": [{"type": "text", "id": "card-text"}],
+    "index": "a0",
+    "version": 1, "versionNonce": 1, "updated": 1700000000000,
+    "isDeleted": false, "fillStyle": "solid", "strokeWidth": 2,
+    "strokeStyle": "solid", "roughness": 1, "opacity": 100,
+    "angle": 0, "seed": 1, "groupIds": [], "frameId": null,
+    "link": null, "locked": false
+  },
+  {
+    "type": "text",
+    "id": "card-text",
+    "x": 52, "y": 52, "width": 276, "height": 156,
+    "containerId": "card-bg",
+    "text": "Card title\n\nBody content here",
+    "originalText": "Card title\n\nBody content here",
+    "fontSize": 16,
+    "fontFamily": 1,
+    "textAlign": "left",
+    "verticalAlign": "top",
+    "autoResize": true,
+    "lineHeight": null,
+    "index": "a1",
+    "version": 1, "versionNonce": 2, "updated": 1700000000000,
+    "isDeleted": false, "fillStyle": "solid", "strokeWidth": 2,
+    "strokeStyle": "solid", "roughness": 1, "opacity": 100,
+    "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "transparent",
+    "seed": 2, "groupIds": [], "frameId": null, "roundness": null,
+    "boundElements": [], "link": null, "locked": false
+  }
+]
+```
+
+- Text `x`/`y` = rectangle `x`/`y` + 12px inset on each side.
+- Text `width` = rectangle `width` − 24, `height` = rectangle `height` − 24.
+- Rectangle `boundElements` must list the text id.
+
+### arrow
+
+```json
+{
+  "type": "arrow",
+  "points": [[0, 0], [160, 0]],
+  "startBinding": null,
+  "endBinding": null,
+  "startArrowhead": null,
+  "endArrowhead": "arrow",
+  "strokeColor": "#374151",
+  "elbowed": false
+}
+```
+
+- To attach to shapes, set `startBinding` / `endBinding`:
+
+```json
+"startBinding": { "elementId": "shape-a", "focus": 0, "gap": 6 },
+"endBinding":   { "elementId": "shape-b", "focus": 0, "gap": 6 }
+```
+
+- `endArrowhead`: `"arrow"` (default) / `"triangle"` / `"dot"` / `"bar"` / `null` (no head).
+- `startArrowhead`: same options (use for bidirectional).
+
+---
+
+## Layout patterns
+
+### Hierarchical tree (top → down)
+- Board title as large standalone `text` at top-left (`fontSize: 36`).
+- Section headers as `text` labels (`fontSize: 24`) above each group.
+- Cards (`rectangle` + `text`) arranged in rows with ~20px gap.
+- `arrow` elements pointing downward between levels.
+
+### Flow diagram (left → right)
+- `ellipse` for start/end nodes.
+- `rectangle` (rounded) for process steps.
+- `diamond` for decision branches.
+- Horizontal `arrow` elements connecting each step.
+
+### Zone-based overview (color blocks)
+- Large background `rectangle` per zone (low opacity or light color) as a backdrop.
+- Cards layered on top within each zone.
+- Zone label as a bold `text` element at the top of each zone.
+- Use different `backgroundColor` per zone (see color palette above).
+
+---
+
+## Common mistakes
+
+| mistake | fix |
+| --- | --- |
+| `backgroundColor` on a `text` element | Use `rectangle` + `containerId` pattern |
+| Missing `fontSize` on text | Add `"fontSize": 16` (minimum) |
+| Missing `index` field | Add unique ascending `"a0"`, `"a1"`, … |
+| Duplicate `id` values | Every element needs a globally unique `id` |
+| Saving `appState` | Never include `appState` in board.json |
+| `files` key missing | Always include `"files": {}` |
+| Only using rectangles | Use diamonds, ellipses, lines, and arrows too |
+| All text the same size | Use H1/H2/H3/Body hierarchy (36/24/20/16) |
+| No color differentiation | Assign one color per zone/category |
+
+---
+
+## Workflow
+
+1. **Read** `.openboard/board.json` to understand the current board state.
+2. **Plan** the layout: identify zones, hierarchy levels, and element types needed.
+3. **Write** the complete updated JSON back to `.openboard/board.json`.
+4. The browser reflects changes within 1 second automatically.
+5. Always read before writing — the user may have made edits in the browser.