create-nola-lang 0.1.13 → 0.1.15

package/dist/scaffold.js

@@ -5,7 +5,8 @@ import { fileURLToPath } from "node:url";
 import { collectExampleFromDisk, devExamplesDir, rewriteExamplePackageJson } from "./examples.js";
 import { fetchExampleFromGitHub } from "./github.js";
 import { providerById } from "./providers.js";
-import { templateByName, templateNames } from "./registry.js";
+import { entryFile, templateByName, templateNames } from "./registry.js";
+/** This package's own templates: `empty` (the one builtin), `_providers/` and `_gitignore`. */
 const TEMPLATES_DIR = fileURLToPath(new URL("../templates/", import.meta.url));
 /** The config a live provider choice writes over the template's own (`templates/_providers/<id>.config.ts`). */
 export function providerConfigUrl(provider) {
@@ -28,39 +29,61 @@ 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`;
 }
-/** _gitignore ships underscored (npm pack strips nested .gitignore files). */
-const RENAMES = { _gitignore: ".gitignore" };
-/** The ONE recommended .gitignore — every scaffold gets it; no template keeps a copy of its own. */
+/** 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);
 /**
- * Add the recommended `.gitignore` to an example's files. Examples are copied
- * verbatim from `examples/`, where the monorepo's root ignore file covers them,
- * so they carry none — one an example does carry wins.
+ * Add the recommended `.gitignore` to a template's files. Templates are
+ * copied as committed — examples from `examples/`, where the monorepo's root
+ * ignore file covers them — so they carry none; one a template does carry wins.
  */
 export async function withRecommendedGitignore(files) {
     if (!files.has(".gitignore"))
         files.set(".gitignore", await readFile(GITIGNORE_URL, "utf8"));
     return files;
 }
-/** Files whose __NAME__/__VERSION__, README-note and __NEXT_STEPS__ placeholders are substituted. */
-const SUBSTITUTED = new Set(["package.json", "README.md", "main.ts", "main.tsi"]);
 /**
- * The comment that opens the entry file (src/main.ts, or the `.tsi` entry
- * of a one-file template) — the file the scaffold lands the user on (VS Code opens it
- * as the active editor), so it carries the first three things to do. The VS
- * Code variant only ships with the editor step's .vscode files, which are
- * what make F5 and the extension prompt real.
+ * The comment that opens the entry file (the `.tsi` entry of a one-file
+ * template and of `empty`, else the plain-TS src/main.ts) — the file the
+ * scaffold lands the user on (VS Code opens it as the active editor), so it
+ * carries the first three things to do. The VS Code variant only ships with
+ * 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") {
-        const breakpointIn = templateByName(template)?.entry
-            ? "on the `ask` line below"
-            : template === "typescript-interop"
-                ? "in src/person.tsi"
-                : "in your .tsi file";
+        // `empty`'s stub has no ask yet — the breakpoint goes on the one the user writes.
+        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";
+        // 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.",
@@ -68,45 +91,12 @@ 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");
 }
 /** Template files that only make sense for the offline (replay) configuration. */
-const OFFLINE_ONLY = new Set(["nola.replay.jsonl"]);
-const 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\n" +
-            "you edit the `.tsi` file or add your own asks, switch the config to a real\n" +
-            "model (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\"` — platform-served inference with the trial key the\n" +
-            "scaffold wrote to `.env` (git-ignored). Out of runs? `npx nola-lang account` opens\n" +
-            "your Nola account, where prepaid balance is added, or bring your\n" +
-            "own model (see the comment in `nola.config.ts`).",
-    },
-};
-/** The README notes for a chosen provider: offline, the Nola trial, or a vendor and the env var its factory reads. */
-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}\` — ${def.label} serves inference with the key it reads\n` +
-            `from \`${def.envVar}\`. Copy \`.env.example\` to \`.env\` (git-ignored; \`nola run\` applies it) and fill in\n` +
-            `\`${def.envVar}\` before the first \`npm start\`, or switch models in \`nola.config.ts\`.`,
-    };
-}
+const OFFLINE_ONLY = ["nola.replay.jsonl"];
 export async function ownVersion() {
     const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
     return pkg.version;
@@ -123,9 +113,26 @@ async function prepareTarget(absRoot, force) {
     for (const entry of entries)
         await rm(join(absRoot, entry), { recursive: true, force: true });
 }
+/**
+ * A template's files as committed: `empty` from this package's templates/
+ * dir, every other template from examples/ — the dev checkout's on disk,
+ * else GitHub at the lockstep tag. Everything is buffered before the caller
+ * touches the target, so a failed fetch scaffolds nothing.
+ */
+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);
+}
 /**
  * Lay a template down into `targetDir`. One implementation serves both entry
- * points: the `create-nola-lang` bin (`npm create nola-lang`) and `nola init`.
+ * points — the `create-nola-lang` bin (`npm create nola-lang`) and `nola init`
+ * — and both sources: the files are collected as committed, then the scaffold
+ * adds what a project needs on top — the chosen provider's config (dropping
+ * the replay ledger), the project name and the lockstep ranges in
+ * package.json, the recommended .gitignore, the vendor key's .env.example,
+ * and the next-steps comment at the top of the entry file.
  */
 export async function scaffold(targetDir, opts = {}) {
     const root = targetDir;
@@ -134,69 +141,42 @@ export async function scaffold(targetDir, opts = {}) {
     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 !== undefined && !exampleFiles.has(".env.example"))
-            exampleFiles.set(".env.example", envExample(envVar));
-        for (const [relPath, content] of exampleFiles) {
-            const target = join(absRoot, relPath);
-            await mkdir(join(target, ".."), { recursive: true });
-            await writeFile(target, content);
-        }
-        return { root, files: [...exampleFiles.keys()].sort() };
-    }
-    const templateRoot = join(TEMPLATES_DIR, template);
-    const versionRange = `^${version}`;
     const provider = opts.provider ?? "none";
-    const notes = readmeNotes(provider);
-    const nextSteps = nextStepsComment(opts.ide ?? "none", template);
-    const files = [];
-    const copyDir = async (fromDir, relDir) => {
-        await mkdir(join(absRoot, relDir), { recursive: true });
-        for (const entry of await readdir(join(templateRoot, fromDir), { withFileTypes: true })) {
-            const fromRel = join(fromDir, entry.name);
-            if (entry.isDirectory()) {
-                await copyDir(fromRel, join(relDir, entry.name));
-                continue;
-            }
-            const toName = RENAMES[entry.name] ?? entry.name;
-            if (provider !== "none" && OFFLINE_ONLY.has(entry.name))
-                continue;
-            const toRel = join(relDir, toName);
-            // A live provider's config replaces the template's own (both builtin templates keep it at the root).
-            const source = provider !== "none" && relDir === "." && entry.name === "nola.config.ts"
-                ? providerConfigUrl(provider)
-                : join(templateRoot, fromRel);
-            let content = await readFile(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__", nextSteps);
-            }
-            await writeFile(join(absRoot, toRel), content);
-            files.push(toRel.replaceAll("\\", "/"));
-        }
-    };
-    await copyDir(".", ".");
-    if (!files.includes(".gitignore")) {
-        await writeFile(join(absRoot, ".gitignore"), await readFile(GITIGNORE_URL, "utf8"));
-        files.push(".gitignore");
+    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)
+            files.delete(offline);
+        files.set("nola.config.ts", await readFile(providerConfigUrl(provider), "utf8"));
+    }
+    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 }));
     }
-    if (envVar !== undefined) {
-        await writeFile(join(absRoot, ".env.example"), envExample(envVar));
-        files.push(".env.example");
+    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 program = files.get(entry);
+    if (program !== undefined)
+        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 });
+        await writeFile(target, content);
     }
-    return { root, files: files.sort() };
+    return { root, files: [...files.keys()].sort() };
 }
 //# sourceMappingURL=scaffold.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nola-lang",
-  "version": "0.1.13",
+  "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

@@ -22,38 +22,88 @@ import type { Person } from "./types.js";
 // thenable Intent<T>. `await`ing it (or `ask`) runs the inference.
 infer function extractPerson(.text: string) {
   // `ask` resolves an intent the way `await` resolves a promise.
-  const person = ask `Extract the person described in the text`<Person>;
+  const person = ask `Extract the person described in the text`: Person;
   return person;
 }
 ```
 
-- `infer function name(...)` — declares a nola function. An optional
-  backtick instruction goes between name and params:
-  `` infer function name`instruction`(...) ``. `await` is legal in the body.
+- `infer function name(...)` — declares a nola function. Any bare template
+  literal on its own line in the body is a CONTEXT STATEMENT: text every
+  later `ask` in the invocation sees, read at each ask. It may continue with
+  values: `` `Page` oncall `when the ticket is an outage.` `` (a name, a call
+  or a bracketed literal; anything else in parentheses — but `await`, `ask`
+  and `this` cannot be values: assign them to a local first). Several are
+  legal, anywhere in the body; one before a loop shows the current state on
+  every pass. Visibility is lexical, like a `const`: a statement inside a
+  block reaches only the asks inside those braces, and statements never
+  accumulate across loop passes — each ask sees every statement visible at
+  its position exactly once, rendered at that ask. `await` is legal in the
+  body.
 - `.name: T` parameters are CONTEXT parameters: their values are shown to
   the LLM. Plain (no dot) parameters are ordinary values the LLM never
   sees. `.` is only legal on infer-function parameters. Rule of thumb:
   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`.
-  `${...}` interpolation works inside the backticks. Anywhere that is NOT
-  directly after `ask` — a stored intent, a call-intent argument, an
-  object/array literal — spell it `` ..`prompt`<T> `` (a typed template
-  there without the dots is NOLA2014); `` ask ..`prompt` `` is still legal.
+- `` ask `prompt`: T `` — an extractor: asks the LLM for a `T`. The colon
+  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
+  literal there, is an extractor: `` createTicket(`a short title`: string, 2) ``.
+  Anywhere else — a stored intent, a ternary, a spread, `new` — spell it
+  `` ..`prompt`: T `` (a typed `` `x`<T> `` elsewhere is NOLA2014, a
+  `` `x`: T `` a syntax error); `` ask ..`prompt` `` and `` fn(..`x`: T) ``
+  are still legal.
 - `` ask fn`hint`(...) `` — or a plain call whose arguments contain an
   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
   name is legal — it is sent to the platform as a free-form inference profile.
-- Prompt templates: inside ANY instruction backticks (marker, extractor,
-  call hint) a hole that starts with a single dot — `${.member}` — reads
-  the intent's prompt scope; a literal containing one REPLACES that
-  intent's prompt block (`${.default}` is the built-in block, `${.next}`
-  the rest of the prompt). Every other `${expr}` is a lexical value.
-  See `references/syntax.md` → "Prompt templates".
+- Values in an instruction — two spellings, one rule: `.name` (a contextual
+  parameter or `const .name` binding) is DATA, rendered as an `<input
+  name>` block the system turn marks as data; a value after text in a
+  context statement (`` `Page` oncall ``) or a `${expr}` hole in ANY
+  instruction backticks is part of the developer's words, spliced where it
+  stands (a string verbatim, a function its name, a call intent its callee
+  and arguments, anything else JSON) — the model FOLLOWS it, so interpolate
+  only text the developer controls (a team name, a count, a date) and put
+  anything a user or a document supplied in `.name`. A context statement is
+  read at EACH ask that sees it (module or body alike); an extractor's or
+  hint's text when the ask runs. A Nola construct (`ask`, `..`) inside a
+  context statement's value or hole, or in a call hint's hole, is NOLA2010
+  (written bare right after the text, NOLA1020); a call intent is a legal
+  value (a HINTED `` fn`hint`(…) `` one only in parentheses or a `${}` hole —
+  bare it is no call intent, and its extractor argument is NOLA2010). There
+  is no `${.member}` prompt scope (a dot cannot start a hole's expression).
+  See `references/syntax.md` → "Context statements" and "Values in an
+  instruction".
+- The prompt itself is the developer's words in four tags — `<context
+  function|module>` with `<input name>` blocks, then `<task>` (`<task
+  call="fn">` for a call intent); the schema rides structured output, never
+  the prompt; `system.message` REPLACES the default system text. See
+  `references/syntax.md` → "The prompt".
 
 ## Where Nola diverges from TypeScript — hard rules
 
@@ -64,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
@@ -72,7 +127,7 @@ infer function extractPerson(.text: string) {
   with an exported type's name (NOLA2011). `./x.tsi` with no `x.tsi` on disk
   is the VIEW of `x.ts`: the same module plus those values — import plain-TS
   types that way when you need their schema. Keep one basename per module.
-- An extractor's `<T>` should be a named, JSON-shaped type. The schema comes
+- An extractor's type should be a named, JSON-shaped type. The schema comes
   from the RESOLVED type, so unions (a `kind` key makes them discriminated),
   `Partial<T>`, `extends`, `Record<string, T>` and types from packages all
   work; `Date` is revived to a real `Date`. `Map`/`Set`/`Promise`, functions
@@ -92,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
@@ -124,8 +126,8 @@ export default defineConfig({
 
 ```tsi
 export infer function summarize(.text: string) {
-  const draft = ask with fast `a rough summary`<string>;
-  return ask with careful `a polished summary of: ${draft}`<string>;
+  const draft = ask with fast `a rough summary`: string;
+  return ask with careful `a polished summary of: ${draft}`: string;
 }
 ```
 
@@ -232,11 +234,11 @@ the providers package:
     "check": "nola check"
   },
   "dependencies": {
-    "@nola-lang/providers": "^0.1.13",
-    "@nola-lang/runtime": "^0.1.13"
+    "@nola-lang/providers": "^0.1.15",
+    "@nola-lang/runtime": "^0.1.15"
   },
   "devDependencies": {
-    "nola-lang": "^0.1.13",
+    "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