docs: add Voice & Style guide and rewrite docs pages to match

Add a Voice & Style section to the docs authoring guide, then bring every
docs page in line with it: lead with the task, add success signals to
procedures, explain jargon on first use, keep bullet casing consistent,
and link out to Troubleshooting where steps can fail.

Applied across English source and all localized versions (uk, zh-cn, es,
pt-br, ko, pl).

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/`.

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
+- instalar la app adecuada para tu forma de trabajar
-- exponer OpenChamber de forma segura para uso remoto
+- abrir OpenChamber para un uso remoto seguro
 - personalizar la apariencia y resolver problemas comunes
 
 ## Lee esto primero

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.

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.
+1. Instala [OpenCode](https://opencode.ai).
-2. Instala la CLI de OpenChamber.
+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.
+4. Abre la URL que imprime la CLI (normalmente `http://localhost:3000`).
-5. Si lo necesitas, inicia un túnel y escanea el código QR desde tu teléfono.
+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
+Si la página no carga, consulta [Resolución de problemas](/es/troubleshooting/).
-- usa **web** para acceso remoto y revisión desde el móvil
+
-- usa **VS Code** para sesiones nativas del editor, junto al código
+## ¿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

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
 

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/)

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

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
+- install the right app for how you work
-- expose OpenChamber safely for remote use
+- open OpenChamber for safe remote use
-- customize appearance and troubleshoot common issues
+- customize the look and fix common issues
 
 ## Read this first
 

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.

packages/docs/content/docs/ko/index.mdx

@@ -5,12 +5,12 @@ description: 웹, 데스크톱, VS Code에서 OpenChamber를 설정하고 운영
 
 # OpenChamber 문서
 
-OpenChamber는 OpenCode를 둘러싼 시각적 작업 공간입니다.
+OpenChamber는 OpenCode(터미널에서 실행되는 AI 코딩 에이전트)를 둘러싼 시각적 작업 공간입니다. 명령줄에 머무르는 대신, 그 작업을 지켜보고 조율할 수 있는 화면을 제공합니다.
 
 이 문서를 사용해:
 
-- 워크플로에 맞는 플랫폼을 설치하세요
+- 작업 방식에 맞는 앱을 설치하세요
-- 원격 사용을 위해 OpenChamber를 안전하게 공개하세요
+- 안전한 원격 사용을 위해 OpenChamber를 여세요
 - 외관을 맞춤 설정하고 흔한 문제를 해결하세요
 
 ## 먼저 읽어보기

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 뷰가 열립니다.

packages/docs/content/docs/ko/quickstart.mdx

@@ -1,22 +1,26 @@
 ---
 title: 빠른 시작
-description: OpenChamber를 빠르게 시작하고 작업에 맞는 플랫폼을 선택하세요.
+description: OpenChamber를 빠르게 시작하고 작업에 맞는 앱을 선택하세요.
 ---
 
 # 빠른 시작
 
 ## 가장 빠른 경로
 
-1. OpenCode를 설치합니다.
+1. [OpenCode](https://opencode.ai)를 설치합니다.
-2. OpenChamber CLI를 설치합니다.
+2. OpenChamber CLI를 설치합니다(한 줄 명령은 [설치](/ko/install/)를 참고하세요).
 3. `openchamber --ui-password be-creative-here`를 실행합니다.
-4. 컴퓨터에서 웹 UI를 엽니다.
+4. CLI가 출력한 URL을 엽니다(보통 `http://localhost:3000`).
-5. 필요하면 터널을 시작하고 휴대폰으로 QR 코드를 스캔합니다.
+5. 휴대폰에서 사용하려면 [터널](/ko/tunnels/)을 시작하고 QR 코드를 스캔합니다.
 
-특히 인스턴스를 원격으로 공개할 계획이라면 강력한 UI 비밀번호를 사용하세요.
+브라우저에 OpenChamber 세션 목록이 보일 것입니다. 화면이 뜨면 정상적으로 실행된 것입니다.
 
-## 어떤 플랫폼을 사용해야 하나요?
+특히 인스턴스를 인터넷에 공개할 계획이라면 강력한 UI 비밀번호를 사용하세요.
 
-- macOS 중심의 일상 작업에는 **데스크톱**을 사용하세요
+페이지가 열리지 않으면 [문제 해결](/ko/troubleshooting/)을 확인하세요.
-- 원격 접근과 모바일 검토에는 **웹**을 사용하세요
+
-- 코드 옆에서 에디터 네이티브 세션을 원하면 **VS Code**를 사용하세요
+## 어떤 앱을 사용해야 하나요?
+
+- macOS에서의 일상 작업에는 **데스크톱**을 사용하세요
+- 원격 접근과 휴대폰 검토에는 **웹**을 사용하세요
+- 코드 바로 옆에서 작업하는 세션에는 **VS Code**를 사용하세요

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. 드롭다운에서 테마를 선택합니다. 곧바로 적용됩니다.
 
 ## 테마 위치
 

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/)

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/) — 터널 링크가 작동하지 않을 때

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:
 

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.

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.
+1. Zainstaluj [OpenCode](https://opencode.ai).
-2. Zainstaluj CLI OpenChamber.
+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.
+4. Otwórz adres URL wypisany przez CLI (zwykle `http://localhost:3000`).
-5. W razie potrzeby uruchom tunel i zeskanuj kod QR telefonem.
+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

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
 

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/)

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

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

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.

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.
+1. Instale o [OpenCode](https://opencode.ai).
-2. Instale a CLI do OpenChamber.
+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.
+4. Abra a URL que a CLI imprime (geralmente `http://localhost:3000`).
-5. Se precisar, inicie um túnel e escaneie o QR code pelo celular.
+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

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
 

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/)

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

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.
+1. Install [OpenCode](https://opencode.ai).
-2. Install OpenChamber CLI.
+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.
+4. Open the URL the CLI prints (usually `http://localhost:3000`).
-5. If needed, start a tunnel and scan the QR code from your phone.
+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
+If the page doesn't load, check [Troubleshooting](/troubleshooting/).
-- use **web** for remote access and mobile review
+
-- use **VS Code** for editor-native sessions beside code
+## 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

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
 

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/)

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

packages/docs/content/docs/uk/index.mdx

@@ -5,11 +5,11 @@ description: Посібник з налаштування та роботи з O
 
 # Документація OpenChamber
 
-OpenChamber — це візуальний робочий простір навколо OpenCode.
+OpenChamber — це візуальний робочий простір навколо OpenCode (AI-агента для кодингу, який працює у вашому терміналі). Він дає екран, де можна спостерігати за цією роботою та керувати нею, замість того щоб лишатися в командному рядку.
 
 Використовуйте ці доки, щоб:
 
-- встановити платформу, що пасує вашому робочому процесу
+- встановити застосунок, що пасує вашому робочому процесу
 - безпечно відкрити OpenChamber для віддаленого використання
 - налаштувати вигляд і усувати типові проблеми
 

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 відкриється на бічній панелі.

packages/docs/content/docs/uk/quickstart.mdx

@@ -7,16 +7,20 @@ description: Швидко запустіть OpenChamber і оберіть пл
 
 ## Найшвидший шлях
 
-1. Встановіть OpenCode.
+1. Встановіть [OpenCode](https://opencode.ai).
-2. Встановіть CLI OpenChamber.
+2. Встановіть CLI OpenChamber (команду в один рядок дивіться в [Встановленні](/uk/install/)).
 3. Виконайте `openchamber --ui-password be-creative-here`.
-4. Відкрийте веб-UI на своїй машині.
+4. Відкрийте URL, який вивів CLI (зазвичай `http://localhost:3000`).
-5. За потреби запустіть тунель і відскануйте QR-код із телефона.
+5. Щоб користуватися з телефона, запустіть [тунель](/uk/tunnels/) і відскануйте QR-код.
 
-Використовуйте надійний пароль UI, особливо якщо плануєте відкривати інстанс віддалено.
+У браузері ви маєте побачити список сесій OpenChamber. Якщо він завантажився — все працює.
+
+Використовуйте надійний пароль UI, особливо якщо плануєте відкривати доступ до інстансу з інтернету.
+
+Якщо сторінка не завантажується, перегляньте [Усунення несправностей](/uk/troubleshooting/).
 
 ## Яку платформу обрати?
 
-- обирайте **десктоп** для щоденної роботи переважно на macOS
+- обирайте **десктоп** для щоденної роботи на macOS
-- обирайте **веб** для віддаленого доступу та перегляду з мобільного
+- обирайте **веб** для віддаленого доступу та перегляду з телефона
-- обирайте **VS Code** для сесій усередині редактора, поруч із кодом
+- обирайте **VS Code** для сесій поруч із вашим кодом

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. Оберіть свою тему зі спадного списку. Вона застосується одразу.
 
 ## Розташування тем
 

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/)

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/) — якщо посилання тунелю не працює

packages/docs/content/docs/zh-cn/index.mdx

@@ -5,11 +5,11 @@ description: 在 Web、桌面与 VS Code 上设置和使用 OpenChamber 的指
 
 # OpenChamber 文档
 
-OpenChamber 是围绕 OpenCode 的可视化工作空间。
+OpenChamber 是围绕 OpenCode（在你终端中运行的 AI 编程智能体）的可视化工作空间。它给你一块屏幕去观察并引导这些工作，而不必停留在命令行里。
 
 使用本文档来：
 
-- 为你的工作流安装合适的平台
+- 为你的工作方式安装合适的应用
 - 安全地将 OpenChamber 开放给远程使用
 - 自定义外观并排查常见问题
 

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 视图会在侧边栏中打开。

packages/docs/content/docs/zh-cn/quickstart.mdx

@@ -1,22 +1,26 @@
 ---
 title: 快速开始
-description: 快速启动 OpenChamber，并为任务选择合适的平台。
+description: 快速启动 OpenChamber，并为任务选择合适的应用。
 ---
 
 # 快速开始
 
 ## 最快路径
 
-1. 安装 OpenCode。
+1. 安装 [OpenCode](https://opencode.ai)。
-2. 安装 OpenChamber CLI。
+2. 安装 OpenChamber CLI（一行命令见[安装](/zh-cn/install/)）。
 3. 运行 `openchamber --ui-password be-creative-here`。
-4. 在你的机器上打开 Web UI。
+4. 打开 CLI 输出的 URL（通常是 `http://localhost:3000`）。
-5. 如有需要，启动隧道并用手机扫描二维码。
+5. 想在手机上使用，启动一个[隧道](/zh-cn/tunnels/)并扫描二维码。
 
-请使用强 UI 密码，尤其是当你打算将实例开放到远程时。
+你应该会在浏览器中看到 OpenChamber 会话列表。如果它能加载出来，说明你已经成功运行起来了。
 
-## 我应该使用哪个平台？
+请使用强 UI 密码，尤其是当你打算将实例开放到互联网时。
+
+如果页面无法加载，请查看[问题排查](/zh-cn/troubleshooting/)。
+
+## 我应该使用哪个应用？
 
 - 在以 macOS 为主的日常工作中使用 **桌面**
 - 在远程访问和移动端审查时使用 **Web**
-- 在代码旁进行编辑器原生会话时使用 **VS Code**
+- 在代码旁进行会话时使用 **VS Code**

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. 从下拉菜单中选择你的主题。它会立即生效。
 
 ## 主题位置
 

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/)

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/) — 如果隧道链接无法使用