Repository navigation
docs(guide): lift the building, dev-shell, agents, tasks, and packages guides - #942
Conversation
📝 WalkthroughWalkthroughAdds five documentation guides covering package scopes, interactive sessions, AI agents, one-shot tasks, builds, tests, and persisted build state through ChangesMinimal usage guides
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
Comment |
…the package count Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The dev-shell and agent workflows are interactive development, which is the session plane (`min activate`), not the build plane (`mip run` on a `[tasks.x]` definition). Rewrite both guides around sessions: tools come from the project's `[session]` block (`packages`, `[session.vars]`, `patches`, `[[session.lifecycle_hooks]]`), you enter with `min activate --attach .`, and you add tools ad-hoc with the in-sandbox `min add`. Keep tasks and building on `mip` (they are genuinely build-plane, one-shot sandboxes) but add a sentence distinguishing them from interactive sessions and cross-link the dev-shell guide. Correct packages to route build/runtime deps through `mip add --build/--runtime` and session tools through `[session]`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sessions receive an uploaded project copy (git push min:// brings changes back), in-session min add also records the package in [session] packages, min destroy takes a session argument, mip test needs a [tasks.test] entry, the registry package is protobuf, build/runtime/task dependency adds route through min add, mip-driven one-shot sandboxes are marked Linux-only with session alternatives, session contents include loadout and stack packages, and agents.md notes the interactive-attach constraint. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
| [session] | ||
| packages = ["claude-code", "base"] | ||
| patches = [ | ||
| { source = "~/.claude", dest = "~/.claude" }, |
There was a problem hiding this comment.
I think this is an antipattern, as this copies like gb's of old working space. Maybe this can just be ~/.claude.json like in the pkg?
There was a problem hiding this comment.
I say we remove this entirely. This got added in the lift, which I missed, and I'm happy you caught it
|
|
||
| ```shell | ||
| $ min activate --attach . | ||
| $ claude |
There was a problem hiding this comment.
We have some issues with TERM not being set atm, do we want to say TERM=xterm claude --dangerously-skip-permissions or something equally verbose for now?
There was a problem hiding this comment.
Evan has said he will pull envs over. Unless that becomes risky lets keep it this way
| @@ -0,0 +1,72 @@ | |||
| --- | |||
| description: Run builds and tests in sandboxed environments using stacks. Covers extra dependencies, test commands, and build state persistence. | |||
There was a problem hiding this comment.
Happy to get this one in as-is, but hopefully with SOPs coming in hot we can switch this to entirely be using sessions / min
There was a problem hiding this comment.
Yup the goal is to remove mip from these docs
| [session] | ||
| packages = ["claude-code", "base", "git"] | ||
| patches = [ | ||
| { source = "~/.claude", dest = "~/.claude" }, |
| [session] | ||
| packages = ["claude-code", "base"] | ||
| patches = [ | ||
| { source = "~/.claude", dest = "~/.claude" }, |
There was a problem hiding this comment.
I say we remove this entirely. This got added in the lift, which I missed, and I'm happy you caught it
| @@ -0,0 +1,72 @@ | |||
| --- | |||
| description: Run builds and tests in sandboxed environments using stacks. Covers extra dependencies, test commands, and build state persistence. | |||
There was a problem hiding this comment.
Yup the goal is to remove mip from these docs
Patching the whole ~/.claude directory copies gigabytes of stale workspace state into the session. Removed from both examples per review. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (3)
docs/guide/packages.md (1)
54-56: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winRemove shell prompts from command-only snippets.
markdownlintreports MD014 because this block shows$ min add --task lint ruffwithout output. Remove the$prompt, or include representative output.🤖 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/packages.md` around lines 54 - 56, Update the command-only shell snippet in the package guide to remove the leading `$` prompt, preserving the command itself so it complies with markdownlint MD014.Source: Linters/SAST tools
docs/guide/agents.md (1)
20-23: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winRemove shell prompts from command-only snippets.
markdownlintreports MD014 because no command output is shown. Remove the$prefixes or add representative output.🤖 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 20 - 23, Update the command-only snippet in the agents guide by removing the `$` shell prompt prefixes from both commands; keep the commands themselves unchanged and do not add output.Source: Linters/SAST tools
docs/guide/dev-shell.md (1)
13-15: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winRemove shell prompts from command-only snippets.
markdownlintreports MD014 for these commands because no output is shown. Remove the$prefixes, or add representative output to each example.Also applies to: 45-47, 89-93
🤖 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/dev-shell.md` around lines 13 - 15, Remove the "$" shell prompt prefixes from the command-only snippets in the developer shell guide, including the examples around "min activate --attach ." and the referenced additional snippets, since they show no command output. Keep the commands otherwise unchanged.Source: Linters/SAST tools
🤖 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 38-56: Update the “Passing through host credentials” guidance and
examples to warn that exposing ~/.ssh, ~/.gitconfig, or inherited
ANTHROPIC_API_KEY grants direct access to host credentials. Recommend dedicated,
scoped session credentials instead, and document the associated trust, rotation,
and revocation implications before showing or endorsing these settings.
In `@docs/guide/building.md`:
- Line 14: Update the command examples in building.md, including the mip build
examples and the additional referenced blocks, to satisfy Markdownlint MD014:
remove the leading $ prompts from commands that show no output, or add
representative output where prompts should remain. Keep the examples clear and
consistent.
In `@docs/guide/tasks.md`:
- Line 52: Change the patches.dir."~/.config/railway" permission from read-write
to read-only by default, and document the security implications and any cases
where write access is explicitly required.
- Line 41: Update the documentation surrounding env_vars.GITHUB_TOKEN to warn
that inheriting the host token exposes credentials to all task commands,
including repository-controlled scripts. Clearly describe this trust boundary
and recommend using a scoped, short-lived token instead of ambient token
inheritance.
---
Nitpick comments:
In `@docs/guide/agents.md`:
- Around line 20-23: Update the command-only snippet in the agents guide by
removing the `$` shell prompt prefixes from both commands; keep the commands
themselves unchanged and do not add output.
In `@docs/guide/dev-shell.md`:
- Around line 13-15: Remove the "$" shell prompt prefixes from the command-only
snippets in the developer shell guide, including the examples around "min
activate --attach ." and the referenced additional snippets, since they show no
command output. Keep the commands otherwise unchanged.
In `@docs/guide/packages.md`:
- Around line 54-56: Update the command-only shell snippet in the package guide
to remove the leading `$` prompt, preserving the command itself so it complies
with markdownlint MD014.
🪄 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: 3401cc5b-f6ad-4fa8-8dc9-5a32be206635
📒 Files selected for processing (5)
docs/guide/agents.mddocs/guide/building.mddocs/guide/dev-shell.mddocs/guide/packages.mddocs/guide/tasks.md
| ## Running a build | ||
|
|
||
| ```shell | ||
| $ mip build |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the Markdownlint MD014 warnings.
These command examples use $ prompts without showing output. Remove the prompts or add representative output so the documentation passes commands-show-output.
Also applies to: 49-50, 58-58
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 14-14: Dollar signs used before commands without showing output
(MD014, commands-show-output)
🤖 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/building.md` at line 14, Update the command examples in
building.md, including the mip build examples and the additional referenced
blocks, to satisfy Markdownlint MD014: remove the leading $ prompts from
commands that show no output, or add representative output where prompts should
remain. Keep the examples clear and consistent.
Source: Linters/SAST tools
…xamples Per review: note that inherited env values and patched files are readable by everything in the sandbox, recommend scoped short-lived credentials, flip the railway patch example to read-only, and point at the activation policy gate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Lifts the five Start workflow pages into
docs/guide/(building, dev-shell, agents, tasks, packages), reframed around the two planes so each guide teaches the right tool:Session plane (
min):min activate --attach ., with tools from the project's[session]block (packages), host files via[session]patches, env via[session.vars], setup via[[session.lifecycle_hooks]], and ad-hoc mid-session installs via the in-sandboxmin add <pkg>. Session lifecycle covered withmin attach/min ls/min destroy.Build plane (
mip):mip build/mip test,[stack]) and tasks.md ([tasks.x],mip run) keep the build/task framing (genuinely one-shot sandboxes), each with a one-sentence session-vs-build distinction and a cross-link to dev-shell.mip add --build/--runtime->[stack], interactive dev tools through[session]packages(+min add), and task-scoped packages viamip add --task.De-numbered filenames, harness->stack, links repo-relative
.md; cross-links to../reference/*resolve once #863 and sibling docs-lift PRs merge. Session patches are{ source, dest }rows (dest home-relative in the session), not the task/harnesspatches.dirform. Verification: em-dash/min add --session/stale-mip shellscrub c 8000 lean.Note
Add guide pages for building, dev-shell, agents, tasks, and packages
Adds five new documentation pages to the guide covering core workflows:
mip buildandmip testwith stacks, including extra dependencies and state persistencemin, covering isolation, patches, env vars, and lifecycle hooksmin addflags andminimal.tomlmip runormin run, with examples for exec/bash, env vars, and host file mappingChanges since #942 opened
~/.claudehost state access configuration from agent setup instructions [5d39eca]Macroscope summarized 8a87911.
Summary by CodeRabbit
minimal.toml.state_key, and running tasks withmip run.patches.