optimal-cli 1.0.1 → 1.1.0

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.

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.