# Exploration Tools

Six tools for intent-aware search, pattern-based scanning, structural hole detection, stacktrace analysis, temporal history, and multi-repository federation.

---

<a id="m1ndseek"></a>

## `seek`
Intent-aware semantic code search. Finds code by **purpose**, not text pattern. Combines keyword matching, graph activation (PageRank), and trigram similarity for ranking.

Unlike `activate` (which propagates signal through edges), `seek` scores every node independently against the query, making it better for finding specific code when you know what it *does* but not where it *lives*.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | `string` | Yes | -- | Natural language description of what the agent is looking for. Example: `"code that validates user credentials"`. |
| `agent_id` | `string` | Yes | -- | Calling agent identifier. |
| `top_k` | `integer` | No | `20` | Maximum results to return. |
| `scope` | `string` | No | -- | File path prefix to limit search scope. Example: `"backend/"`. `None` = entire graph. |
| `node_types` | `string[]` | No | `[]` | Filter by node type: `"function"`, `"class"`, `"struct"`, `"module"`, `"file"`. Empty = all types. |
| `min_score` | `number` | No | `0.1` | Minimum combined score threshold. Range: 0.0 to 1.0. |
| `graph_rerank` | `boolean` | No | `true` | Whether to run graph re-ranking (PageRank weighting) on candidates. Disable for pure text matching. |

### Scoring Formula (V1)

```
combined = keyword_match * 0.6 + graph_activation * 0.3 + trigram * 0.1
```

V2 upgrade path will replace keyword matching with real embeddings (fastembed-rs + jina-embeddings-v2-base-code).

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "seek",
    "arguments": {
      "agent_id": "jimi",
      "query": "code that validates user credentials",
      "top_k": 5,
      "node_types": ["function", "class"]
    }
  }
}
```

### Example Response

```json
{
  "query": "code that validates user credentials",
  "results": [
    {
      "node_id": "file::auth_discovery.py::fn::validate_credentials",
      "label": "validate_credentials",
      "type": "function",
      "score": 0.87,
      "score_breakdown": {
        "embedding_similarity": 0.92,
        "graph_activation": 0.78,
        "temporal_recency": 0.65
      },
      "intent_summary": "Validates user credentials against provider store",
      "file_path": "backend/auth_discovery.py",
      "line_start": 45,
      "line_end": 82,
      "connections": [
        { "node_id": "file::principal_registry.py", "label": "principal_registry.py", "relation": "calls" }
      ]
    }
  ],
  "total_candidates_scanned": 9767,
  "embeddings_used": false,
  "elapsed_ms": 25.0
}
```

### When to Use

- **"Find the code that does X"** -- when you know the purpose, not the filename
- **Codebase onboarding** -- exploring unfamiliar code by intent
- **Pre-modification search** -- find all code related to a feature before changing it

### Related Tools

- [`activate`](activation.md#m1ndactivate) -- graph-propagation search (better for exploring neighborhoods)
- [`scan`](#m1ndscan) -- pattern-based structural analysis (finds anti-patterns, not features)

---

<a id="m1ndscan"></a>

## `scan`
Pattern-aware structural code analysis with graph-validated findings. Detects structural issues using predefined patterns, then validates each finding against the graph to filter false positives. Works across file boundaries.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `pattern` | `string` | Yes | -- | Pattern ID or custom pattern string. Built-in patterns: `"error_handling"`, `"resource_cleanup"`, `"api_surface"`, `"state_mutation"`, `"concurrency"`, `"auth_boundary"`, `"test_coverage"`, `"dependency_injection"`. |
| `agent_id` | `string` | Yes | -- | Calling agent identifier. |
| `scope` | `string` | No | -- | File path prefix to limit scan scope. |
| `severity_min` | `number` | No | `0.3` | Minimum severity threshold. Range: 0.0 to 1.0. |
| `graph_validate` | `boolean` | No | `true` | Validate findings against graph edges (cross-file analysis). Disable for raw pattern matching only. |
| `limit` | `integer` | No | `50` | Maximum findings to return. |

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "scan",
    "arguments": {
      "agent_id": "jimi",
      "pattern": "error_handling",
      "scope": "backend/",
      "severity_min": 0.5
    }
  }
}
```

### Example Response

```json
{
  "pattern": "error_handling",
  "findings": [
    {
      "pattern": "error_handling",
      "status": "confirmed",
      "severity": 0.78,
      "node_id": "file::spawner.py::fn::spawn_agent",
      "label": "spawn_agent",
      "file_path": "backend/spawner.py",
      "line": 89,
      "message": "Bare except clause catches all exceptions including KeyboardInterrupt",
      "graph_context": [
        { "node_id": "file::process_manager.py", "label": "process_manager.py", "relation": "calls" }
      ]
    }
  ],
  "files_scanned": 77,
  "total_matches_raw": 23,
  "total_matches_validated": 8,
  "elapsed_ms": 150.0
}
```

### Finding Status Values

| Status | Meaning |
|--------|---------|
| `"confirmed"` | Graph validation confirms the issue is real |
| `"mitigated"` | The issue exists but is handled by a related module |
| `"false_positive"` | Graph context shows the pattern match is not actually an issue |

### When to Use

- **Code quality audit** -- scan for anti-patterns across the codebase
- **Security review** -- use `"auth_boundary"` to find auth bypass paths
- **Pre-deploy check** -- scan for `"error_handling"` and `"resource_cleanup"` issues
- **Test gaps** -- use `"test_coverage"` to find untested code

### Related Tools

- [`hypothesize`](analysis.md#m1ndhypothesize) -- test a specific structural claim
- [`trace`](#m1ndtrace) -- analyze a specific error (not patterns)

---

<a id="m1ndmissing"></a>

## `missing`
Detect structural holes and missing connections. Given a topic query, finds areas where the graph suggests something *should* exist but does not. Identifies absent abstractions, missing connections, and incomplete patterns.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | `string` | Yes | -- | Search query to find structural holes around. |
| `agent_id` | `string` | Yes | -- | Calling agent identifier. |
| `min_sibling_activation` | `number` | No | `0.3` | Minimum sibling activation threshold. Siblings with activation below this are not considered for hole detection. |

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "missing",
    "arguments": {
      "agent_id": "jimi",
      "query": "database connection pooling",
      "min_sibling_activation": 0.3
    }
  }
}
```

### Example Response

```json
{
  "query": "database connection pooling",
  "holes": [
    {
      "node_id": "structural_hole_1",
      "label": "connection lifecycle",
      "type": "structural_hole",
      "reason": "No dedicated connection pool abstraction -- 4 adjacent modules manage connections independently"
    },
    {
      "node_id": "structural_hole_2",
      "label": "pool metrics",
      "type": "structural_hole",
      "reason": "No pool health monitoring -- 3 adjacent modules expose metrics but pool does not"
    }
  ],
  "total_holes": 9,
  "elapsed_ms": 67.0
}
```

### When to Use

- **Gap analysis** -- "what am I missing?" before implementing a feature
- **Pre-spec** -- identify areas that need design before building
- **Architecture review** -- find missing abstractions or connections
- **Feature completeness** -- after building, check for structural holes around the feature

### Related Tools

- [`activate`](activation.md#m1ndactivate) -- activate with `include_structural_holes: true` for inline hole detection
- [`hypothesize`](analysis.md#m1ndhypothesize) -- test a specific claim about missing structure

---

<a id="m1ndtrace"></a>

## `trace`
Map runtime errors to structural root causes via stacktrace analysis. Parses the stacktrace, maps frames to graph nodes, and scores each node's suspiciousness using trace depth, modification recency, and centrality. Also finds co-change suspects (files modified around the same time as the top suspect).

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `error_text` | `string` | Yes | -- | Full error output (stacktrace + error message). |
| `agent_id` | `string` | Yes | -- | Calling agent identifier. |
| `language` | `string` | No | -- | Language hint: `"python"`, `"rust"`, `"typescript"`, `"javascript"`, `"go"`. Auto-detected if omitted. |
| `window_hours` | `number` | No | `24.0` | Temporal window (hours) for co-change suspect scan. |
| `top_k` | `integer` | No | `10` | Max suspects to return. |

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "trace",
    "arguments": {
      "agent_id": "jimi",
      "error_text": "Traceback (most recent call last):\n  File \"backend/chat_handler.py\", line 234, in handle_message\n  File \"backend/session_pool.py\", line 89, in acquire\n  File \"backend/worker_pool.py\", line 156, in submit\nTimeoutError: pool exhausted",
      "language": "python",
      "top_k": 5
    }
  }
}
```

### Example Response

```json
{
  "language_detected": "python",
  "error_type": "TimeoutError",
  "error_message": "pool exhausted",
  "frames_parsed": 3,
  "frames_mapped": 3,
  "suspects": [
    {
      "node_id": "file::worker_pool.py::fn::submit",
      "label": "submit",
      "type": "function",
      "suspiciousness": 0.91,
      "signals": { "trace_depth_score": 1.0, "recency_score": 0.85, "centrality_score": 0.88 },
      "file_path": "backend/worker_pool.py",
      "line_start": 150,
      "line_end": 175,
      "related_callers": ["session_pool.py::acquire"]
    },
    {
      "node_id": "file::session_pool.py::fn::acquire",
      "label": "acquire",
      "type": "function",
      "suspiciousness": 0.78,
      "signals": { "trace_depth_score": 0.67, "recency_score": 0.72, "centrality_score": 0.65 },
      "file_path": "backend/session_pool.py",
      "line_start": 80,
      "line_end": 110,
      "related_callers": ["chat_handler.py::handle_message"]
    }
  ],
  "co_change_suspects": [
    { "node_id": "file::config.py", "label": "config.py", "modified_at": 1710295000.0, "reason": "Modified within 2h of top suspect" }
  ],
  "causal_chain": ["worker_pool.py::submit", "session_pool.py::acquire", "chat_handler.py::handle_message"],
  "fix_scope": {
    "files_to_inspect": ["backend/worker_pool.py", "backend/session_pool.py", "backend/config.py"],
    "estimated_blast_radius": 23,
    "risk_level": "medium"
  },
  "unmapped_frames": [],
  "elapsed_ms": 3.5
}
```

### Suspiciousness Scoring

| Signal | Weight | Description |
|--------|--------|-------------|
| `trace_depth_score` | High | 1.0 = deepest frame (most specific); decays linearly |
| `recency_score` | Medium | Exponential decay from last modification time |
| `centrality_score` | Medium | Normalized PageRank centrality |

### When to Use

- **Bug investigation** -- paste an error and get ranked suspects
- **Root cause analysis** -- the causal chain shows the error propagation path
- **Fix scoping** -- `fix_scope` tells you which files to inspect and the risk level

### Related Tools

- [`hypothesize`](analysis.md#m1ndhypothesize) -- test a hypothesis about the root cause
- [`impact`](analysis.md#m1ndimpact) -- assess the blast radius of a fix
- [`validate_plan`](lifecycle.md#m1ndvalidate_plan) -- validate your fix plan before implementing

---

<a id="m1ndtimeline"></a>

## `timeline`
Git-based temporal history for a node. Returns the change history, co-change partners, velocity, stability score, and churn data for a specific file or module.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `node` | `string` | Yes | -- | Node external_id. Example: `"file::backend/chat_handler.py"`. |
| `agent_id` | `string` | Yes | -- | Calling agent identifier. |
| `depth` | `string` | No | `"30d"` | Time depth. Values: `"7d"`, `"30d"`, `"90d"`, `"all"`. |
| `include_co_changes` | `boolean` | No | `true` | Include co-changed files with coupling scores. |
| `include_churn` | `boolean` | No | `true` | Include lines added/deleted churn data. |
| `top_k` | `integer` | No | `10` | Max co-change partners to return. |

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "timeline",
    "arguments": {
      "agent_id": "jimi",
      "node": "file::backend/chat_handler.py",
      "depth": "30d",
      "top_k": 5
    }
  }
}
```

### Example Response

```json
{
  "node": "file::backend/chat_handler.py",
  "depth": "30d",
  "changes": [
    {
      "date": "2026-03-10",
      "commit": "a1b2c3d",
      "author": "cosmophonix",
      "delta": "+45/-12",
      "co_changed": ["stream_parser.py", "chat_routes.py"]
    },
    {
      "date": "2026-03-05",
      "commit": "e4f5g6h",
      "author": "cosmophonix",
      "delta": "+120/-30",
      "co_changed": ["session_pool.py", "worker_pool.py"]
    }
  ],
  "co_changed_with": [
    { "file": "stream_parser.py", "times": 8, "coupling_degree": 0.72 },
    { "file": "chat_routes.py", "times": 6, "coupling_degree": 0.55 },
    { "file": "session_pool.py", "times": 4, "coupling_degree": 0.38 }
  ],
  "velocity": "accelerating",
  "stability_score": 0.35,
  "pattern": "churning",
  "total_churn": { "lines_added": 580, "lines_deleted": 120 },
  "commit_count_in_window": 12,
  "elapsed_ms": 45.0
}
```

### Velocity Values

| Value | Meaning |
|-------|---------|
| `"accelerating"` | Change frequency is increasing |
| `"decelerating"` | Change frequency is decreasing |
| `"stable"` | Consistent change rate |

### Pattern Values

| Value | Meaning |
|-------|---------|
| `"expanding"` | Growing (net positive churn) |
| `"shrinking"` | Reducing (net negative churn) |
| `"churning"` | High add+delete with little net growth |
| `"dormant"` | Few or no changes in the window |
| `"stable"` | Small, consistent changes |

### When to Use

- **Hotspot detection** -- find files that change too frequently (stability_score < 0.3)
- **Co-change discovery** -- find files that always change together (coupling_degree > 0.6)
- **Refactoring signals** -- churning files may need redesign

### Related Tools

- [`diverge`](analysis.md#m1nddiverge) -- structural drift across the whole codebase
- [`predict`](analysis.md#m1ndpredict) -- predict co-changes for a given modification

---

<a id="m1ndfederate"></a>

## `federate`
Ingest multiple repositories into a unified federated graph with automatic cross-repo edge detection. After federation, all existing query tools (`activate`, `impact`, `why`, etc.) traverse cross-repo edges automatically.

Node IDs in the federated graph use `{repo_name}::file::path` format.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `agent_id` | `string` | Yes | -- | Calling agent identifier. |
| `repos` | `object[]` | Yes | -- | List of repositories to federate. Each object has: `name` (string, required -- namespace prefix), `path` (string, required -- absolute path), `adapter` (string, default `"code"`). |
| `detect_cross_repo_edges` | `boolean` | No | `true` | Auto-detect cross-repo edges: config, API, import, type, deployment, MCP contract. |
| `incremental` | `boolean` | No | `false` | Only re-ingest repos that changed since last federation. |

### Cross-Repo Edge Types

| Edge Type | Description |
|-----------|-------------|
| `shared_config` | Two repos reference the same configuration key |
| `api_contract` | One repo's API client matches another's API server |
| `package_dep` | Direct package dependency |
| `shared_type` | Same type/interface definition used across repos |
| `deployment_dep` | Deployment configuration dependency |
| `mcp_contract` | MCP tool consumer/provider relationship |

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "federate",
    "arguments": {
      "agent_id": "jimi",
      "repos": [
        { "name": "backend", "path": "/project/backend" },
        { "name": "frontend", "path": "/project/frontend" },
        { "name": "mcp-server", "path": "/project/mcp-server", "adapter": "code" }
      ],
      "detect_cross_repo_edges": true,
      "incremental": false
    }
  }
}
```

### Example Response

```json
{
  "repos_ingested": [
    { "name": "backend", "path": "/project/backend", "node_count": 9767, "edge_count": 26557, "from_cache": false, "ingest_ms": 910.0 },
    { "name": "frontend", "path": "/project/frontend", "node_count": 1200, "edge_count": 3500, "from_cache": false, "ingest_ms": 320.0 },
    { "name": "mcp-server", "path": "/project/mcp-server", "node_count": 250, "edge_count": 680, "from_cache": false, "ingest_ms": 85.0 }
  ],
  "total_nodes": 11217,
  "total_edges": 30737,
  "cross_repo_edges": [
    {
      "source_repo": "frontend",
      "target_repo": "backend",
      "source_node": "frontend::file::src/lib/apiConfig.ts",
      "target_node": "backend::file::main.py",
      "edge_type": "api_contract",
      "relation": "calls_api",
      "weight": 0.85,
      "causal_strength": 0.72
    },
    {
      "source_repo": "mcp-server",
      "target_repo": "backend",
      "source_node": "mcp-server::file::src/mcp-server.js",
      "target_node": "backend::file::main.py",
      "edge_type": "mcp_contract",
      "relation": "calls_api",
      "weight": 0.78,
      "causal_strength": 0.65
    }
  ],
  "cross_repo_edge_count": 18203,
  "incremental": false,
  "skipped_repos": [],
  "elapsed_ms": 1315.0
}
```

### When to Use

- **Multi-repo projects** -- analyze dependencies across frontend, backend, and infrastructure repos
- **Monorepo decomposition** -- understand how packages depend on each other
- **API impact analysis** -- find which repos are affected by an API change

### Related Tools

- [`ingest`](lifecycle.md#m1ndingest) -- single-repo ingestion
- [`impact`](analysis.md#m1ndimpact) -- blast radius analysis (works across federated repos)
- [`why`](memory.md#m1ndwhy) -- path explanation (traverses cross-repo edges)

<a id="m1ndfederate_auto"></a>

## `federate_auto`
Turn explicit external path evidence, local manifest/workspace hints, import/package-name evidence, shared API-route signals, or contract artifacts such as `.proto`, MCP tools, and OpenAPI into repo candidates, namespace suggestions, and an optional one-shot `federate` call.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `agent_id` | `string` | Yes | -- | Calling agent identifier. |
| `scope` | `string` | No | -- | File path prefix to limit discovery sources. |
| `current_repo_name` | `string` | No | auto | Optional namespace override for the current workspace. |
| `max_repos` | `integer` | No | `8` | Maximum discovered external repos to include. |
| `detect_cross_repo_edges` | `boolean` | No | `true` | Whether `execute=true` should auto-detect cross-repo edges. |
| `execute` | `boolean` | No | `false` | If true, immediately run `federate` with the current repo plus discovered candidates. |

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "federate_auto",
    "arguments": {
      "agent_id": "jimi",
      "scope": "docs",
      "execute": false
    }
  }
}
```

### Example Response

```json
{
  "current_repo": { "namespace": "m1nd", "repo_root": "/repo/m1nd" },
  "discovered_repos": [
    {
      "namespace": "runtime",
      "repo_root": "/repo/runtime",
      "marker": ".git",
      "confidence": "high",
      "evidence_types": ["markdown_link"],
      "source_nodes": ["file::docs/architecture.md"],
      "source_files": ["/repo/m1nd/docs/architecture.md"],
      "sampled_paths": ["/repo/runtime/docs/ARCH.md"],
      "suggested_action": "run federate_auto with execute=true or pass suggested_repos into federate"
    }
  ],
  "suggested_repos": [
    { "name": "runtime", "path": "/repo/runtime", "adapter": "code" }
  ],
  "skipped_paths": [],
  "executed": false,
  "federate_result": null,
  "elapsed_ms": 42.0
}
```

### When to Use

- **Cross-repo audits** -- when `audit` or `external_references` already surfaced sibling repo paths
- **Manifest-driven workspaces** -- when `Cargo.toml`, `package.json`, `pnpm-workspace.yaml`, `pyproject.toml`, or `go.work` already point at sibling repos
- **Import-driven discovery** -- when code already imports a sibling package/crate name but the current repo has no explicit path hint
- **Contract-driven discovery** -- when nearby repos expose `.proto` or MCP tool contracts that the current workspace already references by name
- **OpenAPI-driven discovery** -- when the current workspace references `operationId`s or routes defined in a nearby OpenAPI/Swagger spec
- **Schema-driven discovery** -- when the current workspace references message/component names defined in `.proto` or OpenAPI schemas
- **Planning/doc hubs** -- when docs point to runtime repos and you want a namespace plan without manual copy-paste
- **Worktree-heavy setups** -- when the current workspace path is a worktree but you still want repo-shaped namespace suggestions

### Related Tools

- [`external_references`](overview.md) -- raw external path evidence
- [`federate`](#m1ndfederate) -- explicit multi-repo federation
- [`audit`](overview.md) -- broader audit that can surface the evidence before auto-federation

---

<a id="m1ndbatch_view"></a>

## `batch_view`
Read multiple files or glob-resolved files in one call with stable delimiters, optional summaries, and optional auto-ingest.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | `string` | Yes | Calling agent identifier. |
| `files` | `string[]` | Yes | File paths and/or glob patterns to expand. |
| `auto_ingest` | `boolean` | No | Auto-ingest discovered files before reading. |
| `summary_mode` | `boolean` | No | Add inline per-file summaries. |

### When to Use

- Audit proof packets
- Compact multi-file reading after search/glob
- Agent handoff packages

### Related Tools

- [`glob`](#m1ndglob)
- [`coverage_session`](#m1ndcoverage_session)
- [`audit`](../api-reference/lifecycle.md#m1ndaudit)

---

<a id="m1ndscan_all"></a>

## `scan_all`
Run all structural scan patterns in one call and return grouped findings by pattern.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | `string` | Yes | Calling agent identifier. |
| `scope` | `string` | No | Scope path prefix. |
| `patterns` | `string[]` | No | Subset of scan patterns to run. |
| `limit_per_pattern` | `integer` | No | Maximum findings per pattern. |

### When to Use

- Broad first-pass quality/security audit
- Pre-hardening sweep before prioritizing fixes

### Related Tools

- [`scan`](#m1ndscan)
- [`batch_view`](#m1ndbatch_view)
- [`audit`](../api-reference/lifecycle.md#m1ndaudit)

---

<a id="m1ndcross_verify"></a>

## `cross_verify`
Compare graph state against filesystem truth: existence, LOC drift, and optional hash mismatches.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | `string` | Yes | Calling agent identifier. |
| `scope` | `string` | No | Path prefix to limit verification. |
| `check` | `string[]` | No | Checks to run such as `existence`, `loc`, `hash`. |
| `include_dotfiles` | `boolean` | No | Include selected dotfiles in verification. |

### When to Use

- To verify graph and disk still agree
- After daemon drift alerts
- Before trusting an audit result on a changing repo

### Related Tools

- [`audit`](../api-reference/lifecycle.md#m1ndaudit)
- [`external_references`](#m1ndexternal_references)

---

<a id="m1ndcoverage_session"></a>

## `coverage_session`
Report what the current agent session has already read or touched.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | `string` | Yes | Calling agent identifier. |

### When to Use

- To avoid re-reading files during long sessions
- To build a compact unread-next list after search/audit sweeps

### Related Tools

- [`batch_view`](#m1ndbatch_view)
- [`search`](../api-reference/lifecycle.md#m1ndsearch)

---

<a id="m1ndexternal_references"></a>

## `external_references`
Find explicit path references that point outside current ingest roots.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | `string` | Yes | Calling agent identifier. |
| `scope` | `string` | No | Optional scope prefix. |

### When to Use

- Before federation when docs/config already point outside the repo
- To surface repo-boundary evidence in audits

### Related Tools

- [`federate_auto`](#m1ndfederate_auto)
- [`audit`](../api-reference/lifecycle.md#m1ndaudit)

---

<a id="m1ndglob"></a>

## `glob`
Graph-aware file globbing over already indexed files.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | `string` | Yes | Calling agent identifier. |
| `pattern` | `string` | Yes | Glob pattern. |
| `scope` | `string` | No | Optional path prefix. |
| `sort` | `string` | No | Sort order such as `path` or `activation`. |

### When to Use

- When you need filenames by pattern, not content
- Before `batch_view` on a file family

### Related Tools

- [`search`](../api-reference/lifecycle.md#m1ndsearch)
- [`batch_view`](#m1ndbatch_view)

---

<a id="m1ndview"></a>

## `view`
Fast line-numbered file inspection with optional auto-ingest if the file is not yet in the graph.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | `string` | Yes | Calling agent identifier. |
| `file_path` | `string` | Yes | Absolute or workspace-relative file path. |
| `auto_ingest` | `boolean` | No | Auto-ingest file into the graph if not present. |
| `offset` | `integer` | No | Start line offset. |
| `limit` | `integer` | No | Max lines to return. |

### When to Use

- Quick inspection when you already know the file
- Narrow, bounded reads before a surgical context call

### Related Tools

- [`batch_view`](#m1ndbatch_view)
- [`surgical_context`](../api-reference/lifecycle.md#m1ndsurgical_context)
