index-bead

Reindex a single bead by id, without fetching the whole bead corpus.

bobbin index-bead <BEAD_ID> [PATH] [OPTIONS]

bobbin index --include-beads is the batch path: it pulls every visible bead out of Dolt to work out which ones changed. That is fine on a schedule and far too expensive to run on every bd update. index-bead is the fast path for a post-write trigger — it fetches one bead, re-embeds it only if its assembled content actually changed, and leaves the rest of the corpus alone.

Both paths write the same corpus, keyed the same way (beads:{rig}:{bead_id}), so they are interchangeable: a bead updated incrementally looks exactly as a batch run would have left it.

Examples

bobbin index-bead bo-abc123              # reindex one bead, searching every configured rig
bobbin index-bead bo-abc123 --rig aegis  # restrict the lookup to one rig
bobbin index-bead bo-abc123 --force      # re-embed even if the content hash is unchanged
bobbin --json index-bead bo-abc123       # machine-readable result

Options

Outcomes

--json reports one of four statuses, and the human output says the same thing in words:

removed is the case worth understanding. A bead that has just been closed is exactly when a post-write trigger fires, and a closed bead does not pass the default [beads] visibility rules. index-bead applies the same rules the batch query does, so such a bead comes back as “not found” and is swept out of the index — the same end state a full run would reach, arrived at one bead at a time.

The corollary: index-bead never re-admits a bead the batch path filters out. Asking for a bead by name does not relax include_closed, max_age_days or exclude_labels.

Prerequisites

index-bead refuses rather than guessing in three cases:

• No [beads].databases configured. Unlike bobbin index, there is no file half that could still do useful work, so this is an error and not a silent no-op — a hook wired to a misconfigured repo would otherwise report success forever while indexing nothing.
• No index yet. Run bobbin index --include-beads once first. (bobbin init creates an empty vector directory, so its existence is not evidence that an index was ever built.)
• The embedding model changed. A full index wipes and rebuilds on a model change; a single-bead run cannot, and inserting one row of incompatible vectors beside the rest would corrupt search silently. Run bobbin index --force --include-beads instead.

Wiring it to a post-write trigger

The beads side of this — a bd hooks feature that fires the command after a write — lives in the beads CLI, not here. Any post-write mechanism works; the command is idempotent and cheap when nothing changed:

bobbin index-bead "$BEAD_ID"

See Configuration Reference for the [beads] section.