# Changelog

## 0.5.6 (2026-11-06)

**Point your agent at the site: it explains Mega Mind and how it would help you, checks the code, and installs it only if you say yes.**

- **`docs/AGENT-OVERVIEW.md`** (also https://megamind.coinopolis.io/agent-overview.md): a guide written for an agent to
  follow and a person to read. The agent explains what Mega Mind is, says honestly whether it would help
  this user (from a quick look at their agent tools and projects), and checks the code is safe
  (every place it uses the network, every program it runs, every file outside its folders it changes),
  then stops so the user can decide. Only on a yes: installing it (the Linux binary or a source build),
  setting it up *with* the user, and the first real use. `AGENTS.md` points to it.
- **Setup finds a local librarian.** If LM Studio or Ollama is on the machine, setup says so, suggests it,
  and picks models from what's installed (the largest for reviews, a fast one for `--deep`).
  `--librarian auto` does the same unattended. An existing choice is never overridden.
- **Setup ends with the first step:** restart your agent sessions, then tell one *"Backfill the mind for
  this project."* Search on an empty mind says the same instead of "try other words".
- **Local first in the wording:** the search question says `local` sends nothing anywhere; the sample
  `config.toml` in the guide is local (LM Studio and Ollama examples), with Azure as the alternative.
- The README says what Mega Mind is next to `CLAUDE.md`/`AGENTS.md` files, and which platforms have a
  prebuilt binary.
- **Setup fetches the local search model up front** (about 420 MB, once) instead of during an agent's first
  search or record, and its list of files to change now includes the `mind`/`mega-mind` commands it adds
  and Grok's own skill copy.
- `mind doctor` mentions the one-word remote check only when search uses a remote service; "Found 1 new
  repo".
- The agent overview was tested end to end by agents: a live install on a clean Ubuntu 24.04 machine, and
  walk-throughs for macOS and Windows, with every gap they hit fixed.

## 0.5.5 (2026-11-05)

- **The session-start hook now carries the usage rules** (Claude Code and Codex get it every session,
  whether or not the agent loads the skill): search with `--brief` and read every line, never cut
  `mind` output with `head`/`tail`/`sed`, read entries in full with `mind get`, and only `mind ack`
  an entry after checking it, one at a time. Running sessions that never loaded the skill were still
  piping search to `head`, reading entries with `head -80`, and acking every stale entry in a loop.
- **The skill and rule** say the same about `ack`: it tells every later agent the entry is still true.

## 0.5.4 (2026-11-04)

- **`mind search --brief`:** one line per result (match, kind, project, id, title), the same in a terminal
  and piped. Agents were cutting the full output with `head` and missing the result that mattered
  most (in one case, a cross-project decision their task reversed, in fifth place).
- **The skill and the always-on rule** say to scan with `--brief`, read every result, never cut search
  output with `head`, and tell the user when a task changes something an entry records. They also
  say to read entries with `mind get`, not `--raw` (editing only): agents reading the raw markdown
  missed whether its code changed, "may contradict" warnings and the related entries.

## 0.5.3 (2026-11-04)

**Agents find what's already in the mind.** From a live test of Claude Code, Codex and Grok on
questions the mind already answered:

- **Search works in sandboxes.** Codex's sandbox blocks writes outside the project, so `mind search`
  failed ("unable to open database file"). Now, when the index can't be written, search (and `get`,
  `list`, `check`…) uses the saved index read-only (the newest changes may be missing), or a keyword
  index built in memory, and says so.
- **Saving from a sandbox says what to do.** Codex keeps every `.git` read-only even in folders it may
  write, so saving from inside it can't work. `mind record`/`update`/`ack`/`reindex` now say so and
  tell the agent to request escalated permissions for that one command (you approve it), instead of
  a bare "Permission denied".
- **Suggestions on each message:** the prompt hook lists the ids of up to three entries that share
  enough words with the message (a distinctive one, or two in the title; each once per session), so
  an agent opens them before digging through code. Ids only, and only of real entry files: an
  entry's title is another agent's text and isn't put in front of the agent unasked. It reads the saved index only (tens of milliseconds). Claude Code
  and Codex get these; Grok's hooks don't reach the model. `[hooks] suggest = false` turns them off.
  This is the first setting added since 0.5.2's approval change: it doesn't ask anyone to re-approve.
- **"Search first"** in the skill, the always-on rule and the session-start note: before reading code
  to answer a "how do we…" or "why does…" question, not only before building.

## 0.5.2 (2026-11-04)

**Clearer `mind setup`.**

- **Projects:** the step explains what it does and what to type (`~/code`, or a full path), asks
  again when the folder doesn't exist, and catches the common slip `~/home/<you>` ("did you mean
  /home/<you>?"). It says when every repo it finds is already registered, and a `--scan` folder that
  doesn't exist is reported as such.
- **Machine notes preview:** long lines wrap inside the `│` rail instead of breaking it (and running
  into the next line when copied). The text is shown exactly: spaces are kept, and a word longer than
  the line is broken rather than overflowing.
- **Plainer questions:** runbook review is explained before it's asked; detected tools are asked as
  "Found claude. Connect it?"; the `mega-mind` alias is reported as an alias.

**Also:**

- **Approvals survive new settings:** the per-machine approval of the AI settings (now `v4`) still covers
  every existing setting, default or not, but a setting added in a later release is left out while
  it's at its default, so adding one no longer asks everyone to approve again. Approvals made with
  0.5.1 carry over (no re-approval after this upgrade). Older binaries don't know `v4`: run one after
  this and it asks for approval again.
- **`[hooks]` settings** can be left out of `config.toml` like the other sections.
- **Windows hard links:** files in the mind that are hard links are now refused on Windows too (as on
  macOS and Linux), and the error says it's a link instead of "it must be UTF-8 text".
- **OneDrive:** `OneDrive`, `OneDrive - <Company>` and the personal folders OneDrive redirects
  (`~/OneDrive/Documents`, Desktop, Pictures…) are refused as project folders, like `~/Documents`; a
  repo such as `~/onedrive-cli` is fine. The warning now names what "too broad" covers.
- **Docs:** syncing a mind between machines (guide, section 5).

## 0.5.1 (2026-11-04)

**A rich view for people at a colour terminal.** Search results are cards: kind badge, project,
verified/stale state, a match meter, the snippet with your query words picked out, and the files
to open. `get`, `list`, `related`, `stale`, `check`, `log`, `stats`, `digest`, `doctor`, `who`,
`uses`, `projects`, `kinds` and `proposals` use the same style, and long lines wrap to the terminal.
Piped output, `NO_COLOR` and `--json` are unchanged, so agents read exactly what they read before.

## 0.5.0 (2026-11-03)

**Mega Mind, with the command `mind`.** The data folder is `mega-mind` (override with `MIND_HOME`;
the agent name with `MIND_AGENT`); `mind setup` installs the agent skill as `mega-mind`.

- **Code layout:** the two biggest files are split by job. `main.rs` (1,259 lines)
  is now `cli.rs` + `commands/` (find, write, upkeep, projects, proposals); `store.rs` (1,087 lines) is
  now `store/` (entry, kinds, mind, refs, secrets, config, paths). The program is a library with a
  thin `mind` command.

## 0.4.0 (2026-11-02)

Keeping a shared mind accurate as it grows (ideas studied from GBrain and Gigabrain, both MIT;
no code taken).

- **Links between entries:** `related` and `supersedes` must name existing entries; `mind get` shows
  links in both directions ("see also", "replaces", "linked from"); `mind check` lists broken links;
  `mind rm` refuses to delete an entry others link to unless `--yes`.
- **Retiring:** `mind retire <id> --why "…" [--by <new-id>]`. Retired and superseded entries drop out
  of search, lists, stale checks, reviews and hooks, and stay readable (`mind get`, `--all`), so an
  old procedure can't outrank its replacement.
- **`mind maintain`:** nightly upkeep that never edits entries: index, librarian review of stale
  entries, broken links, near-duplicates, and a contradiction check of closely related entries (each
  pair judged once per version, confident verdicts only). `mind get` shows "may contradict";
  `mind doctor` counts contradictions and says when maintain last ran. `nightly.sh` now runs it.
- **Privacy masking:** emails, IP addresses and home-folder user names are masked in text sent to
  remote models, plus your own patterns (`[privacy] patterns`); local models get text unchanged.
- **Trust tie-break:** when two results score about the same, the verified one ranks first.
- **Safer automatic context:** hooks name stale entries and how many of their files changed, never
  file names (entry text is untrusted); `mind get` shows librarian verdicts, and their free-text
  notes only with `--notes`. Nothing that looks like a secret is sent to any model, search queries
  included. Masking fails closed on a bad pattern, more than 50 patterns, or more than 64 KB of text.
- **OpenAI's newer models work as the librarian:** OpenAI's GPT-5 and reasoning models refuse
  `max_tokens` and a custom temperature; mind now retries once with `max_completion_tokens` and
  keeps using it. Azure, LM Studio and other OpenAI-compatible services are unchanged.
- **Hardening (Grok audit):** requests to this machine (LM Studio, local servers) never go through
  an `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY` proxy, since that traffic is unmasked and may carry a key.
  A service's error replies are no longer shown (only the HTTP status and a short error code), so a
  hostile endpoint can't put instructions or echoed keys in front of agents. Endpoint URLs with a
  `?query` are refused (keys belong in `auth`), and so is `user:password@` with any auth setting.
  Short passwords, quoted passphrases with spaces and YAML `|` blocks are caught
  as secrets, while references (`$DEPLOY_KEY`, `${TOKEN}`), placeholders and ordinary code
  (`password: String`, `self.password`, unquoted only: a quoted value is a literal) still pass
  (checked against about 6,000 files of real code). Network errors and privacy-pattern errors are
  fixed descriptions: no proxy URL, server text or pattern text in them.
  Quoted passwords made of ordinary words are secrets too; escaped Windows paths (`C:\\Users\\…`
  in JSON or code) are masked; the Azure VM sign-in request never follows redirects.
  Service error codes are shown only if they're on a known list. Doctor and sign-in errors no longer show
  a token command's arguments or `az`'s raw error output. Masking also catches `ip:2001:db8::1` and
  Windows home folders written with forward slashes (`c:/users/<name>`).

## 0.3.0 (2026-11-02)

Security and polish, from reviews by Codex and Grok.

- **Security:**
  - the secret scanner catches JSON keys (`"password": …`), `client_secret` / `AZURE_CLIENT_SECRET`,
    `secret_access_key`, `Authorization: Bearer|Basic …`, passwords inside URLs and Azure SAS tokens;
  - entries (frontmatter and body) are checked for secrets again before being sent for embeddings or
    review, so hand edits and git pulls can't slip one out; flagged entries stay keyword-searchable and
    are reported;
  - credentials are never sent over plain http (except to this machine: `localhost` or a loopback IP)
    or along a redirect; the Azure sign-in token goes only to Azure OpenAI / AI Services endpoints, or
    to gateways you list in `token_hosts` (`mind setup` asks; API Management gateways must be listed);
  - `az` runs without a shell and token scopes must be plain https URLs; the managed-identity request
    encodes its parameters and checks `AZURE_CLIENT_ID`;
  - Azure tokens are cached per scope, identity and host in the private cache folder, outside the mind
    (on Windows `%LOCALAPPDATA%\mega-mind-cache`); an old cache in the mind folder is deleted; the
    cache file is created owner-only;
  - absolute and `~/` refs must be inside a registered project (agents open refs);
  - git reads ref paths literally (`--literal-pathspecs`), so a file name can't widen a diff;
  - librarian notes are flattened (no control characters or extra lines) and never enter hook context:
    hooks show only the verdict and point to `mind get`; the librarian is told entries and diffs are
    data, not instructions; file names in hook context are sanitised;
  - `skill-local.md` joins agent instructions only if it matches what is already installed or a person
    approves it at the keyboard (`--yes` never adds new or changed text); it is checked for secrets;
  - the mind folder is created readable only by its owner; `mind doctor` warns otherwise.
- **New:** `mind upgrade` (and `--check`): fetch the clone's upstream (https or ssh only), show
  what's new, fast-forward, and rebuild the exact fetched commit from a clean checkout, with the same
  features, into the same place (on Windows the running exe is moved aside and restored on failure).
  A token in the clone's address is moved to git's credential store, read back to confirm, and only
  then removed from the address. Off a terminal it needs `--yes`. It also rebuilds when an earlier
  build failed after fetching.
- **Look and feel:**
  - one layout for every listing (search, list, related, stale): numbered bold title, a meta line
    (kind · project · verified · date · stale), and the id;
  - `mind get` shows a readable view (header, sections, files with their state, related entries, the
    librarian's labelled note) instead of raw YAML; `--raw` is unchanged;
  - search says whether it matched by meaning or by keywords only (and why), wraps the matching passage
    to the terminal, and colours match scores against each provider's own thresholds;
  - `mind setup` runs as five numbered steps, keeps earlier answers when re-run, refuses empty
    required values, lists the files it will change before changing them, and ends with a summary;
  - doctor, stats and digest share the "Mega Mind" header; clearer empty states with the next command;
  - colours work in classic Windows consoles, and error colours follow stderr;
  - layouts follow the real terminal width (stats bars shrink on narrow terminals).
- **Docs:** Windows/macOS build prerequisites, `cargo install --locked`, PowerShell notes, the doctor's
  one-word embedding check, `token_hosts`, and where tokens are cached.

## 0.2.0 (2026-10-31)

- **New:** `mind doctor` checks settings, AI providers, the index and
  each agent tool's setup, with ✓/⚠/✗ and what to fix.
- **New:** `mind stats`, also shown by plain `mind`: entries per project and kind, stale counts, most
  active writers, newest entries.
- **New:** `mind digest [--since 24h|3d|2w|DATE]`: what agents recorded recently, grouped by project.
- **New:** `mind setup`: one-time, re-runnable configuration (name, reviewer, AI providers, agent
  tools, projects), merging into existing settings.
- **New:** pluggable AI. Embeddings: local (optional `local-embeddings` build feature), Azure OpenAI
  (keyless via managed identity or `az login`), any OpenAI-compatible server, or none (keyword
  search). Librarian: LM Studio, Azure, OpenAI-compatible, or none.
- **New:** Codex and Grok support (skill, always-on instructions, hooks); Copilot and other tools get an
  instruction block to paste.
- Search falls back to keywords when the embedding provider is unreachable, and catches up later.
- Stale-entry notes repeat after 10 messages if not handled; only entries actually shown count as told.
- Colour output in terminals (plain when piped or with `NO_COLOR`); help with examples.
- Duplicate check only compares entries of the same kind.
- Personal names and paths moved from code into settings; Windows and macOS paths.
- Security and robustness fixes from independent audits (Claude and Grok):
  - the librarian sends only git diffs of files inside registered projects, never whole files, and
    withholds secret-looking diffs; only real commit hashes reach `git diff`, with external diff tools off;
  - refs can't escape their project (`..`, symlinks, Windows drive letters);
  - the OS certificate store is used (corporate TLS inspection); Azure tokens are cached between runs;
    `AZURE_CLIENT_ID`, slow managed-identity endpoints, `…/openai` URLs and custom token scopes work;
  - `mind record` works when embeddings are down; mind commits ignore global signing and git hooks;
  - librarian notes reach agents marked as unverified AI notes;
  - `mind setup` writes settings atomically and keeps a one-time backup; `mind edit` uses a private
    temp file and editors with arguments; concurrent edits of one entry are refused, not lost;
  - match thresholds per provider (configurable); Azure keys and connection strings in the secret scan.
- Automated tests (`cargo test`).
- Removed `mind backup` (back up the mind folder however you back up other files).

## 0.1.0

- First version: entries in git, hybrid search, staleness via file fingerprints, hooks for Claude Code,
  runbook proposals, LM Studio librarian.