mindlink 1.0.0

package/commands/index.md

@@ -0,0 +1,81 @@
+# MindLink CLI Reference
+
+> Full command reference for the MindLink CLI.
+> Each command page includes synopsis, options, output examples, and error cases.
+
+---
+
+## Commands
+
+Commands are grouped by when and how you run them.
+
+### Run once — in your terminal, before first AI session
+
+| Command | Description |
+|---|---|
+| [init](init.md) | Set up `.brain/` memory for the current project |
+
+### Ask your AI to run — or run yourself in any terminal
+
+| Command | Description |
+|---|---|
+| [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 |
+
+### Keep running in a background terminal tab (while sessions are active)
+
+| Command | Description |
+|---|---|
+| [sync](sync.md) | Watch for changes from other sessions and surface them automatically |
+
+`mindlink sync` runs in **watch mode by default** — it stays alive and prints a notification whenever another session appends to `.brain/SHARED.md`. Use `--once` to check a single time and exit.
+
+### Run in your terminal between sessions — not via AI
+
+These commands are interactive, change settings, or modify files. Keep human hands on them.
+
+| Command | Description |
+|---|---|
+| [clear](clear.md) | Reset SESSION.md for a fresh session start (keeps memory and history) |
+| [reset](reset.md) | Wipe all `.brain/` memory back to blank templates |
+| [config](config.md) | Change agents, git tracking, or auto-sync after init |
+
+### Share and backup — run in your terminal
+
+| Command | Description |
+|---|---|
+| [export](export.md) | Export `.brain/` memory to a shareable zip |
+| [import](import.md) | Import a zip into the current project |
+
+### Maintenance — run in your terminal only
+
+| Command | Description |
+|---|---|
+| [update](update.md) | Check for a newer version — never installs without asking |
+| [uninstall](uninstall.md) | Remove MindLink from the current project |
+
+---
+
+## Global Flags
+
+These flags work on every command.
+
+| Flag | Description |
+|---|---|
+| `--help`, `-h` | Show help for the command |
+| `--version`, `-v` | Show the installed version |
+| `--yes`, `-y` | Skip confirmation prompts (where supported) |
+| `--json` | Output as JSON (status, summary, log) |
+| `--no-progress` | Disable progress bars (useful in scripts and CI) |
+
+---
+
+## Getting Help
+
+```bash
+mindlink --help
+mindlink <command> --help
+```
+
+Every command's `--help` shows a synopsis, all flags, examples, and what gets removed/changed.

package/commands/init.md

@@ -0,0 +1,124 @@
+# mindlink init
+
+Set up memory for the current project.
+
+---
+
+## Synopsis
+
+```bash
+mindlink init [--yes]
+```
+
+---
+
+## Description
+
+Creates a `.brain/` folder in the current directory and generates agent instruction files for the AI agents you select. Memory is scoped to the **absolute path** of this directory — run `mindlink init` separately in each project you want to give memory.
+
+**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.
+
+---
+
+## What Gets Created
+
+```
+your-project/
+├── .brain/
+│   ├── MEMORY.md     ← permanent facts: project identity, architecture, decisions
+│   ├── SESSION.md    ← current session state, updated as you work
+│   ├── SHARED.md     ← shared context readable and writable by any session
+│   └── LOG.md        ← full history of every session ever run
+├── CLAUDE.md         ← Claude Code instruction file (if selected)
+├── CURSOR.md         ← Cursor instruction file (if selected)
+├── AGENTS.md         ← Codex / OpenAI instruction file (if selected)
+├── GEMINI.md         ← Gemini CLI instruction file (if selected)
+└── ...               ← other agent files based on your selection
+```
+
+---
+
+## Interactive Prompts
+
+`mindlink init` walks you through three choices.
+
+### 1. Which AI agents do you use?
+
+Select the agents you use in this project. MindLink generates the right instruction file for each one.
+
+| Agent | File generated |
+|---|---|
+| Claude Code | `CLAUDE.md` |
+| Cursor | `CURSOR.md` |
+| Codex / OpenAI | `AGENTS.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Windsurf | `.windsurfrules` |
+| Cline | `.clinerules` |
+| Aider | `CONVENTIONS.md` |
+| Add custom agent | file name of your choice |
+
+**To change this later:** `mindlink config` → Agent instruction files
+
+### 2. Should .brain/ be tracked by git?
+
+| Choice | What it means |
+|---|---|
+| Enable (commit to git) | Your whole team shares the same AI memory. Decisions, context, and history are tracked alongside code. |
+| Disable (add to .gitignore) | Memory stays on your machine only. Teammates don't see it. |
+
+**To change this later:** `mindlink config` → Git tracking
+
+### 3. Auto-sync between sessions?
+
+| Choice | What it means |
+|---|---|
+| Enable (watch mode) | `mindlink sync` runs automatically in the background, keeping all sessions in sync as they write. |
+| Disable (manual) | Run `mindlink sync` yourself when you want to sync. |
+
+**To change this later:** `mindlink config` → Auto-sync
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--yes`, `-y` | Skip all prompts and use defaults (all agents selected, git enabled, auto-sync enabled) |
+
+---
+
+## Examples
+
+**Standard setup with interactive prompts:**
+```bash
+cd my-project
+mindlink init
+```
+
+**Non-interactive setup (CI or scripting):**
+```bash
+mindlink init --yes
+```
+
+---
+
+## Already Initialized
+
+If `.brain/` already exists, `mindlink init` shows a recovery menu instead of an error:
+
+```
+.brain/ already exists at this path. What would you like to do?
+❯ Change settings       mindlink config
+  View current status   mindlink status
+  Nothing — exit
+```
+
+With `--yes`, exits immediately and tells you to run `mindlink config` to change settings.
+
+---
+
+## Related Commands
+
+- [`mindlink config`](config.md) — change any setting made during init
+- [`mindlink status`](status.md) — check current memory state

package/commands/log.md

@@ -0,0 +1,65 @@
+# mindlink log
+
+View full session history.
+
+---
+
+## Synopsis
+
+```bash
+mindlink log [--all] [--limit <n>] [--since <date>] [--json]
+```
+
+---
+
+## Description
+
+Prints the contents of `.brain/LOG.md` in a readable format. Shows the last 10 sessions by default. Each entry is a summary of what was done in that session, appended automatically by your AI agent at the end of each session.
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--all` | Show the full history instead of the last 10 sessions |
+| `--limit <n>` | Show the last N sessions (default: 10) |
+| `--since <date>` | Show sessions from a specific date forward |
+| `--json` | Output as JSON for scripting or tool integration |
+
+---
+
+## Examples
+
+```bash
+mindlink log                     # last 10 sessions
+mindlink log --all               # full history
+mindlink log --limit 20          # last 20 sessions
+mindlink log --since "Apr 1"     # sessions from April 1 onward
+mindlink log --json              # machine-readable output
+```
+
+---
+
+## Output
+
+```
+Showing last 10 sessions  ·  mindlink log --all to see everything
+
+── Apr 9, 2026 ──────────────────────────────────
+Scaffolded auth module, fixed login redirect bug,
+decided on JWT over sessions.
+
+── Apr 8, 2026 ──────────────────────────────────
+Set up project structure, defined DB schema,
+decided on Postgres over MySQL.
+
+...8 more sessions
+```
+
+---
+
+## Related Commands
+
+- [`mindlink status`](status.md) — quick summary of the last session only
+- [`mindlink clear`](clear.md) — reset current session state

package/commands/reset.md

@@ -0,0 +1,81 @@
+# mindlink reset
+
+Wipe all `.brain/` memory files and start completely fresh.
+
+**Run in your terminal, between sessions — not via AI.** This is a destructive operation; always prompts for confirmation first.
+
+---
+
+## Synopsis
+
+```bash
+mindlink reset [--yes]
+```
+
+---
+
+## Description
+
+Resets all four `.brain/` memory files — `MEMORY.md`, `SESSION.md`, `SHARED.md`, and `LOG.md` — back to blank templates. Your settings (`config.json`) and agent instruction files (e.g. `CLAUDE.md`, `CURSOR.md`) are untouched.
+
+Use this when the project direction has fundamentally changed and you want your AI to start with no prior context. For simply starting a new work session, use [`mindlink clear`](clear.md) instead.
+
+Not what you need? See:
+- [`mindlink clear`](clear.md) — reset SESSION.md only (lighter option, keeps all history)
+- [`mindlink uninstall`](uninstall.md) — remove MindLink from this project entirely
+
+---
+
+## What Gets Reset vs Preserved
+
+| File | Action |
+|---|---|
+| `.brain/MEMORY.md` | Reset to blank template |
+| `.brain/SESSION.md` | Reset to blank template |
+| `.brain/SHARED.md` | Reset to blank template |
+| `.brain/LOG.md` | Reset to blank template |
+| `.brain/config.json` | Untouched — settings preserved |
+| Agent files (CLAUDE.md etc.) | Untouched — instruction files preserved |
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--yes`, `-y` | Skip the confirmation prompt |
+
+---
+
+## Examples
+
+```bash
+mindlink reset
+mindlink reset --yes
+```
+
+---
+
+## Output
+
+```
+! This will wipe all .brain/ memory files and start fresh.
+  MEMORY.md, SESSION.md, SHARED.md, and LOG.md will be reset to blank templates.
+  Your settings and agent files are untouched.
+
+  This cannot be undone (unless .brain/ is tracked by git).
+
+❯ Yes, reset everything
+  Cancel
+
+✓  .brain/ reset. All memory files are blank.
+   Your AI will wake up with no memory of past sessions.
+```
+
+---
+
+## Related Commands
+
+- [`mindlink clear`](clear.md) — lighter reset, SESSION.md only
+- [`mindlink init`](init.md) — set up a project from scratch
+- [`mindlink status`](status.md) — check current memory before resetting

package/commands/status.md

@@ -0,0 +1,76 @@
+# mindlink status
+
+Show last session summary and what's next.
+
+---
+
+## Synopsis
+
+```bash
+mindlink status [--json]
+```
+
+---
+
+## Description
+
+Reads `.brain/SESSION.md` and `.brain/LOG.md` and surfaces the most relevant context from your last session: what was completed, what's coming up next, and basic memory stats.
+
+Useful at the start of a session to quickly orient yourself before opening an AI agent.
+
+---
+
+## Output
+
+```
+Last session — Apr 9, 2026
+
+Completed
+✓  Scaffolded auth module
+✓  Fixed login redirect bug
+✓  Decided: use JWT, not sessions
+
+Up next
+→  Write tests for auth middleware
+→  Hook up password reset flow
+
+Memory stats
+   Sessions logged : 4
+   Decisions made  : 7
+   Last updated    : 2 hours ago
+
+Run mindlink log to see full history.
+```
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON for scripting or tool integration |
+
+---
+
+## Examples
+
+```bash
+mindlink status
+mindlink status --json
+```
+
+---
+
+## Error: Not Initialized
+
+```
+✗  No .brain/ found in this directory.
+   Run mindlink init to get started.
+```
+
+---
+
+## Related Commands
+
+- [`mindlink log`](log.md) — view full session history
+- [`mindlink init`](init.md) — set up memory for this project

package/commands/summary.md

@@ -0,0 +1,89 @@
+# mindlink summary
+
+Show a full briefing of everything MindLink knows about this project.
+
+---
+
+## Synopsis
+
+```bash
+mindlink summary [--json]
+```
+
+---
+
+## Description
+
+Reads all four `.brain/` files and surfaces everything in one view: project identity, architecture, decisions, current session state, what other sessions have shared, and recent history.
+
+Your AI agent can run this itself — just tell it `mindlink summary` and it reads the output directly. This is the cleanest way to brief a mid-session agent without copying files around.
+
+---
+
+## Output
+
+```
+◉ MindLink — Full Briefing
+
+Project Overview
+────────────────
+A todo app built with Next.js and Postgres.
+
+Current Session
+───────────────
+Task:       Build the login page
+In progress: Auth form, JWT middleware
+Blockers:    None
+Up next:     Password reset flow
+
+Shared Context
+──────────────
+Session A found: use Postgres over SQLite — better for concurrent writes.
+
+Recent History (last 3 sessions)
+─────────────────────────────────
+[Apr 9] Scaffolded auth module. Decided: JWT over sessions.
+[Apr 8] Set up database schema. Added migrations.
+[Apr 7] Project started. Chose Next.js + Postgres stack.
+
+Powered by MindLink — github.com/404-not-found/mindlink
+```
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON with keys: `project`, `session`, `log`, `shared` |
+
+---
+
+## Examples
+
+```bash
+mindlink summary
+mindlink summary --json
+```
+
+Ask your AI agent to run it:
+```
+Run mindlink summary and brief me on where we left off.
+```
+
+---
+
+## Error: Not Initialized
+
+```
+✗  No .brain/ found in this directory.
+   Run mindlink init to get started.
+```
+
+---
+
+## Related Commands
+
+- [`mindlink status`](status.md) — lighter-weight last-session view
+- [`mindlink log`](log.md) — full session history
+- [`mindlink init`](init.md) — set up memory for this project

package/commands/sync.md

@@ -0,0 +1,96 @@
+# mindlink sync
+
+Watch for shared context written by other sessions and surface it automatically.
+
+**Run this in a dedicated background terminal tab** while your AI sessions are active. It stays running until you stop it (Ctrl+C).
+
+---
+
+## Synopsis
+
+```bash
+mindlink sync [--once] [--no-progress]
+```
+
+---
+
+## What "watch mode" means
+
+**Watch mode is the default** — when you run `mindlink sync` with no flags, the process stays alive. It watches `.brain/SHARED.md` for any new content written by other sessions in this project. The moment another session appends a discovery or decision, sync detects the change and prints a notification so you know to tell your AI to check `SHARED.md`.
+
+This is designed to run in a separate terminal tab alongside your AI session, not as a one-shot command.
+
+**`--once`** runs a single check and exits — useful when you just want to see what's been shared so far without keeping a watcher running.
+
+If you enabled auto-sync during `mindlink init`, sync runs automatically in the background — you don't need to run this manually.
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--once` | Sync once and exit instead of watching continuously |
+| `--no-progress` | Suppress progress output (useful in scripts) |
+
+---
+
+## Examples
+
+**Watch mode (default) — runs until you stop it:**
+```bash
+mindlink sync
+```
+
+**Sync once and exit:**
+```bash
+mindlink sync --once
+```
+
+---
+
+## Output
+
+**Watch mode:**
+```
+Watching for changes...  (Ctrl+C to stop)
+
+[Apr 9 14:32]  Session A wrote 3 new entries  →  synced ✓
+[Apr 9 14:45]  Session B wrote 1 new entry    →  synced ✓
+```
+
+**Single run:**
+```
+Syncing shared context...
+
+Session A  →  3 new entries
+Session B  →  1 new entry
+
+[████████████████████] 100%
+
+✓  SHARED.md merged. Both sessions are now in sync.
+```
+
+**Nothing to sync:**
+```
+✓  Already in sync. No new entries to merge.
+```
+
+---
+
+## Changing Auto-Sync Setting
+
+To enable or disable auto-sync (set during `mindlink init`):
+
+```bash
+mindlink config
+```
+
+Select **Auto-sync** from the menu.
+
+---
+
+## Related Commands
+
+- [`mindlink config`](config.md) — enable or disable auto-sync
+- [`mindlink status`](status.md) — check current session state

package/commands/uninstall.md

@@ -0,0 +1,88 @@
+# mindlink uninstall
+
+Remove MindLink from the current project.
+
+**Run in your terminal only** — this permanently removes files. Always prompts for confirmation first.
+
+---
+
+## Synopsis
+
+```bash
+mindlink uninstall [--yes]
+```
+
+---
+
+## Description
+
+Removes everything MindLink created in this project directory:
+
+- `.brain/` folder and all memory files inside it
+- Agent instruction files (`CLAUDE.md`, `CURSOR.md`, etc.) that were created during `mindlink init`
+- `.claude/settings.json` hook (if Claude was one of the configured agents)
+
+The MindLink CLI itself is **not** removed. To uninstall the CLI globally:
+
+```bash
+npm uninstall -g mindlink
+```
+
+MindLink reads `config.json` inside `.brain/` to know which agent files to remove. If config is unreadable, it removes all known agent files as a safe default.
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--yes`, `-y` | Skip confirmation and remove everything immediately |
+
+---
+
+## Examples
+
+```bash
+mindlink uninstall          # interactive — shows what will be removed, asks to confirm
+mindlink uninstall --yes    # skip confirmation (useful in scripts)
+```
+
+---
+
+## What Gets Removed
+
+```
+.brain/                 (all memory files)
+CLAUDE.md               (if Claude was configured)
+CURSOR.md               (if Cursor was configured)
+AGENTS.md               (if Codex was configured)
+GEMINI.md               (if Gemini was configured)
+.github/copilot-instructions.md  (if Copilot was configured)
+.windsurfrules          (if Windsurf was configured)
+.clinerules             (if Cline was configured)
+CONVENTIONS.md          (if Aider was configured)
+.claude/settings.json   (if Claude was configured)
+```
+
+---
+
+## What Stays
+
+- The mindlink CLI itself
+- Any files MindLink did not create
+
+---
+
+## Error: Not Initialized
+
+```
+✗  No .brain/ found in this directory.
+   Nothing to uninstall here.
+```
+
+---
+
+## Related Commands
+
+- [`mindlink init`](init.md) — set up memory for this project
+- [`mindlink reset`](reset.md) — wipe memory but keep MindLink installed