specrails-desktop 2.8.0 → 2.9.1

package/docs/guide/pt/pipeline/3-batch-implement-and-multi-feature.md

@@ -0,0 +1,78 @@
+# Batch implement e multi-feature
+
+Uma spec de cada vez está bem, mas muito do trabalho real vem em conjuntos — uma feature mais os seus testes mais a sua migração, ou um backlog que quer despachar numa só sessão. Esta página cobre correr várias specs em conjunto: o modo Batch, as ondas de dependências e como o pipeline impede que trabalho concorrente colida.
+
+## Correr várias specs ao mesmo tempo
+
+A forma mais simples de correr um monte de specs a partir de um rail é o modo **Batch**:
+
+1. **Arraste todas as specs** que quer para um único rail. Empilham-se na lista de specs desse rail.
+2. **Mude o modo do rail para Batch** (o controlo segmentado no cabeçalho do rail).
+3. **Carregue em ▶ Play.**
+
+O rail lança **um** job `/specrails:batch-implement` que trabalha cada spec atribuída. Monitorize-o como qualquer outro job na página Jobs — é um único job que cobre todo o conjunto, não um job por spec.
+
+Isto importa por causa da **fila de um job por projeto**. Como um projeto só corre um job de rail de cada vez, o modo Batch é também a forma mais limpa de *encadear* uma lista de specs sem andar a fazer malabarismo com vários rails e à espera que cada um esvazie.
+
+### Implement vs Batch — que modo?
+
+| | **Implement** | **Batch** |
+|---|---|---|
+| Comando | `/specrails:implement` | `/specrails:batch-implement` |
+| Specs por job | Todas as do rail, tratadas como uma unidade de trabalho | Todas as do rail, trabalhadas **sequencialmente** |
+| Ideal para | Uma alteração fortemente acoplada | Várias features distintas que quer despachar por ordem |
+| Ordenação | n/a | Ondas que respeitam as dependências (ver abaixo) |
+
+Se as specs são realmente uma só alteração, use **Implement**. Se são uma lista de features separadas, use **Batch** e deixe-o sequenciá-las.
+
+## Ondas de dependências
+
+O modo Batch não corre as specs simplesmente de cima para baixo — calcula uma **ordem de execução que respeita as dependências** e agrupa as specs em *ondas*. O orquestrador (`/specrails:batch-implement`) descobre quais specs dependem de quais e depois agenda-as de forma a que nada corra antes do trabalho em que assenta.
+
+Conceptualmente:
+
+```
+Onda 1:  #2 (modelo de dados)     ← sem dependências, corre primeiro
+Onda 2:  #4 (API sobre o modelo)  ← espera por #2
+         #5 (CLI sobre o modelo)  ← espera por #2
+Onda 3:  #7 (docs sobre tudo)     ← espera por #4 e #5
+```
+
+Dentro do job, as specs de cada onda são implementadas antes de a onda seguinte começar. Não configura isto à mão — o orquestrador deriva as ondas a partir das próprias specs. Veja-o desenrolar-se na [vista de detalhe do job](the-job-detail-view): o log em streaming narra em que spec o batch está, e o cabeçalho de tickets mostra todas as specs que o job tocou.
+
+## Isolamento por worktree
+
+Quando várias specs são implementadas numa só execução, o pipeline mantém cada unidade de trabalho isolada para que alterações concorrentes ou sequenciais não pisem os ficheiros umas das outras. O orquestrador de batch corre a implementação de cada spec no seu próprio contexto de trabalho limpo e depois integra os resultados — por isso uma spec a meio nunca deixa a sua árvore num estado intermédio partido visível para a seguinte.
+
+Na prática isto significa:
+
+- Cada spec recebe um ponto de partida limpo para implementar, em vez de herdar as edições em curso da spec anterior a meio do processo.
+- As revisões e os passos de ship operam sobre um snapshot coerente, não sobre um alvo em movimento.
+- Uma falha numa onda fica contida — não corrompe em silêncio as specs que já foram entregues.
+
+A app regista, por job, exatamente que ficheiros foram tocados e qual ticket os tocou (vai ver isto surgir como chips de proveniência na secção **Code** e como uma lista "Ficheiros tocados por este ticket" na modal de detalhe de cada spec). É essa atribuição que lhe permite confiar numa execução com várias specs: pode sempre rastrear uma alteração de ficheiro até à spec que a causou.
+
+## Multi-feature entre projetos
+
+Se quiser paralelismo genuíno — duas grandes features a construir ao mesmo tempo — divida-as **entre projetos**, não entre rails de um mesmo projeto. Cada projeto tem a sua fila independente, por isso:
+
+```
+Projeto A   ▶ Rail a correr a feature X   ┐
+                                          ├─ correm em simultâneo
+Projeto B   ▶ Rail a correr a feature Y   ┘
+```
+
+Não há limite global de concorrência nem disputa entre projetos. Abra os dois, lance um rail em cada e progridem juntos. O único limitador partilhado é o seu limite de orçamento, que pausa as filas por projeto ou da app inteira assim que o gasto do dia atinge o limite.
+
+## Dicas para batches grandes
+
+- **Agrupe specs relacionadas num só rail** antes de mudar para Batch — as ondas de dependências só veem o que está nesse rail.
+- **Defina um orçamento diário** antes de um batch grande para que uma execução inesperadamente cara faça auto-pausa em vez de descontrolar-se. Configure-o em [Orçamento](../settings/customizing).
+- **Use o botão Comparar** na página Jobs depois para comparar duas execuções de batch lado a lado.
+- **Exporte um diagnóstico** (se a telemetria estava ligada) para obter o snapshot exato de perfil + plugins de todo o batch.
+
+## Para onde ir a seguir
+
+- [Rails e jobs](rails-and-jobs) — o modelo da fila em detalhe.
+- [A vista de detalhe do job](the-job-detail-view) — ver um batch a correr ao vivo.
+- [Escolher um motor por rail](picking-an-engine-per-rail) — note que o Batch corre em qualquer fornecedor; o Ultra é só Claude.

package/docs/guide/pt/pipeline/4-picking-an-engine-per-rail.md

@@ -0,0 +1,60 @@
+# Escolher um motor por rail
+
+O Specrails desktop trata o **Claude Code**, o **Codex CLI** e o **Gemini CLI** como motores de primeira classe. Um projeto pode ter um, dois ou os três instalados — e quando há mais do que um, escolhe que motor corre cada rail. Esta página cobre o seletor de motor por rail e quando recorrer a cada um.
+
+## Quando o seletor aparece
+
+O **seletor de motor** vive no cabeçalho do rail, mesmo ao lado do controlo de modo. Só aparece quando o projeto tem **mais do que um** fornecedor instalado.
+
+> **Projetos com um só fornecedor comportam-se exatamente da mesma forma.** Se um projeto tem só um motor, não aparece nenhum seletor e nada muda na escolha de fornecedor — corre simplesmente nesse motor. O seletor existe puramente para projetos com vários fornecedores.
+
+Quando aparece, a sua escolha é **por rail e por lançamento** — rails diferentes podem correr motores diferentes, e a sua escolha é lembrada por projeto (assumindo por default o motor primário do projeto).
+
+## Como escolher um motor
+
+1. Certifique-se de que o seletor de motor do rail está visível (projeto com 2+ fornecedores).
+2. Clique nele e escolha **Claude**, **Codex** ou **Gemini**.
+3. Lance o rail com **▶ Play**.
+
+O motor selecionado corre todas as fases do pipeline desse rail. Se a CLI do motor escolhido não estiver instalada, o lançamento falha de imediato — nada é criado. Instale a CLI em falta e tente de novo.
+
+## Em que cada motor é bom
+
+Os três correm os pipelines standard **Implement** e **Batch**. Aqui fica um guia prático para escolher:
+
+| Motor | Recorra a ele quando… | Notas |
+|--------|--------------------|-------|
+| **Claude** | Quer o conjunto completo de funcionalidades: perfis de agentes, Ultracode, reporte de custo nativo, o suporte de ferramentas mais rico. O default para a maioria do trabalho. | O único motor que suporta **perfis de agentes**, **Ultracode** e algumas funcionalidades de spec exclusivas do Claude (Contract Layer, SMASH). |
+| **Codex** | Prefere o Codex CLI da OpenAI ou quer comparar implementações entre fornecedores. | `codex` ≥ 0.128.0. Sem reporte de custo nativo — a app preenche o custo a partir da sua tabela de preços. Os perfis não se aplicam. |
+| **Gemini** | Quer o Gemini CLI da Google, telemetria nativa ou uma execução mais barata para specs de rotina. | `gemini` ≥ 0.11.0 (defina `GEMINI_API_KEY`). Telemetria OTLP nativa. Os perfis não se aplicam. |
+
+### As funcionalidades exclusivas do Claude
+
+Algumas coisas só funcionam em rails Claude — escolha o Claude se precisar delas:
+
+- **Perfis de agentes** — encaminhamento de modelo por agente. Em rails Codex ou Gemini a execução usa sempre o modo legado e qualquer perfil selecionado é **ignorado**. O seletor de perfil fica escondido nos motores que não são Claude.
+- **Ultracode (modo `Ultra`)** — o modo autónomo que ignora o pipeline. O segmento `Ultra` e o seu seletor de modelo Haiku/Sonnet/Opus só aparecem quando o motor do rail é o Claude.
+- **Contract Layer e SMASH** — funcionalidades de refinamento de spec exclusivas do Claude (são opções de Add Spec, não opções de rail, mas aplica-se a mesma restrição).
+
+Se um projeto mistura motores, a barra lateral direita só mostra as secções que **todos** os fornecedores instalados suportam — por isso a secção **Agentes** desaparece por completo num projeto que inclua qualquer fornecedor que não seja Claude, porque os perfis são específicos do Claude.
+
+## Um fluxo de trabalho prático
+
+Os projetos com vários fornecedores brilham quando quer **comparar** ou **afinar custos**:
+
+- **Comparar implementações.** Ponha a mesma spec em dois rails, defina um com Claude e outro com Codex, lance ambos (entre projetos, ou um a seguir ao outro na fila do mesmo projeto) e depois use o botão **Comparar** na página Jobs para comparar os resultados.
+- **Afinar custos por spec.** Corra specs de alto risco no Claude com um perfil `max`; corra specs de limpeza de rotina no Gemini para poupar no gasto. Filtre `/analytics` por motor para ver a repartição.
+- **Defina um default sensato.** Defina o motor que mais usa como primário do projeto para que os rails assumam-no por default, e só mude por rail quando uma spec específica pedir outro.
+
+## Coisas a ter em conta
+
+- **A escolha de fornecedor é imutável depois de criar o projeto** (v1). Escolhe os fornecedores instalados ao adicionar o projeto; não há um toggle nas Definições para acrescentar ou remover um mais tarde.
+- **O custo é sempre acompanhado**, mesmo para motores sem reporte de custo nativo — a app recorre a uma tabela de preços para que as execuções de Codex e Gemini apareçam na mesma nas [analytics](../analytics/tracking-cost).
+- **O botão "Abrir CLI de IA" do terminal** também oferece um seletor de fornecedor em projetos com vários fornecedores, caso prefira conduzir uma CLI à mão.
+
+## Para onde ir a seguir
+
+- [Usar o Codex](../integrations/using-codex) — instalar e iniciar sessão.
+- [Usar o Gemini](../integrations/using-gemini) — instalar, `GEMINI_API_KEY`, telemetria.
+- [Rails e jobs](rails-and-jobs) — a fila e o fluxo de lançamento.
+- [Acompanhar o custo](../analytics/tracking-cost) — repartição de custo por motor.

package/docs/guide/pt/settings/1-themes.md

@@ -0,0 +1,37 @@
+# Temas
+
+Deixe o Specrails com a cara que mais gosta. A aplicação já vem com cinco temas cuidadosamente afinados, entre os quais pode alternar num instante — sem reiniciar, sem recompilar, sem nada para configurar.
+
+## Os cinco temas integrados
+
+| Tema | Sensação |
+| --- | --- |
+| **Specrails** | O predefinido. Equilibrado, sereno e fiel à marca. |
+| **Dracula** | O clássico roxo escuro. Suave para a vista à noite. |
+| **Aurora Light** | Um tema claro, leve e arejado para trabalhar de dia. |
+| **Obsidian Dark** | Modo escuro profundo, de alto contraste. |
+| **Matrix** | Verde sobre preto, para quando lhe apetece sentir que está dentro do mainframe. |
+
+## Como alternar
+
+1. Abra as **Definições** (a janela de definições de toda a aplicação).
+2. Vá à secção **Aspeto**.
+3. Escolha um tema. Aplica-se de imediato a toda a aplicação.
+
+É só isto. A mudança acontece no momento em que clica — a interface muda de visual ao vivo.
+
+## Onde se aplica
+
+A sua escolha de tema é **válida para toda a aplicação**, não por projeto. Todos os projetos, todas as páginas, todos os painéis seguem o mesmo tema. E chega até a sítios onde talvez não esperasse:
+
+- **O painel de terminal** muda de cores ao vivo, mantendo o histórico (scrollback) e qualquer sessão de shell em execução intactos.
+- **Os gráficos** da página de Análise mudam de tonalidade para combinar.
+- **O realce de sintaxe do código** no visualizador de Código também acompanha o tema.
+
+## Memoriza a sua escolha
+
+A sua seleção fica guardada na aplicação, por isso mantém-se entre reinícios. Para evitar aquele breve relâmpago de cores erradas quando a aplicação abre, o Specrails aplica o tema guardado antes mesmo de a interface acabar de carregar — para que tudo apareça certo já a partir do primeiro fotograma.
+
+## Uma nota para os curiosos
+
+Os temas assentam num pequeno conjunto de papéis de cor semânticos (uma cor de "acento", uma cor de "superfície", e por aí adiante) em vez de tonalidades fixas no código. É por isso que adicionar o próximo tema é fácil e por isso que cada tema se mantém internamente coerente — cada um apenas remapeia esses papéis. Não precisa de pensar em nada disto para usar o tema; é simplesmente a razão por que tudo parece tão fluido.

package/docs/guide/pt/settings/2-language.md

@@ -0,0 +1,39 @@
+# Idioma
+
+O Specrails fala a sua língua. A interface está totalmente traduzida em oito idiomas e, por predefinição, segue o idioma em que o seu computador está configurado — por isso, para a maioria das pessoas, aparece logo no idioma certo logo na primeira abertura.
+
+## Idiomas suportados
+
+- English
+- Español (Spanish)
+- Français (French)
+- Deutsch (German)
+- Português (Portuguese)
+- Italiano (Italian)
+- 中文 (Chinese)
+- 日本語 (Japanese)
+
+## Começa no idioma do seu sistema operativo
+
+A primeira vez que abre o Specrails, ele consulta as preferências de idioma do seu sistema operativo e faz a correspondência com o idioma suportado mais próximo. Se o seu Mac ou PC estiver configurado em espanhol, verá espanhol. Se estiver definido para uma variante regional (como `es-ES` ou `zh-Hans-CN`), o Specrails mapeia-a automaticamente para o idioma base correto.
+
+Não tem de fazer nada — e, se nunca mexer na definição de idioma, o Specrails continua a seguir o seu sistema operativo. Mude mais tarde o idioma do computador e o Specrails acompanha.
+
+## Escolher um idioma manualmente
+
+Quer algo diferente do idioma predefinido do seu sistema operativo? Escolha-o explicitamente:
+
+1. Abra as **Definições**.
+2. Vá à secção **Idioma**.
+3. Escolha o seu idioma.
+
+A mudança é **instantânea** — toda a interface volta a renderizar no novo idioma sem reiniciar. Assim que faz uma escolha explícita, o Specrails memoriza-a e deixa de seguir o sistema operativo, por isso a sua preferência é respeitada sempre que abre a aplicação.
+
+## O que é traduzido
+
+Tudo o que lê na interface — botões, etiquetas, mensagens de estado, títulos de páginas, caixas de diálogo. As datas também se adaptam ao idioma escolhido, ficando formatadas da maneira que esse idioma espera.
+
+## É bom saber
+
+- **O inglês é o idioma de origem.** Se uma funcionalidade novíssima chegar antes de a sua tradução estar concluída, poderá ver pontualmente uma etiqueta em inglês aqui ou ali — será traduzida numa atualização seguinte.
+- A sua escolha de idioma é **válida para toda a aplicação**, igual em todos os seus projetos.

package/docs/guide/pt/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -0,0 +1,46 @@
+# Telemetria do pipeline e diagnóstico
+
+Quando um job do pipeline não corre como esperava, a telemetria dá-lhe um registo detalhado, dos bastidores, do que a CLI de IA fez de facto. Está **desativada por omissão** e é totalmente opcional, por projeto — ative-a apenas quando quiser.
+
+## O que é
+
+A telemetria capta sinais de diagnóstico estruturados (traces, métricas e logs) emitidos pela CLI de IA enquanto executa um job do pipeline. Pense nela como a caixa-preta das suas execuções de pipeline: tempos, uso de tokens e atividade passo a passo, capturados localmente para poder inspecionar um job depois do facto.
+
+Assenta no **OpenTelemetry**, um formato aberto e padronizado — por isso os dados não ficam presos numa caixa proprietária.
+
+## Como ativar
+
+A telemetria é configurada **por projeto**:
+
+1. Abra a página de **Definições** do projeto (a rota de definições por projeto).
+2. Encontre o interruptor **Telemetria do pipeline**.
+3. Ligue-o.
+
+A partir desse momento, os jobs do pipeline desse projeto passam a registar telemetria. Os outros projetos não são afetados — cada projeto decide por si.
+
+### O que é abrangido
+
+A telemetria aplica-se aos **jobs do pipeline** (as execuções em rail Architect → Developer → Reviewer → Ship que estão em fila). Sessões interativas como o chat e o assistente de configuração ficam intencionalmente de fora — a telemetria destina-se às execuções de pipeline repetíveis e inspecionáveis, não a conversas pontuais.
+
+## Onde ficam os dados
+
+Tudo fica na sua máquina, dentro da sua pasta pessoal (`~/.specrails/`) — nunca no seu repositório. As gravações em bruto são guardadas comprimidas junto do respetivo job, e as gravações mais antigas são automaticamente condensadas em resumos compactos ao fim de uma semana para manter tudo arrumado. Nunca precisa de gerir nada disto à mão.
+
+## Exportar um pacote de diagnóstico
+
+A coisa mais útil que a telemetria desbloqueia é a **exportação de diagnóstico** — um único ZIP que empacota tudo sobre um job para resolução de problemas ou partilha.
+
+Quando um job tem telemetria registada, surge um **botão de exportação** no respetivo cartão de job. Clique nele para descarregar um ZIP que contém:
+
+- **`job-metadata.json`** — a identidade e os parâmetros do job
+- **`telemetry.ndjson`** — os sinais registados em bruto
+- **`logs.txt`** — a saída de logs capturada
+- **`summary.md`** — um resumo legível da execução
+
+Se o projeto usar plugins, o pacote inclui também um instantâneo de quais plugins estavam ativos nesse job.
+
+Este é o pacote a obter quando quer perceber uma execução complicada, guardar um registo ou entregar os detalhes a alguém que o esteja a ajudar a depurar.
+
+## Como desativar
+
+Desligue o interruptor a qualquer momento. Os novos jobs deixam de registar de imediato. Tudo o que já foi capturado fica no disco até ser compactado ou até remover o projeto — nada é enviado para parte nenhuma nem se perde sem você saber.

package/docs/guide/pt/settings/4-where-your-data-lives.md

@@ -0,0 +1,48 @@
+# Onde ficam os seus dados
+
+Versão curta: **o Specrails mantém os seus repositórios impecáveis.** Quando aponta a aplicação para um dos seus projetos, ela não se instala lá dentro, não espalha ficheiros de configuração por todo o lado nem reescreve nada que não lhe tenha pedido. O seu código continua a ser seu, e limpo.
+
+## O seu repositório continua limpo
+
+Os ficheiros do próprio Specrails — as suas bases de dados, o estado por projeto, as definições de agentes, as configurações, a telemetria, os resumos e tudo o mais de que precisa para funcionar — vivem todos num único lar arrumado, dentro da sua pasta pessoal:
+
+```
+~/.specrails/
+```
+
+Essa pasta é o workspace privado da aplicação. É onde ficam o registo de projetos, as bases de dados por projeto, as ferramentas integradas e toda a parte operacional. Os seus repositórios de código nunca são usados como depósito para nada disto.
+
+Isto significa que:
+
+- O `.gitignore` do seu repositório **não** é reescrito pela aplicação.
+- O seu repositório não fica cheio de configurações de ferramentas nem de diretórios de estado ocultos.
+- Remover um projeto do Specrails não deixa nenhuma trapalhada no seu código.
+
+Se já usou ferramentas que, em silêncio, adicionavam pastas e ficheiros por todo o projeto, isto é um afastamento deliberado dessa prática. O Specrails foi construído para que apontá-lo a um repositório seja um **não-acontecimento** para o histórico git desse repositório.
+
+## A única coisa que *é* commitada — por desenho
+
+Há exatamente uma exceção intencional, e é o cerne da ferramenta: **as suas specs OpenSpec.**
+
+As specs vivem no seu repositório, em:
+
+```
+openspec/
+```
+
+Isto é de propósito. As suas specs são um **entregável** — um registo versionado e revisável daquilo que decidiu construir e porquê. Pertencem ao lado do seu código, controladas no git, visíveis nos pull requests, partilhadas com a sua equipa. É esse o valor: as specs não são estado descartável de rascunho, são parte do histórico do seu projeto.
+
+Portanto, a regra é simples e honesta:
+
+- **`openspec/`** → vive no seu repositório, commitado, por desenho.
+- **Tudo o resto de que o Specrails precisa** → vive em `~/.specrails/`, fora do seu caminho.
+
+## Porque funciona assim
+
+O Specrails executa as ferramentas de IA a partir do seu próprio workspace privado (em `~/.specrails/`) e só volta ao seu repositório real para aquilo que genuinamente precisa de o tocar — ler o seu código e escrever as specs que pediu. As ferramentas, as definições da framework e a contabilidade ficam todas na pasta pessoal da aplicação.
+
+A conclusão, para si: pode adicionar um projeto, executar pipelines, explorar specs e experimentar com a confiança de que a árvore de trabalho e o histórico git do seu repositório só mudam de formas que esperaria — as suas specs commitadas e o código que os seus pipelines escrevem. Mais nada se infiltra.
+
+## Remover um projeto
+
+Quando remove um projeto do Specrails, a aplicação limpa o seu próprio estado por projeto dentro de `~/.specrails/`. As specs já commitadas no seu repositório ficam onde pertencem — no seu repositório — porque são suas.

package/docs/guide/pt/specs/1-specs-and-the-backlog.md

@@ -0,0 +1,52 @@
+# Specs e o backlog
+
+Uma **spec** é a unidade de trabalho que o pipeline de IA implementa. Pense nela como um ticket: um título, uma descrição do que quer fazer, uma prioridade e, opcionalmente, etiquetas. Quando lança o pipeline, os agentes de IA leem a spec e agem sobre ela — por isso, uma spec clara é o input mais importante para um bom resultado.
+
+Por vezes, na app, as specs também são chamadas de **tickets** — as duas palavras significam o mesmo.
+
+## O quadro
+
+Cada projeto abre no seu **Dashboard**, que mostra a **SpecsBoard** — a lista de todas as specs do projeto. Este é o seu backlog. É aqui que cria novas specs, define a sua prioridade, as arrasta para um rail para as implementar e vê o seu estado mudar à medida que o trabalho avança.
+
+O quadro tem dois modos de visualização, alternados a partir de um botão na barra de ferramentas e memorizados por projeto:
+
+- **Vista de post-its** (a predefinida) — mosaicos em forma de cartão com resumos curtos.
+- **Vista de lista** — linhas compactas de uma só linha.
+
+Também pode filtrar por **estado** (Todos / Por fazer / Concluído) e por **etiqueta**, e ordenar por **Predefinida**, **Ticket #** ou **Prioridade** (cada uma com um seletor ascendente/descendente).
+
+## Estados
+
+Uma spec percorre um pequeno conjunto de estados. O quadro dá a cada um uma pista visual consistente para que possa ler o estado do seu backlog de relance:
+
+| Estado | O que significa |
+|--------|---------------|
+| **Rascunho** | Uma ideia em curso guardada a partir de uma conversa do modo Explore. Ainda não está pronta para implementar — pode voltar e continuar a dar-lhe forma. Mostra uma etiqueta `Draft`. |
+| **Por fazer** | Pronta para ser executada. É aqui que uma spec terminada aterra quando a cria. |
+| **Em curso** | O pipeline está a trabalhar nela neste momento (um ponto azul pulsante). |
+| **Concluído** | Concluída pelo pipeline (um visto verde). |
+| **Cancelado** | Abandonada (um X vermelho). |
+
+Os rascunhos vivem no mesmo grupo ativo que as specs Por fazer — não há uma coluna separada para eles — mas têm um contorno subtilmente colorido e uma etiqueta `Draft` para serem fáceis de identificar. Veja [Rascunhos e o Contract Layer](drafts-and-contract-layer.md) para a história completa sobre rascunhos.
+
+## Prioridades
+
+Cada spec que não seja um rascunho tem uma prioridade: **Crítica**, **Alta**, **Média** ou **Baixa**. A prioridade é apenas uma ferramenta de organização — ajuda-o a decidir o que implementar a seguir e permite-lhe ordenar o quadro. Define-a ao criar uma spec e pode alterá-la a qualquer momento clicando com o botão direito no cartão da spec e escolhendo **Definir prioridade**.
+
+Os rascunhos são a única exceção: um rascunho pode *não* ter prioridade nenhuma, porque ainda é uma ideia em curso. A prioridade fica fixada quando confirma o rascunho numa spec a sério.
+
+## Criar uma spec
+
+Para criar uma spec, clique em **Adicionar** (o botão Mais na barra de ferramentas da SpecsBoard). Abre-se a janela **Adicionar Spec** com algumas formas de trabalhar:
+
+- **Quick** — descreve o que quer e a IA escreve a spec completa de uma só vez. Veja [Adicionar Spec — modo Quick](add-spec-quick-mode.md).
+- **Explore** — conversa com a IA, e ela ajuda-o a dar forma à spec turno a turno. Veja [Adicionar Spec — modo Explore](add-spec-explore-mode.md).
+- **Raw** — o que quer que escreva é guardado tal e qual como uma spec, sem qualquer IA envolvida. Use este modo quando já tem o texto da spec pronto.
+
+Qual escolher depende do quão clara já está a ideia. Sabe exatamente o que quer? Quick. Ainda a pensar nela? Explore. Já tem o texto? Raw.
+
+## Para onde ir a seguir
+
+- [Adicionar Spec — modo Quick](add-spec-quick-mode.md) — a forma mais rápida de transformar uma ideia numa spec.
+- [Adicionar Spec — modo Explore](add-spec-explore-mode.md) — dê forma a uma spec em conversa.
+- [Rascunhos e o Contract Layer](drafts-and-contract-layer.md) — guarde trabalho em curso e enriqueça specs para o pipeline.

package/docs/guide/pt/specs/2-add-spec-quick-mode.md

@@ -0,0 +1,45 @@
+# Adicionar Spec — modo Quick
+
+O modo Quick é para quando já sabe o que quer. Escreve a sua ideia, a IA redige a spec completa, e ela aterra no seu quadro como **Por fazer**. Sem idas e vindas — basta descrever e avançar.
+
+## Criar uma spec no modo Quick
+
+Para criar uma spec rapidamente:
+
+1. No Dashboard, clique em **Adicionar** (o botão Mais na barra de ferramentas da SpecsBoard).
+2. Escolha o modo **Quick**.
+3. Escreva a sua ideia no campo de texto — uma frase ou um parágrafo, o que melhor a capturar.
+4. Clique para gerar.
+
+Enquanto a spec está a ser escrita, uma pequena notificação no canto mostra o nome do projeto, um excerto da sua ideia e o **tempo decorrido** ("A gerar… 0:12"). Quando termina, a notificação muda para "Gerada em <tempo>" com uma ação **Ver** que o leva diretamente à sua nova spec.
+
+É este o fluxo completo. Tudo o que se segue é um ajuste fino opcional.
+
+## O que pode ajustar
+
+**Modelo** — por predefinição, a IA escolhe um modelo sensato. Pode substituí-lo por spec a partir do seletor de modelo se quiser um mais rápido ou mais capaz.
+
+**Motor** — se o seu projeto tiver mais do que um fornecedor de IA instalado (qualquer combinação de Claude, Codex e Gemini), um seletor de motor fica no topo da janela para que possa escolher qual deles gera esta spec. A sua escolha é memorizada por projeto. Projetos com um único fornecedor não mostram isto — não há nada por onde escolher.
+
+**Contexto** — o modo Quick normalmente corre como um único turno, porque não precisa de ler a sua base de código para escrever uma spec a partir da sua descrição. Mas um seletor de contexto permite dar-lhe mais material para trabalhar:
+
+- No nível mais baixo, lê apenas a sua descrição.
+- Em níveis mais altos, pode ler as suas specs existentes, as specs OpenSpec do seu projeto, e até toda a sua base de código antes de escrever.
+
+Quanto mais contexto lhe der, mais demora a geração (passa a multi-turno para poder ler primeiro), mas a spec volta fundamentada no seu projeto real. Recorra a níveis de contexto mais altos quando a spec precisar de referenciar código real, nomes de ficheiros ou comportamentos existentes.
+
+**Anexos** — largue mockups, briefs ou ficheiros de dados no campo da ideia. A IA lê-os como parte da escrita da spec. (Os anexos também passam a geração para multi-turno.)
+
+**Enriquecer com Contract Layer** — um interruptor que acrescenta um bloco estruturado à spec gerada, para que o pipeline a jusante não tenha de adivinhar nomes nem formatos de dados. É opcional e está desativado por predefinição; a sua última escolha é memorizada por projeto. Veja [Rascunhos e o Contract Layer](drafts-and-contract-layer.md) para saber o que adiciona e quando vale a pena.
+
+## Quando usar o modo Quick vs Explore
+
+Use o **Quick** quando a ideia já está clara na sua cabeça — podia escrever a spec você mesmo, mas prefere que a IA o faça. Use o [**Explore**](add-spec-explore-mode.md) quando ainda está a pensar no assunto e quer um parceiro que o ajude a dar-lhe forma.
+
+Uma spec criada no modo Quick é uma spec perfeitamente normal: pode mais tarde abri-la e **Continuar a editar** numa sessão de Explore, se precisar de refinamento.
+
+## Para onde ir a seguir
+
+- [Adicionar Spec — modo Explore](add-spec-explore-mode.md) — para specs que precisam de forma.
+- [Rascunhos e o Contract Layer](drafts-and-contract-layer.md) — o enriquecimento Contract Layer explicado.
+- [Executar pipelines](running-pipelines.md) — arraste a sua nova spec para um rail e implemente-a.

package/docs/guide/pt/specs/3-add-spec-explore-mode.md

@@ -0,0 +1,68 @@
+# Adicionar Spec — modo Explore
+
+O modo Explore é uma conversa. Em vez de escrever a spec você mesmo, conversa sobre a ideia com a IA — ela age como parceira de raciocínio, faz perguntas, propõe estrutura e constrói um **rascunho ao vivo** da spec à medida que avança. Quando estiver satisfeito, confirma o rascunho numa spec a sério.
+
+Recorra ao Explore quando a ideia ainda não está totalmente formada, quando há compromissos a discutir, ou quando quer que a IA olhe para o seu código real antes de fixar a spec.
+
+## Criar uma spec no modo Explore
+
+Para dar forma a uma spec no modo Explore:
+
+1. No Dashboard, clique em **Adicionar** e depois escolha **Explore**.
+2. Escreva a sua primeira mensagem — a ideia, uma pergunta ou um pensamento ainda por amadurecer.
+3. Leia a resposta da IA e continue a responder. A cada turno, ela refina a sua compreensão.
+4. Veja o **rascunho ao vivo** atualizar-se ao lado da conversa — esta é a spec a ganhar forma.
+5. Quando o rascunho parecer correto, clique em **Criar Spec**.
+
+A conversa fica no seu histórico, por isso pode sempre voltar para ver como a spec foi moldada.
+
+## O rascunho ao vivo
+
+À medida que conversa, um painel de rascunho mostra a spec tal como está neste momento — título, descrição, prioridade, etiquetas, critérios de aceitação. Reescreve-se a cada turno com base no que já discutiram. Não o edita diretamente; orienta-o através da conversa ("na verdade, mete a prioridade em alta", "adiciona um critério sobre o tratamento de erros", e por aí adiante).
+
+É este o coração do modo Explore: nunca está a olhar para um formulário em branco. Está sempre a olhar para uma spec real e em evolução.
+
+## Quanto é que a IA vê: o seletor de contexto
+
+Antes de a IA responder, decide quanto do seu projeto ela pode ver. Um seletor de presets de contexto permite-lhe trocar velocidade por profundidade:
+
+| Preset | O que a IA vê |
+|--------|------------------|
+| **Mínimo** | Apenas a sua mensagem. O mais rápido e o mais barato. |
+| **Leve** | + as suas specs existentes. |
+| **Padrão** | + as suas specs e as specs OpenSpec do seu projeto. |
+| **Rico** | + acesso de leitura a toda a sua base de código, para poder fundamentar as respostas em código real. |
+| **Máx** | Rico, mais uma passagem de enriquecimento Contract Layer na confirmação. |
+| **Desktop** | Máx, mais os servidores MCP do seu projeto e os seus próprios servidores MCP aprovados. |
+
+Comece baixo para um brainstorming rápido; suba quando quiser que a IA verifique as suas sugestões contra o seu código real. A escolha é guardada na conversa, por isso não se propaga para outras sessões de Explore.
+
+Se quiser um controlo mais fino, clique em **Ajuste fino** para alternar manualmente as opções subjacentes — incluindo **Os meus MCPs aprovados**, que carrega os servidores MCP que já aprovou localmente sem abrandar a sessão.
+
+## Botões na janela do Explore
+
+- **Criar Spec** — promove o rascunho ao vivo a uma spec a sério com estado **Por fazer**. (Quando está a editar uma spec existente, este botão passa a dizer **Atualizar Spec** e atualiza essa spec no próprio lugar.)
+- **Rever →** — abre uma sobreposição de revisão que mostra a spec proposta em comparação com a baseline antes de confirmar, para não haver surpresas.
+- **Guardar como rascunho** — persiste a conversa como um ticket de rascunho para que a possa retomar mais tarde. Disponível assim que tiver enviado pelo menos uma mensagem. Veja abaixo.
+- **Minimizar** — estaciona a conversa como um chip na doca de chats minimizados, no canto inferior esquerdo. Clique no chip a qualquer momento para voltar diretamente à conversa — nada se perde.
+- **Descartar** — deita a conversa fora (pede confirmação primeiro).
+
+## Guardar como rascunho
+
+Ainda não está pronto para confirmar, mas não quer perder o raciocínio? Clique em **Guardar como rascunho**. A conversa torna-se uma **spec de rascunho** no seu quadro, e o rascunho fica ligado à conversa que está por detrás.
+
+Mais tarde, abra o rascunho a partir do quadro e clique em **Continuar a editar** — a conversa original reabre-se com todo o seu histórico de chat intacto, e continua exatamente onde ficou. Os rascunhos nunca são eliminados automaticamente; ficam à sua espera.
+
+Isto torna o Explore seguro para ideias ainda por amadurecer: comece uma conversa, chegue a algum lado, guarde-a como rascunho e volte amanhã.
+
+Para tudo sobre rascunhos — incluindo o enriquecimento Contract Layer — veja [Rascunhos e o Contract Layer](drafts-and-contract-layer.md).
+
+## Nota sobre múltiplos fornecedores
+
+Se o seu projeto tiver mais do que um fornecedor de IA instalado, um seletor de motor permite-lhe escolher qual deles conduz a conversa do Explore. Projetos com um único fornecedor não o mostram.
+
+## Para onde ir a seguir
+
+- [Rascunhos e o Contract Layer](drafts-and-contract-layer.md) — guardar trabalho em curso e enriquecer specs para o pipeline.
+- [Adicionar Spec — modo Quick](add-spec-quick-mode.md) — quando a ideia já está clara.
+- [Executar pipelines](running-pipelines.md) — implemente a sua spec assim que estiver pronta.

package/docs/guide/pt/specs/4-drafts-and-contract-layer.md

@@ -0,0 +1,81 @@
+# Rascunhos e o Contract Layer
+
+Esta página cobre duas formas de tirar mais partido das suas specs: os **rascunhos** (guardar uma ideia em curso para a retomar mais tarde) e o **Contract Layer** (um enriquecimento opcional que torna as specs mais precisas para o pipeline de IA).
+
+## Rascunhos: guardar uma ideia em curso
+
+Um **rascunho** é uma conversa de [Explore](add-spec-explore-mode.md) em curso guardada como spec. Permite-lhe parar a meio de um pensamento sem perder nada e voltar quando estiver pronto.
+
+### Guardar um rascunho
+
+Enquanto está numa conversa de Explore, clique em **Guardar como rascunho** (disponível assim que tiver enviado pelo menos uma mensagem). A app:
+
+- Cria uma spec com estado **Rascunho** no seu quadro.
+- Dá-lhe um título automaticamente se não tiver definido nenhum (um resumo curto da conversa).
+- Liga-a de volta à conversa, para que todo o histórico de chat seja preservado.
+
+Guardar é idempotente — se guardar a mesma conversa duas vezes, atualiza o rascunho existente em vez de criar um duplicado.
+
+### Como os rascunhos aparecem no quadro
+
+Os rascunhos vivem no mesmo grupo ativo que as suas specs Por fazer — não há uma coluna separada. Vai identificá-los por:
+
+- Uma etiqueta `Draft` onde normalmente fica a etiqueta de prioridade.
+- Um contorno subtilmente colorido no cartão.
+
+Um rascunho pode *não ter prioridade* — a prioridade é definida quando o confirma numa spec a sério.
+
+### Retomar um rascunho
+
+Para continuar de onde ficou:
+
+1. Abra o rascunho a partir do quadro.
+2. Clique em **Continuar a editar** na janela de detalhe.
+3. A conversa de Explore original reabre-se com todo o seu histórico de chat, e o painel do rascunho ao vivo pré-preenchido com tudo o que já tinha moldado.
+4. Continue a conversar. Quando terminar, **Criar Spec** promove o rascunho a uma spec a sério (estado **Por fazer**, com a prioridade que escolher).
+
+### Descartar um rascunho
+
+Os rascunhos **nunca são eliminados automaticamente**. Só desaparecem quando os descarta explicitamente, ou quando os confirma num estado a sério. Descartar um rascunho também limpa a conversa associada quando mais nada a referencia.
+
+> Dica: quando não tiver a certeza se uma spec vale a pena, guarde-a como rascunho e deixe-a repousar. Abra-a na manhã seguinte, dê uma olhadela à descrição, e decida com olhos descansados.
+
+## O Contract Layer: precisão para o pipeline
+
+O **Contract Layer** é um enriquecimento opcional que acrescenta um bloco estruturado à descrição de uma spec. A sua função é eliminar a adivinhação para os agentes de IA que implementam a spec — para que reutilizem os nomes certos, respeitem os formatos de dados esperados e mexam nos ficheiros certos, em vez de inventarem os seus próprios.
+
+### O que adiciona
+
+O Contract Layer são cinco secções curtas acrescentadas à spec:
+
+- **Naming Contract** — os identificadores exatos (funções, campos, rotas) que a implementação deve reutilizar.
+- **Data Shapes** — os payloads, em formato semelhante a JSON, envolvidos.
+- **State Machine** — as transições ou estados pelos quais a funcionalidade passa.
+- **Invariants** — propriedades que devem ser sempre verdadeiras.
+- **File Touch List** — os ficheiros que a implementação deverá editar.
+
+Pense nisto como entregar ao pipeline uma planta precisa em vez de um esboço. É especialmente valioso para specs que se ligam a código existente, onde a IA, ao adivinhar um nome ou um formato, causaria retrabalho.
+
+### Como adicioná-lo
+
+Há três formas de aplicar o Contract Layer:
+
+- **Modo Quick** — ative o interruptor **Enriquecer com Contract Layer** antes de gerar. A sua última escolha é memorizada por projeto. (Veja [Adicionar Spec — modo Quick](add-spec-quick-mode.md).)
+- **Modo Explore** — escolha o preset de contexto **Máx** ou **Desktop** (que correm o enriquecimento automaticamente na confirmação), ou abra **Ajuste fino** e ative-o manualmente. (Veja [Adicionar Spec — modo Explore](add-spec-explore-mode.md).)
+- **Numa spec existente** — abra a janela de detalhe da spec e volte a correr o enriquecimento a partir daí.
+
+### Onde aparece
+
+Depois de uma spec ter um Contract Layer, a janela de detalhe mostra-o como um bloco colapsável com um distintivo do tipo `3/5 preenchidas` — dizendo-lhe quantas das cinco secções foram efetivamente preenchidas (algumas funcionalidades simplesmente não têm, por exemplo, uma state machine, e essas secções ficam marcadas como não aplicáveis). Expanda-o para ler o contrato completo; recolha-o para manter a descrição arrumada.
+
+Se o enriquecimento alguma vez falhar ao correr, a app apresenta uma notificação com uma ação **Repetir** para que o possa disparar de novo.
+
+### Vale sempre a pena?
+
+Nem sempre. Para uma spec pequena e autocontida, a IA consegue implementá-la bem sem ele. O Contract Layer ganha o seu valor em specs que se integram fortemente com código existente, onde os nomes e formatos exatos importam — é aí que fixar o contrato à partida lhe poupa uma ronda de correções mais tarde.
+
+## Para onde ir a seguir
+
+- [Adicionar Spec — modo Explore](add-spec-explore-mode.md) — de onde vêm os rascunhos.
+- [Adicionar Spec — modo Quick](add-spec-quick-mode.md) — o interruptor do Contract Layer no modo Quick.
+- [Executar pipelines](running-pipelines.md) — implemente uma spec assim que estiver pronta.

package/docs/guide/zh/agents/1-meet-the-agents.md

@@ -0,0 +1,38 @@
+# 认识这些 Agent
+
+当你启动一条 **Implement** rail 时，Specrails 并不会把你的 spec 丢给某一个 AI、然后听天由命。它会让一支精干的专职 *Agent* 团队上阵——每个 Agent 只负责一件事，并按精心设计的顺序协作。这一页就来介绍这支团队里都有谁、各自又在做什么。
+
+## 基础三人组
+
+每一次流水线运行都会用到下面这三个 Agent——它们是整个流程的支柱，没有它们，项目根本无法运行一条 rail。
+
+| Agent | 角色 | 它做什么 |
+|-------|------|--------------|
+| **sr-architect** | 规划者 | 阅读你的 spec、检视代码库，产出一份具体的实现方案——要改动哪些文件、改动会是什么形态、有哪些需要留心的地方。它会先想清楚，再让别人动手写代码。 |
+| **sr-developer** | 建造者 | 接过 architect 的方案，真正动手写代码：新建文件、修改、写测试。正是在这一步，你的 spec 变成了实实在在的 diff。 |
+| **sr-reviewer** | 把关者 | 对照 spec 和方案校验 developer 的产出，揪出回归问题，发现不对劲就提出异议。它是改动被视为「完成」之前的质量关卡。 |
+
+可以把它理解成 **设计 → 建造 → 审查**，就像一支严谨的人类团队会走的循环一样。每个 Agent 都把自己的产出交给下一个，所以 developer 永远不会盲目动工，reviewer 手里也始终握着最初的意图可供比对。
+
+## 专家型 Agent
+
+在三人组之外，项目还可以纳入可选的**专家型 Agent**，专门处理某一类工作。你最常见到的一个是：
+
+- **sr-merge-resolver**——一个工具型 Agent，帮你理清合并冲突、调和相互重叠的改动。它是可选的：Profile 只在你需要时才会包含它，而即便缺席，它也绝不会阻塞流水线。
+
+专家型 Agent 是按需启用的。一个全新项目只会带着三人组运行；当项目的工作流确有需要时，你再加入专家型 Agent（以及你自己的**自定义 Agent**——参见 [自定义 Agent 与目录](custom-agents-catalog)）。
+
+## 任务如何送到对的 Agent 手中
+
+在一次运行内，工作是经过*路由*的。一个任务会带着标签，而 Profile 的路由规则会把带标签的任务送给最适合处理它的 Agent——最后再用一条兜底规则，把其余所有任务统统交给 developer。日常使用中你完全不必操心这些；默认设置开箱即用，会把一切合理地分派妥当。当你准备好把特定类型的工作导向特定 Agent 时，请看 [按 Agent 自定义模型](customizing-models-per-agent)。
+
+## 一个需要先说清楚的重要观念
+
+每个 Agent 的*定义*——它的指令、它的性格、它被允许做什么——是**共享的**。它们以文件的形式存在（`.claude/agents/<id>.md`），随你的代码仓库一起流转，因此你的整个团队跑的是同一个 architect、同一个 reviewer。
+
+而**因项目而异**的，是叠加在其上的*配置*：每个 Agent 用哪个模型运行，以及你为某条 rail 挑选了哪一组 Agent 的组合。这正是 Profile 的用武之地——也是下一页的内容。
+
+## 接下来去哪儿
+
+- [Profile 与均衡默认值](profiles-and-the-balanced-default)——团队的配置是如何打包并选用的。
+- [按 Agent 自定义模型](customizing-models-per-agent)——调校成本与质量。