devsmind-mcp 4.2.0 → 4.3.0

package/dist/mcp/server.js

@@ -56,6 +56,7 @@ const fs = __importStar(require("fs"));
 const express_1 = __importDefault(require("express"));
 const database_1 = require("../db/database");
 const config_1 = require("../utils/config");
+const devsmind_branch_1 = require("../utils/devsmind-branch");
 const visualizer_1 = require("./visualizer");
 const diff_1 = require("../utils/diff");
 const revert_1 = require("../db/revert");
@@ -89,23 +90,23 @@ exports.DEVSMIND_PORT = 4513;
  */
 /** MCP prompts/list name for the workflow-contract prompt below — see createMcpServer's prompts handlers. */
 exports.DEVSMIND_PROMPT_NAME = 'devsmind-workflow';
-exports.DEVSMIND_INSTRUCTIONS = `DevsMind is this team's persistent shared code memory — not a personal tool you reach for only when asked to search something. Every teammate's AI agent, in every session, reads from the SAME graph you are about to write to. There is no "your copy."
-
-If you skip recording a change, you are not skipping a formality. You are leaving the whole team's graph stale for every other AI agent that queries this code later — tomorrow, on a different task, in a different session. And the reasoning behind your change (why it was made, what ticket drove it, what was broken before, what you tried and rejected) exists ONLY in this conversation, right now. It is not in the diff. It is not in the commit message. If it isn't captured at commit_changes this turn, it is gone forever — no reindex, no log, no git blame can recover it later.
-
-Non-negotiable workflow:
-1. Call start_session once, before your first WRITE of the conversation (edit_node/commit_changes and the other mutating tools). It mints a session_id that every write REQUIRES — it ties a request's edits together on the local Activity log and makes them revertable as a unit — and every response echoes it back so it stays in front of you, including after a context compaction. Read-only tools (search_nodes, get_node_code, list_nodes, and the other getters) do NOT need it: search and read freely from the very first call. Never invent a session_id yourself; if a write errors saying session_id is required, start_session was skipped — call it now, then retry. If you are resuming a conversation that already called start_session earlier (visible in the reloaded history), reuse that same session_id instead of starting a new one.
-2. Before any filesystem search, grep, or file read: call search_nodes FIRST — it is now the one call for both "find this node" AND "find where X lives across files", so you should not need an external grep. Two inputs, pass either or both: a natural-language query (a real phrase — drives meaning-matching, so "authentication" finds a node described only as "sign-in") and/or pattern, a REAL regex used exactly as you'd give it to grep (e.g. "heartRed|onLikeTap|item\.liked" — nothing is re-escaped or split for you). Pattern-only is a precision mode: exact grep + code-body matches, no semantic blur. It returns two buckets: nodes (the indexed graph — the primary answer for "which function/class", with a true nodes_total before the top-20 cap) and files (a real grep of every repo, or just the path scope if given — the answer for things the graph does not index: CSS, JSON, config, .env, markup, wiring like "where is CORS configured" or "what mounts this middleware" — each sample line reports which function/class it falls inside, and files_total tells you honestly whether there's more than the page shown; pass a bigger offset for the next page). Triage by each node's confidence and relevance, NOT by which name looks right to you — confidence reflects how many independent layers corroborated the hit, which your own reading of a name cannot. Lockfiles and build artifacts are excluded by default, so what comes back is real source. If the response carries a compacted field, it was trimmed to fit and says exactly what was dropped — all counts stay exact, and compact:false gets you the untrimmed payload. It only returns real evidence — genuinely-absent things come back empty with a hint; if so, retry once with a different pattern/query before concluding it is not there. Only drop to a manual grep/read if search_nodes itself says truncated, or you need full file context after it points you at the file.
-3. To read one function/class: call get_node_code instead of opening the file, and do not follow it with a file read for context — this is the ONE node-read call, not a lean summary. It already includes the file's imports, the node's own name/type/signature/description, up to 20 named callers AND callees per direction (with exact uses/used_by counts even when the lists are capped), and up to 40 other declarations from the same file (file_outline — this is how you tell "was this renamed?" or "what else lives here" without opening the file). Reach further in the SAME call instead of a second tool: graph_depth + graph_direction walks the transitive graph past the direct neighbors already included (add graph_code:true for a whole call flow's source in one round trip — if some nodes' code doesn't fit the budget they are named in graph.code_omitted_node_ids, so fetch exactly those rather than re-running blind), and history:"full" returns every revision with diffable edits, pageable with history_limit/history_offset. Every capped section is honest about it (*_truncated, *_hint) — a hint means more is reachable in this same call, not a dead end.
-4. Before touching any function's signature: get_node_code already includes its direct callers by name (used_by_nodes) — for the FULL transitive blast radius, pass graph_direction:"in" with a graph_depth of 2-3 in that same call. Git shows you what changed; it never shows you what depends on it. Find out before you break something, not after.
-5. Before refactoring: get_node_code already includes the last 3 changes' reasoning by default — for the full revision trail with diffable before/after edits, pass history:"full" in that same call. Git blame tells you who and when; it never tells you why. The actual decision context only exists here.
-6. Write EVERY file with edit_node — .ts, .vue, .css, .json, .xml, .md, anything — and never your editor's own edit/write tools. It takes file_path + old_string + new_string exactly like an ordinary edit tool and never refuses a file type; to create a file that doesn't exist yet, pass old_string: "" and the whole file as new_string. Because it knows where your text landed, it works out which function/class you changed automatically: no node_id to look up, no code_snapshot to send back. It answers with every caller of what you changed. The graph only ever holds source code (functions/classes/logic) though — writes landing outside any function (markup, config, an import) get no graph node, normal and expected, not a failure — but the whole-file change is still staged for the local activity log, so commit_changes makes it revertable there like any other edit.
-7. If a file already got edited WITHOUT going through edit_node — your own editor's edit/write tool got used by mistake, or you're catching up on work from before this session — call stage_change to recover it: same file_path/old_string/new_string/replace_all/description shape as edit_node, but it traces and stages the change without touching the file, since new_string is already sitting on disk. It fails clearly (new_string not found) if the edit never actually happened, so it can't silently record the wrong thing. Always prefer edit_node going forward; stage_change exists only to catch up after the fact, not as a second way to make an edit.
-8. commit_changes REQUIRES a message AND a reasoning — the call fails without either. message is the user's request, verbatim, that led to this commit; it builds a local, private, never-pushed activity log (devsmind view → Activity) grouping your work by request and letting the user revert a request as a whole. Pass the exact same text again on a later commit that's still answering the same request — that merges them into one entry instead of splitting it. reasoning (what_changed/why/goal) is ONE object covering everything staged since the last commit — a commit is one logical change, so it gets one why, recorded against every node it touches, not one per edit_node/stage_change call.
-9. commit_changes also REFUSES any batch containing a brand-NEW node with no description — a description is what makes that node findable later by a natural-language search_nodes query instead of only by its exact identifier. If edit_node or stage_change just created a node, call add_description with it (1-3 sentences of what it does and the domain concepts involved — never a restatement of the name) before commit_changes will accept it. Nothing staged is lost by the refusal; retry the same commit_changes call once it's described. Existing nodes are never gated by this — only ones new this commit.
-10. commit_changes is NOT git and never touches it. It writes only into DevsMind's own local graph/database (.devmind/) and local activity log — it never runs git add, git commit, git push, or any other git command, and its "commit" is a completely different thing from a git commit despite the shared word. Calling it successfully is not a signal to now go run git yourself: never run git add/git commit/git push on your own initiative just because commit_changes succeeded, or because you finished a task. Your real git commit — staging and committing the actual code changes — is the developer's decision, made separately, only when they explicitly ask for it, exactly like any other git action.
-11. A workflow is a named log of how ONE piece of functionality grew, across many sessions — read it to learn how the code got this way. start_session tells you if there is a recent one worth continuing; otherwise, when starting work that might belong to an existing multi-session feature, call workflow_list. If a description matches, ask the user before continuing it, then workflow_bind to attach THIS session. Binding is local to you: it never moves, pauses, or steals anyone else's workflow, and two sessions can work different ones at the same time.
-12. Once bound, commit_changes logs a step for you automatically — you do NOT need workflow_add_step for ordinary code work. Call it for the thing a commit cannot express: a DECISION OR RESEARCH FINDING THAT CHANGED NO CODE ("evaluated X, rejected it because Y"), attaching the docs behind it via doc_paths. That is the one kind of knowledge nothing else keeps — git has the diff, history has the per-node reasoning, but neither records what was considered and rejected. If you did work while unbound, or on the wrong workflow, workflow_sync attaches it afterwards from your local activity log: it previews first and only writes when you pass confirm:true, so nothing has to be got right in the moment.
+exports.DEVSMIND_INSTRUCTIONS = `DevsMind is this team's persistent shared code memory — not a personal tool you reach for only when asked to search something. Every teammate's AI agent, in every session, reads from the SAME graph you are about to write to. There is no "your copy."
+
+If you skip recording a change, you are not skipping a formality. You are leaving the whole team's graph stale for every other AI agent that queries this code later — tomorrow, on a different task, in a different session. And the reasoning behind your change (why it was made, what ticket drove it, what was broken before, what you tried and rejected) exists ONLY in this conversation, right now. It is not in the diff. It is not in the commit message. If it isn't captured at commit_changes this turn, it is gone forever — no reindex, no log, no git blame can recover it later.
+
+Non-negotiable workflow:
+1. Call start_session once, before your first WRITE of the conversation (edit_node/commit_changes and the other mutating tools). It mints a session_id that every write REQUIRES — it ties a request's edits together on the local Activity log and makes them revertable as a unit — and every response echoes it back so it stays in front of you, including after a context compaction. Read-only tools (search_nodes, get_node_code, list_nodes, and the other getters) do NOT need it: search and read freely from the very first call. Never invent a session_id yourself; if a write errors saying session_id is required, start_session was skipped — call it now, then retry. If you are resuming a conversation that already called start_session earlier (visible in the reloaded history), reuse that same session_id instead of starting a new one.
+2. Before any filesystem search, grep, or file read: call search_nodes FIRST — it is now the one call for both "find this node" AND "find where X lives across files", so you should not need an external grep. Two inputs, pass either or both: a natural-language query (a real phrase — drives meaning-matching, so "authentication" finds a node described only as "sign-in") and/or pattern, a REAL regex used exactly as you'd give it to grep (e.g. "heartRed|onLikeTap|item\.liked" — nothing is re-escaped or split for you). Pattern-only is a precision mode: exact grep + code-body matches, no semantic blur. It returns two buckets: nodes (the indexed graph — the primary answer for "which function/class", with a true nodes_total before the top-20 cap) and files (a real grep of every repo, or just the path scope if given — the answer for things the graph does not index: CSS, JSON, config, .env, markup, wiring like "where is CORS configured" or "what mounts this middleware" — each sample line reports which function/class it falls inside, and files_total tells you honestly whether there's more than the page shown; pass a bigger offset for the next page). Triage by each node's confidence and relevance, NOT by which name looks right to you — confidence reflects how many independent layers corroborated the hit, which your own reading of a name cannot. Lockfiles and build artifacts are excluded by default, so what comes back is real source. If the response carries a compacted field, it was trimmed to fit and says exactly what was dropped — all counts stay exact, and compact:false gets you the untrimmed payload. It only returns real evidence — genuinely-absent things come back empty with a hint; if so, retry once with a different pattern/query before concluding it is not there. Only drop to a manual grep/read if search_nodes itself says truncated, or you need full file context after it points you at the file.
+3. To read one function/class: call get_node_code instead of opening the file, and do not follow it with a file read for context — this is the ONE node-read call, not a lean summary. It already includes the file's imports, the node's own name/type/signature/description, up to 20 named callers AND callees per direction (with exact uses/used_by counts even when the lists are capped), and up to 40 other declarations from the same file (file_outline — this is how you tell "was this renamed?" or "what else lives here" without opening the file). Reach further in the SAME call instead of a second tool: graph_depth + graph_direction walks the transitive graph past the direct neighbors already included (add graph_code:true for a whole call flow's source in one round trip — if some nodes' code doesn't fit the budget they are named in graph.code_omitted_node_ids, so fetch exactly those rather than re-running blind), and history:"full" returns every revision with diffable edits, pageable with history_limit/history_offset. Every capped section is honest about it (*_truncated, *_hint) — a hint means more is reachable in this same call, not a dead end.
+4. Before touching any function's signature: get_node_code already includes its direct callers by name (used_by_nodes) — for the FULL transitive blast radius, pass graph_direction:"in" with a graph_depth of 2-3 in that same call. Git shows you what changed; it never shows you what depends on it. Find out before you break something, not after.
+5. Before refactoring: get_node_code already includes the last 3 changes' reasoning by default — for the full revision trail with diffable before/after edits, pass history:"full" in that same call. Git blame tells you who and when; it never tells you why. The actual decision context only exists here.
+6. Write EVERY file with edit_node — .ts, .vue, .css, .json, .xml, .md, anything — and never your editor's own edit/write tools. It takes file_path + old_string + new_string exactly like an ordinary edit tool and never refuses a file type; to create a file that doesn't exist yet, pass old_string: "" and the whole file as new_string. Because it knows where your text landed, it works out which function/class you changed automatically: no node_id to look up, no code_snapshot to send back. It answers with every caller of what you changed. The graph only ever holds source code (functions/classes/logic) though — writes landing outside any function (markup, config, an import) get no graph node, normal and expected, not a failure — but the whole-file change is still staged for the local activity log, so commit_changes makes it revertable there like any other edit.
+7. If a file already got edited WITHOUT going through edit_node — your own editor's edit/write tool got used by mistake, or you're catching up on work from before this session — call stage_change to recover it: same file_path/old_string/new_string/replace_all/description shape as edit_node, but it traces and stages the change without touching the file, since new_string is already sitting on disk. It fails clearly (new_string not found) if the edit never actually happened, so it can't silently record the wrong thing. Always prefer edit_node going forward; stage_change exists only to catch up after the fact, not as a second way to make an edit.
+8. commit_changes REQUIRES a message AND a reasoning — the call fails without either. message is the user's request, verbatim, that led to this commit; it builds a local, private, never-pushed activity log (devsmind view → Activity) grouping your work by request and letting the user revert a request as a whole. Pass the exact same text again on a later commit that's still answering the same request — that merges them into one entry instead of splitting it. reasoning (what_changed/why/goal) is ONE object covering everything staged since the last commit — a commit is one logical change, so it gets one why, recorded against every node it touches, not one per edit_node/stage_change call.
+9. commit_changes also REFUSES any batch containing a brand-NEW node with no description — a description is what makes that node findable later by a natural-language search_nodes query instead of only by its exact identifier. If edit_node or stage_change just created a node, call add_description with it (1-3 sentences of what it does and the domain concepts involved — never a restatement of the name) before commit_changes will accept it. Nothing staged is lost by the refusal; retry the same commit_changes call once it's described. Existing nodes are never gated by this — only ones new this commit.
+10. commit_changes is NOT git and never touches it. It writes only into DevsMind's own local graph/database (.devmind/) and local activity log — it never runs git add, git commit, git push, or any other git command, and its "commit" is a completely different thing from a git commit despite the shared word. Calling it successfully is not a signal to now go run git yourself: never run git add/git commit/git push on your own initiative just because commit_changes succeeded, or because you finished a task. Your real git commit — staging and committing the actual code changes — is the developer's decision, made separately, only when they explicitly ask for it, exactly like any other git action.
+11. A workflow is a named log of how ONE piece of functionality grew, across many sessions — read it to learn how the code got this way. start_session tells you if there is a recent one worth continuing; otherwise, when starting work that might belong to an existing multi-session feature, call workflow_list. If a description matches, ask the user before continuing it, then workflow_bind to attach THIS session. Binding is local to you: it never moves, pauses, or steals anyone else's workflow, and two sessions can work different ones at the same time.
+12. Once bound, commit_changes logs a step for you automatically — you do NOT need workflow_add_step for ordinary code work. Call it for the thing a commit cannot express: a DECISION OR RESEARCH FINDING THAT CHANGED NO CODE ("evaluated X, rejected it because Y"), attaching the docs behind it via doc_paths. That is the one kind of knowledge nothing else keeps — git has the diff, history has the per-node reasoning, but neither records what was considered and rejected. If you did work while unbound, or on the wrong workflow, workflow_sync attaches it afterwards from your local activity log: it previews first and only writes when you pass confirm:true, so nothing has to be got right in the moment.
 13. commit_changes also REQUIRES a feedback object (5 fields) — this is the only channel that improves DevsMind over time, so answer it for real, not as a formality. Before writing "none" on any field, actually check: did anything in THIS task take an extra tool call, a guess, a re-read, or a wrong turn? There almost always is something, even on an easy task — a specific one-line answer with evidence (file:line) is far more useful than a reflexive "none". "none" is correct only when you genuinely paid attention and nothing applies. Noticed something worth reporting but aren't committing right now (or don't want to wait until you are)? Call add_feedback directly — same 5 categories, but any one or more, nothing required, no commit needed. Passing evidence (file + snippet) on a graph_problem/edge_problem gets it verified fresh at call time and marked confirmed instead of suspected.`;
 // Shared node-type taxonomy description, reused by update_history and add_description.
 const NODE_TYPE_DESCRIPTION = 'The type of node. Be highly specific and framework-aware. Choose from the taxonomy below (or use a custom value if nothing fits).\n\n' +
@@ -163,6 +164,28 @@ function bindDevmindPath(devmindPath) {
 function getBoundDevmindPath() {
     return boundDevmindPath;
 }
+/**
+ * For a SCOPED indexing session (a caller-provided `scratchpad` filename, e.g. `add_repo`'s
+ * dedicated one) Phase 1 must only scan the ONE repo that session is for — otherwise
+ * `index_continue` would silently pull in every other repo's files too. Phase 2 (edge
+ * resolution, inside `index_complete`) deliberately stays whole-graph even for a scoped
+ * session — a newly-added repo's outgoing references need the full node set to resolve
+ * against, and an existing repo may gain a new incoming reference INTO it, so narrowing that
+ * step would be a correctness regression, not an optimization.
+ *
+ * The DEFAULT (unscoped) scratchpad's `current_repo` is never used to scope anything here —
+ * it's set as an incidental side effect of normal Phase 1 processing (whichever repo the last
+ * extracted file happened to be in), not a deliberate scope. Only an explicitly-provided
+ * `scratchpadFile` opts into this filtering.
+ */
+function scopedRepoFiles(devmindPath, scratchpadFile, pad) {
+    const { repos, total_files } = (0, scanner_1.scanRepoFiles)(devmindPath);
+    if (!scratchpadFile || !pad.current_repo) {
+        return { files: repos.flatMap(r => r.files), totalFiles: total_files };
+    }
+    const scoped = repos.filter(r => r.repo_name === pad.current_repo);
+    return { files: scoped.flatMap(r => r.files), totalFiles: scoped.reduce((sum, r) => sum + r.files.length, 0) };
+}
 // Walk up from a start directory to find a brain folder (`.devsmind`, or a legacy `.devmind`)
 // containing config.json. Both names are tried at every level — see utils/config.ts.
 // Resolve devmind_path from args, falling back to auto-detect from cwd
@@ -254,6 +277,22 @@ const LIST_NODES_DEFAULT_LIMIT = 100;
 /** Max characters of reasoning copied onto a workflow step — a timeline of 200 steps has to stay
  * readable in one response, and the full text is always still on the history rows. */
 const STEP_REASONING_CAP = 2000;
+/** `add_repo`'s dedicated scratchpad filename — separate from the default whole-workspace one so
+ * a scoped single-repo indexing session can never collide with (or be mistaken for) it. Passed as
+ * `scratchpad` to index_checkpoint/index_continue/index_complete to keep working with it. */
+const ADD_REPO_MCP_SCRATCHPAD = 'add_repo_scratchpad.json';
+/** Max characters PER doc in `workflow_add_step`'s `doc_content` — generous enough for a real spec
+ * doc, small enough that one call can't dump a multi-MB blob through the MCP transport. */
+const DOC_CONTENT_CAP = 500_000;
+/** Max number of `doc_content` entries per `workflow_add_step` call — a step records one decision,
+ * not a document dump. */
+const DOC_CONTENT_MAX_COUNT = 10;
+/** Max number of `doc_uploads` entries per `workflow_add_step` call — same reasoning as
+ * DOC_CONTENT_MAX_COUNT. */
+const DOC_UPLOAD_MAX_COUNT = 10;
+/** Max size PER file copied in via `doc_uploads` — generous for a spec doc or a diagram export,
+ * small enough that one call can't copy a huge archive into `.devmind/workflows/`. */
+const DOC_UPLOAD_MAX_BYTES = 20 * 1024 * 1024;
 /**
  * The part of a commit's reasoning worth carrying onto a workflow step: WHY it was done, what it
  * was for, and what was decided.
@@ -311,6 +350,26 @@ function getDatabase(devmindPath) {
     }
     return dbCache.get(dbFile);
 }
+/**
+ * Evicts (closing first, best-effort) the cached `DevMindDatabase` for `devmindPath` — the next
+ * `getDatabase` call constructs a fresh one. Needed after `add_repo` writes a new repo into
+ * `config.json`: `DevMindDatabase` snapshots `ProjectContext` once, in its constructor
+ * (`toRepoRelativePath` reads `this.context.config.repos`, set there and never refreshed), so a
+ * cached instance from an earlier tool call in the SAME session (e.g. `start_session`) would
+ * otherwise keep producing `../<repo>/...`-style ids for the just-added repo's nodes instead of
+ * `{<repo>}/...`, having never seen it in `config.repos`.
+ */
+function invalidateDatabase(devmindPath) {
+    const dbFile = path.join(devmindPath, 'brain.db');
+    const existing = dbCache.get(dbFile);
+    if (existing) {
+        try {
+            existing.close();
+        }
+        catch { /* best-effort */ }
+        dbCache.delete(dbFile);
+    }
+}
 /**
  * Closes every cached DB connection (best-effort) and clears the cache. Normally only reached via
  * the SIGINT/SIGTERM shutdown handlers below; exported so tests can release a fixture's cached
@@ -362,7 +421,10 @@ const SESSION_EXEMPT_READ_TOOLS = new Set([
     // are gone, so they no longer belong here. `workflow_list` is NOT exempt any more either: it
     // reports `bound_workflow_id`, which is a per-session fact — without a session_id it could only
     // ever answer null, which reads as "you are on nothing" rather than "I cannot tell".
-    'get_activity_log'
+    'get_activity_log',
+    // Pulls committed brain state down from git — no session-scoped state involved. push_devsmind_branch
+    // is NOT exempt: it's a real write (commit + push), same bar as commit_changes/workflow_add_step.
+    'pull_devsmind_branch'
 ]);
 /**
  * Creates and wires up a DevsMind MCP Server instance.
@@ -473,7 +535,8 @@ function createMcpServer() {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' }
+                        devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                        scratchpad: { type: 'string', description: 'Advanced: only pass this if add_repo told you to. Selects a scoped indexing session (e.g. the one add_repo started) instead of the default whole-workspace one.' }
                     },
                     required: ['devmind_path']
                 }
@@ -484,7 +547,8 @@ function createMcpServer() {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' }
+                        devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                        scratchpad: { type: 'string', description: 'Advanced: only pass this if add_repo told you to. Selects a scoped indexing session (e.g. the one add_repo started) instead of the default whole-workspace one.' }
                     },
                     required: ['devmind_path']
                 }
@@ -495,7 +559,21 @@ function createMcpServer() {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' }
+                        devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                        scratchpad: { type: 'string', description: 'Advanced: only pass this if add_repo told you to. Selects a scoped indexing session (e.g. the one add_repo started) instead of the default whole-workspace one.' }
+                    },
+                    required: ['devmind_path']
+                }
+            },
+            {
+                name: 'add_repo',
+                description: 'Standalone mode only: add ONE new repo to this brain and index just that repo — the graph-scoping equivalent of index_start, but scoped to a single repo instead of the whole workspace. Registers the repo in config.json/.env, then extracts its structure locally (no LLM) and hands back a first batch of nodes to describe, same as index_start. Continue with index_continue / index_complete exactly as you would for a normal index, but ALWAYS pass the same scratchpad value this call returns — omitting it targets the unrelated whole-workspace session instead. Resumable: if a previous add_repo call is still mid-index, call this again with NO name/path and it tells you which repo and scratchpad to continue with, rather than starting over. Refuses with a clear error in embedded mode (an embedded brain already covers exactly the one repo it lives inside).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                        name: { type: 'string', description: 'New repo name. Omit (along with path) to resume a previous add_repo call that has not finished indexing yet.' },
+                        path: { type: 'string', description: 'Absolute local path to the repo on this machine. Required together with name on a fresh call.' }
                     },
                     required: ['devmind_path']
                 }
@@ -977,7 +1055,7 @@ function createMcpServer() {
             },
             {
                 name: 'workflow_add_step',
-                description: 'Record ONE step on a workflow, with the docs behind it, in the same call. You do NOT need this for ordinary code work — commit_changes already adds a step automatically whenever the session is bound. Call it for the thing a commit cannot express: A DECISION OR RESEARCH FINDING THAT CHANGED NO CODE (e.g. "evaluated Razorpay, no split settlements, going with Stripe"). That is the one kind of knowledge nothing else in DevsMind keeps — git has the diff and history has the per-node reasoning, but neither records what was considered and rejected. Attach the docs it came from via doc_paths.',
+                description: 'Record ONE step on a workflow, with the docs behind it, in the same call. You do NOT need this for ordinary code work — commit_changes already adds a step automatically whenever the session is bound. Call it for the thing a commit cannot express: A DECISION OR RESEARCH FINDING THAT CHANGED NO CODE (e.g. "evaluated Razorpay, no split settlements, going with Stripe"). That is the one kind of knowledge nothing else in DevsMind keeps — git has the diff and history has the per-node reasoning, but neither records what was considered and rejected. Attach the docs it came from three ways: doc_paths (reference a file that already exists in a configured repo, no copy), doc_uploads (COPY an existing file on disk — any type, PDF/docx/image included — into DevsMind\'s own storage; use this for a doc outside any repo, or one you want to survive its source being deleted), or doc_content (paste text you have in hand but that isn\'t a file at all, or no longer is).',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -986,7 +1064,24 @@ function createMcpServer() {
                         summary: { type: 'string', description: 'One line: what was decided or found' },
                         reasoning: { type: 'string', description: 'The why behind it — what was considered, what was rejected, and on what grounds. This is the part nobody can reconstruct later from the code that survived.' },
                         node_ids: { type: 'array', items: { type: 'string' }, description: 'Optional node ids this step relates to. Leave empty for a pure research/decision step.' },
-                        doc_paths: { type: 'array', items: { type: 'string' }, description: 'Optional paths to research/spec docs behind this step, relative to the repo. Stored as PATHS, never copies, so they stay current and are already shared with your team — a path outside the configured repos is rejected, since it would not exist for anyone else.' }
+                        doc_paths: { type: 'array', items: { type: 'string' }, description: 'Optional paths to research/spec docs behind this step, relative to the repo. Stored as PATHS, never copies, so they stay current and are already shared with your team — a path outside the configured repos is rejected, since it would not exist for anyone else.' },
+                        doc_content: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    name: { type: 'string', description: 'File name for this doc, e.g. "interest-caveat.md" — sanitized before use.' },
+                                    content: { type: 'string', description: `The doc's full text (max ${DOC_CONTENT_CAP.toLocaleString()} chars).` }
+                                },
+                                required: ['name', 'content']
+                            },
+                            description: `Optional: up to ${DOC_CONTENT_MAX_COUNT} docs whose CONTENT (not just a path) should be copied into DevsMind's own storage under .devmind/workflows/. Use this instead of doc_paths when the doc has no on-repo home, or when it must keep existing after its source file is deleted. Content is stored on disk, not inlined into future responses — workflow_get_context returns each artifact's file_path, and you read it from there.`
+                        },
+                        doc_uploads: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: `Optional: up to ${DOC_UPLOAD_MAX_COUNT} absolute paths to files (any type; max ${(DOC_UPLOAD_MAX_BYTES / (1024 * 1024)).toFixed(0)}MB each) to COPY into DevsMind's own storage under .devmind/workflows/ — the actual bytes, not just the path. Unlike doc_paths there's no configured-repo restriction, since the point is capturing a doc that may not live in one (or won't stay on disk at all). Use this — not doc_content — whenever the doc already exists as a file; it's simpler and works for binary files doc_content can't hold as text.`
+                        }
                     },
                     required: ['devmind_path', 'summary']
                 }
@@ -1032,6 +1127,29 @@ function createMcpServer() {
                     },
                     required: ['devmind_path']
                 }
+            },
+            {
+                name: 'push_devsmind_branch',
+                description: `Commit graph/history/vectors/workflows onto the dedicated '${devsmind_branch_1.DEVSMIND_BRANCH}' branch and push it. UNLIKE commit_changes, this DOES run real git commands (commit + push) — but only ever on the '${devsmind_branch_1.DEVSMIND_BRANCH}' branch, via a throwaway worktree, so the developer's actual checked-out branch is never touched, moved, or committed to. This exists so a PR diff shows only real code changes, not the hundreds of graph/history files DevsMind itself writes. Only call this when the developer has asked you to push, not as a routine follow-up to commit_changes. Requires a commit message.`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' },
+                        message: { type: 'string', description: `Commit message for this snapshot on the '${devsmind_branch_1.DEVSMIND_BRANCH}' branch.` }
+                    },
+                    required: ['devmind_path', 'message']
+                }
+            },
+            {
+                name: 'pull_devsmind_branch',
+                description: `Read-only counterpart to push_devsmind_branch: copies graph/history/vectors/workflows down from the '${devsmind_branch_1.DEVSMIND_BRANCH}' branch (remote-tracking ref preferred when a remote exists) into .devsmind/ on disk and re-syncs brain.db. Useful after a teammate has pushed — a plain git pull on the code branch no longer brings this data in once it lives on '${devsmind_branch_1.DEVSMIND_BRANCH}' instead.`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        devmind_path: { type: 'string', description: 'Absolute path to the .devmind directory' }
+                    },
+                    required: ['devmind_path']
+                }
             }
         ];
         // Every tool except start_session (the one tool that CREATES a session) requires
@@ -1428,7 +1546,8 @@ function createMcpServer() {
                 }
                 case 'index_checkpoint': {
                     const devmindPath = resolveDevmindPath(args.devmind_path);
-                    const pad = (0, indexer_1.readScratchpad)(devmindPath);
+                    const scratchpadFile = args.scratchpad ? String(args.scratchpad) : undefined;
+                    const pad = (0, indexer_1.readScratchpad)(devmindPath, scratchpadFile);
                     if (!pad) {
                         return {
                             content: [{ type: 'text', text: JSON.stringify({ error: 'No indexing session found. Call index_start first.' }) }]
@@ -1455,7 +1574,8 @@ function createMcpServer() {
                 case 'index_continue': {
                     const devmindPath = resolveDevmindPath(args.devmind_path);
                     const db = getDatabase(devmindPath);
-                    const pad = (0, indexer_1.readScratchpad)(devmindPath);
+                    const scratchpadFile = args.scratchpad ? String(args.scratchpad) : undefined;
+                    const pad = (0, indexer_1.readScratchpad)(devmindPath, scratchpadFile);
                     if (!pad) {
                         return {
                             content: [{ type: 'text', text: JSON.stringify({ error: 'No indexing session found. Call index_start first.' }) }]
@@ -1476,8 +1596,7 @@ function createMcpServer() {
                         'NEVER write or execute external scripts to index files — the server already extracted the structure; you only describe.'
                     ];
                     if (pad.phase === 1) {
-                        const { repos } = (0, scanner_1.scanRepoFiles)(devmindPath);
-                        const allFiles = repos.flatMap(r => r.files);
+                        const { files: allFiles } = scopedRepoFiles(devmindPath, scratchpadFile, pad);
                         const startIdx = pad.last_file_indexed ? allFiles.findIndex(f => f === pad.last_file_indexed) + 1 : 0;
                         const remainingFiles = allFiles.slice(startIdx);
                         if (remainingFiles.length > 0) {
@@ -1485,7 +1604,7 @@ function createMcpServer() {
                             pad.files_done += batch.filesExtracted.length;
                             pad.last_file_indexed = batch.cursor;
                             pad.nodes_created += batch.nodesCreated;
-                            (0, indexer_1.writeScratchpad)(devmindPath, pad);
+                            (0, indexer_1.writeScratchpad)(devmindPath, pad, scratchpadFile);
                             return {
                                 content: [{
                                         type: 'text',
@@ -1500,7 +1619,7 @@ function createMcpServer() {
                             };
                         }
                         pad.phase = 2;
-                        (0, indexer_1.writeScratchpad)(devmindPath, pad);
+                        (0, indexer_1.writeScratchpad)(devmindPath, pad, scratchpadFile);
                     }
                     return {
                         content: [{
@@ -1519,7 +1638,8 @@ function createMcpServer() {
                 case 'index_complete': {
                     const devmindPath = resolveDevmindPath(args.devmind_path);
                     const db = getDatabase(devmindPath);
-                    const pad = (0, indexer_1.readScratchpad)(devmindPath);
+                    const scratchpadFile = args.scratchpad ? String(args.scratchpad) : undefined;
+                    const pad = (0, indexer_1.readScratchpad)(devmindPath, scratchpadFile);
                     if (!pad) {
                         return {
                             content: [{ type: 'text', text: JSON.stringify({ error: 'No indexing session found. Call index_start first.' }) }]
@@ -1530,7 +1650,11 @@ function createMcpServer() {
                             content: [{ type: 'text', text: JSON.stringify({ status: 'complete', message: 'Indexing already completed.', scratchpad: pad }, null, 2) }]
                         };
                     }
-                    const { total_files } = (0, scanner_1.scanRepoFiles)(devmindPath);
+                    // Phase 1 completeness is checked against the SAME scope index_continue used to fill
+                    // it — the whole workspace for the default session, just this repo's files for a
+                    // scoped one (a scoped scratchpad's files_total never covers every other repo, so
+                    // comparing it against the unscoped total would report "incomplete" forever).
+                    const { totalFiles: total_files } = scopedRepoFiles(devmindPath, scratchpadFile, pad);
                     if (pad.phase === 1 && pad.files_done < total_files) {
                         return {
                             isError: true,
@@ -1557,7 +1681,7 @@ function createMcpServer() {
                                 }]
                         };
                     }
-                    const finalPad = (0, indexer_1.completeScratchpad)(devmindPath);
+                    const finalPad = (0, indexer_1.completeScratchpad)(devmindPath, scratchpadFile);
                     db.vacuum();
                     const undescribedCount = db.getAllNodes().filter(n => !n.deprecated && !n.description).length;
                     return {
@@ -1582,6 +1706,94 @@ function createMcpServer() {
                             }]
                     };
                 }
+                case 'add_repo': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const ctx = (0, config_1.loadProjectContext)(devmindPath);
+                    if (!(0, config_1.isStandaloneMode)(ctx.config)) {
+                        return {
+                            isError: true,
+                            content: [{ type: 'text', text: JSON.stringify({ error: 'add_repo is only available in standalone mode — an embedded brain already covers exactly the one repo it lives inside.' }) }]
+                        };
+                    }
+                    const existingPad = (0, indexer_1.readScratchpad)(devmindPath, ADD_REPO_MCP_SCRATCHPAD);
+                    if (existingPad && existingPad.status === 'in_progress' && existingPad.current_repo) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        status: 'resuming',
+                                        message: `An add_repo session for "${existingPad.current_repo}" is already in progress. Do NOT call add_repo again for it — call index_continue (or index_checkpoint to see where it stands) with scratchpad: "${ADD_REPO_MCP_SCRATCHPAD}".`,
+                                        repo_name: existingPad.current_repo,
+                                        scratchpad: existingPad
+                                    }, null, 2)
+                                }]
+                        };
+                    }
+                    const name = args.name ? String(args.name).trim() : '';
+                    const repoPath = args.path ? String(args.path).trim() : '';
+                    if (!name || !repoPath) {
+                        return {
+                            isError: true,
+                            content: [{ type: 'text', text: JSON.stringify({ error: 'add_repo: both name and path are required to add a new repo (omit both only to resume a previous in-progress add_repo call — none was found).' }) }]
+                        };
+                    }
+                    if (ctx.config.repos.some(r => r.name === name)) {
+                        return {
+                            isError: true,
+                            content: [{ type: 'text', text: JSON.stringify({ error: `add_repo: a repo named "${name}" already exists in this brain.` }) }]
+                        };
+                    }
+                    if (!fs.existsSync(repoPath) || !fs.statSync(repoPath).isDirectory()) {
+                        return {
+                            isError: true,
+                            content: [{ type: 'text', text: JSON.stringify({ error: `add_repo: path does not exist or is not a directory: ${repoPath}` }) }]
+                        };
+                    }
+                    const pathKey = `REPO_${name.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+                    const configPath = path.join(devmindPath, 'config.json');
+                    ctx.config.repos.push({ name, path_key: pathKey });
+                    fs.writeFileSync(configPath, JSON.stringify(ctx.config, null, 2) + '\n', 'utf-8');
+                    const envPath = path.join(devmindPath, '.env');
+                    const envLines = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf-8').split('\n').filter(l => l.trim()) : [];
+                    envLines.push(`${pathKey}=${repoPath}`);
+                    fs.writeFileSync(envPath, envLines.join('\n') + '\n', 'utf-8');
+                    // A DB instance already cached by an earlier call THIS session (e.g. start_session)
+                    // would still be working from the config.repos snapshot it took at construction time —
+                    // see invalidateDatabase's doc comment. Evict it so node ids for the new repo's files
+                    // resolve to `{name}/...`, not a fallback `../name/...` relative path.
+                    invalidateDatabase(devmindPath);
+                    // index_start's own pattern, scoped to just this one repo.
+                    const db = getDatabase(devmindPath);
+                    const { repos } = (0, scanner_1.scanRepoFiles)(devmindPath);
+                    const scopedRepo = repos.find(r => r.repo_name === name);
+                    const allFiles = scopedRepo ? scopedRepo.files : [];
+                    const pad = (0, indexer_1.createScratchpad)(devmindPath, allFiles.length, ADD_REPO_MCP_SCRATCHPAD);
+                    pad.current_repo = name; // scopedRepoFiles relies on this to keep index_continue/index_complete scoped to just this repo
+                    const batch = (0, index_build_1.extractFilesIntoGraph)(db, allFiles);
+                    pad.files_done = batch.filesExtracted.length;
+                    pad.last_file_indexed = batch.cursor;
+                    pad.nodes_created = batch.nodesCreated;
+                    (0, indexer_1.writeScratchpad)(devmindPath, pad, ADD_REPO_MCP_SCRATCHPAD);
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'started',
+                                    message: `Repo "${name}" added to config.json/.env. Indexing started (structure only, no LLM) — describe every node in batch.nodes with ONE add_description call, then call index_continue for the next batch.`,
+                                    repo_name: name,
+                                    scratchpad: pad,
+                                    batch: { files: batch.filesExtracted, nodes: batch.nodes, file_imports: batch.fileImports },
+                                    instructions: [
+                                        `Every index_continue / index_checkpoint / index_complete call for this repo MUST include scratchpad: "${ADD_REPO_MCP_SCRATCHPAD}" — omitting it targets the unrelated whole-workspace session instead.`,
+                                        'Describe every node in `batch.nodes` with ONE add_description call.',
+                                        'Then call index_continue (with the scratchpad param) for the next batch. Repeat until it reports no files remain.',
+                                        'Once every node is described, call index_complete (with the scratchpad param).',
+                                        'NEVER write or execute external scripts to index files.'
+                                    ]
+                                }, null, 2)
+                            }]
+                    };
+                }
                 case 'edit_node': {
                     const devmindPath = resolveDevmindPath(args.devmind_path);
                     const editDb = getDatabase(devmindPath);
@@ -2758,6 +2970,66 @@ function createMcpServer() {
                         }
                         docPaths.push(db.toRepoRelativePath(abs));
                     }
+                    // `doc_content` is the copy-in counterpart to doc_paths: for text that has no on-repo
+                    // home (or won't stay there), store the bytes in DevsMind itself via the same
+                    // workflow_artifacts mechanism workflow_import uses, rather than a path that can dangle.
+                    const rawDocContent = Array.isArray(args.doc_content) ? args.doc_content : [];
+                    if (rawDocContent.length > DOC_CONTENT_MAX_COUNT) {
+                        return {
+                            isError: true,
+                            content: [{ type: 'text', text: JSON.stringify({ error: `doc_content accepts at most ${DOC_CONTENT_MAX_COUNT} docs per step, got ${rawDocContent.length}.` }) }]
+                        };
+                    }
+                    const docContent = [];
+                    for (const raw of rawDocContent) {
+                        if (!raw || typeof raw !== 'object' || typeof raw.name !== 'string' || typeof raw.content !== 'string') {
+                            return {
+                                isError: true,
+                                content: [{ type: 'text', text: JSON.stringify({ error: 'Each doc_content entry needs a string `name` and a string `content`.' }) }]
+                            };
+                        }
+                        if (raw.content.length > DOC_CONTENT_CAP) {
+                            return {
+                                isError: true,
+                                content: [{ type: 'text', text: JSON.stringify({ error: `doc_content entry "${raw.name}" is ${raw.content.length} chars, over the ${DOC_CONTENT_CAP} cap.` }) }]
+                            };
+                        }
+                        docContent.push({ name: raw.name, content: raw.content });
+                    }
+                    // `doc_uploads` copies an existing file's bytes in — binary-safe, and no configured-repo
+                    // restriction (that restriction exists for doc_paths because a rejected reference is
+                    // useless to teammates; a copy has no such dependency on where the source lives).
+                    const rawDocUploads = Array.isArray(args.doc_uploads) ? args.doc_uploads.map(String) : [];
+                    if (rawDocUploads.length > DOC_UPLOAD_MAX_COUNT) {
+                        return {
+                            isError: true,
+                            content: [{ type: 'text', text: JSON.stringify({ error: `doc_uploads accepts at most ${DOC_UPLOAD_MAX_COUNT} files per step, got ${rawDocUploads.length}.` }) }]
+                        };
+                    }
+                    const docUploads = [];
+                    for (const raw of rawDocUploads) {
+                        const abs = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(path.dirname(devmindPath), raw);
+                        if (!fs.existsSync(abs)) {
+                            return {
+                                isError: true,
+                                content: [{ type: 'text', text: JSON.stringify({ error: `doc_upload does not exist on disk: ${raw}` }) }]
+                            };
+                        }
+                        const stat = fs.statSync(abs);
+                        if (!stat.isFile()) {
+                            return {
+                                isError: true,
+                                content: [{ type: 'text', text: JSON.stringify({ error: `doc_upload is not a file: ${raw}` }) }]
+                            };
+                        }
+                        if (stat.size > DOC_UPLOAD_MAX_BYTES) {
+                            return {
+                                isError: true,
+                                content: [{ type: 'text', text: JSON.stringify({ error: `doc_upload "${raw}" is ${stat.size} bytes, over the ${DOC_UPLOAD_MAX_BYTES} cap.` }) }]
+                            };
+                        }
+                        docUploads.push(abs);
+                    }
                     const step = db.addWorkflowStep(workflowId, {
                         summary: requireStr(args, 'summary', 'workflow_add_step'),
                         reasoning: args.reasoning ? String(args.reasoning).slice(0, STEP_REASONING_CAP) : undefined,
@@ -2765,7 +3037,18 @@ function createMcpServer() {
                         docPaths: docPaths.length ? docPaths : undefined,
                         sessionId
                     });
-                    return { content: [{ type: 'text', text: JSON.stringify({ status: 'added', step }, null, 2) }] };
+                    const artifacts = [
+                        ...docContent.map(doc => db.addWorkflowArtifact(workflowId, { stepId: step.id, type: 'step_doc', sourceName: doc.name, content: doc.content })),
+                        ...docUploads.map(sourcePath => db.addWorkflowArtifactFromFile(workflowId, { stepId: step.id, type: 'step_doc', sourcePath }))
+                    ];
+                    return {
+                        content: [{
+                                type: 'text',
+                                // Artifact CONTENT is deliberately not echoed back — same reasoning as
+                                // getWorkflowContext (database.ts): the file_path is enough, and content just went in.
+                                text: JSON.stringify({ status: 'added', step, artifacts: artifacts.length ? artifacts : undefined }, null, 2)
+                            }]
+                    };
                 }
                 case 'workflow_bind': {
                     const devmindPath = resolveDevmindPath(args.devmind_path);
@@ -2980,6 +3263,32 @@ function createMcpServer() {
                     const result = (0, workflow_import_1.importWorkflowDocs)(db, args.folder_path ? String(args.folder_path) : undefined, args.file_path ? String(args.file_path) : undefined);
                     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
                 }
+                case 'push_devsmind_branch': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const message = requireStr(args, 'message', 'push_devsmind_branch');
+                    const result = (0, devsmind_branch_1.pushDevsmindBranch)(devmindPath, message);
+                    const status = !result.committed && !result.pushed
+                        ? 'nothing_to_push'
+                        : result.pushed
+                            ? (result.committed ? 'pushed' : 'pushed_prior_commit')
+                            : 'committed_local_only';
+                    return { content: [{ type: 'text', text: JSON.stringify({ status, ...result }, null, 2) }] };
+                }
+                case 'pull_devsmind_branch': {
+                    const devmindPath = resolveDevmindPath(args.devmind_path);
+                    const result = (0, devsmind_branch_1.pullDevsmindBranch)(devmindPath);
+                    if (!result.found) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({ status: 'not_found', message: `No '${devsmind_branch_1.DEVSMIND_BRANCH}' branch found locally or on the remote yet — run push_devsmind_branch first.`, ...result }, null, 2)
+                                }]
+                        };
+                    }
+                    const db = getDatabase(devmindPath);
+                    db.syncFromDisk();
+                    return { content: [{ type: 'text', text: JSON.stringify({ status: 'pulled', ...result, counts: db.getCounts() }, null, 2) }] };
+                }
                 // NOTE: `workflow_pause` and `workflow_resume` are retained as thin aliases for
                 // `workflow_bind`. Their old meaning — move a single global pointer, pausing whoever else
                 // held it — no longer exists, and could not be reproduced without reintroducing the bug