@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/claude-code/perf-compression/SKILL.md

@@ -0,0 +1,163 @@
+# Content Compression
+
+> Master content compression for web delivery — Brotli, gzip, and Zstandard algorithms, compression level selection, content-encoding negotiation, static pre-compression vs dynamic compression, and format-specific optimization strategies.
+
+## When to Use
+
+- Transfer sizes for text-based assets (HTML, CSS, JS, JSON, SVG) are not minimized
+- Lighthouse flags "Enable text compression" as a performance opportunity
+- You need to choose between Brotli and gzip for your server or CDN configuration
+- Build pipeline needs pre-compression of static assets for maximum compression without runtime CPU cost
+- API responses are large JSON payloads that would benefit from compression
+- CDN configuration needs correct Vary and Content-Encoding header setup
+- You are evaluating Zstandard (zstd) as an emerging compression alternative
+- Compression is applied to resources that should not be compressed (images, video)
+- Server CPU usage is high from dynamic compression and you need to optimize compression levels
+- Transfer size budgets require maximizing compression ratios for text assets
+
+## Instructions
+
+1. **Verify compression is active.** In Chrome DevTools Network panel, check the "Content-Encoding" response header for `br` (Brotli), `gzip`, or `zstd`. Compare "Size" column (transfer size) vs "Size" column tooltip (uncompressed size). If they are equal, compression is not active.
+
+   ```bash
+   # Check compression with curl
+   curl -H "Accept-Encoding: br, gzip" -I https://example.com/app.js
+   # Look for: Content-Encoding: br
+   ```
+
+2. **Choose the right algorithm.** Decision matrix:
+
+   | Algorithm      | Compression Ratio       | Compression Speed   | Decompression Speed | Browser Support |
+   | -------------- | ----------------------- | ------------------- | ------------------- | --------------- |
+   | gzip (deflate) | Baseline                | Fast (levels 1-4)   | Very fast           | 100%            |
+   | Brotli         | 15-26% better than gzip | Slow at high levels | Very fast           | 97%             |
+   | Zstandard      | 10-20% better than gzip | Very fast           | Very fast           | ~70% (emerging) |
+
+   **Default recommendation:** Brotli for static assets (pre-compressed at build time), Brotli level 4-6 for dynamic responses, gzip as fallback.
+
+3. **Configure static pre-compression.** For build artifacts (JS, CSS, HTML), compress at build time at maximum quality:
+
+   ```bash
+   # Brotli pre-compression (level 11 — slow but maximum compression)
+   brotli -q 11 dist/app.js     # creates dist/app.js.br
+   brotli -q 11 dist/style.css  # creates dist/style.css.br
+
+   # gzip pre-compression (level 9 — maximum for gzip)
+   gzip -k -9 dist/app.js       # creates dist/app.js.gz
+   ```
+
+   Configure the server to serve pre-compressed files when available:
+
+   ```nginx
+   # Nginx: serve pre-compressed files
+   gzip_static on;
+   brotli_static on;
+   ```
+
+4. **Configure dynamic compression for generated responses.** For API responses, HTML templates, and other dynamic content, use moderate compression levels:
+
+   ```nginx
+   # Nginx dynamic Brotli configuration
+   brotli on;
+   brotli_comp_level 4;  # Good balance of compression and CPU
+   brotli_types text/html text/plain text/css application/json
+                 application/javascript text/xml application/xml
+                 image/svg+xml;
+
+   # Nginx dynamic gzip configuration (fallback)
+   gzip on;
+   gzip_comp_level 6;
+   gzip_types text/html text/plain text/css application/json
+              application/javascript text/xml application/xml
+              image/svg+xml;
+   gzip_min_length 1000;  # Don't compress tiny responses
+   ```
+
+5. **Set correct response headers.** Ensure Content-Encoding and Vary headers are correct:
+
+   ```
+   Content-Encoding: br
+   Vary: Accept-Encoding
+   ```
+
+   The `Vary: Accept-Encoding` header tells caches to store separate versions for different encodings. Without it, a CDN might serve a Brotli-compressed response to a client that only supports gzip.
+
+6. **Know what NOT to compress.** Skip compression for:
+   - Already-compressed formats: JPEG, PNG, WebP, AVIF, MP4, WOFF2, ZIP
+   - Very small responses (<1KB): compression metadata overhead exceeds savings
+   - Encrypted content: compression before encryption can leak information (BREACH attack)
+
+7. **Measure compression effectiveness.** Compare transfer sizes before and after:
+
+   ```javascript
+   // Measure compression ratio for each resource
+   const resources = performance.getEntriesByType('resource');
+   resources.forEach((r) => {
+     if (r.transferSize > 0 && r.decodedBodySize > 0) {
+       const ratio = (1 - r.transferSize / r.decodedBodySize) * 100;
+       console.log(`${r.name}: ${ratio.toFixed(1)}% compressed`);
+     }
+   });
+   ```
+
+## Details
+
+### Compression Level Selection Guide
+
+Brotli levels 0-11 offer a wide range of speed/ratio tradeoffs:
+
+- **Brotli 0-3:** Faster than gzip with similar compression. Use for real-time streaming.
+- **Brotli 4-6:** Sweet spot for dynamic content. Brotli 4 outperforms gzip 9 in both ratio and speed for typical web content.
+- **Brotli 7-9:** Diminishing returns. Only use if CPU is plentiful.
+- **Brotli 10-11:** 100x slower than level 4. Only for pre-compressed static assets.
+
+For gzip: level 6 is the standard default. Level 9 adds ~5% compression for ~50% more CPU. Level 1 is useful for real-time compression of large streaming responses.
+
+### Brotli's Web Dictionary
+
+Brotli includes a built-in static dictionary of common web content fragments (HTML tags, CSS properties, JavaScript keywords). This gives Brotli a significant advantage over gzip for small web resources. A 10KB JavaScript file might compress 20% better with Brotli than gzip specifically because common patterns like `function`, `return`, `document.getElementById` are in the dictionary.
+
+### Worked Example: LinkedIn Compression Migration
+
+LinkedIn reduced transfer sizes by 20% across their static assets by switching from gzip-6 (their previous standard) to a dual strategy: Brotli-11 for build-time pre-compressed static assets and Brotli-5 for dynamic API responses. The static assets (JS bundles, CSS) saw the largest gains — a 450KB (uncompressed) JavaScript bundle went from 120KB with gzip-6 to 95KB with Brotli-11. The migration required: adding Brotli pre-compression to the build pipeline, configuring Nginx brotli_static module, and ensuring the CDN correctly varied on Accept-Encoding.
+
+### Worked Example: Cloudflare Compression Benchmarks
+
+Cloudflare published benchmarks showing that Brotli level 4 outperforms gzip level 9 in both compression ratio (4.5% better) and compression speed (15% faster) for typical web content (HTML, CSS, JS). For their CDN, they use Brotli-4 as the default dynamic compression level, which compresses a typical 100KB HTML page in 2ms (vs 3ms for gzip-9) while achieving a 25:1 compression ratio (vs 22:1 for gzip-9). They estimate this saves 15-20% bandwidth globally across their network.
+
+### Anti-Patterns
+
+**Compressing already-compressed formats.** JPEG, PNG, WebP, MP4, WOFF2, and ZIP files are already compressed. Attempting to compress them adds CPU cost with near-zero (<1%) size reduction, and may even increase size due to compression metadata overhead.
+
+**Using Brotli level 11 for dynamic responses.** Brotli-11 takes approximately 100x longer than Brotli-4 to compress the same content. For a dynamic API response, this adds 50-200ms of CPU time per request. Use Brotli-11 only for static pre-compression at build time.
+
+**Not setting Vary: Accept-Encoding.** Without this header, a CDN or proxy may cache the Brotli-compressed version and serve it to a client that only supports gzip (causing a decode error) or cache the uncompressed version and serve it to a client that supports Brotli (wasting bandwidth).
+
+**Compressing responses under 1KB.** The overhead of compression framing (gzip header: ~20 bytes, Brotli header: ~10 bytes) combined with the minimum block size means very small responses may not shrink or may even grow after compression. Set a minimum size threshold (1KB recommended).
+
+## Source
+
+- RFC 7932: Brotli Compressed Data Format — https://www.rfc-editor.org/rfc/rfc7932
+- RFC 1952: GZIP File Format Specification — https://www.rfc-editor.org/rfc/rfc1952
+- RFC 8878: Zstandard Compression — https://www.rfc-editor.org/rfc/rfc8878
+- Google Brotli repository and benchmarks — https://github.com/google/brotli
+- Cloudflare compression benchmarks — https://blog.cloudflare.com/results-experimenting-brotli/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- All text-based assets (HTML, CSS, JS, JSON, SVG) are served with Content-Encoding: br or gzip.
+- Static assets use Brotli pre-compression at maximum quality (level 11) from the build pipeline.
+- Vary: Accept-Encoding is present on all compressed responses for correct CDN caching behavior.

package/dist/agents/skills/claude-code/perf-compression/skill.yaml

@@ -0,0 +1,38 @@
+name: perf-compression
+version: '1.0.0'
+description: Content compression — Brotli vs gzip comparison, compression levels, content-encoding negotiation, and static vs dynamic compression
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-cdn-strategies
+  - perf-http2-multiplexing
+  - perf-bundle-analysis
+  - perf-cdn-cache-control
+stack_signals: []
+keywords:
+  - brotli
+  - gzip
+  - compression
+  - content-encoding
+  - transfer size
+  - zstd
+  - deflate
+  - compression ratio
+  - static compression
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-connection-costs/SKILL.md

@@ -0,0 +1,165 @@
+# Network Connection Costs
+
+> Understand and minimize the cumulative cost of DNS resolution, TCP handshake, and TLS negotiation — the invisible overhead that adds 100-500ms to every new connection before a single byte of application data transfers.
+
+## When to Use
+
+- Time to First Byte (TTFB) exceeds 600ms and network waterfall shows connection establishment as the bottleneck
+- DevTools shows DNS lookup, TCP connect, and TLS handshake consuming significant time per resource
+- A page connects to more than 4 unique origins (main domain, CDN, analytics, fonts, ads)
+- Mobile users report slow initial page loads, especially on high-latency cellular networks
+- You need to decide how many third-party origins to include on a page
+- Server-side applications make outbound HTTP requests to multiple microservices
+- TTFB is inconsistent across geographic regions, suggesting DNS or routing issues
+- You are optimizing the critical rendering path and need to reduce resource discovery latency
+- Connection reuse metrics show low keep-alive rates or frequent connection churn
+- TLS handshake time exceeds 100ms and certificate chain optimization is needed
+
+## Instructions
+
+1. **Measure connection costs.** In Chrome DevTools Network panel, hover over the Waterfall bar for any resource. The tooltip breaks down: DNS Lookup, TCP Connection (Initial connection), TLS Handshake (SSL), and TTFB (Waiting for server response). Use the Navigation Timing API for programmatic measurement:
+
+   ```javascript
+   const nav = performance.getEntriesByType('navigation')[0];
+   console.log({
+     dns: nav.domainLookupEnd - nav.domainLookupStart, // DNS resolution
+     tcp: nav.connectEnd - nav.connectStart, // TCP handshake
+     tls:
+       nav.secureConnectionStart > 0
+         ? nav.connectEnd - nav.secureConnectionStart // TLS negotiation
+         : 0,
+     ttfb: nav.responseStart - nav.requestStart, // Server processing
+   });
+   ```
+
+2. **Minimize unique origins.** Each unique origin requires a full DNS + TCP + TLS handshake. Audit all origins on your page:
+
+   ```bash
+   # Extract unique origins from a HAR file or DevTools
+   # Target: 4 or fewer unique origins for critical resources
+   ```
+
+   Decision thresholds:
+   - 1-3 origins: optimal, minimal connection overhead
+   - 4-6 origins: acceptable, use preconnect for non-primary origins
+   - 7+ origins: excessive, consolidate or defer non-critical third-party resources
+
+3. **Optimize DNS resolution.** DNS resolution involves recursive lookups through multiple nameservers. Typical cost: 20-120ms globally, but can exceed 200ms for uncached domains on mobile.
+
+   Mitigation strategies:
+   - **dns-prefetch** for origins needed soon: `<link rel="dns-prefetch" href="//cdn.example.com">`
+   - **Reduce DNS TTL carefully** — shorter TTL means more lookups, longer means slower failover
+   - **Use a fast DNS provider** — Cloudflare DNS (1.1.1.1): ~11ms median, Route 53: ~20ms median
+   - **DNS-over-HTTPS (DoH)** — encrypted but may add latency for first resolution
+
+4. **Reduce TCP handshake cost.** TCP requires a 3-way handshake (SYN, SYN-ACK, ACK) — one full round trip. Mitigation:
+   - **TCP Fast Open (TFO)** — sends data in the SYN packet on repeat connections, saving 1 RTT
+   - **Increase initial congestion window (initcwnd)** — default is 10 segments (~14.6KB); this determines how much data transfers in the first RTT after handshake
+   - **Connection reuse via keep-alive** — HTTP/1.1 defaults to keep-alive; HTTP/2 multiplexes over one connection
+
+   ```bash
+   # Check and set initcwnd on Linux
+   ip route show
+   ip route change default via <gateway> dev eth0 initcwnd 10 initrwnd 10
+   ```
+
+5. **Optimize TLS negotiation.** TLS adds 1-2 RTTs depending on version:
+   - **TLS 1.2**: 2 additional RTTs (ClientHello -> ServerHello -> Finished)
+   - **TLS 1.3**: 1 additional RTT (combined handshake), 0-RTT on resumption
+
+   Optimization checklist:
+   - Use TLS 1.3 (saves 1 RTT over TLS 1.2)
+   - Enable TLS session resumption (session tickets or session IDs)
+   - Use ECDSA certificates (256-byte signature vs 2048-byte RSA)
+   - Minimize certificate chain length (2-3 certificates maximum)
+   - Enable OCSP stapling (avoids client-side OCSP check adding 100-200ms)
+
+6. **Use preconnect for critical third-party origins.** Preconnect performs DNS + TCP + TLS ahead of time:
+
+   ```html
+   <!-- Preconnect to critical third-party origins -->
+   <link rel="preconnect" href="https://fonts.googleapis.com" />
+   <link rel="preconnect" href="https://cdn.example.com" />
+
+   <!-- Use dns-prefetch as fallback for browsers that don't support preconnect -->
+   <link rel="dns-prefetch" href="https://fonts.googleapis.com" />
+   ```
+
+7. **Enable connection pooling for server-side requests.** Backend services making HTTP requests to other services should reuse connections:
+
+   ```javascript
+   // Node.js: use an HTTP agent with keep-alive
+   const http = require('http');
+   const agent = new http.Agent({
+     keepAlive: true,
+     maxSockets: 50,
+     maxFreeSockets: 10,
+     timeout: 60000,
+   });
+   ```
+
+## Details
+
+### The Connection Cost Breakdown
+
+A new HTTPS connection to a remote server involves three sequential steps:
+
+| Step                | Roundtrips          | Typical Latency (100ms RTT) | Typical Latency (250ms RTT) |
+| ------------------- | ------------------- | --------------------------- | --------------------------- |
+| DNS Resolution      | 1 RTT (if uncached) | 20-120ms                    | 50-250ms                    |
+| TCP Handshake       | 1 RTT               | 100ms                       | 250ms                       |
+| TLS 1.3             | 1 RTT               | 100ms                       | 250ms                       |
+| TLS 1.2             | 2 RTT               | 200ms                       | 500ms                       |
+| **Total (TLS 1.3)** | **3 RTT**           | **220-320ms**               | **550-750ms**               |
+| **Total (TLS 1.2)** | **4 RTT**           | **320-420ms**               | **800-1000ms**              |
+
+Every unique origin incurs this cost for the first request. Subsequent requests on the same connection skip all of it.
+
+### TCP Slow Start and Initial Congestion Window
+
+After the TCP handshake, the connection starts in slow start mode. The initial congestion window (initcwnd) determines how many TCP segments can be sent before receiving an acknowledgment. With initcwnd=10 (the modern default), approximately 14.6KB of data can transfer in the first RTT. This is why inlining critical CSS under 14KB ensures it arrives in the first roundtrip.
+
+### Worked Example: LinkedIn TTFB Optimization
+
+LinkedIn reduced TTFB by 50% by implementing two changes: (1) adding `<link rel="preconnect">` for 3 third-party origins used for fonts, analytics, and advertising — this shifted 300ms of connection setup from the critical path to the preconnect phase, and (2) increasing their server's initcwnd from the legacy default of 3 to 10, allowing the initial HTML response to transfer 14.6KB in the first RTT instead of 4.4KB. Combined, these changes reduced the visible blank-screen time from 1.2s to 0.6s on median mobile connections.
+
+### Worked Example: Yahoo DNS Optimization
+
+Yahoo measured DNS lookup times averaging 20-120ms across global users. They reduced this by 70% through: (1) implementing `<link rel="dns-prefetch">` for all third-party origins in the document head, (2) reducing unique origins from 12 to 4 by consolidating CDN domains, (3) switching to a DNS provider with better global anycast coverage. The reduction in origins alone saved 4-8 full connection handshakes per page load (400-800ms on mobile).
+
+### Anti-Patterns
+
+**Connecting to too many unique origins.** Each origin requires a full handshake chain. A page with 12 unique origins spends 2-4 seconds just on connection establishment on mobile networks. Consolidate to 4 or fewer origins for critical path resources.
+
+**Oversized TLS certificate chains.** Certificate chains exceeding 3KB (3+ intermediate certificates or RSA-4096 keys) require multiple TCP roundtrips to deliver. Use ECDSA certificates (P-256: 64-byte key vs RSA-2048: 256-byte key) and minimize intermediates.
+
+**Not enabling TLS session resumption.** Without session tickets or session IDs, every connection performs a full TLS handshake. Session resumption reduces TLS to 1 RTT (TLS 1.2) or 0 RTT (TLS 1.3). Verify with: `openssl s_client -connect example.com:443 -reconnect`.
+
+**Relying on DNS TTL alone without prefetch hints.** DNS caches expire, and the first visitor after expiry pays the full lookup cost. Always add `dns-prefetch` hints for known third-party origins as a safety net.
+
+## Source
+
+- Ilya Grigorik, "High Performance Browser Networking" (O'Reilly), Chapters 1-4
+- RFC 7918: TLS False Start — https://www.rfc-editor.org/rfc/rfc7918
+- RFC 8446: TLS 1.3 — https://www.rfc-editor.org/rfc/rfc8446
+- Google Research: "An Argument for Increasing TCP's Initial Congestion Window" — https://research.google/pubs/pub36640/
+- W3C Resource Hints Specification — https://www.w3.org/TR/resource-hints/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- Critical path origins are reduced to 4 or fewer with preconnect hints for necessary third-party origins.
+- TLS 1.3 is active with session resumption enabled and OCSP stapling configured.
+- Connection waterfall shows reuse (no repeat DNS/TCP/TLS for same-origin requests).

package/dist/agents/skills/claude-code/perf-connection-costs/skill.yaml

@@ -0,0 +1,40 @@
+name: perf-connection-costs
+version: '1.0.0'
+description: Network connection overhead — DNS resolution, TCP handshake, TLS negotiation, connection reuse, and keep-alive strategies
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-http2-multiplexing
+  - perf-http3-quic
+  - perf-resource-hints
+  - perf-cdn-strategies
+  - perf-critical-rendering-path
+  - node-performance-profiling
+stack_signals: []
+keywords:
+  - dns resolution
+  - tcp handshake
+  - tls negotiation
+  - connection reuse
+  - keep-alive
+  - time to first byte
+  - ttfb
+  - ssl certificate
+  - connection pooling
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-connection-pooling/SKILL.md

@@ -0,0 +1,250 @@
+# Connection Pooling
+
+> Master database connection pooling — pool sizing formulas, connection lifecycle overhead, PgBouncer transaction-mode pooling, serverless connection management, pool monitoring and diagnostics, and configuration for PostgreSQL, MySQL, and managed database services.
+
+## When to Use
+
+- Database connections are exhausted under load ("too many connections" errors)
+- Request latency includes 20-50ms for new connection establishment per query
+- Serverless functions create excessive database connections on cold starts
+- Connection pool is sized too large, consuming database memory and OS resources
+- Idle connections accumulate and hit the database's max_connections limit
+- A connection leak causes pool exhaustion over hours of uptime
+- Multiple application instances share a database with limited connection capacity
+- Database failover causes all pooled connections to become stale
+- Horizontal scaling of application servers multiplies connection count beyond limits
+- Query latency has high variance with spikes correlating to new connection creation
+
+## Instructions
+
+1. **Understand connection overhead.** Each PostgreSQL connection consumes ~5-10MB of RAM on the server and requires a TCP handshake plus TLS negotiation:
+
+   ```
+   Connection establishment cost:
+   - TCP handshake:      ~0.5ms (same datacenter), ~30ms (cross-region)
+   - TLS handshake:      ~2ms (same datacenter), ~60ms (cross-region)
+   - PostgreSQL auth:    ~5ms (password), ~10ms (SCRAM-SHA-256)
+   - Process creation:   ~2ms (PostgreSQL forks per connection)
+   - Total:              ~10ms (local) to ~100ms (cross-region)
+
+   Per-connection memory (PostgreSQL):
+   - work_mem:           4MB default (per operation, can be higher)
+   - Backend memory:     ~5-10MB base
+   - OS resources:       file descriptors, kernel buffers
+   ```
+
+2. **Size the pool correctly.** The optimal pool size depends on workload type, not application concurrency:
+
+   ```
+   Formula (Brian Brazeal / PostgreSQL wiki):
+   pool_size = (core_count * 2) + effective_spindle_count
+
+   For SSD-backed servers:
+   pool_size = core_count * 2 + 1
+
+   Example: 4-core database server with SSD
+   pool_size = (4 * 2) + 1 = 9 connections
+
+   For I/O-bound workloads (many external API calls during transactions):
+   pool_size = core_count * 4
+   ```
+
+   The counterintuitive rule: smaller pools perform better. A pool of 10 connections on a 4-core server outperforms a pool of 200 because fewer connections mean less context switching, less lock contention, and less memory pressure.
+
+3. **Configure application-level pooling.** Set min, max, idle timeout, and connection lifetime:
+
+   ```typescript
+   // Node.js with pg (node-postgres)
+   import { Pool } from 'pg';
+
+   const pool = new Pool({
+     host: process.env.DB_HOST,
+     max: 10, // maximum connections in pool
+     min: 2, // minimum idle connections
+     idleTimeoutMillis: 30000, // close idle connections after 30s
+     connectionTimeoutMillis: 5000, // fail if connection not acquired in 5s
+     maxLifetimeMillis: 1800000, // recycle connections every 30 min
+   });
+
+   // Always return connections to the pool
+   async function query(sql: string, params?: any[]) {
+     const client = await pool.connect();
+     try {
+       return await client.query(sql, params);
+     } finally {
+       client.release(); // CRITICAL: always release back to pool
+     }
+   }
+   ```
+
+   ```typescript
+   // Prisma connection pool configuration
+   // In DATABASE_URL:
+   // postgresql://user:pass@host:5432/db?connection_limit=10&pool_timeout=5
+
+   // Or in schema.prisma for more control:
+   const prisma = new PrismaClient({
+     datasources: {
+       db: {
+         url: process.env.DATABASE_URL + '?connection_limit=10&pool_timeout=5',
+       },
+     },
+   });
+   ```
+
+4. **Deploy PgBouncer for external pooling.** PgBouncer sits between the application and PostgreSQL, multiplexing many client connections onto fewer database connections:
+
+   ```ini
+   ; pgbouncer.ini
+   [databases]
+   myapp = host=pg-primary port=5432 dbname=myapp
+
+   [pgbouncer]
+   listen_addr = 0.0.0.0
+   listen_port = 6432
+   auth_type = scram-sha-256
+   auth_file = /etc/pgbouncer/userlist.txt
+
+   ; Pool mode: transaction (recommended), session, or statement
+   pool_mode = transaction
+
+   ; Pool sizing
+   default_pool_size = 20        ; connections per user/database pair
+   max_client_conn = 1000        ; total client connections accepted
+   max_db_connections = 50       ; max connections to actual PostgreSQL
+   reserve_pool_size = 5         ; extra connections for burst handling
+
+   ; Timeouts
+   server_idle_timeout = 60      ; close idle server connections after 60s
+   client_idle_timeout = 300     ; close idle client connections after 5min
+   query_timeout = 30            ; kill queries running longer than 30s
+   ```
+
+   ```
+   Architecture:
+   [App Server 1] ──┐                     ┌── [PostgreSQL]
+   [App Server 2] ──┤── [PgBouncer] ──────┤   max_connections = 100
+   [App Server 3] ──┘   1000 clients      └── 50 actual connections
+                        → 50 DB conns
+   ```
+
+5. **Handle serverless connection challenges.** Serverless functions create new connections on every cold start. Use external pooling:
+
+   ```typescript
+   // Neon serverless driver — uses WebSocket, handles pooling externally
+   import { neon } from '@neondatabase/serverless';
+   const sql = neon(process.env.DATABASE_URL);
+
+   // Supabase with connection pooling (uses PgBouncer internally)
+   // Use port 6543 for pooled connections instead of 5432
+   // postgresql://user:pass@host:6543/db?pgbouncer=true
+
+   // Prisma with Accelerate (managed connection pooling)
+   // DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=..."
+
+   // AWS RDS Proxy — managed connection pooling for Lambda
+   // Configure in AWS console, use proxy endpoint instead of RDS endpoint
+   ```
+
+6. **Monitor pool health.** Track pool metrics to diagnose issues before they cause outages:
+
+   ```typescript
+   // node-postgres pool events
+   pool.on('connect', () => {
+     metrics.increment('db.pool.connect');
+   });
+   pool.on('acquire', () => {
+     metrics.increment('db.pool.acquire');
+   });
+   pool.on('remove', () => {
+     metrics.increment('db.pool.remove');
+   });
+   pool.on('error', (err) => {
+     metrics.increment('db.pool.error');
+     console.error('Pool error:', err.message);
+   });
+
+   // Periodic health check
+   setInterval(() => {
+     metrics.gauge('db.pool.total', pool.totalCount);
+     metrics.gauge('db.pool.idle', pool.idleCount);
+     metrics.gauge('db.pool.waiting', pool.waitingCount);
+
+     if (pool.waitingCount > 0) {
+       console.warn(`${pool.waitingCount} queries waiting for connections`);
+     }
+   }, 5000);
+   ```
+
+7. **Handle connection failures gracefully.** Connections break due to network issues, database restarts, or failovers:
+
+   ```typescript
+   // Retry with exponential backoff for transient connection failures
+   async function resilientQuery(sql: string, params?: any[], retries = 3) {
+     for (let attempt = 0; attempt < retries; attempt++) {
+       try {
+         return await pool.query(sql, params);
+       } catch (err: any) {
+         const isTransient = [
+           '57P01', // admin_shutdown
+           '57P03', // cannot_connect_now
+           '08006', // connection_failure
+           '08001', // sqlclient_unable_to_establish_sqlconnection
+         ].includes(err.code);
+
+         if (!isTransient || attempt === retries - 1) throw err;
+         await new Promise((r) => setTimeout(r, 100 * Math.pow(2, attempt)));
+       }
+     }
+   }
+   ```
+
+## Details
+
+### Transaction Mode vs Session Mode (PgBouncer)
+
+In **transaction mode**, PgBouncer assigns a server connection for the duration of a transaction, then returns it to the pool. This achieves the highest multiplexing ratio (1000 clients on 20 connections). Limitation: session-level features (SET, LISTEN/NOTIFY, prepared statements, temporary tables) do not work across transactions. In **session mode**, a server connection is held for the entire client session. Lower multiplexing but full feature compatibility. Most applications should use transaction mode.
+
+### Worked Example: Discord Serverless Migration
+
+Discord migrated their message history API from dedicated servers to serverless functions, which caused connection storms — 10,000 concurrent Lambda invocations each opening a database connection. They deployed PgBouncer on a dedicated instance, configured with `pool_mode = transaction`, `default_pool_size = 25`, and `max_client_conn = 15000`. The PgBouncer instance multiplexes 15,000 Lambda connections onto 25 actual PostgreSQL connections. Result: PostgreSQL CPU dropped from 90% to 35%, and p99 latency decreased from 200ms to 45ms because the database was no longer thrashing with 10,000 concurrent connections.
+
+### Worked Example: Vercel Edge Functions + Neon
+
+Vercel's edge functions run in globally distributed isolates that cannot maintain persistent TCP connections. Neon's serverless driver uses HTTP/WebSocket transport instead of raw TCP, with connection pooling handled by Neon's proxy layer. Each edge function invocation sends a query over HTTP — no connection setup, no pool management. The proxy maintains a warm pool of PostgreSQL connections. Result: cold-start database queries complete in 5-10ms (HTTP overhead) versus 50-100ms (TCP connection establishment), and the PostgreSQL server sees a stable 50 connections regardless of edge function concurrency.
+
+### Anti-Patterns
+
+**Setting pool size equal to max_connections.** If pool_size matches max_connections, one application instance monopolizes all database connections, leaving zero for other services, migration scripts, or admin access. Always reserve 20-30% of max_connections for non-application use.
+
+**Not releasing connections back to the pool.** A missing `client.release()` (or failed `finally` block) causes a connection leak. The pool gradually exhausts. Always release in a finally block or use pool.query() which handles acquisition and release automatically.
+
+**Opening a new pool per request.** Creating a `new Pool()` in a request handler establishes a fresh pool for each request instead of reusing connections. Create the pool once at application startup and reuse it.
+
+**Oversizing the pool.** A pool of 100 connections on a 4-core database causes context-switching overhead and lock contention that degrades throughput. Start with `(cores * 2) + 1` and increase only with load testing evidence.
+
+## Source
+
+- PostgreSQL wiki: Number Of Database Connections — https://wiki.postgresql.org/wiki/Number_Of_Database_Connections
+- PgBouncer documentation — https://www.pgbouncer.org/config.html
+- node-postgres: Pooling — https://node-postgres.com/features/pooling
+- Neon serverless driver — https://neon.tech/docs/serverless/serverless-driver
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Connection pool size follows the (cores \* 2) + 1 formula as a starting point.
+- All database interactions use pooled connections with proper release handling.
+- External pooling (PgBouncer or managed proxy) is deployed for multi-instance or serverless architectures.
+- Pool metrics (total, idle, waiting) are monitored with alerts on exhaustion.
+- No connection leaks exist (verified by monitoring idle count stability over time).