feat: enhance logging and documentation

- Add HelmLogger class diagram to low-level design
- Add logging system documentation
- Create ADR index page for better navigation
- Fix PathData and Value test cases
- Update tasks.md to mark logging implementation complete

Author: ritwik-g

.gitignore

@@ -184,3 +184,6 @@ bin/
 .DS_Store
 .AppleDouble
 .LSOverride
+
+# windsurf rules
+.windsurfrules

docs/ADRs/006-helm-style-logging.md

@@ -0,0 +1,125 @@
+# ADR-006: Helm-Style Logging System
+
+## Status
+Accepted
+
+## Context
+As a Helm plugin, our application needs to follow Helm's logging conventions for consistency and user experience. Key considerations include:
+
+1. Debug output control via environment variables
+2. Error message formatting
+3. Performance in logging operations
+4. Integration with Helm's output conventions
+5. Testing and verification of log output
+
+## Decision
+
+### 1. Implement HelmLogger Class
+Create a dedicated logger class that follows Helm plugin conventions:
+
+```python
+class HelmLogger:
+    @staticmethod
+    def debug(msg: str, *args: Any) -> None:
+        if os.environ.get('HELM_DEBUG'):
+            if args:
+                msg = msg % args
+            print("[debug] %s" % msg, file=sys.stderr)
+
+    @staticmethod
+    def error(msg: str, *args: Any) -> None:
+        if args:
+            msg = msg % args
+        print("Error: %s" % msg, file=sys.stderr)
+```
+
+### 2. Key Design Decisions
+
+1. **Helm Convention Compliance**
+   - Use stderr for all output
+   - Prefix debug messages with "[debug]"
+   - Prefix error messages with "Error:"
+   - Control debug output via HELM_DEBUG environment variable
+
+2. **Performance Optimization**
+   - Use string formatting instead of f-strings for consistent behavior
+   - Lazy evaluation of debug messages
+   - No string concatenation in critical paths
+
+3. **Global Instance Pattern**
+   - Provide a global logger instance
+   - Enable consistent logging across the codebase
+   - Avoid passing logger instances
+
+4. **Testing Support**
+   - Mockable stderr for testing
+   - Environment variable control in tests
+   - String format verification
+
+### 3. Usage Pattern
+```python
+from helm_values_manager.utils.logger import logger
+
+def some_function():
+    logger.debug("Processing %s", value)
+    try:
+        # do something
+        logger.debug("Success!")
+    except Exception as e:
+        logger.error("Failed: %s", str(e))
+```
+
+## Consequences
+
+### Positive
+1. **Consistent User Experience**
+   - Matches Helm's output format
+   - Familiar debug control mechanism
+   - Clear error messages
+
+2. **Performance**
+   - Efficient string formatting
+   - Debug messages skipped when disabled
+   - Minimal memory overhead
+
+3. **Maintainability**
+   - Centralized logging logic
+   - Easy to modify output format
+   - Simple testing approach
+
+4. **Debugging**
+   - Clear debug output control
+   - Consistent message format
+   - Environment-based control
+
+### Negative
+1. **Limited Flexibility**
+   - Fixed output format
+   - No log levels beyond debug/error
+   - No log file support
+
+2. **Global State**
+   - Global logger instance
+   - Potential for test interference
+   - Need careful test isolation
+
+## Implementation Notes
+
+1. **Testing**
+```python
+def test_debug_output():
+    stderr = StringIO()
+    with mock.patch.dict(os.environ, {'HELM_DEBUG': '1'}), \
+         mock.patch('helm_values_manager.utils.logger.sys.stderr', stderr):
+        logger.debug("Test message")
+        assert stderr.getvalue() == "[debug] Test message\n"
+```
+
+2. **Integration**
+```python
+# In PathData class
+def validate(self):
+    logger.debug("Validating PathData for path: %s", self.path)
+    if not self.is_valid():
+        logger.error("Invalid PathData: %s", self.path)
+```

docs/ADRs/README.md

@@ -0,0 +1,67 @@
+# Architecture Decision Records (ADRs)
+
+This directory contains Architecture Decision Records (ADRs) for the Helm Values Manager project.
+
+## What is an ADR?
+An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences.
+
+## ADR Index
+
+### [ADR-001: Helm Values Manager as a Helm Plugin](001-helm-values-manager.md)
+- **Status**: Accepted
+- **Context**: Need for managing configurations and secrets across multiple Kubernetes deployments
+- **Decision**: Implement as a Helm plugin in Python with key-value storage model
+- **Impact**: Defines core architecture and integration approach
+
+### [ADR-002: Config Path and Storage Design](002-config-path-and-storage-design.md)
+- **Status**: Accepted
+- **Context**: Need for separate config definition from value storage
+- **Decision**: Implement path map and standardized command pattern
+- **Impact**: Establishes core data structures and file operations
+- **Dependencies**: ADR-001
+
+### [ADR-003: Unified Path and Value Storage](003-unified-path-value-storage.md)
+- **Status**: Accepted
+- **Context**: Complexity from separate path and value storage
+- **Decision**: Unified dictionary structure for paths and values
+- **Impact**: Simplifies storage and improves consistency
+- **Dependencies**: ADR-002
+
+### [ADR-004: Value Resolution Strategy](004-value-resolution-strategy.md)
+- **Status**: Accepted
+- **Context**: Need for clear value resolution in unified storage
+- **Decision**: Introduce Value class for encapsulation
+- **Impact**: Clarifies value handling and storage strategy
+- **Dependencies**: ADR-003
+
+### [ADR-005: Unified Backend Approach](005-unified-backend-approach.md)
+- **Status**: Proposed
+- **Context**: Split logic in Value class for different storage types
+- **Decision**: Remove storage type distinction, use SimpleValueBackend
+- **Impact**: Simplifies Value class and unifies storage interface
+- **Dependencies**: ADR-004
+
+### [ADR-006: Helm-Style Logging System](006-helm-style-logging.md)
+- **Status**: Accepted
+- **Context**: Need for consistent logging following Helm conventions
+- **Decision**: Implement HelmLogger with Helm-style output
+- **Impact**: Ensures consistent user experience and debugging
+- **Dependencies**: ADR-001
+
+## ADR Template
+For new ADRs, use this template:
+```markdown
+# ADR-NNN: Title
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded]
+
+## Context
+What is the issue that we're seeing that is motivating this decision or change?
+
+## Decision
+What is the change that we're proposing and/or doing?
+
+## Consequences
+What becomes easier or more difficult to do because of this change?
+```

docs/Design/low-level-design.md

@@ -21,8 +21,14 @@ classDiagram
     }
 
     class PathData {
+        +str path
         +Dict metadata
         +Dict~str,Value~ values
+        +validate() None
+        +add_value(environment: str, value: Value) None
+        +get_value(environment: str) Optional[Value]
+        +to_dict() Dict
+        +from_dict(data: Dict, create_value_fn) PathData
     }
 
     class Value {
@@ -85,6 +91,11 @@ classDiagram
         +validate_auth_config(auth_config: dict) None
     }
 
+    class HelmLogger {
+        +debug(msg: str, *args: Any) None
+        +error(msg: str, *args: Any) None
+    }
+
     HelmValuesConfig "1" *-- "*" ConfigValue
     HelmValuesConfig "1" *-- "*" Deployment
     HelmValuesConfig "1" *-- "*" PathData
@@ -99,32 +110,32 @@ classDiagram
 
 ### 2. Value Management
 
-The system uses a unified approach to value storage and resolution through the `Value` class:
+The system manages configuration values through a hierarchy of classes:
 
-```python
-class Value:
-    def __init__(self, path: str, environment: str,
-                 backend: ValueBackend):
-        self.path = path
-        self.environment = environment
-        self._backend = backend
-
-    def get(self) -> str:
-        """Get the resolved value"""
-        return self._backend.get_value(self.path, self.environment)
-
-    def set(self, value: str) -> None:
-        """Set the value"""
-        if not isinstance(value, str):
-            raise ValueError("Value must be a string")
-        self._backend.set_value(self.path, self.environment, value)
-```
+1. **HelmValuesConfig**
+   - Top-level configuration manager
+   - Maintains mapping of paths to PathData instances
+   - Handles backend selection based on value sensitivity
+   - Manages deployments and their configurations
+
+2. **PathData**
+   - Represents a single configuration path and its properties
+   - Owns the configuration path and ensures consistency
+   - Stores metadata (description, required status, sensitivity)
+   - Manages environment-specific values through Value instances
+   - Validates path consistency between itself and its Values
+   - Delegates actual value storage to Value instances
 
-Key features:
-- Encapsulated value resolution logic
-- Unified interface for all storage backends
+3. **Value**
+   - Handles actual value storage and retrieval
+   - Uses appropriate backend for storage operations
+   - Maintains reference to its path and environment
+
+This hierarchy ensures:
 - Clear separation of concerns
-- Type-safe value handling
+- Consistent path handling across the system
+- Proper validation at each level
+- Flexible backend selection based on value sensitivity
 
 ### 3. Command Pattern
 
@@ -249,6 +260,31 @@ The configuration follows the v1 schema:
    - Backup before writes
    - Atomic updates
 
+## Logging System
+
+The logging system follows Helm plugin conventions and provides consistent output formatting:
+
+1. **HelmLogger Class**
+   - Provides debug and error logging methods
+   - Follows Helm output conventions
+   - Uses stderr for all output
+   - Controls debug output via HELM_DEBUG environment variable
+
+2. **Global Logger Instance**
+   - Available via `from helm_values_manager.utils.logger import logger`
+   - Ensures consistent logging across all components
+   - Simplifies testing with mock support
+
+3. **Performance Features**
+   - Uses string formatting for efficiency
+   - Lazy evaluation of debug messages
+   - Minimal memory overhead
+
+4. **Testing Support**
+   - Mockable stderr output
+   - Environment variable control
+   - String format verification
+
 ## Benefits of This Design
 
 1. **Separation of Concerns**

docs/Development/tasks.md

@@ -22,14 +22,14 @@
   - [x] Add support for sensitive field handling
 
 ### PathData Class Implementation
-- [ ] Create PathData class
-  - [ ] Add metadata dictionary support
-  - [ ] Add values dictionary for Value objects
-  - [ ] Implement validation methods
-- [ ] Add serialization support
-  - [ ] Implement to_dict() method
-  - [ ] Implement from_dict() method
-  - [ ] Add tests for serialization
+- [x] Create PathData class
+  - [x] Add metadata dictionary support
+  - [x] Add values dictionary for Value objects
+  - [x] Implement validation methods
+- [x] Add serialization support
+  - [x] Implement to_dict() method
+  - [x] Implement from_dict() method
+  - [x] Add tests for serialization
 
 ### HelmValuesConfig Refactoring
 - [ ] Remove PlainTextBackend references
@@ -75,13 +75,13 @@
   - [ ] Add command-specific validation
 
 ### Testing Infrastructure
-- [ ] Set up test infrastructure
-  - [ ] Add pytest configuration
-  - [ ] Set up test fixtures
-  - [ ] Add mock backends for testing
-- [ ] Add unit tests
-  - [ ] Value class tests
-  - [ ] PathData class tests
+- [x] Set up test infrastructure
+  - [x] Add pytest configuration
+  - [x] Set up test fixtures
+  - [x] Add mock backends for testing
+- [x] Add unit tests
+  - [x] Value class tests
+  - [x] PathData class tests
   - [ ] HelmValuesConfig tests
   - [ ] Backend tests
   - [ ] Command tests
@@ -90,6 +90,22 @@
   - [ ] Backend integration tests
   - [ ] File operation tests
 
+### Logging System
+- [x] Implement Helm-style logger
+  - [x] Create HelmLogger class
+  - [x] Add debug and error methods
+  - [x] Follow Helm output conventions
+  - [x] Add HELM_DEBUG support
+- [x] Add comprehensive tests
+  - [x] Test debug output control
+  - [x] Test error formatting
+  - [x] Test string formatting
+  - [x] Test environment handling
+- [x] Update components to use logger
+  - [x] Update PathData class
+  - [x] Update Value class
+  - [x] Add logging documentation
+
 ### Documentation
 - [ ] Update API documentation
   - [ ] Document Value class