Repository navigation
docs(readme): lead with status and quick start, make sandbox docs config-first - #62
Merged
Merged
Conversation
…fig-first Both entry documents buried what a new reader needs first. The README spent its first ~250 lines on sandbox and permission internals, and SANDBOX explained the sandbox layers before telling operators how to configure anything. - README.md: order sections by reader priority (positioning, Status And Focus, What Works, Quick Start, Configure, Use The CLI) and keep a short Sandbox And Permissions section that configures mode, approval policy, permissions, and host integrations before describing the boundary. - SANDBOX.md: move the sandbox and permission detail out of the README into a tracked document ordered Setup -> Configure -> How it works, so host prerequisites and configuration precede enforcement internals. No fact is dropped: AppArmor and kernel restrictions, mount plan and scanning bounds, enforcement, host integration reachability, SSH and GPG agent handling, capability retention, and permission review without a terminal are preserved. Verified with the repository link and anchor checker over both files (18 links, all resolving), balanced code fences, git diff --check, and a line-level comparison against the removed content.
10 of 12 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Both entry documents buried what a new reader needs first: the README spent its
first ~250 lines on sandbox and permission internals before saying what Merry is
and how to run it, and SANDBOX described the sandbox layers before telling
operators how to configure anything.
README.md now orders sections by reader priority:
The sandbox section keeps what a user actually configures (
[cli] sandbox,approval_policy,[permissions]network and path settings, host integrations),then summarizes the boundary in
### How The Boundary Worksand points toSANDBOX.md.
SANDBOX.md (new tracked file) takes the sandbox and permission detail that
used to live in the README, ordered
Setup -> Configure -> How it works:Setup- requirements, the built-in host probe, the Ubuntu 24.04+ bubblewrapAppArmor profile, and kernel restrictions.
Configure- sandbox mode, approval policy, permissions, host integrations.How it works- sandbox layers, mount plan and scanning bounds, enforcement,host integration reachability, SSH agent, GPG agent, capability retention, and
permission review without a terminal.
No fact was dropped; the removed README material was moved rather than deleted.
Why
Status, focus, and the Quick Start path are what a visitor needs first; sandbox
internals are reference material that belongs behind a link. Configuration
instructions also have to precede the explanation of the mechanism.
Verification
cross-file fragments such as
README.md#sandbox-and-permissionsand#ubuntu-2404-and-newer-the-bubblewrap-apparmor-profile.git diff --checkclean; only the two intended files are modified.HEADconfirmed every removedline is a rewording, a heading-level change, or a relocated sentence.
and Python suites were not run.
Notes
mainintegration in this repository is fast-forward-only; this branch is asingle commit on top of
main.