lensmcp 1.8.0 → 1.10.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "lensmcp-marketplace",
+  "owner": {
+    "name": "David Antoon",
+    "email": "davidmantoon@gmail.com"
+  },
+  "metadata": {
+    "description": "The LensMCP observability lens, packaged as a Claude Code plugin."
+  },
+  "plugins": [
+    {
+      "name": "lensmcp",
+      "source": "./plugin",
+      "description": "Run the LensMCP dev cluster gateway + per-project dashboard + MCP server from inside Claude Code."
+    }
+  ]
+}

package/bundled/main.js

@@ -11,6 +11,9 @@ function __decorate(decorators, target, key, desc) {
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
+function __metadata(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
+}
 
 // servers/lensmcp-mcp/dist/main.js
 import "reflect-metadata";
@@ -20232,10 +20235,145 @@ RenderApp = __decorate([
   })
 ], RenderApp);
 
+// servers/lensmcp-mcp/dist/setup-gate/setup.app.js
+import { App as App21 } from "@frontmcp/sdk";
+
+// servers/lensmcp-mcp/dist/setup-gate/setup-status.tool.js
+import { Tool as Tool24, ToolContext as ToolContext24 } from "@frontmcp/sdk";
+
+// servers/lensmcp-mcp/dist/setup-gate/state.js
+import { existsSync as existsSync5, readFileSync as readFileSync3 } from "node:fs";
+import { dirname as dirname3, join as join3 } from "node:path";
+import { fileURLToPath } from "node:url";
+function lensmcpDir() {
+  const eventFile = process.env["LENSMCP_EVENT_FILE"];
+  if (eventFile)
+    return dirname3(eventFile);
+  return join3(process.cwd(), ".lensmcp");
+}
+function readSetupState() {
+  try {
+    const raw = readFileSync3(join3(lensmcpDir(), "setup-state.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.version === "string" ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function installedVersion() {
+  let dir = dirname3(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const pkg = join3(dir, "package.json");
+    if (existsSync5(pkg)) {
+      try {
+        const version2 = JSON.parse(readFileSync3(pkg, "utf8")).version;
+        if (version2)
+          return version2;
+      } catch {
+      }
+    }
+    const parent = dirname3(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return "0.0.0";
+}
+function checkReadiness() {
+  const installed = installedVersion();
+  const state2 = readSetupState();
+  if (!state2)
+    return { ready: false, installedVersion: installed, reason: "never-setup" };
+  if (state2.version !== installed) {
+    return { ready: false, installedVersion: installed, setupVersion: state2.version, reason: "version-mismatch" };
+  }
+  return { ready: true, installedVersion: installed, setupVersion: state2.version };
+}
+function gateDisabled() {
+  const flag = process.env["LENSMCP_NO_SETUP_GATE"];
+  return flag === "1" || flag === "true";
+}
+function setupRequiredMessage(r) {
+  const last = r.reason === "version-mismatch" && r.setupVersion ? `last set up for v${r.setupVersion}` : "not set up on this machine yet";
+  return `LensMCP is not ready: ${last}, but v${r.installedVersion} is installed. Ask the user to run \`lensmcp setup\` once in their terminal \u2014 it installs the plugin wiring and trusts the dev CA + /etc/hosts (sudo prompts inline; idempotent) \u2014 then retry. Call the \`setup.status\` tool any time to re-check.`;
+}
+
+// servers/lensmcp-mcp/dist/setup-gate/setup-status.tool.js
+var SetupStatusTool = class SetupStatusTool2 extends ToolContext24 {
+  async execute() {
+    const readiness = checkReadiness();
+    return {
+      ready: readiness.ready,
+      installedVersion: readiness.installedVersion,
+      setupVersion: readiness.setupVersion ?? null,
+      reason: readiness.reason ?? null,
+      gateDisabled: gateDisabled(),
+      message: readiness.ready ? `LensMCP is set up for v${readiness.installedVersion}. The lens is open.` : setupRequiredMessage(readiness),
+      fix: readiness.ready ? null : "lensmcp setup"
+    };
+  }
+};
+SetupStatusTool = __decorate([
+  Tool24({
+    name: "setup.status",
+    description: "Report whether LensMCP is set up for the installed version on this machine. Always available (exempt from the setup-gate) so the agent can diagnose. If `ready` is false, ask the user to run `lensmcp setup`.",
+    inputSchema: {}
+  })
+], SetupStatusTool);
+var setup_status_tool_default = SetupStatusTool;
+
+// servers/lensmcp-mcp/dist/setup-gate/gate.plugin.js
+import { Plugin, ToolHook } from "@frontmcp/sdk";
+var { Will } = ToolHook;
+var EXEMPT_TOOLS = /* @__PURE__ */ new Set(["setup.status", "lensmcp.session"]);
+var SetupGatePlugin = class SetupGatePlugin2 {
+  enforceSetup(ctx) {
+    if (gateDisabled())
+      return;
+    let readiness;
+    try {
+      readiness = checkReadiness();
+    } catch {
+      return;
+    }
+    if (!readiness.ready)
+      ctx.fail(new Error(setupRequiredMessage(readiness)));
+  }
+};
+__decorate([
+  Will("execute", {
+    priority: 1e4,
+    filter: (ctx) => !EXEMPT_TOOLS.has(ctx.toolName ?? "")
+  }),
+  __metadata("design:type", Function),
+  __metadata("design:paramtypes", [Object]),
+  __metadata("design:returntype", void 0)
+], SetupGatePlugin.prototype, "enforceSetup", null);
+SetupGatePlugin = __decorate([
+  Plugin({
+    name: "lensmcp-setup-gate",
+    description: "Blocks lens tools until the workspace has run `lensmcp setup` for the installed lensmcp version (after install or upgrade). Fails open on error."
+  })
+], SetupGatePlugin);
+
+// servers/lensmcp-mcp/dist/setup-gate/setup.app.js
+var SetupApp = class SetupApp2 {
+};
+SetupApp = __decorate([
+  App21({
+    id: "lensmcp-setup",
+    name: "LensMCP Setup Gate",
+    description: "Readiness gate: blocks lens tools until the workspace has run `lensmcp setup`, plus the always-open `setup.status` diagnostic.",
+    tools: [setup_status_tool_default],
+    plugins: [SetupGatePlugin]
+  })
+], SetupApp);
+
 // servers/lensmcp-mcp/dist/main.js
 var { session, providers } = createLensSession();
 var transport = process.env["LENSMCP_TRANSPORT"] ?? "stdio";
 var apps = [
+  SetupApp,
   MetaApp,
   AgentApp,
   EventsApp,

package/lib/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/lib/cli.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,gEAAgE;IAChE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAoDD,wBAAsB,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAoChE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/lib/cli.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,gEAAgE;IAChE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAiED,wBAAsB,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAwChE"}

package/lib/cli.js

@@ -9,6 +9,13 @@ Usage:
   lensmcp <command> [options]
 
 Commands:
+  setup [--cwd <dir>] [--skip-format] [--register-host-config <mode>]
+                       First-time bootstrap — runs \`install\` then \`trust\` in
+                       one idempotent pass: plugin + .mcp.json + nx config +
+                       vite/nest wiring, then the dev CA (System keychain),
+                       /etc/hosts (both families) + DNS flush. sudo self-prompts
+                       only for the steps that need it — run in a real terminal.
+                       Then \`lensmcp gateway start\`.
   mcp [--cwd <dir>] [--transport stdio|http] [--port <n>]
                        Launch the LensMCP MCP server. Default transport is
                        stdio (set LENSMCP_TRANSPORT=http or pass --transport
@@ -38,6 +45,12 @@ Commands:
                        Install LensMCP into the host Nx workspace at --cwd
                        (current directory by default). Delegates to
                        \`nx g @lensmcp/nx-plugin:init\`. Idempotent.
+  trust [--cwd <dir>] [--project <p>] [--target <t>]
+                       Make the HTTPS dev gateway trusted: mint + trust the local
+                       dev CA, write /etc/hosts (127.0.0.1 + ::1) for every
+                       cluster host (+ lensmcp.local), flush DNS. Wraps the
+                       auto-discovered \`@lensmcp/cluster:trust\` target.
+                       Idempotent; sudo prompts inline — run in a terminal.
   doctor [--cwd <dir>] [--json]
                        Diagnose the install: Node, workspace + plugin,
                        .mcp.json server entry, MCP bundle, per-project
@@ -65,6 +78,8 @@ export async function runCli(ctx) {
         return { exitCode: 0 };
     }
     switch (command) {
+        case 'setup':
+            return runSetup(ctx, rest, out, err);
         case 'mcp':
             return runMcp(ctx, rest, out, err);
         case 'dashboard':
@@ -75,6 +90,8 @@ export async function runCli(ctx) {
             return runBridge(ctx, rest, out, err);
         case 'install':
             return runInstall(ctx, rest, out, err);
+        case 'trust':
+            return runTrust(ctx, rest, out, err);
         case 'doctor':
             return runDoctor(ctx, rest, out);
         case 'rollout':
@@ -261,9 +278,10 @@ function runGateway(ctx, args, out, err) {
             return { exitCode: 2 };
     }
 }
-/** Find a project + target whose executor is `@lensmcp/cluster:gateway`. An explicit
- *  `project`/`target` short-circuits the scan; otherwise we read each project.json. */
-function findGatewayTarget(cwd, project, target) {
+/** Scan every project.json for the first project carrying a target whose executor
+ *  is `executor`. An explicit project+target short-circuits the scan; a partial
+ *  override fills the missing half from the match. */
+function scanExecutorTarget(cwd, executor, project, target) {
     if (project && target)
         return { project, target };
     const files = walkProjectFiles(cwd, (n) => n === 'project.json');
@@ -277,14 +295,30 @@ function findGatewayTarget(cwd, project, target) {
         }
         const name = pj.name ?? basename(dirname(f));
         for (const [t, def] of Object.entries(pj.targets ?? {})) {
-            if (def.executor === '@lensmcp/cluster:gateway') {
+            if (def.executor === executor) {
                 return { project: project ?? name, target: target ?? t };
             }
         }
     }
+    return undefined;
+}
+/** Find a project + target whose executor is `@lensmcp/cluster:gateway`. */
+function findGatewayTarget(cwd, project, target) {
+    const found = scanExecutorTarget(cwd, '@lensmcp/cluster:gateway', project, target);
+    if (found)
+        return found;
     // Sensible fallback used by most workspaces (tetros: tools/gateway → `gateway:serve`).
     return project || target ? { project: project ?? 'gateway', target: target ?? 'serve' } : undefined;
 }
+/** Find a project + target whose executor is `@lensmcp/cluster:trust`. Falls back
+ *  unconditionally to `gateway:trust` — the conventional home the init generator
+ *  scaffolds — since trust is idempotent and safe to attempt anywhere. */
+function findTrustTarget(cwd, project, target) {
+    return (scanExecutorTarget(cwd, '@lensmcp/cluster:trust', project, target) ?? {
+        project: project ?? 'gateway',
+        target: target ?? 'trust',
+    });
+}
 function readPid(pidFile) {
     try {
         const n = Number(readFileSync(pidFile, 'utf8').trim());
@@ -384,6 +418,96 @@ function runInstall(ctx, args, out, err) {
     });
     return { exitCode: result.status ?? 1 };
 }
+/**
+ * `lensmcp trust` — make the HTTPS dev gateway trusted in real browsers: mint +
+ * trust the local dev CA, write `/etc/hosts` (both `127.0.0.1` and `::1`) for
+ * every cluster host plus `lensmcp.local`, and flush DNS. Delegates to the
+ * auto-discovered `@lensmcp/cluster:trust` target. The executor self-escalates
+ * with `sudo` per privileged step and skips each when already satisfied, so this
+ * is idempotent — but it needs a real terminal so sudo can prompt.
+ */
+function runTrust(ctx, args, out, err) {
+    const opts = parseFlags(args, { string: ['--cwd', '--project', '--target'] });
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    if (!existsSync(join(cwd, 'nx.json'))) {
+        err(`No nx.json found at ${cwd}.`);
+        err('Run `lensmcp trust` from inside a Nx workspace (after `lensmcp install`).');
+        return { exitCode: 1 };
+    }
+    const nxBin = findNxBinary(cwd);
+    if (!nxBin) {
+        err('Could not find the `nx` binary in the workspace. Install Nx first: `yarn add -D nx`.');
+        return { exitCode: 1 };
+    }
+    const target = findTrustTarget(cwd, stringFlag(opts.flags['--project']), stringFlag(opts.flags['--target']));
+    if (!isInteractive()) {
+        out('  note: trust runs `sudo` for the CA + /etc/hosts — run it in a real terminal if a step is needed.');
+    }
+    out(`> ${nxBin} run ${target.project}:${target.target}   (sudo prompts inline for the CA + /etc/hosts)`);
+    const result = spawnSync(nxBin, ['run', `${target.project}:${target.target}`], {
+        cwd,
+        stdio: 'inherit',
+        env: { ...process.env, ...(ctx.env ?? {}) },
+    });
+    return { exitCode: result.status ?? 1 };
+}
+/**
+ * Write the setup-state marker the MCP setup-gate reads to decide readiness.
+ * The shape MUST match `servers/lensmcp-mcp/src/setup-gate/state.ts`
+ * (`SetupState`). Machine-local (`.lensmcp/` is gitignored): it records the
+ * lensmcp version setup completed for, so an upgrade re-arms the gate until
+ * `setup` runs again.
+ */
+function writeSetupState(cwd) {
+    ensureLensmcpDir(cwd);
+    const state = {
+        version: readCliVersion(),
+        completedAt: new Date().toISOString(),
+        steps: { install: true, trust: true },
+    };
+    try {
+        writeFileSync(join(cwd, '.lensmcp', 'setup-state.json'), `${JSON.stringify(state, null, 2)}\n`);
+    }
+    catch {
+        /* non-fatal: the gate just treats the workspace as not-yet-set-up */
+    }
+}
+/**
+ * `lensmcp setup` — first-time bootstrap. Runs `install` (plugin + .mcp.json +
+ * nx config + vite/nest wiring, no sudo) then `trust` (dev CA → keychain,
+ * /etc/hosts, DNS flush, sudo). Both steps are idempotent, so re-running is safe.
+ * Flags are forwarded to whichever sub-command understands them (`--skip-format`,
+ * `--register-host-config` → install; `--project`/`--target` → trust).
+ */
+function runSetup(ctx, args, out, err) {
+    const opts = parseFlags(args, { string: ['--cwd'] });
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    const subCtx = { ...ctx, cwd };
+    out('lensmcp setup — first-time bootstrap (install → trust)');
+    out('');
+    out('[1/2] install — plugin, .mcp.json, nx config, vite/nest wiring');
+    const installRes = runInstall(subCtx, args, out, err);
+    if (installRes.exitCode !== 0) {
+        err('');
+        err('setup: the install step failed — fix the above and re-run `lensmcp setup`.');
+        return installRes;
+    }
+    out('');
+    out('[2/2] trust — dev CA → System keychain, /etc/hosts, DNS flush (sudo)');
+    const trustRes = runTrust(subCtx, args, out, err);
+    if (trustRes.exitCode !== 0) {
+        err('');
+        err('setup: the trust step failed — run `lensmcp setup` directly in a terminal so sudo can prompt.');
+        return trustRes;
+    }
+    // Both steps succeeded → mark the workspace set up for this version (opens the MCP gate).
+    writeSetupState(cwd);
+    out('');
+    out('✓ setup complete.');
+    out('  next:   lensmcp gateway start      (the :443 front door — needs sudo)');
+    out('  verify: lensmcp doctor');
+    return { exitCode: 0 };
+}
 function runDoctor(ctx, args, out) {
     const opts = parseFlags(args, { string: ['--cwd'], boolean: ['--json'] });
     const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
@@ -697,6 +821,11 @@ function ensureLensmcpDir(cwd) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
 }
+/** `sudo` can only prompt for a password when both stdin and stdout are TTYs.
+ *  Used to warn (not block) before the trust step's privileged sub-commands. */
+function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
 /** Narrow a flag value to string-or-undefined, treating booleans as absent. */
 function stringFlag(v) {
     if (v === undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lensmcp",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "lensmcp",
+  "displayName": "LensMCP",
+  "description": "The observability lens for coding agents. One command brings up the dev cluster gateway (every project.json `cluster` decl → its host on :443), the per-project lens dashboard at https://lensmcp.local/<project>/, and the MCP server your agent connects to — scoped automatically to whatever project you opened Claude Code in.",
+  "version": "1.10.0",
+  "author": {
+    "name": "David Antoon",
+    "email": "davidmantoon@gmail.com"
+  },
+  "homepage": "https://github.com/kiwiapps-ltd/lensmcp",
+  "repository": "https://github.com/kiwiapps-ltd/lensmcp",
+  "license": "Apache-2.0",
+  "keywords": [
+    "mcp",
+    "lens",
+    "observability",
+    "nx",
+    "vite",
+    "nestjs",
+    "gateway"
+  ],
+  "mcpServers": "./.mcp.json"
+}

package/plugin/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "lensmcp": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PROJECT_DIR}/node_modules/lensmcp/bin.js",
+        "mcp",
+        "--cwd",
+        "${CLAUDE_PROJECT_DIR}"
+      ]
+    }
+  }
+}

package/plugin/README.md

@@ -0,0 +1,49 @@
+# LensMCP — Claude Code plugin
+
+Run the LensMCP observability lens for **any** project, from inside Claude Code: the dev
+cluster **gateway**, the per-project **dashboard**, and the **MCP server** your agent
+connects to — all scoped automatically to the project you opened Claude Code in.
+
+## What it bundles
+
+- **MCP server** (`.mcp.json`) — launched as `lensmcp mcp --cwd ${CLAUDE_PROJECT_DIR}`, so it
+  always reads *that project's* `.lensmcp/events.jsonl`. Open Claude Code in `tetros` → you
+  get tetros's flows; open it elsewhere → that project's flows. No cross-talk.
+- **Commands** (skills):
+  - `/lensmcp:start` — start the gateway (every `project.json` `cluster` decl → its host on
+    :443) + the lens dashboard at `https://lensmcp.local/<key>/`.
+  - `/lensmcp:stop` — stop the gateway.
+  - `/lensmcp:status` — gateway liveness + `lensmcp doctor`.
+  - `/lensmcp:dashboard` — open the per-project dashboard in the browser.
+  - `/lensmcp:using-lensmcp` — how to drive the lens (which tool answers which question).
+
+## Requirements
+
+The target project must have **`lensmcp` installed** as a dev dependency
+(`yarn add -D lensmcp`) — the plugin shells out to its project-local CLI so versions stay in
+lock-step with the project. `lensmcp` is a **dev-only** tool; never a prod/CI dependency.
+
+Binding **:443** needs privilege — run `nx run gateway:trust` once per machine (sets up the
+`*.local` hosts + a TLS CA), and start the gateway with the elevation your OS requires.
+
+## Install
+
+**Dev (fastest, what we use while iterating):**
+
+```bash
+claude --plugin-dir /Users/davidantoon/git/lensmcp/plugin
+```
+
+**Via marketplace (once published):**
+
+```bash
+/plugin marketplace add kiwiapps-ltd/lensmcp
+/plugin install lensmcp@lensmcp-marketplace
+```
+
+## Multi-project
+
+Each project derives its own `key`, ports, and dashboard mount path
+(`.lensmcp/config.json`), so the lens runs cleanly across projects — switch projects and the
+dashboard moves to `lensmcp.local/<that-project>/` with its own ports. One gateway owns :443
+at a time.

package/plugin/scripts/dashboard-open.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Open the per-project LensMCP dashboard (history-routed) in the default browser.
+# The mount path comes from .lensmcp/config.json (e.g. /tetros), served by the gateway
+# at https://lensmcp.local/<key>/.
+set -uo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+CFG="$PROJECT_DIR/.lensmcp/config.json"
+
+BASE=""
+if [ -f "$CFG" ]; then
+  BASE="$(node -e "try{process.stdout.write(require('$CFG').dashboardBasePath||'')}catch(e){}" 2>/dev/null || echo '')"
+fi
+
+URL="https://lensmcp.local${BASE}/"
+echo "LensMCP dashboard → $URL"
+echo "(needs the gateway running: /lensmcp:start)"
+
+case "$(uname -s)" in
+  Darwin) open "$URL" 2>/dev/null || true ;;
+  Linux)  xdg-open "$URL" 2>/dev/null || true ;;
+  *)      echo "Open it manually: $URL" ;;
+esac

package/plugin/scripts/gateway-start.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Start the LensMCP dev cluster gateway for the project Claude Code is open in.
+# The gateway reads every project.json `cluster` decl, launches each app/service under
+# its host on :443, and serves the per-project lens dashboard at lensmcp.local/<key>/.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+BIN="$PROJECT_DIR/node_modules/lensmcp/bin.js"
+
+if [ ! -f "$BIN" ]; then
+  echo "✗ lensmcp is not installed in $PROJECT_DIR (no node_modules/lensmcp/bin.js)." >&2
+  echo "  Install it as a dev dependency:  yarn add -D lensmcp" >&2
+  echo "  (the gateway is a dev-only tool — never a prod/CI dependency)." >&2
+  exit 1
+fi
+
+exec node "$BIN" gateway start --cwd "$PROJECT_DIR"

package/plugin/scripts/gateway-status.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Report LensMCP gateway status for the current project, then run the install doctor.
+set -uo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+BIN="$PROJECT_DIR/node_modules/lensmcp/bin.js"
+
+if [ ! -f "$BIN" ]; then
+  echo "✗ lensmcp is not installed in $PROJECT_DIR." >&2
+  exit 1
+fi
+
+node "$BIN" gateway status --cwd "$PROJECT_DIR" || true
+echo
+node "$BIN" doctor --cwd "$PROJECT_DIR" || true

package/plugin/scripts/gateway-stop.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Stop the LensMCP dev cluster gateway for the current project.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+BIN="$PROJECT_DIR/node_modules/lensmcp/bin.js"
+
+if [ ! -f "$BIN" ]; then
+  echo "✗ lensmcp is not installed in $PROJECT_DIR." >&2
+  exit 1
+fi
+
+exec node "$BIN" gateway stop --cwd "$PROJECT_DIR"

package/plugin/skills/dashboard/SKILL.md

@@ -0,0 +1,19 @@
+---
+description: Open the per-project LensMCP dashboard (Flows / Cluster / Logs / Resources) in the browser at https://lensmcp.local/<key>/. Use when the user asks to open the lens dashboard, see the flows/cluster UI, or watch the app live.
+---
+
+# Open the LensMCP dashboard
+
+Run the open script with the Bash tool:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/dashboard-open.sh"
+```
+
+It reads the project's mount path from `.lensmcp/config.json` and opens
+`https://lensmcp.local/<key>/` — the human view of the lens (the same event stream the
+MCP server reads): **Flows**, **Cluster**, **Logs**, **Resources**, history-routed so deep
+links + refresh work.
+
+The dashboard is served by the gateway, so it needs the gateway running first
+(`/lensmcp:start`). If the page doesn't load, check `/lensmcp:status`.

package/plugin/skills/start/SKILL.md

@@ -0,0 +1,35 @@
+---
+description: Start the LensMCP dev cluster gateway for the current project — brings up every app/service/site under its host on :443 and the per-project lens dashboard at https://lensmcp.local/<key>/. Use when the user asks to start the gateway/cluster, "start lensmcp", bring the dev cluster up, or start listening.
+---
+
+# Start the LensMCP gateway
+
+Run the startup script with the Bash tool:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/gateway-start.sh"
+```
+
+The script calls `lensmcp gateway start` for the project Claude Code is open in
+(`${CLAUDE_PROJECT_DIR}`). That single command:
+
+- reads every `project.json` `cluster` declaration and launches each app / service /
+  website under its own host (e.g. `app.tetros.ai.local`, `auth.tetros.ai.local`,
+  `api.tetros.ai.local/crm`), each on its own port/socket via the one HTTPS front door
+  on **:443**;
+- serves the project-scoped lens **dashboard** at `https://lensmcp.local/<key>/`;
+- writes a pid + log under `.lensmcp/` so it can be stopped later.
+
+After running it:
+
+1. Report the dashboard URL the script printed.
+2. **Binding :443 needs privilege.** If the log shows `EACCES`/permission denied, tell
+   the user to either run the gateway target with `sudo`, or that ports <1024 require
+   elevation on macOS — and that `lensmcp setup` (install + trust) or `lensmcp trust`
+   must be run once (sudo) to set up the `*.local` hosts + TLS CA. Check
+   `.lensmcp/gateway.log` for the real error.
+3. If the user has not run `lensmcp setup` / `lensmcp trust` yet, mention it (one-time
+   per machine).
+
+Do **not** run a service's `serve`/`serve-hmr` manually — the gateway owns each service's
+lifecycle. This one command is the entry point.

package/plugin/skills/status/SKILL.md

@@ -0,0 +1,18 @@
+---
+description: Report LensMCP status for the current project — gateway liveness, the dashboard URL, and the install doctor (Node, plugin wiring, MCP bundle, per-project vite/nest wiring). Use when the user asks if lensmcp is running, to check the gateway, or to diagnose the lens setup.
+---
+
+# LensMCP status + doctor
+
+Run the status script with the Bash tool:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/gateway-status.sh"
+```
+
+It runs `lensmcp gateway status` (is the gateway up? the project key + dashboard URL) and
+then `lensmcp doctor` (Node version, plugin registration, `.mcp.json`, the MCP server
+bundle, per-project Vite/Nest wiring, agent-dev targets, Chrome for browser capture).
+
+Summarize the result for the user: whether the gateway is running, the dashboard URL, and
+any `✗`/`!` items doctor flagged with their suggested fix.

package/plugin/skills/stop/SKILL.md

@@ -0,0 +1,17 @@
+---
+description: Stop the LensMCP dev cluster gateway for the current project. Use when the user asks to stop the gateway/cluster, "stop lensmcp", or shut the dev cluster down.
+---
+
+# Stop the LensMCP gateway
+
+Run the stop script with the Bash tool:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/gateway-stop.sh"
+```
+
+It calls `lensmcp gateway stop` for `${CLAUDE_PROJECT_DIR}`, which reads the pid recorded
+in `.lensmcp/gateway.pid` and terminates the gateway process group (the gateway plus the
+app/service pods + the lens dashboard it spawned).
+
+Report whether it stopped, or that it was already not running.

package/plugin/skills/using-lensmcp/SKILL.md

@@ -0,0 +1,51 @@
+---
+description: How to drive the LensMCP lens to observe a running app — the start→interact→read loop, and which MCP tool answers which question (what happened on a click, why a component re-rendered, what's slow, memory leaks). Use when the user asks how to use lensmcp, what it can do, or to explain/trace something the running app just did.
+---
+
+# Using LensMCP
+
+LensMCP gives you (and the user) eyes on a running application. Producers (the gateway,
+agent-dev, instrumented apps) write events to `<project>/.lensmcp/events.jsonl`; the MCP
+server and the dashboard both read that file. **Project isolation is automatic** — the MCP
+server is launched with `--cwd ${CLAUDE_PROJECT_DIR}`, so it always reads the flows of the
+project Claude Code is open in. Different project → different event file → different flows.
+
+## First: is the lens set up?
+
+LensMCP gates its tools until the workspace has been set up **once per machine** (and again
+after a lensmcp upgrade). If a tool fails with a **"LensMCP is not ready — run `lensmcp setup`"**
+message — or if `setup.status` reports `ready: false` — do **not** keep retrying. Tell the user
+to run **`lensmcp setup`** in their terminal (it wires the plugin + trusts the dev CA/hosts;
+sudo prompts inline; idempotent), then continue. The `setup.status` tool and the session
+bootstrap stay available even while the gate is closed.
+
+## The loop
+
+1. **Start** the cluster + lens: `/lensmcp:start` (gateway up, all hosts routed, dashboard
+   at `https://lensmcp.local/<key>/`). For a single app instead of the whole cluster, the
+   workspace's `nx run <project>:agent-dev` also produces events.
+2. **Interact** with the running app (click around in the browser, or let an e2e drive it).
+3. **Read** the lens — ask in plain language and call the right MCP tool:
+
+| The user asks… | Tool |
+|---|---|
+| "what's the current state / is the lens live?" | `observe_current_status` |
+| "show me recent flows" / "what just happened?" | `flow_list_recent`, then `flow_get` |
+| "what happened when I clicked X?" | `graph_find_backend_work_caused_by_click`, `graph_trace_from_origin` |
+| "why did this component re-render?" | `graph_explain_rerender` |
+| "what's slow?" / "is there a DB call in a loop?" | `graph_find_slow_path`, `graph_find_db_in_loop` |
+| "what state updates did this cause?" | `graph_find_state_updates_caused_by` |
+| "did anything leak memory?" | `memory_explain_leak`, `memory_find_growth_by_flow` |
+| "tell the story of this flow" | `story_compile`, `story_get` |
+| visual / render checks | `visual_capture_frame`, `visual_inspect_node`, `visual_compare_frames` |
+
+4. Watch it as a human anytime with `/lensmcp:dashboard`.
+
+## Tips
+
+- If a tool returns nothing, no events have been produced yet — start the gateway (or an
+  `agent-dev`) and interact with the app first.
+- `/lensmcp:status` runs the doctor if something seems off (Node, plugin wiring, MCP bundle,
+  per-project Vite/Nest instrumentation, Chrome for browser capture).
+- Don't run a service's `serve`/`serve-hmr` by hand — the gateway owns each service's
+  lifecycle; `/lensmcp:start` is the one entry point.