docs: rework README and add AGENTS.md and the docs landing page - #871
Conversation
📝 WalkthroughWalkthroughChangesRepository documentation refresh
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 |
dcb120e to
b5bacfc
Compare
b5bacfc to
7685cad
Compare
| Apply one with `min activate --loadout dev --attach .`, or list it in | ||
| `default_loadouts` in `~/.config/minimal/config.toml` to have it join every | ||
| session automatically. `min loadout list` shows what's available. The full |
There was a problem hiding this comment.
🟡 Medium README.md:181
The README instructs users to set default_loadouts as a top-level key in ~/.config/minimal/config.toml, but the client schema requires it under the [loadouts] table ([loadouts].default_loadouts) and rejects unknown top-level keys. Following the documented instruction produces an invalid config file, so automatic loadouts never activate. Correct the path so the documented key matches the schema.
| Apply one with `min activate --loadout dev --attach .`, or list it in | |
| `default_loadouts` in `~/.config/minimal/config.toml` to have it join every | |
| session automatically. `min loadout list` shows what's available. The full | |
| Apply one with `min activate --loadout dev --attach .`, or list it in | |
| `default_loadouts` under `[loadouts]` in `~/.config/minimal/config.toml` to have it join every | |
| session automatically. `min loadout list` shows what's available. The full |
🚀 Reply "fix it for me" or copy this AI Prompt for your agent:
In file @README.md around lines 181-183:
The README instructs users to set `default_loadouts` as a top-level key in `~/.config/minimal/config.toml`, but the client schema requires it under the `[loadouts]` table (`[loadouts].default_loadouts`) and rejects unknown top-level keys. Following the documented instruction produces an invalid config file, so automatic loadouts never activate. Correct the path so the documented key matches the schema.
There was a problem hiding this comment.
I'm working on the fix to correct the default_loadouts configuration path in the README.
There was a problem hiding this comment.
The README.md already contains the correct instruction. Lines 176-177 specify: "list it in default_loadouts under [loadouts] in ~/.config/minimal/config.toml" — the "[loadouts]" table specification is already present.
|
Addressed the review — force-pushed.
@macroscopeapp — all six confirmed and fixed:
Also swapped the Discord badge to the permanent invite. One consistency note for a follow-up (not in this round): AGENTS.md's orientation still uses the "build plane / session plane" framing, whereas #858 reframed architecture.md to core-internals vs product-surface. Happy to align AGENTS.md too if you want. |
7685cad to
418c059
Compare
|
@macroscopeapp confirmed and fixed — AGENTS.md's macOS clippy scope now reads |
418c059 to
a8c7b20
Compare
a8c7b20 to
e2bab22
Compare
Expand README.md with the launch content (pitch, install, getting-started walkthroughs, loadouts, contributing/CLA/security). Add AGENTS.md as the tool-neutral, canonical agent/contributor orientation (crate map, platform matrix, justfile recipes, footguns, CI lane map, hard rules), and reduce CLAUDE.md to an @AGENTS.md include. Add the repo assets (logo marks, favicon, loadout demo). Prose uses minimal em-dashes throughout. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
47ad379 to
69eca6e
Compare
…ocs-site (#882) Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
There was a problem hiding this comment.
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/public/loadout-demo.cast`:
- Around line 61-68: Update the recorded commands and output around the EDITOR
demonstration in loadout-demo.cast so the demo uses and resolves EDITOR to "hx",
matching the documented dev loadout configuration; replace the displayed "vim"
value while preserving the surrounding terminal recording.
In `@README.md`:
- Line 245: Update the contributor instructions in the ICLA paragraph to
hyphenate the compound modifier as “~30-second step,” while preserving the
surrounding wording and meaning.
- Around line 205-214: Update the README build-summary text around the `just ci`
and binary-output descriptions to match the platform matrix: state that Linux
`just ci` includes `test-ignored`, clarify that macOS does not build `minimald`,
and avoid presenting the four binaries as universally available.
🪄 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: 9ac0198e-986f-437f-a33e-38e8c9d3ee51
⛔ Files ignored due to path filters (4)
docs/public/favicon.svgis excluded by!**/*.svgdocs/public/loadout-demo.gifis excluded by!**/*.gifdocs/public/minimal-mark-dark.svgis excluded by!**/*.svgdocs/public/minimal-mark-light.svgis excluded by!**/*.svg
📒 Files selected for processing (4)
AGENTS.mdCLAUDE.mdREADME.mddocs/public/loadout-demo.cast
| [7.966, "o", "E"] | ||
| [8.028, "o", "D"] | ||
| [8.07, "o", "I"] | ||
| [8.14, "o", "T"] | ||
| [8.184, "o", "O"] | ||
| [8.249, "o", "R"] | ||
| [8.699, "o", "\r\n"] | ||
| [9.049, "o", "vim\r\n"] |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Align the demo with the documented dev loadout.
README.md configures EDITOR = "hx", but this recording shows EDITOR resolving to vim. Following the README therefore does not reproduce the demo.
Suggested fix
- [9.049, "o", "vim\r\n"]
+ [9.049, "o", "hx\r\n"]📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| [7.966, "o", "E"] | |
| [8.028, "o", "D"] | |
| [8.07, "o", "I"] | |
| [8.14, "o", "T"] | |
| [8.184, "o", "O"] | |
| [8.249, "o", "R"] | |
| [8.699, "o", "\r\n"] | |
| [9.049, "o", "vim\r\n"] | |
| [7.966, "o", "E"] | |
| [8.028, "o", "D"] | |
| [8.07, "o", "I"] | |
| [8.14, "o", "T"] | |
| [8.184, "o", "O"] | |
| [8.249, "o", "R"] | |
| [8.699, "o", "\r\n"] | |
| [9.049, "o", "hx\r\n"] |
🤖 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/public/loadout-demo.cast` around lines 61 - 68, Update the recorded
commands and output around the EDITOR demonstration in loadout-demo.cast so the
demo uses and resolves EDITOR to "hx", matching the documented dev loadout
configuration; replace the displayed "vim" value while preserving the
surrounding terminal recording.
| just ci # the full pre-PR gate: fmt, clippy, cargo-deny, tests, doctests | ||
| just test # run the test suite | ||
| just clippy # lint | ||
| ``` | ||
|
|
||
| `just --list` shows every recipe (builds, VM bring-up, e2e, and more). On | ||
| Linux you can also drive Cargo directly against the whole workspace | ||
| (`cargo build`, `cargo test`); on macOS prefer the recipes so you never have | ||
| to scope crates by hand. Binaries land at | ||
| `target/debug/{min,mip,minimald,minvmd}` (or `target/release/`). Building the |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Keep the build summary aligned with the platform matrix.
On Linux, just ci also runs test-ignored; on macOS, minimald does not build. The current “full pre-PR gate” and four-binary output wording can mislead macOS users.
Suggested wording
-just ci # the full pre-PR gate: fmt, clippy, cargo-deny, tests, doctests
+just ci # pre-PR gates; also runs ignored tests on Linux
...
-Binaries land at `target/debug/{min,mip,minimald,minvmd}` (or `target/release/`).
+On Linux, binaries land at `target/debug/{min,mip,minimald,minvmd}` (or
+`target/release/`); macOS produces only the darwin-capable targets.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| just ci # the full pre-PR gate: fmt, clippy, cargo-deny, tests, doctests | |
| just test # run the test suite | |
| just clippy # lint | |
| ``` | |
| `just --list` shows every recipe (builds, VM bring-up, e2e, and more). On | |
| Linux you can also drive Cargo directly against the whole workspace | |
| (`cargo build`, `cargo test`); on macOS prefer the recipes so you never have | |
| to scope crates by hand. Binaries land at | |
| `target/debug/{min,mip,minimald,minvmd}` (or `target/release/`). Building the | |
| just ci # pre-PR gates; also runs ignored tests on Linux | |
| just test # run the test suite | |
| just clippy # lint | |
| `just --list` shows every recipe (builds, VM bring-up, e2e, and more). On | |
| Linux you can also drive Cargo directly against the whole workspace | |
| (`cargo build`, `cargo test`); on macOS prefer the recipes so you never have | |
| to scope crates by hand. On Linux, binaries land at | |
| `target/debug/{min,mip,minimald,minvmd}` (or `target/release/`); macOS produces only the darwin-capable targets. Building the |
🤖 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 `@README.md` around lines 205 - 214, Update the README build-summary text
around the `just ci` and binary-output descriptions to match the platform
matrix: state that Linux `just ci` includes `test-ignored`, clarify that macOS
does not build `minimald`, and avoid presenting the four binaries as universally
available.
| ### Contributor License Agreement | ||
|
|
||
| Before we can merge your first pull request, you'll need to accept our **Individual Contributor License Agreement (ICLA)**. This is a one-time, ~30 second step: [CLA Assistant](https://cla-assistant.io/) will post a link on your PR, you click through, sign in with GitHub, and you're done — you're then covered for all future contributions to this repository. | ||
| Before we can merge your first pull request, you'll need to accept our **Individual Contributor License Agreement (ICLA)**. This is a one-time, ~30 second step: [CLA Assistant](https://cla-assistant.io/) will post a link on your PR, you click through, sign in with GitHub, and you're done. You're then covered for all future contributions to this repository. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Hyphenate the compound modifier.
Use “one-time, ~30-second step” for correct user-facing prose.
Suggested fix
-This is a one-time, ~30 second step:
+This is a one-time, ~30-second step:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Before we can merge your first pull request, you'll need to accept our **Individual Contributor License Agreement (ICLA)**. This is a one-time, ~30 second step: [CLA Assistant](https://cla-assistant.io/) will post a link on your PR, you click through, sign in with GitHub, and you're done. You're then covered for all future contributions to this repository. | |
| Before we can merge your first pull request, you'll need to accept our **Individual Contributor License Agreement (ICLA)**. This is a one-time, ~30-second step: [CLA Assistant](https://cla-assistant.io/) will post a link on your PR, you click through, sign in with GitHub, and you're done. You're then covered for all future contributions to this repository. |
🧰 Tools
🪛 LanguageTool
[grammar] ~245-~245: Use a hyphen to join words.
Context: ...eement (ICLA)**. This is a one-time, ~30 second step: [CLA Assistant](https://cla...
(QB_NEW_EN_HYPHEN)
🤖 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 `@README.md` at line 245, Update the contributor instructions in the ICLA
paragraph to hyphenate the compound modifier as “~30-second step,” while
preserving the surrounding wording and meaning.
Source: Linters/SAST tools
Following the CI-lane cleanup, remove the docs-site build tooling that no longer applies: the Node/`npm run docs:build` system dependency and the `docs-check` recipe (there is no VitePress site or docs-check recipe on main). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
|
||
| The executables inside a sandbox (git, claude-code, compilers, shells, and more) are delivered by Minimal's secure package manager from a curated registry that is refreshed daily. Because packages are addressed by content rather than mutable version tags and builds are hermetic, the same blueprint resolves to the same environment on every machine. Moving the whole team to the freshest tool versions is one `min update`, which re-pins the blueprint in place. No more stale setup wikis, no more version drift. | ||
|
|
||
| Per-developer Loadouts then layer each person's own editors, terminal multiplexers, and configs on top of that shared toolchain, so the environment stays identical for everyone while you keep the muscle memory you have earned. |
Repo-root docs for the OSS launch (WS4 + WS9). 8 files.
What
README.md— reworked into the launch README: pitch, supported platforms, install, two getting-started walkthroughs, loadouts, tech stack, building/testing (via thejustrecipes), contributing + CLA + security.AGENTS.md(new) — the tool-neutral, canonical orientation for agents and contributors: crate map, platform matrix, justfile recipes, footguns, CI lane map, and the hard rules (frozen workflows, Conventional Commits,just ci).CLAUDE.md— reduced to@AGENTS.md, so there's one source of truth.docs/public/*— repo assets: the logo marks and loadout-demo gif used by the README, plusfavicon.svgand the demo.castsource (both docs-site assets — can move to the scaffold PR if preferred).Style
Prose uses minimal em-dashes — all replaced with commas, colons, parentheses, or periods.
Merge order (top of the docs stack)
This references files that live in the other open docs PRs and the docs-site scaffold, so it should merge after them:
README.md→docs/reference/loadouts.md(docs(reference): add the loadouts reference page #868)AGENTS.md→docs/reference/cli-*.md(docs(reference): add CLI command reference and config/spec pages #863),docs/internal/release-pipeline.md(docs: document the release and install pipeline #867)AGENTS.mddocs-site instructions (npm ci,just docs-check, thedocs-sitelane) → the VitePress scaffold + rootpackage.json(VitePress PR) and the docs-site workflow (CI PR)Links to files already on
main(architecture, commit-conventions, coding-standards) resolve today.Excluded
docs/index.md(the VitePress landing page) belongs with the scaffold PR, not here.docs/rust-coding-standards.mdis owned by docs: architecture v2, internal maintainer docs, and error-handling guide #858 (ADR-link retarget + backtick formatting).🤖 Generated with Claude Code
Note
Rework README and add AGENTS.md contributor orientation document
@AGENTS.mdinclude.Macroscope summarized c67224d.
Summary by CodeRabbit