docs(server): improve first-contributor experience

CONTRIBUTING.md

@@ -11,14 +11,67 @@ SPDX-License-Identifier: MPL-2.0
 ```bash
 git clone https://github.com/streamer45/streamkit.git
 cd streamkit
-cd ui && bun install && cd ..
-just dev    # starts backend + frontend with hot reload
+just build-ui   # build the embedded web UI (required before compiling the server)
+just dev        # starts backend + frontend with hot reload
 ```
 
-**Prerequisites:** Rust 1.92+, Bun 1.3+, [Just](https://github.com/casey/just) (recommended)
+**Prerequisites:** Rust 1.92+, Bun 1.3+, [Just](https://github.com/casey/just)
 
 Run `just --list` to see all available commands.
 
+## Prerequisites (detailed)
+
+### System packages (Ubuntu/Debian)
+
+```bash
+sudo apt install libopus-dev cmake pkg-config libssl-dev
+```
+
+### Rust toolchain
+
+The repo pins the toolchain via `rust-toolchain.toml` (currently Rust 1.92). Install Rust if you haven't already:
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+### Bun
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+### Just (task runner)
+
+```bash
+cargo install just
+```
+
+### Linting tools
+
+Required by `just lint`:
+
+```bash
+cargo install cargo-deny
+pip3 install --user reuse   # note: the apt version is too old
+```
+
+### Development mode
+
+Required by `just dev`:
+
+```bash
+cargo install cargo-watch
+```
+
+### Native plugin development (optional)
+
+Building ML plugins (e.g. whisper, sensevoice) requires additional dependencies:
+
+```bash
+sudo apt install clang libclang-dev
+```
+
 ## Making Changes
 
 1. Create a branch: `git checkout -b feat/my-feature` or `fix/my-bug`

docs/src/content/docs/getting-started/installation.md

@@ -34,12 +34,16 @@ If you want a native host install without containers, you can run the released `
 Required:
 
 - Rust toolchain (the repo is pinned via `rust-toolchain.toml`)
-- `just` (`cargo install just`)
-- Bun (`bun` in `$PATH`) to build the embedded web UI (`ui/dist`)
+- [Just](https://github.com/casey/just) task runner (`cargo install just`)
+- [Bun](https://bun.sh) (`bun` in `$PATH`) to build the embedded web UI (`ui/dist`)
+- System libraries (Ubuntu/Debian): `sudo apt install libopus-dev cmake pkg-config libssl-dev`
 
 Optional:
 
 - `cargo-watch` (`cargo install cargo-watch`) for `just dev`
+- `cargo-deny` (`cargo install cargo-deny`) for license checks in `just lint`
+- `reuse` (`pip3 install --user reuse`) for SPDX license header checks in `just lint` (note: the apt package is too old)
+- `clang` and `libclang-dev` (`sudo apt install clang libclang-dev`) for building native ML plugins (e.g. whisper, sensevoice)
 
 ### Build Steps
 

justfile

@@ -62,6 +62,20 @@ gen-plugin-bindings: fetch-wit-deps
     @gofmt -w sdks/plugin-sdk/go || true
 
 # --- skit ---
+# Pre-flight: ensure the UI has been built (required by RustEmbed)
+check-ui-dist:
+    @if [ ! -d ui/dist ]; then \
+        echo ""; \
+        echo "Error: ui/dist/ does not exist."; \
+        echo ""; \
+        echo "The skit server embeds the web UI at compile time (RustEmbed)."; \
+        echo "Build it first with:"; \
+        echo ""; \
+        echo "  just build-ui"; \
+        echo ""; \
+        exit 1; \
+    fi
+
 # Build the skit in release mode
 build-skit:
     @echo "Building skit..."
@@ -74,7 +88,7 @@ build-skit-profiling:
     @RUSTFLAGS="-C force-frame-pointers=yes" cargo build --release {{moq_features}} {{profiling_features}} -p streamkit-server --bin skit
 
 # Start the skit server
-skit *args='':
+skit *args='': check-ui-dist
     @echo "Starting skit..."
     @cargo run {{moq_features}} -p streamkit-server --bin skit -- {{args}}
 
@@ -165,8 +179,8 @@ test-skit:
 lint-skit:
     @echo "Linting skit..."
     @cargo fmt --all -- --check
-    @cargo clippy --workspace --all-targets -- -D warnings
     @cargo clippy -p streamkit-server --all-targets --features "moq" -- -D warnings
+    @cargo clippy --workspace --exclude streamkit-server --all-targets -- -D warnings
     @mkdir -p target
     @HOST=$(rustc -vV | sed -n 's/^host: //p'); \
       cargo metadata --locked --format-version 1 --filter-platform "$HOST" > target/cargo-metadata.json
@@ -177,8 +191,8 @@ lint-skit:
 fix-skit:
     @echo "Auto-fixing skit code..."
     @cargo fmt --all
-    @cargo clippy --fix --allow-dirty --allow-staged --workspace --all-targets -- -D warnings
     @cargo clippy --fix --allow-dirty --allow-staged -p streamkit-server --all-targets --features "moq" -- -D warnings
+    @cargo clippy --fix --allow-dirty --allow-staged --workspace --exclude streamkit-server --all-targets -- -D warnings
 
 # --- Frontend ---
 # Install UI dependencies using Bun
@@ -393,7 +407,7 @@ dev: install-ui
     @echo "Starting development environment..."
     @echo "Press Ctrl+C to exit."
     @trap 'kill 0' EXIT; \
-    (cd server && cargo watch -x "run {{moq_features}} --bin skit -- serve") & \
+    (cargo watch -x "run {{moq_features}} -p streamkit-server --bin skit -- serve") & \
     (cd ui && bun run dev)
 
 # --- Plugins ---