docs: point agents at describe and fix the --manifest command list

AGENTS.md

@@ -17,32 +17,14 @@
 
 ## Commands
 
-- `pnpm install`
-- `pnpm run build`
-- `pnpm run check`
-- `pnpm run test`
-- `pnpm run verify`
-- `pnpm run coverage`
-- `vref validate --output json`
-- `vref build`
-- `vref build --check --output json`
-- `vref serve`
-- `vref screenshot add ./capture.png --json '{"id":"home",...}' --dry-run --output json`
-- `vref convert --dry-run --output json`
-- `vref manifest add --json '{"id":"home",...}' --dry-run --output json`
-- `vref manifest update home --json '{"title":"Home"}' --dry-run --output json`
-- `vref screenshot remove home --dry-run --output json`
-- `vref describe --output json`
+- `pnpm install`, then `pnpm run verify` for the full gate; focused scripts are in [Contributing](https://github.com/putdotio/vref/blob/main/CONTRIBUTING.md#validation)
+- `vref describe --output json` lists every CLI command, flag, `--fields` value, and error code; usage examples are in the [README](./README.md) and [Visual Reference Guide](./docs/VREF.md)
 
 ## Effect
 
-This repository uses the Effect TypeScript library.
-
-Before writing any Effect code, first read `node_modules/effect/AGENTS.md`
-**completely**, and follow the links in the file when required.
-
-If you need to learn more about particular Effect APIs and concepts that the
-guide doesn't cover, search through the source code in `node_modules/effect/src`.
+This repository uses the Effect TypeScript library. The installed version's own
+guide is `node_modules/effect/AGENTS.md`; consult it for the APIs the change
+touches, and search `node_modules/effect/src` for anything it does not cover.
 
 ## Repo-Specific Guidance
 

docs/DISTRIBUTION.md

@@ -7,8 +7,7 @@
 Merges to `main` are publishable.
 [CI](https://github.com/putdotio/vref/blob/main/.github/workflows/ci.yml) runs `pnpm run verify` (see [Contributing](https://github.com/putdotio/vref/blob/main/CONTRIBUTING.md#validation)), then semantic-release publishes to npm from the `release` Environment when Conventional Commits produce a release.
 
-Those two links are absolute because neither file ships in the tarball, where a
-relative link would dead-end.
+Links to files outside the tarball are absolute so they resolve for npm consumers.
 
 The release job calls the [shared frontend release workflow](https://github.com/putdotio/.github) from `putdotio/.github`, pinned to a tagged commit; the semantic-release action and plugin pins live there. [`scan.yml`](https://github.com/putdotio/vref/blob/main/.github/workflows/scan.yml) calls the shared frontend scan workflow from the same repository: Gitleaks, TruffleHog, Actionlint, and Zizmor on pull requests, weekly, and on manual dispatch.
 
@@ -21,8 +20,8 @@ Release expectations:
 
 ## Package Contents
 
-The npm package includes `dist`, `README.md`, `docs`, `skills`, `AGENTS.md`,
-`CONTEXT.md`, and `SECURITY.md`. The reusable vref skill ships at
+`files` in [`package.json`](../package.json)
+lists what the npm package ships. The reusable vref skill ships at
 `skills/vref/SKILL.md` so consumer repos and shared skill installers can
 discover it, and `CONTEXT.md` travels with it because the packaged `AGENTS.md`
 links the glossary.

docs/VREF.md

@@ -23,9 +23,8 @@ Every command that rewrites the manifest stamps `updatedAt`, so the date the
 gallery displays is the date it last changed. A dry run leaves the file byte
 for byte as it was.
 
-`build`, `validate`, `screenshot add`, `convert`, and `manifest add` all take
-`--manifest`, so a repo mid-migration can keep its manifest somewhere else, such
-as `docs/visual/manifest.json`. Screenshot paths resolve relative to whichever
+Every command that reads a manifest takes `--manifest`, so a repo mid-migration
+can keep it somewhere else, such as `docs/visual/manifest.json`. Screenshot paths resolve relative to whichever
 directory holds the manifest.
 
 Point the gallery at that directory too. `--out` is independent of `--manifest`

skills/vref/references/manifest.md

@@ -20,7 +20,7 @@ Add a metadata-only entry, for a file you are placing yourself:
 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.webp","capturedAt":"2026-05-19T13:35:00.000Z","sizeBytes":39716,"tags":["settings"],"notes":["Settings page."]}' --dry-run --output json
 ```
 
-Convert an existing png or jpeg reference set to webp:
+Edit or remove entries, and convert an existing png or jpeg reference set to webp:
 
 ```bash
 vref manifest update settings --json '{"title":"Settings page"}' --dry-run --output json