Update documentation and configuration for production deployment

- Fix documentation drift across README, AGENTS.md, and CONTRIBUTING.md
- Update Docker configuration with process timing and OAuth env vars
- Simplify shared env config by removing unused Redis and OpenCode API URL
- Add skills documentation to navigation
- Improve .env.example with clearer AUTH_SECRET instructions

Author: chriswritescode-dev

.env.example

@@ -59,9 +59,8 @@ DEBUG=false
 # ============================================
 # Authentication (Better Auth)
 # ============================================
-# AUTH_SECRET is required for production deployments
-# Generate with: openssl rand -base64 32
-# AUTH_SECRET=your-secure-random-secret-here
+# AUTH_SECRET is required - generate with: openssl rand -base64 32
+AUTH_SECRET=CHANGE_ME_GENERATE_WITH_openssl_rand_base64_32
 
 # Trusted origins for authentication (comma-separated)
 # Add your server's external URL when accessing remotely
@@ -120,6 +119,7 @@ PASSKEY_ORIGIN=http://localhost:5003
 # These are optional - frontend uses defaults if not set
 # ============================================
 # VITE_API_URL=http://localhost:5003
+# VITE_SERVER_PORT=5003
 # VITE_OPENCODE_PORT=5551
 # VITE_MAX_FILE_SIZE_MB=50
 # VITE_MAX_UPLOAD_SIZE_MB=50

.github/copilot-instructions.md

@@ -3,7 +3,7 @@
 ## Technology Stack
 
 - **Monorepo**: pnpm workspace with backend, frontend, and shared packages
-- **Backend**: Bun runtime + Hono framework + Better SQLite3
+- **Backend**: Bun runtime + Hono framework + Bun SQLite (bun:sqlite)
 - **Frontend**: React 19 + Vite 7 + Radix UI + Tailwind CSS 4
 - **Validation**: Zod schemas throughout
 - **State**: React Query + Zustand

AGENTS.md

@@ -3,11 +3,11 @@
 ## Commands
 
 - `pnpm dev` - Start both backend (5003) and frontend (5173)
-- `pnpm dev:backend` - Backend only: `bun --watch backend/src/index.ts`
-- `pnpm dev:frontend` - Frontend only: `cd frontend && vite`
+- `pnpm dev:backend` - Backend only: `bun --watch-path backend/src --watch backend/src/index.ts`
+- `pnpm dev:frontend` - Frontend only: `pnpm --filter frontend dev`
 - `pnpm build` - Build both backend and frontend
-- `pnpm test` - Run backend tests: `cd backend && bun test`
-- `cd backend && bun test <filename>` - Run single test file
+- `pnpm test` - Run backend tests: `pnpm --filter backend test` (vitest)
+- `cd backend && vitest <filename>` - Run single test file
 - `cd backend && vitest --ui` - Test UI with coverage
 - `cd backend && vitest --coverage` - Coverage report (80% threshold)
 - `pnpm lint` - Lint both backend and frontend
@@ -23,7 +23,7 @@
 
 ### Backend (Bun + Hono)
 
-- Hono framework with Zod validation, Better SQLite3 database
+- Hono framework with Zod validation, Bun SQLite (bun:sqlite) database
 - Error handling with try/catch and structured logging
 - Follow existing route/service/utility structure
 - Use async/await consistently, avoid .then() chains

CONTRIBUTING.md

@@ -7,7 +7,7 @@ Thanks for your interest in contributing! This guide covers our workflow and how
 1. Fork the repository
 2. Clone your fork locally
 
-See the [README](README.md#option-2-local-development-contributors) for detailed setup instructions.
+See the [Development Setup Guide](docs/development/setup.md) for detailed setup instructions.
 
 ## Project Board Workflow
 
@@ -58,7 +58,7 @@ Each item is tagged with a theme to help you find work in your area of interest:
 ### Backend (Bun + Hono)
 
 - Hono framework with Zod validation
-- Better SQLite3 for database
+- Bun SQLite (bun:sqlite) for database
 - Proper error handling with try/catch
 - Use async/await consistently
 
@@ -73,7 +73,7 @@ Each item is tagged with a theme to help you find work in your area of interest:
 
 ```bash
 pnpm test              # Run all backend tests
-cd backend && bun test <filename>  # Run single test file
+cd backend && vitest <filename>   # Run single test file
 ```
 
 ### Linting

README.md

@@ -32,6 +32,7 @@
 git clone https://github.com/chriswritescode-dev/opencode-manager.git
 cd opencode-manager
 cp .env.example .env
+echo "AUTH_SECRET=$(openssl rand -base64 32)" >> .env
 docker-compose up -d
 # Open http://localhost:5003
 ```

docs/configuration/docker.md

@@ -37,30 +37,40 @@ services:
       dockerfile: Dockerfile
     container_name: opencode-manager
     ports:
-      - "5003:5003"      # OpenCode Manager
-      - "5100:5100"      # Dev server 1
-      - "5101:5101"      # Dev server 2
-      - "5102:5102"      # Dev server 3
-      - "5103:5103"      # Dev server 4
+      - "5003:5003"
+      - "5100:5100"
+      - "5101:5101"
+      - "5102:5102"
+      - "5103:5103"
     environment:
       - NODE_ENV=${NODE_ENV:-production}
       - HOST=0.0.0.0
       - PORT=5003
       - OPENCODE_SERVER_PORT=5551
       - DATABASE_PATH=/app/data/opencode.db
       - WORKSPACE_PATH=/workspace
+      - PROCESS_START_WAIT_MS=2000
+      - PROCESS_VERIFY_WAIT_MS=1000
+      - HEALTH_CHECK_INTERVAL_MS=5000
+      - HEALTH_CHECK_TIMEOUT_MS=30000
+      - MAX_FILE_SIZE_MB=50
+      - MAX_UPLOAD_SIZE_MB=50
+      - DEBUG=false
       - AUTH_SECRET=${AUTH_SECRET}
       - AUTH_TRUSTED_ORIGINS=${AUTH_TRUSTED_ORIGINS:-http://localhost:5003}
       - ADMIN_EMAIL=${ADMIN_EMAIL:-}
       - ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
-      # OAuth providers (optional)
+      - ADMIN_PASSWORD_RESET=${ADMIN_PASSWORD_RESET:-false}
       - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID:-}
       - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET:-}
-      # Passkeys (optional)
+      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID:-}
+      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET:-}
+      - DISCORD_CLIENT_ID=${DISCORD_CLIENT_ID:-}
+      - DISCORD_CLIENT_SECRET=${DISCORD_CLIENT_SECRET:-}
+      - AUTH_SECURE_COOKIES=${AUTH_SECURE_COOKIES:-false}
       - PASSKEY_RP_ID=${PASSKEY_RP_ID:-localhost}
       - PASSKEY_RP_NAME=${PASSKEY_RP_NAME:-OpenCode Manager}
       - PASSKEY_ORIGIN=${PASSKEY_ORIGIN:-http://localhost:5003}
-      # Push notifications (optional)
       - VAPID_PUBLIC_KEY=${VAPID_PUBLIC_KEY:-}
       - VAPID_PRIVATE_KEY=${VAPID_PRIVATE_KEY:-}
       - VAPID_SUBJECT=${VAPID_SUBJECT:-}
@@ -112,8 +122,8 @@ VAPID_SUBJECT=mailto:you@example.com
 
 The container entrypoint (`scripts/docker-entrypoint.sh`) automatically:
 
-1. **Installs Bun** if not present
-2. **Installs OpenCode** if not present
+1. **Verifies Bun** is installed (installed at build time, fallback install if missing)
+2. **Verifies OpenCode** is installed (installed at build time, fallback install if missing)
 3. **Upgrades OpenCode** if below minimum version (1.0.137)
 4. **Validates AUTH_SECRET** is set (required for startup)
 5. **Validates memory plugin** installation

docs/development/setup.md

@@ -6,7 +6,7 @@ Guide for setting up a local development environment.
 
 - [pnpm](https://pnpm.io/installation) - Package manager (required for workspaces)
 - [Bun](https://bun.sh) - Backend runtime
-- [OpenCode TUI](https://opencode.ai) - `npm install -g @opencode/tui`
+- [OpenCode TUI](https://opencode.ai) - `curl -fsSL https://opencode.ai/install | bash`
 
 ## Installation
 

docs/features/memory.md

@@ -167,7 +167,7 @@ The plugin is composed of several subsystems that work together:
 
 ### Storage Layer
 
-The plugin uses a single SQLite database in WAL mode with four tables:
+The plugin uses a single SQLite database in WAL mode with three tables:
 
 | Table | Purpose |
 |-------|---------|
@@ -304,7 +304,7 @@ When deduplication triggers, the existing memory's ID is returned instead of cre
 
 ## Tools
 
-The plugin registers seventeen tools that the AI agent can call:
+The plugin registers twelve tools that the AI agent can call:
 
 ### memory-read
 
@@ -416,16 +416,6 @@ Retrieve a value by key for the current project.
 
 Returns the stored value (formatted as JSON if applicable) or a message indicating the key was not found.
 
-### memory-kv-delete
-
-Delete a key-value pair for the current project.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `key` | string | Yes | The key to delete |
-
-Returns confirmation that the key was deleted.
-
 ### memory-kv-list
 
 List all active key-value pairs for the current project.

docs/features/skills.md

@@ -0,0 +1,92 @@
+# Skills
+
+Skills are reusable instruction sets that provide domain-specific workflows and guidance to OpenCode AI agents. They are stored as `SKILL.md` files and can be scoped globally or per-project.
+
+## Scopes
+
+| Scope | Location | Description |
+|-------|----------|-------------|
+| **Global** | `<workspace>/.config/opencode/skills/<name>/SKILL.md` | Available across all repositories |
+| **Project** | `<repo>/.opencode/skills/<name>/SKILL.md` | Scoped to a specific repository |
+
+## Skill File Format
+
+Each skill is a `SKILL.md` file with YAML frontmatter and a markdown body:
+
+```markdown
+---
+name: my-skill
+description: Short description of what this skill does
+license: MIT
+compatibility: opencode >= 1.0
+metadata:
+  author: your-name
+  version: 1.0.0
+---
+Your skill instructions go here. This is the content that gets
+injected into the AI agent's context when the skill is loaded.
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Lowercase alphanumeric with hyphens (e.g., `my-skill`). Max 64 characters. |
+| `description` | Yes | What the skill does. Max 1024 characters. |
+| `license` | No | License identifier (e.g., `MIT`) |
+| `compatibility` | No | Version compatibility note |
+| `metadata` | No | Key-value pairs for additional context |
+
+### Naming Rules
+
+Skill names must match the pattern `^[a-z0-9]+(-[a-z0-9]+)*$`:
+
+- Lowercase letters and numbers only
+- Hyphens allowed between words
+- No spaces, underscores, or uppercase letters
+- Examples: `test-skill`, `code-review`, `deploy-helper`
+
+## Managing Skills
+
+Skills are managed through the Settings UI under the Skills section, or via the API.
+
+### API Endpoints
+
+All endpoints are under `/api/settings/skills`.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/skills` | List all skills (optional `?repoId=` filter) |
+| `GET` | `/skills/:name` | Get a specific skill (requires `scope` query param, optional `repoId`) |
+| `POST` | `/skills` | Create a new skill |
+| `PUT` | `/skills/:name` | Update an existing skill (requires `scope` query param, optional `repoId`) |
+| `DELETE` | `/skills/:name` | Delete a skill (requires `scope` query param, optional `repoId`) |
+
+### Create Request
+
+```json
+{
+  "name": "my-skill",
+  "description": "Runs type check and lint",
+  "body": "Instructions for the AI agent...",
+  "scope": "global",
+  "license": "MIT",
+  "compatibility": "opencode >= 1.0",
+  "metadata": { "author": "your-name" },
+  "repoId": 1
+}
+```
+
+`repoId` is required when `scope` is `"project"`.
+
+### Update Request
+
+All fields are optional. Set a field to `null` to clear it.
+
+```json
+{
+  "description": "Updated description",
+  "body": "Updated instructions",
+  "license": null
+}
+```

docs/index.md

@@ -10,6 +10,8 @@ Mobile-first web interface for [OpenCode](https://opencode.ai) AI agents. Manage
 ```bash
 git clone https://github.com/chriswritescode-dev/opencode-manager.git
 cd opencode-manager
+cp .env.example .env
+echo "AUTH_SECRET=$(openssl rand -base64 32)" >> .env
 docker-compose up -d
 ```