Project anatomy

You ran vvd create and got a folder. Before you start changing things, it's worth two minutes to know what's in it — mostly because of what isn't.

The folder

bestiary/
├── vvd.json                     the manifest — identity, kind, capabilities
├── src/
│   ├── codec.ts                 your DATA MODEL, alone, pure
│   └── tool.tsx                 your UI            (apps: src/app.tsx)
├── tsconfig.json                strict TS; @/* → src/*; @vvd/sdk types from ~/.vvd
├── .gitignore                   ignores .vvd/ (local state), .vvd-build/, node_modules/
├── README.md
├── AGENTS.md                    the front door for a coding agent
├── ANALYTICS.md                 how to instrument THIS project
├── docs/
│   ├── references.md            "reference, don't retype" — pickers, refs, embeds
│   ├── documents-and-data.md    the codec API and merge semantics
│   ├── collaboration-and-presence.md
│   ├── canvases.md              maps, graphs, boards the vvd way
│   └── server-endpoints-and-secrets.md
└── .claude/skills/vvd-tool/SKILL.md

Two files are yours. The rest is reference material, and you can delete any of it.

src/codec.ts — the data model

The shape of your document, and nothing else. Keep it pure — no UI imports. That's not a style rule: when you ship, vvd save executes this module against a data-only stub to derive two things from your one declaration — which operations an agent can perform on your documents over the API, and which of your fields are searchable. Import React here and that derivation fails.

Storing data is the whole page on this file.

src/tool.tsx — the UI

A React component plus a defineTool call. For an app it's src/app.tsx and defineApp.

What is not there

No package.json. No node_modules. No lockfile. No bundler config.

A fresh project has zero dependencies, because React, the CRDT library, and @vvd/sdk are platform singletons the host injects when your bundle loads. Your project can't have its own copy of React — there is exactly one on the page and you share it.

export default function create(__deps) { … your code … }

tsconfig.json

Strict TypeScript, @/* mapped to src/*, and @vvd/sdk pointed at the SDK type sources the CLI keeps under ~/.vvd. Your editor gets full types with no install step.

If your editor says it can't find @vvd/sdk, the type sources weren't on disk when the project was scaffolded. Building and running are unaffected — the host injects the real SDK at run time — but fix the editor with:

vvd doctor --fix-types

✓ Types wired to the installed SDK bundle at /Users/you/.vvd/sdk (3 @vvd/* aliases).

AGENTS.md and .claude/

If you use a coding agent, these are its briefing: the loop, the five principles, and pointers into docs/. If you don't, ignore them — nothing in the platform reads them.

.vvd/ and .vvd-build/

Local state, gitignored. .vvd/dev.json remembers which world you last ran in — that's why the second vvd run needs no --world=.

vvd.json — the manifest

This is your project's identity, and the thing the platform validates when you ship.

{
  "id": "bestiary",              // FIXED identity — the document type / route the host keys on
  "name": "Bestiary",            // human-facing; change it whenever you like
  "kind": "tool",                // "tool" | "app"   (a wiki is an app + category: "site")
  "version": "0.1.0",
  "icon": "book-open",           // any lucide icon name
  "documentTypes": ["bestiary"], // tools: the document types this tool edits
  "codecModule": "@/codec",      // tools: the ONE data-model module `vvd save` derives from
  "needs": [],                   // host capabilities you require by name
  "capabilities": {
    "readsWorld": true,          // grants `world` + `search` — live read-only world queries
    "writesWorld": true,         // grants `projects` + `documents` — create/mutate world docs
    "sharing": false             // grants publishing a public site (wikis)
  },
  "entryModule": "@/tool"        // apps: "@/app"; apps also carry "route": "<id>"
}

Field by field

Edit it with the CLI, not by hand

The CLI validates as it writes, which saves you a round trip through a failed vvd save.

vvd info

  Bestiary (tool)

name             Bestiary
id               bestiary  (fixed)
kind             tool
version          0.1.0
icon             book-open
document types   bestiary
description      —
capabilities     reads world, writes world

vvd set name=Bestiarium reads=on

✓ name → Bestiarium
✓ reads world → on

vvd set version --bump minor

✓ version 0.1.0 → 0.2.0  (minor bump)

Editable fields: name, description, icon, version, route (apps only), reads, writes, share. Everything else is either derived or permanent.

Other useful forms:

vvd set icon --list          # browse the curated icon suggestions
vvd set version --bump minor # 0.1.0 → 0.2.0  (major | minor | patch)
vvd set --unset description  # clear an optional field
vvd rename "Dragon Dice"     # display name only — the id NEVER changes
vvd edit                     # walk every field interactively
vvd info --json              # the same thing, machine-readable

Three failures come out of this file, and all three are about the permanent fields:

vvd.json isn't valid: on save. vvd save runs the same parser the server runs, so anything that would be rejected on upload is rejected on your machine first, in the same words. Fix what it names and save again.

that id is taken (ID_TAKEN / ID_RESERVED). Something in the catalog already has that id. Because the id follows the name at create time, the fix is a fresh project with a different name — an existing project's id can't be edited.

this project's kind is locked (KIND_LOCKED). A project that's been shared or installed can't move between tool and app. Create a new project for the other kind and move your src/ across.

Next steps

• Storing data — src/codec.ts, in depth and editable.