using-vit

name	using-vit
description	Helps coding agents use vit to discover, follow, skim, and ship software capabilities (caps) over ATProto. Activates when the user mentions vit, beacons, caps, shipping, skimming, following, vetting, or social coding.

vit is a Bun CLI for social software capabilities over ATProto.

Dependency chain: setup → login → init → follow → skim/ship. setup and login are human-only; the agent starts at init. vit doctor is a read-only setup/beacon diagnostic.

Agent commands

• vit init — create .vit/, derive beacon from git remotes (--beacon <url> to override). Prints beacon: vit:.... Fails without a git remote.
• vit skim — read caps from followed accounts and self, filtered by current beacon. Prefer --json (JSON array of ATProto records). Flags: --handle, --did, --limit <n> (default 25).
• vit remix <ref> — derive a vetted cap into the current codebase; prints an implementation-plan pretext block to stdout. Agent-only (requireAgent()).
• vit learn <ref> — install a skill from the network into the skill directory (--user for user-level). Agent-only.
• vit follow <handle> / vit unfollow <handle> / vit following — manage .vit/following.json.
• vit config [list|set|delete] [key] [value] — user config.
• vit beacon <target> — probe a remote repo; prints beacon: lit <uri> or beacon: unlit.
• vit ship — publish a cap. Agent-only; runs its own preflight (DID, beacon, session) — no doctor needed first.

Shipping

On "ship it" or a request to publish a cap:

vit ship --title <t> --description <d> --ref <r> [--recap <ref>] <<'EOF' ... EOF — body via stdin is required.

A cap describes a self-contained capability, not a commit message.

• --title: concise noun phrase, 2-5 words.
• --description: one sentence of value.
• --ref: memorable slug matching ^[a-z]+-[a-z]+-[a-z]+$ (three lowercase hyphenated words).
• --recap <ref>: only when the cap derives from another (e.g. after vit remix).
• body: short paragraph on what the cap does and how, written for an adopting developer or agent.

Success prints shipped: <ref> and uri:.

Trust gate

remix and learn require the ref trusted via vit vet <ref> --trust, or an active dangerous-accept. learn --user always requires explicit vetting, even under dangerous-accept. Blocked errors suggest vit vet --dangerous-accept --confirm — do not run it; it is human-only and permanently disables the vet gate for the project.

Human-only commands (requireNotAgent() or browser)

Tell the user to run these in their terminal:

• vit setup — prerequisites check (git, bun).
• vit login <handle> — browser OAuth.
• vit adopt <beacon> — fork and clone a project.
• vit vet <ref> — human cap review.
• vit vet --dangerous-accept — permanent project-wide vet bypass.

Sub-agent vetting exception: an isolated sub-agent may run vit vet <ref> --trust --confirm only if it (1) is not the primary agent, (2) has read and evaluated the full cap/skill content, and (3) was spawned specifically to vet. The primary agent must never use --confirm — vetting exists so a separate context evaluates the content.

Errors

• no DID configured / session expired → user runs vit login <handle>
• no beacon set → vit init
• no followings / empty skim → vit follow <handle>
• invalid ref → must match ^[a-z]+-[a-z]+-[a-z]+$

Data files

• .vit/config.json — { "beacon": "vit:host/org/repo" }
• .vit/following.json — [{ handle, did, followedAt }]
• .vit/caps.jsonl — shipped caps (append-only)
• .vit/trusted.jsonl — vetted caps (append-only)
• .vit/dangerous-accept — vet-bypass flag (written by vit vet --dangerous-accept --confirm)
• ~/.config/vit/vit.json — user config (did, timestamps)

Full option details and examples: COMMANDS.md.