Configuration reference

Caboodle writes a reviewable TOML plan and a JSON progress file. Use the CLI to create the plan; keep credentials in the environment, never in intent text. The plan’s schema rejects unknown keys.

Plan: caboodle-plan.toml

Crew ownership fields must match the selected mode. Do not hand-edit them into an alternative routing scheme. Profiles explains the contracts.

Intent: caboodle-intent.toml

plan embeds the intent in the plan. verify-questions executes those queries; custom questions require their seed facts in the target database first. The built-in interview self-test instead seeds its own temporary store. Installing and verifying tools does not seed a user’s production graph.

Local state and targets

.caboodle/state.json is generated progress, not user configuration. It records tools, model artifacts and staged shares. Preserve it to resume an interrupted apply or update. .caboodle/interview.toml checkpoints interview answers; .caboodle/episodes/ retains queued install records until confirmed delivery.

caboodle-observability.toml contains a [targets] table with quipu and, when selected, bobbin keys. Values are Prometheus host:port destinations, without a URL scheme or path. Rendering produces files for review, not a live scrape. See emission and proofs for those boundaries.

Environment

The shell release installer also accepts CABOODLE_VERSION, CABOODLE_INSTALL_DIR, CABOODLE_TARGET, CABOODLE_REPOSITORY and CABOODLE_RELEASE_BASE_URL. The last two select the download authority; keep them unset for official releases. These are installer inputs, not plan keys.

Quipu credentials

Obtain an accepted credential from the target server administrator through your approved secret distribution channel. The administrator activates the shared bearer or registers an issued named credential before distributing it. Locally installing a random token does not grant access.

install -d -m 700 "$HOME/.config/quipu" && install -m 400 /secure/issued-token "$HOME/.config/quipu/token"
caboodle provision-quipu-token --from /secure/issued-token --server https://your-quipu-server.example
caboodle doctor

provision-quipu-token proves the issued file against the authenticated server before installing it. It refuses to replace a differing existing credential; rotation remains a separate decision. It creates the canonical file with mode 0400 and its parent with mode 0700. No token is printed or stored in a plan.

A nonempty QUIPU_AUTH_TOKEN after trimming takes precedence over QUIPU_AUTH_TOKEN_FILE, then the default ~/.config/quipu/token. Files are read on every request so rotation reaches running sessions. An explicit file does not fall back to the default if missing. Existing deployments can retain their file override until provisioning and rotation move together; avoid independent copies of secrets. Token contents must never enter command arguments, logs or version control. Doctor and verify name the winning source without printing its value, including an environment value that shadows a valid canonical file.

Doctor checks the protected /episode route with {}. The server authorizes before rejecting the incomplete episode, so no graph data is written. It reports accepted authorization, missing token, rejected token, read-only server, or an unknown write path (including no HTTP response). This is authorization evidence, not a successful storage commit. Doctor also requires a nonempty canonical file with mode 0400 and parent mode 0700, and an authenticated /shapes read returning 2xx. caboodle verify runs that live credential proof before recording Quipu as verified, then exercises installed tools in isolated scratch stores. Set QUIPU_SERVER to the intended server; without it, verify uses the plan’s Quipu MCP URL or http://localhost:3030. Missing, rejected, or unproven credentials leave verification incomplete. Public health is not an auth check.

Quipu MCP for Claude Code

A Claude Code MCP entry for Quipu that holds only a URL sends no bearer. Reads work and every MCP write is refused with missing_or_invalid_bearer_token. caboodle plan --quipu-mcp-url <server> adds a reviewable [quipu_mcp] step. That step changes your Claude Code configuration, so it is opt-in.

apply installs ~/.local/bin/quipu-mcp-headers (mode 0755). Claude Code runs it at connect time. It reads the token with the precedence above and prints the Authorization header. apply then registers the user-scope entry {"type":"http","url":"<server>/mcp","headersHelper":"<helper>"} through claude mcp add-json. The secret is written into neither the helper nor the Claude configuration. Re-running is a no-op. A differing user-scope quipu entry, including one without a headersHelper, is replaced, and the output says so. If registering the new entry fails after the old one was removed, the old entry is put back. A running Claude Code session keeps its old connection until /mcp reconnects it.

Claude Code runs the helper in its own environment, which may not carry the token variables. If this host’s token file is not ~/.config/quipu/token, give its path with --quipu-mcp-token-file. plan also takes it from QUIPU_AUTH_TOKEN_FILE when that is set. The path, never the token, is recorded in the plan and becomes the helper’s default. QUIPU_AUTH_TOKEN and QUIPU_AUTH_TOKEN_FILE still take precedence when Claude Code has them.

verify fails if the user-scope entry is missing, differs from the plan or has no headersHelper. It also fails if a local-scope quipu entry without one shadows it. It then sends an invalid-Turtle quipu_knot call to /mcp, first without a credential as a control, which must be refused. It sends it again with the helper’s header, which must reach Quipu’s parser. Nothing is written. A server that accepts the unauthenticated control reports UNKNOWN, because it cannot show that the helper works. Verify runs in your shell, not in Claude Code. If the helper finds a token only through a variable set in that shell, it warns that Claude Code must see the same variable. Re-plan with --quipu-mcp-token-file if Claude Code will not see it.

Codex search signposts

The desire-path hook bundle supplies dp signpost-prefetch before Codex Bash calls and dp signpost after successful calls. Codex uses the same tool_name: Bash and tool_input.command hook envelope for these events. Turn-completion ingestion remains in codex_notify with --source codex; these search hooks do not convert turn records into tool-failure desires. Failure-event signposting is not claimed by this bundle for Codex.

Set DP_SIGNPOST_BOBBIN_URL, DP_SIGNPOST_LOG, and any deployment-specific DP_SIGNPOST_SEARCH_MODE in the environment that launches Codex. Values in Claude’s settings.json environment do not configure Codex. Verify a real search produces a signpost event under the Codex session ID and that prefetch warms the cache; a configured hook alone does not prove delivery.

Codex edit policy hook

The Yupana bundle registers yupana hook pre-edit for native apply_patch PreToolUse events. This requires a Yupana build with native multi-file Codex patch support; a pre-support binary silently ignores the patch contents. Activate this entry only after the supporting Yupana release is installed. Verify a real edit’s session-attributed guard metric and advisory output; rendered configuration alone does not prove edit coverage. Existing running agents pick up changed hooks on their next launch.

Externally owned Quipu

Set external_quipu = true in a reviewed plan when another mechanism owns Quipu installation. The default is false. Caboodle resolves quipu and quipu-server from PATH, reads both versions, and records their canonical paths with the identity. It never installs, converges, or release-updates these files. Missing executables and incompatible versions fail; external ownership does not waive the isolated write/read round trip or hook registration checks. Other tools retain their managed-install and shadow checks. Build flavors are incompatible with external ownership because Caboodle does not build that installation.

Verify uses the resolved client for both the entity and vocabulary round trips. An external source build has to support those contracts; a version banner alone is insufficient. check-updates reports external ownership rather than claiming release convergence. Apply records identity, while verify records functional proof. Changing executable paths invalidates retained verification even if the version strings match.