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

# Agent install playbook

> The install playbook for coding agents: detect the stack, run vendo init with value flags, hand-wire the gaps the agent tail names, gate on the vendo doctor JSON output.

Vendo puts an agent inside a company's product: customers build views, act
through the host's own API as themselves, and automate work inside the host's
brand and guardrails. It installs as one npm package plus a small `.vendo/`
contract in the host repo. You, a coding agent, can complete the whole
install; `vendo init` does everything deterministic and tells you exactly what
is left.

## Install flow

1. **Detect the stack.** Read `package.json`. A `next` dependency means
   Next.js; an `express` dependency means Express. Those are the two scaffolded
   paths. Anything else is generic Node: Vendo's handler is a plain fetch
   handler, so follow the Express page's shape by hand
   ([Node quickstart](/quickstart-node)) and tell your human detection did not
   apply.

2. **Install the package.**

   ```bash theme={null}
   npm install vendoai
   ```

   `vendoai` is a thin alias of `@vendoai/vendo`; both install the same
   composition and the same `vendo` bin.

3. **Run init with value flags.** Every wizard question has a flag, so a
   non-interactive run never hangs on a prompt. Answer auth
   ([which preset?](/agents/host-auth)) and the model-key question explicitly:

   ```bash theme={null}
   # Next.js host using next-auth, bringing its own model key:
   npx vendo init --yes --auth authJs --byo

   # Express host with no auth provider, bringing its own model key:
   npx vendo init --yes --auth none --byo
   ```

   `--auth` takes `authJs`, `clerk`, `supabase`, `auth0`, `jwt`, or `none`.
   `--byo` declines the Vendo Cloud offer; `--cloud-key <key>` answers it with
   an existing key instead. Cloud vs bring-your-own is your human's call: ask
   before running `vendo cloud login` or assuming a provider key exists. `--framework <next|express>` is required only when
   detection fails (init errors with that exact instruction rather than
   guessing). Optional: `--ai-polish` consents to the AI extraction pass,
   `--theme slot=value` answers uncertain theme slots.

   Init scaffolds the two-file surface (an empty `vendo/registry.tsx` and the
   composition wired to it), writes the `.vendo/` contract (tools.json,
   overrides.json, policy.json, brief.md, theme.json), and adds
   `predev`/`prebuild` sync hooks. It never edits code the host authored.

4. **Hand-wire the gaps the agent tail names.** A non-interactive init ends
   with an `Agent tail:` block listing the exact files this run left for you;
   typically: wrap the root layout (or client entry) in the printed
   `<VendoRoot>` lines, register real host components in `vendo/registry.tsx`
   ([tools and catalog](/agents/tools)), replace the `.vendo/brief.md`
   placeholder, and add the auth line if none was wired
   ([host auth](/agents/host-auth)). Follow the tail, not memory; it is
   derived from what init actually wrote in this repo.

5. **Gate on doctor.** Start the dev server yourself (in `--json` mode doctor
   never starts it for you), then loop:

   ```bash theme={null}
   npx vendo doctor --json
   ```

   Every failing or warning check carries an `error_code` and a `fix_ref` URL
   into the [verify page](/agents/verify). Fix, re-run, repeat until exit 0.

## Rules of engagement

* **Ask your human before creating any account or key.** That includes Vendo
  Cloud (`vendo cloud login`), model provider keys, and sandbox accounts
  (E2B or the managed Cloud sandbox). Relay the choice; never sign up on your own.
* **Never invent props or tools outside the catalog.** Only components
  registered in `vendo/registry.tsx` exist, and only with the props their
  schemas declare. Only tools in `.vendo/tools.json` exist. Copy real names
  from source; see [tools and catalog](/agents/tools).
* **Doctor green is the only definition of done.** `vendo doctor --json`
  exiting 0 (no `broken` checks) is complete; anything less is not, and
  nothing more is required.
* **Run `vendo init` before touching `.vendo/`.** Init writes the whole
  `.vendo/` contract (`tools.json`, `overrides.json`, `policy.json`,
  `brief.md`, `theme.json`) itself. Don't author or edit any of those files
  before the first init run; re-run `npx vendo init` instead of hand-writing
  scaffold files (the route, the registry skeleton, `.vendo/` contents).

## The leaves

* [Host auth](/agents/host-auth): detect the host's auth provider, wire the
  right preset, know when to ask the human.
* [Tools and catalog](/agents/tools): expose the host API as tools; the
  component catalog contract and anti-prop-invention rules.
* [Verify](/agents/verify): every doctor error code: symptom, cause, exact
  fix.