Add SDK foundation tests for governance compliance

- Introduced `test_sdk_foundation.md` to outline governance tests ensuring SDK components adhere to core contracts and patterns.
- Created `test_sdk_foundation_contracts.py` to implement tests for provider interface compliance, model validation, exception hierarchy, resource ID strategy, multi-tenancy, and request/response contracts.
- Added `test_seed_resource_groups.py` to validate resource group seeding functionality, including handling missing subscriptions, name mismatches, foreign key constraints, and idempotency.

Author: nielsweistra

README.md

@@ -803,44 +803,29 @@ See [PIPELINE_SETUP.md](./PIPELINE_SETUP.md) for complete pipeline documentation
 
 ## Documentation
 
-### Getting Started (1-4)
-1. [**Scoped Resource Handler**](./docs/01-SCOPED_RESOURCE_HANDLER.md) - Complete guide to scope-aware resource management
-2. [**Resource ID Strategy**](./docs/02-RESOURCE_ID_STRATEGY.md) - Hybrid path + GUID resource identification
-3. [**Modular Architecture**](./docs/03-MODULAR_ARCHITECTURE.md) - Module organization and design patterns
-4. [**Architecture Overview**](./docs/04-ARCHITECTURE.md) - Detailed SDK architecture and components
-
-### FastAPI Integration (5-7)
-5. [**FastAPI Module**](./docs/05-FASTAPI_MODULE.md) - Complete FastAPI integration guide
-6. [**FastAPI Integration**](./docs/06-FASTAPI_INTEGRATION.md) - Integration patterns and examples
-7. [**FastAPI Quick Reference**](./docs/07-FASTAPI_QUICK_REFERENCE.md) - FastAPI API quick reference
-
-### CI/CD & Operations (8-10)
-8. [**Pipeline Setup**](./docs/08-PIPELINE_SETUP.md) - Complete CI/CD pipeline documentation
-9. [**Automated Versioning**](./docs/09-AUTOMATED_VERSIONING.md) - Git tag-based version management
-10. [**Version Update Guide**](./docs/10-VERSIONING_UPDATE.md) - Version update procedures
-
-### Resource Group & Handlers (11-13)
-11. [**Resource Group Creation Flow**](./docs/11-RESOURCE_GROUP_CREATION_FLOW.md) - Step-by-step RG creation process
-12. [**Resource Group Big 3 Integration**](./docs/12-RESOURCE_GROUP_BIG_3_INTEGRATION.md) - RG with handler mixins
-13. [**Scoped Resources Overview**](./docs/13-SCOPED_RESOURCES_OVERVIEW.md) - Comprehensive scoped resource guide
-
-### Quick References (14-15)
-14. [**Quick Reference**](./docs/14-QUICK_REFERENCE.md) - SDK API quick reference
-15. [**Big 3 Quick Reference**](./docs/15-QUICK_REFERENCE_BIG_3.md) - Handler mixin quick reference
-
-### Location Management (16-20)
-16. [**Locations Handler**](./docs/16-LOCATIONS_HANDLER.md) - Location handler implementation guide
-17. [**Big 3 Implementation**](./docs/17-BIG_3_IMPLEMENTATION.md) - Complete handler mixin implementation
-18. [**ITL Locations Schema**](./docs/18-ITL_LOCATIONS_SCHEMA.md) - Custom location validation
-19. [**Dynamic Locations Summary**](./docs/19-DYNAMIC_LOCATIONS_SUMMARY.md) - Dynamic location management overview
-20. [**Dynamic Locations Complete**](./docs/20-DYNAMIC_LOCATIONS_COMPLETE.md) - Complete location system docs
-
-### Advanced Topics (21-23)
-21. [**Big 3 Summary**](./docs/21-BIG_3_SUMMARY.md) - Handler mixin feature summary
-22. [**Big 3 Complete Summary**](./docs/22-BIG_3_COMPLETE_SUMMARY.md) - Detailed handler mixin documentation
-23. [**Architecture Summary**](./docs/23-ARCHITECTURE_SUMMARY.md) - Quick architecture overview
+**Phase 2 Complete:** Documentation has been consolidated from 26 scattered files into 9 comprehensive, well-organized guides. [See consolidation details »](./docs/99-Archive/CONSOLIDATION_MANIFEST.md)
+
+### Foundation (01-04)
+1. [**Architecture Complete**](./docs/02-ARCHITECTURE.md) - Complete system architecture, components, and design principles
+2. [**Core Concepts**](./docs/03-CORE_CONCEPTS.md) - Scoped handlers, resource ID strategy, and modular architecture (foundation concepts)
+3. [**Resource Groups**](./docs/04-RESOURCE_GROUPS.md) - Complete resource group implementation with creation flow and extensibility patterns
+
+### Handler Patterns (05-07)
+4. [**Handler Mixins**](./docs/06-HANDLER_MIXINS.md) - TimestampedResourceHandler, ProvisioningStateHandler, ValidatedResourceHandler (Big 3)
+5. [**Location Validation**](./docs/07-LOCATION_VALIDATION.md) - Location handler, validation, and 30+ Azure regions + 24 ITL custom locations
+6. [**API Endpoints**](./docs/08-API_ENDPOINTS.md) - FastAPI integration, AppFactory, middleware, and HTTP routing
+
+### Advanced Features (08-09)
+7. [**Async Patterns**](./docs/09-ASYNC_PATTERNS.md) - Service Bus integration, async provider modes, and message queuing
+8. [**Worker Roles**](./docs/11-WORKER_ROLES.md) - Job queue, worker lifecycle, async offloading, and scaling patterns
+9. [**CI/CD Pipelines**](./docs/14-CI_CD_PIPELINES.md) - GitHub Actions workflows, automated versioning, and publishing
+
+### Quick References & Tools
+- [**Quick Reference**](./docs/14-QUICK_REFERENCE.md) - Handler API quick lookup
+- [**Getting Started Guide**](./docs/00-GETTING-STARTED/) - Onboarding and setup
 
 ### Additional Resources
+- [**Archive & Consolidation Details**](./docs/99-Archive/README.md) - Explains document consolidation and where to find old content
 - [**PyPI Setup Guide**](./.github/PYPI_SETUP.md) - Package publishing configuration
 - [**Examples Directory**](./examples/) - Working code examples and usage patterns
 

SEEDING_GUIDE.md

@@ -0,0 +1,234 @@
+# Database Seeding Guide
+
+This guide explains how to populate the ControlPlane database with default data (locations, tenants, policies, etc.).
+
+## Overview
+
+The SDK provides seed functions to initialize the database with commonly needed default data. All seed functions are **idempotent** - they safely check for existing data before creating new records, so they can be called multiple times without side effects.
+
+## Available Seeds
+
+### 1. **Locations** (`seed_locations`)
+- **Purpose**: Populate available cloud regions and extended locations (edge zones)
+- **Includes**: 18 standard Azure regions + 6 extended locations (CDN edge zones)
+- **Source**: `DEFAULT_LOCATIONS` constant from `itl_controlplane_sdk.core.models.base.constants`
+- **Tables**: `locations`, `extended_locations`
+
+### 2. **Default Tenant** (`seed_default_tenant`)
+- **Purpose**: Create the default "ITL" tenant for resource scoping
+- **ID**: `ITL` (from `DEFAULT_TENANT`)
+- **Table**: `tenants`
+- **Required before**: Other seeds that need tenant_id
+
+### 3. **Management Groups** (`seed_default_management_groups`)
+- **Purpose**: Create standard management group hierarchy
+- **Includes**:
+  - Root
+  - Infrastructure
+  - Workloads
+  - Platform
+- **Table**: `management_groups`
+- **Requires**: Default tenant to exist
+
+### 4. **Policies** (`seed_default_policies`)
+- **Purpose**: Create foundational governance policies
+- **Includes**:
+  - Enforce Encryption at Rest
+  - Require RBAC
+  - Enforce Resource Tagging
+  - Audit Logging
+- **Table**: `policies`
+- **Requires**: Default tenant to exist
+
+## Usage
+
+### From Python Code
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+from itl_controlplane_sdk.core.services.seed import SeedService
+
+# Create async database session
+database_url = "postgresql+asyncpg://user:pass@localhost/dbname"
+engine = create_async_engine(database_url)
+async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+async with async_session() as session:
+    # Seed all data
+    results = await SeedService.seed_all(session)
+    
+    # Or seed individual components
+    await SeedService.seed_default_tenant(session)
+    await SeedService.seed_locations(session)
+    await SeedService.seed_default_management_groups(session)
+    await SeedService.seed_default_policies(session)
+```
+
+### From CLI
+
+```bash
+# Seed all data at once
+python -m itl_controlplane_sdk.cli.seed all
+
+# Seed individual components
+python -m itl_controlplane_sdk.cli.seed tenants
+python -m itl_controlplane_sdk.cli.seed locations
+python -m itl_controlplane_sdk.cli.seed management-groups
+python -m itl_controlplane_sdk.cli.seed policies
+
+# With custom options
+python -m itl_controlplane_sdk.cli.seed \
+  --database-url postgresql+asyncpg://user:pass@localhost/dbname \
+  --tenant-id MyTenant \
+  all
+```
+
+### Environment Variables
+
+- `DATABASE_URL`: PostgreSQL connection string
+  - Default: `postgresql+asyncpg://controlplane:controlplane@localhost:5432/controlplane`
+- Tenant ID: Hard-coded to `ITL` (DEFAULT_TENANT_ID)
+
+### Return Values
+
+All seed functions return a dictionary with operation status:
+
+```python
+{
+    "created": 18,          # Number of new records created
+    "skipped": 6,           # Number of existing records (not duplicated)
+    "total": 24             # Total records processed
+}
+```
+
+## Execution Order
+
+Seed functions should be called in this order (dependencies):
+
+1. **Tenant** → Creates default tenant (other seeds depend on this)
+2. **Locations** → Independent, can run anytime
+3. **Management Groups** → Depends on tenant
+4. **Policies** → Depends on tenant
+
+The `seed_all()` function handles this ordering automatically.
+
+## Integration Examples
+
+### In Provider Initialization
+
+```python
+# In Core Provider startup
+from itl_controlplane_sdk.core.services.seed import SeedService
+
+async def startup():
+    # Initialize database first
+    await alembic_upgrade()
+    
+    # Then seed with defaults
+    async with get_session() as session:
+        results = await SeedService.seed_all(session)
+        logger.info(f"Database seeded: {results}")
+    
+    # Then start provider services
+    await start_services()
+```
+
+### In Migration Hooks
+
+```python
+# In alembic env.py after migrations
+def run_migrations_online() -> None:
+    # ... existing migration code ...
+    
+    with connectable.begin() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        
+        with context.begin_transaction():
+            context.run_migrations()
+        
+        # Seed defaults after migrations
+        if environment == "development":
+            asyncio.run(seed_defaults(connection))
+```
+
+### In Docker Entrypoint
+
+```bash
+#!/bin/bash
+set -e
+
+# Run migrations
+alembic upgrade head
+
+# Seed initial data
+python -m itl_controlplane_sdk.cli.seed all
+
+# Start services
+python -m provider.main
+```
+
+## Data Consistency
+
+All seed functions maintain data consistency:
+
+- **Idempotency**: Check record existence before insert
+- **Foreign Keys**: Respect all FK constraints
+- **Transactions**: Commit atomically or rollback on error
+- **Timestamps**: Set created_at and updated_at
+
+## Example Output
+
+```
+INFO - Starting database seed process...
+INFO - ✓ Created default tenant: ITL
+INFO - ✓ Seeded 24 locations (0 already existed)
+INFO - ✓ Seeded 4 management groups (0 already existed)
+INFO - ✓ Seeded 4 policies (0 already existed)
+INFO - ✓ Database seeding completed successfully
+
+Database seed results:
+  tenant: {'created': 1, 'skipped': 0}
+  locations: {'created': 24, 'skipped': 0, 'total': 24}
+  management_groups: {'created': 4, 'skipped': 0}
+  policies: {'created': 4, 'skipped': 0}
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+```
+sqlalchemy.exc.OperationalError: (asyncpg.exceptions.CannotConnectNowError)
+```
+
+**Solution**: Ensure PostgreSQL is running and DATABASE_URL is correct:
+
+```bash
+# Test connection
+python -c "import asyncpg; asyncio.run(asyncpg.connect('postgresql://...'))"
+```
+
+### Foreign Key Violations
+
+```
+sqlalchemy.exc.IntegrityError: (asyncpg.exceptions.IntegrityConstraintViolationError)
+FOREIGN KEY violation
+```
+
+**Solution**: Ensure tenant exists before seeding other data. Use `seed_all()` which handles ordering.
+
+### Already Exists Errors
+
+Seed functions check for existing records and skip them. No error should occur on second run.
+
+## Summary
+
+| Seed Function | Records | Depends On | Purpose |
+|---|---|---|---|
+| `seed_default_tenant` | 1 tenant | - | Create default "ITL" tenant |
+| `seed_locations` | 24 locations | - | Populate available regions/zones |
+| `seed_management_groups` | 4 groups | Tenant | Create default MG hierarchy |
+| `seed_default_policies` | 4 policies | Tenant | Create baseline governance policies |
+
+Use `seed_all()` to run all seeds in correct order with proper dependency handling.