diff --git a/ISSUES.md b/ISSUES.md
new file mode 100644
index 0000000..e309fe3
--- /dev/null
+++ b/ISSUES.md
@@ -0,0 +1,1530 @@
+# Skyscale Restructuring Issues
+
+This document tracks individual issues for the Skyscale restructuring project. Each issue corresponds to a specific task in the milestones.
+
+---
+
+## Milestone 1: Foundation and Documentation
+
+### Issue #1: Create restructuring documentation
+**Priority:** High  
+**Status:** Completed  
+**Assignee:** TBD
+
+**Description:**
+Create comprehensive documentation outlining the restructuring plan, including architecture diagrams, rationale, and migration strategy.
+
+**Tasks:**
+- [x] Create RESTRUCTURING.md
+- [x] Document proposed architecture
+- [x] Document migration strategy
+- [x] Explain design principles
+
+**Acceptance Criteria:**
+- Documentation is clear and comprehensive
+- Team understands the plan
+- All stakeholders have reviewed
+
+---
+
+### Issue #2: Create milestone tracking
+**Priority:** High  
+**Status:** Completed  
+**Assignee:** TBD
+
+**Description:**
+Set up milestone and issue tracking infrastructure to manage the restructuring project.
+
+**Tasks:**
+- [x] Create MILESTONES.md
+- [x] Create ISSUES.md
+- [x] Define milestones
+- [x] Create issue templates
+
+**Acceptance Criteria:**
+- Milestones clearly defined
+- Issues template available
+- Progress trackable
+
+---
+
+### Issue #3: Create directory structure placeholders
+**Priority:** High  
+**Status:** In Progress  
+**Assignee:** TBD
+
+**Description:**
+Create the new directory structure with placeholder README files to establish the target architecture.
+
+**Tasks:**
+- [ ] Create vm/ directory structure
+- [ ] Create runtime/ directory structure
+- [ ] Create sandbox/ directory structure
+- [ ] Create sdk/ directory structure
+- [ ] Create internal/ directory structure
+- [ ] Add README files to each directory
+- [ ] Document module responsibilities
+
+**Acceptance Criteria:**
+- All directories created
+- README files explain purpose
+- No code moved yet (just structure)
+
+---
+
+### Issue #4: Document current architecture
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Document the current architecture as a baseline for comparison and to help with migration.
+
+**Tasks:**
+- [ ] Create architecture diagram for current state
+- [ ] Document current module boundaries
+- [ ] Document current dependencies
+- [ ] Identify areas of concern
+
+**Acceptance Criteria:**
+- Current architecture documented
+- Diagram created
+- Dependencies mapped
+
+---
+
+## Milestone 2: VM Module Extraction
+
+### Issue #5: Create vm/manager module
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Move control-plane/vm/ to vm/manager/ as the first step in extracting VM logic.
+
+**Tasks:**
+- [ ] Create vm/manager/ directory
+- [ ] Move vm.go to vm/manager/manager.go
+- [ ] Move config.go to vm/manager/config.go
+- [ ] Update package declarations
+- [ ] Update imports in moved files
+- [ ] Create vm/manager/README.md
+
+**Acceptance Criteria:**
+- Files moved successfully
+- Package structure correct
+- No compilation errors
+- Tests pass
+
+---
+
+### Issue #6: Create vm/pool module
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Extract VM pool management logic into a dedicated module.
+
+**Tasks:**
+- [ ] Create vm/pool/ directory
+- [ ] Extract warm pool logic from manager
+- [ ] Create pool.go with VMPool type
+- [ ] Implement pool management methods
+- [ ] Add pool configuration
+- [ ] Create vm/pool/README.md
+- [ ] Add unit tests
+
+**Acceptance Criteria:**
+- Pool logic separated
+- Clean API for pool operations
+- Tests pass
+- Documentation complete
+
+---
+
+### Issue #7: Create vm/snapshot module
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create snapshot management module for VM snapshot operations.
+
+**Tasks:**
+- [ ] Create vm/snapshot/ directory
+- [ ] Design snapshot API
+- [ ] Implement snapshot creation
+- [ ] Implement snapshot restoration
+- [ ] Add snapshot metadata management
+- [ ] Create vm/snapshot/README.md
+- [ ] Add unit tests
+
+**Acceptance Criteria:**
+- Snapshot operations working
+- Snapshots can be created and restored
+- Metadata tracked
+- Tests pass
+
+---
+
+### Issue #8: Create vm/network module
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Extract network configuration logic into dedicated module.
+
+**Tasks:**
+- [ ] Create vm/network/ directory
+- [ ] Extract network setup from manager
+- [ ] Implement TAP device management
+- [ ] Implement bridge configuration
+- [ ] Add IP allocation logic
+- [ ] Create vm/network/README.md
+- [ ] Add unit tests
+
+**Acceptance Criteria:**
+- Network logic separated
+- Network operations working
+- Tests pass
+- Documentation complete
+
+---
+
+### Issue #9: Create vm/jailer module
+**Priority:** Low  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create security isolation module for jailer configuration.
+
+**Tasks:**
+- [ ] Create vm/jailer/ directory
+- [ ] Design jailer API
+- [ ] Implement seccomp configuration
+- [ ] Implement UID isolation
+- [ ] Add chroot support
+- [ ] Create vm/jailer/README.md
+- [ ] Add unit tests
+
+**Acceptance Criteria:**
+- Jailer functionality working
+- Security isolation effective
+- Tests pass
+- Documentation complete
+
+---
+
+### Issue #10: Update all imports
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Update all imports across the codebase to use the new vm/ module structure.
+
+**Tasks:**
+- [ ] Update control-plane imports
+- [ ] Update cmd imports
+- [ ] Update test imports
+- [ ] Verify no broken imports
+- [ ] Run go mod tidy
+
+**Acceptance Criteria:**
+- All imports updated
+- No compilation errors
+- Tests pass
+- go mod clean
+
+---
+
+### Issue #11: Add vm/ module tests
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Ensure comprehensive test coverage for the vm/ module.
+
+**Tasks:**
+- [ ] Add manager tests
+- [ ] Add pool tests
+- [ ] Add snapshot tests
+- [ ] Add network tests
+- [ ] Add jailer tests
+- [ ] Add integration tests
+- [ ] Achieve >80% coverage
+
+**Acceptance Criteria:**
+- All modules tested
+- Coverage >80%
+- Integration tests pass
+- CI/CD green
+
+---
+
+### Issue #12: Update documentation
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Update all documentation to reflect the new vm/ module structure.
+
+**Tasks:**
+- [ ] Update README.md
+- [ ] Update architecture docs
+- [ ] Add vm/ module docs
+- [ ] Update developer guide
+- [ ] Add migration notes
+
+**Acceptance Criteria:**
+- Documentation accurate
+- Examples updated
+- Migration guide clear
+
+---
+
+## Milestone 3: Runtime Formalization
+
+### Issue #13: Create runtime/agent module
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Formalize the Go agent as a dedicated module.
+
+**Tasks:**
+- [ ] Create runtime/agent/ directory
+- [ ] Move agent code to runtime/agent/
+- [ ] Clean up agent interface
+- [ ] Add agent configuration
+- [ ] Create runtime/agent/README.md
+- [ ] Add unit tests
+
+**Acceptance Criteria:**
+- Agent is standalone module
+- Clean interface defined
+- Tests pass
+- Documentation complete
+
+---
+
+### Issue #14: Create runtime/python module
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Extract Python runtime bootstrap logic into dedicated module.
+
+**Tasks:**
+- [ ] Create runtime/python/ directory
+- [ ] Move Python bootstrap code
+- [ ] Implement handler loading
+- [ ] Add dependency management
+- [ ] Create runtime/python/README.md
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- Python runtime separated
+- Handler loading works
+- Tests pass
+- Documentation complete
+
+---
+
+### Issue #15: Create runtime/protocol module
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Define and implement the host-guest communication protocol.
+
+**Tasks:**
+- [ ] Create runtime/protocol/ directory
+- [ ] Define protocol messages
+- [ ] Implement protocol encoding/decoding
+- [ ] Add version negotiation
+- [ ] Create runtime/protocol/README.md
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- Protocol clearly defined
+- Implementation works
+- Version negotiation functional
+- Tests pass
+
+---
+
+### Issue #16: Document protocol specification
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Write comprehensive documentation for the host-guest protocol.
+
+**Tasks:**
+- [ ] Document protocol messages
+- [ ] Document message formats
+- [ ] Document error handling
+- [ ] Add protocol examples
+- [ ] Create sequence diagrams
+
+**Acceptance Criteria:**
+- Protocol fully documented
+- Examples clear
+- Diagrams helpful
+
+---
+
+### Issue #17: Implement protocol versioning
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Add version negotiation support to the protocol for future compatibility.
+
+**Tasks:**
+- [ ] Design versioning scheme
+- [ ] Implement version handshake
+- [ ] Add backward compatibility
+- [ ] Test version negotiation
+- [ ] Document versioning
+
+**Acceptance Criteria:**
+- Versioning works
+- Backward compatible
+- Tests pass
+- Documentation complete
+
+---
+
+### Issue #18: Add runtime tests
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Add comprehensive tests for host-guest communication.
+
+**Tasks:**
+- [ ] Add protocol tests
+- [ ] Add agent tests
+- [ ] Add Python runtime tests
+- [ ] Add integration tests
+- [ ] Achieve >80% coverage
+
+**Acceptance Criteria:**
+- All components tested
+- Coverage >80%
+- Integration tests pass
+
+---
+
+### Issue #19: Update agent deployment
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Update how the agent is deployed to VMs to use the new module structure.
+
+**Tasks:**
+- [ ] Update agent build process
+- [ ] Update agent deployment scripts
+- [ ] Test agent in VM
+- [ ] Update documentation
+
+**Acceptance Criteria:**
+- Agent deploys successfully
+- Agent runs in VM
+- Tests pass
+
+---
+
+## Milestone 4: Control Plane Reorganization
+
+### Issue #20: Create cmd/control-plane
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Move control plane entry point to cmd/control-plane/main.go.
+
+**Tasks:**
+- [ ] Create cmd/control-plane/ directory
+- [ ] Move control-plane/main.go to cmd/control-plane/main.go
+- [ ] Update imports
+- [ ] Update build scripts
+- [ ] Test binary
+
+**Acceptance Criteria:**
+- Entry point moved
+- Binary builds
+- Tests pass
+- Build scripts updated
+
+---
+
+### Issue #21: Remove VM logic from control-plane
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Ensure control plane uses vm/ module exclusively and has no direct VM logic.
+
+**Tasks:**
+- [ ] Identify VM dependencies in control-plane
+- [ ] Replace with vm/ module calls
+- [ ] Remove direct Firecracker dependencies
+- [ ] Update tests
+- [ ] Verify separation
+
+**Acceptance Criteria:**
+- No VM logic in control-plane
+- Uses vm/ module only
+- Tests pass
+- Clean dependencies
+
+---
+
+### Issue #22: Refactor control-plane/api
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Clean up API handlers to use new module structure.
+
+**Tasks:**
+- [ ] Update API handlers
+- [ ] Use vm/ module
+- [ ] Use runtime/ module
+- [ ] Improve error handling
+- [ ] Add API tests
+
+**Acceptance Criteria:**
+- API handlers cleaned up
+- New modules used
+- Tests pass
+
+---
+
+### Issue #23: Update control-plane/scheduler
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Update scheduler to use vm/ module exclusively.
+
+**Tasks:**
+- [ ] Update scheduler logic
+- [ ] Use vm/ module
+- [ ] Remove direct VM access
+- [ ] Add scheduler tests
+- [ ] Document scheduler
+
+**Acceptance Criteria:**
+- Scheduler uses vm/ module
+- Tests pass
+- Documentation updated
+
+---
+
+### Issue #24: Clean up control-plane imports
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Remove all direct Firecracker dependencies from control plane.
+
+**Tasks:**
+- [ ] Audit imports
+- [ ] Remove Firecracker imports
+- [ ] Use vm/ module instead
+- [ ] Run go mod tidy
+- [ ] Verify clean dependencies
+
+**Acceptance Criteria:**
+- No Firecracker imports in control-plane
+- Dependencies clean
+- Tests pass
+
+---
+
+### Issue #25: Add control-plane tests
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Add comprehensive tests for control plane orchestration logic.
+
+**Tasks:**
+- [ ] Add API tests
+- [ ] Add scheduler tests
+- [ ] Add integration tests
+- [ ] Achieve >80% coverage
+
+**Acceptance Criteria:**
+- All components tested
+- Coverage >80%
+- Tests pass
+
+---
+
+### Issue #26: Update build scripts
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Update Makefile and build scripts for new structure.
+
+**Tasks:**
+- [ ] Update Makefile
+- [ ] Update build paths
+- [ ] Test builds
+- [ ] Update CI/CD
+- [ ] Document build process
+
+**Acceptance Criteria:**
+- Builds work
+- CI/CD passes
+- Documentation updated
+
+---
+
+## Milestone 5: Sandbox API Implementation
+
+### Issue #27: Design sandbox API
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Design REST API for sandbox operations.
+
+**Tasks:**
+- [ ] Define API endpoints
+- [ ] Design request/response formats
+- [ ] Define error handling
+- [ ] Create API specification
+- [ ] Review with team
+
+**Acceptance Criteria:**
+- API designed
+- Specification complete
+- Team approved
+
+---
+
+### Issue #28: Create sandbox/api module
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Implement API handlers for sandbox operations.
+
+**Tasks:**
+- [ ] Create sandbox/api/ directory
+- [ ] Implement API handlers
+- [ ] Add request validation
+- [ ] Add error handling
+- [ ] Create sandbox/api/README.md
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- API handlers implemented
+- Validation works
+- Tests pass
+
+---
+
+### Issue #29: Create sandbox/lifecycle module
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Implement sandbox lifecycle management (create/suspend/resume/destroy).
+
+**Tasks:**
+- [ ] Create sandbox/lifecycle/ directory
+- [ ] Implement create operation
+- [ ] Implement suspend operation
+- [ ] Implement resume operation
+- [ ] Implement destroy operation
+- [ ] Add state tracking
+- [ ] Create sandbox/lifecycle/README.md
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- All lifecycle operations work
+- State tracked correctly
+- Tests pass
+
+---
+
+### Issue #30: Create sandbox/exec module
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Implement code execution in sandboxes.
+
+**Tasks:**
+- [ ] Create sandbox/exec/ directory
+- [ ] Implement shell execution
+- [ ] Implement Python execution
+- [ ] Add output streaming
+- [ ] Add timeout handling
+- [ ] Create sandbox/exec/README.md
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- Execution works
+- Output streams
+- Timeouts work
+- Tests pass
+
+---
+
+### Issue #31: Create sandbox/fs module
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Implement filesystem operations for sandboxes.
+
+**Tasks:**
+- [ ] Create sandbox/fs/ directory
+- [ ] Implement file upload
+- [ ] Implement file download
+- [ ] Implement directory operations
+- [ ] Add quota management
+- [ ] Create sandbox/fs/README.md
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- File operations work
+- Quotas enforced
+- Tests pass
+
+---
+
+### Issue #32: Add feature flag
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Implement feature flag for sandbox mode.
+
+**Tasks:**
+- [ ] Add feature flag configuration
+- [ ] Implement flag checking
+- [ ] Gate sandbox API behind flag
+- [ ] Add flag documentation
+- [ ] Test with flag on/off
+
+**Acceptance Criteria:**
+- Feature flag works
+- Sandbox disabled by default
+- Can be enabled via config
+
+---
+
+### Issue #33: Implement sandbox state management
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Track sandbox lifecycle state in state manager.
+
+**Tasks:**
+- [ ] Add sandbox state types
+- [ ] Implement state persistence
+- [ ] Add state transitions
+- [ ] Add state queries
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- State persisted correctly
+- Transitions valid
+- Tests pass
+
+---
+
+### Issue #34: Add sandbox tests
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Add comprehensive tests for sandbox operations.
+
+**Tasks:**
+- [ ] Add API tests
+- [ ] Add lifecycle tests
+- [ ] Add execution tests
+- [ ] Add filesystem tests
+- [ ] Add integration tests
+- [ ] Achieve >80% coverage
+
+**Acceptance Criteria:**
+- All components tested
+- Coverage >80%
+- Tests pass
+
+---
+
+### Issue #35: Document sandbox API
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create comprehensive documentation for sandbox API.
+
+**Tasks:**
+- [ ] Document API endpoints
+- [ ] Add request/response examples
+- [ ] Create usage guide
+- [ ] Add code examples
+- [ ] Create tutorials
+
+**Acceptance Criteria:**
+- API fully documented
+- Examples clear
+- Tutorials helpful
+
+---
+
+## Milestone 6: SDK Development
+
+### Issue #36: Design SDK API
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Design Python SDK interface for both Lambda and Sandbox styles.
+
+**Tasks:**
+- [ ] Design Lambda-style API
+- [ ] Design Sandbox-style API
+- [ ] Define common interfaces
+- [ ] Review with team
+- [ ] Create API specification
+
+**Acceptance Criteria:**
+- API designed
+- Both styles supported
+- Team approved
+
+---
+
+### Issue #37: Create sdk/python module
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Implement Python SDK.
+
+**Tasks:**
+- [ ] Create sdk/python/ directory
+- [ ] Set up Python project structure
+- [ ] Implement base client
+- [ ] Add authentication
+- [ ] Create sdk/python/README.md
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- SDK structure in place
+- Base client works
+- Tests pass
+
+---
+
+### Issue #38: Implement Lambda-style API
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Implement Lambda-style function invocation in SDK.
+
+**Tasks:**
+- [ ] Implement function invocation
+- [ ] Add async support
+- [ ] Add result handling
+- [ ] Add error handling
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- Lambda API works
+- Async supported
+- Tests pass
+
+---
+
+### Issue #39: Implement Sandbox-style API
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Implement Sandbox-style operations in SDK.
+
+**Tasks:**
+- [ ] Implement sandbox creation
+- [ ] Implement code execution
+- [ ] Implement file operations
+- [ ] Add lifecycle operations
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- Sandbox API works
+- All operations supported
+- Tests pass
+
+---
+
+### Issue #40: Add SDK tests
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Add comprehensive tests for SDK.
+
+**Tasks:**
+- [ ] Add unit tests
+- [ ] Add integration tests
+- [ ] Add mock server tests
+- [ ] Achieve >80% coverage
+
+**Acceptance Criteria:**
+- All components tested
+- Coverage >80%
+- Tests pass
+
+---
+
+### Issue #41: Create SDK examples
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create example code for both Lambda and Sandbox styles.
+
+**Tasks:**
+- [ ] Create Lambda examples
+- [ ] Create Sandbox examples
+- [ ] Create advanced examples
+- [ ] Add documentation
+- [ ] Test examples
+
+**Acceptance Criteria:**
+- Examples work
+- Cover common use cases
+- Well documented
+
+---
+
+### Issue #42: Document SDK
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create comprehensive SDK documentation.
+
+**Tasks:**
+- [ ] Document installation
+- [ ] Document authentication
+- [ ] Document Lambda API
+- [ ] Document Sandbox API
+- [ ] Add tutorials
+- [ ] Add API reference
+
+**Acceptance Criteria:**
+- SDK fully documented
+- Tutorials clear
+- API reference complete
+
+---
+
+### Issue #43: Publish SDK
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Prepare SDK for PyPI publication.
+
+**Tasks:**
+- [ ] Set up PyPI account
+- [ ] Configure setup.py
+- [ ] Add package metadata
+- [ ] Test installation
+- [ ] Publish to PyPI
+
+**Acceptance Criteria:**
+- SDK on PyPI
+- Installation works
+- Metadata correct
+
+---
+
+## Milestone 7: Internal Utilities and Assets
+
+### Issue #44: Create internal/logging module
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create centralized logging utilities.
+
+**Tasks:**
+- [ ] Create internal/logging/ directory
+- [ ] Implement logging utilities
+- [ ] Add structured logging
+- [ ] Add log levels
+- [ ] Create internal/logging/README.md
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- Logging utilities work
+- Structured logging supported
+- Tests pass
+
+---
+
+### Issue #45: Create internal/config module
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create configuration management utilities.
+
+**Tasks:**
+- [ ] Create internal/config/ directory
+- [ ] Implement config loading
+- [ ] Add validation
+- [ ] Add defaults
+- [ ] Create internal/config/README.md
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- Config loading works
+- Validation works
+- Tests pass
+
+---
+
+### Issue #46: Create internal/errors module
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create error handling utilities.
+
+**Tasks:**
+- [ ] Create internal/errors/ directory
+- [ ] Define error types
+- [ ] Implement error wrapping
+- [ ] Add error codes
+- [ ] Create internal/errors/README.md
+- [ ] Add tests
+
+**Acceptance Criteria:**
+- Error utilities work
+- Error codes defined
+- Tests pass
+
+---
+
+### Issue #47: Organize assets/ directory
+**Priority:** Low  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Organize VM assets (kernels, rootfs, snapshots).
+
+**Tasks:**
+- [ ] Create assets/ directory
+- [ ] Create assets/kernels/
+- [ ] Create assets/rootfs/
+- [ ] Create assets/snapshots/
+- [ ] Move existing assets
+- [ ] Add README files
+
+**Acceptance Criteria:**
+- Assets organized
+- README files added
+- Structure clear
+
+---
+
+### Issue #48: Update asset references
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Update all references to assets to use new paths.
+
+**Tasks:**
+- [ ] Find all asset references
+- [ ] Update paths
+- [ ] Test asset loading
+- [ ] Update configuration
+
+**Acceptance Criteria:**
+- All references updated
+- Assets load correctly
+- Tests pass
+
+---
+
+### Issue #49: Add internal tests
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Add tests for internal utilities.
+
+**Tasks:**
+- [ ] Add logging tests
+- [ ] Add config tests
+- [ ] Add error tests
+- [ ] Achieve >80% coverage
+
+**Acceptance Criteria:**
+- All utilities tested
+- Coverage >80%
+- Tests pass
+
+---
+
+### Issue #50: Document internal modules
+**Priority:** Low  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Document internal module APIs.
+
+**Tasks:**
+- [ ] Document logging API
+- [ ] Document config API
+- [ ] Document errors API
+- [ ] Add usage examples
+
+**Acceptance Criteria:**
+- APIs documented
+- Examples clear
+
+---
+
+## Milestone 8: Testing and Documentation
+
+### Issue #51: Integration testing
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create end-to-end tests for both Lambda and Sandbox workflows.
+
+**Tasks:**
+- [ ] Create test framework
+- [ ] Add Lambda e2e tests
+- [ ] Add Sandbox e2e tests
+- [ ] Add performance tests
+- [ ] Add load tests
+
+**Acceptance Criteria:**
+- E2E tests pass
+- Both modes tested
+- Performance acceptable
+
+---
+
+### Issue #52: Performance benchmarking
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Compare performance before and after restructuring.
+
+**Tasks:**
+- [ ] Set up benchmarks
+- [ ] Run baseline benchmarks
+- [ ] Run new benchmarks
+- [ ] Compare results
+- [ ] Document findings
+
+**Acceptance Criteria:**
+- Benchmarks complete
+- Performance meets/exceeds baseline
+- Results documented
+
+---
+
+### Issue #53: Update README
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Update project README for new architecture.
+
+**Tasks:**
+- [ ] Update architecture section
+- [ ] Update getting started
+- [ ] Update examples
+- [ ] Add sandbox documentation
+- [ ] Update screenshots
+
+**Acceptance Criteria:**
+- README accurate
+- Examples work
+- Up to date
+
+---
+
+### Issue #54: Update architecture docs
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Update architecture documentation.
+
+**Tasks:**
+- [ ] Update architecture diagram
+- [ ] Document new modules
+- [ ] Update design docs
+- [ ] Add decision records
+
+**Acceptance Criteria:**
+- Architecture documented
+- Diagram current
+- Design clear
+
+---
+
+### Issue #55: Create migration guide
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create guide for users to migrate to new version.
+
+**Tasks:**
+- [ ] Document breaking changes
+- [ ] Create migration steps
+- [ ] Add code examples
+- [ ] Create troubleshooting guide
+
+**Acceptance Criteria:**
+- Migration guide complete
+- Breaking changes documented
+- Examples clear
+
+---
+
+### Issue #56: Update CONTRIBUTING
+**Priority:** Medium  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Update contribution guidelines for new structure.
+
+**Tasks:**
+- [ ] Update development setup
+- [ ] Update coding standards
+- [ ] Update module guidelines
+- [ ] Update PR process
+
+**Acceptance Criteria:**
+- Guidelines updated
+- Structure reflected
+- Process clear
+
+---
+
+### Issue #57: Code review
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Comprehensive code review of new architecture.
+
+**Tasks:**
+- [ ] Review all modules
+- [ ] Check code quality
+- [ ] Check consistency
+- [ ] Check documentation
+- [ ] Address feedback
+
+**Acceptance Criteria:**
+- All code reviewed
+- Quality high
+- Consistency good
+
+---
+
+### Issue #58: Security audit
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Security review of new architecture.
+
+**Tasks:**
+- [ ] Audit VM isolation
+- [ ] Audit network security
+- [ ] Audit authentication
+- [ ] Audit sandbox security
+- [ ] Address findings
+
+**Acceptance Criteria:**
+- Security reviewed
+- No critical issues
+- Findings addressed
+
+---
+
+## Milestone 9: Release Preparation
+
+### Issue #59: Final testing
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Comprehensive testing in production-like environment.
+
+**Tasks:**
+- [ ] Set up staging environment
+- [ ] Run all tests
+- [ ] Load testing
+- [ ] Stress testing
+- [ ] User acceptance testing
+
+**Acceptance Criteria:**
+- All tests pass
+- Performance acceptable
+- No critical bugs
+
+---
+
+### Issue #60: Update changelog
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Document all changes in changelog.
+
+**Tasks:**
+- [ ] Review all changes
+- [ ] Write changelog entries
+- [ ] Categorize changes
+- [ ] Add migration notes
+
+**Acceptance Criteria:**
+- Changelog complete
+- All changes documented
+- Categories clear
+
+---
+
+### Issue #61: Create release notes
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Prepare release notes for new version.
+
+**Tasks:**
+- [ ] Write highlights
+- [ ] Document new features
+- [ ] Document breaking changes
+- [ ] Add upgrade instructions
+
+**Acceptance Criteria:**
+- Release notes complete
+- Features highlighted
+- Upgrade path clear
+
+---
+
+### Issue #62: Update version numbers
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Bump version numbers for release.
+
+**Tasks:**
+- [ ] Update version in code
+- [ ] Update version in docs
+- [ ] Update version in SDK
+- [ ] Follow semantic versioning
+
+**Acceptance Criteria:**
+- Versions updated
+- Semantic versioning followed
+- Consistent across project
+
+---
+
+### Issue #63: Tag release
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Create git tags for release.
+
+**Tasks:**
+- [ ] Create release tag
+- [ ] Push tag to GitHub
+- [ ] Create GitHub release
+- [ ] Attach release notes
+
+**Acceptance Criteria:**
+- Tag created
+- Release published
+- Notes attached
+
+---
+
+### Issue #64: Deploy to staging
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Deploy new version to staging environment.
+
+**Tasks:**
+- [ ] Build release binaries
+- [ ] Deploy to staging
+- [ ] Verify deployment
+- [ ] Run smoke tests
+
+**Acceptance Criteria:**
+- Deployed successfully
+- Smoke tests pass
+- Staging healthy
+
+---
+
+### Issue #65: User acceptance testing
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Testing with real users in staging.
+
+**Tasks:**
+- [ ] Recruit test users
+- [ ] Provide test instructions
+- [ ] Collect feedback
+- [ ] Address issues
+
+**Acceptance Criteria:**
+- Users tested
+- Feedback collected
+- Issues addressed
+
+---
+
+### Issue #66: Deploy to production
+**Priority:** High  
+**Status:** Not Started  
+**Assignee:** TBD
+
+**Description:**
+Production deployment of new version.
+
+**Tasks:**
+- [ ] Create deployment plan
+- [ ] Build production binaries
+- [ ] Deploy to production
+- [ ] Monitor deployment
+- [ ] Verify functionality
+
+**Acceptance Criteria:**
+- Deployed successfully
+- No critical issues
+- Monitoring healthy
+
+---
+
+## Summary
+
+**Total Issues:** 66  
+**Completed:** 2  
+**In Progress:** 1  
+**Not Started:** 63
+
+**Priority Breakdown:**
+- High Priority: 45 issues
+- Medium Priority: 18 issues
+- Low Priority: 3 issues
+
+---
+
+## Notes
+
+- Issues can be worked on in parallel when dependencies allow
+- Each issue should have tests and documentation
+- All issues should go through code review
+- Security-sensitive issues require security review
+
+---
+
+## Related Documents
+
+- [RESTRUCTURING.md](RESTRUCTURING.md) - Overall restructuring plan
+- [MILESTONES.md](MILESTONES.md) - Milestone tracking
+- [README.md](README.md) - Project overview
diff --git a/MILESTONES.md b/MILESTONES.md
new file mode 100644
index 0000000..6a1a80a
--- /dev/null
+++ b/MILESTONES.md
@@ -0,0 +1,277 @@
+# Skyscale Restructuring Milestones
+
+This document tracks the milestones for restructuring Skyscale to support both Lambda-style execution and E2B-style long-lived sandboxes.
+
+---
+
+## Milestone 1: Foundation and Documentation
+**Target:** Week 1
+**Status:** In Progress
+
+### Goals
+- Document the restructuring plan
+- Create directory structure
+- Set up tracking infrastructure
+
+### Issues
+1. **Create restructuring documentation** - Document the overall plan and architecture
+2. **Create milestone tracking** - Set up milestone and issue tracking
+3. **Create directory structure placeholders** - Create new directories with README files
+4. **Document current architecture** - Document the existing architecture for reference
+
+### Success Criteria
+- [ ] All documentation files created
+- [ ] Directory structure initialized
+- [ ] Team aligned on restructuring plan
+
+---
+
+## Milestone 2: VM Module Extraction
+**Target:** Weeks 2-3
+**Status:** Not Started
+
+### Goals
+- Extract all Firecracker-related code into `vm/` module
+- Establish VM module as the single source of truth for VM operations
+- No functional changes, pure refactoring
+
+### Issues
+5. **Create vm/manager module** - Move control-plane/vm/ to vm/manager/
+6. **Create vm/pool module** - Extract VM pool logic into dedicated module
+7. **Create vm/snapshot module** - Create snapshot management module
+8. **Create vm/network module** - Extract network configuration logic
+9. **Create vm/jailer module** - Create security isolation module
+10. **Update all imports** - Update imports across codebase to use new vm/ module
+11. **Add vm/ module tests** - Ensure test coverage for vm/ module
+12. **Update documentation** - Document vm/ module API
+
+### Success Criteria
+- [ ] All Firecracker code in vm/ module
+- [ ] No direct Firecracker dependencies outside vm/
+- [ ] All tests passing
+- [ ] Documentation updated
+
+---
+
+## Milestone 3: Runtime Formalization
+**Target:** Weeks 4-5
+**Status:** Not Started
+
+### Goals
+- Formalize the guest runtime as a first-class module
+- Define clear host ↔ guest protocol
+- Separate agent, Python runtime, and protocol
+
+### Issues
+13. **Create runtime/agent module** - Formalize Go agent as a module
+14. **Create runtime/python module** - Extract Python runtime bootstrap
+15. **Create runtime/protocol module** - Define host-guest communication protocol
+16. **Document protocol specification** - Write comprehensive protocol docs
+17. **Implement protocol versioning** - Add version negotiation support
+18. **Add runtime tests** - Test host-guest communication
+19. **Update agent deployment** - Update how agent is deployed to VMs
+
+### Success Criteria
+- [ ] Clear protocol definition
+- [ ] Agent is a standalone module
+- [ ] Protocol versioning in place
+- [ ] All tests passing
+
+---
+
+## Milestone 4: Control Plane Reorganization
+**Target:** Weeks 6-7
+**Status:** Not Started
+
+### Goals
+- Move control plane to be orchestration-only
+- Remove all VM and runtime logic
+- Create thin entry points in cmd/
+
+### Issues
+20. **Create cmd/control-plane** - Move main.go to cmd/control-plane/main.go
+21. **Remove VM logic from control-plane** - Control plane uses vm/ module only
+22. **Refactor control-plane/api** - Clean up API handlers
+23. **Update control-plane/scheduler** - Scheduler uses vm/ module
+24. **Clean up control-plane imports** - Remove direct Firecracker dependencies
+25. **Add control-plane tests** - Test orchestration logic
+26. **Update build scripts** - Update Makefile and build scripts
+
+### Success Criteria
+- [ ] Control plane has no Firecracker dependencies
+- [ ] Entry points in cmd/ are thin
+- [ ] All tests passing
+- [ ] Build scripts updated
+
+---
+
+## Milestone 5: Sandbox API Implementation
+**Target:** Weeks 8-10
+**Status:** Not Started
+
+### Goals
+- Implement E2B-style sandbox API
+- Support long-lived VM sessions
+- Implement behind feature flag
+
+### Issues
+27. **Design sandbox API** - Design REST API for sandbox operations
+28. **Create sandbox/api module** - Implement API handlers
+29. **Create sandbox/lifecycle module** - Implement create/suspend/resume/destroy
+30. **Create sandbox/exec module** - Implement code execution in sandboxes
+31. **Create sandbox/fs module** - Implement filesystem operations
+32. **Add feature flag** - Implement feature flag for sandbox mode
+33. **Implement sandbox state management** - Track sandbox lifecycle state
+34. **Add sandbox tests** - Comprehensive testing for sandbox operations
+35. **Document sandbox API** - API documentation and examples
+
+### Success Criteria
+- [ ] Sandbox API functional behind feature flag
+- [ ] Can create and manage long-lived sandboxes
+- [ ] File upload/download working
+- [ ] Comprehensive tests
+- [ ] API documented
+
+---
+
+## Milestone 6: SDK Development
+**Target:** Weeks 11-12
+**Status:** Not Started
+
+### Goals
+- Create Python SDK for both Lambda and Sandbox styles
+- Provide excellent developer experience
+- Include examples and documentation
+
+### Issues
+36. **Design SDK API** - Design Python SDK interface
+37. **Create sdk/python module** - Implement Python SDK
+38. **Implement Lambda-style API** - Support function invocation
+39. **Implement Sandbox-style API** - Support sandbox operations
+40. **Add SDK tests** - Test SDK functionality
+41. **Create SDK examples** - Example code for both styles
+42. **Document SDK** - Comprehensive SDK documentation
+43. **Publish SDK** - Prepare for PyPI publication
+
+### Success Criteria
+- [ ] Python SDK supports both Lambda and Sandbox
+- [ ] Excellent developer experience
+- [ ] Examples and documentation complete
+- [ ] Ready for release
+
+---
+
+## Milestone 7: Internal Utilities and Assets
+**Target:** Weeks 13-14
+**Status:** Not Started
+
+### Goals
+- Extract common utilities to internal/
+- Organize assets properly
+- Improve code reuse
+
+### Issues
+44. **Create internal/logging module** - Centralized logging utilities
+45. **Create internal/config module** - Configuration management
+46. **Create internal/errors module** - Error handling utilities
+47. **Organize assets/ directory** - Move kernels, rootfs, snapshots
+48. **Update asset references** - Update all references to assets
+49. **Add internal tests** - Test internal utilities
+50. **Document internal modules** - Document internal API
+
+### Success Criteria
+- [ ] Common utilities extracted
+- [ ] Assets organized
+- [ ] Code duplication reduced
+- [ ] All tests passing
+
+---
+
+## Milestone 8: Testing and Documentation
+**Target:** Weeks 15-16
+**Status:** Not Started
+
+### Goals
+- Comprehensive testing of new architecture
+- Update all documentation
+- Performance benchmarking
+
+### Issues
+51. **Integration testing** - End-to-end tests for both Lambda and Sandbox
+52. **Performance benchmarking** - Compare performance before/after
+53. **Update README** - Update project README
+54. **Update architecture docs** - Update architecture documentation
+55. **Create migration guide** - Guide for users to migrate
+56. **Update CONTRIBUTING** - Update contribution guidelines
+57. **Code review** - Comprehensive code review
+58. **Security audit** - Security review of new architecture
+
+### Success Criteria
+- [ ] All tests passing
+- [ ] Performance meets or exceeds baseline
+- [ ] Documentation complete
+- [ ] Security reviewed
+
+---
+
+## Milestone 9: Release Preparation
+**Target:** Week 17
+**Status:** Not Started
+
+### Goals
+- Prepare for release
+- Final testing and validation
+- Communication and rollout
+
+### Issues
+59. **Final testing** - Comprehensive testing in production-like environment
+60. **Update changelog** - Document all changes
+61. **Create release notes** - Prepare release notes
+62. **Update version numbers** - Bump version numbers
+63. **Tag release** - Create git tags
+64. **Deploy to staging** - Deploy to staging environment
+65. **User acceptance testing** - Testing with real users
+66. **Deploy to production** - Production deployment
+
+### Success Criteria
+- [ ] All testing complete
+- [ ] Release notes prepared
+- [ ] Deployed successfully
+- [ ] No critical issues
+
+---
+
+## Timeline Overview
+
+```
+Week 1-1:    M1 - Foundation and Documentation
+Week 2-3:    M2 - VM Module Extraction
+Week 4-5:    M3 - Runtime Formalization
+Week 6-7:    M4 - Control Plane Reorganization
+Week 8-10:   M5 - Sandbox API Implementation
+Week 11-12:  M6 - SDK Development
+Week 13-14:  M7 - Internal Utilities and Assets
+Week 15-16:  M8 - Testing and Documentation
+Week 17:     M9 - Release Preparation
+```
+
+**Total Duration:** ~4 months
+
+---
+
+## Notes
+
+- Milestones can overlap when dependencies allow
+- Each milestone includes testing and documentation
+- Feature flags protect experimental features
+- Rollback plan exists for each milestone
+
+---
+
+## Progress Tracking
+
+Track progress using:
+- This document for milestone-level tracking
+- [ISSUES.md](ISSUES.md) for issue-level tracking
+- GitHub Issues for detailed task management
+- GitHub Projects for visual progress tracking
diff --git a/RESTRUCTURING.md b/RESTRUCTURING.md
new file mode 100644
index 0000000..96f9ae4
--- /dev/null
+++ b/RESTRUCTURING.md
@@ -0,0 +1,229 @@
+# Skyscale Repository Restructuring
+
+## Overview
+
+This document outlines the comprehensive restructuring plan for Skyscale to support both Lambda-style execution and E2B-style long-lived sandboxes while maintaining clean architectural boundaries.
+
+## Core Design Principle
+
+**Separate by responsibility, not by language or feature.**
+
+The restructuring addresses the current interleaving of concerns:
+- Function execution
+- VM lifecycle management
+- Control-plane orchestration logic
+- Guest runtime
+
+These will become **first-class modules** with clear ownership boundaries.
+
+---
+
+## Proposed Top-Level Structure
+
+```
+skyscale/
+│
+├── cmd/                     # Entry points only (thin)
+│   ├── control-plane/       # Control plane daemon
+│   ├── sandboxd/            # NEW: Sandbox-oriented daemon
+│   └── cli/                 # CLI tool
+│
+├── control-plane/           # API + orchestration logic ONLY
+│   ├── api/                 # REST/gRPC API handlers
+│   ├── scheduler/           # Request routing and scheduling
+│   ├── auth/                # Authentication and authorization
+│   ├── state/               # State management
+│   └── registry/            # Function registry
+│
+├── vm/                      # Firecracker & VM lifecycle (CRITICAL)
+│   ├── manager/             # VM start/stop/lifecycle
+│   ├── pool/                # Pre-warmed VM pool management
+│   ├── snapshot/            # Snapshot create/restore
+│   ├── network/             # TAP, vsock, bridges
+│   └── jailer/              # Seccomp, UID isolation
+│
+├── runtime/                 # Guest-side logic (inside VM)
+│   ├── agent/               # Go agent (runs inside VM)
+│   ├── python/              # Python runtime bootstrap
+│   └── protocol/            # Host ↔ guest communication contracts
+│
+├── sandbox/                 # NEW: E2B-style sandbox abstraction
+│   ├── api/                 # Sandbox REST API handlers
+│   ├── lifecycle/           # Create, suspend, resume, destroy
+│   ├── exec/                # Shell + Python execution
+│   └── fs/                  # Workspace, mounts, limits
+│
+├── sdk/                     # Client-facing SDKs
+│   ├── python/              # Python SDK
+│   └── types/               # Shared type definitions
+│
+├── assets/                  # VM assets
+│   ├── kernels/             # Kernel images
+│   ├── rootfs/              # Root filesystem images
+│   └── snapshots/           # VM snapshots
+│
+├── internal/                # Shared internal utilities
+│   ├── logging/             # Logging utilities
+│   ├── config/              # Configuration management
+│   └── errors/              # Error handling
+│
+├── perf/                    # Performance testing
+├── scripts/                 # Build and utility scripts
+├── examples/                # Example functions
+└── docs/                    # Documentation
+```
+
+---
+
+## Why This Structure Works
+
+### 1. `vm/` becomes sacred ground
+
+Everything Firecracker-related lives here. This is the single source of truth for:
+- Starting/stopping microVMs
+- Managing VM pools
+- Creating/restoring snapshots
+- Network configuration
+- Security isolation (jailer)
+
+**Critical Rule:** Nothing outside `vm/` talks to Firecracker directly.
+
+This enables:
+- Lambda execution
+- Long-lived sandboxes
+- REPL environments
+- Testing
+...to all reuse the same VM machinery.
+
+### 2. `runtime/` cleanly separates host vs guest
+
+The Go agent and Python runtime are formalized as first-class components.
+
+#### Protocol is Key
+
+Define clear contracts for:
+- `Exec` - Execute code
+- `UploadFile` - Transfer files
+- `StreamLogs` - Stream execution logs
+- `Shutdown` - Graceful shutdown
+
+Once frozen, everything becomes composable.
+
+### 3. `sandbox/` is a new first-class product
+
+This enables E2B-style sandboxes **without touching Lambda logic**.
+
+A sandbox is simply:
+> A long-lived VM + relaxed execution semantics
+
+Same VM manager, different policy.
+
+### 4. `control-plane/` stops doing too much
+
+It becomes orchestration-only:
+- Request routing
+- Authentication
+- State management
+- Function registry
+
+**No Firecracker code. No runtime logic.**
+
+### 5. `cmd/` stays thin (non-negotiable)
+
+Each entry point:
+- Loads config
+- Wires dependencies
+- Starts services
+
+**No business logic in main.go**
+
+### 6. SDKs live outside infrastructure
+
+The Python SDK will support both:
+
+```python
+# Lambda-style
+invoke("fn", payload)
+
+# Sandbox-style
+sb = Sandbox()
+sb.exec("pip install torch")
+sb.exec("python train.py")
+```
+
+Same backend. Different UX.
+
+---
+
+## Migration Strategy (Low Risk)
+
+### Step 1: Extract VM Logic
+- Move Firecracker code → `vm/`
+- No behavior change
+- Update imports
+
+### Step 2: Formalize Guest Protocol
+- Lock host ↔ agent contracts
+- Document protocol in `runtime/protocol/`
+
+### Step 3: Introduce `sandbox/` Behind Feature Flag
+- Reuse VM pool, snapshots, agent
+- Implement sandbox API
+- Keep disabled by default
+
+### Step 4: SDK-First Development
+- Design Python SDK before API changes
+- Validate developer experience
+
+### Step 5: Reorganize Control Plane
+- Move entry points to `cmd/`
+- Remove VM dependencies
+- Use `vm/` module exclusively
+
+### Step 6: Add Internal Utilities
+- Extract common utilities to `internal/`
+- Improve code reuse
+
+---
+
+## What This Unlocks
+
+### Immediately
+- REPL-like sandboxes
+- Stateful execution
+- Better cold-start control
+- Cleaner code boundaries
+
+### Soon
+- Notebook-style workflows
+- CI sandboxes
+- ML training jobs
+- Dev environments
+
+### Long-term
+**Skyscale ≠ Lambda clone**
+**Skyscale = programmable compute substrate**
+
+---
+
+## Implementation Phases
+
+See [MILESTONES.md](MILESTONES.md) for detailed milestone breakdown and tracking.
+
+---
+
+## Notes
+
+- All changes should be incremental and testable
+- Each phase should maintain backward compatibility
+- Feature flags will protect experimental features
+- Comprehensive testing at each phase
+
+---
+
+## Related Documents
+
+- [MILESTONES.md](MILESTONES.md) - Detailed milestone tracking
+- [ISSUES.md](ISSUES.md) - Individual issue tracking
+- [README.md](README.md) - Project overview
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
diff --git a/RESTRUCTURING_SUMMARY.md b/RESTRUCTURING_SUMMARY.md
new file mode 100644
index 0000000..31d9e8d
--- /dev/null
+++ b/RESTRUCTURING_SUMMARY.md
@@ -0,0 +1,261 @@
+# Restructuring Implementation Summary
+
+## Overview
+
+This document provides a high-level summary of the Skyscale restructuring implementation.
+
+## What Has Been Created
+
+### 1. Documentation (Milestone 1 - Completed)
+
+#### Planning Documents
+- ✅ **RESTRUCTURING.md** - Comprehensive restructuring plan
+- ✅ **MILESTONES.md** - 9 milestones with 66 issues
+- ✅ **ISSUES.md** - Detailed issue tracking with 66 individual issues
+- ✅ **docs/architecture.md** - Architectural documentation
+
+#### Module Documentation
+25 README files created documenting:
+- Purpose and responsibilities of each module
+- Migration status
+- Future API designs
+- Usage examples
+
+### 2. Directory Structure (Milestone 1 - In Progress)
+
+Created complete directory structure for target architecture:
+
+```
+skyscale/
+├── vm/               # VM lifecycle (5 submodules)
+│   ├── manager/      # Core VM operations
+│   ├── pool/         # Pre-warmed pool
+│   ├── snapshot/     # Snapshot management
+│   ├── network/      # Network configuration
+│   └── jailer/       # Security isolation
+│
+├── runtime/          # Guest-side logic (3 submodules)
+│   ├── agent/        # Go agent (inside VM)
+│   ├── python/       # Python runtime
+│   └── protocol/     # Host-guest protocol
+│
+├── sandbox/          # E2B-style sandboxes (4 submodules)
+│   ├── api/          # Sandbox REST API
+│   ├── lifecycle/    # Create/suspend/resume/destroy
+│   ├── exec/         # Code execution
+│   └── fs/           # Filesystem operations
+│
+├── sdk/              # Client SDKs (2 submodules)
+│   ├── python/       # Python SDK
+│   └── types/        # Shared types
+│
+├── internal/         # Shared utilities (3 submodules)
+│   ├── logging/      # Logging utilities
+│   ├── config/       # Configuration
+│   └── errors/       # Error handling
+│
+├── assets/           # VM assets (3 submodules)
+│   ├── kernels/      # Kernel images
+│   ├── rootfs/       # Root filesystems
+│   └── snapshots/    # VM snapshots
+│
+├── cmd/
+│   └── sandboxd/     # Future sandbox daemon
+│
+└── docs/             # Documentation
+```
+
+### 3. Migration Planning
+
+#### Documented Migration Path
+Each module README includes:
+- Current status
+- Migration steps
+- Related issues
+- Future API design
+
+#### Issue Tracking
+66 issues organized into 9 milestones:
+1. ✅ Foundation and Documentation (Issues #1-4)
+2. ⏳ VM Module Extraction (Issues #5-12)
+3. ⏳ Runtime Formalization (Issues #13-19)
+4. ⏳ Control Plane Reorganization (Issues #20-26)
+5. ⏳ Sandbox API Implementation (Issues #27-35)
+6. ⏳ SDK Development (Issues #36-43)
+7. ⏳ Internal Utilities and Assets (Issues #44-50)
+8. ⏳ Testing and Documentation (Issues #51-58)
+9. ⏳ Release Preparation (Issues #59-66)
+
+## Design Principles Established
+
+### 1. Separation by Responsibility
+Modules organized by function, not language:
+- VM operations → `vm/`
+- Guest runtime → `runtime/`
+- Sandbox features → `sandbox/`
+- Client libraries → `sdk/`
+
+### 2. Sacred Ground
+**Nothing outside `vm/` talks to Firecracker directly.**
+
+This enables:
+- Lambda execution
+- Sandboxes
+- REPLs
+- Tests
+
+...to all reuse the same VM machinery.
+
+### 3. Protocol-First
+Host ↔ guest communication via well-defined protocol:
+- `Exec` - Execute code
+- `UploadFile` - Transfer file
+- `StreamLogs` - Stream output
+- `Shutdown` - Graceful stop
+
+### 4. Feature Isolation
+Sandbox features implemented without touching Lambda logic:
+> A sandbox = long-lived VM + different policy
+
+### 5. Thin Entry Points
+Entry points (`cmd/`) only:
+- Load config
+- Wire dependencies
+- Start services
+
+**No business logic in main.go**
+
+## What This Enables
+
+### Immediate Benefits
+- ✅ Clear module boundaries documented
+- ✅ Migration path established
+- ✅ Issues trackable
+- ✅ Team can collaborate effectively
+
+### Near-Term (4 months)
+- 🎯 Lambda-style execution (maintained)
+- 🎯 E2B-style sandboxes (new)
+- 🎯 Cleaner codebase
+- 🎯 Better testing
+
+### Long-Term
+Skyscale becomes a **programmable compute substrate** supporting:
+- Interactive notebooks
+- CI/CD sandboxes
+- ML training jobs
+- Dev environments
+- REPLs
+
+## Next Steps
+
+### For Development Team
+
+1. **Review Documentation**
+   - Read RESTRUCTURING.md
+   - Review MILESTONES.md
+   - Understand module responsibilities
+
+2. **Start Milestone 2** (VM Module Extraction)
+   - Issue #5: Create vm/manager module
+   - Issue #6: Create vm/pool module
+   - And so on...
+
+3. **Follow Best Practices**
+   - Make incremental changes
+   - Test at each step
+   - Maintain backward compatibility
+   - Use feature flags
+
+### For Stakeholders
+
+1. **Track Progress**
+   - Monitor milestone completion
+   - Review issue status
+   - Provide feedback
+
+2. **Plan Resources**
+   - ~4 month timeline
+   - 9 milestones
+   - 66 issues
+
+## Risk Mitigation
+
+### Low-Risk Approach
+- ✅ Documentation first (no code changes yet)
+- ✅ Clear migration path
+- ✅ Incremental changes
+- ✅ Feature flags for new features
+- ✅ Backward compatibility maintained
+
+### Testing Strategy
+- Unit tests at module level
+- Integration tests at system level
+- Performance benchmarking
+- Security audits
+
+### Rollback Plan
+Each milestone is independent and can be:
+- Rolled back if issues arise
+- Paused for higher priority work
+- Adjusted based on feedback
+
+## Success Metrics
+
+### Code Quality
+- [ ] Clear module boundaries
+- [ ] No circular dependencies
+- [ ] >80% test coverage
+- [ ] Clean imports
+
+### Performance
+- [ ] Cold start ≤ baseline
+- [ ] Execution time ≤ baseline
+- [ ] Memory usage ≤ baseline
+- [ ] Pool efficiency improved
+
+### Features
+- [ ] Lambda execution working
+- [ ] Sandbox API functional
+- [ ] Python SDK published
+- [ ] Documentation complete
+
+### Developer Experience
+- [ ] Easy to understand
+- [ ] Easy to contribute
+- [ ] Well documented
+- [ ] Good examples
+
+## Timeline
+
+```
+Month 1: Milestones 1-2 (Foundation + VM Extraction)
+Month 2: Milestones 3-4 (Runtime + Control Plane)
+Month 3: Milestones 5-6 (Sandbox + SDK)
+Month 4: Milestones 7-9 (Internal + Testing + Release)
+```
+
+## Conclusion
+
+The foundation for Skyscale restructuring is now in place:
+- ✅ Clear vision documented
+- ✅ Directory structure created
+- ✅ Migration path established
+- ✅ Issues defined and trackable
+- ✅ Team can start execution
+
+The restructuring will transform Skyscale from a Lambda clone into a **programmable compute substrate** that supports multiple execution models while maintaining clean architecture.
+
+---
+
+**Status**: Milestone 1 Complete (Issues #1-3 ✅, Issue #4 in progress)
+
+**Next**: Begin Milestone 2 - VM Module Extraction (Issues #5-12)
+
+**Timeline**: 4 months for complete restructuring
+
+**Risk Level**: Low (incremental, documented, testable)
+
+---
+
+Last Updated: 2026-01-15
diff --git a/assets/README.md b/assets/README.md
new file mode 100644
index 0000000..a340083
--- /dev/null
+++ b/assets/README.md
@@ -0,0 +1,60 @@
+# Assets
+
+VM assets including kernels, root filesystems, and snapshots.
+
+## Structure
+
+### `assets/kernels/`
+Linux kernel images for Firecracker VMs:
+- vmlinux-5.10 (default)
+- vmlinux-6.1 (newer)
+- Custom kernels
+
+### `assets/rootfs/`
+Root filesystem images:
+- base-python3.8.ext4
+- base-python3.9.ext4
+- base-python3.10.ext4
+
+### `assets/snapshots/`
+VM snapshots for fast initialization:
+- Organized by runtime
+- Versioned
+- Metadata included
+
+## Building Assets
+
+### Kernel
+
+See [scripts/build-kernel.sh](../scripts/build-kernel.sh)
+
+### Root Filesystem
+
+See [scripts/build-rootfs.sh](../scripts/build-rootfs.sh)
+
+### Snapshots
+
+Snapshots are created automatically by the VM manager.
+
+## Configuration
+
+Asset paths are configured via environment variables:
+
+```bash
+FAAS_VM_KERNEL_PATH=/path/to/vmlinux
+FAAS_VM_ROOTFS_PATH=/path/to/rootfs.ext4
+FAAS_SNAPSHOT_DIR=/path/to/snapshots
+```
+
+## Migration Status
+
+🚧 **To Be Organized** - Assets currently in various locations
+
+See [Issue #47-#48](../ISSUES.md) for details.
+
+## Best Practices
+
+- Keep assets immutable
+- Version assets clearly
+- Document asset requirements
+- Automate asset builds
diff --git a/cmd/sandboxd/README.md b/cmd/sandboxd/README.md
new file mode 100644
index 0000000..d6ccc00
--- /dev/null
+++ b/cmd/sandboxd/README.md
@@ -0,0 +1,46 @@
+# Sandboxd
+
+Sandbox-oriented daemon for managing long-lived execution environments.
+
+## Purpose
+
+A specialized daemon for sandbox operations, separate from the control plane.
+
+## Responsibilities
+
+- Manage sandbox lifecycle
+- Handle sandbox API requests
+- Monitor sandbox health
+- Enforce resource limits
+- Clean up idle sandboxes
+
+## Comparison to Control Plane
+
+| Feature | Control Plane | Sandboxd |
+|---------|---------------|----------|
+| Focus | Function invocation | Long-lived sandboxes |
+| Lifetime | Seconds | Minutes to hours |
+| State | Stateless | Stateful |
+| API | Function API | Sandbox API |
+
+## Migration Status
+
+🚧 **Future Enhancement** - Optional separate daemon
+
+May be implemented later to separate concerns or can be integrated into control plane.
+
+## Configuration
+
+```yaml
+sandboxd:
+  port: 8081
+  max_sandboxes: 100
+  idle_timeout: 3600
+  cleanup_interval: 300
+```
+
+## Running
+
+```bash
+./sandboxd --config sandboxd.yaml
+```
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..fef4c99
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,46 @@
+# Documentation
+
+Comprehensive documentation for Skyscale.
+
+## Contents
+
+### Architecture
+- [Architecture Overview](architecture.md)
+- [VM Module](../vm/README.md)
+- [Runtime Module](../runtime/README.md)
+- [Sandbox Module](../sandbox/README.md)
+
+### Getting Started
+- [Installation](installation.md)
+- [Quick Start](quickstart.md)
+- [Configuration](configuration.md)
+
+### Development
+- [Development Setup](development.md)
+- [Contributing](../CONTRIBUTING.md)
+- [Testing](testing.md)
+
+### API Reference
+- [REST API](api-reference.md)
+- [Python SDK](../sdk/python/README.md)
+- [Protocol](../runtime/protocol/README.md)
+
+### Operations
+- [Deployment](deployment.md)
+- [Monitoring](monitoring.md)
+- [Security](security.md)
+
+### Guides
+- [Lambda Functions](guides/lambda-functions.md)
+- [Sandboxes](guides/sandboxes.md)
+- [Performance Tuning](guides/performance.md)
+
+## Migration Status
+
+🚧 **To Be Enhanced**
+
+Additional documentation will be added as features are implemented.
+
+## Contributing
+
+Help improve the docs! See [CONTRIBUTING.md](../CONTRIBUTING.md).
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..88b2972
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,238 @@
+# Skyscale Architecture
+
+## Overview
+
+Skyscale is a serverless platform that supports both Lambda-style function execution and E2B-style long-lived sandboxes, built on Firecracker microVMs.
+
+## Core Principles
+
+1. **Separation by Responsibility**: Modules organized by function, not by language or feature
+2. **Single Source of Truth**: VM operations only in `vm/` module
+3. **Clean Boundaries**: Clear interfaces between modules
+4. **Feature Flexibility**: Support multiple execution models with shared infrastructure
+
+## Module Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Entry Points                         │
+│                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │  control-    │  │              │  │     CLI      │     │
+│  │   plane      │  │  sandboxd    │  │    Tool      │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+└──────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────┴───────────────────────────────────┐
+│                    Control Plane Layer                       │
+│                                                              │
+│  ┌─────────┐  ┌──────────┐  ┌──────┐  ┌───────┐           │
+│  │   API   │  │Scheduler │  │ Auth │  │ State │           │
+│  └─────────┘  └──────────┘  └──────┘  └───────┘           │
+└──────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────┴───────────────────────────────────┐
+│                    Execution Layer                           │
+│                                                              │
+│  ┌─────────────────────┐         ┌──────────────────────┐  │
+│  │    VM Module        │         │   Sandbox Module     │  │
+│  │                     │         │                      │  │
+│  │  • Manager          │         │  • API               │  │
+│  │  • Pool             │         │  • Lifecycle         │  │
+│  │  • Snapshot         │         │  • Exec              │  │
+│  │  • Network          │         │  • Filesystem        │  │
+│  │  • Jailer           │         │                      │  │
+│  └─────────────────────┘         └──────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────┴───────────────────────────────────┐
+│                    Runtime Layer                             │
+│                   (Inside VMs)                              │
+│                                                              │
+│  ┌─────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │  Agent  │  │    Python    │  │  Protocol    │          │
+│  │  (Go)   │  │   Runtime    │  │              │          │
+│  └─────────┘  └──────────────┘  └──────────────┘          │
+└──────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────┐
+│                      Client Layer                             │
+│                                                              │
+│                    ┌────────────┐                            │
+│                    │ Python SDK │                            │
+│                    └────────────┘                            │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+### Lambda-Style Invocation
+
+```
+Client → API → Scheduler → VM Manager → VM Pool → Agent → Python → Result
+```
+
+1. Client sends function invocation request
+2. API validates and authenticates
+3. Scheduler selects VM
+4. VM Manager provides VM from pool
+5. Agent receives request via protocol
+6. Python runtime executes handler
+7. Result streams back through chain
+
+### Sandbox-Style Session
+
+```
+Client → Sandbox API → Sandbox Lifecycle → VM Manager → VM → Agent → Python
+   ↓                                                                    ↑
+   └────────────────────── Multiple Exec Requests ───────────────────┘
+```
+
+1. Client creates sandbox
+2. Sandbox Lifecycle provisions VM
+3. VM persists in "ready" state
+4. Client sends multiple exec requests
+5. Each execution uses same VM
+6. Client destroys sandbox when done
+
+## Module Responsibilities
+
+### Entry Points (`cmd/`)
+- Parse configuration
+- Wire dependencies
+- Start services
+- **No business logic**
+
+### Control Plane
+- **API**: Handle HTTP requests
+- **Scheduler**: Route invocations to VMs
+- **Auth**: Verify API keys
+- **State**: Persist metadata
+- **Registry**: Manage functions
+
+### VM Module
+- **Manager**: VM lifecycle (create, stop, terminate)
+- **Pool**: Pre-warmed VM pool
+- **Snapshot**: Snapshot create/restore
+- **Network**: Network configuration
+- **Jailer**: Security isolation
+
+### Runtime Module
+- **Agent**: Host-guest communication (inside VM)
+- **Python**: Handler execution (inside VM)
+- **Protocol**: Message definitions
+
+### Sandbox Module
+- **API**: Sandbox REST endpoints
+- **Lifecycle**: Create, suspend, resume, destroy
+- **Exec**: Code execution
+- **Filesystem**: File operations
+
+### SDK
+- **Python**: Client library for both styles
+
+## Communication
+
+### Host ↔ Guest Protocol
+
+Defined in `runtime/protocol/`:
+
+```
+Host (Control Plane/Sandbox)
+  ↕ vsock or network
+Guest (Agent)
+  ↕ protocol messages
+Runtime (Python)
+```
+
+Messages:
+- `Exec`: Execute code
+- `UploadFile`: Transfer file
+- `StreamLogs`: Stream output
+- `Shutdown`: Graceful stop
+
+### API Communication
+
+```
+Client (SDK)
+  ↕ HTTPS
+Control Plane (API)
+  ↕ Internal calls
+VM/Sandbox Modules
+```
+
+## Security Model
+
+### Isolation Layers
+
+1. **Firecracker microVM**: Hardware-virtualized isolation
+2. **Jailer**: Additional seccomp, namespace, chroot isolation
+3. **Network**: Isolated network per VM
+4. **Filesystem**: Isolated workspace per sandbox
+
+### Authentication
+
+- API key authentication
+- Per-function/sandbox access control
+- Rate limiting
+- Audit logging
+
+## State Management
+
+### Persistent State (SQLite/Postgres)
+- Function metadata
+- Sandbox metadata
+- VM assignments
+- Execution history
+
+### Transient State (Memory)
+- VM pool
+- Active sandboxes
+- In-flight requests
+
+## Scaling
+
+### Horizontal Scaling
+- Multiple control plane instances
+- Load balancer for API requests
+- Shared state via database
+
+### Vertical Scaling
+- More VMs per host
+- Larger VM pool
+- More memory/CPU per VM
+
+## Performance Optimizations
+
+### Cold Start Reduction
+- Pre-warmed VM pool
+- Snapshot-based initialization
+- Concurrent pool filling
+
+### Execution Efficiency
+- Keep-alive for sandboxes
+- Efficient protocol (vsock)
+- Streaming output
+
+### Resource Management
+- CPU/memory limits per VM
+- Automatic scaling of pool
+- Idle timeout and cleanup
+
+## Future Enhancements
+
+1. **Multi-region**: Deploy across regions
+2. **Custom runtimes**: Support more languages
+3. **GPU support**: Add GPU-enabled VMs
+4. **Distributed tracing**: Full request tracing
+5. **Auto-scaling**: Dynamic pool sizing
+
+## Related Documents
+
+- [RESTRUCTURING.md](../RESTRUCTURING.md) - Restructuring plan
+- [MILESTONES.md](../MILESTONES.md) - Implementation roadmap
+- [ISSUES.md](../ISSUES.md) - Detailed issues
+
+---
+
+Last Updated: 2026-01-15
diff --git a/internal/README.md b/internal/README.md
new file mode 100644
index 0000000..5ac7c67
--- /dev/null
+++ b/internal/README.md
@@ -0,0 +1,62 @@
+# Internal Module
+
+Shared internal utilities used across Skyscale modules.
+
+## Purpose
+
+Common utilities to reduce code duplication and improve maintainability.
+
+## Submodules
+
+### `internal/logging/`
+Centralized logging utilities:
+- Structured logging
+- Log levels
+- Context-aware logging
+- Log formatting
+
+### `internal/config/`
+Configuration management:
+- Config file loading
+- Environment variable parsing
+- Validation
+- Defaults
+
+### `internal/errors/`
+Error handling utilities:
+- Error types
+- Error codes
+- Error wrapping
+- Error formatting
+
+## Important
+
+**Internal packages are not part of the public API.**
+
+These utilities are for use within Skyscale only and may change without notice.
+
+## Status
+
+🚧 **To Be Implemented**
+
+See [Issue #44-#50](../ISSUES.md) for tracking.
+
+## Usage
+
+```go
+import (
+    "github.com/bluequbit/faas/internal/logging"
+    "github.com/bluequbit/faas/internal/config"
+    "github.com/bluequbit/faas/internal/errors"
+)
+
+// Logging
+logger := logging.New("component")
+logger.Info("message", "key", "value")
+
+// Config
+cfg, err := config.Load("config.yaml")
+
+// Errors
+err := errors.New(errors.CodeNotFound, "resource not found")
+```
diff --git a/runtime/README.md b/runtime/README.md
new file mode 100644
index 0000000..a0db2e5
--- /dev/null
+++ b/runtime/README.md
@@ -0,0 +1,55 @@
+# Runtime Module
+
+The `runtime/` module contains guest-side logic that runs **inside** the VM.
+
+## Principle
+
+**Clean separation between host and guest.**
+
+The runtime module defines what runs inside VMs and how the host communicates with it.
+
+## Submodules
+
+### `runtime/agent/`
+The Go agent that runs inside each VM:
+- Receives requests from the control plane
+- Manages the Python runtime
+- Handles code execution
+- Streams logs and results
+
+### `runtime/python/`
+Python runtime bootstrap and management:
+- Python environment initialization
+- Handler loading and execution
+- Dependency management
+- Error handling
+
+### `runtime/protocol/`
+Host ↔ guest communication protocol:
+- Message definitions
+- Encoding/decoding
+- Version negotiation
+- Request/response contracts
+
+## Protocol is Key
+
+The protocol defines:
+- `Exec` - Execute code
+- `UploadFile` - Transfer files
+- `StreamLogs` - Stream execution logs
+- `Shutdown` - Graceful shutdown
+
+Once frozen, everything becomes composable.
+
+## Usage
+
+The runtime module is used by:
+- VM module to bootstrap guest environment
+- Control plane to execute functions
+- Sandbox module for interactive sessions
+
+## Status
+
+🚧 **Under Development** - Agent exists in `cmd/daemon/`, being formalized as a module.
+
+See [Issue #13-#19](../ISSUES.md) for tracking.
diff --git a/runtime/agent/README.md b/runtime/agent/README.md
new file mode 100644
index 0000000..6a4ee02
--- /dev/null
+++ b/runtime/agent/README.md
@@ -0,0 +1,47 @@
+# Runtime Agent
+
+The Go agent runs inside each Firecracker VM and handles communication with the host.
+
+## Responsibilities
+
+- **Request Handling**: Receive and process host requests
+- **Runtime Management**: Start and manage Python runtime
+- **Code Execution**: Execute function code
+- **Log Streaming**: Stream execution logs to host
+- **File Operations**: Handle file uploads/downloads
+- **Health Reporting**: Report VM health status
+
+## Key Features
+
+- Lightweight and fast
+- Single binary deployment
+- Minimal dependencies
+- Efficient communication via vsock or network
+
+## Current State
+
+The agent currently exists in `cmd/daemon/` and will be formalized as a reusable module.
+
+## Migration Status
+
+🚧 **To Be Formalized** from `cmd/daemon/`
+
+See [Issue #13](../../ISSUES.md#issue-13-create-runtimeagent-module) for details.
+
+## Future API
+
+```go
+// Start the agent
+agent := runtime.NewAgent(config)
+err := agent.Start(ctx)
+
+// Handle incoming request
+response, err := agent.HandleRequest(ctx, request)
+
+// Execute code
+result, err := agent.Execute(ctx, code, runtime)
+```
+
+## Deployment
+
+The agent binary is copied into the VM rootfs and started on boot.
diff --git a/runtime/protocol/README.md b/runtime/protocol/README.md
new file mode 100644
index 0000000..7cf5a46
--- /dev/null
+++ b/runtime/protocol/README.md
@@ -0,0 +1,118 @@
+# Runtime Protocol
+
+The protocol module defines the communication contract between host and guest.
+
+## Responsibilities
+
+- **Message Definitions**: Define all message types
+- **Encoding/Decoding**: Handle message serialization
+- **Version Negotiation**: Support protocol versioning
+- **Error Handling**: Standard error responses
+- **Documentation**: Protocol specification
+
+## Protocol Messages
+
+### Core Operations
+
+#### Exec
+Execute code in the VM.
+
+```
+Request:
+{
+  "type": "exec",
+  "runtime": "python3.8",
+  "code": "...",
+  "event": {...},
+  "timeout": 30
+}
+
+Response:
+{
+  "status": "success",
+  "result": {...},
+  "logs": "...",
+  "duration_ms": 150
+}
+```
+
+#### UploadFile
+Transfer file to VM.
+
+```
+Request:
+{
+  "type": "upload_file",
+  "path": "/tmp/data.txt",
+  "content": "base64...",
+  "permissions": "644"
+}
+
+Response:
+{
+  "status": "success",
+  "path": "/tmp/data.txt"
+}
+```
+
+#### StreamLogs
+Stream execution logs.
+
+```
+Request:
+{
+  "type": "stream_logs",
+  "follow": true
+}
+
+Response (streaming):
+{
+  "timestamp": "2024-01-15T10:30:00Z",
+  "level": "info",
+  "message": "..."
+}
+```
+
+#### Shutdown
+Graceful shutdown.
+
+```
+Request:
+{
+  "type": "shutdown",
+  "timeout": 10
+}
+
+Response:
+{
+  "status": "success"
+}
+```
+
+## Version Negotiation
+
+Protocol versions follow semantic versioning.
+
+```
+Handshake:
+{
+  "protocol_version": "1.0.0",
+  "capabilities": ["exec", "upload_file", "stream_logs"]
+}
+```
+
+## Migration Status
+
+🚧 **To Be Defined** - Protocol currently implicit, needs formalization
+
+See [Issue #15-#17](../../ISSUES.md) for details.
+
+## Future Structure
+
+```
+runtime/protocol/
+├── messages.go      # Message type definitions
+├── codec.go         # Encoding/decoding
+├── version.go       # Version negotiation
+└── PROTOCOL.md      # Protocol specification
+```
diff --git a/runtime/python/README.md b/runtime/python/README.md
new file mode 100644
index 0000000..2ccea12
--- /dev/null
+++ b/runtime/python/README.md
@@ -0,0 +1,50 @@
+# Runtime Python
+
+The Python runtime module handles Python execution inside VMs.
+
+## Responsibilities
+
+- **Environment Setup**: Initialize Python environment
+- **Handler Loading**: Load and validate handler functions
+- **Dependency Management**: Install and manage dependencies
+- **Execution**: Execute handler with event and context
+- **Error Handling**: Capture and format errors
+- **Output Capture**: Capture stdout/stderr
+
+## Key Features
+
+- AWS Lambda-compatible handler format
+- Support for requirements.txt
+- Isolated execution environment
+- Comprehensive error reporting
+
+## Handler Format
+
+```python
+def handler(event, context):
+    # Your code here
+    return response
+```
+
+## Migration Status
+
+🚧 **To Be Extracted** - Python runtime logic currently embedded in various places
+
+See [Issue #14](../../ISSUES.md#issue-14-create-runtimepython-module) for details.
+
+## Future Structure
+
+```
+runtime/python/
+├── bootstrap.py    # VM boot initialization
+├── handler.py      # Handler loading and execution
+├── context.py      # Context object
+└── requirements.py # Dependency management
+```
+
+## Execution Flow
+
+1. Bootstrap: Initialize Python on VM boot
+2. Load: Load handler function from uploaded code
+3. Execute: Call handler(event, context)
+4. Return: Stream result back to host
diff --git a/sandbox/README.md b/sandbox/README.md
new file mode 100644
index 0000000..53f93c7
--- /dev/null
+++ b/sandbox/README.md
@@ -0,0 +1,93 @@
+# Sandbox Module
+
+The `sandbox/` module provides E2B-style long-lived sandbox functionality.
+
+## Principle
+
+**A sandbox is just a long-lived VM + relaxed execution semantics.**
+
+Same VM manager, different policy. No need to touch Lambda logic.
+
+## What is a Sandbox?
+
+A sandbox is a persistent, interactive execution environment that:
+- Lives longer than a single function invocation
+- Supports multiple executions in sequence
+- Maintains state between executions
+- Allows file uploads and downloads
+- Can be suspended and resumed
+
+## Submodules
+
+### `sandbox/api/`
+REST API handlers for sandbox operations:
+- Create sandbox
+- Execute code
+- Upload/download files
+- List sandboxes
+- Delete sandbox
+
+### `sandbox/lifecycle/`
+Sandbox lifecycle management:
+- Create: Provision a new sandbox
+- Suspend: Pause sandbox and save state
+- Resume: Restore suspended sandbox
+- Destroy: Clean up sandbox resources
+
+### `sandbox/exec/`
+Code execution in sandboxes:
+- Shell command execution
+- Python code execution
+- Output streaming
+- Timeout handling
+
+### `sandbox/fs/`
+Filesystem operations:
+- File upload
+- File download
+- Directory operations
+- Quota management
+
+## Use Cases
+
+1. **Interactive Development**: REPL-like environments
+2. **Notebook Workflows**: Jupyter-style execution
+3. **CI/CD**: Isolated build environments
+4. **ML Training**: Long-running training jobs
+5. **Dev Environments**: Cloud-based development
+
+## Comparison: Lambda vs Sandbox
+
+| Feature | Lambda | Sandbox |
+|---------|--------|---------|
+| Lifetime | Single invocation | Persistent |
+| State | Stateless | Stateful |
+| Execution | One function call | Multiple executions |
+| Files | Read-only code | Read/write workspace |
+| Use Case | Event processing | Interactive work |
+
+## Status
+
+🚧 **New Feature** - To be implemented behind feature flag
+
+See [Issue #27-#35](../ISSUES.md) for tracking.
+
+## Example Usage
+
+```python
+# Create sandbox
+sandbox = client.sandboxes.create()
+
+# Execute code
+result = sandbox.exec("pip install requests")
+result = sandbox.exec("python train.py")
+
+# Upload files
+sandbox.upload_file("data.csv", content)
+
+# Download results
+results = sandbox.download_file("output.txt")
+
+# Clean up
+sandbox.destroy()
+```
diff --git a/sandbox/api/README.md b/sandbox/api/README.md
new file mode 100644
index 0000000..010b91e
--- /dev/null
+++ b/sandbox/api/README.md
@@ -0,0 +1,117 @@
+# Sandbox API
+
+REST API handlers for sandbox operations.
+
+## Responsibilities
+
+- **Request Handling**: Handle HTTP requests for sandbox operations
+- **Validation**: Validate request parameters
+- **Error Handling**: Return appropriate error responses
+- **Authentication**: Verify API keys
+- **Documentation**: OpenAPI/Swagger specs
+
+## Endpoints
+
+### POST /sandboxes
+Create a new sandbox.
+
+```
+Request:
+{
+  "runtime": "python3.8",
+  "memory_mb": 512,
+  "cpu_count": 1,
+  "timeout_seconds": 3600
+}
+
+Response:
+{
+  "id": "sb_abc123",
+  "status": "ready",
+  "ip": "172.16.0.5",
+  "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+### POST /sandboxes/{id}/exec
+Execute code in sandbox.
+
+```
+Request:
+{
+  "language": "python",
+  "code": "print('hello')",
+  "timeout": 30
+}
+
+Response:
+{
+  "status": "success",
+  "stdout": "hello\n",
+  "stderr": "",
+  "exit_code": 0,
+  "duration_ms": 50
+}
+```
+
+### POST /sandboxes/{id}/files
+Upload file to sandbox.
+
+```
+Request:
+{
+  "path": "/workspace/data.txt",
+  "content": "base64...",
+  "permissions": "644"
+}
+
+Response:
+{
+  "path": "/workspace/data.txt",
+  "size": 1024
+}
+```
+
+### GET /sandboxes/{id}/files/{path}
+Download file from sandbox.
+
+```
+Response:
+{
+  "path": "/workspace/output.txt",
+  "content": "base64...",
+  "size": 2048
+}
+```
+
+### GET /sandboxes
+List sandboxes.
+
+```
+Response:
+{
+  "sandboxes": [
+    {
+      "id": "sb_abc123",
+      "status": "ready",
+      "created_at": "..."
+    }
+  ]
+}
+```
+
+### DELETE /sandboxes/{id}
+Destroy sandbox.
+
+```
+Response:
+{
+  "status": "deleted"
+}
+```
+
+## Migration Status
+
+🚧 **New Module** - To be implemented
+
+See [Issue #28](../../ISSUES.md#issue-28-create-sandboxapi-module) for details.
diff --git a/sandbox/exec/README.md b/sandbox/exec/README.md
new file mode 100644
index 0000000..2bc3786
--- /dev/null
+++ b/sandbox/exec/README.md
@@ -0,0 +1,88 @@
+# Sandbox Exec
+
+Code execution in sandboxes supporting shell and Python.
+
+## Responsibilities
+
+- **Shell Execution**: Execute shell commands
+- **Python Execution**: Execute Python code
+- **Output Streaming**: Stream stdout/stderr
+- **Timeout Handling**: Enforce execution timeouts
+- **Environment**: Manage execution environment
+
+## Execution Types
+
+### Shell Execution
+Execute arbitrary shell commands.
+
+```go
+result, err := exec.Shell(ctx, sandboxID, "ls -la /workspace")
+```
+
+Features:
+- Full shell access
+- Environment variables
+- Working directory control
+- Signal handling
+
+### Python Execution
+Execute Python code or scripts.
+
+```go
+result, err := exec.Python(ctx, sandboxID, "print('hello')")
+```
+
+Features:
+- Import installed packages
+- Persistent state (globals)
+- Exception handling
+- Output capture
+
+## Output Streaming
+
+Real-time output streaming for long-running commands:
+
+```go
+stream, err := exec.StreamShell(ctx, sandboxID, "python train.py")
+for {
+    line, err := stream.ReadLine()
+    if err == io.EOF {
+        break
+    }
+    fmt.Println(line)
+}
+```
+
+## Timeout Handling
+
+Executions are subject to timeouts:
+- Default timeout: 30 seconds
+- Maximum timeout: 1 hour
+- Configurable per request
+
+## Environment Management
+
+Control execution environment:
+- Working directory
+- Environment variables
+- PATH configuration
+- Resource limits
+
+## Migration Status
+
+🚧 **New Module** - To be implemented
+
+See [Issue #30](../../ISSUES.md#issue-30-create-sandboxexec-module) for details.
+
+## Future API
+
+```go
+// Execute shell command
+result, err := exec.Shell(ctx, sandboxID, command, options)
+
+// Execute Python code
+result, err := exec.Python(ctx, sandboxID, code, options)
+
+// Stream output
+stream, err := exec.Stream(ctx, sandboxID, command)
+```
diff --git a/sandbox/fs/README.md b/sandbox/fs/README.md
new file mode 100644
index 0000000..9e04025
--- /dev/null
+++ b/sandbox/fs/README.md
@@ -0,0 +1,114 @@
+# Sandbox Filesystem
+
+Filesystem operations for sandboxes including file upload/download.
+
+## Responsibilities
+
+- **File Upload**: Upload files to sandbox
+- **File Download**: Download files from sandbox
+- **Directory Operations**: Create, list, delete directories
+- **Quota Management**: Enforce storage quotas
+- **Permissions**: Manage file permissions
+
+## Operations
+
+### Upload File
+Upload file to sandbox workspace.
+
+```go
+err := fs.UploadFile(ctx, sandboxID, path, content, permissions)
+```
+
+Features:
+- Base64 encoded content
+- Automatic directory creation
+- Permission control
+- Size validation
+
+### Download File
+Download file from sandbox.
+
+```go
+content, err := fs.DownloadFile(ctx, sandboxID, path)
+```
+
+Features:
+- Base64 encoded content
+- Streaming for large files
+- Path validation
+- Access control
+
+### List Directory
+List files in directory.
+
+```go
+entries, err := fs.ListDirectory(ctx, sandboxID, path)
+```
+
+Returns:
+- File names
+- File sizes
+- Permissions
+- Modification times
+
+### Create Directory
+Create directory in sandbox.
+
+```go
+err := fs.CreateDirectory(ctx, sandboxID, path, permissions)
+```
+
+### Delete Path
+Delete file or directory.
+
+```go
+err := fs.Delete(ctx, sandboxID, path, recursive)
+```
+
+## Workspace
+
+Each sandbox has a workspace directory:
+- Default: `/workspace`
+- Persistent across executions
+- Subject to quota limits
+- Isolated from other sandboxes
+
+## Quota Management
+
+Storage quotas per sandbox:
+- Default: 1 GB
+- Maximum: 10 GB
+- Configurable per sandbox
+- Enforced on upload
+
+## Security
+
+- Path validation to prevent escaping workspace
+- Permission enforcement
+- Size limits
+- Type restrictions
+
+## Migration Status
+
+🚧 **New Module** - To be implemented
+
+See [Issue #31](../../ISSUES.md#issue-31-create-sandboxfs-module) for details.
+
+## Future API
+
+```go
+// Upload file
+err := fs.UploadFile(ctx, sandboxID, path, content, options)
+
+// Download file
+content, err := fs.DownloadFile(ctx, sandboxID, path)
+
+// List directory
+entries, err := fs.ListDirectory(ctx, sandboxID, path)
+
+// Create directory
+err := fs.CreateDirectory(ctx, sandboxID, path, permissions)
+
+// Delete
+err := fs.Delete(ctx, sandboxID, path, recursive)
+```
diff --git a/sandbox/lifecycle/README.md b/sandbox/lifecycle/README.md
new file mode 100644
index 0000000..60ea673
--- /dev/null
+++ b/sandbox/lifecycle/README.md
@@ -0,0 +1,91 @@
+# Sandbox Lifecycle
+
+Sandbox lifecycle management for create, suspend, resume, and destroy operations.
+
+## Responsibilities
+
+- **Creation**: Provision new sandboxes from VMs
+- **Suspension**: Pause sandbox and save state
+- **Resumption**: Restore suspended sandbox
+- **Destruction**: Clean up sandbox resources
+- **State Tracking**: Track sandbox lifecycle state
+
+## Lifecycle States
+
+```
+        create
+   ┌──────────────┐
+   │              ▼
+   │         ┌─────────┐
+   │         │ READY   │◄─┐
+   │         └─────────┘  │
+   │              │       │
+   │         exec │       │ resume
+   │              ▼       │
+   │         ┌─────────┐  │
+   │         │ BUSY    │──┘
+   │         └─────────┘
+   │              │
+   │      suspend │
+   │              ▼
+   │         ┌──────────┐
+   │         │SUSPENDED │
+   │         └──────────┘
+   │              │
+   └──────────────┼──────────┐
+              destroy        │
+                  ▼          │
+              ┌─────────┐    │
+              │DESTROYED│◄───┘
+              └─────────┘
+```
+
+## Operations
+
+### Create
+1. Acquire VM from pool or create new
+2. Initialize sandbox workspace
+3. Set up filesystem
+4. Register in state manager
+5. Return sandbox ID
+
+### Suspend
+1. Save VM state to snapshot
+2. Stop VM
+3. Update state to SUSPENDED
+4. Free resources
+
+### Resume
+1. Restore VM from snapshot
+2. Restore workspace
+3. Update state to READY
+4. Return connection info
+
+### Destroy
+1. Stop VM if running
+2. Clean up workspace
+3. Delete snapshots
+4. Remove from state manager
+5. Free resources
+
+## Migration Status
+
+🚧 **New Module** - To be implemented
+
+See [Issue #29](../../ISSUES.md#issue-29-create-sandboxlifecycle-module) for details.
+
+## Future API
+
+```go
+// Create new sandbox
+sandbox, err := lifecycle.Create(ctx, config)
+
+// Suspend sandbox
+err := lifecycle.Suspend(ctx, sandboxID)
+
+// Resume sandbox
+sandbox, err := lifecycle.Resume(ctx, sandboxID)
+
+// Destroy sandbox
+err := lifecycle.Destroy(ctx, sandboxID)
+```
diff --git a/sdk/README.md b/sdk/README.md
new file mode 100644
index 0000000..e109c49
--- /dev/null
+++ b/sdk/README.md
@@ -0,0 +1,106 @@
+# SDK Module
+
+Client-facing SDKs for interacting with Skyscale.
+
+## Principle
+
+**SDK-first development: Design the developer experience before the API.**
+
+The SDK provides both Lambda-style and Sandbox-style interfaces using the same backend.
+
+## Submodules
+
+### `sdk/python/`
+Python SDK for Skyscale:
+- Lambda-style function invocation
+- Sandbox-style interactive execution
+- File operations
+- Authentication
+- Error handling
+
+### `sdk/types/`
+Shared type definitions:
+- Request/response types
+- Configuration types
+- Error types
+- Common utilities
+
+## Dual API Design
+
+### Lambda-Style
+
+For stateless function execution:
+
+```python
+from skyscale import SkyscaleClient
+
+client = SkyscaleClient(api_key="...")
+
+# Invoke function
+result = client.functions.invoke(
+    name="my-function",
+    payload={"key": "value"}
+)
+```
+
+### Sandbox-Style
+
+For interactive, stateful execution:
+
+```python
+from skyscale import SkyscaleClient
+
+client = SkyscaleClient(api_key="...")
+
+# Create sandbox
+sandbox = client.sandboxes.create(
+    runtime="python3.8",
+    memory_mb=512
+)
+
+# Execute code
+result = sandbox.exec("pip install requests")
+result = sandbox.exec("python train.py")
+
+# Upload files
+sandbox.upload_file("data.csv", content)
+
+# Download results
+output = sandbox.download_file("output.txt")
+
+# Clean up
+sandbox.destroy()
+```
+
+## Key Features
+
+- **Simple API**: Pythonic, intuitive interface
+- **Type Hints**: Full type annotations
+- **Async Support**: Asyncio-compatible
+- **Error Handling**: Clear, actionable errors
+- **Documentation**: Comprehensive docs and examples
+
+## Status
+
+🚧 **Under Development** - To be implemented
+
+See [Issue #36-#43](../ISSUES.md) for tracking.
+
+## Installation
+
+```bash
+pip install skyscale
+```
+
+## Authentication
+
+```python
+# From environment variable
+client = SkyscaleClient()  # uses SKYSCALE_API_KEY
+
+# Explicit API key
+client = SkyscaleClient(api_key="sk_...")
+
+# From config file
+client = SkyscaleClient.from_config("~/.skyscale/config")
+```
diff --git a/sdk/python/README.md b/sdk/python/README.md
new file mode 100644
index 0000000..33554ba
--- /dev/null
+++ b/sdk/python/README.md
@@ -0,0 +1,205 @@
+# Skyscale Python SDK
+
+Official Python SDK for Skyscale.
+
+## Installation
+
+```bash
+pip install skyscale
+```
+
+## Quick Start
+
+### Lambda-Style Functions
+
+```python
+from skyscale import SkyscaleClient
+
+client = SkyscaleClient(api_key="sk_...")
+
+# Invoke function
+result = client.functions.invoke("my-function", {"key": "value"})
+print(result)
+```
+
+### Sandbox-Style Execution
+
+```python
+from skyscale import SkyscaleClient
+
+client = SkyscaleClient(api_key="sk_...")
+
+# Create and use sandbox
+with client.sandboxes.create() as sandbox:
+    # Install dependencies
+    sandbox.exec("pip install pandas numpy")
+    
+    # Upload data
+    sandbox.upload_file("data.csv", open("local_data.csv", "rb"))
+    
+    # Run analysis
+    result = sandbox.exec("python analyze.py")
+    print(result.stdout)
+    
+    # Download results
+    output = sandbox.download_file("results.json")
+```
+
+## API Reference
+
+### Client
+
+```python
+class SkyscaleClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.skyscale.io",
+        timeout: int = 30
+    )
+```
+
+### Functions API
+
+```python
+# Invoke function
+result = client.functions.invoke(
+    name: str,
+    payload: Dict[str, Any],
+    sync: bool = True,
+    timeout: int = 30
+) -> Dict[str, Any]
+
+# List functions
+functions = client.functions.list() -> List[Function]
+
+# Get function
+function = client.functions.get(name: str) -> Function
+
+# Create function
+function = client.functions.create(
+    name: str,
+    runtime: str,
+    handler: str,
+    code: bytes
+) -> Function
+```
+
+### Sandboxes API
+
+```python
+# Create sandbox
+sandbox = client.sandboxes.create(
+    runtime: str = "python3.8",
+    memory_mb: int = 512,
+    cpu_count: int = 1,
+    timeout_seconds: int = 3600
+) -> Sandbox
+
+# List sandboxes
+sandboxes = client.sandboxes.list() -> List[Sandbox]
+
+# Get sandbox
+sandbox = client.sandboxes.get(id: str) -> Sandbox
+```
+
+### Sandbox Operations
+
+```python
+# Execute code
+result = sandbox.exec(
+    code: str,
+    language: str = "python",
+    timeout: int = 30
+) -> ExecResult
+
+# Execute shell command
+result = sandbox.shell(
+    command: str,
+    timeout: int = 30
+) -> ExecResult
+
+# Upload file
+sandbox.upload_file(
+    path: str,
+    content: Union[str, bytes, BinaryIO],
+    permissions: str = "644"
+)
+
+# Download file
+content = sandbox.download_file(path: str) -> bytes
+
+# List files
+files = sandbox.list_files(path: str = "/workspace") -> List[FileInfo]
+
+# Destroy sandbox
+sandbox.destroy()
+```
+
+## Error Handling
+
+```python
+from skyscale import SkyscaleError, TimeoutError, AuthenticationError
+
+try:
+    result = client.functions.invoke("my-function", {...})
+except TimeoutError:
+    print("Function execution timed out")
+except AuthenticationError:
+    print("Invalid API key")
+except SkyscaleError as e:
+    print(f"Error: {e}")
+```
+
+## Async Support
+
+```python
+from skyscale import AsyncSkyscaleClient
+
+async def main():
+    client = AsyncSkyscaleClient(api_key="sk_...")
+    
+    # Async invocation
+    result = await client.functions.invoke("my-function", {...})
+    
+    # Async sandbox
+    async with client.sandboxes.create() as sandbox:
+        result = await sandbox.exec("print('hello')")
+```
+
+## Configuration
+
+```python
+# From environment
+client = SkyscaleClient()  # uses SKYSCALE_API_KEY
+
+# From config file (~/.skyscale/config.json)
+{
+    "api_key": "sk_...",
+    "base_url": "https://api.skyscale.io"
+}
+
+client = SkyscaleClient.from_config()
+```
+
+## Migration Status
+
+🚧 **To Be Implemented**
+
+See [Issue #37-#40](../../ISSUES.md) for details.
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Type checking
+mypy skyscale
+
+# Linting
+flake8 skyscale
+```
diff --git a/sdk/types/README.md b/sdk/types/README.md
new file mode 100644
index 0000000..098b81b
--- /dev/null
+++ b/sdk/types/README.md
@@ -0,0 +1,75 @@
+# SDK Types
+
+Shared type definitions for SDKs.
+
+## Purpose
+
+Common types used across SDK implementations to ensure consistency.
+
+## Type Categories
+
+### Request Types
+- Function invocation requests
+- Sandbox creation requests
+- File operation requests
+
+### Response Types
+- Function invocation results
+- Sandbox information
+- Execution results
+- File metadata
+
+### Configuration Types
+- Client configuration
+- Timeout settings
+- Resource limits
+
+### Error Types
+- Error codes
+- Error messages
+- Error categories
+
+## Migration Status
+
+🚧 **To Be Implemented**
+
+See [Issue #37](../../ISSUES.md#issue-37-create-sdkpython-module) for details.
+
+## Future Structure
+
+```
+sdk/types/
+├── requests.go      # Request type definitions
+├── responses.go     # Response type definitions
+├── errors.go        # Error types
+└── config.go        # Configuration types
+```
+
+## Example Types
+
+```go
+// FunctionInvokeRequest
+type FunctionInvokeRequest struct {
+    Name    string                 `json:"name"`
+    Payload map[string]interface{} `json:"payload"`
+    Sync    bool                   `json:"sync"`
+    Timeout int                    `json:"timeout"`
+}
+
+// SandboxCreateRequest
+type SandboxCreateRequest struct {
+    Runtime        string `json:"runtime"`
+    MemoryMB       int    `json:"memory_mb"`
+    CPUCount       int    `json:"cpu_count"`
+    TimeoutSeconds int    `json:"timeout_seconds"`
+}
+
+// ExecResult
+type ExecResult struct {
+    Status     string `json:"status"`
+    Stdout     string `json:"stdout"`
+    Stderr     string `json:"stderr"`
+    ExitCode   int    `json:"exit_code"`
+    DurationMs int    `json:"duration_ms"`
+}
+```
diff --git a/vm/README.md b/vm/README.md
new file mode 100644
index 0000000..2214370
--- /dev/null
+++ b/vm/README.md
@@ -0,0 +1,59 @@
+# VM Module
+
+The `vm/` module is the **sacred ground** for all Firecracker-related operations. This module provides the single source of truth for VM lifecycle management.
+
+## Principle
+
+**Nothing outside `vm/` talks to Firecracker directly.**
+
+This isolation enables Lambda execution, sandboxes, REPLs, and tests to all reuse the same VM machinery with different policies.
+
+## Submodules
+
+### `vm/manager/`
+Core VM lifecycle management:
+- Starting and stopping microVMs
+- VM instance tracking
+- Resource allocation
+- VM configuration
+
+### `vm/pool/`
+Pre-warmed VM pool management:
+- Maintaining pool of ready VMs
+- Pool size management
+- VM reuse strategies
+- Cold start optimization
+
+### `vm/snapshot/`
+VM snapshot operations:
+- Creating VM snapshots
+- Restoring from snapshots
+- Snapshot metadata management
+- Fast VM initialization
+
+### `vm/network/`
+Network configuration and management:
+- TAP device setup
+- Bridge configuration
+- IP allocation
+- vsock communication
+
+### `vm/jailer/`
+Security isolation and containment:
+- Seccomp configuration
+- UID isolation
+- Chroot setup
+- Resource limits
+
+## Usage
+
+The VM module is used by:
+- Control plane for Lambda-style execution
+- Sandbox module for long-lived sessions
+- Testing framework for isolated tests
+
+## Status
+
+🚧 **Under Development** - This module is being extracted from `control-plane/vm/` as part of the restructuring effort.
+
+See [Issue #5-#12](../ISSUES.md) for tracking.
diff --git a/vm/jailer/README.md b/vm/jailer/README.md
new file mode 100644
index 0000000..bda8b83
--- /dev/null
+++ b/vm/jailer/README.md
@@ -0,0 +1,41 @@
+# VM Jailer
+
+The VM Jailer module handles security isolation for Firecracker VMs.
+
+## Responsibilities
+
+- **Seccomp**: Configure seccomp filters
+- **UID Isolation**: Set up user namespace isolation
+- **Chroot**: Configure chroot jails
+- **Resource Limits**: Apply cgroup limits
+- **Security Policies**: Enforce security policies
+
+## Key Concepts
+
+### Jailer
+Firecracker's built-in security wrapper that sets up isolation.
+
+### Defense in Depth
+Multiple layers of isolation for maximum security.
+
+### Resource Constraints
+CPU, memory, and I/O limits per VM.
+
+## Migration Status
+
+🚧 **New Module** - To be implemented
+
+See [Issue #9](../../ISSUES.md#issue-9-create-vmjailer-module) for details.
+
+## Future API
+
+```go
+// Configure jailer for VM
+jailerConfig, err := jailer.Configure(ctx, vmID, securityPolicy)
+
+// Apply resource limits
+err := jailer.SetLimits(ctx, vmID, limits)
+
+// Get jailer status
+status, err := jailer.GetStatus(ctx, vmID)
+```
diff --git a/vm/manager/README.md b/vm/manager/README.md
new file mode 100644
index 0000000..7935724
--- /dev/null
+++ b/vm/manager/README.md
@@ -0,0 +1,36 @@
+# VM Manager
+
+The VM Manager handles the core lifecycle of Firecracker microVMs.
+
+## Responsibilities
+
+- **VM Creation**: Initialize and start new Firecracker VMs
+- **VM Termination**: Stop and clean up VMs
+- **Resource Management**: Track CPU, memory, and other resources
+- **Configuration**: Apply VM configurations (kernel, rootfs, network, etc.)
+- **State Tracking**: Monitor VM status and health
+
+## Key Types
+
+- `VMManager`: Main manager coordinating VM operations
+- `VMInstance`: Represents a running VM
+- `VMConfig`: Configuration for VM creation
+
+## Migration Status
+
+🚧 **To Be Migrated** from `control-plane/vm/`
+
+See [Issue #5](../../ISSUES.md#issue-5-create-vmmanager-module) for details.
+
+## Future API
+
+```go
+// Create a new VM with configuration
+vm, err := manager.Create(ctx, config)
+
+// Stop and clean up a VM
+err := manager.Terminate(ctx, vmID)
+
+// Get VM status
+status, err := manager.GetStatus(ctx, vmID)
+```
diff --git a/vm/network/README.md b/vm/network/README.md
new file mode 100644
index 0000000..ae5a542
--- /dev/null
+++ b/vm/network/README.md
@@ -0,0 +1,41 @@
+# VM Network
+
+The VM Network module handles network configuration for Firecracker VMs.
+
+## Responsibilities
+
+- **TAP Devices**: Create and configure TAP devices
+- **Bridge Setup**: Configure network bridges
+- **IP Allocation**: Assign and manage IP addresses
+- **vsock**: Configure vsock for host-guest communication
+- **Network Isolation**: Ensure network isolation between VMs
+
+## Key Concepts
+
+### TAP Devices
+Virtual network interfaces attached to VMs.
+
+### CNI Integration
+Integration with Container Network Interface for advanced networking.
+
+### vsock
+Virtual socket for efficient host-guest communication.
+
+## Migration Status
+
+🚧 **To Be Extracted** from `vm/manager/`
+
+See [Issue #8](../../ISSUES.md#issue-8-create-vmnetwork-module) for details.
+
+## Future API
+
+```go
+// Configure network for VM
+netConfig, err := network.Configure(ctx, vmID, options)
+
+// Allocate IP address
+ip, err := network.AllocateIP(ctx)
+
+// Setup vsock
+vsockConfig, err := network.SetupVsock(ctx, vmID)
+```
diff --git a/vm/pool/README.md b/vm/pool/README.md
new file mode 100644
index 0000000..799377f
--- /dev/null
+++ b/vm/pool/README.md
@@ -0,0 +1,41 @@
+# VM Pool
+
+The VM Pool maintains a collection of pre-warmed VMs to minimize cold start times.
+
+## Responsibilities
+
+- **Pool Maintenance**: Keep pool at target size
+- **VM Acquisition**: Provide VMs on demand from pool
+- **VM Return**: Accept VMs back into pool for reuse
+- **Health Checking**: Remove unhealthy VMs from pool
+- **Metrics**: Track pool usage and efficiency
+
+## Key Concepts
+
+### Pre-warmed VMs
+VMs that are already booted and initialized, ready to accept workloads immediately.
+
+### Pool Sizing
+Dynamic or fixed pool sizes based on workload patterns.
+
+### Eviction Policy
+Strategy for removing VMs from pool (FIFO, LRU, health-based).
+
+## Migration Status
+
+🚧 **To Be Extracted** from `vm/manager/`
+
+See [Issue #6](../../ISSUES.md#issue-6-create-vmpool-module) for details.
+
+## Future API
+
+```go
+// Get a VM from the pool
+vm, err := pool.Acquire(ctx)
+
+// Return a VM to the pool
+err := pool.Release(ctx, vm)
+
+// Get pool statistics
+stats := pool.Stats()
+```
diff --git a/vm/snapshot/README.md b/vm/snapshot/README.md
new file mode 100644
index 0000000..8917132
--- /dev/null
+++ b/vm/snapshot/README.md
@@ -0,0 +1,47 @@
+# VM Snapshot
+
+The VM Snapshot module handles creating and restoring VM snapshots for fast initialization.
+
+## Responsibilities
+
+- **Snapshot Creation**: Create memory and disk snapshots
+- **Snapshot Restoration**: Restore VMs from snapshots
+- **Metadata Management**: Track snapshot metadata
+- **Storage**: Manage snapshot storage locations
+- **Layering**: Support snapshot layering for efficiency
+
+## Key Concepts
+
+### Full Snapshots
+Complete VM state including memory and disk.
+
+### Incremental Snapshots
+Only changes since last snapshot (future).
+
+### Snapshot Layering
+Base snapshot + deltas for different configurations.
+
+## Use Cases
+
+1. **Fast Cold Starts**: Pre-initialized Python runtime
+2. **Different Configurations**: Base + function-specific layers
+3. **Version Management**: Snapshot different runtime versions
+
+## Migration Status
+
+🚧 **New Module** - To be implemented
+
+See [Issue #7](../../ISSUES.md#issue-7-create-vmsnapshot-module) for details.
+
+## Future API
+
+```go
+// Create a snapshot from running VM
+snapshot, err := snapshotMgr.Create(ctx, vmID, metadata)
+
+// Restore VM from snapshot
+vm, err := snapshotMgr.Restore(ctx, snapshotID)
+
+// List available snapshots
+snapshots, err := snapshotMgr.List(ctx)
+```