git clone https://github.com/paladini/portmap.git && cd portmap
npm ci && npm run build && node dist/cli.js scan /path/to/your-app

Agent:  fetch('http://localhost:3000/api/users')
Reality: Vite on :5173, API on :8080, nothing on :3000

┌─────────────────────────────────────────────────────────────┐
│  Your repo on disk                                          │
├─────────────────────────────────────────────────────────────┤
│  1. Static discovery                                        │
│     package.json scripts · vite.config · .env localhost URLs│
│     docker-compose port mappings                            │
├─────────────────────────────────────────────────────────────┤
│  2. Runtime scan (optional)                                 │
│     OS listeners → port, PID, process, command line           │
├─────────────────────────────────────────────────────────────┤
│  3. Reconcile                                               │
│     declared ↔ actual ↔ env references → service graph        │
│     → .portmap.json + findings (PRT-01 … PRT-07)            │
└─────────────────────────────────────────────────────────────┘
         ↓                    ↓                    ↓
    CLI pretty          MCP tools            CI --min-findings

git clone https://github.com/paladini/portmap.git
cd portmap
npm ci && npm run build

npm run demo:mismatch     # classic agent mistake → 3 errors
npm run demo:workspace    # frontend + API in sibling folders → resolved

portmap — mismatch-app
root: …/fixtures/mismatch

Services:
  [down] vite — Vite dev server
    declared :5173 (vite.config.ts:server.port)
    not listening

Env references:
  NEXT_PUBLIC_API_URL=http://localhost:3000 → :3000 [unresolved]
  VITE_API_URL=http://localhost:8080 → :8080 [unresolved]

Findings: 3 error(s), 0 warning(s)
  ✖ PRT-01 Declared port 5173 is not listening …
  ✖ PRT-04 NEXT_PUBLIC_API_URL points to localhost:3000 but nothing is listening …
  ✖ PRT-04 VITE_API_URL points to localhost:8080 but nothing is listening …

git clone https://github.com/paladini/portmap.git
cd portmap
npm ci && npm run build
node dist/cli.js scan /path/to/your-app

npx portmap scan .

{
  "mcpServers": {
    "portmap": {
      "command": "node",
      "args": ["/path/to/portmap/dist/cli.js", "mcp"]
    }
  }
}

portmap scan . --write
git add .portmap.json   # optional: commit for stable agent context

harness-score  →  Is the repo harness ready for agents?
portmap        →  Do ports and env URLs align locally?
unhappypath    →  Is the UI ready for real users?

npm ci
npm run build
npm test
npm run demo:mismatch
npm run demo:workspace