.vendo directory

.vendo/ is split by author, in three layers. Which layer a file belongs to tells you whether you may edit it and what can overwrite it.

Layer	Written by	Files
Machine	the deterministic scan, regenerated wholesale	`tools.json`, `catalog.json`, `theme.extracted.json`, `remixable/`, `components/`, `generated/`
Judgment	the AI pass, regenerated by the judge and never by a human	`judgments.json`
Human	you, with init scaffolding some of them, never overwritten	`overrides.json`, `policy.json`, `brief.md`, `design-rules.md`, `theme.json`, `knowledge.json`

That split is the point. A re-sync rewrites the machine layer and re-judges the AI layer without ever clobbering a decision a person made.

Every path

Path	Written by	Format
`tools.json`	`vendo sync`	`vendo/tools@3`. Each tool’s descriptor and execution `binding`, plus inferred field `semantics`, `srcHash`, `audience`, `outputSchema` when the source declares one, and `disabled` for anything extraction could not classify
`judgments.json`	`vendo sync`, AI pass	`vendo/judgments@1`. Keyed by tool name: `description`, `title`, `risk`, `critical`, `disabled`, `audience`, `semantics`
`overrides.json`	init, then you	`vendo/overrides@3`. Per-tool overrides plus `compounds`, `briefs`, per-surface tool menus (`surfaces.agent`, `surfaces.mcp`), and remix scanning (`remix.ignoreSlots`, `remix.sources`)
`catalog.json`	`vendo sync`	`vendo/catalog@1`. The host components your `<VendoProvider>` map registers
`policy.json`	init, then you	`vendo/policy@1`
`theme.json`	init extraction, then you	`VendoTheme`
`theme.extracted.json`	init and sync	`vendo/theme-extracted@1`. What the deterministic scan produced last time, and the merge base that tells “you edited this” from “the brand moved”
`brief.md`	init	The product brief for the system prompt
`design-rules.md`	you, optional	Generation-time design rules, re-read per generation so edits apply without a restart
`knowledge.json`	`vendo knowledge add`, then you	`vendo/knowledge@1`. The registered sources: globs, kind, visibility, name
`knowledge-manifest.json`	`vendo knowledge sync`	`vendo/knowledge-hash@1`. sha256 of every synced document. Regenerable, so deleting it re-syncs everything
`remixable/<slot>.json`	`vendo sync`	`SeedBaseline`. One captured `<Remixable>` wrapper, including the `ported` half a remix starts from
`generated/remix-wiring.ts`	`vendo sync`	TypeScript, not JSON. The const both `createVendo({ remixWiring })` and `<VendoProvider remixWiring>` take — see import & fork
`generated/remix-holes/<Slot>.tsx`	`vendo sync`	TypeScript. One slot’s unportable subtrees, cut from your component and rendered natively as holes
`components/<Name>.json`	`vendo sync`	`CapturedHostComponent`. One registered host component, refs only, no source
`components/modules/<hex>.json`	`vendo sync`	`CapturedModule`, `{ source, imports? }`, content-addressed by the sha-256 of its canonical JSON, so a module ten components share is stored once
`cloud.json`	`vendo sync`, asked once	`{ "pushComponents": boolean }`. This project’s answer to whether registered-component source may go to Vendo Cloud
`data/`	the store	PGlite files
`data/.gitignore`	init	`*` plus an exception for itself. Doctor warns E-CFG-002 when it is missing
`data/judge/`	`vendo sync`, AI pass	One raw artifact per judge stage. Deleted and repopulated on every AI run
`data/extract/`	`vendo init`	Raw extraction-stage artifacts, same idea

What to commit

Commit everything except data/. That directory is runtime state and debugging residue, and the .gitignore init writes there is what keeps it out. Commit components/ too. It is generated, but a missing local file is not a deletion signal to the Cloud push, so gitignoring it hides drift rather than cleaning anything up. generated/ is the one machine-layer directory your own source imports, so it has to exist before your app compiles. Either commit it or regenerate it ahead of the build — the demo host runs vendo sync in predev and prebuild and gitignores the directory. Size scales with distinct modules, not with components. The demo host stores 3 components in about 26 KB, and a 50-component registry over a shared design system lands in the low hundreds of KB, because every shared module and the app-root CSS are stored once. Mark components/ linguist-generated=true in .gitattributes so reviews collapse it.

The content surfaces

Five files are content surfaces. Per surface, resolution is a value passed to createVendo, then the local file, then unset, so the file’s existence is the switch.

Surface	`createVendo` key
`design-rules.md`	`apps.designRules`
`brief.md`	`instructions`
`theme.json`	`theme`
`policy.json`	`guard({ policy })`
`overrides.json`	`profile.overrides`

vendo config status shows which layer owns each one. See the CLI reference. tools.json and catalog.json are deliberately not on that list. They are generation inputs, not host-editable content.

​Every path

​What to commit

​The content surfaces

Every path

What to commit

The content surfaces