docs(concepts): add the loadouts concept guide - #940
Conversation
📝 WalkthroughWalkthroughThis PR adds conceptual documentation for per-developer session loadouts, covering their composition model, supported contributions, activation and default-selection behavior, storage conventions, listing commands, and related references. ChangesLoadout documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
Comment |
|
@macroscope review |
|
Manual reviews triggered for commit All prior checks · these links stay valid even if you push more commits. |
|
Just FYI for future @mentions, I'm Review in progress. Results will be posted as check runs when complete. |
ApprovabilityVerdict: Would Approve Documentation-only change adding a new concept guide for loadouts. No runtime behavior impact; the author owns the added file. Macroscope would have approved this PR. Enable approvability here. |
Loadouts are a session-plane feature, and tasks run through both `min run` and `mip run`, so naming only `mip` as the task runner over-attributed task execution to the advanced build CLI. Drop the `mip` naming and keep the accurate loadouts-apply-to-sessions-not- task-sandboxes contrast. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Note that hook execution is not yet wired up, state that conflicting values fail activation, show the default-loadout legend line in the ls sample, and use bare home-relative patch dests to match the reference schema. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Per review: flag the feature up front instead of the stale trailing note. After #975 loadout-declared hooks are excluded from composition entirely, so the old 'composed and recorded' wording was wrong too. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/concepts/loadouts.md`:
- Around line 48-50: Update the fenced code blocks in the loadouts
documentation, including the referenced ranges, with appropriate language
identifiers to resolve MD040. For command examples, remove shell prompt
characters or include representative command output to resolve MD014 while
preserving the documented commands and examples.
- Around line 117-134: Clarify the lifecycle-hook documentation so composition
and the complete hook example are explicitly described as planned behavior only.
Update the “Hooks from every applied loadout concatenate” statement and the
related example near the lifecycle-hooks section to remain consistent with the
existing “Coming soon” notice, without implying hooks currently execute.
- Around line 32-35: Update the loadout composition description in the relevant
concepts section to match the activation flow: state that the CLI reads and
composes the project contribution with applied loadouts before submitting the
resulting configuration to the daemon. Remove claims that the daemon performs
the merge, and preserve the documented no-override, peer-composition behavior
for conflicts.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e32cd0f6-cf1e-46ee-bc31-0a668a34d5c3
📒 Files selected for processing (1)
docs/concepts/loadouts.md
| Both feed the same session, and the daemon merges them into one final | ||
| configuration when the session comes up. The project contribution and every | ||
| applied loadout compose together as peers: there is no override precedence, | ||
| so a loadout adds to the project rather than silently replacing parts of it. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Keep composition ownership consistent with the activation flow.
This paragraph says the daemon merges project and loadout configuration, but the activation section says the CLI reads and composes loadouts before contacting the daemon. Document one authoritative model—preferably client-side composition followed by daemon submission—to avoid misleading users about conflict handling and runtime behavior.
Also applies to: 171-174
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/concepts/loadouts.md` around lines 32 - 35, Update the loadout
composition description in the relevant concepts section to match the activation
flow: state that the CLI reads and composes the project contribution with
applied loadouts before submitting the resulting configuration to the daemon.
Remove claims that the daemon performs the merge, and preserve the documented
no-override, peer-composition behavior for conflicts.
| ``` | ||
| ~/.config/minimal/loadouts/<name>.toml | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Resolve the supplied markdownlint warnings.
Add language identifiers to the unlabeled fenced blocks, and either remove $ prompts or show representative output for command examples. The supplied static-analysis results report MD040 and MD014 violations in these ranges.
Also applies to: 166-169, 185-187, 216-230
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 48-48: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/concepts/loadouts.md` around lines 48 - 50, Update the fenced code
blocks in the loadouts documentation, including the referenced ranges, with
appropriate language identifiers to resolve MD040. For command examples, remove
shell prompt characters or include representative command output to resolve
MD014 while preserving the documented commands and examples.
Source: Linters/SAST tools
| ### Lifecycle hooks | ||
|
|
||
| > **Coming soon.** Lifecycle hooks are not yet live: a hook declared in a | ||
| > loadout is accepted, but the current release excludes it from composition | ||
| > and nothing executes it. The declaration format below is what will ship. | ||
|
|
||
| Hooks are scripts declared to run at session transition points: `on_activate` | ||
| when the session comes up, `on_destroy` when it is torn down, and `on_failure` | ||
| when activation fails. Declare them to warm a cache, fetch grammars, or clean | ||
| up after a failed start: | ||
|
|
||
| ```toml | ||
| [[lifecycle_hooks]] | ||
| description = "warm the grammar cache" | ||
| on_activate = { type = "inline", value = "hx --grammar fetch >/dev/null 2>&1 || true" } | ||
| ``` | ||
|
|
||
| Hooks from every applied loadout concatenate in declaration order. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Qualify lifecycle-hook composition as future behavior.
Lines 119–121 correctly state that hooks are currently ignored, but lines 134 and 155–159 present hook concatenation and the complete example as active behavior. Move the concatenation rule into a “planned behavior” note or explicitly state that it applies only after hooks are implemented.
Also applies to: 155-159
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/concepts/loadouts.md` around lines 117 - 134, Clarify the lifecycle-hook
documentation so composition and the complete hook example are explicitly
described as planned behavior only. Update the “Hooks from every applied loadout
concatenate” statement and the related example near the lifecycle-hooks section
to remain consistent with the existing “Coming soon” notice, without implying
hooks currently execute.
New concept guide at
docs/concepts/loadouts.mdcovering what a loadout is versus the project'sminimal.toml, where loadouts live, the four things they carry (packages, vars, patches, lifecycle hooks, all applied in-session), applying viamin activate --loadout, auto-applying via[loadouts].default_loadouts, and listing viamin loadout ls. The../reference/loadouts.mdcross-link resolves once #868 merges;./sessions.mdresolves once the sessions concept guide merges. Verification done: no em-dashes, no harness/profile terms, repo-relative.mdlinks,mincommands checked against crates/minimal/src/lib.rs.Note
Add loadouts concept guide to documentation
Adds loadouts.md, a new conceptual guide explaining loadouts as per-developer, session-level configuration bundles. Covers what loadouts can carry (packages, variables with inherit/default, file patches, lifecycle hooks), how to apply them via CLI flags (
--loadout,--no-loadouts) anddefault_loadoutsin client config, and how to list them withmin loadout ls.Changes since #940 opened
Macroscope summarized 8adca38.
Summary by CodeRabbit