update

docs/client-api.md

@@ -43,6 +43,10 @@ Successful response:
 The first exchange enrolls that host against the authorization. Reusing the
 same code and host fingerprint does not consume another host slot. A different
 fingerprint consumes one slot until the configured limit is reached.
+Package authorizations grant access by stable package slug. The version,
+filename, and checksum in a response are resolved from the current package
+catalog when the code is exchanged; replacing a package does not require a new
+authorization code.
 When `requested_action` or `requested_package` is present, the broker validates
 that entitlement before enrolling the host. Older clients may omit both fields,
 but current clients should always identify what they intend to use.

docs/deployment.md

@@ -134,9 +134,10 @@ replacement directly to Gitea, calculates SHA-256, updates the catalog, removes
 the prior Gitea version, and writes audit events without buffering the installer
 on local disk.
 
-An authorization records the exact version and checksum selected when its code
-is created. Revoke and reissue any active code that included a package after
-replacing that package, because the superseded registry version is removed.
+An authorization grants access to the stable package ID, not a particular
+version. Existing active codes and download sessions resolve the package's
+current registry version and checksum, so they automatically use a replacement
+after it is registered.
 
 The load balancer or Nginx must allow request bodies up to
 `TAPM_MAX_UPLOAD_BYTES` and use a sufficiently long request timeout. The
@@ -163,6 +164,9 @@ technician's Gitea credentials for package operations.
 ## 9. Backup and rotation
 
 - Include `tapm_broker` in the existing Galera backup policy.
+- Audit records are retained indefinitely unless an administrator establishes a
+  database retention policy. The portal can filter the retained history and
+  displays up to the newest 250 matching events.
 - Keep `.env` outside Git and readable only by the service administrator.
 - Rotate both Gitea package tokens and the OAuth secret if either webserver is
   compromised.