Skip to content

docs(readme): lead with status and quick start, make sandbox docs config-first - #62

Merged
locez merged 1 commit into
mainfrom
docs/readme-sandbox-restructure
Sep 20, 2026
Merged

locez merged 1 commit into
mainfrom
docs/readme-sandbox-restructure

Conversation

@locez

@locez locez commented Sep 20, 2026

Copy link
Copy Markdown
Owner

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:

positioning + two design promises -> Status And Focus -> What Works
-> Quick Start -> Configure -> Use The CLI -> Sandbox And Permissions
-> Multi-Tool Execution -> Embed Merry -> Verify -> Documentation

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 Works and points to
SANDBOX.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+ bubblewrap
    AppArmor 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

  • Link and anchor checker over both files: 18 links, all resolving, including
    cross-file fragments such as README.md#sandbox-and-permissions and
    #ubuntu-2404-and-newer-the-bubblewrap-apparmor-profile.
  • Code fences balanced in both files (36 and 16 markers).
  • git diff --check clean; only the two intended files are modified.
  • Line-level comparison of the new files against HEAD confirmed every removed
    line is a rewording, a heading-level change, or a relocated sentence.
  • Docs-only change: neither file is read by tests or build scripts, so the Rust
    and Python suites were not run.

Notes

main integration in this repository is fast-forward-only; this branch is a
single commit on top of main.

…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.
@locez
locez merged commit 14dce6d into main Sep 20, 2026
8 checks passed
@locez
locez deleted the docs/readme-sandbox-restructure branch September 20, 2026 05:33
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.

1 participant