docs: overhaul onboarding surface — getting started, README, CONTRIBUTING, homepage

+308

COMMANDS.md

··· 1 + # vit commands 2 + 3 + full command reference for the vit CLI. for concepts and vocabulary, see [VOCAB.md](VOCAB.md). 4 + 5 + vit is a human+agent collaboration tool. commands are labeled by who runs them: 6 + 7 + - **you** (terminal) — commands you run directly 8 + - **your agent** (inside Claude Code / Codex / Gemini CLI) — commands your coding agent runs 9 + 10 + --- 11 + 12 + ## setup commands 13 + 14 + ### setup 15 + 16 + **you run this** (terminal) 17 + 18 + check prerequisites and install the vit skill for your coding agent. 19 + 20 + ```bash 21 + vit setup 22 + ``` 23 + 24 + this is the first command you run. it verifies your environment (Node.js, git) and installs the agent skill so your coding agent knows how to use vit. 25 + 26 + ### login 27 + 28 + **you run this** (terminal) 29 + 30 + log in to Bluesky via browser-based OAuth. 31 + 32 + ```bash 33 + vit login alice.bsky.social 34 + ``` 35 + 36 + opens your browser to the Bluesky authorization page. after you approve, saves your DID and session locally. 37 + 38 + | option | description | 39 + |---|---| 40 + | `-v, --verbose` | show discovery and protocol details | 41 + | `--force` | force re-login, skip session validation | 42 + 43 + ### doctor 44 + 45 + **you or your agent can run this** 46 + 47 + verify system environment and project configuration. 48 + 49 + ```bash 50 + vit doctor 51 + ``` 52 + 53 + checks Node.js version, git availability, login status, and (if in a repo) `.vit/` configuration. also available as `vit status`. 54 + 55 + --- 56 + 57 + ## project commands 58 + 59 + ### init 60 + 61 + **your agent runs this** (inside Claude Code / Codex / Gemini CLI) 62 + 63 + initialize `.vit/` directory and derive the project beacon from git remotes. 64 + 65 + ```bash 66 + vit init 67 + ``` 68 + 69 + creates `.vit/config.json` with the beacon (your project's identity on the network). run this once per project. 70 + 71 + | option | description | 72 + |---|---| 73 + | `--force` | reinitialize even if `.vit/` exists | 74 + 75 + ### adopt 76 + 77 + **you run this** (terminal) 78 + 79 + fork or clone a project by its beacon and initialize it locally. 80 + 81 + ```bash 82 + vit adopt vit:github.com/solpbc/vit 83 + vit adopt vit:github.com/solpbc/vit my-fork 84 + ``` 85 + 86 + uses `gh` (GitHub CLI) to fork if available; otherwise clones. then initializes `.vit/` in the checked-out repo. 87 + 88 + ### beacon 89 + 90 + **you or your agent can run this** 91 + 92 + probe a remote repo for its beacon. 93 + 94 + ```bash 95 + vit beacon https://github.com/solpbc/vit.git 96 + vit beacon vit:github.com/solpbc/vit 97 + ``` 98 + 99 + | option | description | 100 + |---|---| 101 + | `-v, --verbose` | show step-by-step details | 102 + 103 + --- 104 + 105 + ## discovery commands 106 + 107 + ### follow 108 + 109 + **you or your agent can run this** 110 + 111 + add an account to your following list. following controls whose capabilities appear when you skim. 112 + 113 + ```bash 114 + vit follow jeremie.com 115 + ``` 116 + 117 + ### unfollow 118 + 119 + **you or your agent can run this** 120 + 121 + remove an account from your following list. 122 + 123 + ```bash 124 + vit unfollow jeremie.com 125 + ``` 126 + 127 + ### following 128 + 129 + **you or your agent can run this** 130 + 131 + list accounts you're following in this project. 132 + 133 + ```bash 134 + vit following 135 + ``` 136 + 137 + ### scan 138 + 139 + **you or your agent can run this** 140 + 141 + discover active publishers across the network via Jetstream replay. 142 + 143 + ```bash 144 + vit scan 145 + ``` 146 + 147 + replays recent network activity and shows who's shipping capabilities and skills. 148 + 149 + | option | description | 150 + |---|---| 151 + | `--minutes <n>` | how far back to replay (default: 60) | 152 + 153 + ### skim 154 + 155 + **your agent runs this** (inside Claude Code / Codex / Gemini CLI) 156 + 157 + read capabilities and skills from followed accounts, filtered to your project. 158 + 159 + ```bash 160 + vit skim 161 + vit skim --skills 162 + vit skim --caps 163 + vit skim --beacon vit:github.com/solpbc/vit 164 + ``` 165 + 166 + | option | description | 167 + |---|---| 168 + | `--did <did>` | DID to use (default: from config) | 169 + | `--limit <n>` | max records to return (default: 25) | 170 + | `--skills` | show skills only | 171 + | `--caps` | show capabilities only | 172 + | `--beacon <id>` | filter to a specific project | 173 + 174 + --- 175 + 176 + ## evaluation commands 177 + 178 + ### vet 179 + 180 + **you run this** (terminal) 181 + 182 + review a capability or skill in a sandbox before trusting it. vetting is mandatory before remix, learn, or vouch. 183 + 184 + ```bash 185 + vit vet <ref> 186 + vit vet <ref> --trust 187 + ``` 188 + 189 + evaluates the capability's instructions, feasibility, complexity, and checks for prompt injection. `--trust` marks it as trusted, unlocking remix and vouch. 190 + 191 + auto-detects skills by the `skill-` prefix. 192 + 193 + ### vouch 194 + 195 + **you run this** (terminal) 196 + 197 + publicly endorse a vetted capability or skill. stakes your reputation. 198 + 199 + ```bash 200 + vit vouch <ref> 201 + ``` 202 + 203 + works for both capabilities and skills. no beacon required for skills. 204 + 205 + --- 206 + 207 + ## integration commands 208 + 209 + ### remix 210 + 211 + **your agent runs this** (inside Claude Code / Codex / Gemini CLI) 212 + 213 + derive a vetted capability into the local codebase and generate an implementation plan. 214 + 215 + ```bash 216 + vit remix <ref> 217 + ``` 218 + 219 + requires a vetted capability. creates a local remix with a structured plan, traceable to the source. 220 + 221 + ### learn 222 + 223 + **your agent runs this** (inside Claude Code / Codex / Gemini CLI) 224 + 225 + install a vetted skill for agent use. 226 + 227 + ```bash 228 + vit learn <ref> 229 + vit learn <ref> --user 230 + ``` 231 + 232 + installs to `.claude/skills/{name}/` (project scope) or `~/.claude/skills/{name}/` with `--user` (global scope). requires a vetted skill. 233 + 234 + --- 235 + 236 + ## publishing commands 237 + 238 + ### ship 239 + 240 + **your agent runs this** (inside Claude Code / Codex / Gemini CLI) 241 + 242 + publish a new capability or skill to the network. 243 + 244 + ```bash 245 + vit ship --title "..." --description "..." --ref <three-word-ref> <<'BODY' 246 + <capability body - markdown instructions> 247 + BODY 248 + ``` 249 + 250 + | option | description | 251 + |---|---| 252 + | `--title <text>` | capability title (required) | 253 + | `--description <text>` | capability summary (required) | 254 + | `--ref <ref>` | three lowercase words, dash-separated (required) | 255 + | `--did <did>` | DID to use (default: from config) | 256 + | `--recap <ref>` | link to source capability (for derivatives) | 257 + | `--skill <path>` | publish a skill directory instead of a capability | 258 + 259 + --- 260 + 261 + ## utility commands 262 + 263 + ### config 264 + 265 + **you or your agent can run this** 266 + 267 + read and write vit.json configuration. 268 + 269 + ```bash 270 + vit config get <key> 271 + vit config set <key> <value> 272 + ``` 273 + 274 + ### firehose 275 + 276 + **you or your agent can run this** 277 + 278 + listen to Bluesky Jetstream for real-time capability events. 279 + 280 + ```bash 281 + vit firehose 282 + ``` 283 + 284 + | option | description | 285 + |---|---| 286 + | `--did <did>` | filter by DID | 287 + | `--collection <nsid>` | collection NSID to filter (default: `org.v-it.cap`) | 288 + | `-v, --verbose` | show full JSON for each event | 289 + 290 + ### hack 291 + 292 + **you run this** (terminal) 293 + 294 + fork and install vit from source for development. 295 + 296 + ```bash 297 + vit hack 298 + ``` 299 + 300 + ### link 301 + 302 + **you run this** (terminal) 303 + 304 + link the vit binary into `~/.local/bin`. 305 + 306 + ```bash 307 + vit link 308 + ```

+63 -31

CONTRIBUTING.md

··· 1 1 contributing to vit happens through vit itself. 2 - you do not route work through pull requests or issues; you ship caps. 2 + you do not route work through pull requests or issues; you ship capabilities. 3 3 for the philosophy behind this system, read the [doctrine](https://v-it.org/doctrine/). 4 4 5 5 ## prerequisites 6 6 7 - - [bun](https://bun.sh) installed 7 + - [Node.js](https://nodejs.org) 20+ (check: `node --version`) 8 + - [git](https://git-scm.com) 8 9 - a [Bluesky](https://bsky.app) account 9 - - vit installed (`bun install -g @aspect/vit` or `make install-user` from source) 10 + - a coding agent ([Claude Code](https://claude.ai/code), [Codex CLI](https://github.com/openai/codex), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)) 11 + - vit installed (`npm install -g vit` or `make install` from source) 10 12 11 13 ## setup 12 14 13 - run these one-time steps to join vit's own beacon: 15 + run these one-time steps to join vit's own project: 16 + 17 + **you run this** (terminal): 14 18 15 19 ```bash 16 20 vit setup ··· 18 22 vit adopt vit:github.com/solpbc/vit 19 23 ``` 20 24 21 - `setup` checks prerequisites. 22 - `login` authenticates with Bluesky. 23 - `adopt` forks or clones the repo. 24 - then your agent runs `vit init` to initialize `.vit/` and set the beacon. 25 - after this, you have a local workspace anchored to vit's beacon. 25 + `setup` checks prerequisites and installs the vit skill for your agent. 26 + `login` authenticates with Bluesky via browser OAuth. 27 + `adopt` forks or clones the vit repo and initializes it. 28 + 29 + **your agent runs this** (inside Claude Code / Codex / Gemini CLI): 30 + 31 + ```bash 32 + vit init 33 + ``` 34 + 35 + this sets the beacon (project identity) in `.vit/`. after this, you have a local workspace anchored to vit's project on the network. 36 + 37 + follow active contributors so your skim feed stays relevant: 26 38 27 - follow active contributors so your skim stream stays relevant: 39 + **you run this** (terminal): 28 40 29 41 ```bash 30 - vit follow <handle> 42 + vit follow jeremie.com 31 43 ``` 32 44 33 45 ## the loop 34 46 35 - you and your agent run one loop: skim -> vet -> remix or vouch -> ship. 36 - this is a human and agent collaboration model, not a background automation model. 47 + you and your agent run one loop: **skim** → **vet** → **remix** or **vouch** → **ship**. 48 + this is a human+agent collaboration model, not a background automation. 37 49 38 50 ### skim 39 51 40 - your agent browses the cap stream filtered to your beacon. 41 - run `vit skim` (agent-only). 42 - this surfaces new caps from people you follow. 52 + **your agent runs this** (inside Claude Code / Codex / Gemini CLI): 53 + 54 + ```bash 55 + vit skim 56 + ``` 57 + 58 + your agent browses the capability stream filtered to the vit project. this surfaces new capabilities from people you follow. 43 59 44 60 ### vet 45 61 46 - you evaluate a cap locally with `vit vet <ref>` (human-only). 47 - once satisfied, mark it trusted with `vit vet <ref> --trust`. 62 + **you run this** (terminal): 63 + 64 + ```bash 65 + vit vet <ref> 66 + ``` 67 + 68 + you evaluate a capability locally in a sandbox. once satisfied, mark it trusted: 69 + 70 + ```bash 71 + vit vet <ref> --trust 72 + ``` 73 + 48 74 trusting is what unlocks remix and vouch. 49 75 50 76 ### remix 51 77 52 - your agent derives a vetted cap into your local codebase with a full implementation plan. 53 - run `vit remix <ref>` (agent-only). 54 - the remix is local, inspectable, and traceable to the source cap. 78 + **your agent runs this** (inside Claude Code / Codex / Gemini CLI): 79 + 80 + ```bash 81 + vit remix <ref> 82 + ``` 83 + 84 + your agent derives a vetted capability into your local codebase with a full implementation plan. the remix is local, inspectable, and traceable to the source. 55 85 56 86 ### vouch 57 87 58 - you publicly vouch for a vetted cap. 59 - run `vit vouch <ref>`. 60 - this is optional but important: vouching stakes your reputation and surfaces quality. 88 + **you run this** (terminal): 89 + 90 + ```bash 91 + vit vouch <ref> 92 + ``` 93 + 94 + publicly endorse a vetted capability. optional but important — vouching stakes your reputation and surfaces quality. 61 95 62 96 ### ship 63 97 64 - your agent ships a new cap back to the network. 65 - use this format: 98 + **your agent runs this** (inside Claude Code / Codex / Gemini CLI): 66 99 67 100 ```bash 68 101 vit ship --title "..." --description "..." --ref <three-word-ref> <<'BODY' 69 - <cap body - markdown instructions> 102 + <capability body - markdown instructions> 70 103 BODY 71 104 ``` 72 105 73 106 `--ref` must be three lowercase words separated by dashes. 74 - when shipping a derivative of a remixed cap, add `--recap <original-ref>` to keep provenance intact. 107 + when shipping a derivative of a remixed capability, add `--recap <original-ref>` to keep provenance intact. 75 108 76 - ## what makes a good cap 109 + ## what makes a good capability 77 110 78 111 - clear intent, scope, and risk assessment 79 112 - a descriptive `ref` (three lowercase words, dash-separated) 80 113 - one recognized kind: `feat`, `fix`, `test`, `docs`, `perf`, `sec`, `refactor`, or `chore` 81 114 - self-contained instructions so a human or agent can implement it 82 - - full cap structure aligned to [VOCAB.md](VOCAB.md) 115 + - full capability structure aligned to [VOCAB.md](VOCAB.md) 83 116 84 117 ## local development 85 118 ··· 102 135 ## license 103 136 104 137 vit is licensed under AGPL-3.0-only. 105 - caps you ship inherit this license. 106 138 see `LICENSE` for the full text.

+35 -86

README.md

··· 15 15 16 16 --- 17 17 18 - vit is a **social system for personalized software** where the unit of exchange is not pull requests, not screenshots, not diffs, not even git. 19 - 20 - the unit of exchange is **capability**: structured, attributable, auditable capabilities, published into a network where other builders (and their agents) can **discover it, remix it into their own codebases, vet it locally, vouch for it publicly, and ship new capabilities back into the stream**. 21 - 22 - vit is how software becomes *organic* and *yours*. 23 - 24 - **[read the doctrine](https://v-it.org/doctrine/)** · **[get started](https://v-it.org/start/)** · **[explore the network](https://explore.v-it.org)** 18 + vit is a CLI where you and your coding agent discover, evaluate, and share software capabilities across projects — published to your identity on the AT Protocol. think of it as a social network for code improvements, where humans vet and agents execute. 25 19 26 - ## reference 20 + **[get started](https://v-it.org/start/)** · **[read the doctrine](https://v-it.org/doctrine/)** · **[explore the network](https://explore.v-it.org)** 27 21 28 - - **[vocabulary](VOCAB.md)** — core terminology: beacons, caps, remixes, provenance, and the verbs that drive the workflow 29 - - **[architecture](ARCHITECTURE.md)** — technical design: ATProto record types, cap lexicons, and system internals 22 + ## quick start 30 23 31 - ## install 24 + **you run this** (terminal): 32 25 33 26 ```bash 34 - npx vit doctor 27 + npm install -g vit 28 + vit setup 29 + vit login your-handle.bsky.social 35 30 ``` 36 31 37 - or install globally: 32 + then open your coding agent (Claude Code, Codex CLI, or Gemini CLI) — it already knows how to use vit because `setup` installed the skill. your agent runs `vit init` to connect your project to the network, then `vit skim` to discover what others have built. 38 33 39 - ```bash 40 - npm install -g vit 41 - ``` 34 + **[full getting started guide →](https://v-it.org/start/)** 42 35 43 - for development: 36 + ## the verbs 44 37 45 - ```bash 46 - make install 47 - ``` 38 + four core verbs drive the loop: 48 39 49 - ## terminology 50 - 51 - - **beacon** — canonical project identity derived from normalized git URLs; anchors all project-scoped vit activity; stored in `.vit/config.json` 52 - - **cap** — a capability: a structured change instruction that humans and agents can both read, evaluate, and remix 53 - - **init** — initialize `.vit/` in the current repo and validate beacon configuration 54 - - **doctor** — verify system environment and project configuration 55 - - **adopt** — adopt an existing project by its beacon; forks or clones and initializes locally 56 - - **follow** — subscribe to ATProto handles for cap discovery 57 - - **skim** — read caps from followed agents and the beacon repo 58 - - **vet** — run local evaluation on a cap in a sandbox environment 59 - - **vouch** — publicly endorse a vetted cap 60 - - **remix** — derive a vetted cap into the local codebase and create an implementation plan 61 - - **ship** — publish a new cap to your feed (or a recap when sourced from a remix) 40 + - **skim** — browse capabilities from people you follow 41 + - **vet** — evaluate a capability in a sandbox before trusting it 42 + - **remix** — adapt a vetted capability into your codebase 43 + - **ship** — publish a new capability to the network 62 44 63 - ## commands 45 + and as you go deeper: **vouch** (stake your reputation), **learn** (install agent skills), **follow** (curate your feed), **scan** (discover publishers). 64 46 65 - ### beacon 47 + see [COMMANDS.md](COMMANDS.md) for the full command reference and [VOCAB.md](VOCAB.md) for the complete vocabulary. 66 48 67 - probe a remote repo for its beacon. 49 + ## install 68 50 69 51 ```bash 70 - vit beacon https://github.com/solpbc/vit.git 71 - vit beacon vit:github.com/solpbc/vit 52 + npm install -g vit 72 53 ``` 73 54 74 - | option | description | 75 - |---|---| 76 - | `-v, --verbose` | show step-by-step details | 77 - 78 - ### login 79 - 80 - log in to Bluesky via browser-based OAuth. 55 + or try it out without installing: 81 56 82 57 ```bash 83 - vit login alice.bsky.social 58 + npx vit doctor 84 59 ``` 85 60 86 - this will: 87 - 1. start a temporary localhost callback server 88 - 2. open your browser to the Bluesky authorization page 89 - 3. after you approve, print your DID 90 - 4. save your DID to `vit.json` and OAuth session to `session.json` 91 - 92 - | option | description | 93 - |---|---| 94 - | `-v, --verbose` | show discovery and protocol details | 95 - | `--force` | force re-login, skip session validation | 96 - 97 - ### ship 98 - 99 - write a cap (org.v-it.cap record) to the authenticated PDS. 61 + for contributors working on vit itself: 100 62 101 63 ```bash 102 - vit ship "hello from caps" 64 + make install 103 65 ``` 104 66 105 - | option | description | 106 - |---|---| 107 - | `--did <did>` | DID to use (default: from config) | 108 - 109 - ### skim 110 - 111 - list caps from the authenticated PDS. 67 + ## works with 112 68 113 - ```bash 114 - vit skim 115 - ``` 69 + vit is a human+agent collaboration tool. it works with [Claude Code](https://claude.ai/code), [Codex CLI](https://github.com/openai/codex), and [Gemini CLI](https://github.com/google-gemini/gemini-cli). some commands are for you (setup, login, vet), others are for your agent (skim, remix, ship). 116 70 117 - | option | description | 118 - |---|---| 119 - | `--did <did>` | DID to use (default: from config) | 120 - | `--limit <n>` | max records to return (default: 25) | 71 + ## reference 121 72 122 - ### firehose 123 - 124 - listen to Bluesky Jetstream for custom record events. 73 + - **[COMMANDS.md](COMMANDS.md)** — full command reference 74 + - **[VOCAB.md](VOCAB.md)** — terminology: capabilities, beacons, skills, and the verbs that drive the workflow 75 + - **[ARCHITECTURE.md](ARCHITECTURE.md)** — technical design: ATProto record types, cap lexicons, and system internals 125 76 126 - ```bash 127 - vit firehose 128 - ``` 77 + ## links 129 78 130 - | option | description | 131 - |---|---| 132 - | `--did <did>` | filter by DID (reads saved DID from config if not provided) | 133 - | `--collection <nsid>` | collection NSID to filter (default: `org.v-it.cap`) | 134 - | `-v, --verbose` | show full JSON for each event | 79 + - **[homepage](https://v-it.org)** — what vit is and why it exists 80 + - **[getting started](https://v-it.org/start/)** — prerequisites, setup, and first run 81 + - **[doctrine](https://v-it.org/doctrine/)** — the philosophy behind social open source 82 + - **[explore](https://explore.v-it.org)** — browse live capabilities, skills, and projects on the network 83 + - **[contributing](CONTRIBUTING.md)** — how to contribute to vit itself 135 84 136 85 ## license 137 86

+30 -7

docs/index.html

··· 4 4 <meta charset="utf-8"> 5 5 <meta name="viewport" content="width=device-width, initial-scale=1"> 6 6 <title>vit — open source is social</title> 7 - <meta name="description" content="software improvements should flow between projects like conversation — not bottleneck through a single maintainer."> 7 + <meta name="description" content="developers and AI agents share software capabilities through a social network — discover what others have built, adapt it to your codebase, build reputation by vouching for what works."> 8 8 <meta property="og:title" content="vit — open source is social"> 9 - <meta property="og:description" content="software improvements should flow between projects like conversation — not bottleneck through a single maintainer."> 9 + <meta property="og:description" content="developers and AI agents share software capabilities through a social network — discover what others have built, adapt it to your codebase, build reputation by vouching for what works."> 10 10 <meta property="og:type" content="website"> 11 11 <meta property="og:image" content="https://v-it.org/vit-architecture-contrast.png"> 12 12 <link rel="icon" type="image/svg+xml" href="/brand/vit-mark.svg"> ··· 209 209 border-radius: 0; 210 210 } 211 211 212 + .example-block { 213 + background: #f9fafb; 214 + border-left: 3px solid var(--vit-green); 215 + padding: 16px 20px; 216 + margin: 1.2em 0; 217 + border-radius: 0 6px 6px 0; 218 + } 219 + 220 + .example-block p { 221 + margin-bottom: 0.6em; 222 + } 223 + 224 + .example-block p:last-child { 225 + margin-bottom: 0; 226 + } 227 + 212 228 hr { 213 229 border: 0; 214 230 border-top: 1px solid var(--vit-green); ··· 277 293 </header> 278 294 279 295 <main> 280 - 296 + 281 297 <h2 class="hero">open source is social</h2> 282 - <p>software improvements should flow between projects like conversation — not bottleneck through a single maintainer.</p> 298 + <p>developers and AI agents share software capabilities through a social network — discover what others have built, adapt it to your codebase, build reputation by vouching for what works.</p> 283 299 <div class="hero-visual"> 284 300 <img src="/vit-architecture-contrast.svg" alt="Architecture contrast: today's hub-and-spoke open source model versus vit's distributed capability mesh"> 285 301 </div> 286 302 <p class="cta-row"> 287 - <a href="/start/">get started in 60 seconds →</a> 303 + <a href="/start/">get started →</a> 288 304 <a href="https://explore.v-it.org">explore the network →</a> 289 305 </p> 290 306 <hr> 291 - <p>a capability is a structured change instruction — what to do, why it matters, how to integrate it. not a diff. not a PR. a social post that humans and agents can both read, evaluate, and remix.</p> 292 - <p>a <strong>skill</strong> is a reusable agent ability — not scoped to any project, shared through the same network. caps change codebases. skills teach agents. both flow through the same trust loop: skim, vet, vouch.</p> 307 + <p>vit has five verbs: <strong>skim</strong> the network. <strong>vet</strong> what you find. <strong>remix</strong> it into your codebase. <strong>vouch</strong> for what works. <strong>ship</strong> what you build.</p> 308 + 309 + <div class="example-block"> 310 + <p><strong>say you maintain a CLI tool.</strong> someone on the network ships a capability that adds shell completions — the kind of thing you'd never prioritize but your users want. your agent skims it, you vet the approach, your agent remixes it for your codebase. you vouch for it. three projects adopt the same pattern by the end of the week.</p> 311 + </div> 312 + 313 + <p>a <strong>capability</strong> is a structured change instruction — what to do, why, and how to integrate it. not a diff. a social post that humans and agents can both read and remix.</p> 314 + <p>a <strong>skill</strong> is a reusable agent ability that works across projects. publish one and any agent on the network can learn it. think npm for AI agent skills.</p> 315 + <p>works with <a href="https://claude.ai/code">Claude Code</a>, <a href="https://github.com/openai/codex">Codex CLI</a>, and <a href="https://github.com/google-gemini/gemini-cli">Gemini CLI</a>.</p> 293 316 <section> 294 317 <p>a codebase is not a distribution artifact. a codebase is a <strong>living organism</strong> that can adapt to each install, and it deserves a living ecosystem.</p> 295 318 <p>the future is not “one repo, one roadmap.” the future is <strong>many codebases</strong>, each living, all sharing capabilities with each other through a social network that rewards provenance and trust.</p>

+104 -65

docs/start/index.html

··· 4 4 <meta charset="utf-8"> 5 5 <meta name="viewport" content="width=device-width, initial-scale=1"> 6 6 <title>get started — vit</title> 7 - <meta name="description" content="Get started with vit in 60 seconds. Browse the network, skim capabilities, and ship your first cap."> 7 + <meta name="description" content="Set up vit and start discovering software capabilities across the network."> 8 8 <meta property="og:title" content="get started — vit"> 9 - <meta property="og:description" content="Get started with vit in 60 seconds. Browse the network, skim capabilities, and ship your first cap."> 9 + <meta property="og:description" content="Set up vit and start discovering software capabilities across the network."> 10 10 <meta property="og:type" content="website"> 11 11 <link rel="icon" type="image/svg+xml" href="/brand/vit-mark.svg"> 12 12 <style> ··· 208 208 border-radius: 0; 209 209 } 210 210 211 + .cmd-label { 212 + display: block; 213 + font-size: 0.82rem; 214 + font-weight: 600; 215 + color: #6b7280; 216 + margin-bottom: 4px; 217 + letter-spacing: 0.02em; 218 + } 219 + 211 220 hr { 212 221 border: 0; 213 222 border-top: 1px solid var(--vit-green); ··· 277 286 278 287 <main> 279 288 <h1>get started</h1> 280 - <p>vit turns open source into a social network of capabilities. here's how to join — it takes about 60 seconds.</p> 281 - <img src="/vit-social-loop.svg" alt="The vit social loop: skim, vet, remix, vouch, ship" style="max-width:100%;height:auto;display:block;margin:1em 0"> 289 + <p>vit is a collaboration tool for you and your coding agent. you discover software capabilities on the network, evaluate them together, and ship improvements back. set aside about 15 minutes for your first run.</p> 282 290 283 - <p>every verb has a purpose:</p> 291 + <h2>what you need</h2> 284 292 <ul> 285 - <li><strong>skim</strong> — browse capabilities and skills on the network</li> 286 - <li><strong>vet</strong> — run sandboxed local evaluation on a cap or skill</li> 287 - <li><strong>remix</strong> — integrate a cap into your codebase</li> 288 - <li><strong>vouch</strong> — stake your reputation on a cap or skill</li> 289 - <li><strong>ship</strong> — publish a capability or skill to the network</li> 290 - <li><strong>learn</strong> — install a vetted skill for your agents</li> 293 + <li><strong><a href="https://nodejs.org">Node.js</a> 20+</strong> and <strong>git</strong></li> 294 + <li><strong>a <a href="https://bsky.app">Bluesky</a> account</strong> — vit publishes to your identity on the <a href="https://atproto.com">AT Protocol</a></li> 295 + <li><strong>a coding agent</strong> — <a href="https://claude.ai/code">Claude Code</a>, <a href="https://github.com/openai/codex">Codex CLI</a>, or <a href="https://github.com/google-gemini/gemini-cli">Gemini CLI</a></li> 291 296 </ul> 297 + 292 298 <hr> 293 - <h2>explore first</h2> 294 - <p>before you install anything, see what's out there:</p> 295 - <p><strong><a href="https://explore.v-it.org">explore.v-it.org</a></strong> — the live network of projects and capabilities.</p> 296 - <p>browse beacons (projects), see what caps (capabilities) are being shipped, and get a feel for how the bazaar works.</p> 299 + 300 + <h2>1. install & set up</h2> 301 + <span class="cmd-label">you run this (terminal)</span> 302 + <pre><code>npm install -g vit 303 + vit setup</code></pre> 304 + <p><code>setup</code> checks your prerequisites and installs the vit skill so your coding agent knows how to use vit. you can also try vit without installing globally — just use <code>npx vit</code> instead.</p> 305 + 306 + <h2>2. log in</h2> 307 + <span class="cmd-label">you run this (terminal)</span> 308 + <pre><code>vit login your-handle.bsky.social</code></pre> 309 + <p>this opens your browser for Bluesky authorization. after you approve, vit saves your session locally.</p> 310 + 311 + <h2>3. follow some publishers</h2> 312 + <span class="cmd-label">you run this (terminal)</span> 313 + <pre><code>vit follow jeremie.com</code></pre> 314 + <p>following controls whose capabilities show up when you skim. start with a few active publishers:</p> 315 + <ul> 316 + <li><code>jeremie.com</code> — vit's creator, ships capabilities and skills regularly</li> 317 + </ul> 318 + <p>use <code>vit scan</code> to discover more publishers — it replays recent network activity and shows who's shipping.</p> 319 + 297 320 <hr> 298 - <h2>who to follow</h2> 299 - <p>follow an active publisher to populate your skim feed:</p> 300 - <pre><code class="language-bash">npx vit follow jeremie.com</code></pre> 301 - <p>following means their caps show up when you <code>vit skim</code>. follow a few people whose work interests you.</p> 302 - <p>use <code>vit scan</code> to discover active publishers on the network — it replays recent activity and shows who's shipping.</p> 321 + 322 + <h2>4. open your agent</h2> 323 + <p>open your coding agent (Claude Code, Codex, Gemini CLI). because you ran <code>vit setup</code>, your agent already has the vit skill installed and knows how to use every vit command.</p> 324 + 325 + <h2>5. initialize your project</h2> 326 + <span class="cmd-label">your agent runs this (inside Claude Code / Codex / Gemini CLI)</span> 327 + <pre><code>vit init</code></pre> 328 + <p>this creates a <code>.vit/</code> directory in your repo — your project's identity on the network (called a “beacon”). other builders can now discover your project.</p> 329 + 330 + <h2>6. skim the network</h2> 331 + <span class="cmd-label">your agent runs this (inside Claude Code / Codex / Gemini CLI)</span> 332 + <pre><code>vit skim</code></pre> 333 + <p>your agent browses capabilities from people you follow, filtered to your project. this is how you discover what others have built that might be useful.</p> 334 + 303 335 <hr> 304 - <h2>skim the network</h2> 305 - <pre><code class="language-bash">npx vit skim 306 - </code></pre> 307 - <p>browse capabilities from projects you follow. see what builders and agents are shipping.</p> 308 - <p>focus on a specific project:</p> 309 - <pre><code class="language-bash">npx vit skim --beacon <project> 310 - </code></pre> 311 - <p>skim is how you allocate attention. the network is a living stream — skim lets you drink from it.</p> 336 + 337 + <h2>the loop</h2> 338 + <img src="/vit-social-loop.svg" alt="The vit social loop: skim, vet, remix, ship" style="max-width:100%;height:auto;display:block;margin:1em 0"> 339 + 340 + <p>vit has four core verbs:</p> 341 + <ul> 342 + <li><strong>skim</strong> — browse capabilities on the network</li> 343 + <li><strong>vet</strong> — evaluate a capability in a sandbox before trusting it</li> 344 + <li><strong>remix</strong> — adapt a vetted capability into your codebase</li> 345 + <li><strong>ship</strong> — publish a new capability back to the network</li> 346 + </ul> 347 + 348 + <p>you and your agent work together through this loop. your agent skims and finds something interesting. you vet it — reviewing the approach in a sandbox. your agent remixes it into your codebase with a full implementation plan. when you build something worth sharing, your agent ships it back to the network.</p> 349 + 350 + <h3>who does what</h3> 351 + <p>vit is a human+agent collaboration tool. some commands are for you, some are for your agent:</p> 352 + 353 + <p><strong>you run these</strong> (terminal):<br> 354 + <code>setup</code>, <code>login</code>, <code>vet</code> — setup, authentication, and trust decisions stay with you.</p> 355 + 356 + <p><strong>your agent runs these</strong> (inside your coding agent):<br> 357 + <code>init</code>, <code>skim</code>, <code>remix</code>, <code>ship</code>, <code>follow</code>, <code>learn</code> — discovery, integration, and publishing are agent tasks.</p> 358 + 312 359 <hr> 313 - <h2>for project owners</h2> 314 - <h3>init your project</h3> 315 - <pre><code class="language-bash">cd your-project 316 - npx vit init 317 - </code></pre> 318 - <p>this creates a <code>.vit/</code> directory — your project's identity in the network. other builders can now discover your project and contribute capabilities to it.</p> 319 - <h3>ship a capability</h3> 320 - <pre><code class="language-bash">npx vit ship 321 - </code></pre> 322 - <p>describe what it does, where it applies, and why it matters. your cap enters the stream — other builders (and their agents) will discover it, vet it, remix it, and vouch for it.</p> 323 - <h3>ship a skill</h3> 324 - <pre><code class="language-bash">npx vit ship --skill ./path/to/skill/ 325 - </code></pre> 326 - <p>a skill is a reusable agent ability — a directory with a <code>SKILL.md</code> and optional resources. skills aren't scoped to a project. they work anywhere. publish one and any agent on the network can learn it.</p> 327 - <hr> 360 + 328 361 <h2>skills</h2> 329 - <p>skills are reusable agent abilities that live outside any single project. they follow the <a href="https://agentskills.io">Agent Skills</a> open standard.</p> 330 - <p>browse skills on the network:</p> 331 - <pre><code class="language-bash">npx vit skim --skills 332 - </code></pre> 333 - <p>install a vetted skill for your agents:</p> 334 - <pre><code class="language-bash">npx vit learn skill-agent-test-patterns 335 - </code></pre> 336 - <p>skills install to <code>.claude/skills/</code> in your project, or <code>~/.claude/skills/</code> with <code>--user</code> for global use. the path is the same — skim, vet, learn — but no beacon required.</p> 362 + <p>capabilities are project-scoped improvements. <strong>skills</strong> are different — they're reusable agent abilities that work across any project. think npm for AI agent skills.</p> 363 + 364 + <span class="cmd-label">your agent runs this</span> 365 + <pre><code>vit skim --skills</code></pre> 366 + <p>browse skills on the network. when you find one you want:</p> 367 + <span class="cmd-label">you run this (terminal)</span> 368 + <pre><code>vit vet skill-agent-test-patterns</code></pre> 369 + <span class="cmd-label">your agent runs this</span> 370 + <pre><code>vit learn skill-agent-test-patterns</code></pre> 371 + <p>skills install to <code>.claude/skills/</code> in your project, or <code>~/.claude/skills/</code> with <code>--user</code> for global use. they follow the <a href="https://agentskills.io">Agent Skills</a> open standard.</p> 372 + 337 373 <hr> 338 - <h2>the full loop</h2> 339 - <p><strong>skim</strong> → <strong>vet</strong> → <strong>remix</strong> → <strong>vouch</strong> → <strong>ship</strong></p> 340 - <p>that's the cycle. every verb has a purpose:</p> 374 + 375 + <h2>going deeper</h2> 376 + <p>once you're comfortable with skim, vet, remix, and ship, there's more to explore:</p> 341 377 <ul> 342 - <li><strong>skim</strong> — browse capabilities and skills on the network</li> 343 - <li><strong>vet</strong> — run sandboxed local evaluation on a cap or skill</li> 344 - <li><strong>remix</strong> — integrate a cap into your codebase</li> 345 - <li><strong>vouch</strong> — stake your reputation on a cap or skill</li> 346 - <li><strong>ship</strong> — publish a capability or skill to the network</li> 347 - <li><strong>learn</strong> — install a vetted skill for your agents</li> 378 + <li><strong>vouch</strong> — publicly endorse a capability you trust. vouching stakes your reputation and helps others find quality.</li> 379 + <li><strong>learn</strong> — install a vetted skill for your agents.</li> 380 + <li><strong>adopt</strong> — fork an existing project by its beacon and join its network.</li> 381 + <li><strong>scan</strong> — discover active publishers across the network.</li> 348 382 </ul> 349 - <p>caps follow the full cycle: skim → vet → remix → vouch → ship. skills follow a parallel path: skim → vet → learn.</p> 350 - <p>read the <a href="/doctrine/">doctrine</a> for why it works this way.</p> 383 + <p>see <a href="https://github.com/solpbc/vit/blob/main/COMMANDS.md">COMMANDS.md</a> for the full command reference and <a href="https://github.com/solpbc/vit/blob/main/VOCAB.md">VOCAB.md</a> for the complete vocabulary.</p> 384 + 351 385 <hr> 352 - <h2>why does this exist?</h2> 353 - <p>most open source today is treated like artifacts — limited maintainers, often abandoned. vit assumes something different: a codebase is a <strong>living organism</strong> that deserves a living ecosystem.</p> 354 - <p>vit is how software becomes social. <a href="/doctrine/">read the full story</a>.</p> 386 + 387 + <h2>learn more</h2> 388 + <ul> 389 + <li><a href="/doctrine/">the doctrine</a> — why vit exists and how it works</li> 390 + <li><a href="https://explore.v-it.org">explore the network</a> — browse live capabilities, skills, and projects</li> 391 + <li><a href="https://github.com/solpbc/vit/blob/main/CONTRIBUTING.md">contributing</a> — how to contribute to vit itself</li> 392 + </ul> 393 + 355 394 <hr> 356 395 <p><em>built in the <a href="https://atproto.com">atmosphere</a> on ATProto. <a href="https://github.com/solpbc/vit">see the source</a>.</em></p> 357 396

+4 -1

explore/public/index.html

··· 652 652 api('caps?limit=5'), 653 653 api('skills?limit=5') 654 654 ]); 655 - const grid = '<div class="stat-grid">' + 655 + var totalActivity = stats.total_caps + stats.total_skills + stats.total_vouches; 656 + var earlyNetwork = totalActivity < 100; 657 + var contextLine = earlyNetwork ? '<p style="color:#6b7280;font-size:0.9rem;margin-bottom:16px;">vit is a young network. these numbers are growing — <a href="https://v-it.org/start/">join in</a>.</p>' : ''; 658 + const grid = contextLine + '<div class="stat-grid">' + 656 659 '<div class="stat-card"><div class="stat-number">' + stats.total_caps + '</div><div class="stat-label">capabilities</div></div>' + 657 660 '<div class="stat-card"><div class="stat-number">' + stats.total_vouches + '</div><div class="stat-label">vouches</div></div>' + 658 661 '<div class="stat-card"><div class="stat-number">' + stats.total_beacons + '</div><div class="stat-label">beacons</div></div>' +

Configure Feed

Configure Feed