@webjsdev/mcp 0.1.6 → 0.1.8

package/resources/references/styling.md

@@ -0,0 +1,123 @@
+# Styling
+
+## What This Covers
+
+- Tailwind-first: the strong default for pages AND light-DOM components, and the Lit reflex it counters
+- The light-DOM tag-prefix invariant when raw CSS is unavoidable
+- Extracting a repeated Tailwind bundle into a `lib/utils/ui.ts` `html` fragment (not `@apply`)
+- Design tokens: `:root` / `@theme` in the root layout
+- Light-DOM host `display: block` behaviour (and shadow hosts via `:host`)
+- When to use `static styles` (shadow DOM)
+- `position: fixed`, not `sticky`, for a pinned header (the iOS WebKit flicker)
+- Even-grid / no-reflow layout tips
+
+Read this when a task touches a class list, a `<style>`, a design token, a pinned header, or a grid/board/card layout. Sibling ref: `components.md` (light vs shadow DOM, `static styles`, host behaviour in depth).
+
+## Tailwind-first is the strong default
+
+Use Tailwind utilities for pages AND light-DOM components (the default DOM mode). Layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, and interaction states (hover/focus/active/disabled, dark mode) are all utility-expressible. Light DOM does not scope styles, so a utility class on a light-DOM element resolves against the global stylesheet exactly as it does on a page. That is why utilities are the right tool there, not an exception.
+
+### The Lit muscle-memory trap
+
+In Lit a component owns a shadow root and scopes its CSS with `static styles = css\`\``, so the reflex is to author scoped CSS or an inline `<style>` with semantic class names (`.hero`, `.card`, `.btn`) per component. In WebJs the default is light DOM, which does NOT scope. A `css` block does nothing without `static shadow = true` (the framework warns at runtime), and an inline `<style>` with bare semantic class names leaks those names into the global namespace. Reach for Tailwind utilities instead. When the same bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment (below), NOT a CSS class.
+
+### The custom-CSS allowlist
+
+Reserve raw CSS for what utilities genuinely cannot express. This is the exhaustive list, anything outside it should be a utility or a `lib/utils/ui.ts` helper:
+
+- design-token `:root` + `@theme` definitions (palette, fonts, fluid type scale, motion durations, declared once in the root layout),
+- `@property` animated custom properties paired with `@keyframes`,
+- `::-webkit-scrollbar` and `scrollbar-color` (no utility surface),
+- `prefers-reduced-motion` blocks,
+- complex `color-mix()` or gradient effects a utility cannot spell.
+
+When custom CSS IS unavoidable inside a light-DOM component, the tag-prefix invariant holds (every class selector is prefixed with the component tag). Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`\``, the right home for scoped CSS. The Tailwind-first steer is about the LIGHT-DOM default, not shadow DOM.
+
+## DRY via a JS helper, not `@apply`
+
+When the same Tailwind bundle repeats across 2+ places, extract it into a helper in `lib/utils/ui.ts` that returns an `html` fragment (SSR-time, no client runtime, output identical to inline classes):
+
+```ts
+import { html } from '@webjsdev/core';
+
+/** `● label` kicker: small caps, accent colour, above headings. */
+export function rubric(label: string, mb: 'sm' | 'md' = 'md') {
+  const mbCls = mb === 'sm' ? 'mb-3' : 'mb-4';
+  return html`
+    <span class="block font-mono text-[11px] leading-none font-semibold tracking-[0.2em] uppercase text-primary ${mbCls}">● ${label}</span>
+  `;
+}
+```
+
+```ts
+// app/blog/[slug]/page.ts
+import { rubric } from '#lib/utils/ui.ts';
+
+export default function Post({ params }) {
+  return html`${rubric('post')}<h1 class="font-serif ...">${title}</h1>`;
+}
+```
+
+| Repeats | Action |
+|---|---|
+| Once | Inline the classes. |
+| 2 to 3 times, identical | Extract to `lib/utils/ui.ts`. |
+| Varies by 1 to 2 props | Extract with a small parameter (`mb: 'sm' \| 'md'`). |
+| Radically different per call site | Keep inline, do not force-fit. |
+
+Avoid `@apply`: it hides which utilities a class uses and creates a second source of truth. A JS helper keeps the bundle visible at the definition site, composes with conditional classes and active states, and runs at SSR time.
+
+## Design tokens
+
+The default stack is a static compiled Tailwind stylesheet (`css:build` compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off) plus `@theme` design tokens (palette, fonts, fluid type, motion durations) declared once in the root layout. Consume them as utility classes (`text-foreground`, `bg-card`, `font-serif`, `duration-fast`). If you wire your own theme switch, drive BOTH signals on `<html>` (the `data-theme` attribute for the app palette blocks AND the `.dark` class for the `@webjsdev/ui` kit), or half the UI renders stale tokens. Verify dark mode in a real browser, light mode passing proves nothing about dark.
+
+## Light-DOM host display, and shadow hosts
+
+A custom element is `display: inline` in plain CSS, which collapses a component used as a block container to its content size. WebJs marks every LIGHT-DOM host `data-wj-host` and defaults it to `display: block` via one head rule in a low-priority cascade layer (`@layer webjs-host { :where([data-wj-host]) { display: block } }`), so a container component does not collapse. The layer keeps it overridable: any author style INCLUDING a Tailwind utility (`class="flex"`, `grid`, `hidden`) wins over it, and `[hidden]` still hides the host so `?hidden=${cond}` works. Opt into an inline light component with a tag-prefixed rule (`my-badge { display: inline }`).
+
+Shadow-DOM hosts are NOT marked (a document rule would override the shadow tree's own `:host`), so a shadow component sets its host display the idiomatic way in `static styles`:
+
+```ts
+static styles = css`:host { display: block }`;   // a shadow host with no :host display stays inline
+```
+
+**Size the HOST, not just an inner wrapper.** The host custom element is the box the parent lays out. A host that is a flex/grid item in a centering parent (`flex justify-center`, `grid place-items-center`) is sized to its content unless it carries width itself. Put the sizing classes on the host (`w-full max-w-[400px]`), not only on an inner `<div>`. Symptom: a board or card renders tiny even though its inner grid says `w-full max-w-[400px]`. Fix: move the sizing onto the host.
+
+## Even grids, no reflow
+
+The reflow bug (a cell grows when it gets content while the others shrink) comes from `auto`-sized grid rows. Size the tracks explicitly so every cell is an equal fraction regardless of content:
+
+```html
+<!-- a 3x3 board whose cells stay equal and square as it fills -->
+<div class="grid gap-2 aspect-square [grid-template-columns:repeat(3,1fr)] [grid-template-rows:repeat(3,1fr)]">
+  ${cells.map((c) => html`
+    <button class="grid place-items-center min-h-0 overflow-hidden text-[clamp(1rem,8cqi,3rem)]">${c}</button>
+  `)}
+</div>
+```
+
+- `aspect-ratio` (e.g. `aspect-square`) on the CONTAINER plus `repeat(N,1fr)` columns AND rows keeps every cell an equal square that does not resize as marks are placed. Putting `aspect-square` on the CELLS is the common mistake that produces uneven rows.
+- `min-h-0` + `overflow-hidden` on a cell stops its content forcing the track taller (a grid/flex child has an implicit `min-height: auto`).
+- Size text relative to the cell (`clamp()`, container-query units `cqi`) so the glyph scales with the board rather than dictating the cell size.
+
+Verify a layout by USING it, not by glancing at the first paint. A layout bug only shows mid-interaction: play through every state (fill the board, win, reload) and confirm nothing resizes.
+
+## Pin a header with `position: fixed`, never `sticky`
+
+A `position: sticky` header (the common `sticky top-0` pattern) flickers its background for one frame on iOS WebKit (every iOS browser uses WebKit) during a client-router forward navigation. The router's scroll-to-top after the content swap drives a sticky recompute that WebKit mis-repaints. It is iOS-only (fine on desktop and Android, invisible in DevTools emulation), and neither compositor promotion (`translateZ(0)` / `will-change`) nor changing the swap paint timing fixes it. Preserving the header across nav is correct and standard, only the `sticky` positioning is the problem.
+
+The fix is `position: fixed`. A fixed header is always pinned and never does the scroll-relative recompute, so the repaint bug never fires. Because fixed leaves normal flow, reserve the header height on the content below with a single `--header-h` custom property (kept exact with a `ResizeObserver`, degrading fine with no JS):
+
+```css
+:root  { --header-h: 56px; }              /* sane SSR first-paint default */
+header { position: fixed; inset-inline: 0; top: 0; }
+body   { padding-top: var(--header-h); }
+```
+```js
+const hdr = document.querySelector('header');
+const apply = () => document.documentElement.style.setProperty('--header-h', hdr.offsetHeight + 'px');
+apply();
+new ResizeObserver(apply).observe(hdr);
+```
+
+For a dashboard, an alternative is an app-shell scroll container (a non-scrolling `100dvh` flex column with `<main>` as the internal scroller), which needs no offset but changes the scroll model.

package/resources/references/testing.md

@@ -0,0 +1,125 @@
+# Testing
+
+## What This Covers
+
+- The four test layers (unit, browser, e2e, smoke) and where each file lives.
+- The `handle()` harness from `@webjsdev/server/testing` for driving the real request pipeline against a native `Response`.
+- `webjs test` and `webjs test --browser`, plus when a browser or e2e test is REQUIRED (hydration, client router, slots, custom-element upgrade).
+- Bun cross-runtime parity for runtime-sensitive code.
+- Rendering the app and LOOKING for visual defects a static check cannot catch (a collapsed or reflowing layout).
+- Convention validation with `webjs check`.
+
+Read this when you are adding tests for a feature, deciding which layer a test belongs in, or verifying a UI or theming change. For component mount and hydration helpers see `components.md`. For testing actions and the `ActionResult` envelope see `data-and-actions.md`.
+
+## Test layers
+
+Feature folders are primary, and the test kind is a subfolder inside the feature ONLY when that kind is present. Never create an empty `browser/` or `e2e/` folder.
+
+| Kind | Location | What it does |
+|---|---|---|
+| unit + integration | `test/<feature>/<name>.test.{js,ts,mjs}` | Imports modules and asserts. No spawned process, no network. |
+| browser | `test/<feature>/browser/<name>.test.js` | Real DOM, events, shadow / light DOM, in Chromium, Firefox, and WebKit. |
+| e2e | `test/<feature>/e2e/<name>.test.{ts,mjs}` | Boots a real process and drives it over HTTP / browser / stdout. Opt in with `WEBJS_E2E=1`. |
+| smoke | `test/<feature>/smoke/<name>.test.{js,ts}` | Fast deploy-time sanity check, a subset of e2e in spirit. |
+
+Assert only on what the layer needs. A block that inspects only the HTTP response, the SSR HTML string, headers, or the importmap does NOT need a browser. Keep in the browser suite only blocks that genuinely need a DOM (live state via `page.evaluate`, hydration, client-router nav, slots, view transitions, streaming into the DOM, custom-element upgrade).
+
+## App runners (`webjs test`)
+
+```sh
+webjs test              # runtime test runner over everything not under browser/ or e2e/
+webjs test --browser    # web-test-runner against test/**/browser/**
+WEBJS_E2E=1 webjs test   # adds the e2e layer
+```
+
+`webjs test` dispatches on the runtime (`node --test` on Node, `bun test` on Bun). The scaffold's `web-test-runner.config.js` globs `test/**/browser/**/*.test.js` and is already wired, so you do not set it up.
+
+A scaffolded app has one root `test/` directory shaped the same way (feature first, kind second):
+
+```
+test/
+  auth/
+    auth.test.ts                 # signup / login / currentUser
+    browser/login-form.test.js   # only if exercising DOM
+  posts/
+    posts.test.ts
+    browser/post-editor.test.js
+```
+
+## The `handle()` harness (`@webjsdev/server/testing`)
+
+`createRequestHandler({ appDir }).handle(request)` drives the FULL request pipeline (middleware, routing, SSR, page actions, server-action RPC, auth, CSRF) and returns a native `Response`. It is the same entry the framework's own suite uses, so the most realistic way to test an app is to fire a `Request` through it and assert on the `Response`, with no spawned process and no network. `@webjsdev/server/testing` ships thin builders over that `handle()`, each a few lines over native `Request` / `Response` that reuse the REAL cookie names, header names, and wire serializer. For a browser test that needs to drive the app in a real DOM, `createBrowserTestHandler()` from `@webjsdev/server/testing` exposes the same `handle()` pipeline to the WTR Chromium session.
+
+```js
+import { createRequestHandler } from '@webjsdev/server';
+import { testRequest, invokeActionForTest, rawActionRequest, loginAndGetCookies, withSessionCookie }
+  from '@webjsdev/server/testing';
+
+const app = await createRequestHandler({ appDir: process.cwd(), dev: true });
+
+const res = await testRequest(app.handle, '/about');
+assert.equal(res.status, 200);
+assert.match(await res.text(), /About/);
+```
+
+A bare path is prefixed with a dummy origin (the pipeline reads only `pathname` and `search`); a full URL string or a pre-built `Request` also works. The optional third arg is a standard `RequestInit`.
+
+### Auth and session helpers
+
+Server-action CSRF is an Origin / `Sec-Fetch-Site` check, so a test needs no CSRF setup. `loginAndGetCookies` drives the REAL credentials login through `handle()` and captures the genuine signed session cookie, so a follow-up request can hit a protected route as the logged-in user.
+
+```js
+const gated = await testRequest(app.handle, '/dashboard');
+assert.equal(gated.status, 302);                     // -> /login
+
+const { cookies } = await loginAndGetCookies(app.handle, { email, password });
+const dash = await testRequest(app.handle, '/dashboard', withSessionCookie({}, cookies));
+assert.equal(dash.status, 200);
+```
+
+### `invokeActionForTest`: round-trip an action through the REAL endpoint
+
+```js
+// modules/posts/actions/create.server.ts exports createPost
+const out = await invokeActionForTest(app, 'modules/posts/actions/create.server.ts', 'createPost', [input]);
+```
+
+It serializes the args with the WebJs serializer exactly as the generated client stub does, POSTs them same-origin to `/__webjs/action/<hash>/<fn>`, and parses the response. Prefer this over a direct import of the action. A direct import bypasses three production concerns the endpoint enforces (the wire serializer, CSRF, and prod error sanitization), so `invokeActionForTest` catches a regression a direct import cannot see. For negative cases, `rawActionRequest(app, file, fn, args, { crossOrigin: true })` returns the raw `Response` and never throws on a non-2xx (pass `{ omitCsrf: true }` to drop the CSRF pair).
+
+## When a browser or e2e test is REQUIRED
+
+A unit test is necessary but NOT sufficient for any change to hydration, the client router, slots, or custom-element upgrade. The headline behaviour of these is a browser or e2e assertion, so ship one:
+
+- Hydration and the SSR-then-hydrate agreement.
+- Client-router navigation, form submissions through the router, prefetch.
+- Slots and light / shadow DOM projection.
+- Custom-element upgrade of the SSR'd tag.
+- Progressive soft-nav streaming (assert the fallback is live at the moment the URL advances) belongs in e2e (`WEBJS_E2E=1`).
+
+Component mount helpers (`fixture`, `ssrFixture`, `waitForUpdate`) come from `@webjsdev/core/testing`; see `components.md`.
+
+## Rendering the app and looking for UI defects
+
+A layout bug (a board that collapses, cells of unequal size, a grid that resizes as it fills) is invisible to `webjs check`, `webjs typecheck`, and a glance at the empty first paint. Static tools give no signal for a visual defect, so render the app in a real browser and look.
+
+- A browser test can measure real geometry with `getBoundingClientRect()` and FAIL on the defect. There is no framework helper (it is a few lines); write it against your component and assert its children stay the same size and do not resize as the grid fills. Ship one for any grid, board, or gallery layout.
+- Test both light AND dark mode. Light mode passing proves nothing about dark mode. Emulate dark (a `newContext({ colorScheme: 'dark' })` or the theme toggle) and inspect a component's COMPUTED `background-color` and `color`, not just the page chrome.
+- Read the screenshot. Capture `page.screenshot({ fullPage: true })` and open the PNG. White-on-white or a stray light box is obvious visually and invisible in the markup.
+
+## Bun cross-runtime parity
+
+WebJs runs on Node 24+ or Bun. The Node suite is the source of truth; an additive Bun matrix re-runs the runtime-sensitive suite under Bun to catch the long tail of cross-runtime incompatibilities (a `node:*` API Bun implements differently, a crypto or stream edge case, an error-message-format quirk).
+
+Bun parity is part of the definition of done. A change to a runtime-sensitive surface (the serializer, the `node:http` vs `Bun.serve` listener and request path, SSR / action / CSRF dispatch, streams, `node:crypto`, the TS stripper, auth / session / cors) is NOT done until you run the Bun matrix green AND add or update a `test/bun/<feature>.mjs` cross-runtime assertion. Run it with `node scripts/run-bun-tests.js` (needs `bun` on PATH).
+
+## Convention validation (`webjs check`)
+
+`webjs check` is the correctness validator. Every rule catches code that is wrong to ship (a crash, a security leak, a type-strip failure), plus the `no-scaffold-placeholder` sentinel for unreplaced scaffold content. Run it and fix every violation before considering the change done (`webjs check --json` for an agent loop, `webjs check --rules` to list the rules). It is separate from `CONVENTIONS.md`, which carries the customizable project conventions you follow by judgment.
+
+## What NOT to do
+
+- Do not recreate a top-level `test/{unit,browser,e2e}/` shape. Kind is a child of feature, never the reverse.
+- Do not create empty kind folders.
+- Do not import from another package's `test/` directory. Test code is not a public surface.
+- Do not add `.unit` / `.integration` filename suffixes. The folder tells you the kind.
+- Do not run WTR or Playwright inside a headless sandbox that lacks the transform plugins or native browser libraries. Instead, extract the reconciliation or optimistic-update logic into a pure browser-safe utility and cover it with a Node unit test.

package/resources/references/typescript.md

@@ -0,0 +1,148 @@
+# TypeScript
+
+## What This Covers
+
+- TypeScript at runtime with **no build step**: `.ts` / `.mts` is stripped in place, not compiled.
+- **Erasable syntax only** (`erasableSyntaxOnly: true`) and the exact list of banned constructs, with their allowed rewrites.
+- The **pluggable stripper** (Node 24+ built-in vs `amaro` on Bun) and how the browser gets stripped source.
+- **Full-stack type safety**: server-action types flow to the call site, `import type` crosses the `.server` boundary, plus the carrier rule.
+- **Typing pages, layouts, and route handlers** with `PageProps` / `LayoutProps` / `RouteHandlerContext` and the generated route union (`webjs types`).
+
+Read this when you are writing `.ts` in a WebJs app, hit a strip-time 500, or want typed params and hrefs. For action signatures and the serializer wire see `data-and-actions.md`. For typing reactive props see `components.md`.
+
+TypeScript is optional. JS + JSDoc gets the same call-site safety (the language server reads `@typedef` / `@param` / `@returns` identically). Add `"checkJs": true` to enforce it.
+
+## No build step: how `.ts` runs
+
+`.ts` works everywhere `.js` does, same routing conventions, same server-action behaviour. There is no user-visible `tsc` run and no build output.
+
+- **Server-side** `.ts` imports are stripped by the runtime automatically (Node exposes `process.features.typescript === 'strip'`, Bun runs `.ts` natively).
+- **Browser-bound** `.ts` requests go through the pluggable stripper on the dev server, which does whitespace replacement (every source position maps to the same output position, so stack traces stay byte-exact with no sourcemap shipped). Cached by mtime.
+
+The stripper backs onto **Node 24+'s built-in `module.stripTypeScriptTypes`** (itself SWC's WASM transform in strip-only mode) or, on **Bun**, `amaro` loaded directly (byte-identical output). Force one with `WEBJS_TS_STRIPPER=builtin|amaro`.
+
+## Erasable syntax only
+
+The stripper supports **erasable TypeScript only**: type annotations, `interface`, `type`, `declare`, generics, `import type`, `as` casts, and `satisfies`. Non-erasable syntax is rejected at strip time (a 500 naming the file), so set `erasableSyntaxOnly: true` in `tsconfig.json` to catch it as an editor squiggle first. `webjs check`'s `erasable-typescript-only` rule verifies the flag is set.
+
+Banned constructs and their erasable rewrites:
+
+```ts
+// BANNED (rejected at compile + runtime)
+enum Color { Red, Green, Blue }
+class Foo { constructor(public x: number) {} }   // parameter property
+namespace Util { export const helper = 1; }       // value namespace
+import fs = require('fs');                         // import = require
+@legacyDecorator class C {}                        // legacy decorator + emitDecoratorMetadata
+
+// ALLOWED (canonical erasable forms)
+const Color = { Red: 'Red', Green: 'Green', Blue: 'Blue' } as const;
+type Color = typeof Color[keyof typeof Color];
+
+class Foo {
+  x: number;
+  constructor(x: number) { this.x = x; }
+}
+
+const Util = { helper: 1 };
+
+import * as fs from 'fs';
+```
+
+A third-party `.ts` dependency shipping non-erasable syntax fails the same way (rare, most npm packages publish compiled `.js`). WebJs is buildless end-to-end with no bundler fallback, so keep `erasableSyntaxOnly` on and your own code never hits it.
+
+Prefer explicit `.ts` extensions in imports. A `.js` specifier pointing at a `.ts` sibling also resolves in the dev server, but explicit `.ts` is clearer.
+
+## Minimum `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noEmit": true,
+    "checkJs": true,
+    "allowJs": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "erasableSyntaxOnly": true
+  }
+}
+```
+
+`erasableSyntaxOnly: true` is the non-negotiable line. It aligns the compiler's accepted syntax with the stripper's, so violations surface as diagnostics instead of a runtime 500.
+
+## Full-stack type safety
+
+### Server actions type-check automatically
+
+Calling a server action from a client component resolves at type-check time to the action's real source file. The runtime stub swap is invisible to the checker, and the RPC serializer makes runtime match the types (`Date` stays `Date`, `Map` stays `Map`, `BigInt` stays `BigInt`; see `data-and-actions.md` for the full supported set).
+
+```ts
+// modules/posts/actions/create-post.server.ts
+export async function createPost(
+  input: { title: string; body: string },
+): Promise<ActionResult<PostFormatted>> { /* ... */ }
+
+// modules/posts/components/new-post.ts
+import { createPost } from '#modules/posts/actions/create-post.server.ts';
+const r = await createPost({ title, body });
+//        ^ Promise<ActionResult<PostFormatted>>
+if (r.success) r.data.title;   // PostFormatted.title: string
+```
+
+Class instances arrive as plain objects (prototypes and methods lost, matching React Server Actions). The opt-in `SerializableActionFn` annotation turns that silent loss into a compile error (`Serializable<T>` / `SerializableArgs` / `SerializableResult` are also exported, all types-only).
+
+### The carrier rule: `import type` across the `.server` boundary
+
+A `.server.ts` file WITHOUT `'use server'` is a server-only utility whose browser stub throws at load. But a **type-only** `import type { Row } from '#db/schema.server.ts'` is safe: the stripper erases it before it can reach the browser, so sharing a derived row type from a `.server.ts` into a shipping component is fine and is not flagged. A **value** import of that same file into a shipping module is the crash the `no-server-import-in-browser-module` check catches. So carry TYPES over the boundary with `import type`, and carry DATA over it through a `'use server'` action (whose RPC stub loads safely client-side).
+
+### Typed page / layout / route-handler props
+
+Type each routing entry with the exported helpers so a param typo is a compile error.
+
+```ts
+import type { PageProps, LayoutProps, RouteHandlerContext } from '@webjsdev/core';
+
+// Static route: params is Record<string, string>.
+export default function About({ searchParams }: PageProps) { /* ... */ }
+
+// Dynamic route: pass the route literal to narrow params.
+export default function Post({ params }: PageProps<'/blog/[slug]'>) {
+  const slug = params.slug; // typed string
+}
+
+// Layout adds children.
+export default function RootLayout({ children }: LayoutProps) { /* ... */ }
+
+// Route handler's 2nd arg.
+export async function GET(req: Request, ctx: RouteHandlerContext) {
+  return Response.json({ id: ctx.params.id });
+}
+```
+
+With no route literal (or before you generate route types), `params` is `Record<string, string>`, the runtime default. With `R` set to a generated dynamic route, `params` narrows to its exact shape (`{ slug: string }`, `{ rest: string[] }`, `{ slug?: string[] }`). These are pure types, erased at runtime.
+
+Type page metadata with the exported `Metadata` type (and `MetadataContext` for the `generateMetadata` argument), the same ergonomics as Next.js's `import type { Metadata } from 'next'`.
+
+### The generated route union (`webjs types`)
+
+Run `webjs types` to write `.webjs/routes.d.ts`, an opt-in overlay augmenting `@webjsdev/core` with one key per route in `app/`. It narrows two things at tsserver time:
+
+- The `Route` href type: `navigate('/blog/anything')` passes, `navigate('/nonexistent')` is an error. Until you generate the types, `Route` is `string` (unconstrained, non-breaking for JSDoc and un-generated apps).
+- Per-route `params`: `PageProps<'/blog/[slug]'>['params']` becomes `{ slug: string }`.
+
+```sh
+webjs types     # writes .webjs/routes.d.ts (route count printed)
+```
+
+`webjs dev` emits it at startup and re-emits after each route rebuild, so the editor always has fresh types. The file is gitignored (regenerated per machine, like Next's `.next/types`); the scaffold `tsconfig.json` already lists it in `include`. To opt in for an existing app, run `webjs types` once and add `.webjs/routes.d.ts` to `include`. This is webjs's no-build equivalent of Next 15's `typedRoutes`, achieved via interface declaration-merging rather than a bundler.
+
+### The `webjs` config block and auth user
+
+The `webjs` object in `package.json` has two typed references so a typo'd key is diagnosed instead of dropped: a JSON Schema (VS Code flags an unknown key while you edit) and the `WebjsConfig` type from `@webjsdev/core`. Type `auth()`'s session user by augmenting the `AuthUser` interface (types every `auth()` call) or by parameterising `createAuth<AppUser>(...)` (types one instance), both types-only. Un-augmented, `user` resolves to `Record<string, unknown>`.
+
+Both `@webjsdev/core` and `@webjsdev/server` ship hand-authored `.d.ts` overlays with a `types` export condition, so a `strict` + `nodenext` app resolves real types for either import with no TS7016 error. The runtime stays plain `.js` + JSDoc; the overlays cost nothing at runtime.

package/src/mcp-docs.js

@@ -4,20 +4,20 @@
  * `webjs mcp` (lib/mcp.js) started as four READ-ONLY introspection tools. This
  * module adds the second layer the Next.js MCP (`next-devtools-mcp`) showed is
  * the high-leverage one: the framework knowledge an agent needs to author
- * idiomatic webjs code, surfaced as MCP RESOURCES (the `agent-docs/*.md` corpus
+ * idiomatic WebJs code, surfaced as MCP RESOURCES (the WebJs skill references
  * plus the `AGENTS.md` contract), an `init` "read first" primer that fights the
  * React/RSC mental model, a `docs` retrieval tool, and guided-workflow PROMPTS
  * built from the recipes.
  *
  * It stays hand-rolled and ZERO-dependency (no `@modelcontextprotocol/sdk`),
- * consistent with webjs being buildless + minimal-deps. Everything here is PURE
+ * consistent with WebJs being buildless + minimal-deps. Everything here is PURE
  * 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/agent-docs` (copied
+ * 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 `agent-docs/`. {@link resolveDocsLocation} encodes that
+ * back to the repo-root skill. {@link resolveDocsLocation} encodes that
  * two-path lookup so source stays single (no committed duplicate docs).
  *
  * @module mcp-docs
@@ -33,8 +33,8 @@ const DOCS_SCHEME = 'webjs-docs://';
 /**
  * Resolve where the framework-docs corpus lives, plus the `AGENTS.md` contract
  * path. Tries the BUNDLED location first (a published `@webjsdev/mcp` ships
- * `resources/agent-docs/` + `resources/AGENTS.md` via `prepack`), then falls
- * back to the monorepo-root layout (`agent-docs/` + `AGENTS.md`) used in dev and
+ * `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).
  *
@@ -46,11 +46,20 @@ export function resolveDocsLocation(moduleUrl) {
   const pkgRoot = resolve(here, '..'); // packages/mcp/src -> packages/mcp
   const repoRoot = resolve(here, '..', '..', '..'); // -> monorepo root
 
-  const bundledDocs = join(pkgRoot, 'resources', 'agent-docs');
-  if (existsSync(bundledDocs)) {
-    return { docsDir: bundledDocs, agentsPath: join(pkgRoot, 'resources', 'AGENTS.md') };
+  const bundledRefs = join(pkgRoot, 'resources', 'references');
+  if (existsSync(bundledRefs)) {
+    return {
+      docsDir: bundledRefs,
+      agentsPath: join(pkgRoot, 'resources', 'AGENTS.md'),
+      skillPath: join(pkgRoot, 'resources', 'SKILL.md'),
+    };
   }
-  return { docsDir: join(repoRoot, 'agent-docs'), agentsPath: join(repoRoot, 'AGENTS.md') };
+  const skill = join(repoRoot, '.agents', 'skills', 'webjs');
+  return {
+    docsDir: join(skill, 'references'),
+    agentsPath: join(repoRoot, 'AGENTS.md'),
+    skillPath: join(skill, 'SKILL.md'),
+  };
 }
 
 /**
@@ -74,6 +83,7 @@ function docName(file) {
  */
 function titleFor(name) {
   if (name === 'AGENTS') return 'AGENTS.md (the framework contract + invariants)';
+  if (name === 'SKILL') return 'SKILL.md (the WebJs agent skill: how to build)';
   return name
     .split('-')
     .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
@@ -89,12 +99,15 @@ function titleFor(name) {
  * @returns {Array<{ name: string, file: string, uri: string, title: string }>}
  */
 export function catalogue(deps) {
-  const { docsDir, agentsPath, listDir, exists } = deps;
+  const { docsDir, agentsPath, skillPath, listDir, exists } = deps;
   /** @type {Array<{ name: string, file: string, uri: string, title: string }>} */
   const out = [];
   if (exists(agentsPath)) {
     out.push({ name: 'AGENTS', file: agentsPath, uri: `${DOCS_SCHEME}AGENTS`, title: titleFor('AGENTS') });
   }
+  if (skillPath && exists(skillPath)) {
+    out.push({ name: 'SKILL', file: skillPath, uri: `${DOCS_SCHEME}SKILL`, title: titleFor('SKILL') });
+  }
   let files = [];
   try { files = listDir(docsDir).filter((f) => /\.md$/i.test(f)).sort(); } catch { files = []; }
   for (const f of files) {
@@ -275,7 +288,7 @@ export async function searchDocs(deps, args) {
 
 /**
  * The guided-workflow PROMPTS, built from the recipes. Each is a single-message
- * prompt that hands the agent the canonical webjs recipe plus the invariants it
+ * prompt that hands the agent the canonical WebJs recipe plus the invariants it
  * must not break, then tells it to pull `webjs-docs://recipes` for the full set.
  * Static metadata; {@link getPrompt} fills the message text.
  */
@@ -291,7 +304,7 @@ export const PROMPTS = [
 /**
  * The canonical recipe snippet + invariant reminders for each prompt. Kept
  * compact on purpose: the prompt orients + shows the shape, then points at the
- * full `webjs-docs://recipes` resource. The shapes mirror `agent-docs/recipes.md`.
+ * full `webjs-docs://recipes` resource. The shapes mirror `.agents/skills/webjs/references/data-and-actions.md`.
  *
  * @type {Record<string, string>}
  */
@@ -417,7 +430,7 @@ export function getPrompt(name, args) {
     ? `Context: ${provided.map(([k, v]) => `${k}=${v}`).join(', ')}.\n\n`
     : '';
 
-  const text = `${argLine}${body}\n\nSee \`webjs-docs://recipes\` for the full recipe set and \`webjs-docs://AGENTS\` for the invariants.`;
+  const text = `${argLine}${body}\n\nSee \`webjs-docs://SKILL\` for the full guide (it routes to the reference for each task) and \`webjs-docs://AGENTS\` for the invariants.`;
   return {
     description: meta.description,
     messages: [{ role: 'user', content: { type: 'text', text } }],

package/src/mcp-source.js

@@ -2,7 +2,7 @@
  * The `source` tool for `webjs mcp` (#378): read-only access to the FRAMEWORK
  * source itself.
  *
- * webjs is buildless, so every app's `node_modules/@webjsdev/<pkg>/src` holds the
+ * WebJs is buildless, so every app's `node_modules/@webjsdev/<pkg>/src` holds the
  * authored JSDoc `.js`, and server-side that source runs directly. (The one built
  * artifact is the `@webjsdev/core` browser bundle in `dist/`, which this tool
  * deliberately skips: it surfaces only the authored `src/`.) That is a real
@@ -153,6 +153,13 @@ export function listSources(deps, pkgFilter) {
 export async function grepSources(deps, query) {
   const q = String(query).toLowerCase();
   if (!q) return 'Provide a non-empty `query`.';
+  // No resolvable packages means NOTHING was searched. Returning "no matches"
+  // here would read as authoritative absence when the search never ran, which
+  // is the #837 dogfood failure: an odd/shimmed node_modules layout resolved
+  // zero roots, so a real symbol looked missing and the agent lost trust.
+  if (!deps.roots.length) {
+    return 'No @webjsdev/* source is resolvable here, so NOTHING was searched (run inside a webjs app or the monorepo). This is not the same as "not found".';
+  }
   /** @type {string[]} */
   const hits = [];
   let capped = false;
@@ -170,7 +177,10 @@ export async function grepSources(deps, query) {
       }
     }
   }
-  if (!hits.length) return `No matches for "${query}" in the @webjsdev/* source.`;
+  // Disclose the SEARCHED scope on a no-match, so "no matches" reads as a
+  // comprehensive-search result the agent can trust, not a silent gap (#837).
+  const searched = deps.roots.map((r) => r.pkg).join(', ');
+  if (!hits.length) return `No matches for "${query}" in the searched @webjsdev/* source (${searched}).`;
   if (capped) hits.push(`... (truncated at ${MAX_HITS} matches; narrow the query or read a file with \`path\`)`);
   return hits.join('\n');
 }

package/src/mcp.js

@@ -2,7 +2,7 @@
  * `webjs mcp`: a minimal, READ-ONLY Model Context Protocol server (#262).
  *
  * Exposes the live introspection surface an AI agent needs while editing a
- * webjs app (the route table, registered server actions with their RPC
+ * WebJs app (the route table, registered server actions with their RPC
  * endpoints, registered custom-element tags, and the structured `webjs check`
  * violations) over MCP's stdio transport. Every tool REUSES an existing
  * `@webjsdev/server` data function and MUTATES NOTHING. The prior art is
@@ -14,7 +14,7 @@
  * to stdout. STDOUT IS THE PROTOCOL CHANNEL, so this module writes ONLY
  * JSON-RPC frames there and routes every diagnostic to stderr. A malformed
  * input line is answered with a JSON-RPC parse error and never crashes the
- * loop. Hand-rolled with zero new dependency (webjs is buildless +
+ * loop. Hand-rolled with zero new dependency (WebJs is buildless +
  * minimal-deps).
  *
  * @module mcp
@@ -417,7 +417,7 @@ function rpcError(id, code, message) {
 }
 
 /**
- * Run the read-only webjs MCP server over the given streams. Reads
+ * Run the read-only WebJs MCP server over the given streams. Reads
  * newline-delimited JSON-RPC from `stdin`, writes one response line per request
  * to `stdout`, and logs diagnostics to `stderr` ONLY (stdout is the protocol
  * channel). Resolves when stdin ends (clean shutdown).
@@ -470,6 +470,7 @@ export async function runMcpServer(opts) {
     docsDeps = {
       docsDir: loc.docsDir,
       agentsPath: loc.agentsPath,
+      skillPath: loc.skillPath,
       listDir: readdirSync,
       exists: existsSync,
       readFile,