feat: Enable Mix validation in socket-restricted orchestration sandboxes (NIC-413)

elixir/BOOTSTRAP.md

@@ -0,0 +1,267 @@
+# Symphony Bootstrap Guide
+
+This guide provides a **ready-to-run full preflight example** for Symphony setup, addressing environment validation, dependency checks, and sample configurations that work out of the box.
+
+## Quick Start (5-minute setup)
+
+```bash
+# 1. Navigate to Symphony Elixir directory
+cd symphony/elixir
+
+# 2. Run bootstrap validation and setup
+make bootstrap
+
+# 3. Copy example configuration  
+cp WORKFLOW.example.md WORKFLOW.md
+
+# 4. Edit WORKFLOW.md - update project_slug to your Linear project
+# Get your project slug: right-click your Linear project → copy URL → extract slug
+
+# 5. Start Symphony
+./bin/symphony ./WORKFLOW.md
+```
+
+If successful, you'll see:
+- Dashboard at http://localhost:4000
+- Symphony polling your Linear project for issues
+
+## What `make bootstrap` Does
+
+The bootstrap script validates and sets up:
+
+### ✅ **Dependency Checks**
+- Elixir/Erlang (via mise or system installation)
+- Mix build tool  
+- Git version control
+- Codex CLI (optional but recommended)
+
+### ✅ **Environment Validation** 
+- `LINEAR_API_KEY` environment variable
+- API key format validation
+- Workspace directory creation and permissions
+
+### ✅ **Project Setup**
+- Downloads and compiles dependencies
+- Tests Elixir environment compilation
+- Creates `WORKFLOW.example.md` with working defaults
+
+### ✅ **Ready-to-Run Configuration**
+- No external dependencies in sample workflow
+- Local workspace configuration  
+- Conservative defaults for safe operation
+- Clear customization points
+
+## Sample vs Production Configuration
+
+### Sample Configuration (`WORKFLOW.example.md`)
+
+The generated sample configuration is designed to work immediately:
+
+```yaml
+tracker:
+  project_slug: "example-project"  # ← REPLACE THIS
+polling:
+  interval_ms: 10000  # Conservative 10s polling
+agent:
+  max_concurrent_agents: 3  # Start small
+  max_turns: 15  # Limited scope
+hooks:
+  after_create: |
+    # Basic git clone example
+    git clone --depth 1 https://github.com/your-org/your-repo .
+```
+
+### Production Configuration
+
+For production use, customize:
+
+```yaml
+tracker:
+  project_slug: "your-actual-project-slug"
+polling:
+  interval_ms: 5000  # Faster polling
+agent:
+  max_concurrent_agents: 10  # Scale up
+  max_turns: 30  # Longer sessions
+codex:
+  command: codex --model gpt-5.3-codex app-server  # Better model
+hooks:
+  after_create: |
+    # Your actual repository setup
+    git clone https://github.com/your-org/your-repo .
+    mise trust && mise install
+    npm install  # or other build steps
+```
+
+## Dependency Installation
+
+### Option 1: mise (Recommended)
+
+```bash
+# Install mise
+curl https://mise.jdx.dev/install.sh | sh
+
+# Install Elixir/Erlang
+cd symphony/elixir
+mise install
+
+# Verify
+mise exec -- elixir --version
+```
+
+### Option 2: System Installation
+
+**macOS:**
+```bash
+brew install elixir
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update
+sudo apt install elixir
+```
+
+## Linear Setup
+
+1. **Get API Key:**
+   - Go to https://linear.app/settings/security
+   - Create new Personal API Key
+   - Copy the token
+
+2. **Set Environment Variable:**
+   ```bash
+   export LINEAR_API_KEY=your_token_here
+
+   # Make permanent (choose your shell):
+   echo 'export LINEAR_API_KEY=your_token_here' >> ~/.bashrc
+   echo 'export LINEAR_API_KEY=your_token_here' >> ~/.zshrc
+   ```
+
+3. **Find Project Slug:**
+   - Open Linear in browser
+   - Navigate to your project
+   - Right-click → "Copy URL" 
+   - Extract slug from URL: `linear.app/team/PROJECT_SLUG/...`
+
+## Troubleshooting
+
+### `make bootstrap` fails
+
+**Dependencies missing:**
+```bash
+# Install missing tools
+brew install elixir git  # macOS
+apt install elixir git   # Linux
+```
+
+**Linear API key issues:**
+```bash
+# Check if set
+echo $LINEAR_API_KEY
+
+# Test API access
+curl -H "Authorization: $LINEAR_API_KEY" https://api.linear.app/graphql \
+  -d '{"query":"{ viewer { name } }"}'
+```
+
+**Workspace permission errors:**
+```bash
+# Fix permissions
+sudo chown -R $USER ~/code/symphony-workspaces
+```
+
+### Symphony startup fails
+
+**Port already in use:**
+```bash
+# Change port in WORKFLOW.md
+server:
+  port: 4001  # Different port
+```
+
+**Git clone fails in hooks:**
+```bash
+# Test git access
+git clone --depth 1 https://github.com/your-org/your-repo test-clone
+```
+
+**Codex not found:**
+- Install from https://developers.openai.com/codex/
+- Or use different command in WORKFLOW.md
+
+## Validation Tests
+
+The bootstrap includes built-in validation:
+
+```bash
+# Run full validation suite
+make bootstrap
+
+# Individual checks  
+elixir --version
+mix --version
+git --version
+echo $LINEAR_API_KEY
+ls -la ~/code/symphony-workspaces
+```
+
+### Manual Validation
+
+Verify complete setup:
+
+```bash
+# 1. Start Symphony
+./bin/symphony ./WORKFLOW.md
+
+# 2. Check dashboard
+open http://localhost:4000
+
+# 3. Create test issue in Linear
+# 4. Verify Symphony picks it up
+# 5. Check workspace creation
+ls ~/code/symphony-workspaces
+```
+
+## Environment Examples
+
+### Local Development
+- Uses `WORKFLOW.example.md` defaults
+- Local workspace directory
+- Conservative polling and agent limits
+- Basic git clone in hooks
+
+### CI/Production
+- Higher polling frequency
+- More concurrent agents
+- Production repository URLs
+- Additional validation steps
+
+### Docker/Container
+```yaml
+workspace:
+  root: /workspace/symphony-workspaces
+hooks:
+  after_create: |
+    git clone --depth 1 $REPO_URL .
+    npm ci  # or other build commands
+```
+
+## Next Steps After Bootstrap
+
+1. **Test the setup** - Create a simple Linear issue
+2. **Monitor the dashboard** - Watch Symphony pick up and process work
+3. **Customize workflow** - Adjust polling, agents, hooks for your needs  
+4. **Add skills** - Copy relevant skills from Symphony repo to your project
+5. **Scale gradually** - Increase concurrent agents as you gain confidence
+
+## Support
+
+If bootstrap validation passes but Symphony still doesn't work:
+
+1. Check the generated `WORKFLOW.example.md` configuration
+2. Verify your Linear project has issues in the configured states
+3. Test Codex CLI access independently
+4. Check Symphony logs in `./log/` directory
+
+The bootstrap script creates a known-good starting point that works locally. Customize from there based on your specific environment needs.