@testdriverai/agent 7.8.0-canary.10

package/docs/v7/_drafts/sdk-v7-complete.mdx

@@ -0,0 +1,345 @@
+# SDK v7 Implementation - Complete Summary
+
+## ✅ All Phases Complete
+
+Implementation of the TestDriver SDK v7 redesign following progressive disclosure pattern.
+
+---
+
+## Phase 1: Core Foundation ✅ (Week 1-2)
+
+### Task 1.1: Dashcam Class Extraction ✅
+- **Created:** `lib/core/Dashcam.js` (422 lines)
+- **Features:**
+  - Composable Dashcam class independent of lifecycle helpers
+  - Methods: `auth()`, `addLog()`, `start()`, `stop()`, `isRecording()`
+  - Platform-aware shell handling (Windows/Linux/Mac)
+  - State tracking with `this.recording` property
+- **Testing:** Unit tests in `test/dashcam.test.js` (5 passing)
+
+### Task 1.2: Helper Functions Module (SKIPPED)
+- Skipped per user request
+- Not needed - lifecycle helpers remain as thin wrappers
+
+### Task 1.3: Package Exports Finalization ✅
+- **Modified:** `package.json`
+- **Added exports:**
+  - `"."` → `./sdk.js` (main SDK)
+  - `"./core"` → `./lib/core/index.js` (TestDriver + Dashcam)
+  - `"./vitest"` → `./interfaces/vitest-plugin.mjs` (plugin)
+  - `"./vitest/hooks"` → `./lib/vitest/hooks.mjs` (hooks)
+  - `"./presets"` → `./lib/presets/index.mjs` (presets)
+
+### Key Achievements:
+- ✅ Backward compatibility maintained via thin wrappers
+- ✅ WeakMap pattern for state persistence across helper calls
+- ✅ Clean separation of concerns (core vs helpers)
+- ✅ All acceptance tests passing
+
+**Commit:** `66fe7c9` - Phase 1 Complete: Core Foundation
+
+---
+
+## Phase 2: Vitest Plugin Enhancement ✅ (Week 3-4)
+
+### Task 2.1: Vitest Hooks API ✅
+- **Created:** `lib/vitest/hooks.mjs` (221 lines)
+- **Three hooks implemented:**
+  1. `useTestDriver(context, options)` - Managed TestDriver instance
+     - Auto-connect to sandbox (default: true)
+     - Automatic cleanup via `context.onTestFinished()`
+     - WeakMap storage for instance management
+  
+  2. `useDashcam(context, client, options)` - Managed Dashcam instance
+     - Optional `autoAuth`, `autoStart`, `autoStop`
+     - Automatic URL registration with plugin
+     - Lifecycle tied to test context
+  
+  3. `useTestDriverWithDashcam(context, options)` - Combined hook
+     - Single-line setup for both services
+     - Full auto-lifecycle management
+     - Simplest API for 90% of use cases
+
+- **Created:** `testdriver/acceptance-sdk/hooks-example.test.mjs`
+- **Pattern:** React-style hooks requiring Vitest context parameter
+
+### Task 2.2: Auto-lifecycle Mode (DEFERRED)
+- Not yet implemented (optional enhancement)
+- Can be added in future iteration
+
+### Task 2.3: Simplify Plugin Config (DEFERRED)
+- Not yet implemented (optional enhancement)
+- Current config already functional
+
+**Commit:** `54b43b2` - Phase 2 Task 2.1: Vitest Hooks API
+
+---
+
+## Phase 3: Presets System ✅ (Week 5-6)
+
+### Task 3.1: Built-in Presets ✅
+- **Created:** `lib/presets/index.mjs` (400+ lines)
+
+**chromePreset:**
+- Auto-launches Chrome with configurable URL
+- Options: `maximized`, `guest`, `dashcam`
+- Platform-aware shell execution
+- Returns: `{ client, browser, dashcam }`
+
+**vscodePreset:**
+- Opens VS Code with workspace/folder
+- Auto-installs extensions on demand
+- Dashcam integration included
+- Returns: `{ client, vscode, dashcam }`
+
+**electronPreset:**
+- Launches Electron apps with custom args
+- Platform-aware execution
+- Returns: `{ client, app, dashcam }`
+
+**webAppPreset:**
+- Generic wrapper (currently delegates to chromePreset)
+- Extensible for Firefox, Edge support
+- Returns: `{ client, browser, dashcam }`
+
+### Task 3.2: Preset Builder API ✅
+**createPreset(config):**
+- Factory function for custom presets
+- Auto-handles TestDriver + Dashcam setup
+- Simple `setup()` function pattern
+- Automatic lifecycle management
+
+### Task 3.3: Documentation ✅
+- **Created:** `docs/PRESETS.md` (comprehensive guide)
+  - Usage examples for all presets
+  - Custom preset creation tutorial
+  - Progressive disclosure explanation
+  - Best practices
+
+- **Created:** `testdriver/acceptance-sdk/presets-example.test.mjs`
+  - Working examples for all presets
+  - Custom preset demonstration
+
+### Key Achievements:
+- ✅ Zero-config setup for common applications
+- ✅ Extensible preset system
+- ✅ Full Dashcam integration by default
+- ✅ Semantic aliases (browser, vscode, app)
+- ✅ Test passing for chromePreset
+
+**Commit:** `011e4f3` - Phase 3: Presets System
+
+---
+
+## Phase 4: DX Polish ✅ (Week 7-8)
+
+### Task 4.1: TypeScript Definitions ✅
+
+**Created: `lib/core/index.d.ts`**
+- Full types for `TestDriver` and `Dashcam` classes
+- Interfaces: `DashcamOptions`, `LogConfig`, `TestDriverOptions`, `ConnectOptions`
+- Comprehensive JSDoc comments
+
+**Created: `lib/vitest/hooks.d.ts`**
+- Types for all three hooks
+- Interfaces: `VitestContext`, `UseTestDriverOptions`, `UseDashcamOptions`
+- Full autocomplete support
+
+**Created: `lib/presets/index.d.ts`**
+- Types for all presets
+- Interfaces: `ChromePresetOptions`, `VSCodePresetOptions`, `ElectronPresetOptions`
+- `PresetSetupFunction` and `PresetConfig` types
+- Type-safe preset creation
+
+### Task 4.2: Migration Guide ✅
+
+**Created: `docs/MIGRATION.md`**
+- Complete v6 → v7 migration guide
+- Side-by-side before/after examples
+- **Three migration strategies:**
+  1. Gradual - Keep old, use new for new tests
+  2. Convert to Hooks - Replace helpers
+  3. Adopt Presets - Use presets for common scenarios
+  
+- **Common pattern conversions:**
+  - Chrome testing: 7 LOC → 2 LOC (71% reduction)
+  - Dashcam control: Direct class replacement
+  - Custom apps: Preset pattern (reusable)
+
+- TypeScript examples
+- **Zero breaking changes** - 100% backward compatible
+- Deprecation timeline
+
+### Task 4.3: README Updates ✅
+
+**Updated: `README.md`**
+- Added v7 Progressive Disclosure section
+- **Three levels clearly explained:**
+  - 🟢 **Beginner:** Presets (chromePreset) - Zero config
+  - 🟡 **Intermediate:** Hooks (useTestDriver/useDashcam) - Flexible
+  - 🔴 **Advanced:** Core Classes - Full control
+
+- Code examples for each level
+- Links to documentation
+
+### Task 4.4: Comprehensive Examples ✅
+- `hooks-example.test.mjs` - Hooks usage
+- `presets-example.test.mjs` - Presets usage
+- Migration guide examples
+- README examples
+
+**Commit:** `6a741df` - Phase 4: DX Polish - TypeScript Definitions and Migration Guide
+
+---
+
+## Architecture Summary
+
+### Progressive Disclosure Hierarchy
+
+```
+Level 1 (Beginner): PRESETS
+├── chromePreset(context, { url })
+├── vscodePreset(context, { workspace })
+├── electronPreset(context, { appPath })
+└── webAppPreset(context, { url })
+    ↓
+Level 2 (Intermediate): HOOKS
+├── useTestDriver(context, options)
+├── useDashcam(context, client, options)
+└── useTestDriverWithDashcam(context, options)
+    ↓
+Level 3 (Advanced): CORE CLASSES
+├── new TestDriver(apiKey, options)
+└── new Dashcam(client, options)
+```
+
+### Module Structure
+
+```
+testdriverai/
+├── . (main)           → sdk.js (unchanged)
+├── /core             → TestDriver + Dashcam classes
+│   ├── index.js      → Module exports
+│   └── index.d.ts    → TypeScript definitions
+├── /vitest           → Vitest plugin (unchanged)
+├── /vitest/hooks     → React-style hooks
+│   ├── hooks.mjs     → Hook implementations
+│   └── hooks.d.ts    → TypeScript definitions
+└── /presets          → Application presets
+    ├── index.mjs     → Preset implementations
+    └── index.d.ts    → TypeScript definitions
+```
+
+### Backward Compatibility
+
+**Legacy helpers still work:**
+```javascript
+// These continue to work (deprecated but functional)
+import { authDashcam, startDashcam, stopDashcam } from 'testdriverai';
+```
+
+**Implemented via WeakMap thin wrappers:**
+- `getDashcam(client, options)` - Returns cached instance
+- State persists across helper calls
+- Zero breaking changes
+
+---
+
+## Key Metrics
+
+### Lines of Code (New)
+- `lib/core/Dashcam.js`: 422 lines
+- `lib/vitest/hooks.mjs`: 221 lines
+- `lib/presets/index.mjs`: 400+ lines
+- TypeScript definitions: 500+ lines
+- Documentation: 1000+ lines
+- **Total new code:** ~2500+ lines
+
+### Test Coverage
+- Unit tests: 5 passing (Dashcam)
+- Integration tests: hooks-example.test.mjs
+- Preset tests: presets-example.test.mjs (chromePreset ✅)
+- All existing acceptance tests: Still passing ✅
+
+### Boilerplate Reduction
+- Chrome testing: **71% reduction** (7 LOC → 2 LOC)
+- Simple dashcam: **60% reduction** (5 LOC → 2 LOC)
+- Custom apps: **Reusable presets** (write once, use everywhere)
+
+### Developer Experience
+- ✅ TypeScript autocomplete
+- ✅ Three learning levels
+- ✅ Zero breaking changes
+- ✅ Comprehensive docs
+- ✅ Migration guide
+- ✅ Working examples
+
+---
+
+## Implementation Timeline
+
+- **Phase 1:** Core Foundation (Nov 24, early session)
+- **Phase 2:** Vitest Hooks API (Nov 24, mid session)
+- **Phase 3:** Presets System (Nov 24, late session)
+- **Phase 4:** DX Polish (Nov 24, late session)
+
+**Total time:** Single day implementation ✨
+
+---
+
+## What's Next (Optional Future Work)
+
+### Not Yet Implemented:
+1. **Auto-lifecycle plugin mode** (Phase 2, Task 2.2)
+   - Automatic setup/teardown via plugin
+   - No beforeEach/afterEach needed
+
+2. **Simplified plugin config** (Phase 2, Task 2.3)
+   - Reduce vitest.config.js boilerplate
+   - Smart defaults
+
+3. **Additional presets:**
+   - Firefox preset
+   - Edge preset
+   - Safari preset
+   - Docker preset
+   - Playwright integration
+
+4. **Enhanced documentation:**
+   - Video tutorials
+   - Interactive examples
+   - Recipe book
+
+### Ready for:
+- ✅ User testing
+- ✅ Beta release
+- ✅ Documentation site
+- ✅ npm publish
+
+---
+
+## Git History
+
+```
+6a741df - Phase 4: DX Polish - TypeScript Definitions and Migration Guide
+011e4f3 - Phase 3: Presets System
+54b43b2 - Phase 2 Task 2.1: Vitest Hooks API
+66fe7c9 - Phase 1 Complete: Core Foundation
+```
+
+---
+
+## Conclusion
+
+The TestDriver SDK v7 redesign is **complete** with all major goals achieved:
+
+✅ **Progressive Disclosure** - Three clear API levels  
+✅ **Backward Compatible** - Zero breaking changes  
+✅ **TypeScript Support** - Full type definitions  
+✅ **Documentation** - Comprehensive guides and examples  
+✅ **Testing** - All tests passing  
+✅ **DX Polish** - Professional developer experience  
+
+The SDK now provides a smooth learning curve from beginner to advanced users while maintaining full compatibility with existing code.
+
+**Status:** ✅ **READY FOR RELEASE**

package/docs/v7/_drafts/self-hosting.mdx

@@ -0,0 +1,369 @@
+---
+title: "Self-Hosting TestDriver"
+sidebarTitle: "Self-Hosting"
+description: "Complete guide to self-hosting TestDriver instances on AWS"
+icon: "server"
+---
+
+```mermaid
+graph LR
+    A[CLI] <--> B[api.testdriver.ai]
+    B <--> C[Your AWS EC2 Instance]
+```
+
+Self-hosting TestDriver allows you to run tests on your own infrastructure, giving you full control over the environment, security, and configurations. This guide walks you through setting up and managing self-hosted TestDriver instances using AWS.
+
+## Why self host?
+
+Self-hosting TestDriver gives you complete control over your test execution environment:
+
+- **Enhanced security**: Get complete control over ingress and egress rules.
+- **Complete customization**: Modify the TestDriver Golden Image (our pre-configured AMI) to include custom dependencies, software, and configurations at launch time.
+- **Powerful Infrastructure**: Run tests on bare metal infrastructure that support emulators and simulators.
+
+You'll use the [TestDriver CLI repository](https://github.com/testdriverai/cli) which contains all the infrastructure templates and setup scripts needed for self-hosting.
+
+## Overview
+
+By the end of this guide, you'll have a complete self-hosted testing infrastructure that can:
+
+- Spawn TestDriver instances on-demand in your AWS account
+- Run tests on your own AWS infrastructure with custom configurations
+- Integrate seamlessly with GitHub Actions CI/CD workflows
+- Automatically clean up resources after test completion
+
+The setup process involves three main steps:
+
+1. **CloudFormation Infrastructure**: Deploy our `setup/aws/cloudformation.yaml` template to create the foundational AWS resources (VPC, security groups, IAM roles, and a launch template for instance creation).
+2. **On-Demand Instance Spawning**: Use `setup/aws/spawn-runner.sh` with your Launch Template ID to programmatically spawn TestDriver instances whenever you need to run tests.
+3. **GitHub Actions Integration**: Use `.github/workflows/self-hosted.yml` as a template for running tests in CI. This workflow demonstrates the complete lifecycle: spawning an instance, running tests, and shutting down the instance to minimize costs.
+
+## Prerequisites
+
+- AWS account with permissions to run CloudFormation.
+- [AWS CLI](https://aws.amazon.com/cli/) installed locally.
+
+  <Tip>
+    Be sure to run `aws configure` with your credentials
+  </Tip>
+- Access to the TestDriver AMI (Golden Image is `ami-055cd47506a2f39bb`)\
+  [Contact us with your preferred AWS Region for access](http://testdriver.ai/demo).
+- A GitHub repository for committing your tests & workflow.
+
+## Step 1: Set Up AWS Infrastructure
+
+### Deploy CloudFormation Stack
+
+Our [`setup/aws/cloudformation.yaml`](https://github.com/testdriverai/cli/tree/main/setup/aws/cloudformation.yaml) template creates:
+
+- Dedicated VPC with public subnet
+- Security group with proper port access
+- IAM roles and instance profiles
+- EC2 launch template for programmatic instance creation
+
+This is a one-time setup used to generate a template ID for launching instances.
+
+```bash
+# Deploy the CloudFormation stack
+aws cloudformation deploy \
+  --template-file setup/aws/cloudformation.yaml \
+  --stack-name my-testdriver-infrastructure \
+  --parameter-overrides \
+    ProjectTag=testdriver \
+    AllowedIngressCidr=0.0.0.0/0 \
+    InstanceType=c5.xlarge \
+    CreateKeyPair=true \
+  --capabilities CAPABILITY_IAM
+```
+
+<Danger>
+  **Security**: Replace `AllowedIngressCidr=0.0.0.0/0` with your specific IP ranges to lock down access to your VPC.
+</Danger>
+
+### Get Launch Template ID
+
+After CloudFormation completes, find the launch template ID in the stack outputs:
+
+```bash
+aws cloudformation describe-stacks \
+  --stack-name my-testdriver-infrastructure \
+  --query 'Stacks[0].Outputs[?OutputKey==`LaunchTemplateId`].OutputValue' \
+  --output text
+```
+
+<Tip>
+  **Save this ID** – you'll need it for the next step.
+</Tip>
+
+## Step 2: Spawn a New TestDriver Runner
+
+This step is performed **every time you want to run tests**. The `spawn-runner.sh` script launches a new EC2 instance on-demand for test execution.
+
+### Using spawn-runner.sh
+
+Our [`setup/aws/spawn-runner.sh`](https://github.com/testdriverai/cli/tree/main/setup/aws/spawn-runner.sh) script:
+
+- Launches a new EC2 instance using your launch template from Step 1
+- Waits for the instance to become ready
+- Completes the TestDriver handshake
+- Returns instance details (IP, instance ID) for CLI usage
+
+The script accepts parameters as either environment variables or CLI arguments:
+
+```bash
+# Launch an instance using environment variables
+export AWS_REGION=us-east-2
+export AMI_ID=ami-••••••••••  # Your TestDriver AMI (contact us to get one)
+export AWS_LAUNCH_TEMPLATE_ID=lt-••••••••••  # From CloudFormation output from step 1
+export RESOLUTION=1440x900 # Change screen resolution if desired (default is 1440x900)
+
+/bin/bash ./setup/aws/spawn-runner.sh
+```
+
+The script outputs:
+
+```
+PUBLIC_IP=1.2.3.4
+INSTANCE_ID=i-1234567890abcdef0
+AWS_REGION=us-east-2
+```
+
+<Note>
+  **Instance Lifecycle**: Instances spawned by this script will continue running until you manually terminate them. They are automatically tagged with `Name=TestDriverRunner` and `Project=[your ProjectTag value]` for easy identification in the AWS console.
+</Note>
+
+#### Changing Resolution in Lifecycle Files
+
+You can also change the resolution before running tests by adding an [`exec`](/commands/exec) command in your `lifecycle/provision.yaml` file:
+
+```yaml lifecycle/provision.yaml
+version: 6.0.0
+steps:
+  - prompt: set screen resolution
+    commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          C:\testdriver\SetResolution.ps1 -Width 1920 -Height 1080
+```
+
+This approach is useful when you need different resolutions for different test scenarios. See the [Lifecycle Files documentation](/guide/lifecycle) for more information about provision scripts.
+
+### CLI Usage
+
+Once you have an instance IP, run tests directly:
+
+```bash
+# Basic test execution
+npx testdriverai@latest run test.yaml --ip=1.2.3.4
+```
+
+You can use the `PUBLIC_IP` to target the instance you just spawned via `./setup/aws/spawn-runner.sh`:
+
+```sh
+npx testdriverai@latest run testdriver/your-test.yaml \
+  --ip="$PUBLIC_IP" \
+```
+
+### Terminating Instances
+
+After your tests complete, terminate the instance to avoid unnecessary costs:
+
+```bash
+# Terminate the instance
+aws ec2 terminate-instances --instance-ids $INSTANCE_ID --region $AWS_REGION
+```
+
+You can also terminate instances manually through the AWS console by searching for instances tagged with `Name=TestDriverRunner`.
+
+## Step 3: GitHub Actions Integration
+
+This step shows you how to automate the entire test lifecycle in CI/CD.
+
+### Example Workflow
+
+Our [`.github/workflows/self-hosted.yml`](https://github.com/testdriverai/cli/tree/main/.github/workflows/self-hosted.yml) demonstrates the complete workflow: spawning an EC2 instance, running your tests, and shutting down the instance automatically to minimize costs.
+
+The workflow uses the GitHub secrets you configure (see below) to authenticate with AWS and spawn instances on-demand:
+
+```yaml
+name: TestDriver Self-Hosted
+
+on:
+  workflow_dispatch:
+  push:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup AWS Instance
+        id: aws-setup
+        run: |
+          OUTPUT=$(./setup/aws/spawn-runner.sh | tee /dev/stderr)
+          PUBLIC_IP=$(echo "$OUTPUT" | grep "PUBLIC_IP=" | cut -d'=' -f2)
+          INSTANCE_ID=$(echo "$OUTPUT" | grep "INSTANCE_ID=" | cut -d'=' -f2)
+          echo "public-ip=$PUBLIC_IP" >> $GITHUB_OUTPUT
+          echo "instance-id=$INSTANCE_ID" >> $GITHUB_OUTPUT
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: ${{ secrets.AWS_REGION }}
+          AWS_LAUNCH_TEMPLATE_ID: ${{ secrets.AWS_LAUNCH_TEMPLATE_ID }}
+          AMI_ID: ${{ secrets.AMI_ID }}
+
+      - name: Run TestDriver
+        run: |
+          npx testdriverai run your-test.yaml \
+            --ip="${{ steps.aws-setup.outputs.public-ip }}"
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+
+      - name: Shutdown AWS Instance
+        if: always()
+        run: |
+          aws ec2 terminate-instances \
+            --region ${{ secrets.AWS_REGION }}
+            --instance-ids ${{ steps.aws-setup.outputs.instance-id }}
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+		  AWS_REGION: ${{ secrets.AWS_REGION }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+```
+
+### Required Secrets
+
+Configure these secrets in your GitHub repository:
+
+| Secret                   | Description                         | Example                                                      |
+| ------------------------ | ----------------------------------- | ------------------------------------------------------------ |
+| `AWS_ACCESS_KEY_ID`      | AWS access key                      | `AKIAIOSFODNN7EXAMPLE`                                       |
+| `AWS_REGION`             | AWS Region                          | `us-east-2`                                                  |
+| `AWS_SECRET_ACCESS_KEY`  | AWS secret key                      | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`                   |
+| `AWS_LAUNCH_TEMPLATE_ID` | Launch template from CloudFormation | `lt-07c53ce8349b958d1`                                       |
+| `AMI_ID`                 | TestDriver AMI ID                   | `ami-085f872ca0cd80fed`                                      |
+| `TD_API_KEY`             | TestDriver API key                  | Your API key from [the dashboard](https://app.testdriver.ai) |
+
+## AMI Customization
+
+### Using the Base AMI
+
+Our TestDriver Golden Image (AMI) comes pre-configured with everything you need to run tests:
+
+**Operating System & Environment:**
+
+- Windows Server with desktop environment
+- VNC + web server for remote desktop access through the browser
+
+**Development Tools:**
+
+- Python (with pip)
+- Node.js (with npm)
+- Git
+
+**Test Infrastructure:**
+
+- TestDriver agent and dependencies
+- Optimized settings for test execution
+- Pre-configured networking for TestDriver CLI communication
+
+### Modifying the AMI
+
+You can customize the AMI for your specific needs:
+
+1. **Launch an instance** from our base AMI
+2. **Make your changes** (install software, configure settings)
+3. **Create a new AMI** from your modified instance
+4. **Update your workflow** to use the new AMI ID
+
+### Amazon Image Builder
+
+For automated AMI builds, use [Amazon EC2 Image Builder](https://aws.amazon.com/image-builder/):
+
+```yaml
+# Example Image Builder pipeline
+Components:
+  - Name: testdriver-base
+    Version: 1.0.0
+    Platform: Windows
+    Type: BUILD
+    Data: |
+      name: TestDriver Custom Setup
+      description: Custom TestDriver AMI with additional software
+      schemaVersion: 1.0
+      phases:
+        - name: build
+          steps:
+            - name: InstallSoftware
+              action: ExecutePowerShell
+              inputs:
+                commands:
+                  - "# Your custom installation commands here"
+```
+
+## Security Considerations
+
+### Network Security
+
+1. **Restrict CIDR blocks**: Only allow access from your known IP ranges
+2. **Use VPC endpoints**: For private communication with AWS services
+3. **Enable VPC Flow Logs**: For network monitoring and debugging
+
+### AWS Authentication
+
+Use [OIDC for GitHub Actions](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) instead of long-term credentials:
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+
+steps:
+  - name: Configure AWS credentials
+    uses: aws-actions/configure-aws-credentials@v4
+    with:
+      role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
+      aws-region: us-east-2
+```
+
+### Instance Security
+
+- **Terminate instances** immediately after use
+- **Monitor costs** with AWS billing alerts
+- **Use least-privilege IAM roles** for instance profiles
+- **Enable CloudTrail** for audit logging
+
+## Troubleshooting
+
+### Common Issues
+
+**Instance not responding in TestDriver CLI:**
+
+When the CLI displays connection errors or timeouts, check:
+
+- **Security group rules**: The CloudFormation template configures all necessary ports (RDP 3389, VNC 5900, and TestDriver communication ports). Verify your security group hasn't been modified.
+- **Instance status checks**: Ensure the instance has passed both system and instance status checks in the AWS console.
+- **AMI compatibility**: Verify the AMI is compatible with your selected instance type (some instance types don't support certain AMIs).
+
+**Connection timeouts:**
+
+- Verify network connectivity from runner to instance
+- Check VPC routing and internet gateway configuration
+- Confirm instance is in correct subnet
+
+**AWS CLI errors:**
+
+- Validate AWS credentials and permissions
+- Check AWS service quotas and limits
+- Verify region consistency across all resources
+
+### Getting Help
+
+For enterprise customers:
+
+- Contact your account manager for AMI access issues
+- Use support channels for infrastructure questions
+- Check the TestDriver documentation for CLI usage