Configuration Reference

Configuration controls how Boundline resolves routing, assistant bindings, Canon defaults, 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
• 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|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
• 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.

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.

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 .