optimal-cli 1.0.1 → 1.1.0

package/skills/stamp-transactions/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: stamp-transactions
+description: Auto-categorize unclassified transactions using a 4-stage rule-based matching engine
+---
+
+## Purpose
+Queries all unclassified transactions (where `provider IS NULL` or `category_id IS NULL`) for a given user and runs them through a 4-stage matching algorithm to assign provider names and categories. Optionally runs in dry-run mode to preview results without writing.
+
+## Inputs
+- **user-id** (required): Supabase user UUID whose transactions to stamp
+- **dry-run** (optional): Preview matches without updating the database
+
+## Matching Algorithm (4 stages)
+| Stage | Name | Confidence | Method |
+|-------|------|------------|--------|
+| 1 | PATTERN | 100% | Regex patterns for transfers, Zelle, P2P, CC payments, payroll, ATM, fees |
+| 2 | LEARNED | 80-99% | Description hash lookup in `learned_patterns` (weight determines confidence) |
+| 3 | EXACT | 100% | Provider name (or variant) found as substring in description |
+| 4 | FUZZY | 60-95% | Token overlap between description and provider names (threshold 0.6) |
+| Fallback | CATEGORY_INFER | 50% | Map institution-specific category to standard category |
+
+Transactions matching at >= 90% confidence are auto-confirmed. Below that, they remain `pending` for user review.
+
+## Steps
+1. Load matching rules from DB: `providers`, `learned_patterns`, `user_provider_overrides`
+2. Fetch unclassified transactions for the user
+3. Fetch `stamp_categories` and user `categories` for name-to-ID mapping
+4. Run each transaction through the 4-stage pipeline
+5. Update matched rows with `provider`, `provider_method`, `provider_confidence`, `category_id`
+
+## Output
+```
+Matcher loaded: 342 providers, 89 learned patterns
+Found 156 unclassified transactions
+
+Stamped: 127  |  Unmatched: 29  |  Total: 156
+By match type: PATTERN=18, LEARNED=34, EXACT=52, FUZZY=19, CATEGORY_INFER=4
+```
+
+In dry-run mode, no database writes occur — the output shows what would happen.
+
+## CLI Usage
+```bash
+# Full stamp run
+tsx bin/optimal.ts stamp-transactions --user-id <uuid>
+
+# Preview only
+tsx bin/optimal.ts stamp-transactions --user-id <uuid> --dry-run
+```
+
+## Environment
+Requires: `OPTIMAL_SUPABASE_URL`, `OPTIMAL_SUPABASE_SERVICE_KEY`
+
+## Tables Read
+- `providers` — global provider-to-category mappings + aliases
+- `learned_patterns` — user-confirmed description patterns
+- `user_provider_overrides` — per-user category overrides
+- `stamp_categories` — standard category definitions
+- `categories` — user-specific categories
+
+## Tables Written
+- `transactions` — update `provider`, `provider_method`, `provider_confidence`, `provider_inferred_at`, `category_id`

package/skills/upload-income-statements/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: upload-income-statements
+description: Load confirmed income statement CSVs into ReturnPro for accuracy auditing
+---
+
+## Purpose
+Uploads confirmed income statement CSVs (exported from NetSuite) into `confirmed_income_statements`. These serve as the source of truth for financial accuracy auditing — the audit-financials skill compares staged data against these confirmed records. Maintaining accurate confirmed data is essential because ReturnPro targets 100% accuracy between staged and confirmed financials.
+
+## Inputs
+- **file** (required): Absolute path to the income statement CSV file on disk
+- **month** (required): Target month as YYYY-MM (e.g., `2026-01`)
+- **replace** (optional): If set, deletes existing confirmed rows for the target month before inserting. Default: false (append/upsert).
+
+## Steps
+1. Call `lib/returnpro/upload-income.ts::uploadIncomeStatements(file, month, options?)` to orchestrate the upload
+2. Read the CSV file and parse rows (account_code, account_name, total_amount, period)
+3. Validate account codes against `dim_account`
+4. If `--replace` flag is set, delete existing `confirmed_income_statements` rows for the target month
+5. Batch-insert rows into `confirmed_income_statements`
+6. Run a quick accuracy check against `stg_financials_raw` for the uploaded month (same logic as audit-financials)
+7. Report accuracy inline so Carlos immediately knows the data state
+8. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Parsed income statement CSV: 189 accounts for 2026-01
+Inserted: 189  |  Replaced: 0
+Quick accuracy check (2026-01): 91.2% (83/91 staged accounts match)
+```
+
+## CLI Usage
+```bash
+# Upload income statement
+optimal upload-income-statements --file ~/Downloads/returnpro-data/IS-Jan-2026.csv --month 2026-01
+
+# Replace existing month data
+optimal upload-income-statements --file ~/Downloads/returnpro-data/IS-Jan-2026.csv --month 2026-01 --replace
+```
+
+## Environment
+Requires: `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`
+
+## Tables Touched
+- `confirmed_income_statements` — insert/replace confirmed GL account rows
+- `stg_financials_raw` — read-only for post-upload accuracy check
+- `dim_account` — validate account codes
+
+## Gotchas
+- **Coverage gap**: Confirmed data has ~185-193 accounts/month vs staging's ~88-93. The delta is GL accounts not in Solution7 (expected, but tracked).
+- **Always run audit after upload**: The skill automatically runs a quick accuracy check, but a full audit-financials run is recommended for detailed investigation.
+- **Upload via Admin Console**: Can also be done via the ReturnPro Admin Console UI (Income Statement tab).
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/returnpro/upload-income.ts` to be extracted from dashboard-returnpro's `/api/admin/confirmed-income-statements` route.

package/skills/upload-netsuite/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: upload-netsuite
+description: Upload NetSuite XLSM or CSV financial data into ReturnPro staging tables
+---
+
+## Purpose
+Uploads NetSuite financial exports (XLSM macro-enabled workbooks or CSV files) into `stg_financials_raw`. This is the primary data pipeline for ReturnPro FP&A staging. Handles both single-sheet CSV files and multi-sheet XLSM workbooks (auto-detects format). Supports Wes-style multi-sheet workbooks where each month tab contains that month's data.
+
+## Inputs
+- **file** (required): Absolute path to the NetSuite XLSM or CSV file on disk
+- **month** (optional): Target month as YYYY-MM. Required for CSV files. For XLSM with monthly tabs, auto-detected from sheet names.
+- **dry-run** (optional): Parse and validate without writing to Supabase.
+
+## Steps
+1. Call `lib/returnpro/upload-netsuite.ts::uploadNetsuite(file, month?, options?)` to orchestrate the upload
+2. Detect file format by extension (.xlsm, .xlsx, .csv)
+3. For XLSM/XLSX: check for multi-sheet layout using `hasMonthlySheets()` — if 3+ month-named sheets exist, read per-month tabs (NOT Summary)
+4. For CSV: read single file, require `--month` parameter
+5. Parse rows into staging format: `account_code`, `account_name`, `amount` (as TEXT), `period` (YYYY-MM), `source_file`
+6. Resolve account codes against `dim_account` for validation
+7. Batch-upsert into `stg_financials_raw` (keyed on account_code + period + master_program_id)
+8. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Format: NetSuite XLSM (multi-sheet: Jan, Feb, Mar)
+Parsed 3 months: 2026-01 (91 rows), 2026-02 (89 rows), 2026-03 (93 rows)
+Total inserted: 273  |  Updated: 0  |  Skipped: 0
+```
+
+## CLI Usage
+```bash
+# XLSM with auto-detected monthly tabs
+optimal upload-netsuite --file ~/Downloads/returnpro-data/Solution7-Q1-2026.xlsm
+
+# CSV with explicit month
+optimal upload-netsuite --file ~/Downloads/returnpro-data/netsuite-jan-2026.csv --month 2026-01
+
+# Dry run to preview
+optimal upload-netsuite --file ~/Downloads/returnpro-data/Solution7-Q1-2026.xlsm --dry-run
+```
+
+## Environment
+Requires: `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`
+
+## Tables Touched
+- `stg_financials_raw` — upsert parsed rows (amount stored as TEXT)
+- `dim_account` — validate account codes
+
+## Gotchas
+- **amount is TEXT**: The `stg_financials_raw.amount` column is TEXT, not NUMERIC. Always CAST before numeric comparisons.
+- **Multi-sheet detection**: `hasMonthlySheets()` triggers when 3+ sheets have month-like names. If present, reads individual month tabs and ignores Summary sheet.
+- **Never run SQL manually**: Use migration files + `supabase db push --linked` for schema changes.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/returnpro/upload-netsuite.ts` to be extracted from dashboard-returnpro's `/api/staging/upload` route.

package/skills/upload-r1/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: upload-r1
+description: Upload R1 XLSX files parsed with WASM/calamine, aggregate by program, and load into ReturnPro staging
+---
+
+## Purpose
+Uploads R1 reverse-logistics XLSX files into ReturnPro's financial staging tables. The R1 export is parsed using WASM-based calamine (fast XLSX parser without ExcelJS overhead), rows are aggregated by master program, and results are upserted into `stg_financials_raw`. This is one of the primary data ingestion paths for ReturnPro FP&A.
+
+## Inputs
+- **file** (required): Absolute path to the R1 XLSX file on disk
+- **month** (required): Target month as YYYY-MM (e.g., `2026-01`). Used for the staging period column.
+- **dry-run** (optional): Parse and aggregate without writing to Supabase. Useful for previewing row counts.
+
+## Steps
+1. Call `lib/returnpro/upload-r1.ts::uploadR1(file, month, options?)` to orchestrate the upload
+2. Read the XLSX file with WASM/calamine parser (faster than ExcelJS for large files)
+3. Normalize column headers — map R1-specific column names to standard staging fields (account_code, amount, description)
+4. Aggregate rows by `master_program_id` + `account_code` within the target month
+5. Resolve program names to `dim_master_program.id` via fuzzy match
+6. Upsert aggregated rows into `stg_financials_raw` (keyed on account_code + month + master_program_id)
+7. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Parsed R1 XLSX: 1,842 rows across 47 programs
+Aggregated to 312 staging rows for 2026-01
+Inserted: 298  |  Updated: 14  |  Skipped: 0
+```
+
+## CLI Usage
+```bash
+optimal upload-r1 --file ~/Downloads/returnpro-data/R1-January-2026.xlsx --month 2026-01
+optimal upload-r1 --file ~/Downloads/returnpro-data/R1-January-2026.xlsx --month 2026-01 --dry-run
+```
+
+## Environment
+Requires: `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`
+
+## Tables Touched
+- `stg_financials_raw` — upsert aggregated rows (note: `amount` column is TEXT, not NUMERIC)
+- `dim_master_program` — lookup for program name resolution
+- `dim_account` — lookup for account code validation
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/returnpro/upload-r1.ts` to be extracted from dashboard-returnpro's `/api/r1/` routes.

package/supabase/.temp/cli-latest

@@ -0,0 +1 @@
+v2.75.0

package/supabase/migrations/20250305000001_create_agent_configs.sql

@@ -0,0 +1,36 @@
+-- Create table for storing agent OpenClaw configs
+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,
+  version TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Index for faster lookups
+CREATE INDEX IF NOT EXISTS idx_agent_configs_name ON agent_configs(agent_name);
+
+-- Enable RLS
+ALTER TABLE agent_configs ENABLE ROW LEVEL SECURITY;
+
+-- Allow service role full access
+CREATE POLICY "Service role full access" ON agent_configs
+  FOR ALL
+  TO service_role
+  USING (true)
+  WITH CHECK (true);
+
+-- Add updated_at trigger
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER update_agent_configs_updated_at
+  BEFORE UPDATE ON agent_configs
+  FOR EACH ROW
+  EXECUTE FUNCTION update_updated_at_column();

package/supabase/migrations/20260305111300_create_cli_config_registry.sql

@@ -0,0 +1,22 @@
+-- create shared config registry for optimal-cli profile sync
+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);
+
+-- note: rls policies intentionally deferred until auth model is finalized.

package/supabase/migrations/20260306195000_create_kanban_tables.sql

@@ -0,0 +1,97 @@
+-- Kanban tables for 3-way sync: supabase + obsidian + cli
+
+-- Projects table
+CREATE TABLE IF NOT EXISTS cli_projects (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  slug TEXT UNIQUE NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT,
+  status TEXT DEFAULT 'active' CHECK (status IN ('active', 'archived', 'on_hold')),
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Tasks table
+CREATE TABLE IF NOT EXISTS cli_tasks (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  project_id UUID REFERENCES cli_projects(id) ON DELETE CASCADE,
+  task_id TEXT NOT NULL, -- from obsidian filename, e.g., "task__optimal-cli-shared-config-registry__b7c1d2e3"
+  title TEXT NOT NULL,
+  description TEXT,
+  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'in_progress', 'done', 'cancelled')),
+  priority INTEGER DEFAULT 3 CHECK (priority BETWEEN 1 AND 4),
+  owner TEXT, -- agent or person responsible
+  assignee TEXT,
+  tags JSONB DEFAULT '[]',
+  source TEXT, -- e.g., "chat:carlos:2026-03-04"
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW(),
+  completed_at TIMESTAMPTZ,
+  completed_by TEXT,
+  metadata JSONB DEFAULT '{}',
+  UNIQUE(project_id, task_id)
+);
+
+-- Sync log for tracking changes
+CREATE TABLE IF NOT EXISTS cli_sync_log (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  entity_type TEXT NOT NULL, -- 'project' or 'task'
+  entity_id UUID NOT NULL,
+  action TEXT NOT NULL, -- 'create', 'update', 'delete'
+  source TEXT NOT NULL, -- 'cli', 'obsidian', 'manual'
+  synced_at TIMESTAMPTZ DEFAULT NOW(),
+  payload JSONB
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_tasks_project ON cli_tasks(project_id);
+CREATE INDEX IF NOT EXISTS idx_tasks_status ON cli_tasks(status);
+CREATE INDEX IF NOT EXISTS idx_tasks_owner ON cli_tasks(owner);
+CREATE INDEX IF NOT EXISTS idx_tasks_assignee ON cli_tasks(assignee);
+CREATE INDEX IF NOT EXISTS idx_sync_log_entity ON cli_sync_log(entity_type, entity_id);
+
+-- Enable RLS
+ALTER TABLE cli_projects ENABLE ROW LEVEL SECURITY;
+ALTER TABLE cli_tasks ENABLE ROW LEVEL SECURITY;
+ALTER TABLE cli_sync_log ENABLE ROW LEVEL SECURITY;
+
+-- RLS policies (service role can do everything)
+CREATE POLICY "service_role_full_access_projects" ON cli_projects FOR ALL USING (true) WITH CHECK (true);
+CREATE POLICY "service_role_full_access_tasks" ON cli_tasks FOR ALL USING (true) WITH CHECK (true);
+CREATE POLICY "service_role_full_access_sync_log" ON cli_sync_log FOR ALL USING (true) WITH CHECK (true);
+
+-- Function to update updated_at
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Triggers for updated_at
+CREATE TRIGGER update_projects_updated_at BEFORE UPDATE ON cli_projects
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
+
+CREATE TRIGGER update_tasks_updated_at BEFORE UPDATE ON cli_tasks
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
+
+-- Insert default project for optimal tasks
+INSERT INTO cli_projects (slug, name, description)
+VALUES ('optimal-tasks', 'Optimal Tasks', 'Main task tracking for optimal agents')
+ON CONFLICT (slug) DO NOTHING;
+
+-- Function to log sync
+CREATE OR REPLACE FUNCTION log_sync(
+  p_entity_type TEXT,
+  p_entity_id UUID,
+  p_action TEXT,
+  p_source TEXT,
+  p_payload JSONB DEFAULT '{}'::JSONB
+)
+RETURNS VOID AS $$
+BEGIN
+  INSERT INTO cli_sync_log (entity_type, entity_id, action, source, payload)
+  VALUES (p_entity_type, p_entity_id, p_action, p_source, p_payload);
+END;
+$$ LANGUAGE plpgsql;