# Clarifying questions

The agent's questions before it plans (the first of two turns). Choices are cards you can pick with the number keys; text questions take a line. The agent's recommended option is marked but never pre-selected, so a person answers rather than rubber-stamps. A choice can offer "Other", for the person's own words. Asked mid-run (`during`), the heading drops "Before I plan".

- Registry name: `clarifying-questions` (`@candor/clarifying-questions`)
- 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/clarifying-questions

## Install

```bash
npx candor-ui add clarifying-questions
```

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

## Example

```tsx
"use client"

import type { ClarifyingQuestion } from "@/lib/work"
import { ClarifyingQuestions } from "@/components/clarifying-questions"

const questions: ClarifyingQuestion[] = [
  {
    id: "q1",
    kind: "choice",
    prompt: "Which values should region have?",
    options: [
      { id: "a", label: "us, eu, apac", detail: "Matches the data model notes" },
      { id: "b", label: "us, eu, apac, other", detail: "Adds a catch-all for customers that don't fit" },
      { id: "c", label: "One value per country", detail: "Finer than any data region Acme runs" },
    ],
    recommended: "b",
  },
  {
    id: "q2",
    kind: "choice",
    prompt: "Where should it appear?",
    multiple: true,
    options: [
      { id: "customer", label: "Customer page" },
      { id: "admin", label: "Admin customer view" },
      { id: "mobile", label: "Mobile app" },
    ],
  },
  { id: "q3", kind: "text", prompt: "Anything the team should know?", placeholder: "e.g. backfill from billing country", optional: true },
]

export default function Example() {
  return <ClarifyingQuestions className="max-w-xl" questions={questions} onSubmit={() => {}} onSkip={() => {}} />
}
```

## <ClarifyingQuestions>

Props:

- `questions: ClarifyingQuestion[]`: The agent's questions, asked one at a time in this order.
- `onSubmit: (answers: ClarifyingAnswer[]) => void`: Called with every answer once the last question is answered.
- `onSkip?: (() => void) | undefined`: Let the agent decide the rest itself.
- `submitting?: boolean | undefined` (default `false`): Disables Send and shows "Sending" while the answers go to the agent.
- `during?: boolean | undefined` (default `false`): The agent asks while it works, not before it plans.
- `className?: string | undefined`

## Strings (`clarifyingQuestions`)

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

- `label`: Questions from the agent
- `progress`: Before I plan · question {step} of {total}
- `progressDuring`: Question {step} of {total}
- `other`: Other
- `otherLabel`: Your answer
- `agentsPick`: Agent’s pick
- `back`: Back
- `letAgentDecide`: Let the agent decide
- `sending`: Sending
- `send`: Send answers
- `next`: Next

## 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`.