create-nola-lang 0.1.12 → 0.1.14

package/README.md

@@ -25,8 +25,13 @@ symlink to it for Claude Code) are written without a question; `--ide none` and
 
 You get one template per feature — `feature-extraction` (the default) is one
 `src/main.tsi` with a top-level `ask`, `function-calling` the same with a call
-intent over an async function in `src/tickets.ts`, `typescript-interop` is
-`src/person.tsi` plus a plain-TS consumer — with `nola.config.ts`, tsconfig,
-and a recorded replay ledger so the first run works without any API key. `npm create nola`
+intent over an async function in `src/tickets.ts`, `agent-loop` a top-level
+`while` around an ask, `typescript-interop` is `src/person.tsi` plus a plain-TS
+consumer, `triage-ticket` the one-file shape on typesafe.ai — each with
+`nola.config.ts` and a tsconfig, and the first two and `typescript-interop`
+with a recorded replay ledger so the first run works without any API key.
+Every template but `empty` is one of the curated examples in the Nola
+repository, fetched at the release tag matching this package's version;
+`empty` (config, tsconfig and a stub entry) ships inside the package. `npm create nola`
 is a short alias of this package (`create-nola`); `nola init` (from the
 `nola-lang` package) lays down the same templates.

package/dist/{chunk-LUSVIOAN.js → chunk-CB26Z47Y.js}

@@ -16,7 +16,7 @@ var PROVIDERS = [
   },
   { id: "google", label: "Gemini", hint: 'google("gemini-2.5-flash"), reads GEMINI_API_KEY', envVar: "GEMINI_API_KEY", model: 'google("gemini-2.5-flash")' },
   { id: "typesafe", label: "typesafe.ai", hint: "typesafe(), reads TYPESAFE_API_KEY", envVar: "TYPESAFE_API_KEY", model: "typesafe()" },
-  { id: "none", label: "Skip for now", hint: "the builtin templates run offline from a replay ledger; pick a model in nola.config.ts later" }
+  { id: "none", label: "Skip for now", hint: "keeps the template's own config (the recorded ones run offline); pick a model in nola.config.ts later" }
 ];
 function providerById(id2) {
   return PROVIDERS.find((p) => p.id === id2);
@@ -170,17 +170,32 @@ async function fetchExampleFromGitHub(name, version, fetchImpl = fetch) {
 // src/registry.ts
 var DEFAULT_ENTRY = "src/main.ts";
 var TEMPLATES = [
-  { name: "feature-extraction", label: "extract typed data from context", source: "builtin", entry: "src/main.tsi" },
+  {
+    name: "feature-extraction",
+    label: "extract typed data from context",
+    source: "example",
+    featured: true,
+    entry: "src/main.tsi"
+  },
   {
     name: "function-calling",
     label: "call an async function from a TypeScript file",
-    source: "builtin",
+    source: "example",
+    featured: true,
+    entry: "src/main.tsi"
+  },
+  {
+    name: "agent-loop",
+    label: "an agent loop in one .tsi file: a top-level while with an ask, and a context statement read on every pass",
+    source: "example",
+    featured: true,
     entry: "src/main.tsi"
   },
   {
     name: "typescript-interop",
     label: "an infer function example, imported and awaited from plain TypeScript",
-    source: "builtin"
+    source: "example",
+    featured: true
   },
   {
     name: "triage-ticket",
@@ -190,7 +205,7 @@ var TEMPLATES = [
     entry: "src/main.tsi",
     provider: { label: "typesafe.ai", envVar: "TYPESAFE_API_KEY" }
   },
-  { name: "empty", label: "nola.config + tsconfig only, bring your own code", source: "builtin" },
+  { name: "empty", label: "nola.config + tsconfig only, bring your own code", source: "builtin", entry: "src/main.tsi" },
   { name: "file-ticket", label: "call intents: the model fills a function's arguments", source: "example" },
   { name: "extract-resume", label: "nested arrays of objects, JSDoc schema descriptions", source: "example" },
   { name: "extract-invoice", label: "same-file type references, optional fields", source: "example" },
@@ -231,16 +246,14 @@ function envExample(envVar) {
 ${envVar}=
 `;
 }
-var RENAMES = { _gitignore: ".gitignore" };
 var GITIGNORE_URL = new URL("../templates/_gitignore", import.meta.url);
 async function withRecommendedGitignore(files) {
   if (!files.has(".gitignore")) files.set(".gitignore", await readFile3(GITIGNORE_URL, "utf8"));
   return files;
 }
-var SUBSTITUTED = /* @__PURE__ */ new Set(["package.json", "README.md", "main.ts", "main.tsi"]);
 function nextStepsComment(ide, template) {
   if (ide === "vscode") {
-    const breakpointIn = templateByName(template)?.entry ? "on the `ask` line below" : template === "typescript-interop" ? "in src/person.tsi" : "in your .tsi file";
+    const breakpointIn = template === "empty" ? "on your first `ask` in this file" : templateByName(template)?.entry ? "on the `ask` line below" : template === "typescript-interop" ? "in src/person.tsi" : "in your .tsi file";
     return [
       "// Next steps in VS Code:",
       "//   1. Press F5 to run this file (.vscode/launch.json is already set up).",
@@ -255,29 +268,7 @@ function nextStepsComment(ide, template) {
     "//   2. Set up your editor (VS Code extension, debugging): https://nola.sh/docs/start/editor-setup/"
   ].join("\n");
 }
-var OFFLINE_ONLY = /* @__PURE__ */ new Set(["nola.replay.jsonl"]);
-var README_NOTES = {
-  offline: {
-    START_NOTE: "works offline, no API key needed",
-    PROVIDER_NOTE: 'This project runs offline: `nola.config.ts` replays answers from the committed\n`nola.replay.jsonl` ledger. The ledger is keyed by the exact prompt, so once\nyou edit the `.tsi` file or add your own asks, switch the config to a real\nmodel (see the comment in `nola.config.ts`): `model: "nola"` with a key from\n`npx nola-lang key` (25 free runs), or your own provider and its key.'
-  },
-  nola: {
-    START_NOTE: "uses your 25 free Nola runs (key in .env)",
-    PROVIDER_NOTE: '`nola.config.ts` sets `model: "nola"` \u2014 platform-served inference with the trial key the\nscaffold wrote to `.env` (git-ignored). Out of runs? `npx nola-lang account` opens\nyour Nola account, where prepaid balance is added, or bring your\nown model (see the comment in `nola.config.ts`).'
-  }
-};
-function readmeNotes(provider) {
-  if (provider === "none") return README_NOTES.offline;
-  if (provider === "nola") return README_NOTES.nola;
-  const def = providerById(provider);
-  if (!def?.envVar || !def.model) throw new Error(`provider "${provider}" has no vendor config`);
-  return {
-    START_NOTE: `set ${def.envVar} in .env first`,
-    PROVIDER_NOTE: `\`nola.config.ts\` sets \`model: ${def.model}\` \u2014 ${def.label} serves inference with the key it reads
-from \`${def.envVar}\`. Copy \`.env.example\` to \`.env\` (git-ignored; \`nola run\` applies it) and fill in
-\`${def.envVar}\` before the first \`npm start\`, or switch models in \`nola.config.ts\`.`
-  };
-}
+var OFFLINE_ONLY = ["nola.replay.jsonl"];
 async function ownVersion() {
   const pkg = JSON.parse(await readFile3(new URL("../package.json", import.meta.url), "utf8"));
   return pkg.version;
@@ -289,67 +280,42 @@ async function prepareTarget(absRoot, force) {
   if (!force) throw new Error(`target directory ${absRoot} is not empty`);
   for (const entry of entries) await rm2(join3(absRoot, entry), { recursive: true, force: true });
 }
+async function collectTemplate(def, version) {
+  if (def.source === "builtin") return collectExampleFromDisk(TEMPLATES_DIR, def.name);
+  const dev = await devExamplesDir();
+  return dev ? collectExampleFromDisk(dev, def.name) : fetchExampleFromGitHub(def.name, version);
+}
 async function scaffold(targetDir, opts = {}) {
   const root = targetDir;
   const absRoot = resolve(targetDir);
   const template = opts.template ?? "feature-extraction";
   const def = templateByName(template);
   if (!def) throw new Error(`unknown template "${template}" (valid: ${templateNames().join(", ")})`);
+  const version = await ownVersion();
+  const files = await collectTemplate(def, version);
   await prepareTarget(absRoot, opts.force ?? false);
   const name = opts.name ?? basename(absRoot);
-  const version = await ownVersion();
-  const envVar = vendorEnvVar(template, opts.provider ?? "none");
-  if (def.source === "example") {
-    const dev = await devExamplesDir();
-    const exampleFiles = await withRecommendedGitignore(
-      dev ? await collectExampleFromDisk(dev, template) : await fetchExampleFromGitHub(template, version)
-    );
-    const manifest = exampleFiles.get("package.json");
-    if (manifest) exampleFiles.set("package.json", rewriteExamplePackageJson(manifest, { name, version }));
-    if (envVar !== void 0 && !exampleFiles.has(".env.example")) exampleFiles.set(".env.example", envExample(envVar));
-    for (const [relPath, content] of exampleFiles) {
-      const target = join3(absRoot, relPath);
-      await mkdir2(join3(target, ".."), { recursive: true });
-      await writeFile2(target, content);
-    }
-    return { root, files: [...exampleFiles.keys()].sort() };
-  }
-  const templateRoot = join3(TEMPLATES_DIR, template);
-  const versionRange = `^${version}`;
   const provider = opts.provider ?? "none";
-  const notes = readmeNotes(provider);
-  const nextSteps2 = nextStepsComment(opts.ide ?? "none", template);
-  const files = [];
-  const copyDir = async (fromDir, relDir) => {
-    await mkdir2(join3(absRoot, relDir), { recursive: true });
-    for (const entry of await readdir2(join3(templateRoot, fromDir), { withFileTypes: true })) {
-      const fromRel = join3(fromDir, entry.name);
-      if (entry.isDirectory()) {
-        await copyDir(fromRel, join3(relDir, entry.name));
-        continue;
-      }
-      const toName = RENAMES[entry.name] ?? entry.name;
-      if (provider !== "none" && OFFLINE_ONLY.has(entry.name)) continue;
-      const toRel = join3(relDir, toName);
-      const source = provider !== "none" && relDir === "." && entry.name === "nola.config.ts" ? providerConfigUrl(provider) : join3(templateRoot, fromRel);
-      let content = await readFile3(source, "utf8");
-      if (SUBSTITUTED.has(entry.name)) {
-        content = content.replaceAll("__NAME__", name).replaceAll("__VERSION__", versionRange).replaceAll("__START_NOTE__", notes.START_NOTE).replaceAll("__PROVIDER_NOTE__", notes.PROVIDER_NOTE).replaceAll("__NEXT_STEPS__", nextSteps2);
-      }
-      await writeFile2(join3(absRoot, toRel), content);
-      files.push(toRel.replaceAll("\\", "/"));
-    }
-  };
-  await copyDir(".", ".");
-  if (!files.includes(".gitignore")) {
-    await writeFile2(join3(absRoot, ".gitignore"), await readFile3(GITIGNORE_URL, "utf8"));
-    files.push(".gitignore");
-  }
-  if (envVar !== void 0) {
-    await writeFile2(join3(absRoot, ".env.example"), envExample(envVar));
-    files.push(".env.example");
+  if (provider !== "none") {
+    for (const offline of OFFLINE_ONLY) files.delete(offline);
+    files.set("nola.config.ts", await readFile3(providerConfigUrl(provider), "utf8"));
+  }
+  const manifest = files.get("package.json");
+  if (manifest) files.set("package.json", rewriteExamplePackageJson(manifest, { name, version }));
+  await withRecommendedGitignore(files);
+  const envVar = vendorEnvVar(template, provider);
+  if (envVar !== void 0 && !files.has(".env.example")) files.set(".env.example", envExample(envVar));
+  const entry = entryFile(template);
+  const program = files.get(entry);
+  if (program !== void 0) files.set(entry, `${nextStepsComment(opts.ide ?? "none", template)}
+
+${program}`);
+  for (const [relPath, content] of files) {
+    const target = join3(absRoot, relPath);
+    await mkdir2(join3(target, ".."), { recursive: true });
+    await writeFile2(target, content);
   }
-  return { root, files: files.sort() };
+  return { root, files: [...files.keys()].sort() };
 }
 
 // src/add.ts
@@ -1571,7 +1537,7 @@ function nodeVersionWarning(version = process.versions.node) {
   if (nodeSupportsTypeStripping(version)) return void 0;
   const lines = [
     `Node ${version} is older than Nola needs: Node >= ${NODE_FLOOR}, the first release that runs .ts files natively.`,
-    "On this Node, `npm start` and the VS Code F5 launch fail with ERR_UNKNOWN_FILE_EXTENSION for src/main.ts."
+    "On this Node, `npm start` and the VS Code F5 launch fail with ERR_UNKNOWN_FILE_EXTENSION on the first plain .ts file they load."
   ];
   if (hasStripTypesFlag(version)) {
     lines.push(
@@ -1614,15 +1580,15 @@ var TEMPLATE_QUESTION = "Select a template:";
 var EXAMPLE_QUESTION = "Select an example:";
 var MORE_EXAMPLES = "more-examples";
 var BACK = "back";
-var builtinNames = () => TEMPLATES.filter((t) => t.source === "builtin").map((t) => `"${t.name}"`).join(", ");
 function templateMenu() {
   const featured = featuredNames().map((name) => templateOption(templateByName(name)));
   return [...featured, { value: MORE_EXAMPLES, label: "More examples\u2026", hint: exampleNames().join(", ") }];
 }
 function exampleMenu() {
   const examples = exampleNames().map((name) => templateOption(templateByName(name)));
-  return [...examples, { value: BACK, label: "\u2190 Back", hint: "the builtin templates" }];
+  return [...examples, { value: BACK, label: "\u2190 Back", hint: "the first menu" }];
 }
+var FETCH_FAILURE_HINT = 'Only "empty" ships inside the CLI and needs no download \u2014 every other template is fetched from GitHub.';
 async function selectTemplate(prompter) {
   for (; ; ) {
     const choice = await prompter.select(TEMPLATE_QUESTION, templateMenu());
@@ -1832,7 +1798,7 @@ function plainPrompter() {
 var FLOW_OPTIONS = {
   template: {
     type: "string",
-    description: "template to scaffold (feature-extraction, function-calling, typescript-interop, empty, or a curated example)"
+    description: "template to scaffold: feature-extraction (the default), function-calling, agent-loop, typescript-interop, triage-ticket, empty, or another curated example"
   },
   add: { type: "boolean", description: "add Nola to the existing project in [dir] instead of scaffolding" },
   ide: { type: "string", description: "editor setup: vscode (the default) | none" },
@@ -2070,7 +2036,7 @@ Next steps:
     } catch (err) {
       if (err instanceof ExampleFetchError && interactive) {
         prompter.note(`${err.message}
-The builtin templates (${builtinNames()}) work offline.`);
+${FETCH_FAILURE_HINT}`);
         input.dir = outcome.dir;
         input.template = void 0;
         continue;

package/dist/examples.d.ts

@@ -3,8 +3,10 @@ export declare function devExamplesDir(): Promise<string | null>;
 /** rel-path → content for one example, from the dev checkout's examples dir. */
 export declare function collectExampleFromDisk(examplesDir: string, name: string): Promise<Map<string, string>>;
 /**
- * Structured rewrite for a scaffolded example's package.json — examples stay
- * runnable workspaces in-repo, so they carry no __NAME__ placeholders.
+ * Structured rewrite for a scaffolded template's package.json — examples stay
+ * runnable workspaces in-repo (and `empty` follows their convention), so no
+ * template carries __NAME__ placeholders: the name is set here and the
+ * workspace `*` ranges become the lockstep `^<version>`.
  */
 export declare function rewriteExamplePackageJson(content: string, opts: {
     name: string;

package/dist/examples.js

@@ -33,8 +33,10 @@ export async function collectExampleFromDisk(examplesDir, name) {
     return files;
 }
 /**
- * Structured rewrite for a scaffolded example's package.json — examples stay
- * runnable workspaces in-repo, so they carry no __NAME__ placeholders.
+ * Structured rewrite for a scaffolded template's package.json — examples stay
+ * runnable workspaces in-repo (and `empty` follows their convention), so no
+ * template carries __NAME__ placeholders: the name is set here and the
+ * workspace `*` ranges become the lockstep `^<version>`.
  */
 export function rewriteExamplePackageJson(content, opts) {
     const pkg = JSON.parse(content);

package/dist/flow.d.ts

@@ -97,10 +97,16 @@ export declare const EXAMPLE_QUESTION = "Select an example:";
 export declare const MORE_EXAMPLES = "more-examples";
 /** the examples menu's last row — back to the first menu */
 export declare const BACK = "back";
-/** The first menu: the builtin templates and the featured example in registry order, then the examples row. */
+/** The first menu: the featured examples and `empty` in registry order, then the examples row. */
 export declare function templateMenu(): PrompterOption[];
 /** The second menu: the curated examples the first menu does not carry, in registry order, then Back. */
 export declare function exampleMenu(): PrompterOption[];
+/**
+ * The note a failed example fetch gets (interactive: the menu is asked
+ * again). Only `empty` ships inside the CLI; every other template is fetched
+ * from GitHub, so an offline machine can still scaffold that one.
+ */
+export declare const FETCH_FAILURE_HINT = "Only \"empty\" ships inside the CLI and needs no download \u2014 every other template is fetched from GitHub.";
 export declare const PROVIDER_QUESTION = "Select an inference provider:";
 /** `nola key`'s confirmation before the browser opens (the scaffold's consent is the provider select itself). */
 export declare const SIGN_IN_QUESTION = "This machine already used its 25 free Nola runs. Sign in to get an API key for this project?";
@@ -132,7 +138,7 @@ export interface RunFlowArgs {
 export declare const FLOW_OPTIONS: {
     readonly template: {
         readonly type: "string";
-        readonly description: "template to scaffold (feature-extraction, function-calling, typescript-interop, empty, or a curated example)";
+        readonly description: "template to scaffold: feature-extraction (the default), function-calling, agent-loop, typescript-interop, triage-ticket, empty, or another curated example";
     };
     readonly add: {
         readonly type: "boolean";

package/dist/flow.js

@@ -18,7 +18,7 @@ import { nodeVersionWarning } from "./node-version.js";
 import { openBrowser } from "./open-url.js";
 import { detectPackageManager, packageManagerCommands } from "./package-manager.js";
 import { isProviderId, PROVIDERS, providerById, providerIds } from "./providers.js";
-import { entryFile, exampleNames, featuredNames, TEMPLATES, templateByName, templateNames } from "./registry.js";
+import { entryFile, exampleNames, featuredNames, templateByName, templateNames } from "./registry.js";
 import { ownVersion, scaffold, vendorEnvVar } from "./scaffold.js";
 import { applyTrial } from "./trial.js";
 const DEFAULT_DIR = "nola-app";
@@ -62,9 +62,10 @@ function templateOption(t) {
 /*
  * The template step is TWO menus (clack's select has no sections): the first
  * lists the first-menu templates — feature-extraction, function-calling,
- * typescript-interop, triage-ticket (the featured example), empty — and one
- * "More examples…" row; that row opens the remaining curated examples, with a
- * Back row to return. `--template <name>` answers either level directly.
+ * agent-loop, typescript-interop, triage-ticket (the featured examples),
+ * empty (the one builtin) — and one "More examples…" row; that row opens the
+ * remaining curated examples, with a Back row to return. `--template <name>`
+ * answers either level directly.
  */
 export const TEMPLATE_QUESTION = "Select a template:";
 export const EXAMPLE_QUESTION = "Select an example:";
@@ -72,11 +73,7 @@ export const EXAMPLE_QUESTION = "Select an example:";
 export const MORE_EXAMPLES = "more-examples";
 /** the examples menu's last row — back to the first menu */
 export const BACK = "back";
-/** `"feature-extraction", "function-calling", …` — for the fetch-failure note. */
-const builtinNames = () => TEMPLATES.filter((t) => t.source === "builtin")
-    .map((t) => `"${t.name}"`)
-    .join(", ");
-/** The first menu: the builtin templates and the featured example in registry order, then the examples row. */
+/** The first menu: the featured examples and `empty` in registry order, then the examples row. */
 export function templateMenu() {
     const featured = featuredNames().map((name) => templateOption(templateByName(name)));
     return [...featured, { value: MORE_EXAMPLES, label: "More examples…", hint: exampleNames().join(", ") }];
@@ -84,8 +81,14 @@ export function templateMenu() {
 /** The second menu: the curated examples the first menu does not carry, in registry order, then Back. */
 export function exampleMenu() {
     const examples = exampleNames().map((name) => templateOption(templateByName(name)));
-    return [...examples, { value: BACK, label: "← Back", hint: "the builtin templates" }];
+    return [...examples, { value: BACK, label: "← Back", hint: "the first menu" }];
 }
+/**
+ * The note a failed example fetch gets (interactive: the menu is asked
+ * again). Only `empty` ships inside the CLI; every other template is fetched
+ * from GitHub, so an offline machine can still scaffold that one.
+ */
+export const FETCH_FAILURE_HINT = 'Only "empty" ships inside the CLI and needs no download — every other template is fetched from GitHub.';
 /** Ask the two-level template menu until a template is chosen; null = cancelled. */
 async function selectTemplate(prompter) {
     for (;;) {
@@ -370,7 +373,7 @@ export function plainPrompter() {
 export const FLOW_OPTIONS = {
     template: {
         type: "string",
-        description: "template to scaffold (feature-extraction, function-calling, typescript-interop, empty, or a curated example)",
+        description: "template to scaffold: feature-extraction (the default), function-calling, agent-loop, typescript-interop, triage-ticket, empty, or another curated example",
     },
     add: { type: "boolean", description: "add Nola to the existing project in [dir] instead of scaffolding" },
     ide: { type: "string", description: "editor setup: vscode (the default) | none" },
@@ -675,7 +678,7 @@ export async function runFlow(args, opts = {}) {
         }
         catch (err) {
             if (err instanceof ExampleFetchError && interactive) {
-                prompter.note(`${err.message}\nThe builtin templates (${builtinNames()}) work offline.`);
+                prompter.note(`${err.message}\n${FETCH_FAILURE_HINT}`);
                 input.dir = outcome.dir; // keep the chosen dir, re-pick the template
                 input.template = undefined;
                 continue;

package/dist/github.d.ts

@@ -1,4 +1,4 @@
-/** Network/acquisition failure — the builtin templates always work offline. */
+/** Network/acquisition failure — `empty`, the one builtin template, always works offline. */
 export declare class ExampleFetchError extends Error {
 }
 export type FetchLike = (url: string) => Promise<{

package/dist/github.js

@@ -1,6 +1,6 @@
 /** Production example acquisition: GitHub Trees API + raw file fetches. */
 const REPO = "nola-lang/nola";
-/** Network/acquisition failure — the builtin templates always work offline. */
+/** Network/acquisition failure — `empty`, the one builtin template, always works offline. */
 export class ExampleFetchError extends Error {
 }
 /** Try the lockstep release tag first; a repo without that tag serves main. */

package/dist/index.js

@@ -87,7 +87,7 @@ import {
   writeEnvKey,
   writeSession,
   writeVscodeSetup
-} from "./chunk-LUSVIOAN.js";
+} from "./chunk-CB26Z47Y.js";
 import {
   clackPrompter
 } from "./chunk-7IQIRMK6.js";

package/dist/launch.d.ts

@@ -17,7 +17,7 @@ export interface Launcher {
     /**
      * `code <dir> [<dir>/<entry>]`, detached; "not-found" when VS Code's `code`
      * command is not on PATH. `entry` is a project-relative file to open as the
-     * active editor on top of the folder (the scaffold's src/main.ts).
+     * active editor on top of the folder (the template's entry file).
      */
     openVscode(dir: string, entry?: string): Promise<"opened" | "not-found">;
 }
@@ -25,7 +25,7 @@ export interface Launcher {
  * The arguments that open a project in VS Code: the folder alone, or the
  * folder plus one file. `code <folder> <file>` opens the folder as the
  * workspace and the file as the active editor — that is how the scaffold
- * lands the user on src/main.ts instead of an empty window.
+ * lands the user on the entry file instead of an empty window.
  */
 export declare function vscodeArgs(dir: string, entry?: string): string[];
 /**

package/dist/launch.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
  * The arguments that open a project in VS Code: the folder alone, or the
  * folder plus one file. `code <folder> <file>` opens the folder as the
  * workspace and the file as the active editor — that is how the scaffold
- * lands the user on src/main.ts instead of an empty window.
+ * lands the user on the entry file instead of an empty window.
  */
 export function vscodeArgs(dir, entry) {
     return entry === undefined ? [dir] : [dir, join(dir, entry)];

package/dist/main.js

@@ -3,7 +3,7 @@ import {
   CREATE_COMMAND,
   dispatch,
   ownVersion
-} from "./chunk-LUSVIOAN.js";
+} from "./chunk-CB26Z47Y.js";
 import "./chunk-FPS2V3S4.js";
 
 // src/main.ts

package/dist/node-version.d.ts

@@ -1,6 +1,7 @@
 /**
- * The Node floor the docs state. Plain `.ts` (the templates' `src/main.ts`)
- * is loaded by Node's native type stripping, which is on by default only from
+ * The Node floor the docs state. Plain `.ts` (an example's `src/main.ts`, or the
+ * plain modules a `.tsi` entry imports) is loaded by Node's native type
+ * stripping, which is on by default only from
  * 22.18 on the 22 line and 23.6 on the 23 line; before that it sits behind
  * `--experimental-strip-types` and the default loader rejects `.ts` outright
  * (ERR_UNKNOWN_FILE_EXTENSION) — `npm start` and the F5 launch both die on

package/dist/node-version.js

@@ -1,6 +1,7 @@
 /**
- * The Node floor the docs state. Plain `.ts` (the templates' `src/main.ts`)
- * is loaded by Node's native type stripping, which is on by default only from
+ * The Node floor the docs state. Plain `.ts` (an example's `src/main.ts`, or the
+ * plain modules a `.tsi` entry imports) is loaded by Node's native type
+ * stripping, which is on by default only from
  * 22.18 on the 22 line and 23.6 on the 23 line; before that it sits behind
  * `--experimental-strip-types` and the default loader rejects `.ts` outright
  * (ERR_UNKNOWN_FILE_EXTENSION) — `npm start` and the F5 launch both die on
@@ -47,7 +48,7 @@ export function nodeVersionWarning(version = process.versions.node) {
         return undefined;
     const lines = [
         `Node ${version} is older than Nola needs: Node >= ${NODE_FLOOR}, the first release that runs .ts files natively.`,
-        "On this Node, `npm start` and the VS Code F5 launch fail with ERR_UNKNOWN_FILE_EXTENSION for src/main.ts.",
+        "On this Node, `npm start` and the VS Code F5 launch fail with ERR_UNKNOWN_FILE_EXTENSION on the first plain .ts file they load.",
     ];
     if (hasStripTypesFlag(version)) {
         lines.push("Upgrade Node (recommended), or set NODE_OPTIONS=--experimental-strip-types for `npm start` and add", '"--experimental-strip-types" to runtimeArgs in .vscode/launch.json.');

package/dist/providers.d.ts

@@ -4,7 +4,7 @@
  * template registry: `nola` is the platform, labelled "nola: dev" so the row
  * reads as a mode of the project rather than a fourth vendor (the free trial, or a key on the
  * account — see `keyPath`), the four vendors write a bring-your-own config,
- * `none` is the offline default (the builtin templates replay their ledgers). typesafe.ai
+ * `none` is the offline default (the template's own config: a recorded ledger or a mock). typesafe.ai
  * serves literal unions and booleans only; it is listed for every template all
  * the same, and `providerOptions` (flow.ts) brackets that caveat into its hint.
  */

package/dist/providers.js

@@ -10,7 +10,7 @@ export const PROVIDERS = [
     },
     { id: "google", label: "Gemini", hint: 'google("gemini-2.5-flash"), reads GEMINI_API_KEY', envVar: "GEMINI_API_KEY", model: 'google("gemini-2.5-flash")' },
     { id: "typesafe", label: "typesafe.ai", hint: "typesafe(), reads TYPESAFE_API_KEY", envVar: "TYPESAFE_API_KEY", model: "typesafe()" },
-    { id: "none", label: "Skip for now", hint: "the builtin templates run offline from a replay ledger; pick a model in nola.config.ts later" },
+    { id: "none", label: "Skip for now", hint: "keeps the template's own config (the recorded ones run offline); pick a model in nola.config.ts later" },
 ];
 export function providerById(id) {
     return PROVIDERS.find((p) => p.id === id);

package/dist/registry.d.ts

@@ -2,31 +2,40 @@
  * The template menu. Static by design: it is versioned in lockstep with the
  * git tag the example fetcher pulls from, so names and labels cannot drift.
  *
+ * `empty` is the ONLY builtin template (config + tsconfig + a stub entry,
+ * shipped inside this package). Every other template IS a curated example:
+ * its files come from `examples/` — on disk in a dev checkout, from GitHub
+ * (the lockstep release tag) in production — and the scaffolder adds the
+ * project name, the lockstep ranges, the recommended `.gitignore`, the
+ * chosen provider's config and the next-steps comment on top.
+ *
  * The first menu leads (in this order) and is organized BY FEATURE:
  * `feature-extraction` (the default) and `function-calling` are each one
  * `.tsi` file with a top-level ask — the two things Nola does —
+ * `agent-loop` is the same shape around a top-level `while`,
  * `typescript-interop` is the infer-function shape called from plain
- * TypeScript, `triage-ticket` (a FEATURED example: fetched from examples/
- * like the rest, listed here because it is the one-file shape on a
- * non-chat vendor) and `empty`. The other curated examples follow (behind
- * "More examples…"). extract-person is deliberately absent —
- * typescript-interop IS extract-person plus the replay ledger.
+ * TypeScript, `triage-ticket` the one-file shape on a non-chat vendor, then
+ * `empty` (a stub `src/main.tsi` to write your own in). The other curated
+ * examples follow (behind "More examples…").
+ * extract-person is deliberately absent — typescript-interop IS
+ * extract-person plus the replay ledger.
  */
 export interface TemplateDef {
     name: string;
     /** one-line menu description */
     label: string;
+    /** where the files come from: this package's `templates/` dir, or `examples/` */
     source: "builtin" | "example";
     /**
-     * An example listed on the FIRST menu, in registry order beside the
-     * builtin templates, instead of behind "More examples…". Its files still
-     * come from examples/ (`source` is unchanged).
+     * An example listed on the FIRST menu, in registry order beside `empty`,
+     * instead of behind "More examples…". Its files still come from examples/
+     * (`source` is unchanged).
      */
     featured?: true;
     /**
      * The file that IS the program — what `start` runs, launch.json's
      * `program`, what VS Code opens, where the next-steps comment lands.
-     * Absent = the plain-TS `src/main.ts` every other template has.
+     * Absent = the plain-TS `src/main.ts` the other examples have.
      */
     entry?: string;
     /**
@@ -43,7 +52,7 @@ export interface TemplateDef {
 /** What a template runs unless it names its own entry: the plain-TS main. */
 export declare const DEFAULT_ENTRY = "src/main.ts";
 export declare const TEMPLATES: readonly TemplateDef[];
-/** The first menu's templates: the builtins and the featured example, in registry order. */
+/** The first menu's templates: the featured examples and `empty`, in registry order. */
 export declare function featuredNames(): string[];
 /** The examples behind "More examples…": every example the first menu does not carry. */
 export declare function exampleNames(): string[];

package/dist/registry.js

@@ -1,17 +1,32 @@
 /** What a template runs unless it names its own entry: the plain-TS main. */
 export const DEFAULT_ENTRY = "src/main.ts";
 export const TEMPLATES = [
-    { name: "feature-extraction", label: "extract typed data from context", source: "builtin", entry: "src/main.tsi" },
+    {
+        name: "feature-extraction",
+        label: "extract typed data from context",
+        source: "example",
+        featured: true,
+        entry: "src/main.tsi",
+    },
     {
         name: "function-calling",
         label: "call an async function from a TypeScript file",
-        source: "builtin",
+        source: "example",
+        featured: true,
+        entry: "src/main.tsi",
+    },
+    {
+        name: "agent-loop",
+        label: "an agent loop in one .tsi file: a top-level while with an ask, and a context statement read on every pass",
+        source: "example",
+        featured: true,
         entry: "src/main.tsi",
     },
     {
         name: "typescript-interop",
         label: "an infer function example, imported and awaited from plain TypeScript",
-        source: "builtin",
+        source: "example",
+        featured: true,
     },
     {
         name: "triage-ticket",
@@ -21,7 +36,7 @@ export const TEMPLATES = [
         entry: "src/main.tsi",
         provider: { label: "typesafe.ai", envVar: "TYPESAFE_API_KEY" },
     },
-    { name: "empty", label: "nola.config + tsconfig only, bring your own code", source: "builtin" },
+    { name: "empty", label: "nola.config + tsconfig only, bring your own code", source: "builtin", entry: "src/main.tsi" },
     { name: "file-ticket", label: "call intents: the model fills a function's arguments", source: "example" },
     { name: "extract-resume", label: "nested arrays of objects, JSDoc schema descriptions", source: "example" },
     { name: "extract-invoice", label: "same-file type references, optional fields", source: "example" },
@@ -29,7 +44,7 @@ export const TEMPLATES = [
     { name: "chain-of-thought", label: "two asks sharing accumulating context", source: "example" },
     { name: "research-notes", label: "TS control flow orchestrating nola functions", source: "example" },
 ];
-/** The first menu's templates: the builtins and the featured example, in registry order. */
+/** The first menu's templates: the featured examples and `empty`, in registry order. */
 export function featuredNames() {
     return TEMPLATES.filter((t) => t.source === "builtin" || t.featured).map((t) => t.name);
 }