Add comprehensive architectural documentation and developer guidelines

- Add CLAUDE.md with project overview and key commands for AI assistance
- Create docs/architecture/ with detailed architectural analysis:
  * ARCHITECTURAL_PATTERNS.md: 16 design patterns, anti-patterns, and 15 improvement suggestions
  * LOGGING_ARCHITECTURE.md: Analysis of sophisticated dual logging system (Log() vs Term())
  * PLUGIN_SYSTEM.md: Complete plugin architecture guide with examples
  * SERVICE_SYSTEM.md: Service-oriented design and dependency injection documentation
- Add comprehensive DEVELOPER_GUIDELINES.md covering:
  * Code style and conventions
  * Architecture guidelines and best practices
  * Logging guidelines for dual system usage
  * Plugin and service development guides
  * Testing, error handling, and performance considerations
- Update docs/README.md with improved organization and navigation

Total: 1,915 lines of comprehensive documentation covering system architecture,
development practices, and contribution guidelines.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: andypost

CLAUDE.md

@@ -0,0 +1,78 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Build and Development
+- `make` - Build the launchr binary to `bin/launchr`
+- `make DEBUG=1` - Build with debug symbols for use with dlv debugger
+- `make deps` - Fetch go dependencies
+- `make test` - Run all tests
+- `make lint` - Run golangci-lint with fixes
+- `make install` - Install globally to `$GOPATH/bin`
+- `go generate ./...` - Generate code (runs as part of build)
+
+### Usage
+- `bin/launchr --help` - Show help
+- `bin/launchr --version` - Show version
+- `bin/launchr build` - Build custom launchr with plugins
+
+## Architecture Overview
+
+Launchr is a CLI action runner that executes tasks defined in YAML files across multiple runtimes (containers, shell, plugins). The architecture is built around several core patterns:
+
+### Core Systems
+
+**Plugin Architecture**: Weight-based plugin system where plugins register via `init()` functions and implement lifecycle interfaces like `OnAppInitPlugin`, `CobraPlugin`, `DiscoveryPlugin`. Plugins are registered globally through `launchr.RegisterPlugin()`.
+
+**Service-Oriented Design**: Core services (Config, Manager, PluginManager) are registered and retrieved through dependency injection via `App.AddService()` and `App.GetService()`. All services implement the `Service` interface.
+
+**Runtime Strategy Pattern**: Multiple runtime implementations (shell, container, plugin) that implement the `Runtime` interface with `Init()`, `Execute()`, `Close()`, `Clone()` methods.
+
+### Key Components
+
+- **Action System** (`pkg/action/`): Core action entity with manager handling lifecycle, discovery, validation, and execution
+- **Runtime System**: Shell, Container (Docker/K8s), and Plugin runtime implementations  
+- **Discovery System**: YAML and embedded filesystem action discovery with extensible discovery plugins
+- **Configuration System**: YAML-based config with dot-notation access and reflection-based caching
+- **Plugin System** (`plugins/`): Core plugins for naming, CLI integration, discovery, value processing, and verbosity
+
+### Important Interfaces
+
+- `App`: Global application state management
+- `Plugin`: Base plugin interface with `PluginInfo()` and lifecycle hooks
+- `Service`: Dependency injection with `ServiceInfo()`
+- `Runtime`: Action execution environment abstraction
+- `Manager`: Action management and orchestration
+
+### Key Files
+
+- `app.go`: Main application implementation with plugin and service management
+- `types.go`: Type aliases to reduce external dependencies
+- `pkg/action/manager.go`: Action lifecycle management
+- `pkg/action/action.go`: Core action entity
+- `internal/launchr/config.go`: Configuration system
+- `plugins/default.go`: Plugin registration
+
+### Development Patterns
+
+- Type aliases in `types.go` for clean interfaces
+- Error handling with custom types and `errors.Is()` support
+- Go template integration for dynamic action configuration
+- Mutex-protected operations for concurrency safety
+- `fs.FS` interface for filesystem abstraction
+- JSON Schema validation for inputs and configuration
+
+### Execution Flow
+
+1. Plugin registration and service initialization
+2. Action discovery through registered discovery plugins
+3. Cobra command generation from discovered actions
+4. Multi-stage input validation (runtime flags, persistent flags, action parameters)
+5. Runtime-specific execution with cleanup
+6. Support for async action execution with status tracking
+
+### Environment Variables
+
+- `LAUNCHR_ACTIONS_PATH`: Path for action discovery (default: current directory)