feat: webjs source <Export> prints one export's signature and doc

.agents/skills/webjs/SKILL.md

@@ -9,7 +9,7 @@ Use this skill for end-to-end WebJs app work. It helps you choose the right laye
 
 ## Full Documentation
 
-This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). The complete hosted docs live at https://webjs.dev/docs.
+This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). To check ONE export's contract, run `npx webjs source <Export>` (for example `npx webjs source createAuth`, or `--pkg core` to narrow): it prints that export's signature and the doc comment above it from the installed package, so you read the declaration instead of the file. The MCP `source` tool does the same with `export`. Open the source file when the question is about behaviour the signature does not state. The complete hosted docs live at https://webjs.dev/docs.
 
 ## What WebJs Is
 

.claude/hooks/block-prose-punctuation.sh

@@ -306,7 +306,7 @@ fi
 # positives (a wrongly blocked write), the same tradeoff as the rules above:
 # e.g. a sentence-ending "built on webjs." is not flagged (trailing period),
 # and the `bin/webjs.js` "webjs commands:" usage banner may rarely trip it.
-webjs_cli='create|dev|start|test|check|ci|routes|elision|db|ui|doctor|types|typecheck|mcp|vendor|help|version|add|init|generate|migrate|push|studio|seed|pin|unpin|list|audit|outdated|update|view|diff|info|build'
+webjs_cli='create|dev|start|test|check|ci|routes|elision|db|ui|doctor|types|typecheck|mcp|vendor|help|version|add|init|generate|migrate|push|studio|seed|pin|unpin|list|audit|outdated|update|view|diff|info|build|source'
 
 # Scan copy: drop fenced code blocks, inline code spans, and emphasis markers
 # so a `webjs` inside code is never considered and **webjs** still matches.

AGENTS.md

@@ -580,6 +580,7 @@ webjs ci     [-f|--fail-fast] [--only <title>]... [--json] [--signoff]   # local
 webjs routes [--json] [--table] [--no-headers]   # print the route table (path / owner file / methods, #975). Default tree; --json is byte-identical to the MCP list_routes tool; --no-headers drops the --table header for piping
 webjs elision [--json] [--verify] [--routes <paths>]  # the elision verdict (#1308): every component module as elided or shipped (a shipped one naming the EVIDENCE that forced it and the module that did the forcing), every page/layout as inert / import-only / ships-whole, and every orphan class that gets no verdict at all (either no registration call, or a computed tag; the scanner matches only a literal one). --json is byte-identical to the MCP list_elision tool. --verify renders every static page route with elision on and off and diffs the observable SSR bytes (the framework's own differential guard, pointed at your app): exit 0 on parity, non-zero on a divergence OR on a corpus where nothing could be compared. It proves elision did not change the bytes you SERVE, NOT post-hydration behaviour (a wrongly dropped module is a dead click, not different bytes), so run your browser/e2e suite twice under WEBJS_ELIDE=1 / WEBJS_ELIDE=0 for that half. Dynamic routes are skipped by name; --routes adds real paths
 webjs mcp                          # read-only MCP: routes, actions (RPC hashes), components, elision (what the browser drops, and why each shipped module ships), check, ui kit
+webjs source <Export> [--pkg <name>]   # one export's signature plus its doc comment from the installed @webjsdev/* (the typed declarations, the authored JSDoc as the fallback; overloads all print; a miss names the searched packages). The MCP `source` tool's `export` argument is the same lookup. Exit 1 on a miss
 webjs doctor [--json] [--strict]   # project-health checklist (incl. a framework-resolve check that warns when @webjsdev/core can't be resolved from the app dir, the fresh-worktree-without-node_modules trap #954; a page/layout elision advisory PLUS the component-elision verdict, which warns only on an orphan (#1308); a `framework-links` check that warns when the `@webjsdev/core` entry is a symlink that DANGLES or resolves outside the checkout owning its `node_modules`, which is what an install inside a linked worktree leaves behind and what a plain resolve probe cannot see, #1442; a warning when a route module writes a `<link rel="stylesheet">` without `asset()`, #1095; a `WORKSPACE_OVERRIDES` warning when a workspace MEMBER's package.json carries `overrides` / `resolutions`, which npm and bun honour only at the workspace root, #1492); non-zero exit on a hard fail OR on a check the app gated `error`. --json emits `{ results, summary }` (results is the DoctorResult[], each carrying a stable code + its effective severity; summary counts pass/warn/fail/off), plus a third `configErrors` key on the one path where a rejected `webjs.doctor` config stops any check running; --strict additionally fails on every REMAINING warning (#975). Per-check severity is CONFIG, not a flag: `webjs.doctor.gate` maps a code to `off` / `warn` / `error` so CI gates a chosen subset (#1257)
 webjs audit  [--json]              # the dependency audit with a reviewable allowlist (#1492): runs `npm audit` or `bun audit` (nearest lockfile, so a workspace member uses the root's) and fails on any advisory at or above `webjs.audit.level` (default high) that `webjs.audit.ignore` does not list. Each ignore entry is `{ id, reason }`, the one place an accepted advisory is recorded; a malformed block exits 1 and an id the audit stopped reporting prints as stale. The scaffold's CI audit step runs it
 webjs types                        # generate .webjs/routes.d.ts (typed Route union + per-route params, #258)

packages/cli/bin/webjs.js

@@ -99,6 +99,8 @@ const USAGE = `webjs commands:
   webjs elision [--json] [--verify]               Report which component modules are elided and why each shipped one ships;
                                                   --verify diffs SSR output with elision on vs off (exits non-zero on a divergence)
   webjs mcp                                       Start the read-only MCP server (routes / actions / components / elision / check)
+  webjs source <Export> [--pkg <name>]            Print the signature plus doc comment of one export from the installed @webjsdev/*
+                                                  packages (typed declarations first, the authored JSDoc as the fallback); exit 1 on a miss
   webjs doctor [--json] [--strict]                Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout elision, component elision, un-versioned stylesheet links).
                                                   --json emits the structured results (with stable codes). --strict additionally fails on every remaining warning.
                                                   Per-check severity is CONFIG: map a code to off/warn/error under "webjs": { "doctor": { "gate": {...} } }
@@ -326,6 +328,19 @@ const HELP = {
     summary: 'Start the read-only MCP server (routes / actions / components / elision / check + a docs/source knowledge layer).',
     examples: ['webjs mcp'],
   },
+  source: {
+    usage: 'webjs source <Export> [--pkg <name>]',
+    summary: 'Print one framework export\'s signature plus the doc comment above it, read from the installed @webjsdev/* packages (the typed declarations first, the authored JSDoc when none carries a doc; every overload). The cheap way to check a contract before opening the source file.',
+    options: [
+      { flag: '--pkg <name>', description: 'Search one package only: core, server, cli, ui or intellisense.' },
+    ],
+    notesTitle: 'Exit status',
+    notes: [
+      '0 when at least one declaration printed; 1 on a miss (the message names the packages that were searched).',
+      'The read-only MCP `source` tool returns the same text for { export: "<Export>" }.',
+    ],
+    examples: ['webjs source createAuth', 'webjs source optimistic --pkg core', 'webjs source getFileStore'],
+  },
   version: {
     usage: 'webjs version',
     summary: 'Print the installed @webjsdev/cli version. Also available as webjs --version / -v.',
@@ -1968,6 +1983,29 @@ Full docs: https://webjs.dev/docs`);
         `  --from PROVIDER     CDN to resolve through. One of: ${[...SUPPORTED_PROVIDERS].join(', ')}. Default: jspm.`);
       process.exit(1);
     }
+    case 'source': {
+      // One export's signature plus its doc comment from the installed
+      // @webjsdev/* packages (#1623): the same lookup the MCP `source` tool
+      // runs for its `export` arg, so a Bash-only agent (no MCP) checks a
+      // contract for the price of the declaration instead of the whole file.
+      // Read-only: it reads the resolved package roots and loads no module.
+      const name = rest.find((a) => !a.startsWith('--'));
+      const pkgAt = rest.indexOf('--pkg');
+      const pkg = pkgAt >= 0 ? rest[pkgAt + 1] : undefined;
+      if (!name) {
+        console.error('usage: webjs source <Export> [--pkg core|server|cli|ui|intellisense]');
+        process.exit(1);
+      }
+      const { lookupExport, resolveFrameworkRoots } = await import('@webjsdev/mcp');
+      const { existsSync, readdirSync } = await import('node:fs');
+      const { readFile } = await import('node:fs/promises');
+      const roots = resolveFrameworkRoots(process.cwd(), { exists: existsSync });
+      const readdir = (d) => readdirSync(d, { withFileTypes: true }).map((e) => ({ name: e.name, isDir: e.isDirectory() }));
+      const out = await lookupExport({ roots, readFile, readdir }, name, pkg);
+      console.log(out);
+      if (!/^@webjsdev\//m.test(out)) process.exit(1);
+      break;
+    }
     case 'mcp': {
       // Read-only MCP server (#262, #415) over stdio. STDOUT is the JSON-RPC
       // channel, so nothing here may write to stdout: the data functions are

packages/cli/templates/AGENTS.md

@@ -22,10 +22,13 @@ This is what separates a working app from a broken one.
    rules (git, tests, review) are in `.agents/rules/workflow.md`; follow them
    too.
 3. **Read the framework source for exact contracts.** WebJs is 100% buildless
-   native ES modules, so the source you run IS the source you read. When you
-   need a precise API signature or behavior, open the package source under
-   `node_modules/@webjsdev/*` directly (each package ships its own `AGENTS.md`).
-   The full hosted docs are at https://webjs.dev/docs.
+   native ES modules, so the source you run IS the source you read. For one
+   export's signature and doc comment run `npx webjs source <Export>` (for
+   example `npx webjs source createAuth`); it reads the installed package and
+   prints the declaration, not the file. When you need the behaviour behind a
+   signature, open the package source under `node_modules/@webjsdev/*` directly
+   (each package ships its own `AGENTS.md`). The full hosted docs are at
+   https://webjs.dev/docs.
 
 {{PLAYBOOK}}
 

packages/mcp/AGENTS.md

@@ -77,7 +77,12 @@ src/
                          source from node_modules/@webjsdev/*/src (read-only,
                          traversal-guarded via realpath, loads no module).
                          resolveFrameworkRoots locates each package by probing
-                         the require.resolve node_modules dirs.
+                         the require.resolve node_modules dirs. lookupExport
+                         (the tool's `export` arg and `webjs source <Export>`)
+                         returns ONE export's signature plus the doc above it:
+                         the .d.ts declarations under the package root first,
+                         the authored src JSDoc as the fallback, overloads all,
+                         a miss naming the searched packages (#837).
   check-report.js        projectCheck(violations) -> { violations, summary }.
                          The shared shape returned by BOTH the MCP `check` tool
                          and `webjs check --json` (the CLI imports it from