@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Documentation
+
+- Documentation cleanup and simplification.
+
 ## 0.5.0 - 2026-09-03
 
 0.5.x runs on NetBox 4.7, 0.4.x stays on NetBox 4.6, and no version of NetBox runs both. See the [compatibility matrix](https://antoinekh.github.io/netbox-change-control/compatibility/).
 
@@ -141,20 +141,7 @@ Both are custom actions, and both are optional.
 | `netbox_change_control.bypass_policy` | Write outside a branch while `protect_main` is enabled. | Automation accounts, and the people who run an incident. |
 | `netbox_change_control.override_window_changerequest` | Merge a change request outside its change window. | Whoever is allowed to break a change freeze. |
 
-To grant them, go to **Administration > Permissions > Add**, and enter the action in the *additional actions* field rather than ticking view, add, change or delete:
-
-| Exemption | Object type | Action to enter |
-|---|---|---|
-| Write directly to main | Change Control > Policy | `bypass` |
-| Merge outside the change window | Change Control > Change Request | `override_window` |
-
-!!! info "Important"
-
-    The trailing part of a custom permission name has to be a real model name, because NetBox splits on the last underscore. That is why the bypass lives on `Policy` and the window override on `ChangeRequest`, rather than on names that would read better.
-
-!!! note
-
-    Superusers hold every permission, so they are exempt from `protect_main` and from every change window without being granted anything.
+Neither is a tick box on the permission form: the action is typed into *additional actions*, and the object type is not the one the name suggests. See [granting the custom actions](permissions.md#granting-the-custom-actions), which covers **Abandon** and **Reopen** the same way.
 
 ### Setting up groups
 
 
@@ -25,9 +25,7 @@ The two transitions a person makes by hand have an action each, and a permission
 | **Abandon** | The change request page, or `POST /change-requests/{id}/abandon/` | `netbox_change_control.abandon_changerequest` | Draft, Needs review, Approved, Rejected |
 | **Reopen** | The change request page, or `POST /change-requests/{id}/reopen/` | `netbox_change_control.reopen_changerequest` | Abandoned only |
 
-Reopening returns the request to Draft and then recomputes, rather than restoring the status it held before. Its reviews may have gone stale and its policies may have changed while it was set aside, so the honest answer has to be worked out again.
-
-Completed is never reopened. It records a merge that actually happened, and taking it back up would invite a second merge of a branch already in main.
+Reopening returns the request to Draft and recomputes from there, rather than restoring the status it held before. Completed is never reopened. See [what the states mean](#what-the-states-mean).
 
 ## The lifecycle
 
 
@@ -115,12 +115,7 @@ curl -X PATCH "$NETBOX/api/plugins/change-control/policies/$POLICY_ID/" \
   -d '{"checks": ["peer-signoff"]}'
 ```
 
-`checks` replaces the whole list, so send every name the policy should require, not just the new one. Read it back first if you are adding to an existing set:
-
-```bash
-curl -s -H "Authorization: Token $TOKEN" \
-  "$NETBOX/api/plugins/change-control/policies/$POLICY_ID/" | jq '.checks'
-```
+`checks` replaces the whole list, so send every name the policy should require, not just the new one. See [choosing which checks a policy requires](api.md#choosing-which-checks-a-policy-requires) for adding one without dropping the rest.
 
 The check now runs only on change requests carrying that policy. Elsewhere it has no row, does not run, and does not block. Detach the policy and its check disappears with it.
 
@@ -140,17 +135,7 @@ curl -X PATCH "$NETBOX/api/plugins/change-control/policies/$POLICY_ID/" \
   -d '{"checks": ["cab-approval"]}'
 ```
 
-Every change request carrying that policy now shows a required `cab-approval` check, pending, blocking the merge. Whatever performs the sign-off reports the result the same way any external check does:
-
-```bash
-CHECK_ID=$(curl -s -H "Authorization: Token $TOKEN" \
-  "$NETBOX/api/plugins/change-control/checks/?change_request_id=$CR_ID&name=cab-approval" \
-  | jq -r '.results[0].id')
-
-curl -X PATCH "$NETBOX/api/plugins/change-control/checks/$CHECK_ID/" \
-  -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
-  -d '{"status": "success", "summary": "Approved at the 14:00 CAB", "details_url": "https://cab.example.com/2026-08-26"}'
-```
+Every change request carrying that policy now shows a required `cab-approval` check, pending, blocking the merge. Whatever performs the sign-off reports the result the same way any external check does: see [reporting a check result](api.md#reporting-a-check-result).
 
 This is how to require a pipeline, a ticket, or a person outside NetBox for one class of change only, without wiring that requirement into every change request. See [checks reported by an external system](custom-checks.md#checks-reported-by-an-external-system) for the full contract, including why a reporter cannot decide whether its own check counts.
 
 
@@ -97,19 +97,11 @@ The merge gate does not depend on this cache; it re-evaluates. The cache is for
 
 ### Repeated work is collapsed, not deferred
 
-Refreshing a change request is correct on every event that could change its answer, and doing
-it per event is what keeps the cached status honest without any caller having to remember.
-The cost is that one user action is often many events: attaching policies is one signal each.
+Refreshing a change request is correct on every event that could change its answer, and doing it per event is what keeps the cached status honest without any caller having to remember. The cost is that one user action is often many events: attaching policies is one signal each.
 
-`netbox_change_control/batching.py` collapses those bursts. A caller that knows it is about to
-cause one wraps it in `batched()`, and each affected change request is refreshed once when the
-block ends.
+`netbox_change_control/batching.py` collapses those bursts. A caller that knows it is about to cause one wraps it in `batched()`, and each affected change request is refreshed once when the block ends.
 
-It deliberately does not use `transaction.on_commit`. Deferring past the commit would mean a
-request's checks are not yet run when the view that submitted it renders the next page, and it
-would make every test that asserts on a check result depend on `captureOnCommitCallbacks`.
-Outside a block the refresh is immediate, so nothing changes for the callers which are not
-part of a burst.
+It deliberately does not use `transaction.on_commit`. Deferring past the commit would mean a request's checks are not yet run when the view that submitted it renders the next page, and it would make every test that asserts on a check result depend on `captureOnCommitCallbacks`. Outside a block the refresh is immediate, so nothing changes for the callers which are not part of a burst.
 
 ### Staleness is derived from a snapshot, not a flag
 
@@ -119,13 +111,9 @@ This is preferable to a `stale` boolean maintained by signals, because a flag ca
 
 ### `protect_main` listens to every write
 
-`protect_main_on_save` and `protect_main_on_delete` are registered without a sender, so they
-run for every model write anywhere in NetBox. That is deliberate rather than an oversight: the
-set of protected models is not knowable at import time, because it depends on which models
-branching supports and on `protect_main_scope`, which is configuration.
+`protect_main_on_save` and `protect_main_on_delete` are registered without a sender, so they run for every model write anywhere in NetBox. That is deliberate rather than an oversight: the set of protected models is not knowable at import time, because it depends on which models branching supports and on `protect_main_scope`, which is configuration.
 
-The cost is bounded by ordering the guard cheaply. The first thing each receiver does is read
-`protect_main`, and with it off, which is the default, that is the whole cost of the call.
+The cost is bounded by ordering the guard cheaply. The first thing each receiver does is read `protect_main`, and with it off, which is the default, that is the whole cost of the call.
 
 ### `protect_main_scope`
 
 
@@ -4,11 +4,7 @@ Another plugin can add content to this plugin's pages, and checks to its merge g
 
 ## What this plugin injects elsewhere
 
-The traffic runs both ways. This plugin uses the same hooks to put its own content on
-netbox-branching's branch page: the change request governing that branch, its status, what is
-still outstanding and a link to it, or an offer to open one when there is none. It uses the
-`alerts` and `right_page` hooks, and `branch_page_placement` decides which of them renders, so
-a deployment can compare the two or turn both off. See `netbox_change_control/template_content.py`.
+The traffic runs both ways. This plugin uses the same hooks to put its own content on netbox-branching's branch page: the change request governing that branch, its status, what is still outstanding and a link to it, or an offer to open one when there is none. It uses the `alerts` and `right_page` hooks, and `branch_page_placement` decides which of them renders, so a deployment can compare the two or turn both off. See `netbox_change_control/template_content.py`.
 
 ## Injecting content into a page
 
 
@@ -8,22 +8,6 @@
 
 This is the NetBox 4.7 line. For NetBox 4.6, stay on the 0.4.x line; the two do not overlap, because netbox-branching 1.1.x and 1.2 do not either. [The compatibility matrix](compatibility.md) has every release.
 
-## Upgrading from the 4.6 line
-
-There is no version of NetBox which 0.4.x and 0.5.x share, so this is a move between lines rather than an ordinary upgrade. NetBox 4.7 replaced django-mptt with a PostgreSQL `ltree` implementation and dropped the `lft`, `rght`, `tree_id` and `level` columns. netbox-branching 1.1.x reads those columns and cannot run on 4.7; netbox-branching 1.2 rewrote that part and requires 4.7. The plugin sits on top of whichever is installed and inherits the split.
-
-Upgrade NetBox and netbox-branching together, then the plugin. Follow NetBox's own upgrade guide for the rest; these are only the points this plugin adds to it.
-
-1. **Check the platform.** NetBox 4.7 requires PostgreSQL 15 or later and Redis 6.0 or later. It installs the PostgreSQL `ltree` extension on the first migration, which needs the `CREATE` privilege on the database. A NetBox user which owns its database already holds it.
-2. **Drain the queues before restarting the workers.** NetBox 4.7 removed an argument from the function a queued webhook job calls, so a job still enqueued across the restart fails.
-3. **Plan a window.** The 4.7 migration backfills every hierarchical table, then rebuilds the config context cache for every device and virtual machine. Both scale with the size of the database, and neither is reversible in practice.
-4. **Merge or delete open branches first, if you can.** A branch schema is a copy of the main schema as it stood when the branch was created, and carrying one across a migration of this size is the least tested path there is.
-5. **Then run `manage.py migrate netbox_change_control`.** The one migration this release adds records a field change NetBox made to a base class. It writes no data and takes no time.
-
-Nothing in the plugin's own data changes. Change requests, policies, rules, reviews, comments and checks all survive untouched.
-
-Two things behave differently afterwards, both covered in the [changelog](changelog.md): a webhook payload no longer carries the top-level `username` and `request_id` keys, and [policy conditions](policy-conditions.md) can read the transition itself.
-
 ## Installation
 
 Install the package into the NetBox virtual environment, then enable it **before** `netbox_branching`, which must stay last in the list:
@@ -71,7 +55,23 @@ Every setting is optional. The defaults are safe to install on an existing NetBo
 | `enforce_merge_gate` | `True` | Refuse to merge a branch without an approved change request. |
 | `notify_reviewers` | `True` | Raise NetBox notifications on status transitions. |
 | `branch_page_placement` | `['right_page']` | Where a branch page shows its change request. `right_page` puts it in a card in the right-hand column, `alerts` puts it across the top of the page, both shows both, and `[]` shows neither. |
-| `enable_builtin_checks` | `True` | Which built-in checks are available to policies. `True` for all, `False` for none, or a list of names. A check applies only where a policy names it. |
-| `required_external_checks` | `[]` | Checks reported through the REST API. Each blocks the merge until reported. |
+| `enable_builtin_checks` | `True` | Which built-in checks are available to policies. `True` for all, `False` for none, or a list of names from `has-changes`, `no-conflicts`, `not-stale` and `threads-resolved`. A check applies only where a policy names it. |
+| `required_external_checks` | `[]` | Checks reported through the REST API. Each entry is a name, or a `(name, label)` pair. Each blocks the merge until reported. |
 | `enable_auto_merge` | `True` | Allow requests that opt in to merge themselves once every gate passes. When `False`, the periodic job is not registered at all. |
 | `auto_merge_interval` | `10` | Minutes between automatic merge sweeps. Keep every change window longer than this. Takes effect when the worker restarts. |
+
+## Upgrading from the 4.6 line
+
+There is no version of NetBox which 0.4.x and 0.5.x share, so this is a move between lines rather than an ordinary upgrade. NetBox 4.7 replaced django-mptt with a PostgreSQL `ltree` implementation and dropped the `lft`, `rght`, `tree_id` and `level` columns. netbox-branching 1.1.x reads those columns and cannot run on 4.7; netbox-branching 1.2 rewrote that part and requires 4.7. The plugin sits on top of whichever is installed and inherits the split.
+
+Upgrade NetBox and netbox-branching together, then the plugin. Follow NetBox's own upgrade guide for the rest; these are only the points this plugin adds to it.
+
+1. **Check the platform.** NetBox 4.7 requires PostgreSQL 15 or later and Redis 6.0 or later. It installs the PostgreSQL `ltree` extension on the first migration, which needs the `CREATE` privilege on the database. A NetBox user which owns its database already holds it.
+2. **Drain the queues before restarting the workers.** NetBox 4.7 removed an argument from the function a queued webhook job calls, so a job still enqueued across the restart fails.
+3. **Plan a window.** The 4.7 migration backfills every hierarchical table, then rebuilds the config context cache for every device and virtual machine. Both scale with the size of the database, and neither is reversible in practice.
+4. **Merge or delete open branches first, if you can.** A branch schema is a copy of the main schema as it stood when the branch was created, and carrying one across a migration of this size is the least tested path there is.
+5. **Then run `manage.py migrate netbox_change_control`.** The one migration this release adds records a field change NetBox made to a base class. It writes no data and takes no time.
+
+Nothing in the plugin's own data changes. Change requests, policies, rules, reviews, comments and checks all survive untouched.
+
+Two things behave differently afterwards, both covered in the [changelog](changelog.md): a webhook payload no longer carries the top-level `username` and `request_id` keys, and [policy conditions](policy-conditions.md) can read the transition itself.
@@ -62,7 +62,7 @@ So a change approved at midday with a window opening at 21:00 does merge at 21:0
 
 Only ever one job per branch. A single write can reach the automatic merge by more than one route, and the request is still Approved at the second arrival because the merge has only been queued and not yet run. A queued, scheduled or running merge for the branch stops another being added.
 
-The merge is **enqueued as a background job**, the same path the branching plugin's own merge button takes. It is never run inline: auto-merge is reached from a signal, so merging directly would run a whole branch merge inside the web request that submitted the final review.
+The merge is **enqueued as a background job**, the same path the branching plugin's own merge button takes. It is never run inline: auto-merge is reached from a signal, so merging directly would run a whole branch merge inside the web request that submitted the final review. It runs as the requester, so the changelog records the merge against the person who asked for it.
 
 If the branch changes during the wait, the approvals go stale, the status returns to Needs review, and the evening merge does not happen. Approval is only valid for the branch state it was given against.
 
@@ -94,6 +94,4 @@ The immediate trigger does not save you here. It only fires when the final appro
 
 Fix it either way round: widen the window, or lower `auto_merge_interval`. Leave some margin rather than matching them exactly, because a busy worker can run a sweep late.
 
-Setting `enable_auto_merge` to `False` skips registering the job entirely, so a site that does not use auto-merge gets no periodic job and no Job records from this plugin.
-
-The merge runs as the requester. Set `enable_auto_merge` to `False` to disable the feature globally without editing any request.
+Setting `enable_auto_merge` to `False` disables the feature globally without editing any request, and skips registering the job entirely, so a site that does not use auto-merge gets no periodic job and no Job records from this plugin.