docs: describe the write-ahead audit model and bring the contract files up to date

docs/architecture.md

@@ -21,7 +21,7 @@ GiteaExecutor                         (gitea/executor.py)
 Gitea REST API (/api/v1)
 ```
 
-Every tool call ends in one audit event, and every result is wrapped in the same envelope.
+Every tool call is audited (a write-ahead `tool_call_started` entry, then one `tool_invocation` entry with the outcome), and every result is wrapped in the same envelope.
 
 ## Catalog
 

docs/raw-api.md

@@ -26,12 +26,12 @@ because credentials belong in the identity, not in the URL.
 ## Behaviour
 
 - It goes through the same executor as every generated tool: the identity's token, no redirects,
-  response limits, redaction and secret masking, the result envelope and one audit event.
+  response limits, redaction and secret masking, the result envelope and the same audit entries (`tool_call_started`, then `tool_invocation`).
 - There is no allow list of paths and no write classification: with full access, the token's
   scopes and the identity's Gitea permissions are the limit.
 - `READ_ONLY=true` keeps the tool listed but it accepts only `GET`.
 - `TOOLSETS` without `misc`, or `DISABLED_TOOLS=gitea_api_request`, removes it.
-- The audit event records the method and the path, so it is visible which endpoint was called.
+- The audit entry records the method and the path, so it is visible which endpoint was called.
 
 ## Example
 

docs/troubleshooting.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 Start with the result of the failing call: errors carry `error.status`, `error.kind` and
-Gitea's sanitized message, and the audit log has one event per call (see
+Gitea's sanitized message, and the audit log has a result entry (`tool_invocation`) per call, preceded by a `tool_call_started` entry (see
 [audit-logging.md](audit-logging.md)).
 
 ## The server does not start