pathenger 0.1.0 → 1.0.0

package/README.md

@@ -1,567 +1,493 @@
-# pathenger
+# Pathenger
 
-Step-by-step flows for command-line apps. Explicit, branching, testable.
+Pathenger is a step-driven framework for command-line flows. You declare every step in one place, connect them explicitly, and start the flow from a named first step.
 
-Most prompt libraries hand you widgets and wish you luck with the orchestration. pathenger inverts that: you declare your CLI as a graph of steps, each one of which shows a message, does some work, or asks a question, and the flow engine walks the graph until you tell it to exit. Branches, loops, validation, and async work are all first-class. Your CLI _is_ the flow.
+Common prompt libraries hand you widgets and wish you luck with the orchestration. Pathenger does the opposite.
 
-```ts
-import { pathenger } from 'pathenger'
+You declare your CLI as a graph of steps. Each one shows a message, does some work, or asks a question. The engine walks the graph until you tell it to exit. Branches, loops, validation, and async work are all first-class.
 
-const io = pathenger.create()
+```
+npm i -S pathenger
+```
 
-io.step.output({
-	id: 'welcome',
-	message: 'Welcome aboard.',
-	duration: 1000,
-	next: 'name'
-})
+## Let's Go
 
-io.step.input({
-	id: 'name',
-	type: 'text',
-	message: 'What is your name?',
-	validate: (value) => value.length > 1 || 'A little longer, please.',
-	next: 'goodbye'
-})
+A step is either:
 
-io.step.output({
-	id: 'goodbye',
-	message: () => `Nice to meet you, ${io.results.name}.`,
-	level: 'success',
-	next: io.exit()
-})
+- A class extending `Pathenger.OutputStep` or `Pathenger.InputStep`
+- A typed object created with `Pathenger.createOutputStep()` or `Pathenger.createInputStep()`
 
-io.start('welcome')
-```
+Both forms work together in the same flow.
 
-That's a complete program. No `main()`, no prompt-then-if-then-prompt spaghetti. Register steps, point them at each other, start the flow.
+## Create a flow
 
-## Install
+Create one flow per CLI application. Its generic types define shared app state and the results produced by steps.
 
-```bash
-pnpm add pathenger
-```
+```ts
+import { Pathenger } from 'pathenger'
 
-## The mental model
+type Store = { bundleKb?: number; projectDirectory?: string }
 
-Three ideas, and you know the whole library:
+type Results = { confirmBuild?: boolean; build?: { bundleKb: number } }
 
-1. **A step either _does_ something or _asks_ something.** Output steps show a message and optionally run a task. Input steps show a message and collect an answer. A step never does both. If you need both then that's two steps. Step by step by step. Explicit progression.
+const flow = Pathenger.create<Store, Results>()
+```
 
-2. **Every step declares `next`.** There is no implicit "then the one below it." `next` is a step id, or a function that returns one, which is how you branch. Because `next` is explicit, it can point _backwards_ and cycles are _legal_, which is how you build menus and REPL-style apps that run until the user quits.
+`flow.store` is app-owned shared state. `flow.results` is engine-owned and receives each completed step’s result by step id.
 
-3. **`io` is your app's shared state.** `io.results` holds every step's result, keyed by step id (the engine writes it). `io.store` is yours: a typed grab-bag for anything that spans steps or lives in extracted functions.
+## Define output steps with classes
 
-## Creating your instance
+An output step shows a message, may run work, and then moves to its next step.
 
-Create one `io` per app and export it from a module. Every step file and every extracted helper imports it from there. No threading a context argument five levels deep.
+```ts
+class BuildDone extends Pathenger.OutputStep {
+	id = 'buildDone'
+	level = 'success'
+	next = flow.exit()
+
+	message = () => {
+		const bundleSize = flow.store.bundleKb ?? 0
+		return `Build complete. Output written to dist/ (${bundleSize} KB).`
+	}
+}
+```
 
 ```ts
-// source/io.ts
-import { pathenger } from 'pathenger'
+class Build extends Pathenger.OutputStep<{ bundleKb: number }> {
+	id = 'build'
+	message = 'Building…'
+	next = BuildDone
 
-type StoreT {
-	isPnpmInstalled?: boolean
-	templates?: Template[]
-}
+	task = async () => {
+		const bundleKb = await buildProject()
 
-export const io = pathenger.create<StoreT>()
-```
+		flow.store.bundleKb = bundleKb
+		return { bundleKb }
+	}
 
-The generic types `io.store` so every access is checked and autocompleted across your whole codebase. You can also declare your results shape with a second generic — see [TypeScript](#typescript).
+	post = async (result) => {
+		console.log(`Built ${result.bundleKb} KB.`)
+	}
+}
+```
 
-Your entry point imports the step files (importing registers them) and starts the flow:
+The generic on `OutputStep<Result>` types the values received by `next`, `post`, and `back`.
 
 ```ts
-// source/index.ts
-import { io } from './io'
-import './steps/welcome'
-import './steps/mainMenu'
-import './steps/createProduct'
+class Publish extends Pathenger.OutputStep<{ url: string }> {
+	id = 'publish'
+	message = 'Publishing…'
+	next = (result) => (result.url ? Published : flow.exit.error('Publish failed.'))
 
-io.start('welcome')
+	task = async () => {
+		return await publishProject()
+	}
+}
 ```
 
-## Output steps
+## Define input steps with classes
 
-An output step shows a message, optionally runs async work while the message is on screen, then moves on.
+An input step asks one question and produces one answer.
 
 ```ts
-io.step.output({
-	id: 'checkPnpm',
-	message: 'Checking for pnpm.',
-	duration: 1000,
-	task: async () => await hasGlobalPnpm(),
-	next: (result) => (result ? 'cloneTemplate' : 'noPnpmWarning')
-})
-```
+class ConfirmBuild extends Pathenger.InputStep<boolean> {
+	type: 'boolean' = 'boolean'
 
-Lifecycle: **pre → message → task → post → next**
+	id = 'confirmBuild'
+	message = 'Build the project?'
+	yes = 'Build'
+	no = 'Cancel'
 
-| Property   | Type                                                     | Required | What it does                                                                                                   |
-| ---------- | -------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
-| `id`       | `string`                                                 | yes      | Unique step id. Registering a duplicate throws immediately.                                                    |
-| `message`  | `string \| () => string`                                 | yes      | The text shown for this step. Functions run synchronously at render time.                                      |
-| `level`    | `'info' \| 'success' \| 'warning' \| 'error' \| 'debug'` | no       | Styling/color of the message. Defaults to `'info'`.                                                            |
-| `duration` | `number`                                                 | no       | Minimum milliseconds the step stays on screen (see below).                                                     |
-| `pre`      | `() => void \| Promise<void>`                            | no       | Async setup, runs silently _before_ the message renders.                                                       |
-| `task`     | `() => unknown \| Promise<unknown>`                      | no       | Async work, runs _while_ the message is on screen, with a spinner. Its return value becomes the step's result. |
-| `post`     | `(result) => void \| Promise<void>`                      | no       | Side effects after the result is locked in. Cannot block progression.                                          |
-| `next`     | `string \| (result) => string \| ExitToken`              | yes      | Where to go. Receives the step's result.                                                                       |
+	next = (shouldBuild) => {
+		return shouldBuild ? Build : flow.exit()
+	}
+}
+```
 
-### `duration`
+```ts
+class ProjectName extends Pathenger.InputStep<string> {
+	type: 'text' = 'text'
 
-`duration` is the **minimum time the step stays on screen**. That single rule covers everything:
+	id = 'projectName'
+	message = 'Project name?'
+	placeholder = 'my-app'
 
-- Message-only step with `duration: 1000` → the message shows for one second, then the flow advances. Use this to pace output so it reads as deliberate rather than dumped.
-- Step with a `task` → the spinner runs for _at least_ `duration`, and longer if the task is still pending. Fast tasks don't flash; slow tasks aren't cut off.
+	validate = (name) => {
+		return name.length >= 2 || 'Use at least two characters.'
+	}
 
-### `pre` vs `task`
+	next = Build
+}
+```
 
-`pre` runs **before** the message renders. It's setup: fetch the data the step needs to display itself. `task` runs **while** the message is on screen. It's the work the message narrates, i.e "Cloning product template…" with a spinner, where the message _is the UX for the work_. If you fold your work into `pre`, the user stares at the previous step while it happens and your message flashes by after the fact. Put display prerequisites in `pre`; put the actual work in `task`.
+The generic on `InputStep<Value>` types the value received by `validate`, `post`, `back`, and `next`.
 
-### The step's result
+Input classes declare their prompt type with `type`:
 
-An output step's result is its task's return value (`undefined` if there's no task). It lands in `io.results[id]` and is passed to `next` and `post`. Tasks that need to record more than one value write to `io.store`. (That is what it is for.)
+- `'text'`
+- `'boolean'`
+- `'select'`
+- `'multiselect'`
 
-## Input steps
+## Define typed object steps
 
-An input step shows a message and collects an answer.
+Use the factories for concise, fully typed object declarations.
 
 ```ts
-io.step.input({
-	id: 'productId',
-	type: 'text',
-	message: 'What will your product ID be?',
-	tip: 'alpha-numeric with dashes and underscores',
-	placeholder: 'my-new-product',
-	filter: /^[a-zA-Z0-9_-]*$/,
-	validate: async (value) => {
-		const existingIds = await fetcher('/api/getProductIds')
-		return existingIds.includes(value) ? `"${value}" is already taken.` : true
-	},
-	next: 'productName'
+const Welcome = Pathenger.createOutputStep({
+	id: 'welcome',
+	message: 'Welcome to Pathenger.',
+	duration: 500,
+	next: ConfirmBuild
 })
 ```
 
-Lifecycle: **pre → message → input (filter per keystroke) → validate (on submit) → post → next**
+```ts
+const Deployment = Pathenger.createInputStep({
+	type: 'select',
 
-| Property   | Type                                                   | Required | What it does                                                                                                                         |
-| ---------- | ------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `id`       | `string`                                               | yes      | Unique step id.                                                                                                                      |
-| `type`     | `'text' \| 'select' \| 'multiselect' \| 'confirm'`     | yes      | Which prompt to render.                                                                                                              |
-| `message`  | `string \| () => string`                               | yes      | The question. Functions run synchronously at render time.                                                                            |
-| `tip`      | `string \| () => string`                               | no       | Persistent hint rendered dim beneath the input. Turns red when validation fails.                                                     |
-| `pre`      | `() => void \| Promise<void>`                          | no       | Async setup before the message renders.                                                                                              |
-| `validate` | `(value) => true \| string \| Promise<true \| string>` | no       | Runs on ENTER. Return a string to block progression and show it as the reason, in red. May be async — a spinner shows while it runs. |
-| `post`     | `(result) => void \| Promise<void>`                    | no       | Side effects after the answer is accepted. Cannot block progression — that's `validate`'s job.                                       |
-| `next`     | `string \| (result) => string \| ExitToken`            | yes      | Where to go. Receives the answer.                                                                                                    |
+	id: 'deployment',
+	message: 'Where should this run?',
+	options: [
+		{ label: 'Cloud', value: 'cloud' },
+		{ label: 'On-premise', value: 'on-prem' }
+	],
 
-An input step's result is the submitted answer. It lands in `io.results[id]` and is passed to `validate`, `post`, and `next`.
+	next: (deployment) => {
+		return deployment === 'cloud' ? Publish : ConfigureServer
+	}
+})
+```
 
-### `type: 'text'`
+`createOutputStep()` and `createInputStep()` are the plain-object equivalents of the class base types. They provide contextual types for lifecycle callbacks and reject properties that do not belong to the selected step type.
 
-| Property      | Type                                   | What it does                                                                                                                                                                                                           |
-| ------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `value`       | `string \| () => string`               | Initial _editable_ value, prefilled in the input.                                                                                                                                                                      |
-| `placeholder` | `string \| () => string`               | Ghost text shown when the input is empty. Never submitted.                                                                                                                                                             |
-| `filter`      | `RegExp \| (value: string) => boolean` | Runs on **every keystroke**, synchronously. The keystroke is rejected if the candidate value fails. Regexes use **full-match semantics** — `/^[a-z]*$/` and `/[a-z]*/` behave identically; the whole value must match. |
+## Start a flow
 
-`filter` and `validate` split validation the way it actually needs to be split: `filter` is cheap and sync, so it can run per keystroke and physically keep bad characters out. `validate` runs once on submit, so it's allowed to be async and expensive — hit an API, read the filesystem, take its time behind a spinner. Don't put a network call in a keystroke handler; pathenger won't let you.
+Pass the complete flow definition to `start`.
 
 ```ts
-// Deriving the initial value from an earlier answer
-io.step.input({
-	id: 'productName',
-	type: 'text',
-	message: 'What will your product title be?',
-	value: () => titleCase(io.results.productId),
-	next: 'productRoute'
+await flow.start({
+	firstStep: Welcome,
+
+	steps: [Welcome, ConfirmBuild, Build, BuildDone],
+
+	onCancel: () => {
+		console.log('\nCancelled. Nothing was changed.')
+	}
 })
 ```
 
-### `type: 'select'`
-
-| Property  | Type                                                                           | What it does                     |
-| --------- | ------------------------------------------------------------------------------ | -------------------------------- |
-| `options` | `Option[] \| () => Option[]` where `Option = { label: string, value: string }` | The choices. Arrow keys + ENTER. |
+Pathenger instantiates every supplied step class once, uses factory-created objects directly, indexes the resulting steps by `id`, validates the graph, and begins at `firstStep`.
 
-The result is the chosen option's `value` — the string itself, not the `{ label, value }` object.
+A flow can use classes and object steps together:
 
 ```ts
-io.step.input({
-	id: 'deployment',
-	type: 'select',
-	message: 'Is your product deployed on-prem or in the cloud?',
-	options: [
-		{ label: 'On-Prem', value: 'on-prem' },
-		{ label: 'Cloud', value: 'cloud' }
-	],
-	next: (result) => (result === 'on-prem' ? 'verifyOnPrem' : 'shouldInstall')
+await flow.start({
+	firstStep: Welcome,
+	steps: [Welcome, Deployment, ConfirmBuild, Build, BuildDone]
 })
 ```
 
-### `type: 'multiselect'`
+## Link steps
 
-Same `options` shape as `select`; SPACE toggles, ENTER submits. The result is an **array** of the chosen values (empty array if nothing was chosen — use `validate` to require a minimum).
+Use a step reference when linking steps. This keeps links safe when IDs are renamed.
 
 ```ts
-io.step.input({
-	id: 'features',
-	type: 'multiselect',
-	message: 'Which features should be scaffolded?',
-	options: featureOptions,
-	validate: (values) => values.length > 0 || 'Pick at least one.',
-	next: 'confirmPlan'
-})
+next = BuildDone
 ```
 
-### `type: 'confirm'`
+A string id is also valid when needed:
 
-| Property | Type     | What it does                                    |
-| -------- | -------- | ----------------------------------------------- |
-| `yes`    | `string` | Label for the affirmative. Defaults to `'Yes'`. |
-| `no`     | `string` | Label for the negative. Defaults to `'No'`.     |
+```ts
+next = 'buildDone'
+```
 
-The result is a `boolean`.
+Use a function to branch based on the completed step’s result:
 
 ```ts
-io.step.input({
-	id: 'verifyOnPrem',
-	type: 'confirm',
-	message: 'Are you sureeee it is on-prem?',
-	yes: 'Yes, I am sure',
-	no: 'No, not really',
-	next: 'shouldInstall'
-})
+next = (answer) => (answer ? Build : flow.exit())
 ```
 
-## Dynamic properties are sync. Lifecycle hooks are async.
-
-This is the rule that keeps steps predictable, so it gets its own heading.
+Use `flow.exit()` for a successful terminal step:
 
-Any _display_ property — `message`, `tip`, `placeholder`, `value`, `options` — can be a function, and that function runs **synchronously at render time**. It reads from `io.results` and `io.store`; it never fetches. Anything async belongs in a lifecycle hook: `pre`, `task`, `validate`, or `post`.
+```ts
+next = flow.exit()
+```
 
-So "the select options come from an API" looks like this — `pre` fetches, `options` reads:
+Use `flow.exit.error()` for a failed terminal step:
 
 ```ts
-io.step.input({
-	id: 'chooseTemplate',
-	pre: async () => {
-		io.store.templates = await fetcher('/api/templates')
-	},
-	type: 'select',
-	message: 'Which template?',
-	options: () =>
-		io.store.templates.map((template) => ({ label: template.name, value: template.id })),
-	next: 'confirmTemplate'
-})
+next = flow.exit.error('Build failed. Check the compiler output.')
 ```
 
-The render loop never awaits a property, and you always know exactly when your code runs.
+## Output-step API
+
+Every output step requires:
+
+- `id: string`
+- `message: string | (() => string)`
+- `next: StepReference | string | ExitToken | ((result) => StepReference | string | ExitToken)`
+
+Optional output properties:
+
+- `level: 'info' | 'success' | 'warning' | 'error' | 'debug'`
+- `duration: number`
+- `pre: () => void | Promise<void>`
+- `task: () => Result | Promise<Result>`
+- `post: (result: Result) => void | Promise<void>`
+- `back: (result: Result | undefined) => void | Promise<void>`
+
+`pre` runs before rendering. Use it to fetch data needed by a dynamic message.
+
+`task` runs while the message is visible. Use it for the work the message describes.
 
-## Branching and why explicit `next` is the point
+`duration` is the minimum time an output step remains visible. A task may keep the step on screen longer, but never shorter.
 
-`next` is required on every step (it is literally the feature). Because progression is always explicit:
+`post` runs after the task settles.
 
-- **Branches are just functions.** `next: (result) => result ? 'installDeps' : 'skipInstall'`
-- **Cycles are legal.** A `next` can point at any registered step, including one "behind" it. Point every branch's final step back at a menu and you have an app that runs until the user quits:
+`back` compensates for external side effects if the user navigates back past the step.
+
+## Input-step API
+
+Every input step requires:
+
+- `type`
+- `id: string`
+- `message: string | (() => string)`
+- `next: StepReference | string | ExitToken | ((answer) => StepReference | string | ExitToken)`
+
+All input types may use:
+
+- `tip: string | (() => string)`
+- `pre: () => void | Promise<void>`
+- `validate: (answer) => true | string | Promise<true | string>`
+- `post: (answer) => void | Promise<void>`
+- `canGoBack: boolean`
+- `back: (answer) => void | Promise<void>`
+
+### Text input
 
 ```ts
-io.step.input({
-	id: 'mainMenu',
-	type: 'select',
-	message: 'What would you like to do?',
-	options: [
-		{ label: 'Create a product', value: 'createProduct' },
-		{ label: 'Delete a product', value: 'deleteProduct' },
-		{ label: 'Quit', value: 'quit' }
-	],
-	next: (result) => (result === 'quit' ? io.exit() : result)
+const Directory = Pathenger.createInputStep({
+	type: 'text',
+	id: 'directory',
+	message: 'Output directory?',
+	value: () => flow.store.projectDirectory ?? 'dist',
+	placeholder: 'dist',
+	filter: /^[a-z0-9-]+$/i,
+	next: Build
 })
 ```
 
-Notice the trick in that last line: option values can _be_ step ids, so the menu routes itself.
+Text-only properties:
 
-## Exiting
+- `value: string | (() => string)`
+- `placeholder: string | (() => string)`
+- `filter: RegExp | ((value: string) => boolean)`
 
-`io.exit()` returns an exit token. Use it anywhere a step id is accepted:
+### Boolean input
 
 ```ts
-next: io.exit() // clean exit, status code 0
-next: () => io.exit() // same, from a branch
-next: () => io.exit.error('Could not clone. Check your SSH credentials.') // red message, status code 1
+const Overwrite = Pathenger.createInputStep({
+	type: 'boolean',
+	id: 'overwrite',
+	message: 'Overwrite the existing directory?',
+	yes: 'Overwrite',
+	no: 'Cancel',
+	next: (shouldOverwrite) => (shouldOverwrite ? Build : flow.exit())
+})
 ```
 
-No magic strings. An exit token can't collide with a step id, can't be typo'd into a broken reference, and carries its message as data instead of a parsed prefix.
+Boolean-only properties:
 
-## `io.results` and `io.store`
+- `yes?: string`
+- `no?: string`
 
-**`io.results`** is engine-owned: after a step completes, `io.results[id]` holds its result (the answer for input steps, the task's return value for output steps). Read it anywhere — in later steps' dynamic properties, in `next` functions, in extracted helpers.
-
-**`io.store`** is yours. It's the shared state for everything that isn't a single step's result: flags set by tasks, data fetched in `pre`, accumulations across a loop. Because your app exports one `io` instance, extracted functions just import it — no context parameter threading through five layers of helpers:
+### Select input
 
 ```ts
-// source/utilities/cloneTemplate.ts
-import { io } from '../io'
-
-export async function cloneTemplate() {
-	try {
-		await git.clone(templateUrl, io.results.productId)
-		io.store.didCloneSucceed = true
-	} catch {
-		io.store.didCloneSucceed = false
-	}
-}
+const Template = Pathenger.createInputStep({
+	type: 'select',
+	id: 'template',
+	message: 'Choose a template.',
+	options: [
+		{ label: 'Starter', value: 'starter' },
+		{ label: 'Library', value: 'library' }
+	],
+	next: Build
+})
 ```
 
-Rule of thumb: if one step produces it and the flow consumes it, let it be the step's result. If it's shared, shaped, or written from helpers, put it in the store.
-
-## Starting the flow — and what gets validated
+### Multiselect input
 
 ```ts
-io.start('welcome')
+const Features = Pathenger.createInputStep({
+	type: 'multiselect',
+	id: 'features',
+	message: 'Choose features.',
+	options: () => availableFeatures(),
+	next: Build
+})
 ```
 
-`io.start` validates the graph **before rendering anything**:
+Select and multiselect properties:
 
-- Every static string `next` must resolve to a registered step. A typo fails at startup with a message naming the step and the missing id — never mid-flow after the user has answered six prompts.
-- The start id must exist.
-- Unreachable steps produce a warning (they're often a sign of a broken reference elsewhere).
+- `options: Array<{ label: string; value: string }> | (() => Array<{ label: string; value: string }>)`
 
-Duplicate ids don't even make it that far — `io.step.output` / `io.step.input` throw at registration.
+## Dynamic values
 
-Function `next`s can't be checked statically, so they're checked at runtime: returning an unknown id produces an error that names _which step_ returned _which bad id_, not a stack trace from the engine's guts.
-
-`Ctrl+C` is handled for you: the terminal is restored (no half-drawn prompt), an optional `onCancel` runs, and the process exits cleanly:
+Display properties may be values or synchronous functions:
 
 ```ts
-io.start('welcome', { onCancel: () => console.log('\nNo worries. Nothing was changed.') })
+message = () => `Building ${flow.results.projectName}…`
+placeholder = () => flow.results.projectName ?? 'my-app'
+options = () => flow.store.templates ?? []
 ```
 
-## Preseeded answers
+Dynamic functions run at render time. They should read already-available values from `flow.results` or `flow.store`.
+
+Do not fetch or perform async work in a dynamic function. Use `pre` instead.
 
-Pass answers up front and their steps resolve without prompting — the step still runs its lifecycle (`pre`, `validate`, `post`, `next`), it just skips the interactive part. This is how a scaffolding CLI grows a `--yes` mode, and how flows run in CI:
+## Shared state and results
+
+A task’s return value becomes that step’s result:
 
 ```ts
-io.start('welcome', {
-	answers: { productId: 'demo-product', deployment: 'cloud', shouldInstall: false }
-})
-```
+class Build extends Pathenger.OutputStep<{ bundleKb: number }> {
+	id = 'build'
+	message = 'Building…'
+	next = BuildDone
 
-Preseeded answers still go through `validate`. If a preseeded answer fails validation, the flow falls back to prompting for that step interactively — or, with `interactive: false`, exits with an error. `interactive: false` also means any _unseeded_ input step is an error: perfect for CI, where a hung prompt is a hung pipeline.
+	task = async () => {
+		return { bundleKb: 128 }
+	}
+}
 
-## Testing
+const bundleKb = flow.results.build?.bundleKb
+```
 
-Interactive CLIs are notoriously untestable. pathenger flows aren't, because the graph is data. `io.test` runs the flow headless — no TTY, no rendering, durations skipped — and returns what happened:
+Use `flow.store` for shared or shaped data, especially data written from helpers:
 
 ```ts
-import { io } from '../source/io'
-import '../source/steps'
-
-test('choosing on-prem routes through verification', async () => {
-	const run = await io.test('welcome', {
-		answers: {
-			productId: 'demo-product',
-			productName: 'Demo Product',
-			productRoute: '/demo-product',
-			deployment: 'on-prem',
-			verifyOnPrem: true,
-			shouldInstall: false
-		}
-	})
-
-	expect(run.visited).toContain('verifyOnPrem')
-	expect(run.results.deployment).toBe('on-prem')
-	expect(run.exit.code).toBe(0)
-})
+flow.store.projectDirectory = 'dist'
 ```
 
-`run.visited` is the ordered list of step ids the flow walked, `run.results` is the final results object, and `run.exit` tells you how it ended. Assert on paths, not pixels.
+Rule of thumb:
 
-`pathenger.create()` returns an instance precisely so tests can isolate: your _app_ makes `io` a singleton by exporting it, but a test can always construct a fresh one.
+- One step produces one value for later flow decisions: return it from the step.
+- Multiple steps or helpers need the value: write it to `flow.store`.
 
-## Handing over the terminal
+## Going back
 
-Sometimes a task needs to run a child process that has its own interactive moment — `git clone` asking for an SSH passphrase, an editor, a pager. Don't fight it; hand over the terminal:
+Set `canGoBack` on an input step to let the user return to a prior input and edit its answer.
 
 ```ts
-io.step.output({
-	id: 'cloneTemplate',
-	message: 'Cloning product template.',
-	task: async () => {
-		return await io.suspend(() =>
-			spawnWithInheritedStdio('git', ['clone', templateUrl, io.results.productId])
-		)
-	},
-	next: (result) =>
-		result.succeeded
-			? 'complete'
-			: io.exit.error('Clone failed. Check your SSH credentials.')
+const ConfirmBuild = Pathenger.createInputStep({
+	type: 'boolean',
+	id: 'confirmBuild',
+	message: 'Build now?',
+	canGoBack: true,
+	next: Build
 })
 ```
 
-`io.suspend` restores the cursor, leaves raw mode, runs your function with the terminal fully released, then re-enters the flow and redraws. The child process prompts however it wants; pathenger picks up where it left off.
+When going back, Pathenger restores the `flow.results` and `flow.store` snapshot from when the target input was first rendered.
 
-## TypeScript
-
-Declare your store and (optionally) your results shape when you create the instance:
+Pathenger cannot automatically undo filesystem, network, database, or process effects. Give side-effecting steps a `back` hook:
 
 ```ts
-interface Store {
-	isPnpmInstalled?: boolean
-	templates?: Template[]
-}
+class CloneTemplate extends Pathenger.OutputStep {
+	id = 'cloneTemplate'
+	message = 'Cloning template…'
+	next = Build
 
-interface Results {
-	productId: string
-	productName: string
-	deployment: 'on-prem' | 'cloud'
-	shouldInstall: boolean
-	features: string[]
-}
+	task = async () => {
+		return await cloneTemplate()
+	}
 
-export const io = pathenger.create<Store, Results>()
+	back = async () => {
+		await removeClonedTemplate()
+	}
+}
 ```
 
-Now `io.store.isPnpmInstalled` is a checked `boolean | undefined`, `io.results.deployment` is `'on-prem' | 'cloud'`, and a typo'd key is a compile error. Declaring your shapes up front is very much in the spirit of the library: explicit beats inferred-and-mysterious.
+Back hooks run in reverse order as steps are unwound.
 
-## A complete example
+## Preseeded answers and non-interactive runs
 
-The product-creation CLI, end to end:
+Pass answers to skip matching prompts:
 
 ```ts
-import { pathenger } from 'pathenger'
-import { titleCase } from 'change-case'
-import { fetcher, hasGlobalPnpm, cloneTemplate } from './utilities'
+await flow.start({
+	firstStep: Welcome,
+	steps: [Welcome, ConfirmBuild, Build, BuildDone],
+	answers: { confirmBuild: true }
+})
+```
 
-interface Store {
-	didCloneSucceed?: boolean
-}
+Preseeded values still run `validate`, `post`, and `next`.
 
-const io = pathenger.create<Store>()
+For CI or scripts, disable prompting:
 
-io.step.output({
-	id: 'welcome',
-	message: 'Welcome to the product creator.',
-	duration: 1000,
-	next: 'productId'
+```ts
+await flow.start({
+	firstStep: Welcome,
+	steps: [Welcome, ConfirmBuild, Build, BuildDone],
+	answers: { confirmBuild: true },
+	interactive: false
 })
+```
 
-io.step.input({
-	id: 'productId',
-	type: 'text',
-	message: 'What will your product ID be?',
-	tip: 'alpha-numeric with dashes and underscores',
-	placeholder: 'my-new-product',
-	filter: /^[a-zA-Z0-9_-]*$/,
-	next: 'productName',
-
-	validate: async (value) => {
-		const existingIds = await fetcher('/api/getProductIds')
-		return existingIds.includes(value) ? `"${value}" is already taken.` : true
-	}
-})
+An unseeded input in a non-interactive run is an error.
 
-io.step.input({
-	id: 'productName',
-	type: 'text',
-	message: 'What will your product title be?',
-	value: () => titleCase(io.results.productId),
-	next: 'productRoute'
-})
+## Testing
 
-io.step.input({
-	id: 'productRoute',
-	type: 'text',
-	message: 'What route should it live at?',
-	placeholder: () => '/' + io.results.productId,
-	next: 'deployment'
-})
+Use the same explicit step inventory in headless tests.
 
-io.step.input({
-	id: 'deployment',
-	type: 'select',
-	message: 'Is your product deployed on-prem or in the cloud?',
-	options: [
-		{ label: 'On-Prem', value: 'on-prem' },
-		{ label: 'Cloud', value: 'cloud' }
-	],
-	next: (result) => (result === 'on-prem' ? 'verifyOnPrem' : 'shouldInstall')
+```ts
+const run = await flow.test({
+	firstStep: Welcome,
+	steps: [Welcome, ConfirmBuild, Build, BuildDone],
+	answers: { confirmBuild: true }
 })
 
-io.step.input({
-	id: 'verifyOnPrem',
-	type: 'confirm',
-	message: 'Are you sureeee it is on-prem?',
-	yes: 'Yes, I am sure',
-	no: 'No, not really',
-	next: 'shouldInstall'
-})
+expect(run.visited).toEqual(['welcome', 'confirmBuild', 'build', 'buildDone'])
 
-io.step.input({
-	id: 'shouldInstall',
-	type: 'confirm',
-	message: 'Go ahead and install dependencies?',
-	next: (result) => (result ? 'checkPnpm' : 'cloneTemplate')
-})
+expect(run.results.build).toEqual({ bundleKb: expect.any(Number) })
 
-io.step.output({
-	id: 'checkPnpm',
-	message: 'Checking for pnpm.',
-	duration: 1000,
-	task: async () => await hasGlobalPnpm(),
-	next: (result) => (result ? 'cloneTemplate' : 'noPnpmWarning')
-})
+expect(run.exit.code).toBe(0)
+```
 
-io.step.output({
-	id: 'noPnpmWarning',
-	level: 'warning',
-	message: 'pnpm is not globally installed. Skipping dependency install.',
-	duration: 1000,
-	next: 'cloneTemplate'
-})
+Tests do not render the terminal, prompt for input, or wait for display durations.
 
-io.step.output({
-	id: 'cloneTemplate',
-	message: 'Cloning product template.',
-	task: async () => {
-		await cloneTemplate()
-	},
-	next: () =>
-		io.store.didCloneSucceed
-			? 'complete'
-			: io.exit.error('Failed to clone the template. Check your SSH credentials.')
-})
+## Release the terminal
 
-io.step.output({
-	id: 'complete',
-	level: 'success',
-	message: () =>
-		`Product created. cd ${io.results.productId} && pnpm start to begin development.`,
-	duration: 1250,
-	next: io.exit()
-})
+Use `flow.suspend()` when a child process needs direct terminal access.
 
-io.start('welcome')
+```ts
+class CloneRepository extends Pathenger.OutputStep {
+	id = 'cloneRepository'
+	message = 'Cloning repository…'
+	next = Build
+
+	task = async () => {
+		return await flow.suspend(() => spawnGitCloneWithInheritedStdio())
+	}
+}
 ```
 
-## Why not just use a prompt library?
+Pathenger releases the terminal, runs the supplied function, then restores the flow terminal state afterward.
 
-inquirer, prompts, and @clack/prompts are good at what they do: individual prompt widgets. But the moment your CLI has branches, loops, validation against live data, or async work between questions, the orchestration lands in your lap as a pile of `if`s and `await`s, and it's exactly the part that's hard to read, hard to change, and impossible to test.
+## Flow guarantees
 
-pathenger owns the orchestration. The flow is declared, so it can be validated at startup, preseeded for CI, walked headlessly in tests, and read top-to-bottom by the next person. The prompts are the easy part. The graph is the product.
+Before rendering, Pathenger validates the supplied flow:
 
-## API summary
+- Every step id is unique.
+- `firstStep` exists in `steps`.
+- Static `next` ids resolve to registered steps.
+- Unreachable steps produce a warning.
+- Dynamic `next` targets are validated when they resolve.
+- Classes are instantiated once per flow run.
+- Factory-created objects are used as declared.
 
-|                                        |                                                                                     |
-| -------------------------------------- | ----------------------------------------------------------------------------------- |
-| `pathenger.create<Store, Results>()`   | Create an `io` instance. Export one per app.                                        |
-| `io.step.output(step)`                 | Register an output step. Throws on duplicate id.                                    |
-| `io.step.input(step)`                  | Register an input step. Throws on duplicate id.                                     |
-| `io.start(startId, options?)`          | Validate the graph and run the flow. Options: `answers`, `interactive`, `onCancel`. |
-| `io.test(startId, options?)`           | Run headless. Returns `{ visited, results, exit }`.                                 |
-| `io.results`                           | Every completed step's result, keyed by step id. Engine-owned.                      |
-| `io.store`                             | Your shared state. Typed by the `Store` generic.                                    |
-| `io.exit()` / `io.exit.error(message)` | Exit tokens, usable anywhere a step id is accepted.                                 |
-| `io.suspend(fn)`                       | Release the terminal for a child process, then resume the flow.                     |
+The flow is explicit, typed, testable, and contained in its `start()` or `test()` call.