boten-gemma 0.1.0

package/README.md

@@ -0,0 +1,860 @@
+# Gemma
+
+A confirmation-first personal AI assistant. Gemma is a single-process Node.js gateway that connects messaging channels (Web, Telegram, CLI) to an LLM with tool access. The core invariant: **no tool executes without user approval**.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+- [Channels](#channels)
+- [LLM Providers](#llm-providers)
+- [Authentication](#authentication)
+- [Tools](#tools)
+- [Confirmation Gate](#confirmation-gate)
+- [Skills](#skills)
+- [Panels](#panels)
+- [Automation](#automation)
+- [Web UI](#web-ui)
+- [WebSocket Protocol](#websocket-protocol)
+- [Deployment](#deployment)
+- [Project Structure](#project-structure)
+
+---
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Interactive first-run setup (auth, channels, directories)
+npx gemma setup
+
+# Or configure manually and start
+npx gemma start
+
+# Development
+npm run dev        # Server with tsx (auto-restart)
+npm run dev:ui     # Vite dev server on :5173 with HMR
+npm run build      # Full production build (server + UI)
+```
+
+### Prerequisites
+
+- **Node.js 22+** (uses built-in `.env` loading, ES2023 features)
+- A Gemini API key or Google OAuth credentials
+- Optional: Brave Search API key for web search
+
+### First Run
+
+On first launch, Gemma runs an interactive setup wizard:
+
+1. **Auth** -- Choose OAuth (browser flow), API key, or skip
+2. **Channels** -- Enable Telegram (with bot token), Web UI (with optional password)
+3. **Setup** -- Creates `~/.gemma/` directory structure, writes `gemma.json`, copies workspace templates
+
+After setup, Gemma starts on `http://localhost:18789`.
+
+---
+
+## Architecture
+
+Gemma is a **single-process gateway** that orchestrates messaging channels, an LLM, and tool execution through a mandatory confirmation gate.
+
+### Message Flow
+
+```
+Channel (Web / Telegram / CLI)
+  -> Gateway.handleMessage()
+    -> Session resolution (per channel+sender)
+    -> Agent loop (up to 25 iterations):
+        1. Auto-compact if context > 200k chars
+        2. Hard trim if context > 320k chars
+        3. Build system prompt (workspace files + skills + runtime)
+        4. LLM.generate() -- streaming async generator
+        5. Collect text + tool calls from stream
+        6. If text only -> send response, break
+        7. If tool calls -> ConfirmationGate.process()
+           -> Auto-approve check (internal reads only)
+           -> Present to user via channel
+           -> Execute approved tools
+        8. Feed tool results back to LLM
+        9. Continue loop
+    -> Send final response to channel
+```
+
+### Key Design Decisions
+
+- **Single import boundary**: `ConfirmationGate` is the _only_ module that imports the tool executor. The executor is never re-exported or accessible from any other path.
+- **Streaming-first**: Both LLM providers are async generators. No buffered mode.
+- **Error-as-text**: When all LLM retries are exhausted, errors are yielded as text chunks rather than thrown, keeping the conversation alive.
+- **Session serialization**: Each session allows only one concurrent agent loop run via a `running` flag.
+
+---
+
+## Configuration
+
+Gemma loads config from `gemma.json`, searched in order: current directory, then `~/.gemma/`.
+
+- **JSON5** comments and trailing commas supported
+- **`${ENV_VAR}`** expansion in string values
+- **`~`** expands to home directory
+- Full **Zod validation** with sensible defaults
+
+### Complete Reference
+
+#### Model
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `model.provider` | `'gemini' \| 'openai-compat'` | `'gemini'` | LLM provider |
+| `model.model` | `string` | `'gemini-2.5-flash'` | Default model name |
+| `model.fallbackModel` | `string?` | -- | Fallback model when primary is at capacity |
+| `model.auth` | `'oauth' \| 'api-key' \| 'adc'` | auto-detected | Force a specific auth mode |
+| `model.apiKey` | `string?` | -- | Gemini API key (or use `GEMINI_API_KEY` env) |
+| `model.oauth.clientId` | `string?` | -- | Custom OAuth client ID |
+| `model.oauth.clientSecret` | `string?` | -- | Custom OAuth client secret |
+| `model.openaiCompat.baseUrl` | `string` | `http://localhost:11434/v1` | OpenAI-compatible server URL |
+| `model.openaiCompat.model` | `string` | `llama3.2` | Model name for OpenAI-compat |
+
+#### Gateway
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `gateway.port` | `number` | `18789` | HTTP/WS port (env: `GEMMA_PORT`) |
+| `gateway.bind` | `string` | `'127.0.0.1'` | Bind address (env: `GEMMA_BIND`) |
+| `gateway.auth.token` | `string?` | -- | Optional password for WebSocket auth |
+
+#### Channels
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `channels.web.enabled` | `boolean` | `true` | Enable Web UI + WebSocket |
+| `channels.telegram.enabled` | `boolean` | `false` | Enable Telegram bot |
+| `channels.telegram.token` | `string?` | -- | Bot token (or `TELEGRAM_BOT_TOKEN` env) |
+| `channels.telegram.webhookUrl` | `string?` | -- | Webhook URL (omit for polling mode) |
+| `channels.telegram.allowFrom` | `number[]` | `[]` | Allowed Telegram user IDs (empty = all) |
+| `channels.cli.enabled` | `boolean` | `false` | Enable CLI channel |
+
+#### Confirmation
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `confirm.timeout` | `number` | `300` | Confirmation timeout in seconds |
+| `confirm.autoApprove.internalReads` | `boolean` | `true` | Auto-approve reads inside `~/.gemma/` |
+| `confirm.autoApprove.memoryWrites` | `boolean` | `false` | Auto-approve writes to MEMORY.md |
+
+#### Agent Loop
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `agent.maxIterations` | `number` | `25` | Max tool-call rounds per request (1-100) |
+| `agent.compactionThreshold` | `number` | `200000` | Auto-compact above this char count |
+| `agent.maxContextChars` | `number` | `320000` | Hard trim above this char count |
+| `agent.maxToolResultChars` | `number` | `30000` | Truncate individual tool results |
+
+#### Tools
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `tools.exec.timeout` | `number` | `30` | Shell command timeout (seconds) |
+| `tools.exec.shell` | `string` | `'/bin/bash'` | Shell for exec tool |
+| `tools.webSearch.provider` | `string` | `'brave'` | Web search provider |
+| `tools.webSearch.apiKey` | `string?` | -- | Brave Search API key (or `BRAVE_SEARCH_API_KEY` env) |
+
+#### Panels
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `panels.enabled` | `boolean` | `true` | Enable panel system |
+| `panels.dir` | `string` | `'~/.gemma/panels'` | Panels directory |
+| `panels.maxDataSize` | `number` | `5242880` | Max data storage per panel (bytes) |
+| `panels.disabled` | `string[]` | `[]` | Panel names to disable |
+| `panels.devMode` | `boolean` | `false` | Proxy to panel dev servers |
+| `panels.serviceTimeout` | `number` | `30000` | Service start/stop/RPC timeout (ms) |
+
+#### Automation
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `heartbeat.enabled` | `boolean` | `true` | Enable periodic heartbeat |
+| `heartbeat.intervalMinutes` | `number` | `30` | Heartbeat interval |
+| `heartbeat.prompt` | `string` | `'Read HEARTBEAT.md...'` | Prompt sent to agent |
+| `cron.enabled` | `boolean` | `true` | Enable cron system |
+| `cron.store` | `string` | `'~/.gemma/cron/jobs.json'` | Job persistence path |
+
+#### Skills
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `skills.dirs` | `string[]` | `[]` | Extra skill directories |
+| `skills.entries` | `Record` | `{}` | Per-skill configuration |
+
+#### MCP
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `mcp.servers` | `Record<string, MCPServer>` | `{}` | Named MCP server configs |
+
+Each MCP server: `{ command, args?, env?, enabled? }`
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `GEMMA_HOME` | Override home directory (default: `~/.gemma`) |
+| `GEMMA_PORT` | Override gateway port |
+| `GEMMA_BIND` | Override bind address |
+| `GEMINI_API_KEY` | Gemini API key |
+| `BRAVE_SEARCH_API_KEY` | Brave Search API key |
+| `TELEGRAM_BOT_TOKEN` | Telegram bot token |
+| `GEMMA_OAUTH_CLIENT_ID` | Custom OAuth client ID |
+| `GEMMA_OAUTH_CLIENT_SECRET` | Custom OAuth client secret |
+
+### Example `gemma.json`
+
+```json5
+{
+  // Use Gemini 3 Flash with 2.5 Flash as fallback
+  "model": {
+    "model": "gemini-3-flash-preview",
+    "fallbackModel": "gemini-2.5-flash"
+  },
+  "gateway": {
+    "port": 18789,
+    "bind": "0.0.0.0",
+    "auth": { "token": "my-secret" }
+  },
+  "channels": {
+    "web": { "enabled": true },
+    "telegram": {
+      "enabled": true,
+      "token": "${TELEGRAM_BOT_TOKEN}",
+      "allowFrom": [123456789]
+    }
+  },
+  "confirm": {
+    "autoApprove": {
+      "internalReads": true,
+      "memoryWrites": true
+    }
+  },
+  "mcp": {
+    "servers": {
+      "filesystem": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
+      }
+    }
+  }
+}
+```
+
+---
+
+## Channels
+
+### Web (default)
+
+HTTP server + WebSocket on the configured port. Serves:
+- React SPA at `/`
+- Panel files at `/panels/:name/*`
+- Panel SDK at `/panels/_sdk/gemma-panel.js`
+- Panel API at `/api/panels`
+- Health check at `/health`
+- Telegram webhook at `/webhook/telegram`
+
+WebSocket at `/ws` handles all real-time communication (chat, streaming, confirmations, config, sessions, cron, logs, panels). Optional token auth via `gateway.auth.token`.
+
+### Telegram
+
+Uses [grammY](https://grammy.dev/) framework. Supports:
+- **Polling mode** (default): Standalone long-polling
+- **Webhook mode**: Routes through the web channel's HTTP server
+- **Inline keyboard confirmations**: Approve All / Select Individual / Reject All
+- **Streaming**: Edits message in-place every second with accumulated text
+- **Access control**: `allowFrom` whitelist of Telegram user IDs
+
+### CLI
+
+Readline-based interface for local development. Color-coded output via chalk. Confirmations via text input (`y`/`n`/comma-separated indices).
+
+---
+
+## LLM Providers
+
+### Gemini (default)
+
+Two API endpoints depending on auth mode:
+
+| Auth Mode | Endpoint | URL |
+|-----------|----------|-----|
+| API key | Standard Gemini API | `generativelanguage.googleapis.com/v1beta` |
+| OAuth | Code Assist proxy | `cloudcode-pa.googleapis.com/v1internal` |
+| ADC | Standard Gemini API | Same as API key |
+
+**Features:**
+- SSE streaming with async generator interface
+- Thinking/reasoning mode (`thinkingBudget: 8192` tokens)
+- `thoughtSignature` propagation on tool calls
+- Retry logic: 5 retries, exponential backoff (1s base, 5s for capacity exhaustion), 60s max delay
+- Fallback model: automatically tries a configured fallback on `MODEL_CAPACITY_EXHAUSTED`
+- Respects `Retry-After` headers
+
+**Available models:** `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.0-flash`, `gemini-2.0-flash-lite`
+
+### OpenAI-Compatible
+
+For local/self-hosted LLMs: **Ollama**, **LM Studio**, **vLLM**, etc.
+
+```json5
+{
+  "model": {
+    "provider": "openai-compat",
+    "openaiCompat": {
+      "baseUrl": "http://localhost:11434/v1",
+      "model": "llama3.2"
+    }
+  }
+}
+```
+
+Uses standard `/chat/completions` with streaming. No retry logic or fallback model support.
+
+---
+
+## Authentication
+
+Three modes, auto-detected in priority order:
+
+### 1. OAuth (recommended)
+
+```bash
+gemma auth --google
+```
+
+Opens a browser for Google OAuth consent. Tokens cached at `~/.gemma/auth/tokens.json` (chmod 600) with automatic refresh 5 minutes before expiry.
+
+OAuth credentials are borrowed from the installed [Gemini CLI](https://github.com/anthropics/gemini-cli) (`@google/gemini-cli-core`). Falls back to `GEMMA_OAUTH_CLIENT_ID`/`GEMMA_OAUTH_CLIENT_SECRET` env vars or config.
+
+Supports headless environments (SSH, CI) -- prints URL for user to open on any device.
+
+### 2. API Key
+
+```bash
+export GEMINI_API_KEY="your-key-here"
+# or in gemma.json:
+# "model": { "apiKey": "your-key" }
+```
+
+### 3. Application Default Credentials (ADC)
+
+For GCP environments. Uses `google-auth-library` with `cloud-platform` scope. Auto-detected when no OAuth tokens or API key are available.
+
+### Auth Commands
+
+```bash
+gemma auth --status    # Show current auth mode and email
+gemma auth --google    # Run OAuth flow
+gemma auth --api-key   # Set API key
+gemma auth --logout    # Revoke tokens and delete
+```
+
+---
+
+## Tools
+
+8 built-in tools, all going through the confirmation gate:
+
+### `read`
+Read file contents with optional line range.
+- **Params**: `path` (required), `startLine?`, `endLine?` (1-based)
+- Returns numbered lines with metadata
+
+### `write`
+Write content to a file, creating parent directories as needed.
+- **Params**: `path` (required), `content` (required)
+
+### `edit`
+Find-and-replace a unique string in a file.
+- **Params**: `path` (required), `old_string` (required), `new_string` (required)
+- Rejects if old_string appears 0 or 2+ times
+
+### `exec`
+Execute a shell command.
+- **Params**: `command` (required), `timeout?` (default 30s)
+- Returns stdout, stderr, exit code. SIGTERM then SIGKILL on timeout.
+
+### `web_search`
+Search the web via Brave Search API.
+- **Params**: `query` (required), `count?` (max 20, default 5)
+- Requires `BRAVE_SEARCH_API_KEY` or config
+
+### `web_fetch`
+Fetch a URL and convert HTML to markdown.
+- **Params**: `url` (required), `maxLength?` (default 50000)
+
+### `cron`
+Manage scheduled jobs (list, add, update, remove, enable, disable, run).
+- Schedule formats: cron expressions (`0 9 * * 1-5`), intervals (`every:30m`), one-shots (`at:2024-03-15T09:00:00Z`)
+
+### `create_panel`
+Scaffold, update, remove, list, or rebuild UI panels.
+- Templates: `html` (custom HTML) or `react` (React 18 + Vite + TypeScript)
+- Optional backend service with RPC and event support
+
+### MCP Tools
+
+External tools from MCP servers are discovered at startup and registered as `mcp__<server>__<tool>`. They go through the same confirmation gate as built-in tools. MCP servers can be hot-reloaded via the Settings UI.
+
+---
+
+## Confirmation Gate
+
+The security boundary. Every tool call passes through the gate before execution.
+
+### Auto-Approve Rules
+
+| Condition | Auto-approved? | Default |
+|-----------|---------------|---------|
+| `read` tool targeting paths inside `~/.gemma/` | Yes | `internalReads: true` |
+| `read` tool targeting `HEARTBEAT.md` | Yes | Always |
+| `write`/`edit` to `MEMORY.md` or `memory/*.md` | Configurable | `memoryWrites: false` |
+| Everything else | No | Requires confirmation |
+
+### Cowboy Mode
+
+Per-session toggle that bypasses ALL confirmations. Enabled via the shield toggle in the Web UI. Use with caution.
+
+### Audit Log
+
+Every confirmation cycle is logged to `~/.gemma/logs/audit.jsonl`:
+```json
+{
+  "timestamp": "2024-03-15T09:00:00.000Z",
+  "session": "s-abc123-xyz",
+  "proposed": [{"tool": "exec", "args": {"command": "ls"}}],
+  "approved": [0],
+  "rejected": [],
+  "auto_approved": [],
+  "user_response_time_ms": 2100
+}
+```
+
+---
+
+## Skills
+
+Skills are `SKILL.md` files with YAML frontmatter that provide domain-specific instructions to the agent.
+
+### Format
+
+```markdown
+---
+name: my-skill
+description: What this skill does
+metadata:
+  requires:
+    bins: [docker]           # Required binaries on PATH
+    env: [DOCKER_HOST]       # Required environment variables
+---
+# Instructions for the agent
+Detailed instructions here...
+```
+
+### Loading Order (later overrides earlier)
+
+1. `./skills/` -- Bundled with Gemma
+2. `~/.gemma/workspace/skills/` -- User workspace
+3. Config `skills.dirs` entries -- Custom directories
+
+### Bundled Skills (5)
+
+| Skill | Description |
+|-------|-------------|
+| `web-research` | Search the web and extract content from URLs |
+| `file-ops` | Read, write, and edit files on the local filesystem |
+| `coding` | Writing, debugging, reviewing, and explaining code |
+| `system-admin` | Execute system commands and manage servers |
+| `panel-development` | Guide for creating Gemma panels with backend services |
+
+Skills are gated by their `requires` field -- unavailable skills (missing binaries/env vars) are excluded from the system prompt.
+
+---
+
+## Panels
+
+Panels are mini web apps that extend Gemma's UI. They run in sandboxed iframes and communicate via a client SDK and optional backend services.
+
+### Display Modes
+
+- **Tab** -- Full-width content area, shown as a nav item in the sidebar
+- **Sidebar** -- Compact widget at the bottom of the sidebar (max 300px height)
+
+### Creating a Panel
+
+The LLM can scaffold panels via the `create_panel` tool, or you can create one manually:
+
+```
+~/.gemma/panels/my-panel/
+  panel.json       # Manifest (required)
+  index.html       # Entry point
+  dist/            # Build output (for React panels)
+  data/            # Scoped data directory (runtime)
+  service.ts       # Backend service (optional)
+```
+
+### Manifest (`panel.json`)
+
+```json
+{
+  "name": "my-panel",
+  "title": "My Panel",
+  "version": "1.0.0",
+  "entry": "index.html",
+  "display": "tab",
+  "icon": "puzzle",
+  "permissions": ["send:chat", "read:data", "write:data"],
+  "service": "service.js"
+}
+```
+
+**Permissions**: `send:chat`, `read:data`, `write:data`, `read:memory`, `listen:chat`
+
+### Client SDK
+
+Auto-injected into panel HTML. Provides:
+
+```javascript
+const panel = new GemmaPanel();
+
+// Data storage (scoped per panel)
+await panel.readData('key');
+await panel.writeData('key', value);
+
+// Chat integration
+panel.sendChat('Hello from my panel');
+panel.onMessage(msg => console.log(msg));
+
+// Backend RPC
+const result = await panel.callBackend('myMethod', { param: 'value' });
+panel.onEvent('update', data => console.log(data));
+
+// Theme
+const theme = await panel.getTheme(); // { isDark, variables }
+
+// Notifications
+panel.notify('Something happened', 'info');
+```
+
+### Backend Services
+
+Optional server-side logic for panels. Export `start`, `onRpc`, and `stop`:
+
+```typescript
+import type { PanelServiceContext } from './gemma-panel.js';
+
+export async function start(ctx: PanelServiceContext) {
+  ctx.emit('ready', { status: 'initialized' });
+  ctx.schedule('refresh', 60000, () => { /* periodic work */ });
+  ctx.registerTool({ name: 'my_tool', description: '...', parameters: {...},
+    execute: async (args) => ({ content: 'result' }) });
+}
+
+export async function onRpc(method: string, params: unknown, ctx: PanelServiceContext) {
+  if (method === 'getData') return { items: [] };
+  throw new Error(`Unknown method: ${method}`);
+}
+
+export async function stop() { /* cleanup */ }
+```
+
+---
+
+## Automation
+
+### Heartbeat
+
+Periodic wake-up that prompts the agent on a timer (default: every 30 minutes).
+
+The agent reads `HEARTBEAT.md` from the workspace and acts on standing instructions. If nothing needs attention, it replies `HEARTBEAT_OK`. Runs in the most recently active web session.
+
+### Cron
+
+Full-featured scheduled job system.
+
+**Schedule formats:**
+- Cron expression: `0 9 * * 1-5` (9 AM weekdays)
+- Interval: `every:30m`, `every:2h`, `every:1d`
+- One-shot: `at:2024-03-15T09:00:00Z`
+
+**Key behaviors:**
+- Jobs persist to `~/.gemma/cron/jobs.json`
+- Each job runs in an isolated session (or shared `main` session)
+- Cron jobs **bypass the confirmation gate** -- they are pre-authorized
+- Consecutive errors are tracked per job
+- Jobs can be managed via the `cron` tool, Web UI, or WebSocket API
+
+---
+
+## Web UI
+
+React 18 single-page application with Tailwind CSS 3 and shadcn/ui.
+
+### Views
+
+| View | Description |
+|------|-------------|
+| **Chat** | Conversation interface with streaming markdown, thinking display, inline tool confirmations, cowboy mode toggle |
+| **Settings** | MCP server management, model/fallback selection, agent loop tuning, API keys, auth status |
+| **Cron** | Create/edit/delete scheduled jobs with friendly schedule picker |
+| **Logs** | Real-time log viewer with level/source filtering and auto-scroll |
+| **Panel Manager** | List installed panels, enable/disable, view errors |
+| **Panel tabs** | Full-width iframe hosting for tab-display panels |
+
+### Chat Features
+
+- **Streaming markdown** with syntax-highlighted code blocks (Shiki)
+- **Thinking/reasoning display** -- collapsible with duration counter
+- **Inline confirmations** -- approve/reject individual or all tool calls with risk indicators
+- **Tool result cards** -- collapsible with status and preview
+- **Per-session model override** and thinking toggle
+- **Cowboy mode** -- shield toggle with confirmation dialog
+- **Session management** -- sidebar with create, switch, rename, delete
+
+### Development
+
+```bash
+npm run dev:ui   # Vite on :5173, proxies /ws, /api, /panels to gateway on :18789
+```
+
+---
+
+## WebSocket Protocol
+
+38 message types over a single WebSocket connection at `/ws`.
+
+### Core Chat
+
+| Type | Direction | Description |
+|------|-----------|-------------|
+| `chat` | Both | User message or assistant reply |
+| `stream` | S->C | Streaming response chunk (`done: true` signals end) |
+| `thinking` | S->C | LLM reasoning chunk |
+| `confirmation` | S->C | Present tool calls with risk assessment |
+| `confirmation_response` | C->S | User approval/rejection by call IDs |
+| `tool_results` | S->C | Tool execution results |
+
+### Session Management
+
+| Type | Direction | Description |
+|------|-----------|-------------|
+| `session:resume` | C->S | Resume session on connect |
+| `session:list` / `session:list:response` | Both | List all sessions |
+| `session:new` / `session:switch` / `session:delete` / `session:rename` | C->S | CRUD operations |
+| `session:restored` | S->C | Full session data with history |
+| `session:event` | S->C | Session CRUD notifications |
+
+### Config, Cron, Logs, Panels
+
+Full CRUD over WebSocket for config management, MCP servers, cron jobs, log streaming, and panel bridge (data read/write, RPC, events).
+
+See `src/shared/ws-types.ts` for the complete type definitions.
+
+---
+
+## Deployment
+
+### Docker
+
+```bash
+# Build
+docker build -f docker/Dockerfile -t gemma .
+
+# Run with persistent state
+docker run -d \
+  -p 18789:18789 \
+  -v gemma-data:/home/node/.gemma \
+  -e GEMINI_API_KEY=your-key \
+  -e GEMMA_BIND=0.0.0.0 \
+  gemma
+```
+
+The Docker image:
+- Two-stage build (Node 22 -> Node 22 Alpine)
+- Installs Gemini CLI globally for OAuth credential extraction
+- Runs as non-root `node` user
+- Exposes port 18789
+- Persists all state in `/home/node/.gemma` volume
+
+### Docker Compose
+
+A `docker-compose.yml` with Caddy reverse proxy is included:
+
+```bash
+cd docker
+cp .env.example .env   # Edit with your API keys
+docker compose up -d
+```
+
+This sets up Gemma behind Caddy for automatic HTTPS. Edit the `Caddyfile` for your domain.
+
+### VPS / Bare Metal
+
+```bash
+npm install
+npm run build
+npx gemma start
+```
+
+Use a process manager (systemd, PM2) for production. Set `GEMMA_BIND=0.0.0.0` to listen on all interfaces. Use a reverse proxy (nginx, Caddy) for TLS.
+
+---
+
+## Project Structure
+
+```
+gemma/
+  src/
+    index.ts                    # CLI entry point, auth commands, setup wizard
+    gateway.ts                  # Main Gateway class, agent loop, lifecycle
+    config/
+      schema.ts                 # Zod config schema (all options)
+      loader.ts                 # JSON5 loading, env expansion, tilde expansion
+      defaults.ts               # Default values
+    core/
+      session.ts                # Session interface and creation
+      session-store.ts          # File-based session persistence (JSONL)
+      compaction.ts             # LLM-powered context summarization
+      logger.ts                 # Structured logger with ring buffer
+    llm/
+      types.ts                  # LLMProvider interface, Message, ToolCall types
+      gemini.ts                 # Gemini provider (dual endpoint, retry, fallback)
+      openai-compat.ts          # OpenAI-compatible provider
+      auth/
+        resolver.ts             # Auth mode detection and initialization
+        oauth.ts                # OAuth flow (desktop + headless)
+        oauth-callback.ts       # Local callback server for OAuth
+        token-store.ts          # Token persistence and auto-refresh
+        types.ts                # Auth types
+    channels/
+      types.ts                  # Channel interface
+      web.ts                    # HTTP server + WebSocket (700+ lines)
+      telegram.ts               # grammY bot with inline keyboards
+      cli.ts                    # Readline interface
+    confirm/
+      gate.ts                   # Confirmation gate (security boundary)
+      auto-approve.ts           # Auto-approve rule engine
+      audit.ts                  # JSONL audit logging
+    tools/
+      types.ts                  # Tool/ToolHandler interfaces, ToolContext
+      registry.ts               # Tool registry with registerBuiltins()
+      executor.ts               # Tool executor (only imported by gate.ts)
+      builtin/
+        read.ts, write.ts, edit.ts, exec.ts
+        web-search.ts, web-fetch.ts
+        cron.ts, panel.ts
+    mcp/
+      manager.ts                # MCP server lifecycle management
+      adapter.ts                # MCP tool -> Gemma tool adapter
+    skills/
+      loader.ts                 # SKILL.md discovery and parsing
+      gating.ts                 # Binary/env requirement checking
+      prompt-injector.ts        # Skill list -> system prompt XML
+    panels/
+      registry.ts               # Panel discovery and validation
+      routes.ts                 # HTTP routes for panel serving
+      types.ts                  # Panel manifest and service types
+      service-manager.ts        # Panel service lifecycle
+      service-loader.ts         # Dynamic ESM import with hot-reload
+      service-context.ts        # Scoped context builder for services
+      sdk/
+        gemma-panel.js          # Client-side panel SDK
+    automation/
+      heartbeat.ts              # Periodic agent prompt timer
+      cron/
+        service.ts              # CronService orchestrator
+        types.ts                # Job, schedule, event types
+        schedule.ts             # Next-run computation
+        parse-schedule.ts       # Human-friendly schedule parsing
+        store.ts                # JSON persistence
+    memory/
+      memory-manager.ts         # Workspace file loading by scope
+      daily-log.ts              # Daily log file management
+    shared/
+      ws-types.ts               # WebSocket protocol types (38 message types)
+    ui/                         # React SPA (separate build via Vite)
+      main.tsx                  # React entry
+      App.tsx                   # Root component
+      components/
+        AppShell.tsx            # Layout shell (sidebar + content + statusbar)
+        Sidebar.tsx             # Navigation + session list + panel widgets
+        StatusBar.tsx           # Connection, model, cowboy mode indicators
+        views/                  # ChatView, SettingsView, CronView, LogsView, PanelManagerView
+        ai/                     # Conversation, MessageResponse, Reasoning, Shimmer, CodeBlock
+        chat/                   # ConfirmationCard, ToolCallCard, ToolResultBadge
+        panels/                 # PanelHost (tab), PanelSidebarSlot (sidebar)
+        settings/               # MCPServerCard, MCPServerForm
+        cron/                   # CronJobCard, CronJobForm
+        ui/                     # 19 shadcn/ui primitives
+      hooks/
+        useGateway.ts           # Central WS hub (chat, streaming, sessions, model)
+        useConfig.ts            # Config CRUD over WS
+        useSessions.ts          # Session list management
+        usePanels.ts            # Panel manifest fetching
+        useCron.ts              # Cron job management
+        useLogs.ts              # Log streaming
+        usePanelBridge.ts       # iframe <-> WS bridge for panels
+        usePanelThemeBridge.ts  # Theme sync to panel iframes
+  skills/                       # Bundled skill definitions (SKILL.md files)
+  templates/
+    panel/                      # HTML panel template
+    panel-react/                # React panel template (React 18 + Vite + TS)
+    *.md                        # Workspace templates (SOUL, INSTRUCTIONS, IDENTITY, etc.)
+  docker/
+    Dockerfile                  # Two-stage production build
+```
+
+### NPM Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Full build: TypeScript server + Vite React UI |
+| `npm run build:server` | Server only: `tsc` -> `dist/` |
+| `npm run build:ui` | UI only: `vite build` -> `dist/ui/` |
+| `npm run dev` | Dev server: `tsx src/index.ts` |
+| `npm run dev:ui` | UI dev server: Vite on :5173 with HMR |
+
+### TypeScript Conventions
+
+- **ESM only** (`"type": "module"`)
+- All imports use `.js` extensions: `import { X } from './file.js'`
+- Node imports use `node:` prefix: `import { readFile } from 'node:fs/promises'`
+- Type-only imports: `import type { X } from './types.js'`
+- Target: ES2023, Module: Node16, Strict mode
+- Path alias: `@gemma/*` -> `./src/*` (server), `@/*` -> `./src/ui/*` (UI)
+
+---
+
+## Workspace Files
+
+On first run, these template files are copied to `~/.gemma/workspace/`:
+
+| File | Purpose |
+|------|---------|
+| `SOUL.md` | Personality and behavioral guidelines |
+| `INSTRUCTIONS.md` | Operating rules and constraints |
+| `IDENTITY.md` | Name, role, tone configuration |
+| `USER.md` | User profile and preferences |
+| `TOOLS.md` | Tool usage notes |
+| `MEMORY.md` | Curated long-term memory |
+| `BOOTSTRAP.md` | First-run welcome (deleted after first session) |
+
+These files are loaded into the system prompt on every LLM call. Edit them to customize Gemma's behavior.
+
+---
+
+## License
+
+[Add license here]