flowchart TD
    Client["LLM / MCP Client<br/>(Claude, Antigravity, Cursor)"] -->|JSON-RPC| Server["FastMCP Server<br/>(office_mcp.server)"]

    subgraph SafetyEngine ["Safety & Concurrency Engine"]
        Sandbox["Path Sandbox<br/>(OFFICE_MCP_ALLOWED_ROOTS)"]
        LockMgr["DocumentLockManager<br/>(Exclusive in-memory write locks)"]
        SnapMgr["SnapshotManager<br/>(.office_snapshots + SHA-256)"]
        Audit["AuditLogger<br/>(SQLite WAL: office_audit.db)"]
    end

    subgraph ExecutionLayer ["Transactional Execution Pipeline"]
        Executor["ChangeSet Executor"]
        Verifier["Verification Engine<br/>(AST, Formula Errors, Visual PNG)"]
    end

    subgraph DriverLayer ["Dual-Tier Office Drivers"]
        Worker["STA Worker Registry<br/>(Dedicated Thread + pythoncom Pump)"]
        COM["Windows COM Automation<br/>(Excel, Word, PowerPoint .Application)"]
        Fallback["Pure-Python Fallbacks<br/>(openpyxl, python-docx, python-pptx)"]
    end

    Server --> Sandbox
    Sandbox --> LockMgr
    LockMgr --> SnapMgr
    SnapMgr --> Executor
    Executor --> DriverLayer
    DriverLayer --> Worker
    Worker --> COM
    Worker -.->|Non-Windows| Fallback
    Executor --> Verifier
    Verifier -->|Pass| Commit["Commit Document & Release Lock"]
    Verifier -->|Fail| Rollback["Auto-Rollback to .bak Snapshot"]
    Commit --> Audit
    Rollback --> Audit

# Clone repository
git clone https://github.com/your-org/office-mcp.git
cd office-mcp

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate

# Install package in editable mode
pip install -e .

# (Optional) Install development dependencies
pip install -e ".[dev]"

{
  "mcpServers": {
    "office-mcp": {
      "command": "python",
      "args": ["-m", "office_mcp.server"],
      "env": {
        "OFFICE_MCP_ALLOWED_ROOTS": "[\"C:\\\\path\\\\to\\\\documents\", \"C:\\\\path\\\\to\\\\workspace\"]",
        "OFFICE_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

{
  "mcpServers": {
    "office-mcp": {
      "command": "python",
      "args": ["-m", "office_mcp.server"],
      "cwd": "C:/path/to/office-mcp",
      "env": {
        "OFFICE_MCP_ALLOWED_ROOTS": "[\"C:/path/to/office-mcp\"]"
      }
    }
  }
}

{
  "servers": {
    "office-mcp": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/Scripts/python.exe",
      "args": ["-m", "office_mcp.server"]
    }
  }
}

{
  "document_id": "C:/path/to/documents/Financials.xlsx",
  "intent": "Update Q4 Revenue and format summary table",
  "operations": [
    {
      "op_type": "set_range",
      "target": "A1:C3",
      "params": {
        "sheet": "Summary",
        "values": [
          ["Quarter", "Revenue", "Expenses"],
          ["Q3", 150000, 90000],
          ["Q4", 220000, 110000]
        ]
      }
    },
    {
      "op_type": "set_formula",
      "target": "B4",
      "params": {
        "sheet": "Summary",
        "formula": "=SUM(B2:B3)"
      }
    },
    {
      "op_type": "format_range",
      "target": "A1:C1",
      "params": {
        "sheet": "Summary",
        "bold": true,
        "bg_color_rgb": "#1F4E78",
        "color_rgb": "#FFFFFF"
      }
    },
    {
      "op_type": "create_table",
      "target": "SummaryTable",
      "params": {
        "sheet": "Summary",
        "range_address": "A1:C3",
        "style": "TableStyleMedium9"
      }
    }
  ],
  "expected_invariants": [
    "no_formula_errors"
  ],
  "risk_level": "low",
  "dry_run": false
}

{
  "document_id": "C:/path/to/documents/Quarterly_Report.docx",
  "intent": "Add Executive Summary and Financial Metrics Table",
  "operations": [
    {
      "op_type": "add_heading",
      "target": "Executive Summary",
      "params": { "level": 1 }
    },
    {
      "op_type": "add_paragraph",
      "target": "During Q4, overall performance exceeded targets across all key business units.",
      "params": { "font_size_pt": 11 }
    },
    {
      "op_type": "insert_table",
      "target": "",
      "params": {
        "rows": 3,
        "cols": 3,
        "headers": ["Department", "Budget", "Actual"],
        "data": [
          ["Engineering", "$500,000", "$480,000"],
          ["Marketing", "$200,000", "$210,000"]
        ],
        "style": "Table Grid"
      }
    }
  ],
  "expected_invariants": [
    {
      "invariant_type": "min_paragraphs",
      "expected_value": 2
    }
  ],
  "risk_level": "low"
}

{
  "document_id": "C:/path/to/documents/PitchDeck.pptx",
  "intent": "Add Title Slide and KPI Callout Shapes",
  "operations": [
    {
      "op_type": "add_slide",
      "target": "",
      "params": {
        "layout_num": 12,
        "title": "Q4 Performance Overview"
      }
    },
    {
      "op_type": "add_textbox",
      "target": "Strategic Growth & Milestones",
      "params": {
        "slide_index": 1,
        "left": 100,
        "top": 120,
        "width": 800,
        "height": 60,
        "font_size": 32,
        "bold": true,
        "color_rgb": "#111827"
      }
    },
    {
      "op_type": "add_shape",
      "target": "rounded_rectangle",
      "params": {
        "slide_index": 1,
        "left": 100,
        "top": 220,
        "width": 300,
        "height": 160,
        "fill_color": "#2563EB",
        "text": "+45% YoY Growth"
      }
    }
  ],
  "expected_invariants": [
    {
      "invariant_type": "min_slide_count",
      "expected_value": 1
    }
  ],
  "risk_level": "medium"
}

# Run full test suite
pytest

# Run tests with verbose output
pytest -v

# Run only Excel driver tests
pytest tests/test_excel.py

# Run only safety engine tests
pytest tests/test_safety.py

# Format and lint code
ruff check src tests
ruff format src tests

# Static type verification
mypy src