brain-wiki 0.1.0.dev0__tar.gz → 0.1.0.dev1__tar.gz

{brain_wiki-0.1.0.dev0 → brain_wiki-0.1.0.dev1}/.claude-plugin/marketplace.json

@@ -4,7 +4,7 @@
     "name": "brain-wiki contributors"
   },
   "description": "brain-wiki: a local-first Markdown second brain shared by your AI agents.",
-  "version": "0.1.0.dev0",
+  "version": "0.1.0.dev1",
   "plugins": [
     {
       "name": "brain-wiki",

{brain_wiki-0.1.0.dev0 → brain_wiki-0.1.0.dev1}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "brain-wiki",
   "displayName": "brain-wiki",
-  "version": "0.1.0.dev0",
+  "version": "0.1.0.dev1",
   "description": "A local-first second brain for AI agents, kept as plain Markdown that you own.",
   "author": {
     "name": "brain-wiki contributors"

{brain_wiki-0.1.0.dev0 → brain_wiki-0.1.0.dev1}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "brain-wiki==0.1.0.dev0",
+        "brain-wiki==0.1.0.dev1",
         "brain",
         "mcp",
         "--host",

brain_wiki-0.1.0.dev1/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+## 0.1.0.dev1 (2026-10-14)
+
+- `brain setup --guide` prints the setup steps for an AI agent, so any agent
+  that can run commands can set brain-wiki up from one prompt, without the
+  plugin. Without a terminal, `brain setup` points to it, and an agent that
+  finds no brain is told to use the `brain-setup` skill or the guide.
+- Every setup step is now a command, so the guide never edits config files:
+  `brain agents [list | grant | revoke]` changes what an app may do as an
+  undoable run, and `brain harvest enable | disable | route` configures
+  harvest. A refusal names the `brain agents grant` command that allows it.
+  `brain brains limit HOST BRAIN...` and `unlimit HOST` set which brains an
+  app may use.
+- `brain setup` also asks what each connected app may do, grants the
+  `harvest` ability with harvest, and ends with what to try next.
+- The CLI is built on Typer. Action commands are real subcommands with their
+  own help (`brain rules add --help`), and `brain --install-completion`
+  installs tab completion. `--brain`, `--as`, and `--json` still work before
+  or after the command. `brain --version` also prints the file format.
+- Removed commands, and what replaces them: `brain version` → `brain
+  --version`; `brain list` → `brain brains` (also with `--as HOST`); `brain
+  notes` and `brain recent` → `brain search ""` with filters (e.g. `brain
+  search "" --since 7d`; browsing sorts by `recent`); `brain outline TARGET` →
+  `brain read TARGET --mode outline`.
+- `brain rule` is now `brain rules`; `rule` still works as a hidden alias.
+- `brain review` also covers rule proposals: `review list` shows them with
+  consolidation and edit proposals, marking each one's kind, and `review
+  show`, `accept`, and `reject` take a rule proposal's id.
+- `brain import --phase` given with a mode other than `--overlay` is a usage
+  error even when it is `--phase 0`.
+- Harvest routes are a fallback: a project's `.brain-wiki.toml` now wins over
+  a catch-all route such as `~/**`.
+
+Fixes from an audit of every command, each with a regression test:
+
+- **Data loss:** undo could delete notes when the first write came before
+  any full scan. In a git brain, undo lost files git never tracked (inbox
+  episodes, proposals), left deletions staged, and failed for any run but the
+  newest. Undo now restores from the run's saved copies in every brain.
+- **Safety:** `brain review accept` trusted the packet inside the proposal
+  file, so a forged one could write `rules.md`; it now rebuilds the packet
+  from the brain. `--as HOST` is enforced by every write command.
+- `brain import --apply --dry-run` applied the import; a failed `brain
+  brains rename` deleted the brain's entry; overlay phases 1–3 never ran in
+  a git repository; `--to-episodes` turned frontmatter into an episode.
+- `tags`, `types`, `orphans`, and `unresolved` showed a stale index; `search
+  --where` ignored tags, aliases, title, and id; `read --mode raw` was not
+  the raw file; `doctor` counted hubs as notes.
+- `brain check` recorded edits that lint rejects; `brain mv` of a topic left
+  its `brain.toml` entry behind; topics with `review = "always"` skipped
+  review for new notes.
+- `brain connect` broke a project-scope install on a later user-scope
+  connect, did not restore config files byte for byte, and crashed on
+  malformed JSON.
+- Unexpected errors exit 10 with a log reference instead of a traceback;
+  conflicts report `conflict:`, and only stale data reports `stale:`.
+
+## 0.1.0.dev0 (2026-10-14)
+
+First release.
+
+- **Brain format**: plain Markdown notes with frontmatter, claims with
+  provenance, and typed relations (`part_of`, `depends_on`,
+  `conflicts_with`, `supersedes`, `related_to`, and their inverses);
+  topics as folders, nested to any depth; immutable inbox episodes;
+  `rules.md`; a managed `AGENTS.md` block.
+- **Index and retrieval**: SQLite FTS5 index outside the brain, freshness
+  checks, guard co-retrieval (superseding and conflicting notes come with
+  every hit), search filters, facets, and intents, orientation, and
+  Obsidian-style browsing (`brain topics`, `notes`, `links`, `backlinks`,
+  `tags`, and more).
+- **Write path**: one episode writer with server-set provenance, secret
+  redaction, size caps, and dedupe; episodes dropped in by hand count as
+  untrusted; checked direct edits (`brain check`, `brain restore`, a
+  per-topic `agent_edits` policy), which agents may make by default; rules
+  that need the user's words and confirmation; `brain mv`.
+- **Runs**: every curated change is locked, gated by lint, recorded with
+  pre-images, committed to git when the brain is a repository, and
+  undoable.
+- **Consolidation**: packets with short handles, a per-op validator, a
+  deterministic writer that never deletes text, and review proposals. Your
+  agent consolidates in its session over MCP; `brain consolidate --prepare`
+  and `--apply` drive it by hand.
+- **Lint and reports**: the BW rule catalog with strict and migrate
+  profiles, cached whole-brain lint, safe fixes as one run, staged-file
+  lint and a pre-commit hook, and browsable reports.
+- **Agents**: a stdio MCP server with thirteen tools and three prompts;
+  `brain connect` for Claude Code, Codex, Antigravity, OpenClaw, and
+  Cursor, with instructions placed where each host reads them; session readers and
+  harvest for Claude Code, Codex, and Antigravity, with headless presets
+  for large backfills; origin lookup; a plugin bundle with three skills;
+  `brain setup` and `brain doctor`.
+- **Import**: overlay adoption of Obsidian vaults in phases, copying into
+  a brain, documents and agent memory files as episodes.
+- **Visualizer**: `brain viz`, a local read-only 3D map of groups,
+  topics, folders, and notes with typed relations and issue highlighting,
+  and HTML, JSON, and GraphML export.
+- **Bench**: offline retrieval, lint, and performance suites, and
+  model-backed consolidation scenarios through headless presets.
+
+Known limitations:
+
+- No privacy levels inside a brain: every agent that may use a brain
+  reads all of it. Keep separate lives in separate brains
+  ([proposal](https://github.com/brain-wiki/brain-wiki/blob/main/docs/proposals/privacy.md)).
+- Maintenance runs when you ask your agent; there is no scheduler
+  ([proposal](https://github.com/brain-wiki/brain-wiki/blob/main/docs/proposals/scheduled-maintenance.md)).
+- Chat apps that need a remote MCP server (ChatGPT, claude.ai, the Gemini
+  app) are not supported ([proposal](https://github.com/brain-wiki/brain-wiki/blob/main/docs/proposals/remote-mcp.md)).

{brain_wiki-0.1.0.dev0 → brain_wiki-0.1.0.dev1}/CONTRIBUTING.md

@@ -49,14 +49,14 @@ with Python 3.11 and 3.13, runs brain-wiki-viz's checks at the bundle's
 commit, and checks that the bundle rebuilds from it. A version tag runs
 `.github/workflows/release.yml`: it checks the tag against the version and
 the changelog, runs the checks, builds, publishes to PyPI with trusted
-publishing, publishes `server.json` to the MCP Registry (final versions
-only), and creates the GitHub release from the changelog entry.
+publishing, and creates the GitHub release from the changelog entry. Its
+MCP Registry job is turned off until the project decides to be listed.
 
 1. Set `version` in `pyproject.toml` to `X.Y.Z`, or a development release
    such as `X.Y.Z.devN`, and date its changelog entry: `## X.Y.Z (YYYY-MM-DD)`.
    A development release goes to PyPI like any other, and pip and uv install
    it while no final release exists; the GitHub release is marked a
-   pre-release, and the MCP Registry, a public catalog, is skipped.
+   pre-release.
 2. `uv run scripts/sync_versions.py`, then commit.
 3. `git tag vX.Y.Z && git push origin main vX.Y.Z`.
 4. Move `main` to the next development version (`X.Y.(Z+1).dev0` after

{brain_wiki-0.1.0.dev0 → brain_wiki-0.1.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: brain-wiki
-Version: 0.1.0.dev0
+Version: 0.1.0.dev1
 Summary: A local-first second brain for AI agents, kept as plain Markdown that you own.
 Project-URL: Homepage, https://github.com/brain-wiki/brain-wiki
 Project-URL: Documentation, https://github.com/brain-wiki/brain-wiki/tree/main/docs/user
@@ -30,6 +30,7 @@ Requires-Dist: jsonschema>=4.20
 Requires-Dist: mcp<3,>=2.3
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: tomlkit>=0.12
+Requires-Dist: typer<1,>=0.26
 Description-Content-Type: text/markdown
 
 # brain-wiki
@@ -89,12 +90,18 @@ uv, Homebrew, and most Linux builds include, and [uv](https://docs.astral.sh/uv/
 | Antigravity | `agy plugin install https://github.com/brain-wiki/brain-wiki` |
 | OpenClaw, Cursor, other MCP clients | Install the command, then `brain connect openclaw`, `brain connect cursor`, or `brain connect generic --print` (see below) |
 
+No plugin yet, or an agent not listed? Ask any agent that can run commands:
+
+> Install brain-wiki with `uv tool install brain-wiki`, then run
+> `brain setup --guide` and follow it.
+
 **2. Ask your agent to set it up.**
 
 > Set up brain-wiki.
 
-The `brain-setup` skill explains each choice, lets you decide, and shows
-every change before making it:
+The `brain-setup` skill (or the guide `brain setup --guide` prints, which
+holds the same steps) explains each choice, lets you decide, and shows every
+change before making it:
 
 - where your brain lives (a new folder, or an Obsidian vault adopted in
   place) and whether to track it with git;
@@ -116,21 +123,23 @@ every change before making it:
 
 ```sh
 uv tool install brain-wiki      # or: pipx install brain-wiki
-brain doctor                    # checks SQLite, your brains, and the agents on this machine
-brain init ~/brains/personal --name personal --git
-brain connect claude-code       # or codex, antigravity, openclaw, cursor; try --dry-run first
+brain setup                     # step by step: create a brain, connect your agents, harvest
 brain log "Lumen keeps attachments next to their notes; Obsidian expects relative paths."
 brain search "attachments"
 brain viz                       # a local 3D map of the brain
 ```
 
+Or do the steps yourself: `brain doctor` (checks SQLite, your brains, and
+the agents on this machine), `brain init ~/brains/personal --name personal
+--git`, and `brain connect claude-code` (or codex, antigravity, openclaw,
+cursor; try `--dry-run` first).
+
 Keep brains outside your code repositories. Agents may log and correct
-notes by default; to let one consolidate or propose rules, give it a profile
-in the brain's `brain.toml`:
+notes by default; `brain setup` asks whether each app may also consolidate
+and propose rules, or grant it yourself:
 
-```toml
-[agents.claude-code]
-write = ["episodes", "edit", "consolidate", "propose_rules"]
+```sh
+brain agents grant claude-code consolidate propose_rules
 ```
 
 Marketplace installs start the server with `uvx`. With the command

{brain_wiki-0.1.0.dev0 → brain_wiki-0.1.0.dev1}/README.md

@@ -55,12 +55,18 @@ uv, Homebrew, and most Linux builds include, and [uv](https://docs.astral.sh/uv/
 | Antigravity | `agy plugin install https://github.com/brain-wiki/brain-wiki` |
 | OpenClaw, Cursor, other MCP clients | Install the command, then `brain connect openclaw`, `brain connect cursor`, or `brain connect generic --print` (see below) |
 
+No plugin yet, or an agent not listed? Ask any agent that can run commands:
+
+> Install brain-wiki with `uv tool install brain-wiki`, then run
+> `brain setup --guide` and follow it.
+
 **2. Ask your agent to set it up.**
 
 > Set up brain-wiki.
 
-The `brain-setup` skill explains each choice, lets you decide, and shows
-every change before making it:
+The `brain-setup` skill (or the guide `brain setup --guide` prints, which
+holds the same steps) explains each choice, lets you decide, and shows every
+change before making it:
 
 - where your brain lives (a new folder, or an Obsidian vault adopted in
   place) and whether to track it with git;
@@ -82,21 +88,23 @@ every change before making it:
 
 ```sh
 uv tool install brain-wiki      # or: pipx install brain-wiki
-brain doctor                    # checks SQLite, your brains, and the agents on this machine
-brain init ~/brains/personal --name personal --git
-brain connect claude-code       # or codex, antigravity, openclaw, cursor; try --dry-run first
+brain setup                     # step by step: create a brain, connect your agents, harvest
 brain log "Lumen keeps attachments next to their notes; Obsidian expects relative paths."
 brain search "attachments"
 brain viz                       # a local 3D map of the brain
 ```
 
+Or do the steps yourself: `brain doctor` (checks SQLite, your brains, and
+the agents on this machine), `brain init ~/brains/personal --name personal
+--git`, and `brain connect claude-code` (or codex, antigravity, openclaw,
+cursor; try `--dry-run` first).
+
 Keep brains outside your code repositories. Agents may log and correct
-notes by default; to let one consolidate or propose rules, give it a profile
-in the brain's `brain.toml`:
+notes by default; `brain setup` asks whether each app may also consolidate
+and propose rules, or grant it yourself:
 
-```toml
-[agents.claude-code]
-write = ["episodes", "edit", "consolidate", "propose_rules"]
+```sh
+brain agents grant claude-code consolidate propose_rules
 ```
 
 Marketplace installs start the server with `uvx`. With the command

{brain_wiki-0.1.0.dev0 → brain_wiki-0.1.0.dev1}/docs/design/03-config-and-storage.md

@@ -54,7 +54,9 @@ hosts   = ["claude-code"]
 - No credentials are ever stored here. Proposed remote backends use the
   platform's own credential chains ([remote sync](../proposals/remote-sync.md)).
 - The file is created by `brain init` and edited by `brain brains add |
-  remove | default`, which preserve comments and formatting.
+  remove | rename | default | limit`, which preserve comments and formatting.
+  `add` and `rename` take names of lowercase letters, digits, and hyphens.
+  An edit that fails changes nothing.
 
 ## 3. Choosing a brain
 
@@ -76,6 +78,9 @@ If nothing matches, the command fails with a message that suggests
 **Host limits.** When `[hosts.<id>] brains` is set, a selection outside
 that list is refused for that host, whichever source produced it. This is
 how a user keeps, say, a work brain away from a personal assistant.
+`brain brains limit HOST BRAIN...` sets the list and `unlimit HOST` clears
+it; a host default outside the new list moves to its first brain, since it
+would only be refused.
 
 **Project files** name a brain, not a path, so a repository can carry one
 without exposing anyone's directory layout. If the named brain does not
@@ -116,9 +121,9 @@ reports the duplicate id.
 | Adopt an existing folder | `brain import --overlay <path>` | See [09](09-import.md). Adds `brain.toml` and the generated files without moving anything. |
 | Register on another device | `brain brains add <name> <path>` | For a brain that arrived by git clone or file sync. Validates `brain.toml`. |
 | Move | move the folder, then `brain brains add <name> <new path>` | Same id, so index and history carry over. The name may be re-pointed because its old folder is no longer a brain (or holds the same brain); otherwise the name is refused. |
-| Rename | `brain brains rename <old> <new>` | Config only; `brain.toml` `name` is cosmetic. |
+| Rename | `brain brains rename <old> <new>` | Config only; `brain.toml` `name` is cosmetic. Refused when `<new>` is already registered; otherwise the entry and every reference to `<old>` (`default`, `[hosts.*] brain` and `brains`, harvest routes) change in one write. |
 | Forget | `brain brains remove <name>` | Config only. The folder, index, and state stay until `--purge-state` deletes the last two. The brain folder is never deleted by brain-wiki. |
-| Check | `brain doctor` | Config, brain, index, SQLite features (trigram), git status, host wiring, pending crashed runs. |
+| Check | `brain doctor` | Config (including brains registered with no default), brain, index (note counts as in `brain brains`), SQLite features (trigram), git status, host wiring, pending crashed runs. |
 
 ## 6. Storage and sync
 

{brain_wiki-0.1.0.dev0 → brain_wiki-0.1.0.dev1}/docs/design/04-index-and-retrieval.md

@@ -311,11 +311,11 @@ JOIN nodes n ON n.id = CASE WHEN e.src = h.id THEN e.dst ELSE e.src END;
 | Parameter | Default | Meaning |
 |---|---|---|
 | `query` | `""` | Free text. **Empty means browse**: no text matching, results ordered by `sort` (default `recent`) within the filters. |
-| `limit` | 8 | Primary results, before expansion and guards. Max 50. |
-| `topic` | all | Restrict to one or more topics, each with its sub-topics. |
+| `limit` | 8 | Primary results, before expansion and guards. Max 50 (the CLI refuses more rather than clamping). |
+| `topic` | all | Restrict to one or more topics, each with its sub-topics. Slugs match case-insensitively; an unknown slug is `not_found`, not an empty result. |
 | `type` | any | Restrict to note types (`decision`, `release`, `person`…), as in frontmatter. |
 | `tag` | any | Restrict to notes carrying all of these tags. |
-| `where` | none | Frontmatter property equality, e.g. `{"stage": "open"}`; values compare as strings, lists match any item. |
+| `where` | none | Frontmatter property equality, e.g. `{"stage": "open"}`; values compare as strings, case-insensitively, lists match any item. Keys the index keeps as columns match too: `tags` and `aliases` (any item), `title`, `id` (as written), `type`, `status` (or a custom `stage`), `topic`, `created`, `updated`. |
 | `include_episodes` | on for a query, off when browsing | Pending episodes are searchable; a browse lists curated notes unless episodes are asked for. |
 | `include_archived` | false | Also return notes with `status: archived`. |
 | `include_archived_episodes` | false | Also return consolidated episodes (CLI `--include archived_episodes` only). |
@@ -443,8 +443,8 @@ guessing.
 |---|---|
 | `outline` (default for hubs) | Frontmatter summary, headings, active claims (each with its `inputs`, and `[unverified]` in the text when not `local`), relations with resolved titles |
 | `full` (default for notes) | The body, then the current claims (unverified ones marked) and a count of superseded ones; no metadata |
-| `section` | One heading's content; `claims` gives the claims block |
-| `raw` | The file exactly as on disk (for agents about to edit it, [05 §2.3](05-write-path-and-consolidation.md#23-checked-agent-edits)) |
+| `section` | One heading's content; `claims` gives the claims block. Asking for a `section` implies this mode; the mode without a section, or a section with another mode, is a usage error |
+| `raw` | The file exactly as on disk (for agents about to edit it, [05 §2.3](05-write-path-and-consolidation.md#23-checked-agent-edits)); an episode stays in its untrusted envelope |
 
 Every relation and backlink in the result carries its handle: `id` and
 `path` in the structured result, and the path after the title in the text,
@@ -468,7 +468,8 @@ Guard banners show at most three in full, then a count with a pointer to
 `brain_neighbors` for the rest, so a note with many conflicts does not bury
 its own content. Search results render their banners the same way.
 
-Every mode except `raw` starts with banners computed by §5:
+Every mode except `raw` starts with banners computed by §5 (a `raw` read
+still carries them in the structured result, but its text is the file alone):
 
 ```
 ⚠ SUPERSEDED by "Use SQLite FTS5 for local search" (topics/search/fts5.md), 2026-10-09
@@ -504,7 +505,7 @@ included in full:
 5. Recent changes: the last 5 `log.md` entries, one line each, and the number
    of notes updated in the last 7 days.
 6. Inbox status: pending episode count, oldest pending age, rule proposals
-   awaiting `brain rule accept`, and a hint to consolidate when 20 or more
+   awaiting `brain rules accept`, and a hint to consolidate when 20 or more
    episodes are pending or the oldest is more than 7 days old.
 7. How to query: three example calls built from this brain's own topics and
    types (a keyword search, a typed "latest" lookup, and a `why` search).
@@ -515,6 +516,9 @@ The same function generates the managed block of `AGENTS.md`.
 
 | Query | Used by | Notes |
 |---|---|---|
+| Notes within filters, newest first | `brain_search("")`, `brain search ""` (e.g. `--since 7d`, `--topic T`) | The search path without text matching (§6.1); there is no separate listing command |
+| Headings, claims, and relations of a note | read (`outline`), `brain read TARGET --mode outline` | §7 |
+| Links as written in a file, and in other files | `brain links`, `brain backlinks` | Edges by the file that declares them (`declared_in`), resolved or not; `brain neighbors` follows them by meaning instead (§9.2) |
 | Backlinks of a node | read (`outline`), neighbors, lint orphans | All edges with `dst = node` |
 | Facet counts | orientation, search `facets`, `brain tags`, `brain types` | Counts by type, topic, tag, and property |
 | Orphans, dead ends, unresolved links | `brain orphans`, `brain unresolved`, reports | Nodes without incoming edges; nodes without outgoing edges; links that resolve to nothing |
@@ -525,7 +529,7 @@ The same function generates the managed block of `AGENTS.md`.
 
 ### 9.1 Brain list
 
-`brain_list` (CLI `brain list`) answers "which brains exist, and what is
+`brain_list` (CLI `brain brains`) answers "which brains exist, and what is
 each for?" for the calling host:
 
 | Field | Source |

{brain_wiki-0.1.0.dev0 → brain_wiki-0.1.0.dev1}/docs/design/05-write-path-and-consolidation.md

@@ -107,7 +107,7 @@ discover ─► filter ─► route ─► extract ─► distill (or raw) ─
 |---|---|
 | Discover | A per-host session reader lists sessions with id, working directory, start and last-modified time, size, and whether it is a subagent ([08 §6.4](08-agent-integrations.md#64-session-readers)). |
 | Filter | Skip subagent sessions, brain-wiki's own headless runs, sessions idle for less than `min_idle_minutes` (still in progress), and sessions with fewer than `min_user_turns` user messages. |
-| Route | Each session belongs to the brain of its working directory, checked in order: the first matching pattern in `[harvest.routes]`, a project file (`.brain-wiki.toml`), the brain folder it is inside, then the host's `brain` ([03 §3](03-config-and-storage.md#3-choosing-a-brain)). Sessions that resolve to no brain are skipped, never sent to the default brain. |
+| Route | Each session belongs to the brain of its working directory, checked in order: a project file (`.brain-wiki.toml`), the brain folder it is inside, the first matching pattern in `[harvest.routes]` (`brain harvest route PATTERN BRAIN` adds one and keeps longer patterns first, so a specific folder still wins over `~/**`), then the host's `brain`. Routes come after what the folder itself says, so a catch-all never overrides a project's own brain ([03 §3](03-config-and-storage.md#3-choosing-a-brain)). Sessions that resolve to no brain are skipped, never sent to the default brain. |
 | Extract | Normalize turns (user text, assistant text, tool calls by name and short argument summary). Tool output bodies are dropped. Text the host injected into turns (reminders, command echoes) is stripped. Secrets are scrubbed. Inputs are computed from the tool calls. |
 | Distill | One call to the configured headless preset ([08 §7](08-agent-integrations.md#7-headless-presets)) with the distill instructions (`prompts/distill.md`): the model returns `{skip, summary, claims[{text, turns}], negative_findings, open_questions, topics}`. Long sessions are split into chunks of at most 30k tokens, one episode per chunk. With `--raw`, no model is called and the episode holds a condensed transcript excerpt instead; consolidation distills it later. |
 | Write | Episodes with `bw-captured: harvest`, `bw-agent`, `bw-session`, `bw-turns`, `bw-device`, and the computed `bw-inputs`. The dedupe key `<host>:<session>:<turn range>` makes a repeated harvest write nothing new. |
@@ -138,9 +138,13 @@ The in-agent recipe is off by default and enabled per host (`[harvest]
 enabled` and `hosts` in the user config, plus `harvest` in the host's
 profile `write` list). `brain harvest` in a terminal is the owner's
 command and needs neither; every CLI run starts as a dry run that lists the sessions
-it would read, the brain each routes to, and an estimate of tokens for
-distillation; `--apply` executes. A backend only receives sessions routed
-to a brain; unrouted sessions are skipped.
+it would read (full session id and the folder it ran in), the brain each
+routes to, and an estimate of tokens for distillation; `--apply` executes,
+and `--apply --dry-run` lists the turn ranges it would write as episodes,
+per session, and writes nothing. `--from` with an unknown host, or one
+without a session reader, is a usage error, as it is for `brain harvest
+enable`. A backend only receives sessions routed to a brain; unrouted
+sessions are skipped.
 
 ### 2.3 Checked agent edits
 
@@ -167,7 +171,8 @@ recorded version:
 | Links and relations | A relation does not parse or names an unknown `bw-` field (error), or a new link does not resolve (warning) |
 | Claims | Claim metadata is broken, or a claim was deleted or reworded in place. Claims change only by superseding (move the old claim to `bw-claims-superseded`, add the new one), so a fact's history is never lost |
 | Claim provenance | An agent changed an existing claim's `origin`, `inputs`, or `src`. Only brain-wiki and the user set provenance |
-| Loss guard | Much of a note's text disappeared in one edit: a warning above 10%, an error above 50% unless `--allow-shrink` |
+| Loss guard | Much of a note's text disappeared in one edit: a warning above 10%, an error above 50% unless `--allow-shrink` (MCP `allow_shrink`) |
+| Lint | The edit introduces a strict lint error: file rules on the new content, and cross-file rules (a `by:` naming no claim, a supersession cycle) reported on lines the edit added or changed. Warnings and info are shown with their own severity and do not block |
 | Protected files | Any of the files above changed |
 | Sync debris | Merge-conflict markers or sync-conflict copies |
 
@@ -177,20 +182,23 @@ it; `log.md` gains a line; the brain's git repo, if any, gets a commit;
 author `agent:<host>`. Claims the edit added get `origin: agent` and
 `inputs: unknown`, whatever the agent wrote (an edit cannot show what else
 happened in the session), so they show as unverified until the user edits
-them; consolidation keeps the worse value when it merges. A
-failed check records nothing and returns every problem with its line; the
+them; consolidation keeps the worse value when it merges. Claims the user
+adds are left as written. A failed check records nothing and returns every problem with its line; the
 agent fixes the file and checks again, or `brain restore <path>` puts back
 the last recorded version.
 
 **The last recorded version.** The index keeps, for each note, the content
 it had when a run last wrote it, when `brain check` last recorded it, or
-when the index was first built. A note created outside brain-wiki after
-that is recorded as absent, so it shows as a pending creation. A note whose
+when the index was first built: every note found before the first full
+scan completes counts as the starting version, even when a write (a first
+`brain log` or rule change) indexed some files before that scan. A note
+created outside brain-wiki after that is recorded as absent, so it shows as a pending creation. A note whose
 file differs from its recorded version has a *pending edit*. `brain check`
 with no paths lists pending edits with their diffs; `brain check --adopt
 PATH` records a pending edit as the user's (author `owner`) even when checks
 report problems, which is how hand edits made outside brain-wiki can be
-given an undo point. Pending edits are not lint errors: humans edit their
+given an undo point. Adopting cannot record a protected file or a file that
+is not a note, so a failed check suggests `--adopt` only when it would help. Pending edits are not lint errors: humans edit their
 notes freely, and nothing nags them. A rename by hand carries the recorded
 version to the new path. The recorded versions survive index rebuilds,
 since they are the only record of unchecked edits; only a lost index starts
@@ -285,7 +293,7 @@ rolled back from in-memory pre-images before the lock is released.
 | Trigger | Backend | How |
 |---|---|---|
 | User asks their agent ("consolidate my brain") | `agent` | The skill drives `brain_consolidate_prepare` / `brain_consolidate_apply` over MCP. |
-| User drives it from a terminal | `agent` | `brain consolidate --prepare` writes the packet and instructions; any model or person produces the ops; `brain consolidate --apply OPS.json --run RUN` validates and applies them. |
+| User drives it from a terminal | `agent` | `brain consolidate --prepare` prints the instructions and packet (`--out FILE` writes the same JSON document `--json` prints: `run`, `instructions`, `packet`); any model or person produces the ops; `brain consolidate --apply OPS.json --run RUN` validates and applies them. Exit codes follow [07 §2.3](07-interfaces.md#23-exit-codes): 0 applied or dry run, 1 invalid ops (including a file that is not JSON) or routed to review, 4 stale (prepare again). |
 
 v0.1 never consolidates on its own in the background. Running an LLM costs
 money and attention, and the user should choose when. Scheduled, headless
@@ -509,12 +517,20 @@ session. They get the strictest path.
 
 | Path | Flow |
 |---|---|
-| `brain rule add "…"` | The person running the CLI is the user. Written immediately, `origin: owner`, `quote` defaults to the text. |
-| MCP `brain_propose_rule {text, user_quote, replaces?}` | Requires `propose_rules` in the profile's `write` list. The server asks the user to confirm, showing the exact rule: through an input-required result carrying an elicitation request on 2026-07-28 connections, or a pushed elicitation on older sessions, whichever the client advertises. The tool is also annotated as destructive and, for hosts that honor it, as requiring user interaction (`_meta["anthropic/requiresUserInteraction"]`), so the call itself is approved by the user. Confirmed → written with `origin: owner`, `via: mcp`. Declined → nothing. If the client supports neither form of confirmation, the rule is written as a proposal (`inbox/proposals/rule-<id>.md`) and orientation shows "1 rule awaiting confirmation: `brain rule accept <id>`". |
+| `brain rules add "…"` | The person running the CLI is the user. Written immediately, `origin: owner`, `quote` defaults to the text. With `--as <host>`, it needs `propose_rules` and is saved as a proposal instead ([07 §1](07-interfaces.md#1-agent-profiles)). |
+| MCP `brain_propose_rule {text, user_quote, replaces?}` | Requires `propose_rules` in the profile's `write` list. The server asks the user to confirm, showing the exact rule: through an input-required result carrying an elicitation request on 2026-07-28 connections, or a pushed elicitation on older sessions, whichever the client advertises. The tool is also annotated as destructive and, for hosts that honor it, as requiring user interaction (`_meta["anthropic/requiresUserInteraction"]`), so the call itself is approved by the user. Confirmed → written with `origin: owner`, `via: mcp`. Declined → nothing. If the client supports neither form of confirmation, the rule is written as a proposal (`inbox/proposals/rule-<id>.md`) and orientation shows "1 rule awaiting confirmation: `brain rules accept <id>`". |
 | Consolidation | Never. If an episode looks like a preference ("user prefers X"), the instructions say to record it as a claim in a `preferences` topic; promoting it to a rule is a separate, user-confirmed step. |
 
 Replacing a rule (`replaces: r-…`) moves the old line to `archive/rules.md`.
 Budget overflow is an error that tells the user which rules are longest.
+Adding, proposing, or accepting a rule is refused with `not_found` when
+`replaces` names no rule, and with `conflict` when an existing rule already
+says the same thing (compared ignoring case and spacing).
+
+A proposal is known by its file name (`rule-<id>.md`): `brain rules list`
+and `brain review list` show that id, and the rule it replaces, and `accept`
+and `reject` take it (`brain rules accept ID` or `brain review accept ID`).
+Accepting and rejecting are the user's decisions: no profile allows them.
 
 ## 7. Validation and apply
 
@@ -531,7 +547,7 @@ Budget overflow is an error that tells the user which rules are longest.
 | V7 | Completeness: episodes neither cited nor skipped. | Not an error: they stay pending and the run reports them. |
 | V8 | **Supersession ratio**: for a note with ≥ 4 active claims, superseded + retracted in this run ÷ active before > `max_supersede_ratio`. | Run is routed to review. |
 | V9 | **Specificity warning**: a superseding claim drops anchors (numbers, dates, versions, URLs, code spans, wikilinks) that appear in the old claim. | Warning in the run record and review file. Not blocking: changing a value is the point of superseding, and the old text is kept. |
-| V10 | Any touched topic has `review = "always"`, or sources include `inputs` ≠ `local` and `review_external = true` (default `false`). | Run is routed to review. |
+| V10 | Any topic an op writes into has `review = "always"` (a note's own topic for claim ops and relations, the target's too for `supersedes`, the topic of a created note, and the parent of a created sub-topic, whose policy it inherits), or sources include `inputs` ≠ `local` and `review_external = true` (default `false`). | Run is routed to review. |
 | V11 | Lint (strict) on every touched file after the in-memory apply; errors already present before the run do not count. | Invalid; nothing is written. |
 
 **Why not a content-loss threshold on whole files?** Because the writer
@@ -546,12 +562,31 @@ summary, the rendered diff, warnings, and the ops as a fenced JSON block.
 Nothing else changes; the episodes stay pending (and are excluded from new
 packets while a proposal references them).
 
-- `brain review list | show <run> | accept <run> | reject <run>`. Review is
-  CLI-only: there are no MCP review tools, so an agent can point the user
+- `brain review list | show <id> | accept <id> | reject <id>`, the one queue
+  for consolidation and edit proposals (`run-…`) and rule proposals (§6);
+  `list` marks each proposal's kind. Review is CLI-only: there are no MCP review tools, so an agent can point the user
   at a proposal but cannot accept it (MCP review tools are in the
   [backlog](../proposals/README.md#backlog)).
 - Accept re-validates the stored ops against the current brain (notes may
-  have changed) and applies them as a normal run.
+  have changed) and applies them as a normal run. The proposal is a file
+  anything with access to the brain can write, so the packet embedded in it
+  is never trusted: accept rebuilds the packet from the current brain with
+  the code `prepare` uses, keeping only which handle names which note,
+  claim, and episode (from the packet saved in `<state>/runs/<run>/` when
+  this device prepared the run, else from the proposal). Every note must be
+  a note or hub outside `rules.md`, `log.md`, `brain.toml`, `AGENTS.md`,
+  `inbox/`, `archive/`, and `reports/`, at the path and id the proposal
+  names; every episode a pending one whose archive target is its computed
+  archive location. A proposal that names anything else is refused with a
+  `format` error (exit 1) and nothing is written. Hashes, line ranges,
+  provenance (`origin`, `inputs`), and topic review policies come from the
+  files. A note, claim, or episode the ops use that has changed or gone
+  makes the accept stale (exit 4): reject the proposal and consolidate
+  again.
+- `show` prints what accepting would do, computed the same way: the review
+  reasons, one line per op with handles resolved to paths, and the diff
+  against the brain as it is now (or why accepting would fail). It never
+  prints the packet.
 - Proposals are files in the brain, so they sync to the user's other
   devices and can be reviewed in Obsidian.
 
@@ -599,16 +634,21 @@ Pre-images are stored next to it (`preimages/<sha256>`, gzip).
 
 `brain undo [<run>]` (default: the latest applied run on this device):
 
-- **Git brains:** if the run's commit exists, `git revert --no-edit <commit>`.
-  Revert merges with later edits; a conflict aborts the revert and reports
-  the files, leaving the tree as it was.
-- **Other brains:** for each file, if its current hash equals `after`,
-  restore the pre-image (or delete it if `before` is null) and move episodes
-  back. If any file changed since the run, refuse and list them. `--force`
-  saves the current versions under `<state>/runs/<run>/conflicts/` first.
-- Undo is itself recorded (`kind: undo`) and logged in `log.md`.
-
-Retention: the last 200 runs or 90 days, whichever keeps more.
+- For each file, if its current hash equals `after`, restore the pre-image
+  (or delete it if `before` is null) and move episodes back. `log.md` is
+  append-only and not restored. If any file changed since the run, refuse
+  and list them; files no later run touched do not block, so an older run
+  can be undone. `--force` saves the current versions under
+  `<state>/runs/<run>/conflicts/` first.
+- Undo is itself a run (`kind: undo`, §7.3): logged in `log.md` and, in a
+  git brain, committed with exactly the restored files, deletions included.
+- Git is never the source of what to restore, the pre-images are: a run can
+  touch files git never saw (an uncommitted episode, a proposal), and a
+  `git revert` of an older run conflicts on `log.md`.
+
+Retention: the last 200 runs or 90 days, whichever keeps more. Older runs can no
+longer be undone by `brain undo`; in a git brain, their commits can still be reverted
+with git.
 
 ## 9. Concurrency and multiple devices
 

{brain_wiki-0.1.0.dev0 → brain_wiki-0.1.0.dev1}/docs/design/06-lint-and-reports.md

@@ -163,12 +163,15 @@ check`, not by lint, so hand edits never raise warnings.
 converting frontmatter relations, listing notes in hubs) run only when
 their codes are selected with `--select`, because they are suggestions, not
 repairs. `--select` and `--ignore` take codes or prefixes (`BW3`, `BW405`)
-for checks and fixes alike. Rules:
+for checks and fixes alike; one that matches no rule is a usage error, so a
+typo cannot pass as "no problems". Rules:
 
 - A fix changes only the lines it must (02 §4). It never reflows prose.
 - All fixes in one invocation form one run with an undo record, one
   `log.md` entry, and one git commit if git mode is on.
-- `--fix --dry-run` prints the diff.
+- `--fix --dry-run` prints the diff; `--dry-run` alone is a usage error.
+- `--fix` changes files, so under `--as <host>` it needs the `edit`
+  capability ([07 §1](07-interfaces.md#1-agent-profiles)).
 - Fixes that need judgment (resolving an ambiguous link, removing a
   secret, choosing between conflict copies) are never automatic.
 
@@ -184,6 +187,10 @@ topics/search/fts5.md
 2 problems (1 error, 1 warning), 1 fixable with --fix
 ```
 
+The "fixable with --fix" count is what `--fix` with the same options would
+repair. Fixable `info` problems are counted after it, with the selection
+that turns them on: `; 2 more with --fix --select BW205,BW405`.
+
 `--json` emits a list of `{code, severity, path, line, message, fixable}`.
 Exit codes: `0` no errors, `1` errors found, `2` usage error; the rest as in
 [07 §2.3](07-interfaces.md#23-exit-codes).
@@ -214,8 +221,13 @@ churn on every run.
 ## 8. Pre-commit integration
 
 - `brain lint --install-hook` writes a small `.git/hooks/pre-commit` in the
-  brain that runs `brain lint --staged`. It refuses to overwrite an
-  existing hook and prints how to chain it instead.
+  brain that runs `brain lint --staged`. Run again, it reports the hook as
+  already installed. It refuses to overwrite any other existing hook and
+  prints how to chain it instead.
+- The hook also checks brain-wiki's own run commits. When it (or anything
+  else) makes git refuse one, the run stays applied, its files stay staged,
+  and the command prints git's message on stderr with how to finish: fix the
+  problem, then `git commit`.
 - The repository also ships `.pre-commit-hooks.yaml` so users of the
   pre-commit framework can add `brain-lint` to their own config.