Using caboodle

Caboodle ships a resumable interview and the plan/apply/verify engine with adapters for Quipu, Camayoc, Bobbin, Yupana, and Desire Path.

cargo install --git https://github.com/scbrown/caboodle --locked

# Guided: use, crew themes, and anticipated graph questions are checkpointed.
caboodle init --guided

# Read-only preflight: every blocker on this host, before anything installs.
caboodle doctor

# Non-interactive: read the same schema from caboodle-intent.toml.
caboodle plan --profile retrieval --intent caboodle-intent.toml

# Converge the reviewed plan, then prove both tools with isolated round trips.
caboodle apply
caboodle verify
caboodle verify-questions

# Or run both phases together after review.
caboodle install

apply installs a missing released tool and reads its version back — a successful installer exit alone is never accepted. verify uses temporary isolated stores: it proves a marker absent, writes it, and requires the reader path to return it. Progress is written atomically to .caboodle/state.json, so rerunning converges.

If input ends partway through an interview, Caboodle stops without a plan and keeps accepted answers in .caboodle/interview.toml. Run caboodle init --guided again to resume at the next unanswered question. Invalid answers are rejected and never produce a plan.

Use --skip-install when package installation belongs to another system; the version and functional checks still run.

code-intel adds checksum-pinned Yupana and proves a caller edge in a temporary repository with isolated HOME/state. everything additionally installs Desire Path by building the revision its v0.3.2 tag names, reads it back from dp version, and proves ingest/list against a temporary database. These checks never use the user’s normal evidence stores.

caboodle-intent.toml names the intended use, zero or more themed crew members, and at least one anticipated ontology question. A question is a contract, not a wish: it includes an answer shape, fixture/seed intent, executable SELECT or ASK SPARQL, and an expected result marker. The reviewed install plan embeds the contract, and verify-questions executes it through Quipu’s reader path. This makes “what should the graph answer?” an install acceptance test.

A first install usually has no ontology to ask about yet. Pressing enter at the question-count prompt selects the built-in self-test question instead. It seeds one caboodle-verify-roundtrip node into a scratch store and queries for it, so it passes on a fresh machine. verify-questions always runs it against that scratch store, even when --db points at your own. Replace it with real questions later by editing [intent] in the plan.

intended_use = "answer dependency and ownership questions about my services"

[[crew_members]]
name = "Harbor"
theme = "patient navigator"
domain = "service operations"
role = "trace dependencies and explain incidents"

[[anticipated_questions]]
question = "which services depend on the message broker?"
answer_shape = "a list of service entities"
seed_intent = "two fixture services and one depends_on edge to the fixture broker"
sparql = "SELECT ?service WHERE { ?service <https://example.org/depends_on> <https://example.org/broker> }"
expected = "fixture-service"

The prose fields steer ontology and seed construction; the SPARQL and expected marker decide whether that construction is retrievable through the path a reader will actually use. Never put credentials in this file or the generated plan.

Review observability before deployment

For every selected tool, CABOODLE emits a versioned contract. Quipu and Bobbin currently declare /metrics and required metric families; tools without an exporter remain explicit contracts with an unavailable reason rather than being silently omitted. Supply generic Prometheus targets without URL schemes:

[targets]
quipu = "quipu.example:8080"
bobbin = "bobbin.example:3030"

Then render and inspect the artifacts. Rendering never claims the targets were scraped or deploys anything:

caboodle render-observability --targets caboodle-observability.toml
caboodle validate-observability
less caboodle-observability/prometheus.yml
less caboodle-observability/alerts.yml
less caboodle-observability/dashboard.json
less caboodle-observability/contracts.json

Validation fails on a missing or malformed selected target, a target for a tool whose pinned contract has no exporter, a missing scrape job, or an alert or dashboard metric absent from the versioned contracts.