# Instructions editor

An agent's standing instructions, with variables like {{workspace.name}} that are filled in per run. Variables are checked as you type: a known one is listed with what it becomes; an unknown one is flagged, because it would reach the model as literal braces. Insert any known variable from the list.

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

## Install

```bash
npx candor-ui add instructions-editor
```

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

## Example

```tsx
"use client"

import * as React from "react"
import { InstructionsEditor, type InstructionVariable } from "@/components/instructions-editor"

const variables: InstructionVariable[] = [
  { name: "agent.name", description: "This agent’s display name", example: "Dev agent" },
  { name: "account.name", description: "The customer account", example: "Acme" },
  { name: "env.stage", description: "Production or the environment’s name", example: "Staging" },
]

export default function Example() {
  const [value, setValue] = React.useState(
    "You are {{agent.name}} on {{account.name}}’s software team.\n\nWork in {{env.stage}} unless someone names another environment. Never apply a migration to Production yourself: open an approval request.\n\nName new feature flags with the {{team.prefix}} prefix."
  )
  return <InstructionsEditor className="max-w-2xl" value={value} onChange={setValue} variables={variables} maxLength={4000} />
}
```

## <InstructionsEditor>

Props:

- `value: string`: The instructions text, with {{variables}} as written.
- `onChange: (value: string) => void`: Called with the new text on each edit or variable insert.
- `variables: InstructionVariable[]`: The variables a run fills in; any other {{name}} is flagged as unknown.
- `maxLength?: number | undefined` (default `8000`): Most characters allowed, shown as a count. Defaults to 8000.
- `className?: string | undefined`

## Strings (`instructionsEditor`)

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

- `instructions`: Instructions
- `insert`: Insert
- `length`: {length} / {max}
- `unknown`: { one: "Unknown variable: {names}. It would reach the model as written.", other: "Unknown variables: {names}. They would reach the model as written.", }

## Types

### InstructionVariable

```ts
{ name: string; description: string; example: string }
```

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