add callout to use spectrum

Author: qwerzl

docs-src/advanced-kits/imessage/getting-started.mdx.vel

@@ -3,6 +3,13 @@ title: "Getting Started"
 description: "Install the Advanced iMessage SDK, connect to a server, and send your first message"
 ---
 
+<Note>
+  Most apps should use [Spectrum](/spectrum-ts/getting-started) - it gives you
+  a unified, higher-level API across iMessage, WhatsApp Business, and other
+  platforms. Reach for `@photon-ai/advanced-imessage` directly only when you
+  need low-level iMessage control that Spectrum doesn't expose.
+</Note>
+
 `@photon-ai/advanced-imessage` is an ESM-only TypeScript SDK for the Advanced iMessage v2 gRPC server. It exposes resource-oriented namespaces for messages, chats, groups, attachments, addresses, polls, shared locations, and durable events.
 
 The SDK is intentionally thin: each method maps closely to a server RPC, returns typed public objects, and keeps stream recovery explicit.

docs-src/advanced-kits/whatsapp/getting-started.mdx.vel

@@ -5,6 +5,13 @@ description: "Connect the WhatsApp Business SDK and send your first message"
 
 import { TypeTooltip } from "/snippets/type-tooltip.mdx";
 
+<Note>
+  Most apps should use [Spectrum](/spectrum-ts/getting-started) - it gives you
+  a unified, higher-level API across WhatsApp Business, iMessage, and other
+  platforms. Reach for `@photon-ai/whatsapp-business` directly only when you
+  need low-level WhatsApp control that Spectrum doesn't expose.
+</Note>
+
 `@photon-ai/whatsapp-business` is a TypeScript SDK for the WhatsApp Business API. It connects to our managed gRPC gateway, which fronts Meta's Cloud API — you get typed message sending, a resumable event stream, and media handling without wiring webhooks yourself.
 
 ## Installation

docs-src/opensource/imessage-kit.mdx.vel

@@ -8,10 +8,12 @@ import { TypeTooltip } from "/snippets/type-tooltip.mdx";
 `@photon-ai/imessage-kit` is an MIT-licensed, macOS-only SDK that talks directly to the local Messages database and AppleScript bridge. Use it when you want to read, send, and automate iMessage on a Mac you control — automation tools, AI agents, chat-first apps.
 
 <Note>
-  For remote iMessage delivery, threaded replies, tapbacks, edits / unsends, and
-  live typing indicators, use
-  [`@photon-ai/advanced-imessage`](/advanced-kits/imessage/getting-started)
-  instead. That SDK talks to a hosted bridge and doesn't require macOS.
+  This SDK is for talking to iMessage **locally on a Mac you control**. If you
+  want remote/hosted iMessage delivery, threaded replies, tapbacks, edits /
+  unsends, and live typing indicators, use
+  [Spectrum](/spectrum-ts/getting-started) for a unified API across platforms,
+  or [`@photon-ai/advanced-imessage`](/advanced-kits/imessage/getting-started)
+  when you need low-level iMessage control.
 </Note>
 
 ## Requirements

docs.json

@@ -67,7 +67,7 @@
         "tab": "Platform SDKs",
         "groups": [
           {
-            "group": "Advanced kits",
+            "group": "Advanced Kits",
             "pages": [
               {
                 "group": "iMessage",

legacy/imessage.mdx

@@ -3,7 +3,14 @@ title: "iMessage (Legacy)"
 description: "Documentation for the legacy @photon-ai/advanced-imessage-kit SDK"
 ---
 
-`@photon-ai/advanced-imessage-kit` is the legacy HTTP + Socket.IO-based iMessage SDK. For new projects, use [`@photon-ai/advanced-imessage`](/advanced-kits/imessage/getting-started) instead.
+`@photon-ai/advanced-imessage-kit` is the legacy HTTP + Socket.IO-based iMessage SDK and is no longer recommended for new projects.
+
+<Note>
+  For new projects, use [Spectrum](/spectrum-ts/getting-started) for a unified,
+  higher-level API across platforms, or
+  [`@photon-ai/advanced-imessage`](/advanced-kits/imessage/getting-started) when
+  you need low-level iMessage control.
+</Note>
 
 ## Installation