@webjsdev/mcp 0.1.17 → 0.1.19

package/README.md

@@ -1,9 +1,9 @@
 # @webjsdev/mcp
 
-The webjs **Model Context Protocol server** for AI coding agents. A read-only
+The WebJs **Model Context Protocol server** for AI coding agents. A read-only
 MCP server (newline-delimited JSON-RPC 2.0 over stdio) that gives an agent the
-live introspection surface plus the framework knowledge layer it needs while
-editing a webjs app.
+WebJs brief, the live introspection surface, and the framework source it needs
+while editing a WebJs app.
 
 ## Run it
 
@@ -19,114 +19,41 @@ no install:
 }
 ```
 
-Every webjs scaffold wires this entry automatically. `webjs mcp` (the CLI
+Every WebJs scaffold wires this entry automatically. `webjs mcp` (the CLI
 subcommand) delegates to this same server, so both routes run identical code.
 
 ## What it exposes
 
+- **`init` tool**: the WebJs brief, the short list of what differs from Next.js
+  App Router routing and Lit components, plus what each other tool is for.
+  WebJs is designed so Lit and Next.js habits produce correct code, and where
+  one cannot, `webjs check` and the runtime refuse it with the fix in the
+  message, so the brief is the whole of the agent-facing documentation. The
+  human docs live at https://webjs.dev/docs. `init` prepends a warning when the
+  app's installed `@webjsdev/mcp` is strictly newer than the running server's,
+  naming every way the server may have been started (a global install, the
+  `npx` package cache, `@webjsdev/cli` behind `webjs mcp`, or a checkout).
 - **Introspection tools** (read-only, scoped to an `appDir`): `list_routes`,
   `list_actions` (RPC endpoints plus the full data contract: HTTP verb, cache
   config, and boolean flags for tags/invalidates/validate/middleware; reserved
   config exports are excluded from the callable-action list), `list_components`,
-  `list_elision` (the display-only elision verdict: which component modules the
-  browser never downloads, the evidence behind each one that ships, every
-  page/layout as inert / import-only / shipped, and any orphan class that gets
-  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 (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).
+  `check` (the structured `webjs check` violations, each with its fix). Each
+  projects an existing `@webjsdev/server` data function and mutates nothing.
 - **`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
-  helper signatures, paste-ready structural example, a11y header, and deps (pass
-  `name`). Kit-scoped (not `appDir`-scoped); shares one projector with
-  `webjsui view`.
-
-## Which docs you get
-
-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:
-
-```json
-{
-  "package": "@webjsdev/mcp",
-  "version": "0.1.12",
-  "sha": "e5806e2400000000000000000000000000000000",
-  "copiedAt": "2026-08-08T09:14:22.031Z"
-}
-```
-
-`sha` is the full commit the docs were copied from, so it resolves straight to a
-GitHub diff. Every field is `null` rather than a plausible-looking default when
-it cannot be established, so a consumer can always tell a real answer from no
-answer: `sha` when the source tree is not itself a git checkout root, and
-`package` / `version` when the manifest cannot be read. None of those fails the
-publish. A dev checkout has no bundle and so no stamp.
-
-The SHA is deliberately refused when the tree merely SITS inside some other
-checkout, because `git rev-parse` walks up to an ancestor and would otherwise
-report an unrelated repository's HEAD as the commit these docs came from. That
-answer is a well-formed SHA, so nothing downstream could catch it.
+  `node_modules/@webjsdev/*/src` (read-only, traversal-guarded). Pass `export`
+  for one export's signature plus doc comment, the cheapest way to check a
+  contract.
+- **`ui` tool**: the `@webjsdev/ui` kit. With no args it returns the
+  component inventory plus the block and chart NAMES grouped by category (a
+  block is a ready-made view you install and then edit: a login or signup
+  page, a sidebar shell, a dashboard, a chart). `type` (`ui` / `block` /
+  `chart` / `all`) and `category` (`login`, `sidebar`, `area`, ...) list the
+  matches with one-line descriptions. `name` returns one component's helper
+  signatures, paste-ready structural example, a11y header and deps, or one
+  block's description, dependencies, install command
+  (`npx @webjsdev/ui add <name>`) and files with their targets; `source: true`
+  adds a block's sources. Everything it returns is baked plain Tailwind, never
+  a `cn-*` name, and a test caps the no-args payload size. Kit-scoped (not
+  `appDir`-scoped); shares one projector with `webjsui view`.
 
 STDOUT is the JSON-RPC channel; every diagnostic goes to stderr.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "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.",
+  "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 the WebJs brief, live app introspection over routes, actions, components, and convention checks, and the framework source.",
   "bin": {
     "webjs-mcp": "bin/webjs-mcp.js"
   },
@@ -21,12 +21,11 @@
   "files": [
     "bin",
     "src",
-    "README.md",
-    "resources"
+    "README.md"
   ],
   "dependencies": {
-    "@webjsdev/server": "^0.8.0",
-    "@webjsdev/ui": "^0.3.9"
+    "@webjsdev/server": "^0.10.0",
+    "@webjsdev/ui": "^0.5.0"
   },
   "publishConfig": {
     "access": "public"
@@ -48,9 +47,5 @@
   ],
   "engines": {
     "node": ">=24.0.0"
-  },
-  "scripts": {
-    "prepack": "node scripts/copy-mcp-resources.js",
-    "postpack": "node scripts/clean-mcp-resources.js"
   }
 }

package/src/brief.js

@@ -0,0 +1,52 @@
+/**
+ * The WebJs brief: the whole of what an agent needs to know beyond its Lit and
+ * Next.js training data. Lit and Next habits are meant to produce correct WebJs
+ * code, and where one cannot, `webjs check` and the runtime refuse it with the
+ * fix in the message, so the agent-facing docs are this brief and nothing more.
+ *
+ * Single source. The MCP `init` tool returns it, and the root `AGENTS.md` plus
+ * the scaffold's `packages/cli/templates/AGENTS.md` carry it VERBATIM under the
+ * `## The WebJs brief` heading. `test/repo-health/brief-parity.test.mjs`
+ * asserts all three agree, so edit it here and paste it there.
+ *
+ * @module brief
+ */
+
+/** The heading both `AGENTS.md` files place the brief under. */
+export const BRIEF_HEADING = '## The WebJs brief';
+
+/** The brief itself, as markdown, without its heading. */
+export const BRIEF = [
+  'WebJs is a no-build full-stack framework. Write it the way you write Next.js',
+  'routing and Lit components, with the differences below.',
+  '',
+  '- Routing follows the Next.js App Router: `app/page.ts`, `layout.ts`,',
+  '  `route.ts`, `middleware.ts`, `[param]`, `[...slug]`, `(group)`,',
+  '  `loading.ts`, `error.ts`, `not-found.ts`, `metadata` and',
+  '  `generateMetadata`, and server actions.',
+  '- Components use Lit\'s APIs (`html`, `css`, reactive properties through',
+  '  `static properties` plus `declare` or the `WebComponent({ ... })` factory,',
+  '  the lifecycle, directives, context, task), imported from `@webjsdev/core`',
+  '  and its `/directives`, `/context`, `/task` and `/signals` subpaths. The base',
+  '  class is `WebComponent`. Register with `Class.register(\'my-tag\')` or',
+  '  `customElements.define`.',
+  '- Components render light DOM by default and `<slot>` works there too. Keep',
+  '  them light: page styles such as Tailwind and the UI kit do not reach into a',
+  '  shadow root. Use `static shadow = true` only when light DOM cannot work.',
+  '- TypeScript must be erasable, so no decorators and no enums.',
+  '- Server-only code and server actions live in `*.server.ts` files. With',
+  '  `\'use server\'` at the top, their exports are callable from components and',
+  '  bindable as `<form action=${fn}>`. A failed form action re-renders the page',
+  '  with its result on `actionData`.',
+  '- `cookies()`, `headers()` and `revalidatePath()` come from `@webjsdev/server`,',
+  '  and so does `createAuth()`, which is Auth.js\'s API. Files in `public/` are',
+  '  served from the site root.',
+  '- Never import `lit`, `next` or `react`.',
+  '',
+  'Before hand-writing auth, sessions, caching, rate limits, uploads, realtime or',
+  'SEO, run `npx webjs source`, which lists what WebJs provides for each need.',
+  '`npx webjs source <Export>` then prints one export\'s signature and example.',
+  'After each edit run `npx webjs check` and `npx webjs status`. The framework',
+  'source is in `node_modules/@webjsdev/*` (no build, so it is the code that',
+  'runs) and the human docs are at https://webjs.dev/docs.',
+].join('\n');

package/src/catalog.js

@@ -0,0 +1,82 @@
+/**
+ * The feature catalogue: what WebJs provides beyond the brief, grouped by what
+ * an app needs (auth, sessions, caching, uploads, realtime, ...). An agent that
+ * does not know an export's name cannot ask `source` for it, so before #1686 a
+ * feature the brief does not name (rate limiting, file storage, broadcast) was
+ * found only by reading the framework source, or hand-written instead.
+ *
+ * `npx webjs source` with no name prints it, and so does the MCP `source` tool
+ * with no arguments. Every name here resolves through `lookupExport`, so the
+ * second call (`npx webjs source <Name>`) returns the signature and example;
+ * `packages/mcp/test/catalog.test.mjs` holds that, and holds each name to be a
+ * real export of the module named for its group.
+ *
+ * Curated rather than derived: the export lists mix the app-facing surface
+ * with framework plumbing (`buildModuleGraph`, `jspmGenerate`), and a need is
+ * not a property any export carries. Add an entry when an app-facing export
+ * lands; the test fails on one that disappears.
+ *
+ * @module catalog
+ */
+
+/**
+ * @typedef {{ need: string, names: string[], note?: string }} CatalogGroup
+ * @typedef {{ module: string, groups: CatalogGroup[] }} CatalogSection
+ */
+
+/** @type {CatalogSection[]} */
+export const FEATURE_CATALOG = [
+  {
+    module: '@webjsdev/server',
+    groups: [
+      { need: 'Auth', names: ['createAuth', 'Credentials', 'GitHub', 'Google', 'AuthError'], note: "Auth.js's API: auth(), signIn(), signOut(), handlers" },
+      { need: 'Sessions and cookies', names: ['session', 'getSession', 'cookies', 'headers'] },
+      { need: 'Redirects and errors', names: ['redirect', 'permanentRedirect', 'notFound', 'forbidden', 'unauthorized'] },
+      { need: 'Caching', names: ['cache', 'revalidatePath', 'revalidateTag', 'revalidateAll'] },
+      { need: 'Rate limits and CORS', names: ['rateLimit', 'cors', 'clientIp'] },
+      { need: 'File uploads', names: ['getFileStore', 'setFileStore', 'diskStore', 'generateKey', 'signedUrl', 'verifySignedUrl'] },
+      { need: 'Realtime', names: ['broadcast'], note: 'a route.ts exporting WS handles WebSocket connections' },
+      { need: 'Streaming responses', names: ['stream', 'streamResponse', 'acceptsStream'] },
+      { need: 'Route handlers', names: ['json', 'readBody', 'route'] },
+      { need: 'SEO', names: ['sitemap', 'sitemapIndex', 'robots'] },
+      { need: 'Env validation', names: ['validateEnv'], note: 'an env.ts schema checks process.env at boot' },
+      { need: 'Server tests', names: ['testRequest', 'submitForm', 'invokeActionForTest', 'loginAndGetCookies', 'createRequestHandler'] },
+    ],
+  },
+  {
+    module: '@webjsdev/core',
+    groups: [
+      { need: 'Components', names: ['WebComponent', 'html', 'css', 'nothing', 'unsafeHTML'] },
+      { need: 'Directives', names: ['classMap', 'styleMap', 'repeat', 'map', 'when', 'choose', 'ref', 'live', 'until', 'guard', 'keyed', 'ifDefined'] },
+      { need: 'State', names: ['signal', 'computed', 'effect', 'Task', 'createContext'] },
+      { need: 'Client navigation and data', names: ['navigate', 'refreshPage', 'revalidate', 'optimistic', 'connectWS'] },
+      { need: 'Streaming and assets', names: ['Suspense', 'asset', 'cspNonce'] },
+    ],
+  },
+  {
+    module: '@webjsdev/core/testing',
+    groups: [
+      { need: 'Component tests', names: ['fixture', 'ssrFixture', 'waitForUpdate', 'click'] },
+    ],
+  },
+];
+
+/**
+ * The catalogue as the text `npx webjs source` and the MCP `source` tool print.
+ * @param {CatalogSection[]} [catalog]
+ * @returns {string}
+ */
+export function featureCatalog(catalog = FEATURE_CATALOG) {
+  const out = [
+    'What WebJs provides, by need. `npx webjs source <Name>` (or the MCP `source`',
+    'tool with `export`) prints one name\'s signature and a working example. Use',
+    'these before writing your own.',
+  ];
+  for (const section of catalog) {
+    out.push('', section.module);
+    for (const g of section.groups) {
+      out.push(`  ${g.need}: ${g.names.join(', ')}${g.note ? ` (${g.note})` : ''}`);
+    }
+  }
+  return out.join('\n');
+}

package/src/mcp-init.js

@@ -0,0 +1,139 @@
+/**
+ * The `init` tool of `webjs mcp`: the one thing an agent reads before it writes
+ * WebJs code.
+ *
+ * It returns the WebJs brief (see `brief.js`) plus a map of the server's other
+ * tools. There is no docs corpus behind it any more. Lit and Next.js habits are
+ * meant to produce correct WebJs code, and where one cannot, `webjs check` and
+ * the runtime refuse it with the fix in the message, so the brief is the whole
+ * of the agent-facing documentation. For an exact contract the agent reads the
+ * framework source, which is no-build and therefore the code that runs (the
+ * `source` tool).
+ *
+ * Pure given its injected `{ appDir, serverVersion, readFile, exists }` deps, so
+ * it is testable in-process without touching the real filesystem.
+ *
+ * @module mcp-init
+ */
+
+import { join } from 'node:path';
+
+import { BRIEF, BRIEF_HEADING } from './brief.js';
+
+/**
+ * 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).
+ *
+ * @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 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 (a globally installed server lags the app it is asked
+ * about, #1319). Equal or lower is silent. It warns rather than failing, since
+ * a stale brief and stale tools still beat no answer.
+ *
+ * It names every way the server may have been started rather than guessing one,
+ * because nothing here can observe it: a global install, the package cache
+ * behind `npx @webjsdev/mcp`, `@webjsdev/cli` when started as `webjs mcp`, or a
+ * checkout.
+ *
+ * @param {{ appDir?: string, serverVersion?: string, readFile: Function, exists?: Function }} deps
+ * @returns {Promise<string | null>}
+ */
+export 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;
+  return (
+    `Warning: this MCP server is @webjsdev/mcp@${server}, but this app has @webjsdev/mcp@${app}, ` +
+    'so the brief and the tools below may be stale. ' +
+    '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.'
+  );
+}
+
+/** What the server's other tools are for, so the agent reaches for the right one. */
+const TOOL_MAP = [
+  '## The tools on this server',
+  '',
+  '- Before hand-writing auth, sessions, caching, rate limits, uploads, realtime',
+  '  or SEO, call `source` with no arguments: it lists what WebJs provides.',
+  '- For an exact contract, call `source` with `export` set to one export name',
+  '  (its signature plus doc comment), `path` to read a framework file, or',
+  '  `query` to grep the `@webjsdev/*` source.',
+  '- To see the live app, call `list_routes`, `list_actions` and',
+  '  `list_components`.',
+  '- To validate an edit, call `check`. Every violation carries its fix.',
+  '- Before hand-writing a page, a form, a dashboard or a chart, call `ui` to',
+  '  find a ready-made block in the `@webjsdev/ui` kit.',
+].join('\n');
+
+/**
+ * The `init` tool output: an optional staleness warning, the brief, and the
+ * tool map.
+ *
+ * @param {{ appDir?: string, serverVersion?: string, readFile: Function, exists?: Function }} deps
+ * @returns {Promise<string>}
+ */
+export async function initText(deps) {
+  const warning = await staleWarning(deps);
+  return [
+    '# WebJs: read first',
+    '',
+    ...(warning ? [warning, ''] : []),
+    BRIEF_HEADING,
+    '',
+    BRIEF,
+    '',
+    TOOL_MAP,
+  ].join('\n');
+}

package/src/mcp-source.js

@@ -27,6 +27,8 @@
 
 import { createRequire } from 'node:module';
 import { join, resolve, sep, relative } from 'node:path';
+import { readdirSync, statSync } from 'node:fs';
+import { featureCatalog } from './catalog.js';
 
 /** The published framework packages whose source an agent may want to read. */
 export const FRAMEWORK_PACKAGES = ['core', 'server', 'cli', 'intellisense', 'ui'];
@@ -91,6 +93,25 @@ export function resolveFrameworkRoots(cwd, fsDeps) {
  * @param {{ readdir: (d: string) => Array<{ name: string, isDir: boolean }> }} deps
  * @returns {string[]}
  */
+/**
+ * The real directory listing `walkSource` and the source tool read, following
+ * a symlinked directory the way the module resolver does.
+ * @param {string} dir
+ * @returns {Array<{ name: string, isDir: boolean }>}
+ */
+export function listDir(dir) {
+  return readdirSync(dir, { withFileTypes: true }).map((e) => {
+    let isDir = e.isDirectory();
+    // A symlinked directory is a directory: pnpm and workspace installs link
+    // a package (or its `src`) rather than copying it, and a Dirent of a link
+    // answers isDirectory() false, which skipped everything under it (#1686).
+    if (!isDir && e.isSymbolicLink()) {
+      try { isDir = statSync(join(dir, e.name)).isDirectory(); } catch { /* dangling */ }
+    }
+    return { name: e.name, isDir };
+  });
+}
+
 export function walkSource(dir, deps) {
   /** @type {string[]} */
   const files = [];
@@ -114,21 +135,25 @@ export function walkSource(dir, deps) {
 }
 
 /**
- * No-args / `package` mode: list the resolved packages and their `src/`
- * top-level files (the entry points), so the agent has a map to grep or read.
+ * `package` mode: list the resolved packages and their `src/` top-level files
+ * (the entry points), so the agent has a map to grep or read. `readHint` is
+ * the next step the caller offers, since the MCP tool and the CLI read the
+ * listing with different commands.
  *
  * @param {{ roots: Array<{ pkg: string, root: string, src: string }>, readdir: Function }} deps
  * @param {string} [pkgFilter]
+ * @param {{ readHint?: string }} [opts]
  * @returns {string}
  */
-export function listSources(deps, pkgFilter) {
+export function listSources(deps, pkgFilter, opts = {}) {
+  const readHint = opts.readHint ?? 'Read with `source({ path })` or search with `source({ query })`.';
   const roots = pkgFilter ? deps.roots.filter((r) => r.pkg === pkgFilter) : deps.roots;
   if (!roots.length) {
     return pkgFilter
       ? `@webjsdev/${pkgFilter} is not installed/resolvable here. Resolvable: ${deps.roots.map((r) => r.pkg).join(', ') || '(none)'}`
       : 'No @webjsdev/* packages resolvable from here (run inside a webjs app or the monorepo).';
   }
-  const lines = ['webjs framework authored source (buildless; server-side this runs directly, and core ships a built browser dist/ that is excluded here). Read with `source({ path })` or search with `source({ query })`.', ''];
+  const lines = [`webjs framework authored source (buildless; server-side this runs directly, and core ships a built browser dist/ that is excluded here). ${readHint}`, ''];
   for (const r of roots) {
     const dirName = r.src.split(sep).pop(); // 'src' for most, 'lib' for cli
     let entries = [];
@@ -325,9 +350,10 @@ function declarationFrom(lines, line, isTypes) {
  * @param {{ roots: Array<{ pkg: string, root: string, src: string }>, readFile: Function, readdir: Function }} deps
  * @param {string} name an export name, e.g. `createAuth`
  * @param {string} [pkgFilter] one of the framework packages, e.g. `server`
+ * @param {boolean} [caseRetried] internal: the case-swapped retry is already this call
  * @returns {Promise<string>}
  */
-export async function lookupExport(deps, name, pkgFilter) {
+export async function lookupExport(deps, name, pkgFilter, caseRetried = false) {
   const n = String(name || '').trim();
   if (!/^[A-Za-z_$][\w$]*$/.test(n)) return 'Pass an export name (letters, digits, _ or $), e.g. `createAuth`.';
   const roots = pkgFilter ? deps.roots.filter((r) => r.pkg === pkgFilter) : deps.roots;
@@ -360,6 +386,15 @@ export async function lookupExport(deps, name, pkgFilter) {
   }
   const searched = deps.roots.map((r) => r.pkg).join(', ');
   if (!hits.length) {
+    // The name as written with another case: a convention is written lower
+    // camel (`generateMetadata`) and its type upper (`GenerateMetadata`).
+    const other = n[0] === n[0].toLowerCase() ? n[0].toUpperCase() + n.slice(1) : n[0].toLowerCase() + n.slice(1);
+    if (other !== n && !caseRetried) {
+      const cased = await lookupExport(deps, other, pkgFilter, true);
+      if (cased.startsWith('@webjsdev/')) return `"${n}" is not an export; its type is ${other}:\n${cased}`;
+    }
+    const members = await lookupMember(deps, roots, n);
+    if (members) return members;
     return `No export named "${n}" in the searched @webjsdev/* packages (${roots.map((r) => r.pkg).join(', ')}${pkgFilter ? `; resolvable: ${searched}` : ''}). Try \`query\` for a substring search, or \`path\` to read a file.`;
   }
   // The typed declarations are the answer; the JS doc is added only when the
@@ -377,10 +412,60 @@ export async function lookupExport(deps, name, pkgFilter) {
   return out.join('\n').trimEnd();
 }
 
+/**
+ * A name that is no export but a MEMBER of an exported interface or class
+ * (`actionData` on `PageProps`, `fieldErrors` on `FormActionData`). Agents look
+ * those up by the name they write (#1686: `actionData` was the most grepped
+ * term across the eval builds), so the member's doc and declaration print,
+ * headed by the type that owns it.
+ * @param {{ readFile: Function, readdir: Function }} deps
+ * @param {Array<{ pkg: string, root: string }>} roots
+ * @param {string} n
+ * @returns {Promise<string | null>}
+ */
+async function lookupMember(deps, roots, n) {
+  const memberRe = new RegExp(`^\\s+(?:readonly\\s+)?(?:static\\s+)?${n.replace(/\$/g, '\\$')}\\??\\s*[:(<]`);
+  const ownerRe = /^export\s+(?:declare\s+)?(?:abstract\s+)?(?:interface|class|type)\s+([A-Za-z_$][\w$]*)/;
+  const out = [];
+  let count = 0;
+  for (const r of roots) {
+    for (const file of walkSource(r.root, deps).filter((f) => /\.d\.(?:ts|mts|cts)$/.test(f))) {
+      let text = '';
+      try { text = await deps.readFile(file, 'utf8'); } catch { continue; }
+      if (!text.includes(n)) continue;
+      const lines = text.split('\n');
+      const rel = relative(r.root, file).split(sep).join('/');
+      for (let i = 0; i < lines.length; i++) {
+        if (!memberRe.test(lines[i])) continue;
+        let owner = null;
+        for (let j = i - 1; j >= 0; j--) {
+          const m = ownerRe.exec(lines[j]);
+          if (m) { owner = m[1]; break; }
+          if (/^\S/.test(lines[j]) && !/^\s*(?:\*|\/\/|\/\*)/.test(lines[j]) && /^(?:}|export)/.test(lines[j])) break;
+        }
+        if (!owner) continue;
+        if (++count > MAX_EXPORT_HITS) continue;
+        const decl = [];
+        for (let k = i, depth = 0; k < lines.length && decl.length < MAX_DECL_LINES; k++) {
+          decl.push(lines[k]);
+          for (const ch of lines[k]) { if (ch === '{' || ch === '(') depth++; else if (ch === '}' || ch === ')') depth--; }
+          if (depth <= 0 && /[;,]\s*$/.test(lines[k])) break;
+        }
+        out.push(`"${n}" is a member of ${owner} (@webjsdev/${r.pkg} ${rel}:${i + 1}); \`source ${owner}\` prints the whole type.`);
+        out.push(...docAbove(lines, i), ...decl, '');
+      }
+    }
+  }
+  if (!out.length) return null;
+  if (count > MAX_EXPORT_HITS) out.push(`... (${count - MAX_EXPORT_HITS} more members named "${n}"; narrow with \`package\`)`);
+  return out.join('\n').trimEnd();
+}
+
 /**
  * The `source` tool entry point. Dispatches on the args: `export` looks up one
- * export's signature and doc, `path` reads a file, `query` greps, otherwise
- * (or with `package`) lists the packages. PURE given `deps`
+ * export's signature and doc, `path` reads a file, `query` greps, `package`
+ * lists that package's entry points, and no args prints the feature catalogue
+ * (what WebJs provides, by need). PURE given `deps`
  * (`{ roots, readFile, readdir }`).
  *
  * @param {object} deps
@@ -392,5 +477,6 @@ export async function runSourceTool(deps, args) {
   if (a.export) return lookupExport(deps, a.export, a.package);
   if (a.path) return readSource(deps, a.path);
   if (a.query) return grepSources(deps, a.query);
-  return listSources(deps, a.package);
+  if (a.package) return listSources(deps, a.package);
+  return featureCatalog();
 }