diff --git a/AGENTS-providers.md b/AGENTS-providers.md
index b6e5895..1181305 100644
--- a/AGENTS-providers.md
+++ b/AGENTS-providers.md
@@ -46,6 +46,17 @@ Defined in `src/core/types.ts`. Every provider exports a class implementing this
 
 The kernel calls `react` and `sendTyping` if they exist; safe to omit when the platform has no analogue.
 
+### Typed errors providers throw
+
+Providers communicate two distinct failure modes back to the kernel via typed errors from `src/core/errors.ts`. Throwing strings or generic `Error`s bypasses the kernel's retry/HTTP-status logic.
+
+| Error                        | Thrown from                  | Carries          | Kernel reaction                                                                                  |
+| ---------------------------- | ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
+| `RateLimitError`             | `send(target, msg)`          | `retryAfterMs`   | In-request retry up to 3× (clamped 100–5000 ms); on final failure returns `429` with `Retry-After` header (seconds) |
+| `AgentNotFoundError`         | `findOrCreateAgentChannel`   | `agentId`        | Returns `404 { error: "Agent not found: <id>" }` from `POST /api/send`                            |
+
+Platforms report rate limits in different units (Discord: ms, Slack: seconds). Convert to ms in a small `toRateLimitError(err)` helper inside the adapter — see the exported helpers in `src/providers/discord/adapter.ts` and `src/providers/slack/adapter.ts` for the pattern (both exported for unit tests).
+
 ### `KernelContext`
 
 What `start(ctx)` receives. Currently exposes:
@@ -155,7 +166,7 @@ Add a `docs/<provider>.md` mirroring `docs/discord.md`'s structure: bot setup, c
 
 - Unit-test the message translation (platform event → `IncomingMessage`) in isolation; don't pull in the platform SDK runtime in tests.
 - The kernel's tests (`src/__tests__/queue.test.ts`, `server.test.ts`, etc.) use `mockProvider.test.ts` as a reference for a minimal `BridgeProvider` implementation — copy that pattern when building a real adapter so the kernel tests stay provider-agnostic.
-- Run the full suite: `npm test` (169 tests at time of writing). All kernel tests should pass with your provider added.
+- Run the full suite: `npm test`. All kernel tests should pass with your provider added.
 
 ## Voice transcription
 
diff --git a/AGENTS.md b/AGENTS.md
index b30bcee..cd80bc6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,6 +24,7 @@ This repo is **Maestro Relay** — a chat-platform-to-Maestro bridge built aroun
 - `src/core/maestro.ts` — `maestro-cli` wrapper
 - `src/core/transcription.ts` — generic ffmpeg + whisper pipeline
 - `src/core/attachments.ts` — provider-agnostic attachment download
+- `src/core/errors.ts` — typed kernel errors (`RateLimitError`, `AgentNotFoundError`) providers throw
 - `src/core/logger.ts`, `src/core/config.ts`, `src/core/splitMessage.ts`
 
 ### Discord provider
diff --git a/docs/api.md b/docs/api.md
index c6c6049..abb8e78 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -98,6 +98,6 @@ Returns `503` with `"status":"not_ready"` if no provider is connected.
 | `405`  | Method not allowed                                             |
 | `413`  | Request body exceeds 1 MB                                      |
 | `415`  | Wrong Content-Type (must be `application/json`)                |
-| `429`  | Rate limited by upstream platform after 3 retries              |
+| `429`  | Rate limited by upstream platform after 3 retries (response includes a `Retry-After` header in seconds) |
 | `500`  | Internal server error                                          |
 | `503`  | The named provider is not connected                            |
diff --git a/docs/architecture.md b/docs/architecture.md
index 99046c4..243cee9 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -68,6 +68,7 @@ The schema upgrades on first start: legacy `agent_channels` (single-PK `channel_
 | `src/core/maestro.ts`                         | `maestro-cli` wrapper                                  |
 | `src/core/transcription.ts`                   | ffmpeg + whisper pipeline                              |
 | `src/core/attachments.ts`                     | Provider-agnostic attachment download                  |
+| `src/core/errors.ts`                          | Typed errors (`RateLimitError`, `AgentNotFoundError`)  |
 | `src/providers/discord/adapter.ts`            | DiscordProvider implementing BridgeProvider            |
 | `src/providers/discord/messageCreate.ts`      | Discord message → IncomingMessage                      |
 | `src/providers/discord/voice.ts`              | Discord voice-message detection                        |