specrails-desktop 2.36.0 → 2.42.2

package/docs/guide/es/integrations/5-mcp-server.md

@@ -4,20 +4,20 @@ Specrails puede exponerse **a sí mismo** a cualquier asistente de IA que hable
 
 Esta es la dirección opuesta a las funciones de plugins y "Mis MCPs aprobados": esas dejan que Specrails *use* otros servidores MCP; esta deja que otras apps usen **Specrails**.
 
-## Cómo activarlo
+## Viene activado de serie
 
-Está **desactivado por defecto**. Abre **Configuración ▸ MCP** y activa **Habilitar MCP**. Eso es todo — el servidor arranca de inmediato, sin reiniciar.
+Está **activado por defecto**: el servidor ya está en marcha la primera vez que abres la app, sin reiniciar ni tocar nada. Abre **Configuración ▸ MCP** para copiar la configuración de cliente, o para desactivarlo si no lo quieres.
 
 Tú mantienes el control de *qué* puede hacer una IA externa mediante un conjunto de niveles de permiso:
 
 | Nivel | Qué permite | Por defecto |
 |---|---|---|
 | **Lectura** | Listar e inspeccionar proyectos, specs, trabajos, analíticas… | Siempre activo (cuando MCP está habilitado) |
-| **Escritura** | Crear y editar specs, cambiar la configuración y la config de los rails | Desactivado — actívalo tú |
-| **Lanzar IA** | Acciones que ejecutan una IA y **cuestan dinero** (lanzar un rail, generar una spec, enviar un turno de chat) | Desactivado — actívalo tú |
-| **Destructivo** | Borrar proyectos/specs/trabajos, detener trabajo en curso | Desactivado — actívalo tú |
+| **Escritura** | Crear y editar specs, cambiar la configuración y la config de los rails | Activado — desmárcalo para restringir |
+| **Lanzar IA** | Acciones que ejecutan una IA y **cuestan dinero** (lanzar un rail, generar una spec, enviar un turno de chat) | Activado — desmárcalo para restringir |
+| **Destructivo** | Borrar proyectos/specs/trabajos, detener trabajo en curso | Activado — desmárcalo para restringir |
 
-Si tu asistente intenta algo que cubre un nivel desactivado, Specrails lo rechaza con un mensaje claro que te indica qué nivel activar. Así puedes empezar en modo solo lectura y abrir exactamente lo que necesites.
+Los cuatro niveles vienen concedidos de serie, así que un asistente conectado puede manejar toda la app desde el primer momento. Desmarca cualquier nivel que prefieras reservarte; si después tu asistente intenta algo que cubre ese nivel, Specrails lo rechaza con un mensaje claro que te indica qué nivel volver a activar.
 
 ## Conectar tu asistente
 
@@ -50,11 +50,15 @@ codex mcp add specrails -- <comando del bridge de Ajustes ▸ MCP>
 
 La cabecera `Authorization: Bearer <token>` también funciona. Si cambiaste el puerto de la app, sustituye `4200` por el tuyo.
 
-Una vez conectado, tu asistente ve unas **18 herramientas** que cubren toda la app — proyectos, specs, rails y trabajos, chat/Explore, agentes, plugins, Jira, loops, el explorador de código, analíticas, configuración — más una herramienta de **guía** incorporada que lee primero para entender cómo funciona Specrails sin que tú tengas que explicar nada.
+Una vez conectado, tu asistente ve **22 herramientas** que cubren toda la app — proyectos, specs, rails y trabajos, chat/Explore, agentes, plugins, Jira, loops, el explorador de código, analíticas, configuración — incluida una herramienta de **guía** incorporada que lee primero para entender cómo funciona Specrails sin que tú tengas que explicar nada.
+
+Antes de actuar, el asistente puede usar `specrails_context` para consultar el estado actual del proyecto, las specs, las ejecuciones y Git. Las secciones no disponibles se indican expresamente; no significan que el proyecto esté vacío. `specrails_code(search)` busca texto en el código y `read_file` lee rangos concretos de líneas, indicando cómo continuar cuando queda contenido.
+
+Cada sesión MCP externa conserva su propia selección de proyecto. En modo Misión, el proyecto predeterminado es el fijado en la conversación, que cambias desde la interfaz de misión; una selección MCP no puede sustituirlo. Un `projectId` explícito permite dirigir una operación intencionadamente a otro proyecto.
 
 ## Qué puedes hacer con él
 
-Unas cuantas recetas una vez que tu asistente está conectado. Empieza con **Lectura** activado y, cuando quieras que de verdad cree y lance trabajo, activa **Escritura** y **Lanzar IA**.
+Unas cuantas recetas una vez que tu asistente está conectado. Todo viene activado por defecto; desmarca **Escritura** o **Lanzar IA** en Configuración ▸ MCP si por ahora prefieres que solo observe.
 
 **Convierte en specs el trabajo de tus otras herramientas.** Si tu asistente también tiene conectados GitHub, Jira, Gmail o Slack, puede traerte el trabajo a Specrails:
 > *"Coge las incidencias abiertas de GitHub de esta semana con la etiqueta 'bug', crea una spec para cada una en el proyecto de la API y lánzalas."*
@@ -64,7 +68,7 @@ Unas cuantas recetas una vez que tu asistente está conectado. Empieza con **Lec
 **Piloto automático nocturno.** Déjalo en marcha con la app en la bandeja y vuelve a un informe:
 > *"Aquí tienes 12 ideas. Convierte cada una en una spec, lánzalas de tres en tres por los rails, vigila cada trabajo y mañana dame un resumen de lo que terminó, lo que falló y lo que costó."*
 
-Mantén **Destructivo** desactivado y podrá trabajar toda la noche sin borrar nada nunca.
+Desmarca **Destructivo** y podrá trabajar toda la noche sin borrar nada nunca.
 
 **En todos tus proyectos.** Algo que el panel no hace por sí solo:
 > *"Revisa todos mis proyectos. Dime cuáles tienen specs en el backlog y ningún rail en marcha, y arranca el de mayor prioridad en cada uno."*

package/docs/guide/es/integrations/6-agent-chat.md

@@ -68,6 +68,7 @@ Las respuestas llegan fluidas y ya formateadas (encabezados, tablas, listas), ca
 - **Minimiza sin perder nada.** Haz clic en la ✕ para devolver el panel a la burbuja: la conversación sigue en marcha. Vuelve a abrirlo y aterrizas en el último mensaje; no hay que reescribir nada.
 - **Nueva conversación.** El botón **+** inicia un hilo limpio; el historial vive a nivel de app, por encima de cualquier proyecto concreto.
 - **Cambia de misión.** El selector de misiones junto al selector de proyecto lista tus conversaciones de más reciente a más antigua — un punto pulsante marca aquellas donde el agente sigue trabajando, y una pequeña insignia cuenta los mensajes en cola. La búsqueda aparece cuando la lista supera las ocho, y el icono de papelera de cada fila elimina una misión tras una confirmación rápida en línea — incluso una en marcha (avisa primero y luego detiene al agente).
+- **Encuentra una misión desde cualquier sitio.** Pulsa **⌘K** (o el botón **Buscar** del sidebar en modo Agente) y escribe cualquier fragmento que recuerdes: una palabra del título *o* de lo que se dijo dentro. Las misiones coinciden al instante por título desde memoria y, un latido después, llegan las coincidencias por contenido con el pasaje resaltado, más el proyecto anclado y cuándo tuvo actividad por última vez. En modo Agente las misiones son el primer grupo; en el tablero van justo después de Proyectos. Enter abre la misión.
 
 ## Algunas cosas que conviene saber
 

package/docs/guide/fr/integrations/5-mcp-server.md

@@ -4,20 +4,20 @@ Specrails peut s'exposer **lui-même** à n'importe quel assistant IA qui parle
 
 C'est la direction inverse des fonctionnalités plugins et « Mes MCP approuvés » : celles-ci permettent à Specrails d'*utiliser* d'autres serveurs MCP ; ceci permet à d'autres apps d'utiliser **Specrails**.
 
-## L'activer
+## Activé d'emblée
 
-C'est **désactivé par défaut**. Ouvrez **Paramètres ▸ MCP** et basculez **Activer MCP**. C'est tout — le serveur démarre immédiatement, sans redémarrage.
+C'est **activé par défaut** : le serveur tourne déjà dès la première ouverture de l'app, sans redémarrage ni rien à basculer. Ouvrez **Paramètres ▸ MCP** pour copier la configuration client, ou pour le désactiver si vous n'en voulez pas.
 
 Vous gardez le contrôle de *ce qu'*une IA externe peut faire grâce à un ensemble de niveaux de permission :
 
 | Niveau | Ce qu'il autorise | Par défaut |
 |---|---|---|
 | **Lecture** | Lister et inspecter les projets, specs, jobs, analyses… | Toujours actif (lorsque MCP est activé) |
-| **Écriture** | Créer et modifier des specs, changer les paramètres et la configuration des rails | Désactivé — à activer |
-| **Lancement d'IA** | Actions qui exécutent une IA et **coûtent de l'argent** (lancer un rail, générer une spec, envoyer un tour de chat) | Désactivé — à activer |
-| **Destructif** | Supprimer des projets/specs/jobs, arrêter un travail en cours | Désactivé — à activer |
+| **Écriture** | Créer et modifier des specs, changer les paramètres et la configuration des rails | Activé — décochez pour restreindre |
+| **Lancement d'IA** | Actions qui exécutent une IA et **coûtent de l'argent** (lancer un rail, générer une spec, envoyer un tour de chat) | Activé — décochez pour restreindre |
+| **Destructif** | Supprimer des projets/specs/jobs, arrêter un travail en cours | Activé — décochez pour restreindre |
 
-Si votre assistant tente quelque chose que couvre un niveau désactivé, Specrails refuse avec un message clair vous indiquant quel niveau activer. Vous pouvez donc commencer en lecture seule et ouvrir exactement ce dont vous avez besoin.
+Les quatre niveaux sont accordés d'emblée : un assistant connecté peut piloter toute l'app immédiatement. Décochez tout niveau que vous préférez garder pour vous ; si votre assistant tente ensuite quelque chose que ce niveau couvre, Specrails refuse avec un message clair vous indiquant quel niveau réactiver.
 
 ## Connecter votre assistant
 
@@ -50,11 +50,15 @@ codex mcp add specrails -- <commande du bridge depuis Réglages ▸ MCP>
 
 L'en-tête `Authorization: Bearer <token>` fonctionne aussi. Si vous avez changé le port de l'app, remplacez `4200`.
 
-Une fois connecté, votre assistant voit environ **18 outils** couvrant toute l'app — projets, specs, rails et jobs, chat/Explore, agents, plugins, Jira, loops, l'explorateur de code, les analyses, les paramètres — plus un outil **guide** intégré qu'il lit en premier afin de comprendre le fonctionnement de Specrails sans que vous ayez à expliquer quoi que ce soit.
+Une fois connecté, votre assistant voit **22 outils** couvrant toute l'app — projets, specs, rails et jobs, chat/Explore, agents, plugins, Jira, loops, l'explorateur de code, les analyses, les paramètres — dont un outil **guide** intégré qu'il lit en premier afin de comprendre le fonctionnement de Specrails sans que vous ayez à expliquer quoi que ce soit.
+
+Avant d'agir, l'assistant peut utiliser `specrails_context` pour consulter l'état actuel du projet, des specs, des exécutions et de Git. Les sections indisponibles sont signalées explicitement ; elles ne signifient pas que le projet est vide. `specrails_code(search)` recherche du texte dans le code source, et `read_file` lit des plages de lignes précises en indiquant comment poursuivre lorsqu'il reste du contenu.
+
+Chaque session MCP externe conserve sa propre sélection de projet. En mode Mission, le projet par défaut est celui épinglé à la conversation, que vous modifiez dans l'interface de mission ; une sélection MCP ne peut pas le remplacer. Un `projectId` explicite permet de cibler volontairement une opération dans un autre projet.
 
 ## Ce que vous pouvez en faire
 
-Quelques recettes une fois votre assistant connecté. Commencez avec **Lecture** activée, puis activez **Écriture** et **Lancement d'IA** quand vous voulez qu'il crée et lance réellement du travail.
+Quelques recettes une fois votre assistant connecté. Tout est activé par défaut ; décochez **Écriture** ou **Lancement d'IA** dans Paramètres ▸ MCP si vous préférez qu'il se contente d'observer pour l'instant.
 
 **Transformez le travail de vos autres outils en specs.** Si votre assistant a aussi GitHub, Jira, Gmail ou Slack connectés, il peut amener le travail jusqu'à Specrails pour vous :
 > *« Prends les issues GitHub ouvertes cette semaine étiquetées "bug", crée une spec pour chacune dans le projet API, et lance-les. »*
@@ -64,7 +68,7 @@ Quelques recettes une fois votre assistant connecté. Commencez avec **Lecture**
 **Pilote automatique nocturne.** Laissez-le tourner avec l'app dans la zone de notification et revenez à un rapport :
 > *« Voici 12 idées. Transforme chacune en une spec, lance-les trois par trois à travers les rails, surveille chaque job, et demain donne-moi un résumé de ce qui s'est terminé, ce qui a échoué et ce que ça a coûté. »*
 
-Gardez **Destructif** désactivé et il peut construire toute la nuit sans jamais rien supprimer.
+Décochez **Destructif** et il peut construire toute la nuit sans jamais rien supprimer.
 
 **À travers tous vos projets.** Quelque chose que le tableau de bord ne fait pas tout seul :
 > *« Vérifie tous mes projets. Dis-moi lesquels ont des specs dans le backlog sans aucun rail en cours, et démarre la plus prioritaire dans chacun. »*

package/docs/guide/fr/integrations/6-agent-chat.md

@@ -68,6 +68,7 @@ Les réponses arrivent en flux fluide et s'affichent déjà mises en forme (titr
 - **Réduire sans rien perdre.** Cliquez sur la ✕ pour renvoyer le panneau dans la bulle — la conversation continue de tourner. Rouvrez-le et vous atterrissez sur le dernier message ; rien n'est à retaper.
 - **Nouvelle conversation.** Le bouton **+** démarre un fil vierge ; l'historique vit au niveau de l'application, au-dessus de tout projet individuel.
 - **Changez de mission.** Le sélecteur de missions, à côté du sélecteur de projet, liste vos conversations de la plus récente à la plus ancienne — un point clignotant signale celles où l'agent travaille encore, et un petit badge compte les messages en file. La recherche apparaît dès que la liste dépasse huit entrées, et l'icône corbeille de chaque ligne supprime une mission après une confirmation rapide en ligne — même une mission en cours (elle prévient d'abord, puis arrête l'agent).
+- **Retrouvez une mission de n'importe où.** Appuyez sur **⌘K** (ou le bouton **Rechercher** de la barre latérale en mode Agent) et tapez n'importe quel fragment dont vous vous souvenez — un mot du titre *ou* de ce qui a été dit dedans. Les missions correspondent instantanément par titre depuis la mémoire, puis un instant plus tard arrivent les correspondances par contenu avec le passage surligné, le projet épinglé et la date de dernière activité. En mode Agent, les missions forment le premier groupe ; sur le tableau, elles suivent les Projets. Entrée ouvre la mission.
 
 ## Quelques points à savoir
 

package/docs/guide/it/integrations/5-mcp-server.md

@@ -4,20 +4,20 @@ Specrails può esporre **se stesso** a qualsiasi assistente AI che parli il [Mod
 
 Questa è la direzione opposta rispetto alle funzionalità dei plugin e degli "MCP approvati da me": quelle permettono a Specrails di *usare* altri server MCP; questa permette ad altre app di usare **Specrails**.
 
-## Come attivarlo
+## Attivo fin da subito
 
-È **disattivato di default**. Apri **Impostazioni ▸ MCP** e attiva **Abilita MCP**. Fatto — il server si avvia immediatamente, senza riavvii.
+È **attivo di default** — il server è già in esecuzione la prima volta che apri l'app, senza riavvii e senza toccare nulla. Apri **Impostazioni ▸ MCP** per copiare la configurazione client, o per disattivarlo se non lo vuoi.
 
 Resti tu a controllare *cosa* può fare un'AI esterna tramite una serie di livelli di permesso:
 
 | Livello | Cosa consente | Default |
 |---|---|---|
 | **Lettura** | Elencare e ispezionare progetti, spec, job, analisi… | Sempre attivo (quando l'MCP è abilitato) |
-| **Scrittura** | Creare e modificare spec, cambiare impostazioni e configurazione dei rail | Disattivato — da abilitare |
-| **AI-spawn** | Azioni che eseguono un'AI e **costano denaro** (lanciare un rail, generare una spec, inviare un turno di chat) | Disattivato — da abilitare |
-| **Distruttivo** | Eliminare progetti/spec/job, fermare il lavoro in corso | Disattivato — da abilitare |
+| **Scrittura** | Creare e modificare spec, cambiare impostazioni e configurazione dei rail | Attivo — deseleziona per limitare |
+| **AI-spawn** | Azioni che eseguono un'AI e **costano denaro** (lanciare un rail, generare una spec, inviare un turno di chat) | Attivo — deseleziona per limitare |
+| **Distruttivo** | Eliminare progetti/spec/job, fermare il lavoro in corso | Attivo — deseleziona per limitare |
 
-Se il tuo assistente prova a fare qualcosa coperto da un livello disattivato, Specrails rifiuta con un messaggio chiaro che ti indica quale livello attivare. Così puoi partire in sola lettura e aprire esattamente ciò che ti serve.
+Tutti e quattro i livelli sono concessi fin da subito, quindi un assistente collegato può guidare l'intera app da subito. Deseleziona qualsiasi livello che preferisci tenere per te; se poi il tuo assistente prova a fare qualcosa coperto da quel livello, Specrails rifiuta con un messaggio chiaro che ti indica quale livello riattivare.
 
 ## Collegare il tuo assistente
 
@@ -50,11 +50,15 @@ codex mcp add specrails -- <comando bridge da Impostazioni ▸ MCP>
 
 Funziona anche l'header `Authorization: Bearer <token>`. Se hai cambiato la porta dell'app, sostituisci `4200`.
 
-Una volta collegato, il tuo assistente vede circa **18 strumenti** che coprono l'intera app — progetti, spec, rail e job, chat/Explore, agenti, plugin, Jira, loop, l'esploratore del codice, le analisi, le impostazioni — più uno strumento **guida** integrato che legge per primo, così capisce come funziona Specrails senza che tu debba spiegargli nulla.
+Una volta collegato, il tuo assistente vede **22 strumenti** che coprono l'intera app — progetti, spec, rail e job, chat/Explore, agenti, plugin, Jira, loop, l'esploratore del codice, le analisi, le impostazioni — incluso uno strumento **guida** integrato che legge per primo, così capisce come funziona Specrails senza che tu debba spiegargli nulla.
+
+Prima di agire, l'assistente può usare `specrails_context` per consultare lo stato attuale del progetto, delle spec, delle esecuzioni e di Git. Le sezioni non disponibili vengono indicate esplicitamente; non significano che il progetto sia vuoto. `specrails_code(search)` cerca testo nel codice sorgente e `read_file` legge intervalli precisi di righe, indicando come continuare quando resta altro contenuto.
+
+Ogni sessione MCP esterna mantiene la propria selezione del progetto. In modalità Missione, il progetto predefinito è quello fissato alla conversazione, che modifichi nell'interfaccia della missione; una selezione MCP non può sostituirlo. Un `projectId` esplicito permette di indirizzare intenzionalmente un'operazione a un altro progetto.
 
 ## Cosa puoi farci
 
-Qualche ricetta una volta collegato il tuo assistente. Parti con la **Lettura** attiva, poi accendi **Scrittura** e **AI-spawn** quando vuoi che crei e lanci davvero il lavoro.
+Qualche ricetta una volta collegato il tuo assistente. È tutto attivo di default; deseleziona **Scrittura** o **AI-spawn** in Impostazioni ▸ MCP se per ora preferisci che si limiti a osservare.
 
 **Trasforma il lavoro degli altri tuoi strumenti in spec.** Se il tuo assistente ha collegati anche GitHub, Jira, Gmail o Slack, può portare il lavoro dentro Specrails al posto tuo:
 > *"Prendi le issue GitHub aperte di questa settimana con etichetta 'bug', crea una spec per ognuna nel progetto API e lanciale."*
@@ -64,7 +68,7 @@ Qualche ricetta una volta collegato il tuo assistente. Parti con la **Lettura**
 **Pilota automatico notturno.** Lascialo in esecuzione con l'app nella barra di sistema e torna a un resoconto:
 > *"Ecco 12 idee. Trasforma ognuna in una spec, lanciale tre alla volta sui rail, tieni d'occhio ogni job e domani dammi un riepilogo di cosa è finito, cosa è fallito e quanto è costato."*
 
-Tieni **Distruttivo** disattivato e potrà lavorare tutta la notte senza mai eliminare nulla.
+Deseleziona **Distruttivo** e potrà lavorare tutta la notte senza mai eliminare nulla.
 
 **Su tutti i tuoi progetti.** Qualcosa che la dashboard da sola non fa:
 > *"Controlla tutti i miei progetti. Dimmi quali hanno spec nel backlog e nessun rail in esecuzione, e avvia in ognuno quella a priorità più alta."*

package/docs/guide/it/integrations/6-agent-chat.md

@@ -68,6 +68,7 @@ Le risposte arrivano fluide e già formattate (titoli, tabelle, elenchi), ciascu
 - **Riduci a icona, senza perdere nulla.** Clicca la ✕ per rimettere il pannello nella bolla — la conversazione continua a girare. Riaprilo e atterri sull'ultimo messaggio; nulla viene riscritto.
 - **Nuova conversazione.** Il pulsante **+** avvia un thread pulito; la cronologia vive a livello di app, sopra qualunque singolo progetto.
 - **Cambia missione.** Il selettore di missioni accanto al selettore di progetto elenca le conversazioni dalla più recente alla più vecchia — un punto pulsante segnala quelle in cui l'agente sta ancora lavorando, e un piccolo badge conta i messaggi in coda. La ricerca compare quando la lista supera le otto voci, e l'icona del cestino su ogni riga elimina una missione dopo una rapida conferma in linea — anche una in corso (prima avvisa, poi ferma l'agente).
+- **Trova una missione da ovunque.** Premi **⌘K** (o il pulsante **Cerca** della barra laterale in modalità Agente) e digita un frammento qualsiasi che ricordi — una parola del titolo *o* di ciò che è stato detto dentro. Le missioni corrispondono all'istante per titolo dalla memoria e, un battito dopo, arrivano le corrispondenze per contenuto con il passaggio evidenziato, più il progetto fissato e l'ultima attività. In modalità Agente le missioni sono il primo gruppo; sulla board stanno subito dopo i Progetti. Invio apre la missione.
 
 ## Alcune cose da sapere
 

package/docs/guide/ja/integrations/5-mcp-server.md

@@ -4,20 +4,20 @@ Specrails は、[Model Context Protocol](https://modelcontextprotocol.io) を話
 
 これは、プラグインや「My approved MCPs」機能とは逆方向の働きをします。それらは Specrails が*ほかの* MCP サーバーを*使う*ためのものですが、こちらは他のアプリに **Specrails** を使わせるためのものです。
 
-## オンにする
+## 最初からオン
 
-これは**デフォルトでオフ**です。**Settings ▸ MCP** を開いて **Enable MCP** を切り替えてください。それだけです — サーバーは即座に起動し、再起動は不要です。
+これは**デフォルトでオン**です — 初めてアプリを開いた時点でサーバーはすでに動いており、再起動も切り替えも不要です。**Settings ▸ MCP** を開けばクライアント設定をコピーでき、不要ならそこでオフにできます。
 
 外部の AI がどんな操作をできるかは、一連の権限ティアで*あなた*がコントロールできます。
 
 | ティア | 許可される内容 | デフォルト |
 |---|---|---|
 | **Read**（読み取り） | プロジェクト、スペック、ジョブ、アナリティクスなどの一覧表示と確認 | 常時オン（MCP が有効なとき） |
-| **Write**（書き込み） | スペックの作成・編集、設定やレール構成の変更 | オフ — 任意で有効化 |
-| **AI-spawn**（AI 起動） | AI を走らせて**お金がかかる**操作（レールの起動、スペックの生成、チャットターンの送信） | オフ — 任意で有効化 |
-| **Destructive**（破壊的操作） | プロジェクト／スペック／ジョブの削除、実行中の作業の停止 | オフ — 任意で有効化 |
+| **Write**（書き込み） | スペックの作成・編集、設定やレール構成の変更 | オン — 制限するならチェックを外す |
+| **AI-spawn**（AI 起動） | AI を走らせて**お金がかかる**操作（レールの起動、スペックの生成、チャットターンの送信） | オン — 制限するならチェックを外す |
+| **Destructive**（破壊的操作） | プロジェクト／スペック／ジョブの削除、実行中の作業の停止 | オン — 制限するならチェックを外す |
 
-無効なティアに該当する操作をアシスタントが試みると、Specrails はそれを拒否し、どのティアをオンにすればよいかを明確なメッセージで知らせます。ですから、まずは読み取り専用から始め、必要なものだけをぴったり開放できます。
+4 つのティアはすべて最初から付与されているので、接続したアシスタントはすぐにアプリ全体を操作できます。自分だけに留めておきたいティアはチェックを外してください。その後アシスタントがそのティアに該当する操作を試みると、Specrails は拒否し、どのティアを再びオンにすればよいかを明確なメッセージで知らせます。
 
 ## アシスタントを接続する
 
@@ -50,11 +50,15 @@ codex mcp add specrails -- <設定 ▸ MCP のブリッジコマンド>
 
 `Authorization: Bearer <token>` ヘッダーも使えます。アプリのポートを変更している場合は `4200` を置き換えてください。
 
-接続が完了すると、アシスタントにはアプリ全体をカバーする約 **18 個のツール**が見えるようになります — プロジェクト、スペック、レールとジョブ、チャット／Explore、エージェント、プラグイン、Jira、ループ、コードエクスプローラー、アナリティクス、設定など。さらに、最初に読み込む組み込みの**ガイド**ツールも含まれているので、あなたが何も説明しなくても、アシスタントは Specrails の仕組みを理解できます。
+接続が完了すると、アシスタントにはアプリ全体をカバーする **22 個のツール**が見えるようになります — プロジェクト、スペック、レールとジョブ、チャット／Explore、エージェント、プラグイン、Jira、ループ、コードエクスプローラー、アナリティクス、設定など。最初に読み込む組み込みの**ガイド**ツールも含まれているので、あなたが何も説明しなくても、アシスタントは Specrails の仕組みを理解できます。
+
+操作の前に、アシスタントは `specrails_context` でプロジェクト、スペック、実行、Git の現在の状態を確認できます。取得できないセクションは明示され、プロジェクトが空であることを意味しません。`specrails_code(search)` はソースコード内のテキストを検索し、`read_file` は指定した行範囲を読み込みます。続きがある場合は、その読み方も返されます。
+
+外部 MCP セッションごとに、選択中のプロジェクトは独立しています。ミッションモードでは、会話に固定されたプロジェクトがデフォルトになり、変更はミッション画面で行います。MCP 側の選択で上書きすることはできません。別のプロジェクトを意図的に操作する場合は、`projectId` を明示します。
 
 ## これで何ができるか
 
-アシスタントを接続したあとの、いくつかのレシピを紹介します。まずは **Read**（読み取り）をオンにして始め、実際に作業を作成・起動させたくなったら **Write**（書き込み）と **AI-spawn**（AI 起動）をオンにしてください。
+アシスタントを接続したあとの、いくつかのレシピを紹介します。すべてデフォルトでオンです。当面は観察だけさせたい場合は、Settings ▸ MCP で **Write**（書き込み）や **AI-spawn**（AI 起動）のチェックを外してください。
 
 **ほかのツールにある作業をスペックに変える。** アシスタントが GitHub、Jira、Gmail、Slack にも接続されていれば、その作業をあなたの代わりに Specrails へ持ち込めます。
 > *「今週の 'bug' ラベルの付いた未解決の GitHub Issue を取り込んで、API プロジェクトにそれぞれスペックを作って、起動して。」*
@@ -64,7 +68,7 @@ codex mcp add specrails -- <設定 ▸ MCP のブリッジコマンド>
 **夜通しのオートパイロット。** アプリをトレイに置いたまま走らせておけば、戻ってきたときにはレポートができています。
 > *「アイデアが 12 個あります。それぞれをスペックにして、レールで 3 つずつ起動して、すべてのジョブを見守って、明日になったら何が完了して、何が失敗して、いくらかかったかをまとめて教えて。」*
 
-**Destructive**（破壊的操作）をオフにしておけば、何ひとつ削除することなく一晩中ビルドを続けられます。
+**Destructive**（破壊的操作）のチェックを外しておけば、何ひとつ削除することなく一晩中ビルドを続けられます。
 
 **すべてのプロジェクトをまたいで。** ダッシュボードだけでは単独でできないことです。
 > *「私のプロジェクトを全部チェックして。バックログにスペックがあるのにレールが 1 つも動いていないものを教えて、それぞれで最も優先度の高いものを 1 つ起動して。」*

package/docs/guide/ja/integrations/6-agent-chat.md

@@ -67,6 +67,7 @@ pure-output action は spawn 前に拒否されます。詳細は
 - **最小化しても失わない。** ✕ をクリックするとパネルはバブルへ戻ります——会話はそのまま動き続けます。開き直すと最新のメッセージに着地します。何も打ち直す必要はありません。
 - **新しい会話。** **+** ボタンでまっさらなスレッドを始めます。履歴はアプリ全体にわたって存在し、個々のプロジェクトの上位にあります。
 - **ミッションの切り替え。** プロジェクトセレクターの隣にあるミッションセレクターは、会話を新しい順に一覧表示します — 点滅するドットはエージェントがまだ作業中の会話を示し、小さなバッジはキュー内のメッセージ数を表します。リストが 8 件を超えると検索欄が現れます。各行のゴミ箱アイコンは、行内のクイック確認のあとにミッションを削除します — 実行中のものでも可能です（先に警告し、その後エージェントを停止します）。
+- **どこからでもミッションを探す。** **⌘K**（またはエージェントモードのサイドバーの **検索** ボタン）を押して、覚えている断片を入力してください——タイトルの単語でも、*中で話された内容* でも構いません。ミッションはまずメモリからタイトルで即座に一致し、一拍おいて内容による一致がハイライト付きで届き、固定されたプロジェクトと最終アクティビティも表示されます。エージェントモードではミッションが最初のグループ、ボードではプロジェクトの直後に並びます。Enter でミッションを開きます。
 
 ## 知っておくとよいこと
 

package/docs/guide/pt/integrations/5-mcp-server.md

@@ -4,20 +4,20 @@ O Specrails pode expor-se **a si próprio** a qualquer assistente de IA que fale
 
 Este é o sentido oposto das funcionalidades de plugins e "Os meus MCPs aprovados": essas permitem que o Specrails *use* outros servidores MCP; esta permite que outras apps usem o **Specrails**.
 
-## Como ativar
+## Vem ativado de origem
 
-Está **desativado por predefinição**. Abra **Definições ▸ MCP** e ligue o **Enable MCP**. É só isso — o servidor arranca imediatamente, sem reiniciar.
+Está **ativado por predefinição** — o servidor já está a correr na primeira vez que abre a app, sem reiniciar nem ligar nada. Abra **Definições ▸ MCP** para copiar a configuração de cliente, ou para o desligar se não o quiser.
 
 Mantém o controlo *do que* uma IA externa pode fazer através de um conjunto de níveis de permissão:
 
 | Nível | O que permite | Predefinição |
 |---|---|---|
 | **Leitura** | Listar e inspecionar projetos, specs, trabalhos, análises… | Sempre ativo (quando o MCP está ativado) |
-| **Escrita** | Criar e editar specs, alterar definições e configuração de rails | Desativado — ativação opcional |
-| **Invocação de IA** | Ações que correm uma IA e **custam dinheiro** (lançar um rail, gerar uma spec, enviar um turno de chat) | Desativado — ativação opcional |
-| **Destrutivo** | Eliminar projetos/specs/trabalhos, parar trabalho em curso | Desativado — ativação opcional |
+| **Escrita** | Criar e editar specs, alterar definições e configuração de rails | Ativado — desmarque para restringir |
+| **Invocação de IA** | Ações que correm uma IA e **custam dinheiro** (lançar um rail, gerar uma spec, enviar um turno de chat) | Ativado — desmarque para restringir |
+| **Destrutivo** | Eliminar projetos/specs/trabalhos, parar trabalho em curso | Ativado — desmarque para restringir |
 
-Se o seu assistente tentar algo abrangido por um nível desativado, o Specrails recusa com uma mensagem clara que lhe diz qual o nível a ativar. Assim, pode começar apenas em modo de leitura e abrir exatamente aquilo de que precisa.
+Os quatro níveis vêm concedidos de origem, por isso um assistente ligado pode conduzir toda a app desde logo. Desmarque qualquer nível que prefira reservar para si; se depois o seu assistente tentar algo abrangido por esse nível, o Specrails recusa com uma mensagem clara que lhe diz qual o nível a voltar a ativar.
 
 ## Ligar o seu assistente
 
@@ -50,11 +50,15 @@ codex mcp add specrails -- <comando do bridge de Configurações ▸ MCP>
 
 O cabeçalho `Authorization: Bearer <token>` também funciona. Se você mudou a porta do app, troque `4200`.
 
-Uma vez ligado, o seu assistente vê cerca de **18 ferramentas** que cobrem a app inteira — projetos, specs, rails e trabalhos, chat/Explore, agentes, plugins, Jira, loops, o explorador de código, análises, definições — mais uma ferramenta de **guia** incorporada que lê primeiro, para que perceba como o Specrails funciona sem que lhe explique seja o que for.
+Uma vez ligado, o seu assistente vê **22 ferramentas** que cobrem a app inteira — projetos, specs, rails e trabalhos, chat/Explore, agentes, plugins, Jira, loops, o explorador de código, análises, definições — incluindo uma ferramenta de **guia** incorporada que lê primeiro, para que perceba como o Specrails funciona sem que lhe explique seja o que for.
+
+Antes de agir, o assistente pode usar `specrails_context` para consultar o estado atual do projeto, das specs, das execuções e do Git. As secções indisponíveis são indicadas explicitamente; não significam que o projeto esteja vazio. `specrails_code(search)` procura texto no código-fonte e `read_file` lê intervalos específicos de linhas, indicando como continuar quando ainda há conteúdo.
+
+Cada sessão MCP externa mantém a sua própria seleção de projeto. No modo Missão, o projeto predefinido é o que está fixado na conversa, que altera na interface da missão; uma seleção MCP não o pode substituir. Um `projectId` explícito permite direcionar intencionalmente uma operação para outro projeto.
 
 ## O que pode fazer com ele
 
-Algumas receitas assim que o seu assistente estiver ligado. Comece com a **Leitura** ativa e, depois, ligue a **Escrita** e a **Invocação de IA** quando quiser que ele crie e lance trabalho de verdade.
+Algumas receitas assim que o seu assistente estiver ligado. Está tudo ativo por predefinição; desmarque a **Escrita** ou a **Invocação de IA** em Definições ▸ MCP se por agora preferir que ele apenas observe.
 
 **Transforme em specs o trabalho das suas outras ferramentas.** Se o seu assistente também tiver o GitHub, o Jira, o Gmail ou o Slack ligados, ele pode trazer esse trabalho para o Specrails por si:
 > *"Pega nas issues abertas do GitHub desta semana com a etiqueta 'bug', cria uma spec para cada uma no projeto da API e lança-as."*
@@ -64,7 +68,7 @@ Algumas receitas assim que o seu assistente estiver ligado. Comece com a **Leitu
 **Piloto automático durante a noite.** Deixe-o a correr com a app no tabuleiro (tray) e volte para encontrar um relatório:
 > *"Aqui estão 12 ideias. Transforma cada uma numa spec, lança-as três de cada vez pelos rails, vigia todos os trabalhos e amanhã dá-me um resumo do que terminou, do que falhou e do que custou."*
 
-Mantenha o **Destrutivo** desativado e ele pode trabalhar a noite toda sem nunca eliminar nada.
+Desmarque o **Destrutivo** e ele pode trabalhar a noite toda sem nunca eliminar nada.
 
 **Em todos os seus projetos.** Algo que o painel não faz por si só:
 > *"Verifica todos os meus projetos. Diz-me quais têm specs no backlog e nenhum rail a correr, e arranca o de prioridade mais alta em cada um."*

package/docs/guide/pt/integrations/6-agent-chat.md

@@ -67,6 +67,7 @@ As respostas chegam de forma fluida e já formatadas (títulos, tabelas, listas)
 - **Minimize sem perder nada.** Clique no ✕ para devolver o painel à bolha — a conversa continua rodando. Reabra e você chega na mensagem mais recente; nada é redigitado.
 - **Nova conversa.** O botão **+** inicia um fio limpo; o histórico vive no nível da aplicação, acima de qualquer projeto individual.
 - **Troque de missão.** O seletor de missões ao lado do seletor de projeto lista suas conversas da mais recente para a mais antiga — um ponto pulsante marca aquelas em que o agente ainda está trabalhando, e um pequeno selo conta as mensagens na fila. A busca aparece quando a lista passa de oito, e o ícone de lixeira de cada linha exclui uma missão após uma confirmação rápida em linha — mesmo uma em andamento (ele avisa primeiro e depois para o agente).
+- **Encontre uma missão de qualquer lugar.** Pressione **⌘K** (ou o botão **Pesquisar** da barra lateral no modo Agente) e digite qualquer fragmento de que se lembre — uma palavra do título *ou* do que foi dito lá dentro. As missões coincidem na hora por título a partir da memória e, um instante depois, chegam as coincidências por conteúdo com o trecho destacado, mais o projeto fixado e quando teve atividade pela última vez. No modo Agente as missões são o primeiro grupo; no quadro ficam logo depois de Projetos. Enter abre a missão.
 
 ## Algumas coisas para saber
 

package/docs/guide/zh/integrations/5-mcp-server.md

@@ -4,20 +4,20 @@ Specrails 可以把**自己**暴露给任何会说 [Model Context Protocol](http
 
 这和插件以及「My approved MCPs」功能的方向正好相反：那些功能是让 Specrails 去*使用*别的 MCP 服务器；而这个功能是让别的应用来使用 **Specrails**。
 
-## 打开它
+## 开箱即用
 
-它**默认是关闭的**。打开 **Settings ▸ MCP**，把 **Enable MCP** 拨开。就这样——服务器会立即启动，无需重启。
+它**默认是开启的**——第一次打开应用时服务器就已经在运行，无需重启，也不用拨任何开关。打开 **Settings ▸ MCP** 可以复制客户端配置，或者在不需要时把它关掉。
 
 通过一组权限层级，你可以始终掌控外部 AI 能透过它做*哪些*事：
 
 | 层级 | 它允许什么 | 默认 |
 |---|---|---|
 | **Read** | 列出并查看项目、规格、任务、分析数据等等…… | 始终开启（在 MCP 启用时） |
-| **Write** | 创建和编辑规格、修改设置与 rail 配置 | 关闭——需手动开启 |
-| **AI-spawn** | 会运行 AI 并**产生费用**的操作（启动一条 rail、生成一份规格、发送一次聊天） | 关闭——需手动开启 |
-| **Destructive** | 删除项目 / 规格 / 任务，停止正在运行的工作 | 关闭——需手动开启 |
+| **Write** | 创建和编辑规格、修改设置与 rail 配置 | 开启——取消勾选即可限制 |
+| **AI-spawn** | 会运行 AI 并**产生费用**的操作（启动一条 rail、生成一份规格、发送一次聊天） | 开启——取消勾选即可限制 |
+| **Destructive** | 删除项目 / 规格 / 任务，停止正在运行的工作 | 开启——取消勾选即可限制 |
 
-如果你的助手试图做某个被禁用层级所涵盖的事，Specrails 会拒绝，并给出一条清晰的提示，告诉你该打开哪个层级。所以你可以先从只读开始，再精确地放开你需要的部分。
+四个层级默认全部授予，所以接入的助手一开始就能驱动整个应用。把你想自己保留的层级取消勾选即可；之后如果助手试图做该层级涵盖的事，Specrails 会拒绝，并给出一条清晰的提示，告诉你该重新打开哪个层级。
 
 ## 连接你的助手
 
@@ -50,11 +50,15 @@ codex mcp add specrails -- <设置 ▸ MCP 中的 bridge 命令>
 
 也可以使用 `Authorization: Bearer <token>` 请求头。如果修改过应用端口, 请替换 `4200`。
 
-一旦连上，你的助手会看到大约 **18 个工具**，覆盖整个应用——项目、规格、rail 和任务、聊天 / Explore、agent、插件、Jira、loop、代码浏览器、分析、设置——外加一个内置的**指南（guide）**工具，它会先读这个工具，从而无需你解释任何东西就能理解 Specrails 是怎么运作的。
+一旦连上，你的助手会看到 **22 个工具**，覆盖整个应用——项目、规格、rail 和任务、聊天 / Explore、agent、插件、Jira、loop、代码浏览器、分析、设置——其中包括一个内置的**指南（guide）**工具，它会先读这个工具，从而无需你解释任何东西就能理解 Specrails 是怎么运作的。
+
+操作前，助手可以通过 `specrails_context` 了解项目、规格、执行任务和 Git 的当前状态。无法获取的部分会明确标注，并不表示项目为空。`specrails_code(search)` 用于搜索源代码中的文本，`read_file` 用于读取指定行范围；如果还有内容，会提供继续读取的信息。
+
+每个外部 MCP 会话独立保存所选项目。在任务模式中，默认使用会话中固定的项目，需要在任务界面修改；MCP 的项目选择不能覆盖它。如果要有意操作另一个项目，可以明确传入 `projectId`。
 
 ## 你能用它做些什么
 
-连上助手后，这里有几个上手的小配方。先打开 **Read**，等你真想让它创建并启动工作时，再打开 **Write** 和 **AI-spawn**。
+连上助手后，这里有几个上手的小配方。一切默认开启；如果你暂时只想让它观察，就在 Settings ▸ MCP 里取消勾选 **Write** 或 **AI-spawn**。
 
 **把你其他工具里的工作变成规格。** 如果你的助手还连着 GitHub、Jira、Gmail 或 Slack，它就能替你把这些工作搬进 Specrails：
 > *「把本周打了 'bug' 标签的开放 GitHub issue 拿过来，在 API 项目里为每个创建一份规格，然后启动它们。」*
@@ -64,7 +68,7 @@ codex mcp add specrails -- <设置 ▸ MCP 中的 bridge 命令>
 **通宵自动驾驶。** 让应用待在托盘里跑着，回来时就能拿到一份报告：
 > *「这里有 12 个点子。把每个变成一份规格，在 rail 上每次三个地启动它们，盯着每一个任务，明天给我一份总结：哪些完成了、哪些失败了、各花了多少钱。」*
 
-只要让 **Destructive** 保持关闭，它就能跑一整夜而绝不会删掉任何东西。
+取消勾选 **Destructive**，它就能跑一整夜而绝不会删掉任何东西。
 
 **横跨你所有的项目。** 这是 dashboard 自己做不到的事：
 > *「检查我所有的项目。告诉我哪些在 backlog 里有规格却没有 rail 在跑，并在每个项目里启动优先级最高的那一个。」*

package/docs/guide/zh/integrations/6-agent-chat.md

@@ -66,6 +66,7 @@ spawn 前拒绝；详见 [Kimi matrix](../../../kimi.md)。
 - **最小化，而不丢失。** 点击 ✕ 把面板收回气泡——对话仍在继续运行。重新打开时你会落在最新一条消息上；无需重新输入任何内容。
 - **新建对话。** **+** 按钮开启一段全新的线程；历史记录存在于整个应用层面，凌驾于任何单个项目之上。
 - **切换任务。** 项目选择器旁的任务选择器按从新到旧列出你的对话——跳动的圆点标记代理仍在工作的对话，小徽章显示排队消息的数量。列表超过八条时会出现搜索框；每行的垃圾桶图标在快速的行内确认后删除任务——即使是正在运行的任务（会先警告，然后停止代理）。
+- **随时随地找到任务。** 按 **⌘K**（或代理模式下侧边栏的 **搜索** 按钮），输入你记得的任何片段——标题中的一个词，*或者* 对话里说过的内容。任务会立刻按标题从内存中匹配，紧接着按内容匹配的结果也会到达，并高亮匹配段落，同时显示固定的项目和最近活动时间。在代理模式下任务是第一组；在看板中紧跟在项目之后。按 Enter 打开任务。
 
 ## 一些需要知道的事
 

package/docs/internals/README.md

@@ -12,6 +12,7 @@ If you're a user looking for **how do I do X?** docs, head back to the [user gui
 | [api-reference.md](api-reference.md) | REST endpoint catalogue under `/api/*` and `/api/projects/:projectId/*` |
 | [configuration.md](configuration.md) | Settings, env vars, kill switches, advanced flags |
 | [operations-runbook.md](operations-runbook.md) | Start/stop, port conflicts, recovery procedures, backups |
+| [core-runtime-updates.md](core-runtime-updates.md) | Core runtime discovery, durable package updates, version reporting and recovery after partial workspace refresh |
 | [openspec-workflow.md](openspec-workflow.md) | `opsx:*` change lifecycle — used by the app itself for structured change management |
 | [adding-a-provider.md](adding-a-provider.md) | How to add a new AI CLI: one adapter file plus one entry in the registry |
 | [profiles.md](profiles.md) | Agent profiles quick start: open the Agents section, pick a profile per rail at launch, author custom agents in Agent Studio. For the true file-format and snapshotting internals, read `server/profile-manager.ts` and the profile-manager section of `CLAUDE.md` |

package/docs/internals/browser-capture-performance.md

@@ -1,6 +1,6 @@
 # Embedded browser: performance + popup support
 
-The embedded browser backs two surfaces: **Add Spec → From a website** (`BrowserCaptureModal`) and the read-only **WebView** for opening links / the Agent-Mode Browser tool (`WebViewModal`, `AgentBrowserCapture`). Both ride the same session machinery. This doc maps the pipeline, the fluidity levers applied (benchmark: Cursor's embedded browser), the tuning knobs, and the OAuth popup design.
+The Playwright capture engine backs **Add Spec → From a website** (`BrowserCaptureModal`) and the screencast fallback for in-app browsing. Desktop browsing uses a native webview when available; this document covers the instrumented capture/fallback path, its tuning knobs, and OAuth popup handling. Local smoke timings below describe this pipeline, not a measured comparison with Cursor.
 
 ## Pipeline map
 
@@ -42,7 +42,9 @@ useBrowserCaptureSession (client)  ───────────────
 | **Ack-first screencast** — `screencastFrameAck` fires (fire-and-forget) *before* the handler/fan-out, overlapping Chromium's next capture with delivery. | `browser-playwright.ts` `startScreencast` | Higher fps ceiling, lower frame age. |
 | **Wheel fast-path** — skip the redundant `mouse.move` when the cursor hasn't moved (tracked via `lastMouse`), and dispatch move+wheel back-to-back (`Promise.all`) so a concurrent wheel can't interleave between them. | `browser-playwright.ts` `dispatchInput` | ~2× fewer CDP commands per wheel; ordering hazard removed. |
 | **Frame conflation for slow consumers** — skip a frame for any WS client whose `bufferedAmount` exceeds 1 MB (frames are independent JPEGs; `lastFrame` still updates). | `browser-capture-manager.ts` fan-out | Latency stays bounded under backpressure — staleness, not fps, is what reads as "sluggish". |
-| **Centralised screencast params** — `screencastParams()`: JPEG, `everyNthFrame: 1`, guard caps 3840×2400 (viewport already ≤ display size, so this is a guard, not a downscaler). | `browser-playwright.ts` | Tunable quality knob (below); pathological-viewport guard. |
+| **Retina PNG capture** — the interactive page and JPEG stream keep their CSS dimensions; selected PNG regions are re-rasterized at display density (up to 2), bounded to a 3840×2400 viewport raster. | `browser-playwright.ts`, `browser-viewport.ts` | Higher-resolution capture artifacts without altering input units, page zoom, scroll, or responsive breakpoints. Desktop native browsing supplies Retina live rendering. |
+| **Recoverable screencast startup** — partial CDP sessions are detached after rejection; the manager retries once, then closes the failed stream explicitly. Late frames from previous popup/root views are discarded. | Playwright handle + manager | A transient CDP failure no longer leaves a permanently blank, apparently ready session. |
+| **Browser acceleration defaults** — no unconditional `--disable-gpu`; explicit compatibility override remains available. | `chromiumLaunchArgs` | Lets Chromium choose its rendering path; no universal measured speedup is claimed. |
 | **Live URL bar** — `onNavigated` (main-frame `framenavigated`) broadcasts `nav` on in-page link clicks/redirects. | manager + playwright handle | URL bar no longer goes stale after clicking links. |
 
 ### Client
@@ -55,6 +57,42 @@ useBrowserCaptureSession (client)  ───────────────
 
 Select-mode hover-probe throttling (rAF + 40 ms) is untouched — element-picker precision is unchanged.
 
+### Capture density and CDP streaming limitation
+
+`resize` carries optional display `deviceScaleFactor` for **PNG capture density**;
+`width`/`height`, pointer positions, DOM boxes, responsive presets, and capture
+rectangles remain **CSS pixels**. Old clients without DPR remain supported.
+The server normalizes finite dimensions and density, caps requested density to
+`[1, 2]`, and lowers effective density when necessary to keep a full-viewport PNG
+within 3840×2400. It serializes viewport changes and keeps only the newest pending
+resize. The interactive Playwright context stays at its original DPR 1.
+
+The **JPEG fallback stream remains 1 pixel per CSS pixel**. The native desktop
+webview is the path for full-density live browsing. Several CDP alternatives were
+tested and rejected rather than trading correctness for nominal frame dimensions:
+
+- Context DPR 2 alone still emits a CSS-sized JPEG and changes delivered
+  `WheelEvent.deltaY` without changing native scroll distance.
+- `setVisibleSize` plus `dontSetVisibleSize` enlarges the JPEG but leaves the
+  page in its upper-left quadrant with white padding. This caused the reported
+  quarter-page rendering regression.
+- An explicit emulated `viewport` fills the raster at scroll zero but fixes a
+  document clip that stops following the viewport after scrolling.
+- Top-level emulation `scale` fills the raster and follows scrolling, but
+  changes pointer coordinates and wheel-event units.
+
+The production adapter therefore does **not** issue those emulation commands.
+The smoke checks colored markers at all four edges of the decoded **JPEG** after
+scroll/resize, as well as both DOM wheel deltas and actual native scroll distance.
+
+High-density region screenshots use `Page.captureScreenshot` with **CSS** layout
+metrics, scroll offsets, and `clip.scale` equal to effective capture density.
+This leaves the interactive page untouched while re-rasterizing text/vector
+detail. PNG dimensions are `rect × effective density` (rounded to pixels); the
+DOM attachment still describes the original CSS rectangle. At density 1 the
+existing Playwright capture path remains. A half-CSS-pixel stripe fixture verifies
+detail missing from an interpolated 1× PNG, alongside diagonal/text comparisons.
+
 ## Popup support (OAuth login windows)
 
 Pop-ups now work end-to-end — the design:
@@ -70,12 +108,12 @@ Pop-ups now work end-to-end — the design:
 | Knob | Default | Effect |
 |---|---|---|
 | `SPECRAILS_BROWSER_SCREENCAST_QUALITY` (server env) | `70` | JPEG quality 1–100. Lower → smaller frames/higher fps; higher → crisper. |
+| `SPECRAILS_BROWSER_DISABLE_GPU` (server env) | unset | Set exactly `true` to force Chromium software rendering for driver compatibility. |
 | `localStorage['specrails-desktop:browser-capture-debug'] = '1'` (client) | off | Per-2s frame-pipeline stats in the console. |
 | `MAX_CLIENT_BUFFERED_BYTES` (`browser-capture-manager.ts`) | 1 MB | WS backpressure threshold before frames are conflated per client. |
 
 ## Deferred / non-goals
 
-- **DPR-aware streaming** (frames at `devicePixelRatio ×` for retina crispness) — costs 4× pixels; quality knob covers most of it. Revisit if crispness complaints appear.
 - **Context prewarm on Add-Spec-modal open** — would shave the first-ever Chromium launch (~0.5–1 s); needs a hook outside the browser-capture surface. The shared context already persists across sessions, so only the first open pays it.
 - **Input round-trip probe** — needs a server echo; the frame probe covers the visible symptom.
 
@@ -83,6 +121,20 @@ Pop-ups now work end-to-end — the design:
 
 Unit coverage: `server/browser-capture-manager.test.ts` (deferred nav, conflation, full popup lifecycle), `server/browser-playwright.test.ts` (`screencastParams`), `server/project-router.browser.test.ts` (popup-view route), `client/src/lib/browser-frame-pipeline.test.ts` (latest-wins/drop/dispose/stats), `client/src/lib/browser-capture.test.ts` (coalescer, popup helpers).
 
+`node scripts/smoke-browser-rendering.mjs` exercises the real exported Playwright
+handle using generated pages and temporary profiles, with no Specrails DB or
+external sites. It asserts fully painted CSS-sized JPEG frames, unchanged layout
+and zoom, pointer/text/wheel input, resize, and correctly positioned PNG crops
+at density 1, 2, and fractional 1.92 after scrolling (including 2000×1100 CSS).
+It verifies real PNG detail against interpolated 1× images. It reports launch,
+first-frame, input-command, received-frame
+rate, and frame-byte diagnostics with acceleration defaults and the software
+override. These timings exclude WS/client decoding and are not end-to-end input
+latency. Earlier sample timings from the discarded enlarged-surface experiment
+are intentionally omitted: a partly painted frame is not a valid performance
+comparison. Run the smoke for current local diagnostics; no performance threshold
+or Cursor-equivalence claim is asserted.
+
 Manual QA feel-check list:
 
 1. **Scroll fluidity** — open a long page (e.g. a docs site), trackpad-scroll fast: motion should track your fingers with no rubber-banding or seconds-later catch-up.

package/docs/internals/browser-login-popups.md

@@ -0,0 +1,45 @@
+# Browser authentication popup audit
+
+Date: 2026-09-05. Branch: `feat/codex-gpt-6-astra`.
+
+## Scope and causes
+
+The browser already supported first-level authentication windows. The audit found defects in nested windows, closure and asynchronous lifecycle handling, rather than a universal prohibition on `window.open`.
+
+On macOS, a real WKWebView fixture reproduced two failures: the first popup's `on_new_window` handler explicitly denied another popup, and the installed Wry UI delegate did not implement `webViewDidClose:`. A page could deliver its authentication result with `postMessage` but leave its window open. The initial blank window, cross-origin redirects, shared cookies and opener relationship already worked.
+
+The Chromium development path also completed the ordinary OAuth sequence. Regression tests reproduced missed children opened before subscription, closed pages adopted after an asynchronous opener lookup, missed closure notifications and an obsolete popup screencast failure disconnecting the whole session.
+
+The review found two additional recovery problems in the streamed UI: browser navigation always targeted the root page even when a popup was visible, and switching back to the root changed the client optimistically while HTTP failures were ignored. Reloading a login could therefore reload its opener, or a failed view switch could enable root-page capture while the stream still showed the login.
+
+## Implementation boundaries
+
+- Native windows retain the engine-supplied `NewWindowFeatures`, including the opener configuration. They are actual related browser windows; an OAuth URL is not reopened in an unrelated browser profile.
+- Nested native windows share the same pane owner and have a bounded live-window count. Closing a pane releases only its own windows. Creation failures produce an owner-scoped, localized error without exposing an OAuth URL or raw native error.
+- The macOS close delegate handles only `webViewDidClose:` and forwards Wry's existing delegate behavior. It uses the public WebKit callback, without rewriting a site's JavaScript or exposing an application command to the page.
+- Playwright subscription replay checks the direct opener, skips closed pages, deduplicates delivery and invalidates pending lookups when the parent closes. Late close subscriptions notify once. A superseded popup's failed CDP startup does not disconnect the opener.
+- Streamed navigation targets the page selected when the action starts. Popup navigation returns `target: 'popup'` and does not replace or persist root-page metadata; the client takes popup metadata from the existing WebSocket events. View switching remains tied to server state, and failures remain visible without pretending a switch succeeded. Late responses are checked against the session, popup revision and latest switch request.
+
+HTTP/HTTPS/about:blank navigation restrictions, Chromium request guards and the native app-command boundary remain enforced. This change does not disable browser origin isolation, alter an identity provider's COOP policy, or transfer cookies to the system browser.
+
+## Reproducible acceptance checks
+
+`node scripts/smoke-browser-popups.mjs` exercises the production Playwright page handle and session manager with temporary state and two synthetic local origins. It covers blank-window creation, cross-origin HTTP redirects, login input, cookies, `postMessage`, self-close, iframe-initiated login, nested second-factor windows, repeated immediate callbacks, late listener attachment and isolation between browser sessions.
+
+The native popup fixture is under `src-tauri/examples/native-browser-popup-smoke.rs`. From `src-tauri`, run `cargo run --offline --example native-browser-popup-smoke --features native-browser-smoke` on macOS. It uses a temporary authentication fixture and an ephemeral browser store. It checks actual WebKit behavior, rather than substituting mocked window events: asynchronous opening, opener communication and cookies, nested windows, `_blank`, an iframe, immediate self-close, the window limit and retry, owner cleanup and denied remote app commands. The existing `native-browser-smoke` example also passes the Retina snapshot and selector regression checks after installing the popup delegate.
+
+Unit and component regressions cover lifecycle races, navigation ownership, failed view switches and localized native popup errors. See the browser rendering and capture checks in [the Retina audit](browser-native-retina-audit.md) for the independent viewport and screenshot guarantees.
+
+Completed checks for this patch:
+
+- Server coverage: 282 files and 7,418 tests passed; 85.98% statements, 78.40% branches, 90.02% functions and 88.32% lines, with the existing thresholds.
+- Client coverage: 354 files and 4,431 tests passed; 89.24% statements/lines, 83.00% branches and 74.58% functions, with the existing thresholds.
+- Targeted popup checks: 120 server tests across the page handle, manager and HTTP routes; 61 client tests for the streamed browser and API; 63 client tests for the native pane, native API and locale parity.
+- Rust: 26 library tests passed, plus `cargo check --offline --all-targets --features native-browser-smoke` and both actual WebKit smoke examples.
+- Global TypeScript, the production server/client/CLI build and the Core 4.11.1 / Desktop 2.40.0 compatibility check passed.
+
+No real Okta tenant, credentials, production database or user browser profile is used. Passing the synthetic OAuth flows does not certify every organization's identity-provider policy. Windows native behavior still needs a real Windows smoke run; macOS WebKit and Chromium are the locally exercised engines. Native changes require rebuilding the desktop application and do not replace an installed signed release.
+
+## Reference
+
+The [official Okta Auth JS documentation](https://github.com/okta/okta-auth-js/) describes popup flows that exchange results with `window.postMessage`, and a distinct redirect-based flow for external identity providers whose COOP headers separate browsing contexts. Preserving browser-native opener semantics is necessary; overriding those security policies in Specrails would not be a valid interoperability fix.