# Answer receipt

The collapsed record of something settled in a thread: the question or ask, the answer (or the assumption written in its place), who settled it and when, and a Change action that reopens it. An answer has a solid border and a tick; an assumption has a dashed border and reads "Assumed" in words, with what it means. Who answered comes from the app (`by`), never from the model. When Change no longer applies it stays in place, locked, saying why (`changeLocked`).

The question, the answer and the assumption are drawn as text, never as links or markup. What the record is (a question, a connection chosen, a mockup approved) is the app's `kind`. QuestionCard draws one when its question is answered or skipped.

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

## Install

```bash
npx candor-ui@4 add answer-receipt
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/answer-receipt`.
It brings in: agent-avatar, bidi, button, heading-level, heading-scope, locale, locked, relative-time, tokens, work, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import * as React from "react"
import { Link2, MessageCircleQuestion } from "lucide-react"
import type { AgentIdentity } from "@/lib/candor/chat"
import { AnswerReceipt } from "@/components/candor/answer-receipt"

const agent: AgentIdentity = { id: "a-plan", name: "Planning agent", role: "planner" }
const minutesAgo = (n: number) => new Date(Date.now() - n * 60_000)

export default function Example() {
  const [reopened, setReopened] = React.useState<string | null>(null)
  return (
    <div className="flex max-w-xl flex-col gap-3">
      <AnswerReceipt
        kind={{ label: "Question", icon: MessageCircleQuestion }}
        question="How often should customers be billed?"
        answer={{ kind: "answer", text: "Monthly, on the first of the month." }}
        by={{ kind: "person", name: "Dana Reyes" }}
        at={minutesAgo(12)}
        onChange={() => setReopened("billing")}
      />
      <AnswerReceipt
        kind={{ label: "Question", icon: MessageCircleQuestion }}
        question="Which currency should prices show in?"
        // Skipped: the assumption the agent wrote is the record, drawn dashed and read as "Assumed".
        answer={{ kind: "assumed", assumption: "US dollars", implication: "Prices show in USD only; no conversion." }}
        by={{ kind: "person", name: "Dana Reyes" }}
        at={minutesAgo(9)}
        onChange={() => setReopened("currency")}
      />
      <AnswerReceipt
        kind={{ label: "Connection chosen", icon: Link2 }}
        question="Where should the records come from?"
        answer={{ kind: "answer", text: "The production database, read only." }}
        by={{ kind: "agent", agent }}
        at={minutesAgo(3)}
        notes={["Replaced in round 2"]}
        onChange={() => setReopened("source")}
        // Your app knows when a choice can't be changed any more: Change stays, locked, and says why.
        changeLocked="The import has already run from this source."
      />
      {reopened && <p className="text-xs text-muted-foreground">Your app reopens the card for “{reopened}” here.</p>}
    </div>
  )
}
```

## <AnswerReceipt>

Props:

- `question: string`: The question or ask that was settled, often the agent's words. Shown as the record's heading, as text.
- `answer: AnswerReceiptAnswer`: What was settled: an answer (`{ kind: "answer", text }`) or a written assumption (`{ kind: "assumed", assumption, implication? }`).
- `kind?: AnswerReceiptKind | undefined`: What kind of record it is, in the app's words, drawn as a small label beside it. Left out, no label.
- `by?: Actor | undefined`: Who answered or skipped, from the app: an agent (with its avatar) or a person by name. Left out, nobody is named.
- `at?: Date | string | undefined`: When it was settled, shown as "3 minutes ago" with the exact time on hover. Left out, no time is shown.
- `notes?: readonly string[] | undefined`: Notes in the app's words, one per line under the record: "Replaced in round 2", "Late answer".
- `onChange?: (() => void) | undefined`: Shows Change; called when it's pressed. Reopen the question or ask from here.
- `changeLocked?: string | null | undefined`: Why the answer can't be changed any more, if it can't: Change stays and says so. `null` or unset means it can.
- `className?: string | undefined`
- `headingLevel?: HeadingLevel | undefined`: The level of the question's heading. Defaults to one below the nearest `HeadingScope`, else 2.

## Strings (`answerReceipt`)

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

- `answer`: Answer
- `assumed`: Assumed
- `assumptionMissing`: The assumption wasn’t recorded.
- `implication`: That means: {implication}
- `answeredByAt`: Answered by {name} {time}
- `answeredBy`: Answered by {name}
- `answeredAt`: Answered {time}
- `skippedByAt`: Skipped by {name} {time}
- `skippedBy`: Skipped by {name}
- `skippedAt`: Skipped {time}
- `change`: Change

## Types

### AnswerReceiptAnswer

What a receipt records: an answer someone gave, or the assumption written in its place.

```ts
{
  kind: "answer";
  /** The answer, a person's or the agent's words. Shown as text. */
  text: string;
} | {
  kind: "assumed";
  /** What is assumed, in the agent's words: "Monthly billing". Shown as text, under "Assumed". */
  assumption: string;
  /** What the assumption means, in the agent's words. Shown as "That means: …". */
  implication?: string | undefined;
}
```

### AnswerReceiptKind

The kind of thing settled, in the app's words: "Question", "Connection chosen", "Mockup approved".

```ts
{
  /** The kind's name, drawn beside the record. */
  label: string;
  /** An icon beside the label; the label is always drawn too. */
  icon?: LucideIcon | undefined;
}
```

## Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

### Actor

Import: `import type { Actor } from "@/lib/candor/work"` (item `work`, https://candor.themethodic.com/docs/work.md)

Who did something: an agent, named by the app, or a person. An agent is the identity the app gives it (its name is the app's, never the model's); a person is the name the app gives them. Digest, DigestEmail, ChangeList, DecisionReview and the approval items all take it.

```ts
{ kind: "agent"; agent: AgentIdentity } | { kind: "person"; name: string }
```

### HeadingLevel

Import: `import type { HeadingLevel } from "@/lib/candor/heading-level"` (item `heading-level`, https://candor.themethodic.com/docs/heading-level.md)

A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.

```ts
1 | 2 | 3 | 4 | 5 | 6
```

### AgentIdentity

Import: `import type { AgentIdentity } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

```ts
{
  id: string;
  /** The displayed name, e.g. "Architect agent". Never derived from model output. */
  name: string;
  role: AgentRole;
  specialty?: string | undefined;
}
```

## 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`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.
