specrails-desktop 2.8.0 → 2.9.1

package/docs/guide/pt/insights/1-analytics-and-cost-tracking.md

@@ -0,0 +1,78 @@
+# Analytics e controlo de custos
+
+Sempre que o Specrails corre uma CLI de IA por si — um job de pipeline, uma quick spec, uma sessão de Explore, um refinamento de IA, um resumo de ficheiro — fica registado o que aconteceu: que modelo correu, quantos tokens entraram e saíram, quanto tempo demorou e quanto custou. A secção **Analytics** transforma tudo isso num único painel, para que saiba sempre para onde vai o seu investimento em IA.
+
+Abra-a a partir da barra lateral direita (tem a etiqueta **Analytics**). Tudo o que vê diz respeito ao projeto em que se encontra neste momento — mude de projeto e os números acompanham-no.
+
+## O que conta como gasto
+
+O Specrails regista cinco tipos de atividade de IA, a que chamamos *superfícies*. Cada uma tem uma cor consistente em todos os gráficos, para a identificar num relance:
+
+- **Job** — um rail de pipeline a correr Architect → Developer → Reviewer → Ship.
+- **Quick spec** — uma spec gerada pelo caminho rápido de Add Spec.
+- **Explore spec** — uma conversa de Explore em que dá forma a uma spec à medida que conversa.
+- **AI edit** — um refinamento assistido por IA sobre um agente ou ficheiro.
+- **File summary** — os resumos em linguagem simples que dão vida ao Code explorer.
+
+Há um par de coisas que, propositadamente, *não* são registadas: tanto o chat lateral como o assistente de configuração arrancam CLIs de IA, mas nunca aparecem nos seus gastos. Assim, o painel reflete trabalho real e repetível, em vez de conversa ocasional.
+
+## Ler o painel
+
+A página é composta por um punhado de blocos, de cima para baixo:
+
+### O medidor de consumo (Hero)
+
+O grande número no topo é o seu gasto total para o período selecionado, acompanhado por uma variação **vs anterior**, para perceber num relance se a tendência é de subida ou de descida face à janela anterior. Se acabou de começar a usar um projeto, o estado vazio indica-lhe quando o registo começou ("Registo iniciado em YYYY-MM-DD") — não há preenchimento retroativo de histórico, por isso o medidor só conhece as execuções que aconteceram enquanto estava nesta versão.
+
+### Cronologia diária
+
+Um gráfico de barras empilhadas com o gasto por dia, dividido por superfície. Os dias sem atividade aparecem como zero em vez de serem saltados, para que a forma da sua semana seja honesta. É a forma mais rápida de ver *quando* correu um lote dispendioso.
+
+### Quick vs Explore
+
+Um cartão lado a lado a comparar os seus dois estilos de criação de specs. Se correu menos de cinco sessões de Explore, mostra um convite à ação delicado em vez de médias enganadoras — amostras pequenas não dão comparações de confiança.
+
+### Por modelo
+
+Os seus modelos com mais gasto (até dez). Clique em qualquer modelo para filtrar todo o painel apenas por esse modelo — útil quando quer saber quanto lhe está realmente a custar um modelo topo de gama em particular.
+
+### Dispersão custo vs turnos
+
+Cada ponto é uma invocação, representando o custo face ao número de turnos. Os pontos discrepantes — as execuções caras, de muitos turnos — saltam logo à vista. (A dispersão mostra os seus 500 pontos mais recentes, para se manter ágil.)
+
+### Top tickets
+
+Os seus dez tickets mais caros somando *todas* as superfícies, para que um ticket que custou pouco no Explore e muito num job mostre o seu verdadeiro total. Os tickets eliminados e as execuções sem atribuição ganham os seus próprios baldes, para que nada desapareça silenciosamente dos totais.
+
+### Tabela de invocações em bruto
+
+A verdade dos factos: uma linha por invocação. Este bloco tem os seus próprios filtros secundários, que afetam apenas a tabela, para poder aprofundar sem mexer nos gráficos acima.
+
+## Filtrar
+
+O cabeçalho fixo no topo traz os dois filtros principais — **período** e **superfície** — e ambos ficam guardados no URL da página. Isto significa que pode marcar nos favoritos ou partilhar uma vista filtrada ("últimos 30 dias, só jobs") e ela reabre exatamente como a deixou. Os filtros da tabela em bruto são separados e ficam locais a esse bloco.
+
+Uma nota sobre rigor: as execuções falhadas e abortadas ficam de fora das *médias de custo* (distorceriam os números por execução), mas continuam a contar para o total de execuções e para a taxa de falhas. Assim, as médias mantêm-se limpas enquanto o retrato de fiabilidade se mantém completo.
+
+## Custo por ticket
+
+Não precisa de ir à página de Analytics para ver quanto custou uma spec. Abra qualquer ticket e, se tiver algum gasto associado, vê um resumo numa só linha logo por baixo do título:
+
+> $0.42 · 6 turnos · 1m 12s ativos · detalhe
+
+Clique nele e vai parar à página de Analytics já filtrada por esse ticket. É o caminho mais rápido entre "quanto me custou esta funcionalidade?" e o detalhe completo.
+
+## Exportar os seus dados
+
+Quando precisa dos números fora da aplicação — uma folha de cálculo, um relatório financeiro, a sua própria análise — use o menu **Export**. Oferece quatro formatos:
+
+- **CSV de resumo** — um ficheiro com várias secções, com totais, cronologia diária, por superfície, por modelo e top tickets.
+- **JSON de resumo** — o mesmo resumo, estruturado.
+- **CSV em bruto** — todas as linhas de invocação (até 10.000; assinala se teve de truncar).
+- **JSON em bruto** — as mesmas linhas em bruto, estruturadas.
+
+As exportações respeitam os filtros de período e superfície que tiver aplicados nesse momento, e os ficheiros são nomeados de forma a ordenarem-se com lógica: `<project>-analytics-<period>-<date>.csv`. O botão fica desativado quando não há nada para exportar, e recebe uma notificação de erro clara se uma transferência falhar.
+
+## Sempre em direto
+
+Não precisa de atualizar a página. Quando uma nova invocação é registada em qualquer ponto do projeto, o painel aberto volta a carregar-se discretamente pouco depois, para que o medidor de consumo acompanhe o trabalho à medida que vai terminando.

package/docs/guide/pt/insights/2-the-integrated-terminal.md

@@ -0,0 +1,46 @@
+# O terminal integrado
+
+O Specrails tem um terminal a sério mesmo lá dentro — o painel que sobe a partir do fundo da janela, tal como o do VS Code ou do Cursor. Corre a sua shell real, na pasta real do seu projeto, para poder correr `git`, `npm`, testes ou o que precisar sem sair da aplicação.
+
+## Abrir e fechar
+
+A forma mais rápida é pelo teclado: **Cmd+J** (macOS) ou **Ctrl+J** (Windows/Linux) abre e fecha o painel, e dá o foco ao terminal assim que ele aparece, para poder começar a escrever de imediato. Também pode usar a seta na barra de estado.
+
+O painel tem três estados:
+
+- **Oculto** — recolhido de lado.
+- **Restaurado** — o painel normal, em meia altura.
+- **Maximizado** — a ocupar toda a área de trabalho quando precisa de espaço para ler o output.
+
+Minimizar o painel (a seta) **não** interrompe nada — as suas shells continuam a correr em segundo plano. A única coisa que termina mesmo uma sessão é fechá-la (o ícone do caixote do lixo, ou o ✕ de cada separador).
+
+## Várias sessões
+
+Pode ter vários terminais ao mesmo tempo no mesmo projeto — até dez. Cada um ganha o seu separador; pode renomeá-los para que "dev server" e "testes" não se confundam. Todos arrancam na pasta do seu projeto e carregam o perfil da sua shell (`.zshrc`, `.bashrc`, e por aí fora), para que os seus aliases e o PATH sejam exatamente o que esperaria.
+
+E aqui está o mais importante: os seus terminais **sobrevivem à mudança de projetos e de separadores**. O Specrails mantém cada sessão viva e intacta nos bastidores — scrollback, processos em execução, tudo — para que saltar para a secção Analytics e voltar não reinicie a sua shell nem interrompa um comando de longa duração. As sessões só terminam quando as fecha explicitamente (ou quando remove o projeto inteiro).
+
+## Por projeto, e memorizado
+
+Se o painel está aberto, a altura para que o arrastou, que separadores existem — tudo isso fica memorizado **por projeto**. Volte a um projeto e está tal como o deixou.
+
+## As funcionalidades premium
+
+Isto não é uma consola básica. O terminal vem com os mimos que esperaria de um terminal de primeira:
+
+- **Renderização rápida e nítida** via WebGL (com um modo alternativo automático, para nunca falhar), tratamento completo de larguras Unicode e ligaduras de tipos de letra.
+- **Pesquisar no scrollback** com **Cmd+F** — ótimo para encontrar aquele erro enterrado 500 linhas acima.
+- **Zoom do tipo de letra** com **Cmd+=**, **Cmd+-** e **Cmd+0** para repor.
+- **Atalhos da área de transferência** — Cmd+C / Cmd+V para copiar e colar, Cmd+K para limpar — além de um menu de contexto do botão direito.
+- **Arrastar e largar caminhos de ficheiros** (na aplicação de desktop): largue um ficheiro sobre o terminal e o seu caminho é inserido, corretamente entre aspas para a sua shell.
+- **Redimensionamento suave** — arrastar a altura do painel ou recolher a barra lateral não faz o output tremer.
+- **Imagens inline** — terminais que emitem imagens em Sixel ou no estilo iTerm2 mostram-nas mesmo no sítio.
+- **Integração com a shell** — o Specrails sabe onde cada comando começa e acaba, por isso consegue acompanhar o seu histórico de comandos e avisá-lo quando um comando de longa duração termina (uma notificação de desktop, com um modo alternativo no browser). Se, por alguma razão, a sua shell não puder ser instrumentada, degrada-se discretamente e avisa-o uma vez.
+
+## Definições
+
+As preferências do terminal vivem em duas camadas: um padrão para toda a aplicação e uma substituição opcional por projeto. A definição por projeto prevalece quando existe, para poder manter um aspeto geral comum e, ao mesmo tempo, afinar um projeto que precise de algo diferente.
+
+## Desligá-lo
+
+O terminal está ligado por predefinição. Se preferir ficar sem ele, pode desativá-lo através das flags `VITE_FEATURE_TERMINAL_PANEL` (cliente) ou `SPECRAILS_TERMINAL_PANEL` (servidor) — defina qualquer uma como `false`. A maioria das pessoas vai simplesmente deixá-lo ligado.

package/docs/guide/pt/insights/3-code-explorer.md

@@ -0,0 +1,50 @@
+# Code explorer
+
+A secção **Code** dá-lhe uma janela amigável e só de leitura para o seu repositório — pensada especialmente para quem quer perceber o que a IA tem andado a construir sem viver dentro de um editor. Tem uma árvore de ficheiros à esquerda, um visualizador de código à direita e, por cima do código, um resumo em linguagem simples do que cada ficheiro faz na prática.
+
+Nesta versão é estritamente só de leitura: nada do que faz aqui altera os seus ficheiros. Pense nisto como uma sala de leitura, não uma oficina.
+
+Abra-a a partir da barra lateral direita (**Code**) e, como tudo o resto, diz respeito ao seu projeto atual.
+
+## A árvore de ficheiros
+
+O painel da esquerda é uma árvore virtualizada dos ficheiros do seu projeto — rápida mesmo em repositórios grandes. Respeita o seu `.gitignore` e uma lista de exclusão incorporada, por isso vê os ficheiros que interessam, e não um mar de artefactos de build e `node_modules`.
+
+Junto aos ficheiros vai reparar em **etiquetas de proveniência** — pequenos marcadores que lhe dizem que um ficheiro foi *alterado por IA*. É este o coração do Code explorer: o Specrails regista que ficheiros cada job de pipeline criou ou modificou, e liga-os de volta ao ticket que motivou o trabalho. Assim consegue responder, num relance, a "foi a IA que escreveu isto, ou fui eu?".
+
+No topo da árvore há um filtro:
+
+- **Alterados por IA** (a predefinição) — apenas os ficheiros que a IA alterou.
+- **Todos os ficheiros** — a árvore completa.
+
+A sua escolha fica memorizada por projeto, por isso, se o que mais lhe importa são as alterações feitas pela IA, vai vê-las em primeiro lugar de cada vez.
+
+## O visualizador de código
+
+Clique num ficheiro e ele abre num visualizador completo (com o Monaco, o mesmo motor do VS Code), com realce de sintaxe adequado e a condizer com o tema que escolheu para a aplicação. Alguns limites sensatos mantêm tudo fluido: os ficheiros binários são recusados com delicadeza e os ficheiros muito grandes (acima de 2 MB) não carregam.
+
+O ficheiro atual fica guardado no URL da página, para poder marcar nos favoritos ou partilhar uma ligação diretamente para um ficheiro específico.
+
+Como a edição não faz parte desta versão, o visualizador oferece um botão **Editar num editor externo** que copia o caminho absoluto do ficheiro — cole-o no editor da sua preferência e continue a partir daí.
+
+## Resumos por IA
+
+Por cima do código vê um **resumo em linguagem simples** do ficheiro — para que serve, o que faz — escrito de forma a que uma pessoa não programadora consiga acompanhar. São gerados por si e ficam em cache, por isso abrir um ficheiro que já tinha visto antes é instantâneo.
+
+Os resumos são espertos a manter-se atualizados: estão associados ao conteúdo do ficheiro, por isso, quando um ficheiro muda de verdade, o resumo é regenerado, mas os ficheiros inalterados não são resumidos de novo sem necessidade. Se for você a editar um ficheiro, o seu resumo é marcado como desatualizado em vez de ser regenerado em silêncio — fica no controlo de quando é atualizado. Há uma ação de **regenerar** para quando quiser uma nova versão a pedido.
+
+Algumas salvaguardas mantêm os custos sob controlo: a geração de resumos corre dentro de um **orçamento mensal** (alguns dólares por predefinição, configurável nas Definições) e há limites para quantos resumos um único job pode despoletar. Se um resumo for ignorado, a aplicação diz-lhe porquê — orçamento atingido, um limite por job, ou simplesmente o ficheiro não ter sido encontrado.
+
+Pode também escolher o **idioma do resumo** (inglês ou espanhol) nas definições globais, na área da *secção Code*.
+
+## Ligar o código de volta às specs
+
+A ligação de proveniência funciona nos dois sentidos. Dentro do Code explorer, clicar na etiqueta de um ticket num ficheiro abre o detalhe desse ticket. E no sentido inverso, a vista de **detalhe do ticket** tem uma secção *Ficheiros alterados por este ticket* — clique aí num ficheiro e salta diretamente para o Code explorer com ele aberto. Fecha o ciclo entre "aqui está a spec que escrevemos" e "aqui está o código que daí saiu".
+
+## O que (ainda) não faz
+
+Para deixar as expectativas claras, esta primeira versão deixa de fora, de propósito, algumas coisas: edição dentro da aplicação, resumos ao nível do símbolo ou da pasta, uma vista de diff narrativa e o "pergunte à IA sobre este ficheiro" em modo de conversa. A proveniência atribui um ficheiro apenas ao seu ticket principal. São o tipo de coisas que podem crescer com o tempo.
+
+## Desligá-lo
+
+O Code explorer está ligado por predefinição. Pode ser desativado com as flags `VITE_FEATURE_CODE_EXPLORER` (cliente) ou `SPECRAILS_CODE_EXPLORER` (servidor) — defina qualquer uma como `false`. Desligá-lo deixa todos os seus dados registados e resumos em segurança no disco, intactos, para o caso de o voltar a ligar.

package/docs/guide/pt/integrations/1-ai-providers.md

@@ -0,0 +1,64 @@
+# Providers de IA (Claude, Codex, Gemini)
+
+O Specrails não está preso a uma única IA. Todas as partes da app que falam com uma IA — Explore Spec, spec rápida (Quick), rails, chat, AI Edit, o botão "Open AI CLI" do terminal — podem correr através de qualquer um dos três providers de primeira linha. Você escolhe quais é que cada projeto usa e pode até alternar tarefa a tarefa.
+
+## Os três providers
+
+| Provider | CLI | Feito por | Notas |
+|---|---|---|---|
+| **Claude** | `claude` | Anthropic | O mais completo. O único provider para Agentes (perfis) e rails Ultracode, e para o Contract Refine. |
+| **Codex** | `codex` | OpenAI | Requer codex `0.128.0+`. Lê os seus servidores MCP a partir do `~/.codex/config.toml` global. |
+| **Gemini** | `gemini` | Google | Requer gemini `0.11.0+`. Usa telemetria nativa e um ficheiro de instruções `GEMINI.md`. |
+
+Os três estão **ativados por omissão**. Um provider aparece em **Adicionar Projeto** sempre que o seu CLI estiver instalado e no seu `PATH`. Por isso o primeiro passo é sempre o mesmo: instale o CLI que quer e autentique-se com ele, exatamente como a documentação dessa ferramenta descreve. Assim que `claude --version` (ou `codex`, ou `gemini`) funcionar no seu terminal, o Specrails consegue usá-lo.
+
+## Instalar um provider para um projeto
+
+Quando adiciona um projeto, o assistente de configuração pergunta qual ou quais providers instalar. Escolha um, avance pelo passo de instalação e está feito. A partir daí o projeto simplesmente *tem* esse provider — nunca mais precisa de pensar nisso. Specs, rails, chat e analytics funcionam todos da mesma forma, independentemente do que escolheu.
+
+Se um CLI que quer não aparecer em Adicionar Projeto, é quase sempre porque o CLI não está instalado ou não está no seu `PATH`. Instale-o e volte a abrir Adicionar Projeto.
+
+## Instalar vários providers num só projeto
+
+Pode instalar **mais do que um** provider no mesmo projeto — por exemplo Claude *e* Gemini. Em **Adicionar Projeto**, a lista de providers passa a ser um conjunto de caixas de seleção; marque tudo o que quiser. O primeiro que selecionar torna-se o provider **primário** (por omissão) do projeto; os restantes ficam disponíveis como alternativas.
+
+Algumas coisas que vale a pena saber sobre projetos multi-provider:
+
+- **Com um só provider, tudo se comporta exatamente como antes.** Se um projeto tiver apenas um provider, nunca verá um seletor de provider em lado nenhum — a app mantém-se limpa e simples.
+- **A barra lateral direita só mostra as secções que todos os providers instalados suportam.** Como os Agentes (perfis) são um conceito exclusivo do Claude, a secção **Agentes** desaparece assim que um projeto inclui qualquer provider que não seja Claude. Todo o resto (Specs, Código, Analytics, Integrações, Terminal, Chat) permanece.
+- **A escolha de providers fica fixada após a criação.** Nesta versão escolhe os seus providers quando adiciona o projeto e não podem ser alterados mais tarde nas Definições. Se precisar de uma combinação diferente, isso é um projeto novo.
+
+## Escolher um provider a cada invocação
+
+A grande vantagem de um projeto multi-provider é poder escolher a IA certa para cada tarefa — sem mexer em nenhuma definição global. Sempre que uma IA corre, aparece um pequeno seletor de provider (apenas quando o projeto tem mais do que um):
+
+- **Adicionar Spec** — um seletor de motor permite-lhe Explorar ou gerar rapidamente (Quick) uma spec com o provider que preferir.
+- **Cabeçalho do rail** — escolha o motor para esse rail específico antes de o lançar.
+- **Terminal** — o botão "Open AI CLI" (Sparkles) abre um menu de providers para que possa entrar em qualquer CLI instalado na diretoria desse projeto.
+
+A sua escolha é guardada por projeto, predefinida para o provider primário, para que não tenha de a repetir de cada vez.
+
+## O que só o Claude consegue fazer
+
+Algumas funcionalidades são, por natureza, específicas do Claude, por isso ficam escondidas ou são ignoradas quando outro provider está em jogo:
+
+- **Agentes (perfis)** — o catálogo de agentes por projeto e o roteamento de modelos. Escondido em qualquer projeto que inclua um provider que não seja Claude.
+- **Rails Ultracode** — correm sempre no Claude.
+- **Contract Refine** — a passagem extra de "Contract Layer" sobre uma spec confirmada só corre quando o provider da conversa é o Claude.
+- **Modos avançados de Adicionar Spec** (SMASH / Contract Layer) — escondidos para motores que não sejam Claude.
+
+Todo o resto — Explore, spec rápida (Quick), o pipeline completo de rails, AI Edit, chat, analytics de custos — funciona nos três.
+
+## Acompanhamento de custos entre providers
+
+A página **Analytics** acompanha cada invocação faturável, independentemente do provider. Em projetos multi-provider acrescenta chips de filtro por motor para que possa comparar o gasto por provider. O Claude reporta o seu próprio custo exato; para o Codex e o Gemini, o Specrails estima o custo a partir de uma tabela de preços incorporada, por isso os valores são aproximações próximas e não montantes faturados.
+
+## Resolução de problemas
+
+- **Um provider que instalei não aparece.** Confirme que o CLI está no seu `PATH` (experimente `claude --version` / `codex --version` / `gemini --version` num terminal novo). A app sonda os CLIs dos providers através do `PATH` do seu sistema.
+- **Os servidores MCP do Codex não carregam no chat.** O Codex lê os servidores MCP a partir do `~/.codex/config.toml` global — registe-os aí com `codex mcp add`.
+- **Desativar em emergência.** Um provider pode ser desligado em toda a app através de uma variável de ambiente (`SPECRAILS_CODEX_BETA=0` ou `SPECRAILS_GEMINI_BETA=0`). Isto só esconde o provider da *seleção*; raramente é necessário.
+
+## Ver também
+
+Os guias dedicados a cada provider aprofundam cada CLI: o guia do Codex e o guia do Gemini cobrem cada um a configuração, o que funciona e as particularidades específicas de cada provider.

package/docs/guide/pt/integrations/2-plugins.md

@@ -0,0 +1,44 @@
+# Plugins (Integrações)
+
+A secção **Integrações** é um marketplace por projeto de extras opcionais que ampliam o que a IA consegue fazer. Cada projeto decide de forma independente que plugins quer — instalar um plugin num projeto nunca afeta outro.
+
+Os plugins funcionam registando discretamente um **servidor MCP** (Model Context Protocol) no seu projeto, dando à IA novas ferramentas para invocar durante rails e chat. Não precisa de perceber de MCP para os usar — instale-os e ficam disponíveis na próxima vez que um rail correr.
+
+## O que está disponível hoje
+
+Esta versão inclui **apenas plugins incorporados**: os plugins que pode instalar são os que vêm integrados na app. Não há registo remoto, nem plugins carregados por utilizadores, nem carregamento de código de terceiros — por isso tudo o que está no catálogo é verificado e distribuído com o Specrails.
+
+O plugin de destaque é:
+
+- **Serena** — navegação semântica de código. Dá à IA uma compreensão da sua base de código apoiada por um language server (saltar para a definição, encontrar referências, pesquisa consciente de símbolos) em vez de uma simples correspondência de texto. Ótimo para repositórios maiores ou desconhecidos onde quer que o agente raciocine sobre símbolos reais.
+
+  O Serena requer a ferramenta `uv` no seu `PATH` (corre via `uvx`). A app deteta automaticamente se o `uv` está presente e avisa-o caso esteja em falta.
+
+## Instalar um plugin
+
+1. Abra **Integrações** a partir da barra lateral direita.
+2. Encontre o plugin no catálogo. Cada cartão mostra um estado: **Não instalado**, **Instalado**, **Degradado** ou **Órfão**.
+3. Clique no plugin para **pré-visualizar a instalação** — isto mostra-lhe exatamente que ficheiros vão mudar antes de qualquer coisa acontecer.
+4. Clique em **Instalar**. Verá o progresso em tempo real à medida que tudo é configurado.
+
+Nos bastidores, a instalação é *cirúrgica e aditiva*: só acrescenta as suas próprias entradas ao `.mcp.json` do seu projeto (e, para alguns plugins, um ficheiro de fragmento no namespace protegido `.claude/agents/`). Nunca reescreve a sua configuração por inteiro, e adicionar um segundo plugin nunca pode perturbar o primeiro. Se a instalação não conseguir verificar-se como saudável, é revertida de forma limpa.
+
+## Gerir plugins instalados
+
+- **Saúde.** Cada plugin tem uma verificação de saúde a pedido. Um plugin que instala bem mas que mais tarde não consegue arrancar é marcado como **Degradado** — não bloqueia os seus rails, apenas verá o selo e um motivo.
+- **Desinstalar.** Remover um plugin elimina cirurgicamente apenas as entradas que lhe pertencem, deixando o resto da sua configuração intacto.
+- **Órfãos.** Se os ficheiros de um plugin ficarem para trás sem o estado adequado (por exemplo, após uma alteração interrompida), aparece como **Órfão** e pode limpá-lo com um clique.
+
+## Como os plugins surgem no seu trabalho
+
+- **Rails.** Antes de um rail correr, o Specrails verifica quais os plugins instalados e saudáveis e disponibiliza essas ferramentas ao agente para esse trabalho. Um plugin degradado é simplesmente ignorado nessa execução — o rail é lançado normalmente. Cada trabalho regista um instantâneo de quais os plugins que estavam ativos, que pode consultar na exportação de diagnóstico do trabalho.
+- **Chat.** O chat recolhe automaticamente a configuração MCP do seu projeto, por isso os plugins instalados também ficam disponíveis aí.
+- **Configuração.** Os plugins são ignorados enquanto um projeto ainda está a ser configurado — entram em ação assim que o projeto fica pronto.
+
+## Notas sobre providers
+
+Os plugins têm consciência do provider. O Serena e plugins MCP semelhantes resolvem-se para providers que registam MCP através do `.mcp.json` do projeto (Claude e Gemini). Para projetos Codex, os servidores MCP são geridos através da própria configuração global do Codex, por isso as entradas de plugins em **Integrações** são filtradas em conformidade. O cartão do Jira em Integrações é agnóstico ao provider e aparece para toda a gente — consulte o guia do Jira.
+
+## Ficheiros reservados
+
+Os plugins gerem um conjunto pequeno e bem definido de ficheiros no seu projeto: o seu `.mcp.json` (fundido cirurgicamente), algum estado em `.specrails/plugins/` e fragmentos de agente por plugin em `.claude/agents/custom-<plugin>.md`. Estes são ativos de equipa que pode versionar se quiser partilhar uma integração com os seus colegas — a app nunca os sobrescreve às cegas.

package/docs/guide/pt/integrations/3-jira-integration.md

@@ -0,0 +1,71 @@
+# Integração com o Jira
+
+Quer que as suas specs vivam num **quadro Jira** real em vez de dentro do Specrails? A integração com o Jira apoia as specs de um projeto em issues do Jira, mantém os estados sincronizados à medida que os rails correm e fica fora do caminho no resto do tempo. Cada projeto sincroniza com **o seu próprio** quadro Jira.
+
+## Como funciona (a versão curta)
+
+O Specrails atua como uma **camada de sincronização** entre o Jira e o seu projeto. A ideia central: o seu repositório local de specs continua a ser a fonte canónica que o pipeline lê, e o Specrails é responsável por mantê-lo de acordo com o Jira.
+
+- Quando lança um rail, o Specrails move a issue Jira associada para **Em curso**.
+- Quando um trabalho termina, o Specrails transita a issue (para **Concluído**, ou de volta para **A fazer** se falhar) e publica um comentário de conclusão com o id do trabalho, o custo e a duração.
+- Periodicamente, o Specrails faz **polling** ao Jira em busca de alterações que alguém tenha feito no quadro e reflete-as de volta nas suas specs.
+
+Todas as escritas de retorno passam por uma fila de saída (outbox) durável e resistente a falhas, por isso um soluço momentâneo do Jira nunca quebra um trabalho — a atualização simplesmente volta a tentar.
+
+## Conectar um quadro
+
+Conecta-se a partir da página **Definições** de um projeto (há também um passo opcional "Configurar Jira" no final do assistente de Adicionar Projeto). O assistente de ligação guia-o através de:
+
+1. **Testar** — introduza o URL e as credenciais do seu Jira, e o Specrails verifica a ligação.
+2. **Escolher um projeto** — escolha com que projeto Jira sincronizar.
+3. **Mapa de estados (opcional)** — associe os estados do seu fluxo de trabalho Jira aos estados do Specrails, caso a deteção automática precise de uma ajuda (mais abaixo).
+4. **Conectar** — feito. As suas specs passam a espelhar esse quadro.
+
+### Autenticação
+
+Esta versão usa autenticação por **colar token** — rápida, no dispositivo e sem qualquer backend envolvido:
+
+- **Jira Cloud:** o e-mail da sua conta mais um token de API.
+- **Jira Data Center / Server:** um Personal Access Token (PAT).
+
+O seu token é armazenado **cifrado na sua própria máquina** e nunca a abandona. A app mostra apenas se um token está presente, nunca o token em si.
+
+## Mapeamento de estados
+
+A parte mais complicada de qualquer sincronização com o Jira é fazer corresponder *o seu* fluxo de trabalho aos estados simples do Specrails (A fazer / Em curso / Concluído, mais as variantes de cancelar/concluir). O Specrails resolve isto em dois níveis:
+
+1. **O seu mapa de estados explícito**, se definir um no assistente — ganha sempre.
+2. **Deteção automática** a partir da categoria de cada estado (novo / em curso / concluído) mais uma correspondência inteligente para estados do tipo cancelar e concluir.
+
+Quando precisa de mover uma issue ao longo de um fluxo de trabalho com transições condicionadas, encontra um caminho válido passo a passo e preenche quaisquer campos obrigatórios (como uma resolução) pelo caminho. Se um estado for genuinamente inalcançável, a operação fica em espera como dead-letter e é-lhe apresentada em vez de falhar silenciosamente — verá um indicador **degradado** e pode tentar de novo.
+
+## Hot-swap: ligar e desligar com segurança
+
+A ligação ao Jira é **por spec**, capturada no momento em que lança um rail — não é um interruptor global de tudo ou nada no quadro. Isso torna-a segura de alternar:
+
+- **Ativar ou desativar** a integração nunca muda de casa as suas specs existentes.
+- **Desligar** repõe o seu projeto no comportamento normal de specs locais.
+- As specs que já têm uma ligação ao Jira mantêm a sua escrita de retorno; as que não têm ficam intocadas.
+
+Por isso pode experimentar à vontade — ligue, corra uns quantos rails, desligue — sem baralhar o seu quadro nem as suas specs locais.
+
+## No dia a dia
+
+Uma vez conectada, a página de Definições do projeto mostra um **cartão de ligação** onde pode:
+
+- **Sincronizar agora** — forçar um polling imediato em vez de esperar pelo temporizador.
+- **Tentar dead-letters de novo** — voltar a correr quaisquer escritas de retorno que tenham ficado presas.
+- **Toggle de hot-swap** — pausar/retomar temporariamente a integração.
+- **Desligar** — desassociar o quadro de forma limpa.
+
+As specs apoiadas no Jira mostram um **selo com a chave Jira** (como `PROJ-123`) no seu cartão, e ao clicar nele segue de volta para a issue. Também receberá pequenas notificações quando uma sincronização termina, quando um token de autenticação expira (para que o possa renovar) ou quando a integração entra num estado degradado.
+
+## Coisas a ter em mente
+
+- **Polling, não webhooks.** Como o Specrails corre localmente, faz polling ao Jira em busca de alterações em vez de receber notificações push. As alterações aparecem dentro do intervalo de polling, não instantaneamente.
+- **Um quadro por projeto.** Projetos diferentes podem sincronizar com quadros diferentes; um único projeto sincroniza com exatamente um.
+- **Em conflitos, vence a última escrita** para o caso raro de dois separadores editarem o mesmo rascunho em simultâneo.
+
+## Desligar
+
+Se alguma vez quiser recuar por completo, basta **Desligar** nas Definições. As suas specs voltam ao comportamento apenas local, e os metadados do Jira ficam simplesmente sem uso — nada é destruído.

package/docs/guide/pt/integrations/4-mobile-companion.md

@@ -0,0 +1,38 @@
+# A app companion para telemóvel
+
+O Specrails tem uma app companion para telemóvel para que possa ficar de olho nos seus rails enquanto está longe da secretária — ver trabalhos a correr, vê-los terminar e manter-se a par sem estar sentado em frente ao painel.
+
+## Para que serve
+
+A companion é uma superfície de **monitorização**. Liga-se à sua app de ambiente de trabalho Specrails em execução através da sua rede local e espelha a atividade ao vivo de projetos e trabalhos para o seu telemóvel. Pense nela como uma janela de relance para os mesmos rails que de outra forma veria no painel.
+
+## Emparelhar o telemóvel
+
+O emparelhamento assenta num **código QR** para que não tenha de escrever nada de complicado:
+
+1. Certifique-se de que a sua app de ambiente de trabalho Specrails está em execução e de que o seu telemóvel está na **mesma rede local** (mesmo Wi-Fi).
+2. Na app de ambiente de trabalho, abra o ecrã de emparelhamento para mostrar um código QR.
+3. Na app companion do seu telemóvel, leia esse código.
+4. O telemóvel descobre a app de ambiente de trabalho na rede e liga-se.
+
+A partir daí a companion mantém uma ligação ao vivo e transmite listas de projetos e atualizações de trabalhos à medida que acontecem.
+
+## Como funciona a ligação
+
+A app de ambiente de trabalho anuncia-se na sua rede local para que o telemóvel a encontre, e o código QR transporta os detalhes de que o telemóvel precisa para se ligar com segurança. Tudo permanece na sua rede local — a companion fala diretamente com a sua máquina, não através de qualquer serviço na cloud.
+
+Como assenta na rede local, os dois dispositivos precisam de conseguir alcançar-se. Se o emparelhamento não funcionar:
+
+- Confirme que ambos os dispositivos estão no **mesmo Wi-Fi** (e que a rede não isola os clientes uns dos outros).
+- Certifique-se de que a app de ambiente de trabalho está **em execução** quando lê o código.
+- Volte a abrir o ecrã de emparelhamento para atualizar o código QR e tente ler de novo.
+
+## O que vai ver
+
+Uma vez emparelhada, a companion apresenta os seus projetos e a respetiva atividade de trabalhos ao vivo, dando-lhe as mesmas atualizações de rails em tempo real que chegam ao painel de ambiente de trabalho — enviadas para o seu telemóvel à medida que ocorrem. É a forma mais fácil de saber o momento exato em que um rail de longa duração termina.
+
+## Bom saber
+
+- **Monitorização em primeiro lugar.** A companion foi pensada para acompanhar os rails, não para conduzir todo o fluxo de trabalho de ambiente de trabalho a partir do telemóvel.
+- **Apenas local.** Sem conta, sem relé na cloud — a sua máquina e o seu telemóvel, na sua rede.
+- **Mantenha o ambiente de trabalho acordado.** A companion espelha uma app de ambiente de trabalho em execução; se a sua máquina adormecer ou a app fechar, as atualizações ao vivo ficam em pausa até voltar.

package/docs/guide/pt/pipeline/1-rails-and-jobs.md

@@ -0,0 +1,94 @@
+# Rails e jobs
+
+Já tem specs no quadro. É aqui que elas se transformam em código. Um **rail** é a faixa que conduz uma spec por todo o pipeline — Architect → Developer → Reviewer → Ship — executando agentes de IA reais dentro da diretoria do seu projeto. Esta página cobre o lançamento de um rail, a fila de jobs e como acompanhar o trabalho a acontecer ao vivo.
+
+## O que é um rail
+
+Imagine o seu ecrã dividido em dois:
+
+```
+SpecsBoard (esquerda)       Rails (direita)
+─────────────────           ─────────────────
+#1 Login flow      ─┐
+#2 Webhook retry    │  arrastar para
+#3 Cost limits      │ ────────────►   Rail 1   ▶ Play
+#4 Audit log        │
+                    └────────────►   Rail 2   ▶ Play
+```
+
+Um rail é uma **faixa de execução**. Arrasta um cartão de spec do SpecsBoard para um rail e depois carrega em **▶ Play**. O rail lança o pipeline e trabalha a spec de ponta a ponta, mesmo na diretoria de trabalho do seu projeto — editando ficheiros, correndo testes, tudo.
+
+Pode ter vários rails para organizar o trabalho em faixas com nome (uma para a feature em que está focado, outra em fila atrás dela). Mais sobre múltiplos rails e batches em [Batch implement e multi-feature](batch-implement-and-multi-feature).
+
+## Lançar um rail sobre uma spec
+
+1. **Arraste um cartão de spec** do SpecsBoard para um rail. O ID da spec aparece na lista de specs do rail. (Prefere não arrastar? Use o popover **Mover para um rail** no cartão de spec — mostra um ponto de estado por rail para que não largue trabalho numa faixa ocupada.)
+2. **Escolha um modo** se quiser algo diferente do default — o controlo segmentado no cabeçalho do rail oferece `Implement`, `Batch` e (apenas rails Claude) `Ultra`.
+3. **Carregue em ▶ Play.**
+
+É só isto. O rail arranca um processo de CLI de IA no seu projeto e inicia o pipeline.
+
+### O que há no cabeçalho de um rail
+
+| Controlo | O que faz |
+|---------|--------------|
+| **Pílula de estado** | `idle`, `running` ou `failed`. Não há um "completed" separado — um rail volta a `idle` quando o seu job termina sem problemas. |
+| **Lista de specs** | Os IDs atribuídos a este rail. Arraste mais para dentro, arraste para fora para os desligar. |
+| **Controlo de modo** | `Implement` / `Batch` / `Ultra` — veja a tabela abaixo. Guardado por rail. |
+| **Seletor de perfil** | Que perfil de agentes corre (apenas rails Claude). Só aparece quando o projeto tem pelo menos um perfil. |
+| **Seletor de motor** | Que fornecedor instalado corre este rail — Claude, Codex ou Gemini. Só aparece quando o projeto tem mais do que um fornecedor. Veja [Escolher um motor por rail](picking-an-engine-per-rail). |
+| **▶ Play / ■ Stop** | Iniciar ou cancelar. |
+
+### Os três modos de rail
+
+| Modo | Comando | O que faz |
+|------|---------|--------------|
+| **Implement** | `/specrails:implement` | Um único job que cobre todas as specs do rail. Corre o pipeline completo Architect → Developer → Reviewer → Ship. O default do dia a dia. |
+| **Batch** | `/specrails:batch-implement` | Um único job que trabalha as specs do rail sequencialmente, em ondas que respeitam as dependências. Ideal para várias specs relacionadas. |
+| **Ultra** | Ultracode | O Claude implementa cada spec de forma autónoma, **ignorando** o pipeline. Um job independente por spec. Só Claude. |
+
+O Ultra é o caso à parte: salta a cadeia de agentes e entrega ao Claude a spec em bruto para trabalhar com as suas ferramentas nativas. É aberto, por isso carregar em Play abre primeiro uma confirmação, e um seletor de modelo por rail deixa-o escolher Haiku / Sonnet / Opus. Só aparece quando o motor do rail é o Claude.
+
+## A fila de jobs
+
+Sempre que carrega em Play, a execução do rail torna-se um **job**. A regra mais importante para interiorizar:
+
+> **Um job de cada vez, por projeto.** Cada projeto tem uma única fila. Dentro de um projeto, só um job de rail corre de cada vez — os restantes ficam em fila atrás dele e arrancam automaticamente à medida que se libertam slots.
+
+Isto surpreende quem adiciona três rails à espera de que corram em paralelo. Não correm — não dentro do mesmo projeto. Adicionar rails *organiza* o seu trabalho em faixas; não faz com que essas faixas corram em simultâneo.
+
+**O paralelismo real é entre projetos.** Cada projeto tem a sua fila independente, por isso um rail no Projeto A e um rail no Projeto B correm ao mesmo tempo sem disputar recursos. Quer mais throughput? Abra mais projetos.
+
+Não há um botão global de concorrência para afinar. O único limitador automático é baseado no orçamento: se definiu um orçamento diário (do projeto ou da app), a fila pausa automaticamente assim que o gasto desse dia atinge o limite.
+
+## Acompanhar a execução
+
+Encontra todos os jobs em **Jobs**, na barra lateral direita do projeto — uma lista de cartões, do mais recente para o mais antigo. Cada cartão mostra um selo de estado, o selo do perfil, um selo de prioridade, a duração, o custo e o comando lançado. Por cima da lista:
+
+- **Chips de filtro por estado** — mostram apenas os jobs num dado estado.
+- **Filtro por intervalo de datas** — restringe a uma janela temporal.
+- **Comparar** — escolhe dois jobs e vê-os lado a lado.
+
+Clique em qualquer cartão para abrir a **vista de detalhe do job**, onde vivem o log em streaming ao vivo e as métricas ao vivo. É a próxima página: [A vista de detalhe do job](the-job-detail-view).
+
+## Cancelar um job
+
+Carregue em **■ Stop** no cabeçalho do rail. A app envia `SIGTERM` ao subprocesso, espera **5 segundos** por uma saída limpa e depois faz `SIGKILL`. Nada fica criado pela metade.
+
+## Se um rail não arrancar
+
+Se escolher um motor cuja CLI não está instalada na sua máquina, o lançamento **falha de imediato** em vez de iniciar um job partido — nada é criado. Instale a CLI do fornecedor em falta ([Usar o Codex](../integrations/using-codex), [Usar o Gemini](../integrations/using-gemini)) e lance de novo. A falta de Claude ou Codex devolve uma mensagem precisa "*<provider> CLI not found*"; a falta de Gemini mostra hoje um erro de lançamento genérico, mas o resultado é o mesmo.
+
+## Parar tudo
+
+Se algo parecer errado:
+
+- **Um rail** — carregue em **■ Stop** no seu cabeçalho.
+- **Auto-pausa por orçamento** — defina um orçamento diário e a fila pausa-se a si própria quando o gasto desse dia atinge o limite.
+- **Tudo** — feche a app desktop, ou execute `specrails-desktop stop`.
+
+## Para onde ir a seguir
+
+- [A vista de detalhe do job](the-job-detail-view) — fases, métricas ao vivo, cartões de ticket.
+- [Batch implement e multi-feature](batch-implement-and-multi-feature) — correr várias specs ao mesmo tempo.
+- [Escolher um motor por rail](picking-an-engine-per-rail) — Claude vs Codex vs Gemini.

package/docs/guide/pt/pipeline/2-the-job-detail-view.md

@@ -0,0 +1,90 @@
+# A vista de detalhe do job
+
+Clique em qualquer cartão de job na página **Jobs** e chega aqui: o cockpit de uma única execução de rail. Foi construída em torno de uma promessa — **os números ao vivo que vê são reais, nunca estimativas.** Esta página percorre as fases, as métricas ao vivo e os cartões de ticket.
+
+## O layout
+
+Dois painéis ficam por cima do log completo em streaming:
+
+```
+┌─────────────────────────────────────────────┐
+│  Cabeçalho de estado  (ícone · duração · …) │
+├─────────────────────────────────────────────┤
+│  Cabeçalho de tickets  ( #12  #14  #15 )    │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Log em streaming  (auto-scroll · pesquisa) │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## Fases do pipeline
+
+Para os jobs `Implement` e `Batch`, a execução percorre as fases definidas pelo slash command — por default:
+
+```
+Architect ──► Developer ──► Reviewer ──► Ship
+```
+
+Cada fase é um agente especializado que o motor do rail invoca na diretoria do seu projeto:
+
+| Fase | Agente | O que faz |
+|-------|-------|--------------|
+| **Architect** | `sr-architect` | Planeia a implementação. |
+| **Developer** | `sr-developer` | Escreve o código. |
+| **Reviewer** | `sr-reviewer` | Revê o resultado. |
+| **Ship** | (varia) | Finalização: testes, commit, rascunho de PR. |
+
+Que agente trata de cada fase é decidido pelo **perfil de agentes** do projeto. O trio base (`sr-architect`, `sr-developer`, `sr-reviewer`) está sempre presente; as regras de encaminhamento de um perfil podem acrescentar agentes ou trocar qual deles corre uma fase. A barra de progresso das fases só aparece quando o comando define mesmo fases — os jobs Ultracode (que ignoram o pipeline) não mostram nenhuma.
+
+## Métricas ao vivo — honestas por princípio
+
+O cabeçalho de estado é a manchete. Mostra um ícone de estado, uma linha de atividade a descrever o que o job está a fazer *neste momento*, uma contagem dos passos dados e uma fila de métricas:
+
+| Métrica | Quando vê o valor real |
+|--------|------------------------------|
+| **Duração** | **Ao vivo.** Um contador de 1 segundo vai subindo enquanto o job corre — este é o único número genuinamente ao vivo. |
+| **Turnos** | Derivados incrementalmente dos eventos de assistant transmitidos à medida que chegam. |
+| **Tokens** | Agregados incrementalmente a partir do mesmo stream (tolerante a eventos sem campos de uso). |
+| **Custo** | Mostrado como `—` até o job terminar, e depois revelado como o valor autoritativo `total_cost_usd`. |
+
+O princípio de design: **nada de números aproximados ou estimados a meio da execução.** A duração é real porque não passa de um relógio. Turnos e tokens são acumulados a partir de atividade realmente transmitida. O custo *não* é estimado de propósito durante a execução — aparece como pendente e só passa ao seu valor final e autoritativo quando o fornecedor o reporta na saída do job. Se um número parecer estar à espera, é intencional — está a ver a verdade, não uma projeção.
+
+A etiqueta e o ícone do cabeçalho correspondem ao estado do job, e o painel é renderizado para jobs `running`, `completed` e `failed` por igual — por isso a vista de detalhe de um job terminado mostra as mesmas métricas congeladas nos seus valores finais.
+
+## Os cartões de ticket
+
+O **cabeçalho de tickets** fica entre o cabeçalho de estado e o log. É um cartão de identidade premium que mostra um chip por cada spec que o job tocou — correspondidos a partir do comando lançado, por isso reflete exatamente quais os tickets de que esta execução tratou.
+
+- **2–3 tickets** — mostrados como uma lista de chips.
+- **4 ou mais** — colapsam num modo compacto `+ N more` com um chevron para expandir, para o cabeçalho ficar arrumado.
+
+Clicar num chip abre o detalhe dessa spec **por cima da página do job** — não perde o seu lugar nem muda de rota. É uma forma rápida de reler o que um job deve entregar enquanto o vê trabalhar. (Em ecrãs com largura de tablet pode até arrastar uma modal de ticket para o lado e comparar duas specs lado a lado.)
+
+## O log em streaming
+
+Por baixo dos painéis fica o log completo da execução, transmitido em tempo real pelo WebSocket:
+
+- **Auto-scroll** mantém o output mais recente à vista (faça scroll para cima e pausa, para poder ler).
+- **Pesquisa** para saltar para uma frase.
+- **Copiar** para agarrar o log inteiro.
+
+Esta é a verdade crua do que a IA está a fazer — cada chamada de ferramenta, cada edição de ficheiro, cada execução de teste.
+
+## Exportação de diagnóstico
+
+Se a [telemetria](../settings/customizing) estava ativada para o job, aparece um botão **Exportar diagnóstico** no cabeçalho. Descarrega um ZIP que contém:
+
+- `job-metadata.json` — comando, estado, perfil, plugins.
+- `telemetry.ndjson` — sinais OTLP/JSON não comprimidos.
+- `logs.txt` — o log completo em streaming.
+- `summary.md` — destaques legíveis por humanos.
+- `profile.json`, `plugins.json` — snapshots exatos do que correu (quando presentes).
+
+Útil para partilhar uma execução com um colega de equipa, ou para abrir um relatório de bug preciso.
+
+## Para onde ir a seguir
+
+- [Rails e jobs](rails-and-jobs) — lançar e enfileirar.
+- [Batch implement e multi-feature](batch-implement-and-multi-feature) — muitas specs, ondas de dependências.
+- [Acompanhar o custo](../analytics/tracking-cost) — transformar os custos por job em analytics do projeto.