Skip to content

docs(reference): add CLI command reference and config/spec pages - #863

Merged
norrietaylor merged 6 commits into
mainfrom
pr/05-cli-reference
Jul 25, 2026
Merged

norrietaylor merged 6 commits into
mainfrom
pr/05-cli-reference

Conversation

@norrietaylor

@norrietaylor norrietaylor commented Jul 21, 2026 •

Copy link
Copy Markdown
Member

Fifth PR in the oss/integration decomposition — the CLI & config reference section (WS8, first half). Pure docs. 12 files, +779/−207.

What

  • Per-binary CLI reference: cli-min.md, cli-mip.md, cli-minimald.md, cli-minvmd.md, plus the cli.md overview.
  • Config & spec pages: minimal-dot-toml.md, tasks.md, build-specs.md, sandbox-operations.md, and the harness-specs.md → stack-specs.md rename.
  • manifest.json — the reference-page index.

Accuracy fix

Removed a stale "known issues" note in the mip reference that cited dump --stacks (todo!()) and patched-build --remote-addr. Both were since fixed (dump --stacks by #842) and their issues closed, so citing them as current known issues was inaccurate.

Verification

  • Links: every relative .md/.json link resolves; no danglers. Nothing in this set links to loadouts.md, so deferring it is clean.
  • Manifest: valid JSON; all 11 listed pages are present in this PR.
  • Scrub: no leaked emails/secrets/inbox refs.
  • Staleness handled: the branch's cli.md rewrite already omits the --hostpath-deps row that fix(mip): dump --stacks; remove the dead HostPath build dep variant #842 removed (no reversion); harness-specs has no lingering references.

Depends on nothing already merged; branches off current main. The loadouts page (367 lines) follows as PR6.

🤖 Generated with Claude Code

Note

Add CLI command reference pages and update config/spec docs for mip, min, minimald, and minvmd

Changes since #863 opened

  • Rewrote CLI reference documentation to clarify that min is the primary session CLI that communicates with minimald, which runs inside a microVM managed by minvmd on macOS and optionally on Linux, and positioned mip as an advanced Linux-only interface to the underlying declarative package and build engine [31995e8]
  • Updated the --gvproxy-bin flag description for the run command in the minimald CLI reference to indicate it is used for networking and defaults to a typical system install path [31995e8]
  • Modified the add operation documentation in sandbox operations to indicate packages are recorded as session, runtime, or build dependencies in minimal.toml based on flags, removed the --task flag, and updated the --session flag description to state it also adds packages to the [session] packages list [31995e8]
  • Replaced global CLI flag --minvmd with --provider <PROVIDER> and added --no-input flag across CLI reference documentation [d8f700d]
  • Added comprehensive documentation for [session], [params], [cache], and [stdlib] configuration sections in minimal.toml reference [d8f700d]
  • Updated min attach command to make SESSION parameter optional with automatic session resolution and interactive picker behavior [d8f700d]
  • Clarified canonical versus alias naming throughout configuration and task specifications [d8f700d]
  • Added echo action for tasks that prints a fixed string without composing a sandbox [d8f700d]
  • Updated runtime files and provider paths from legacy format to provider-based directory structure [d8f700d]
  • Documented min add command behavior differences between sessions and task sandboxes [d8f700d]
  • Added user namespaces disabled documentation for Linux host setup [d8f700d]
  • Updated bare min command behavior and auto-start exceptions in CLI reference [d8f700d]
  • Made type field optional with default oci-image in outputs configuration [d8f700d]
  • Refined patches path rule to require ~/ prefix for tilde expansion in task specifications [d8f700d]
  • Wrapped description values in quotes within YAML front matter across all reference documentation files [d8f700d]
  • Updated shell completion documentation wording from fixed list to include-based phrasing [d8f700d]
  • Removed known issues section related to run --timeout and --detach flags from minvmd CLI reference [d8f700d]
  • Updated known issues section to note --stdlib-dir flag is accepted but ignored in minimald CLI reference [d8f700d]
  • Added reference documentation for the loadouts feature covering schema definition, CLI interface, and configuration [0c6204d]
  • Registered the loadouts reference page in the documentation manifest [0c6204d]

Macroscope summarized bfaddc4.

Summary by CodeRabbit

  • Documentation
    • Added reference pages for the min session CLI, mip, minimald, and minvmd, plus a new loadouts guide.
    • Refreshed the CLI overview and expanded documentation for sandbox helper commands, tasks, stacks, build specifications, and minimal.toml.
    • Updated Linux host setup guidance with improved troubleshooting and added coverage for when user namespaces are disabled.
    • Updated the documentation reference manifest to include the new loadouts page.

@coderabbitai

coderabbitai Bot commented Jul 21, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

The documentation reorganizes CLI references around min, mip, minimald, and minvmd, adds loadout navigation, updates schema terminology and command names, expands sandbox operations, and revises Linux host setup guidance.

Changes

CLI and command references

Layer / File(s) Summary
CLI reference surfaces
docs/reference/cli.md, docs/reference/cli-min.md, docs/reference/cli-minimald.md, docs/reference/cli-minvmd.md
The overview separates session and package/build planes, while dedicated pages document binaries, flags, commands, daemon behavior, platform availability, and known issues.
Package and sandbox command references
docs/reference/cli-mip.md, docs/reference/sandbox-operations.md
References document mip package/build workflows and in-sandbox min commands, including validation, materialization, cache, dependency, shorthand, and completion behavior.

Schema and supporting documentation

Layer / File(s) Summary
Schema and task documentation
docs/reference/build-specs.md, docs/reference/minimal-dot-toml.md, docs/reference/stack-specs.md, docs/reference/tasks.md
Schema terminology, mip command links, field behavior, task arguments, examples, and stack references are updated.
Loadout reference and navigation
docs/reference/loadouts.md, docs/reference/manifest.json
Loadout files, schemas, activation selection, composition, policy, configuration, listing, and shell behavior are documented and the page is added to the reference manifest.
Linux host setup guidance
docs/reference/linux-host-setup.md
Front matter, namespace troubleshooting, AppArmor instructions, installation wording, deployment notes, and remediation guidance are revised.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

Possibly related PRs

Poem

I’m a rabbit with docs in my den,
Where mip and min guide us again.
Loadouts and stacks hop into place,
Daemons and schemas keep steady pace.
With carrots of clarity, pages now sing! 🐇

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly matches the main change: adding CLI reference and config/spec documentation pages.
Description check ✅ Passed The description is detailed and covers summary and verification, but it does not follow the template's explicit Testing and Checklist sections.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

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

Add the per-binary CLI reference (min, mip, minimald, minvmd) and the
reference manifest, and revise the config/spec pages: minimal.toml, tasks,
build specs, sandbox operations, the cli overview, and the harness-specs ->
stack-specs rename.

Drop a stale "known issues" note in the mip reference whose cited bugs
(dump --stacks and patched-build --remote-addr) were since fixed and their
issues closed. The loadouts reference page follows in a separate PR.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@norrietaylor norrietaylor changed the title docs(reference): CLI command reference and config/spec pages docs(reference): add CLI command reference and config/spec pages Jul 21, 2026
@norrietaylor
norrietaylor force-pushed the pr/05-cli-reference branch from 9b47593 to d6e7d25 Compare July 21, 2026 03:02
@norrietaylor
norrietaylor marked this pull request as ready for review July 21, 2026 15:59
@norrietaylor

Copy link
Copy Markdown
Member Author

@macroscope-app review

@macroscopeapp

macroscopeapp Bot commented Jul 21, 2026

Copy link
Copy Markdown

Manual reviews triggered for commit d6e7d25:

All prior checks · these links stay valid even if you push more commits.

@macroscopeapp

macroscopeapp Bot commented Jul 21, 2026

Copy link
Copy Markdown

Review in progress. Results will be posted as check runs when complete.

@norrietaylor

Copy link
Copy Markdown
Member Author

@coderabbitai ignore

@coderabbitai

coderabbitai Bot commented Jul 21, 2026

Copy link
Copy Markdown
Contributor
✅ Action performed

Reviews paused.

Comment thread docs/reference/cli-min.md Resolved
Comment thread docs/reference/cli-min.md Resolved
Comment thread docs/reference/cli-min.md Resolved
Comment thread docs/reference/cli-min.md Resolved
Comment thread docs/reference/sandbox-operations.md Resolved
@macroscopeapp

macroscopeapp Bot commented Jul 21, 2026

Copy link
Copy Markdown

Approvability

Verdict: Would Approve

Documentation-only changes adding CLI reference pages and updating existing docs. No runtime code changes. Open comments are minor doc accuracy issues that don't affect runtime behavior.

Macroscope would have approved this PR. Enable approvability here.

Comment thread docs/reference/cli-minimald.md Resolved
Comment thread docs/reference/cli-minvmd.md Resolved
…mpt, remove em-dashes

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 8

🤖 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/reference/cli-min.md`:
- Around line 8-11: Update the introductory description of the min CLI to state
that most commands automatically start minimald when it is not running, while
explicitly identifying the bug command as an exception. Keep the existing daemon
and session-management context unchanged.
- Line 30: Add language identifiers to every fenced code example in
docs/reference/cli-min.md, including the listed locations, using the appropriate
identifier such as console or shell so all fences satisfy markdownlint MD040.
- Around line 131-136: Update the environment-variable redaction behavior
described in the CLI documentation so sensitive-shaped names always take
precedence over the verbatim allowlist, including MINIMAL_*, MINVMD_*, and
MINIMALD_* variables. Restrict those prefixes to explicitly known-safe names or
state that sensitive-name filtering is applied after allowlist matching,
ensuring values such as MINIMAL_API_TOKEN are recorded by name only.

In `@docs/reference/cli-minimald.md`:
- Line 29: Add the console or shell language identifier to both fenced command
blocks in the CLI documentation, including the fences at the referenced
locations, so they comply with markdownlint MD040.
- Around line 21-22: Update the defaults documented for the --minimal-state-dir
and --minimal-cache-dir options to reference XDG_STATE_HOME and XDG_CACHE_HOME
respectively, keeping the existing option descriptions unchanged.

In `@docs/reference/cli-minvmd.md`:
- Line 26: Add a language identifier to every fenced command block in the CLI
documentation, including the blocks at all referenced locations. Use console or
shell consistently so markdownlint-cli2 MD040 passes.

In `@docs/reference/cli-mip.md`:
- Line 34: Add a console or shell language identifier to every fenced command
block in cli-mip.md, including the listed occurrences, while leaving the command
content unchanged.

In `@docs/reference/cli.md`:
- Around line 41-45: Update the “In-sandbox helper commands” overview in cli.md
to include build, test, and patched-pkg alongside add, search, check, and run,
or revise the wording to clearly indicate the listed commands are only examples;
keep the link to sandbox operations intact.
🪄 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: 93061e2b-d505-4a50-add4-30b1a3eda0bc

📥 Commits

Reviewing files that changed from the base of the PR and between 4bfdcb0 and 57dd6d1.

📒 Files selected for processing (12)
  • docs/reference/build-specs.md
  • docs/reference/cli-min.md
  • docs/reference/cli-minimald.md
  • docs/reference/cli-minvmd.md
  • docs/reference/cli-mip.md
  • docs/reference/cli.md
  • docs/reference/linux-host-setup.md
  • docs/reference/manifest.json
  • docs/reference/minimal-dot-toml.md
  • docs/reference/sandbox-operations.md
  • docs/reference/stack-specs.md
  • docs/reference/tasks.md

Comment thread docs/reference/cli-min.md Resolved
Comment thread docs/reference/cli-min.md Resolved
Comment thread docs/reference/cli-min.md Resolved
Comment thread docs/reference/cli-minimald.md Resolved
Comment thread docs/reference/cli-minimald.md Resolved
Comment thread docs/reference/cli-minvmd.md Resolved
Comment thread docs/reference/cli-mip.md Resolved
Comment thread docs/reference/cli.md Resolved
…acies

Remove commands that are feature-gated or not yet ready to expose, and
correct several inaccuracies against the source:

- min: drop the session policy, login, and feature-gated mesh/ssh-forward
  sections
- min: note that most commands auto-start the daemon while bug does not,
  and that the daemon runs inside the minvmd microVM host on macOS
- min/mip: add requires at least one package, so show <PACKAGES>...
- minimald: default state/cache dirs are $XDG_STATE_HOME / $XDG_CACHE_HOME,
  not $XDG_*_DIR; drop the not-yet-exposed --num-parallel-builds flag
- minvmd: document the run "start" alias and distinguish boot from run

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Comment thread docs/reference/cli-minimald.md Resolved
Comment thread docs/reference/cli-mip.md Outdated

# `mip` - package/build CLI

`mip` is the Minimal package/build CLI. It reads a project's

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should probably mention that mip stands for "Minimal in-process", it only works on Linux, and its meant for advanced users only

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done — cli-mip.md now opens with "mip (short for 'Minimal in-process')" plus a callout that it's Linux-only and for advanced users driving the package/build plane directly, pointing readers to the min session CLI. 31995e8

Comment thread docs/reference/cli.md Resolved
Comment thread docs/reference/sandbox-operations.md Resolved
Comment thread docs/reference/sandbox-operations.md Resolved
norrietaylor and others added 2 commits July 23, 2026 15:34
De-emphasize `mip` across the CLI reference: `min` is the primary
surface, and `mip` is marked as the advanced, Linux-only package/build
CLI (with its "Minimal in-process" name spelled out). Correct the
in-sandbox `min add` flags: `--session` records packages in the
`[session]` list in `minimal.toml`, and drop `--task`, which is not
available in session sandboxes. Simplify the `--gvproxy-bin` description.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the removed --minvmd flag with --provider local-minvmd, make attach's
SESSION optional with its resolution rules and the min-run-only exec channel,
list the real autostart exceptions, correct provider directory names, drop
dead known-issue links (the minvmd --timeout one is fixed on main), document
bare min and --no-input, and regenerate the help SHAs against main. Add the
missing [session] section (plus [params], [cache], [stdlib]) to the
minimal.toml reference, drop the phantom ty alias, retarget the dead
harnesses concept link, and rename the {#harness} anchor to {#stack}. Fix
tasks.md's invalid multi-line inline tables, document the echo action, and
correct alias directions. Scope sandbox-operations add semantics per backend
(session no-flag records in [session] packages). Cover the
max_user_namespaces preflight case in linux-host-setup. Quote colon-bearing
frontmatter descriptions across the reference set.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@norrietaylor
norrietaylor enabled auto-merge (squash) July 25, 2026 00:26

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)
docs/reference/minimal-dot-toml.md (1)

212-214: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Include the env_vars alias in the raw-file validation rule.

The preceding field definition documents env_vars as an alias for vars, but this rejection rule mentions only vars. State that both vars and env_vars are invalid for raw-file outputs.

🤖 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/reference/minimal-dot-toml.md` around lines 212 - 214, Update the
raw-file validation rule in the documentation to explicitly list both vars and
its env_vars alias as invalid oci-image-only fields, while preserving the
existing entrypoint, cmd, and path restrictions.
docs/reference/linux-host-setup.md (1)

64-72: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Do not state that installing the profile does not weaken the host.

The profile intentionally leaves minimald unconfined and grants it the userns permission. It does not alter the host-wide setting or affect unrelated binaries, but it does expand the permissions available to minimald; the current wording understates that security tradeoff. Ubuntu documents this as an additional permission that reduces the restriction for the profiled application. (discourse.ubuntu.com)

Suggested wording
-Installing it neither sandboxes minimald nor weakens the host.
+It does not sandbox minimald or change the host-wide setting; it grants only minimald a named profile with the userns permission.
🤖 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/reference/linux-host-setup.md` around lines 64 - 72, Revise the AppArmor
profile explanation in the section describing `flags=(unconfined)` to remove the
claim that installing it does not weaken the host. State that the profile leaves
`minimald` unconfined and grants it `userns`, expanding permissions for that
application while not changing host-wide settings or affecting unrelated
binaries.
🤖 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/reference/linux-host-setup.md`:
- Around line 105-111: Update the “User namespaces disabled entirely” section to
include kernel.unprivileged_userns_clone as an additional check and remediation,
covering hosts where it is set to 0 alongside CONFIG_USER_NS and
user.max_user_namespaces. If the troubleshooting guidance cannot support this
case, explicitly narrow the section’s scope to the two existing failure modes.

In `@docs/reference/loadouts.md`:
- Around line 24-26: Add an explicit language identifier to both fenced code
blocks in the loadouts documentation: use text for the path example and text or
console for the loadout-list output. Keep the existing fenced content unchanged.

In `@docs/reference/minimal-dot-toml.md`:
- Line 75: Update the sideload documentation example and heading to use
[[upstream.sideloads]] as the primary syntax, and identify [[upstream.sideload]]
only as the accepted compatibility alias.
- Line 3: Update the front-matter description for the minimal.toml reference so
it reflects all documented schema sections, including session, params, cache,
and stdlib, while retaining the existing sections or replacing the list with
accurate broader wording.
- Around line 96-101: Update the primary stack example to use the canonical
`name = "<stack name>"` key instead of `use`. Retain `use` only in the
surrounding documentation as a deprecated compatibility alias, consistent with
the `[stack]` guidance.

---

Outside diff comments:
In `@docs/reference/linux-host-setup.md`:
- Around line 64-72: Revise the AppArmor profile explanation in the section
describing `flags=(unconfined)` to remove the claim that installing it does not
weaken the host. State that the profile leaves `minimald` unconfined and grants
it `userns`, expanding permissions for that application while not changing
host-wide settings or affecting unrelated binaries.

In `@docs/reference/minimal-dot-toml.md`:
- Around line 212-214: Update the raw-file validation rule in the documentation
to explicitly list both vars and its env_vars alias as invalid oci-image-only
fields, while preserving the existing entrypoint, cmd, and path restrictions.
🪄 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: bbff121e-d4ff-4723-bbec-79d9a8372e16

📥 Commits

Reviewing files that changed from the base of the PR and between 57dd6d1 and 0c6204d.

📒 Files selected for processing (13)
  • docs/reference/build-specs.md
  • docs/reference/cli-min.md
  • docs/reference/cli-minimald.md
  • docs/reference/cli-minvmd.md
  • docs/reference/cli-mip.md
  • docs/reference/cli.md
  • docs/reference/linux-host-setup.md
  • docs/reference/loadouts.md
  • docs/reference/manifest.json
  • docs/reference/minimal-dot-toml.md
  • docs/reference/sandbox-operations.md
  • docs/reference/stack-specs.md
  • docs/reference/tasks.md
🚧 Files skipped from review as they are similar to previous changes (9)
  • docs/reference/manifest.json
  • docs/reference/cli-min.md
  • docs/reference/build-specs.md
  • docs/reference/cli-minvmd.md
  • docs/reference/cli.md
  • docs/reference/tasks.md
  • docs/reference/cli-mip.md
  • docs/reference/sandbox-operations.md
  • docs/reference/stack-specs.md

Comment on lines +105 to +111
## User namespaces disabled entirely

Separately from the AppArmor restriction, a kernel built without
`CONFIG_USER_NS`, or a host with `user.max_user_namespaces` set to `0`, cannot
create user namespaces at all. The daemon's preflight reports this as its own
error. The fix is distribution-specific: raise `user.max_user_namespaces` via
sysctl, or use a kernel with user namespaces enabled.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Document kernel.unprivileged_userns_clone as an additional gate.

Some Linux distributions also disable unprivileged user namespaces with kernel.unprivileged_userns_clone=0. Hosts with that setting will produce the same failure but are not covered by this troubleshooting section. Add it to the checks/remediation, or explicitly scope the section to the two supported failure modes. (gitlab.com)

🤖 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/reference/linux-host-setup.md` around lines 105 - 111, Update the “User
namespaces disabled entirely” section to include
kernel.unprivileged_userns_clone as an additional check and remediation,
covering hosts where it is set to 0 alongside CONFIG_USER_NS and
user.max_user_namespaces. If the troubleshooting guidance cannot support this
case, explicitly narrow the section’s scope to the two existing failure modes.

Comment on lines +24 to +26
```
<config>/minimal/loadouts/<name>.toml
```

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add language identifiers to both fenced blocks.

The path example and loadout-list output fences trigger markdownlint MD040. Mark them as text or console.

Proposed fix
-```
+```text
 <config>/minimal/loadouts/<name>.toml>

- +text
NAME DESCRIPTION CONTRIBUTES

  • dev helix + zellij with my dotfiles 2 pkg / 4 var / 5 patch / 1 hook
    extra 1 pkg / 0 var / 0 patch / 0 hook
    @@
  • default (from [loadouts].default_loadouts)

Also applies to: 288-294

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 24-24: 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/reference/loadouts.md` around lines 24 - 26, Add an explicit language
identifier to both fenced code blocks in the loadouts documentation: use text
for the path example and text or console for the loadout-list output. Keep the
existing fenced content unchanged.

Source: Linters/SAST tools

---
description: Schema reference for the minimal.toml configuration file — upstream, stack, defaults, tasks, and outputs sections.
title: minimal.toml
description: "Schema reference for the minimal.toml configuration file: upstream, stack, defaults, tasks, and outputs sections."

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Keep the front-matter description synchronized with the documented schema.

The page now documents [session], [params], [cache], and [stdlib], but the description lists only upstream, stack, defaults, tasks, and outputs. Update it to include the new sections or use broader wording.

🤖 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/reference/minimal-dot-toml.md` at line 3, Update the front-matter
description for the minimal.toml reference so it reflects all documented schema
sections, including session, params, cache, and stdlib, while retaining the
existing sections or replacing the list with accurate broader wording.

are built using the version of packages from your upstream.

Each sideload entry is loaded in order from the specified repository, and follows the same schema as `[upstream]`:
Each sideload entry is loaded in order from the specified repository, and follows the same schema as `[upstream]` (the canonical table name is `sideloads`; `sideload` is an accepted alias):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Use the canonical sideload table name in the example.

This text says sideloads is canonical while the heading and example use [[upstream.sideload]]. If the singular form is only an accepted alias, show [[upstream.sideloads]] as the primary syntax and label the singular form as compatibility syntax.

🤖 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/reference/minimal-dot-toml.md` at line 75, Update the sideload
documentation example and heading to use [[upstream.sideloads]] as the primary
syntax, and identify [[upstream.sideload]] only as the accepted compatibility
alias.

Comment on lines +96 to 101
The `[stack]` section configures the [stack](https://docs.minimal.dev/concepts/stacks) to use for building code, if any.
See [stack specs](./stack-specs.md) for how stacks themselves are defined.

`[harness]` is accepted as a deprecated alias for `[stack]`, pending removal after
`use` is an accepted alias for the canonical `name` key; both parse. `[harness]`
is accepted as a deprecated alias for `[stack]`, pending removal after
July 2026; prefer `[stack]` in new configs.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Use the canonical name key in the primary stack example.

The prose identifies name as canonical but the example above still uses use. Change the example to name = "<stack name>" and document use only as the deprecated/compatibility alias.

🤖 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/reference/minimal-dot-toml.md` around lines 96 - 101, Update the primary
stack example to use the canonical `name = "<stack name>"` key instead of `use`.
Retain `use` only in the surrounding documentation as a deprecated compatibility
alias, consistent with the `[stack]` guidance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants