# Knowledge entry

One thing the agent knows, as a row: a kind badge from the app's `kinds` (a draft or confirmed requirement, an attachment, a convention, a lesson), the summary, a source line (who gave it or which agent inferred it, the app's words for where it came from, and when), the things it mentions as EntityChips, and a link to its evidence.

The summary is often the model's words, so it is drawn as plain text, never a link; the evidence link is the app's own address, drawn through the app's link (`LinkProvider`). A replaced entry is struck through and says so in words ("Replaced in round 2"), since a strike-through alone isn't read out or seen by everyone. "Correct this" calls the app, which asks the agent to correct the entry; the row changes nothing itself. In a list, put each row in an `<li>` of the app's `<ul>`.

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

## Install

```bash
npx candor-ui@4 add knowledge-entry
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/knowledge-entry`.
It brings in: badge, bidi, button, chat, entity-chip, link, locale, relative-time, tokens, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { FileCheck2, FilePen, GraduationCap } from "lucide-react"
import { KnowledgeEntry, type KnowledgeEntryKind } from "@/components/candor/knowledge-entry"

const ago = (h: number) => new Date(Date.now() - h * 3_600_000).toISOString()

const kinds: Record<string, KnowledgeEntryKind> = {
  draft: { label: "Draft requirement", icon: FilePen, tone: "outline" },
  confirmed: { label: "Confirmed requirement", icon: FileCheck2, tone: "accent" },
  lesson: { label: "Lesson", icon: GraduationCap },
}

const builder = { id: "a-build", name: "Builder", role: "dev" }

export default function Example() {
  return (
    <ul className="max-w-2xl divide-y rounded-xl border bg-card">
      <li>
        <KnowledgeEntry
          kind="confirmed"
          kinds={kinds}
          text="Orders over $50,000 need a second approver before they ship."
          from={{ person: "Dana" }}
          source={["Order approvals", "Question 4"]}
          at={ago(26)}
          entities={[
            { kind: "table", name: "orders" },
            { kind: "field", name: "orders.total", label: "Total" },
          ]}
          onCorrect={() => {}}
        />
      </li>
      <li>
        <KnowledgeEntry
          kind="draft"
          kinds={kinds}
          text="Orders over $25,000 need a second approver."
          from={{ agent: builder }}
          source={["Order approvals", "Round 1"]}
          at={ago(72)}
          replaced={{ where: "round 2" }}
        />
      </li>
      <li>
        <KnowledgeEntry
          kind="lesson"
          kinds={kinds}
          text="The orders table checks its rules before approval runs, so test orders need a total."
          from={{ agent: builder }}
          source={["This workspace"]}
          at={ago(5)}
          evidence={{ label: "Run 42, step 7", href: "#run-42" }}
          onCorrect={() => {}}
        />
      </li>
    </ul>
  )
}
```

## <KnowledgeEntry>

Props:

- `text: string`: What is known, in a sentence or two. Often the model's words: drawn as plain text, never a link.
- `kind?: string | undefined`: Which kind of entry it is: a key of `kinds`. A kind with no entry shows this key as it is.
- `kinds?: Readonly<Record<string, KnowledgeEntryKind>> | undefined`: The app's kinds, by key: each one's word, icon and tone.
- `from?: { person: string } | { agent: AgentIdentity } | undefined`: Who gave it: a person ("From Dana"), or an agent that inferred it ("Inferred by Builder").
- `source?: readonly string[] | undefined`: Where it came from, in the app's words, in order: `["Renewal board", "Question 4"]`. Each is drawn as text.
- `at?: string | undefined`: When it was learned, as an ISO time, drawn as a relative time. A time that can't be read is left out.
- `entities?: readonly EntityRef[] | undefined`: The things in the app's system the entry mentions, drawn as EntityChips.
- `onOpenEntity?: ((entity: EntityRef) => void) | undefined`: Makes each EntityChip a button; called with the entity pressed.
- `evidence?: { label: string; href: string } | undefined`: A link to what the entry rests on: the app's words and its own address, never one taken from model text.
- `replaced?: { where?: string | undefined } | undefined`: The entry has been replaced: it is struck through, with "Replaced in {where}" in words (or "Replaced").
- `onCorrect?: (() => void) | undefined`: Shows "Correct this"; called when it's pressed. Ask the agent to correct the entry from here.
- `className?: string | undefined`: Classes, merged with Candor's.

## Strings (`knowledgeEntry`)

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

- `inferredBy`: Inferred by {name}
- `from`: From {name}
- `replaced`: Replaced
- `replacedIn`: Replaced in {where}
- `correct`: Correct this
- `mentions`: Mentions

## Types

### KnowledgeEntryKind

One kind of entry, as the app names it: its word, an icon and a tone.

```ts
{
  /** The kind's word, in the app's words: "Confirmed requirement", "Lesson". Always drawn. */
  label: string;
  /** An icon before the word. */
  icon?: LucideIcon | undefined;
  /** The badge's tone. The word says what the kind is; the colour only goes with it. Default `neutral`. */
  tone?: "neutral" | "outline" | "accent" | "success" | "warning" | "destructive" | undefined;
}
```

## Types from other items

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

### 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;
}
```

### EntityRef

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

```ts
{
  kind: EntityKind;
  /** The identifier, e.g. "orders.status" or "billing.invoice.due_date". */
  name: string;
  /** A friendlier label when there is one, e.g. "Region". */
  label?: string | undefined;
  /** Where it lives, when more than one place is in scope, e.g. "Shop staging". */
  location?: string | undefined;
}
```

### AgentRole

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

What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).

```ts
string
```

### EntityKind

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

What kind of thing an entity is: "record", "table", "workflow"… Any string; the app registers each kind's icon and noun (see EntityKindsProvider), and presets cover the kinds of the systems an app commonly works with.

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