Initial commit: add .gitignore and README

ARCHITECTURE.md

@@ -0,0 +1,113 @@
+# Architecture Documentation
+
+## System Overview
+
+Strategic is a TypeScript CLI + Solidity atomic executor for DeFi strategies. It enables users to define complex multi-step DeFi operations in JSON and execute them atomically on-chain.
+
+## Execution Flow
+
+```
+Strategy JSON
+    ↓
+Strategy Loader (validate, substitute blinds)
+    ↓
+Planner/Compiler (compile steps → calls)
+    ↓
+Guard Evaluation (pre-execution checks)
+    ↓
+Execution Engine
+    ├─ Simulation Mode (fork testing)
+    ├─ Dry Run (validation only)
+    ├─ Explain Mode (show plan)
+    └─ Live Execution
+        ├─ Direct (via executor contract)
+        └─ Flashbots (MEV protection)
+```
+
+## Flash Loan Flow
+
+```
+1. Strategy defines aaveV3.flashLoan step
+2. Compiler detects flash loan requirement
+3. Steps after flash loan are compiled as callback operations
+4. Executor.executeFlashLoan() is called
+5. Aave Pool calls executeOperation() callback
+6. Callback operations execute atomically
+7. Flash loan is repaid automatically
+```
+
+## Guard Evaluation Order
+
+1. **Global Guards** (strategy-level)
+   - Evaluated before compilation
+   - If any guard with `onFailure: "revert"` fails, execution stops
+
+2. **Step Guards** (per-step)
+   - Evaluated before each step execution
+   - Can be `revert`, `warn`, or `skip`
+
+3. **Post-Execution Guards**
+   - Evaluated after execution completes
+   - Used for validation (e.g., health factor check)
+
+## Component Architecture
+
+### Core Components
+
+- **CLI** (`src/cli.ts`): User interface, command parsing
+- **Strategy Loader** (`src/strategy.ts`): JSON parsing, validation, blind substitution
+- **Planner/Compiler** (`src/planner/compiler.ts`): Step → call compilation
+- **Guard Engine** (`src/planner/guards.ts`): Safety check evaluation
+- **Execution Engine** (`src/engine.ts`): Orchestrates execution
+- **AtomicExecutor.sol**: On-chain executor contract
+
+### Adapters
+
+Protocol-specific adapters abstract contract interactions:
+- Each adapter provides typed methods
+- Handles ABI encoding/decoding
+- Manages protocol-specific logic
+
+### Guards
+
+Safety checks that can block execution:
+- `oracleSanity`: Price validation
+- `twapSanity`: TWAP price checks
+- `maxGas`: Gas limits
+- `minHealthFactor`: Aave health factor
+- `slippage`: Slippage protection
+- `positionDeltaLimit`: Position size limits
+
+## Data Flow
+
+1. **Strategy Definition**: JSON file with steps, guards, blinds
+2. **Blind Substitution**: Runtime values replace `{{blind}}` placeholders
+3. **Compilation**: Steps → contract calls (calldata)
+4. **Guard Evaluation**: Safety checks before execution
+5. **Execution**: Calls sent to executor contract
+6. **Telemetry**: Results logged (opt-in)
+
+## Security Model
+
+- **Allow-List**: Executor only calls allow-listed contracts
+- **Pausability**: Owner can pause executor
+- **Flash Loan Security**: Only authorized pools can call callback
+- **Guard Enforcement**: Guards can block unsafe operations
+- **Reentrancy Protection**: Executor uses ReentrancyGuard
+
+## Cross-Chain Architecture
+
+For cross-chain strategies:
+1. Source chain executes initial steps
+2. Bridge message sent (CCIP/LayerZero/Wormhole)
+3. Target chain receives message
+4. Compensating leg executes if main leg fails
+5. State guards monitor message delivery
+
+## Testing Strategy
+
+- **Unit Tests**: Individual components (adapters, guards, compiler)
+- **Integration Tests**: End-to-end strategy execution
+- **Foundry Tests**: Solidity contract testing
+- **Fork Simulation**: Test on mainnet fork before live execution
+