# Instructing an AI to Build ChainRender Apps

How to phrase instructions so an AI produces correct, Grade-A ChainRender apps. These patterns work with any
capable AI assistant (in a chat, an editor, or via the ChainRender MCP server).

## The golden rule: give it the vocabulary first

Always start by providing the machine-readable vocabulary as context:

```
Here is the ChainRender vocabulary you must compose within:
<paste JSON.stringify(vocabulary()) here>

Compose only using these node types, capabilities, and resolver kinds. Use the compose.* builders from
@chainrender/client. Do not invent constructs outside this vocabulary.
```

This one instruction prevents the most common AI failure — inventing an API that doesn't exist. ChainRender's
closed vocabulary makes the AI's output *constrained by construction*.

Two refinements:
- **Point it at the docs as Markdown** — `https://chainrender.org/docs/llms.txt` lists every page with a Markdown
  link, so the AI reads ChainRender's real rules instead of yours paraphrased.
- **Trim the vocabulary if context is tight.** Most of its ~59 KB is the resolver-kind list; give the AI the rest and
  let it look kinds up (MCP `chainrender_search_kinds` / `chainrender_describe_kind`).

## Instruction patterns that work

**Be explicit about the trust grade you want:**
> "Build a token-claim page. It must be **Grade A** — fully on-chain, no off-chain images or fetches. Use on-chain
> resolvers for any data."

**Name the resolver for live data:**
> "Show the ETH/USDC price using the **Chainlink feed resolver**, rendered as a live value."

**Ask it to check the tree first:**
> "Before grading, run `checkNode()` on the tree and fix every issue — `compile()` silently drops unknown fields and
> invalid enum values."

**Ask it to encode resolver args from the descriptor:**
> "Encode each slot's `arg` exactly as the kind's descriptor says — `abi.encode` of its args, or raw bytes when it's
> marked `packed`."

**Ask it to self-verify:**
> "After composing, call `grade()` and show me the letter and breakdown. If it's not Grade A, tell me exactly which
> dependency lowered it and fix it."

**Specify the app type:**
> "Make this a **multi-view app** with tabs: an Overview tab and a Details tab. Use `buildTabs`."

**Request the presentation as tokens, not hardcoded:**
> "Style it with the design tokens (spacing, colors) so it re-themes cleanly — don't hardcode pixel values."

## Instruction patterns to AVOID

- **Don't ask for arbitrary code or scripts** — ChainRender has no arbitrary-code path; the AI can't produce one,
  and asking wastes turns. Ask for declared actions and resolvers instead.
- **Don't ask it to "just fetch" off-chain data** casually — that drops the grade. If you want Grade A, say so, and
  the AI will use on-chain resolvers.
- **Don't skip the grade check** — always have the AI grade + show the breakdown, so trust is verified, not assumed.

## A complete example prompt

```
You are building a ChainRender app. Vocabulary:
<paste vocabulary()>

Task: An on-chain "member badge" that shows a verified-membership checkmark using the selective-disclosure
credential resolver, plus the member's verified ENS name (the ensName kind; its arg is the 20 address bytes).
Requirements:
- Grade A (fully on-chain).
- Compose with compose.* builders.
- After composing, run checkNode() and fix every issue; then call grade() and compileComponent(); show me the grade
  letter, the breakdown, and the hash.
- If the grade isn't A, name the offending dependency and fix it before finishing.
```

This gives the AI the schema, the task, the trust bar, and the self-verification step — everything it needs to
produce a checkable, Grade-A result.

## Why this is safe

Because ChainRender makes AI output *verifiable*:
- **Closed vocabulary** → the AI can't express an invalid app.
- **`grade()`** → the AI's trust claim is computed, not asserted; you see the real letter + reasons.
- **Deterministic `compileComponent()`** → you reproduce the exact hash independently.
- **The enforcer** → an unsafe app is refused at registration, even if the AI tried to produce one.

You're never trusting the AI's *word* that an app is safe or trustless — you're checking the grade and the hash.
That's the whole point: **AI proposes, the SDK and chain verify.**

## If the AI writes Solidity too

Give it the toolchain block from **[Local Build Environment](../guides/local-build-environment.md)** — Hardhat 3, solc
0.8.36, `pragma solidity ^0.8.28`, `cancun`, optimizer `runs: 200` with `yul: false`, viaIR off — and tell it the
`npm audit` Zod advisory is a known dev-only finding it must not "fix" with `--force`.

## Related
- **[Building ChainRender Apps with AI](../guides/building-with-ai.md)** — the step-by-step workflow.
- **[The Vocabulary](./vocabulary.md)** · **[The Trust Grade](../concepts/trust-grade.md)**