docs: add comprehensive guide on host vs WASM bindings

Added new documentation to clarify the dual binding architecture and resolve
confusion around target triple mismatches. This addresses the core concepts
behind the fix for issue #16.

Key additions:
- New guide: "Host vs WASM Bindings" with complete examples and use cases
- Added to sidebar navigation for easy discovery
- Cross-references from rule reference and troubleshooting docs
- Visual diagrams showing the binding architecture
- Practical examples of when to use each binding type

The guide explains:
- How the same WIT-generated code creates two binding types
- Target platform differences (host vs wasm32-wasip2)
- Capabilities and limitations of each binding type
- Common errors and solutions
- Best practices for development workflows

This ensures developers understand when to use:
- {name}_bindings_host: For test runners, benchmarks, development tools
- {name}_bindings: For actual component implementations

Resolves documentation gaps around the host vs WASM binding architecture.

Author: avrabe

docs-site/CONTENT_HIERARCHY.md

@@ -0,0 +1,180 @@
+# Documentation Content Hierarchy
+
+## Purpose
+
+This document defines the clear content hierarchy for the docs-site to prevent duplication and ensure proper cross-referencing between pages.
+
+## Content Ownership Structure
+
+### 1. Installation & Setup (Canonical Sources)
+
+**Primary owner:** `/installation.md`
+- Complete installation instructions for all platforms
+- All language-specific setup (Rust, Go, C++, JavaScript)
+- Toolchain configuration details
+- Troubleshooting installation issues
+
+**Secondary references:**
+- `/getting-started.mdx` - Quick reference with link to full installation
+- `/first-component.md` - Minimal setup with reference to installation guide
+- Language-specific guides - Link to installation for setup details
+
+**Pattern:** Other pages should provide minimal setup and reference `/installation.md` for details.
+
+### 2. Tutorial Progression (Learning Path)
+
+**Ultra-fast (2 min):** `/zero-to-component.mdx`
+- Immediate success using existing examples
+- Minimal explanation, maximum speed
+- References detailed tutorials for understanding
+
+**Quick hands-on (10 min):** `/first-component.md`  
+- Build from scratch step-by-step
+- Focused on practical implementation
+- References installation and detailed tutorials
+
+**Complete understanding (30 min):** `/tutorials/rust-guided-walkthrough.mdx`
+- Deep explanations of concepts and pipeline
+- Line-by-line code analysis with diagrams
+- Complete mental model building
+
+**Technical reference:** `/tutorials/code-explained.mdx`
+- Visual diagrams of component building process
+- Progressive complexity with Mermaid diagrams
+- Technical deep-dive into each file
+
+### 3. Code Examples (Canonical Patterns)
+
+**BUILD.bazel patterns:**
+- **Owner:** `/examples/basic/` - Canonical Rust component pattern
+- **Owner:** `/examples/calculator/` - Error handling pattern
+- **Owner:** Language-specific examples - Language-specific patterns
+
+**References:**
+- Tutorial pages link to examples instead of duplicating BUILD.bazel code
+- Rule reference shows usage patterns, examples show complete implementations
+
+**WIT interface examples:**
+- **Owner:** `/tutorials/code-explained.mdx` - Detailed WIT explanations
+- **References:** Other pages link to detailed explanations rather than re-explaining
+
+### 4. Advanced Topics (Specialized Ownership)
+
+**Component Composition:**
+- **Owner:** `/composition/wac/` - Complete WAC composition guide
+- **References:** Getting started mentions composition, links to dedicated guide
+
+**Performance Optimization:**
+- **Owner:** `/production/performance/` - Wizer and optimization techniques
+- **References:** Other pages mention performance, link to dedicated guide
+
+**Security & Signing:**
+- **Owner:** `/security/component-signing.mdx` - Complete security guide
+- **References:** Brief mentions in other pages, links for details
+
+### 5. Language-Specific Content
+
+**Rust:** `/languages/rust/`
+**Go:** `/languages/go/`  
+**C++:** `/languages/cpp/`
+**JavaScript:** `/languages/javascript/`
+
+**Pattern:** Each language guide owns its specific patterns and advanced features. Getting started provides overview, language guides provide depth.
+
+### 6. Reference Documentation
+
+**Rule Reference:** `/reference/rules.mdx`
+- **Owner:** Complete API documentation for all rules
+- **Pattern:** Examples show usage, reference shows complete API
+
+**Troubleshooting:** `/troubleshooting/common-issues.mdx`
+- **Owner:** All error messages and solutions
+- **Pattern:** Other pages reference troubleshooting for specific issues
+
+## Content Cross-Reference Patterns
+
+### ✅ Good Patterns
+
+1. **Provide minimal context + link to canonical source**
+   ```markdown
+   For complete installation instructions, see the [Installation Guide](/installation/).
+   
+   Quick setup for Rust:
+   [minimal code example]
+   ```
+
+2. **Use approach grids for different learning paths**
+   ```html
+   <div class="approach-grid">
+     <div class="approach-card">
+       <h3>🚀 Ultra-Fast (2 minutes)</h3>
+       <p>Get working instantly</p>
+       <a href="/zero-to-component/">Zero to Component →</a>
+     </div>
+   </div>
+   ```
+
+3. **Reference examples instead of duplicating BUILD.bazel**
+   ```markdown
+   For the complete BUILD.bazel pattern, see the [basic example](/examples/basic/).
+   ```
+
+### ❌ Anti-Patterns to Avoid
+
+1. **Duplicating installation instructions**
+   - ❌ Copy full MODULE.bazel setup across multiple pages
+   - ✅ Provide minimal setup + link to installation guide
+
+2. **Re-explaining WIT syntax**
+   - ❌ Explain WIT syntax on every tutorial page  
+   - ✅ Link to detailed explanation in code-explained tutorial
+
+3. **Duplicating BUILD.bazel examples**
+   - ❌ Show complete BUILD.bazel on multiple pages
+   - ✅ Show pattern summary + link to complete example
+
+4. **Redundant troubleshooting**
+   - ❌ Scatter error solutions across multiple pages
+   - ✅ Centralize in troubleshooting guide + cross-reference
+
+## Content Update Protocol
+
+### When Adding New Content
+
+1. **Check existing hierarchy** - Does this content fit an existing owner?
+2. **Identify content type** - Tutorial, reference, example, or specialized guide?
+3. **Assign ownership** - Which page should be the canonical source?
+4. **Plan references** - How will other pages reference this content?
+
+### When Updating Existing Content
+
+1. **Identify the canonical owner** - Update the source of truth first
+2. **Update references** - Ensure cross-references remain accurate
+3. **Check for duplication** - Remove any content that duplicates the update
+
+### Review Checklist
+
+Before publishing content changes:
+
+- [ ] Is this content duplicated elsewhere?
+- [ ] Does this page properly reference canonical sources?
+- [ ] Are cross-references accurate and helpful?
+- [ ] Does this follow the established content hierarchy?
+- [ ] Would a new user understand the learning progression?
+
+## Maintenance
+
+This hierarchy should be reviewed quarterly to:
+- Identify new duplication that has crept in
+- Update reference patterns as content evolves
+- Ensure learning paths remain clear and progressive
+- Consolidate content that has become scattered
+
+## Success Metrics
+
+- **No content duplication** - Same information shouldn't exist in multiple places
+- **Clear learning paths** - Users can progress from beginner to advanced
+- **Fast answers** - Users can quickly find what they need
+- **Cross-references work** - Links lead to the right level of detail
+
+This hierarchy ensures our documentation grows systematically while remaining maintainable and user-friendly.

docs-site/astro.config.mjs

@@ -82,6 +82,7 @@ export default defineConfig({
 				{
 					label: 'Guides',
 					items: [
+						{ label: 'Host vs WASM Bindings', slug: 'guides/host-vs-wasm-bindings' },
 						{ label: 'Advanced Features', slug: 'guides/advanced-features' },
 						{ label: 'Migration Guide', slug: 'guides/migration' },
 						{ label: 'Toolchain Configuration', slug: 'guides/toolchain-configuration' },

docs-site/docs_build.bzl

@@ -56,7 +56,7 @@ def _docs_build_impl(ctx):
         # Install dependencies using hermetic npm (from PATH via tools)
         npm install --no-audit --no-fund
 
-        # Build documentation site
+        # Build documentation site (rule docs should be pre-generated)
         npm run build
 
         # Return to execution root and create output file there

docs-site/scripts/generate-rule-docs.js

@@ -23,7 +23,7 @@ const SCHEMA_GENERATOR_TARGET = '//tools/generate_schemas:generate_schemas';
  * Generate fresh schema JSON from Bazel
  */
 function generateSchemaJson() {
-    console.log('🔧 Generating fresh rule schemas from Bazel...');
+    console.log('Generating fresh rule schemas from Bazel...');
 
     try {
         const result = execSync(`cd "${REPO_ROOT}" && bazel run ${SCHEMA_GENERATOR_TARGET}`, {
@@ -33,7 +33,7 @@ function generateSchemaJson() {
 
         return JSON.parse(result);
     } catch (error) {
-        console.error('❌ Failed to generate schemas:', error.message);
+        console.error('Failed to generate schemas:', error.message);
 
         // Fallback: try to use existing schema file
         const fallbackPath = path.join(REPO_ROOT, 'docs/rule_schemas.json');
@@ -252,12 +252,12 @@ function generateRuleReference(schemas) {
  * Main execution
  */
 function main() {
-    console.log('📚 Generating Rule Reference Documentation...');
+    console.log('Generating Rule Reference Documentation...');
 
     try {
         // Generate schema JSON
         const schemas = generateSchemaJson();
-        console.log(`✅ Loaded ${Object.keys(schemas).length} rule definitions`);
+        console.log(`Loaded ${Object.keys(schemas).length} rule definitions`);
 
         // Generate markdown
         const markdown = generateRuleReference(schemas);
@@ -271,11 +271,11 @@ function main() {
         const outputPath = path.join(DOCS_OUTPUT_DIR, 'rules.mdx');
         fs.writeFileSync(outputPath, markdown, 'utf-8');
 
-        console.log(`📖 Generated rule reference: ${outputPath}`);
-        console.log(`📊 Documented ${Object.keys(schemas).length} rules and providers`);
+        console.log(`Generated rule reference: ${outputPath}`);
+        console.log(`Documented ${Object.keys(schemas).length} rules and providers`);
 
     } catch (error) {
-        console.error('❌ Error generating documentation:', error.message);
+        console.error('Error generating documentation:', error.message);
         process.exit(1);
     }
 }

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

@@ -90,6 +90,8 @@ wac_compose(
 )
 ```
 
+> **📋 Rule Reference:** For complete details on composition rule attributes, see [`wac_compose`](/reference/rules/#wac_compose) and [`wac_remote_compose`](/reference/rules/#wac_remote_compose).
+
 ### Component Interface Definitions
 
 Define interfaces that allow composition:

docs-site/src/content/docs/first-component.md

@@ -41,34 +41,23 @@ mkdir -p src wit
 touch BUILD.bazel MODULE.bazel Cargo.toml src/lib.rs wit/greeting.wit
 ```
 
-## Step 2: Configure Bazel Module
+## Step 2: Configure Your Project
 
-Set up your `MODULE.bazel`:
+Set up your project dependencies. For detailed installation instructions and advanced configuration options, see the [Installation Guide](/installation/).
+
+**Quick setup for Rust components:**
 
 ```python title="MODULE.bazel"
-module(
-    name = "my_first_component",
-    version = "0.1.0",
-)
+module(name = "my_first_component", version = "0.1.0")
 
-# Add rules_wasm_component
 bazel_dep(name = "rules_wasm_component", version = "1.0.0")
 bazel_dep(name = "rules_rust", version = "0.48.0")
 
-# Configure crate dependencies
 crate = use_extension("@rules_rust//crate_universe:extension.bzl", "crate")
-crate.from_cargo(
-    name = "crates",
-    cargo_lockfile = "//:Cargo.lock",
-    manifests = ["//:Cargo.toml"],
-)
+crate.from_cargo(name = "crates", cargo_lockfile = "//:Cargo.lock", manifests = ["//:Cargo.toml"])
 use_repo(crate, "crates")
 ```
 
-## Step 3: Set Up Rust Dependencies
-
-Create your `Cargo.toml`:
-
 ```toml title="Cargo.toml"
 [package]
 name = "my-first-component"
@@ -82,13 +71,11 @@ wit-bindgen = { version = "0.30.0", default-features = false, features = ["reall
 crate-type = ["cdylib"]
 ```
 
-Generate the lock file:
-
 ```bash
 cargo generate-lockfile
 ```
 
-## Step 4: Define the WIT Interface
+## Step 3: Define the WIT Interface
 
 Create your component interface in `wit/greeting.wit`:
 
@@ -112,7 +99,7 @@ world greeting-component {
 }
 ```
 
-## Step 5: Configure the Build
+## Step 4: Configure the Build
 
 Set up your `BUILD.bazel`:
 
@@ -141,7 +128,9 @@ rust_wasm_component_test(
 )
 ```
 
-## Step 6: Implement the Component
+> **📋 Rule Reference:** For complete details on all rule attributes and options, see [`wit_library`](/reference/rules/#wit_library), [`rust_wasm_component_bindgen`](/reference/rules/#rust_wasm_component_bindgen), and [`rust_wasm_component_test`](/reference/rules/#rust_wasm_component_test).
+
+## Step 5: Implement the Component
 
 Create your Rust implementation in `src/lib.rs`:
 
@@ -174,7 +163,7 @@ impl Guest for GreetingComponent {
         let count = GREETING_COUNTER.fetch_add(1, Ordering::SeqCst) + 1;
 
         // Generate personalized greeting
-        format!("Hello, {}! This is greeting #{} 👋", name, count)
+        format!("Hello, {}! This is greeting #{}", name, count)
     }
 
     fn random_greeting() -> String {
@@ -184,7 +173,7 @@ impl Guest for GreetingComponent {
         // Simple pseudo-random selection based on counter
         let greeting = GREETINGS[count as usize % GREETINGS.len()];
 
-        format!("{}, friend! 🎉", greeting)
+        format!("{}, friend!", greeting)
     }
 
     fn greeting_count() -> u32 {
@@ -196,7 +185,7 @@ impl Guest for GreetingComponent {
 greeting_component_bindings::export!(GreetingComponent with_types_in greeting_component_bindings);
 ```
 
-## Step 7: Build Your Component
+## Step 6: Build Your Component
 
 Now build your component with Bazel:
 
@@ -215,7 +204,7 @@ If the build succeeds, you'll see output like:
 INFO: Build completed successfully, 15 total actions
 ```
 
-## Step 8: Test Your Component
+## Step 7: Test Your Component
 
 Run the automated tests:
 
@@ -227,7 +216,7 @@ bazel test //:greeting_test
 # //:greeting_test                                 PASSED in 1.2s
 ```
 
-## Step 9: Inspect Your Component
+## Step 8: Inspect Your Component
 
 Examine the generated WebAssembly component:
 
@@ -242,7 +231,7 @@ wasm-tools validate bazel-bin/greeting_component.wasm --features component-model
 ls -lh bazel-bin/greeting_component.wasm
 ```
 
-## Step 10: Run Your Component
+## Step 9: Run Your Component
 
 If you have wasmtime installed, you can run your component:
 
@@ -253,10 +242,10 @@ wasmtime run --wasi preview2 bazel-bin/greeting_component.wasm
 
 <div class="demo-buttons">
   <a href="https://stackblitz.com/github/pulseengine/rules_wasm_component/tree/main/examples/basic" class="demo-button">
-    🚀 Try this tutorial in StackBlitz
+    Try this tutorial in StackBlitz
   </a>
   <a href="https://github.com/codespaces/new?repo=pulseengine/rules_wasm_component" class="demo-button">
-    ☁️ Open in GitHub Codespace
+    Open in GitHub Codespace
   </a>
 </div>