docs(readme): slim README to quickstart, move details to docs - #410
Conversation
57e1a3e to
b0a7dbb
Compare
wz-gsa
left a comment
wz-gsa
left a comment
There was a problem hiding this comment.
Adversarial review — LGTM, verified this is a clean content move with no silent loss
This is the risk class where a big README reorg (+230/-348) most often goes wrong — content quietly dropped, or an anchor left dangling after a heading rename. I checked both, not just skimmed the diff.
Content-loss check — traced all 4 removed troubleshooting blocks to their actual destination, not just "there's a link now":
- Expired-USAi-key manual rotation — the literal 4-step console click-path is gone verbatim, but the automatic rotation flow it described is documented with more nuance elsewhere (placeholder-preservation caveats, ADR-0008 ref). Functionally covered, not a byte-for-byte relocation. Non-blocking, noted below.
- msb DNS resolution (
ACQ_MSB_DNS_NAMESERVER) — byte-for-byte equivalent already lives atdocs/BACKEND_GUIDE.md#dns--name-resolution(pre-existing, untouched). No loss. - "Commits show Unverified" — fully intact at
KNOWN_FAILURE_MODES.md#22, which is a superset of the README version (adds ADR-0007/0021 links + msb/sbx parity note). No loss. - "Pulled a branch, acq behaves like the old version" — fully intact at
KNOWN_FAILURE_MODES.md#24, superset of the README version. No loss.
Anchor-link integrity — checked every internal #anchor touched or introduced by this diff, GitHub-slugified by hand: all 13 pass, including the self-referential ones inside the same file. Confirmed Step 2: Install acq really does slugify to step-2-install-acq (the one I most wanted to see with my own eyes).
Nice catch by the author, worth calling out: the moved "How It Works" content in docs/CONCEPTS.md doesn't just copy the old README text — it fixes two anchors that this same PR's rename would otherwise have broken (#troubleshooting → the correct KNOWN_FAILURE_MODES.md#22-... and howto/acq.md#rotate-your-usai-key). That's the right way to do a section rename alongside a content move.
"What's in this repo" table — moved cleanly to CONTRIBUTING.md with zero duplication (README no longer carries a copy), gained a legitimate install.sh row, and all 13 listed paths verified to exist. No dangling entries.
Found while checking anchors — a genuinely dead, pre-existing link, NOT introduced by this PR: docs/BACKEND_GUIDE.md:67 points at ../README.md#step-2-install-sbx-cli, which doesn't exist (confirmed the line is untouched by this diff — git diff on that file is empty). Filed as #415 rather than blocking this PR on it.
Non-blocking
.markdown-link-check.json'sgnu.org/parallelignore-pattern addition is unrelated to the content move — same "CI-config rider in a feature PR" pattern flagged on patterns #391. Harmless here, but worth splitting into its own commit/PR going forward for clean disclosure.- The manual USAi-key-rotation click-path (console → Rotate → copy → paste) has no single verbatim home anymore; consider restoring it as an explicit callout in
docs/howto/acq.mdfor users who want the manual path outside the automatic flow.
CI (Markdown Lint, Link Check, pre-commit, Conventional Commit Title) all green. Approve.
AI-assisted (OpenCode).
I'll try to be better about this going forward, but I'm going to leave it in.
I'll add a section about recognizing when your key is expired and how to rotate it on the host without restarting your sandbox. |
The README had grown to 537 lines and buried the 3-step quickstart under conceptual and developer-oriented material, hurting the primary audience: a non-technical, first-time-CLI user. Trim the README to the essentials and relocate detail to existing docs: - How It Works internals, Customizing, Advanced: extra kits, and Optional Integrations -> docs/CONCEPTS.md - Direct package-manager install, manual clone install, and tagged-release notes -> docs/howto/acq.md (new "Installing acq" section) - "What's in This Repo" file-map -> CONTRIBUTING.md - Deep troubleshooting (USAi expiry, DNS, unverified commits, stale branch) already lives in docs/KNOWN_FAILURE_MODES.md; README keeps only the two first-run traps a newcomer hits (wrong-folder ./acq, Command Line Tools) and points to KNOWN_FAILURE_MODES.md for the rest Kept inline per review: the three-repo ecosystem "you are here" table and the "Why Sandboxes?" bullets. Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
The Link Check job failed on https://www.gnu.org/software/parallel/ (status 0 — connection failure), a pre-existing link in CONTRIBUTING.md's local-dev notes. GNU's site is intermittently unreachable from the CI runner. Add it to the markdown-link-check ignore patterns so a transient GNU outage can't fail the docs check. Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
Add a 'Rotate your USAi key' section to docs/howto/acq.md that points at the in-place ./acq usai-rotate-api-key subcommand (no session restart, which the sbx backend handles poorly), covers the console Rotate/copy path, and notes attach-time rotation as secondary. Point the README's rotation mention at it and cross-link Known Failure Modes §20 for truncated-copy rejections. Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
414fce4 to
7d0f22b
Compare
wz-gsa
left a comment
wz-gsa
left a comment
There was a problem hiding this comment.
Re-approve after the push (prior approval auto-dismissed). Both non-blocking notes from my first review are addressed: the manual USAi key-rotation click-path is restored in docs/howto/acq.md (with a nice addition — clarifying no session restart is needed), and the gnu.org/parallel ignore-pattern now has its own disclosed commit message rather than riding silently. Nothing else changed. Still approve.
2 participants
Context
We've been simplifying the language and streamlining the process, but
README.mdhad grown to 537 lines and buried the 3-step quickstart under conceptual and developer-oriented material. That hurts the primary audience: a non-technical, first-time-CLI user who has likely never done development work on their workstation.This PR strips the README to the essentials and moves everything non-essential into other files (not just README subsections).
What changed
The README drops from 537 to 235 lines. Content moved to existing docs rather than deleted:
docs/CONCEPTS.mddocs/CONCEPTS.mddocs/CONCEPTS.mddocs/howto/acq.md(new "Installing acq" section)CONTRIBUTING.mddocs/KNOWN_FAILURE_MODES.md; README now points thereKept inline (per review): the three-repo ecosystem "you are here" table, the "Why Sandboxes?" bullets, the 3-step quickstart, and the two first-run traps a newcomer actually hits (wrong-folder
./acq, Command Line Tools / Dock).Verification transcript
Run in the acq sandbox:
npm run lint:md(markdownlint-cli2, same rules as CI)#installing-acq,#msb-host-setup,#multiple-workspaces,#step-2-install-acq)gitleaks protect --stagedgh stack view --jsondocs/npm-install-fresh-macos(#387)Rollback
Revert this branch/PR. Docs-only; no runtime behavior changes.
Security impact
None. No auth/authz, dependency, or code changes; documentation reorganization only.
AI-assisted (OpenCode). Human owner: @mogul.