docs(concepts): add the sessions concept guide by norrietaylor · Pull Request #939 · gominimal/minimal

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

New user-facing concept guide for Minimal sessions (provider/session model, activation/attach, composition from project config plus loadouts, lifecycle, and the session/sandbox/task relationship). Cross-links to ../reference/cli-min.md and ./loadouts.md currently dangle and resolve once #863/#868 (loadouts) and the CLI reference land. Verification done: no em-dashes, no "harness"/"profile", no private-repo name, repo-relative .md links, every min command exists in the CLI.

Note

Add sessions concept guide to Minimal documentation

Adds sessions.md, a new concept guide covering the Minimal sessions model. The guide explains the provider architecture (minimald, minvmd), session lifecycle commands (min activate, min attach, min ls, rename, destroy, stop), composition from project config and loadouts, and the relationship between sessions, sandboxes, and tasks.

Changes since #939 opened

Clarified sandbox composition and lifecycle mechanics including when composition occurs, workspace mounting, environment setup, persistence across detach/reattach cycles, and task execution behavior [da0354f]
Updated session attachment and detachment behavior descriptions including interactive shell mechanics, workspace persistence, and git push workflow [da0354f]
Restricted non-interactive command execution to only accept min run <task name> invocations via --command/-c flag, requiring arbitrary commands to use an interactive shell [da0354f]
Clarified provider stop behavior regarding running shells, session persistence, re-hosting, and force flag requirements [da0354f]
Updated composition section to include lifecycle hooks in loadouts and clarified file patch timing and hook execution status [da0354f]
Updated CLI flag documentation and examples for min activate including --attach and --no-prompt behavior [da0354f]
Reframed sessions as durable environments that persist in the background after detaching rather than temporary sandboxed places, while maintaining isolation guarantees that host resources remain invisible unless explicitly allowed [b7e0fee]
Added documentation introducing loadouts as personal tooling that affects interactive shells without contaminating project environments [b7e0fee]
Documented platform-specific networking limitations for activation networking, specifying unsupported configurations on Linux and macOS [b7e0fee]
Clarified that lifecycle hooks are inert in the current release, with project-declared hooks composed but never executed and loadout-declared hooks excluded from composition [b7e0fee]
Updated min stop command description to indicate it stops the active provider rather than specifically minimald, with sessions persisting across provider restarts [b7e0fee]

^{Macroscope summarized f31e6f3.}

Summary by CodeRabbit

Documentation
- Added a new guide for Minimal “sessions” as durable, isolated developer environments.
- Documented how to create and manage sessions, including activation and attach/detach behavior.
- Explained session composition from loadouts and contributions, plus how tasks run within sessions.
- Covered user policy approval flow and session lifecycle commands.
- Linked to the relevant CLI reference and loadouts documentation.

Author a user-facing concept guide for Minimal sessions: what a session is and why, the provider/session model, creating and entering one, composition from project config plus loadouts, lifecycle, and how sessions relate to sandboxes and tasks. Grounded in the min CLI surface and the architecture docs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

📝 Walkthrough

Walkthrough

Adds a documentation page defining Minimal sessions, providers, activation and attachment, composition and policy handling, lifecycle commands, and the relationship between sessions, sandboxes, and tasks.

Changes

Sessions documentation

Layer / File(s)	Summary
Session model and providers `docs/concepts/sessions.md`	Defines sessions, isolation and reproducibility, provider responsibilities, and `minimald`/`minvmd` implementations.
Activation and composition `docs/concepts/sessions.md`	Documents `min activate`, attachment, composition from loadouts and configuration, and client-enforced policy approvals.
Lifecycle and related concepts `docs/concepts/sessions.md`	Documents session management commands, session/sandbox/task relationships, and related references.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

gominimal/minimal#863: Adds related session CLI behavior and configuration reference documentation.

Suggested reviewers: twitchyliquid64

Poem

A rabbit hops through sessions bright,
With loadouts packed and policies right.
min activate opens the door,
Sandboxes bloom on every floor.
Lifecycle commands keep paths clear—
Documentation carrots for every ear!

🚥 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 is concise, conventional, and accurately summarizes the main change: adding the sessions concept guide.
Description check	✅ Passed	The description is mostly complete and explains the guide well, though it doesn't use the template's Testing and Checklist headings.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

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

The command channel accepts only mi 8000 n run invocations, project files are an uploaded workspace copy (git push min:// brings changes back), lifecycle hook execution is not yet wired, provider stop keeps session records, and the sandbox persists across detach. Also covers detach explicitly and drops the redundant trailing path from the activate example, per review. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

coderabbitai

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/sessions.md`:
- Around line 196-204: Update the `min stop` documentation to describe stopping
the active provider rather than calling `minimald` the provider daemon. Use
platform-neutral wording throughout this paragraph, and mention that `minimald`
or `minvmd` may be the provider implementation only where needed to clarify the
distinction.
- Around line 7-11: Revise the session terminology throughout this guide,
including the definition and the sections around the later
session-versus-sandbox references, so a session is consistently described as the
durable provider-managed object. Describe the sandbox as the execution and
isolation context that the session owns or launches, and remove wording that
presents the session itself as the sandbox or explicitly denies that
relationship.
- Around line 61-62: Update the command examples in sessions.md, including the
min activate --attach block and the additional cited examples, to resolve MD014
by removing shell prompts and using command fences or adding representative
output. Keep the commands and documentation meaning unchanged so markdownlint
passes.

🪄 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: f91f5446-1b11-40c6-81ae-97a5dd9a887b

📥 Commits

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

📒 Files selected for processing (1)

docs/concepts/sessions.md

twitchyliquid64

LGTM caveat comments

- mention detach in the intro - introduce loadouts in 'Why sessions' as the personal-tooling vector - note loadouts contribute to the shell, never to tasks - make session-vs-sandbox terminology consistent (session = durable environment; sandbox = execution context) - describe current networking caveats: own-ip unavailable on the native Linux provider, macOS host-net outbound-only - correct the lifecycle-hooks status after #975: project hooks composed but never executed, loadout hooks excluded from composition - platform-neutral wording for min stop Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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

twitchyliquid64 reviewed Jul 23, 2026

View reviewed changes