create-nola-lang 0.1.14 → 0.1.15

package/dist/add.d.ts

@@ -1,3 +1,4 @@
+import type { Runtime } from "./package-manager.js";
 import { type ProviderId } from "./providers.js";
 export interface AddResult {
     /** files written, e.g. ["nola.config.ts", "package.json"] */
@@ -17,6 +18,8 @@ export interface AddOptions {
      * empty template's — the nola key step rewrites it afterwards (`applyTrial`).
      */
     provider?: ProviderId;
+    /** "bun" also merges @nola-lang/bun into devDependencies; the bunfig lines are suggested by the flow's outro, never written */
+    runtime?: Runtime;
 }
 /**
  * Retrofit an existing npm project: write nola.config.ts (unless present) and

package/dist/add.js

@@ -61,7 +61,8 @@ export async function addNola(targetDir, opts = {}) {
         await writeFile(configPath, await readFile(vendor ? providerConfigUrl(vendor.id) : EMPTY_CONFIG_URL, "utf8"));
         wrote.push("nola.config.ts");
     }
-    for (const [section, name, fixedRange] of REQUIRED) {
+    const required = opts.runtime === "bun" ? [...REQUIRED, ["devDependencies", "@nola-lang/bun", null]] : REQUIRED;
+    for (const [section, name, fixedRange] of required) {
         const existing = existingRange(name);
         if (existing !== undefined) {
             skipped.push(`${name} already present (${existing}) — left untouched`);

package/dist/checkout.js

@@ -28,6 +28,7 @@ export async function checkoutRoot() {
 const LINKS = [
     ["@nola-lang/runtime", "runtime"],
     ["@nola-lang/providers", "providers"],
+    ["@nola-lang/bun", "bun"],
     ["nola-lang", "nola-lang"],
 ];
 /**

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

@@ -52,6 +52,7 @@ async function checkoutRoot() {
 var LINKS = [
   ["@nola-lang/runtime", "runtime"],
   ["@nola-lang/providers", "providers"],
+  ["@nola-lang/bun", "bun"],
   ["nola-lang", "nola-lang"]
 ];
 var LINK_CHECKOUT_ENV = "NOLA_LINK_CHECKOUT";
@@ -184,6 +185,13 @@ var TEMPLATES = [
     featured: true,
     entry: "src/main.tsi"
   },
+  {
+    name: "tool-use",
+    label: "offer functions as tools: the model calls them as it needs before it answers",
+    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",
@@ -246,17 +254,34 @@ function envExample(envVar) {
 ${envVar}=
 `;
 }
+var BUNFIG_TOML = 'preload = ["@nola-lang/bun/preload"]\n\n[test]\npreload = ["@nola-lang/bun/preload"]\n';
+var BUN_ENGINE = ">=1.3.0";
+function applyBunRuntime(content, opts) {
+  const pkg = JSON.parse(content);
+  const scripts = pkg.scripts ?? {};
+  scripts.start = `bun ${opts.entry}`;
+  pkg.scripts = scripts;
+  const dev = pkg.devDependencies ?? {};
+  dev["@nola-lang/bun"] = `^${opts.version}`;
+  pkg.devDependencies = dev;
+  const engines = pkg.engines ?? {};
+  engines.bun = BUN_ENGINE;
+  pkg.engines = engines;
+  return `${JSON.stringify(pkg, null, 2)}
+`;
+}
 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;
 }
-function nextStepsComment(ide, template) {
+function nextStepsComment(ide, template, runtime = "node") {
   if (ide === "vscode") {
     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";
+    const runLine = runtime === "bun" ? "//   1. Run this file: bun start (F5 runs it too, under Node's loader \u2014 .vscode/launch.json is already set up)." : "//   1. Press F5 to run this file (.vscode/launch.json is already set up).";
     return [
       "// Next steps in VS Code:",
-      "//   1. Press F5 to run this file (.vscode/launch.json is already set up).",
+      runLine,
       `//   2. Set a breakpoint ${breakpointIn} and press F5 again to step through the ask.`,
       '//   3. Install the recommended "Nola" extension when VS Code offers it \u2014 IntelliSense,',
       "//      go to definition and diagnostics inside .tsi files."
@@ -264,7 +289,7 @@ function nextStepsComment(ide, template) {
   }
   return [
     "// Next steps:",
-    "//   1. Run this file: npm start",
+    `//   1. Run this file: ${runtime === "bun" ? "bun start" : "npm start"}`,
     "//   2. Set up your editor (VS Code extension, debugging): https://nola.sh/docs/start/editor-setup/"
   ].join("\n");
 }
@@ -296,18 +321,24 @@ async function scaffold(targetDir, opts = {}) {
   await prepareTarget(absRoot, opts.force ?? false);
   const name = opts.name ?? basename(absRoot);
   const provider = opts.provider ?? "none";
+  const runtime = opts.runtime ?? "node";
+  const entry = entryFile(template);
   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 }));
+  if (runtime === "bun") {
+    files.set("bunfig.toml", BUNFIG_TOML);
+    const current = files.get("package.json");
+    if (current !== void 0) files.set("package.json", applyBunRuntime(current, { entry, 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)}
+  if (program !== void 0) files.set(entry, `${nextStepsComment(opts.ide ?? "none", template, runtime)}
 
 ${program}`);
   for (const [relPath, content] of files) {
@@ -368,7 +399,8 @@ async function addNola(targetDir, opts = {}) {
     await writeFile3(configPath, await readFile4(vendor ? providerConfigUrl(vendor.id) : EMPTY_CONFIG_URL, "utf8"));
     wrote.push("nola.config.ts");
   }
-  for (const [section, name, fixedRange] of REQUIRED) {
+  const required = opts.runtime === "bun" ? [...REQUIRED, ["devDependencies", "@nola-lang/bun", null]] : REQUIRED;
+  for (const [section, name, fixedRange] of required) {
     const existing = existingRange(name);
     if (existing !== void 0) {
       skipped.push(`${name} already present (${existing}) \u2014 left untouched`);
@@ -1558,6 +1590,12 @@ function detectPackageManager(userAgent = process.env.npm_config_user_agent) {
 function packageManagerCommands(pm) {
   return { install: `${pm} install`, start: `${pm} start`, run: `${pm} run` };
 }
+function isRuntime(value) {
+  return value === "node" || value === "bun";
+}
+function defaultRuntime(pm) {
+  return pm === "bun" ? "bun" : "node";
+}
 
 // src/flow.ts
 var DEFAULT_DIR = "nola-app";
@@ -1674,11 +1712,18 @@ async function resolveProvider(input, prompter, template) {
     return choice;
   }
 }
+function resolveRuntime(input) {
+  if (input.runtime !== void 0) {
+    if (!isRuntime(input.runtime)) throw new Error(`invalid --runtime "${input.runtime}" (valid: node, bun)`);
+    return input.runtime;
+  }
+  return defaultRuntime(input.packageManager ?? "npm");
+}
 async function resolveExtras(input, prompter, dir, template) {
   const provider = await resolveProvider(input, prompter, template);
   if (provider === null) return null;
   const setup = await resolveSetup(input, prompter, dir);
-  return setup === null ? null : { provider, ...setup };
+  return setup === null ? null : { provider, ...setup, runtime: resolveRuntime(input) };
 }
 async function resolveScaffoldOptions(input, prompter) {
   if (input.add && input.template) {
@@ -1689,6 +1734,9 @@ async function resolveScaffoldOptions(input, prompter) {
   if (input.ide !== void 0 && input.ide !== "vscode" && input.ide !== "none") {
     throw new Error(`invalid --ide "${input.ide}" (valid: vscode, none)`);
   }
+  if (input.runtime !== void 0 && !isRuntime(input.runtime)) {
+    throw new Error(`invalid --runtime "${input.runtime}" (valid: node, bun)`);
+  }
   if (input.agents !== void 0) parseAgentsFlag(input.agents);
   flaggedProvider(input);
   if (input.add) {
@@ -1802,6 +1850,10 @@ var FLOW_OPTIONS = {
   },
   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" },
+  runtime: {
+    type: "string",
+    description: "runtime the project runs on: node | bun (default: bun when bun ran the scaffolder \u2014 bunfig.toml preload + `bun src/main.tsi`)"
+  },
   agents: {
     type: "string",
     description: `agent skill files: ${AGENT_IDS.join(",")} | all | none (default: claude,universal)`
@@ -1961,6 +2013,8 @@ async function runFlow(args, opts = {}) {
     agents: args.agents,
     provider: args.provider,
     trial: args.trial,
+    runtime: args.runtime,
+    packageManager: pm,
     keyPath,
     signIn: signInNow,
     cwd: opts.cwd,
@@ -1974,7 +2028,7 @@ async function runFlow(args, opts = {}) {
     }
     if (outcome.kind === "add") {
       const grant = outcome.provider === "nola" ? await obtainTrial(prompter, opts, interactive) : null;
-      const result = await addNola(outcome.dir, { provider: outcome.provider });
+      const result = await addNola(outcome.dir, { provider: outcome.provider, runtime: outcome.runtime });
       const trial = grant ? await applyTrial(outcome.dir, { apiKey: grant.apiKey, hasConfig: !result.wrote.includes("nola.config.ts") }) : { wrote: [], skipped: [] };
       const ide = outcome.ide === "vscode" ? await writeVscodeSetup(outcome.dir) : { wrote: [], skipped: [] };
       const ag = outcome.agents.length > 0 ? await writeAgentSkills(outcome.dir, outcome.agents) : { wrote: [], removed: [], skipped: [] };
@@ -1987,7 +2041,10 @@ async function runFlow(args, opts = {}) {
       }
       const lines = [
         packageManagerCommands(pm).install,
-        'optional start script:  "start": "nola run src/main.ts"',
+        ...outcome.runtime === "bun" ? [
+          'bunfig.toml: preload = ["@nola-lang/bun/preload"] (runs .tsi from source under Bun)',
+          'optional start script:  "start": "bun src/main.ts"'
+        ] : ['optional start script:  "start": "nola run src/main.ts"'],
         'tsconfig tip: directory-style include (e.g. ["src"]) lets the editor see .tsi files',
         commented(CONSOLE_COMMAND, CONSOLE_NOTE)
       ];
@@ -2002,7 +2059,13 @@ Next steps:
     try {
       const grant = outcome.provider === "nola" ? await obtainTrial(prompter, opts, interactive) : null;
       const provider = outcome.provider === "nola" ? grant ? "nola" : "none" : outcome.provider;
-      const { files } = await scaffold(outcome.dir, { template: outcome.template, force: outcome.force, provider, ide: outcome.ide });
+      const { files } = await scaffold(outcome.dir, {
+        template: outcome.template,
+        force: outcome.force,
+        provider,
+        ide: outcome.ide,
+        runtime: outcome.runtime
+      });
       let trialWrote = [];
       if (grant) {
         const trial = await applyTrial(outcome.dir, { apiKey: grant.apiKey, hasConfig: false });

package/dist/flow.d.ts

@@ -1,7 +1,7 @@
 import { type AgentId } from "./agents.js";
 import { type CommandSpec } from "./cli.js";
 import { type Launcher } from "./launch.js";
-import { type PackageManager } from "./package-manager.js";
+import { type PackageManager, type Runtime } from "./package-manager.js";
 import { type ProviderId } from "./providers.js";
 export interface PrompterOption {
     value: string;
@@ -45,6 +45,10 @@ export interface FlowInput {
     provider?: string;
     /** --trial / --no-trial: shorthand for --provider nola / --provider none */
     trial?: boolean;
+    /** --runtime <node|bun>; undefined = bun when bun ran the scaffolder, else node */
+    runtime?: string;
+    /** the manager that invoked us — decides the default runtime */
+    packageManager?: PackageManager;
     /** how the nola row is worded, decided by runFlow from ~/.nola (spec 2026-09-04-cli-sign-in-design.md §5); default trial */
     keyPath?: KeyPath;
     /**
@@ -75,12 +79,14 @@ export type FlowOutcome = {
     provider: ProviderId;
     ide: "vscode" | "none";
     agents: AgentId[];
+    runtime: Runtime;
 } | {
     kind: "add";
     dir: string;
     provider: ProviderId;
     ide: "vscode" | "none";
     agents: AgentId[];
+    runtime: Runtime;
 } | {
     kind: "cancelled";
 };
@@ -130,6 +136,7 @@ export interface RunFlowArgs {
     agents?: string;
     provider?: string;
     trial?: boolean;
+    runtime?: string;
 }
 /**
  * The flow's flags, declared ONCE for both bins (`npm create nola-lang` and
@@ -148,6 +155,10 @@ export declare const FLOW_OPTIONS: {
         readonly type: "string";
         readonly description: "editor setup: vscode (the default) | none";
     };
+    readonly runtime: {
+        readonly type: "string";
+        readonly description: "runtime the project runs on: node | bun (default: bun when bun ran the scaffolder — bunfig.toml preload + `bun src/main.tsi`)";
+    };
     readonly agents: {
         readonly type: "string";
         readonly description: `agent skill files: ${string} | all | none (default: claude,universal)`;

package/dist/flow.js

@@ -16,7 +16,7 @@ import { acquireKey, SignInRequiredError } from "./key.js";
 import { realLauncher } from "./launch.js";
 import { nodeVersionWarning } from "./node-version.js";
 import { openBrowser } from "./open-url.js";
-import { detectPackageManager, packageManagerCommands } from "./package-manager.js";
+import { defaultRuntime, detectPackageManager, isRuntime, packageManagerCommands } from "./package-manager.js";
 import { isProviderId, PROVIDERS, providerById, providerIds } from "./providers.js";
 import { entryFile, exampleNames, featuredNames, templateByName, templateNames } from "./registry.js";
 import { ownVersion, scaffold, vendorEnvVar } from "./scaffold.js";
@@ -230,13 +230,22 @@ async function resolveProvider(input, prompter, template) {
         return choice;
     }
 }
+/** `--runtime`, else the manager's default (bun → bun). Validated up front like the other flags. */
+function resolveRuntime(input) {
+    if (input.runtime !== undefined) {
+        if (!isRuntime(input.runtime))
+            throw new Error(`invalid --runtime "${input.runtime}" (valid: node, bun)`);
+        return input.runtime;
+    }
+    return defaultRuntime(input.packageManager ?? "npm");
+}
 /** The provider and setup (editor + agents) questions, in that order, shared by every outcome site; null = cancelled. */
 async function resolveExtras(input, prompter, dir, template) {
     const provider = await resolveProvider(input, prompter, template);
     if (provider === null)
         return null;
     const setup = await resolveSetup(input, prompter, dir);
-    return setup === null ? null : { provider, ...setup };
+    return setup === null ? null : { provider, ...setup, runtime: resolveRuntime(input) };
 }
 /** Args fill prompts; whatever is missing is asked (never asked non-interactively). */
 export async function resolveScaffoldOptions(input, prompter) {
@@ -246,6 +255,9 @@ export async function resolveScaffoldOptions(input, prompter) {
     if (input.ide !== undefined && input.ide !== "vscode" && input.ide !== "none") {
         throw new Error(`invalid --ide "${input.ide}" (valid: vscode, none)`);
     }
+    if (input.runtime !== undefined && !isRuntime(input.runtime)) {
+        throw new Error(`invalid --runtime "${input.runtime}" (valid: node, bun)`);
+    }
     if (input.agents !== undefined)
         parseAgentsFlag(input.agents); // throws on unknown ids
     flaggedProvider(input); // throws on an unknown id or a contradiction
@@ -377,6 +389,10 @@ export const FLOW_OPTIONS = {
     },
     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" },
+    runtime: {
+        type: "string",
+        description: "runtime the project runs on: node | bun (default: bun when bun ran the scaffolder — bunfig.toml preload + `bun src/main.tsi`)",
+    },
     agents: {
         type: "string",
         description: `agent skill files: ${AGENT_IDS.join(",")} | all | none (default: claude,universal)`,
@@ -596,6 +612,8 @@ export async function runFlow(args, opts = {}) {
         agents: args.agents,
         provider: args.provider,
         trial: args.trial,
+        runtime: args.runtime,
+        packageManager: pm,
         keyPath,
         signIn: signInNow,
         cwd: opts.cwd,
@@ -609,7 +627,7 @@ export async function runFlow(args, opts = {}) {
         }
         if (outcome.kind === "add") {
             const grant = outcome.provider === "nola" ? await obtainTrial(prompter, opts, interactive) : null;
-            const result = await addNola(outcome.dir, { provider: outcome.provider });
+            const result = await addNola(outcome.dir, { provider: outcome.provider, runtime: outcome.runtime });
             const trial = grant
                 ? await applyTrial(outcome.dir, { apiKey: grant.apiKey, hasConfig: !result.wrote.includes("nola.config.ts") })
                 : { wrote: [], skipped: [] };
@@ -629,7 +647,12 @@ export async function runFlow(args, opts = {}) {
             }
             const lines = [
                 packageManagerCommands(pm).install,
-                'optional start script:  "start": "nola run src/main.ts"',
+                ...(outcome.runtime === "bun"
+                    ? [
+                        'bunfig.toml: preload = ["@nola-lang/bun/preload"] (runs .tsi from source under Bun)',
+                        'optional start script:  "start": "bun src/main.ts"',
+                    ]
+                    : ['optional start script:  "start": "nola run src/main.ts"']),
                 'tsconfig tip: directory-style include (e.g. ["src"]) lets the editor see .tsi files',
                 commented(CONSOLE_COMMAND, CONSOLE_NOTE),
             ];
@@ -644,7 +667,13 @@ export async function runFlow(args, opts = {}) {
             const grant = outcome.provider === "nola" ? await obtainTrial(prompter, opts, interactive) : null;
             // A nola choice without a key (declined sign-in, API failure) scaffolds the plain template — the note above says why.
             const provider = outcome.provider === "nola" ? (grant ? "nola" : "none") : outcome.provider;
-            const { files } = await scaffold(outcome.dir, { template: outcome.template, force: outcome.force, provider, ide: outcome.ide });
+            const { files } = await scaffold(outcome.dir, {
+                template: outcome.template,
+                force: outcome.force,
+                provider,
+                ide: outcome.ide,
+                runtime: outcome.runtime,
+            });
             let trialWrote = [];
             if (grant) {
                 const trial = await applyTrial(outcome.dir, { apiKey: grant.apiKey, hasConfig: false });

package/dist/index.js

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

package/dist/main.js

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

package/dist/package-manager.d.ts

@@ -14,4 +14,9 @@ export interface PackageManagerCommands {
     run: string;
 }
 export declare function packageManagerCommands(pm: PackageManager): PackageManagerCommands;
+/** The runtime a scaffold targets: Node (the loader, `nola run`) or Bun (`@nola-lang/bun`'s preload, `bun src/main.tsi`). */
+export type Runtime = "node" | "bun";
+export declare function isRuntime(value: string): value is Runtime;
+/** `bun create nola` produces a Bun project unless `--runtime node` says otherwise; every other manager scaffolds for Node. */
+export declare function defaultRuntime(pm: PackageManager): Runtime;
 //# sourceMappingURL=package-manager.d.ts.map

package/dist/package-manager.js

@@ -5,4 +5,11 @@ export function detectPackageManager(userAgent = process.env.npm_config_user_age
 export function packageManagerCommands(pm) {
     return { install: `${pm} install`, start: `${pm} start`, run: `${pm} run` };
 }
+export function isRuntime(value) {
+    return value === "node" || value === "bun";
+}
+/** `bun create nola` produces a Bun project unless `--runtime node` says otherwise; every other manager scaffolds for Node. */
+export function defaultRuntime(pm) {
+    return pm === "bun" ? "bun" : "node";
+}
 //# sourceMappingURL=package-manager.js.map

package/dist/registry.d.ts

@@ -10,8 +10,8 @@
  * 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 —
+ * `feature-extraction` (the default), `function-calling` and `tool-use` are
+ * each one `.tsi` file with a top-level ask — the three 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` the one-file shape on a non-chat vendor, then

package/dist/registry.js

@@ -15,6 +15,13 @@ export const TEMPLATES = [
         featured: true,
         entry: "src/main.tsi",
     },
+    {
+        name: "tool-use",
+        label: "offer functions as tools: the model calls them as it needs before it answers",
+        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",

package/dist/scaffold.d.ts

@@ -1,3 +1,4 @@
+import type { Runtime } from "./package-manager.js";
 import { type ProviderId } from "./providers.js";
 export interface ScaffoldResult {
     root: string;
@@ -23,6 +24,12 @@ export interface ScaffoldOptions {
      * files the flow writes make true); without one it stays editor-neutral.
      */
     ide?: "vscode" | "none";
+    /**
+     * The runtime the project runs on; default "node". "bun" adds bunfig.toml with the
+     * @nola-lang/bun preload, a `bun <entry>` start script, the devDependency and
+     * engines.bun — build/check stay the Node CLI (spec 2026-10-14-bun-support).
+     */
+    runtime?: Runtime;
 }
 /** The config a live provider choice writes over the template's own (`templates/_providers/<id>.config.ts`). */
 export declare function providerConfigUrl(provider: Exclude<ProviderId, "none">): URL;
@@ -39,6 +46,15 @@ export declare function vendorEnvVar(template: string, provider: ProviderId): st
  * `.gitignore` keeps trackable (`!.env.example`), so it can be committed.
  */
 export declare function envExample(envVar: string): string;
+/** The Bun project's bunfig.toml: the preload for `bun src/main.tsi` and for `bun test`. */
+export declare const BUNFIG_TOML = "preload = [\"@nola-lang/bun/preload\"]\n\n[test]\npreload = [\"@nola-lang/bun/preload\"]\n";
+/** The Bun floor @nola-lang/bun needs (process.getBuiltinModule). */
+export declare const BUN_ENGINE = ">=1.3.0";
+/** A Bun project's manifest additions on top of the template's: the start script, the devDependency, engines.bun. */
+export declare function applyBunRuntime(content: string, opts: {
+    entry: string;
+    version: string;
+}): string;
 /**
  * Add the recommended `.gitignore` to a template's files. Templates are
  * copied as committed — examples from `examples/`, where the monorepo's root
@@ -53,7 +69,7 @@ export declare function withRecommendedGitignore(files: Map<string, string>): Pr
  * the editor step's .vscode files, which are what make F5 and the extension
  * prompt real.
  */
-export declare function nextStepsComment(ide: "vscode" | "none", template: string): string;
+export declare function nextStepsComment(ide: "vscode" | "none", template: string, runtime?: Runtime): string;
 export declare function ownVersion(): Promise<string>;
 /**
  * Lay a template down into `targetDir`. One implementation serves both entry

package/dist/scaffold.js

@@ -29,6 +29,24 @@ export function vendorEnvVar(template, provider) {
 export function envExample(envVar) {
     return `# Copy to .env and fill in — \`nola run\` applies .env before evaluating nola.config.ts.\n${envVar}=\n`;
 }
+/** The Bun project's bunfig.toml: the preload for `bun src/main.tsi` and for `bun test`. */
+export const BUNFIG_TOML = 'preload = ["@nola-lang/bun/preload"]\n\n[test]\npreload = ["@nola-lang/bun/preload"]\n';
+/** The Bun floor @nola-lang/bun needs (process.getBuiltinModule). */
+export const BUN_ENGINE = ">=1.3.0";
+/** A Bun project's manifest additions on top of the template's: the start script, the devDependency, engines.bun. */
+export function applyBunRuntime(content, opts) {
+    const pkg = JSON.parse(content);
+    const scripts = pkg.scripts ?? {};
+    scripts.start = `bun ${opts.entry}`;
+    pkg.scripts = scripts;
+    const dev = pkg.devDependencies ?? {};
+    dev["@nola-lang/bun"] = `^${opts.version}`;
+    pkg.devDependencies = dev;
+    const engines = pkg.engines ?? {};
+    engines.bun = BUN_ENGINE;
+    pkg.engines = engines;
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}
 /** The ONE recommended .gitignore — every scaffold gets it; no template keeps a copy of its own (_gitignore ships underscored: npm pack strips nested .gitignore files). */
 const GITIGNORE_URL = new URL("../templates/_gitignore", import.meta.url);
 /**
@@ -49,7 +67,7 @@ export async function withRecommendedGitignore(files) {
  * the editor step's .vscode files, which are what make F5 and the extension
  * prompt real.
  */
-export function nextStepsComment(ide, template) {
+export function nextStepsComment(ide, template, runtime = "node") {
     if (ide === "vscode") {
         // `empty`'s stub has no ask yet — the breakpoint goes on the one the user writes.
         const breakpointIn = template === "empty"
@@ -59,9 +77,13 @@ export function nextStepsComment(ide, template) {
                 : template === "typescript-interop"
                     ? "in src/person.tsi"
                     : "in your .tsi file";
+        // A Bun project still debugs under Node's loader: the .vscode files are valid whenever Node is present.
+        const runLine = runtime === "bun"
+            ? "//   1. Run this file: bun start (F5 runs it too, under Node's loader — .vscode/launch.json is already set up)."
+            : "//   1. Press F5 to run this file (.vscode/launch.json is already set up).";
         return [
             "// Next steps in VS Code:",
-            "//   1. Press F5 to run this file (.vscode/launch.json is already set up).",
+            runLine,
             `//   2. Set a breakpoint ${breakpointIn} and press F5 again to step through the ask.`,
             '//   3. Install the recommended "Nola" extension when VS Code offers it — IntelliSense,',
             "//      go to definition and diagnostics inside .tsi files.",
@@ -69,7 +91,7 @@ export function nextStepsComment(ide, template) {
     }
     return [
         "// Next steps:",
-        "//   1. Run this file: npm start",
+        `//   1. Run this file: ${runtime === "bun" ? "bun start" : "npm start"}`,
         "//   2. Set up your editor (VS Code extension, debugging): https://nola.sh/docs/start/editor-setup/",
     ].join("\n");
 }
@@ -124,6 +146,8 @@ export async function scaffold(targetDir, opts = {}) {
     await prepareTarget(absRoot, opts.force ?? false);
     const name = opts.name ?? basename(absRoot);
     const provider = opts.provider ?? "none";
+    const runtime = opts.runtime ?? "node";
+    const entry = entryFile(template);
     // A live provider's config replaces the template's own; the ledger it replayed goes with it.
     if (provider !== "none") {
         for (const offline of OFFLINE_ONLY)
@@ -133,15 +157,21 @@ export async function scaffold(targetDir, opts = {}) {
     const manifest = files.get("package.json");
     if (manifest)
         files.set("package.json", rewriteExamplePackageJson(manifest, { name, version }));
+    // A Bun project (spec 2026-10-14-bun-support): the preload, a `bun <entry>` start script, the devDependency, engines.bun.
+    if (runtime === "bun") {
+        files.set("bunfig.toml", BUNFIG_TOML);
+        const current = files.get("package.json");
+        if (current !== undefined)
+            files.set("package.json", applyBunRuntime(current, { entry, version }));
+    }
     await withRecommendedGitignore(files);
     const envVar = vendorEnvVar(template, provider);
     if (envVar !== undefined && !files.has(".env.example"))
         files.set(".env.example", envExample(envVar));
     // The entry file greets the user with the next steps — it is what VS Code opens.
-    const entry = entryFile(template);
     const program = files.get(entry);
     if (program !== undefined)
-        files.set(entry, `${nextStepsComment(opts.ide ?? "none", template)}\n\n${program}`);
+        files.set(entry, `${nextStepsComment(opts.ide ?? "none", template, runtime)}\n\n${program}`);
     for (const [relPath, content] of files) {
         const target = join(absRoot, relPath);
         await mkdir(join(target, ".."), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nola-lang",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Scaffold a new Nola project (npm create nola, or npm create nola-lang)",
   "keywords": [
     "nola",

package/skills/nola/SKILL.md

@@ -45,8 +45,8 @@ infer function extractPerson(.text: string) {
   one dot marks a value flowing INTO the model (`.name`); a template after
   `ask` is a value coming OUT.
 - `` ask `prompt`: T `` — an extractor: asks the LLM for a `T`. The colon
-  is glued to the closing backtick; `` ask `prompt`<T> `` is the same
-  construct (write `: T` unless a page shows otherwise).
+  is on the closing backtick's line (glued or spaced); `` ask `prompt`<T> ``
+  is the same construct (write `: T` unless a page shows otherwise).
   `${...}` interpolation works inside the backticks. The `..` is implied
   directly after `ask` and in a call's argument list — a typed template
   that starts an argument, or a value nested in a plain object/array
@@ -59,6 +59,24 @@ infer function extractPerson(.text: string) {
   extractor — is a call intent (the LLM fills the extractor-shaped
   arguments, then the function runs). Only `` fn`hint`(...) `` carries
   instruction text.
+- `` ask `use` admin `and` cfg.defaults `go`: T `` — an ASK SEQUENCE: a
+  bare value between texts is named data the model sees where it stands
+  (`${x}` stays your words); `` ask `words` fn(`slot`: T) `` is a call
+  intent with words; several `[lists]` union with your words between them;
+  the type glues to the last part. The kind follows the parts: texts and
+  data → extract, one call → function calling, lists → tool use; a list
+  beside a call is reserved (NOLA2019).
+- `` ask `task` [searchFiles, fs.readFile]: T `` — a TOOL-USE ask: the
+  functions in brackets between the template and the type are tools the
+  model may call, as often as it needs, before it answers; Nola runs each
+  call, hands the result back and asks again, the typed answer ends the
+  loop. Parentheses RUN a function once (a call intent), brackets OFFER
+  functions. Entries are names or member chains (a call written there is
+  reserved, NOLA1022); the contract derives from the signature and JSDoc;
+  `.withMaxTurns(n)` / config `ask.maxTurns` (10) cap the turns (NOLA3020);
+  a tool that throws ends the ask (NOLA3021); the model must support tool
+  calls — openai/anthropic/google/"nola", or `mockProvider(…, { tools:
+  true })` (NOLA3019 otherwise).
 - `ask with <modelName> <intent>` — routes one ask through a named model
   from `nola.config.ts`. The name must be a static identifier. When the
   platform serves inference (`model: "nola"`) any unconfigured
@@ -96,6 +114,11 @@ infer function extractPerson(.text: string) {
   `import { f } from "./x.tsi"`. Imports of plain TS use NodeNext style:
   `import { g } from "./y.js"` (the `.js` extension, even though the source
   file is `.ts`).
+- `.tsi` runs from source through the Node loader (`nola run`, Node ≥ 22.18)
+  or, on Bun, through `@nola-lang/bun`'s preload — `preload =
+  ["@nola-lang/bun/preload"]` in `bunfig.toml`, then `bun src/main.tsi`;
+  `nola check` / `nola build` stay on Node (`references/config.md`, "Running
+  on Bun").
 - Every `export type` / `export interface` in a `.tsi` is ALSO a runtime
   value (`User.toJsonSchema()`, `User.validate(v)`, `User.parse(v)`,
   `User["~standard"]` — Standard Schema AND Standard JSON Schema, so
@@ -124,5 +147,5 @@ Read these before non-trivial work:
 
 - `references/syntax.md` — full grammar and semantics of every construct
 - `references/patterns.md` — worked examples (extraction, call intents)
-- `references/config.md` — `nola.config.ts`, providers, project layout
+- `references/config.md` — `nola.config.ts`, providers, project layout, running on Bun
 - `references/pitfalls.md` — common errors (NOLA codes) and their fixes

package/skills/nola/references/config.md

@@ -39,7 +39,9 @@ export default defineConfig({
 ```
 
 `openai({ model })` requires an explicit model; optional fields are `apiKey`,
-`apiKeyEnv` (default `"OPENAI_API_KEY"`), `baseUrl` and `fetch`.
+`apiKeyEnv` (default `"OPENAI_API_KEY"`), `baseUrl` and `fetch`. With a custom
+`fetch`, `apiKey`/`apiKeyEnv` are optional: the fetch authenticates, and without
+a key no vendor auth header is sent (the same rule for every vendor factory).
 
 `typesafe()` (typesafe.ai's Jev, reads `TYPESAFE_API_KEY`, model defaults to
 `jev-latest`) is NOT a chat model: it is the DECISION model that answers the
@@ -232,11 +234,11 @@ the providers package:
     "check": "nola check"
   },
   "dependencies": {
-    "@nola-lang/providers": "^0.1.14",
-    "@nola-lang/runtime": "^0.1.14"
+    "@nola-lang/providers": "^0.1.15",
+    "@nola-lang/runtime": "^0.1.15"
   },
   "devDependencies": {
-    "nola-lang": "^0.1.14",
+    "nola-lang": "^0.1.15",
     "typescript": "^5.6.0"
   },
   "engines": { "node": ">=22.18" }
@@ -270,6 +272,33 @@ for you). Do not mix versions.
   a bare `npx nola` outside a project resolves an unrelated npm package named
   `nola`.)
 
+### Running on Bun
+
+`bun create nola` scaffolds a Bun project: `@nola-lang/bun` in devDependencies,
+`bunfig.toml` with its preload, `start: "bun src/main.tsi"`. Any Node project
+becomes one by adding the same three things:
+
+```toml
+# bunfig.toml
+preload = ["@nola-lang/bun/preload"]
+
+[test]
+preload = ["@nola-lang/bun/preload"]
+```
+
+- `bun src/main.tsi` / `bun --watch src/main.tsi` run `.tsi` from source;
+  `bun test` files import `.tsi` modules. Bun ≥ 1.3.
+- One-step bundles and executables: a build script with
+  `Bun.build({ entrypoints: ["src/main.tsi"], plugins: [nola()], target: "bun",
+  compile: { outfile: "my-app" } })` (`import { nola } from "@nola-lang/bun"`).
+- `nola build` output runs under `bun` with nothing added
+  (`bun dist/src/main.tsi.js`, `bun build --compile dist/src/main.tsi.js`).
+- `nola check`, `nola build`, `nola console` run on Node (`bun run check`
+  launches them there). `nola run` is the Node loader — under Bun it is
+  NOLA3015; use the preload. No source map rides a Bun plugin: stack-trace
+  lines through `.tsi` are right at module level and in plain functions, ONE
+  TOO HIGH inside an `infer function` body, and columns inside an `ask` drift.
+
 ## tsconfig.json
 
 ```json

package/skills/nola/references/patterns.md

@@ -258,6 +258,68 @@ call intent awaits a promise-returning callee itself (`ask` ≈ `await`), so
 ask, `.withRetry(n)` on a call intent re-invokes it on failure — only use it
 when the target is idempotent.
 
+## The tool-use project: offer functions, let the model call them
+
+The same one-file shape for the third feature (`npm create nola` scaffolds
+it as `tool-use`): the top-level `ask` offers two plain-TypeScript functions
+as tools. The model calls them as it needs — here it lists a folder, reads
+a file to be sure, then answers — and the typed answer is what `ask` yields.
+
+```ts
+// src/tools.ts — plain TypeScript; the JSDoc is the contract the model sees
+/**
+ * Lists the files under a directory on disc D.
+ * @param dir an absolute directory path, such as D:/docs
+ * @param pattern keeps only the paths that contain it
+ */
+export async function searchFiles(dir: string, pattern?: string): Promise<string[]> { /* … */ return []; }
+
+/** Reads a file's text. */
+export async function readFile(path: string): Promise<string> { /* … */ return ""; }
+```
+
+```tsi
+// src/main.tsi — run with: nola run src/main.tsi
+import { readFile, searchFiles } from "./tools.js";
+
+const files = ask `the files on disc D that belong to a US visa application` [searchFiles, readFile]: string[];
+
+console.log(JSON.stringify(files));
+```
+
+Parentheses run a function once with model-filled arguments (the
+function-calling project); brackets offer functions the model may call zero
+or more times. Cap the loop with `.withMaxTurns(n)` when a task should not
+wander; return a failure as a value (`{ error: "no such file" }`) when the
+model should recover from it, since a thrown error ends the ask.
+
+## Data in place: a bare value in the instruction
+
+When the model needs a value beside the words that explain it, write the
+value bare between texts (an ask sequence): it reaches the model as a
+named input block where you wrote it. A `${}` hole splices the value into
+your words instead — pick by what the model should treat it as.
+
+```tsi
+// src/main.tsi
+interface Person {
+  name: string;
+}
+declare const project: { id: string; lead: string };
+declare const policy: string;
+
+// data where it stands: <input name="project"> … </input>, then your next words
+export const owner = ask `the person responsible for` project `given this policy` policy: Person;
+
+// words: the id is spliced into the sentence
+export const lead = ask `the lead of project ${project.id}`: string;
+```
+
+The same shape puts words on a call (`` ask `register the applicant` createUser(`user id`: string) ``)
+and words between tool lists (`` ask `find` [searchFiles] `or, when stale,` [readDir] `done`: string[] ``).
+The kind follows the parts, never the data: texts and data extract, a call
+with a typed slot is function calling, lists are tool use.
+
 ## An agent loop with a live context statement
 
 A context statement is read at EACH ask that sees it, so one placed before a

package/skills/nola/references/pitfalls.md

@@ -135,10 +135,11 @@ export const stored = ..`the user's full name`: string;         // stored: dots
 
 > expected a type after the extractor's `:` on the same line — write `…`: T.
 
-The colon spelling `` ask `the ticket id`: string `` needs the colon glued to
-the backtick (a colon after a space is a ternary's, never the extractor's) and
-the type on the colon's line. Two more traps come with it, both from the type
-having no closing delimiter:
+The colon spelling `` ask `the ticket id`: string `` takes the colon glued,
+spaced or on the next line (`` `p` : string `` and `` `p`\n  : string `` are the
+same ask — a line break alone never ends an ask) and needs the type on the
+colon's line. Two more traps come with it, both from the type having no
+closing delimiter:
 
 ```tsi
 interface User { name: string }
@@ -164,6 +165,12 @@ comparison). Chain intent methods after a parenthesized extractor
 > parentheses, or assign it to a local first (`await`, `ask` and `this` cannot
 > be values).
 
+The same code, with ask-site wording, covers an ask sequence: `this`,
+`await`, `ask`, `function` or `class` where a value would start after a
+text, a value ending in a backtick (`` ask `p` new Foo `more` ``), and text
+after the type (`` ask `p`: T `more` `` — the type ends the sequence; move
+the text before `: T`).
+
 ```tsi
 export infer function total(.items: string[], a: number, b: number) {
   // WRONG — an operator after a value
@@ -345,6 +352,101 @@ A bare template with no type, `` createTicket(`a short ticket title`, 2) ``,
 is not a slot at all: it is a plain string argument and the call stays an
 ordinary call — no error, and no model request.
 
+## NOLA1021 / NOLA1022 — a tool list holds functions
+
+> a tool list holds functions — a name, a member, an expression that is one function, or a group (a module or an object of functions, an array of them), bare or spread; a literal cannot be one, and the list is not empty.
+
+The brackets after an ask's template are a TOOL LIST (tool use). An entry is
+a value: a name or dotted chain (one function, or a group — a module, an
+object of functions, an array of them), a spread of a group, or an
+expression that is one function. A literal (a string, a number, an arrow,
+an object or array literal) or an empty list is NOLA1021, and a call written
+in the list — describing the arguments in place — is reserved (NOLA1022):
+
+```tsi
+// not-checked — WRONG
+const a = ask `find the files` [searchFiles, "readFile"]: string[];     // NOLA1021
+const b = ask `get the user` [getUser(`the id`: string)]: User;         // NOLA1022 — reserved
+```
+
+```tsi
+// RIGHT
+const a = ask `find the files` [searchFiles, fs.readFile]: string[];
+const g = ask `find the files` [fileTools, ...moreTools]: string[];   // a group by name, a group flattened
+const b = ask `get the user` [getUser]: User;   // the arguments come from getUser's signature
+```
+
+## NOLA1023 — a typed ask in a ternary's consequent
+
+> a typed extractor directly in a ternary's consequent — parenthesize it: `cond ? (ask `p`: T) : y`.
+
+Two colons with different meanings would sit side by side, so the typed ask
+goes in parentheses (an untyped ask, a call intent and the `<T>` form need
+none; the alternate position is free):
+
+```tsi
+// not-checked — WRONG
+const t = cond ? ask `the title`: string : "untitled";
+```
+
+```tsi
+// RIGHT
+const t = cond ? (ask `the title`: string) : "untitled";
+```
+
+## NOLA2018 — a tool list entry the compiler cannot use
+
+An entry that is neither one function nor a group (a value, a type-only
+import, a class, a union of function types — `const f = cond ? a : b` —
+`any`), a function under a spread, a group reached through an expression
+(`[groups[0]]` — name it or spread it), a method reached through a call
+(`api.client().search` — name the object first), a group with nothing
+callable, or
+two tools that would share one name on the wire (`a.b` beside `a_b`; the
+same function twice; a spread's `search` beside another). Name a function
+or a group, keep the names distinct, offer colliding groups bare so their
+names carry the prefix. A parameter the walk cannot derive — a rest
+parameter, a `Map`, a generic parameter — is NOLA2002 at the entry; a group
+member the walk cannot use fails the group, naming the member.
+
+## NOLA2019 — a reserved shape of the ask sequence
+
+Tools beside a call: `` ask `use` [searchFiles] `then` createUser(`id`: string) ``
+is the kind where the loop runs and the call's slots are the answer —
+designed, not built. Offer the function as a tool, or make the call its own
+ask after the tool-use ask. Also a `..` sequence inside a call's slot
+(`` fn(..`t` user: string) ``): a slot's instruction is one text.
+
+## NOLA2020 — an ask sequence that cannot mean one thing
+
+Two calls with typed slots (an ask makes one call — split the asks); a
+`: T` beside a call (the call's result is the type — drop it); text after
+a bare call (`` ask f(`x`: string) `more` `` — put the words first:
+`` ask `more` f(`x`: string) ``); a call with typed slots inside a data
+value (`` ask `use` (createUser(`id`: string)) `go`: T `` — write it bare
+between texts, it is the action, not data).
+
+## NOLA3019 – NOLA3022 — tool use at run time
+
+- NOLA3019: the resolved model cannot request tool calls (a hand-written
+  `LanguageModel`, a mock without `{ tools: true }`, `typesafe()`, a vendor
+  model with `toolUse: false`). Route the
+  ask to `openai` / `anthropic` / `google` / `"nola"`, or brand the mock.
+  Refused before the network.
+- NOLA3020: the model kept calling tools past the cap (`.withMaxTurns(n)`,
+  else `ask.maxTurns`, 10). Raise the cap, give it tools that answer in fewer
+  calls, or sharpen the task. Definitive; the transcript rides the error.
+- NOLA3021: a tool threw. Fix the tool, or return the failure as a value
+  when the model should recover from it. Invalid arguments never reach the
+  function — they go back to the model as that call's result.
+- NOLA3022: the list could not be built when the ask ran — a value that is
+  not what its type promised (a group member that is not a function, a
+  tuple of another length), a function with no name (an anonymous arrow in
+  an array), or two tools with one wire name. Before the network.
+
+`.withRetry(n)` on a tool-use ask re-runs the WHOLE loop, tools included:
+only with tools that are safe to repeat.
+
 ## NOLA3010 — bare `await` on a raw extract or call intent
 
 > extract/call intents carry no construction scope — only `ask` supplies their
@@ -465,13 +567,19 @@ export infer function route(.ticket: string) {
 }
 ```
 
-## NOLA3015 — running `.tsi` under Bun or Deno
+## NOLA3015 — the Node loader under Bun or Deno
+
+`nola run` and `node --import nola-lang/register` ARE Node's module-hooks API;
+Bun and Deno do not run them. On Bun, run `.tsi` from source through
+`@nola-lang/bun` instead: `preload = ["@nola-lang/bun/preload"]` in
+`bunfig.toml`, then `bun src/main.tsi` (see config.md, "Running on Bun").
+Deno cannot load `.tsi` at all — run on Node. Any package manager is fine
+(`bun install`, `bun run start`: the `nola` bin is a Node script).
+
+## NOLA3023 — Bun older than 1.3
 
-The loader is Node's module-hooks API; Bun and Deno do not run it. Any package
-manager is fine (`bun install`, `bun run start`, `pnpm start`, `yarn start` —
-the `nola` bin is a Node script), but `bun --bun`, `bun src/main.ts` and
-`deno run` cannot load `.tsi`. Run on Node: `nola run` or
-`node --import nola-lang/register src/main.ts`.
+`@nola-lang/bun` needs `process.getBuiltinModule` (Bun ≥ 1.3). Run
+`bun upgrade`.
 
 ## Other things that will not parse
 
@@ -481,6 +589,12 @@ the `nola` bin is a Node script), but `bun --bun`, `bun src/main.ts` and
 - `infer` on a method, arrow function or function expression — top-level
   function declarations only.
 - `fn(..)` — the bare derive-all call form is reserved (NOLA1004).
-- `` ask `p` : T `` — a colon after a space is not the extractor's type; only a
-  colon glued to the closing backtick is (`` `p`: T ``). In a ternary the
-  spaced colon is the separator.
+- `` cond ? ask `p` : y `` — a colon on the extractor's line is its type,
+  spaced or glued, so the ask reads `y` as its type and the ternary loses its
+  alternate: NOLA1023. A typed ask standing bare as a consequent is the same
+  code — parenthesize it: `` cond ? (ask `p`: T) : y ``, on one line or
+  three: the formatted `` cond\n  ? ask `p`\n  : y `` reads `y` as the type
+  too, since a line break alone never ends an ask.
+- `` fn(`x` [tools]: T) `` — a tool list is never a call slot; a bracket
+  there keeps its JavaScript meaning. The list goes on the ask site or the
+  stored `..` form only.

package/skills/nola/references/syntax.md

@@ -236,16 +236,22 @@ export infer function lookup(text: string) {
 - With no type, the extractor asks for free text: the wire schema is a plain
   string and the static TS type is `any`. Give every extractor an explicit
   type unless you deliberately want unconstrained prose.
-- TWO SPELLINGS OF THE TYPE, one construct. `: T` — a colon GLUED to the
-  closing backtick, like an annotation — is the taught form and what every
-  example writes. `<T>` — a type argument after the backtick — is the same
-  construct: `` ask `the ticket id`<string> ``, `` ..`x`<T> ``,
+- TWO SPELLINGS OF THE TYPE, one construct. `: T` — a colon after the
+  closing backtick on the same line, glued like an annotation or spaced
+  (`` `p`: T `` and `` `p` : T `` are the same ask) — is the taught form and
+  what every example writes. `<T>` — a type argument after the backtick — is
+  the same construct: `` ask `the ticket id`<string> ``, `` ..`x`<T> ``,
   `` fn(`x`<T>) ``, `` ask `q`<Choice<C>> `` — same AST, same emit, same
   definition, same ledger entries; legal everywhere `: T` is. Rules for the
-  colon: a colon after whitespace is never the extractor's (so
-  `` cond ? ask `p` : fallback `` stays a ternary over an untyped ask, and
-  `` cond ? ask `p`: number : fallback `` asks for a number); the type starts
-  on the colon's line (NOLA1018 otherwise); a type NAME followed by `.`
+  colon: it may follow glued, spaced, or on the next line (a line break
+  alone never ends an ask); an ask directly
+  in a ternary's consequent is parenthesized, on one line or three,
+  `` cond ? (ask `p`: number) : fallback `` — bare it is NOLA1023, because
+  the colon after the ask is its type and `` cond ? ask `p` : fallback ``
+  would read `fallback` as that type (a call intent and the `<T>` form need
+  no parentheses, and the alternate position is free:
+  `` cond ? y : ask `p`: number ``); the
+  type starts on the colon's line (NOLA1018 otherwise); a type NAME followed by `.`
   continues the type (`` `p`: User.withRetry(2) `` is the type
   `User.withRetry` called with 2) — chain intent methods after a
   parenthesized extractor (`` ask (..`p`: User).withRetry(2) ``), a
@@ -256,7 +262,7 @@ export infer function lookup(text: string) {
   starts an argument, or a property value / element of a plain object or
   array literal written in the arguments: `` fn(`x`: T) ``,
   `` api.save({ note: `x`: T }) ``, `` fn([`x`: T]) ``. Everywhere else it is
-  required: `` const i = ..`x`: T ``, `` fn(cond ? ..`x`: T : y) ``,
+  required: `` const i = ..`x`: T ``, `` fn(cond ? (..`x`: T) : y) ``,
   `` fn(...[..`x`: T]) ``, `` new Foo(..`x`: T) ``,
   `` ask (..`x`: T).withRetry(2) `` (parenthesized: the template is no longer
   a first token — `` fn((`x`: T)) `` is a syntax error too). A `` `x`<T> ``
@@ -441,6 +447,125 @@ Two consequences to keep in mind:
   round trips only. Once the arguments are filled, the callee's own promise
   runs to completion, the same as a plain `await fn()` in your code.
 
+## Tool use
+
+A tool-use ask offers the model functions it may call before it answers —
+a bracketed list of function names between the task and the type:
+
+```tsi
+import { readFile, searchFiles } from "./tools.js";
+
+export infer function find(.query: string) {
+  return ask `the files on disc D that belong to a US visa application` [searchFiles, readFile]: string[];
+}
+```
+
+```tsi
+import * as fileTools from "./tools.js";
+import { dbTools } from "./db.js";
+
+const report = ask `analyze this report` [fileTools, dbTools]: Report;   // the model sees fileTools.search, dbTools.search, …
+const files = ask `the matching files` [...fileTools]: string[];          // flat: search, readFile
+```
+
+Brackets OFFER, parentheses RUN: `` ask getUser(`id`: string) `` is a call
+intent (getUser runs exactly once, the value is what it returned);
+`` ask `the user's name` [getUser]: string `` offers getUser (the model
+calls it zero or more times, the value is the model's answer). Reach for
+the call when you want the function's own result, for the list when the
+answer needs lookups first.
+
+- Each provider call is a TURN: the model answers or requests tool calls;
+  Nola validates the arguments against the function's parameters, runs
+  the calls in the reply's order, renders each result (`fmt`: a string
+  verbatim, anything else JSON) and asks again with the transcript. An
+  unknown tool name or invalid arguments never reach the function — they
+  go back as that call's result. The answer then gets the usual validation
+  and single correction turn (not counted against the cap).
+- Entries are VALUES, judged by the type checker: a name or dotted chain
+  names one function (`searchFiles`, `fs.readFile`) or a GROUP — a module
+  namespace, an object of functions, an array of them — whose functions
+  the model sees as `group.member`; `[...group]` offers them flat by their
+  own names; any other expression that is one function (`tools[0]`) is
+  named by the function. Group tools by what they are for: two groups
+  sharing a `search` never collide, a flat list with two does (NOLA2018).
+  The contract derives from each signature: one object over the
+  parameters, by name in order; optional/defaulted parameters optional; the
+  JSDoc summary is the description, `@param` tags describe the properties.
+  A member chain keeps its receiver (its object must be a plain chain —
+  a name, `this`, dotted / indexed / optional access; `api.client().search`
+  is NOLA2018, name the object first); a group's functions are called on
+  the group. One declared signature per tool: a union of functions, `any`,
+  `unknown`, a class, a group with nothing callable, a group reached
+  through an expression (name it or spread it): NOLA2018. An underivable
+  parameter (a rest parameter, a Map): NOLA2002 at the entry; a group
+  member it cannot use fails the group, naming the member. At run time a
+  list whose values do not match their types, an unnamed function or a
+  name collision is NOLA3022 before the network.
+- The cap: `.withMaxTurns(n)` on the intent, else config `ask.maxTurns`
+  (10); past it NOLA3020, definitive, transcript attached. A throwing tool
+  is NOLA3021 with the error as `cause`; return a failure as a value when
+  the model should recover from it. `.withRetry(n)` re-runs the WHOLE
+  loop, tools included; `.withTimeout` bounds provider calls only.
+- The model must support tool calls: `openai`, `anthropic`, `google`,
+  `model: "nola"`; `mockProvider(…, { tools: true })` with `toolCalls([{
+  name, args }])` values scripting tool turns; `replay()` of a recorded
+  ledger. Anything else is NOLA3019 before the network; `fallback` /
+  `roundRobin` skip members without support on a tool-use ask. A vendor
+  factory's `toolUse` option, beside `structuredOutputs`, names the
+  strategy (`"native"`, the default and the only one today) or marks a
+  host without tool calling (`toolUse: false` — unbranded, NOLA3019,
+  skipped by a group); a group mixing strategies is NOLA3003.
+- Where the list is legal: directly after the template at the ask site
+  (`ask`, `ask with <name>`) and on the stored form (`` ..`p` [fn]: T ``);
+  the type follows the list (`]: T` — or `] : T` — or `]<T>`). Never in a call's
+  slots. A call-shaped entry (`` [getUser(`id`: string)] ``) is reserved
+  (NOLA1022); a literal or an empty list is NOLA1021. In a ternary's
+  consequent, parenthesize the typed ask (NOLA1023), as always.
+- Receipts carry `turns` (each call's arguments, result or error,
+  duration); telemetry fires `onToolCallStart` / `onToolCallEnd`; the
+  terminal trace and `nola console` show the calls under the ask.
+
+## The ask sequence
+
+After the first text, texts and values alternate (spec 2026-10-12):
+
+```tsi
+const owner = ask `the person responsible for` project `given this policy` policy: Person;
+const user = ask `register the applicant` createUser(`user id`: string, `email`: string);
+const files = ask `find` [searchFiles, readFile] `or, when stale,` [readDir] `and return paths`: string[];
+```
+
+- A bare value (a name, a member chain, a literal, `new X()`, a plain call,
+  a parenthesized expression) is DATA: the model reads an `<input name>`
+  block where you wrote it, named by what you wrote, with its type on the
+  wire; `${x}` inside a text stays your words. Prefer a hole for a literal.
+- A call with a typed slot is the ACTION: the kind is function calling, the
+  call's result is the value, no `: T`. A `[list]` offers tools; several
+  lists union (the same entry in two lists is one tool), and the words
+  between them are guidance, nothing enforces "or".
+- The kind follows the parts: texts and data → extract; one call → function
+  calling; one or more lists → tool use; a list beside a call is reserved
+  (NOLA2019); two calls, `: T` beside a call, text after a bare call
+  (`` ask f(`x`: T) `more` `` — put the words first), or a call with typed
+  slots inside a data value: NOLA2020.
+- Two values never touch (`user [x]` is an index, `user (x)` a call); text
+  first; `: T` follows the last part (a backtick, `]` or the value) — glued,
+  spaced, or on its own line; `<T>` only after a text or a list. `this`,
+  `await`, `ask`, an unparenthesized function and a value ending in a
+  template are NOLA1020.
+- An ask may span lines, one part per line: a line break alone never ends
+  it. After a text the next part may start on the next line, and the type
+  may stand on its own line; the ask ends at `;`, a closer, an operator, a
+  statement keyword (`const`, `return`, `type X`, `let x`, …) or its type.
+  After a VALUE a name on the next line is a new statement, as in JS. The
+  one trap: semicolon-free code after a call sequence that ends on a text —
+  `` …`done`\nnotify(files) `` takes `notify(files)` as a value; end the ask
+  with `;`.
+  A call's slot stays one text (a `..` sequence there is NOLA2019). A
+  sequence lowers to an instruction ARRAY of parts; a one-text ask lowers
+  as before.
+
 ## Values in an instruction: `.x` and `${x}`
 
 Two spellings put a value in front of the model — pick by what the model