# Channel setup

Where agents can reach the team outside the app, one row per channel: its status, where it posts, and when an agent may post without asking. A broken channel says what's wrong and offers to reconnect.

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

## Install

```bash
npx candor-ui add channel-setup
```

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

## Example

```tsx
"use client"

import * as React from "react"
import { ChannelSetup } from "@/components/channel-setup"
import type { Channel } from "@/lib/ops"

export default function Example() {
  const [channels, setChannels] = React.useState<Channel[]>([
    { id: "slack", kind: "slack", status: "connected", target: "#eng-keel", replies: "updates" },
    { id: "teams", kind: "teams", status: "not-connected", replies: "off" },
    { id: "email", kind: "email", status: "broken", replies: "mentions", problem: "Bounced: platform@acme.example doesn’t accept outside mail" },
  ])
  return (
    <ChannelSetup
      className="max-w-xl"
      channels={channels}
      onConnect={() => {}}
      onReplies={(id, replies) => setChannels((cs) => cs.map((c) => (c.id === id ? { ...c, replies } : c)))}
    />
  )
}
```

## <ChannelSetup>

Props:

- `channels: Channel[]`: One row per channel, with its status, where it posts and when agents may post.
- `onConnect?: ((id: string) => void) | undefined`: Shows Connect, or Reconnect on a broken channel; called with the channel id.
- `onReplies?: ((id: string, r: Channel["replies"]) => void) | undefined`: Shows the when-agents-post choice on connected channels; called with the channel id and the new setting.
- `className?: string | undefined`

## Strings (`channelSetup`)

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

- `channels`: Channels
- `email`: Email
- `notConnected`: Not connected
- `whenAgentsPost`: {channel}: when agents post
- `repliesMentions`: When asked
- `repliesMentionsDetail`: Only replies when someone mentions it
- `repliesUpdates`: Updates
- `repliesUpdatesDetail`: Also posts when runs finish or need someone
- `repliesOff`: Off
- `repliesOffDetail`: Connected but silent
- `connect`: Connect
- `reconnect`: Reconnect

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