diff --git a/packages/shared/src/telemetry/README.md b/packages/shared/src/telemetry/README.md
index 9dd03c7b569..8d6b57351dc 100644
--- a/packages/shared/src/telemetry/README.md
+++ b/packages/shared/src/telemetry/README.md
@@ -108,6 +108,35 @@ data paths document their own contract in their own file:
 - [Run-Log Events](../../../../doc/run-log-events.md) — events written to the
   local `heartbeat_run_events` table.
 
+## Connector Events
+
+The three `connector.*` events record tool-connector lifecycle and usage for
+connections whose `connection_purpose` is `tool`. The generated contract
+remains the authority for their exact dimensions and optionality. These
+durable rules are not expressible in the generated `string`/`number` types:
+
+- `connector_key` is never a free-text connector name or URL. It carries the
+  connection's `sourceTemplateKey` only when that key resolves to a reviewed
+  first-party catalog definition; every other connection emits the literal
+  `custom`. `connectorKeyForConnection()` in
+  `server/src/services/connector-telemetry.ts` owns this rule.
+- `connector.connection_created` and `connector.connection_updated` are
+  emitted only after the lifecycle write commits, from returned rows. Writes
+  that affect no rows and no-op changes do not emit.
+- `connector.invocation_completed` is emitted once per invocation reaching a
+  terminal status. Its `origin` dimension separates setup tests (the Apps →
+  Test tab) from agent and user calls using the durable test-origin columns.
+  `duration_seconds` is `completedAt - startedAt` rounded to whole seconds and
+  floored at zero; it is omitted when either timestamp is unavailable.
+- Delivery is best-effort and never blocks product writes. A duplicate (never
+  contradictory) `failed` invocation event is possible when failure-path
+  bookkeeping itself fails, and a crash between the product write and emission
+  loses that event. Do not treat these events as an exactly-once ledger.
+
+Use `trackConnectorConnectionCreated()`, `trackConnectorConnectionUpdated()`,
+and `trackConnectorInvocationCompleted()` from `events.ts` to emit these
+events.
+
 ## Dimension Values
 
 Telemetry dimension values must be primitives. Use only the value types allowed