Installation

Install in an app repo that owns visual references:

pnpm add -D @putdotio/vref

Quick Start

Create a repo-local manifest and screenshots:

.vref/
  manifest.json
  screenshots/

Build the gallery:

vref build

Validate without writing index.html:

vref validate --output json
vref build --check --output json

After the owning app repo captures or updates screenshots, rebuild the gallery:

vref build

Open the gallery locally:

vref serve

Agents should inspect the command schema before automating:

vref describe --output json

When vref output is piped or captured in a non-interactive process, JSON is the default. Use --fields to keep automation responses small:

vref validate --fields screenshotCount,groupCount
vref describe --fields commands,automation

Manifest

vref reads .vref/manifest.json by default and writes .vref/index.html. Screenshot file paths are relative to .vref/ and must stay inside that directory.

{
  "version": 1,
  "title": "put.io Roku visual reference",
  "description": "Curated Roku screenshots for review and design comparison.",
  "updatedAt": "2026-05-19T13:35:00.000Z",
  "screenshots": [
    {
      "id": "home",
      "title": "Home",
      "group": "Main pages",
      "platform": "Roku",
      "device": "Roku 720p",
      "viewport": { "width": 1280, "height": 720 },
      "file": "screenshots/roku-720p/home.jpg",
      "capturedAt": "2026-05-19T13:34:00.000Z",
      "sizeBytes": 22788,
      "tags": ["home", "navigation"],
      "notes": ["Home menu with Files, Search, and Settings visible."]
    }
  ]
}

Append a screenshot entry from raw JSON without editing the manifest by hand:

vref manifest add --json '{"id":"settings","title":"Settings","group":"Main pages","platform":"Roku","device":"Roku 720p","viewport":{"width":1280,"height":720},"file":"screenshots/roku-720p/settings.jpg","capturedAt":"2026-05-19T13:35:00.000Z","sizeBytes":39716,"tags":["settings"],"notes":["Settings page."]}' --dry-run --output json

Remove --dry-run after the preview looks correct. The command only edits manifest metadata; app repos still own screenshot capture and file updates.

Docs

• Visual Reference Guide
• Plan
• Distribution
• vref skill
• Agent guide
• Security

Contributing

See Contributing for setup, validation, and pull request expectations.

License

MIT, see License