Skip to content

feat(min)!: re-parent session verbs under the session noun - #1008

Merged
norrietaylor merged 1 commit into
mainfrom
feat/min-session-provider-nouns
Jul 29, 2026
Merged

feat(min)!: re-parent session verbs under the session noun#1008
norrietaylor merged 1 commit into
mainfrom
feat/min-session-provider-nouns

Conversation

@norrietaylor

@norrietaylor norrietaylor commented Jul 29, 2026

Copy link
Copy Markdown
Member

Breaking change to the min command surface. Second slice of the
<noun> <verb> sweep started by #976, which did the mip package half.

Old → new

Old New
min activate min session activate
min attach min session attach
min destroy min session destroy
min rename min session rename
min session policy (unchanged, already noun-first)

Unchanged by deliberate decision, and commented in the source as exceptions so
a later reader does not "fix" them:

  • min with no subcommand — resolve-or-activate-and-attach, the most common
    thing anyone does with the CLI
  • min ls — the highest-traffic command; the break is not worth the consistency
  • min stop — acts on the daemon backend rather than any session, and is the
    daemon-lifecycle command people reach for
  • min init, min add, min update — passthroughs to the mip commands of
    the same name; keeping the spelling identical across the two CLIs beats the
    hierarchy

Nouns accept singular and plural as a visible alias: session/sessions,
loadout/loadouts.

The convention is written down

docs/reference/cli.md gains a Command naming convention section: the
<noun> <verb> rule, singular/plural aliasing, verbs shared across nouns
rather than owned by one, and a table of the documented exceptions above. This
is the part that stops the convention being re-derived from the command tree
every time someone adds a command.

Verification

Check Result
just ci (darwin scope) green — 521 tests, doctests ok
just e2e (VM-backed session e2e over HVF) green — cold activate, warm min ls, sandbox proof (pty attach + min add jq + run)
cargo build -p minimal green
cargo clippy -p minimal green (the sandbox2 dead-code findings are pre-existing on darwin — identical on clean main)

just e2e is the check that matters here: scripts/session-e2e.sh drives the
renamed commands for real, so it proves the re-parenting end to end.

Not verifiable on macOS, left to CI: the crates/minimald call-site updates
(the crate does not build on darwin).

Callers swept

scripts/session-e2e.sh, scripts/bulk-upload-e2e.sh,
scripts/stress-session-e2e.sh, scripts/e2e-attach-pty.py,
scripts/kernel-bump-review.sh, justfile, crates/mctx, crates/minimald,
crates/op, crates/sessions, AGENTS.md, README.md, and the docs tree.

Out of scope

  • Renaming the runnable unit defined in minimal.toml (sandbox vs session
    vs task) — still undecided, and it gates the shape of the run path.

Note for reviewers

An earlier revision of this branch introduced a provider noun, making
min provider stop the long form with min stop as a shortcut. That has been
dropped: stop stays a plain top-level command. There is no provider noun.

Refs: #1005

🤖 Generated with Claude Code

Note

Re-parent session verbs under min session noun in the CLI

  • Session lifecycle commands (activate, attach, destroy, rename, policy) are moved from top-level min <verb> to min session <verb> (with sessions as a visible alias); ls and stop remain at the top level.
  • All error messages, docs, scripts, and generated config comments are updated to reference the new min session ... forms.
  • Behavioral Change: the old top-level verbs (min activate, min attach, etc.) are no longer recognized; callers must use the new min session <verb> form.

Macroscope summarized f79f504.

Summary by CodeRabbit

  • New Features / CLI Updates
    • Session management commands now use the consistent min session ... format (activate, attach, rename, destroy), with corresponding help and error guidance updated when session arguments are omitted or ambiguous.
  • Documentation
    • Updated guides, references, examples, and generated configuration/comment text to use min session activate/min session attach everywhere, plus added CLI command naming convention documentation and clarified top-level exceptions.
  • Tests
    • Updated CLI and diagnostic tests to match the corrected min session ... command wording.

@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Session lifecycle commands are routed under min session, with CLI messaging, tests, scripts, examples, generated output, and documentation updated to use the namespaced forms.

Changes

Session CLI migration

Layer / File(s) Summary
Session command routing and messages
crates/minimal/src/*, crates/minimal/tests/*, crates/diagnostics/src/*
Session lifecycle variants dispatch through Command::Session; related help text, errors, diagnostics, and tests use min session ....
Session script and recipe updates
scripts/*, justfile
End-to-end, stress, bulk-upload, PTY, and development recipes invoke namespaced session commands.
CLI naming and reference documentation
docs/reference/cli.md, docs/reference/cli-min.md
References define the noun-verb convention, document session commands, and identify top-level exceptions.
User guides and command examples
README.md, docs/*, crates/op/project/init.rs, crates/sessions/example_project/minimal.toml, AGENTS.md
User-facing examples, generated TOML comments, and operational guidance use min session activate and min session attach.
Daemon and persistence references
crates/minimald/*, crates/sessions/*
Daemon messages and composition documentation refer to the namespaced activation flow.

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

Possibly related issues

Possibly related PRs

Suggested reviewers: twitchyliquid64

Poem

A rabbit hops through session light,
Renaming commands neat and right.
Attach, activate, destroy too,
Now every path knows what to do.
The docs all sing, “A new route!” 🐇

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 conventional, concise, and accurately summarizes the main breaking change.
Description check ✅ Passed The description is detailed and covers the change, verification, and caveats, so it mostly satisfies the template.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

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

@norrietaylor norrietaylor changed the title feat!(min): re-parent session verbs under session and provider nouns feat(min)!: re-parent session verbs under session and provider nouns Jul 29, 2026
@norrietaylor
norrietaylor force-pushed the feat/min-session-provider-nouns branch from b25b803 to 3efe3b7 Compare July 29, 2026 01:36
@norrietaylor norrietaylor changed the title feat(min)!: re-parent session verbs under session and provider nouns feat(min)!: re-parent session verbs under the session noun Jul 29, 2026
@norrietaylor
norrietaylor force-pushed the feat/min-session-provider-nouns branch from 1690f6b to f7b06d9 Compare July 29, 2026 04:24

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 7

🤖 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/loadouts.md`:
- Around line 166-169: Update the console examples in the loadouts
documentation, including both affected command blocks, to remove the `$` prompt
prefixes since they contain no output. Keep the commands themselves unchanged
and ensure the resulting Markdown passes the MD014 lint rule.

In `@docs/concepts/sessions.md`:
- Around line 67-69: Update the affected console examples in sessions.md,
including the block containing “min session activate --attach,” to remove $
prompt prefixes when no output is shown, or add representative output; ensure
all listed command blocks satisfy markdownlint-cli2 MD014.

In `@docs/guide/agents.md`:
- Around line 20-23: Update the shell command block in the agents guide to
resolve MD014 by removing the leading “$” prompts from both commands, or add
representative command output; preserve the existing commands and their
ordering.

In `@docs/guide/dev-shell.md`:
- Line 14: Remove the leading “$” prompts from the command-only shell fences in
dev-shell.md, including the command around “min session activate --attach .” and
the additionally referenced commands, while preserving them as shell commands
without adding output.

In `@docs/guide/setup.md`:
- Line 2: Update the guide description metadata to reference `min session
activate --attach .` instead of the non-attaching activation command, matching
the documented entry flow while preserving the existing setup summary.

In `@docs/reference/cli-min.md`:
- Line 58: Update the fenced command blocks in the CLI documentation at the
listed locations to specify a language, using shell for commands and console
where output is shown, so every newly added fence satisfies markdownlint MD040.

In `@docs/reference/cli.md`:
- Around line 29-33: Update the command examples in the “Command naming
convention” section to remove the undocumented “min completions install” example
or replace it with a documented noun/verb command, while preserving the
convention explanation and remaining valid examples.
🪄 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: 65c31f85-66c9-4f7a-a90f-4d92d96c1e1a

📥 Commits

Reviewing files that changed from the base of the PR and between d8c2f47 and f7b06d9.

📒 Files selected for processing (32)
  • AGENTS.md
  • README.md
  • crates/diagnostics/src/procs.rs
  • crates/minimal/src/attach.rs
  • crates/minimal/src/lib.rs
  • crates/minimal/src/prompt.rs
  • crates/minimal/tests/cli.rs
  • crates/minimald/src/server.rs
  • crates/minimald/src/session.rs
  • crates/minimald/src/store.rs
  • crates/op/src/project/init.rs
  • crates/sessions/docs/COMPOSITION.md
  • crates/sessions/example_project/minimal.toml
  • crates/sessions/src/core/compose.rs
  • crates/sessions/src/store.rs
  • crates/sessions/src/wire/request.rs
  • docs/concepts/loadouts.md
  • docs/concepts/sessions.md
  • docs/guide/agents.md
  • docs/guide/dev-shell.md
  • docs/guide/setup.md
  • docs/reference/cli-min.md
  • docs/reference/cli.md
  • docs/reference/linux-host-setup.md
  • docs/reference/loadouts.md
  • docs/reference/minimal-dot-toml.md
  • justfile
  • scripts/bulk-upload-e2e.sh
  • scripts/e2e-attach-pty.py
  • scripts/kernel-bump-review.sh
  • scripts/session-e2e.sh
  • scripts/stress-session-e2e.sh

Comment thread docs/concepts/loadouts.md
Comment thread docs/concepts/sessions.md
Comment thread docs/guide/agents.md
Comment thread docs/guide/dev-shell.md
Comment thread docs/guide/setup.md
Comment thread docs/reference/cli-min.md
Comment thread docs/reference/cli.md Outdated
Move activate, attach, destroy, and rename under the session noun,
continuing the <noun> <verb> sweep that #976 started with mip package.

min ls, min stop, bare min, and the init/add/update passthroughs stay
top-level as deliberate ergonomic exceptions, commented as such in the
source so a later reader does not "fix" them. stop in particular acts on
the daemon backend rather than any session. Nouns gain a visible
singular/plural alias.

Documents the convention itself in docs/reference/cli.md, so it is not
re-derived from the command tree every time someone adds a command.

BREAKING CHANGE: min activate, min attach, min destroy and min rename
are now min session activate, min session attach, min session destroy
and min session rename.

Refs: #1005

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@norrietaylor
norrietaylor force-pushed the feat/min-session-provider-nouns branch from f7b06d9 to f79f504 Compare July 29, 2026 04:31

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 2

🤖 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/guide/agents.md`:
- Around line 25-27: Update the session command guidance near the `min session
attach -c` documentation to enumerate all supported non-interactive command
paths: `min run <task>`, `min package build [args...]`, `min check [args...]`,
and the internal `git-receive-pack min://` path. Replace the claim that only
`min run` is accepted while preserving the instruction to launch the agent from
an attached shell for interactive use.

In `@docs/reference/cli-min.md`:
- Around line 17-23: Update the command-convention section in the CLI reference
to explicitly list bare “min dirs”, “min bug”, “min version”, and “min
completions” as deliberate standalone exceptions, while preserving the existing
noun/verb convention and previously documented exceptions.
🪄 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: 7c026af3-092f-480f-a157-41bfb4e7eb7f

📥 Commits

Reviewing files that changed from the base of the PR and between f7b06d9 and f79f504.

📒 Files selected for processing (32)
  • AGENTS.md
  • README.md
  • crates/diagnostics/src/procs.rs
  • crates/minimal/src/attach.rs
  • crates/minimal/src/lib.rs
  • crates/minimal/src/prompt.rs
  • crates/minimal/tests/cli.rs
  • crates/minimald/src/server.rs
  • crates/minimald/src/session.rs
  • crates/minimald/src/store.rs
  • crates/op/src/project/init.rs
  • crates/sessions/docs/COMPOSITION.md
  • crates/sessions/example_project/minimal.toml
  • crates/sessions/src/core/compose.rs
  • crates/sessions/src/store.rs
  • crates/sessions/src/wire/request.rs
  • docs/concepts/loadouts.md
  • docs/concepts/sessions.md
  • docs/guide/agents.md
  • docs/guide/dev-shell.md
  • docs/guide/setup.md
  • docs/reference/cli-min.md
  • docs/reference/cli.md
  • docs/reference/linux-host-setup.md
  • docs/reference/loadouts.md
  • docs/reference/minimal-dot-toml.md
  • justfile
  • scripts/bulk-upload-e2e.sh
  • scripts/e2e-attach-pty.py
  • scripts/kernel-bump-review.sh
  • scripts/session-e2e.sh
  • scripts/stress-session-e2e.sh
🚧 Files skipped from review as they are similar to previous changes (21)
  • crates/minimald/src/store.rs
  • docs/reference/minimal-dot-toml.md
  • scripts/e2e-attach-pty.py
  • docs/reference/cli.md
  • crates/sessions/example_project/minimal.toml
  • crates/minimal/src/prompt.rs
  • justfile
  • crates/minimald/src/server.rs
  • crates/sessions/src/store.rs
  • crates/op/src/project/init.rs
  • crates/minimald/src/session.rs
  • crates/sessions/src/wire/request.rs
  • scripts/stress-session-e2e.sh
  • crates/sessions/docs/COMPOSITION.md
  • docs/reference/loadouts.md
  • crates/minimal/tests/cli.rs
  • docs/guide/setup.md
  • crates/diagnostics/src/procs.rs
  • scripts/bulk-upload-e2e.sh
  • scripts/session-e2e.sh
  • crates/minimal/src/lib.rs

Comment thread docs/guide/agents.md
Comment on lines 25 to +27
Claude Code launches inside the session with your project's source code and a read-only system containing the `claude-code` binary and core utilities from `base`. The session has no additional access to anything on your host system unless you explicitly declare it.

Note that sessions are driven interactively: attaching needs a terminal, and the non-interactive `min attach -c` channel accepts only `min run <task>` invocations. Launch the agent from inside an attached shell as shown above, rather than scripting it from the host.
Note that sessions are driven interactively: attaching needs a terminal, and the non-interactive `min session attach -c` channel accepts only `min run <task>` invocations. Launch the agent from inside an attached shell as shown above, rather than scripting it from the host.

Copy link
Copy Markdown

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 all supported attach -c command paths.

This currently says the non-interactive channel accepts only min run <task>, but the daemon also accepts min package build [args...] and min check [args...] (plus the internal git-receive-pack min:// path). Update the guide so users are not incorrectly told that supported build/check automation is unavailable.

🤖 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/guide/agents.md` around lines 25 - 27, Update the session command
guidance near the `min session attach -c` documentation to enumerate all
supported non-interactive command paths: `min run <task>`, `min package build
[args...]`, `min check [args...]`, and the internal `git-receive-pack min://`
path. Replace the claim that only `min run` is accepted while preserving the
instruction to launch the agent from an attached shell for interactive use.

Comment thread docs/reference/cli-min.md
Comment on lines +17 to +23
Commands are spelled `min <noun> <verb>`, and every noun accepts its singular
and plural form (`session`/`sessions`, `provider`/`providers`,
`loadout`/`loadouts`). Bare `min` and a handful of bare verbs (`ls`, `stop`,
`init`, `add`, `update`) survive at the top level as deliberate ergonomic
exceptions, called out as such below; see
[the CLI convention](./cli.md#command-naming-convention) for the rule and the
full list of exceptions.

Copy link
Copy Markdown

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 the remaining standalone commands.

This section claims the min <noun> <verb> convention and lists the full exceptions, but this file also documents bare min dirs, min bug, min version, and min completions. Either scope the convention to the command families it governs or explicitly document these standalone commands as exceptions.

🤖 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/cli-min.md` around lines 17 - 23, Update the
command-convention section in the CLI reference to explicitly list bare “min
dirs”, “min bug”, “min version”, and “min completions” as deliberate standalone
exceptions, while preserving the existing noun/verb convention and previously
documented exceptions.

@norrietaylor
norrietaylor enabled auto-merge (squash) July 29, 2026 04:46
@norrietaylor
norrietaylor merged commit 3dd92ad into main Jul 29, 2026
29 checks passed
@norrietaylor
norrietaylor deleted the feat/min-session-provider-nouns branch July 29, 2026 05:19
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