chore: import upstream snapshot with attribution

documentation/dev/test/ABOUT.testing.md

@@ -0,0 +1,370 @@
+---
+title: "About Testing in Sirius"
+description: "Comprehensive guide to the Sirius testing philosophy, infrastructure, and operator-first testing approach for integration and validation testing."
+template: "TEMPLATE.about"
+version: "1.0.0"
+last_updated: "2025-01-03"
+author: "Development Team"
+tags: ["testing", "philosophy", "integration", "operator-first", "validation", "qa"]
+categories: ["testing", "philosophy"]
+difficulty: "intermediate"
+prerequisites: ["docker", "testing concepts", "integration testing"]
+related_docs:
+  - "README.container-testing.md"
+  - "README.documentation-testing.md"
+  - "README.cicd.md"
+dependencies:
+  - "testing/container-testing/"
+  - "testing/documentation/"
+  - "scripts/git-hooks/"
+llm_context: "high"
+search_keywords:
+  [
+    "testing philosophy",
+    "operator-first testing",
+    "integration testing",
+    "validation testing",
+    "automated qa",
+    "standalone tests",
+    "testing infrastructure"
+  ]
+---
+
+# About Testing in Sirius
+
+## Overview
+
+Testing in Sirius follows an **operator-first philosophy** that prioritizes real-world validation over traditional unit testing. Our testing approach focuses on proving that complete systems, processes, and integrations work correctly in realistic scenarios, rather than testing individual code units in isolation.
+
+## Testing Philosophy
+
+### Operator-First Approach
+
+**Core Principle**: Tests should validate that operators can successfully use the system to accomplish real tasks.
+
+**What This Means**:
+- Tests simulate actual user workflows and operations
+- Validation focuses on end-to-end functionality
+- Tests prove that complete processes work as intended
+- Results must be actionable and meaningful to operators
+
+**Example**: Instead of testing a scanner function in isolation, we test that the scanner can be invoked standalone, process real data, and produce valid results that an operator would actually use.
+
+### Integration-Focused Testing
+
+**Primary Goal**: Validate that different components work together correctly.
+
+**Testing Scope**:
+- Cross-service communication
+- Data flow between components
+- End-to-end process validation
+- Real-world scenario simulation
+
+**Benefits**:
+- Catches integration issues that unit tests miss
+- Validates complete workflows
+- Ensures system reliability for operators
+- Provides confidence in production deployments
+
+## Current Testing Infrastructure
+
+### Container Testing
+
+**Location**: `testing/container-testing/`
+
+**Purpose**: Validate Docker container builds, health, and integration
+
+**What's Tested**:
+- Docker Compose configuration validation
+- Individual container builds (all targets)
+- Service health checks
+- Cross-service communication
+- Integration testing
+
+**Automation**:
+- `make test-all` - Complete test suite
+- `make test-build` - Build validation
+- `make test-health` - Health checks
+- `make test-integration` - Integration testing
+
+### Documentation Testing
+
+**Location**: `testing/documentation/`
+
+**Purpose**: Validate documentation completeness, accuracy, and consistency
+
+**What's Tested**:
+- YAML front matter completeness
+- Template compliance
+- Index completeness
+- Link validation
+- Metadata validity
+
+**Automation**:
+- `make lint-docs` - Full documentation validation
+- `make lint-docs-quick` - Quick validation
+- `make lint-index` - Index completeness check
+
+### Pre-commit Validation
+
+**Location**: `scripts/git-hooks/`
+
+**Purpose**: Quick validation before commits
+
+**What's Tested**:
+- Docker Compose configuration validity
+- Basic syntax checks
+- Quick documentation validation
+- Code formatting
+
+## Testing Standards
+
+### Test Structure
+
+**Standalone Execution**: Every test must be able to run independently without dependencies on the main codebase.
+
+**Real Data**: Tests should use realistic data and scenarios, not mocked or synthetic data.
+
+**Actionable Results**: Test results must provide clear, actionable information for operators and developers.
+
+**Automated Validation**: All tests must be automatable and runnable via command-line tools.
+
+### Test Categories
+
+#### 1. Build Validation Tests
+
+**Purpose**: Ensure components can be built correctly
+
+**Examples**:
+- Docker container builds
+- Multi-stage build validation
+- Architecture compatibility
+- Dependency resolution
+
+**Validation Criteria**:
+- Build completes without errors
+- All build targets work correctly
+- Images are properly tagged
+- Dependencies are resolved
+
+#### 2. Health Validation Tests
+
+**Purpose**: Ensure services start and remain healthy
+
+**Examples**:
+- Service startup validation
+- Health endpoint checks
+- Resource availability
+- Graceful shutdown
+
+**Validation Criteria**:
+- Services start within expected time
+- Health endpoints respond correctly
+- No critical errors in logs
+- Proper resource utilization
+
+#### 3. Integration Validation Tests
+
+**Purpose**: Ensure components work together correctly
+
+**Examples**:
+- Cross-service communication
+- Database connectivity
+- Message queue functionality
+- API endpoint integration
+
+**Validation Criteria**:
+- Services can communicate
+- Data flows correctly
+- APIs respond as expected
+- Error handling works
+
+#### 4. Process Validation Tests
+
+**Purpose**: Ensure complete workflows function correctly
+
+**Examples**:
+- End-to-end scanning processes
+- Data processing pipelines
+- User authentication flows
+- Deployment processes
+
+**Validation Criteria**:
+- Complete workflows execute successfully
+- Results are valid and usable
+- Error conditions are handled
+- Performance meets requirements
+
+## Future Testing Objectives
+
+### Next 3 Months
+
+**Priority 1**: Scanner Testing Infrastructure
+- Standalone scanner execution tests
+- Real vulnerability detection validation
+- Output format verification
+- Performance benchmarking
+
+**Priority 2**: API Testing Infrastructure
+- Endpoint functionality validation
+- Authentication and authorization testing
+- Data validation and error handling
+- Performance and load testing
+
+**Priority 3**: Engine Testing Infrastructure
+- Agent communication testing
+- Task execution validation
+- Resource management testing
+- Error recovery testing
+
+### Long-term Vision
+
+**Comprehensive Test Coverage**: Every major component and process will have dedicated testing infrastructure.
+
+**Automated Validation**: All tests will be integrated into CI/CD pipelines and pre-commit hooks.
+
+**Operator Confidence**: Tests will provide operators with confidence that the system works correctly in production.
+
+**Continuous Improvement**: Testing infrastructure will evolve with the system to maintain high quality standards.
+
+## Testing Best Practices
+
+### For Test Developers
+
+1. **Start with Real Scenarios**: Design tests around actual operator workflows
+2. **Use Real Data**: Test with realistic data, not synthetic or mocked data
+3. **Validate Complete Processes**: Test end-to-end functionality, not just individual components
+4. **Make Tests Standalone**: Ensure tests can run independently without external dependencies
+5. **Provide Clear Results**: Test output should be actionable and meaningful
+
+### For System Developers
+
+1. **Design for Testability**: Build components that can be tested independently
+2. **Expose Health Endpoints**: Provide clear health and status indicators
+3. **Use Standard Interfaces**: Follow consistent patterns for APIs and data formats
+4. **Document Dependencies**: Clearly document what each component needs to function
+5. **Plan for Validation**: Consider how operators will validate that components work correctly
+
+### For Operators
+
+1. **Run Tests Regularly**: Use testing infrastructure to validate system health
+2. **Understand Test Results**: Learn to interpret test output for troubleshooting
+3. **Report Issues**: Use test failures to identify and report problems
+4. **Validate Changes**: Run tests after any system changes or updates
+5. **Trust the Tests**: Use test results to make operational decisions
+
+## Testing Tools and Commands
+
+### Container Testing
+
+```bash
+# Full test suite
+cd testing/container-testing
+make test-all
+
+# Individual tests
+make test-build
+make test-health
+make test-integration
+
+# Quick validation
+make build-all
+```
+
+### Documentation Testing
+
+```bash
+# Full documentation validation
+cd testing/documentation
+make lint-docs
+
+# Quick validation
+make lint-docs-quick
+make lint-index
+```
+
+### Pre-commit Validation
+
+```bash
+# Automatic validation
+git commit  # Runs quick validation automatically
+
+# Manual validation
+cd testing/container-testing
+make build-all
+make lint-docs-quick
+```
+
+## Integration with Development
+
+### CI/CD Pipeline
+
+**Pre-commit**: Quick validation (~30 seconds)
+- Docker Compose configuration validation
+- Basic syntax checks
+- Quick documentation validation
+
+**CI/CD**: Full testing (~5-10 minutes)
+- Complete Docker builds
+- Integration testing
+- Health checks
+- Cross-service communication
+
+### Local Development
+
+**Available Commands**: Developers can run full test suites locally when needed
+
+**Testing Strategy**: Quick validation for commits, full testing for CI and local validation
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Symptoms | Solution |
+|-------|----------|----------|
+| **Test Failures** | Tests fail unexpectedly | Check logs, verify dependencies, run individual tests |
+| **Build Issues** | Docker builds fail | Check Dockerfile syntax, verify base images |
+| **Integration Issues** | Services can't communicate | Check network configuration, verify service health |
+| **Documentation Issues** | Linting fails | Check YAML front matter, verify template compliance |
+
+### Debugging Commands
+
+```bash
+# Check test logs
+cd testing/container-testing
+make logs
+
+# Run individual tests
+make test-build
+make test-health
+
+# Check documentation
+cd testing/documentation
+make lint-docs
+```
+
+## Getting Help
+
+### Documentation
+
+- [README.container-testing.md](README.container-testing.md) - Container testing guide
+- [README.documentation-testing.md](README.documentation-testing.md) - Documentation testing guide
+- [README.cicd.md](../architecture/README.cicd.md) - CI/CD pipeline guide
+
+### Common Issues
+
+- Check test logs for specific error messages
+- Verify all dependencies are available
+- Ensure proper environment configuration
+- Run tests individually to isolate issues
+
+### Support
+
+- Review testing documentation for guidance
+- Check CI/CD logs for automated test results
+- Use local testing for debugging and validation
+- Report issues with specific test output and logs
+
+---
+
+_This testing philosophy guide follows the Sirius Documentation Standard. For specific testing implementation details, see [README.container-testing.md](README.container-testing.md) and [README.documentation-testing.md](README.documentation-testing.md)._

documentation/dev/test/CHECKLIST.testing-by-type.md

@@ -0,0 +1,470 @@
+---
+title: "Testing Checklists by Issue Type"
+description: "Comprehensive testing checklists for different types of changes to ensure thorough validation before merging"
+template: "TEMPLATE.documentation-standard"
+version: "1.0.0"
+last_updated: "2025-10-11"
+author: "Development Team"
+tags: ["testing", "checklist", "validation", "quality-assurance"]
+categories: ["testing", "development"]
+difficulty: "beginner"
+prerequisites: ["docker", "git", "development-environment"]
+related_docs:
+  - "README.container-testing.md"
+  - "../operations/README.git-operations.md"
+dependencies: []
+llm_context: "high"
+search_keywords: ["testing", "checklist", "validation", "qa", "issue-types"]
+---
+
+# Testing Checklists by Issue Type
+
+## Purpose
+
+This document provides specific testing checklists for different types of changes. Use the appropriate checklist based on what components your fix or feature affects.
+
+## When to Use
+
+- **Before committing** any code changes
+- **Before merging** to main/demo branch
+- **During code review** to ensure completeness
+- **After deployment** for verification
+
+## How to Use
+
+1. Identify which type of change you're making
+2. Follow the complete checklist for that type
+3. Check off each item as you test
+4. Document any failures or issues
+5. Only proceed to merge after all checks pass
+
+## Testing Checklists
+
+### Frontend Changes (UI/UX)
+
+**Applies to**: Changes in `sirius-ui/src/pages/`, `sirius-ui/src/components/`
+
+- [ ] **Visual Testing**
+
+  - [ ] Component renders correctly in browser
+  - [ ] Responsive design works on mobile/tablet/desktop
+  - [ ] Dark mode (if applicable) displays correctly
+  - [ ] All buttons and interactive elements are clickable
+  - [ ] No layout breaking or overflow issues
+
+- [ ] **Functional Testing**
+
+  - [ ] All forms submit correctly
+  - [ ] Validation messages display properly
+  - [ ] Error states are handled gracefully
+  - [ ] Loading states display when appropriate
+  - [ ] Success/error toasts appear as expected
+
+- [ ] **Browser Testing**
+
+  - [ ] Chrome/Chromium (primary)
+  - [ ] Firefox (if significant changes)
+  - [ ] Safari (if significant changes)
+
+- [ ] **Accessibility**
+
+  - [ ] Keyboard navigation works
+  - [ ] Screen reader friendly (if major UI change)
+  - [ ] Proper ARIA labels (if applicable)
+
+- [ ] **Container Testing**
+  - [ ] Hot reload works in development mode
+  - [ ] Production build completes successfully
+  - [ ] No console errors in browser
+
+**Container Commands**:
+
+```bash
+# Development mode test
+docker compose up
+
+# Production build test
+docker compose -f docker-compose.yaml up --build
+```
+
+---
+
+### Backend API Changes (TRPC/Routes)
+
+**Applies to**: Changes in `sirius-ui/src/server/api/routers/`
+
+- [ ] **API Endpoint Testing**
+
+  - [ ] Endpoint accepts correct input format
+  - [ ] Endpoint returns expected data structure
+  - [ ] Error cases return appropriate error messages
+  - [ ] HTTP status codes are correct
+  - [ ] Response time is acceptable
+
+- [ ] **Data Validation**
+
+  - [ ] Input validation works (Zod schemas)
+  - [ ] Required fields are enforced
+  - [ ] Type coercion works correctly
+  - [ ] Invalid data is rejected with clear errors
+
+- [ ] **Authentication/Authorization**
+
+  - [ ] Protected endpoints require authentication
+  - [ ] Session/JWT validation works
+  - [ ] Unauthorized access is blocked
+
+- [ ] **Database Interaction**
+
+  - [ ] Queries return expected data
+  - [ ] No SQL injection vulnerabilities
+  - [ ] Transactions complete successfully
+  - [ ] Error handling for database failures
+
+- [ ] **Container Testing**
+  - [ ] Check logs for errors: `docker compose logs sirius-ui`
+  - [ ] Verify no crashes or exceptions
+  - [ ] Test with development and production builds
+
+**Testing Example**:
+
+```bash
+# Watch container logs during testing
+docker compose logs -f sirius-ui
+
+# Test endpoint via browser console or Postman
+# Verify response structure and error handling
+```
+
+---
+
+### Database Schema Changes
+
+**Applies to**: Changes in `sirius-ui/prisma/schema.prisma`, migrations
+
+- [ ] **Schema Validation**
+
+  - [ ] Prisma schema is valid: `npx prisma validate`
+  - [ ] Migration generates correctly: `npx prisma migrate dev`
+  - [ ] No conflicting field types
+  - [ ] Relationships are correctly defined
+
+- [ ] **Migration Testing**
+
+  - [ ] Migration runs successfully on clean database
+  - [ ] Migration is reversible (if needed)
+  - [ ] Existing data is preserved (if applicable)
+  - [ ] Seed script works with new schema
+
+- [ ] **Application Testing**
+
+  - [ ] All queries still work
+  - [ ] CRUD operations function correctly
+  - [ ] No type errors in TypeScript
+  - [ ] Prisma Client regenerates correctly
+
+- [ ] **Data Integrity**
+  - [ ] Foreign keys are enforced
+  - [ ] Unique constraints work
+  - [ ] Default values are applied
+  - [ ] Required fields are enforced
+
+**Container Commands**:
+
+```bash
+# Inside container
+docker exec -it sirius-ui npx prisma db push --force-reset
+docker exec -it sirius-ui npm run seed
+
+# Verify schema
+docker exec -it sirius-ui npx prisma validate
+
+# Check generated client
+docker exec -it sirius-ui npx prisma generate
+```
+
+---
+
+### Authentication Changes
+
+**Applies to**: Changes in `sirius-ui/src/server/auth.ts`, auth-related endpoints
+
+- [ ] **Login/Logout Testing**
+
+  - [ ] Can log in with valid credentials
+  - [ ] Login fails with invalid credentials
+  - [ ] Logout clears session correctly
+  - [ ] Session persists across page refreshes
+
+- [ ] **Session Management**
+
+  - [ ] Session timeout works correctly
+  - [ ] JWT tokens are generated properly
+  - [ ] Token expiration is handled
+  - [ ] Refresh tokens work (if implemented)
+
+- [ ] **Password Security**
+
+  - [ ] Passwords are hashed (never stored plain text)
+  - [ ] Password reset works correctly
+  - [ ] Old password verification works
+  - [ ] Password requirements are enforced
+
+- [ ] **Protected Routes**
+
+  - [ ] Unauthorized users are redirected to login
+  - [ ] Authorized users can access protected pages
+  - [ ] Session state is checked on route changes
+
+- [ ] **Database State**
+  - [ ] User records are created/updated correctly
+  - [ ] Can reset database to default credentials
+  - [ ] Seed script recreates admin user
+
+**Testing Commands**:
+
+```bash
+# Reset database to default credentials
+docker exec -it sirius-ui npx prisma db push --force-reset
+docker exec -it sirius-ui npm run seed
+
+# Default credentials: admin / password
+```
+
+**Important**: After testing authentication changes, **reset the database** so other developers aren't affected:
+
+```bash
+docker exec -it sirius-ui npm run seed
+```
+
+---
+
+### Docker/Container Changes
+
+**Applies to**: Changes in `Dockerfile`, `docker-compose.yaml`, startup scripts
+
+- [ ] **Build Testing**
+
+  - [ ] Development image builds successfully
+  - [ ] Production image builds successfully
+  - [ ] Build time is reasonable
+  - [ ] Image size is acceptable
+
+- [ ] **Runtime Testing**
+
+  - [ ] Container starts successfully
+  - [ ] All processes run correctly
+  - [ ] Environment variables are loaded
+  - [ ] Healthchecks pass
+
+- [ ] **Development Mode**
+
+  - [ ] Hot reload works
+  - [ ] Volume mounts work correctly
+  - [ ] Source code changes reflect immediately
+  - [ ] Debugging is possible
+
+- [ ] **Production Mode**
+
+  - [ ] Optimized build runs correctly
+  - [ ] No development dependencies in final image
+  - [ ] Security scanning passes (if applicable)
+  - [ ] Startup time is acceptable
+
+- [ ] **Multi-Container Testing**
+  - [ ] All containers start together
+  - [ ] Services can communicate
+  - [ ] Networking is configured correctly
+  - [ ] Dependencies start in correct order
+
+**Testing Commands**:
+
+```bash
+# Test development build
+docker compose up --build
+
+# Test production build
+docker compose -f docker-compose.yaml up --build
+
+# Check container health
+docker compose ps
+
+# View logs for debugging
+docker compose logs -f [service-name]
+
+# Test rebuild after changes
+docker compose down
+docker compose up --build
+```
+
+---
+
+### Documentation Changes
+
+**Applies to**: Changes in `documentation/` directory
+
+- [ ] **Content Quality**
+
+  - [ ] YAML front matter is complete and valid
+  - [ ] All required sections are present
+  - [ ] Examples are accurate and tested
+  - [ ] Links are valid and working
+  - [ ] Code snippets are correct
+
+- [ ] **Structure Validation**
+
+  - [ ] Follows appropriate template
+  - [ ] Consistent formatting throughout
+  - [ ] Proper markdown syntax
+  - [ ] Headings are hierarchical
+
+- [ ] **Documentation Index**
+
+  - [ ] File is added to `README.documentation-index.md`
+  - [ ] Categorized correctly
+  - [ ] Description is accurate
+
+- [ ] **Pre-commit Checks**
+  - [ ] Quick documentation checks pass
+  - [ ] Index completeness validation passes
+  - [ ] No linting errors
+
+**Testing Commands**:
+
+```bash
+cd testing
+make lint-docs-quick  # Quick validation
+make lint-docs         # Full validation
+make lint-index        # Index completeness check
+```
+
+---
+
+### Git Operations Changes
+
+**Applies to**: Changes in pre-commit hooks, git workflows
+
+- [ ] **Pre-commit Hook Testing**
+
+  - [ ] Hook runs on commit attempt
+  - [ ] Checks execute correctly
+  - [ ] Failures block commit appropriately
+  - [ ] Success allows commit to proceed
+
+- [ ] **Workflow Testing**
+
+  - [ ] Test on feature branch
+  - [ ] Test on main/demo branch
+  - [ ] Verify branch detection logic
+  - [ ] Check optimization flags work
+
+- [ ] **Documentation**
+  - [ ] New workflow is documented
+  - [ ] Examples are provided
+  - [ ] Troubleshooting section added
+
+**Testing Commands**:
+
+```bash
+# Test pre-commit hook
+git add .
+git commit -m "test: validate pre-commit hook"
+
+# Test on feature branch
+git checkout -b test/pre-commit-test
+# Make a change and commit
+
+# Test failure cases
+# Intentionally create validation failure
+```
+
+---
+
+## Post-Merge Verification
+
+After merging to main/demo, verify:
+
+- [ ] **Container Health**
+
+  - [ ] All containers start successfully
+  - [ ] No errors in logs
+  - [ ] Services respond to requests
+
+- [ ] **Functionality Check**
+
+  - [ ] Core features still work
+  - [ ] No regressions introduced
+  - [ ] New feature/fix works as expected
+
+- [ ] **Rollback Preparedness**
+  - [ ] Know the last good commit hash
+  - [ ] Can quickly revert if needed
+  - [ ] Team is notified of deployment
+
+---
+
+## Troubleshooting Testing Issues
+
+### Container Won't Start
+
+```bash
+# Check logs
+docker compose logs [service-name]
+
+# Rebuild from scratch
+docker compose down -v
+docker compose build --no-cache
+docker compose up
+```
+
+### Database Issues
+
+```bash
+# Reset database
+docker exec -it sirius-ui npx prisma db push --force-reset
+docker exec -it sirius-ui npm run seed
+```
+
+### Network Issues
+
+```bash
+# Check container networking
+docker network ls
+docker network inspect sirius_default
+
+# Restart containers
+docker compose restart
+```
+
+### Build Issues
+
+```bash
+# Clear Docker cache
+docker builder prune -a
+
+# Rebuild specific service
+docker compose build --no-cache [service-name]
+```
+
+---
+
+## Continuous Improvement
+
+**Add new checklists** as you encounter new types of issues:
+
+1. Document what testing was needed
+2. Create a new checklist section
+3. Include specific commands and examples
+4. Update this document
+5. Notify team of new checklist
+
+**Update existing checklists** based on:
+
+- Issues that slipped through testing
+- New tools or testing approaches
+- Feedback from team members
+- Changes in technology stack
+
+---
+
+_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._

documentation/dev/test/README.container-testing.md

@@ -0,0 +1,470 @@
+---
+title: "Container Testing"
+description: "Comprehensive container testing system for Sirius Scan, providing automated validation of Docker builds, service health, and integration before production deployment"
+template: "TEMPLATE.documentation-standard"
+version: "1.0.0"
+last_updated: "2025-01-03"
+author: "Development Team"
+tags: ["docker", "testing", "containers", "ci-cd", "validation"]
+categories: ["development", "testing", "infrastructure"]
+difficulty: "intermediate"
+prerequisites: ["docker", "make", "bash"]
+related_docs:
+  - "README.development.md"
+  - "ABOUT.documentation.md"
+dependencies:
+  - "docker-compose.yaml"
+  - "testing/container-testing/"
+  - "testing/Makefile"
+llm_context: "high"
+search_keywords:
+  ["container", "testing", "docker", "health-check", "validation", "ci-cd"]
+---
+
+# Container Testing
+
+## Purpose
+
+This document describes the comprehensive container testing system for SiriusScan, providing automated validation of Docker builds, service health, and integration before production deployment. It serves as the definitive guide for developers and DevOps engineers who need to ensure container reliability and system integrity.
+
+## When to Use
+
+- **Before every production deployment** - Validate that all containers build and function correctly
+- **After making changes to Dockerfiles** - Ensure modifications don't break the build process
+- **During development cycles** - Catch container issues early in the development process
+- **When troubleshooting container issues** - Use health checks and integration tests to diagnose problems
+- **In CI/CD pipelines** - Automated validation of container builds and functionality
+- **When onboarding new team members** - Understand the testing infrastructure and processes
+
+## How to Use
+
+### Quick Start
+
+```bash
+# Navigate to container testing directory
+cd testing/container-testing
+
+# Run complete test suite (includes runtime auth contract — see below)
+make test-all
+
+# Run specific test types
+make test-build    # Build validation only
+make test-health   # Health checks only
+make test-integration  # Integration tests only
+make test-runtime-contract  # SIRIUS_API_KEY parity, engine preflight script, API HTTP contract
+make test-public-ghcr  # anonymous GHCR access for the compose-rendered IMAGE_TAG
+make test-release-gates  # test-build + test-integration + test-runtime-contract (release bar)
+
+# Test specific environment
+make test-dev      # Development environment
+make test-prod     # Production environment
+```
+
+**Alternative: Run scripts directly from project root**
+
+```bash
+# From project root directory
+./testing/container-testing/test-integration.sh
+./testing/container-testing/test-health.sh
+./testing/container-testing/test-build.sh
+```
+
+### Prerequisites
+
+- Docker Engine 20.10.0+
+- Docker Compose V2
+- Make utility
+- curl, nc (netcat), jq (for health checks)
+- 4GB RAM minimum (8GB recommended)
+
+### Step-by-Step Process
+
+1. **Navigate to container testing directory**: `cd /path/to/Sirius/testing/container-testing`
+2. **Run build tests**: `make test-build` to validate all containers build successfully
+3. **Run health tests**: `make test-health` to verify services start and respond correctly
+4. **Run integration tests**: `make test-integration` to test service interactions
+5. **`make test-all` also runs `test-runtime-contract`**, which starts the stack from the repo root and runs `scripts/verify-runtime-auth-contract.sh` (shared `SIRIUS_API_KEY`, postgres parity, authenticated `GET /host/`).
+6. **Review results**: Check test output and logs in `testing/logs/` directory
+
+**Alternative approach** (from project root):
+
+1. **Navigate to project root**: `cd /path/to/Sirius`
+2. **Run tests directly**: `./testing/container-testing/test-integration.sh`
+3. **Review results**: Check test output and logs in `testing/logs/` directory
+
+## What It Is
+
+### Architecture Overview
+
+The container testing system consists of these main components:
+
+- **Build Validation**: Tests individual container builds and Docker Compose configurations
+- **Health Checks**: Validates service startup, connectivity, and basic functionality
+- **Integration Tests**: Verifies inter-service communication and data flow
+- **Runtime Auth Contract** (`make test-runtime-contract`): Runs [`scripts/verify-runtime-auth-contract.sh`](../../../scripts/verify-runtime-auth-contract.sh) against a running stack. Default container names match `container_name` in `docker-compose.yaml` (`sirius-ui`, `sirius-api`, etc.). For a non-default Compose project (e.g. `name: sirius-test`), set `SIRIUS_CONTRACT_CONTAINER_UI`, `SIRIUS_CONTRACT_CONTAINER_API`, `SIRIUS_CONTRACT_CONTAINER_ENGINE`, and `SIRIUS_CONTRACT_CONTAINER_POSTGRES` before running the script. Use `SIRIUS_API_PUBLIC_URL` if the API is not on `http://localhost:9001`.
+- **Public GHCR Contract** (`make test-public-ghcr`): Runs [`scripts/verify-ghcr-public-access.sh`](../../../scripts/verify-ghcr-public-access.sh) with the selected `IMAGE_TAG` and checks the exact image refs rendered by `docker-compose.yaml`. Failures distinguish `unauthorized` (visibility/token problem) from `manifest unknown` (tag publication problem).
+
+### Technical Details
+
+#### Build Testing System
+
+**Purpose**: Ensures all containers can be built successfully with correct configurations.
+
+**Components**:
+
+- `testing/container-testing/test-build.sh` - Main build validation script
+- Tests all Docker Compose configurations (base, dev, prod)
+- Validates individual container builds for all services
+- Cleans up test images after completion
+
+**Services Tested**:
+
+- `sirius-ui` (Next.js frontend)
+- `sirius-api` (Go REST API)
+- `sirius-engine` (Multi-service container)
+- `sirius-postgres` (Database)
+- `sirius-valkey` (Cache)
+- `sirius-rabbitmq` (Message queue)
+
+**Build Targets Validated**:
+
+- Production builds (`production`, `runner`, `runtime` stages)
+- Development builds (`development` stage)
+- Multi-stage Dockerfile validation
+
+#### Health Check System
+
+**Purpose**: Verifies that all services start correctly and respond to basic health checks.
+
+**Components**:
+
+- `testing/container-testing/test-health.sh` - Health validation script
+- Service-specific health endpoints
+- Database connectivity tests
+- Port accessibility validation
+
+**Health Checks Performed**:
+
+1. **Container Status**: All 6 containers running and healthy
+2. **UI Health**: Next.js application serving content on port 3000
+3. **API Health**: Go API responding on port 9001 with `/health` endpoint
+4. **Engine Health**: Process validation for sirius-engine container
+5. **Database Health**: PostgreSQL connectivity and readiness
+6. **Cache Health**: Valkey/Redis responding to ping commands
+7. **Queue Health**: RabbitMQ broker status and connectivity
+8. **Port Accessibility**: External port binding validation
+
+#### Integration Testing System
+
+**Purpose**: Tests inter-service communication and data flow between components.
+
+**Components**:
+
+- `testing/container-testing/test-integration.sh` - Integration validation script
+- Service-to-service communication tests
+- Database integration validation
+- Message queue functionality tests
+
+**Integration Tests**:
+
+- API to Database connectivity
+- UI to API communication
+- Engine to Message Queue integration
+- Cross-service data validation
+
+### Implementation Details
+
+#### File Structure
+
+```
+testing/
+├── container-testing/
+│   ├── test-build.sh          # Build validation
+│   ├── test-health.sh         # Health checks
+│   ├── test-integration.sh    # Integration tests
+│   └── Makefile               # Container testing commands
+├── logs/                      # Test execution logs
+│   ├── build_test_*.log
+│   ├── health_test_*.log
+│   └── integration_test_*.log
+└── README.md                  # Testing documentation
+```
+
+**Note**: The Makefile is located in the `container-testing/` directory and should be run from there. The test scripts can be run either from the `container-testing/` directory via Makefile or directly from the project root.
+
+#### Makefile Integration
+
+The testing system uses a dedicated Makefile in the `container-testing/` directory:
+
+```makefile
+# Testing targets (run from testing/container-testing/)
+test-all: test-build test-health test-integration
+test-build: ./test-build.sh
+test-health: ./test-health.sh
+test-integration: ./test-integration.sh
+
+# Environment-specific testing
+test-dev: ./test-health.sh dev
+test-prod: ./test-health.sh prod
+```
+
+**Usage**:
+
+- Run from `testing/container-testing/` directory: `make test-all`
+- Or run scripts directly from project root: `./testing/container-testing/test-integration.sh`
+
+#### Logging and Reporting
+
+**Log Files**: All test executions create timestamped log files in `testing/logs/`
+
+- Format: `{test_type}_test_{timestamp}.log`
+- Contains: Full command output, test results, error details
+- Retention: Logs are kept for troubleshooting and analysis
+
+**Test Results**: Each test provides clear pass/fail indicators:
+
+- ✅ PASSED: Test completed successfully
+- ❌ FAILED: Test failed with error details
+- Summary: Total tests, passed, failed counts
+
+#### Environment Support
+
+**Development Environment**:
+
+- Uses `docker-compose.dev.yaml` overrides
+- Includes volume mounts for live development
+- Accounts for longer startup times due to dependency downloads
+
+**Production Environment**:
+
+- Uses `docker-compose.prod.yaml` overrides
+- Tests production-optimized builds
+- Validates production configuration
+
+**Base Environment**:
+
+- Uses standard `docker-compose.yaml`
+- Tests default configuration
+- Validates core functionality
+
+### Advanced Topics
+
+#### Custom Test Configuration
+
+**Environment Variables**:
+
+```bash
+export TEST_RETRIES=120         # Retry attempts (default: 60, dev mode: 120)
+export LOG_LEVEL=debug          # Logging verbosity (info, debug)
+```
+
+**Timeout Configuration**:
+
+- **Default**: 60 retries × 2 seconds = 120 seconds total
+- **Development Mode**: Automatically increases to 120 retries × 2 seconds = 240 seconds total
+- **Custom**: Override with `TEST_RETRIES` environment variable
+
+**Custom Test Execution**:
+
+```bash
+# Run with custom timeout (4 minutes)
+TEST_RETRIES=120 ./testing/scripts/test-health.sh dev
+
+# Run with debug logging
+LOG_LEVEL=debug ./testing/scripts/test-health.sh dev
+
+# Run with both custom timeout and debug logging
+TEST_RETRIES=180 LOG_LEVEL=debug ./testing/scripts/test-health.sh dev
+```
+
+#### Performance Monitoring
+
+**Resource Usage Tracking**:
+
+- Container startup times
+- Memory and CPU usage during tests
+- Build time optimization
+- Service response times
+
+**Optimization Opportunities**:
+
+- Parallel test execution
+- Build cache utilization
+- Service startup optimization
+- Resource limit tuning
+
+#### Security Considerations
+
+**Test Isolation**:
+
+- Tests run in isolated Docker networks
+- No external network access during testing
+- Cleanup procedures remove all test artifacts
+
+**Security Validation**:
+
+- Container security scanning (future enhancement)
+- Vulnerability assessment (future enhancement)
+- Secret management validation (future enhancement)
+
+## Troubleshooting
+
+### FAQ
+
+**Q: Why do health tests fail with "API not ready yet" errors?**
+A: The sirius-api service takes time to download Go dependencies in development mode. The health check automatically increases timeout to 4 minutes for dev mode, and includes fallback validation for this scenario.
+
+**Q: Why does development mode take longer than production mode?**
+A: Development mode downloads Go dependencies at runtime, which can take 2-4 minutes depending on your internet connection. Production mode pre-builds these dependencies, so it starts much faster.
+
+**Q: How do I run tests for a specific service only?**
+A: Modify the test scripts to comment out unwanted services, or use Docker Compose to start only the services you need to test.
+
+**Q: What if build tests fail with "target stage not found" errors?**
+A: Check that Docker Compose files reference correct Dockerfile stage names. Common stages are `development`, `production`, `runtime`, and `runner`.
+
+**Q: How can I increase test timeout for slow systems?**
+A: Set the `TEST_RETRIES` environment variable: `export TEST_RETRIES=120 && make test-health` (120 retries = 4 minutes total)
+
+**Q: Why do integration tests fail with connection refused errors?**
+A: Ensure all services are fully started before running integration tests. Use `docker compose ps` to verify service status.
+
+**Q: How do I debug a specific test failure?**
+A: Check the timestamped log file in `testing/logs/` for detailed error information and command output.
+
+**Q: Can I run tests in parallel?**
+A: Currently tests run sequentially to avoid resource conflicts. Parallel execution is planned for future enhancement.
+
+**Q: What if I need to test with custom Docker images?**
+A: Modify the test scripts to use your custom image tags, or update the Docker Compose files to reference your images.
+
+### Command Reference
+
+```bash
+# From testing/container-testing/ directory
+make test-all
+make test-build
+make test-health
+make test-integration
+make test-public-ghcr
+make test-dev
+make test-prod
+
+# Or from project root directory
+./testing/container-testing/test-build.sh
+./testing/container-testing/test-health.sh dev
+./testing/container-testing/test-integration.sh prod
+
+# Docker Compose validation
+docker compose config --quiet
+docker compose -f docker-compose.yaml -f docker-compose.dev.yaml config --quiet
+
+# Service health checks
+docker compose ps
+docker compose logs sirius-api
+curl -f http://localhost:9001/health
+
+# Container debugging
+docker exec -it sirius-engine /bin/bash
+docker logs sirius-engine --tail 50 -f
+
+# Cleanup
+docker compose down -v
+docker system prune -f
+```
+
+### Common Issues and Solutions
+
+| Issue                 | Symptoms                          | Solution                                                  |
+| --------------------- | --------------------------------- | --------------------------------------------------------- |
+| Build failures        | "target stage not found" errors   | Check Dockerfile stage names in Compose files             |
+| Health check timeouts | "service not ready" errors        | Increase timeout or check service logs                    |
+| Port conflicts        | "port already in use" errors      | Stop conflicting services or change ports                 |
+| Permission errors     | "permission denied" in containers | Check file permissions and Docker daemon access           |
+| Network issues        | "connection refused" errors       | Verify Docker network configuration                       |
+| Resource exhaustion   | Out of memory errors              | Increase Docker memory limits or close other applications |
+
+### Debugging Steps
+
+1. **Check service status**: `docker compose ps` to see which containers are running
+2. **Review service logs**: `docker compose logs [service-name]` for error details
+3. **Verify network connectivity**: `docker network ls` and `docker network inspect sirius`
+4. **Test individual components**: Run health checks manually with curl commands
+5. **Check resource usage**: `docker stats` to monitor CPU and memory usage
+6. **Validate configuration**: `docker compose config` to check for syntax errors
+
+### Log Analysis
+
+**Build Test Logs**:
+
+```bash
+# View build test results
+tail -f testing/logs/build_test_*.log
+
+# Check for specific errors
+grep -i "error\|failed" testing/logs/build_test_*.log
+```
+
+**Health Test Logs**:
+
+```bash
+# Monitor health check progress
+tail -f testing/logs/health_test_*.log
+
+# Find failed tests
+grep -i "failed\|error" testing/logs/health_test_*.log
+```
+
+**Integration Test Logs**:
+
+```bash
+# Check integration test results
+cat testing/logs/integration_test_*.log
+
+# Analyze service communication
+grep -i "connection\|timeout" testing/logs/integration_test_*.log
+```
+
+### Performance Troubleshooting
+
+**Slow Build Times**:
+
+- Check Docker BuildKit is enabled: `export DOCKER_BUILDKIT=1`
+- Clear Docker cache: `docker builder prune`
+- Use build cache mounts for dependencies
+
+**Slow Service Startup**:
+
+- Check system resources: `docker stats`
+- Optimize Dockerfile layers
+- Use multi-stage builds efficiently
+
+**Test Execution Time**:
+
+- Run tests in parallel (future enhancement)
+- Optimize health check intervals
+- Use faster base images where possible
+
+### Lessons Learned
+
+**2025-01-03**: Implemented comprehensive container testing system to address build reliability issues. Key insight: Automated testing prevents deployment failures and improves development confidence.
+
+**2025-01-03**: Created health check system with fallback validation for services with longer startup times. Lesson: Account for real-world service startup patterns in test design.
+
+**2025-01-03**: Established layered testing approach (build → health → integration). Benefit: Catches issues at appropriate levels and provides clear failure isolation.
+
+**2025-01-03**: Implemented timestamped logging system for all test executions. Advantage: Enables detailed troubleshooting and historical analysis of test failures.
+
+## LLM Context
+
+[Additional context specifically for Large Language Models:]
+
+- **Key Concepts**: Container testing involves build validation, health checks, and integration testing to ensure Docker containers work correctly before deployment
+- **Technical Context**: Uses Docker Compose for orchestration, shell scripts for automation, and Make for command execution. Tests cover 6 services: UI, API, Engine, PostgreSQL, Valkey, and RabbitMQ
+- **Common Patterns**: Layered testing approach (build → health → integration), automated cleanup, timestamped logging, environment-specific configurations
+- **Edge Cases**: API dependency downloading in dev mode, service startup timing variations, port conflicts, resource constraints
+- **Integration Points**: Connects with CI/CD pipelines, deployment processes, monitoring systems, and development workflows
+
+---
+
+_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._

documentation/dev/test/README.documentation-testing.md

@@ -0,0 +1,437 @@
+---
+title: "Documentation Testing"
+description: "Comprehensive documentation testing system for Sirius project, providing automated validation of documentation quality, structure, and completeness using specialized linters."
+template: "TEMPLATE.documentation-standard"
+version: "1.0.0"
+last_updated: "2025-01-03"
+author: "Development Team"
+tags: ["documentation", "testing", "linting", "validation", "quality"]
+categories: ["development", "testing", "documentation"]
+difficulty: "intermediate"
+prerequisites: ["markdown", "yaml", "bash"]
+related_docs:
+  - "README.container-testing.md"
+  - "ABOUT.documentation.md"
+dependencies:
+  - "scripts/documentation/"
+  - "testing/Makefile"
+llm_context: "high"
+search_keywords:
+  ["documentation", "testing", "linting", "validation", "yaml", "markdown"]
+---
+
+# Documentation Testing
+
+## Purpose
+
+This document describes the comprehensive documentation testing system for the Sirius project, providing automated validation of documentation quality, structure, and completeness. It serves as the definitive guide for developers and technical writers who need to ensure documentation meets our standards and is optimized for LLM consumption.
+
+## When to Use
+
+- **Before committing documentation changes** - Validate that all documentation meets our standards
+- **During documentation reviews** - Ensure consistency and completeness across all docs
+- **When creating new documentation** - Verify proper structure and metadata
+- **In CI/CD pipelines** - Automated validation of documentation quality
+- **When troubleshooting documentation issues** - Use linters to identify specific problems
+- **For LLM optimization** - Ensure documentation is properly structured for AI consumption
+
+## How to Use
+
+### Quick Start
+
+```bash
+# Navigate to container testing directory
+cd testing/container-testing
+
+# Run complete documentation testing
+make lint-docs
+
+# Run quick documentation checks
+make lint-docs-quick
+
+# Check documentation index completeness
+make lint-index
+
+# Run all validation including documentation
+make validate-all
+```
+
+### Prerequisites
+
+- Bash shell environment
+- `yq` utility (for full YAML validation)
+- `grep`, `sed`, `awk` (standard Unix tools)
+- Make utility
+- Git (for pre-commit hooks)
+
+### Step-by-Step Process
+
+1. **Navigate to container testing directory**: `cd /path/to/Sirius/testing/container-testing`
+2. **Run quick checks**: `make lint-docs-quick` for basic validation
+3. **Run full linting**: `make lint-docs` for comprehensive validation
+4. **Check index completeness**: `make lint-index` to verify all files are indexed
+5. **Review results**: Check output and logs in `tmp/` directory
+
+## What It Is
+
+### Architecture Overview
+
+The documentation testing system consists of three main components:
+
+- **YAML Front Matter Validation**: Ensures all documents have complete and valid metadata
+- **Template Compliance Checking**: Verifies documents follow their specified templates
+- **Index Completeness Validation**: Ensures all documentation files are properly indexed
+
+### Technical Details
+
+#### YAML Front Matter Validation
+
+**Purpose**: Ensures all documentation files have complete and valid YAML front matter.
+
+**Components**:
+
+- `scripts/documentation/lint-docs.sh` - Main validation script
+- `scripts/documentation/lint-quick.sh` - Quick validation script
+- Validates required and optional fields
+- Checks field value validity
+
+**Required Fields**:
+
+- `title` - Human-readable document title
+- `description` - Brief purpose description
+- `template` - Template used to create document
+- `version` - Document version
+- `last_updated` - Last modification date
+
+**Optional Fields**:
+
+- `author` - Document author
+- `tags` - Searchable tags
+- `categories` - Document categories
+- `difficulty` - Complexity level (beginner, intermediate, advanced)
+- `prerequisites` - Required knowledge
+- `related_docs` - Related documentation
+- `dependencies` - Required files/systems
+- `llm_context` - LLM relevance level (high, medium, low)
+- `search_keywords` - Search optimization
+
+**Validation Rules**:
+
+- YAML syntax must be valid
+- Required fields must be present
+- Field values must match valid options
+- Template references must exist
+- Related documents must exist
+
+#### Template Compliance Checking
+
+**Purpose**: Verifies that documents follow their specified template structure.
+
+**Components**:
+
+- Template file parsing and section extraction
+- Document section comparison
+- Missing section detection
+- Custom document support
+
+**Supported Templates**:
+
+- `TEMPLATE.documentation-standard` - Standard documentation
+- `TEMPLATE.guide` - Step-by-step guides
+- `TEMPLATE.troubleshooting` - Problem-solving docs
+- `TEMPLATE.about` - About documents
+- `TEMPLATE.reference` - Technical specifications
+- `TEMPLATE.architecture` - System design docs
+- `TEMPLATE.api` - API documentation
+- `TEMPLATE.template` - Template documents
+- `TEMPLATE.custom` - Custom documents (no compliance checking)
+
+**Compliance Rules**:
+
+- Documents must have all required sections from their template
+- Section headings must match exactly
+- Custom documents are exempt from compliance checking
+- Meta-documents (ABOUT files) are exempt from compliance checking
+
+#### Index Completeness Validation
+
+**Purpose**: Ensures all documentation files are properly referenced in the documentation index.
+
+**Components**:
+
+- `scripts/documentation/lint-index.sh` - Index validation script
+- File discovery in `documentation/dev/` directory
+- Index parsing and link extraction
+- Missing file detection
+- Extra file detection
+
+**Validation Rules**:
+
+- All files in `dev/` must be referenced in the index
+- All referenced files must exist in `dev/`
+- No duplicate references allowed
+- Footer links are excluded from validation
+
+### Implementation Details
+
+#### File Structure
+
+```
+scripts/documentation/
+├── lint-docs.sh              # Full documentation linting
+├── lint-quick.sh             # Quick documentation checks
+└── lint-index.sh             # Index completeness validation
+
+testing/
+├── Makefile                  # Testing commands
+└── tmp/                      # Linting logs and output
+    ├── documentation-lint-*.log
+    └── index-lint-*.log
+```
+
+#### Makefile Integration
+
+The documentation testing system integrates with the testing Makefile:
+
+```makefile
+# Documentation testing targets
+lint-docs: ../scripts/documentation/lint-docs.sh
+lint-docs-quick: ../scripts/documentation/lint-quick.sh
+lint-index: ../scripts/documentation/lint-index.sh
+
+# Full validation including documentation
+validate-all: build-all test-all lint-docs
+```
+
+#### Logging and Reporting
+
+**Log Files**: All linting executions create timestamped log files in `tmp/`
+
+- Format: `{lint_type}-{timestamp}.log`
+- Contains: Full validation output, errors, warnings
+- Retention: Logs are kept for troubleshooting
+
+**Validation Results**: Each validation provides clear indicators:
+
+- ✅ PASSED: Validation completed successfully
+- ❌ FAILED: Validation failed with error details
+- ⚠️ WARNING: Non-critical issues found
+- Summary: Total files, passed, failed counts
+
+#### Pre-commit Integration
+
+**Pre-commit Hook**: `.git/hooks/pre-commit` runs documentation validation:
+
+1. **Quick documentation linting** - Basic validation
+2. **Index completeness check** - Ensures all files are indexed
+3. **Build tests** - Validates system still works
+
+**Hook Behavior**:
+
+- Runs from project root or testing directory
+- Fails commit if validation fails
+- Provides clear error messages
+- Suggests fixes for common issues
+
+### Advanced Topics
+
+#### Custom Validation Rules
+
+**Environment Variables**:
+
+```bash
+export DOCS_DIR="../documentation/dev"     # Documentation directory
+export TEMPLATES_DIR="../documentation/dev/templates"  # Templates directory
+export LOG_LEVEL="debug"                   # Logging verbosity
+```
+
+**Custom Validation**:
+
+```bash
+# Run with custom documentation directory
+DOCS_DIR="../custom-docs" make lint-docs
+
+# Run with debug logging
+LOG_LEVEL="debug" make lint-docs
+
+# Run with custom template directory
+TEMPLATES_DIR="../custom-templates" make lint-docs
+```
+
+#### Template Development
+
+**Creating New Templates**:
+
+1. **Copy base template**: `cp TEMPLATE.template.md TEMPLATE.new-type.md`
+2. **Define structure**: Add required sections for new document type
+3. **Update validation**: Add new template to `VALID_TEMPLATES` array
+4. **Test validation**: Run `make lint-docs` to verify template works
+
+**Template Requirements**:
+
+- Must include YAML front matter
+- Must define clear section structure
+- Must be self-documenting
+- Must follow naming conventions
+
+#### LLM Optimization
+
+**Context Building**:
+
+- Rich metadata in front matter
+- Consistent structure across documents
+- Clear relationships between documents
+- Comprehensive search keywords
+
+**AI-Friendly Features**:
+
+- Structured content for predictable parsing
+- Detailed descriptions for AI understanding
+- Working examples with expected outputs
+- Comprehensive troubleshooting information
+
+## Troubleshooting
+
+### FAQ
+
+**Q: Why do I get "Template file not found" warnings?**
+A: The quick linter looks for template files in the wrong location. This is a known issue and doesn't affect functionality. Use `make lint-docs` for accurate validation.
+
+**Q: Why does index linting fail with "Missing from index" errors?**
+A: Some documentation files are not referenced in the documentation index. Add them to `documentation/README.documentation-index.md` or remove unused files.
+
+**Q: How do I fix "Invalid difficulty value" errors?**
+A: Difficulty must be one of: "beginner", "intermediate", "advanced". Check your YAML front matter for typos.
+
+**Q: Why do I get "Missing section" warnings?**
+A: Your document is missing required sections from its template. Compare your document structure with the template file.
+
+**Q: How do I add a new document type?**
+A: Create a new template file, add it to the validation system, and update the documentation index.
+
+**Q: Why does pre-commit hook fail?**
+A: Check the error messages in the terminal. Common issues include missing YAML front matter, invalid field values, or missing index entries.
+
+**Q: How do I disable validation for a specific document?**
+A: Use `TEMPLATE.custom` template type, which skips template compliance checking.
+
+**Q: Can I run validation on specific files only?**
+A: Modify the linting scripts to target specific files, or use grep to filter the file list.
+
+### Command Reference
+
+```bash
+# Complete documentation validation
+make lint-docs
+
+# Quick documentation checks
+make lint-docs-quick
+
+# Index completeness validation
+make lint-index
+
+# Full system validation
+make validate-all
+
+# Manual script execution
+../scripts/documentation/lint-docs.sh
+../scripts/documentation/lint-quick.sh
+../scripts/documentation/lint-index.sh
+
+# Check specific validation
+grep -r "template:" ../documentation/dev/
+grep -r "llm_context: high" ../documentation/dev/
+grep -r "difficulty:" ../documentation/dev/
+
+# Debug validation issues
+LOG_LEVEL=debug make lint-docs
+tail -f tmp/documentation-lint-*.log
+```
+
+### Common Issues and Solutions
+
+| Issue                | Symptoms                          | Solution                                            |
+| -------------------- | --------------------------------- | --------------------------------------------------- |
+| Missing front matter | "No YAML metadata" errors         | Add complete YAML front matter with required fields |
+| Invalid field values | "Invalid difficulty value" errors | Check field values against valid options            |
+| Template compliance  | "Missing section" warnings        | Compare document structure with template            |
+| Index completeness   | "Missing from index" errors       | Add files to documentation index                    |
+| Broken links         | "File not found" errors           | Fix file paths in related_docs                      |
+| YAML syntax errors   | "YAML parse error" messages       | Fix YAML syntax in front matter                     |
+
+### Debugging Steps
+
+1. **Check log files**: Review timestamped logs in `tmp/` directory
+2. **Run quick validation**: Use `make lint-docs-quick` for basic checks
+3. **Validate YAML syntax**: Check front matter for syntax errors
+4. **Compare with templates**: Ensure document follows template structure
+5. **Check index entries**: Verify all files are properly indexed
+6. **Test individual files**: Run validation on specific files
+
+### Log Analysis
+
+**Documentation Lint Logs**:
+
+```bash
+# View validation results
+tail -f tmp/documentation-lint-*.log
+
+# Check for specific errors
+grep -i "error\|failed" tmp/documentation-lint-*.log
+
+# Find warnings
+grep -i "warning" tmp/documentation-lint-*.log
+```
+
+**Index Lint Logs**:
+
+```bash
+# View index validation results
+cat tmp/index-lint-*.log
+
+# Check missing files
+grep "missing from index" tmp/index-lint-*.log
+
+# Check extra files
+grep "extra files in index" tmp/index-lint-*.log
+```
+
+### Performance Optimization
+
+**Faster Validation**:
+
+- Use `make lint-docs-quick` for development
+- Run validation on specific files only
+- Optimize template file parsing
+- Cache validation results
+
+**Resource Usage**:
+
+- Monitor disk space for log files
+- Clean up old log files regularly
+- Use efficient file parsing methods
+- Optimize regex patterns
+
+### Lessons Learned
+
+**2025-01-03**: Implemented comprehensive documentation testing system to ensure consistency and quality. Key insight: Automated validation prevents documentation drift and improves maintainability.
+
+**2025-01-03**: Created template compliance checking with support for custom documents. Lesson: Flexibility is important for meta-documents and special cases.
+
+**2025-01-03**: Established index completeness validation to ensure all documentation is discoverable. Benefit: Prevents orphaned documentation and improves navigation.
+
+**2025-01-03**: Integrated documentation testing with pre-commit hooks for automated quality assurance. Advantage: Catches documentation issues before they reach the repository.
+
+## LLM Context
+
+[Additional context specifically for Large Language Models:]
+
+- **Key Concepts**: Documentation testing involves YAML validation, template compliance, and index completeness to ensure documentation quality and consistency
+- **Technical Context**: Uses shell scripts for automation, YAML parsing for metadata validation, and regex for content analysis. Tests cover 14 documentation files with 8 different templates
+- **Common Patterns**: Layered validation approach (quick → full → index), automated cleanup, timestamped logging, pre-commit integration
+- **Edge Cases**: Custom documents exempt from template compliance, meta-documents with unique structure, footer links excluded from index validation
+- **Integration Points**: Connects with git hooks, CI/CD pipelines, development workflows, and documentation maintenance processes
+
+---
+
+_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._