diff --git a/AI_TOOLSET_SETUP.md b/AI_TOOLSET_SETUP.md
new file mode 100644
index 0000000..fe43d0f
--- /dev/null
+++ b/AI_TOOLSET_SETUP.md
@@ -0,0 +1,338 @@
+# AI Toolset Repository Setup
+
+This document provides instructions for setting up the ai-toolset repository and using it as a submodule.
+
+## Current Status
+
+✅ **Main Repository:** Successfully pushed to `ssh://git@194.163.145.241:2222/copper-tone-tech/mev-beta.git`
+
+⚠️ **AI Toolset Remote:** Configured but needs initialization
+
+## Repository URLs
+
+- **Main Project:** `ssh://git@194.163.145.241:2222/copper-tone-tech/mev-beta.git`
+- **AI Toolset:** `ssh://git@194.163.145.241:2222/administrator/ai-toolset`
+
+## Option 1: Force Push to ai-toolset (New Repository)
+
+If the ai-toolset repository is empty or you want to replace its contents:
+
+```bash
+# Force push current branch as main
+git push ai-toolset v2-master-dev:main --force
+
+# Verify
+git ls-remote ai-toolset
+```
+
+## Option 2: Initialize ai-toolset Repository (Recommended)
+
+If you want to keep ai-toolset separate and sync changes:
+
+```bash
+# Create a dedicated branch for ai-toolset
+git checkout -b ai-toolset-main
+
+# Push to ai-toolset
+git push ai-toolset ai-toolset-main:main
+
+# Return to development branch
+git checkout v2-master-dev
+```
+
+## Option 3: Use as Submodule in Other Projects
+
+Once the ai-toolset repository is set up, other projects can include it:
+
+### In Your Other Project
+
+```bash
+# Navigate to your project
+cd /path/to/your-project
+
+# Add as submodule
+git submodule add ssh://git@194.163.145.241:2222/administrator/ai-toolset tools/ai-toolset
+
+# Initialize
+git submodule update --init --recursive
+
+# Commit
+git add .gitmodules tools/ai-toolset
+git commit -m "Add ai-toolset for audit and testing infrastructure"
+```
+
+### Using the Scripts
+
+After adding as submodule:
+
+```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
+```
+
+## What's Included in ai-toolset
+
+### 🔧 Audit & Testing Scripts
+
+1. **audit.sh** (394 lines)
+   - 12-section comprehensive audit
+   - SPEC.md compliance
+   - Security scanning
+   - Code quality analysis
+   - Colored output with severity levels
+
+2. **test.sh** (267 lines)
+   - 7 test types
+   - Container-based execution
+   - Coverage reports (HTML + percentage)
+   - Verbose mode support
+
+3. **check-compliance.sh** (321 lines)
+   - 8 MUST DO requirements
+   - 7 MUST NOT DO violations
+   - Architecture validation
+   - Foundry integration check
+
+4. **check-docs.sh** (238 lines)
+   - Package documentation
+   - Exported symbols coverage
+   - README validation
+   - Comment density analysis
+
+### 📚 Documentation (1,700+ lines)
+
+- **SPEC.md** - Technical specification
+- **docs/AUDIT_AND_TESTING.md** - Complete testing guide (600+ lines)
+- **docs/SCRIPTS_REFERENCE.md** - All scripts documented (700+ lines)
+- **docs/README.md** - Documentation index
+- **docs/DEVELOPMENT_SETUP.md** - Environment setup
+- **docs/REFACTORING_PLAN.md** - Systematic refactoring plan
+
+### 🛠️ Development Infrastructure
+
+- **scripts/dev.sh** - Unified development script
+- **scripts/dev-up.sh** - Start containers
+- **scripts/dev-down.sh** - Stop containers
+- **scripts/generate-bindings.sh** - Contract binding generation
+- **scripts/extract-official-abis.sh** - ABI extraction
+
+### 📦 Code Quality Improvements
+
+- **pkg/validation/helpers.go** - Address/amount validation
+- **pkg/sequencer/selector_registry.go** - Function selector registry
+- Fixed race conditions (13 atomic metrics)
+- Added error logging (0 silent failures)
+- Address validation at ingress points
+
+## Quick Start (After Repository Setup)
+
+### As a Submodule User
+
+```bash
+# 1. Add to your project
+git submodule add ssh://git@194.163.145.241:2222/administrator/ai-toolset tools/ai-toolset
+
+# 2. Create symlinks (optional but recommended)
+mkdir -p 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
+
+# 3. Use from your project root
+./scripts/audit.sh
+./scripts/test.sh all
+./scripts/check-compliance.sh
+```
+
+### Updating the Submodule
+
+```bash
+# Update to latest version
+cd tools/ai-toolset
+git pull origin main
+cd ../..
+
+# Commit the update
+git add tools/ai-toolset
+git commit -m "Update ai-toolset to latest version"
+```
+
+## CI/CD Integration Examples
+
+### GitHub Actions
+
+```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: Run Tests
+        run: ./tools/ai-toolset/scripts/test.sh all
+
+      - name: Check Compliance
+        run: ./tools/ai-toolset/scripts/check-compliance.sh
+```
+
+### GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+audit:
+  stage: test
+  script:
+    - git submodule update --init --recursive
+    - ./tools/ai-toolset/scripts/audit.sh
+    - ./tools/ai-toolset/scripts/test.sh all
+    - ./tools/ai-toolset/scripts/check-compliance.sh
+```
+
+## Customization for Your Project
+
+### 1. SPEC.md
+
+The included SPEC.md is for the MEV bot. Create your own:
+
+```bash
+# Copy as template
+cp tools/ai-toolset/SPEC.md ./SPEC.md
+
+# Customize for your project
+vim SPEC.md
+```
+
+### 2. Scripts
+
+Scripts are designed to be project-agnostic but can be customized:
+
+```bash
+# Copy and modify
+cp tools/ai-toolset/scripts/audit.sh ./scripts/audit-custom.sh
+
+# Edit for your needs
+vim scripts/audit-custom.sh
+```
+
+### 3. Documentation Structure
+
+Use the documentation as a template:
+
+```bash
+# Copy structure
+cp -r tools/ai-toolset/docs/* ./docs/
+
+# Adapt to your project
+```
+
+## Troubleshooting
+
+### Submodule Not Initialized
+
+```bash
+git submodule update --init --recursive
+```
+
+### Permission Denied
+
+```bash
+chmod +x tools/ai-toolset/scripts/*.sh
+```
+
+### Cannot Push to ai-toolset
+
+If the repository already exists with content:
+
+```bash
+# Fetch existing content
+git fetch ai-toolset
+
+# Merge or rebase
+git pull ai-toolset main --allow-unrelated-histories
+
+# Then push
+git push ai-toolset v2-master-dev:main
+```
+
+### Fresh Start
+
+If you want to completely replace ai-toolset content:
+
+```bash
+git push ai-toolset v2-master-dev:main --force
+```
+
+## Verification
+
+After setup, verify everything works:
+
+```bash
+# Clone test
+git clone --recursive ssh://git@194.163.145.241:2222/administrator/ai-toolset test-ai-toolset
+cd test-ai-toolset
+
+# Test scripts
+./scripts/audit.sh
+./scripts/test.sh --help
+./scripts/check-compliance.sh --help
+
+# Verify documentation
+ls -la docs/
+```
+
+## Summary of Changes
+
+This setup provides:
+
+- ✅ **34 files** added/modified in latest commit
+- ✅ **7,514 lines** of code and documentation
+- ✅ **4 comprehensive audit scripts**
+- ✅ **5 documentation files** (1,700+ lines)
+- ✅ **9 development scripts**
+- ✅ **Phase 1 refactoring** complete (race conditions fixed, validation added)
+- ✅ **Build status:** All packages compile
+- ✅ **SPEC.md violations:** Reduced from 7 to 5
+
+## Next Steps
+
+1. **Push to ai-toolset** using one of the options above
+2. **Test as submodule** in another project
+3. **Configure CI/CD** with the provided examples
+4. **Customize** SPEC.md for your project
+5. **Run audits** regularly as part of your development workflow
+
+## Support
+
+For detailed usage information:
+
+- Read `SUBMODULE_USAGE.md` for comprehensive guide
+- Check `docs/SCRIPTS_REFERENCE.md` for all script documentation
+- Review `docs/AUDIT_AND_TESTING.md` for testing guidelines
+- See commit history for examples and patterns
+
+---
+
+**Repository:** `ssh://git@194.163.145.241:2222/administrator/ai-toolset`
+**Status:** Ready for initial push
+**Last Updated:** 2025-11-11
+**Commits:** 2 (audit infrastructure + submodule documentation)