Agent install playbook

​

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) and tell your human detection did not apply.
2. Install the package.
   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?) and the model-key question explicitly:
   # 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), replace the .vendo/brief.md placeholder, and add the auth line if none was wired (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:
   npx vendo doctor --json
   
   Every failing or warning check carries an error_code and a fix_ref URL into the verify page. 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.
• 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: detect the host’s auth provider, wire the right preset, know when to ask the human.
• Tools and catalog: expose the host API as tools; the component catalog contract and anti-prop-invention rules.
• Verify: every doctor error code: symptom, cause, exact fix.