@webjsdev/mcp 0.1.18 → 0.1.20

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,28 +19,30 @@ 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).
+  `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
@@ -54,87 +56,4 @@ subcommand) delegates to this same server, so both routes run identical code.
   a `cn-*` name, and a test caps the no-args payload size. 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.
-
 STDOUT is the JSON-RPC channel; every diagnostic goes to stderr.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "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.9.0",
-    "@webjsdev/ui": "^0.4.0"
+    "@webjsdev/server": "^0.10.1",
+    "@webjsdev/ui": "^0.5.1"
   },
   "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/guides.js

@@ -0,0 +1,319 @@
+/**
+ * Pattern guides: how WebJs wants a feature built, one short page per need
+ * (routing, the module layout, progressive enhancement, optimistic UI, type
+ * safety, data flow, authentication, testing, uploads). `npx webjs source <guide>` prints one,
+ * as does the MCP `source` tool given the guide's name as `export`.
+ *
+ * These are not a docs corpus (the removed `docs` tool served the whole site).
+ * Each guide is capped (under 40 lines, held by test/guides.test.mjs) and
+ * ends in actions, never prose: the exports to look up next and the docs page
+ * for the long version. Every export a guide names is checked to exist. A
+ * guide is printed only when asked for by name; nothing lists them up front.
+ *
+ * Guide names are slugs no package exports (`optimistic-ui`, not
+ * `optimistic`), so a lookup of an export never lands on a guide.
+ *
+ * @module guides
+ */
+
+/** @type {Record<string, { need: string, text: string }>} */
+export const GUIDES = {
+  routing: {
+    need: 'the app/ file conventions: pages, layouts, route.ts, middleware.ts, boundaries',
+    text: `Guide: routing (the app/ file conventions, as in the Next.js App Router)
+
+  app/page.ts                   /          default export (ctx) => html, server only
+  app/layout.ts                 wraps every page below it; only the root one writes <html>
+  app/posts/[id]/page.ts        /posts/1   params.id, or const { id } = await params
+  app/docs/[...slug]/page.ts    /docs/a/b  params.slug is a string[] ([[...slug]] matches /docs too)
+  app/(admin)/users/page.ts     /users     a (group) adds no URL segment; _folders are not routed
+  app/api/posts/[id]/route.ts   export async function GET(req: Request, { params }) {
+                                  const { id } = await params; return Response.json(...) }
+                                GET, POST, PUT, PATCH, DELETE, each returning a Response
+  app/middleware.ts             export default async function middleware(request: Request),
+                                run before every page, form post and route.ts under it;
+                                return a Response to answer, nothing to continue
+  app/admin/middleware.ts       the same for /admin and everything under it
+  middleware.ts beside app/     the app-wide one, which also sees action RPC calls
+
+Gate a section in a middleware.ts, not in a layout: a page renders before its
+layouts, and a client navigation skips the layouts the browser already has.
+
+Boundaries, the nearest one up the folders renders inside the layouts above it:
+  loading.ts      shown while the page loads
+  error.ts        a render that throws, given { error }
+  not-found.ts    notFound(), or (at the root) no route matched
+  forbidden.ts    forbidden(), a 403      unauthorized.ts  unauthorized(), a 401
+Throw them, or redirect('/login'), from a page, a layout or a form action.
+
+Metadata: export const metadata = { title, description } from a page or a
+layout, or export async function generateMetadata({ params }) for a dynamic one.
+
+Look up: npx webjs source redirect, npx webjs source notFound, npx webjs source generateMetadata
+Docs: https://webjs.dev/docs/routing`,
+  },
+
+  modules: {
+    need: 'how an app is laid out',
+    text: `Guide: modules (how a WebJs app is laid out)
+
+One folder per feature under modules/<feature>/, and thin routes:
+  modules/posts/actions/create-post.server.ts   'use server', one action per file
+  modules/posts/queries/list-posts.server.ts    server-only reads, called by pages
+  modules/posts/components/post-list.ts         Lit components (these ship)
+  modules/posts/types.ts                        types derived from the schema
+  app/posts/page.ts                             awaits a query, renders components
+  db/schema.server.ts                           every table, one defineRelations
+
+Each table goes in db/schema.server.ts with its row type beside it
+(export type Post = typeof posts.$inferSelect), and its relations in the one
+defineRelations call. modules/users/ in a fresh app is a working example of
+the whole shape: read it, then replace it with the app's own features.
+
+Next: npx webjs source progressive-enhancement (or optimistic-ui, type-safety, data-flow)
+Docs: https://webjs.dev/docs/conventions`,
+  },
+
+  'progressive-enhancement': {
+    need: 'forms that work with and without JavaScript',
+    text: `Guide: progressive-enhancement (forms that work before and after JavaScript)
+
+Bind every write to a 'use server' action, never fetch() plus a click handler:
+  <form action=\${createPost} class="group">
+    <input name="title" value=\${actionData?.values?.title ?? ''}>
+    \${actionData?.fieldErrors?.title ? html\`<p role="alert">\${actionData.fieldErrors.title}</p>\` : nothing}
+    <button class="group-aria-busy:opacity-50" type="submit">Save</button>
+  </form>
+
+- JavaScript off: the browser posts; a success that calls redirect() is a 303,
+  and a failure re-renders the page at 422 with the result on actionData.
+- JavaScript on: the client router posts the same body and applies the result
+  in place (no reload, scroll and focus kept, the form reset on success), with
+  aria-busy on the form while it is in flight.
+- Invalid input: return { success: false, fieldErrors, values, status: 422 }.
+- Several actions on one form: <button formaction=\${deletePost}>.
+
+Look up: npx webjs source ActionResult, npx webjs source PageProps
+Docs: https://webjs.dev/docs/progressive-enhancement`,
+  },
+
+  'optimistic-ui': {
+    need: 'show a write before the server confirms it',
+    text: `Guide: optimistic-ui (show a write before the server confirms it)
+
+Inside a Lit component that owns the list, seeded by its page as a property:
+  pending = optimistic(this, { source: () => this.posts, update: (rows, p) => ... });
+  onDelete(e, id) { e.preventDefault(); this.pending.add({ id }, deletePost(new FormData(e.target))); }
+
+- Keep the reducer pure (it runs on every render); mint a temp id in the handler.
+- The entry drops when the promise settles; on success write the server's row
+  into the seeded property.
+- Keep the form bound to the action (action=\${deletePost}) so it posts with
+  JavaScript off; @submit only intercepts it.
+- One value (a like, a toggle): optimistic(signal, value, () => action()).
+- Skip it when the result cannot be predicted from the input.
+
+Look up: npx webjs source optimistic (a full component example)
+Docs: https://webjs.dev/docs/optimistic-ui`,
+  },
+
+  'type-safety': {
+    need: 'one set of types from the database to the page',
+    text: `Guide: type-safety (one set of types from the database to the page)
+
+TypeScript must be erasable: no enum, decorator, value namespace or parameter
+property. Types are stripped to whitespace and nothing is compiled.
+- Rows: export type Post = typeof posts.$inferSelect beside the table;
+  inserts use typeof posts.$inferInsert. Never hand-write a row type.
+- Actions return ActionResult<Post>, and the one function is typed for a form
+  binding, an RPC call from a component and a route handler alike.
+- Pages: PageProps<'/posts/[id]'> types params from the route; actionData is a
+  failed action's result (pass its type as the second parameter).
+- Components take types with import type, which is erased, so a server
+  module never reaches the browser.
+- npx webjs types writes typed hrefs; npx webjs typecheck runs tsc.
+
+Look up: npx webjs source ActionResult, npx webjs source PageProps
+Docs: https://webjs.dev/docs/typescript`,
+  },
+
+  'data-flow': {
+    need: 'queries, actions, RPC and route handlers',
+    text: `Guide: data-flow (where server code goes and how the browser reaches it)
+
+- Reads: queries/*.server.ts with no 'use server', called from a page or a
+  layout, which run only on the server (as Next.js server components do).
+- Drizzle 1.0's db.query takes objects, not Drizzle 0.x's eq() / asc():
+    db.query.posts.findMany({ where: { userId }, orderBy: { createdAt: 'desc' }, with: { author: true } })
+  eq(), and() and lt() go in db.select().from(posts).where(...).
+- SQLite's drivers are synchronous: db.transaction((tx) => { ... }) takes a
+  sync callback whose queries end in .all(), .get() or .run() (never async).
+- Writes: actions/*.server.ts with 'use server'. A form binds one; a component
+  imports and calls it, which goes over RPC (a Date or a Map survives).
+- Public HTTP API: app/api/<name>/route.ts exporting GET, POST and the rest,
+  calling the same actions (or wrap one with route()):
+    // app/api/polls/[slug]/route.ts
+    export async function GET(_req: Request, { params }: { params: Promise<{ slug: string }> }) {
+      const poll = await findPoll((await params).slug);
+      return poll ? Response.json(poll) : Response.json({ error: 'Not found' }, { status: 404 });
+    }
+- Components never import the database or a server-only module: data arrives
+  as a property from the page, or through an action call.
+- After a write: revalidatePath('/posts') refreshes cached pages, redirect()
+  navigates, and a returned failure re-renders with its message.
+- Cache a read with cache(fn, { key, ttl, tags }) and revalidateTag(tag).
+
+Look up: npx webjs source route, npx webjs source cache, npx webjs source revalidatePath
+Docs: https://webjs.dev/docs/server-actions`,
+  },
+
+  authentication: {
+    need: 'accounts, sign-in and protected pages',
+    text: `Guide: authentication (accounts, sign-in, protected pages)
+
+createAuth is Auth.js's API, written once in a server-only module:
+  // modules/auth/auth.server.ts
+  export const { auth, signIn, signOut, handlers } = createAuth({
+    providers: [Credentials({ async authorize(c: { email: string; password: string }) {
+      const user = await findUserByEmail(c.email);   // your own query
+      if (!user || !(await verifyPassword(c.password, user.passwordHash))) return null;
+      return { id: String(user.id), email: user.email };
+    } })],
+  });
+  // app/api/auth/[...path]/route.ts
+  export const { GET, POST } = handlers;
+- Keep a password hash on users, never the password: scrypt from node:crypto
+  with a random salt, compared with timingSafeEqual.
+- Log in: a 'use server' action awaits signIn('credentials', formData,
+  { redirectTo: '/' }). A wrong password throws CredentialsSignin: catch it and
+  return { success: false, error }. Log out: await signOut({ redirectTo: '/login' }).
+- Gate pages in app/middleware.ts, not in a layout:
+    const PUBLIC = ['/login', '/signup', '/api/auth'];
+    export default async function middleware(request: Request) {
+      const { pathname } = new URL(request.url);
+      if (PUBLIC.some((p) => pathname === p || pathname.startsWith(p + '/'))) return;
+      if (!(await auth())?.user) return Response.redirect(new URL('/login', request.url), 303);
+    }
+- An action a component calls directly skips app/middleware.ts: check
+  (await auth())?.user inside it.
+- Add GitHub or Google: providers: [GitHub({ clientId, clientSecret })].
+  AUTH_SECRET signs the session; development and tests generate one.
+
+Look up: npx webjs source createAuth, npx webjs source Credentials
+Docs: https://webjs.dev/docs/auth`,
+  },
+
+  testing: {
+    need: 'server tests against a real database',
+    text: `Guide: testing (server tests against a real database)
+
+npx webjs test runs test/**/*.test.ts (node --test, or bun test on Bun) on a
+fresh migrated SQLite database, so a test never touches db/dev.db.
+- Pages and forms, through the real request handler:
+    const app = await createRequestHandler({ appDir, dev: true });
+    const res = await submitForm(app.handle, '/posts/new', { title: 'Hi' });
+    assert.equal(res.status, 303);
+- testRequest(app.handle, '/posts') for a GET or a JSON route. Carry a cookie
+  the app set into the next request:
+    const cookie = cookiesToHeader(getSetCookies(res));
+    await submitForm(app.handle, '/p/abc', { option: '1' }, { cookies: cookie });
+  loginAndGetCookies signs in with credentials and returns the same header.
+- Call a query or an action directly for its logic; an action that redirects
+  throws, so test that one through submitForm.
+- Components: npx webjs test --browser, with fixture() from @webjsdev/core/testing.
+
+Look up: npx webjs source submitForm, npx webjs source testRequest
+Docs: https://webjs.dev/docs/testing`,
+  },
+
+  uploads: {
+    need: 'attach a file to a record, store it and serve it back',
+    text: `Guide: uploads (attach a file to a record, store it and serve it back)
+
+The row keeps the storage key, never the bytes, so the table gets a
+fileKey: text() column beside the record's own fields.
+- The form: <form action=\${attachFile}> holding <input type="file" name="file"
+  accept="image/png,image/jpeg,application/pdf">. A bound form gets
+  enctype="multipart/form-data" from the renderer (writing it is harmless).
+- The 'use server' action checks the file before storing it:
+    const file = formData.get('file');
+    const fail = (msg: string) => ({ success: false as const, fieldErrors: { file: msg }, status: 422 });
+    if (!(file instanceof File) || file.size === 0) return fail('Choose a file.');
+    if (file.size > 5 * 1024 * 1024) return fail('At most 5 MB.');
+    if (!['image/png', 'image/jpeg', 'application/pdf'].includes(file.type)) return fail('An image or a PDF.');
+    const key = generateKey(file.name);   // <uuid>.<ext>, safe as a path
+    await getFileStore().put(key, file);  // streamed into .webjs/uploads
+    await db.update(documents).set({ fileKey: key }).where(eq(documents.id, id));
+- Serving: nothing serves stored files by default, so the app adds a route:
+    // app/files/[key]/route.ts
+    export async function GET(req: Request, { params }: { params: Promise<{ key: string }> }) {
+      const { key } = await params;
+      const check = verifySignedUrl(new URL(req.url), process.env.FILE_URL_SECRET!);
+      if (!check.valid || check.key !== key) return new Response('Forbidden', { status: 403 });
+      const stored = await getFileStore().get(key);
+      if (!stored) return new Response('Not found', { status: 404 });
+      return new Response(stored.body, { headers: { 'content-type': stored.contentType,
+        'x-content-type-options': 'nosniff', 'content-disposition': 'attachment' } });
+    }
+- The link, minted in a page: base is that route's path, since the default is
+  the store's /uploads/<key>, which nothing serves.
+    signedUrl(doc.fileKey, { secret: process.env.FILE_URL_SECRET!, base: '/files/' + doc.fileKey, expiresIn: 3600 })
+- file.type is what the browser claims, so keep nosniff and attachment on
+  anything a user sent. Set FILE_URL_SECRET in .env.
+
+Look up: npx webjs source signedUrl, npx webjs source getFileStore, npx webjs source generateKey
+Docs: https://webjs.dev/docs/file-storage`,
+  },
+};
+
+/**
+ * File convention names, as an agent looks them up, onto the guide that
+ * explains them. In the #1692 evals agents ran `webjs source not-found`,
+ * `route` and `middleware` and then read the router to learn the conventions.
+ * Matched case-sensitively, so a name that differs from an export only in case
+ * stays the export (`notfound` is the guide, `notFound` the function). None
+ * of these is an export: test/guides.test.mjs holds that. `route` and
+ * `middleware` are exports (the `route()` adapter, the middleware type), so
+ * they print the export with a pointer here (`conventionPointer`). The words
+ * for a file upload (`upload`, `attachments`) find the `uploads` guide.
+ * @type {Record<string, string>}
+ */
+export const GUIDE_ALIASES = Object.fromEntries([
+  'routes', 'router', 'app-router', 'file-conventions',
+  'page', 'page.ts', 'layout', 'layout.ts', 'route.ts', 'route-handler', 'route-handlers',
+  'middleware.ts', 'proxy.ts', 'not-found', 'not-found.ts', 'notfound', 'error', 'error.ts',
+  'loading', 'loading.ts', 'forbidden.ts', 'unauthorized.ts', 'global-error', 'global-error.ts',
+  'global-not-found', 'boundaries', 'dynamic-routes', 'catch-all', 'route-groups',
+].map((alias) => [alias, 'routing']).concat(
+  ['upload', 'file-upload', 'file-uploads', 'attachments', 'attachment'].map((alias) => [alias, 'uploads']),
+));
+
+/** The exports whose name is also a file convention (`route.ts`, `middleware.ts`). */
+const CONVENTION_EXPORTS = new Set(['route', 'middleware']);
+
+/**
+ * The line an export lookup appends when the name is also a file convention,
+ * so `webjs source route` (the `route()` adapter) still leads to `route.ts`.
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function conventionPointer(name) {
+  return CONVENTION_EXPORTS.has(String(name ?? '').trim())
+    ? 'For the route.ts / middleware.ts file convention: npx webjs source routing'
+    : null;
+}
+
+/**
+ * One guide's text, or null when the name is not a guide. Case and spaces are
+ * forgiven for a guide's own name (`Optimistic UI` finds `optimistic-ui`); an
+ * alias (`not-found`, `middleware.ts`, `app/page.ts`) matches as written.
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function guide(name) {
+  const raw = String(name ?? '').trim();
+  const key = raw.toLowerCase().replace(/[\s_]+/g, '-');
+  if (Object.hasOwn(GUIDES, key)) return GUIDES[key].text;
+  const alias = raw.replace(/^\.?\/?app\//, '').replace(/\.(?:m?js|mts)$/, '.ts');
+  return Object.hasOwn(GUIDE_ALIASES, alias) ? GUIDES[GUIDE_ALIASES[alias]].text : null;
+}