Add comprehensive GitHub Copilot and AI agent setup documentation

.github/copilot-instructions.md

@@ -2,6 +2,75 @@
 
 This document provides context and guidelines for GitHub Copilot when working on the Onchain Test Kit project.
 
+## Table of Contents
+1. [Quick Start Setup](#quick-start-setup-for-github-copilot)
+2. [Project Overview](#project-overview)
+3. [Build and Development Commands](#build-and-development-commands)
+4. [Architecture & Project Layout](#architecture--project-layout)
+5. [Configuration Patterns](#configuration-patterns)
+6. [Development Guidelines](#development-guidelines)
+7. [Environment Setup](#environment-setup)
+8. [Common Patterns & Examples](#common-patterns--examples)
+9. [Troubleshooting](#troubleshooting)
+10. [Understanding Agent Instructions Structure](#understanding-agent-instructions-structure)
+11. [Example Workflows for AI Agents](#example-workflows-for-ai-agents)
+
+## Quick Start Setup for GitHub Copilot
+
+### Step 1: Repository Setup
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/coinbase/onchaintestkit.git
+   cd onchaintestkit
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+3. **Verify setup**:
+   ```bash
+   npm run build && npm run test
+   ```
+
+### Step 2: GitHub Copilot Configuration
+1. **Enable Copilot** in your IDE (VS Code, IntelliJ, etc.)
+2. **Load project context**: Open the repository in your IDE to let Copilot understand the codebase
+3. **Review instructions**: Familiarize yourself with this file and the specialized instruction files in `.github/instructions/`
+
+### Step 3: AI Agent Setup (Optional)
+For advanced AI assistance, review the agent-specific documentation:
+- **Claude**: See `CLAUDE.md` for Claude-specific instructions and focus areas
+- **Gemini**: See `GEMINI.md` for Gemini-specific strengths and workflows
+- **General**: See `AGENTS.md` for common AI agent guidelines
+
+### Step 4: Environment Configuration
+1. **Set required environment variables**:
+   ```bash
+   # Create .env file (never commit this)
+   cp .env.example .env
+   # Edit .env to add your E2E_TEST_SEED_PHRASE and any other secrets
+   nano .env   # Or use your preferred editor (vim, code, etc.)
+   ```
+
+2. **Prepare wallet extensions** (required for testing):
+   ```bash
+   npm run prepare-metamask  # ✅ Works correctly
+   npm run prepare-coinbase  # ⚠️ Currently has known issues
+   npm run prepare-phantom   # ⚠️ Currently has known issues
+   ```
+
+### Step 5: Verify Setup
+```bash
+# Run the complete setup verification
+npm run build
+npm run lint
+npm run test
+
+# If all pass, you're ready to contribute!
+```
+
 ## Project Overview
 
 The Onchain Test Kit is an **end-to-end testing toolkit for blockchain applications**, powered by Playwright. It provides comprehensive wallet automation and testing capabilities for DApps with support for MetaMask, Coinbase Wallet, and Phantom wallets.
@@ -219,4 +288,157 @@
 
 ---
 
-**Remember**: This is a testing toolkit focused on reliability and developer experience. Always prioritize clear APIs, comprehensive error handling, and type safety over performance optimizations.
+**Remember**: This is a testing toolkit focused on reliability and developer experience. Always prioritize clear APIs, comprehensive error handling, and type safety over performance optimizations.
+
+## Understanding Agent Instructions Structure
+
+### Main Documentation Files
+- **`.github/copilot-instructions.md`** (this file): Primary GitHub Copilot configuration and context
+- **`AGENTS.md`**: General instructions for all AI coding agents
+- **`CLAUDE.md`**: Claude-specific instructions and focus areas
+- **`GEMINI.md`**: Gemini-specific strengths and development priorities
+- **`CONTRIBUTING.md`**: Human contributor guidelines (also useful for agents)
+
+### Specialized Instruction Files (`.github/instructions/`)
+Located in `.github/instructions/`, these provide deep, specialized guidance:
+
+1. **`development.instructions.md`**: 
+   - Development environment setup
+   - Code quality standards  
+   - Architecture guidelines
+   - Build and deployment workflows
+
+2. **`testing.instructions.md`**:
+   - Comprehensive testing strategies
+   - Test structure and organization
+   - Fork mode testing patterns
+   - Cross-wallet compatibility testing
+
+3. **`wallet-integration.instructions.md`**:
+   - Wallet-specific implementation patterns
+   - Extension setup and configuration
+   - Action handling and debugging
+   - Cross-wallet testing approaches
+
+### How to Use These Instructions
+
+#### For New Contributors
+1. Start with this file (`.github/copilot-instructions.md`) for project overview
+2. Review `AGENTS.md` for general development patterns
+3. Check agent-specific files (`CLAUDE.md`, `GEMINI.md`) if using those tools
+4. Dive into specialized instructions based on your task:
+   - Building features? → `development.instructions.md`
+   - Writing tests? → `testing.instructions.md`
+   - Working with wallets? → `wallet-integration.instructions.md`
+
+#### For AI Agents
+- **Primary context**: Load this file for main project understanding
+- **Task-specific**: Reference specialized instruction files for detailed guidance
+- **Agent-specific**: Follow your agent's specific documentation (CLAUDE.md, GEMINI.md, etc.)
+
+#### Best Practices for Extending Instructions
+- **Keep consistency**: Follow the established patterns and tone
+- **Be specific**: Include concrete examples and code snippets
+- **Test examples**: Ensure all code examples work with the current codebase
+- **Cross-reference**: Link related sections between files
+- **Update regularly**: Keep instructions current with code changes
+
+## Example Workflows for AI Agents
+
+### Workflow 1: Adding a New Wallet Action
+```typescript
+// 1. Define the action type
+type NewActionType = 'signMessage' | 'personalSign';
+
+// 2. Add to base wallet interface
+interface ActionOptions {
+  message?: string;
+  shouldApprove?: boolean;
+}
+
+// 3. Implement in all wallet classes
+async handleAction(action: WalletActionType, options: ActionOptions): Promise<void> {
+  switch (action) {
+    case 'signMessage':
+      return this.handleSignMessage(options);
+    // ... other cases
+  }
+}
+
+// 4. Add comprehensive tests
+test('sign message action', async ({ wallet }) => {
+  await wallet.handleAction('signMessage', {
+    message: 'Hello World',
+    shouldApprove: true
+  });
+});
+```
+
+### Workflow 2: Adding Fork Mode Support for New Chain
+```typescript
+// 1. Research the chain configuration
+const optimismConfig = {
+  name: 'Optimism',
+  chainId: 10,
+  rpcUrl: 'https://opt-mainnet.g.alchemy.com/v2/api-key',
+  forkBlockNumber: 110000000, // Specific block for reproducibility
+};
+
+// 2. Create configuration pattern
+const optimismFork = configure()
+  .withMetaMask()
+  .withLocalNode({
+    fork: optimismConfig.rpcUrl,
+    forkBlockNumber: optimismConfig.forkBlockNumber,
+    chainId: optimismConfig.chainId,
+  })
+  .withNetwork(optimismConfig)
+  .build();
+
+// 3. Add example test
+test('test on Optimism fork', async ({ page, metamask, node }) => {
+  await page.goto('https://app.uniswap.org');
+  // Test with real Optimism contracts and liquidity
+});
+```
+
+### Workflow 3: Debugging Wallet Issues
+```typescript
+// 1. Add comprehensive logging
+class WalletDebugger {
+  static async debugWalletAction(wallet: Wallet, action: string) {
+    console.log(`Starting ${action} on ${wallet.constructor.name}`);
+
+    try {
+      await wallet.handleAction(action);
+      console.log(`✅ ${action} completed successfully`);
+    } catch (error) {
+      console.error(`❌ ${action} failed:`, error);
+      // Take screenshot for debugging
+      await this.captureDebugInfo(wallet, error);
+      throw error;
+    }
+  }
+}
+
+// 2. Create diagnostic test
+test('diagnose wallet connection issues', async ({ page, wallet }) => {
+  await WalletDebugger.debugWalletAction(wallet, 'connect');
+});
+```
+
+### Troubleshooting Common Agent Issues
+
+#### Issue: "Agent suggestions not relevant to blockchain context"
+**Solution**: Ensure you're loading the correct context files and understanding the wallet automation patterns.
+
+#### Issue: "Generated tests are flaky"
+**Solution**: Use proper waiting strategies and timeouts specifically for blockchain operations:
+```typescript
+// Good: Specific timeouts for wallet operations
+await wallet.handleAction('connect', { timeout: 30000 });
+await expect(page.getByTestId('balance')).toBeVisible({ timeout: 45000 });
+```
+
+#### Issue: "Agent doesn't understand fork mode implications"
+**Solution**: Review the fork mode examples in the documentation and understand that fork mode creates local blockchain instances with real mainnet data.

AGENTS.md

@@ -2,6 +2,52 @@
 
 This document provides general instructions for AI coding agents working on the Onchain Test Kit project. For agent-specific instructions, see the corresponding files (CLAUDE.md, GEMINI.md, etc.).
 
+## Getting Started as an AI Agent
+
+### Quick Setup Checklist
+1. **Environment Verification**:
+   ```bash
+   node --version    # Must be >= 14.0.0
+   npm --version     # Verify npm is available
+   ```
+
+2. **Repository Setup**:
+   ```bash
+   npm install       # Install dependencies
+   npm run build     # Verify build works
+   npm run test      # Confirm tests pass (3 tests, ~800ms)
+   ```
+
+3. **Understanding the Codebase**:
+   - Main API: `src/configBuilder.ts` (affects all users)
+   - Test creation: `src/createOnchainTest.ts`
+   - Wallet implementations: `src/wallets/*/index.ts`
+   - CLI tools: `src/cli/*.mjs`
+
+### Agent Workflow Example
+```typescript
+// 1. Understand the user's requirement
+// Example: "Add support for a new wallet action"
+
+// 2. Identify the files to modify
+// - src/wallets/base/types.ts (add action type)
+// - src/wallets/*/index.ts (implement in all wallets)
+// - tests/ (add comprehensive tests)
+
+// 3. Follow existing patterns
+const config = configure()
+  .withMetaMask()
+  .withSeedPhrase({ seedPhrase: "...", password: "..." })
+  .withNetwork({ name: "Base", rpcUrl: "...", chainId: 8453 })
+  .build();
+
+// 4. Validate with tests
+test('new action works correctly', async ({ metamask }) => {
+  await metamask.handleAction('newAction', { shouldApprove: true });
+  // Verify expected behavior
+});
+```
+
 ## Project Overview
 
 The Onchain Test Kit is an end-to-end testing toolkit for blockchain applications, powered by Playwright. It provides comprehensive wallet automation and testing capabilities for DApps with support for MetaMask, Coinbase Wallet, and Phantom wallets.
@@ -98,21 +144,79 @@
 
 ## Common Issues and Solutions
 
-### TypeScript Compilation
+### Agent Setup Issues
+
+#### 1. "Cannot find module" or TypeScript errors
+```bash
+# Solution: Ensure all dependencies are installed
+npm install
+npm run build
+
+# Check peer dependencies
+npm ls @playwright/test
+```
+
+#### 2. "Extension not found" during wallet tests
+```bash
+# Solution: Prepare wallet extensions
+npm run prepare-metamask  # ✅ Works
+npm run prepare-coinbase  # ⚠️ Known issue with zip download
+npm run prepare-phantom   # ⚠️ Known issue with zip download
+
+# Workaround: Use MetaMask for testing until other wallets are fixed
+```
+
+#### 3. "Network timeout" or RPC errors
+```bash
+# Solution: Use proper RPC URLs with rate limits
+# For fork mode testing, use paid RPC providers (Alchemy, Infura)
+# Avoid public endpoints for CI/CD pipelines
+```
+
+#### 4. Test flakiness or timing issues
+```typescript
+// Solution: Use proper waiting strategies
+await expect(page.getByTestId('result')).toBeVisible({ timeout: 30000 });
+await wallet.handleAction('connect', { timeout: 45000 });
+```
+
+### Build and Development Issues
+
+#### TypeScript Compilation
 - Ensure `@playwright/test` is available in dependencies
 - Check tsconfig.json includes proper lib configuration for Node.js
 - Use proper typing for Playwright fixtures
 
-### Wallet Extension Issues
+#### Wallet Extension Issues
 - Run preparation scripts to download extensions
 - Verify extension paths in test configuration
 - Check browser compatibility
 
-### Network Configuration
+#### Network Configuration
 - Validate RPC URLs and chain IDs
 - Use proper network configurations from viem
 - Handle rate limiting with paid RPC providers
 
+### Agent-Specific Best Practices
+
+#### For Claude
+- Focus on comprehensive analysis and edge cases
+- Provide detailed explanations for complex blockchain concepts
+- Consider multiple implementation approaches
+- Document reasoning behind architectural decisions
+
+#### For Gemini
+- Emphasize rapid prototyping and iteration
+- Focus on user experience and clear APIs
+- Optimize for performance and reliability
+- Provide practical, actionable solutions
+
+#### For GitHub Copilot
+- Use descriptive function and variable names
+- Write clear comments explaining blockchain-specific logic
+- Follow established patterns consistently
+- Leverage TypeScript types for better suggestions
+
 ## Contributing Guidelines
 
 1. **Follow existing patterns**: Use established architectural approaches