coldstart

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 <symbol>" 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/"`…

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: <path>] 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.

List the notebook notes that are WRITTEN BUT UNFINDABLE — missing the fields a note cannot be retrieved without (identityAliases, anchor symbols, a flow's verified paths). Notes written before those fields were required are correct but unreachable, and this is how they get found. Returns a worklist, never a change: repairing is your work, because every gap needs a judgement about the code (which words a reader would search for, which symbols the note is actually about, which files you can honestly claim to have read). Fix each one with kb_write, passing the note's `id` — fields merge, so nothing already in the note is lost. A clean notebook returns "Nothing to repair here." Run it when the user asks to repair, fix, or clean up the notebook.

List file/flow notes whose identityAliases may no longer describe them — a DIFFERENT problem from kb_repair: that one finds notes with NO aliases at all, this one is for aliases that exist but have gone stale (a note rewritten several times can carry words that were really symptoms of an earlier write, not stable facts). Paginated 10 notes at a time. Each entry shows the current (capped) identityAliases AND the full historical union hidden past the render cap — read both before retracting anything, because dropping a visible alias can resurface an older hidden one on the next fold. Re-read the note's code, then reconcile via kb_write (retract stale entries, re-put the rest) — never mechanically, every judgement needs the current code. Returns "No file/flow notes to reconcile." when done. If the response includes `more`, call again with `offset` set to `more.nextOffset` for the next batch.

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: <path>] = 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.

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.

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: `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/verified; lesson: kind:"absence"/scope/body). Call with NO arguments to get the full spec guide. REQUIRED for the note to be findable at all — file-single: identityAliases + anchors[].symbols; file-hub: identityAliases + facets[].symbol; flow: identityAliases + steps + verified; lesson: scope.terms. A note missing these is written but unreachable: identityAliases are the only STABLE search surface besides the exact title (incidentAliases are optional — symptom words for a write that describes one, replaced by the next such write, never required), and anchor symbols are the only channel that answers a query typed as an identifier. This tool WRITES to the repo notebook; it never commits to git — publishing notes is a human-only step (`coldstart kb commit`).