/map

The Living Map

The Living Map is a derived, always-fresh structural view of a codebase that craft agents read instead of re-exploring the same files on every invocation. It is an optimization you never have to set up: it builds itself the first time an agent needs to orient in an area, and it is wired to never block - if anything goes wrong it quietly drops to a coarser view rather than erroring.

This is a reference for the curious or the stuck. Nothing here is required reading to use craft.

How it works

• **Structural, not semantic.** The map records what the code *is* - files, symbols,

signatures, scope - parsed with a bundled WebAssembly parser (web-tree-sitter). It never spends model tokens on facts a parser gets for free.

• **Per area, on demand.** An agent asks for one directory; the map returns that

directory's own files only, ranked by reference frequency and trimmed to a token budget. Huge repos are never indexed up front.

• **Three tiers, one identity.** Nested-scope code (C#, TypeScript, TSX, Java,

Python, JavaScript) is parsed into fully-qualified anchors. Shell falls to a flat floor. Markdown headings become slug paths. Anything else gets a file-level anchor.

• **Always fresh.** A file's slice is keyed to a content hash. Edit the file and the

next read re-derives just that file; everything else stays cached. A branch switch cannot serve you a stale slice.

• **It is reached only through `scripts/map/map-run.sh`.** Nothing else depends on

the map's internals.

Why a grammar degrades (the never-lie floor)

A grammar is bundled at a pinned version. Languages move faster than grammars, so a newer language feature can confuse an older grammar. When that happens the parser can mis-bind a name - for example, an out-of-date C# grammar reads a C# 12 primary constructor and attaches the wrong identifier to the class.

The map refuses to ship that. If the parser leaves an error at or before a definition's name, the **whole file degrades to a file-level entry** rather than emit a name it cannot stand behind. A wrong map is worse than a coarse one - it would steer an agent into the wrong code. Clean files in the same run are unaffected.

`/craft:status` shows `Map: active · N langs · M degraded` when this is in effect.

How to refresh

You do not refresh it by hand. The map re-derives any file whose content changed the next time its area is read. If you ever want a clean rebuild, delete `.craft/map/` and the next read rebuilds from source.

How to turn it off

Add to `.craft/settings.yaml`:

map:
  enabled: false

With the map off, craft behaves exactly as it did before the map existed - agents orient from scratch, no map is built, nothing errors. The flag is opt-out: absent means on. You can also tune the per-area token budget:

map:
  token_budget: 4096

Maintainer notes

The committed artifacts (`scripts/map/runner.js` and `scripts/map/grammars/*.wasm`) are regenerated by a build step, not installed by users:

• `npm run build` (in `scripts/map/`) re-bundles `runner.js` and re-vendors the

grammar wasm. Run it after a web-tree-sitter or grammar bump.

• `node tags/vendor-queries.mjs` re-vendors the tree-sitter `tags.scm` queries,

keeping only the patterns the bundled grammar version supports.

• `npm run grammar-check` runs the pre-ship grammar QA gates (golden diff,

parse-error density on known-good code, identifier sanity) before a grammar is trusted. `node_modules` is build-time only and never committed.