docs: close the gaps in the prose for people

motoko commented

2026-11-06 17:57:35 +01:00

Collaborator

Why

A documentation audit of the prose for people, run on 2026-11-06 at
becb455, found the README, docs/INSTALL.md, and docs/MAINTENANCE.md
answering their readers only in part. A person deciding whether to
adopt could not learn what the two hooks do to a session, nor that
.claude/settings.json turns off more than the four denied tools,
although adoption copies all of it into every user's sessions. A Codex
user following the Quick start never met the hook trust that only they
can give, so their sessions ran without the main-checkout guard. A
repository adopted before foundry-upgrade was sent to the Quick
start, which only adopts. The maintainer could not tell which tool
versions the checks pass on, while the forge's job pins ShellCheck
0.11.0, whose codes the scripts' directives name, and the README allows
0.7.0.

What changed

A new README section, Hooks and settings, placed after the Quick start
and holding the Codex subsections, says what the main-checkout guard
refuses and what the shell check does, lists the other switches of
.claude/settings.json with the way out for any of them, and says the
OpenCode plugins are tested against stubs only; the Description points
to it. The Quick start opens with the pointer to docs/INSTALL.md for
the other cases, and its step 3 has a Codex user trust the hooks in the
fresh session that loads the copied files, while adoption step 2 has
the agent ask the user to do so there, as UPGRADING.md already did
for an upgrade.

docs/INSTALL.md sends a repository adopted before foundry-upgrade to
the README's Upgrading section, and tells a new repository's step 2 in
three sentences: the empty commit, its push on the user's word before
the adoption's pull request, and the copy or the deletions.

docs/MAINTENANCE.md names the versions the checks pass on, as the
forge's job pins them, and owns the Node.js requirement, with the test
that runs it, so the README's Dependencies no longer list Node.js for an
adopter.

How to verify

Read README.md from the top on this branch: the Description points to
Hooks and settings, which names what each hook does and every switch of
.claude/settings.json, which jq -r 'keys[]' .claude/settings.json
lists; on main the Description names the hooks without saying what they
do and only the denied tools. Then read the Quick start as a Codex
user: step 3 has you trust the hooks in the fresh session; on main no
step does. Read docs/INSTALL.md § Adopted before foundry-upgrade:
its link lands on the README's Upgrading section; on main it says "as
the Quick start describes". Read the first paragraph of
docs/MAINTENANCE.md beside .forgejo/workflows/maintenance.yml: the
versions match its image comment and its npm install line.

Checks run on the tip: the six checks of docs/MAINTENANCE.md, all
passing, with 225 agent configuration tests and 46 work-folder tests,
and three review rounds of document-reviewer and security-reviewer
with no finding left open. No regression test changes: the change is
prose only. Not tried: an adoption from Codex or OpenCode, since
neither client is installed here.

Considerations

The Codex hooks documentation does not say whether a running session
lists a hooks.json created after it started, only that Codex warns at
startup when hooks need review, so the Quick start and adoption step 2
put the hook trust in the fresh session that loads the copied files,
which holds either way. The guard's sentence gives its gist and leaves
its cases to the script's header and to the refusal's reason. The
audit's rule on when a change needs a migration in UPGRADING.md is
left for a decision of its own, and its findings on the workflow pages
and the eval runner's header for a later change.

## Why A documentation audit of the prose for people, run on 2026-11-06 at becb455, found the README, `docs/INSTALL.md`, and `docs/MAINTENANCE.md` answering their readers only in part. A person deciding whether to adopt could not learn what the two hooks do to a session, nor that `.claude/settings.json` turns off more than the four denied tools, although adoption copies all of it into every user's sessions. A Codex user following the Quick start never met the hook trust that only they can give, so their sessions ran without the main-checkout guard. A repository adopted before `foundry-upgrade` was sent to the Quick start, which only adopts. The maintainer could not tell which tool versions the checks pass on, while the forge's job pins ShellCheck 0.11.0, whose codes the scripts' directives name, and the README allows 0.7.0. ## What changed A new README section, Hooks and settings, placed after the Quick start and holding the Codex subsections, says what the main-checkout guard refuses and what the shell check does, lists the other switches of `.claude/settings.json` with the way out for any of them, and says the OpenCode plugins are tested against stubs only; the Description points to it. The Quick start opens with the pointer to `docs/INSTALL.md` for the other cases, and its step 3 has a Codex user trust the hooks in the fresh session that loads the copied files, while adoption step 2 has the agent ask the user to do so there, as `UPGRADING.md` already did for an upgrade. `docs/INSTALL.md` sends a repository adopted before `foundry-upgrade` to the README's Upgrading section, and tells a new repository's step 2 in three sentences: the empty commit, its push on the user's word before the adoption's pull request, and the copy or the deletions. `docs/MAINTENANCE.md` names the versions the checks pass on, as the forge's job pins them, and owns the Node.js requirement, with the test that runs it, so the README's Dependencies no longer list Node.js for an adopter. ## How to verify Read `README.md` from the top on this branch: the Description points to Hooks and settings, which names what each hook does and every switch of `.claude/settings.json`, which `jq -r 'keys[]' .claude/settings.json` lists; on main the Description names the hooks without saying what they do and only the denied tools. Then read the Quick start as a Codex user: step 3 has you trust the hooks in the fresh session; on main no step does. Read `docs/INSTALL.md` § Adopted before `foundry-upgrade`: its link lands on the README's Upgrading section; on main it says "as the Quick start describes". Read the first paragraph of `docs/MAINTENANCE.md` beside `.forgejo/workflows/maintenance.yml`: the versions match its image comment and its `npm install` line. Checks run on the tip: the six checks of `docs/MAINTENANCE.md`, all passing, with 225 agent configuration tests and 46 work-folder tests, and three review rounds of `document-reviewer` and `security-reviewer` with no finding left open. No regression test changes: the change is prose only. Not tried: an adoption from Codex or OpenCode, since neither client is installed here. ## Considerations The Codex hooks documentation does not say whether a running session lists a `hooks.json` created after it started, only that Codex warns at startup when hooks need review, so the Quick start and adoption step 2 put the hook trust in the fresh session that loads the copied files, which holds either way. The guard's sentence gives its gist and leaves its cases to the script's header and to the refusal's reason. The audit's rule on when a change needs a migration in `UPGRADING.md` is left for a decision of its own, and its findings on the workflow pages and the eval runner's header for a later change.

motoko added 3 commits

2026-11-06 17:57:40 +01:00

docs(install): point old adoptions at the upgrade afb318e182

The section for a repository adopted before foundry-upgrade sent its
reader to the Quick start, which only adopts, so they would have run the
adoption prompt on an adopted repository. The step 2 bullet of a new
repository was one sentence of eighty words that left unclear whether
and when the empty commit is pushed.

docs(readme): answer the adopter's questions 901ef6f88a

A person deciding whether to adopt could not learn from the README what
the two hooks do to a session, nor that .claude/settings.json turns off
more than the four denied tools, although adoption copies all of it into
every user's sessions. A Codex user following the Quick start never met
the hook trust that only they can give, so their sessions ran without
the main-checkout guard, while adoption step 2 asked the agent to
complete it. The pointer to docs/INSTALL.md came after the steps it
exempts its readers from.

docs(maintenance): name the pinned tool versions

Maintenance / checks (pull_request) Successful in 4m12s

Details

f87ece4c24

docs/MAINTENANCE.md did not say which tool versions the checks pass on,
while the forge's job pins ShellCheck 0.11.0, whose codes the scripts'
directives name, Prettier 3.9.9, and Node.js 22, so a maintainer on the
ShellCheck 0.7.0 the README allows could see results that differ from
CI's. The README listed Node.js among the suggested tools with no use
for an adopter: only tests/agent-config/opencode-plugins.sh runs it.

motoko force-pushed docs/people-prose-gaps from f87ece4c24

Maintenance / checks (pull_request) Successful in 4m12s

Details

to cf80a41b2c

Maintenance / checks (pull_request) Successful in 4m10s

Details

Maintenance / checks (push) Successful in 3m43s

Details

2026-11-06 18:10:36 +01:00

Compare