diff --git a/README.md b/README.md
index 6e94732..fa53f97 100644
--- a/README.md
+++ b/README.md
@@ -5,12 +5,40 @@
-[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/immutable-releases/details.json)
+[](https://github.com/reponomics/PolicyChecks/actions/workflows/ci.yml)
+[](https://scorecard.dev/viewer/?uri=github.com/reponomics/PolicyChecks)
+[](https://github.com/apps/policychecks)
+
+
+**Badges for GitHub repository settings that other badge services can't see.**
+
+## What is PolicyChecks?
+
+Several repository settings aren't exposed to unauthenticated callers through the GitHub API, which prevents public badge services from reporting them: whether Actions must be pinned to a full-length commit SHA, whether secret push protection is on, whether the default branch blocks force pushes.
+
+PolicyChecks is a GitHub App and a badge service. Install the App on a repository, grant it repository `Administration: Read`, and each of those settings becomes a badge. It reports what the GitHub API says about a setting and nothing more: no code is scanned, and no value is inferred that the API didn't give.
+
+## See it in action
+
+The badges below are live, and they belong to this repository. They come from the public instance at `policychecks.reponomics.org`.
+
+**Actions and releases**
+
+
[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/sha-pinning-required/details.json)
-[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/web-commit-signoff-required/details.json)
-[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/community-health/details.json)
+[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/immutable-releases/details.json)
+
+
+**Secret protection**
+
+
[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/secret-scanning-enabled/details.json)
[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/secret-push-protection-enabled/details.json)
+
+
+**Default branch rules**
+
+
[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/default-branch-force-pushes-blocked/details.json)
[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/default-branch-signed-commits-required/details.json)
[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/default-branch-linear-history-required/details.json)
@@ -19,146 +47,210 @@
[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/default-branch-status-checks-required/details.json)
-PolicyChecks is a badge service and validation endpoint that checks the current status of a repository's administrative settings, giving maintainers a convenient way to show that OSS best practices are a matter of policy.
-
-## How it Works
+**Repository and community**
-PolicyChecks uses a GitHub app that requests repository `Administration: Read` permissions so that it can query the GitHub REST API for information about repo settings that public badge services are otherwise unable to provide.
-
-For example, in its documentation about the [secure use](https://docs.github.com/en/actions/reference/security/secure-use#using-third-party-actions) of GitHub Actions, GitHub recommends pinning actions to a full-length commit SHA. Administrators of repositories and organizations are able to configure repositories so that full-SHA-pinned actions are required (when enabled, workflows with actions that do not satisfy this criterion will fail). By installing PolicyChecks, a repo can display a badge that shows whether that setting is enabled or not.
+
+[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/web-commit-signoff-required/details.json)
+[](https://policychecks.reponomics.org/github/reponomics/PolicyChecks/community-health/details.json)
+
-
-
-
-
-
+Every badge links to its `details.json`, which names the GitHub endpoint and the fields the result came from.
-
+## Quick start
-## PolicyChecks Badges
+**1. Install the GitHub App**
-The following table describes the set of badges that PolicyChecks currently supports. PolicyChecks queries repository-based API endpoints. Some of the settings reported on have their own unique endpoint; some are included in responses returned by a general `repos/OWNER/REPO` endpoint; others are included on the basis of `branch ruleset` endpoints evaluated relative to the default branch; and, for good measure, we also include the response from GitHub's public community profile health score endpoint (`repos/OWNER/REPO/community/profile`). Although we only request _repository_ `Administration: Read` permission, and query repository endpoints, our internal probes indicate that the repository endpoints queried will return positive results for settings that are enabled at the _organization_ level as well, so long as they are configured by the organization to apply to the repository. Note that for any ruleset-based settings, or those that pertain to a specific _ref_, PolicyChecks evaluates the setting with respect to the repository's default branch.
+Install [PolicyChecks](https://github.com/apps/policychecks) on the repositories you want badges for. The App asks for repository `Administration: Read` and nothing else.
-If the GitHub API provides an endpoint that reliably tracks a specific repo setting, and the response from that API contains a field that clearly establishes whether a given setting is enabled or disabled, then when the PolicyChecks service identifies a positive response, the badge will indicate that the setting is `enabled`. If a response clearly indicates that a particular setting is _not_ enabled for that setting and repository, the badge will show `disabled`. If it receives any other response, including authorization failure, general API request failure, rate-limit throttling, or if the response is in any way ambiguous, the badge will instead simply show `unknown`. Similar rules are applied when reporting on the repository's community health profile score, except instead of `enabled`/`disabled`, a non-`unknown` response will be a percentage expressed as a fraction, in the following shape: `NN / 100`.
+**2. Add a badge to your README**
-| Check | Repo Setting Description | API endpoint |
-| --- | --- | --- |
-| Immutable releases | Disallow assets and tags from being modified once a release is published | `/repos/{owner}/{repo}/immutable-releases` |
-| SHA pinning | Require actions to be pinned to a full-length commit SHA | `/repos/{owner}/{repo}/actions/permissions` |
-| Web signoff | Require contributors to sign off on web-based commits | `/repos/{owner}/{repo}` |
-| Secret scanning | Get notified when a secret is pushed to a repository | `/repos/{owner}/{repo}` |
-| Secret push protection | Block commits that contain supported secrets | `/repos/{owner}/{repo}` |
-| Force pushes blocked | Prevent users with push access from force pushing to refs | `/repos/{owner}/{repo}/rules/branches/{branch}` |
-| Signed commits | Commits pushed to matching refs must have verified signatures | `/repos/{owner}/{repo}/rules/branches/{branch}` |
-| Linear history | Prevent merge commits from being pushed to matching refs | `/repos/{owner}/{repo}/rules/branches/{branch}` |
-| Deletion blocked | Only allow users with bypass permissions to delete matching refs | `/repos/{owner}/{repo}/rules/branches/{branch}` |
-| Pull request required | Require all commits to be made to a non-target branch and submitted via a pull request before they can be merged | `/repos/{owner}/{repo}/rules/branches/{branch}` |
-| Status checks | Require status checks to pass before the default branch is updated | `/repos/{owner}/{repo}/rules/branches/{branch}` |
-| Community health | A percentage of how many of GitHub's recommended community health files are present | `/repos/{owner}/{repo}/community/profile` |
+Pick a badge ID from [Supported checks](#supported-checks) and substitute your own `OWNER` and `REPO`:
-## Endpoints
+```markdown
+[](https://policychecks.reponomics.org/github/OWNER/REPO/sha-pinning-required/details.json)
+```
-Each supported badge has a stable badge ID, such as `sha-pinning-required` or `community-health`, and supports the same endpoint shape:
+The URL pattern is the same for every badge:
```text
-GET /github/{owner}/{repo}/{badge-id}.svg # Returns an SVG badge with status `enabled`, `disabled`, or `unknown`
-GET /github/{owner}/{repo}/{badge-id}.json # Returns a Shields-compatible JSON result for use in custom badge tooling
-GET /github/{owner}/{repo}/{badge-id}/details.json # Returns the PolicyChecks evaluation record and selected response-derived details
-GET /github/{owner}/{repo}/info.json # A general JSON response that provides collective information about multiple different settings
+https://policychecks.reponomics.org/github/OWNER/REPO/BADGE_ID.svg
```
-Use the SVG endpoint for badges, the Shields-compatible JSON endpoint for badge tooling, and the details endpoint for the underlying PolicyChecks evaluation record. Details JSON identifies the badge as `badgeId` and omits internal classification fields. README badges can link directly to their details JSON:
-
-```markdown
-[](https://policychecks.reponomics.org/github/OWNER/REPO/immutable-releases/details.json)
+**3. Commit and push**
+
+The badge should appear after the service evaluates the repository. If it shows `unknown`, see [Status semantics](#status-semantics) — the most common cause is that the App is not installed on that repository yet.
+
+## Supported checks
+
+| Check | What it reports | Badge ID | GitHub REST source |
+| --- | --- | --- | --- |
+| SHA pinning | Actions must be pinned to a full-length commit SHA | `sha-pinning-required` | `/repos/{owner}/{repo}/actions/permissions` |
+| Immutable releases | Assets and tags cannot be modified once a release is published | `immutable-releases` | `/repos/{owner}/{repo}/immutable-releases` |
+| Secret scanning | Secret scanning is enabled | `secret-scanning-enabled` | `/repos/{owner}/{repo}` |
+| Secret push protection | Pushes containing supported secrets are blocked | `secret-push-protection-enabled` | `/repos/{owner}/{repo}` |
+| Web signoff | Web-based commits require a sign-off | `web-commit-signoff-required` | `/repos/{owner}/{repo}` |
+| Force pushes blocked | Force pushes to the default branch are blocked | `default-branch-force-pushes-blocked` | `/repos/{owner}/{repo}/rules/branches/{branch}` |
+| Signed commits | Commits to the default branch need verified signatures | `default-branch-signed-commits-required` | `/repos/{owner}/{repo}/rules/branches/{branch}` |
+| Linear history | Merge commits are blocked on the default branch | `default-branch-linear-history-required` | `/repos/{owner}/{repo}/rules/branches/{branch}` |
+| Deletion blocked | Only bypass actors may delete the default branch | `default-branch-deletion-blocked` | `/repos/{owner}/{repo}/rules/branches/{branch}` |
+| Pull request required | Changes must reach the default branch through a pull request | `default-branch-pull-request-required` | `/repos/{owner}/{repo}/rules/branches/{branch}` |
+| Status checks | Status checks must pass before the default branch updates | `default-branch-status-checks-required` | `/repos/{owner}/{repo}/rules/branches/{branch}` |
+| Community health | GitHub's community profile score, rendered as `NN/100` | `community-health` | `/repos/{owner}/{repo}/community/profile` |
+
+Rule-based checks are evaluated against the repository's default branch.
+
+## How it works
+
+```mermaid
+flowchart LR
+ A[README badge request] --> B[PolicyChecks]
+ B -->|cached result| F[SVG or JSON response]
+ B --> C[GitHub App installation token]
+ C --> D[GitHub repository REST API]
+ D --> E["enabled / disabled / unknown"]
+ E --> F
```
-
-
-