GitHub Check Run on every pull request

Problem

Needly's growth rate is structurally zero. One person installs a GitHub App and looks at a private page. No other collaborator on the repository ever sees that Needly exists.

This is the strongest growth loop available to a GitHub App, and the one that built Codecov, Vercel and Danger: put useful output on the pull request itself, where every collaborator already is.

Scope

Publish a Needly check run on pull requests in watched repositories.

Needly - Attention
  Waiting 14h for review - assigned to @alice
  Risk HIGH - authentication, database migration
  1 of 2 approvals

The check must be genuinely useful on its own, not an advertisement. If it is noise, maintainers will disable it and the loop closes.

Acceptance criteria

• Check run created and updated as the pull request state changes
• Content is accurate, short, and never duplicates what GitHub already shows
• Check is always neutral or success, never failure: Needly must not be able to block a merge
• Opt-in per repository, configurable in Settings, off by default
• The checks: write permission is requested as an optional, incremental scope so cautious organisations can install without it
• Rate limiting and backoff so a busy repository cannot exhaust the installation quota
• Detail view links back to Needly

Security note

This changes Needly's posture from read-only observer to a service that writes to repositories, which will slow some enterprise reviews. Mitigate with a narrowly scoped optional permission and clear documentation in docs/github-app.md. The loop is worth the friction, but the opt-in is not negotiable.

Start with docs/github-app.md and trace the existing GitHub App integration and pull-request event entry points. Define the opt-in settings, optional checks:write permission, check-run updates, rate limiting, and detail link against the acceptance criteria; done means accurate non-blocking checks work on watched repositories without exhausting installation quota.