docs + fix(release): sell-focused README, dev guide, and bash-3.2 artifact collection fix#10
Conversation
macOS GitHub runners ship bash 3.2, which lacks `globstar`, so the
`shopt -s globstar` + `**` recursive globs in collect-release-artifacts.sh
errored ('shopt: globstar: invalid shell option name') and failed the
release before publishing. Replace the recursive globs with `find`, which
works on bash 3.2.
Reframe the README around end users who download and use the app rather than developers building from source. Lead with the value proposition, hero screenshot, benefit-led feature list, install path (with the unsigned-app first-launch note), and a privacy/local-first section. Move all setup, run, CLI, and release commands into docs/development.md, and add docs/images/README.md documenting the expected screenshots.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request restructures the project documentation by moving development instructions from the main README to a new docs/development.md file, polishing the main README, and adding a screenshot guide. It also updates collect-release-artifacts.sh to use find instead of bash globstar (**) to support older bash versions on macOS runners. A review comment correctly points out that using find ... | head -n1 under set -euo pipefail can trigger a SIGPIPE failure (exit status 141) if multiple files are found, and provides a suggestion to temporarily disable pipefail in the subshell.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Under set -o pipefail, 'find ... | head -n1' can exit 141 when find keeps writing after head closes the pipe (multiple artifacts present). Run each in a subshell with pipefail disabled so the early-exit pipe is ignored without affecting the parent shell.
The .diff-table/.diff-line/.line-no/.split-side/.comment-row rules styled a previous custom diff renderer. The diff body now renders via @pierre/diffs into a Shadow DOM (using [data-line]/diffs-* selectors), so these light-DOM class rules apply to nothing and are referenced nowhere in src. Removing ~165 lines of misleading dead CSS.
1 participant
Combines #8 and #9 into a single PR off a fresh copy of
main.1. Release fix (was #8)
Problem: The Release workflow's
collect-release-artifacts.shusedshopt -s globstar+**recursive globs. macOS GitHub runners (macos-14) ship bash 3.2, whereglobstardoesn't exist, so the step failed withshopt: globstar: invalid shell option nameand the release aborted after building the DMG but before publishing. Observed in thev0.1.1-rc1run.Fix: Replace the recursive globs with
find, which works on bash 3.2+. Verified locally on bash 3.2.57 (same as the runner): finds artifacts, canonicalizes names, writesSHASUMS256.txt, exits 0.2. Sell-focused docs (was #9)
Reworks the project docs to sell the app to end users and separates build/run instructions from the pitch.
README.md— rewritten as a product pitch (end-user first): hero block (logo, tagline, badges, hero screenshot), "Why you need it", benefit-led "What you get", screenshot gallery, Install (.dmg+ planned Homebrew, with the unsigned-app first-launch note), privacy/local-first section, and a slim "Build from source" handoff that keeps the workspace-layout table.docs/development.md(new) — all setup, run, dev, backend CLI, formatting, review-data, and release commands moved out of the README.docs/images/README.md(new) — documents the five expected screenshot filenames the README references.Notes for reviewers
docs/images/*.png; those PNGs are not in this PR yet, so they render as broken until captures are added (filenames documented indocs/images/README.md).main, cherry-picking the release fix and applying the resolved doc state — no merge commits.Test plan
bash -nsyntax check on bash 3.2.57out/makeartifactsv0.1.1-rcNprerelease after merge to validate end-to-end