@balacode/mental 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "mental",
+  "owner": {
+    "name": "Ali Farahat",
+    "url": "https://github.com/afaraha8403"
+  },
+  "metadata": {
+    "description": "Never reconstruct where you left off."
+  },
+  "plugins": [
+    {
+      "name": "mental",
+      "source": "./",
+      "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."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "mental",
+  "displayName": "Mental",
+  "version": "0.2.0",
+  "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",
+    "url": "https://github.com/afaraha8403"
+  },
+  "homepage": "https://github.com/afaraha8403/mental#readme",
+  "repository": "https://github.com/afaraha8403/mental",
+  "license": "MIT",
+  "keywords": [
+    "continuity",
+    "journal",
+    "decisions",
+    "okf",
+    "skills",
+    "mcp"
+  ],
+  "mcpServers": "./.mcp.json"
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "mental",
+  "version": "0.2.0",
+  "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",
+    "url": "https://github.com/afaraha8403"
+  },
+  "homepage": "https://github.com/afaraha8403/mental#readme",
+  "repository": "https://github.com/afaraha8403/mental",
+  "license": "MIT",
+  "keywords": [
+    "continuity",
+    "journal",
+    "decisions",
+    "okf",
+    "skills",
+    "mcp"
+  ],
+  "logo": "assets/logo.svg"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "mental": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/cli.mjs", "serve"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-26
+
+### Added
+
+- Ranked FTS search (`bm25`) with snippets, and SQL-side `--type` / `--status` / `--tag` / `--kind` filters so a typed query cannot be crowded out by untyped matches.
+- `mental list` includes each concept's `description`; `--kind` filters attention on list and search.
+- `mental show` returns `backlinks` from the derived link index (file-scan fallback).
+- MCP `list` tool; search accepts the same typed filters as the CLI; tool results are compact JSON.
+- Agent **Mental receipt** at the end of a turn that used the CLI: `<br>`, title `🧠 Mental`, then type lines (📓 journal, 🚦 attention, 🎯 decision, 📝 note, 🔍 read). Example in the skill; the always-on rule points at it. TTY writes use the same type emojis. `--json` stays ASCII (`MENTAL_ASCII=1` strips emoji).
+- `mental install` copies the skill to `~/.config/opencode/skills/mental` (OpenCode).
+
+### 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.
+- npm package is `@balacode/mental` (unscoped `mental` is taken). The CLI bin stays `mental`.
+
+## [0.1.0] - 2026-08-26
+
+First public release of the Mental CLI.
+
+### Added
+
+- Standalone Mental CLI: on a TTY, no args prints a one-shot heartbeat and exits; named commands are one-shot; agents use `--json`.
+- UUID identity in `~/.mental/bindings.json`, with `remap` / `split` / `link` and `local --import` / `--move`.
+- Attention residue (`mental attention`) and `journal --against` so heartbeat carries what is still in the air.
+- Agent Plugins 1.0.0 package: root `plugin.json`, skill at `skills/mental/`, MCP at `mcp.json` (stdio `./bin/cli.mjs serve`).
+- Cursor / Claude Code shims: `.cursor-plugin/plugin.json` (SVG logo) and `.claude-plugin/plugin.json` (`displayName: Mental`).
+- `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
+[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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Farahat
+
+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,277 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="Mental" width="128" height="128">
+</p>
+
+# 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.
+
+- **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`.
+
+## Install
+
+### Paste this into your agent
+
+Copy the block into Cursor, Claude Code, Copilot, Codex, or any other coding agent:
+
+```text
+Install Mental from https://github.com/afaraha8403/mental.
+
+Mental is a local-first continuity layer. Git records what changed; Mental records where we left off, why a decision was made, and what is still in the air.
+
+The repo is an Agent Plugins 1.0.0 package (https://agent-plugins.org/specification): plugin.json at the repo root, skill at skills/mental/, MCP at mcp.json.
+
+Use this client's native plugin install if you have one, then put the CLI on PATH and finish setup:
+
+  npm i -g @balacode/mental
+  mental install
+  mental doctor
+
+Do not enable hooks unless I ask. Optional MCP is `mental install --mcp`. After doctor, tell me what it reports.
+```
+
+### Client one-liners
+
+**Cursor** — paste in Agent chat:
+
+```text
+/add-plugin https://github.com/afaraha8403/mental
+```
+
+**Claude Code:**
+
+```text
+/plugin marketplace add afaraha8403/mental
+/plugin install mental@mental
+```
+
+**VS Code** — Command Palette → **Chat: Install Plugin From Source**, then:
+
+```text
+https://github.com/afaraha8403/mental
+```
+
+**GitHub Copilot CLI:**
+
+```bash
+copilot plugin marketplace add afaraha8403/mental
+copilot plugin install mental@mental
+```
+
+Plugin install loads the skill and MCP. Still run `mental install` so the CLI, skill, and tiny always-on rule land on this machine.
+
+### CLI
+
+```bash
+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.
+
+From a clone, without npm:
+
+```bash
+cd /path/to/mental
+node bin/cli.mjs install --json
+```
+
+```bash
+mental doctor          # PATH, bindings, ignore, skills
+mental doctor --fix-ignore   # add .mental/ and .mental-id to your global git excludes
+```
+
+## Agent Plugins 1.0.0
+
+Mental is packaged as a portable [Agent Plugins](https://agent-plugins.org/) 1.0.0 plugin — the vendor-neutral format maintained by Amazon, Cursor, Microsoft, OpenAI, and Vercel. Compatible clients (Cursor, VS Code, GitHub Copilot, ChatGPT/Codex, Kiro) load the same directory: no per-client rewrite of the skill or MCP server.
+
+The spec's interoperability floor is small and closed:
+
+| Piece | Where | Role |
+| --- | --- | --- |
+| `plugin.json` | repo root | Manifest (`$schema` + `name`). The portable schema has no icon field. |
+| `skills/mental/` | Agent Skills | Procedure: when to journal, CLI contract, privacy. |
+| `mcp.json` | repo root | stdio MCP → `./bin/cli.mjs serve` (`cwd` `${PLUGIN_ROOT}`) |
+
+Cursor extras live in `.cursor-plugin/plugin.json` (logo). Claude Code extras live in `.claude-plugin/plugin.json` (`displayName: Mental`) and `.claude-plugin/marketplace.json`. Rules and hooks are **not** portable v1 components — they still come from `mental install` / `mental hooks on`.
+
+Plugin install loads the skill and MCP. The CLI remains the contract: humans type `mental`; agents call `mental … --json`.
+
+## How you use it (human)
+
+On a TTY, in any git repo:
+
+```bash
+mental
+```
+
+Prints a one-shot **heartbeat** and exits — resume, last outcome, git, residue in the air, unsettled decisions. Not a menu. UUID / root / index live on `where` and `doctor`.
+
+Daily loop:
+
+1. `mental` — where did I leave off?
+2. Do the work.
+3. At a real task boundary (not every chat turn):
+
+```bash
+mental journal --title "What landed" --body "Evidence git cannot see." --resume "Exact next action — open loops: none" --against PLAN.md
+```
+
+Lookup:
+
+```bash
+mental status          # git + resume + residue + open decisions + notes (writes status/current.md cache)
+mental heartbeat --json  # same pulse as `mental` on a TTY; agents use this
+mental where           # root, uuid, mode — read-only, does not create identity
+mental search overlay
+mental list --type Decision --kind direction
+mental show notes/some-fact.md
+```
+
+Write a decision only when it constrains the future. Write attention for residue that is not a choice (Tom said X, a concern, later):
+
+```bash
+mental decide --title "Heartbeat only, no standing TUI" --status decided
+mental attention --title "Tom said ship the pointer not the dump" --kind direction --from Tom
+mental attention --title "Tom said ship the pointer not the dump" --status resolved
+mental note --title "Identity is a UUID in bindings.json"
+```
+
+Same `--title` updates the existing decision (paths are identities). `--path` targets a specific file.
+
+Mental is **not** a todo app. Do not store transcripts. Do not duplicate PLAN.md.
+
+Non-TTY (pipes, agents) always pass `--json`. No args + not a TTY prints help and exits 2.
+
+## How agents use it
+
+Always:
+
+```bash
+mental where --json
+mental heartbeat --json
+```
+
+```bash
+mental journal --title "…" --body "…" --resume "…" --against PLAN.md --json
+mental attention --title "…" --kind concern --status open --json
+mental decide --title "…" --status open --json
+mental decide --title "…" --status decided --json
+mental search "…" --json
+mental list --type Decision --json
+mental show notes/some-fact.md --json
+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.
+
+Turns that invoked `mental` end with `<br>`, then the title `🧠 Mental`, then one type line per write/read (see the skill).
+
+## Identity (UUID, not the folder)
+
+Identity lives in `~/.mental/bindings.json`. Origin is a hint (SSH ≡ HTTPS). Two clones of the same origin share one brain until you split.
+
+| Situation | Command |
+| --- | --- |
+| This clone should use an existing UUID | `mental remap --to <uuid>` (or `mental link --to <uuid>`) |
+| This clone should diverge | `mental split` (`--copy` keeps OKF files) |
+| List bindings | `mental remap` |
+| Opt in to `./.mental` in this repo | `mental doctor --fix-ignore` then `mental local` |
+| Copy home slice into `./.mental` | `mental local --import` |
+| Same, and mark store=local | `mental local --move` |
+
+`where` does **not** create a UUID. First write (`status`, `journal`, `install`, …) does. Leftover Balakit `./.mental` (no `.mental-local` marker) is ingested into `~/.mental/projects/<uuid>/` on that write; the leftover folder is not deleted.
+
+## Optional: hooks and MCP
+
+Default **off**. Skill + rule are the contract.
+
+```bash
+mental hooks on        # Cursor sessionStart + Claude SessionStart/PreCompact → mental status --json
+mental hooks off
+mental serve           # MCP stdio: heartbeat, where, status, search, list, show, journal, attention, decide, note
+mental install --mcp   # register `mental serve` in ~/.cursor/mcp.json + ~/.claude.json; does not enable hooks
+```
+
+MCP is how tool-only agents (parallel sessions, orchestrators) re-pulse and record mid-chat. `mental uninstall` removes the MCP entries too.
+
+```bash
+mental uninstall                 # remove skill/rule/hooks copies; ~/.mental stays
+mental uninstall --delete-data --confirm DELETE   # wipe ~/.mental too
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `mental` | Heartbeat (TTY): resume, last outcome, git, residue, unsettled decisions; then exit. Non-TTY → help, exit 2 |
+| `mental heartbeat` | Same pulse; agents pass `--json` |
+| `mental where` | Active bundle: `root`, `id`, `mode`, `reason`, `gitRoot` (read-only) |
+| `mental status` | Git + Resume + residue + open/deferred decisions + notes; writes `status/current.md`; first write creates identity |
+| `mental search <q>` | Query the derived index (`--type`, `--status`, `--tag`, `--kind`); hits include `description` + `snippet` |
+| `mental list` | List concepts (`--type`, `--status`, `--tag`, `--kind`) |
+| `mental show <path>` | One OKF file relative to the bundle root (includes `backlinks`) |
+| `mental reindex` | Rebuild `${XDG_CACHE_HOME:-~/.cache}/mental/<uuid>.sqlite` |
+| `mental journal --title --body --resume [--against]` | Append today’s journal section |
+| `mental attention --title --kind` | Create or update residue (`--status resolved` closes it) |
+| `mental decide --title` | Create or update a decision (`--status decided` closes by title; `--path` targets a file) |
+| `mental note --title` | Scaffold a note |
+| `mental local [--import \| --move]` | Project `./.mental` after ignore check |
+| `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 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 |
+
+Global flags: `--json`, `--dir <path>` (same as `MENTAL_DIR`).
+
+## Privacy
+
+- Default store: `~/.mental/` (never commit).
+- Project `.mental/` is opt-in and must be gitignored (`mental doctor --fix-ignore`). Agents must not edit `.gitignore`.
+- Never store secrets, tokens, or private keys in Mental files.
+- Uninstall does not delete OKF unless you type `DELETE`.
+
+## Tests
+
+```bash
+npm test
+```
+
+## Layout
+
+OKF files under `~/.mental/projects/<uuid>/` (or `./.mental` after `mental local`):
+
+```text
+journal/YYYY-MM-DD.md
+decisions/YYYY-MM-DD-slug.md
+attention/YYYY-MM-DD-slug.md
+notes/slug.md
+status/current.md          # disposable cache, not SoT
+```
+
+Index: `${XDG_CACHE_HOME:-~/.cache}/mental/<uuid>.sqlite` (rebuildable).
+
+Agent Plugin (this repo):
+
+```text
+plugin.json                # Agent Plugins 1.0.0 manifest
+mcp.json                   # stdio MCP → ./bin/cli.mjs serve
+assets/logo.svg            # Cursor logo (portable spec has no icon field)
+.cursor-plugin/plugin.json
+.claude-plugin/plugin.json # displayName: Mental
+skills/mental/SKILL.md
+rules/mental.mdc           # Cursor always-on pointer (install copies it)
+hooks/session-start.sh     # optional; mental hooks on
+```