docs(rate_limit): sync the README with the design doc

  fails open like any other, so a rule whose `ban_for` cannot resolve stops

  blocking entirely: watch `errors_total` after changing one.

  Take care combining `ban_for` with `cost:`. One expensive call can cross the

  limit on its own, and with a ban attached that costs the caller the whole ban

  rather than a single rejection. Checking with `peek` first has the same edge,

  since the call it deliberately lets through is enough to start a ban. Bans

  suit counting discrete failures, such as bad credentials, better than they

  suit variable-cost resource limits.

### Redis keys

Each matched check writes a key shaped:

| metric                                              | type    | labels                                       | meaning                                                              |

|-----------------------------------------------------|---------|----------------------------------------------|----------------------------------------------------------------------|

| `gitlab_labkit_rate_limiter_checks_total`           | counter | `rate_limiter`, `action`, `matched`, `error` | Exactly one increment per `check` call, including fail-open. `action` is what the caller should do (`"allow"` or `"block"`); `matched` and `error` are `"true"`/`"false"`. |

| `gitlab_labkit_rate_limiter_rule_evaluations_total` | counter | `rate_limiter`, `rule`, `action`, `result`   | One increment per evaluated rule (plus one per matched `:skip` rule). `action` is the configured rule action (`"limit"`, `"log"`, `"skip"`); `result` is what the evaluation decided (`"allow"`, `"block"`, `"log"`, `"skip"` — see the Actions table). |

| `gitlab_labkit_rate_limiter_rule_evaluations_total` | counter | `rate_limiter`, `rule`, `action`, `result`   | One increment per evaluated rule (plus one per matched `:skip` rule). `action` is the configured rule action (`"limit"`, `"log"`, `"skip"`); `result` is what the evaluation decided (`"allow"`, `"block"`, `"log"`, `"skip"`, `"banned"` — see the Actions table). |

| `gitlab_labkit_rate_limiter_calls_total`            | counter | `rate_limiter`, `rule`, `action`             | **Deprecated** — superseded by `checks_total` + `rule_evaluations_total`. Historical per-rule counter: one increment per counted rule (plus one per matched `:skip` rule), `rule="unmatched", action="allow"` when no rule matched. Emitted unchanged during the transition. |

| `gitlab_labkit_rate_limiter_errors_total`           | counter | `rate_limiter`                               | **Deprecated** — use `checks_total{error="true"}`. Fail-open events (any `StandardError` in the labkit path); still the only error metric for `peek`. |

| `gitlab_labkit_rate_limiter_limit`                  | gauge   | `rate_limiter`, `rule`                       | Resolved limit at the last check (useful when `limit:` is callable). |

      # clearing after a success knows who succeeded, not which rules matched.

      #

      # @param identifier [Identifier, Hash] caller attributes

      # @return [Integer] number of Redis keys removed, 0 on Redis error

      # @return [Integer] number of Redis keys removed; on a Redis error, those

      #   removed before it failed

      def clear(identifier)

        @evaluator.clear(to_identifier(identifier))

      end