stack-cleaner 1.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bespoke Woodcraft Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+<div align="center">
+
+# Stack Cleaner
+
+**See, organize, and clean up your Claude Code setup: every skill, plugin, MCP server, and agent, split by _global_ vs. _project_.**
+
+Free · open source · runs locally · sends nothing.
+
+[**Live app →**](https://stackcleaner.com) &nbsp;·&nbsp; [Guided setup →](https://stackcleaner.com/setup) &nbsp;·&nbsp; [Try the demo →](https://stackcleaner.com/inventory)
+
+</div>
+
+---
+
+Over time, Claude Code accumulates a lot: user-level skills in `~/.claude`, project skills in every repo's `.claude`, plugins from a handful of marketplaces, MCP servers wired into different projects, and a pile of sub-agents. It gets hard to answer simple questions: *what do I actually have? what do I never use? what's duplicated? what can I safely remove?*
+
+This tool answers them. You run one command, it reads your local Claude Code install, and the web app shows everything **grouped by where it lives** (global vs. each project), with **real usage counts**, so you can spot the dead weight and build a one-click cleanup plan.
+
+## How it works
+
+```
+  ┌─────────────┐      ┌──────────────────────┐      ┌─────────────────────┐
+  │  1. Scan    │  →   │  2. See              │  →   │  3. Tidy            │
+  │  one line   │      │  global vs project   │      │  cleanup plan, or   │
+  │  in terminal│      │  + real usage counts │      │  hand it to Claude  │
+  └─────────────┘      └──────────────────────┘      └─────────────────────┘
+```
+
+1. **Scan**: run the one-liner below. It writes `stack-cleaner.json` next to you. No dependencies, nothing sent anywhere.
+2. **See**: drop that file into the [web app](https://stackcleaner.com/inventory). It's parsed in your browser; nothing is uploaded.
+3. **Tidy**: tick the items you want gone and export a shell script, a paste-to-Claude prompt, or JSON.
+
+### The scan
+
+**The one command**, same on macOS, Windows, and Linux, no `curl`, nothing piped:
+
+```bash
+npx stack-cleaner@latest
+```
+
+It runs the published npm package (which bundles the same scanner) and writes `stack-cleaner.json` next to you. Node ships with Claude Code, so you already have it.
+
+<details>
+<summary>Prefer not to use npm? Download the script straight from this site instead.</summary>
+
+**macOS / Linux** (bash/zsh):
+
+```bash
+curl -fsSL https://stackcleaner.com/scan.mjs | node
+```
+
+**Windows** (PowerShell): `curl` there is an alias for `Invoke-WebRequest`, so call `curl.exe` and download-then-run instead of piping:
+
+```powershell
+curl.exe -fsSL https://stackcleaner.com/scan.mjs -o stack-cleaner-scan.mjs; node stack-cleaner-scan.mjs
+```
+
+</details>
+
+Prefer to read it first? It's one short, dependency-free file ([`public/scan.mjs`](public/scan.mjs)). Download then run (use `curl.exe` on Windows):
+
+```bash
+curl -fsSL https://stackcleaner.com/scan.mjs -o stack-cleaner-scan.mjs
+node stack-cleaner-scan.mjs
+```
+
+**Not comfortable in a terminal?** The [**Setup page**](https://stackcleaner.com/setup) walks you through it copy-paste by copy-paste. You never need a GitHub account or any coding.
+
+## What it captures
+
+For every item it records the type, the scope (global or which project), a description, and a **real usage count**: how many times you've actually invoked it, and when you last did.
+
+| Type | Global source | Project source |
+|------|---------------|----------------|
+| **Skills** | `~/.claude/skills/*/SKILL.md` | `<repo>/.claude/skills/*/SKILL.md` |
+| **Plugins** | `~/.claude/plugins/installed_plugins.json` | – |
+| **MCP servers** | `~/.claude.json` → `mcpServers` | per-project `mcpServers` + `.mcp.json` |
+| **Agents** | `~/.claude/agents/*.md` | `<repo>/.claude/agents/*.md` |
+
+It enumerates **every project** Claude Code knows about (from `~/.claude.json`), not just the folder you run it in, so you get your whole picture in one pass.
+
+### Where usage counts come from
+
+The scan reads your local Claude Code **transcripts** (`~/.claude/projects/*.jsonl`) to count real invocations for **skills, agents, and MCP servers**, so you can finally see what's *installed but never used*, even for the types that carry no usage count in plain config. It extracts **only the tool / skill / agent / MCP-server names, the counts, and the timestamps**, never your prompts, message text, tool arguments, file paths, or command contents. It all stays local until you choose to upload the file. Pass `--no-transcripts` to skip the transcript read entirely. (Skills and plugins also keep their counts from Claude Code's own `skillUsage` / `pluginUsage` tables.)
+
+## Privacy & safety
+
+This is the part that matters, because the output describes your tooling.
+
+- **Runs entirely on your machine.** The scan never makes a network request. The web app parses your file in the browser and stores it only in that browser's `localStorage`. It is never uploaded.
+- **Transcripts: names and counts only.** To compute real usage it streams your local transcripts but extracts **only** tool/skill/agent/MCP-server names, counts, and timestamps, never prompt text, arguments, file paths, or command contents. Opt out with `--no-transcripts`.
+- **Secrets are stripped before the file is written.** MCP `env` values, auth headers, URL credentials, and token-looking arguments are replaced with `<redacted>`. Your home directory is rewritten to `~` so your username doesn't leak.
+- **It only reads.** The scan never modifies, installs, or removes anything. Removal commands are generated as text for *you* to review and run.
+- **No dependencies, no build step to scan.** `scan.mjs` is plain Node with `node:` built-ins only. Read the whole thing in a minute.
+
+## The cleanup plan
+
+Select items and the tool builds three things:
+
+- **Hand to Claude**: a prompt you paste back into Claude Code so it does the removals for you.
+- **Shell script**: the exact `claude plugins uninstall …` / `rm -rf ~/.claude/skills/…` / `claude mcp remove …` commands, grouped by type, for you to review and run.
+- **JSON**: a machine-readable selection for your own tooling.
+
+Nothing is ever removed by this tool. You stay in control.
+
+## Run it yourself / self-host
+
+It's a standard Next.js (App Router) app with no backend and no database.
+
+```bash
+git clone https://github.com/BespokeWoodcraftStudio/stack-cleaner
+cd stack-cleaner
+npm install
+npm run dev        # http://localhost:3000
+
+# scan your own machine straight from the source:
+node public/scan.mjs
+```
+
+Or install the published CLI globally and run it from anywhere:
+
+```bash
+npm i -g stack-cleaner
+stack-cleaner          # writes stack-cleaner.json in the current folder
+```
+
+Deploy your own copy to Vercel (or any static-capable Next host) with one click of "Import Project". There's nothing to configure.
+
+## The inventory schema
+
+The scan emits, and the app reads, a single JSON shape, abbreviated below; the full field list is in [`lib/types.ts`](lib/types.ts):
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-…",
+  "generator": "scan.mjs@1.0.0",
+  "machine": { "platform": "darwin", "node": "v22.0.0" },
+  "projects": ["my-app", "my-blog"],
+  "usageSummary": {             // present when the transcript scan ran
+    "totalInvocations": 1280,
+    "itemsWithUsage": 24,
+    "itemsUnused": 11,
+    "transcriptsScanned": 4142,
+    "generatedFrom": "transcripts"
+  },
+  "items": [
+    {
+      "id": "skill:global:graphify",
+      "type": "skill",            // skill | plugin | mcp | agent
+      "scope": "global",          // global | project
+      "project": null,            // basename for project-scoped items
+      "name": "graphify",
+      "description": "…",
+      "path": "~/.claude/skills/graphify",
+      "usageCount": 10,           // mirrors invocationCount when matched
+      "lastUsedAt": 1718000000000,
+      "usageClass": "good",       // good | warn | bad | info | unknown
+      "usageLabel": "✅ 10 uses", // display string
+      "invocationCount": 10,      // transcript invocations (0 = tracked, never used)
+      "lastUsed": 1718000000000,  // epoch ms of most recent invocation, or null
+      "usageSource": "transcripts", // "transcripts" | "claude-json" | "none"
+      "removeCmd": "rm -rf ~/.claude/skills/graphify"
+    }
+  ]
+}
+```
+
+Because it's just JSON, you can hand-write or generate an inventory from any source and drop it in.
+
+## Project layout
+
+```
+public/scan.mjs              the local scanner (zero-dep Node)
+lib/types.ts                 the shared inventory schema
+lib/inventory.ts             parse / filter / group / manifest logic
+lib/demo.ts                  the built-in demo dataset
+app/page.tsx                 landing
+app/setup/page.tsx           guided, non-technical walkthrough
+app/inventory/page.tsx       the tool
+components/                  ui primitives + page sections
+```
+
+## Documentation
+
+- [**FAQ**](docs/FAQ.md) (or the in-app [/faq](https://stackcleaner.com/faq)): is anything uploaded, are my keys safe, can it delete things, Windows support…
+- [**Usage guide**](docs/USAGE.md): a walkthrough of the inventory tool: filtering, selection, and the three cleanup exports.
+- [**Setup wizard**](https://stackcleaner.com/setup): the non-technical, copy-paste path.
+- [**Security policy**](SECURITY.md): how to privately report a redaction miss (and what we already do).
+- [**Support / troubleshooting**](SUPPORT.md): common errors and where to get help.
+- [**Changelog**](CHANGELOG.md) · [**Contributing**](CONTRIBUTING.md) · [**Code of Conduct**](CODE_OF_CONDUCT.md)
+
+## Contributing
+
+Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup and the verify gate, and [SECURITY.md](SECURITY.md) for reporting a secret leak privately. Good first additions: more cleanup-command coverage, richer usage-trend views, and broader plugin-marketplace detection.
+
+## License
+
+MIT, see [LICENSE](LICENSE). A [Bespoke Woodcraft Studio](https://github.com/BespokeWoodcraftStudio) tool. Not affiliated with Anthropic; "Claude" and "Claude Code" are trademarks of Anthropic.

package/bin/cli.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// stack-cleaner — npx CLI
+//
+// Scans your local Claude Code setup (skills, plugins, MCP servers, agents)
+// plus transcript usage, and writes a redacted stack-cleaner.json you can
+// upload to https://stackcleaner.com to explore + clean up.
+//
+//   npx stack-cleaner
+//   npx stack-cleaner --stdout
+//   npx stack-cleaner --out my-inventory.json
+//
+// Privacy: only tool/server/agent/skill NAMES, counts, and timestamps are
+// extracted from transcripts. No prompt text, args, paths, or commands.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { runScan } from "../public/scan.mjs";
+
+const UPLOAD_URL = "https://stackcleaner.com";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function readVersion() {
+  try {
+    const pkgPath = resolve(__dirname, "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function printHelp() {
+  const v = readVersion();
+  process.stdout.write(
+    `stack-cleaner v${v}
+
+Scan your local Claude Code setup (skills, plugins, MCP servers, agents) and
+transcript usage into a redacted stack-cleaner.json. Then upload it to
+${UPLOAD_URL} to explore and clean up what you're not using.
+
+Usage:
+  npx stack-cleaner [options]
+
+Options:
+  -h, --help               Show this help and exit.
+  -v, --version            Print the version and exit.
+      --stdout, --print    Print the inventory JSON to stdout instead of writing a file.
+      --out <file>         Write the inventory to <file> (default: stack-cleaner.json).
+      --no-transcripts     Skip transcript usage scanning (faster; no usage counts).
+      --transcripts-dir <dir>
+                           Scan transcripts from <dir> instead of ~/.claude/projects.
+
+Examples:
+  npx stack-cleaner
+  npx stack-cleaner --stdout > inventory.json
+  npx stack-cleaner --out ~/Desktop/inventory.json
+  npx stack-cleaner --no-transcripts
+
+Privacy: only tool/server/agent/skill names, counts, and timestamps are read
+from transcripts — never prompt text, arguments, file paths, or commands.
+
+After scanning, upload the JSON at ${UPLOAD_URL}.
+`
+  );
+}
+
+function parseArgs(argv) {
+  const opts = {
+    help: false,
+    version: false,
+    stdout: false,
+    outFile: "stack-cleaner.json",
+    transcripts: true,
+    transcriptsDir: undefined,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "-h":
+      case "--help":
+        opts.help = true;
+        break;
+      case "-v":
+      case "--version":
+        opts.version = true;
+        break;
+      case "--stdout":
+      case "--print":
+        opts.stdout = true;
+        break;
+      case "--no-transcripts":
+        opts.transcripts = false;
+        break;
+      case "--out": {
+        const next = argv[++i];
+        if (next === undefined) {
+          throw new Error("--out requires a file path");
+        }
+        opts.outFile = next;
+        break;
+      }
+      case "--transcripts-dir": {
+        const next = argv[++i];
+        if (next === undefined) {
+          throw new Error("--transcripts-dir requires a directory path");
+        }
+        opts.transcriptsDir = next;
+        break;
+      }
+      default:
+        // Support --out=file / --transcripts-dir=dir style too.
+        if (arg.startsWith("--out=")) {
+          opts.outFile = arg.slice("--out=".length);
+        } else if (arg.startsWith("--transcripts-dir=")) {
+          opts.transcriptsDir = arg.slice("--transcripts-dir=".length);
+        } else {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+  }
+
+  return opts;
+}
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n\n`);
+    process.stderr.write(`Run \`stack-cleaner --help\` for usage.\n`);
+    process.exit(1);
+    return;
+  }
+
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+
+  if (opts.version) {
+    process.stdout.write(`${readVersion()}\n`);
+    return;
+  }
+
+  // Friendly banner — keep it on stderr so `--stdout` stays pure JSON on stdout.
+  if (!opts.stdout) {
+    process.stderr.write(`stack-cleaner v${readVersion()}\n`);
+    process.stderr.write(`Scanning your Claude Code setup...\n`);
+  }
+
+  try {
+    await runScan({
+      stdout: opts.stdout,
+      outFile: opts.outFile,
+      transcripts: opts.transcripts,
+      transcriptsDir: opts.transcriptsDir,
+    });
+  } catch (err) {
+    process.stderr.write(`\nScan failed: ${err && err.message ? err.message : err}\n`);
+    process.exit(1);
+    return;
+  }
+
+  // Next-step guidance (skip when piping JSON to stdout so we don't pollute it).
+  if (!opts.stdout) {
+    process.stderr.write(
+      `\nNext step:\n` +
+        `  1. Open ${UPLOAD_URL}\n` +
+        `  2. Upload the ${opts.outFile} file to explore and clean up your setup.\n`
+    );
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`\nUnexpected error: ${err && err.message ? err.message : err}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "stack-cleaner",
+  "version": "1.1.5",
+  "private": false,
+  "license": "MIT",
+  "description": "See, organize, and clean up your Claude Code skills, plugins, MCP servers, and agents (split by global vs. project).",
+  "bin": {
+    "stack-cleaner": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "public/scan.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "scan": "node public/scan.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "comment:deps": "The published package is the CLI (bin/cli.mjs + public/scan.mjs), which uses only Node built-ins — so it has no runtime dependencies and `npx stack-cleaner` installs nothing extra. next/react/react-dom power the web app and are dev/build-only (Vercel installs devDependencies during the build).",
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "geist": "^1.7.2",
+    "next": "^15.5.4",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.9"
+  }
+}

package/public/scan.mjs

@@ -0,0 +1,719 @@
+#!/usr/bin/env node
+// =============================================================
+// Stack Cleaner — local scan
+//
+//   curl -fsSL https://stackcleaner.com/scan.mjs | node
+//   # or:  node scan.mjs            (writes ./stack-cleaner.json)
+//          node scan.mjs --stdout   (prints JSON to stdout instead)
+//
+// Reads your local Claude Code install and writes a single JSON file
+// describing every skill, plugin, MCP server, and agent you have — split
+// by global (~/.claude) vs. project (each repo's .claude). Drop that file
+// into the web app to see and organize everything.
+//
+// It also scans your local Claude Code transcripts (~/.claude/projects/*.jsonl)
+// to count how often each skill, agent, and MCP server was actually invoked,
+// and when it was last used. ONLY tool/server/agent/skill NAMES, counts, and
+// timestamps are read from transcripts — never your prompts, messages, command
+// text, file paths, or tool arguments. Disable with --no-transcripts.
+//
+// PRIVACY: this runs entirely on your machine. It never sends anything
+// anywhere. Secrets are aggressively redacted before they ever touch the
+// output file: MCP env values, auth headers, tokens, and URL credentials
+// are replaced with "<redacted>". Your home directory is rewritten to "~".
+// Skill/agent descriptions are prose blurbs copied from their frontmatter; we
+// also scrub obvious token shapes (sk-…, ghp_…, "Authorization: …") out of them,
+// but that pass is best-effort — don't keep secrets in a SKILL.md description.
+// Read this file before you run it — it's short and has no dependencies.
+//
+// SPDX-License-Identifier: MIT
+// =============================================================
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import readline from "node:readline";
+import { pathToFileURL } from "node:url";
+
+const SCHEMA_VERSION = 1;
+const GENERATOR = "scan.mjs@1.1.5";
+const HOME = os.homedir();
+const CLAUDE = path.join(HOME, ".claude");
+
+// ---------- small helpers ----------
+const tilde = (p) => (p && p.startsWith(HOME) ? "~" + p.slice(HOME.length) : p);
+const exists = (p) => { try { fs.accessSync(p); return true; } catch { return false; } };
+const readText = (p) => { try { return fs.readFileSync(p, "utf8"); } catch { return null; } };
+const readJSON = (p) => { const t = readText(p); if (!t) return null; try { return JSON.parse(t); } catch { return null; } };
+const listDir = (p, kind) => {
+  try {
+    return fs.readdirSync(p, { withFileTypes: true })
+      .filter((d) => (kind === "dir" ? d.isDirectory() : d.isFile()))
+      .map((d) => d.name);
+  } catch { return []; }
+};
+
+// Pull `name:` and `description:` out of YAML-ish frontmatter without a YAML dep.
+// Handles single-line scalars, quoted values, and block scalars (`>`, `>-`, `|`,
+// `|-`) — the conventional way skills write their long, multi-line descriptions.
+function parseFrontmatter(text) {
+  if (!text) return {};
+  const m = text.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return {};
+  const out = {};
+  const lines = m[1].split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    let v = kv[2].trim();
+
+    // Block scalar: `>` (folded → spaces) or `|` (literal → newlines), with an
+    // optional chomp indicator and trailing comment. The body is the following
+    // more-indented lines, ending at the first line dedented to the key or less.
+    const block = v.match(/^([|>])[+-]?\s*(?:#.*)?$/);
+    if (block) {
+      const folded = block[1] === ">";
+      const keyIndent = (line.match(/^(\s*)/) || ["", ""])[1].length;
+      const body = [];
+      let j = i + 1;
+      for (; j < lines.length; j++) {
+        if (lines[j].trim() === "") { body.push(""); continue; }
+        const ind = (lines[j].match(/^(\s*)/) || ["", ""])[1].length;
+        if (ind <= keyIndent) break;
+        body.push(lines[j]);
+      }
+      const firstContent = body.find((b) => b.trim() !== "") || "";
+      const baseIndent = (firstContent.match(/^(\s*)/) || ["", ""])[1].length;
+      const stripped = body.map((b) => b.slice(baseIndent));
+      while (stripped.length && stripped[stripped.length - 1].trim() === "") stripped.pop();
+      out[key] = folded ? stripped.join(" ").replace(/\s+/g, " ").trim() : stripped.join("\n");
+      i = j - 1;
+      continue;
+    }
+
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      v = v.slice(1, -1);
+    }
+    out[key] = v;
+  }
+  return out;
+}
+
+// ---------- secret redaction ----------
+const SECRET_HINT = /(key|token|secret|password|passwd|auth|bearer|credential|api[_-]?key|client[_-]?secret)/i;
+// A long opaque string that looks like a credential rather than a flag/package.
+const LOOKS_SECRET = /^(?:[A-Za-z0-9._\-]{24,}|sk-[A-Za-z0-9._\-]+|gh[pousr]_[A-Za-z0-9]+|xox[baprs]-[A-Za-z0-9-]+)$/;
+
+// A KEY=value pair whose key names a secret (e.g. API_KEY=…, auth-token=…).
+const SECRET_KV = /^[A-Za-z0-9_.-]*(?:key|token|secret|password|passwd|auth|bearer|credential)[A-Za-z0-9_.-]*=.+/i;
+
+// A bare opaque string that looks like a credential rather than a flag/package:
+// a known token shape, or 18+ mixed letters+digits in a single run (no path,
+// scope, or version shape) — so we don't redact package names ("playwright"),
+// semvers ("4.22.4"), or scoped packages ("@scope/pkg").
+function looksLikeToken(s) {
+  if (!s) return false;
+  if (LOOKS_SECRET.test(s)) return true;
+  return s.length >= 18 && /^[A-Za-z0-9._-]+$/.test(s) && /[A-Za-z]/.test(s) && /[0-9]/.test(s)
+    && !/^v?\d+\.\d+/.test(s) && !s.includes("..");
+}
+
+// Scrub secrets embedded *inside* a single string (a combined arg, or a prose
+// description): known token shapes anywhere, plus a secret-named label followed
+// by an opaque value (e.g. `Authorization: Bearer sk-…`, `X-Api-Key: abc123…`).
+function scrubSecrets(s) {
+  if (!s) return s;
+  return String(s)
+    .replace(/sk-[A-Za-z0-9._-]{8,}|gh[pousr]_[A-Za-z0-9]{8,}|xox[baprs]-[A-Za-z0-9-]{6,}|AKIA[0-9A-Z]{12,}/g, "<redacted>")
+    .replace(/((?:authorization|bearer|api[_-]?key|access[_-]?token|client[_-]?secret|x-[a-z-]*key|token|secret|password|passwd|credential)["':=\s]+)([A-Za-z0-9._\-+/]{12,})/gi, "$1<redacted>");
+}
+
+function redactArgs(argv) {
+  if (!Array.isArray(argv)) return argv;
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = String(argv[i]);
+    const prev = i > 0 ? String(argv[i - 1]) : "";
+    // Redact the value that follows a secret-introducing token (a flag like
+    // --token, or a bare label like "password"). Don't redact another flag.
+    if (prev && SECRET_HINT.test(prev) && !/^-/.test(a) && !SECRET_HINT.test(a)) {
+      out.push("<redacted>"); continue;
+    }
+    // KEY=value where the key names a secret (flag or positional form).
+    if (SECRET_KV.test(a)) { out.push(a.split("=")[0] + "=<redacted>"); continue; }
+    // Any URL / connection string: always sanitize it — userinfo, query string,
+    // and token-looking path segments (some hosted MCP endpoints key by path).
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(a)) {
+      try { new URL(a); out.push(redactUrl(a)); continue; } catch { /* not a URL */ }
+    }
+    // A bare opaque token passed positionally.
+    if (looksLikeToken(a)) { out.push("<redacted>"); continue; }
+    // A secret embedded inside one combined arg (e.g. a single `--header` value).
+    const scrubbed = scrubSecrets(a);
+    if (scrubbed !== a) { out.push(scrubbed); continue; }
+    // Rewrite absolute home paths so usernames don't leak in args.
+    out.push(a.startsWith(HOME) ? tilde(a) : a);
+  }
+  return out;
+}
+
+function redactUrl(u) {
+  const raw = String(u);
+  try {
+    const url = new URL(raw);
+    const auth = url.username || url.password ? "redacted@" : "";
+    const segments = url.pathname.split("/").map((seg) => (looksLikeToken(seg) ? "<redacted>" : seg));
+    const query = url.search ? "?<redacted>" : "";
+    return `${url.protocol}//${auth}${url.host}${segments.join("/")}${query}`;
+  } catch {
+    return raw.replace(/([?&][^=]+=)[^&]+/g, "$1<redacted>");
+  }
+}
+
+function redactRecord(obj) {
+  if (!obj || typeof obj !== "object") return undefined;
+  const out = {};
+  for (const k of Object.keys(obj)) out[k] = "<redacted>";
+  return Object.keys(out).length ? out : undefined;
+}
+
+// Turn one MCP server config into a safe, human-readable summary.
+function summarizeMcp(name, cfg) {
+  if (!cfg || typeof cfg !== "object") return { transport: "unknown" };
+  const out = {};
+  const type = cfg.type || (cfg.url ? "http" : cfg.command ? "stdio" : "unknown");
+  out.transport = type;
+  if (cfg.command) {
+    out.command = cfg.command;
+    out.args = redactArgs(cfg.args);
+  }
+  if (cfg.url) out.url = redactUrl(cfg.url);
+  const env = redactRecord(cfg.env);
+  if (env) out.env = env;
+  const headers = redactRecord(cfg.headers);
+  if (headers) out.headers = headers;
+  return out;
+}
+
+// A short, readable label for an MCP source line.
+function mcpSourceLabel(summary) {
+  if (summary.url) { try { return new URL(summary.url).host; } catch { return summary.transport; } }
+  if (summary.command) return [summary.command, ...(summary.args || [])].join(" ").slice(0, 60);
+  return summary.transport;
+}
+
+// A one-line description for an MCP server (no secrets — summary is pre-redacted).
+function mcpDescription(summary) {
+  if (summary.url) { try { return `${summary.transport.toUpperCase()} MCP at ${new URL(summary.url).host}`; } catch { return `${summary.transport} MCP server`; } }
+  if (summary.command) return `stdio MCP via \`${[summary.command, ...(summary.args || [])].join(" ").slice(0, 80)}\``;
+  return `${summary.transport} MCP server`;
+}
+
+// ---------- usage classification ----------
+const DAY = 86_400_000;
+
+function classifyUsage(usageCount, lastUsedAt, { passive = false } = {}) {
+  const now = Date.now();
+  if (usageCount == null && lastUsedAt == null) return passive ? "info" : "unknown";
+  const count = usageCount || 0;
+  if (count > 0) return "good";
+  // count == 0
+  if (lastUsedAt && now - lastUsedAt < 7 * DAY) return "warn"; // recent but unused
+  return "bad";
+}
+
+function usageLabel(usageCount, lastUsedAt, usageClass) {
+  const now = Date.now();
+  if (usageClass === "unknown") return "no usage signal";
+  if (usageClass === "info") return "passive";
+  if (usageCount && usageCount > 0) {
+    return `✅ ${usageCount.toLocaleString()} use${usageCount === 1 ? "" : "s"}`;
+  }
+  if (lastUsedAt && now - lastUsedAt < 7 * DAY) return "⚠️ never (recent install)";
+  return "➖ never";
+}
+
+// ---------- transcript usage scanning (PRIVACY-CRITICAL) ----------
+// Streams ~/.claude/projects/*.jsonl (and one level deeper) line-by-line and
+// tallies how often each MCP server / agent / skill was invoked, plus the most
+// recent invocation time. The ONLY data extracted is names + counts + the
+// max timestamp per key — never prompt text, message prose, command text,
+// arguments, cwd, or file paths.
+//
+// Returns { byKey: Map<kind:name, { count, lastUsed }>, totalInvocations, transcriptsScanned }.
+// `kind` is one of "mcp" | "agent" | "skill". Keys are stored normalized.
+
+// Normalize a name for matching: lowercase, drop a leading "plugin_" / "plugin:"
+// namespace, and (for "plugin:skill" / "<plugin>:<id>" shapes) take the
+// meaningful trailing segment. Keeps things like "vercel:deploy" → "deploy".
+function normalizeName(s) {
+  if (!s) return "";
+  let n = String(s).toLowerCase().trim();
+  // Strip a leading plugin_ prefix (e.g. "plugin_vercel_vercel" handled by caller's
+  // server logic; here we just remove a bare "plugin_" / "plugin:" lead-in).
+  n = n.replace(/^plugin[_:]/, "");
+  // If namespaced with a colon, take the trailing segment ("vercel:deploy" → "deploy").
+  if (n.includes(":")) n = n.split(":").pop();
+  return n.trim();
+}
+
+// Derive the MCP server name from a tool name like "mcp__<server>__<tool>".
+// Also collapse the "plugin_<x>_<server>" convention down to "<server>" so it
+// matches a configured MCP item named "<server>".
+function mcpServerFromToolName(toolName) {
+  const m = String(toolName).match(/^mcp__(.+?)__/);
+  if (!m) return null;
+  let server = m[1];
+  // "plugin_vercel_vercel" → "vercel"; "plugin_claude-mem_mcp-search" → "mcp-search".
+  const pm = server.match(/^plugin_[^_]+_(.+)$/);
+  if (pm) server = pm[1];
+  return server;
+}
+
+function transcriptKey(kind, name) {
+  return `${kind}:${normalizeName(name)}`;
+}
+
+// Discover candidate .jsonl transcript files under a projects dir:
+// projectsDir/*.jsonl and projectsDir/<sub>/*.jsonl (one level deeper).
+function findTranscriptFiles(projectsDir) {
+  const files = [];
+  for (const entry of listDir(projectsDir, "dir")) {
+    const sub = path.join(projectsDir, entry);
+    for (const f of listDir(sub, "file")) {
+      if (f.endsWith(".jsonl")) files.push(path.join(sub, f));
+    }
+  }
+  // Also pick up any .jsonl sitting directly in projectsDir.
+  for (const f of listDir(projectsDir, "file")) {
+    if (f.endsWith(".jsonl")) files.push(path.join(projectsDir, f));
+  }
+  return files;
+}
+
+// Tally one decoded transcript line into the byKey map.
+function tallyLine(obj, byKey) {
+  if (!obj || typeof obj !== "object") return 0;
+  const content = obj.message && obj.message.content;
+  if (!Array.isArray(content)) return 0;
+  const ts = obj.timestamp ? Date.parse(obj.timestamp) : NaN;
+  const when = Number.isFinite(ts) ? ts : null;
+  let counted = 0;
+  for (const part of content) {
+    if (!part || part.type !== "tool_use" || typeof part.name !== "string") continue;
+    const toolName = part.name;
+    let key = null;
+    if (/^mcp__(.+?)__/.test(toolName)) {
+      const server = mcpServerFromToolName(toolName);
+      if (server) key = transcriptKey("mcp", server);
+    } else if (toolName === "Agent" || toolName === "Task") {
+      const sub = part.input && part.input.subagent_type;
+      if (typeof sub === "string" && sub) key = transcriptKey("agent", sub);
+    } else if (toolName === "Skill") {
+      const sk = part.input && part.input.skill;
+      if (typeof sk === "string" && sk) key = transcriptKey("skill", sk);
+    }
+    if (!key) continue;
+    const rec = byKey.get(key) || { count: 0, lastUsed: null };
+    rec.count += 1;
+    if (when != null && (rec.lastUsed == null || when > rec.lastUsed)) rec.lastUsed = when;
+    byKey.set(key, rec);
+    counted += 1;
+  }
+  return counted;
+}
+
+async function scanOneTranscript(file, byKey) {
+  let total = 0;
+  await new Promise((resolve) => {
+    let stream;
+    try {
+      stream = fs.createReadStream(file, { encoding: "utf8" });
+    } catch { resolve(); return; }
+    stream.on("error", () => resolve());
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    rl.on("line", (line) => {
+      const s = line.trim();
+      if (!s) return;
+      let obj;
+      try { obj = JSON.parse(s); } catch { return; } // skip unparseable lines
+      total += tallyLine(obj, byKey);
+    });
+    rl.on("error", () => resolve());
+    rl.on("close", () => resolve());
+  });
+  return total;
+}
+
+async function scanTranscripts({ transcriptsDir, quiet = false } = {}) {
+  const dir = transcriptsDir || path.join(CLAUDE, "projects");
+  const byKey = new Map();
+  if (!exists(dir)) {
+    return { byKey, totalInvocations: 0, transcriptsScanned: 0 };
+  }
+  const files = findTranscriptFiles(dir);
+  if (!quiet) {
+    process.stderr.write(`  scanning ${files.length} transcript file${files.length === 1 ? "" : "s"}…\n`);
+  }
+  let totalInvocations = 0;
+  let transcriptsScanned = 0;
+  for (const file of files) {
+    totalInvocations += await scanOneTranscript(file, byKey);
+    transcriptsScanned += 1;
+  }
+  return { byKey, totalInvocations, transcriptsScanned };
+}
+
+// ---------- project labels ----------
+// Map each eligible project dir to a unique display label. Normally the basename,
+// but when two project paths share a basename (e.g. ~/a/web and ~/b/web) the bare
+// basename would collapse them into one inventory group with a single (last-wins)
+// location. Colliding ones are qualified with their parent dir ("a/web", "b/web"),
+// falling back to the full home-relative path if even that still collides — so
+// distinct projects always stay distinct.
+function buildProjectLabels(paths) {
+  const byBase = new Map();
+  for (const p of paths) {
+    const b = path.basename(p);
+    const arr = byBase.get(b);
+    if (arr) arr.push(p); else byBase.set(b, [p]);
+  }
+  const labels = new Map();
+  for (const [base, group] of byBase) {
+    if (group.length === 1) { labels.set(group[0], base); continue; }
+    const byParent = new Map();
+    for (const p of group) {
+      const q = `${path.basename(path.dirname(p))}/${base}`;
+      const arr = byParent.get(q);
+      if (arr) arr.push(p); else byParent.set(q, [p]);
+    }
+    for (const [qualified, qgroup] of byParent) {
+      if (qgroup.length === 1) labels.set(qgroup[0], qualified);
+      else for (const p of qgroup) labels.set(p, tilde(p)); // last resort: unique path
+    }
+  }
+  return labels;
+}
+
+// ---------- inventory build ----------
+// Collects every skill / agent / plugin / MCP item from the local install,
+// optionally overlays transcript usage, and returns the inventory OBJECT.
+// Does NOT write or print anything.
+export async function buildInventory(opts = {}) {
+  const { transcripts = true, transcriptsDir, quiet = false } = opts;
+
+  const root = readJSON(path.join(HOME, ".claude.json")) || {};
+  const skillUsage = root.skillUsage || {};
+  const pluginUsage = root.pluginUsage || {};
+
+  const items = [];
+  const projectNames = new Set();
+  // basename -> tilde'd `.claude` dir for each project that has any items. Emitted
+  // so the web app can show a project's on-disk location even when it has only MCP
+  // servers (which carry no per-item path for the UI to derive a location from).
+  const projectLocations = {};
+
+  function addSkill(scope, project, dirName, skillDir) {
+    const fm = parseFrontmatter(readText(path.join(skillDir, "SKILL.md")));
+    const name = fm.name || dirName;
+    // usage tables key skills by their invocation name (bare or plugin:skill).
+    const u = skillUsage[name] || skillUsage[dirName] || null;
+    const usageCount = u ? (u.usageCount ?? null) : null;
+    const lastUsedAt = u ? (u.lastUsedAt ?? null) : null;
+    const usageClass = classifyUsage(usageCount, lastUsedAt);
+    items.push({
+      id: `skill:${scope === "global" ? "global" : "project:" + project}:${dirName}`,
+      type: "skill", scope, project: scope === "global" ? null : project,
+      name, description: scrubSecrets(fm.description || ""),
+      path: tilde(skillDir),
+      usageCount, lastUsedAt, usageClass,
+      usageLabel: usageLabel(usageCount, lastUsedAt, usageClass),
+      // dir name is used to match transcript Skill invocations (input.skill).
+      _matchKind: "skill", _matchName: dirName,
+      removeCmd: scope === "global"
+        ? `rm -rf ${tilde(skillDir)}`
+        : `git rm -r .claude/skills/${dirName}`,
+    });
+  }
+
+  function addAgent(scope, project, fileName, agentFile) {
+    const base = fileName.replace(/\.md$/, "");
+    const fm = parseFrontmatter(readText(agentFile));
+    const name = fm.name || base;
+    const u = skillUsage[name] || skillUsage[base] || null; // agents sometimes appear here too
+    const usageCount = u ? (u.usageCount ?? null) : null;
+    const lastUsedAt = u ? (u.lastUsedAt ?? null) : null;
+    const usageClass = classifyUsage(usageCount, lastUsedAt, { passive: true });
+    items.push({
+      id: `agent:${scope === "global" ? "global" : "project:" + project}:${base}`,
+      type: "agent", scope, project: scope === "global" ? null : project,
+      name, description: scrubSecrets(fm.description || ""),
+      path: tilde(agentFile),
+      usageCount, lastUsedAt, usageClass,
+      usageLabel: usageLabel(usageCount, lastUsedAt, usageClass),
+      // filename stem is used to match transcript Agent invocations (subagent_type).
+      _matchKind: "agent", _matchName: base,
+      removeCmd: scope === "global"
+        ? `rm ${tilde(agentFile)}`
+        : `git rm .claude/agents/${fileName}`,
+    });
+  }
+
+  function addMcp(scope, project, name, cfg) {
+    const summary = summarizeMcp(name, cfg);
+    items.push({
+      id: `mcp:${scope === "global" ? "global" : "project:" + project}:${name}`,
+      type: "mcp", scope, project: scope === "global" ? null : project,
+      name, description: mcpDescription(summary),
+      source: mcpSourceLabel(summary),
+      usageCount: null, lastUsedAt: null, usageClass: "info",
+      usageLabel: "passive (surfaced on demand)",
+      // server name is used to match transcript mcp__<server>__ invocations.
+      _matchKind: "mcp", _matchName: name,
+      removeCmd: scope === "global"
+        ? `claude mcp remove ${name} -s user`
+        : `claude mcp remove ${name}`,
+    });
+  }
+
+  // ---- global skills ----
+  const globalSkillsDir = path.join(CLAUDE, "skills");
+  for (const d of listDir(globalSkillsDir, "dir")) {
+    const dir = path.join(globalSkillsDir, d);
+    if (exists(path.join(dir, "SKILL.md"))) addSkill("global", null, d, dir);
+  }
+
+  // ---- global agents ----
+  const globalAgentsDir = path.join(CLAUDE, "agents");
+  for (const f of listDir(globalAgentsDir, "file")) {
+    if (f.endsWith(".md")) addAgent("global", null, f, path.join(globalAgentsDir, f));
+  }
+
+  // ---- plugins (global; installed_plugins.json) ----
+  const installed = readJSON(path.join(CLAUDE, "plugins", "installed_plugins.json"));
+  if (installed && installed.plugins) {
+    for (const [key, entries] of Object.entries(installed.plugins)) {
+      const entry = Array.isArray(entries) ? entries[0] : entries;
+      const [pluginName, marketplace] = key.split("@");
+      const u = pluginUsage[key] || null;
+      const usageCount = u ? (u.usageCount ?? null) : null;
+      const lastUsedAt = u ? (u.lastUsedAt ?? null) : null;
+      const usageClass = classifyUsage(usageCount, lastUsedAt);
+      const installPath = entry && entry.installPath
+        ? (entry.installPath.startsWith(HOME) ? tilde(entry.installPath) : "<external>")
+        : undefined;
+      items.push({
+        // Bare name; the marketplace lives in `source` (matches the demo shape).
+        id: `plugin:global:${pluginName}`,
+        type: "plugin", scope: "global", project: null,
+        name: pluginName,
+        description: "", // not stored locally; the demo/curation can add it
+        source: marketplace || "",
+        version: entry ? entry.version : undefined,
+        path: installPath,
+        usageCount, lastUsedAt, usageClass,
+        usageLabel: usageLabel(usageCount, lastUsedAt, usageClass),
+        // The CLI wants the full name@marketplace form to uninstall.
+        removeCmd: `claude plugins uninstall ${key} -y`,
+      });
+    }
+  }
+
+  // ---- global MCP servers ----
+  for (const [name, cfg] of Object.entries(root.mcpServers || {})) {
+    addMcp("global", null, name, cfg);
+  }
+
+  // ---- per-project (from every known project path in ~/.claude.json) ----
+  const projectPaths = new Set();
+  if (exists(path.join(process.cwd(), ".claude")) || exists(path.join(process.cwd(), ".mcp.json"))) {
+    projectPaths.add(process.cwd());
+  }
+  for (const p of Object.keys(root.projects || {})) projectPaths.add(p);
+
+  // Keep only real, non-global project dirs. The home directory's .claude IS the
+  // global scope, so a project path resolving to it (the scan ran from $HOME, or
+  // $HOME is registered in ~/.claude.json's projects) would duplicate every global
+  // skill/agent/MCP as a phantom project named after your username — skip it.
+  const eligiblePaths = [...projectPaths].filter(
+    (p) => exists(p) && path.resolve(path.join(p, ".claude")) !== path.resolve(CLAUDE),
+  );
+  // Disambiguate any project dirs that share a basename so they stay distinct.
+  const projectLabels = buildProjectLabels(eligiblePaths);
+
+  for (const projPath of eligiblePaths) {
+    const project = projectLabels.get(projPath) || path.basename(projPath);
+    const projConf = (root.projects && root.projects[projPath]) || {};
+
+    let touched = false;
+
+    // project skills
+    const pSkills = path.join(projPath, ".claude", "skills");
+    for (const d of listDir(pSkills, "dir")) {
+      const dir = path.join(pSkills, d);
+      if (exists(path.join(dir, "SKILL.md"))) { addSkill("project", project, d, dir); touched = true; }
+    }
+    // project agents
+    const pAgents = path.join(projPath, ".claude", "agents");
+    for (const f of listDir(pAgents, "file")) {
+      if (f.endsWith(".md")) { addAgent("project", project, f, path.join(pAgents, f)); touched = true; }
+    }
+    // project MCP servers — from ~/.claude.json projects[path].mcpServers and/or .mcp.json
+    const fromConf = projConf.mcpServers || {};
+    const fromFile = (readJSON(path.join(projPath, ".mcp.json")) || {}).mcpServers || {};
+    for (const [name, cfg] of Object.entries({ ...fromFile, ...fromConf })) {
+      addMcp("project", project, name, cfg); touched = true;
+    }
+
+    if (touched) {
+      projectNames.add(project);
+      projectLocations[project] = tilde(path.join(projPath, ".claude"));
+    }
+  }
+
+  // ---- transcript usage overlay ----
+  let usageSummary;
+  if (transcripts) {
+    const { byKey, totalInvocations, transcriptsScanned } = await scanTranscripts({ transcriptsDir, quiet });
+
+    // Match each tracked item (skill / agent / mcp) to its transcript tally.
+    let itemsWithUsage = 0;
+    let itemsUnused = 0;
+    for (const item of items) {
+      if (!item._matchKind) continue; // plugins are not transcript-tracked
+      const key = transcriptKey(item._matchKind, item._matchName);
+      const rec = byKey.get(key);
+      const count = rec ? rec.count : 0;
+      const last = rec ? rec.lastUsed : null;
+      item.invocationCount = count;
+      item.lastUsed = last;
+      item.usageSource = "transcripts";
+      if (count > 0) {
+        itemsWithUsage += 1;
+        // Light up the existing UI fields from the transcript signal.
+        item.usageCount = count;
+        item.lastUsedAt = last;
+        item.usageClass = classifyUsage(count, last);
+        item.usageLabel = usageLabel(count, last, item.usageClass);
+      } else {
+        // No transcript invocations → genuinely never used. Reflect that in the
+        // existing UI fields so the per-item badge, the "unused" filter, the
+        // stat cell, and usageSummary.itemsUnused all describe the same set.
+        // (The transcript corpus is the authoritative usage record; a tracked
+        // item absent from it has not been used.)
+        item.usageCount = 0;
+        item.lastUsedAt = last;
+        item.usageClass = classifyUsage(0, last);
+        item.usageLabel = usageLabel(0, last, item.usageClass);
+        itemsUnused += 1;
+      }
+    }
+
+    usageSummary = {
+      totalInvocations,
+      itemsWithUsage,
+      itemsUnused,
+      transcriptsScanned,
+      generatedFrom: "transcripts",
+    };
+  } else {
+    // Transcripts disabled — preserve today's ~/.claude.json behavior and just
+    // annotate the usageSource per item so consumers know where the signal came from.
+    for (const item of items) {
+      if (item.type === "skill") {
+        item.usageSource = (item.usageCount != null || item.lastUsedAt != null) ? "claude-json" : "none";
+      } else if (item.type === "agent" || item.type === "mcp") {
+        item.usageSource = "none";
+      }
+    }
+  }
+
+  // Drop internal matching helpers before emitting.
+  for (const item of items) { delete item._matchKind; delete item._matchName; }
+
+  const inventory = {
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    generator: GENERATOR,
+    machine: { platform: process.platform, node: process.version },
+    projects: [...projectNames].sort((a, b) => a.localeCompare(b)),
+    projectLocations,
+    items,
+  };
+  if (usageSummary) inventory.usageSummary = usageSummary;
+  return inventory;
+}
+
+// ---------- scan: build + write/print + log summary ----------
+export async function runScan(opts = {}) {
+  const {
+    stdout = false,
+    outFile = "stack-cleaner.json",
+    transcripts = true,
+    transcriptsDir,
+    quiet = false,
+  } = opts;
+
+  const inventory = await buildInventory({ transcripts, transcriptsDir, quiet });
+  const json = JSON.stringify(inventory, null, 2);
+
+  const outPath = path.resolve(process.cwd(), outFile);
+  if (stdout) {
+    process.stdout.write(json + "\n");
+  } else {
+    fs.writeFileSync(outPath, json);
+  }
+
+  // summary counts for the console
+  const items = inventory.items;
+  const by = (t) => items.filter((i) => i.type === t).length;
+  const g = items.filter((i) => i.scope === "global").length;
+  const p = items.length - g;
+
+  const log = (s) => process.stderr.write(s + "\n");
+  log("");
+  log("  Stack Cleaner — scan complete");
+  log("  ─────────────────────────────────────");
+  log(`  skills ${by("skill")}   plugins ${by("plugin")}   mcp ${by("mcp")}   agents ${by("agent")}`);
+  log(`  ${g} global · ${p} project   across ${inventory.projects.length} project${inventory.projects.length === 1 ? "" : "s"}`);
+  if (inventory.usageSummary) {
+    const us = inventory.usageSummary;
+    log(`  usage: ${us.totalInvocations.toLocaleString()} invocations · ${us.itemsWithUsage} used · ${us.itemsUnused} unused   (${us.transcriptsScanned} transcript${us.transcriptsScanned === 1 ? "" : "s"})`);
+  }
+  log("");
+  if (!stdout) {
+    log(`  ✓ wrote ${outPath}`);
+    log("  → open the web app and drop this file in.");
+    log("");
+  }
+  return inventory;
+}
+
+export { scrubSecrets, redactArgs, redactUrl, looksLikeToken, buildProjectLabels };
+
+// ---------- CLI arg parsing + auto-run guard ----------
+function parseArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--stdout" || a === "--print") opts.stdout = true;
+    else if (a === "--no-transcripts") opts.transcripts = false;
+    else if (a === "--transcripts-dir") opts.transcriptsDir = argv[++i];
+    else if (a.startsWith("--transcripts-dir=")) opts.transcriptsDir = a.slice("--transcripts-dir=".length);
+    else if (a === "--out") opts.outFile = argv[++i];
+    else if (a.startsWith("--out=")) opts.outFile = a.slice("--out=".length);
+  }
+  return opts;
+}
+
+// Run when invoked directly (`node scan.mjs`) or piped (`curl … | node`),
+// but NOT when imported (e.g. by bin/cli.mjs).
+const invokedDirectly = !process.argv[1] || import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  runScan(parseArgs(process.argv.slice(2))).catch((err) => {
+    process.stderr.write(`\n  ✗ scan failed: ${err && err.message ? err.message : err}\n`);
+    process.exit(1);
+  });
+}