docs: update spectrum-ts documentation for v5.0.0 (#89)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: photon-action-bot[bot]

docs-src/spectrum-ts/content.mdx.vel

@@ -1,14 +1,14 @@
 ---
 title: "Content"
-description: "Build text, markdown, attachments, voice, contacts, polls, rich links, groups, replies, edits, unsends, typing indicators, rename, avatar, and platform-specific content for outgoing messages"
+description: "Build text, markdown, attachments, voice, contacts, polls, rich links, app link cards, groups, replies, edits, unsends, typing indicators, rename, avatar, and platform-specific content for outgoing messages"
 ---
 
 import { TypeTooltip } from "/snippets/type-tooltip.mdx";
 
 {% set ci = symbol("ts:spectrum-ts#ContentInput") %}
 {% set cb = symbol("ts:spectrum-ts#ContentBuilder") %}
 
-Spectrum exposes a family of content builders — `text`, `markdown`, `attachment`, `voice`, `contact`, `richlink`, `poll`, `group`, `custom`, `reaction`, `reply`, `edit`, `unsend`, `typing`, `rename`, and `avatar` — plus a string shortcut that's equivalent to `text()`. Any API that takes a <TypeTooltip name="ContentInput" type={`{{ ci.signature }}`} /> accepts a plain string or a <TypeTooltip name="ContentBuilder" type={`{{ cb.signature }}`} />.
+Spectrum exposes a family of content builders — `text`, `markdown`, `attachment`, `voice`, `contact`, `richlink`, `app`, `poll`, `group`, `custom`, `reaction`, `reply`, `edit`, `unsend`, `typing`, `rename`, and `avatar` — plus a string shortcut that's equivalent to `text()`. Any API that takes a <TypeTooltip name="ContentInput" type={`{{ ci.signature }}`} /> accepts a plain string or a <TypeTooltip name="ContentBuilder" type={`{{ cb.signature }}`} />.
 
 ## Text
 
@@ -229,6 +229,18 @@ await space.send(richlink("https://example.com/article"));
   | `cover()` | `() => Promise<{ mimeType?, read(), stream() } \| undefined>` | OG image. |
 </Accordion>
 
+## App link cards
+
+Send a URL as an app-style link card. On iMessage, the URL renders as a native mini-app card; on Slack, Telegram, WhatsApp, and terminal, it falls back to the plain URL.
+
+```ts
+import { app } from "spectrum-ts";
+
+await space.send(app("https://example.com/deep-link"));
+```
+
+Use `app()` when you want to present a link as a tappable card rather than an inline URL. For richer iMessage cards with layout control, see [Mini-app cards](/spectrum-ts/providers/imessage#mini-app-cards).
+
 ## Polls
 
 {% set pollChoiceInput = symbol("ts:spectrum-ts#PollChoiceInput") %}

docs-src/spectrum-ts/getting-started.mdx.vel

@@ -9,6 +9,8 @@ import { TypeTooltip } from "/snippets/type-tooltip.mdx";
 
 ## Installation
 
+`spectrum-ts` is the batteries-included package — it bundles the runtime and every official provider.
+
 <CodeGroup>
 ```bash npm
 npm install spectrum-ts
@@ -27,6 +29,14 @@ bun add spectrum-ts
 ```
 </CodeGroup>
 
+For a leaner install, depend on `@spectrum-ts/core` plus only the providers you need:
+
+```bash
+bun add @spectrum-ts/core @spectrum-ts/imessage @spectrum-ts/telegram
+```
+
+Either way, the `spectrum-ts/providers/<platform>` import paths work as long as the matching provider package is installed.
+
 Requires TypeScript 5 or later (TypeScript 6 is also supported).
 
 ## Core concepts
@@ -125,6 +135,21 @@ for await (const [space, message] of app.messages) {
 
 Messages from every provider merge into the single `app.messages` stream. The `message.platform` field identifies the source.
 
+## Logging
+
+Spectrum emits structured logs across the core runtime and providers. Control the verbosity with `logLevel`:
+
+```ts
+const app = await Spectrum({
+  projectId: process.env.PROJECT_ID!,
+  projectSecret: process.env.PROJECT_SECRET!,
+  providers: [imessage.config()],
+  logLevel: "debug",
+});
+```
+
+Log output is sanitized — sensitive fields like tokens and secrets are redacted from error attributes before they reach any log destination.
+
 ## Telemetry
 
 Spectrum has built-in [OpenTelemetry](https://opentelemetry.io/) instrumentation. Enable it by passing `telemetry: true`:

docs-src/spectrum-ts/introduction.mdx.vel

@@ -23,7 +23,7 @@ A user might message you in iMessage today, WhatsApp tomorrow, and your app next
 
 With Spectrum, you run one agent server and add providers for the interfaces you want to support. Each provider connects a native interface to the same Spectrum API, so your agent can feel consistent everywhere.
 
-Today, Spectrum supports iMessage, WhatsApp Business, Telegram, and terminal development. The same model is built for more interfaces over time: Slack, Discord, websites, apps, phone calls, meetings, and hardware like HomePod.
+Today, Spectrum supports iMessage, WhatsApp Business, Telegram, Slack, and terminal development. The same model is built for more interfaces over time: Discord, websites, apps, phone calls, meetings, and hardware like HomePod.
 
 ## Supported interfaces today
 
@@ -39,12 +39,15 @@ Spectrum currently includes official providers for:
   <Card title="Telegram" icon="paper-plane" href="/spectrum-ts/providers/telegram">
     Build bots on the Telegram Bot API with inbound webhooks through Fusor.
   </Card>
+  <Card title="Slack" icon="hashtag" href="/spectrum-ts/providers/slack">
+    Connect to Slack workspaces through the Slack API.
+  </Card>
   <Card title="Terminal" icon="terminal" href="/spectrum-ts/providers/terminal">
     Build, test, and demo agents from your local terminal.
   </Card>
 </CardGroup>
 
-You can also build custom providers with `definePlatform`. Use custom providers to bring websites, apps, Slack, Discord, internal tools, or new device interfaces into Spectrum.
+You can also build custom providers with `definePlatform`. Use custom providers to bring websites, apps, Discord, internal tools, or new device interfaces into Spectrum.
 
 <Card title="View all providers" icon="plug" href="/spectrum-ts/providers">
   See the built-in providers and learn how to combine them.

docs-src/spectrum-ts/providers.mdx.vel

@@ -20,6 +20,9 @@ Providers plug into Spectrum's type system and runtime. Each one exports a calla
   <Card title="Telegram" icon="paper-plane" href="/spectrum-ts/providers/telegram">
     Telegram Bot API with Fusor webhooks. Text, media, reactions, replies, typing, and edits.
   </Card>
+  <Card title="Slack" icon="hashtag" href="/spectrum-ts/providers/slack">
+    Slack API with multi-workspace support. Text, media, reactions, replies, typing, and threads.
+  </Card>
 </CardGroup>
 
 ## Combining providers
@@ -30,7 +33,7 @@ Drop any combination into `providers`:
   <Tab title="Aggregate import">
     ```ts
     import { Spectrum } from "spectrum-ts";
-    import { imessage, terminal, whatsappBusiness } from "spectrum-ts/providers";
+    import { imessage, slack, terminal, whatsappBusiness } from "spectrum-ts/providers";
 
     const app = await Spectrum({
       projectId: "...",
@@ -42,6 +45,9 @@ Drop any combination into `providers`:
           phoneNumberId: process.env.WA_NUMBER_ID!,
           appSecret: process.env.WA_SECRET!,
         }),
+        slack.config({
+          tokens: { TEAM_ID: process.env.SLACK_BOT_TOKEN! },
+        }),
         terminal.config(),
       ],
     });
@@ -51,6 +57,7 @@ Drop any combination into `providers`:
     ```ts
     import { Spectrum } from "spectrum-ts";
     import { imessage } from "spectrum-ts/providers/imessage";
+    import { slack } from "spectrum-ts/providers/slack";
     import { terminal } from "spectrum-ts/providers/terminal";
     import { whatsappBusiness } from "spectrum-ts/providers/whatsapp-business";
 
@@ -64,6 +71,9 @@ Drop any combination into `providers`:
           phoneNumberId: process.env.WA_NUMBER_ID!,
           appSecret: process.env.WA_SECRET!,
         }),
+        slack.config({
+          tokens: { TEAM_ID: process.env.SLACK_BOT_TOKEN! },
+        }),
         terminal.config(),
       ],
     });

docs-src/spectrum-ts/providers/imessage.mdx.vel

@@ -318,6 +318,34 @@ const sent = await space.send(customizedMiniApp({
   Mini-app cards require cloud or dedicated mode. In local mode, `customizedMiniApp()` throws an `UnsupportedError`.
 </Note>
 
+## Native contact card sharing
+
+Share the bot account's own iMessage contact card directly in a chat. Use `nativeContactCard()` to build the content, or the `space.shareContactCard()` sugar method on a narrowed iMessage space:
+
+<Tabs>
+  <Tab title="Sugar (space.shareContactCard)">
+    ```ts
+    import { imessage } from "spectrum-ts/providers/imessage";
+
+    const im = imessage(space);
+    await im.shareContactCard();
+    ```
+  </Tab>
+  <Tab title="Canonical (space.send)">
+    ```ts
+    import { nativeContactCard, imessage } from "spectrum-ts/providers/imessage";
+
+    await space.send(nativeContactCard());
+    ```
+  </Tab>
+</Tabs>
+
+This shares the bot's own contact card as it appears in iMessage — recipients can tap it to save the contact. Useful for onboarding flows where you want users to add your bot to their contacts.
+
+<Note>
+  Native contact card sharing requires cloud or dedicated mode. In local mode, `nativeContactCard()` throws an `UnsupportedError`.
+</Note>
+
 ## Fetching attachments
 
 Retrieve an attachment by its iMessage GUID using `getAttachment` on the narrowed platform instance. The returned `Attachment` is lazy — `.read()` and `.stream()` each trigger an independent download, so cache `.read()` if you need the bytes more than once.

docs-src/spectrum-ts/providers/slack.mdx.vel

@@ -0,0 +1,124 @@
+---
+title: "Slack"
+description: "Send and receive messages through the Slack API"
+---
+
+```ts
+import { slack } from "spectrum-ts/providers/slack";
+```
+
+The Slack provider connects your agent to Slack workspaces through the Slack API. It supports multi-workspace installations, text and media messaging, reactions, threaded replies, typing indicators, and edits.
+
+## Config
+
+<Tabs>
+  <Tab title="Single workspace">
+    ```ts
+    slack.config({
+      tokens: {
+        TEAM_ID: "xoxb-your-bot-token",
+      },
+    });
+    ```
+  </Tab>
+  <Tab title="Multi-workspace">
+    ```ts
+    slack.config({
+      tokens: {
+        TEAM_A: process.env.SLACK_TOKEN_A!,
+        TEAM_B: process.env.SLACK_TOKEN_B!,
+      },
+      teams: {
+        TEAM_A: {
+          appId: "A0123456789",
+          botUserId: "U0123456789",
+          grantedScopes: ["chat:write", "channels:history"],
+          teamName: "Team A",
+        },
+        TEAM_B: {
+          appId: "A9876543210",
+          botUserId: "U9876543210",
+          grantedScopes: ["chat:write", "channels:history"],
+          teamName: "Team B",
+        },
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
+
+| Option | Description |
+|---|---|
+| `tokens` | A map of team ID to bot token (`xoxb-...`). At least one entry is required. |
+| `teams` | Optional metadata per team — app ID, bot user ID, granted scopes, and display name. |
+| `endpoint` | Optional custom Slack API base URL. |
+
+## Example
+
+```ts
+import { Spectrum } from "spectrum-ts";
+import { slack } from "spectrum-ts/providers/slack";
+
+const app = await Spectrum({
+  projectId: process.env.PROJECT_ID!,
+  projectSecret: process.env.PROJECT_SECRET!,
+  providers: [
+    slack.config({
+      tokens: { TEAM_ID: process.env.SLACK_BOT_TOKEN! },
+    }),
+  ],
+});
+
+for await (const [space, message] of app.messages) {
+  if (message.content.type === "text") {
+    await space.send(`Echo: ${message.content.text}`);
+  }
+}
+```
+
+## Starting a conversation
+
+Resolve a user by their Slack user ID and open a space. Pass `teamId` as a space parameter to target a specific workspace:
+
+```ts
+const sl = slack(app);
+const user = await sl.user("U0123456789");
+const space = await sl.space.create(user, { teamId: "TEAM_ID" });
+
+await space.send("Hello from Spectrum.");
+```
+
+## Space properties
+
+Slack spaces carry a `teamId` field indicating which workspace the conversation belongs to. Access it through narrowing:
+
+```ts
+for await (const [space, message] of app.messages) {
+  if (message.platform !== "Slack") continue;
+  const slackSpace = slack(space);
+  console.log(slackSpace.teamId);
+}
+```
+
+## Message extras
+
+Narrowed Slack messages expose additional fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `isFromMe` | `boolean` | Whether the message was sent by the bot. |
+| `subtype` | `string` (optional) | Slack message subtype (e.g. `"bot_message"`). |
+| `threadTs` | `string` (optional) | Thread timestamp if the message is in a thread. |
+| `ts` | `string` (optional) | Message timestamp. |
+
+## Supported features
+
+| Feature | Support |
+|---|---|
+| Text messages | Send and receive |
+| Markdown | Send (rendered as Slack mrkdwn) |
+| Media (files, images) | Send and receive |
+| Reactions | Send and receive |
+| Threaded replies | Send and receive |
+| Typing indicators | Send |
+| Message edits | Send and receive |

docs.json

@@ -43,7 +43,8 @@
                   "spectrum-ts/providers/imessage",
                   "spectrum-ts/providers/terminal",
                   "spectrum-ts/providers/whatsapp-business",
-                  "spectrum-ts/providers/telegram"
+                  "spectrum-ts/providers/telegram",
+                  "spectrum-ts/providers/slack"
                 ]
               },
               {