docs: add clarity on use of custom packet type (#12)

Author: streamer45

ROADMAP.md

@@ -111,6 +111,7 @@ StreamKit is audio-first today. Video support is a major milestone for v1.0:
 
 - ResourceManager integration for native plugins (unified model caching)
 - Plugin API versioning and compatibility checks
+- Plugin-defined packet schemas/metadata ("virtual packet types") that surface in `/schema/packets` and the UI while flowing as `Custom(type_id)` at runtime
 - Exploration of WASM/Native API convergence
 
 ---

apps/skit/src/bin/gen-docs-reference.rs

@@ -346,6 +346,80 @@ fn render_packet_page(entry: &PacketTypeEntry) -> Result<String> {
     out.push_str(&format!("Type system: `{}`\n\n", entry.kind_repr));
     out.push_str(&format!("Runtime: `{}`\n\n", entry.runtime_repr));
 
+    if entry.id == "Custom" {
+        out.push_str(
+            r#"## Why `Custom` exists
+`Custom` is StreamKit's **extensibility escape hatch**: it lets plugins and pipelines exchange
+structured data **without adding new built-in packet variants**.
+
+It was designed to:
+
+- Keep the core packet set small and stable (important for UIs and SDKs).
+- Enable fast iteration for plugin-defined events and typed messages.
+- Preserve type-checking via `type_id` so pipelines still validate before running.
+- Stay user-friendly over JSON APIs (`encoding: "json"` is debuggable and easy to inspect).
+
+## When to use it
+Use `Custom` when you need **structured, typed messages** that don't fit existing packet types, for example:
+
+- Plugin-defined events (e.g. VAD, moderation, scene triggers, rich status updates).
+- Application-level envelopes (e.g. tool results, routing hints, structured logs).
+- Telemetry-like events (see below) that you want to treat as first-class data.
+
+Prefer other packet types when they fit:
+
+- Audio frames/streams: `/reference/packets/raw-audio/` or `/reference/packets/opus-audio/`
+- Plain strings: `/reference/packets/text/`
+- Opaque bytes, blobs, or media: `/reference/packets/binary/`
+- Speech-to-text results: `/reference/packets/transcription/`
+
+## Type IDs, versioning, and compatibility
+`type_id` is the **routing key** for `Custom` and is part of the type system.
+
+- Compatibility: `PacketType::Custom { type_id: "a@1" }` only connects to the same `type_id`.
+  If you truly want "any custom", use `PacketType::Any` on the input pin.
+- Versioning: include a major version suffix like `@1` and bump it for breaking payload changes.
+- Namespacing: use a stable, collision-resistant prefix (examples below).
+
+Examples used in this repo:
+
+- `core::telemetry/event@1` (telemetry envelope used on the WebSocket bus)
+- `plugin::native::vad/vad-event@1` (VAD-style events)
+
+## Payload conventions
+`data` is schema-less JSON: treat it as **untrusted input** and validate it in consumers.
+
+For "event"-shaped payloads, a common convention is an `event_type` string inside `data`:
+
+```json
+{
+  "type_id": "core::telemetry/event@1",
+  "encoding": "json",
+  "data": { "event_type": "vad.start", "source": "mic" },
+  "metadata": { "timestamp_us": 1735257600000000 }
+}
+```
+
+Related docs:
+
+- WebSocket telemetry events: `/reference/websocket-api/#telemetry-events-nodetelemetry`
+- Nodes that observe/emit telemetry: `/reference/nodes/core-telemetry-tap/`, `/reference/nodes/core-telemetry-out/`
+
+## When a core packet type is a better fit
+`Custom` is great for iteration, but adding a new core packet type can be worth it when:
+
+- The payload is **high-volume / performance-sensitive** (zero-copy, binary codecs, large frames).
+- The payload needs **canonical semantics** across the ecosystem (multiple nodes, UIs, SDKs).
+- There are **well-defined fields** that benefit from first-class schema/compat rules (not just `type_id`).
+- The payload should be **universally inspectable/renderable** in the UI (timelines, previews, editors).
+
+In those cases, open a GitHub issue describing the use case and examples (or send a PR). The goal is to keep
+the built-in packet set small and stable, and graduate widely useful patterns out of `Custom` when needed.
+
+"#,
+        );
+    }
+
     let registry = streamkit_core::packet_meta::packet_type_registry();
     if let Some(meta) = registry.iter().find(|m| m.id == entry.id) {
         out.push_str("## UI Metadata\n");

docs/src/content/docs/reference/configuration-generated.md

@@ -587,8 +587,7 @@ Telemetry and observability configuration (OpenTelemetry, tokio-console).
                 "core::sink"
               ],
               "allowed_plugins": [
-                "plugin::*",
-                "native::audio*"
+                "plugin::*"
               ],
               "allowed_samples": [
                 "oneshot/*.yml",
@@ -1012,8 +1011,7 @@ Telemetry and observability configuration (OpenTelemetry, tokio-console).
               "core::sink"
             ],
             "allowed_plugins": [
-              "plugin::*",
-              "native::audio*"
+              "plugin::*"
             ],
             "allowed_samples": [
               "oneshot/*.yml",

docs/src/content/docs/reference/nodes/transport-http-fetcher.md

@@ -2,12 +2,12 @@
 # SPDX-FileCopyrightText: © 2025 StreamKit Contributors
 # SPDX-License-Identifier: MPL-2.0
 title: "transport::http::fetcher"
-description: "Fetches binary data from an HTTP/HTTPS URL. Security: this is an SSRF-capable node; restrict it via role allowlists. Redirects are disabled (v0.1.0)."
+description: "Fetches binary data from an HTTP/HTTPS URL. Security: this is an SSRF-capable node; restrict it via role allowlists. Redirects are disabled (v0.1.x)."
 ---
 
 `kind`: `transport::http::fetcher`
 
-Fetches binary data from an HTTP/HTTPS URL. Security: this is an SSRF-capable node; restrict it via role allowlists. Redirects are disabled (v0.1.0).
+Fetches binary data from an HTTP/HTTPS URL. Security: this is an SSRF-capable node; restrict it via role allowlists. Redirects are disabled (v0.1.x).
 
 ## Categories
 - `transport`

docs/src/content/docs/reference/packets/custom.md

@@ -11,6 +11,74 @@ Type system: `PacketType::Custom { type_id }`
 
 Runtime: `Packet::Custom(Arc<CustomPacketData>)`
 
+## Why `Custom` exists
+`Custom` is StreamKit's **extensibility escape hatch**: it lets plugins and pipelines exchange
+structured data **without adding new built-in packet variants**.
+
+It was designed to:
+
+- Keep the core packet set small and stable (important for UIs and SDKs).
+- Enable fast iteration for plugin-defined events and typed messages.
+- Preserve type-checking via `type_id` so pipelines still validate before running.
+- Stay user-friendly over JSON APIs (`encoding: "json"` is debuggable and easy to inspect).
+
+## When to use it
+Use `Custom` when you need **structured, typed messages** that don't fit existing packet types, for example:
+
+- Plugin-defined events (e.g. VAD, moderation, scene triggers, rich status updates).
+- Application-level envelopes (e.g. tool results, routing hints, structured logs).
+- Telemetry-like events (see below) that you want to treat as first-class data.
+
+Prefer other packet types when they fit:
+
+- Audio frames/streams: `/reference/packets/raw-audio/` or `/reference/packets/opus-audio/`
+- Plain strings: `/reference/packets/text/`
+- Opaque bytes, blobs, or media: `/reference/packets/binary/`
+- Speech-to-text results: `/reference/packets/transcription/`
+
+## Type IDs, versioning, and compatibility
+`type_id` is the **routing key** for `Custom` and is part of the type system.
+
+- Compatibility: `PacketType::Custom { type_id: "a@1" }` only connects to the same `type_id`.
+  If you truly want "any custom", use `PacketType::Any` on the input pin.
+- Versioning: include a major version suffix like `@1` and bump it for breaking payload changes.
+- Namespacing: use a stable, collision-resistant prefix (examples below).
+
+Examples used in this repo:
+
+- `core::telemetry/event@1` (telemetry envelope used on the WebSocket bus)
+- `plugin::native::vad/vad-event@1` (VAD-style events)
+
+## Payload conventions
+`data` is schema-less JSON: treat it as **untrusted input** and validate it in consumers.
+
+For "event"-shaped payloads, a common convention is an `event_type` string inside `data`:
+
+```json
+{
+  "type_id": "core::telemetry/event@1",
+  "encoding": "json",
+  "data": { "event_type": "vad.start", "source": "mic" },
+  "metadata": { "timestamp_us": 1735257600000000 }
+}
+```
+
+Related docs:
+
+- WebSocket telemetry events: `/reference/websocket-api/#telemetry-events-nodetelemetry`
+- Nodes that observe/emit telemetry: `/reference/nodes/core-telemetry-tap/`, `/reference/nodes/core-telemetry-out/`
+
+## When a core packet type is a better fit
+`Custom` is great for iteration, but adding a new core packet type can be worth it when:
+
+- The payload is **high-volume / performance-sensitive** (zero-copy, binary codecs, large frames).
+- The payload needs **canonical semantics** across the ecosystem (multiple nodes, UIs, SDKs).
+- There are **well-defined fields** that benefit from first-class schema/compat rules (not just `type_id`).
+- The payload should be **universally inspectable/renderable** in the UI (timelines, previews, editors).
+
+In those cases, open a GitHub issue describing the use case and examples (or send a PR). The goal is to keep
+the built-in packet set small and stable, and graduate widely useful patterns out of `Custom` when needed.
+
 ## UI Metadata
 - `label`: `Custom`
 - `color`: `#e67e22`

docs/src/content/docs/reference/plugins/plugin-native-helsinki.md

@@ -32,6 +32,7 @@ Source: `plugins/native/helsinki/target/release/libhelsinki.so`
 | `model_dir` | `string` | no | `models/opus-mt-en-es` | Path to model directory containing safetensors and tokenizer files |
 | `source_language` | `string enum[en, es]` | no | `en` | Source language code: 'en' (English) or 'es' (Spanish) |
 | `target_language` | `string enum[en, es]` | no | `es` | Target language code: 'en' (English) or 'es' (Spanish) |
+| `warmup` | `boolean` | no | `false` | If true, run a small warmup translation during initialization to reduce first-request latency |
 
 
 <details>
@@ -86,6 +87,11 @@ Source: `plugins/native/helsinki/target/release/libhelsinki.so`
         "es"
       ],
       "type": "string"
+    },
+    "warmup": {
+      "default": false,
+      "description": "If true, run a small warmup translation during initialization to reduce first-request latency",
+      "type": "boolean"
     }
   },
   "type": "object"

docs/src/content/docs/reference/plugins/plugin-native-nllb.md

@@ -36,14 +36,14 @@ Source: `plugins/native/nllb/target/release/libnllb.so`
 
 ## Example Pipeline
 
-> [!CAUTION]
-> The NLLB model family is licensed **CC-BY-NC-4.0** (non-commercial). Verify the specific model license and your intended use before deploying in production.
-
 ```yaml
 # SPDX-FileCopyrightText: © 2025 StreamKit Contributors
 #
 # SPDX-License-Identifier: MPL-2.0
 
+#
+# skit:input_asset_tags=speech
+
 name: Speech Translation (English → Spanish)
 description: Translates English speech into Spanish speech
 mode: oneshot
@@ -74,6 +74,7 @@ steps:
       model_path: models/nllb-200-distilled-600M-ct2-int8
       source_language: eng_Latn
       target_language: spa_Latn
+      compute_type: int8
       beam_size: 1
       num_threads: 4
 

docs/src/content/docs/reference/plugins/plugin-native-sensevoice.md

@@ -40,6 +40,9 @@ Source: `plugins/native/sensevoice/target/release/libsensevoice.so`
 ## Example Pipeline
 
 ```yaml
+#
+# skit:input_asset_tags=speech
+
 name: Speech-to-Text (SenseVoice)
 description: Transcribes speech in multiple languages using SenseVoice
 mode: oneshot

docs/src/content/docs/reference/plugins/plugin-native-vad.md

@@ -43,6 +43,9 @@ Source: `plugins/native/vad/target/release/libvad.so`
 #
 # SPDX-License-Identifier: MPL-2.0
 
+#
+# skit:input_asset_tags=speech
+
 name: Voice Activity Detection
 description: Detects voice activity and outputs events as JSON
 mode: oneshot

docs/src/content/docs/reference/plugins/plugin-native-whisper.md

@@ -42,6 +42,9 @@ Source: `plugins/native/whisper/target/release/libwhisper.so`
 ## Example Pipeline
 
 ```yaml
+#
+# skit:input_asset_tags=speech
+
 name: Speech-to-Text (Whisper)
 description: Transcribes speech to text using Whisper
 mode: oneshot