Skip to content

Simplify README to four sections - #440

Merged
evandowning merged 4 commits into
mainfrom
worktree-readme-simplify
Sep 1, 2026
Merged

Simplify README to four sections#440
evandowning merged 4 commits into
mainfrom
worktree-readme-simplify

Conversation

@evandowning

Copy link
Copy Markdown
Contributor

Reduces README.md from 189 to 84 lines, leaving four sections: setup and updating, usage, development, and documentation.

What changed

  • Setup and updating — the install script or a source build, coop setup, and a short paragraph on coop update and the background update check, linking to the full flag reference.
  • Usage — the quick-start flow (coop up, then coop claude or coop codex) and the bypass-permissions note, linking to the command reference.
  • Development — the build, lint, test, and integration commands, linking to CONTRIBUTING.md and docs/testing.md. This section is new; the README previously had no contributor entry point.
  • Documentation — the existing documentation link list, plus the docs index, architecture, trust model, contributing guide, and security policy.

Removed: the feature list, the 30-row command table, the coop update flag table, the release-verification walkthrough, and the requirements section. Each duplicated a document that remains the system of record — docs/commands.md, docs/configuration.md, docs/getting-started.md, and docs/trust-model.md. Nothing in the repository linked to a README anchor this change deletes.

Supporting edits

docs/getting-started.md gains an Install section carrying the install-script one-liner and the manual gh attestation verify instructions, which previously lived only in the README.

CONTRIBUTING.md linked to README.md#requirements, an anchor this change removes; it now points at docs/getting-started.md#prerequisites.

Setup accuracy fix

Writing the condensed setup section surfaced a claim that was wrong on macOS. coop setup installs a runtime and fetches a guest kernel only on the Firecracker backend (src/setup.rs). The Lima path (src/lima.rs) does neither — it fails outright when limactl is missing, telling the reader to run brew install lima. The old README said Lima was "installed automatically by coop setup", which was never true. Both the README and the getting-started prerequisites now state the platform split and name brew install lima.

The new Install section is also corrected on two points: coop update treats the checksum as mandatory while install.sh skips verification when no sha256sum or shasum binary is present, and both fall back to the GitHub attestations API for releases published without a usable bundle asset.

Follow-up, not in this PR

docs/commands.md:151 describes coop setup with the same missing platform qualifier. It is outside this change's diff and left for a separate fix.

Documentation only — no code changes.

🤖 Generated with Claude Code

@evandowning evandowning self-assigned this Sep 1, 2026
@evandowning evandowning added the component:documentation 📖 Improvements or additions to documentation label Sep 1, 2026
@evandowning
evandowning marked this pull request as ready for review September 1, 2026 12:52
@evandowning
evandowning requested a review from hbrodin September 1, 2026 12:52

@hbrodin hbrodin left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approving — the cut is sound and the setup correction is right.

I verified the platform split against the source: src/setup.rs:102-103 calls install_firecracker and fetch_kernel on the Firecracker path only, and src/lima.rs:649 hard-fails with brew install lima, so the old README's "installed automatically by coop setup" was indeed wrong. All four added anchors resolve (commands.md#update, configuration.md#updates-section, getting-started.md#prerequisites, docs/index.md), CONTRIBUTING.md:33 was the only inbound link to a deleted README anchor repo-wide, and every removed section is covered by the doc it now points to.

One inline suggestion on the manual verification recipe. One more for a file outside this diff:

docs/commands.md:151 — the follow-up you flagged in the description. It is the last unqualified coop setup description left (docs/getting-started.md:119 and docs/backends.md:147 already split by backend), so after this PR it contradicts the corrected README.md:30. One line, if you would rather land it here than in a separate PR:

Run this once after installing coop. It checks prerequisites and builds a template root filesystem. On Linux it also installs Firecracker and fetches a guest kernel; on macOS it requires Lima to already be installed (brew install lima) and fails without it.

Non-blocking: the description does not match the diff — it says 84 lines (the file is 67) and lists four sections including a new Development section, but the README has three (Setup, Usage, Documentation) and links docs/testing.md nowhere. Reads like a section was cut before push; worth reconciling the body or restoring it.

Comment thread docs/getting-started.md Outdated
evandowning and others added 4 commits September 1, 2026 15:48
Reduce README.md from 189 to 84 lines, leaving four sections: setup and
updating, usage, development, and documentation.

Drop the feature list, the full command table, and the release-verification
walkthrough. The command table duplicated docs/commands.md, the update flags
are documented at docs/commands.md#update and docs/configuration.md, and the
backend requirements are in docs/getting-started.md.

Add an Install section to docs/getting-started.md so the release-verification
instructions keep a user-facing home, and point CONTRIBUTING.md at that
document instead of the removed README requirements anchor.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`coop setup` installs a runtime and fetches a kernel only on the Firecracker
backend (src/setup.rs). The Lima path (src/lima.rs) does neither and fails
when limactl is missing, so state the platform split and point macOS readers
at `brew install lima`, in the README and in the getting-started
prerequisites.

Also correct the new Install section: `coop update` requires the checksum
while install.sh skips it when no sha256sum tool is present, and both fall
back to the GitHub attestations API when no bundle asset is published. Align
the Linux arm64 support wording between the two documents.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Henrik Brodin <90325907+hbrodin@users.noreply.github.com>
@evandowning
evandowning force-pushed the worktree-readme-simplify branch from 61f4f59 to 684b9b8 Compare September 1, 2026 19:48
@evandowning
evandowning merged commit 83c0855 into main Sep 1, 2026
9 checks passed
@evandowning
evandowning deleted the worktree-readme-simplify branch September 1, 2026 19:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component:documentation 📖 Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants