@spikedpunch/mast 0.3.0 → 0.4.0

package/README.md

@@ -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,6 +259,9 @@ 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 tools — ten that
@@ -246,8 +270,32 @@ 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
@@ -488,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.
@@ -508,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.
 
 ---
 
@@ -522,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.
 
 ---
 

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

@@ -18,7 +18,7 @@ graph, so prefer it over reading files or grepping.
 - When a query returns nothing, **change vocabulary — do not repeat it**.
 - **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 (see below); a **new** file is not, and is invisible until an index pass runs.
+  you; a **new** file is not, and is invisible until an index pass runs.
 
 ## Picking the right tool
 
@@ -36,49 +36,8 @@ graph, so prefer it over reading files or grepping.
 | `mast_status` | index freshness and health |
 | `mast_reindex` | refresh the index after edits |
 
-## 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.
+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.

package/dist/cli/docs-cmd.d.ts

@@ -9,6 +9,7 @@ import type { Command } from 'commander';
  */
 export declare class DocsError extends Error {
 }
+export declare const PACKAGE_ROOT: string;
 export interface DocTopic {
     readonly name: string;
     readonly file: string;

package/dist/cli/docs-cmd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-cmd.d.ts","sourceRoot":"","sources":["../../src/cli/docs-cmd.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,KAAK;CAAG;AAMvC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAIzC,CAAC;AAEF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAc5C;AAED,wBAAgB,QAAQ,IAAI,MAAM,CASjC;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAY1D;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwC3D"}
+{"version":3,"file":"docs-cmd.d.ts","sourceRoot":"","sources":["../../src/cli/docs-cmd.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,KAAK;CAAG;AAIvC,eAAO,MAAM,YAAY,QAA4D,CAAC;AAEtF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAKzC,CAAC;AAEF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAc5C;AAED,wBAAgB,QAAQ,IAAI,MAAM,CASjC;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAY1D;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwC3D"}

package/dist/cli/docs-cmd.js

@@ -16,11 +16,12 @@ export class DocsError extends Error {
 }
 // `dist/cli/` and `src/cli/` both sit two levels below the package root, so this
 // resolves identically under vitest and in the published tarball.
-const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
 export const DOC_TOPICS = [
     { name: 'readme', file: 'README.md', summary: 'Install, quick start, CLI and MCP tool reference' },
     { name: 'spec', file: 'MAST_SPEC.md', summary: 'Full behavioural specification — schemas, tool contracts, invariants' },
     { name: 'skill', file: 'assets/skill.md', summary: 'The instructions to paste into an agent prompt or skill file' },
+    { name: 'signals', file: 'assets/signals.md', summary: 'The staleness, truncation and emptiness signals on an answer, and how to read them' },
 ];
 export function readDoc(name) {
     const topic = DOC_TOPICS.find((t) => t.name === name);

package/dist/cli/docs-cmd.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs-cmd.js","sourceRoot":"","sources":["../../src/cli/docs-cmd.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"docs-cmd.js","sourceRoot":"","sources":["../../src/cli/docs-cmd.ts"],"names":[],"mappings":"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"}

package/dist/cli/hook-cmd.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerHookCommand(program: Command): void;
+//# sourceMappingURL=hook-cmd.d.ts.map

package/dist/cli/hook-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-cmd.d.ts","sourceRoot":"","sources":["../../src/cli/hook-cmd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAU1D"}

package/dist/cli/hook-cmd.js

@@ -0,0 +1,13 @@
+import { runHookFromProcess } from './hook.js';
+export function registerHookCommand(program) {
+    program
+        .command('hook <harness> <event>')
+        .description('Hook entry point: read a harness hook JSON on stdin, write its envelope on stdout (claude|cursor|vscode, session-start|search)')
+        .action(async (harness, event) => {
+        // In normal use `cli/index.ts` dispatches `hook` before this program is ever
+        // imported, to avoid its startup cost; this registration exists so `mast --help`
+        // lists the command and the README drift guard sees it.
+        await runHookFromProcess(harness, event);
+    });
+}
+//# sourceMappingURL=hook-cmd.js.map

package/dist/cli/hook-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-cmd.js","sourceRoot":"","sources":["../../src/cli/hook-cmd.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,OAAO;SACJ,OAAO,CAAC,wBAAwB,CAAC;SACjC,WAAW,CAAC,gIAAgI,CAAC;SAC7I,MAAM,CAAC,KAAK,EAAE,OAAe,EAAE,KAAa,EAAE,EAAE;QAC/C,6EAA6E;QAC7E,iFAAiF;QACjF,wDAAwD;QACxD,MAAM,kBAAkB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/hook-state-dir.d.ts

@@ -0,0 +1,24 @@
+/** The two facts the search hook needs from the project's configuration. */
+export interface HookConfig {
+    readonly stateDir: string;
+    readonly fileExtensions: readonly string[];
+}
+/**
+ * Resolves the state directory and the indexed extensions the way `resolveConfig`
+ * does, without zod.
+ *
+ * This is a second producer of two facts, tolerated because the hook runs before every
+ * Grep and `resolveConfig` drags in zod through `env.ts`. `hook-state-dir.test.ts`
+ * runs both over the same cases; change one and that test tells you about the other.
+ *
+ * Precedence mirrors `resolveConfig` minus the CLI flags, which a hook never has.
+ * State dir: MAST_STATE_DIR, then `state_dir` in `<root>/mast.config.json`, then the
+ * default, resolved against the project root (an absolute value stays as it is).
+ * Extensions: `file_extensions` in `mast.config.json`, then the one persisted in
+ * `<state dir>/config.json` (what `mast init --extensions` wrote), then the default.
+ *
+ * Throws where `resolveConfig` throws (an empty MAST_STATE_DIR, an unparseable
+ * config file), so the hook reports the same broken setup the CLI would.
+ */
+export declare function resolveHookConfigLight(projectRoot: string, env: Record<string, string | undefined>): HookConfig;
+//# sourceMappingURL=hook-state-dir.d.ts.map

package/dist/cli/hook-state-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-state-dir.d.ts","sourceRoot":"","sources":["../../src/cli/hook-state-dir.ts"],"names":[],"mappings":"AAKA,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,UAAU,CAcZ"}

package/dist/cli/hook-state-dir.js

@@ -0,0 +1,57 @@
+// Imports Node built-ins and builtin-only repo modules only; see cli/hook.ts.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { DEFAULT_FILE_EXTENSIONS, DEFAULT_STATE_DIR } from '../store/defaults.js';
+/**
+ * Resolves the state directory and the indexed extensions the way `resolveConfig`
+ * does, without zod.
+ *
+ * This is a second producer of two facts, tolerated because the hook runs before every
+ * Grep and `resolveConfig` drags in zod through `env.ts`. `hook-state-dir.test.ts`
+ * runs both over the same cases; change one and that test tells you about the other.
+ *
+ * Precedence mirrors `resolveConfig` minus the CLI flags, which a hook never has.
+ * State dir: MAST_STATE_DIR, then `state_dir` in `<root>/mast.config.json`, then the
+ * default, resolved against the project root (an absolute value stays as it is).
+ * Extensions: `file_extensions` in `mast.config.json`, then the one persisted in
+ * `<state dir>/config.json` (what `mast init --extensions` wrote), then the default.
+ *
+ * Throws where `resolveConfig` throws (an empty MAST_STATE_DIR, an unparseable
+ * config file), so the hook reports the same broken setup the CLI would.
+ */
+export function resolveHookConfigLight(projectRoot, env) {
+    const root = resolve(projectRoot);
+    const fileConfig = readJsonObject(join(root, 'mast.config.json'));
+    const fromEnv = env['MAST_STATE_DIR'];
+    if (fromEnv === '')
+        throw new Error('MAST_STATE_DIR is set but empty');
+    const stateDir = resolve(root, fromEnv ?? stateDirOf(fileConfig) ?? DEFAULT_STATE_DIR);
+    const fileExtensions = stringArrayOf(fileConfig, 'file_extensions') ??
+        stringArrayOf(readJsonObject(join(stateDir, 'config.json')), 'file_extensions') ??
+        DEFAULT_FILE_EXTENSIONS;
+    return { stateDir, fileExtensions };
+}
+function readJsonObject(file) {
+    if (!existsSync(file))
+        return null;
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    return Object.fromEntries(Object.entries(parsed));
+}
+function stateDirOf(fileConfig) {
+    const value = fileConfig?.['state_dir'];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error('mast.config.json: state_dir must be a string');
+    return value;
+}
+function stringArrayOf(source, key) {
+    const value = source?.[key];
+    if (!Array.isArray(value))
+        return undefined;
+    const strings = value.filter((entry) => typeof entry === 'string');
+    return strings.length === value.length ? strings : undefined;
+}
+//# sourceMappingURL=hook-state-dir.js.map

package/dist/cli/hook-state-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-state-dir.js","sourceRoot":"","sources":["../../src/cli/hook-state-dir.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAQlF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAAmB,EACnB,GAAuC;IAEvC,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAClC,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAElE,MAAM,OAAO,GAAG,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACtC,IAAI,OAAO,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,OAAO,IAAI,UAAU,CAAC,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC;IAEvF,MAAM,cAAc,GAClB,aAAa,CAAC,UAAU,EAAE,iBAAiB,CAAC;QAC5C,aAAa,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,EAAE,iBAAiB,CAAC;QAC/E,uBAAuB,CAAC;IAE1B,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;AACtC,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACxF,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,UAAU,CAAC,UAA0C;IAC5D,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC,WAAW,CAAC,CAAC;IACxC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAC/F,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,aAAa,CAAC,MAAsC,EAAE,GAAW;IACxE,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC;IACpF,OAAO,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC"}

package/dist/cli/hook.d.ts

@@ -0,0 +1,44 @@
+export type Harness = 'claude' | 'cursor' | 'vscode';
+export type HookEvent = 'session-start' | 'search';
+/** What the hook needs from the outside world; injected so the shell is testable. */
+export interface HookIo {
+    readStdin(): Promise<string>;
+    write(text: string): void;
+    warn(line: string): void;
+    env: Record<string, string | undefined>;
+    cwd(): string;
+    fileExists(path: string): boolean;
+    isDirectory(path: string): boolean;
+    /** Same text `mast prime` prints for this project root. May be slow. */
+    prime(projectRoot: string): Promise<string>;
+}
+export interface HookFacts {
+    readonly indexExists: boolean;
+    readonly primeText: string;
+    /**
+     * True when the search's `path` names an existing directory. A directory called
+     * `next.js` or `site.io` would otherwise read as a file with an unindexed extension
+     * and silence the reminder for every search under it.
+     */
+    readonly searchPathIsDirectory: boolean;
+    /** The extensions this project indexes: its own list where it sets one, else the defaults. */
+    readonly indexedExtensions: readonly string[];
+}
+export declare const SEARCH_REMINDER: string;
+/**
+ * The whole decision, pure. Returns the harness's envelope, or null for "print nothing".
+ * Unknown harness or event is null rather than a throw: see `runHook` for why.
+ */
+export declare function decide(harness: string, event: string, input: unknown, facts: HookFacts): object | null;
+/**
+ * I/O shell around `decide`.
+ *
+ * Never throws and never sets a failing exit code. A hook that fails breaks the user's
+ * session, and anything on stdout that is not the envelope is a malformed hook response,
+ * so every problem here ends as empty stdout plus one stderr line. Ordinary quiet cases
+ * (no index, a search scoped to another language) say nothing at all.
+ */
+export declare function runHook(harness: string, event: string, io: HookIo): Promise<void>;
+/** Production wiring, called from `cli/index.ts` and from the commander registration. */
+export declare function runHookFromProcess(harness: string, event: string): Promise<void>;
+//# sourceMappingURL=hook.d.ts.map

package/dist/cli/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/cli/hook.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AACrD,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,QAAQ,CAAC;AAEnD,qFAAqF;AACrF,MAAM,WAAW,MAAM;IACrB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,GAAG,IAAI,MAAM,CAAC;IACd,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,wEAAwE;IACxE,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,8FAA8F;IAC9F,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C;AAED,eAAO,MAAM,eAAe,QAEyC,CAAC;AAuFtE;;;GAGG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAKtG;AAeD;;;;;;;GAOG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BvF;AAoCD,yFAAyF;AACzF,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}