mikser-io 9.101.0 → 10.0.0

package/app.js

@@ -74,8 +74,7 @@ function locate(argv) {
             // rebuilt whatever the gates let through, which on a settled tree
             // is nothing, and a caller asking for a full re-render got a no-op
             // reported as success.
-            force: has('--force', '-f'),
-            renderPresets: has('--render-presets') ? (value('--render-presets') ?? true) : undefined }
+            force: has('--force', '-f') }
 
     return {
         longRunning,

package/index.js

@@ -6,6 +6,10 @@ export * from './src/roles.js'
 export * from './src/inventory.js'
 export * from './src/report.js'
 export * from './src/cli.js'
+// What one plugin offers another. A plugin publishes an API under a name
+// (provideService) or adds to an extension point (contribute); consumers ask
+// core, never a sibling. Replaces reaching into runtime.options.<plugin>.
+export * from './src/services.js'
 // The diagnostics behind --explain. Exported so a transport — the MCP tool
 // surface, the api plugin's routes — can serve the same structured report the
 // CLI formats, rather than each one reimplementing the question.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.101.0",
+  "version": "10.0.0",
   "files": [
     "app.js",
     "index.js",

package/src/cli.js

@@ -40,12 +40,25 @@ const declared = new Map()
 //
 //   cliOption('--lighthouse', 'audit the built pages with Lighthouse, and exit 0')
 //
-// Reads back from `runtime.options` under commander's usual camel-cased name.
+// Reads back from `runtime.options` under commander's usual camel-cased name —
+// but NOT at construction time. Declaring happens during the load phase and
+// the table is not parsed until after it, so an option read while the plugin
+// is being built is always undefined. Read it in a hook: onLoaded and later
+// all run after stage two. documents() read its folder at construction first,
+// and `--documents content` silently did nothing.
 export function cliOption(flags, description, defaultValue) {
+    // No CLI at all — a plugin constructed by a test harness, or embedded
+    // programmatically through setup({ ... }) rather than run from a terminal.
+    // There is nothing to register the option on and nothing about that is a
+    // mistake, so it returns quietly. Throwing here made every plugin that
+    // declares an option unusable in its own unit tests, which is how this was
+    // found.
+    //
+    // Declaring LATE is still an error — see below — because that one really
+    // is a mistake: the option would never be parsed and the flag would look
+    // ignored.
     const commander = runtime.engine?.commander
-    if (!commander) {
-        throw new Error('cliOption: no commander yet — call it while the plugin is being constructed')
-    }
+    if (!commander) return undefined
     if (runtime.engine.cliSealed) {
         throw new Error(
             `cliOption(${JSON.stringify(flags)}): the option table was already parsed. `
@@ -97,7 +110,28 @@ export function completeCliParse() {
     }
 
     commander.parse(process.argv)
-    Object.assign(runtime.options, commander.opts())
+
+    // ONLY the options a plugin declared.
+    //
+    // Assigning the whole opts() blob put core's own options back to their
+    // parsed values — and by this point the engine has already NORMALISED
+    // several of them. `--working-folder` defaults to './' and onInitialize
+    // resolves it to an absolute path; re-assigning made it './' again, after
+    // the load phase, so every plugin that resolves a folder in onLoaded got a
+    // relative one. `path.join('./', 'schemas')` is `schemas`, which reaches
+    // import() as a BARE SPECIFIER — so schemas, presets and layout sidecars
+    // all failed with "Cannot find package 'schemas'" on a clean build that
+    // was otherwise green.
+    //
+    // Stage two exists to pick up what stage one could not know about. It has
+    // no business restating what stage one already produced and the engine has
+    // since corrected.
+    const parsed = commander.opts()
+    for (const option of commander.options) {
+        if (!declared.has(option.flags)) continue
+        const name = option.attributeName()
+        if (parsed[name] !== undefined) runtime.options[name] = parsed[name]
+    }
 }
 
 // The plugin-declared options carried by a client's argv.

package/src/engine.js

@@ -32,7 +32,7 @@ import { queryContext } from './database/query-context.js'
 // Build a structuredClone-safe copy of runtime.options for WORKER
 // dispatch. Plugin surfaces live under `runtime.options.<plugin>` per
 // the engine's namespacing convention and routinely hold functions
-// (e.g. `runtime.options.layouts.inspect`, `runtime.options.preview.get`)
+// (e.g. the `layouts` service's inspect(), the `preview` service's get())
 // — those don't cross thread boundaries via Piscina's structured clone.
 //
 // Per-key probe: anything that survives `structuredClone(value)` passes
@@ -539,7 +539,6 @@ export async function setup(options) {
             .option('-c --config <file>', 'set mikser mikser.config.js location', './mikser.config.js')
             .option('-m --mode <mode>', 'set mikser runtime mode', 'development')
             .option('-r --clear', 'clear current state before execution', false)
-            .option('--render-presets [name]', 're-render preset derivatives whose sources and revisions are unchanged; with a name, only that preset')
             .option('-o --output-folder <folder>', 'set mikser output folder relative to working folder', 'out')
             .option('-w --watch', 'watch entities for changes', false)
             .option('-f --force', 'rebuild everything; disable incremental dispatch', false)
@@ -600,7 +599,10 @@ Which check answers which question:
   Are the derivatives current?
       --render-presets [n]  re-derives every preset, or one by name, without
                             touching anything else. For a preset edited without
-                            bumping its revision.
+                            bumping its revision. Declared by the assets
+                            plugin, so it exists only in a project that loads
+                            one — and a config without assets() refuses it as
+                            unknown rather than accepting it and doing nothing.
 
   Start over.
       --clear               removes the output folder and reopens the cache.
@@ -625,11 +627,6 @@ Which check answers which question:
                             instance is ALWAYS in watch mode, so watch alone
                             answers the wrong question.
 
-  Is the page fast, and can it be read?
-      --lighthouse          from mikser-io-lighthouse, if installed. A plugin
-                            declares its own options now, and they appear here
-                            beside core's — see cliOption().
-
   What did this build do, and cost?
       --json                the whole report as one document on stdout, with
                             every warning carrying a stable code, and per-phase
@@ -845,8 +842,18 @@ The full version, with what each code means: docs/diagnostics.md`)
         // The same three commands the instance answers over the socket —
         // one implementation, so a forwarded --audit-output cannot disagree with a
         // local one about what it checked.
-        const code = await runReportOnly()
-        if (code !== null) process.exit(code)
+        //
+        // --tools and --tool are NOT among them: they are dispatched at `import`
+        // instead, because the tool registry is not complete until every
+        // plugin's onLoaded has run and this hook runs ahead of all of them.
+        // The import dispatch existed already and was documented as
+        // load-bearing, but this call reached the same code first and exited,
+        // so it never ran — and every tool a plugin registers was missing from
+        // the CLI while the listing looked healthy, just short.
+        if (!runtime.options.tools && !runtime.options.tool) {
+            const code = await runReportOnly()
+            if (code !== null) process.exit(code)
+        }
     })
 
     onRender(async (signal) => {
@@ -1054,7 +1061,7 @@ The full version, with what each code means: docs/diagnostics.md`)
                                 mc.port2.unref()
                                 renderOptions.port = mc.port1
                                 // Strip plugin-surface functions
-                                // (runtime.options.layouts.inspect, etc.) so
+                                // (the layouts service's inspect, etc.) so
                                 // Piscina's structured clone doesn't choke on
                                 // them. Engine-side primitives pass through;
                                 // plugin surfaces are reachable via the
@@ -1501,30 +1508,17 @@ The full version, with what each code means: docs/diagnostics.md`)
         if (failed) logger.error('Mikser completed with %d render error%s', failed, failed === 1 ? '' : 's')
         else logger.notice('Mikser completed')
 
-        // Is everything the templates linked to actually there?
+        // The `render-presets-unhandled` guard is gone, and so is the state it
+        // read.
         //
-        // The URL helpers build paths; they do not resolve them. So a preset
-        // that never ran, a library that was not copied, or a template naming
-        // an extension the preset stopped producing all yield a well-formed
-        // link to a file that does not exist — and the only symptom is a
-        // missing image on the deployed site, found by a person.
-        //
-        // Checked at the end of the cycle because that is the first moment the
-        // answer is stable: derivatives are produced during the cycle, so
-        // asking any earlier would report files that were about to appear.
-        // --render-presets with nothing to consume it.
-        //
-        // The flag is implemented by the assets plugin, so without that plugin
-        // it reaches nobody: the build runs normally, nothing is re-derived,
-        // and the operator is left to notice. Checked here rather than at
-        // onLoaded because the engine's own onLoaded is registered first and
-        // runs before any plugin has set itself up.
-        if (runtime.options.renderPresets && !runtime.state?.assets?.renderPresetsHandled) {
-            useLogger().error({ code: 'render-presets-unhandled' },
-                '--render-presets was passed, but no assets plugin is loaded to act on it. '
-                + 'Nothing was re-derived. Add assets() to the plugins array, or drop the flag.')
-            process.exitCode = 1
-        }
+        // It existed because core declared `--render-presets` while the assets
+        // plugin implemented it, so the flag could be passed at a build that
+        // had no plugin to act on it — accepted, ignored, and reported after
+        // the fact. The plugin declares the option itself now, so a config
+        // without assets() does not have the flag at all and a misspelling is
+        // refused by name before anything is built. There is nothing left to
+        // warn about after the event.
+
 
         const brokenTargets = await reportBrokenReferences(useLogger())
         await reportMissingAssets(useLogger(), brokenTargets)

package/src/instance.js

@@ -73,6 +73,11 @@ export function socketPath(workingFolder) {
 //
 //   → { type: 'build',  config, clear, renderPresets }
 //   → { type: 'report', config, tool, tools, toolArgs, explain, auditOutput, fingerprint, json }
+//
+// A PLUGIN's options are not listed here and are not hand-carried: they travel
+// on `argv` and are applied by withRequestOutput against the instance's own
+// option table. --render-presets used to be named explicitly, which is what a
+// core-declared plugin flag costs — one more thing to remember in two files.
 //   ← { type: 'log', chunk }        (zero or more, in order)
 //   ← { type: 'done', code }
 //   ← { type: 'refused', reason, detail }
@@ -460,8 +465,6 @@ async function serveBuild(socket, request, logger) {
         // silent no-op, which is the failure this surface exists to remove —
         // and restoring it after keeps the watcher from forcing every later
         // rebuild.
-        const priorRenderPresets = runtime.options.renderPresets
-        if (request.renderPresets !== undefined) runtime.options.renderPresets = request.renderPresets
         // Applied for THIS cycle only, like renderPresets. An instance left in
         // force mode would re-render the whole site on every later save.
         const priorForce = runtime.options.force
@@ -486,7 +489,6 @@ async function serveBuild(socket, request, logger) {
                 emitReport()
             })
         } finally {
-            runtime.options.renderPresets = priorRenderPresets
             runtime.options.force = priorForce
         }
 

package/src/plugins/assets.js

@@ -1,5 +1,6 @@
 import { reportEvaluated } from '../report.js'
 import { countEntities } from '../catalog.js'
+import { cliOption } from '../cli.js'
 import path from 'node:path'
 import { mkdir, writeFile, unlink, rm, readFile, symlink, } from 'fs/promises'
 import { existsSync } from 'node:fs'
@@ -86,6 +87,33 @@ export function assets(options = {}) {
         changeExtension,
         constants: { ACTION, OPERATION },
     }) => {
+    // Declared HERE, not in core.
+    //
+    // Everything this flag does happens in this plugin, and core carried it
+    // only because a plugin could not declare an option until 9.100.0. The
+    // cost of that was a flag a build could accept with nothing loaded to act
+    // on it: passed, ignored, and reported afterwards by a `render-presets-
+    // unhandled` guard in the engine. Declared here, a config without assets()
+    // simply does not have the option, so the mistake is refused by name
+    // before anything is built rather than explained after.
+    // The folders this plugin owns, on the command line.
+    //
+    // They were config-only, because a plugin could not declare an option
+    // before 9.100.0 — so overriding one for a single run meant editing the
+    // config, which is the file whose checksum decides whether the whole
+    // catalog is still valid. A flag is the difference between "try this
+    // once" and "invalidate everything".
+    //
+    // CLI beats config beats default, which is the order every other option
+    // here already follows.
+    cliOption('--assets <folder>',
+        'folder for derived assets, relative to the working folder (default: assets)')
+    cliOption('--presets <folder>',
+        'folder holding the preset modules, relative to the working folder (default: presets)')
+    cliOption('--render-presets [name]',
+        're-render preset derivatives whose sources and revisions are unchanged; '
+        + 'with a name, only that preset')
+
     const collection = 'presets'
     const type = 'preset'
     const checksumMap = new Set()
@@ -425,12 +453,16 @@ export function assets(options = {}) {
         runtime.engine ??= {}
         runtime.engine.assets = { explainMissing }
 
-        runtime.options.presets = options.presetsFolder || collection
+        // `??`, not `||`: an option commander did not see is undefined, and
+        // falling through to the config is the point. `||` would also fall
+        // through for an intentional empty string, which is a different
+        // answer than "not given".
+        runtime.options.presets = runtime.options.presets ?? options.presetsFolder ?? collection
         runtime.options.presetsFolder = path.join(runtime.options.workingFolder, runtime.options.presets)
         logger.debug('Presets folder: %s', runtime.options.presetsFolder)
         await mkdir(runtime.options.presetsFolder, { recursive: true })
 
-        runtime.options.assets = options.assetsFolder || 'assets'
+        runtime.options.assets = runtime.options.assets ?? options.assetsFolder ?? 'assets'
         runtime.options.assetsFolder = path.join(runtime.options.workingFolder, runtime.options.assets)
         logger.debug('Assets folder: %s', runtime.options.assetsFolder)
 
@@ -641,7 +673,6 @@ export function assets(options = {}) {
             // end of the cycle: a flag that reaches no plugin has to say so,
             // rather than building normally and leaving the operator to
             // notice nothing was re-derived.
-            runtime.state.assets.renderPresetsHandled = true
 
             const known = Object.keys(runtime.state.assets.presets)
             const names = wanted === true ? known : [wanted]

package/src/plugins/data.js

@@ -1,4 +1,5 @@
 import path from 'path'
+import { cliOption } from '../cli.js'
 import { mkdir, writeFile, unlink, open } from 'fs/promises'
 import _ from 'lodash'
 import sift from 'sift'
@@ -17,9 +18,23 @@ export function data(options = {}) {
         onBeforeRender,
         constants: { OPERATION },
     }) => {
+    // The folder this plugin owns, on the command line.
+    //
+    // Config-only until 9.100.0, because a plugin could not declare an option
+    // — so overriding it for one run meant editing the config, which is the
+    // file whose checksum decides whether the catalog is still valid. A flag
+    // is the difference between trying something once and invalidating
+    // everything.
+    //
+    // CLI beats config beats default. `??` rather than `||` below: an option
+    // commander did not see is undefined, and an intentional empty string is a
+    // different answer than "not given".
+    cliOption('--data <folder>',
+        'folder for emitted data files, relative to the OUTPUT folder (default: data)')
+
     onLoaded(async () => {
         const logger = useLogger()
-        runtime.options.data = options.dataFolder || 'data'
+        runtime.options.data = runtime.options.data ?? options.dataFolder ?? 'data'
         runtime.options.dataFolder = path.join(runtime.options.outputFolder, runtime.options.data)
 
         logger.debug('Data folder: %s', runtime.options.dataFolder)

package/src/plugins/documents.js

@@ -1,4 +1,5 @@
 import { useSource } from '../source.js'
+import { cliOption } from '../cli.js'
 
 // documents — the canonical content source plugin.
 //
@@ -13,6 +14,13 @@ export function documents(options = {}) {
         const collection = 'documents'
         const type = 'document'
 
+        // The folder this plugin owns, on the command line. Config-only until
+        // 9.100.0, because a plugin could not declare an option — and editing
+        // the config to try another folder once invalidates the catalog,
+        // whose checksum covers it. CLI beats config beats default.
+        cliOption('--documents <folder>',
+            'folder of source documents, relative to the working folder (default: documents)')
+
         useSource(core, {
             collection,
             type,

package/src/plugins/files.js

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { cliOption } from '../cli.js'
 import { mkdir, symlink, unlink, lstat, realpath } from 'fs/promises'
 import { globby } from 'globby'
 import pMap from 'p-map'
@@ -23,6 +24,20 @@ export function files(options = {}) {
         constants: { ACTION },
     }) => {
         const collection = 'files'
+        // The folder this plugin owns, on the command line.
+        //
+        // Config-only until 9.100.0, because a plugin could not declare an option
+        // — so overriding it for one run meant editing the config, which is the
+        // file whose checksum decides whether the catalog is still valid. A flag
+        // is the difference between trying something once and invalidating
+        // everything.
+        //
+        // CLI beats config beats default. `??` rather than `||` below: an option
+        // commander did not see is undefined, and an intentional empty string is a
+        // different answer than "not given".
+        cliOption('--files <folder>',
+            'folder of static files copied into the output by symlink, relative to the working folder (default: files)')
+
         const type = 'file'
 
         async function ensureLink(relativePath) {
@@ -156,7 +171,7 @@ export function files(options = {}) {
 
         onLoaded(async () => {
             const logger = useLogger()
-            runtime.options.files = options.filesFolder || collection
+            runtime.options.files = runtime.options.files ?? options.filesFolder ?? collection
             runtime.options.filesFolder = path.join(runtime.options.workingFolder, runtime.options.files)
 
             logger.debug('Files folder: %s', runtime.options.filesFolder)

package/src/plugins/preview.js

@@ -6,7 +6,7 @@
 //   1. An in-memory cache (Map<filename, { bytes, mime, expiresAt,
 //      size, deps }>) with LRU eviction past a configurable byte cap.
 //   2. An Express GET /preview/:filename route that serves cache entries.
-//   3. Exposes the cache surface at runtime.options.preview = { store,
+//   3. Offers the cache surface as the `preview` service = { store,
 //      get, stats, config } so other plugins (mikser-io-mcp's
 //      mikser_preview_render tool, library-mode callers) can stash bytes
 //      and retrieve them by URL without going through MCP.
@@ -29,6 +29,7 @@
 // isn't mounted.
 
 import sift from 'sift'
+import { provideService } from '../services.js'
 
 export function preview(options = {}) {
     return ({ runtime, onLoaded, onPersist, useJournal, useLogger, registerRoute, constants: { OPERATION } }) => {
@@ -98,13 +99,14 @@ export function preview(options = {}) {
         }
     }
 
-    // Expose the cache surface at runtime.options.preview so other
-    // plugins / library callers can use it without going through MCP.
-    // `config` is part of the surface too — mikser-io-mcp's
-    // mikser_preview_render reads it to derive URL paths + TTL clamps.
-    // Done at factory-eval time (before any onLoaded fires) so a
-    // later plugin's onLoad / onLoaded can already see it.
-    runtime.options.preview = { store, get, stats, config }
+    // Offer the cache surface as a service, so a plugin that wants it asks
+    // core rather than reaching into runtime.options.preview. `config` is
+    // part of the surface too — mikser-io-mcp's mikser_preview_render reads
+    // it to derive URL paths + TTL clamps.
+    //
+    // Provided at factory-eval time, before any hook runs, so a consumer's
+    // onLoad / onLoaded can already see it whatever the plugin order.
+    provideService('preview', { store, get, stats, config }, { plugin: 'mikser-io' })
 
     // Per-cycle invalidation. For every preview entry that has `deps`,
     // walk this cycle's catalog mutations and evict the entry if any
@@ -144,7 +146,7 @@ export function preview(options = {}) {
 
     // HTTP route: served regardless of whether MCP is on, so previews
     // are also reachable from library-mode callers that stored bytes
-    // via runtime.options.preview.store() directly.
+    // via the preview service's store() directly.
     onLoaded(async () => {
         const logger = useLogger()
         const app = runtime.options.app

package/src/plugins/resources.js

@@ -1,4 +1,5 @@
 import { mkdir, symlink, rename, unlink } from 'node:fs/promises'
+import { cliOption } from '../cli.js'
 import { createWriteStream } from 'node:fs'
 import lodash from 'lodash'
 import deepdash from 'deepdash'
@@ -27,6 +28,20 @@ export function resources(options = {}) {
         updateProgress,
         constants: { OPERATION },
     }) => {
+    // The folder this plugin owns, on the command line.
+    //
+    // Config-only until 9.100.0, because a plugin could not declare an option
+    // — so overriding it for one run meant editing the config, which is the
+    // file whose checksum decides whether the catalog is still valid. A flag
+    // is the difference between trying something once and invalidating
+    // everything.
+    //
+    // CLI beats config beats default. `??` rather than `||` below: an option
+    // commander did not see is undefined, and an intentional empty string is a
+    // different answer than "not given".
+    cliOption('--resources <folder>',
+        'folder of library resources linked into the output, relative to the working folder (default: resources)')
+
     const collection = 'resources'
     const type = 'resource'
 
@@ -46,7 +61,7 @@ export function resources(options = {}) {
                 : resourcesName,
         }
 
-        runtime.options.resources = options.resourcesFolder || collection
+        runtime.options.resources = runtime.options.resources ?? options.resourcesFolder ?? collection
         runtime.options.resourcesFolder = path.join(runtime.options.workingFolder, runtime.options.resources)
         logger.debug('Resources folder: %s', runtime.options.resourcesFolder)
 

package/src/plugins.js

@@ -1,5 +1,6 @@
 import { useLogger } from './engine.js'
 import { onLoad } from './lifecycle.js'
+import { resetServices } from './services.js'
 import runtime from './runtime.js'
 
 import * as core from '../index.js'
@@ -23,6 +24,13 @@ import * as core from '../index.js'
 onLoad(() => {
     const logger = useLogger()
 
+    // The service and extension-point registries are module state, which
+    // outlives one load phase — a watcher re-reads its config in the same
+    // process. Clearing here, before any factory runs, means a reload
+    // rebuilds them from scratch instead of a provider colliding with the
+    // copy of itself it registered last time.
+    resetServices()
+
     runtime.options.plugins = (runtime.options.plugins ?? [])
         .concat(runtime.config.plugins ?? [])
         .filter(Boolean)

package/src/services.js

@@ -0,0 +1,88 @@
+// What one plugin offers another, without either importing the other.
+//
+// Plugins reached into each other through `runtime.options`:
+//
+//       runtime.options.layouts.inspect      read by core
+//       runtime.options.schemas.lookup       read by forms, layouts, ocr
+//       runtime.options.preview.get          read by core, layouts, mcp
+//       runtime.options.roles                read by mcp
+//
+// It worked, and it was wrong in a specific way: mikser-io-mcp and
+// mikser-io-layouts were coupled through a shared mutable object neither of
+// them owns. Nothing declared the relationship, so nothing could check it —
+// a consumer's `if (!runtime.options.layouts) return` reads as a null check
+// but is really an is-that-plugin-installed check wearing a disguise.
+//
+// It also cost the two best names. Commander derives an option's property
+// from its long flag, so `--layouts <folder>` writes runtime.options.layouts
+// — on top of the inspect API, after the load phase, with the failure
+// surfacing three plugins away.
+//
+// This covers ONE direction: one plugin provides, others consume. The other
+// direction — many plugins adding to a surface one plugin serves — already
+// has a home for each surface it applies to: tools.js, routes.js, roles.js
+// and cli.js. A generic contribution registry would be a fifth way to do
+// what those four already do.
+//
+// So: core holds the registry, and neither side names the other.
+
+const services = new Map()        // name -> { api, plugin }
+
+// Publish an API under a name other plugins can ask for.
+//
+//   provideService('layouts', { inspect }, { plugin: 'mikser-io-layouts' })
+//
+// Call at factory-eval time, before any hook runs, so that a consumer's
+// onLoaded can already see it. Same rule as cliOption: declare during
+// construction, read during a hook.
+export function provideService(name, api, { plugin } = {}) {
+    if (!name || !api) return
+    const existing = services.get(name)
+    if (existing) {
+        // Two providers for one name is a configuration mistake, not a
+        // precedence question. Last-write-wins would hand consumers whichever
+        // plugin happened to be constructed later — the exact order
+        // dependence this registry exists to remove. Thrown rather than
+        // logged: this runs at factory-eval time, where plugins.js already
+        // catches, names the plugin and carries on with the rest.
+        throw new Error(
+            `Service "${name}" is already provided by ${existing.plugin ?? 'another plugin'}` +
+            `${plugin ? `; ${plugin} tried to provide it too` : ''}. Only one plugin may provide a service.`)
+    }
+    services.set(name, { api, plugin })
+}
+
+// Ask for a service. Returns undefined when nothing provides it, so a
+// consumer degrades on purpose:
+//
+//   const layouts = useService('layouts')
+//   if (!layouts) return        // layouts plugin isn't installed
+//
+// This replaces `if (!runtime.options.mcp) return`, which read as a null
+// check but was really an is-that-plugin-loaded check wearing a disguise.
+export function useService(name) {
+    return services.get(name)?.api
+}
+
+// Ask for a service the caller cannot work without. Throws naming the
+// package that provides it, because "cannot read properties of undefined"
+// does not tell anyone which npm install they are missing.
+export function requireService(name, { from } = {}) {
+    const found = services.get(name)
+    if (found) return found.api
+    throw new Error(
+        `No plugin provides the "${name}" service` +
+        (from ? `. Install ${from} and add it to the plugins array.` : '.'))
+}
+
+// Drop everything. The registries are module state, which outlives a single
+// run inside one process — tests, and the watcher's repeated config reloads.
+export function resetServices() {
+    services.clear()
+}
+
+// What is registered right now. For --explain and the MCP inventory tool:
+// "which plugin provides what" is a question people ask.
+export function serviceInventory() {
+    return [...services].map(([name, { plugin }]) => ({ name, plugin }))
+}

package/src/source.js

@@ -337,9 +337,19 @@ export function useSource(core, options) {
         // have already passed. We do folder resolution here — by which
         // point engine has set workingFolder and journal + catalog
         // have initialized.
-        absFolder = path.isAbsolute(folder)
-            ? folder
-            : path.join(runtime.options.workingFolder, folder)
+        // A `--<collection> <folder>` flag, if the plugin declared one, wins
+        // over the configured folder.
+        //
+        // Resolved HERE rather than where useSource was called, and that is
+        // the whole point: plugin factories run during the load phase, and the
+        // CLI table is not complete until after it — so an option read at
+        // construction is always undefined. documents() read it there first
+        // and `--documents content` silently did nothing, which is the shape
+        // of bug this option mechanism exists to prevent rather than create.
+        const configured = runtime.options[collection] ?? folder
+        absFolder = path.isAbsolute(configured)
+            ? configured
+            : path.join(runtime.options.workingFolder, configured)
         runtime.options[`${collection}Folder`] = absFolder
         // The authoritative set of folders whose files become entities.
         //

package/src/tools.js

@@ -7,13 +7,17 @@
 // the first. Closing that by adding a CLI flag per tool would drift the moment
 // anyone added a tool.
 //
-// One direction, today. The mcp plugin mirrors its registrations into here, so
-// every tool it registers is reachable from the CLI. The reverse is NOT true: a
-// tool registered directly against this registry does not appear in an MCP
-// session, because the substrate binds sessions from its own list and MCP wants
-// a zod shape for `inputSchema` while the engine is deliberately zod-free.
-// Registering through `runtime.options.mcp` therefore remains the way to reach
-// both surfaces, and that is what every tool does now.
+// Both directions. The mcp plugin mirrors its own registrations into here, and
+// binds every tool registered here into each session — prefixing on the way
+// out, since `mikser_` belongs to MCP's flat namespace and not to the engine.
+// So a plugin registers once, against this registry, and reaches both surfaces
+// without depending on the mcp plugin being installed, or on where it sits in
+// the plugins array.
+//
+// `inputSchema` is stored opaquely, which is what makes that possible: a
+// plugin may describe its parameters in the neutral vocabulary below or hand
+// over a zod shape, and the engine passes either through untouched rather than
+// taking a dependency on zod to hold it.
 //
 // So the REGISTRY is substrate and the transports are consumers. ADR-0006's
 // five tests, which MCP itself failed on release cadence:
@@ -50,6 +54,13 @@ export function registerTool(name, definition = {}, handler) {
         runtime.engine?.logger?.debug('Tool %s re-registered, replacing the previous handler', name)
     }
     tools.set(name, {
+        // The whole definition, not the three fields core happens to read.
+        // A transport needs more than core does — `mutates: true` is how a
+        // tool says it changes something, and MCP wraps those differently.
+        // Dropping unknown keys here meant a plugin could only reach that
+        // behaviour by registering with the mcp plugin directly, which is
+        // exactly the coupling this registry exists to remove.
+        ...definition,
         name,
         description: definition.description ?? '',
         inputSchema: definition.inputSchema ?? {},

package/testing/harness.js

@@ -7,6 +7,7 @@
 
 import _ from 'lodash'
 import realRuntime from '../src/runtime.js'
+import { resetServices } from '../src/services.js'
 import { matchEntity, normalize, changeExtension, getFormatInfo, checksum, AbortError } from '../src/utils.js'
 
 const OPERATION = {
@@ -31,6 +32,11 @@ export function createHarness({
     entities = [],
     journal = [],
 } = {}) {
+    // A fresh harness is a fresh world. The service registry is module state,
+    // so without this the previous test's provider is still registered and
+    // constructing the plugin again is (correctly) an error — every package
+    // building a plugin per test would otherwise have to remember to clear it.
+    resetServices()
     const hookNames = [
         'load', 'loaded', 'import', 'imported',
         'process', 'processed', 'persist', 'persisted',