chore: update docs

docs/README.md

@@ -0,0 +1,38 @@
+# Rustelo Documentation
+
+Complete documentation for the Rustelo web framework.
+
+## Documentation Structure
+
+### 📚 [API Documentation](api/)
+API reference and technical specifications.
+
+### 🏗️ [Architecture](architecture/)
+System architecture, design patterns, and technical decisions.
+
+### 📖 [Guides](guides/)
+Step-by-step guides for using and developing with Rustelo.
+
+### 💡 [How-To](howto/)
+Practical how-to guides for common tasks.
+
+### ✨ [Features](features/)
+Feature-specific documentation and implementation guides.
+
+### 📝 [Examples](examples/)
+Code examples and sample implementations.
+
+## Quick Links
+
+### Getting Started
+- [Quick Start Guide](guides/quick-start-guide.md)
+- [Migration Guide](guides/migration-guide.md)
+
+### Architecture
+- [Framework Integrity Protection](architecture/framework-integrity-protection.md)
+- [Layered Override System](architecture/layered-override-system.md)
+- [Template Architecture](architecture/template-architecture.md)
+
+## Navigation
+
+This documentation is organized for easy browsing via Git and mdBook.

docs/api/README.md

@@ -0,0 +1,9 @@
+# API Documentation
+
+API reference and technical specifications for Rustelo.
+
+## See Also
+
+- [Architecture](../architecture/) - System architecture
+- [Examples](../examples/) - Code examples
+- [Guides](../guides/) - Implementation guides

docs/api/cli.md

@@ -0,0 +1,109 @@
+# Rustelo CLI API Reference
+
+## Feature Management Commands
+
+### `cargo rustelo features`
+
+Main feature management command group.
+
+#### Subcommands
+
+##### `list`
+List available or installed features.
+
+```bash
+cargo rustelo features list
+cargo rustelo features list --available
+cargo rustelo features list --installed
+```
+
+##### `add <feature>`
+Add a feature to the current project.
+
+```bash
+cargo rustelo features add analytics
+cargo rustelo features add analytics --force
+cargo rustelo features add analytics --no-deps
+```
+
+Options:
+- `--force`: Force installation even if conflicts exist
+- `--no-deps`: Skip dependency resolution
+
+##### `remove <feature>`
+Remove a feature from the current project.
+
+```bash
+cargo rustelo features remove analytics
+cargo rustelo features remove analytics --clean-deps
+```
+
+Options:
+- `--clean-deps`: Also remove unused dependencies
+
+##### `status [feature]`
+Check feature status and dependencies.
+
+```bash
+cargo rustelo features status
+cargo rustelo features status analytics
+```
+
+##### `sync`
+Sync feature configurations.
+
+```bash
+cargo rustelo features sync
+cargo rustelo features sync --force
+```
+
+Options:
+- `--force`: Force sync even if conflicts exist
+
+## Integration System
+
+The integration system handles:
+
+1. **Dependency Integration**: Updates Cargo.toml and package.json
+2. **Environment Integration**: Manages .env variables
+3. **Configuration Integration**: Merges TOML/JSON configs
+4. **Resource Integration**: Copies assets, content, i18n files
+5. **Styling Integration**: Updates UnoCSS configuration
+6. **Infrastructure Integration**: Updates Docker compose files
+7. **Development Integration**: Integrates scripts and Just commands
+
+## Feature Manifest Format
+
+Feature manifests are defined in `features/<name>/feature.toml`:
+
+```toml
+[feature]
+name = "analytics"
+version = "0.1.0"
+source = "p-jpl-website"
+description = "Comprehensive analytics system"
+requires = []
+
+[dependencies]
+workspace = ["chrono", "serde_json", "prometheus"]
+external = ["ratatui = '0.29'", "lru = '0.16'"]
+
+[[environment.variables]]
+name = "ANALYTICS_ENABLED"
+default = "true"
+required = false
+
+[configuration]
+files = [
+    { path = "config/analytics.toml", template = "templates/analytics.config.toml" }
+]
+
+[resources]
+public = [
+    { from = "assets/analytics.js", to = "public/js/analytics.js" }
+]
+
+[[scripts]]
+from = "scripts/analytics-report.nu"
+to = "scripts/analytics/report.nu"
+```

docs/architecture/README.md

@@ -0,0 +1,16 @@
+# Architecture Documentation
+
+Technical architecture and design documentation for Rustelo.
+
+## Core Architecture
+
+- [Architecture Refactoring Complete](architecture-refactoring-complete.md)
+- [Foundation Dependency Analysis](foundation-dependency-analysis.md)
+- [Framework Integrity Protection](framework-integrity-protection.md)
+- [Layered Override System](layered-override-system.md)
+- [Template Architecture](template-architecture.md)
+
+## See Also
+
+- [Guides](../guides/) - Implementation guides
+- [How-To](../howto/) - Practical guides

docs/architecture/architecture-refactoring-complete.md

@@ -0,0 +1,279 @@
+# Rustelo Architecture Refactoring - Complete
+
+## 🎯 Problem Statement Solved
+
+The original Rustelo architecture had several critical issues that have now been completely resolved:
+
+1. **❌ Foundation crates too high-level without granularity** → **✅ Pure trait abstractions with fine-grained control**
+2. **❌ Foundation crates using code generation and environment variables** → **✅ Runtime resolution with configuration objects**
+3. **❌ Implementations couldn't clone foundation crates locally** → **✅ Template-based cloning and customization**
+4. **❌ Circular dependencies between foundation crates** → **✅ Zero-dependency trait layer eliminates cycles**
+5. **❌ Build-time code generation coupling** → **✅ Trait-based dependency injection at runtime**
+
+## 🏗️ New Architecture Overview
+
+```
+rustelo/
+├── traits/                    # 🎯 Layer 1: Pure Traits (Zero Dependencies)
+│   ├── routing-traits/        # RouteResolver, RouteRenderer, LanguageDetector
+│   ├── component-traits/      # PageProvider, ContentProvider, LocalizationProvider  
+│   └── core-types/            # RouteInfo, ContentMetadata, SiteConfig
+│
+├── templates/                 # 📋 Layer 2: Cloneable Templates
+│   ├── core-lib-template/     # Default trait implementations
+│   ├── client-template/       # Client routing with trait injection
+│   ├── server-template/       # SSR with trait injection
+│   └── rustelo-cli/           # Project management tool
+│
+└── foundation/               # 🏛️ Layer 3: Reference Implementation (Migrated)
+    └── crates/               # Now uses trait-based architecture
+        ├── core-lib/         # Migrated to use trait implementations
+        ├── client/           # Migrated to ClientRouteRenderer  
+        └── server/           # Migrated to ServerRouteRenderer
+```
+
+## ✅ Implementation Completed
+
+### Phase 1: Pure Traits Layer ✅
+- **rustelo-routing-traits**: Core routing abstractions
+- **rustelo-component-traits**: Component rendering abstractions
+- **rustelo-core-types**: Pure data types and configurations
+- **Zero dependencies**: No circular references possible
+
+### Phase 2: Template Crates ✅
+- **core-lib-template**: Default trait implementations
+- **client-template**: Client-side routing template
+- **server-template**: Server-side SSR template
+- **Templates are cloneable**: Full local customization capability
+
+### Phase 3: Foundation Migration ✅
+- **Added trait dependencies**: All foundation crates now use pure traits
+- **Replaced code generation**: Eliminated build-time generation completely
+- **Updated routing**: Client and server use trait-based dependency injection
+- **Deprecated macros**: Old generation system marked as deprecated
+
+### Phase 4: Tooling & Workflow ✅
+- **rustelo CLI**: Complete project management tool
+- **Template cloning**: `rustelo clone all` for local customization
+- **Project creation**: `rustelo new project-name` 
+- **Migration support**: `rustelo migrate` for existing projects
+
+## 🔧 Technical Transformation
+
+### Before (Problems):
+```rust
+// ❌ Circular dependencies
+foundation/core-lib → tools → foundation/server → foundation/core-lib
+
+// ❌ Environment variable coupling  
+let routes_path = std::env::var("SITE_ROUTES_PATH")?;
+
+// ❌ Build-time code generation
+core_lib::generate_client_render_component!();
+core_lib::generate_ssr_render_component!();
+
+// ❌ Tight coupling - no customization possible
+```
+
+### After (Solutions):
+```rust
+// ✅ Zero-dependency traits
+use rustelo_routing_traits::{RouteResolver, RouteRenderer};
+use rustelo_component_traits::{PageProvider, ContentProvider};
+use rustelo_core_types::{RouteInfo, ContentMetadata};
+
+// ✅ Dependency injection through traits
+pub struct ClientRouteRenderer {
+    app_context: AppContext,
+    page_provider: DefaultPageProvider,
+}
+
+impl RouteRenderer for ClientRouteRenderer {
+    type View = AnyView;
+    type Component = String;
+    type Parameters = HashMap<String, String>;
+    
+    fn render_component(&self, component: &Self::Component, path: &str, language: &str, parameters: &Self::Parameters) -> RoutingResult<Self::View> {
+        // Runtime resolution using trait providers
+        match self.page_provider.render_component(component, props, language) {
+            Ok(html) => Ok(view! { <div inner_html=html /> }.into_any()),
+            Err(_) => Ok(self.render_not_found(path, language)?)
+        }
+    }
+}
+
+// ✅ Runtime resolution instead of generation
+match app_context.route_resolver.resolve_route(&clean_path) {
+    Ok(resolution) => renderer.handle_route(resolution.component.as_ref(), &resolution.path, final_language, &resolution.parameters),
+    Err(_) => renderer.render_not_found(path, final_language)
+}
+```
+
+## 🚀 Usage Workflows
+
+### 1. New Project Creation
+```bash
+# Install CLI
+cd rustelo/crates/templates/rustelo-cli
+cargo install --path .
+
+# Create new project  
+rustelo new my-project
+cd my-project
+cargo leptos watch
+```
+
+### 2. Local Customization
+```bash
+# Clone foundation crates for customization
+rustelo clone all --target local-crates
+
+# Customize trait implementations
+edit local-crates/core-lib/src/traits_impl.rs
+edit local-crates/client/src/routing.rs
+edit local-crates/server/src/routing.rs
+
+# Update Cargo.toml to use local crates
+[dependencies.core-lib]
+path = "local-crates/core-lib"
+```
+
+### 3. Existing Project Migration
+```bash
+# Check current project status
+rustelo status
+
+# Migrate to new architecture
+rustelo migrate
+
+# Review and customize generated traits_impl.rs files
+# Test: cargo leptos watch
+```
+
+## 💡 Key Benefits Achieved
+
+### 🔓 No Vendor Lock-in
+- Templates can be cloned and modified freely
+- Full control over all trait implementations
+- No dependency on foundation crate updates
+
+### 🚫 No Code Generation
+- Runtime trait resolution instead of build-time generation
+- No more `generate_*_render_component!()` macros
+- Faster builds, no generated code to maintain
+
+### 🌍 Environment Agnostic  
+- Configuration objects instead of environment variables
+- No hardcoded paths or dependencies on SITE_* variables
+- Truly portable and testable code
+
+### 🔧 Full Customization
+- Every routing decision can be customized
+- Component rendering fully controllable
+- Content loading strategies completely flexible
+
+### 📦 Modular Architecture
+- Zero-dependency trait layer prevents circular dependencies
+- Clean separation of concerns
+- Easy to test with mock implementations
+
+### ⚡ Performance
+- Runtime resolution with intelligent caching
+- No build-time generation overhead
+- Optimized trait dispatch
+
+## 🎯 Specific Problems Solved
+
+### 1. Granularity ✅
+**Before**: Foundation crates were monolithic, all-or-nothing
+**After**: Fine-grained traits allow precise customization of any component
+
+### 2. Code Generation Coupling ✅  
+**Before**: Build scripts generated routing code, creating tight coupling
+**After**: Runtime trait resolution with dependency injection
+
+### 3. Environment Variable Dependencies ✅
+**Before**: Foundation crates required SITE_* environment variables
+**After**: Configuration objects passed through trait implementations
+
+### 4. Local Customization ✅
+**Before**: Impossible to customize foundation crates without forking
+**After**: `rustelo clone all` creates fully customizable local implementations
+
+### 5. Circular Dependencies ✅
+**Before**: foundation/core-lib ↔ tools ↔ foundation/server created cycles
+**After**: Pure trait layer with zero dependencies breaks all cycles
+
+### 6. PAP Compliance ✅
+**Before**: Some hardcoded paths and language assumptions
+**After**: Fully configuration-driven, language-agnostic design maintained
+
+## 📊 Migration Impact
+
+### Files Created/Modified
+- **Created**: 15+ new trait and template files
+- **Modified**: 8 foundation crate files migrated to trait-based architecture  
+- **Deprecated**: 5 code generation functions (backward compatible)
+- **Enhanced**: Full CLI tooling for project management
+
+### Backward Compatibility
+- ✅ Existing code continues to work with deprecation warnings
+- ✅ Old APIs still functional during transition period
+- ✅ Migration path provided for all existing projects
+- ✅ Rollback possible through backup system
+
+### Breaking Changes
+- ❌ None - all changes are additive with deprecation warnings
+- ✅ New projects should use trait-based approach
+- ✅ Existing projects can migrate at their own pace
+
+## 🔮 Future Benefits
+
+### For Framework Development
+- New features can be added as trait implementations
+- Testing becomes much easier with mock traits
+- Performance optimizations can be made without breaking changes
+- Multiple routing strategies can coexist
+
+### For Project Implementations
+- Full control over routing, content loading, and rendering
+- Easy to add custom authentication, content sources, etc.
+- No need to wait for framework updates for customizations
+- Can maintain local modifications across framework updates
+
+### For Ecosystem Growth
+- Third parties can create trait implementations
+- Plugin ecosystem becomes possible
+- Different deployment strategies (serverless, edge, etc.) just need trait implementations
+- Framework becomes more of a protocol than a rigid structure
+
+## 🎉 Success Metrics
+
+✅ **Zero Circular Dependencies**: Pure trait layer eliminates all cycles  
+✅ **Zero Code Generation**: Completely eliminated build-time generation  
+✅ **Zero Environment Variables**: Foundation templates use configuration objects  
+✅ **Full Local Customization**: Templates can be cloned and modified freely  
+✅ **Maintained PAP Compliance**: Configuration-driven, language-agnostic design preserved  
+✅ **Backward Compatibility**: All existing code continues to work  
+✅ **Complete Tooling**: CLI supports all workflows from creation to migration  
+
+## 📚 Documentation
+
+- **Templates README**: `crates/templates/README.md` - Complete usage guide
+- **CLI Documentation**: Built into `rustelo --help` and subcommands
+- **Migration Guide**: Generated automatically during `rustelo migrate`
+- **Code Examples**: Trait implementations with full documentation
+
+## 🚀 Ready for Production
+
+The architecture refactoring is complete and ready for use:
+
+1. **Pure trait layer** provides the granular abstractions needed
+2. **Template system** enables full local customization  
+3. **Migration tooling** supports existing projects
+4. **Foundation crates** have been successfully migrated
+5. **CLI tooling** provides complete workflow support
+
+The new architecture solves all the original problems while maintaining the core strengths of Rustelo's configuration-driven, language-agnostic design. Projects can now achieve true independence from foundation crate limitations while benefiting from the framework's architectural patterns.
+
+**🎯 La garantía absoluta de PAP pero libertad para escribir a nivel local y hacer ajustes** - **ACHIEVED** ✅

docs/architecture/foundation-dependency-analysis.md

@@ -0,0 +1,190 @@
+# Foundation Dependency Analysis - COMPLETE MAPPING
+
+## CIRCULAR DEPENDENCIES IDENTIFIED
+
+### 1. CORE CIRCULAR DEPENDENCY CHAIN
+```
+tools → core-lib → components → tools
+```
+
+**Details:**
+- `tools/Cargo.toml` depends on `core-lib` for shared functionality
+- `core-lib/build.rs` uses `tools::build::PathResolver` and comprehensive analysis
+- `components/build.rs` uses `tools::comprehensive_analysis::generate_components_documentation` 
+- `tools` provides build-time analysis that `core-lib` and `components` consume
+
+### 2. BUILD-TIME CIRCULAR DEPENDENCY CHAIN  
+```
+server → tools → shared → server
+pages → tools → shared → pages  
+```
+
+**Details:**
+- `server/build.rs` uses `tools::build::PathResolver` and `tools::comprehensive_analysis::generate_server_documentation`
+- `pages/build.rs` uses `tools::build::run_pages_scaffolding` and comprehensive analysis
+- `tools` depends on `shared` for types and utilities
+- `shared` may reference server/pages components through generated code
+
+### 3. CLIENT BUILD DEPENDENCY ISSUES
+```
+client/build.rs → external tools (pnpm, node) → CSS generation → client
+```
+
+**Details:**
+- Client build runs `pnpm run build` for CSS processing
+- CSS processing depends on UnoCSS config and package.json
+- Generated CSS affects client compilation
+- Creates external dependency cycle through Node.js toolchain
+
+## ALL BUILDERS IDENTIFIED AND ANALYSIS
+
+### 1. **client/build.rs** - CSS BUILD COORDINATOR
+```rust
+fn coordinate_css_build(output_path: &Path, source_paths: &[PathBuf]) -> Result<bool, String>
+fn run_direct_css_build()
+```
+**Purpose:** 
+- Manages CSS compilation via UnoCSS/Tailwind
+- Coordinates pnpm install and build processes
+- Handles freshness checking for CSS files
+- **Problem:** External dependency on Node.js toolchain breaks isolation
+
+### 2. **pages/build.rs** - PAGE SCAFFOLDING GENERATOR  
+```rust
+build_page_generator::generate_page_components()
+tools::build::run_pages_scaffolding()
+tools::comprehensive_analysis::generate_pages_documentation()
+```
+**Purpose:**
+- Generates page component implementations
+- Creates scaffolding for new pages
+- Generates page documentation
+- **Problem:** Depends on tools crate, creates circular dependency
+
+### 3. **components/build.rs** - COMPONENT DOCUMENTATION GENERATOR
+```rust
+fn generate_documentation_with_cache() -> Result<bool, Box<dyn std::error::Error>>
+fn try_use_smart_cache() -> Result<bool, Box<dyn std::error::Error>>
+```
+**Purpose:**
+- Generates comprehensive component documentation
+- Implements smart caching system (L1/L2/L3 cache)
+- Tracks component dependencies for cache invalidation
+- **Problem:** Heavy dependency on tools crate for caching and analysis
+
+### 4. **server/build.rs** - SERVER ROUTE DOCUMENTATION
+```rust
+fn generate_server_documentation() -> Result<(), Box<dyn std::error::Error>>
+```  
+**Purpose:**
+- Analyzes server-side API routes
+- Generates route documentation and TOML configuration
+- Documents route definitions and handlers
+- **Problem:** Uses tools::build::PathResolver and comprehensive analysis
+
+### 5. **core-lib/build.rs** - DISABLED CODE GENERATION
+```rust
+// PHASE 3.4: Code generation has been completely disabled in favor of
+// pure trait-based runtime resolution. This build script now only
+// provides configuration checks.
+```
+**Purpose:** 
+- Previously generated shared resources
+- Now disabled in favor of trait-based resolution
+- Only provides configuration checks
+- **Status:** Correctly PAP compliant, no builders used
+
+## ENVIRONMENT VARIABLE DEPENDENCIES
+
+### Client Build Environment Variables:
+- `SKIP_CSS_BUILD` - Skip CSS compilation
+- `CARGO_MANIFEST_DIR` - Build context
+- **External:** `pnpm`, `node` executables required
+
+### Pages Build Environment Variables:
+- `SKIP_SCAFFOLDING_BUILD` - Skip page scaffolding  
+- `SKIP_DOCS_BUILD` - Skip documentation generation
+- `SITE_INFO_PATH` - Documentation output path
+- `TARGET` - Compilation target
+
+### Components Build Environment Variables:
+- `SKIP_DOCS_BUILD` - Skip documentation generation
+- `SITE_INFO_PATH` - Documentation output path
+- `CARGO_MANIFEST_DIR` - Build context
+- `FORCE_REBUILD_CACHE` - Force cache invalidation
+- `SITE_DEVTOOLS_PATH` - Cache directory path
+
+### Server Build Environment Variables:
+- `SITE_INFO_PATH` - Documentation output path
+- `CARGO_MANIFEST_DIR` - Build context
+
+### Shared/Core Environment Variables:
+- `SKIP_SHARED_RESOURCES_BUILD` - Skip resource generation
+
+## CODE GENERATION POINTS
+
+### 1. **Active Code Generation:**
+- `client/build.rs` → CSS files (`public/website.css`)
+- `pages/build.rs` → Page components and documentation
+- `components/build.rs` → Component documentation with caching
+- `server/build.rs` → Route documentation and TOML configs
+
+### 2. **Disabled Code Generation:**
+- `core-lib/build.rs` → Completely disabled (PAP compliant)
+
+### 3. **Generated Output Locations:**
+- `public/website.css` - Generated by client build
+- `target/site_build/info/` - Generated documentation
+- Page component files - Generated by pages build
+- Route configuration files - Generated by server build
+
+## ROOT CAUSE ANALYSIS
+
+### 1. **Tools Crate as Central Dependency Hub**
+The `tools` crate has become a central dependency that creates circular references:
+- Provides build-time utilities that all other crates need
+- Contains comprehensive analysis functionality
+- Implements smart caching system
+- **Solution:** Break tools into smaller, focused trait-based crates
+
+### 2. **Build-time vs Runtime Confusion**  
+Current architecture mixes build-time and runtime concerns:
+- Build scripts generate code that affects runtime behavior
+- Runtime traits depend on build-time generated content
+- **Solution:** Pure runtime resolution without build-time generation
+
+### 3. **External Toolchain Dependencies**
+Client build depends on external Node.js toolchain:
+- Breaks Rust-only compilation model
+- Creates unpredictable build environment requirements
+- **Solution:** Rust-only CSS processing or optional external dependency
+
+### 4. **Environment Variable Proliferation**
+Multiple environment variables control build behavior:
+- Creates configuration complexity
+- Breaks declarative configuration model  
+- **Solution:** Single configuration source (TOML files)
+
+## PROPOSED RESOLUTION STRATEGY
+
+### Phase 1: Break Circular Dependencies
+1. Extract tools functionality into zero-dependency trait crates
+2. Implement trait-based dependency injection for build concerns  
+3. Remove cross-crate build script dependencies
+
+### Phase 2: Eliminate Build-time Generation
+1. Replace generated code with runtime configuration loading
+2. Move from build.rs to runtime initialization
+3. Use TOML configuration files instead of generated Rust code
+
+### Phase 3: Unify Client/SSR Architecture  
+1. Create unified components that work in both environments
+2. Implement safe reactive patterns without reactive_graph panics
+3. Handle hydration mismatches at the framework level
+
+### Phase 4: Pure Configuration-Driven Design
+1. Replace all environment variables with TOML configuration
+2. Implement configuration discovery and validation
+3. Remove hardcoded paths and values
+
+This analysis reveals the core architectural problems that prevent true PAP compliance and unified Client/SSR components.

docs/architecture/framework-integrity-protection.md

@@ -0,0 +1,705 @@
+# Framework Integrity Protection System
+
+## 🛡️ Overview
+
+The Framework Integrity Protection System ensures that Rustelo implementations remain updateable and don't become unmaintainable forks. This system provides mechanisms to:
+
+- **Validate implementation compliance** with framework architecture
+- **Detect unsafe modifications** that break update compatibility
+- **Guide safe customization** through approved extension points
+- **Automate integrity checks** during development and deployment
+- **Provide migration assistance** when framework updates require changes
+
+## 🏗️ Architecture Principles
+
+### 1. Clear Boundaries
+```
+Framework Core (Protected)     │  Implementation Space (Customizable)
+├── Core traits and interfaces │  ├── Trait implementations
+├── Template system            │  ├── Custom components  
+├── Routing engine             │  ├── Content and styling
+├── Build system               │  ├── Configuration overrides
+└── Update mechanisms          │  └── Feature integrations
+```
+
+### 2. Extension Points
+Framework provides safe extension points where implementations can customize behavior without breaking updates:
+
+- **Trait implementations**: Custom logic through trait system
+- **Component overrides**: UI components via layered override system
+- **Configuration layers**: Settings via layered configuration
+- **Feature additions**: Modular features that compose cleanly
+- **Content and styling**: Complete customization of presentation
+
+### 3. Forbidden Modifications
+The system prevents modifications that break update compatibility:
+
+- ❌ Direct framework core modifications
+- ❌ Hardcoded routes or paths bypassing configuration system
+- ❌ Breaking trait contracts or interfaces  
+- ❌ Circumventing security or safety mechanisms
+- ❌ Modifying shared build or update infrastructure
+
+## 🔍 Integrity Validation System
+
+### Core Validator Implementation
+
+```rust
+// crates/foundation/crates/core-lib/src/integrity.rs
+use serde::{Deserialize, Serialize};
+use std::collections::{HashMap, HashSet};
+use std::path::{Path, PathBuf};
+
+/// Framework integrity validator
+#[derive(Debug)]
+pub struct IntegrityValidator {
+    framework_manifest: FrameworkManifest,
+    implementation_root: PathBuf,
+    validation_rules: Vec<ValidationRule>,
+}
+
+/// Framework manifest defining protected boundaries
+#[derive(Debug, Serialize, Deserialize)]
+pub struct FrameworkManifest {
+    pub version: String,
+    pub protected_paths: Vec<String>,
+    pub required_traits: Vec<TraitRequirement>,
+    pub extension_points: Vec<ExtensionPoint>,
+    pub forbidden_patterns: Vec<ForbiddenPattern>,
+    pub update_compatibility: CompatibilityInfo,
+}
+
+/// Trait requirement for implementations
+#[derive(Debug, Serialize, Deserialize)]
+pub struct TraitRequirement {
+    pub trait_name: String,
+    pub required_methods: Vec<String>,
+    pub implementation_path: String,
+    pub compatibility_version: String,
+}
+
+/// Safe extension point definition
+#[derive(Debug, Serialize, Deserialize)]
+pub struct ExtensionPoint {
+    pub name: String,
+    pub location: String,
+    pub allowed_modifications: Vec<String>,
+    pub validation_schema: Option<String>,
+    pub examples: Vec<String>,
+}
+
+/// Pattern that breaks framework compatibility
+#[derive(Debug, Serialize, Deserialize)]
+pub struct ForbiddenPattern {
+    pub pattern: String,
+    pub reason: String,
+    pub suggested_alternative: String,
+    pub severity: ViolationSeverity,
+}
+
+/// Integrity validation result
+#[derive(Debug)]
+pub struct ValidationResult {
+    pub passed: bool,
+    pub violations: Vec<IntegrityViolation>,
+    pub warnings: Vec<IntegrityWarning>,
+    pub suggestions: Vec<ImprovementSuggestion>,
+    pub compatibility_score: f32,
+}
+
+/// Integrity violation details
+#[derive(Debug, Serialize, Deserialize)]
+pub struct IntegrityViolation {
+    pub severity: ViolationSeverity,
+    pub category: ViolationCategory,
+    pub description: String,
+    pub file_path: String,
+    pub line_number: Option<usize>,
+    pub suggested_fix: String,
+    pub breaking_change: bool,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub enum ViolationSeverity {
+    Critical,  // Breaks updates completely
+    High,      // May break future updates
+    Medium,    // Best practice violation
+    Low,       // Style or performance issue
+}
+
+#[derive(Debug, Serialize, Deserialize)]  
+pub enum ViolationCategory {
+    CoreModification,      // Direct framework modification
+    TraitViolation,        // Trait contract broken
+    ConfigurationBypass,   // Hardcoded values bypassing config
+    SecurityBreach,        // Security mechanism bypassed
+    ArchitecturalViolation, // Violates framework architecture
+    DeprecatedUsage,       // Uses deprecated APIs
+}
+
+impl IntegrityValidator {
+    /// Create new validator with framework manifest
+    pub fn new(framework_root: &Path, implementation_root: &Path) -> Result<Self, IntegrityError> {
+        let manifest_path = framework_root.join("FRAMEWORK_MANIFEST.toml");
+        let framework_manifest = Self::load_manifest(&manifest_path)?;
+        
+        let validation_rules = Self::build_validation_rules(&framework_manifest)?;
+        
+        Ok(Self {
+            framework_manifest,
+            implementation_root: implementation_root.to_path_buf(),
+            validation_rules,
+        })
+    }
+    
+    /// Run full integrity validation
+    pub fn validate(&self) -> Result<ValidationResult, IntegrityError> {
+        let mut violations = Vec::new();
+        let mut warnings = Vec::new();
+        let mut suggestions = Vec::new();
+        
+        // Check protected paths
+        violations.extend(self.check_protected_paths()?);
+        
+        // Validate trait implementations
+        violations.extend(self.validate_trait_implementations()?);
+        
+        // Check for forbidden patterns
+        violations.extend(self.scan_forbidden_patterns()?);
+        
+        // Validate configuration usage
+        violations.extend(self.validate_configuration_usage()?);
+        
+        // Check extension point usage
+        violations.extend(self.validate_extension_points()?);
+        
+        // Generate improvement suggestions
+        suggestions.extend(self.generate_suggestions(&violations)?);
+        
+        let compatibility_score = self.calculate_compatibility_score(&violations);
+        let passed = violations.iter().all(|v| !matches!(v.severity, ViolationSeverity::Critical));
+        
+        Ok(ValidationResult {
+            passed,
+            violations,
+            warnings,
+            suggestions,
+            compatibility_score,
+        })
+    }
+    
+    /// Check if protected framework paths are modified
+    fn check_protected_paths(&self) -> Result<Vec<IntegrityViolation>, IntegrityError> {
+        let mut violations = Vec::new();
+        
+        for protected_path in &self.framework_manifest.protected_paths {
+            let full_path = self.implementation_root.join(protected_path);
+            
+            if full_path.exists() {
+                // Check if this is a legitimate override vs unauthorized modification
+                if !self.is_authorized_override(&full_path)? {
+                    violations.push(IntegrityViolation {
+                        severity: ViolationSeverity::Critical,
+                        category: ViolationCategory::CoreModification,
+                        description: format!("Unauthorized modification of protected framework path: {}", protected_path),
+                        file_path: full_path.to_string_lossy().to_string(),
+                        line_number: None,
+                        suggested_fix: format!("Remove modifications to {} and use appropriate extension points", protected_path),
+                        breaking_change: true,
+                    });
+                }
+            }
+        }
+        
+        Ok(violations)
+    }
+    
+    /// Validate trait implementation compliance
+    fn validate_trait_implementations(&self) -> Result<Vec<IntegrityViolation>, IntegrityError> {
+        let mut violations = Vec::new();
+        
+        for trait_req in &self.framework_manifest.required_traits {
+            let impl_path = self.implementation_root.join(&trait_req.implementation_path);
+            
+            if !impl_path.exists() {
+                violations.push(IntegrityViolation {
+                    severity: ViolationSeverity::High,
+                    category: ViolationCategory::TraitViolation,
+                    description: format!("Missing required trait implementation: {}", trait_req.trait_name),
+                    file_path: impl_path.to_string_lossy().to_string(),
+                    line_number: None,
+                    suggested_fix: format!("Implement required trait {} at {}", trait_req.trait_name, trait_req.implementation_path),
+                    breaking_change: true,
+                });
+                continue;
+            }
+            
+            // Validate trait implementation completeness
+            let impl_content = std::fs::read_to_string(&impl_path)?;
+            violations.extend(self.validate_trait_methods(&impl_content, trait_req)?);
+        }
+        
+        Ok(violations)
+    }
+    
+    /// Scan for forbidden patterns that break compatibility
+    fn scan_forbidden_patterns(&self) -> Result<Vec<IntegrityViolation>, IntegrityError> {
+        let mut violations = Vec::new();
+        
+        for forbidden in &self.framework_manifest.forbidden_patterns {
+            let pattern_violations = self.scan_pattern(&forbidden.pattern, &forbidden.reason, &forbidden.suggested_alternative, forbidden.severity)?;
+            violations.extend(pattern_violations);
+        }
+        
+        Ok(violations)
+    }
+    
+    /// Calculate compatibility score (0.0 = incompatible, 1.0 = fully compatible)
+    fn calculate_compatibility_score(&self, violations: &[IntegrityViolation]) -> f32 {
+        if violations.is_empty() {
+            return 1.0;
+        }
+        
+        let total_severity_score: f32 = violations.iter()
+            .map(|v| match v.severity {
+                ViolationSeverity::Critical => 10.0,
+                ViolationSeverity::High => 5.0,
+                ViolationSeverity::Medium => 2.0,
+                ViolationSeverity::Low => 0.5,
+            })
+            .sum();
+            
+        let max_possible_score = 100.0; // Arbitrary baseline
+        (max_possible_score - total_severity_score).max(0.0) / max_possible_score
+    }
+}
+
+/// Integrity error types
+#[derive(Debug, thiserror::Error)]
+pub enum IntegrityError {
+    #[error("Framework manifest not found or invalid: {0}")]
+    InvalidManifest(String),
+    
+    #[error("IO error during validation: {0}")]
+    IoError(#[from] std::io::Error),
+    
+    #[error("Parsing error: {0}")]
+    ParseError(String),
+    
+    #[error("Configuration error: {0}")]
+    ConfigurationError(String),
+}
+
+/// Auto-repair capability for common violations
+impl IntegrityValidator {
+    /// Attempt to automatically fix violations where possible
+    pub fn auto_repair(&self, violations: &[IntegrityViolation]) -> Result<RepairResult, IntegrityError> {
+        let mut repaired = Vec::new();
+        let mut failed = Vec::new();
+        
+        for violation in violations {
+            match self.attempt_repair(violation) {
+                Ok(()) => repaired.push(violation.clone()),
+                Err(e) => failed.push((violation.clone(), e)),
+            }
+        }
+        
+        Ok(RepairResult { repaired, failed })
+    }
+    
+    /// Attempt to repair a specific violation
+    fn attempt_repair(&self, violation: &IntegrityViolation) -> Result<(), IntegrityError> {
+        match violation.category {
+            ViolationCategory::ConfigurationBypass => {
+                self.repair_configuration_bypass(violation)
+            },
+            ViolationCategory::DeprecatedUsage => {
+                self.repair_deprecated_usage(violation)
+            },
+            // Only safe, automated repairs
+            _ => Err(IntegrityError::ConfigurationError(
+                "Manual repair required for this violation type".to_string()
+            ))
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct RepairResult {
+    pub repaired: Vec<IntegrityViolation>,
+    pub failed: Vec<(IntegrityViolation, IntegrityError)>,
+}
+```
+
+## 🔧 CLI Integration
+
+### Integrity Commands
+
+```rust
+// Add to rustelo CLI in main.rs
+
+/// Framework integrity protection commands
+#[derive(Debug, Clap)]
+pub enum IntegrityCommand {
+    /// Validate framework integrity
+    Validate {
+        /// Path to implementation root
+        #[clap(long, default_value = ".")]
+        path: String,
+        
+        /// Output format (human, json, junit)
+        #[clap(long, default_value = "human")]
+        format: String,
+        
+        /// Fail on warnings
+        #[clap(long)]
+        strict: bool,
+        
+        /// Generate detailed report
+        #[clap(long)]
+        detailed: bool,
+    },
+    
+    /// Auto-repair violations where possible
+    Repair {
+        /// Path to implementation root  
+        #[clap(long, default_value = ".")]
+        path: String,
+        
+        /// Dry run (don't make changes)
+        #[clap(long)]
+        dry_run: bool,
+        
+        /// Only repair specific categories
+        #[clap(long)]
+        categories: Option<Vec<String>>,
+    },
+    
+    /// Show framework compatibility information
+    Compatibility {
+        /// Framework version to check against
+        #[clap(long)]
+        target_version: Option<String>,
+    },
+    
+    /// Initialize integrity protection for new implementation
+    Init {
+        /// Path to implementation root
+        #[clap(long, default_value = ".")]
+        path: String,
+        
+        /// Enable continuous validation
+        #[clap(long)]
+        continuous: bool,
+    },
+}
+
+async fn handle_integrity_command(cmd: IntegrityCommand) -> Result<(), CliError> {
+    match cmd {
+        IntegrityCommand::Validate { path, format, strict, detailed } => {
+            validate_integrity(&path, &format, strict, detailed).await
+        },
+        IntegrityCommand::Repair { path, dry_run, categories } => {
+            repair_violations(&path, dry_run, categories).await
+        },
+        IntegrityCommand::Compatibility { target_version } => {
+            check_compatibility(target_version.as_deref()).await
+        },
+        IntegrityCommand::Init { path, continuous } => {
+            init_integrity_protection(&path, continuous).await
+        },
+    }
+}
+
+async fn validate_integrity(
+    path: &str, 
+    format: &str, 
+    strict: bool, 
+    detailed: bool
+) -> Result<(), CliError> {
+    let framework_root = detect_framework_root()?;
+    let implementation_root = PathBuf::from(path);
+    
+    let validator = IntegrityValidator::new(&framework_root, &implementation_root)?;
+    let result = validator.validate()?;
+    
+    match format {
+        "json" => println!("{}", serde_json::to_string_pretty(&result)?),
+        "junit" => output_junit_format(&result)?,
+        _ => output_human_format(&result, detailed)?,
+    }
+    
+    if !result.passed || (strict && !result.warnings.is_empty()) {
+        std::process::exit(1);
+    }
+    
+    Ok(())
+}
+```
+
+## 🚨 Continuous Validation
+
+### Pre-commit Hook Integration
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit - Framework integrity validation
+
+echo "🛡️ Running framework integrity validation..."
+
+# Run integrity check
+if ! cargo rustelo integrity validate --strict; then
+    echo "❌ Framework integrity validation failed!"
+    echo "Run 'cargo rustelo integrity repair' to attempt automatic fixes"
+    echo "Or 'cargo rustelo integrity validate --detailed' for more information"
+    exit 1
+fi
+
+echo "✅ Framework integrity validation passed"
+```
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/integrity.yml
+name: Framework Integrity Check
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main, develop]
+
+jobs:
+  integrity:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          
+      - name: Install Rustelo CLI
+        run: cargo install --path crates/templates/rustelo-cli
+        
+      - name: Validate Framework Integrity
+        run: |
+          cargo rustelo integrity validate \
+            --format junit \
+            --strict \
+            --detailed > integrity-results.xml
+            
+      - name: Upload Integrity Report
+        uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: integrity-report
+          path: integrity-results.xml
+          
+      - name: Comment PR with Integrity Issues
+        if: failure() && github.event_name == 'pull_request'
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const fs = require('fs');
+            const results = fs.readFileSync('integrity-results.xml', 'utf8');
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `## ⚠️ Framework Integrity Issues\n\`\`\`\n${results}\n\`\`\``
+            });
+```
+
+## 📋 Framework Manifest
+
+### Core Framework Manifest
+
+```toml
+# FRAMEWORK_MANIFEST.toml - Defines framework boundaries and rules
+
+[framework]
+name = "rustelo"
+version = "0.1.0"
+integrity_version = "1.0"
+compatibility_level = "stable"
+
+# Paths that are protected from direct modification
+[[protected_paths]]
+path = "crates/foundation/crates/core-lib/src/lib.rs"
+reason = "Core framework interface"
+alternatives = ["Implement traits in your own crates"]
+
+[[protected_paths]] 
+path = "crates/foundation/crates/core-lib/src/routing/mod.rs"
+reason = "Core routing system"
+alternatives = ["Use route configuration in config/routes/"]
+
+[[protected_paths]]
+path = "templates/shared/"
+reason = "Shared template system"
+alternatives = ["Create local overrides in config/local/"]
+
+# Required trait implementations for compatibility
+[[required_traits]]
+trait_name = "ContentLoader"
+implementation_path = "src/content/loader.rs"
+required_methods = ["load", "validate", "cache_key"]
+compatibility_version = "1.0"
+
+[[required_traits]]
+trait_name = "RouteHandler"
+implementation_path = "src/routing/handlers.rs"  
+required_methods = ["handle_request", "supports_route"]
+compatibility_version = "1.0"
+
+# Safe extension points
+[[extension_points]]
+name = "custom_components"
+location = "src/components/custom/"
+allowed_modifications = ["create", "modify", "delete"]
+description = "Custom UI components"
+
+[[extension_points]]
+name = "content_processors"
+location = "src/content/processors/"
+allowed_modifications = ["create", "extend"]
+description = "Custom content processing logic"
+
+[[extension_points]]
+name = "configuration_overrides"
+location = "config/local/"
+allowed_modifications = ["create", "modify"]
+description = "Local configuration overrides"
+
+# Patterns that break framework compatibility
+[[forbidden_patterns]]
+pattern = 'hardcoded_routes = ["/', '"/api", "/admin"]'
+reason = "Hardcoded routes bypass configuration system"
+suggested_alternative = "Use route configuration in config/routes/*.toml"
+severity = "Critical"
+
+[[forbidden_patterns]]
+pattern = "pub mod core_lib {"
+reason = "Direct framework core modification"
+suggested_alternative = "Implement traits and use extension points"  
+severity = "Critical"
+
+[[forbidden_patterns]]
+pattern = "unsafe {"
+reason = "Unsafe code bypasses framework safety guarantees"
+suggested_alternative = "Use safe alternatives or request framework extension"
+severity = "High"
+
+[[forbidden_patterns]]
+pattern = 'include_str!("../../'
+reason = "Relative includes bypass asset system"
+suggested_alternative = "Use framework asset loading APIs"
+severity = "Medium"
+
+# Update compatibility information
+[update_compatibility]
+breaking_changes_policy = "semantic_versioning"
+migration_assistance = true
+automated_migration = ["configuration", "dependencies"]
+manual_migration = ["trait_signatures", "api_changes"]
+
+[validation_rules]
+max_compatibility_score = 0.8  # Minimum score for updates
+critical_violations_allowed = 0
+high_violations_threshold = 3
+medium_violations_threshold = 10
+```
+
+## 🔄 Update Safety System
+
+### Safe Update Process
+
+```rust
+/// Safe framework update system
+pub struct UpdateManager {
+    current_version: String,
+    target_version: String,
+    integrity_validator: IntegrityValidator,
+}
+
+impl UpdateManager {
+    /// Check if update is safe to apply
+    pub fn can_update_safely(&self) -> Result<UpdateSafetyReport, UpdateError> {
+        let validation_result = self.integrity_validator.validate()?;
+        
+        if !validation_result.passed {
+            return Ok(UpdateSafetyReport {
+                safe: false,
+                reason: "Integrity violations must be resolved first".to_string(),
+                violations: validation_result.violations,
+                required_actions: self.generate_required_actions(&validation_result.violations),
+            });
+        }
+        
+        let compatibility = self.check_version_compatibility()?;
+        
+        Ok(UpdateSafetyReport {
+            safe: compatibility.compatible,
+            reason: compatibility.reason,
+            violations: Vec::new(),
+            required_actions: compatibility.migration_steps,
+        })
+    }
+    
+    /// Perform safe update with validation
+    pub async fn update_safely(&mut self) -> Result<UpdateResult, UpdateError> {
+        let safety_report = self.can_update_safely()?;
+        
+        if !safety_report.safe {
+            return Err(UpdateError::UnsafeUpdate {
+                reason: safety_report.reason,
+                required_actions: safety_report.required_actions,
+            });
+        }
+        
+        // Create backup before update
+        self.create_backup().await?;
+        
+        // Apply update
+        let result = self.apply_update().await?;
+        
+        // Validate post-update
+        let post_validation = self.integrity_validator.validate()?;
+        
+        if !post_validation.passed {
+            // Rollback on validation failure
+            self.rollback().await?;
+            return Err(UpdateError::PostUpdateValidationFailed {
+                violations: post_validation.violations,
+            });
+        }
+        
+        Ok(result)
+    }
+}
+```
+
+## 📊 Benefits
+
+### For Implementation Maintainers
+- **Safe updates**: Never worry about breaking changes
+- **Clear guidance**: Know exactly what can be customized safely
+- **Automated validation**: Catch issues before they become problems
+- **Easy troubleshooting**: Clear error messages with suggested fixes
+
+### For Framework Maintainers  
+- **Update confidence**: Know implementations won't break
+- **Reduced support**: Fewer compatibility issues
+- **Architecture enforcement**: Ensure design principles are followed
+- **Quality control**: Maintain high standards across ecosystem
+
+### For Teams
+- **Collaboration safety**: Multiple developers can work without breaking compatibility
+- **CI/CD integration**: Automated checks in development pipeline  
+- **Knowledge sharing**: Clear documentation of what's allowed/forbidden
+- **Risk mitigation**: Prevent costly refactoring due to incompatible changes
+
+This comprehensive framework integrity protection system ensures that Rustelo implementations remain updateable and compatible with the core framework while providing maximum flexibility for customization through approved extension points.

docs/architecture/layered-override-system.md

@@ -0,0 +1,351 @@
+# Rustelo Layered Override System
+
+## 🎯 Architecture Overview
+
+The layered override system enables customization at multiple levels while maintaining framework integrity and update safety. This system follows a clear precedence hierarchy:
+
+**Precedence Order**: `Local > Feature > Template > Framework`
+
+## 🏗️ Layer Definitions
+
+### 1. Framework Layer (Bottom - Never Modified)
+- **Location**: Framework crates in dependencies
+- **Content**: Core rustelo functionality
+- **Modification**: ❌ Never modified directly
+- **Updates**: Automatic via `cargo rustelo update`
+
+### 2. Template Layer (Foundation)
+- **Location**: Project templates from `/rustelo/templates/`
+- **Content**: Default project structure and configurations
+- **Modification**: ❌ Not modified directly in projects
+- **Updates**: Synced via `cargo rustelo sync templates`
+
+### 3. Feature Layer (Additive)
+- **Location**: Feature-specific additions from `/rustelo/features/*/templates/`
+- **Content**: Feature configurations, dependencies, tooling
+- **Modification**: ✅ Can be overridden by local layer
+- **Updates**: Managed via `cargo rustelo add/remove <feature>`
+
+### 4. Local Layer (Top - Full Control)
+- **Location**: Project-specific files and customizations
+- **Content**: Local customizations, overrides, project-specific code
+- **Modification**: ✅ Full control by developers
+- **Updates**: Always preserved during framework updates
+
+## 🔧 Override Resolution Process
+
+### Configuration Files (Cargo.toml, justfile, package.json)
+
+```
+Resolution Order:
+1. Check for local override: `config/local/Cargo.toml`
+2. Check for feature configs: `config/features/*/Cargo.toml`
+3. Check template default: `config/templates/Cargo.toml`
+4. Fall back to framework defaults
+```
+
+**Merge Strategy**: Hierarchical merge with higher layers taking precedence
+
+### Component Overrides (Pages, Components)
+
+```
+Resolution Order:
+1. Local components: `src/components/local/`
+2. Feature components: `src/components/features/*/`
+3. Template components: `src/components/templates/`
+4. Framework components: Framework crates
+```
+
+**Selection Strategy**: First found wins (no merging for components)
+
+### Route Definitions
+
+```
+Resolution Order:
+1. Local routes: `config/routes/local/`
+2. Feature routes: `config/routes/features/*/`
+3. Template routes: `config/routes/templates/`
+4. Framework routes: Generated defaults
+```
+
+**Merge Strategy**: Route sets are merged with local routes overriding conflicts
+
+### Styling (CSS, UnoCSS)
+
+```
+Resolution Order:
+1. Local styles: `styles/local/`
+2. Feature styles: `styles/features/*/`
+3. Template styles: `styles/templates/`
+4. Framework styles: Default framework styles
+```
+
+**Merge Strategy**: CSS cascade with local styles having highest specificity
+
+## 📁 Directory Structure
+
+```
+my-rustelo-project/
+├── config/
+│   ├── local/              # Local overrides (highest precedence)
+│   │   ├── Cargo.toml
+│   │   ├── justfile
+│   │   └── app.toml
+│   ├── features/           # Feature-specific configs
+│   │   ├── analytics/
+│   │   ├── smart-build/
+│   │   └── debugging-tools/
+│   └── templates/          # Template defaults (lowest precedence)
+├── src/
+│   ├── components/
+│   │   ├── local/          # Local component overrides
+│   │   ├── features/       # Feature components
+│   │   └── templates/      # Template components
+│   └── pages/
+│       ├── local/          # Local page overrides
+│       ├── features/       # Feature pages
+│       └── templates/      # Template pages
+├── routes/
+│   ├── local/              # Local route definitions
+│   ├── features/           # Feature routes
+│   └── templates/          # Template routes
+├── styles/
+│   ├── local/              # Local styling
+│   ├── features/           # Feature styles
+│   └── templates/          # Template styles
+└── scripts/
+    ├── local/              # Local scripts
+    ├── features/           # Feature scripts
+    └── templates/          # Template scripts
+```
+
+## ⚙️ Implementation
+
+### Configuration Resolution Engine
+
+```rust
+pub struct LayeredConfig {
+    layers: Vec<ConfigLayer>,
+}
+
+#[derive(Debug, Clone)]
+pub enum ConfigLayer {
+    Local(PathBuf),
+    Feature(String, PathBuf),
+    Template(PathBuf),
+    Framework,
+}
+
+impl LayeredConfig {
+    pub fn resolve<T>(&self, config_name: &str) -> Result<T, ConfigError> 
+    where 
+        T: DeserializeOwned + Merge
+    {
+        let mut result = T::default();
+        
+        // Apply layers from lowest to highest precedence
+        for layer in &self.layers {
+            if let Some(config) = self.load_config_from_layer(layer, config_name)? {
+                result.merge(config);
+            }
+        }
+        
+        Ok(result)
+    }
+}
+```
+
+### Component Resolution Engine
+
+```rust
+pub struct LayeredComponents {
+    component_dirs: Vec<ComponentDir>,
+}
+
+#[derive(Debug, Clone)]
+pub enum ComponentDir {
+    Local(PathBuf),
+    Feature(String, PathBuf),
+    Template(PathBuf),
+    Framework,
+}
+
+impl LayeredComponents {
+    pub fn find_component(&self, name: &str) -> Option<PathBuf> {
+        // Search from highest to lowest precedence
+        for dir in &self.component_dirs {
+            if let Some(path) = self.search_component_in_dir(dir, name) {
+                return Some(path);
+            }
+        }
+        None
+    }
+}
+```
+
+## 🚀 CLI Integration
+
+### Automatic Layer Setup
+
+```bash
+# Create layered structure when adding features
+cargo rustelo add analytics
+# Creates: config/features/analytics/, src/components/features/analytics/, etc.
+
+# Create local override
+cargo rustelo override component Header
+# Creates: src/components/local/Header.rs (overrides template/feature version)
+
+# Create local config override  
+cargo rustelo override config Cargo.toml
+# Creates: config/local/Cargo.toml (merges with other layers)
+```
+
+### Override Management
+
+```bash
+# List all overrides
+cargo rustelo list-overrides
+
+# Show override hierarchy for specific item
+cargo rustelo trace component Header
+# Output:
+# Header component resolution:
+# ✅ src/components/local/Header.rs (USED)
+# 🔸 src/components/features/analytics/Header.rs 
+# 🔸 src/components/templates/Header.rs
+
+# Remove local override (fall back to next layer)
+cargo rustelo remove-override component Header
+```
+
+## 🛡️ Update Safety
+
+### Framework Updates
+When running `cargo rustelo update`:
+
+1. **Framework crates** are updated to latest versions
+2. **Template defaults** are refreshed (but not applied)
+3. **Feature configs** are updated if compatible
+4. **Local overrides** are never modified
+5. **Conflict detection** warns of incompatibilities
+
+### Feature Updates
+When running `cargo rustelo add/remove <feature>`:
+
+1. **Feature layer** is added/removed
+2. **Local overrides** take precedence over new feature configs
+3. **Dependency conflicts** are resolved in favor of local choices
+4. **Migration warnings** provided for breaking changes
+
+## 🎨 Configuration Merging Examples
+
+### Cargo.toml Merging
+
+**Template Layer**:
+```toml
+[dependencies]
+leptos = "0.6"
+serde = "1.0"
+```
+
+**Feature Layer (analytics)**:
+```toml
+[dependencies] 
+prometheus = "0.13"
+chrono = "0.4"
+```
+
+**Local Layer**:
+```toml
+[dependencies]
+leptos = "0.7"  # Override template version
+anyhow = "1.0"  # Add local dependency
+```
+
+**Final Result**:
+```toml
+[dependencies]
+leptos = "0.7"        # Local override
+serde = "1.0"         # From template
+prometheus = "0.13"   # From analytics feature
+chrono = "0.4"        # From analytics feature  
+anyhow = "1.0"        # Local addition
+```
+
+### UnoCSS Configuration Merging
+
+**Template Layer**:
+```typescript
+export default {
+  theme: {
+    colors: {
+      primary: '#3b82f6',
+    }
+  }
+}
+```
+
+**Feature Layer (analytics)**:
+```typescript
+export default {
+  theme: {
+    colors: {
+      analytics: '#10b981',
+    }
+  },
+  shortcuts: {
+    'metric-card': 'bg-white shadow-md rounded-lg p-4',
+  }
+}
+```
+
+**Local Layer**:
+```typescript
+export default {
+  theme: {
+    colors: {
+      primary: '#ef4444',  // Override template primary
+      brand: '#8b5cf6',    // Add local color
+    }
+  }
+}
+```
+
+**Final Result**:
+```typescript
+export default {
+  theme: {
+    colors: {
+      primary: '#ef4444',     // Local override
+      analytics: '#10b981',   // From analytics feature
+      brand: '#8b5cf6',       // Local addition
+    }
+  },
+  shortcuts: {
+    'metric-card': 'bg-white shadow-md rounded-lg p-4',  // From analytics
+  }
+}
+```
+
+## 📋 Benefits
+
+### For Developers
+- **Full customization** without losing update capability
+- **Clear precedence** - always know which config wins
+- **Safe experimentation** - local changes never affect framework
+- **Easy rollback** - remove local override to revert to defaults
+
+### for Framework Maintainers
+- **Update safety** - never break user customizations
+- **Feature composability** - features don't conflict with each other
+- **Clear boundaries** - framework, template, feature, and local concerns separated
+- **Debugging support** - trace resolution path for any configuration
+
+### For Teams
+- **Consistent structure** - all projects follow same layered approach
+- **Shared overrides** - commit local layer for team-wide customizations
+- **Feature experimentation** - test features without permanent changes
+- **Migration safety** - gradual migration between framework versions
+
+This layered override system ensures that Rustelo provides maximum flexibility while maintaining the reliability and update safety that production applications require.

docs/architecture/overview.md

@@ -0,0 +1,159 @@
+# Rustelo Feature-Based Architecture Overview
+
+## Architecture Vision
+
+Rustelo has been transformed from a basic framework into a modular, feature-composable system that preserves all advanced functionality from p-jpl-website while enabling clean composition and reuse.
+
+## Core Structure
+
+```
+rustelo/
+├── framework/           # Core framework crates
+│   └── crates/
+│       ├── rustelo-core/
+│       ├── rustelo-web/
+│       ├── rustelo-auth/
+│       ├── rustelo-content/
+│       └── rustelo-cli/     # Enhanced CLI with feature management
+├── foundation/          # Advanced blueprint from p-jpl-website
+│   └── crates/
+│       ├── client/          # Advanced Leptos client
+│       ├── server/          # Advanced Axum server
+│       ├── core-lib/        # Sophisticated shared library
+│       ├── core-types/      # Enhanced type system
+│       ├── components/      # Rich UI component library
+│       ├── pages/           # Advanced page generation
+│       ├── tools/           # Development tools and analytics
+│       └── utils/           # Utility functions
+├── features/            # Modular features
+│   ├── analytics/           # Comprehensive analytics system
+│   ├── smart-build/         # Incremental build system
+│   ├── debugging-tools/     # Enhanced debugging capabilities
+│   └── ui-components/       # Reusable Leptos components
+├── registry/            # Central configuration
+│   ├── dependencies.toml   # Centralized dependency versions
+│   └── features.toml       # Feature registry and metadata
+└── templates/           # Project scaffolding templates
+```
+
+## Key Architectural Principles
+
+### 1. Language Agnostic Design
+- No hardcoded languages in the framework
+- Dynamic language discovery from configuration
+- i18n integration with Fluent files
+- Language-specific routing without code changes
+
+### 2. Configuration-Driven Architecture
+- All paths configurable via environment variables
+- Route definitions in TOML files, not code
+- Content types via `content-kinds.toml`
+- Feature composition through configuration
+
+### 3. Modular Design
+- Features are self-contained and composable
+- Clean interfaces between components
+- Dependency injection patterns
+- Zero breaking changes policy
+
+### 4. Dependency Priority System
+- p-jpl-website dependencies take priority
+- Registry-based version management
+- Conflict detection and resolution
+- Workspace dependency coordination
+
+## Integration Levels
+
+The system provides integration at all stack levels:
+
+### 1. Dependencies
+- **Cargo.toml**: Workspace dependencies and external crates
+- **package.json**: Node.js dependencies for tooling
+- **Registry**: Centralized version management
+
+### 2. Environment
+- **.env**: Environment variables and configuration
+- **Secrets**: Secure handling of sensitive values
+- **Defaults**: Sensible default values
+
+### 3. Configuration
+- **TOML/JSON**: Intelligent config file merging
+- **Override**: Feature-specific configuration
+- **Validation**: Configuration integrity checks
+
+### 4. Resources
+- **Public**: Static assets (JS, CSS, images)
+- **Site**: Content and documentation files
+- **i18n**: Translation files (Fluent .ftl)
+
+### 5. Styling
+- **UnoCSS**: Atomic CSS with feature presets
+- **Themes**: Feature-specific theme extensions
+- **Components**: Styled component libraries
+
+### 6. Infrastructure
+- **Docker**: Service composition and deployment
+- **CI/CD**: Automated testing and deployment
+- **Monitoring**: Observability and alerting
+
+### 7. Development
+- **Scripts**: Nushell automation scripts
+- **Just**: Task runner integration
+- **Git**: Hooks and workflow automation
+
+## Feature Lifecycle
+
+```
+Discovery → Installation → Configuration → Integration → Usage → Removal
+```
+
+### Discovery
+- Browse available features in registry
+- Check feature compatibility
+- Review feature documentation
+
+### Installation
+- Dependency resolution and conflict detection
+- Resource copying and integration
+- Configuration merging and validation
+
+### Configuration
+- Environment variable setup
+- Feature-specific configuration
+- Integration validation
+
+### Integration
+- All stack levels integrated automatically
+- Dependency injection and wiring
+- Testing and validation
+
+### Usage
+- Feature APIs and functionality available
+- Documentation and examples provided
+- Monitoring and analytics enabled
+
+### Removal
+- Clean removal of all feature artifacts
+- Dependency cleanup and validation
+- Configuration restoration
+
+## Migration Strategy
+
+The architecture preserves backward compatibility while enabling gradual migration:
+
+1. **Existing rustelo users**: Continue using basic functionality
+2. **p-jpl-website users**: Full feature set available as composable features
+3. **New users**: Start with foundation + selected features
+4. **Advanced users**: Create custom features and compositions
+
+## Success Metrics
+
+✅ **Achieved Goals:**
+- All p-jpl-website functionality preserved as features
+- Zero hardcoded dependencies or paths
+- Clean feature addition/removal
+- No breaking changes for existing users
+- Single command project creation
+- Complete resource integration
+- Feature composition without conflicts
+- Clean separation of concerns

docs/architecture/template-architecture.md

@@ -0,0 +1,155 @@
+# Rustelo Template Architecture
+
+## 🏗️ Unified Template System
+
+After consolidating the template functionality, Rustelo now uses a **layered template architecture** that serves different phases of development:
+
+## Template Hierarchy
+
+### 1. **Project Templates** (`/rustelo/templates/`)
+**Purpose**: Complete project scaffolding with full tooling setup
+- **When**: Initial project creation (`cargo rustelo new`)
+- **Features**: Variable substitution, workspace configuration, complete tooling
+- **Coverage**: Configs, scripts, docs, Docker, content, styling, build automation
+
+**Available Templates**:
+- `basic` - Standard web application (most common)
+- `cms` - Content management focused
+- `minimal` - Lightweight for prototypes
+- `enterprise` - Advanced features for large deployments
+- `saas` - Software-as-a-Service with subscriptions
+- `ai-powered` - AI/ML integration
+- `ecommerce` - Online store functionality
+
+### 2. **Crate Templates** (`/rustelo/crates/templates/`)
+**Purpose**: Deep customization via trait-based architecture
+- **When**: Advanced customization needs (`cargo rustelo clone`)
+- **Features**: Trait implementations, local dependencies, standalone operation
+- **Coverage**: Individual crate functionality with full customization capability
+
+**Available Templates**:
+- `client-template` - WASM client with trait-based routing
+- `server-template` - Axum server with comprehensive features
+- `core-lib-template` - Core business logic implementations
+- `rustelo-cli` - CLI tool template for project management
+
+### 3. **Feature Templates** (`/rustelo/features/*/templates/`)
+**Purpose**: Modular feature configuration
+- **When**: Adding/removing features (`cargo rustelo add/remove`)
+- **Features**: Feature-specific configs, dependencies, tooling additions
+- **Coverage**: Analytics configs, build optimizations, specialized tooling
+
+## 🔄 Template Integration Workflow
+
+### Phase 1: Project Creation
+```bash
+cargo rustelo new my-project --template basic --features auth,content
+```
+**Result**: Complete project with:
+- Workspace structure from project template
+- Feature-specific configurations from feature templates
+- All tooling (just, CSS, package.json, scripts) properly configured
+
+### Phase 2: Crate Customization (Optional)
+```bash
+cargo rustelo clone client --target local-crates
+```
+**Result**: Local crate with:
+- Trait-based implementations you can modify
+- Direct dependencies for standalone development
+- Full control over routing, rendering, content loading
+
+### Phase 3: Feature Management
+```bash
+cargo rustelo add analytics    # Adds feature templates + dependencies
+cargo rustelo remove auth      # Removes cleanly without breaking
+cargo rustelo update          # Updates framework, preserves customizations
+```
+
+## 🎯 Template Composition Strategy
+
+### Variable Substitution System
+**Project Templates** support dynamic configuration:
+```toml
+name = "{{project_name_snake}}-client"
+authors = [{{authors}}]
+features = {{selected_features}}
+```
+
+### Layered Override System
+**Precedence Order**: Local > Feature > Template > Framework
+
+1. **Framework Layer**: Core rustelo crates (never modified)
+2. **Template Layer**: Default implementations from templates
+3. **Feature Layer**: Feature-specific additions/configurations
+4. **Local Layer**: Project-specific overrides and customizations
+
+### Dependency Resolution
+**Project Templates**: Use workspace dependencies
+```toml
+rustelo-web = { workspace = true }
+```
+
+**Crate Templates**: Use direct dependencies for customization
+```toml
+rustelo-routing-traits = { path = "../../traits/routing-traits" }
+```
+
+## 🧩 Template System Benefits
+
+### For New Projects
+- **Single Command**: Complete setup with `cargo rustelo new`
+- **Full Tooling**: Just, CSS, configs, scripts all working
+- **Feature Selection**: Choose capabilities during creation
+
+### For Customization
+- **Trait-Based**: Modify behavior without forking framework
+- **Granular Control**: Customize routing, rendering, content loading
+- **Update Safety**: Framework updates don't break customizations
+
+### for Framework Integrity
+- **No Forking**: Framework stays in dependencies
+- **Validation**: CLI ensures customizations don't break contracts
+- **Upgrade Path**: Clear migration between framework versions
+
+## 🔧 Template Development Guidelines
+
+### Adding Project Templates
+1. Create directory in `/rustelo/templates/`
+2. Add configuration to `templates.json`
+3. Include shared components via `assets.includes`
+4. Support variable substitution for dynamic values
+
+### Adding Crate Templates
+1. Create directory in `/rustelo/crates/templates/`
+2. Include trait dependencies and implementations
+3. Support standalone operation with direct dependencies
+4. Provide customization examples in README
+
+### Adding Feature Templates
+1. Create in `/rustelo/features/{feature}/templates/`
+2. Include feature-specific configurations
+3. Update CLI to handle feature addition/removal
+4. Document feature interactions and dependencies
+
+## 🚀 Migration Path
+
+### From Old Foundation Templates
+Foundation templates have been **consolidated into the unified system**:
+- Build functionality moved to crate templates
+- Template variety preserved in project templates
+- CLI integration enhanced for seamless workflows
+
+### For Existing Projects
+```bash
+# Check current project structure
+cargo rustelo status
+
+# Migrate to new template system
+cargo rustelo migrate
+
+# Optionally clone crates for customization
+cargo rustelo clone all --target local-crates
+```
+
+This unified architecture provides the flexibility for both rapid prototyping and deep customization while maintaining framework integrity and upgrade safety.

docs/examples/README.md

@@ -0,0 +1,219 @@
+# Rustelo Usage Examples
+
+## Quick Start
+
+### Creating a New Project with Features
+
+```bash
+# Create new project directory
+mkdir my-rustelo-app && cd my-rustelo-app
+
+# Copy foundation structure
+cp -r /path/to/rustelo/foundation/* .
+
+# Add desired features
+cargo rustelo features add analytics
+cargo rustelo features add smart-build
+
+# Check status
+cargo rustelo features status
+```
+
+### Available Feature Combinations
+
+#### Minimal Setup
+```bash
+# Just the foundation - basic Leptos + Axum
+# No additional features needed
+```
+
+#### Analytics-Enabled
+```bash
+cargo rustelo features add analytics
+# Provides: navigation tracking, server monitoring, browser analytics
+```
+
+#### Performance-Optimized
+```bash
+cargo rustelo features add smart-build
+cargo rustelo features add analytics
+# Provides: fast builds + performance monitoring
+```
+
+#### Full-Stack Development
+```bash
+cargo rustelo features add analytics
+cargo rustelo features add smart-build
+cargo rustelo features add debugging-tools
+cargo rustelo features add ui-components
+# Provides: complete development environment
+```
+
+## Real-World Examples
+
+### Blog with Analytics
+
+```bash
+# Setup
+mkdir my-blog && cd my-blog
+cp -r /path/to/rustelo/foundation/* .
+
+# Add analytics for visitor tracking
+cargo rustelo features add analytics
+
+# Configure analytics
+echo 'ANALYTICS_ENABLED=true' >> .env
+echo 'ANALYTICS_LOG_PATH=logs/blog-analytics' >> .env
+
+# Build and run
+cargo leptos build
+cargo leptos serve
+```
+
+### E-commerce with Performance Monitoring
+
+```bash
+# Setup high-performance e-commerce site
+mkdir my-shop && cd my-shop
+cp -r /path/to/rustelo/foundation/* .
+
+# Add performance features
+cargo rustelo features add smart-build
+cargo rustelo features add analytics
+
+# Configure for production
+echo 'SMART_BUILD_PARALLEL_JOBS=8' >> .env
+echo 'ANALYTICS_API_KEY=your-api-key' >> .env
+
+# Fast development builds
+cargo leptos watch  # Uses smart-build caching
+```
+
+### Development Team Setup
+
+```bash
+# Full development environment
+mkdir team-project && cd team-project
+cp -r /path/to/rustelo/foundation/* .
+
+# Add all development features
+cargo rustelo features add analytics
+cargo rustelo features add smart-build
+cargo rustelo features add debugging-tools
+
+# Team-specific configuration
+echo 'SMART_BUILD_CACHE_DIR=.cache/team-build' >> .env
+echo 'ANALYTICS_LOG_PATH=logs/team-analytics' >> .env
+
+# Enhanced debugging available
+# Use browser log analysis, server monitoring, etc.
+```
+
+## Feature-Specific Examples
+
+### Analytics Feature
+
+```bash
+# Add analytics
+cargo rustelo features add analytics
+
+# Available commands:
+# - Navigation tracking analysis
+# - Server log monitoring
+# - Browser error tracking
+# - Performance reporting
+
+# Example usage:
+cargo run --bin analytics -- search --errors-only --hours 1
+cargo run --bin analytics -- dashboard --refresh 30
+cargo run --bin analytics -- report --type summary
+```
+
+### Smart Build Feature
+
+```bash
+# Add smart build
+cargo rustelo features add smart-build
+
+# Features:
+# - Incremental builds with caching
+# - Build performance optimization
+# - Cache management tools
+
+# Configuration:
+echo 'SMART_BUILD_CACHE_DIR=.cache/builds' >> .env
+echo 'SMART_BUILD_PARALLEL_JOBS=auto' >> .env
+
+# Enhanced build performance automatically
+cargo leptos build  # Uses smart caching
+```
+
+## Custom Feature Development
+
+### Creating a Custom Feature
+
+```bash
+# Create feature structure
+mkdir -p features/my-custom-feature/templates
+mkdir -p features/my-custom-feature/assets
+mkdir -p features/my-custom-feature/scripts
+
+# Create feature manifest
+cat > features/my-custom-feature/feature.toml << 'EOF'
+[feature]
+name = "my-custom-feature"
+version = "0.1.0"
+description = "My custom functionality"
+
+[dependencies]
+workspace = ["serde", "tokio"]
+external = []
+
+[[environment.variables]]
+name = "MY_FEATURE_ENABLED"
+default = "true"
+required = false
+EOF
+
+# Register in features registry
+echo '[features.my-custom-feature]' >> registry/features.toml
+echo 'description = "My custom functionality"' >> registry/features.toml
+echo 'source = "local"' >> registry/features.toml
+echo 'status = "available"' >> registry/features.toml
+
+# Install custom feature
+cargo rustelo features add my-custom-feature
+```
+
+## Troubleshooting
+
+### Common Issues
+
+```bash
+# Feature not found
+cargo rustelo features list  # Check available features
+
+# Dependency conflicts
+cargo rustelo features status  # Check for conflicts
+
+# Integration issues
+cargo rustelo features sync --force  # Force resync
+
+# Clean install
+cargo rustelo features remove feature-name --clean-deps
+cargo rustelo features add feature-name --force
+```
+
+### Getting Help
+
+```bash
+# CLI help
+cargo rustelo --help
+cargo rustelo features --help
+
+# Feature documentation
+cargo rustelo features explain analytics
+
+# Status check
+cargo rustelo features status
+```

docs/features/README.md

@@ -0,0 +1,99 @@
+# Rustelo Features Documentation
+
+## Available Features
+
+### Analytics
+Comprehensive analytics system with navigation tracking, server monitoring, and browser analytics.
+
+**Installation:**
+```bash
+cargo rustelo features add analytics
+```
+
+**Provides:**
+- Navigation tracking with cache performance analysis
+- Server log analysis and panic detection
+- Browser console error tracking
+- Real-time monitoring dashboard
+- CLI tools for analysis and reporting
+
+**Configuration:** `config/analytics.toml`
+
+### Smart Build
+Incremental build system with intelligent caching and performance optimization.
+
+**Installation:**
+```bash
+cargo rustelo features add smart-build
+```
+
+**Provides:**
+- Multi-layer cache system (L1/L2/L3)
+- Incremental builds with change detection
+- Build performance optimization
+- Cache management and cleanup tools
+
+**Configuration:** `config/smart-build.toml`
+
+## Feature Development
+
+### Creating a New Feature
+
+1. Create feature directory:
+```bash
+mkdir features/my-feature
+```
+
+2. Create feature manifest:
+```toml
+# features/my-feature/feature.toml
+[feature]
+name = "my-feature"
+version = "0.1.0"
+description = "My custom feature"
+
+[dependencies]
+workspace = ["serde", "tokio"]
+external = []
+```
+
+3. Add to features registry:
+```toml
+# registry/features.toml
+[features.my-feature]
+description = "My custom feature"
+source = "local"
+status = "available"
+requires = []
+```
+
+### Feature Manifest Sections
+
+- **feature**: Basic metadata (name, version, description)
+- **dependencies**: Workspace and external dependencies
+- **environment**: Environment variables
+- **configuration**: Configuration files to install/merge
+- **resources**: Assets, content, and i18n files
+- **scripts**: Development and automation scripts
+- **node**: Node.js dependencies
+- **styles**: UnoCSS presets and styling
+- **docker**: Docker services and infrastructure
+- **just**: Just command modules
+
+### Feature Integration Levels
+
+1. **Dependencies**: Cargo and Node.js dependencies
+2. **Environment**: Environment variables and secrets
+3. **Configuration**: TOML/JSON config file merging
+4. **Resources**: Public assets, site content, i18n files
+5. **Styling**: UnoCSS preset and theme integration
+6. **Infrastructure**: Docker services and deployment configs
+7. **Development**: Scripts, Just commands, git hooks
+
+### Best Practices
+
+1. **Self-Contained**: Features should be independent and removable
+2. **Configurable**: Use environment variables for customization
+3. **Documented**: Include clear documentation and examples
+4. **Tested**: Provide tests for feature functionality
+5. **Versioned**: Use semantic versioning for feature updates

docs/guides/README.md

@@ -0,0 +1,15 @@
+# User Guides
+
+Step-by-step guides for using and developing with Rustelo.
+
+## Getting Started
+
+- [Quick Start Guide](quick-start-guide.md)
+- [Migration Guide](migration-guide.md)
+- [New Workflows](new-workflows.md)
+- [Tooling Integration](tooling-integration.md)
+
+## See Also
+
+- [Architecture](../architecture/) - Technical architecture
+- [How-To](../howto/) - Practical guides

docs/guides/migration-guide.md

@@ -0,0 +1,453 @@
+# Migration Guide - Unified Template Architecture
+
+## 🎯 Overview
+
+This guide helps you migrate from the previous template system to the new unified template architecture with layered override system. The new system provides:
+
+- **Unified template management** across all project types
+- **Layered override system** (Local > Feature > Template > Framework)  
+- **Framework integrity protection** for safe updates
+- **Feature-aware tooling** that adapts to enabled features
+- **Complete tooling integration** (just, CSS, configs, scripts)
+
+## 🚀 Quick Migration (5 Minutes)
+
+For most projects, migration is automatic:
+
+```bash
+# 1. Update to latest Rustelo version
+cargo install rustelo-cli --git https://github.com/your-org/rustelo
+
+# 2. Run automatic migration
+cargo rustelo migrate --from-legacy --backup
+
+# 3. Validate integrity
+cargo rustelo integrity validate --detailed
+
+# 4. Test your project
+just dev
+```
+
+## 📋 Migration Checklist
+
+### Before Migration
+- [ ] **Backup your project**: `cp -r my-project my-project-backup`
+- [ ] **Document customizations**: Note any custom templates or overrides
+- [ ] **Check git status**: Ensure working directory is clean
+- [ ] **Update Rustelo**: Install latest version with new CLI
+
+### During Migration  
+- [ ] **Run migration tool**: `cargo rustelo migrate --interactive`
+- [ ] **Review changes**: Check generated files and moved configurations
+- [ ] **Update dependencies**: Run `cargo update` if needed
+- [ ] **Test build**: Ensure project builds with `just build`
+
+### After Migration
+- [ ] **Validate integrity**: `cargo rustelo integrity validate`
+- [ ] **Test functionality**: Verify all features work as expected
+- [ ] **Update documentation**: Note any changes in project README
+- [ ] **Commit changes**: Commit migrated project to version control
+
+## 🔄 Specific Migration Scenarios
+
+### Scenario 1: Basic Project (No Custom Templates)
+
+**Before**: Standard Rustelo project with default templates
+**After**: Uses unified template system automatically
+
+```bash
+# Migration is automatic
+cargo rustelo migrate
+```
+
+**Changes**:
+- Templates now resolved through layered system
+- Configuration moved to `config/` directory structure
+- Tooling commands available through layered justfile
+
+### Scenario 2: Custom Templates in foundation/templates/
+
+**Before**: Custom templates in `crates/foundation/templates/`
+**After**: Templates moved to appropriate layer
+
+```bash
+# Interactive migration with template analysis
+cargo rustelo migrate --interactive --analyze-templates
+
+# Review suggested moves:
+# foundation/templates/custom.html → config/local/templates/custom.html
+# foundation/templates/build.rs → templates/shared/build.rs.template
+```
+
+**Manual Steps**:
+1. Review template analysis report
+2. Confirm template categorization (local vs shared)
+3. Update template references in your code
+
+### Scenario 3: Heavy Customization (Multiple Features)
+
+**Before**: Extensively customized project with multiple features
+**After**: Organized through layered override system
+
+```bash
+# Comprehensive migration with feature detection
+cargo rustelo migrate --comprehensive --detect-features
+
+# Features detected and organized:
+# analytics/ → config/features/analytics/
+# smart-build/ → config/features/smart-build/
+# custom-routes/ → config/local/routes/
+```
+
+**Post-Migration Structure**:
+```
+my-project/
+├── config/
+│   ├── local/          # Your local overrides (highest precedence)
+│   ├── features/       # Feature-specific configurations
+│   └── templates/      # Base template configurations
+├── src/                # Your application code
+└── scripts/            # Organized automation scripts
+```
+
+### Scenario 4: Team Project with Multiple Developers
+
+**Before**: Inconsistent template usage across team
+**After**: Standardized layered system
+
+```bash
+# Team lead runs migration
+cargo rustelo migrate --team-mode --create-shared-config
+
+# Generates shared configuration for team
+# Creates .rustelo/team-config.toml
+# Updates .gitignore for proper sharing
+```
+
+**Team Benefits**:
+- Consistent development environment
+- Safe customization without breaking updates
+- Clear separation of shared vs personal overrides
+
+## 🛠️ New Workflows
+
+### Development Workflow
+
+```bash
+# 1. Start development with all enabled features
+just dev-full
+
+# 2. Make changes to components/content/config
+# Changes are hot-reloaded automatically
+
+# 3. Quality check before committing  
+just quality  # Runs formatting, linting, tests, and integrity validation
+
+# 4. Commit with automatic validation
+git add . && git commit -m "Your changes"
+# Pre-commit hook runs integrity validation automatically
+```
+
+### Feature Management Workflow
+
+```bash
+# Add new feature to project
+cargo rustelo add analytics
+
+# What happens:
+# - Feature dependencies added to Cargo.toml
+# - Feature templates installed to config/features/analytics/
+# - Justfile updated with analytics commands
+# - UnoCSS config extended with analytics styles
+
+# Remove feature cleanly
+cargo rustelo remove analytics
+# Removes all feature-specific configurations safely
+```
+
+### Customization Workflow
+
+```bash
+# 1. Override a template locally (highest precedence)
+cargo rustelo override template justfile
+# Creates config/local/justfile with current content
+# Edit this file - your changes will take precedence
+
+# 2. Override component behavior
+cargo rustelo override component NavBar
+# Creates src/components/local/NavBar.rs
+# Implement your custom navigation bar
+
+# 3. Add local configuration
+echo 'theme_color = "#ff6b6b"' >> config/local/app.toml
+# Local config overrides feature and base configs
+```
+
+### Update Workflow
+
+```bash
+# 1. Check update safety
+cargo rustelo integrity validate --target-version 0.2.0
+
+# 2. Safe update (if validation passes)
+cargo rustelo update --version 0.2.0
+
+# 3. If validation fails, repair first
+cargo rustelo integrity repair --auto
+cargo rustelo integrity validate
+cargo rustelo update --version 0.2.0
+
+# 4. Verify after update
+just test-all
+```
+
+## 🗂️ New Directory Structure
+
+### Before Migration
+```
+my-project/
+├── crates/
+│   └── foundation/
+│       └── templates/     # Custom templates (problematic)
+├── src/
+├── config/               # Some configs
+└── scripts/              # Some scripts
+```
+
+### After Migration
+```
+my-project/
+├── config/
+│   ├── local/            # Local overrides (highest precedence)
+│   │   ├── justfile      # Custom commands
+│   │   ├── app.toml      # App-specific config
+│   │   └── templates/    # Local template overrides
+│   ├── features/         # Feature-specific configurations
+│   │   ├── analytics/
+│   │   │   ├── justfile  # Analytics commands
+│   │   │   ├── uno.config.ts # Analytics styles
+│   │   │   └── package.json # Analytics dependencies
+│   │   └── smart-build/
+│   │       └── justfile  # Smart build commands
+│   └── templates/        # Base template configurations
+├── src/
+│   ├── components/
+│   │   ├── local/        # Local component overrides
+│   │   └── features/     # Feature-specific components
+│   └── content/
+├── scripts/              # Organized by category
+│   ├── local/           # Local automation
+│   ├── features/        # Feature-specific scripts
+│   └── templates/       # Base scripts
+└── templates/           # Project template files
+    └── shared/          # Shared templates for generation
+```
+
+## 🔧 CLI Command Changes
+
+### Template Management
+```bash
+# OLD: No unified template management
+# NEW: Comprehensive template system
+
+cargo rustelo template list                    # List all available templates
+cargo rustelo template show justfile          # Show template content
+cargo rustelo template customize justfile     # Create local override
+cargo rustelo template sync                   # Sync with latest templates
+```
+
+### Feature Management  
+```bash
+# OLD: Manual feature configuration
+# NEW: Integrated feature system
+
+cargo rustelo features list                   # List available features
+cargo rustelo features enabled               # Show enabled features
+cargo rustelo add analytics                  # Add feature with all configs
+cargo rustelo remove smart-build            # Remove feature cleanly
+cargo rustelo features sync                  # Update feature configurations
+```
+
+### Override Management
+```bash
+# NEW: Layered override system
+
+cargo rustelo list-overrides                 # Show active overrides
+cargo rustelo override template justfile     # Override template locally
+cargo rustelo override component NavBar      # Override component locally
+cargo rustelo trace template justfile        # Show resolution path
+cargo rustelo remove-override template justfile # Remove local override
+```
+
+### Integrity Protection
+```bash
+# NEW: Framework integrity validation
+
+cargo rustelo integrity validate             # Check integrity
+cargo rustelo integrity validate --detailed  # Detailed validation report
+cargo rustelo integrity repair              # Auto-repair violations
+cargo rustelo integrity init                # Setup integrity protection
+```
+
+## 🚨 Common Issues and Solutions
+
+### Issue 1: "Template not found" after migration
+
+**Problem**: Old template references in code
+**Solution**:
+```bash
+# Find old references
+grep -r "foundation/templates" src/
+# Update to use layered system
+cargo rustelo trace template <template_name>
+```
+
+### Issue 2: Custom justfile commands missing
+
+**Problem**: Commands defined in old locations
+**Solution**:
+```bash
+# Create local override
+cargo rustelo override template justfile
+# Add your custom commands to config/local/justfile
+```
+
+### Issue 3: Integrity validation fails
+
+**Problem**: Code violates framework boundaries  
+**Solution**:
+```bash
+# Get detailed violation report
+cargo rustelo integrity validate --detailed
+
+# Auto-repair common issues
+cargo rustelo integrity repair
+
+# Manual fixes for critical violations
+# (Follow suggestions in validation report)
+```
+
+### Issue 4: Feature conflicts after migration
+
+**Problem**: Multiple features providing conflicting configurations
+**Solution**:
+```bash
+# Check feature status
+cargo rustelo features status
+
+# Resolve conflicts through local overrides
+cargo rustelo override config <conflicting_config>
+```
+
+### Issue 5: Build performance regression
+
+**Problem**: New layered system seems slower
+**Solution**:
+```bash
+# Enable smart-build feature
+cargo rustelo add smart-build
+
+# Use cached builds
+just build-cached
+
+# Optimize cache
+just cache-optimize
+```
+
+## 📊 Benefits Comparison
+
+### Development Experience
+
+| Aspect | Before | After |
+|--------|---------|-------|
+| Template Management | Manual files | Unified system with CLI |
+| Feature Integration | Manual configuration | Automatic with `rustelo add` |
+| Customization | Risky modifications | Safe layered overrides |
+| Team Collaboration | Inconsistent setups | Standardized configurations |
+| Framework Updates | Often broke customizations | Protected integrity system |
+
+### Code Quality
+
+| Aspect | Before | After |
+|--------|---------|-------|
+| Consistency | Manual enforcement | Automated validation |
+| Documentation | Scattered | Centralized and generated |
+| Testing | Project-specific | Integrated test patterns |
+| Performance | Variable | Optimized with smart-build |
+
+## 🎓 Learning Path
+
+### Week 1: Basic Usage
+- [ ] Complete migration checklist
+- [ ] Learn new CLI commands (`rustelo --help`)
+- [ ] Practice override system (`rustelo override --help`)
+- [ ] Understand layered precedence (Local > Feature > Template > Framework)
+
+### Week 2: Advanced Features
+- [ ] Add your first feature (`rustelo add analytics`)
+- [ ] Customize feature configuration
+- [ ] Learn integrity validation (`rustelo integrity validate`)
+- [ ] Practice safe update workflow
+
+### Week 3: Team Integration
+- [ ] Set up shared team configuration
+- [ ] Document team-specific overrides
+- [ ] Implement CI/CD with integrity checks
+- [ ] Train team members on new workflows
+
+### Month 2+: Mastery
+- [ ] Create custom features
+- [ ] Contribute to framework templates
+- [ ] Optimize build performance with smart caching
+- [ ] Help other teams migrate
+
+## 💡 Tips and Best Practices
+
+### Template Customization
+- **DO**: Use local overrides for project-specific changes
+- **DON'T**: Modify framework core files directly
+- **TIP**: Use `cargo rustelo trace` to understand resolution
+
+### Configuration Management
+- **DO**: Keep sensitive config in environment variables
+- **DON'T**: Commit secrets to configuration files
+- **TIP**: Use `.env.example` for configuration templates
+
+### Feature Integration
+- **DO**: Add features through CLI for proper integration
+- **DON'T**: Manually copy feature files
+- **TIP**: Check feature compatibility before adding multiple features
+
+### Update Safety
+- **DO**: Run integrity validation before updates
+- **DON'T**: Force updates when validation fails
+- **TIP**: Use auto-repair for common violations
+
+### Team Collaboration
+- **DO**: Share feature configurations through version control
+- **DON'T**: Share local overrides unless specifically needed
+- **TIP**: Document team conventions in project README
+
+## 📞 Getting Help
+
+### Self-Service Resources
+1. **CLI Help**: `cargo rustelo help <command>` 
+2. **Template Documentation**: `cargo rustelo template docs`
+3. **Integrity Reports**: `cargo rustelo integrity validate --detailed`
+4. **Feature Guide**: `cargo rustelo features docs`
+
+### Community Support
+1. **GitHub Issues**: Report bugs and request features
+2. **Discussions**: Ask questions and share experiences
+3. **Discord/Slack**: Real-time help from community
+4. **Documentation**: Comprehensive guides and examples
+
+### Professional Support
+1. **Migration Assistance**: Paid migration support for complex projects
+2. **Custom Features**: Development of organization-specific features
+3. **Training**: Team training on new architecture
+4. **Consulting**: Architecture review and optimization
+
+---
+
+**Remember**: Migration is designed to be safe and incremental. Start small, validate often, and don't hesitate to ask for help if you encounter issues.

docs/guides/new-workflows.md

@@ -0,0 +1,487 @@
+# New Development Workflows - Unified Template Architecture
+
+## 🎯 Overview
+
+This document outlines the new development workflows enabled by the unified template architecture. The new system transforms how you develop, customize, and maintain Rustelo projects through:
+
+- **Layered override system** for safe customization
+- **Feature-aware tooling** that adapts to your project
+- **Framework integrity protection** for safe updates
+- **Unified CLI** for all project operations
+
+## 🚀 Core Workflows
+
+### 1. Project Creation Workflow
+
+#### New Project from Scratch
+```bash
+# Create new project with features
+cargo rustelo new my-saas \
+  --template webapp \
+  --features analytics,smart-build,debugging-tools \
+  --database postgres \
+  --styling tailwind
+
+# What happens automatically:
+# ✅ Project structure created with layered config
+# ✅ Features integrated with proper templates  
+# ✅ Tooling configured (justfile, CSS, package.json)
+# ✅ Integrity protection enabled
+# ✅ CI/CD templates added
+```
+
+#### Start Development Immediately
+```bash
+cd my-saas
+
+# One-command development setup
+just setup
+
+# Start full development environment
+just dev-full
+
+# Features automatically active:
+# - Analytics dashboard on http://localhost:3001
+# - Smart build caching enabled
+# - Debugging tools with browser log capture
+# - Hot reload for all file types
+```
+
+### 2. Feature Management Workflow
+
+#### Adding Features During Development
+```bash
+# Add new feature to existing project
+cargo rustelo add auth
+
+# Interactive feature configuration
+✅ Auth feature will be added to my-saas
+📋 Select authentication methods:
+  [x] JWT tokens
+  [x] OAuth2 (Google, GitHub)
+  [ ] 2FA/TOTP
+  [ ] Magic links
+
+📋 Database integration:
+  [x] User model and migrations
+  [x] Session management
+  [x] Role-based access control
+
+🔧 Installing auth feature...
+✅ Added dependencies to Cargo.toml
+✅ Created config/features/auth/
+✅ Updated justfile with auth commands
+✅ Added auth components to src/components/features/auth/
+✅ Created database migrations
+✅ Updated UnoCSS with auth styles
+
+🚀 Feature ready! Try: just auth-setup
+```
+
+#### Feature-Specific Development
+```bash
+# Work on specific feature
+just auth-dev          # Start auth development server
+just auth-test          # Run auth-specific tests  
+just auth-migrate       # Run auth database migrations
+just auth-demo          # Start feature demo/playground
+
+# Analytics for feature development
+just analytics-report   # View auth feature metrics
+```
+
+### 3. Customization Workflow
+
+#### Safe Template Customization
+```bash
+# See what can be customized
+cargo rustelo list-overrides
+
+# Override a template safely
+cargo rustelo override template justfile
+
+# Template copied to config/local/justfile
+# Edit with your customizations - they'll take precedence
+# Framework updates won't overwrite your changes
+
+# Example local justfile addition:
+echo '
+# Custom deployment command for my-saas
+deploy-staging:
+    @echo "🚀 Deploying to staging..."
+    docker build -t my-saas:staging .
+    kubectl apply -f k8s/staging/
+' >> config/local/justfile
+```
+
+#### Component Override System
+```bash
+# Override framework component
+cargo rustelo override component NavBar
+
+# Creates src/components/local/NavBar.rs with current implementation
+# Customize without breaking updates:
+
+// src/components/local/NavBar.rs
+#[component]
+pub fn NavBar() -> impl IntoView {
+    view! {
+        <nav class="my-custom-nav-style">
+            <div class="brand">{"My SaaS"}</div>
+            // Your customizations here
+        </nav>
+    }
+}
+```
+
+#### Configuration Layer System
+```bash
+# Local configuration (highest precedence)
+echo 'brand_color = "#ff6b6b"' >> config/local/app.toml
+
+# Feature configuration
+echo '[dashboard]
+refresh_interval = 30' >> config/features/analytics/config.toml
+
+# Resolution order: Local > Feature > Template > Framework
+cargo rustelo trace config brand_color
+# Output: config/local/app.toml (value: "#ff6b6b")
+```
+
+### 4. Quality Assurance Workflow
+
+#### Continuous Quality Checks
+```bash
+# One command for comprehensive quality validation
+just quality
+
+# Runs in parallel:
+# ✅ Code formatting (rustfmt)
+# ✅ Linting (clippy with strict settings)  
+# ✅ Tests (unit + integration)
+# ✅ Framework integrity validation
+# ✅ Security audit
+# ✅ Performance benchmarks (if enabled)
+# ✅ Documentation generation
+```
+
+#### Pre-commit Workflow (Automatic)
+```bash
+# Commit triggers automatic validation
+git add .
+git commit -m "Add user authentication"
+
+# Pre-commit hook runs:
+# 🔍 Framework integrity check
+# 🧪 Quick test suite
+# 📝 Format check
+# 🔒 Security scan
+
+# Commit blocked if issues found:
+❌ Framework integrity validation failed!
+💡 Run 'cargo rustelo integrity repair' to fix common issues
+💡 Run 'cargo rustelo integrity validate --detailed' for more info
+```
+
+### 5. Team Collaboration Workflow
+
+#### Shared Team Configuration
+```bash
+# Team lead sets up shared configuration
+cargo rustelo init --team-mode
+
+# Creates .rustelo/team-config.toml:
+[team]
+name = "my-saas-team"
+shared_features = ["analytics", "auth", "smart-build"]
+code_style = "strict"
+quality_gates = "required"
+
+[shared_overrides]
+justfile = "config/shared/justfile"
+theme = "config/shared/theme.toml"
+
+# Team members sync automatically
+cargo rustelo sync --team
+```
+
+#### Developer Onboarding  
+```bash
+# New team member setup (one command)
+git clone https://github.com/company/my-saas
+cd my-saas
+cargo rustelo setup --team
+
+# Automatically:
+# ✅ Installs correct Rust toolchain
+# ✅ Downloads team configuration  
+# ✅ Sets up development environment
+# ✅ Runs initial build and tests
+# ✅ Validates integrity
+# ✅ Creates local config template
+
+# Ready to develop in ~2 minutes
+just dev
+```
+
+### 6. Framework Update Workflow
+
+#### Safe Update Process
+```bash
+# Check update safety first  
+cargo rustelo integrity validate --target-version 0.3.0
+
+# If safe (no violations):
+cargo rustelo update --version 0.3.0 --auto-migrate
+
+# If violations found:
+❌ 3 integrity violations prevent safe update:
+   - Hardcoded routes in src/routing.rs:45
+   - Direct core import in src/lib.rs:12  
+   - Unsafe block in src/auth.rs:67
+
+💡 Run auto-repair for common issues:
+cargo rustelo integrity repair --auto
+
+💡 For manual fixes, see detailed report:
+cargo rustelo integrity validate --detailed
+```
+
+#### Update with Migration
+```bash
+# Major update requiring migration
+cargo rustelo update --version 1.0.0 --migrate
+
+# Interactive migration process:
+🔄 Migrating to Rustelo v1.0.0...
+
+📋 Detected changes requiring attention:
+  - Auth trait signature updated (manual fix needed)
+  - New configuration format for routing
+  - Deprecated API: get_route() → resolve_route()
+
+🛠️ Automatic migrations:
+  ✅ Updated Cargo.toml dependencies
+  ✅ Migrated configuration files
+  ✅ Updated deprecated API calls
+  
+⚠️ Manual actions required:
+  1. Update auth trait implementation in src/auth.rs
+     - See migration guide: guides/v0.3-to-v1.0.md
+  2. Review new routing configuration format
+     - Run: cargo rustelo template show routes.toml
+
+Continue with migration? [y/N]: y
+```
+
+### 7. Debugging and Troubleshooting Workflow
+
+#### Comprehensive Debugging
+```bash
+# Start debugging session for specific page
+just debug-full /dashboard
+
+# Launches parallel debugging:
+# 🖥️ Development server with debug logging
+# 🌐 Browser console capture for /dashboard
+# 📊 Performance monitoring
+# 🔍 Network request analysis
+# 📝 Combined debug report generation
+
+# After 30 seconds, generates:
+# reports/debug-session-20231201-143022.html
+```
+
+#### Issue Diagnosis
+```bash
+# Something broken? Run diagnosis
+cargo rustelo diagnose
+
+# Comprehensive system check:
+✅ Framework integrity: PASSED
+✅ Configuration validity: PASSED  
+❌ Database connection: FAILED
+  - PostgreSQL not running on localhost:5432
+  - Fix: just db-start
+✅ Asset compilation: PASSED
+⚠️  Cache performance: DEGRADED  
+  - L1 cache hit rate: 45% (target: >80%)
+  - Fix: just cache-optimize
+
+# Suggested actions prioritized by impact
+```
+
+### 8. Performance Optimization Workflow
+
+#### Smart Build System
+```bash
+# Enable smart caching (if not already enabled)
+cargo rustelo add smart-build
+
+# Immediate benefits:
+just build-smart        # Intelligent incremental builds
+just cache-stats        # Monitor cache performance
+just cache-optimize     # Tune cache parameters
+
+# Performance benchmarking
+just benchmark-builds   # Compare build times
+just benchmark-runtime  # Application performance metrics
+
+# Results:
+Build Performance Improvements:
+  - Clean build: 3m 45s → 1m 12s (68% faster)
+  - Incremental: 45s → 8s (82% faster)  
+  - Cache hit rate: 89%
+```
+
+#### Runtime Performance
+```bash
+# Add performance monitoring
+cargo rustelo add metrics
+
+# Monitor application performance
+just metrics-dashboard  # Real-time performance dashboard
+just metrics-report     # Generate performance report
+
+# Optimization workflow:
+1. just dev              # Start with monitoring
+2. # Use application normally
+3. just metrics-report   # Identify bottlenecks
+4. # Optimize hot paths
+5. just benchmark-compare # Validate improvements
+```
+
+### 9. Deployment Workflow  
+
+#### Production Deployment
+```bash
+# Pre-deployment validation
+just deploy-check
+
+# Comprehensive pre-deployment validation:
+✅ Framework integrity validated
+✅ All tests passing (unit + integration + e2e)
+✅ Security audit clean
+✅ Performance benchmarks acceptable
+✅ Database migrations ready
+✅ Assets optimized
+✅ Configuration valid for production
+
+# Deploy to staging first
+just deploy-staging
+
+# Staging validation
+just validate-staging
+
+# Production deployment (if staging passes)
+just deploy-prod
+```
+
+#### Zero-Downtime Deployment
+```bash
+# Blue-green deployment (if configured)
+just deploy-blue-green
+
+# Rolling deployment
+just deploy-rolling
+
+# Canary deployment  
+just deploy-canary --percentage 10
+
+# Automatic rollback on issues
+# (Configured through deployment templates)
+```
+
+### 10. Monitoring and Maintenance Workflow
+
+#### Health Monitoring
+```bash
+# Application health dashboard
+just monitoring-dashboard
+
+# Automated health checks
+just health-check-full
+
+# System status:
+🟢 Application: Healthy (99.9% uptime)
+🟢 Database: Healthy (avg response: 12ms)
+🟡 Cache: Warning (hit rate: 75%)
+🟢 External APIs: Healthy
+🔍 Integrity: Validated (last check: 5m ago)
+```
+
+#### Maintenance Tasks
+```bash
+# Weekly maintenance routine
+just maintenance-weekly
+
+# Runs automatically:
+# 🧹 Cache cleanup and optimization
+# 📊 Performance report generation  
+# 🔄 Dependency security updates
+# 📋 Health summary report
+# 🔍 Framework integrity check
+# 💾 Automated backups
+```
+
+## 🎯 Workflow Benefits
+
+### For Individual Developers
+
+| Traditional Approach | New Unified Workflows |
+|---------------------|---------------------|
+| Manual template management | Automated with CLI |
+| Risky customizations | Safe layered overrides |
+| Complex feature integration | One-command feature addition |
+| Update anxiety | Integrity-protected updates |
+| Inconsistent tooling | Feature-aware automation |
+
+### For Teams
+
+| Challenge | Solution |
+|-----------|----------|
+| Environment inconsistency | Standardized team configuration |
+| Onboarding complexity | One-command setup |
+| Knowledge silos | Shared templates and workflows |
+| Integration conflicts | Layered override system |
+| Update coordination | Validated update process |
+
+### For Organizations
+
+| Need | Fulfillment |
+|------|-------------|
+| Quality assurance | Automated validation pipelines |
+| Security compliance | Built-in security scanning |
+| Performance standards | Integrated benchmarking |
+| Maintenance efficiency | Automated maintenance workflows |
+| Knowledge management | Documented, templated processes |
+
+## 📚 Learning Resources
+
+### Getting Started (Day 1)
+1. **Quick Start**: Follow migration guide for existing project
+2. **New Project**: Create new project with `cargo rustelo new`
+3. **Basic Commands**: Learn `just --list` and `cargo rustelo --help`
+4. **First Override**: Try `cargo rustelo override template justfile`
+
+### Intermediate (Week 1)
+1. **Feature Management**: Add your first feature with `cargo rustelo add`
+2. **Layer Understanding**: Use `cargo rustelo trace` to understand resolution
+3. **Quality Workflows**: Run `just quality` and understand each check
+4. **Integrity System**: Learn `cargo rustelo integrity validate`
+
+### Advanced (Month 1)
+1. **Custom Features**: Create organization-specific features
+2. **Team Configuration**: Set up shared team workflows
+3. **Performance Optimization**: Master smart-build and caching
+4. **Deployment Automation**: Configure production deployment workflows
+
+### Expert (Month 3+)
+1. **Framework Contribution**: Contribute templates and features back
+2. **Architecture Design**: Design systems using layered principles
+3. **Training Others**: Help teammates and community members
+4. **Innovation**: Pioneer new workflow patterns
+
+---
+
+**Next Steps**: Choose the workflow most relevant to your current needs and try it out. The system is designed to be discoverable - use `--help` on any command to learn more!

docs/guides/quick-start-guide.md

@@ -0,0 +1,528 @@
+# Quick Start Guide - Create Rustelo Implementation
+
+## 🚀 Two Ways to Get Started
+
+This guide shows you how to create a Rustelo implementation using two approaches:
+1. **Command Line**: Interactive, step-by-step creation
+2. **Config File**: Declarative, reproducible setup
+
+Both approaches create the same result - choose what fits your workflow best!
+
+---
+
+## 📋 Prerequisites (2 minutes)
+
+### Install Rustelo CLI
+```bash
+# Install latest Rustelo CLI
+cargo install rustelo-cli
+
+# Verify installation
+cargo rustelo --version
+# Output: rustelo-cli 0.1.0
+
+# Check available commands
+cargo rustelo --help
+```
+
+### System Requirements
+- **Rust**: 1.70+ (install from [rustup.rs](https://rustup.rs))
+- **Node.js**: 18+ (for CSS and tooling)
+- **Git**: For version control
+- **Database**: PostgreSQL or SQLite (optional, for database features)
+
+---
+
+## 🎯 Approach 1: Command Line Creation
+
+### Step 1: Create New Project (Interactive)
+```bash
+# Start interactive project creation
+cargo rustelo new
+
+# Interactive prompts:
+📋 Project name: my-webapp
+📋 Description: My awesome web application
+📋 Template type:
+  > webapp (Full-stack web application)
+    api (REST API server)
+    static (Static site generator)
+    desktop (Desktop application)
+
+📋 Select features:
+  [x] analytics (Usage analytics and monitoring)
+  [x] auth (Authentication and authorization)  
+  [ ] smart-build (Intelligent build caching)
+  [x] debugging-tools (Enhanced debugging capabilities)
+  [ ] email (Multi-provider email system)
+  [ ] tls (HTTPS/TLS support)
+
+📋 Database:
+  > postgres (PostgreSQL - production ready)
+    sqlite (SQLite - development friendly)
+    none (No database)
+
+📋 Styling:
+  [x] tailwind (Tailwind CSS via UnoCSS)
+  [ ] custom (Custom CSS setup)
+
+📋 Additional options:
+  [x] github-actions (CI/CD workflows)
+  [x] docker (Docker configuration)
+  [x] docs (Documentation setup)
+```
+
+### Step 2: Project Generated
+```bash
+✅ Created my-webapp project with:
+   - Template: webapp
+   - Features: analytics, auth, debugging-tools
+   - Database: PostgreSQL
+   - Styling: Tailwind/UnoCSS
+   - CI/CD: GitHub Actions
+   - Containerization: Docker
+
+📁 Project structure created at: ./my-webapp/
+🔧 Configuration files generated
+📦 Dependencies resolved
+🚀 Ready for development!
+
+Next steps:
+  cd my-webapp
+  just setup
+  just dev
+```
+
+### Step 3: Development Setup
+```bash
+cd my-webapp
+
+# One-command setup (installs dependencies, sets up database, etc.)
+just setup
+
+# Setup process:
+🔧 Installing Rust dependencies...
+📦 Installing Node.js dependencies...
+🗄️ Setting up PostgreSQL database...
+🎨 Building initial CSS...
+✅ Development environment ready!
+
+# Start development server
+just dev
+
+# Development server started:
+🚀 Server running at http://localhost:3000
+📊 Analytics dashboard at http://localhost:3001
+🔧 Debug tools enabled
+🔄 Hot reload active
+```
+
+### Step 4: Explore Your Project
+```bash
+# See available commands
+just --list
+
+# Available recipes:
+# dev              Start development server
+# dev-full         Start all services (server, analytics, debugging)
+# build            Build for development
+# build-prod       Build for production
+# test             Run tests
+# auth-setup       Setup authentication
+# analytics-report Generate analytics report
+# db-migrate       Run database migrations
+# quality          Run all quality checks
+
+# Try some commands:
+just auth-setup     # Configure authentication
+just db-migrate     # Run database migrations
+just quality        # Check code quality
+```
+
+---
+
+## ⚙️ Approach 2: Config File Creation
+
+### Step 1: Create Project Config File
+```bash
+# Create project configuration
+mkdir my-webapp
+cd my-webapp
+
+# Create rustelo.toml configuration
+cat > rustelo.toml << 'EOF'
+[project]
+name = "my-webapp"
+description = "My awesome web application"
+version = "0.1.0"
+authors = ["Your Name <your.email@example.com>"]
+license = "MIT"
+
+[template]
+type = "webapp"
+variant = "full-stack"
+
+[features]
+# Core features
+analytics = { enabled = true, config = { retention_days = 30, dashboard_port = 3001 } }
+auth = { enabled = true, config = { methods = ["jwt", "oauth2"], providers = ["google", "github"] } }
+debugging-tools = { enabled = true, config = { browser_logs = true, performance_monitoring = true } }
+
+# Optional features (disabled by default)
+smart-build = { enabled = false }
+email = { enabled = false }
+tls = { enabled = false }
+
+[database]
+type = "postgres"
+url = "postgresql://localhost:5432/my_webapp"
+migrations = true
+auto_setup = true
+
+[styling]
+framework = "tailwind"
+processor = "unocss"
+themes = ["light", "dark"]
+custom_colors = { primary = "#3b82f6", secondary = "#10b981" }
+
+[development]
+hot_reload = true
+debug_mode = true
+log_level = "debug"
+port = 3000
+
+[build]
+optimize = true
+target_dir = "target"
+features = ["analytics", "auth", "debugging-tools"]
+
+[deployment]
+docker = true
+ci_cd = "github-actions"
+environments = ["staging", "production"]
+
+[tooling]
+justfile = true
+package_json = true
+dockerfile = true
+github_actions = true
+documentation = true
+
+[quality]
+pre_commit_hooks = true
+code_formatting = "rustfmt"
+linting = "clippy"
+testing = { unit = true, integration = true, e2e = false }
+EOF
+```
+
+### Step 2: Generate Project from Config
+```bash
+# Create project from configuration file
+cargo rustelo create --config rustelo.toml
+
+# Output:
+📋 Reading configuration from rustelo.toml...
+✅ Configuration validated
+🏗️ Creating project structure...
+📦 Installing dependencies...
+🔧 Configuring features...
+🎨 Setting up styling system...
+🗄️ Configuring database...
+🚀 Setting up development environment...
+
+✅ Project created successfully!
+
+Project: my-webapp (v0.1.0)
+Template: webapp (full-stack variant)
+Features: analytics, auth, debugging-tools
+Database: PostgreSQL
+Styling: Tailwind/UnoCSS
+
+Next steps:
+  just setup
+  just dev
+```
+
+### Step 3: Verify Configuration
+```bash
+# Check generated project matches config
+cargo rustelo info
+
+# Output:
+📋 Project Information:
+  Name: my-webapp
+  Template: webapp (full-stack)
+  Generated by: cargo rustelo v0.1.0
+  Configuration: rustelo.toml
+  
+🎯 Enabled Features:
+  ✅ analytics (retention: 30 days, port: 3001)
+  ✅ auth (JWT + OAuth2: google, github)  
+  ✅ debugging-tools (browser logs, performance monitoring)
+  
+🗄️ Database:
+  Type: PostgreSQL
+  URL: postgresql://localhost:5432/my_webapp
+  Migrations: Enabled
+  
+🎨 Styling:
+  Framework: Tailwind CSS
+  Processor: UnoCSS
+  Themes: light, dark
+  Primary: #3b82f6, Secondary: #10b981
+
+🔧 Development:
+  Port: 3000
+  Hot Reload: Enabled
+  Debug Mode: Enabled
+  Log Level: debug
+```
+
+### Step 4: Customize Configuration (Optional)
+```bash
+# Edit configuration for your needs
+nano rustelo.toml
+
+# Example customizations:
+[features]
+# Add more features
+smart-build = { enabled = true, config = { cache_size = "2GB", parallel_jobs = 4 } }
+email = { enabled = true, config = { provider = "sendgrid", templates = true } }
+
+[styling.custom_colors]
+# Update brand colors
+primary = "#ff6b6b"
+secondary = "#4ecdc4"
+accent = "#45b7d1"
+
+# Regenerate with new configuration
+cargo rustelo update --config rustelo.toml
+
+# Applies configuration changes:
+✅ Added smart-build feature
+✅ Added email feature  
+✅ Updated color theme
+🔄 Rebuilding CSS with new colors...
+✅ Configuration updated successfully!
+```
+
+---
+
+## 🔄 Configuration File Templates
+
+### Minimal Configuration (API Only)
+```toml
+# minimal-api.toml
+[project]
+name = "my-api"
+description = "Simple REST API"
+
+[template]
+type = "api"
+
+[features]
+auth = { enabled = true }
+
+[database]
+type = "sqlite"
+```
+
+### Full-Featured Web App
+```toml
+# full-webapp.toml
+[project]
+name = "my-saas"
+description = "Full SaaS application"
+
+[template] 
+type = "webapp"
+variant = "saas"
+
+[features]
+analytics = { enabled = true }
+auth = { enabled = true, config = { methods = ["jwt", "oauth2", "2fa"] } }
+smart-build = { enabled = true }
+debugging-tools = { enabled = true }
+email = { enabled = true }
+tls = { enabled = true }
+
+[database]
+type = "postgres"
+url = "$DATABASE_URL"
+
+[styling]
+framework = "tailwind"
+themes = ["light", "dark", "system"]
+
+[deployment]
+docker = true
+ci_cd = "github-actions"
+environments = ["dev", "staging", "prod"]
+```
+
+### Static Site
+```toml
+# static-site.toml
+[project]
+name = "my-blog"
+description = "Personal blog"
+
+[template]
+type = "static"
+
+[features]
+analytics = { enabled = true, config = { provider = "google" } }
+
+[styling]
+framework = "tailwind"
+themes = ["minimal"]
+
+[content]
+type = "markdown"
+source = "content/"
+```
+
+### Team/Organization Template
+```toml
+# team-template.toml
+[project]
+name = "team-project"
+description = "Standardized team project"
+
+[template]
+type = "webapp"
+
+[features]
+analytics = { enabled = true }
+auth = { enabled = true }
+smart-build = { enabled = true }
+debugging-tools = { enabled = true }
+
+[team]
+shared_config = true
+code_style = "strict"
+pre_commit_hooks = ["format", "lint", "test", "integrity"]
+
+[quality]
+coverage_threshold = 90.0
+security_scan = true
+performance_budget = { fcp = "1.5s", lcp = "2.5s" }
+```
+
+---
+
+## 🎯 Next Steps After Creation
+
+### Development Workflow
+```bash
+# Start development
+just dev
+
+# In separate terminal, try features:
+just auth-setup        # Setup authentication
+just analytics-report  # View analytics
+just db-migrate        # Run database migrations
+
+# Check code quality
+just quality
+
+# Run tests
+just test
+```
+
+### Customization
+```bash
+# Override templates locally
+cargo rustelo override template justfile
+# Edit config/local/justfile with your custom commands
+
+# Override components
+cargo rustelo override component NavBar
+# Edit src/components/local/NavBar.rs
+
+# Add local configuration
+echo 'debug_toolbar = true' >> config/local/development.toml
+```
+
+### Feature Management
+```bash
+# Add more features
+cargo rustelo add smart-build
+cargo rustelo add email
+
+# Check feature status
+cargo rustelo features status
+
+# Remove features
+cargo rustelo remove debugging-tools
+```
+
+### Production Deployment
+```bash
+# Build for production
+just build-prod
+
+# Run deployment checks
+just deploy-check
+
+# Deploy (if configured)
+just deploy-staging  # Deploy to staging first
+just deploy-prod     # Deploy to production
+```
+
+---
+
+## 🚨 Common Issues and Solutions
+
+### Issue 1: Database Connection Failed
+```bash
+# Problem: PostgreSQL not running
+# Solution:
+just db-start        # Start database
+just db-setup        # Setup database schema
+just db-migrate      # Run migrations
+```
+
+### Issue 2: Port Already in Use
+```bash
+# Problem: Port 3000 already in use
+# Solution: Change port in config/local/development.toml
+echo 'port = 3001' >> config/local/development.toml
+just dev
+```
+
+### Issue 3: Node.js Dependencies Missing
+```bash
+# Problem: CSS build fails
+# Solution:
+npm install          # Install Node.js dependencies
+just css-build       # Rebuild CSS
+```
+
+### Issue 4: Permission Denied
+```bash
+# Problem: Permission errors on Linux/Mac
+# Solution:
+chmod +x scripts/**/*.sh  # Make scripts executable
+sudo chown -R $USER target/  # Fix target directory ownership
+```
+
+---
+
+## 📚 What's Next?
+
+1. **Read the Migration Guide**: [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)
+2. **Explore New Workflows**: [NEW_WORKFLOWS.md](./NEW_WORKFLOWS.md)  
+3. **Understand Architecture**: [TEMPLATE_ARCHITECTURE.md](./TEMPLATE_ARCHITECTURE.md)
+4. **Learn Layer System**: [LAYERED_OVERRIDE_SYSTEM.md](./LAYERED_OVERRIDE_SYSTEM.md)
+5. **Check Integrity Protection**: [FRAMEWORK_INTEGRITY_PROTECTION.md](./FRAMEWORK_INTEGRITY_PROTECTION.md)
+
+## 🆘 Getting Help
+
+- **CLI Help**: `cargo rustelo help <command>`
+- **Project Issues**: `cargo rustelo diagnose`
+- **Community**: GitHub Discussions
+- **Documentation**: `cargo rustelo docs`
+
+**Happy coding with Rustelo! 🦀🚀**

docs/guides/tooling-integration.md

@@ -0,0 +1,501 @@
+# Rustelo Tooling Integration
+
+## 🎯 Overview
+
+Complete tooling template coverage ensures that all development tools work seamlessly with the unified template system and layered override architecture. This integration provides:
+
+- **Feature-aware tooling** that adapts to enabled features
+- **Layered configuration merging** for all tools
+- **Consistent development workflows** across all project templates
+- **Hot-reload integration** with the override system
+
+## 🛠️ Integrated Tools
+
+### 1. Just (Command Runner)
+
+**Integration Points:**
+- Feature-specific commands added automatically
+- Local overrides for custom workflows
+- Template-based recipe generation
+- Environment-aware execution
+
+**Example Structure:**
+```
+config/
+├── local/justfile           # Local command overrides
+├── features/
+│   ├── analytics/justfile   # Analytics-specific commands
+│   └── smart-build/justfile # Build optimization commands
+└── templates/justfile       # Base commands from template
+```
+
+**Command Examples:**
+```just
+# Base template commands
+dev:
+    cargo leptos watch
+
+build:
+    cargo leptos build --release
+
+# Feature-specific commands (analytics)
+analytics-report:
+    cargo run --bin analytics -- report --hours 24
+
+# Local overrides
+dev-debug:
+    RUST_LOG=debug cargo leptos watch
+```
+
+### 2. CSS/UnoCSS System
+
+**Integration Points:**
+- Layered UnoCSS configurations
+- Feature-specific styling
+- Component-aware class generation
+- Development vs production builds
+
+**Configuration Layers:**
+```typescript
+// config/templates/uno.config.ts (Base)
+export default {
+  presets: ['@unocss/preset-uno', '@unocss/preset-wind'],
+  theme: {
+    colors: {
+      primary: '#3b82f6',
+    }
+  }
+}
+
+// config/features/analytics/uno.config.ts
+export default {
+  theme: {
+    colors: {
+      analytics: '#10b981',
+    }
+  },
+  shortcuts: {
+    'metric-card': 'bg-white shadow-md rounded-lg p-4',
+  }
+}
+
+// config/local/uno.config.ts (Highest precedence)
+export default {
+  theme: {
+    colors: {
+      primary: '#ef4444',  // Override
+      brand: '#8b5cf6',    // Local addition
+    }
+  }
+}
+```
+
+### 3. Package.json Management
+
+**Integration Points:**
+- Dependency management across layers
+- Script merging and overrides
+- Feature-specific Node.js tools
+- Development vs production configs
+
+**Layer Structure:**
+```json
+// config/templates/package.json
+{
+  "scripts": {
+    "css:build": "unocss 'src/**/*.rs' -o public/app.css",
+    "css:watch": "unocss 'src/**/*.rs' -o public/app.css --watch"
+  },
+  "devDependencies": {
+    "@unocss/cli": "^0.58.0"
+  }
+}
+
+// config/features/analytics/package.json  
+{
+  "scripts": {
+    "analytics:dev": "node scripts/analytics-dev.js"
+  },
+  "dependencies": {
+    "chart.js": "^4.0.0"
+  }
+}
+
+// config/local/package.json
+{
+  "scripts": {
+    "dev": "concurrently \"cargo leptos watch\" \"npm run css:watch\"",
+    "test": "cargo test && npm run test:frontend"
+  }
+}
+```
+
+### 4. Cargo.toml Workspace Configuration
+
+**Integration Points:**
+- Workspace dependency management
+- Feature flag coordination
+- Crate-specific configurations
+- Build optimization settings
+
+**Layer Examples:**
+```toml
+# config/templates/Cargo.toml (Base workspace)
+[workspace]
+members = ["crates/*"]
+
+[workspace.dependencies]
+leptos = "0.6"
+tokio = { version = "1.0", features = ["full"] }
+
+# config/features/analytics/Cargo.toml
+[workspace.dependencies]
+prometheus = "0.13"
+chrono = { version = "0.4", features = ["serde"] }
+
+# config/local/Cargo.toml (Local overrides)
+[workspace.dependencies] 
+leptos = "0.7"  # Override version
+anyhow = "1.0"  # Local addition
+
+[profile.dev]
+opt-level = 1  # Local optimization
+```
+
+### 5. Development Scripts
+
+**Integration Points:**
+- Layered script execution
+- Feature-aware automation
+- Environment detection
+- Cross-platform compatibility
+
+**Script Structure:**
+```
+scripts/
+├── local/           # Local automation scripts
+│   ├── custom-build.sh
+│   └── deploy-staging.sh
+├── features/        # Feature-specific scripts
+│   ├── analytics/
+│   │   ├── collect-metrics.sh
+│   │   └── generate-reports.sh
+│   └── smart-build/
+│       └── cache-management.sh
+└── templates/       # Base template scripts
+    ├── setup.sh
+    ├── build.sh
+    └── test.sh
+```
+
+### 6. Build System Integration
+
+**Integration Points:**
+- Build.rs script composition
+- Asset pipeline coordination
+- Route generation integration
+- Optimization settings
+
+**Build Configuration:**
+```rust
+// crates/client/build.rs (Generated)
+fn main() {
+    // Layer-aware CSS build
+    let css_config = resolve_layered_config::<UnoConfig>("uno.config.ts")?;
+    build_css_with_config(&css_config)?;
+    
+    // Layer-aware route generation
+    let routes = resolve_layered_routes()?;
+    generate_route_code(&routes)?;
+    
+    // Feature-specific build steps
+    if feature_enabled("analytics") {
+        build_analytics_assets()?;
+    }
+}
+```
+
+## 🔧 Implementation Strategy
+
+### 1. Template Generation
+
+**Enhanced Template System:**
+- Templates include complete tooling setup
+- Feature selection determines which tools are included
+- Layered override structure created automatically
+
+**CLI Integration:**
+```bash
+# Create project with full tooling
+cargo rustelo new my-project --template basic --features analytics,smart-build
+
+# Result: Complete tooling setup with:
+# - Just commands for development
+# - UnoCSS configuration with analytics styles
+# - Package.json with analytics dependencies
+# - Build scripts with smart caching
+```
+
+### 2. Configuration Resolution
+
+**Unified Configuration Engine:**
+```rust
+pub struct ToolingManager {
+    config_resolver: LayeredConfig,
+    project_root: PathBuf,
+}
+
+impl ToolingManager {
+    pub fn resolve_just_config(&mut self) -> Result<JustConfig> {
+        self.config_resolver.resolve("justfile")
+    }
+    
+    pub fn resolve_css_config(&mut self) -> Result<UnoConfig> {
+        self.config_resolver.resolve("uno.config.ts")
+    }
+    
+    pub fn resolve_package_config(&mut self) -> Result<PackageConfig> {
+        self.config_resolver.resolve("package.json")
+    }
+}
+```
+
+### 3. Feature Integration
+
+**Automatic Tool Updates:**
+```bash
+# Adding feature updates all related tooling
+cargo rustelo add analytics
+
+# Updates:
+# - justfile (adds analytics commands)
+# - uno.config.ts (adds analytics styles)  
+# - package.json (adds analytics dependencies)
+# - build scripts (adds analytics builds)
+```
+
+### 4. Development Workflows
+
+**Hot Reload Integration:**
+- CSS changes trigger UnoCSS rebuild
+- Configuration changes reload layered configs
+- Component overrides trigger selective rebuilds
+- Script changes restart development server
+
+**Watch System:**
+```bash
+# Comprehensive development mode
+just dev
+
+# Runs:
+# - cargo leptos watch (Rust hot reload)
+# - unocss --watch (CSS hot reload)
+# - node scripts/config-watcher.js (Config hot reload)
+```
+
+## 📋 Tooling Templates
+
+### Just Template (Feature-Aware)
+
+```just
+# Base development commands
+dev:
+    @echo "🚀 Starting development server..."
+    cargo leptos watch
+
+build:
+    @echo "🏗️ Building for production..."
+    cargo leptos build --release
+
+test:
+    @echo "🧪 Running tests..."
+    cargo test
+
+# CSS commands (always included)
+css-build:
+    @echo "🎨 Building CSS..."
+    unocss 'src/**/*.rs' -o public/app.css
+
+css-watch:
+    @echo "👀 Watching CSS..."
+    unocss 'src/**/*.rs' -o public/app.css --watch
+
+{{#if features.analytics}}
+# Analytics commands (feature-specific)
+analytics-report:
+    @echo "📊 Generating analytics report..."
+    cargo run --bin analytics -- report --hours 24
+
+analytics-dashboard:
+    @echo "📈 Starting analytics dashboard..."
+    cargo run --bin analytics -- dashboard
+{{/if}}
+
+{{#if features.smart-build}}
+# Smart build commands (feature-specific)
+build-cached:
+    @echo "⚡ Building with smart cache..."
+    cargo run --bin smart-build -- build --cached
+
+cache-clean:
+    @echo "🧹 Cleaning build cache..."
+    cargo run --bin smart-build -- cache clean
+{{/if}}
+
+# Local overrides marker
+{{#if local_commands}}
+# === Local Commands (Override) ===
+{{local_commands}}
+{{/if}}
+```
+
+### UnoCSS Template (Layered)
+
+```typescript
+// Base configuration with feature composition
+import { defineConfig } from 'unocss'
+
+export default defineConfig({
+  // Base presets (always included)
+  presets: [
+    '@unocss/preset-uno',
+    '@unocss/preset-wind',
+    '@unocss/preset-typography',
+  ],
+  
+  // Base theme
+  theme: {
+    colors: {
+      primary: '{{theme.primary_color}}',
+      secondary: '{{theme.secondary_color}}',
+      {{#each theme.colors}}
+      '{{@key}}': '{{this}}',
+      {{/each}}
+    },
+    fontFamily: {
+      sans: {{theme.font_sans}},
+      serif: {{theme.font_serif}},
+      mono: {{theme.font_mono}},
+    },
+  },
+  
+  // Base shortcuts
+  shortcuts: {
+    'btn': 'px-4 py-2 rounded transition-colors',
+    'btn-primary': 'btn bg-primary text-white hover:bg-primary/80',
+    'card': 'bg-white shadow-md rounded-lg p-4',
+    {{#each shortcuts}}
+    '{{@key}}': '{{this}}',
+    {{/each}}
+  },
+  
+  {{#if features.analytics}}
+  // Analytics feature styles
+  rules: [
+    [/^metric-(\d+)$/, ([, d]) => ({ 'font-size': `${d}px` })],
+  ],
+  shortcuts: {
+    ...shortcuts,
+    'metric-card': 'card border-l-4 border-analytics',
+    'chart-container': 'w-full h-64 bg-gray-50 rounded',
+  },
+  {{/if}}
+  
+  // Content sources (layer-aware)
+  content: [
+    'src/**/*.rs',
+    'templates/**/*.html',
+    {{#if features.analytics}}
+    'src/components/features/analytics/**/*.rs',
+    {{/if}}
+    {{#if local_content}}
+    'src/components/local/**/*.rs',
+    {{/if}}
+  ],
+  
+  // Safelist for always-included classes
+  safelist: [
+    'text-red-500',
+    'text-green-500',
+    'text-blue-500',
+    {{#each safelist}}
+    '{{this}}',
+    {{/each}}
+  ]
+})
+```
+
+### Package.json Template (Mergeable)
+
+```json
+{
+  "name": "{{project_name}}",
+  "version": "{{project_version}}",
+  "description": "{{project_description}}",
+  "private": true,
+  
+  "scripts": {
+    "css:build": "unocss 'src/**/*.rs' -o public/app.css",
+    "css:watch": "unocss 'src/**/*.rs' -o public/app.css --watch",
+    "build": "npm run css:build && cargo leptos build --release",
+    "dev": "concurrently \"cargo leptos watch\" \"npm run css:watch\"",
+    
+    {{#if features.analytics}}
+    "analytics:dev": "node scripts/features/analytics/dev-server.js",
+    "analytics:report": "node scripts/features/analytics/generate-report.js",
+    {{/if}}
+    
+    {{#if features.smart-build}}
+    "build:smart": "node scripts/features/smart-build/cached-build.js",
+    "cache:clean": "node scripts/features/smart-build/clean-cache.js",
+    {{/if}}
+    
+    {{#each local_scripts}}
+    "{{@key}}": "{{this}}",
+    {{/each}}
+  },
+  
+  "devDependencies": {
+    "@unocss/cli": "^0.58.0",
+    "@unocss/preset-uno": "^0.58.0",
+    "@unocss/preset-wind": "^0.58.0",
+    "concurrently": "^8.2.0",
+    
+    {{#if features.analytics}}
+    "chart.js": "^4.0.0",
+    "date-fns": "^2.30.0",
+    {{/if}}
+    
+    {{#if features.smart-build}}
+    "chokidar": "^3.5.0",
+    "fast-glob": "^3.3.0",
+    {{/if}}
+    
+    {{#each additional_dependencies}}
+    "{{@key}}": "{{this}}",
+    {{/each}}
+  }
+}
+```
+
+## 🎯 Benefits
+
+### For Developers
+- **Unified tooling** across all project types
+- **Feature-aware automation** - tools adapt to enabled features
+- **Local customization** without losing update capability
+- **Consistent workflows** regardless of project complexity
+
+### For Teams
+- **Standardized tooling** across all Rustelo projects
+- **Shared configurations** with local override capability
+- **Feature parity** - same tools work the same way everywhere
+- **Easy onboarding** - familiar tooling patterns
+
+### For Framework
+- **Tool integration** - all tools work together seamlessly
+- **Update safety** - tooling updates don't break customizations
+- **Feature composability** - tools from different features integrate properly
+- **Performance optimization** - smart caching and coordination
+
+This comprehensive tooling integration ensures that Rustelo provides a complete, production-ready development experience with all the tools developers need working seamlessly together.

docs/howto/README.md

@@ -0,0 +1,8 @@
+# How-To Guides
+
+Practical how-to guides for common tasks with Rustelo.
+
+## See Also
+
+- [Guides](../guides/) - Step-by-step guides
+- [Examples](../examples/) - Code examples

docs/howto/creating-a-site.md

@@ -0,0 +1,474 @@
+# Creating a Site with Rustelo Framework
+
+This guide provides step-by-step instructions for creating a new website project using Rustelo as a framework dependency.
+
+## 🎯 Overview
+
+Rustelo follows a **framework-as-dependency** architecture, meaning you don't fork the framework - you use it as a library dependency in your own project. This ensures you can:
+
+- ✅ Get framework updates automatically
+- ✅ Keep your customizations separate from framework code
+- ✅ Use the asset fallback system (Local → Framework → Generated)
+- ✅ Avoid maintaining a fork
+
+## 📋 Prerequisites
+
+- Rust 1.70+ installed
+- Node.js 18+ (for frontend assets)
+- Just task runner: `cargo install just`
+- Git (recommended for version control)
+
+## 🚀 Step-by-Step Guide
+
+### Step 1: Create Your Project Directory
+
+```bash
+# Create your site project
+mkdir my-awesome-site
+cd my-awesome-site
+
+# Initialize git repository (optional but recommended)
+git init
+```
+
+### Step 2: Create Cargo.toml
+
+Create a `Cargo.toml` file with Rustelo dependencies:
+
+```toml
+[package]
+name = "my-awesome-site"
+version = "0.1.0"
+edition = "2021"
+authors = ["Your Name <your.email@example.com>"]
+description = "My awesome site built with Rustelo framework"
+
+# Main binary
+[[bin]]
+name = "server"
+path = "src/main.rs"
+
+[dependencies]
+# Core Rustelo framework dependencies
+rustelo-core = { path = "../rustelo/crates/rustelo-core" }
+rustelo-web = { path = "../rustelo/crates/rustelo-web" }
+
+# Optional framework components (uncomment as needed)
+# rustelo-auth = { path = "../rustelo/crates/rustelo-auth" }
+# rustelo-content = { path = "../rustelo/crates/rustelo-content" }
+
+# Web framework essentials
+leptos = { version = "0.8.6", features = ["ssr"] }
+leptos_axum = "0.8.5"
+axum = "0.8.4"
+tokio = { version = "1.47.1", features = ["rt-multi-thread", "signal"] }
+tower = "0.5.2"
+tower-http = { version = "0.6.6", features = ["fs"] }
+
+# Basic utilities
+tracing = "0.1"
+tracing-subscriber = "0.3"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+[features]
+default = []
+
+# Optional features (enable as needed)
+# auth = ["rustelo-auth"]
+# content = ["rustelo-content"]
+# database = ["rustelo-core/database"]
+
+[profile.release]
+codegen-units = 1
+lto = true
+opt-level = 'z'
+
+# Leptos configuration for development server
+[[workspace.metadata.leptos]]
+name = "my-awesome-site"
+bin-package = "my-awesome-site"
+bin-target-path = "src/main.rs"
+lib-profile-release = "wasm-release"
+```
+
+### Step 3: Create Source Code Structure
+
+```bash
+# Create source directory
+mkdir -p src
+
+# Create basic directory structure
+mkdir -p {content,assets,config,justfiles,public}
+```
+
+### Step 4: Create Main Application File
+
+Create `src/main.rs`:
+
+```rust
+//! My Awesome Site - Built with Rustelo Framework
+//! 
+//! This demonstrates using Rustelo as a framework dependency for a production site.
+
+use axum::{
+    response::Html,
+    routing::get,
+    Router,
+};
+use rustelo_core::config::RusteloConfig;
+use tower_http::services::ServeDir;
+use tracing_subscriber;
+
+/// Home page component
+async fn home() -> Html<&'static str> {
+    Html(r#"
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>My Awesome Site</title>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <style>
+            body { 
+                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; 
+                max-width: 1200px; 
+                margin: 0 auto; 
+                padding: 2rem;
+                line-height: 1.6;
+            }
+            .hero { 
+                text-align: center; 
+                padding: 4rem 0; 
+                background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+                color: white;
+                border-radius: 1rem;
+                margin-bottom: 3rem;
+            }
+            .features { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 2rem; }
+            .feature { 
+                background: #f8fafc; 
+                padding: 2rem; 
+                border-radius: 0.5rem; 
+                border: 1px solid #e2e8f0;
+            }
+            .feature h3 { color: #2d3748; margin-top: 0; }
+            .footer { 
+                text-align: center; 
+                margin-top: 4rem; 
+                padding-top: 2rem; 
+                border-top: 1px solid #e2e8f0;
+                color: #718096;
+            }
+        </style>
+    </head>
+    <body>
+        <div class="hero">
+            <h1>🌟 My Awesome Site</h1>
+            <p>Built with Rustelo Framework-as-Dependency Architecture</p>
+        </div>
+        
+        <div class="features">
+            <div class="feature">
+                <h3>🦀 Framework-as-Dependency</h3>
+                <p>Uses Rustelo as a library dependency, not a fork. Get framework updates automatically while keeping your customizations.</p>
+            </div>
+            
+            <div class="feature">
+                <h3>📁 Asset Fallback System</h3>
+                <p>Local → Framework → Generated priority resolution. Override any framework asset with your local version.</p>
+            </div>
+            
+            <div class="feature">
+                <h3>🔧 Modular Features</h3>
+                <p>Enable only the framework features you need: authentication, content management, database support, etc.</p>
+            </div>
+            
+            <div class="feature">
+                <h3>🚀 Production Ready</h3>
+                <p>Built on Leptos + Axum with SSR, optimized builds, and cross-compilation support.</p>
+            </div>
+        </div>
+        
+        <div class="footer">
+            <p><em>Powered by Rustelo Framework • <a href="/api/status">API Status</a></em></p>
+        </div>
+    </body>
+    </html>
+    "#)
+}
+
+/// About page
+async fn about() -> Html<&'static str> {
+    Html(r#"
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>About - My Awesome Site</title>
+        <style>
+            body { font-family: Arial, sans-serif; max-width: 800px; margin: 0 auto; padding: 2rem; }
+            .nav { margin-bottom: 2rem; }
+            .nav a { margin-right: 1rem; text-decoration: none; color: #2563eb; }
+        </style>
+    </head>
+    <body>
+        <div class="nav">
+            <a href="/">Home</a>
+            <a href="/about">About</a>
+            <a href="/api/status">API</a>
+        </div>
+        <h1>About My Awesome Site</h1>
+        <p>This site demonstrates the Rustelo framework-as-dependency architecture.</p>
+        <p>Key benefits:</p>
+        <ul>
+            <li>No source code forking required</li>
+            <li>Automatic framework updates</li>
+            <li>Local asset overrides</li>
+            <li>Modular feature system</li>
+        </ul>
+    </body>
+    </html>
+    "#)
+}
+
+/// API endpoint showing framework integration
+async fn api_status() -> axum::Json<serde_json::Value> {
+    axum::Json(serde_json::json!({
+        "status": "ok",
+        "framework": "rustelo",
+        "architecture": "framework-as-dependency",
+        "features": {
+            "core": true,
+            "web": true,
+            "auth": false,
+            "content": false
+        },
+        "message": "🎉 Framework-as-dependency architecture working!"
+    }))
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Initialize logging
+    tracing_subscriber::fmt()
+        .with_target(false)
+        .init();
+
+    tracing::info!("🚀 Starting My Awesome Site...");
+
+    // Load framework configuration (with defaults if no config file exists)
+    let _config = RusteloConfig::load().unwrap_or_default();
+    
+    tracing::info!("📋 Framework configuration loaded");
+
+    // Build application routes
+    let app = Router::new()
+        .route("/", get(home))
+        .route("/about", get(about))
+        .route("/api/status", get(api_status))
+        // Serve static files if they exist
+        .nest_service("/static", ServeDir::new("public"))
+        .nest_service("/assets", ServeDir::new("assets"))
+        .with_state(());
+
+    // Start server
+    let addr = "127.0.0.1:3030";
+    tracing::info!("🌐 Server starting at http://{}", addr);
+    tracing::info!("✨ Framework-as-dependency architecture active!");
+
+    let listener = tokio::net::TcpListener::bind(addr).await?;
+    axum::serve(listener, app).await?;
+
+    Ok(())
+}
+```
+
+### Step 5: Create Framework Configuration (Optional)
+
+Create `rustelo.toml` for framework configuration:
+
+```toml
+[framework]
+name = "my-awesome-site"
+version = "0.1.0"
+description = "My awesome site built with Rustelo"
+
+[assets]
+# Asset resolution configuration
+local_path = "assets"
+framework_path = "../rustelo/assets"
+organize_by_category = false
+
+[server]
+host = "127.0.0.1"
+port = 3030
+enable_tls = false
+
+[features]
+# Enable framework features as needed
+auth = false
+content = false
+database = false
+```
+
+### Step 6: Create Justfile for Task Management
+
+Create `justfile` with framework fallback pattern:
+
+```just
+# My Awesome Site - Task Runner with Framework Fallback
+# Local tasks take priority, framework tasks as fallback
+
+# Try to import local tasks, then framework tasks
+mod? local-base 'justfiles/base.just'                    # Local base tasks
+mod? base '../rustelo/justfiles/base.just'              # Framework fallback
+
+# Local development server
+dev:
+    @echo "🚀 Starting development server..."
+    cargo run --bin server
+
+# Local build
+build mode="release":
+    @echo "🔨 Building for {{mode}} mode..."
+    @if [ "{{mode}}" = "release" ]; then \
+        cargo build --release; \
+    else \
+        cargo build; \
+    fi
+
+# Local test
+test:
+    @echo "🧪 Running tests..."
+    cargo test
+
+# Local clean
+clean:
+    @echo "🧹 Cleaning build artifacts..."
+    cargo clean
+    rm -rf target/
+
+# Check code quality
+check:
+    @echo "🔍 Checking code quality..."
+    cargo check
+    cargo clippy
+    cargo fmt --check
+
+# Format code
+fmt:
+    @echo "✨ Formatting code..."
+    cargo fmt
+
+# Install dependencies
+deps:
+    @echo "📦 Installing dependencies..."
+    cargo fetch
+
+# Show available tasks
+help:
+    @echo "Available tasks:"
+    @just --list
+```
+
+### Step 7: Create Local Justfile Tasks (Optional)
+
+Create `justfiles/base.just` for site-specific tasks:
+
+```just
+# Local base tasks for My Awesome Site
+
+# Custom deploy task
+deploy:
+    @echo "🚀 Deploying My Awesome Site..."
+    just build release
+    # Add your deployment commands here
+
+# Custom content tasks
+content-update:
+    @echo "📝 Updating content..."
+    # Add content management commands here
+
+# Custom asset processing
+assets-build:
+    @echo "🎨 Processing assets..."
+    # Add asset processing commands here
+```
+
+### Step 8: Run Your Site
+
+```bash
+# Run development server
+just dev
+
+# Or run directly with cargo
+cargo run --bin server
+
+# Visit http://127.0.0.1:3030
+```
+
+## 🔧 Customization Options
+
+### Enable Framework Features
+
+Uncomment features in `Cargo.toml` as needed:
+
+```toml
+# Enable authentication
+rustelo-auth = { path = "../rustelo/crates/rustelo-auth" }
+
+# Enable content management  
+rustelo-content = { path = "../rustelo/crates/rustelo-content" }
+
+[features]
+auth = ["rustelo-auth"]
+content = ["rustelo-content"]
+database = ["rustelo-core/database"]
+```
+
+### Asset Fallback System
+
+1. **Local Assets**: Place in `assets/` - highest priority
+2. **Framework Assets**: Automatic fallback to framework assets
+3. **Generated Assets**: Created by build system if needed
+
+### Override Framework Justfile Tasks
+
+Create `justfiles/base.just` with your custom tasks to override framework defaults.
+
+## 📁 Final Project Structure
+
+```
+my-awesome-site/
+├── Cargo.toml              # Dependencies and configuration
+├── rustelo.toml            # Framework configuration (optional)
+├── justfile                # Task runner with framework fallback
+├── src/
+│   └── main.rs             # Main application
+├── justfiles/              # Local task overrides
+│   └── base.just           # Custom tasks
+├── assets/                 # Local assets (override framework)
+├── content/                # Site content
+├── config/                 # Configuration files
+├── public/                 # Static public files
+└── target/                 # Build output
+```
+
+## 🚀 Next Steps
+
+1. **Add Content**: Create pages in `src/` or use `rustelo-content` crate
+2. **Style Your Site**: Add CSS in `assets/` or `public/`
+3. **Enable Features**: Add authentication, database, etc.
+4. **Deploy**: Use `just deploy` or your preferred deployment method
+5. **Update Framework**: `cargo update` gets latest framework versions
+
+## ✨ Benefits Achieved
+
+- ✅ **No fork required** - Pure dependency usage
+- ✅ **Framework updates** - Automatic via `cargo update`
+- ✅ **Local customization** - Override any framework asset
+- ✅ **Asset fallback** - Local → Framework → Generated
+- ✅ **Modular features** - Enable only what you need
+- ✅ **Production ready** - Optimized builds and deployment
+
+This approach ensures you have a maintainable, updatable website that leverages the Rustelo framework without becoming dependent on a fork!

docs/howto/using-cargo-rustelo.md

@@ -0,0 +1,323 @@
+# Using Cargo Rustelo - The Easy Way
+
+Rustelo provides a powerful Cargo subcommand that makes creating and managing Rustelo sites incredibly simple.
+
+## 🚀 Installation
+
+Install Rustelo CLI as a Cargo subcommand:
+
+```bash
+# Install from local development
+cargo install --path rustelo/crates/rustelo-cli
+
+# Or install from crates.io (when published)
+cargo install cargo-rustelo
+```
+
+## 🎯 Quick Start - 30 Seconds to a Working Site
+
+```bash
+# 1. Create a new site (does everything automatically!)
+cargo rustelo init my-awesome-site
+
+# 2. Navigate to the project
+cd my-awesome-site  
+
+# 3. Start development server
+cargo rustelo dev
+
+# 4. Visit http://127.0.0.1:3030 🎉
+```
+
+That's it! You have a fully functional Rustelo site with:
+- ✅ Framework-as-dependency architecture
+- ✅ Asset fallback system (Local → Framework → Generated)
+- ✅ Complete project structure
+- ✅ Development server with hot reload
+- ✅ Production build configuration
+
+## 📋 Available Commands
+
+### **Project Management**
+
+#### **`cargo rustelo init <name>`** - Create New Site
+Creates a complete Rustelo implementation with all necessary files.
+
+```bash
+# Basic usage
+cargo rustelo init my-site
+
+# With custom path
+cargo rustelo init my-blog --path ./sites/my-blog
+
+# With different template
+cargo rustelo init my-app --template advanced
+```
+
+**What it creates:**
+- Complete `Cargo.toml` with framework dependencies
+- Main application file with working examples  
+- Asset directories and configuration
+- Justfile with framework fallbacks
+- Leptos configuration for development
+- All directory structure needed
+
+#### **`cargo rustelo dev`** - Development Server
+Starts development server with hot reload and asset watching.
+
+```bash
+# Start server on default port (3030)
+cargo rustelo dev
+
+# Custom port
+cargo rustelo dev --port 8080
+
+# Enable file watching (default)
+cargo rustelo dev --watch
+```
+
+#### **`cargo rustelo build`** - Production Build
+Builds optimized production version with asset resolution.
+
+```bash
+# Production build
+cargo rustelo build --release
+
+# Development build with assets
+cargo rustelo build
+
+# Skip asset processing
+cargo rustelo build --no-assets
+
+# Build specific asset categories only
+cargo rustelo build --categories static,content
+
+# Organize assets by category in output
+cargo rustelo build --organize-by-category
+```
+
+#### **`cargo rustelo update`** - Framework Updates
+Updates framework version while preserving local customizations.
+
+```bash
+# Update to latest version
+cargo rustelo update
+
+# Update to specific version
+cargo rustelo update 1.2.3
+
+# Force update (overwrites conflicts)
+cargo rustelo update --force
+```
+
+### **Asset Management**
+
+#### **`cargo rustelo assets list`** - View Assets
+Shows all available assets and their resolution paths.
+
+```bash
+# List all assets
+cargo rustelo assets list
+
+# Filter by category
+cargo rustelo assets list --categories static,content
+
+# Show category statistics
+cargo rustelo assets list --stats
+```
+
+#### **`cargo rustelo assets check`** - Asset Conflicts
+Checks for conflicts between local and framework assets.
+
+```bash
+# Check all assets
+cargo rustelo assets check
+
+# Check specific categories
+cargo rustelo assets check --categories config
+```
+
+#### **`cargo rustelo assets resolve <path>`** - Asset Resolution
+Shows exactly where a specific asset resolves to.
+
+```bash
+# Resolve specific asset
+cargo rustelo assets resolve styles/main.css
+
+# Shows: Local → Framework → Generated priority
+```
+
+#### **`cargo rustelo assets organize`** - Organize Assets
+Organizes assets by category in target directory.
+
+```bash
+# Organize all assets
+cargo rustelo assets organize ./organized-assets
+
+# Organize specific categories
+cargo rustelo assets organize ./dist --categories static,content
+```
+
+### **Build Pipeline**
+
+#### **`cargo rustelo pipeline init`** - Setup Build Pipeline
+Initializes advanced build pipeline configuration.
+
+```bash
+# Initialize pipeline config
+cargo rustelo pipeline init
+
+# Force overwrite existing config
+cargo rustelo pipeline init --force
+```
+
+#### **`cargo rustelo pipeline targets`** - List Build Targets
+Shows all available build targets (dev, prod, cross-linux, etc.).
+
+#### **`cargo rustelo pipeline run <target>`** - Run Build Target  
+Executes specific build target with hooks and asset processing.
+
+```bash
+# Run production build target
+cargo rustelo pipeline run prod
+
+# Run with custom variables
+cargo rustelo pipeline run dev --vars debug=true,mode=development
+```
+
+### **Cross-Compilation** (for CI/CD)
+
+#### **`cargo rustelo cross init`** - Setup Cross-Compilation
+Configures Docker-based cross-compilation for building Linux binaries on macOS.
+
+```bash
+# Initialize cross-compilation
+cargo rustelo cross init
+
+# Custom target and image
+cargo rustelo cross init --target x86_64-unknown-linux-gnu --image rust:latest
+
+# Force overwrite existing config
+cargo rustelo cross init --force
+```
+
+#### **`cargo rustelo cross build`** - Cross-Compile
+Builds application for Linux using Docker containers.
+
+```bash
+# Build for Linux (production)
+cargo rustelo cross build
+
+# Development build
+cargo rustelo cross build --mode dev
+
+# Custom target
+cargo rustelo cross build --target aarch64-unknown-linux-gnu
+
+# Verbose output
+cargo rustelo cross build --verbose
+
+# Skip Docker image build if exists
+cargo rustelo cross build --skip-image-build
+```
+
+#### **`cargo rustelo cross test`** - Cross-Platform Testing
+Runs tests in cross-compilation environment.
+
+```bash
+# Run tests in Linux container
+cargo rustelo cross test
+
+# Test specific target
+cargo rustelo cross test --target x86_64-unknown-linux-gnu
+```
+
+## 🎯 Common Workflows
+
+### **Starting a New Project**
+```bash
+cargo rustelo init my-site
+cd my-site
+cargo rustelo dev
+```
+
+### **Adding Features**
+```bash
+# Check available assets
+cargo rustelo assets list
+
+# Check what gets overridden
+cargo rustelo assets check
+
+# Build with specific features
+cargo rustelo build --categories auth,content
+```
+
+### **Production Deployment**
+```bash
+# Build optimized version
+cargo rustelo build --release --organize-by-category
+
+# Or use build pipeline
+cargo rustelo pipeline run prod
+
+# For Linux servers (from macOS)
+cargo rustelo cross build --mode release
+```
+
+### **Framework Updates**
+```bash
+# Update framework dependencies
+cargo rustelo update
+
+# Check if any assets need attention
+cargo rustelo assets check
+
+# Rebuild with new framework version
+cargo rustelo build
+```
+
+## ✨ Benefits Over Manual Setup
+
+| **Aspect** | **Manual Setup** | **`cargo rustelo init`** |
+|------------|------------------|--------------------------|
+| **Time** | 30+ minutes | 30 seconds |
+| **Files Created** | 8+ files manually | Everything automated |
+| **Configuration** | Error-prone manual config | Perfect config every time |
+| **Dependencies** | Must know exact versions | Latest compatible versions |
+| **Asset System** | Must understand fallback logic | Working out of the box |
+| **Leptos Config** | Complex metadata setup | Configured automatically |
+| **Framework Updates** | Manual dependency management | `cargo rustelo update` |
+
+## 🔄 Typical Development Cycle
+
+```bash
+# 1. Create project
+cargo rustelo init my-project && cd my-project
+
+# 2. Development with hot reload
+cargo rustelo dev
+
+# 3. Check assets and build
+cargo rustelo assets list
+cargo rustelo build
+
+# 4. Update framework when needed  
+cargo rustelo update
+
+# 5. Deploy to production
+cargo rustelo cross build  # For Linux servers
+```
+
+## 🎉 Result
+
+With `cargo rustelo`, you get a **true framework-as-dependency architecture** with:
+
+- ✅ **No forking required** - Pure dependency usage
+- ✅ **30-second setup** - From zero to working site instantly  
+- ✅ **Asset fallback system** - Local overrides work automatically
+- ✅ **Framework updates** - `cargo rustelo update` gets latest features
+- ✅ **Professional tooling** - All the power, none of the complexity
+- ✅ **Production ready** - Optimized builds, cross-compilation, CI/CD support
+
+**This is exactly what modern framework tooling should be!** 🚀