diff --git a/SUBMODULE_USAGE.md b/SUBMODULE_USAGE.md
new file mode 100644
index 0000000..5bc7c2d
--- /dev/null
+++ b/SUBMODULE_USAGE.md
@@ -0,0 +1,398 @@
+# Using This Repository as a Git Submodule
+
+This repository can be included in other projects as a Git submodule to provide comprehensive audit and testing infrastructure.
+
+## Repository Information
+
+**Submodule URL:** `ssh://git@194.163.145.241:2222/administrator/ai-toolset`
+
+## What This Provides
+
+### 🔧 Audit & Testing Scripts (4 comprehensive scripts)
+
+1. **scripts/audit.sh** - 12-section codebase audit
+   - SPEC.md compliance
+   - Go code quality
+   - Security scanning
+   - Concurrency safety
+   - Error handling
+   - Documentation coverage
+   - Test coverage
+   - Dependencies
+   - Contract bindings
+   - Build verification
+   - File organization
+   - Git status
+
+2. **scripts/test.sh** - 7 test types
+   - Unit tests
+   - Integration tests
+   - Race detection
+   - Benchmarks
+   - Coverage reports
+   - Contract tests
+   - Package-specific tests
+
+3. **scripts/check-compliance.sh** - SPEC.md validation
+   - 8 MUST DO requirements
+   - 7 MUST NOT DO violations
+   - Architecture requirements
+   - Foundry integration
+   - Development scripts
+
+4. **scripts/check-docs.sh** - Documentation coverage
+   - Package documentation
+   - Exported function comments
+   - Exported type comments
+   - README files
+   - Inline comment density
+   - API documentation
+   - Example code
+
+### 📚 Comprehensive Documentation (1,700+ lines)
+
+- **SPEC.md** - Technical specification and requirements
+- **docs/AUDIT_AND_TESTING.md** - Complete testing guide (600+ lines)
+- **docs/SCRIPTS_REFERENCE.md** - All scripts documented (700+ lines)
+- **docs/README.md** - Documentation index and navigation
+- **docs/DEVELOPMENT_SETUP.md** - Environment setup guide
+- **docs/REFACTORING_PLAN.md** - Systematic refactoring plan
+
+### 🛠️ Development Infrastructure
+
+- **scripts/dev.sh** - Unified development script
+- Container-based development (Podman/Docker)
+- Foundry integration for contracts
+- Go binding generation
+- Complete development workflow
+
+## Adding as a Submodule
+
+### Option 1: Add to Parent Repository
+
+From your parent repository:
+
+```bash
+# Add as submodule
+git submodule add ssh://git@194.163.145.241:2222/administrator/ai-toolset tools/ai-toolset
+
+# Initialize and update
+git submodule update --init --recursive
+
+# Commit the submodule
+git add .gitmodules tools/ai-toolset
+git commit -m "Add ai-toolset submodule for audit/testing infrastructure"
+```
+
+### Option 2: Clone Repository with Submodules
+
+If cloning a repository that already includes this submodule:
+
+```bash
+# Clone with submodules
+git clone --recursive <parent-repo-url>
+
+# Or if already cloned
+git submodule update --init --recursive
+```
+
+## Using the Scripts
+
+Once added as a submodule, you can use the scripts from your parent repository:
+
+### Direct Usage
+
+```bash
+# Run audit
+./tools/ai-toolset/scripts/audit.sh
+
+# Run tests
+./tools/ai-toolset/scripts/test.sh all
+
+# Check compliance
+./tools/ai-toolset/scripts/check-compliance.sh
+
+# Check documentation
+./tools/ai-toolset/scripts/check-docs.sh
+```
+
+### Symlink Setup (Recommended)
+
+Create symlinks in your parent repository for easier access:
+
+```bash
+# Create scripts directory in parent repo
+mkdir -p scripts
+
+# Symlink audit scripts
+ln -s ../tools/ai-toolset/scripts/audit.sh scripts/audit.sh
+ln -s ../tools/ai-toolset/scripts/test.sh scripts/test.sh
+ln -s ../tools/ai-toolset/scripts/check-compliance.sh scripts/check-compliance.sh
+ln -s ../tools/ai-toolset/scripts/check-docs.sh scripts/check-docs.sh
+
+# Now use from parent repo
+./scripts/audit.sh
+./scripts/test.sh all
+```
+
+### Copy and Customize
+
+If you need to customize the scripts for your project:
+
+```bash
+# Copy scripts to your repository
+cp -r tools/ai-toolset/scripts/* ./scripts/
+
+# Customize as needed
+vim scripts/audit.sh
+
+# Commit your customized versions
+git add scripts/
+git commit -m "Add customized audit scripts"
+```
+
+## Updating the Submodule
+
+### Update to Latest Version
+
+```bash
+# Navigate to submodule
+cd tools/ai-toolset
+
+# Pull latest changes
+git pull origin v2-master-dev
+
+# Go back to parent repo
+cd ../..
+
+# Commit the submodule update
+git add tools/ai-toolset
+git commit -m "Update ai-toolset to latest version"
+```
+
+### Update All Submodules
+
+```bash
+# Update all submodules to latest
+git submodule update --remote --merge
+
+# Commit updates
+git add .
+git commit -m "Update all submodules"
+```
+
+## Adapting to Your Project
+
+### 1. SPEC.md Customization
+
+The included `SPEC.md` is specific to the MEV bot project. For your project:
+
+```bash
+# Copy as template
+cp tools/ai-toolset/SPEC.md ./SPEC.md
+
+# Customize for your project
+vim SPEC.md
+
+# The check-compliance.sh script will use your SPEC.md
+```
+
+### 2. Script Configuration
+
+Most scripts are project-agnostic, but you can configure them:
+
+```bash
+# Set environment variables
+export GO_CONTAINER=your-go-container
+export COVERAGE_THRESHOLD=80
+
+# Run with custom settings
+./tools/ai-toolset/scripts/test.sh coverage
+```
+
+### 3. Documentation Structure
+
+Use the documentation structure as a template:
+
+```bash
+# Copy documentation structure
+cp -r tools/ai-toolset/docs/* ./docs/
+
+# Customize for your project
+vim docs/README.md
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+# .github/workflows/audit.yml
+name: Code Audit
+
+on: [push, pull_request]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: recursive
+
+      - name: Run Audit
+        run: ./tools/ai-toolset/scripts/audit.sh
+
+      - name: Check Compliance
+        run: ./tools/ai-toolset/scripts/check-compliance.sh
+
+      - name: Run Tests
+        run: ./tools/ai-toolset/scripts/test.sh all
+```
+
+### GitLab CI Example
+
+```yaml
+# .gitlab-ci.yml
+audit:
+  stage: test
+  script:
+    - git submodule update --init --recursive
+    - ./tools/ai-toolset/scripts/audit.sh
+    - ./tools/ai-toolset/scripts/check-compliance.sh
+    - ./tools/ai-toolset/scripts/test.sh all
+```
+
+## Available Documentation
+
+All documentation is available in the `docs/` directory:
+
+- **Start Here:** `docs/README.md` - Documentation index
+- **Setup:** `docs/DEVELOPMENT_SETUP.md` - Environment setup
+- **Testing:** `docs/AUDIT_AND_TESTING.md` - Complete testing guide
+- **Scripts:** `docs/SCRIPTS_REFERENCE.md` - All scripts documented
+- **Planning:** `docs/REFACTORING_PLAN.md` - Refactoring guide
+
+## Script Capabilities Summary
+
+### audit.sh
+
+✓ 12 comprehensive checks
+✓ Colored output with severity levels
+✓ SPEC.md compliance validation
+✓ Security scanning
+✓ Code quality analysis
+
+### test.sh
+
+✓ 7 test types
+✓ Container-based execution
+✓ Coverage reports (HTML + percentage)
+✓ Verbose mode support
+✓ Package-specific testing
+
+### check-compliance.sh
+
+✓ MUST DO requirements (8 checks)
+✓ MUST NOT DO violations (7 checks)
+✓ Architecture validation
+✓ Foundry integration check
+✓ Development script verification
+
+### check-docs.sh
+
+✓ Package documentation
+✓ Exported symbols coverage
+✓ README file validation
+✓ Comment density analysis
+✓ >80% coverage target
+
+## Exit Codes
+
+All scripts use consistent exit codes:
+
+- **0** - Success (all checks passed)
+- **1** - Failure (violations found, tests failed)
+- **127** - Command not found
+- **255** - Container error
+
+## Best Practices
+
+1. **Keep Submodule Updated**
+   - Regularly pull latest changes
+   - Review release notes before updating
+
+2. **Run Before Commits**
+   ```bash
+   # Pre-commit hook
+   ./tools/ai-toolset/scripts/test.sh unit
+   ./tools/ai-toolset/scripts/check-compliance.sh
+   ```
+
+3. **Run Before Push**
+   ```bash
+   # Pre-push validation
+   ./tools/ai-toolset/scripts/test.sh all
+   ./tools/ai-toolset/scripts/audit.sh
+   ./tools/ai-toolset/scripts/check-docs.sh
+   ```
+
+4. **CI/CD Integration**
+   - Run audit on every push
+   - Block merges on failures
+   - Generate coverage reports
+
+## Troubleshooting
+
+### Submodule Not Initialized
+
+```bash
+git submodule update --init --recursive
+```
+
+### Permission Denied on Scripts
+
+```bash
+chmod +x tools/ai-toolset/scripts/*.sh
+```
+
+### Container Not Found
+
+```bash
+# Update container name in environment
+export GO_CONTAINER=your-container-name
+./tools/ai-toolset/scripts/test.sh unit
+```
+
+### Custom Script Directory
+
+```bash
+# Scripts look for Go code in ./pkg/ by default
+# For different structure, customize scripts or use symlinks
+```
+
+## Support
+
+For issues or questions:
+
+1. Check documentation in `docs/`
+2. Review `docs/SCRIPTS_REFERENCE.md`
+3. Check `docs/AUDIT_AND_TESTING.md` for testing guidance
+4. Review commit history for examples
+
+## Version Information
+
+This infrastructure includes:
+
+- **Scripts:** 4 audit/test scripts + 5 development scripts
+- **Documentation:** 1,700+ lines across 5 comprehensive guides
+- **Code Quality:** Fixed race conditions, added validation, eliminated silent failures
+- **Build Status:** ✅ All packages compile
+- **Test Coverage:** >70% target with detailed reports
+
+---
+
+**Repository:** `ssh://git@194.163.145.241:2222/administrator/ai-toolset`
+**Branch:** `v2-master-dev`
+**Last Updated:** 2025-11-11
+**Status:** Production Ready ✅