AI agent docs

Every Kiavi package ships with a postinstall hook and an init CLI that drop the 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.

Installing or upgrading a Kiavi SDK automatically:

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 it does not exist. It falls back to CLAUDE.md if that is what your repo uses instead.

The update is safe and idempotent. Installing multiple Kiavi SDKs accumulates their entries in one fenced block.

Package managers can block dependency lifecycle scripts. A blocked script cannot print its own prompt because it never starts. pnpm 10 reports blocked scripts during install and lets you approve them with pnpm approve-builds; npm runs them by default unless ignore-scripts is enabled.

Run the affected package’s init command for an immediate manual refresh:

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

The init output checks globally disabled scripts and prints package-manager-specific approval guidance. For pnpm, run pnpm approve-builds in the project and approve the Kiavi package. For npm with scripts disabled, remove that restriction with npm config set ignore-scripts false if it matches your security policy. Agents may make these configuration changes only with the user’s approval.

<!-- 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)

Each doc's first line is a version marker (`<!-- @kiavi/<pkg>@<version> -->`).
Before trusting a doc, confirm that version matches the installed package in
`node_modules/@kiavi/<pkg>/package.json`. If they differ the doc is stale:
refresh it with `npx <pkg> init` (e.g. `npx kiavi-js init`), then re-read it.
Follow the init output to allow dependency scripts so future upgrades refresh it
automatically.
<!-- 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.

Normally the postinstall hook refreshes docs during an upgrade. Run init when the hook was blocked or whenever you want to force a refresh:

npx kiavi-browser init

Each installed .kiavi/<package>.md carries a version marker on its first line. Compare it against the installed package in node_modules/@kiavi/<package>/package.json to tell whether the docs are stale. That is exactly the check the AGENTS.md reference block asks your coding agent to run before it trusts a doc, so an agent can refresh the docs for you when they drift:

<!-- @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.