@creator-notes/cnotes 0.16.11

package/skills/cnotes/SKILL.md

@@ -0,0 +1,680 @@
+---
+name: cnotes
+description: CreatorNotes CLI for the terminal. The command is `cnotes`. Use when the user mentions CreatorNotes or the cnotes CLI, asks to use this CLI skill, or wants to create, read, update, search, summarize, organize, or visualize notes, canvases, or transcripts in a CreatorNotes workspace. Covers cnotes notes, cnotes canvas, cnotes timeline, cnotes search, cnotes versions, relationships, and operations. Prefer the cnotes CLI, verify the active workspace with cnotes workspace current, use --json when parsing output, and wrap write operations in cnotes operations begin and cnotes operations end.
+metadata:
+  short-description: Work with CreatorNotes via the cnotes CLI
+---
+
+# CreatorNotes CLI (`cnotes`)
+
+A command-line interface for CreatorNotes — create notes, build canvases, search knowledge, and manage workspaces from the terminal.
+
+## Getting Started
+
+### Install
+
+```bash
+npm install -g @creator-notes/cnotes
+```
+
+### Authenticate
+
+```bash
+cnotes auth login           # Opens browser for OAuth
+cnotes auth login --token <key>  # Direct API key
+cnotes auth status          # Check current session
+```
+
+### Select a Workspace
+
+```bash
+cnotes workspace list
+cnotes workspace select <id>
+cnotes workspace current    # Verify active workspace + see its relationship types
+```
+
+`cnotes workspace current` lists the relationship types already defined in the
+workspace. Reuse those labels when cross-linking notes rather than coining new
+ones — see [Relationship mentions](#content-via-markdown).
+
+## Command Reference
+
+### Global Flags (apply to ALL commands)
+```
+--json           Output raw JSON (best for piping / parsing)
+-q, --quiet      Minimal output (IDs only — useful for scripting)
+-w, --workspace <id>   Override active workspace
+--server <url>         Override server URL (default: https://creatornotes.app)
+```
+
+### Reading output (start here)
+
+`cnotes` follows one output contract across every command. Learn it once and you never have to guess.
+
+1. **Success is the exit code, not anything in the body.** Exit `0` means the command succeeded. Never decide success by looking for an `ok` field or a particular key. The body is data; the exit code is the verdict. Failures use a typed table so you can branch on the class of error:
+
+   | exit | meaning | typical fix |
+   |------|---------|-------------|
+   | `0`  | success | n/a |
+   | `2`  | auth required | `cnotes auth login` |
+   | `3`  | validation (bad input) | fix the input shown in the error |
+   | `4`  | not found | the `hint` names the list command to run |
+   | `5`  | conflict (already exists / state collision) | re-fetch and retry |
+   | `6`  | rate limited | back off and retry |
+   | `7`  | permission denied | `cnotes workspace current` |
+
+2. **Reads return their data directly; writes return an envelope.** `cnotes notes list/get/search --json` emit a bare array, so `… --json | jq '.[0].displayId'` works. `cnotes notes create --json` returns an object: `{ results, relationshipsCreated, relationshipTypesCreated }`. The created notes live under **`results`** (not `notes`, not `ok`). Read them with `jq '.results[].displayId'`. Each result carries `displayId` and `title`, the identifiers you reuse next, not only the internal id.
+
+3. **Errors hand you the next move.** A failed command prints `{ error, code, exitCode, hint }` to stderr in `--json` mode. The `hint` is actionable: a wrong workspace id returns a 404 with `resource: "workspace"` and the hint `Run \`cnotes workspace list\``, rather than an opaque 500. Read the `hint` before retrying.
+
+### Notes (`cnotes notes` / `cnotes n`)
+```bash
+# List notes (default 20, excludes drafts)
+cnotes notes list [--search <query>] [--type <type>] [--tags <csv>] [--pinned] [--limit <n>]
+
+# Get one or more notes by display ID (always returns an array, in input order,
+# in a single round-trip). Pass one ID or many — never call this in a loop.
+cnotes notes get <id> [<id>...] [--all-versions] [--content-only]
+cnotes notes get MEETING-12
+cnotes notes get MEETING-12 PRD-3 IDEA-7
+
+# Reading a LARGE note/transcript: --content-only prints just the raw markdown
+# (no JSON envelope, no metadata chrome), so the terminal won't clip a giant
+# JSON line. Best for transcripts you want to read or chunk.
+cnotes notes get TRANSCRIPT-1 --content-only
+cnotes notes get TRANSCRIPT-1 --content-only > /tmp/transcript.md   # then chunk the file
+# Without --content-only, fetch JSON and pull `.content` yourself:
+#   cnotes notes get TRANSCRIPT-1 --json | jq -r '.[0].content'
+# (Reads are a bare array, so a single note is always at .[0].)
+
+# Create one or more notes (always batch-shaped). Pass --notes as a single
+# JSON object or an array. Title comes from the # h1 heading in each note's
+# markdown. Use [@key: Title](relationship:references) to cross-reference
+# another item in the same batch — @key is replaced with the new note's
+# display ID after creation.
+cnotes notes create --notes '{"key":"A","type":"Insight","markdown":"# Solo note","tags":["ux"]}'
+cnotes notes create --notes '[
+  {"key":"A","type":"PainPoint","markdownFile":"./problem.md"},
+  {"key":"B","type":"Insight","markdown":"# Fix\nSee [@A: Problem](relationship:references)."}
+]'
+# Each item: {key, type, markdown | markdownFile, tags?}.
+# On validation failure the response lists every bad item by index + key + field
+# (and `details.items` in --json mode), so you can fix the whole batch in one shot.
+
+# Update metadata only (not content — use versions for that)
+# NOTE: --title is NOT available. Title is read-only, derived from the # h1 heading in version content.
+# To change a note's title, create a new version with a different # h1 heading.
+cnotes notes update <id> [--type <t>] [--tags <csv>] [--archive] [--unarchive] [--pin] [--unpin]
+
+# Delete (archive)
+cnotes notes delete <id>
+
+# Bulk archive/unarchive multiple notes at once
+cnotes notes bulk-archive --ids '["MEETING-1","PRD-3","IDEA-7"]' [--unarchive]
+
+# Bulk retype multiple notes to a new type (atomic per note: creates new, archives old, cross-links)
+cnotes notes bulk-retype --ids '["NOTE-1","NOTE-3","NOTE-5"]' --type Insight
+
+# Text search
+cnotes notes search <query> [--type <type>] [--limit <n>]
+```
+
+### Versions (`cnotes versions` / `cnotes v`)
+```bash
+# List versions
+cnotes versions list <noteId>
+
+# Create a new version (updates note content)
+cnotes versions create <noteId> --description "what changed" --markdown-file <path.md>
+cnotes versions create <noteId> --description "what changed" --markdown "<short content>"  # inline (short only)
+cnotes versions create <noteId> --description "what changed" --markdown-stdin < changes.md
+```
+
+### Canvas (`cnotes canvas` / `cnotes c`)
+```bash
+# List / get (archived canvases excluded by default)
+cnotes canvas list [--include-archived]
+cnotes canvas get <canvasId>
+# `get` returns each node kind in its own array (nodes/textNodes/richtextNodes/
+# listNodes/canvasLinkNodes) AND a unified `allNodes` array — every node flattened
+# to {id, kind, displayId, label, positionX, positionY, width, height} — plus
+# `contentBounds` (the bounding box of everything). Use allNodes/contentBounds to
+# reason about occupancy in one read instead of unioning the per-kind arrays.
+# (You rarely need this for placement — `cnotes canvas place` already avoids overlaps.)
+
+# Read every note on a canvas as one concatenated markdown document, in display
+# order (top-to-bottom, then left-to-right) — think across a canvas in one round-trip
+cnotes canvas read <canvasId>
+
+# AI digest of canvas: narrative summary + per-note summary list for every note on the canvas
+cnotes canvas digest <canvasId>
+
+# Create / update / delete
+cnotes canvas create "<name>" [--goal "<text>"] [--audience "<text>"]
+cnotes canvas update <canvasId> [--title "<text>"] [--goal "<text>"] [--audience "<text>"]
+cnotes canvas delete <canvasId>
+cnotes canvas set-as-home <canvasId>
+cnotes canvas archive <canvasId>
+cnotes canvas unarchive <canvasId>
+
+# Add nodes to canvas
+cnotes canvas add-node <canvasId> --note <noteId> [--x <n>] [--y <n>]
+cnotes canvas add-text <canvasId> --text "<content>" [--size heading|paragraph] [--x <n>] [--y <n>]
+cnotes canvas add-richtext <canvasId> --content-file <path.md> [--size small|medium|large] [--color "#3B82F6"] [--x <n>] [--y <n>]
+cnotes canvas add-richtext <canvasId> --content "<content>" [--size small|medium|large] [--color "#3B82F6"] [--x <n>] [--y <n>]  # inline (short only)
+# A list item is a COLLECTION OF NOTES, not a text block. --description is a one-line FRAME;
+# the content is the member notes you pass to --notes. If you have N distinct things
+# (questions, risks, options), create N notes first — pick the right type, e.g. a Question
+# note per open question — then group them: --notes ID1,ID2,ID3. Pasting a numbered/bulleted
+# list into --description with no --notes is the wrong shape (you get a "0 items" container
+# masquerading as prose). For a standalone markdown block, use add-richtext instead.
+cnotes canvas add-list <canvasId> --description "<markdown>" [--notes <id1,id2,...>] [--view list|grid] [--x <n>] [--y <n>]
+cnotes canvas add-link <canvasId> --target <otherCanvasId> [--x <n>] [--y <n>]
+
+# 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.
+cnotes canvas place <canvasId> --spec ./layout.json
+cnotes canvas place <canvasId> --spec-stdin                  # JSON from stdin
+cnotes canvas place <canvasId> --spec-inline '<short JSON>'  # for tiny specs only
+
+# Bulk add with explicit positions (escape hatch — only for pixel-perfect templates)
+cnotes canvas bulk-add <canvasId> --notes '[{"noteId":"NOTE-1","x":100,"y":100},{"noteId":"NOTE-2","x":400,"y":100}]'
+
+# Move / remove nodes
+cnotes canvas move-node <canvasId> --node <nodeId> --x <n> --y <n>
+cnotes canvas remove-node <canvasId> --node <nodeId>
+
+# Bulk remove multiple nodes at once
+cnotes canvas bulk-remove <canvasId> --nodes '["nodeId1","nodeId2"]'
+
+# Bulk move multiple nodes at once (more efficient than repeated move-node)
+cnotes canvas bulk-move <canvasId> --moves '[{"nodeId":"abc","nodeType":"note","x":200,"y":300},{"nodeId":"def","nodeType":"text","x":500,"y":300}]'
+# nodeType: note | text | list | canvas | richtext (defaults to "note")
+
+# Connect nodes
+cnotes canvas add-edge <canvasId> --source <nodeId> --target <nodeId> [--label "<text>"]
+
+# Templates — create structured canvases from predefined layouts
+cnotes canvas templates                                           # List available templates
+cnotes canvas from-template <templateId> [--title "<title>"]      # Create empty skeleton
+cnotes canvas from-template <templateId> --populate               # Auto-populate zones with matching notes
+# Templates: sprint-retrospective, swot-analysis, kanban-board, feature-prioritization, meeting-notes, product-roadmap
+
+# Agent-run bracketing — group a sequence of canvas changes into one operation
+# with before/after snapshots so the user can see "AI did X" and revert as a unit.
+# REQUIRED when an AI agent modifies a canvas. See "Agent-Run Bracketing" below.
+cnotes canvas agent-run wrap  --canvas <id> --prompt "<intent>" -- <command>   # one-shot
+cnotes canvas agent-run begin --canvas <id> --prompt "<intent>" [--rationale "<plan>"]  # multi-step
+cnotes canvas agent-run end   --canvas <id>
+cnotes canvas activity <canvasId>   # inspect operations + attribution after the fact
+```
+
+### Timeline (`cnotes timeline` / `cnotes tl`)
+```bash
+# Show recent changes (default: last 7 days)
+cnotes timeline [--since <when>] [--until <when>] [--type <noteType>] [--note <filter>] [--limit <n>]
+
+# Examples
+cnotes timeline                        # last 7 days
+cnotes timeline --since 30d            # last 30 days
+cnotes timeline --since 2w --type Meeting   # meetings in last 2 weeks
+cnotes timeline --since 7d --note standup   # filter by note name
+# Supported --since formats: relative (7d, 2w, 3h, 30m), ISO date (2026-03-21), unix ms
+```
+
+### Relationships (`cnotes relationships` / `cnotes rel`)
+```bash
+cnotes rel list [--note <displayId>]
+
+# List the relationship types defined in the workspace. Check this BEFORE
+# using a relationship:<type> label so you reuse an existing type instead of
+# creating a near-duplicate.
+cnotes rel types
+```
+
+### Semantic Search (`cnotes search` / `cnotes s`)
+```bash
+cnotes search semantic "<query>" [--limit <n>] [--canvas <canvasId>]
+```
+
+### Types (`cnotes types` / `cnotes t`)
+```bash
+# List all types (supertags) in the workspace
+cnotes types list
+
+# Create a new type (prefix is auto-derived from display name)
+cnotes types create <name> [--display-name <name>] [--description <text>] [--color <hex>]
+
+# Update an existing type (prefix updates automatically when display name changes)
+cnotes types update <name> [--display-name <name>] [--description <text>] [--color <hex>]
+
+# Retype a note (atomic: creates new note with target type, archives old one, cross-links both)
+cnotes notes retype <displayId> --type <NewType>
+```
+
+### Memory (`cnotes memory` / `cnotes mem`)
+```bash
+# Search facts and entities by relevance
+cnotes memory query "<query>" [--limit <n>] [--source <conversation|notes>]
+
+# List all workspace facts (extracted from notes and conversations)
+cnotes memory facts [--source <conversation|notes>]
+
+# List all entities (people, topics, orgs) identified by Zep
+cnotes memory entities [--source <conversation|notes>]
+```
+
+### Files (`cnotes files` / `cnotes f`)
+```bash
+# Upload an image to the workspace (max 5MB, supports .jpg .jpeg .png .gif .webp)
+cnotes files upload <path> [--markdown]   # --markdown outputs ![filename](url) syntax
+```
+
+### Init & MCP (`cnotes init` / `cnotes mcp`)
+```bash
+# Interactive setup wizard — auth, workspace, AI integrations, skill install
+cnotes init
+
+# Configure MCP server for AI tools (also handled by cnotes init)
+cnotes mcp setup          # Claude Desktop
+cnotes mcp setup-codex    # OpenAI Codex
+```
+
+### Theme (`cnotes theme`)
+
+Personal UI theme preference (synced to your account, applies on next browser reload — does NOT live-update an open tab).
+
+```bash
+# List built-in presets — current one is marked with *
+cnotes theme list
+
+# Show the active theme + any per-token color overrides
+cnotes theme get
+
+# Switch to a built-in preset
+cnotes theme set <id>          # e.g. dracula, ember, catppuccin-mocha, sage, light, dark
+
+# Override a single color (switches the theme to "custom" automatically)
+cnotes theme set-color <token> <hex>   # e.g. cnotes theme set-color primary "#ff00aa"
+
+# Drop all custom overrides and return to the base preset
+cnotes theme reset
+```
+
+**Editable tokens** (anything else is rejected with 422):
+`background`, `card`, `popover`, `muted`, `border`, `sidebar-background`,
+`primary`, `primary-foreground`, `ring`, `accent-teal`,
+`foreground`, `muted-foreground`, `prose-body`, `prose-heading`,
+`code-background`, `code-foreground`, `blockquote-border`,
+`destructive`, `success`, `warning`, `info`.
+
+`set-color` merges into existing overrides — call it repeatedly to build up a custom palette. `reset` returns to the preset that was the base of your custom theme (or `dark` if you started from scratch).
+
+### Config
+```bash
+cnotes config get-server
+cnotes config set-server <url>
+```
+
+## Assembling URLs for Responses
+
+When you reference a workspace or canvas in a response (so the user can click through), build the URL yourself in this exact shape:
+
+```
+<origin>/<workspaceId>?canvasId=<canvasId>
+```
+
+- `<origin>` is `https://creatornotes.app` for prod, or `http://localhost:3000` when the active session / `--server` points at local dev. Match whichever the CLI is currently talking to.
+- `<workspaceId>` and `<canvasId>` are the Convex IDs returned by `cnotes workspace current` / `cnotes canvas get` / `cnotes canvas list --json`. Use raw IDs — do not slug-ify.
+- To link a workspace without a specific canvas, omit the query: `<origin>/<workspaceId>`. The app will redirect to the last-visited or home canvas.
+
+**Do not invent path segments.** These shapes do NOT exist and will 404 or redirect somewhere wrong:
+
+- `/workspace/<id>/canvas/<canvasId>` ← wrong, fabricated
+- `/workspaces/<id>` ← wrong
+- `/canvas/<canvasId>` ← wrong (there is a `/shared/<canvasId>` route, but only for public share links)
+
+If you need the origin, read it from `cnotes config get-server` rather than guessing.
+
+## Best Practices
+
+### Note IDs
+- Notes have **display IDs** like `MEETING-12`, `PRD-5`, `IDEA-3` — use these in commands.
+- Convex IDs (e.g., `n17a43p7aenrxyr...`) also work but are less readable.
+- When creating notes, capture the display ID from the output for subsequent commands.
+
+### Note Types
+- The `--type` parameter must reference an **existing supertag** in the workspace. Free-text type strings are rejected.
+- Before creating a note, check available types with `cnotes types list`. **Run `cnotes types list --json` and read each type's `validationPrompt` (its quality rubric) before authoring** — it spells out what a good instance of that type contains (e.g. a Decision needs the alternatives, rationale, and a revisit trigger). Author to the rubric so the note lands well-formed, rather than getting nudged after save.
+- If the type you need doesn't exist, create it first: `cnotes types create "MyType" --display-name "My Type"`
+- Type names are **case-sensitive** and use PascalCase (e.g., `Update`, `PainPoint`, `Meeting`).
+- The display ID prefix is **auto-derived** from the display name: spaces become hyphens, all uppercase (e.g., display name "Pain Point" → prefix `PAIN-POINT`, display name "Idea" → prefix `IDEA`).
+- Prefix is **immutable** once notes of that type exist. To change a note's type, use `cnotes notes retype <displayId> --type <NewType>`.
+
+### Content via Markdown
+- Markdown is the only content format on the wire. For multi-line content, write to a file and pass the path via `markdownFile`:
+  ```bash
+  cnotes notes create --notes '[{"key":"A","type":"Note","markdownFile":"./note.md"}]'
+  ```
+- Use inline `markdown` only for short, single-line content.
+- **Always start markdown content with a `# h1` heading.** This becomes the note title. Follow proper markdown structure: `## h2` for major sections, `### h3` for subsections. Well-structured heading hierarchy is expected for all notes.
+- **Relationship mentions in markdown**: Use `[NOTE-123](relationship:references)` or `[NOTE-123: Title](relationship:references)` syntax — plain text "NOTE-123" does NOT create clickable mentions.
+- **Reuse an existing relationship type before inventing one.** Run `cnotes rel types` (or read the list printed by `cnotes workspace current`) and pick the closest existing label. The type slot is free-form, so an unknown label is auto-created as a custom workspace type rather than dropped — but that means a typo or a needless synonym (`support` vs `supports`, `relates-to` vs `related-to`) silently pollutes the workspace's type vocabulary forever. Only coin a new type when nothing existing fits.
+- Names are normalized to lowercase + hyphens, so `Depends On`, `depends on`, and `depends-on` all resolve to the same type. When `cnotes notes create` does create new types, it reports them (`+ created N new relationship types: …`) — treat that line as a prompt to double-check you didn't mean an existing one.
+- Common built-in types to reach for first:
+  - `depends-on` / `blocks` — dependency ordering between notes
+  - `references` — general "see also" link (default if omitted)
+  - `implements` — a note that delivers on what another identifies (e.g., feature → requirement, solution → gap)
+  - `derived-from` — a note created based on another's content
+  - `extends` — adds depth or detail to another note's topic
+  - `invalidates` / `supersedes` — supersedes or contradicts another note
+  - `related-to` — loose thematic connection
+  - `duplicates` — notes covering the same thing
+- Simple mention shorthand: `[NOTE-123]` or `[NOTE-123: Title]` (defaults to "references")
+
+### Updating Content vs Metadata
+- To change note **content** (including title), create a new **version**: `cnotes versions create <id> --description "..." --markdown-file ./updated.md`
+- Title is derived from the `# h1` heading in the latest version — to rename a note, create a new version with a different heading.
+- To change note **type/tags/pin/archive**, use: `cnotes notes update <id> --type "..." --tags "..."`
+- These are separate operations by design.
+
+### JSON Mode for Scripting
+- Use `--json` to get raw JSON output for parsing with `jq` or piping between commands. See [Reading output](#reading-output-start-here) for the contract behind these shapes.
+- Reads emit a bare array; writes emit an envelope. Read created notes from `results`, never from `notes`/`ok`:
+  ```bash
+  # Capture the display IDs a batch create produced
+  IDS=$(cnotes notes create --json --notes '[…]' | jq -r '.results[].displayId')
+  ```
+- Treat a `0` exit code as the only success signal. Do not re-run a write because an expected key looked empty; re-running a successful `notes create` duplicates the batch.
+- On validation failure with `--json`, the per-item errors come back in `details.items` (array of `{index, key?, field, message}`) so they can be parsed and surfaced precisely.
+- Use `-q` (quiet) to get just the ID(s), useful for chaining:
+  ```bash
+  NOTE_ID=$(cnotes notes create --notes '{"key":"A","type":"Note","markdown":"# Quick note"}' -q)
+  cnotes canvas add-node <canvasId> --note "$NOTE_ID"
+  ```
+
+### Canvas Orientation
+
+**Always start canvas work with `cnotes canvas digest <canvasId> --json`.** The digest returns the narrative summary, key themes, and a per-note summary list covering every note on the canvas. Use this as your single source of context before making any changes — do not read each note individually unless you need full content.
+
+The `notes` array entries have the shape `{ displayId, title, type, summary }`. When `summary` is `null`, the AI summary hasn't been generated yet (fresh note, or too short to summarize); run `cnotes notes get <displayId> [<displayId>...]` (batch-fetch in one call) if you need full content.
+
+If `status` is `"none"` or `"stale"`, the `notes` array is still populated and accurate — you can start working immediately. Trigger a narrative refresh with `POST /api/canvas/<canvasId>/digest` only if you need the narrative itself.
+
+### Wrapping batch work in an operation (ENFORCED for `notes create`)
+
+When an AI agent (including you, Claude) is doing a **batch of work** — creating notes, modifying 2+ entities, or building a canvas with content — wrap it in a workspace-level **operation**. The batch then shows up in the timeline as a single legible row with intent + evidence + count, and the user can later revert the whole run as one unit.
+
+Without wrapping, each write is a standalone timeline row with no shared intent, no grouping, and no way to revert as a batch.
+
+**This is enforced for note creation.** `cnotes notes create` (the batch-create endpoint) is rejected with `operation_required` (HTTP 422) unless a run is active — the server refuses to create notes outside an operation. Begin one first; the active run then auto-attaches to every subsequent write.
+
+#### When to wrap
+
+| Action | Wrap? |
+|---|---|
+| Reading: `digest`, `get`, `list`, `activity`, `timeline`, `search`, `memory query`, `rel list` | **No** — read-only |
+| **Any `cnotes notes create`** (even a single note) | **Yes — enforced.** Creates run through the batch endpoint, which now rejects writes with no active run |
+| A single `notes update` / tag / pin / archive change | **No** — single metadata edits don't go through the guarded create path |
+| Two or more writes that belong to one intent (multi-note batch, canvas build-out, multi-step refactor) | **Yes** |
+| Canvas mutations done as part of an agent task | **Yes** — even one canvas command, if it's part of a larger batch |
+
+#### The pattern
+
+`cnotes operations begin` opens a run; **every subsequent cnotes write on this server attaches to it automatically**, across any shell, until you call `cnotes operations end`. No env var to export, no eval trick — the active run is persisted in `~/.cnotes/config.json` per server, so stateless callers (separate Bash invocations, disjoint tool calls) all attach correctly.
+
+```bash
+# 1. Open the run with the user's intent as the prompt.
+cnotes operations begin --prompt "Reorganize roadmap into quarters" --json
+
+# 2. Do the work. Every cnotes write here attaches to the run automatically.
+cnotes notes create --notes '[ ... ]'
+cnotes canvas add-text <canvasId> --text "Q1" --size heading --x 0 --y 0
+cnotes canvas place <canvasId> --spec /tmp/q1.json
+cnotes canvas add-edge <canvasId> --source <a> --target <b> --label "depends on"
+
+# 3. Close the run when done.
+cnotes operations end
+```
+
+**Always close the run.** If `begin` succeeded, `end` must run — otherwise the operation stays `running` and subsequent `cnotes operations begin` calls will refuse (with a clear "active run already exists, end it first or pass --force" message). The server-side reaper will eventually mark a stale `running` row as `abandoned` after about an hour, but that's a safety net, not the intended flow.
+
+**If something goes wrong mid-batch** and you can't recover: `cnotes operations end --force` (on a future begin) ends the prior run server-side and starts a fresh one.
+
+#### Writing a good `--prompt`
+
+The prompt is the **intent** the user sees on the timeline row. Use the user's own language where you can:
+
+- "Build a fan-out under Goals heading with Q1 milestones"
+- "Reorganize the canvas into a SWOT layout"
+- "Add risks list and connect to the parent goal"
+
+Avoid generic prompts like "make changes" or "update canvas" — they make the timeline useless.
+
+#### Verifying it worked
+
+After your run, the user (or you) can:
+- Look at the **timeline panel** in the workspace → the run appears as one row with a bot icon, your prompt as the headline, and a "N notes" count
+- Expand the row → each member note appears nested
+- Run `cnotes operations get <agentRunId>` → confirms `affectedNoteCount` reflects everything the run touched
+
+If the timeline shows individual note rows instead of one grouped run, the writes didn't attach — usually because `begin` was never called, or `end` was called too early (before the writes).
+
+### Canvas Layout
+
+**Don't compute coordinates by hand. Use `cnotes canvas place` with a layout spec.**
+
+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 `cnotes canvas place` is for, and you should reach for it whenever you're adding more than one item.
+
+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.
+
+**You don't have to find a free coordinate.** `place` is collision-aware against content already on the canvas. By default (`placement: "auto"`) it drops your layout in a clear band **below everything that's already there**, and if you do pass an `origin` that would overlap, it slides the whole block straight down until it's clear. So appending a new section to a non-empty canvas Just Works — no need to read existing positions and guess a safe `origin` first. Use `--placement append` to force "below everything", or `--placement exact` (or `"placement": "exact"` in the doc) to honor your `origin` verbatim for pixel-perfect templates.
+
+Use `cnotes 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).
+
+#### The layout DSL
+
+A layout document is `{ root, edges?, origin?, placement? }` where `root` is one of four node kinds:
+
+- **`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.
+
+`gap` accepts a preset (`"tight"`, `"medium"`, `"spacious"`) or a raw pixel number. Defaults to `"medium"`.
+
+`placement` (top-level, optional) controls where the whole layout sits relative to existing content: `"auto"` (default, collision-aware — below existing content / de-collide), `"append"` (always below everything), `"exact"` (honor `origin` verbatim). `origin` is the top-left corner; omit it and `auto`/`append` pick a safe one for you.
+
+#### Leaf item shapes
+
+```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",     "description": "Risks tracked weekly — owner: @ana", "noteIds": ["A","B","C"], "viewMode": "list" }
+{ "kind": "item", "type": "canvas",   "linkedCanvasId": "abc..." }
+```
+
+The optional `key` lets edges and other items reference this leaf later (`@<key>`).
+
+`richtext.content` accepts markdown directly — the server converts to TipTap before measuring.
+
+`list.description` is a one-line **frame**, never the content itself — the content is `noteIds` (the member notes). For N distinct things, create N notes (right type per item, e.g. `Question` for open questions) and list their ids. A `list` with a multi-item description and an empty `noteIds` is the wrong shape — use `richtext` when you genuinely want one standalone markdown block with no members.
+
+#### Edges
+
+Edges live at the top level alongside `root`. Each endpoint is resolved in this priority order:
+
+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
+
+```json
+"edges": [
+  { "from": "@a", "to": "@b", "label": "depends on" },
+  { "from": "NOTE-7", "to": "@a" }
+]
+```
+
+#### 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" }
+        ] }
+    ]
+  }
+}
+```
+
+**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" }
+        ] }
+      ] }
+    ]
+  }
+}
+```
+
+**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" }
+      ]
+    }
+  }
+}
+```
+
+**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" }
+  ]
+}
+```
+
+#### Workflow
+
+1. Write the layout doc to a temp file (`/tmp/layout.json`).
+2. Run `cnotes 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).
+
+#### Constraints
+
+- **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.
+
+#### When the layout engine isn't enough
+
+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
+
+In all other cases — and especially when adding 3+ items at once — use `place`.
+
+### Interlinking Notes
+
+When creating multiple related notes, interlink at two levels:
+
+**1. Relationship mentions inside note content** — connects notes in the knowledge graph:
+- Use `cnotes notes create` with an array and `@key` placeholders for cross-references.
+- Example: `[@B: The Problem](relationship:references)` in markdown.
+- The server resolves placeholders to real display IDs in one atomic transaction.
+
+**2. Canvas edges between nodes** — visual connections on the canvas:
+- After adding nodes, connect them with `cnotes canvas add-edge`.
+- Use descriptive labels (e.g., "triggers", "depends on").
+
+Both levels are needed — edges are visual-only, mentions are content-level.
+
+#### Placeholder Syntax for `cnotes notes create`
+
+Use `[@key: Title](relationship:type)` where `key` matches a note's `key` field in the `--notes` JSON:
+```markdown
+This builds on [@B: The Problem](relationship:references) and enables [@C: The Workflow](relationship:derived-from).
+```
+
+The relationship type is free-form, but **reuse an existing type before inventing one** — run `cnotes rel types` and pick the closest match. Unknown labels are auto-created (not dropped), so a needless synonym permanently clutters the workspace's vocabulary. Common built-ins to reach for first: `depends-on`, `blocks`, `related-to`, `derived-from`, `references`, `extends`, `implements`, `invalidates`, `supersedes`, `duplicates`. See the markdown content section above for when to use each type.
+
+### Memory
+
+Before creating or updating notes on a topic, **query memory first** to understand what is already known:
+
+1. **Start broad:** `cnotes memory query "<topic>"` — get the top facts and entities.
+2. **Follow entities:** Run follow-up queries on related people, teams, or initiatives.
+3. **Check temporal validity:** Facts have `validAt`/`invalidAt` timestamps — prefer current facts.
+4. **Synthesize:** Combine facts from 2-3 queries before acting.
+
+### Error Handling
+- Branch on the **exit code** first (see the table in [Reading output](#reading-output-start-here)); it tells you the class of failure without parsing prose.
+- In `--json` mode a failure prints `{ error, code, exitCode, hint }` to stderr. The `hint` names the command that fixes it, so read it before retrying.
+- If a command fails with auth errors (exit `2`), run `cnotes auth status` to verify credentials.
+- If a workspace error occurs (exit `4` not found, or `7` permission), verify with `cnotes workspace current` and list options with `cnotes workspace list`.