Use this tool FIRST for 'where is X documented?', 'which file covers Y?', or 'which section defines Z?'.
Follow up with `atlas_read(anchor)` only if you need the section body, or fall back to `atlas_search`
if you need multiple ranked snippets across documents.

Behavior & Output:
- Read-only, deterministic BM25 lookup against the local SQLite FTS5 index (auto-refreshed before query).
- Returns a JSON string with `{found: true, anchor, heading, path, line, alternatives}` when matched,
  or `{found: false, hint}` when no section matches.

Use this tool for broad or multi-section topics ('where all is armor mentioned?') or when
`atlas_where` returns no single match. Pass a returned `anchor` to `atlas_read` to inspect the full section.

Behavior & Output:
- Read-only lexical search via SQLite FTS5 (no embeddings; project synonyms come from `.atlas/aliases.yml`).
- Returns a JSON string `{query, count, hits: [{anchor, title, path, line, snippet, score}]}`.
  Returns `count: 0` and an empty `hits` list if nothing matches.

Use this tool after obtaining an `anchor` from `atlas_where`, `atlas_search`, or `atlas_outline`.
Never read raw documentation files from disk when `atlas_read` can fetch the exact section.

Behavior & Output:
- Read-only lookup from the local documentation index.
- Returns a JSON string `{anchor, heading, path, lines, content, truncated, next_offset}`.
  If the anchor does not exist, returns `{error, suggestions}` with the closest valid anchors.

Use this tool when exploring an unfamiliar project structure, browsing available documents,
or when keyword searches (`atlas_where` / `atlas_search`) did not match your query terms.

Behavior & Output:
- Read-only, side-effect-free query of indexed document headings.
- Returns a JSON string `{doc, outline, truncated}` where `outline` lists each heading level,
  title, and `anchor` ready for `atlas_read`.

Use this tool to inspect granular checklist items embedded in specs. To inspect numbered
high-level Work Orders (`Work Order N — ⬜ OPEN / ✅ DONE`), use `atlas_status` instead.

Behavior & Output:
- Read-only query over indexed Markdown checkboxes.
- Returns a JSON string `{status, owner, count, tasks: [{text, done, owner, tags, anchor, path, line}]}`.

Use this tool to answer 'which code files implement this spec section?' or 'what other sections
reference or belong to the same document as this anchor?'.

Behavior & Output:
- Read-only lookup against the local section graph and frontmatter metadata (`implements`, `tags`).
- Returns a JSON string `{anchor, heading, path, implements: [...], tags: [...], outgoing_links: [...], incoming_links: [...], siblings: [...]}`
  or `{error}` if the anchor is unknown.

Use this tool before starting or delegating a feature task. It bundles the top matching spec
sections (with stable anchors), linked source file paths, open tasks, project guardrails, and
the verified checkoff command so the subagent does not need to search from scratch.

Behavior & Output:
- Read-only aggregation of indexed documentation sections and code metadata.
- Returns a formatted Markdown brief string ready to paste into a subagent prompt.

Use this tool as the FINAL step after tests pass to record a new Work Order in the bound Google Doc
or local managed Markdown file (`docs/ARCHITECTURE.md`). If the Work Order heading already exists and
you only need to flip `⬜ OPEN` to `✅ DONE`, use `atlas_set_status` instead.

Behavior & Output:
- Pre-write wiring gate: when `status='done'`, verifies that every symbol in `verify_symbols` (and
  `.atlas/wo-symbols.yml`) is both defined and referenced/called (`calls + references > 0`). If any
  symbol is dead code, returns `{written: false, refused: true, refusal: "..."}` without touching disk/network.
- Atomic verified write: appends the formatted status line, reads the document back to confirm presence,
  logs to `.atlas/mutations.log`, and returns `{written: true, verified: true, wo, line}`.

Use this tool as the final step when completing an existing open Work Order (`wo=N`) or a checkbox
task from `atlas_tasks` (`task='...'`). To append a brand-new Work Order entry that is not yet in the
document, use `atlas_publish` instead.

Behavior & Output:
- Pre-write wiring gate: when `status='done'`, checks that all symbols in `verify_symbols` (and
  `.atlas/wo-symbols.yml`) are defined and have at least one caller/reference. Refuses with
  `{changed: false, refused: true, refusal: "..."}` if any symbol is unwired.
- Verified in-place update: updates the status marker or checkbox in the local Markdown file (or active
  Google Doc tab for Work Orders), verifies by reading back, and returns JSON `{changed, verified, status}`.

Use this tool to modify balancing values, implementation markers, or metadata in an existing row.
To add a brand-new row to a tab, use `atlas_sheet_append`. If unsure of tab names, call `atlas_sheets` first.

Behavior & Output:
- Resolves the exact cell range from `row_key` + header names, preventing off-by-one row overwrites.
- If a column name is unknown, aborts without writing and returns the list of valid column headers.
- Returns JSON `{ok, sheet, tab, row, key, changes, verified, resynced, dry_run}` and refreshes the local search index.

Use this tool when adding a new entry (e.g. a new unit, item, or parameter row) to a bound spreadsheet.
To modify cells of an existing row, use `atlas_sheet_update` instead.

Behavior & Output:
- Not idempotent: each non-dry-run call appends a new row at the bottom of the table and verifies it by read-back.
- Validates all keys in `values` against the tab's header row before writing.
- Returns JSON `{ok, sheet, tab, values, range, verified, resynced, dry_run}` and updates the local search index.

Takes no parameters. Call this tool before `atlas_sheet_update` or `atlas_sheet_append`
whenever you need to discover the exact `sheet` name/ID or valid `tab` names.

Behavior & Output:
- Read-only metadata lookup; returns spreadsheet and tab names without dumping cell contents.
- Returns JSON `{spreadsheets: [{name, id, tabs: [...]}]}` or `{spreadsheets: [], hint: "..."}`
  when no spreadsheet has been synced yet.

Use this tool BEFORE reading source files to find where a symbol lives (~30 tokens per signature vs.
thousands of tokens for a full file) or set `usage=True` to check if a symbol is actually called before
marking a task done. Supports GDScript (`.gd`/`.tscn`), Python, TypeScript/JavaScript, Rust, C#, Go,
Java, Kotlin, and Swift.

Behavior & Output:
- Read-only static scan of project source files; ignores build directories and `.atlas/`.
- Returns a formatted summary of matching definitions (`path:line — signature`) and, when `usage=True`,
  the caller/reference count and file:line call sites for each symbol.

Takes no parameters. Checks managed documentation for duplicate section anchors, empty headings,
oversized sections (>8,000 chars), Work Orders missing a status marker (`⬜`/`🚧`/`✅`), and broken
`implements:` code file paths. Use this tool after editing documentation or running `atlas init`.

Behavior & Output:
- Read-only structural check; respects `.atlas/managed.json` (separating managed docs from legacy discovered docs).
- Returns a JSON string `{managed_issues: [...], discovered_hints: [...], clean: bool}` detailing each issue by file and line.

Takes no parameters. Use this tool first when asked about project progress, completed milestones,
or which Work Order is next — one call returns the authoritative list without reading documentation files.
For granular Markdown checkboxes (`- [ ]`), use `atlas_tasks` instead.

Behavior & Output:
- Read-only query over all Work Order headings/entries in the index (up to 60 orders).
- Returns a human- and agent-readable summary starting with the index freshness timestamp,
  total counts (`done` / `open`), and one line per Work Order (`WO # — status — title (anchor)`).