brainkeeper 0.2.2__tar.gz → 0.3.0__tar.gz

{brainkeeper-0.2.2 → brainkeeper-0.3.0}/CHANGELOG.md

@@ -9,6 +9,19 @@ Two artifacts are versioned independently:
 - **`spec-vX.Y.Z`**: the brainkeeper specification (`spec/`).
 - **`brainkeeper-vX.Y.Z`**: the `brainkeeper` Python package, which contains the vault engine library, the MCP server, and the CLI.
 
+## [brainkeeper-v0.3.0] - 2026-07-06
+
+> ⚠️ **Breaking release.** The vault location changes: it is now fixed at `~/.brainkeeper/vault`, deliberately not configurable. Existing vaults must be moved into place and `--vault` flags removed (see Migration below).
+
+### Changed
+- **Breaking:** `serve` loses `--vault`. The server always serves `~/.brainkeeper/vault`; if it doesn't exist, `serve` exits with an error pointing at `brainkeeper init`.
+- **Breaking:** `init` loses its `path` positional. It always scaffolds `~/.brainkeeper/vault`.
+- New `brainkeeper.cli.vault_path()` helper: the single source of truth for the fixed vault location.
+
+### Migration
+- Move any existing vault into place instead of running `init` (the target must not exist yet): `mkdir -p ~/.brainkeeper && mv ~/MyVault ~/.brainkeeper/vault`.
+- Remove `--vault` from every MCP client entry that references `brainkeeper serve`. The command is now just `uvx brainkeeper serve`.
+
 ## [brainkeeper-v0.2.2] - 2026-05-05
 
 ### Fixed
@@ -136,6 +149,7 @@ First public release of the `brainkeeper` Python package. Implements spec v0.1.4
 - Archive semantics narrowed to completed projects only; retired Areas are deleted or distilled into Brain, not archived.
 - Domain tags: cardinality relaxed to 0..n (optional but recommended); vocabulary derived from folders under `projects/` and `areas/` rather than an enumerated list in the config.
 
+[brainkeeper-v0.3.0]: https://github.com/dasirra/brainkeeper/releases/tag/brainkeeper-v0.3.0
 [brainkeeper-v0.2.2]: https://github.com/dasirra/brainkeeper/releases/tag/brainkeeper-v0.2.2
 [brainkeeper-v0.2.1]: https://github.com/dasirra/brainkeeper/releases/tag/brainkeeper-v0.2.1
 [spec-v0.2.0]: https://github.com/dasirra/brainkeeper/releases/tag/spec-v0.2.0

{brainkeeper-0.2.2 → brainkeeper-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainkeeper
-Version: 0.2.2
+Version: 0.3.0
 Summary: Structured Markdown vault standard with a Python vault engine and MCP interface
 Project-URL: Homepage, https://github.com/dasirra/brainkeeper
 Project-URL: Repository, https://github.com/dasirra/brainkeeper
@@ -94,15 +94,22 @@ Either way, you need Python 3.11 or newer.
 If you don't already have a brainkeeper vault, create one:
 
 ```bash
-uvx brainkeeper init ~/MyVault
+uvx brainkeeper init
 ```
 
-This creates the six layer directories and drops a `brainkeeper.yaml` (the minimal reference config) at the vault root. Open the YAML to adjust folder names and area substructure to taste. Validate against the schema at any time:
+This scaffolds the vault at `~/.brainkeeper/vault`: the six layer directories plus a `brainkeeper.yaml` (the minimal reference config) at the vault root. Open the YAML to adjust folder names and area substructure to taste. Validate against the schema at any time:
 
 ```bash
 uvx check-jsonschema \
   --schemafile https://raw.githubusercontent.com/dasirra/brainkeeper/main/spec/schema/brainkeeper.schema.json \
-  ~/MyVault/brainkeeper.yaml
+  ~/.brainkeeper/vault/brainkeeper.yaml
+```
+
+Already have a vault elsewhere? Move it into place instead of running `init` (the target must not exist yet):
+
+```bash
+mkdir -p ~/.brainkeeper
+mv ~/MyVault ~/.brainkeeper/vault
 ```
 
 ### 3. Configure your MCP client
@@ -112,7 +119,7 @@ The MCP server is launched by your LLM harness over stdio. Pick the snippet for
 **Claude Code** (one command):
 
 ```bash
-claude mcp add --scope user brainkeeper -- uvx brainkeeper serve --vault ~/MyVault
+claude mcp add --scope user brainkeeper -- uvx brainkeeper serve
 ```
 
 **Claude Desktop**: edit the config file at
@@ -127,15 +134,15 @@ and add:
   "mcpServers": {
     "brainkeeper": {
       "command": "uvx",
-      "args": ["brainkeeper", "serve", "--vault", "/Users/you/MyVault"]
+      "args": ["brainkeeper", "serve"]
     }
   }
 }
 ```
 
-Then restart Claude Desktop. Use an absolute path; `~` is not expanded inside this JSON.
+Then restart Claude Desktop.
 
-**Other clients**: any MCP-capable harness that speaks stdio works. The command is `uvx brainkeeper serve --vault /absolute/path/to/vault` (or `brainkeeper serve --vault ...` if you `pip install`ed).
+**Other clients**: any MCP-capable harness that speaks stdio works. The command is `uvx brainkeeper serve` (or `brainkeeper serve` if you `pip install`ed).
 
 ### 4. Verify
 
@@ -206,7 +213,7 @@ The current spec version is **v0.1.4**. See [`CHANGELOG.md`](https://github.com/
 
 This is the first public release. Known constraints:
 
-- **One vault per server instance.** Each MCP process serves a single `--vault`. Multi-vault setups need multiple server entries in your client config.
+- **One vault per server instance.** The server always serves the fixed vault at `~/.brainkeeper/vault`. Multiple vaults are not supported.
 - **`move_note` does not rewrite wikilinks.** Inbound links to a moved note become stale until you fix them manually. Planned for a later release.
 - **No always-on indexing.** The MCP runs only while its host (Claude Code, Claude Desktop, etc.) is running. There is no background daemon.
 - **The MCP encodes the spec contract.** If you let an LLM use raw filesystem tools (Read, Write, Edit) on the vault path, it will produce notes that violate the frontmatter contract or land in the wrong layer. Tell your agent to use only the brainkeeper tools when working inside the vault.

{brainkeeper-0.2.2 → brainkeeper-0.3.0}/README.md

@@ -58,15 +58,22 @@ Either way, you need Python 3.11 or newer.
 If you don't already have a brainkeeper vault, create one:
 
 ```bash
-uvx brainkeeper init ~/MyVault
+uvx brainkeeper init
 ```
 
-This creates the six layer directories and drops a `brainkeeper.yaml` (the minimal reference config) at the vault root. Open the YAML to adjust folder names and area substructure to taste. Validate against the schema at any time:
+This scaffolds the vault at `~/.brainkeeper/vault`: the six layer directories plus a `brainkeeper.yaml` (the minimal reference config) at the vault root. Open the YAML to adjust folder names and area substructure to taste. Validate against the schema at any time:
 
 ```bash
 uvx check-jsonschema \
   --schemafile https://raw.githubusercontent.com/dasirra/brainkeeper/main/spec/schema/brainkeeper.schema.json \
-  ~/MyVault/brainkeeper.yaml
+  ~/.brainkeeper/vault/brainkeeper.yaml
+```
+
+Already have a vault elsewhere? Move it into place instead of running `init` (the target must not exist yet):
+
+```bash
+mkdir -p ~/.brainkeeper
+mv ~/MyVault ~/.brainkeeper/vault
 ```
 
 ### 3. Configure your MCP client
@@ -76,7 +83,7 @@ The MCP server is launched by your LLM harness over stdio. Pick the snippet for
 **Claude Code** (one command):
 
 ```bash
-claude mcp add --scope user brainkeeper -- uvx brainkeeper serve --vault ~/MyVault
+claude mcp add --scope user brainkeeper -- uvx brainkeeper serve
 ```
 
 **Claude Desktop**: edit the config file at
@@ -91,15 +98,15 @@ and add:
   "mcpServers": {
     "brainkeeper": {
       "command": "uvx",
-      "args": ["brainkeeper", "serve", "--vault", "/Users/you/MyVault"]
+      "args": ["brainkeeper", "serve"]
     }
   }
 }
 ```
 
-Then restart Claude Desktop. Use an absolute path; `~` is not expanded inside this JSON.
+Then restart Claude Desktop.
 
-**Other clients**: any MCP-capable harness that speaks stdio works. The command is `uvx brainkeeper serve --vault /absolute/path/to/vault` (or `brainkeeper serve --vault ...` if you `pip install`ed).
+**Other clients**: any MCP-capable harness that speaks stdio works. The command is `uvx brainkeeper serve` (or `brainkeeper serve` if you `pip install`ed).
 
 ### 4. Verify
 
@@ -170,7 +177,7 @@ The current spec version is **v0.1.4**. See [`CHANGELOG.md`](https://github.com/
 
 This is the first public release. Known constraints:
 
-- **One vault per server instance.** Each MCP process serves a single `--vault`. Multi-vault setups need multiple server entries in your client config.
+- **One vault per server instance.** The server always serves the fixed vault at `~/.brainkeeper/vault`. Multiple vaults are not supported.
 - **`move_note` does not rewrite wikilinks.** Inbound links to a moved note become stale until you fix them manually. Planned for a later release.
 - **No always-on indexing.** The MCP runs only while its host (Claude Code, Claude Desktop, etc.) is running. There is no background daemon.
 - **The MCP encodes the spec contract.** If you let an LLM use raw filesystem tools (Read, Write, Edit) on the vault path, it will produce notes that violate the frontmatter contract or land in the wrong layer. Tell your agent to use only the brainkeeper tools when working inside the vault.

{brainkeeper-0.2.2 → brainkeeper-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brainkeeper"
-version = "0.2.2"
+version = "0.3.0"
 description = "Structured Markdown vault standard with a Python vault engine and MCP interface"
 readme = "README.md"
 license = { text = "MIT" }

{brainkeeper-0.2.2 → brainkeeper-0.3.0}/src/brainkeeper/__init__.py

@@ -1,3 +1,3 @@
 """brainkeeper: structured Markdown vault standard with engine, MCP, and CLI."""
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"

{brainkeeper-0.2.2 → brainkeeper-0.3.0}/src/brainkeeper/cli/__init__.py

@@ -9,6 +9,12 @@ from . import serve as _serve
 from . import init as _init
 
 
+def vault_path() -> Path:
+    """Fixed vault location: the single source of truth."""
+    # resolve() keeps the watcher/index path keys canonical under symlinked homes
+    return (Path.home() / ".brainkeeper" / "vault").resolve()
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="brainkeeper",
@@ -17,28 +23,20 @@ def main(argv: list[str] | None = None) -> int:
     sub = parser.add_subparsers(dest="command", metavar="COMMAND")
 
     sp_serve = sub.add_parser("serve", help="Start the MCP server")
-    sp_serve.add_argument(
-        "--vault",
-        type=Path,
-        required=True,
-        help="Path to vault root containing brainkeeper.yaml",
-    )
     sp_serve.add_argument("-v", "--verbose", action="store_true")
 
-    sp_init = sub.add_parser("init", help="Bootstrap a new vault")
-    sp_init.add_argument(
-        "path", type=Path, help="Path for the new vault root (created if absent)"
-    )
+    sub.add_parser("init", help="Bootstrap the vault at ~/.brainkeeper/vault")
 
     args = parser.parse_args(argv)
 
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    args.vault = vault_path()
     if args.command == "serve":
         return _serve.run(args)
-    if args.command == "init":
-        return _init.run(args)
-
-    parser.print_help()
-    return 0
+    return _init.run(args)
 
 
 if __name__ == "__main__":

{brainkeeper-0.2.2 → brainkeeper-0.3.0}/src/brainkeeper/cli/init.py

@@ -31,11 +31,18 @@ def _find_minimal_yaml() -> Path:
 
 
 def run(args) -> int:
-    vault = args.path.expanduser().resolve()
-    vault.mkdir(parents=True, exist_ok=True)
-
-    for layer in _LAYER_DIRS:
-        (vault / layer).mkdir(exist_ok=True)
+    vault = args.vault
+    try:
+        vault.mkdir(parents=True, exist_ok=True)
+        for layer in _LAYER_DIRS:
+            (vault / layer).mkdir(exist_ok=True)
+    except (FileExistsError, NotADirectoryError):
+        print(
+            f"error: cannot create {vault}: a file is in the way. "
+            "Remove it and re-run `brainkeeper init`.",
+            file=sys.stderr,
+        )
+        return 1
 
     config_path = vault / "brainkeeper.yaml"
     if config_path.exists():

{brainkeeper-0.2.2 → brainkeeper-0.3.0}/src/brainkeeper/cli/serve.py

@@ -13,9 +13,12 @@ def run(args) -> int:
         format="%(asctime)s %(levelname)s %(name)s: %(message)s",
         stream=sys.stderr,
     )
-    vault = args.vault.expanduser().resolve()
+    vault = args.vault
     if not vault.is_dir():
-        print(f"error: vault path is not a directory: {vault}", file=sys.stderr)
+        print(
+            f"error: no vault at {vault}. Run `brainkeeper init` to create it.",
+            file=sys.stderr,
+        )
         return 1
     srv = BrainkeeperServer(vault)
     srv.run_stdio()

brainkeeper-0.3.0/tests/unit/test_cli.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+from brainkeeper.cli import main
+
+_LAYER_DIRS = [
+    "00 Inbox",
+    "10 Journal",
+    "20 Projects",
+    "30 Areas",
+    "40 Brain",
+    "90 Archive",
+]
+
+
+def test_init_creates_layers_and_config(tmp_path: Path, monkeypatch):
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    assert main(["init"]) == 0
+    vault = tmp_path / ".brainkeeper" / "vault"
+    for layer in _LAYER_DIRS:
+        assert (vault / layer).is_dir()
+    assert (vault / "brainkeeper.yaml").exists()
+
+
+def test_reinit_warns_and_preserves_config(tmp_path: Path, monkeypatch, capsys):
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    main(["init"])
+    config_path = tmp_path / ".brainkeeper" / "vault" / "brainkeeper.yaml"
+    config_path.write_text("# user edit\n")
+
+    assert main(["init"]) == 0
+    assert "already exists" in capsys.readouterr().err
+    assert config_path.read_text() == "# user edit\n"
+
+
+def test_serve_missing_vault_exits_1(tmp_path: Path, monkeypatch, capsys):
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    assert main(["serve"]) == 1
+    assert "brainkeeper init" in capsys.readouterr().err
+
+
+def test_init_blocked_by_file_exits_1(tmp_path: Path, monkeypatch, capsys):
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    (tmp_path / ".brainkeeper").write_text("not a directory\n")
+    assert main(["init"]) == 1
+    assert "error" in capsys.readouterr().err

{brainkeeper-0.2.2 → brainkeeper-0.3.0}/uv.lock

@@ -78,7 +78,7 @@ wheels = [
 
 [[package]]
 name = "brainkeeper"
-version = "0.2.2"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "fastmcp" },