Locate the files relevant to a task. Pass query = EVERY salient identifier from the task (symbol names, domain nouns, the rare token you half-remember) — not one distilled keyword. Recall is bounded by the terms you give: a one-token query cannot out-rank lookalikes, so over-supply rather than under-supply. Reach for find BEFORE Read/Grep/Glob.

HOW IT WORKS: find greps every term across the repo body AND matches declared names (filenames, path segments, exported symbols), then ranks files by DISTINCT-TERM COVERAGE — the file that covers MORE of your query rises above its lookalikes. This catches body-level matches (nested defs, dynamic refs, string literals) that a declared-name index misses.

OUTPUT: a ranked page. Top files get an inline preview — their indexed symbols (with line ranges) plus the body lines where your rare terms CLUSTER (def/class/assignment lines first), so you often answer WITHOUT a follow-up Read. Lower-ranked files list as bare paths. Prose/doc and stylesheet matches are partitioned into secondary lists so they do not crowd out source. Related files (sharing a rare identifier with a top hit, no import edge between them) are surfaced as first-class neighbors.

NAMING: case- and separator-insensitive (LoadStaging ≡ load_staging). It does NOT expand synonyms or plurals for you — that is your job: if the concept could be named two ways, pass both tokens.

AFTER THE RESULT:

1. A path + its inline symbols/preview answer the question → done, no Read needed.

2. Path looks right but you need shape/usage → gs on it (symbols + imports + per-symbol callers + importers in one shot).

3. "no indexed file contains any of [...]" → those identifiers do not exist in the repo; reformulate or grep for a phrase/regex find cannot index. Do not grep spelling variants of a token find already reported absent.

Drill into a known file. Returns these sections as compact text:

• Symbols — top-level + per-class methods (name, kind, line range, extends/implements). With cross-file callers attached per exported symbol (inline if 1 caller; newline-per-caller block if ≥2). For huge files (>20 symbols, no match), symbols are reordered by caller count (most-used first) and truncated to top 15.

• Imports — 1-hop internal outbound dependencies (library imports stripped).

• Importers — 1-hop reverse: files in this repo that import this one. With match, additionally lists EVERY indexed file (importer or not, any language) whose CONTENT references the matched term even when its filename does not (a registry, admin, or config file using the symbol — or a frontend file referencing a backend name). That subsection IS the complete "who uses " answer: it is exhaustive over indexed content, so a subsystem absent from it does NOT use the symbol — do not grep to enumerate or re-verify use-sites, and do not keep hunting in subsystems the section rules out.

• Related — files sharing rare identifier/string-literal tokens with this file (with match: with the matched symbols' code region), shown only when NO import edge connects them. These are name-reference relations the import graph cannot see — Django migrations↔models, config-by-name registration, cross-language (JS↔Python) pairs. Treat them as first-class neighbors: the shared token shown is the reason they are related. Use this AFTER find surfaces a candidate file. This is the right tool for "who uses this file" / "who calls this symbol" — no separate call needed.

view controls which sections you get (default full = all four). symbols, imports, importers, callers each return one section in isolation when you want a byte-light answer.

For god-files (large classes, large routers, large config modules), pass match to filter symbols/imports/importers/callers to one area — e.g. match: "auth" or match: "/^handle/". Substring is case-insensitive; wrap in slashes for regex.

Prefer this over Read when you need shape, neighbors, or usage. Reach for Read only for implementation details inside a method body. If you have called gs on 5+ files for one question, you are enumerating — go back to find with a sharper path glob or a different concept token instead.

Search the repo's NOTEBOOK — durable notes past agents wrote after finishing tasks here (file purposes, cross-file flows, traps/lessons, established absences). Try this BEFORE find when the task might have been seen before: a hit can answer outright or point straight at the right files, skipping a search. Pass plain task words (symptoms work: "logout loop after refresh"), symbol names, or file names.

Results are inlined in full with a freshness stamp computed against the CURRENT code: [fresh] = the cited file is byte-identical to when the note was verified; [evidence changed: ] = that file drifted since — re-verify before relying on it (and correct the note if it proved wrong: coldstart kb write). Absence notes ("there is no X") are re-checked live. No hits or an empty notebook → fall through to find, no tax.

Read everything the NOTEBOOK knows at ONE exact address — the file you are about to edit. Address-keyed, not concept-keyed: unlike kb_search (fuzzy, ranked), this filters notes by exact anchor path, so it is exhaustive at that path. Returns the file note's facets, every cross-file flow that passes THROUGH this file, and lessons/absences anchored here — each with a live freshness stamp against the current code.

Reach for this the moment you have DECIDED on a file and are about to modify it: it surfaces the flow you might break, the absence you are about to violate, the rationale for the code's shape. A clean result ("nothing known here") is itself a positive signal — proceed. Anything marked [evidence changed: ] drifted since it was verified; re-verify before relying on it, and correct the note with kb_write if it proved wrong. Pass an optional symbol to narrow to one top-level symbol at that path.

Save or correct a NOTEBOOK note after finishing real work here — you have the files in context, so no future agent is better placed to record what you learned. Write a file note (what a file is for), a flow note (how a task spans files), or an absence lesson (a confirmed "there is no X"). Also the tool to FIX or RETRACT a note you used that proved wrong (op: "put" replaces, op: "retract" removes).

TWO-PHASE reuse gate: a flow/lesson spec sent WITHOUT an id first searches the notebook for the same concept. If plausible matches exist, kb_write returns {status:"candidates", candidates:[...]} INSTEAD of writing — re-call with into: "<id>" to merge into an existing note, or is_new: true to declare a genuinely new one. This makes note identity reliable (matching, not guessing an exact title). File notes skip the gate (id derives from the path).

The spec shape is documented in coldstart.md — briefly: type ("file"|"flow"|"lesson", or sugar "file-hub"/"file-single"), title, summary, anchors ([{path, symbols?}] — the addresses the note is about, which drive freshness), plus type-specific fields (file: facets/character; flow: steps; lesson: kind:"absence"/scope/body). Call with NO arguments to get the full spec guide. This tool WRITES to the repo notebook; it never commits to git — publishing notes is a human-only step (coldstart kb commit).

Notebook overview: how many notes exist (by type: file/flow/lesson), how many are flagged stale (their anchored files drifted since verification), and how many are superseded/retracted. Pass paths (array of repo-relative paths) to instead list the notes anchored at each of those exact paths with their freshness state — a quick "is anything known here?" check across several files at once.