docs(concepts): lift the supply-chain, sandboxing, packages, and stacks guides by norrietaylor · Pull Request #938 · gominimal/minimal

norrietaylor · 2026-07-23T19:46:19Z

Lifts four concept guides into docs/concepts/: software-supply-chain, sandboxing, packages (the content-addressed package model), and stacks (renamed from harnesses, all harness/profile wording retired). Links converted to repo-relative .md; minimal <cmd> corrected to mip per the clap definitions. Cross-links to ../reference/stack-specs.md and ../reference/cli-mip.md currently dangle and resolve once #863 (and the per-binary CLI reference pages) merge. Verification done: no em-dashes, no harness/profile mentions, no private-repo names, all internal links repo-relative.

Note

Add concepts documentation for supply chain, sandboxing, packages, stacks, and profiles

Adds five new Markdown pages under docs/concepts/ covering core Minimal concepts:

software-supply-chain.md: explains the layered supply chain model, upstream linkage via minimal.toml, and how software is expressed as configuration
sandboxing.md: details the sandbox model for tasks and hermetic package builds, including input wiring, /state, pinhole mappings, and network access rules
packages.md: covers package definition, caching by spec hash, hermetic builds, and sideloading from other repositories
stacks.md: documents available stacks, auto-detection via mip init, and declaring build/runtime dependencies
profiles.md: explains profile inheritance across supply chain layers, global defaults, and per-task overrides

Changes since #938 opened

Updated terminology in documentation comments and descriptions [30adac9]
Added documentation for session sandbox composition and workspace initialization [ff5a61c]
Clarified configuration layer inheritance rules and profile extension behavior [ff5a61c]
Updated package presence scope for stacks and profiles [ff5a61c]
Enhanced cleanroom sandbox isolation documentation and local build instructions [ff5a61c]
Generalized task sandbox filesystem mapping documentation [ff5a61c]
Updated locked_commit documentation to reflect min update behavior [ff5a61c]
Updated dependency addition guidance to use min add flags [ff5a61c]
Corrected initialization command from mip init to min init [ff5a61c]
Clarified stack documentation regarding registry source and task inheritance [ff5a61c]

^{Macroscope summarized 3d8b938.}

…ks guides Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-07-23T19:46:26Z

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 51 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5c30bd5d-bcd8-4db3-b6c6-00ae13f8dd61

📥 Commits

Reviewing files that changed from the base of the PR and between 7fd582e and ff5a61c.

📒 Files selected for processing (5)

docs/concepts/packages.md
docs/concepts/profiles.md
docs/concepts/sandboxing.md
docs/concepts/software-supply-chain.md
docs/concepts/stacks.md

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

…sh prose

twitchyliquid64 · 2026-07-23T22:24:33Z

+You can force the CLI to build artifacts locally using a combination of the `--no-fetch` and `--no-cache` flags.
+
+
+## The task sandbox


Should we mention the session sandbox here? Its the sandbox you drop into when you use a session, the union of [session] and [stack] stuff in your minimal.toml as well as your loadout.

twitchyliquid64 · 2026-07-23T22:25:12Z

+ - The repository's files and directories, from the repository root downward, but not above it.
+ - A `/state` directory, which can be shared between tasks and task invocations by specifying a task `state_key`. Package managers
+   are typically wired to cache source downloads and intermediate build artifacts in this directory.
+ - Pinhole filesystem mappings, as declared by packages. For instance, the `claude-code` package wires the `~/.claude` directory into task sandboxes so claude-code


I think we can drop this one for now while we figure out what to do with [task.patches] sections

De-emphasize `mip` per review feedback: `min` is the primary product surface, while `mip` drives the advanced build plane. Qualify the stacks intro as a build-plane command and drop the `mip update` reference from the upstream config comment in favor of a tool-neutral phrasing, without changing the underlying mechanics. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Layers add definitions rather than override them (from_profile excepted), locked_commit is pinned by min update, the build cleanroom's network carve-out is stated, the claude-code pinhole example is dropped pending the task.patches decision, a session-sandbox section is added per review, profile packages are scoped to tasks, stack docs route dependency adds through min add, and the stacks table defers to the registry as source of truth. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(concepts): lift the supply-chain, sandboxing, packages, and stac…

4b73824

…ks guides Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(concepts): fix cache order, restore the profiles guide, and poli…

3d8b938

…sh prose

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

twitchyliquid64 reviewed Jul 23, 2026

View reviewed changes

twitchyliquid64 approved these changes Jul 23, 2026

View reviewed changes

norrietaylor and others added 2 commits July 23, 2026 15:40

norrietaylor merged commit bc91deb into main Jul 25, 2026
29 checks passed

norrietaylor deleted the pr/docs-concepts branch July 25, 2026 00:25

Navigation Menu

Repository navigation

docs(concepts): lift the supply-chain, sandboxing, packages, and stacks guides - #938

docs(concepts): lift the supply-chain, sandboxing, packages, and stacks guides#938
norrietaylor merged 4 commits into
mainfrom
pr/docs-concepts

norrietaylor commented Jul 23, 2026 •

edited by macroscopeapp Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 23, 2026 •

edited

Loading

Review limit reached

Uh oh!

twitchyliquid64 Jul 23, 2026

Uh oh!

twitchyliquid64 Jul 23, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		You can force the CLI to build artifacts locally using a combination of the `--no-fetch` and `--no-cache` flags.


		## The task sandbox

Conversation

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

Uh oh!

Add concepts documentation for supply chain, sandboxing, packages, stacks, and profiles

Changes since #938 opened

Uh oh!

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

Uh oh!

Review limit reached

Uh oh!

twitchyliquid64 Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

twitchyliquid64 Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

norrietaylor commented Jul 23, 2026 •

edited by macroscopeapp Bot

Loading

coderabbitai Bot commented Jul 23, 2026 •

edited

Loading