# Configuration reference
Tambo 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`
| `schema_version` | Plan schema version, currently `1`. |
| `profile` | `kg`, `retrieval`, `code-intel`, `everything` or `crew`. |
| `tools` | Ordered tool selection derived from the profile. |
| `shares` | Canonical Quipu share directories to stage during apply. |
| `quipu_db` | Explicit destination database, required when shares are selected. |
| `quipu_flavor` | `release` (default) or `lancedb`; see [profiles](profiles.md#quipu-install-flavor). |
| `stack_config.quipu.owl.reactive_materialize` | Recommended OWL materialization setting merged into Bobbin's config. |
| `crew.mode` | `shantytown`, `creel`, `both` or `standalone`. |
| `crew.durable_owner` | Shantytown for durable crew work, when selected. |
| `crew.burst_owner` | Creel for browser bursts, when selected. |
| `crew.routing` | `single-owner` or `explicit-handoff`, derived from the mode. |
| `crew.policy.identity_source` | `quipu`; crew identity authority. |
| `crew.policy.model` | Optional model selection. |
| `crew.policy.tools` | The crew profile's tool set. |
| `intent` | Intended-use contract described below. |
| `embedding_model.destination` | Directory for the model artifacts. |
| `embedding_model.artifacts` | Array of entries, each with `name`, HTTPS `url` and `sha256`. |
Crew ownership fields must match the selected mode. Do not hand-edit them into
an alternative routing scheme. [Profiles](profiles.md) explains the contracts.
## Intent: `caboodle-intent.toml`
| `intended_use` | Nonempty plain-language purpose. |
| `crew_members` | Array with `name`, `theme`, `domain`, `role`; may be empty. |
| `anticipated_questions` | At least one executable reader-path question. |
| `anticipated_questions[].question` | The question in words. |
| `anticipated_questions[].answer_shape` | Shape of the expected answer. |
| `anticipated_questions[].seed_intent` | Facts required before the query can pass. |
| `anticipated_questions[].sparql` | `SELECT` or `ASK` query. |
| `anticipated_questions[].expected` | Marker required in its result. |
| `anticipated_questions[].self_test` | Built-in scratch-store check flag; normally generated by the interview. |
`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](emission.md) and [proofs](proofs.md) for those boundaries.
## Environment
| `HOME` | User configuration, data and default install directories. |
| `CARGO_HOME` | Overrides the binary destination root; binaries go in its `bin/`. |
| `PATH` | Must find the installed binaries before stale copies. |
| `CABOODLE_CAMAYOC_ROOT` | Override the Camayoc distribution root. |
| `QUIPU_SERVER` | Existing Quipu server for operations that need one; temporary functional checks remain isolated. |
| `QUIPU_AUTH_TOKEN` | Nonempty bearer override for Quipu requests. |
| `QUIPU_AUTH_TOKEN_FILE` | Request-time token file; defaults to `~/.config/quipu/token`. |
| `CABOODLE_HOLD_FILE` | Override the release-update hold marker, default `~/.caboodle/hold`. |
| `SHANTY_TOOLING_MANIFEST` | Shantytown's managed rig registration manifest; see [agent setup](installing.md#registering-mcp-servers). |
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 (advanced remote mode)
The default `tambo quickstart` uses a local embedded store and needs no token
or running server. Only explicit `QUIPU_SERVER` or `quipu_mcp` configuration
selects authenticated remote verification. To return to local mode, unset the
environment variable and deliberately remove any remote MCP plan configuration.
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.
```sh
install -d -m 700 "$HOME/.config/quipu" && install -m 400 /secure/issued-token "$HOME/.config/quipu/token"
tambo provision-quipu-token --from /secure/issued-token --server https://your-quipu-server.example
tambo 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. `tambo 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`.
`tambo 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. Tambo 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 Tambo 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.