#209 Apps: Write comprehensive documentation guide

## Parent Epic: #195 ## Description Write comprehensive 'How to Write Apps' documentation. ## Location docs/tutorials/how-to-write-apps.md ## Document Structure ### 1. Introduction - What are Highway Apps? - Why use apps vs built-in tools? - App capabilities overview ### 2. Quick Start - Prerequisites - Create your first app (Hello World) - Register via API - Install to tenant - Use in workflow ### 3. App SDK Reference #### AppContext API - checkpoint() - get_config() - get_secret() - http_request() - emit_event() - wait_for_event() - sleep() - get_state() / set_state() - Logging methods #### App Base Class - Required attributes - Optional attributes - @action decorator - Action parameters/returns schemas ### 4. Building Apps #### Simple Actions - Return values - Error handling - Logging best practices #### Idempotent Actions (Checkpoints) - When to use checkpoints - Checkpoint naming - Testing replay behavior #### External API Integration - HTTP requests - Circuit breaker behavior - Handling failures #### Event-Driven Actions - Emitting events - Waiting for events - Timeout handling #### Configuration - Configuration schema - Accessing config values - Default values #### Secrets Management - Declaring required secrets - Accessing secrets - Security best practices ### 5. Testing Your App #### Using AppSandbox - Basic testing - Mocking HTTP - Testing checkpoints - Testing events #### API Testing Endpoint - POST /api/v1/apps/{id}/test ### 6. Publishing Your App #### Registration Process - API endpoints - Version management - Semantic versioning #### Visibility Options - Private - Tenant - Public (marketplace) ### 7. Best Practices - Naming conventions - Error handling - Performance considerations - Security guidelines ### 8. Examples - Hello World (simple) - HTTP API integration - Event-driven workflow - Notification hub (complex) ### 9. Troubleshooting - Common errors - Debugging tips - Logs and monitoring ## Additional Files - docs/api/apps.md - API reference - docs/architecture/APP_SYSTEM_DESIGN.md - Technical design ## Requirements - Clear, concise writing - Code examples tested - Screenshots where helpful