Compose bootstrap resources from multiple selected config roots

[Guria]

Summary

I maintain a dotfiles repository that composes a workstation configuration from multiple selected configuration roots.

The repository uses mise configuration environments for selection. This works, but the selection layer currently requires a manually maintained template:

• the template enumerates the dimensions relevant to the repository;
• it derives positive environment labels from those dimensions;
• it manually adds negated labels for dimensions that are not active;
• environment-specific contributions must remain synchronized with that template.

The problem is not simply that mise lacks environment selection. The problem is that a configuration composed from several selected roots has no first-class bootstrap resource graph. The repository has to discover selected roots, materialize their contributions, and reconcile their interactions through a custom orchestration loop.

This discussion proposes a low-level API for composing selected bootstrap resource declarations. It does not assume that the solution should be called components, packages, or bundles, and it does not require a new selector DSL. Whether the existing environment model should be extended or reused is one of the design questions.

The repository model

The repository contains capability-specific configuration roots. A root may provide mise tools and global task fragments, application configuration, shell fragments, templates, managed blocks, agent instructions and skills, repository seeds and overlays, and host-specific services.

The roots are not independent applications. They contribute to shared configuration surfaces. For example, ~/.config/mise/, the shared agent instruction tree, and ~/.config/pitchfork/config.toml receive contributions from multiple roots. Some contributions are active only for a selected environment.

The current implementation applies these roots in a custom sequence, then runs a reconciliation phase after all selected global configuration has materialized.

Selection and environment dimensions

The repository currently uses mise environments for selection:

• hostname-derived environments;
• machine and platform dimensions;
• display-class environments such as headed;
• explicit opt-in labels from ~/.config/dotty/envs;
• negative environments such as not-exe.xyz.

This is an adopted approach, not an assumption that the current API is sufficient.

The practical problem is that the repository must maintain a template describing the dimensions it knows about. That template also manually emits negated labels. For example, a contribution that should apply outside exe.xyz depends on not-exe.xyz.toml, while the bootstrap template must know that exe.xyz is a dimension that can be negated.

This creates two maintenance obligations:

1. the template must be updated when a new selectable dimension is introduced;
2. environment-specific contributions must use names that remain consistent with the template's positive and negative labels.

The selection rules are distributed between mise's environment discovery, the repository's .miserc.toml template, environment-specific entrypoints, and manual environment labels.

A future API does not necessarily need a new selector language. It could reuse the existing environment resolution model. But the current manually maintained dimension/negation template should not be treated as the final selection design.

Cross-root example: fff contributes to the shared harness configuration

The fff configuration is not part of the Claude Code configuration itself.

fff is a capability that provides:

• the fff-mcp executable;
• the MCP server declaration;
• an instruction contribution for the shared agent configuration;
• a reconciliation action that registers the server with Claude Code when Claude Code is selected.

Claude Code is only one consumer of this capability. Other agents or harness clients may consume the same shared configuration in the future. Putting the entire integration in the claude root would make the ownership direction wrong: the consumer would own a capability-specific contribution.

The desired composition is:

fff selected
  → install fff-mcp
  → contribute fff instructions to the shared harness configuration
  → register fff with selected harness clients that support MCP

claude selected
  → install Claude Code
  → expose Claude Code's configuration surface

fff selected, claude not selected
  → install fff-mcp
  → keep the shared fff contribution
  → do not invoke the Claude-specific registration

fff not selected
  → do not install fff-mcp
  → do not materialize the fff contribution
  → do not register fff anywhere

In the current repository, the fff root contributes to the shared ~/.local/share/dotty/agents/AGENTS.md tree and declares a reconciliation task. That task reaches Claude Code through an optional task dependency because Claude Code may not be selected.

The important relationship is therefore not:

claude owns fff

It is:

fff contributes to a shared harness surface
Claude Code is one selected consumer of that contribution

The same pattern applies to herdr, mise-introspection, catchup, and other capabilities that add permissions, tools, instructions, or integrations to the shared harness configuration.

Other concrete examples

The names and domains below are specific to this setup. They are examples of resource relationships, not proposed mise concepts:

• cpa contributes client configuration, while cpa-host contributes gateway/backend service configuration on cpamc.exe.xyz.
• cpa contributes a tunnel only outside exe.xyz through mise.not-exe.xyz.toml.
• apphane-host, axisflow-host, and easysell publish environment-specific repository seeds and overlays consumed later by the repos capability.
• t3code patches its provider settings from available CPA sources during reconciliation.
• selected SSH-related capabilities contribute encrypted keys, but keys must only be installed when their contributing configuration root is selected.

Current orchestration

The custom bootstrap task currently has to determine which environment-specific roots are active, apply each active root separately, merge shared symlink-each trees, compose managed blocks, render templates with the correct source root, install tools contributed by selected roots, run integrations only when their consumers are selected, re-render shared configuration after new fragments appear, run a final reconciliation phase, and resolve selected resources such as encrypted SSH keys.

The result is a second orchestration layer around mise. It repeats decisions that mise already makes for configuration selection, but it has no common resource graph, conflict model, or provenance output.

Existing mise behavior that seems reusable

The existing API already has useful semantics:

• configuration environments decide which config files are active;
• relative source paths resolve relative to the config that declares them;
• templates expose config_root;
• [dotfiles] entries merge by target;
• managed edits merge by (path, id);
• symlink-each records managed links;
• [bootstrap.files] and [bootstrap.directories] already participate in plan/status;
• bootstrap has declarative lifecycle phases and resource IDs;
• mise config ls can show loaded configuration files.

The gap is that monorepo.config_roots is primarily used for task/tool discovery and workspace operations. It does not currently mean “collect bootstrap declarations from all these roots and apply them as one graph.”

Proposed API direction

The first question is whether the existing environment selection model can be used directly, or whether mise needs a more general way to describe selectable configuration dimensions.

The bootstrap resource problem is separate from that question.

A possible low-level API would let mise collect declarations from selected configuration roots:

[bootstrap]
config_roots = ["bundles/*"]

The exact key and relationship to [monorepo].config_roots are open questions. The intended behavior would be:

1. resolve each root using mise's normal configuration and environment rules;
2. include only active contributions;
3. collect declarative bootstrap resources;
4. resolve each relative source against its declaring config root;
5. preserve that root as the template's config_root;
6. build one resource graph;
7. expose one plan, status, and apply operation.

This proposal does not require introducing a new bundle, component, or package selector. It also does not claim that the current environment dimension template is ideal. Selection and resource composition should be designed as related but separable concerns.

Possible conflict semantics

A composed resource graph would need deterministic conflict handling.

A possible MVP policy:

• identical declarations for the same resource are deduplicated;
• different whole-file declarations for the same target are an error;
• different sources for the same symlink-each leaf are an error;
• edit entries with different IDs compose;
• edit entries with the same ID but different definitions are an error;
• filesystem conflicts retain the current explicit --force behavior;
• independent configuration roots do not acquire an implicit precedence relationship.

Errors should identify both declarations, for example:

conflicting bootstrap resources for ~/.config/tool/config.toml

  first:
    config: bundles/editor/mise.toml
    source: bundles/editor/config/tool/config.toml

  second:
    config: bundles/workstation/mise.workstation.toml
    source: bundles/workstation/config/tool/config.toml

Provenance and status

For composed resources, status and plan output would be more useful if they included the contribution origin.

For example:

{
  "target": "~/.local/share/dotty/agents/AGENTS.md/fff",
  "source": "bundles/fff/agents/instructions/fff.agents.md",
  "config": "bundles/fff/mise.toml",
  "config_root": "bundles/fff",
  "environment": [],
  "state": "applied"
}

This could also explain why a resource is active, why it is inactive, which config root owns a managed link, which declarations conflict, which source disappeared, and why a shared target is still considered managed.

The current dotfiles status output already reports target, source, mode, and state. The proposal would extend that with provenance rather than introducing an unrelated ownership system.

Source and template semantics

I would expect the following behavior:

# bundles/fff/mise.toml
[dotfiles]
"~/.local/share/dotty/agents/AGENTS.md/fff" = {
  source = "agents/instructions/fff.agents.md",
  template = "tera"
}

The source should resolve relative to bundles/fff/mise.toml, and the template should see:

config_root = bundles/fff

This preserves the behavior of independently applied config roots and avoids making templates depend on the aggregate root.

What this would cover

This would cover composed symlink-each configuration trees, shared managed files, contributions from multiple selected roots, environment-specific contributions, source-relative templates, one plan/status/apply operation, deterministic conflict diagnostics, and provenance for each resource.

It would also make it possible for repositories like this one to remove much of their custom bootstrap looping without requiring mise to understand a repository-specific “bundle” concept.

What it would not cover initially

I would not expect the MVP to aggregate arbitrary imperative tasks or hooks.

Tasks may install or call tools, access the network, mutate repositories, provision credentials, start services, or assume another task exists. Their lifecycle and dependency semantics deserve a separate discussion.

A first implementation could therefore support only declarative resources and leave custom reconciliation tasks explicit.

Alternative smaller step

A smaller first step could add provenance to existing bootstrap resources without adding multi-root collection:

declaring config
declaring config root
active environment
source
resource identity

That would improve conflict diagnostics and status output and could serve as a foundation for later resource collection. It would not solve the need for one aggregate plan/apply/status operation.

Open questions

1. Should bootstrap use a new [bootstrap.config_roots] setting, or should this extend the existing [monorepo].config_roots model?
2. Should collection be limited to declarative resources initially?
3. Should independent roots have no precedence, with conflicts failing explicitly?
4. Should identical declarations be deduplicated or shown as multiple contributions?
5. How should symlink-each state be represented when multiple roots contribute to one target tree?
6. Should inactive contributions be visible in a verbose status mode?
7. Should provenance be persisted, or derived from the active configuration on every run?
8. Could the existing bootstrap resource ID model be reused directly?
9. Should hooks/tasks eventually get an aggregate lifecycle, or remain explicitly invoked?
10. How should config trust and environment-specific config discovery interact with aggregate roots?
11. Can the existing environment model discover dimensions without a repository-maintained negation template, or should negated environments remain explicit?

Suggested MVP

The narrowest useful MVP appears to be a selected-root collection for declarative resources: [dotfiles], [bootstrap.files], and [bootstrap.directories].

It should provide:

• reuse of the existing environment selection mechanism, without requiring a new selector DSL;
• source-relative resolution;
• template evaluation with the declaring root as config_root;
• deterministic conflict errors;
• provenance in plan and status;
• one aggregate apply/plan/status operation.

The MVP should not aggregate arbitrary hooks or tasks. Those have side effects and need a separate lifecycle contract.

The selection problem should remain an explicit open question. The current environment setup is useful, but maintaining the dimension and negation template is a real part of the cost of this approach.

[Guria]

I'm open for alternative implementations and suggestions as you obviously have better context how to solve such things.

[jdx]

Thanks for the detailed write-up. I traced this through the current config and bootstrap implementations, and I agree with the separation between selection and resource composition.

I opened #12100 with the smaller provenance step proposed here. It retains the declaring config, config_root, active config environment, and resolved source for dotfiles and managed files/directories, then exposes that origin in plan/status output.

A couple of implementation findings affect the collection follow-up:

• The existing [monorepo].config_roots loader is reusable and already discovers the active environment-specific configs for each root.
• Its resulting config union cannot be handed directly to bootstrap. Current aggregation assumes hierarchical precedence and silently chooses one declaration for duplicate dotfile/file targets. Independent selected roots need a separate composition phase that preserves normal precedence within each root, but treats sibling-root collisions as explicit conflicts.
• symlink-each ownership is already recorded per (source, target), so multiple contributors to one target tree are feasible. The composer still needs to expand and validate leaf identities before apply so two roots cannot claim the same leaf accidentally.
• The current environment model only knows active positive labels. It cannot synthesize not-* labels without a declared universe of dimensions, so I would keep automatic negation out of the bootstrap composition MVP.

My preferred next step after #12100 is a bootstrap-specific selected-root loader, reusing the monorepo discovery internals, followed by conflict-aware composition for [dotfiles], [bootstrap.files], and [bootstrap.directories]. I would not make every [monorepo].config_roots entry contribute host bootstrap resources implicitly.

AI-assisted — Tool: Codex; model: openai/GPT-5; version: unavailable.

[Guria]

First — thanks @jdx. Composition shipped within days of this discussion, the
provenance layer from #12100 landed first, and the traced-through reply
above is exactly the kind of response that makes upstream worth engaging
with. This repo already runs on the result.

Follow-up with verified results on v2026.8.9, which shipped the selected-root composition from this discussion (#12105, #12132), checked against a fixture mirroring this repo's shape (config_roots = ["bundles/*"]).

Confirmed working:

• edit entries with distinct IDs from different roots compose into one file — the (path, id) key works across roots;
• identical declarations deduplicate;
• environment-specific configs (mise.<env>.toml) load per selected root, so env-gated contributions behave the same under composition;
• conflicts name both declaring configs — the provenance from feat(bootstrap): expose resource provenance #12100 shows up in the error itself.

One divergence from the conflict semantics discussed here. The comment above states:

symlink-each ownership is already recorded per (source, target), so multiple contributors to one target tree are feasible. The composer still needs to expand and validate leaf identities before apply so two roots cannot claim the same leaf accidentally.

The shipped composer errors before that leaf expansion: any two declarations of the same target are a conflict, even when the source trees hold disjoint leaves (a: conf.d/a.toml, b: conf.d/b.toml → conflicting dotfile declarations, both origins named).

Sharing one directory across roots is symlink-each's primary composition case — merging into a directory the root doesn't own is that mode's documented purpose. The repo this discussion came from declares "~/.config/mise/" symlink-each from 31 roots, disjoint by construction (each contributes its own conf.d/<bundle>.toml fragment), so with target-keyed conflicts the composition cannot replace the orchestration loop at all.

One more behavior worth flagging for adoption planning: a parent's config_roots is live in child invocations. mise bootstrap run from inside bundles/a still composes all roots and hits the same conflict, so the glob can't be staged root by root — enabling it anywhere changes every per-root pass at once.

Minimal repro with materialized fixture trees and a fix-detector script: https://github.com/Guria/mise-config-roots-repro

Is target-keyed conflict the intended MVP boundary, with the leaf-identity validation quoted above as a follow-up? Leaf-keyed validation — union the source trees, conflict only when two roots claim the same leaf — would unblock the original use case; the custom loop in this repo exists mostly to perform exactly that union by hand.

[jdx]

Confirmed — this was an implementation gap in the config-root composer. It keyed sibling whole-file declarations by the directory target before symlink-each expanded its source tree, so the existing per-(source, target) ownership machinery never got a chance to compose disjoint leaves.

I opened #12190 with the fix. It:

• preserves multiple same-target symlink-each contributors;
• validates their combined desired footprint before mutation;
• allows shared directories and disjoint leaves;
• rejects duplicate leaf claims and file/directory prefix collisions with both declaring configs;
• keeps ownership state independent when one contributor is already applied and another still needs work.

The focused unit tests and e2e/cli/test_bootstrap_config_roots pass, including the materialized two-root shape from the repro and a state-recording regression case.

The inherited parent config_roots behavior remains unchanged; this PR addresses the leaf-keyed composition blocker.

Thanks for the careful verification and the fix-detector repro.

AI-assisted — Tool: Codex; model: openai/GPT-5; version: unavailable.