clawvault 2.3.1 → 2.4.1

package/README.md

@@ -2,401 +2,193 @@
 
 **An elephant never forgets.**
 
-Structured memory system for AI agents. Store, search, and link memories across sessions.
+Structured memory system for AI agents. Typed storage, knowledge graph, task management, and Obsidian-native dashboards — all local, all markdown.
 
-🌐 **Website:** [clawvault.dev](https://clawvault.dev) | 📦 **npm:** [clawvault](https://www.npmjs.com/package/clawvault) | 🛠️ **ClawHub:** [clawvault skill](https://clawhub.com/skills/clawvault)
+[![npm](https://img.shields.io/npm/v/clawvault)](https://www.npmjs.com/package/clawvault) [![tests](https://img.shields.io/badge/tests-361%20passing-brightgreen)]()
 
-> **Built for [OpenClaw](https://openclaw.ai)** — the AI agent framework. Works standalone too.
+🌐 [clawvault.dev](https://clawvault.dev) · 📚 [docs.clawvault.dev](https://docs.clawvault.dev) · 🛠️ [ClawHub Skill](https://clawhub.com/skills/clawvault)
 
-## Install for OpenClaw Agents
+> Works with [OpenClaw](https://openclaw.ai) agents or standalone. No cloud. No API keys. Just files.
 
-```bash
-# Install the skill (recommended for OpenClaw agents)
-clawhub install clawvault
-
-# Or install the CLI globally
-npm install -g clawvault
-```
-
-## Requirements
-
-- **Node.js 18+**
-- **[qmd](https://github.com/Versatly/qmd)** — Local semantic search (required)
+## Install
 
 ```bash
-# Install qmd first
-bun install -g qmd   # or: npm install -g qmd
-
-# Then install clawvault
 npm install -g clawvault
 ```
 
-## Why ClawVault?
-
-AI agents forget things. Context windows overflow, sessions end, important details get lost. ClawVault fixes that:
-
-- **Structured storage** — Organized categories, not random notes
-- **Local search** — qmd provides BM25 + semantic search with local embeddings (no API quotas)
-- **Wiki-links** — `[[connections]]` visible in Obsidian's graph view
-- **Session continuity** — Handoff/recap system for context death
-- **Token efficient** — Search instead of loading entire memory files
-
 ## Quick Start
 
 ```bash
-# Initialize vault with qmd collection
-clawvault init ~/memory --qmd-collection my-memory
-
-# Store memories
-clawvault remember decision "Use qmd" --content "Local embeddings, no API limits"
-clawvault remember lesson "Context death is survivable" --content "Write it down"
-clawvault capture "Quick note to process later"
-
-# Search (uses qmd)
-clawvault search "decision"           # BM25 keyword search
-clawvault vsearch "what did I decide" # Semantic search
-
-# Session management
-clawvault wake
-clawvault sleep "build wake/sleep commands" --next "run doctor"
-clawvault handoff --working-on "task1" --next "task2"   # Manual handoff (advanced)
-clawvault recap                                         # Manual recap (advanced)
-```
+# Create a vault
+clawvault init ~/memory --name my-brain
 
-**Tip:** Set `CLAWVAULT_PATH` to skip directory walk (or use `shell-init`):
-```bash
-echo 'export CLAWVAULT_PATH="$HOME/memory"' >> ~/.bashrc
-eval "$(clawvault shell-init)"
-```
-
-## Observational Memory
+# Store memories by type
+clawvault remember decision "Use PostgreSQL" --content "Chose for JSONB support"
+clawvault remember lesson "Always checkpoint" --content "Context death is real"
+clawvault capture "Quick thought to process later"
 
-Automatically compress conversations into prioritized observations:
-
-```bash
-# One-shot: compress a conversation file
-clawvault observe --compress session.md
+# Search
+clawvault search "postgresql"           # Keyword (BM25)
+clawvault vsearch "what database?"      # Semantic (local embeddings)
 
-# Active sessions: incremental observe from OpenClaw transcripts
-clawvault observe --active
+# Session lifecycle
+clawvault wake                          # Start session, load context
+clawvault sleep "built auth system" \   # End session with handoff
+  --next "deploy to staging"
 
-# Watch mode: monitor a directory for new session files
-clawvault observe --watch ./sessions/
+# Task management
+clawvault task add "Ship v2" --owner agent --project acme --priority high
+clawvault task list
+clawvault blocked
+clawvault backlog add "Explore caching" --project acme
 
-# Background daemon
-clawvault observe --daemon
+# Visual dashboards (Obsidian JSON Canvas)
+clawvault canvas --template brain           # System architecture overview
+clawvault canvas --template project-board   # Task board by owner
 ```
 
-Observations use emoji priorities:
-- 🔴 **Critical** — decisions, errors, blockers, deadlines
-- 🟡 **Notable** — preferences, architecture discussions, people interactions
-- 🟢 **Info** — routine updates, deployments, general progress
+## Features
 
-Critical and notable observations are automatically routed to vault categories (`decisions/`, `lessons/`, `people/`, etc.). The system uses LLM compression (Gemini, Anthropic, or OpenAI) with a rule-based fallback.
-
-For long-running OpenClaw sessions, `observe --active` tracks per-session byte cursors in `.clawvault/observe-cursors.json` and only compresses new transcript deltas once threshold windows are crossed.
-
-Integrated into the sleep/wake lifecycle:
-```bash
-clawvault sleep "task summary" --session-transcript conversation.md
-# → observations auto-generated and routed
+### 📁 Typed Memory Storage
+Every memory has a category: `decisions/`, `lessons/`, `people/`, `projects/`, `commitments/`. No more dumping everything into one file. "Show me all decisions" actually works.
 
-clawvault wake
-# → recent 🔴/🟡 observations included in context
-```
+### 🧠 Knowledge Graph
+Wiki-links (`[[connections]]`) build a typed graph index. Query with graph-aware context that blends semantic search with relationship traversal.
 
-Token-budget-aware context injection:
 ```bash
-clawvault context "what decisions were made" --budget 2000
-# → blends semantic + graph-neighbor context within budget
-
-clawvault context "what decisions were made" --format json
-# → includes explain metadata (signals + rationale) per entry
-
-clawvault context "plan database migration" --profile planning
-# → profile-tuned ordering for planning, incident, handoff, or default
-
-clawvault context "URGENT outage: rollback failed" --profile auto
-# → auto infers incident/planning/handoff/default from prompt intent
+clawvault graph                              # Graph summary
+clawvault context "database migration" \     # Graph-aware context
+  --profile planning --budget 2000
 ```
 
-## Search
-
-Use `clawvault search` / `qmd` for vault search — it indexes the **entire vault** (decisions/, people/, lessons/, observations/, etc.).
-
-OpenClaw's built-in `memory_search` only indexes `MEMORY.md` + `memory/**/*.md`. If your vault lives inside `memory/`, it'll work. If your vault is elsewhere, `memory_search` won't find your ClawVault categories.
+### ✅ Task Management
+Tasks and backlog stored as markdown with frontmatter. Agents and humans share the same system.
 
 ```bash
-# Full vault search (recommended)
-clawvault search "query"              # BM25 keyword
-clawvault vsearch "what did I decide" # Semantic (local embeddings)
-
-# OpenClaw memory search (only MEMORY.md + memory/*.md)
-# Works if vault is inside memory/, misses vault categories otherwise
+clawvault task add "Fix auth" --owner bot --priority critical
+clawvault task update fix-auth --status blocked --blocked-by "api-key"
+clawvault blocked                            # Triage blocked work
+clawvault backlog promote explore-caching    # Backlog → active task
 ```
 
-## Vault Structure
+### 🎨 Obsidian Dashboards
+Generate visual dashboards as [JSON Canvas](https://jsoncanvas.org) files:
 
-```
-my-memory/
-├── .clawvault.json      # Config (includes qmd collection name)
-├── .clawvault/
-│   └── graph-index.json # Typed memory graph index (incremental rebuilds)
-├── decisions/           # Choices with reasoning
-├── lessons/             # Things learned
-├── people/              # One file per person
-├── projects/            # Active work
-├── commitments/         # Promises and deadlines
-├── inbox/               # Quick capture (process later)
-└── handoffs/            # Session continuity
-```
-
-## Commands
-
-### Store Memories
+| Template | Description |
+|----------|-------------|
+| `brain` | 4-quadrant architecture: vault structure, direction, agent workspace, knowledge graph |
+| `project-board` | Owner-centric kanban with status columns, priority icons, agent/human cards |
+| `default` | Two-column dashboard with activity metrics and task triage |
+| `sprint` | Weekly focus with sprint metrics and open loops |
 
 ```bash
-# With type classification (recommended)
-clawvault remember <type> <title> --content "..."
-# Types: decision, lesson, fact, commitment, project, person
-
-# Quick capture
-clawvault capture "Note to self"
-
-# Manual store
-clawvault store -c decisions -t "Title" --content "..."
+clawvault canvas --template brain
+clawvault canvas --template project-board --owner my-agent
 ```
 
-**Note:** All write commands auto-update the qmd index. Use `--no-index` to skip.
-
-### Search
+### 🔭 Observational Memory
+Auto-compress conversations into prioritized observations. Critical items route to vault categories automatically.
 
 ```bash
-clawvault search "query"           # BM25 keyword
-clawvault search "query" -c people # Filter by category
-clawvault vsearch "query"          # Semantic (local embeddings)
+clawvault observe --compress session.md      # One-shot compression
+clawvault observe --active                   # Incremental from transcripts
 ```
 
-### Browse
+### 🛡️ Context Death Recovery
+Checkpoint/recover system keeps agents alive across crashes and session resets.
 
 ```bash
-clawvault list                # All documents
-clawvault list decisions      # By category
-clawvault get decisions/title # Specific document
-clawvault stats               # Vault overview
-clawvault graph --refresh     # Typed memory graph summary
+clawvault checkpoint --working-on "migration" --focus "step 3"
+clawvault recover                            # After crash/reset
 ```
 
-### Session Continuity
+### 🌐 Tailscale Networking
+Multi-vault collaboration over Tailscale with trust levels and cross-vault search.
 
 ```bash
-# Start a session (recover + recap + summary)
-clawvault wake
-
-# End a session with a handoff
-clawvault sleep "building CRM, fixing webhook" \
-  --blocked "waiting for API key" \
-  --next "deploy to production" \
-  --decisions "chose Supabase over Firebase" \
-  --feeling "focused"
-
-# Manual tools (advanced)
-clawvault handoff --working-on "task1" --next "task2"
-clawvault recap --brief   # Token-efficient recap
-
-# Health check
-clawvault doctor
-
-# OpenClaw compatibility check
-clawvault compat
-
-# CI/automation-friendly compatibility gate
-clawvault compat --strict   # exits non-zero on warnings/errors
-# validates openclaw CLI readiness, hook events/requirements, handler safety/profile delegation, and SKILL metadata
-# flags missing, non-zero, or signal-terminated openclaw CLI checks as warnings
-# warns on unsafe handler execution conventions (execSync usage, shell:true options, missing --profile auto delegation)
-
-# Validate a specific project root (fixtures/CI)
-clawvault compat --strict --base-dir ./tests/compat-fixtures/healthy
-
-# Run strict compatibility fixture matrix (healthy + intentional drift cases)
-npm run test:compat-fixtures
-# fixture expectations are defined in tests/compat-fixtures/cases.json
-# fixture manifest includes schemaVersion for explicit contract evolution (current schemaVersion=2)
-# includes expectedCheckLabels to lock compat check-label contract
-# supports expected status, detail snippets, and hint snippets per check
-# supports openclawExitCode/openclawSignal/openclawMissing for declarative CLI failure simulation cases
-# each case also owns its scenario description (README coverage is validated)
-# expected check labels are validated against live compat output to catch stale contracts
-# includes a fresh build before running fixtures
-
-# Quick smoke check (healthy fixture only)
-npm run test:compat-smoke
-# runs fast contract validation + healthy fixture check (requires existing dist build)
-# fails fast if build artifacts are stale
-
-# Validate compatibility fixture contract only (no full matrix execution)
-npm run test:compat-contract
-# includes manifest/docs/runtime-label parity checks with a fresh build
-
-# Fast contract-only validation (requires existing dist build)
-npm run test:compat-contract:fast
-# fails fast if compat source is newer than dist build artifacts
-
-# Run full local CI gate (typecheck + tests + compat fixtures)
-npm run ci
-# runs build-backed contract validation, fixture matrix execution, and standalone summary artifact validation
-
-# Optional: run only specific compatibility fixtures
-COMPAT_CASES=healthy,missing-events npm run test:compat-fixtures
-# duplicate COMPAT_CASES entries are rejected to prevent ambiguous selection
-# empty/whitespace-only COMPAT_CASES values are rejected as invalid selection input
-# runner logs resolved case selection before execution for easier verification
-
-# Optional: run fast fixture checks without building
-npm run test:compat-fixtures:fast
-
-# Optional: write per-fixture JSON reports to a directory
-COMPAT_REPORT_DIR=/tmp/clawvault-compat-reports npm run test:compat-fixtures
-# includes per-case reports and summary.json (summarySchemaVersion + mode/schemaVersion/selectedCases/selectedTotal + expected/runtime labels + passed/failed case lists + preflight/overall timing + slowest cases)
-# summary artifacts are validated for schema/field invariants before write (fail-fast on malformed report generation)
-# validator now also enforces result-entry schema and passed/failed list coherence with selected case ordering
-# slowestCases telemetry is also validated against case-result durations and sort order
-# summary validation is enforced centrally in summary artifact writing, so all emitters share one contract path
-# per-case report artifacts are also validated centrally before write
-
-# Optional: validate an existing compatibility summary artifact set
-node scripts/validate-compat-summary.mjs /tmp/clawvault-compat-reports/summary.json
-# explicit option form (also supports custom case-report directory)
-node scripts/validate-compat-summary.mjs --summary /tmp/clawvault-compat-reports/summary.json --report-dir /tmp/clawvault-compat-reports
-# summary-only mode when per-case reports are unavailable
-node scripts/validate-compat-summary.mjs --summary /tmp/summary.json --allow-missing-case-reports
-# machine-readable success output for automation
-node scripts/validate-compat-summary.mjs --summary /tmp/summary.json --json
-# json output is schema-versioned and also used for machine-readable error payloads
-# success payload includes summary/fixture schema versions for downstream compatibility checks
-# write validator result payload (success/error) to a file
-node scripts/validate-compat-summary.mjs --summary /tmp/summary.json --json --out /tmp/validator-result.json
-# in CI, compat-summary artifacts now include summary.json + report-schema-validator-result.json + validator-result.json + schema-validator-result.json + validator-result-verifier-result.json + artifact-bundle-validator-result.json + artifact-bundle-manifest-validator-result.json
-# validator payload schema/validation is centralized in scripts/lib/compat-summary-validator-output.mjs
-# JSON schema artifacts for payload contracts live in /schemas (including json-schema-validator-output)
-# generic schema checker CLI lives at scripts/validate-json-schema.mjs
-# schema-validator result payload is written to schema-validator-result.json in compat report dirs
-# summary/case-report artifacts can also be schema-validated via scripts/validate-compat-report-schemas.mjs
-# see validator usage/help
-node scripts/validate-compat-summary.mjs --help
-# equivalent npm wrapper (supports arg passthrough, env fallback)
-npm run test:compat-summary:verify -- /tmp/clawvault-compat-reports/summary.json
-# validate previously emitted validator-result payload directly
-npm run test:compat-validator-result:verify -- /tmp/clawvault-compat-reports/validator-result.json
-# npm verifier wrapper enforces --require-ok by default
-# validate validator-result payload against its JSON schema contract
-npm run test:compat-validator-result:schema
-# validate schema-validator-result payload against its own schema contract
-npm run test:compat-schema-validator-result:verify
-# validate summary.json and per-case report artifacts against schema documents
-npm run test:compat-report-schemas:verify
-# emit report-schema validator output payload + validate its schema contract
-npm run test:compat-report-schemas:verify:report
-npm run test:compat-report-schemas:verify:schema
-# emit verifier output payload + validate verifier payload schema
-npm run test:compat-validator-result:verify:report
-npm run test:compat-validator-result:verify:schema
-# verify full compat artifact bundle contract + emit schema-validated bundle result
-npm run test:compat-artifact-bundle:verify
-npm run test:compat-artifact-bundle:verify:report
-npm run test:compat-artifact-bundle:verify:schema
-npm run test:compat-artifact-bundle:manifest:schema
-npm run test:compat-artifact-bundle:manifest:verify
-npm run test:compat-artifact-bundle:manifest:verify:report
-npm run test:compat-artifact-bundle:manifest:verify:schema
-# bundle result now includes an artifactContracts manifest (artifact path + schema id + expected/actual schema version), now including artifact-bundle-manifest-validator-result.json
-# bundle validator supports --manifest <path> to override the default contract manifest
-# manifest verifier emits artifact-bundle-manifest-validator-result.json with schemaId/version-field contract checks
-# explicit verifier CLI options:
-node scripts/validate-compat-validator-result.mjs --validator-result /tmp/clawvault-compat-reports/validator-result.json --json --out /tmp/verifier-result.json
-# enforce success-only validator-result status in strict automation paths
-node scripts/validate-compat-validator-result.mjs --validator-result /tmp/clawvault-compat-reports/validator-result.json --require-ok
-# use --help for verifier usage and path-resolution rules
-# or run fixture generation + standalone summary validation together
-npm run test:compat-summary:fast
-# debug stack wrappers individually when isolating compat contract drift
-npm run test:compat-report-stack:fast
-npm run test:compat-validator-stack:fast
-npm run test:compat-artifact-stack:fast
-# script behavior is covered by dedicated unit tests (success + failure + env fallback)
-# validator exits with a clear error when no summary path/source input is provided
-# summary scripts respect COMPAT_REPORT_DIR (defaults to .compat-reports when unset)
-# report parsing now validates per-check schema and warning/error count coherence before artifact evaluation
+clawvault serve                              # Start API server
+clawvault peers                              # Manage vault peers
+clawvault net-search "query"                 # Search across vaults
 ```
 
+## Setup & Customization
 
-## Agent Setup (AGENTS.md)
-
-Add this to your `AGENTS.md` to ensure proper memory habits:
-
-```markdown
-## Memory
+```bash
+# Full setup with neural graph theme + Obsidian Bases views
+clawvault setup --theme neural --canvas brain
 
-**Write everything down. Memory doesn't survive session restarts.**
+# Minimal agent vault
+clawvault init ./memory --minimal
 
-### Search (use qmd, not memory_search)
-\`\`\`bash
-qmd search "query" -c your-memory    # Fast keyword
-qmd vsearch "query" -c your-memory   # Semantic
-\`\`\`
+# Custom categories
+clawvault init ./memory --categories "notes,research,code"
 
-### Store
-\`\`\`bash
-clawvault remember decision "Title" --content "..."
-clawvault remember lesson "Title" --content "..."
-\`\`\`
+# Skip visual config
+clawvault setup --no-graph-colors --no-bases
+```
 
-### Session Start
-\`\`\`bash
-clawvault wake
-\`\`\`
+### Graph Themes
 
-### Session End
-\`\`\`bash
-clawvault sleep "..." --next "..."
-\`\`\`
+| Theme | Description |
+|-------|-------------|
+| `neural` | Dark background, colored nodes by category, green network links, golden glow |
+| `minimal` | Subtle category colors, no background changes |
+| `none` | Skip graph theming |
 
-### Checkpoint (during heavy work)
-\`\`\`bash
-clawvault checkpoint --working-on "..." --focus "..." --blocked "..."
-\`\`\`
+## Vault Structure
 
 ```
+memory/
+├── .clawvault.json          # Vault config
+├── .clawvault/
+│   └── graph-index.json     # Knowledge graph
+├── tasks/                   # Active tasks (markdown + frontmatter)
+├── backlog/                 # Ideas and future work
+├── decisions/               # Choices with reasoning
+├── lessons/                 # Things learned
+├── people/                  # One file per person
+├── projects/                # Active work
+├── commitments/             # Promises and deadlines
+├── inbox/                   # Quick captures
+├── handoffs/                # Session continuity
+├── ledger/
+│   ├── raw/                 # Raw session transcripts
+│   ├── observations/        # Compressed observations
+│   └── reflections/         # Weekly reflections
+├── all-tasks.base           # Obsidian Bases view
+├── by-owner.base            # Tasks by owner
+└── dashboard.canvas         # Generated dashboard
+```
+
+## For OpenClaw Agents
 
-## Templates
-
-ClawVault includes templates for common memory types:
+```bash
+# Install as a skill
+clawhub install clawvault
 
-- `decision.md` — Choices with context and reasoning
-- `lesson.md` — Things learned
-- `person.md` — People you work with
-- `project.md` — Active work
-- `handoff.md` — Session state before context death
-- `daily.md` — Daily notes
+# Or add to your agent's tools
+npm install -g clawvault
+```
 
-Use with: `clawvault store -c category -t "Title" -f decision`
+Add to your `AGENTS.md`:
 
-## Library Usage
+```markdown
+## Memory
+- `clawvault wake` on session start
+- `clawvault sleep "summary" --next "next steps"` on session end
+- `clawvault checkpoint` every 10-15 min during heavy work
+- `clawvault remember <type> "title" --content "..."` for important items
+- `clawvault search "query"` before asking questions
+```
 
-```typescript
-import { ClawVault, createVault, findVault } from 'clawvault';
+## Requirements
 
-const vault = await createVault('./memory', { qmdCollection: 'my-memory' });
+- **Node.js 18+**
+- **[qmd](https://github.com/Versatly/qmd)** — Local semantic search (optional but recommended)
 
-await vault.store({
-  category: 'decisions',
-  title: 'Use ClawVault',
-  content: 'Decided to use ClawVault for memory.',
-});
+## Docs
 
-const results = await vault.find('memory', { limit: 5 });
-```
+Full documentation at **[docs.clawvault.dev](https://docs.clawvault.dev)**
 
 ## License
 
@@ -404,4 +196,4 @@ MIT
 
 ---
 
-*"An elephant never forgets." — Now neither do you.* 🐘
+*Built by [Versatly](https://versatly.com) — autonomous AI employees for businesses.* 🐘

package/bin/register-core-commands.js

@@ -13,6 +13,13 @@ export function registerCoreCommands(
     .option('-n, --name <name>', 'Vault name')
     .option('--qmd', 'Set up qmd semantic search collection')
     .option('--qmd-collection <name>', 'qmd collection name (defaults to vault name)')
+    .option('--no-bases', 'Skip Obsidian Bases file generation')
+    .option('--no-tasks', 'Skip tasks/ and backlog/ directories')
+    .option('--no-graph', 'Skip initial graph build')
+    .option('--categories <list>', 'Comma-separated list of custom categories to create')
+    .option('--canvas <template>', 'Generate a canvas dashboard on init (default, brain, project-board, sprint)')
+    .option('--theme <style>', 'Graph color theme to apply (neural, minimal, none)', 'none')
+    .option('--minimal', 'Create minimal vault (memory categories only, no tasks/bases/graph)')
     .action(async (vaultPath, options) => {
       const targetPath = vaultPath || '.';
       console.log(chalk.cyan(`\n🐘 Initializing ClawVault at ${path.resolve(targetPath)}...\n`));
@@ -67,10 +74,26 @@ export function registerCoreCommands(
   program
     .command('setup')
     .description('Auto-discover and configure a ClawVault')
-    .action(async () => {
+    .option('--graph-colors', 'Set up graph color scheme for Obsidian')
+    .option('--no-graph-colors', 'Skip graph color configuration')
+    .option('--bases', 'Generate Obsidian Bases views for task management')
+    .option('--no-bases', 'Skip Bases file generation')
+    .option('--canvas [template]', 'Generate canvas dashboard (default, brain, project-board, sprint)')
+    .option('--no-canvas', 'Skip canvas generation')
+    .option('--theme <style>', 'Graph color theme (neural, minimal, none)', 'neural')
+    .option('--force', 'Overwrite existing configuration files')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
       try {
         const { setupCommand } = await import('../dist/commands/setup.js');
-        await setupCommand();
+        await setupCommand({
+          graphColors: options.graphColors,
+          bases: options.bases,
+          canvas: options.canvas,
+          theme: options.theme,
+          force: options.force,
+          vault: options.vault
+        });
       } catch (err) {
         console.error(chalk.red(`Error: ${err.message}`));
         process.exit(1);

package/bin/register-task-commands.js

@@ -242,12 +242,28 @@ export function registerTaskCommands(
     .description('Generate Obsidian canvas dashboard')
     .option('-v, --vault <path>', 'Vault path')
     .option('--output <path>', 'Output file path (default: dashboard.canvas)')
+    .option('--template <id>', 'Canvas template ID (default, project-board, brain, sprint)')
+    .option('--project <project>', 'Project filter for template-aware canvases')
+    .option('--owner <owner>', 'Filter tasks by owner (agent name or human)')
+    .option('--width <pixels>', 'Canvas width in pixels', parseInt)
+    .option('--height <pixels>', 'Canvas height in pixels', parseInt)
+    .option('--include-done', 'Include completed tasks (default: limited)')
+    .option('--list-templates', 'List available canvas templates and exit')
     .action(async (options) => {
       try {
-        const vaultPath = resolveVaultPath(options.vault);
+        const vaultPath = options.listTemplates
+          ? (options.vault || '.')
+          : resolveVaultPath(options.vault);
         const { canvasCommand } = await import('../dist/commands/canvas.js');
         await canvasCommand(vaultPath, {
-          output: options.output
+          output: options.output,
+          template: options.template,
+          project: options.project,
+          owner: options.owner,
+          width: options.width,
+          height: options.height,
+          includeDone: options.includeDone,
+          listTemplates: options.listTemplates
         });
       } catch (err) {
         console.error(chalk.red(`Error: ${err.message}`));

package/bin/register-task-commands.test.js

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { Command } from 'commander';
+import { registerTaskCommands } from './register-task-commands.js';
+import { chalkStub, stubResolveVaultPath } from './test-helpers/cli-command-fixtures.js';
+
+describe('register-task-commands', () => {
+  it('adds canvas template and listing flags', () => {
+    const program = new Command();
+    registerTaskCommands(program, {
+      chalk: chalkStub,
+      resolveVaultPath: stubResolveVaultPath
+    });
+
+    const canvasCommand = program.commands.find((command) => command.name() === 'canvas');
+    expect(canvasCommand).toBeDefined();
+
+    const optionFlags = canvasCommand?.options.map((option) => option.flags) ?? [];
+    expect(optionFlags).toEqual(expect.arrayContaining([
+      '--template <id>',
+      '--list-templates',
+      '--project <project>'
+    ]));
+  });
+});