docs(reference): add the loadouts reference page by norrietaylor · Pull Request #868 · gominimal/minimal

norrietaylor · 2026-07-21T19:02:04Z

Adds docs/reference/loadouts.md (367 lines) — the loadouts reference page — and restores its manifest.json entry. This is the second half of the reference-docs work (WS8); the first half is #863.

Why it's separate / stacked on #863

The reference docs form a cyclic link graph centered on cli-mip.md, so a session/build split would leave dead links between merges. loadouts.md is the one clean fault line — a leaf (nothing links to it), so it split out cleanly. It links out to cli-min.md, cli-mip.md, minimal-dot-toml.md, and tasks.md; two of those live in #863, so this PR is based on pr/05-cli-reference to stay link-clean. I'll retarget it to main once #863 merges.

Verification

Links resolve against the docs(reference): add CLI command reference and config/spec pages #863 base + this page.
manifest.json valid; all 12 pages present (loadouts restored).
Scrub clean.

🤖 Generated with Claude Code

Note

Add loadouts reference page to documentation

Adds loadouts.md covering the Loadouts feature schema, config directory layout, CLI selection flags, client config keys, composition/conflict policy, and environment variable behavior in the attach shell. Also registers the new page in manifest.json.

Changes since #868 opened

Replaced terminology 'session sandbox' with 'session' throughout the loadouts reference documentation [bd69733]
Updated patch destination path format in examples from home-anchored to home-relative notation [bd69733]
Clarified destination path semantics for patches in loadouts configuration [bd69733]
Removed the 'Current limitations' note regarding patches and lifecycle hooks in the sandbox launcher [bd69733]
Updated platform config directory description to remove explicit macOS contrast [bd69733]
Refined path expansion and glob semantics for source and dest configuration fields in loadouts [0fe0e86]
Updated lifecycle hooks documentation to reflect current implementation status and composition behavior [0fe0e86]
Changed patches example to use glob pattern instead of explicit file list [0fe0e86]
Applied formatting corrections to front-matter and inline references [0fe0e86]

^{Macroscope summarized bf4e1b1.}

Add docs/reference/loadouts.md and restore its entry in the reference manifest. Split out from the CLI/config reference PR because loadouts is a leaf page: it links out to the CLI and config references but nothing links back to it, so deferring it kept both PRs under 1000 lines and link-clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-07-21T19:02:12Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 145cbbb4-4c72-4c11-bd97-e7b6ae5cb1c5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

_{Comment @coderabbitai help to get the list of available commands.}

evanspearman · 2026-07-22T15:45:55Z

+consistency with Minimal's state and cache dirs, not
+`~/Library/Application Support`. The global


We can probably omit the part about ~/Library/Application Support

Done in bd69733 — dropped the ~/Library/Application Support aside; the sentence now just states macOS uses $HOME/.config.

evanspearman · 2026-07-22T15:46:26Z

+> **Current limitations**: of the four things a loadout can contribute,
+> **packages** and **vars** take effect inside the session today. **Patches**
+> and **lifecycle hooks** are parsed, validated, and composed into the
+> session's configuration, but the session launcher does not yet apply them
+> inside the sandbox — the daemon holds them with the session and logs each
+> one as deferred. The schema below documents all four so files written
+> now stay valid as the remaining plumbing lands.
+


I would just remove this block. It will no longer be true by the time we GA

Done in bd69733 — removed the block. Consistent with patches/hooks being applied in-session by GA, so the deferred caveat would be stale.

evanspearman · 2026-07-22T15:48:26Z

+    { dest = "~/.config/helix/config.toml", source = "~/dotfiles/helix/config.toml" },
+    { dest = "~/.config/helix/languages.toml", source = "~/dotfiles/helix/languages.toml" },
+    { dest = "~/.config/helix/themes/", source = "~/dotfiles/helix/themes/**/*.toml" },
+
+    # Zellij: single config file plus a layouts directory.
+    { dest = "~/.config/zellij/config.kdl", source = "~/dotfiles/zellij/config.kdl" },
+    { dest = "~/.config/zellij/layouts/", source = "~/dotfiles/zellij/layouts/**/*.kdl" },


dest shouldn't have the ~/ dest is always relative to ~/.

Fixed in bd69733 — dropped the leading ~/ here and on every other dest example (helix/zellij/psqlrc/nvim). dest is resolved relative to $HOME, so it's redundant. Also reworded the dest prose at the bottom to match.

evanspearman · 2026-07-22T15:50:22Z

+```
+
+Names are not checked at activation: an unknown package composes cleanly
+and fails later, when the session sandbox first spawns, with


I think we decided to no longer use the term sandbox. I would just change this to "session"

Done in bd69733 — "session sandbox" → "session" here and at the schema note below. Left line 17's "task sandboxes (mip run)" as-is since that's the one-shot task environment, not the interactive session.

evanspearman · 2026-07-22T15:52:51Z

+    { dest = "~/.psqlrc", source = "~/dotfiles/psqlrc" },
+    { dest = "certs/",    source = ["~/ca/root.pem", "~/ca/dev.pem"] },
+    { dest = "~/.config/nvim/", source = "~/dotfiles/nvim/**/*.lua" },


Same comment with respect to leading ~/

Fixed in bd69733 (swept all dest examples).

evanspearman · 2026-07-22T15:54:22Z

+  dotfile tree the host may not have is safe. Other enumeration failures
+  (permission denied, unreadable entries) still fail the composition.
+
+**`dest`** is interpreted relative to the sandbox user's home directory; a


Leading ~/ should not be included.

Fixed in bd69733 — the prose now reads "interpreted relative to the session user's home directory" with no ~/ recommendation, and every example matches.

Replace prose em-dashes with context-appropriate punctuation (commas, colons, semicolons, and parentheses) throughout the loadouts reference. Wording and meaning are unchanged, including the deferred patches/hooks caveat; code blocks and verbatim output are untouched.

Drop the leading `~/` from every patch `dest` example: `dest` is always resolved relative to the session user's home, so the prefix is redundant. Remove the "Current limitations" deferred-patches/hooks block (it will be untrue by GA), omit the macOS `~/Library/Application Support` aside, and use "session" rather than "sandbox" for the interactive session context. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Note that hook execution is not yet wired up, replace the list-source certs example with a glob (same-dest list entries fail composition), correct dest semantics (verbatim path for literal sources, directory for globs), scope host-home expansion to the tilde prefix ($HOME resolves against session vars), quote the frontmatter description, and point task sandboxes at the Tasks page without naming the CLI. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

norrietaylor mentioned this pull request Jul 21, 2026

docs: rework README and add AGENTS.md and the docs landing page #871

Merged

evanspearman requested changes Jul 22, 2026

View reviewed changes

This was referenced Jul 23, 2026

docs(concepts): add the sessions concept guide #939

Merged

docs(concepts): add the loadouts concept guide #940

Merged

norrietaylor marked this pull request as ready for review July 23, 2026 21:45

norrietaylor and others added 2 commits July 23, 2026 14:53

norrietaylor merged commit 0c6204d into pr/05-cli-reference Jul 25, 2026
2 checks passed

norrietaylor deleted the pr/06-loadouts branch July 25, 2026 00:24

		consistency with Minimal's state and cache dirs, not
		`~/Library/Application Support`. The global

Uh oh!

Conversation

norrietaylor commented Jul 21, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why it's separate / stacked on #863

Verification

Add loadouts reference page to documentation

Changes since #868 opened

Uh oh!

coderabbitai Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

norrietaylor commented Jul 21, 2026 •

edited by macroscopeapp Bot

Loading

coderabbitai Bot commented Jul 21, 2026 •

edited

Loading