Configuration Reference

Configuration controls how Boundline resolves routing, assistant bindings, Canon defaults, provider registrations, domain defaults, and other explicit runtime policy.

Configuration is not the same thing as session state, traces, or provider auth.

Config Locations

Common locations:

<workspace>/.boundline/config.toml
<primary-workspace>/.boundline/cluster.toml
$XDG_CONFIG_HOME/boundline/config.toml
$HOME/.config/boundline/config.toml

Workspace-local configuration is where most operators should look first.

Resolution Precedence

Boundline resolves many runtime values in this order:

1. explicit CLI input
2. workspace config
3. cluster config
4. user-global config
5. built-in defaults

Inspect the effective result with:

boundline config show --scope effective

What Config Owns

Workspace and global config can own:

• routing defaults
• assistant bindings
• runtime capability profiles
• slot effort policies
• Canon preferences
• capability-provider registrations and active selection metadata
• domain template settings
• project memory roots
• workflow registry references

Keep major delivery behavior explicit and reviewable.

The default repo-visible roots remain docs/project/ for stable inputs and docs/evidence/ for durable outputs. Config can remap project-memory roots, but it should not blur the boundary between repo-visible delivery knowledge and runtime-owned state. See Project Memory Structure.

What Config Does Not Own

The following remain runtime-owned rather than config-authored:

• session state in .boundline/session.json
• traces under .boundline/traces/
• planning-gate outcomes such as goal_quality_state, plan_quality_state, backlog_quality_state, and planning_analysis_state
• additive backlog projections such as backlog_quality_findings, backlog_task_count, backlog_mvp_scope, and backlog_unmapped_items
• additive planning-analysis projections such as planning_analysis_findings and planning_analysis_coverage
• phase_request and assistant-safe follow-up commands
• read-only readiness answers from boundline probe

Provider Auth Profiles

Provider auth is adjacent to config but separate from it.

boundline models auth login --provider github-copilot
boundline models auth status

• Auth profiles are user-scoped.
• They live beside the user-global config in auth-profiles.json.
• They are not written into workspace config or session state.
• In the current public slice, login supports github-copilot.

Treat these profiles as operator credentials, not repository configuration.

Capability Provider Configuration

Capability-provider registrations are workspace-visible configuration, but the runtime still owns activation and validation outcomes.

Use the CLI surface instead of editing raw keys:

boundline provider add demo --workspace <workspace> --command python3 --arg scripts/provider.py
boundline provider show --workspace <workspace> --json
boundline provider remove demo --workspace <workspace>

Configuration stores provider descriptors, config-ref wiring, secret-handle refs, setup requirements, and the currently selected provider ID. Readiness, validation disposition, accepted evidence, and failure class remain runtime state rather than config-authored truth.

Assistant Setup Versus Routing

Assistant setup has two parts:

• package surfaces generated by boundline init --assistant <host>
• runtime/model routing defaults resolved by config

Package folders expose commands. Routing decides which runtime or model owns a delivery slot. They are related but not the same.

Ollama Routing Presets

Use boundline init --ollama-profile <profile> when the workspace should run against local Ollama models instead of remote provider defaults.

boundline init --ollama-profile small

The preset writes codex:ollama/<model> routes for the four delivery slots and uses OLLAMA_BASE_URL from the provider env layer. The default endpoint is http://localhost:11434.

Profile	Target	Planning and implementation	Verification and review
small	Apple Silicon with 16 GB unified memory	qwen2.5-coder:7b	qwen2.5:7b
medium	64 GB local workstation	qwen2.5-coder:14b	qwen2.5:14b
large	96/128 GB local workstation	qwen2.5-coder:32b	qwen2.5:72b

Framework Adapter Selection

Framework adapter selection is workspace-local config, but operators should manage it through the adapter commands instead of raw key edits:

boundline adapter add speckit --workspace <workspace>
boundline adapter show --workspace <workspace> --json
boundline adapter remove --workspace <workspace>

Use adapter show --json to inspect the persisted selection, config completeness, declared supported transports, stage override claims, hook subscriptions, and compatibility metadata before running plan or run.

When required adapter fields are missing, adapter add --non-interactive blocks before activation and reports the missing field keys plus the recovery command. If an already selected adapter later returns a blocked preflight, Boundline keeps that pre-claim boundary explicit through the recorded fallback reason.

Canon Preferences

Canon preferences are part of config when governed delivery is expected:

boundline config set-canon --workspace . --mode-selection auto-confirm
boundline config show --workspace . --scope workspace

Common fields include:

• mode selection
• default risk
• default zone
• default owner

Workflow Registry Boundaries

Authored workflows stay intentionally narrow. They describe one bounded route, not a hidden workflow engine.

[workflow.governed-delivery]
goal_source = "session"
entry = "capture"
phases = ["capture", "plan", "run", "review", "govern", "inspect"]
allow_review = true
allow_governance = true
summary = "bounded delivery path with review and governance before completion"
recommended_when = "the task needs explicit review and governance evidence"

[workflow.governed-delivery.when]
review = "review_triggered"
governance = "governance_required"

The supported authored shape has no branching, loops, fan-out, fan-in, hidden background progression, or Canon-owned workflow control. Workflows provide named entrypoints over the same runtime; governance remains explicit and route-driven.

Safe Defaults

Use these defaults unless there is a clear reason not to:

• keep normal local delivery on the session-native path
• use Canon only when governed delivery is required
• inspect effective routing before blaming an assistant package
• treat blocked context, failed validation, and blocked governance as real stop conditions
• keep framework adapters opt-in and inspect supported_transports plus config completeness before treating an adapter as runnable

Advanced Context And Semantic Acceleration

Two optional policy surfaces remain explicit:

[routing.advanced_context]
retrieval_mode = "local"
remote_policy = "local_only"

[routing.semantic_acceleration]
policy = "local"
index_hook_action = "mark_stale"

• advanced_context controls the baseline local retrieval path.
• semantic_acceleration is an additive opt-in for local semantic expansion.
• index_hook_action = "mark_stale" is optional and only valid when semantic acceleration stays local.

Common operator commands for this surface are:

boundline config set-semantic-acceleration --scope workspace --policy local
boundline init --semantic-index-hook-action mark-stale
boundline index status --workspace .
boundline index doctor --workspace .