docs: update feature documentation and mkdocs config (#222)

Author: chriswritescode-dev

docs/features/ai-config.md

@@ -4,21 +4,41 @@ Configure AI models, providers, and custom agents.
 
 ## Model Selection
 
-Browse and select from available AI models:
+### Quick Model Switcher
 
-1. Click the **model selector** in the chat interface
-2. Browse available models
-3. Click a model to set it for the current session
+A compact model switcher is embedded directly in the chat interface. Click the **model name** in the prompt area or chat header to open the quick-select popover:
 
-### Changing Models Mid-Session
+| Item | Description |
+|------|-------------|
+| **Active model** | Shown at the top with a checkmark. Click the star icon to add or remove from favorites. |
+| **Favorites** | Pinned models always appear first in the list. |
+| **Recents** | Last 10 used models appear below favorites (excluding the active one and any favorites). |
+| **Variants** | Some models offer tier options (e.g., fast or pro). Variant items are highlighted and show a checkmark on the active selection. |
+| **All Models…** | Opens the full model browser when you need a model not in recents or favorites. |
+
+Model selections persist across page reloads.
+
+### Per-Agent Model Selection
+
+Each agent can use a different model independently:
+
+1. Select an agent in the chat session header
+2. Open the quick model switcher
+3. Choose a model — it is now stored for that agent
 
-You can switch models during a chat session:
+When you switch agents, the model you last used with that agent is restored automatically. Your global model selection is unaffected.
 
-1. Click the model name in the chat header
-2. Select a different model
-3. Continue chatting with the new model
+### Full Model Browser
+
+To browse all available models:
+
+1. Click **All Models…** in the quick-select popover
+2. Filter by provider or search by name
+3. Click a model to select it
+
+### Changing Models Mid-Session
 
-Context is preserved when switching models.
+You can switch models at any point during a session without losing context. The new model is used for all subsequent messages.
 
 ## Provider Credentials
 

docs/features/assistant-internal-api.md

@@ -2,6 +2,8 @@
 
 The Assistant Internal API provides capabilities for OpenCode agents to interact with the manager backend via a secure bearer-token API.
 
+> For a user-facing overview of how to use and set up assistant mode, see [Assistant Mode](assistant-mode.md).
+
 ## Authentication
 
 All endpoints require a bearer token. The token can be found at:
@@ -122,12 +124,46 @@ Returns the updated settings object.
 - `400`: Invalid request body or disallowed key
 - `401`: Missing or invalid bearer token
 
+### Repos
+
+**GET `/api/internal/repos`**
+
+Retrieve a list of all managed repositories, ordered by the user's repo preference order.
+
+**Response:**
+```ts
+{
+  repos: Array<{
+    id: number
+    repoUrl?: string              // Git remote URL (absent for local-only repos)
+    localPath: string             // Relative path under repos root
+    fullPath: string              // Absolute filesystem path
+    sourcePath?: string           // Source worktree path (for worktrees)
+    branch?: string               // Current branch name (for worktrees)
+    defaultBranch: string         // e.g. "main"
+    cloneStatus: 'cloning' | 'ready' | 'error'
+    clonedAt: number              // Timestamp when repo was cloned
+    lastPulled?: number           // Timestamp of last pull
+    lastAccessedAt?: number       // Timestamp of last access
+    openCodeConfigName?: string   // Associated OpenCode config name
+    isWorktree?: boolean          // Whether repo is a worktree
+    isLocal?: boolean             // Whether repo is local-only
+  }>
+}
+```
+
+**Status Codes:**
+- `200`: Repository list returned
+- `401`: Missing or invalid bearer token
+- `500`: Server error (database failure)
+
 ## Skills
 
-The assistant workspace includes three skills that document these capabilities:
+The assistant workspace includes four skills that document these capabilities:
 
 1. **Schedule Management** (`.opencode/skills/schedule-management/SKILL.md`)
 2. **Notifications** (`.opencode/skills/notifications/SKILL.md`)
 3. **Manager Settings** (`.opencode/skills/manager-settings/SKILL.md`)
+4. **Repo Management** (`.opencode/skills/repo-management/SKILL.md`)
 
 These skills are automatically provisioned when assistant mode is initialized and contain detailed examples and usage patterns.

docs/features/assistant-mode.md

@@ -0,0 +1,64 @@
+# Assistant Mode
+
+Assistant Mode gives OpenCode Manager a dedicated AI workspace — an isolated directory (`repos/assistant/`) where a built-in assistant agent can manage scheduled jobs, send push notifications, and read or update settings via a secure internal API.
+
+## What Is Assistant Mode?
+
+The assistant workspace is a special repository-like directory managed and maintained by OpenCode Manager. When initialized it contains:
+
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | Workspace description the agent reads on every session start |
+| `opencode.json` | OpenCode configuration scoped to the assistant agent |
+| `.opencode/internal-token` | Bearer token used to authenticate against the internal API |
+| `.opencode/agents/assistant.md` | Agent definition with system prompt and permissions |
+| `.opencode/skills/` | Auto-generated skills teaching the agent to use the internal API |
+
+## Skills Provided
+
+Four skills are provisioned automatically when assistant mode is initialized:
+
+| Skill | What it teaches |
+|-------|----------------|
+| `schedule-management` | Create, list, update, delete, and run scheduled jobs |
+| `notifications` | Send push notifications to registered user devices |
+| `manager-settings` | Read and patch user preferences |
+| `repo-management` | List all managed repositories |
+
+See [Assistant Internal API](assistant-internal-api.md) for the full API reference these skills expose.
+
+## Getting Started
+
+1. Click **Assistant** in the sidebar or mobile tab bar
+2. On first visit, OpenCode Manager initializes the workspace and creates a new session
+3. A welcome prompt is automatically sent to orient the agent
+4. Subsequent visits resume the most recent session
+
+No manual setup is required. The workspace directory and all managed files are created automatically.
+
+## Session Views
+
+The assistant page works in two modes:
+
+| Mode | URL | What you see |
+|------|-----|-------------|
+| Redirect | `/assistant` | Instantly redirects to the last session or creates one |
+| Session list | `/assistant?view=sessions` | Full session history with sidebar panels |
+
+The session list exposes the same management panels as regular repos — file browser, MCP servers, skills, source control, and permissions reset.
+
+## Workspace Initialization
+
+The workspace is initialized idempotently. Managed files are only rewritten when OpenCode Manager has updated their content. User customizations to managed files are preserved.
+
+### Warnings
+
+If a managed file was modified after initialization, the next session will receive an inline prompt explaining which files were preserved and what the expected content is. This surfaces configuration drift without silently overwriting your changes.
+
+### Re-initializing
+
+To re-apply all managed files to their latest defaults:
+
+1. Navigate to the session list (`?view=sessions`)
+2. Open the **Permissions** panel
+3. Use the reset action to re-initialize the workspace

docs/features/chat.md

@@ -19,6 +19,17 @@ Messages stream in real-time using Server-Sent Events (SSE):
 - No waiting for complete responses
 - Can interrupt generation if needed
 
+## Model Selection
+
+Click the **model name** in the chat prompt area to open the quick model switcher. From there you can:
+
+- Switch to a favorite or recently used model without leaving the chat
+- Toggle favorites (star icon next to the active model)
+- Pick a model variant (highlighted in orange when available)
+- Open **All Models…** to browse the full model list
+
+Each agent retains its own model selection — switching agents restores the model last used with that agent. See [AI Configuration](ai-config.md#model-selection) for the full reference.
+
 ## Slash Commands
 
 Type `/` to see available commands:

docs/features/overview.md

@@ -29,6 +29,7 @@ OpenCode Manager provides a comprehensive web interface for managing OpenCode AI
 - **Slash Commands** - Built-in (`/help`, `/new`, `/compact`) and custom commands
 - **File Mentions** - Reference files with `@filename` autocomplete
 - **Plan/Build Modes** - Toggle between read-only and file-change modes
+- **Per-Agent Model Selection** — Each agent retains its own model selection independently
 - **Mermaid Diagrams** - Visual diagram rendering in chat
 
 [Learn more →](chat.md)
@@ -94,3 +95,11 @@ OpenCode Manager provides a comprehensive web interface for managing OpenCode AI
 - **Customizable** - Control which events trigger notifications
 
 [Learn more →](notifications.md)
+
+### Assistant Mode
+
+- **Dedicated AI Workspace** — Isolated assistant directory with managed configuration and a built-in bearer-token API
+- **Auto-Provisioned Skills** — Schedule management, notifications, settings, and repo listing skills available out of the box
+- **Session Continuity** — Navigating to the assistant always resumes the most recent session or creates one automatically
+
+[Learn more →](assistant-mode.md)

docs/features/stt.md

@@ -71,18 +71,26 @@ Any OpenAI-compatible transcription API works:
 
 ## Using Voice Input
 
-### Recording
+### Tap-to-Start / Tap-to-Stop
 
-1. Click the **microphone** button in the chat input
-2. Speak your message
-3. Click the **stop** button when finished
-4. Your speech is transcribed into the input field
+1. **Tap the microphone button** in the chat input to begin recording
+2. The button shows active recording status
+3. **Tap the stop button** when you have finished speaking
+4. The transcribed text is inserted into the input field
 5. Review and send
 
-### Recording Overlay
+### Recording States
 
-While recording, a visual overlay indicates active recording status.
+| State | Indicator | When it appears |
+|-------|-----------|-----------------|
+| Recording | "Recording…" | Microphone is active; audio is being captured |
+| Processing | "Processing…" | Audio sent to STT backend; waiting for transcript (external provider only) |
+| Interim text | Live partial transcript | Browser is streaming partial results in real time (built-in provider only) |
 
-### Aborting
+### Cancelling
 
-Click the **cancel** button during recording to discard without transcribing.
+Tap the **cancel (×) button** during recording to discard the recording without transcribing.
+
+### Errors
+
+If recording fails — microphone permission denied, startup timeout, or transcription error — a brief error message appears and auto-dismisses after 3 seconds. No text is inserted.

docs/index.md

@@ -21,7 +21,7 @@ Open [http://localhost:5003](http://localhost:5003) and create your admin accoun
 OpenCode Manager is a mobile-first web interface for [OpenCode](https://opencode.ai) AI agents. It combines repository management, chat/session control, Git and file tools, schedules, AI configuration, MCP server management, push notifications, and full PWA support into a single responsive application.
 
 - **Repository management** — Clone, discover, and manage multiple Git repos with SSH authentication and worktree support
-- **Chat & sessions** — Real-time SSE streaming with slash commands, `@file` mentions, and Plan/Build modes
+- **Chat & sessions** — Real-time SSE streaming with slash commands, `@file` mentions, Plan/Build modes, and per-agent model selection
 - **Schedules** — Recurring repo jobs with reusable prompts, run history, and linked sessions
 - **AI configuration** — Model/provider setup, OAuth for Anthropic/GitHub Copilot, custom agents
 - **MCP & Skills** — MCP server management and skill support
@@ -43,6 +43,7 @@ OpenCode Manager runs as a pnpm workspace:
 - **Chat & Sessions** — Real-time SSE streaming, slash commands, `@file` mentions, Plan/Build modes, Mermaid diagrams — [Learn more](features/chat.md)
 - **Files** — Directory browser with tree view, syntax highlighting, create/rename/delete, ZIP download — [Learn more](features/files.md)
 - **Schedules** — Recurring repo jobs with reusable prompts, run history, linked sessions — [Learn more](features/schedules.md)
+- **Assistant Mode** — Dedicated AI workspace with auto-provisioned skills for schedule management, notifications, settings, and repo listing — [Learn more](features/assistant-mode.md)
 - **AI Configuration** — Model/provider setup, OAuth for Anthropic/GitHub Copilot, custom agents — [Learn more](features/ai-config.md)
 - **MCP Servers** — Add local or remote MCP servers with OAuth support — [Learn more](features/mcp.md)
 - **Skills** — Skill support for extended agent capabilities — [Learn more](features/skills.md)

mkdocs.yml

@@ -35,6 +35,8 @@ nav:
     - AI Configuration: features/ai-config.md
     - Skills: features/skills.md
     - MCP Servers: features/mcp.md
+    - Assistant Mode: features/assistant-mode.md
+    - Assistant Internal API: features/assistant-internal-api.md
     - Text-to-Speech: features/tts.md
     - Speech-to-Text: features/stt.md
     - Push Notifications: features/notifications.md