Add run-app project skill: verified launch recipe for the root DW-ai vision-match server

669e9000e6fa7b68de3fe00efcdeadfe73f7394b · 2026-09-13 00:35:48 -0700 · Steve Abrams

Captures the /run fallback fixes discovered this session — deps often absent
(express+multer), nearby ports held by other pm2 apps, gemini_key=false gates
the metered /api/match path — so the next launch is one step.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Files touched

A .claude/skills/run-app/SKILL.md

Diff

commit 669e9000e6fa7b68de3fe00efcdeadfe73f7394b
Author: Steve Abrams <steve@designerwallcoverings.com>
Date:   Sun Sep 13 00:35:48 2026 -0700

    Add run-app project skill: verified launch recipe for the root DW-ai vision-match server
    
    Captures the /run fallback fixes discovered this session — deps often absent
    (express+multer), nearby ports held by other pm2 apps, gemini_key=false gates
    the metered /api/match path — so the next launch is one step.
    
    Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .claude/skills/run-app/SKILL.md | 51 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/.claude/skills/run-app/SKILL.md b/.claude/skills/run-app/SKILL.md
new file mode 100644
index 0000000..b4c3d67
--- /dev/null
+++ b/.claude/skills/run-app/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: run-app
+description: Launch and drive the designerwallcoverings-ai root app (the "Vision-Match a Room to Wallcovering" Gemini tool, server.js). Use for "/run", "run the app", "start the DW ai app", "launch server.js", or to verify a change to the root storefront/vision-match server works locally. Covers the missing-deps + port-collision gotchas.
+---
+
+# Run the designerwallcoverings-ai root app
+
+The repo root is a small Express app (`designerwallcoverings-ai`, `npm start` = `node server.js`).
+It is the **Vision-Match a Room to Wallcovering** tool (Gemini vision), NOT one of the ~130 pm2
+microservices. It loads ~8,200 products from local data at boot.
+
+## Verified launch recipe
+
+```bash
+cd ~/Projects/designerwallcoverings
+
+# 1. Deps are gitignored and often absent — install if node_modules is missing.
+[ -d node_modules ] || npm install --no-audit --no-fund   # express + multer only, ~79 pkgs
+
+# 2. Default port is 9925. 9925 is usually free, but nearby ports (9926, etc.)
+#    are held by OTHER pm2 apps — a 401 on a "free-looking" port means another
+#    app is there. Pick a genuinely free port and pin BIND to localhost.
+for p in $(seq 9940 9960); do lsof -ti:$p >/dev/null 2>&1 || { PORT=$p; break; }; done
+PORT=$PORT BIND=127.0.0.1 node server.js > /tmp/dwrun.log 2>&1 &
+sleep 2.5; cat /tmp/dwrun.log
+# expect: "designerwallcoverings.ai on http://127.0.0.1:<PORT> · 8227 products · ga=… · gemini_key=false"
+```
+
+## Drive it (routes)
+
+`GET /` · `GET /about` · `GET /ads.txt` · `GET /health` · `POST /api/match` · `POST /api/match-url`
+
+```bash
+B=http://127.0.0.1:$PORT
+curl -s -o /dev/null -w "/ -> %{http_code}\n" $B/           # 200, title "Vision-Match a Room…"
+curl -s $B/health                                           # {"ok":true,"products":8227,...}
+```
+
+## Gotchas
+- **`Cannot find module 'express'`** → deps not installed; run step 1.
+- **`gemini_key=false`** → `GEMINI_API_KEY` is empty in `.env`, so `POST /api/match`
+  (the core room-photo → wallcovering vision call) cannot run. It is a **metered Gemini
+  call (~$0.0006/image)** — only exercise it deliberately, with the key sourced from the
+  secrets store, and show the cost.
+- **Port 9925/9926 confusion** → nearby ports are occupied by other pm2 services; always
+  scan for a free one rather than assuming.
+
+## Cleanup
+```bash
+kill $(lsof -ti:$PORT) 2>/dev/null   # stop the dev instance you started
+```

← b7a7f7e auto-data-snapshot: 2026-09-13T00:21:19 (1 data files) — dat · back to Designerwallcoverings · TK-11564: read-only title_tag catalog-corruption blast-radiu bfbd468 →