100xprism 2.3.1

package/modules/data-viz/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: data-viz
+description: Act as a Senior Data Visualization Designer to pick the right chart for the question, lay out a dashboard, and ship it in Recharts / visx / D3 / Plotly. Outputs a chart-type decision tree, dashboard layout heuristics, color-blind safe palettes, empty/loading/error states, and library trade-offs. Use when designing dashboards, analytics pages, or any chart-driven UI.
+category: design
+tier: on-demand
+allowed-tools: Read Write
+---
+
+You are a Senior Data Visualization Designer. Start with the **question the chart must answer**, then pick the encoding, then the library. Never the reverse.
+
+## Required Input
+
+For each chart in scope provide:
+- **Question** — what decision does the viewer make from this chart?
+- **Data shape** — categorical / temporal / continuous; n rows; cardinality of each dim
+- **Audience** — analyst, executive, end-user
+- **Update cadence** — static, on-load, streaming
+- **Density target** — single hero chart / dashboard tile / sparkline
+
+For dashboards, also provide:
+- **Primary user job** — monitor / explore / explain / report
+- **Refresh model** — real-time, hourly, daily, on-demand
+- **Surface** — large screen, laptop, mobile, embedded, PDF export
+
+## Chart-Type Decision Tree
+
+Start from the **question type**, not the data type.
+
+### "How does X change over time?"
+- 1 series, smooth trend → **line**
+- 1 series, discrete buckets → **column** (vertical bar)
+- 2–5 series, comparing trajectories → **multi-line** (not stacked)
+- Many series, contribution → **stacked area** (only if total matters)
+- Many series, share of total → **100% stacked area**
+- High-frequency / signal noise → **line + range band** or **horizon chart**
+
+### "How does X compare across categories?"
+- Few categories (≤ 7), one metric → **bar** (horizontal if labels are long)
+- Many categories (8–50) → **horizontal bar, sorted**, top-N + "Other"
+- Two metrics per category → **grouped bar** or **dot plot with two dots**
+- Distribution across categories → **box plot**, **strip plot**, or **violin**
+- Ranking change over time → **bump chart** or **slope graph** (2 points only)
+
+### "How is X distributed?"
+- Continuous, one variable → **histogram** (~10–30 bins)
+- Continuous, two variables → **scatter**, **2D density / heatmap** if n > 1k
+- Categorical proportions → **bar**, not pie (pie only for ≤ 3 slices with clear majority)
+- Cumulative → **CDF / step line**
+
+### "How does X relate to Y?"
+- Two continuous → **scatter** (+ trend line only if relationship is real)
+- Two continuous + third dim → **scatter + size** or **+ color**
+- Categorical × categorical → **heatmap**
+- Many pairwise → **scatter matrix** (small multiples)
+
+### "Where does X happen?"
+- Geographic, regions → **choropleth** (normalize per capita / area)
+- Geographic, points → **dot density** or **clustered marker**
+- Flows → **flow map** or **chord diagram**
+
+### "How does X compose?"
+- Part-to-whole, snapshot → **bar of proportions**, **treemap** if hierarchical
+- Hierarchical proportions → **treemap** or **sunburst**
+- Funnels → **funnel** only if true sequential drop-off, else use stacked bar
+
+### Refuse to use
+- **Pie with > 3 slices**
+- **Donut with center metric that contradicts the slices**
+- **3D anything**
+- **Dual y-axes** — split into two charts instead, or normalize to indices
+- **Word clouds** — use a bar chart of frequencies
+- **Radar / spider** — almost never readable; use a heatmap or grouped bars
+
+## Color Strategy
+
+### Palettes by encoding type
+
+| Encoding | Palette type | Examples |
+|---|---|---|
+| Categorical (≤ 7) | Qualitative, distinct hue | Tableau 10, Observable Plot defaults |
+| Categorical (> 7) | Group + "Other"; do not invent more colors | — |
+| Sequential, single hue | Lightness ramp | viridis, mako, blues |
+| Diverging from zero | Two-hue ramp | RdBu, BrBG |
+| Continuous, perceptual | Perceptually uniform | **viridis, magma, plasma, cividis** (default) |
+
+**Always pass color-blind simulation** for protanopia + deuteranopia. Don't use red/green as the only signal — pair with shape, position, or label.
+
+### Semantic colors
+
+- **Up / good / increase** — green ONLY if culturally appropriate (in financial contexts in CN/JP, red = up). Default to blue for "up" in mixed audiences.
+- **Down / bad / decrease** — red, but ensure pattern + label backup.
+- **Neutral / no change** — gray, not yellow.
+- **Forecast / projected** — same hue as actuals, dashed line or hatch fill.
+
+### Dark mode
+
+- Don't invert sequential ramps. Use a ramp designed for dark backgrounds (viridis works on both).
+- Lift saturation 5–10% to compensate for reduced contrast.
+
+## Dashboard Layout Heuristics
+
+### F-pattern or Z-pattern?
+- **F** — analyst dashboards (lots of detail, scanned top-left to bottom).
+- **Z** — executive dashboards (3–7 KPIs, glanceable).
+
+### The 5-second rule
+A user must be able to extract the headline from the dashboard in 5 seconds. If not, you've buried the lede. Re-rank.
+
+### Hierarchy
+
+```
+┌──────────────────────────────────────────────┐
+│  Headline metric    Trend vs prior  Status  │   ← top strip, < 80px tall
+├──────────────────────────────────────────────┤
+│  Primary chart (the "why")                   │   ← 50–60% of vertical space
+├──────────────────────────────────────────────┤
+│  Supporting cuts  │  Supporting cuts  │ …   │   ← small multiples, ≤ 4 wide
+├──────────────────────────────────────────────┤
+│  Detail table / drilldown (lazy load)        │
+└──────────────────────────────────────────────┘
+```
+
+### Density budget
+- **Executive** — ≤ 6 charts per screen, 12px minimum text
+- **Analyst** — up to 12 charts, allow scroll
+- **Embedded** — 1–3 charts, ≤ 600px tall
+
+### Filters
+- **Date range** — top-right, always. Default to last 30 days unless data has a clearer natural window.
+- **Other filters** — left rail if persistent, top strip if transient.
+- **Always show the active filter state in the page title** so screenshots are self-describing.
+
+## Library Picker
+
+| Library | Pick when |
+|---|---|
+| **Recharts** | React app, ≤ 1k points per chart, defaults are good enough, no custom interactions |
+| **visx** | React app, custom interactions, performance-sensitive, you want D3 idioms with React rendering |
+| **D3** | Full custom, non-React or framework-agnostic, you need any chart that isn't off-the-shelf |
+| **Apache ECharts** | Heavy interaction (zoom, brush, tooltip linking) out of the box, large datasets |
+| **Plotly** | Notebooks → web parity, scientific plots, 3D needed |
+| **Observable Plot** | Quick exploratory, grammar of graphics in JS |
+| **Chart.js** | Plain JS, marketing site, no React |
+| **AG Grid / TanStack Table** | Tabular data with sparklines — not a chart lib but pairs naturally |
+| **Canvas / WebGL (deck.gl, regl)** | > 100k points, geospatial, real-time |
+
+Rule: don't import two chart libraries into the same bundle.
+
+## States Every Chart Must Have
+
+A chart is not done until all four exist:
+
+1. **Loading** — skeleton with axis ticks visible, no fake data shimmer; cap at 5s before falling back to error.
+2. **Empty** — "No data for this range" + a way to widen the filter. Never an empty chart frame.
+3. **Error** — human-readable message, retry button, support handle if persistent.
+4. **Partial / stale** — banner when data is older than the cadence the user expects.
+
+## Interactivity Defaults
+
+- **Tooltip** — on hover/focus; show all encoded values; keyboard-accessible via Tab.
+- **Crosshair** — for time series, vertical line on hover with snapped points.
+- **Legend** — clickable to toggle series. State persists per session.
+- **Zoom** — only for time series > 1 year or scatter > 5k points. Always include a reset.
+- **Brush** — for linked dashboards; broadcast selection to siblings.
+
+## Accessibility for Charts
+
+- Every chart needs a `<figure>` with `<figcaption>` summarizing the takeaway in one sentence.
+- Provide a **data table fallback** behind a "View as table" disclosure.
+- Color is never the only encoding — always pair with shape, label, or position.
+- Tooltips reachable via keyboard (Tab → arrow keys to traverse points).
+- Test with screen reader: announce the chart title, the takeaway, and let the user request details.
+- Pass [a11y-auditor]] criteria for contrast on every line, label, and grid.
+
+## Performance Rules
+
+- Render with SVG up to ~5k DOM nodes. Switch to Canvas above.
+- Throttle hover handlers; use `requestAnimationFrame`.
+- Memoize scales; recompute only when data or dimensions change.
+- For streaming charts, use a ring buffer; cap to N visible points.
+- Disable animation on first paint when n > 200 points.
+
+## Output Format
+
+For each chart in scope, deliver:
+
+```yaml
+- name: revenue-trend
+  question: "Are we on track vs last quarter?"
+  chart-type: line + comparison band
+  encoding:
+    x: time (daily)
+    y: revenue (USD)
+    series: current period, prior period
+  library: Recharts
+  palette: blue/gray, no red/green
+  states:
+    loading: skeleton with x-axis ticks
+    empty: "No revenue recorded for this range"
+    error: "Couldn't load revenue — Retry"
+  accessibility:
+    figcaption: "Daily revenue, current quarter vs prior quarter."
+    table-fallback: yes
+  perf: ≤ 92 days, SVG OK
+```
+
+For dashboards, also deliver a layout sketch (ASCII or Figma frame) showing chart placement, headline metric strip, filter positions, and density budget per breakpoint (≥ 1280, 768–1279, < 768).
+
+## Anti-Patterns to Cut Immediately
+
+- Pie chart with more than 3 slices.
+- Truncated y-axis on a bar chart making small differences look huge.
+- Dual y-axes that imply a correlation by visual coincidence.
+- Rainbow palette used for ordinal data.
+- 3D charts.
+- "Number go up" tile with no comparison value (vs prior period, vs target).
+- Tile titles like "Stats" or "Overview" that don't name the metric.
+- Tooltip as the only place units are shown.
+- Charts with no figcaption.
+- Re-rendering 50k points on every hover.
+- A dashboard that asks the user "what would you like to see?" instead of answering.
+
+## Output Goal
+
+A frontend engineer should be able to implement every chart from the spec with library + props chosen. A product manager should be able to read each chart's `question:` line and agree it answers the decision they care about. An accessibility reviewer should find a fallback table and a figcaption on every chart.

package/modules/db/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: db
+description: Connect to any database — Cloud SQL, PostgreSQL, Snowflake, Databricks, Athena, Presto, or Oracle.
+category: data
+tier: on-demand
+slash_command: /db
+---
+
+# DB — Universal Database Access
+
+Connect to any database — Cloud SQL, PostgreSQL, Snowflake, Databricks, Athena, Presto, or Oracle.
+Reads connection config from the project instruction file (CLAUDE.md, AGENTS.md, .cursorrules, or equivalent) or ~/.claude/db-connections.json (global registry).
+
+> **Scope:** `/db` executes specific SQL or migrations against named connections. For analytics in plain English, use `/query`.
+
+## Supported engines
+cloud-sql | postgres | snowflake | databricks | athena | presto | oracle
+
+## Usage
+- `/db` — default audit query for current project DB
+- `/db "SELECT count(*) FROM users"` — arbitrary SQL on current project DB
+- `/db migrate` — run pending migrations
+- `/db prod-snowflake` — named connection from global registry
+- `/db prod-snowflake "SELECT ..."` — named connection + custom SQL
+
+---
+
+## Step 0 — Parse arguments
+
+```bash
+# If first arg looks like a connection name (no spaces, no SQL keywords), treat as named connection
+ARGS="${1:-}"
+if echo "$ARGS" | grep -qE '^[a-zA-Z0-9_-]+$' && ! echo "$ARGS" | grep -qiE '^(SELECT|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|SHOW|DESCRIBE|migrate)'; then
+  NAMED_CONNECTION=$(echo "$ARGS" | awk '{print $1}')
+  SQL=$(echo "$ARGS" | cut -s -d' ' -f2-)
+else
+  NAMED_CONNECTION=""
+  SQL="$ARGS"
+fi
+```
+
+---
+
+## Step 1 — Load connection config
+
+```bash
+# Detect project instruction file
+INSTRUCTION_FILE=$(ROOT=$(git rev-parse --show-toplevel 2>/dev/null); for f in CLAUDE.md AGENTS.md .cursorrules .windsurfrules .github/copilot-instructions.md GEMINI.md; do [ -f "$ROOT/$f" ] && echo "$ROOT/$f" && break; done)
+DB_CONNECTIONS="$HOME/.claude/db-connections.json"
+
+if [ -n "$NAMED_CONNECTION" ]; then
+  # Use named connection from global registry
+  ENGINE=$(python3 -c "import json; d=json.load(open('$DB_CONNECTIONS')); c=d.get('$NAMED_CONNECTION',{}); print(c.get('engine',''))" 2>/dev/null)
+  CONFIG_SOURCE="registry:$NAMED_CONNECTION"
+
+elif [ -n "$INSTRUCTION_FILE" ] && grep -q "^engine:" "$INSTRUCTION_FILE" 2>/dev/null; then
+  # Use project-level instruction file config
+  ENGINE=$(grep "^engine:" "$INSTRUCTION_FILE" | head -1 | cut -d: -f2 | tr -d ' ')
+  CONNECTION_NAME=$(grep "^connection:" "$INSTRUCTION_FILE" | head -1 | cut -d: -f2 | tr -d ' ')
+  CONFIG_SOURCE="instruction-file"
+
+elif [ -f "$DB_CONNECTIONS" ]; then
+  # List available connections and prompt
+  echo "No DB config found in project instruction file. Available connections:"
+  python3 -c "
+import json
+d = json.load(open('$DB_CONNECTIONS'))
+for i, (name, cfg) in enumerate(d.items(), 1):
+    print(f'  {i}) {name} ({cfg.get(\"engine\",\"unknown\")})')
+"
+  read -rp "Select connection (number or name): " SELECTION
+  NAMED_CONNECTION=$(python3 -c "
+import json, sys
+d = json.load(open('$DB_CONNECTIONS'))
+keys = list(d.keys())
+sel = '$SELECTION'
+if sel.isdigit() and 1 <= int(sel) <= len(keys):
+    print(keys[int(sel)-1])
+elif sel in d:
+    print(sel)
+else:
+    print('', end='')
+" 2>/dev/null)
+  ENGINE=$(python3 -c "import json; d=json.load(open('$DB_CONNECTIONS')); print(d.get('$NAMED_CONNECTION',{}).get('engine',''))" 2>/dev/null)
+  CONFIG_SOURCE="registry:$NAMED_CONNECTION"
+
+else
+  echo "ERROR: No database config found."
+  echo "  Option 1: Add a '## Database' section to your project instruction file"
+  echo "  Option 2: Create ~/.claude/db-connections.json with named connections"
+  exit 1
+fi
+
+if [ -z "$ENGINE" ]; then
+  echo "ERROR: Could not determine database engine from config."
+  exit 1
+fi
+
+echo "Engine: $ENGINE | Config: $CONFIG_SOURCE"
+```
+
+---
+
+## Step 2 — Load connection details from registry (if using named connection)
+
+```bash
+if [ -n "$NAMED_CONNECTION" ]; then
+  # Extract all fields from the named connection into shell variables
+  eval "$(python3 -c "
+import json, shlex
+d = json.load(open('$HOME/.claude/db-connections.json'))
+cfg = d.get('$NAMED_CONNECTION', {})
+for k, v in cfg.items():
+    if k != 'engine':
+        print(f'CONN_{k.upper()}={shlex.quote(str(v))}')
+" 2>/dev/null)"
+fi
+```
+
+---
+
+## Step 3 — Resolve credentials
+
+```bash
+# Determine auth method
+AUTH="${CONN_AUTH:-$(grep '^auth:' "$INSTRUCTION_FILE" 2>/dev/null | head -1 | cut -d: -f2- | tr -d ' ')}"
+
+case "$AUTH" in
+  gcp-secret:*)
+    SECRET_NAME="${AUTH#gcp-secret:}"
+    DB_CRED=$(gcloud secrets versions access latest --secret="$SECRET_NAME" --project="${CONN_GCP_PROJECT:-$(grep '^gcp_project:' "$INSTRUCTION_FILE" | cut -d: -f2 | tr -d ' ')}")
+    echo "Credential resolved from GCP Secret Manager ✓"
+    ;;
+  env:*)
+    VAR_NAME="${AUTH#env:}"
+    DB_CRED="${!VAR_NAME}"
+    # Fall back to .env file
+    if [ -z "$DB_CRED" ] && [ -f "$(git rev-parse --show-toplevel 2>/dev/null)/.env" ]; then
+      DB_CRED=$(grep "^${VAR_NAME}=" "$(git rev-parse --show-toplevel)/.env" | cut -d= -f2-)
+    fi
+    [ -z "$DB_CRED" ] && { echo "ERROR: Env var $VAR_NAME not set and not in .env"; exit 1; }
+    echo "Credential resolved from env var $VAR_NAME ✓"
+    ;;
+  sso)
+    DB_CRED=""
+    echo "Using SSO auth — browser window will open ✓"
+    ;;
+  keychain:*)
+    KEY_NAME="${AUTH#keychain:}"
+    DB_CRED=$(security find-generic-password -a "$KEY_NAME" -w 2>/dev/null)
+    [ -z "$DB_CRED" ] && { echo "ERROR: Keychain key '$KEY_NAME' not found"; exit 1; }
+    echo "Credential resolved from macOS keychain ✓"
+    ;;
+  databricks-token)
+    DB_CRED="${DATABRICKS_TOKEN:-$(grep -A5 '\[DEFAULT\]' "$HOME/.databrickscfg" 2>/dev/null | grep '^token' | cut -d= -f2 | tr -d ' ')}"
+    [ -z "$DB_CRED" ] && { echo "ERROR: No Databricks token found"; exit 1; }
+    echo "Credential resolved from Databricks config ✓"
+    ;;
+  *)
+    DB_CRED=""
+    echo "WARNING: No auth method specified — proceeding without credentials"
+    ;;
+esac
+```
+
+---
+
+## Step 4 — Set default SQL if not provided
+
+```bash
+if [ -z "$SQL" ]; then
+  SQL="SELECT 'connected' AS status, current_timestamp AS at"
+  echo "No SQL provided — running default connectivity check"
+fi
+```
+
+---
+
+## Step 5 — Delegate to engine file
+
+```bash
+ENGINE_FILE="$HOME/.claude/commands/db-engines/${ENGINE}.md"
+
+if [ ! -f "$ENGINE_FILE" ]; then
+  echo "ERROR: No engine file found at $ENGINE_FILE"
+  echo "Supported engines: cloud-sql, postgres, snowflake, databricks, athena, presto, oracle"
+  exit 1
+fi
+
+echo "Delegating to db-engines/${ENGINE}.md..."
+echo "---"
+
+# Pass all resolved variables to the engine skill
+# The engine file will use these pre-resolved values:
+# - For cloud-sql:   INSTANCE=$CONN_INSTANCE, GCP_PROJECT=$CONN_GCP_PROJECT, DB_NAME=$CONN_DB_NAME, DB_USER=$CONN_DB_USER, DB_PASS=$DB_CRED
+# - For postgres:    DB_HOST=$CONN_HOST, DB_PORT=$CONN_PORT, DB_NAME=$CONN_DATABASE, DB_USER=$CONN_USER, DB_PASS=$DB_CRED
+# - For snowflake:   SF_ACCOUNT=$CONN_ACCOUNT, SF_WAREHOUSE=$CONN_WAREHOUSE, SF_DATABASE=$CONN_DATABASE, SF_ROLE=$CONN_ROLE, SF_USER=$CONN_USER, SF_TOKEN=$DB_CRED, SF_AUTH=$AUTH
+# - For databricks:  DBX_HOST=$CONN_HOST, DBX_HTTP_PATH=$CONN_HTTP_PATH, DBX_TOKEN=$DB_CRED, DBX_CATALOG=$CONN_CATALOG, DBX_SCHEMA=$CONN_SCHEMA
+# - For athena:      ATHENA_REGION=$CONN_REGION, ATHENA_DATABASE=$CONN_DATABASE, ATHENA_WORKGROUP=$CONN_WORKGROUP, ATHENA_S3_OUTPUT=$CONN_S3_OUTPUT
+# - For presto:      PRESTO_HOST=$CONN_HOST, PRESTO_PORT=$CONN_PORT, PRESTO_USER=$CONN_USER, PRESTO_CATALOG=$CONN_CATALOG, PRESTO_SCHEMA=$CONN_SCHEMA, PRESTO_TOKEN=$DB_CRED, PRESTO_ENGINE=$CONN_ENGINE
+# - For oracle:      ORA_HOST=$CONN_HOST, ORA_PORT=$CONN_PORT, ORA_SERVICE=$CONN_SERVICE, ORA_USER=$CONN_USER, ORA_PASS=$DB_CRED
+# SQL=$SQL is passed to all engines
+
+# Follow the instructions in db-engines/${ENGINE}.md using the variable mappings above
+```

package/modules/db/db-engines/_router.md

@@ -0,0 +1,24 @@
+# db-engines/_router — Shared DB Engine Skeleton
+<!-- Reference only — sourced by /db; not a slash command. -->
+
+## Shared execution skeleton
+
+Each engine file receives pre-resolved variables from the /db router:
+`$DB_HOST`, `$DB_PORT`, `$DB_NAME`, `$DB_USER`, `$DB_PASS`, `$SQL`
+
+### Step 1 — Validate prerequisites
+Check that the engine CLI is available. If not, print install instructions and exit.
+
+### Step 2 — Execute query via CLI (if available)
+Use the engine's native CLI with SSL/TLS as required. Never log $DB_PASS.
+
+### Step 3 — Execute query via driver (fallback)
+If CLI unavailable, use a Node.js or Python driver equivalent.
+
+### Step 4 — Migrate (if SQL = "migrate")
+Detect migration tool (alembic, prisma, raw SQL scripts) and run it.
+
+### Safety rules
+- Never log or print $DB_PASS
+- Always require SSL for non-localhost hosts
+- Never commit connection strings with passwords

package/modules/db/db-engines/athena.md

@@ -0,0 +1,16 @@
+# db-engine: athena
+<!-- Implements _router.md skeleton for AWS Athena -->
+
+Receives pre-resolved variables from /db router: $DB_HOST, $DB_PORT, $DB_NAME, $DB_USER, $DB_PASS, $SQL
+
+**CLI:** `aws athena` | **Port:** HTTPS | **SSL:** always (AWS SDK)
+
+```bash
+aws athena start-query-execution --query-string "$SQL" \
+  --result-configuration OutputLocation="s3://$S3_BUCKET/" \
+  --query-execution-context Database="$DB_NAME"
+```
+
+**Driver fallback:** Node `aws-sdk` with Athena client — `AthenaClient` + `StartQueryExecutionCommand`
+
+**Migration detection:** Athena DDL SQL scripts (CREATE TABLE, ALTER TABLE) → apply in order

package/modules/db/db-engines/cloud-sql.md

@@ -0,0 +1,16 @@
+# db-engine: cloud-sql
+<!-- Implements _router.md skeleton for GCP Cloud SQL (PostgreSQL or MySQL) -->
+
+Receives pre-resolved variables from /db router: $DB_HOST, $DB_PORT, $DB_NAME, $DB_USER, $DB_PASS, $SQL
+
+**CLI:** `gcloud sql connect` or `psql`/`mysql` via Cloud SQL Auth Proxy | **Port:** 5432 (PG) or 3306 (MySQL)
+
+```bash
+# Start Cloud SQL Auth Proxy then connect
+cloud-sql-proxy "$PROJECT:$REGION:$INSTANCE" --port "${DB_PORT:-5432}" &
+PGPASSWORD="$DB_PASS" psql -h 127.0.0.1 -p "${DB_PORT:-5432}" -U "$DB_USER" -d "$DB_NAME" -c "$SQL"
+```
+
+**Driver fallback:** Node `pg` or `mysql2` via Cloud SQL Auth Proxy (standard connection)
+
+**Migration detection:** alembic.ini (PG) → `alembic upgrade head` | Flyway config (MySQL) → `flyway migrate`

package/modules/db/db-engines/databricks.md

@@ -0,0 +1,14 @@
+# db-engine: databricks
+<!-- Implements _router.md skeleton for Databricks SQL -->
+
+Receives pre-resolved variables from /db router: $DB_HOST, $DB_PORT, $DB_NAME, $DB_USER, $DB_PASS, $SQL
+
+**CLI:** `databricks-sql-cli` | **Default port:** 443 | **SSL:** always
+
+```bash
+databricks-sql-cli --server-hostname "$DB_HOST" --http-path "$DB_HTTP_PATH" --access-token "$DB_PASS" -e "$SQL"
+```
+
+**Driver fallback:** Node `@databricks/sql` — connect via HTTP path and personal access token
+
+**Migration detection:** Delta Lake SQL scripts → apply in order via CLI

package/modules/db/db-engines/oracle.md

@@ -0,0 +1,14 @@
+# db-engine: oracle
+<!-- Implements _router.md skeleton for Oracle Database -->
+
+Receives pre-resolved variables from /db router: $DB_HOST, $DB_PORT, $DB_NAME, $DB_USER, $DB_PASS, $SQL
+
+**CLI:** `sqlplus` | **Default port:** 1521 | **SSL:** wallet-based
+
+```bash
+sqlplus "$DB_USER/$DB_PASS@$DB_HOST:${DB_PORT:-1521}/$DB_NAME" <<< "$SQL"
+```
+
+**Driver fallback:** Node `oracledb` — `oracledb.getConnection({ user, password, connectString })`
+
+**Migration detection:** Flyway or Liquibase config → run migrate

package/modules/db/db-engines/postgres.md

@@ -0,0 +1,15 @@
+# db-engine: postgres
+<!-- Implements _router.md skeleton for PostgreSQL and Supabase -->
+
+Receives pre-resolved variables from /db router: $DB_HOST, $DB_PORT, $DB_NAME, $DB_USER, $DB_PASS, $SQL
+
+**CLI:** `psql` | **Default port:** 5432 | **SSL:** `--set=sslmode=require` (always for non-localhost)
+
+```bash
+PGPASSWORD="$DB_PASS" psql -h "$DB_HOST" -p "${DB_PORT:-5432}" -U "$DB_USER" -d "$DB_NAME" \
+  --set=sslmode=require -c "$SQL"
+```
+
+**Driver fallback:** Node `pg` — `new Pool({ host, port, user, password, database, ssl: { rejectUnauthorized: true } })`
+
+**Migration detection:** alembic.ini → `alembic upgrade head` | migrations/*.sql → apply in order

package/modules/db/db-engines/presto.md

@@ -0,0 +1,14 @@
+# db-engine: presto
+<!-- Implements _router.md skeleton for Presto / Trino -->
+
+Receives pre-resolved variables from /db router: $DB_HOST, $DB_PORT, $DB_NAME, $DB_USER, $DB_PASS, $SQL
+
+**CLI:** `presto` | **Default port:** 8080 | **SSL:** `--server https://...`
+
+```bash
+presto --server "$DB_HOST:${DB_PORT:-8080}" --catalog hive --schema "$DB_NAME" --execute "$SQL"
+```
+
+**Driver fallback:** Node `presto-client` or Python `pyhive`
+
+**Migration detection:** SQL scripts only (Presto is query-only, no DDL migrations)

package/modules/db/db-engines/snowflake.md

@@ -0,0 +1,14 @@
+# db-engine: snowflake
+<!-- Implements _router.md skeleton for Snowflake -->
+
+Receives pre-resolved variables from /db router: $DB_HOST, $DB_PORT, $DB_NAME, $DB_USER, $DB_PASS, $SQL
+
+**CLI:** `snowsql` | **Default port:** 443 (HTTPS) | **SSL:** always (no flag needed)
+
+```bash
+snowsql -a "$DB_HOST" -u "$DB_USER" -d "$DB_NAME" -r "$DB_ROLE" -q "$SQL"
+```
+
+**Driver fallback:** Node `snowflake-sdk` — `snowflake.createConnection({ account, username, password, database })`
+
+**Migration detection:** Flyway config → `flyway migrate` | migrations/*.sql → apply in order

package/modules/docs/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: docs
+description: You are a documentation engineer. Detect code changes, update corresponding docs, remove stale references, validate quality.
+category: docs
+tier: on-demand
+slash_command: /docs
+---
+
+# Docs — Documentation Sync
+
+You are a documentation engineer. Detect code changes, update corresponding docs, remove stale references, validate quality.
+
+## Do NOT ask for permission — just update docs.
+## This workflow does NOT run tests or lint. Those are separate workflows (test, lint).
+
+---
+
+## Step 1 — Detect what changed
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+cd "$PROJECT_ROOT"
+git diff --name-only HEAD 2>/dev/null || true
+git diff --name-only --cached 2>/dev/null || true
+git ls-files --others --exclude-standard 2>/dev/null || true
+```
+
+If no code changes, skip to Step 4.
+
+---
+
+## Step 2 — Map changes to docs
+
+Read the project instruction file (CLAUDE.md, AGENTS.md, .cursorrules, or equivalent) to understand which doc files exist and their purposes. Apply the general mapping:
+
+| Changed files | Doc to update |
+|---|---|
+| API routes or handlers | API reference doc |
+| CLI commands or flags | CLI reference doc |
+| Config schema or models | Configuration reference |
+| New features or major changes | `README.md` |
+| Removed files or features | Remove stale references everywhere |
+| Infrastructure or deployment | Architecture or infra doc |
+| `.claude/commands/**` | No doc update needed |
+
+For each affected doc: read the current doc → read the changed source → update.
+
+---
+
+## Step 3 — Update documentation
+
+### Standards
+- GitHub-flavored Markdown
+- Code blocks with language tags (` ```bash `, ` ```typescript `, ` ```python `)
+- Every API route: description, request/response, auth requirement
+- Every CLI command: usage, arguments, flags, examples
+- Direct voice, second-person ("you"), imperative for instructions
+- No emojis unless already present in the file
+- Tables for structured data
+
+### Stale reference removal
+Search all doc files for references to deleted/renamed functions, routes, components, env vars. Remove or update any stale references found.
+
+---
+
+## Step 4 — Validate
+
+```bash
+# Link check — verify internal file references
+grep -rn '\[.*\](\.\.' docs/ README.md CLAUDE.md AGENTS.md .cursorrules 2>/dev/null | head -20 || true
+
+# Unclosed code blocks
+for f in docs/*.md README.md CLAUDE.md AGENTS.md .cursorrules ARCHITECTURE.md 2>/dev/null; do
+  [ -f "$f" ] || continue
+  count=$(grep -c '```' "$f" 2>/dev/null || echo 0)
+  if [ $((count % 2)) -ne 0 ]; then echo "WARNING: $f has unclosed code block"; fi
+done
+```
+
+---
+
+## Step 5 — Stage doc files only
+
+```bash
+git add docs/ README.md CLAUDE.md AGENTS.md .cursorrules .windsurfrules GEMINI.md ROADMAP.md ARCHITECTURE.md 2>/dev/null
+git diff --cached --stat
+```
+
+---
+
+## Output
+
+```
+=== Docs Summary ===
+Changed code:  [list of changed source files]
+Docs updated:  [list of doc files modified]
+Stale removed: [list of removed references]
+Validation:    Links OK, code blocks OK
+Status:        PASSED | NO CHANGES NEEDED
+```