diff --git a/packages/docs/CONTRIBUTING.md b/packages/docs/CONTRIBUTING.md
index 74741823..8a0bcc9d 100644
--- a/packages/docs/CONTRIBUTING.md
+++ b/packages/docs/CONTRIBUTING.md
@@ -2,6 +2,85 @@
 
 This package is docs content source-of-truth for OpenChamber.
 
+## Voice & style
+
+Write for someone trying to get something done — not for an engineer reading a
+spec. Assume the reader may be non-technical. A page should feel quick to read,
+never like a separate chore just to get through one screen.
+
+These rules describe how we already write the docs. Follow them so the style
+stays the same no matter who is writing.
+
+### Who you're writing for
+
+- Assume curiosity, not expertise. The reader knows what they want to do, not
+  how OpenChamber works inside.
+- One page = one job. If a page is answering two unrelated questions, split it.
+
+### Keep it short
+
+- Lead with the task, not background. The first line should say what the page is
+  for ("Use `openchamber tunnel` to expose a running OpenChamber instance.").
+- Cut anything that doesn't change what the reader does next.
+- A basic page should fit in a screen or two. Long, dense reference pages (like
+  Reverse Proxy) are the exception — and they say so in their first line ("Use
+  this page if you run OpenChamber behind...").
+
+### Steps
+
+- Number sequential actions; use bullets for options or unordered notes.
+- Start each step with a verb: "Run", "Open", "Pick".
+- End a procedure by telling the reader what success looks like, so they know
+  they did it right.
+
+```mdx
+3. Run `openchamber --ui-password be-creative-here`.
+4. Open the printed URL (usually `http://localhost:3000`).
+
+You should land on the OpenChamber session list. If you see it, the server is
+running.
+```
+
+### Plain language
+
+- Explain a term the first time it appears, in parentheses, in everyday words:
+  - good: start a tunnel (a public link to your local OpenChamber)
+  - bad: start a tunnel — the reader doesn't know what that is yet
+- Prefer common words over internal ones. "App", "version", "page" beat
+  "surface", "instance", "route" when the meaning is the same. If an internal
+  term is unavoidable, define it once.
+- Don't reach for `SSE`, `WebSocket`, `buffering`, or header names unless the
+  page is explicitly an advanced/operator page.
+
+### Bullets and sentences
+
+- Be consistent within a single list. Either all short fragments (lowercase, no
+  period) or all full sentences (capital letter, period) — don't mix the two in
+  one list.
+- Use fragments for quick option lists; use full sentences for rules, warnings,
+  or anything the reader must not misread.
+
+### Link out instead of re-explaining
+
+- Where a step can realistically fail, link to
+  [Troubleshooting](/troubleshooting/) right there, not only at the bottom.
+- Don't re-document something another page owns — link to it. (Quickstart points
+  at Install for the actual install command instead of copying it.)
+
+### Show, don't only tell
+
+- A screenshot beats a paragraph for anything visual (where a button is, what a
+  screen looks like). See [Images](#images) for how to add one.
+- Always pair a screenshot with one line of text — the image supports the step,
+  it isn't the whole step.
+
+### Commands and code
+
+- Make code blocks copy-paste-ready: real, working values. Only use a
+  `<placeholder>` when the value is genuinely user-specific, and make that
+  obvious (e.g. `app.example.com`, `~/.secrets/cf-token`).
+- One command per idea. Don't chain unrelated commands just to look compact.
+
 ## Add a new docs page
 
 1. Create a new file in `packages/docs/content/docs/`.
diff --git a/packages/docs/content/docs/es/index.mdx b/packages/docs/content/docs/es/index.mdx
index 23d60d1a..fc43e251 100644
--- a/packages/docs/content/docs/es/index.mdx
+++ b/packages/docs/content/docs/es/index.mdx
@@ -5,12 +5,12 @@ description: Guía de configuración y uso de OpenChamber en web, escritorio y V
 
 # Documentación de OpenChamber
 
-OpenChamber es el espacio de trabajo visual en torno a OpenCode.
+OpenChamber es el espacio de trabajo visual en torno a OpenCode (el agente de programación con IA que se ejecuta en tu terminal). Te da una pantalla para observar y dirigir ese trabajo, en lugar de vivir en la línea de comandos.
 
 Usa esta documentación para:
 
-- instalar la plataforma adecuada para tu flujo de trabajo
-- exponer OpenChamber de forma segura para uso remoto
+- instalar la app adecuada para tu forma de trabajar
+- abrir OpenChamber para un uso remoto seguro
 - personalizar la apariencia y resolver problemas comunes
 
 ## Lee esto primero
diff --git a/packages/docs/content/docs/es/install.mdx b/packages/docs/content/docs/es/install.mdx
index 110f8821..5b04e948 100644
--- a/packages/docs/content/docs/es/install.mdx
+++ b/packages/docs/content/docs/es/install.mdx
@@ -5,15 +5,15 @@ description: Instala OpenChamber para escritorio, web o VS Code.
 
 # Instalación
 
-OpenChamber tiene tres plataformas principales:
+Hay tres formas de ejecutar OpenChamber:
 
 - app de escritorio para macOS
-- app web alojada por la CLI con PWA instalable
+- app web alojada por la CLI, que puedes instalar como una app de teléfono (una PWA)
 - extensión para VS Code
 
 ## Requisito previo
 
-Instala [OpenCode](https://opencode.ai) primero.
+Instala [OpenCode](https://opencode.ai) primero: OpenChamber se ejecuta sobre él.
 
 ## Web + PWA
 
@@ -22,12 +22,12 @@ curl -fsSL https://raw.githubusercontent.com/openchamber/openchamber/main/script
 openchamber --ui-password be-creative-here
 ```
 
-Luego abre la URL que imprime la CLI (normalmente `http://localhost:3000`).
+Abre la URL que imprime la CLI (normalmente `http://localhost:3000`). Deberías ver la lista de sesiones de OpenChamber. Para tenerlo a mano, usa la opción "Instalar" de tu navegador en la barra de direcciones para añadirlo como una app.
 
 ## Escritorio
 
-Descarga la última compilación de escritorio desde la página de releases de GitHub o la página de descargas de OpenChamber.
+Descarga la última compilación de escritorio desde la página de releases de GitHub o la página de descargas de OpenChamber. Ábrela e inicia sesión con tu flujo de trabajo habitual de OpenCode.
 
 ## VS Code
 
-Instálala desde el VS Code Marketplace e inicia sesión con tu flujo de trabajo habitual de OpenCode.
+Instálala desde el VS Code Marketplace e inicia sesión con tu flujo de trabajo habitual de OpenCode. La vista de OpenChamber se abre entonces en la barra lateral.
diff --git a/packages/docs/content/docs/es/quickstart.mdx b/packages/docs/content/docs/es/quickstart.mdx
index c7866820..80518c84 100644
--- a/packages/docs/content/docs/es/quickstart.mdx
+++ b/packages/docs/content/docs/es/quickstart.mdx
@@ -1,22 +1,26 @@
 ---
 title: Inicio rápido
-description: Inicia OpenChamber rápidamente y elige la plataforma adecuada para la tarea.
+description: Inicia OpenChamber rápidamente y elige la app adecuada para la tarea.
 ---
 
 # Inicio rápido
 
 ## La vía más rápida
 
-1. Instala OpenCode.
-2. Instala la CLI de OpenChamber.
+1. Instala [OpenCode](https://opencode.ai).
+2. Instala la CLI de OpenChamber (consulta [Instalación](/es/install/) para el comando de una sola línea).
 3. Ejecuta `openchamber --ui-password be-creative-here`.
-4. Abre la UI web en tu máquina.
-5. Si lo necesitas, inicia un túnel y escanea el código QR desde tu teléfono.
+4. Abre la URL que imprime la CLI (normalmente `http://localhost:3000`).
+5. Para usarlo desde tu teléfono, inicia un [túnel](/es/tunnels/) y escanea el código QR.
 
-Usa una contraseña de UI fuerte, sobre todo si piensas exponer la instancia de forma remota.
+Deberías ver la lista de sesiones de OpenChamber en tu navegador. Si carga, ya está todo en marcha.
 
-## ¿Qué plataforma debería usar?
+Usa una contraseña de UI fuerte, sobre todo si piensas exponer la instancia a internet.
 
-- usa **escritorio** para el día a día en flujos de trabajo centrados en macOS
-- usa **web** para acceso remoto y revisión desde el móvil
-- usa **VS Code** para sesiones nativas del editor, junto al código
+Si la página no carga, consulta [Resolución de problemas](/es/troubleshooting/).
+
+## ¿Qué app debería usar?
+
+- usa **escritorio** para el día a día en macOS
+- usa **web** para acceso remoto y revisión desde el teléfono
+- usa **VS Code** para sesiones junto a tu código
diff --git a/packages/docs/content/docs/es/themes.mdx b/packages/docs/content/docs/es/themes.mdx
index e3b53a3d..b229c337 100644
--- a/packages/docs/content/docs/es/themes.mdx
+++ b/packages/docs/content/docs/es/themes.mdx
@@ -17,7 +17,7 @@ mkdir -p ~/.config/openchamber/themes
 
 2. Añade tu archivo JSON a ese directorio (por ejemplo, `my-theme.json`).
 3. Abre OpenChamber y ve a **Settings -> Theme -> Reload themes**.
-4. Elige tu tema en el desplegable.
+4. Elige tu tema en el desplegable. Se aplica de inmediato.
 
 ## Ubicación de los temas
 
diff --git a/packages/docs/content/docs/es/troubleshooting.mdx b/packages/docs/content/docs/es/troubleshooting.mdx
index 2dc66ff3..128cd272 100644
--- a/packages/docs/content/docs/es/troubleshooting.mdx
+++ b/packages/docs/content/docs/es/troubleshooting.mdx
@@ -5,6 +5,8 @@ description: Problemas comunes de configuración y ejecución con soluciones rá
 
 # Resolución de problemas
 
+¿Te topaste con un problema? Busca el síntoma abajo y prueba la solución.
+
 ## El comando OpenChamber se cierra o no arranca
 
 - confirma que Node.js es `>=20`
@@ -23,8 +25,16 @@ description: Problemas comunes de configuración y ejecución con soluciones rá
 - reinicia el túnel desde la misma instancia/puerto
 - regenera el enlace de conexión si el token anterior ya se usó
 
+Consulta [Túneles](/es/tunnels/) para la configuración completa, y [Proxy inverso](/es/reverse-proxy/) si usas uno.
+
 ## La extensión de VS Code no se conecta
 
 - confirma que el servidor de OpenChamber está en marcha
 - verifica que la extensión está actualizada
 - recarga la ventana de VS Code y reintenta la conexión
+
+## Relacionado
+
+- [Inicio rápido](/es/quickstart/)
+- [Túneles](/es/tunnels/)
+- [Proxy inverso](/es/reverse-proxy/)
diff --git a/packages/docs/content/docs/es/tunnels.mdx b/packages/docs/content/docs/es/tunnels.mdx
index 8937f133..f329038a 100644
--- a/packages/docs/content/docs/es/tunnels.mdx
+++ b/packages/docs/content/docs/es/tunnels.mdx
@@ -5,7 +5,7 @@ description: Expón OpenChamber de forma segura para acceso remoto y móvil.
 
 # Túneles
 
-Usa `openchamber tunnel` para exponer una instancia de OpenChamber en marcha.
+Un túnel es un enlace público a tu OpenChamber, para que puedas acceder a él desde tu teléfono u otra red. Usa `openchamber tunnel` para crear uno para una instancia en marcha.
 
 ## Inicio rápido (modo rápido de Cloudflare)
 
@@ -27,6 +27,8 @@ openchamber tunnel start --provider cloudflare --mode quick
 openchamber tunnel status
 ```
 
+Cuando el túnel está activo, `status` muestra una URL pública. Ábrela, o escanea el código QR, para acceder a OpenChamber desde cualquier lugar.
+
 Por defecto, OpenChamber imprime un código QR en sesiones TTY interactivas. Usa `--qr` para forzar la salida del QR, o `--no-qr` para desactivarla.
 
 ## Modos gestionados
@@ -75,3 +77,7 @@ openchamber tunnel stop --port 3000
 - un único túnel activo por instancia de OpenChamber (puerto)
 - iniciar un nuevo modo/proveedor en la misma instancia reemplaza el túnel anterior
 - generar un nuevo enlace de conexión revoca el anterior sin usar
+
+## Relacionado
+
+- [Resolución de problemas](/es/troubleshooting/) — si el enlace del túnel no funciona
diff --git a/packages/docs/content/docs/index.mdx b/packages/docs/content/docs/index.mdx
index 020f9b77..7acb6b67 100644
--- a/packages/docs/content/docs/index.mdx
+++ b/packages/docs/content/docs/index.mdx
@@ -5,13 +5,13 @@ description: Setup and operating guide for OpenChamber across web, desktop, and
 
 # OpenChamber Docs
 
-OpenChamber is the visual workspace around OpenCode.
+OpenChamber is the visual workspace around OpenCode (the AI coding agent that runs in your terminal). It gives you a screen to watch and steer that work, instead of living on the command line.
 
 Use these docs to:
 
-- install the right surface for your workflow
-- expose OpenChamber safely for remote use
-- customize appearance and troubleshoot common issues
+- install the right app for how you work
+- open OpenChamber for safe remote use
+- customize the look and fix common issues
 
 ## Read this first
 
diff --git a/packages/docs/content/docs/install.mdx b/packages/docs/content/docs/install.mdx
index c38706a8..a25eb3b2 100644
--- a/packages/docs/content/docs/install.mdx
+++ b/packages/docs/content/docs/install.mdx
@@ -5,15 +5,15 @@ description: Install OpenChamber for desktop, web, or VS Code.
 
 # Install
 
-OpenChamber has three main surfaces:
+There are three ways to run OpenChamber:
 
 - desktop app for macOS
-- CLI-hosted web app with installable PWA
+- web app hosted by the CLI, which you can install like a phone app (a PWA)
 - VS Code extension
 
 ## Prerequisite
 
-Install [OpenCode](https://opencode.ai) first.
+Install [OpenCode](https://opencode.ai) first — OpenChamber runs on top of it.
 
 ## Web + PWA
 
@@ -22,12 +22,12 @@ curl -fsSL https://raw.githubusercontent.com/openchamber/openchamber/main/script
 openchamber --ui-password be-creative-here
 ```
 
-Then open the URL printed by the CLI (usually `http://localhost:3000`).
+Open the URL the CLI prints (usually `http://localhost:3000`). You should see the OpenChamber session list. To keep it handy, use your browser's "Install" option in the address bar to add it as an app.
 
 ## Desktop
 
-Download the latest desktop build from the GitHub releases page or the OpenChamber download page.
+Download the latest desktop build from the GitHub releases page or the OpenChamber download page. Open it and sign into your usual OpenCode workflow.
 
 ## VS Code
 
-Install from the VS Code Marketplace and sign into your usual OpenCode workflow.
+Install from the VS Code Marketplace and sign into your usual OpenCode workflow. The OpenChamber view then opens in the sidebar.
diff --git a/packages/docs/content/docs/ko/index.mdx b/packages/docs/content/docs/ko/index.mdx
index fe6e3baa..da2db722 100644
--- a/packages/docs/content/docs/ko/index.mdx
+++ b/packages/docs/content/docs/ko/index.mdx
@@ -5,12 +5,12 @@ description: 웹, 데스크톱, VS Code에서 OpenChamber를 설정하고 운영
 
 # OpenChamber 문서
 
-OpenChamber는 OpenCode를 둘러싼 시각적 작업 공간입니다.
+OpenChamber는 OpenCode(터미널에서 실행되는 AI 코딩 에이전트)를 둘러싼 시각적 작업 공간입니다. 명령줄에 머무르는 대신, 그 작업을 지켜보고 조율할 수 있는 화면을 제공합니다.
 
 이 문서를 사용해:
 
-- 워크플로에 맞는 플랫폼을 설치하세요
-- 원격 사용을 위해 OpenChamber를 안전하게 공개하세요
+- 작업 방식에 맞는 앱을 설치하세요
+- 안전한 원격 사용을 위해 OpenChamber를 여세요
 - 외관을 맞춤 설정하고 흔한 문제를 해결하세요
 
 ## 먼저 읽어보기
diff --git a/packages/docs/content/docs/ko/install.mdx b/packages/docs/content/docs/ko/install.mdx
index 9df9d520..d4f72c2e 100644
--- a/packages/docs/content/docs/ko/install.mdx
+++ b/packages/docs/content/docs/ko/install.mdx
@@ -5,15 +5,15 @@ description: 데스크톱, 웹, VS Code용 OpenChamber를 설치하세요.
 
 # 설치
 
-OpenChamber에는 세 가지 주요 플랫폼이 있습니다:
+OpenChamber를 실행하는 방법은 세 가지입니다:
 
 - macOS용 데스크톱 앱
-- 설치 가능한 PWA를 갖춘 CLI 호스팅 웹 앱
+- CLI가 호스팅하는 웹 앱으로, 휴대폰 앱처럼 설치할 수 있습니다(PWA)
 - VS Code 확장
 
 ## 사전 요구 사항
 
-먼저 [OpenCode](https://opencode.ai)를 설치하세요.
+먼저 [OpenCode](https://opencode.ai)를 설치하세요 — OpenChamber는 그 위에서 실행됩니다.
 
 ## 웹 + PWA
 
@@ -22,12 +22,12 @@ curl -fsSL https://raw.githubusercontent.com/openchamber/openchamber/main/script
 openchamber --ui-password be-creative-here
 ```
 
-그런 다음 CLI가 출력한 URL을 여세요(보통 `http://localhost:3000`).
+CLI가 출력한 URL을 여세요(보통 `http://localhost:3000`). OpenChamber 세션 목록이 보일 것입니다. 자주 사용하려면 브라우저 주소창의 "설치" 옵션으로 앱처럼 추가하세요.
 
 ## 데스크톱
 
-GitHub 릴리스 페이지 또는 OpenChamber 다운로드 페이지에서 최신 데스크톱 빌드를 내려받으세요.
+GitHub 릴리스 페이지 또는 OpenChamber 다운로드 페이지에서 최신 데스크톱 빌드를 내려받으세요. 실행한 뒤 평소 사용하는 OpenCode 워크플로로 로그인하세요.
 
 ## VS Code
 
-VS Code 마켓플레이스에서 설치하고 평소 사용하는 OpenCode 워크플로로 로그인하세요.
+VS Code 마켓플레이스에서 설치하고 평소 사용하는 OpenCode 워크플로로 로그인하세요. 그러면 사이드바에 OpenChamber 뷰가 열립니다.
diff --git a/packages/docs/content/docs/ko/quickstart.mdx b/packages/docs/content/docs/ko/quickstart.mdx
index 58c3d3a1..086e33ed 100644
--- a/packages/docs/content/docs/ko/quickstart.mdx
+++ b/packages/docs/content/docs/ko/quickstart.mdx
@@ -1,22 +1,26 @@
 ---
 title: 빠른 시작
-description: OpenChamber를 빠르게 시작하고 작업에 맞는 플랫폼을 선택하세요.
+description: OpenChamber를 빠르게 시작하고 작업에 맞는 앱을 선택하세요.
 ---
 
 # 빠른 시작
 
 ## 가장 빠른 경로
 
-1. OpenCode를 설치합니다.
-2. OpenChamber CLI를 설치합니다.
+1. [OpenCode](https://opencode.ai)를 설치합니다.
+2. OpenChamber CLI를 설치합니다(한 줄 명령은 [설치](/ko/install/)를 참고하세요).
 3. `openchamber --ui-password be-creative-here`를 실행합니다.
-4. 컴퓨터에서 웹 UI를 엽니다.
-5. 필요하면 터널을 시작하고 휴대폰으로 QR 코드를 스캔합니다.
+4. CLI가 출력한 URL을 엽니다(보통 `http://localhost:3000`).
+5. 휴대폰에서 사용하려면 [터널](/ko/tunnels/)을 시작하고 QR 코드를 스캔합니다.
 
-특히 인스턴스를 원격으로 공개할 계획이라면 강력한 UI 비밀번호를 사용하세요.
+브라우저에 OpenChamber 세션 목록이 보일 것입니다. 화면이 뜨면 정상적으로 실행된 것입니다.
 
-## 어떤 플랫폼을 사용해야 하나요?
+특히 인스턴스를 인터넷에 공개할 계획이라면 강력한 UI 비밀번호를 사용하세요.
 
-- macOS 중심의 일상 작업에는 **데스크톱**을 사용하세요
-- 원격 접근과 모바일 검토에는 **웹**을 사용하세요
-- 코드 옆에서 에디터 네이티브 세션을 원하면 **VS Code**를 사용하세요
+페이지가 열리지 않으면 [문제 해결](/ko/troubleshooting/)을 확인하세요.
+
+## 어떤 앱을 사용해야 하나요?
+
+- macOS에서의 일상 작업에는 **데스크톱**을 사용하세요
+- 원격 접근과 휴대폰 검토에는 **웹**을 사용하세요
+- 코드 바로 옆에서 작업하는 세션에는 **VS Code**를 사용하세요
diff --git a/packages/docs/content/docs/ko/themes.mdx b/packages/docs/content/docs/ko/themes.mdx
index 0f2ee84c..c549cdf2 100644
--- a/packages/docs/content/docs/ko/themes.mdx
+++ b/packages/docs/content/docs/ko/themes.mdx
@@ -17,7 +17,7 @@ mkdir -p ~/.config/openchamber/themes
 
 2. 해당 디렉터리에 JSON 파일을 추가합니다(예: `my-theme.json`).
 3. OpenChamber를 열고 **Settings -> Theme -> Reload themes**로 이동합니다.
-4. 드롭다운에서 테마를 선택합니다.
+4. 드롭다운에서 테마를 선택합니다. 곧바로 적용됩니다.
 
 ## 테마 위치
 
diff --git a/packages/docs/content/docs/ko/troubleshooting.mdx b/packages/docs/content/docs/ko/troubleshooting.mdx
index 78830cd9..fcc702ee 100644
--- a/packages/docs/content/docs/ko/troubleshooting.mdx
+++ b/packages/docs/content/docs/ko/troubleshooting.mdx
@@ -5,6 +5,8 @@ description: 흔한 설정 및 실행 문제와 빠른 해결 방법.
 
 # 문제 해결
 
+문제가 생겼나요? 아래에서 증상을 찾아 해결 방법을 시도해 보세요.
+
 ## OpenChamber 명령이 종료되거나 시작되지 않음
 
 - Node.js `>=20`인지 확인하세요
@@ -23,8 +25,16 @@ description: 흔한 설정 및 실행 문제와 빠른 해결 방법.
 - 같은 인스턴스/포트에서 터널을 다시 시작하세요
 - 이전 토큰이 이미 사용되었다면 연결 링크를 다시 생성하세요
 
+전체 설정은 [터널](/ko/tunnels/)을, 리버스 프록시를 사용한다면 [리버스 프록시](/ko/reverse-proxy/)를 참고하세요.
+
 ## VS Code 확장이 연결되지 않음
 
 - OpenChamber 서버가 실행 중인지 확인하세요
 - 확장이 최신인지 확인하세요
 - VS Code 창을 새로 고치고 연결을 다시 시도하세요
+
+## 관련 문서
+
+- [빠른 시작](/ko/quickstart/)
+- [터널](/ko/tunnels/)
+- [리버스 프록시](/ko/reverse-proxy/)
diff --git a/packages/docs/content/docs/ko/tunnels.mdx b/packages/docs/content/docs/ko/tunnels.mdx
index 6b61f150..b213d219 100644
--- a/packages/docs/content/docs/ko/tunnels.mdx
+++ b/packages/docs/content/docs/ko/tunnels.mdx
@@ -5,7 +5,7 @@ description: 원격 및 모바일 접근을 위해 OpenChamber를 안전하게 
 
 # 터널
 
-실행 중인 OpenChamber 인스턴스를 공개하려면 `openchamber tunnel`을 사용하세요.
+터널은 OpenChamber로 연결되는 공개 링크로, 휴대폰이나 다른 네트워크에서 접근할 수 있게 해줍니다. 실행 중인 인스턴스에 터널을 만들려면 `openchamber tunnel`을 사용하세요.
 
 ## 빠른 시작 (Cloudflare 빠른 모드)
 
@@ -27,6 +27,8 @@ openchamber tunnel start --provider cloudflare --mode quick
 openchamber tunnel status
 ```
 
+터널이 올라오면 `status`에 공개 URL이 표시됩니다. 그 URL을 열거나 QR 코드를 스캔하면 어디서든 OpenChamber에 접근할 수 있습니다.
+
 기본적으로 OpenChamber는 대화형 TTY 세션에서 QR 코드를 출력합니다. `--qr`로 QR 출력을 강제하거나 `--no-qr`로 비활성화하세요.
 
 ## 관리형 모드
@@ -75,3 +77,7 @@ openchamber tunnel stop --port 3000
 - OpenChamber 인스턴스(포트)당 활성 터널은 하나입니다
 - 같은 인스턴스에서 새 모드/공급자를 시작하면 이전 터널이 대체됩니다
 - 새 연결 링크를 생성하면 사용되지 않은 이전 링크가 무효화됩니다
+
+## 관련 문서
+
+- [문제 해결](/ko/troubleshooting/) — 터널 링크가 작동하지 않을 때
diff --git a/packages/docs/content/docs/pl/index.mdx b/packages/docs/content/docs/pl/index.mdx
index d6836810..1ed9a8fd 100644
--- a/packages/docs/content/docs/pl/index.mdx
+++ b/packages/docs/content/docs/pl/index.mdx
@@ -5,7 +5,7 @@ description: Przewodnik konfiguracji i obsługi OpenChamber w przeglądarce, na
 
 # Dokumentacja OpenChamber
 
-OpenChamber to wizualna przestrzeń pracy wokół OpenCode.
+OpenChamber to wizualna przestrzeń pracy wokół OpenCode (agenta AI do programowania, który działa w terminalu). Daje Ci ekran, na którym możesz obserwować i kierować tą pracą, zamiast pozostawać w wierszu poleceń.
 
 Skorzystaj z tej dokumentacji, aby:
 
diff --git a/packages/docs/content/docs/pl/install.mdx b/packages/docs/content/docs/pl/install.mdx
index e66ad23a..c8d3631e 100644
--- a/packages/docs/content/docs/pl/install.mdx
+++ b/packages/docs/content/docs/pl/install.mdx
@@ -5,15 +5,15 @@ description: Zainstaluj OpenChamber na komputer, do przeglądarki lub do VS Code
 
 # Instalacja
 
-OpenChamber ma trzy główne platformy:
+OpenChamber można uruchomić na trzy sposoby:
 
 - aplikacja na komputer dla macOS
-- aplikacja webowa hostowana przez CLI z instalowalnym PWA
+- aplikacja webowa hostowana przez CLI, którą możesz zainstalować jak aplikację na telefonie (jako PWA)
 - rozszerzenie do VS Code
 
 ## Wymaganie wstępne
 
-Najpierw zainstaluj [OpenCode](https://opencode.ai).
+Najpierw zainstaluj [OpenCode](https://opencode.ai) — OpenChamber działa na jego bazie.
 
 ## Przeglądarka + PWA
 
@@ -22,12 +22,12 @@ curl -fsSL https://raw.githubusercontent.com/openchamber/openchamber/main/script
 openchamber --ui-password be-creative-here
 ```
 
-Następnie otwórz adres URL wypisany przez CLI (zwykle `http://localhost:3000`).
+Otwórz adres URL wypisany przez CLI (zwykle `http://localhost:3000`). Powinna pojawić się lista sesji OpenChamber. Aby mieć ją zawsze pod ręką, użyj opcji „Zainstaluj” w pasku adresu przeglądarki, aby dodać ją jako aplikację.
 
 ## Komputer
 
-Pobierz najnowszą kompilację na komputer ze strony wydań na GitHubie lub ze strony pobierania OpenChamber.
+Pobierz najnowszą kompilację na komputer ze strony wydań na GitHubie lub ze strony pobierania OpenChamber. Otwórz ją i zaloguj się do swojego zwykłego procesu pracy OpenCode.
 
 ## VS Code
 
-Zainstaluj z VS Code Marketplace i zaloguj się do swojego zwykłego procesu pracy OpenCode.
+Zainstaluj z VS Code Marketplace i zaloguj się do swojego zwykłego procesu pracy OpenCode. Widok OpenChamber otworzy się wtedy na pasku bocznym.
diff --git a/packages/docs/content/docs/pl/quickstart.mdx b/packages/docs/content/docs/pl/quickstart.mdx
index c6769230..3200c429 100644
--- a/packages/docs/content/docs/pl/quickstart.mdx
+++ b/packages/docs/content/docs/pl/quickstart.mdx
@@ -7,16 +7,20 @@ description: Szybko uruchom OpenChamber i wybierz platformę odpowiednią do zad
 
 ## Najszybsza droga
 
-1. Zainstaluj OpenCode.
-2. Zainstaluj CLI OpenChamber.
+1. Zainstaluj [OpenCode](https://opencode.ai).
+2. Zainstaluj CLI OpenChamber (jednowierszowe polecenie znajdziesz w sekcji [Instalacja](/pl/install/)).
 3. Uruchom `openchamber --ui-password be-creative-here`.
-4. Otwórz webowy interfejs na swoim komputerze.
-5. W razie potrzeby uruchom tunel i zeskanuj kod QR telefonem.
+4. Otwórz adres URL wypisany przez CLI (zwykle `http://localhost:3000`).
+5. Aby korzystać z telefonu, uruchom [tunel](/pl/tunnels/) i zeskanuj kod QR.
 
-Używaj silnego hasła UI, zwłaszcza jeśli planujesz udostępniać instancję zdalnie.
+W przeglądarce powinna pojawić się lista sesji OpenChamber. Jeśli się załadowała, wszystko działa.
+
+Używaj silnego hasła UI, zwłaszcza jeśli planujesz udostępnić instancję w internecie.
+
+Jeśli strona się nie ładuje, zajrzyj do [Rozwiązywania problemów](/pl/troubleshooting/).
 
 ## Której platformy użyć?
 
-- użyj **komputera** do codziennej pracy w procesach skupionych na macOS
+- użyj **komputera** do codziennej pracy na macOS
 - użyj **przeglądarki** do zdalnego dostępu i przeglądania na telefonie
-- użyj **VS Code** do sesji natywnych dla edytora, obok kodu
+- użyj **VS Code** do sesji tuż obok Twojego kodu
diff --git a/packages/docs/content/docs/pl/themes.mdx b/packages/docs/content/docs/pl/themes.mdx
index c2244020..69d7d1b5 100644
--- a/packages/docs/content/docs/pl/themes.mdx
+++ b/packages/docs/content/docs/pl/themes.mdx
@@ -17,7 +17,7 @@ mkdir -p ~/.config/openchamber/themes
 
 2. Dodaj swój plik JSON do tego katalogu (na przykład `my-theme.json`).
 3. Otwórz OpenChamber, a następnie przejdź do **Settings -> Theme -> Reload themes**.
-4. Wybierz swój motyw z listy rozwijanej.
+4. Wybierz swój motyw z listy rozwijanej. Zostanie zastosowany od razu.
 
 ## Lokalizacja motywów
 
diff --git a/packages/docs/content/docs/pl/troubleshooting.mdx b/packages/docs/content/docs/pl/troubleshooting.mdx
index 5a2e78a4..2ac1f280 100644
--- a/packages/docs/content/docs/pl/troubleshooting.mdx
+++ b/packages/docs/content/docs/pl/troubleshooting.mdx
@@ -5,6 +5,8 @@ description: Typowe problemy z konfiguracją i działaniem oraz szybkie rozwiąz
 
 # Rozwiązywanie problemów
 
+Coś poszło nie tak? Znajdź poniżej swój objaw i wypróbuj rozwiązanie.
+
 ## Polecenie OpenChamber kończy się lub nie uruchamia
 
 - upewnij się, że Node.js `>=20`
@@ -23,8 +25,16 @@ description: Typowe problemy z konfiguracją i działaniem oraz szybkie rozwiąz
 - zrestartuj tunel z tej samej instancji/portu
 - wygeneruj nowy link połączenia, jeśli poprzedni token został już użyty
 
+Pełną konfigurację znajdziesz w [Tunele](/pl/tunnels/), a jeśli używasz proxy — w [Reverse proxy](/pl/reverse-proxy/).
+
 ## Rozszerzenie VS Code nie łączy się
 
 - upewnij się, że serwer OpenChamber działa
 - zweryfikuj, że rozszerzenie jest zaktualizowane
 - przeładuj okno VS Code i ponów połączenie
+
+## Powiązane
+
+- [Szybki start](/pl/quickstart/)
+- [Tunele](/pl/tunnels/)
+- [Reverse proxy](/pl/reverse-proxy/)
diff --git a/packages/docs/content/docs/pl/tunnels.mdx b/packages/docs/content/docs/pl/tunnels.mdx
index 67db78bb..f2b2071f 100644
--- a/packages/docs/content/docs/pl/tunnels.mdx
+++ b/packages/docs/content/docs/pl/tunnels.mdx
@@ -5,7 +5,7 @@ description: Bezpiecznie udostępnij OpenChamber do dostępu zdalnego i mobilneg
 
 # Tunele
 
-Użyj `openchamber tunnel`, aby udostępnić działającą instancję OpenChamber.
+Tunel to publiczny link do Twojego OpenChamber, dzięki któremu możesz dotrzeć do niego z telefonu lub z innej sieci. Użyj `openchamber tunnel`, aby utworzyć go dla działającej instancji.
 
 ## Szybki start (tryb szybki Cloudflare)
 
@@ -27,6 +27,8 @@ openchamber tunnel start --provider cloudflare --mode quick
 openchamber tunnel status
 ```
 
+Gdy tunel działa, `status` pokazuje publiczny adres URL. Otwórz go lub zeskanuj kod QR, aby dotrzeć do OpenChamber z dowolnego miejsca.
+
 Domyślnie OpenChamber wypisuje kod QR w interaktywnych sesjach TTY. Użyj `--qr`, aby wymusić wyświetlenie kodu QR, lub `--no-qr`, aby je wyłączyć.
 
 ## Tryby zarządzane
@@ -75,3 +77,7 @@ openchamber tunnel stop --port 3000
 - jeden aktywny tunel na instancję OpenChamber (port)
 - uruchomienie nowego trybu/dostawcy na tej samej instancji zastępuje poprzedni tunel
 - wygenerowanie nowego linku połączenia unieważnia poprzedni nieużyty
+
+## Powiązane
+
+- [Rozwiązywanie problemów](/pl/troubleshooting/) — jeśli link tunelu nie działa
diff --git a/packages/docs/content/docs/pt-br/index.mdx b/packages/docs/content/docs/pt-br/index.mdx
index 93ef3d91..20e44d95 100644
--- a/packages/docs/content/docs/pt-br/index.mdx
+++ b/packages/docs/content/docs/pt-br/index.mdx
@@ -5,12 +5,12 @@ description: Guia de configuração e uso do OpenChamber na web, no desktop e no
 
 # Documentação do OpenChamber
 
-O OpenChamber é o espaço de trabalho visual em torno do OpenCode.
+O OpenChamber é o espaço de trabalho visual em torno do OpenCode (o agente de programação com IA que roda no seu terminal). Ele te dá uma tela para acompanhar e direcionar esse trabalho, em vez de viver na linha de comando.
 
 Use esta documentação para:
 
 - instalar a plataforma certa para o seu fluxo de trabalho
-- expor o OpenChamber com segurança para uso remoto
+- abrir o OpenChamber para uso remoto seguro
 - personalizar a aparência e resolver problemas comuns
 
 ## Leia isto primeiro
diff --git a/packages/docs/content/docs/pt-br/install.mdx b/packages/docs/content/docs/pt-br/install.mdx
index b13a6f98..48164860 100644
--- a/packages/docs/content/docs/pt-br/install.mdx
+++ b/packages/docs/content/docs/pt-br/install.mdx
@@ -5,15 +5,15 @@ description: Instale o OpenChamber para desktop, web ou VS Code.
 
 # Instalação
 
-O OpenChamber tem três plataformas principais:
+Há três formas de rodar o OpenChamber:
 
 - app de desktop para macOS
-- app web hospedado pela CLI com PWA instalável
+- app web hospedado pela CLI, que você pode instalar como um app de celular (um PWA)
 - extensão para VS Code
 
 ## Pré-requisito
 
-Instale o [OpenCode](https://opencode.ai) primeiro.
+Instale o [OpenCode](https://opencode.ai) primeiro — o OpenChamber roda em cima dele.
 
 ## Web + PWA
 
@@ -22,12 +22,12 @@ curl -fsSL https://raw.githubusercontent.com/openchamber/openchamber/main/script
 openchamber --ui-password be-creative-here
 ```
 
-Depois abra a URL impressa pela CLI (geralmente `http://localhost:3000`).
+Abra a URL que a CLI imprime (geralmente `http://localhost:3000`). Você deve ver a lista de sessões do OpenChamber. Para deixá-lo à mão, use a opção "Instalar" do seu navegador na barra de endereço para adicioná-lo como um app.
 
 ## Desktop
 
-Baixe a build de desktop mais recente na página de releases do GitHub ou na página de download do OpenChamber.
+Baixe a build de desktop mais recente na página de releases do GitHub ou na página de download do OpenChamber. Abra-a e entre no seu fluxo de trabalho habitual do OpenCode.
 
 ## VS Code
 
-Instale pela VS Code Marketplace e entre no seu fluxo de trabalho habitual do OpenCode.
+Instale pela VS Code Marketplace e entre no seu fluxo de trabalho habitual do OpenCode. A visualização do OpenChamber então abre na barra lateral.
diff --git a/packages/docs/content/docs/pt-br/quickstart.mdx b/packages/docs/content/docs/pt-br/quickstart.mdx
index 008792b4..cf551ef1 100644
--- a/packages/docs/content/docs/pt-br/quickstart.mdx
+++ b/packages/docs/content/docs/pt-br/quickstart.mdx
@@ -7,16 +7,20 @@ description: Inicie o OpenChamber rapidamente e escolha a plataforma certa para
 
 ## Caminho mais rápido
 
-1. Instale o OpenCode.
-2. Instale a CLI do OpenChamber.
+1. Instale o [OpenCode](https://opencode.ai).
+2. Instale a CLI do OpenChamber (veja [Instalação](/pt-br/install/) para o comando de uma linha).
 3. Execute `openchamber --ui-password be-creative-here`.
-4. Abra a UI web na sua máquina.
-5. Se precisar, inicie um túnel e escaneie o QR code pelo celular.
+4. Abra a URL que a CLI imprime (geralmente `http://localhost:3000`).
+5. Para usar pelo celular, inicie um [túnel](/pt-br/tunnels/) e escaneie o QR code.
 
-Use uma senha de UI forte, principalmente se pretende expor a instância remotamente.
+Você deve ver a lista de sessões do OpenChamber no navegador. Se ela carregar, está tudo funcionando.
+
+Use uma senha de UI forte, principalmente se pretende expor a instância à internet.
+
+Se a página não carregar, confira a [Solução de problemas](/pt-br/troubleshooting/).
 
 ## Qual plataforma devo usar?
 
-- use **desktop** para o uso diário em fluxos focados em macOS
+- use **desktop** para o uso diário no macOS
 - use **web** para acesso remoto e revisão pelo celular
-- use **VS Code** para sessões nativas do editor, ao lado do código
+- use **VS Code** para sessões ao lado do seu código
diff --git a/packages/docs/content/docs/pt-br/themes.mdx b/packages/docs/content/docs/pt-br/themes.mdx
index 67192b05..c3338adf 100644
--- a/packages/docs/content/docs/pt-br/themes.mdx
+++ b/packages/docs/content/docs/pt-br/themes.mdx
@@ -17,7 +17,7 @@ mkdir -p ~/.config/openchamber/themes
 
 2. Adicione seu arquivo JSON a esse diretório (por exemplo, `my-theme.json`).
 3. Abra o OpenChamber e vá em **Settings -> Theme -> Reload themes**.
-4. Escolha seu tema na lista suspensa.
+4. Escolha seu tema na lista suspensa. Ele é aplicado na hora.
 
 ## Localização dos temas
 
diff --git a/packages/docs/content/docs/pt-br/troubleshooting.mdx b/packages/docs/content/docs/pt-br/troubleshooting.mdx
index 69c834a4..4e32235e 100644
--- a/packages/docs/content/docs/pt-br/troubleshooting.mdx
+++ b/packages/docs/content/docs/pt-br/troubleshooting.mdx
@@ -5,6 +5,8 @@ description: Problemas comuns de configuração e execução com soluções ráp
 
 # Solução de problemas
 
+Topou com um problema? Encontre o sintoma abaixo e tente a solução.
+
 ## O comando OpenChamber encerra ou não inicia
 
 - confirme o Node.js `>=20`
@@ -23,8 +25,16 @@ description: Problemas comuns de configuração e execução com soluções ráp
 - reinicie o túnel a partir da mesma instância/porta
 - gere um novo link de conexão se o token anterior já tiver sido usado
 
+Veja [Túneis](/pt-br/tunnels/) para a configuração completa e [Proxy reverso](/pt-br/reverse-proxy/) se você usar um.
+
 ## A extensão do VS Code não conecta
 
 - confirme que o servidor do OpenChamber está em execução
 - verifique se a extensão está atualizada
 - recarregue a janela do VS Code e tente conectar de novo
+
+## Relacionado
+
+- [Início rápido](/pt-br/quickstart/)
+- [Túneis](/pt-br/tunnels/)
+- [Proxy reverso](/pt-br/reverse-proxy/)
diff --git a/packages/docs/content/docs/pt-br/tunnels.mdx b/packages/docs/content/docs/pt-br/tunnels.mdx
index c4dc4b6c..a2b4b856 100644
--- a/packages/docs/content/docs/pt-br/tunnels.mdx
+++ b/packages/docs/content/docs/pt-br/tunnels.mdx
@@ -5,7 +5,7 @@ description: Exponha o OpenChamber com segurança para acesso remoto e móvel.
 
 # Túneis
 
-Use `openchamber tunnel` para expor uma instância do OpenChamber em execução.
+Um túnel é um link público para o seu OpenChamber, para que você possa acessá-lo pelo celular ou de outra rede. Use `openchamber tunnel` para criar um para uma instância em execução.
 
 ## Início rápido (modo rápido da Cloudflare)
 
@@ -27,6 +27,8 @@ openchamber tunnel start --provider cloudflare --mode quick
 openchamber tunnel status
 ```
 
+Quando o túnel estiver no ar, o `status` mostra uma URL pública. Abra-a, ou escaneie o QR code, para acessar o OpenChamber de qualquer lugar.
+
 Por padrão, o OpenChamber imprime um QR code em sessões TTY interativas. Use `--qr` para forçar a saída do QR, ou `--no-qr` para desativá-la.
 
 ## Modos gerenciados
@@ -75,3 +77,7 @@ openchamber tunnel stop --port 3000
 - um único túnel ativo por instância do OpenChamber (porta)
 - iniciar um novo modo/provedor na mesma instância substitui o túnel anterior
 - gerar um novo link de conexão revoga o anterior não utilizado
+
+## Relacionado
+
+- [Solução de problemas](/pt-br/troubleshooting/) — se o link do túnel não funcionar
diff --git a/packages/docs/content/docs/quickstart.mdx b/packages/docs/content/docs/quickstart.mdx
index 38c761d4..62051ae7 100644
--- a/packages/docs/content/docs/quickstart.mdx
+++ b/packages/docs/content/docs/quickstart.mdx
@@ -1,22 +1,26 @@
 ---
 title: Quickstart
-description: Start OpenChamber quickly and choose the right surface for the task.
+description: Start OpenChamber quickly and pick the right app for the task.
 ---
 
 # Quickstart
 
 ## Fastest path
 
-1. Install OpenCode.
-2. Install OpenChamber CLI.
+1. Install [OpenCode](https://opencode.ai).
+2. Install the OpenChamber CLI (see [Install](/install/) for the one-line command).
 3. Run `openchamber --ui-password be-creative-here`.
-4. Open the web UI on your machine.
-5. If needed, start a tunnel and scan the QR code from your phone.
+4. Open the URL the CLI prints (usually `http://localhost:3000`).
+5. To use it from your phone, start a [tunnel](/tunnels/) and scan the QR code.
 
-Use a strong UI password, especially if you plan to expose the instance remotely.
+You should see the OpenChamber session list in your browser. If it loads, you're up and running.
 
-## Which surface should I use?
+Use a strong UI password, especially if you plan to open the instance to the internet.
 
-- use **desktop** for macOS-heavy daily driver workflows
-- use **web** for remote access and mobile review
-- use **VS Code** for editor-native sessions beside code
+If the page doesn't load, check [Troubleshooting](/troubleshooting/).
+
+## Which app should I use?
+
+- use **desktop** for day-to-day work on macOS
+- use **web** for remote access and reviewing from your phone
+- use **VS Code** for sessions right next to your code
diff --git a/packages/docs/content/docs/themes.mdx b/packages/docs/content/docs/themes.mdx
index 633b06da..d24b44b1 100644
--- a/packages/docs/content/docs/themes.mdx
+++ b/packages/docs/content/docs/themes.mdx
@@ -17,7 +17,7 @@ mkdir -p ~/.config/openchamber/themes
 
 2. Add your JSON file to that directory (for example `my-theme.json`).
 3. Open OpenChamber, then go to **Settings -> Theme -> Reload themes**.
-4. Pick your theme from the dropdown.
+4. Pick your theme from the dropdown. It applies right away.
 
 ## Theme location
 
diff --git a/packages/docs/content/docs/troubleshooting.mdx b/packages/docs/content/docs/troubleshooting.mdx
index 7d013f14..d708053b 100644
--- a/packages/docs/content/docs/troubleshooting.mdx
+++ b/packages/docs/content/docs/troubleshooting.mdx
@@ -5,6 +5,8 @@ description: Common setup and runtime issues with quick fixes.
 
 # Troubleshooting
 
+Hit a snag? Find the symptom below and try the fix.
+
 ## OpenChamber command exits or fails to start
 
 - confirm Node.js `>=20`
@@ -23,8 +25,16 @@ description: Common setup and runtime issues with quick fixes.
 - restart tunnel from the same instance/port
 - regenerate connect link if previous token was already used
 
+See [Tunnels](/tunnels/) for the full setup, and [Reverse Proxy](/reverse-proxy/) if you run one.
+
 ## VS Code extension does not connect
 
 - confirm OpenChamber server is running
 - verify extension is updated
 - reload VS Code window and retry connection
+
+## Related
+
+- [Quickstart](/quickstart/)
+- [Tunnels](/tunnels/)
+- [Reverse Proxy](/reverse-proxy/)
diff --git a/packages/docs/content/docs/tunnels.mdx b/packages/docs/content/docs/tunnels.mdx
index 1206cdad..cd86a3d8 100644
--- a/packages/docs/content/docs/tunnels.mdx
+++ b/packages/docs/content/docs/tunnels.mdx
@@ -5,7 +5,7 @@ description: Expose OpenChamber safely for remote and mobile access.
 
 # Tunnels
 
-Use `openchamber tunnel` to expose a running OpenChamber instance.
+A tunnel is a public link to your OpenChamber, so you can reach it from your phone or another network. Use `openchamber tunnel` to create one for a running instance.
 
 ## Quick start (Cloudflare quick mode)
 
@@ -27,6 +27,8 @@ openchamber tunnel start --provider cloudflare --mode quick
 openchamber tunnel status
 ```
 
+When the tunnel is up, `status` shows a public URL. Open it, or scan the QR code, to reach OpenChamber from anywhere.
+
 By default, OpenChamber prints a QR code in interactive TTY sessions. Use `--qr` to force QR output, or `--no-qr` to disable it.
 
 ## Managed modes
@@ -75,3 +77,7 @@ openchamber tunnel stop --port 3000
 - one active tunnel per OpenChamber instance (port)
 - starting a new mode/provider on same instance replaces previous tunnel
 - generating a new connect link revokes previous unused one
+
+## Related
+
+- [Troubleshooting](/troubleshooting/) — if the tunnel link doesn't work
diff --git a/packages/docs/content/docs/uk/index.mdx b/packages/docs/content/docs/uk/index.mdx
index fc0af5c9..0210cbcd 100644
--- a/packages/docs/content/docs/uk/index.mdx
+++ b/packages/docs/content/docs/uk/index.mdx
@@ -5,11 +5,11 @@ description: Посібник з налаштування та роботи з O
 
 # Документація OpenChamber
 
-OpenChamber — це візуальний робочий простір навколо OpenCode.
+OpenChamber — це візуальний робочий простір навколо OpenCode (AI-агента для кодингу, який працює у вашому терміналі). Він дає екран, де можна спостерігати за цією роботою та керувати нею, замість того щоб лишатися в командному рядку.
 
 Використовуйте ці доки, щоб:
 
-- встановити платформу, що пасує вашому робочому процесу
+- встановити застосунок, що пасує вашому робочому процесу
 - безпечно відкрити OpenChamber для віддаленого використання
 - налаштувати вигляд і усувати типові проблеми
 
diff --git a/packages/docs/content/docs/uk/install.mdx b/packages/docs/content/docs/uk/install.mdx
index 68640131..3dd412a1 100644
--- a/packages/docs/content/docs/uk/install.mdx
+++ b/packages/docs/content/docs/uk/install.mdx
@@ -5,15 +5,15 @@ description: Встановіть OpenChamber для десктопа, вебу
 
 # Встановлення
 
-OpenChamber має три основні платформи:
+Є три способи запустити OpenChamber:
 
 - десктоп-застосунок для macOS
-- вебзастосунок на базі CLI зі встановлюваним PWA
+- вебзастосунок на базі CLI, який можна встановити як застосунок на телефоні (PWA)
 - розширення для VS Code
 
 ## Передумова
 
-Спершу встановіть [OpenCode](https://opencode.ai).
+Спершу встановіть [OpenCode](https://opencode.ai) — OpenChamber працює поверх нього.
 
 ## Веб + PWA
 
@@ -22,12 +22,12 @@ curl -fsSL https://raw.githubusercontent.com/openchamber/openchamber/main/script
 openchamber --ui-password be-creative-here
 ```
 
-Потім відкрийте URL, який вивів CLI (зазвичай `http://localhost:3000`).
+Відкрийте URL, який вивів CLI (зазвичай `http://localhost:3000`). Ви маєте побачити список сесій OpenChamber. Щоб він був під рукою, скористайтеся опцією «Install» в адресному рядку браузера й додайте його як застосунок.
 
 ## Десктоп
 
-Завантажте найновішу десктопну збірку зі сторінки релізів на GitHub або зі сторінки завантаження OpenChamber.
+Завантажте найновішу десктопну збірку зі сторінки релізів на GitHub або зі сторінки завантаження OpenChamber. Відкрийте її та увійдіть у свій звичний робочий процес OpenCode.
 
 ## VS Code
 
-Встановіть із VS Code Marketplace і увійдіть у свій звичний робочий процес OpenCode.
+Встановіть із VS Code Marketplace і увійдіть у свій звичний робочий процес OpenCode. Після цього вікно OpenChamber відкриється на бічній панелі.
diff --git a/packages/docs/content/docs/uk/quickstart.mdx b/packages/docs/content/docs/uk/quickstart.mdx
index c071beb2..21a139da 100644
--- a/packages/docs/content/docs/uk/quickstart.mdx
+++ b/packages/docs/content/docs/uk/quickstart.mdx
@@ -7,16 +7,20 @@ description: Швидко запустіть OpenChamber і оберіть пл
 
 ## Найшвидший шлях
 
-1. Встановіть OpenCode.
-2. Встановіть CLI OpenChamber.
+1. Встановіть [OpenCode](https://opencode.ai).
+2. Встановіть CLI OpenChamber (команду в один рядок дивіться в [Встановленні](/uk/install/)).
 3. Виконайте `openchamber --ui-password be-creative-here`.
-4. Відкрийте веб-UI на своїй машині.
-5. За потреби запустіть тунель і відскануйте QR-код із телефона.
+4. Відкрийте URL, який вивів CLI (зазвичай `http://localhost:3000`).
+5. Щоб користуватися з телефона, запустіть [тунель](/uk/tunnels/) і відскануйте QR-код.
 
-Використовуйте надійний пароль UI, особливо якщо плануєте відкривати інстанс віддалено.
+У браузері ви маєте побачити список сесій OpenChamber. Якщо він завантажився — все працює.
+
+Використовуйте надійний пароль UI, особливо якщо плануєте відкривати доступ до інстансу з інтернету.
+
+Якщо сторінка не завантажується, перегляньте [Усунення несправностей](/uk/troubleshooting/).
 
 ## Яку платформу обрати?
 
-- обирайте **десктоп** для щоденної роботи переважно на macOS
-- обирайте **веб** для віддаленого доступу та перегляду з мобільного
-- обирайте **VS Code** для сесій усередині редактора, поруч із кодом
+- обирайте **десктоп** для щоденної роботи на macOS
+- обирайте **веб** для віддаленого доступу та перегляду з телефона
+- обирайте **VS Code** для сесій поруч із вашим кодом
diff --git a/packages/docs/content/docs/uk/themes.mdx b/packages/docs/content/docs/uk/themes.mdx
index 73c3651e..70218c2a 100644
--- a/packages/docs/content/docs/uk/themes.mdx
+++ b/packages/docs/content/docs/uk/themes.mdx
@@ -17,7 +17,7 @@ mkdir -p ~/.config/openchamber/themes
 
 2. Додайте свій JSON-файл у цю директорію (наприклад, `my-theme.json`).
 3. Відкрийте OpenChamber, потім перейдіть до **Settings -> Theme -> Reload themes**.
-4. Оберіть свою тему зі спадного списку.
+4. Оберіть свою тему зі спадного списку. Вона застосується одразу.
 
 ## Розташування тем
 
diff --git a/packages/docs/content/docs/uk/troubleshooting.mdx b/packages/docs/content/docs/uk/troubleshooting.mdx
index 4b6d96a9..6fb2f8e7 100644
--- a/packages/docs/content/docs/uk/troubleshooting.mdx
+++ b/packages/docs/content/docs/uk/troubleshooting.mdx
@@ -5,6 +5,8 @@ description: Типові проблеми з налаштуванням і за
 
 # Усунення несправностей
 
+Щось пішло не так? Знайдіть свою проблему нижче і спробуйте рішення.
+
 ## Команда OpenChamber завершується або не запускається
 
 - переконайтеся, що Node.js `>=20`
@@ -23,8 +25,16 @@ description: Типові проблеми з налаштуванням і за
 - перезапустіть тунель із того самого інстансу/порту
 - згенеруйте нове посилання для підключення, якщо попередній токен уже було використано
 
+Докладне налаштування див. у розділі [Тунелі](/uk/tunnels/), а якщо ви використовуєте проксі — [Зворотний проксі](/uk/reverse-proxy/).
+
 ## Розширення VS Code не підключається
 
 - переконайтеся, що сервер OpenChamber запущено
 - перевірте, що розширення оновлено
 - перезавантажте вікно VS Code і повторіть підключення
+
+## Пов’язане
+
+- [Швидкий старт](/uk/quickstart/)
+- [Тунелі](/uk/tunnels/)
+- [Зворотний проксі](/uk/reverse-proxy/)
diff --git a/packages/docs/content/docs/uk/tunnels.mdx b/packages/docs/content/docs/uk/tunnels.mdx
index 988f401b..89a60f23 100644
--- a/packages/docs/content/docs/uk/tunnels.mdx
+++ b/packages/docs/content/docs/uk/tunnels.mdx
@@ -5,7 +5,7 @@ description: Безпечно відкрийте OpenChamber для віддал
 
 # Тунелі
 
-Використовуйте `openchamber tunnel`, щоб відкрити запущений інстанс OpenChamber.
+Тунель — це публічне посилання на ваш OpenChamber, щоб дістатися до нього з телефона чи з іншої мережі. Скористайтеся `openchamber tunnel`, щоб створити його для запущеного інстансу.
 
 ## Швидкий старт (швидкий режим Cloudflare)
 
@@ -27,6 +27,8 @@ openchamber tunnel start --provider cloudflare --mode quick
 openchamber tunnel status
 ```
 
+Коли тунель піднято, `status` показує публічний URL. Відкрийте його або відскануйте QR-код, щоб дістатися до OpenChamber звідусіль.
+
 Типово OpenChamber виводить QR-код в інтерактивних TTY-сесіях. Використовуйте `--qr`, щоб примусово вивести QR, або `--no-qr`, щоб вимкнути його.
 
 ## Керовані режими
@@ -75,3 +77,7 @@ openchamber tunnel stop --port 3000
 - один активний тунель на інстанс OpenChamber (порт)
 - запуск нового режиму/провайдера на тому самому інстансі замінює попередній тунель
 - генерація нового посилання для підключення відкликає попереднє невикористане
+
+## Пов'язане
+
+- [Усунення несправностей](/uk/troubleshooting/) — якщо посилання тунелю не працює
diff --git a/packages/docs/content/docs/zh-cn/index.mdx b/packages/docs/content/docs/zh-cn/index.mdx
index 6db5d85a..6e4f390d 100644
--- a/packages/docs/content/docs/zh-cn/index.mdx
+++ b/packages/docs/content/docs/zh-cn/index.mdx
@@ -5,11 +5,11 @@ description: 在 Web、桌面与 VS Code 上设置和使用 OpenChamber 的指
 
 # OpenChamber 文档
 
-OpenChamber 是围绕 OpenCode 的可视化工作空间。
+OpenChamber 是围绕 OpenCode（在你终端中运行的 AI 编程智能体）的可视化工作空间。它给你一块屏幕去观察并引导这些工作，而不必停留在命令行里。
 
 使用本文档来：
 
-- 为你的工作流安装合适的平台
+- 为你的工作方式安装合适的应用
 - 安全地将 OpenChamber 开放给远程使用
 - 自定义外观并排查常见问题
 
diff --git a/packages/docs/content/docs/zh-cn/install.mdx b/packages/docs/content/docs/zh-cn/install.mdx
index f5f4229f..421f552a 100644
--- a/packages/docs/content/docs/zh-cn/install.mdx
+++ b/packages/docs/content/docs/zh-cn/install.mdx
@@ -5,15 +5,15 @@ description: 为桌面、Web 或 VS Code 安装 OpenChamber。
 
 # 安装
 
-OpenChamber 有三个主要平台：
+运行 OpenChamber 有三种方式：
 
 - 面向 macOS 的桌面应用
-- 由 CLI 托管、可安装为 PWA 的 Web 应用
+- 由 CLI 托管的 Web 应用，可以像手机应用一样安装（即 PWA）
 - VS Code 扩展
 
 ## 前提条件
 
-请先安装 [OpenCode](https://opencode.ai)。
+请先安装 [OpenCode](https://opencode.ai)——OpenChamber 在它之上运行。
 
 ## Web + PWA
 
@@ -22,12 +22,12 @@ curl -fsSL https://raw.githubusercontent.com/openchamber/openchamber/main/script
 openchamber --ui-password be-creative-here
 ```
 
-然后打开 CLI 输出的 URL（通常是 `http://localhost:3000`）。
+打开 CLI 输出的 URL（通常是 `http://localhost:3000`）。你应该会看到 OpenChamber 会话列表。想随手取用，可以使用浏览器地址栏中的“安装”选项，把它添加为一个应用。
 
 ## 桌面
 
-从 GitHub 发布页或 OpenChamber 下载页下载最新的桌面版本。
+从 GitHub 发布页或 OpenChamber 下载页下载最新的桌面版本。打开它，并登录你常用的 OpenCode 工作流。
 
 ## VS Code
 
-从 VS Code Marketplace 安装，并登录你常用的 OpenCode 工作流。
+从 VS Code Marketplace 安装，并登录你常用的 OpenCode 工作流。随后 OpenChamber 视图会在侧边栏中打开。
diff --git a/packages/docs/content/docs/zh-cn/quickstart.mdx b/packages/docs/content/docs/zh-cn/quickstart.mdx
index f1814e79..659902bb 100644
--- a/packages/docs/content/docs/zh-cn/quickstart.mdx
+++ b/packages/docs/content/docs/zh-cn/quickstart.mdx
@@ -1,22 +1,26 @@
 ---
 title: 快速开始
-description: 快速启动 OpenChamber，并为任务选择合适的平台。
+description: 快速启动 OpenChamber，并为任务选择合适的应用。
 ---
 
 # 快速开始
 
 ## 最快路径
 
-1. 安装 OpenCode。
-2. 安装 OpenChamber CLI。
+1. 安装 [OpenCode](https://opencode.ai)。
+2. 安装 OpenChamber CLI（一行命令见[安装](/zh-cn/install/)）。
 3. 运行 `openchamber --ui-password be-creative-here`。
-4. 在你的机器上打开 Web UI。
-5. 如有需要，启动隧道并用手机扫描二维码。
+4. 打开 CLI 输出的 URL（通常是 `http://localhost:3000`）。
+5. 想在手机上使用，启动一个[隧道](/zh-cn/tunnels/)并扫描二维码。
 
-请使用强 UI 密码，尤其是当你打算将实例开放到远程时。
+你应该会在浏览器中看到 OpenChamber 会话列表。如果它能加载出来，说明你已经成功运行起来了。
 
-## 我应该使用哪个平台？
+请使用强 UI 密码，尤其是当你打算将实例开放到互联网时。
+
+如果页面无法加载，请查看[问题排查](/zh-cn/troubleshooting/)。
+
+## 我应该使用哪个应用？
 
 - 在以 macOS 为主的日常工作中使用 **桌面**
 - 在远程访问和移动端审查时使用 **Web**
-- 在代码旁进行编辑器原生会话时使用 **VS Code**
+- 在代码旁进行会话时使用 **VS Code**
diff --git a/packages/docs/content/docs/zh-cn/themes.mdx b/packages/docs/content/docs/zh-cn/themes.mdx
index ade18e84..8b7f0b6c 100644
--- a/packages/docs/content/docs/zh-cn/themes.mdx
+++ b/packages/docs/content/docs/zh-cn/themes.mdx
@@ -17,7 +17,7 @@ mkdir -p ~/.config/openchamber/themes
 
 2. 将你的 JSON 文件添加到该目录（例如 `my-theme.json`）。
 3. 打开 OpenChamber，然后前往 **Settings -> Theme -> Reload themes**。
-4. 从下拉菜单中选择你的主题。
+4. 从下拉菜单中选择你的主题。它会立即生效。
 
 ## 主题位置
 
diff --git a/packages/docs/content/docs/zh-cn/troubleshooting.mdx b/packages/docs/content/docs/zh-cn/troubleshooting.mdx
index 681e1717..e07cf107 100644
--- a/packages/docs/content/docs/zh-cn/troubleshooting.mdx
+++ b/packages/docs/content/docs/zh-cn/troubleshooting.mdx
@@ -5,6 +5,8 @@ description: 常见的设置与运行问题及快速解决方法。
 
 # 问题排查
 
+遇到问题了？在下面找到对应的现象，试试相应的解决方法。
+
 ## OpenChamber 命令退出或无法启动
 
 - 确认 Node.js `>=20`
@@ -23,8 +25,16 @@ description: 常见的设置与运行问题及快速解决方法。
 - 从同一实例/端口重启隧道
 - 如果之前的令牌已被使用，请重新生成连接链接
 
+完整设置请参阅[隧道](/zh-cn/tunnels/)；如果你使用反向代理，请参阅[反向代理](/zh-cn/reverse-proxy/)。
+
 ## VS Code 扩展无法连接
 
 - 确认 OpenChamber 服务器正在运行
 - 确认扩展已更新
 - 重新加载 VS Code 窗口并重试连接
+
+## 相关内容
+
+- [快速开始](/zh-cn/quickstart/)
+- [隧道](/zh-cn/tunnels/)
+- [反向代理](/zh-cn/reverse-proxy/)
diff --git a/packages/docs/content/docs/zh-cn/tunnels.mdx b/packages/docs/content/docs/zh-cn/tunnels.mdx
index 59138652..0e049f21 100644
--- a/packages/docs/content/docs/zh-cn/tunnels.mdx
+++ b/packages/docs/content/docs/zh-cn/tunnels.mdx
@@ -5,7 +5,7 @@ description: 安全地将 OpenChamber 开放给远程和移动访问。
 
 # 隧道
 
-使用 `openchamber tunnel` 来开放正在运行的 OpenChamber 实例。
+隧道是指向你的 OpenChamber 的一个公开链接，让你可以从手机或另一个网络访问它。使用 `openchamber tunnel` 为正在运行的实例创建一个隧道。
 
 ## 快速开始（Cloudflare 快速模式）
 
@@ -27,6 +27,8 @@ openchamber tunnel start --provider cloudflare --mode quick
 openchamber tunnel status
 ```
 
+隧道建立后，`status` 会显示一个公开 URL。打开它，或扫描二维码，即可从任何地方访问 OpenChamber。
+
 默认情况下，OpenChamber 会在交互式 TTY 会话中输出二维码。使用 `--qr` 强制输出二维码，或使用 `--no-qr` 将其禁用。
 
 ## 托管模式
@@ -75,3 +77,7 @@ openchamber tunnel stop --port 3000
 - 每个 OpenChamber 实例（端口）只有一个活动隧道
 - 在同一实例上启动新的模式/提供商会替换之前的隧道
 - 生成新的连接链接会吊销之前未使用的链接
+
+## 相关内容
+
+- [问题排查](/zh-cn/troubleshooting/) — 如果隧道链接无法使用