vendo init: scan, interview, and scaffold your app

Run init after installing the umbrella:

npx vendo init

The wizard scans the app with deterministic analysis plus available AI assistance. It interviews you with recommendations on four questions: your model import, the product brief, risk labels for critical tools, and whether to open the MCP door. Theme is extracted automatically, not asked. It then proposes the handler route, the MCP discovery route when you opt in, and <VendoRoot> wiring. The scaffolded <VendoRoot> imports the extracted .vendo/theme.json and passes it as the theme prop, so shipped chrome adopts the host brand from the first boot with no hand wiring. Every code change is permission-gated and shown as a diff. Critical-tool risk answers land in .vendo/overrides.json and remain authoritative across future sync runs. Init also writes policy, product brief, theme, and the PGlite ignore entry where applicable. Init also proposes predev and prebuild hooks in package.json so extraction runs alongside your dev and build:

{
  "scripts": {
    "predev": "vendo sync",
    "prebuild": "vendo sync --strict"
  }
}

The proposal is idempotent (vendo sync is prepended when a hook already exists), preserves your existing formatting, and only writes if you approve the diff. Init also creates or appends VENDO_BASE_URL=http://localhost:3000 to .env.example with a comment explaining that present-mode credential forwarding is disabled without it. The write is idempotent — existing lines are preserved — so it is safe to run vendo init again. One of those questions is whether to open the MCP door. Opening it is a host decision and needs a HostOAuthAdapter, so init never invents auth wiring or flips mcp: true. On yes, init generates the Next.js /.well-known sibling route and points you at the remaining wiring. The door stays off unless you opt in.

Framework detection

Init reads package.json and scaffolds only the files that apply. It detects two frameworks by dependency:

Next.js (a next dependency): proposes app/api/vendo/[...vendo]/route.ts (under src/app when that directory exists) and wraps the root layout in <VendoRoot>. Opting into MCP also proposes app/.well-known/[...vendo]/route.ts in the same app-router layout.
Express (an express dependency): proposes a vendo/server.ts module (vendo/server.mjs without a tsconfig.json) holding the createVendo() composition and a Node HTTP-to-fetch adapter, plus a starter vendo/ai.ts. Two manual steps remain: mount the adapter with app.use("/api/vendo", mountVendo()) and wrap the client entry in <VendoRoot>. Init prints both, and vendo doctor reports broken until they are done.

Init recognizes only next and express, checking next first, so an app with both dependencies gets the Next scaffold. A host with neither is treated as Next. In other runtimes (Fastify, Hono, Bun), decline the proposed diffs and mount vendo.handler yourself. See Quickstart: Express and other JavaScript servers.

Agent mode

npx vendo init --agent

Agent mode emits the setup plan with its four plain-language questions and writes nothing. Use vendo doctor after setup. It checks wiring and makes one live /status round trip.

Non-interactive setup

Pass an app directory as the positional argument; it defaults to the current directory. For CI, agents, or a reviewed scripted setup, use:

npx vendo init [dir] --yes --model-import '@/lib/ai' --brief 'What the product does and who uses it'

--yes skips the four-question interview, still prints each proposed diff, and approves all code changes.
--model-import <specifier> chooses the module that exports the host’s AI SDK model (default @/lib/ai for Next.js and ./ai for Express).
--brief <text> supplies the contents of .vendo/brief.md.
--force regenerates Vendo-owned .vendo files while preserving existing host source files.

​Framework detection

​Agent mode

​Non-interactive setup

Framework detection

Agent mode

Non-interactive setup