mikser-io 9.58.0 → 9.61.0

package/CLAUDE.md

@@ -158,7 +158,12 @@ brevity.
 - `server.js` — Express bring-up: CLI flags (`--server`, `--cors`,
   `--no-cors`), trust-proxy, CORS (with extensible header arrays for
   plugins to push onto), late-binding static mount + listen.
-- `report.js` — the `--json` build report. `warnings` is a VIEW of
+- `report.js` — the `--json` build report. `invalidated` says WHY the
+  build did work (`nothing` / `sources` / `config` / `version` / `clear`),
+  recorded where each is decided — `reportWipe` in database/index.js,
+  `reportChanged` in source.js as the complement of `reportGated`.
+  `evaluated` is what a subsystem looked at vs what exists
+  (`reportEvaluated`), generalised from assets' matchTally. `warnings` is a VIEW of
   `logger.warn`; `faults` is a view of `logger.error` **carrying a
   `code`** — a subsystem declaring it cannot work, deduped by that code,
   never cleared per cycle, and surfaced in `mikser_ping`. The log call is
@@ -182,6 +187,14 @@ brevity.
   `isRefKey`, `writeEntity`, `matchEntity`, `getFormatInfo`,
   `changeExtension`, `checksum`, `normalize`, `formatErrorContext`,
   `formatLogArgs`, `ExpandError`, `AbortError`.
+- `src/plugins/render/file.js` — the template filesystem helpers
+  (`readFile`, `jsonFile`, `glob`). Every read RECORDS a query edge by
+  default; `{ track: false }` opts out. Keyed on **`id`, never `uri`** —
+  for a `files` entity `uri` is the DEPLOYED path, so a uri edge matches
+  nothing for the commonest case. `glob` records the PATTERN as a regex
+  over ids, not the matched paths, so a file appearing later still
+  invalidates. Paths resolve against `options.workingFolder` — the
+  render-time `runtime` is a per-render projection with no options on it.
 - `render.js` / `postprocess.js` — Piscina worker entry points AND the
   default-export functions the INLINE/SERIAL dispatcher calls directly.
   Each receives entity + options + config + state; the WORKER path also
@@ -197,7 +210,12 @@ brevity.
   `descriptor.options` and arrive as the `config` arg to
   `load`/`render`/`setup`/`postprocess`/`teardown`.
 - `config.js` — loads `mikser.config.js` at `onLoad` into
-  `runtime.config`. v9 holds only engine-level keys (`server`,
+  `runtime.config`. The cache-invalidating stamp covers the config's whole
+  local module graph, captured via `module.registerHooks` during the import
+  (Node 22.15+; older runtimes fall back to the entry file and warn). Scoped
+  to the config's own directory — `node_modules` alone is not enough of a
+  filter, because a workspace symlinks its siblings outside it. Coverage is
+  published at `runtime.options.configCoverage` and in the build report. v9 holds only engine-level keys (`server`,
   `logging`, `catalog` if tuned) plus the `plugins` array — all
   plugin options moved to the factory call site (ADR-0010).
 - `plugins.js` — dispatches v9 plugin entries at `onLoad`. Each

package/README.md

@@ -6,17 +6,21 @@
 
 # Mikser
 
-**Mikser is the AI-native content engine.** It mixes content from anywhere — markdown files, Google Sheets, your ERP, a CMS, any API — into one live catalog, links it together with references, and ships it to any frontend. Edit a price in your ERP or a cell in a spreadsheet, and every page that uses it updates within seconds — in whatever framework you built the site with.
+**Mikser is the AI-native content engine.** It mixes content from anywhere — markdown files, Google Sheets, your ERP, a CMS, any API — into one live index of everything you publish, keeps track of how the pieces point at each other, and ships it to any frontend. Edit a price in your ERP or a cell in a spreadsheet, and every page that uses it updates within seconds — in whatever framework you built the site with.
 
-**Framework-agnostic on both ends.** Headless CMSes (Sanity, Contentful) free you from the database but lock authoring into their UI. Frameworks like Astro let you bring any frontend but lock you into the framework. Mikser frees both: **any source in, any frontend out.** Provider plugins turn external systems into content sources; the catalog is served over plain HTTP, with idiomatic [Vue](https://github.com/almero-digital-marketing/mikser-io-sdk-vue) / [React](https://github.com/almero-digital-marketing/mikser-io-sdk-react) / [Svelte](https://github.com/almero-digital-marketing/mikser-io-sdk-svelte) SDKs on top (`useDocument`, `useDocuments`, multilingual `useHref`, live SSE). It's also AI-native: agents read and write the same catalog over MCP using the same calls a frontend developer uses — there's no separate "AI API" to keep in sync.
+Two words appear throughout, and they mean what they sound like. The **catalog** is that index: everything mikser currently knows about your content, in one place you can ask questions of. A **reference** is one piece of content pointing at another — an article at its author, a product page at the price behind it, a landing page at the photo it uses. Mikser knowing those links is what makes most of the rest possible.
 
-**References merge sources into one call.** Mikser tracks how entities reference each other — an article's author, the marketing copy and ERP price behind a product page, the images a landing page uses. Fetch the product and pull its marketing copy, price, and hero image along with it in one round-trip. Change any of them and every page subscribed to a reference touching it re-renders live, without polling — and mikser invalidates *exactly* the pages that depend on it, nothing more.
+**Framework-agnostic on both ends.** Headless CMSes (Sanity, Contentful) free you from the database but lock authoring into their UI. Frameworks like Astro let you bring any frontend but lock you into the framework. Mikser frees both: **any source in, any frontend out.** Small adapters turn outside systems into content sources; the catalog is served over ordinary HTTP, with [Vue](https://github.com/almero-digital-marketing/mikser-io-sdk-vue) / [React](https://github.com/almero-digital-marketing/mikser-io-sdk-react) / [Svelte](https://github.com/almero-digital-marketing/mikser-io-sdk-svelte) libraries on top that make it feel native, including live updates pushed to the browser. It's also AI-native: agents read and write that same catalog through MCP — the open standard AI assistants use to talk to outside tools — with the same calls a frontend developer makes. There's no separate "AI API" to keep in sync.
+
+**References merge sources into one call.** Because mikser knows how the pieces point at each other, you can fetch a product page and pull its marketing copy, its price and its hero image along with it in one round-trip — even though those three came from three different systems. Change any one of them and every page that uses it updates by itself, without anything asking repeatedly whether something changed — and only the pages that actually depend on it, nothing more.
+
+**And it can answer for what an agent did.** The reason to hesitate before letting an AI edit a real website isn't that it's hard to set up — it's *it'll break something and nobody will notice until a client calls*. Mikser is built so you don't have to take the agent's word for it: point at any text on the finished site and it tells you which file wrote it, ask before a change and it lists the pages that will be affected, and it refuses the edit outright if someone else touched the file in the meantime. [What an agent can ask](#what-an-agent-can-ask) is the short version.
 
 **Your content stays yours.** Source files live on disk as `.md` / `.yml` — diffable, version-controllable, portable on day one and year ten. No database lock-in, no proprietary export. And it's the content layer, not your whole backend: business logic, accounts, and transactions stay in their own services; mikser handles the part that's actually content — rendered to HTML, PDF, email, and other formats from the same source.
 
-Built for Node.js around a strict lifecycle and a composable plugin system: every document, asset, and template flows through the same pipeline, and plugins hook in at any phase. MIT-licensed, runs on Node, zero hosted dependencies. **The portability promise is the architecture, not a feature.**
+Built for Node.js around a fixed sequence of build steps and a plugin system: every document, image and template goes through the same pipeline, and a plugin can attach to any step in it. MIT-licensed, runs on Node, zero hosted dependencies. **The portability promise is the architecture, not a feature.**
 
-> **New to mikser?** Read the [Architecture Overview](./docs/overview.md) — one document, end-to-end walkthrough of how a file becomes a deployed page across all twenty lifecycle phases. It's the doc most projects need first.
+> **New to mikser?** Read the [Architecture Overview](./docs/overview.md) — one document, start to finish, on how a file becomes a published page. It's the doc most projects need first.
 
 ## Where it fits
 
@@ -34,23 +38,21 @@ Build mikser into the parts of your application that are content-shaped. Keep th
 
 ## Why mikser
 
-**Your content stays yours.** Source files live on disk as `.md`, `.yml`, `.html` with YAML front-matter. The build output is plain static files. No database lock-in, no proprietary export format. The whole content tree is copyable, diffable, and version-controllable with git — your site is portable on day one and on year ten.
-
-**Static-first with a built-in live channel.** Most content engines pick one side: static-site generators (Hugo, Eleventy, Jekyll) are fast but rebuild-only; headless CMSes (Sanity, Contentful, Strapi) are live but every page is an API round-trip. Mikser composes both — content publishes as static files by default (fast first paint, no API on the happy path), and the live channel arrives on top, so edits show up in connected clients without a refresh and without losing the static advantage.
+**Fast pages that still update live.** Most tools make you choose. Site generators (Hugo, Eleventy, Jekyll) produce fast pages but only change when you rebuild them; hosted CMSes (Sanity, Contentful, Strapi) update instantly but every page view waits on their API. Mikser does both: pages are published as real files, so they load fast and don't depend on anything being up, and updates arrive on top of that — an edit shows up in an open browser without a refresh.
 
-**Incremental builds that scale.** Mikser tracks every entity in a journal. When a file changes, only the affected entities re-process — not the whole site graph. On 10k+ documents this dramatically outpaces tools that rebuild more on every change.
+**It only rebuilds what changed.** When a file changes, mikser works out what actually depends on it and redoes only that — not the whole site. On a site with ten thousand pages that is the difference between a rebuild you wait for and one you don't notice.
 
-**Concurrent rendering.** Renders run async by default and CPU-heavy layouts (MJML compile, image processing, custom transforms) opt into a Piscina worker pool per layout via `task: worker` in frontmatter. Multi-format outputs (HTML, PDF, MJML email, etc.) generate from the same source; the pool is lazy — no workers spawn until they're asked for.
+**Heavy work runs in parallel.** Pages render concurrently, and anything genuinely slow — compiling an email template, processing an image — can be moved onto separate CPU cores by adding one line to the template. HTML, PDF and email all come from the same source document.
 
 **Asset pipelines are whatever Node can do.** Most static frameworks (Astro, Next.js, Hugo) ship image optimization and stop there — video transcoding, AI upscaling, watermarking all need a separate service. Mikser runs user-written modules over binary inputs: ~10 lines around `sharp` resize an image, ~10 around `fluent-ffmpeg` transcode a video, ~30 around the Replicate API upscale with AI. Anything an npm package can do, your pipeline can do — including pulling uploads from a DAM or CDN through the same flow.
 
-**One lifecycle, everything composes.** Plugins hook into 20+ named lifecycle phases. A search-indexing plugin shares the same journal iteration as an email-rendering plugin and a PDF-postprocessing plugin — no glue code, no orchestration layer. The engine doesn't know which plugins are loaded; plugins don't have to know about each other.
+**Everything composes.** A build is a fixed sequence of named steps, and a plugin attaches to whichever ones it needs. A search-indexing plugin, an email renderer and a PDF generator all see the same run without knowing about each other, and without any glue code holding them together.
 
 **Run anywhere.** The same CLI handles one-shot builds, watch-mode dev loops, and a long-running HTTP server with a shared Express app. `npx mikser` ships a static site; `mikser --watch` is the dev loop; `mikser --server` exposes a live admin/API.
 
-**Outages don't take you down.** Headless CMSes (Contentful, Sanity, Strapi) treat the API as the source of truth — when it blinks, every frontend errors out. Mikser inverts that: reads become static files on disk, the live channel layers on top. A reverse proxy keeps serving the files when mikser blips. Visitors don't notice; live updates pause until mikser returns.
+**Outages don't take the site down.** With a hosted CMS, the API *is* the site — when it blinks, every page errors. Mikser publishes real files to disk and layers live updates on top, so if mikser itself stops, the files keep being served. Visitors see nothing; live updates simply resume when it's back.
 
-**Library mode.** Mikser is also a library. `useRenderer`, `useCollection`, and direct lifecycle hooks let you embed the engine inside an existing Node app instead of running it as a CLI — plugins like `vector` add their own primitives the same way.
+**Use it as a library.** Mikser doesn't have to be a command you run. You can embed the engine inside an existing Node application and drive it directly.
 
 **Open source.** MIT-licensed, on GitHub, no telemetry, no auth wall, no SaaS dependency. What you see is what runs.
 
@@ -58,15 +60,15 @@ Build mikser into the parts of your application that are content-shaped. Keep th
 
 A real content stack pulls from more than one system. Marketing copy lives in a CMS or a spreadsheet. Prices and stock live in an ERP. Hero images live in a DAM. Editorial pages live in markdown files in the repo. Most teams either pick one tool and contort the rest to fit it, or build sync services that copy everything into one database — and then more sync services when things drift out of sync.
 
-Mikser is built around a different bet: **one queryable substrate that any source can pour into, and any frontend can read from.**
+Mikser is built around a different bet: **one place any source can pour into, and any frontend can read from.**
 
-**Any source.** Provider plugins let you treat external systems as content sources. A Google Sheet, an ERP feed, a Drive folder, a Notion database, an HTTP webhook, the local repo's `.md` files — each becomes a stream of entities flowing into mikser's catalog with the same shape. The authoring tool doesn't change. The editorial workflow doesn't change. The team writing product copy in Google Sheets keeps writing product copy in Google Sheets — mikser just notices when they save.
+**Any source.** Small adapters let you treat outside systems as content sources. A Google Sheet, an ERP feed, a Drive folder, a Notion database, the `.md` files in your repo — each pours into the catalog in the same shape, so everything downstream treats them alike. The authoring tool doesn't change. The editorial workflow doesn't change. The team writing product copy in Google Sheets keeps writing product copy in Google Sheets — mikser just notices when they save.
 
-**Cross-source composition through references.** Mikser tracks references between entities the way a graph database does. A product page can declare `$marketing` pointing at a row pulled from a spreadsheet, `$pricing` at a record pulled from your ERP, `$hero` at an asset pulled from your DAM. A single API call from your frontend asks for the product page *with* its referenced data — and gets the page, the marketing copy, the price, and the hero image merged into one response. One round trip, not three or four, and no consumer-side join logic to maintain.
+**Pieces from different systems, joined.** A product page can point at a row from a spreadsheet for its copy, a record from your ERP for its price, and a photo from your asset library — and one request from your frontend returns all four together. One round trip instead of four, and no stitching code on your side to keep working.
 
-**Live updates are uniform across every source.** Edit a cell in the spreadsheet, change a price in the ERP, replace an asset in the DAM — the pages depending on those entities update within seconds, in every frontend connected to mikser's live channel. You don't write per-source invalidation; mikser already knows which pages reference what.
+**Live updates work the same way whatever the source.** Edit a cell in the spreadsheet, change a price in the ERP, swap a photo in the asset library — the pages that use them update within seconds, everywhere. You don't write anything to make that happen for each source; mikser already knows which pages use what.
 
-**Your frontend is whatever you want.** Mikser exposes the catalog over HTTP (and over MCP, for AI agents). You query it from React, Vue, Svelte, SvelteKit, Next.js, an iOS app, a kiosk — anything that speaks HTTP. The framework SDKs (`mikser-io-sdk-react`, `mikser-io-sdk-vue`, `mikser-io-sdk-svelte`) make the calls feel native, but they're optional. Headless CMSes free you from the database lock. Frameworks like Astro free you from one kind of authoring lock. Mikser frees you from both at once: **any source on the input side, any framework on the output side.**
+**Your frontend is whatever you want.** The catalog is served over ordinary HTTP (and over MCP, for AI agents). You read it from React, Vue, Svelte, SvelteKit, Next.js, an iOS app, a kiosk — anything that can make a web request. The framework SDKs (`mikser-io-sdk-react`, `mikser-io-sdk-vue`, `mikser-io-sdk-svelte`) make the calls feel native, but they're optional. Headless CMSes free you from the database lock. Frameworks like Astro free you from one kind of authoring lock. Mikser frees you from both at once: **any source on the input side, any framework on the output side.**
 
 What this looks like in practice:
 
@@ -78,15 +80,15 @@ Adding a source is mechanical. See [`mikser-io-csv`](https://github.com/almero-d
 
 ## Built for AI-assisted development
 
-Files-as-source isn't just a portability story — it makes the project unusually friendly to AI coding agents. There's a static-time half (the agent reads your tree the way it reads any repo — no DB connection, no schema upload, no sandboxed query layer to learn) and a runtime half (when the agent needs to write or render, mikser ships its own MCP server in core, so it talks to the live engine instead of a parallel REST shim you have to maintain).
+That last section was about an agent looking after a site that already exists. This one is about building one in the first place — where keeping content in files turns out to matter for a second reason: a coding assistant can read your whole project the way it reads any repository, with no database to connect to and no schema to be told about. And when it needs to write something or render a preview, it talks to the running engine directly rather than through a separate API somebody has to maintain.
 
 **Zero infra friction for discovery.** An agent can `rg "type: product"` across the content tree to find every product doc in a second. No DB connection, no API token, no schema file to parse.
 
 **The schema emerges from examples, not a definition file.** Front-matter shows what fields exist *in the docs that exist*. Markdown + YAML are overwhelmingly well-represented in AI training data, so the model "speaks" them fluently and infers structure from real documents better than from a schema definition.
 
-**Determinism shortens the iteration loop.** Save a file → watcher fires → predictable rebuild. No DB triggers, no surprise cache invalidation, no API quotas. The agent's mental model of "what happens next" can be precise instead of probabilistic.
+**What happens next is predictable.** Save a file, the build runs, the output changes — no database triggers firing elsewhere, no cache clearing itself at an awkward moment, no rate limits. An assistant can reason about the result instead of guessing at it.
 
-**The SDK's `.d.ts` is the read-side contract.** When the agent writes frontend query code, the operator subset and envelope shape are right there in types — a step-change for code generation quality versus "go read the REST API docs."
+**The types are the documentation.** When an assistant writes frontend code against mikser, the shape of every query and response is described in TypeScript types it can read directly — which produces markedly better generated code than pointing it at API docs and hoping.
 
 **Plugin-by-example.** Authoring a new plugin? There are 15+ existing ones in the same shape to pattern-match against. Convention is dense enough that new plugins look like the old ones without coaching.
 
@@ -101,20 +103,20 @@ Files-as-source isn't just a portability story — it makes the project unusuall
 
 The runtime half — the agent driving the live engine, not just reading the tree — gets its own section below.
 
-The honest caveat: this advantage is real on **content-shaped work** — adding pages, restructuring collections, generating new layouts, building frontends. It doesn't make mikser better for non-content tasks (concurrency bugs in the worker pool, database tuning elsewhere in your stack); those are plain Node debugging like anywhere else. The visibility advantage also degrades past ~10k documents — at that scale the agent queries via the SDK instead of grepping the tree, which is still good but less "see everything at once."
+The honest caveat: this helps with **content work** — adding pages, reorganising sections, building frontends. It doesn't make mikser better at everything else in your stack; that's ordinary debugging like anywhere. And the "read the whole project at once" advantage fades past roughly ten thousand documents, where an assistant queries the catalog instead — still good, less panoramic.
 
 ## Control mikser from your AI agent
 
 Install the [`mikser-io-mcp`](https://github.com/almero-digital-marketing/mikser-io-mcp) plugin and any MCP-speaking client — Claude Desktop, Claude Code, ChatGPT, custom agents — connects to the running engine. From inside a chat, your AI can:
 
-- read every entity in the catalog
-- write new content files (markdown, layouts, configuration) — writes land on disk and the next cycle picks them up
-- render any layout for preview without touching the output folder
-- **surface interactive UI inline in the conversation** — you author the UI as a normal mikser layout with YAML frontmatter (`mcpUi: { mode, actions }`). The agent reads `mikser://mcp-ui/modes` to discover what UIs your project supports, calls `mikser_preview_ui` to render one against an entity, and the host displays the result as a sandboxed iframe in the chat. Buttons in the UI deliver their click back as a separate MCP tool turn — the iframe sends a JSON-RPC `tools/call` to the host over `postMessage` per the [MCP Apps spec](https://github.com/modelcontextprotocol/ext-apps), which the host bridges into a real `mikser_ui_action` invocation. The agent sees a structured `{action, entityId, payload}` result; if you declared `mcpUi.handler.url`, mikser forwards the action to your webhook first and uses its response. No separate UI framework, no glue code; layouts are still just layouts
-- watch every build log as it streams past
-- introspect engine state — current lifecycle phase, effective config, recent log buffer
+- read anything in the catalog
+- write new content — pages, templates, settings. The file lands on disk and the next build picks it up.
+- render a page just to look at it, without publishing anything
+- **show you a real interface inside the chat.** Instead of describing a change, the agent can render an actual editable panel — a form, a preview with Approve and Reject buttons — and you click it in the conversation. Pressing a button sends your answer straight back to the agent as its next step.
 
-Plugins extend the tool surface the same way they mount HTTP routes; install the plugin, the agent gets new verbs. No glue code, no per-project agent wiring.
+  You build those panels as ordinary mikser templates; there is no separate UI framework and no glue code. Under the hood they follow the [MCP Apps spec](https://github.com/modelcontextprotocol/ext-apps): the panel renders in a sandboxed frame, a click travels back as a real tool call, and if you point it at a webhook of your own, mikser forwards the action there first and uses the reply.
+
+Plugins add to what the agent can do the same way they add web routes: install one, and the agent has new abilities. Nothing to wire up per project.
 
 ```js
 // mikser.config.js
@@ -132,21 +134,46 @@ mikser --server                 # MCP mounts at /mcp on the same port
 
 What that feels like in practice: *"draft three hero-section variants and show me previews"* — three layouts written, three previews returned inline, one chat turn. *"Why did the build break?"* — the agent reads the rolling log buffer and answers from the same view your terminal sees. *"Update this article's tone and show me the preview"* — the agent edits the file and surfaces the rendered article inline; you click Approve or Reject, the agent acts on your choice. Operator, AI, and any observer dashboard share the same engine because mikser is single-tenant by design.
 
-### Editing is the easy part — verification is where it pays off
+### What an agent can ask
+
+When an agent changes ten files you can read them all. At two hundred you can't — and that's exactly the point where letting AI do the work starts to be worth it. Most systems leave the checking to you. Mikser lets the agent check its own work first, because the engine kept a record of what it did and can be asked about it afterwards.
+
+**"Where did this come from?"** — point at any text on the finished site and get back the file that produced it, and the line in that file. Nothing else needs to happen: the engine noted it while building. Without this, finding which file writes a particular button means opening the site in a browser, poking at the page source and guessing at filenames.
+
+**"What else is using this?"** — before removing a photo, a page or a person, ask what still points at it. The answer is a list, not a search that might have missed something.
+
+**"What will this change touch?"** — ask before writing, not after. You get back the pages that would be rebuilt and why each one — so nobody discovers on Monday that editing a shared snippet quietly changed forty pages.
+
+**"Did it actually work?"** — the site as it really is on disk, compared against what the engine believes it published. "The build said it succeeded" and "the site is actually up to date" are two different claims, and this checks the second one.
 
-When an AI agent edits ten files, the next question is: *did it do what I asked?* When it edits two hundred, you can't read them all yourself — and that's exactly the scale where AI editing starts being interesting. Most content systems leave verification to the human (read the diff, check the preview, hope you caught the issues). Mikser turns the questions a reviewer would ask into things the agent can answer for itself:
+Alongside those: search the whole site for anything that still reads the old way, and — because everything is ordinary files — the same change history and one-command rollback your developers already use for code.
 
-- **"Did I update every article that needed it?"** — semantic search finds anything that still matches the old tone or phrasing the agent was supposed to change.
-- **"What else mentions this person, product, or topic?"** — mikser knows how content references content. "Show me every page that mentions Dick" returns the list instantly, no full-tree scan.
-- **"Did anything break?"** — if a reference points at something that no longer exists, mikser surfaces it as a warning. The build either completes cleanly or doesn't.
-- **"Can I see what this looks like before publishing?"** — render any single page or section on demand, no full rebuild, no staging deploy. With an `mcpUi` layout, the agent surfaces the rendered preview *inside the chat* with approve/reject controls; one click sends the result back as the tool response.
-- **"What changed since I last looked?"** — `git diff`. The catalog is plain files, so the audit trail is the same one your engineers already use for code.
-- **"Roll back this batch?"** — `git checkout`. Atomic. No database migration to undo, no version-history-feature to learn.
+What this changes: reviewing AI work stops being *read every single change* and becomes *spot-check where the agent was least sure.*
 
-The shift this enables: AI review stops being *"read every change"* and becomes *"spot-check the agent's confidence."* The agent verifies its own work; the human samples and approves. That's the workflow that lets a content team actually use AI at scale — change the tone across the entire site in a morning, ship it after a coffee.
+### What stops an agent breaking your site
+
+The other half is the engine saying no. Not politely stepping aside — actually refusing to do things it can tell are wrong:
+
+- **It won't overwrite somebody else's work.** If a person, or another agent, changed the file since this one read it, the edit is refused rather than quietly replacing what they wrote.
+- **Undo takes back one piece of work, not everything since.** Documents added afterwards stay. And if taking a change back would leave a link pointing at a page that no longer exists, it refuses — even though the file change itself would have gone through fine. That broken link is the failure nobody spots until it's live.
+- **Nothing is deleted quietly.** A delete first lists what still points at the thing being removed. Uploaded files go to a recycle folder rather than being erased, so a wrong call is recoverable.
+- **People only get the parts of the site they should have.** You decide who may change the words, who may change the design, who may do both. When an agent hits that boundary it doesn't just fail — it says which role could do the thing, which is a sentence the person can forward to whoever can. That's the difference between a dead end and a handoff.
+- **If something is broken, it says so.** "No results" because a feature has failed and "no results" because there genuinely aren't any look identical everywhere else. Here, the agent can tell which one it's looking at — and so can you.
 
 Full tool reference and twelve worked scenarios in the [`mikser-io-mcp` plugin docs](https://github.com/almero-digital-marketing/mikser-io-mcp#readme).
 
+## The handoff
+
+The shape this is built for: a developer builds the site, hands it to the client, and the client points their own agent at it. From then on changes happen inside the structure that was designed, rather than the agent reinventing it.
+
+What makes that work is that the boundary is real, not a convention everyone agrees to respect. You decide which parts of the site each kind of person may change — the words, the pictures, the design, the templates — and you write the description of each role in your own words. Mikser hands that description to whoever is asking. A site might describe its editor role as:
+
+> Pages, text and images. Can read the templates and styles to see how a page is built, but not change them — so nothing edited here can break the site.
+
+An agent connecting as that role sees exactly that sentence, what it may change, what it may only look at, and what the other roles on the site can do. When it reaches the edge of what it's allowed, it stops and names the role that could do the thing instead — so the answer is *ask your developer about the design system*, not a blank error the agent might try to route around. There is no way for it to ask for more access, and there won't be.
+
+So the developer's structure holds because the engine holds it, the client gets an agent that can genuinely change the content, and when something is out of bounds you get a sentence with a name in it rather than a broken page nobody noticed.
+
 ## Plugins on top of the engine
 
 The engine is what stays stable — the lifecycle, the catalog, the file-based content model. Plugins are independent npm packages sitting on the plugin API: some are essential to the SSG workflow, some give external systems HTTP access to the catalog, some are integrations that earn their keep on real projects, and some are probes that test how far the lifecycle stretches without touching the core. Install what a project needs; drop what it doesn't.
@@ -237,11 +264,11 @@ For a working starter — config with a real plugin set, sample `documents/`, ex
 The shape mikser fits cleanly:
 
 - **Marketing sites with editorial teams** — content authors work in files (via their editor, a Git client, or `mikser-io-decap`), engineers ship features without negotiating with a CMS schema, the site stays portable.
-- **Multilingual publishing platforms** — the `useHref()` / `useAlternates()` pattern decouples logical references from per-locale URLs. One source tree, many language deployments.
-- **Content-heavy product catalogues** — `documents` + `mikser-io-schemas` + `data` plugin + a Frontend Framework = typed product listings with live updates, semantic search via `vector`, and static-CDN-friendly JSON snapshots all at once.
-- **AI-augmented media pipelines** — `assets` plugin presets call out to Replicate / OpenAI / local models to upscale images, transcribe audio, transcode video. The pipeline is JS code, so anything Node can do is in scope.
-- **Mixed-output publishing** — the same source document renders to HTML, PDF (via `post-pdf`), MJML email (via `post-mjml`), and JSON snapshots. One catalog, many output formats, all concurrent.
-- **Headless backends for static frontends** — pair the `api` plugin with `sdk-api` for SSE-driven live frontends; pair the `data` plugin output with any static host for pre-rendered consumption.
+- **Multilingual publishing** — link to a page by what it *is*, and each language gets the right URL automatically. One source tree, many language sites.
+- **Large product catalogues** — product listings that update live, search by meaning rather than exact words, and pre-built data files a CDN can serve — from the same source.
+- **AI-assisted media handling** — upscale images, transcribe audio, transcode video, on the way in. The pipeline is ordinary JavaScript, so anything Node can do is available to it.
+- **One source, several formats** — the same document becomes a web page, a PDF and an email, all from one edit.
+- **A content backend for a frontend you already have** — serve it live over HTTP, or export flat files for any static host.
 
 The shape mikser **doesn't** fit cleanly: anything with non-technical content authors who can't or won't work with files, anything with non-content business logic at the core, anything needing multi-tenant / per-user auth. Those aren't bugs — they're outside the design envelope. See [`decisions/0001-content-layer-not-the-app.md`](./docs/decisions/0001-content-layer-not-the-app.md) for the explicit scope decision.
 
@@ -256,7 +283,7 @@ What you get from how this project is built:
 
 ## Mikser among static site generators
 
-**The only SSG that's both fast enough for daily use and deep enough for AI agents to drive.**
+Mikser is often evaluated against static site generators, so here is the honest placement. **It does not win on speed** — Hugo does, and that is worth knowing. What mikser has that none of them do is a build the engine can answer questions about afterwards.
 
 | SSG | Speed | Feature surface | The tradeoff |
 |---|---|---|---|
@@ -264,9 +291,11 @@ What you get from how this project is built:
 | Eleventy | OK | Broad, no introspection | Flexible but slow at corpus scale |
 | Astro | OK | Modern, framework-coupled | Tied to a frontend framework |
 | Next.js SSG | meh | Full framework | Framework first, content second |
-| **Mikser** | Incremental beats Hugo's full rebuild | Broad, deeply observable, AI-native | None of the speed-vs-features kind |
+| **Mikser** | Fast enough that watch-mode rebuilds feel instant | Broad, and queryable after the fact | Not the fastest cold build |
+
+Hugo wins a full cold rebuild. Most cycles aren't full cold rebuilds — CI deploys, watch-mode edits, "ran mikser, nothing changed" — and there the persistent manifest skips what is still current. But speed is not the axis worth choosing mikser on, and a reader who evaluates it as a faster SSG will miss what it is for.
 
-Every other SSG asks you to trade something — raw speed for features (Hugo), features for framework lock-in (Astro, Next), introspection for any of the above (Eleventy). Mikser doesn't make that trade. Hugo still wins a full cold rebuild — and that's worth knowing — but most cycles aren't full cold rebuilds. CI deploys, watch-mode edits, "ran mikser, nothing changed" — these are the daily case, where Mikser's persistent manifest skips what's still current while Hugo rebuilds everything from scratch. The rest of the feature surface (MCP introspection on every lifecycle phase, files-as-source-of-truth, 20-phase composability, multi-format outputs from one corpus) is what no other "fast" SSG carries.
+**The comparison that actually matters is different.** If you are handing a site to someone whose agent will edit it, the real alternative is a headless CMS with an MCP wrapper: structured content, and no way to check what the agent did to it. That is the gap [What an agent can ask](#what-an-agent-can-ask) describes, and it is not a speed question.
 
 ## Acknowledgments
 

package/docs/api-reference.md

@@ -1112,6 +1112,17 @@ debris; `isJunkPath(filePath)` asks.
 
 Plugin factories — `yaml()`, `json()`, `frontMatter()`, `assets()`,
 `resources()`, `shares()`, `observer()`, `mapper()`, `commands()`,
+
+`observer({ <name>: { readMany, readOne?, uri?, cron?, collection?, type? } })`
+pulls entities from an external API and keeps the catalog in step with it:
+`readMany` supplies the records, each becomes an entity under
+`/observer/<collection>/<record.id>` with the record as its meta, and anything
+the source no longer returns is deleted. Writes are gated on a checksum of the
+meta, so a frequent cron over unchanged records writes nothing. `readOne` is
+the single-record path a webhook uses. `uri` is OPTIONAL — give it the
+collection's endpoint and mikser can route a webhook to it by origin and record
+where each entity came from; leave it out for a source with no addressable URL,
+and the entities are synthetic, with the record as their whole content.
 `renderHbs()` — are configured rather than called, and live in
 [configuration.md](configuration.md).
 

package/docs/diagnostics.md

@@ -26,6 +26,9 @@ engine source, the entry point is missing and belongs on this page.
 | I am an agent reading CLI output, not speaking MCP | [`--tools` / `--tool`](#the-two-agent-workflows) |
 | Did my schema validate anything at all? | [`schemas.names()`](#schemasnames--schemaslookup) |
 | A tool answered emptily — is it broken, or is there nothing to find? | [`faults`](#faults) |
+| I edited the build and nothing rebuilt | `--json` → `config.files` |
+| Why did this build do any work at all? | `--json` → `invalidated` |
+| Did my new pattern get a chance to match? | `--json` → `evaluated` |
 
 ## Command line
 
@@ -150,6 +153,33 @@ The buckets, and the distinction between them is the point:
 | `warnings` | everything that went through `logger.warn` this cycle, with its `code` |
 | `faults` | subsystems that reported they **cannot work** — see [Faults](#faults) |
 
+`invalidated` says why the build did anything, which the counts never did —
+`0 rendered` reads the same whether nothing needed doing or something did and
+the engine failed to notice:
+
+| cause | means |
+| --- | --- |
+| `nothing` | the engine looked and there was no work. A finding, not an absence — check `summary.gated` to see how much it looked at |
+| `sources` | these files changed, named in `changed` (capped, with `truncated` when there were more) |
+| `config` | the config or a module it imports moved, so the cache was wiped |
+| `version` | the engine version moved, with `from` and `to` |
+| `clear` | you passed `--clear` |
+
+A wipe outranks changed sources: once the cache goes, every file is a changed
+file and listing them all is noise.
+
+`evaluated` says what each subsystem actually looked at, against what exists —
+`{ assets: { evaluated: 0, of: 397 } }`. A new pattern that never had the
+chance to match anything otherwise looks exactly like a run with nothing to do.
+
+Each report also carries `config`: the files the config stamp spans, and
+whether that coverage is `complete`. The stamp is what makes a config edit
+invalidate the cache, and it covers the config's whole local module graph —
+not just the entry file. So if you keep the build in `config/pipeline.js` and
+import it from both a dev and a prod config, editing the pipeline invalidates,
+which is the case that matters. `config.files` is there so *"I edited the build
+and nothing rebuilt"* is answerable by reading rather than by experiment.
+
 Each report also carries `cycleId`, `startedAt` and `finishedAt`. Under
 `--watch` two consecutive reports are otherwise indistinguishable, so
 "is this my edit's cycle or the one before it" has no answer without the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.58.0",
+  "version": "9.61.0",
   "description": "A mixer for content: entities in, configurable render pipelines, outputs of any kind. Static sites are the canonical recipe, not the definition — the same engine renders PDFs, emails and whatever a renderer plugin produces. Files are the source of truth, every lifecycle phase is observable, and the build graph is queryable by an agent.",
   "main": "index.js",
   "exports": {

package/src/catalog.js

@@ -536,6 +536,33 @@ export async function findEntities(query) {
     return shim.all().filter(m)
 }
 
+// How many entities match, without materializing any of them.
+//
+// findEntities parses the JSON body of every row it returns, which is the
+// wrong price for a number. A COUNT(*) with the same pushed-down WHERE is one
+// query and no parsing — the difference between asking "how big is the
+// catalog" costing nothing and costing a full scan.
+//
+// Returns null when the query cannot be answered in SQL alone. A residual
+// JS-side clause would require fetching the rows to test them, which is
+// exactly what this exists to avoid, and guessing a number would be worse than
+// admitting there isn't one.
+export function countEntities(query) {
+    if (!db?.isOpen) {
+        const shim = mapStub()
+        if (!shim) return 0
+        if (!query) return shim.all().length
+        const m = typeof query === 'function' ? query : sift(query)
+        return shim.all().filter(m).length
+    }
+    if (!query) return stmtCount.get().c
+
+    const t = siftToSql(query)
+    // A residual matcher means part of the filter never reached SQL.
+    if (residualMatcher(query, t.jsFilter)) return null
+    return db.prepare(`SELECT COUNT(*) AS c FROM mikser_entities ${t.sql}`).get(...t.params).c
+}
+
 // Streaming variant of findEntities. Same query shape, same sift→SQL
 // translation, but yields entities chunk-by-chunk so peak memory is
 // O(chunk × entity) instead of O(corpus × entity).

package/src/config.js

@@ -1,10 +1,74 @@
 import runtime from './runtime.js'
 import { useLogger } from './engine.js'
 import { onLoad } from './lifecycle.js'
-import { checksum } from './utils.js'
+import { checksum, checksumOf } from './utils.js'
 import path from 'node:path'
+import nodeModule from 'node:module'
+import { fileURLToPath } from 'node:url'
 import { existsSync } from 'node:fs'
 
+// Every local module the config actually pulls in, recorded as it loads.
+//
+// The stamp used to be the entry file's bytes alone, and that is inverted
+// against significance the moment a project has more than one config — which
+// is as soon as it has a dev one and a prod one. Both import the module that
+// decides how the site is built; neither IS that module. So a comment in the
+// thin wrapper wiped the catalog, and rewriting the pipeline that processes
+// every asset changed nothing and rebuilt nothing, on a green build.
+//
+// Node's own loader hook rather than parsing import statements. The resolver
+// already knows the answer exactly, including transitive imports and dynamic
+// ones that actually ran, and a regex over source is the kind of thing that
+// silently misses a case — which here means silently not invalidating, the
+// exact failure being fixed.
+//
+// Scoped to files under the config's own directory. `node_modules` is not
+// enough of a filter on its own: a workspace symlinks its siblings, so
+// `mikser-io` itself resolves to a real path outside node_modules and the
+// engine's entire source tree would land in the stamp.
+function captureConfigGraph(root) {
+    const files = new Set()
+    let capturing = false
+
+    // Node 22.15+. Older runtimes keep the previous behaviour rather than a
+    // worse guess, and `configCoverage` says which one is in force.
+    if (typeof nodeModule.registerHooks !== 'function') {
+        return { files, supported: false, start() {}, stop() {} }
+    }
+    nodeModule.registerHooks({
+        load(url, context, next) {
+            if (capturing && url.startsWith('file:')) {
+                const file = fileURLToPath(url)
+                if (!file.includes(`${path.sep}node_modules${path.sep}`)
+                    && !path.relative(root, file).startsWith('..')) {
+                    files.add(file)
+                }
+            }
+            return next(url, context)
+        },
+    })
+    return {
+        files,
+        supported: true,
+        start() { capturing = true },
+        stop() { capturing = false },
+    }
+}
+
+// One stamp over the whole set, path-qualified and order-independent.
+//
+// Path as well as content, so moving a module between two files with the same
+// bytes still counts as a change.
+async function stampGraph(files) {
+    const parts = []
+    for (const file of [...files].sort()) {
+        try {
+            parts.push(`${file}:${await checksum(file)}`)
+        } catch { /* vanished between load and stat — the next cycle sees it */ }
+    }
+    return parts.length ? checksumOf(parts.join('\n')) : null
+}
+
 onLoad(async () => {
     const logger = useLogger()
     const configFile = path.resolve(runtime.options.config)
@@ -19,16 +83,10 @@ onLoad(async () => {
     // invalidation, so the only symptom was output that did not match the
     // config, with nothing saying so.
     //
-    // The file's bytes only. A config that imports other modules will not
-    // notice a change in those, which is a real limit worth knowing rather
-    // than a reason to hash the whole module graph.
-    try {
-        runtime.options.configChecksum = await checksum(configFile)
-    } catch {
-        // No config file is a legitimate state (defaults all the way down);
-        // absent stamp means "nothing to compare", not "changed".
-        runtime.options.configChecksum = null
-    }
+    // Computed AFTER the import, from what the import actually loaded — see
+    // captureConfigGraph. Before it, there is nothing to hash but the entry
+    // file, which is the bug.
+    const graph = captureConfigGraph(path.dirname(configFile))
 
     // Absence is decided by looking for the file, NOT by catching
     // ERR_MODULE_NOT_FOUND from the import.
@@ -48,14 +106,54 @@ onLoad(async () => {
         logger.debug('No config file at %s — using defaults', configFile)
     } else {
         // No catch: any failure loading a config that EXISTS is fatal.
-        const config = await import(configFile)
-        if (typeof config.default == 'function') {
-            runtime.config = await config.default(runtime)
-        } else if (typeof config.default == 'object') {
-            runtime.config = config.default
+        graph.start()
+        try {
+            const config = await import(configFile)
+            if (typeof config.default == 'function') {
+                runtime.config = await config.default(runtime)
+            } else if (typeof config.default == 'object') {
+                runtime.config = config.default
+            }
+        } finally {
+            graph.stop()
+        }
+    }
+
+    // The stamp, and what it covers.
+    //
+    // Coverage is published because "I edited the build and nothing rebuilt"
+    // was only answerable by experiment. It is the difference between a limit
+    // that is documented and one that is visible at the moment it bites.
+    //
+    // Absent stamp means "nothing to compare", not "changed" — no config file
+    // is a legitimate state, defaults all the way down.
+    const covered = [...graph.files]
+    runtime.options.configCoverage = {
+        files: covered.sort(),
+        // False on a runtime without loader hooks, where the stamp is the
+        // entry file alone and a change to anything it imports is invisible.
+        complete: graph.supported,
+    }
+    if (covered.length) {
+        runtime.options.configChecksum = await stampGraph(covered)
+        logger.debug('Config checksum spans %d file(s): %s', covered.length, covered.join(', '))
+    } else {
+        try {
+            runtime.options.configChecksum = existsSync(configFile) ? await checksum(configFile) : null
+        } catch {
+            runtime.options.configChecksum = null
         }
     }
 
+    // Said once, at the only moment it can be acted on. A project whose build
+    // lives in a module the stamp cannot reach gets a rebuild it did not ask
+    // for rather than silence it cannot diagnose.
+    if (existsSync(configFile) && !graph.supported) {
+        logger.warn({ code: 'config-coverage-partial' },
+            'This Node build has no module loader hooks, so the config stamp covers %s alone. Editing a module '
+            + 'it imports will NOT invalidate anything — run with --force after such a change.', configFile)
+    }
+
     // Nothing else is loaded. There is deliberately no `config/<plugin>
     // .config.js` channel: plugin options arrive as factory arguments
     // (ADR-0010), and an entry in `plugins` is a factory call result — a

package/src/database/index.js

@@ -47,6 +47,7 @@ import { mkdirSync, unlinkSync, existsSync, readFileSync, writeFileSync } from '
 import Database from 'better-sqlite3'
 import runtime from '../runtime.js'
 import { isReportOnlyRun } from '../tools.js'
+import { reportWipe } from '../report.js'
 import { onLoaded } from '../lifecycle.js'
 import packageInfo from '../../package.json' with { type: 'json' }
 
@@ -355,6 +356,15 @@ export function createSqliteDatabase({
             } else if (forceWipe) {
                 logger?.info('Clearing the cache and rebuilding from sources.')
             }
+            // Recorded where the decision is made. The report otherwise shows
+            // a cold build and no reason for it, and "everything rebuilt" is
+            // the same output whether the version moved, the config moved, or
+            // someone passed --clear.
+            reportWipe(
+                recorded && recorded !== version ? 'version' : forceWipe ? 'clear' : 'config',
+                recorded && recorded !== version ? { from: recorded, to: version } : {},
+            )
+
             // Unlink, rather than dropping table by table.
             //
             // The wipe used to have to know which tables to keep, because

package/src/plugins/assets.js

@@ -1,3 +1,5 @@
+import { reportEvaluated } from '../report.js'
+import { countEntities } from '../catalog.js'
 import path from 'node:path'
 import { mkdir, writeFile, unlink, rm, readFile, symlink, } from 'fs/promises'
 import { existsSync } from 'node:fs'
@@ -482,6 +484,24 @@ export function assets(options = {}) {
 
         reportUnmatchedPresets(logger)
 
+        // How much of the catalog this run actually looked at.
+        //
+        // The warning above only fires on a full cycle, because on an
+        // incremental one a healthy preset legitimately matches nothing. That
+        // is correct and it leaves the reverse question unanswered: a NEW
+        // pattern that never had the chance to match anything looks exactly
+        // like a run with nothing to do. `evaluated 4 of 397` answers it
+        // without needing a warning to decide whether to fire.
+        try {
+            // COUNT(*), not a fetch: the denominator is a number, and paying a
+            // full scan and a JSON.parse per row to produce it would make the
+            // diagnostic cost more than the thing it diagnoses.
+            reportEvaluated('assets', {
+                evaluated: matchTally.evaluated,
+                of: countEntities({ collection: { $ne: collection } }),
+            })
+        } catch { /* a count is not worth failing a build over */ }
+
         let revisions = await globby('**/*.md5', { cwd: runtime.options.assetsFolder })
         for (let revision of revisions) {
             const [preset] = revision.split(path.sep)

package/src/plugins/observer.js

@@ -2,6 +2,38 @@ import path from 'path'
 import { hash } from 'hasha'
 import _ from 'lodash'
 
+// Where the record came from, when that is knowable.
+//
+// `uri` is optional: an observer reading from an SDK, a local queue or
+// anything without an addressable endpoint has nothing meaningful to put here.
+// The empty string is the established shape for a synthetic entity whose meta
+// IS its content — the same one csv row entities use — and the source sweep
+// scopes on it, so inventing a path like `/7` would be worse than saying
+// nothing.
+function entityUri(base, id) {
+    return base ? `${base}/${id}` : ''
+}
+
+// The origin to register a webhook sync under, or null if there is none.
+//
+// This used to be `new URL(options[name].uri).origin` inline, which made `uri`
+// silently mandatory: leaving it out threw ERR_INVALID_URL out of onLoaded and
+// took the whole build down at startup, with nothing in the message naming the
+// observer or the option responsible. An absent uri is a legitimate config; a
+// malformed one is a mistake, and only the second deserves to stop anything.
+function originOf(uri, observerName, logger) {
+    if (!uri) return null
+    try {
+        return new URL(uri).origin
+    } catch {
+        logger?.warn?.({ code: 'observer-bad-uri' },
+            'Observer [%s] has uri: %j, which is not an absolute URL — so no webhook can be routed to it by '
+            + 'origin. Give it a full URL like https://api.example.com/things, or drop the option if this '
+            + 'observer is not reachable over HTTP.', observerName, uri)
+        return null
+    }
+}
+
 export function observer(options = {}) {
     return ({
         runtime,
@@ -48,7 +80,7 @@ export function observer(options = {}) {
                     recent.add(id)
                     const entity = normalize({
                         id,
-                        uri: `${uri}/${meta.id}`,
+                        uri: entityUri(uri, meta.id),
                         name,
                         collection,
                         type,
@@ -110,7 +142,7 @@ export function observer(options = {}) {
                 const name = path.join(collection, meta.name || meta.id.toString())
                 const entity = normalize({
                     id,
-                    uri: `${uri}/${meta.id}`,
+                    uri: entityUri(uri, meta.id),
                     name,
                     collection,
                     type,
@@ -130,7 +162,12 @@ export function observer(options = {}) {
             } else {
                 if (current) {
                     logger.debug('Observer delete: %s', id)
-                    await deleteEntity(entity)
+                    // `current`, not `entity` — the latter is built inside the
+                    // branch above and is not in scope here, so this threw
+                    // ReferenceError into the surrounding catch and became one
+                    // log line. A record deleted upstream stayed in the
+                    // catalog and went on rendering.
+                    await deleteEntity(current)
                 }
             }
         } catch (err) {
@@ -155,13 +192,15 @@ export function observer(options = {}) {
                 }
             })
 
-            const { origin } = new URL(options[observerName].uri)
-            onSync(origin, async ({ context }) => {
-                if (context.uri) {
-                    logger.debug('Syncing observer: [%s] %s', observerName, context.uri)
-                    return syncEntities(observerName)
-                }
-            })
+            const origin = originOf(options[observerName].uri, observerName, logger)
+            if (origin) {
+                onSync(origin, async ({ context }) => {
+                    if (context.uri) {
+                        logger.debug('Syncing observer: [%s] %s', observerName, context.uri)
+                        return syncEntities(observerName)
+                    }
+                })
+            }
         }
     })
 

package/src/plugins/render/file.js

@@ -1,17 +1,125 @@
 import { readFileSync } from 'node:fs'
-import { globby } from 'globby'
+import path from 'node:path'
+import { globbySync } from 'globby'
+import picomatch from 'picomatch'
 
-export function load({ runtime }) {
-    runtime.readFile = (file) => {
-        const relativePath = file.name || file
-        return readFileSync(relativePath, { encoding: 'utf8' })
+// Filesystem helpers a template can call, and the dependency each one creates.
+//
+// A template that reads a file depends on that file. Until these recorded it,
+// the render's refClosure named none of what it read, so editing the file
+// rebuilt nothing and the output went quietly stale — the same hole lookupHref
+// had before it started recording, and the same failure: a green build and a
+// site that is wrong.
+//
+// So every read records an edge by default. The asymmetry decides it: not
+// recording fails silently and is found weeks later by a person; over-recording
+// costs one rebuild nobody notices. Pass `{ track: false }` for a read that
+// genuinely is not a dependency.
+//
+// WHAT is recorded differs per helper, and the difference matters:
+//
+//   readFile / jsonFile record the resolved PATH. One file, one edge.
+//
+//   glob records the PATTERN, not the paths it matched. Recording the matches
+//   would rebuild when a matched file changes but NOT when a new file appears,
+//   and appearing is half of what a glob is for. A pattern-derived edge covers
+//   both, because it is re-evaluated against whatever exists at the time.
+//
+// Both are `query` edges on `uri`, which is an indexed column — the same
+// mechanism a sidecar's findEntities() already uses, rather than a second one.
+
+// Relative to the WORKING FOLDER, not to wherever the process happens to have
+// been started. `readFile('styles/base.css')` used to resolve against cwd,
+// which quietly worked in development and broke under any launcher that starts
+// mikser elsewhere.
+//
+// The working folder comes from the `options` the engine hands every render
+// plugin. Not from `runtime.options` — the `runtime` a render sees is a small
+// projection built per render, and it has no options on it.
+function resolvePath(workingFolder, file) {
+    const name = file?.name ?? file
+    if (typeof name !== 'string' || !name.length) return null
+    if (path.isAbsolute(name)) return name
+    return path.join(workingFolder ?? '.', name)
+}
+
+// The entity id a path would have, or null if it could not have one.
+//
+// Keyed on `id`, NOT on `uri`. It is tempting to match the filesystem path
+// against `uri` and it is wrong: `uri` means the source file for a document or
+// a layout, but for a `files` entity it is where the file was DEPLOYED to —
+// under the output folder. An edge on uri therefore matches nothing for
+// exactly the case these helpers are most used for, reading parts out of
+// `files/`. Ids are source-relative everywhere, so they are the one key that
+// answers the same question for every collection.
+function entityIdFor(workingFolder, resolved) {
+    if (!workingFolder || !resolved) return null
+    const rel = path.relative(workingFolder, resolved)
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null
+    return '/' + rel.split(path.sep).join('/')
+}
+
+// Whether an entity could exist for this path at all.
+//
+// mikser can only invalidate on entities: a file under no source folder is not
+// watched, has no entity, and no edge can bring it back. That limit is fine —
+// what is not fine is it being invisible, because "tracked it" and "there was
+// nothing to track" read identically from a template. Said once per path.
+const warnedOutside = new Set()
+function warnIfUntrackable(options, resolved, logger) {
+    const folders = ['documentsFolder', 'filesFolder', 'assetsFolder', 'resourcesFolder', 'dataFolder']
+        .map(key => options?.[key]).filter(Boolean)
+    if (!folders.length) return  // nothing configured to compare against
+    if (folders.some(folder => !path.relative(folder, resolved).startsWith('..'))) return
+    if (warnedOutside.has(resolved)) return
+    warnedOutside.add(resolved)
+    logger?.warn?.({ code: 'untracked-file-read' },
+        'A template read %s, which is outside every content folder — so it has no entity, nothing watches it, '
+        + 'and changing it will NOT rebuild the pages that read it. Move it under a content folder if that '
+        + 'matters, or pass { track: false } to say the staleness is intended.', resolved)
+}
+
+export function load({ runtime, options, track, logger }) {
+    const workingFolder = options?.workingFolder
+    const record = (resolved, opts) => {
+        if (opts?.track === false || !resolved) return
+        warnIfUntrackable(options, resolved, logger)
+        const id = entityIdFor(workingFolder, resolved)
+        if (id) track?.query?.({ id })
+    }
+
+    runtime.readFile = (file, opts) => {
+        const resolved = resolvePath(workingFolder, file)
+        record(resolved, opts)
+        return readFileSync(resolved, { encoding: 'utf8' })
     }
-    runtime.jsonFile = (file) => {
-        const relativePath = file.name || file
-        return JSON.parse(readFileSync(relativePath, { encoding: 'utf8' }))
+    runtime.jsonFile = (file, opts) => {
+        const resolved = resolvePath(workingFolder, file)
+        record(resolved, opts)
+        return JSON.parse(readFileSync(resolved, { encoding: 'utf8' }))
     }
-    runtime.glob = (pattern, options = {}) => {
-        return globby.sync(pattern, options)
+
+    // `globby.sync` does not exist — the export is `globbySync`, so every call
+    // here threw TypeError. Loudly, at least, which is why nobody had stale
+    // output from it: the helper simply never worked.
+    runtime.glob = (pattern, opts = {}) => {
+        const patterns = (Array.isArray(pattern) ? pattern : [pattern]).filter(Boolean)
+        const base = opts.cwd ?? workingFolder ?? '.'
+        const resolved = patterns.map(p => (path.isAbsolute(p) ? p : path.join(base, p)))
+
+        if (opts.track !== false && track?.query) {
+            for (const p of resolved) {
+                // The PATTERN as a regex over entity ids, so a file that did
+                // not exist when this render ran still matches once it appears
+                // — which recording the matched paths could never do.
+                const idPattern = entityIdFor(workingFolder, p)
+                if (!idPattern) continue
+                try {
+                    track.query({ id: { $regex: picomatch.makeRe(idPattern).source } })
+                } catch { /* an unparseable pattern records nothing; the glob still runs */ }
+            }
+        }
+        return globbySync(resolved, { ...opts, cwd: undefined })
     }
 
     // Stringify an arbitrary value as a JSON literal. Use with the

package/src/render.js

@@ -308,7 +308,17 @@ export default async ({ entity, options, config, context, state, logger, port, t
     for (let pluginName of pluginsToLoad) {
         const plugin = await loadPlugin(pluginName)
         plugins[pluginName] = plugin
-        if (plugin?.load) await plugin.load({ entity, options, config: plugin.options, context, runtime, state, logger })
+        // `track` goes to load(), not only to render().
+        //
+        // A helper plugin publishes functions a template calls DURING the
+        // render — readFile, glob — and those reads are dependencies exactly
+        // as much as a partial or a lookup is. Without this they could not
+        // record even if they wanted to, so a template that read ten files
+        // produced a refClosure naming none of them: the build stays green
+        // and the output goes stale, which is the same hole lookupHref had.
+        if (plugin?.load) {
+            await plugin.load({ entity, options, config: plugin.options, context, runtime, state, logger, track })
+        }
     }
 
     const rendererPlugin = plugins[`render-${renderer}`]

package/src/report.js

@@ -109,8 +109,12 @@ export function resetReport() {
     const previous = runtime.state.cycle
     if (previous && !previous.finishedAt) finishCycle()
     runtime.state.cycle = { id: nextCycleId(), startedAt: Date.now(), finishedAt: null }
-    runtime.state.report = { rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0 }
+    runtime.state.report = {
+        rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0, evaluated: {},
+    }
     runtime.state.renderErrors = []
+    // Per cycle, unlike the wipe: what changed is a fact about THIS build.
+    runtime.state.changed = { ids: [], count: 0 }
 }
 
 // End of a cycle: stamp it, file it, and wake anyone waiting on it.
@@ -136,10 +140,70 @@ function store() {
     // Without this the build everyone looks at first reports cycleId: null.
     runtime.state ??= {}
     runtime.state.cycle ??= { id: 1, startedAt: Date.now(), finishedAt: null }
-    runtime.state.report ??= { rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0 }
+    runtime.state.report ??= {
+        rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0, evaluated: {},
+    }
+    runtime.state.report.evaluated ??= {}
     return runtime.state.report
 }
 
+// Why this cycle did any work at all.
+//
+// The counts say what happened; they never said what STARTED it. "0 rendered"
+// is the same line whether nothing needed doing, or something needed doing and
+// the engine could not tell — which is the difference between a build you can
+// trust and one you have to reproduce by hand.
+//
+// Two halves, because there are two ways work begins. A WIPE is process-level:
+// the version moved, the config moved, `--clear` was passed, and everything is
+// rebuilt from source. Otherwise it is the sources that changed since last
+// time, which is per cycle.
+//
+// `nothing` is a first-class answer, not an absence. It means the engine
+// looked and there was genuinely no work — which is the one thing an operator
+// most wants distinguished from a build that silently did not notice.
+
+// Set once, by whoever decided to wipe. Not gated on reportWanted: it happens
+// at database open, which may be before a reader has asked for a report, and
+// it is one small object.
+export function reportWipe(cause, detail = {}) {
+    runtime.state ??= {}
+    runtime.state.wipe = { cause, ...detail }
+}
+
+// One source whose bytes moved. The complement of reportGated: between them
+// every file the engine looked at is accounted for.
+export function reportChanged(id) {
+    if (!reportWanted() || !id) return
+    const store = changedStore()
+    store.count++
+    // Capped. On a cold build this is the whole corpus, and the cause already
+    // says so — the list is for the incremental case, where naming the three
+    // files that moved is the entire answer.
+    if (store.ids.length < CHANGED_LIMIT) store.ids.push(id)
+}
+
+const CHANGED_LIMIT = 50
+
+function changedStore() {
+    runtime.state ??= {}
+    runtime.state.changed ??= { ids: [], count: 0 }
+    return runtime.state.changed
+}
+
+// What a subsystem looked at, against what it could have looked at.
+//
+// Generalised from the assets plugin, which already warns when a configured
+// preset matched none of the entities a full cycle evaluated. That reasoning —
+// an incremental cycle only re-evaluates what changed, so matching nothing can
+// be perfectly healthy — is not specific to presets, and neither is the
+// question it answers. "assets evaluated 4 of 397" is the line that tells you
+// instantly that a new pattern never had the chance to match anything.
+export function reportEvaluated(scope, { evaluated, of } = {}) {
+    if (!reportWanted() || !scope) return
+    store().evaluated[scope] = { evaluated: evaluated ?? 0, ...(Number.isFinite(of) ? { of } : {}) }
+}
+
 // An entity whose SOURCE did not change is gated at import and never becomes
 // a render task at all — so it appears in neither `rendered` nor `skipped`,
 // and the two lists would not reconcile with the corpus size without saying
@@ -309,6 +373,25 @@ export function renderErrorCount() {
     return errorStore().length
 }
 
+// The cause, and enough detail to act on it.
+//
+// A wipe outranks changed sources: when the cache went, everything is a
+// changed source and saying so is noise. `nothing` is returned rather than
+// omitted, because an absent field reads as "not recorded" and this is a
+// finding.
+function invalidation() {
+    const wipe = runtime.state?.wipe
+    if (wipe) return wipe
+    const { ids, count } = changedStore()
+    if (!count) return { cause: 'nothing' }
+    return {
+        cause: 'sources',
+        changed: ids,
+        count,
+        ...(count > ids.length ? { truncated: count - ids.length } : {}),
+    }
+}
+
 export function buildReport() {
     const report = store()
     const cycle = runtime.state?.cycle
@@ -325,6 +408,18 @@ export function buildReport() {
         // failed build, whatever the other counts say.
         errors: errorStore(),
         warnings: report.warnings,
+        // Why this build did any work — see reportWipe / reportChanged.
+        invalidated: invalidation(),
+        // What each subsystem looked at, against what it could have.
+        ...(Object.keys(report.evaluated ?? {}).length ? { evaluated: report.evaluated } : {}),
+        // Which files the config stamp spans.
+        //
+        // "I edited the build and nothing rebuilt" was only answerable by
+        // experiment: the stamp covered the entry file, real projects put the
+        // build in a module it imports, and nothing said which. Published
+        // rather than documented, because a limit you can see at the moment it
+        // bites is a different thing from one written down elsewhere.
+        ...(runtime.options?.configCoverage ? { config: runtime.options.configCoverage } : {}),
         // Named conditions reported at error level: a subsystem saying it
         // cannot work, as opposed to `errors`, which is a render that threw.
         // Carried whole rather than filtered to this cycle — a fault raised at
@@ -345,6 +440,8 @@ export function buildReport() {
             gated: report.gated,
             warnings: report.warnings.length,
             faults: faults().length,
+            // Sources whose bytes moved this cycle. The complement of `gated`.
+            changed: changedStore().count,
         },
     }
 }

package/src/source.js

@@ -44,7 +44,7 @@ import pMap from 'p-map'
 import runtime from './runtime.js'
 import { ACTION } from './constants.js'
 import { checksum as fileChecksum, checksumOf, junkIgnore } from './utils.js'
-import { reportGated } from './report.js'
+import { reportGated, reportChanged } from './report.js'
 import { findById, findEntities, checksumsByCollection } from './catalog.js'
 import { useDatabase } from './database/index.js'
 
@@ -456,6 +456,10 @@ export function useSource(core, options) {
             reportGated()
             return
         }
+        // Past the gate means the bytes are new or different — the complement
+        // of reportGated, so between them every file looked at is accounted
+        // for and "why did this build do anything" has an answer.
+        reportChanged(id)
 
         const base = {
             id,