Support external vault roots across tooling

README.md

@@ -44,6 +44,54 @@ make graph                   # generate index/graph.json and validate it
 make test                    # run the tooling tests
 ```
 
+## External data vault
+
+Keep this repository as the control plane (tools, skills, agents, hooks, tests,
+operational documentation), and store notes in a separate data repository.
+The empty PARA skeleton also supports self-contained use.
+
+All Python commands select data with `--vault-root`, then the
+`KNOWLEDGE_BASE_ROOT` environment variable, then this framework's root.
+An explicit root must be an existing directory; Git operations require it to
+be the Git repository root. The working directory does not select the vault.
+
+```sh
+python3 /path/to/framework/scripts/mcp-server.py --vault-root /path/to/vault
+make -C /path/to/framework graph VAULT_ROOT=/path/to/vault
+make -C /path/to/framework install-hooks VAULT_ROOT=/path/to/vault
+make -C /path/to/framework install-mcp-claude VAULT_ROOT=/path/to/vault
+```
+
+`VAULT_ROOT` defaults to `KNOWLEDGE_BASE_ROOT`, then the framework directory.
+The hook installer honors Git's hooks directory (including worktrees and
+`core.hooksPath`), preserves unmanaged hooks, and writes a wrapper pointing at
+framework tooling. Reinstall after moving the framework or vault. The hook
+regenerates and validates the selected vault, then rejects unstaged graph changes.
+
+Configure each stdio MCP client with command `python3` and arguments
+`["/path/to/framework/scripts/mcp-server.py", "--vault-root", "/path/to/vault"]`.
+MCP reads, writes and Git operations use that vault; `refresh_graph` invokes
+the framework generator by absolute path and writes the selected graph even
+when validation is requested. A README resource is advertised only if present.
+
+Global skill and agent symlinks must point into this framework. MCP is their
+only interface for vault access; unavailable operations are reported without
+shell fallback. The CLI examples here are for operators. No personal taxonomy is assumed.
+Agents call `read_instructions` to load framework `AGENTS.md` and
+`AGENT_QUERY_GUIDE.md` even before a data graph exists. This read-only tool
+returns those two framework documents; `read_note` remains vault-scoped.
+
+For migration, test the external root first, back up MCP configurations and
+symlink targets, cut clients and hooks over, then smoke-test initialize,
+tools/list, graph_summary, search, read and refresh. Only remove old tool copies
+after this passes. On failure restore the configs and symlinks and retain the
+old copies. Restart existing clients to load the new server command.
+
+A minimal data repository contains `01_projects/` through `04_archives/`,
+`index/graph.json` and repository hygiene. Before removing a root hub, replace
+its inbound links with links between PARA hubs and validate the graph. Preserve
+untracked files separately from the tracked-file cleanup.
+
 ## Generation
 - Run `make graph`
 - Output is written to `index/graph.json`