prod deploy

docs/development/frontend/storage.mdx

@@ -178,6 +178,11 @@ All storage keys should:
    - `form_draft`
    - `wizard_state`
 
+6. **User Onboarding**: `{feature}_completed` or `{feature}_cancelled`
+   - `walkthrough_completed`
+   - `tutorial_completed`
+   - `onboarding_skipped`
+
 ## Adding New Storage Values
 
 ### Step 1: Define Your Storage Key

docs/development/gateway/device-management.mdx

@@ -0,0 +1,178 @@
+---
+title: Device Management Architecture
+description: Technical implementation of device detection, caching, and management in the DeployStack Gateway CLI
+sidebar: Device Management
+---
+
+# Gateway Device Management Architecture
+
+The DeployStack Gateway implements a sophisticated device management system that balances security, performance, and user experience. This document explains the technical architecture, design decisions, and implementation details from a developer perspective.
+
+## Architecture Overview
+
+The Gateway's device management system consists of three core components:
+
+**Device Detection System**
+- Hardware fingerprinting for unique device identification
+- System information collection for compatibility and analytics
+- Lightweight signature generation for cache validation
+
+**Device Information Cache**
+- High-performance caching to eliminate redundant device detection
+- Secure storage using OS keychain with encrypted fallback
+- Integrity validation and automatic cache invalidation
+
+**OAuth2 Integration**
+- Device registration during authentication flow
+- Device information included in token exchange
+- No separate device management endpoints required
+
+## The Performance Problem We Solved
+
+### Original Challenge
+
+Before implementing device caching, every Gateway command suffered from a significant performance bottleneck:
+
+- **Device fingerprinting took 3+ seconds** on every command execution
+- Commands like `deploystack refresh` and `deploystack mcp` felt sluggish
+- Users experienced poor CLI responsiveness
+- System resources were wasted on redundant hardware detection
+
+### Root Cause Analysis
+
+Device fingerprinting is inherently expensive because it requires:
+- Network interface enumeration to collect MAC addresses
+- System information queries across multiple OS APIs
+- Cryptographic hashing of collected hardware data
+- File system operations to gather system details
+
+This expensive operation was happening on **every single command** because device information is required for:
+- Backend API authentication and device tracking
+- Security validation and audit logging
+- Configuration management and team analytics
+
+## Device Caching Architecture
+
+### Design Principles
+
+**Performance First**
+- Cache-first architecture with graceful fallback
+- 30x performance improvement (3s → 0.1s)
+- Persistent cache across logout/login sessions
+
+**Security Without Compromise**
+- Hardware signature validation for cache integrity
+- Automatic invalidation on hardware changes
+- Encrypted storage with integrity checksums
+
+**Developer Experience**
+- Completely transparent to end users
+- No manual cache management required
+- Automatic background operation
+
+### Cache Storage Strategy
+
+We implemented a dual-storage approach for maximum reliability:
+
+**Primary: OS Keychain Storage**
+- macOS: Keychain Services
+- Windows: Credential Manager  
+- Linux: Secret Service API
+- Benefits: Native OS security, encrypted at rest, user-scoped access
+
+**Fallback: Encrypted File Storage**
+- AES-256-GCM encryption with derived keys
+- Stored in `~/.deploystack/device-cache.enc`
+- File permissions restricted to user only (0o600)
+- Used when keychain access fails or is unavailable
+
+### Cache Validation System
+
+**Hardware Signature Validation**
+- Lightweight hardware signature (not full fingerprint)
+- Detects major hardware changes without expensive operations
+- Automatically invalidates cache when hardware changes detected
+
+**Integrity Protection**
+- SHA256 checksums with random salts prevent tampering
+- Cache version tracking for schema evolution
+- Automatic cleanup of corrupted or invalid cache entries
+
+**Time-Based Expiration**
+- 30-day cache lifetime for security
+- Automatic renewal during normal usage
+- Configurable expiration for different deployment scenarios
+
+## Device Detection Implementation
+
+### Hardware Fingerprinting Process
+
+**Network Interface Collection**
+- Enumerate all network interfaces
+- Extract MAC addresses from physical interfaces
+- Filter out virtual and temporary interfaces
+- Handle cross-platform interface naming differences
+
+**System Information Gathering**
+- Operating system type and version
+- System architecture (x64, arm64, etc.)
+- Hostname and system identifiers
+- Node.js runtime version for compatibility
+
+**Fingerprint Generation**
+- Combine hardware identifiers in deterministic order
+- Apply cryptographic hashing (SHA256)
+- Generate stable, unique device identifier
+- Ensure consistency across reboots and minor system changes
+
+### Lightweight Hardware Signatures
+
+For cache validation, we use a much faster "hardware signature" instead of full fingerprinting:
+
+**Why Separate Signatures?**
+- Full fingerprinting: 3+ seconds, comprehensive hardware analysis
+- Hardware signature: \<100ms, basic system identifiers
+- Signature detects major changes (new hardware, different machine)
+- Signature allows minor changes (software updates, network changes)
+
+**Signature Components**
+- Primary MAC address of main network interface
+- System hostname and basic OS identifiers
+- Minimal set of stable hardware characteristics
+- Fast to compute, sufficient for cache validation
+
+## Security Architecture
+
+### Threat Model Considerations
+
+**Cache Tampering Protection**
+- SHA256 checksums with random salts
+- Integrity validation on every cache access
+- Automatic invalidation of corrupted cache
+- Secure key derivation for encryption
+
+**Hardware Change Detection**
+- Automatic cache invalidation when hardware changes
+- Prevents cache reuse on different machines
+- Detects both major and minor hardware modifications
+- Balances security with usability
+
+**Storage Security**
+- OS keychain provides encrypted storage
+- Fallback encryption uses industry-standard AES-256-GCM
+- File permissions restrict access to user only
+- No plaintext device information stored
+
+### Privacy Considerations
+
+**Minimal Data Collection**
+- Only collect device information necessary for functionality
+- No tracking or analytics data in device cache
+- User control over device naming and identification
+- Clear data retention and cleanup policies
+
+**Data Isolation**
+- Device cache is user-scoped and isolated
+- No cross-user cache sharing or access
+- Secure cleanup when users are removed
+- Audit trail separate from cached data