[dabodamjan]

What changed

• README: opens with the problem and three trust lines under the install prompt; the before/after figure, the keyboard figure and the resume-loop figure replace the paragraphs they explain; the table says what each command writes and what to do without a shortcut; Limits is seven one-line bullets with the reasoning linked, not repeated.
• "Shortcut" replaces "chord" in every file. Decision 001 renamed to 001-shortcuts-live-in-karabiner.md (git mv). The keystroke block moved there; the ASCII flow diagram moved to docs/architecture.md.
• karabiner/build.py: the constant is SHORTCUTS, docstring updated, generator re-run; the JSON is byte-identical.
• New: docs/images/ (three webp figures, 1280x640 social preview PNG), .github/workflows/tests.yml (macOS runner; the suite plus the system-bash pass).
• Fix: uninstall removes only what the manifest records. A Karabiner rule file that was already at the install path, and a CLAUDE.md block that was already in place, are left alone when the install did not record them. Previously uninstall deleted the rule file and stripped the block. New test case 4q covers both. INSTALL.md's uninstall list says so.
• Wording: prompt retention in INSTALL.md and docs/architecture.md now matches the stash hook (files older than 24 hours are deleted on the next stash-hook run, otherwise they stay); the README says a repeat install refreshes only the manifest metadata.
• Badge: added only after the first green run of the macOS job. It reads "no status" until the merge triggers the push run on main.

Verified

• ./tests/run.sh: passed: 145 failed: 0 (and the same with --system-bash); of the four new 4q assertions, the two that check the files stay failed on the old code
• python3 karabiner/build.py --check: match; no JSON diff
• grep for "chord": nothing. Em dashes: none. Relative links and image paths: all resolve.
• GitHub Actions: macos pass on every push, including the uninstall fix (run 39848175320); both suite passes report passed: 145 failed: 0 on the runner.
• The three README figures render on GitHub.
• Known gap: on macos-latest the bash on PATH is also 3.2, so the two suite passes in CI run under the same bash and no newer bash is tested there. Locally the suite passes under bash 5 and 3.2.

Follow-up (not in this PR)

• A Linux job: tests/run.sh lines 62, 133 and 194 read file modes with stat -f %Lp ... || stat -c %a ..., which does not produce a clean value under GNU stat. Port those three assertions (for example through python3 os.stat), then add an ubuntu-latest job.

Left for Damjan

• Upload docs/images/social-preview.png as the repository social preview (Settings > General > Social preview).

• About box (description, topics) is applied with gh repo edit after merge; homepage once the post is live.

• "Who made this" links ReleaseRocket, Itemlist, QRGenie and BarcodeCraft to their sites.