@balacode/mental 0.2.2 → 0.2.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mental",
   "displayName": "Mental",
-  "version": "0.2.2",
+  "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.2",
+  "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,20 @@ 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
@@ -49,7 +63,8 @@ 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.2...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

package/README.md

@@ -76,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 also **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.
+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:
 
@@ -86,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
 ```
 
@@ -176,7 +176,7 @@ Mid-chat, not just start/finish: search decisions before changing an approach, r
 
 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>`, title `🧠 Mental  ` (two trailing spaces so chat markdown does not join lines), indented `Kind: Verb` items, then `</br>` (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)
 
@@ -231,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,11 +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 };
@@ -150,6 +151,19 @@ export function cmdDoctor(args, io = {}) {
     }
   }
 
+  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");
   const data = {
     checks,

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,9 +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;
@@ -28,6 +30,35 @@ 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,
@@ -37,7 +68,7 @@ export function cmdInstall(args, io = {}) {
     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" });
 
@@ -50,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,
   });

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 + PATH; removes leftover Balakit Mental skill/rule copies
+  ${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/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.2",
+  "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.2",
+  "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 `🧠 Mental  ` (two trailing spaces), then indented `Kind: Verb` lines, then `</br>`. Never one line. 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

@@ -91,7 +91,10 @@ 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 literal `</br>` (open and close, each on its own 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`.
@@ -102,21 +105,21 @@ not this repo, so links would 404. The CLI tool card already has the path.
 **Writes (copy this shape, including the two spaces after `Mental`):**
 
 ```text
-</br>
+────────
 🧠 Mental  
   🚦 Attention: Recorded  “Tom said ship”
   📓 Journal: Recorded  “Resolver landed”
   🎯 Decision: Decided  “Keep the JSON envelope”
-</br>
+────────
 ```
 
 **Read-only (heartbeat / search / show / list):**
 
 ```text
-</br>
+────────
 🧠 Mental  
   🔍 Read: Heartbeat
-</br>
+────────
 ```
 
 | Emoji | Kind | Item line |