jamgate 0.1.0 → 0.4.1

package/README.md

@@ -9,10 +9,15 @@
 > agent reads from and writes to, kept honest at write time. Local-first, no cloud calls,
 > one dependency.
 
+One command wires Jamgate into every MCP client on your machine:
+
 ```bash
-claude mcp add jamgate -- npx jamgate
+npx jamgate setup
 ```
 
+[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000?logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=jamgate&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJqYW1nYXRlIl19)
+ •  one-click **Claude Desktop** bundle → the `.mcpb` on the [latest release](https://github.com/amirj4m/jamgate/releases/latest)
+
 ## The problem: memory quality, not storage
 
 You are one person, but every AI you use is a separate island. You design with one,
@@ -76,15 +81,42 @@ remembered.
 Jamgate runs **locally** — your memory never leaves your machine. Requires Node.js 20+.
 No install step: `npx` fetches and runs it on demand.
 
-### Claude Code
+### Option A — `npx jamgate setup` (recommended)
+
+One command detects the MCP clients installed on your machine (Claude Code, Claude Desktop,
+Cursor, Windsurf) and wires Jamgate into each:
 
 ```bash
-claude mcp add jamgate -- npx jamgate
+npx jamgate setup
+```
+
+It is **safe to run**: idempotent (running it twice changes nothing), it never touches any
+server entry but its own, and it backs up each config file to `<file>.jamgate-backup` before
+writing. Useful flags:
+
+```bash
+npx jamgate setup --dry-run                          # show what would change, write nothing
+npx jamgate setup --remote https://you/mcp --token … # wire HTTP transport (see Remote mode)
+npx jamgate status                                    # show which clients are wired + where the store lives
 ```
 
-### Claude Desktop
+Restart your client(s) afterwards. On Claude Code, when the `claude` CLI is present, setup
+uses `claude mcp add` under the hood; otherwise it merges `~/.claude.json` directly.
 
-Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+### Option B — per-client manual
+
+Prefer to wire it yourself? Each client is a small config change.
+
+**Claude Code:**
+
+```bash
+claude mcp add jamgate -- npx jamgate
+```
+
+**Claude Desktop** — one-click: download the `.mcpb` bundle from the
+[latest release](https://github.com/amirj4m/jamgate/releases/latest) and open it (Claude
+Desktop → Settings → Extensions; the bundle is unsigned, so you may see an "unverified"
+prompt). Or add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
 
 ```json
 {
@@ -97,9 +129,8 @@ Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
 }
 ```
 
-### Cursor
-
-Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
+**Cursor** — click the **Add to Cursor** badge at the top, or add to `~/.cursor/mcp.json`
+(or `.cursor/mcp.json` in a project):
 
 ```json
 {
@@ -112,6 +143,8 @@ Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
 }
 ```
 
+**Windsurf** — add the same `mcpServers` block to `~/.codeium/windsurf/mcp_config.json`.
+
 Restart the agent. It now has three tools:
 
 - **`save_memory`** — store a durable fact. The gate rejects junk, drops exact
@@ -122,7 +155,8 @@ Restart the agent. It now has three tools:
 - **`forget_memory`** — delete a memory by id.
 
 Your memory lives in `~/.jamgate/memory.json`. Same machine, every agent → one shared
-memory.
+memory. To share one memory across **different** machines and your phone, see
+[Remote mode](#remote-mode-self-hosted).
 
 ## Optional: local semantic search
 
@@ -153,6 +187,211 @@ All configuration is via environment variables; every one has a sensible default
 | `JAMGATE_DUP_THRESHOLD` | `0.88` | Semantic near-duplicate sensitivity (0–1); higher = stricter. |
 | `JAMGATE_GATE_LOG` | on | `off` disables the local decision log. |
 | `JAMGATE_TTL_<TYPE>_DAYS` | per type | Override the freshness window for a memory type, e.g. `JAMGATE_TTL_PROJECT_DAYS=180`. |
+| `JAMGATE_HTTP` | off | `1`/`true` enables [remote mode](#remote-mode-self-hosted) (same as the `--http` flag). |
+| `JAMGATE_PORT` | `8420` | Port for remote mode (same as `--port`). |
+| `JAMGATE_HOST` | `127.0.0.1` | Interface to bind in remote mode. Keep it on localhost behind a reverse proxy. |
+| `JAMGATE_TOKEN` | — | Bearer token required in remote mode. The server refuses to start without it. |
+
+## Deploy your own (no terminal needed)
+
+Want one shared memory across your **phone, browser, and laptop** but don't want to run a
+server? Click a button, log into a hosting platform, and you get **your own** Jamgate instance
+with its own URL and token — no terminal, no server knowledge. Same gate, same store as the
+local install; only the transport is over the network (this is [Remote mode](#remote-mode-self-hosted),
+set up for you).
+
+**What you should know first (honest version):**
+
+- **You pay the platform directly — we host nothing.** A tiny always-on instance with a small
+  persistent disk runs roughly **$5–7/month** on Railway or Render. That bill is between you and
+  the platform; Jamgate takes no cut and runs no cloud.
+- **Your instance, your data.** The memory store lives on a disk *in your account* on *your*
+  platform. Jamgate never sees it, never proxies it, has no telemetry. A deploy button is
+  convenience, not hosting — see [DECISIONS D-031](./DECISIONS.md).
+- **Whoever holds the token holds the memory.** The deploy generates a strong bearer token for
+  you. Treat it like a password. There are no per-user accounts (one instance = one person; see
+  [Honest limits](#honest-limits-read-this)).
+
+### Deploy to Render (works today)
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/amirj4m/jamgate)
+
+The button reads [`render.yaml`](./render.yaml) straight from this repo: it builds the image from
+the [`Dockerfile`](./Dockerfile), **generates a random `JAMGATE_TOKEN` for you**, and attaches a
+1 GB persistent disk at `/data` for your memory. Render provisions a paid `starter` instance
+(a disk needs one). After it goes live, read your token under **Environment**, and your URL is
+the service URL with `/mcp` appended (e.g. `https://jamgate-xxxx.onrender.com/mcp`).
+
+### Deploy on Railway
+
+Railway deploys need a *published template* to auto-generate the token and attach the volume —
+that's a one-time step in the maintainer's Railway workspace, so the button below is **not live
+yet**. [`railway.json`](./railway.json) already pins the Dockerfile build and the `/healthz`
+check, so a manual "deploy from repo" works now; the one-click button lands once the template is
+published.
+
+<!-- After publishing the template, paste its code and enable this button:
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/TEMPLATE_CODE)
+-->
+
+*Maintainer steps to make the button live (one time):* create a project from this repo on
+Railway → add a **Volume** mounted at `/data` → add a variable `JAMGATE_TOKEN` with a generated
+value (`${{ secret(32) }}`) → **Settings → Generate Template from Project** → publish, then paste
+the resulting `railway.com/new/template/<code>` URL into the button markdown above.
+
+### Get your URL and token, then connect your devices
+
+Once the deploy is live you have two things: a **URL** ending in `/mcp` and a **token** (from the
+platform's environment/variables tab). Connect each device to the same instance so they share one
+memory:
+
+- **Desktops (Claude Code, Cursor, Windsurf) — one command:**
+
+  ```bash
+  npx jamgate setup --remote https://your-instance/mcp --token <your-token>
+  ```
+
+  This wires every detected client on that machine to your instance (Streamable HTTP clients
+  only; others are skipped with a reason).
+
+- **Phone (Claude app) and claude.ai in a browser:** Settings → **Connectors** → *Add custom
+  connector* → URL `https://your-instance/mcp`, and provide the bearer token when asked. The same
+  three tools (`save_memory`, `recall_memory`, `forget_memory`) then work from your phone.
+
+Save on your phone, recall on your laptop — one memory, everywhere. For the full server-owner
+path (your own VPS, systemd + Caddy), keep reading.
+
+## Remote mode (self-hosted)
+
+By default Jamgate runs **locally over stdio** — one process per agent, on your machine, no
+network. That's the right model for a single computer. But you are one person with agents in
+several places at once: the Claude app on your **phone**, claude.ai in a **browser**, Claude
+Code on a **laptop**. stdio can't be their shared brain — each would get its own local process
+and its own memory.
+
+**Remote mode** is the answer: run **one** Jamgate instance on a server you control, put it
+behind HTTPS, and point every agent at the same URL. Now they share **one** memory of you — save
+on your phone, recall on your laptop. It's the same gate and the same store, just reachable over
+the network. It stays **opt-in**; stdio remains the default and the local-first promise is
+unchanged. Whether it's your own memory or a whole team's, the rule is one instance per person
+(see [Honest limits](#honest-limits-read-this)).
+
+### Run it
+
+```bash
+# A strong token is REQUIRED — the server refuses to start without one.
+export JAMGATE_TOKEN=$(openssl rand -hex 32)
+jamgate --http                 # listens on 127.0.0.1:8420/mcp
+# or: jamgate --http --port 9000     (or JAMGATE_HTTP=1 JAMGATE_PORT=9000)
+```
+
+The MCP endpoint is `/mcp`. Every request must carry `Authorization: Bearer <token>`; anything
+else gets a `401`.
+
+### Security model
+
+- **Bearer token.** One shared secret in `JAMGATE_TOKEN` guards every request, compared in
+  constant time so it can't be recovered from response timing. Generate it with
+  `openssl rand -hex 32`, keep it out of shell history, and rotate it by restarting with a new
+  value.
+- **TLS is terminated by a reverse proxy, not by Jamgate.** Jamgate speaks plain HTTP and binds
+  to `127.0.0.1` by default, so it is never directly exposed. Put **caddy** or **nginx** in
+  front to terminate HTTPS and forward to it locally. A bearer token over plain HTTP on the open
+  internet is a leaked token — **always** run it behind TLS.
+- **Your server, your data.** The store is still a flat file on a disk you own. No Jamgate cloud,
+  no third party, no telemetry. "Self-hosted" means exactly that.
+
+### Deploy: systemd + Caddy
+
+A `systemd` unit to keep Jamgate running (fill in your user and a real token — ideally load the
+token from an `EnvironmentFile` with `600` permissions rather than inlining it):
+
+```ini
+# /etc/systemd/system/jamgate.service
+[Unit]
+Description=Jamgate MCP memory (remote mode)
+After=network.target
+
+[Service]
+# Load JAMGATE_TOKEN=... (and any JAMGATE_* overrides) from a root-only file:
+EnvironmentFile=/etc/jamgate.env
+Environment=JAMGATE_HTTP=1
+Environment=JAMGATE_PORT=8420
+Environment=JAMGATE_STORE=/var/lib/jamgate/memory.json
+ExecStart=/usr/bin/npx jamgate
+User=jamgate
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+echo "JAMGATE_TOKEN=$(openssl rand -hex 32)" | sudo tee /etc/jamgate.env >/dev/null
+sudo chmod 600 /etc/jamgate.env
+sudo systemctl enable --now jamgate
+```
+
+**Caddy** — automatic HTTPS, two lines of real config:
+
+```caddyfile
+memory.example.com {
+    reverse_proxy 127.0.0.1:8420
+}
+```
+
+**nginx** — equivalent, with TLS certs managed by certbot:
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name memory.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/memory.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/memory.example.com/privkey.pem;
+
+    location /mcp {
+        proxy_pass         http://127.0.0.1:8420/mcp;
+        proxy_http_version 1.1;
+        proxy_set_header   Connection "";        # keep-alive for SSE streaming
+        proxy_buffering    off;                  # don't buffer the event stream
+        proxy_read_timeout 3600s;
+    }
+}
+```
+
+### Connect your agents
+
+Point every agent at `https://your-domain/mcp` with the token.
+
+**Claude app (iOS / Android / desktop) and claude.ai** — Settings → Connectors → *Add custom
+connector* → URL `https://your-domain/mcp`, and provide the bearer token when asked. Once
+connected, the same three tools (`save_memory`, `recall_memory`, `forget_memory`) are available
+from your phone and browser.
+
+**Claude Code** — add it as an HTTP MCP server:
+
+```bash
+claude mcp add --transport http jamgate https://your-domain/mcp \
+  --header "Authorization: Bearer <token>"
+```
+
+**Any MCP client** that speaks Streamable HTTP works the same way: URL `https://your-domain/mcp`,
+header `Authorization: Bearer <token>`.
+
+### Honest limits (read this)
+
+- **Whoever holds the token holds the memory.** There are no per-user accounts — the token *is*
+  the authentication. Treat it like a password: strong, secret, rotated on suspicion.
+- **One instance = one human.** Jamgate's memory is *of one person*, by design. There is no
+  multi-user tenancy, no per-identity isolation or access control. That's a deliberate scope
+  choice, not a missing feature — it keeps the security surface to a single secret and a single
+  store. If several people each want a memory, run one instance per person.
+- **Concurrency is single-process.** Multiple agents hitting one instance at once is safe (writes
+  are serialized by a lock and re-read before write). This holds for one Jamgate process on one
+  host; it is not a distributed multi-node store.
+- **No TLS in the box.** If you skip the reverse proxy, you're sending a bearer token in the
+  clear. Don't.
 
 ## How it compares
 
@@ -191,9 +430,9 @@ be local, free, and one command to install.
 
 ## Status
 
-Early but real, and now installable with one command. The MVP core, robustness, and
-intelligence layers all work today (see [`CHANGELOG.md`](./CHANGELOG.md) for the full
-0.1.0 scope):
+Early but real, and now installable with one command. The MVP core, robustness,
+intelligence, and optional remote layers all work today (see [`CHANGELOG.md`](./CHANGELOG.md)
+for the full scope):
 
 - **Gate core** — rule pre-filter, exact dedup, time-aware supersession, source-trust
   conflict guard, over a local flat-file store.
@@ -201,10 +440,19 @@ intelligence layers all work today (see [`CHANGELOG.md`](./CHANGELOG.md) for the
   automatic schema migration.
 - **Intelligence** — trusted client provenance, fuzzy recall, optional local embeddings
   with graceful fallback, auto-subject derivation, local decision log.
-
-Verified end-to-end over the MCP protocol and covered by an automated test suite (89
-tests) on Node 20.x and 22.x. Next: a thin classifier for ambiguous cases (trained on the
-local decision log) and multi-device sync (see [`DECISIONS.md`](./DECISIONS.md)).
+- **Remote mode** *(optional)* — self-hosted Streamable HTTP transport with bearer-token
+  auth, so one instance can serve all of your agents (phone, browser, laptop) from one
+  shared memory. stdio stays the default.
+- **One-click install** — `npx jamgate setup` wires every detected client (Claude Code,
+  Claude Desktop, Cursor, Windsurf) in one idempotent, backup-first command, plus a Cursor
+  deeplink and a Claude Desktop `.mcpb` bundle.
+- **Deploy your own** *(no terminal)* — a `Dockerfile`, a Render blueprint, and a Railway
+  config so a non-technical user can click a button, log into a platform, and get their own
+  hosted instance with a generated token and a persistent disk. We host nothing.
+
+Verified end-to-end over the MCP protocol (both stdio and HTTP) and covered by an automated
+test suite (138 tests) on Node 20.x and 22.x. Next: a thin classifier for ambiguous cases
+(trained on the local decision log) and multi-device sync (see [`DECISIONS.md`](./DECISIONS.md)).
 **Goal: impact, not profit — open-source (MIT), built in the open.**
 
 ## Development

package/dist/http.js

@@ -0,0 +1,270 @@
+import { createServer as createHttpServer, } from "node:http";
+import { randomUUID, timingSafeEqual } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { VERSION } from "./version.js";
+import { createServer } from "./index.js";
+import { resolveGateLogConfig } from "./gate/log.js";
+/**
+ * Optional REMOTE mode for Jamgate (Phase 5, D-029).
+ *
+ * stdio stays the default and the local-first story is unchanged; this module adds an
+ * opt-in Streamable HTTP transport so ONE self-hosted Jamgate instance can serve all of a
+ * single human's MCP clients at once — the phone app, claude.ai, Claude Code on a laptop,
+ * a ChatGPT connector — sharing one memory. It is a generic feature for every Jamgate user,
+ * not bespoke to any deployment.
+ *
+ * Security model (see README "Remote mode"):
+ *  - A bearer token (JAMGATE_TOKEN) gates every request; the comparison is constant-time.
+ *  - TLS is terminated by a reverse proxy (caddy/nginx), never in-process — we bind to
+ *    localhost by default so the proxy is the only public entry point.
+ *  - One instance = one human. Whoever holds the token holds the memory. There is no
+ *    multi-user tenancy by design (D-029).
+ */
+const DEFAULT_PORT = 8420;
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_MCP_PATH = "/mcp";
+const HEALTH_PATH = "/healthz";
+/**
+ * Decide the run mode from CLI args and environment. HTTP mode is opt-in via the `--http`
+ * flag or a truthy `JAMGATE_HTTP` env var; stdio is the default when neither is set. The
+ * port comes from `--port <n>`, else `JAMGATE_PORT`, else the platform's `PORT` (PaaS hosts
+ * such as Railway and Render inject it), else {@link DEFAULT_PORT}. An invalid port falls
+ * back to the default rather than crashing the server on a typo.
+ */
+export function parseCliOptions(argv, env = process.env) {
+    const http = argv.includes("--http") || isTruthyEnv(env.JAMGATE_HTTP);
+    let port;
+    const flagIndex = argv.indexOf("--port");
+    if (flagIndex !== -1 && flagIndex + 1 < argv.length) {
+        port = Number(argv[flagIndex + 1]);
+    }
+    else if (env.JAMGATE_PORT) {
+        port = Number(env.JAMGATE_PORT);
+    }
+    else if (env.PORT) {
+        // Deploy platforms (Railway, Render, Heroku, …) assign the listen port via $PORT and
+        // expect the app to honor it. JAMGATE_PORT still wins so an explicit override is possible.
+        port = Number(env.PORT);
+    }
+    if (port === undefined || !Number.isInteger(port) || port < 0 || port > 65535) {
+        port = DEFAULT_PORT;
+    }
+    return { http, port };
+}
+function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    const v = value.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+/**
+ * Constant-time check of an `Authorization: Bearer <token>` header against the expected
+ * token. Returns false for a missing/malformed header or any mismatch. The comparison uses
+ * `timingSafeEqual` so an attacker can't learn the token byte-by-byte from response timing;
+ * when the lengths differ we still run one comparison (against the presented value itself)
+ * to avoid leaking the token length through an early return.
+ */
+export function bearerTokenMatches(authorizationHeader, expectedToken) {
+    if (!authorizationHeader)
+        return false;
+    const prefix = "Bearer ";
+    if (!authorizationHeader.startsWith(prefix))
+        return false;
+    const presented = Buffer.from(authorizationHeader.slice(prefix.length).trim(), "utf8");
+    const expected = Buffer.from(expectedToken, "utf8");
+    if (presented.length !== expected.length) {
+        // Length already differs, so it can't match — but compare presented against itself so
+        // the work (and thus the timing) doesn't depend on the expected token's length.
+        timingSafeEqual(presented, presented);
+        return false;
+    }
+    return timingSafeEqual(presented, expected);
+}
+/**
+ * Start the HTTP transport and resolve once it is listening. Each MCP session gets its own
+ * `StreamableHTTPServerTransport` and its own `createServer(store)` instance (so the
+ * per-connection handshake provenance in D-024 still works over HTTP), all sharing the one
+ * injected store. Sessions are tracked by the `mcp-session-id` header per the SDK's stateful
+ * Streamable HTTP pattern, and torn down when the client disconnects or DELETEs the session.
+ */
+export function startHttpServer(opts) {
+    const host = opts.host ?? process.env.JAMGATE_HOST ?? DEFAULT_HOST;
+    const path = opts.path ?? DEFAULT_MCP_PATH;
+    const port = opts.port ?? DEFAULT_PORT;
+    const gateLog = opts.gateLog ?? resolveGateLogConfig();
+    // Live sessions, keyed by the session id the transport assigns at initialize time.
+    const transports = new Map();
+    const httpServer = createHttpServer((req, res) => {
+        handleRequest(req, res, { store: opts.store, token: opts.token, path, transports, gateLog }).catch((err) => {
+            console.error("jamgate http: unhandled request error:", err);
+            if (!res.headersSent) {
+                sendJson(res, 500, {
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+            else {
+                res.end();
+            }
+        });
+    });
+    return new Promise((resolve, reject) => {
+        httpServer.once("error", reject);
+        httpServer.listen(port, host, () => {
+            httpServer.removeListener("error", reject);
+            const addr = httpServer.address();
+            const boundPort = typeof addr === "object" && addr ? addr.port : port;
+            resolve({
+                server: httpServer,
+                port: boundPort,
+                host,
+                path,
+                close: () => new Promise((res2, rej2) => {
+                    for (const t of transports.values())
+                        void t.close();
+                    transports.clear();
+                    httpServer.close((err) => (err ? rej2(err) : res2()));
+                }),
+            });
+        });
+    });
+}
+async function handleRequest(req, res, ctx) {
+    // 0. Health check — deliberately BEFORE the auth gate and outside the MCP endpoint. Deploy
+    //    platforms (Railway, Render, …) probe an unauthenticated URL to decide if the container
+    //    is live, so this must answer 200 without a token. It exposes only liveness + version —
+    //    never any memory, session, or config data (RULES §10: nothing leaks).
+    const reqPath = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`).pathname;
+    if (reqPath === HEALTH_PATH) {
+        if (req.method === "GET" || req.method === "HEAD") {
+            sendJson(res, 200, { status: "ok", version: VERSION });
+        }
+        else {
+            res.setHeader("Allow", "GET, HEAD");
+            sendJson(res, 405, {
+                jsonrpc: "2.0",
+                error: { code: -32000, message: `Method ${req.method} not allowed` },
+                id: null,
+            });
+        }
+        return;
+    }
+    // 1. Auth gate — before anything else, on every method. A missing/wrong token is a flat
+    //    401; we never fall through to session handling for an unauthenticated request.
+    if (!bearerTokenMatches(req.headers.authorization, ctx.token)) {
+        res.setHeader("WWW-Authenticate", 'Bearer realm="jamgate"');
+        sendJson(res, 401, {
+            jsonrpc: "2.0",
+            error: { code: -32001, message: "Unauthorized: valid bearer token required" },
+            id: null,
+        });
+        return;
+    }
+    // 2. Past the auth gate, only the MCP endpoint exists (the unauthenticated `/healthz` was
+    //    already handled in step 0). Everything else is 404.
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    if (url.pathname !== ctx.path) {
+        sendJson(res, 404, {
+            jsonrpc: "2.0",
+            error: { code: -32601, message: `Not found. MCP endpoint is ${ctx.path}` },
+            id: null,
+        });
+        return;
+    }
+    const sessionId = header(req, "mcp-session-id");
+    if (req.method === "POST") {
+        const body = await readJsonBody(req);
+        if (body === PARSE_ERROR) {
+            sendJson(res, 400, {
+                jsonrpc: "2.0",
+                error: { code: -32700, message: "Parse error: request body is not valid JSON" },
+                id: null,
+            });
+            return;
+        }
+        let transport = sessionId ? ctx.transports.get(sessionId) : undefined;
+        if (!transport) {
+            if (isInitializeRequest(body)) {
+                // New session: spin up a fresh transport + its own server, sharing the store.
+                transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (sid) => {
+                        ctx.transports.set(sid, transport);
+                    },
+                });
+                transport.onclose = () => {
+                    const sid = transport.sessionId;
+                    if (sid)
+                        ctx.transports.delete(sid);
+                };
+                const server = createServer(ctx.store, ctx.gateLog);
+                await server.connect(transport);
+            }
+            else {
+                // Not an initialize and no known session → the client must initialize first.
+                sendJson(res, 400, {
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32000,
+                        message: "Bad Request: no valid session id; send an initialize request first",
+                    },
+                    id: null,
+                });
+                return;
+            }
+        }
+        await transport.handleRequest(req, res, body);
+        return;
+    }
+    if (req.method === "GET" || req.method === "DELETE") {
+        // GET opens the server→client SSE stream; DELETE ends the session. Both need a session.
+        const transport = sessionId ? ctx.transports.get(sessionId) : undefined;
+        if (!transport) {
+            sendJson(res, 400, {
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "Bad Request: unknown or missing session id" },
+                id: null,
+            });
+            return;
+        }
+        await transport.handleRequest(req, res);
+        return;
+    }
+    res.setHeader("Allow", "GET, POST, DELETE");
+    sendJson(res, 405, {
+        jsonrpc: "2.0",
+        error: { code: -32000, message: `Method ${req.method} not allowed` },
+        id: null,
+    });
+}
+function header(req, name) {
+    const v = req.headers[name];
+    return Array.isArray(v) ? v[0] : v;
+}
+const PARSE_ERROR = Symbol("parse-error");
+/** Read and JSON-parse the request body. Returns the parsed value, `undefined` for an empty
+ *  body, or the {@link PARSE_ERROR} sentinel when the body isn't valid JSON. */
+async function readJsonBody(req) {
+    const raw = await new Promise((resolve, reject) => {
+        let data = "";
+        req.setEncoding("utf8");
+        req.on("data", (chunk) => (data += chunk));
+        req.on("end", () => resolve(data));
+        req.on("error", reject);
+    });
+    if (raw.trim() === "")
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return PARSE_ERROR;
+    }
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(payload);
+}

package/dist/index.js

@@ -2,9 +2,13 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
+import { VERSION } from "./version.js";
 import { FileStore } from "./store/fileStore.js";
 import { loadTransformersEmbedder, resolveDupThreshold } from "./embeddings/embedder.js";
+import { parseCliOptions, startHttpServer } from "./http.js";
+import { setupCommand, statusCommand } from "./setup/cli.js";
 import { prefilter } from "./gate/prefilter.js";
 import { deriveSubject } from "./gate/subject.js";
 import { appendGateLog, resolveGateLogConfig, } from "./gate/log.js";
@@ -14,7 +18,7 @@ import { appendGateLog, resolveGateLogConfig, } from "./gate/log.js";
  * client provenance is captured from the handshake, D-024) without spawning a process.
  */
 export function createServer(store, gateLog = resolveGateLogConfig()) {
-    const server = new Server({ name: "jamgate", version: "0.1.0" }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "jamgate", version: VERSION }, { capabilities: { tools: {} } });
     /** The MCP client behind the current connection, taken from the `clientInfo` the client
      *  sent in the `initialize` handshake (D-024). This is server-observed provenance — the
      *  calling agent cannot spoof it through tool arguments. Undefined until the handshake
@@ -173,8 +177,9 @@ export function createServer(store, gateLog = resolveGateLogConfig()) {
     });
     return server;
 }
-async function main() {
-    // Optional local embeddings (D-026): try to load the model; null → fuzzy recall only.
+/** Build the default FileStore, wiring in optional local embeddings (D-026). Shared by the
+ *  stdio and HTTP bootstraps so both run identical gate/store behaviour. */
+async function buildStore() {
     // Loading is lazy and best-effort so the base install and offline/CI runs work unchanged.
     const embedder = await loadTransformersEmbedder();
     if (embedder)
@@ -182,18 +187,68 @@ async function main() {
     else
         console.error("jamgate: running on fuzzy recall (no embedding model loaded)");
     // Depend on the adapter contract, not a concrete backend (D-019).
-    const store = new FileStore(undefined, {
+    return new FileStore(undefined, {
         embedder: embedder ?? undefined,
         dupThreshold: resolveDupThreshold(),
     });
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    // Install-helper subcommands run before any store/server bootstrap — they only touch client
+    // config files, never the memory store or a transport (the One-Click Install phase, D-030).
+    if (argv[0] === "setup") {
+        process.exitCode = await setupCommand(argv.slice(1));
+        return;
+    }
+    if (argv[0] === "status") {
+        process.exitCode = await statusCommand();
+        return;
+    }
+    const opts = parseCliOptions(argv);
+    const store = await buildStore();
+    if (opts.http) {
+        // Opt-in remote mode (D-029). stdio stays the default; this only runs on --http /
+        // JAMGATE_HTTP. A bearer token is mandatory — refuse to start without one, rather than
+        // silently exposing a memory over the network.
+        const token = process.env.JAMGATE_TOKEN;
+        if (!token || token.trim() === "") {
+            console.error("jamgate: HTTP mode requires a bearer token, but JAMGATE_TOKEN is not set.\n" +
+                "  Set a strong secret and restart, e.g.:\n" +
+                "    JAMGATE_TOKEN=$(openssl rand -hex 32) jamgate --http\n" +
+                "  TLS must be terminated by a reverse proxy (caddy/nginx); see the README " +
+                '"Remote mode" section. Refusing to start.');
+            process.exit(1);
+        }
+        const running = await startHttpServer({ store, token, port: opts.port });
+        console.error(`jamgate MCP server running on http://${running.host}:${running.port}${running.path} ` +
+            "(bearer auth required; terminate TLS at a reverse proxy)");
+        return;
+    }
     const server = createServer(store);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // stdout is the MCP channel; logs must go to stderr.
     console.error("jamgate MCP server running on stdio");
 }
-// Only bootstrap stdio when run as the CLI entrypoint, not when imported by a test.
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+/** True when this module is the process entrypoint (run as the CLI), not imported by a test.
+ *  Must compare against the *realpath* of `process.argv[1]`: npm/npx install the bin as a
+ *  symlink (`node_modules/.bin/jamgate` → the real `dist/index.js`), so `process.argv[1]` is
+ *  the symlink path while `import.meta.url` is the resolved target. A naive equality check
+ *  fails there and `main()` never runs — the wizard exits 0 with no output (the 0.4.0 bug).
+ *  Resolving the symlink first makes both sides the same real file. */
+function isMainEntrypoint() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+    }
+    catch {
+        // realpathSync throws if the path doesn't exist; fall back to the raw comparison.
+        return import.meta.url === pathToFileURL(entry).href;
+    }
+}
+if (isMainEntrypoint()) {
     main().catch((err) => {
         console.error("jamgate fatal:", err);
         process.exit(1);

package/dist/setup/cli.js

@@ -0,0 +1,199 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { runSetup, runStatus, } from "./runner.js";
+/**
+ * Terminal front-end for `jamgate setup` and `jamgate status`: parse argv, run the (pure-ish)
+ * runner, and print a clear per-client report. Kept separate from `runner.ts` so the wiring
+ * logic can be unit-tested without going through argv parsing or console output.
+ */
+const execFileAsync = promisify(execFile);
+const VALID_CLIENTS = ["claude-code", "claude-desktop", "cursor", "windsurf"];
+/** Parse `setup` flags: `--dry-run`, `--remote <url>`, `--token <token>`, `--client <id>...`. */
+export function parseSetupArgs(argv, env) {
+    let dryRun = false;
+    let url;
+    let token = env.JAMGATE_TOKEN;
+    const only = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--remote") {
+            url = argv[++i];
+            if (!url)
+                return { mode: "remote", dryRun, error: "--remote requires a URL argument" };
+        }
+        else if (arg === "--token") {
+            token = argv[++i];
+            if (!token)
+                return { mode: "stdio", dryRun, error: "--token requires a value" };
+        }
+        else if (arg === "--client") {
+            const id = argv[++i];
+            if (!VALID_CLIENTS.includes(id)) {
+                return {
+                    mode: "stdio",
+                    dryRun,
+                    error: `unknown --client "${id}" (expected one of: ${VALID_CLIENTS.join(", ")})`,
+                };
+            }
+            only.push(id);
+        }
+        else {
+            return { mode: "stdio", dryRun, error: `unknown argument "${arg}"` };
+        }
+    }
+    const mode = url ? "remote" : "stdio";
+    if (mode === "remote" && !token) {
+        return {
+            mode,
+            url,
+            dryRun,
+            error: "remote mode requires a bearer token — pass --token <token> or set JAMGATE_TOKEN " +
+                "(it must match the token the remote jamgate server runs with)",
+        };
+    }
+    return { mode, url, token, dryRun, only: only.length ? only : undefined };
+}
+/** The real `claude` CLI adapter. `isAvailable` probes `claude --version`; `add` shells out to
+ *  `claude mcp add --scope user`. Both swallow failures into a boolean so the runner can fall
+ *  back to a direct JSON merge rather than leaving Claude Code unwired. */
+export const realClaudeCli = {
+    async isAvailable() {
+        try {
+            await execFileAsync("claude", ["--version"], { timeout: 10_000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async add(spec) {
+        try {
+            await execFileAsync("claude", claudeAddArgs(spec), { timeout: 30_000 });
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, stderr: err instanceof Error ? err.message : String(err) };
+        }
+    },
+    previewCommand(spec) {
+        return `claude ${claudeAddArgs(spec).join(" ")}`;
+    },
+};
+/** Build the argv for `claude mcp add` for a given transport (shared by add + previewCommand). */
+function claudeAddArgs(spec) {
+    if (spec.mode === "remote") {
+        const args = ["mcp", "add", "--scope", "user", "--transport", "http", "jamgate", spec.url ?? ""];
+        if (spec.token)
+            args.push("--header", `Authorization: Bearer ${spec.token}`);
+        return args;
+    }
+    return ["mcp", "add", "--scope", "user", "jamgate", "--", "npx", "jamgate"];
+}
+const SYMBOL = {
+    configured: "✓",
+    updated: "✓",
+    "already-configured": "•",
+    "not-found": "–",
+    skipped: "–",
+    error: "✗",
+};
+function describe(r) {
+    const verb = r.dryRun ? "would be " : "";
+    switch (r.outcome) {
+        case "configured":
+            return `${r.dryRun ? "would configure" : "configured"} (${r.transport})`;
+        case "updated":
+            return `${r.dryRun ? "would update" : "updated"} (${r.transport})`;
+        case "already-configured":
+            return "already configured";
+        case "not-found":
+            return "not found";
+        case "skipped":
+            return `${verb}skipped`;
+        case "error":
+            return "error";
+    }
+}
+/** Format the setup report as lines of terminal text. */
+export function formatSetupReport(results, opts) {
+    const lines = [];
+    lines.push(opts.dryRun ? "jamgate setup — dry run (no files written)\n" : "jamgate setup\n");
+    for (const r of results) {
+        let line = `  ${SYMBOL[r.outcome]} ${r.label.padEnd(15)} ${describe(r)}`;
+        if (r.detail && (r.outcome === "not-found" || r.outcome === "skipped" || r.outcome === "error")) {
+            line += ` — ${r.detail}`;
+        }
+        lines.push(line);
+        if (r.path && (r.outcome === "configured" || r.outcome === "updated")) {
+            const via = r.method === "claude-cli" ? "claude mcp add" : r.path;
+            lines.push(`      ${r.dryRun ? "target" : "via"}: ${via}${r.backedUp ? " (backup written)" : ""}`);
+        }
+    }
+    const configured = results.filter((r) => r.outcome === "configured" || r.outcome === "updated");
+    const already = results.filter((r) => r.outcome === "already-configured");
+    lines.push("");
+    if (opts.dryRun) {
+        lines.push(`  ${configured.length} client(s) would change, ${already.length} already configured. ` +
+            "Re-run without --dry-run to apply.");
+    }
+    else {
+        lines.push(`  Done: ${configured.length} configured, ${already.length} already configured. ` +
+            "Restart your client(s) to pick up jamgate.");
+    }
+    return lines.join("\n");
+}
+/** Format the status report as lines of terminal text. */
+export function formatStatusReport(report) {
+    const lines = ["jamgate status\n"];
+    for (const c of report.clients) {
+        const mark = c.wired ? "✓" : c.detected ? "•" : "–";
+        const state = c.wired
+            ? `wired (${c.transport})`
+            : c.detected
+                ? "detected, not wired"
+                : "not found";
+        lines.push(`  ${mark} ${c.label.padEnd(15)} ${state}`);
+        if (c.wired && c.path)
+            lines.push(`      ${c.path}`);
+    }
+    lines.push("");
+    lines.push(`  store: ${report.storePath}`);
+    return lines.join("\n");
+}
+/** Entry point for `jamgate setup`. Returns a process exit code. */
+export async function setupCommand(argv, deps = {}) {
+    const env = deps.env ?? process.env;
+    const log = deps.log ?? ((m) => console.log(m));
+    const parsed = parseSetupArgs(argv, env);
+    if (parsed.error) {
+        log(`jamgate setup: ${parsed.error}`);
+        return 1;
+    }
+    const options = {
+        mode: parsed.mode,
+        url: parsed.url,
+        token: parsed.token,
+        dryRun: parsed.dryRun,
+        only: parsed.only,
+        platform: deps.platform,
+        env,
+        claudeCli: deps.claudeCli ?? realClaudeCli,
+    };
+    const results = await runSetup(options);
+    log(formatSetupReport(results, { dryRun: parsed.dryRun }));
+    return 0;
+}
+/** Entry point for `jamgate status`. Returns a process exit code. */
+export async function statusCommand(deps = {}) {
+    const log = deps.log ?? ((m) => console.log(m));
+    const report = await runStatus({
+        env: deps.env,
+        platform: deps.platform,
+        claudeCli: deps.claudeCli ?? realClaudeCli,
+    });
+    log(formatStatusReport(report));
+    return 0;
+}

package/dist/setup/clients.js

@@ -0,0 +1,137 @@
+import { join } from "node:path";
+/** Resolve the user's home directory from the environment (test-injectable). */
+function home(env) {
+    return env.HOME || env.USERPROFILE || null;
+}
+/** Resolve the base config directory used by Claude Desktop, per platform. */
+function claudeDesktopDir(platform, env) {
+    const h = home(env);
+    if (platform === "darwin") {
+        return h ? join(h, "Library", "Application Support", "Claude") : null;
+    }
+    if (platform === "win32") {
+        return env.APPDATA ? join(env.APPDATA, "Claude") : null;
+    }
+    // Linux and everything else follow the XDG base-dir spec.
+    const base = env.XDG_CONFIG_HOME || (h ? join(h, ".config") : null);
+    return base ? join(base, "Claude") : null;
+}
+export const CLIENTS = [
+    {
+        id: "claude-code",
+        label: "Claude Code",
+        serverKey: "jamgate",
+        supportsRemote: true,
+        configPath(_platform, env) {
+            const h = home(env);
+            return h ? join(h, ".claude.json") : null;
+        },
+        detectPaths(_platform, env) {
+            const h = home(env);
+            // The config file itself is the strongest signal; the CLI is detected separately in the
+            // runner (it may be on PATH before the file exists on a very fresh install).
+            return h ? [join(h, ".claude.json")] : [];
+        },
+    },
+    {
+        id: "claude-desktop",
+        label: "Claude Desktop",
+        serverKey: "jamgate",
+        // Claude Desktop installs local (stdio) servers natively; remote servers go through the
+        // connectors UI / mcp-remote, not a plain HTTP entry, so we don't claim remote support.
+        supportsRemote: false,
+        configPath(platform, env) {
+            const dir = claudeDesktopDir(platform, env);
+            return dir ? join(dir, "claude_desktop_config.json") : null;
+        },
+        detectPaths(platform, env) {
+            const dir = claudeDesktopDir(platform, env);
+            return dir ? [dir] : [];
+        },
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        serverKey: "jamgate",
+        supportsRemote: true,
+        configPath(_platform, env) {
+            const h = home(env);
+            return h ? join(h, ".cursor", "mcp.json") : null;
+        },
+        detectPaths(_platform, env) {
+            const h = home(env);
+            return h ? [join(h, ".cursor")] : [];
+        },
+    },
+    {
+        id: "windsurf",
+        label: "Windsurf",
+        serverKey: "jamgate",
+        // Windsurf's remote support is SSE-based (`serverUrl`) rather than Streamable HTTP; rather
+        // than write an entry we haven't verified round-trips, we wire stdio only.
+        supportsRemote: false,
+        configPath(_platform, env) {
+            const h = home(env);
+            return h ? join(h, ".codeium", "windsurf", "mcp_config.json") : null;
+        },
+        detectPaths(_platform, env) {
+            const h = home(env);
+            return h ? [join(h, ".codeium", "windsurf")] : [];
+        },
+    },
+];
+export function clientById(id) {
+    const def = CLIENTS.find((c) => c.id === id);
+    if (!def)
+        throw new Error(`Unknown client id: ${id}`);
+    return def;
+}
+/**
+ * Build the server entry to write for a given client and mode. The stdio entry runs the
+ * published package with `npx jamgate` so it always tracks the installed version; the remote
+ * entry points at the user's self-hosted HTTP endpoint with a bearer header. Claude Code gets
+ * an explicit `type` to match how its own `claude mcp add` records entries.
+ */
+export function buildEntry(client, params) {
+    if (params.mode === "remote") {
+        if (!params.url)
+            throw new Error("remote mode requires a url");
+        const headers = {};
+        if (params.token)
+            headers.Authorization = `Bearer ${params.token}`;
+        const entry = { url: params.url };
+        if (Object.keys(headers).length > 0)
+            entry.headers = headers;
+        if (client.id === "claude-code")
+            entry.type = "http";
+        return entry;
+    }
+    const entry = { command: "npx", args: ["jamgate"] };
+    // Claude Code records stdio servers as {type, command, args, env}. Match that shape exactly
+    // so an entry written by `claude mcp add` is recognised as already-configured on re-run
+    // (otherwise the empty `env` would read as a spurious diff and re-"update" every run).
+    if (client.id === "claude-code") {
+        entry.type = "stdio";
+        entry.env = {};
+    }
+    return entry;
+}
+/**
+ * The bare per-server config object Cursor's one-click deeplink base64-encodes. Cursor's
+ * deeplink takes the server config WITHOUT the `mcpServers` wrapper (verified against Cursor's
+ * install-links docs), so this mirrors {@link buildEntry} for Cursor but is exposed separately
+ * for the README badge generator and its test.
+ */
+export function cursorDeeplinkConfig(params = { mode: "stdio" }) {
+    return buildEntry(clientById("cursor"), params);
+}
+/**
+ * Generate Cursor's official one-click install deeplink for Jamgate. Shape verified against
+ * Cursor docs: `cursor://anysphere.cursor-deeplink/mcp/install?name=<name>&config=<base64>`
+ * where `<base64>` is the base64 of the bare server config JSON.
+ */
+export function cursorDeeplink(params = { mode: "stdio" }) {
+    const config = cursorDeeplinkConfig(params);
+    const base64 = Buffer.from(JSON.stringify(config), "utf8").toString("base64");
+    return `cursor://anysphere.cursor-deeplink/mcp/install?name=jamgate&config=${base64}`;
+}

package/dist/setup/merge.js

@@ -0,0 +1,52 @@
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Structural deep-equality, sufficient for the JSON server entries we compare. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const ak = Object.keys(a);
+        const bk = Object.keys(b);
+        if (ak.length !== bk.length)
+            return false;
+        return ak.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/**
+ * Compute the merge of a jamgate server entry into an existing (parsed) config document.
+ *
+ * @param existing  The parsed config, or undefined if the file did not exist. Anything that
+ *                  is not a plain object is treated as absent (we start fresh, preserving
+ *                  nothing we can't understand — the caller backs up first).
+ * @param key       The server key to manage (always "jamgate").
+ * @param entry     The desired server entry.
+ */
+export function planMerge(existing, key, entry) {
+    const hadValidRoot = isPlainObject(existing);
+    const root = hadValidRoot ? { ...existing } : {};
+    const hadServers = isPlainObject(root.mcpServers);
+    const servers = hadServers
+        ? { ...root.mcpServers }
+        : {};
+    const current = servers[key];
+    if (current !== undefined && deepEqual(current, entry)) {
+        return { config: root, status: "already-configured", changed: false };
+    }
+    const status = current !== undefined
+        ? "updated"
+        : !hadValidRoot || !hadServers
+            ? "created"
+            : "configured";
+    servers[key] = entry;
+    root.mcpServers = servers;
+    return { config: root, status, changed: true };
+}

package/dist/setup/runner.js

@@ -0,0 +1,194 @@
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { CLIENTS, buildEntry, } from "./clients.js";
+import { planMerge } from "./merge.js";
+/**
+ * The IO layer of `jamgate setup` / `jamgate status`. Given a platform + environment (both
+ * injectable so tests run entirely against a temp home), it detects installed MCP clients,
+ * wires Jamgate into each safely, and reports per-client outcomes.
+ *
+ * Safety guarantees (see DECISIONS D-030):
+ *  - Idempotent: a second run changes nothing.
+ *  - Never clobbers other servers or other fields — only the `jamgate` key is managed.
+ *  - Backs up any config file to `<file>.jamgate-backup` before overwriting it.
+ *  - `--dry-run` computes and reports every change without writing anything.
+ */
+/** The suffix appended to a config file to hold its pre-write backup. */
+export const BACKUP_SUFFIX = ".jamgate-backup";
+async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read + JSON-parse a config file. Returns undefined if the file is absent, and the special
+ *  { __malformed: true } marker if it exists but isn't valid JSON (so we still back it up). */
+async function readConfig(path) {
+    if (!(await pathExists(path)))
+        return { existing: undefined, malformed: false, fileExists: false };
+    const raw = await fs.readFile(path, "utf8");
+    if (raw.trim() === "")
+        return { existing: undefined, malformed: false, fileExists: true };
+    try {
+        return { existing: JSON.parse(raw), malformed: false, fileExists: true };
+    }
+    catch {
+        return { existing: undefined, malformed: true, fileExists: true };
+    }
+}
+/** Atomically-ish write: back up any existing file, then write pretty JSON with a trailing
+ *  newline (matches how these editors format their own configs). */
+async function writeConfig(path, config, fileExists) {
+    await fs.mkdir(dirname(path), { recursive: true });
+    let backedUp = false;
+    if (fileExists) {
+        await fs.copyFile(path, path + BACKUP_SUFFIX);
+        backedUp = true;
+    }
+    await fs.writeFile(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+    return backedUp;
+}
+/** Is the given client installed on this machine? A config file/dir existing is the signal;
+ *  Claude Code additionally counts as present when the `claude` CLI is available. */
+async function isDetected(client, platform, env, claudeCli) {
+    for (const p of client.detectPaths(platform, env)) {
+        if (await pathExists(p))
+            return true;
+    }
+    if (client.id === "claude-code" && claudeCli && (await claudeCli.isAvailable()))
+        return true;
+    return false;
+}
+async function configureClient(client, opts, platform, env) {
+    const base = {
+        id: client.id,
+        label: client.label,
+        path: client.configPath(platform, env),
+        transport: opts.mode,
+        outcome: "not-found",
+        backedUp: false,
+        dryRun: opts.dryRun,
+    };
+    // Remote mode only applies to clients that actually speak Streamable HTTP.
+    if (opts.mode === "remote" && !client.supportsRemote) {
+        return {
+            ...base,
+            outcome: "skipped",
+            detail: "no verified HTTP transport — install stdio instead, or use a connector",
+        };
+    }
+    if (!(await isDetected(client, platform, env, opts.claudeCli))) {
+        return { ...base, outcome: "not-found", detail: "client not detected on this machine" };
+    }
+    const path = base.path;
+    if (!path) {
+        return { ...base, outcome: "skipped", detail: "no supported config path on this platform" };
+    }
+    const entry = buildEntry(client, {
+        mode: opts.mode,
+        url: opts.url,
+        token: opts.token,
+    });
+    // Decide the outcome from the current file state first (uniform across CLI and merge paths).
+    const { existing, malformed, fileExists } = await readConfig(path);
+    const plan = planMerge(existing, client.serverKey, entry);
+    if (plan.status === "already-configured") {
+        return { ...base, outcome: "already-configured" };
+    }
+    const outcome = plan.status === "updated" ? "updated" : "configured";
+    // Prefer `claude mcp add` for a FRESH Claude Code add when the CLI is present; updates and
+    // every other case go through the deterministic JSON merge (which cleanly replaces our key).
+    const useCli = client.id === "claude-code" &&
+        opts.claudeCli !== undefined &&
+        plan.status !== "updated" &&
+        (await opts.claudeCli.isAvailable());
+    if (opts.dryRun) {
+        const detail = useCli && opts.claudeCli
+            ? `would run: ${opts.claudeCli.previewCommand({ mode: opts.mode, url: opts.url, token: opts.token })}`
+            : malformed
+                ? "would rewrite malformed config (original backed up)"
+                : `would write ${path}`;
+        return {
+            ...base,
+            outcome,
+            method: useCli ? "claude-cli" : "json-merge",
+            detail,
+        };
+    }
+    if (useCli && opts.claudeCli) {
+        const res = await opts.claudeCli.add({ mode: opts.mode, url: opts.url, token: opts.token });
+        if (res.ok) {
+            return { ...base, outcome, method: "claude-cli" };
+        }
+        // CLI failed for some reason — fall through to the JSON merge so the client still gets wired.
+    }
+    const backedUp = await writeConfig(path, plan.config, fileExists);
+    return { ...base, outcome, method: "json-merge", backedUp };
+}
+/** Run `jamgate setup` across all (or a subset of) clients. */
+export async function runSetup(opts) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
+    const clients = CLIENTS.filter((c) => !opts.only || opts.only.includes(c.id));
+    const results = [];
+    for (const client of clients) {
+        try {
+            results.push(await configureClient(client, {
+                mode: opts.mode,
+                dryRun: opts.dryRun,
+                url: opts.url,
+                token: opts.token,
+                claudeCli: opts.claudeCli,
+            }, platform, env));
+        }
+        catch (err) {
+            results.push({
+                id: client.id,
+                label: client.label,
+                path: client.configPath(platform, env),
+                transport: opts.mode,
+                outcome: "error",
+                backedUp: false,
+                dryRun: opts.dryRun,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return results;
+}
+/** Inspect where Jamgate is wired and where its store lives, without changing anything. */
+export async function runStatus(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
+    const clients = [];
+    for (const client of CLIENTS) {
+        const path = client.configPath(platform, env);
+        const detected = await isDetected(client, platform, env, opts.claudeCli);
+        let wired = false;
+        let transport;
+        if (path) {
+            const { existing } = await readConfig(path);
+            const servers = existing && typeof existing === "object" && existing !== null
+                ? existing.mcpServers
+                : undefined;
+            const entry = servers && typeof servers === "object" && servers !== null
+                ? servers[client.serverKey]
+                : undefined;
+            if (entry && typeof entry === "object") {
+                wired = true;
+                transport = "url" in entry ? "http" : "stdio";
+            }
+        }
+        clients.push({ id: client.id, label: client.label, path, detected, wired, transport });
+    }
+    // Mirror the store's own path resolution (FileStore: JAMGATE_STORE ?? ~/.jamgate/memory.json)
+    // so status reports where memories actually live.
+    const storePath = opts.storePath ??
+        env.JAMGATE_STORE ??
+        join(env.HOME || env.USERPROFILE || homedir(), ".jamgate", "memory.json");
+    return { clients, storePath };
+}

package/dist/version.js

@@ -0,0 +1,9 @@
+/**
+ * The single source of truth for the Jamgate version string in code.
+ *
+ * Kept in sync with `package.json` by hand on each release (the build has no codegen step).
+ * Used for the MCP server `serverInfo.version` and the `/healthz` payload, so both report
+ * the same number without importing `package.json` at runtime (which would break once the
+ * code is bundled or the file layout changes between `dist/` and the published package).
+ */
+export const VERSION = "0.4.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamgate",
-  "version": "0.1.0",
+  "version": "0.4.1",
   "mcpName": "io.github.amirj4m/jamgate",
   "description": "A neutral, cross-agent memory quality gate for AI agents, delivered as an MCP server — a gate, not a store.",
   "keywords": [