@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/security/secure-ai-application-templates.md

@@ -0,0 +1,347 @@
+---
+name: secure-ai-application-templates
+category: security
+version: 1.0.0
+contributed: 2026-02-20
+contributor: dominion-flow
+last_updated: 2026-02-20
+tags: [security, rag, ai-applications, prompt-injection, input-sanitization, output-filtering, canary-tokens, owasp]
+difficulty: hard
+usage_count: 0
+success_rate: 100
+---
+
+# Secure AI Application Templates
+
+## Problem
+
+When building RAG applications, AI-powered functions, or any system that processes untrusted content through an LLM, developers often forget to include security layers until after an attack happens. The PoisonedRAG attack (USENIX 2025) showed that injecting just 5 malicious documents into a corpus of millions achieves 90% attack success.
+
+Every AI application needs input sanitization, output filtering, document provenance tracking, and canary token monitoring built in from the start — not bolted on after a breach.
+
+## Solution Pattern
+
+Include these security templates in every AI application by default. When building any RAG pipeline, AI function, or agent tool, copy the relevant template and adapt it.
+
+## Template 1: RAG Document Pre-Ingestion Scanner
+
+**Use before:** Embedding any document into a vector database.
+
+```javascript
+// rag-security.js — Pre-ingestion document scanner
+// Apply BEFORE chunking and embedding. Reject or flag documents that fail.
+
+const INVISIBLE_CHAR_REGEX = /[\u200B\u200C\u200D\uFEFF\u2060\u200E\u200F\u202A-\u202E\u2061-\u2064\uFFF9-\uFFFB\u00AD\u034F\u061C\u115F\u1160\u17B4\u17B5\u180E\u3164]/g;
+
+// Tag characters used for ASCII smuggling (U+E0000-U+E007F)
+const TAG_CHAR_REGEX = /[\uDB40\uDC00-\uDB40\uDC7F]/g;
+
+const INJECTION_PATTERNS = [
+  /ignore\s+(all|previous|prior|above)\s+instructions/i,
+  /disregard\s+(all|prior|previous|above)/i,
+  /forget\s+(all|prior|previous|your)/i,
+  /new\s+instructions\s*:/i,
+  /system\s+(prompt|override|message)\s*:/i,
+  /you\s+are\s+now/i,
+  /act\s+as\s+(if\s+you\s+are|a)/i,
+  /bypass\s+(safety|security|filter|restriction)/i,
+  /\bDAN\s+mode\b/i,
+  /\bdeveloper\s+mode\b/i,
+];
+
+const EXFILTRATION_PATTERNS = [
+  /collect\s+(all\s+)?api\s*key/i,
+  /read\s+\.env\s+and\s+(send|encode|include|append)/i,
+  /mail\s+.*\s+to\s+\S+@\S+/i,
+  /send\s+.*\s+(credentials|password|secret|key)\s+to/i,
+  /access\s+(crypto|bitcoin|ethereum)\s+wallet/i,
+  /base64\s+encode\s+.*\s+(secret|key|credential)/i,
+  /without\s+the\s+user\s+knowing/i,
+  /silently\s+(collect|gather|send|forward|transmit)/i,
+];
+
+/**
+ * Scan a document before RAG ingestion.
+ * @param {string} content - Document text content
+ * @param {object} metadata - Document metadata (source, author, date)
+ * @returns {{ safe: boolean, findings: Array, sanitized: string }}
+ */
+function scanForIngestion(content, metadata = {}) {
+  const findings = [];
+
+  // 1. Invisible character detection
+  const invisibleMatches = content.match(INVISIBLE_CHAR_REGEX);
+  const tagMatches = content.match(TAG_CHAR_REGEX);
+  if (invisibleMatches || tagMatches) {
+    findings.push({
+      severity: 'CRITICAL',
+      type: 'invisible_characters',
+      count: (invisibleMatches?.length || 0) + (tagMatches?.length || 0),
+      detail: 'Invisible characters found — may hide malicious instructions',
+    });
+  }
+
+  // 2. NFKC normalize before pattern scanning
+  const normalized = content.normalize('NFKC');
+
+  // 3. Prompt injection detection
+  for (const pattern of INJECTION_PATTERNS) {
+    const match = normalized.match(pattern);
+    if (match) {
+      findings.push({
+        severity: 'HIGH',
+        type: 'prompt_injection',
+        pattern: pattern.source,
+        matched: match[0],
+        detail: `Prompt injection pattern: "${match[0]}"`,
+      });
+    }
+  }
+
+  // 4. Exfiltration / credential harvesting detection
+  for (const pattern of EXFILTRATION_PATTERNS) {
+    const match = normalized.match(pattern);
+    if (match) {
+      findings.push({
+        severity: 'CRITICAL',
+        type: 'exfiltration',
+        pattern: pattern.source,
+        matched: match[0],
+        detail: `Exfiltration pattern: "${match[0]}"`,
+      });
+    }
+  }
+
+  // 5. Sanitize: strip invisible chars, NFKC normalize
+  const sanitized = normalized
+    .replace(INVISIBLE_CHAR_REGEX, '')
+    .replace(TAG_CHAR_REGEX, '');
+
+  const hasCritical = findings.some(f => f.severity === 'CRITICAL');
+  const hasHigh = findings.some(f => f.severity === 'HIGH');
+
+  return {
+    safe: !hasCritical && !hasHigh,
+    findings,
+    sanitized,
+    metadata: {
+      ...metadata,
+      scanned_at: new Date().toISOString(),
+      trust_level: hasCritical ? 'BLOCKED' : hasHigh ? 'SUSPICIOUS' : 'TRUSTED',
+    },
+  };
+}
+
+// Usage in RAG pipeline:
+// const result = scanForIngestion(docContent, { source: 'upload', author: 'user' });
+// if (!result.safe) { reject or quarantine the document }
+// else { proceed to chunk and embed result.sanitized }
+```
+
+## Template 2: AI Function Output Filter
+
+**Use after:** Any LLM generates output that will be displayed to users or executed.
+
+```javascript
+// output-filter.js — Filter LLM output before returning to user
+// Prevents the LLM from leaking secrets, PII, or executing injected instructions.
+
+const SECRET_PATTERNS = [
+  { name: 'AWS Access Key', regex: /AKIA[0-9A-Z]{16}/g },
+  { name: 'Anthropic API Key', regex: /sk-ant-api03-[A-Za-z0-9\-_]{20,}/g },
+  { name: 'GitHub PAT', regex: /ghp_[A-Za-z0-9]{36}/g },
+  { name: 'Stripe Live Key', regex: /sk_live_[0-9a-zA-Z]{24,}/g },
+  { name: 'Private Key', regex: /-----BEGIN\s+(RSA|DSA|EC|PGP|ENCRYPTED)\s+PRIVATE\s+KEY-----/g },
+  { name: 'JWT Token', regex: /eyJ[A-Za-z0-9\-_]+\.eyJ[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+/g },
+  { name: 'Database URI', regex: /(postgres|mysql|mongodb|redis):\/\/[^\s"']+/g },
+  { name: 'Password in URL', regex: /[a-zA-Z]{3,10}:\/\/[^\/\s:@]+:[^\/\s:@]+@/g },
+];
+
+const PII_PATTERNS = [
+  { name: 'SSN', regex: /\b\d{3}-\d{2}-\d{4}\b/g },
+  { name: 'Credit Card', regex: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g },
+  { name: 'Bitcoin Address', regex: /\b(bc1|[13])[a-zA-HJ-NP-Z0-9]{25,39}\b/g },
+  { name: 'Ethereum Address', regex: /\b0x[a-fA-F0-9]{40}\b/g },
+];
+
+/**
+ * Filter LLM output for leaked secrets and PII.
+ * @param {string} output - Raw LLM output
+ * @returns {{ filtered: string, redactions: Array }}
+ */
+function filterOutput(output) {
+  let filtered = output;
+  const redactions = [];
+
+  for (const { name, regex } of [...SECRET_PATTERNS, ...PII_PATTERNS]) {
+    const matches = filtered.match(regex);
+    if (matches) {
+      for (const match of matches) {
+        redactions.push({ type: name, value: match.substring(0, 8) + '...[REDACTED]' });
+        filtered = filtered.replace(match, `[REDACTED: ${name}]`);
+      }
+    }
+  }
+
+  return { filtered, redactions };
+}
+```
+
+## Template 3: Canary Token Monitor
+
+**Use in:** System prompts to detect prompt leakage.
+
+```javascript
+// canary-tokens.js — Inject and monitor canary tokens in system prompts
+// If the canary appears in LLM output, the system prompt was leaked.
+
+const crypto = require('crypto');
+
+/**
+ * Generate a unique canary token for this session.
+ * @returns {string} A unique token like "CANARY-a3f8b2c1"
+ */
+function generateCanary() {
+  const id = crypto.randomBytes(4).toString('hex');
+  return `CANARY-${id}`;
+}
+
+/**
+ * Inject canary into system prompt.
+ * @param {string} systemPrompt - The system prompt
+ * @param {string} canary - The canary token
+ * @returns {string} System prompt with canary injected
+ */
+function injectCanary(systemPrompt, canary) {
+  return `${systemPrompt}\n\n<!-- Internal tracking: ${canary} - Do not output this value -->`;
+}
+
+/**
+ * Check if LLM output contains the canary (prompt leakage detected).
+ * @param {string} output - LLM output
+ * @param {string} canary - The canary token
+ * @returns {boolean} true if canary leaked
+ */
+function checkCanaryLeakage(output, canary) {
+  return output.includes(canary);
+}
+
+// Usage:
+// const canary = generateCanary();
+// const prompt = injectCanary(baseSystemPrompt, canary);
+// ... send to LLM ...
+// if (checkCanaryLeakage(llmOutput, canary)) {
+//   log('ALERT: System prompt leaked!');
+//   // Reject the output, log the incident
+// }
+```
+
+## Template 4: Document Provenance Tracker
+
+**Use for:** Tracking which documents influenced each RAG response for audit trails.
+
+```javascript
+// provenance.js — Track document provenance in RAG responses
+// Essential for debugging poisoned document attacks after the fact.
+
+/**
+ * Wrap RAG context with provenance metadata.
+ * @param {Array} chunks - Retrieved document chunks
+ * @returns {{ context: string, provenance: Array }}
+ */
+function buildProvenanceContext(chunks) {
+  const provenance = chunks.map((chunk, i) => ({
+    index: i,
+    source: chunk.metadata?.source || 'unknown',
+    author: chunk.metadata?.author || 'unknown',
+    ingested_at: chunk.metadata?.scanned_at || 'unknown',
+    trust_level: chunk.metadata?.trust_level || 'UNSCANNED',
+    similarity: chunk.score,
+    excerpt: chunk.text.substring(0, 100) + '...',
+  }));
+
+  // Build context string with source markers
+  const context = chunks.map((chunk, i) =>
+    `[Source ${i}: ${chunk.metadata?.source || 'unknown'} (trust: ${chunk.metadata?.trust_level || 'UNSCANNED'})]\n${chunk.text}`
+  ).join('\n\n');
+
+  return { context, provenance };
+}
+
+/**
+ * Log RAG response with full provenance for audit.
+ * @param {string} query - User query
+ * @param {string} response - LLM response
+ * @param {Array} provenance - Document provenance
+ */
+function logWithProvenance(query, response, provenance) {
+  const entry = {
+    timestamp: new Date().toISOString(),
+    query,
+    response_excerpt: response.substring(0, 200),
+    sources_used: provenance.length,
+    trust_breakdown: {
+      trusted: provenance.filter(p => p.trust_level === 'TRUSTED').length,
+      suspicious: provenance.filter(p => p.trust_level === 'SUSPICIOUS').length,
+      unscanned: provenance.filter(p => p.trust_level === 'UNSCANNED').length,
+      blocked: provenance.filter(p => p.trust_level === 'BLOCKED').length,
+    },
+    provenance,
+  };
+  // Write to audit log (file, database, or monitoring service)
+  console.log('[RAG-AUDIT]', JSON.stringify(entry));
+  return entry;
+}
+```
+
+## When to Use
+
+- Building any RAG pipeline (document Q&A, knowledge base, chatbot)
+- Creating AI-powered functions that process untrusted input
+- Building agent tools that accept external content
+- Any application where documents enter via upload, API, or web scraping
+- MCP server development (tool descriptions are a trust surface)
+
+## When NOT to Use
+
+- Pure computation with no LLM involvement
+- Applications that only process trusted, internal data
+- Simple LLM wrappers with no external document input
+
+## Implementation Checklist
+
+When building any AI application, verify:
+
+- [ ] **Input sanitization:** All external content scanned before LLM sees it (Template 1)
+- [ ] **Output filtering:** LLM output checked for leaked secrets/PII before display (Template 2)
+- [ ] **Canary tokens:** System prompts include canary for leakage detection (Template 3)
+- [ ] **Provenance tracking:** Every RAG response logs which documents influenced it (Template 4)
+- [ ] **Trust levels:** Documents tagged with trust level at ingestion time
+- [ ] **NFKC normalization:** All text normalized before pattern matching
+- [ ] **Invisible char stripping:** Zero-width and tag characters removed from all input
+
+## Common Mistakes
+
+- Scanning AFTER embedding (too late — poisoned vectors already in the DB)
+- Only scanning for known patterns (use AI classification for novel attacks)
+- Trusting all documents equally (internal docs vs user uploads have different trust levels)
+- Not logging provenance (can't trace which document caused a bad response)
+- Forgetting to normalize Unicode before regex (attackers use confusable characters)
+
+## OWASP Agentic Top 10 Coverage
+
+| Template | Covers | OWASP Risk |
+|----------|--------|------------|
+| Pre-ingestion scanner | Document poisoning | ASI06: Memory/Context Poisoning |
+| Output filter | Data leakage | ASI07: Output Handling |
+| Canary tokens | Prompt extraction | ASI01: Agent Goal Hijacking |
+| Provenance tracker | Audit trail | ASI09: Logging/Monitoring |
+
+## References
+
+- PoisonedRAG (USENIX 2025): 5 docs = 90% attack success
+- OWASP Top 10 for Agentic Applications 2026
+- Microsoft Presidio (PII detection): https://github.com/microsoft/presidio
+- secrets-patterns-db (1600+ patterns): https://github.com/mazen160/secrets-patterns-db
+- Companion: `security/agent-security-scanner.md` — Full 6-layer scanning pipeline
+- Companion: `/fire-security-scan` — Manual and auto-triggered scanning command

package/skills-library/security/sql-injection-prevention-postgresjs.md

@@ -0,0 +1,151 @@
+---
+name: sql-injection-prevention-postgresjs
+category: security
+version: 1.0.0
+contributed: 2026-02-19
+contributor: my-other-project
+last_updated: 2026-02-19
+tags: [sql-injection, postgres.js, security, dynamic-queries, input-validation]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# SQL Injection Prevention for postgres.js
+
+## Problem
+
+When using postgres.js (`postgres` npm package) with dynamic queries, two common patterns introduce SQL injection:
+
+1. **Dynamic column names in UPDATE** — Using `sql.unsafe()` with `Object.keys(userInput)` concatenated into the query. An attacker passing `"name; DROP TABLE profiles;--"` as a field key achieves injection.
+
+2. **Dynamic ORDER BY from query params** — Passing `?sort=name;DROP TABLE profiles` directly into `ORDER BY ${sort}` in a template string fed to `sql.unsafe()`.
+
+Both bypass postgres.js tagged template literal protection because column/table names can't be parameterized in standard SQL.
+
+### Symptoms
+- `sql.unsafe()` calls with string concatenation
+- `Object.keys()` from request body used in SQL
+- `req.query.sort` passed directly to ORDER BY
+- Any raw string interpolation in SQL queries
+
+## Solution Pattern
+
+### Pattern 1: Column Whitelist for Dynamic UPDATE
+
+Replace `sql.unsafe()` with postgres.js `sql()` helper and a Set-based whitelist:
+
+```javascript
+// BEFORE (VULNERABLE)
+export const updateUser = async (id, updateData) => {
+  const fields = Object.keys(updateData);
+  const sets = fields.map((f, i) => `${f} = $${i + 1}`).join(', ');
+  const values = fields.map(f => updateData[f]);
+  const result = await sql.unsafe(
+    `UPDATE profiles SET ${sets} WHERE id = $${fields.length + 1} RETURNING *`,
+    [...values, id]
+  );
+  return result[0];
+};
+
+// AFTER (SAFE)
+const ALLOWED_COLUMNS = new Set([
+  'name', 'email', 'bio', 'website', 'location', 'skills',
+  'role', 'avatar_url', 'phone', 'full_name', 'dark_mode'
+]);
+
+export const updateUser = async (id, updateData) => {
+  const safeData = {};
+  for (const [key, val] of Object.entries(updateData)) {
+    if (ALLOWED_COLUMNS.has(key)) safeData[key] = val;
+  }
+  if (Object.keys(safeData).length === 0) return null;
+
+  // postgres.js sql() helper safely handles dynamic columns
+  const result = await sql`
+    UPDATE profiles SET ${sql(safeData, ...Object.keys(safeData))}
+    WHERE id = ${id} RETURNING *
+  `;
+  return result[0];
+};
+```
+
+### Pattern 2: sanitizeSort() for Dynamic ORDER BY
+
+Create a reusable utility that validates sort input against a whitelist:
+
+```javascript
+// server/middleware/inputValidation.js
+export const sanitizeSort = (sortInput, allowedColumns, defaultSort = 'created_at DESC') => {
+  if (!sortInput || typeof sortInput !== 'string') return defaultSort;
+  const parts = sortInput.trim().split(/\s+/);
+  const column = parts[0].replace(/^[a-z]+\./i, ''); // Strip table prefix
+  const direction = (parts[1] || 'ASC').toUpperCase();
+  if (!allowedColumns.includes(column)) return defaultSort;
+  if (direction !== 'ASC' && direction !== 'DESC') return defaultSort;
+  // Preserve original table prefix if present (e.g., "p.created_at")
+  const prefix = sortInput.trim().match(/^([a-z]+\.)/i)?.[1] || '';
+  return `${prefix}${column} ${direction}`;
+};
+```
+
+Usage in models:
+
+```javascript
+import { sanitizeSort } from '../middleware/inputValidation.js';
+
+const ALLOWED_SORT = ['created_at', 'name', 'email', 'role', 'updated_at'];
+
+export const getUsers = async (options = {}) => {
+  const validSort = sanitizeSort(options.sort, ALLOWED_SORT);
+  const limit = Number(options.limit) || 20;
+  const offset = Number(options.offset) || 0;
+
+  // validSort is guaranteed safe — use in sql.unsafe for ORDER BY only
+  const result = await sql.unsafe(
+    `SELECT * FROM profiles ORDER BY ${validSort} LIMIT $1 OFFSET $2`,
+    [limit, offset]
+  );
+  return result;
+};
+```
+
+## Implementation Steps
+
+1. Identify all `sql.unsafe()` calls with string interpolation
+2. For UPDATE queries: create column whitelist Set, use `sql()` helper
+3. For ORDER BY: create `sanitizeSort()`, define model-specific allowed columns
+4. For LIMIT/OFFSET: cast to `Number()` — never interpolate raw strings
+5. Test with injection payloads: `name;DROP TABLE x--`, `name UNION SELECT *`
+
+## When to Use
+
+- Any postgres.js project with dynamic UPDATE queries
+- Any endpoint accepting `?sort=` query parameters
+- Models that build SQL from user-provided field names
+- REST APIs with sortable list endpoints
+
+## When NOT to Use
+
+- If using an ORM (Prisma, Sequelize) — they handle parameterization
+- Static SQL with no dynamic parts — tagged templates are already safe
+- If column names come from trusted server-side code only
+
+## Common Mistakes
+
+- Trusting `Object.keys()` from request body — attackers control key names
+- Using `sql.unsafe()` when `sql` tagged template would work
+- Forgetting to whitelist new columns after schema changes
+- Allowing table prefixes without validation (e.g., `information_schema.columns`)
+- Only validating column name but not direction (`ASC`/`DESC`)
+
+## Related Skills
+
+- [POSTGRES_SQL_TEMPLATE_BINDING_ERROR](../database-solutions/POSTGRES_SQL_TEMPLATE_BINDING_ERROR.md) - Template binding issues
+- [PRODUCTION_HARDENING_DOCUMENTATION](../deployment-security/PRODUCTION_HARDENING_DOCUMENTATION.md) - General hardening
+
+## References
+
+- postgres.js docs: https://github.com/porsager/postgres#dynamic-columns
+- OWASP SQL Injection: https://owasp.org/www-community/attacks/SQL_Injection
+- Contributed from: my-other-project (Feb 2026 security audit)

package/skills-library/supabase-connection-pooler-fix.md

@@ -0,0 +1,102 @@
+# Supabase Connection Pooler - IPv4 Fix
+
+## Problem
+VPS cannot connect to Supabase PostgreSQL database. Two errors occur:
+
+### Error 1: IPv6 Unreachable (Direct Connection)
+```
+Error: connect ENETUNREACH 2600:1f18:2e13:9d18:88be:d4c9:6b70:87e9:5432
+```
+**Cause:** Direct connection (`db.[project].supabase.co:5432`) resolves to IPv6, but VPS has no IPv6 connectivity.
+
+### Error 2: Connection Timeout (Transaction Pooler)
+```
+Error: write CONNECT_TIMEOUT aws-1-us-east-1.pooler.supabase.com:6543
+```
+**Cause:** Transaction pooler on port 6543 may have firewall restrictions or require special configuration.
+
+---
+
+## Solution: Use Session Pooler with URL-Encoded Password
+
+### Working Connection String Format
+```
+postgresql://postgres.[PROJECT_REF]:[URL_ENCODED_PASSWORD]@aws-1-us-east-1.pooler.supabase.com:5432/postgres
+```
+
+### Key Points
+
+1. **Use Session Pooler (port 5432)** - NOT transaction pooler (port 6543)
+   - Session pooler: `pooler.supabase.com:5432`
+   - Transaction pooler: `pooler.supabase.com:6543`
+
+2. **URL Encode Special Characters in Password**
+   - `*` → `%2A`
+   - `@` → `%40`
+   - `/` → `%2F`
+   - `&` → `%26`
+   - `#` → `%23`
+
+   Example: `Jubileess_*7*` → `Jubileess_%2A7%2A`
+
+3. **Username Format for Pooler**
+   - Direct: `postgres`
+   - Pooler: `postgres.[PROJECT_REF]`
+
+---
+
+## Connection String Comparison
+
+### Direct Connection (IPv6 issues)
+```
+postgresql://postgres:PASSWORD@db.[PROJECT].supabase.co:5432/postgres
+```
+
+### Transaction Pooler (may timeout)
+```
+postgresql://postgres.[PROJECT]:PASSWORD@aws-1-us-east-1.pooler.supabase.com:6543/postgres?pgbouncer=true
+```
+
+### Session Pooler (RECOMMENDED for VPS)
+```
+postgresql://postgres.[PROJECT]:URL_ENCODED_PASSWORD@aws-1-us-east-1.pooler.supabase.com:5432/postgres
+```
+
+---
+
+## How to Find Your Pooler URL
+
+1. Go to Supabase Dashboard
+2. Click "Connect" button
+3. Select "Connection String" tab
+4. Change "Method" dropdown to "Session pooler"
+5. Note: It says "IPv4 compatible" at the bottom
+
+---
+
+## Verification
+
+After updating `.env`, restart the server and check logs:
+```bash
+pm2 restart all
+pm2 logs lms-server --lines 20
+```
+
+**Success indicator:**
+```
+✅ [DATABASE] Connection successful! Supabase PostgreSQL is ready.
+```
+
+**Failure indicators:**
+```
+❌ [DATABASE] Failed to connect to Supabase PostgreSQL
+Error: connect ENETUNREACH ...  # IPv6 issue
+Error: write CONNECT_TIMEOUT ... # Pooler/firewall issue
+```
+
+---
+
+## References
+- [Supabase Connection Management](https://supabase.com/docs/guides/database/connection-management)
+- [Supabase GitHub Discussion #21789](https://github.com/orgs/supabase/discussions/21789)
+- [Supavisor FAQ](https://supabase.com/docs/guides/troubleshooting/supavisor-faq-YyP5tI)

package/skills-library/system-context/POWERSHELL_BASH_INTEROP.md

@@ -0,0 +1,82 @@
+---
+name: powershell-bash-interop
+category: system-context
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [powershell, bash, windows, shell, interop, scripts]
+difficulty: medium
+---
+
+# PowerShell & Bash Interop
+
+## Problem
+
+Claude Code's shell is bash (Git Bash on Windows), but some Windows operations require PowerShell (COM objects, system shortcuts, Windows APIs). Mixing syntax causes cryptic failures.
+
+## Solution Pattern
+
+Know which shell to use for what, and how to call one from the other.
+
+## Shell Selection Guide
+
+| Task | Use | Why |
+|------|-----|-----|
+| Git operations | Bash | Native git |
+| npm/node commands | Bash | Works in both, bash is default |
+| File operations (basic) | Bash | `cp`, `mv`, `rm` work fine |
+| Desktop shortcuts | PowerShell | Requires COM objects |
+| Windows services | PowerShell | `Get-Service`, `Start-Service` |
+| Registry access | PowerShell | `Get-ItemProperty` |
+| Environment variables (persistent) | PowerShell | `[Environment]::SetEnvironmentVariable` |
+| Docker | Bash | CLI is the same everywhere |
+| `curl` / `wget` | Bash | PowerShell's `curl` is aliased to `Invoke-WebRequest` |
+
+## Calling PowerShell from Bash
+
+```bash
+# One-liner
+powershell.exe -Command "Get-Process | Where-Object {$_.ProcessName -eq 'node'}"
+
+# Multi-line script
+powershell.exe -Command "
+\$desktop = [Environment]::GetFolderPath('Desktop')
+\$shortcut = (New-Object -ComObject WScript.Shell).CreateShortcut(\"\$desktop\\MyApp.lnk\")
+\$shortcut.TargetPath = 'C:\\path\\to\\my-app\\start.bat'
+\$shortcut.Save()
+"
+```
+
+**Key escaping rules in bash → PowerShell:**
+- `$` must be escaped as `\$` (bash would expand it otherwise)
+- Use single quotes inside PowerShell where possible
+- Backslashes in paths must be doubled or use forward slashes
+
+## Calling Bash from PowerShell
+
+```powershell
+# Run a bash command
+bash -c "git status"
+
+# Run a bash script
+bash -c "cd /c/path/to/my-project && npm test"
+```
+
+## Common Pitfalls
+
+1. **`curl` in PowerShell** — It's actually `Invoke-WebRequest`, not `curl`. Use bash for real `curl`.
+2. **Path separators** — PowerShell uses `\`, bash uses `/`. Both work in most tools on Windows.
+3. **Exit codes** — PowerShell `$LASTEXITCODE` vs bash `$?`. They don't bridge cleanly.
+4. **`rm`** — In PowerShell it's `Remove-Item`. In bash it's GNU `rm`. Different flags.
+
+## When to Use
+
+- Creating desktop shortcuts (New Application Init Checklist)
+- Managing Windows services
+- Any task requiring Windows-specific APIs
+- Debugging shell-related failures
+
+## When NOT to Use
+
+- Standard dev operations (git, npm, docker) — just use bash
+- Linux/Mac environments