handoff-mcp-server 0.20.0 → 0.22.1

package/src/mcp/handlers/get_task.rs

@@ -22,6 +22,14 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let (data, status) = read_task(&task_dir)?
         .ok_or_else(|| anyhow::anyhow!("Task file not found in {}", task_dir.display()))?;
 
+    // `links` stays the legacy `Vec<String>` for backward compatibility with
+    // existing clients (skills / VSCode extension). `task_links` is an
+    // additive field carrying the normalized, deduplicated view from the
+    // `links()` accessor (wiki/130-document-management.md §9.1), so callers
+    // that understand typed links (doc/url/file/task) can read them without
+    // re-deriving the merge themselves.
+    let normalized_links = data.links();
+
     let result = serde_json::json!({
         "id": data.id,
         "title": data.title,
@@ -33,6 +41,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
         "completed_at": data.completed_at,
         "labels": data.labels,
         "links": data.links,
+        "task_links": normalized_links,
         "done_criteria": data.done_criteria,
         "schedule": data.schedule,
         "dependencies": data.dependencies,

package/src/mcp/handlers/import_context.rs

@@ -360,6 +360,7 @@ fn create_task_recursive(
         completed_at,
         labels: extract_string_array_from(task_val, "labels"),
         links: extract_string_array_from(task_val, "links"),
+        task_links: Vec::new(),
         done_criteria: extract_done_criteria(task_val),
         schedule: extract_schedule(task_val),
         dependencies: extract_string_array_from(task_val, "dependencies"),

package/src/mcp/handlers/memory.rs

@@ -11,6 +11,7 @@ use serde_json::{json, Value};
 use std::path::Path;
 
 use super::resolve_project_dir;
+use crate::context::injection::{filter_already_injected, rank_by_bm25_and_scope, RankConfig};
 use crate::storage::config::{read_config, SettingsConfig};
 use crate::storage::ensure_handoff_exists;
 use crate::storage::memory::{
@@ -277,49 +278,47 @@ pub fn handle_query(arguments: &Value) -> Result<String> {
     for p in &file_paths {
         query_tokens.extend(lexsim::tokenize(&basename(p)));
     }
-    let scores = corpus.bm25_scores_tokens(&query_tokens);
 
-    // Score + scope-path bonus, then threshold and rank.
-    let mut ranked: Vec<(usize, f64)> = memories
-        .iter()
-        .enumerate()
-        .map(|(i, m)| {
-            let mut s = scores[i];
-            if scope_matches(&m.scope_paths, &file_paths) {
-                s += SCOPE_PATH_BONUS;
-            }
-            (i, s)
-        })
-        .filter(|(_, s)| *s >= settings.memory_query_min_score)
-        .collect();
-    ranked.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
+    // Score + scope-path bonus, then threshold and rank (shared with doc_query).
+    let scope_paths: Vec<Vec<String>> = memories.iter().map(|m| m.scope_paths.clone()).collect();
+    let rank_config = RankConfig {
+        min_score: settings.memory_query_min_score,
+        scope_path_bonus: SCOPE_PATH_BONUS,
+        // Rank without truncating yet — the session diff below needs the full
+        // ranked order so it can backfill past already-injected memories.
+        limit: memories.len(),
+    };
+    let ranked = rank_by_bm25_and_scope(
+        &corpus,
+        &query_tokens,
+        &scope_paths,
+        &file_paths,
+        &rank_config,
+    );
 
     // Per-session diff: drop memories already injected this session at the same
     // hash. The `limit` is applied to the *fresh* set so the caller still gets up
     // to `limit` new memories even when earlier prompts already consumed some.
     let now = now_rfc3339();
     let injected_set = session_id.map(|sid| read_injected_set(&handoff, sid, &now));
-    let fresh: Vec<(usize, f64)> = ranked
-        .into_iter()
-        .filter(|(i, _)| match &injected_set {
-            Some(set) => {
-                let m = &memories[*i];
-                !set.already_injected(&m.id, &m.content_hash)
-            }
-            None => true,
-        })
-        .take(limit)
-        .collect();
+    let already_injected = |i: usize| match &injected_set {
+        Some(set) => {
+            let m = &memories[i];
+            set.already_injected(&m.id, &m.content_hash)
+        }
+        None => false,
+    };
+    let fresh = filter_already_injected(ranked, already_injected, limit);
 
     let out: Vec<Value> = fresh
         .iter()
-        .map(|(i, s)| {
-            let m = &memories[*i];
+        .map(|item| {
+            let m = &memories[item.index];
             json!({
                 "id": m.id,
                 "text": m.text,
                 "kind": m.kind,
-                "score": round2(*s),
+                "score": round2(item.score),
             })
         })
         .collect();
@@ -352,13 +351,13 @@ fn mark_injected_memories(
     handoff: &std::path::Path,
     session_id: &str,
     memories: &[MemoryEntry],
-    fresh: &[(usize, f64)],
+    fresh: &[crate::context::injection::RankItem],
     now: &str,
 ) -> Result<()> {
     let mut set = read_injected_set(handoff, session_id, now);
     set.updated_at = now.to_string();
-    for (i, _) in fresh {
-        let m = &memories[*i];
+    for item in fresh {
+        let m = &memories[item.index];
         set.mark(&m.id, &m.content_hash);
     }
     // (1) Persist the suppression record first — this is the correctness-critical
@@ -369,8 +368,8 @@ fn mark_injected_memories(
     // concurrent edit's other fields. A failure here is non-fatal: the sidecar
     // already recorded the injection, so the worst case is a slightly stale
     // hit_count — never a re-spam or a double count.
-    for (i, _) in fresh {
-        let m = &memories[*i];
+    for item in fresh {
+        let m = &memories[item.index];
         if let Ok(Some(mut entry)) = read_memory_by_id(handoff, &m.id) {
             entry.hit_count = entry.hit_count.saturating_add(1);
             entry.last_referenced_at = Some(now.to_string());
@@ -742,16 +741,6 @@ impl UnionFind {
     }
 }
 
-/// True if any `scope` prefix matches any `file` path.
-fn scope_matches(scopes: &[String], files: &[String]) -> bool {
-    if scopes.is_empty() || files.is_empty() {
-        return false;
-    }
-    scopes
-        .iter()
-        .any(|scope| files.iter().any(|f| f.contains(scope.as_str())))
-}
-
 /// Last path component of `p` (handles both `/` and `\` separators).
 fn basename(p: &str) -> String {
     p.rsplit(['/', '\\']).next().unwrap_or(p).to_string()
@@ -796,15 +785,6 @@ mod tests {
         assert_eq!(basename("plain.rs"), "plain.rs");
     }
 
-    #[test]
-    fn scope_matches_prefix() {
-        let scopes = vec!["src/storage/".to_string()];
-        let files = vec!["/repo/src/storage/mod.rs".to_string()];
-        assert!(scope_matches(&scopes, &files));
-        let files2 = vec!["/repo/src/mcp/mod.rs".to_string()];
-        assert!(!scope_matches(&scopes, &files2));
-    }
-
     #[test]
     fn string_array_parsing() {
         let v = json!({ "tags": ["a", "b", 3, "c"] });

package/src/mcp/handlers/mod.rs

@@ -7,6 +7,8 @@ pub mod check_criterion;
 pub mod config;
 pub mod config_crud;
 pub mod dashboard;
+pub mod docs;
+pub mod docs_query;
 pub mod fork_session;
 pub mod get_session;
 pub mod get_task;
@@ -95,6 +97,19 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_timer_start" => timer::handle_start(arguments),
         "handoff_timer_stop" => timer::handle_stop(arguments),
         "handoff_timer_get_time" => timer::handle_get_time(arguments),
+        "handoff_doc_save" => docs::handle_doc_save(arguments),
+        "handoff_doc_get" => docs::handle_doc_get(arguments),
+        "handoff_doc_list" => docs::handle_doc_list(arguments),
+        "handoff_doc_delete" => docs::handle_doc_delete(arguments),
+        "handoff_doc_reassemble" => docs::handle_doc_reassemble(arguments),
+        "handoff_doc_tree" => docs::handle_doc_tree(arguments),
+        "handoff_doc_graph" => docs::handle_doc_graph(arguments),
+        "handoff_doc_trace" => docs::handle_doc_trace(arguments),
+        "handoff_doc_verify" => docs::handle_doc_verify(arguments),
+        "handoff_doc_verify_status" => docs::handle_doc_verify_status(arguments),
+        "handoff_doc_query" => docs_query::handle_doc_query(arguments),
+        "handoff_doc_analyze" => docs_query::handle_doc_analyze(arguments),
+        "handoff_doc_import" => docs_query::handle_doc_import(arguments),
         _ => Err(anyhow::anyhow!("Tool not implemented: {name}")),
     };
 

package/src/mcp/handlers/update_task.rs

@@ -114,6 +114,7 @@ fn handle_create(
         completed_at: None,
         labels: extract_string_array(task_val, "labels"),
         links: extract_string_array(task_val, "links"),
+        task_links: Vec::new(),
         done_criteria: extract_done_criteria(task_val),
         schedule: extract_schedule(task_val),
         dependencies,
@@ -208,6 +209,7 @@ fn handle_upsert_create(
         completed_at: None,
         labels: extract_string_array(task_val, "labels"),
         links: extract_string_array(task_val, "links"),
+        task_links: Vec::new(),
         done_criteria: extract_done_criteria(task_val),
         schedule: extract_schedule(task_val),
         dependencies,

package/src/mcp/tools.rs

@@ -1234,6 +1234,201 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 "required": ["task_id"]
             }),
         },
+        // ---- Document management tools (P1-6a, v5 rearchitecture: wiki/130-document-management.md §3.1) ----
+        ToolDefinition {
+            name: "handoff_doc_save".to_string(),
+            description: "Create or update a document from a full Markdown body. The body is stored verbatim at _doc.<slug>.md and split in-memory into a `sections` byte-offset index (no per-section files), syncing the bidirectional task<->doc link when task_ids is given. Omit doc_id to create a new document (slug is then required and must be unique); pass an existing doc_id to update it (slug is taken from the existing document — it cannot be renamed via doc_save). Returns a JSON string {doc_id,slug,title,doc_type,section_count,content_hash,warnings:[…]} — warnings lists any task_ids that could not be resolved.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "doc_id": { "type": "string", "description": "Existing document id to update. Omit to create a new document." },
+                    "slug": { "type": "string", "description": "Human-readable file-naming slug ([a-z0-9-], max 60 chars), used to name _doc.<slug>.json/.md. Required when creating; ignored on update (the existing document's slug is kept)." },
+                    "title": { "type": "string", "description": "Document title. Required when creating; optional on update (defaults to the existing title)." },
+                    "body": { "type": "string", "description": "Full Markdown body. Required." },
+                    "doc_type": { "type": "string", "description": "Document type.", "enum": ["spec", "design", "adr", "guide", "note"], "default": "note" },
+                    "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for filtering/search." },
+                    "scope_paths": { "type": "array", "items": { "type": "string" }, "description": "Path prefixes this document applies to; boosts relevance in doc_list(query=...) when a file path matches." },
+                    "parent_id": { "type": "string", "description": "Parent document id (family tree)." },
+                    "task_ids": { "type": "array", "items": { "type": "string" }, "description": "Task ids to link bidirectionally. On update, ids removed from this list are unlinked; ids added are linked." },
+                    "related": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "rel": { "type": "string", "enum": ["supersedes", "references", "implements", "extends", "conflicts"] } }, "required": ["id", "rel"] }, "description": "Sibling/relative relationships to other documents." },
+                    "split_level": { "type": "integer", "description": "ATX heading level at/above which the body is split into sections.", "default": 2 },
+                    "auto_inject": { "type": "string", "description": "Auto-injection control.", "enum": ["auto", "full", "outline", "none"], "default": "auto" }
+                },
+                "required": ["body"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_get".to_string(),
+            description: "Read a document by doc_id or slug. format='full' returns the original Markdown body (read directly from _doc.<slug>.md) plus metadata; 'meta' returns metadata only (no body, cheap for graph traversal); 'section' returns one section's body (byte-sliced from the document body, requires seq). Returns a JSON string.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "doc_id": { "type": "string", "description": "Document id or slug to read." },
+                    "format": { "type": "string", "description": "Read mode.", "enum": ["full", "meta", "section"], "default": "full" },
+                    "seq": { "type": "integer", "description": "Section sequence number. Required when format='section'." }
+                },
+                "required": ["doc_id"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_list".to_string(),
+            description: "List/search documents. Filters (doc_type, tags [AND — every tag must be present], task_id) are applied first; an optional query BM25-ranks the survivors by title + tags + body text. include_body includes each matching document's full body, read from _doc.<slug>.md (default false — metadata only). Returns a JSON string {documents:[…]}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "doc_type": { "type": "string", "description": "Filter by document type." },
+                    "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter: document must have every listed tag (AND)." },
+                    "task_id": { "type": "string", "description": "Filter: only documents linked to this task." },
+                    "include_body": { "type": "boolean", "description": "Include each document's full body.", "default": false },
+                    "query": { "type": "string", "description": "BM25 text search over title + tags + body." }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_delete".to_string(),
+            description: "Delete a document (by doc_id or slug) and its body file. Unlinks the document from any linked tasks' task_links, removes it from its parent's children list, and clears parent_id on any of its own children (orphaning them — delete does not cascade to descendants). Returns a JSON string {deleted,doc_id,section_count,warnings:[…]}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "doc_id": { "type": "string", "description": "Document id or slug to delete." }
+                },
+                "required": ["doc_id"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_reassemble".to_string(),
+            description: "Read a document's (by doc_id or slug) original Markdown body directly from _doc.<slug>.md, restoring BOM/frontmatter, and detect drift (the body's current content hash no longer matches its recorded content_hash — e.g. edited directly outside doc_save). Optionally writes the body to output_path. Returns a JSON string {doc_id,body,drifted,output_path?}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "doc_id": { "type": "string", "description": "Document id or slug to reassemble." },
+                    "output_path": { "type": "string", "description": "Optional filesystem path to write the reassembled body to." }
+                },
+                "required": ["doc_id"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_tree".to_string(),
+            description: "Traverse a document's family tree (parent/children) starting from doc_id (id or slug), up to depth levels of descendants, plus the immediate parent (if any). include_related additionally attaches the document's related (semantic) links. Returns a JSON string tree {id,title,doc_type,parent,children:[…],related:[…]}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "doc_id": { "type": "string", "description": "Root document id or slug to traverse from." },
+                    "depth": { "type": "integer", "description": "How many levels of children to descend.", "default": 2 },
+                    "include_related": { "type": "boolean", "description": "Also include the root document's `related` entries.", "default": false }
+                },
+                "required": ["doc_id"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_verify".to_string(),
+            description: "Operate on a document's verification matrix (wiki/140-verification-matrix.md): generate (create a matrix from the document's current sections, error if one already exists), check (mark fragment_seq verified, recording verified_at/reviewer/notes/content_hash_at_verify), skip (mark fragment_seq skipped), sync (re-sync the matrix with the document's current sections — adds new sections as pending, removes deleted ones, preserves existing item status), or set_refs (update impl_refs/test_refs for fragment_seq). Overall verification_status is recomputed after every mutation: 'pending' if all items pending, 'verified' if all verified/skipped, else 'in_review'. Returns a JSON string {doc_id,verification_status,checked,skipped,pending,total,stale}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "doc_id": { "type": "string", "description": "Document id or slug to operate on." },
+                    "action": { "type": "string", "description": "Verification matrix action.", "enum": ["generate", "check", "skip", "sync", "set_refs"] },
+                    "skip_seqs": { "type": "array", "items": { "type": "integer" }, "description": "generate only: section seqs to create as 'skipped' instead of 'pending'." },
+                    "fragment_seq": { "type": "integer", "description": "check/skip/set_refs: the section seq (VerificationItem.fragment_seq) to operate on." },
+                    "reviewer": { "type": "string", "description": "check: who verified it.", "enum": ["ai", "user"] },
+                    "notes": { "type": "string", "description": "check: optional free-text note." },
+                    "impl_refs": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "lines": { "type": "string" }, "label": { "type": "string" } }, "required": ["path"] }, "description": "set_refs: implementation code references to attach to fragment_seq." },
+                    "test_refs": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "lines": { "type": "string" }, "label": { "type": "string" } }, "required": ["path"] }, "description": "set_refs: test code references to attach to fragment_seq." }
+                },
+                "required": ["doc_id", "action"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_verify_status".to_string(),
+            description: "Get a document's verification matrix status: overall verification_status, progress counts (checked/skipped/pending/total/stale/percentage), and (when include_items=true) every item with a computed stale flag (its content_hash_at_verify no longer matches the section's current content_hash — spec §3.5). Errors if the document has no verification matrix yet (use handoff_doc_verify(action='generate') first). Returns a JSON string {doc_id,title,verification_status,progress:{…},items?:[…]}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "doc_id": { "type": "string", "description": "Document id or slug to read verification status for." },
+                    "include_items": { "type": "boolean", "description": "Include the full per-item list (with stale detection).", "default": false }
+                },
+                "required": ["doc_id"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_graph".to_string(),
+            description: "Build a graph of every document in the project: nodes (one per document, with id/slug/title/doc_type/tags/task_ids/section_count/updated_at, plus verification_progress {total,verified} when include_verification=true and a matrix exists), edges (explicit parent_id -> type='parent_child'/direction='down', explicit related[] -> type=<rel>/direction='forward', and — when include_implicit=true — implicit shared_task edges for documents sharing task_ids and shared_scope edges for documents sharing scope_paths), and layers (doc ids grouped by doc_type). Intended for graph-visualization UIs. Returns a JSON string {nodes:[…],edges:[…],layers:{…}}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "include_implicit": { "type": "boolean", "description": "Also emit shared_task/shared_scope implicit edges.", "default": true },
+                    "include_verification": { "type": "boolean", "description": "Attach verification_progress {total,verified} to each node that has a verification matrix.", "default": false }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_trace".to_string(),
+            description: "Trace a document's family-tree lineage from doc_id (id or slug): direction='up' walks the child->parent chain to the root; 'down' walks parent->children (DFS); 'both' (default) merges the up chain, the target doc, and the down chain into one ordered chain (root to leaf). related (implements/references/etc.) documents encountered along the chain are appended as detour entries. Multi-child forks encountered in the down direction are additionally reported in branches[] (one entry per fork, {fork_from,docs:[…]}). Cycle-safe: a visited set skips any document already seen in the traversal. Returns a JSON string {chain:[{id,title,doc_type,rel}…],branches:[{fork_from,docs:[…]}…]}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "doc_id": { "type": "string", "description": "Document id or slug to trace from." },
+                    "direction": { "type": "string", "description": "Traversal direction.", "enum": ["up", "down", "both"], "default": "both" }
+                },
+                "required": ["doc_id"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_query".to_string(),
+            description: "Inject document sections relevant to the current prompt/file/task (hook-driven context injection, mirrors memory_query at section granularity). Ranks by BM25 relevance + scope_paths match + task_id affinity, then stages each result as 'full' (whole section body, when its token estimate is within the inline threshold) or 'outline' (heading + sibling table of contents only, for larger sections — fetch the body via doc_get(format='section')). With session_id, already-injected sections (same content_hash) are skipped this session; mark_injected (default true) records survivors. suppress_doc_ids excludes given documents from this call's results; combined with suppress_until_changed=true (requires session_id), the suppression is recorded in the session's injected sidecar and persists across future calls until that document's content_hash changes. Returns a JSON string {documents:[…],injected_count}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "text": { "type": "string", "description": "Prompt/query text to rank sections against." },
+                    "file_paths": { "type": "array", "items": { "type": "string" }, "description": "File paths in play; boosts documents whose scope_paths match." },
+                    "task_id": { "type": "string", "description": "Boost sections belonging to documents linked to this task (highest-weight ranking signal)." },
+                    "session_id": { "type": "string", "description": "Session id for per-session diff injection (skips sections already injected at their current content_hash)." },
+                    "limit": { "type": "integer", "description": "Max number of sections to return.", "default": 5 },
+                    "mark_injected": { "type": "boolean", "description": "Record returned sections in the session's injected sidecar.", "default": true },
+                    "suppress_doc_ids": { "type": "array", "items": { "type": "string" }, "description": "Document ids to exclude entirely from this call's results." },
+                    "suppress_until_changed": { "type": "boolean", "description": "With suppress_doc_ids and session_id: persist the suppression in the session's injected sidecar so those documents stay excluded from future doc_query calls until their content_hash changes.", "default": false }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_analyze".to_string(),
+            description: "Read-only scan of a Markdown file or directory (never writes). Auto-detects doc_type (keyword scan), tags (frontmatter + heading tokens), scope_paths (code/inline file paths), and a suggested_slug (derived from title) per file; extracts and classifies Markdown links (internal/external/broken); proposes a parent/children tree from directory structure (skip with flatten=true). Returns a JSON conditioning report {files_scanned,auto_resolved:[…],needs_review:[…],proposed_tree:{…}} for AI review before handoff_doc_import.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "path": { "type": "string", "description": "File or directory path (relative to project_dir) to scan." },
+                    "recursive": { "type": "boolean", "description": "Recurse into subdirectories when path is a directory.", "default": true },
+                    "flatten": { "type": "boolean", "description": "Skip parent/children tree inference; every file is a standalone document.", "default": false }
+                },
+                "required": ["path"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_doc_import".to_string(),
+            description: "Bulk-write an analyzed payload (from handoff_doc_analyze, with the AI's overrides applied) as new documents. Each analyzed.auto_resolved entry must carry its file's full Markdown 'body' (doc_import writes from the payload, it does not re-read the filesystem). Each document's slug is taken from its override's 'slug' if given, else its suggested_slug, disambiguated with a numeric suffix on collision. Persists every file as a document, applies proposed_tree parent/children relationships, links task_ids to every imported document (bidirectionally), and invalidates the doc corpus cache. Returns a JSON string {imported_count,documents:[{doc_id,slug,title,section_count}],warnings:[…]}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "analyzed": { "type": "object", "description": "The handoff_doc_analyze report, with each auto_resolved entry additionally carrying its file's 'body'." },
+                    "overrides": { "type": "array", "items": { "type": "object", "properties": { "file": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "doc_type": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "scope_paths": { "type": "array", "items": { "type": "string" } } }, "required": ["file"] }, "description": "Per-file AI overrides applied on top of analyzed.auto_resolved before writing." },
+                    "task_ids": { "type": "array", "items": { "type": "string" }, "description": "Link every imported document to these tasks (bidirectionally)." }
+                },
+                "required": ["analyzed"]
+            }),
+        },
     ]
 }