# Step walker

A guided walk (Candor's StepWalker): the stages across the top, the current one as a focus card below. Finished stages can be revisited; later ones can't be skipped to.

- Registry name: `step-walker` (`@candor/step-walker`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/step-walker

## Install

```bash
npx candor-ui add step-walker
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/step-walker`.
It brings in: locale, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import * as React from "react"
import { StepWalker } from "@/components/step-walker"
import { Button } from "@/components/ui/button"

const stages = ["Choose a repository", "Consent", "First read"]

const body = [
  "Pick the repository Keel should learn first. You can add more later.",
  "See exactly what Keel reads and where it goes, then allow it.",
  "Keel reads acme-api: tables, migrations and flags. You can ask questions while it reads.",
]

export default function Example() {
  const [stage, setStage] = React.useState(0)
  const last = stage === stages.length - 1
  return (
    <StepWalker className="w-full max-w-xl" stages={stages} current={stage} onGoTo={setStage}>
      <div className="rounded-xl border bg-card p-5">
        <h3 className="text-base font-semibold">{stages[stage]}</h3>
        <p className="mt-1 text-sm text-muted-foreground">{body[stage]}</p>
        <div className="mt-4 flex justify-end">
          <Button size="sm" variant={last ? "ghost" : "default"} onClick={() => setStage(last ? 0 : stage + 1)}>
            {last ? "Start over" : "Continue"}
          </Button>
        </div>
      </div>
    </StepWalker>
  )
}
```

## <StepWalker>

Props:

- `stages: string[]`: Stage names, in order.
- `current: number`: Index of the current stage, from 0; earlier ones show as done.
- `onGoTo?: ((index: number) => void) | undefined`: Lets finished stages be revisited; called with the stage's index.
- `children: React.ReactNode`
- `className?: string | undefined`

## Strings (`stepWalker`)

The fixed words, English by default. Override any of them under `stepWalker` in `<LocaleProvider strings={{ stepWalker: { … } }}>`; the table is exported as `stepWalkerStrings`.

- `steps`: Steps

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.