Merge chore/repository-organization-20260901 into integration/repository-organization-20260901

2026-09-01 21:47:50 -04:00
parent a7c860a2e3 3b4da0305e
commit 607bc95b73
98 changed files with 476 additions and 280 deletions
@@ -14,7 +14,7 @@ function classifyCiPaths(paths) {
  const under = (prefixes) => paths.some((path) => prefixes.some((prefix) => path.startsWith(prefix)));

  return {
-    android: forceAll || under(['app/', 'relay-core/', 'relay-ui/', 'ui-preview/', 'quest/', 'gradle/']) || exact([
+    android: forceAll || under(['app/', 'gradle/']) || exact([
      'build.gradle.kts', 'settings.gradle.kts', 'gradle.properties', 'gradlew', 'gradlew.bat',
      'scripts/check-android-locales.py', 'scripts/android-locale-harness.py',
      'scripts/check-android-collection-apis.py', 'scripts/check-android-native-compat.py',
@@ -16,7 +16,7 @@ const none = {

 assert.deepEqual(classifyCiPaths(['README.md']), none);
 assert.deepEqual(classifyCiPaths(['desktop/src/cli.ts']), { ...none, desktop: true });
-assert.deepEqual(classifyCiPaths(['relay-core/src/main/kotlin/Wire.kt']), { ...none, android: true });
+assert.deepEqual(classifyCiPaths(['experiments/quest/src/main/kotlin/Quest.kt']), none);
 assert.deepEqual(classifyCiPaths(['scripts/check-android-release-notes.py']), { ...none, android: true });
 assert.deepEqual(classifyCiPaths(['scripts/check-android-native-compat.py']), { ...none, android: true });
 assert.deepEqual(classifyCiPaths(['scripts/android_release_artifacts.py']), { ...none, android: true });
@@ -20,10 +20,6 @@ on:
    branches: [main, dev]
    paths:
      - "app/**"
-      - "relay-core/**"
-      - "relay-ui/**"
-      - "ui-preview/**"
-      - "quest/**"
      - "gradle/**"
      - "build.gradle.kts"
      - "settings.gradle.kts"
@@ -24,10 +24,7 @@ Thumbs.db
 local.properties
 /build/
 /app/build/
-/relay-core/build/
-/relay-ui/build/
-/ui-preview/build/
-/quest/build/
+/experiments/quest/**/build/
 /app/release/
 *.apk
 *.aab
@@ -17,7 +17,7 @@ contract here and in `RELEASE.md`.
 - Android local/cloud verification → **[docs/android-build-lane.md](docs/android-build-lane.md)**
 - Android emulator lanes → **[docs/android-emulator-testing.md](docs/android-emulator-testing.md)** — suggest the smallest relevant API 36 lanes; never run the full matrix automatically
 - `android_*` toolset + MCP → **[docs/mcp-tooling.md](docs/mcp-tooling.md)**
- Follow-ups / deferred work / known gaps → **[TODO.md](TODO.md)** (the single home for "what's next" — never DEVLOG, never scattered code comments)
+- Follow-ups / deferred work / known gaps → **[docs/project/TODO.md](docs/project/TODO.md)** (the single home for "what's next" — never DEVLOG, never scattered code comments)

 ## Branch contract

@@ -1281,7 +1281,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this

 - **Voice-exit chime firing on every Add-connection tap.** `ConnectionSwitchCoordinator.switchConnection` fires the `voiceStopCallback` unconditionally at step 3 (correct for connection-to-connection switches while voice is active), but `beginAddConnection` also routes through `switchConnection` to bind the placeholder Connection's auth store before the pair wizard runs — and `VoiceViewModel.exitVoiceMode()` was playing `sfxPlayer.playExit()` regardless of whether voice mode was actually on. Logcat confirmed the chime on every Add-connection FAB tap. Fix adds an idempotence guard at the top of `exitVoiceMode()`: early-return when `_uiState.value.voiceMode` is already false. Teardown is still safe to skip because every inner statement is null-guarded + try/catch-wrapped and would be a no-op on an already-stopped voice session; the only meaningful line is the `playExit()` SFX, which is what we're silencing.
 - **500 ms freeze on every Add-connection tap.** `ConnectionSwitchCoordinator.switchConnection` runs a `withTimeoutOrNull(AUTH_HYDRATE_TIMEOUT_MS = 500L)` block at step 10 to wait for the freshly-bound `AuthManager` to flip `AuthState` from `Loading` to `Paired`. The comment acknowledged Add-connection is the common path and the 500 ms was meant to be "imperceptible," but on-device it wasn't — the user perceived the delay (and the voice chime masking it) on every tap. The placeholder Connection created by `beginAddConnection` has `pairedAt == null` and an empty EncryptedSharedPreferences store, so `AuthState` will NEVER reach `Paired` — the 500 ms is pure stall. Fix short-circuits the hydrate wait when `target.pairedAt == null`: skip `withTimeoutOrNull` entirely for placeholders and log at DEBUG instead of the misleading "auth hydrate timeout" INFO. Real paired-to-paired switches still run the full hydrate wait because both sides have `pairedAt != null`.
- **KDoc nested-comment trap in `ConnectionViewModel.relayReady` doc block.** A literal `/voice/*` path pattern inside the `relayReady` KDoc opened a nested block comment (Kotlin supports nested `/* */`, Java does not) whose `*/` then closed only the nested level — leaving the outer `/**` open for the remaining ~2200 lines of the file. Symptom: `MainActivity.kt:67` "Unresolved reference 'isReady'" plus ~50 cascading "Cannot infer type" errors across `PairedDevicesScreen`, `SettingsScreen`, `TerminalScreen`. Real errors (`Missing '}`, `Unclosed comment`) were the last two lines of `./gradlew compileGooglePlayDebugKotlin` output, easy to miss. Fix was a two-character rewrite: path patterns now wrapped in backticks AND `/*` → `/...` so the glob-looking character isn't in a block-comment position. Lesson logged in `DEVLOG.md` 2026-04-21; worth a sweep of other KDoc blocks for shell/regex-looking patterns before the next large diff.
+- **KDoc nested-comment trap in `ConnectionViewModel.relayReady` doc block.** A literal `/voice/*` path pattern inside the `relayReady` KDoc opened a nested block comment (Kotlin supports nested `/* */`, Java does not) whose `*/` then closed only the nested level — leaving the outer `/**` open for the remaining ~2200 lines of the file. Symptom: `MainActivity.kt:67` "Unresolved reference 'isReady'" plus ~50 cascading "Cannot infer type" errors across `PairedDevicesScreen`, `SettingsScreen`, `TerminalScreen`. Real errors (`Missing '}`, `Unclosed comment`) were the last two lines of `./gradlew compileGooglePlayDebugKotlin` output, easy to miss. Fix was a two-character rewrite: path patterns now wrapped in backticks AND `/*` → `/...` so the glob-looking character isn't in a block-comment position. Lesson logged in `docs/project/DEVLOG.md` 2026-04-21; worth a sweep of other KDoc blocks for shell/regex-looking patterns before the next large diff.

 - **Orphan placeholder connections from abandoned Add-connection flows.** The `beginAddConnection` path pre-creates a placeholder Connection and switches to it before the pair wizard runs — so `applyPairingPayload` lands the token in the right auth store. Previously, cleanup of the placeholder was wired only to the explicit Cancel button and TopAppBar back arrow. System back (gesture back / predictive back) bypassed that branch, leaving the placeholder in the connection list forever. Two-part fix: (a) `PairScreen` now installs a `BackHandler` that routes system back through the same `onCancel` → `discardPlaceholderConnection` branch the explicit back arrow uses; (b) `ConnectionViewModel.init` sweeps for any existing orphans (tuple: `pairedAt == null && apiServerUrl.isBlank() && label == PLACEHOLDER_LABEL`) on cold start and removes them — the tuple cannot be produced by any real pairing, so the sweep is safe without a dry-run. If the active connection at startup points at an orphan, the sweep switches to the first surviving real connection before deleting. Fixes the "why does my chip say 'New connection…'" symptom on devices that were affected pre-fix.
 - **Pair flow now auto-starts the camera on Add connection.** `ConnectionWizard` gains an `autoStart: String?` param (currently only `"scan"` is honored). The Add-connection FAB on `ConnectionsSettingsScreen` passes it so the wizard fires the camera permission launcher on first composition instead of forcing users through the Method chooser — one obvious next step, one-tap flow. Re-pair surfaces intentionally leave `autoStart` null so the full Scan / Enter code / Show code chooser stays available there. The deep-link arg is plumbed through `Screen.Pair`'s route (`pair?connectionId=...&autoStart=...`) and `PairScreen`'s new `autoStart` param; unrecognized values fall through to the default Method step so future builds can add more targets without breaking old ones.
@@ -2098,7 +2098,7 @@ picker.
 - **`CLAUDE.md`** — updated Git section with the new branching policy,
  added file-table entries for `hermes-relay-update`,
  `register_code_command`, and the expanded `install.sh`
- **`TODO.md`** — captures open research questions around proper
+- **`docs/project/TODO.md`** — captures open research questions around proper
  Hermes plugin/skill/tool distribution
 - **`user-docs` vitepress site** — new "For AI Agents" copy-paste
  block on the home view, Feature Matrix component, two-track explainer,
@@ -259,16 +259,20 @@ translations may ship as `ai-translated`; do not claim fluent review unless a
 review reference is recorded. Focused correction PRs from fluent contributors
 are the canonical way to improve wording and can advance a locale to
 `community-reviewed` or `verified` under `docs/translation-playbook.md`.
-Translated READMEs use separate `README.<locale>.md` files; `README.md` remains
-the canonical project description. User docs may be added incrementally under
-`user-docs/<locale>/`, with links back to canonical English reference material.
+Translated README entrypoints live under `docs/readme/` as
+`README.<locale>.md`; root `README.md` remains the canonical project
+description. Keep translated entrypoints concise: summarize onboarding and
+core capabilities, link to localized user docs where available, and link back
+to English for fast-moving architecture, security, and operator detail. User
+docs may be added incrementally under `user-docs/<locale>/`, with links back to
+canonical English reference material.

 ## Changelog & writing conventions

-This is a **public repo** — `CHANGELOG.md`, `DEVLOG.md`, the README, and everything under `docs/` ship publicly. Keep them clean:
+This is a **public repo** — `CHANGELOG.md`, `docs/project/DEVLOG.md`, the README, and everything under `docs/` ship publicly. Keep them clean:

- **`CHANGELOG.md`** follows [Keep a Changelog](https://keepachangelog.com/) (Added / Changed / Fixed). Append your change to the `## [Unreleased]` block in the PR. Entries can carry detail while they accumulate, but at release-prep the version block is **condensed to crisp public bullets** (1–2 lines each) — the deep "how we debugged it" narrative belongs in commit messages and `DEVLOG.md`, not the public changelog.
- **`DEVLOG.md`** is a factual engineering log — what changed, why, and how it was verified. Keep it depersonalized and third-person; it's a record, not a diary.
+- **`CHANGELOG.md`** follows [Keep a Changelog](https://keepachangelog.com/) (Added / Changed / Fixed). Append your change to the `## [Unreleased]` block in the PR. Entries can carry detail while they accumulate, but at release-prep the version block is **condensed to crisp public bullets** (1–2 lines each) — the deep "how we debugged it" narrative belongs in commit messages and `docs/project/DEVLOG.md`, not the public changelog.
+- **`docs/project/DEVLOG.md`** is a factual engineering log — what changed, why, and how it was verified. Keep it depersonalized and third-person; it's a record, not a diary.
 - **No non-public wording anywhere committed:** no personal names (attribute impersonally — identity lives in git history), no real server hostnames/IPs or internal deployment names, no AI/assistant process self-narration, no fork/branch plumbing in user-facing notes. Generic example IPs in setup docs are fine.

 Release notes (`RELEASE_NOTES.md`, `app/src/main/assets/whats_new.txt`, `docs/play-store-listing.md`) are theme-framed and user-facing; see [RELEASE.md](RELEASE.md) §2 "Scrub for public distribution" for the full checklist.
@@ -21,7 +21,13 @@
 </p>

 <p align="center">
-  <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a><br>
+  <strong>English</strong> ·
+  <a href="docs/readme/README.de.md">Deutsch</a> ·
+  <a href="docs/readme/README.es.md">Español</a> ·
+  <a href="docs/readme/README.ja.md">日本語</a> ·
+  <a href="docs/readme/README.pt-BR.md">Português (Brasil)</a> ·
+  <a href="docs/readme/README.ru.md">Русский</a> ·
+  <a href="docs/readme/README.zh-CN.md">简体中文</a><br>
  <a href="https://hermes-relay.dev/docs/">Documentation</a> ·
  <a href="https://github.com/Codename-11/hermes-relay/releases">Releases</a> ·
  <a href="https://github.com/Codename-11/hermes-relay/discussions">Discussions</a> ·
@@ -1,109 +0,0 @@
-<p align="center">
-  <img src="assets/play-store-feature-1024x500.png" alt="Hermes-Relay — 随身携带您的 Hermes 代理" width="800">
-</p>
-
-<p align="center">
-  <strong>运行在您的电脑上，连接到您的设备。</strong><br>
-  Hermes-Relay 是 <a href="https://github.com/NousResearch/hermes-agent">Hermes Agent</a> 的原生 Android 客户端，提供流式聊天、免手动语音和代理管理；另有单文件 CLI，让代理在已配对的电脑上安全使用终端、文件和截图工具。
-</p>
-
-<p align="center">
-  <strong>简体中文</strong> · <a href="README.md">English</a><br>
-  <a href="https://hermes-relay.dev/docs/zh-CN/">中文文档</a> ·
-  <a href="https://github.com/Codename-11/hermes-relay/releases">版本下载</a> ·
-  <a href="https://github.com/Codename-11/hermes-relay/discussions">社区讨论</a> ·
-  <a href="CHANGELOG.md">更新日志</a>
-</p>
-
-> 英文 [README.md](README.md) 是最新、完整的项目说明。本页维护中文安装入口和核心功能摘要；协议、架构和维护者文档以英文版本为准。
-
-## 功能简介
-
- **Android 应用**：流式聊天、会话历史、文件附件、Hermes 管理、语音模式、原生插件页面、Petdex 悬浮宠物、多连接和配置文件；也可将 Hermes 设为 Android 助手。
- **无需插件的标准路径**：聊天、管理和标准语音可直接连接未修改的上游 Hermes Agent。
- **可选 Relay 插件**：增加终端、手机控制、媒体传输、通知助手、Relay 语音、电脑工具，以及需确认的代理创建插件页面草稿。
- **安全连接**：二维码配对、Android Keystore、证书固定、按通道授权和可配置会话有效期。
- **远程使用**：可配置 Tailscale 或 HTTPS 地址，在家庭局域网和远程路由之间自动切换。
- **两种 Android 发行渠道**：Google Play 版本适合日常使用；sideload 版本包含完整手机控制能力。
-
-## 快速开始
-
-### 1. 安装 Android 应用
-
- [Google Play](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay)：自动更新，包含聊天、语音、管理、终端、媒体和通知功能。
- [GitHub Releases](https://github.com/Codename-11/hermes-relay/releases)：下载最新 `android-v*` 版本中以 `-sideload-release.apk` 结尾的文件，获得完整手机控制功能。
-
-### 2. 启动 Hermes API 服务
-
-手机需要能够访问 Hermes API 服务，并使用 API 密钥进行身份验证：
-
-```bash
-hermes setup --portal
-
-mkdir -p ~/.hermes
-API_SERVER_KEY="$(openssl rand -hex 32)"
-cat >> ~/.hermes/.env <<EOF
-API_SERVER_ENABLED=true
-API_SERVER_HOST=0.0.0.0
-API_SERVER_PORT=8642
-API_SERVER_KEY=$API_SERVER_KEY
-EOF
-chmod 600 ~/.hermes/.env
-
-echo "Android API URL: http://<电脑IP>:8642   key: $API_SERVER_KEY"
-hermes gateway
-```
-
-`0.0.0.0` 会让同一网络中的设备访问 API。请保留强密钥；离开可信局域网时，应使用 Tailscale 或 HTTPS 反向代理，不要直接把端口暴露到互联网。
-
-### 3. 在手机上连接
-
-打开应用后，可以：
-
- 扫描局域网中的 Hermes；
- 手动输入 `http://<主机>:8642` 和 API 密钥；
- 扫描包含 API、Dashboard 和可选 Relay 地址的设置二维码。
-
-如需在手机上管理模型、密钥、技能和配置文件，请运行 Hermes Dashboard，并在应用的 **管理** 页面登录一次。同一登录会话也会启用标准语音。
-
-### 4. 可选：安装 Relay
-
-仅在需要终端、手机控制、媒体路由、Relay 会话、实时语音、电脑工具或代理创建插件页面草稿时安装：
-
-```bash
-hermes plugins install Codename-11/hermes-relay/plugin --enable
-hermes relay doctor
-hermes relay start --no-ssl
-hermes pair
-```
-
-已安装的 Hermes 插件可通过已认证的 Dashboard 向 Android 提供由应用安全渲染的原生页面，无需在手机上运行插件代码。Relay 1.5.0 另支持需用户确认的代理创建页面草稿。
-
-完整说明请阅读[中文快速开始](https://hermes-relay.dev/docs/zh-CN/guide/quick-start)；远程访问、协议和高级配置暂时链接到英文参考文档。
-
-安装问题、早期想法、一般交流和作品分享请使用 [GitHub Discussions](https://github.com/Codename-11/hermes-relay/discussions)。可复现的错误和明确、可执行的功能请求请提交到 [Issues](https://github.com/Codename-11/hermes-relay/issues/new)。
-
-## 中文界面
-
-<table>
-  <tr>
-    <td align="center" width="33%"><img src="assets/screenshots/Zh01.jpg" alt="中文设置界面" width="100%"><br><sub><b>设置</b></sub></td>
-    <td align="center" width="33%"><img src="assets/screenshots/Zh02.jpg" alt="中文管理界面" width="100%"><br><sub><b>管理</b></sub></td>
-    <td align="center" width="33%"><img src="assets/screenshots/Zh03.jpg" alt="中文导航界面" width="100%"><br><sub><b>导航</b></sub></td>
-  </tr>
-</table>
-
-## 参与翻译
-
-Android 英文资源是规范来源。新增语言必须保持资源名称、类型和格式参数一致，并通过：
-
-```bash
-python scripts/check-android-locales.py
-./gradlew lint
-```
-
-翻译规范、目录命名、复数和占位符规则见 [docs/localization.md](docs/localization.md)。
-
-## 许可证
-
-[MIT](LICENSE) — Copyright (c) 2026 [Axiom-Labs](https://codename-11.dev)
@@ -924,7 +924,7 @@ gradlew promoteReleaseArtifact --from-track=internal --promote-track=production
  (This step was only needed as a retrofit for v0.1.0 — v0.1.1+ inherit
  the Download section automatically from `RELEASE_NOTES.md`.)
 - Confirm Play Console shows the new versionCode on the target track.
- Update `DEVLOG.md` with a short entry for the release.
+- Update `docs/project/DEVLOG.md` with a short entry for the release.

 ## CI Behavior

@@ -348,7 +348,7 @@ class BridgeCommandHandler(
     * the multiplexer. The two paths are fully independent.
     *
     * Caught by Bailey's on-device test 2026-04-14 — see the v0.4.1
-     * "voice intent local dispatch loop" entry in ROADMAP.md.
+     * "voice intent local dispatch loop" entry in docs/project/ROADMAP.md.
     */
    suspend fun handleLocalCommand(envelope: Envelope): LocalDispatchResult {
        if (envelope.type != "bridge.command") {
@@ -73,7 +73,7 @@ private const val SWIPE_DISMISS_THRESHOLD_PX = 80f
 * progress" moment (pairing, long upload, a bridge action sequence). When first
 * reused, decouple it from [ConnectionStatusSnapshot] and rename to a generic
 * `StatusToast`. It also anchors [UpdateAvailableBanner]'s visual language + the
- * shared [ConnectionStepRow]/[StepGlyph] helpers. See TODO.md.
+ * shared [ConnectionStepRow]/[StepGlyph] helpers. See docs/project/TODO.md.
 *
 * Rendered as a top-aligned overlay inside a `Box` — it slides down OVER the UI
 * without shifting layout. Pair it with `AnimatedVisibility(enter =
@@ -751,7 +751,7 @@ one-time pairing, the interactive PTY/TUI shell, client-side tool routing,
 auto-reconnect with TOFU cert pinning, server-side session management, the
 headless daemon, local diagnostics, and the optional Windows management tray.

-What's next (see [ROADMAP.md](../ROADMAP.md#desktop-track) for the full track):
+What's next (see [docs/project/ROADMAP.md](../docs/project/ROADMAP.md#desktop-track) for the full track):

 - Service installers — `install-service-{win,linux,mac}` to register the daemon with `sc.exe` / systemd user unit / `launchd` so it auto-starts on login.
 - Multi-client server-side routing — today a connected desktop client is single-slot; allow laptop + home-desktop + work-box attached simultaneously with per-client tool dispatch via a new hermes-agent `ContextVar`.
@@ -1,6 +1,7 @@
 # Hermes Relay Android UI Design Reference

-Status: design reference for future Android, Quest, and pairing-flow work.
+Status: design reference for Android and pairing-flow work. The quarantined
+Quest prototype is retained under `experiments/quest/` for historical context.

 Use this document when a future session asks for mobile UI polish, pairing flow changes, QR scanning, connection setup, onboarding, terminal cockpit, or "make it feel more like Orca." It is intentionally a reference, not an implementation task list.

@@ -11,7 +12,6 @@ This project should keep its native Android stack:
 - Kotlin + Jetpack Compose + Material 3 for app chrome and interaction flows.
 - CameraX + ML Kit for QR scanning.
 - Android WebView only where it is already the correct tool, such as xterm.
- Meta Spatial SDK for Quest/XR surfaces where needed.

 Do not propose a React Native or Expo migration just because Orca's mobile app uses that stack. The useful lesson from Orca is the visual discipline and pairing UX, not the framework choice.

@@ -205,7 +205,10 @@ Target layout:

 ### Quest / XR

-Use this reference for Quest visual tone, but do not force the phone layout into XR. Quest should keep the spatial cockpit concept:
+The inactive Quest prototype is quarantined under `experiments/quest/` and is
+not part of the production Android build or normal CI. If development resumes,
+use this reference for its visual tone, but do not force the phone layout into
+XR. The spatial cockpit concept was:

 - MorphingSphere and voice pipeline remain first-class.
 - Terminal panels should be spatial, readable, and anchored.
@@ -30,8 +30,8 @@ Status: **passed**

 ### Compared

- Source: `C:\Users\Bailey\.codex\generated_images\019f6640-e6dc-7c33-8aca-a1610e2a19f0\call_JzVlJKlG8KWTJRo2xup7oTlq.png`
- Implementation: `C:\Users\Bailey\.codex\visualizations\2026\07\25\agent-drawer-audit\passport-qa-final.png`
+- Source: `<session-generated-reference>`
+- Implementation: `<session-visualization-artifact>`
 - Source size: 852 x 1846 px
 - Device viewport: Android, 1080 x 2340 px, font scale 1.0
 - State: Agent tab, Victor pinned profile, disconnected gateway
@@ -105,11 +105,11 @@ final result: passed

 ## Assistant overlay

- Reference: `C:\Users\Bailey\.codex\generated_images\019fb003-68ea-7052-85c7-3745fa7e838e\call_jPwpDr9QfaCDA6k2c01StBYe.png`
+- Reference: `<session-generated-reference>`
 - Implementation captures:
-  - `C:\Users\Bailey\.codex\visualizations\2026\07\29\019fb003-68ea-7052-85c7-3745fa7e838e\assistant-live-compact.png`
-  - `C:\Users\Bailey\.codex\visualizations\2026\07\29\019fb003-68ea-7052-85c7-3745fa7e838e\assistant-live-expanded.png`
- Combined comparison: `C:\Users\Bailey\.codex\visualizations\2026\07\29\019fb003-68ea-7052-85c7-3745fa7e838e\assistant-design-comparison.png`
+  - `<session-visualization-artifact>`
+  - `<session-visualization-artifact>`
+- Combined comparison: `<session-visualization-artifact>`
 - Device viewport: 1080 × 2340, portrait, Samsung SM-S938U
 - States reviewed: system assistant compact overlay and expanded overlay over a non-Hermes app

@@ -146,18 +146,18 @@ final result: blocked

 ## Appearance customization and visual assets

- Selected reference: `C:\Users\Bailey\.codex\generated_images\019fe6f7-920d-7be1-b287-608a0bc2ff49\exec-facb08cb-3d8f-400a-b6ff-6f1a11a74d95.png`
+- Selected reference: `<session-generated-reference>`
 - Reference pixels: 852 x 1843.
 - Final real-screen captures:
-  - `C:\Users\Bailey\.codex\worktrees\af0f\hermes-relay\app\build\store-shots\05_themes.png`
-  - `C:\Users\Bailey\.codex\worktrees\af0f\hermes-relay\app\build\store-shots\05_theme_customizer.png`
-  - `C:\Users\Bailey\.codex\worktrees\af0f\hermes-relay\app\build\store-shots\08_appearance.png`
+  - `app/build/store-shots/05_themes.png`
+  - `app/build/store-shots/05_theme_customizer.png`
+  - `app/build/store-shots/08_appearance.png`
 - Implementation pixels: 1080 x 2160, portrait Robolectric/Roborazzi capture of the production Compose screen at its 360 dp Android viewport.
 - Normalization: the selected reference was scaled to 1080 px wide and cropped to the same 2160 px viewport for the full-view comparison. The reference's taller aspect ratio remains visible as an expected viewport difference; the focused customizer capture verifies the below-fold editor content.
 - Comparison evidence:
-  - Initial full-view comparison: `C:\Users\Bailey\.codex\visualizations\2026\08\09\019fe6f7-920d-7be1-b287-608a0bc2ff49\appearance-reference-v-current.png`
-  - Final normalized full-view comparison: `C:\Users\Bailey\.codex\visualizations\2026\08\09\019fe6f7-920d-7be1-b287-608a0bc2ff49\appearance-reference-v-current-2.png`
-  - Focused customizer comparison: `C:\Users\Bailey\.codex\visualizations\2026\08\09\019fe6f7-920d-7be1-b287-608a0bc2ff49\appearance-customizer-reference-v-current.png`
+  - Initial full-view comparison: `<session-visualization-artifact>`
+  - Final normalized full-view comparison: `<session-visualization-artifact>`
+  - Focused customizer comparison: `<session-visualization-artifact>`
 - State: Hermes Relay dark preset, customizer expanded. The focused capture expands the real control by click and scrolls its Shape row into view.

 ### Comparison history
@@ -187,15 +187,15 @@ final result: passed

 ## Conversation voice dock

- Reference: `C:\Users\Bailey\.codex\generated_images\019fba42-1e93-78e1-9cd6-6919fb52d5bc\exec-89feab69-9caf-4084-b107-6bff43e511d6.png`
+- Reference: `<session-generated-reference>`
 - Implementation captures:
-  - `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit\implemented_conversation_final.png`
-  - `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit\conversation_refined_expanded.png`
-  - `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit\focus_final_expanded.png`
- Combined comparison: `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit\voice-dock-design-comparison-final.png`
- Expanded before/after comparison: `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit\voice-expanded-before-after.png`
- Entry transition recording: `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit\voice_entry_transition.mp4`
- Entry transition frame sequence: `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit\voice_entry_transition_frames.png`
+  - `<session-visualization-artifact>`
+  - `<session-visualization-artifact>`
+  - `<session-visualization-artifact>`
+- Combined comparison: `<session-visualization-artifact>`
+- Expanded before/after comparison: `<session-visualization-artifact>`
+- Entry transition recording: `<session-visualization-artifact>`
+- Entry transition frame sequence: `<session-visualization-artifact>`
 - Reference size: 853 x 1844 px
 - Device viewport: 1080 x 2340, portrait, Samsung SM-S938U
 - States reviewed: collapsed idle dock, expanded Tap-mode controls, collapsed and expanded Focus header, Focus-to-Conversation transition
@@ -229,8 +229,8 @@ copying the mockup's illustrative content.
 6. Compared the original and refined expanded Conversation and Focus states together; the final panels remove metadata fragmentation, header truncation, and avatar bleed-through.
 7. Recorded a persisted-Focus voice entry, inspected the 30 fps frame sequence, and verified that Conversation appears first through a continuous composer expansion before Focus is offered as an explicit action.
 8. Re-audited the installed Standard-mode drawer in both presentations. The final Conversation and Focus captures are:
-   - `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit-standard\21-final-expanded.png`
-   - `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit-standard\24-final-focus-expanded.png`
+   - `<session-visualization-artifact>`
+   - `<session-visualization-artifact>`
   The route summary is now two clearly separated lines (`Standard mode · Victor` and `xAI TTS · Leo`), with duplicate provider/model aliases removed and configuration provenance left to Voice Settings.
 9. Verified the Conversation long-press menu on-device in `22-final-speak-menu.png`: completed assistant messages expose Copy, Quote in reply, and Speak response without stacking Android's text-selection toolbar over the app menu.
 10. Verified the connection footer remains present under the Conversation composer. Focus remains the only in-app voice presentation that hides it.
@@ -242,13 +242,13 @@ final result: passed

 ## System voice overlay redesign

- Selected reference: `C:\Users\Bailey\.codex\generated_images\019fba42-1e93-78e1-9cd6-6919fb52d5bc\exec-6a606b04-58c3-4a6d-b11b-cd25f99a047d.png`
+- Selected reference: `<session-generated-reference>`
 - Source concepts:
-  - `C:\Users\Bailey\.codex\generated_images\019fba42-1e93-78e1-9cd6-6919fb52d5bc\exec-31a5512a-9cb7-455a-b111-d5797ab09e93.png`
-  - `C:\Users\Bailey\.codex\generated_images\019fba42-1e93-78e1-9cd6-6919fb52d5bc\exec-bbfd616e-3847-4a2e-bbd0-65deb5e4e98c.png`
+  - `<session-generated-reference>`
+  - `<session-generated-reference>`
 - Baseline captures:
-  - `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit-standard\29-current-overlay-expanded.png`
-  - `C:\Users\Bailey\.codex\visualizations\2026\07\31\019fba42-1e93-78e1-9cd6-6919fb52d5bc\voice-ui-audit-standard\30-current-overlay-expanded.png`
+  - `<session-visualization-artifact>`
+  - `<session-visualization-artifact>`
 - Device viewport: 1080 x 2340, portrait, Samsung SM-S938U
 - States to review: collapsed system overlay and expanded system overlay over a non-Hermes app

@@ -267,7 +267,7 @@ not require an API endpoint or API bearer when dashboard chat is ready.

 ### 12. Android as a Hermes Platform/Channel — "Threads" (Shipped 2026-06-28; unified-session model 2026-06-29)

-> **Status (2026-08-12):** SHIPPED as the `phone` platform plugin (`plugin/phone_platform.py`) — registered via `ctx.register_platform` with **no fork** (the ~16-file upstream change sketched below was avoided; the original research predates the open plugin-platform registry). Two-way reply is device-verified. Agent-facing entry is `send_message target=phone` (the stale `target=mobile:<device_id>` syntax below is superseded); standalone cron delivery uses the registered sender, and the adapter publishes its canonical home destination through upstream's channel directory. Live cron certification remains tracked in TODO.md.
+> **Status (2026-08-12):** SHIPPED as the `phone` platform plugin (`plugin/phone_platform.py`) — registered via `ctx.register_platform` with **no fork** (the ~16-file upstream change sketched below was avoided; the original research predates the open plugin-platform registry). Two-way reply is device-verified. Agent-facing entry is `send_message target=phone` (the stale `target=mobile:<device_id>` syntax below is superseded); standalone cron delivery uses the registered sender, and the adapter publishes its canonical home destination through upstream's channel directory. Live cron certification remains tracked in docs/project/TODO.md.
 >
 > **Decision (2026-06-29) — unified-session "Threads", not a separate surface:** the proactive agent↔phone conversation is **not** a separate app lane/tab/segment. It is a **source-tagged session inside the one Chat surface** — a **Thread** (`source=phone`). The three things distinguishing a Thread from a normal gateway chat are *session properties*, not a separate UI: (a) the agent can initiate a turn, (b) it rides the relay `proactive` transport and is relay-gated, (c) it's a standing/named DM. **Scrollback = the gateway session store** (same read path Chat uses); **live receive = the relay `proactive` push** (→ notification); **send = `proactive.reply`**. The local `ProactiveInboxStore` is demoted to a live-push cache + outbox (no parallel history). The Thread capability is surfaced in the **connection best-path/capability UI** (a relay-tier capability, like terminal/bridge/voice) and as a clean **Threads** entry (thread-spool icon, NOT a phone glyph) pinned atop the session drawer when active — never a connection-wizard step. Degrades cleanly: no relay plugin → no `source=phone` sessions → Chat is unchanged (standard-path-safe). This **supersedes the earlier "separate Agent lane / 4th nav segment" sketch** and folds in the "show chat source/platform attribution in Chat" goal in one stroke.
 >
@@ -3240,7 +3240,7 @@ escalation remains reserved and reports disabled. The optional driver is not
 bundled or updated by Hermes-Relay, and Hermes forces driver telemetry off for
 every child process it starts. The legacy engine remains the default and the
 fail-closed fallback while the live Windows acceptance and remaining scope,
-redaction, and grant-bridge hardening gates tracked in `TODO.md` stay open.
+redaction, and grant-bridge hardening gates tracked in `docs/project/TODO.md` stay open.

 **Second-phase refinement (2026-08-13).** CUA is the preferred/default setting
 for new structured-control sessions; the original Windows input path is named
@@ -3743,7 +3743,7 @@ the session, duplicate submission, wrong-session events, or an arbitrary timer.
 Normal terminal delivery is unchanged, queued turns retain their existing
 ownership, Relay remains optional, and unmodified upstream compatibility is
 preserved. Physical certification across the reported device/network matrix
-remains tracked in `TODO.md`.
+remains tracked in `docs/project/TODO.md`.

 ---

@@ -4118,7 +4118,7 @@ visible without mislabeling their parent turn. Older Gateways remain usable
 but show Unavailable when no exact local terminal truth exists. Declarative
 Gateway scenarios cover all four upstream states, complete-snapshot
 disappearance, client-side profile isolation, and method-not-found; physical
-and current-host certification remains tracked in `TODO.md`. An upstream
+and current-host certification remains tracked in `docs/project/TODO.md`. An upstream
 profile field/filter or explicitly owned aggregate activity route would remove
 the remaining ambiguity for multi-profile clients.

@@ -18,7 +18,7 @@
      },
      "surfaces": {
        "android": "complete",
-        "readme": "english-fallback",
+        "readme": "maintained-summary",
        "user_docs": "core-pages",
        "website": "complete"
      },
@@ -53,7 +53,7 @@
      },
      "surfaces": {
        "android": "complete",
-        "readme": "english-fallback",
+        "readme": "maintained-summary",
        "user_docs": "core-pages",
        "website": "complete"
      },
@@ -77,7 +77,7 @@
      },
      "surfaces": {
        "android": "complete",
-        "readme": "english-fallback",
+        "readme": "maintained-summary",
        "user_docs": "core-pages",
        "website": "complete"
      },
@@ -101,7 +101,7 @@
      },
      "surfaces": {
        "android": "complete",
-        "readme": "english-fallback",
+        "readme": "maintained-summary",
        "user_docs": "core-pages",
        "website": "complete"
      },
@@ -125,7 +125,7 @@
      },
      "surfaces": {
        "android": "complete",
-        "readme": "english-fallback",
+        "readme": "maintained-summary",
        "user_docs": "english-fallback",
        "website": "english-fallback"
      }
@@ -78,21 +78,25 @@ structurally complete but semantically stale translation.
 9. Test the locale on an emulator or device, including in-app and Android-system
   language switching, process restart, text expansion, and
   accessibility.
-10. Add the language to the README language links and status registry. New
-   AI-assisted locales start as `ai-translated` with empty `review_refs`.
+10. Add a compact `docs/readme/README.<locale>.md` entrypoint, link it from the
+   root README language list, and update the status registry. New AI-assisted
+   locales start as `ai-translated` with empty `review_refs`.

 ## README and user documentation

-`README.md` remains canonical. Translations use separate files such as
-`README.zh-CN.md` and link back to English. Product documentation can be rolled
-out by locale under `user-docs/<locale>/`; untranslated technical references
-should link to the canonical English page rather than copying stale content.
+`README.md` remains canonical. Translated entrypoints live under
+`docs/readme/` as `README.<locale>.md` and link back to English. They are
+deliberately compact onboarding and core-feature summaries, not full copies of
+the fast-moving English README. Product documentation can be rolled out by
+locale under `user-docs/<locale>/`; untranslated technical references should
+link to the canonical English page rather than copying stale content.

 `docs/localization-status.json` is the authoritative per-locale and per-surface
 status. README and user-documentation translations may follow app translation;
 maintainer `docs/` and ADRs remain canonical English.

-The public documentation currently localizes a deliberately bounded first-run
+All shipped non-English Android locales have a compact translated README
+entrypoint. The public documentation localizes a deliberately bounded first-run
 set for German, Spanish, Japanese, Brazilian Portuguese, and Simplified Chinese.
 Russian currently falls back to the canonical English documentation:

@@ -513,7 +513,7 @@ reply completes. A reaction overlays whatever else would show (including
 ### Forthcoming behavior (designed, not yet rendered)

 These are specified so authors can plan, but the renderer doesn't drive them
-yet — they're tracked in `TODO.md`. Authoring the clips/flags now is harmless.
+yet — they're tracked in `docs/project/TODO.md`. Authoring the clips/flags now is harmless.

 - **`attention` reaction** — a one-shot when a notification arrives. Reserved: it
  needs a host event the pet doesn't yet receive (unlike `greet`/`done`, which
@@ -2,14 +2,14 @@

 > **Purpose.** Detailed implementation plan for the v0.4 bridge feature expansion wave. Each work unit here is self-contained enough that an agent can pick it up and execute independently, including per-unit Agent briefs, file lists, acceptance criteria, and reference-implementation pointers.
 >
-> **Why this file exists.** The high-level [`ROADMAP.md`](../../ROADMAP.md) at the repo root lists the milestones for this wave as brief bullets; this file is where the scoping detail lives. While this plan is active, it's the source of truth for the agent team. Once every unit here has shipped, the plan file gets archived or deleted and the shipped items live on in [`CHANGELOG.md`](../../CHANGELOG.md) and [`DEVLOG.md`](../../DEVLOG.md).
+> **Why this file exists.** The high-level [`docs/project/ROADMAP.md`](../../docs/project/ROADMAP.md) lists the milestones for this wave as brief bullets; this file is where the scoping detail lives. While this plan is active, it's the source of truth for the agent team. Once every unit here has shipped, the plan file gets archived or deleted and the shipped items live on in [`CHANGELOG.md`](../../CHANGELOG.md) and [`docs/project/DEVLOG.md`](../../docs/project/DEVLOG.md).
 >
-> **Origin.** Compiled 2026-04-13 from a comparison pass against [raulvidis/hermes-android](https://github.com/raulvidis/hermes-android) plus prior research. Scope covers bridge-channel tool expansion, reliability patterns, and one documentation/skill addition — deferred and research-horizon items live in [`ROADMAP.md`](../../ROADMAP.md), not here.
+> **Origin.** Compiled 2026-04-13 from a comparison pass against [raulvidis/hermes-android](https://github.com/raulvidis/hermes-android) plus prior research. Scope covers bridge-channel tool expansion, reliability patterns, and one documentation/skill addition — deferred and research-horizon items live in [`docs/project/ROADMAP.md`](../../docs/project/ROADMAP.md), not here.
 >
 > **Related files.**
-> - [`ROADMAP.md`](../../ROADMAP.md) — milestone-level view of where this plan sits in the broader arc
+> - [`docs/project/ROADMAP.md`](../../docs/project/ROADMAP.md) — milestone-level view of where this plan sits in the broader arc
 > - [`CHANGELOG.md`](../../CHANGELOG.md) — cumulative release history
-> - [`DEVLOG.md`](../../DEVLOG.md) — session-by-session narrative log
+> - [`docs/project/DEVLOG.md`](../../docs/project/DEVLOG.md) — session-by-session narrative log
 > - [`CLAUDE.md`](../../CLAUDE.md) — project conventions every implementing agent should read first
 > - [`docs/spec.md`](../spec.md) — formal architecture spec
 > - [`docs/decisions.md`](../decisions.md) — architecture decision records (ADRs)
@@ -30,7 +30,7 @@
 | **P** | Architectural pattern / reliability improvement, not a new tool. |
 | **Doc** | Documentation surface change. |

-Longer-term / research / aspirational items live in [`ROADMAP.md`](../../ROADMAP.md), not in this plan.
+Longer-term / research / aspirational items live in [`docs/project/ROADMAP.md`](../../docs/project/ROADMAP.md), not in this plan.

 **Effort sizing** (scope, not duration): **S** = trivial single-file change, **M** = multi-file change touching 2–4 layers, **L** = new subsystem or cross-cutting work.

@@ -9,16 +9,16 @@
 > **Related files.**
 > - [`CLAUDE.md`](../../CLAUDE.md) — project conventions every implementing agent reads first
 > - [`docs/spec.md`](../spec.md) — protocol / voice surface reference
-> - [`ROADMAP.md`](../../ROADMAP.md) — where this pass sits in the broader arc
+> - [`docs/project/ROADMAP.md`](../../docs/project/ROADMAP.md) — where this pass sits in the broader arc
 > - [`docs/plans/2026-04-13-bridge-feature-expansion.md`](./2026-04-13-bridge-feature-expansion.md) — precedent for plan-file format
-> - [`DEVLOG.md`](../../DEVLOG.md) — append session entry on completion
+> - [`docs/project/DEVLOG.md`](../../docs/project/DEVLOG.md) — append session entry on completion
 > - Upstream reference: `~/.hermes/hermes-agent/tools/tts_tool.py` on hermes-host (`you@hermes-host`)

 ## How to use this file

 1. **Bailey:** walk each work unit, mark status checkbox (`[x] Now` / `[x] Next` / `[x] Later` / `[x] Skip`). Leave inline notes to override scope.
 2. **Orchestrator agent:** creates the worktree + branch per [Worktree setup](#worktree-setup), then dispatches work units per the [Sequencing](#sequencing--parallelism) plan. The orchestrator owns the working tree; subagents are given narrow, self-contained tasks and asked to return diffs or land commits on the shared branch.
-3. **Session end:** run acceptance checklist, update `DEVLOG.md` + `CHANGELOG.md`, open one PR for the whole branch with all unit IDs in the body.
+3. **Session end:** run acceptance checklist, update `docs/project/DEVLOG.md` + `CHANGELOG.md`, open one PR for the whole branch with all unit IDs in the body.

 ## Worktree setup

@@ -56,7 +56,7 @@ cd ../hermes-android-voice
 | **Wave 2** | V2 | Serial | Extends `VoiceViewModel.stripMarkdown()` → must land before V3 because V3's coalesce logic runs against sanitized text. |
 | **Wave 3** | V3 | Serial | Chunking changes to `VoiceViewModel.kt` — conflicts with V4. |
 | **Wave 4** | V4 | Serial | Pipelining rewrite of `VoiceViewModel.startTtsConsumer()` — takes the output of V3's chunker as input. |
-| **Wave 5** | Doc1 | Serial | `DEVLOG.md` + `CHANGELOG.md` + `user-docs/` updates after code stabilizes. |
+| **Wave 5** | Doc1 | Serial | `docs/project/DEVLOG.md` + `CHANGELOG.md` + `user-docs/` updates after code stabilizes. |

 **Shared-file hot-spot.** `VoiceViewModel.kt` is touched by V2, V3, and V4. These **must** serialize — do not parallelize them. The orchestrator should handle them in sequence (V2→V3→V4) as three commits from one agent session, not three concurrent subagents.

@@ -341,14 +341,14 @@ cd ../hermes-android-voice
 **Summary.** Capture the wave in the append-only log, bump CHANGELOG with an `[Unreleased]` entry, refresh user-docs voice-mode troubleshooting, update spec if the TTS pipeline section exists.

 **Scope / Acceptance criteria.**
- `DEVLOG.md`: append a 2026-04-16 session entry summarizing what shipped and the diagnosis chain that motivated it.
+- `docs/project/DEVLOG.md`: append a 2026-04-16 session entry summarizing what shipped and the diagnosis chain that motivated it.
 - `CHANGELOG.md`: `[Unreleased] — Changed` entry: "Voice output quality — switched to ElevenLabs flash streaming model, added client+relay text sanitization, coalesced short sentences, prefetched next sentence during playback, and swapped to ExoPlayer for gapless concatenation." Use conventional-changelog tone.
 - `user-docs/`: if there's a voice-mode page, add a "What changed in voice mode" note. If not, don't create one just for this.
 - `docs/spec.md`: if there's a voice-pipeline section, update the flow diagram or prose to reflect the prefetch + gapless architecture.
- No entry in `ROADMAP.md` — the wave is complete, not milestoned.
+- No entry in `docs/project/ROADMAP.md` — the wave is complete, not milestoned.

 **Files to touch.**
- `DEVLOG.md`
+- `docs/project/DEVLOG.md`
 - `CHANGELOG.md`
 - `user-docs/*` (conditional)
 - `docs/spec.md` (conditional)
@@ -278,13 +278,13 @@
 **Summary.** Capture the wave. Unlike the voice-quality-pass docs pass, this one DOES update `user-docs/features/voice.md` because barge-in is a user-facing feature with a settings UI they need to discover.

 **Scope.**
- `DEVLOG.md`: append 2026-04-17 entry (second of the day) summarizing the barge-in stack.
+- `docs/project/DEVLOG.md`: append 2026-04-17 entry (second of the day) summarizing the barge-in stack.
 - `CHANGELOG.md`: add to `[Unreleased]` under an `### Added — Barge-in` section.
 - `docs/spec.md` Phase V section: reference the new barge-in architecture (duplex audio, VAD, AEC, resume).
 - `user-docs/features/voice.md`: add a new "## Barge-in (interrupt the agent)" section with screenshot placeholder, settings description, device compatibility note.

 **Files to touch.**
- `DEVLOG.md`, `CHANGELOG.md`, `docs/spec.md`, `user-docs/features/voice.md`.
+- `docs/project/DEVLOG.md`, `CHANGELOG.md`, `docs/spec.md`, `user-docs/features/voice.md`.

 **Dependencies.** All B units committed.

@@ -310,7 +310,7 @@ Add option (A) to R3's acceptance criteria: `handle_sessions_list` gains a loopb

 **Root-level:**
 - `CHANGELOG.md` — new `[Unreleased]` entry under `### Added`: "Dashboard plugin with four tabs: Relay Management, Bridge Activity, Push Console (stub), Media Inspector" + brief bullet list of the three new relay routes.
- `DEVLOG.md` — session entry for 2026-04-18 dashboard plugin work: Context, Decision summary, Implementation notes (one-liner per wave), Deferred (push console needs FCM).
+- `docs/project/DEVLOG.md` — session entry for 2026-04-18 dashboard plugin work: Context, Decision summary, Implementation notes (one-liner per wave), Deferred (push console needs FCM).
 - `README.md` — add one line under Quick Start mentioning the dashboard tab becomes available after gateway restart.
 - `CLAUDE.md` — add `plugin/dashboard/` to Repository Layout; add four Key Files entries for the dashboard plugin (manifest.json, plugin_api.py, src/index.jsx, dist/index.js one-liners).

@@ -100,7 +100,7 @@ Confirm exact invocation by reading `hermes_cli/main.py:1034` area (agent will d
 ### Phase 4 — Polish + docs *(post-smoke)*
 - Update `~/.hermes/hermes-relay/README.md` with desktop install section.
 - Update hermes-relay `CHANGELOG.md` `[Unreleased]`.
- Update hermes-relay `DEVLOG.md` with session summary.
+- Update hermes-relay `docs/project/DEVLOG.md` with session summary.
 - Bump version via `scripts/bump-version.sh 0.8.0-alpha`.
 - User-docs page in `user-docs/guide/desktop.md`.

@@ -34,7 +34,7 @@

 ## Integration sequence

-1. Update ROADMAP.md with the alpha.6 scope + deferred items.
+1. Update docs/project/ROADMAP.md with the alpha.6 scope + deferred items.
 2. Launch 6 parallel agents (A–F) with isolated file ownership.
 3. I integrate cli.ts + desktop_tool.py after all agents report.
 4. Expand `npm run smoke` to cover new subcommands.
@@ -262,7 +262,7 @@ Tool calls must appear live without leaving voice mode.
 ### Wave 7 - Documentation and operator guidance

 - Update `user-docs/features/voice.md`.
- Update `TODO.md` to mark the realtime-agent TODO as planned/linked.
+- Update `docs/project/TODO.md` to mark the realtime-agent TODO as planned/linked.
 - Add troubleshooting for auth/session binding, provider disconnect fallback, and why tools still run through Hermes.
 - Add DEVLOG entry after implementation lands.

@@ -116,7 +116,7 @@ Design target:
  data, side effects, and durable transcript state
 - avoid hard-coding OpenAI WebRTC details into Android voice UX or broker core

-This is tracked in `TODO.md` under **Pluggable Realtime Agent media
+This is tracked in `docs/project/TODO.md` under **Pluggable Realtime Agent media
 transports**.

 ### 3. Map OpenAI Wire Events to Normalized Events
@@ -143,7 +143,7 @@ Owns: `plugin/dashboard/**`.

 ### Coordinator — docs (this doc + the rest)
 `docs/plans/2026-06-20-structured-media-channel.md` (Q3 plan — design only, not built here),
-`docs/decisions.md` entry, `TODO.md` follow-ups + retirement note, `DEVLOG.md`, `CHANGELOG`.
+`docs/decisions.md` entry, `docs/project/TODO.md` follow-ups + retirement note, `docs/project/DEVLOG.md`, `CHANGELOG`.

 ---

@@ -154,4 +154,4 @@ Owns: `plugin/dashboard/**`.
  unchanged; with the seam patched out / absent, no exception reaches a turn.
 - Clean UI/UX: the transport badge + ladder read clearly; the injected-context audit shows the
  exact server-side block.
- Docs updated; retirement tracked in `TODO.md`.
+- Docs updated; retirement tracked in `docs/project/TODO.md`.
@@ -135,7 +135,7 @@ A small bottom sheet that is the single place the per-surface truth + the explai

 The **plugin secure proxy** (the "Secure proxy — Not advertised" row) is a **stub today**: the Android side models it (`Endpoint.kt` `ProxyEndpoint`, `plugin_proxy` role, `hasSecureProxy()`), and `isEncryptedOverlayRoute()` already treats it as encrypted — but **the relay has no proxy-forward implementation, pairing never emits a `plugin_proxy` candidate, and no cert/pin is generated.** Enabling it end-to-end is the unbuilt **Phase 4** of `2026-06-18-native-secure-routes.md` (relay HTTP-forward routes + `RELAY_SSL_*` cert + pairing emission; ~2–3 wk).

-**Implication for this plan:** the indicator must **not block** on the proxy. We design the wording/placement so that *when* a `plugin_proxy` route is advertised it slots in as a 🔒 **TLS (pinned)** route automatically (it already would, via `isEncryptedOverlayRoute`). Until then it stays honestly "Not advertised." Recommend a separate spike to stand it up + test on the server (tracked in `TODO.md`), independent of this UX work.
+**Implication for this plan:** the indicator must **not block** on the proxy. We design the wording/placement so that *when* a `plugin_proxy` route is advertised it slots in as a 🔒 **TLS (pinned)** route automatically (it already would, via `isEncryptedOverlayRoute`). Until then it stays honestly "Not advertised." Recommend a separate spike to stand it up + test on the server (tracked in `docs/project/TODO.md`), independent of this UX work.

 ---

@@ -187,7 +187,7 @@ New bottom sheet; per-surface rows + explainer + TOFU/keystore lines + docs link
 New user-docs page + the four conflation edits + TOFU documentation.

 ### Spike — stand up & test the plugin secure proxy · L (separate, not blocking)
-Phase 4 of `2026-06-18-native-secure-routes.md`. Tracked in `TODO.md`.
+Phase 4 of `2026-06-18-native-secure-routes.md`. Tracked in `docs/project/TODO.md`.

 ---

@@ -3,7 +3,7 @@
 Triage of all 13 open GitHub issues (multi-agent code-verified pass + adversarial
 cross-check), grouped into workstreams that land on `dev` via worktree feature
 branches before the next releases. Owner-only actions (GitHub comments/closures,
-labels, Play Console, on-device checks) are tracked in `TODO.md` — automation
+labels, Play Console, on-device checks) are tracked in `docs/project/TODO.md` — automation
 never posts to GitHub on the owner's behalf.

 ## Verdict summary
@@ -3,7 +3,7 @@
 Research snapshot mapping OpenAI's realtime voice offering (as of July 2026)
 onto the hermes-relay realtime agent, to scope next-release-candidate work.
 Companion TODO items live under "OpenAI realtime provider — next-RC roadmap"
-in `TODO.md`.
+in `docs/project/TODO.md`.

 ## Repo starting point

@@ -45,7 +45,7 @@ as a collaborator. This continues that pattern.
  Run `./gradlew lint` once before the PR.
  (Use `--no-daemon`; never pipe gradle through `tail` — it masks the exit code.)
 - **Conventional Commits, one commit per extracted controller.** `--no-ff` PR into
-  `dev` at the end. Update `DEVLOG.md`.
+  `dev` at the end. Update `docs/project/DEVLOG.md`.
 - **If a cluster is too entangled** to extract without logic changes, STOP, leave it
  in place, and report — open the PR with the completed steps rather than forcing it.

@@ -111,7 +111,7 @@ change, defer it and report** — Steps 1–4 stand on their own.
  `ProfileController` extracted (Step 5 optional).
 - `compileSideloadDebugKotlin` + `compileSideloadDebugUnitTestKotlin` green; focused
  slice passes; `./gradlew lint` clean; `ArchitectureBoundaryTest` green.
- `DEVLOG.md` updated. One PR (`feature/connectionviewmodel-decomposition` → `dev`,
+- `docs/project/DEVLOG.md` updated. One PR (`feature/connectionviewmodel-decomposition` → `dev`,
  `--no-ff`). Worktree removed.
 - **Report:** `ConnectionViewModel` line-count before/after, what moved where, any
  cluster left in place + why, and any deferred cleanups noted.
@@ -102,7 +102,7 @@ Advanced users can narrow or extend this through `~/.hermes/desktop-control.json
 ### Phase 0 — Research Pack + Tech Decision (Ready Now)
 - Port this enhanced plan into repo `docs/plans/`.
 - Add ADR for Tauri choice + CLI fallback.
- Update `ROADMAP.md` and `desktop/README.md`.
+- Update `docs/project/ROADMAP.md` and `desktop/README.md`.
 - Define Easy/Standard/Advanced tiers and default blocklist.

 ### Phase 1 — Tool Schema + Server Registration
@@ -182,6 +182,6 @@ Do not ship until the user can instantly understand from the UI whether Hermes i

 **Brief goal prompt for Codex (copy-paste ready):**

-"Read the enhanced plan at docs/plans/desktop-control-computer-use-enhanced.md. Start by completing Phase 0: port the enhancements into the repo, add the Tauri decision ADR, and update ROADMAP.md. Then implement Phase 1 tool schemas while ensuring full backward compatibility with the existing desktop CLI. Focus on keeping the CLI as the primary surface and Tauri as the optional polished tray/overlay experience. Make the default pairing flow seamless for Easy-tier users."
+"Read the enhanced plan at docs/plans/desktop-control-computer-use-enhanced.md. Start by completing Phase 0: port the enhancements into the repo, add the Tauri decision ADR, and update docs/project/ROADMAP.md. Then implement Phase 1 tool schemas while ensuring full backward compatibility with the existing desktop CLI. Focus on keeping the CLI as the primary surface and Tauri as the optional polished tray/overlay experience. Make the default pairing flow seamless for Easy-tier users."

 **Current pairing/settings parity goal prompt:** use `docs/plans/2026-05-17-desktop-android-pairing-parity.md` instead for the next tray UI pass.
@@ -14,7 +14,7 @@ contract test (Plan C).
 ## Working rules

 - One branch off `dev`: `feature/upstream-relay-isolation`. Conventional Commits, one logical
-  commit per step. `--no-ff` PR into `dev` at the end. Update `DEVLOG.md`.
+  commit per step. `--no-ff` PR into `dev` at the end. Update `docs/project/DEVLOG.md`.
 - Do **NOT** run a full gradle assemble or `adb install` (on-device builds are Bailey's via
  Android Studio). DO verify with `./gradlew lint` and focused unit tests.
 - If the real code contradicts this plan, **stop and report** rather than guessing.
@@ -85,7 +85,7 @@ renamed/removed routes, misses only runtime-auth regressions. Note the tradeoff

 ## Acceptance

- ADR in `docs/decisions.md`; `DEVLOG.md` updated.
+- ADR in `docs/decisions.md`; `docs/project/DEVLOG.md` updated.
 - `network/` split into `upstream|relay|shared`; all imports updated; `./gradlew lint` clean.
 - `ArchitectureBoundaryTest` exists, is in the CI explicit `--tests` list, and passes.
 - Contract job exists, runs without the bootstrap, asserts route existence on pinned vanilla
@@ -4227,7 +4227,7 @@ Expected new keyless cold start: client ~+1–2s after first DataStore emission,

 ## 2026-05-19 — Experimental Realtime Hermes Voice Agent

-**Plan.** [docs/plans/2026-05-19-realtime-hermes-voice-agent.md](docs/plans/2026-05-19-realtime-hermes-voice-agent.md) — add a switchable Android voice engine that brokers a realtime provider session (OpenAI first, xAI ready) while keeping Hermes as authority for profiles, sessions, memory, tool execution, Android bridge safety, confirmations, and cancellation. Stable `Hermes chat + voice output` remains the default and is untouched.
+**Plan.** [`2026-05-19-realtime-hermes-voice-agent.md`](../plans/2026-05-19-realtime-hermes-voice-agent.md) — add a switchable Android voice engine that brokers a realtime provider session (OpenAI first, xAI ready) while keeping Hermes as authority for profiles, sessions, memory, tool execution, Android bridge safety, confirmations, and cancellation. Stable `Hermes chat + voice output` remains the default and is untouched.

 **Surface added.**

@@ -4384,7 +4384,7 @@ Post-fix smoke: Victor called `desktop_terminal("hostname")` → returned `{"std

 ## 2026-04-23 — Desktop CLI thin-client v0.1 (`@hermes-relay/cli`)

-**Context.** The broader ask from the vault's [Desktop Client.md](../../../SynologyDrive/-Vault-/Axiom-Vault/3.%20System/Projects/Hermes-Relay/Desktop%20Client.md) decomposes into two independent pieces: (A) "one Node binary with CLI + TUI modes that talks to a remote Hermes over WSS" and (B) "per-tool dispatch routing so local tools run on the client while the brain stays on the server." This session ships **A** — with CLI mode specifically — and defers B to a separate hermes-agent PR on `fork/tool-relay`. The two are decoupled: the CLI consumes the existing `tui` WSS channel and `tui_gateway` subprocess shape without any server-side change.
+**Context.** An earlier private design note decomposed the desktop-client work into two independent pieces: (A) "one Node binary with CLI + TUI modes that talks to a remote Hermes over WSS" and (B) "per-tool dispatch routing so local tools run on the client while the brain stays on the server." This session ships **A** — with CLI mode specifically — and defers B to a separate hermes-agent PR on `fork/tool-relay`. The two are decoupled: the CLI consumes the existing `tui` WSS channel and `tui_gateway` subprocess shape without any server-side change.

 ### Architecture decision — same channel, different renderer

@@ -0,0 +1,11 @@
+# Project records
+
+Public project-planning and engineering records live here so the repository
+root stays focused on entrypoints, build metadata, and release contracts.
+
+- [`TODO.md`](TODO.md) — the canonical home for deferred work and known gaps.
+- [`ROADMAP.md`](ROADMAP.md) — high-level product and release direction.
+- [`DEVLOG.md`](DEVLOG.md) — factual engineering history and verification notes.
+
+Keep these files depersonalized and public-safe. User-facing release history
+continues to live in the root [`CHANGELOG.md`](../../CHANGELOG.md).
@@ -1,6 +1,6 @@
 # Hermes-Relay Roadmap

-> Where Hermes-Relay is headed. Short, high-level, grouped by release milestone. For detailed implementation plans of active work see [`docs/plans/`](docs/plans/); for shipped work see [`CHANGELOG.md`](CHANGELOG.md); for the session-by-session narrative see [`DEVLOG.md`](DEVLOG.md).
+> Where Hermes-Relay is headed. Short, high-level, grouped by release milestone. For detailed implementation plans of active work see [`docs/plans/`](../plans/); for shipped work see [`CHANGELOG.md`](../../CHANGELOG.md); for the session-by-session narrative see [`DEVLOG.md`](DEVLOG.md).

 ## Vision

@@ -8,29 +8,29 @@ Native Android companion for the [Hermes agent platform](https://github.com/Nous

 ## Shipped

- **v0.3.0** — Bridge channel (sideload), voice mode, notification companion, two build flavors, full safety rails system. [CHANGELOG](CHANGELOG.md#030---2026-04-13)
- **v0.2.0** — Voice mode foundation, terminal preview, TOFU cert pinning, Paired Devices screen. [CHANGELOG](CHANGELOG.md)
+- **v0.3.0** — Bridge channel (sideload), voice mode, notification companion, two build flavors, full safety rails system. [CHANGELOG](../../CHANGELOG.md#030---2026-04-13)
+- **v0.2.0** — Voice mode foundation, terminal preview, TOFU cert pinning, Paired Devices screen. [CHANGELOG](../../CHANGELOG.md)
 - **v0.1.0** — Chat, sessions, QR pairing, encrypted storage, Play Store submission.

 ### Desktop track (parallel lane to Android) — **experimental**

-Release tags: `cli-v*` (separate cadence from Android `android-v*` and Plugin `plugin-v*`). Historical alpha prereleases used `desktop-v*`, and the installer/updater keep a migration fallback. Curl-installed prebuilt binaries (no Node required); Windows first, macOS / Linux same release. Workflows: [`ci-desktop.yml`](.github/workflows/ci-desktop.yml) + [`release-cli.yml`](.github/workflows/release-cli.yml).
+Release tags: `cli-v*` (separate cadence from Android `android-v*` and Plugin `plugin-v*`). Historical alpha prereleases used `desktop-v*`, and the installer/updater keep a migration fallback. Curl-installed prebuilt binaries (no Node required); Windows first, macOS / Linux same release. Workflows: [`ci-desktop.yml`](../../.github/workflows/ci-desktop.yml) + [`release-cli.yml`](../../.github/workflows/release-cli.yml).

 **Shipped (2026-04-23 — first tagged release `desktop-v0.3.0-alpha.1`):**

- **`@hermes-relay/cli` v0.1** — Node thin-client at [`desktop/`](desktop/). Remote chat + pair + status + tools subcommands over the relay's `tui` WSS channel. Shares `~/.hermes/remote-sessions.json` with the Android client (pair once, both work).
+- **`@hermes-relay/cli` v0.1** — Node thin-client at [`desktop/`](../../desktop/). Remote chat + pair + status + tools subcommands over the relay's `tui` WSS channel. Shares `~/.hermes/remote-sessions.json` with the Android client (pair once, both work).
 - **v0.2 — resilience + pairing UX** — multi-endpoint pairing (ADR 24: `--pair-qr` probes LAN/Tailscale/Public, strict-priority within-tier race, 4s timeout, 60s cache), reconnect-on-drop state machine (1s→30s exp backoff, 5min on 429, gate re-check post-sleep), TOFU cert pinning via pre-WS TLS probe (SPKI sha256, `sha256/<base64>` OkHttp-compatible).
 - **v0.2 — UX polish** — bare `hermes-relay` → `shell` (full Hermes CLI over PTY with `clear; exec hermes` after tmux settles); contextual connect banner (`Connected via LAN (plain) — server 0.6.0`); `status` surfaces grants + TTL + endpoint role from `auth.ok`; new `devices` subcommand talking to relay `GET/DELETE/PATCH /sessions` over HTTP.
 - **Phase B — client-side tool routing** — server-side `plugin/relay/channels/desktop.py` + `plugin/tools/desktop_tool.py` register `desktop_read_file` / `_write_file` / `_terminal` / `_search_files` / `_patch` via `tools.registry` (mirror of `android_*` pattern — **zero hermes-agent core change**). Client-side `DesktopToolRouter` attaches to the `desktop` channel, dispatches under a 30s AbortController, heartbeats `desktop.status` every 30s. One-time per-URL consent gate + `--no-tools` kill-switch.
 - **`hermes-relay daemon`** — headless WSS + tool router that keeps desktop tools serving without a visible shell. Fails closed on missing stored consent (`--allow-tools` escape hatch with an explicit `--token`). JSON-line logs by default, auto-human on TTY. Inherits transport's reconnect state machine; `setImmediate(exit)` to flush final log line before process dies.
 - **Pre-release hardening** — `hermes-relay doctor` (local diagnostic report, human + `--json`, no token leakage); `uninstall.{sh,ps1}` (3-tier: default keeps session store, `--purge` wipes it with cross-surface warning, `--service` stub); interactive first-run prompts (`resolveFirstRunUrl` — auto-picks single stored session, numbered picker for multiple, welcome banner for fresh install); version-aware install (`upgrading X → Y` readback pre-install, post-install confirmation).
- **Self-setup skill** — [`skills/devops/hermes-relay-desktop-setup/SKILL.md`](skills/devops/hermes-relay-desktop-setup/SKILL.md) lets any Hermes agent install, pair, and troubleshoot the CLI with **live local diagnostics** via `desktop_terminal` (can read the user's Node version, PATH, binary location directly — something the Android setup skill can't match).
+- **Self-setup skill** — [`skills/devops/hermes-relay-desktop-setup/SKILL.md`](../../skills/devops/hermes-relay-desktop-setup/SKILL.md) lets any Hermes agent install, pair, and troubleshoot the CLI with **live local diagnostics** via `desktop_terminal` (can read the user's Node version, PATH, binary location directly — something the Android setup skill can't match).

-**Shipped — `desktop-v0.3.0-alpha.6` (seamless-local dev pass, done 2026-04-23):** Plan at [`docs/plans/2026-04-23-desktop-alpha-6-seamless-local.md`](docs/plans/2026-04-23-desktop-alpha-6-seamless-local.md). Nine features across six parallel agent workstreams, all opt-in: workspace-awareness envelope + active-editor signal (#1+#8), `hermes-relay update` self-update subcommand (#2), `desktop_open_in_editor` tool + interactive patch approval with unified-diff rendering (#3+#4), conversation picker on connect (#5), clipboard bridge + screenshot handlers (#9+#12), and a `hermes` alias so muscle-memory works without the `-relay` suffix (#13). Integration day: 2026-04-23.
+**Shipped — `desktop-v0.3.0-alpha.6` (seamless-local dev pass, done 2026-04-23):** Plan at [`docs/plans/2026-04-23-desktop-alpha-6-seamless-local.md`](../plans/2026-04-23-desktop-alpha-6-seamless-local.md). Nine features across six parallel agent workstreams, all opt-in: workspace-awareness envelope + active-editor signal (#1+#8), `hermes-relay update` self-update subcommand (#2), `desktop_open_in_editor` tool + interactive patch approval with unified-diff rendering (#3+#4), conversation picker on connect (#5), clipboard bridge + screenshot handlers (#9+#12), and a `hermes` alias so muscle-memory works without the `-relay` suffix (#13). Integration day: 2026-04-23.

-**Active — `desktop-v0.3.0-alpha.7` (native image paste):** Plan at [`docs/plans/2026-04-23-desktop-alpha-7-native-paste.md`](docs/plans/2026-04-23-desktop-alpha-7-native-paste.md). Two-repo workstream: client slash commands `/paste` (clipboard), `/screenshot` (primary display), `/image <path>` (file) land in `hermes-relay chat`, each echoes a one-line feedback and attaches the image to the next `prompt.submit` so the vision-capable model sees it in the same turn — parity with Claude Desktop's paste UX minus OS-level Ctrl+V (terminals don't pipe image bytes to stdin). Client half is new `desktop/src/chatAttach.ts` + slash-command branches in `desktop/src/commands/chat.ts`. Server half is ONE new `@method("image.attach.bytes")` on the fork's `tui_gateway/server.py` (branch `feat/image-attach-bytes` → merged to `axiom`); the fork's existing `_enrich_with_attached_images` already handles multimodal payload plumbing and session-scoped image state, so this release is almost entirely about bridging client-captured bytes to server-side state that's been there for months. Relay channel unchanged — `tui` is a transparent RPC forwarder. Graceful fallback when hermes-host hasn't been updated yet: client catches `method not found`, prints a pointer at the axiom rollout, REPL stays alive.
+**Active — `desktop-v0.3.0-alpha.7` (native image paste):** Plan at [`docs/plans/2026-04-23-desktop-alpha-7-native-paste.md`](../plans/2026-04-23-desktop-alpha-7-native-paste.md). Two-repo workstream: client slash commands `/paste` (clipboard), `/screenshot` (primary display), `/image <path>` (file) land in `hermes-relay chat`, each echoes a one-line feedback and attaches the image to the next `prompt.submit` so the vision-capable model sees it in the same turn — parity with Claude Desktop's paste UX minus OS-level Ctrl+V (terminals don't pipe image bytes to stdin). Client half is new `desktop/src/chatAttach.ts` + slash-command branches in `desktop/src/commands/chat.ts`. Server half is ONE new `@method("image.attach.bytes")` on the fork's `tui_gateway/server.py` (branch `feat/image-attach-bytes` → merged to `axiom`); the fork's existing `_enrich_with_attached_images` already handles multimodal payload plumbing and session-scoped image state, so this release is almost entirely about bridging client-captured bytes to server-side state that's been there for months. Relay channel unchanged — `tui` is a transparent RPC forwarder. Graceful fallback when hermes-host hasn't been updated yet: client catches `method not found`, prints a pointer at the axiom rollout, REPL stays alive.

-**Active — desktop control / computer-use:** Enhanced plan at [`docs/plans/desktop-control-computer-use-enhanced.md`](docs/plans/desktop-control-computer-use-enhanced.md); earlier MVP implementation record at [`docs/plans/desktop-computer-use-mvp.md`](docs/plans/desktop-computer-use-mvp.md). Windows now has the first Tauri tray/overlay app as the primary Easy/Standard install surface: pair, start/pause daemon, Devices/Revoke, Task Log, Settings, overlay status chip, emergency stop, and bundled CLI sidecar. The existing CLI and daemon remain the primary advanced/headless surface. `desktop_computer_*` schemas are registered on the normal desktop tool channel but advertised only behind the explicit experimental computer-use flag. Host input still requires desktop-tool consent plus a visible, task-scoped assist/control grant; there is no unrestricted or silent mouse/keyboard automation.
+**Active — desktop control / computer-use:** Enhanced plan at [`docs/plans/desktop-control-computer-use-enhanced.md`](../plans/desktop-control-computer-use-enhanced.md); earlier MVP implementation record at [`docs/plans/desktop-computer-use-mvp.md`](../plans/desktop-computer-use-mvp.md). Windows now has the first Tauri tray/overlay app as the primary Easy/Standard install surface: pair, start/pause daemon, Devices/Revoke, Task Log, Settings, overlay status chip, emergency stop, and bundled CLI sidecar. The existing CLI and daemon remain the primary advanced/headless surface. `desktop_computer_*` schemas are registered on the normal desktop tool channel but advertised only behind the explicit experimental computer-use flag. Host input still requires desktop-tool consent plus a visible, task-scoped assist/control grant; there is no unrestricted or silent mouse/keyboard automation.

 **Desktop control UX direction:** Tauri v2 (Rust + static web UI) is the native shell for the polished Easy-tier experience: tray icon, always-visible overlay chip, task log, settings, and one-click pause/emergency stop. Easy tier pairs once, shows a connected/observing chip, and exposes Devices / Revoke / Task Log / Settings / Emergency Stop from the tray. Standard tier adds full tray management; Advanced tier remains CLI + daemon + JSON policy (`~/.hermes/desktop-control.json`) for operators. The default policy baseline blocks password managers, credential prompts, banking/payment/crypto surfaces, OS security/admin settings, and private-key/token material until locally overridden.

@@ -64,7 +64,7 @@ Moving the Play Store listing from a personal account to the DUNS-verified Axiom

 ## Next — v0.4: Bridge feature expansion

-Detailed plan: [`docs/plans/2026-04-13-bridge-feature-expansion.md`](docs/plans/2026-04-13-bridge-feature-expansion.md).
+Detailed plan: [`docs/plans/2026-04-13-bridge-feature-expansion.md`](../plans/2026-04-13-bridge-feature-expansion.md).

 Expands the bridge channel's tool surface substantially, ports reliability patterns from the broader Hermes-Android ecosystem, and ships a per-app playbook skill so the agent has ready-made procedures for common apps out of the box.

@@ -84,16 +84,16 @@ Expands the bridge channel's tool surface substantially, ports reliability patte

 Small follow-ons to v0.4 deliberately deferred to keep the v0.4.0 release surface focused.

-**Unattended access mode** *(sideload-only).* ~~Opt-in toggle on the Bridge tab that acquires `FULL_WAKE_LOCK + ACQUIRE_CAUSES_WAKEUP`, raises `SCREEN_OFF_TIMEOUT` to max while active, and requests `KeyguardManager.requestDismissKeyguard()` so the agent can drive the device while the user is away.~~ **SHIPPED in v0.4.1** — see [`CHANGELOG.md`](CHANGELOG.md#041---unreleased). Final shape: opt-in toggle on the Bridge tab (sideload-only) that acquires `SCREEN_BRIGHT_WAKE_LOCK | ACQUIRE_CAUSES_WAKEUP | ON_AFTER_RELEASE` per bridge action, calls `KeyguardManager.requestDismissKeyguard()` via the registered MainActivity host, and reports `keyguard_blocked` (HTTP 423) when a credential lock blocks the action. Hard-bounded by the existing bridge auto-disable timer; persistent foreground-service notification + amber "Unattended ON" status-overlay chip stay visible while active; first-enable shows a scary dialog explaining the security model and credential-lock limitation. The original spec mentioned a WiFi-disconnect failsafe — rejected during implementation because Tailscale / VPN invalidates the "leaving WiFi = leaving LAN" assumption; the existing relay-disconnect detection (master toggle drops on disconnect → `UnattendedAccessManager.release()`) plus the auto-disable timer cover that surface.
+**Unattended access mode** *(sideload-only).* ~~Opt-in toggle on the Bridge tab that acquires `FULL_WAKE_LOCK + ACQUIRE_CAUSES_WAKEUP`, raises `SCREEN_OFF_TIMEOUT` to max while active, and requests `KeyguardManager.requestDismissKeyguard()` so the agent can drive the device while the user is away.~~ **SHIPPED in v0.4.1** — see [`CHANGELOG.md`](../../CHANGELOG.md#041---unreleased). Final shape: opt-in toggle on the Bridge tab (sideload-only) that acquires `SCREEN_BRIGHT_WAKE_LOCK | ACQUIRE_CAUSES_WAKEUP | ON_AFTER_RELEASE` per bridge action, calls `KeyguardManager.requestDismissKeyguard()` via the registered MainActivity host, and reports `keyguard_blocked` (HTTP 423) when a credential lock blocks the action. Hard-bounded by the existing bridge auto-disable timer; persistent foreground-service notification + amber "Unattended ON" status-overlay chip stay visible while active; first-enable shows a scary dialog explaining the security model and credential-lock limitation. The original spec mentioned a WiFi-disconnect failsafe — rejected during implementation because Tailscale / VPN invalidates the "leaving WiFi = leaving LAN" assumption; the existing relay-disconnect detection (master toggle drops on disconnect → `UnattendedAccessManager.release()`) plus the auto-disable timer cover that surface.

 **Voice intent local dispatch loop.** The v0.4 voice intent handler builds `bridge.command` envelopes and routes them through the `ChannelMultiplexer` → WSS → relay → back-to-phone path, which the relay correctly rejects with `ignoring unexpected bridge.command from phone` (the wire protocol is server→phone only by design). Voice intents are phone-local, so the dispatch should be local: extend `BridgeCommandHandler` with a `handleLocalCommand(envelope)` entry point that runs the existing `when(path)` dispatch + the full Tier 5 safety check pipeline (blocklist → destructive verb modal → action executor) in-process, and have `RealVoiceBridgeIntentHandler.dispatch()` call it instead of `multiplexer.send()`. Single source of truth for "bridge command → action" preserved; safety modals still fire for destructive verbs; no WSS round-trip for an action that's happening on the same device. Caught by Bailey's on-device test 2026-04-14 after the multiplexer-wiring fix unblocked the dispatch path.

-**~~Tiered permission checklist with JIT permission errors~~ — shipped on `feature/tiered-permissions` (v0.4.1).** See [CHANGELOG.md](CHANGELOG.md) under `[Unreleased] → v0.4.1 Bridge fast-follows` for the landed surface. Original scope:
+**~~Tiered permission checklist with JIT permission errors~~ — shipped on `feature/tiered-permissions` (v0.4.1).** See [CHANGELOG.md](../../CHANGELOG.md) under `[Unreleased] → v0.4.1 Bridge fast-follows` for the landed surface. Original scope:

 - Tiered checklist with sideload-only sections gated on `BuildFlavor.SIDELOAD` (Core bridge / Notification companion / Voice & camera / Sideload features), Optional pills, runtime-permission launchers, ON_RESUME re-probes — done.
 - JIT permission-denied surfacing — bridge tool error envelope carries canonical `code` + `permission` aliases, Python `ResolveResult` types in `plugin/tools/resolve_result.py`, agent-tool wrappers upgrade `permission_denied` responses to structured LLM-readable envelopes, voice-mode JIT chip deep-links to `Settings.ACTION_APPLICATION_DETAILS_SETTINGS` for the running package — done.

-**Voice intent → server session sync.** ✅ **Shipped 2026-04-16** — see [CHANGELOG `[Unreleased]`](CHANGELOG.md#unreleased) for the implementation. Picked option (d) (not in the original menu): synthesize OpenAI-format `assistant` (with `tool_calls`) + `tool` (with `tool_call_id`) message pairs from local voice-intent traces and pass them under a new `messages` field on the existing `/v1/runs` and `/api/sessions/{id}/chat/stream` payloads. LLMs are trained on this exact shape so they read it as natural conversation history rather than a system-prompt side note (lower retry risk than option (b)). Zero server changes (option (a) avoided), no double-dispatch (option (c) avoided). Idempotency via a `syncedToServer` flag on each trace.
+**Voice intent → server session sync.** ✅ **Shipped 2026-04-16** — see [CHANGELOG `[Unreleased]`](../../CHANGELOG.md#unreleased) for the implementation. Picked option (d) (not in the original menu): synthesize OpenAI-format `assistant` (with `tool_calls`) + `tool` (with `tool_call_id`) message pairs from local voice-intent traces and pass them under a new `messages` field on the existing `/v1/runs` and `/api/sessions/{id}/chat/stream` payloads. LLMs are trained on this exact shape so they read it as natural conversation history rather than a system-prompt side note (lower retry risk than option (b)). Zero server changes (option (a) avoided), no double-dispatch (option (c) avoided). Idempotency via a `syncedToServer` flag on each trace.

 **Original problem statement (preserved for context):** Voice intents currently dispatch in-process (good for latency) and append a **local-only** trace to chat history (good for visual continuity), but the server-side session never sees them — so the gateway LLM has no memory of prior voice actions when the user follows up via text or voice. Symptom: user says "open Chrome" via voice (works), then says "did that work?" → LLM responds "I have no prior context for what you're asking about". Caught by Bailey's on-device test 2026-04-14: "The chat is resetting on voice or with our tools?" — actually voice intents bypass chat entirely, but the user-visible effect is the same.

@@ -117,7 +117,7 @@ Shape subject to change. Each theme needs a separate design + plan pass before i

 ### Desktop thin-client — Phase B (client-side tool routing)

-v0.1 ships a remote-chat CLI. Phase B is the bigger win: **per-tool dispatch routing** so file/terminal/browser tools run against the user's machine while state tools (memory, skills, sessions, cron) stay on the server. Design detailed in the vault under `Axiom-Vault/3. System/Projects/Hermes-Relay/Desktop Client.md`. Key insertion point is hermes-agent `model_tools.py::handle_function_call()` (~line 517) — before `registry.dispatch()`, consult a session-scoped routing table populated by a relay handshake extension where the client advertises which tools it can service. Isomorphic to how `android_*` tools already flow through the `bridge.command` channel. Proposed branch: `fork/tool-relay` on the hermes-agent fork; upstream issue to open before merging. Blocked on: (a) the handshake extension in `plugin/relay/auth.py` to carry the advertised-tools list, (b) a new `desktop.command` channel mirroring `bridge.command` semantics, (c) the upstream PR conversation.
+v0.1 ships a remote-chat CLI. Phase B is the bigger win: **per-tool dispatch routing** so file/terminal/browser tools run against the user's machine while state tools (memory, skills, sessions, cron) stay on the server. An earlier private design note supplied the initial decomposition. Key insertion point is hermes-agent `model_tools.py::handle_function_call()` (~line 517) — before `registry.dispatch()`, consult a session-scoped routing table populated by a relay handshake extension where the client advertises which tools it can service. Isomorphic to how `android_*` tools already flow through the `bridge.command` channel. Proposed branch: `fork/tool-relay` on the hermes-agent fork; upstream issue to open before merging. Blocked on: (a) the handshake extension in `plugin/relay/auth.py` to carry the advertised-tools list, (b) a new `desktop.command` channel mirroring `bridge.command` semantics, (c) the upstream PR conversation.

 ### Observability & introspection
 - Real-time accessibility event streaming for reactive workflows (`android_events`, `android_event_stream`)
@@ -154,6 +154,6 @@ Dedicated **"Hermes Phone"** — a device (or phone ROM) that boots straight int

 New ideas enter via: direct proposals in GitHub issues, comparison passes against similar projects, community feedback from users and contributors, or internal research that turns into a shipped prototype.

-Active work waves (like the v0.4 bridge feature expansion above) get their detailed implementation plans in [`docs/plans/`](docs/plans/). When a plan wave ships, its plan file is archived or removed and the items migrate into [`CHANGELOG.md`](CHANGELOG.md).
+Active work waves (like the v0.4 bridge feature expansion above) get their detailed implementation plans in [`docs/plans/`](../plans/). When a plan wave ships, its plan file is archived or removed and the items migrate into [`CHANGELOG.md`](../../CHANGELOG.md).

 Have an idea? [Open an issue](https://github.com/Codename-11/hermes-relay/issues/new) — every one is read.
@@ -0,0 +1,49 @@
+# Hermes-Relay
+
+**Läuft auf deinem Rechner. Ist auf deinen Geräten dabei.**
+
+[English](../../README.md) · **Deutsch** · [Español](README.es.md) · [日本語](README.ja.md) · [Português (Brasil)](README.pt-BR.md) · [Русский](README.ru.md) · [简体中文](README.zh-CN.md)
+
+> Englisch ist die verbindliche und vollständige Projektbeschreibung. Diese
+> KI-gestützte Übersetzung ist ein gepflegter, kompakter Einstieg.
+
+Hermes-Relay bringt deinen [Hermes Agent](https://github.com/NousResearch/hermes-agent)
+auf Android und verbundene Computer. Hermes läuft weiterhin auf deinem eigenen
+Rechner; Hermes-Relay stellt die nativen Oberflächen und optionalen Erweiterungen bereit.
+
+## Kernfunktionen
+
+- **Android:** Streaming-Chat, Sitzungen, eingehende Dateien, Manage, Voice und Petdex.
+- **Standardverbindung:** Chat, Manage, Sitzungen, Voice und Dateien nutzen direkt das unveränderte Hermes Dashboard/Gateway.
+- **Optionale Relay-Erweiterung:** Terminal/TUI, Benachrichtigungen, Desktop-Werkzeuge, erweiterte Voice, Relay-Sitzungen und Medienfunktionen.
+- **Sideload-Version:** ergänzt zustimmungspflichtige Device-Control-Funktionen wie Bildschirmlesen, Tippen und Navigation.
+- **CLI / UI:** verbindet Computer direkt mit Relay und stellt zustimmungspflichtige Datei-, Terminal-, Such- und Screenshot-Werkzeuge bereit.
+
+## Schnellstart für Android
+
+1. Installiere die App über [Google Play](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay) oder lade die signierte Sideload-APK aus den neuesten [`android-v*` Releases](https://github.com/Codename-11/hermes-relay/releases) herunter.
+2. Starte auf dem Hermes-Rechner die Standardoberfläche:
+
+   ```bash
+   hermes dashboard
+   ```
+
+3. Öffne in Android **Connect**, suche Hermes im LAN oder gib die Dashboard-Adresse ein und melde dich an. Für den Standardweg sind weder Relay noch ein separater API-Schlüssel erforderlich.
+4. Installiere Relay nur für die zusätzlichen Funktionen:
+
+   ```bash
+   hermes plugins install Codename-11/hermes-relay/plugin --enable
+   hermes relay doctor
+   hermes relay start --no-ssl
+   ```
+
+   Verwende `--no-ssl` nur in einem vertrauenswürdigen LAN oder VPN. Kopple danach über **Relay → Pair new device** im Dashboard.
+
+## Weitere Informationen
+
+[Deutscher Schnellstart](https://hermes-relay.dev/docs/de/guide/quick-start) ·
+[Installation](https://hermes-relay.dev/docs/de/guide/getting-started) ·
+[Fehlerbehebung](https://hermes-relay.dev/docs/de/guide/troubleshooting) ·
+[Vollständige englische Dokumentation](https://hermes-relay.dev/docs/)
+
+[MIT-Lizenz](../../LICENSE)
@@ -0,0 +1,49 @@
+# Hermes-Relay
+
+**Se ejecuta en tu equipo. Te acompaña en tus dispositivos.**
+
+[English](../../README.md) · [Deutsch](README.de.md) · **Español** · [日本語](README.ja.md) · [Português (Brasil)](README.pt-BR.md) · [Русский](README.ru.md) · [简体中文](README.zh-CN.md)
+
+> El inglés es la descripción canónica y completa del proyecto. Esta traducción
+> asistida por IA es una introducción breve y mantenida.
+
+Hermes-Relay lleva tu [Hermes Agent](https://github.com/NousResearch/hermes-agent)
+a Android y a equipos conectados. Hermes sigue ejecutándose en tu propia máquina;
+Hermes-Relay aporta interfaces nativas y extensiones opcionales.
+
+## Funciones principales
+
+- **Android:** chat en streaming, sesiones, archivos entrantes, Manage, voz y Petdex.
+- **Conexión estándar:** chat, Manage, sesiones, voz y archivos se conectan directamente al Dashboard/Gateway de Hermes sin modificar.
+- **Extensión Relay opcional:** Terminal/TUI, notificaciones, herramientas de escritorio, voz mejorada, sesiones Relay y funciones multimedia.
+- **Versión sideload:** añade Device Control con confirmación para leer la pantalla, tocar y navegar.
+- **CLI / UI:** conecta equipos directamente con Relay y ofrece herramientas de archivos, terminal, búsqueda y capturas sujetas a consentimiento.
+
+## Inicio rápido en Android
+
+1. Instala la aplicación desde [Google Play](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay) o descarga la APK sideload firmada desde la versión [`android-v*` más reciente](https://github.com/Codename-11/hermes-relay/releases).
+2. Inicia la superficie estándar en el equipo que ejecuta Hermes:
+
+   ```bash
+   hermes dashboard
+   ```
+
+3. En Android, abre **Connect**, busca Hermes en la red local o escribe la dirección del Dashboard e inicia sesión. La ruta estándar no necesita Relay ni una clave de API independiente.
+4. Instala Relay solo si quieres las funciones adicionales:
+
+   ```bash
+   hermes plugins install Codename-11/hermes-relay/plugin --enable
+   hermes relay doctor
+   hermes relay start --no-ssl
+   ```
+
+   Usa `--no-ssl` únicamente en una red local o VPN de confianza. Después, vincula el dispositivo desde **Relay → Pair new device** en el Dashboard.
+
+## Más información
+
+[Inicio rápido en español](https://hermes-relay.dev/docs/es/guide/quick-start) ·
+[Instalación](https://hermes-relay.dev/docs/es/guide/getting-started) ·
+[Solución de problemas](https://hermes-relay.dev/docs/es/guide/troubleshooting) ·
+[Documentación completa en inglés](https://hermes-relay.dev/docs/)
+
+[Licencia MIT](../../LICENSE)
@@ -0,0 +1,49 @@
+# Hermes-Relay
+
+**自分のマシンで動作し、いつものデバイスから使えます。**
+
+[English](../../README.md) · [Deutsch](README.de.md) · [Español](README.es.md) · **日本語** · [Português (Brasil)](README.pt-BR.md) · [Русский](README.ru.md) · [简体中文](README.zh-CN.md)
+
+> 英語版が完全かつ正規のプロジェクト説明です。この AI 支援翻訳は、
+> 継続的に管理される簡潔な導入ページです。
+
+Hermes-Relay は、[Hermes Agent](https://github.com/NousResearch/hermes-agent)
+を Android と接続済みコンピューターから使えるようにします。Hermes 本体は
+自分のマシンで動作し続け、Hermes-Relay がネイティブ UI と任意の拡張機能を提供します。
+
+## 主な機能
+
+- **Android:** ストリーミング Chat、Sessions、受信ファイル、Manage、Voice、Petdex。
+- **標準接続:** Chat、Manage、Sessions、Voice、Files は、変更を加えていない Hermes Dashboard/Gateway に直接接続します。
+- **任意の Relay 拡張:** Terminal/TUI、通知、デスクトップツール、拡張 Voice、Relay Sessions、メディア機能。
+- **Sideload 版:** 画面読み取り、タップ、ナビゲーションなど、確認が必要な Device Control を追加します。
+- **CLI / UI:** コンピューターを Relay に直接接続し、同意制のファイル、ターミナル、検索、スクリーンショットツールを提供します。
+
+## Android クイックスタート
+
+1. [Google Play](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay) からインストールするか、最新の [`android-v*` リリース](https://github.com/Codename-11/hermes-relay/releases)から署名済み Sideload APK をダウンロードします。
+2. Hermes を実行しているマシンで標準の接続先を起動します。
+
+   ```bash
+   hermes dashboard
+   ```
+
+3. Android で **Connect** を開き、LAN 内の Hermes を検索するか Dashboard アドレスを入力してサインインします。標準経路では Relay も別の API キーも不要です。
+4. 追加機能が必要な場合だけ Relay をインストールします。
+
+   ```bash
+   hermes plugins install Codename-11/hermes-relay/plugin --enable
+   hermes relay doctor
+   hermes relay start --no-ssl
+   ```
+
+   `--no-ssl` は信頼できる LAN または VPN 内でのみ使用してください。その後、Dashboard の **Relay → Pair new device** からペアリングします。
+
+## 詳細
+
+[日本語クイックスタート](https://hermes-relay.dev/docs/ja/guide/quick-start) ·
+[インストール](https://hermes-relay.dev/docs/ja/guide/getting-started) ·
+[トラブルシューティング](https://hermes-relay.dev/docs/ja/guide/troubleshooting) ·
+[完全な英語ドキュメント](https://hermes-relay.dev/docs/)
+
+[MIT ライセンス](../../LICENSE)
@@ -0,0 +1,49 @@
+# Hermes-Relay
+
+**Roda na sua máquina. Acompanha você nos seus dispositivos.**
+
+[English](../../README.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [日本語](README.ja.md) · **Português (Brasil)** · [Русский](README.ru.md) · [简体中文](README.zh-CN.md)
+
+> O inglês é a descrição canônica e completa do projeto. Esta tradução assistida
+> por IA é uma introdução compacta e mantida.
+
+O Hermes-Relay leva seu [Hermes Agent](https://github.com/NousResearch/hermes-agent)
+para o Android e computadores conectados. O Hermes continua rodando na sua própria
+máquina; o Hermes-Relay fornece interfaces nativas e extensões opcionais.
+
+## Recursos principais
+
+- **Android:** chat com streaming, sessões, arquivos recebidos, Manage, voz e Petdex.
+- **Conexão padrão:** chat, Manage, sessões, voz e arquivos se conectam diretamente ao Dashboard/Gateway do Hermes sem modificações.
+- **Extensão Relay opcional:** Terminal/TUI, notificações, ferramentas de desktop, voz aprimorada, sessões Relay e recursos de mídia.
+- **Versão sideload:** adiciona Device Control com confirmação para ler a tela, tocar e navegar.
+- **CLI / UI:** conecta computadores diretamente ao Relay e oferece ferramentas de arquivos, terminal, busca e captura de tela com consentimento.
+
+## Início rápido no Android
+
+1. Instale pelo [Google Play](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay) ou baixe o APK sideload assinado na versão [`android-v*` mais recente](https://github.com/Codename-11/hermes-relay/releases).
+2. Inicie a superfície padrão na máquina que executa o Hermes:
+
+   ```bash
+   hermes dashboard
+   ```
+
+3. No Android, abra **Connect**, procure o Hermes na rede local ou informe o endereço do Dashboard e entre. O caminho padrão não exige Relay nem uma chave de API separada.
+4. Instale o Relay apenas se quiser os recursos adicionais:
+
+   ```bash
+   hermes plugins install Codename-11/hermes-relay/plugin --enable
+   hermes relay doctor
+   hermes relay start --no-ssl
+   ```
+
+   Use `--no-ssl` somente em uma rede local ou VPN confiável. Depois, faça o pareamento em **Relay → Pair new device** no Dashboard.
+
+## Saiba mais
+
+[Início rápido em português](https://hermes-relay.dev/docs/pt-BR/guide/quick-start) ·
+[Instalação](https://hermes-relay.dev/docs/pt-BR/guide/getting-started) ·
+[Solução de problemas](https://hermes-relay.dev/docs/pt-BR/guide/troubleshooting) ·
+[Documentação completa em inglês](https://hermes-relay.dev/docs/)
+
+[Licença MIT](../../LICENSE)
@@ -0,0 +1,52 @@
+# Hermes-Relay
+
+**Работает на вашем компьютере. Доступен с ваших устройств.**
+
+[English](../../README.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [日本語](README.ja.md) · [Português (Brasil)](README.pt-BR.md) · **Русский** · [简体中文](README.zh-CN.md)
+
+> Английская версия — полное и каноническое описание проекта. Этот перевод,
+> выполненный с помощью ИИ, — краткое поддерживаемое введение.
+
+Hermes-Relay переносит ваш [Hermes Agent](https://github.com/NousResearch/hermes-agent)
+на Android и подключённые компьютеры. Сам Hermes продолжает работать на вашем
+компьютере, а Hermes-Relay предоставляет нативные интерфейсы и дополнительные расширения.
+
+## Основные возможности
+
+- **Android:** потоковый чат, сессии, входящие файлы, Manage, голосовой режим и Petdex.
+- **Стандартное подключение:** чат, Manage, сессии, голос и файлы подключаются напрямую к неизменённому Hermes Dashboard/Gateway.
+- **Необязательное расширение Relay:** Terminal/TUI, уведомления, инструменты рабочего стола, расширенный голосовой режим, сессии Relay и работа с медиа.
+- **Sideload-версия:** добавляет Device Control с подтверждением для чтения экрана, нажатий и навигации.
+- **CLI / UI:** подключает компьютеры напрямую к Relay и предоставляет требующие согласия инструменты для файлов, терминала, поиска и снимков экрана.
+
+## Быстрый старт на Android
+
+1. Установите приложение из [Google Play](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay) или загрузите подписанный sideload APK из последнего выпуска [`android-v*`](https://github.com/Codename-11/hermes-relay/releases).
+2. Запустите стандартную поверхность на компьютере с Hermes:
+
+   ```bash
+   hermes dashboard
+   ```
+
+3. На Android откройте **Connect**, найдите Hermes в локальной сети или введите адрес Dashboard и войдите в систему. Для стандартного пути не нужны Relay или отдельный API-ключ.
+4. Установите Relay, только если нужны дополнительные возможности:
+
+   ```bash
+   hermes plugins install Codename-11/hermes-relay/plugin --enable
+   hermes relay doctor
+   hermes relay start --no-ssl
+   ```
+
+   Используйте `--no-ssl` только в доверенной локальной сети или VPN. Затем выполните сопряжение через **Relay → Pair new device** в Dashboard.
+
+## Подробнее
+
+Русская пользовательская документация пока не локализована. Быстро меняющиеся
+сведения остаются каноническими на английском:
+
+[Быстрый старт на английском](https://hermes-relay.dev/docs/guide/quick-start) ·
+[Установка](https://hermes-relay.dev/docs/guide/getting-started) ·
+[Устранение неполадок](https://hermes-relay.dev/docs/guide/troubleshooting) ·
+[Полная документация](https://hermes-relay.dev/docs/)
+
+[Лицензия MIT](../../LICENSE)
@@ -0,0 +1,48 @@
+# Hermes-Relay
+
+**运行在您的电脑上，连接到您的设备。**
+
+[English](../../README.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [日本語](README.ja.md) · [Português (Brasil)](README.pt-BR.md) · [Русский](README.ru.md) · **简体中文**
+
+> 英文版是完整、规范的项目说明。此 AI 辅助翻译是持续维护的精简入门页。
+
+Hermes-Relay 将您的 [Hermes Agent](https://github.com/NousResearch/hermes-agent)
+带到 Android 和已连接的电脑上。Hermes 仍在您自己的电脑上运行；
+Hermes-Relay 提供原生界面和可选扩展。
+
+## 核心功能
+
+- **Android：**流式聊天、会话、接收文件、Manage、语音和 Petdex。
+- **标准连接：**聊天、Manage、会话、语音和文件直接连接未修改的 Hermes Dashboard/Gateway。
+- **可选 Relay 扩展：**Terminal/TUI、通知、桌面工具、增强语音、Relay 会话和媒体功能。
+- **Sideload 版本：**增加需要确认的 Device Control，可读取屏幕、点击和导航。
+- **CLI / UI：**电脑直接连接 Relay，并提供需要授权的文件、终端、搜索和截图工具。
+
+## Android 快速开始
+
+1. 从 [Google Play](https://play.google.com/store/apps/details?id=com.axiomlabs.hermesrelay) 安装，或从最新 [`android-v*` 版本](https://github.com/Codename-11/hermes-relay/releases)下载已签名的 Sideload APK。
+2. 在运行 Hermes 的电脑上启动标准连接界面：
+
+   ```bash
+   hermes dashboard
+   ```
+
+3. 在 Android 中打开 **Connect**，在局域网中查找 Hermes，或输入 Dashboard 地址并登录。标准路径不需要 Relay，也不需要单独的 API 密钥。
+4. 仅在需要附加功能时安装 Relay：
+
+   ```bash
+   hermes plugins install Codename-11/hermes-relay/plugin --enable
+   hermes relay doctor
+   hermes relay start --no-ssl
+   ```
+
+   `--no-ssl` 仅限可信局域网或 VPN。然后在 Dashboard 中通过 **Relay → Pair new device** 配对。
+
+## 了解更多
+
+[中文快速开始](https://hermes-relay.dev/docs/zh-CN/guide/quick-start) ·
+[安装与设置](https://hermes-relay.dev/docs/zh-CN/guide/getting-started) ·
+[故障排除](https://hermes-relay.dev/docs/zh-CN/guide/troubleshooting) ·
+[完整英文文档](https://hermes-relay.dev/docs/)
+
+[MIT 许可证](../../LICENSE)
@@ -280,4 +280,4 @@ keeping route ownership explicit:
  `webui` as a rich-chat prompt hint; upstream removed that unused path at the
  verified `b20cc5f` snapshot. Hermes has no stable `android` or mobile platform
  hint, so Android must not claim Desktop parity or invent one. The upstream
-  platform-hint follow-up is tracked in `TODO.md`.
+  platform-hint follow-up is tracked in `docs/project/TODO.md`.
@@ -1,6 +1,12 @@
 # Hermes Quest

-Spatial SDK Quest app for the Hermes relay terminal cockpit.
+> **Status: quarantined experiment.** This project is not shipped, supported,
+> or exercised by normal Hermes-Relay CI. It is preserved as a standalone
+> prototype for a possible future spatial terminal and voice client.
+
+Spatial SDK Quest prototype for the Hermes relay terminal cockpit. Its
+Quest-specific transport and UI modules live beside it so the production
+Android build remains independent.

 ## Build

@@ -8,19 +14,19 @@ From the repo root:

 ```powershell
 $env:ANDROID_HOME='C:\Users\Bailey\AppData\Local\Android\Sdk'
-.\gradlew.bat :quest:assembleDebug --console=plain
+.\gradlew.bat -p experiments\quest assembleDebug --console=plain
 ```

 APK:

 ```text
-quest\build\outputs\apk\debug\quest-debug.apk
+experiments\quest\build\outputs\apk\debug\quest-debug.apk
 ```

 Install on a connected Quest:

 ```powershell
-adb install -r quest\build\outputs\apk\debug\quest-debug.apk
+adb install -r experiments\quest\build\outputs\apk\debug\quest-debug.apk
 adb shell monkey -p com.axiomlabs.hermesquest.debug 1
 ```

@@ -54,7 +60,9 @@ and MorphingSphere listening/speaking hooks.

 ## Tooling

-Use Android Studio for Kotlin, Compose, Gradle, logcat, and direct install/run. Open the repo root when working across `:app`, `:relay-core`, and `:relay-ui`; open `quest/` directly when focusing on Spatial SDK or Meta Spatial Editor tasks.
+Use Android Studio for Kotlin, Compose, Gradle, logcat, and direct install/run.
+Open `experiments/quest/` as its own Gradle project. The production repo root
+does not include this experiment in its project graph.

 Use Meta Quest Developer Hub for headset setup, ADB pairing, install/uninstall, casting, logcat, and quick device state checks.

@@ -62,8 +70,8 @@ Use Meta Spatial Editor when editing/exporting `.metaspatial`/`.glxf` scenes or

 ```powershell
 $env:ANDROID_HOME='C:\Users\Bailey\AppData\Local\Android\Sdk'
-.\gradlew.bat :quest:export -Pquest.exportScenes=true --console=plain
-.\gradlew.bat :quest:hotReload -Pquest.exportScenes=true --console=plain
+.\gradlew.bat -p experiments\quest export -Pquest.exportScenes=true --console=plain
+.\gradlew.bat -p experiments\quest hotReload -Pquest.exportScenes=true --console=plain
 ```

 Normal `assembleDebug` does not require Meta Spatial Editor. The app creates a programmatic spatial terminal panel when exported GLXF scene assets are absent.
@@ -7,6 +7,7 @@ pluginManagement {
    plugins {
        id("com.android.application") version "9.3.2"
        id("com.android.library") version "9.3.2"
+        id("org.jetbrains.kotlin.jvm") version "2.4.10"
        id("org.jetbrains.kotlin.plugin.compose") version "2.4.10"
        id("org.jetbrains.kotlin.plugin.serialization") version "2.4.10"
    }
@@ -20,10 +21,8 @@ dependencyResolutionManagement {
    }
 }

-rootProject.name = "quest"
+rootProject.name = "hermes-quest-experiment"

 include(":relay-core")
 include(":relay-ui")
-
-project(":relay-core").projectDir = file("../relay-core")
-project(":relay-ui").projectDir = file("../relay-ui")
+include(":ui-preview")
@@ -2,8 +2,9 @@

 A JVM-only **Compose for Desktop** module for iterating on presentational
 composables **on the PC with hot reload** — edit, see it live, no
-build/deploy/test loop on a device. It is **not shipped**: nothing in the app,
-plugin, or CLI release builds depends on it.
+build/deploy/test loop on a device. It belongs only to the quarantined Quest
+experiment and is **not shipped**: nothing in the production app, plugin, or
+CLI release builds depends on it.

 ## Why this exists

@@ -21,16 +22,15 @@ module *or* to the shared `MorphingSphereCore.kt` reload live.
 **Cold run (no hot reload):**

 ```bash
-./gradlew :ui-preview:run
+./gradlew -p experiments/quest :ui-preview:run
 ```

-> **First-sync check:** this is the only piece of the dev tooling that pins a
-> Compose Multiplatform version (`org.jetbrains.compose` `1.10.3` in
-> `build.gradle.kts`) against the repo's Kotlin (`2.3.21`). If a future Kotlin bump
+> **First-sync check:** this experimental tooling pins a Compose Multiplatform
+> version (`org.jetbrains.compose` `1.12.0` in `build.gradle.kts`) against the
+> Quest build's Kotlin (`2.4.10`). If a future Kotlin bump
 > breaks the pairing, realign per the
 > [Compose compatibility matrix](https://kotlinlang.org/docs/multiplatform/compose-compatibility-and-versioning.html).
-> The module is fully additive — removing the `include(":ui-preview")` line in
-> `settings.gradle.kts` drops it with zero impact on shipped builds.
+> The module is fully additive inside the quarantined build.

 ## What can live here

@@ -41,16 +41,15 @@ the network must be fed **fake state** from the gallery controls.

 ### The single-source-of-truth pattern

-The sphere is the model to copy. Its **algorithm** lives once in
-`MorphingSphereCore.kt` (pure `kotlin.math`), source-shared into this module from
-`:relay-ui` and guarded by `MorphingSphereCoreParityTest`. Each surface supplies
-only a thin renderer:
+Inside this experiment, the sphere algorithm lives in
+`relay-ui/.../MorphingSphereCore.kt` (pure `kotlin.math`) and is source-shared
+into this module. The production Android and web sphere implementations remain
+separate sources of truth outside the experiment.

 | Surface | Renderer | Lives in |
 |---|---|---|
-| Android | `MorphingSphere.kt` (Canvas + `@Preview`) | `:relay-ui`, `:app` |
-| Desktop | `DesktopSphere.kt` (Canvas, no `@Preview`) | this module |
-| Web | `sphere.js` | `preview/web/` |
+| Quest experiment | `MorphingSphere.kt` (Canvas + `@Preview`) | `:relay-ui` |
+| Desktop experiment | `DesktopSphere.kt` (Canvas, no `@Preview`) | this module |

 To add a component: hoist it to a value-only `@Composable`, add it to
 `PreviewGallery` in `Main.kt`, and drive it from controls. If it needs logic that
@@ -32,7 +32,6 @@ media3 = "1.11.0"
 androidVad = "2.0.10"
 sherpaOnnx = "v1.13.4"
 onnxRuntime = "1.27.0"
-spatialsdk = "0.13.2"
 play-app-update = "2.1.0"

 [libraries]
@@ -98,17 +97,6 @@ camera-view = { group = "androidx.camera", name = "camera-view", version.ref = "
 media3-exoplayer = { group = "androidx.media3", name = "media3-exoplayer", version.ref = "media3" }

 # Meta Spatial SDK
-meta-spatial-sdk-base = { group = "com.meta.spatial", name = "meta-spatial-sdk", version.ref = "spatialsdk" }
-meta-spatial-sdk-compose = { group = "com.meta.spatial", name = "meta-spatial-sdk-compose", version.ref = "spatialsdk" }
-meta-spatial-sdk-ovrmetrics = { group = "com.meta.spatial", name = "meta-spatial-sdk-ovrmetrics", version.ref = "spatialsdk" }
-meta-spatial-sdk-toolkit = { group = "com.meta.spatial", name = "meta-spatial-sdk-toolkit", version.ref = "spatialsdk" }
-meta-spatial-sdk-vr = { group = "com.meta.spatial", name = "meta-spatial-sdk-vr", version.ref = "spatialsdk" }
-meta-spatial-sdk-isdk = { group = "com.meta.spatial", name = "meta-spatial-sdk-isdk", version.ref = "spatialsdk" }
-meta-spatial-sdk-castinputforward = { group = "com.meta.spatial", name = "meta-spatial-sdk-castinputforward", version.ref = "spatialsdk" }
-meta-spatial-sdk-hotreload = { group = "com.meta.spatial", name = "meta-spatial-sdk-hotreload", version.ref = "spatialsdk" }
-meta-spatial-sdk-datamodelinspector = { group = "com.meta.spatial", name = "meta-spatial-sdk-datamodelinspector", version.ref = "spatialsdk" }
-meta-spatial-sdk-uiset = { group = "com.meta.spatial", name = "meta-spatial-sdk-uiset", version.ref = "spatialsdk" }
-meta-spatial-sdk-mruk = { group = "com.meta.spatial", name = "meta-spatial-sdk-mruk", version.ref = "spatialsdk" }

 # android-vad (Silero) — on-device voice activity detection for barge-in (B2)
 android-vad-silero = { group = "com.github.gkonovalov.android-vad", name = "silero", version.ref = "androidVad" }
@@ -15,6 +15,6 @@ request under `/docs/`. The meta refresh and visible link provide a no-script
 fallback to the guide root. Privacy compatibility pages identify
 `https://hermes-relay.dev/privacy.html` as canonical.

-Removal is tracked in the repository root `TODO.md`. Do not delete this shim
+Removal is tracked in the repository root `docs/project/TODO.md`. Do not delete this shim
 solely because the first fixed release has shipped; honor the documented
 compatibility window for older Play and sideload installations.
@@ -1,5 +1,5 @@
 name: hermes-relay
-# Temporary v1 shim for Hermes installers that reject manifests the runtime supports; see TODO.md.
+# Temporary v1 shim for Hermes installers that reject manifests the runtime supports; see docs/project/TODO.md.
 manifest_version: 1
 api_version: 1
 version: 1.11.1
@@ -160,7 +160,7 @@ BRIEF="${WTDIR}/ISSUE-BRIEF.md"
  echo "## Definition of done"
  echo
  echo "- The fix passes the verification above (write the failing test first where the surface is CI-gateable)."
-  echo "- Update CHANGELOG \`[Unreleased]\`, and DEVLOG.md at end of session; park any follow-ups in TODO.md."
+  echo "- Update CHANGELOG \`[Unreleased]\`, and docs/project/DEVLOG.md at end of session; park any follow-ups in docs/project/TODO.md."
  echo "- Feature branches target \`dev\` (never straight to \`main\`); merge with --no-ff."
  echo
  echo "## Issue body"
@@ -27,9 +27,3 @@ dependencyResolutionManagement {

 rootProject.name = "hermes-relay"
 include(":app")
-include(":relay-core")
-include(":relay-ui")
-// Desktop Compose Hot Reload harness for fast UI iteration. Not shipped — no
-// release artifact depends on it. See docs/ui-preview / ui-preview/README.md.
-include(":ui-preview")
-includeBuild("quest")
@@ -15,7 +15,7 @@ metadata:

 # Hermes-Relay Desktop CLI Setup

-> **Experimental.** The desktop CLI at `desktop/` is a preview-grade thin client. Pairing, chat, shell (PTY pipe to the host), and local tool routing (`desktop_terminal` / `desktop_read_file` / `desktop_write_file` / `desktop_search_files` / `desktop_patch`) all work end-to-end. Daemon mode, multi-client routing, and code-signed binaries are the v1.0 polish — see the [ROADMAP](https://github.com/Codename-11/hermes-relay/blob/main/ROADMAP.md#desktop-track-parallel-lane-to-android--experimental).
+> **Experimental.** The desktop CLI at `desktop/` is a preview-grade thin client. Pairing, chat, shell (PTY pipe to the host), and local tool routing (`desktop_terminal` / `desktop_read_file` / `desktop_write_file` / `desktop_search_files` / `desktop_patch`) all work end-to-end. Daemon mode, multi-client routing, and code-signed binaries are the v1.0 polish — see the [ROADMAP](https://github.com/Codename-11/hermes-relay/blob/main/docs/project/ROADMAP.md#desktop-track-parallel-lane-to-android--experimental).

 The [Hermes-Relay](https://github.com/Codename-11/hermes-relay) desktop CLI (`hermes-relay`) is a thin client that gives you remote access to a Hermes agent running on another machine. It pipes a full PTY shell (with the agent's native Ink TUI), streams structured chat events for scripting, and — uniquely — lets the remote agent execute tools **on your local machine** (read files, run shell commands, search the filesystem) through a round-trip over the same WSS relay the Android client uses. The agent brain stays on the host; your laptop is the hands.

@@ -158,7 +158,7 @@ While inside the shell/TUI session (bare `hermes-relay`, the default mode), `Ctr
 - **[Local tool routing](./tools.md)** — 23 agent-callable tools: file I/O, unified-diff patching, ripgrep, shell + PowerShell exec, process control, a background-job API, archive/transfer, clipboard, screenshot, and editor-launcher. Strict consent gate per relay URL; non-TTY stdin fails closed. The experimental computer-use family is off by default and has a separate persistent enablement switch.
 - **[Self-update](./subcommands.md#hermes-relay-update)** — `hermes-relay update` polls GitHub Releases, semver-compares, and verifies SHA256. POSIX and Windows CLI-only installs replace the standalone binary; a detected Windows UI installation updates the complete CLI+UI bundle and restores the processes that were running.
 - **[Surface plugins](./subcommands.md#hermes-relay-plugins)** — install, update, and launch terminal dashboard plugins from the CLI. The first built-in plugin is [Herm](https://github.com/liftaris/herm), installed as `herm-tui` and resumed with `herm -c`.
- **[Workspace awareness](./subcommands.md#hermes-relay-workspace)** — on connect, the client advertises `cwd`, `git_root`, `git_branch`, `repo_name`, `hostname`, `platform`, `active_shell` to the relay so the agent knows which repo you're in. Client-side capability shipped in alpha.6; server-side prompt-context consumption is on the way (see [ROADMAP.md](https://github.com/Codename-11/hermes-relay/blob/main/ROADMAP.md#desktop-track-parallel-lane-to-android--experimental)).
+- **[Workspace awareness](./subcommands.md#hermes-relay-workspace)** — on connect, the client advertises `cwd`, `git_root`, `git_branch`, `repo_name`, `hostname`, `platform`, `active_shell` to the relay so the agent knows which repo you're in. Client-side capability shipped in alpha.6; server-side prompt-context consumption is on the way (see [docs/project/ROADMAP.md](https://github.com/Codename-11/hermes-relay/blob/main/docs/project/ROADMAP.md#desktop-track-parallel-lane-to-android--experimental)).
 - **[Conversation picker](./subcommands.md#hermes-relay-shell)** — on first or fresh attach, choose from recent server-side Hermes conversations with first-prompt previews before the TUI starts.
 - **[TUI session continuity](./subcommands.md#hermes-relay-sessions)** — bare `hermes-relay` resumes the active/default tmux session, replays recent scrollback, and `sessions list/resume/new/kill` gives explicit control when you need it.
 - **[Editor tool + interactive patch approval](./tools.md#desktop-open-in-editor-and-interactive-patches)** — agent calls `desktop_open_in_editor(path, line, col)` to open `$VISUAL` / `$EDITOR` / VSCode / Cursor / Sublime / nvim. Agent-proposed patches render as colored unified diffs with `y`/`n`/`e`/`r` prompts.
@@ -436,7 +436,7 @@ hermes-relay workspace --json    # machine-readable
 Fields detected via parallel `git rev-parse` / `git status --porcelain=v1 --branch` calls under a 2 s total budget: `cwd`, `git_root`, `git_branch`, `git_status_summary` (staged / modified counts), `repo_name`, `hostname`, `platform`, `arch`, `active_shell`. Active-editor hints (`active_editor`) detect VSCode / Cursor via `$VSCODE_IPC_HOOK_CLI` + `TERM_PROGRAM`, or poll tmux's `display-message -p "#{pane_current_path}:#{pane_current_command}"` if `--watch-editor` is on.

 ::: tip Server-side consumption
-The client-side workspace envelope shipped in alpha.6. Server-side prompt-context injection (so the agent reads "Active desktop workspace: machine=X · repo=Y · branch=Z" every turn) is on the way — see [ROADMAP.md](https://github.com/Codename-11/hermes-relay/blob/main/ROADMAP.md#desktop-track-parallel-lane-to-android--experimental). Until then, the envelope is captured by the relay as ephemeral session metadata; you can ask the agent about it explicitly via tool calls.
+The client-side workspace envelope shipped in alpha.6. Server-side prompt-context injection (so the agent reads "Active desktop workspace: machine=X · repo=Y · branch=Z" every turn) is on the way — see [docs/project/ROADMAP.md](https://github.com/Codename-11/hermes-relay/blob/main/docs/project/ROADMAP.md#desktop-track-parallel-lane-to-android--experimental). Until then, the envelope is captured by the relay as ephemeral session metadata; you can ask the agent about it explicitly via tool calls.
 :::

 ## `hermes-relay logo`