ai-or-die 0.1.0

package/CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Claude Code Web is a web-based interface for the Claude Code CLI that enables browser-based access with multi-session support and real-time streaming capabilities. The application provides a terminal emulator interface through xterm.js with WebSocket communication for real-time interaction.
+
+The project uses the **ai-or-die** agent infrastructure for AI-assisted development. See `AGENTS.md` for the full team roster and handoff protocol.
+
+## Agent Infrastructure
+
+### Agent Personas
+Agent definitions are mirrored in two locations for tool compatibility:
+- `.github/agents/` -- for GitHub Copilot and GitHub-native tooling
+- `.claude/agents/` -- for Claude Code
+
+Available agents: **Architect**, **Engineer**, **QA Reviewer**, **Troubleshooter**, **Researcher**.
+
+### Documentation-Driven Workflow
+Before starting any task, consult the relevant documentation:
+- `docs/agent-instructions/` -- Philosophy, research guidelines, testing standards, tooling conventions
+- `docs/adrs/` -- Architecture Decision Records (check before proposing new patterns)
+- `docs/specs/` -- Component specifications (read before implementing, update after changing behavior)
+- `docs/architecture/` -- System diagrams and component overviews
+- `docs/history/` -- Incident post-mortems and debugging notes
+
+### Mandatory Rules
+1. **Spec updates with code changes**: When code behavior changes, the corresponding spec in `docs/specs/` must be updated in the same commit or PR.
+2. **ADR compliance**: Never contradict an accepted ADR. To change direction, write a new ADR that supersedes the old one.
+3. **Cross-platform support**: All code must work on both Windows and Linux. Use `path.join()` for file paths, provide `.sh` and `.ps1` script variants, and test on both platforms in CI.
+4. **Test coverage**: Every feature and bug fix requires tests. No exceptions.
+
+## Common Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server (with extra logging)
+npm run dev
+
+# Start production server
+npm start
+
+# Start with custom port
+npm start -- --port 8080
+
+# Start with authentication
+npm start -- --auth your-token
+
+# Start with HTTPS
+npm start -- --https --cert cert.pem --key key.pem
+
+# Run tests
+npm test
+
+# Run validation (Linux/macOS)
+bash scripts/validate.sh
+
+# Run validation (Windows PowerShell)
+powershell scripts/validate.ps1
+```
+
+## Architecture
+
+### Core Components
+
+**Server Layer (src/server.js)**
+- Express server handling REST API and WebSocket connections
+- Session persistence via SessionStore (saves to ~/.claude-code-web/sessions.json)
+- Authentication middleware with rate limiting
+- Folder mode for working directory selection
+- Auto-save sessions every 30 seconds
+
+**Claude Bridge (src/claude-bridge.js)**
+- Manages Claude CLI process spawning using node-pty
+- Handles multiple concurrent Claude sessions
+- Process lifecycle management (start, stop, resize)
+- Output buffering for reconnection support
+- Searches for Claude CLI in multiple standard locations
+
+**Session Management**
+- Persistent sessions survive server restarts
+- Multi-browser support - same session accessible from different devices
+- Session data includes: ID, name, working directory, output buffer, creation time
+- Sessions auto-save and can be manually deleted
+
+**Client Architecture (src/public/)**
+- **app.js**: Main interface controller, terminal setup, WebSocket management
+- **session-manager.js**: Session tab UI, notifications, multi-session handling
+- **plan-detector.js**: Detects Claude plan mode and provides approval UI
+- **auth.js**: Client-side authentication handling
+- **service-worker.js**: PWA support for offline capabilities
+
+### WebSocket Protocol
+
+The application uses WebSocket for real-time bidirectional communication:
+- `create_session`: Initialize new Claude session
+- `join_session`: Connect to existing session
+- `leave_session`: Disconnect without stopping Claude
+- `start_claude`: Launch Claude CLI in session
+- `input`: Send user input to Claude
+- `resize`: Adjust terminal dimensions
+- `stop`: Terminate Claude process
+
+### Security Features
+- Optional token-based authentication (Bearer token or query parameter)
+- Rate limiting (100 requests/minute per IP by default)
+- Path validation to prevent directory traversal
+- HTTPS support with SSL certificates
+
+## Key Implementation Details
+
+- Claude CLI discovery attempts multiple paths including ~/.claude/local/claude
+- Sessions persist to disk at ~/.claude-code-web/sessions.json
+- Output buffer maintains last 1000 lines for reconnection
+- Terminal uses xterm-256color with full ANSI color support
+- Folder browser restricts access to base directory and subdirectories only
+- Mobile-responsive design with touch-optimized controls
+
+## Coding Style
+
+- Language: Node.js (CommonJS modules)
+- Indentation: 2 spaces
+- Quotes: single quotes
+- Semicolons: required
+- File naming: kebab-case for modules, PascalCase for classes, camelCase for functions/variables
+- Tests: `*.test.js` in the `test/` directory
+- Commits: Conventional Commits format (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, `refactor:`)

package/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to ai-or-die
+
+Thanks for your interest in contributing! This guide covers how to set up the project, run it locally, write tests, and open quality pull requests.
+
+## Project Structure
+
+- `bin/ai-or-die.js`: CLI entry point; parses flags and starts the server.
+- `src/server.js`: Express + WebSocket server, routes, session wiring.
+- `src/base-bridge.js`: Shared bridge logic for all CLI tools.
+- `src/claude-bridge.js`, `src/codex-bridge.js`, etc.: Tool-specific bridges extending BaseBridge.
+- `src/copilot-bridge.js`, `src/gemini-bridge.js`, `src/terminal-bridge.js`: New tool bridges.
+- `src/utils/*`: Helpers (auth token handling, session persistence).
+- `src/public/*`: Browser UI assets (HTML/JS/CSS) served by the server.
+- `test/*.test.js`: Mocha unit tests.
+- `docs/`: Technical documentation, specs, ADRs, and agent instructions.
+
+## Setup
+
+```bash
+git clone https://github.com/animeshkundu/ai-or-die.git
+cd ai-or-die
+npm install
+npm run dev
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+Write tests in `test/` as `name.test.js`. Use Mocha with Node's `assert`. Mock process spawns — avoid network calls or real CLI invocations in tests.
+
+## Coding Style
+
+- **Language**: Node.js (CommonJS)
+- **Indentation**: 2 spaces, semicolons, single quotes
+- **Files**: kebab-case for modules, PascalCase for classes, camelCase for functions
+- **Tests**: `*.test.js` in `test/`
+- **Cross-platform**: Always use `os.homedir()`, `path.join()`, and platform-aware command discovery
+
+## Adding a New Tool
+
+1. Create `src/yourname-bridge.js` extending `BaseBridge`
+2. Register it in `src/server.js` (import, instantiate, add to `getBridgeForAgent()`)
+3. Add WebSocket handler for `start_yourtool` in `handleMessage()`
+4. The UI generates cards dynamically from `/api/config` — no HTML changes needed
+
+See [docs/architecture/bridge-pattern.md](docs/architecture/bridge-pattern.md) for the full guide.
+
+## Pull Request Guidelines
+
+- Concise description with linked issues
+- Include tests for behavior changes
+- Update relevant docs in `docs/specs/` when changing code
+- Screenshots/GIFs for UI-facing changes
+- Follow Conventional Commits (`feat:`, `fix:`, `chore:`)
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add Gemini CLI bridge support
+fix(bridge): handle Windows path separators in command discovery
+chore(release): v0.1.0
+```
+
+## Documentation
+
+Before making code changes, check:
+- `docs/agent-instructions/` for development protocols
+- `docs/adrs/` for past architectural decisions
+- `docs/specs/` for the relevant module specification
+
+After making code changes, update the corresponding spec.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 ai-or-die contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,165 @@
+# ai-or-die
+
+Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser.
+
+ai-or-die is a web-based terminal aggregator that provides browser access to multiple AI CLI tools through a unified interface. Launch Claude, GitHub Copilot, Google Gemini, OpenAI Codex, or a raw terminal session — all from one place, with multi-session support and real-time streaming.
+
+## Features
+
+- **Multi-tool support** — Claude, Copilot, Gemini, Codex, and raw terminal in one interface
+- **Dynamic tool detection** — automatically discovers which tools are installed
+- **Real-time streaming** — full terminal emulation via xterm.js with 256-color support
+- **Multi-session** — run multiple sessions in browser tabs, switch between them
+- **Multi-device** — same session accessible from different browsers/devices
+- **Session persistence** — sessions survive server restarts
+- **Authentication** — token-based auth enabled by default
+- **Dev Tunnels** — secure remote access via Microsoft Dev Tunnels
+- **Cross-platform** — works on Linux and Windows (ConPTY)
+- **PWA** — installable as a Progressive Web App
+- **Mobile-friendly** — responsive design with touch-optimized controls
+
+## Requirements
+
+- Node.js >= 16
+- At least one supported CLI tool installed:
+  - [Claude Code](https://claude.ai/code) — `claude`
+  - [GitHub Copilot CLI](https://github.com/features/copilot/cli) — `copilot`
+  - [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) — `gemini`
+  - [OpenAI Codex](https://openai.com/codex) — `codex`
+  - Terminal is always available (bash/PowerShell)
+
+## Quick Start
+
+```bash
+# Run without installing
+npx ai-or-die
+
+# Or install globally
+npm install -g ai-or-die
+ai-or-die
+```
+
+## Usage
+
+```bash
+# Start with default settings
+ai-or-die
+
+# Custom port
+ai-or-die --port 8080
+
+# With specific auth token
+ai-or-die --auth your-secret-token
+
+# Development mode (extra logging)
+ai-or-die --dev
+
+# HTTPS mode
+ai-or-die --https --cert cert.pem --key key.pem
+
+# Remote access via Dev Tunnels
+ai-or-die --tunnel --tunnel-allow-anonymous
+
+# Custom tool aliases
+ai-or-die --claude-alias "AI" --copilot-alias "CP" --gemini-alias "Gem"
+
+# Disable auth (not recommended for production)
+ai-or-die --disable-auth
+```
+
+## CLI Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --port <number>` | Server port | `7777` |
+| `--no-open` | Don't auto-open browser | |
+| `--auth <token>` | Set auth token | auto-generated |
+| `--disable-auth` | Disable authentication | |
+| `--https` | Enable HTTPS | |
+| `--cert <path>` | SSL certificate file | |
+| `--key <path>` | SSL private key file | |
+| `--dev` | Development mode | |
+| `--plan <type>` | Subscription plan (pro, max5, max20) | `max20` |
+| `--tunnel` | Enable Dev Tunnel | |
+| `--tunnel-allow-anonymous` | Allow anonymous tunnel access | |
+| `--claude-alias <name>` | Display name for Claude | `Claude` |
+| `--codex-alias <name>` | Display name for Codex | `Codex` |
+| `--copilot-alias <name>` | Display name for Copilot | `Copilot` |
+| `--gemini-alias <name>` | Display name for Gemini | `Gemini` |
+| `--terminal-alias <name>` | Display name for Terminal | `Terminal` |
+
+## Dev Tunnels Setup
+
+For remote access, ai-or-die uses [Microsoft Dev Tunnels](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/):
+
+```bash
+# Install devtunnel CLI
+# Windows:
+winget install Microsoft.devtunnel
+
+# Linux:
+curl -sL https://aka.ms/DevTunnelCliInstall | bash
+
+# First-time login (one-time)
+devtunnel user login
+
+# Then start ai-or-die with tunnel
+ai-or-die --tunnel --tunnel-allow-anonymous
+```
+
+## Supported Tools
+
+| Tool | Command | Install |
+|------|---------|---------|
+| Claude | `claude` | [claude.ai/code](https://claude.ai/code) |
+| Copilot | `copilot` | `npm install -g @github/copilot` or `winget install GitHub.Copilot` |
+| Gemini | `gemini` | `npm install -g @google/gemini-cli` |
+| Codex | `codex` | [openai.com/codex](https://openai.com/codex) |
+| Terminal | bash/PowerShell | Always available |
+
+Tools that aren't installed appear as disabled in the UI. Install them at any time — ai-or-die detects them on next startup.
+
+## Architecture
+
+See [docs/](docs/README.md) for full technical documentation:
+
+- [System Overview](docs/architecture/overview.md)
+- [WebSocket Protocol](docs/architecture/websocket-protocol.md)
+- [Bridge Pattern](docs/architecture/bridge-pattern.md)
+- [Architecture Decision Records](docs/adrs/)
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/animeshkundu/ai-or-die.git
+cd ai-or-die
+npm install
+
+# Run in dev mode
+npm run dev
+
+# Run tests
+npm test
+```
+
+## API
+
+### REST Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/health` | Server health check |
+| `GET` | `/api/config` | Server config + tool availability |
+| `GET` | `/api/sessions/list` | List all sessions |
+| `POST` | `/api/sessions/create` | Create a new session |
+| `DELETE` | `/api/sessions/:id` | Delete a session |
+| `GET` | `/api/folders` | Browse directories |
+
+### WebSocket
+
+Connect to `ws://localhost:7777?token=<auth-token>` for real-time communication. See [WebSocket Protocol docs](docs/architecture/websocket-protocol.md) for the full message reference.
+
+## License
+
+MIT

package/bin/ai-or-die.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const path = require('path');
+const crypto = require('crypto');
+
+// Lazy-load open — may not be available in SEA binary
+let open;
+try { open = require('open'); } catch { open = null; }
+const { startServer } = require('../src/server');
+
+const program = new Command();
+
+program
+  .name('ai-or-die')
+  .description('ai-or-die — Universal AI coding terminal')
+  .version('0.1.0')
+  .option('-p, --port <number>', 'port to run the server on', '7777')
+  .option('--no-open', 'do not automatically open browser')
+  .option('--auth <token>', 'authentication token for secure access')
+  .option('--disable-auth', 'disable authentication (not recommended for production)')
+  .option('--https', 'enable HTTPS (requires cert files)')
+  .option('--cert <path>', 'path to SSL certificate file')
+  .option('--key <path>', 'path to SSL private key file')
+  .option('--dev', 'development mode with additional logging')
+  .option('--plan <type>', 'subscription plan (pro, max5, max20)', 'max20')
+  .option('--claude-alias <name>', 'display alias for Claude (default: env CLAUDE_ALIAS or "Claude")')
+  .option('--codex-alias <name>', 'display alias for Codex (default: env CODEX_ALIAS or "Codex")')
+  .option('--copilot-alias <name>', 'display alias for Copilot (default: env COPILOT_ALIAS or "Copilot")')
+  .option('--gemini-alias <name>', 'display alias for Gemini (default: env GEMINI_ALIAS or "Gemini")')
+  .option('--terminal-alias <name>', 'display alias for Terminal (default: env TERMINAL_ALIAS or "Terminal")')
+  .option('--tunnel', 'enable dev tunnel (requires devtunnel CLI installed)')
+  .option('--tunnel-allow-anonymous', 'allow anonymous access to dev tunnel')
+  .parse();
+
+const options = program.opts();
+
+function generateRandomToken(length = 10) {
+  const chars = 'ABCDEFGHJKMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789';
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+async function main() {
+  try {
+    const port = parseInt(options.port, 10);
+
+    if (isNaN(port) || port < 1 || port > 65535) {
+      console.error('Error: Port must be a number between 1 and 65535');
+      process.exit(1);
+    }
+
+    // Handle authentication logic
+    let authToken = null;
+    let noAuth = options.disableAuth === true;
+
+    if (!noAuth) {
+      if (options.auth) {
+        // Use provided token
+        authToken = options.auth;
+      } else {
+        // Generate random token
+        authToken = generateRandomToken();
+      }
+    }
+
+    const serverOptions = {
+      port,
+      auth: authToken,
+      noAuth: noAuth,
+      https: options.https,
+      cert: options.cert,
+      key: options.key,
+      dev: options.dev,
+      plan: options.plan,
+      // UI aliases for assistants
+      claudeAlias: options.claudeAlias || process.env.CLAUDE_ALIAS || 'Claude',
+      codexAlias: options.codexAlias || process.env.CODEX_ALIAS || 'Codex',
+      copilotAlias: options.copilotAlias || process.env.COPILOT_ALIAS || 'Copilot',
+      geminiAlias: options.geminiAlias || process.env.GEMINI_ALIAS || 'Gemini',
+      terminalAlias: options.terminalAlias || process.env.TERMINAL_ALIAS || 'Terminal',
+      folderMode: true // Always use folder mode
+    };
+
+    console.log('Starting ai-or-die...');
+    console.log(`Port: ${port}`);
+    console.log('Mode: Folder selection mode');
+    console.log(`Plan: ${options.plan}`);
+    console.log(`Aliases: Claude → "${serverOptions.claudeAlias}", Codex → "${serverOptions.codexAlias}", Copilot → "${serverOptions.copilotAlias}", Gemini → "${serverOptions.geminiAlias}", Terminal → "${serverOptions.terminalAlias}"`);
+
+    // Display authentication status prominently
+    if (noAuth) {
+      console.log('\n⚠️  AUTHENTICATION DISABLED - Server is accessible without a token');
+      console.log('   (Use without --disable-auth flag for security in production)');
+    } else {
+      console.log('\n🔐 AUTHENTICATION ENABLED');
+      if (options.auth) {
+        console.log('   Using provided authentication token');
+      } else {
+        console.log('   Generated random authentication token:');
+        console.log(`   \x1b[1m\x1b[33m${authToken}\x1b[0m`);
+        console.log('   \x1b[2mSave this token - you\'ll need it to access the interface\x1b[0m');
+      }
+    }
+
+    const server = await startServer(serverOptions);
+
+    const protocol = options.https ? 'https' : 'http';
+    const url = `${protocol}://localhost:${port}`;
+
+    console.log(`\n🚀 ai-or-die is running at: ${url}`);
+
+    if (!noAuth) {
+      console.log('\n📋 Authentication Required:');
+      if (options.auth) {
+        console.log('   Use your provided authentication token to access the interface');
+      } else {
+        console.log(`   Enter this token when prompted: \x1b[1m\x1b[33m${authToken}\x1b[0m`);
+      }
+    }
+
+    // Dev tunnel setup
+    let tunnelProcess = null;
+    let publicUrl = null;
+    if (options.tunnel) {
+      console.log('\n\x1b[36m  Connecting dev tunnel...\x1b[0m');
+      try {
+        const { spawn: cpSpawn, execFileSync } = require('child_process');
+
+        // Check if devtunnel CLI is available
+        const devtunnelCmd = process.platform === 'win32' ? 'where' : 'which';
+        try {
+          execFileSync(devtunnelCmd, ['devtunnel'], { stdio: 'ignore' });
+        } catch (_) {
+          const isWin = process.platform === 'win32';
+          console.error('\n\x1b[31m  devtunnel CLI not found.\x1b[0m\n');
+          console.error('  Install it with a single command:');
+          if (isWin) {
+            console.error('  \x1b[1mwinget install Microsoft.devtunnel\x1b[0m');
+          } else if (process.platform === 'darwin') {
+            console.error('  \x1b[1mbrew install --cask devtunnel\x1b[0m');
+          } else {
+            console.error('  \x1b[1mcurl -sL https://aka.ms/DevTunnelCliInstall | bash\x1b[0m');
+          }
+          console.error('\n  Then run: \x1b[1mdevtunnel user login\x1b[0m (one-time)\n');
+          process.exit(1);
+        }
+
+        const tunnelArgs = ['host', '-p', String(port)];
+        if (options.tunnelAllowAnonymous) tunnelArgs.push('--allow-anonymous');
+        tunnelProcess = cpSpawn('devtunnel', tunnelArgs, { stdio: ['pipe', 'pipe', 'pipe'] });
+
+        tunnelProcess.stdout.on('data', (data) => {
+          const match = data.toString().match(/https:\/\/[\w.-]+\.devtunnels\.ms\S*/);
+          if (match && !publicUrl) {
+            publicUrl = match[0].trim();
+            console.log(`\n  \x1b[1m\x1b[32mTunnel ready:\x1b[0m \x1b[1m\x1b[4m${publicUrl}\x1b[0m\n`);
+            if (options.open) {
+              if (open) open(publicUrl).catch(() => {});
+            }
+          }
+        });
+        tunnelProcess.stderr.on('data', (data) => {
+          const output = data.toString().trim();
+          if (output && options.dev) console.log(`  [devtunnel] ${output}`);
+        });
+        tunnelProcess.on('error', () => {
+          console.error('\n  \x1b[31mDev tunnel process failed to start.\x1b[0m');
+        });
+      } catch (error) {
+        console.error('  Failed to start dev tunnel:', error.message);
+      }
+    } else if (options.open) {
+      try { if (open) await open(url); } catch (error) {
+        console.warn('  Could not automatically open browser:', error.message);
+      }
+    }
+
+    console.log('\nPress Ctrl+C to stop the server\n');
+
+    const shutdown = async () => {
+      console.log('\nShutting down server...');
+      // Close dev tunnel first if active
+      if (tunnelProcess) { try { tunnelProcess.kill(); } catch (_) {} }
+      server.close(() => {
+        console.log('Server closed');
+        process.exit(0);
+      });
+    };
+
+    process.on('SIGINT', () => { shutdown(); });
+    process.on('SIGTERM', () => { shutdown(); });
+
+  } catch (error) {
+    console.error('Error starting server:', error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/docs/.nojekyll

@@ -0,0 +1 @@
+# Prevent GitHub Pages from using Jekyll so our assets serve as-is

package/docs/README.md

@@ -0,0 +1,37 @@
+# ai-or-die Documentation
+
+Central documentation for the ai-or-die project -- a Node.js web application that provides browser-based access to AI CLI tools (Claude, Codex, Copilot, Gemini, Terminal, and more) through a shared terminal emulator interface.
+
+## Architecture
+
+- [System Overview](architecture/overview.md)
+- [WebSocket Protocol](architecture/websocket-protocol.md)
+- [Bridge Pattern](architecture/bridge-pattern.md)
+
+## Specifications
+
+- [Server](specs/server.md)
+- [CLI Bridges](specs/bridges.md)
+- [Session Store](specs/session-store.md)
+- [Authentication](specs/authentication.md)
+- [Client Application](specs/client-app.md)
+- [Usage Analytics](specs/usage-analytics.md)
+
+## Architecture Decision Records
+
+- [ADR Template](adrs/0000-template.md)
+- [ADR-0001: Bridge Base Class](adrs/0001-bridge-base-class.md)
+- [ADR-0002: DevTunnels over ngrok](adrs/0002-devtunnels-over-ngrok.md)
+- [ADR-0003: Multi-Tool Architecture](adrs/0003-multi-tool-architecture.md)
+- [ADR-0004: Cross-Platform Support](adrs/0004-cross-platform-support.md)
+
+## Agent Instructions
+
+- [Philosophy](agent-instructions/00-philosophy.md)
+- [Research & Web](agent-instructions/01-research-and-web.md)
+- [Testing & Validation](agent-instructions/02-testing-and-validation.md)
+- [Tooling & Pipelines](agent-instructions/03-tooling-and-pipelines.md)
+
+## History
+
+- [Changelog](history/README.md)

package/docs/adrs/0000-template.md

@@ -0,0 +1,35 @@
+# ADR-0000: [Title]
+
+## Status
+
+**Proposed** | Accepted | Deprecated
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+Describe the forces at play, including technical, political, social, and project-specific. What is the issue that is motivating this decision or change? What constraints exist?
+
+## Decision
+
+State the architecture decision clearly. Use full sentences and active voice. Explain *what* we are doing and *why*.
+
+## Consequences
+
+### Positive
+
+- What becomes easier or possible as a result of this change?
+
+### Negative
+
+- What becomes harder or what trade-offs are introduced?
+
+### Neutral
+
+- What other effects does this decision have that are neither clearly positive nor negative?
+
+## Notes
+
+Any additional context, links to discussions, or references to related ADRs.