@creator-notes/cli 0.2.0 → 0.2.2

package/skills/cn/SKILL.md

@@ -0,0 +1,289 @@
+# CreatorNotes CLI (`cn`)
+
+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/cli
+```
+
+### Authenticate
+
+```bash
+cn auth login           # Opens browser for OAuth
+cn auth login --token <key>  # Direct API key
+cn auth status          # Check current session
+```
+
+### Select a Workspace
+
+```bash
+cn workspace list
+cn workspace select <id>
+cn workspace current    # Verify active workspace
+```
+
+## 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)
+```
+
+### Notes (`cn notes` / `cn n`)
+```bash
+# List notes (default 20, excludes drafts)
+cn notes list [--search <query>] [--type <type>] [--tags <csv>] [--pinned] [--limit <n>]
+
+# Get a single note by display ID or Convex ID
+cn notes get <id> [--all-versions]
+
+# Create a note
+cn notes create --markdown-file <path.md> [--title <title>] [--type <type>] [--tags <csv>] [--draft]
+cn notes create --markdown "<content>" [--title <title>] [--type <type>] [--tags <csv>] [--draft]  # inline (short content only)
+cn notes create --content-file <path.json>   # TipTap JSON from file
+cn notes create --content-stdin               # TipTap JSON from stdin
+
+# Update metadata only (not content — use versions for that)
+cn notes update <id> [--title <t>] [--type <t>] [--tags <csv>] [--archive] [--unarchive] [--pin] [--unpin]
+
+# Delete (archive)
+cn notes delete <id>
+
+# Bulk archive/unarchive multiple notes at once
+cn notes bulk-archive --ids '["MEETING-1","PRD-3","IDEA-7"]' [--unarchive]
+
+# Bulk create interlinked notes in one atomic transaction
+# Use @key placeholders for cross-references — resolved to real displayIds server-side
+cn notes bulk-create --notes '[{"key":"A","title":"Note A","type":"Insight","markdownFile":"./a.md"},{"key":"B","title":"Note B","type":"Problem","markdownFile":"./b.md"}]' --json
+
+# Text search
+cn notes search <query> [--type <type>] [--limit <n>]
+```
+
+### Versions (`cn versions` / `cn v`)
+```bash
+# List versions
+cn versions list <noteId>
+
+# Create a new version (updates note content)
+cn versions create <noteId> --description "what changed" --markdown-file <path.md>
+cn versions create <noteId> --description "what changed" --markdown "<short content>"  # inline (short only)
+cn versions create <noteId> --description "what changed" --content-file <path.json>
+```
+
+### Canvas (`cn canvas` / `cn c`)
+```bash
+# List / get (archived canvases excluded by default)
+cn canvas list [--include-archived]
+cn canvas get <canvasId>
+
+# AI digest (summary) of canvas
+cn canvas digest <canvasId>
+
+# Create / delete
+cn canvas create "<name>"
+cn canvas delete <canvasId>
+cn canvas set-as-home <canvasId>
+
+# Add nodes to canvas
+cn canvas add-node <canvasId> --note <noteId> [--x <n>] [--y <n>]
+cn canvas add-text <canvasId> --text "<content>" [--size heading|paragraph] [--x <n>] [--y <n>]
+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)
+cn canvas bulk-add <canvasId> --notes '[{"noteId":"NOTE-1","x":100,"y":100},{"noteId":"NOTE-2","x":400,"y":100}]'
+
+# Move / remove nodes
+cn canvas move-node <canvasId> --node <nodeId> --x <n> --y <n>
+cn canvas remove-node <canvasId> --node <nodeId>
+
+# Bulk remove multiple nodes at once
+cn canvas bulk-remove <canvasId> --nodes '["nodeId1","nodeId2"]'
+
+# Bulk move multiple nodes at once (more efficient than repeated move-node)
+cn 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 (defaults to "note")
+
+# Connect nodes
+cn canvas add-edge <canvasId> --source <nodeId> --target <nodeId> [--label "<text>"]
+
+# Templates — create structured canvases from predefined layouts
+cn canvas templates                                           # List available templates
+cn canvas from-template <templateId> [--title "<title>"]      # Create empty skeleton
+cn canvas from-template <templateId> --populate               # Auto-populate zones with matching notes
+# Templates: sprint-retrospective, swot-analysis, kanban-board, feature-prioritization, meeting-notes, product-roadmap
+```
+
+### Timeline (`cn timeline` / `cn tl`)
+```bash
+# Show recent changes (default: last 7 days)
+cn timeline [--since <when>] [--until <when>] [--type <noteType>] [--note <filter>] [--limit <n>]
+
+# Examples
+cn timeline                        # last 7 days
+cn timeline --since 30d            # last 30 days
+cn timeline --since 2w --type Meeting   # meetings in last 2 weeks
+cn 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 (`cn relationships` / `cn rel`)
+```bash
+cn rel list [--note <displayId>]
+```
+
+### Semantic Search (`cn search` / `cn s`)
+```bash
+cn search semantic "<query>" [--limit <n>] [--canvas <canvasId>]
+```
+
+### Types (`cn types` / `cn t`)
+```bash
+# List all types (supertags) in the workspace
+cn types list
+
+# Create a new type
+cn types create <name> [--prefix <PREFIX>] [--display-name <name>] [--description <text>] [--color <hex>]
+
+# Update an existing type
+cn types update <name> [--prefix <PREFIX>] [--display-name <name>] [--description <text>] [--color <hex>]
+```
+
+### Memory (`cn memory` / `cn mem`)
+```bash
+# Search facts and entities by relevance
+cn memory query "<query>" [--limit <n>] [--source <conversation|notes>]
+
+# List all workspace facts (extracted from notes and conversations)
+cn memory facts [--source <conversation|notes>]
+
+# List all entities (people, topics, orgs) identified by Zep
+cn memory entities [--source <conversation|notes>]
+```
+
+### Config
+```bash
+cn config get-server
+cn config set-server <url>
+```
+
+## 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 `cn types list`.
+- If the type you need doesn't exist, create it first: `cn types create "MyType" --prefix "MT"`
+- Type names are **case-sensitive** and use PascalCase (e.g., `Update`, `PainPoint`, `Meeting`).
+- The display ID prefix (e.g., `UPDATE-`, `PP-`) comes from the supertag's `prefix` field.
+
+### Content via Markdown
+- For multi-line content, **use `--markdown-file`**: write content to a file first, then pass the path.
+  ```bash
+  cn notes create --markdown-file ./note.md --title "My Note" --type "Note"
+  ```
+- Only use inline `--markdown "..."` for very short, single-line content.
+- The server converts markdown to TipTap JSON automatically.
+- **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.
+- Supported relationship types: `depends-on`, `blocks`, `related-to`, `derived-from`, `references`, `extends`, `implements`, `invalidates`, `duplicates`
+- Simple mention shorthand: `[NOTE-123]` or `[NOTE-123: Title]` (defaults to "references")
+
+### Updating Content vs Metadata
+- To change note **content**, create a new **version**: `cn versions create <id> --description "..." --markdown-file ./updated.md`
+- To change note **title/type/tags/pin/archive**, use: `cn notes update <id> --title "..."`
+- 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.
+- Use `-q` (quiet) to get just the ID, useful for chaining:
+  ```bash
+  NOTE_ID=$(cn notes create --markdown "Quick note" -q)
+  cn canvas add-node <canvasId> --note "$NOTE_ID"
+  ```
+
+### Canvas Layout
+
+When adding 3+ notes to a canvas, **plan all positions upfront** and use `bulk-add` in a single call instead of repeated `add-node` calls.
+
+#### Layout Constants
+
+| Item | Width (px) | Height (px) |
+|------|-----------|-------------|
+| Node (rendered) | 280 | 100 |
+| Grid cell (node + padding) | 400 | 180 |
+| Edge label | ~80 | ~14 |
+
+Node center offset from top-left: `(+140, +50)`.
+
+#### Text Node Sizing
+
+Use `--size` to control text node font size (default: `heading`):
+
+| Size | Use for |
+|------|---------|
+| `heading` (default) | Section headers, zone titles, canvas labels |
+| `paragraph` | Descriptions, annotations, supporting context |
+
+#### Positioning Algorithm
+
+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`. Center each rank horizontally with 400px spacing between nodes.
+4. **Use `bulk-add`** for all nodes, then add edges with `add-edge`.
+
+#### Common Topologies
+
+**Linear chain** (A→B→C→D): stack vertically at X=300, Y increments of 180.
+
+**Fan-out** (A→B, A→C, A→D): root on top, children spread horizontally at 400px intervals.
+
+**Diamond** (A→B, A→C, B→D, C→D): 2-column layout centered under root.
+
+### Interlinking Notes
+
+When creating multiple related notes, interlink at two levels:
+
+**1. Relationship mentions inside note content** — connects notes in the knowledge graph:
+- Use `cn notes bulk-create` with `@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 `cn 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 `bulk-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).
+```
+
+Supported relationship types: `depends-on`, `blocks`, `related-to`, `derived-from`, `references`, `extends`, `implements`, `invalidates`, `duplicates`
+
+### Memory
+
+Before creating or updating notes on a topic, **query memory first** to understand what is already known:
+
+1. **Start broad:** `cn 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
+- If a command fails with auth errors, run `cn auth status` to verify credentials.
+- If workspace-related errors occur, verify with `cn workspace current`.