@creator-notes/cli 0.2.20 → 0.2.23

package/skills/cn/SKILL.md

@@ -100,7 +100,13 @@ cn canvas add-richtext <canvasId> --content "<content>" [--size small|medium|lar
 cn canvas add-list <canvasId> --name "<name>" --notes <id1,id2,...> [--view list|grid] [--x <n>] [--y <n>]
 cn canvas add-link <canvasId> --target <otherCanvasId> [--x <n>] [--y <n>]
 
-# Bulk add multiple notes at once (more efficient than repeated add-node)
+# Place items using a declarative layout (NO x/y math — server packs them)
+# This is the PREFERRED way to add multiple items. See "Canvas Layout" below.
+cn canvas place <canvasId> --spec ./layout.json
+cn canvas place <canvasId> --spec-stdin                  # JSON from stdin
+cn canvas place <canvasId> --spec-inline '<short JSON>'  # for tiny specs only
+
+# Bulk add with explicit positions (escape hatch — only for pixel-perfect templates)
 cn canvas bulk-add <canvasId> --notes '[{"noteId":"NOTE-1","x":100,"y":100},{"noteId":"NOTE-2","x":400,"y":100}]'
 
 # Move / remove nodes
@@ -230,109 +236,177 @@ cn config set-server <url>
 
 ### Canvas Layout
 
-When adding 3+ items to a canvas, **plan all positions upfront** and use `bulk-add` in a single call instead of repeated `add-node` calls.
-
-#### Grid Cell System (Note Units)
-
-All canvas positioning uses a **note unit (1u)** as the base measurement. 1u = 400px wide × 180px tall. Every item type has a known width in note units — you must account for this when planning layouts.
-
-| Item type | Width (px) | Width (u) | Height (px) | Height (u) |
-|-----------|-----------|-----------|-------------|------------|
-| Note node | 400 | 1.0 | 180 | 1.0 |
-| Text node | ~280 | 0.7 | ~40 | 0.2 |
-| Richtext small | 560 | 1.4 | varies | varies |
-| Richtext medium | 1120 | 2.8 | varies | varies |
-| Richtext large | 1680 | 4.2 | varies | varies |
-| List node (grid) | 580 | 1.45 | 160+ | varies |
-| Canvas link | 400 | 1.0 | 80 | 0.4 |
-| Edge label | ~80 | 0.2 | ~14 | — |
-
-Node center offset from top-left: `(+140, +50)`.
+**Don't compute coordinates by hand. Use `cn canvas place` with a layout spec.**
 
-#### Richtext Nodes
+The server measures every item, packs them into a no-overlap layout, and inserts them in a single batch. You describe **structure** (rows, columns, what's near what) — the server resolves pixels. This is what `cn canvas place` is for, and you should reach for it whenever you're adding more than one item.
 
-Use `add-richtext` for formatted content with headings, lists, bold, italic, and code blocks:
+The call is **best-effort, not transactional** — per-item failures are reported in the response (HTTP 207) but the items that succeeded stay on the canvas. Always inspect `items[].error` and `edges[].error` before assuming success.
 
-| Size | Width (px) | Width (u) | Use for |
-|------|-----------|-----------|---------|
-| `small` (default) | 560 | 1.4 | Annotations, callouts, small formatted notes |
-| `medium` | 1120 | 2.8 | Section descriptions, formatted explanations |
-| `large` | 1680 | 4.2 | Billboard-scale hero text, full-width banners |
+Use `cn canvas bulk-add` with explicit `x/y` ONLY for pixel-perfect templates (e.g. demo recordings or tutorial walkthroughs that need to match a specific screenshot).
 
-Optional `--color` sets a tinted background (hex, e.g. `#3B82F6` blue, `#F59E0B` amber, `#6366F1` indigo).
+#### The layout DSL
 
-**Content via file (IMPORTANT):** For multi-line richtext, **always use `--content-file`**: write markdown to a temp file first, then pass the path. Inline `--content` does NOT interpret `\n` as newlines — bash passes literal backslash-n, which renders as broken text.
+A layout document is `{ root, edges?, origin? }` where `root` is one of four node kinds:
 
-**Richtext height is dynamic** — it depends on content length, font size, and padding (colored nodes have much larger padding). The server computes `estimatedHeight` (px) and returns it in the JSON response from `add-richtext` and `bulk-add` (for richtext items).
-
-**Workflow:** Create richtext nodes first with `--json`, read `estimatedHeight` from the response, then use it to calculate positions for items below: `nextY = richtextY + estimatedHeight + vGap`.
+- **`stack`** — items flow along one axis (like CSS flexbox)
+  ```json
+  { "kind": "stack", "axis": "vertical", "gap": "medium",
+    "align": "start", "items": [ /* LayoutNode */ ] }
+  ```
+- **`grid`** — N columns, items wrap to new rows (like CSS grid auto-flow)
+  ```json
+  { "kind": "grid", "columns": 3, "gap": "medium",
+    "items": [ /* LayoutNode */ ] }
+  ```
+- **`anchor`** — place a sub-tree relative to an EXISTING canvas node
+  ```json
+  { "kind": "anchor", "to": "NOTE-12", "direction": "right",
+    "gap": "medium", "child": /* LayoutNode */ }
+  ```
+- **`item`** — a leaf node (no x/y!). One per visible thing on the canvas.
 
-**Fallback estimates** (only when you can't create richtext first):
+`gap` accepts a preset (`"tight"`, `"medium"`, `"spacious"`) or a raw pixel number. Defaults to `"medium"`.
 
-| Size | Colored | Uncolored |
-|------|---------|-----------|
-| small | 1.5u (270px) | 1u (180px) |
-| medium | 2u (360px) | 1.5u (270px) |
-| large | 2.5u (450px) | 2u (360px) |
+#### Leaf item shapes
 
-**Layout impact — CRITICAL:** A `medium` richtext is 2.8u wide (1120px) — it spans almost 3 note columns. You MUST account for this when planning positions. Items below a richtext must use its actual height (not 180px) to calculate the next row.
+```json
+{ "kind": "item", "type": "note",     "noteId": "NOTE-3", "key": "a" }
+{ "kind": "item", "type": "text",     "content": "Hello", "fontSize": 32, "colorVariant": "muted" }
+{ "kind": "item", "type": "richtext", "content": "# Markdown OK", "size": "medium", "colorHex": "#3B82F6" }
+{ "kind": "item", "type": "list",     "name": "Risks", "noteIds": ["A","B","C"], "viewMode": "list" }
+{ "kind": "item", "type": "canvas",   "linkedCanvasId": "abc..." }
+```
 
-#### Text Node Sizing
+The optional `key` lets edges and other items reference this leaf later (`@<key>`).
 
-| Size | Use for |
-|------|---------|
-| `heading` (default) | Section headers, zone titles, canvas labels |
-| `paragraph` | Descriptions, annotations, supporting context |
+`richtext.content` accepts markdown directly — the server converts to TipTap before measuring.
 
-**Never use ALL CAPS** for text node content. Use title case instead (e.g., "Key Tensions" not "KEY TENSIONS").
+#### Edges
 
-#### Layout Density
+Edges live at the top level alongside `root`. Each endpoint is resolved in this priority order:
 
-Gaps between items are expressed as **multiples of 1u**:
+1. **`@<key>`** — any item placed in the same call that carries a matching `key`
+2. **Original `noteId`** of a note placed in this call (e.g. `"NOTE-7"`) — no `key` needed
+3. **Display id or convex id** of a node already on the canvas
 
-| Density | H gap (px) | V gap (px) | When to use |
-|---------|-----------|-----------|-------------|
-| **tight** | 60 | 27 | Same concern, one board — retro, kanban |
-| **medium** | 200 | 72 | Organized, clear separation — SWOT, roadmap |
-| **spacious** | 400 | 144 | Distinct topics, breathing room |
+```json
+"edges": [
+  { "from": "@a", "to": "@b", "label": "depends on" },
+  { "from": "NOTE-7", "to": "@a" }
+]
+```
 
-#### Positioning Algorithm (Notes Only)
+#### Examples
+
+**Fan-out under a heading** (the failure case the agent kept getting wrong):
+```json
+{
+  "root": {
+    "kind": "stack", "axis": "vertical", "gap": "medium",
+    "items": [
+      { "kind": "item", "type": "richtext",
+        "content": "# Goals\nWhat we're committing to this quarter.",
+        "size": "medium" },
+      { "kind": "grid", "columns": 4,
+        "items": [
+          { "kind": "item", "type": "note", "noteId": "GOAL-1" },
+          { "kind": "item", "type": "note", "noteId": "GOAL-2" },
+          { "kind": "item", "type": "note", "noteId": "GOAL-3" },
+          { "kind": "item", "type": "note", "noteId": "GOAL-4" }
+        ] }
+    ]
+  }
+}
+```
 
-1. **Build the graph** — list all notes and their relationships.
-2. **Assign ranks** — Rank 0 for root nodes (no incoming edges), Rank N = `max(parent ranks) + 1`.
-3. **Calculate positions** — `Y = 100 + rank × (180 + vGap)`. Center each rank horizontally with `(400 + hGap)` spacing.
-4. **Use `bulk-add`** for all notes, then add edges with `add-edge`.
+**SWOT-style four-quadrant layout**:
+```json
+{
+  "root": {
+    "kind": "stack", "axis": "vertical", "gap": "spacious",
+    "items": [
+      { "kind": "stack", "axis": "horizontal", "gap": "spacious", "items": [
+        { "kind": "grid", "columns": 2, "items": [
+          { "kind": "item", "type": "note", "noteId": "STR-1" },
+          { "kind": "item", "type": "note", "noteId": "STR-2" }
+        ] },
+        { "kind": "grid", "columns": 2, "items": [
+          { "kind": "item", "type": "note", "noteId": "WEAK-1" }
+        ] }
+      ] },
+      { "kind": "stack", "axis": "horizontal", "gap": "spacious", "items": [
+        { "kind": "grid", "columns": 2, "items": [
+          { "kind": "item", "type": "note", "noteId": "OPP-1" }
+        ] },
+        { "kind": "grid", "columns": 2, "items": [
+          { "kind": "item", "type": "note", "noteId": "THR-1" }
+        ] }
+      ] }
+    ]
+  }
+}
+```
 
-#### Mixed-Type Layout (Notes + Richtext + Text)
+**Anchor a new column to the right of an existing note**:
+```json
+{
+  "root": {
+    "kind": "anchor", "to": "NOTE-12", "direction": "right", "gap": "medium",
+    "child": {
+      "kind": "stack", "axis": "vertical", "gap": "tight",
+      "items": [
+        { "kind": "item", "type": "note", "noteId": "NEW-1" },
+        { "kind": "item", "type": "note", "noteId": "NEW-2" }
+      ]
+    }
+  }
+}
+```
 
-When a canvas mixes node types, plan as a **row-based grid** where each row's Y depends on the tallest item in the previous row.
+**Diamond topology with edges**:
+```json
+{
+  "root": {
+    "kind": "stack", "axis": "vertical", "gap": "medium", "align": "center",
+    "items": [
+      { "kind": "item", "type": "note", "noteId": "A", "key": "root" },
+      { "kind": "stack", "axis": "horizontal", "gap": "medium", "items": [
+        { "kind": "item", "type": "note", "noteId": "B", "key": "left" },
+        { "kind": "item", "type": "note", "noteId": "C", "key": "right" }
+      ] },
+      { "kind": "item", "type": "note", "noteId": "D", "key": "tail" }
+    ]
+  },
+  "edges": [
+    { "from": "@root", "to": "@left" },
+    { "from": "@root", "to": "@right" },
+    { "from": "@left", "to": "@tail" },
+    { "from": "@right", "to": "@tail" }
+  ]
+}
+```
 
-**Execution order:**
-1. Create richtext/text nodes first (`add-richtext --json`) — capture `estimatedHeight` from response
-2. Calculate note positions using actual richtext heights for Y offsets
-3. `bulk-add` all notes with correctly calculated positions
-4. `add-edge` for all connections
+#### Workflow
 
-**Row Y calculation:**
-```
-Row 0 Y = 100
-Row 1 Y = Row0_Y + tallestItemInRow0 + vGap
-Row 2 Y = Row1_Y + tallestItemInRow1 + vGap
-```
+1. Write the layout doc to a temp file (`/tmp/layout.json`).
+2. Run `cn canvas place <canvasId> --spec /tmp/layout.json --json`.
+3. The response includes `items[]` (with resolved `positionX/Y`, `width`, `height`, `id`, and your `key`), `edges[]` (with resolved edge ids), and `bbox` (the bounding box of the whole layout).
 
-**Row X calculation** — place items left-to-right using actual widths:
-```
-Item 1: x = 100, right edge = 100 + itemWidth
-Item 2: x = rightEdge1 + hGap
-```
+#### Constraints
 
-#### Common Topologies
+- **Anchors take zero space in their parent** — when nested inside a `stack` or `grid`, an anchor reserves no slot, so siblings collapse together. Anchors are best used at the root or as their own top-level branch.
+- **Anchor `to:` must be a node already on the canvas** — local `@key` refs only work for edges, not for anchor targets in this version.
+- **Never use ALL CAPS** for text node content. Use title case (e.g., "Key Tensions" not "KEY TENSIONS").
+- **Multi-line richtext content** is best authored as markdown — the server converts it server-side.
 
-**Linear chain** (A→B→C→D): stack vertically at X=300, Y increments of `180 + vGap`.
+#### When the layout engine isn't enough
 
-**Fan-out** (A→B, A→C, A→D): root on top, children spread horizontally at `400 + hGap` intervals.
+A few cases still need explicit `x/y` via `bulk-add`:
+- Reproducing a canvas pixel-for-pixel for a demo/screenshot
+- Templates with intentional off-grid placement
+- Adding a single item next to a known coordinate without invoking the solver
 
-**Diamond** (A→B, A→C, B→D, C→D): 2-column layout centered under root.
+In all other cases — and especially when adding 3+ items at once — use `place`.
 
 ### Interlinking Notes