nodmix 2026.5.25

package/docs/start/wizard-cli-reference.md

@@ -0,0 +1,331 @@
+---
+summary: "Complete reference for CLI setup flow, auth/model setup, outputs, and internals"
+read_when:
+  - You need detailed behavior for nodmix onboard
+  - You are debugging onboarding results or integrating onboarding clients
+title: "CLI setup reference"
+sidebarTitle: "CLI reference"
+---
+
+This page is the full reference for `nodmix onboard`.
+For the short guide, see [Onboarding (CLI)](/start/wizard).
+
+## What the wizard does
+
+Local mode (default) walks you through:
+
+- Model and auth setup (OpenAI Code subscription OAuth, Anthropic Claude CLI or API key, plus MiniMax, GLM, Ollama, Moonshot, StepFun, and AI Gateway options)
+- Workspace location and bootstrap files
+- Gateway settings (port, bind, auth, tailscale)
+- Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, iMessage, and other bundled channel plugins)
+- Daemon install (LaunchAgent, systemd user unit, or native Windows Scheduled Task with Startup-folder fallback)
+- Health check
+- Skills setup
+
+Remote mode configures this machine to connect to a gateway elsewhere.
+It does not install or modify anything on the remote host.
+
+## Local flow details
+
+<Steps>
+  <Step title="Existing config detection">
+    - If `~/.nodmix/nodmix.json` exists, choose Keep, Modify, or Reset.
+    - Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`).
+    - CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full` to also remove workspace.
+    - If config is invalid or contains legacy keys, the wizard stops and asks you to run `nodmix doctor` before continuing.
+    - Reset uses `trash` and offers scopes:
+      - Config only
+      - Config + credentials + sessions
+      - Full reset (also removes workspace)
+
+  </Step>
+  <Step title="Model and auth">
+    - Full option matrix is in [Auth and model options](#auth-and-model-options).
+
+  </Step>
+  <Step title="Workspace">
+    - Default `~/.nodmix/workspace` (configurable).
+    - Seeds workspace files needed for first-run bootstrap ritual.
+    - Workspace layout: [Agent workspace](/concepts/agent-workspace).
+
+  </Step>
+  <Step title="Gateway">
+    - Prompts for port, bind, auth mode, and tailscale exposure.
+    - Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
+    - In token mode, interactive setup offers:
+      - **Generate/store plaintext token** (default)
+      - **Use SecretRef** (opt-in)
+    - In password mode, interactive setup also supports plaintext or SecretRef storage.
+    - Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
+      - Requires a non-empty env var in the onboarding process environment.
+      - Cannot be combined with `--gateway-token`.
+    - Disable auth only if you fully trust every local process.
+    - Non-loopback binds still require auth.
+
+  </Step>
+  <Step title="Channels">
+    - [WhatsApp](/channels/whatsapp): optional QR login
+    - [Telegram](/channels/telegram): bot token
+    - [Discord](/channels/discord): bot token
+    - [Google Chat](/channels/googlechat): service account JSON + webhook audience
+    - [Mattermost](/channels/mattermost): bot token + base URL
+    - [Signal](/channels/signal): optional `signal-cli` install + account config
+    - [iMessage](/channels/imessage): `imsg` CLI path + Messages DB access; use an SSH wrapper when the Gateway runs off-Mac
+    - DM security: default is pairing. First DM sends a code; approve via
+      `nodmix pairing approve <channel> <code>` or use allowlists.
+  </Step>
+  <Step title="Daemon install">
+    - macOS: LaunchAgent
+      - Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
+    - Linux and Windows via WSL2: systemd user unit
+      - Wizard attempts `loginctl enable-linger <user>` so gateway stays up after logout.
+      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
+    - Native Windows: Scheduled Task first
+      - If task creation is denied, Nodmix falls back to a per-user Startup-folder login item and starts the gateway immediately.
+      - Scheduled Tasks remain preferred because they provide better supervisor status.
+    - Runtime selection: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.
+
+  </Step>
+  <Step title="Health check">
+    - Starts gateway (if needed) and runs `nodmix health`.
+    - `nodmix status --deep` adds the live gateway health probe to status output, including channel probes when supported.
+
+  </Step>
+  <Step title="Skills">
+    - Reads available skills and checks requirements.
+    - Lets you choose node manager: npm, pnpm, or bun.
+    - Installs optional dependencies (some use Homebrew on macOS).
+
+  </Step>
+  <Step title="Finish">
+    - Summary and next steps, including iOS, Android, and macOS app options.
+
+  </Step>
+</Steps>
+
+<Note>
+If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
+If Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
+</Note>
+
+## Remote mode details
+
+Remote mode configures this machine to connect to a gateway elsewhere.
+
+<Info>
+Remote mode does not install or modify anything on the remote host.
+</Info>
+
+What you set:
+
+- Remote gateway URL (`ws://...`)
+- Token if remote gateway auth is required (recommended)
+
+<Note>
+- If gateway is loopback-only, use SSH tunneling or a tailnet.
+- Discovery hints:
+  - macOS: Bonjour (`dns-sd`)
+  - Linux: Avahi (`avahi-browse`)
+
+</Note>
+
+## Auth and model options
+
+<AccordionGroup>
+  <Accordion title="Anthropic API key">
+    Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
+  </Accordion>
+  <Accordion title="OpenAI Code subscription (OAuth)">
+    Browser flow; paste `code#state`.
+
+    Sets `agents.defaults.model` to `openai/gpt-5.5` through the Codex runtime when model is unset or already OpenAI-family.
+
+  </Accordion>
+  <Accordion title="OpenAI Code subscription (device pairing)">
+    Browser pairing flow with a short-lived device code.
+
+    Sets `agents.defaults.model` to `openai/gpt-5.5` through the Codex runtime when model is unset or already OpenAI-family.
+
+  </Accordion>
+  <Accordion title="OpenAI API key">
+    Uses `OPENAI_API_KEY` if present or prompts for a key, then stores the credential in auth profiles.
+
+    Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset, `openai/*`, or `openai-codex/*`.
+
+  </Accordion>
+  <Accordion title="xAI (Grok) OAuth">
+    Browser sign-in for eligible SuperGrok or X Premium accounts. This is the
+    recommended xAI path for most users. Nodmix stores the resulting auth
+    profile for Grok models, `x_search`, and `code_execution`.
+  </Accordion>
+  <Accordion title="xAI (Grok) device code">
+    Remote-friendly browser sign-in with a short code instead of a localhost
+    callback. Use this from SSH, Docker, or VPS hosts.
+  </Accordion>
+  <Accordion title="xAI (Grok) API key">
+    Prompts for `XAI_API_KEY` and configures xAI as a model provider. Use this
+    when you want an xAI Console API key instead of subscription OAuth.
+  </Accordion>
+  <Accordion title="OpenCode">
+    Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`) and lets you choose the Zen or Go catalog.
+    Setup URL: [opencode.ai/auth](https://opencode.ai/auth).
+  </Accordion>
+  <Accordion title="API key (generic)">
+    Stores the key for you.
+  </Accordion>
+  <Accordion title="Vercel AI Gateway">
+    Prompts for `AI_GATEWAY_API_KEY`.
+    More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway).
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway">
+    Prompts for account ID, gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
+    More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway).
+  </Accordion>
+  <Accordion title="MiniMax">
+    Config is auto-written. Hosted default is `MiniMax-M2.7`; API-key setup uses
+    `minimax/...`, and OAuth setup uses `minimax-portal/...`.
+    More detail: [MiniMax](/providers/minimax).
+  </Accordion>
+  <Accordion title="StepFun">
+    Config is auto-written for StepFun standard or Step Plan on China or global endpoints.
+    Standard currently includes `step-3.5-flash`, and Step Plan also includes `step-3.5-flash-2603`.
+    More detail: [StepFun](/providers/stepfun).
+  </Accordion>
+  <Accordion title="Synthetic (Anthropic-compatible)">
+    Prompts for `SYNTHETIC_API_KEY`.
+    More detail: [Synthetic](/providers/synthetic).
+  </Accordion>
+  <Accordion title="Ollama (Cloud and local open models)">
+    Prompts for `Cloud + Local`, `Cloud only`, or `Local only` first.
+    `Cloud only` uses `OLLAMA_API_KEY` with `https://ollama.com`.
+    The host-backed modes prompt for base URL (default `http://127.0.0.1:11434`), discover available models, and suggest defaults.
+    `Cloud + Local` also checks whether that Ollama host is signed in for cloud access.
+    More detail: [Ollama](/providers/ollama).
+  </Accordion>
+  <Accordion title="Moonshot and Kimi Coding">
+    Moonshot (Kimi K2) and Kimi Coding configs are auto-written.
+    More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot).
+  </Accordion>
+  <Accordion title="Custom provider">
+    Works with OpenAI-compatible and Anthropic-compatible endpoints.
+
+    Interactive onboarding supports the same API key storage choices as other provider API key flows:
+    - **Paste API key now** (plaintext)
+    - **Use secret reference** (env ref or configured provider ref, with preflight validation)
+
+    Non-interactive flags:
+    - `--auth-choice custom-api-key`
+    - `--custom-base-url`
+    - `--custom-model-id`
+    - `--custom-api-key` (optional; falls back to `CUSTOM_API_KEY`)
+    - `--custom-provider-id` (optional)
+    - `--custom-compatibility <openai|anthropic>` (optional; default `openai`)
+    - `--custom-image-input` / `--custom-text-input` (optional; override inferred model input capability)
+
+  </Accordion>
+  <Accordion title="Skip">
+    Leaves auth unconfigured.
+  </Accordion>
+</AccordionGroup>
+
+Model behavior:
+
+- Pick default model from detected options, or enter provider and model manually.
+- Custom-provider onboarding infers image support for common model IDs and asks only when the model name is unknown.
+- When onboarding starts from a provider auth choice, the model picker prefers
+  that provider automatically. For Volcengine and BytePlus, the same preference
+  also matches their coding-plan variants (`volcengine-plan/*`,
+  `byteplus-plan/*`).
+- If that preferred-provider filter would be empty, the picker falls back to
+  the full catalog instead of showing no models.
+- Wizard runs a model check and warns if the configured model is unknown or missing auth.
+
+Credential and profile paths:
+
+- Auth profiles (API keys + OAuth): `~/.nodmix/agents/<agentId>/agent/auth-profiles.json`
+- Legacy OAuth import: `~/.nodmix/credentials/oauth.json`
+
+Credential storage mode:
+
+- Default onboarding behavior persists API keys as plaintext values in auth profiles.
+- `--secret-input-mode ref` enables reference mode instead of plaintext key storage.
+  In interactive setup, you can choose either:
+  - environment variable ref (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`)
+  - configured provider ref (`file` or `exec`) with provider alias + id
+- Interactive reference mode runs a fast preflight validation before saving.
+  - Env refs: validates variable name + non-empty value in the current onboarding environment.
+  - Provider refs: validates provider config and resolves the requested id.
+  - If preflight fails, onboarding shows the error and lets you retry.
+- In non-interactive mode, `--secret-input-mode ref` is env-backed only.
+  - Set the provider env var in the onboarding process environment.
+  - Inline key flags (for example `--openai-api-key`) require that env var to be set; otherwise onboarding fails fast.
+  - For custom providers, non-interactive `ref` mode stores `models.providers.<id>.apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
+  - In that custom-provider case, `--custom-api-key` requires `CUSTOM_API_KEY` to be set; otherwise onboarding fails fast.
+- Gateway auth credentials support plaintext and SecretRef choices in interactive setup:
+  - Token mode: **Generate/store plaintext token** (default) or **Use SecretRef**.
+  - Password mode: plaintext or SecretRef.
+- Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
+- Existing plaintext setups continue to work unchanged.
+
+<Note>
+Headless and server tip: complete OAuth on a machine with a browser, then copy
+that agent's `auth-profiles.json` (for example
+`~/.nodmix/agents/<agentId>/agent/auth-profiles.json`, or the matching
+`$NODMIX_STATE_DIR/...` path) to the gateway host. `credentials/oauth.json`
+is only a legacy import source.
+</Note>
+
+## Outputs and internals
+
+Typical fields in `~/.nodmix/nodmix.json`:
+
+- `agents.defaults.workspace`
+- `agents.defaults.skipBootstrap` when `--skip-bootstrap` is passed
+- `agents.defaults.model` / `models.providers` (if Minimax chosen)
+- `tools.profile` (local onboarding defaults to `"coding"` when unset; existing explicit values are preserved)
+- `gateway.*` (mode, bind, auth, tailscale)
+- `session.dmScope` (local onboarding defaults this to `per-channel-peer` when unset; existing explicit values are preserved)
+- `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*`
+- Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible)
+- `skills.install.nodeManager`
+  - The `setup --node-manager` flag accepts `npm`, `pnpm`, or `bun`.
+  - Manual config can still set `skills.install.nodeManager: "yarn"` later.
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`nodmix agents add` writes `agents.list[]` and optional `bindings`.
+
+WhatsApp credentials go under `~/.nodmix/credentials/whatsapp/<accountId>/`.
+Sessions are stored under `~/.nodmix/agents/<agentId>/sessions/`.
+
+<Note>
+Some channels are delivered as plugins. When selected during setup, the wizard
+prompts to install the plugin (npm or local path) before channel configuration.
+</Note>
+
+Gateway wizard RPC:
+
+- `wizard.start`
+- `wizard.next`
+- `wizard.cancel`
+- `wizard.status`
+
+Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.
+
+Signal setup behavior:
+
+- Downloads the appropriate release asset
+- Stores it under `~/.nodmix/tools/signal-cli/<version>/`
+- Writes `channels.signal.cliPath` in config
+- JVM builds require Java 21
+- Native builds are used when available
+- Windows uses WSL2 and follows Linux signal-cli flow inside WSL
+
+## Related docs
+
+- Onboarding hub: [Onboarding (CLI)](/start/wizard)
+- Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
+- Command reference: [`nodmix onboard`](/cli/onboard)

package/docs/start/wizard.md

@@ -0,0 +1,141 @@
+---
+summary: "CLI onboarding: guided setup for gateway, workspace, channels, and skills"
+read_when:
+  - Running or configuring CLI onboarding
+  - Setting up a new machine
+title: "Onboarding (CLI)"
+sidebarTitle: "Onboarding: CLI"
+---
+
+CLI onboarding is the **recommended** way to set up Nodmix on macOS,
+Linux, or Windows (via WSL2; strongly recommended).
+It configures a local Gateway or a remote Gateway connection, plus channels, skills,
+and workspace defaults in one guided flow.
+
+```bash
+nodmix onboard
+```
+
+## Locale
+
+The CLI wizard localizes fixed onboarding copy. It resolves locale from
+`NODMIX_LOCALE`, then `LC_ALL`, then `LC_MESSAGES`, then `LANG`, and falls
+back to English. Supported wizard locales are `en`, `zh-CN`, and `zh-TW`.
+
+```bash
+NODMIX_LOCALE=zh-CN nodmix onboard
+```
+
+Names and stable identifiers stay literal: `Nodmix`, `Gateway`, `Tailscale`,
+commands, config keys, URLs, provider IDs, model IDs, and plugin/channel labels
+are not translated.
+
+<Info>
+Fastest first chat: open the Control UI (no channel setup needed). Run
+`nodmix dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).
+</Info>
+
+To reconfigure later:
+
+```bash
+nodmix configure
+nodmix agents add <name>
+```
+
+<Note>
+`--json` does not imply non-interactive mode. For scripts, use `--non-interactive`.
+</Note>
+
+<Tip>
+CLI onboarding includes a web search step where you can pick a provider
+such as Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search,
+Ollama Web Search, Perplexity, SearXNG, or Tavily. Some providers require an
+API key, while others are key-free. You can also configure this later with
+`nodmix configure --section web`. Docs: [Web tools](/tools/web).
+</Tip>
+
+## QuickStart vs Advanced
+
+Onboarding starts with **QuickStart** (defaults) vs **Advanced** (full control).
+
+<Tabs>
+  <Tab title="QuickStart (defaults)">
+    - Local gateway (loopback)
+    - Workspace default (or existing workspace)
+    - Gateway port **18789**
+    - Gateway auth **Token** (auto-generated, even on loopback)
+    - Tool policy default for new local setups: `tools.profile: "coding"` (existing explicit profile is preserved)
+    - DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals)
+    - Tailscale exposure **Off**
+    - Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)
+
+  </Tab>
+  <Tab title="Advanced (full control)">
+    - Exposes every step (mode, workspace, gateway, channels, daemon, skills).
+
+  </Tab>
+</Tabs>
+
+## What onboarding configures
+
+**Local mode (default)** walks you through these steps:
+
+1. **Model/Auth** — choose any supported provider/auth flow (API key, OAuth, or provider-specific manual auth), including Custom Provider
+   (OpenAI-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model.
+   Security note: if this agent will run tools or process webhook/hooks content, prefer the strongest latest-generation model available and keep tool policy strict. Weaker/older tiers are easier to prompt-inject.
+   For non-interactive runs, `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext API key values.
+   In non-interactive `ref` mode, the provider env var must be set; passing inline key flags without that env var fails fast.
+   In interactive runs, choosing secret reference mode lets you point at either an environment variable or a configured provider ref (`file` or `exec`), with a fast preflight validation before saving.
+   For Anthropic, interactive onboarding/configure offers **Anthropic Claude CLI** as the preferred local path and **Anthropic API key** as the recommended production path. Anthropic setup-token also remains available as a supported token-auth path.
+2. **Workspace** — Location for agent files (default `~/.nodmix/workspace`). Seeds bootstrap files.
+3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
+   In interactive token mode, choose default plaintext token storage or opt into SecretRef.
+   Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
+4. **Channels** — built-in and official plugin chat channels such as iMessage, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
+5. **Daemon** — Installs a LaunchAgent (macOS), systemd user unit (Linux/WSL2), or native Windows Scheduled Task with per-user Startup-folder fallback.
+   If token auth requires a token and `gateway.auth.token` is SecretRef-managed, daemon install validates it but does not persist the resolved token into supervisor service environment metadata.
+   If token auth requires a token and the configured token SecretRef is unresolved, daemon install is blocked with actionable guidance.
+   If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, daemon install is blocked until mode is set explicitly.
+6. **Health check** — Starts the Gateway and verifies it's running.
+7. **Skills** — Installs recommended skills and optional dependencies.
+
+<Note>
+Re-running onboarding does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`).
+CLI `--reset` defaults to config, credentials, and sessions; use `--reset-scope full` to include workspace.
+If the config is invalid or contains legacy keys, onboarding asks you to run `nodmix doctor` first.
+</Note>
+
+**Remote mode** only configures the local client to connect to a Gateway elsewhere.
+It does **not** install or change anything on the remote host.
+
+## Add another agent
+
+Use `nodmix agents add <name>` to create a separate agent with its own workspace,
+sessions, and auth profiles. Running without `--workspace` launches onboarding.
+
+What it sets:
+
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+Notes:
+
+- Default workspaces follow `~/.nodmix/workspace-<agentId>`.
+- Add `bindings` to route inbound messages (onboarding can do this).
+- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
+
+## Full reference
+
+For detailed step-by-step breakdowns and config outputs, see
+[CLI Setup Reference](/start/wizard-cli-reference).
+For non-interactive examples, see [CLI Automation](/start/wizard-cli-automation).
+For the deeper technical reference, including RPC details, see
+[Onboarding Reference](/reference/wizard).
+
+## Related docs
+
+- CLI command reference: [`nodmix onboard`](/cli/onboard)
+- Onboarding overview: [Onboarding Overview](/start/onboarding-overview)
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Agent first-run ritual: [Agent Bootstrapping](/start/bootstrapping)

package/docs/style.css

@@ -0,0 +1,184 @@
+#content > h1:first-of-type {
+  display: none !important;
+}
+
+.nav-tabs {
+  position: relative;
+}
+
+.nav-tabs-item > div {
+  opacity: 0;
+}
+
+.nav-tabs-underline {
+  position: absolute;
+  left: 0;
+  bottom: 0;
+  height: 1.5px;
+  width: var(--nav-tab-underline-width, 0);
+  transform: translateX(var(--nav-tab-underline-x, 0));
+  background-color: rgb(var(--primary));
+  border-radius: 999px;
+  pointer-events: none;
+  opacity: 0;
+  transition:
+    transform 260ms ease-in-out,
+    width 260ms ease-in-out,
+    opacity 160ms ease-in-out;
+  will-change: transform, width;
+}
+
+html.dark .nav-tabs-underline {
+  background-color: rgb(var(--primary-light));
+}
+
+.nav-tabs-underline-ready .nav-tabs-underline {
+  opacity: 1;
+}
+
+.showcase-hero {
+  display: grid;
+  gap: 18px;
+  margin: 8px 0 22px;
+  padding: clamp(18px, 3vw, 30px);
+  border: 1px solid color-mix(in oklab, rgb(var(--primary)) 24%, transparent);
+  border-radius: 8px;
+  background: color-mix(in oklab, rgb(var(--primary)) 5%, transparent);
+  box-shadow: 0 18px 48px -34px rgba(0, 0, 0, 0.45);
+}
+
+.showcase-kicker {
+  margin: 0;
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  opacity: 0.72;
+}
+
+.showcase-lead {
+  margin: 0;
+  max-width: 48rem;
+  font-size: clamp(18px, 2vw, 23px);
+  line-height: 1.6;
+}
+
+.showcase-actions,
+.showcase-jump-links {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
+.showcase-actions a,
+.showcase-jump-links a {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 40px;
+  padding: 0 14px;
+  border: 1px solid color-mix(in oklab, rgb(var(--primary)) 24%, transparent);
+  border-bottom: 1px solid color-mix(in oklab, rgb(var(--primary)) 24%, transparent);
+  border-radius: 8px;
+  background: color-mix(in oklab, rgb(var(--primary)) 4%, transparent);
+  text-decoration: none;
+  transition:
+    transform 0.16s ease,
+    border-color 0.16s ease,
+    background 0.16s ease;
+}
+
+.showcase-actions a:first-child {
+  background: color-mix(in oklab, rgb(var(--primary)) 12%, transparent);
+  border-color: color-mix(in oklab, rgb(var(--primary)) 36%, transparent);
+}
+
+.showcase-actions a:hover,
+.showcase-jump-links a:hover {
+  transform: translateY(-1px);
+  border-color: color-mix(in oklab, rgb(var(--primary)) 46%, transparent);
+}
+
+.showcase-highlights {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+}
+
+.showcase-highlight,
+.showcase-video-card {
+  border: 1px solid color-mix(in oklab, rgb(var(--primary)) 18%, transparent);
+  border-radius: 8px;
+  background: color-mix(in oklab, rgb(var(--primary)) 3%, transparent);
+}
+
+.showcase-highlight {
+  padding: 14px;
+}
+
+.showcase-highlight strong {
+  display: block;
+  margin-bottom: 6px;
+}
+
+.showcase-highlight span,
+.showcase-section-intro,
+.showcase-video-card p {
+  opacity: 0.74;
+}
+
+.showcase-jump-links {
+  margin: 18px 0 28px;
+}
+
+.showcase-section-intro {
+  margin: 0 0 16px;
+}
+
+.showcase-video-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 18px;
+  margin: 0 0 28px;
+}
+
+.showcase-video-card {
+  padding: 14px;
+  box-shadow: 0 18px 44px -32px rgba(0, 0, 0, 0.48);
+}
+
+.showcase-video-card h3 {
+  margin: 0 0 8px;
+}
+
+.showcase-video-card p {
+  margin: 0 0 12px;
+}
+
+.showcase-video-card a {
+  border-bottom: 0;
+}
+
+.showcase-video-shell {
+  position: relative;
+  margin-bottom: 14px;
+  padding-bottom: 56.25%;
+  overflow: hidden;
+  border-radius: 8px;
+  background: #0a0a0a;
+}
+
+.showcase-video-shell iframe {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  border: 0;
+}
+
+@media (max-width: 960px) {
+  .showcase-highlights,
+  .showcase-video-grid {
+    grid-template-columns: 1fr;
+  }
+}