# Infrastructure-from-Code (IaC) Guide\n\n## Overview\n\nThe Infrastructure-from-Code system automatically detects technologies in your project and infers infrastructure requirements based on\norganization-specific rules. It consists of three main commands:\n\n- **detect**: Scan a project and identify technologies\n- **complete**: Analyze gaps and recommend infrastructure components\n- **ifc**: Full-pipeline orchestration (workflow)\n\n## Quick Start\n\n### 1. Detect Technologies in Your Project\n\nScan a project directory for detected technologies:\n\n```\nprovisioning detect /path/to/project --out json\n```\n\n**Output Example:**\n\n```\n{\n  "detections": [\n    {"technology": "nodejs", "confidence": 0.95},\n    {"technology": "postgres", "confidence": 0.92}\n  ],\n  "overall_confidence": 0.93\n}\n```\n\n### 2. Analyze Infrastructure Gaps\n\nGet a completeness assessment and recommendations:\n\n```\nprovisioning complete /path/to/project --out json\n```\n\n**Output Example:**\n\n```\n{\n  "completeness": 1.0,\n  "changes_needed": 2,\n  "is_safe": true,\n  "change_summary": "+ Adding: postgres-backup, pg-monitoring"\n}\n```\n\n### 3. Run Full Workflow\n\nOrchestrate detection → completion → assessment pipeline:\n\n```\nprovisioning ifc /path/to/project --org default\n```\n\n**Output:**\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n🔄 Infrastructure-from-Code Workflow\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nSTEP 1: Technology Detection\n────────────────────────────\n✓ Detected 2 technologies\n\nSTEP 2: Infrastructure Completion\n─────────────────────────────────\n✓ Completeness: 1%\n\n✅ Workflow Complete\n```\n\n## Command Reference\n\n### detect\n\nScan and detect technologies in a project.\n\n**Usage:**\n\n```\nprovisioning detect [PATH] [OPTIONS]\n```\n\n**Arguments:**\n\n- `PATH`: Project directory to analyze (default: current directory)\n\n**Options:**\n\n- `-o, --out TEXT`: Output format - `text`, `json`, `yaml` (default: `text`)\n- `-C, --high-confidence-only`: Only show detections with confidence > 0.8\n- `--pretty`: Pretty-print JSON/YAML output\n- `-x, --debug`: Enable debug output\n\n**Examples:**\n\n```\n# Detect with default text output\nprovisioning detect /path/to/project\n\n# Get JSON output for parsing\nprovisioning detect /path/to/project --out json | jq '.detections'\n\n# Show only high-confidence detections\nprovisioning detect /path/to/project --high-confidence-only\n\n# Pretty-printed YAML output\nprovisioning detect /path/to/project --out yaml --pretty\n```\n\n### complete\n\nAnalyze infrastructure completeness and recommend changes.\n\n**Usage:**\n\n```\nprovisioning complete [PATH] [OPTIONS]\n```\n\n**Arguments:**\n\n- `PATH`: Project directory to analyze (default: current directory)\n\n**Options:**\n\n- `-o, --out TEXT`: Output format - `text`, `json`, `yaml` (default: `text`)\n- `-c, --check`: Check mode (report only, no changes)\n- `--pretty`: Pretty-print JSON/YAML output\n- `-x, --debug`: Enable debug output\n\n**Examples:**\n\n```\n# Analyze completeness\nprovisioning complete /path/to/project\n\n# Get detailed JSON report\nprovisioning complete /path/to/project --out json\n\n# Check mode (dry-run, no changes)\nprovisioning complete /path/to/project --check\n```\n\n### ifc (workflow)\n\nRun the full Infrastructure-from-Code pipeline.\n\n**Usage:**\n\n```\nprovisioning ifc [PATH] [OPTIONS]\n```\n\n**Arguments:**\n\n- `PATH`: Project directory to process (default: current directory)\n\n**Options:**\n\n- `--org TEXT`: Organization name for rule loading (default: `default`)\n- `-o, --out TEXT`: Output format - `text`, `json` (default: `text`)\n- `--apply`: Apply recommendations (future feature)\n- `-v, --verbose`: Verbose output with timing\n- `--pretty`: Pretty-print output\n- `-x, --debug`: Enable debug output\n\n**Examples:**\n\n```\n# Run workflow with default rules\nprovisioning ifc /path/to/project\n\n# Run with organization-specific rules\nprovisioning ifc /path/to/project --org acme-corp\n\n# Verbose output with timing\nprovisioning ifc /path/to/project --verbose\n\n# JSON output for automation\nprovisioning ifc /path/to/project --out json\n```\n\n## Organization-Specific Inference Rules\n\nCustomize how infrastructure is inferred for your organization.\n\n### Understanding Inference Rules\n\nAn inference rule tells the system: "If we detect technology X, we should recommend taskservice Y."\n\n**Rule Structure:**\n\n```\nversion: "1.0.0"\norganization: "your-org"\nrules:\n  - name: "rule-name"\n    technology: ["detected-tech"]\n    infers: "required-taskserv"\n    confidence: 0.85\n    reason: "Why this taskserv is needed"\n    required: true\n```\n\n### Creating Custom Rules\n\nCreate an organization-specific rules file:\n\n```\n# ACME Corporation rules\ncat > $PROVISIONING/config/inference-rules/acme-corp.yaml << 'EOF'\nversion: "1.0.0"\norganization: "acme-corp"\ndescription: "ACME Corporation infrastructure standards"\n\nrules:\n  - name: "nodejs-to-redis"\n    technology: ["nodejs", "express"]\n    infers: "redis"\n    confidence: 0.85\n    reason: "Node.js applications need caching"\n    required: false\n\n  - name: "postgres-to-backup"\n    technology: ["postgres"]\n    infers: "postgres-backup"\n    confidence: 0.95\n    reason: "All databases require backup strategy"\n    required: true\n\n  - name: "all-services-monitoring"\n    technology: ["nodejs", "python", "postgres"]\n    infers: "monitoring"\n    confidence: 0.90\n    reason: "ACME requires monitoring on production services"\n    required: true\nEOF\n```\n\nThen use them:\n\n```\nprovisioning ifc /path/to/project --org acme-corp\n```\n\n### Default Rules\n\nIf no organization rules are found, the system uses sensible defaults:\n\n- Node.js + Express → Redis (caching)\n- Node.js → Nginx (reverse proxy)\n- Database → Backup (data protection)\n- Docker → Kubernetes (orchestration)\n- Python → Gunicorn (WSGI server)\n- PostgreSQL → Monitoring (production safety)\n\n## Output Formats\n\n### Text Output (Default)\n\nHuman-readable format with visual indicators:\n\n```\nSTEP 1: Technology Detection\n────────────────────────────\n✓ Detected 2 technologies\n\nSTEP 2: Infrastructure Completion\n─────────────────────────────────\n✓ Completeness: 1%\n```\n\n### JSON Output\n\nStructured format for automation and parsing:\n\n```\nprovisioning detect /path/to/project --out json | jq '.detections[0]'\n```\n\nOutput:\n\n```\n{\n  "technology": "nodejs",\n  "confidence": 0.8333333134651184,\n  "evidence_count": 1\n}\n```\n\n### YAML Output\n\nAlternative structured format:\n\n```\nprovisioning detect /path/to/project --out yaml\n```\n\n## Practical Examples\n\n### Example 1: Node.js + PostgreSQL Project\n\n```\n# Step 1: Detect\n$ provisioning detect my-app\n✓ Detected: nodejs, express, postgres, docker\n\n# Step 2: Complete\n$ provisioning complete my-app\n✓ Changes needed: 3\n  - redis (caching)\n  - nginx (reverse proxy)\n  - pg-backup (database backup)\n\n# Step 3: Full workflow\n$ provisioning ifc my-app --org acme-corp\n```\n\n### Example 2: Python Django Project\n\n```\n$ provisioning detect django-app --out json\n{\n  "detections": [\n    {"technology": "python", "confidence": 0.95},\n    {"technology": "django", "confidence": 0.92}\n  ]\n}\n\n# Inferred requirements (with gunicorn, monitoring, backup)\n```\n\n### Example 3: Microservices Architecture\n\n```\n$ provisioning ifc microservices/ --org mycompany --verbose\n🔍 Processing microservices/\n  - service-a: nodejs + postgres\n  - service-b: python + redis\n  - service-c: go + mongodb\n\n✓ Detected common patterns\n✓ Applied 12 inference rules\n✓ Generated deployment plan\n```\n\n## Integration with Automation\n\n### CI/CD Pipeline Example\n\n```\n#!/bin/bash\n# Check infrastructure completeness in CI/CD\n\nPROJECT_PATH=${1:-.}\nCOMPLETENESS=$(provisioning complete $PROJECT_PATH --out json | jq '.completeness')\n\nif (( $(echo "$COMPLETENESS < 0.9" | bc -l) )); then\n    echo "❌ Infrastructure completeness too low: $COMPLETENESS"\n    exit 1\nfi\n\necho "✅ Infrastructure is complete: $COMPLETENESS"\n```\n\n### Configuration as Code Integration\n\n```\n# Generate JSON for infrastructure config\nprovisioning detect /path/to/project --out json > infra-report.json\n\n# Use in your config processing\ncat infra-report.json | jq '.detections[]' | while read -r tech; do\n    echo "Processing technology: $tech"\ndone\n```\n\n## Troubleshooting\n\n### "Detector binary not found"\n\n**Solution:** Ensure the provisioning project is properly built:\n\n```\ncd $PROVISIONING/platform\ncargo build --release --bin provisioning-detector\n```\n\n### No technologies detected\n\n**Check:**\n\n1. Project path is correct: `provisioning detect /actual/path`\n2. Project contains recognizable technologies (package.json, Dockerfile, requirements.txt, etc.)\n3. Use `--debug` flag for more details: `provisioning detect /path --debug`\n\n### Organization rules not being applied\n\n**Check:**\n\n1. Rules file exists: `$PROVISIONING/config/inference-rules/{org}.yaml`\n2. Organization name is correct: `provisioning ifc /path --org myorg`\n3. Verify rules structure with: `cat $PROVISIONING/config/inference-rules/myorg.yaml`\n\n## Advanced Usage\n\n### Custom Rule Template\n\nGenerate a template for a new organization:\n\n```\n# Template will be created with proper structure\nprovisioning rules create --org neworg\n```\n\n### Validate Rule Files\n\n```\n# Check for syntax errors\nprovisioning rules validate /path/to/rules.yaml\n```\n\n### Export Rules for Integration\n\nExport as Rust code for embedding:\n\n```\nprovisioning rules export myorg --format rust > rules.rs\n```\n\n## Best Practices\n\n1. **Organize by Organization**: Keep separate rules for different organizations\n2. **High Confidence First**: Start with rules you're confident about (confidence > 0.8)\n3. **Document Reasons**: Always fill in the `reason` field for maintainability\n4. **Test Locally**: Run on sample projects before applying organization-wide\n5. **Version Control**: Commit inference rules to version control\n6. **Review Changes**: Always inspect recommendations with `--check` first\n\n## Related Commands\n\n```\n# View available taskservs that can be inferred\nprovisioning taskserv list\n\n# Create inferred infrastructure\nprovisioning taskserv create {inferred-name}\n\n# View current configuration\nprovisioning env | grep PROVISIONING\n```\n\n## Support and Documentation\n\n- **Full CLI Help**: `provisioning help`\n- **Specific Command Help**: `provisioning help detect`\n- **Configuration Guide**: See `CONFIG_ENCRYPTION_GUIDE.md`\n- **Task Services**: See `SERVICE_MANAGEMENT_GUIDE.md`\n\n---\n\n## Quick Reference\n\n### 3-Step Workflow\n\n```\n# 1. Detect technologies\nprovisioning detect /path/to/project\n\n# 2. Analyze infrastructure gaps\nprovisioning complete /path/to/project\n\n# 3. Run full workflow (detect + complete)\nprovisioning ifc /path/to/project --org myorg\n```\n\n### Common Commands\n\n| Task | Command |\n| ------ | --------- |\n| **Detect technologies** | `provisioning detect /path` |\n| **Get JSON output** | `provisioning detect /path --out json` |\n| **Check completeness** | `provisioning complete /path` |\n| **Dry-run (check mode)** | `provisioning complete /path --check` |\n| **Full workflow** | `provisioning ifc /path --org myorg` |\n| **Verbose output** | `provisioning ifc /path --verbose` |\n| **Debug mode** | `provisioning detect /path --debug` |\n\n### Output Formats\n\n```\n# Text (human-readable)\nprovisioning detect /path --out text\n\n# JSON (for automation)\nprovisioning detect /path --out json | jq '.detections'\n\n# YAML (for configuration)\nprovisioning detect /path --out yaml\n```\n\n### Organization Rules\n\n#### Use Organization Rules\n\n```\nprovisioning ifc /path --org acme-corp\n```\n\n#### Create Rules File\n\n```\nmkdir -p $PROVISIONING/config/inference-rules\ncat > $PROVISIONING/config/inference-rules/myorg.yaml << 'EOF'\nversion: "1.0.0"\norganization: "myorg"\nrules:\n  - name: "nodejs-to-redis"\n    technology: ["nodejs"]\n    infers: "redis"\n    confidence: 0.85\n    reason: "Caching layer"\n    required: false\nEOF\n```\n\n### Example: Node.js + PostgreSQL\n\n```\n$ provisioning detect myapp\n✓ Detected: nodejs, postgres\n\n$ provisioning complete myapp\n✓ Changes: +redis, +nginx, +pg-backup\n\n$ provisioning ifc myapp --org default\n✓ Detection: 2 technologies\n✓ Completion: recommended changes\n✅ Workflow complete\n```\n\n### CI/CD Integration\n\n```\n#!/bin/bash\n# Check infrastructure is complete before deploy\nCOMPLETENESS=$(provisioning complete . --out json | jq '.completeness')\n\nif (( $(echo "$COMPLETENESS < 0.9" | bc -l) )); then\n    echo "Infrastructure incomplete: $COMPLETENESS"\n    exit 1\nfi\n```\n\n### JSON Output Examples\n\n#### Detect Output\n\n```\n{\n  "detections": [\n    {"technology": "nodejs", "confidence": 0.95},\n    {"technology": "postgres", "confidence": 0.92}\n  ],\n  "overall_confidence": 0.93\n}\n```\n\n#### Complete Output\n\n```\n{\n  "completeness": 1.0,\n  "changes_needed": 2,\n  "is_safe": true,\n  "change_summary": "+ redis, + monitoring"\n}\n```\n\n### Flag Reference\n\n| Flag | Short | Purpose |\n| ------ | ------- | --------- |\n| `--out TEXT` | `-o` | Output format: text, json, yaml |\n| `--debug` | `-x` | Enable debug output |\n| `--pretty` | | Pretty-print JSON/YAML |\n| `--check` | `-c` | Dry-run (detect/complete) |\n| `--org TEXT` | | Organization name (ifc) |\n| `--verbose` | `-v` | Verbose output (ifc) |\n| `--apply` | | Apply changes (ifc, future) |\n\n### Troubleshooting\n\n| Issue | Solution |\n| ------- | ---------- |\n| "Detector binary not found" | `cd $PROVISIONING/platform && cargo build --release` |\n| No technologies detected | Check file types (.py, .js, go.mod, package.json, etc.) |\n| Organization rules not found | Verify file exists: `$PROVISIONING/config/inference-rules/{org}.yaml` |\n| Invalid path error | Use absolute path: `provisioning detect /full/path` |\n\n### Environment Variables\n\n| Variable | Purpose |\n| ---------- | --------- |\n| `$PROVISIONING` | Path to provisioning root |\n| `$PROVISIONING_ORG` | Default organization (optional) |\n\n### Default Inference Rules\n\n- Node.js + Express → Redis (caching)\n- Node.js → Nginx (reverse proxy)\n- Database → Backup (data protection)\n- Docker → Kubernetes (orchestration)\n- Python → Gunicorn (WSGI)\n- PostgreSQL → Monitoring (production)\n\n### Useful Aliases\n\n```\n# Add to shell config\nalias detect='provisioning detect'\nalias complete='provisioning complete'\nalias ifc='provisioning ifc'\n\n# Usage\ndetect /my/project\ncomplete /my/project\nifc /my/project --org myorg\n```\n\n### Tips & Tricks\n\n**Parse JSON in bash:**\n\n```\nprovisioning detect . --out json | \\n  jq '.detections[] | .technology' | \\n  sort | uniq\n```\n\n**Watch for changes:**\n\n```\nwatch -n 5 'provisioning complete . --out json | jq ".completeness"'\n```\n\n**Generate reports:**\n\n```\nprovisioning detect . --out yaml > detection-report.yaml\nprovisioning complete . --out yaml > completion-report.yaml\n```\n\n**Validate all organizations:**\n\n```\nfor org in $PROVISIONING/config/inference-rules/*.yaml; do\n    org_name=$(basename "$org" .yaml)\n    echo "Testing $org_name..."\n    provisioning ifc . --org "$org_name" --check\ndone\n```\n\n### Related Guides\n\n- Full guide: `docs/user/INFRASTRUCTURE_FROM_CODE_GUIDE.md`\n- Inference rules: `docs/user/INFRASTRUCTURE_FROM_CODE_GUIDE.md#organization-specific-inference-rules`\n- Service management: `docs/user/SERVICE_MANAGEMENT_QUICKREF.md`\n- Configuration: `docs/user/CONFIG_ENCRYPTION_QUICKREF.md`
