nccgs 1.0.0

package/.claude/skills/setup-vivox-voice-chat/evals/README.md

@@ -0,0 +1,101 @@
+# Vivox Voice & Text Chat Skill Eval Suite
+
+Evaluation suite for the `setup-vivox-voice-chat` skill, powered by [Promptfoo](https://www.promptfoo.dev/). Validates that the skill routes the model to the correct Vivox v16 APIs (no v4/legacy hallucinations) across init, channel join, and messaging.
+
+## Prerequisites
+
+- **Node.js** v18 or later
+- A **LiteLLM API key** (from https://uai-litellm.internal.unity.com)
+
+## Setup
+
+### 1. Install Promptfoo
+
+```bash
+# Option A: install globally
+npm install -g promptfoo
+
+# Option B: use npx (no install needed)
+npx promptfoo@latest eval
+```
+
+### 2. Configure your API key
+
+```bash
+cd evals/
+cp .env.example .env
+```
+
+Open `.env` and set your personal LiteLLM key:
+
+```
+OPENAI_API_KEY=your-litellm-api-key-here
+OPENAI_BASE_URL=https://uai-litellm.internal.unity.com
+```
+
+> **Important:** Never commit your `.env` file. It is already in `.gitignore`.
+
+## Running the evals
+
+All commands should be run from the `evals/` directory.
+
+Use `-j 10` to run up to 10 eval requests concurrently.
+
+### Run the full suite
+
+```bash
+promptfoo eval -j 10
+```
+
+### Run a specific test file
+
+```bash
+promptfoo eval --tests tests/init-and-login.yaml -j 10
+promptfoo eval --tests tests/voice-channels.yaml -j 10
+promptfoo eval --tests tests/text-chat.yaml -j 10
+```
+
+## Viewing results
+
+### Terminal output
+
+Results are printed to the terminal with pass/fail per assertion.
+
+### Interactive web UI
+
+```bash
+promptfoo view
+```
+
+Opens a local UI (usually `http://localhost:15500`) for browsing results, filtering, and comparing runs.
+
+## Assertions used
+
+| Type | What it checks |
+|---|---|
+| `icontains` | Response contains a substring (case-insensitive), e.g. an exact Vivox API name |
+| `not-icontains` | Response does NOT contain a substring (used to catch v4 legacy names like `Client.Instance`) |
+| `llm-rubric` | An LLM judges whether the response meets a semantic requirement (e.g. correct init order) |
+
+## Adding new tests
+
+1. Create a new YAML file in `tests/`:
+
+```yaml
+- description: "Short description of what is being tested"
+  vars:
+    user_message: "The user request to test"
+    reference_content: "file://../references/your-reference.md"  # optional
+  assert:
+    - type: icontains
+      value: "VivoxService.Instance.JoinGroupChannelAsync"
+    - type: not-icontains
+      value: "SendDirectedTextMessageAsync"
+    - type: llm-rubric
+      value: |
+        Describe the semantic requirement the response must meet.
+```
+
+2. Add the file to `promptfooconfig.yaml` under `tests:`.
+
+3. Run it: `promptfoo eval --tests tests/your-new-test.yaml`.

package/.claude/skills/setup-vivox-voice-chat/evals/promptfooconfig.yaml

@@ -0,0 +1,32 @@
+description: "Vivox Voice & Text Chat Skill Eval Suite"
+
+providers:
+  # Evaluated model: used by the test itself
+  - id: openai:chat:claude-sonnet-4-5
+    config:
+      max_tokens: 2048
+
+prompts:
+  - id: eval-prompt
+    label: "Eval prompt"
+    raw: "{{skill_content}}\n\n{{reference_content}}\n\n{{custom_instructions}}\n\n## User Request\n\n{{user_message}}"
+
+defaultTest:
+  options:
+    # Assertion judge: used by llm-rubric
+    provider: openai:chat:claude-sonnet-4-6
+  vars:
+    skill_content: file://../SKILL.md
+    reference_content: ""
+    custom_instructions: |
+      IMPORTANT:
+      - This is a planning eval. Do not emit MCP XML/tool-call tags.
+      - Refer to APIs with their exact names as documented in the provided skill and references. Do not invent or paraphrase symbol names.
+      - Do not mention tool names you will not call. If a step is inapplicable, explain the behavior without naming the omitted API.
+      - Always present the complete plan up front. If a step requires a user action, describe what you will do after it succeeds and what happens if it fails, in a single response.
+      - Answer only the step or phase requested by the user message. Do not include unrelated setup or migration content that was not asked for.
+
+tests:
+  - file://tests/init-and-login.yaml
+  - file://tests/voice-channels.yaml
+  - file://tests/text-chat.yaml

package/.claude/skills/setup-vivox-voice-chat/evals/tests/init-and-login.yaml

@@ -0,0 +1,76 @@
+# ============================================================
+# WORKFLOW: Init + Login — correct order and re-init guard
+# ============================================================
+
+- description: "Cold-start init: UGS Core -> Auth -> Vivox Init -> Vivox Login, in order"
+  vars:
+    user_message: |
+      I'm adding Vivox to a fresh Unity project. Walk me through
+      the initialization from an empty MonoBehaviour Start method.
+    reference_content: file://../references/init-and-login.md
+  assert:
+    - type: icontains
+      value: "UnityServices.InitializeAsync"
+    - type: icontains
+      value: "AuthenticationService.Instance.SignInAnonymouslyAsync"
+    - type: icontains
+      value: "VivoxService.Instance.InitializeAsync"
+    - type: icontains
+      value: "VivoxService.Instance.LoginAsync"
+    - type: llm-rubric
+      value: |
+        The response MUST describe the four initialization calls in this
+        exact order:
+        1. UnityServices.InitializeAsync
+        2. AuthenticationService.Instance.SignInAnonymouslyAsync
+        3. VivoxService.Instance.InitializeAsync
+        4. VivoxService.Instance.LoginAsync
+        Any other ordering (e.g. Vivox init before UGS init, or Login
+        before Vivox init) is a failure.
+        The response MUST NOT use v4 legacy patterns (Client.Instance,
+        ILoginSession, AccountId, ChannelId) as callable code. It is
+        fine — even helpful — to mention those names in a "don't use
+        these" warning or migration note; a failure is only when the
+        code samples or step-by-step instructions actually invoke them.
+
+- description: "Login with display name: LoginOptions.DisplayName"
+  vars:
+    user_message: |
+      After Vivox is initialized, sign the player in with the display name
+      "Sunbeam" and enable text-to-speech.
+    reference_content: file://../references/init-and-login.md
+  assert:
+    - type: icontains
+      value: "LoginOptions"
+    - type: icontains
+      value: "DisplayName"
+    - type: icontains
+      value: "EnableTTS"
+    - type: icontains
+      value: "VivoxService.Instance.LoginAsync"
+    - type: llm-rubric
+      value: |
+        The response must construct a LoginOptions with DisplayName set to
+        "Sunbeam" and EnableTTS set to true, then pass it to
+        VivoxService.Instance.LoginAsync. It must not USE the v4 AccountId
+        or ILoginSession types as callable code (mentioning them in a
+        "don't use" warning is acceptable — failure is only when the code
+        actually invokes them).
+
+- description: "Double-init must warn about VxErrorAlreadyInitialized (5041)"
+  vars:
+    user_message: |
+      My Start method runs every time the main scene reloads and I'm
+      seeing Vivox errors. How do I stop it from re-initializing?
+    reference_content: file://../references/init-and-login.md
+  assert:
+    - type: icontains
+      value: "5041"
+    - type: llm-rubric
+      value: |
+        The response must identify the underlying issue as
+        VivoxService.Instance.InitializeAsync being called more than once,
+        cite the 5041 VxErrorAlreadyInitialized error, and propose a fix
+        such as guarding with IsInitialized or making the bootstrap
+        object DontDestroyOnLoad. The fix must NOT be to catch and
+        swallow the exception.

package/.claude/skills/setup-vivox-voice-chat/evals/tests/text-chat.yaml

@@ -0,0 +1,65 @@
+# ============================================================
+# WORKFLOW: Text chat — channel messages, directed messages, history
+# ============================================================
+
+- description: "Send a channel message and receive channel messages"
+  vars:
+    user_message: |
+      Send the text "gg" into the "lobby" channel from a UI button, and
+      log every message received in that channel to the console.
+    reference_content: file://../references/text-chat.md
+  assert:
+    - type: icontains
+      value: "VivoxService.Instance.SendChannelTextMessageAsync"
+    - type: icontains
+      value: "VivoxService.Instance.ChannelMessageReceived"
+    - type: icontains
+      value: "VivoxMessage"
+    - type: llm-rubric
+      value: |
+        The response must call VivoxService.Instance.SendChannelTextMessageAsync
+        with channelName "lobby" and message "gg", AND subscribe to
+        VivoxService.Instance.ChannelMessageReceived with a handler that
+        takes a VivoxMessage and logs at least MessageText and
+        SenderDisplayName. It must NOT wire the send path to the
+        DirectedMessageReceived event.
+
+- description: "Send a directed (direct) message — must use SendDirectTextMessageAsync, not SendDirected..."
+  vars:
+    user_message: |
+      Whisper "meet me at the north gate" to the player whose PlayerId
+      is "abc123".
+    reference_content: file://../references/text-chat.md
+  assert:
+    - type: icontains
+      value: "VivoxService.Instance.SendDirectTextMessageAsync"
+    - type: llm-rubric
+      value: |
+        The response must call VivoxService.Instance.SendDirectTextMessageAsync
+        with playerId "abc123" and the exact message
+        "meet me at the north gate". The method name must be
+        SendDirectTextMessageAsync (with "Direct", no "ed" before "Text").
+        SendDirectedTextMessageAsync does not exist in the SDK and MUST
+        NOT be USED as callable code — but mentioning it in a "common
+        hallucination, don't use this" warning is fine and even helpful.
+        The response may also mention subscribing to the
+        DirectedMessageReceived event on the recipient side.
+
+- description: "Fetch the most recent channel chat history"
+  vars:
+    user_message: |
+      Fetch the last 25 messages from the "lobby" channel and print them
+      to the console in oldest-to-newest order.
+    reference_content: file://../references/text-chat.md
+  assert:
+    - type: icontains
+      value: "GetChannelTextMessageHistoryAsync"
+    - type: llm-rubric
+      value: |
+        The response must call
+        VivoxService.Instance.GetChannelTextMessageHistoryAsync with
+        channelName "lobby" and requestSize 25 (or equivalent). It must
+        note that the returned collection is newest-first and must
+        reverse the collection (or iterate in reverse) before printing to
+        achieve oldest-to-newest ordering. It should reference
+        VivoxMessage.SenderDisplayName and VivoxMessage.MessageText.

package/.claude/skills/setup-vivox-voice-chat/evals/tests/voice-channels.yaml

@@ -0,0 +1,74 @@
+# ============================================================
+# WORKFLOW: Voice channels — group, positional, join lifecycle
+# ============================================================
+
+- description: "Join a lobby group channel with voice and text"
+  vars:
+    user_message: |
+      The player is logged into Vivox. Have them join a non-positional
+      channel called "lobby" with both voice and text enabled.
+    reference_content: file://../references/voice-channels.md
+  assert:
+    - type: icontains
+      value: "VivoxService.Instance.JoinGroupChannelAsync"
+    - type: icontains
+      value: "ChatCapability.TextAndAudio"
+    - type: not-icontains
+      value: "JoinPositionalChannelAsync"
+    - type: not-icontains
+      value: "IChannelSession"
+    - type: llm-rubric
+      value: |
+        The response must call VivoxService.Instance.JoinGroupChannelAsync
+        with the channel name "lobby" and ChatCapability.TextAndAudio. It
+        must NOT use the positional or echo join methods, and must not
+        use any v4 IChannelSession API.
+
+- description: "Join a 3D positional channel with Channel3DProperties"
+  vars:
+    user_message: |
+      Set up proximity voice: players near each other in the world should
+      hear each other, and voices fall off with distance. Name the
+      channel "world-proximity".
+    reference_content: file://../references/voice-channels.md
+  assert:
+    - type: icontains
+      value: "Channel3DProperties"
+    - type: icontains
+      value: "Set3DPosition"
+    - type: not-icontains
+      value: "JoinGroupChannelAsync"
+    - type: llm-rubric
+      value: |
+        This is a planning eval: judge the plan's correctness, not whether
+        it names APIs literally or includes runnable code. The plan must:
+        (a) identify positional (3D) channels as the mechanism — mentioning
+        "positional channel", "3D channel", or JoinPositionalChannelAsync
+        all count, since positional channels have exactly one join method;
+        (b) use the channel name "world-proximity";
+        (c) configure Channel3DProperties (naming at least the audible/
+        conversational distance concept, and ideally the fade model);
+        (d) state that each player's 3D position needs a per-frame update
+        via Set3DPosition (or an equivalent per-frame transform sync) so
+        distance attenuation actually works;
+        (e) make clear that awaiting the join call is not sufficient —
+        ChannelJoined must be subscribed to first for the join to be
+        observable.
+
+- description: "Subscribe to ChannelJoined BEFORE calling JoinGroupChannelAsync"
+  vars:
+    user_message: |
+      When I call JoinGroupChannelAsync my UI never activates for the
+      newly joined channel. What am I doing wrong?
+    reference_content: file://../references/voice-channels.md
+  assert:
+    - type: icontains
+      value: "ChannelJoined"
+    - type: llm-rubric
+      value: |
+        The response must diagnose the problem as the ChannelJoined event
+        being subscribed AFTER the join call, and instruct the user to
+        subscribe to VivoxService.Instance.ChannelJoined BEFORE calling
+        JoinGroupChannelAsync. It must clearly state that awaiting the
+        JoinGroupChannelAsync call does NOT mean the join is complete —
+        the join completes when the ChannelJoined event fires.

package/.claude/skills/setup-vivox-voice-chat/references/events-and-participants.md

@@ -0,0 +1,79 @@
+# Events, Participants, and Lifecycle
+
+## Service-Level Events
+
+All on `VivoxService.Instance`. Subscribe **before** the async call that produces them.
+
+| Event | Signature | Fires on |
+|---|---|---|
+| `LoggedIn` | `Action` | `LoginAsync` success (also on reconnect) |
+| `LoggedOut` | `Action` | `LogoutAsync` or disconnect |
+| `ChannelJoined` | `Action<string channelName>` | Any `Join*ChannelAsync` success |
+| `ChannelLeft` | `Action<string channelName>` | `LeaveChannelAsync` / `LeaveAllChannelsAsync` / disconnect |
+| `ParticipantAddedToChannel` | `Action<VivoxParticipant>` | Any user joins a channel you're in (including yourself) |
+| `ParticipantRemovedFromChannel` | `Action<VivoxParticipant>` | Any user leaves |
+| `ChannelMessageReceived` | `Action<VivoxMessage>` | Any channel text message |
+| `ChannelMessageEdited` | `Action<VivoxMessage>` | Any channel message edited |
+| `ChannelMessageDeleted` | `Action<VivoxMessage>` | Any channel message deleted |
+| `DirectedMessageReceived` | `Action<VivoxMessage>` | Any directed message to you |
+| `DirectedMessageEdited` | `Action<VivoxMessage>` | Directed message edited |
+| `DirectedMessageDeleted` | `Action<VivoxMessage>` | Directed message deleted |
+
+## VivoxParticipant
+
+Delivered by `ParticipantAddedToChannel` and `ParticipantRemovedFromChannel`. Represents one participant in one channel — the same user in two channels is two separate `VivoxParticipant` instances.
+
+| Property | Purpose |
+|---|---|
+| `PlayerId` | Stable UAS PlayerId of the participant |
+| `DisplayName` | From the participant's `LoginOptions.DisplayName` |
+| `ChannelName` | Which channel this participation is in |
+| `IsSelf` | `true` if this is the local player |
+| `IsMuted` | Current locally-muted state |
+| `AudioEnergy` | Continuous 0.0–1.0 signal for VU-meter UI |
+| `SpeechDetected` | `true` when Vivox judges audio energy is speech, not noise |
+
+## Per-Participant Events
+
+Live on the `VivoxParticipant` instance, **not** on `VivoxService.Instance`:
+
+- `ParticipantMuteStateChanged` — `IsMuted` flipped.
+- `ParticipantSpeechDetected` — `SpeechDetected` flipped.
+- `ParticipantAudioEnergyChanged` — `AudioEnergy` updated (higher-frequency; use for VU meter).
+
+Typical wiring in a roster item that represents one participant:
+
+```csharp
+public void Bind(VivoxParticipant p)
+{
+    _participant = p;
+    p.ParticipantMuteStateChanged += Refresh;
+    p.ParticipantSpeechDetected   += Refresh;
+}
+
+void OnDestroy()
+{
+    if (_participant == null) return;
+    _participant.ParticipantMuteStateChanged -= Refresh;
+    _participant.ParticipantSpeechDetected   -= Refresh;
+}
+```
+
+## Local Mute Actions
+
+Called on the `VivoxParticipant` (not the service):
+
+- `participant.MutePlayerLocally()` — you stop hearing them.
+- `participant.UnmutePlayerLocally()` — you resume hearing them.
+
+The remote participant is unaware. To mute globally (they cannot be heard by anyone), a moderator client needs a server-issued mute token.
+
+## Cleanup Discipline
+
+`VivoxService.Instance` is a persistent singleton across scene loads. Any handler you subscribe from a MonoBehaviour **must** be unsubscribed in `OnDestroy` or `OnDisable`, or the handler will fire against a destroyed object on the next scene load and throw a `MissingReferenceException`.
+
+Pattern: subscribe in `Awake`/`Start`, mirror the list in `OnDestroy`, always null-guard `VivoxService.Instance` (it may already be null during application quit).
+
+## Connection Recovery
+
+On network blips Vivox will auto-reconnect and re-fire `LoggedIn` and (for previously-joined channels) `ChannelJoined`. Design handlers to be **idempotent** — do not assume `LoggedIn` fires exactly once per session, and don't grant one-shot benefits (analytics event, first-login reward) from inside it without a guard.

package/.claude/skills/setup-vivox-voice-chat/references/init-and-login.md

@@ -0,0 +1,92 @@
+# Initialization and Login
+
+## Package and Namespaces
+
+Install `com.unity.services.vivox` via Package Manager. Add `using Unity.Services.Vivox;` to any script that touches the SDK. For UGS-backed auth also add `using Unity.Services.Core;` and `using Unity.Services.Authentication;`.
+
+## Full Initialization Snippet
+
+Grounded on the Vivox docs — do not deviate from this order.
+
+```csharp
+using System;
+using UnityEngine;
+using Unity.Services.Authentication;
+using Unity.Services.Core;
+using Unity.Services.Vivox;
+
+public class VivoxBootstrap : MonoBehaviour
+{
+    async void Start()
+    {
+        await UnityServices.InitializeAsync();
+        await AuthenticationService.Instance.SignInAnonymouslyAsync();
+
+        await VivoxService.Instance.InitializeAsync();
+
+        VivoxService.Instance.LoggedIn  += OnLoggedIn;
+        VivoxService.Instance.LoggedOut += OnLoggedOut;
+
+        await VivoxService.Instance.LoginAsync(new LoginOptions
+        {
+            DisplayName = "Bob",
+            EnableTTS   = false
+        });
+    }
+
+    void OnLoggedIn()  { /* joins, UI enable, etc. */ }
+    void OnLoggedOut() { /* teardown */ }
+
+    void OnDestroy()
+    {
+        if (VivoxService.Instance == null) return;
+        VivoxService.Instance.LoggedIn  -= OnLoggedIn;
+        VivoxService.Instance.LoggedOut -= OnLoggedOut;
+    }
+}
+```
+
+## VivoxConfigurationOptions
+
+`InitializeAsync` takes an optional `VivoxConfigurationOptions`. Common fields: log level, audio ducking behavior, server region. Leave defaults for most projects; only override when platform-specific tuning is documented in the Vivox docs (e.g. mobile ducking).
+
+## LoginOptions
+
+| Field | Notes |
+|---|---|
+| `DisplayName` | Shown to other participants via `VivoxParticipant.DisplayName`. Session-only, not persisted. Max 127 bytes. Sanitize / uniqueness-check server-side; the SDK does not validate. |
+| `EnableTTS` | Enables text-to-speech injection into channels. Off by default. |
+| Blocked list | Preload users blocked by this player. |
+
+The identity Vivox binds this login to is the current `AuthenticationService.Instance.PlayerId` — that's how other clients address you for directed messages. If you skip UAS, Vivox falls back to a per-session GUID and cross-session identity is lost.
+
+## Sign Out
+
+```csharp
+await VivoxService.Instance.LogoutAsync();
+```
+
+`LogoutAsync` fires `LoggedOut`. Call it before shutting the app down cleanly; the SDK also handles ungraceful teardown but explicit logout gives you a clean disconnect on the server side.
+
+## Access Tokens (VAT) — When You Need Them
+
+The default UGS-backed path automatically mints access tokens signed by your UGS project. You don't touch tokens in code.
+
+You need to switch to server-side VAT minting when:
+
+- You're not using UGS Authentication (custom identity system).
+- You need privileged tokens: kick a user from a channel, mute-all, transcription enable, join-muted.
+- You want channel-scoped ACLs (only players holding a valid join token for `raid-42` can enter).
+
+Do **not** embed the Vivox app secret / HMAC signing key in client code. See the "Access Token Developer Guide" and the C++, C#, Python, and JavaScript minting examples in the Unity Vivox documentation map for server implementations.
+
+## Re-init Guard
+
+Calling `VivoxService.Instance.InitializeAsync()` twice throws `5041 VxErrorAlreadyInitialized`. If your `Start` may run again after scene reload, wrap init in a check:
+
+```csharp
+if (VivoxService.Instance != null && !VivoxService.Instance.IsInitialized)
+    await VivoxService.Instance.InitializeAsync();
+```
+
+Or make the bootstrap MonoBehaviour `DontDestroyOnLoad` so it only runs once.

package/.claude/skills/setup-vivox-voice-chat/references/text-chat.md

@@ -0,0 +1,93 @@
+# Text Chat
+
+Text works over any channel joined with `ChatCapability.TextOnly` or `ChatCapability.TextAndAudio`, plus directed (peer-to-peer) messages that don't require a shared channel.
+
+## Channel Messages
+
+**Send:**
+
+```csharp
+await VivoxService.Instance.SendChannelTextMessageAsync(
+    string channelName,
+    string message);
+```
+
+**Receive:**
+
+```csharp
+VivoxService.Instance.ChannelMessageReceived += OnChannelMessageReceived;
+
+void OnChannelMessageReceived(VivoxMessage m)
+{
+    // m.ChannelName, m.SenderDisplayName, m.SenderPlayerId,
+    // m.MessageText, m.ReceivedTime, m.Language, m.FromSelf, m.MessageId
+}
+```
+
+## Directed Messages
+
+**Send:** (note spelling — `SendDirect…`, not `SendDirected…`)
+
+```csharp
+await VivoxService.Instance.SendDirectTextMessageAsync(
+    string playerId,   // recipient's UAS PlayerId
+    string message);
+```
+
+**Receive:** (event *is* `Directed…`)
+
+```csharp
+VivoxService.Instance.DirectedMessageReceived += OnDirectedMessageReceived;
+
+void OnDirectedMessageReceived(VivoxMessage m)
+{
+    // Same VivoxMessage fields, but m.ChannelName is null and m.FromSelf is false.
+}
+```
+
+## VivoxMessage Fields
+
+| Field | Notes |
+|---|---|
+| `ChannelName` | The channel the message came in on. **`null` for directed messages.** |
+| `SenderDisplayName` | As set in the sender's `LoginOptions`. |
+| `SenderPlayerId` | UAS PlayerId — stable identity to reply/DM back. |
+| `MessageText` | The message body. |
+| `ReceivedTime` | `DateTime` of receipt. |
+| `Language` | Sender's language tag if set. |
+| `FromSelf` | `true` for the local player's own channel messages; `false` for directed messages. |
+| `MessageId` | Server-assigned ID — required to edit or delete. |
+
+## Chat History
+
+Retention: **7 days** by default (30 days if Text Evidence Management is enabled).
+
+```csharp
+IReadOnlyCollection<VivoxMessage> GetChannelTextMessageHistoryAsync(
+    string channelName,
+    int requestSize = 10,
+    ChatHistoryQueryOptions options = null);
+
+IReadOnlyCollection<VivoxMessage> GetDirectTextMessageHistoryAsync(
+    string playerId,
+    int requestSize = 10,
+    ChatHistoryQueryOptions options = null);
+```
+
+Both return messages **newest-first**. Reverse when rendering a chat log.
+
+## Edit and Delete
+
+Only the original sender can edit or delete their own messages.
+
+| Op | Channel | Directed |
+|---|---|---|
+| Edit | `EditChannelTextMessageAsync(channelName, messageId, newText)` | `EditDirectTextMessageAsync(messageId, newText)` |
+| Delete | `DeleteChannelTextMessageAsync(channelName, messageId)` | `DeleteDirectTextMessageAsync(messageId)` |
+| Notify (all participants) | `ChannelMessageEdited`, `ChannelMessageDeleted` | `DirectedMessageEdited`, `DirectedMessageDeleted` |
+
+All notify events carry the updated `VivoxMessage`.
+
+## Anti-flooding
+
+Vivox rate-limits messages per player. When implementing chat UI, disable the send button after each send until acknowledged, and surface a "try again in a moment" hint on rate-limit errors — do not spam-retry.

package/.claude/skills/setup-vivox-voice-chat/references/troubleshooting.md

@@ -0,0 +1,47 @@
+# Troubleshooting and Platform Notes
+
+For the authoritative error table, see the Vivox SDK error codes page linked from the Vivox documentation map.
+
+## Common Errors
+
+| Code | Name | Cause | Fix |
+|---|---|---|---|
+| `5041` | `VxErrorAlreadyInitialized` | `VivoxService.Instance.InitializeAsync()` called twice | Guard with `IsInitialized` or make bootstrap `DontDestroyOnLoad` |
+| `20502` | `VxXmppServerErrorServiceUnavailable` | Exceeded 10 non-positional channels per user, or 200 participants per channel | Leave a channel before joining another; for large positional channels use Large 3D Channels setting |
+| Login fails silently | — | Subscribed to `LoggedIn` **after** `LoginAsync` returned | Subscribe first, then call `LoginAsync` |
+| `ChannelJoined` never fires | — | Awaited `JoinGroupChannelAsync` as if it completes the join | Bind `ChannelJoined` before calling; treat the await as "request queued" |
+| No audio in / out | — | Mic permission denied, wrong `ChatCapability` (e.g. `TextOnly` when audio expected), or muted input device | Check runtime permission, `ChatCapability`, and `IsInputDeviceMuted` — call `UnmuteInputDevice()` if muted |
+
+## Platform Notes
+
+### Android
+
+- Merge `<uses-permission android:name="android.permission.RECORD_AUDIO"/>` into `AndroidManifest.xml`.
+- Request at runtime with `UnityEngine.Android.Permission.RequestUserPermission(Permission.Microphone)` **before** joining an audio channel — Android will not prompt automatically for you.
+- Bluetooth SCO underruns cause choppy input — see the Android troubleshooting page in the documentation map.
+- If shrinking / obfuscating with R8/ProGuard, add the Vivox ProGuard rules from the docs.
+
+### iOS
+
+- Add `NSMicrophoneUsageDescription` to Info.plist (Project Settings → Player → iOS → Microphone Usage Description).
+- The orange/red iOS recording indicator is shown any time Vivox is capturing — this is OS-enforced and expected.
+
+### WebGL
+
+- The Vivox WebGL SDK is a subset of the native SDK. Audio Taps, some codecs, and certain positional-audio features are unavailable. Read the WebGL support page in the documentation map before promising a feature on web.
+- Browsers require a user gesture before capturing the mic — trigger the first `JoinGroupChannelAsync`/`JoinPositionalChannelAsync` from a button click, not from `Start()`.
+
+### NDA Platforms (console)
+
+Vivox ships NDA-gated packages for consoles. Contact Unity for access; the public UPM package does not include console binaries.
+
+## Diagnostic Checklist
+
+When integration seems broken and no clear error surfaces:
+
+1. Confirm init order — `UnityServices.InitializeAsync` → `AuthenticationService.Instance.SignInAnonymouslyAsync` → `VivoxService.Instance.InitializeAsync` → `VivoxService.Instance.LoginAsync`.
+2. Log every event handler entry (`LoggedIn`, `ChannelJoined`, `ChannelMessageReceived`). If a handler you expect never enters, you subscribed after the event already fired.
+3. Confirm the joined channel's `ChatCapability` matches what you're trying to do (text vs audio).
+4. Confirm mic permission on the platform you're testing.
+5. If audio was working then stopped after a scene reload, you have leaked event subscriptions from destroyed MonoBehaviours — audit `OnDestroy` unsubscribes.
+6. If a directed message never arrives, verify `SendDirectTextMessageAsync` is targeting the recipient's **UAS PlayerId** (not display name), and that the recipient has subscribed to `DirectedMessageReceived`.