Skip to content

docs: polish README (url-only step, portable install path, dedupe config)#16

Merged
atani merged 1 commit intomainfrom
docs/readme-polish
Apr 18, 2026
Merged

docs: polish README (url-only step, portable install path, dedupe config)#16
atani merged 1 commit intomainfrom
docs/readme-polish

Conversation

@atani
Copy link
Copy Markdown
Owner

@atani atani commented Apr 18, 2026

Summary

Targeted README fixes spotted while re-reading after v0.7.2.

  1. Browser-mode step list undercounts --url-only. Step 1 ('Create a comment with placeholders') sounded mandatory; only step 5 mentioned the url-only case. Mark step 1 as skipped and rewrite step 5 as an either/or branch so the flow is consistent.
  2. Manual install uses a path that is not writable without sudo on Apple Silicon. Swap /usr/local/bin/gh-attach for ~/.local/bin/gh-attach so the snippet works out of the box on both Intel and Apple Silicon.
  3. Direct mode claim was overconfident. The feature-complete README said Direct mode 'works on GitHub.com' but that path has not been regression-tested against the current github.com UI. Soften the wording to 'historical / opt-in, use at your own discretion'.
  4. Duplicated config file section. The Configuration File section repeated what the Direct mode section already covered. Fold them into one authoritative description.

Test plan

  • README renders correctly on GitHub (markdown-only changes)
  • bash -n of bin/gh-attach still passes (no script change in this PR)

…onfig section

- Clarify that step 1 of Browser mode (create placeholder comment) is
  skipped when --url-only is set. Previously step 1 sounded mandatory
  and only step 5 mentioned the url-only path.
- Replace the manual-install symlink target /usr/local/bin with
  ~/.local/bin so the snippet works without sudo on Apple Silicon
  (where /usr/local/bin is not writable by default).
- Soften the Direct mode claim — we have not regression-tested it
  against current github.com, so call it historical/opt-in rather than
  asserting it works.
- Fold the duplicated 'Configuration file' section into the Direct
  mode section. One authoritative description instead of two.
@atani atani merged commit 9a0615b into main Apr 18, 2026
1 check passed
@atani atani deleted the docs/readme-polish branch April 18, 2026 14:51
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