docs: update cli, hub, and web README files with new features and configuration

- cli/README.md: Remove non-existent runner commands, add codex resume and worktree config
- hub/README.md: Document auto-generated CLI_API_TOKEN, add session/machines/events endpoints and push notifications
- web/README.md: Add settings and terminal routes, terminal and voice assistant sections
- docs/guide: Fix broken anchor link and add terminal FAQ entry
- AGENTS.md: Add new source directory references

AGENTS.md

@@ -31,7 +31,10 @@ Short guide for AI agents in this repo. Prefer progressive loading: start with t
 ## Key source dirs
 - `cli/src/api/`, `cli/src/claude/`, `cli/src/commands/`, `cli/src/codex/`
 - `hub/src/web/`, `hub/src/socket/`, `hub/src/telegram/`, `hub/src/sync/`
+- `hub/src/socket/handlers/cli/` - Terminal multiplexing, session handlers
+- `hub/src/notifications/` - Push and Telegram notifications
 - `web/src/components/`, `web/src/api/`, `web/src/hooks/`
+- `web/src/routes/sessions/terminal.tsx` - Terminal UI
 
 ## Critical Thinking
 

cli/README.md

@@ -24,6 +24,7 @@ Run Claude Code, Codex, or Gemini sessions from your terminal and control them r
 
 - `hapi` - Start a Claude Code session (passes through Claude CLI flags). See `src/index.ts`.
 - `hapi codex` - Start Codex mode. See `src/codex/runCodex.ts`.
+- `hapi codex resume <sessionId>` - Resume existing Codex session.
 - `hapi gemini` - Start Gemini mode via ACP. See `src/agent/runners/runAgentSession.ts`.
   Note: Gemini runs in remote mode only; it waits for messages from the hub UI/Telegram.
 
@@ -43,8 +44,6 @@ See `src/commands/auth.ts`.
 - `hapi runner list` - List active sessions managed by runner.
 - `hapi runner stop-session <sessionId>` - Terminate specific session.
 - `hapi runner logs` - Print path to latest runner log file.
-- `hapi runner install` - Install runner as system service.
-- `hapi runner uninstall` - Remove runner system service.
 
 See `src/runner/run.ts`.
 
@@ -82,6 +81,14 @@ See `src/configuration.ts` for all options.
 - `HAPI_RUNNER_HEARTBEAT_INTERVAL` - Heartbeat interval in ms (default: 60000).
 - `HAPI_RUNNER_HTTP_TIMEOUT` - HTTP timeout for runner control in ms (default: 10000).
 
+### Worktree (set by runner)
+
+- `HAPI_WORKTREE_BASE_PATH` - Base repository path.
+- `HAPI_WORKTREE_BRANCH` - Current branch name.
+- `HAPI_WORKTREE_NAME` - Worktree name.
+- `HAPI_WORKTREE_PATH` - Full worktree path.
+- `HAPI_WORKTREE_CREATED_AT` - Creation timestamp (ms).
+
 ## Storage
 
 Data is stored in `~/.hapi/` (or `$HAPI_HOME`):

docs/guide/faq.md

@@ -91,6 +91,10 @@ In the session view, tap the "Files" tab to:
 
 Yes. Open any session and use the chat interface to send messages directly to the AI agent.
 
+### Can I access a terminal remotely?
+
+Yes. Open a session in the web app and tap the Terminal tab for a remote shell.
+
 ### How do I use voice control?
 
 Set `ELEVENLABS_API_KEY`, open a session in the web app, and click the microphone button. See [Voice Assistant](./voice-assistant.md).

docs/guide/quick-start.md

@@ -55,6 +55,6 @@ Enter your access token to log in.
 ## Next steps
 
 - [Seamless Handoff](./how-it-works.md#seamless-handoff) - Switch between terminal and phone seamlessly
-- [Remote access](./installation.md#remote-access) - Access HAPI from anywhere
+- [Hub setup](./installation.md#hub-setup) - Access HAPI from anywhere
 - [Notifications](./installation.md#telegram-setup) - Set up Telegram notifications
 - [Install the App](./pwa.md) - Add HAPI to your home screen

hub/README.md

@@ -17,7 +17,7 @@ See `src/configuration.ts` for all options.
 
 ### Required
 
-- `CLI_API_TOKEN` - Base shared secret used by CLI and web login. Clients append `:<namespace>` for isolation.
+- `CLI_API_TOKEN` - Base shared secret used by CLI and web login. Clients append `:<namespace>` for isolation. Auto-generated on first run if not set.
 
 ### Optional (Telegram)
 
@@ -36,6 +36,11 @@ See `src/configuration.ts` for all options.
 - `CORS_ORIGINS` - Comma-separated origins, or `*`.
 - `HAPI_HOME` - Data directory (default: ~/.hapi).
 - `DB_PATH` - SQLite database path (default: HAPI_HOME/hapi.db).
+- `TELEGRAM_NOTIFICATION` - Enable/disable Telegram notifications (default: true).
+- `HAPI_RELAY_API` - Relay API domain (default: relay.hapi.run).
+- `HAPI_RELAY_AUTH` - Relay auth key (default: hapi).
+- `HAPI_RELAY_FORCE_TCP` - Force TCP relay mode (true/1).
+- `VAPID_SUBJECT` - Contact email/URL for Web Push.
 
 ## Running
 
@@ -76,7 +81,15 @@ See `src/web/routes/` for all endpoints.
 - `GET /api/sessions` - List all sessions.
 - `GET /api/sessions/:id` - Get session details.
 - `POST /api/sessions/:id/abort` - Abort session.
-- `POST /api/sessions/:id/switch` - Switch session mode (remote/local).
+- `POST /api/sessions/:id/switch` - Switch session to remote mode.
+- `POST /api/sessions/:id/resume` - Resume inactive session.
+- `POST /api/sessions/:id/upload` - Upload file (base64, max 50MB).
+- `POST /api/sessions/:id/upload/delete` - Delete uploaded file.
+- `POST /api/sessions/:id/archive` - Archive active session.
+- `PATCH /api/sessions/:id` - Rename session.
+- `DELETE /api/sessions/:id` - Delete inactive session.
+- `GET /api/sessions/:id/slash-commands` - List slash commands.
+- `GET /api/sessions/:id/skills` - List skills.
 - `POST /api/sessions/:id/permission-mode` - Set permission mode.
 - `POST /api/sessions/:id/model` - Set model preference.
 
@@ -94,6 +107,7 @@ See `src/web/routes/` for all endpoints.
 
 - `GET /api/machines` - List online machines.
 - `POST /api/machines/:id/spawn` - Spawn new session on machine.
+- `POST /api/machines/:id/paths/exists` - Check if path exists.
 
 ### Git/Files (`src/web/routes/git.ts`)
 
@@ -106,11 +120,18 @@ See `src/web/routes/` for all endpoints.
 ### Events (`src/web/routes/events.ts`)
 
 - `GET /api/events` - SSE stream for live updates.
+- `POST /api/visibility` - Report client visibility state.
 
 ### Voice (`src/web/routes/voice.ts`)
 
 - `POST /api/voice/token` - Get ElevenLabs conversation token.
 
+### Push Notifications (`src/web/routes/push.ts`)
+
+- `GET /api/push/vapid-public-key` - Get VAPID public key.
+- `POST /api/push/subscribe` - Subscribe to push notifications.
+- `DELETE /api/push/subscribe` - Unsubscribe.
+
 ### CLI (`src/web/routes/cli.ts`)
 
 - `POST /cli/sessions` - Create/load session.
@@ -135,6 +156,13 @@ Namespace: `/cli`
 - `rpc-register` - Register RPC handler.
 - `rpc-unregister` - Unregister RPC handler.
 
+### Terminal events (web to hub)
+
+- `terminal:create` - Open terminal for session.
+- `terminal:write` - Send input.
+- `terminal:resize` - Resize dimensions.
+- `terminal:close` - Close terminal.
+
 ### Hub events (hub to clients)
 
 - `update` - Broadcast session/message updates.
@@ -185,10 +213,14 @@ See `src/store/index.ts` for SQLite persistence:
 
 - `src/web/` - HTTP service and routes.
 - `src/socket/` - Socket.IO setup and handlers.
+- `src/socket/handlers/cli/` - Modular CLI handlers.
 - `src/telegram/` - Telegram bot.
 - `src/sync/` - Core session/message logic.
 - `src/store/` - SQLite persistence.
 - `src/sse/` - Server-Sent Events.
+- `src/config/` - Configuration loading and generation.
+- `src/notifications/` - Push and Telegram notifications.
+- `src/visibility/` - Client visibility tracking.
 
 ## Security model
 

web/README.md

@@ -29,6 +29,8 @@ See `src/router.tsx` for route definitions.
 - `/sessions/new` - Create new session.
 - `/sessions/$sessionId/files` - File browser with git status.
 - `/sessions/$sessionId/file` - File viewer with diff support.
+- `/sessions/$sessionId/terminal` - Terminal interface.
+- `/settings` - Application settings.
 
 ## Features
 
@@ -61,11 +63,25 @@ See `src/router.tsx` for route definitions.
 - File content display with syntax highlighting.
 - Staged/unstaged diff view.
 
-### New session (`src/components/NewSession.tsx`)
+### Terminal (`src/routes/sessions/terminal.tsx`)
 
-- Machine selector.
+- Remote terminal via xterm.js
-- Directory input with recent paths.
+- Real-time via Socket.IO
-- Agent type selector (claude/codex/gemini).
+- Resize handling
+
+### Voice assistant
+
+- ElevenLabs integration (@elevenlabs/react)
+- Real-time voice control
+
+### New session (`src/components/NewSession/`)
+
+Modular session creation:
+- Machine selector
+- Directory input with recent paths
+- Agent type selector
+- Model selector
+- Permission mode toggle (YOLO mode)
 
 ## Authentication
 
@@ -93,7 +109,7 @@ See `src/hooks/useSSE.ts`.
 
 ## Stack
 
-React 19 + Vite + TanStack Router/Query + Tailwind + @assistant-ui/react.
+React 19 + Vite + TanStack Router/Query + Tailwind + @assistant-ui/react + xterm.js + @elevenlabs/react + socket.io-client + workbox + shiki.
 
 ## Source structure