diff --git a/packages/docs/content/docs/es/walkthrough.mdx b/packages/docs/content/docs/es/walkthrough.mdx
new file mode 100644
index 00000000..8eb2c207
--- /dev/null
+++ b/packages/docs/content/docs/es/walkthrough.mdx
@@ -0,0 +1,63 @@
+---
+title: Recorrido por los cambios
+description: Lee un diff en el orden que tiene sentido, no en orden alfabético.
+---
+
+# Recorrido por los cambios
+
+Un diff está ordenado por ruta de archivo, que casi nunca es el orden en el que el cambio cobra sentido. El recorrido lo reordena: las ediciones relacionadas se agrupan en **paradas**, cada parada explica qué hace ahora el código de forma distinta, y las paradas se ordenan para que cada una se apoye en la anterior.
+
+Explica y ordena. No juzga tu código ni emite veredictos — para eso está [Review](/git/).
+
+Ábrelo con el icono **Recorrido** en la barra derecha, o con el botón **Recorrido con IA** en los paneles de cambios y de pull request. Ambos solo abren el panel; no se genera nada hasta que pulsas **Generar recorrido**.
+
+## Qué puede recorrer
+
+| Ámbito | Qué incluye |
+| --- | --- |
+| Todo sin confirmar | Todo lo que aún no está en un commit: preparado, sin preparar y archivos nuevos |
+| Preparados | Solo lo que iría a un commit ahora mismo |
+| Sin preparar | Árbol de trabajo y archivos nuevos |
+| Esta rama | Todos los commits de la rama que no están en su base |
+| Pull request | El cambio tal como existe en GitHub |
+
+**Esta rama** no significa "commits sin subir": es todo lo que la rama añade a su base, se haya subido o no. Por eso, tras hacer commit pero antes de subirlo, esta y el pull request difieren a propósito: una muestra lo que hiciste, el otro lo que ven ahora quienes revisan.
+
+Cada ámbito se guarda por separado, así que cambiar entre ellos nunca pierde nada.
+
+## Elegir el modelo
+
+Los recorridos usan tu modelo pequeño por defecto. Elige otro en **Ajustes → Sesiones → Modelo del recorrido de cambios**, o solo para una revisión desde la cabecera del panel — útil cuando un cambio es lo bastante delicado como para merecer un modelo más potente.
+
+El selector solo ofrece modelos capaces de devolver salida estructurada, porque sin ella el recorrido no se puede montar. Si un modelo se queda corto para el diff, la generación se rechaza con una explicación en vez de recortar la entrada en silencio: un recorrido escrito sobre medio diff suena seguro y se equivoca.
+
+Al reabrir el panel verás el modelo que produjo lo que tienes delante, así que **Regenerar** repite con el mismo salvo que lo cambies.
+
+## Coste y caché
+
+Nada se genera por su cuenta. La generación solo empieza cuando la pides, y regenerar también es manual.
+
+Los resultados se guardan en caché según el contenido exacto del diff. Devuelve el árbol de trabajo a un estado anterior y el recorrido anterior vuelve gratis, sin llamar al modelo. Cambia de modelo y vuelve: el recorrido de cada uno sigue ahí.
+
+La generación se ejecuta en el servidor de OpenChamber, no en la pestaña del navegador. Recarga la página o cierra el panel y continúa; al volver, el resultado te espera. Solo **Cancelar** la detiene.
+
+## Ser honesto sobre lo desactualizado
+
+Cada parada está anclada al contenido exacto del código que describe, así que el panel puede avisarte cuando ese código ha cambiado:
+
+- **Pasos desactualizados** — el código que describía una parada cambió o desapareció. El recorrido se sigue mostrando, marcado, para que decidas si regenerar.
+- **Sin cubrir** — cambios del diff actual que ninguna parada describe. Ahí entran las ediciones hechas después de generar, los cambios que el recorrido consideró rutinarios y los archivos de bloqueo u otra salida generada, que se dejan fuera del modelo a propósito. Todo aparece al final para que nada desaparezca en silencio.
+
+Regenerar no parchea, reescribe: el recorrido anterior va al modelo como contexto, así que lo que sigue siendo cierto se conserva, y todo se reancla al código actual.
+
+## Notas
+
+- Puedes comentar cualquier línea igual que en la vista de diff; los comentarios se adjuntan al campo del chat.
+- Disponible en escritorio y anchos de tableta. No se ofrece en la extensión de VS Code ni en la app móvil.
+- Recorrer un pull request requiere una cuenta de GitHub conectada — consulta [Issues y PR de GitHub](/github/).
+
+## Relacionado
+
+- [Git y GitHub](/git/) — el panel de cambios del que lee, y la acción Review que sí juzga el código
+- [Issues y PR de GitHub](/github/) — conecta GitHub para recorrer pull requests
+- [Proveedores, modelos y agentes](/providers/) — de dónde sale el modelo pequeño
diff --git a/packages/docs/content/docs/fr/walkthrough.mdx b/packages/docs/content/docs/fr/walkthrough.mdx
new file mode 100644
index 00000000..5f7dc41e
--- /dev/null
+++ b/packages/docs/content/docs/fr/walkthrough.mdx
@@ -0,0 +1,63 @@
+---
+title: Parcours des modifications
+description: Lisez un diff dans l’ordre qui a du sens, pas dans l’ordre alphabétique.
+---
+
+# Parcours des modifications
+
+Un diff est trié par chemin de fichier, ce qui n’est presque jamais l’ordre dans lequel la modification prend son sens. Le parcours le réorganise : les changements liés sont regroupés en **étapes**, chaque étape explique ce que le code fait désormais différemment, et les étapes s’enchaînent pour que chacune s’appuie sur la précédente.
+
+Il explique et ordonne. Il ne juge pas votre code et ne rend aucun verdict — c’est le rôle de [Review](/git/).
+
+Ouvrez-le par l’icône **Parcours** dans la barre de droite, ou par le bouton **Parcours IA** dans les panneaux des modifications et de la pull request. Les deux se contentent d’ouvrir le panneau ; rien n’est généré tant que vous n’appuyez pas sur **Générer le parcours**.
+
+## Ce qu’il peut parcourir
+
+| Portée | Ce qu’elle couvre |
+| --- | --- |
+| Tout non validé | Tout ce qui n’est pas encore dans un commit : indexé, non indexé et nouveaux fichiers |
+| Indexées | Uniquement ce qui partirait dans un commit maintenant |
+| Non indexées | Copie de travail et nouveaux fichiers |
+| Cette branche | Tous les commits de la branche absents de sa base |
+| Pull request | La modification telle qu’elle existe sur GitHub |
+
+**Cette branche** ne veut pas dire « commits non poussés » : c’est tout ce que la branche ajoute à sa base, poussé ou non. Après un commit mais avant un push, elle et la pull request diffèrent donc volontairement : l’une montre ce que vous avez fait, l’autre ce que voient les relecteurs.
+
+Chaque portée est stockée séparément : passer de l’une à l’autre ne perd jamais rien.
+
+## Choisir le modèle
+
+Les parcours utilisent votre petit modèle par défaut. Choisissez-en un autre dans **Paramètres → Sessions → Modèle du parcours des modifications**, ou pour une seule relecture depuis l’en-tête du panneau — utile quand une modification est assez risquée pour mériter un modèle plus solide.
+
+Le sélecteur ne propose que des modèles capables de sortie structurée, sans laquelle le parcours ne peut pas être assemblé. Si un modèle est trop petit pour le diff, la génération est refusée avec une explication plutôt que de tronquer l’entrée en silence : un parcours écrit sur la moitié d’un diff sonne assuré et se trompe.
+
+En rouvrant le panneau, vous voyez le modèle qui a produit ce que vous avez sous les yeux ; **Régénérer** reprend donc le même tant que vous n’en changez pas.
+
+## Coût et cache
+
+Rien ne se génère tout seul. La génération ne démarre que sur votre demande, et la régénération est manuelle elle aussi.
+
+Les résultats sont mis en cache d’après le contenu exact du diff. Ramenez la copie de travail à un état antérieur et le parcours d’alors revient gratuitement, sans appel au modèle. Changez de modèle puis revenez : le parcours de chacun est toujours là.
+
+La génération tourne sur le serveur OpenChamber, pas dans votre onglet. Rechargez la page ou fermez le panneau : le travail continue et le résultat vous attend. Seul **Annuler** l’interrompt.
+
+## Rester honnête sur l’obsolescence
+
+Chaque étape est ancrée au contenu exact du code qu’elle décrit, ce qui permet au panneau de signaler quand ce code a bougé :
+
+- **Étapes obsolètes** — le code décrit par une étape a changé ou disparu. Le parcours reste affiché, marqué, pour que vous décidiez s’il faut régénérer.
+- **Non traité** — des modifications du diff actuel qu’aucune étape ne décrit. On y trouve les changements faits après la génération, ceux que le parcours a jugés courants, ainsi que les fichiers de verrouillage et autres sorties générées, délibérément tenus hors du modèle. Tout est listé à la fin pour que rien ne disparaisse en silence.
+
+Régénérer ne rapièce pas, cela réécrit : le parcours précédent est fourni au modèle comme contexte, ce qui reste vrai est conservé, et tout est réancré sur le code actuel.
+
+## Notes
+
+- Vous pouvez commenter n’importe quelle ligne comme dans la vue diff ; les commentaires se rattachent au champ du chat.
+- Disponible sur ordinateur et sur les largeurs de tablette. Non proposé dans l’extension VS Code ni dans l’application mobile.
+- Parcourir une pull request exige un compte GitHub connecté — voir [Issues et PR GitHub](/github/).
+
+## Voir aussi
+
+- [Git et GitHub](/git/) — le panneau des modifications qu’il lit, et l’action Review qui, elle, juge le code
+- [Issues et PR GitHub](/github/) — connectez GitHub pour parcourir les pull requests
+- [Fournisseurs, modèles et agents](/providers/) — d’où vient le petit modèle
diff --git a/packages/docs/content/docs/ja/walkthrough.mdx b/packages/docs/content/docs/ja/walkthrough.mdx
new file mode 100644
index 00000000..ea43496f
--- /dev/null
+++ b/packages/docs/content/docs/ja/walkthrough.mdx
@@ -0,0 +1,63 @@
+---
+title: 変更のウォークスルー
+description: 差分をアルファベット順ではなく、意味の通る順序で読みます。
+---
+
+# 変更のウォークスルー
+
+差分はファイルパス順に並びますが、それは変更の意味が通る順序であることはほとんどありません。ウォークスルーはこれを並べ替えます。関連する編集を**ステップ**にまとめ、各ステップはコードが今までと何が違う動きをするのかを説明し、前のステップの上に次が積み上がる順序で並びます。
+
+説明し、順序を与えるものです。コードを評価したり判定を下したりはしません。それは [Review](/git/) の役割です。
+
+右側のレールの**ウォークスルー**アイコン、または変更パネルとプルリクエストパネルの **AI ウォークスルー**ボタンから開きます。どちらもパネルを開くだけで、**ウォークスルーを生成**を押すまで何も生成されません。
+
+## 対象にできる範囲
+
+| 範囲 | 含まれるもの |
+| --- | --- |
+| 未コミットすべて | まだコミットされていないもの全部: ステージ済み、未ステージ、新規ファイル |
+| ステージ済み | 今コミットすれば入るものだけ |
+| 未ステージ | 作業ツリーと新規ファイル |
+| このブランチ | ベースに無い、このブランチのすべてのコミット |
+| プルリクエスト | GitHub 上に存在する形の変更 |
+
+**このブランチ**は「未プッシュのコミット」ではなく、プッシュの有無に関わらずブランチがベースに追加したすべてです。そのためコミット後・プッシュ前には、これとプルリクエストは意図的に食い違います。前者はあなたが何をしたかを、後者はレビュアーが今何を見ているかを示します。
+
+範囲ごとに別々に保存されるため、切り替えても失われるものはありません。
+
+## モデルの選択
+
+ウォークスルーは既定でスモールモデルを使います。**設定 → セッション → 変更ウォークスルーのモデル**で別のモデルを選べます。一度だけならパネルのヘッダーからも選べます。リスクの高い変更を、より強いモデルに任せたいときに便利です。
+
+選択肢に出るのは構造化出力を返せるモデルだけです。それが無ければウォークスルーは組み立てられません。差分に対してモデルが小さすぎる場合は、入力を黙って切り詰めるのではなく、理由を示して生成を拒否します。差分の半分だけを見て書かれたウォークスルーは、自信ありげに間違えるからです。
+
+パネルを開き直すと、目の前の内容を生成したモデルが表示されます。したがって**再生成**は、変更しない限り同じモデルで繰り返します。
+
+## コストとキャッシュ
+
+勝手に生成されることはありません。生成はあなたが求めたときだけ始まり、再生成も手動です。
+
+結果は差分の正確な内容に対してキャッシュされます。作業ツリーを以前の状態に戻せば、そのときのウォークスルーがモデル呼び出し無しで戻ります。モデルを切り替えて戻しても、それぞれのウォークスルーは残っています。
+
+生成はブラウザのタブではなく OpenChamber サーバー上で動きます。ページを再読み込みしてもパネルを閉じても処理は続き、戻れば結果が待っています。止められるのは**キャンセル**だけです。
+
+## 古くなったことを正直に示す
+
+各ステップは説明対象のコードの正確な内容に紐づいているため、そのコードが動いたことをパネルが伝えられます。
+
+- **古くなったステップ** — ステップが説明していたコードが変わった、あるいは無くなった。ウォークスルーは印を付けたまま表示され、再生成するかはあなたが決めます。
+- **未対応** — 現在の差分のうち、どのステップも説明していない変更。生成後に加えた編集、ウォークスルーが定型的と判断した変更、そして意図的にモデルへ渡していないロックファイルなどの生成物が含まれます。すべて末尾に一覧されるので、黙って消えるものはありません。
+
+再生成は継ぎ当てではなく書き直しです。前回のウォークスルーが文脈としてモデルに渡るため、まだ正しい部分は残り、すべてが現在のコードに紐づけ直されます。
+
+## 補足
+
+- 差分ビューと同じように任意の行にコメントできます。コメントはチャットの入力欄に添付されます。
+- デスクトップとタブレット幅で利用できます。VS Code 拡張とモバイルアプリでは提供されません。
+- プルリクエストのウォークスルーには GitHub アカウントの接続が必要です。[GitHub の Issue と PR](/github/) を参照してください。
+
+## 関連
+
+- [Git と GitHub](/git/) — 読み取り元となる変更パネルと、実際にコードを評価する Review アクション
+- [GitHub の Issue と PR](/github/) — プルリクエストを扱うために GitHub を接続する
+- [プロバイダー・モデル・エージェント](/providers/) — スモールモデルの出どころ
diff --git a/packages/docs/content/docs/ko/walkthrough.mdx b/packages/docs/content/docs/ko/walkthrough.mdx
new file mode 100644
index 00000000..9d305838
--- /dev/null
+++ b/packages/docs/content/docs/ko/walkthrough.mdx
@@ -0,0 +1,63 @@
+---
+title: 변경 워크스루
+description: diff를 알파벳순이 아니라 이해되는 순서로 읽습니다.
+---
+
+# 변경 워크스루
+
+diff는 파일 경로순으로 정렬되지만, 그 순서가 변경을 이해하기 좋은 순서인 경우는 거의 없습니다. 워크스루는 이를 다시 배열합니다. 관련된 수정들을 **단계**로 묶고, 각 단계는 코드가 이제 무엇을 다르게 하는지 설명하며, 앞 단계 위에 다음 단계가 쌓이도록 순서를 정합니다.
+
+설명하고 순서를 부여할 뿐, 코드를 심사하거나 판정을 내리지 않습니다. 그건 [Review](/git/)의 역할입니다.
+
+오른쪽 레일의 **워크스루** 아이콘이나, 변경 패널과 풀 리퀘스트 패널의 **AI 워크스루** 버튼으로 엽니다. 둘 다 패널을 열기만 하며, **워크스루 생성**을 누르기 전에는 아무것도 생성되지 않습니다.
+
+## 다룰 수 있는 범위
+
+| 범위 | 포함되는 것 |
+| --- | --- |
+| 커밋되지 않은 전체 | 아직 커밋되지 않은 모든 것: 스테이지됨, 스테이지 안 됨, 새 파일 |
+| 스테이지됨 | 지금 커밋하면 들어갈 것만 |
+| 스테이지 안 됨 | 작업 트리와 새 파일 |
+| 이 브랜치 | 베이스에 없는 이 브랜치의 모든 커밋 |
+| 풀 리퀘스트 | GitHub에 존재하는 형태의 변경 |
+
+**이 브랜치**는 "푸시하지 않은 커밋"이 아니라, 푸시 여부와 무관하게 브랜치가 베이스에 더한 전부입니다. 그래서 커밋한 뒤 푸시하기 전에는 이것과 풀 리퀘스트가 의도적으로 달라집니다. 하나는 당신이 한 일을, 다른 하나는 리뷰어가 지금 보는 것을 보여줍니다.
+
+범위마다 따로 저장되므로 전환해도 잃는 것이 없습니다.
+
+## 모델 선택
+
+워크스루는 기본적으로 스몰 모델을 사용합니다. **설정 → 세션 → 변경 워크스루 모델**에서 다른 모델을 고르거나, 한 번만 쓸 모델은 패널 헤더에서 고를 수 있습니다. 변경이 충분히 위험해서 더 강한 모델에 맡기고 싶을 때 유용합니다.
+
+선택 목록에는 구조화된 출력을 반환할 수 있는 모델만 나옵니다. 그것 없이는 워크스루를 구성할 수 없기 때문입니다. 모델이 diff에 비해 작으면 입력을 조용히 잘라내는 대신 이유를 설명하며 생성을 거부합니다. diff의 절반만 보고 쓴 워크스루는 자신 있게 틀리기 때문입니다.
+
+패널을 다시 열면 지금 보고 있는 결과를 만든 모델이 표시되므로, 바꾸지 않는 한 **다시 생성**은 같은 모델로 반복합니다.
+
+## 비용과 캐시
+
+저절로 생성되는 것은 없습니다. 생성은 요청할 때만 시작되고, 재생성도 수동입니다.
+
+결과는 diff의 정확한 내용을 기준으로 캐시됩니다. 작업 트리를 이전 상태로 되돌리면 그때의 워크스루가 모델 호출 없이 그대로 돌아옵니다. 모델을 바꿨다가 되돌려도 각각의 워크스루가 남아 있습니다.
+
+생성은 브라우저 탭이 아니라 OpenChamber 서버에서 실행됩니다. 페이지를 새로 고치거나 패널을 닫아도 작업은 계속되고, 돌아오면 결과가 기다립니다. 멈추는 것은 **취소**뿐입니다.
+
+## 오래됨을 정직하게 알리기
+
+각 단계는 설명 대상 코드의 정확한 내용에 묶여 있어서, 그 코드가 변했을 때 패널이 알려줄 수 있습니다.
+
+- **오래된 단계** — 단계가 설명하던 코드가 바뀌었거나 사라졌습니다. 워크스루는 표시된 채로 계속 보이며, 다시 생성할지는 당신이 정합니다.
+- **미포함** — 현재 diff에서 어떤 단계도 설명하지 않는 변경입니다. 생성 이후에 한 수정, 워크스루가 일상적이라고 판단한 변경, 그리고 의도적으로 모델에 넘기지 않는 잠금 파일 등 생성물이 여기에 들어갑니다. 모두 끝에 나열되므로 조용히 사라지는 것은 없습니다.
+
+재생성은 기우는 것이 아니라 다시 쓰는 것입니다. 이전 워크스루가 맥락으로 모델에 전달되어 여전히 맞는 부분은 살아남고, 전체가 현재 코드에 다시 묶입니다.
+
+## 참고
+
+- diff 보기와 똑같이 아무 줄에나 코멘트할 수 있고, 코멘트는 채팅 입력창에 첨부됩니다.
+- 데스크톱과 태블릿 너비에서 사용할 수 있습니다. VS Code 확장과 모바일 앱에서는 제공되지 않습니다.
+- 풀 리퀘스트 워크스루에는 연결된 GitHub 계정이 필요합니다 — [GitHub 이슈와 PR](/github/)을 참고하세요.
+
+## 관련 문서
+
+- [Git과 GitHub](/git/) — 이 기능이 읽어오는 변경 패널, 그리고 실제로 코드를 심사하는 Review 액션
+- [GitHub 이슈와 PR](/github/) — 풀 리퀘스트를 다루려면 GitHub를 연결하세요
+- [프로바이더, 모델, 에이전트](/providers/) — 스몰 모델이 어디서 오는지
diff --git a/packages/docs/content/docs/pl/walkthrough.mdx b/packages/docs/content/docs/pl/walkthrough.mdx
new file mode 100644
index 00000000..5377f828
--- /dev/null
+++ b/packages/docs/content/docs/pl/walkthrough.mdx
@@ -0,0 +1,63 @@
+---
+title: Przewodnik po zmianach
+description: Czytaj różnice w kolejności, która ma sens, a nie alfabetycznie.
+---
+
+# Przewodnik po zmianach
+
+Różnice są posortowane po ścieżkach plików, a to prawie nigdy nie jest kolejność, w której zmiana staje się zrozumiała. Przewodnik układa je na nowo: powiązane edycje trafiają do wspólnych **kroków**, każdy krok tłumaczy, co kod robi teraz inaczej, a kolejność kroków jest taka, by każdy opierał się na poprzednim.
+
+Tłumaczy i porządkuje. Nie ocenia kodu i nie wydaje werdyktów — od tego jest [Review](/git/).
+
+Otwórz go ikoną **Przewodnik** na prawym pasku albo przyciskiem **Przewodnik AI** w panelach zmian i pull requestu. Oba tylko otwierają panel; nic nie powstaje, dopóki nie naciśniesz **Wygeneruj przewodnik**.
+
+## Co można przejrzeć
+
+| Zakres | Co obejmuje |
+| --- | --- |
+| Wszystko niezatwierdzone | Wszystko, czego nie ma jeszcze w commicie: poczekalnia, drzewo robocze i nowe pliki |
+| W poczekalni | Tylko to, co trafiłoby teraz do commita |
+| Poza poczekalnią | Drzewo robocze i nowe pliki |
+| Ta gałąź | Wszystkie commity gałęzi, których nie ma w jej bazie |
+| Pull request | Zmiana w postaci, w jakiej istnieje na GitHubie |
+
+**Ta gałąź** to nie „commity bez pusha", lecz wszystko, co gałąź dokłada do swojej bazy — niezależnie od pusha. Dlatego po commicie, a przed pushem, ona i pull request celowo się różnią: jedno pokazuje, co zrobiłeś, drugie to, co widzą teraz recenzenci.
+
+Każdy zakres jest zapisywany osobno, więc przełączanie między nimi niczego nie gubi.
+
+## Wybór modelu
+
+Przewodniki domyślnie używają małego modelu. Inny wybierzesz w **Ustawienia → Sesje → Model przewodnika po zmianach** albo — na jeden raz — w nagłówku panelu. Przydaje się, gdy zmiana jest na tyle ryzykowna, że zasługuje na mocniejszy model.
+
+Lista pokazuje tylko modele potrafiące zwracać ustrukturyzowaną odpowiedź, bo bez niej przewodnika nie da się złożyć. Jeśli model jest za mały na te różnice, generowanie zostaje odrzucone z wyjaśnieniem, zamiast po cichu obciąć wejście: przewodnik napisany na podstawie połowy różnic brzmi pewnie i się myli.
+
+Po ponownym otwarciu panelu zobaczysz model, który stworzył to, co masz przed sobą, więc **Wygeneruj ponownie** powtórzy tym samym, dopóki go nie zmienisz.
+
+## Koszt i pamięć podręczna
+
+Nic nie generuje się samo. Generowanie zaczyna się wyłącznie na Twoje żądanie, ponowne również jest ręczne.
+
+Wyniki są zapisywane w pamięci podręcznej według dokładnej treści różnic. Przywróć drzewo robocze do wcześniejszego stanu, a tamten przewodnik wróci za darmo, bez wywołania modelu. Przełącz model i wróć — przewodnik każdego z nich nadal tam jest.
+
+Generowanie działa na serwerze OpenChamber, nie w karcie przeglądarki. Odśwież stronę albo zamknij panel, a praca trwa dalej; po powrocie wynik czeka. Zatrzymuje ją tylko **Anuluj**.
+
+## Uczciwość wobec nieaktualności
+
+Każdy krok jest przypięty do dokładnej treści kodu, który opisuje, więc panel potrafi powiedzieć, kiedy ten kod się zmienił:
+
+- **Nieaktualne kroki** — kod opisywany przez krok zmienił się albo zniknął. Przewodnik nadal się wyświetla, z oznaczeniem, żebyś sam zdecydował o ponownym wygenerowaniu.
+- **Nieuwzględnione** — zmiany w bieżących różnicach, których nie opisuje żaden krok. Trafiają tu edycje zrobione po wygenerowaniu, zmiany uznane przez przewodnik za rutynowe oraz pliki blokad i inne wyniki narzędzi, celowo trzymane poza modelem. Wszystko jest wypisane na końcu, żeby nic nie zniknęło po cichu.
+
+Ponowne wygenerowanie nie łata, lecz pisze od nowa: poprzedni przewodnik trafia do modelu jako kontekst, więc to, co nadal jest prawdą, zostaje, a całość zostaje przypięta do bieżącego kodu.
+
+## Uwagi
+
+- Możesz komentować dowolną linię tak samo jak w widoku różnic; komentarze dołączają się do pola czatu.
+- Dostępne na komputerze i przy szerokościach tabletu. Nie ma tego w rozszerzeniu VS Code ani w aplikacji mobilnej.
+- Przewodnik po pull requeście wymaga połączonego konta GitHub — zobacz [Issues i PR na GitHubie](/github/).
+
+## Powiązane
+
+- [Git i GitHub](/git/) — panel zmian, z którego to czyta, oraz akcja Review, która faktycznie ocenia kod
+- [Issues i PR na GitHubie](/github/) — połącz GitHub, aby przeglądać pull requesty
+- [Dostawcy, modele i agenci](/providers/) — skąd bierze się mały model
diff --git a/packages/docs/content/docs/pt-br/walkthrough.mdx b/packages/docs/content/docs/pt-br/walkthrough.mdx
new file mode 100644
index 00000000..59dbf88d
--- /dev/null
+++ b/packages/docs/content/docs/pt-br/walkthrough.mdx
@@ -0,0 +1,63 @@
+---
+title: Percurso pelas mudanças
+description: Leia um diff na ordem que faz sentido, não em ordem alfabética.
+---
+
+# Percurso pelas mudanças
+
+Um diff é ordenado por caminho de arquivo, que quase nunca é a ordem em que a mudança faz sentido. O percurso reorganiza isso: edições relacionadas viram **paradas**, cada parada explica o que o código passa a fazer de diferente, e as paradas seguem uma ordem em que cada uma se apoia na anterior.
+
+Ele explica e ordena. Não julga o seu código nem dá veredictos — isso é papel do [Review](/git/).
+
+Abra pelo ícone **Percurso** na barra direita ou pelo botão **Percurso com IA** nos painéis de mudanças e de pull request. Ambos apenas abrem o painel; nada é gerado até você apertar **Gerar percurso**.
+
+## O que dá para percorrer
+
+| Escopo | O que inclui |
+| --- | --- |
+| Tudo sem commit | Tudo que ainda não está em commit: no stage, fora do stage e arquivos novos |
+| No stage | Só o que iria para um commit agora |
+| Fora do stage | Árvore de trabalho e arquivos novos |
+| Este branch | Todos os commits do branch que não estão na base |
+| Pull request | A mudança como ela existe no GitHub |
+
+**Este branch** não quer dizer "commits sem push": é tudo o que o branch acrescenta à sua base, com push ou sem. Por isso, depois do commit e antes do push, ele e o pull request divergem de propósito: um mostra o que você fez, o outro o que os revisores veem agora.
+
+Cada escopo é guardado separadamente, então alternar entre eles nunca perde nada.
+
+## Escolhendo o modelo
+
+Os percursos usam o seu modelo pequeno por padrão. Escolha outro em **Configurações → Sessões → Modelo do percurso de mudanças**, ou apenas para uma revisão no cabeçalho do painel — útil quando a mudança é arriscada o bastante para merecer um modelo mais forte.
+
+O seletor só oferece modelos capazes de devolver saída estruturada, porque sem ela o percurso não se monta. Se o modelo for pequeno demais para o diff, a geração é recusada com explicação em vez de cortar a entrada em silêncio: um percurso escrito sobre metade de um diff soa seguro e está errado.
+
+Ao reabrir o painel você vê o modelo que produziu o que está na tela, então **Gerar novamente** repete com o mesmo, a menos que você troque.
+
+## Custo e cache
+
+Nada é gerado sozinho. A geração só começa quando você pede, e gerar de novo também é manual.
+
+Os resultados ficam em cache pelo conteúdo exato do diff. Volte a árvore de trabalho para um estado anterior e aquele percurso retorna de graça, sem chamar o modelo. Troque de modelo e volte: o percurso de cada um continua lá.
+
+A geração roda no servidor do OpenChamber, não na aba do navegador. Recarregue a página ou feche o painel e o trabalho continua; ao voltar, o resultado está esperando. Só **Cancelar** interrompe.
+
+## Honestidade sobre o que ficou velho
+
+Cada parada está ancorada ao conteúdo exato do código que descreve, então o painel consegue avisar quando esse código mudou:
+
+- **Etapas desatualizadas** — o código que a parada descrevia mudou ou sumiu. O percurso continua aparecendo, marcado, para você decidir se regenera.
+- **Sem cobertura** — mudanças do diff atual que nenhuma parada descreve. Entram aí as edições feitas depois de gerar, as mudanças que o percurso considerou rotineiras e os arquivos de lock e outras saídas geradas, mantidas fora do modelo de propósito. Tudo aparece no fim, para que nada suma em silêncio.
+
+Regenerar não remenda, reescreve: o percurso anterior vai ao modelo como contexto, o que ainda é verdade permanece, e tudo é reancorado no código atual.
+
+## Notas
+
+- Você pode comentar qualquer linha como na visão de diff; os comentários se anexam ao campo do chat.
+- Disponível em desktop e larguras de tablet. Não é oferecido na extensão do VS Code nem no app móvel.
+- Percorrer um pull request exige uma conta do GitHub conectada — veja [Issues e PRs do GitHub](/github/).
+
+## Relacionado
+
+- [Git e GitHub](/git/) — o painel de mudanças de onde isso lê, e a ação Review, que de fato julga o código
+- [Issues e PRs do GitHub](/github/) — conecte o GitHub para percorrer pull requests
+- [Provedores, modelos e agentes](/providers/) — de onde vem o modelo pequeno
diff --git a/packages/docs/content/docs/uk/walkthrough.mdx b/packages/docs/content/docs/uk/walkthrough.mdx
new file mode 100644
index 00000000..ef87ab6d
--- /dev/null
+++ b/packages/docs/content/docs/uk/walkthrough.mdx
@@ -0,0 +1,63 @@
+---
+title: Розбір змін
+description: Читайте diff у порядку, який має сенс, а не в алфавітному.
+---
+
+# Розбір змін
+
+Diff упорядкований за шляхами файлів, а це майже ніколи не той порядок, у якому зміна стає зрозумілою. Розбір перебудовує його: пов'язані правки збираються в **кроки**, кожен крок пояснює, що саме код тепер робить інакше, а самі кроки йдуть так, щоб кожен спирався на попередній.
+
+Він пояснює й упорядковує. Він не оцінює ваш код і не виносить вердиктів — для цього є [Review](/git/).
+
+Відкрийте його іконкою **Розбір** у правому рейлі або кнопкою **AI-розбір** у панелях змін і pull request. Обидві лише відкривають панель; нічого не генерується, доки ви не натиснете **Створити розбір**.
+
+## Що можна розібрати
+
+| Область | Що охоплює |
+| --- | --- |
+| Усе незакомічене | Усе, що ще не в комітах: індекс, робоче дерево й нові файли |
+| В індексі | Лише те, що зараз пішло б у коміт |
+| Поза індексом | Робоче дерево й нові файли |
+| Ця гілка | Усі коміти гілки, яких немає в базовій |
+| Pull request | Зміна в тому вигляді, у якому вона є на GitHub |
+
+**Ця гілка** — це не «незапушені коміти», а все, що гілка додає до базової, незалежно від пушу. Тому після коміту, але до пушу, вона й pull request навмисно розходяться: одне показує, що ви зробили, друге — що зараз бачать рецензенти.
+
+Кожна область зберігається окремо, тож перемикання між ними нічого не втрачає.
+
+## Вибір моделі
+
+За замовчуванням розбір використовує вашу small model. Іншу можна обрати в **Налаштування → Сесії → Модель для розбору змін** або для одного разу в шапці панелі — корисно, коли зміна достатньо ризикована, щоб віддати її сильнішій моделі.
+
+У списку показані лише моделі, які вміють structured output, бо без нього розбір неможливо зібрати. Якщо модель замала для цього diff, генерація відхиляється з поясненням, а не обрізає вхід мовчки: розбір, написаний за половиною diff, звучить упевнено й при цьому помиляється.
+
+Відкривши панель знову, ви побачите модель, яка створила те, що перед вами, тож **Створити заново** повторить тією самою, доки ви її не зміните.
+
+## Витрати й кеш
+
+Ніщо не генерується саме. Генерація починається лише на ваш запит, і повторна теж робиться вручну.
+
+Результати кешуються за точним вмістом diff. Поверніть робоче дерево до попереднього стану — і попередній розбір повернеться безкоштовно, без звернення до моделі. Перемкніть модель і назад — розбір кожної з них лишиться на місці.
+
+Генерація виконується на сервері OpenChamber, а не у вкладці браузера. Перезавантажте сторінку чи закрийте панель — робота триває, а результат чекатиме на вас. Зупиняє її лише кнопка **Скасувати**.
+
+## Чесність щодо застарілого
+
+Кожен крок прив'язаний до точного вмісту коду, який він описує, тож панель може сказати, коли той код змінився:
+
+- **Застарілі кроки** — код, який описував крок, змінився або зник. Розбір усе одно показується, з позначкою, щоб ви самі вирішили, чи перегенеровувати.
+- **Не описано** — зміни в поточному diff, яких не описує жоден крок. Сюди потрапляють правки, зроблені після генерації, зміни, які розбір визнав рутинними, а також lock-файли й інші згенеровані файли, які свідомо не потрапляють до моделі. Усе це перелічено в кінці, щоб нічого не зникло непомітно.
+
+Повторна генерація не латає, а переписує: попередній розбір іде в модель як контекст, тому точні частини зберігаються, а прив'язки заново перераховуються під поточний код.
+
+## Примітки
+
+- Коментувати можна будь-який рядок, так само як у вигляді diff; коментарі чіпляються до поля вводу в чаті.
+- Доступно на десктопі та планшетних ширинах. У розширенні для VS Code і в мобільному застосунку не пропонується.
+- Для розбору pull request потрібен під'єднаний акаунт GitHub — див. [Issues та PR на GitHub](/github/).
+
+## Пов'язане
+
+- [Git і GitHub](/git/) — панель змін, з якої це читається, і дія Review, яка таки оцінює код
+- [Issues та PR на GitHub](/github/) — під'єднайте GitHub, щоб розбирати pull request
+- [Провайдери, моделі та агенти](/providers/) — звідки береться small model
diff --git a/packages/docs/content/docs/walkthrough.mdx b/packages/docs/content/docs/walkthrough.mdx
new file mode 100644
index 00000000..f4b54a31
--- /dev/null
+++ b/packages/docs/content/docs/walkthrough.mdx
@@ -0,0 +1,63 @@
+---
+title: Changes Walkthrough
+description: Read a diff in the order it makes sense, not in alphabetical order.
+---
+
+# Changes Walkthrough
+
+A diff is sorted by file path, which is almost never the order in which the change makes sense. The walkthrough reorders it: related edits are grouped into **stops**, each stop explains what the code now does differently, and the stops are ordered so each one builds on the last.
+
+It explains and orders. It does not judge your code or hand out verdicts — that is what [Review](/git/) is for.
+
+Open it from the **Walkthrough** icon in the right rail, or from the **AI walkthrough** button in the Changes and Pull Request panels. Both just open the panel; nothing is generated until you press **Generate walkthrough**.
+
+## What it can review
+
+| Scope | What it covers |
+| --- | --- |
+| All uncommitted | Everything not yet committed: staged, unstaged, and new files |
+| Staged | Only what would go into a commit right now |
+| Unstaged | Working tree and new files |
+| This branch | Every commit on this branch that is not on its base |
+| Pull request | The change as it exists on GitHub |
+
+**This branch** is not "unpushed commits" — it is everything the branch adds to its base, pushed or not. So after committing but before pushing, it and the pull request deliberately differ: one shows what you did, the other what reviewers currently see.
+
+Each scope is stored separately, so switching between them never loses anything.
+
+## Choosing the model
+
+Walkthroughs use your small model by default. Pick a different one in **Settings → Sessions → Changes Walkthrough Model**, or for a single review in the panel header — useful when a change is risky enough to deserve a stronger model.
+
+The picker only offers models that can return structured output, because the walkthrough cannot be assembled without it. If a model is too small for the diff, generation is refused with an explanation rather than silently truncating the input: a walkthrough written against half a diff reads as confident and is wrong.
+
+Reopening a panel shows the model that produced what you are looking at, so **Regenerate** repeats with the same one unless you change it.
+
+## Cost and caching
+
+Nothing generates on its own. Generation only ever starts when you ask, and regeneration is manual too.
+
+Results are cached against the exact content of the diff. Return the working tree to an earlier state and the earlier walkthrough comes back for free, no model call. Switch models and back, and each one's walkthrough is still there.
+
+Generation runs on the OpenChamber server, not in your browser tab. Reload the page or close the panel and it keeps going; come back and the result is waiting. Pressing **Cancel** is the only thing that stops it.
+
+## Staying honest about staleness
+
+Every stop is anchored to the exact content of the code it describes, so the panel can tell you when that code has moved on:
+
+- **Outdated steps** — the code a stop described has changed or is gone. The walkthrough still shows, marked, so you can decide whether to regenerate.
+- **Not covered** — changes in the current diff that no stop describes. That includes edits made after generating, changes the walkthrough judged routine, and lockfiles and other generated files, which are deliberately kept out of the model's input. They are all listed at the end of the stream so nothing disappears silently.
+
+Regenerating re-authors rather than patches: the previous walkthrough goes to the model as context so accurate parts survive, and everything is re-anchored to the current code.
+
+## Notes
+
+- Comment on any line in the walkthrough exactly as in the diff view; comments attach to the chat composer.
+- Available on desktop and tablet widths. Not offered in the VS Code extension or the mobile app.
+- A pull request review needs a connected GitHub account — see [GitHub Issues & PRs](/github/).
+
+## Related
+
+- [Git & GitHub](/git/) — the Changes panel this reads from, and the Review action that does judge code
+- [GitHub Issues & PRs](/github/) — connect GitHub to review pull requests
+- [Providers, Models & Agents](/providers/) — where the small model comes from
diff --git a/packages/docs/content/docs/zh-cn/walkthrough.mdx b/packages/docs/content/docs/zh-cn/walkthrough.mdx
new file mode 100644
index 00000000..99171d37
--- /dev/null
+++ b/packages/docs/content/docs/zh-cn/walkthrough.mdx
@@ -0,0 +1,63 @@
+---
+title: 改动导读
+description: 按讲得通的顺序读差异，而不是按字母顺序。
+---
+
+# 改动导读
+
+差异按文件路径排序，而这几乎从来不是让改动讲得通的顺序。导读会重新编排：相关的修改被归入一个个**步骤**，每个步骤说明代码现在有什么不同的行为，步骤的先后顺序保证后一步建立在前一步之上。
+
+它负责解释和排序，不评判你的代码，也不给结论——那是 [Review](/git/) 的职责。
+
+从右侧栏的**导读**图标打开，或在改动面板和拉取请求面板中点击 **AI 导读**按钮。两者都只是打开面板；在你按下**生成导读**之前不会生成任何内容。
+
+## 可以导读的范围
+
+| 范围 | 包含内容 |
+| --- | --- |
+| 全部未提交 | 尚未进入提交的一切：已暂存、未暂存和新文件 |
+| 已暂存 | 只包含此刻提交会带上的内容 |
+| 未暂存 | 工作区和新文件 |
+| 当前分支 | 该分支上基线分支所没有的全部提交 |
+| 拉取请求 | GitHub 上现有形态的改动 |
+
+**当前分支**不是“未推送的提交”，而是该分支相对基线新增的全部内容，无论是否推送。因此在提交之后、推送之前，它和拉取请求会有意不同：一个显示你做了什么，另一个显示评审者当前看到什么。
+
+各个范围分别保存，来回切换不会丢失任何内容。
+
+## 选择模型
+
+导读默认使用你的小模型。可在**设置 → 会话 → 改动导读模型**中更换，或只为这一次在面板标题栏中选择——当改动的风险足以交给更强的模型时很有用。
+
+选择列表只提供能返回结构化输出的模型，因为没有它就无法组装导读。如果模型对这份差异来说太小，生成会带着说明被拒绝，而不是悄悄截断输入：只看了半份差异写出的导读听起来笃定，实际却是错的。
+
+重新打开面板时会显示生成当前内容的那个模型，所以只要你不更换，**重新生成**就会沿用它。
+
+## 开销与缓存
+
+不会自行生成。生成只在你请求时开始，重新生成同样需要手动触发。
+
+结果按差异的确切内容缓存。把工作区恢复到先前状态，当时的导读就会免费回来，不会调用模型。切换模型再切回来，各自的导读都还在。
+
+生成运行在 OpenChamber 服务器上，而不是浏览器标签页里。刷新页面或关闭面板，工作仍在继续；回来时结果已在等你。只有**取消**能停止它。
+
+## 对过时保持诚实
+
+每个步骤都锚定在它所描述代码的确切内容上，因此面板能告诉你那段代码何时发生了变化：
+
+- **过时的步骤**——步骤所描述的代码已改变或不存在。导读仍会显示并加以标记，由你决定是否重新生成。
+- **未涵盖**——当前差异中没有任何步骤描述的改动。其中包括生成之后所做的修改、导读判定为常规的改动，以及锁文件等特意不送入模型的生成产物。它们都列在末尾，不会有内容悄无声息地消失。
+
+重新生成不是打补丁，而是重写：上一版导读会作为上下文交给模型，仍然成立的部分得以保留，整体则重新锚定到当前代码。
+
+## 说明
+
+- 可以像在差异视图中一样对任意行发表评论，评论会附加到聊天输入框。
+- 在桌面和平板宽度下可用。VS Code 扩展和移动应用中不提供。
+- 导读拉取请求需要已连接的 GitHub 账户，参见 [GitHub Issue 与 PR](/github/)。
+
+## 相关
+
+- [Git 与 GitHub](/git/)——它读取的改动面板，以及确实会评判代码的 Review 操作
+- [GitHub Issue 与 PR](/github/)——连接 GitHub 以导读拉取请求
+- [提供方、模型与代理](/providers/)——小模型从何而来
diff --git a/packages/docs/sidebar.config.json b/packages/docs/sidebar.config.json
index a364bf71..22d8183d 100644
--- a/packages/docs/sidebar.config.json
+++ b/packages/docs/sidebar.config.json
@@ -240,6 +240,20 @@
"ja": "Git と GitHub"
}
},
+ {
+ "label": "Changes Walkthrough",
+ "link": "/walkthrough/",
+ "translations": {
+ "uk": "Розбір змін",
+ "zh-CN": "改动导读",
+ "es": "Recorrido por los cambios",
+ "pt-BR": "Percurso pelas mudanças",
+ "ko": "변경 워크스루",
+ "pl": "Przewodnik po zmianach",
+ "fr": "Parcours des modifications",
+ "ja": "変更のウォークスルー"
+ }
+ },
{
"label": "GitHub Issues & PRs",
"link": "/github/",
diff --git a/packages/ui/src/components/icon/sprite.ts b/packages/ui/src/components/icon/sprite.ts
index 8ecfbf11..a5d2dd76 100644
--- a/packages/ui/src/components/icon/sprite.ts
+++ b/packages/ui/src/components/icon/sprite.ts
@@ -192,6 +192,7 @@ export const iconSpriteData = {
"robot": ``,
"robot-2": ``,
"rocket": ``,
+ "route": ``,
"save-3": ``,
"scales-3": ``,
"scan-2": ``,
diff --git a/packages/ui/src/components/layout/ContextPanel.tsx b/packages/ui/src/components/layout/ContextPanel.tsx
index 3cc8e813..574f8591 100644
--- a/packages/ui/src/components/layout/ContextPanel.tsx
+++ b/packages/ui/src/components/layout/ContextPanel.tsx
@@ -8,6 +8,7 @@ import { FilesView } from '@/components/views/FilesView';
import { GitView } from '@/components/views/GitView';
import { PullRequestView } from '@/components/views/PullRequestView';
import { TerminalView } from '@/components/views/TerminalView';
+import { WalkthroughView } from '@/components/views/walkthrough/WalkthroughView';
import { PlanView } from '@/components/views/PlanView';
import { ProjectContextPanel } from './RightSidebarTabs';
import { SidebarFilesTree } from './SidebarFilesTree';
@@ -158,6 +159,7 @@ const getModeLabel = (
if (mode === 'chat') return t('contextPanel.mode.chat');
if (mode === 'file') return t('contextPanel.mode.files');
if (mode === 'diff') return t('contextPanel.mode.diff');
+ if (mode === 'walkthrough') return t('contextPanel.mode.walkthrough');
if (mode === 'plan') return t('contextPanel.mode.plan');
if (mode === 'preview') return t('contextPanel.mode.preview');
if (mode === 'browser') return t('contextPanel.mode.browser');
@@ -247,6 +249,10 @@ const getTabIcon = (tab: { mode: ContextPanelMode; targetPath: string | null }):
return ;
}
+ if (tab.mode === 'walkthrough') {
+ return ;
+ }
+
if (tab.mode === 'git') {
return ;
}
@@ -2717,6 +2723,12 @@ export const ContextPanel: React.FC = () => {
() => tabs.some((tab) => tab.mode === 'terminal'),
[tabs],
);
+ // Keep-alive: the walkthrough holds reading progress and scroll position that
+ // a remount would silently throw away.
+ const hasWalkthroughTab = React.useMemo(
+ () => tabs.some((tab) => tab.mode === 'walkthrough'),
+ [tabs],
+ );
const BrowserPane = isElectronBrowserRuntime() ? DesktopBrowserPane : IframeBrowserPane;
const hasFileTabs = React.useMemo(
() => tabs.some((tab) => tab.mode === 'file'),
@@ -2979,7 +2991,12 @@ export const ContextPanel: React.FC = () => {
) : null}
- {activeTab?.mode !== 'chat' && !isFileTabActive && activeTab?.mode !== 'browser' && activeTab?.mode !== 'diff' && activeTab?.mode !== 'terminal' ? activeNonChatContent : null}
+ {hasWalkthroughTab ? (
+
+
+
+ ) : null}
+ {activeTab?.mode !== 'chat' && !isFileTabActive && activeTab?.mode !== 'browser' && activeTab?.mode !== 'diff' && activeTab?.mode !== 'terminal' && activeTab?.mode !== 'walkthrough' ? activeNonChatContent : null}
diff --git a/packages/ui/src/components/layout/ContextPanelRail.tsx b/packages/ui/src/components/layout/ContextPanelRail.tsx
index 12fcd12c..38ab1b64 100644
--- a/packages/ui/src/components/layout/ContextPanelRail.tsx
+++ b/packages/ui/src/components/layout/ContextPanelRail.tsx
@@ -19,6 +19,8 @@ import { CSS } from '@dnd-kit/utilities';
import { Icon } from '@/components/icon/Icon';
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
import { useEffectiveDirectory } from '@/hooks/useEffectiveDirectory';
+import { useDeviceInfo } from '@/lib/device';
+import { isVSCodeRuntime } from '@/lib/desktop';
import { useI18n } from '@/lib/i18n';
import {
sortContextSurfaces,
@@ -30,6 +32,9 @@ import { useGitStatus } from '@/stores/useGitStore';
import { normalizeContextPanelDirectoryKey, useUIStore } from '@/stores/useUIStore';
const RAIL_TOOLTIP_DELAY_MS = 150;
+// Tablet width and up: below this the walkthrough cannot show a stop and its
+// code side by side, which is the whole point of the surface.
+const WALKTHROUGH_MIN_WIDTH = 768;
const EMPTY_TABS: never[] = [];
type RailItemProps = {
@@ -105,6 +110,7 @@ export const ContextPanelRail: React.FC = () => {
const setContextRailOrder = useUIStore((state) => state.setContextRailOrder);
const openContextSurface = useUIStore((state) => state.openContextSurface);
const planModeEnabled = useFeatureFlagsStore((state) => state.planModeEnabled);
+ const { screenWidth } = useDeviceInfo();
const gitStatus = useGitStatus(directoryKey || null);
const sensors = useSensors(
@@ -124,12 +130,17 @@ export const ContextPanelRail: React.FC = () => {
if (surface.id === 'plan' && !planModeEnabled) {
return false;
}
+ // The walkthrough needs room for a stop list beside real code, and its
+ // diffs come from OpenChamber's Git routes, which VS Code does not serve.
+ if (surface.id === 'walkthrough' && (isVSCodeRuntime() || screenWidth < WALKTHROUGH_MIN_WIDTH)) {
+ return false;
+ }
if (surface.availability === 'has-content') {
return tabs.some((tab) => tab.mode === surface.mode);
}
return true;
});
- }, [contextRailOrder, planModeEnabled, tabs]);
+ }, [contextRailOrder, planModeEnabled, screenWidth, tabs]);
const handleDragEnd = React.useCallback((event: DragEndEvent) => {
const { active, over } = event;
diff --git a/packages/ui/src/components/model-picker/ModelPickerList.tsx b/packages/ui/src/components/model-picker/ModelPickerList.tsx
index 7d9314b2..f06dc190 100644
--- a/packages/ui/src/components/model-picker/ModelPickerList.tsx
+++ b/packages/ui/src/components/model-picker/ModelPickerList.tsx
@@ -339,6 +339,11 @@ interface ModelPickerListProps {
selectedModel?: { providerID: string; modelID: string } | null;
hiddenModels?: HiddenModel[];
allowedProviderIds?: string[];
+ /**
+ * Per-model gate, for callers whose feature needs a capability rather than a
+ * provider (e.g. structured output). Applied on top of `allowedProviderIds`.
+ */
+ isModelAllowed?: (providerID: string, modelID: string) => boolean;
includeNotSelected?: boolean;
onSelectNone?: () => void;
selectionCount?: (entry: ModelPickerEntry) => number;
@@ -379,6 +384,7 @@ export const ModelPickerList: React.FC = ({
selectedModel,
hiddenModels = [],
allowedProviderIds,
+ isModelAllowed,
includeNotSelected = false,
onSelectNone,
selectionCount,
@@ -448,17 +454,19 @@ export const ModelPickerList: React.FC = ({
const filteredFavorites = React.useMemo(() => favoriteModels.filter(({ model, providerID, modelID }) => {
if (allowedProviderSet && !allowedProviderSet.has(providerID)) return false;
+ if (isModelAllowed && !isModelAllowed(providerID, modelID)) return false;
if (isHidden(providerID, modelID)) return false;
const providerName = providerById.get(providerID)?.name || providerID;
return matchesQuery(getModelDisplayName(model), providerName);
- }), [allowedProviderSet, favoriteModels, isHidden, matchesQuery, providerById]);
+ }), [allowedProviderSet, favoriteModels, isHidden, isModelAllowed, matchesQuery, providerById]);
const filteredRecents = React.useMemo(() => recentModels.filter(({ model, providerID, modelID }) => {
if (allowedProviderSet && !allowedProviderSet.has(providerID)) return false;
+ if (isModelAllowed && !isModelAllowed(providerID, modelID)) return false;
if (isHidden(providerID, modelID)) return false;
const providerName = providerById.get(providerID)?.name || providerID;
return matchesQuery(getModelDisplayName(model), providerName);
- }), [allowedProviderSet, isHidden, matchesQuery, providerById, recentModels]);
+ }), [allowedProviderSet, isHidden, isModelAllowed, matchesQuery, providerById, recentModels]);
const orderedProviders = React.useMemo(() => {
if (!providerOrder || providerOrder.length === 0) return providers;
@@ -477,11 +485,12 @@ export const ModelPickerList: React.FC = ({
const filteredModels = models.filter((model) => {
const modelID = typeof model.id === 'string' ? model.id : '';
if (!modelID || isHidden(provider.id, modelID)) return false;
+ if (isModelAllowed && !isModelAllowed(provider.id, modelID)) return false;
return matchesQuery(getModelDisplayName(model), provider.name || provider.id);
});
return { ...provider, models: filteredModels };
})
- .filter((provider) => provider.models.length > 0), [allowedProviderSet, isHidden, matchesQuery, orderedProviders]);
+ .filter((provider) => provider.models.length > 0), [allowedProviderSet, isHidden, isModelAllowed, matchesQuery, orderedProviders]);
const flatModelList = React.useMemo(() => {
const items: ModelPickerEntry[] = [];
diff --git a/packages/ui/src/components/sections/agents/ModelSelector.tsx b/packages/ui/src/components/sections/agents/ModelSelector.tsx
index 7d8cea8e..0d3841fa 100644
--- a/packages/ui/src/components/sections/agents/ModelSelector.tsx
+++ b/packages/ui/src/components/sections/agents/ModelSelector.tsx
@@ -23,6 +23,7 @@ interface ModelSelectorProps {
onChange: (providerId: string, modelId: string) => void;
className?: string;
allowedProviderIds?: string[];
+ isModelAllowed?: (providerId: string, modelId: string) => boolean;
placeholder?: string;
tooltipsEnabled?: boolean;
dropdownPortalToBody?: boolean;
@@ -34,6 +35,7 @@ export const ModelSelector: React.FC = ({
onChange,
className,
allowedProviderIds,
+ isModelAllowed,
placeholder,
tooltipsEnabled = true,
dropdownPortalToBody = false,
@@ -115,6 +117,7 @@ export const ModelSelector: React.FC = ({
selectedModel={selectedModel}
hiddenModels={hiddenModels}
allowedProviderIds={allowedProviderIds}
+ isModelAllowed={isModelAllowed}
includeNotSelected
onSelectNone={handleSelectNone}
onEscape={closePicker}
diff --git a/packages/ui/src/components/sections/openchamber/DefaultsSettings.tsx b/packages/ui/src/components/sections/openchamber/DefaultsSettings.tsx
index 5018f63b..a3001a89 100644
--- a/packages/ui/src/components/sections/openchamber/DefaultsSettings.tsx
+++ b/packages/ui/src/components/sections/openchamber/DefaultsSettings.tsx
@@ -45,6 +45,7 @@ export const DefaultsSettings: React.FC = () => {
const showDeletionDialog = useUIStore((state) => state.showDeletionDialog);
const setShowDeletionDialog = useUIStore((state) => state.setShowDeletionDialog);
const providers = useConfigStore((state) => state.providers);
+ const modelsMetadata = useConfigStore((state) => state.modelsMetadata);
const [defaultModel, setDefaultModel] = React.useState();
const [defaultVariant, setDefaultVariant] = React.useState();
@@ -52,6 +53,7 @@ export const DefaultsSettings: React.FC = () => {
const [smallModelUseDefault, setSmallModelUseDefault] = React.useState(true);
const [smallModelOverride, setSmallModelOverride] = React.useState();
const [smallModelProviders, setSmallModelProviders] = React.useState();
+ const [walkthroughModelOverride, setWalkthroughModelOverride] = React.useState();
const [isLoading, setIsLoading] = React.useState(true);
const parsedModel = React.useMemo(() => getDisplayModel(defaultModel), [defaultModel]);
@@ -65,6 +67,7 @@ export const DefaultsSettings: React.FC = () => {
defaultAgent?: string;
smallModelUseDefault?: boolean;
smallModelOverride?: string;
+ walkthroughModelOverride?: string;
} | null = null;
if (!data) {
@@ -84,6 +87,8 @@ export const DefaultsSettings: React.FC = () => {
defaultAgent: typeof settings.defaultAgent === 'string' ? settings.defaultAgent : undefined,
smallModelUseDefault: typeof raw.smallModelUseDefault === 'boolean' ? raw.smallModelUseDefault : undefined,
smallModelOverride: typeof raw.smallModelOverride === 'string' ? raw.smallModelOverride : undefined,
+ walkthroughModelOverride:
+ typeof raw.walkthroughModelOverride === 'string' ? raw.walkthroughModelOverride : undefined,
};
}
} catch {
@@ -123,6 +128,9 @@ export const DefaultsSettings: React.FC = () => {
if (typeof data.smallModelOverride === 'string' && data.smallModelOverride.trim()) {
setSmallModelOverride(data.smallModelOverride.trim());
}
+ if (typeof data.walkthroughModelOverride === 'string' && data.walkthroughModelOverride.trim()) {
+ setWalkthroughModelOverride(data.walkthroughModelOverride.trim());
+ }
}
} catch (error) {
console.warn('Failed to load defaults settings:', error);
@@ -236,10 +244,43 @@ export const DefaultsSettings: React.FC = () => {
[]
);
+ const handleWalkthroughModelOverrideChange = React.useCallback(
+ async (providerId: string, modelId: string) => {
+ const newValue = providerId && modelId ? `${providerId}/${modelId}` : undefined;
+ setWalkthroughModelOverride(newValue);
+ try {
+ // Clearing the picker is how the user goes back to the small model, so
+ // an empty value is a real choice rather than a no-op.
+ await updateDesktopSettings({ walkthroughModelOverride: newValue ?? '' });
+ } catch (error) {
+ console.warn('Failed to save walkthrough model override:', error);
+ }
+ },
+ []
+ );
+
+ // The walkthrough cannot work at all without schema-shaped output, so models
+ // the catalog says cannot do it are hidden rather than offered and then
+ // refused. A missing capability is not a "no": roughly half the catalog omits
+ // the field, and those models usually work.
+ const isStructuredOutputCapable = React.useCallback(
+ (providerId: string, modelId: string) =>
+ modelsMetadata.get(`${providerId}/${modelId}`)?.structured_output !== false,
+ [modelsMetadata]
+ );
+
const parsedSmallModel = React.useMemo(() => getDisplayModel(smallModelOverride), [smallModelOverride]);
+ const parsedWalkthroughModel = React.useMemo(
+ () => getDisplayModel(walkthroughModelOverride),
+ [walkthroughModelOverride]
+ );
React.useEffect(() => {
- if (smallModelUseDefault || smallModelProviders !== undefined) return;
+ // Both pickers filter by the same authenticated-provider list, so either
+ // one being open is reason enough to fetch it.
+ // Both pickers filter by the same authenticated-provider list, and the
+ // walkthrough picker is always visible, so this is always worth fetching.
+ if (smallModelProviders !== undefined) return;
let cancelled = false;
(async () => {
try {
@@ -256,7 +297,7 @@ export const DefaultsSettings: React.FC = () => {
return () => {
cancelled = true;
};
- }, [smallModelUseDefault, smallModelProviders]);
+ }, [smallModelProviders]);
const availableVariants = React.useMemo(() => {
if (!parsedModel.providerId || !parsedModel.modelId) return [];
@@ -396,6 +437,32 @@ export const DefaultsSettings: React.FC = () => {
/>
) : null}
+
+
+