add officer-invoiceshelf sidecar

owns the invoiceshelf contract: instance url, sanctum token and the company
header that scopes every request. the platform side is the usual thin
auth+forward proxy at /api/invoiceshelf and holds no credentials.

built against the live 2.4.2 instance rather than the 3.0.0-alpha.1 checkout
in _references — the route allow-list came from artisan route:list on the
running container. they differ: 2.4.2 has estimates/{id}/convert-to-invoice
but no invoices/{id}/convert-to-estimate.

three upstream quirks absorbed here:
- accept: application/json is mandatory, or an unauthenticated request 302s
  to an html login instead of returning 401
- origin/referer must never be sent, or statefulapi() switches to session+csrf
  and every request 419s. the proxy forwards neither.
- a wrong company header does not error, it silently returns another company's
  data. the pinned company is explicit and logged.

document pdfs are repaired: 2.4.2 prefixes them with a literal serialised http
response (201 bytes) inside a body already typed application/pdf. we slice to
the %PDF- magic. the report routes don't have the bug.

resources are an allow-list. backups, disks, modules, update/*, installation/*,
mail config, settings writes and ownership transfer stay unreachable, and the
per-resource action list keeps `send` — which really emails the customer —
from being reachable by accident.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.env.example

@@ -28,6 +28,17 @@ TRANSMISSION_USER=
 TRANSMISSION_PASS=
 # TRANSMISSION_RPC_PATH=/transmission/rpc
 
+# InvoiceShelf (officer-invoiceshelf). The token is a Sanctum personal access token — mint one with
+# POST /api/v1/auth/login {username: <email>, password, device_name} and copy the `token` field. It has
+# full abilities and never expires, so treat it as a password.
+# INVOICESHELF_COMPANY_ID pins which company every request is scoped to. Leave it unset on a
+# single-company install and the sidecar resolves it once at boot and LOGS the choice — worth setting
+# explicitly if you have more than one, because InvoiceShelf does not error on a wrong company header,
+# it silently returns the other company's data.
+INVOICESHELF_URL=https://invoice.example.com
+INVOICESHELF_TOKEN="<sanctum api token, e.g. 1|xxxxxxxx>"
+# INVOICESHELF_COMPANY_ID=1
+
 # slskd (officer-slskd). The key is injected as X-API-Key on every forwarded request.
 SLSKD_URL=http://127.0.0.1:5030
 SLSKD_API_KEY="<slskd api key>"