AI agent docs

Every Kiavi package ships with an init CLI that drops the same authoritative integration guide you’re reading here into your repo, where coding agents (Cursor, Claude Code, Aider, Continue, GitHub Copilot Chat with custom instructions, etc.) will pick it up.

The docs that get installed are the same llm-docs.md files that ship with the installed package version. They are version-pinned, so they describe the API of the version you actually have installed, not whatever’s current on npm.

After installing one or more Kiavi packages:

npx kiavi-browser init
npx kiavi-js init
npx kiavi-react-native init

(Substitute pnpm dlx, bunx, or yarn dlx for npx if you prefer. Pass --yes to skip the confirmation prompt, useful in CI.)

Each command:

1. Writes the package’s integration guide to .kiavi/<package-name>.md in your repo root.
2. Adds (or updates) a fenced reference block in AGENTS.md, or creates one if AGENTS.md doesn’t exist. Falls back to CLAUDE.md if that’s what your repo uses instead.

Re-running is safe and idempotent. Running multiple Kiavi inits accumulates, the fenced block always lists every Kiavi doc currently installed.

<!-- kiavi:start -->

## Kiavi auth

Integration docs for the Kiavi packages installed in this repo. When adding,
modifying, or removing authentication code, read the relevant file(s) below
before making changes.

- [@kiavi/kiavi-browser](./.kiavi/kiavi-browser.md)
- [@kiavi/kiavi-js](./.kiavi/kiavi-js.md)
<!-- kiavi:end -->

The fence markers (<!-- kiavi:start --> / <!-- kiavi:end -->) are how the init script finds the block on re-runs. Don’t edit them. Anything outside the fence is left alone, you can keep your own AGENTS.md content above and below it.

After upgrading any Kiavi package. The package’s postinstall hook prints a one-line hint pointing you at the right command. It stays silent when the docs are already at the installed version, so unchanged upgrades produce no noise:

  → @kiavi/kiavi-browser updated to 0.4.0, run `npx kiavi-browser init` to refresh integration docs.

Each installed .kiavi/<package>.md carries a version marker on its first line so the postinstall hook can compare:

<!-- @kiavi/kiavi-browser@0.3.1 -->

# @kiavi/kiavi-browser

...

Yes. Both should be checked in. They’re part of the agent context for your repo, the same way a README is. Reviewers benefit from seeing the integration guide your agent saw when it wrote the auth code.

The .kiavi/ files are short (around 250 lines per SDK) and they don’t change between unrelated commits, only when you upgrade a Kiavi package, so the diff noise stays minimal.

• It survives package upgrades cleanly (one file replaced, no diff to chase through your own code).
• Agents read it once and have the full surface area, no guessing about where the API reference lives.
• It makes the source of truth explicit: if your code disagrees with .kiavi/kiavi-browser.md, the doc wins, because it ships with the version you have installed.