docs: stop the contributor first hour promising things that are not true (#1443)

Author: y3owk1n

.agents/skills/create-pr/SKILL.md

@@ -31,7 +31,8 @@ the usual ones.
 
 1. Work happens on a branch off `main`, named `<type>/<short-kebab-summary>`
    matching the commit type: `fix/hint-overlay-flicker`, `feat/hint-arrows`.
-2. Run the full gate — it is exactly what CI runs, so surprises surface here:
+2. Run the full gate — the same recipes CI gates on, run on your host only,
+   where CI runs them on macOS, Linux and Windows:
 
    ```bash
    just ci

.github/pull_request_template.md

@@ -44,7 +44,9 @@
       scan, build); CI runs them on macOS, Linux and Windows
 - [ ] Tests added/updated for new or changed functionality
 - [ ] Documentation updated (if applicable)
-- [ ] Commit messages follow [conventional commits](https://www.conventionalcommits.org/)
+- [ ] PR title is a [conventional commit](https://www.conventionalcommits.org/)
+      subject written for users — this PR squash-merges, so the title is what
+      Release Please ships in the changelog, not the commits on the branch
 
 ## Screenshots / Recordings
 

CONTRIBUTING.md

@@ -47,7 +47,9 @@ issues, so reports stay confidential.
 
 Set up your environment by following
 [DEVELOPMENT.md](docs/DEVELOPMENT.md#development-setup) — Devbox is the
-recommended path and provides every tool pre-configured.
+recommended path and provides the toolchain pre-configured. On Linux, read the
+prerequisites there first: Devbox does not cover the system packages a CGO
+build links against.
 
 ---
 
@@ -234,9 +236,7 @@ and don't submit changes you can't explain.
 
 ## Good First Contributions
 
-Not sure where to start? Issues labeled
-[`good first issue`](https://github.com/y3owk1n/neru/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-are curated to be well-scoped for newcomers. Beyond those:
+Not sure where to start? Any of these are welcome:
 
 - 🐛 Bug fixes — check the [open issues](https://github.com/y3owk1n/neru/issues)
 - 📝 Documentation improvements or typo fixes

README.md

@@ -286,11 +286,11 @@ and pull requests are very welcome.
 
 ```bash
 git checkout -b feature/your-feature
-just ci   # everything CI checks, locally
+just ci   # the same recipes CI gates on, on your host only
 # open a pull request
 ```
 
-→ [Contributing Guide](CONTRIBUTING.md) · [Development Guide](docs/DEVELOPMENT.md) · [Good first issues](https://github.com/y3owk1n/neru/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+→ [Contributing Guide](CONTRIBUTING.md) · [Development Guide](docs/DEVELOPMENT.md)
 
 ---
 

docs/DEVELOPMENT.md

@@ -43,13 +43,21 @@ Then from a second terminal:
 ./bin/neru hints        # should show hint overlays
 ```
 
+> [!IMPORTANT]
+> On macOS this needs Accessibility permission granted to whichever app starts
+> the daemon — your terminal, when you run `./bin/neru launch` by hand. Without
+> it the smoke test reports an accessibility error instead of drawing overlays.
+> Same grant, same place as for the integration tests: see
+> [Running integration tests](#running-integration-tests).
+
 There is no `just run` recipe — build first, then launch the daemon directly.
 The CLI talks to the running daemon over a socket, so both halves come from the
 same `./bin/neru` binary.
 
 For end-user installation (Homebrew, Nix, prebuilt binaries) see
-[INSTALLATION.md](INSTALLATION.md); for preparing a Linux host see
-[LINUX_SETUP.md](LINUX_SETUP.md).
+[INSTALLATION.md](INSTALLATION.md); on Linux,
+[LINUX_SETUP.md](LINUX_SETUP.md) covers both preparing the host and the
+[build dependencies](LINUX_SETUP.md#build-dependencies) a source build needs.
 
 ---
 
@@ -59,13 +67,17 @@ For end-user installation (Homebrew, Nix, prebuilt binaries) see
 
 - **Go 1.26+** — [Install Go](https://golang.org/dl/)
 - **Xcode Command Line Tools** (macOS) — `xcode-select --install`
+- **Build dependencies** (Linux) — the system `-dev`/`-devel` packages a CGO
+  build links against, listed for apt, dnf and pacman in
+  [LINUX_SETUP.md](LINUX_SETUP.md#build-dependencies). Install them before your
+  first build, including under Devbox.
 - **Just** — command runner — [install](https://github.com/casey/just)
 - **golangci-lint** — linter — [install](https://golangci-lint.run/usage/install/)
 
 ### Option A: Devbox (recommended)
 
 [Devbox](https://www.jetify.com/devbox) provides an isolated environment with
-every tool pre-configured:
+the toolchain below pre-configured:
 
 ```bash
 curl -fsSL https://get.jetify.com/devbox | bash
@@ -80,6 +92,13 @@ in the repo root takes over whenever you `cd` in.
 Devbox manages Go 1.26+, gopls, gotools, gofumpt, golines, golangci-lint, just,
 and clang-tools (for CGo).
 
+On Linux it is not enough on its own: Devbox does not pull the `-dev` outputs a
+CGO build links against
+([jetify-com/devbox#2761](https://github.com/jetify-com/devbox/issues/2761)),
+so install the system packages listed in
+[LINUX_SETUP.md](LINUX_SETUP.md#build-dependencies) first — `just build` fails
+in the compiler without them.
+
 ### Option B: Manual installation
 
 ```bash