@balacode/mental 0.2.0 → 0.2.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mental",
   "displayName": "Mental",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Never reconstruct where you left off. Mental keeps the resume, the decisions, and what's still in the air — so you and your agents continue as if the last session never ended.",
   "author": {
     "name": "Ali Farahat",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mental",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Never reconstruct where you left off. Mental keeps the resume, the decisions, and what's still in the air — so you and your agents continue as if the last session never ended.",
   "author": {
     "name": "Ali Farahat",

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-08-26
+
+### Added
+
+- `mental doctor` checks npm for a newer `@balacode/mental` (warn only; fail open). `mental install` from a published install upgrades the global CLI when npm is ahead, then re-runs so skills match. `MENTAL_SKIP_UPDATE_CHECK=1` skips the network. Heartbeat never checks.
+
+### Changed
+
+- Agent Mental receipt wraps with a separator line (`────────`) instead of `</br>`, which printed as literal tags in Claude Code and other agents.
+
+### Fixed
+
+- `mental install` / `npm i -g` overwrites an existing global `mental` bin (npm 11 EEXIST). Leftover `@mental/cli` links no longer block `@balacode/mental`.
+
+## [0.2.2] - 2026-08-26
+
+### Added
+
+- `mental install` finds leftover **Balakit** Mental skill/rule copies (fingerprint: `npx balakit doctor`, `mentalDataPolicy`, …) and deletes them before writing the standalone skill. Mental-only `<!-- BEGIN balakit -->` blocks are stripped. Journals and `./.mental` data are not deleted. `mental doctor` warns if any remain.
+
+## [0.2.1] - 2026-08-26
+
+### Changed
+
+- Agent Mental receipt wraps with `</br>`, uses a markdown hard break after `🧠 Mental`, and prints indented `Kind: Verb` lines so Cursor chat does not collapse the block onto one line.
+
 ## [0.2.0] - 2026-08-26
 
 ### Added
@@ -20,7 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- README now shows the logo, explains the [Agent Plugins 1.0.0](https://agent-plugins.org/specification) packaging, and includes copy-paste install prompts for Cursor, Claude Code, VS Code, and GitHub Copilot.
+- README now shows the logo, npm (`@balacode/mental`), [Agent Plugins 1.0.0](https://agent-plugins.org/specification) packaging, and copy-paste install prompts for Cursor, Claude Code, VS Code, and GitHub Copilot.
 - npm package is `@balacode/mental` (unscoped `mental` is taken). The CLI bin stays `mental`.
 
 ## [0.1.0] - 2026-08-26
@@ -37,6 +63,9 @@ First public release of the Mental CLI.
 - `install --mcp` registers `serve`; `decide` updates by title so an open decision can close.
 - Install, doctor, uninstall; hooks stay off by default.
 
-[Unreleased]: https://github.com/afaraha8403/mental/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/afaraha8403/mental/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/afaraha8403/mental/releases/tag/v0.2.3
+[0.2.2]: https://github.com/afaraha8403/mental/releases/tag/v0.2.2
+[0.2.1]: https://github.com/afaraha8403/mental/releases/tag/v0.2.1
 [0.2.0]: https://github.com/afaraha8403/mental/releases/tag/v0.2.0
 [0.1.0]: https://github.com/afaraha8403/mental/releases/tag/v0.1.0

package/README.md

@@ -4,15 +4,18 @@
 
 # Mental
 
+[![npm](https://img.shields.io/npm/v/@balacode/mental.svg)](https://www.npmjs.com/package/@balacode/mental)
+
 Local-first continuity layer for you and your coding agents.
 
 Git records **what** changed. Mental records the small amount git cannot explain: where you left off, why a decision was made, what is still in the air after a hop, and the next exact action. **OKF markdown is the source of truth.** SQLite is a derived cache. Agents call `mental … --json` — they do not grep YAML.
 
+- **npm:** [@balacode/mental](https://www.npmjs.com/package/@balacode/mental) — install this; the CLI binary is `mental`
 - **Repo:** https://github.com/afaraha8403/mental
 - **Spec:** [PLAN.md](./PLAN.md)
 - **Plugin standard:** [Agent Plugins 1.0.0](https://agent-plugins.org/specification)
 
-Mental is **not** a Balakit plugin. Default data lives in `~/.mental` (UUID bindings). Project `./.mental` only after `mental local`.
+Mental is **not** a Balakit plugin. Default data lives in `~/.mental` (UUID bindings). Project `./.mental` only after `mental local`. The unscoped npm package [`mental`](https://www.npmjs.com/package/mental) is a different project.
 
 ## Install
 
@@ -73,7 +76,7 @@ npm i -g @balacode/mental
 mental install
 ```
 
-Last install wins. That puts `mental` on PATH (typically `~/.local/bin/mental`), copies the skill + tiny always-on rule into `~/.claude`, `~/.cursor`, `~/.agents`, and `~/.config/opencode`, and creates a `~/.mental` skeleton. It does **not** turn on hooks or MCP.
+Last install wins: an existing global `mental` bin is overwritten (npm 11 no longer fails with EEXIST). That puts `mental` on PATH (typically `~/.local/bin/mental`), copies the skill + tiny always-on rule into `~/.claude`, `~/.cursor`, `~/.agents`, and `~/.config/opencode`, and creates a `~/.mental` skeleton. From a published install it also **upgrades** the CLI when npm has a newer version, then re-runs so skills match. It **removes leftover Balakit Mental skill/rule copies** (the old `npx balakit doctor` pointer) so they cannot fight the new rule. It does **not** turn on hooks or MCP, and it does not delete journals. A git checkout installs that tree and does not clobber it with the registry.
 
 From a clone, without npm:
 
@@ -83,7 +86,7 @@ node bin/cli.mjs install --json
 ```
 
 ```bash
-mental doctor          # PATH, bindings, ignore, skills
+mental doctor          # PATH, bindings, ignore, skills, npm update
 mental doctor --fix-ignore   # add .mental/ and .mental-id to your global git excludes
 ```
 
@@ -171,9 +174,9 @@ mental status --json
 
 Mid-chat, not just start/finish: search decisions before changing an approach, record attention the moment residue surfaces, and re-pulse `mental heartbeat --json` whenever other agents may have written — it is cheap and derives git live.
 
-Do not grep `.mental` or parse YAML. If `mental` is missing, continue the coding task (fail open) and mention install.
+Do not grep `.mental` or parse YAML. If `mental` is missing, try `npx @balacode/mental …`. If that fails, continue the coding task (fail open) and mention `npm i -g @balacode/mental` then `mental install`.
 
-Turns that invoked `mental` end with `<br>`, then the title `🧠 Mental`, then one type line per write/read (see the skill).
+Turns that invoked `mental` end with a separator line (`────────`), title `🧠 Mental  ` (two trailing spaces so chat markdown does not join lines), indented `Kind: Verb` items, then `────────` (see the skill). Do not emit `</br>` — it prints as literal tags.
 
 ## Identity (UUID, not the folder)
 
@@ -228,11 +231,11 @@ mental uninstall --delete-data --confirm DELETE   # wipe ~/.mental too
 | `mental remap [--to id]` | List or retarget this clone’s UUID |
 | `mental split [--copy]` | New UUID for this clone |
 | `mental link --to <id>` | Point this clone at an existing UUID |
-| `mental install` | User skill + rule; `~/.mental` skeleton; CLI on PATH; `--mcp` registers MCP config |
+| `mental install` | User skill + rule; `~/.mental` skeleton; CLI on PATH (overwrites existing bin; upgrades if npm is newer); `--mcp` registers MCP config |
 | `mental uninstall` | Remove installed skill/rule/hooks/MCP entries |
 | `mental hooks on\|off` | Optional session hooks |
 | `mental serve` | Optional MCP stdio (full command surface) |
-| `mental doctor` | PATH, bindings, ignore, skills. `--fix-ignore` adds `.mental/` to global excludes |
+| `mental doctor` | PATH, bindings, ignore, skills, npm update. `--fix-ignore` adds `.mental/` to global excludes |
 
 Global flags: `--json`, `--dir <path>` (same as `MENTAL_DIR`).
 

package/bin/commands/doctor.mjs

@@ -9,10 +9,12 @@ import { loadBindings } from "../lib/bindings.mjs";
 import { checkMentalIgnored, ensureMentalExcluded, gitAvailable } from "../lib/ignore.mjs";
 import { skillsPresent } from "../lib/install-skills.mjs";
 import { printResult, brandMark } from "../lib/output.mjs";
-import { CMD } from "../lib/pkg.mjs";
+import { CMD, NAME, VERSION } from "../lib/pkg.mjs";
 import { isOptedInLocal } from "../lib/import-legacy.mjs";
 import { findGitRoot } from "../lib/git.mjs";
 import { indexPath } from "../lib/index.mjs";
+import { leftoverBalakitMentalCount, findBalakitMental } from "../lib/legacy-balakit.mjs";
+import { checkForUpdate, cmpSemver, updateHint } from "../lib/update.mjs";
 
 function check(id, ok, message, level = "error") {
   return { id, ok, level, message };
@@ -126,6 +128,40 @@ export function cmdDoctor(args, io = {}) {
         ),
       );
     }
+
+    const leftoverWiring = leftoverBalakitMentalCount({ home, projectDir: gitRoot || cwd });
+    if (leftoverWiring > 0) {
+      const found = findBalakitMental({ home, projectDir: gitRoot || cwd });
+      const sample = [
+        ...found.skills,
+        ...found.rules,
+        ...found.plugins,
+        ...found.blocks.map((b) => b.file),
+      ]
+        .slice(0, 4)
+        .join(", ");
+      checks.push(
+        check(
+          "legacy-balakit",
+          false,
+          `Balakit Mental skill/rule still present (${sample}). Run \`${CMD} install\` to remove it.`,
+          "warn",
+        ),
+      );
+    }
+  }
+
+  const upd = checkForUpdate({ env });
+  if (!upd.skipped && upd.latest) {
+    const behind = cmpSemver(upd.latest, VERSION) > 0;
+    checks.push(
+      check(
+        "update",
+        !behind,
+        behind ? updateHint(VERSION, upd.latest, NAME) : `CLI ${VERSION} (npm ${upd.latest})`,
+        behind ? "warn" : "info",
+      ),
+    );
   }
 
   const problems = checks.filter((c) => !c.ok && c.level === "error");

package/bin/commands/install.mjs

@@ -2,6 +2,7 @@
  * `mental install` — copy skill + tiny rule to user agent dirs; ~/.mental skeleton.
  * `--hooks` and `--mcp` are optional and default off.
  */
+import { spawnSync } from "node:child_process";
 import { resolveBundle } from "../lib/resolve.mjs";
 import { userMentalDir } from "../lib/bindings.mjs";
 import { ensureSkeleton } from "../lib/okf.mjs";
@@ -9,8 +10,10 @@ import { installSkills } from "../lib/install-skills.mjs";
 import { installGlobalCli } from "../lib/install-cli.mjs";
 import { enableHooks } from "../lib/hooks.mjs";
 import { enableMcp } from "../lib/mcp.mjs";
-import { CMD } from "../lib/pkg.mjs";
+import { CMD, NAME, VERSION } from "../lib/pkg.mjs";
 import { printResult, brandLine } from "../lib/output.mjs";
+import { purgeBalakitMental } from "../lib/legacy-balakit.mjs";
+import { checkForUpdate, cmpSemver, isDevCheckout } from "../lib/update.mjs";
 
 export function cmdInstall(args, io = {}) {
   const stdout = io.stdout ?? process.stdout;
@@ -27,12 +30,45 @@ export function cmdInstall(args, io = {}) {
   const hooks = Boolean(args.flags?.hooks);
   const mcp = Boolean(args.flags?.mcp);
   const cwd = args.cwd ?? process.cwd();
+  const env = args.env ?? process.env;
+  const stderr = io.stderr ?? process.stderr;
 
+  if (env.MENTAL_SKIP_SELF_UPDATE !== "1" && !isDevCheckout()) {
+    const upd = checkForUpdate({ env });
+    if (upd.latest && cmpSemver(upd.latest, VERSION) > 0) {
+      const bumped = installGlobalCli({ home, env, spec: NAME });
+      const newBin = bumped.bin;
+      if (bumped.npm && newBin) {
+        if (!args.json) {
+          stdout.write(`${brandLine(`updating CLI ${VERSION} → ${upd.latest}`)}\n`);
+        }
+        const childArgs = ["install"];
+        if (args.json) childArgs.push("--json");
+        if (project) childArgs.push("--project");
+        if (hooks) childArgs.push("--hooks");
+        if (mcp) childArgs.push("--mcp");
+        if (args.dir) childArgs.push("--dir", args.dir);
+        const child = spawnSync(newBin, childArgs, {
+          encoding: "utf8",
+          cwd,
+          env: { ...env, MENTAL_SKIP_SELF_UPDATE: "1", MENTAL_SKIP_UPDATE_CHECK: "1" },
+        });
+        if (child.stdout) stdout.write(child.stdout);
+        if (child.stderr) stderr.write(child.stderr);
+        return child.status ?? 1;
+      }
+    }
+  }
+
+  const legacy = purgeBalakitMental({
+    home,
+    projectDir: cwd,
+  });
   const installed = installSkills({
     home,
     projectDir: project ? cwd : null,
   });
-  const cli = installGlobalCli({ home, env: args.env ?? process.env });
+  const cli = installGlobalCli({ home, env });
   const personal = userMentalDir(home);
   ensureSkeleton(personal, { name: "personal" });
 
@@ -45,7 +81,7 @@ export function cmdInstall(args, io = {}) {
   const resolved = resolveBundle({
     cwd,
     home,
-    env: args.env ?? process.env,
+    env,
     dir: args.dir ?? null,
     write: true,
   });
@@ -61,6 +97,8 @@ export function cmdInstall(args, io = {}) {
     mcp: mcpResult,
     where: resolved.ok ? resolved.data : null,
     imported: imported || null,
+    legacyRemoved: legacy.removed,
+    legacyLeftover: legacy.leftover,
   };
   const importLine =
     imported?.copied?.length
@@ -73,6 +111,13 @@ export function cmdInstall(args, io = {}) {
       ? `\nMCP: ${CMD} serve registered in ${mcpResult.written.join(", ")}`
       : `\nMCP: config write failed (${mcpResult?.error?.message ?? "unknown"}) — add \`${CMD} serve\` manually`
     : "";
+  const legacyLine = legacy.removed.length
+    ? `\nremoved ${legacy.removed.length} Balakit Mental leftover(s)`
+    : "";
+  const leftoverLine =
+    legacy.leftover.length
+      ? `\nstill mixed Balakit block(s) (Mental text inside a kit block): ${legacy.leftover.join(", ")}`
+      : "";
   printResult(
     stdout,
     args.json,
@@ -80,7 +125,7 @@ export function cmdInstall(args, io = {}) {
     data,
     undefined,
     () =>
-      `${brandLine(`installed skill + rule (${installed.written.length} paths)`)}\n~/.mental skeleton: ${personal}${cliLine}${hookLine}${mcpLine}${importLine}`,
+      `${brandLine(`installed skill + rule (${installed.written.length} paths)`)}\n~/.mental skeleton: ${personal}${cliLine}${hookLine}${mcpLine}${importLine}${legacyLine}${leftoverLine}`,
   );
   return 0;
 }

package/bin/lib/args.mjs

@@ -22,11 +22,11 @@ Usage:
   ${CMD} remap                 List UUID bindings, or --to <id> / --from <id> for this clone
   ${CMD} split                 New UUID for this clone (--copy keeps OKF files)
   ${CMD} link                  Point this clone at --to <id>
-  ${CMD} install               Skill + rule + put ${CMD} on PATH (overrides previous)
+  ${CMD} install               Skill + rule + PATH; overwrites existing bin; upgrades if npm is newer
   ${CMD} uninstall             Remove installed skill/rule/hooks (OKF stays unless --delete-data DELETE)
   ${CMD} hooks on|off          Optional session-start hooks (default off)
   ${CMD} serve                 Optional MCP stdio (heartbeat/where/status/search/list/show/journal/attention/decide/note)
-  ${CMD} doctor                PATH, bindings, ignore, skill, index
+  ${CMD} doctor                PATH, bindings, ignore, skill, index, update
   ${CMD} reindex               Rebuild derived sqlite index from OKF files
 
 TTY: no args prints a one-shot heartbeat and exits. Named commands are one-shot.

package/bin/lib/install-cli.mjs

@@ -41,7 +41,7 @@ function replaceWithSymlink(dest, target) {
 }
 
 /**
- * @param {{ home: string, env?: NodeJS.ProcessEnv }} opts
+ * @param {{ home: string, env?: NodeJS.ProcessEnv, spec?: string }} opts
  * @returns {{
  *   ok: boolean,
  *   bin: string | null,
@@ -50,13 +50,30 @@ function replaceWithSymlink(dest, target) {
  *   message: string,
  * }}
  */
-export function installGlobalCli({ home, env = process.env }) {
+export function installGlobalCli({ home, env = process.env, spec = PKG_ROOT }) {
+  const prefix = npmGlobalPrefix(env);
+  const npmBin = prefix ? npmGlobalBin(prefix) : null;
+  // npm 11 refuses to replace an existing global bin (EEXIST). Last install
+  // wins: drop our previous `mental` link (often leftover @mental/cli).
+  if (npmBin) {
+    try {
+      unlinkSync(npmBin);
+    } catch {
+      // missing
+    }
+  }
   const npm = runNpm(
-    ["install", "-g", "--no-fund", "--no-audit", "--no-package-lock", PKG_ROOT],
+    [
+      "install",
+      "-g",
+      "--force",
+      "--no-fund",
+      "--no-audit",
+      "--no-package-lock",
+      spec,
+    ],
     env,
   );
-  const prefix = npmGlobalPrefix(env);
-  const npmBin = prefix ? npmGlobalBin(prefix) : null;
   const pathBin = join(home, ".local", "bin", CMD);
   const fallback = join(PKG_ROOT, "bin", "cli.mjs");
   const target =

package/bin/lib/legacy-balakit.mjs

@@ -0,0 +1,220 @@
+/**
+ * Find and remove Balakit-era Mental *tooling* (skill + always-on rule).
+ * Never deletes OKF data (`~/.mental` or `./.mental`).
+ *
+ * Balakit installed the personal Mental rule user-wide (`~/.cursor/rules/mental.mdc`,
+ * managed `BEGIN balakit` blocks) and the skill via skills.sh (`-g`) into agent
+ * skill dirs. Those copies still tell agents to `npx balakit doctor` and fight
+ * the standalone CLI.
+ */
+import { existsSync, lstatSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const BALAKIT_BEGIN_RE = /<!-- BEGIN balakit\b[^>]*-->/;
+const BALAKIT_BLOCK_RE =
+  /<!-- BEGIN balakit\b[^>]*-->\r?\n[\s\S]*?<!-- END balakit\b[^>]*-->/g;
+
+/**
+ * Distinctive strings from the Balakit `mental` rule/skill (removed from the
+ * kit in 02bf1c2). Our current skill/rule never contain these.
+ * @param {string} text
+ */
+export function isBalakitMentalText(text) {
+  if (!text) return false;
+  return (
+    /npx balakit doctor/i.test(text) ||
+    /mentalDataPolicy/.test(text) ||
+    /\.balakit\/installed\.json/.test(text) ||
+    /Respect the installed Mental data policy/.test(text) ||
+    /The `\.mental\/` Project Continuity Layer/.test(text) ||
+    /plugins\/balakit-mental/.test(text)
+  );
+}
+
+/** User-global skill dirs skills.sh used for a global `mental` install. */
+export function userSkillCandidates(home) {
+  return [
+    join(home, ".claude", "skills", "mental"),
+    join(home, ".cursor", "skills", "mental"),
+    join(home, ".agents", "skills", "mental"),
+    join(home, ".codex", "skills", "mental"),
+    join(home, ".config", "opencode", "skills", "mental"),
+    join(home, ".gemini", "skills", "mental"),
+    join(home, ".codeium", "windsurf", "skills", "mental"),
+    join(home, ".kilocode", "skills", "mental"),
+    join(home, ".continue", "skills", "mental"),
+    join(home, ".pi", "agent", "skills", "mental"),
+    join(home, ".amp", "skills", "mental"),
+    join(home, ".roo", "skills", "mental"),
+    join(home, ".windsurf", "skills", "mental"),
+  ];
+}
+
+function projectSkillCandidates(root) {
+  if (!root) return [];
+  return [
+    join(root, ".claude", "skills", "mental"),
+    join(root, ".cursor", "skills", "mental"),
+    join(root, ".agents", "skills", "mental"),
+    join(root, ".github", "skills", "mental"),
+    join(root, "plugins", "balakit-mental"),
+  ];
+}
+
+function userRuleCandidates(home) {
+  return [join(home, ".cursor", "rules", "mental.mdc")];
+}
+
+function projectRuleCandidates(root) {
+  if (!root) return [];
+  return [
+    join(root, ".cursor", "rules", "mental.mdc"),
+    join(root, ".cursor", "rules", "balakit-mental.mdc"),
+  ];
+}
+
+function managedDocCandidates(home, projectDir) {
+  const files = [
+    join(home, ".claude", "CLAUDE.md"),
+    join(home, ".codex", "AGENTS.md"),
+    join(home, ".agents", "AGENTS.md"),
+  ];
+  if (projectDir) {
+    files.push(join(projectDir, "AGENTS.md"), join(projectDir, "CLAUDE.md"));
+  }
+  return files;
+}
+
+function pluginCandidates(home) {
+  return [join(home, ".cursor", "plugins", "local", "balakit-mental")];
+}
+
+function skillMarkdown(dir) {
+  try {
+    return readFileSync(join(dir, "SKILL.md"), "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function readIfFile(file) {
+  try {
+    const st = lstatSync(file);
+    if (!st.isFile()) return "";
+    return readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function isDir(p) {
+  try {
+    return lstatSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A Balakit managed block that is only the old Mental rule (safe to delete).
+ * Mixed kit blocks (base/testing + mental) are reported, not stripped.
+ * @param {string} block
+ */
+export function isMentalOnlyBalakitBlock(block) {
+  if (!isBalakitMentalText(block)) return false;
+  const headings = block.match(/^# .+$/gm) || [];
+  return headings.length <= 1;
+}
+
+/**
+ * @param {{ home: string, projectDir?: string | null }} opts
+ * @returns {{
+ *   skills: string[],
+ *   rules: string[],
+ *   plugins: string[],
+ *   blocks: Array<{ file: string, strip: boolean }>,
+ * }}
+ */
+export function findBalakitMental({ home, projectDir = null }) {
+  /** @type {string[]} */
+  const skills = [];
+  /** @type {string[]} */
+  const rules = [];
+  /** @type {string[]} */
+  const plugins = [];
+  /** @type {Array<{ file: string, strip: boolean }>} */
+  const blocks = [];
+
+  for (const dir of [...userSkillCandidates(home), ...projectSkillCandidates(projectDir)]) {
+    if (isDir(dir) && isBalakitMentalText(skillMarkdown(dir))) skills.push(dir);
+  }
+  for (const file of [...userRuleCandidates(home), ...projectRuleCandidates(projectDir)]) {
+    if (isBalakitMentalText(readIfFile(file))) rules.push(file);
+  }
+  for (const dir of pluginCandidates(home)) {
+    if (existsSync(dir)) plugins.push(dir);
+  }
+  for (const file of managedDocCandidates(home, projectDir)) {
+    const cur = readIfFile(file);
+    if (!BALAKIT_BEGIN_RE.test(cur) || !isBalakitMentalText(cur)) continue;
+    const m = cur.match(BALAKIT_BLOCK_RE);
+    const block = m ? m.join("\n") : cur;
+    blocks.push({ file, strip: isMentalOnlyBalakitBlock(block) });
+  }
+  return { skills, rules, plugins, blocks };
+}
+
+function rmPath(p) {
+  rmSync(p, { recursive: true, force: true });
+}
+
+/**
+ * Drop Mental-only `BEGIN balakit` blocks. Leave mixed kit blocks intact.
+ * @param {string} file
+ */
+export function stripMentalOnlyBalakitBlock(file) {
+  const cur = readIfFile(file);
+  if (!cur) return false;
+  const next = cur.replace(BALAKIT_BLOCK_RE, (block) =>
+    isMentalOnlyBalakitBlock(block) ? "" : block,
+  );
+  if (next === cur) return false;
+  writeFileSync(file, next.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, ""));
+  return true;
+}
+
+/**
+ * Remove Balakit Mental skill/rule copies. Call *before* writing the new ones.
+ * @param {{ home: string, projectDir?: string | null }} opts
+ */
+export function purgeBalakitMental({ home, projectDir = null }) {
+  const found = findBalakitMental({ home, projectDir });
+  /** @type {string[]} */
+  const removed = [];
+  /** @type {string[]} */
+  const leftover = [];
+
+  for (const p of [...found.skills, ...found.rules, ...found.plugins]) {
+    try {
+      rmPath(p);
+      removed.push(p);
+    } catch {
+      leftover.push(p);
+    }
+  }
+  for (const b of found.blocks) {
+    if (b.strip) {
+      if (stripMentalOnlyBalakitBlock(b.file)) removed.push(b.file);
+      else leftover.push(b.file);
+    } else {
+      leftover.push(b.file);
+    }
+  }
+  return { removed, leftover, found };
+}
+
+/** @param {{ home: string, projectDir?: string | null }} opts */
+export function leftoverBalakitMentalCount(opts) {
+  const f = findBalakitMental(opts);
+  return f.skills.length + f.rules.length + f.plugins.length + f.blocks.length;
+}

package/bin/lib/update.mjs

@@ -0,0 +1,69 @@
+/**
+ * Fail-open npm update check. Heartbeat does not call this (must stay cheap).
+ * `MENTAL_SKIP_UPDATE_CHECK=1` skips. `MENTAL_NPM_LATEST` pins a version (tests).
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { NAME, PKG_ROOT } from "./pkg.mjs";
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1}
+ */
+export function cmpSemver(a, b) {
+  const pa = String(a).split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => Number.parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return 1;
+    if (pa[i] < pb[i]) return -1;
+  }
+  return 0;
+}
+
+/** True when running from a git checkout (not the published tarball). */
+export function isDevCheckout() {
+  return existsSync(join(PKG_ROOT, ".git"));
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function skipUpdateCheck(env = process.env) {
+  const v = env.MENTAL_SKIP_UPDATE_CHECK;
+  return v === "1" || v === "true" || v === "yes";
+}
+
+/**
+ * @param {{ env?: NodeJS.ProcessEnv, name?: string, timeoutMs?: number }} [opts]
+ * @returns {{ skipped: boolean, latest: string | null }}
+ */
+export function checkForUpdate(opts = {}) {
+  const env = opts.env ?? process.env;
+  if (skipUpdateCheck(env)) return { skipped: true, latest: null };
+  const pinned = env.MENTAL_NPM_LATEST;
+  if (typeof pinned === "string" && /^\d+\.\d+\.\d+/.test(pinned.trim())) {
+    return { skipped: false, latest: pinned.trim().split(/\s+/)[0] };
+  }
+  const name = opts.name ?? NAME;
+  const timeout = opts.timeoutMs ?? 5000;
+  const r = spawnSync("npm", ["view", name, "version"], {
+    encoding: "utf8",
+    env,
+    timeout,
+  });
+  if (r.status !== 0) return { skipped: false, latest: null };
+  const v = (r.stdout || "").trim().split(/\s+/)[0];
+  if (!/^\d+\.\d+\.\d+/.test(v)) return { skipped: false, latest: null };
+  return { skipped: false, latest: v };
+}
+
+/**
+ * @param {string} current
+ * @param {string} latest
+ * @param {string} [pkg]
+ */
+export function updateHint(current, latest, pkg = NAME) {
+  return `CLI ${current}; npm ${latest}. Run \`mental install\` or \`npm i -g --force ${pkg}\`.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balacode/mental",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Never reconstruct where you left off. Mental keeps the resume, the decisions, and what's still in the air.",
   "license": "MIT",
   "type": "module",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "mental",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Never reconstruct where you left off. Mental keeps the resume, the decisions, and what's still in the air — so you and your agents continue as if the last session never ended.",
   "author": {
     "name": "Ali Farahat",

package/rules/mental.mdc

@@ -13,6 +13,6 @@ If `mental` is not on PATH, try `npx @balacode/mental …`. If that fails, conti
 
 Never commit Mental data. Never write secrets. Never edit gitignore; tell the user to run `mental doctor`.
 
-If you invoked `mental` this turn, end the user-visible reply with `<br>`, then the title `🧠 Mental`, then type lines under it (example in the Mental skill). Not a code fence.
+If you invoked `mental` this turn, end the user-visible reply with a separator line (`────────`), then `🧠 Mental  ` (two trailing spaces), then indented `Kind: Verb` lines, then `────────`. Never one line. Not `</br>`. Example in the Mental skill. Not a code fence.
 
 On a pasted transcript or a plan-progress question ("where in the plan / what's left?"), use the Mental skill. Cheap reload is `mental heartbeat --json`, not a notes dump.

package/skills/mental/SKILL.md

@@ -87,39 +87,48 @@ If you invoked `mental` this turn, end the **user-visible** reply with this bloc
 Last thing in the message. Not a code fence (so emojis render).
 Skip the whole block if you did not run `mental`.
 
-Separator is a literal `<br>` on its own line (not dashes, not a blank line).
-Next line is the title `🧠 Mental`. Then one item line per thing that happened,
-type-emoji first. At most four item lines; if more, keep the writes and end
-with `+N more`.
+Cursor markdown joins adjacent lines into one paragraph. A lone `<br>`
+becomes a break *inside* that paragraph, so `🧠 Mental` and the item
+collapse to one line. Do **not** put the title and items on the same line.
+
+Wrap with a separator line (`────────`) on its own line above and below.
+That is a visible rule even as plain text. Do not emit `<br>` or `</br>` —
+those print as literal tags in Claude Code and other agents. Do not use
+markdown `---` here: it can become a heading underline under the last item.
+Title line is `🧠 Mental` plus **two trailing spaces** (markdown hard break).
+Each item is indented two spaces: `emoji Kind: Verb  “title”`.
+At most four item lines; if more, keep the writes and end with `+N more`.
 
 Titles only — no `file://` or markdown links. Mental files live in `~/.mental`,
 not this repo, so links would 404. The CLI tool card already has the path.
 
-**Writes (copy this shape):**
+**Writes (copy this shape, including the two spaces after `Mental`):**
 
 ```text
-<br>
-🧠 Mental
-📓 journaled “Resolver landed”
-🚦 recorded attention “Tom said ship”
-🎯 decided “Keep the JSON envelope”
+────────
+🧠 Mental  
+  🚦 Attention: Recorded  “Tom said ship”
+  📓 Journal: Recorded  “Resolver landed”
+  🎯 Decision: Decided  “Keep the JSON envelope”
+────────
 ```
 
 **Read-only (heartbeat / search / show / list):**
 
 ```text
-<br>
-🧠 Mental
-🔍 heartbeat
+────────
+🧠 Mental  
+  🔍 Read: Heartbeat
+────────
 ```
 
 | Emoji | Kind | Item line |
 | --- | --- | --- |
-| 📓 | Journal | `📓 journaled “<title>”` |
-| 🚦 | Attention | `🚦 recorded attention “<title>”` or `🚦 resolved attention “<title>”` |
-| 🎯 | Decision | `🎯 decided “<title>”` or `🎯 opened decision “<title>”` |
-| 📝 | Note | `📝 noted “<title>”` |
-| 🔍 | Read | `🔍 heartbeat` / `🔍 searched` / `🔍 showed` / `🔍 listed` |
+| 📓 | Journal | `  📓 Journal: Recorded  “<title>”` |
+| 🚦 | Attention | `  🚦 Attention: Recorded  “<title>”` or `  🚦 Attention: Resolved  “<title>”` |
+| 🎯 | Decision | `  🎯 Decision: Decided  “<title>”` or `  🎯 Decision: Opened  “<title>”` |
+| 📝 | Note | `  📝 Note: Recorded  “<title>”` |
+| 🔍 | Read | `  🔍 Read: Heartbeat` / `Searched` / `Showed` / `Listed` |
 
 Mix writes and a read in one block if both happened. Never invent Mental activity.