optimal-cli 1.0.0 → 1.1.0

package/skills/manage-scenarios/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: manage-scenarios
+description: Save, load, compare, and delete named budget scenarios for Wes projections
+---
+
+## Purpose
+Manages named budget scenarios for the Wes dashboard budget projection system. Scenarios are snapshots of `fpa_yield_assumptions` data (unit forecasts, WIP units, yield rates) that can be saved, loaded, compared side-by-side, and shared across users. This enables what-if analysis — e.g., "optimistic Q2" vs "conservative Q2" scenarios.
+
+## Inputs
+- **action** (required): One of `save`, `load`, `list`, `compare`, `delete`.
+- **name** (required for save/load/delete): Scenario name (e.g., `"optimistic-q2-2026"`, `"baseline-fy25"`).
+- **fiscal-year** (optional): Fiscal year filter. Default: current fiscal year.
+- **user-id** (optional): User UUID for scenario ownership. Default: Carlos's user ID.
+- **compare-with** (required for compare): Second scenario name to compare against.
+- **format** (optional): Output format for compare/list — `table` (default) or `csv`.
+
+## Steps
+1. Call `lib/budget/scenarios.ts::manageScenarios(action, options)` to orchestrate
+2. **save**: Snapshot current `fpa_yield_assumptions` rows (filtered by user + fiscal year) into a named scenario record, stored as JSON blob with metadata (name, created_at, user_id, row_count)
+3. **load**: Restore a saved scenario by overwriting `fpa_yield_assumptions` rows for the target user + fiscal year with the snapshot data. Creates a backup of current data first.
+4. **list**: Show all saved scenarios with name, created_at, fiscal_year, row_count, user
+5. **compare**: Load two scenarios side-by-side and compute deltas — total units, revenue projection, per-program differences
+6. **delete**: Remove a named scenario (with confirmation)
+7. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+**list**:
+```
+| Name | FY | Created | Rows | User |
+|------|----|---------|------|------|
+| baseline-fy25 | FY25 | 2026-01-15 | 1,264 | Carlos |
+| optimistic-q2 | FY26 | 2026-02-20 | 1,310 | Carlos |
+```
+
+**compare**:
+```
+Comparing: baseline-fy25 vs optimistic-q2
+
+| Program | Baseline Units | Optimistic Units | Delta | Delta % |
+|---------|---------------|-----------------|-------|---------|
+| BRTON-WM | 42,000 | 48,500 | +6,500 | ↑15.5% |
+| FORTX-POOL | 18,200 | 16,800 | -1,400 | ↓-7.7% |
+| Total | 7,352,022 | 7,891,450 | +539,428 | ↑7.3% |
+```
+
+**save**: `Saved scenario "optimistic-q2" (1,310 rows, FY26)`
+
+**load**: `Loaded scenario "baseline-fy25" → overwrote 1,264 rows (backup: auto-backup-20260301T100000)`
+
+## CLI Usage
+```bash
+# Save current assumptions as a named scenario
+optimal manage-scenarios save --name optimistic-q2 --fiscal-year FY26
+
+# Load a saved scenario
+optimal manage-scenarios load --name baseline-fy25
+
+# List all scenarios
+optimal manage-scenarios list
+
+# Compare two scenarios
+optimal manage-scenarios compare --name baseline-fy25 --compare-with optimistic-q2
+
+# Delete a scenario
+optimal manage-scenarios delete --name old-test-scenario
+```
+
+## Environment
+Requires: `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`
+
+## Tables Touched
+- `fpa_yield_assumptions` — read/write unit forecasts and yield data. Unique key: `(user_id, fiscal_year, month, master_program_id)`
+- `wes_imports` — baseline reference for sync validation
+- Scenario storage: TBD — either a new `budget_scenarios` table or JSON blobs in an existing metadata table
+
+## Gotchas
+- **fpa_yield_assumptions refactor**: Table was refactored Feb 2026 — dropped 3 WIP% columns, added `wip_units INTEGER`. Unique key is `(user_id, fiscal_year, month, master_program_id)`.
+- **Wes sync pattern**: When baselines diverge, copy from Carlos to all other users. FY25 baseline: 7,352,022 units, 1,264 rows, 97 masters.
+- **Load creates backup**: Loading a scenario automatically saves the current state as `auto-backup-{timestamp}` before overwriting.
+- **User isolation**: Scenarios are per-user by default. Cross-user scenario sharing requires explicit user-id parameter.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/budget/scenarios.ts` to be built on top of existing `lib/budget/projections.ts` in wes-dashboard.

package/skills/migrate-db/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: migrate-db
+description: Run Supabase database migrations across ReturnPro or OptimalOS instances
+---
+
+## Purpose
+Executes pending database migrations against the linked Supabase instance using `supabase db push --linked`. This is the only sanctioned way to modify database schemas — Carlos never runs SQL manually. Supports both the ReturnPro instance (financial data) and the OptimalOS instance (kanban, transactions).
+
+## Inputs
+- **instance** (required): Target Supabase instance — `returnpro` or `optimalos`.
+- **migration** (optional): Specific migration file name to create before pushing (e.g., `add-budget-scenarios-table`). If provided, creates the file in `supabase/migrations/` first.
+- **sql** (optional): SQL content for a new migration file. Required if `--migration` is specified.
+- **dry-run** (optional): Show pending migrations without applying them.
+
+## Steps
+1. Call `lib/infra/migrate.ts::migrateDb(instance, options?)` to orchestrate
+2. **Resolve instance** — map `returnpro` to `/home/optimal/dashboard-returnpro` supabase config, `optimalos` to `/home/optimal/optimalos` supabase config (or the consolidated `/home/optimal/optimal-cli/supabase` config)
+3. **Create migration file** (if `--migration` + `--sql` provided):
+   - Generate timestamped filename: `{YYYYMMDDHHmmss}_{migration-name}.sql`
+   - Write SQL content to `supabase/migrations/{filename}`
+4. **List pending** — show which migrations haven't been applied yet
+5. **Push** — run `supabase db push --linked` from the appropriate project directory
+6. **Verify** — confirm migration was applied successfully
+7. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Instance: returnpro
+Project dir: /home/optimal/dashboard-returnpro
+Pending migrations: 1
+
+Applying: 20260301100000_add-budget-scenarios-table.sql
+Migration applied successfully.
+
+Current schema version: 20260301100000
+```
+
+Dry-run:
+```
+[DRY RUN] Instance: returnpro
+Pending migrations:
+  1. 20260301100000_add-budget-scenarios-table.sql (new)
+Would run: supabase db push --linked
+```
+
+## CLI Usage
+```bash
+# Push pending migrations to ReturnPro
+optimal migrate-db --instance returnpro
+
+# Push to OptimalOS
+optimal migrate-db --instance optimalos
+
+# Create a new migration and push
+optimal migrate-db --instance returnpro --migration add-budget-scenarios --sql "CREATE TABLE budget_scenarios (...);"
+
+# Dry run
+optimal migrate-db --instance returnpro --dry-run
+```
+
+## Environment
+Requires: `supabase` CLI installed (Homebrew, v2.72.7+). Authentication is handled internally by `supabase db push --linked`.
+
+## Supabase Instances
+
+| Instance | Supabase URL | Project Directory |
+|----------|-------------|-------------------|
+| returnpro | vvutttwunexshxkmygik.supabase.co | /home/optimal/dashboard-returnpro |
+| optimalos | hbfalrpswysryltysonm.supabase.co | /home/optimal/optimalos |
+
+## Gotchas
+- **Never run SQL manually**: Always use migration files + `supabase db push --linked`. This is a hard rule.
+- **No `supabase db execute`**: The `db execute` subcommand does not exist in Supabase CLI v2.72.7. Use migration files instead.
+- **No psql directly**: The pooler has permission issues and direct IPv6 is unreachable. `db push --linked` handles auth internally.
+- **stg_financials_raw.amount is TEXT**: If a migration touches this column, remember it stores amounts as TEXT strings, not NUMERIC.
+- **Reserved fields in Strapi**: If migrating Strapi's underlying Postgres, avoid `status`, `published_at`, `locale`, `meta` as column names.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/infra/migrate.ts` to be built as a cross-repo migration runner.

package/skills/preview-newsletter/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: preview-newsletter
+description: Deploy the newsletter preview site to Vercel for client review
+---
+
+## Purpose
+Deploys the newsletter-preview Next.js site to Vercel so clients and stakeholders can review newsletters and social posts in a branded web interface. This is a thin wrapper around the `deploy` skill, pre-configured for the `newsletter-preview` app. The preview site renders published Strapi content at `https://newsletter.op-hub.com`.
+
+## Inputs
+- **prod** (optional): Deploy to production. Default: preview deployment.
+
+## Steps
+1. Call `lib/infra/deploy.ts::deploy('newsletter-preview', options?)` to deploy
+2. Resolves to path `/home/optimal/projects/newsletter-preview`
+3. Runs `vercel --cwd /home/optimal/projects/newsletter-preview` (or `vercel --prod` for production)
+4. Waits for deployment to complete (up to 2 minutes)
+5. Returns the deployment URL
+6. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Deploying newsletter-preview...
+Preview URL: https://newsletter-preview-abc123.vercel.app
+```
+
+Or for production:
+```
+Deploying newsletter-preview to production...
+Production URL: https://newsletter.op-hub.com
+```
+
+## CLI Usage
+```bash
+# Preview deployment
+optimal preview-newsletter
+
+# Production deployment
+optimal preview-newsletter --prod
+```
+
+## Environment
+Requires: `vercel` CLI installed globally and authenticated.
+
+## Gotchas
+- **This is just a deploy**: No content generation happens here. Use `generate-newsletter` or `generate-newsletter-insurance` first to create content, then deploy the preview.
+- **Strapi must be reachable**: The preview site fetches content from Strapi at build time and runtime. Strapi must be running at `https://strapi.op-hub.com`.
+- **Brand routes**: CRE-11TRUST content at `/cre-11trust`, LIFEINSUR content at `/lifeinsur`.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Uses existing `lib/infra/deploy.ts` with `newsletter-preview` app name.

package/skills/project-budget/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: project-budget
+description: Run FY26 budget projections with percentage or flat adjustments on FY25 checked-in units
+---
+
+## Purpose
+Generates FY26 budget projections by applying uniform adjustments (percentage or flat) to FY25 actual checked-in units. Supports both unit volume and average retail price projections, with revenue calculations (units x retail).
+
+Data comes from either:
+1. ReturnPro Supabase `fpa_wes_imports` table (default)
+2. A JSON file of `CheckedInUnitsSummary[]` (via `--file` flag or stdin)
+
+## Inputs
+- **adjustment-type** (optional): `percent` or `flat`. Default: `percent`.
+- **adjustment-value** (optional): Numeric value for the adjustment. Default: `0` (no change).
+- **format** (optional): Output format — `table` (Bloomberg-dense markdown) or `csv`. Default: `table`.
+- **fiscal-year** (optional): Base fiscal year for actuals. Default: `2025`.
+- **user-id** (optional): Supabase user UUID to filter imports by.
+- **file** (optional): Path to a JSON file containing `CheckedInUnitsSummary[]` array. If provided, skips Supabase fetch.
+
+## Steps
+1. Load FY25 data: fetch from `fpa_wes_imports` or parse from JSON file
+2. Call `initializeProjections(summary)` to create baseline entries
+3. Call `applyUniformAdjustment(projections, type, value)` if adjustment specified
+4. Format output as table or CSV via `formatProjectionTable()` or `exportToCSV()`
+
+## Output
+Table format (default) — Bloomberg-dense:
+
+```
+FY25 Actual: 7.35M units  |  FY26 Projected: 7.65M units  |  +4.0%
+Revenue: $180.2M -> $187.4M  |  +4.0%
+
+| Client | Program | FY25 Units | FY26 Units | Delta | Avg Retail | Proj Retail | Rev Delta |
+|--------|---------|------------|------------|-------|------------|-------------|-----------|
+| Walmart | BRTON-WM-LIQ | 120.5K | 125.3K | +4.8K (4.0%) | $45.20 | $45.20 | +$217.0K |
+```
+
+CSV format: full-precision export with unit, retail, and inventory value columns.
+
+## CLI Usage
+```bash
+# Default: no adjustment, table format, FY25 from Supabase
+npx tsx bin/optimal.ts project-budget
+
+# 4% growth projection
+npx tsx bin/optimal.ts project-budget --adjustment-type percent --adjustment-value 4
+
+# Flat +500 units per program
+npx tsx bin/optimal.ts project-budget --adjustment-type flat --adjustment-value 500
+
+# CSV output
+npx tsx bin/optimal.ts project-budget --adjustment-type percent --adjustment-value 4 --format csv
+
+# From JSON file instead of Supabase
+npx tsx bin/optimal.ts project-budget --file ./fy25-actuals.json --adjustment-type percent --adjustment-value 10
+```
+
+## Environment
+Requires (when using Supabase): `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`

package/skills/publish-blog/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: publish-blog
+description: Publish a blog post to Strapi CMS and deploy the portfolio site to Vercel
+---
+
+## Purpose
+End-to-end blog publishing workflow: creates or updates a blog post in Strapi CMS, publishes it, and deploys the portfolio-2026 site to Vercel so the post goes live at carloslenis.com. Supports both manual blog posts and automated research reports (AI-generated content with specific formatting rules).
+
+## Inputs
+- **title** (required): Blog post title.
+- **slug** (optional): URL slug. Default: auto-generated from title + year (e.g., `copper-investment-thesis-ai-data-centers-2026`).
+- **content** (required): Markdown content for the blog post body.
+- **site** (required): Site filter — `portfolio` (carloslenis.com) or `insurance` (future).
+- **tags** (optional): Comma-separated tag names (e.g., `"Automated Report,AI,Finance"`).
+- **documentId** (optional): If provided, updates an existing post instead of creating a new one.
+- **deploy** (optional): Auto-deploy portfolio site after publishing. Default: true.
+- **draft** (optional): Create as draft without publishing. Default: false (publish immediately).
+
+## Steps
+1. Call `lib/cms/strapi-client.ts` functions to manage the blog post lifecycle
+2. **Build payload** — construct Strapi `blog-post` data: title, slug, content, site, tags
+3. **Create or update** — if `--documentId` given, `strapiPut('/api/blog-posts', documentId, data)`; otherwise `strapiPost('/api/blog-posts', data)`
+4. **Publish** — unless `--draft` is set, call `publish('blog-posts', documentId)`
+5. **Deploy** — unless `--deploy false`, call `lib/infra/deploy.ts::deploy('portfolio', { prod: true })` to push to Vercel production
+6. **Return** — documentId, slug, and live URL
+7. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Blog post published: "Copper Investment Thesis for AI Data Centers"
+Slug: copper-investment-thesis-ai-data-centers-2026
+DocumentId: abc123-def456
+Site: portfolio
+Tags: Automated Report, AI, Finance
+Deploy: production → https://carloslenis.com
+```
+
+## CLI Usage
+```bash
+# Publish a new blog post and deploy
+optimal publish-blog --title "My Post" --content ./post.md --site portfolio --tags "Finance"
+
+# Create as draft (no deploy)
+optimal publish-blog --title "Draft Post" --content ./draft.md --site portfolio --draft
+
+# Update existing post
+optimal publish-blog --documentId abc123 --content ./updated.md --deploy
+```
+
+## Automated Report Format
+When publishing AI-generated research reports, the content MUST follow these rules:
+- **Tag**: `"Automated Report"` (never pretend Carlos wrote it)
+- **Structure**: Disclosure blockquote at top, `---` between every section, `## ` headings for section cards
+- **References**: Numbered inline refs `[[1]](#ref-1)` with `## Sources & References` section at bottom
+- **Tables**: Use heavily to break up text (data tables, comparisons, scorecards)
+- **Links**: Every data claim must be hyperlinked to its source
+- **Slug format**: `topic-keywords-YYYY`
+
+The portfolio site's `BlogContent` component auto-detects multi-section posts (4+ sections with `---`) and renders each `## ` section as a themed card with colored borders.
+
+## Environment
+Requires: `STRAPI_URL`, `STRAPI_API_TOKEN`, `vercel` CLI (for deploy)
+
+## Gotchas
+- **documentId for updates**: Strapi v5 uses documentId (UUID), not numeric id.
+- **Site field**: The `site` enum in Strapi blog-post schema determines which site renders the post. Add new sites by editing the schema.
+- **Deploy after publish**: By default, the portfolio site is redeployed to production after publishing. Pass `--deploy false` to skip.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Uses existing `lib/cms/strapi-client.ts` for Strapi operations and `lib/infra/deploy.ts` for Vercel deployment.

package/skills/publish-social-posts/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: publish-social-posts
+description: Push social post drafts from Strapi to live platforms (Instagram, Facebook, LinkedIn) via distribution hub
+---
+
+## Purpose
+Publishes social post drafts from Strapi CMS to their target platforms (Instagram, Facebook, LinkedIn, Twitter/X). Works through the distribution hub: publishes the Strapi entry (triggers webhook), which n8n picks up to post to the actual social platforms via Meta Marketing API and other platform APIs. Handles both immediate publishing and scheduled posts.
+
+## Inputs
+- **brand** (required): Brand key — `CRE-11TRUST` or `LIFEINSUR`
+- **documentIds** (optional): Comma-separated Strapi documentIds to publish. If omitted, publishes all pending drafts for the brand.
+- **schedule-only** (optional): Only publish posts with a `scheduled_date` in the future (let the 15-minute cron handle delivery). Default: false.
+- **test** (optional): Post to test/sandbox accounts instead of live pages.
+
+## Steps
+1. Call `lib/cms/strapi-client.ts::publishSocialPosts(brand, options?)` to orchestrate
+2. **Fetch pending posts** — if `--documentIds` provided, fetch those specific posts; otherwise `listByBrand('social-posts', brand, 'draft')` to get all pending drafts
+3. **Validate posts** — ensure each post has required fields: headline, body, image_url, platform, scheduled_date
+4. **Publish in Strapi** — `publish('social-posts', documentId)` for each post (sets publishedAt, triggers webhook)
+5. **n8n distribution** — Strapi publish webhook fires n8n workflow which:
+   - Reads `brand-config` for platform IDs (IG page ID, FB page ID, etc.)
+   - Posts to target platform via respective API
+   - Updates `delivery_status` (pending → scheduled/delivered/failed)
+   - Writes `platform_post_id` back to Strapi on success
+6. **Report results** — summarize published vs scheduled vs failed
+7. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Brand: LIFEINSUR
+Posts processed: 9
+
+| # | Headline | Platform | Status | Post ID |
+|---|----------|----------|--------|---------|
+| 1 | "Protect What Matters" | instagram | delivered | 17899... |
+| 2 | "Your Family's Future" | facebook | delivered | 61294... |
+| 3 | "Life Insurance Myths" | instagram | scheduled (3/4) | — |
+| ... | ... | ... | ... | ... |
+
+Delivered: 4  |  Scheduled: 5  |  Failed: 0
+```
+
+## CLI Usage
+```bash
+# Publish all pending LIFEINSUR posts
+optimal publish-social-posts --brand LIFEINSUR
+
+# Publish specific posts
+optimal publish-social-posts --brand CRE-11TRUST --documentIds abc123,def456,ghi789
+
+# Only set up scheduled posts (don't post immediately)
+optimal publish-social-posts --brand LIFEINSUR --schedule-only
+
+# Test mode
+optimal publish-social-posts --brand LIFEINSUR --test
+```
+
+## Environment
+Requires: `STRAPI_URL`, `STRAPI_API_TOKEN`
+Platform credentials managed in n8n (Meta access token, Twitter keys, etc.), not in CLI.
+
+## Gotchas
+- **n8n must be running**: Distribution depends on n8n catching the Strapi webhook.
+- **brand-config required**: The `brand-config` content type in Strapi must have platform IDs (IG page ID, FB page ID) for the target brand.
+- **Scheduling**: Posts with future `scheduled_date` are queued — a 15-minute n8n cron picks them up. Posts with past/blank `scheduled_date` are distributed immediately on publish.
+- **delivery_status flow**: pending → scheduled (if future date) → delivered/failed. Partial state means some platforms succeeded and others failed.
+- **Meta Marketing API**: Requires `ads_management` + `ads_read` permissions on the Meta developer app access token.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Uses existing `lib/cms/strapi-client.ts` for Strapi operations; distribution handled by n8n webhook.

package/skills/rate-anomalies/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: rate-anomalies
+description: Flag outlier $/unit rates across programs and months in ReturnPro financial data
+---
+
+## Purpose
+Detects anomalous per-unit rates ($/unit) across programs and months in ReturnPro's staged financial data. Compares each program-month's rate against its historical average and flags statistical outliers. This is a key data quality tool — rate anomalies often indicate data entry errors, misclassified programs, or upstream reporting issues.
+
+## Inputs
+- **months** (optional): Comma-separated YYYY-MM strings to analyze. Default: last 6 months with data.
+- **threshold** (optional): Z-score threshold for flagging anomalies. Default: `2.0` (2 standard deviations).
+- **programs** (optional): Comma-separated program name substrings to filter. Default: all programs.
+- **format** (optional): Output format — `table` (default) or `csv`.
+
+## Steps
+1. Call `lib/returnpro/anomalies.ts::detectRateAnomalies(options?)` to fetch and analyze data
+2. Query `stg_financials_raw` for revenue and unit rows across the target months
+3. Compute $/unit rate for each program-month combination
+4. Calculate historical mean and standard deviation per program
+5. Flag any program-month where the rate's z-score exceeds the threshold
+6. Sort flagged anomalies by severity (highest z-score first)
+7. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+Bloomberg-dense table with inline severity indicators:
+
+| Program | Month | Rate | Avg Rate | Z-Score | Delta |
+|---------|-------|------|----------|---------|-------|
+| BRTON-WM | 2026-01 | $3.42/u | $2.10/u | 3.1 | ↑62.9% |
+| FORTX-POOL | 2025-12 | $0.89/u | $1.55/u | -2.4 | ↓-42.6% |
+
+Rows with z-score > 3.0 get `bg-red-500/5` row tint indicator. All numbers are `font-mono`, right-aligned.
+
+## CLI Usage
+```bash
+# Default: last 6 months, z-score threshold 2.0
+optimal rate-anomalies
+
+# Specific months, stricter threshold
+optimal rate-anomalies --months 2026-01,2025-12 --threshold 1.5
+
+# Filter to specific programs
+optimal rate-anomalies --programs BRTON,FORTX
+
+# CSV export
+optimal rate-anomalies --format csv > anomalies.csv
+```
+
+## Environment
+Requires: `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`
+
+## Tables Touched
+- `stg_financials_raw` — read revenue and unit data (CAST amount from TEXT)
+- `dim_master_program` — resolve program names
+
+## Gotchas
+- **amount is TEXT**: Always CAST `stg_financials_raw.amount` before numeric operations.
+- **Reference implementation**: The Bloomberg-dense rate anomaly explorer UI is at `components/analysis/rate-anomaly-explorer.tsx` in dashboard-returnpro (Feb 2026 redesign).
+- **Sign conventions**: Revenue is positive, expenses are negative. Unit counts are always positive.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/returnpro/anomalies.ts` to be extracted from dashboard-returnpro's `/api/analytics/rate-anomalies` route.

package/skills/scrape-ads/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: scrape-ads
+description: Scrape Meta Ad Library for competitor ad intelligence using headless Playwright browser
+---
+
+## Purpose
+Scrape the Facebook/Meta Ad Library to extract competitor ad data for analysis. Uses headless Chromium with anti-detection measures (disabled automation features, realistic user agent, viewport 1920x1080). Extracts ad metadata including Library ID, status, start date, ad copy, platforms, impressions, spend, and media type.
+
+## Inputs
+- **companies** (required): Comma-separated list of company names, OR a path to a text file with one company per line
+- **output** (optional): File path to save CSV results (default: stdout)
+- **batch-size** (optional): Number of companies per batch (default: 6). Companies run sequentially within a batch with 4s delay between each.
+
+## Steps
+1. **Parse companies** — accept CSV string or read from file (one company per line)
+2. **Launch browser** — headless Chromium with anti-detection args
+3. **Batch processing** — split companies into batches of `batch-size`, each batch gets a fresh browser context
+4. **Per company**: navigate to Ad Library search URL, wait for load, scroll to load all ads (up to 15 scrolls with 2s delay each)
+5. **Extract ads** — two-stage: first try DOM querySelectorAll for divs containing exactly one `Library ID: \d+`, then fallback to splitting full page text by Library ID boundaries
+6. **Parse metadata** — regex extraction of Library ID, start date, status, page name, ad text, impressions, spend, media type, platforms
+7. **Extract landing URLs** — scan DOM for `l.facebook.com` redirect links and associate with ad IDs
+8. **Output CSV** — columns: company_searched, ad_id, page_name, ad_text, status, start_date, impressions, spend, media_type, platforms, landing_page_url, full_text_snippet
+
+## Output
+- CSV data (to stdout or file) with one row per ad
+- Console progress logs during scraping
+
+## CLI Usage
+```bash
+# Scrape specific companies (stdout)
+optimal scrape-ads --companies "State Farm,Allstate,GEICO"
+
+# Scrape from file, save to CSV
+optimal scrape-ads --companies ~/projects/meta-ad-scraper/data/companies.txt --output ./ads.csv
+
+# Custom batch size
+optimal scrape-ads --companies "Company A,Company B" --batch-size 3
+```
+
+## Environment
+Requires: `playwright` npm package with Chromium browser installed (`npx playwright install chromium`)
+
+## Gotchas
+- **Browser install**: Playwright requires a one-time `npx playwright install chromium` to download the browser binary. The scraper will fail if this hasn't been run.
+- **Rate limiting**: Facebook may rate-limit or block automated access. The 4s delay between companies and fresh contexts per batch help mitigate this.
+- **Anti-detection**: Uses `--disable-blink-features=AutomationControlled` and a realistic user agent string.
+- **DOM extraction**: The primary extraction strategy looks for div elements containing exactly one Library ID with text length between 50-5000 chars, deduplicated by Library ID. Falls back to text splitting if DOM strategy finds nothing.
+- **Batch strategy**: Per memory, run in 3 parallel batches of 6 companies each for optimal throughput.
+- **No actual execution in CI**: This scraper hits live Facebook servers. Do not run in automated pipelines without explicit intent.

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.