@nifrajs/cli 2.2.0 → 2.4.0

package/src/levels-tool.ts

@@ -1,36 +1,34 @@
 /**
- * `nifra levels` — the verification ladder, computed from gates that already exist:
+ * `nifra levels` - the verification ladder, computed from gates that already exist:
  *
- *   L0 typed contract      — `nifra check` passes (compiler-enforced frontend↔backend contract)
- *   L1 route assurance     — `nifra.assurance.ts` present and every route satisfies its policy
- *   L2 capability lockfile — capability/effect assurance passes and the lockfile is in sync
- *   L3 route manifest      — the emitted manifest hash-verifies and matches the current app
- *   L4 invariant-tested    — every route passes through an explicitly isolated executor
+ *   L0 typed contract      - `nifra check` passes (compiler-enforced frontend↔backend contract)
+ *   L1 route assurance     - `nifra.assurance.ts` present and every route satisfies its policy
+ *   L2 capability lockfile - capability/effect assurance passes and the lockfile is in sync
+ *   L3 route manifest      - the emitted manifest hash-verifies and matches the current app
+ *   L4 invariant-tested    - every route passes through an explicitly isolated executor
  *
- * A level counts only when every level below it holds — the ladder is cumulative, so "L3" is one
+ * A level counts only when every level below it holds - the ladder is cumulative, so "L3" is one
  * honest word for a whole posture. Levels are computed, never self-declared.
  */
 
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
-import { evaluateRouteAssurance } from "@nifrajs/core/assurance"
-import { type evaluateCapabilityAssurance, snapshotCapabilities } from "@nifrajs/core/capabilities"
+import type { AssuranceReport } from "@nifrajs/core/assurance"
+import { snapshotCapabilities } from "@nifrajs/core/capabilities"
 import { buildNifraManifest, parseNifraManifest } from "@nifrajs/core/manifest"
 import { type ContractTestApp, runAdversarialContract } from "@nifrajs/testing"
-import { loadAssuranceConfig } from "./assure.ts"
 import {
-  collectCapabilityProjectReport,
+  type CapabilityProjectReport,
   diffCapabilitySnapshots,
   parseCapabilityLockfile,
 } from "./capabilities-tool.ts"
-import { collectCheckResult } from "./check.ts"
 import { DEFAULT_MANIFEST_FILE } from "./manifest-tool.ts"
 
 export interface VerificationLevelStatus {
   readonly level: number
   readonly name: string
   readonly ok: boolean
-  /** Why the level does not hold — a gate failure or a missing prerequisite. Empty when ok. */
+  /** Why the level does not hold - a gate failure or a missing prerequisite. Empty when ok. */
   readonly reasons: readonly string[]
 }
 
@@ -51,10 +49,18 @@ export async function collectVerificationLevels(
   cwd: string,
   options: CollectLevelsOptions = {},
 ): Promise<VerificationLevelsResult> {
+  // The ladder is the fullest view over the one project verification: L0 is the check view, L1/L2 read
+  // the route-assurance + capability evidence the same collector already computed (no second walk), and
+  // only the ladder-specific L3 (manifest) and L4 (invariants) are evaluated here.
+  const { collectProjectVerification } = await import("./verification.ts")
+  const verification = await collectProjectVerification(cwd, {
+    ...(options.config !== undefined ? { config: options.config } : {}),
+    maxDiagnostics: 5,
+  })
   const statuses: { level: number; name: string; ok: boolean; reasons: string[] }[] = []
 
-  // L0 — typed contract (`nifra check`).
-  const check = await collectCheckResult(cwd, { maxDiagnostics: 5 })
+  // L0 - typed contract (`nifra check`).
+  const check = await verification.check()
   statuses.push({
     level: 0,
     name: "typed contract",
@@ -63,11 +69,11 @@ export async function collectVerificationLevels(
   })
 
   // L1-L4 all hang off the assurance config; without it the ladder stops at L0 by definition.
-  let config: Awaited<ReturnType<typeof loadAssuranceConfig>> | undefined
-  try {
-    config = await loadAssuranceConfig(cwd, options.config)
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err)
+  if (verification.config === undefined) {
+    const reason =
+      verification.configError instanceof Error
+        ? verification.configError.message
+        : String(verification.configError)
     for (const [level, name] of [
       [1, "route assurance"],
       [2, "capability lockfile"],
@@ -78,9 +84,10 @@ export async function collectVerificationLevels(
     }
     return finalize(statuses)
   }
+  const config = verification.config
 
-  // L1 — route assurance.
-  const assurance = evaluateRouteAssurance(config.source, config.policy)
+  // L1 - route assurance.
+  const assurance = verification.routeAssurance as AssuranceReport
   statuses.push({
     level: 1,
     name: "route assurance",
@@ -88,14 +95,13 @@ export async function collectVerificationLevels(
     reasons: assurance.findings.map((f) => f.message).slice(0, 5),
   })
 
-  // L2 — capability assurance + lockfile in sync.
+  // L2 - capability assurance + lockfile in sync.
   const l2Reasons: string[] = []
-  let capabilityReport: ReturnType<typeof evaluateCapabilityAssurance> | undefined
+  const capabilityReport = verification.capability?.report
   if (config.capabilities === undefined) {
     l2Reasons.push("nifra.assurance.ts declares no capabilities policy")
   } else {
-    const project = await collectCapabilityProjectReport(cwd, config.source, config.capabilities)
-    capabilityReport = project.report
+    const project = verification.capability as CapabilityProjectReport
     if (!project.report.ok) {
       l2Reasons.push(...project.report.findings.map((f) => f.message).slice(0, 5))
     }
@@ -115,11 +121,11 @@ export async function collectVerificationLevels(
     reasons: l2Reasons,
   })
 
-  // L3 — emitted manifest hash-verifies AND matches the current app.
+  // L3 - emitted manifest hash-verifies AND matches the current app.
   const l3Reasons: string[] = []
   const manifestPath = resolve(cwd, config.manifest?.path ?? DEFAULT_MANIFEST_FILE)
   if (!existsSync(manifestPath)) {
-    l3Reasons.push(`manifest missing (${manifestPath}) — run \`nifra manifest emit\``)
+    l3Reasons.push(`manifest missing (${manifestPath}) - run \`nifra manifest emit\``)
   } else {
     try {
       const recorded = await parseNifraManifest(await Bun.file(manifestPath).text(), manifestPath)
@@ -130,7 +136,7 @@ export async function collectVerificationLevels(
           ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
         })
         if (current.contentHash !== recorded.contentHash) {
-          l3Reasons.push("manifest is stale — the app changed since it was emitted")
+          l3Reasons.push("manifest is stale - the app changed since it was emitted")
         }
       } else {
         l3Reasons.push("manifest cannot be validated while assurance is failing")
@@ -146,11 +152,11 @@ export async function collectVerificationLevels(
     reasons: l3Reasons,
   })
 
-  // L4 — contract-generated invariants against an explicitly isolated executor.
+  // L4 - contract-generated invariants against an explicitly isolated executor.
   const l4Reasons: string[] = []
   if (config.invariants === undefined) {
     l4Reasons.push(
-      "no isolated invariant executor configured — add `invariants.executor` in nifra.assurance.ts",
+      "no isolated invariant executor configured - add `invariants.executor` in nifra.assurance.ts",
     )
   } else {
     const invariants = await runAdversarialContract(config.source as ContractTestApp, {

package/src/load.ts

@@ -1,12 +1,12 @@
 /**
  * Zero-config app discovery. The CLI reads a few conventions from the project root:
- *   - `routes/`         — the file-based routes (per `@nifrajs/web/fs`).
- *   - `nifra.config.ts`  — the CLI's framework wiring (see {@link NifraFramework}); `framework.ts` is
+ *   - `routes/`         - the file-based routes (per `@nifrajs/web/fs`).
+ *   - `nifra.config.ts`  - the CLI's framework wiring (see {@link NifraFramework}); `framework.ts` is
  *                         used as a fallback. One of the two is required.
- *   - `backend.ts`      — exports `backend` (a `@nifrajs/core` server, the contract). Optional.
+ *   - `backend.ts`      - exports `backend` (a `@nifrajs/core` server, the contract). Optional.
  *
  * Why two filenames: a multi-target app's edge entry (`_worker.ts`) imports `framework.ts` for the
- * render adapter, so `framework.ts` must stay edge-bundlable — it can't reference Vite plugins or the
+ * render adapter, so `framework.ts` must stay edge-bundlable - it can't reference Vite plugins or the
  * SFC compiler (Bun would pull them into the `target:"browser"` worker and fail on `child_process`).
  * `nifra.config.ts` holds that build/dev tooling instead: it's imported ONLY by this CLI (which runs on
  * Bun), so its Vite plugin + SFC-compiler imports (`@vitejs/plugin-vue`, `@nifrajs/web-vue/plugin`) never
@@ -17,9 +17,9 @@ import { resolve } from "node:path"
 import { checkPipelineSeparation } from "./pipeline-guard.ts"
 
 /**
- * A plugin list — either an array, or a **thunk** that returns one (optionally async). Both forms are
+ * A plugin list - either an array, or a **thunk** that returns one (optionally async). Both forms are
  * accepted; {@link resolvePlugins} normalizes them. The thunk is just a convenience for deferring a
- * plugin's construction — it does NOT make a plugin edge-safe (Bun.build follows a dynamic `import()`
+ * plugin's construction - it does NOT make a plugin edge-safe (Bun.build follows a dynamic `import()`
  * even from an unused export, so a Vite/compiler import in an edge-bundled file fails regardless). Edge
  * safety comes from WHERE the config lives: keep these fields in `nifra.config.ts` (CLI-only), not in
  * the edge-imported `framework.ts`. See the module header.
@@ -29,7 +29,7 @@ export type PluginsField =
   | (() => readonly unknown[] | Promise<readonly unknown[]>)
 
 /**
- * The CLI's framework wiring — exported from `nifra.config.ts` (or `framework.ts` as a fallback).
+ * The CLI's framework wiring - exported from `nifra.config.ts` (or `framework.ts` as a fallback).
  * `create-nifra` generates it. Only `adapter` + `clientModule` are required; the plugin/condition
  * fields are framework-specific extras (Vue/Svelte/Solid need them; React/Preact don't).
  */
@@ -43,7 +43,7 @@ export interface NifraFramework {
   /** Bun build plugins that compile routes for the CLIENT bundle (`nifra build`), e.g.
    * `[vueBunPlugin("dom")]`. React/Preact JSX is Bun-native → none. */
   readonly clientPlugins?: PluginsField
-  /** Bun runtime plugins that compile routes for SSR — `nifra dev` (Bun-native route import) and
+  /** Bun runtime plugins that compile routes for SSR - `nifra dev` (Bun-native route import) and
    * `nifra start` register them via `Bun.plugin`, e.g. `[vueBunPlugin("ssr")]`. React/Preact → none. */
   readonly serverPlugins?: PluginsField
   /** Extra Bun.build / Vite resolve conditions, e.g. Solid's `["solid"]`. */
@@ -109,7 +109,7 @@ export interface LoadAppOptions {
 }
 
 /**
- * Root-level monorepo config — exported from `nifra.config.ts` at the workspace root.
+ * Root-level monorepo config - exported from `nifra.config.ts` at the workspace root.
  * Each key in `apps` is the short name used to namespace MCP tools (`nifra_<name>_context` etc.);
  * each value is a path relative to the root that contains its own `nifra.config.ts` / `framework.ts`.
  *
@@ -145,7 +145,7 @@ export async function detectMonorepo(
 
 /**
  * Load all apps declared in a monorepo config. Returns `{ name, cwd, app }[]` in declaration order.
- * Individual app load failures throw — each app must be valid.
+ * Individual app load failures throw - each app must be valid.
  */
 export async function loadMonorepoApps(
   rootCwd: string,
@@ -187,7 +187,7 @@ export async function loadApp(
   }
   if (!existsSync(resolve(cwd, "routes"))) {
     throw new Error(
-      `[nifra] no routes/ directory in ${cwd} — nifra apps are file-routed under routes/.`,
+      `[nifra] no routes/ directory in ${cwd} - nifra apps are file-routed under routes/.`,
     )
   }
   const fw = (await importWithQuery(configPath, options.importQuery)) as Partial<NifraFramework>
@@ -196,6 +196,15 @@ export async function loadApp(
       `[nifra] ${configFile} must export \`adapter\` (a render adapter object) and \`clientModule\` (a string).`,
     )
   }
+  // A `clientModule` given as a RELATIVE path (a local client entry, e.g. `./src/client.tsx`) is
+  // resolved to absolute here. It is embedded verbatim as an import specifier in the generated client
+  // entry, and `nifra dev` and `nifra build` write that entry into DIFFERENT directories - so a relative
+  // specifier would resolve against different bases and load in one phase but not the other. A bare or
+  // package specifier (`@nifrajs/web-react/client`) is location-independent and passes through unchanged.
+  const clientModule =
+    fw.clientModule.startsWith("./") || fw.clientModule.startsWith("../")
+      ? resolve(cwd, fw.clientModule)
+      : fw.clientModule
   const [vitePlugins, clientPlugins, serverPlugins] = await Promise.all([
     resolvePlugins(fw.vitePlugins),
     resolvePlugins(fw.clientPlugins),
@@ -215,7 +224,7 @@ export async function loadApp(
     cwd,
     routesDir: resolve(cwd, "routes"),
     outDir: resolve(cwd, outDirName),
-    framework: fw as NifraFramework,
+    framework: { ...fw, clientModule } as NifraFramework,
     resolvedPlugins,
     backend,
   }

package/src/manifest-tool.ts

@@ -1,4 +1,4 @@
-/** `nifra manifest` — emit/sign/diff the deployable route trust artifact. */
+/** `nifra manifest` - emit/sign/diff the deployable route trust artifact. */
 
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
@@ -46,7 +46,9 @@ export async function runManifestEmit(
   options: { readonly config?: string; readonly out?: string; readonly sign?: string } = {},
 ): Promise<boolean> {
   const config = await loadAssuranceConfig(cwd, options.config)
-  const assurance = evaluateRouteAssurance(config.source, config.policy)
+  const assurance = evaluateRouteAssurance(config.source, config.policy, {
+    ...(config.capabilities !== undefined ? { definitions: config.capabilities.definitions } : {}),
+  })
   const capabilityProject =
     config.capabilities === undefined
       ? undefined

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"
 
@@ -25,7 +26,7 @@ export function docsTools(
     {
       name: "nifra_docs",
       description:
-        "Search nifra's framework documentation and get back ONLY the matching sections — auth, uploads, ISR, WebSockets, loaders, deployment, anything. Call with no query for the cheap section index; pass query (e.g. \"isr revalidate\") for the top matching sections. Use this instead of reading llms-full.txt (~150 KB) whole. For the EXACT TypeScript of a type/interface/function, call nifra_types instead (don't read .d.ts files).",
+        "Search nifra's framework documentation and get back ONLY the matching sections - auth, uploads, ISR, WebSockets, loaders, deployment, anything. Call with no query for the cheap section index; pass query (e.g. \"isr revalidate\") for the top matching sections. Use this instead of reading llms-full.txt (~150 KB) whole. For the EXACT TypeScript of a type/interface/function, call nifra_types instead (don't read .d.ts files).",
       inputSchema: {
         type: "object",
         properties: {
@@ -40,7 +41,7 @@ export function docsTools(
       handler: async (args) => {
         const corpus = await loadDocs()
         if (corpus === undefined) {
-          return "docs corpus missing — run `bun run gen:llms` in the nifra repo (published builds ship it)."
+          return "docs corpus missing - run `bun run gen:llms` in the nifra repo (published builds ship it)."
         }
         const { query, limit } = args as { query?: string; limit?: number }
         return renderDocsResult(corpus, query, clamp(limit, 1, 5, 3))
@@ -49,7 +50,7 @@ export function docsTools(
     {
       name: "nifra_example",
       description:
-        'Get a VERIFIED, copy-pasteable nifra code example for a task — auth route, file upload, ISR page, loader/action, typed client, SSE, deployment, etc. Every snippet is typechecked against the installed nifra version, so it compiles as-is. PREFER THIS over writing nifra code from memory (training data drifts). Call with no query for the grouped index; pass query (e.g. "protected route", "upload", "isr revalidate") for matching snippets.',
+        'Get a VERIFIED, copy-pasteable nifra code example for a task - auth route, file upload, ISR page, loader/action, typed client, SSE, deployment, etc. Every snippet is typechecked against the installed nifra version, so it compiles as-is. PREFER THIS over writing nifra code from memory (training data drifts). Call with no query for the grouped index; pass query (e.g. "protected route", "upload", "isr revalidate") for matching snippets.',
       inputSchema: {
         type: "object",
         properties: {
@@ -64,7 +65,7 @@ export function docsTools(
       handler: async (args) => {
         const corpus = await loadExamples()
         if (corpus === undefined) {
-          return "examples corpus missing — run `bun run gen:llms` in the nifra repo (published builds ship it)."
+          return "examples corpus missing - run `bun run gen:llms` in the nifra repo (published builds ship it)."
         }
         const { query, limit } = args as { query?: string; limit?: number }
         return renderExamplesResult(corpus, query, clamp(limit, 1, 5, 3))
@@ -73,14 +74,14 @@ export function docsTools(
     {
       name: "nifra_types",
       description:
-        'Get the EXACT TypeScript declaration of any exported @nifrajs/* symbol — interface, type, class, function, const. Each signature is generated from the package\'s built .d.ts, so it is the LITERAL declaration: complete, authoritative, never prose and never truncated. THIS IS THE SOURCE OF TRUTH for nifra\'s types — do NOT read node_modules/@nifrajs/**/*.d.ts; call this instead. Pass `name` for an exact symbol (e.g. "RateLimitStore", "RouteSchema", "Context", "rateLimit"); pass `query` to search by keyword; omit both for the per-package index of names. A `name` lookup is always the complete declaration; a `query` returns a one-line summary plus the signature, collapsing an oversized body — pass `full: true` to override.',
+        'Get the EXACT TypeScript declaration of any exported @nifrajs/* symbol - interface, type, class, function, const. Each signature is generated from the package\'s built .d.ts, so it is the LITERAL declaration: complete, authoritative, never prose and never truncated. THIS IS THE SOURCE OF TRUTH for nifra\'s types - do NOT read node_modules/@nifrajs/**/*.d.ts; call this instead. Pass `name` for an exact symbol (e.g. "RateLimitStore", "RouteSchema", "Context", "rateLimit"); pass `query` to search by keyword; omit both for the per-package index of names. A `name` lookup is always the complete declaration; a `query` returns a one-line summary plus the signature, collapsing an oversized body - pass `full: true` to override.',
       inputSchema: {
         type: "object",
         properties: {
           name: {
             type: "string",
             description:
-              "Exact symbol name — returns its literal declaration (e.g. RateLimitStore).",
+              "Exact symbol name - returns its literal declaration (e.g. RateLimitStore).",
           },
           query: {
             type: "string",
@@ -94,7 +95,7 @@ export function docsTools(
           full: {
             type: "boolean",
             description:
-              "Query mode only: return whole declarations instead of collapsed ones. Off by default — a search is for picking a symbol, and one match can be tens of thousands of characters.",
+              "Query mode only: return whole declarations instead of collapsed ones. Off by default - a search is for picking a symbol, and one match can be tens of thousands of characters.",
           },
         },
         additionalProperties: false,
@@ -102,7 +103,7 @@ export function docsTools(
       handler: async (args) => {
         const corpus = await loadTypes()
         if (corpus === undefined) {
-          return "types corpus missing — run `bun run build && bun run gen:llms` in the nifra repo (published builds ship it)."
+          return "types corpus missing - run `bun run build && bun run gen:llms` in the nifra repo (published builds ship it)."
         }
         const { name, query, limit, full } = args as {
           name?: string
@@ -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,39 +1,49 @@
 /**
- * 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.
+ * The PUBLIC nifra docs MCP - Streamable-HTTP transport exposing the project-INDEPENDENT tools
+ * (`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.
- * {@link handleMcpHttp} self-hosts ANYWHERE Bun runs — the simplest path is `nifra docs-mcp` on a VPS; the
- * same handler runs on Cloudflare/Vercel edge (there inline the corpus as string imports — a Worker has no
+ * {@link handleMcpHttp} self-hosts ANYWHERE Bun runs - the simplest path is `nifra docs-mcp` on a VPS; the
+ * same handler runs on Cloudflare/Vercel edge (there inline the corpus as string imports - a Worker has no
  * filesystem). `export default { port, fetch }` also lets `bun run mcp-http.ts` serve it directly.
  */
 
 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.2.0"
+const VERSION = "2.4.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,18 +56,21 @@ 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] } },
+  })
 }
 
 /**
  * Worker/edge + local entry. `export default { fetch }` is the universal server shape: Cloudflare /
  * Vercel edge / Deno deploy use `fetch` (and ignore `port`); `bun run mcp-http.ts` auto-serves it on
- * `port` (PORT env, default 8787) — Bun serves a module's default-exported server, so NO manual
+ * `port` (PORT env, default 8787) - Bun serves a module's default-exported server, so NO manual
  * `Bun.serve` here (that would double-bind the port).
  */
 export default {

package/src/mcp-protocol.ts

@@ -1,7 +1,7 @@
 /**
  * The MCP JSON-RPC dispatch now lives in `@nifrajs/mcp` (shared with nifra apps that expose their own
- * MCP server / MCP Apps widgets). This module is a thin re-export so the CLI's existing imports — and
- * the `@nifrajs/cli/mcp` self-host surface — keep resolving here unchanged.
+ * MCP server / MCP Apps widgets). This module is a thin re-export so the CLI's existing imports - and
+ * the `@nifrajs/cli/mcp` self-host surface - keep resolving here unchanged.
  */
 
 export * from "@nifrajs/mcp/protocol"

package/src/mcp-render.ts

@@ -1,12 +1,12 @@
 /**
- * The `nifra_render` engine + its child-process entry — the page half of `nifra_run`. Where `nifra_run`
+ * The `nifra_render` engine + its child-process entry - the page half of `nifra_run`. Where `nifra_run`
  * runs requests through the BACKEND, this SSRs page routes through the WEB app (`createWebApp`), so an
  * agent can verify a page renders and its loader ran after an edit. Spawned fresh per call (`bun
  * mcp-render.ts <cwd>`) so the project's CURRENT route/loader code is loaded.
  *
- * No build required: a placeholder `clientEntry` is injected (the SSR HTML renders regardless — the
+ * No build required: a placeholder `clientEntry` is injected (the SSR HTML renders regardless - the
  * client bundle only matters for hydration in the browser, not for "did this page render server-side").
- * {@link renderPages} never throws — every failure (no config, a loader error, a render throw) becomes
+ * {@link renderPages} never throws - every failure (no config, a loader error, a render throw) becomes
  * `{ error }` so the agent gets the actionable message.
  */
 
@@ -19,7 +19,7 @@ import { loadApp, resolvePlugins } from "./load.ts"
 const errString = (err: unknown): string =>
   err instanceof Error ? `${err.name}: ${err.message}` : String(err)
 
-/** Load the project, register its SSR plugins, and build the SSR `createWebApp` once — the cost the warm
+/** Load the project, register its SSR plugins, and build the SSR `createWebApp` once - the cost the warm
  * worker amortizes across calls. Never throws (every failure → `{ error }`). Factored out of
  * {@link renderPages} so the cold path (fresh process per call) and the warm worker share one builder. */
 async function buildWebApp(cwd: string): Promise<{ app: AppLike } | { error: string }> {
@@ -92,7 +92,7 @@ function redirectConsoleToStderr(): void {
 /**
  * Warm-worker loop (`--worker`): build the web app ONCE, then SSR each `{ id, input: { requests } }` line
  * against that hot app and reply `{ id, output }`. The parent (`mcp.ts`'s warm-render handler) spawns this,
- * fingerprints the source tree, and restarts the worker when a file changes — so warm reuse never serves a
+ * fingerprints the source tree, and restarts the worker when a file changes - so warm reuse never serves a
  * stale render. Mirrors `mcp-run.ts`'s worker (single backend entry → no per-call entry key needed here).
  */
 async function runWorker(cwd: string): Promise<void> {
@@ -148,7 +148,7 @@ if (import.meta.main) {
   // The parent (mcp.ts) spawns `bun mcp-render.ts <cwd>` WITHOUT setting the subprocess `cwd` option, so
   // this process inherits the MCP server's working dir, not the app's. SSR resolves `react-dom/server`
   // from `process.cwd()` to share ONE React core with the app's route components (the dual-React fix in
-  // @nifrajs/web-react) — so we must chdir to the app root before any render. Best-effort: a bad path
+  // @nifrajs/web-react) - so we must chdir to the app root before any render. Best-effort: a bad path
   // surfaces later as a load error rather than crashing the child here.
   if (cwd !== process.cwd()) {
     try {

package/src/mcp-run.ts

@@ -1,6 +1,6 @@
 /**
  * The `nifra_run` engine + its child-process entry. The MCP server spawns this file fresh on every
- * `nifra_run` call (`bun mcp-run.ts <cwd>`) so the project's CURRENT backend code is loaded — picking
+ * `nifra_run` call (`bun mcp-run.ts <cwd>`) so the project's CURRENT backend code is loaded - picking
  * up the agent's latest edits. {@link runBackend} is the pure-ish core (resolve entry → import → run),
  * exported so it's unit-testable in-process; the entry below wires it to stdin/stdout.
  */
@@ -48,7 +48,7 @@ export async function loadBackend(
 
 /**
  * Resolve the backend entry under `cwd`, import it, and run `requests` through its exported app. Never
- * throws — every failure (missing/invalid entry, import/compile/runtime error) becomes `{ error }`, so
+ * throws - every failure (missing/invalid entry, import/compile/runtime error) becomes `{ error }`, so
  * the caller (and the agent) always gets actionable output. An import error here IS the failure the
  * agent needs to see and fix.
  */