bugsink mcp and claude subagents - documentation and test fixes

docs/subagents/DEVOPS-GUIDE.md

@@ -51,27 +51,30 @@ The devops subagent understands:
 
 **Container Services:**
 
-| Service | Image | Purpose | Port |
-|---------|-------|---------|------|
-| `app` | Custom (Dockerfile.dev) | Node.js application | 3000, 3001 |
-| `postgres` | postgis/postgis:15-3.4 | Database with PostGIS | 5432 |
-| `redis` | redis:alpine | Caching and job queues | 6379 |
+| Service    | Image                   | Purpose                | Port       |
+| ---------- | ----------------------- | ---------------------- | ---------- |
+| `app`      | Custom (Dockerfile.dev) | Node.js application    | 3000, 3001 |
+| `postgres` | postgis/postgis:15-3.4  | Database with PostGIS  | 5432       |
+| `redis`    | redis:alpine            | Caching and job queues | 6379       |
 
 ### Example Requests
 
 **Container debugging:**
+
 ```
 "Use devops to debug why the dev container fails to start.
 The postgres service shows as unhealthy and the app can't connect."
 ```
 
 **CI/CD pipeline update:**
+
 ```
 "Use devops to add a step to the deploy-to-test.yml workflow
 that runs database migrations before restarting the app."
 ```
 
 **PM2 configuration:**
+
 ```
 "Use devops to update the PM2 ecosystem config to use cluster
 mode with 4 instances instead of max for the API server."
@@ -107,11 +110,11 @@ podman exec -it flyer-crawler-dev npm run test:unit
 
 When running commands from Git Bash on Windows, paths may be incorrectly converted:
 
-| Solution | Example |
-|----------|---------|
+| Solution                   | Example                                                  |
+| -------------------------- | -------------------------------------------------------- |
 | `sh -c` with single quotes | `podman exec container sh -c '/usr/local/bin/script.sh'` |
-| Double slashes | `podman exec container //usr//local//bin//script.sh` |
-| MSYS_NO_PATHCONV=1 | `MSYS_NO_PATHCONV=1 podman exec ...` |
+| Double slashes             | `podman exec container //usr//local//bin//script.sh`     |
+| MSYS_NO_PATHCONV=1         | `MSYS_NO_PATHCONV=1 podman exec ...`                     |
 
 ### PM2 Production Configuration
 
@@ -124,10 +127,10 @@ module.exports = {
       name: 'flyer-crawler-api',
       script: './node_modules/.bin/tsx',
       args: 'server.ts',
-      instances: 'max',        // Use all CPU cores
-      exec_mode: 'cluster',    // Enable cluster mode
+      instances: 'max', // Use all CPU cores
+      exec_mode: 'cluster', // Enable cluster mode
       max_memory_restart: '500M',
-      kill_timeout: 5000,      // Graceful shutdown
+      kill_timeout: 5000, // Graceful shutdown
 
       env_production: {
         NODE_ENV: 'production',
@@ -138,9 +141,9 @@ module.exports = {
       name: 'flyer-crawler-worker',
       script: './node_modules/.bin/tsx',
       args: 'src/services/worker.ts',
-      instances: 1,            // Single instance for workers
+      instances: 1, // Single instance for workers
       max_memory_restart: '1G',
-      kill_timeout: 10000,     // Workers need more time
+      kill_timeout: 10000, // Workers need more time
     },
   ],
 };
@@ -167,9 +170,9 @@ pm2 describe flyer-crawler-api
 
 ### CI/CD Workflow Files
 
-| File | Purpose |
-|------|---------|
-| `.gitea/workflows/deploy-to-prod.yml` | Production deployment |
+| File                                  | Purpose                     |
+| ------------------------------------- | --------------------------- |
+| `.gitea/workflows/deploy-to-prod.yml` | Production deployment       |
 | `.gitea/workflows/deploy-to-test.yml` | Test environment deployment |
 
 **Deployment Flow:**
@@ -227,12 +230,14 @@ The infra-architect subagent understands:
 ### Example Requests
 
 **Memory optimization:**
+
 ```
 "Use infra-architect to analyze memory usage of the worker
 processes. They're frequently hitting the 1GB limit and restarting."
 ```
 
 **Capacity planning:**
+
 ```
 "Use infra-architect to estimate resource requirements for
 handling 10x current traffic. Include database, Redis, and
@@ -240,6 +245,7 @@ application server recommendations."
 ```
 
 **Cost optimization:**
+
 ```
 "Use infra-architect to identify opportunities to reduce
 infrastructure costs without impacting performance."
@@ -247,13 +253,13 @@ infrastructure costs without impacting performance."
 
 ### Resource Limits Reference
 
-| Process | Memory Limit | Notes |
-|---------|--------------|-------|
-| API Server | 500MB | Per cluster instance |
-| Worker | 1GB | Single instance |
-| Analytics Worker | 1GB | Single instance |
-| PostgreSQL | System RAM | Tune `shared_buffers` |
-| Redis | 256MB | `maxmemory` setting |
+| Process          | Memory Limit | Notes                 |
+| ---------------- | ------------ | --------------------- |
+| API Server       | 500MB        | Per cluster instance  |
+| Worker           | 1GB          | Single instance       |
+| Analytics Worker | 1GB          | Single instance       |
+| PostgreSQL       | System RAM   | Tune `shared_buffers` |
+| Redis            | 256MB        | `maxmemory` setting   |
 
 ## The bg-worker Subagent
 
@@ -294,12 +300,14 @@ The bg-worker subagent understands:
 ### Example Requests
 
 **Debugging stuck jobs:**
+
 ```
 "Use bg-worker to debug why jobs are stuck in the flyer processing
 queue. Check for failed jobs, worker status, and Redis connectivity."
 ```
 
 **Adding retry logic:**
+
 ```
 "Use bg-worker to add exponential backoff retry logic to the
 AI extraction job. It should retry up to 3 times with increasing
@@ -307,6 +315,7 @@ delays for rate limit errors."
 ```
 
 **Queue monitoring:**
+
 ```
 "Use bg-worker to add health check endpoints for monitoring
 queue depth and worker status."
@@ -346,7 +355,7 @@ export const flyerWorker = new Worker(
       max: 10,
       duration: 1000,
     },
-  }
+  },
 );
 ```
 
@@ -390,13 +399,13 @@ pm2 delete all
 
 ### Systemd Services (Production)
 
-| Service | Command |
-|---------|---------|
-| PostgreSQL | `sudo systemctl {start|stop|status} postgresql` |
-| Redis | `sudo systemctl {start|stop|status} redis-server` |
-| NGINX | `sudo systemctl {start|stop|status} nginx` |
-| Bugsink | `sudo systemctl {start|stop|status} gunicorn-bugsink` |
-| Logstash | `sudo systemctl {start|stop|status} logstash` |
+| Service    | Command                |
+| ---------- | ---------------------- | ---- | ------------------------- |
+| PostgreSQL | `sudo systemctl {start | stop | status} postgresql`       |
+| Redis      | `sudo systemctl {start | stop | status} redis-server`     |
+| NGINX      | `sudo systemctl {start | stop | status} nginx`            |
+| Bugsink    | `sudo systemctl {start | stop | status} gunicorn-bugsink` |
+| Logstash   | `sudo systemctl {start | stop | status} logstash`         |
 
 ### Health Checks