@nifrajs/cli 2.2.0 → 2.4.0

package/src/examples.ts

@@ -1,8 +1,8 @@
 /**
- * `nifra_example` — verified, copy-pasteable code examples for agents. The corpus is `examples.json`
+ * `nifra_example` - verified, copy-pasteable code examples for agents. The corpus is `examples.json`
  * (written into this package by `bun run gen:llms`): the same doc snippets `check:docs` typechecks
  * against the live `@nifrajs/*` API. So every example this returns is GUARANTEED to compile against the
- * installed version — the antidote to an agent hallucinating a framework API from stale training.
+ * installed version - the antidote to an agent hallucinating a framework API from stale training.
  *
  * Keyword-scored over each example's name/topic/slug (curated identifiers, heavily weighted) and its
  * code body. No query → a grouped index of what's available (the cheap discovery call).
@@ -12,9 +12,9 @@ import { countBodyHits, queryTermGroups, tokenize, tokenSetHas } from "./search-
 
 export interface Example {
   readonly name: string
-  /** The doc page's title, e.g. "Nifra — Auth & sessions". */
+  /** The doc page's title, e.g. "Nifra - Auth & sessions". */
   readonly topic: string
-  /** The doc page slug, e.g. "auth" — a short, matchable tag. */
+  /** The doc page slug, e.g. "auth" - a short, matchable tag. */
   readonly slug: string
   readonly code: string
 }
@@ -63,19 +63,19 @@ export function renderExamplesResult(
     const index = [...byTopic.entries()]
       .map(([topic, names]) => `- **${topic}**: ${names.join(", ")}`)
       .join("\n")
-    return `# nifra examples — index (${examples.length} verified snippets; pass \`query\` to fetch code)\n\nEvery snippet is typechecked against the installed nifra version — prefer these over recalling an API.\n\n${index}`
+    return `# nifra examples - index (${examples.length} verified snippets; pass \`query\` to fetch code)\n\nEvery snippet is typechecked against the installed nifra version - prefer these over recalling an API.\n\n${index}`
   }
   const matches = searchExamples(examples, query, limit)
   if (matches.length === 0) {
     return `No examples matched ${JSON.stringify(query)}. Call without a query for the index, or try a broader term (e.g. "auth", "upload", "isr", "client").`
   }
   return matches
-    .map((m) => `## ${m.name} — ${m.topic}\n\n\`\`\`ts\n${m.code}\n\`\`\``)
+    .map((m) => `## ${m.name} - ${m.topic}\n\n\`\`\`ts\n${m.code}\n\`\`\``)
     .join("\n\n---\n\n")
 }
 
 /** Load the bundled example corpus. Resolves relative to this module so it works from `src/` (repo dev)
- * and `dist/` (published) alike — `docs/examples.json` sits at the package root next to both. */
+ * and `dist/` (published) alike - `docs/examples.json` sits at the package root next to both. */
 export async function loadExamplesCorpus(): Promise<Example[] | undefined> {
   const url = new URL("../docs/examples.json", import.meta.url)
   try {

package/src/init-agents.ts

@@ -1,18 +1,18 @@
 /**
- * `nifra init-agents` — retrofit an EXISTING app with the agent-discovery files a freshly scaffolded
+ * `nifra init-agents` - retrofit an EXISTING app with the agent-discovery files a freshly scaffolded
  * app ships, so an already-built project adopts the nifra MCP in one command:
  *
- *   .mcp.json          — Claude Code's project MCP registry  (launches `bunx @nifrajs/cli mcp`)
- *   .cursor/mcp.json   — Cursor's MCP registry (same server config)
- *   CLAUDE.md          — Claude's MCP-first preamble + `@AGENTS.md` import
- *   AGENTS.md          — a `## MCP server` section appended (or a minimal file if none exists)
+ *   .mcp.json          - Claude Code's project MCP registry  (launches `bunx @nifrajs/cli mcp`)
+ *   .cursor/mcp.json   - Cursor's MCP registry (same server config)
+ *   CLAUDE.md          - Claude's MCP-first preamble + `@AGENTS.md` import
+ *   AGENTS.md          - a `## MCP server` section appended (or a minimal file if none exists)
  *
- * The generators are imported from `create-nifra/agent-files` — the SAME source of truth `create-nifra`
- * uses at scaffold time — so a retrofitted app and a freshly scaffolded one get byte-identical configs.
+ * The generators are imported from `create-nifra/agent-files` - the SAME source of truth `create-nifra`
+ * uses at scaffold time - so a retrofitted app and a freshly scaffolded one get byte-identical configs.
  *
  * Safety: this writes into the user's existing tree, so it NEVER silently clobbers a file they may have
  * customized. By default an existing `.mcp.json` / `CLAUDE.md` / `.cursor/mcp.json` is SKIPPED with a
- * notice; `--force` overwrites. `AGENTS.md` is special-cased — if it already has the MCP section it's
+ * notice; `--force` overwrites. `AGENTS.md` is special-cased - if it already has the MCP section it's
  * left alone, otherwise the section is APPENDED (never overwriting the user's conventions), and `--force`
  * is not needed for that append since it's additive. Every write path is resolved + confined under the
  * cwd (no `..` traversal escaping the project root).
@@ -34,10 +34,10 @@ import {
 export interface InitAgentsFileResult {
   /** Project-root-relative POSIX path. */
   readonly path: string
-  /** `wrote` — created or (with --force) overwrote; `appended` — added the MCP section to an existing
-   * AGENTS.md; `skipped` — already present and not forced; `present` — MCP section already there. */
+  /** `wrote` - created or (with --force) overwrote; `appended` - added the MCP section to an existing
+   * AGENTS.md; `skipped` - already present and not forced; `present` - MCP section already there. */
   readonly action: "wrote" | "appended" | "skipped" | "present"
-  /** Why it was skipped/left, for the notice (e.g. "exists — pass --force to overwrite"). */
+  /** Why it was skipped/left, for the notice (e.g. "exists - pass --force to overwrite"). */
   readonly note?: string
 }
 
@@ -52,7 +52,7 @@ export interface InitAgentsOptions {
 }
 
 /** Confine a project-relative path under `cwd` and return the absolute path. Rejects a spec that escapes
- * the root (defense-in-depth — these specs are constants, but the cwd-confinement invariant is enforced
+ * the root (defense-in-depth - these specs are constants, but the cwd-confinement invariant is enforced
  * at the seam, not assumed). Exported so the invariant is directly testable. */
 export function safeJoin(cwd: string, rel: string): string {
   const abs = resolve(cwd, rel)
@@ -80,7 +80,7 @@ async function writeOwned(
 ): Promise<InitAgentsFileResult> {
   const abs = safeJoin(cwd, rel)
   if (!force && (await fileExists(abs))) {
-    return { path: rel, action: "skipped", note: "exists — pass --force to overwrite" }
+    return { path: rel, action: "skipped", note: "exists - pass --force to overwrite" }
   }
   // `.cursor/mcp.json` needs its parent dir; `recursive` is a no-op for the root-level files.
   await mkdir(resolve(abs, ".."), { recursive: true })
@@ -91,7 +91,7 @@ async function writeOwned(
 /**
  * AGENTS.md is additive, not owned: if it exists and already has the MCP section, leave it; if it exists
  * without the section, append the section (preserving the user's conventions); if it's absent, write a
- * minimal AGENTS.md that is just the MCP section under a heading. `--force` is irrelevant here — we never
+ * minimal AGENTS.md that is just the MCP section under a heading. `--force` is irrelevant here - we never
  * overwrite the user's existing guidance.
  */
 async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
@@ -121,7 +121,7 @@ async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
 
 /**
  * Retrofit `cwd` with the four agent-discovery files. Pure enough to unit-test (no argv, no process.exit,
- * no console) — the CLI wrapper handles printing + the exit code.
+ * no console) - the CLI wrapper handles printing + the exit code.
  */
 export async function initAgents(
   cwd: string,
@@ -153,13 +153,13 @@ export function renderInitAgents(result: InitAgentsResult): string {
   const wroteAny = result.files.some((f) => f.action === "wrote" || f.action === "appended")
   const footer = wroteAny
     ? "\nThe nifra MCP is now registered. Restart your agent so it picks up .mcp.json, then prefer nifra_docs / nifra_example and gate on nifra check."
-    : "\nNothing to do — every file was already present (use --force to overwrite the owned ones)."
+    : "\nNothing to do - every file was already present (use --force to overwrite the owned ones)."
   return `nifra init-agents\n\n${lines.join("\n")}\n${footer}`
 }
 
 /**
  * CLI entry: run the retrofit at `cwd` and print the result. Returns `true` (the command always succeeds
- * unless a write throws — which propagates as a non-zero exit via the dispatcher's catch). `--json`
+ * unless a write throws - which propagates as a non-zero exit via the dispatcher's catch). `--json`
  * emits the structured result for agents/CI.
  */
 export async function runInitAgents(

package/src/internal/typescript-import.ts

@@ -0,0 +1,33 @@
+/**
+ * The one place the CLI imports TypeScript from.
+ *
+ * The interpolated-SQL rule parses source with the TypeScript compiler, because the regex it replaced
+ * could not tell `sql\`… ${id} …\`` (bound) from a plain template (injectable) without guessing at
+ * string and comment boundaries. That is the right tool, but it is a ~25 MB dependency, and the CLI's
+ * own typecheck step already treats `tsc` as something the PROJECT provides rather than something the
+ * CLI ships. Making it a hard dependency would have contradicted that for every install.
+ *
+ * So it is an optional peer, resolved at the moment the rule runs. Every Nifra project has TypeScript
+ * - the templates all ship a `typecheck` script - so this resolves in practice; the point is that an
+ * install does not pay for it.
+ */
+
+/** The slice of the compiler the SQL scanner uses. Structural, so the peer stays optional. */
+export type TypeScriptApi = typeof import("typescript")
+
+/**
+ * Import the project's TypeScript, or `undefined` when it is not installed.
+ *
+ * Only a RESOLUTION failure is absence. A compiler that resolves and then fails while evaluating is a
+ * broken install, not a missing one, and telling that user to install what they already have sends
+ * them the wrong way - so that error is rethrown for the caller to report.
+ */
+export async function importTypeScript(): Promise<TypeScriptApi | undefined> {
+  try {
+    return (await import("typescript")) as TypeScriptApi
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause)
+    if (/cannot find (?:package|module)|ERR_MODULE_NOT_FOUND/i.test(message)) return undefined
+    throw cause
+  }
+}

package/src/introspect.ts

@@ -1,6 +1,6 @@
 /**
- * Introspect a loaded nifra project into a Markdown brief — the API routes (`backend.routes()`), the
- * page routes (`discoverRoutes`), and a conventions summary — for piping into an AI coding agent's
+ * Introspect a loaded nifra project into a Markdown brief - the API routes (`backend.routes()`), the
+ * page routes (`discoverRoutes`), and a conventions summary - for piping into an AI coding agent's
  * prompt. Used by `nifra context` (stdout) and the `nifra mcp` server (a tool result), so an agent sees
  * *this* project's actual surface, not just generic docs.
  */
@@ -28,7 +28,7 @@ interface JsonSchemaNode {
 }
 
 /**
- * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) — the
+ * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) - the
  * shape agents already think in, at a fraction of the raw JSON Schema's tokens (~70-80% smaller).
  * Anything the renderer doesn't model falls back to the raw JSON for that subtree, so the output
  * is always faithful, just not always minimal.
@@ -74,7 +74,7 @@ export function tsTypeOf(schema: unknown, depth = 0): string {
 }
 
 /** One route's request/response field shapes, indented under its line. Reads the declared schemas off the
- * descriptor so an agent gets the exact input + output contract — not just "this route is validated". */
+ * descriptor so an agent gets the exact input + output contract - not just "this route is validated". */
 function schemaLines(schema: ReflectedRoute["schema"]): string[] {
   const s = schema
   if (!s) return []
@@ -95,11 +95,11 @@ function schemaLines(schema: ReflectedRoute["schema"]): string[] {
 const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
 /**
- * The typed-client call form for a route — the exact `client<typeof app>` proxy chain an agent should
+ * The typed-client call form for a route - the exact `client<typeof app>` proxy chain an agent should
  * write, derived from the same convention `@nifrajs/client` implements (so it never has to read the
  * client tests to learn it): a static segment is a property (`.users`), a path param/wildcard is a call
  * that appends the value (`({ id })`), the root path is `.index`, and the HTTP verb is the terminal call.
- * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first —
+ * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first -
  * so the `{ query }` argument lands in the right slot for each.
  */
 export function clientCall(method: string, path: string, schema: unknown): string {
@@ -140,10 +140,10 @@ export function apiRoutesSection(routes: readonly ReflectedRoute[]): string {
       ...schemaLines(r.schema),
       `    - call: \`${clientCall(r.method, r.path, r.schema)}\` → \`{ ok, status, data, error }\``,
     ])
-  return `## API routes (backend.ts)\n\nEach route's \`body\`/\`query\`/\`response\` shape is its contract — the typed client derives request inputs and \`res.data\` from these, so a screen built on \`client<typeof app>\` stays in sync automatically. The \`call\` line is the exact \`client<typeof app>\` form: static path segments are properties, a path param is a call (\`({ id })\`), the verb is the terminal call (body first for POST/PUT/PATCH), and every call returns the never-throwing \`{ ok, status, data, error }\` Result.\n\n${lines.join("\n")}`
+  return `## API routes (backend.ts)\n\nEach route's \`body\`/\`query\`/\`response\` shape is its contract - the typed client derives request inputs and \`res.data\` from these, so a screen built on \`client<typeof app>\` stays in sync automatically. The \`call\` line is the exact \`client<typeof app>\` form: static path segments are properties, a path param is a call (\`({ id })\`), the verb is the terminal call (body first for POST/PUT/PATCH), and every call returns the never-throwing \`{ ok, status, data, error }\` Result.\n\n${lines.join("\n")}`
 }
 
-/** Compact API-routes INDEX for the no-arg `nifra_context` call — `METHOD path` per route, WITHOUT the
+/** Compact API-routes INDEX for the no-arg `nifra_context` call - `METHOD path` per route, WITHOUT the
  * body/query/response shapes or the per-route `call` line. Bounds the first-call payload on a big backend:
  * an agent gets the full route list (so it knows what's mounted) plus a pointer to fetch any route's full
  * contract via the `path`/`kind` slice, instead of every schema up front. */
@@ -154,7 +154,7 @@ export function apiRoutesIndexSection(routes: readonly ReflectedRoute[]): string
   const lines = [...routes]
     .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
     .map((r) => `- \`${r.method} ${r.path}\``)
-  return `## API routes (backend.ts)\n\n${routes.length} route${routes.length === 1 ? "" : "s"}. Call \`nifra_context\` again with \`path\` (a route prefix) and/or \`kind: "api"\` for the body/query/response contracts + the exact \`client<typeof app>\` call form — or \`nifra_routes\` for the same as structured JSON.\n\n${lines.join("\n")}`
+  return `## API routes (backend.ts)\n\n${routes.length} route${routes.length === 1 ? "" : "s"}. Call \`nifra_context\` again with \`path\` (a route prefix) and/or \`kind: "api"\` for the body/query/response contracts + the exact \`client<typeof app>\` call form - or \`nifra_routes\` for the same as structured JSON.\n\n${lines.join("\n")}`
 }
 
 /** Markdown section listing the file-routed pages (URL pattern → source file). */
@@ -172,25 +172,25 @@ const CONVENTIONS = `## Conventions (summary)
 
 - **Backend:** \`server()\` from \`@nifrajs/core\`; returning a value sends JSON. Validate untrusted input with
   a route schema (\`{ body, query, params }\` using \`t\` from \`@nifrajs/schema\` or any Standard Schema) and read
-  the typed \`c.body\` / \`c.query\` / \`c.params\` — never hand-parse.
+  the typed \`c.body\` / \`c.query\` / \`c.params\` - never hand-parse.
 - **Cross-cutting concerns** (rate limit / \`429\`, CORS, auth, CSRF, caching, security headers, body limits)
   → \`@nifrajs/middleware\`, applied with \`app.use(...)\`. Don't hand-roll them; call \`nifra_docs("middleware")\`
   for the full list + usage.
 - **Need the exact TypeScript of a \`@nifrajs/*\` symbol?** Call \`nifra_types({ name })\` (e.g. \`RateLimitStore\`,
-  \`RouteSchema\`) — the authoritative, complete declaration. Never read \`@nifrajs\` \`.d.ts\` files.
+  \`RouteSchema\`) - the authoritative, complete declaration. Never read \`@nifrajs\` \`.d.ts\` files.
 - **Response contract (no drift):** declare \`{ response: t.object({...}) }\` on a route to lock its output
-  shape — the handler is type-checked against it and the client sees exactly that shape. The contract above
+  shape - the handler is type-checked against it and the client sees exactly that shape. The contract above
   is the single source of truth for both sides.
-- **Client — ALWAYS use this for API calls:** \`client<typeof app>(url)\` derives request inputs AND
+- **Client - ALWAYS use this for API calls:** \`client<typeof app>(url)\` derives request inputs AND
   \`res.data\` from the backend's route types, so the compiler catches any frontend/backend drift. Never
-  hand-roll \`fetch\` + ad-hoc response types for an internal API — that's exactly how screens drift. It
+  hand-roll \`fetch\` + ad-hoc response types for an internal API - that's exactly how screens drift. It
   never throws: branch on \`res.ok ? res.data : res.error\`.
 - **Pages:** file-routed under \`routes/\`; \`loader\`/\`action\` are server-only but the module is also bundled
-  for the browser — **never top-level-import server-only code** (DB, secrets, \`process.env\`) into a route
+  for the browser - **never top-level-import server-only code** (DB, secrets, \`process.env\`) into a route
   file; reach it via \`ctx.api\` / \`ctx.env\`.
 - \`app.fetch(Request)\` is the universal entry. Full reference: this repo's \`AGENTS.md\`, or \`llms-full.txt\`.`
 
-/** Optional narrowing for {@link describeProject} — a path prefix and/or one section. A filtered
+/** Optional narrowing for {@link describeProject} - a path prefix and/or one section. A filtered
  * brief omits the conventions block (the agent already has it from its first full call), so
  * follow-up calls cost a fraction of the tokens. */
 export interface ContextFilter {
@@ -199,9 +199,9 @@ export interface ContextFilter {
 }
 
 /**
- * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** — the route list (API
+ * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** - the route list (API
  * routes as `METHOD path`, page routes as `pattern → file`) + conventions + a pointer to fetch full
- * contracts via the slice — so learning a big project is cheap, not a full-surface schema dump. Passing a
+ * contracts via the slice - so learning a big project is cheap, not a full-surface schema dump. Passing a
  * {@link ContextFilter} (`path` prefix and/or `kind`) returns the narrowed, FULL detail (per-route
  * body/query/response shapes + the typed-client `call` form), and omits the conventions block (the agent
  * already has it from the index call).
@@ -211,7 +211,7 @@ export function describeProject(app: LoadedApp, filter?: ContextFilter): string
   try {
     manifest = discoverRoutes(app.routesDir)
   } catch {
-    // No (or unreadable) routes/ — the page-routes section reports that.
+    // No (or unreadable) routes/ - the page-routes section reports that.
   }
   const prefix = filter?.path
   let routes = backendRoutes(app.backend)
@@ -228,10 +228,10 @@ export function describeProject(app: LoadedApp, filter?: ContextFilter): string
   const sections: string[] = [`# nifra project: ${app.cwd.slice(app.cwd.lastIndexOf("/") + 1)}`]
   if (isIndex) {
     sections.push(
-      "A full-stack nifra app — Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).",
-      // Point agents at the verified surface, not recalled APIs — nifra is young, so training data is the
+      "A full-stack nifra app - Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).",
+      // Point agents at the verified surface, not recalled APIs - nifra is young, so training data is the
       // wrong source. The MCP tools (nifra_docs / nifra_example) are checked against the installed version.
-      "> **Build against THIS surface + the verified tools — do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.",
+      "> **Build against THIS surface + the verified tools - do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.",
     )
   }
   if (filter?.kind !== "pages") {
@@ -255,7 +255,7 @@ export interface RouteJson {
 }
 
 /**
- * The backend's API routes as structured JSON — what the `nifra_routes` MCP tool returns, so an agent
+ * The backend's API routes as structured JSON - what the `nifra_routes` MCP tool returns, so an agent
  * consumes the contract programmatically (`list_routes` / `get_route_schema`) instead of parsing the
  * Markdown brief. Optionally filtered to routes whose path starts with `pathPrefix`. Reuses the exact
  * same `call` form and TS-shaped contracts the Markdown brief shows.
@@ -292,11 +292,11 @@ export function routesToJson(app: LoadedApp, pathPrefix?: string): RouteJson[] {
 }
 
 // ===================================================================================================
-// `nifra routes [--json]` — the focused, uniform view of every route the app serves, with methods.
+// `nifra routes [--json]` - the focused, uniform view of every route the app serves, with methods.
 //
 // `nifra context` lists page routes + API routes for an agent's prompt (Markdown, with schemas).
 // `nifra routes` answers a different question: "what does this app actually serve, and with which
-// methods?" — so an agent sees instantly that `POST /api/explain` is (or isn't) mounted, instead of
+// methods?" - so an agent sees instantly that `POST /api/explain` is (or isn't) mounted, instead of
 // discovering it via a 405. It marks which backend routes are AUTO-MOUNTED under the page router's
 // `apiPrefix` (default `/api`), and `--json` makes it machine-consumable. The table-building +
 // rendering are pure (no fs / no module loads), so they're unit-tested; the cwd gathering is the thin
@@ -313,7 +313,7 @@ export interface RouteTableEntry {
   readonly path: string
   /** Methods this route serves, sorted (page: `GET`, plus `POST` when it has an `action`). */
   readonly methods: readonly string[]
-  /** Source file (page only — the route module path relative to `routes/`). */
+  /** Source file (page only - the route module path relative to `routes/`). */
   readonly file?: string
   /** True when this API route is auto-mounted under the page router's `apiPrefix` (so it's reachable
    * through the same web app, no hand-wired `if (pathname.startsWith("/api/"))`). Pages are never
@@ -345,7 +345,7 @@ function isUnderPrefix(path: string, prefix: string): boolean {
 }
 
 /**
- * Build the unified, sorted route table from page routes + backend API routes. Pure — the caller
+ * Build the unified, sorted route table from page routes + backend API routes. Pure - the caller
  * supplies page `hasAction` (resolved via a module load) and the API descriptors (`backend.routes()`).
  * Page routes serve `GET` (+ `POST` when they export an `action`); API routes carry their declared
  * method, and are flagged `autoMounted` when at/under `apiPrefix`. Sorted by path, then kind, then the
@@ -449,7 +449,7 @@ export async function describeRoutes(
   try {
     manifest = discoverRoutes(app.routesDir)
   } catch {
-    // No (or unreadable) routes/ — fall through with no pages; the table still shows API routes.
+    // No (or unreadable) routes/ - fall through with no pages; the table still shows API routes.
   }
   const pages: PageRouteInput[] = []
   for (const route of manifest?.routes ?? []) {

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)
+}