@spikedpunch/mast 0.2.0 → 0.4.0

package/README.md

@@ -33,7 +33,7 @@ MAST takes a different approach:
 - **AST-level chunking** — every function, class, interface, and type alias is its own chunk. The assistant gets the exact declaration it needs, not the file it happens to live in.
 - **Ranked search** — BM25 (FTS5) handles keyword and identifier queries; a declaration-exact ranker ("ranker D") catches exact-symbol-name queries that BM25's trigram tokenizer can rank inconsistently. Both are fused via Reciprocal Rank Fusion so a chunk that both rankers agree on outranks one that only one of them found.
 - **Structural queries** — "who calls this function?", "what implements this interface?", "what does this file import?" are answered from a pre-built symbol graph, not by grepping source. Answers are instantaneous and structurally correct.
-- **JIT staleness detection** — on every read, MAST checks whether the file on disk has changed since it was last indexed. If it has, the file is transparently re-parsed in the background before the result is returned. The index never goes stale without the assistant knowing.
+- **Staleness handling that says what it actually does** — five read tools (`mast_signature`, `mast_callers`, `mast_exports`, `mast_dependencies`, `mast_rename_impact`) re-parse a changed file inline before answering; `mast_search` and `mast_implementors` flag affected results with `stale: true` rather than re-parsing. Both only cover files the index *already knows*: a brand-new file is invisible until a reindex, which is why `mast serve` watches by default and why `mast_search` carries an `unindexed_files` warning when it does not.
 - **Token accounting** — every tool response includes `_stats` with the token count returned and the counterfactual "what would a naive full-file read have cost?", giving a concrete measure of efficiency over time.
 
 ---
@@ -142,12 +142,21 @@ mast index --incremental     # reindex only what changed
 mast install-hooks           # reindex automatically after commits and checkouts
 ```
 
+Then tell your agent to use it. One command installs what your harness can take — hooks
+that prime the agent at session start and remind it before a built-in search, or a rules
+file where there are no hooks ([details](#tell-the-assistant-how-to-use-it)):
+
+```bash
+mast setup claude            # or cursor, vscode, windsurf, zed, desktop
+```
+
 Everything shipped with your build is readable offline, so you never have to work out
 which docs match your version:
 
 ```bash
 mast docs                    # list the topics
 mast docs spec               # the full behavioural specification
+mast docs signals            # how to read the flags on an answer (stale, truncated, empty)
 mast skill                   # the instructions to paste into an agent prompt
 ```
 
@@ -170,6 +179,8 @@ claude mcp add mast -- mast serve
 Add `--scope project` to write `.mcp.json` into the repository so your team picks it up
 from the checkout.
 
+To prime the agent at session start and remind it before a search: `mast setup claude`.
+
 ### Claude Desktop
 
 `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
@@ -190,6 +201,10 @@ from the checkout.
 Claude Desktop does not run in your project directory, so `MAST_STATE_DIR` must be
 absolute. The CLI and editor integrations below infer it from the working directory.
 
+Claude Desktop has no hook system and no rules file mast can write. The instructions string
+`mast serve` sends in the MCP handshake is its only channel, and it needs no setup;
+`mast setup desktop` just says so.
+
 ### Cursor
 
 `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` globally:
@@ -202,6 +217,8 @@ absolute. The CLI and editor integrations below infer it from the working direct
 }
 ```
 
+To add the hooks and a rules file: `mast setup cursor`.
+
 ### VS Code (GitHub Copilot)
 
 `.vscode/mcp.json`:
@@ -214,6 +231,8 @@ absolute. The CLI and editor integrations below infer it from the working direct
 }
 ```
 
+To add the session-primer hook: `mast setup vscode`.
+
 ### Windsurf
 
 `~/.codeium/windsurf/mcp_config.json`:
@@ -226,6 +245,8 @@ absolute. The CLI and editor integrations below infer it from the working direct
 }
 ```
 
+To add a rules file: `mast setup windsurf`.
+
 ### Zed
 
 `settings.json`:
@@ -238,16 +259,43 @@ absolute. The CLI and editor integrations below infer it from the working direct
 }
 ```
 
+To add mast's instructions to a rules file you already keep (`.rules`, `AGENTS.md`, and the
+others Zed reads): `mast setup zed`.
+
 ### Any other MCP client
 
-Run `mast serve` over stdio from the project root. It advertises eleven read tools and
-needs no arguments beyond `serve`.
+Run `mast serve` over stdio from the project root. It advertises eleven tools — ten that
+read and `mast_reindex`, which writes — and needs no arguments beyond `serve`.
 
 ### Tell the assistant how to use it
 
 Registering the server gives the model the tools; it does not tell it *when* to reach for
-them, or how to read a flagged answer. `mast skill` prints instructions written for that —
-paste them into your system prompt, `CLAUDE.md`, `.cursorrules`, or a skill file:
+them. `mast setup <harness>` installs what each harness can take:
+
+| harness | session primer | search reminder | static instructions |
+|---|---|---|---|
+| `claude` (Claude Code) | yes | yes, before `Grep` and `Glob` | none written |
+| `cursor` | yes | yes, but after the search runs | `.cursor/rules/mast.mdc` |
+| `vscode` (VS Code Copilot) | yes | no | none written |
+| `windsurf` | no | no | `.windsurf/rules/mast.md`, or `.devin/rules/mast.md` if `.devin/` exists |
+| `zed` | no | no | a marked block in the first rules file that exists |
+| `desktop` (Claude Desktop) | no | no | none written |
+
+The session primer is the rule set plus the live index state, given at session start. The
+search reminder is one line naming `mast_search`, attached to a built-in search. Windsurf,
+Zed and Claude Desktop have no hook system mast can use, so for them `mast setup` installs
+the static file only, and says so. `mast serve` also sends a short instructions string when
+the MCP connection opens; whether a harness passes that to the model is the harness's choice.
+
+```bash
+mast setup claude             # project scope; add --global for ~/.claude/settings.json
+mast setup cursor --check     # exit 0 only if the hooks and the rules file are current
+mast setup windsurf --dry-run
+mast setup zed --remove
+```
+
+Anything else, or a harness not listed, can use `mast skill`, which prints the same short
+instructions to paste into a system prompt, `CLAUDE.md`, or a skill file:
 
 ```bash
 mast skill                    # print it
@@ -261,6 +309,12 @@ marked block, so re-running after an upgrade replaces the previous copy instead
 a second one. It never runs on its own, and it never creates a config file you did not
 already keep.
 
+**What is verified.** In Claude Code, both hooks were observed delivering their text to the
+model in one session. For Cursor, VS Code and Windsurf, the hook formats and rules-file
+locations were read from the vendor's documentation and nothing was run inside the tool.
+The list of files Zed reads was not checked against Zed's documentation. Whether any of
+this changes how often an agent uses mast has not been measured.
+
 ---
 
 ## Upgrading
@@ -279,6 +333,13 @@ it on the next `serve` or `index`. Nothing is lost that cannot be rebuilt — th
 derived state — but on a large monorepo it is minutes, and it is better known in advance
 than discovered as an unexplained stall.
 
+If mast's hooks, rules files or skill blocks are installed in the project (or hook files
+under your home directory), the report ends with an "After upgrading" block listing the
+commands to re-run, such as `mast setup claude --check` and `mast skill --install`. It runs
+on the version you have now, so it cannot know what the new version would write: it only
+knows the files exist, and `--check` is what compares them. A project with none of these
+gets no such block.
+
 ---
 
 ## Using MAST in a monorepo
@@ -289,7 +350,10 @@ tool rather than one index per package.
 
 **What is indexed.** `.ts`, `.tsx`, `.js`, `.jsx`, and `.md`, minus `node_modules`,
 `dist`, `build`, `coverage`, `.next`, `.turbo`, `.mast`, and test files. Override with
-`--extensions` and `--exclude` on `mast init`, or edit `.mast/config.json`.
+`--extensions` and `--exclude` on `mast init`, or — for a setting the whole team should
+get — `file_extensions` / `exclude_patterns` in `mast.config.json` at the project root.
+Editing `.mast/config.json` also works and is read back, but that file is gitignored and
+per-machine, so the change will not travel; `mast.config.json` outranks it.
 
 **Other languages are not indexed, and this matters.** MAST parses TypeScript and
 JavaScript only. A symbol defined in Python, Go, Java, or Rust is absent from the index,
@@ -297,7 +361,16 @@ which looks exactly like absent from the repository. Treat an empty result as "M
 not find it", never as "it does not exist" — `mast skill` says this to the model too.
 
 **Add `.mast/` to `.gitignore`.** It is derived state, it is large, and it is
-machine-specific.
+machine-specific — on a 14k-file monorepo it is around 420 MB, almost all of it `graph.db`.
+Ignore the whole directory, including `.mast/config.json`: that file is a *resolved*
+snapshot and carries absolute paths (`project_root`, `resolved_state_dir`) that mean
+nothing on anyone else's machine. The file meant to be committed is `mast.config.json` at
+the project root — see the next paragraph.
+
+**If you move the index, move the ignore rule with it.** `.mast/` is the default location,
+not the only one: a `state_dir` in `mast.config.json`, a `MAST_STATE_DIR` in the
+environment, or a `--state-dir` flag all put the index somewhere else, and a `.gitignore`
+naming `.mast/` then protects nothing.
 
 **A custom index location is not remembered between runs.** `--state-dir` applies to the
 one command you pass it to. Path settings are deliberately never read back out of a
@@ -351,9 +424,19 @@ Options:
   -e, --exported         Only exported symbols
   -f, --file <glob>      Restrict to files matching a glob
       --state-dir <dir>  State directory
+      --reindex          Incrementally reindex before searching
       --json             Emit the raw MCP response instead of text
 ```
 
+`--reindex` exists because the CLI has neither freshness mechanism the MCP server has:
+no file watcher, and no cached freshness probe (a one-shot process has no lifetime to
+amortise one over). Without it, a file created since the last index run is invisible —
+JIT staleness only re-parses files the index already knows. It is opt-in because it adds
+a whole incremental index run to what is otherwise a single query, and it reports what it
+did on **stderr**, so `--json` consumers keep a parseable stdout. A reindex that loses
+`structure.lock` to a concurrent writer — likelier now that `mast serve` watches by
+default — warns and queries the existing index rather than failing the search.
+
 **Why:** the fastest way to check what the index actually contains, and the same code path
 the MCP `mast_search` tool uses — it dispatches through the registered handler rather than
 re-implementing ranking, so CLI and assistant results cannot disagree. Staleness and
@@ -390,10 +473,16 @@ Start the MCP server over stdio.
 Options:
   --state-dir <dir>         State directory
   --no-startup-reindex      Skip the startup staleness check (not recommended)
+  --no-watch                Do not watch source files (batch/container use)
   --watch                   Watch source files and incrementally reindex on change
-                             (interactive use; not needed in the container ladder)
+                             (the default; accepted for compatibility)
 ```
 
+Watching is **on by default**. JIT staleness only re-parses files the index already knows,
+so without a watcher a file created during a session stays invisible to every read tool
+until something reindexes — and nothing does. A watcher failure (EMFILE, permissions) logs
+a warning and the server keeps serving, so the default cannot stop `serve` from starting.
+
 The server implements a four-step startup ladder so MCP clients get a usable server in under a second even for large projects. See [Startup Ladder](#startup-ladder) for details.
 
 ---
@@ -442,6 +531,7 @@ Invoke any MCP read tool directly, with byte-identical output to the MCP transpo
 ```
 Options:
   --state-dir <dir>   State directory
+  --reindex           Incrementally reindex before querying (see `mast search --reindex`)
   --json              Emit the exact single-line MCP response (default pretty-prints)
 ```
 
@@ -459,8 +549,9 @@ tool that does not exist lists the ones that do.
 
 ### `mast docs [topic]`
 
-Print documentation shipped with the installed build — `readme`, `spec`, or `skill`. No
-argument lists the topics with the version they belong to.
+Print documentation shipped with the installed build — `readme`, `spec`, `skill`, or
+`signals` (the staleness, truncation and emptiness flags on an answer). No argument lists
+the topics with the version they belong to.
 
 **Why:** removes the step where a reader looks up their version and then finds docs for a
 different one. What `mast docs` prints is what the binary in your `node_modules` does.
@@ -479,10 +570,117 @@ Options:
 ```
 
 **Why:** registering the MCP server gives a model the tools but not the judgement — when to
-search instead of reading, that code tokens beat prose in a query, and how to read a
-staleness or truncation flag. It also tells the model that an empty result means "MAST did
-not find it", not "it does not exist", which is the single most consequential thing to get
-right about a search tool.
+search instead of reading, and that code tokens beat prose in a query. The text is short
+(under 4,000 characters) so it fits a rules file. It also tells the model that an empty
+result means "MAST did not find it", not "it does not exist", which is the single most
+consequential thing to get right about a search tool, and points at `mast docs signals` for
+how to read the individual flags.
+
+---
+
+### `mast prime [path]`
+
+Print the session primer: a short rule set for using mast, plus the live index health.
+
+```
+Options:
+  --state-dir <dir>   State directory
+```
+
+**Why:** it is the text an agent should be given at the start of a session. When the index
+is fresh or stale it prints the rules and the file count and age of the index (a stale
+index adds the changed/unindexed/deleted split and a `mast_reindex` instruction). When
+there is no index, or the index describes a different tree, it withholds the rules and says
+what is wrong. It exits 0 in every state, unlike `mast status`.
+
+---
+
+### `mast hook <harness> <event>`
+
+The entry point for agent hooks. Reads the harness's hook JSON on stdin and writes that
+harness's JSON envelope on stdout, or writes nothing. `<harness>` is `claude`, `cursor` or
+`vscode`; `<event>` is `session-start` or `search`.
+
+- `session-start` emits the same text `mast prime` prints for the project (the hook's `cwd`,
+  else the first workspace root, else the current directory), in every index state.
+- `search` emits a one-line reminder to try `mast_search` first. It stays silent when no
+  index exists for the project, or when the search is scoped by `type`, `glob` or `path` to
+  a language mast does not index. "Indexes" follows the project's own `file_extensions`
+  where it sets one, so a project that indexes `.mjs` is reminded on a `*.mjs` search.
+
+```
+Arguments:
+  harness   claude | cursor | vscode
+  event     session-start | search
+```
+
+**Why:** a hook that fails breaks the user's session, so this command exits 0 for every
+ordinary condition (empty or malformed stdin, an unknown harness or event, a missing index)
+and leaves stdout empty, with one line on stderr where something went wrong. `search` runs
+before every Grep, so it is dispatched before the rest of the CLI loads.
+
+---
+
+### `mast setup <harness> [path]`
+
+Install what tells an agent to use mast: hooks that prime it at session start and remind it
+before a built-in search, and rules files for harnesses that read them. `<harness>` is
+`claude`, `cursor`, `vscode`, `windsurf`, `zed` or `desktop`; `[path]` is the project root
+(default: the current directory).
+
+| harness | project file (default) | `--global` |
+|---|---|---|
+| `claude` | `.claude/settings.json` | `~/.claude/settings.json` |
+| `cursor` | `.cursor/hooks.json` and `.cursor/rules/mast.mdc` | `~/.cursor/hooks.json` only; Cursor has no user-level rules file, and a note says so |
+| `vscode` | `.github/hooks/mast.json` | `~/.copilot/hooks/mast.json` |
+| `windsurf` | `.windsurf/rules/mast.md`, or `.devin/rules/mast.md` if a `.devin` directory exists | refused (exit 1) |
+| `zed` | a marked block in the first existing of `.rules`, `.cursorrules`, `.windsurfrules`, `.clinerules`, `.github/copilot-instructions.md`, `AGENT.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` | refused (exit 1) |
+| `desktop` | nothing | nothing |
+
+```
+Options:
+  --global    Write the user-level file instead of the project one
+  --check     Write nothing; exit 0 only if everything is installed and current
+  --remove    Remove what mast installed
+  --dry-run   Print what would be written, and write nothing
+```
+
+`claude` and `cursor` get both hooks (`mast hook <harness> session-start` and
+`mast hook <harness> search`). **`vscode` gets the session primer only:** VS Code ignores hook
+matchers, so a search hook would run before every tool call, and the name of its search tool
+is not documented. **`windsurf`, `zed` and `desktop` have no hook system mast can use**, so
+the first line of output says that only static instructions are installed. `desktop` writes
+nothing: its only channel is the instructions string `mast serve` sends in the MCP handshake,
+which needs no setup, and every flag exits 0 after saying so.
+
+The rules files carry the text `mast skill` prints. `mast.mdc` (frontmatter `description` and
+`alwaysApply: true`) and the Windsurf `mast.md` (frontmatter `trigger: always_on`) belong to
+mast outright, and are overwritten if they differ; there is no marker, the name is the claim.
+The Windsurf file stays under Windsurf's documented 12,000-character limit, checked in a test.
+`zed` never creates a file: if none of Zed's candidates exists it writes nothing and exits 1,
+telling you to create `.rules` and run it again, and otherwise it splices the same marked
+block `mast skill --install` uses into the first one that exists. `--remove` takes out that
+block, from every candidate that carries it, and leaves the file. The Zed file list is
+from memory of Zed's documentation and has not been checked against it.
+
+**Why:** the hook command depends on how mast is installed. A global install writes
+`mast hook ...`; a source checkout writes `node "<path to dist/cli/index.js>" hook ...`, a
+path specific to your machine, so do not commit that file; a project dependency writes a path
+into `node_modules/.bin`. A project dependency cannot be installed with `--global`: a
+user-level hook pointing into one project's `node_modules` breaks in every other project.
+For VS Code the relative `node_modules/.bin/mast` is unverified, because its docs do not
+say what directory hooks run in.
+
+For hook files it only ever touches entries whose command ends in `hook <harness> session-start`
+or `hook <harness> search`. Every other key, hook and field in the file is kept, in order, and
+the file keeps its indentation and trailing newline. Re-running changes nothing and does not
+write any file; a changed install (say, source to global) replaces the entry in place. A file
+that is not valid JSON, or whose `hooks` have an unexpected shape, is reported and left
+untouched (exit 1). `--remove` deletes only mast's entries, and for `vscode` deletes
+`mast.json` once nothing else is in it. `--check` cannot be combined with `--remove` or
+`--dry-run` (exit 2), nor can an unknown harness be given (exit 2). For `cursor`, `--check`
+exits 0 only if both the hooks file and the rules file are current. Nothing here has been
+run inside Cursor, VS Code, Windsurf or Zed.
 
 ---
 
@@ -493,7 +691,9 @@ Check for a newer release; print how to install it, and what it will cost.
 **Why:** it detects how MAST was installed and prints the matching command rather than
 running it, because a CLI cannot reliably distinguish a global install from a dev
 dependency. It also reports whether the upgrade bumps the index schema — which forces a
-full reindex on the next `serve` — and your package manager cannot tell you that.
+full reindex on the next `serve` — and your package manager cannot tell you that. When
+mast's hooks, rules files or skill blocks are installed, it lists the `mast setup <harness>
+--check` and `mast skill --install` commands to re-run afterwards.
 
 ---
 
@@ -512,6 +712,31 @@ MAST registers 11 tools with the MCP server. Every read tool includes a `_stats`
 }
 ```
 
+### The signals
+
+Beyond the results, a response carries fields describing what MAST **does not know** about
+the answer it just gave. All but the last are omitted entirely when they do not apply, so
+their absence carries meaning and their presence is never noise. `truncated` is the one
+exception — it is a required field on every `type_context` entry and is present-and-`false`
+in the ordinary case, so read it, don't test for it.
+
+| signal | carried by | means |
+|---|---|---|
+| `stale` | per result of `mast_search`, `mast_implementors` | this result's file changed on disk since it was indexed. The content and line numbers shown may be out of date; no re-parse was attempted (see [JIT Staleness Checks](#jit-staleness-checks)) |
+| `file_busy_returning_stale_cache` | `mast_signature`, `mast_callers`, `mast_exports`, `mast_dependencies`, `mast_rename_impact` | a re-parse *was* attempted and lost to a concurrent writer, so the previous chunk was returned. Contended, not wrong by design — retry shortly |
+| `index_empty` | the empty answer of any of the eight tools that return a result set | nothing is indexed at all. The answer is empty because there was nothing to answer from, not because nothing matched |
+| `unindexed_files` | `mast_search`, `mast_callers`, `mast_implementors`, `mast_rename_impact`, `mast_project_skeleton` (always); `mast_signature`, `mast_exports`, `mast_dependencies` (on an empty answer only) | this many files exist on disk and are not in the index. The answer was computed over an incomplete corpus — an empty or thin result may mean "not indexed" rather than "not present". The tools that claim an exhaustive set report it even when they found something, because a short list reads exactly like a complete one; the three that answer about one named thing report it only when that thing was not found |
+| `results_truncated` | `mast_signature`, `mast_implementors` | the list was capped at `limit`; the field carries the real, uncapped total |
+| `exports_truncated` | `mast_exports` | the same, for a module's export list |
+| `potential_truncated` | `mast_callers`, `mast_rename_impact` | the unresolved-candidate fetch was capped at 50; the field carries the real match count |
+| `truncated` | a `type_context` entry of `mast_signature` | that referenced type's declaration was clipped at 50 lines. The one signal that *is* always present, as a boolean |
+
+Two distinctions that are not flags but carry the same weight: in `mast_callers` and
+`mast_rename_impact`, a **`verified_caller`** carries a `resolution` naming how the edge was
+statically proven and is safe to act on, while a **`potential_match`** carries a `reason` and
+is a name match with no proven edge — review before editing. And an empty result is never
+proof of absence: MAST indexes TypeScript, JavaScript, and Markdown only.
+
 ---
 
 ### `mast_search`
@@ -529,7 +754,7 @@ Lexical BM25 + declaration-exact search over the indexed codebase.
 }
 ```
 
-**Returns:** `{ results[], suggestions?, _stats }`. Each result includes `file_path`, `start_line`, `end_line`, `content`, `chunk_type`, `symbol_name`, `parent_symbol`, `is_exported`, `match_score` (BM25 score, negative; `null` when the hit came only from ranker D), `rank`, `match_snippet`, and an optional `related` hint when a method and its class shell both matched (only the higher-ranked one is returned). `suggestions` is present, possibly empty, only when `results` is empty — a zero-result "did you mean" assist.
+**Returns:** `{ results[], suggestions?, index_empty?, unindexed_files?, _stats }`. Each result includes `file_path`, `start_line`, `end_line`, `content`, `chunk_type`, `symbol_name`, `parent_symbol`, `is_exported`, `match_score` (BM25 score, negative; `null` when the hit came only from ranker D), `rank`, `match_snippet`, an optional `stale` flag, and an optional `related` hint when a method and its class shell both matched (only the higher-ranked one is returned). `suggestions` is present, possibly empty, only when `results` is empty — a zero-result "did you mean" assist. See [The signals](#the-signals) for `stale`, `index_empty`, and `unindexed_files`.
 
 **Why:** `grep` and `glob` find exact strings and require the caller to already know the pattern. `mast_search` ranks by relevance across two signals fused with Reciprocal Rank Fusion:
 
@@ -776,13 +1001,34 @@ with default `k = 60`. A chunk appearing at rank 1 in both lists scores twice as
 
 ### JIT Staleness Checks
 
-Every read tool (search, exports, signature, callers, dependencies, implementors) calls `jitRefreshFile` before returning results. This function:
+Read tools handle a file that changed since it was indexed in one of **two** ways. Which one a tool
+uses is fixed per tool, not decided at runtime:
+
+**Re-parse inline** — `mast_signature`, `mast_callers`, `mast_exports`, `mast_dependencies`,
+`mast_rename_impact`. Before returning, each calls `jitRefreshFile`, which:
 
-1. Reads the stored mtime for the file from the `files` table.
+1. Reads the stored mtime for the file from the `files` table. **If there is no row, it returns
+   immediately** — an unindexed file has no stored mtime to compare against, which is the whole of
+   why JIT cannot discover new files.
 2. Calls `stat()` on the file on disk.
-3. If the disk mtime is newer, acquires the `structure.lock` and re-parses the file immediately.
+3. If the disk mtime is newer, acquires the `structure.lock` and re-parses the file immediately,
+   on the request path — the answer waits for it.
+
+If the lock is held by a concurrent writer the previous chunk is returned with
+`file_busy_returning_stale_cache` set, so the caller is told rather than quietly served stale data.
+
+**Stat and flag** — `mast_search`, `mast_implementors`. These call `findStaleFiles`, which stats the
+files behind the results and sets `stale: true` on the affected ones. **No re-parse is attempted**:
+taking a write lock on a ranked result set would serialise the cheapest tools in the package behind
+the most expensive operation in it. The line coordinates on a flagged result may be off; the caller
+is expected to re-read or call a re-parsing tool.
+
+**Neither** — `mast_project_skeleton` (documented exempt) and `mast_efficiency`.
 
-This means an assistant editing a file and immediately querying it will always see the current version, without waiting for a scheduled reindex. (JIT staleness handles files already known to the index; a brand-new file or symbol still needs `mast_reindex` or the next scheduled/watch reindex to be discoverable.)
+Both mechanisms only ever touch files the index **already knows**. Neither can discover a file that
+was never indexed, so a file created during a session is invisible to every read tool until
+something reindexes it — which is why `mast serve` watches by default, and why every
+primary-result tool reports `unindexed_files` when the index is nonetheless behind.
 
 ### Startup Ladder
 

package/assets/prime.md

@@ -0,0 +1,18 @@
+# Using mast
+
+mast indexes this repository's TypeScript, JavaScript and Markdown at the AST level.
+
+- To find code (a symbol, its callers, a module's exports), call mast before grep, glob or
+  reading whole files. It returns ranked declarations, not line matches.
+- Put code tokens in the query: function, type and column names. An exact symbol name
+  anchors its declaration to the top. If a query returns nothing, change the vocabulary.
+- `mast_search`: discover code by name or token.
+- `mast_signature`: a symbol's declaration and resolved parameter types.
+- `mast_callers`: who calls a function. Run it before any refactor.
+- `mast_exports`: a module's public API, without reading the file.
+- `mast_rename_impact`: the checklist for a rename.
+- Use grep for other languages, non-code files, or an exact regex over text.
+- An empty result is not proof of absence. Check `index_empty`, `unindexed_files` and
+  `stale` on the response before concluding something does not exist.
+- Call `mast_reindex` after creating or renaming files. A new file is invisible to every
+  read tool until an index pass runs.

package/assets/signals.md

@@ -0,0 +1,51 @@
+# MAST signal reference
+
+The fields MAST puts on an answer to say what it does not know, and how it treats a file that
+changed after it was indexed. `mast skill` carries the short rules; this is the detail behind them.
+
+## How MAST handles a file that changed since it was indexed
+
+Two mechanisms, and which one you get depends on the tool. Neither can see a file that
+was never indexed at all.
+
+- **Re-parsed for you, before the answer** — `mast_signature`, `mast_callers`,
+  `mast_exports`, `mast_dependencies`, `mast_rename_impact`. If the re-parse loses a
+  race with a writer, the result carries `file_busy_returning_stale_cache`.
+- **Flagged, not re-parsed** — `mast_search`, `mast_implementors`. Affected results
+  carry `stale: true`. The code and line numbers shown may be out of date; call one of
+  the tools above, or `mast_reindex`, to get the current version.
+
+Both only cover files already in the index. That is why creating a file needs an
+explicit `mast_reindex`.
+
+## Reading the answers honestly
+
+MAST reports what it does not know. These signals are load-bearing. All but the last are
+**omitted entirely when they do not apply** — so their absence is meaningful, and their
+presence is never `false`. `truncated` is the exception: it is always present on a
+`type_context` entry, so check its value rather than its presence.
+
+| signal | on | means |
+|---|---|---|
+| `stale` | per result of `mast_search`, `mast_implementors` | this result's file changed since indexing; line numbers may be wrong |
+| `file_busy_returning_stale_cache` | the five re-parsing tools | a refresh was attempted and lost to a writer; retry shortly |
+| `index_empty` | the empty answer of any of the eight tools that return a result set | **nothing is indexed at all.** This is not "no match" — run `mast_reindex`, or check that `mast_status` names the tree you meant |
+| `unindexed_files` | `mast_search`, `mast_callers`, `mast_implementors`, `mast_rename_impact`, `mast_project_skeleton` (always); `mast_signature`, `mast_exports`, `mast_dependencies` (on an empty answer only) | that many files on disk are not in the index, so this answer was computed over an incomplete corpus. **An empty result carrying this is not evidence of absence.** The set-returning tools report it even with hits — a short list of callers reads exactly like a complete one |
+| `results_truncated` | `mast_signature`, `mast_implementors` | you got the first page, not the answer. The field carries the real total; raise `limit` or narrow the query |
+| `exports_truncated` | `mast_exports` | the same, for a module's export list |
+| `potential_truncated` | `mast_callers`, `mast_rename_impact` | the unresolved-candidate set was capped; the real count is larger |
+| `truncated` | a type in `mast_signature`'s `type_context` | that declaration was clipped at 50 lines |
+
+Two more things that are not flags:
+
+- In `mast_callers` and `mast_rename_impact`, **`verified_callers` and
+  `potential_matches` are not the same claim.** A verified caller carries a `resolution`
+  and is safe to act on. A potential match carries a `reason` and is a name match with
+  no proven edge — review it before editing it.
+- An **empty result is not proof of absence.** MAST indexes TypeScript, JavaScript, and
+  Markdown only — a symbol defined in Python, Go, Java, or any other language is absent
+  from the index, not absent from the repository. Check `index_empty` and
+  `unindexed_files` before concluding "it isn't there", and **never delete or rewrite
+  code on the strength of an empty result alone.** Every result-set tool carries
+  `unindexed_files` now, not just `mast_search` — so an empty `mast_callers` answer that
+  carries it is not a green light to delete the function.

package/assets/skill.md

@@ -6,13 +6,19 @@ graph, so prefer it over reading files or grepping.
 
 ## Rules
 
-- Call `mast_status` at the start of a session to confirm the index is fresh.
+- Call `mast_status` at the start of a session to confirm the index is fresh. Read
+  **`stale_breakdown.unindexed`**: any non-zero value means files exist that MAST has never
+  seen, and no amount of querying will find them. Read that field rather than
+  `freshness_cause`, which reports a single ranked cause and shows `"phase1_stale"` ahead of
+  `"unindexed_files"` whenever both are non-zero.
 - **Search before opening any file.** No file path without a MAST result behind it.
 - **Use code tokens in queries** — function names, type names, column names.
   `createTable uuid primaryKey` beats `migration pattern`. An exact symbol name in the
   query anchors its declaration to the top.
 - When a query returns nothing, **change vocabulary — do not repeat it**.
-- Call `mast_reindex` after writing files, to keep the index current.
+- **Call `mast_reindex` after creating or renaming files**, before any query that depends
+  on what you just wrote. Editing the *body* of a file MAST already knows is handled for
+  you; a **new** file is not, and is invisible until an index pass runs.
 
 ## Picking the right tool
 
@@ -30,16 +36,8 @@ graph, so prefer it over reading files or grepping.
 | `mast_status` | index freshness and health |
 | `mast_reindex` | refresh the index after edits |
 
-## Reading the answers honestly
-
-MAST reports what it does not know, and those signals are load-bearing:
-
-- A result carrying **`file_busy_returning_stale_cache`** or a staleness flag means the
-  answer may predate the file on disk. Do not treat it as current.
-- A **`truncated`** or **`potential_truncated`** flag means the set was capped. The real
-  count is larger than what you were shown.
-- An **empty result is not proof of absence.** MAST indexes TypeScript, JavaScript, and
-  Markdown only — a symbol defined in Python, Go, Java, or any other language is absent
-  from the index, not absent from the repository. Check the flags before concluding
-  "it isn't there", and never delete or rewrite code on the strength of an empty result
-  alone.
+An empty result is not proof of absence. MAST indexes TypeScript, JavaScript, and Markdown
+only, so a symbol in any other language is absent from the index, not from the repository.
+Check `index_empty` and `unindexed_files` on the response before concluding "it isn't
+there", and never delete or rewrite code on an empty result alone. `mast docs signals`
+prints the full signal reference.