Repository navigation
docs(reference): add a glossary of user-facing terms - #3258
norrietaylor wants to merge 3 commits into
Conversation
One word per thing, one line each. Box is the user-facing word; the glossary is the one place that ties it to the min session commands.
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: trueFinishing Touches
|
| | Word | Meaning | | ||
| |------|---------| | ||
| | **box** | An isolated place where you and your agent work on one project. It has only the tools your `minimal.toml` and your loadouts declare. You manage boxes with the `min session` commands. | | ||
| | **sandbox** | The operating-system isolation that a box runs in. On macOS, and on Linux with `--provider local-minvmd`, that is a microVM. Otherwise it is a Linux user namespace. | |
There was a problem hiding this comment.
sandbox is not in our domain model. box host is better
| | **package** | A tool that Minimal builds or fetches by content hash, such as `git` or `claude`. Packages come from the upstream. | | ||
| | **upstream** | The package registry a project reads from, pinned to one commit by `[upstream]` in `minimal.toml`. | | ||
| | **stack** | How a project builds, such as `rust` or `pnpm`, set by `[stack]` in `minimal.toml`. | | ||
| | **task** | A command declared in `minimal.toml` that runs once in its own sandbox and exits, such as a build or a test run. | |
There was a problem hiding this comment.
definition is wrong.
|
Review failed at none of the 3 personas completed; nothing to fold Comment |
Takes its terms from the gominimal/arch glossary (Box, Box Type, Box Spec, entry, Minimal Registry, Box Host, Box Provider), limited to what the CLI ships today. One heading per term, so pages can link to the one definition.
min box exec replaces min session exec, and local replaces local-minimald (BCLI-042, BCLI-046).
There was a problem hiding this comment.
Read at b56dbd2, each term's claim checked against the CLI on main rather than the architecture it was taken from, since the page says "limited to what the CLI ships today".
Every claim that names a command, a spelling or a path holds. min box exec, min box spec, min box list, min box attach and min box rm are the verbs on main. The network modes print as none, host_ip and own_ip (the NetworkMode words), which is what the page says. Loadouts resolve under <config dir>/loadouts, so ~/.config/minimal/loadouts/ is right for a default config dir. local and local-minvmd are the provider names --provider takes. [stack] and [upstream] are the tables minimal.toml reads.
The shape is right. One heading per term gives the other pages one anchor each (glossary.md#box-spec), and leaving out what does not ship yet keeps the page true as the CLI stands, with the architecture's glossary as the page it will grow from.
Two notes, neither blocking:
- "A Box Type ... never grants more" is the constraint rule (T23, merged as #3292: a derived type only narrows), so it is true today; worth keeping an eye on when the admission check (T24, #3312) lands, so the page and the daemon say the same thing.
- "On macOS, and under
--provider local-minvmdon Linux, the box runs inside a microVM" is right; the quickstart (#3259) says "macOS (Apple Silicon)", and this page does not say the architecture, which is fine for a glossary.
What
Adds
docs/reference/glossary.mdand lists it indocs/reference/manifest.json.The terms come from the glossary of record in gominimal/arch (
architecture.md§ Glossary), limited to what the CLI ships today:sessionandtasktypes, exec, Box Spec, network modeminimal.toml, entry, loadout, stackEach term gets its own heading, so a page links to the single definition (
glossary.md#box-spec) and doesn't restate it.Left out because they don't ship yet: the agent, service, build and container-build types, Box Volume, Loadout Mode, secrets, the Box Egress Proxy, and the Gatehouse terms. They get added when the CLI exposes them.
Why
User feedback on the docs: they use "different words to describe the same thing". The user docs say session about 684 times and box 211 times, plus environment, dev shell and workspace.
The arch model settles this. A box is the thing, and session is one Box Type. The glossary uses only those words and says that you manage interactive boxes with
min sessiontoday.This is the first step of a docs restructure. A command-first quickstart is in a stacked PR, and short task guides plus a structure lint follow.
Verification
just lint-prose docs/reference/glossary.md: 0 alerts.docs/reference/cli-min.md.manifest.json.