Documentation is outdated and incomplete

First of all, I really like Capslock and what it does! However, I feel that it can be hard to use for outsiders (as evidenced by various issues: #1, https://github.com/google/capslock/issues/35#issuecomment-3869244928, #53, #199, #266). I believe part of the problem is a lack of understanding (#199), a part is outdated documentation (https://github.com/google/capslock/issues/35#issuecomment-3869244928), and another part of it is missing documentation (#266). I think all of these can be addressed, but I'm particularly interested in the latter two gaps (as I personally don't have issues pertaining to the former).

For this reason I would propose (and be interested in contributing, if there's interest) two overarching categories of changes:

1. Simply updating the documentation .
- The [docs](https://github.com/google/capslock/tree/53bc4614488992f21bb733a0c05fd8207239a981/docs) haven't been updated in two years all the while the following changes have been made (probably an incomplete list): https://github.com/google/capslock/commit/526f799231f6db771de99e7ab7639649ce9d7607, https://github.com/google/capslock/commit/2aae6b0b872eee94182a250628176e5c4f9c4d5c, https://github.com/google/capslock/commit/4693513b6ce9b0c702ee74757dbf0a9d94d2b894, https://github.com/google/capslock/commit/4be1944824c868a8bb35fed8f0359201527ab983, https://github.com/google/capslock/commit/2a216f50d53be184889fc987da3faf3ea4f638cc, https://github.com/google/capslock/commit/e505c8d18295dc208f71d4de153da7bae899446b, https://github.com/google/capslock/commit/d8bfb1648b8f31de699f0b0e22e2e26dba9cd382, https://github.com/google/capslock/commit/83127606f2aefcb5c3b83704b9b73598df205233, https://github.com/google/capslock/commit/39f66c672864ed85c701720007496ab350f4b9ca
- [capslock-git-diff](https://github.com/google/capslock/tree/53bc4614488992f21bb733a0c05fd8207239a981/cmd/capslock-git-diff) was created but not included in the documentation.
2. Add examples/instructions for expected workflows, of which I think there are two:
- Auditing: Use Capslock as an auditing tool to help review packages. This is more or less already covered by the existing documentation.
- Integration: Integrate Capslock into a project to track capability changes and be notified of changes. This is, I believe, sorely lacking.

Moreover, some smaller problems I encountered while writing this up:

- There is no link to the documentation in the README (not counting the [link specifically to the caveats](https://github.com/google/capslock/blob/53bc4614488992f21bb733a0c05fd8207239a981/README.md?plain=1#L43)).
- Code snippets in the docs don't have syntax highlighting.