@kitn.ai/chat/src/stories/docs/ForAIAgents.mdx

Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. Authored in SolidJS.

import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="Docs/Using with AI" />

# Using with AI

`@kitn.ai/chat` ships machine-readable orientation files that follow the
[llmstxt.org](https://llmstxt.org) convention, so coding agents (Claude Code,
Copilot, Cursor, Codex, …) can wire up the components correctly without guessing.

The philosophy is **human-led, AI-assisted**: humans own the architecture,
the design decisions, and the final review. The files below exist so that AI
tools do the wiring work correctly the first time instead of hallucinating
prop names or attribute APIs.

**View them now:** <a href="/llms.txt" target="_blank" rel="noreferrer">llms.txt</a> ·
<a href="/llms-full.txt" target="_blank" rel="noreferrer">llms-full.txt</a>
(open in a new tab)

## The files

Both files are **auto-generated** from `dist/custom-elements.json` by
`scripts/gen-llms.mjs` during `npm run build`, so they never drift from the
shipped API. Do not edit them by hand.

| File | Size | Audience | Contents |
|---|---|---|---|
| `llms.txt` | ~4 KB | Agents + humans | Dense orientation: install command, the property-vs-attribute rule, two-layer architecture, framework wiring (React / Vue / plain HTML), theming tokens. Fast to read — the right file to paste into a prompt. |
| `llms-full.txt` | ~60 KB | Agents | Everything in `llms.txt` plus a generated props/events table for every element, a streaming recipe, and a step-by-step "build a chat app" runbook. |

### Where to find them after `npm install`

```
node_modules/@kitn.ai/chat/llms.txt
node_modules/@kitn.ai/chat/llms-full.txt
```

Both paths are listed in the package's `files` field and are therefore always
present after install. They are also copied to `dist/llms/` inside the package
(at `node_modules/@kitn.ai/chat/dist/llms/llms.txt`), and published at:

- https://kitn.dev/llms.txt
- https://kitn.dev/llms-full.txt

## How to point an agent at them

| Tool | What to do |
|---|---|
| **Claude Code** | Add `@node_modules/@kitn.ai/chat/llms.txt` to `CLAUDE.md`, or run `read node_modules/@kitn.ai/chat/llms-full.txt` inside the session |
| **GitHub Copilot** | Add the path to `.github/copilot-instructions.md`; workspace indexing picks it up automatically |
| **Cursor** | Reference the file in `.cursorrules` |
| **Codex / ChatGPT** | Paste the URL `https://kitn.dev/llms.txt` into the prompt, or fetch it with a browsing tool |
| **Any agent** | `npm install @kitn.ai/chat` → file is at `node_modules/@kitn.ai/chat/llms.txt` |

For one-off sessions, pasting the content of `llms.txt` directly into the
system prompt is enough. For a project where the agent will revisit these
components repeatedly, point it at the installed file path so it always reads
the version that matches the installed package.

## What agents most need to know

These are the facts that AI tools most commonly get wrong when working with
`kc-*` elements. They appear in both machine-readable files, but they are
worth knowing up front.

### 1 — Array and object data goes on JS properties, not HTML attributes

An HTML attribute is always a string. Passing `messages`, `models`, `context`,
`suggestions`, or `slashCommands` as an attribute silently fails.

```js
const chat = document.querySelector('kc-chat');
chat.messages = [{ id: '1', role: 'assistant', content: 'Hi!' }]; // ✅ property
```

```html
<kc-chat messages="[...]"></kc-chat>  <!-- ❌ never works -->
```

Only scalar props (string / number / boolean) work as attributes — for example
`placeholder`, `loading`, and `theme`.

### 2 — Events are kebab-case `kc-*` CustomEvents, and they do not bubble

Listen directly on the element, not on a parent:

```js
chat.addEventListener('kc-submit', (e) => console.log(e.detail.value));
```

Common events: `kc-submit`, `kc-feedback`, `kc-model-change`, `kc-new-chat`, `kc-select`.

### 3 — Streaming requires a new array + new object on every chunk

Mutating an existing message object in place does **not** trigger a re-render.
Replace, don't mutate:

```js
// ✅ re-renders on every chunk
chat.messages = chat.messages.map(
  (m) => (m.id === aid ? { ...m, content: answer } : m)
);

// ❌ does NOT re-render
chat.messages[i].content = next;
```

The same rule applies to every array/object property: always assign a new
reference.

## Build a chat app (the runbook agents follow)

```js
import '@kitn.ai/chat/elements';
const chat = document.querySelector('kc-chat');
chat.messages = [];

chat.addEventListener('kc-submit', async (e) => {
  const userText = e.detail.value;

  // Append the user message (new array)
  const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: userText }];
  chat.messages = history;
  chat.loading = true;

  // Empty assistant placeholder to stream into
  const aid = crypto.randomUUID();
  chat.messages = [...history, { id: aid, role: 'assistant', content: '' }];

  // Stream — reassign a NEW array with a NEW message object each chunk.
  // Mutating in place will NOT re-render.
  let answer = '';
  for await (const token of streamFromYourAPI(history)) {
    answer += token;
    chat.messages = chat.messages.map((m) => (m.id === aid ? { ...m, content: answer } : m));
  }
  chat.loading = false;
});
```

## Agent Skills (progressive loading) — planned

Web Awesome and similar design systems are moving toward a **skills directory**:
a structured set of per-component markdown files that AI tools load
progressively, fetching only the documentation relevant to the current task.

`@kitn.ai/chat` already provides `dist/llms/llms-full.txt` as a single,
comprehensive reference (60 KB, all 42 elements). A per-element skills
directory would let agents pull just the `kc-chat` spec when they only need
that one element, rather than loading the full file.

This is tracked as a follow-up improvement. If you want it sooner, the starting
point is `scripts/gen-llms.mjs` — it already reads `dist/custom-elements.json`
and has all the data needed to emit `dist/skills/kc-chat.md`,
`dist/skills/kc-message.md`, etc.

## Links

- <a href="/llms.txt" target="_blank" rel="noreferrer"><code>llms.txt</code></a> — orientation (~4 KB; also at `https://kitn.dev/llms.txt`)
- <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>llms-full.txt</code></a> — full per-element reference (~60 KB; also at `https://kitn.dev/llms-full.txt`)
- Custom Elements Manifest — `dist/custom-elements.json` (published at `https://unpkg.com/@kitn.ai/chat/dist/custom-elements.json`)
- Repository — https://github.com/kitn-ai/chat