Release 0.30.0

.github/scripts/validate-mcp-registry.mjs

@@ -205,15 +205,12 @@ function main() {
   const packageArguments = npmPackage.packageArguments ?? []
   assert.deepEqual(
     packageArguments.map((entry) => entry.value ?? entry.valueHint ?? null),
-    ['serve', '--stdio', 'graph_path'],
-    'server.json package arguments must model `madar serve --stdio <graph_path>`',
+    ['serve', '--stdio', '--auto-refresh'],
+    'server.json package arguments must model `madar serve --stdio --auto-refresh`',
   )
 
   const graphPathArgument = packageArguments.find((entry) => entry.valueHint === 'graph_path')
-  assert.ok(graphPathArgument, 'server.json must require a graph_path positional argument')
-  assert.equal(graphPathArgument.default, 'out/graph.json', 'graph_path should default to out/graph.json')
-  assert.equal(graphPathArgument.format, 'filepath', 'graph_path should be marked as a filepath input')
-  assert.equal(graphPathArgument.isRequired, true, 'graph_path should be required')
+  assert.equal(graphPathArgument, undefined, 'server.json must not pin the MCP server to a static graph_path argument')
 
   const toolProfile = (npmPackage.environmentVariables ?? []).find((entry) => entry.name === 'MADAR_TOOL_PROFILE')
   assert.ok(toolProfile, 'server.json must describe the MADAR_TOOL_PROFILE environment variable')

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to the TypeScript package will be documented in this file.
 
+## [0.30.0] - 2026-07-14
+
+### Added
+
+- **Installed MCP integrations now keep their graph current automatically**: newly generated Claude Code, Codex, Cursor, Copilot, Gemini, Aider, and OpenCode configurations launch `madar serve --stdio --auto-refresh`. The server reconciles the active workspace at startup, watches it while the agent session is active, and publishes refreshed graph artifacts atomically after source or relevant configuration changes. Re-run your agent's `madar <agent> install` command after upgrading to update an existing managed MCP entry. Closes #545.
+- **Linked Git worktrees now receive isolated Madar artifacts**: default graphs, caches, reports, compare output, and time-travel artifacts live outside a linked checkout in its repository's shared Git data directory, with a distinct artifact directory for each worktree. This prevents branches from sharing or overwriting graph state while keeping generated artifacts out of the checkout. Closes #546.
+
+### Notes
+
+- **An MCP server is scoped to the worktree it started in**: start or reconnect the agent/MCP server from the intended worktree. A running server cannot follow an agent that later changes directory or creates and moves into another worktree.
+
 ## [0.29.0] - 2026-07-12
 
 ### Added

README.md

@@ -95,6 +95,8 @@ madar opencode install
 
 After installing a profile, run `madar doctor` and `madar status`. Installer details are in the [CLI and MCP reference](https://github.com/mohanagy/madar/blob/main/docs/reference/cli-and-mcp.md).
 
+If you upgrade to `0.30.0` from an earlier version, run your profile's install command again (for example, `madar claude install` or `madar codex install`) to update its managed MCP entry with automatic refresh.
+
 ## Use Without MCP
 
 You can also generate context directly from the CLI:
@@ -138,9 +140,9 @@ It helps less when:
 - the task is obvious from one file
 - the question needs live runtime behavior
 - the code relies heavily on dynamic patterns static analysis cannot see
-- the generated graph is stale after large repo changes
+- you use a standalone graph without regenerating it after large repo changes
 
-If the repo changed a lot, regenerate:
+For standalone CLI workflows, regenerate after substantial repo changes:
 
 ```bash
 madar generate .
@@ -150,13 +152,21 @@ madar generate .
 
 Madar records graph freshness so agents can tell whether context still matches the repo. On git workspaces, freshness is tied to the graph build commit plus the working-tree diff, so unrelated changes do not have to block a focused task by default.
 
+Installed MCP profiles in `0.30.0` start `madar serve --stdio --auto-refresh`. Madar reconciles the graph when that server starts, then watches the active workspace and refreshes the graph after source or relevant configuration changes. You do not need to run `madar generate` after every agent edit or session; manual generation remains available for standalone CLI workflows.
+
 ```bash
 madar pack "how does auth work?" --require-fresh-context
 madar pack "how does auth work?" --require-fresh-graph
 ```
 
 Use `--require-fresh-context` when the selected files must be fresh. Use `--require-fresh-graph` when the whole graph must match the current repo.
 
+## Git Worktrees
+
+Run Madar and your coding agent from the same linked Git worktree. Madar keeps the default graph and related artifacts outside that checkout, under the repository's shared Git data directory, and gives each worktree its own isolated artifact directory. That keeps branches from sharing graph state and avoids generated `out/` artifacts inside linked worktrees.
+
+An MCP server selects its workspace when it starts. If an agent later creates or switches to another worktree, start or reconnect the agent/MCP server from that new worktree; a running server cannot follow a later directory change.
+
 ## Evidence
 
 Madar now has proof-backed public TypeScript `explain-runtime` legacy benchmark receipts across six open-source repos. Each row below has `benchmark_outcome = "full_win"`, `benchmark_readiness = "ready"`, `answer_quality.madar.passed = true`, and `answer_contract.runtime_proof.missing_obligations = []`.
@@ -200,13 +210,15 @@ It does not record prompt text, answer text, source paths, source content, or re
 
 ## What's New
 
-Current version: `0.29.0`.
+Current version: `0.30.0`.
+
+`0.30.0` makes installed MCP integrations self-refreshing: they reconcile the graph at startup and watch the active workspace through an agent session. It also gives each linked Git worktree isolated external graph and artifact storage. Start or reconnect MCP from the worktree the agent is using; a running server stays scoped to the worktree where it started.
 
 `0.29.0` adds full project-local Codex CLI wiring: `madar codex install` now owns a task-applicable `UserPromptSubmit` hook, its local script, and a marker-owned Madar MCP entry alongside the AGENTS profile. The hook provides guidance for local code tasks, not enforcement; review and trust it in Codex before relying on it.
 
 `0.28.0` promoted the public benchmark work to a proof-backed stable release: six public TypeScript `explain-runtime` legacy rows now have checked-in `full_win` receipts, strict runtime-proof gates, direct-evidence answer checks, scoped benchmark roots, and share-safe reports. It also includes retrieval and extraction improvements for runtime handoffs, source-visible framework flows, and benchmark reproducibility.
 
-Read the full notes in the [0.29.0 changelog](https://github.com/mohanagy/madar/blob/main/CHANGELOG.md#0290---2026-07-12).
+Read the full notes in the [0.30.0 changelog](https://github.com/mohanagy/madar/blob/main/CHANGELOG.md#0300---2026-07-14).
 
 ## Docs
 

docs/mcp-registry/server.json

@@ -9,13 +9,13 @@
         "source": "github",
         "url": "https://github.com/mohanagy/madar"
     },
-    "version": "0.29.0",
+    "version": "0.30.0",
     "packages": [
         {
             "registryType": "npm",
             "registryBaseUrl": "https://registry.npmjs.org",
             "identifier": "@lubab/madar",
-            "version": "0.29.0",
+            "version": "0.30.0",
             "runtimeHint": "npx",
             "transport": {
                 "type": "stdio"
@@ -31,11 +31,7 @@
                 },
                 {
                     "type": "positional",
-                    "valueHint": "graph_path",
-                    "description": "Path to out/graph.json. Run `madar generate .` first so the local MCP server has a graph artifact to serve.",
-                    "default": "out/graph.json",
-                    "format": "filepath",
-                    "isRequired": true
+                    "value": "--auto-refresh"
                 }
             ],
             "environmentVariables": [
@@ -53,7 +49,7 @@
     ],
     "_meta": {
         "io.modelcontextprotocol.registry/publisher-provided": {
-            "notes": "Public npm package plus local graph artifact install flow. Madar is the renamed continuation of `graphify-ts`; use `@lubab/madar` and `https://github.com/mohanagy/madar` as the canonical package and repository.",
+            "notes": "Public npm package plus local auto-refresh MCP flow. The registry starts `madar serve --stdio --auto-refresh` in the active workspace, so Madar builds and refreshes its local graph without a static graph-path argument. Madar is the renamed continuation of `graphify-ts`; use `@lubab/madar` and `https://github.com/mohanagy/madar` as the canonical package and repository.",
             "source": "docs/mcp-registry/server.json"
         }
     }

docs/reference/cli-and-mcp.md

@@ -43,7 +43,7 @@ The checked-in public registry manifest lives at [`docs/mcp-registry/server.json
 npm run registry:validate
 ```
 
-The official MCP Registry hosts metadata, not Madar code or your local graph artifact. Madar's registry entry points back to the public npm package and the same local-first runtime flow: run `madar generate .` to create `out/graph.json`, then start the local stdio server with `npx @lubab/madar serve --stdio out/graph.json`, or let `madar <agent> install` write that wiring for you. Generated Claude and Cursor MCP configs now call the installed `madar` command as `madar serve --stdio <absolute project graph path>` instead of writing a version-pinned `npx` launcher into the repo-local config.
+The official MCP Registry hosts metadata, not Madar code or your local graph artifact. Its entry starts `npx @lubab/madar serve --stdio --auto-refresh` from the active workspace: Madar creates the graph when needed, then refreshes it after local changes. Do not add a fixed `out/graph.json` argument to that registry command, because it would become stale and would not follow a linked Git worktree's isolated artifact directory. Start or reconnect the MCP server from each worktree the agent enters. Generated agent MCP configs use the installed `madar` command with the same `serve --stdio --auto-refresh` flow rather than a version-pinned `npx` launcher or an absolute graph path.
 
 If you still discover older `graphify-ts` links or listings, Madar is the current project name. Use `https://github.com/mohanagy/madar` and `@lubab/madar` as the canonical repository and package surfaces.
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lubab/madar",
-    "version": "0.29.0",
+    "version": "0.30.0",
     "description": "Stop AI coding agents from rediscovering large TypeScript/Node repos. Madar compiles task-aware local context packs from what runs for this task.",
     "license": "MIT",
     "author": "mohanagy",