Contributing to Bobbin

Bobbin is a local-first Rust code context engine.

Using Just

This project uses just as a command runner. Always prefer just commands over raw cargo commands - they’re configured with sensible defaults that reduce output noise and save context.

just --list          # Show available commands
just setup           # Install system deps (protoc, c++, verify rust)
just build           # Build (quiet output)
just test            # Run tests (quiet output)
just check           # Type check (quiet output)
just lint            # Run clippy (quiet output)
just run             # Build and run

Verbose Output

All cargo commands run in quiet mode by default (-q --message-format=short). To see full output:

just build verbose=true
just test verbose=true

Rust Development

Prerequisites

• Rust (stable toolchain) — install via rustup
• just command runner
• protoc (Protocol Buffers compiler) — required by lancedb
• C++ compiler (g++ on Linux, Xcode CLT on macOS)

Run just setup to install system dependencies automatically.

Build Commands

just build           # Build the project
just test            # Run all tests
just check           # Type check without building
just lint            # Lint with clippy

Feature Integration Checklist

When adding new features to bobbin (new search signals, data sources, chunk types, or storage capabilities), review whether the bobbin context command should incorporate the new signal.

The context command is the “everything relevant in one shot” command. It combines hybrid search + temporal coupling to assemble task-aware context bundles. New retrieval signals should flow into it.

Before merging a new feature, check:

• Does this feature produce a new retrieval signal? (e.g., dependency graph, complexity scores)
• If yes, should context use it during assembly? Update src/search/context.rs
• Does this change chunk types or storage schema? Update context output types if needed
• Does the MCP context tool need updating? Check src/mcp/server.rs
• Are there new CLI flags that context should also expose?

Task specs for the context command live in docs/tasks/context-*.md.

Code Quality Standards

Linting

Clippy is the primary Rust linter. Run it via just:

just lint            # Clippy with quiet output
just lint verbose=true  # Full clippy output

All warnings should be resolved before merging.

Documentation Checks

The mdbook documentation has its own quality pipeline:

just docs build      # Build the book (mdbook)
just docs lint       # Markdown lint (markdownlint-cli2)
just docs check      # Full pipeline: lint + vale + validate + build

Run just docs check before pushing documentation changes.

Domain vocabulary (Vale spelling)

Vale’s Style check runs across every file in docs/book/src/, so a spelling error in any file fails the check — even one untouched by your change. Domain terms (product names, identifiers like knowledge_context, dev jargon like async) are not in Vale’s dictionary and would flag as misspellings.

Add such terms to the accept-list, one per line:

.vale/styles/config/vocabularies/Bobbin/accept.txt

Entries are case-insensitive when lowercase (e.g. quipu also accepts Quipu); add an explicit capitalized form only when the lowercase spelling is itself a real word that should still be checked. To find every flagged term locally:

vale sync
vale --minAlertLevel error docs/book/src/

Feature Flags

The knowledge feature enables Quipu integration. When adding code that depends on Quipu, gate it behind #[cfg(feature = "knowledge")]:

#![allow(unused)]
fn main() {
#[cfg(feature = "knowledge")]
fn open_knowledge_store(&self) -> Result<quipu::Store> {
    // ...
}
}

This ensures Bobbin compiles cleanly with and without the feature.