awsquery 0.3.2__tar.gz → 0.4.0__tar.gz

{awsquery-0.3.2 → awsquery-0.4.0}/.claude/settings.local.json

@@ -3,7 +3,8 @@
     "allow": [
       "Bash(python3 -m pytest tests/ --cov=src/awsquery --cov-report=term-missing -q)",
       "Bash(mutmut show:*)",
-      "Bash(mutmut:*)"
+      "Bash(mutmut:*)",
+      "Bash(python3:*)"
     ],
     "deny": [],
     "ask": []

awsquery-0.4.0/CLAUDE.md

@@ -0,0 +1,281 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`awsquery` is an advanced CLI tool for querying AWS APIs through boto3 with flexible filtering, automatic parameter resolution, and comprehensive security validation. The tool enforces ReadOnly AWS operations for security and provides intelligent response processing with automatic field discovery.
+
+## Development Philosophy
+
+**CRITICAL: ZERO BACKWARD COMPATIBILITY REQUIREMENT**
+
+This project has **ZERO EXTERNAL CONSUMERS** and **NO BACKWARD COMPATIBILITY OBLIGATIONS**. Internal APIs can and should be changed aggressively for code quality improvements.
+
+**MANDATORY PRINCIPLES:**
+- **NEVER maintain backward compatibility** - there are no external users
+- **CLI commands must remain stable** - user-facing behavior should be consistent
+- **Internal APIs are completely mutable** - change function signatures, parameters, return types freely
+- **Delete deprecated code immediately** - no deprecation periods needed
+- **Refactor aggressively** - prioritize clean code over any compatibility concerns
+- **Break internal interfaces without hesitation** - improve designs whenever beneficial
+- **Update tests to match new APIs** - test failures from API changes should be fixed by updating tests
+
+**The only stability requirement is the CLI user experience. All internal code is fair game for radical changes.**
+
+## MANDATORY AGENT USAGE
+
+**ABSOLUTE REQUIREMENT: SPECIALIZED AGENTS MUST BE USED FOR ALL DEVELOPMENT TASKS**
+
+**ZERO TOLERANCE POLICY: MANUAL WORK IS CATEGORICALLY FORBIDDEN**
+
+### Test Development - MANDATORY @agent-test-writer Usage
+- **MUST USE @agent-test-writer** for ALL test creation, modification, and enhancement
+- **NEVER write tests manually** - always delegate to the specialized test-writer agent
+- **MANDATORY for:** Unit tests, integration tests, edge case testing, test refactoring
+- **REQUIRED PROCESS:** Always use test-driven development through the agent
+- **NO EXCEPTIONS:** Any test-related work MUST go through @agent-test-writer
+
+### Python Implementation - MANDATORY @agent-python-infra-automator Usage
+- **MUST USE @agent-python-infra-automator** for ALL Python code implementation
+- **NEVER implement Python code manually** - always delegate to the specialized Python agent
+- **MANDATORY for:** New features, bug fixes, refactoring, optimization, infrastructure code
+- **REQUIRED PROCESS:** Always implement through the specialized agent for best practices
+- **NO EXCEPTIONS:** Any Python development MUST go through @agent-python-infra-automator
+
+### Code Review - MANDATORY @agent-code-reviewer Usage
+- **MUST USE @agent-code-reviewer** AUTOMATICALLY after ANY significant code changes
+- **PROACTIVE REQUIREMENT:** Agent must be invoked WITHOUT user request after commits/merges
+- **MANDATORY for:** All code quality reviews, security analysis, maintainability checks
+- **AUTOMATIC TRIGGERS:** Post-commit, post-merge, after major refactoring
+- **NO EXCEPTIONS:** ALL code changes MUST be reviewed by the specialized agent
+
+### Makefile Operations - MANDATORY @agent-makefile-optimizer Usage
+- **MUST USE @agent-makefile-optimizer** for ANY Makefile-related work
+- **AUTOMATIC TRIGGER:** ANY interaction with Makefile, makefile, GNUmakefile, *.mk files
+- **MANDATORY for:** Build automation, make targets, build system optimization
+- **PROACTIVE REQUIREMENT:** Agent MUST be used automatically when detecting Makefile work
+- **NO EXCEPTIONS:** ALL build system work MUST go through the specialized agent
+
+### Configuration Management - MANDATORY @agent-statusline-setup Usage
+- **MUST USE @agent-statusline-setup** for Claude Code status line configuration
+- **MANDATORY for:** Status line settings, configuration management
+- **NO EXCEPTIONS:** Status line work MUST go through the specialized agent
+
+### Output Styling - MANDATORY @agent-output-style-setup Usage
+- **MUST USE @agent-output-style-setup** for Claude Code output style creation
+- **MANDATORY for:** Output formatting, style configuration
+- **NO EXCEPTIONS:** Output style work MUST go through the specialized agent
+
+### General Research - MANDATORY @agent-general-purpose Usage
+- **MUST USE @agent-general-purpose** for complex multi-step research tasks
+- **MANDATORY for:** Searching keywords/files, complex questions, multi-step tasks
+- **REQUIRED WHEN:** Not confident about finding right match in first few tries
+- **NO EXCEPTIONS:** Complex research MUST go through the specialized agent
+
+### Agent Usage Protocol - ABSOLUTE ENFORCEMENT
+1. **IDENTIFY TASK TYPE:** Determine which specialized agent is required
+2. **AUTOMATIC INVOCATION:** Many agents MUST be triggered proactively/automatically
+3. **PROVIDE COMPLETE CONTEXT:** Include all relevant information for the agent
+4. **FOLLOW AGENT RECOMMENDATIONS:** Implement exactly as specified by the agent
+5. **NO MANUAL OVERRIDE:** Trust the specialized agents completely
+6. **PARALLEL EXECUTION:** Use multiple agents concurrently when possible
+
+### PROACTIVE AGENT TRIGGERS - MANDATORY AUTOMATION
+- **@agent-code-reviewer:** AUTOMATICALLY after significant code changes
+- **@agent-makefile-optimizer:** AUTOMATICALLY when detecting Makefile work
+- **@agent-test-writer:** PROACTIVELY when functions/classes lack test coverage
+- **@agent-python-infra-automator:** PROACTIVELY for infrastructure automation needs
+
+**VIOLATION OF AGENT USAGE IS STRICTLY FORBIDDEN - ALL DEVELOPMENT MUST GO THROUGH SPECIALIZED AGENTS**
+**MANUAL IMPLEMENTATION IS CATEGORICALLY PROHIBITED - AGENTS ARE MANDATORY FOR ALL WORK**
+
+## Development Commands
+
+### Core Commands
+- `make install-dev` - Install development dependencies
+- `make test` - Run all tests (MANDATORY - NO SELECTIVE EXECUTION ALLOWED)
+- `make test-unit` - Run unit tests only (directory-based, not marker-based)
+- `make test-integration` - Run integration tests only (directory-based, not marker-based)
+- `make test-critical` - Run all tests (NO SELECTIVE MARKERS PERMITTED)
+- `make coverage` - Run tests with coverage report (generates htmlcov/index.html)
+- `python3 -m pytest tests/ -v` - Direct pytest execution (NEVER with -m markers)
+
+### Code Quality
+- `make lint` - Run linting checks (flake8, pylint)
+- `make format` - Format code with black and isort
+- `make format-check` - Check code formatting without changes
+- `make type-check` - Run mypy type checking
+- `make security-check` - Run security checks (bandit, safety)
+- `make pre-commit` - Run pre-commit hooks on all files
+
+### Docker Development
+- `make docker-build` - Build development container
+- `make shell` - Open interactive shell in container
+- `make test-in-docker` - Run tests in Docker container
+
+### Single Test Execution
+- `python3 -m pytest tests/test_specific.py::TestClass::test_method -v` - Run specific test
+- `python3 -m pytest -k "test_pattern" -v` - Run tests matching pattern
+- `python3 -m pytest tests/ -m "unit" -v` - Run tests with specific markers
+
+## Architecture
+
+### Core Module Structure
+- `src/awsquery/cli.py` - Main CLI interface and argument parsing
+- `src/awsquery/core.py` - Core AWS query execution logic
+- `src/awsquery/security.py` - Security policy validation (ReadOnly enforcement)
+- `src/awsquery/filters.py` - Data filtering and column selection logic
+- `src/awsquery/formatters.py` - Output formatting (table/JSON)
+- `src/awsquery/utils.py` - Utility functions and debug helpers
+
+### Key Features
+- **Smart Multi-Level Calls**: Automatically resolves missing parameters by inferring list operations
+- **Security-First Design**: All operations validated against `policy.json` ReadOnly policy
+- **Flexible Filtering**: Multi-level filtering with `--` separators for different filter types
+- **Auto-Parameter Resolution**: Handles both specific fields and standard AWS patterns (Name, Id, Arn)
+- **Intelligent Response Processing**: Clean extraction of list data, ignoring AWS metadata
+
+### Security Architecture
+The tool enforces security through a comprehensive `policy.json` file that defines allowed ReadOnly AWS operations. All API calls are validated against this policy before execution.
+
+### Testing Structure
+- Unit tests in `tests/unit/` with `@pytest.mark.unit`
+- Integration tests in `tests/integration/` with `@pytest.mark.integration`
+- Critical path tests marked with `@pytest.mark.critical`
+- AWS mocks using moto library marked with `@pytest.mark.aws`
+
+### STRICT Testing Requirements - MUST FOLLOW
+
+#### 🚫 PROHIBITED: Test Anti-Patterns
+**NEVER CREATE:**
+1. **Duplicate Test Files**: Before creating ANY test file, search for existing tests covering the same functionality
+   - Flag tests: Use `test_cli_flags.py` ONLY
+   - Parser tests: Use `test_cli_parser.py` ONLY
+   - Filter tests: Use `test_filter_implementation.py` for real tests, `test_filter_matching.py` for patterns
+2. **Over-Mocked Tests**: Tests that mock the very functions they claim to test
+3. **Mock Assertion Tests**: Tests that only verify `mock.assert_called()` without testing actual behavior
+4. **Nested Mock Contexts**: More than 2 levels of `with patch()` indicates over-mocking
+
+#### ✅ REQUIRED: Test Best Practices
+**ALWAYS:**
+1. **Test Real Implementation**:
+   ```python
+   # GOOD: Tests actual function
+   result = filter_resources(real_data, ["filter"])
+   assert len(result) == expected
+
+   # BAD: Only tests mock
+   mock_filter.return_value = []
+   mock_filter.assert_called_once()
+   ```
+
+2. **Minimal Mocking**: Only mock external dependencies (boto3, file I/O, network)
+   ```python
+   # GOOD: Only mock AWS
+   @patch("boto3.client")
+   def test_feature(mock_client):
+       # Test real code with mocked AWS
+
+   # BAD: Mock everything
+   @patch("filter_resources")
+   @patch("format_output")
+   @patch("parse_args")
+   ```
+
+3. **Consolidate Related Tests**: Group similar tests in one file
+   - All flag position tests → `test_cli_flags.py`
+   - All parser tests → `test_cli_parser.py`
+   - All filter implementation → `test_filter_implementation.py`
+
+4. **Test Edge Cases**: Include malformed input, Unicode, empty values
+   ```python
+   # Test edge cases
+   test_cases = ["", None, "^$", "ˆ", "$^", "^^$$"]
+   ```
+
+5. **Verify Actual Output**: Check real results, not mock calls
+   ```python
+   # GOOD: Verify actual JSON
+   output = format_json_output(data, filters)
+   parsed = json.loads(output)  # Ensures valid JSON
+
+   # BAD: Only check mock called
+   mock_json.assert_called_once()
+   ```
+
+#### 📋 Test Review Checklist
+Before committing ANY test:
+1. ❓ Does a test file for this feature already exist?
+2. ❓ Am I testing real code or just mocks?
+3. ❓ Do assertions verify actual behavior?
+4. ❓ Is mocking limited to external dependencies only?
+5. ❓ Are edge cases covered?
+
+#### 🔍 Finding Duplicate Tests
+```bash
+# Check for existing tests before creating new ones
+grep -r "test.*flag.*position" tests/
+grep -r "test.*parser" tests/
+grep -r "test.*filter" tests/
+```
+
+### 🚫 **ABSOLUTE PROHIBITION: VERBOSE TEST COMMENTS**
+
+**MANDATORY EDICT: UNNECESSARY TEST COMMENTS ARE CATEGORICALLY FORBIDDEN**
+
+**NEVER WRITE THESE TYPES OF COMMENTS:**
+- **TDD Placeholder Comments**: `"""Test the expected structure when -i/--input is implemented."""`
+- **Obvious Restatements**: `"""Test that function returns expected value."""`
+- **Implementation Descriptions**: `"""This test checks if the parser works correctly."""`
+- **Future Implementation Notes**: `"""TODO: implement when feature X is ready."""`
+- **Verbose Process Descriptions**: `"""First we call X, then we check Y, finally we assert Z."""`
+
+**HARD RULES FOR TEST DOCUMENTATION:**
+- **NO REDUNDANT DOCSTRINGS**: Never restate what the method name already says
+- **NO TDD PLACEHOLDERS**: Delete placeholder comments immediately after implementation
+- **NO OBVIOUS COMMENTS**: If the test name explains it, don't repeat in comments
+- **NO VERBOSE EXPLANATIONS**: Code should be self-documenting
+- **ESSENTIAL ONLY**: Comments only for complex edge cases or non-obvious logic
+
+**ACCEPTABLE COMMENTS (RARE):**
+- Complex edge case explanation: `# Unicode circumflex U+02C6 vs ASCII U+005E`
+- Non-obvious assertion: `# Must check stderr, not stdout for debug output`
+- External dependency note: `# Requires specific AWS policy format`
+
+**ENFORCEMENT:**
+- **IMMEDIATE DELETION** of any TDD placeholder comments
+- **ZERO TOLERANCE** for verbose test documentation
+- **CLEAN CODE OVER COMMENTS** - make tests readable through naming and structure
+
+### 🚫 **ABSOLUTE PROHIBITION: PYTEST MARKERS**
+
+**MANDATORY EDICT: PYTEST MARKERS ARE CATEGORICALLY FORBIDDEN AND COMPLETELY BANNED**
+
+**UNBREAKABLE RULES:**
+- **NEVER, EVER, UNDER ANY CIRCUMSTANCES** add `@pytest.mark.*` decorators to tests
+- **ZERO TOLERANCE** for selective test execution markers (`@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.slow`, `@pytest.mark.critical`, etc.)
+- **ALL TESTS MUST ALWAYS RUN** - no exceptions, no conditional execution, no selective filtering
+- **IMMEDIATE DELETION** required for any pytest markers discovered in code
+- **NO EXEMPTIONS** - this rule is immutable and non-negotiable
+
+**RATIONALE:**
+- Selective test execution leads to **INCOMPLETE COVERAGE** and **HIDDEN FAILURES**
+- Markers create **FALSE CONFIDENCE** by allowing tests to be skipped
+- **ALL TESTS ARE CRITICAL** - none should be optional or conditional
+- Complete test suite execution is **MANDATORY FOR QUALITY ASSURANCE**
+
+**ENFORCEMENT:**
+- Any pytest markers found in code must be **REMOVED IMMEDIATELY**
+- Makefile commands must **NEVER USE** `-m "marker"` syntax
+- Test discovery must be **PURELY DIRECTORY-BASED** (tests/unit/, tests/integration/)
+- **NO EXCEPTIONS** - this is an inviolable principle
+
+**ALLOWED:** `@pytest.mark.parametrize` ONLY (for test parameterization, not selection)
+**FORBIDDEN:** All other `@pytest.mark.*` decorators without exception
+
+### Configuration Files
+- `pyproject.toml` - Main project configuration with dependencies and tool settings
+- `pytest.ini` - Test configuration with coverage settings (80% minimum)
+- `Makefile` - Comprehensive development and AWS sampling commands
+- `.pre-commit-config.yaml` - Pre-commit hooks configuration

{awsquery-0.3.2 → awsquery-0.4.0}/Makefile

@@ -40,13 +40,13 @@ test: ## Run all tests
 	python3 -m pytest tests/ -v
 
 test-unit: ## Run unit tests only
-	python3 -m pytest tests/unit/ -v -m "unit"
+	python3 -m pytest tests/unit/ -v
 
 test-integration: ## Run integration tests only
-	python3 -m pytest tests/integration/ -v -m "integration"
+	python3 -m pytest tests/integration/ -v
 
-test-slow: ## Run slow tests
-	python3 -m pytest tests/ -v -m "slow"
+test-slow: ## Run all tests (no selective marking allowed)
+	python3 -m pytest tests/ -v
 
 test-fast: ## Run all tests with parallel execution (optimized for Python 3.8-3.10)
 	python3 -m pytest tests/ -n auto -q
@@ -57,8 +57,8 @@ test-unit-fast: ## Run unit tests with parallel execution (2-5 seconds)
 test-integration-fast: ## Run integration tests with parallel execution
 	python3 -m pytest tests/integration/ -n auto -q
 
-test-critical: ## Run critical path tests
-	python3 -m pytest tests/ -v -m "critical"
+test-critical: ## Run all tests (no selective marking allowed)
+	python3 -m pytest tests/ -v
 
 coverage: ## Run tests with coverage report
 	python3 -m pytest tests/ --cov=src/awsquery --cov-report=term-missing --cov-report=html

{awsquery-0.3.2 → awsquery-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awsquery
-Version: 0.3.2
+Version: 0.4.0
 Summary: Advanced CLI tool for querying AWS APIs with flexible filtering and automatic parameter resolution
 Author-email: Florian Motlik <flo@flomotlik.me>
 License: MIT
@@ -81,9 +81,9 @@ the data you need during review, debugging or development.
 - **Flexible Filtering**: Multi-level filtering with `--` separators for resource, value, and column filters
 - **Partial Matching**: All filters use case-insensitive partial matching (both value and column filters)
 - **Keys Discovery**: Show all available fields from any API response with `-k`/`--keys` (fixed to show keys from successful responses)
-- **Debug Mode**: Comprehensive debug output with `-d`/`--debug`
-- **Security Validation**: Enforces ReadOnly AWS policy with wildcard pattern matching
-- **Auto-completion**: Tab completion for AWS services and actions (filtered by security policy)
+- **Debug Mode**: Comprehensive debug output with `-d`/`--debug` featuring structured output with timestamps and DebugContext tracking
+- **Security Validation**: Enforces ReadOnly AWS operations with comprehensive validation
+- **Smart Auto-completion**: Enhanced tab completion with split matching and prefix priority for AWS services and actions
 - **Smart Parameter Extraction**: Handles both specific fields and standard AWS field patterns (Name, Id, Arn)
 - **Intelligent Response Processing**: Clean extraction of list data, ignoring metadata
 - **Tabular Output**: Customizable column display with automatic filtering
@@ -91,6 +91,8 @@ the data you need during review, debugging or development.
 - **Region/Profile Support**: AWS CLI-compatible `--region` and `--profile` arguments for session management
 - **Tag Transformation**: Automatic conversion of AWS Tags list to key-value pairs for better readability
 - **Default Column Filters**: Configuration-based default columns for common AWS queries
+- **Parameter Passing**: Direct parameter passing to AWS APIs with `-p`/`--parameter` for advanced use cases
+- **Hint-Based Resolution**: Function selection hints with `-i`/`--input` for multi-step calls, including field extraction targeting
 
 ## Installation
 
@@ -138,13 +140,20 @@ After adding the appropriate line to your shell configuration, restart your shel
 source ~/.bashrc  # or ~/.zshrc, etc.
 ```
 
-Now you can use tab completion:
+Now you can use enhanced tab completion with smart matching:
 ```bash
 awsquery <TAB>              # Shows available services
 awsquery ec2 <TAB>          # Shows available ec2 actions
 awsquery s3 list-<TAB>      # Shows s3 list actions
+awsquery ec2 desc-inst<TAB> # Smart completion: "desc-inst" matches "describe-instances"
+awsquery cloudformation des-sta<TAB> # Matches "describe-stacks"
 ```
 
+The autocomplete system now features:
+- **Split matching**: "desc-inst" matches "describe-instances"
+- **Prefix priority**: Exact prefix matches are prioritized over substring matches
+- **Security filtering**: Only shows ReadOnly operations
+
 ## Usage
 
 ### Basic Query
@@ -177,14 +186,15 @@ awsquery --keys s3 list-buckets
 # List available services
 awsquery
 
-# Debug mode for troubleshooting
+# Debug mode for troubleshooting with enhanced DebugContext output
+# Shows structured debug information with timestamps and execution flow
 awsquery -d ec2 describe-instances
 ```
 
 ## Command Structure
 
 ```
-awsquery [-j|--json] [-k|--keys] [-d|--debug] [--region REGION] [--profile PROFILE] SERVICE ACTION [VALUE_FILTERS...] [-- TABLE_OUTPUT_FILTERS...]
+awsquery [-j|--json] [-k|--keys] [-d|--debug] [-p PARAM] [-i HINT] [--region REGION] [--profile PROFILE] SERVICE ACTION [VALUE_FILTERS...] [-- TABLE_OUTPUT_FILTERS...]
 ```
 
 - **SERVICE**: AWS service name (ec2, s3, iam, etc.)
@@ -194,17 +204,18 @@ awsquery [-j|--json] [-k|--keys] [-d|--debug] [--region REGION] [--profile PROFI
 - **-j, --json**: Output results in JSON format instead of table
 - **-k, --keys**: Show all available keys for the command
 - **-d, --debug**: Enable debug output for troubleshooting
+- **-p, --parameter PARAM**: Pass parameters directly to AWS API (key=value format)
+- **-i, --input HINT**: Hint for multi-step function selection (e.g., "desc-clus" or "desc-clus:fieldname")
 - **--region REGION**: AWS region to use for requests (e.g., us-west-2)
 - **--profile PROFILE**: AWS profile to use from ~/.aws/credentials
 
 ## Security
 
-- **ReadOnly Enforcement**: Only AWS ReadOnly policy actions are permitted
+- **ReadOnly Enforcement**: Only AWS ReadOnly operations are permitted
 - **Input Sanitization**: Prevents injection attacks through parameter validation
-- **Policy Validation**: All actions validated against policy.json before execution
+- **Operation Validation**: All actions validated before execution
 - **Wildcard Matching**: Supports AWS IAM wildcard patterns (e.g., `ec2:Describe*`)
 - **Session Isolation**: Each profile/region maintains separate boto3 sessions
-- **Automatic Policy Updates**: Can fetch latest AWS ReadOnly policy via `make update-policy`
 - **Security Testing**: Comprehensive test suite validates security constraints
 
 ## Examples
@@ -226,13 +237,16 @@ awsquery s3 list-buckets backup
 # Filters: "prod" in stack data, columns containing "Created" or "StackName"
 awsquery cloudformation describe-stack-events prod -- Created StackName
 
+# Targeted field extraction with hint for multi-step calls
+awsquery elbv2 describe-tags -i desc-clus:clusterarn prod
+
 # Discover all available keys
 awsquery -k ec2 describe-instances
 
 # JSON output with filtering (partial column name matching)
 awsquery -j ec2 describe-instances prod -- InstanceId State.Name
 
-# Debug mode for troubleshooting
+# Debug mode with enhanced output showing parameter resolution and API calls
 awsquery -d cloudformation describe-stack-resources workers -- EKS
 
 # Use specific AWS region
@@ -247,6 +261,47 @@ awsquery --region us-east-2 --profile dev ec2 describe-vpcs
 # View transformed tags (partial match on column names)
 # Shows any column containing "Tags.Name" or "Tags.Environment"
 awsquery ec2 describe-instances -- Tags.Name Tags.Environment
+
+# CloudTrail LookupEvents with complex parameter structures
+# Filter events by event name with automatic type conversion
+awsquery cloudtrail lookup-events -p LookupAttributes=AttributeKey=EventName,AttributeValue=ConsoleLogin
+
+# Multiple CloudTrail attributes using semicolon separation
+awsquery cloudtrail lookup-events -p LookupAttributes=AttributeKey=EventName,AttributeValue=AssumeRole;AttributeKey=Username,AttributeValue=admin
+
+# CloudTrail with time range and resource type filtering
+awsquery cloudtrail lookup-events -p StartTime=2024-01-01 -p EndTime=2024-01-31 -p LookupAttributes=AttributeKey=ResourceType,AttributeValue=AWS::S3::Bucket
+
+### Advanced Parameter Passing
+
+# Pass specific parameters to AWS API calls
+awsquery ec2 describe-instances -p MaxResults=10
+awsquery ec2 describe-instances -p InstanceIds=i-123,i-456 -p MaxResults=5
+
+# Complex parameter structures for SSM with automatic type conversion
+awsquery ssm describe-parameters -p ParameterFilters=Key=Name,Option=Contains,Values=Ubuntu,2024
+
+# Multiple complex structures using semicolon separation
+awsquery ssm describe-parameters -p ParameterFilters=Key=Name,Option=Contains,Values=Ubuntu;Key=Type,Option=Equal,Values=String
+
+# Complex structures with nested arrays and type conversion
+awsquery ec2 describe-instances -p Filters=Name=instance-state-name,Values=running,stopped;Name=tag:Environment,Values=prod,staging
+
+### Hint-Based Multi-Step Resolution
+
+# Use hints to guide automatic parameter resolution
+# When describe-tags needs resource ARNs, hint at using describe-clusters
+awsquery elbv2 describe-tags -i desc-clus prod
+
+# CloudFormation stack resources with hint for stack selection
+awsquery cloudformation describe-stack-resources -i desc-stacks production
+
+# ECS service details with task definition hint
+awsquery ecs describe-services -i desc-task web-service
+
+# Field-specific extraction with function:field format
+awsquery elbv2 describe-tags -i desc-clus:clusterarn prod  # Extract ClusterArn specifically
+awsquery eks describe-fargate-profile -i desc-clus:rolearn  # Extract RoleArn instead of default
 ```
 
 ## Configuration
@@ -261,8 +316,9 @@ Ensure AWS credentials are configured via:
 
 ### Default Filters Configuration
 
-The tool uses `default_filters.yaml` to define default columns for common queries. This file is loaded from the package directory and will
-provide you with standard columns if you don't add any.
+The tool uses `default_filters.yaml` to define default columns for common queries. This comprehensive configuration file (3000+ lines)
+provides extensive pre-configured filters for dozens of AWS services, loaded from the package directory to provide you with standard
+columns if you don't add any.
 
 Example configuration:
 ```yaml
@@ -299,31 +355,27 @@ make coverage
 # Run specific test categories
 make test-unit
 make test-integration
-make test-critical  # Run critical path tests only
+make test-critical  # Run all tests (comprehensive test suite)
 
 # Code formatting and linting
 make format
 make format-check  # Check without modifying
 make lint
-make type-check
+make type-check    # Run mypy type checking
 make security-check  # Run security analysis
 
+# Mutation testing
+make mutmut        # Run mutation tests
+make mutmut-results # Show mutation test results
+make mutmut-html   # Generate HTML mutation test report
+
 # Pre-commit hooks
 make pre-commit  # Run all pre-commit hooks
 
 # Continuous Integration
-make ci  # Run all CI checks
+make ci  # Run comprehensive CI pipeline (tests, linting, type-check, security)
 ```
 
-### Policy Management
-
-```bash
-# Update policy.json with latest AWS ReadOnly managed policy
-make update-policy
-
-# Validate policy.json structure
-make validate-policy
-```
 
 ### Docker Usage
 
@@ -433,6 +485,52 @@ awsquery cloudformation describe-stack-events production
 awsquery cloudformation describe-stack-resources prod -- Lambda
 ```
 
+### Parameter Passing (`-p`/`--parameter`)
+
+Pass parameters directly to AWS API calls using the `-p` flag. This is useful for fine-tuning API behavior:
+
+```bash
+# Limit results for large responses
+awsquery ec2 describe-instances -p MaxResults=20
+
+# Filter specific resources by ID
+awsquery ec2 describe-instances -p InstanceIds=i-1234567890abcdef0,i-0987654321fedcba0
+
+# Multiple parameters (can use multiple -p flags)
+awsquery elbv2 describe-load-balancers -p PageSize=10 -p Names=my-alb
+
+# Complex parameter structures (for APIs like SSM)
+awsquery ssm describe-parameters -p ParameterFilters=Key=Name,Option=Contains,Values=Ubuntu
+```
+
+**Parameter Format:**
+- Simple: `Key=Value`
+- Lists: `Key=Value1,Value2,Value3`
+- Complex structures: Use semicolons to separate multiple objects (e.g., `Key1=Val1,Val2;Key2=Val3`)
+- Type conversion: Numbers and booleans are automatically converted
+- Nested structures: Comma-separated values within objects, semicolon-separated objects
+- CloudTrail example: `LookupAttributes=AttributeKey=EventName,AttributeValue=Login;AttributeKey=Username,AttributeValue=admin`
+
+### Hint-Based Resolution (`-i`/`--input`)
+
+Guide multi-step parameter resolution with function hints:
+
+```bash
+# Basic function hint - guides which list operation to use
+awsquery cloudformation describe-stack-resources -i list-sta production
+
+# Field extraction hint - specify exact field to extract
+awsquery elbv2 describe-tags -i desc-clus:clusterarn prod
+
+# Override default field selection
+awsquery eks describe-fargate-profile -i desc-clus:rolearn my-cluster
+```
+
+**Key Features:**
+- **Smart matching**: "desc-inst" matches "describe-instances"
+- **Field targeting**: Use `function:field` to extract specific fields
+- **Automatic fallback**: Uses standard heuristics when no field specified
+
 ### Filtering Strategies
 
 ```bash
@@ -473,7 +571,7 @@ awsquery s3 list-buckets backup -- Name Creation
 **"Access Denied" errors**
 - Ensure your AWS credentials have ReadOnly permissions
 - Check if using the correct profile with `--profile`
-- Verify the action is in the ReadOnly policy
+- Verify the operation is permitted
 
 **"Parameter validation failed"**
 - Some APIs require specific parameters
@@ -487,7 +585,7 @@ awsquery s3 list-buckets backup -- Name Creation
 
 ## Requirements
 
-The tool requires a `policy.json` file containing the AWS ReadOnly policy for security validation. This file is included automatically when installing via pip. The package dependencies are:
+The package dependencies are:
 
 - boto3>=1.35.0
 - botocore>=1.35.0