@upgraide/ui-notes-cli 0.1.3 → 0.2.1

package/README.md

@@ -45,10 +45,12 @@ uinotes config
 
 # Set a value
 uinotes config set apiUrl https://my-api.example.com
-uinotes config set defaultProject my-app
+
+# Bind a project to the current directory
+uinotes set project my-app
 ```
 
-**Config keys:** `apiUrl`, `apiKey`, `defaultProject`
+**Config keys:** `apiUrl`, `apiKey`
 
 ### `uinotes projects`
 
@@ -122,11 +124,19 @@ The CLI looks for config in two places (local takes priority):
 ```json
 {
   "apiUrl": "http://localhost:3000",
-  "apiKey": "your-api-key",
-  "defaultProject": "my-app"
+  "apiKey": "your-api-key"
 }
 ```
 
+### Project Binding
+
+Run `uinotes set project <slug>` to create a `.uinotes` file in the current directory. This binds the project to the directory tree so all commands automatically use it — no `--project` flag needed.
+
+The CLI resolves the project in this order:
+1. `--project` flag (explicit override)
+2. `.uinotes` file in current directory or nearest parent
+3. No project (commands that require one will error)
+
 API keys are redacted when displayed with `uinotes config`.
 
 ## Global Options

package/api.ts

@@ -11,7 +11,7 @@ export async function apiFetch(
     'x-api-key': config.apiKey,
   };
 
-  const targetProject = project || config.defaultProject;
+  const targetProject = project || config.project;
   if (targetProject) {
     headers['x-project'] = targetProject;
   }

package/commands/batch.ts

@@ -0,0 +1,116 @@
+import type { Config } from '../config.js';
+import { apiFetch } from '../api.js';
+import { readFileSync } from 'fs';
+
+interface BatchOp {
+  op: 'resolve' | 'wontfix' | 'comment' | 'reopen';
+  id: string;
+  message?: string;
+  text?: string;
+}
+
+interface BatchOptions {
+  project?: string;
+  concurrency?: number;
+  dryRun?: boolean;
+}
+
+export async function batch(config: Config, source: string, opts: BatchOptions): Promise<void> {
+  let input: string;
+  if (source === '-') {
+    input = await readStdin();
+  } else {
+    input = readFileSync(source, 'utf-8');
+  }
+
+  const lines = input.trim().split('\n').filter(l => l.trim());
+  const ops: BatchOp[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    try {
+      ops.push(JSON.parse(lines[i]));
+    } catch {
+      console.error(`Line ${i + 1}: invalid JSON — skipped`);
+    }
+  }
+
+  if (ops.length === 0) {
+    console.log('No operations to execute.');
+    return;
+  }
+
+  if (opts.dryRun) {
+    console.log(`Dry run: ${ops.length} operations`);
+    for (let i = 0; i < ops.length; i++) {
+      console.log(`[${i + 1}/${ops.length}] ${ops[i].op} ${ops[i].id}`);
+    }
+    return;
+  }
+
+  const concurrency = opts.concurrency || 5;
+  let succeeded = 0;
+  let failed = 0;
+
+  for (let i = 0; i < ops.length; i += concurrency) {
+    const chunk = ops.slice(i, i + concurrency);
+    await Promise.allSettled(
+      chunk.map(async (op, idx) => {
+        const globalIdx = i + idx;
+        try {
+          await executeOp(config, op, opts.project);
+          succeeded++;
+          console.log(`[${globalIdx + 1}/${ops.length}] ${op.op} ${op.id} ✓`);
+        } catch (err: any) {
+          failed++;
+          console.log(`[${globalIdx + 1}/${ops.length}] ${op.op} ${op.id} ✗ ${err.message}`);
+        }
+      })
+    );
+  }
+
+  console.log(`Batch complete: ${succeeded}/${ops.length} succeeded${failed > 0 ? `, ${failed} failed` : ''}`);
+}
+
+async function executeOp(config: Config, op: BatchOp, project?: string): Promise<void> {
+  switch (op.op) {
+    case 'resolve':
+      await apiFetch(config, `/notes/${op.id}`, {
+        method: 'PATCH',
+        body: { status: 'resolved', resolution: op.message },
+        project,
+      });
+      break;
+    case 'wontfix':
+      await apiFetch(config, `/notes/${op.id}`, {
+        method: 'PATCH',
+        body: { status: 'wontfix', resolution: op.message },
+        project,
+      });
+      break;
+    case 'comment':
+      if (!op.text) throw new Error('Missing "text" field for comment operation');
+      await apiFetch(config, `/notes/${op.id}/comments`, {
+        method: 'POST',
+        body: { body: op.text },
+        project,
+      });
+      break;
+    case 'reopen':
+      await apiFetch(config, `/notes/${op.id}`, {
+        method: 'PATCH',
+        body: { status: 'open' },
+        project,
+      });
+      break;
+    default:
+      throw new Error(`Unknown operation: ${(op as any).op}`);
+  }
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}

package/commands/bulk-resolve.ts

@@ -31,9 +31,9 @@ async function bulkResolve(
   filterValue: string,
   opts: BulkResolveOptions,
 ): Promise<void> {
-  const project = opts.project || config.defaultProject;
+  const project = opts.project || config.project;
   if (!project) {
-    console.error('No project specified. Use --project or set defaultProject in config.');
+    console.error('No project specified. Use --project or run: uinotes set project <slug>');
     process.exit(1);
   }
 

package/commands/changelog.ts

@@ -0,0 +1,150 @@
+import type { Config } from '../config.js';
+import { apiFetch } from '../api.js';
+
+interface ChangelogOptions {
+  project?: string;
+  since?: string;
+  format?: 'markdown' | 'json' | 'conventional';
+}
+
+interface Note {
+  id: string;
+  type: string;
+  body: string;
+  component: string | null;
+  resolved_at: string | null;
+}
+
+const TYPE_ORDER = ['bug', 'ux', 'feature', 'question'];
+
+const TYPE_LABELS: Record<string, string> = {
+  bug: 'Bugs',
+  ux: 'UX',
+  feature: 'Features',
+  question: 'Questions',
+};
+
+const TYPE_CONVENTIONAL: Record<string, string> = {
+  bug: 'fix',
+  ux: 'style',
+  feature: 'feat',
+  question: 'docs',
+};
+
+function isISODate(value: string): boolean {
+  return /^\d{4}-\d{2}-\d{2}/.test(value);
+}
+
+function resolveTimestamp(since: string): string {
+  if (isISODate(since)) {
+    return since;
+  }
+
+  // Treat as git ref, resolve to ISO timestamp
+  const result = Bun.spawnSync(['git', 'log', '-1', '--format=%cI', since]);
+  const output = result.stdout.toString().trim();
+
+  if (result.exitCode !== 0 || !output) {
+    throw new Error(`Could not resolve git ref "${since}". Make sure it exists.`);
+  }
+
+  return output;
+}
+
+function formatMarkdown(notes: Note[]): string {
+  const grouped: Record<string, Note[]> = {};
+
+  for (const note of notes) {
+    if (!grouped[note.type]) grouped[note.type] = [];
+    grouped[note.type].push(note);
+  }
+
+  const lines: string[] = ['## UI Notes Resolved', ''];
+
+  for (const type of TYPE_ORDER) {
+    const group = grouped[type];
+    if (!group || group.length === 0) continue;
+
+    lines.push(`### ${TYPE_LABELS[type] || type}`);
+    for (const note of group) {
+      const shortId = note.id.slice(0, 8);
+      const body = note.body.split('\n')[0].trim();
+      lines.push(`- ${body} (#${shortId})`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatConventional(notes: Note[]): string {
+  const lines: string[] = [];
+
+  for (const type of TYPE_ORDER) {
+    const group = notes.filter((n) => n.type === type);
+    for (const note of group) {
+      const prefix = TYPE_CONVENTIONAL[note.type] || note.type;
+      const scope = note.component || 'ui';
+      const body = note.body.split('\n')[0].trim();
+      const shortId = note.id.slice(0, 8);
+      lines.push(`${prefix}(${scope}): ${body} (note:${shortId})`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function formatJSON(notes: Note[]): string {
+  const items = notes.map((n) => ({
+    id: n.id,
+    type: n.type,
+    body: n.body,
+    component: n.component,
+    resolved_at: n.resolved_at,
+  }));
+  return JSON.stringify(items, null, 2);
+}
+
+export async function changelog(config: Config, opts: ChangelogOptions): Promise<void> {
+  const since = opts.since;
+  if (!since) {
+    console.error('--since is required. Provide a git ref (e.g., HEAD~5, v1.2.0) or ISO date (e.g., 2026-02-01).');
+    process.exit(1);
+  }
+
+  const timestamp = resolveTimestamp(since);
+  const format = opts.format || 'markdown';
+
+  const params = new URLSearchParams();
+  params.set('status', 'all');
+  params.set('resolved_after', timestamp);
+  params.set('limit', '500');
+
+  const path = `/notes?${params.toString()}`;
+  const response = (await apiFetch(config, path, { project: opts.project })) as {
+    ok: boolean;
+    data: { notes: Note[] };
+  };
+
+  const notes = response.data.notes
+    .filter((n) => n.resolved_at)
+    .sort((a, b) => (a.resolved_at! > b.resolved_at! ? 1 : -1));
+
+  if (notes.length === 0) {
+    console.log('No resolved notes found since ' + timestamp);
+    return;
+  }
+
+  switch (format) {
+    case 'json':
+      console.log(formatJSON(notes));
+      break;
+    case 'conventional':
+      console.log(formatConventional(notes));
+      break;
+    case 'markdown':
+    default:
+      console.log(formatMarkdown(notes));
+      break;
+  }
+}

package/commands/config.ts

@@ -1,6 +1,6 @@
 import { getConfig, getConfigPath, setConfigValue } from '../config.js';
 
-const VALID_KEYS = ['apiUrl', 'apiKey', 'defaultProject'];
+const VALID_KEYS = ['apiUrl', 'apiKey'];
 
 function redactKey(value: string): string {
   if (!value || value.length <= 4) return '****';

package/commands/context.ts

@@ -55,7 +55,7 @@ export async function context(config: Config, opts: ContextOptions): Promise<voi
   const output = formatNotesForAI(notes, {
     format: opts.format || 'markdown',
     componentFilter: opts.component,
-    projectName: opts.project || config.defaultProject || 'unknown',
+    projectName: opts.project || config.project || 'unknown',
     resolvedNotes: resolvedMap,
   });
 

package/commands/explain.ts

@@ -0,0 +1,67 @@
+import type { Config } from '../config.js';
+import { apiFetch } from '../api.js';
+
+interface ExplainOptions {
+  format?: 'markdown' | 'json';
+  project?: string;
+}
+
+export async function explain(config: Config, noteId: string, opts: ExplainOptions): Promise<void> {
+  const response = await apiFetch(config, `/notes/${noteId}/explain`, {
+    project: opts.project,
+  }) as any;
+
+  const { note, comments, history, visual_diffs } = response.data;
+
+  if (opts.format === 'json') {
+    console.log(JSON.stringify(response.data, null, 2));
+    return;
+  }
+
+  // Default: markdown format
+  const lines: string[] = [];
+  lines.push(`# Note ${note.id} — ${note.type} (${note.status})`);
+  lines.push('');
+  if (note.component) lines.push(`**Component**: ${note.component}`);
+  if (note.selector) lines.push(`**Selector**: \`${note.selector}\``);
+  lines.push(`**URL**: ${note.url}`);
+  if (note.author) lines.push(`**Author**: ${note.author}`);
+  lines.push(`**Created**: ${note.created_at}`);
+  if (note.resolved_at) lines.push(`**Resolved**: ${note.resolved_at}`);
+  if (note.screenshot_url) lines.push(`**Screenshot**: ${note.screenshot_url}`);
+  lines.push('');
+  lines.push(`> ${note.body}`);
+
+  if (comments.length > 0) {
+    lines.push('');
+    lines.push(`## Comments (${comments.length})`);
+    lines.push('');
+    for (const c of comments) {
+      lines.push(`**${c.author}** (${c.created_at}):`);
+      lines.push(`> ${c.body}`);
+      lines.push('');
+    }
+  }
+
+  if (history.length > 0) {
+    lines.push('## History');
+    lines.push('');
+    for (const h of history) {
+      lines.push(`- ${h.changed_at}: ${h.field} ${h.old_value ?? '(none)'} → ${h.new_value ?? '(none)'}${h.changed_by ? ` (${h.changed_by})` : ''}`);
+    }
+  }
+
+  if (visual_diffs.length > 0) {
+    lines.push('');
+    lines.push(`## Visual Diffs (${visual_diffs.length})`);
+    lines.push('');
+    for (const vd of visual_diffs) {
+      lines.push(`- ${vd.created_at}: diff ${vd.diff_percentage != null ? `${vd.diff_percentage}%` : 'N/A'}`);
+      if (vd.before_url) lines.push(`  Before: ${vd.before_url}`);
+      if (vd.after_url) lines.push(`  After: ${vd.after_url}`);
+      if (vd.diff_url) lines.push(`  Diff: ${vd.diff_url}`);
+    }
+  }
+
+  console.log(lines.join('\n'));
+}

package/commands/install-skills.ts

@@ -0,0 +1,58 @@
+import type { Config } from '../config.js';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+interface InstallSkillsOptions {
+  dir?: string;
+  check?: boolean;
+}
+
+const DEFAULT_DIR = '.claude/skills';
+
+export async function installSkills(_config: Config, opts: InstallSkillsOptions): Promise<void> {
+  const targetDir = opts.dir || join(process.cwd(), DEFAULT_DIR);
+  const skillsSourceDir = join(import.meta.dir, '..', 'skills');
+
+  // List available skills
+  let skillFiles: string[];
+  try {
+    skillFiles = readdirSync(skillsSourceDir).filter(f => f.endsWith('.md'));
+  } catch {
+    console.error('Could not read bundled skill files.');
+    process.exit(1);
+  }
+
+  if (skillFiles.length === 0) {
+    console.error('No skill files found in package.');
+    process.exit(1);
+  }
+
+  if (opts.check) {
+    // Check installed vs bundled
+    console.log('Skill status:');
+    for (const file of skillFiles) {
+      const targetPath = join(targetDir, file);
+      if (existsSync(targetPath)) {
+        console.log(`  ${file}: installed`);
+      } else {
+        console.log(`  ${file}: not installed`);
+      }
+    }
+    return;
+  }
+
+  // Install skills
+  mkdirSync(targetDir, { recursive: true });
+
+  for (const file of skillFiles) {
+    const sourcePath = join(skillsSourceDir, file);
+    const targetPath = join(targetDir, file);
+    const content = readFileSync(sourcePath, 'utf-8');
+    writeFileSync(targetPath, content);
+  }
+
+  console.log(`Installed ${skillFiles.length} skills to ${targetDir}/`);
+  for (const file of skillFiles) {
+    console.log(`  ${file}`);
+  }
+}

package/commands/schema.ts

@@ -0,0 +1,33 @@
+import type { Config } from '../config.js';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+const RESOURCES = ['notes', 'comments', 'projects', 'webhooks'];
+
+export async function schema(_config: Config, resource?: string): Promise<void> {
+  if (!resource) {
+    console.log('Available schemas:');
+    for (const r of RESOURCES) {
+      console.log(`  ${r}`);
+    }
+    console.log('\nUsage: uinotes schema --resource <name>');
+    return;
+  }
+
+  if (!RESOURCES.includes(resource)) {
+    console.error(`Unknown resource: ${resource}`);
+    console.error(`Available: ${RESOURCES.join(', ')}`);
+    process.exit(1);
+  }
+
+  const schemaDir = join(import.meta.dir, '..', 'schemas');
+  const schemaPath = join(schemaDir, `${resource}.json`);
+
+  try {
+    const content = readFileSync(schemaPath, 'utf-8');
+    console.log(content);
+  } catch {
+    console.error(`Schema file not found: ${schemaPath}`);
+    process.exit(1);
+  }
+}

package/commands/set.ts

@@ -0,0 +1,9 @@
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+
+export function setProject(slug: string): void {
+  const filePath = join(process.cwd(), '.uinotes');
+  writeFileSync(filePath, JSON.stringify({ project: slug }, null, 2) + '\n');
+  console.log(`Bound project "${slug}" to ${process.cwd()}`);
+  console.log(`Created .uinotes — commit this file so your team and AI agents inherit it.`);
+}

package/commands/visual-diff.ts

@@ -37,9 +37,9 @@ async function loadPlaywright() {
 }
 
 export async function visualDiff(config: Config, opts: VisualDiffOptions): Promise<void> {
-  const project = opts.project || config.defaultProject;
+  const project = opts.project || config.project;
   if (!project) {
-    console.error('Error: --project is required (or set defaultProject in config)');
+    console.error('Error: --project is required (or run: uinotes set project <slug>)');
     process.exit(1);
   }
 

package/config.ts

@@ -11,7 +11,7 @@ export interface ResolveConfig {
 export interface Config {
   apiUrl: string;
   apiKey: string;
-  defaultProject?: string;
+  project?: string;
   resolve?: ResolveConfig;
 }
 
@@ -23,11 +23,34 @@ const DEFAULT_CONFIG: Config = {
   apiKey: '',
 };
 
-function readJsonFile(path: string): Config | null {
+function readJsonFile(path: string): Record<string, any> | null {
   if (!existsSync(path)) return null;
   return JSON.parse(readFileSync(path, 'utf-8'));
 }
 
+/**
+ * Walk up the directory tree from cwd looking for a .uinotes file
+ * that binds a project slug to this directory tree.
+ */
+function findDirectoryProject(startDir: string): string | undefined {
+  let dir = startDir;
+  while (true) {
+    const filePath = join(dir, '.uinotes');
+    if (existsSync(filePath)) {
+      try {
+        const content = JSON.parse(readFileSync(filePath, 'utf-8'));
+        if (content.project) return content.project;
+      } catch {
+        // Invalid JSON — skip
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+  return undefined;
+}
+
 export function getConfigPath(): string {
   if (existsSync(LOCAL_PATH)) return LOCAL_PATH;
   return GLOBAL_PATH;
@@ -36,14 +59,22 @@ export function getConfigPath(): string {
 export function getConfig(): Config {
   // Per-repo config takes priority
   const local = readJsonFile(LOCAL_PATH);
-  if (local) return { ...DEFAULT_CONFIG, ...local };
+  const base = local
+    ? { ...DEFAULT_CONFIG, ...local }
+    : (() => {
+        const global = readJsonFile(GLOBAL_PATH);
+        if (global) return { ...DEFAULT_CONFIG, ...global };
+        // Create default global config
+        writeFileSync(GLOBAL_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n');
+        return { ...DEFAULT_CONFIG };
+      })();
 
-  const global = readJsonFile(GLOBAL_PATH);
-  if (global) return { ...DEFAULT_CONFIG, ...global };
+  // Resolve project from .uinotes directory binding (if not already set)
+  if (!base.project) {
+    base.project = findDirectoryProject(process.cwd());
+  }
 
-  // Create default global config
-  writeFileSync(GLOBAL_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n');
-  return DEFAULT_CONFIG;
+  return base as Config;
 }
 
 export function setConfigValue(key: string, value: string): Config {

package/index.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env bun
 
 import { getConfig } from './config.js';
 import { configShow, configSet } from './commands/config.js';
@@ -22,16 +22,22 @@ Commands:
   projects add-url <slug> <pattern>     Add URL pattern to project
   projects remove-url <slug> <pattern>  Remove URL pattern
   projects delete <slug>                Archive a project
+  set project <slug>                    Bind project to current directory
   login                                 Login and create API key
   pull                                  Fetch open notes
   context                               AI-optimized digest of open notes
+  explain <id>                          Full context for a single note
   resolve <id>                          Mark note as resolved
   wontfix <id>                          Mark note as won't fix
   comment <id> "text"                   Add a comment to a note
   comments <id>                         List comments for a note
   resolve-by-component <name> [msg]     Bulk resolve notes by component
   resolve-by-selector <sel> [msg]       Bulk resolve notes by selector
+  changelog                             Generate changelog from resolved notes
   visual-diff                           Capture & compare page screenshots
+  batch <file|->                        Execute NDJSON batch operations
+  schema                                List or print API resource schemas
+  install-skills                        Install Claude Code skill files
   config                                View/edit configuration
 
 Options:
@@ -47,7 +53,13 @@ Options:
   --root-dir <dir>  Source root for file resolution (default: cwd)
   --compare         Compare current screenshots against previous (visual-diff)
   --width <px>      Viewport width for screenshots (default: 1280)
-  --full-page       Capture full page height (default: true)`;
+  --full-page       Capture full page height (default: true)
+  --since <ref>     Git ref or ISO date for changelog start
+  --dir <path>      Target directory for skill installation
+  --check           Check installed skill versions
+  --resource <name> Resource name for schema command
+  --concurrency <n> Concurrent batch operations (default: 5)
+  --dry-run         Preview batch operations without executing`;
 
 function parseFlags(args: string[]): { flags: Record<string, string>; arrays: Record<string, string[]>; positional: string[] } {
   const flags: Record<string, string> = {};
@@ -116,13 +128,47 @@ async function main() {
     return;
   }
 
+  // set command is local-only, no API key needed
+  if (command === 'set') {
+    const sub = positional[1];
+    if (sub === 'project') {
+      const slug = positional[2];
+      if (!slug) {
+        console.error('Usage: uinotes set project <slug>');
+        process.exit(1);
+      }
+      const { setProject } = await import('./commands/set.js');
+      setProject(slug);
+      return;
+    }
+    console.error(`Unknown set subcommand: ${sub}`);
+    process.exit(1);
+  }
+
+  // Schema command is local-only, no API key needed
+  if (command === 'schema') {
+    const { schema } = await import('./commands/schema.js');
+    await schema(getConfig(), flags.resource);
+    return;
+  }
+
+  // install-skills is local-only, no API key needed
+  if (command === 'install-skills') {
+    const { installSkills } = await import('./commands/install-skills.js');
+    await installSkills(getConfig(), {
+      dir: flags.dir,
+      check: flags.check === 'true',
+    });
+    return;
+  }
+
   const config = getConfig();
   if (!config.apiKey) {
     console.error('No API key configured. Run: uinotes config set apiKey <your-key>');
     process.exit(1);
   }
 
-  const project = flags.project;
+  const project = flags.project || config.project;
 
   switch (command) {
     case 'projects': {
@@ -230,6 +276,20 @@ async function main() {
       });
       break;
 
+    case 'explain': {
+      const id = positional[1];
+      if (!id) {
+        console.error('Usage: uinotes explain <note-id> [--format markdown|json]');
+        process.exit(1);
+      }
+      const { explain } = await import('./commands/explain.js');
+      await explain(config, id, {
+        project,
+        format: (flags.format as 'markdown' | 'json') || undefined,
+      });
+      break;
+    }
+
     case 'resolve': {
       const id = positional[1];
       if (!id) {
@@ -288,6 +348,16 @@ async function main() {
       break;
     }
 
+    case 'changelog': {
+      const { changelog } = await import('./commands/changelog.js');
+      await changelog(config, {
+        project,
+        since: flags.since,
+        format: (flags.format as 'markdown' | 'json' | 'conventional') || undefined,
+      });
+      break;
+    }
+
     case 'visual-diff': {
       const { visualDiff } = await import('./commands/visual-diff.js');
       await visualDiff(config, {
@@ -300,6 +370,21 @@ async function main() {
       break;
     }
 
+    case 'batch': {
+      const source = positional[1];
+      if (!source) {
+        console.error('Usage: uinotes batch <file|-> [--concurrency 5] [--dry-run]');
+        process.exit(1);
+      }
+      const { batch } = await import('./commands/batch.js');
+      await batch(config, source, {
+        project,
+        concurrency: flags.concurrency ? parseInt(flags.concurrency) : undefined,
+        dryRun: flags['dry-run'] === 'true',
+      });
+      break;
+    }
+
     case 'resolve-by-selector': {
       const sel = positional[1];
       if (!sel) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upgraide/ui-notes-cli",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "CLI for UI Notes - pull and manage UI feedback notes",
   "license": "MIT",
   "keywords": ["cli", "ui", "notes", "feedback", "ui-notes"],
@@ -11,7 +11,9 @@
     "*.ts",
     "commands/*.ts",
     "formatters/*.ts",
-    "resolvers/*.ts"
+    "resolvers/*.ts",
+    "schemas/*.json",
+    "skills/*.md"
   ],
   "engines": {
     "bun": ">=1.0.0"

package/schemas/comments.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Comment",
+  "description": "A comment on a note",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Unique comment identifier" },
+    "note_id": { "type": "string", "description": "ID of the parent note" },
+    "author": { "type": "string", "description": "Comment author" },
+    "body": { "type": "string", "description": "Comment text" },
+    "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }
+  },
+  "required": ["id", "note_id", "author", "body", "created_at"]
+}

package/schemas/notes.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Note",
+  "description": "A UI feedback note attached to a page element",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Unique note identifier" },
+    "project": { "type": "string", "description": "Project slug this note belongs to" },
+    "type": { "type": "string", "enum": ["bug", "ux", "feature", "question"], "description": "Type of feedback" },
+    "status": { "type": "string", "enum": ["open", "resolved", "wontfix"], "description": "Current status" },
+    "body": { "type": "string", "description": "Note content/description" },
+    "url": { "type": "string", "description": "Page URL where the note was created" },
+    "component": { "type": ["string", "null"], "description": "Component name from data attributes" },
+    "text_content": { "type": ["string", "null"], "description": "Text content of the annotated element" },
+    "selector": { "type": ["string", "null"], "description": "CSS selector for the annotated element" },
+    "tag": { "type": ["string", "null"], "description": "HTML tag of the annotated element" },
+    "author": { "type": ["string", "null"], "description": "Author email or name" },
+    "screenshot_url": { "type": ["string", "null"], "description": "URL to the screenshot capture" },
+    "resolution": { "type": ["string", "null"], "description": "Resolution message when resolved" },
+    "resolved_at": { "type": ["string", "null"], "format": "date-time", "description": "When the note was resolved" },
+    "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }
+  },
+  "required": ["id", "project", "type", "status", "body", "url", "created_at"]
+}

package/schemas/projects.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Project",
+  "description": "A UI Notes project that groups notes",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Unique project identifier" },
+    "slug": { "type": "string", "description": "URL-friendly project identifier" },
+    "name": { "type": "string", "description": "Display name" },
+    "url_patterns": { "type": "array", "items": { "type": "string" }, "description": "URL glob patterns for auto-matching" },
+    "archived": { "type": "boolean", "description": "Whether the project is archived" },
+    "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }
+  },
+  "required": ["id", "slug", "name", "created_at"]
+}

package/schemas/webhooks.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Webhook",
+  "description": "A webhook endpoint for receiving note events",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Unique webhook identifier" },
+    "project_id": { "type": "string", "description": "Project this webhook belongs to" },
+    "url": { "type": "string", "description": "Webhook delivery URL" },
+    "secret": { "type": ["string", "null"], "description": "HMAC signing secret" },
+    "events": { "type": "array", "items": { "type": "string" }, "description": "Events to subscribe to" },
+    "active": { "type": "boolean", "description": "Whether the webhook is active" },
+    "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }
+  },
+  "required": ["id", "project_id", "url", "events", "active", "created_at"]
+}

package/skills/uinotes-batch.md

@@ -0,0 +1,23 @@
+---
+name: uinotes-batch
+description: Execute multiple note operations in a single call using NDJSON. Use for bulk triage of multiple notes.
+---
+
+# uinotes-batch
+
+Execute multiple operations (resolve, wontfix, comment, reopen) in one invocation.
+
+## When to use
+- After triaging multiple notes and deciding actions for each
+- When resolving several notes as part of a single fix
+- For bulk operations that span multiple notes
+
+## Command
+```bash
+echo '{"op":"resolve","id":"abc123","message":"Fixed overflow"}
+{"op":"comment","id":"def456","text":"Needs design input"}
+{"op":"wontfix","id":"ghi789","message":"Deprecated component"}' | uinotes batch -
+```
+
+Operations: `resolve`, `wontfix`, `comment` (requires `text`), `reopen`.
+Add `--dry-run` to preview without executing.

package/skills/uinotes-changelog.md

@@ -0,0 +1,22 @@
+---
+name: uinotes-changelog
+description: Generate a changelog from resolved UI notes. Use after resolving notes to create release notes or PR descriptions.
+---
+
+# uinotes-changelog
+
+Generate a changelog from notes resolved since a git ref or date.
+
+## When to use
+- After resolving notes, to generate a summary for PR descriptions
+- For release notes listing UI fixes
+- To audit what was fixed in a time period
+
+## Command
+```bash
+uinotes changelog --since HEAD~5
+uinotes changelog --since v1.2.0 --format conventional
+uinotes changelog --since 2026-02-01 --format json
+```
+
+Formats: `markdown` (default), `conventional` (conventional commits), `json`.

package/skills/uinotes-comment.md

@@ -0,0 +1,19 @@
+---
+name: uinotes-comment
+description: Add a comment to a UI note. Use to document progress, ask questions, or provide status updates on notes.
+---
+
+# uinotes-comment
+
+Add comments to notes to document progress or communicate.
+
+## When to use
+- To document what was tried or what's blocking a fix
+- To ask clarifying questions about a note
+- To provide a status update before resolving
+
+## Command
+```bash
+uinotes comment <note-id> "Comment text here"
+uinotes comments <note-id>  # List existing comments
+```

package/skills/uinotes-context.md

@@ -0,0 +1,22 @@
+---
+name: uinotes-context
+description: Fetch AI-optimized context of open UI notes for the current project. Use when asked to check for UI bugs, feedback, or notes.
+---
+
+# uinotes-context
+
+Run `uinotes context` to get a structured digest of all open UI notes.
+
+## When to use
+- At the start of a task to understand what UI issues exist
+- Before making UI changes to check for related notes
+- When the user asks about UI bugs, feedback, or design issues
+
+## Command
+```bash
+uinotes context --format markdown
+```
+
+Add `--resolve-files --root-dir .` to map notes to source files.
+Add `--type bug` to filter by type (bug, ux, feature, question).
+Add `--project <slug>` to target a specific project.

package/skills/uinotes-explain.md

@@ -0,0 +1,21 @@
+---
+name: uinotes-explain
+description: Get full context for a single note including comments, history, and visual diffs. Use when investigating a specific note.
+---
+
+# uinotes-explain
+
+Get fully-hydrated context for a single note in one call.
+
+## When to use
+- When investigating a specific note before fixing it
+- When you need comments, history, or visual diff context
+- When triaging a single note
+
+## Command
+```bash
+uinotes explain <note-id>
+uinotes explain <note-id> --format json
+```
+
+Returns: note body, type, status, component, selector, URL, screenshot URL, all comments, status history, and visual diffs.

package/skills/uinotes-resolve.md

@@ -0,0 +1,26 @@
+---
+name: uinotes-resolve
+description: Mark a UI note as resolved after fixing it. Use after completing a fix for a UI issue.
+---
+
+# uinotes-resolve
+
+Mark notes as resolved after fixing the issue they describe.
+
+## When to use
+- After fixing a bug, UX issue, or implementing a feature request described in a note
+- After verifying a fix addresses the feedback
+
+## Commands
+```bash
+# Resolve with a message explaining the fix
+uinotes resolve <note-id> "Fixed by updating the component"
+
+# Mark as won't fix with explanation
+uinotes wontfix <note-id> "Working as intended"
+
+# Bulk resolve all notes for a component
+uinotes resolve-by-component <ComponentName> --message "Refactored component"
+```
+
+Always include a resolution message describing what was done.