claudiomaradonna/agent-foundry
claudiomaradonna/agent-foundry
Template
1
0
Fork 0
Code Issues Pull requests Activity Actions

docs: trim the README to what an adopter reads #212

Merged
claudiomaradonna merged 3 commits from docs/readme-trim into main 2026-11-10 17:04:33 +01:00
Conversation 0 Commits 3 Files changed 5 +262 -232
motoko commented 2026-11-10 17:02:56 +01:00
Collaborator
Copy link

Why

The README ran to about 2800 words, fourteen minutes at the 200 words a
minute AGENTS.md counts, where it sizes a README to five to eight. A
person deciding whether to adopt met the agent's six adoption steps
before the settings they agree to, and then a manual of what a command
meets inside Claude Code's sandbox, which a developer asks only once a
command has failed. A documentation audit found both blocks misplaced.
Moving the sandbox manual alone would have met the size, and was set
aside because it left the agent's procedure in the person's way.

What changed

The README now holds about 1190 words. Its Hooks and settings keeps what
an adopter agrees to: what the hooks refuse, what the settings turn off
and unset, what the sandbox leaves open, when a command runs outside it,
and the way out, once. The operating detail stands in a new
docs/SANDBOX.md.

The six adoption steps and the validator command open
docs/INSTALL.md, with their numbers and text kept; the Quick start
keeps the person's four steps and links to them. Step 6's reviews take
the README and the install guide as the goal. UPGRADING.md cites the
steps there, and its Denied tools migration names Hooks and settings,
where the list it points to has stood since #203.

The Description, Dependencies, and References lose what the workflows
guide and docs/MAINTENANCE.md already say. AGENTS.md, the skills,
and the settings stay as they are.

How to verify

  1. Read the README top to bottom: it ends within eight minutes, and the
    Quick start's link opens the six steps.
  2. In UPGRADING.md, follow the Secret rules at every depth migration's
    link: it opens the guide's Secret files section, where main's link
    opened the README.
  3. Run
    git diff --color-moved=dimmed-zebra main -- README.md docs/INSTALL.md docs/SANDBOX.md:
    the moved paragraphs show dimmed, and the rest is the new text.

The six checks of docs/MAINTENANCE.md pass on the tip. The suite's
sandbox and network-isolation tests were skipped, since bubblewrap
cannot start inside the agent session's sandbox; the forge's job runs
them.

Considerations

The README and the sandbox guide both say that commands run unsandboxed
where bubblewrap or socat is missing, and that a failed command may be
retried outside the sandbox: the reviews asked for both in the README,
for the adopter. The anchors the new links carry have no automatic
check.

## Why The README ran to about 2800 words, fourteen minutes at the 200 words a minute `AGENTS.md` counts, where it sizes a README to five to eight. A person deciding whether to adopt met the agent's six adoption steps before the settings they agree to, and then a manual of what a command meets inside Claude Code's sandbox, which a developer asks only once a command has failed. A documentation audit found both blocks misplaced. Moving the sandbox manual alone would have met the size, and was set aside because it left the agent's procedure in the person's way. ## What changed The README now holds about 1190 words. Its Hooks and settings keeps what an adopter agrees to: what the hooks refuse, what the settings turn off and unset, what the sandbox leaves open, when a command runs outside it, and the way out, once. The operating detail stands in a new `docs/SANDBOX.md`. The six adoption steps and the validator command open `docs/INSTALL.md`, with their numbers and text kept; the Quick start keeps the person's four steps and links to them. Step 6's reviews take the README and the install guide as the goal. `UPGRADING.md` cites the steps there, and its Denied tools migration names Hooks and settings, where the list it points to has stood since #203. The Description, Dependencies, and References lose what the workflows guide and `docs/MAINTENANCE.md` already say. `AGENTS.md`, the skills, and the settings stay as they are. ## How to verify 1. Read the README top to bottom: it ends within eight minutes, and the Quick start's link opens the six steps. 2. In `UPGRADING.md`, follow the Secret rules at every depth migration's link: it opens the guide's Secret files section, where main's link opened the README. 3. Run `git diff --color-moved=dimmed-zebra main -- README.md docs/INSTALL.md docs/SANDBOX.md`: the moved paragraphs show dimmed, and the rest is the new text. The six checks of `docs/MAINTENANCE.md` pass on the tip. The suite's sandbox and network-isolation tests were skipped, since bubblewrap cannot start inside the agent session's sandbox; the forge's job runs them. ## Considerations The README and the sandbox guide both say that commands run unsandboxed where bubblewrap or socat is missing, and that a failed command may be retried outside the sandbox: the reviews asked for both in the README, for the adopter. The anchors the new links carry have no automatic check. 
The README ran to fourteen minutes, and what a command meets inside
Claude Code's sandbox, which a developer asks only once a command has
failed, made up a third of it. docs/SANDBOX.md takes that detail with
its text, and the README keeps what an adopter agrees to: what the
settings refuse and unset, what the sandbox leaves open, and the way
out, once.

The Denied tools migration named the README's Description for what
Hooks and settings has held since the hooks moved there.
The six steps are the agent's procedure, and stood between the four
steps a person takes and the settings that person agrees to. The
install guide, which already held their variants, now opens with them
and with the validator command a person runs after them; the README
keeps the request and links to the steps.

Step 6's reviews take the README and the install guide as the goal,
since the steps they check the adoption against now stand in the
second.
docs(readme): drop what other documents say
All checks were successful
Maintenance / checks (pull_request) Successful in 4m23s
Details
Maintenance / checks (push) Successful in 4m5s
Details
99fc8652bb
 
The Description walked through the work file's phases, which the
workflows guide it links holds, and Dependencies gave the maintainer's
reasons for Prettier and bubblewrap, which docs/MAINTENANCE.md holds.
References listed sources an adopter does not act on; the Codex links
a reader follows stand where they are used.
claudiomaradonna deleted branch docs/readme-trim 2026-11-10 17:04:36 +01:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
claudiomaradonna/agent-foundry!212
No description provided.