README: full audit-ready rewrite — 3,551-line extension, commands, architecture, file structure

README.md

@@ -1,3 +1,68 @@
-# alfred-commander
+# Alfred Commander
 
-Alfred Commander — VS Code extension for AI chat, voice commands, and workspace tools in Alfred IDE.
+**3,551-line VS Code extension — AI chat, voice, stats, walkthrough — the brain of Alfred IDE.**
+
+Alfred Commander is a single-file VS Code/code-server extension that provides multi-provider AI chat, speech-to-text/text-to-speech, workspace intelligence, and an interactive walkthrough. It is the primary user interface for Alfred IDE.
+
+## Architecture
+
+One extension, one `extension.js` — 3,551 lines of production code. No framework, no bundler, no node_modules. Pure VS Code API.
+
+### What It Does
+
+| Feature | How it works |
+|---------|-------------|
+| **AI Chat** | Multi-provider (Anthropic Claude, OpenAI GPT, Groq, local Ollama) via streaming API |
+| **Voice** | Browser SpeechRecognition for STT, Kokoro TTS engine for speech output |
+| **Attachments** | Drag-and-drop files/images into chat, base64 encoding for vision models |
+| **Model Picker** | Runtime model switching across all providers |
+| **Stats Panel** | Account usage, token counts, billing period, plan badge |
+| **Walkthrough** | 6-page interactive onboarding (sovereignty, models, voice, shortcuts, stats) |
+| **Sidebar** | Custom webview with full HTML/CSS/JS UI rendered in VS Code panel |
+| **MCP Tools** | 500+ tools via gocodeme-mcp service integration |
+
+### Commands
+
+| Command | Action |
+|---------|--------|
+| `alfred-commander.open` | Open the Alfred chat panel |
+| `alfred-commander.toggle` | Toggle panel visibility |
+| `alfred-commander.showStats` | Account & usage statistics |
+| `alfred-commander.welcome` | Open walkthrough |
+| `alfred-commander.workspaceStatus` | Workspace health check |
+
+## File Structure
+
+```
+alfred-commander/
+├── extension.js              # 3,551 lines — entire extension
+├── package.json              # Extension manifest, commands, keybindings
+├── extensions.json           # Extension dependency declarations
+├── media/
+│   ├── alfred-icon.svg       # Panel icon
+│   └── walkthrough/
+│       ├── meet-alfred.md    # Introduction walkthrough
+│       ├── sovereign.md      # Sovereignty & privacy walkthrough
+│       ├── models.md         # AI model configuration
+│       ├── voice.md          # Voice assistant setup
+│       ├── shortcuts.md      # Keyboard shortcuts reference
+│       └── stats.md          # Usage statistics guide
+```
+
+## Key Design Decisions
+
+- **Single file**: No build step, no transpilation, no bundler. `extension.js` is the extension.
+- **Webview UI**: Full HTML/CSS/JS UI rendered inside VS Code's webview API — not a tree view or quick pick.
+- **Multi-provider**: Provider abstraction supports Anthropic, OpenAI, Groq, and Ollama with a single chat interface.
+- **Offline voice**: TTS via local Kokoro engine (no cloud API calls for speech).
+- **Zero telemetry**: No analytics, no tracking, no phone-home. Conversations stay on the server.
+
+## Runs On
+
+- **Alfred IDE** (cloud): code-server 4.x on Linux — primary target
+- **Alfred IDE** (desktop): Windows portable build
+- **VS Code**: Compatible with stock VS Code (some features require Alfred infrastructure)
+
+## License
+
+AGPL-3.0