> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitfield.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Build with AI agents

> Give an AI agent the Runtime Kit public names so it adds features without importing private implementation code.

<div className="bf-article">
  <p className="bf-lead">
    Runtime Kit gives AI agents three public moves: read named data, send an action request, and edit `things-to-store-and-run.json` without importing private implementation code.
  </p>

  ## What this is

  This page is for founders and developers who ask an AI agent to build with Bitfield.

  An AI agent needs rails. Without rails, it will choose the fastest-looking direct dependency: import unpublished code, parse files in UI code, wire features directly together, or create a second data path. That can work for one screen and punish you later.

  Runtime Kit gives the agent a better instruction set:

  ```text theme={null}
  If you are writing app code:
    read with useBitfieldData(...)
    request work with sendRequestToBitfieldTarget(...)

  If you are declaring package material:
    edit things-to-store-and-run.json
    keep files inside the package
    expose stable data names and action names
  ```

  That is the whole point. An AI agent can move fast without making every feature depend on every other feature.

  ## The instruction to give your AI agent

  Paste this into your AI coding session before asking it to build a Bitfield feature:

  ```text theme={null}
  Use only the public Runtime Kit surface.

  App code may import:
  - sendRequestToBitfieldTarget from @bitfield/runtime-kit
  - useBitfieldData from @bitfield/runtime-kit/react

  App code must not import unpublished Runtime Kit code, parse things-to-store-and-run.json,
  construct storage addresses, choose low-level readers, or call the implementation for
  an action directly.

  Package work belongs in things-to-store-and-run.json.
  React work reads named data or sends action requests.
  If a feature needs new data, add it to things-to-store-and-run.json first.
  If a feature needs work to run, declare a stable action name and call that action.
  ```

  That prompt is not magic. It tells an AI agent which files and names it may use.

  ## The public work split

  Give an AI agent one of these jobs at a time:

  | Job                      | What the agent should edit                                           | What the agent should not edit             |
  | ------------------------ | -------------------------------------------------------------------- | ------------------------------------------ |
  | Add package data.        | `things-to-store-and-run.json` in the package.                       | React components.                          |
  | Add a screen.            | React screen code that imports the public hook.                      | Package admission or storage setup.        |
  | Add a user action.       | A call to an action name with payload and reply handling.            | The private implementation for the action. |
  | Add package-owned bytes. | Package-local files plus an entry in `things-to-store-and-run.json`. | Random local files outside the package.    |
  | Fix a broken read.       | Data name and component states.                                      | Low-level reader machinery.                |

  This split matters because AI agents are good at adding code quickly. Runtime Kit makes the fast path the safer path.

  ## Good request examples

  Ask for one concrete change at a time:

  ```text theme={null}
  Add a welcome panel that reads the data name "welcome-copy"
  with useBitfieldData(...). Render loading, error, empty, and success states.
  Do not import unpublished Runtime Kit code.
  ```

  ```text theme={null}
  Add a record for welcome copy in things-to-store-and-run.json. Keep the address stable,
  use one payload action, and do not put secrets in the package.
  ```

  ```text theme={null}
  Add a button that calls the action "welcome.suggest" with a JSON payload.
  Decode the reply bytes as JSON only because this action's reply shape says it
  returns JSON.
  ```

  These requests are specific enough that the agent can succeed without inventing a new architecture.

  ## Prompt packs

  Use these when you want the agent to build one specific Runtime Kit shape.

  ### First feature prompt

  ```text theme={null}
  Build the first Runtime Kit feature for a launch screen.

  Create or update one package file:
  - package set: launch-starter
  - package: launch-product
  - package file: things-to-store-and-run.json
  - record: package::launch-product::welcome-copy
  - action: launch.next-step

  Create one React screen:
  - read data name "welcome-copy" with useBitfieldData(...)
  - render loading, error, empty, and success states
  - add one button that calls sendRequestToBitfieldTarget(...)
  - decode reply bytes only according to the reply shape below

  Public action shape:
  - action: launch.next-step
  - request payload: { topic: string }
  - reply payload: { suggestion: string }

  Before editing, list the files you will touch and the product job each file owns.
  After editing, report package set, package, package file, data names, action names, payloads, replies, screens, and verification.
  ```

  ### React read prompt

  ```text theme={null}
  Add a React screen that reads the data name "launch-checklist".

  Use only:
  - useBitfieldData from @bitfield/runtime-kit/react

  The component must render:
  - loading
  - error
  - empty
  - success

  Do not parse things-to-store-and-run.json.
  Do not construct storage addresses.
  Do not import package files.
  ```

  ### Target request prompt

  ```text theme={null}
  Add a user action that calls "help.search".

  Use only:
  - sendRequestToBitfieldTarget from @bitfield/runtime-kit

  Request payload:
  - { query: string }

  Reply payload:
  - { results: { title: string; url: string }[] }

  Support cancellation if the query changes before the previous request finishes.
  Do not import the implementation for "help.search".
  Do not assume every action returns JSON unless this reply shape says it does.
  ```

  ### Package file prompt

  ```text theme={null}
  Create things-to-store-and-run.json for package "help-package".

  Package file:
  - things-to-store-and-run.json

  Things:
  - one stored_bytes file named "help/getting-started.txt"
  - one slot action named "help.search"

  Rules:
  - keep every package file path inside the package folder
  - use exactly one payload action for each record
  - do not include secrets
  - keep action names stable and product-facing
  ```

  ### Placeable surface prompt

  ```text theme={null}
  Add a screen placement named "launch.help".

  Descriptor:
  - id: launch.help
  - label: Help
  - region: panel
  - componentKey: surface.launch.help
  - preparedInputs: []
  - targets: [help.search]

  Shell rule:
  - the shell renders descriptor labels, order, active id, region, and componentKey
  - the shell must not branch on "help" or import HelpSearch directly

  Screen body rule:
  - the body may call help.search through sendRequestToBitfieldTarget(...)
  - the body must not import the implementation for help.search
  ```

  ### Troubleshooting prompt

  ```text theme={null}
  Debug this Runtime Kit feature by walking the public chain.

  Return this table:
  - package set
  - package
  - package file exists?
  - data names
  - action names
  - request payload shape
  - reply payload shape
  - screen states rendered
  - exact failed link: package file, data read, action request, reply decoding, local state, or activation
  - fix
  - verification

  Do not fix by importing unpublished Runtime Kit code.
  Do not fix by editing local state by hand.
  ```

  ## Bad request examples

  These requests invite tangled code:

  | Bad request                         | Better request                                                                                                |
  | ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
  | "Just read the data from Bitfield." | "Use `useBitfieldData('welcome-copy')` and render all four states."                                           |
  | "Wire the package into the page."   | "Declare package data in `things-to-store-and-run.json`, then read the data name from the page."              |
  | "Call the search implementation."   | "Call `product.search` with this payload shape."                                                              |
  | "Make it work however you can."     | "Stay inside the public Runtime Kit imports and explain any missing package file, data name, or action name." |

  The better request names the screen, data name, action name, and files an AI agent may touch.

  ## Bad output and corrected output

  ### Direct package parsing

  #### Wrong shape

  ```tsx theme={null}
  const packageFile = await fetch('/packages/help-package/things-to-store-and-run.json');
  const data = await packageFile.json();
  ```

  #### Public read

  ```tsx theme={null}
  const help = useBitfieldData<HelpCopy>('help-copy');
  ```

  The component reads named data. It does not parse package source.

  ### Unpublished Runtime Kit import

  #### Wrong shape

  ```ts theme={null}
  import { createBitfieldReadScope } from '@bitfield/runtime-kit/internal';
  ```

  #### Public import

  ```ts theme={null}
  import { useBitfieldData } from '@bitfield/runtime-kit/react';
  ```

  App code uses the public hook. Setup machinery stays outside app code.

  ### Missing UI states

  #### Wrong shape

  ```tsx theme={null}
  const welcome = useBitfieldData<WelcomeCopy>('welcome-copy');
  return <h2>{welcome.data.headline}</h2>;
  ```

  #### Full render path

  ```tsx theme={null}
  const welcome = useBitfieldData<WelcomeCopy>('welcome-copy');

  if (welcome.loading) return <p>Loading...</p>;
  if (welcome.error) return <p>Could not load welcome copy.</p>;
  if (!welcome.data) return <p>No welcome copy yet.</p>;

  return <h2>{welcome.data.headline}</h2>;
  ```

  Runtime Kit reads have loading, error, empty, and success states.

  ### Uncontracted reply parsing

  #### Wrong shape

  ```ts theme={null}
  const data = JSON.parse(new TextDecoder().decode(reply.payload));
  ```

  #### Declared reply shape

  ```ts theme={null}
  type SearchReply = { results: { title: string; url: string }[] };
  const data = JSON.parse(new TextDecoder().decode(reply.payload)) as SearchReply;
  ```

  JSON parsing is valid only when the action's reply shape says the reply is JSON.

  ### Local-state hand edit

  #### Wrong shape

  ```text theme={null}
  Open ~/.bitfield and edit the package record until the screen works.
  ```

  #### Repair the source

  ```text theme={null}
  Inspect local state for evidence, then repair `things-to-store-and-run.json`, account activation, or the Runtime Kit feature path that produced the bad state.
  ```

  Local state is support evidence. It is not the feature authoring surface.

  ## Review checklist for generated code

  Before you accept AI output, check these exact things:

  | Check         | Pass condition                                                                       |
  | ------------- | ------------------------------------------------------------------------------------ |
  | Imports       | App code imports only from `@bitfield/runtime-kit` or `@bitfield/runtime-kit/react`. |
  | Reads         | Components use `useBitfieldData(...)` and handle loading, error, empty, and success. |
  | Requests      | User actions call `sendRequestToBitfieldTarget(...)` with a non-empty target name.   |
  | Replies       | The code decodes reply bytes according to the action's reply shape.                  |
  | Package data  | Package material lives in `things-to-store-and-run.json` and package-local files.    |
  | Secrets       | No private keys, tokens, account files, or customer data are in package examples.    |
  | Package files | UI code does not parse package files or build storage paths.                         |

  If any row fails, reject the change and make an AI agent repair that exact file, name, or action first.

  ## Full Runtime Kit review map

  Make an AI agent fill this out before you accept the work:

  | Required answer  | Why it matters                                                                     |
  | ---------------- | ---------------------------------------------------------------------------------- |
  | Package set      | Prevents guessing which product/project the package belongs to.                    |
  | Package          | Names the package that owns the material.                                          |
  | Package file     | Confirms package material enters through `things-to-store-and-run.json`.           |
  | Records          | Names the package-owned data records.                                              |
  | Stored bytes     | Names package-owned files and confirms paths stay inside the package.              |
  | Data names       | Names what app screens read with `useBitfieldData(...)`.                           |
  | Action names     | Names what app actions call with `sendRequestToBitfieldTarget(...)`.               |
  | Request payloads | States the public shape sent to each target.                                       |
  | Reply payloads   | States how reply bytes are decoded.                                                |
  | Screens          | Names React components or screen-placement entries that use the data/action names. |
  | Render states    | Confirms loading, error, empty, and success are handled.                           |
  | Verification     | Gives the command, test, manual check, or docs validation used.                    |

  If any row is blank, an AI agent has not described the concrete public files and names clearly enough.

  ## What an AI agent should explain back

  Ask an AI agent to summarize the chain it used:

  ```text theme={null}
  Tell me:
  1. Which things-to-store-and-run.json file changed.
  2. Which data names the UI reads.
  3. Which action names the UI calls.
  4. Which payload and reply shapes are public.
  5. Which unpublished Runtime Kit code you did not import.
  ```

  If an AI agent cannot answer those five points, the work is not ready.

  ## Common mistakes

  **Letting an AI agent invent a new public API**

  If an AI agent adds a new hook, provider, context, or subscription import, stop it. The current public imports are one request function and one React read hook.

  **Letting an AI agent move package setup into React**

  React renders named data. Package admission belongs in Runtime Kit, not app components.

  **Letting an AI agent make action names too implementation-specific**

  Use stable product names like `product.search` or `welcome.suggest`. Do not expose the private runner, file name, or implementation choice in the action name.

  **Letting an AI agent ignore empty and error states**

  AI often writes the happy path only. Runtime Kit components should render loading, error, empty, and success states every time.

  ## Quick reference

  ```text theme={null}
  App read       -> useBitfieldData(...)
  App action     -> sendRequestToBitfieldTarget(...)
  Package data   -> things-to-store-and-run.json
  Public names    -> data names, action names, payloads, replies
  Review failure -> reject unpublished imports and storage wiring in app code
  ```

  ## Now build the bigger version

  Use this full prompt for the next AI-built feature:

  ```text theme={null}
  Build a Runtime Kit feature named launch-assistant.

  Create one package file with:
  - one record named launch-checklist
  - one stored file named launch-help
  - one action named launch.next-step

  Create one React screen with:
  - useBitfieldData('launch-checklist')
  - a button that calls sendRequestToBitfieldTarget(...)
  - loading, error, empty, and success states

  Before writing code, list:
  - package name
  - data names
  - action names
  - request payload shape
  - reply payload shape

  Use only @bitfield/runtime-kit and @bitfield/runtime-kit/react.
  Do not import unpublished Runtime Kit code.
  ```

  That prompt makes an AI agent build the package and the screen together while keeping the public files and names intact.
</div>