docs: update installation instructions and enhance access control tests

Author: hardbyte

docs/contributing.md

@@ -8,18 +8,31 @@ Welcome to the python-common-expression-language development guide! This documen
 
 This Python package provides bindings for Google's Common Expression Language (CEL) using a Rust backend:
 
-```
-┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
-│   Python API   │───▶│   Rust Wrapper   │───▶│   cel crate     │
-│                 │    │     (PyO3)       │    │   (upstream)    │
-├─────────────────┤    ├──────────────────┤    ├─────────────────┤
-│ • cel.evaluate  │    │ • Type conversion│    │ • CEL parser    │
-│ • Context class │    │ • Error handling │    │ • Expression    │
-│ • CLI tool      │    │ • Function calls │    │   evaluation    │
-└─────────────────┘    └──────────────────┘    └─────────────────┘
+```mermaid
+%%{init: {"flowchart": {"padding": 20}}}%%
+flowchart LR
+    subgraph Python["  🐍 Python Layer  "]
+        API["&nbsp;&nbsp;cel.evaluate()<br/>&nbsp;&nbsp;Context class<br/>&nbsp;&nbsp;CLI tool&nbsp;&nbsp;"]
+    end
+    
+    subgraph Rust["&nbsp;&nbsp;🦀 Rust Wrapper (PyO3)&nbsp;&nbsp;"]
+        Wrapper["&nbsp;&nbsp;Type conversion<br/>&nbsp;&nbsp;Error handling<br/>&nbsp;&nbsp;Function calls&nbsp;&nbsp;"]
+    end
+    
+    subgraph CEL["&nbsp;&nbsp;⚡ CEL Engine (upstream)&nbsp;&nbsp;"]
+        Engine["&nbsp;&nbsp;CEL parser<br/>&nbsp;&nbsp;Expression evaluation<br/>&nbsp;&nbsp;Built-in functions&nbsp;&nbsp;"]
+    end
+    
+    Python --> Rust
+    Rust --> CEL
+    
+    style Python fill:#e8f4f8,color:#2c3e50
+    style Rust fill:#fdf2e9,color:#2c3e50  
+    style CEL fill:#f0f9ff,color:#2c3e50
 ```
 
 **Key Files:**
+
 - `src/lib.rs` - Main evaluation engine and type conversions
 - `src/context.rs` - Context management and Python function integration  
 - `python/cel/` - Python module structure and CLI
@@ -85,12 +98,6 @@ uv run pytest tests/test_upstream_improvements.py  # Future compatibility
 uv run pytest --cov=cel
 ```
 
-**Test Categories:**
-- **Basic Operations** (42 tests) - Core CEL evaluation
-- **Arithmetic** (31 tests) - Math operations and mixed types
-- **Type Conversion** (23 tests) - Python ↔ CEL type mapping
-- **Context Management** (11 tests) - Variables and functions
-- **Upstream Detection** (26 tests) - Future compatibility monitoring
 
 ## Upstream Compatibility Strategy
 
@@ -160,12 +167,6 @@ When updating the `cel` crate dependency:
 5. **Update documentation** to reflect new features
 6. **Test thoroughly** to ensure no regressions
 
-Example recent upgrade (cel-interpreter 0.10.0 → cel 0.11.0):
-- Crate was renamed from `cel-interpreter` to `cel`
-- Function registration API completely changed (new `IntoFunction` trait)
-- All Python API remained backward compatible
-- 287 tests continued passing after migration
-
 ## Code Style & Conventions
 
 ### Rust Code
@@ -209,76 +210,6 @@ def add_function(self, name: str, func: Callable) -> None:
     """
 ```
 
-### Testing Conventions
-
-```python
-import pytest
-import cel
-
-class TestFeatureCategory:
-    """Test [specific feature] with [scope] coverage."""
-    
-    def test_specific_behavior(self):
-        """Test [what] [under what conditions]."""
-        # Arrange
-        context = {"key": "value"}
-        
-        # Act  
-        result = cel.evaluate("key", context)
-        
-        # Assert
-        assert result == "value"
-        
-    def test_error_condition(self):
-        """Test that [condition] raises [exception type]."""
-        with pytest.raises(RuntimeError, match="Undefined variable"):
-            cel.evaluate("undefined_variable")
-```
-
-## Contributing Guidelines
-
-### Development Process
-
-1. **Issue Discussion** - Open an issue to discuss significant changes
-2. **Branch Creation** - Create feature branch from main
-3. **Implementation** - Follow code style and add tests
-4. **Testing** - Ensure all tests pass (`uv run pytest`)
-5. **Documentation** - Update docs for user-facing changes
-6. **Pull Request** - Submit with clear description and examples
-
-### What We're Looking For
-
-**High Priority Contributions:**
-- **Enhanced error handling** - Better Python exception mapping
-- **Performance improvements** - Optimization of type conversions
-- **Local utility functions** - Python implementations of missing CEL functions
-- **Documentation improvements** - Examples, guides, edge cases
-
-**Upstream Contributions (cel crate):**
-- **String utilities** - `lowerAscii`, `upperAscii`, `indexOf`, etc.
-- **Type introspection** - `type()` function implementation  
-- **Mixed arithmetic** - Better signed/unsigned integer support
-- **CEL spec compliance** - OR operator boolean return values
-
-### Testing Requirements
-
-All contributions must include:
-- **Unit tests** for new functionality
-- **Integration tests** for user-facing features  
-- **Error condition tests** for edge cases
-- **Documentation tests** for examples in docs
-
-```bash
-# Full test suite (required before PR)
-uv run pytest
-
-# Documentation examples (must pass)
-uv run --group docs pytest tests/test_docs.py
-
-# Upstream compatibility (monitoring)
-uv run pytest tests/test_upstream_improvements.py
-```
-
 ## Debugging & Troubleshooting
 
 ### Common Issues
@@ -321,28 +252,6 @@ uv run pytest --profile tests/test_performance.py
 ## Release Process
 
 1. **Version Bump** - Update version in `pyproject.toml`
-2. **Changelog** - Document changes in `CHANGELOG.md`  
-3. **Testing** - Full test suite across Python versions
-4. **Documentation** - Update any version-specific docs
-5. **Release** - Tag and publish to PyPI via CI
-
-## Resources
-
-### Documentation
-- **User Docs**: https://python-common-expression-language.readthedocs.io/
-- **CEL Specification**: https://github.com/google/cel-spec
-- **cel crate**: https://docs.rs/cel/latest/cel/
-
-### Development Tools
-- **PyO3 Guide**: https://pyo3.rs/
-- **maturin**: https://www.maturin.rs/
-- **Rust Book**: https://doc.rust-lang.org/book/
-
-### Community
-- **Issues**: https://github.com/hardbyte/python-common-expression-language/issues
-- **Discussions**: Use GitHub Discussions for questions and ideas
-- **CEL Community**: https://github.com/google/cel-spec/discussions
-
----
+2. **Changelog** - Document changes in `CHANGELOG.md`
+3. **Release** - Create a release in GitHub to trigger publishing to PyPI
 
-Thank you for contributing to python-common-expression-language! Your efforts help provide a robust, performant CEL implementation for the Python ecosystem.

docs/getting-started/installation.md

@@ -9,26 +9,27 @@ Getting Python CEL up and running is quick and easy.
 
 ## Install from PyPI
 
-=== "pip"
+=== "uv"
 
     ```bash
-    pip install common-expression-language
+    uv add common-expression-language
     ```
 
-=== "uv"
+=== "uv tool (CLI only)"
 
+    Install the CLI tool globally:
+    
     ```bash
-    uv add common-expression-language
+    uv tool install common-expression-language
     ```
 
-=== "pipx (CLI only)"
+=== "pip"
 
-    If you only want the CLI tool:
-    
     ```bash
-    pipx install common-expression-language
+    pip install common-expression-language
     ```
 
+
 ## Verify Installation
 
 After installation, you should have both the Python library and CLI tool available:

docs/how-to-guides/access-control-policies.md

@@ -126,10 +126,40 @@ def check_hierarchical_access(user, resource, action):
         "user": {**user, "role_level": role_hierarchy.get(user["role"], 0)},
         "resource": resource,
         "action": action,
-        "required_level": 1  # Minimum level to access system
+        "required_level": 0  # Minimum level to access system
     }
 
     return evaluate(policy, context)
+
+# Test the hierarchical access control
+guest_user = {"role": "guest", "id": "guest1"}
+user_account = {"role": "user", "id": "user1"}
+manager_account = {"role": "manager", "id": "mgr1"}
+
+public_resource = {"public": True, "owner": "admin", "collaborators": []}
+private_resource = {"public": False, "owner": "user1", "collaborators": ["guest1"]}
+
+# Test 1: Guest accessing public resource
+result = check_hierarchical_access(guest_user, public_resource, "read")
+assert result == True, "Guest should access public resource"
+
+# Test 2: Guest accessing private resource (denied)  
+result = check_hierarchical_access(guest_user, private_resource, "write")
+assert result == False, "Guest should not write to private resource"
+
+# Test 3: User accessing owned resource
+result = check_hierarchical_access(user_account, private_resource, "write")
+assert result == True, "User should access owned resource"
+
+# Test 4: Manager can delete (role_level >= 3)
+result = check_hierarchical_access(manager_account, private_resource, "delete")
+assert result == True, "Manager should delete any resource"
+
+# Test 5: Guest as collaborator can read
+result = check_hierarchical_access(guest_user, private_resource, "read")
+assert result == True, "Guest collaborator should read resource"
+
+print("✓ Hierarchical access control working correctly")
 ```
 
 ### Time-Based Access
@@ -162,6 +192,33 @@ def check_time_based_access(user, resource, action, current_time=None):
     }
 
     return evaluate(policy, context)
+
+# Test time-based access control
+standard_user = {"role": "user", "schedule": "standard"}
+flexible_user = {"role": "user", "schedule": "flexible"}
+admin_user = {"role": "admin", "schedule": "standard"}
+test_resource = {"id": "test_doc"}
+
+# Test 1: Standard user during business hours
+business_time = datetime.now().replace(hour=14)  # 2 PM
+result = check_time_based_access(standard_user, test_resource, "read", business_time)
+assert result == True, "Standard user should access during business hours"
+
+# Test 2: Standard user after hours (denied)
+after_hours = datetime.now().replace(hour=22)  # 10 PM
+result = check_time_based_access(standard_user, test_resource, "read", after_hours)
+assert result == False, "Standard user should be denied after hours"
+
+# Test 3: Flexible user during extended hours
+result = check_time_based_access(flexible_user, test_resource, "read", after_hours)
+assert result == True, "Flexible user should access during extended hours"
+
+# Test 4: Admin always has access
+early_morning = datetime.now().replace(hour=5)  # 5 AM
+result = check_time_based_access(admin_user, test_resource, "read", early_morning)
+assert result == True, "Admin should always have access"
+
+print("✓ Time-based access control working correctly")
 ```
 
 ### Resource-Specific Policies
@@ -200,6 +257,42 @@ def check_resource_specific_access(user, resource, action):
     }
 
     return evaluate(policy, context)
+
+# Test resource-specific access control
+developer = {"role": "developer", "id": "dev1"}
+analyst = {"role": "analyst", "id": "analyst1"}
+operator = {"role": "operator", "id": "ops1"}
+
+document_resource = {"type": "document", "owner": "dev1", "public": False, "collaborators": ["analyst1"]}
+database_resource = {"type": "database", "name": "prod_db"}
+system_resource = {"type": "system", "name": "web_server"}
+
+# Test 1: Developer with database (can read/write)
+result = check_resource_specific_access(developer, database_resource, "write")
+assert result == True, "Developer should write to database"
+
+result = check_resource_specific_access(developer, database_resource, "read")
+assert result == True, "Developer should read database"
+
+# Test 2: Analyst with database (read-only)
+result = check_resource_specific_access(analyst, database_resource, "read")
+assert result == True, "Analyst should read database"
+
+result = check_resource_specific_access(analyst, database_resource, "write")
+assert result == False, "Analyst should not write to database"
+
+# Test 3: Operator with system (can read/restart)
+result = check_resource_specific_access(operator, system_resource, "restart")
+assert result == True, "Operator should restart system"
+
+# Test 4: Analyst as document collaborator
+result = check_resource_specific_access(analyst, document_resource, "read")
+assert result == True, "Analyst collaborator should read document"
+
+result = check_resource_specific_access(analyst, document_resource, "write")
+assert result == False, "Analyst collaborator should not write document"
+
+print("✓ Resource-specific access control working correctly")
 ```
 
 ## Kubernetes Validation Rules