memoryintel 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "memoryintel",
+  "owner": {
+    "name": "Adeesh Sharma",
+    "url": "https://github.com/adeeshsharma"
+  },
+  "metadata": {
+    "description": "Persistent, cross-session project memory for AI coding agents.",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "memoryintel",
+      "source": "./",
+      "description": "Persistent project memory for AI coding agents — initialize once, then agents automatically load and update project understanding across sessions.",
+      "version": "1.0.0"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "memoryintel",
+  "description": "Persistent project memory for AI coding agents — initialize once, then agents automatically load and update project understanding across sessions.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Adeesh Sharma",
+    "url": "https://github.com/adeeshsharma"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adeesh Sharma
+
+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,192 @@
+# Memory Intel
+
+[![CI](https://github.com/adeeshsharma/memoryintel/actions/workflows/ci.yml/badge.svg)](https://github.com/adeeshsharma/memoryintel/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/memoryintel.svg)](https://www.npmjs.com/package/memoryintel)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Persistent, cross-session project memory for AI coding agents. Set it up once per project; after
+that, agents automatically load and update project understanding — architecture, decisions,
+progress, a running "mental model" — across new chats, new sessions, and even across tools
+(Claude Code, Cursor, Codex, Gemini CLI).
+
+This repository is itself running Memory Intel on itself — see `.memoryintel/` for the tool's own
+current state, decisions, and open todo items. Any agent with the skill below active will read it
+automatically.
+
+## Quick Start
+
+```bash
+npx skills add adeeshsharma/memoryintel --skill memoryintel   # teaches an agent the shape of it
+npm install -g memoryintel                                      # the CLI those instructions call
+```
+
+Then, in any project, ask an agent to "set up persistent memory here" once. From then on, `load`/
+`update` fire automatically via Claude Code's `SessionStart`/`Stop` hooks (see "Point Claude Code
+at the plugin" below) — nothing else to remember. See `.memoryintel/instructions.md` in a given
+project for its own specific guidance once initialized.
+
+## Install
+
+**The CLI** is on the npm registry:
+
+```bash
+npm install -g memoryintel
+# or run it without installing:
+npx memoryintel status
+```
+
+**The Claude Code plugin** — this is what actually wires up automatic `SessionStart`/`Stop`
+hooks, not just agent-readable instructions. This repo is its own marketplace
+(`.claude-plugin/marketplace.json`), so no separate hosting or git clone is needed:
+
+```bash
+claude plugin marketplace add adeeshsharma/memoryintel
+claude plugin install memoryintel@memoryintel
+```
+
+That's a one-time install — restart Claude Code and the hooks are active for every session from
+then on, in every project. See "Skill vs. plugin" below if it's not obvious why this is a plugin
+and not just a skill.
+
+**Just the skill, no automation** — if you want the agent-facing instructions (what `memoryintel
+init`/`load`/`update` are and when to use them) without the automatic hooks, install it standalone:
+
+```bash
+npx skills add adeeshsharma/memoryintel --skill memoryintel
+```
+
+<details>
+<summary>Developing/testing this plugin locally, without the marketplace</summary>
+
+```bash
+claude --plugin-dir "$(npm root -g)/memoryintel"   # or any local checkout
+```
+
+`--plugin-dir` is Claude Code's own documented flag for loading a plugin from a specific
+directory for one session, bypassing marketplaces entirely (see
+[Create plugins](https://code.claude.com/docs/en/plugins)). Needs to be passed every launch; a
+shell alias avoids retyping it:
+
+```bash
+alias claude-mi='claude --plugin-dir "$(npm root -g)/memoryintel"'
+```
+
+</details>
+
+### Skill vs. plugin
+
+A **skill** is just instructions loaded into an agent's context — it teaches an agent *what to
+do*, and the agent decides on its own judgment *whether* to act on it. A **plugin** is a bundle
+that can include a skill *and* hooks — commands Claude Code itself runs automatically at fixed
+lifecycle moments (`SessionStart`, `Stop`), no agent judgment involved. Memory Intel's plugin
+bundles both: the skill (`skills/memoryintel/SKILL.md`) plus `hooks/hooks.json`, which runs
+`memoryintel load` at the start of every session and `memoryintel check-stop` at the end of every
+one — the latter can even block finishing until memory's been updated. The standalone skill
+install above gives an agent the knowledge; only the plugin gives you the automation that doesn't
+depend on the agent noticing anything.
+
+### If you don't want to touch Claude Code's plugin system at all
+
+The CLI works standalone, with no plugin/skill/hook involved — useful for scripting, for other
+tools, or just to try it out:
+
+```bash
+memoryintel init      # once per project — scaffolds .memoryintel/, installs pointer files
+                       # for tools without native hooks (Cursor, Codex, Gemini CLI, opencode)
+memoryintel load       # print resolved context to stdout
+memoryintel update plan.toon   # apply an update-plan
+```
+
+`memoryintel init` never touches a project's own `.claude/settings.json` — Claude Code automation
+comes entirely from the plugin's own `hooks/hooks.json` in this repo, active once the plugin
+itself is active. From then on, agents load and update project memory on their own, per that
+project's own `.memoryintel/instructions.md`.
+
+If a shared local dashboard is running (a read-only view of every initialized project on this
+machine), turn it off any time with `memoryintel dashboard disable` — or back on with
+`memoryintel dashboard enable`.
+
+## Prerequisites
+
+Node.js ≥18 — actually verified as the real floor (CI runs the full suite on Node 18), not an
+assumed default.
+
+## How it works
+
+Full design docs live in `docs/superpowers/specs/`; a diagram-heavy architecture reference lives
+in `docs/architecture/memory-intel-architecture.html`. In short: `.memoryintel/` is a structured,
+git-committed set of markdown/JSON files an agent reads at session start and selectively updates
+when something meaningful changes — never a changelog, always a maintained understanding of the
+project as it currently is. See `.memoryintel/context/decisions.md` in this very repository for
+the specific design decisions behind that, with rationale.
+
+## Benchmarks: with vs. without
+
+Measured on a real second project ([distilled-docs](https://github.com/adeeshsharma/distilled-docs),
+an 8-phase, single-day build), not a synthetic one. Methodology: real file sizes from that
+project's actual `.memoryintel/` state, tokens estimated at ~4 chars/token (a standard, slightly
+conservative approximation — not measured API telemetry, since neither path logs real token
+counts from the model provider).
+
+**Per-session context bootstrap:**
+
+| | Chars | Tokens (est.) |
+|---|---|---|
+| `memoryintel load` (curated: mental model + active context + technical domain) | 9,223 | ~2,300 |
+| No memory, conservative (skim one architecture doc) | 6,126 | ~1,500 |
+| No memory, realistic (doc + git log + a handful of source files) | ~28,000 | ~7,000 |
+| No memory, worst case (re-derive from the full source tree, 49 files) | 113,652 | ~28,400 |
+
+That's **67–92% fewer tokens per session bootstrap**, depending on how much of the codebase an
+agent would otherwise need to re-read to reach equivalent situational awareness — and that range
+brackets the same order of magnitude as published numbers from purpose-built memory systems for
+chat agents ([Mem0](https://arxiv.org/pdf/2504.19413): ~90% vs. full context; Letta/MemGPT-class
+systems: 85–93%), despite solving a different problem (durable project state, not conversation
+history).
+
+**Why the gap widens over time, not just per-call:** `.memoryintel/` content is self-compressing,
+capped at ~300 lines per file by default — load cost stays roughly flat as a project grows. The
+no-memory alternative doesn't; it scales with total codebase size. A project one day old and one
+a year old cost about the same to bootstrap with Memory Intel. Without it, the older project costs
+more, every single session.
+
+**Not just tokens:** `context/decisions.md` and `context/learnings.md` hold things a memory-less
+agent would otherwise silently redo or get wrong twice — a real example from that same build: a
+subtle bundler bug (a literal-string dynamic `import()` statically resolved by esbuild instead of
+treated as a runtime URL) got fixed once and recorded, not re-debugged on the next session that
+touched that code path.
+
+These numbers are reproducible for your own project: every `memoryintel load` call logs a
+`session-load` event (domain, files, character/line counts) to `memory-events.jsonl`, visible in
+the dashboard's "Session activity" section or queryable directly from the event log.
+
+## Development
+
+Working on this repo itself, rather than just using the published package:
+
+```bash
+git clone https://github.com/adeeshsharma/memoryintel.git
+cd memoryintel
+npm install
+npm run build                # compiles dist/, regenerates skills/memoryintel/SKILL.md from src/skill.ts
+npm link                     # makes `memoryintel` resolve to this exact checkout instead of the published one
+npm test                     # 207 tests, vitest
+npm run build:skill:check    # fails if skills/memoryintel/SKILL.md has drifted from src/skill.ts
+```
+
+CI (`.github/workflows/ci.yml`) runs the full suite on Ubuntu, Windows, and macOS on every
+push/PR to `master`, and is required via branch protection.
+
+## Releasing
+
+Automated with [release-please](https://github.com/googleapis/release-please) and npm [Trusted
+Publishing](https://docs.npmjs.com/trusted-publishers/) — see [RELEASING.md](RELEASING.md).
+`CHANGELOG.md` is generated automatically starting with the first automated release.
+
+## Contributing
+
+Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/adapters/claudeCode.js

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { runGitStatusPorcelain, porcelainPath, runGitRevParseHead } from '../core/gitPorcelain.js';
+function readMarker(markerPath) {
+    if (!existsSync(markerPath))
+        return { lastFlaggedDiffSignature: null };
+    try {
+        const raw = readFileSync(markerPath, 'utf-8').trim();
+        if (raw.length === 0)
+            return { lastFlaggedDiffSignature: null };
+        const parsed = JSON.parse(raw);
+        return { lastFlaggedDiffSignature: typeof parsed.lastFlaggedDiffSignature === 'string' ? parsed.lastFlaggedDiffSignature : null };
+    }
+    catch {
+        return { lastFlaggedDiffSignature: null };
+    }
+}
+function writeMarker(markerPath, marker) {
+    writeFileSync(markerPath, JSON.stringify(marker));
+}
+// Combines the current HEAD commit with the sorted, joined `git status --porcelain` output - a
+// stable signature for "what's currently dirty, at what commit" - or null if this isn't a git
+// repository / git failed for any reason.
+//
+// HEAD is part of the signature, not just the working-tree diff: a diff-only signature goes
+// back to '' the moment a commit lands, even one this project's own memory never recorded -
+// this project's own established workflow is to commit promptly, so a diff-only signature was
+// blind to almost every real change by the time anyone would notice. Confirmed on a real
+// project (distilled-docs): `.session-marker.json` had never once recorded a flagged diff in
+// its whole history, despite real, uncommitted work sitting there unaccounted for, because every
+// prior unit of work had already been committed by the time any check-stop would have seen it.
+//
+// Excludes anything under .memoryintel/ entirely from the working-tree half: this function's own
+// marker writes (and `update`'s writes to memory files) would otherwise show up as part of the
+// very diff being tracked, causing every check to see a "new" signature forever, even with no
+// real code change.
+function computeDiffSignature(projectRoot) {
+    const lines = runGitStatusPorcelain(projectRoot);
+    if (lines === null)
+        return null;
+    const filtered = lines
+        .filter((l) => {
+        const path = porcelainPath(l);
+        return path !== '.memoryintel' && !path.startsWith('.memoryintel/');
+    })
+        .sort();
+    const head = runGitRevParseHead(projectRoot) ?? '';
+    return `${head}\n${filtered.join('\n')}`;
+}
+function isWorkingTreeDirty(projectRoot) {
+    const lines = runGitStatusPorcelain(projectRoot);
+    if (lines === null)
+        return false;
+    return lines.some((l) => {
+        const path = porcelainPath(l);
+        return path !== '.memoryintel' && !path.startsWith('.memoryintel/');
+    });
+}
+export function runCheckStop(memoryRoot) {
+    const projectRoot = dirname(memoryRoot);
+    const markerPath = join(memoryRoot, '.session-marker.json');
+    const marker = readMarker(markerPath);
+    const signature = computeDiffSignature(projectRoot);
+    if (signature === null)
+        return { decision: 'allow' };
+    if (signature === marker.lastFlaggedDiffSignature) {
+        return { decision: 'allow' };
+    }
+    // A brand-new marker (nothing has ever been flagged or resolved in this project) with a
+    // currently-clean working tree has nothing actionable to report - baseline silently so a
+    // FUTURE commit or dirty file compares against this starting point, rather than blocking
+    // just because this exact HEAD has never been seen before, which would nag on every fresh
+    // project's very first Stop event.
+    if (marker.lastFlaggedDiffSignature === null && !isWorkingTreeDirty(projectRoot)) {
+        writeMarker(markerPath, { lastFlaggedDiffSignature: signature });
+        return { decision: 'allow' };
+    }
+    writeMarker(markerPath, { lastFlaggedDiffSignature: signature });
+    return {
+        decision: 'block',
+        reason: "Working tree has changes memory hasn't accounted for. Classify them, write a TOON update-plan, and run `memoryintel update <plan-file>` (see .memoryintel/instructions.md) before finishing - running `memoryintel update` bare, with no plan file, fails. Or finish again to proceed without updating this time."
+    };
+}
+// Called after a successful `update`. Does NOT simply clear the marker to null — `update` only
+// writes to .memoryintel/, so the user's actual source diff that triggered the nudge (e.g. an
+// uncommitted src.js) is still sitting there afterward. Clearing to null would make that
+// still-present, already-addressed diff look "new" again on the very next check-stop call,
+// causing an immediate re-block right after the agent just logged something — the opposite of
+// the intended anti-nag behavior. Instead, capture the CURRENT diff signature as the new
+// baseline: "this exact situation has now been accounted for."
+export function resolveCheckStopMarker(memoryRoot) {
+    const markerPath = join(memoryRoot, '.session-marker.json');
+    const projectRoot = dirname(memoryRoot);
+    const signature = computeDiffSignature(projectRoot);
+    writeMarker(markerPath, { lastFlaggedDiffSignature: signature ? signature : null });
+}

package/dist/adapters/genericPointer.js

@@ -0,0 +1,39 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const START_MARKER = '<!-- memoryintel:managed:start -->';
+const END_MARKER = '<!-- memoryintel:managed:end -->';
+const POINTER_BLOCK = `${START_MARKER}
+This project uses Memory Intel. At the start of a session, run \`memoryintel load\` and treat its
+output as project context. Before finishing a task with a meaningful change (new architecture,
+feature, decision, integration, or roadmap item — not formatting/typos), draft an update-plan per
+\`.memoryintel/instructions.md\` and run \`memoryintel update\`, without narrating this to the user.
+${END_MARKER}`;
+function upsertPointerBlock(filePath, existingContentIfNew) {
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, `${existingContentIfNew}${POINTER_BLOCK}\n`);
+        return;
+    }
+    const content = readFileSync(filePath, 'utf-8');
+    if (content.includes(START_MARKER))
+        return; // already installed, idempotent no-op
+    const separator = content.endsWith('\n') ? '\n' : '\n\n';
+    writeFileSync(filePath, `${content}${separator}${POINTER_BLOCK}\n`);
+}
+const NATIVE_FILES = ['AGENTS.md', 'GEMINI.md'];
+export function installPointerAdapters(projectRoot) {
+    const existingNativeFiles = NATIVE_FILES.filter((f) => existsSync(join(projectRoot, f)));
+    if (existingNativeFiles.length > 0) {
+        for (const file of existingNativeFiles) {
+            upsertPointerBlock(join(projectRoot, file), '');
+        }
+    }
+    else {
+        upsertPointerBlock(join(projectRoot, 'AGENTS.md'), '# Project Instructions\n\n');
+    }
+    const cursorRulesDir = join(projectRoot, '.cursor', 'rules');
+    mkdirSync(cursorRulesDir, { recursive: true });
+    const cursorRulePath = join(cursorRulesDir, 'memoryintel.mdc');
+    if (!existsSync(cursorRulePath)) {
+        writeFileSync(cursorRulePath, `---\nalwaysApply: true\n---\n\n${POINTER_BLOCK}\n`);
+    }
+}

package/dist/cli.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findMemoryIntelRoot } from './core/discovery.js';
+import { runUpdate } from './commands/update.js';
+import { runLoad } from './commands/load.js';
+import { runStatus } from './commands/status.js';
+import { runInit } from './commands/init.js';
+import { runCheckStop } from './adapters/claudeCode.js';
+import { runDashboardEnable, runDashboardDisable } from './commands/dashboardToggle.js';
+import { runDaemonStart } from './commands/daemonStart.js';
+export const USAGE = `Usage: memoryintel <command> [options]
+
+Commands:
+  init [path]              Initialize .memoryintel/ in the current or given directory
+  load [--domain <d>]      Print resolved memory context to stdout
+  update <plan.toon|->     Apply an update-plan (file path, or - for stdin)
+  status                   Print a human-readable summary of current memory state
+  check-stop               Stop-hook check: emit a JSON allow/block decision
+  dashboard <enable|disable>  Turn the shared local dashboard on or off
+  daemon start             Run the dashboard daemon in the foreground (usually auto-started)
+
+An update-plan row may set kind=compress to compact an oversized section; update() only applies
+such a row when its target file is currently git-clean.
+`;
+export function dispatch(argv) {
+    const [command] = argv;
+    if (!command) {
+        return { exitCode: 0, stdout: USAGE, stderr: '' };
+    }
+    switch (command) {
+        case 'init': {
+            const target = argv[1] ? join(process.cwd(), argv[1]) : process.cwd();
+            runInit(target);
+            return { exitCode: 0, stdout: `Initialized Memory Intel in ${join(target, '.memoryintel')}\n`, stderr: '' };
+        }
+        case 'load': {
+            const domainFlagIndex = argv.indexOf('--domain');
+            const domain = domainFlagIndex !== -1 ? argv[domainFlagIndex + 1] : undefined;
+            const output = runLoad(process.cwd(), domain);
+            return { exitCode: 0, stdout: output, stderr: '' };
+        }
+        case 'status': {
+            const root = findMemoryIntelRoot(process.cwd());
+            if (!root)
+                return { exitCode: 1, stdout: '', stderr: 'No .memoryintel/ found.\n' };
+            return { exitCode: 0, stdout: runStatus(root), stderr: '' };
+        }
+        case 'check-stop': {
+            const root = findMemoryIntelRoot(process.cwd());
+            if (!root)
+                return { exitCode: 0, stdout: '', stderr: '' };
+            const result = runCheckStop(root);
+            return { exitCode: 0, stdout: JSON.stringify(result) + '\n', stderr: '' };
+        }
+        case 'dashboard': {
+            const sub = argv[1];
+            if (sub === 'enable') {
+                runDashboardEnable();
+                return { exitCode: 0, stdout: 'Dashboard enabled. It will start on the next `load` or `update` call.\n', stderr: '' };
+            }
+            if (sub === 'disable') {
+                const result = runDashboardDisable();
+                return {
+                    exitCode: 0,
+                    stdout: `Dashboard disabled${result.stopped ? ' and stopped' : ''}. This affects the shared dashboard for every Memory Intel project on this machine.\n`,
+                    stderr: ''
+                };
+            }
+            return { exitCode: 1, stdout: '', stderr: 'Usage: memoryintel dashboard <enable|disable>\n' };
+        }
+        default:
+            return { exitCode: 1, stdout: USAGE, stderr: `Unknown command: ${command}\n` };
+    }
+}
+// Real process entrypoint — exercised by tests/cliBinary.test.ts, which spawns the built bin.
+//
+// Never call process.exit() here. Writes to a pipe (which is how Claude Code invokes the
+// SessionStart hook) are asynchronous, and process.exit() tears the process down without
+// flushing them — truncating output at the pipe buffer size (64 KB on Linux). Setting
+// process.exitCode and returning lets the event loop drain stdout first.
+async function main() {
+    const argv = process.argv.slice(2);
+    const [command] = argv;
+    try {
+        if (command === 'daemon' && argv[1] === 'start') {
+            await runDaemonStart();
+            // Intentionally never resolves further — this process IS the daemon, kept alive by the
+            // listening HTTP server, until `memoryintel dashboard disable` sends it SIGTERM.
+            return;
+        }
+        if (command === 'update') {
+            const root = findMemoryIntelRoot(process.cwd());
+            if (!root) {
+                process.stderr.write('No .memoryintel/ found.\n');
+                process.exitCode = 1;
+                return;
+            }
+            const source = argv[1] ?? '-';
+            const planText = source === '-' ? readFileSync(0, 'utf-8') : readFileSync(source, 'utf-8');
+            // Caught live: an agent ran bare `memoryintel update` (no plan-file argument, no piped
+            // stdin) as a one-shot Bash tool call. `source` defaulted to '-' (read stdin), stdin was
+            // immediately EOF, and the resulting empty planText fell through to decodeToonTable's
+            // generic "Malformed TOON table header" error - true, but useless for figuring out what
+            // actually went wrong. This is the one case worth naming explicitly before it gets there.
+            if (planText.trim().length === 0) {
+                process.stderr.write('memoryintel: No update-plan given. Pass a TOON plan file (`memoryintel update <path>`) or pipe TOON content via stdin. See .memoryintel/instructions.md for the update-plan format.\n');
+                process.exitCode = 1;
+                return;
+            }
+            const result = await runUpdate(root, planText);
+            process.stdout.write(`Applied: ${result.applied.join(', ') || '(none)'}\nSkipped: ${result.skipped.join(', ') || '(none)'}\n`);
+            process.exitCode = 0;
+            return;
+        }
+        const result = dispatch(argv);
+        process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        process.exitCode = result.exitCode;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`memoryintel: ${message.split('\n')[0]}\n`);
+        process.exitCode = 1;
+    }
+}
+function isDirectInvocation() {
+    if (!process.argv[1])
+        return false;
+    try {
+        // process.argv[1] is the path used to invoke this file, which may be a symlink
+        // (npm link, a global install's bin shim). Resolve it before comparing against
+        // import.meta.url — otherwise this check silently never matches when run through any
+        // linked/global binary name.
+        //
+        // Both sides are resolved through realpathSync, not just the argv[1] side: Node's own
+        // import.meta.url for the entry script and a realpath()'d process.argv[1] aren't
+        // guaranteed to agree on drive-letter casing on Windows (the entry URL doesn't necessarily
+        // go through the same filesystem-canonicalization pass argv[1] gets here), and NTFS is
+        // case-insensitive besides — an exact === comparison silently and permanently failed there,
+        // meaning main() never ran for a process spawned this way (e.g. the daemon's own child
+        // process, started via `node dist/cli.js daemon start`): no server ever bound, no error
+        // either, since nothing was left to keep the event loop alive. Caught live via a real CI
+        // Windows job: the daemon-spawn test found a live pid that then did nothing at all.
+        const invoked = realpathSync(process.argv[1]);
+        const self = realpathSync(fileURLToPath(import.meta.url));
+        return process.platform === 'win32' ? invoked.toLowerCase() === self.toLowerCase() : invoked === self;
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectInvocation()) {
+    main();
+}

package/dist/commands/daemonStart.js

@@ -0,0 +1,8 @@
+import { startDaemon } from '../daemon/server.js';
+export async function runDaemonStart(preferredPort = 4390) {
+    const { port, server } = await startDaemon(preferredPort);
+    return {
+        port,
+        close: () => new Promise((resolve) => server.close(() => resolve()))
+    };
+}

package/dist/commands/dashboardToggle.js

@@ -0,0 +1,17 @@
+import { readGlobalSettings, writeGlobalSettings } from '../daemon/settings.js';
+import { readDaemonHandle, clearDaemonHandle, isProcessAlive } from '../daemon/daemonHandle.js';
+export function runDashboardEnable() {
+    writeGlobalSettings({ ...readGlobalSettings(), dashboardEnabled: true });
+}
+export function runDashboardDisable() {
+    writeGlobalSettings({ ...readGlobalSettings(), dashboardEnabled: false });
+    const handle = readDaemonHandle();
+    if (handle && isProcessAlive(handle.pid)) {
+        process.kill(handle.pid, 'SIGTERM');
+        clearDaemonHandle();
+        return { stopped: true };
+    }
+    if (handle)
+        clearDaemonHandle();
+    return { stopped: false };
+}