Give your software a way to be asked.

Start with an operation you already have.

evoke new writes a reflex that already works. The body is your code. It receives typed arguments, returns one line, and can call anything you already have.

import type { Reflex } from "./reflex.d.ts"

export default (async ({ who }) => `Hello, ${who}!`) satisfies Reflex

$ evoke new hello
+ hello/reflex.toml
+ hello/hello.mts
+ hello/reflex.d.ts
$ cd hello && evoke check
  hello  read  runs hello.mts
$ evoke run hello who=Ada
  hello who="Ada"
Hello, Ada!

Describe the boundary.

The manifest is what the classifier reads and what the body receives. Its wording decides accuracy. Every input has exactly one source, so a sentence can never invent a value.

reflex = 1

description = """
Turn the lights in one room on, off, or dim them.
Ceiling and lamp lights only."""
not_for = ["colour scenes and schedules", "asking whether a light is on"]
effect  = "write"
confirm = "Set the {room} lights {state}?"
run     = "lights.mts"

[config]
bridge = "Hue bridge address"

[args.room]
ask   = "Which room?"
vocab = "rooms"

[args.state]
ask         = "What should the lights do?"
options.on  = "Switch on."
options.off = "Switch off."
options.dim = "Lower the brightness without switching off."

[args.brightness]
ask      = "How bright, in percent?"
pick     = "number"
range    = [1, 100]
optional = true

[examples]
"turn on the kitchen lights"   = { state = "on" }
"dim the office to 30 percent" = { state = "dim", brightness = "30 percent" }

[tests]
"make it darker in here" = { state = "dim" }
"light a candle"         = false

Put decisions inside your app.

A decision is a typed value your code holds before anything runs. Inspect it, show it, fill what is missing, ask for approval, then run it. Or let handle() do the whole loop.

import type { Reflexes } from "./evoke.d.ts"

const project = await load<Reflexes>({ root: import.meta.dirname })
const d = await project.decide("kill the lights in the den")

switch (d.outcome) {
  case "run":     await project.run(d); break
  case "confirm": if (await ui.confirm(d.prompt.template))
                    await project.run(d, { confirmed: true }); break
  case "ask":     project.fill(d, await ui.pick(d.missing)); break
  case "abstain": ui.say(d.contenders); break
}

// typed by evoke.d.ts once the reflex is known
if (d.outcome === "run" && d.reflex === "lights") {
  d.values.room    // string
  d.values.state   // "on" | "off" | "dim"
}

Use the SDK → The types, key by key: Decisions.

Connect compatible operations.

Two ways to run several things, with two owners. A weave is planned by evoke from declared outputs. A continuation is chosen by your program and driven by your loop.

const plan = await project.steps("look up dana's address and email them")
plan.steps       // [{ n: 1, text, decision, reflex: "contact", effect: "read", ... }, { n: 2, ... }]
plan.binds       // [{ from: 1, to: 2, arg: "to", field: "email", kind: "email", via: "fill" }]
plan.verdict     // { outcome: "run" | "ask" | "confirm" | "refuse", because?: [...] }

const woven = await project.weave(input, {
  ask: (d, turn) => ui.pick(d.missing, turn.step),     // before anything runs
  confirm: (d, turn) => ui.confirm(d.prompt.template),   // at the step's turn
})
woven.status     // the worst step's: "ran", "failed", "declined", "refused", "unanswered"

View the chaining example → The loop, in the runbook example.

Keep team-specific names separate.

Your data supplies the vocabulary. The operation underneath never changes. A multi-tenant server compiles the same reflexes over each tenant's own words, in milliseconds.

const tenant = project.with({ vocab: { rooms: await db.rooms(user) } })
const d = await tenant.decide(input)
if (d.outcome === "run") await tenant.run(d)

den    = "The TV room downstairs; also 'the snug'."
office = { what = "The upstairs study.", value = "group-7" }

Test the interpretation and the program.

Three tests, each for a different thing. The wording over the installed set, the control flow offline, and the body as a plain function.

$ evoke test
  lights  3 passed · 1 failed
    "make it darker in here"  state: expected "dim", read "off"
  timer   8 passed
  1 of 12 cases failed  →  evoke test
[1]

const record = process.env.RECORD ? jev() : undefined
const project = await load({
  reflexes: { timer },
  adapter: replay("answers.toml", { record }),
})
const d = await project.decide("timer for 10 minutes")
assert.equal(d.outcome, "run")

import note from "../note/note.mts"

const context = {
  input: "",
  config: { file: "notes/today.txt" },
  signal: new AbortController().signal,
}
assert.equal(await note({ text: "buy milk" }, context),
  'noted "buy milk" in ~/notes/today.txt')

Examples and tests → Testing in the SDK →

Share what you built.

Publishing is a git tag. No account, no registry, no build step. Others install from the repository, pinned by tag, commit and content. Their wording stays in their own files.

$ git tag v1.2.0 && git push --tags
$ evoke add radhi/home/lights
+ lights  radhi/home/lights 1.2.0  write  runs lights.mts
  inactive  lights: vocabulary "rooms" is empty  →  evoke vocab rooms add <word> "<meaning>"

$ evoke check
  lights  write  runs lights.mts
  1.2.0 → 2.0.0  major
    args.state  renamed power

Publish a reflex →

Where evoke fits in what you already have.