optimal-cli 1.0.0 → 1.1.0

package/scripts/migrate-v2.ts

@@ -0,0 +1,78 @@
+import { createClient } from '@supabase/supabase-js'
+
+const url = 'https://hbfalrpswysryltysonm.supabase.co'
+const key = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImhiZmFscnBzd3lzcnlsdHlzb25tIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImlhdCI6MTc0MjIzMTEyMiwiZXhwIjoyMDU3ODA3MTIyfQ.oyzf_We-WCOsJ8xYs2_Q9wi8QSBr_1Ym_F_75o67kR0'
+
+const supabase = createClient(url, key)
+
+async function runMigration() {
+  console.log('🔧 Running migration: agent_configs table')
+  console.log(`   URL: ${url}`)
+  console.log('')
+
+  // Test connection first
+  const { data: testData, error: testError } = await supabase
+    .from('agent_configs')
+    .select('count')
+    .limit(1)
+
+  if (testError?.code === '42P01') {
+    console.log('   Table does not exist. Creating...')
+  } else if (testError) {
+    console.log('   Error checking table:', testError.message)
+  } else {
+    console.log('   ✓ Table already exists')
+    return
+  }
+
+  // Create table using raw SQL
+  const sql = `
+    CREATE TABLE IF NOT EXISTS agent_configs (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      agent_name TEXT NOT NULL UNIQUE,
+      config_json JSONB NOT NULL DEFAULT '{}',
+      version TEXT NOT NULL DEFAULT '0.0.0',
+      created_at TIMESTAMPTZ DEFAULT NOW(),
+      updated_at TIMESTAMPTZ DEFAULT NOW()
+    );
+  `
+
+  // Try using the SQL API directly
+  const response = await fetch(`${url}/rest/v1/`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${key}`,
+      'apikey': key,
+      'Prefer': 'tx=rollback'
+    },
+    body: JSON.stringify({ query: sql })
+  })
+
+  console.log('   Response status:', response.status)
+  
+  if (response.status === 404 || response.status === 400) {
+    console.log('')
+    console.log('⚠️  Cannot run migration via REST API.')
+    console.log('')
+    console.log('Please run this SQL in Supabase SQL Editor:')
+    console.log('')
+    console.log('━'.repeat(60))
+    console.log(sql)
+    console.log('━'.repeat(60))
+    console.log('')
+    console.log('Then run:')
+    console.log('  CREATE INDEX idx_agent_configs_name ON agent_configs(agent_name);')
+    console.log('  ALTER TABLE agent_configs ENABLE ROW LEVEL SECURITY;')
+    console.log('  CREATE POLICY "Service role full access" ON agent_configs FOR ALL TO service_role USING (true) WITH CHECK (true);')
+    process.exit(1)
+  }
+
+  const text = await response.text()
+  console.log('   Response:', text.slice(0, 200))
+}
+
+runMigration().catch(err => {
+  console.error('❌ Migration failed:', err)
+  process.exit(1)
+})

package/scripts/migrate.ts

@@ -0,0 +1,79 @@
+import { createClient } from '@supabase/supabase-js'
+
+const url = 'https://hbfalrpswysryltysonm.supabase.co'
+const key = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImhiZmFscnBzd3lzcnlsdHlzb25tIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImlhdCI6MTc0MjIzMTEyMiwiZXhwIjoyMDU3ODA3MTIyfQ.oyzf_We-WCOsJ8xYs2_Q9wi8QSBr_1Ym_F_75o67kR0'
+
+const supabase = createClient(url, key)
+
+async function createTable() {
+  console.log('🔧 Creating agent_configs table...')
+
+  // Create table using raw SQL via RPC or direct query
+  const createTableSQL = `
+    CREATE TABLE IF NOT EXISTS agent_configs (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      agent_name TEXT NOT NULL UNIQUE,
+      config_json JSONB NOT NULL DEFAULT '{}',
+      version TEXT NOT NULL DEFAULT '0.0.0',
+      created_at TIMESTAMPTZ DEFAULT NOW(),
+      updated_at TIMESTAMPTZ DEFAULT NOW()
+    );
+  `
+
+  // Try to create the table by inserting and letting it fail if exists
+  const { error: insertError } = await supabase
+    .from('agent_configs')
+    .insert({
+      agent_name: '__test__',
+      config_json: {},
+      version: '0.0.0'
+    })
+
+  if (insertError?.code === '42P01') {
+    console.log('   Table does not exist. Creating via SQL...')
+    
+    // Use the SQL API
+    const response = await fetch(`${url}/rest/v1/rpc/exec_sql`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${key}`,
+        'apikey': key
+      },
+      body: JSON.stringify({ sql: createTableSQL })
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      console.log('   RPC failed, trying alternative...')
+      console.log('   Error:', text.slice(0, 200))
+      
+      // Alternative: create via pg_graphql or direct postgrest
+      console.log('   Please run this SQL in Supabase SQL Editor:')
+      console.log('')
+      console.log(createTableSQL)
+      console.log('')
+      console.log('   Then run:')
+      console.log('   CREATE INDEX idx_agent_configs_name ON agent_configs(agent_name);')
+      console.log('   ALTER TABLE agent_configs ENABLE ROW LEVEL SECURITY;')
+      process.exit(1)
+    }
+    
+    console.log('   ✓ Table created')
+  } else if (insertError?.code === '23505') {
+    console.log('   ✓ Table already exists (unique constraint violation on test insert)')
+    // Clean up test row
+    await supabase.from('agent_configs').delete().eq('agent_name', '__test__')
+  } else if (insertError) {
+    console.log('   Error:', insertError.message)
+  } else {
+    console.log('   ✓ Table exists and is writable')
+    // Clean up test row
+    await supabase.from('agent_configs').delete().eq('agent_name', '__test__')
+  }
+
+  console.log('')
+  console.log('✅ Migration complete!')
+}
+
+createTable().catch(console.error)

package/scripts/run-migration.ts

@@ -0,0 +1,59 @@
+import { createClient } from '@supabase/supabase-js'
+
+const url = process.env.OPTIMAL_SUPABASE_URL!
+const key = process.env.OPTIMAL_SUPABASE_SERVICE_KEY!
+
+const supabase = createClient(url, key)
+
+// Create the table via SQL query
+const sql = `
+create table if not exists public.cli_config_registry (
+  id uuid primary key default gen_random_uuid(),
+  owner text not null,
+  profile text not null default 'default',
+  config_version text not null,
+  payload jsonb not null,
+  payload_hash text not null,
+  source text not null default 'optimal-cli',
+  updated_by text,
+  updated_at timestamptz not null default now(),
+  created_at timestamptz not null default now(),
+  unique (owner, profile)
+);
+
+create index if not exists idx_cli_config_registry_owner_profile
+  on public.cli_config_registry (owner, profile);
+
+create index if not exists idx_cli_config_registry_updated_at
+  on public.cli_config_registry (updated_at desc);
+`
+
+const { data, error } = await supabase.rpc('pg_execute', { sql_text: sql })
+
+if (error) {
+  console.error('Migration failed:', error)
+  // Try alternative approach
+  console.log('Attempting alternative table creation...')
+  
+  // Just verify table exists by querying
+  const { data: test, error: testErr } = await supabase
+    .from('cli_config_registry')
+    .select('count')
+    .limit(1)
+  
+  if (testErr && testErr.code !== '42P01') {
+    console.error('Table verification failed:', testErr)
+    process.exit(1)
+  }
+  
+  if (testErr?.code === '42P01') {
+    console.error('Table cli_config_registry does not exist and could not be created.')
+    console.error('Please run this SQL manually in Supabase SQL Editor:')
+    console.log(sql)
+    process.exit(1)
+  }
+  
+  console.log('Table exists!')
+} else {
+  console.log('Migration applied successfully')
+}

package/scripts/seed-board.ts

@@ -0,0 +1,203 @@
+#!/usr/bin/env tsx
+/**
+ * Seed the kanban board with the full implementation backlog.
+ * Idempotent — checks existing tasks by title before creating.
+ *
+ * Usage: npx tsx scripts/seed-board.ts
+ */
+import 'dotenv/config'
+import { createTask, getBoard } from '../lib/kanban.js'
+
+const PROJECT_SLUG = 'optimal-cli-refactor'
+
+interface SeedTask {
+  title: string
+  skill_ref?: string
+  priority: 1 | 2 | 3 | 4
+  labels: string[]
+  description?: string
+}
+
+const tasks: SeedTask[] = [
+  // --- Phase 2 follow-ups (ready — no blockers) ---
+  {
+    title: 'Implement upload-r1 lib function',
+    skill_ref: '/upload-r1',
+    priority: 2,
+    labels: ['returnpro', 'phase-2'],
+    description: 'Extract R1 marketplace data upload from dashboard-returnpro into lib/returnpro/upload-r1.ts',
+  },
+  {
+    title: 'Implement upload-netsuite lib function',
+    skill_ref: '/upload-netsuite',
+    priority: 2,
+    labels: ['returnpro', 'phase-2'],
+    description: 'Extract NetSuite XLSM upload pipeline into lib/returnpro/upload-netsuite.ts',
+  },
+  {
+    title: 'Implement upload-income-statements lib function',
+    skill_ref: '/upload-income-statements',
+    priority: 2,
+    labels: ['returnpro', 'phase-2'],
+    description: 'Extract confirmed income statement CSV upload into lib/returnpro/upload-income-statements.ts',
+  },
+  {
+    title: 'Implement rate-anomalies lib function',
+    skill_ref: '/rate-anomalies',
+    priority: 3,
+    labels: ['returnpro', 'phase-2'],
+    description: 'Extract rate anomaly detection logic from dashboard-returnpro into lib/returnpro/rate-anomalies.ts',
+  },
+  {
+    title: 'Implement diagnose-months lib function',
+    skill_ref: '/diagnose-months',
+    priority: 3,
+    labels: ['returnpro', 'phase-2'],
+    description: 'Extract month-level diagnostic comparison into lib/returnpro/diagnose-months.ts',
+  },
+  {
+    title: 'Implement generate-netsuite-template lib function',
+    skill_ref: '/generate-netsuite-template',
+    priority: 3,
+    labels: ['returnpro', 'phase-2'],
+    description: 'Generate blank NetSuite XLSM templates for data entry into lib/returnpro/generate-netsuite-template.ts',
+  },
+
+  // --- Content follow-ups (ready) ---
+  {
+    title: 'Implement generate-newsletter-insurance',
+    skill_ref: '/generate-newsletter-insurance',
+    priority: 2,
+    labels: ['content', 'phase-3'],
+    description: 'Insurance-specific newsletter generation (LIFEINSUR brand) with Groq AI content',
+  },
+  {
+    title: 'Implement distribute-newsletter (n8n webhook)',
+    skill_ref: '/distribute-newsletter',
+    priority: 2,
+    labels: ['content', 'phase-3'],
+    description: 'Trigger n8n webhook to distribute published newsletter via GoHighLevel email',
+  },
+  {
+    title: 'Implement generate-social-posts pipeline',
+    skill_ref: '/generate-social-posts',
+    priority: 2,
+    labels: ['content', 'phase-3'],
+    description: 'Full pipeline: scrape competitors, analyze patterns, generate 9 social posts, push to Strapi',
+  },
+  {
+    title: 'Implement publish-social-posts',
+    skill_ref: '/publish-social-posts',
+    priority: 3,
+    labels: ['content', 'phase-3'],
+    description: 'Publish scheduled social posts to Meta (IG/FB) via Marketing API',
+  },
+  {
+    title: 'Implement publish-blog',
+    skill_ref: '/publish-blog',
+    priority: 3,
+    labels: ['content', 'phase-3'],
+    description: 'Publish blog post to Strapi CMS and deploy preview site via Vercel',
+  },
+
+  // --- Infrastructure follow-ups (ready) ---
+  {
+    title: 'Implement migrate-db skill',
+    skill_ref: '/migrate-db',
+    priority: 3,
+    labels: ['infra', 'phase-3'],
+    description: 'Run Supabase migrations via CLI (supabase db push --linked) with pre-flight checks',
+  },
+  {
+    title: 'Implement manage-scenarios for budget',
+    skill_ref: '/manage-scenarios',
+    priority: 3,
+    labels: ['budget', 'phase-3'],
+    description: 'CRUD for budget projection scenarios (save/load/compare named adjustment sets)',
+  },
+  {
+    title: 'Implement delete-batch for transactions',
+    skill_ref: '/delete-batch',
+    priority: 3,
+    labels: ['transactions', 'phase-3'],
+    description: 'Bulk delete transactions by date range or import batch ID with confirmation safeguard',
+  },
+
+  // --- Frontend migration (backlog — future phase) ---
+  {
+    title: 'Migrate dashboard-returnpro to apps/ as read-only',
+    priority: 4,
+    labels: ['frontend', 'phase-4'],
+    description: 'Move dashboard-returnpro Next.js app into apps/dashboard-returnpro as a read-only frontend consuming CLI skills',
+  },
+  {
+    title: 'Migrate optimalos to apps/ as read-only',
+    priority: 4,
+    labels: ['frontend', 'phase-4'],
+    description: 'Move optimalos Next.js app into apps/optimalos as a read-only frontend consuming CLI skills',
+  },
+  {
+    title: 'Migrate portfolio-2026 to apps/ as read-only',
+    priority: 4,
+    labels: ['frontend', 'phase-4'],
+    description: 'Move portfolio-2026 Next.js app into apps/portfolio-2026 as a read-only frontend consuming CLI skills',
+  },
+  {
+    title: 'Migrate wes-dashboard to apps/ as read-only',
+    priority: 4,
+    labels: ['frontend', 'phase-4'],
+    description: 'Move wes-dashboard Next.js app into apps/wes-dashboard as a read-only frontend consuming CLI skills',
+  },
+  {
+    title: 'Migrate newsletter-preview to apps/ as read-only',
+    priority: 4,
+    labels: ['frontend', 'phase-4'],
+    description: 'Move newsletter-preview Next.js app into apps/newsletter-preview as a read-only frontend consuming CLI skills',
+  },
+]
+
+async function main() {
+  console.log(`Seeding kanban board for project: ${PROJECT_SLUG}`)
+  console.log(`Tasks to seed: ${tasks.length}\n`)
+
+  // Fetch existing tasks for idempotency check
+  const existing = await getBoard(PROJECT_SLUG)
+  const existingTitles = new Set(existing.map(t => t.title))
+
+  console.log(`Existing tasks on board: ${existing.length}`)
+
+  let created = 0
+  let skipped = 0
+
+  for (const task of tasks) {
+    if (existingTitles.has(task.title)) {
+      console.log(`  SKIP: "${task.title}" (already exists)`)
+      skipped++
+      continue
+    }
+
+    try {
+      const result = await createTask({
+        project_slug: PROJECT_SLUG,
+        title: task.title,
+        description: task.description,
+        priority: task.priority,
+        skill_ref: task.skill_ref,
+        labels: task.labels,
+      })
+      console.log(`  CREATE: "${result.title}" [P${result.priority}] (${result.id})`)
+      created++
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      console.error(`  ERROR: "${task.title}" — ${msg}`)
+    }
+  }
+
+  console.log(`\nDone. Created: ${created}, Skipped: ${skipped}`)
+  console.log(`Total tasks on board: ${existing.length + created}`)
+}
+
+main().catch((err) => {
+  console.error('Seed failed:', err)
+  process.exit(1)
+})

package/scripts/test-kanban.ts

@@ -0,0 +1,21 @@
+import { getBoardByStatus, listProjects } from '../lib/kanban.js'
+
+async function main() {
+  console.log('Testing kanban lib...')
+  
+  const projects = await listProjects()
+  console.log('Projects:', projects.map(p => p.slug).join(', '))
+
+  const board = await getBoardByStatus('optimal-cli')
+  console.log('Board:')
+  for (const [status, tasks] of Object.entries(board)) {
+    if (tasks.length > 0) {
+      console.log(`  ${status}: ${tasks.length}`)
+      for (const t of tasks) {
+        console.log(`    - ${t.title} (claimed: ${t.claimed_by || 'none'})`)
+      }
+    }
+  }
+}
+
+main().catch(console.error)

package/skills/audit-financials/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: audit-financials
+description: Compare staged financials against confirmed income statements and report accuracy per month
+---
+
+## Purpose
+Verifies data accuracy between `stg_financials_raw` (staged from NetSuite XLSM/CSV) and `confirmed_income_statements` (from NetSuite income statement CSVs). This is the most critical financial health check — every data session should start by running this.
+
+## Inputs
+- **months** (optional): Comma-separated YYYY-MM strings to filter (e.g., `2026-01,2025-12`). Omit for all months.
+- **tolerance** (optional): Dollar tolerance for match detection. Default `1.00`.
+
+## Steps
+1. Call `lib/returnpro/audit.ts::runAuditComparison(months?, tolerance?)` to fetch and compare data
+2. Paginate all `stg_financials_raw` rows (amount is TEXT — parseFloat)
+3. Paginate all `confirmed_income_statements` rows
+4. Aggregate staging by `account_code|YYYY-MM` key
+5. Compare each overlapping account: exact match, sign-flip match, or mismatch (within tolerance)
+6. Compute accuracy = (exactMatch + signFlipMatch) / overlap * 100
+
+## Output
+Per-month table:
+
+| Month | Confirmed | Staged | Match | Mismatch | Accuracy |
+|-------|-----------|--------|-------|----------|----------|
+| 2026-01 | 189 | 91 | 83 | 8 | 91.2% |
+
+Plus total staging rows and confirmed rows counts.
+
+Flag any month below 100% accuracy — investigate mismatches and identify root causes.
+
+## Environment
+Requires: `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`

package/skills/board-create/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: board-create
+description: Create a new task on the kanban board
+---
+
+## Purpose
+Adds a new task to the project board. Agents use this to break work into trackable subtasks.
+
+## Inputs
+- **project** (optional): Project slug. Default: `optimal-cli-refactor`
+- **title** (required): Task title
+- **description** (optional): Detailed task description
+- **priority** (optional): 1=urgent, 2=high, 3=normal, 4=low. Default: 3
+- **skill** (optional): Skill that should handle this task (e.g. `/audit-financials`)
+- **labels** (optional): Comma-separated labels
+- **blocked_by** (optional): Comma-separated task IDs that must complete first
+
+## Steps
+1. Call `lib/kanban.ts::createTask(input)` with provided params
+2. Return the created task ID and title
+
+## Output
+```
+Created task: {id} — "{title}" (priority {priority}, status backlog)
+```
+
+## Environment
+Requires: `OPTIMAL_SUPABASE_URL`, `OPTIMAL_SUPABASE_SERVICE_KEY`

package/skills/board-update/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: board-update
+description: Update a task's status, assignment, or metadata on the kanban board
+---
+
+## Purpose
+Moves tasks through the kanban lifecycle. Agents call this to claim work, mark completion, or flag blockers.
+
+## Inputs
+- **task_id** (required): UUID of the task to update
+- **status** (optional): New status (backlog, ready, in_progress, blocked, review, done, canceled)
+- **agent** (optional): Agent name to assign (e.g. `claude-code`, `carlos`)
+- **priority** (optional): New priority (1-4)
+- **message** (optional): Log message describing the update
+
+## Steps
+1. Call `lib/kanban.ts::updateTask(taskId, updates)`
+2. Call `lib/kanban.ts::logActivity(taskId, { agent, action: 'status_change', message })`
+3. Return updated task summary
+
+## Output
+```
+Updated task {id}: status → {status}, agent → {agent}
+```
+
+## Environment
+Requires: `OPTIMAL_SUPABASE_URL`, `OPTIMAL_SUPABASE_SERVICE_KEY`

package/skills/board-view/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: board-view
+description: Display the current kanban board as a markdown table
+---
+
+## Purpose
+Shows all tasks for a project grouped by status column. Use this to check what work is queued, in progress, or completed.
+
+## Inputs
+- **project** (optional): Project slug. Default: `optimal-cli-refactor`
+- **status** (optional): Filter to a single status column (backlog, ready, in_progress, blocked, review, done)
+
+## Steps
+1. Call `lib/kanban.ts::getBoard(projectSlug)` to fetch all tasks
+2. Group tasks by status
+3. Format as a markdown table with columns: Status | Priority | Title | Agent | Skill
+
+## Output
+Markdown table grouped by status:
+
+| Status | P | Title | Agent | Skill |
+|--------|---|-------|-------|-------|
+| in_progress | 1 | Upload R1 data | claude-code | /upload-r1 |
+| backlog | 2 | Extract KPI skills | — | — |
+
+## Environment
+Requires: `OPTIMAL_SUPABASE_URL`, `OPTIMAL_SUPABASE_SERVICE_KEY`

package/skills/delete-batch/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: delete-batch
+description: Bulk delete transactions by filter from the OptimalOS transactions table
+---
+
+## Purpose
+Performs bulk deletion of transactions from OptimalOS's `transactions` table based on filter criteria. Used to clean up bad imports, remove duplicate batches, or clear test data. Requires explicit confirmation due to the destructive nature of the operation. Always creates an audit log entry before deleting.
+
+## Inputs
+- **batch-id** (optional): Delete all transactions belonging to a specific `upload_batches.id`. This is the safest and most common deletion method.
+- **user-id** (optional): Filter by owner UUID. Required if not using `--batch-id`.
+- **date-range** (optional): Delete transactions within a date range as `YYYY-MM-DD:YYYY-MM-DD` (inclusive).
+- **bank** (optional): Filter by bank/source format (`chase_checking`, `chase_credit`, `discover`, `generic`).
+- **confirm** (optional): Skip the interactive confirmation prompt. Default: false (requires confirmation).
+- **dry-run** (optional): Show what would be deleted without actually deleting. Default: false.
+
+## Steps
+1. Call `lib/transactions/ingest.ts::deleteBatch(options)` to orchestrate the deletion
+2. **Build filter** — construct WHERE clause from provided filters (batch-id, user-id, date-range, bank)
+3. **Count affected rows** — `SELECT COUNT(*) FROM transactions WHERE <filters>` to show impact
+4. **Dry-run check** — if `--dry-run`, display count and sample rows, then exit
+5. **Confirm** — unless `--confirm` is set, display count and ask for explicit confirmation
+6. **Audit log** — insert a record into `cli_task_logs` with deletion details (filter, count, timestamp)
+7. **Delete** — `DELETE FROM transactions WHERE <filters>` in batches of 100
+8. **Clean up batches** — if `--batch-id` used, update `upload_batches.status` to `deleted`
+9. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Filter: batch_id = 42
+Affected rows: 231 transactions
+Date range: 2025-11-01 to 2025-11-30
+Bank: chase_credit
+
+Deleted: 231 transactions
+Batch 42 marked as deleted.
+Audit log entry: cli_task_logs.id = 789
+```
+
+Dry-run mode:
+```
+[DRY RUN] Would delete 231 transactions matching:
+  batch_id = 42, bank = chase_credit
+  Sample: 2025-11-01 "AMAZON.COM" -$47.99, 2025-11-02 "WHOLE FOODS" -$82.31, ...
+```
+
+## CLI Usage
+```bash
+# Delete by batch ID (safest)
+optimal delete-batch --batch-id 42
+
+# Delete by user and date range
+optimal delete-batch --user-id <uuid> --date-range 2025-11-01:2025-11-30
+
+# Dry run to preview
+optimal delete-batch --batch-id 42 --dry-run
+
+# Skip confirmation prompt
+optimal delete-batch --batch-id 42 --confirm
+```
+
+## Environment
+Requires: `OPTIMAL_SUPABASE_URL`, `OPTIMAL_SUPABASE_SERVICE_KEY`
+
+## Tables Touched
+- `transactions` — DELETE matching rows
+- `upload_batches` — update status to `deleted` (if batch-id used)
+- `cli_task_logs` — audit trail entry
+
+## Gotchas
+- **Destructive operation**: Always runs a count + dry-run preview before actual deletion unless `--confirm` is explicitly passed.
+- **No undo**: Deleted transactions cannot be recovered. Re-import the original CSV if needed.
+- **Batch deletion is preferred**: Using `--batch-id` is the safest method because it deletes exactly what was imported in one operation, with clean provenance tracking.
+- **Categories are preserved**: Deleting transactions does not cascade to `categories`.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function to be added to `lib/transactions/ingest.ts` alongside existing ingestion logic.

package/skills/deploy/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: deploy
+description: Deploy an app to Vercel (preview or production)
+---
+
+## Purpose
+Deploy one of the Optimal project apps to Vercel. Supports both preview deployments (default) and production deployments (with `--prod`).
+
+## Inputs
+- **app** (required): App name to deploy. One of: `dashboard-returnpro`, `optimalos`, `portfolio`, `newsletter-preview`, `wes`.
+- **prod** (optional): Pass `--prod` flag to deploy to production instead of preview.
+
+## Steps
+1. Resolve the app name to its absolute filesystem path via `lib/infra/deploy.ts::getAppPath()`
+2. Call `vercel --cwd <path>` (or `vercel --prod --cwd <path>` for production)
+3. Wait up to 2 minutes for the deployment to complete
+4. Return the deployment URL
+
+## Output
+The Vercel deployment URL (e.g., `https://portfolio-2026-abc123.vercel.app` for preview, or the production URL for `--prod`).
+
+## Available Apps
+
+| Name | Path |
+|------|------|
+| dashboard-returnpro | /home/optimal/dashboard-returnpro |
+| optimalos | /home/optimal/optimalos |
+| portfolio | /home/optimal/portfolio-2026 |
+| newsletter-preview | /home/optimal/projects/newsletter-preview |
+| wes | /home/optimal/wes-dashboard |
+
+## Usage
+```bash
+optimal deploy portfolio          # preview deployment
+optimal deploy portfolio --prod   # production deployment
+optimal deploy dashboard-returnpro --prod
+```
+
+## Environment
+Requires: `vercel` CLI installed globally and authenticated.