`req r1`

**Decision.** The index layer is **strictly additive**. Every existing vibevm code path keeps working exactly as today when no index is present. No registry is required to have an index. No project is required to consume one; a consumer that finds none falls back to the live `git ls-remote` path that exists today.

**Discovery is a ladder, and the eternal handshake is its first rung.** A consumer probes two candidate bases in order — `<index-url>/v1/index`, then `<index-url>` — and at each one asks `hello.json` **before** any `repomd.json`. A 200 whose body parses as a handshake and carries a world of the epoch this build reads settles the probe: that world's `path` refines the base every later file is fetched from. Only «no handshake here» (404, 5xx, connect failure) moves on to the next candidate and, when neither answers, to the `repomd.json` probe at the same two bases — the compatibility surface for indexes published before the handshake existed. Nothing at all → the live path, silently, exactly as before.

**Asked first, not asked beside** — because `successor` is the in-band forwarding pointer for an index that MOVED, and it is readable exactly when the old address no longer serves a catalog. A handshake sought only next to a `repomd.json` that answered would be read in every case except the one it exists for. The price is up to two extra GETs, and it is paid only by indexes that have no handshake.

**A probe answers `found`, `absent`, or `refused`, and the third is what keeps this section honest.** «Absent» is the only outcome that falls through quietly, because it is the one that means what the fall-through assumes: nothing is published here. An index that IS there and cannot serve this consumer — it refused us (401/403), its body does not parse as a handshake, its handshake format is one this build does not read, or it publishes no world of this build's epoch — answers **`refused`**, carrying the offered epochs, this build's epoch, a recipe, and whatever the document said in `min_client` / `notice` / `successor`. Collapsing that into «absent» would make a private, broken or newer-than-us index indistinguishable from a missing one, which is the silence [PROP-044 §2](../../common/PROP-044-change-native-formats.xml#laws) forbids: a break that announces itself is normal life, a riddle is what strands users.

**A `successor` is named to the operator, never followed by the client.** Automatic following needs a cycle watchman and a trust rule for the address it lands on, and neither is decided; naming the address costs the human one command and invents no policy.

**Rationale.**

`req r2`

**Decision.** Each vibevm registry org that opts in maintains a dedicated git repository named `index` (configurable; default name `index`) under the same org root:

Inside this repository sits a fixed file layout (§2.4) holding the org's catalog. The repository is:

**Why a dedicated repo, not files-in-package-repos.**

**Why not a hosted central HTTP service** (npm-style `registry.npmjs.org`):

**Configurable but defaulted.** A `[[registry]]` block pins a custom index location — the key exists in `RegistrySection` (one type serving both the project `vibe.toml` and the machine-global `~/.vibe/registry.toml`, so the columns share one vocabulary), and this exact block parses (pinned by test `prop005_index_url_example_parses`, which carries it verbatim):

The bottom rung is host-aware. Canonical public `https://github.com/<org>` maps to `https://raw.githubusercontent.com/<org>/index/<registry-ref>`; other hosts retain `<registry-url>/index`. This makes both fresh and already- seeded GitHub configurations whose `index_url` field is absent consume the static repository rather than its HTML page. The full ladder remains env override → manifest key → host-aware default; exact `none` on either explicit rung disables lookup. Lookalike hosts, nested paths, userinfo, unsafe owners/refs, queries and fragments are never rewritten.

**For three months this block was a parse refusal, and saying so was the point — until 2026-08-20, when the key landed (B-083, owner-ruled «построить ключ»).** `RegistrySection` carried `deny_unknown_fields` without `index_url`, so a reader copying the example got an error; the fact above honestly said `plan` while the tree disagreed with the document. The strictness itself was never the defect and stays: the section still refuses unknown fields, now with `index_url` among the known ones — pinned red-then-green by the landing (the pre-landing parse error is quoted in the worker report; `registry_section_still_refuses_unknown_fields_alongside_index_url` keeps the refusal honest).

**The environment variable `VIBEVM_INDEX_URL_<REGISTRY>` is the ladder's top rung — the operator's per-run re-point, no longer the only source.** Until 2026-08-20 it was the sole locator, deliberately weaker than the manifest field it stood in for (per-shell, per-run, travelling with neither project nor lockfile) — which is why it never closed the requirement above. Now it *overrides* the key: env beats `index_url` beats the default, and `none` at either explicit rung disables the index. The name normalization (`ASCII alphanumerics upper-cased, the rest to `_``) is unchanged.

404 / connect-failure on the index → **silent** fallback to live `ls-remote`: no error message, because the operator never promised an index. This half is built, and it is the `absent` outcome of [`##A-PROBE-HAS-THREE-OUTCOMES-NOT-TWO`](#optional) — the other two outcomes are never silent.

`req r1`

**Decision.** Package repositories are the **source of truth** for content (manifests, files, tags). The index is a **derived hot cache**, regeneratable from the authoritative package state.

**Server-mode wrinkle.** The `vibe-index serve` mode (§2.5) is described in the prompt as "the only writer; source of truth". This is true *for the index data*. The server holds the canonical RAM copy, persists it to disk on every mutation, and refuses writes from other processes (file lock + mtime checks at startup). But the server's writes are **derived from package-repo state** — the ground truth for "is this version published?" is still the actual git tag in the actual package repo. A divergence (index says `v0.1.0` exists; the package repo's tag was force-deleted) surfaces at consumer install time as an integrity failure on cross-source `content_hash` verification, and the operator has the diagnostic clear: "your index lies; reindex".

`req r2`

**Decision.** The index repo's working tree (and equivalently its raw-HTTP-served file tree) carries:

**`hello.json`** — the eternal handshake ([PROP-044 §3](../../common/PROP-044-change-native-formats.xml#truth)): `{vibe, worlds[], min_client?, notice?, successor?}`, the one document whose keys never change meaning, through which a client of any age learns which worlds this index currently serves, where each lives, and where the handshake itself moved. Its shape is `schemas/hello/e1/hello.jtd.json` and its type is generated like every other wire type ([§2.12](#types)); the index writes it, and [§2.1](#optional) is where a consumer reads it.

**The handshake is deliberately absent from `repomd.json::files`, and the asymmetry is the design.** `repomd.json` is the manifest of **one** world; the handshake stands **above** worlds and dispatches to them, so a world's manifest can no more vouch for it than a chapter can vouch for the table of contents. The consequence to hold: the handshake is the one served file the manifest's `sha256` map does not cover, and what verifies it instead is that it **parses** — an HTTP 200 whose body is not a handshake is a loud refusal naming the broken index, never a quiet fall-through to `repomd.json` ([§2.1](#optional)).

**What the writer owns is a stated whitelist, not whatever the directory happens to hold** — four root files (`hello.json`, `repomd.json`, `primary.jsonl`, `primary.jsonl.gz`) and three trees (`by-name/`, `by-cap/`, `by-purl/`), named once in the code so the two readers that ask "is this catalog still the projection of its journal?" — `vibe-index rebuild <data-dir> --check` (with `cargo xtask rebuild --check <data-dir>` as a thin compatibility wrapper) and the golden-corpus test — cannot compare different sets. The rest of the directory is not the writer's and is not compared: `README.md` and `.gitignore` are written once by `init`, and the whole of `state/` ([§2.13](#persistence)) is the server's own bookkeeping. A blacklist would have to enumerate the world and would rot the day the directory grew a file nobody listed.

**`repomd.json`** — the manifest, modelled after RPM's `repomd.xml`:

**`primary.jsonl`** — newline-delimited JSON, one record per `(group, name, version)`. Lines are sorted by `(group, name, version)` — the PROP-008 §2.2 identity ordering. Each line is one §2.6 entry. JSONL is chosen over JSON-array because:

**`primary.jsonl.gz`** — gzip-compressed equivalent for HTTP-bandwidth-conscious consumers. ~5× compression typical for JSON. Byte-identical content; gzip is deterministic at level 6 with the standard zlib dictionary so the file is reproducible across machines (we pin level and disable `mtime` in the gzip header to keep the SHA-256 stable). Both `primary.jsonl` and `primary.jsonl.gz` ship; consumer chooses based on `Accept-Encoding`.

**`by-name/<name>.json`** — the candidate-set file for one bare package name (PROP-008 §2.8). A single HTTP GET fetches every `(group, name)` package that shares the short name `<name>`, each with all its versions — ~1–10 KB. This is the path short-name resolution (PROP-008 §2.6) walks: one GET per registry yields the whole candidate set, so a collision (PROP-008 §2.7) is detected at once. The directory level keyed on `kind` before PROP-008; `kind` left package identity, so `<name>` alone is the key.

`tombstone` — `{reason, superseded_by?}`, carried by the candidate-set file **only when the bare name is buried**, and omitted from the wire otherwise (which is why the live example above does not show it). A name that ever existed answers with the current thing, a forwarding pointer, or a tombstone carrying a reason — never with silence ([PROP-044 §2](../../common/PROP-044-change-native-formats.xml#laws)). The consequence that is easy to miss: the file is written **even when the name has no packages left**, because an absent file *is* the silence the law forbids. A buried name therefore looks like this:

**`by-cap/<capability-slug>.jsonl`** — for `vibe install --capability ui:landing-page` style queries (PROP-003 capability-driven resolution). Each line: `{"kind":"feat","name":"welcome-page","version":"0.3.0","capability":"ui:landing-page@0.3.0"}`. `<capability-slug>` is the capability string with `:` and `/` and `@` replaced by `--` (filesystem-safe; reversible). Optional in v0; populated when present.

**`by-purl/<purl-slug>.jsonl`** — for "what vibevm packages document this upstream library?" queries (PROP-003 §2.5.6 `describes`). Same shape as `by-cap`; `<purl-slug>` is the PURL with `/` replaced by `--`.

**Sort invariants.** Every file with multiple entries is sorted deterministically:

Determinism matters because the index repo lives in git: a non-deterministic order would produce churn diffs on every regenerate, defeating the value of git as the transport.

`req r1`

**Decision.** A single binary, `vibe-index`, ships in two modes selected by subcommand:

**Why one binary, not two.** Same code paths (the in-memory `Index` struct, the persistence layer, the scanner) are shared. Two binaries would force consumers to install both. clap-style subcommand dispatch handles the mode selection.

**Distribution.** The utility lives at `crates/vibe-index/` as a **member of the top-level vibevm workspace** — built, tested and gated by the same `cargo … --workspace` invocations as every other crate. [§6](#distribution) records why the original standalone-workspace decision was reversed and what the reversal bought.

`req r1`

**Decision.** Every `(group, name, version)` entry carries the following fields. This is the shape lines of `primary.jsonl` follow, and the elements each `by-name/<name>.json` candidate's `versions[]` carry. **The authority for that shape is `schemas/index/e1/entry.jtd.json`; this section is its reading aid.** The JTD file is the source of truth, the Rust is generated from it into `crates/vibe-wire/src/generated/` and re-exported through `crates/vibe-index/src/types/entry/`, and `cargo xtask check-codegen` refuses any drift between the two. The record is defined once, in the shared `version_entry` vocabulary, because the candidate-set file and the journal carry it transitively and the schema language has no cross-file reference — `entry.jtd.json` is the root that names it. So the index entry stands in exactly the same arrangement as the wire reports under the root `schemas/`, not a different one. Where this section and the schema disagree, **the schema wins and this section is the defect**. What this section carries that the schema cannot is the *provenance* below — where each field comes from — and that is a copy of nothing.

The three slots — `must_understand`, `yanked`, `frozen` — appear above in their *significant* form, but all three are **omitted from the wire when empty** (an empty list; `false`). A live record for an un-yanked snapshot package therefore carries none of them, and the same holds for `tombstone` on the candidate-set file ([§2.4](#layout)). Reading this example as "these keys are always present" is the one mistake it invites.

**Field provenance.**

**Forward compatibility.** `schema_version: 1` is recorded at file scope (in `repomd.json`) and at entry scope. Entries carrying fields a reader does not know coexist with it: unknown fields are tolerated, and known-but-absent ones default. **This sentence was false for as long as it stood.** Fifteen catalog aggregates carried `deny_unknown_fields`, so a reader meeting one unknown key refused the whole file — the opposite of what the fact promised — and the contradiction survived because nobody could remove the attribute safely. That was not caution: while every mutation read the catalog to rewrite it, tolerance would have SILENTLY DELETED the tolerated fields on the next write, which is worse than refusing. Phase 3 removed the condition rather than the symptom — a mutation is now an append to the journal plus a reprojection, so nothing read is ever written back, there is nothing to lose, and the strictness could finally go ([PROP-044 §4.4](../../common/PROP-044-change-native-formats.xml#machinery)). What tolerance still does NOT mean is acting on a record one does not understand; that refusal moved to the per-record capability set (`##NEVER-SILENT-SCHEMA`).

`req r1`

**Decision.** The **digest** of `content_hash` is the join key between the index and the lockfile, and it joins only **at a stated recipe** ([PROP-002 §2.1](../vibe-registry/PROP-002-decentralized-registry.xml#identity)). A consumer that fetches `flow:wal@0.1.0` via the index records the digest a no-index fetch would have produced — for every tree except the ones recipe 1 exists to disambiguate, where the two recipes deliberately disagree and that disagreement is the point. **Index entries are advisory; the bytes are authoritative.**

The index and the lockfile currently stand at **different** recipes: the index emits `sha256-tree/1:`, the lockfile keeps the bare `sha256:` until its own format moves. So their strings are deliberately unequal, and nothing compares them as strings — the index client does not read the field at all. Written down because the asymmetry looks like a defect to a cold reader and is instead the thing that keeps a live lockfile from being rewritten by a change it did not ask for.

The `repomd.json::files[*].sha256` covers integrity of the index files themselves. The per-entry `content_hash` covers integrity of the package content, and carries its recipe so a check compares like with like. The two are independent: a tampered index file fails its file-hash check; a tampered package repo (force-pushed tag) fails its content-hash check at fetch time.

**Out of scope for v0:** GPG-signed `repomd.json.asc`, Merkle-log audit trail (Go sumdb-style). [§9](#open) tracks both.

`req r1`

**Decision.** Two regeneration modes. Both are available via the CLI (`vibe-index reindex`); the HTTP trigger was withdrawn by owner ruling 2026-08-20 (`##TRIGGER-HTTP`):

**Full reindex.** Walk every package repo in the org; for each repo, list tags; for each `v<semver>` tag, read `vibe.toml` and `subskills/**/vibe-subskill.toml` at that ref; compute `content_hash`; assemble §2.6 entry. Replace the in-memory index wholesale, then atomic-write the on-disk files.

Sources for the walk:

**Incremental reindex.** Detect what changed since the last run and update only the affected entries.

Incremental is the default cadence target (one run per minute on an active org); full is the bootstrap path and the "trust nothing" recovery option.

`req r1`

**Decision.** The HTTP server is the **only writer** when running. It locks the data directory via a PID file (`<data-dir>/state/server.lock`) at startup; refuses to start if the lock is held by another live process; refuses CLI mutations against the same data directory by detecting the lock from CLI side (CLI-mode `add` / `remove` / `reindex` errors with "server is running on this data dir; use the HTTP API").

In-memory state model:

On every successful write, the server:

**The writer never calls `now()`.** Every timestamp a write stamps — the manifest's `generated_at` and each candidate-set file's `indexed_at` — arrives as an argument: the CLI passes the moment its command began, the server passes the moment of the mutation event, and the index and entry modules contain no clock call at all (a panel step refuses one). One state therefore produces one byte sequence, which is what makes "rebuild and compare" a real verification, an empty diff a real no-op, and a wire-diff a quantitative measure of a break rather than a wall of timestamp churn ([PROP-044 §4.3](../../common/PROP-044-change-native-formats.xml#machinery)). Determinism here is an instrument, not tidiness: without it every later recoverability check measures the clock instead of the content.

**The writer stamps its own schema version only into an artifact it creates from scratch.** A catalog it *read* keeps the version that catalog carried: the value is state, not a constant of whichever binary happens to be running. Otherwise a catalog written by a later version and opened by an older binary for any mutation would silently shed its own marker and start claiming ours — a file that still looks consistent while asserting something untrue about itself, which is the failure re-fetching cannot cure ([PROP-044 §2, law 1](../../common/PROP-044-change-native-formats.xml#laws)). What the writer does when the version it read is one it cannot serve is a separate question and not answered here; this fact only forbids the silent overwrite.

**The clause the journal adds: a projection has no version to keep.** Once a mutation is an append to the journal followed by a reprojection, the writer no longer reads a catalog at all — it builds one from the facts. There is therefore nothing to preserve, and stamping this build's constant asserts something true about the artifact just written, rather than overwriting a claim some other writer made. The rule above is unchanged and still binds every path that *does* read a catalog before rewriting it; what changed is how many such paths exist. The protection it was reaching for did not disappear with them — it moved up a floor, to the journal's own epoch and to each record's `must_understand` set, where a build meeting facts from a newer world refuses them by name instead of quietly reading a subset and re-labelling the result ([PROP-044 §4.5](../../common/PROP-044-change-native-formats.xml#machinery)). Read the two together and the invariant is one thing said twice: a file never claims an authorship it does not have.

**Concurrency.** axum + tokio. Reads do not block reads. Writes block reads (RwLock) for the duration of the in-memory mutation; disk I/O happens after lock release for any path it can (e.g. `primary.jsonl` rewrites are queued and serialised by a single dedicated writer task). For the request rates we target (max ~10 writes/min during a publish burst, ~1000 reads/min during a CI install storm), a coarse RwLock is sufficient.

**Process model.** Single process. No replication. An operator who needs HA runs the server behind a load balancer with N replicas and a shared filesystem — but that's outside v0. v0 expects one process per data directory.

`req r1`

**Decision.** REST API, JSON over HTTP. CORS open on read endpoints (so a future web UI can hit it from a browser). Routes:

**The admin surface the server builds is one route — `GET /v1/admin/status` — and since 2026-08-20 that is the *specified* surface, not a gap.** The reindex trigger spent months as «specified and unbuilt»: the router registers **16 paths** and none of them was it, the handler module holds `status` alone, and the code's own note («reindex POST lands in slice 6») described a slice that closed without it. The fork `BACKLOG.md` B-085 recorded — build it, or retire it in favour of the CLI verb — was resolved by owner ruling 2026-08-20: **retired**. `##TRIGGER-HTTP` carries the reasoning, [§11](#wire-up)'s hook recipe now invokes the CLI verb, and the route returns, if ever, at the first real operator's need.

**Authentication.** Bearer tokens via `Authorization: Bearer <token>`. Tokens are read from `<data-dir>/state/admin.tokens` (one token per line; comment lines start with `#`). Read endpoints accept missing/invalid tokens silently. Write endpoints require a valid token; mismatch → 401 with a generic message ("authentication required"; do not echo the supplied token nor say which valid prefix it matched). Tokens never appear in logs (logging redacts the `Authorization` header).

**Per-host lockdown.** By default the server binds to `127.0.0.1:8412` — local-only. Operators expose externally by setting `--bind 0.0.0.0:8412` and putting it behind a reverse proxy with TLS. v0 does not ship TLS termination; this is the reverse proxy's job. (Same posture as `cargo`'s sparse index protocol: the upstream is HTTP — TLS is for the CDN / proxy in front.)

**Errors.** Application/json error shape, taken from RFC 7807 Problem Details (lightweight subset) — four members always, and one extension member when the error is a quarantine refusal ([§2.19](#unavailable)):

**`instance` is not emitted, and the subset is the four members above plus `unavailable`.** RFC 7807 makes every member optional, so omitting `instance` is conformance rather than a gap — but naming a member the body does not carry teaches a client to look for it. What the body does carry beyond the four is the refusal row, as an extension member, which is the mechanism that RFC provides for precisely this and the reason the status can stay `404` while the answer stops being «not found».

`req r2`

**Decision.** `vibe-index [--log-level LEVEL] <subcommand> <data-dir> [args]`. The data directory is a **required positional** on every verb — the one argument no invocation can omit, so it is not dressed as an option. One global flag stands above the verbs: `--log-level off|error|warn|info|debug|trace`.

**Decision (owner, 2026-08-19).** Taking a package out of circulation is **three distinct operations over two different entities**, and the surface must offer all three rather than making one stand in for the others:

**What every withdrawal verb refuses, and why the two refusals must not share a message.** Each of the three verbs answers its question against the **projection of the journal**, never against the catalog on disk, and refuses **before** appending anything — so a refused command leaves the journal exactly as it found it. Two refusals apply to all three, and they come from different laws:

**Why that condition is a conjunction and not a convenience, stated because the tempting relaxation defeats another verb.** An operator who `remove`s every version of a name leaves it carrying nothing — and full deletion's whole guarantee is that the result is **indistinguishable from a package that never existed** ([PROP-010 §2.6](../vibe-registry/PROP-010-local-package-cache.xml#resolution)). Letting `bury` then plant a tombstone on that empty name would put the deleted package's name back on the wire, in a file written precisely so it can be read — quietly undoing the operation the operator chose. So «nothing to bury» is the correct answer for an emptied name, and a future reader who finds the refusal unhelpful is looking at the mechanism that makes deletion mean what it says.

**The two conditions overlap unless the verb is written to keep them apart, and `bury` is where that bites.** A buried name has no packages in any group, so «nothing stands here» is *also* true of it — a verb that tested the plainer condition first would answer «no such name» about a name whose tombstone it is holding. **The requirement is that the two partition; how is the implementation's business.** Two ways are equivalent and both are correct: test «already in that state» first, or spell the plainer condition as the conjunction it really is («no packages anywhere AND no tombstone»). What is NOT correct is the naive reading, in which the more specific case never reaches its own message.

**`--json` is a property of nine verbs, not of the binary.** Every verb that ANSWERS a question carries it — `get`, `list`, `search`, `capabilities`, `purls`, `outdated`, `verify`, `reindex`, `rescan-org`; the six that perform an action and report only success (`init`, `add`, `remove`, `dump`, `serve`, `stop`) do not. `dump` is the instructive exception: it is machine output already, so a `--json` switch on it would be a second spelling of `--format json`. Saying «all subcommands» would send a script author looking for a flag six verbs do not have.

`--log-level` is global (it may be written before or after the subcommand) and it folds into the one lever `VIBE_LOG`, which the subscriber reads exactly once at start-up: passing the flag SETS that variable, so the process environment always explains the output an operator is looking at. The flag speaks a closed set of six values while the variable keeps the full directive language — one thing with a coarse dial and a fine one, never two spellings of the same power.

**The tracing subscriber is installed on every invocation, at `warn` by default, and that is a decision rather than a default nobody chose.** It is the binary's job and not the library's; there is no `RUST_LOG` fallback and no second lever. The reason is the refusal path: a version this build cannot act on is reported at WARN when a catalog loads ([§2.19](#unavailable)), and a publication failure is reported at WARN when the server pushes ([§2.17](#auto-publish)). Both are things an operator must be able to see on **any** subcommand — so a subscriber installed only under some flag would make observability an accidental property of which verb happened to be running, which is how a message that exists is never read. The ordering that makes the flag honest is part of the same decision: the fold writes `VIBE_LOG` at the very top of `main`, after the parse and before the subscriber, so `--help` and parse errors still answer before any log and the variable is never left describing output it no longer governs.

**Help-text smoke** lives under `crates/vibe-index/tests/help_smoke.rs`, mirroring `every_subcommand_renders_help` in `vibe-cli`.

`req r1`

**Decision.** The catalog's wire types are **generated from the schemas of [§2.6](#entry) and re-exported**, never written by hand: the definitions live in `vibe_wire::generated` beside the JTD they come from, `crates/vibe-index/src/types/` re-exports them so every `vibe_index::types::*` path keeps its meaning, and `cargo xtask check-codegen` is the gate that refuses a drift between schema and type. `VersionEntry` comes from the shared `version_entry` vocabulary; `NameEntry` / `PackageEntry` / `Tombstone` from `schemas/index/e1/by_name.jtd.json`; `BindingSite` from `by_purl`.

Two shapes stay hand-written, and each says why. `Repomd` / `RepomdFileEntry` — its `size` is a `u64` where the schema language reaches only `u32` (an open owner fork, `BACKLOG.md` B-091 — filed as B-056 and renumbered 2026-08-19, because that coordinate carried a closed row too and a reader following it landed there), and its `files` union is tagged by this document's own law ([§2.4](#layout)). And `Index` below, which is not a wire type at all: it is the server's in-RAM state, no single document ever carries it, and it holds two members the catalog deliberately never serialises — the reader's quarantine record and the per-name tombstones the writer projects back onto the candidate-set files:

**The generated types carry a fixed trait floor — `Debug`, `Clone`, `PartialEq`, `Eq` beside the serde pair — and `Default` is deliberately not in it.** The dividing question is whether the trait says anything about the FORMAT: the four are properties of the Rust representation and the wire knows nothing of them, so emitting them unconditionally is the same class of decision as canonical ordering. `Default` is different in kind — «does this type have a meaningful empty value» is a judgement about the type, not a fact about its form. An empty `ProvidesEntry` means «provides nothing»; an empty `VersionEntry` means nothing at all, since twenty-odd of its fields are required. So `Default` lives in hand-written impls beside the generated tree, on the sub-structures where it is meaningful, and **`VersionEntry` has none**.

**The consequence, which nothing in the tree guards:** because the record derives no `Default`, every literal that builds one names all its fields, and there is no `..Default::default()` tail anywhere to shorten them. That is not an inconvenience to be optimised away — it is what makes adding a field a decision at every construction site instead of a silent zero. A future session that "simplifies" by deriving `Default` on the record would change how records are built from fixtures without any test going red, which is why the boundary is written here rather than left to be re-derived.

**What moving to generated types cost, measured rather than estimated, so the price is not re-paid in reverse.** Three traits left with the hand-written shapes and the tree was checked for each: `Ord` / `Hash` / `PartialOrd` — wanted by **nobody**, and a comment claiming one of them justified duplicating a vocabulary had been false since it was written; `Copy` on the kind vocabulary — really lost, and the call sites that had it became explicit clones; `Default` — restored by hand where it means something. The classification is what matters, not the counts, which is why the counts live in the dated measurement (`campaigns/packages-2026-09/harvest/f42c-reexport-radius.md`) and not in this sentence. Anyone proposing to restore a duplicate type for the sake of `Copy` is proposing to unpay this, and should read what it bought first.

**A vocabulary fragment that changes in a new epoch is a DIFFERENT fragment, and it is separated by its NAME, not by a directory.** The shared home holds fragments once, by name, and every schema module that pulls one re-exports it; when a second epoch needs a changed shape, the changed shape gets its own name and sits beside the old one in the same home. Worlds stay separated because two names never denote one type — the same rule that makes the shared home possible at all. Putting epochs into the home's directory structure instead would fork the home and give one fragment two addresses, which is the collision the single-home phase exists to prevent. *Revisit when:* the first second-epoch schema pulls a first-epoch fragment — that is the day this rule is exercised for real, and until then it has never been tested.

`PkgKey = (Group, String)` — the `(group, name)` identity of PROP-008 §2.2, and the order `by_pkgref` walks in. `kind` is metadata and identifies nothing, so it is not part of the key.

**Search keeps no stored index.** The postings are built per query against the loaded `Index` (`index/search.rs`) rather than held as a field, so no mutation has anything to invalidate. Token = lowercased ASCII alphanumeric run; ~30-stopword filter (the same list `vibe-check::activation_conflict` uses, deliberately reused for consistency). Ranking is term-overlap — one point per query token a hit carries — with the `(group, name)` identity breaking ties. Good enough for ≤10k packages; tantivy is a v1 upgrade if it isn't. Search answers only over what this build can act on: it asks the `quarantine::usable_*` accessors, never `pkg.versions` raw ([§2.6](#entry)).

`req r1`

**Decision.** `<data-dir>/` layout:

**The one thing to notice in that tree: `state/` is not mirrored, and the journal lives there.** Everything above `state/` is a projection and may be deleted and rebuilt; `state/journal/` is the layer it is rebuilt FROM ([§2.3](#truth)), and the server refuses to start without it. So the directory's gitignore boundary and its truth boundary run in opposite directions — the served half is disposable, the unserved half is not — and an operator who backs up «the index» by copying what the mirror carries has backed up the derivative and left the original.

**`/metrics` counts from memory, not from a file.** The counters are atomics in the server's own state and reset with the process, which is what an operational counter means; no `state/stats.json` exists, and a reader looking for one would find a durable-looking name for a volatile fact.

The data-dir doubles as a git working tree of the org's `index` repo. `state/` is `.gitignore`d (the `init` subcommand writes a default `.gitignore`). Operators commit + push the rest manually, or via `--auto-commit-push` — built 2026-08-06, contract in [§2.17](#auto-publish).

**Atomic write protocol.** For each file F to be replaced:

**Step 4 went unperformed until 2026-08-20; it is now `atomic_write`'s closing act.** The anchor keeps the finding's name: for one campaign every `sync_all` in the crate was on a FILE and no code path opened a directory to flush it — the gap was filed as `BACKLOG.md` B-087 rather than quietly dropped from the protocol, because a durability step deleted for being unimplemented is how a guarantee becomes folklore. What step 4 buys is the durability of the *rename* across a power loss on POSIX: without it the new bytes are safe and the directory entry pointing at them may not be. The B-087 landing closed it the conservative way — the code caught up to the protocol as ratified: `fsync_parent_dir` in `index/persistence.rs` runs after the rename (POSIX real, errors surfaced, never swallowed; Windows a no-op with the reason recorded in code, exactly as this step's own parenthesis allows), and every production projection writer reaches it through the one `atomic_write`. The journal shard stays outside by measured verdict, not omission: it is an append-in-place NDJSON write with no tmp→rename, so this protocol does not describe it; the lockfile and auth `sync_all` sites are test fixtures on read-only production paths.

`repomd.json` is replaced **last among the files it vouches for**, so a reader that fetches `repomd.json` first then chases hashes always sees consistent files. The handshake is written after it and is the one root file that does not weaken the rule, because the manifest never claimed it ([§2.4](#layout)) — the precedent being `README.md` and `.gitignore`, which `init` writes and the map does not carry either.

`req r1`

**Consumer side (`vibe-cli`, `vibe-registry`).**

**Publisher side (`vibe-publish`).**

**`vibe outdated` (M1.10 follow-up).**

**`vibe search` (M2.10 — this is what unblocks it).**

Each integration point is a separate slice. v0 of `vibe-index` ships without any of them — the index can be populated and consumed via raw HTTP / git clone before vibevm consumers know about it. Integration slices land in M2.10 / M1.10 follow-ups.

`req r1`

**The problem, and it is not performance.** To learn what changed, the index enumerates the organisation. That is a cost, but the cost is the small half. The large half is that **the picture goes stale without anyone doing anything wrong**: a developer publishing a package creates a repository and pushes a tag straight to the git host, never passing through the index service. So the index's image is behind from the moment it is taken, and a stale index is worse than a slow one — the package exists and cannot be found.

**This is what makes the organisation cache honest.** [§2.8](#reindex)'s cache and its cheap freshness check reduce how often the index asks; they do not change who knows first. A webhook does: the image becomes authoritative **because it is fed**, rather than because we assumed nobody else writes. Both mechanisms ship — the freshness check is what keeps the cache truthful when no webhook is configured, and every deployment starts that way.

**The endpoint is per host flavour, deliberately.** `POST /v1/hooks/{source}` where `{source}` names the git host's flavour (`github` today; other flavours are added when one is measured, not reserved in advance). One route per flavour rather than one generic route, because the payload shape and the signature scheme are host-specific and a single endpoint would have to sniff which it received — which is guessing, dressed as convenience.

**A webhook authenticates with its own shared secret, never with an admin token.** The sender signs the request body under a per-hook secret and the index verifies that signature; an unverifiable request is refused and not processed. Two reasons, and the second is the important one. *(i)* The secret is held by a third party — the git host — and must be rotatable without touching the tokens that authorise real writes. *(ii)* **Least authority:** an admin token authorises arbitrary writes, while a webhook may only cause the index to re-read one repository. Handing a notification channel the authority to write anything is how a notification becomes an attack surface. Secret storage follows [§7](#secrets) — file, never a flag, never a log.

**The load-bearing rule: a payload says *that* something changed, never *what* it now is.** The index reads the manifest from the git host itself and applies the per-package `add` / `remove` of [§2.8](#reindex) for the named repository only. Nothing from the request body is ever written into an index record. This follows from [§2.3](#truth) — package repos remain authoritative — and it is the rule that keeps an attacker-influenced input from becoming index content. **A webhook may never trigger a full reindex**, both because that is the expensive thing it exists to avoid and because a cheap request that causes an expensive walk is a denial-of-service lever.

**Deliveries arrive twice, out of order, or not at all, and the design assumes all three.** The handler is idempotent by construction — re-reading a repository and upserting its versions is the same operation performed twice — and it never infers from one event that it saw the previous one. Consequence, stated so it is not quietly dropped later: **webhooks reduce staleness, they do not abolish the full walk.** The explicit `rescan-org` verb of [§2.8](#reindex) stays unconditional exactly because a missed delivery is invisible from inside.

**What each failure answers.** An unverifiable signature is `401` and is not processed. A payload naming a repository outside this server's configured organisation is `400` and is not processed — the scope check is not optional, since the repository name is the one field of the payload we act on. A verified, in-scope delivery whose re-read fails is `202`: the request was accepted and the work is ours to retry. Answering `5xx` to a sender that retries on a schedule we do not control would turn our own outage into a retry storm — the failure is on our side, and the status code should say so rather than invite the sender to hammer.

**The GitHub-Actions alternative, and why it is the fallback rather than the default.** The same effect is reachable without any endpoint: an Action in the package repository `POST`s to the write API of [§2.10](#http) with an admin token. It is genuinely simpler — no new route, no signature verification, nothing to specify. What it costs is exactly what `#WEBHOOK-SECRET-IS-NOT-THE-ADMIN-TOKEN` protects: **every participating repository then holds a credential that can write anything**, and the number of places a broad secret lives grows with the organisation. The webhook keeps one narrow secret in one place. So: webhook by default; the Action is the honest answer for an organisation that already runs its publishing through Actions and prefers one mechanism to two, and it has one capability the webhook does not — it can also push the built index files, being a runner with a checkout.

**Named, not invented — two things this section does NOT settle.** *(i)* Whether the server should require the pushed ref to look like a release tag before acting, or re-read on any push to the default branch as well: the second catches a manifest edited without a tag, which [§2.8](#reindex)'s incremental walk already treats as a real case, and the first is cheaper. Decide it against a measured event volume, not here. *(ii)* The GitVerse flavour is **unmeasured**: their public API could not enumerate an organisation, and nothing here establishes what their webhooks can do. Writing a `gitverse` route from that ignorance would be inventing a contract for a system nobody in this repository has watched.

**What it fixes.** The server already accepts an authenticated write, writes the files atomically, recomputes the manifest and verifies integrity. The one thing it could not do was **carry the result to where it is served from**. `--auto-commit-push` closes that: after each successful mutation the server commits the data directory and pushes it. Built 2026-08-06 on the owner's ruling; the flag had been declared and discarded by one line since the server shipped.

**Where it publishes is the operator's setting, and vibe-index does not mint a second place to say so.** The data directory is already a git working tree ([§2.4](#layout)), and a working tree's remote and branch are configured with plain git. So the push carries no refspec and names no remote — it goes where the tree is already pointed. A private repository is a legitimate target by construction: it is simply what the operator cloned. Rejected: a `--push-remote` / `--push-url` pair, and a target block in the on-disk config — both would be a second home for a value git already owns, which is the defect class this repository keeps paying for.

**Startup refuses rather than warns, and this is the flag's most important behaviour.** `state/` holds the bearer tokens ([§7](#secrets)). If the data directory's `.gitignore` does not cover them — a directory created before `init` wrote one, or one edited since — `git add -A` would stage those tokens and push them to a host that may be public. So with the flag set, the server **does not start** unless it confirms `state/admin.tokens` is ignored, and the refusal says so in those words. The check runs once at startup rather than per mutation, because the operator must learn the configuration is unsafe **before** the first token leaves the machine, not after.

**The second refusal:** the flag set over a data directory that is not a git working copy also stops the server, naming what to do. Publishing by committing a directory that is not tracked is not a degraded mode, it is a no-op that would look like success forever.

**A push failure never turns a successful write into an error.** By the time publication runs the mutation is on disk and in memory; the HTTP write has happened. So a failure is logged at `warn` with git's own message and counted as `vibe_index_publish_failures_total`, and the request still answers as it would have. It is not rolled back either: a network outage must not be able to corrupt index state. Transient failures self-heal — git accumulates, and the next successful push carries the queued commits.

**Nothing to commit is success, not an error** — the opposite of the publish flow's rule for the same operation, and deliberately so. The index lock is released before the push, so a second mutation can land while the first is publishing and the first commit carries both. The second then finds nothing staged, and that is the normal course of events rather than a caller's mistake.

**One publication at a time, and the response waits for it.** Two concurrent mutations must not interleave two commits in one working copy, so publication takes its own lock — not the index lock, which is released earlier and correctly so. The handler awaits the result on a blocking thread, which means a `200` says «persisted **and** published». For an index that is what the operator asked for, and mutations are publish events rather than a hot path.

**The commit message names what moved** — the upsert or the removal, with the package coordinate. Each of the three mutating routes knows its own change, so the index's history reads as a log of publications rather than a wall of identical messages.

<status stage="spec" state="void">Retired 2026-08-14 by the determinism phase. It recorded a real consequence of the writer stamping a fresh generation time on every write: a repeated identical upsert produced a diff and therefore a commit, so the empty-diff path fired only on the overlap case. Both halves of that consequence are gone — the writer takes its clock as an input (`##THE-WRITER-TAKES-ITS-CLOCK-AS-AN-INPUT`), and a mutation that changes nothing no longer writes at all (`##A-MUTATION-THAT-CHANGES-NOTHING-COMMITS-NOTHING`). Its closing sentence asked whether the index's own write should be deterministic and called that a question about the format rather than about this flag; the format answered yes. This tombstone stays so the old sentence's name is never reused and inbound links do not break.</status>

**A mutation that changes nothing writes nothing, and therefore commits nothing.** An upsert whose entry equals the one already stored under that version number leaves the in-memory state untouched, never reaches the writer, and never reaches the publisher; the two removal routes have always behaved this way, and the upsert route now matches them. The response is still success — the resource is already in the requested state, which is what idempotency means over HTTP — and the distinction between *created* and *changed* is kept, because a differing entry under an existing version number is an update and must still land. Determinism alone would not have bought this: with the clock arriving per mutation event, a repeat would still have moved `generated_at` and produced a diff. The point is not to produce an empty diff but to not create the work, so that the catalog's history records events that actually happened.

**No identity is invented.** The commit uses whatever git identity the host is configured with; if there is none, `git commit` fails and that failure takes the path above — logged and counted, never fatal to the write. Inventing a fallback author would put a name in an organisation's published history that nobody chose.

`req r2`

**Decision (owner rulings, 2026-08-13; not built — this section is the contract the build will follow).** A **channel** is an author-controlled named pointer `(group, name, channel) → version` — npm's dist-tags and Docker's tags are the prior art. The pointer map is **flat**: several channels may point at one version (a release that is both `latest` and `stable` is the everyday case), and no promotion semantics (`beta` → `stable` as a registry operation) are baked into the format — promotion is the author's workflow, not registry law. A channel may point at a snapshot or at a frozen version (PROP-044 §2b) — the axes are orthogonal.

`req r1`

**Decision.** A surface that cannot act on a record does not drop it — it **names it**. [PROP-044 §4.5](../../common/PROP-044-change-native-formats.xml#machinery) gives the law («the refusal surfaces at the point of use with a generated recipe»); this section gives its shape in this catalog. A version whose `must_understand` ([§2.6](#entry)) names a capability this build lacks is **unavailable to this build**, and every surface that computes an answer says so out loud. Quietly narrowing the answer instead would be the silence [PROP-044 §2](../../common/PROP-044-change-native-formats.xml#laws) forbids: the package exists and cannot be found, which is a riddle rather than a break.

**The answer row is one shape, used by every surface:** `{group, name, version, missing, recipe}`. It carries the **full coordinate even where the envelope around it already names the package** — a row that identifies itself survives being copied out of its envelope by a script, and a context-dependent one does not. `missing` is exactly the subset of the record's `must_understand` this build does not understand — not the whole declaration, because a reader that understands three of four capabilities must be told about the fourth, not about all four. `recipe` is the generated text that says what a person or a script does about it.

**The recipe is built in one place and never written as a literal at a call site.** One home, N surfaces: a literal per surface is N texts that drift, and the one that drifts is the one nobody reads until it matters. It is **degenerate today by measurement, not by omission** — no reader capability has been built yet, so every missing capability is one this build simply does not know and there is no second class of recipe to write. The per-capability table this grows into gets its first row from the first capability that lands; inventing rows for capabilities that do not exist would be machinery for a consumer that does not exist.

**Quarantine is the READER's judgement about a (record × build) pair, never a property of the record** — so it is derived at the point of use from the record's own `must_understand` and is **never stored on the wire**. The consequence worth the ink: the command line and the server agree **by construction**, not by two implementations being kept in step. The predicate reads the record, so it does not matter which carrier the record arrived in — and the carriers genuinely differ, since a catalog LOADED from disk arrives with a quarantine record while one PROJECTED from the journal arrives with an empty one. Two surfaces that agreed only because someone remembered to update both would disagree the first time one of them was forgotten.

**The safe default is a property of the construction.** The answering path asks the **named accessors** (`quarantine::usable_*`) and never reads the stored version list or `latest_stable` raw; the **writer's** path, the mutations, and the operational counters ask the raw state deliberately — the catalog is the projection of the journal ([§2.3](#truth)), and a reader's capabilities have no business shrinking what is WRITTEN or miscounting what the index HOLDS. The asymmetry is stated in the doc-comments of both sides, and that statement is the only defence against the next author reaching for the wrong accessor: the two calls look identical at the call site and differ only in what they mean.

**Which surfaces owe it, as a rule rather than a list** — because a list rots and a rule does not: **every surface that COMPUTES an answer owes the refusal; a surface that serves a stored file verbatim does not.** Computing covers each read verb that selects, narrows, ranks or aggregates, and each HTTP route that answers from the in-RAM index. Serving verbatim covers the raw file routes of [§2.10](#http).

**The raw candidate-set file is not silent, and making it «speak» could only mean removing information from it.** `by-name/<name>.json` hands back the record word for word, `must_understand` included — and that declaration IS the explanation of the refusal, delivered to a client that can then apply its own capability set rather than ours. Silence lived exactly in the surfaces that computed an answer and dropped a record without a word; the file that says everything was never the problem.

**Over HTTP the status stays `404` and the body carries the reason.** «You did not get the thing» is preserved for every client that only reads status codes, while the problem document's `type` and `title` name the refusal in its own words — not «resource not found» — and an **extension member** carries the whole answer row ([§2.10](#http) fixes the RFC 7807 shape; extension members are what that RFC provides for exactly this). The judgement rides the envelope and never enters the record: a `VersionEntry` is generated from the schema and says nothing about any reader.

`design r1`

**There is no `LICENSE` inside the crate, and that is the correct state.** `Cargo.toml` carries `license-file.workspace = true`, so the crate inherits the repository's licence rather than keeping a second copy that can disagree with it — the same single-home rule this document applies to normative values, applied to the one value a licence is. The repository's licence is UPL-1.0.

`design r1`

Minimal Rust crates to keep redistribution clean:

**No `prometheus` crate is pulled, and the omission is the design.** `/metrics` renders the Prometheus text exposition format from a hand-written serialiser, because the surface is a handful of counters and the exposition format is stable text — so the dependency would buy formatting we can write once and cost a tree we then carry forever. This is what «minimal crates to keep redistribution clean» means when it is applied rather than stated.

`tokio` is taken with four features — `signal`, `sync`, `time`, `fs` — not `full`. `full` is the shape a project reaches for before it knows what it uses; naming the four is the same discipline as the paragraph above, one level down.

**`vibe-core` dependency.** `vibe-index` parses `vibe.toml` and `vibe-subskill.toml` through `vibe-core`'s own `Manifest` / `SubskillManifest` types, so the index can never drift from the manifest schema. This reverses the proposal's original standalone-no-`vibe-core` stance — [§6](#distribution) records the reversal, [§9](#open) item 11 the de-rot finding that forced it. What stays duplicated is small and stable: the four-variant `PackageKind` / `NamingConvention` (`src/types/kinds.rs`, frozen by `VIBEVM-SPEC.md` §4, needing the `Ord` + `clap::ValueEnum` the `vibe-core` originals lack) and the `compute_content_hash` algorithm (`src/content_hash.rs`, gated by `tests/content_hash_parity.rs`). `compute_content_hash` folds into `vibe-core` once it is lowered out of `vibe-registry`.

**The parity gate is wider than one fixture and one algorithm.** It runs BOTH implementations over BOTH fixtures in BOTH recipes: `fixtures/golden-flow-wal-1.0.0/` is the ordinary package, and `fixtures/golden-order-trap-0.1.0/` is the tree built to make recipes 0 and 1 disagree — a directory whose name is continued by a sibling file at a byte below `/`, the only shape on which component-wise and byte-wise ordering part company ([PROP-002 §2.1](../vibe-registry/PROP-002-decentralized-registry.xml#identity)). A single fixture would let the two implementations agree by accident on every tree that never exercises the difference, which is exactly how a hash regression once reached a consumer before any golden noticed.

**Deliberately NOT pulling:**

`design r1`

**Decision.** Use shell-out to `git` via `std::process::Command` for the scanner's read paths (`git tag`, `git show <ref>:<path>`, `git rev-parse <tag>`). Same path `vibe-registry::shell.rs` already follows. Rationale matches PROP-001 §2.1: shell-out works on every platform git works on, no per-host bindings to maintain.

**Not** `gix` for v0: smaller dep tree wins. v1 may switch if perf demands and gix's read API matures further.

`design r1`

**Each mutating handler does the whole write itself, under the index's async write-lock:** replay the journal, project a probe, append the event, reproject, write the catalog, swap the in-memory index. There is no writer task and no channel to post to. The queue that the task was reaching for turned out to be unnecessary once mutations became journal appends: a handler holds the lock for one append plus one projection, and the operations it serialises are publish events rather than a hot path ([§2.17](#auto-publish) makes the same argument about awaiting the push). What IS serialised separately is publication — its own lock, and a blocking thread, because a git command must not run on the async executor.

`design r1`

For every flag with a default, precedence is: explicit CLI flag > env var (`VIBE_INDEX_*`) > on-disk config (`<data-dir>/state/config.toml`, optional) > built-in default. Same shape `vibe show config` already uses on the consumer side. *(Built 2026-08-20, B-086: the machine is `crates/vibe-index/src/config.rs` — every resolution carries the value AND its source, surfaced by the `vibe-index config <data-dir>` verb; the file rung parses strictly, an unknown key is a loud refusal. Four members ride it (`log-level` — with `VIBE_LOG` as the recorded legacy synonym below `VIBE_INDEX_LOG`, `git`, `api-base`, `dump-format`); the remaining ~17 flags-with-defaults join by the worked pattern — the mechanical continuation and its two owner forks (boolean value dialect; the `--limit` naming collision) are listed in the R3-LADDER worker report and the release-TZ log. `data-dir` is not a member: it is the required positional (`##CLI-SURFACE`) and the file rung lives inside it.)*

**None of that ladder exists.** There is no `config.toml` anywhere in the crate and no `VIBE_INDEX_*` family: a flag with a default gets it from its own declaration, full stop. Two environment variables do exist and neither is part of a precedence chain — `VIBE_INDEX_GIT` overrides the git binary the scanner shells out to, and `VIBE_LOG` is the logging lever `--log-level` folds into ([§2.11](#cli)). The requirement stands and the fork is `BACKLOG.md` B-086: build the ladder, or say plainly that this binary is configured by flags and two named variables. What must not survive is the middle state, where a document describes a resolution order an operator can neither use nor observe.

`crates/vibe-index/` standalone crate with `Cargo.toml` + `src/main.rs` + `src/lib.rs`. clap dispatch with stub subcommands that all print "not yet implemented". `vibe-index --version` works. `tests/help_smoke.rs` passes.

Commit: `feat(services/vibe-index): skeleton crate + clap subcommand dispatch`.

`src/types/` (entry / repomd), `src/index/` (memory, persistence, primary, by_name, repomd). JTD schemas in `schemas/`. Atomic write protocol. `vibe-index init` works (writes empty `repomd.json` + empty `primary.jsonl`). `vibe-index dump` works. `vibe-index verify` works (checks file hashes). Round-trip tests.

Commits:

`src/scanner/from_clones.rs` walks `<org-dir>/<repo>/.git` directories; `src/content_hash.rs` mirrors `vibe-registry::compute_content_hash`; `vibe-index reindex --from-clones` works against `fixtures/sample-org/`. Parity test against `vibe-registry`. Incremental mode = full for now (deferred to slice 7).

Commits:

`get`, `list`, `search`, `capabilities`, `purls`, `outdated`. Inverted text index for search. JSON output for every subcommand. `cli_e2e.rs` covers each.

Commits:

`vibe-index serve --read-only`. axum app exposes `/healthz`, `/readyz`, `/v1/index/*`, `/v1/packages*`, `/v1/capabilities/*`, `/v1/purls/*`, `/metrics`. PID lock file. CORS open. `server_e2e.rs` covers each route.

Commits:

After slice 5: vibe-index is **independently usable** as a read-only server fed by `reindex --from-clones`. This is the "MVP" mark.

`vibe-index add` / `vibe-index remove`. HTTP `POST /v1/packages`, `DELETE /v1/packages/...`. Bearer-token auth via `<data-dir>/state/admin.tokens`. Write-side server-vs-CLI lock arbitration.

Commits:

`<data-dir>/state/checkpoint.json`. `vibe-index reindex --incremental --from-clones` walks the diff between checkpoint and current state. Test: full vs incremental produce identical output.

Commit: `feat(services/vibe-index): incremental reindex via checkpoint`.

`reqwest`-based GitHub API walk. `--token-file FILE`. Rate-limit-aware backoff. Same shape as `--from-clones` from caller's POV.

Commit: `feat(services/vibe-index): reindex --from-github (REST API walk)`.

`crates/vibe-publish/src/lib.rs::Publisher::publish` gains optional index POST after successful push. New env var `VIBEVM_INDEX_TOKEN_<HOST>`. New `[[registry]].index_url` / `[[registry]].index_token` fields in the project manifest.

Commit: `feat(vibe-publish): POST to registry index after publish (opt-in)`.

`crates/vibe-registry/src/multi_registry_resolver.rs` gains the index-aware fast path. Falls back transparently on 404 / connect-failure. Live e2e test against an index-equipped registry.

Commit: `feat(vibe-registry): consume registry index for resolve fast path (opt-in)`.

`crates/vibe-index/docs/` filled in (operator-handbook, consumer-protocol, format). `manual-tests/M2.10-index-smoke.md` walks the live e2e: bootstrap an index from a fresh org dir, serve it, install a package through it, search it.

Commits: