@balacode/mental 0.2.0 → 0.2.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mental",
   "displayName": "Mental",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.2",
   "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,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +32,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 +49,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.0...HEAD
+[Unreleased]: https://github.com/afaraha8403/mental/compare/v0.2.2...HEAD
+[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. 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.
 
 From a clone, without npm:
 
@@ -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 `</br>`, title `🧠 Mental  ` (two trailing spaces so chat markdown does not join lines), indented `Kind: Verb` items, then `</br>` (see the skill).
 
 ## Identity (UUID, not the folder)
 

package/bin/commands/doctor.mjs

@@ -13,6 +13,7 @@ import { CMD } 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";
 
 function check(id, ok, message, level = "error") {
   return { id, ok, level, message };
@@ -126,6 +127,27 @@ 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 problems = checks.filter((c) => !c.ok && c.level === "error");

package/bin/commands/install.mjs

@@ -11,6 +11,7 @@ import { enableHooks } from "../lib/hooks.mjs";
 import { enableMcp } from "../lib/mcp.mjs";
 import { CMD } from "../lib/pkg.mjs";
 import { printResult, brandLine } from "../lib/output.mjs";
+import { purgeBalakitMental } from "../lib/legacy-balakit.mjs";
 
 export function cmdInstall(args, io = {}) {
   const stdout = io.stdout ?? process.stdout;
@@ -28,6 +29,10 @@ export function cmdInstall(args, io = {}) {
   const mcp = Boolean(args.flags?.mcp);
   const cwd = args.cwd ?? process.cwd();
 
+  const legacy = purgeBalakitMental({
+    home,
+    projectDir: cwd,
+  });
   const installed = installSkills({
     home,
     projectDir: project ? cwd : null,
@@ -61,6 +66,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 +80,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 +94,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,7 +22,7 @@ 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; removes leftover Balakit Mental skill/rule copies
   ${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)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balacode/mental",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.2",
   "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 `</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.
 
 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,45 @@ 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 literal `</br>` (open and close, each on its own line).
+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”
+</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
-🔍 heartbeat
+</br>
+🧠 Mental  
+  🔍 Read: Heartbeat
+</br>
 ```
 
 | 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.