@webjsdev/mcp 0.1.13 → 0.1.14

package/README.md

@@ -34,9 +34,11 @@ subcommand) delegates to this same server, so both routes run identical code.
   no verdict at all; identical to `webjs elision --json`),
   `check` (the structured `webjs check` violations). Each projects an existing
   `@webjsdev/server` data function and mutates nothing.
-- **Knowledge layer**: an `init` mental-model primer, a `docs` retrieval tool,
-  MCP `resources` (the skill references + `SKILL.md` + `AGENTS.md` as `webjs-docs://*`),
-  and `prompts` (the recipes as guided workflows).
+- **Knowledge layer**: an `init` mental-model primer (which also names the docs
+  corpus it is serving, and warns when this server's copy looks stale against
+  the app's), a `docs` retrieval tool, MCP `resources` (the skill references +
+  `SKILL.md` + `AGENTS.md` as `webjs-docs://*`), and `prompts` (the recipes as
+  guided workflows).
 - **`source` tool**: reads the framework's own no-build source from
   `node_modules/@webjsdev/*/src` (read-only, traversal-guarded).
 - **`ui` tool**: the `@webjsdev/ui` kit inventory (no args) or one component's
@@ -44,10 +46,65 @@ subcommand) delegates to this same server, so both routes run identical code.
   `name`). Kit-scoped (not `appDir`-scoped); shares one projector with
   `webjsui view`.
 
-The docs corpus is bundled into the package at `prepack`, so `npx @webjsdev/mcp`
-is self-contained; in the monorepo it falls back to the live repo-root docs.
+## Which docs you get
 
-That bundle is a snapshot frozen at publish time, so a published tarball keeps
+The corpus is resolved in three rungs, highest first:
+
+1. `<appDir>/node_modules/@webjsdev/mcp/resources`, the app's own installed copy.
+2. `<pkg>/resources`, this server's bundled snapshot, so `npx @webjsdev/mcp` is
+   self-contained.
+3. Whatever the server resolves locally, which is the repo-root skill on the
+   monorepo dev path. This rung is an unconditional fallback rather than a
+   checkout probe, so a published install whose `resources/` bundle is missing
+   lands here too, with an empty corpus. That is why neither the corpus line nor
+   the warning asserts a checkout.
+
+The app's copy wins because it is version-matched to the framework you are
+editing, and so is the only corpus that can be correct about that app. This
+matters most for a GLOBAL install (`npm i -g` / `bun add -g`), which otherwise
+keeps serving the docs it was published with forever, contradicting the copy
+sitting in your own `node_modules`. That is a real incident, not a hypothetical:
+a server published one day before the client router stopped needing an explicit
+`import '@webjsdev/core/client-router'` kept teaching that import for months, and
+an agent following it wrote dead imports into three layouts, each of which the
+elision analyser then correctly refused to strip.
+
+`appDir` is a per-call argument, so the corpus follows it. `resources/list` and
+`resources/read` carry no `appDir` in the MCP protocol and resolve from the
+server's working directory, which is what a `tools/call` with no `appDir`
+defaults to, so in the ordinary case every surface reads one corpus.
+
+`init` names the corpus it served on its first line, and prepends a warning when
+the app's installed `@webjsdev/mcp` is strictly newer than the running server's:
+
+```
+Warning: this MCP server is @webjsdev/mcp@0.1.4, but this app has @webjsdev/mcp@0.1.12,
+so the server may be stale. The docs below come from this app's own copy, so they
+match it; update the server so its TOOLS match too. Update whichever copy runs this
+server: a global install (npm i -g @webjsdev/mcp@latest, or bun add -g @webjsdev/mcp),
+the package cache behind npx @webjsdev/mcp, @webjsdev/cli when the server is started
+as webjs mcp, or the checkout it runs from.
+Docs corpus: @webjsdev/mcp@0.1.12, copied from webjsdev/webjs e5806e2 on 2026-08-08.
+```
+
+It warns rather than refusing to answer, because a knowledge tool that declines
+sends the agent back to its training data, which is what the caveat exists to
+correct. Equal versions, an older app, and an unreadable app manifest are all
+silent.
+
+Two details the wording is deliberate about. It does not name a global install as
+the thing to fix, because nothing observes how the server was started and the two
+shipped configurations are an `npx` invocation (whose staleness is a package
+cache) and `webjs mcp` (whose staleness is the CLI's own dependency). And it does
+not promise the docs below came from the app: the warning reads the app's
+`package.json` while the corpus rung probes that install's `resources/`, so a
+workspace-linked install can have a manifest to compare and no corpus to serve.
+In that case the corpus falls through to the server's snapshot and the warning
+says so, rather than contradicting the corpus line printed under it.
+
+## The build stamp
+
+The bundle is a snapshot frozen at publish time, so a published tarball keeps
 serving the docs as they read on the day it was cut. `prepack` stamps it with
 `resources/corpus.json` so the snapshot can say which docs it holds:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "description": "The Model Context Protocol server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Gives AI coding agents live app introspection over routes, actions, components, and convention checks, plus a knowledge layer of docs, recipes, and framework source.",
   "bin": {

package/resources/AGENTS.md

@@ -33,7 +33,7 @@ itself): commands, repo-health git config, changelog flow, dev error overlay.
 
 ## AI-driven development: guardrails for all agents
 
-**WebJs is AI-first. These rules apply to ALL agents (Claude, Cursor, Copilot, Antigravity, Gemini, opencode) through a SINGLE cross-agent source the scaffold ships**: `AGENTS.md` (the open standard Cursor / opencode / Antigravity / the Copilot coding agent read natively) plus the skill at `.agents/skills/webjs/` and the workflow rules at `.agents/rules/workflow.md`. Tools that do not read `AGENTS.md` natively get a THIN bridge pointing at it (`CLAUDE.md` for Claude Code, `GEMINI.md` for Gemini CLI, `.github/copilot-instructions.md` for Copilot in VS Code), never a duplicated rule set. Claude Code additionally ships the protective enforcement hooks (`.claude/`, `.hooks/pre-commit`).
+**WebJs is AI-first. These rules apply to ALL agents (Claude, Cursor, Copilot, Antigravity, Gemini, opencode) through a SINGLE cross-agent source the scaffold ships**: `AGENTS.md` (the open standard Cursor / opencode / Antigravity / the Copilot coding agent read natively) plus the skill at `.agents/skills/webjs/` and the workflow rules at `.agents/rules/workflow.md`. Tools that do not read `AGENTS.md` natively get a THIN bridge pointing at it (`CLAUDE.md` for Claude Code), never a duplicated rule set. The scaffold shipped `GEMINI.md` and `.github/copilot-instructions.md` as further bridges until #1368 removed them, so `CLAUDE.md` is the only one today. Claude Code additionally ships the protective enforcement hooks (`.claude/`, `.hooks/pre-commit`).
 
 ### Before starting ANY work: verify and sync the branch
 
@@ -99,8 +99,8 @@ Every code change MUST include, automatically:
 
 1. **Tests, every applicable layer (not just unit).** Ship the tests that prove the change across EVERY layer it touches: **unit** (`packages/*/test/**`, `test/**`, including the counterfactual that fails when reverted), **browser** (`*/test/**/browser/*` via `npm run test:browser`, for hydration / DOM / slots / client router / custom-element upgrade), **e2e** (`test/e2e/*.test.mjs` via `WEBJS_E2E=1`, including network probes / navigation / streaming), and **smoke** (`test/examples/*/smoke/*`). A unit test is NECESSARY BUT NOT SUFFICIENT for any client-router / component / browser-facing change (the headline behaviour is a browser/e2e assertion). **Bun parity is part of the task, not an afterthought:** WebJs runs on Node 24+ AND Bun (#508), so a change to a runtime-sensitive surface (the serializer, the node:http vs `Bun.serve` listener + request path, SSR / action / CSRF dispatch, streams, `node:crypto`, the TS stripper, auth / session / cors) MUST be proven on Bun (`node scripts/run-bun-tests.js` + the touched `test/bun/*.mjs` under `bun`) AND ship an added/updated `test/bun/<feature>.mjs` cross-runtime assertion. `npm test` does NOT run browser, e2e, or Bun; run them yourself and report the result. Never report work done with failing or missing tests. See `references/testing.md`. Enforced by `.claude/hooks/require-tests-with-src.sh` (the scaffold variant WARNS unless `WEBJS_TEST_GATE=block`) and `.claude/hooks/require-bun-parity-with-runtime-src.sh` (BLOCKS a commit that stages runtime-sensitive source with no `test/bun/**` test; escape hatch `WEBJS_BUN_VERIFIED=1`).
 2. **Documentation, part of the definition of done (not optional).** A task is NOT done until EVERY doc surface its change touches is in sync: `AGENTS.md` + the skill at `.agents/skills/webjs/` (SKILL.md + references/) for new API surface, `CONVENTIONS.md` (and per-package `AGENTS.md`) for new conventions, the docs site (`website/app/docs/<topic>`), the marketing `website/`, the scaffold templates (`packages/cli/templates/` per-agent rule files), and `README.md` for a headline capability. Updating `AGENTS.md` alone reproduces the #488 gap (docs site left stale). Invoke the `webjs-doc-sync` skill to sync every applicable surface. Enforced by `.claude/hooks/require-docs-with-src.sh`, which BLOCKS a commit that stages public `packages/*/src` source with no doc surface alongside it (a genuinely internal refactor / CI / release / perf change with no behaviour change bypasses with `WEBJS_NO_DOC_GATE=1`).
-3. **Scaffold + skill sync (when a feature changes what apps should do).** The scaffold `webjs create` emits is a gallery index home + a root layout + db wiring, a densely-commented feature gallery (`packages/cli/templates/gallery/**`, single-concept demos under `app/features/` plus the `app/examples/todo` app, shipped in every UI template) and the api backend-features showcase (`packages/cli/lib/api-gallery.js`), plus the one cross-agent skill at `packages/cli/templates/.agents/skills/webjs/` (SKILL.md + references). So when a WebJs feature is added or changed, ask: does the generator (`packages/cli/lib/{create,api-gallery}.js`), a gallery demo (`packages/cli/templates/gallery/`), or the agent skill (`.agents/skills/webjs/SKILL.md` + its `references/`) need to move so a freshly scaffolded app and the skill teach the new reality? Verify by generating an app and running `generate + boot + webjs check` (the generators emit strings, so an escaping bug only shows in a freshly generated app). See `framework-dev.md`.
-4. **Convention validation.** Run `webjs check` and fix violations. Run `webjs doctor` too when you touched an in-repo app (`examples/blog`, `website`): the required `conventions` CI job runs it over both, and it fails on a hard toolchain check or on whatever that app's `webjs.doctor.gate` marks `error` (today `UNMARKED_ASSET_LINKS` in `website` and `examples/blog`), so a clean `webjs check` alone is not enough to predict that job (#1257).
+3. **Scaffold + skill sync (when a feature changes what apps should do).** The scaffold `webjs create` emits is a gallery index home + a root layout + db wiring, a densely-commented feature gallery (`gallery/**`, single-concept demos under `app/features/` plus the `app/examples/todo` app, shipped in every UI template) and the api backend-features showcase (`packages/cli/lib/api-gallery.js`), plus the one cross-agent skill at `packages/cli/templates/.agents/skills/webjs/` (SKILL.md + references). So when a WebJs feature is added or changed, ask: does the generator (`packages/cli/lib/{create,api-gallery}.js`), a gallery demo (`gallery/`), or the agent skill (`.agents/skills/webjs/SKILL.md` + its `references/`) need to move so a freshly scaffolded app and the skill teach the new reality? Verify by generating an app and running `generate + boot + webjs check` (the generators emit strings, so an escaping bug only shows in a freshly generated app). See `framework-dev.md`.
+4. **Convention validation.** Run `webjs check` and fix violations. Run it from INSIDE an app, never from the repo root: the root is a workspace, not an app, so the command refuses there with exit 1 rather than reporting the cross-app collisions no single runtime ever sees (#1301). In this repo that means `( cd gallery && npx webjs check )`, `( cd examples/blog && npx webjs check )` and `( cd website && npx webjs check )`. Run `webjs doctor` too when you touched an in-repo app (`gallery`, `examples/blog`, `website`): the required `conventions` CI job runs it over all three, and it fails on a hard toolchain check or on whatever that app's `webjs.doctor.gate` marks `error` (today `UNMARKED_ASSET_LINKS` in `website` and `examples/blog`), so a clean `webjs check` alone is not enough to predict that job (#1257).
 
 ### Git workflow (mandatory)
 
@@ -159,7 +159,7 @@ Self-check: `page.ts` / `layout.ts` should NOT appear in the network tab or the
 
 ## Framework source: where to find it
 
-Plain JS with JSDoc lives in `node_modules/@webjsdev/` (`core/`, `server/`, `cli/`, `mcp/`, `intellisense/`, `ui/`); what you read is what runs. Starting points: SSR `@webjsdev/server/src/ssr.js`, client hydration `@webjsdev/core/src/render-client.js`, client router `@webjsdev/core/src/router-client.js`, convention rules `@webjsdev/server/src/check.js`. For UI debugging use the Playwright MCP server; for live introspection the scaffold wires the read-only `@webjsdev/mcp` server (`npx @webjsdev/mcp`, also reachable as `webjs mcp`): `list_routes`, `list_actions`, `list_components`, `list_elision` (what the browser never downloads, and why each shipped module ships), `check`, `ui` (the `@webjsdev/ui` kit inventory + a component's helpers / paste-ready example / a11y header), plus a knowledge layer (docs / recipes / framework source).
+Plain JS with JSDoc lives in `node_modules/@webjsdev/` (`core/`, `server/`, `cli/`, `mcp/`, `intellisense/`, `ui/`); what you read is what runs. Starting points: SSR `@webjsdev/server/src/ssr.js`, client hydration `@webjsdev/core/src/render-client.js`, client router `@webjsdev/core/src/router-client.js`, convention rules `@webjsdev/server/src/check.js`. For UI debugging use the Playwright MCP server; for live introspection the scaffold wires the read-only `@webjsdev/mcp` server (`npx @webjsdev/mcp`, also reachable as `webjs mcp`): `list_routes`, `list_actions`, `list_components`, `list_elision` (what the browser never downloads, and why each shipped module ships), `check`, `ui` (the `@webjsdev/ui` kit inventory + a component's helpers / paste-ready example / a11y header), plus a knowledge layer (docs / recipes / framework source). That knowledge layer reads the docs corpus installed in the app itself when there is one, so it is version-matched to the framework you are editing rather than to whenever the server was published, and `init` names the corpus it served and warns when a global install looks stale against the app.
 
 ---
 
@@ -279,7 +279,7 @@ MyThing.register('my-thing');
 
 **Signals are the default state primitive.** Import `signal` / `computed` from `@webjsdev/core`, read with `signal.get()` inside `render()`, and the built-in `SignalWatcher` re-renders on change. Module-scope signals share state across components and survive navigations; instance signals (constructor) are component-local.
 
-**Reactive properties ride HTML attributes, reflect to them, or arrive via SSR hydration.** They are declared ONLY by passing the property shape into the base-class factory `WebComponent({ ... })`. There is no `static properties` block and no `declare` line. The bare form takes a type constructor (`count: Number`, `label: String`, `open: Boolean`); the `prop()` helper carries options (`count: prop(Number, { reflect: true })`, `name: prop(String, { attribute: 'show-close-button' })`, internal state `prop({ state: true })` with no type), and narrows the TS type (`student: prop<Student>(Object)`, `mode: prop<'a' | 'b'>(String, { reflect: true })`). The types flow automatically to `this.<prop>`. Set defaults in the constructor after `super()` (a declarative `default` option also exists for lit-parity, a function default running per instance for a fresh object / array, but the constructor is the recommended way). NEVER use a class-field declaration OR initializer (e.g., `count = 0` or `todos!: Todo[]`), which compiles to define an own property on the instance and clobbers the reactive accessor (caught by `reactive-props-no-class-field`). Declaring your own `static properties` THROWS at runtime and is flagged by `no-static-properties`. Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`): the two share one JSON converter so neither crashes, but `Array` states the prop's shape and `array-prop-uses-array-type` flags the `Object` form. Property options: `type` (default `String`), `reflect`, `state`, `hasChanged`, `converter`, `default`, `attribute`. A `reflect: true` property whose value has no attribute representation REMOVES its attribute and warns rather than writing one, which covers a function (or an array carrying one, whose source would otherwise ship to every visitor) and a JSON-typed value `JSON.stringify` cannot serialize (a cycle, a `BigInt`, a throwing `toJSON`); a value merely CARRYING a function still reflects whole, since `JSON.stringify` drops it to `null` without losing the rest.
+**Reactive properties ride HTML attributes, reflect to them, or arrive via SSR hydration.** They are declared ONLY by passing the property shape into the base-class factory `WebComponent({ ... })`. There is no `static properties` block and no `declare` line. The bare form takes a type constructor (`count: Number`, `label: String`, `open: Boolean`); the `prop()` helper carries options (`count: prop(Number, { reflect: true })`, `name: prop(String, { attribute: 'show-close-button' })`, internal state `prop({ state: true })` with no type), and narrows the TS type (`student: prop<Student>(Object)`, `mode: prop<'a' | 'b'>(String, { reflect: true })`). The types flow automatically to `this.<prop>`. Set defaults in the constructor after `super()` (a declarative `default` option also exists for lit-parity, a function default running per instance for a fresh object / array, but the constructor is the recommended way). NEVER use a class-field declaration OR initializer (e.g., `count = 0` or `todos!: Todo[]`), which compiles to define an own property on the instance and clobbers the reactive accessor (caught by `reactive-props-no-class-field`). Declaring your own `static properties` THROWS at runtime and is flagged by `no-static-properties`. Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`): the two share one JSON converter so neither crashes, but `Array` states the prop's shape and `array-prop-uses-array-type` flags the `Object` form. Property options: `type` (default `String`), `reflect`, `state`, `hasChanged`, `converter`, `default`, `attribute`. A `converter.fromAttribute` runs on BOTH attribute readers (the SSR one and the client one) through one shared implementation, ahead of type coercion, so it executes server-side and must not touch browser globals, and a throw from it is not caught on either side. A source attribute is read identically by the SSR reader and the browser, because both resolve it against the same expression `observedAttributes` is built from: it is matched by its LOWERCASED name (so write kebab-case, never camelCase), a prop that renames its attribute answers to the new name ONLY, a `state: true` prop is skipped entirely, a name matching no declared property is ignored, and HTML character references are decoded before the value is coerced (including the legacy semicolon-less forms, wherever a browser decodes them). A `reflect: true` property whose value has no attribute representation REMOVES its attribute and warns rather than writing one, which covers a function (or an array carrying one, whose source would otherwise ship to every visitor) and a JSON-typed value `JSON.stringify` cannot serialize (a cycle, a `BigInt`, a throwing `toJSON`); a value merely CARRYING a function still reflects whole, since `JSON.stringify` drops it to `null` without losing the rest.
 
 **Lifecycle (lit-aligned), in order:** `shouldUpdate`, `willUpdate`, controllers' `hostUpdate()`, `update` (calls `render()` + commits), controllers' `hostUpdated()`, `firstUpdated`, `updated`, `updateComplete`, each receiving a `changedProperties` Map. **SSR runs only the constructor, attribute application, the pre-render hooks (`willUpdate` / `hostUpdate`), `reflect: true` reflection, and `render()`; it does NOT call `connectedCallback`, `firstUpdated`, `updated`, or any browser-only hook.** So defaults for first paint go in the constructor; browser-only data (localStorage, viewport, `navigator.*`) goes in `connectedCallback` writing a signal; server-known data arrives via the page function. Never ship a placeholder first paint that fetches in `connectedCallback`. A browser-only global in the constructor/`render()` throws at SSR (flagged by `no-browser-globals-in-render`; attribute methods and `closest()` are shimmed).
 
@@ -305,7 +305,7 @@ Default export receives `{ children, params, searchParams, url }`, must embed `c
 
 ### Error / loading / metadata routes
 
-`error.{js,ts}` default-exports `({ error, ...ctx }) => TemplateResult` (catches sibling-page / deeper render errors, innermost wins, prod sends only `error.message`). `loading.{js,ts}` wraps the sibling page in `Suspense` with an immediately-flushed fallback. `forbidden.{js,ts}` / `unauthorized.{js,ts}` render the nearest 403 / 401 boundary for a thrown `forbidden()` / `unauthorized()` (#848). Two **root-only** boundaries (`app/` root exactly): `global-error.{js,ts}` is the app-wide catch-all tried after the nested `error` boundaries are exhausted, and it renders its **own** `<!doctype><html><body>` document (returned verbatim, since a root-layout failure is when it fires). Because it is returned verbatim (no framework `<head>` splice), it ships **no importmap or boot script**, so keep it **static HTML with no components/hydration** (a last-resort page must not depend on the module system that may have just failed); under an opt-in CSP, an inline `<script>` in it must carry the nonce via `cspNonce()` (an inline `<style>` needs one only if you tighten `style-src`, since the default allows inline style outright). `global-not-found.{js,ts}` renders for an unmatched-anywhere URL when no `not-found` matches. `not-found` is nearest-wins from the throwing page's chain (#848 fixed the prior root-only behavior). Metadata routes (`sitemap`, `robots`, `manifest`, `icon`, `apple-icon`, `opengraph-image`, `twitter-image`) live at app root or static segments only and default-export a possibly-async function; `sitemap(entries)` / `sitemapIndex(sitemaps)` from `@webjsdev/server` serialize spec-valid XML.
+`error.{js,ts}` default-exports `({ error, ...ctx }) => TemplateResult` (catches sibling-page / deeper render errors, innermost wins, prod sends only `error.message`). `loading.{js,ts}` wraps the sibling page in `Suspense` with an immediately-flushed fallback. `forbidden.{js,ts}` / `unauthorized.{js,ts}` render the nearest 403 / 401 boundary for a thrown `forbidden()` / `unauthorized()` (#848). Two **root-only** boundaries (`app/` root exactly): `global-error.{js,ts}` is the app-wide catch-all tried after the nested `error` boundaries are exhausted, and it renders its **own** `<!doctype><html><body>` document (returned verbatim, since a root-layout failure is when it fires). Because it is returned verbatim (no framework `<head>` splice), it ships **no importmap or boot script**, so keep it **static HTML with no components/hydration** (a last-resort page must not depend on the module system that may have just failed); under an opt-in CSP, an inline `<script>` in it must carry the nonce via `cspNonce()` (an inline `<style>` needs one only if you tighten `style-src`, since the default allows inline style outright). `global-not-found.{js,ts}` renders for an unmatched-anywhere URL when no `not-found` matches. `not-found` is nearest-wins from the throwing page's chain (#848 fixed the prior root-only behavior). Metadata routes (`sitemap`, `robots`, `manifest`, `icon`, `apple-icon`, `opengraph-image`, `twitter-image`) live at app root or static segments only and default-export a possibly-async function; `sitemap(entries)` / `sitemapIndex(sitemaps)` from `@webjsdev/server` serialize spec-valid XML. **`icon` / `apple-icon` are auto-LINKED** into the head (`<link rel="icon" href="/icon">`, `<link rel="apple-touch-icon" href="/apple-icon">`, base-path prefixed, no asserted `type` / `sizes` since the route picks its content type at request time), so writing the file is the whole wiring. A declared `metadata.icons` **suppresses** them rather than merging, matching Next's precedence for its static icon files, so an app that outgrows a placeholder route names its real icons instead of deleting it. `opengraph-image` / `twitter-image` are NOT auto-linked (a preview image is a per-page editorial choice): point `metadata.openGraph.images` / `metadata.twitter.images` at them. Declare a favicon through `metadata.icons` or a metadata route, never a hand-written `<link rel="icon">`, since only the root layout may write a shell at all (invariant 8). See `references/routing-and-pages.md`.
 
 ### Route handlers (`app/**/route.{js,ts}`)
 

package/resources/SKILL.md

@@ -238,7 +238,9 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 - Writing a bare `<form method="post">` and expecting a page `action` export to catch it. There is no such export; bind the action with `action=${fn}` or the submission is a 405.
 - Putting a submitter's `formaction=${fn}` on anything that is not a submit control, or on a button carrying its own `name` / `value`. The identity IS the button's name/value pair, so both halves are spoken for.
 - Writing `formmethod="get"` or `formenctype="text/plain"` on a button that BINDS an action. Neither can carry that action's body, so the pair contradicts itself and throws. On a button that binds nothing it is a legal native override and is honoured.
-- Binding an action whose file declares `export const method = 'GET'`. That is a 405 at runtime and a `webjs check` error.
+- Binding an action whose file declares `export const method = 'GET'`. Form-bound actions strictly require POST (default). Binding a GET action to a form is a 405 at runtime and a `webjs check` error (`form-action-not-a-get-action`).
+- Leaving read-only RPC server query actions as default `POST`. Always export `export const method = 'GET'` for RPC data queries so arguments ride URL params, ETags/304 caching work, and CSRF is safely bypassed.
+- Writing `method="get"` on a bound `<form action=${fn}>`. WebJs supplies `method="post"` and `formenctype` automatically, and a bound form declaring `method="get"` is REFUSED at render (a thrown error, not a warning), because a GET sends no body for the action to read.
 - Throwing `redirect()` / `notFound()` inside a `route.ts` handler (uncaught 500). Return a `Response` there.
 - A placeholder first paint that fetches in `connectedCallback`. SSR does not call `connectedCallback`; put first-paint data in the constructor (server-known inputs) or use `async render()`.
 - A browser global (`window`, `document`, `localStorage`) in the constructor or `render()`. It throws at SSR; do browser-only work in `connectedCallback`.

package/resources/corpus.json

@@ -1,6 +1,6 @@
 {
   "package": "@webjsdev/mcp",
-  "version": "0.1.13",
-  "sha": "207f216844251c7f171060aa6ac18d25d7d117f6",
-  "copiedAt": "2026-08-08T19:53:44.949Z"
+  "version": "0.1.14",
+  "sha": "d1ecf972d1bc34128ccdc71878cd87d5430cf4c7",
+  "copiedAt": "2026-08-10T21:12:38.703Z"
 }

package/resources/references/built-ins.md

@@ -145,7 +145,7 @@ setFileStore(diskStore({ dir: '/var/data/uploads', baseUrl: '/files' }));
 
 ## The `"webjs"` config block (package.json)
 
-All keys are optional, and a malformed entry in a key the SERVER reads is dropped at boot with a warning, never crashing the pipeline. The one exception is `doctor.gate`, which is read by the `webjs doctor` CLI rather than the server and rejects a bad entry outright (see the doctor severity gate below): a gate whose typo was quietly ignored would leave CI un-gated while looking gated, which is the one thing that mechanism cannot afford.
+All keys are optional, and a malformed entry in a key the SERVER reads is dropped at boot rather than crashing the pipeline, some readers warning as they drop it. `headers` and `redirects` warn on every drop. Both warn for the key itself when it is present but not an array, and for each rule or entry inside it; `headers` has a third level and warns per header directive too. An absent key is the default and says nothing. An UNKNOWN top-level key no longer passes in silence either (#1300): the block is validated against the published JSON Schema once per boot, in dev and in prod alike, and one aggregated warning names what was ignored. So a `"redirect"` typed for `"redirects"` now says so in the server output instead of silently leaving the feature at its default. It never fails the boot. Know its exact reach, since what it passes over looks like what it catches. It reports any unknown TOP-LEVEL key, whatever it is called, and it checks the VALUE of 9 of the 17 known keys, being the one `enum` and the `boolean` / `integer` leaves. It does not descend into a nested object, so a misspelling inside `dev` or `start` is not reported, and it does not type-check the other 8 (`headers`, `redirects`, `basePath`, `allowedOrigins`, `csp`, `dev`, `start`, `doctor`), whose schemas are the free-form ones a blunt check would start refusing working configs over. Whether anything else notices a value this check passes over is up to that value's own reader, and it varies by reader. `doctor.gate` varies furthest, since the boot check never descends into any key and the `webjs doctor` CLI, not the server, is what reads this one, rejecting a bad entry outright (see the doctor severity gate below): a gate whose typo was quietly ignored would leave CI un-gated while looking gated, which is the one thing that mechanism cannot afford.
 
 ### Security headers
 

package/resources/references/components.md

@@ -135,17 +135,21 @@ The bare form is shorthand: `count: Number` means `prop(Number)`. Use `prop()` t
 |---|---|---|
 | `type` | `String` | Constructor feeding the default attribute converter |
 | `reflect` | `false` | Property changes write back to the HTML attribute (a value with no attribute representation removes it instead, see below) |
-| `state` | `false` | Internal-only. No attribute, not observed |
+| `state` | `false` | Internal-only. No attribute, not observed, and never read from one at SSR either |
 | `attribute` | derived from name | The HTML attribute name the property rides |
 | `default` | none | Declarative initial value (a function runs per instance for a fresh object / array) |
 | `hasChanged` | strict `!==` | Custom change detection |
-| `converter` | type-based | Custom attribute-to-property serialization |
+| `converter` | type-based | Custom attribute-to-property serialization. `fromAttribute` runs on BOTH readers (the client upgrade and SSR), ahead of type coercion |
 
 For an array-typed prop pass `Array`, not `Object` (`array-prop-uses-array-type` flags the `Object` form). For anything the built-in converters cannot parse (Date, Map, Set) supply a `converter`.
 
+**A `converter.fromAttribute` runs SERVER-SIDE too.** Both attribute readers go through one shared implementation, so the converter fires during SSR as well as on the client upgrade, and it wins over the declared `type` on both. So keep it free of browser globals (`document`, `window`, `navigator`), since SSR has no DOM and touching one throws where the same code worked in the browser. A converter that THROWS is not caught by either reader, because an author who writes one owns the conversion: at SSR the throw lands in per-component error isolation (an error box in dev, an empty element at a 200 in production, with the cause in the server log) while sibling components still render, and on the client it escapes `attributeChangedCallback` during upgrade. Both readers hand the converter DECODED attribute text, so a converter that parses its input (`JSON.parse` for a Map or a Set, `new Date(...)`) sees the same string on both sides even when the attribute carries `"` or `&`.
+
 **A `reflect: true` property holding a FUNCTION drops its attribute instead of writing one, and so does one holding an array that carries a function, unless the prop is `Object` or `Array` typed.** A function has no HTML attribute representation, and the serializations it would otherwise get are both useless and dangerous. `String(fn)` is the function's SOURCE, so a reflected `'use server'` action would ship its whole body, closure secrets included, to every visitor, and `JSON.stringify(fn)` is `undefined`, which lands in the attribute as the literal four-character string. So the reflection path treats a function like `null`, removes the attribute, and warns naming the property, the tag, and the attribute. This holds on both sides, since SSR and the client-side setter run the same path, and it holds for every property name (the leak was never specific to one called `action`). Two exceptions. A property with a custom `converter.toAttribute` runs that converter first and is left alone, because an author who writes one has taken responsibility for serializing whatever they are handed. And an `Object` or `Array` typed property CARRYING a function keeps its data, because `JSON.stringify` drops the function to `null` and omits the key, so `[1, 2, fn]` reflects as `[1,2,null]` with no source and nothing else lost. If you need a function on a component, use a plain property or a signal and do not mark it `reflect`.
 
-**An `Object` or `Array` typed reflected property whose value `JSON.stringify` cannot serialize AT ALL drops its attribute the same way, and warns.** Three shapes do this: a cycle (an object or array that reaches itself, which arrives from a parent/child graph, a linked node, a memo table, or anything a library hands back with a back-reference), a `BigInt` anywhere inside the value, and an author `toJSON()` that throws. The line to keep straight is that a value which serializes WITH A GAP in it keeps its data (the carried-function case above), while one that does not serialize at all has no string to put in the attribute and so has no attribute representation, exactly like a function. The property itself is untouched and still holds the value; only the attribute goes. Before this guard the throw escaped reflection entirely, which meant a client upgrade threw before the component's first render, and an SSR render was swallowed by per-component error isolation, which shows an error box in dev and renders the component EMPTY on a page that still returned 200 in production. To reflect something about a graph-shaped value, reflect a derived scalar (an id, a count) and keep the graph on a non-reflected property. On the read side an attribute that is PRESENT but not parseable JSON reads back as `null` rather than as the raw string, on both the SSR and the client reader. An ABSENT attribute is a different case: neither reader sees it, so the property keeps its constructor value.
+**An `Object` or `Array` typed reflected property whose value `JSON.stringify` cannot serialize AT ALL drops its attribute the same way, and warns.** Three shapes do this: a cycle (an object or array that reaches itself, which arrives from a parent/child graph, a linked node, a memo table, or anything a library hands back with a back-reference), a `BigInt` anywhere inside the value, and an author `toJSON()` that throws. The line to keep straight is that a value which serializes WITH A GAP in it keeps its data (the carried-function case above), while one that does not serialize at all has no string to put in the attribute and so has no attribute representation, exactly like a function. The property itself is untouched and still holds the value; only the attribute goes. Before this guard the throw escaped reflection entirely, which meant a client upgrade threw before the component's first render, and an SSR render was swallowed by per-component error isolation, which shows an error box in dev and renders the component EMPTY on a page that still returned 200 in production. To reflect something about a graph-shaped value, reflect a derived scalar (an id, a count) and keep the graph on a non-reflected property. On the read side an attribute that is PRESENT but not parseable JSON reads back as `null` rather than as the raw string, on both the SSR and the client reader. An ABSENT attribute is a different case: neither reader sees it, so the property keeps its constructor value. The two readers also see the same attribute SET, not merely the same fallback: a `state: true` prop, a camelCase attribute name, and an attribute matching no declared property are all ignored by both, and both are handed a value whose HTML character references are already decoded.
+
+**Writing attributes in markup.** Names are case-insensitive and the browser lowercases them while parsing, so write kebab-case (`user-name`); a camelCase attribute (`userName="…"`) reaches no property on either side. A prop that renames its attribute answers to the new name ONLY, so `open: prop(Boolean, { attribute: 'is-open' })` is written `<my-el is-open>` and `<my-el open>` reaches nothing. Character references are decoded before the value is coerced, so `cfg="&#123;&quot;a&quot;:1&#125;"` parses as the object it spells and `label="Tom &amp; Jerry"` is `Tom & Jerry`; the legacy semicolon-less forms decode exactly where a browser decodes them (`&nbsp` at the end of a value is a non-breaking space, `&nbspx` and `&nbsp=x` stay literal), and writing the semicolon avoids the question. A `state: true` prop takes an SSR value only through a `.prop=${value}` binding from the parent template, never from an attribute.
 
 **Never use a class-field declaration OR initializer** (`count = 0`, `student: Student = {...}`, `todos!: Todo[]`). Under `useDefineForClassFields` even a type-only `todos!: Todo[]` compiles to define an own property after `super()`, which clobbers the prototype's reactive accessor and silently breaks reactivity. Only declare props in the factory and read/write them off `this`. The `reactive-props-no-class-field` rule catches this.
 

package/resources/references/data-and-actions.md

@@ -146,15 +146,41 @@ Everything the action declares applies here too, or an action would be protected
 - `invalidates` is evicted when the action actually RAN (a middleware short-circuit does not evict), and the evicted tags are reported on the response so the browser's tag coordinator bypasses a stale cached GET. One reach limit: `fetch` follows the success `303` transparently, so JS cannot read a redirect's headers; the tags are on the wire and the `422` re-render carries them, and the redirect's own render is server-side and seeds fresh data.
 - `invalidates` and `tags` receive the SAME first argument the action does, so on a form boundary they receive the `FormData`. `invalidates: (input) => ['post:' + input.id]` returns `post:undefined` for a submission and evicts nothing. Either read the field (`(fd) => ['post:' + fd.get('id')]`), declare a `validate` that transforms the `FormData` into the typed input first (the transform result is what the config functions then see), or use an argument-independent tag.
 - `method = 'GET'` cannot be bound to a form: a GET action rides its args in the url and is CSRF-exempt, so it cannot answer a form POST. That is a `405` at runtime and the `form-action-not-a-get-action` error in `webjs check`.
+- A form whose buttons run DIFFERENT actions binds each on its submitter, `<button formaction=${publishDraft}>`. **The submitter is self-sufficient** (#1307): the renderer gives it `formmethod="post"` and `formenctype` ON THE BUTTON, alongside the identity riding the button's own `name`/`value` pair, and a submitter's `formmethod` overrides the form's `method` per HTML. So a per-button action works inside a bound form, an unbound form, a `method="get"` form, or a form with no method at all, and the enclosing form does not need binding for the button's sake. Bind the form when the FORM itself should run an action on a plain submit. In dev the client logs one `console.error` at submit time for a submission holding an identity it cannot deliver, and in production both server-visible fingerprints reach `onError` with a code (`WEBJS_FORM_SUBMITTED_AS_GET` for an identity in the query string, `WEBJS_FORM_ACTION_MISSING` for a body carrying no identity). See `muscle-memory-gotchas.md` for the shape.
 
 The response drives the page: a success is a `303` PRG (to `result.redirect` when it is a same-site local path, else the page's own url), a failure re-renders the SAME page with `status` (default `422`) and the result on `actionData`, a submission carrying no identity is a `405`, and one whose hash no longer resolves is a `422` with a resubmit message (a form held open across a deploy). The submission is Origin-verified like an RPC call, so no token field is needed.
 
 A streamed return (#489) is refused from a form-bound action: the RPC stub decodes frames, but a submission is answered with a redirect or a page, and with JS off there is no consumer at all. Stream from a programmatic call instead.
 
-## HTTP-verb config exports
+## HTTP-verb config exports & decision guide
 
 A `'use server'` action is a POST by default. Reserved sibling exports, read statically (the same way a page reads `export const revalidate`), change its HTTP semantics WITHOUT changing the call site (you still write `await getUser(7)`).
 
+### HTTP Verbs Decision Guide
+
+| Action Kind | Target Verb | Example Declaration | HTTP Semantics & Features |
+|---|---|---|---|
+| **Form-Bound Action** (`<form action=${fn}>`) | **POST** (default) | *(no export or `export const method = 'POST'`) | Standard HTML form submission. Enforces `POST` + `multipart/form-data` or `urlencoded`. **Never export `method = 'GET'`** (triggers 405 refusal & `webjs check` violation). |
+| **RPC Read Action (Query)** | **GET** | `export const method = 'GET'` | Read-only RPC calls (`await getTodos()`). Args ride URL query params (with POST fallback over 4KB). CSRF-exempt, supports ETags, 304 revalidation, and `export const cache`. |
+| **RPC Write Action (Mutation)** | **POST** / **PUT** / **PATCH** / **DELETE** | Default or `export const method = 'DELETE'` | Data-modifying RPC calls (`await deleteUser(4)`). Carries CSRF protection, serialized payload body, and evicts cached query tags via `export const invalidates`. |
+
+### Choosing the right HTTP verb
+
+1. **Form-Bound Actions (`<form action=${fn}>` / `<button formaction=${fn}>`):**
+   - **MUST be POST.** Leave unannotated (default) or export `export const method = 'POST'`.
+   - **NEVER export `export const method = 'GET'` for form actions.** The HTML renderer automatically emits `method="post"` and `formenctype` for form actions. Binding a `method = 'GET'` action to a form returns a `405 Method Not Allowed` at runtime and triggers a `webjs check` error (`form-action-not-a-get-action`).
+   - **NEVER add `method="get"` to a bound `<form action=${fn}>`.** WebJs manages form submission semantics automatically, and a bound form declaring `method="get"` is REFUSED at render (a thrown error, not a warning), because a GET sends no body for the action to read.
+
+2. **Programmatic / RPC Read Actions (Queries):**
+   - **ALWAYS export `export const method = 'GET'` for read-only queries.**
+   - When an action only fetches data (`await getUser(id)`), exporting `method = 'GET'` instructs the client RPC stub to issue an HTTP GET request with arguments encoded in query parameters.
+   - Enables browser/CDN caching, weak ETags (returning 304 Not Modified on cache hit), and HTTP `Cache-Control` header generation when paired with `export const cache = ...`.
+
+3. **Programmatic / RPC Write Actions (Mutations):**
+   - **Use POST, PUT, PATCH, or DELETE for writes.**
+   - Use default `POST` or explicitly export `PUT`/`PATCH`/`DELETE` for RESTful RPC calls (`await removeUser(id)`).
+   - Pair mutating actions with `export const invalidates = (args...) => ['tag']` to evict cached reads matching those tags upon completion.
+
 ```ts
 // modules/users/queries/get-user.server.ts: a cached, tagged GET read
 'use server';
@@ -165,8 +191,9 @@ export async function getUser(id: number) { return db.query.users.findFirst({ wh
 ```
 
 ```ts
-// a mutation evicts the tags it touches
+// modules/users/actions/update-user.server.ts: a mutation evicting matching tags
 'use server';
+export const method = 'PATCH';                     // explicit verb
 export const invalidates = (id: number) => ['user:' + id];
 export const middleware = [requireAuth];           // async (ctx, next) => result; read ctx via actionContext()
 export async function updateUser(id: number, patch: Partial<User>) { /* ... */ }

package/resources/references/muscle-memory-gotchas.md

@@ -110,6 +110,7 @@ The bound, refused, and allowed shapes in full. Every "no" row is a binding that
 | `action=${fn}` on any other tag | yes | `action` submits nothing off a `<form>`, so it is an ordinary attribute and the function would be stringified |
 | `action="${fn}"`, or a mixed `action="/x/${fn}"` | yes | quoting turns a binding hole back into a plain attribute |
 | `formaction=${fn}` unquoted, on a submitter, ANYWHERE | **no, it BINDS** | the second supported shape (#1207, #1307). A bound submitter carries its WHOLE submission: the identity rides the button's own `name`/`value` pair, the one channel a browser submits for the pressed button alone, and the renderer adds `formmethod="post"` and `formenctype="multipart/form-data"` to the button itself. So it works inside a bound form, an unbound form, a `method="get"` form, or a form with no method at all, and it asks NOTHING of the element around it. No `formaction` url is emitted, and the server takes the LAST `__webjs_action` entry |
+
 | `formaction=${fn}` on a submitter carrying its own `name` or `value` | yes | the identity IS that name/value pair, so both halves are already spoken for. Bind one action on the form and dispatch on `name="intent"` if you need the button's own value |
 | `formaction=${fn}` on a non-submit control, or `<input type="image">` | yes | `formaction` is inert on anything that does not submit, and an image submitter sends `name.x` / `name.y` coordinates instead of `name=value`, so the identity would never arrive |
 | `formaction=${fn}` on a submitter with `form="other"` | yes | it re-points the submitter at a different form owner, which may not be where the identity field it needs lives |
@@ -118,6 +119,8 @@ The bound, refused, and allowed shapes in full. Every "no" row is a binding that
 | `formmethod="dialog"` on a submitter that binds nothing | **no** | a native `<dialog>` dismissal, never a submission, so there is no body for the action to miss. It IS refused on a button that also binds an action, which is a straight contradiction |
 | a plain `formaction="/url"` on a submitter inside a bound form | **no** | it retargets the submission away from the page's bound action entirely, so where it goes and how is your business |
 | `.action=` on a native form | yes | the supported binding is the plain attribute, and a `.prop` on a native element drops at SSR, so accepting it would mean a form that submits under JS and does nothing without it |
+| `export const method = 'GET'` on a form-bound action file | yes | form-bound actions strictly enforce `POST`. Binding a GET action to a form produces a 405 runtime refusal and `webjs check` error (`form-action-not-a-get-action`) |
+| `method="get"` on a bound `<form action=${fn}>` | yes | WebJs supplies `method="post"` and `formenctype` automatically, and a bound form declaring `method="get"` is REFUSED at render (a thrown error, not a warning), because a GET sends no body for the action to read |
 | `.method=` / `.enctype=` / `.encoding=` on a BOUND form | yes | the same reason one level over. All three are reflected IDL attributes, so SSR drops the binding and emits `method="post"` while a browser ends at what you assigned. Write them as plain attributes |
 | a second `action=${fn}` on one form | yes | SSR emits the second as a plain url next to the identity field, the client takes the last. Bind exactly one, in either position |
 | a plain `action="/url"` beside the bound hole | yes | the hole drops only its OWN attribute, so SSR keeps the static one while the client removes it: without JS the browser posts to `/url`, with JS to the page |
@@ -134,6 +137,27 @@ That last row is the one to remember: quoting a binding hole turns it back into
 
 `.action=${fn}` on a native form is refused during SSR too, even though the property is dropped there and nothing could leak, so a page cannot render clean on the server and then throw on hydration.
 
+**A bound submitter is self-sufficient and asks nothing of the form around it.** This is the shape people expect to have to wire up, and do not:
+
+```ts
+// components/publish-button.ts   <- the submitter lives here
+class PublishButton extends WebComponent({}) {
+  render() { return html`<button formaction=${publishDraft}>Publish</button>`; }
+}
+PublishButton.register('publish-button');
+
+// app/triage/page.ts             <- the form lives here
+// BOTH work. The button carries its own submission attributes.
+html`<form><publish-button></publish-button></form>`;
+html`<form action=${saveAll}><publish-button></publish-button></form>`;
+```
+
+The renderer supplies the submission attributes at the level where the action is BOUND (#1307), so a bound `<button>` gains `formmethod="post"` and `formenctype` ON THE BUTTON, alongside the reserved `__webjs_action` identity riding the button's own `name`/`value` pair. A submitter's `formmethod` overrides the form's `method` per HTML, so the submission is a POST whatever the enclosing form declares, including no `method` at all or `method="get"`, and the identity travels in the body where the dispatcher reads it.
+
+That is also why the renderer refuses only a SAME-ELEMENT contradiction (a bound submitter's own `formmethod` other than post, an `formenctype` the server cannot parse, `formmethod="dialog"`) and never a cross-element one. A component renders its template in a separate pass with no view of the host page, so the cross-element question is unanswerable at render time, and self-sufficiency leaves nothing for it to answer. One consequence: no `formaction` url is emitted, so the submission targets whatever the FORM targets, and a form declaring `action="/x"` sends its buttons there. The action still runs when `/x` is a PAGE route, since the identity travels in the body; against a `route.ts` or another origin nothing runs, which the dev-time client guard reports at submit time.
+
+**Two runtime signals cover what is left.** In dev, submitting a form that carries an action identity it cannot deliver logs one `console.error` naming the fix, once per shape; it never throws, so the submission behaves exactly as it does in production. In production, both server-visible fingerprints reach the `onError` hook (the programmatic `createRequestHandler({ onError })` option and any sink an `instrumentation.{js,ts}` installed) with a code to group on: `WEBJS_FORM_SUBMITTED_AS_GET` for a page GET carrying the reserved field in its query string, and `WEBJS_FORM_ACTION_MISSING` for a form body carrying no identity at all. A BOUND submitter carries its own `formmethod="post"`, and a bound form is refused a `method="get"` outright, so what reaches the first one is a PLAIN submitter's `formmethod="get"`, which native precedence lets win and the renderer deliberately honours, or a hand-authored form carrying the reserved field. Both are detect-only, so no status changes, and both carry the submitted field NAMES and never the values.
+
 **Inside a component you may never see the error.** Per-component SSR error isolation contains the throw, so development shows an error box in place of the component and production renders it empty with the page still returning 200. A form that has silently vanished in production is this bug wearing a disguise; the message is in the server log. Nothing leaks either way.
 
 Two things that "renders it empty" understates, both worth knowing before you go looking:

package/resources/references/routing-and-pages.md

@@ -192,7 +192,28 @@ Refusals worth knowing: `formaction=${fn}` is supported on a `<button>` anywhere
 
 Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments and default-export a possibly-async function; `sitemap()` / `sitemapIndex()` from `@webjsdev/server` serialize spec-valid XML.
 
-The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless). Then point `metadata` at the route via `openGraph.images` / `twitter.images` / `icons` (or drop a static file in `public/` instead).
+The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless).
+
+**`icon` and `apple-icon` are LINKED for you.** An app that declares no `metadata.icons` gets `<link rel="icon" href="/icon">` and `<link rel="apple-touch-icon" href="/apple-icon">` in the head automatically, for whichever of the two routes it defines (base-path prefixed, since that is where the route answers). No `type` or `sizes` is asserted, because the route picks its content type at request time and the browser sniffs the served one.
+
+Declaring `metadata.icons` **suppresses** the routes rather than merging with them, which is what Next does with its static icon files. So an app that outgrows a placeholder `app/icon.ts` names its real icons and the route stops being linked without having to be deleted:
+
+```ts
+// app/layout.ts  ->  these win; /icon and /apple-icon are no longer linked
+export const metadata = {
+  icons: {
+    icon: [
+      { url: '/public/favicon-192.png', type: 'image/png', sizes: '192x192' },
+      { url: '/public/favicon.svg', type: 'image/svg+xml', sizes: 'any' },
+    ],
+    apple: { url: '/public/apple-touch-icon.png', sizes: '180x180' },
+  },
+};
+```
+
+Declare a favicon through `metadata.icons` (or a metadata route), never as a hand-written `<link rel="icon">`: only the root layout may write a shell at all (invariant 8), so a hand-written tag is unavailable to every other layout. A `public/favicon.ico` needs no declaration either way, since the framework serves it at the origin root for crawlers that read no markup.
+
+`opengraph-image` and `twitter-image` are NOT auto-linked (a preview image is a per-page editorial choice, not a site-wide default). Point `metadata` at those via `openGraph.images` / `twitter.images`.
 
 ```ts
 // app/opengraph-image.ts  (OG is 1200x630; apple-icon 180x180)

package/resources/references/styling.md

@@ -109,6 +109,19 @@ The default stack is a static compiled Tailwind stylesheet (`css:build` compiles
 
 **Two halves.** (1) `public/input.css` MAPS token names into Tailwind with `@theme inline` (`--color-background: var(--background)`), so `bg-background` resolves to `var(--background)`. That is infrastructure; leave it. (2) The root layout (`app/layout.ts`) DEFINES the values as plain CSS custom properties in a `<style>` block. That is your palette; make it your own. A freshly cleared app (after `npm run gallery:clear`) ships only the OS system-colour base (`Canvas` / `CanvasText`) with NO tokens, so building this palette is your first styling step.
 
+**`@theme` and `@theme inline` differ in whether the token reaches `:root`, and the difference is silent.** Measured on `tailwindcss@4.3.0`, a token mapped in a theme block is emitted as a real `:root` custom property when:
+
+| block | token used only through a utility (`border-border`) | token written as a raw `var(--color-x)` in any SCANNED file | token unused |
+|---|---|---|---|
+| `@theme` | emitted | emitted | not emitted |
+| `@theme inline` | NOT emitted (the value is substituted into the utility) | emitted | not emitted |
+
+The one cell that bites is `inline` plus utility-only usage. Nothing on the page can then inherit `--color-x`, so a raw `var(--color-x)` written somewhere Tailwind never scanned resolves to nothing and the declaration falls back to its initial value (a border or outline silently becomes `currentColor`).
+
+"Scanned" is wider than it looks, and this is the part worth knowing: Tailwind scans source files as raw text, so a `var(--color-ring)` inside a component's `static styles` template DOES count and forces emission, exactly like one in the stylesheet. That is why the `@webjsdev/ui` kit theme works despite using `inline`. So the rule is not "shadow components need a plain `@theme`". It is: **if a token is only ever used through utilities, and something outside the scanned source needs to inherit it, map that token with a plain `@theme`.** Anything under a configured `@source` is scanned and needs no special handling.
+
+Whichever form you use, a token nothing references is dropped in both, so an unused mapping is dead configuration rather than a safety net.
+
 **Light and dark, defined once (DRY).** Write each colour token ONE time with the native CSS `light-dark(LIGHT, DARK)` function and let `color-scheme` pick the side. The default `color-scheme: light dark` follows the OS; a `[data-theme]` attribute forces one. No duplicated light/dark blocks:
 
 ```html

package/resources/references/ui-kit.md

@@ -72,5 +72,20 @@ dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
   the tokens are missing (re-run `npx webjsdev ui init` or let `add` self-heal them).
 - Custom elements are display-only-safe at SSR and hydrate in the browser, the
   standard WebJs component model (`references/components.md`).
+- A registry module should do no work at module scope, because the elision
+  analyser reads a module-scope call or a `document` reference as client work
+  and then the page that imports it ships whole (#1320). `cn` itself is clean,
+  so importing it never pins a page. Six modules still trip the analyser and DO
+  pin an importing page: `checkbox`, `radio-group`, `pagination`, `progress`,
+  `sonner`, `tabs`. The first two inject a stylesheet for real; the other four
+  are an analyser precision gap (an arrow with an expression body puts its call
+  at brace depth 0). Either way the page ships, so treat the list as fact rather
+  than as a technicality. Keep your own copies clean when you edit them, and run
+  `npx webjsdev elision`, which names the blocker whenever a page ships.
+- `native-select`'s `<option>` colours ride the design tokens, not the module.
+  An app with no theme block gets the browser default `<option>` colours along
+  with everything else unstyled, fixed the same way (re-run `init`, or let `add`
+  plant the block). An app whose block predates the rule keeps the default until
+  the rule is added by hand, because `init` never rewrites an existing block.
 
 Full per-package reference lives in the installed `@webjsdev/ui/AGENTS.md`.

package/src/mcp-docs.js

@@ -14,11 +14,15 @@
  * given its injected `{ docsDir, agentsPath, readFile }` deps, so it is testable
  * in-process without booting a server or touching the real filesystem.
  *
- * Docs resolution (so `npx @webjsdev/cli mcp` is self-contained): a published
- * install reads the corpus bundled under `<cli>/resources/references` (copied
- * at `prepack`, see `scripts/copy-mcp-resources.js`); a monorepo dev run falls
- * back to the repo-root skill. {@link resolveDocsLocation} encodes that
- * two-path lookup so source stays single (no committed duplicate docs).
+ * Docs resolution (so `npx @webjsdev/mcp` is self-contained): the APP's own
+ * installed `@webjsdev/mcp` corpus wins, then the running server's snapshot
+ * bundled under `<pkg>/resources/references` (copied at `prepack`, see
+ * `scripts/copy-mcp-resources.js`), then a repo-root-relative fallback, which is
+ * the skill on a monorepo dev run. {@link resolveDocsLocation} encodes that
+ * lookup so source stays single
+ * (no committed duplicate docs). `init` reports which of the three it served,
+ * from the `corpus.json` build stamp, and warns when the app's installed mcp is
+ * newer than the running server (#1319).
  *
  * @module mcp-docs
  */
@@ -30,38 +34,230 @@ import { fileURLToPath } from 'node:url';
 /** The URI scheme for a framework-docs resource: `webjs-docs://<name>`. */
 const DOCS_SCHEME = 'webjs-docs://';
 
+/**
+ * The paths of one bundled corpus root (`<something>/resources`), tagged with
+ * which rung it is so a caller can say WHOSE docs it ended up serving.
+ *
+ * @param {string} root  the `resources` directory
+ * @param {'app' | 'bundled'} corpusSource  which rung this root is
+ * @returns {{ docsDir: string, agentsPath: string, skillPath: string, corpusPath: string, corpusSource: 'app' | 'bundled' }}
+ */
+function bundleAt(root, corpusSource) {
+  return {
+    docsDir: join(root, 'references'),
+    agentsPath: join(root, 'AGENTS.md'),
+    skillPath: join(root, 'SKILL.md'),
+    corpusPath: join(root, 'corpus.json'),
+    corpusSource,
+  };
+}
+
 /**
  * Resolve where the framework-docs corpus lives, plus the `AGENTS.md` contract
- * path. Tries the BUNDLED location first (a published `@webjsdev/mcp` ships
- * `resources/references/` + `resources/SKILL.md` + `resources/AGENTS.md` via `prepack`), then falls
- * back to the monorepo-root skill layout used in dev and
- * tests. Returns `{ docsDir, agentsPath }`; either path may not exist, callers
- * fail soft (an empty corpus is valid, never a crash).
+ * and build-stamp paths. Three rungs, highest first:
+ *
+ * 1. `<appDir>/node_modules/@webjsdev/mcp/resources`, the APP's own installed
+ *    copy. It wins because it is version-matched to the framework the agent is
+ *    editing, and so is the only corpus that can be correct about that app. A
+ *    globally installed server otherwise serves a snapshot frozen at whatever
+ *    it was published from, which taught reverted guidance for months (#1319).
+ * 2. `<pkgRoot>/resources`, the running server's own bundled snapshot (copied
+ *    at `prepack`, see `scripts/copy-mcp-resources.js`).
+ * 3. A repo-root-relative path, which is the monorepo skill on a dev/test run.
+ *    This rung is an unconditional FALLBACK, not a checkout probe, so a
+ *    published install whose `resources/` bundle is missing lands here too,
+ *    with `repoRoot` inside `node_modules` and an empty corpus. `corpusPath` is
+ *    `null` because no bundle was found, which is why nothing downstream may
+ *    assert a checkout on this rung.
+ *
+ * The rung-1 probe is a plain `existsSync` on the references directory rather
+ * than `require.resolve('@webjsdev/mcp')` from `appDir`, because what this needs
+ * is "a directory of markdown at a known path" and nothing more. Resolving the
+ * package would go through its `exports` map, and in this monorepo that lands on
+ * the workspace symlink back to `packages/mcp`, whose `resources/` does not
+ * exist in a checkout, so the resolve would fall to rung 3 anyway.
+ *
+ * Any returned path may not exist; callers fail soft (an empty corpus is valid,
+ * never a crash).
  *
  * @param {string} [moduleUrl]  `import.meta.url` of the caller (defaults to this module)
- * @returns {{ docsDir: string, agentsPath: string }}
+ * @param {string} [appDir]  the app being asked about; enables the rung-1 probe
+ * @returns {{ docsDir: string, agentsPath: string, skillPath: string, corpusPath: string | null, corpusSource: 'app' | 'bundled' | 'repo' }}
  */
-export function resolveDocsLocation(moduleUrl) {
+export function resolveDocsLocation(moduleUrl, appDir) {
   const here = dirname(fileURLToPath(moduleUrl || import.meta.url));
   const pkgRoot = resolve(here, '..'); // packages/mcp/src -> packages/mcp
   const repoRoot = resolve(here, '..', '..', '..'); // -> monorepo root
 
-  const bundledRefs = join(pkgRoot, 'resources', 'references');
-  if (existsSync(bundledRefs)) {
-    return {
-      docsDir: bundledRefs,
-      agentsPath: join(pkgRoot, 'resources', 'AGENTS.md'),
-      skillPath: join(pkgRoot, 'resources', 'SKILL.md'),
-    };
+  if (typeof appDir === 'string' && appDir) {
+    const appRoot = join(appDir, 'node_modules', '@webjsdev', 'mcp', 'resources');
+    if (existsSync(join(appRoot, 'references'))) return bundleAt(appRoot, 'app');
   }
+  const bundledRoot = join(pkgRoot, 'resources');
+  if (existsSync(join(bundledRoot, 'references'))) return bundleAt(bundledRoot, 'bundled');
+
   const skill = join(repoRoot, '.agents', 'skills', 'webjs');
   return {
     docsDir: join(skill, 'references'),
     agentsPath: join(repoRoot, 'AGENTS.md'),
     skillPath: join(skill, 'SKILL.md'),
+    corpusPath: null,
+    corpusSource: 'repo',
   };
 }
 
+/**
+ * Compare two `major.minor.patch` versions, returning `-1` / `0` / `1`.
+ *
+ * Dependency-free by design (this package ships zero dependencies), and
+ * deliberately coarse: any prerelease or build suffix is stripped before
+ * comparing, a missing segment reads as `0`, and a non-numeric segment reads as
+ * `0`. Its only consumer is the staleness warning, where the question is "is the
+ * app's copy meaningfully newer", so ranking two prereleases of one patch is not
+ * a case that needs an answer.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1}
+ */
+export function compareVersions(a, b) {
+  const parts = (v) => String(v == null ? '' : v).trim().split(/[-+]/)[0].split('.');
+  const pa = parts(a);
+  const pb = parts(b);
+  for (let i = 0; i < 3; i++) {
+    const x = Number(pa[i]);
+    const y = Number(pb[i]);
+    const nx = Number.isFinite(x) ? x : 0;
+    const ny = Number.isFinite(y) ? y : 0;
+    if (nx !== ny) return nx < ny ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * The `@webjsdev/mcp` version installed in `appDir`, or `null` when that cannot
+ * be known (no app dir, no install, an unreadable or unparseable manifest, no
+ * `version` field). Only mcp's own version is read: the corpus ships INSIDE this
+ * package, so mcp's version is the only one that bounds the docs, and reading
+ * the other `@webjsdev/*` manifests would multiply the failure modes without
+ * adding signal.
+ *
+ * @param {string} [appDir]
+ * @param {{ exists?: (p: string) => boolean, readFile: (p: string, enc: string) => Promise<string> }} deps
+ * @returns {Promise<string | null>}
+ */
+export async function readAppMcpVersion(appDir, deps) {
+  if (typeof appDir !== 'string' || !appDir) return null;
+  const manifest = join(appDir, 'node_modules', '@webjsdev', 'mcp', 'package.json');
+  try {
+    if (deps.exists && !deps.exists(manifest)) return null;
+    const version = JSON.parse(await deps.readFile(manifest, 'utf8')).version;
+    return typeof version === 'string' && version ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The one line naming WHICH docs corpus `init` is serving, so an agent reading a
+ * stale global install can see that it is stale (#1319). Never throws: a
+ * missing, unreadable, or malformed stamp degrades to the unstamped wording,
+ * because refusing to answer is strictly worse than answering with a caveat.
+ *
+ * @param {object} deps
+ * @returns {Promise<string>}
+ */
+async function corpusLine(deps) {
+  // Rung 3 has no stamp, and it is a FALLBACK rather than a checkout probe, so
+  // this must not claim a checkout: a published install whose `resources/` is
+  // missing lands here too, with an empty corpus and no checkout to name.
+  if (!deps.corpusPath) return 'Docs corpus: no bundled snapshot; serving whatever docs this server resolved locally.';
+  const unstamped = 'Docs corpus: an unstamped @webjsdev/mcp bundled snapshot.';
+  try {
+    const stamp = JSON.parse(await deps.readFile(deps.corpusPath, 'utf8'));
+    if (!stamp || !stamp.version) return unstamped;
+    const pkg = stamp.package || '@webjsdev/mcp';
+    const date = typeof stamp.copiedAt === 'string' && stamp.copiedAt ? stamp.copiedAt.slice(0, 10) : 'an unknown date';
+    // A SHA the stamp could not capture drops the clause rather than printing a
+    // placeholder: the point of a provenance line is that no answer reads as no
+    // answer. Same reason the shape is checked, since only a real commit id
+    // resolves to a diff.
+    const sha = typeof stamp.sha === 'string' && /^[0-9a-f]{40}$/.test(stamp.sha) ? stamp.sha.slice(0, 7) : null;
+    return sha
+      ? `Docs corpus: ${pkg}@${stamp.version}, copied from webjsdev/webjs ${sha} on ${date}.`
+      : `Docs corpus: ${pkg}@${stamp.version}, copied on ${date}.`;
+  } catch {
+    return unstamped;
+  }
+}
+
+/**
+ * What the warning says about WHOSE docs it just served, one clause per rung.
+ *
+ * A `Map` rather than an object literal, for the reason `docsDepsCache` is one:
+ * an object literal inherits `Object.prototype`, so a lookup keyed on an
+ * unexpected value like `constructor` or `toString` returns a truthy FUNCTION,
+ * the `||` fallback never fires, and the warning splices native-code source into
+ * its own text. A `Map` has no prototype keys, so the fallback covers every value
+ * that is not one of these three.
+ *
+ * The `repo` clause deliberately does NOT claim a live checkout. Rung 3 is an
+ * unconditional fallback rather than a checkout probe (see
+ * {@link resolveDocsLocation}), so it is also where a published install with no
+ * bundled `resources/` lands, and there the "checkout" does not exist and the
+ * corpus is empty.
+ */
+const SERVED_CLAUSE = new Map([
+  ['app', "The docs below come from this app's own copy, so they match it; update the server so its TOOLS match too."],
+  ['bundled', "The docs below are the server's own older snapshot, not this app's copy."],
+  ['repo', "The docs below are whatever this server resolved locally, not this app's copy."],
+]);
+
+/**
+ * The staleness warning, or `null` when there is nothing to warn about.
+ *
+ * Fires only when the app's installed `@webjsdev/mcp` is strictly NEWER than the
+ * running server's. Equal or lower is silent: a newer server reading an older app
+ * is the ordinary shape and is not a defect. It warns rather than failing,
+ * because a read-only knowledge tool that refuses to answer sends the agent back
+ * to its training data, which is the thing the caveat exists to correct.
+ *
+ * Two things the wording is careful about, because the obvious phrasings are both
+ * wrong:
+ *
+ * - It does NOT name a global install as the thing to update. Nothing here can
+ *   observe how the server was started, and the shipped configurations are an
+ *   `npx @webjsdev/mcp` (whose staleness is a package cache) and `webjs mcp`
+ *   (whose staleness is `@webjsdev/cli`'s own dependency), neither of which a
+ *   `npm i -g` would fix.
+ * - It does NOT promise the docs below are the app's. The warning's probe is the
+ *   app's `package.json`, while the corpus rung's probe is that install's
+ *   `resources/references`, and the two can disagree: a workspace-linked or
+ *   otherwise resources-less install has a manifest to read but no corpus to
+ *   serve, so the corpus falls through to the server's older snapshot. That case
+ *   gets an extra clause naming what was actually served, rather than a claim
+ *   that contradicts the corpus line printed directly beneath it.
+ *
+ * @param {object} deps
+ * @returns {Promise<string | null>}
+ */
+async function staleWarning(deps) {
+  const server = deps.serverVersion;
+  // '0.0.0' is the sentinel both entry points fall back to when they cannot read
+  // their own manifest, so it means "unknown", not "older than everything".
+  if (!server || server === '0.0.0') return null;
+  const app = await readAppMcpVersion(deps.appDir, deps);
+  if (!app || compareVersions(app, server) <= 0) return null;
+  const served = SERVED_CLAUSE.get(deps.corpusSource) || "The docs below may not be this app's copy.";
+  return (
+    `Warning: this MCP server is @webjsdev/mcp@${server}, but this app has @webjsdev/mcp@${app}, ` +
+    `so the server may be stale. ${served} ` +
+    'Update whichever copy runs this server: a global install (npm i -g @webjsdev/mcp@latest, ' +
+    'or bun add -g @webjsdev/mcp), the package cache behind npx @webjsdev/mcp, ' +
+    '@webjsdev/cli when the server is started as webjs mcp, or the checkout it runs from.'
+  );
+}
+
 /**
  * A doc's logical name from its filename: `lit-muscle-memory-gotchas.md` ->
  * `lit-muscle-memory-gotchas`. The `AGENTS.md` contract keeps its own name.
@@ -191,6 +387,8 @@ export function sectionByHeading(md, headingRe) {
 export async function initText(deps) {
   let agents = '';
   try { agents = await deps.readFile(deps.agentsPath, 'utf8'); } catch { agents = ''; }
+  const corpus = await corpusLine(deps);
+  const warning = await staleWarning(deps);
   const execModel = sectionByHeading(agents, /^##\s+Execution model/im);
   const invariants = sectionByHeading(agents, /^##\s+Invariants/im);
 
@@ -217,6 +415,11 @@ export async function initText(deps) {
   const parts = [
     '# webjs: read first',
     '',
+    // Provenance first, so an agent reading a months-old global install sees
+    // which docs it is holding before it reads a word of them (#1319).
+    ...(warning ? [warning, ''] : []),
+    corpus,
+    '',
     router,
     '',
     execModel || '(execution-model section unavailable)',

package/src/mcp.js

@@ -50,25 +50,46 @@ const RESERVED_CONFIG = new Set(['method', 'cache', 'tags', 'invalidates', 'vali
  * into an agent-friendly shape. Descriptions are crisp so a model picks the
  * right tool without reading source.
  */
+/**
+ * The `appDir` property, shared by every tool that is scoped to one app.
+ *
+ * `init` and `docs` carry it too, not just the introspection tools: the docs
+ * corpus is resolved from the app being asked about (#1319), so a tool that did
+ * not ADVERTISE `appDir` could never receive one from a conforming client, and
+ * the app-corpus rung would be reachable only from hand-written JSON-RPC.
+ */
+const APPDIR_PROP = {
+  type: 'string',
+  description: 'App directory to introspect. Defaults to the server cwd.',
+};
+
 /** The shared input schema for the introspection tools: an optional appDir override. */
 const APPDIR_SCHEMA = {
+  type: 'object',
+  properties: { appDir: { ...APPDIR_PROP } },
+  required: [],
+};
+
+/** `init` takes only the optional appDir, which selects whose docs corpus it reports. */
+const INIT_SCHEMA = {
   type: 'object',
   properties: {
     appDir: {
-      type: 'string',
-      description: 'App directory to introspect. Defaults to the server cwd.',
+      ...APPDIR_PROP,
+      description: "App directory whose docs corpus to read. Defaults to the server cwd.",
     },
   },
   required: [],
 };
 
-/** `init` takes no input. */
-const INIT_SCHEMA = { type: 'object', properties: {}, required: [] };
-
-/** `docs` takes an optional topic OR a free-text query. */
+/** `docs` takes an optional topic OR a free-text query, plus the optional appDir. */
 const DOCS_SCHEMA = {
   type: 'object',
   properties: {
+    appDir: {
+      ...APPDIR_PROP,
+      description: "App directory whose docs corpus to read. Defaults to the server cwd.",
+    },
     topic: {
       type: 'string',
       description: 'A doc name (e.g. components, recipes, lit-muscle-memory-gotchas, AGENTS). Returns the full doc.',
@@ -500,22 +521,46 @@ export async function runMcpServer(opts) {
   const runners = makeToolRunners(deps);
 
   // The docs corpus deps for the knowledge layer (#376): resources / prompts /
-  // init / docs. Injectable for tests; otherwise resolved from the bundled
-  // (published) or repo-root (dev) docs and node fs.
-  let docsDeps = opts.docsDeps;
-  if (!docsDeps) {
-    const loc = resolveDocsLocation(import.meta.url);
+  // init / docs. Injectable for tests; otherwise resolved from the app's own
+  // installed corpus, the bundled (published) snapshot, or the repo-root (dev)
+  // docs, plus node fs.
+  //
+  // Resolved PER CALL and memoized by appDir (#1319), not once at boot. `appDir`
+  // is a per-call tool argument, so a boot-time resolution would pin the corpus
+  // to the launch directory forever and defeat the app-corpus rung for any host
+  // that overrides it. `resources/list` and `resources/read` carry no appDir in
+  // the MCP protocol, so they resolve from `cwd`, which is the same value a
+  // `tools/call` with no `appDir` argument defaults to; the surfaces can only
+  // diverge when a caller deliberately asks about a different app.
+  let docsFs = null;
+  if (!opts.docsDeps) {
     const { readFile } = await import('node:fs/promises');
     const { readdirSync, existsSync } = await import('node:fs');
-    docsDeps = {
-      docsDir: loc.docsDir,
-      agentsPath: loc.agentsPath,
-      skillPath: loc.skillPath,
-      listDir: readdirSync,
-      exists: existsSync,
-      readFile,
-    };
+    docsFs = { listDir: readdirSync, exists: existsSync, readFile };
   }
+  /** @type {Map<string, object>} */
+  const docsDepsCache = new Map();
+  /** The docs deps for one appDir. An injected `opts.docsDeps` wins for every appDir. */
+  const docsDepsFor = (dir) => {
+    if (opts.docsDeps) return opts.docsDeps;
+    const key = typeof dir === 'string' ? dir : '';
+    let built = docsDepsCache.get(key);
+    if (!built) {
+      const loc = resolveDocsLocation(import.meta.url, key);
+      built = {
+        docsDir: loc.docsDir,
+        agentsPath: loc.agentsPath,
+        skillPath: loc.skillPath,
+        corpusPath: loc.corpusPath,
+        corpusSource: loc.corpusSource,
+        appDir: key,
+        serverVersion: version,
+        ...docsFs,
+      };
+      docsDepsCache.set(key, built);
+    }
+    return built;
+  };
 
   // The `source` tool (#378): read the framework's own source from
   // node_modules/@webjsdev/*/src (no-build, so it is the real JSDoc). Roots are
@@ -581,12 +626,12 @@ export async function runMcpServer(opts) {
 
     // Knowledge layer (#376): the framework docs as MCP resources.
     if (method === 'resources/list') {
-      return rpcResult(id, { resources: listResources(docsDeps) });
+      return rpcResult(id, { resources: listResources(docsDepsFor(cwd)) });
     }
     if (method === 'resources/read') {
       const uri = ((msg && msg.params) || {}).uri;
       try {
-        const r = await readResource(docsDeps, uri);
+        const r = await readResource(docsDepsFor(cwd), uri);
         return rpcResult(id, { contents: [r] });
       } catch (e) {
         return rpcError(id, -32602, e && e.message ? e.message : String(e));
@@ -621,9 +666,9 @@ export async function runMcpServer(opts) {
       try {
         const result = isKnowledgeTool
           ? name === 'init'
-            ? await initText(docsDeps)
+            ? await initText(docsDepsFor(appDir))
             : name === 'docs'
-              ? await searchDocs(docsDeps, args)
+              ? await searchDocs(docsDepsFor(appDir), args)
               : await runSourceTool(sourceDeps, args)
           : isUiTool
             ? runUiTool(uiDeps, args)