# `PromptRunner`
[🔗](https://github.com/nshkrdotcom/prompt_runner_sdk/blob/v0.12.1/lib/prompt_runner.ex#L1)

Public API for building plans and executing prompt runs.

# `plan`

```elixir
@spec plan(
  term(),
  keyword()
) :: {:ok, PromptRunner.Plan.t()} | {:error, term()}
```

# `preflight`

```elixir
@spec preflight(
  term(),
  keyword()
) :: {:ok, map()} | {:error, term()}
```

# `repair`

```elixir
@spec repair(
  term(),
  keyword()
) :: {:ok, PromptRunner.Run.t()} | {:error, term()}
```

# `run`

```elixir
@spec run(
  term(),
  keyword()
) :: {:ok, PromptRunner.Run.t()} | {:error, term()}
```

Builds a plan from `input` and runs it.

## Selecting what runs

Exactly one of these decides the targets; the first that applies wins.

- `prompts: ["02", "03"]` — run exactly these, in this order. An id naming no
  prompt is an error rather than a shorter run.
- `phase: 2` — run one phase
- `remaining: true` — run every prompt whose recorded status is not
  `completed`, in order, including prompts *earlier* than the furthest one
  that finished. A prompt with no record is remaining. A missing progress
  store means a new run; an existing unreadable or malformed store is an
  error rather than permission to re-run the packet.
- `continue: true` — resume from `last_completed + 1`. This steps over an
  earlier prompt that failed or never ran; when it does, the skipped prompts
  are named.
- `all: true` — run everything

## Pre-flight verification

`verify_first: true` evaluates a prompt's verify contract before invoking the
provider and, if it already passes, marks the prompt completed with no
session and records that no session ran. It defaults on under
`remaining: true` and off for explicitly named prompts, since naming a prompt
is a request to run it. A contract with no evaluable clause, and one
containing `changed_paths_only`, are never pre-flighted — both would pass
vacuously.

`keep_going: true` records prompt-local errors, attempts the rest of the
selected prompts, and returns all failures at the end. The default remains
fail-fast for dependent prompt chains.

# `run_prompt`

```elixir
@spec run_prompt(
  String.t(),
  keyword()
) :: {:ok, PromptRunner.Run.t()} | {:error, term()}
```

# `scaffold`

```elixir
@spec scaffold(
  term(),
  keyword()
) :: {:ok, map()} | {:error, term()}
```

# `status`

```elixir
@spec status(term()) :: {:ok, map()} | {:error, term()}
```

# `validate`

```elixir
@spec validate(
  term(),
  keyword()
) :: :ok | {:error, term()}
```

# `version`

```elixir
@spec version() :: String.t()
```

Returns the Prompt Runner version.

This is the single source of truth for every version string Prompt Runner
emits, including the CLI banner, generated packet manifests, and the
`run_prompts.exs` install entry.

---

*Consult [api-reference.md](api-reference.md) for complete listing*