@nifrajs/cli 2.3.0 → 2.5.0

package/src/cli.ts

@@ -89,9 +89,12 @@ Usage:
                                          nifra_run (backend), nifra_render (SSR a page), nifra_docs,
                                          nifra_example (verified snippets), nifra_scaffold (route→file),
                                          nifra_check (drift gate + fixes), nifra_levels (verification
-                                         ladder), nifra_doctor (deps + duplicate installs).
+                                         ladder), nifra_doctor (deps), nifra_explain (structured errors),
+                                         nifra_inspect (request traces), nifra_learn (guided build path).
   nifra docs-mcp [--port <n>]            Serve the PUBLIC docs MCP over HTTP (nifra_docs + nifra_example) -
                                          self-host on a VPS so any remote agent can learn nifra. Default :8787.
+  nifra learn   [<step>]                 Print the guided build-an-app path (the human view of nifra_learn):
+                                         no arg for the step index, a number for one step's goal/do/verify.
   nifra check   [--json] [--lints-only]  Gate: typecheck + lints (hand-rolled fetch(), untyped client("…"),
                                          server-only imports in routes/). Run as "done"; --json for agents;
                                          --lints-only skips tsc for a near-instant inner-loop pass.
@@ -133,9 +136,10 @@ Usage:
   nifra upgrade <version>                Run the per-release upgrade recipe for <version>: sweep every
                 [--write] [--no-verify]  matching dependency pin (preserving ^/~/exact), move removed
                 [--list] [--json]        packages, apply exact imports, then verify with nifra check.
-                                         Dry-run by default; --write applies then verifies (--no-verify
+                [--allow-downgrade]      Dry-run by default; --write applies then verifies (--no-verify
                                          to skip). --list shows available targets. Fail-closed on an
-                                         unknown version. Deterministic + idempotent.
+                                         unknown version or a rollback (--allow-downgrade overrides).
+                                         Deterministic + idempotent.
   nifra port    [--target <t>] [--json]  Portability linter: print a feature × deploy-target capability
                 [--ci] [--strict]        matrix (in-memory stores, in-process cron/WebSocket, Bun/Deno
                                          globals, node: builtins) with file:line evidence. --target auto-
@@ -150,7 +154,7 @@ Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "2.3.0"
+const CLI_VERSION = "2.5.0"
 
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v: unknown): RenderAdapter => v as RenderAdapter
@@ -532,6 +536,18 @@ async function main(): Promise<void> {
     console.log(`nifra docs MCP (HTTP) → ${server.url}`)
     return
   }
+  // `learn` prints the guided build-an-app path (the human head of `nifra_learn`). Project-independent:
+  // the path is static, so no project needs to load. `nifra learn` for the index, `nifra learn 3` for a step.
+  if (command === "learn") {
+    const { renderLearnResult } = await import("./learn.ts")
+    const stepArg = argv[1]
+    console.log(
+      renderLearnResult(
+        stepArg !== undefined && /^\d+$/.test(stepArg) ? Number(stepArg) : undefined,
+      ),
+    )
+    return
+  }
   // `check` is a pure cwd-based gate (typecheck + lint) - it must run even when the project doesn't
   // load (API-only, not built yet), so it dispatches before the eager `loadApp` below.
   if (command === "check") {
@@ -768,6 +784,7 @@ async function main(): Promise<void> {
         json: argv.includes("--json"),
         list: argv.includes("--list"),
         verify: !argv.includes("--no-verify"),
+        allowDowngrade: argv.includes("--allow-downgrade"),
       })
       if (!ok) process.exitCode = 1
     } catch (err) {

package/src/doctor.ts

@@ -10,9 +10,10 @@
  * when a monorepo would hoist it. Relative paths, runtime builtins (node core, `node:`/`bun:`, `bun`),
  * the package's own name, and tsconfig `paths` aliases are excluded - none of them are npm deps.
  */
-import { realpath, stat } from "node:fs/promises"
+import type { Dirent } from "node:fs"
+import { readdir, realpath, stat } from "node:fs/promises"
 import { builtinModules } from "node:module"
-import { dirname, join, relative } from "node:path"
+import { dirname, join, relative, sep } from "node:path"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
 
 // Runtime-provided modules that are never an npm dependency: Node core (bare + `node:` form) and Bun's
@@ -124,6 +125,10 @@ export interface DoctorResult {
   readonly findings: readonly DoctorFinding[]
   /** Packages that resolve to more than one physical install across this workspace. */
   readonly duplicateInstalls: readonly DuplicateInstallFinding[]
+  /** Workspace-linked deps whose `default`-condition artifact lags their `bun`-condition source.
+   * Advisory (never folded into `ok`): while actively editing a linked package its dist is always
+   * momentarily behind - the finding matters when a dev server starts against it. */
+  readonly staleDists: readonly StaleDistFinding[]
   /** Dependencies written by `--auto-fix` / MCP `autoFix:true`. */
   readonly fixed?: readonly DoctorAppliedFix[]
   /** Findings that were safe to report but not safe to write automatically. */
@@ -460,6 +465,156 @@ export async function collectDuplicateInstalls(
   return findings
 }
 
+/** A workspace-linked dependency whose build artifact is older than its source. */
+export interface StaleDistFinding {
+  readonly package: string
+  /** The `default`-condition artifact (what Vite's SSR runner, vitest, and node consumers load),
+   * relative to the doctor root when possible. `missing: true` means it was never built at all. */
+  readonly distFile: string
+  readonly missing: boolean
+  /** The newest source file under the package's `bun`-condition tree - the proof of staleness. */
+  readonly sourceFile: string
+  /** How far the artifact lags the newest source, in whole seconds (0 when `missing`). */
+  readonly behindSeconds: number
+}
+
+/**
+ * Resolve one condition through an export-map entry: a string is terminal; an object takes the first
+ * key that is the wanted condition or `default` (insertion order, like the runtime), skipping `types`.
+ */
+function exportTarget(entry: unknown, condition: "bun" | "default"): string | undefined {
+  if (typeof entry === "string") return entry
+  if (!isRecord(entry)) return undefined
+  for (const [key, value] of Object.entries(entry)) {
+    if (key === "types") continue
+    if (key === condition || key === "default") return exportTarget(value, condition)
+  }
+  return undefined
+}
+
+// Bounded recursive walk for the newest file under a package's source tree. The cap is a runaway
+// guard, not a tuning knob - a real `src/` is a few hundred files.
+const MAX_SOURCE_FILES = 4_096
+async function newestFileUnder(
+  dir: string,
+): Promise<{ readonly file: string; readonly mtimeMs: number } | undefined> {
+  let newest: { file: string; mtimeMs: number } | undefined
+  let seen = 0
+  const walk = async (current: string): Promise<void> => {
+    const entries: Dirent[] = await readdir(current, { withFileTypes: true }).catch(
+      () => [] as Dirent[],
+    )
+    for (const entry of entries) {
+      if (seen >= MAX_SOURCE_FILES) return
+      const path = join(current, entry.name)
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === "dist" || entry.name.startsWith("."))
+          continue
+        await walk(path)
+        continue
+      }
+      if (!entry.isFile()) continue
+      seen++
+      const s = await stat(path).catch(() => undefined)
+      if (s !== undefined && (newest === undefined || s.mtimeMs > newest.mtimeMs))
+        newest = { file: path, mtimeMs: s.mtimeMs }
+    }
+  }
+  await walk(dir)
+  return newest
+}
+
+/**
+ * Find workspace-linked dependencies whose `default`-condition artifact (`dist/…`) has fallen behind
+ * their `bun`-condition source (`src/…`).
+ *
+ * The split export map is what makes this a trap: Bun (the build, the tests, the prod binary) reads
+ * live source, while Vite's SSR runner and any node consumer read a build artifact nothing in the dev
+ * loop regenerates. `dist/` is gitignored, so the drift never shows in a diff - it surfaces as a 500
+ * INSIDE framework/shared-package code and reads like an upstream regression. npm-installed copies are
+ * immutable and skipped; only symlinked (workspace) installs can drift.
+ */
+export async function collectStaleWorkspaceDists(
+  cwd: string,
+  rootPackage: Record<string, unknown>,
+): Promise<StaleDistFinding[]> {
+  const findings: StaleDistFinding[] = []
+  const seen = new Set<string>()
+  for (const field of DEPENDENCY_FIELDS) {
+    for (const name of depNames(rootPackage, field)) {
+      if (seen.has(name)) continue
+      seen.add(name)
+      // Boundary "" - never matches a real dir, so the upward walk runs to the filesystem root and
+      // finds a hoisted copy wherever the install put it.
+      const copy = await resolvedInstalledCopy(cwd, "", name)
+      // A real (tarball) install lives under node_modules and cannot drift; only a symlink out of the
+      // tree - a workspace/link install whose realpath escapes node_modules - has a live `src`.
+      if (copy === undefined || copy.path.includes(`${sep}node_modules${sep}`)) continue
+      const meta = await readJson(join(copy.path, "package.json"))
+      const exportsMap = meta?.exports
+      if (!isRecord(exportsMap)) continue
+      // Every subpath with a bun→src / default→dist split; the root "." alone would miss the common
+      // "deep subpaths only" layout.
+      const pairs: Array<{ readonly bun: string; readonly dist: string }> = []
+      const entries = Object.keys(exportsMap).some((k) => k.startsWith("."))
+        ? Object.entries(exportsMap)
+        : ([[".", exportsMap]] as Array<[string, unknown]>)
+      for (const [, entry] of entries) {
+        const bun = exportTarget(entry, "bun")
+        const dist = exportTarget(entry, "default")
+        if (bun !== undefined && dist !== undefined && bun !== dist) pairs.push({ bun, dist })
+      }
+      if (pairs.length === 0) continue
+      // One newest-source probe per package: the bun targets share a source tree (its top directory).
+      const sourceDirs = new Set(
+        pairs
+          .map((p) => p.bun.replace(/^\.\//, "").split("/")[0])
+          .filter((d): d is string => d !== undefined && d.length > 0),
+      )
+      let newest: { file: string; mtimeMs: number } | undefined
+      for (const dir of sourceDirs) {
+        const candidate = await newestFileUnder(join(copy.path, dir))
+        if (candidate !== undefined && (newest === undefined || candidate.mtimeMs > newest.mtimeMs))
+          newest = candidate
+      }
+      if (newest === undefined) continue
+      // Report the package once, anchored on its stalest (or missing) artifact.
+      let worst: StaleDistFinding | undefined
+      for (const pair of pairs) {
+        const distPath = join(copy.path, pair.dist.replace(/^\.\//, ""))
+        const distStat = await stat(distPath).catch(() => undefined)
+        const finding: StaleDistFinding | undefined =
+          distStat === undefined
+            ? {
+                package: name,
+                distFile: displayPath(cwd, distPath),
+                missing: true,
+                sourceFile: displayPath(cwd, newest.file),
+                behindSeconds: 0,
+              }
+            : distStat.mtimeMs < newest.mtimeMs
+              ? {
+                  package: name,
+                  distFile: displayPath(cwd, distPath),
+                  missing: false,
+                  sourceFile: displayPath(cwd, newest.file),
+                  behindSeconds: Math.round((newest.mtimeMs - distStat.mtimeMs) / 1000),
+                }
+              : undefined
+        if (finding === undefined) continue
+        if (
+          worst === undefined ||
+          (finding.missing && !worst.missing) ||
+          finding.behindSeconds > worst.behindSeconds
+        )
+          worst = finding
+      }
+      if (worst !== undefined) findings.push(worst)
+    }
+  }
+  return findings.sort((a, b) => a.package.localeCompare(b.package))
+}
+
 function depRecord(
   pkg: Record<string, unknown>,
   field: string,
@@ -518,7 +673,8 @@ async function inferDependencyFix(
 /** Run doctor against the project at `cwd`: diff source imports vs declared deps. */
 export async function collectDoctorResult(cwd: string): Promise<DoctorResult> {
   const pkg = await readJson(join(cwd, "package.json"))
-  if (pkg === undefined) return { ok: true, ran: false, findings: [], duplicateInstalls: [] }
+  if (pkg === undefined)
+    return { ok: true, ran: false, findings: [], duplicateInstalls: [], staleDists: [] }
 
   const scopes = await doctorPackageScopes(cwd, pkg)
 
@@ -531,11 +687,14 @@ export async function collectDoctorResult(cwd: string): Promise<DoctorResult> {
   })
   findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
   const duplicateInstalls = await collectDuplicateInstalls(cwd, pkg)
+  const staleDists = await collectStaleWorkspaceDists(cwd, pkg)
+  // `staleDists` is advisory (see DoctorResult): it never fails `ok`.
   return {
     ok: findings.length === 0 && duplicateInstalls.length === 0,
     ran: true,
     findings,
     duplicateInstalls,
+    staleDists,
   }
 }
 
@@ -639,6 +798,22 @@ export async function runDoctor(
     }
     console.log("")
   }
+  // Advisory, printed regardless of ok: a stale linked dist doesn't fail doctor, but silently eating
+  // it costs an hour of misdiagnosis when the dev server 500s inside the package.
+  if (result.staleDists.length > 0) {
+    console.log(
+      `⚠ ${result.staleDists.length} workspace-linked package(s) with a build artifact older than their source (Bun reads src, Vite SSR/node consumers read dist):\n`,
+    )
+    for (const f of result.staleDists) {
+      console.log(
+        f.missing
+          ? `  ${f.package} - ${f.distFile} was never built`
+          : `  ${f.package} - ${f.distFile} is ${f.behindSeconds}s behind ${f.sourceFile}`,
+      )
+      console.log(`      rebuild ${f.package}`)
+    }
+    console.log("")
+  }
   if (result.ok) {
     console.log(
       "✓ every imported package is declared and identity-sensitive installs are deduplicated",
@@ -668,6 +843,14 @@ export async function runDoctor(
       for (const copy of finding.copies) {
         console.log(`      ${copy.version} at ${copy.path} ← ${copy.importers.join(", ")}`)
       }
+      if (finding.package === "@nifrajs/core") {
+        console.log(
+          "      ↳ a second @nifrajs/core breaks module identity: `typeof backend` collapses to `any`",
+        )
+        console.log(
+          "        at `.merge()` and route-type inference silently degrades - usually that error's root cause.",
+        )
+      }
     }
     console.log(
       "\n  Align dependency ranges and reinstall from the workspace root; doctor never deletes installs.",

package/src/learn.ts

@@ -0,0 +1,152 @@
+/**
+ * The guided learn path - a SEQUENCE for building a nifra app end to end, as opposed to the random-access
+ * search of `nifra_docs`/`nifra_example`. It is deliberately thin on embedded code: each step points at the
+ * tool that produces the CORRECT, verified artifact (`nifra_scaffold` for a route, `nifra_example` for a
+ * verified snippet, `nifra_run`/`nifra_render` to see it work), so an agent walks the path by composing the
+ * existing tools rather than pasting code that can drift from the installed version.
+ *
+ * One source, two heads: `nifra_learn` (MCP) serves it to an agent as structured steps; `nifra learn` (CLI)
+ * prints the same path for a human. Add or reorder steps here and both update.
+ */
+
+export interface LearnStep {
+  /** Stable slug, e.g. `page-route`. */
+  readonly id: string
+  readonly title: string
+  /** What you will have once this step is done. */
+  readonly goal: string
+  /** How to do it - prefer directing to the tool that emits the correct artifact over inline code. */
+  readonly do: string
+  /** How to confirm it worked. */
+  readonly verify: string
+  /** The `nifra_*` tools that carry out this step. */
+  readonly tools: readonly string[]
+  /** A `nifra_docs`/`nifra_example` query for going deeper. */
+  readonly seeAlso?: string | undefined
+}
+
+export const LEARN_PATH: readonly LearnStep[] = [
+  {
+    id: "create-app",
+    title: "Create the app",
+    goal: "A running nifra dev server with one page route.",
+    do: "Scaffold a new project with `npm create nifra@latest`, pick your framework adapter (React/Solid/Vue/Svelte/Preact), then `npm run dev`.",
+    verify: "The dev server prints a localhost URL and the default page renders.",
+    tools: ["nifra_context"],
+    seeAlso: "project structure routes backend",
+  },
+  {
+    id: "page-route",
+    title: "Add a page route",
+    goal: "A second page, server-rendered, reachable by URL.",
+    do: "Ask nifra_scaffold for the path (e.g. /about) - it returns the exact `routes/` file and a contract-correct page stub. File-based: `routes/about.tsx` serves `/about`.",
+    verify: "nifra_render /about returns the rendered HTML.",
+    tools: ["nifra_scaffold", "nifra_render"],
+    seeAlso: "page routes file-based routing layouts",
+  },
+  {
+    id: "loader",
+    title: "Load data for a page",
+    goal: "A page whose data is fetched on the server before render.",
+    do: "Export a `loader` from the route and read its result in the component. Get the exact shape from nifra_example ('loader').",
+    verify: "nifra_render the page and confirm the loaded data is in the HTML.",
+    tools: ["nifra_example", "nifra_render"],
+    seeAlso: "loader server data page",
+  },
+  {
+    id: "api-route",
+    title: "Add a typed API route",
+    goal: "A backend endpoint with a typed request/response contract.",
+    do: "Add the route to `backend.ts` with an @nifrajs/schema body/query/response schema. nifra_context shows the resulting contract and the exact typed-client call form.",
+    verify:
+      "nifra_run { method, path, body } and check the status + parsed body; nifra_check confirms the contract typechecks.",
+    tools: ["nifra_context", "nifra_run", "nifra_check"],
+    seeAlso: "api route schema validation backend",
+  },
+  {
+    id: "typed-client",
+    title: "Call the API, fully typed",
+    goal: "The page calls the API through the compile-time typed client - no hand-written client twin.",
+    do: "Use @nifrajs/client against the backend type. The call form is exactly what nifra_context prints for that route; a drifted call is a compile error, not a runtime surprise.",
+    verify: "nifra_check passes; nifra_run the page path and see the data flow end to end.",
+    tools: ["nifra_context", "nifra_check", "nifra_run"],
+    seeAlso: "typed client treaty end-to-end types",
+  },
+  {
+    id: "protect",
+    title: "Protect a route",
+    goal: "A route that requires an authenticated session.",
+    do: "Wire @nifrajs/auth (or @nifrajs/better-auth) and gate the route. nifra_example ('protected route') has the verified pattern; nifra_assure reports whether the gate is actually enforced.",
+    verify:
+      "nifra_run the route unauthenticated (expect 401/redirect) and authenticated (expect 200); nifra_assure shows the enforcement evidence.",
+    tools: ["nifra_example", "nifra_assure", "nifra_run"],
+    seeAlso: "auth session protected route better-auth",
+  },
+  {
+    id: "background-work",
+    title: "Do work in the background",
+    goal: "A request that enqueues a job instead of blocking on slow work.",
+    do: "Define a job with @nifrajs/jobs and enqueue it from a route. nifra_example ('job') has the shape; nifra_inspect shows the enqueue landing on the dev server.",
+    verify:
+      "nifra_run the route, then nifra_inspect the dev server to see the request completed fast and the effect fired.",
+    tools: ["nifra_example", "nifra_run", "nifra_inspect"],
+    seeAlso: "jobs queue background enqueue",
+  },
+  {
+    id: "ship",
+    title: "Build and deploy",
+    goal: "A production build served by your chosen runtime.",
+    do: "Pick an adapter (@nifrajs/node, @nifrajs/workers, @nifrajs/deno, or a static/Vercel target) and run the production build. nifra_levels shows what the app already proves before you ship.",
+    verify:
+      "The build completes and the artifact serves the app; nifra_check + nifra_levels are green.",
+    tools: ["nifra_levels", "nifra_check"],
+    seeAlso: "deploy build adapters node workers deno",
+  },
+]
+
+/** The compact index: numbered steps with their goal, plus how to drill into one. */
+function renderIndex(): string {
+  const lines = LEARN_PATH.map((step, i) => `${i + 1}. ${step.title} - ${step.goal} [${step.id}]`)
+  return [
+    `nifra learn path (${LEARN_PATH.length} steps). Call nifra_learn with step: N for the detail of step N.`,
+    "",
+    ...lines,
+  ].join("\n")
+}
+
+/** One step's full detail, with a pointer to the next. */
+function renderStep(step: LearnStep, index: number): string {
+  const parts = [
+    `Step ${index + 1}/${LEARN_PATH.length}: ${step.title}  [${step.id}]`,
+    "",
+    `Goal:   ${step.goal}`,
+    `Do:     ${step.do}`,
+    `Verify: ${step.verify}`,
+    `Tools:  ${step.tools.join(", ")}`,
+  ]
+  if (step.seeAlso !== undefined) {
+    parts.push(`See:    nifra_docs / nifra_example "${step.seeAlso}"`)
+  }
+  const next = LEARN_PATH[index + 1]
+  parts.push(
+    "",
+    next !== undefined
+      ? `Next:   step ${index + 2} (${next.title})`
+      : "Done - you have shipped a nifra app.",
+  )
+  return parts.join("\n")
+}
+
+/**
+ * Render the learn path. No `step` (or an out-of-range one) returns the index; a valid 1-based `step`
+ * returns that step's detail. Kept pure so `nifra_learn` and `nifra learn` render identically.
+ */
+export function renderLearnResult(step?: number): string {
+  if (step === undefined) return renderIndex()
+  const index = step - 1
+  const found = LEARN_PATH[index]
+  if (found === undefined) {
+    return `No step ${step}. The path has ${LEARN_PATH.length} steps.\n\n${renderIndex()}`
+  }
+  return renderStep(found, index)
+}

package/src/mcp-app-tool.ts

@@ -0,0 +1,86 @@
+/**
+ * The `nifra_examples_app` MCP tool: nifra's verified code examples as an MCP Apps widget. It returns the
+ * examples as `structuredContent`, rendered by the {@link examplesWidget} `ui://` widget in MCP Apps hosts
+ * (ChatGPT Apps, MCPJam, Goose); text-only hosts still get the example names as plain text. Part of the
+ * public docs-MCP tool set (served by `handleMcpHttp`), so every self-host gets it from one definition.
+ * `loadExamples` is injected, so the same tool reads the corpus from disk (CLI) or a cached fetch (edge).
+ */
+import { defineMcpTool, defineMcpWidget, type McpTool } from "@nifrajs/mcp"
+import type { Example } from "./examples.ts"
+
+/** The widget: renders `structuredContent.examples` as a filterable list of example cards. */
+export const examplesWidget = defineMcpWidget({
+  uri: "ui://nifra/examples",
+  name: "nifra examples",
+  description: "Interactive browser of verified, copy-pasteable nifra code examples.",
+  head: `<style>
+    :root { color-scheme: light dark; font: 14px/1.5 system-ui, sans-serif; }
+    body { margin: 0; padding: 16px; }
+    h1 { font-size: 16px; margin: 0 0 4px; }
+    #q { width: 100%; box-sizing: border-box; padding: 6px 10px; margin: 8px 0 14px; border-radius: 6px; border: 1px solid color-mix(in srgb, currentColor 25%, transparent); background: transparent; color: inherit; font: inherit; }
+    .card { border: 1px solid color-mix(in srgb, currentColor 15%, transparent); border-radius: 10px; padding: 10px 12px; margin-bottom: 10px; }
+    .topic { font-size: 12px; opacity: .6; }
+    .name { font-weight: 600; margin: 2px 0 6px; }
+    pre { margin: 0; padding: 8px 10px; border-radius: 6px; background: color-mix(in srgb, currentColor 8%, transparent); overflow-x: auto; font: 12px/1.5 ui-monospace, monospace; }
+  </style>`,
+  html: `
+    <h1>nifra examples</h1>
+    <input id="q" placeholder="Filter examples…" />
+    <div id="list"></div>
+    <script>
+      var ALL = [];
+      function esc(s){ return String(s).replace(/[&<>]/g, function(c){ return c==="&"?"&amp;":c==="<"?"&lt;":"&gt;"; }); }
+      function paint(items){
+        document.getElementById("list").innerHTML = items.map(function(e){
+          var code = e.code.length > 600 ? e.code.slice(0, 600) + "\\n…" : e.code;
+          return "<div class='card'><div class='topic'>" + esc(e.topic) + "</div><div class='name'>" + esc(e.name) +
+            "</div><pre>" + esc(code) + "</pre></div>";
+        }).join("") || "<p style='opacity:.6'>No matching examples.</p>";
+      }
+      function render(data){ ALL = (data && data.examples) || []; paint(ALL); }
+      mcpApp.onData(render);
+      document.getElementById("q").addEventListener("input", function(ev){
+        var q = ev.target.value.toLowerCase();
+        paint(ALL.filter(function(e){ return (e.topic + e.name + e.slug).toLowerCase().indexOf(q) !== -1; }));
+      });
+    </script>
+  `,
+})
+
+/** The widget-backed tool. `loadExamples` is injected (disk on the CLI, cached fetch on the edge). */
+export function examplesAppTool(loadExamples: () => Promise<Example[] | undefined>): McpTool {
+  return defineMcpTool({
+    name: "nifra_examples_app",
+    description:
+      "Browse nifra's verified code examples as an interactive, filterable list (MCP Apps widget). Pass query to pre-filter; the widget also filters client-side.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string", description: "Pre-filter examples by keyword." } },
+      additionalProperties: false,
+    },
+    widget: examplesWidget,
+    handler: async (args) => {
+      const all = (await loadExamples()) ?? []
+      const q = ((args.query as string) ?? "").toLowerCase()
+      const matched = (
+        q
+          ? all.filter((e) => `${e.topic} ${e.name} ${e.slug} ${e.code}`.toLowerCase().includes(q))
+          : all
+      ).slice(0, 30)
+      return {
+        text:
+          matched.length === 0
+            ? "No matching examples."
+            : `${matched.length} example(s): ${matched.map((e) => e.name).join(", ")}.`,
+        structuredContent: {
+          examples: matched.map((e) => ({
+            name: e.name,
+            topic: e.topic,
+            slug: e.slug,
+            code: e.code,
+          })),
+        },
+      }
+    },
+  })
+}

package/src/mcp-docs-tools.ts

@@ -1,5 +1,5 @@
 /**
- * The two project-INDEPENDENT MCP tools - `nifra_docs` + `nifra_example` - as a single factory shared
+ * The project-INDEPENDENT MCP tools - `nifra_docs`, `nifra_example`, `nifra_types`, `nifra_learn` - as a single factory shared
  * by every transport: the project stdio server ({@link projectTools}), the CLI HTTP server
  * (`nifra docs-mcp`), and the site's Cloudflare-Pages worker (`/mcp`). The corpus source is injected as
  * loaders, so the SAME tool definitions work whether the corpus comes from disk (`Bun.file`, on the
@@ -9,6 +9,7 @@
 
 import { renderDocsResult } from "./docs-search.ts"
 import { type Example, renderExamplesResult } from "./examples.ts"
+import { renderLearnResult } from "./learn.ts"
 import type { McpTool } from "./mcp-protocol.ts"
 import { renderTypesResult, type TypeEntry } from "./types-search.ts"
 
@@ -113,5 +114,21 @@ export function docsTools(
         return renderTypesResult(corpus, name, query, clamp(limit, 1, 8, 5), full === true)
       },
     },
+    {
+      name: "nifra_learn",
+      description:
+        "Walk the guided path to build a nifra app end to end - an ORDERED sequence (create → page route → loader → typed API → typed client → auth → background jobs → deploy), not the random-access search of nifra_docs/nifra_example. Call with no args for the step index; pass `step: N` for that step's goal, how to do it (which tool emits the correct artifact), and how to verify it. Use it when scaffolding a new app or learning nifra's flow - each step composes the other nifra_* tools.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          step: {
+            type: "number",
+            description: "1-based step number to expand (omit for the index).",
+          },
+        },
+        additionalProperties: false,
+      },
+      handler: async (args) => renderLearnResult((args as { step?: number }).step),
+    },
   ]
 }

package/src/mcp-http.ts

@@ -1,8 +1,9 @@
 /**
  * The PUBLIC nifra docs MCP - Streamable-HTTP transport exposing the project-INDEPENDENT tools
- * (`nifra_docs` + `nifra_example`) so any remote AI agent can learn nifra without a local checkout.
- * Both tools read the bundled corpus (llms-full.txt / examples.json shipped in this package) and ignore
- * `cwd`, so they reuse the exact definitions from {@link projectTools} - one source, no drift.
+ * (`nifra_docs`, `nifra_example`, `nifra_types`, `nifra_learn` + the `nifra_examples_app` MCP Apps widget)
+ * so any remote AI agent can learn nifra without a local checkout. They read the bundled corpus
+ * (llms-full.txt / examples.json / types.json shipped in this package) and ignore `cwd`, so they reuse the
+ * exact definitions from {@link projectTools} - one source, no drift.
  *
  * The transport itself (body cap, CORS, JSON-RPC dispatch) lives in `@nifrajs/mcp/http`; this module is
  * the docs-specific layer over it: it supplies the bundled corpus tools and the `nifra-docs` server info.
@@ -12,28 +13,37 @@
  */
 
 import { type McpHttpOptions, respondMcpHttp as respondMcpHttpCore } from "@nifrajs/mcp/http"
-import type { McpTool } from "@nifrajs/mcp/protocol"
+import { type McpTool, UI_MIME } from "@nifrajs/mcp/protocol"
 import { loadDocsCorpus } from "./docs-search.ts"
 import { loadExamplesCorpus } from "./examples.ts"
+import { examplesAppTool, examplesWidget } from "./mcp-app-tool.ts"
 import { docsTools } from "./mcp-docs-tools.ts"
 import { loadTypesCorpus } from "./types-search.ts"
 
 export type { McpHttpOptions } from "@nifrajs/mcp/http"
 export type { Example } from "./examples.ts"
-// Re-exported so a self-host (e.g. a Cloudflare-Pages `/mcp` worker route) gets the corpus-injectable
-// tool factory + the transport core from one entry: `import { respondMcpHttp, docsTools } from "@nifrajs/cli/mcp"`.
+// Re-exported so a self-host gets the corpus-injectable tool factories + the transport core from one
+// entry: `import { respondMcpHttp, docsTools, examplesAppTool } from "@nifrajs/cli/mcp"`.
+export { examplesAppTool, examplesWidget } from "./mcp-app-tool.ts"
 export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "2.3.0"
+const VERSION = "2.5.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
-const DOCS_HEALTH =
-  "nifra docs MCP - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example."
+// Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
+const docsHealth = (tools: McpTool[]): string =>
+  `nifra docs MCP - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: ${tools
+    .map((tool) => tool.name)
+    .join(", ")}.`
 
-/** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */
+/** The project-independent tools, reading the package's bundled corpus from disk (CLI use): the text
+ * docs tools plus the `nifra_examples_app` MCP Apps widget tool. */
 export function publicDocsTools(): McpTool[] {
-  return docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus)
+  return [
+    ...docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus),
+    examplesAppTool(loadExamplesCorpus),
+  ]
 }
 
 /**
@@ -46,12 +56,20 @@ export function respondMcpHttp(
   tools: McpTool[],
   options: McpHttpOptions = {},
 ): Promise<Response> {
-  return respondMcpHttpCore(request, tools, SERVER_INFO, { health: DOCS_HEALTH, ...options })
+  return respondMcpHttpCore(request, tools, SERVER_INFO, { health: docsHealth(tools), ...options })
 }
 
-/** The CLI HTTP handler: serves the disk-backed corpus tools. (`nifra docs-mcp` / `bun run` this file.) */
+/** The CLI HTTP handler: serves the disk-backed corpus tools + registers the examples widget's `ui://`
+ * resource so MCP Apps hosts can render `nifra_examples_app`. (`nifra docs-mcp` / `bun run` this file.) */
 export function handleMcpHttp(request: Request): Promise<Response> {
-  return respondMcpHttp(request, publicDocsTools())
+  return respondMcpHttp(request, publicDocsTools(), {
+    features: {
+      resources: [examplesWidget.resource],
+      ui: { mimeTypes: [UI_MIME] },
+      instructions:
+        "nifra's own documentation, runnable examples, and API types - for building with the nifra framework. Call nifra_docs / nifra_example / nifra_types / nifra_learn to learn it without a local checkout.",
+    },
+  })
 }
 
 /**