Restructure documentation for better organization and maintainability

Major documentation overhaul to improve discoverability and reduce duplication:

**New Documentation Structure:**
- docs/guides/ - User-focused guides (quick-start, troubleshooting)
- docs/usage/ - Detailed usage documentation (CLI, API, output format)
- docs/technical/ - Technical docs with nested architecture and ADRs

**Key Changes:**
- Simplified README.md from 169 to 75 lines (60% reduction)
- Simplified SPECIFICATION.md from ~200 to ~120 lines (40% reduction)
- Created comprehensive usage guides with extracted content
- Reorganized ADRs under architecture/ for logical grouping
- Updated all cross-references and file paths
- Improved Flask example with realistic build system integration

**Benefits:**
- Progressive disclosure: Basic → Detailed documentation flow
- Eliminated content duplication between files
- Clear separation of user guides vs technical implementation
- Better organized technical documentation hierarchy
- Maintainable structure for future additions

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

Co-Authored-By: Claude <noreply@anthropic.com>

Author: davidkopp

CLAUDE.md

@@ -70,10 +70,15 @@ python3 -c "from dependency_resolver.detectors.dpkg_detector import DpkgDetector
 - `dependency_resolver/executors/` - Environment execution adapters
 - `dependency_resolver/core/` - Base interfaces and orchestrator
 - `tests/` - Test suites organized by component (detectors, executors, integration, specialized)
-- `docs/adr/` - Architecture decision records
-- `docs/detectors/` - Individual detector documentation
+- `docs/guides/` - User guides (quick start, troubleshooting)
+- `docs/usage/` - Detailed usage documentation (CLI, API, output format)
+- `docs/technical/` - Technical documentation including:
+  - `docs/technical/architecture/adr/` - Architecture decision records
+  - `docs/technical/detectors/` - Individual detector documentation
+  - `docs/technical/architecture/` - System architecture documentation
+  - `docs/technical/adding-new-detectors.md` - Guide for implementing new package manager detectors
 
 ## Project Files
 
+- [README.md](./README.md) - Overview with links to detailed docs
 - [SPECIFICATION.md](./SPECIFICATION.md) - Requirements and constraints
-- [README.md](./README.md) - Update after adding features

CONTRIBUTING.md

@@ -131,7 +131,7 @@ Please refer to the [CLAUDE.md](./CLAUDE.md) file for detailed development guide
 
 ## Adding New Package Manager Detectors
 
-To add support for a new package manager, follow the comprehensive guide in [docs/ADDING_NEW_DETECTORS.md](./docs/ADDING_NEW_DETECTORS.md). This guide covers:
+To add support for a new package manager, follow the comprehensive guide in [docs/technical/adding-new-detectors.md](./docs/technical/adding-new-detectors.md). This guide covers:
 
 - Implementation patterns and interface requirements
 - Testing strategies with Docker environments
@@ -143,7 +143,8 @@ To add support for a new package manager, follow the comprehensive guide in [doc
 If you have questions or need help:
 
 - Check the [SPECIFICATION.md](./SPECIFICATION.md) for project requirements and design approaches
-- Review [docs/ADDING_NEW_DETECTORS.md](./docs/ADDING_NEW_DETECTORS.md) for detector implementation guidance
+- Review [docs/technical/adding-new-detectors.md](./docs/technical/adding-new-detectors.md) for detector implementation guidance
+- Check [docs/technical/](./docs/technical/) for architecture documentation and ADRs
 - Review existing code for patterns and conventions
 - Open an issue for discussion if you're unsure about an approach
 

README.md

@@ -1,168 +1,75 @@
 # dependency-resolver
 
 A tool for creating snapshots of installed packages on specified target environments. The project provides both a command-line interface and a Python library for programmatic use.
-Its main focus is dependency resolving of Docker containers, but it also supports dependency resolving on the host system.
-The output is a structured JSON that includes information about all the installed packages from supported sources with their version and unique hash values.
+
+Its main focus is dependency resolving of Docker containers, but it also supports dependency resolving on the host system. The output is a structured JSON that includes information about all the installed packages from supported sources with their version and unique hash values.
 
 ## Installation
 
 ```bash
-# Clone and install
 git clone https://github.com/green-coding-solutions/dependency-resolver
 cd dependency-resolver
 pip install .
 ```
 
-## Usage
-
-The dependency-resolver can be used in two ways:
-
-1. **Command Line Interface (CLI)** - For direct terminal usage
-2. **Programmatic Interface** - As a Python library in other projects
-
-### Command Line Interface
+## Quick Start
 
 ```bash
-# Analyze host system (default behavior)
+# Analyze host system
 python3 -m dependency_resolver
 
-# Explicitly specify host environment
-python3 -m dependency_resolver host
-
-# Analyze Docker container by name
+# Analyze Docker container
 python3 -m dependency_resolver docker nginx
 
-# Analyze Docker container by ID
-python3 -m dependency_resolver docker a1b2c3d4e5f6
-
-# Get only container metadata (skip dependency detection)
-python3 -m dependency_resolver docker nginx --only-container-info
-
-# Enable debug output
-python3 -m dependency_resolver --debug
-
-# Set working directory
-python3 -m dependency_resolver --working-dir /path/to/project
-
-# Skip system scope package managers
-python3 -m dependency_resolver --skip-system-scope
-
-# Pretty print JSON output
+# Pretty print output
 python3 -m dependency_resolver --pretty-print
-```
-
-### Programmatic Interface
-
-The dependency-resolver can also be used as a Python library in other projects. Here are some examples:
 
-```python
-import dependency_resolver
-
-# Simple host system analysis
-deps_json = dependency_resolver.resolve_host_dependencies()
-
-# Get results as Python dictionary for further processing
-deps_dict = dependency_resolver.resolve_dependencies_as_dict(
-    environment_type="host",
-    skip_system_scope=True
-)
-
-# Docker container analysis
-docker_deps = dependency_resolver.resolve_docker_dependencies(
-    container_identifier="nginx",
-    working_dir="/app"
-)
-
-# Advanced usage with direct access to core classes
-from dependency_resolver import Orchestrator, HostExecutor, OutputFormatter
-
-executor = HostExecutor()
-orchestrator = Orchestrator(debug=True, skip_system_scope=True)
-dependencies = orchestrator.resolve_dependencies(executor)
-formatter = OutputFormatter()
-json_output = formatter.format_json(dependencies, pretty_print=True)
+# Get help with all options
+python3 -m dependency_resolver -h
 ```
 
-**Available convenience functions:**
+## Supported Package Managers
+
+- **apt/dpkg** - System packages Ubuntu/Debian
+- **apk** - System packages of Alpine
+- **pip** - Python packages
+- **npm** - Node.js packages
 
-- `resolve_host_dependencies()` - Analyze host system, returns JSON string
-- `resolve_docker_dependencies()` - Analyze Docker container, returns JSON string
-- `resolve_docker_dependencies_as_dict()` - Analyze Docker container, returns Python dictionary
-- `resolve_dependencies_as_dict()` - Generic analysis, returns Python dictionary
+Also captures **Docker container metadata** when analyzing containers.
 
-**Available classes for advanced usage:**
+## Usage Options
 
-- `Orchestrator` - Main dependency resolution coordinator
-- `HostExecutor`, `DockerExecutor` - Environment adapters
-- `OutputFormatter` - JSON formatting utilities
+### Command Line Interface
 
-### Supported Environments
+For terminal usage with full control over options and environments.
 
-- **host** - Host system analysis (default)
-- **docker** - Docker container analysis (requires container ID or name)
+### Programmatic Interface
 
-### Supported Detectors
+Use as a Python library in other projects:
 
-**Package Managers:**
+```python
+import dependency_resolver
 
-- **apt/dpkg** - System packages Ubuntu/Debian
-- **apk** - System packages of Alpine
-- **pip** - Python packages
-- **npm** - Node.js packages
+# Analyze host system
+deps = dependency_resolver.resolve_host_dependencies()
 
-**Container Information:**
-
-- **docker-info** - Docker container metadata and base image details
-
-### Output Format
-
-The tool outputs JSON with the following structure:
-
-```json
-{
-  "_container-info": {
-    "name": "nginx-container",
-    "image": "nginx:latest",
-    "hash": "sha256:2cd1d97f893f..."
-  },
-  "dpkg": {
-    "scope": "system",
-    "dependencies": {
-      "package-name": {
-        "version": "1.2.3 amd64",
-        "hash": "abc123..."
-      }
-    }
-  },
-  "pip": {
-    "scope": "project",
-    "location": "/path/to/venv/lib/python3.12/site-packages",
-    "hash": "def456...",
-    "dependencies": {
-      "package-name": {
-        "version": "1.2.3"
-      }
-    }
-  }
-}
+# Analyze Docker container
+docker_deps = dependency_resolver.resolve_docker_dependencies("nginx")
 ```
 
 ## Documentation
 
-### Architecture & Detector Documentation
-
-For detailed information about architectural decisions and package manager implementations:
-
-- **Architecture Decision Records**: See [docs/adr/](./docs/adr/) for architectural decisions
-- **Detector Documentation**: See [docs/detectors/](./docs/detectors/) for detailed implementation information:
-  - [APK Detector](./docs/detectors/apk_detector.md) - Alpine Linux package detection
-  - [DPKG Detector](./docs/detectors/dpkg_detector.md) - Debian/Ubuntu package detection
-  - [NPM Detector](./docs/detectors/npm_detector.md) - Node.js package detection
-  - [PIP Detector](./docs/detectors/pip_detector.md) - Python package detection
-  - [Docker Info Detector](./docs/detectors/docker_info_detector.md) - Individual container metadata
-
-See the complete [SPECIFICATION.md](./SPECIFICATION.md) for detailed requirements and implementation constraints.
+- **[Quick Start Guide](./docs/guides/quick-start.md)** - Get up and running
+- **[CLI Usage Guide](./docs/usage/cli-guide.md)** - Complete command line reference
+- **[Python API Guide](./docs/usage/programmatic-api.md)** - Programmatic usage
+- **[Output Format Guide](./docs/usage/output-format.md)** - Understanding the JSON results
+- **[Troubleshooting](./docs/guides/troubleshooting.md)** - Common issues and solutions
+- **[Technical Documentation](./docs/technical/)** - Architecture and implementation details
 
 ## Contributing
 
 For development setup, contribution guidelines, and information about running tests and code quality checks, please see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Requirements and Design
+
+See the complete [SPECIFICATION.md](./SPECIFICATION.md) for detailed requirements and implementation constraints.