fix: correct wit_dependency_analyzer argument mismatch

- Revert to run_shell approach for proper output redirection
- Tool expects single config.json argument and outputs to stdout
- Fix incorrect two-argument call that caused usage errors
- Restores WIT dependency validation functionality

Author: avrabe

docs-site/astro.config.mjs

@@ -65,6 +65,14 @@ export default defineConfig({
 						{ label: 'Go Components', slug: 'languages/go' },
 					],
 				},
+				{
+					label: 'Guides',
+					items: [
+						{ label: 'Advanced Features', slug: 'guides/advanced-features' },
+						{ label: 'Toolchain Configuration', slug: 'guides/toolchain-configuration' },
+						{ label: 'External WIT Dependencies', slug: 'guides/external-wit-dependencies' },
+					],
+				},
 				{
 					label: 'Examples',
 					items: [

docs-site/src/content/docs/composition/wac.md

@@ -3,16 +3,28 @@ title: WAC Composition
 description: Build complex multi-component systems using WebAssembly Composition (WAC)
 ---
 
-Learn how to compose multiple WebAssembly components into sophisticated applications using WAC (WebAssembly Composition).
+## Building Applications from Components
 
-## Overview
+Think of **WAC (WebAssembly Composition)** as "wiring" for your WebAssembly components. Just like connecting electronic components on a circuit board, you can connect software components to create complete applications.
+
+**The magic of composition:** You can take a Rust authentication service, a Go database connector, a JavaScript frontend, and a C++ data processor - all built as separate WebAssembly components - and wire them together into a single application.
+
+**Why this matters:**
+- **Team independence** - Different teams can work on different components in their preferred languages
+- **Component reuse** - Build once, compose into multiple applications
+- **Easy testing** - Test components in isolation, then test the composition
+- **Flexible deployment** - Swap components without rebuilding everything
+
+**How it works:** You write a simple "composition script" that describes which components to instantiate and how to connect their interfaces. WAC handles all the complexity of making them work together.
+
+## Key Concepts
 
 WAC (WebAssembly Composition) allows you to:
 
-- ✅ **Connect Components** - Link multiple components together
-- ✅ **Define Data Flow** - Specify how data moves between components
-- ✅ **Create Applications** - Build complete systems from component parts
-- ✅ **Maintain Isolation** - Components remain independent and secure
+- **Connect Components** - Link multiple components together through their interfaces
+- **Define Data Flow** - Specify how data moves between components
+- **Create Applications** - Build complete systems from component parts
+- **Maintain Isolation** - Components remain independent and secure
 
 ## Basic Composition
 

docs-site/src/content/docs/getting-started.mdx

@@ -3,7 +3,17 @@ title: Getting Started
 description: Quick start guide for building WebAssembly components with Bazel
 ---
 
-Get up and running with WebAssembly Component Model in minutes using Bazel.
+## Welcome to the Future of Software Components
+
+Ready to build software that's **portable**, **secure**, and **fast**? WebAssembly components let you write code once and run it anywhere - from web browsers to servers, IoT devices to desktop apps.
+
+Think of WebAssembly components as **smart LEGO blocks** for software:
+- **Plug-and-play**: Components from different languages work together seamlessly
+- **Secure by design**: Each component runs in its own sandbox
+- **Near-native speed**: Performance similar to compiled C/C++
+- **Universal deployment**: Same component runs on any platform
+
+**rules_wasm_component** makes building these components as easy as traditional software - no complex WebAssembly knowledge required!
 
 ## Prerequisites
 
@@ -76,32 +86,56 @@ wit-bindgen = { version = "0.30.0", default-features = false, features = ["reall
 
 ## Your First Component
 
-Let's create a simple "Hello World" WebAssembly component:
+Let's create a simple "Hello World" WebAssembly component to see how easy it is.
+
+**What we're building**: A self-contained WebAssembly component that exports a "greet" function. Unlike traditional libraries, this component can be called from any language and runs in complete isolation.
+
+**The process**: We'll define an interface (what functions the component provides), implement the logic in Rust, and let Bazel handle all the WebAssembly compilation magic.
 
 ### 1. Define the WIT Interface
 
+**WIT (WebAssembly Interface Types)** is like a contract - it describes what functions your component provides and what types they use. This lets other components (in any language) know how to call your code.
+
 import CodeFromFile from '@components/CodeFromFile.astro';
 
 <CodeFromFile file="examples/basic/wit/hello.wit" title="examples/basic/wit/hello.wit" />
 
+This defines a "world" (think of it as an API) with one function: `greet` that takes a string and returns a string.
+
 ### 2. Create the Build File
 
+**Bazel BUILD files** tell the build system how to compile your code. Here we're saying "take this WIT interface and this Rust code, and build me a WebAssembly component":
+
 <CodeFromFile file="examples/basic/BUILD.bazel" title="examples/basic/BUILD.bazel" />
 
+The `wit_library` creates the interface definitions, and `rust_wasm_component` compiles your Rust code into a WebAssembly component that implements that interface.
+
 ### 3. Implement the Component
 
+**The Rust implementation** is just normal Rust code. The `wit-bindgen` macro automatically generates the glue code that connects your Rust functions to the WebAssembly component interface:
+
 <CodeFromFile file="examples/basic/src/lib.rs" title="examples/basic/src/lib.rs" />
 
 ### 4. Build the Component
 
+**That's it!** Bazel handles downloading the WebAssembly toolchain, compiling your Rust code, and packaging everything into a component:
+
 ```bash
 # Build the component
 bazel build //:hello_component
 
-# Test with wasmtime
+# Test with wasmtime (WebAssembly runtime)
 wasmtime run --wasi preview2 bazel-bin/hello_component.wasm
 ```
 
+**What just happened?** Bazel automatically:
+- Downloaded the Rust toolchain and WebAssembly tools
+- Compiled your Rust code to WebAssembly
+- Generated bindings from your WIT interface
+- Packaged everything into a `.wasm` component file
+
+Your component is now ready to run on any platform that supports WebAssembly!
+
 <div class="demo-buttons">
   <a href="https://stackblitz.com/github/pulseengine/rules_wasm_component/tree/main/examples/basic" class="demo-button">
     Try this example in StackBlitz

docs-site/src/content/docs/index.mdx

@@ -21,6 +21,41 @@ hero:
 
 import { Card, CardGrid } from '@astrojs/starlight/components';
 
+## What is the WebAssembly Component Model?
+
+The **WebAssembly Component Model** is a revolutionary approach to building portable, secure, and composable software. Think of it as "microservices for WebAssembly" - you can build small, focused components in any language and connect them together like LEGO blocks.
+
+### Why Should You Care?
+
+**🔗 Language Freedom**: Write your auth service in Rust, your API in Go, your frontend in JavaScript, and your ML pipeline in Python - all running together seamlessly.
+
+**🚀 Performance**: Near-native speed with WebAssembly's efficiency, but with the safety and portability of sandboxed execution.
+
+**📦 True Portability**: Build once, run anywhere - from edge devices to cloud servers, from browsers to embedded systems.
+
+**🔒 Security by Default**: Each component runs in its own sandbox with explicit interfaces - no hidden dependencies or side effects.
+
+### Real-World Use Cases
+
+- **Microservices**: Replace Docker containers with lightweight WASM components
+- **Plugin Systems**: Add extensibility to your apps with secure, fast plugins
+- **Edge Computing**: Deploy the same code to CDN edges, IoT devices, and cloud
+- **Multi-language Projects**: Combine the best tools from different ecosystems
+
+## Why rules_wasm_component?
+
+Building WebAssembly components traditionally involves complex toolchains and manual configuration. **rules_wasm_component** makes it as easy as:
+
+```python
+rust_wasm_component(
+    name = "my_service",
+    srcs = ["src/lib.rs"],
+    wit = ":my_interfaces",
+)
+```
+
+That's it! Bazel handles the complexity while you focus on building great software.
+
 ## Features
 
 <CardGrid stagger>

docs-site/src/content/docs/languages/rust.md

@@ -3,18 +3,35 @@ title: Rust Components
 description: Build WebAssembly components with Rust using rules_rust integration
 ---
 
-Build high-performance WebAssembly components with Rust, featuring seamless rules_rust integration and wit-bindgen support.
+## Why Rust for WebAssembly Components?
+
+Rust is the **ideal language** for WebAssembly components. Its zero-cost abstractions, memory safety, and lack of runtime overhead make it perfect for creating fast, secure, portable components.
+
+**The Rust advantage:**
+- **Memory safety without garbage collection** - Perfect for sandboxed environments
+- **Zero-cost abstractions** - High-level code compiles to efficient WebAssembly
+- **Excellent tooling** - wit-bindgen automatically generates all the glue code
+- **Small binaries** - Dead code elimination keeps components lightweight
+- **Mature ecosystem** - Leverage existing Rust crates in your components
+
+**How it works:** You write normal Rust code, define interfaces in WIT (WebAssembly Interface Types), and the toolchain handles all the WebAssembly compilation magic. The result is a portable component that can be called from any language.
 
 ## Features
 
-- ✅ **Full Component Model Support** - WASI Preview 2 and Component Model
-- ✅ **wit-bindgen Integration** - Automatic binding generation from WIT interfaces
-- ✅ **Multiple Build Profiles** - Debug, release, and custom configurations
-- ✅ **rules_rust Integration** - Leverages existing Bazel Rust ecosystem
-- ✅ **Incremental Builds** - Fast iteration with Bazel caching
+- **Full Component Model Support** - WASI Preview 2 and Component Model
+- **wit-bindgen Integration** - Automatic binding generation from WIT interfaces
+- **Multiple Build Profiles** - Debug, release, and custom configurations
+- **rules_rust Integration** - Leverages existing Bazel Rust ecosystem
+- **Incremental Builds** - Fast iteration with Bazel caching
 
 ## Basic Component
 
+Let's build a calculator component to demonstrate the core concepts. This example shows how to:
+- Define a clear interface with WIT
+- Implement business logic in pure Rust
+- Handle errors properly with WebAssembly-safe types
+- Build and test the component
+
 ### WIT Interface Definition
 
 ```wit title="wit/calculator.wit"
@@ -357,18 +374,20 @@ bazel query 'kind(rust_wasm_component, //...)'
 
 <div class="demo-buttons">
   <a href="https://stackblitz.com/github/pulseengine/rules_wasm_component/tree/main/examples/basic" class="demo-button">
-    🚀 Try Rust Example
+    Try Rust Example
   </a>
   <a href="/examples/basic/" class="demo-button">
-    📖 Full Example
+    Full Example
   </a>
 </div>
 
 ## Performance Characteristics
 
-<div class="perf-indicator">⚡ 1.35-6x faster startup with Wizer</div>
-<div class="perf-indicator">🚀 ~2MB typical component size</div>
-<div class="perf-indicator">💾 Low memory footprint with wee_alloc</div>
+**Production-ready performance** out of the box:
+
+<div class="perf-indicator">1.35-6x faster startup with Wizer</div>
+<div class="perf-indicator">~2MB typical component size</div>
+<div class="perf-indicator">Low memory footprint with wee_alloc</div>
 
 Rust components offer excellent performance characteristics:
 

wit/wit_deps_check.bzl

@@ -22,12 +22,13 @@ def _wit_deps_check_impl(ctx):
     # Run dependency analysis
     output_file = ctx.actions.declare_file(ctx.label.name + "_analysis.json")
 
-    # Run dependency analysis using Bazel-native approach
-    ctx.actions.run(
-        executable = ctx.executable._wit_dependency_analyzer,
-        arguments = [config_file.path, output_file.path],
+    # Run dependency analysis using ctx.actions.run_shell for output redirection
+    ctx.actions.run_shell(
+        command = "$1 $2 > $3",
+        arguments = [ctx.executable._wit_dependency_analyzer.path, config_file.path, output_file.path],
         inputs = [config_file, ctx.file.wit_file],
         outputs = [output_file],
+        tools = [ctx.executable._wit_dependency_analyzer],
         mnemonic = "CheckWitDependencies",
         progress_message = "Checking WIT dependencies in %s" % ctx.file.wit_file.short_path,
     )