mindlink 1.1.4 → 1.2.0

package/README.md

@@ -12,15 +12,17 @@ Three things break AI-assisted development:
 
 MindLink fixes all three. One command per project.
 
+Git gave every developer a shared version history. MindLink gives your AI team a shared memory — persistent, version-controlled, and not locked inside any one tool.
+
 [![npm version](https://img.shields.io/npm/v/mindlink)](https://www.npmjs.com/package/mindlink)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#installation)
 
 ---
 
-> ### ◉ Latest — v1.1.4
-> **Session memory · Cross-session sync · Cross-agent · 8 AI agents supported · Auto-refresh agent files on every update**
-> [→ Full release notes](https://github.com/404-not-found/mindlink/releases/tag/v1.1.4)
+> ### ◉ Latest — v1.2.0
+> **Auto-bootstrap on init · `mindlink diff` · Team onboarding mode · Memory timestamps · Windows hook warning · Propagating update system**
+> [→ Full release notes](https://github.com/404-not-found/mindlink/releases/tag/v1.2.0)
 
 ---
 
@@ -32,7 +34,8 @@ MindLink fixes all three. One command per project.
 - [Supported Agents](#supported-agents)
 - [Commands](#commands)
 - [Can My AI Run These Commands?](#can-my-ai-run-these-commands-itself)
-- [The Hook (Claude Code)](#the-hook-claude-code-users)
+- [What's New in v1.2](#whats-new-in-v12)
+- [Best with Claude Code](#best-with-claude-code)
 - [License](#license)
 - [Contributing](#contributing)
 
@@ -90,7 +93,7 @@ Close any AI session whenever you want — Claude Code, Cursor, Codex, whatever
 
 **One memory, every agent** — use Claude Code in the morning, switch to Cursor in the afternoon — both read the exact same `.brain/` folder. No syncing. No duplicating context. No "but I told the other AI this already." Every agent you use shares one brain, because the memory lives in your project, not inside any particular tool. This is something no AI vendor can replicate — they each only know their own product.
 
-**Team memory out of the box** — commit `.brain/` to git and your whole team shares the same AI context. New teammate joins, does `git pull`, and their AI agent is already fully briefed on the project. No onboarding session, no copying notes, no "let me catch you up."
+**Team memory, like git** — commit `.brain/` to git and your whole team shares the same AI context, automatically. New developer joins, does `git pull` — their AI is already fully briefed. Two developers in the same project? Their agents share context in real time, just like working off the same branch. No onboarding session, no copying notes, no "let me catch you up." This is what git did for code history — MindLink does for AI memory.
 
 **Plug in, not lock in** — works with Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, Windsurf, Cline, Aider, and more. Because MindLink just writes files that agents read — no APIs, no SDKs, no version dependencies — it works with whatever version you have installed today and every version that comes after.
 
@@ -116,6 +119,10 @@ MindLink works with any version of:
 | Windsurf | `.windsurfrules` |
 | Cline | `.clinerules` |
 | Aider | `CONVENTIONS.md` |
+| Zed | `.rules` |
+| Kiro | `.kiro/steering/mindlink.md` |
+| Continue.dev | `.continue/rules/mindlink.md` |
+| Trae | `.trae/rules/mindlink.md` |
 
 MindLink works by writing instruction files that agents read at startup — no API calls, no SDKs, no version pinning. It works with whatever version you have today and any version released tomorrow. If your agent isn't listed, `mindlink init` lets you add a custom one.
 
@@ -126,7 +133,7 @@ MindLink works by writing instruction files that agents read at startup — no A
 **Run once per project — in your terminal, inside the project directory:**
 ```bash
 cd my-project
-mindlink init        # creates .brain/ here — this is where your AI's memory lives
+mindlink init        # creates .brain/ here — pre-filled from your project on day 1
 ```
 
 **Ask your AI to run these, or run them yourself in any terminal:**
@@ -134,6 +141,7 @@ mindlink init        # creates .brain/ here — this is where your AI's memory l
 mindlink status      # what happened last session, what's next
 mindlink summary     # full briefing — everything your AI knows, in one view
 mindlink log         # complete session history
+mindlink diff        # what changed in .brain/ since last session
 mindlink sync --once # check what other sessions have shared
 ```
 
@@ -159,7 +167,7 @@ mindlink import      # unzip into this project — merge or overwrite your exist
 **Run in your terminal only — maintenance tasks:**
 ```bash
 mindlink doctor      # health check — verify your setup is working correctly
-mindlink update      # check for a newer version, never installs without asking
+mindlink update      # check for a newer version, refreshes agent files in all projects
 mindlink uninstall   # remove MindLink from this project
 ```
 
@@ -171,7 +179,7 @@ Every command supports `--help`. Full CLI reference: [commands/](commands/index.
 
 Yes — and it should, for the read-only ones. Your AI has a terminal. Tell it to run `mindlink summary` or `mindlink status` and it reads the output directly. This is the cleanest way to brief a mid-session agent without copying files around.
 
-**AI can run:** `status`, `summary`, `log`, `sync --once`
+**AI can run:** `status`, `summary`, `log`, `diff`, `sync --once`
 
 **Run yourself:** `init`, `clear`, `reset`, `config`, `export`, `import`, `update`, `uninstall` — these are interactive, change settings, or modify files. Keep human hands on them.
 
@@ -179,9 +187,42 @@ The one exception: `mindlink sync` in watch mode runs continuously — keep it i
 
 ---
 
-## The Hook (Claude Code users)
+## Best with Claude Code
+
+MindLink works with every agent listed above. But Claude Code users get something the others don't: **a second enforcement layer**.
+
+Every other agent reads the instruction file at startup and follows it as best it can. That's the instruction layer — guidance, not guarantees. The agent can skip a step, misread a section, or forget to write after a long session.
+
+Claude Code gets both the instruction file **and** an OS-level hook that fires before every single message — outside the AI's control. This hook:
+
+- Scans for memory triggers and reminds the agent to write `MEMORY.md` before answering
+- Forces `SESSION.md` to be updated as the last action of every response
+- Runs a shell-level check after every response: if `MEMORY.md` still contains only placeholders, the agent is immediately flagged and must fill it in before continuing
+
+**The practical difference:**
+
+| | All other agents | Claude Code |
+|---|---|---|
+| Persistent memory | ✓ instruction file | ✓ instruction file + hook |
+| Enforced on every message | ✗ | ✓ OS-level hook |
+| Post-response memory verification | ✗ | ✓ shell check |
+| Context compaction recovery | ✓ instruction | ✓ instruction + hook |
+
+If you're choosing an agent specifically to use with MindLink, Claude Code gives you the most reliable memory behavior. Other agents work well — Claude Code works harder.
+
+---
+
+## What's New in v1.2
+
+**`mindlink init` now pre-fills your memory on day 1.** It scans your project — `package.json`, `README.md`, recent git commits, top-level directories — and writes a populated Core section into `MEMORY.md` before your first session. No more blank slate.
+
+**Team onboarding mode.** When a teammate runs `mindlink init` in a project that already has `.brain/` memory, MindLink detects it and offers "set up agent files only" — writing just the instruction files without touching memory or config. One command, AI fully briefed.
+
+**`mindlink diff` — see what your AI learned this session.** Shows which `.brain/` files changed since the session started. If `.brain/` is git-tracked, shows line-level additions and removals.
+
+**Memory timestamps.** Agent instruction files now tell the AI to append `<!-- added: YYYY-MM-DD -->` to every new entry — so you can see how old a fact is and spot stale decisions.
 
-Claude Code users get an extra layer: a `UserPromptSubmit` hook in `.claude/settings.json` that fires on every message, reminding your agent to re-read `.brain/` if its context was just compacted. Other agents rely on their instruction files — Claude Code gets both because it supports OS-level hooks. Same protection, different delivery.
+**`mindlink update` now propagates everything.** When a new version adds a section to MEMORY.md or changes a template, running `mindlink update` applies those changes to all your initialized projects — without touching your existing memory content.
 
 ---
 

package/commands/diff.md

@@ -0,0 +1,115 @@
+# mindlink diff
+
+Show what changed in `.brain/` since the current session started.
+
+---
+
+## Synopsis
+
+```bash
+mindlink diff [--since <ref>] [--json]
+```
+
+---
+
+## Description
+
+Shows a per-file summary of `.brain/` changes since the session began — which files were modified, how many lines they contain, and when they were last touched.
+
+If `.brain/` is committed to git, `mindlink diff` also shows line-level additions and removals so you can see exactly what the AI wrote.
+
+This command is useful for:
+- Verifying that your AI actually wrote to MEMORY.md during the session (not just claimed to)
+- Reviewing what context was captured before closing a session
+- Debugging why a follow-up session is missing context
+
+**Your AI can run this.** Ask it to run `mindlink diff` to check its own work.
+
+---
+
+## Output
+
+**Without git tracking:**
+```
+  .brain/ changes
+  Session started 12m ago
+  .brain/ is not git-tracked — showing modification times only
+
+  ●  MEMORY.md   94 lines · modified 3m ago
+  ○  SESSION.md  32 lines · modified 12m ago
+  ○  LOG.md      24 lines · modified 12m ago
+  ○  SHARED.md   21 lines · modified 12m ago
+
+  ✓  1 file updated this session.
+```
+
+`●` = modified this session · `○` = not modified this session
+
+**With git tracking (`.brain/` committed):**
+```
+  .brain/ changes
+  Session started 12m ago
+  Git diff against: HEAD~1
+
+  ●  MEMORY.md   97 lines · modified 3m ago
+       + TypeScript + Node.js <!-- added: 2026-04-12 -->
+       + Use mtime-based session verification for Stop hook
+
+  ○  SESSION.md  32 lines · modified 12m ago
+       no changes since last commit
+```
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--since <ref>` | Git ref or date to diff against. Default: `HEAD~1`. Examples: `HEAD~3`, `"2026-04-10"` |
+| `--json` | Output as JSON — useful for scripting or AI consumption |
+
+---
+
+## Examples
+
+**Check what changed this session:**
+```bash
+mindlink diff
+```
+
+**Diff against 3 commits ago:**
+```bash
+mindlink diff --since HEAD~3
+```
+
+**Machine-readable output:**
+```bash
+mindlink diff --json
+```
+
+---
+
+## JSON Output
+
+```json
+{
+  "MEMORY.md": {
+    "exists": true,
+    "mtime": 1776041234567,
+    "sizeLines": 97,
+    "added": ["TypeScript + Node.js"],
+    "removed": []
+  },
+  "SESSION.md": { "exists": true, "mtime": 1776041117345, "sizeLines": 32, "added": [], "removed": [] },
+  "LOG.md":     { "exists": true, "mtime": 1776041117346, "sizeLines": 24, "added": [], "removed": [] },
+  "SHARED.md":  { "exists": true, "mtime": 1776041117346, "sizeLines": 21, "added": [], "removed": [] }
+}
+```
+
+---
+
+## Related Commands
+
+- [`mindlink status`](status.md) — high-level view of current session state
+- [`mindlink summary`](summary.md) — full contents of all `.brain/` files in one view
+- [`mindlink clear`](clear.md) — reset SESSION.md for a fresh start

package/commands/index.md

@@ -22,6 +22,7 @@ Commands are grouped by when and how you run them.
 | [status](status.md) | Show last session summary and what's next |
 | [summary](summary.md) | Full briefing — everything MindLink knows, in one view |
 | [log](log.md) | View full session history |
+| [diff](diff.md) | Show what changed in `.brain/` since the current session started |
 
 ### Keep running in a background terminal tab (while sessions are active)
 

package/commands/init.md

@@ -18,6 +18,8 @@ Creates a `.brain/` folder in the current directory and generates agent instruct
 
 **Run this before starting your AI session.** The agent reads the instruction files on startup. If you init after a session has already started, the current session won't see it — the next one will.
 
+**MEMORY.md is pre-filled on day 1.** `mindlink init` scans your project and auto-populates the Core section with what it finds: project name and description from `package.json`, detected tech stack, top-level directory structure, and recent git commits. Your first AI session starts already briefed — no manual setup required.
+
 ---
 
 ## What Gets Created
@@ -56,6 +58,10 @@ Select the agents you use in this project. MindLink generates the right instruct
 | Windsurf | `.windsurfrules` |
 | Cline | `.clinerules` |
 | Aider | `CONVENTIONS.md` |
+| Zed | `.rules` |
+| Kiro | `.kiro/steering/mindlink.md` |
+| Continue.dev | `.continue/rules/mindlink.md` |
+| Trae | `.trae/rules/mindlink.md` |
 | Add custom agent | file name of your choice |
 
 **To change this later:** `mindlink config` → Agent instruction files
@@ -105,7 +111,7 @@ mindlink init --yes
 
 ## Already Initialized
 
-If `.brain/` already exists, `mindlink init` shows a recovery menu instead of an error:
+If `.brain/` already exists **and agent files are present**, `mindlink init` shows a recovery menu:
 
 ```
 .brain/ already exists at this path. What would you like to do?
@@ -118,6 +124,25 @@ With `--yes`, exits immediately and tells you to run `mindlink config` to change
 
 ---
 
+## Team Onboarding Mode
+
+If `.brain/` exists with real memory content **but no agent instruction files** — the typical state after `git pull` on a team project — `mindlink init` detects this automatically and offers a lighter flow:
+
+```
+◉  MindLink memory found in this project.
+   MEMORY.md has content — this looks like a team project.
+
+❯ Set up agent files    recommended for new team members
+  Full re-init          recreate everything, reconfigure settings
+  Cancel
+```
+
+**"Set up agent files"** skips all configuration prompts and writes only the instruction files (CLAUDE.md, .cursorrules, etc.) for the agents you select. The existing `.brain/` memory, session state, and config are untouched. Your AI is immediately briefed from the team's shared memory.
+
+This is the intended workflow for new team members joining a project that already uses MindLink.
+
+---
+
 ## Related Commands
 
 - [`mindlink config`](config.md) — change any setting made during init

package/commands/update.md

@@ -1,6 +1,6 @@
 # mindlink update
 
-Update mindlink to the latest version.
+Update mindlink to the latest version and refresh all project files.
 
 **Run in your terminal only** — this downloads and installs software. Always prompts before doing anything.
 
@@ -16,9 +16,18 @@ mindlink update
 
 ## Description
 
-Checks the latest version on [GitHub Releases](https://github.com/404-not-found/mindlink/releases) and prompts before installing. Never updates silently — you are always shown what version you're moving to and can cancel.
+Checks the latest version on npm and prompts before installing. Never updates silently — you are always shown what version you're moving to and can cancel.
 
-Release notes for every version are available at:
+After installing (or if you're already up to date), `mindlink update` automatically refreshes every initialized project on your machine:
+
+- **Agent instruction files** (`CLAUDE.md`, `.cursorrules`, etc.) are overwritten with the latest templates in all registered projects. These files are owned by MindLink — any manual edits will be replaced.
+- **Claude Code hooks** (`.claude/settings.json`) are refreshed to the latest hook commands.
+- **MEMORY.md migrations** are applied non-destructively — new sections introduced in this version are injected into existing MEMORY.md files if they are absent. Your existing content is never touched.
+- **Missing brain files** are created if a new version introduced a new `.brain/` file that didn't exist in older projects.
+
+This means running `mindlink update` is always safe — your memory is preserved and your projects are brought to current spec automatically.
+
+Release notes for every version:
 ```
 https://github.com/404-not-found/mindlink/releases
 ```
@@ -44,10 +53,18 @@ Latest version    : x.y.z+1
   Skip this version
   Cancel
 
-[████████████████████] 100%
-
 ✓  Updated to x.y.z+1
    See what's new: github.com/404-not-found/mindlink/releases/tag/vx.y.z+1
+
+  Refreshing agent files in 3 projects...
+
+  /Users/you/projects/my-app
+    ✓  CLAUDE.md
+    ✓  CURSOR.md
+    ✓  .claude/settings.json
+    ✓  .brain/MEMORY.md
+
+  All agent files are up to date.
 ```
 
 **Already up to date:**
@@ -59,4 +76,5 @@ Latest version    : x.y.z+1
 
 ## Related Commands
 
+- [`mindlink init`](init.md) — set up a new project
 - [`mindlink help`](index.md) — see all commands