claude-code-arcane 1.0.0

package/skills/feature-flags/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: feature-flags
+description: "Feature flag strategy: types, provider selection, lifecycle, naming, rollout, cleanup"
+category: "operations"
+argument-hint: "[setup|audit|cleanup]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# feature-flags — Feature Flags & Rollouts
+
+Separate deploy from release. Enable gradual rollouts, kill switches, and experiments.
+
+## When to use
+
+- Risky feature needing rollback safety
+- Gradual rollout (1% -> 10% -> 50% -> 100%)
+- Kill switch for incident response
+- A/B experiments with segments
+- Dark launches (code in prod, not visible)
+
+## When NOT to use
+
+- Runtime config (use env vars / ConfigMap)
+- Permissions / RBAC (use auth system)
+- Permanent per-user personalization (not a flag)
+
+---
+
+## Flag types
+
+| Type | Purpose | Lifetime | Example |
+|------|---------|----------|---------|
+| **Release** | Separate deploy from release | Days-weeks | `dashboard-new-layout` |
+| **Experiment** | A/B test | Weeks | `exp-onboarding-v2` |
+| **Ops** | Kill switch / circuit breaker | Months-permanent | `ops-disable-heavy-query` |
+| **Permission** | Entitlements by plan/role | Permanent | `feature-x-pro-plan` |
+
+Release flags MUST have an expiration date. Ops flags may be permanent.
+
+## Provider selection
+
+| Provider | When to use |
+|----------|-------------|
+| **GrowthBook** | Default — open source, self-hosted, A/B integrated |
+| **Unleash** | Mature OSS alternative, strong multi-language SDK |
+| **LaunchDarkly** | SaaS, best UX, budget available, no self-host desire |
+| **Env vars / DB row** | AVOID — reinvents the wheel, no audit trail |
+
+## Naming convention
+
+- kebab-case: `<area>-<what>[-<version>]`
+- Prefix by type: `exp-` (experiment), `ops-` (ops), no prefix for release
+- Include domain area, avoid ambiguous names like `test` or `new-feature`
+
+## Evaluation patterns
+
+- **Backend:** server-side eval, resolved before response
+- **Frontend:** hydrate from backend or SDK with local cache
+- **Mobile:** local cache + refresh on foreground, fallback to defaults offline
+
+## Targeting & rollout
+
+- Gradual: 0% -> 1% (canary) -> 5% -> 25% -> 50% -> 100%, 24-48h between steps
+- Cohort: plan, country, creation date, internal emails (dogfooding)
+- Sticky hashing on userId for consistent UX
+- Kill switch: flag always ON, turn OFF during incidents
+
+## Lifecycle management
+
+Every flag at creation MUST have:
+- **Owner** (person responsible)
+- **Type** (release / experiment / ops / permission)
+- **Expiration** (release: 30-60d; experiment: end of test; ops: permanent)
+- **Cleanup ticket** linked in tracker
+
+### Cleanup process
+1. Detect stale flags (100% ON or OFF for >30 days)
+2. Remove SDK calls, keep winning branch only
+3. Delete dead code from losing branch
+4. Archive flag in provider (preserve audit trail)
+
+## Checklist
+
+- [ ] SDK client keys (read-only) in client, admin API keys server-only
+- [ ] Sensitive flags (billing, permissions) evaluated server-side only
+- [ ] Audit logging enabled on flag changes
+- [ ] Admin console requires 2FA
+
+## Anti-patterns
+
+- Flag without owner/expiration — becomes permanent zombie
+- Evaluating flag on every code line — evaluate once per request, pass result
+- Using flags for runtime config — use env vars
+- Complex targeting with sensitive data on client — move server-side
+- Deleting flag without code cleanup — dead branch forever
+- Flag without success metric — cannot measure impact
+- Multiple interacting flags without documented matrix — combinatorial bugs
+- Rollout 0->100% directly — defeats the purpose of gradual rollout

package/skills/figma/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: figma
+description: "Figma manager: inspect designs, export assets, extract styles/components via MCP or REST API."
+category: "design"
+argument-hint: "[inspect|export|tokens] [node-id or url]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+# Figma Manager
+
+Integra con Figma via MCP nativo o REST API.
+
+## Vía MCP
+
+Tools: `mcp__figma__authenticate`, `mcp__figma__complete_authentication`
+Una vez autenticado, MCP expone operations. Revisá `mcp__figma__*` en contexto.
+
+## Vía REST API
+
+```bash
+curl "https://api.figma.com/v1/files/$FILE_KEY" \
+  -H "X-Figma-Token: $FIGMA_TOKEN"
+```
+
+Obtener FILE_KEY del URL: `https://www.figma.com/file/<FILE_KEY>/name?node-id=123-456`
+Node IDs en URL están con `-`, en API usar `:` (ej: `123:456`).
+
+## Operaciones Clave
+
+### File tree completo
+```bash
+GET /v1/files/$FILE_KEY
+```
+Devuelve estructura completa (puede ser huge).
+
+### Nodos específicos
+```bash
+GET /v1/files/$FILE_KEY/nodes?ids=123:456,789:012
+```
+Mucho más eficiente que todo el file.
+
+### Exportar imágenes
+```bash
+GET /v1/files/$FILE_KEY/images?ids=123:456&format=svg&scale=1
+```
+Formats: `png`, `jpg`, `svg`, `pdf`
+Scale: 1-4 (para PNG)
+
+Response tiene URLs temporales (expiran en ~1h). Descargar inmediatamente.
+
+### Styles globales
+```bash
+GET /v1/files/$FILE_KEY/styles
+```
+Colores, text styles, effects, grids publicados en el file.
+
+### Components publicados
+```bash
+GET /v1/files/$FILE_KEY/components
+GET /v1/files/$FILE_KEY/component_sets
+```
+
+### Variables (design tokens)
+```bash
+GET /v1/files/$FILE_KEY/variables/local
+```
+Figma Variables = design tokens nativos (primitives, aliases, modes).
+
+## Comandos
+
+### Inspect frame
+```
+/figma inspect <figma_url>
+```
+
+Flujo:
+1. Parsear URL → file_key + node_id
+2. GET nodos → estructura
+3. Extraer:
+   - Dimensions (w × h)
+   - Position (x, y)
+   - Fills, strokes, effects
+   - Text properties (font, size, weight, color, alignment)
+   - Auto-layout rules
+   - Children hierarchy
+4. Output estructurado
+
+### Export assets
+```
+/figma export <figma_url> [--format svg|png] [--scale 2]
+```
+
+Para bulk (todos los frames con prefix "icon/"):
+1. Buscar nodos matching pattern
+2. Bulk export
+3. Descargar a `assets/icons/`
+4. Nombrar kebab-case desde el node name
+
+### Extract tokens
+```
+/figma tokens <figma_url> [--output css|tailwind|json]
+```
+
+Ver `/figma-tokens` para detalle completo.
+
+### Component spec
+```
+/figma component <figma_url>
+```
+
+Genera spec completo del component:
+- Variants (property variants)
+- States (default, hover, active, disabled)
+- Tokens usados
+- Anatomy con measurements
+- Props/API sugeridos
+
+## Reglas
+
+- **Rate limit**: 2 req/s por token (strict)
+- **Response size**: archivos grandes pueden dar 30MB+ de JSON — usar `/nodes?ids=` selectivo
+- **URLs exportadas expiran**: descargar inmediatamente después del GET
+- **Plugin API vs REST API**: REST es read-only. Plugins (JavaScript en Figma) pueden modificar.
+- **Tokens vs Styles**: si el file usa Figma Variables, usar esos. Si no, fallback a Styles.

package/skills/figma-to-code/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: figma-to-code
+description: "Convert Figma designs to production-ready code adapted to the project stack. Detects existing components and design tokens."
+category: "design"
+argument-hint: "[figma-url or node-id]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# Figma to Code
+
+Convierte diseños de Figma en código adaptado al stack del proyecto actual.
+
+## Input
+
+El usuario proporciona:
+1. **URL de Figma** (obligatorio) — `figma.com/design/{fileKey}/{fileName}?node-id={nodeId}`
+2. **Qué implementar** (opcional) — componente específico, pantalla, sección
+3. **Stack override** (opcional) — si quiere algo distinto al stack del proyecto
+
+## Process
+
+### 1. Parsear URL y obtener diseño
+
+Extraer `fileKey` y `nodeId` de la URL:
+- `figma.com/design/:fileKey/:fileName?node-id=:nodeId` → convertir `-` a `:` en nodeId
+- `figma.com/design/:fileKey/branch/:branchKey/:fileName` → usar branchKey como fileKey
+
+Llamar a `get_design_context` con fileKey y nodeId para obtener:
+- Código de referencia (React+Tailwind por default)
+- Screenshot del diseño
+- Hints contextuales (Code Connect, tokens, annotations)
+
+### 2. Detectar stack del proyecto
+
+Detectar framework (Next.js, React, Vue, Svelte, Flutter, SwiftUI, RN) y UI library (shadcn, MUI, Chakra, Tailwind, Styled Components) del proyecto.
+
+> → Read references/stack-detection.md for detection tables and adaptation rules
+
+### 3. Buscar componentes existentes
+
+Antes de generar código nuevo, buscar en el proyecto:
+- Componentes UI reutilizables que matcheen con el diseño
+- Tokens de diseño (colores, spacing, typography) ya definidos
+- Patrones de layout existentes
+
+```bash
+# Buscar componentes UI
+find src/components -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" 2>/dev/null
+```
+
+### 4. Adaptar código al stack
+
+El output de `get_design_context` es React+Tailwind de referencia. Adaptar al stack detectado (shadcn, CSS Modules, Styled Components, Vue, Svelte, Flutter).
+
+> → Read references/stack-detection.md for stack adaptation mapping table
+
+### 5. Generar código
+
+Para cada componente/pantalla:
+
+1. **Crear archivo(s)** siguiendo la convención del proyecto
+2. **Reutilizar** componentes existentes donde sea posible
+3. **Mapear** colores/fonts a tokens del proyecto
+4. **Responsive** — si el diseño tiene breakpoints, implementarlos
+5. **Accesibilidad** — aria labels, semantic HTML, keyboard nav
+6. **Estados** — hover, active, disabled, loading, empty, error
+
+### 6. Checklist post-generación & Output
+
+> → Read references/checklist-and-output.md for 7-item quality checklist and output template format
+
+## Rules
+- SIEMPRE leer el diseño de Figma antes de generar código
+- NUNCA generar código sin antes buscar componentes existentes en el proyecto
+- Preferir reutilización sobre creación nueva
+- Si el diseño usa componentes que no existen → crearlos siguiendo el design system
+- Responsive por default
+- Accesibilidad por default
+- No generar archivos de test para componentes UI (a menos que se pida)
+- En español para comentarios, en inglés para código

package/skills/figma-to-code/references/checklist-and-output.md

@@ -0,0 +1,32 @@
+# Checklist & Output Template
+
+## Checklist post-generacion
+
+- [ ] Usa componentes existentes del proyecto (no reinventa)
+- [ ] Tokens de color mapeados a variables del proyecto
+- [ ] Typography consistente con el design system
+- [ ] Responsive en los breakpoints del proyecto
+- [ ] Sin valores hardcodeados (usa tokens/variables)
+- [ ] Accesible (semantic HTML, aria labels)
+- [ ] Estados de interaccion implementados
+
+## Output Template
+
+```markdown
+## Componentes generados
+
+| Archivo | Qué es | Componentes reutilizados |
+|---------|--------|------------------------|
+| `src/components/FeatureName.tsx` | Componente principal | Button, Card |
+
+## Tokens mapeados
+| Figma | Proyecto |
+|-------|---------|
+| #3B82F6 | `--color-primary` / `text-blue-500` |
+
+## Decisiones tomadas
+- [Decisión 1: por qué se usó X en vez de Y]
+
+## TODOs
+- [ ] [Algo que necesita input del diseñador/usuario]
+```

package/skills/figma-to-code/references/stack-detection.md

@@ -0,0 +1,34 @@
+# Stack Detection Tables
+
+## Framework Detection
+
+| Archivo | Stack |
+|---------|-------|
+| `package.json` con `next` | Next.js |
+| `package.json` con `react` | React |
+| `package.json` con `vue` | Vue |
+| `package.json` con `svelte` | Svelte |
+| `pubspec.yaml` | Flutter |
+| `*.swift` + `Package.swift` | SwiftUI |
+| `package.json` con `react-native` | React Native |
+
+## UI Library Detection
+
+| Indicador | Library |
+|-----------|---------|
+| `@shadcn/ui` o `components/ui/` | shadcn/ui |
+| `@mui/material` | Material UI |
+| `@chakra-ui` | Chakra UI |
+| `tailwindcss` | Tailwind CSS |
+| `styled-components` | Styled Components |
+
+## Stack Adaptation
+
+| Si el proyecto usa | Adaptar a |
+|--------------------|-----------|
+| shadcn/ui | Usar `<Button>`, `<Card>`, `<Input>` etc. del proyecto |
+| CSS Modules | Convertir Tailwind a CSS Modules |
+| Styled Components | Convertir a styled() |
+| Vue | Convertir JSX a `<template>` + `<script setup>` |
+| Svelte | Convertir a `.svelte` components |
+| Flutter | Convertir a Widgets |

package/skills/figma-tokens/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: figma-tokens
+description: "Extract Figma design tokens and generate consumable formats: CSS variables, Tailwind config, JSON, Style Dictionary, Swift, Flutter."
+category: "design"
+argument-hint: "[output-format: css|tailwind|json|style-dict]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+# Figma Tokens → Code
+
+Extrae tokens desde Figma y los convierte a formatos usables por el stack.
+
+## Fuentes en Figma
+
+| Fuente | API | Notas |
+|--------|-----|-------|
+| **Variables** (moderna, preferida) | `GET /v1/files/$KEY/variables/local` | Primitives, aliases, modes (light/dark) |
+| **Styles** (legacy) | `GET /v1/files/$KEY/styles` | Color, text, effect styles |
+
+## Token Categories
+
+| Category | Structure |
+|----------|-----------|
+| **Colors** | Nested by scale: `color.primary.500: "#3B82F6"` |
+| **Typography** | Composite: fontFamily, fontWeight, fontSize, lineHeight, letterSpacing |
+| **Spacing** | Scale: `1: 4px, 2: 8px, 3: 12px, 4: 16px, 6: 24px, 8: 32px` |
+| **Border radius** | `sm: 4px, md: 8px, lg: 12px, full: 9999px` |
+| **Shadows** | CSS shadow strings: `0 4px 6px rgba(0,0,0,0.1)` |
+
+## Output Formats
+
+| Format | Target | Naming |
+|--------|--------|--------|
+| **CSS Variables** | `:root { --color-primary-500: ... }` + `[data-theme="dark"]` | kebab-case |
+| **Tailwind Config** | `theme.extend.colors/spacing/borderRadius/boxShadow` | nested dot |
+| **Style Dictionary** | Multi-platform (iOS Swift, Android XML, Web CSS) | per-platform |
+| **SwiftUI** | `extension Color { static let primary500 = ... }` | camelCase |
+| **Flutter (Dart)** | `class AppColors { static const primary500 = Color(0xFF...) }` | camelCase |
+
+## Comando
+
+`/figma-tokens <figma_url> [--output css|tailwind|json|style-dictionary|swift|flutter]`
+
+Flujo: pedir formato (default: Tailwind web, JSON multi-platform) → extraer variables → categorizar → generar output → preguntar ubicación (Next.js→`tailwind.config.ts`, Vue→`src/styles/tokens.css`, Swift→`Sources/DesignSystem/Tokens.swift`, Flutter→`lib/design/tokens.dart`).
+
+## Naming Conventions
+
+Figma `Primary/500` → `primary-500`. Convertir: CSS kebab-case (`--color-primary-500`), Tailwind nested (`primary.500`), Swift camelCase (`primary500`).
+
+## Reglas
+
+- Preservar modes (light/dark) si existen en Figma
+- Aliases semánticos > primitives: exportar ambos, priorizar aliases en uso
+- Validar coherencia: alias sin valor → flaggear
+- Versionar tokens: git commit cada regeneración

package/skills/file-uploads/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: file-uploads
+description: "File upload decision guide: signed URLs, validation, storage, virus scanning, image processing, UX. Use for: upload, file storage, attachment, avatar, image, document, GCS, S3, presigned."
+category: "backend"
+argument-hint: "[stack: go|ts|react|rn]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# file-uploads — Decision Guide
+
+Default storage: **GCS**. Logic identical for S3/R2 — adapt provider SDK.
+
+## Upload Strategy Decision
+
+| Strategy | When | Trade-off |
+|---|---|---|
+| **Signed URL (direct)** | Default for all uploads | Backend never touches bytes; scales trivially |
+| **Server proxy** | <100KB parsed inline (small CSV) | Simple but consumes backend RAM; no scale |
+| **Resumable/multipart** | >100MB (videos, datasets) | 8-32MB chunks; resume on failure |
+| **tus protocol** | Vendor-neutral resumable | Requires tusd server |
+
+## Signed URL Flow
+
+```
+Client → POST /uploads/sign → Backend (validate, create pending row, return signed URL)
+Client → PUT bytes → Storage (uploads-pending/)
+Storage → Event (Pub/Sub) → Worker (MIME sniff + virus scan)
+Worker → if clean: move to uploads-clean/, update DB status
+```
+
+Key decisions:
+- Backend **never touches bytes** — only signs and tracks
+- **Two buckets**: uploads-pending (quarantine) + uploads-clean (served)
+- Key is **UUID**, never client filename (PII, collisions, path traversal)
+- Signed URL expiry: **<=15min**; include content-length constraint in signature
+- Multi-tenant: `t/{tenant}/u/{user}/{uuid}` key path
+
+## Checklist
+
+| Check | Where | Detail |
+|---|---|---|
+| MIME whitelist | Sign + Worker (sniff) | Whitelist only; sniff first 512 bytes server-side |
+| Size limit | Sign + URL constraint | Enforce per use case (10MB avatar, 100MB doc) |
+| Virus scan | Worker (async) | ClamAV / Cloudmersive / VirusTotal; never serve status != clean |
+| Content-Type match | Worker | Sniffed vs declared; reject on mismatch |
+| Checksum | Worker (post-scan) | SHA-256 stored for integrity |
+
+Never trust client Content-Type or file extension alone.
+
+## Storage Decision
+
+| Provider | When | Notes |
+|---|---|---|
+| **GCS** | Default (GCP) | V4 signed URLs, Pub/Sub, Cloud CDN |
+| **S3** | AWS stack | Presigned URLs, EventBridge, CloudFront |
+| **R2** | Egress-sensitive | S3-compatible, zero egress fees |
+
+## Image Processing
+
+- **On upload** (worker): predictable sizes — avatars, thumbnails
+- **On demand** (CDN): many sizes — Cloudflare Images or imgproxy
+- Always WebP/AVIF for delivery; generate thumbnails async, never in request
+
+## Status Machine
+
+`pending` → `scanning` → `clean` | `infected` (deleted) | `rejected` (deleted)
+
+DB columns: id, owner_id, tenant_id, bucket, key, mime, size, checksum_sha256, status, scanned_at, created_at.
+
+## UX Patterns
+
+- Progress (web): XHR `upload.onprogress` — fetch lacks upload progress
+- Progress (RN): expo-file-system `uploadAsync`
+- >100MB: switch to resumable with per-chunk retry + exponential backoff
+- Show placeholder until `status=clean`; poll or WebSocket for completion
+
+## Anti-patterns
+
+- Proxying bytes through backend — wastes RAM, crashes pods
+- Trusting extension or client Content-Type without server sniff
+- Client filename as key — PII, collisions, traversal
+- Serving pending/scanning files; sync virus scan in request
+- Signed URLs >15min; no size limit; any-MIME allowed
+- Public buckets; missing CORS; no rate limit on /uploads/sign
+
+## Checklist
+
+- [ ] Signed URL <=15min; content-length in signature
+- [ ] MIME whitelist at sign AND worker (real sniff)
+- [ ] UUID key, never client filename
+- [ ] Separate pending/clean buckets; virus scan before serving
+- [ ] DB status machine (pending→scanning→clean)
+- [ ] SHA-256 checksum post-scan; CORS on bucket
+- [ ] Rate limit on /uploads/sign; tenant_id in path
+- [ ] Thumbnails async; CDN for clean files; structured logs

package/skills/financial-analyst/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: financial-analyst
+description: "Financial ratio analysis, DCF valuation, budget variance analysis, and rolling forecast construction for strategic decision-making."
+argument-hint: ""
+category: "finance"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Financial Analyst
+
+## Overview
+
+Production-ready financial analysis toolkit providing ratio analysis, DCF valuation, budget variance analysis, and rolling forecast construction. Designed for financial modeling, forecasting & budgeting, management reporting, business performance analysis, and investment analysis.
+
+## 5-Phase Workflow
+
+### Phase 1: Scoping
+- Define analysis objectives and stakeholder requirements
+- Identify data sources and time periods
+- Establish materiality thresholds and accuracy targets
+- Select appropriate analytical frameworks
+
+### Phase 2: Data Analysis & Modeling
+- Collect and validate financial data (income statement, balance sheet, cash flow)
+- **Validate input data completeness** before running ratio calculations (check for missing fields, nulls, or implausible values)
+- Calculate financial ratios across 5 categories (profitability, liquidity, leverage, efficiency, valuation)
+- Build DCF models with WACC and terminal value calculations; **cross-check DCF outputs against sanity bounds** (e.g., implied multiples vs. comparables)
+- Construct budget variance analyses with favorable/unfavorable classification
+- Develop driver-based forecasts with scenario modeling
+
+### Phase 3: Insight Generation
+- Interpret ratio trends and benchmark against industry standards
+- Identify material variances and root causes
+- Assess valuation ranges through sensitivity analysis
+- Evaluate forecast scenarios (base/bull/bear) for decision support
+
+### Phase 4: Reporting
+- Generate executive summaries with key findings
+- Produce detailed variance reports by department and category
+- Deliver DCF valuation reports with sensitivity tables
+- Present rolling forecasts with trend analysis
+
+### Phase 5: Follow-up
+- Track forecast accuracy (target: +/-5% revenue, +/-3% expenses)
+- Monitor report delivery timeliness (target: 100% on time)
+- Update models with actuals as they become available
+- Refine assumptions based on variance analysis
+
+## Tools
+
+### 1. Ratio Calculator (`scripts/ratio_calculator.py`)
+
+Calculate and interpret financial ratios from financial statement data.
+
+**Ratio Categories:**
+- **Profitability:** ROE, ROA, Gross Margin, Operating Margin, Net Margin
+- **Liquidity:** Current Ratio, Quick Ratio, Cash Ratio
+- **Leverage:** Debt-to-Equity, Interest Coverage, DSCR
+- **Efficiency:** Asset Turnover, Inventory Turnover, Receivables Turnover, DSO
+- **Valuation:** P/E, P/B, P/S, EV/EBITDA, PEG Ratio
+
+```bash
+python scripts/ratio_calculator.py sample_financial_data.json
+python scripts/ratio_calculator.py sample_financial_data.json --format json
+python scripts/ratio_calculator.py sample_financial_data.json --category profitability
+```
+
+### 2. DCF Valuation (`scripts/dcf_valuation.py`)
+
+Discounted Cash Flow enterprise and equity valuation with sensitivity analysis.
+
+**Features:**
+- WACC calculation via CAPM
+- Revenue and free cash flow projections (5-year default)
+- Terminal value via perpetuity growth and exit multiple methods
+- Enterprise value and equity value derivation
+- Two-way sensitivity analysis (discount rate vs growth rate)
+
+```bash
+python scripts/dcf_valuation.py valuation_data.json
+python scripts/dcf_valuation.py valuation_data.json --format json
+python scripts/dcf_valuation.py valuation_data.json --projection-years 7
+```
+
+### 3. Budget Variance Analyzer (`scripts/budget_variance_analyzer.py`)
+
+Analyze actual vs budget vs prior year performance with materiality filtering.
+
+**Features:**
+- Dollar and percentage variance calculation
+- Materiality threshold filtering (default: 10% or $50K)
+- Favorable/unfavorable classification with revenue/expense logic
+- Department and category breakdown
+- Executive summary generation
+
+```bash
+python scripts/budget_variance_analyzer.py budget_data.json
+python scripts/budget_variance_analyzer.py budget_data.json --format json
+python scripts/budget_variance_analyzer.py budget_data.json --threshold-pct 5 --threshold-amt 25000
+```
+
+### 4. Forecast Builder (`scripts/forecast_builder.py`)
+
+Driver-based revenue forecasting with rolling cash flow projection and scenario modeling.
+
+**Features:**
+- Driver-based revenue forecast model
+- 13-week rolling cash flow projection
+- Scenario modeling (base/bull/bear cases)
+- Trend analysis using simple linear regression (standard library)
+
+```bash
+python scripts/forecast_builder.py forecast_data.json
+python scripts/forecast_builder.py forecast_data.json --format json
+python scripts/forecast_builder.py forecast_data.json --scenarios base,bull,bear
+```
+
+## Knowledge Bases
+
+| Reference | Purpose |
+|-----------|---------|
+| `references/financial-ratios-guide.md` | Ratio formulas, interpretation, industry benchmarks |
+| `references/valuation-methodology.md` | DCF methodology, WACC, terminal value, comps |
+| `references/forecasting-best-practices.md` | Driver-based forecasting, rolling forecasts, accuracy |
+| `references/industry-adaptations.md` | Sector-specific metrics and considerations (SaaS, Retail, Manufacturing, Financial Services, Healthcare) |
+
+## Templates
+
+| Template | Purpose |
+|----------|---------|
+| `assets/variance_report_template.md` | Budget variance report template |
+| `assets/dcf_analysis_template.md` | DCF valuation analysis template |
+| `assets/forecast_report_template.md` | Revenue forecast report template |
+
+## Key Metrics & Targets
+
+| Metric | Target |
+|--------|--------|
+| Forecast accuracy (revenue) | +/-5% |
+| Forecast accuracy (expenses) | +/-3% |
+| Report delivery | 100% on time |
+| Model documentation | Complete for all assumptions |
+| Variance explanation | 100% of material variances |
+
+## Input Data Format
+
+All scripts accept JSON input files. See `assets/sample_financial_data.json` for the complete input schema covering all four tools.
+
+## Dependencies
+
+**None** - All scripts use Python standard library only (`math`, `statistics`, `json`, `argparse`, `datetime`). No numpy, pandas, or scipy required.