Silica Core

Use before editing or explaining a source file, or when a traceback or a diff names `file:line`: one call serves the file, a `#Class.member`, or the symbol at `#L<line>`, with its supertypes, extenders, callers, the signatures it names, external dependencies and importers, inside a character budget. Static AST only, same repo state, same bytes. Check `truncated` before treating the target as complete; `dropped` names what did not fit. `languages` lists the parsers this install has.

Ask what the index could see before trusting a search or calling absence. Inventory of the root and what the index did with each file: `indexed` (in the index, matches disk), `changed` (differs from the index), `excluded` (an ignore rule or a type the index does not read; `reason` says which), `failed` (read or conversion error), `unconverted` (a PDF whose text layer the index could not read, or an office file with no extracted `.md` beside it; `reason` says which). A PDF is indexed from its own text layer, one section per page, unless a `.md` sits beside it — that sidecar is indexed instead, and both rows carry `source_state`: `stale` means the original changed after the conversion, `unverifiable` that the sidecar records no hash of it or its original is not under the root. `index.state` is `cold` when nothing was ever indexed: an empty listing there is not "no files".

Read a located slice before citing it: lines `start..end`, one `section` by heading, a PDF page, or the whole file when it fits `max_chars`, always with the outline and a `version`; `truncated` and `next_start` say how to continue. A PDF is served from its own text layer, page by page: `section="p. 8"` serves one page — the whole page, ~1.2k tokens (measured 2026-09-09), so ask for it to cite a passage a search located, and widen the search's `width` to explore — `pages` counts them, `page_map` gives the pages the slice covers, and `extract_path` is that text on disk, for grep and the harness's own reader (a cache, rebuilt when the PDF changes, under no `version` guard). A PDF or office file with a `.md` extracted beside it is served from that instead, and `source_state` says whether the original still hashes to what the conversion recorded: `stale` means the PDF changed and the `.md` did not, `unverifiable` that the sidecar records no hash or its original is gone. Reading the `.md` itself, the path a search hit carries, reports the same `source` and `source_state`. Either way `source` names the original, and a PDF with no readable text layer is `error.unconverted`. Carry `version` forward as `expect_version` to be refused instead of reading different bytes under an old citation; `version` is the served text's, never the original's.

For a question that names no identifier (what a behaviour is, where it is decided, why), call this before any grep (a Grep tool, or grep or rg in a shell), Glob or Read: it ranks passages and, in a source tree, the functions, methods, classes and constants themselves, by the question's words and their vectors. Do not grep for the words of a question; grep for an exact string or a symbol name you already know. Each hit carries its densest `width`-char window and line; a PDF's section is a page, so on a PDF hit widen `width` (1200-1500) rather than reading the page. `matched_terms` are the query terms in the hit; `coverage` is the share of the query's idf mass they carry (near 1 = every rare term matched, near 0 = only the common words); `terms_absent` are query terms found nowhere in the corpus. No boolean "no answer" exists: read coverage and matched_terms and decide to stop or rephrase. A hit the dense leg alone found carries `dense` and coverage 0. In a source tree a hit's `section` is the symbol, `span` its lines, and `silica_read(path, section=<symbol>)` serves its body.

Write one note atomically, as given, then lint it: `lint` lists structural violations and unresolved wikilinks. Refuses to overwrite when `expect_version` does not match or when `create_only` is set and the file exists. Undo is git; the core keeps no journal.