create-nola-lang 0.1.3 → 0.1.4

package/dist/skill-install.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-install.js","sourceRoot":"","sources":["../src/skill-install.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAgB,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC5G,OAAO,EAAiB,aAAa,EAAE,MAAM,WAAW,CAAC;AAczD,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAsB,EAAE,OAA4B,EAAE;IAC1F,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC;IAC5B,IAAI,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC7B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;YACxD,QAAQ,GAAG,aAAa,EAAE,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,aAAa,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,IAAI,MAAiB,CAAC;IACtB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;SAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,oFAAoF,CAAC,CAAC;QACpG,OAAO,CAAC,CAAC;IACX,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,uBAAuB,EAAE,aAAa,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;QACtG,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC5B,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,GAAG,MAAmB,CAAC;IAC/B,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;QACtD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACnD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO;QAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,OAAO,GACX,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,gCAAgC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,uBAAuB,CAAC;IAChH,IAAI,QAAQ,CAAC,KAAK;QAAE,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;;QACvC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"skill-install.js","sourceRoot":"","sources":["../src/skill-install.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAgB,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC5G,OAAO,EAAiB,aAAa,EAAE,MAAM,WAAW,CAAC;AAgBzD,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAsB,EAAE,OAA4B,EAAE;IAC1F,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC;IAC5B,IAAI,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC7B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;YACxD,QAAQ,GAAG,aAAa,EAAE,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,aAAa,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,IAAI,MAAiB,CAAC;IACtB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;SAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,oFAAoF,CAAC,CAAC;QACpG,OAAO,CAAC,CAAC;IACX,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,uBAAuB,EAAE,aAAa,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;QACtG,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC5B,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,GAAG,MAAmB,CAAC;IAC/B,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;QACtD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1E,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO;QAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvD,IAAI,OAAO,GAAG,uBAAuB,CAAC;IACtC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,GAAG,gCAAgC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;SAC5F,IAAI,MAAM,CAAC,KAAK;QAAE,OAAO,GAAG,kEAAkE,CAAC;IACpG,IAAI,QAAQ,CAAC,KAAK;QAAE,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;;QACvC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,CAAC,CAAC;AACX,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nola-lang",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Scaffold a new Nola project (npm create nola, or npm create nola-lang)",
   "keywords": [
     "nola",
@@ -38,7 +38,8 @@
   "files": [
     "dist",
     "!dist/.tsbuildinfo",
-    "templates"
+    "templates",
+    "skills"
   ],
   "scripts": {
     "bundle": "node scripts/bundle.mjs"

package/skills/nola/SKILL.md

@@ -0,0 +1,75 @@
+---
+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

@@ -0,0 +1,227 @@
+# `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` 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 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

@@ -0,0 +1,277 @@
+# 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;
+}
+```