optimal-cli 1.0.0 → 1.1.0

package/skills/diagnose-months/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: diagnose-months
+description: Find FK resolution failures and data gaps in staged financial months
+---
+
+## Purpose
+Diagnoses data quality issues in `stg_financials_raw` by scanning for foreign key resolution failures (orphaned account codes, unresolved program IDs, missing client mappings) and data gaps (months with unexpectedly low row counts). This is the go-to debugging tool when audit-financials reports accuracy below 100% — it pinpoints exactly which rows failed to resolve against dimension tables.
+
+## Inputs
+- **months** (optional): Comma-separated YYYY-MM strings to diagnose. Default: all months with data.
+- **verbose** (optional): Show individual failing rows (not just summary counts). Default: false.
+
+## Steps
+1. Call `lib/returnpro/diagnose.ts::diagnoseMonths(months?, options?)` to run diagnostics
+2. For each target month, query `stg_financials_raw` and attempt FK resolution:
+   - Join `account_code` against `dim_account.account_code` — flag unresolved
+   - Join `master_program_id` against `dim_master_program.id` — flag unresolved
+   - Join `client_id` against `dim_client.id` — flag unresolved (if present)
+3. Count rows per month and compare against expected baseline (~88-93 accounts/month for staging)
+4. Identify months with zero staging data (data gaps)
+5. Summarize failures by type and month
+6. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+Summary table:
+
+| Month | Rows | Unresolved Accounts | Unresolved Programs | Unresolved Clients | Status |
+|-------|------|---------------------|---------------------|--------------------|--------|
+| 2026-01 | 91 | 0 | 2 | 0 | 2 issues |
+| 2025-12 | 89 | 1 | 0 | 0 | 1 issue |
+| 2025-11 | 0 | - | - | - | NO DATA |
+
+With `--verbose`, individual failing rows are listed below the summary:
+
+```
+Unresolved programs in 2026-01:
+  Row 45: account_code=4100, master_program_id=999 (no match in dim_master_program)
+  Row 72: account_code=5200, master_program_id=1001 (no match in dim_master_program)
+```
+
+## CLI Usage
+```bash
+# Diagnose all months
+optimal diagnose-months
+
+# Specific months
+optimal diagnose-months --months 2026-01,2025-12
+
+# Verbose output with individual rows
+optimal diagnose-months --months 2026-01 --verbose
+```
+
+## Environment
+Requires: `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`
+
+## Tables Touched
+- `stg_financials_raw` — scan for FK issues
+- `dim_account` — validate account codes
+- `dim_master_program` — validate program IDs
+- `dim_client` — validate client IDs
+- `dim_program_id` — validate program IDs (secondary lookup)
+
+## Gotchas
+- **Coverage gap is expected**: Staging has ~88-93 accounts/month vs confirmed's ~185-193. This is because not all GL accounts are in Solution7. Diagnose-months focuses on FK resolution failures within the staged data, not the coverage gap itself.
+- **amount is TEXT**: Remember to CAST when doing any numeric analysis on flagged rows.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/returnpro/diagnose.ts` to be extracted from dashboard-returnpro's `/api/admin/diagnose-months` route.

package/skills/distribute-newsletter/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: distribute-newsletter
+description: Push a published newsletter to GoHighLevel for email distribution via n8n webhook
+---
+
+## Purpose
+Triggers distribution of a published Strapi newsletter to subscribers via GoHighLevel email. Uses n8n as the orchestration layer — the skill fires a webhook that kicks off the n8n distribution workflow, which handles email blast creation, recipient targeting, and delivery tracking with 3x retry logic.
+
+## Inputs
+- **documentId** (required): Strapi newsletter documentId to distribute.
+- **brand** (optional): Brand filter for recipient targeting (`CRE-11TRUST` or `LIFEINSUR`). Auto-detected from the newsletter if not provided.
+- **test** (optional): Send to a test recipient list instead of the full subscriber list. Useful for previewing the email in an inbox before full blast.
+
+## Steps
+1. Call `lib/newsletter/distribute.ts::distributeNewsletter(documentId, options?)` to orchestrate
+2. **Fetch newsletter from Strapi** — `strapiGet('/api/newsletters/{documentId}')` — verify it is published (not draft)
+3. **Validate HTML body** — ensure `html_body` is present and non-empty
+4. **Determine brand** — from newsletter's `brand` field or `--brand` override
+5. **Fire n8n webhook** — POST to the n8n distribution webhook URL with payload: `{ documentId, brand, html_body, subject_line, sender_email, test }`
+6. **n8n workflow handles**: GHL campaign creation, recipient targeting by brand, email send, 3x retry on failures
+7. **Poll for delivery status** — check newsletter's `delivery_status` field (pending → sending → delivered/partial/failed) with 10s intervals, timeout after 5 minutes
+8. **Update Strapi** — `strapiPut('/api/newsletters', documentId, { delivery_status, delivered_at, recipients_count })` (done by n8n, but verify here)
+9. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Newsletter: "South Florida CRE Market Update — March 2026"
+Brand: CRE-11TRUST
+Delivery status: delivered
+Recipients: 342
+Delivered at: 2026-03-01T09:15:00Z
+GHL Campaign ID: camp_abc123
+```
+
+## CLI Usage
+```bash
+# Distribute a published newsletter
+optimal distribute-newsletter --documentId abc123-def456
+
+# Test send first
+optimal distribute-newsletter --documentId abc123-def456 --test
+
+# Explicit brand override
+optimal distribute-newsletter --documentId abc123-def456 --brand LIFEINSUR
+```
+
+## Environment
+Requires: `STRAPI_URL`, `STRAPI_API_TOKEN`, `N8N_WEBHOOK_URL` (distribution trigger endpoint)
+GoHighLevel credentials are stored in n8n, not in the CLI.
+
+## Gotchas
+- **Must be published**: The newsletter must be in "published" state in Strapi. Draft newsletters cannot be distributed.
+- **n8n must be running**: The distribution workflow depends on n8n being active (`npx n8n` or running as service on port 5678).
+- **3x retry logic**: n8n handles retries. If all 3 attempts fail, `delivery_status` is set to `failed` and `delivery_errors` JSON contains the failure details.
+- **Scheduling**: Newsletters with a future `scheduled_date` are queued and distributed by a 15-minute n8n cron, not immediately.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/newsletter/distribute.ts` to be built as a webhook trigger client.

package/skills/export-budget/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: export-budget
+description: Export FY26 budget projections as CSV with unit, retail, and inventory value columns
+---
+
+## Purpose
+Exports FY26 budget projections as a CSV file suitable for import into spreadsheets, Vena, or other planning tools. Includes full unit projection, average retail projection, and computed inventory value (units x retail) columns.
+
+This is a convenience wrapper around `project-budget --format csv` that writes directly to stdout for piping to a file.
+
+## Inputs
+- **adjustment-type** (optional): `percent` or `flat`. Default: `percent`.
+- **adjustment-value** (optional): Numeric value for the adjustment. Default: `0` (no change).
+- **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.
+
+## Steps
+1. Load FY25 data (same as `project-budget`)
+2. Initialize projections
+3. Apply adjustment if specified
+4. Call `exportToCSV(projections)` and write to stdout
+
+## Output
+CSV with these columns:
+- Program Code, Master Program, Client
+- 2025 Actual Units, Unit Adj Type, Unit Adj Value, 2026 Projected Units, Unit Change, Unit Change %
+- 2025 Avg Retail, Retail Adj Type, Retail Adj Value, 2026 Projected Retail, Retail Change, Retail Change %
+- 2025 Inventory Value, 2026 Projected Inv. Value, Inv. Value Change, Inv. Value Change %
+
+## CLI Usage
+```bash
+# Export with 4% growth to file
+npx tsx bin/optimal.ts export-budget --adjustment-type percent --adjustment-value 4 > fy26-projections.csv
+
+# Export from JSON data source
+npx tsx bin/optimal.ts export-budget --file ./fy25-actuals.json > fy26-projections.csv
+
+# No adjustment (baseline copy)
+npx tsx bin/optimal.ts export-budget > fy26-baseline.csv
+```
+
+## Environment
+Requires (when using Supabase): `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`

package/skills/export-kpis/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: export-kpis
+description: Export KPI totals by program and client from ReturnPro financial data
+---
+
+## Purpose
+Exports KPI data aggregated by program, client, and month from ReturnPro's `stg_financials_raw` table via the `get_kpi_totals_by_program_client` RPC function. Useful for ad-hoc financial analysis, stakeholder reporting, and data validation.
+
+## Inputs
+- **months** (optional): Comma-separated YYYY-MM strings (e.g., `2026-01,2025-12`). Defaults to the 3 most recent months with data.
+- **programs** (optional): Comma-separated program name substrings for case-insensitive filtering (e.g., `BRTON,FORTX`).
+- **format** (optional): Output format — `table` (markdown, default) or `csv`.
+
+## Steps
+1. Call `lib/returnpro/kpis.ts::exportKpis(options?)` to fetch KPI data
+2. Resolve months — use provided list or default to 3 most recent months in `stg_financials_raw`
+3. If programs filter given, resolve names to `master_program_id` via `dim_master_program` (partial match)
+4. For each month (x program), call `get_kpi_totals_by_program_client` RPC
+5. Map results to flat `KpiRow[]` (month, kpiName, kpiBucket, programName, clientName, totalAmount)
+6. Format as markdown table or CSV
+
+## Output
+Table format (default):
+
+| Month   | KPI | Bucket | Client | Program | Amount |
+|---------|-----|--------|--------|---------|--------|
+| 2026-01 | Revenue | Actual | Walmart | BRTON-WM | $1.2M |
+
+CSV format: standard comma-separated with header row.
+
+Amounts use compact notation ($1.2M, $890K) in table mode, full precision in CSV mode.
+
+## CLI Usage
+```bash
+# Latest 3 months, table format
+npx tsx bin/optimal.ts export-kpis
+
+# Specific month
+npx tsx bin/optimal.ts export-kpis --months 2026-01
+
+# Multiple months, CSV output
+npx tsx bin/optimal.ts export-kpis --months 2025-10,2025-11,2025-12 --format csv
+
+# Filter to BRTON programs only
+npx tsx bin/optimal.ts export-kpis --months 2026-01 --programs BRTON
+
+# Pipe CSV to file
+npx tsx bin/optimal.ts export-kpis --format csv > kpis-export.csv
+```
+
+## Environment
+Requires: `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`

package/skills/generate-netsuite-template/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: generate-netsuite-template
+description: Generate a blank NetSuite upload template pre-filled with account codes and program mappings
+---
+
+## Purpose
+Creates a blank upload template (XLSX or CSV) pre-populated with valid account codes, account names, and program mappings from ReturnPro's dimension tables. This saves time when preparing NetSuite data for staging upload — instead of manually looking up codes, Carlos gets a ready-to-fill template with all valid FK references.
+
+## Inputs
+- **month** (required): Target month as YYYY-MM for the template header/period column.
+- **format** (optional): Output format — `xlsx` (default) or `csv`.
+- **output** (optional): File path to save the template. Default: `~/Downloads/returnpro-data/netsuite-template-{YYYY-MM}.{ext}`
+- **programs** (optional): Comma-separated program name substrings to include. Default: all active programs.
+
+## Steps
+1. Call `lib/returnpro/templates.ts::generateNetsuiteTemplate(month, options?)` to build the template
+2. Fetch all active accounts from `dim_account` (account_code, account_name)
+3. Fetch all active programs from `dim_master_program` (program_id, program_name)
+4. Build template structure: one row per account_code, columns for period, account_code, account_name, amount (blank), master_program_id, program_name
+5. If `--programs` filter given, only include matching programs
+6. Write to disk as XLSX (with header formatting) or CSV
+7. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Generated NetSuite template for 2026-01
+Accounts: 193  |  Programs: 97
+Saved to: ~/Downloads/returnpro-data/netsuite-template-2026-01.xlsx
+```
+
+## CLI Usage
+```bash
+# Default XLSX template
+optimal generate-netsuite-template --month 2026-01
+
+# CSV format, custom output path
+optimal generate-netsuite-template --month 2026-01 --format csv --output ./template.csv
+
+# Only BRTON programs
+optimal generate-netsuite-template --month 2026-01 --programs BRTON
+```
+
+## Environment
+Requires: `RETURNPRO_SUPABASE_URL`, `RETURNPRO_SUPABASE_SERVICE_KEY`
+
+## Tables Touched
+- `dim_account` — read account codes and names
+- `dim_master_program` — read program IDs and names
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/returnpro/templates.ts` to be extracted from dashboard-returnpro's `/api/admin/netsuite-template` route.

package/skills/generate-newsletter/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: generate-newsletter
+description: Generate a branded newsletter with AI-powered content, news, and optional property listings, then push to Strapi CMS
+---
+
+## Purpose
+End-to-end newsletter generation pipeline. Fetches news from NewsAPI, generates AI summaries via Groq (Llama 3.3 70B), reads property listings from Excel (CRE brand only), builds branded HTML, and pushes a draft to Strapi CMS. Supports multiple brands: CRE-11TRUST (ElevenTrust) and LIFEINSUR (Anchor Point Insurance).
+
+## Inputs
+- **brand** (required): `CRE-11TRUST` or `LIFEINSUR`
+- **date** (optional): Edition date as YYYY-MM-DD (default: today)
+- **excel** (optional): Path to Excel file with property listings (columnar format: col A = labels, B-N = properties). Only used for CRE-11TRUST brand.
+- **dry-run** (optional): If set, generates content but does NOT push to Strapi. Useful for previewing output.
+
+## Steps
+1. **Load brand config** — determines news query, sender email, display name, template styling
+2. **Read Excel properties** (CRE-11TRUST only) — parse columnar Excel via `readExcelProperties()`
+3. **Fetch news** — `fetchNews(query)` hits NewsAPI for 5 latest articles matching the brand's query
+4. **Generate AI content** — `generateAiContent(properties, news)` sends properties + news to Groq and gets back market overview, property analyses, and news summaries as structured JSON
+5. **Build HTML** — `buildHtml()` assembles a responsive email-safe HTML newsletter with brand-specific colors and sections
+6. **Build Strapi payload** — `buildStrapiPayload()` creates the structured payload with slug (includes timestamp for uniqueness)
+7. **Push to Strapi** — `strapiPost('/api/newsletters', data)` creates a draft newsletter in Strapi CMS (skipped in dry-run mode)
+
+## Output
+- Newsletter HTML (logged length)
+- Strapi draft documentId (or "DRY RUN" indicator)
+- Console summary of all generated content
+
+## CLI Usage
+```bash
+# CRE newsletter with properties from Excel
+optimal generate-newsletter --brand CRE-11TRUST --excel ~/projects/newsletter-automation/input/properties.xlsx
+
+# LIFEINSUR newsletter (no properties)
+optimal generate-newsletter --brand LIFEINSUR
+
+# Preview without pushing to Strapi
+optimal generate-newsletter --brand CRE-11TRUST --dry-run
+
+# Specific edition date
+optimal generate-newsletter --brand CRE-11TRUST --date 2026-03-01 --excel ./input/latest.xlsx
+```
+
+## Environment
+Requires: `GROQ_API_KEY`, `NEWSAPI_KEY`, `STRAPI_URL`, `STRAPI_API_TOKEN`
+Optional: `GROQ_MODEL` (default: llama-3.3-70b-versatile), `NEWSAPI_QUERY`, `LIFEINSUR_NEWSAPI_QUERY`
+
+## Gotchas
+- **Image extraction skipped**: The Python pipeline extracts embedded EMF/WMF images from Excel. This is deferred in the TypeScript port — use the Python pipeline for image-heavy newsletters.
+- **Slug uniqueness**: Slugs include a timestamp (YYYYMMDDTHHMMSS) to avoid conflicts on same-day reruns.
+- **Excel column order matters**: "contact info" matcher runs before "name" to avoid disambiguation issues.
+- **Strapi rate limits**: API token does not rate-limit, but admin login does (5 attempts then 429 for ~2min).
+- **ExcelJS dependency**: Only loaded dynamically when `--excel` is provided, so the dep is optional for non-CRE newsletters.

package/skills/generate-newsletter-insurance/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: generate-newsletter-insurance
+description: Generate an insurance-specific newsletter for Anchor Point Insurance Co. (brand=LIFEINSUR)
+---
+
+## Purpose
+Generates a branded newsletter for Anchor Point Insurance Co. (brand=LIFEINSUR). This is a specialization of the generate-newsletter skill, pre-configured for the insurance vertical — it fetches life insurance and financial planning news, uses the Anchor Point brand palette (warm charcoal #44403E, terracotta #AD7C59, warm beige #FCF9F6), and omits property listings (which are CRE-11TRUST only).
+
+## Inputs
+- **date** (optional): Edition date as YYYY-MM-DD. Default: today.
+- **dry-run** (optional): Generate content but do NOT push to Strapi. Useful for previewing.
+- **news-query** (optional): Override the default NewsAPI query. Default: `LIFEINSUR_NEWSAPI_QUERY` env var or `"life insurance financial planning south florida"`.
+
+## Steps
+1. Call `lib/newsletter/generate-insurance.ts::generateInsuranceNewsletter(options?)` to orchestrate
+2. **Load LIFEINSUR brand config** — palette, sender email (from `brand-config` in Strapi or hardcoded defaults), display name "Anchor Point Insurance Co."
+3. **Fetch news** — `fetchNews(query)` hits NewsAPI for 5 latest articles matching insurance/financial planning topics
+4. **Generate AI content** — `generateAiContent(null, news)` sends news to Groq (no properties for LIFEINSUR). Returns market overview and news summaries.
+5. **Build HTML** — `buildHtml()` assembles responsive email-safe HTML with Anchor Point brand colors and insurance-specific sections
+6. **Build Strapi payload** — `buildStrapiPayload()` with brand=`LIFEINSUR`, slug includes timestamp for uniqueness
+7. **Push to Strapi** — `strapiPost('/api/newsletters', data)` creates a draft newsletter (skipped in dry-run mode)
+8. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Brand: LIFEINSUR (Anchor Point Insurance Co.)
+News articles fetched: 5
+AI content generated: market_overview (342 words), 5 news summaries
+HTML length: 12,847 chars
+Strapi draft created: documentId=abc123-def456
+```
+
+## CLI Usage
+```bash
+# Generate insurance newsletter for today
+optimal generate-newsletter-insurance
+
+# Specific date
+optimal generate-newsletter-insurance --date 2026-03-01
+
+# Preview without pushing to Strapi
+optimal generate-newsletter-insurance --dry-run
+
+# Custom news query
+optimal generate-newsletter-insurance --news-query "florida insurance market rates"
+```
+
+## Environment
+Requires: `GROQ_API_KEY`, `NEWSAPI_KEY`, `STRAPI_URL`, `STRAPI_API_TOKEN`
+Optional: `GROQ_MODEL` (default: llama-3.3-70b-versatile), `LIFEINSUR_NEWSAPI_QUERY`
+
+## Gotchas
+- **No properties**: Unlike CRE-11TRUST, LIFEINSUR newsletters do not include property listings. The `--excel` parameter is not available.
+- **Slug uniqueness**: Slugs include a timestamp (YYYYMMDDTHHMMSS) to avoid conflicts on same-day reruns.
+- **Brand palette**: Primary #44403E (warm charcoal), Accent #AD7C59 (terracotta), BG #FCF9F6 (warm beige).
+- **Preview site**: Published newsletters render at https://newsletter.op-hub.com/lifeinsur
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/newsletter/generate-insurance.ts` to be ported from `generate-newsletter-lifeinsur.py` in the newsletter-automation repo.

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

@@ -0,0 +1,67 @@
+---
+name: generate-social-posts
+description: Analyze competitor ads, generate 9 branded social posts with AI copy and Unsplash photos
+---
+
+## Purpose
+End-to-end social media post generation pipeline. Scrapes competitor ads from Meta Ad Library for pattern analysis, generates 9 themed social posts with AI-written copy, sources stock photography from Unsplash, and pushes drafts to Strapi CMS. This is a weekly workflow — typically run as "Generate 9 new social posts for [BRAND] for the week of [DATE]".
+
+## Inputs
+- **brand** (required): Brand key — `CRE-11TRUST` or `LIFEINSUR`
+- **week** (required): Week start date as YYYY-MM-DD (e.g., `2026-03-03` for the week of March 3rd)
+- **competitors** (optional): Comma-separated competitor names or path to file. Default: uses the brand's standard competitor list.
+- **count** (optional): Number of posts to generate. Default: `9`.
+- **dry-run** (optional): Generate content but do NOT push to Strapi.
+
+## Steps
+1. Call `lib/social/post-generator.ts::generateSocialPosts(brand, week, options?)` to orchestrate the full pipeline
+2. **Scrape competitor ads** — run `lib/social/scraper.ts::scrapeAds(competitors)` against the brand's competitor list (3 parallel batches of 6 companies)
+3. **Analyze ad patterns** — extract common themes, CTAs, platforms, and copy structures from scraped data
+4. **Generate post copy** — send analysis to Groq AI to generate 9 posts with: headline, body, cta_text, cta_url, platform targeting, overlay_style, and scheduling (spread across the week)
+5. **Source photos** — for each post theme, search Unsplash via `unsplash.com/napi/search/photos?query=X&per_page=3` and select the best match
+6. **Build Strapi payloads** — create `social-post` entries with all fields: brand, headline, body, cta_text, cta_url, image_url, overlay_style, template, scheduled_date, competitor_ref, platform, delivery_status=pending
+7. **Push to Strapi** — `strapiPost('/api/social-posts', data)` for each post (skipped in dry-run mode)
+8. Log execution via `lib/kanban.ts::logSkillExecution()`
+
+## Output
+```
+Brand: LIFEINSUR (Anchor Point Insurance Co.)
+Competitors scraped: 18 companies, 1,382 ads analyzed
+Posts generated: 9
+
+| # | Platform | Headline | Scheduled | Overlay |
+|---|----------|----------|-----------|---------|
+| 1 | instagram | "Protect What Matters Most" | Mon 3/3 | dark-bottom |
+| 2 | facebook | "Your Family's Future..." | Mon 3/3 | brand-bottom |
+| 3 | instagram | "Life Insurance Myths..." | Tue 3/4 | brand-full |
+| ... | ... | ... | ... | ... |
+
+Pushed 9 drafts to Strapi.
+```
+
+## CLI Usage
+```bash
+# Generate 9 posts for Anchor Point Insurance
+optimal generate-social-posts --brand LIFEINSUR --week 2026-03-03
+
+# CRE brand with custom competitors
+optimal generate-social-posts --brand CRE-11TRUST --week 2026-03-03 --competitors "CBRE,JLL,Cushman"
+
+# Dry run, custom count
+optimal generate-social-posts --brand LIFEINSUR --week 2026-03-03 --count 6 --dry-run
+```
+
+## Environment
+Requires: `GROQ_API_KEY`, `STRAPI_URL`, `STRAPI_API_TOKEN`, `playwright` (for ad scraping)
+Optional: `GROQ_MODEL` (default: llama-3.3-70b-versatile)
+
+## Gotchas
+- **Unsplash API**: Use `unsplash.com/napi/search/photos` (public search is bot-blocked by Anubis challenge page).
+- **Scraper batches**: Run in 3 parallel batches of 6 companies each for optimal throughput.
+- **Overlay styles**: `dark-bottom`, `brand-bottom`, `brand-full`, `dark-full` — choose based on image content.
+- **Platform targeting**: Posts should be spread across instagram, facebook, linkedin based on brand's platform mix.
+- **Scheduled dates**: Spread posts across the week (e.g., 2 Mon, 2 Tue, 2 Wed, 2 Thu, 1 Fri).
+- **Playwright browser**: Requires one-time `npx playwright install chromium`.
+
+## Status
+Implementation status: Not yet implemented. Spec only. Lib function `lib/social/post-generator.ts` to be built as a multi-step orchestrator calling existing scraper and CMS functions.

package/skills/health-check/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: health-check
+description: Run the health check script across all Optimal services
+---
+
+## Purpose
+Run the workstation health check script to verify the status of all Optimal services, Docker containers, and Git repositories.
+
+## Inputs
+None.
+
+## Steps
+1. Execute `/home/optimal/scripts/health-check.sh` via `lib/infra/deploy.ts::healthCheck()`
+2. Script checks each service (timeout: 30 seconds total):
+   - **n8n**: Process running check (`pgrep`)
+   - **Affine**: Docker container status + HTTP check against `https://affine.op-hub.com`
+   - **Strapi CMS**: systemd user service status + HTTP health endpoint on `127.0.0.1:1337/_health`
+   - **Git Repositories**: Fetch latest, report uncommitted changes / unpushed commits / behind remote
+   - **Docker**: systemd service status + active container count
+   - **OptimalOS**: HTTP check on `localhost:3001`
+3. Return the full formatted output
+
+## Output
+Formatted status report with per-service check/warn/fail indicators:
+
+```
+Health Check - 2026-03-01 10:00:00
+▸ n8n           -> running on port 5678
+▸ Affine        -> running at https://affine.op-hub.com
+▸ Strapi CMS    -> running at https://strapi.op-hub.com
+▸ Git Repos     -> per-repo sync status
+▸ Docker        -> N containers active
+▸ OptimalOS     -> dev server on port 3001 (optional)
+```
+
+## Usage
+```bash
+optimal health-check
+```
+
+## Environment
+Requires: bash, curl, git, docker, systemctl. The script at `/home/optimal/scripts/health-check.sh` must exist.

package/skills/ingest-transactions/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ingest-transactions
+description: Parse & deduplicate bank CSV files into the OptimalOS transactions table
+---
+
+## Purpose
+Reads a bank-exported CSV from disk, auto-detects the bank format (Chase Checking, Chase Credit, Discover, or Generic), parses rows into normalized transactions, deduplicates against existing data using SHA-256 hashes, and batch-inserts new records into the `transactions` table on the OptimalOS Supabase instance.
+
+## Inputs
+- **file** (required): Absolute path to the CSV file on disk
+- **user-id** (required): Supabase user UUID to own the imported transactions
+
+## Supported Formats
+| Format | Detection | Sign Convention |
+|--------|-----------|-----------------|
+| Chase Checking | `Details, Posting Date, Description, Amount, Type, Balance` | Negative = expense |
+| Chase Credit | `Transaction Date, Post Date, Description, Category, Type, Amount` | Negative = expense |
+| Discover | `Trans. Date, Post Date, Description, Amount, Category` | Positive = charge (flipped) |
+| Generic CSV | Any CSV with `date`, `description`, `amount` columns | As-is |
+
+Amex XLSX is not yet supported in the CLI (use the OptimalOS web UI).
+
+## Steps
+1. Read the CSV file from `--file` path
+2. Auto-detect bank format from header row
+3. Parse rows using format-specific normalizer (handles quoted fields, date formats, amounts with $, parentheses, commas)
+4. Generate SHA-256 dedup hash for each row: `sha256(date|amount|normalizedDescription)[0:32]`
+5. Query `transactions.dedup_hash` to find existing duplicates
+6. Create an `upload_batches` record for provenance tracking
+7. Resolve category names to `categories.id` (create if missing)
+8. Batch-insert new rows (50 per batch)
+
+## Output
+```
+Format detected: chase_credit (confidence: 1.0)
+Parsed 247 transactions
+Inserted: 231  |  Skipped (duplicates): 16  |  Failed: 0
+```
+
+## CLI Usage
+```bash
+tsx bin/optimal.ts ingest-transactions --file ~/Downloads/chase-statement.csv --user-id <uuid>
+```
+
+## Environment
+Requires: `OPTIMAL_SUPABASE_URL`, `OPTIMAL_SUPABASE_SERVICE_KEY`
+
+## Tables Touched
+- `transactions` — insert new rows
+- `upload_batches` — provenance record
+- `categories` — resolve or create category mappings

package/skills/manage-cms/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: manage-cms
+description: Create, update, list, publish, and delete content in Strapi CMS across all brands
+---
+
+## Purpose
+Full content lifecycle management for Strapi v5 CMS. Handles newsletters, social posts, and blog posts across multiple brands (CRE-11TRUST, LIFEINSUR). Used by the newsletter pipeline, social post pipeline, and portfolio blog publishing.
+
+## Inputs
+- **action** (required): One of `list`, `get`, `create`, `update`, `delete`, `publish`, `unpublish`, `upload`
+- **contentType** (required): Strapi plural name — `newsletters`, `social-posts`, or `blog-posts`
+- **brand** (optional): Brand filter — `CRE-11TRUST` or `LIFEINSUR`
+- **documentId** (required for update/delete/publish/unpublish): Strapi v5 documentId (UUID string, NOT numeric id)
+- **slug** (optional for get): Look up item by slug instead of documentId
+- **data** (required for create/update): Field values as key-value pairs
+- **status** (optional for list): `draft` or `published` — filters by Strapi draftAndPublish status
+- **filePath** (required for upload): Absolute path to file for upload
+- **refData** (optional for upload): `{ ref, refId, field }` to link upload to an entry
+
+## Steps
+1. Determine action and validate required inputs
+2. Call the appropriate function from `lib/cms/strapi-client.ts`:
+   - **list**: `listByBrand(contentType, brand, status?)` or `strapiGet('/api/{contentType}', params)`
+   - **get**: `findBySlug(contentType, slug)` or `strapiGet('/api/{contentType}/{documentId}')`
+   - **create**: `strapiPost('/api/{contentType}', data)` — include `brand` in data
+   - **update**: `strapiPut('/api/{contentType}', documentId, data)` — uses documentId, NOT numeric id
+   - **delete**: `strapiDelete('/api/{contentType}', documentId)`
+   - **publish**: `publish(contentType, documentId)` — sets publishedAt
+   - **unpublish**: `unpublish(contentType, documentId)` — clears publishedAt
+   - **upload**: `strapiUploadFile(filePath, refData?)`
+3. Return the result with documentId, title/headline, and status
+
+## Output
+- **list**: Count and table of items with documentId, title, brand, status, updatedAt
+- **get**: Full item fields
+- **create**: `Created {contentType}: {documentId} — "{title}"`
+- **update**: `Updated {contentType}: {documentId}`
+- **delete**: `Deleted {contentType}: {documentId}`
+- **publish/unpublish**: `Published/Unpublished {contentType}: {documentId}`
+- **upload**: Uploaded file URL(s)
+
+## Environment
+Requires: `STRAPI_URL`, `STRAPI_API_TOKEN`
+
+## Gotchas
+- **documentId, not id**: Strapi v5 PUT/DELETE use documentId (UUID string). The numeric `id` field exists but should not be used for mutations.
+- **Reserved fields**: Never use `status`, `published_at`, `locale`, or `meta` as custom field names — Strapi v5 reserves them.
+- **Slug uniqueness**: Include a timestamp in slugs for same-day reruns to avoid conflicts.
+- **draftAndPublish**: Drafts are created by default. Explicitly call `publish` to make content live.
+- **Rate limits**: Strapi admin login rate-limits aggressively (5 attempts then 429). The API token does not have this issue.