nola-lang 0.1.2 → 0.1.4

package/README.md

@@ -10,7 +10,7 @@ Install as a **devDependency** — your app depends on
 instead (the scaffold sets all of this up):
 
 ```bash
-npm create nola-lang my-app     # or: npx nola init
+npm create nola my-app          # or: npx nola init
 ```
 
 ## Commands

package/dist/main.js

@@ -10,7 +10,7 @@ const HELP = `nola <command>
 
 Commands:
   init [dir] [--template <t>|--add] [--ide vscode] [--agents <list>]  scaffold or retrofit a Nola project
-  skill install [--agents <list>]  write agent skill files (Claude Code, Cursor, Copilot, AGENTS.md) into the project
+  skill install [--agents <list>] [--force]  write agent skill files (Claude Code, Cursor, Copilot, AGENTS.md) into the project
   build [dir] [--out <dir>]   compile all .tsi files (js+map+d.ts to --out)
   run <entry>                 run a .tsi/.js entry with the Nola loader + nola.config.ts
   check [dir]                 type-check lowered .tsi files AND the project's .ts files, positions mapped back
@@ -26,6 +26,7 @@ async function main() {
             ide: { type: "string" },
             watch: { type: "boolean" },
             agents: { type: "string" },
+            force: { type: "boolean" },
         },
     });
     const [command, arg] = positionals;
@@ -76,7 +77,7 @@ async function main() {
         case "init":
             return cmdInit(arg, { template: values.template, add: values.add, ide: values.ide, agents: values.agents });
         case "skill":
-            return cmdSkill(arg, { agents: values.agents });
+            return cmdSkill(arg, { agents: values.agents, force: values.force });
         default:
             console.log(HELP);
             return command ? 1 : 0;

package/dist/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,IAAI,GAAG;;;;;;;;;CASZ,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QACxC,gBAAgB,EAAE,IAAI;QACtB,OAAO,EAAE;YACP,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;YACxC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC5B,GAAG,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;YACxB,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACvB,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;YAC1B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SAC3B;KACF,CAAC,CAAC;IACH,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,WAAW,CAAC;IACnC,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,GAAG,IAAI,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;YACnE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;gBACnC,OAAO,CAAC,CAAC;YACX,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,eAAe,OAAO,CAAC,MAAM,gBAAgB,CAAC,CAAC;YAC3D,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;YAC9C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;gBACjC,OAAO,CAAC,CAAC;YACX,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;YACrC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,GAAG,GAAG,KAAK,IAAqB,EAAE;gBACtC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,wBAAwB,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;gBACvE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACtB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;oBACnC,OAAO,CAAC,CAAC;gBACX,CAAC;gBACD,OAAO,CAAC,GAAG,CAAC,sBAAsB,OAAO,CAAC,MAAM,gBAAgB,CAAC,CAAC;gBAClE,OAAO,CAAC,CAAC;YACX,CAAC,CAAC;YACF,MAAM,IAAI,GAAG,MAAM,GAAG,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;YAC/B,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;YAC1C,IAAI,KAAiC,CAAC;YACtC,KAAK,CAAC,GAAG,IAAI,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;gBACtD,IAAI,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC3B,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC,CAAC,CAAC;YACH,OAAO,MAAM,IAAI,OAAO,CAAS,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,0BAA0B;QACxE,CAAC;QACD,KAAK,KAAK;YACR,OAAO,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;QAC3B,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9G,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAClD;YACE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAC5B,CAAC,GAAG,EAAE,EAAE;IACN,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CACF,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"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"}

package/dist/skill.d.ts

@@ -1,5 +1,6 @@
 /** `nola skill install` — write agent skill adapters into the current project. */
 export declare function cmdSkill(sub: string | undefined, opts: {
     agents?: string;
+    force?: boolean;
 }): Promise<number>;
 //# sourceMappingURL=skill.d.ts.map

package/dist/skill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"AAIA,kFAAkF;AAClF,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAMlG"}
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"AAIA,kFAAkF;AAClF,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAMnH"}

package/dist/skill.js

@@ -1,11 +1,11 @@
 import { runSkillInstall } from "create-nola-lang";
-const USAGE = "nola skill install [--agents claude,cursor,copilot,agents-md | all | none]";
+const USAGE = "nola skill install [--agents claude,cursor,copilot,agents-md | all | none] [--force]";
 /** `nola skill install` — write agent skill adapters into the current project. */
 export async function cmdSkill(sub, opts) {
     if (sub !== "install") {
         console.log(USAGE);
         return sub ? 1 : 0;
     }
-    return runSkillInstall({ agents: opts.agents });
+    return runSkillInstall({ agents: opts.agents, force: opts.force });
 }
 //# sourceMappingURL=skill.js.map

package/dist/skill.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,KAAK,GAAG,4EAA4E,CAAC;AAE3F,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAuB,EAAE,IAAyB;IAC/E,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnB,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,eAAe,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,KAAK,GAAG,sFAAsF,CAAC;AAErG,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAuB,EAAE,IAA0C;IAChG,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnB,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,eAAe,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;AACrE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nola-lang",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The Nola language toolchain: nola init/build/run/check and the Node loader for .tsi files",
   "keywords": [
     "nola",
@@ -27,7 +27,7 @@
   },
   "type": "module",
   "bin": {
-    "nola": "./dist/main.js"
+    "nola": "dist/main.js"
   },
   "exports": {
     ".": {
@@ -38,18 +38,17 @@
   },
   "files": [
     "dist",
-    "!dist/.tsbuildinfo",
-    "skills"
+    "!dist/.tsbuildinfo"
   ],
   "dependencies": {
     "@ampproject/remapping": "^2.3.0",
     "@jridgewell/trace-mapping": "^0.3.25",
-    "@nola-lang/ast": "0.1.2",
-    "@nola-lang/compiler": "0.1.2",
-    "@nola-lang/node-loader": "0.1.2",
-    "@nola-lang/parser": "0.1.2",
-    "@nola-lang/runtime": "0.1.2",
-    "create-nola-lang": "0.1.2",
+    "@nola-lang/ast": "0.1.4",
+    "@nola-lang/compiler": "0.1.4",
+    "@nola-lang/node-loader": "0.1.4",
+    "@nola-lang/parser": "0.1.4",
+    "@nola-lang/runtime": "0.1.4",
+    "create-nola-lang": "0.1.4",
     "esbuild": "^0.25.0",
     "typescript": "^5.6.0"
   },

package/skills/nola/SKILL.md

@@ -1,75 +0,0 @@
----
-name: nola
-description: Writing Nola .tsi files — a TypeScript superset with infer
-  functions and ask extractors. Use when creating or editing .tsi files or
-  nola.config.ts.
----
-
-# Writing Nola
-
-Nola is a TypeScript superset. `.tsi` files are NOT valid TypeScript — the
-Nola toolchain lowers them to plain TS before tsc, bundlers, or Node see
-them. Everything you know about TypeScript applies inside a `.tsi` file
-EXCEPT the constructs below. A configured LLM resolves the new constructs at
-run time.
-
-## The constructs at a glance
-
-```tsi
-import type { Person } from "./types.js";
-
-// An LLM-backed function: lowers to a plain function returning a lazy,
-// 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>;
-  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.
-- `.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 in (`.name` — the value flows into the model), TWO dots out
-  (`` ..`prompt` `` — a value comes out of it).
-- `` ask ..`prompt`<T> `` — an extractor: asks the LLM for a `T`.
-  `${...}` interpolation works inside the backticks.
-- `` 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 with <providerName> <intent>` — routes one ask through a named
-  provider from `nola.config.ts`. The name must be a static identifier.
-- 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".
-
-## Where Nola diverges from TypeScript — hard rules
-
-- `ask` is a reserved word in `.tsi` (still legal as a member/property
-  name). `infer` is contextual: a keyword only directly before `function`.
-- Identifiers starting with `__nola` are reserved. Never write them.
-- Imports of `.tsi` files keep the literal extension:
-  `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`).
-- An extractor's `<T>` should be a named, structurally simple type
-  (object/array/primitive fields). `Date` works (revived to a real `Date`);
-  `Map`/`Set` and other ambient lib types do not.
-- Raw extract/call intents are resolved with `ask`, never bare `await`
-  (that throws NOLA3010). Infer-function RETURN values may be awaited.
-
-## References
-
-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/pitfalls.md` — common errors (NOLA codes) and their fixes

package/skills/nola/references/config.md

@@ -1,227 +0,0 @@
-# `nola.config.ts`, providers, and project layout
-
-## The import surface is FROZEN — use exactly these two specifiers
-
-```ts
-import { defineConfig } from "@nola-lang/runtime";
-import { openai, mockProvider, withRetry } from "@nola-lang/providers";
-```
-
-`defineConfig` and everything app-facing come from `@nola-lang/runtime`.
-Everything provider-shaped — provider factories (`openai`, `anthropic`,
-`google`, `mockProvider`), resilience combinators (`withRetry`, `fallback`,
-`roundRobin`, `constant`, `exponential`) and record/replay (`record`,
-`replay`) — comes from `@nola-lang/providers`.
-
-Never import providers from the runtime, never import `defineConfig` from the
-providers package, and never reach for a subpath (`@nola-lang/runtime/config`,
-`@nola-lang/runtime/providers`, `nola-lang/runtime`) — those do not exist.
-`@nola-lang/providers` deliberately does not depend on the runtime, which is
-what keeps a second copy of the runtime out of the install tree.
-
-## Minimal config
-
-`nola.config.ts` lives at the project root and default-exports a
-`defineConfig` call. `providers.default` is required:
-
-```ts
-import { openai } from "@nola-lang/providers";
-import { defineConfig } from "@nola-lang/runtime";
-
-export default defineConfig({
-  providers: {
-    // Reads OPENAI_API_KEY from the environment at the first ask.
-    default: openai({ model: "gpt-5-mini" }),
-  },
-});
-```
-
-`openai({ model })` requires an explicit model; optional fields are `apiKey`,
-`apiKeyEnv` (default `"OPENAI_API_KEY"`), `baseUrl` and `fetch`.
-
-### Named providers become `ask with <name>` targets
-
-Every other key of `providers` is a name you choose, and that name is exactly
-what `ask with` and `.withProvider()` accept:
-
-```ts
-import { anthropic, openai } from "@nola-lang/providers";
-import { defineConfig } from "@nola-lang/runtime";
-
-export default defineConfig({
-  providers: {
-    default: openai({ model: "gpt-5-mini" }),
-    fast: openai({ model: "gpt-5-nano" }),
-    careful: anthropic({ model: "claude-sonnet-4-5" }),
-  },
-});
-```
-
-```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>;
-}
-```
-
-An `ask with` name that is not a key of the map fails at run time with
-NOLA3004, listing the configured names.
-
-### Other config sections
-
-```ts
-import { mockProvider, openai } from "@nola-lang/providers";
-import { defineConfig } from "@nola-lang/runtime";
-
-export default defineConfig({
-  providers: {
-    default: openai({ model: "gpt-5-mini" }),
-    mock: mockProvider(() => ({ ok: true })),
-  },
-  // hermetic override — EVERY ask goes here, even .withProvider()-pinned ones
-  forceProvider: process.env.CI ? "mock" : undefined,
-  observability: { logLevel: "info" },
-  ask: { timeoutMs: 60_000 },          // per-invocation timeout; 0 disables
-  system: { message: "Answer in British English." },
-  compiler: { underivableContextType: "error" },   // "error" | "prune" | "omit"
-  build: { target: "app" },            // "app" (default) | "lib"
-});
-```
-
-Keep `compiler.underivableContextType` a LITERAL value — the editor reads it
-statically and cannot execute your config, so a computed value is invisible to
-it.
-
-### Resilience combinators
-
-Combinators wrap a provider and return a provider, so they nest:
-
-```ts
-import { exponential, fallback, openai, withRetry } from "@nola-lang/providers";
-import { defineConfig } from "@nola-lang/runtime";
-
-export default defineConfig({
-  providers: {
-    default: fallback([
-      withRetry(openai({ model: "gpt-5-mini" }), exponential({ maxRetries: 3 })),
-      openai({ model: "gpt-5-nano" }),
-    ]),
-  },
-});
-```
-
-`withRetry(provider, policy)` takes a policy built by `constant({ maxRetries })`
-or `exponential({ maxRetries, delayMs?, multiplier?, maxDelayMs? })`; it retries
-the wire call and fail-fasts on definitive errors (most 4xx). It is unrelated to
-the intent method `.withRetry(n)`, which re-runs the whole ask.
-
-## Package layout
-
-`nola-lang` is a DEV dependency — it holds the compiler, the CLI and
-TypeScript, and never ships to production. The app depends on the runtime and
-the providers package:
-
-```json
-{
-  "type": "module",
-  "scripts": {
-    "start": "nola run src/main.ts",
-    "build": "nola build",
-    "check": "nola check"
-  },
-  "dependencies": {
-    "@nola-lang/providers": "^0.1.0",
-    "@nola-lang/runtime": "^0.1.0"
-  },
-  "devDependencies": {
-    "nola-lang": "^0.1.0",
-    "typescript": "^5.6.0"
-  },
-  "engines": { "node": ">=22" }
-}
-```
-
-`nola-lang`, `@nola-lang/runtime` and `@nola-lang/providers` are released in
-LOCKSTEP — give all three the same version (`npm create nola-lang` pins them
-for you). Do not mix versions.
-
-- `nola run <entry>` runs a `.ts`/`.tsi` entry through the loader with
-  `nola.config.ts` applied.
-- `nola build [dir] [--out dist]` emits plain JS + source maps + `.d.ts`. For
-  app projects (the default) it also emits `dist/nola.config.js` and wires
-  every built module to it, so `node dist/main.js` needs no loader. Library
-  authors set `build: { target: "lib" }` and let the consuming app configure
-  the process.
-- `nola check [dir]` type-checks `.tsi` and `.ts` together with diagnostics
-  mapped back to `.tsi` positions. Plain `tsc` over `src` is NOT a check path.
-- Scaffold a project with `npm create nola-lang my-app` (or `npx nola init`).
-
-## tsconfig.json
-
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "allowArbitraryExtensions": true,
-    "noEmit": true,
-    "skipLibCheck": true
-  },
-  "include": ["src"]
-}
-```
-
-`include` must be DIRECTORY-style (`["src"]`), never a `.ts`-suffixed glob
-like `["src/**/*.ts"]`: the directory form is what lets the editor tooling
-admit `.tsi` files into the program while plain `tsc` ignores them. Under the
-glob form `.tsi` files fall out of the program and auto-import stops offering
-your infer functions. `module`/`moduleResolution` are NodeNext (hence `./x.js`
-specifiers for plain TS imports) and `allowArbitraryExtensions` is required
-for the `.tsi` declaration pairs.
-
-## Developing offline
-
-`mockProvider` returns canned answers — deterministic, no API key, and the
-right default for examples and tests. It takes either a queue of values (one
-per ask, in order) or a function of the request:
-
-```ts
-import { mockProvider } from "@nola-lang/providers";
-import { defineConfig } from "@nola-lang/runtime";
-
-export default defineConfig({
-  providers: {
-    default: mockProvider([{ name: "Alice Smith", age: 32 }]),
-  },
-});
-```
-
-### record / replay
-
-`record(inner, path)` wraps a real provider and appends every exchange to a
-JSONL ledger; `replay(path)` serves answers back from that ledger:
-
-```ts
-import { openai, record, replay } from "@nola-lang/providers";
-import { defineConfig } from "@nola-lang/runtime";
-
-const live = process.env.NOLA_RECORD === "1";
-
-export default defineConfig({
-  providers: {
-    default: live
-      ? record(openai({ model: "gpt-5-mini" }), "./nola.replay.jsonl")
-      : replay("./nola.replay.jsonl"),
-  },
-});
-```
-
-`replay` is STRICT: entries are keyed by a fingerprint of the exact request, and
-a request with no matching entry fails with NOLA3008 rather than quietly calling
-the network. Any change to a prompt, an instruction, a schema or the provider
-params re-keys the entry — re-record the ledger after editing a `.tsi`.
-
-Secrets in production come from the real environment; `.env` files are a
-dev-time convenience of the loader only.

package/skills/nola/references/patterns.md

@@ -1,277 +0,0 @@
-# Nola patterns — worked examples
-
-## The starter project, end to end
-
-This is the shape every Nola project takes: `.tsi` files hold the infer
-functions, a plain `.ts` entry point calls them, and `nola run` executes the
-entry with the loader and `nola.config.ts` in place.
-
-```
-my-app/
-  nola.config.ts        # providers
-  package.json          # nola-lang in devDependencies
-  tsconfig.json         # include: ["src"]
-  src/
-    person.tsi          # the Nola source
-    main.ts             # a plain TypeScript consumer
-```
-
-`src/person.tsi` — the type and the infer function live together:
-
-```tsi
-export interface Person {
-  name: string;
-  age: number;
-  employer: string;
-  job: string;
-}
-
-export infer function extractPerson(.message: string) {
-  const person = ask ..`the person described in the text`<Person>;
-  return person;
-}
-```
-
-`src/main.ts` — plain TypeScript. Note the literal `.tsi` extension in the
-import, and that `await` on the returned `Intent` is what runs the inference:
-
-```ts
-import { extractPerson } from "./person.tsi";
-
-const person = await extractPerson(
-  "Alice Smith, 32, is a staff engineer at Acme Corp working on distributed systems.",
-);
-console.log(JSON.stringify(person));
-```
-
-Run it:
-
-```bash
-nola run src/main.ts        # or: npm start
-nola check                  # type-checks .tsi and .ts together
-nola build                  # dist/ — plain JS + source maps + .d.ts
-```
-
-## Composing several asks in one invocation
-
-Every `ask` in one invocation shares that invocation's context — the `..`
-contextual parameters and the function's instruction marker. That is what lets
-you split one big prompt into several small, individually-typed asks instead of
-demanding everything at once.
-
-What is NOT shared is the answers. Earlier results are recorded on the
-invocation's frame, but history does not compose into later prompts yet: a
-later ask does NOT see what an earlier ask returned. When it needs an earlier
-answer, pass it forward explicitly with `${}` interpolation.
-
-```tsi
-export infer function solve(.problem: string) {
-  // Both asks see `problem` (the contextual parameter). They do NOT see each
-  // other's answers automatically — the reasoning is handed to the second ask
-  // explicitly through `${}`.
-  const reasoning = ask ..`think step by step about the problem before answering`;
-  const answer = ask ..`the final numeric answer, given this reasoning: ${reasoning}`<number>;
-  return { reasoning, answer };
-}
-```
-
-Once an `ask` returns, its result is an ORDINARY typed value — branch on it,
-pass it to plain functions, put it in an object literal, interpolate it into a
-later prompt:
-
-```tsi
-export type Category = "billing" | "refund" | "fraud" | "other";
-
-export infer function classifyMessage(.message: string) {
-  const category = ask ..`the category of the customer message`<Category>;
-  const urgent = ask ..`does the message need urgent attention`<"yes" | "no">;
-
-  // plain TS from here on
-  if (category === "fraud") return { category, urgent: true, escalate: true };
-  return { category, urgent: urgent === "yes", escalate: false };
-}
-```
-
-Plain TypeScript orchestrates the loop; the infer functions stay small:
-
-```tsi
-// src/research.tsi
-export interface Conclusion {
-  answer: string;
-  /** the collected notes that directly support the answer */
-  evidence: string[];
-}
-
-export infer function nextQuery(.question: string, .notes: string[]) {
-  return ask ..`the single best search query to advance the research; keywords only`<string>;
-}
-
-export infer function conclude(.question: string, .notes: string[]) {
-  return ask ..`answer the research question using only the collected notes`<Conclusion>;
-}
-```
-
-```ts
-// src/main.ts
-import { conclude, nextQuery } from "./research.tsi";
-import { search } from "./search.js";
-
-const question = "who maintains the project?";
-const notes: string[] = [];
-for (let i = 0; i < 3; i++) {
-  const query = await nextQuery(question, notes);
-  notes.push(await search(query));
-}
-const conclusion = await conclude(question, notes);
-```
-
-## Call intents — let the LLM fill a function's arguments
-
-When you already have a function that DOES something, do not extract its
-arguments one at a time and then call it. Make the call itself the intent: the
-LLM fills every extractor-shaped argument in one provider call, and the
-function runs with the results.
-
-`src/tickets.ts` — an ordinary TypeScript helper, nothing Nola about it:
-
-```ts
-export async function createTicket(title: string, priority: number): Promise<string> {
-  const res = await fetch("https://example.test/tickets", {
-    method: "POST",
-    body: JSON.stringify({ title, priority }),
-  });
-  return (await res.json()).id as string;
-}
-```
-
-`src/file-ticket.tsi` — the helper is imported with the NodeNext `.js`
-specifier, and the call gets extractor arguments:
-
-```tsi
-import { createTicket } from "./tickets.js";
-
-export infer function fileTicket(.request: string) {
-  // Sigil-less: the extractor argument makes this call an intent. `2` is a
-  // plain argument and is passed through untouched.
-  const id = ask createTicket(..`a short ticket title for the request`<string>, 2);
-  return id;
-}
-```
-
-Add instruction text for the call with the marker form — it is the only
-spelling that carries a hint:
-
-```tsi
-export infer function fileTicketCarefully(.request: string) {
-  return ask createTicket`file the ticket exactly as the customer described it`(
-    ..`a short ticket title`<string>,
-    ..`priority 1-5, where 1 is most urgent`<number>,
-  );
-}
-```
-
-Every extractor slot needs an explicit `<T>`, and all slots of one call
-resolve together in a single provider round trip.
-
-`createTicket` is async, but `id` is a `string`, not a `Promise<string>` — a
-call intent awaits a promise-returning callee itself (`ask` ≈ `await`), so
-`await ask createTicket(...)` is redundant. Because the callee runs inside the
-ask, `.withRetry(n)` on a call intent re-invokes it on failure — only use it
-when the target is idempotent.
-
-## Typing the answers
-
-Prefer a NAMED, exported `type` or `interface` for `<T>` over an inline object
-literal: it documents the contract, it is reusable from plain TS, and JSDoc
-comments on its members become descriptions in the schema the LLM sees.
-
-```tsi
-export interface LineItem {
-  description: string;
-  quantity: number;
-  /** price per unit in USD */
-  unitPrice: number;
-}
-
-export interface Invoice {
-  invoiceNumber: string;
-  issuedTo: string;
-  lineItems: LineItem[];
-  /** grand total in USD */
-  total: number;
-  /** ISO date; omit when the document has none */
-  dueDate?: string;
-}
-
-export infer function extractInvoice(.document: string) {
-  return ask ..`the invoice data from the document`<Invoice>;
-}
-```
-
-Closed label sets keep the model on-rails — a string-literal union, a string
-enum, or an inline union all work:
-
-```tsi
-export type Category = "billing" | "refund" | "fraud" | "other";
-
-export enum Sentiment {
-  Positive = "positive",
-  Neutral = "neutral",
-  Negative = "negative",
-}
-
-export infer function triage(.message: string) {
-  const category = ask ..`the category of the customer message`<Category>;
-  const sentiment = ask ..`the overall sentiment of the message`<Sentiment>;
-  const urgent = ask ..`does the message need urgent attention`<"yes" | "no">;
-  return { category, sentiment, urgent: urgent === "yes" };
-}
-```
-
-### Types from another file
-
-Cross-file types are supported. Import the type from a plain `.ts` file with a
-type-only import and the NodeNext `.js` specifier; the toolchain derives the
-schema for you:
-
-```ts
-// src/models.ts
-export interface Person {
-  name: string;
-  age: number;
-}
-```
-
-```tsi
-// src/report.tsi
-import type { Person } from "./models.js";
-
-export infer function extractPerson(.text: string) {
-  return ask ..`the person described in the text`<Person>;
-}
-```
-
-Recursive types are legal too:
-
-```tsi
-export type TreeNode = {
-  label: string;
-  children?: TreeNode[];
-};
-
-export infer function parseTree(.input: string) {
-  return ask ..`the tree structure described in the input`<TreeNode>;
-}
-```
-
-`Date` fields work and come back as real `Date` instances:
-
-```tsi
-export type CalendarEvent = { title: string; at: Date };
-
-export infer function nextEvent(.calendar: string) {
-  const event = ask ..`the next event on the calendar`<CalendarEvent>;
-  const when: Date = event.at;   // a Date, not a string
-  return when;
-}
-```

package/skills/nola/references/pitfalls.md

@@ -1,281 +0,0 @@
-# Common Nola errors and their fixes
-
-Diagnostic codes are stable: `NOLA1xxx` parse, `NOLA2xxx` compile, `NOLA3xxx`
-run time.
-
-## NOLA1009 — `ask with` needs a static provider name
-
-> expected a provider name after `ask with` — for a dynamic provider use
-> `.withProvider(...)` on the intent.
-
-The alias after `with` must be a bare identifier naming a key of the
-`providers` map in `nola.config.ts`. A string literal, a variable expression or
-a parenthesized expression will not parse.
-
-```tsi
-export infer function summarize(.text: string, useFast: boolean) {
-  // WRONG
-  const a = ask with "fast" ..`a rough summary`<string>;
-  const b = ask with providers.fast ..`a rough summary`<string>;
-
-  // RIGHT — name it in nola.config.ts, then use that name
-  const c = ask with fast ..`a rough summary`<string>;
-
-  // RIGHT — dynamic choice
-  const d = ask (..`a rough summary`<string>).withProvider(useFast ? "fast" : "careful");
-
-  return { a, b, c, d };
-}
-```
-
-```ts
-// nola.config.ts
-export default defineConfig({
-  providers: {
-    default: openai({ model: "gpt-5-mini" }),
-    fast: openai({ model: "gpt-5-nano" }),
-  },
-});
-```
-
-## NOLA1010 — `.` on a non-infer function
-
-> `.` context parameters are only allowed on infer function parameters.
-
-```tsi
-// WRONG — a plain function has no inference context to put the value in
-function summarize(.text: string) {
-  return text.slice(0, 10);
-}
-
-// RIGHT
-export infer function summarize(.text: string) {
-  return ask ..`a one-sentence summary`<string>;
-}
-```
-
-If the function is genuinely plain TypeScript, drop the `.`; the parameter is
-an ordinary argument.
-
-## NOLA2001 — `ask` outside an infer function body
-
-> `ask` is only allowed directly inside an infer function body.
-
-`ask` is not legal at module level, and not inside a nested closure — not even
-one written inside an infer function.
-
-```tsi
-// WRONG
-const kind = ask ..`the kind`<string>;                  // module level
-
-export infer function f(.t: string) {
-  const g = () => ask ..`the kind`<string>;             // nested closure
-  return g();
-}
-
-// RIGHT — ask directly in the body; from plain TS, await the infer function
-export infer function f(.t: string) {
-  return ask ..`the kind`<string>;
-}
-```
-
-Constructing an extractor outside a body is fine — only resolving it is
-restricted:
-
-```tsi
-export const nameIntent = ..`the user's full name`<string>;   // legal, inert
-```
-
-## NOLA2002 — a type the compiler cannot turn into a schema
-
-> unsupported type for intent schema: …
-
-An extractor's `<T>` must describe a JSON-shaped value: strings, numbers,
-booleans, `Date`, arrays, plain object/interface/type-alias shapes,
-string-literal unions, string enums, and references to those (same-file or
-imported). Ambient lib types like `Map`, `Set`, `RegExp`, functions and
-generics are not derivable.
-
-```tsi
-export infer function tally(.doc: string) {
-  // WRONG
-  const wrong = ask ..`counts per label`<Map<string, number>>;
-
-  // RIGHT — a JSON-shaped type; convert afterwards in plain TS
-  const counts = ask ..`counts per label`<{ label: string; count: number }[]>;
-  const asMap = new Map(counts.map((c) => [c.label, c.count]));
-  return asMap;
-}
-```
-
-Always give an extractor a concrete `<T>` in an expression position. An
-extractor is a value-producing expression; it is not a statement, a type, or a
-declaration.
-
-## NOLA2008 — an underivable `.` contextual parameter type
-
-> contextual parameter 'm' has a type that cannot be derived for inference:
-> unsupported type for intent schema: Map<string, number>. Set
-> compiler.underivableContextType to "prune" or "omit" in nola.config.ts to
-> allow it.
-
-The same derivability rules apply to contextual parameters, because their
-values are serialized into the prompt.
-
-```tsi
-// WRONG
-export infer function topLabel(.index: Map<string, number>) {
-  return ask ..`the label with the highest count`<string>;
-}
-
-// RIGHT — pass a JSON-shaped view as the contextual parameter
-export infer function topLabel(.index: { label: string; count: number }[]) {
-  return ask ..`the label with the highest count`<string>;
-}
-
-// RIGHT — keep the exotic value, but as a PLAIN parameter (the LLM never
-// sees its value, so nothing needs deriving)
-export infer function topLabel(.summary: string, index: Map<string, number>) {
-  const label = ask ..`the label with the highest count`<string>;
-  return { label, count: index.get(label) ?? 0 };
-}
-```
-
-If you must keep an underivable member on a contextual type, relax the policy
-in `nola.config.ts` — `"prune"` drops just the underivable members and keeps
-the rest of the type; `"omit"` drops the whole type silently:
-
-```ts
-export default defineConfig({
-  providers: { default: openai({ model: "gpt-5-mini" }) },
-  compiler: { underivableContextType: "prune" },   // default is "error"
-});
-```
-
-Keep that value a literal — the editor reads it statically and never executes
-your config.
-
-## NOLA2004 — a call-intent slot with no `<T>`
-
-> an extractor used as a call-intent argument must have an explicit `<T>`.
-
-```tsi
-declare function createTicket(title: string, priority: number): Promise<string>;
-
-export infer function fileTicket(.request: string) {
-  // WRONG — the slot has no type
-  const wrong = ask createTicket(..`a short ticket title`, 2);
-
-  // RIGHT
-  const id = ask createTicket(..`a short ticket title`<string>, 2);
-  return id;
-}
-```
-
-## NOLA3010 — bare `await` on a raw extract or call intent
-
-> extract/call intents carry no construction scope — only `ask` supplies their
-> frame.
-
-A raw extractor or call intent has no context of its own; it borrows the frame
-of the `ask` that resolves it. Awaiting one directly (typically from plain TS,
-or after storing it in a variable) throws at run time.
-
-```ts
-// WRONG — nothing supplies the inference context
-import { nameIntent } from "./person.tsi";
-const name = await nameIntent;
-```
-
-```tsi
-// RIGHT — resolve it with `ask` inside an infer function
-import { nameIntent } from "./person.tsi";
-
-export infer function whoIsIt(.text: string) {
-  return ask nameIntent;
-}
-```
-
-```ts
-// RIGHT — from plain TS, await the INFER FUNCTION's result (that is an
-// Intent, which does open its own invocation)
-import { whoIsIt } from "./person.tsi";
-
-const name = await whoIsIt("Alice Smith, 32, works at Acme Corp.");
-```
-
-## Import mistakes
-
-- `.tsi` imports keep the LITERAL extension:
-
-```ts
-import { extractPerson } from "./person.tsi";     // RIGHT
-import { extractPerson } from "./person";         // WRONG — unresolved
-import { extractPerson } from "./person.js";      // WRONG — no such file
-```
-
-- Plain TypeScript imports use the NodeNext `.js` specifier, even though the
-  file on disk is `.ts`:
-
-```ts
-import { createTicket } from "./tickets.js";      // RIGHT
-import { createTicket } from "./tickets.ts";      // WRONG — TS5097
-import { createTicket } from "./tickets";         // WRONG — TS2835
-```
-
-- Never import a `*.nola.*` module. Those are internal companion modules the
-  compiler generates for cross-file types; only generated code imports them,
-  and a hand-written file with such a name is NOLA2006.
-
-```ts
-import { Person } from "./models.nola.js";        // WRONG — internal
-import type { Person } from "./models.js";        // RIGHT
-```
-
-## Never write generated-code names
-
-`__nola` and any identifier starting with `__nola` are reserved in `.tsi`.
-`__nola.ask(...)`, `__nola.intents.ExtractIntent(...)`, `__nola.types.string()`
-and `__nola_file_ctx()` are what the compiler EMITS — they are not an API you
-call, and writing them by hand is an error.
-
-```tsi
-export infer function read(.doc: string) {
-  // WRONG — this is emitted code, not a user-facing API
-  const wrong = await __nola.ask(
-    __nola.intents.ExtractIntent({ instruction: "the value", type: __nola.types.string(), loc: "1:1" }),
-    __frame,
-  );
-
-  // RIGHT
-  const v = ask ..`the value`<string>;
-  return v;
-}
-```
-
-## NOLA2009 — `${.member}` outside a Nola instruction
-
-`${.x}` is prompt-scope access and only means something inside an
-infer-function marker, an extractor's backticks, or a call-intent hint. In a
-plain template literal it is an error — use a lexical value there.
-
-## NOLA2010 — a Nola construct inside a marker / call-hint hole
-
-Marker and call-hint literals are re-emitted from source, so `..`, call
-intents and `ask` cannot appear in their holes. Compute the value first and
-interpolate the result, or move the ask into the function body.
-
-## NOLA3014 — a prompt template rendered nothing (or threw)
-
-A `${.member}` template must produce text. An empty result usually means the
-template only read members that were undefined; a throw is a bug in the
-template's own JS. Fixed at the template — there is no retry.
-
-## Other things that will not parse
-
-- `async infer function f(...)` — an infer function is never `async` in source;
-  `await` is already legal in its body.
-- `export default infer function f(...)` — export by name instead.
-- `infer` on a method, arrow function or function expression — top-level
-  function declarations only.
-- `fn(..)` — the bare derive-all call form is reserved (NOLA1004).

package/skills/nola/references/syntax.md

@@ -1,377 +0,0 @@
-# Nola syntax reference
-
-Everything valid in TypeScript is valid in a `.tsi` file. This file documents
-only the additions. `ask` and `with` are reserved words in `.tsi` (`ask` stays
-legal as a member/property name); `infer` is a keyword only directly before
-`function` at statement or export position, so `T extends infer U` in a
-conditional type is untouched.
-
-## `infer function`
-
-An `infer function` declares an LLM-backed function. Calling one runs NOTHING:
-it returns a lazy, thenable `Intent<T>`. The work happens when the intent is
-resolved — with `ask` inside another infer function, or with `await` from
-plain TS.
-
-```tsi
-// plain
-infer function summarize(.text: string) {
-  return ask ..`a one-sentence summary`<string>;
-}
-
-// exported
-export infer function classify(.message: string) {
-  return ask ..`the category of the message`<string>;
-}
-
-// with an instruction marker between the name and the parameter list
-export infer function triage`triage the ticket like a support lead`(.ticket: string) {
-  return ask ..`the severity: low, medium or high`<"low" | "medium" | "high">;
-}
-```
-
-Rules:
-
-- Top-level function declarations only. `infer` on a method, arrow function,
-  or function expression is a "reserved for a future Nola version" error.
-- `async infer function` is a parse error — an infer function is never `async`
-  in source; it is implicitly awaitable through `Intent`.
-- The instruction marker is a template literal. `${expr}` holes interpolate
-  lexical values into the instruction; a `${.member}` hole makes the marker a
-  prompt TEMPLATE for the function's CONTEXT block (see "Prompt templates").
-- `export default infer function` does NOT parse. Export by name
-  (`export infer function f(...)`) and let consumers import the name.
-- `ask` is legal only DIRECTLY inside an infer function body — not at module
-  level, not inside a nested closure (NOLA2001).
-- `await` IS legal inside the body, for ordinary promises (fetch, DB, any
-  library):
-
-```tsi
-export infer function enrich(.handle: string, fetchProfile: (h: string) => Promise<string>) {
-  const profile = await fetchProfile(handle);       // ordinary promise
-  return ask ..`the person's job title from: ${profile}`<string>;
-}
-```
-
-### Return type annotation
-
-Leave the return type off and let it infer — that is what every example in
-this repo does. When you do annotate, the annotation is `Intent<T>` (the body
-returns `T`, the way an `async` function body returns `T` under `Promise<T>`):
-
-```tsi
-import type { Intent } from "@nola-lang/runtime";
-
-interface User {
-  name: string;
-}
-
-export infer function getUser(.message: string): Intent<User> {
-  const user = ask ..`the user described in the message`<User>;
-  return user;
-}
-```
-
-Do NOT annotate it `Promise<T>`: `Intent<T>` is `PromiseLike<T>`, not a
-`Promise`, so `nola check` reports TS2739 (missing `catch`, `finally`,
-`[Symbol.toStringTag]`).
-
-## `.` contextual parameters
-
-A parameter prefixed with ONE dot is a CONTEXT parameter: its name, type and
-runtime VALUE are composed into the prompt of every `ask` in that invocation.
-A plain parameter is an ordinary JS argument — its name and type reach the
-LLM, its value does not. Mnemonic: one dot IN (`.name`), two dots OUT
-(`` ..`prompt` ``). Writing `..name` on a parameter is NOLA1013.
-
-```tsi
-export type Issue = { id: string; description: string };
-
-// `issue` is visible to the LLM; `fallback` is a normal JS value only.
-export infer function classifyIssue(.issue: Issue, fallback: string) {
-  const kind = ask ..`the kind of this issue`<string>;
-  return kind || fallback;
-}
-```
-
-- `.` is legal ONLY on infer-function parameters. On any other function it is
-  NOLA1010.
-- A contextual parameter's TYPE must be derivable to an inference schema:
-  strings, numbers, booleans, `Date`, arrays, plain object/interface/type-alias
-  shapes, string-literal unions, string enums, and same-file or imported
-  references to those. `Map`, `Set` and other ambient lib types are NOT
-  derivable and raise NOLA2008 under the default policy.
-- Several contextual parameters are fine; they compose into one context block:
-
-```tsi
-export infer function nextQuery(.question: string, .notes: string[]) {
-  return ask ..`the single best search query to advance the research`<string>;
-}
-```
-- `const .x = …` (a contextual BINDING inside the body) is reserved for a
-  future Nola version — NOLA1014 today.
-
-## Extractors — `` ..`instruction`<T> ``
-
-An extractor is the request itself: instruction text in backticks plus an
-optional type argument.
-
-```tsi
-export infer function parse(.doc: string) {
-  const id = ask ..`the ticket id`<string>;             // typed
-  const count = ask ..`how many line items`<number>;
-  const free = ask ..`think step by step about the document`;  // untyped
-  return { id, count, free };
-}
-```
-
-- `${expr}` interpolation is legal inside the backticks and is evaluated at
-  intent-construction time. Strings splice as-is; anything else is
-  JSON-stringified. A hole starting with a single dot (`${.type}`) is NOT a
-  lexical value — it reads the extractor's prompt scope and turns the
-  backticks into a prompt template (see "Prompt templates"):
-
-```tsi
-interface Person {
-  name: string;
-  age: number;
-}
-
-export infer function lookup(text: string) {
-  return ask ..`the person described in: ${text}`<Person>;
-}
-```
-
-- With no `<T>`, 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
-  `<T>` unless you deliberately want unconstrained prose.
-- `<T>` accepts scalars, `Date`, arrays, inline object literals, same-file
-  and imported non-generic aliases/interfaces, string-literal unions and
-  string enums. JSDoc comments on members become schema descriptions:
-
-```tsi
-export interface Conclusion {
-  answer: string;
-  /** the collected notes that directly support the answer */
-  evidence: string[];
-}
-```
-
-- An extractor may be CONSTRUCTED anywhere in a `.tsi` file, module level
-  included — construction needs no context. Only `ask` is position-restricted:
-
-```tsi
-export const nameIntent = ..`the user's full name`<string>;   // legal, inert
-```
-
-## The `ask` operator
-
-`ask` is a unary prefix operator with `await`'s precedence. It resolves any
-`Askable` — an extractor, a call intent, or the `Intent` returned by calling
-an infer function — to its value.
-
-```tsi
-import { getUserById } from "./users.tsi";
-
-type User = { name: string };
-
-export infer function report(.text: string) {
-  const user = ask ..`the user named in the text`<User>;   // extractor
-  const record = ask getUserById(user.name);               // another infer function
-  return record;
-}
-```
-
-### `ask with <name>` — pin one ask to a provider
-
-```tsi
-export infer function summarize(.text: string) {
-  const draft = ask with fast ..`a rough summary`<string>;
-  const final = ask with careful ..`a polished summary of: ${draft}`<string>;
-  return final;
-}
-```
-
-- `<name>` must be a STATIC identifier naming a key of the `providers` map in
-  `nola.config.ts`. An extractor, a parenthesized expression, a string literal
-  or anything else after `with` is NOLA1009 — use `.withProvider(...)` for a
-  dynamic provider.
-- The name is matched against the config at ask time, not compile time; an
-  unknown name is a runtime `NolaConfigError` (NOLA3004).
-- `ask without` is a plain ask of the identifier `without`, not a pin.
-
-## Call intents
-
-A call intent lets the LLM fill some of a function's arguments, then calls the
-function with them. All slots of one call intent resolve in ONE provider call.
-
-Three spellings:
-
-```tsi
-declare function createTicket(title: string, priority: number): Promise<string>;
-
-export infer function file(.request: string) {
-  // 1. sigil-less — a plain call whose arguments contain an extractor
-  const a = ask createTicket(..`a short ticket title`<string>, 2);
-
-  // 2. empty marker — identical lowering; the only spelling for a call
-  //    intent whose arguments are all plain
-  const b = ask createTicket``("fallback title", 3);
-
-  // 3. hint marker — the ONLY carrier of instruction text for the call
-  const c = ask createTicket`file the ticket the customer asked for`(
-    ..`a short ticket title`<string>,
-    ..`priority 1-5, 1 is most urgent`<number>,
-  );
-
-  return { a, b, c };
-}
-```
-
-Detection rule for the sigil-less form — BOTH must hold:
-
-- the callee is an `Identifier` or a `MemberExpression` (any nesting, computed
-  included), and
-- at least one well-formed extractor appears in a slot position: a direct
-  argument, or nested at any depth inside plain object/array literals.
-
-```tsi
-declare const api: { save(order: { qty: number; note: string }): Promise<string> };
-
-export infer function place(.request: string) {
-  // member callee + extractor nested in an object literal → call intent
-  return ask api.save({ qty: 1, note: ..`a one-line note for the warehouse`<string> });
-}
-```
-
-These stay PLAIN calls (the extractor is just a value argument): an extractor
-inside a ternary, logical expression, spread element or template substitution;
-a nested call (in `` outer(inner(..`x`<T>)) `` the INNER call is the intent and
-`outer` receives an `Askable`); `new Foo(...)`, `super(...)`, `import(...)`,
-optional calls (`fn?.(...)`, `a?.b(...)`); and exotic callees (`getFn()(...)`,
-IIFEs) — use the marker form if you want a call intent on one of those.
-
-Parenthesizing an extractor does NOT opt out. To pass an intent as a plain
-value, bind it to a variable first:
-
-```tsi
-const i = ..`a short title`<string>;
-helper(i);                       // plain call — helper receives the Askable
-```
-
-Every extractor used as a call-intent slot must carry an explicit `<T>`
-(NOLA2004). The bare derive-all form `fn(..)` is reserved (NOLA1004).
-
-### Result of a call intent — async callees are awaited
-
-`ask fn(...)` yields the callee's SETTLED value, exactly like `await fn(...)`
-would: if the function returns a promise (or any thenable), the intent awaits
-it before resolving. Its static type is `Awaited<ReturnType<typeof fn>>`. Never
-write `await ask fn(...)` — the extra `await` is a no-op.
-
-```tsi
-declare function createTicket(title: string, priority: number): Promise<string>;
-
-export infer function file(.request: string) {
-  const id = ask createTicket(..`a short ticket title`<string>, 2); // id: string, not Promise<string>
-  return id;
-}
-```
-
-Two consequences to keep in mind:
-
-- The callee runs INSIDE the ask, so a rejected promise fails the ask at the
-  call site (NolaResolutionError with the intent's location) — and
-  `.withRetry(n)` re-runs the WHOLE ask, including the callee. Do not put
-  `.withRetry` on a call intent whose target is not idempotent.
-- The invocation timeout (`ask.timeoutMs` / `.withTimeout`) bounds provider
-  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.
-
-## Prompt templates — `${.member}`
-
-Every instruction literal (infer-function marker, extractor prompt, call-intent
-hint) can act as a TEMPLATE for the prompt block that intent contributes. One
-rule: a substitution hole whose expression starts with a single dot reads the
-intent's prompt scope; every other hole is ordinary lexical JavaScript.
-
-```tsi
-infer function analyze`${.default}
-Rules: answer only from the arguments above; never invent ids.`(.ticket: Ticket) {
-  const id = ask ..`ticket id, comply with ${.type}`<string>;
-  return id;
-}
-
-// A full custom CONTEXT block — everything after the dot is plain TypeScript
-infer function triage`
-CONTEXT — inside ${.signature}, ${.file}
-${.args.map(a => `- ${a.name} (${a.type}): ${JSON.stringify(a.value)}`)}
-
-TASK
-${.next}
-`(.ticket: string) { … }
-```
-
-- Override rule (static): a literal with at least ONE `${.x}` hole is a
-  template — its rendered text REPLACES that intent's block (CONTEXT for an
-  infer function, TASK for an extractor / call hint). A literal with no scope
-  hole is an instruction, exactly as before (`Purpose:` / `<request>` inside
-  the built-in block), even when it has lexical `${}` holes.
-- Function scope (`FunctionPromptScope`): `.fn`, `.signature`, `.file`,
-  `.args[]` (`name`, `type` — native type text, `value`, `contextual`),
-  `.nested`, `.hasContext`, `.default` (the built-in CONTEXT block, no
-  Purpose line), `.next` (the rest of the prompt: callee blocks + TASK).
-- Extractor / call-hint scope (`ExtractPromptScope`): `.type` (native type
-  text of the target), `.schema` (the JSON Schema, serialized),
-  `.hasContext`, `.default` (the built-in TASK block), `.format` (the JSON
-  response rules).
-- Safe by default: a function template that never reads `.next` gets the
-  rest of the prompt appended after it; an extractor template that never
-  reads `.format` gets the JSON response rules appended. Read them only to
-  choose WHERE they go (wrapping). `.next`/`.default`/`.format` are
-  getters, memoized — reading twice does not compose twice.
-- Rendering: arrays render one item per line (no `.join` needed),
-  `undefined`/`null` render as nothing, objects as JSON, `Date` as ISO.
-  Templates render when the ask composes its prompt — lexical values inside
-  a TEMPLATE are read then, not at construction (the only observable
-  difference from an instruction's eager `${}`).
-- Nested holes follow the same rule: `${.file}` inside a `.map` callback's
-  own template literal still reads the scope. Keyword members work
-  (`${.default}`).
-- Editor: completion, hover and precise TS errors work inside the backticks
-  (an unknown member is a TS2339 at the member).
-- Errors: `${.x}` in a template literal that is not a Nola instruction is
-  NOLA2009; a Nola construct (`..`, call intent, `ask`) inside a marker /
-  call-hint hole is NOLA2010; a template that throws or renders empty fails
-  the ask with NOLA3014 (definitive).
-
-## Intent methods
-
-Every intent (extractor, call intent, infer-function result) accepts:
-
-```tsi
-export infer function tuned(.text: string) {
-  const a = ask (..`the title`<string>).withRetry(2);
-  const b = ask (..`the body`<string>).withProvider("careful");
-  const c = ask (..`a creative tagline`<string>).withParams({ temperature: 0.9, maxOutputTokens: 200 });
-  return { a, b, c };
-}
-```
-
-- `.withRetry(n)` — `n` extra whole-ask attempts, flat, no backoff.
-- `.withProvider(nameOrProvider)` — the dynamic form of `ask with`.
-- `.withParams({ temperature, maxOutputTokens, providerOptions })` — wire knobs,
-  merged per field with anything already set.
-
-Two more exist ONLY on the `Intent` an infer function returns (they act when
-the intent roots an invocation), and are typically used from plain TS:
-
-```ts
-import { extractPerson } from "./person.tsi";
-
-const person = await extractPerson(text).withTimeout(30_000);
-const loose = await extractPerson(text).detached();   // do not inherit the caller frame's context
-```
-
-All of these CLONE the intent — the original stays unstarted, and an intent
-resolves at most once.