Search code AND documents in the project's local index — your FIRST tool to find, explore or investigate anything here, before broad file reads or grep.

Runs a semantic hybrid search (vector + BM25, fused via RRF) over pre-indexed chunks of source code (classes/functions/methods) and documents (Markdown, text, JSON/YAML/ TOML). Pass natural language or exact symbols. To get your bearings in an unfamiliar project first, use atlas_brief.

Token-efficient two-pass pattern: by default this returns metadata only (file_path, lines, symbol, type, score). Locate first, then read the exact lines with Read, or re-call with include_content=true for the few results whose content you actually need.

Call directly — do NOT call atlas_status first "just to check". If the index does not exist yet, this raises an actionable error explaining how to build it (see atlas_index).

Omit response_profile to respect the operator configuration. Do not select "full" routinely: it overrides ATLAS_CONTEXT_OPTIMIZATION even when enabled. Start with metadata and expand only symbols needed to close an evidence gap. Start with only one or two directly relevant symbols; inspect their contents before expanding helpers, types or additional results. Do not expand every search hit automatically. Stop when the task has sufficient evidence. Use atlas_expand(refs) for omitted content; use "full" only when explicitly requested or when fields omitted by the compact format are required.

Query the derived knowledge graph for hubs, paths, neighborhood explanations, or the reverse-impact radius of a node.

Call this directly when the question is about connectivity, rationale, centrality, or "what breaks if I change this?" in the indexed workspace. It reads the derived graph.json produced by atlas_index; it does not rebuild the graph itself.

Assemble a task-oriented context pack for a symbol or file in one call.

Use this first when you already know which symbol or file you will edit, debug, review, or understand. It composes neighborhood, impact radius, inferred tests and brief layer under a token budget so you do not need to chain atlas_graph / atlas_brief / atlas_search yourself.

Omit response_profile to respect the operator configuration. An explicit "full" overrides ATLAS_CONTEXT_OPTIMIZATION; use it only when requested or when the full representation is required.

Expand compact search references by chunk id — no embedding and no Jev.

Start with only one or two refs, then inspect the response before expanding more. Each additional ref must fill a specific evidence gap. Use three to five only when the task already requires comparing those symbols; never open all hits automatically. Stop when there is enough evidence to answer.

Pass up to five ref values from a compact atlas_search response. Each ref identifies a chunk in the current index (not a historical snapshot). Legacy Base64 references are also supported. If the file changed or the chunk is gone, the item is marked obsolete without returning stale lines. Content comes from the original symbol's indexed line range, including text truncated during indexing. If content_complete is false, pass next_ref to atlas_expand again and concatenate content in content_range order (character offsets, exclusive end). Follow next_ref only if the remaining content is needed; a complete symbol requires all its pages. Continuations are tied to the file hash and need no session cache.

A large class comes back as its header plus outline: the class's methods, each with its own ref and line range. Expand only the methods you need; follow next_ref only if you really need the whole class body.

Get a pre-computed, token-bounded briefing that orients you in an unfamiliar project.

Call this FIRST, once, when you start working on a project you do not already know. It replaces the usual orientation ritual (listing directories, reading the README, opening several files just to get your bearings) with a single small response.

Returns a ranked summary: identity (repo, language distribution, size), layers (the main directories, what role each plays, and their most important files), entrypoints (how the project is actually started), and hubs (the most connected files — the ones whose change propagates furthest). Every list is ranked and capped, so the response size does NOT grow with the size of the repository.

Do NOT call this to enumerate symbols or files: by design it reports at most a handful of layers and a few files per layer. Use atlas_search (optionally with path_prefix) to find a specific implementation, and atlas_graph to explore connectivity. Do NOT call it more than once per session — the briefing only changes after atlas_index re-runs.

Facts are derived deterministically from the index; nothing is guessed. Entries carry confidence (declared when read from a manifest such as pyproject/package.json, inferred when detected in code) and warnings reports known gaps, e.g. graph_unavailable, no_import_edges, low_symbol_coverage, index_stale.

Staleness is detected by comparing the indexed git HEAD with the current one, so uncommitted edits are not detected (same limitation as atlas_status).

Get diagnostic metadata and health status of the local vector index.

Use this only for explicit diagnostics (e.g. the user asks about index health, staleness, or which repos/languages are indexed) or to decide whether atlas_index should be run. It is NOT a precondition for atlas_search/atlas_brief — call those directly; they raise an actionable error themselves if the index is missing. Never indexes anything itself.

Returns: JSON string with index_exists, total_chunks, repos_indexed, languages_indexed, embedding_model, embedding_backend, storage_backend, index_path, index_resolution (how the index directory was resolved: "cli-arg" | "env" | "discovery" | "editor-project-dir" | "roots" | "roots-fallback" | "editor-project-dir-fallback" | "cwd-fallback" — useful to diagnose client misconfiguration when index_exists is unexpectedly false), last_indexed_at, git_head_sha, is_stale (true when the indexed git HEAD differs from the workspace's current HEAD), and reindexing (true when another process currently holds the reindex lock for this index).

Also `resolution_coverage`: which languages had their imports resolved and
how. Either `{scip: [...], treesitter: [...], none: [...], files_unresolved: N}`
— each language in exactly one tier, `none` meaning "indexed and searchable,
but mute about how it connects" — or `{status: "unknown", reason:
"index_version_below_2_2_0"}` for an index built before 2.2.0. Never trust an
absent tier as "nothing to resolve".

And `watch`: whether this server is watching the workspace for changes —
"active" (watching; edits trigger an incremental reindex after a debounce),
"disabled" (ATLAS_WATCH not set — the default), "unavailable" (ATLAS_WATCH
set but the optional `watchdog` dependency is not installed) or "failed"
(the observer could not start; see stderr). Only "active" means the index
keeps itself current while the server runs.

Index (or re-index) source code and documents into the local search index.

Use to build the index the first time, or to refresh it after atlas_status reports is_stale: true or large changes.

IMPORTANT: unless the user already said what to index, call with dry_run=true first, show the candidate folders, and ASK whether to index everything or specific folders. Then call again with the chosen 'paths' (or none for the whole workspace).

Incremental by default: unchanged files (by content hash) are skipped, so re-runs are fast. full=true forces a complete rebuild.

full=true or empty/omitted 'paths' (whole-workspace) run asynchronously in a background subprocess and return immediately — poll atlas_status (reindexing: true while running). A non-empty 'paths' with full=false runs synchronously and returns stats directly.