specrails-desktop 2.7.0 → 2.9.0

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

@@ -0,0 +1,68 @@
+# スペックを追加 — Explore モード
+
+Explore モードは、対話です。スペックを自分で書く代わりに、AI とアイデアについて話し合います。AI は考える相棒として、質問を投げかけ、構成を提案し、話を進めるうちにスペックの**ライブ下書き**を組み立てていきます。納得できたら、その下書きを本物のスペックとしてコミットします。
+
+アイデアがまだ固まりきっていないとき、検討すべきトレードオフがあるとき、あるいはスペックを確定する前に AI に実際のコードを見てほしいときには、Explore を選びましょう。
+
+## Explore モードでスペックを作成する
+
+Explore モードでスペックを形にするには、次の手順で進めます。
+
+1. ダッシュボードで**追加**をクリックし、**Explore** を選びます。
+2. 最初のメッセージを入力します。アイデアでも、質問でも、まだ形になっていない思いつきでもかまいません。
+3. AI の返答を読んで、さらに返信を続けます。ターンごとに、AI は理解を深めていきます。
+4. チャットの横で**ライブ下書き**が更新されていくのを眺めましょう。これが、形になっていくスペックです。
+5. 下書きが良さそうに見えたら、**スペックを作成**をクリックします。
+
+会話は履歴に残るので、スペックがどう形作られたのかをあとから振り返ることもできます。
+
+## ライブ下書き
+
+会話を進めるにつれて、下書きペインには現時点でのスペック（タイトル・説明・優先度・ラベル・受け入れ基準）が表示されます。話し合った内容に基づいて、ターンごとに自身を書き換えていきます。直接編集するのではなく、会話を通じて舵を取ります（「やっぱり優先度を高にして」「エラー処理についての基準を追加して」といった具合に）。
+
+これこそが Explore モードの核心です。真っ白なフォームを前に固まることはありません。いつでも、進化していく本物のスペックを眺めながら進められます。
+
+## AI が見える範囲：コンテキストスライダー
+
+AI が答える前に、プロジェクトのどこまでを AI に見せるかをあなたが決めます。コンテキストプリセットスライダーで、速度と深さのバランスを調整できます。
+
+| プリセット | AI が見える範囲 |
+|--------|------------------|
+| **最小** | あなたのメッセージだけ。最速・最安。 |
+| **ライト** | + 既存のスペック。 |
+| **標準** | + スペックとプロジェクトの OpenSpec スペック。 |
+| **リッチ** | + コードベース全体への読み取りアクセス。回答を実際のコードに根ざせます。 |
+| **最大** | リッチに加えて、コミット時に Contract Layer の強化パスを実行。 |
+| **Desktop** | 最大に加えて、プロジェクトの MCP サーバーとあなた自身の承認済み MCP サーバー。 |
+
+手早くブレインストーミングしたいときは低めから始め、AI に提案を実際のコードと照らし合わせて検証してほしくなったら上げていきましょう。選択は会話ごとに保存されるので、他の Explore セッションに漏れることはありません。
+
+より細かく制御したい場合は、**微調整**をクリックして、土台のオプションを手動で切り替えられます。これには**承認済みの MCP**も含まれ、セッションを遅くすることなく、ローカルですでに承認済みの MCP サーバーを読み込めます。
+
+## Explore シェルのボタン
+
+- **スペックを作成** — ライブ下書きをステータス **Todo** の本物のスペックに昇格させます。（既存のスペックを編集している場合、このボタンは代わりに**スペックを更新**と表示され、そのスペックをその場でパッチします。）
+- **レビュー →** — レビューオーバーレイを開き、コミット前に、提案されたスペックをベースラインとの差分として表示します。これで思いがけない結果に驚くことはありません。
+- **下書きとして保存** — 会話を下書きチケットとして保存し、あとから再開できるようにします。少なくとも 1 件メッセージを送信すると使えるようになります。詳しくは下記をご覧ください。
+- **最小化** — 会話を左下の最小化チャットドックにチップとして格納します。チップはいつでもクリックでき、すぐに会話に戻れます。何も失われません。
+- **破棄** — 会話を捨てます（先に確認を求めます）。
+
+## 下書きとして保存する
+
+コミットする準備はまだだけれど、考えたことを失いたくない。そんなときは**下書きとして保存**をクリックします。会話はボード上の**下書きスペック**になり、その下書きは背後の会話とリンクされたままになります。
+
+あとからボードでその下書きを開き、**編集を続ける**をクリックすると、元の会話がチャット履歴ごとそのまま再び開き、中断したところからぴったり続けられます。下書きが自動で削除されることは決してありません。あなたを待っていてくれます。
+
+これにより、Explore は半端なアイデアでも安心して使えます。会話を始め、ある程度まで進め、下書きとして保存し、翌日また戻ってくる、というふうに。
+
+下書きについてのすべて（Contract Layer による強化も含めて）は、[下書きと Contract Layer](drafts-and-contract-layer.md)をご覧ください。
+
+## マルチプロバイダーについて
+
+プロジェクトに複数の AI プロバイダーがインストールされている場合、エンジンセレクターで、どのエンジンが Explore の会話を駆動するかを選べます。プロバイダーが 1 つだけのプロジェクトでは表示されません。
+
+## 次はこちら
+
+- [下書きと Contract Layer](drafts-and-contract-layer.md) — 作りかけの作業を保存し、パイプライン向けにスペックを充実させる。
+- [スペックを追加 — クイックモード](add-spec-quick-mode.md) — アイデアがすでにはっきりしているとき。
+- [パイプラインを実行する](running-pipelines.md) — スペックが整ったら実装する。

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

@@ -0,0 +1,81 @@
+# 下書きと Contract Layer
+
+このページでは、スペックをさらに活かす 2 つの方法を扱います。**下書き**（作りかけのアイデアを保存して、あとから再開する仕組み）と、**Contract Layer**（スペックを AI パイプライン向けにより正確にする、任意の強化機能）です。
+
+## 下書き：作りかけのアイデアを保存する
+
+**下書き**とは、作りかけの [Explore](add-spec-explore-mode.md) 会話をスペックとして保存したものです。考えの途中で手を止めても何も失わずに済み、準備ができたら戻ってこられます。
+
+### 下書きを保存する
+
+Explore の会話中に、**下書きとして保存**をクリックします（少なくとも 1 件メッセージを送信すると使えるようになります）。アプリは次のことを行います。
+
+- ステータス **下書き** のスペックをボードに作成します。
+- タイトルを設定していなければ、自動で付けます（会話の短い要約）。
+- 会話とリンクさせ、チャット履歴全体を保持します。
+
+保存はべき等です。同じ会話を 2 回保存しても、重複を作らず、既存の下書きを更新します。
+
+### ボード上での下書きの見え方
+
+下書きは Todo のスペックと同じアクティブな枠に並びます。専用の列はありません。次の点で見分けられます。
+
+- 優先度ピルが通常表示される位置にある `Draft` ピル。
+- カードのほんのり色づいたボーダー。
+
+下書きは**優先度を持たない**ことが許されています。優先度は、本物のスペックとしてコミットするときに設定します。
+
+### 下書きを再開する
+
+中断したところから続けるには、次の手順で進めます。
+
+1. ボードから下書きを開きます。
+2. 詳細モーダルで**編集を続ける**をクリックします。
+3. 元の Explore 会話がチャット履歴ごと再び開き、ライブ下書きペインにはそれまで形にしてきた内容があらかじめ入っています。
+4. 引き続き話し合いましょう。終わったら**スペックを作成**で、下書きを本物のスペック（ステータス **Todo**、あなたが選んだ優先度付き）に昇格させます。
+
+### 下書きを破棄する
+
+下書きが**自動で削除されることは決してありません**。明示的に破棄したとき、または本物のステータスにコミットしたときにだけ消えます。下書きを破棄すると、他に参照しているものがなければ、リンクされた会話もあわせて片付けられます。
+
+> ヒント：そのスペックをやる価値があるか迷ったら、下書きとして保存して寝かせておきましょう。翌朝開いて説明をさっと眺め、新鮮な目で判断するのです。
+
+## Contract Layer：パイプラインのための精度
+
+**Contract Layer** は、スペックの説明に構造化されたブロックを追記する、任意の強化機能です。その役目は、スペックを実装する AI エージェントにとっての当て推量をなくすことです。これにより、エージェントは正しい名前を再利用し、期待されるデータの形に合わせ、独自のものを発明する代わりに、正しいファイルに手を入れるようになります。
+
+### 何が追加されるのか
+
+Contract Layer は、スペックに追記される 5 つの短いセクションです。
+
+- **Naming Contract** — 実装が再利用すべき、正確な識別子（関数・フィールド・ルート）。
+- **Data Shapes** — 関わってくる JSON 風のペイロード。
+- **State Machine** — 機能が移っていく遷移や状態。
+- **Invariants** — 常に成り立っていなければならない性質。
+- **File Touch List** — 実装が編集すると見込まれるファイル。
+
+スケッチではなく正確な設計図をパイプラインに手渡すようなものだと考えてください。とりわけ既存のコードに組み込むスペックでは、AI が名前や形を当て推量すると手戻りが生じるので、この機能が効いてきます。
+
+### 追加する方法
+
+Contract Layer を適用する方法は 3 つあります。
+
+- **クイックモード** — 生成前に **Contract Layer で強化** トグルをオンにします。直前の選択はプロジェクトごとに記憶されます。（[スペックを追加 — クイックモード](add-spec-quick-mode.md)を参照。）
+- **Explore モード** — **最大** または **Desktop** のコンテキストプリセットを選ぶ（コミット時に強化が自動で実行されます）か、**微調整**を開いて手動でトグルします。（[スペックを追加 — Explore モード](add-spec-explore-mode.md)を参照。）
+- **既存のスペックに対して** — スペックの詳細モーダルを開き、そこから強化を再実行します。
+
+### どこに表示されるか
+
+スペックに Contract Layer が付くと、詳細モーダルでは折りたたみ可能な開閉セクションとして表示され、`3/5 件入力済み` のようなバッジが添えられます。これは、5 つのセクションのうち実際に何件が埋まったかを示しています（たとえば State Machine を持たない機能もあり、そうしたセクションは該当なしと表示されます）。展開すれば契約の全文を読め、折りたためば説明をすっきり保てます。
+
+万が一、強化の実行に失敗した場合は、アプリが**再試行**アクション付きの通知を出すので、もう一度実行できます。
+
+### いつでも価値があるのか
+
+いつもそうとは限りません。小さく自己完結したスペックなら、AI はこれがなくてもきちんと実装できます。Contract Layer が真価を発揮するのは、既存のコードと密に結びつくスペック、正確な名前や形が重要になる場面です。そういうときこそ、契約を前もって固めておくことで、あとで修正のひと回りを回避できるのです。
+
+## 次はこちら
+
+- [スペックを追加 — Explore モード](add-spec-explore-mode.md) — 下書きはここから生まれます。
+- [スペックを追加 — クイックモード](add-spec-quick-mode.md) — クイックモードの Contract Layer トグル。
+- [パイプラインを実行する](running-pipelines.md) — スペックが整ったら実装する。

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

@@ -0,0 +1,38 @@
+# Conheça os agentes
+
+Quando lança um rail de **Implement**, o Specrails não entrega a sua spec a uma única IA na esperança de que tudo corra bem. Em vez disso, põe a trabalhar uma pequena equipa de *agentes* especializados, cada um com uma tarefa, numa ordem bem pensada. Esta página apresenta quem faz parte dessa equipa e o que cada um faz.
+
+## O trio de base
+
+Todas as execuções do pipeline usam estes três agentes — são a espinha dorsal, e um projeto não consegue lançar um rail sem eles.
+
+| Agente | Função | O que faz |
+|--------|--------|-----------|
+| **sr-architect** | O planeador | Lê a sua spec, analisa a base de código e produz um plano de implementação concreto — que ficheiros mexer, que forma vai ter a alteração, com o que ter cuidado. Pensa antes de alguém escrever código. |
+| **sr-developer** | O construtor | Pega no plano do architect e escreve mesmo o código: ficheiros novos, edições, testes. É aqui que a sua spec se transforma num diff real. |
+| **sr-reviewer** | O crítico | Valida o trabalho do developer face à spec e ao plano, deteta regressões e contesta quando algo não está bem. É a barreira de qualidade antes de a alteração ser considerada concluída. |
+
+Pense nisto como **desenhar → construir → rever**, o mesmo ciclo que uma equipa humana cuidadosa seguiria. Cada agente entrega o seu resultado ao seguinte, por isso o developer nunca trabalha às cegas e o reviewer tem sempre a intenção original para comparar.
+
+## Agentes especialistas
+
+Para além do trio, um projeto pode incluir **agentes especialistas** opcionais que tratam de tipos de trabalho específicos. O mais comum que vai encontrar é:
+
+- **sr-merge-resolver** — um agente utilitário que ajuda a desenredar conflitos de merge e a conciliar alterações que se sobrepõem. É opcional: os perfis só o incluem quando o quiser, e nunca bloqueia o pipeline se estiver ausente.
+
+Os especialistas são de adesão voluntária. Um projeto acabado de criar corre apenas com o trio; adicione especialistas (e os seus próprios **agentes personalizados** — veja [Agentes personalizados e o catálogo](custom-agents-catalog)) quando o fluxo de trabalho do projeto o exigir.
+
+## Como as tarefas chegam ao agente certo
+
+Dentro de uma execução, o trabalho é *encaminhado*. Uma tarefa traz tags, e as regras de encaminhamento de um perfil enviam as tarefas etiquetadas para o agente mais indicado para elas — com uma regra final do tipo apanha-tudo que manda o resto para o developer. Para uma utilização normal não precisa de pensar nisto; a configuração predefinida encaminha tudo de forma sensata logo à partida. Quando estiver pronto para direcionar tipos de trabalho específicos para agentes específicos, veja [Personalizar modelos por agente](customizing-models-per-agent).
+
+## Uma ideia importante, já agora
+
+A *definição* de cada agente — as suas instruções, a sua personalidade, o que lhe é permitido fazer — é **partilhada**. Vivem como ficheiros (`.claude/agents/<id>.md`) que viajam com o seu repositório, por isso toda a equipa corre o mesmo architect, o mesmo reviewer.
+
+O que é **por projeto** é a *configuração* por cima: com que modelo cada agente corre, e que combinação de agentes escolhe para um dado rail. É para isso que servem os perfis — e esse é o tema da próxima página.
+
+## Para onde ir a seguir
+
+- [Perfis e a predefinição equilibrada](profiles-and-the-balanced-default) — como a configuração da equipa é empacotada e selecionada.
+- [Personalizar modelos por agente](customizing-models-per-agent) — afine o custo e a qualidade.

package/docs/guide/pt/agents/2-profiles-and-the-balanced-default.md

@@ -0,0 +1,45 @@
+# Perfis e a predefinição equilibrada
+
+Um **perfil** é uma receita guardada para uma execução do pipeline. Responde a três perguntas num só lugar:
+
+1. **Que agentes** participam (o trio de base, mais quaisquer especialistas ou agentes personalizados).
+2. **Que modelo** cada agente usa.
+3. **Como as tarefas são encaminhadas** para esses agentes.
+
+Vai encontrar os perfis na secção **Agentes** de qualquer projeto (barra lateral direita → **Agentes** → separador **Perfis**).
+
+## A predefinição equilibrada
+
+Logo à partida, um projeto resolve para um perfil **default** sensato. Inclui o trio de base — `sr-architect`, `sr-developer`, `sr-reviewer` — e encaminha todas as tarefas para o developer através de uma única regra do tipo apanha-tudo. Os modelos estão equilibrados para o trabalho do dia a dia: um modelo capaz onde importa, sem recorrer à opção mais cara em cada passo.
+
+Se o seu projeto já tinha os modelos dos agentes configurados à maneira antiga (no frontmatter dos ficheiros dos agentes), o botão **Migrar** lê esses valores e cria um perfil `default` que reflete exatamente o comportamento atual — sem perdas, nada muda até que decida afiná-lo.
+
+O ponto principal: **não precisa de criar um perfil para usar o Specrails.** A predefinição simplesmente funciona. Os perfis são a forma de ir mais além.
+
+## Como um perfil é escolhido para uma execução
+
+Quando lança um rail, o Specrails escolhe um perfil por esta ordem:
+
+1. **A sua escolha explícita** no cabeçalho do rail (veja abaixo).
+2. A sua **preferência por developer** — um perfil que tenha marcado como a sua predefinição pessoal para este projeto (é local a si e não é committado).
+3. O perfil **`default`** do projeto.
+
+O perfil é capturado num *snapshot no lançamento*, por isso cada rail num batch pode correr um perfil diferente, e alterar um perfil mais tarde nunca reescreve jobs que já tenham começado.
+
+## Selecionar um perfil por rail
+
+A seleção do perfil acontece mesmo onde lança — no **cabeçalho do rail**, através do seletor de perfis.
+
+- Escolha um perfil no menu pendente para o usar **apenas neste lançamento**.
+- Use a opção de persistir para tornar um perfil a escolha permanente do rail daí para a frente.
+
+É todo o fluxo: escolha um perfil, lance, pronto. Rails concorrentes no mesmo batch podem levar cada um o seu próprio perfil, por isso uma correção rápida e uma funcionalidade pesada podem correr lado a lado com configurações diferentes.
+
+## Quando a secção Agentes está silenciosa
+
+Os perfis são uma capacidade do Claude. Num projeto que inclua um provider que não seja o Claude (Codex ou Gemini), a secção Agentes fica oculta e os rails correm sem perfis — isso é esperado, não é um bug. Os perfis também exigem uma versão suficientemente recente do `specrails-core` no projeto; se for mais antiga, verá um banner amarelo. Os perfis que criar continuam a ser **guardados** — apenas não afetam o pipeline até o core ser atualizado. Atualize com o comando indicado no banner para os desbloquear.
+
+## Para onde ir a seguir
+
+- [Personalizar modelos por agente](customizing-models-per-agent) — construa perfis `fast` e `max`.
+- [Agentes personalizados e o catálogo](custom-agents-catalog) — veja e expanda a equipa.

package/docs/guide/pt/agents/3-customizing-models-per-agent.md

@@ -0,0 +1,60 @@
+# Personalizar modelos por agente
+
+A coisa mais útil que os perfis lhe permitem fazer é **escolher o modelo certo para cada passo**. Um passo de planeamento pode merecer o seu modelo mais forte; um passo de construção rotineiro pode ficar perfeitamente satisfeito com algo mais rápido e mais barato. Os perfis deixam-no exprimir exatamente isso.
+
+É aqui que a separação entre o partilhado e o por projeto compensa:
+
+- As *definições* dos agentes mantêm-se partilhadas por toda a equipa.
+- O *modelo com que cada agente corre* é configurado **por projeto**, dentro de um perfil, e só afeta o seu projeto.
+
+Mude um modelo e muda o custo e o comportamento para esse projeto — sem tocar na configuração de mais ninguém nem nas instruções subjacentes do agente.
+
+## Mudar o modelo que um agente usa
+
+Em **Agentes → Perfis**, selecione um perfil e abra o seu editor de cadeia de agentes. Cada agente na cadeia tem um campo de modelo. Há também um modelo de **orquestrador** que corre a coordenação de topo do pipeline.
+
+Os valores de modelo são aliases — para o Claude são `opus`, `sonnet` e `haiku` (do mais capaz → ao mais rápido). Defina o alias que quiser por agente:
+
+- Deixe o modelo de um agente **em branco** para recorrer à predefinição do próprio ficheiro do agente.
+- Defina-o explicitamente para o substituir apenas neste perfil.
+
+Guarde, e o próximo rail lançado com esse perfil usa os novos modelos. Os jobs já em execução mantêm o seu snapshot.
+
+## Criar perfis como `fast` e `max`
+
+O padrão natural é um par de perfis com nome a que recorre consoante o trabalho:
+
+**Um perfil `fast`** — para alterações pequenas e de baixo risco em que quer velocidade e uma fatura menor:
+
+- Architect: um modelo intermédio ou rápido — o plano é simples.
+- Developer: um modelo rápido — a alteração é mecânica.
+- Reviewer: mantenha-o sólido, mas também pode poupar aqui.
+
+**Um perfil `max`** — para funcionalidades complicadas e de alto risco em que quer que cada passo seja o mais afiado possível:
+
+- Architect, developer e reviewer: o seu modelo mais forte em toda a linha.
+
+### Duas formas de construir um
+
+1. **Duplicar e ajustar** *(recomendado).* Selecione o seu perfil `default`, **Duplique-o**, dê à cópia um nome em kebab-case como `fast` ou `max`, e depois ajuste o modelo de cada agente. Herda uma cadeia e um encaminhamento que sabe estarem bons e muda apenas o que pretende.
+2. **Começar do zero.** Crie um **Perfil em branco** e monte a cadeia você mesmo. Tem ainda assim de incluir o trio de base (`sr-architect`, `sr-developer`, `sr-reviewer`) — o pipeline depende dos três — e exatamente uma regra de encaminhamento terminal do tipo apanha-tudo, que tem de ser a última.
+
+Os nomes de perfil são em kebab-case minúsculo (p. ex. `fast`, `max`, `cheap-and-cheerful`).
+
+## Encaminhar tarefas para agentes específicos
+
+As **regras de encaminhamento** de um perfil decidem que agente trata uma tarefa etiquetada. Cada regra lista tags de tarefa e um agente de destino; vence a primeira regra cujas tags coincidam, e uma única regra `default: true` no fim apanha tudo o resto. Apenas agentes que estejam realmente na cadeia do perfil podem ser destinos de encaminhamento — o editor faz cumprir esta regra.
+
+Para uso do dia a dia não vai mexer no encaminhamento: a regra apanha-tudo envia o trabalho para o developer e isso está correto. Recorra a regras de tags quando quiser, por exemplo, que o trabalho etiquetado com `migration` vá para um especialista.
+
+## Escolher o perfil quando lança
+
+Tudo isto se junta no lançamento: no cabeçalho do rail, escolha `fast`, `max` ou `default` por rail. Um batch pode misturá-los — uma correção minúscula em `fast`, uma grande funcionalidade em `max`, ambas a correr ao mesmo tempo. Veja [Perfis e a predefinição equilibrada](profiles-and-the-balanced-default) para o fluxo de seleção.
+
+## Uma nota sobre segurança
+
+Eliminar um perfil é seguro para o trabalho em curso: os jobs já lançados com ele mantêm o seu snapshot, e os lançamentos futuros simplesmente recorrem à ordem de resolução. Experimente à vontade.
+
+## Para onde ir a seguir
+
+- [Agentes personalizados e o catálogo](custom-agents-catalog) — adicione agentes para pôr nas suas cadeias.

package/docs/guide/pt/agents/4-custom-agents-catalog.md

@@ -0,0 +1,43 @@
+# Agentes personalizados e o catálogo
+
+Os perfis decidem *que agentes correm e com que modelos*. Mas de onde vêm os próprios agentes? Vêm do **catálogo de Agentes**.
+
+Abra **Agentes → Catálogo** em qualquer projeto. É um visualizador apenas de leitura de todos os agentes disponíveis para esse projeto, em dois grupos:
+
+- **Agentes upstream** — os agentes que vêm com o `specrails-core`: o trio de base (`sr-architect`, `sr-developer`, `sr-reviewer`) e quaisquer especialistas como o `sr-merge-resolver`.
+- **Agentes personalizados** — agentes que adicionou você mesmo, com o nome `custom-*`.
+
+Cada entrada do catálogo mostra para que serve o agente e o seu modelo predefinido, para que possa ver toda a equipa antes de ligar os agentes a uma cadeia de perfil.
+
+## Adicionar um agente personalizado
+
+Os agentes personalizados são simples ficheiros Markdown no seu repositório, em `.claude/agents/`, com o nome `custom-<algo>.md`. O ficheiro contém as instruções do agente (o seu system prompt) e um pequeno cabeçalho de frontmatter que inclui um `model:` predefinido.
+
+Assim que o ficheiro existe no projeto, aparece no catálogo como agente personalizado, e pode adicionar o seu id à cadeia de agentes de qualquer perfil (e encaminhar tarefas para ele). O id tem de coincidir com o nome do ficheiro — uma entrada para `custom-docs` corresponde a `.claude/agents/custom-docs.md`.
+
+Como vivem no seu repositório, os agentes personalizados são **ativos de equipa que se podem committar**: faça commit do ficheiro e toda a equipa fica com o agente. Isto espelha a ideia central de toda a secção Agentes —
+
+> **As definições dos agentes são partilhadas (vivem no repositório e viajam com o `git`). A configuração dos modelos é por projeto (vive nos perfis).**
+
+O namespace `custom-*` é reservado e protegido: os comandos `init` e `update` do `specrails-core` nunca tocam em `.claude/agents/custom-*.md`, por isso os seus agentes personalizados sobrevivem intactos às atualizações do core. (A mesma proteção cobre fragmentos contribuídos por plugins, como o `custom-serena.md`.)
+
+## Pôr um agente personalizado a trabalhar
+
+O fluxo típico:
+
+1. Escreva `.claude/agents/custom-<nome>.md` com instruções e um modelo predefinido.
+2. Confirme que aparece em **Agentes → Catálogo** em Personalizados.
+3. Em **Agentes → Perfis**, adicione o agente à cadeia de um perfil (substituindo opcionalmente o seu modelo para esse perfil).
+4. Adicione uma regra de encaminhamento para que as tarefas com as tags certas cheguem até ele — ou confie na ordem da cadeia.
+5. Lance um rail com esse perfil a partir do cabeçalho do rail.
+
+## Acompanhar o desempenho dos perfis
+
+A secção Agentes tem também um separador **Utilização** — uma análise por perfil de quantos jobs correram sob cada perfil numa janela selecionada. É uma forma rápida de confirmar que a sua divisão `fast`/`max` está mesmo a ser usada como pretendia, e de detetar para que perfil a sua equipa tende a gravitar.
+
+## Resumo de toda a secção
+
+- Os **Agentes** são os membros especializados da equipa — o trio partilhado mais especialistas e os seus agentes personalizados. ([Conheça os agentes](meet-the-agents))
+- Os **Perfis** empacotam que agentes correm, com que modelos e como as tarefas são encaminhadas — selecionados por rail no lançamento. O perfil default é a escolha equilibrada do dia a dia. ([Perfis e a predefinição equilibrada](profiles-and-the-balanced-default))
+- Os **Modelos** são afinados por agente, por projeto, dentro dos perfis — construa `fast` e `max` à medida do trabalho. ([Personalizar modelos por agente](customizing-models-per-agent))
+- O **catálogo** mostra todos os agentes, e o namespace `custom-*` permite-lhe fazer crescer a equipa — definições partilhadas, configuração por projeto.

package/docs/guide/pt/getting-started/1-what-is-specrails.md

@@ -0,0 +1,49 @@
+# O que é o specrails
+
+Bem-vindo ao **specrails** — uma app de desktop que transforma um assistente de programação com IA numa verdadeira equipa de software a trabalhar nos *seus* projetos, na *sua* máquina.
+
+Em vez de andar a copiar e colar prompts de um lado para o outro, descreve o que pretende sob a forma de uma **spec**, e o specrails fá-la passar por um pipeline de desenvolvimento completo — desenhando, construindo, revendo e entregando a alteração — enquanto a vê acontecer em direto.
+
+## Desenvolvimento com IA orientado por specs
+
+No coração do specrails está uma ideia simples: **a melhor forma de obter bom código de uma IA é partir de uma spec clara.**
+
+Uma *spec* é uma descrição curta e estruturada de um trabalho concreto — uma funcionalidade, uma correção, um refactor. Pode escrever uma em segundos, ou moldá-la através de um chat guiado que faz as perguntas certas e a redige por si. Cada spec torna-se um **ticket** no quadro do seu projeto, tal como uma tarefa em qualquer gestor de issues.
+
+A partir daí, entrega a spec ao pipeline e deixa a IA fazer o trabalho pesado.
+
+## O pipeline: Arquiteto → Developer → Revisor → Ship
+
+Quando lança uma spec, o specrails fá-la passar por quatro fases, cada uma interpretada por um agente de IA focado:
+
+1. **Arquiteto** — lê a sua spec e o código à volta, e depois planeia a alteração: que ficheiros tocar e qual deve ser a forma da solução.
+2. **Developer** — escreve o código propriamente dito, seguindo o plano.
+3. **Revisor** — verifica o trabalho em termos de correção e qualidade, apanhando problemas antes de si.
+4. **Ship** — finaliza a alteração para que fique pronta a fazer commit.
+
+Vê cada fase à medida que decorre, com logs em direto a fluir diretamente da IA. Nada fica escondido — se algo correr mal, vai ver exatamente onde.
+
+## Projetos
+
+Tudo no specrails está organizado em torno de **projetos**. Um projeto é simplesmente uma pasta no seu computador que contém uma base de código. Pode adicionar tantos projetos quantos quiser e alternar entre eles instantaneamente — cada um guarda as suas próprias specs, histórico de jobs, analytics e definições.
+
+O specrails nunca toca em código que não lhe tenha pedido. Trabalha dentro do seu repositório existente, e é você quem mantém o controlo sobre o que vai para commit.
+
+## Escolha o seu fornecedor de IA
+
+O specrails funciona com as principais CLIs de programação com IA:
+
+- **Claude** (Claude Code)
+- **Codex** (Codex CLI)
+- **Gemini** (Gemini CLI)
+
+Escolha aquela que já usa — ou instale mais do que uma e escolha por tarefa. Um projeto pode correr num único fornecedor ou em vários ao mesmo tempo, por isso nunca fica preso a um só.
+
+## Porque vai gostar
+
+- **Velocidade sem caos** — as specs mantêm a IA focada, por isso obtém alterações úteis em vez de palpites dispersos.
+- **Visibilidade total** — logs em direto, uma vista clara do pipeline e analytics por projeto mostram-lhe exatamente o que aconteceu e quanto custou.
+- **A sua máquina, o seu código** — tudo corre localmente sobre o seu repositório real.
+- **Tudo num só lugar** — specs, jobs, chat, um terminal integrado e o acompanhamento de custos, tudo numa única janela.
+
+Pronto para começar? A seguir: [Instalação e primeira utilização](installing-and-first-run).

package/docs/guide/pt/getting-started/2-installing-and-first-run.md

@@ -0,0 +1,42 @@
+# Instalação e primeira utilização
+
+Pôr o specrails a funcionar na sua máquina leva uns dois minutos. Aqui fica o fluxo completo.
+
+## 1. Descarregar e instalar
+
+Vá buscar o instalador para a sua plataforma:
+
+- **macOS (Apple Silicon)** — um ficheiro `.dmg`. Abra-o e arraste o **specrails** para a sua pasta Aplicações.
+- **Windows** — um instalador `.exe`. Execute-o e siga as instruções.
+
+> **Atenção aos avisos de segurança no macOS e no Windows**
+>
+> - No **Windows**, o instalador ainda não está assinado digitalmente, por isso o SmartScreen pode mostrar um aviso. Clique em **Mais informações → Executar mesmo assim** para continuar.
+> - No **macOS**, a app está assinada e notarizada, por isso deverá abrir sem problemas.
+
+## 2. O que vai precisar (pré-requisitos)
+
+O specrails corre pipelines de desenvolvimento com IA conduzindo ferramentas de linha de comandos reais, por isso há algumas coisas que precisam de estar disponíveis. A boa notícia: a app de desktop **já traz a maioria delas incluída** (o Node.js, o npm e o Git vêm dentro da app), por isso numa máquina nova normalmente não há nada para instalar.
+
+A única coisa que o specrails não consegue incluir é a própria **CLI do fornecedor de IA**. Vai precisar de pelo menos uma de:
+
+- **Claude Code**
+- **Codex CLI**
+- **Gemini CLI**
+
+Instale aquela que planeia usar, inicie sessão nela uma vez a partir do seu terminal, e está tudo a postos. O specrails deteta automaticamente quais os fornecedores presentes.
+
+> Se alguma vez vir uma ferramenta assinalada como em falta, a app mostra uma ligação **Mais informações** com comandos de instalação prontos a copiar e colar, adaptados ao seu sistema operativo (Homebrew no macOS, winget no Windows, apt/dnf no Linux). Pode voltar a verificar a qualquer momento sem reiniciar.
+
+## 3. Primeira utilização — o ecrã de boas-vindas
+
+Da primeira vez que abrir o specrails, vai dar com um **ecrã de boas-vindas** limpo. Ainda não há projetos, por isso a app convida-o a adicionar o primeiro.
+
+Vai ver:
+
+- Uma breve descrição do que o specrails faz.
+- Um único botão **Adicionar o seu primeiro projeto**.
+
+É todo o processo de arranque — sem conta para criar, sem registo. O specrails funciona inteiramente na sua máquina.
+
+Clique em **Adicionar o seu primeiro projeto** e continue para [Adicionar o seu primeiro projeto](adding-your-first-project).

package/docs/guide/pt/getting-started/3-adding-your-first-project.md

@@ -0,0 +1,58 @@
+# Adicionar o seu primeiro projeto
+
+Um projeto é apenas uma pasta no seu computador que contém uma base de código. Vamos ligar uma.
+
+## Abrir a janela Adicionar projeto
+
+Clique em **Adicionar o seu primeiro projeto** no ecrã de boas-vindas (ou, mais tarde, no botão **Adicionar projeto** na barra lateral esquerda). Aparece uma pequena janela.
+
+## Preencher os dados
+
+**Pasta do projeto** *(obrigatório)*
+
+Aponte o specrails para a pasta que contém o seu código. Na app de desktop pode clicar no ícone de pasta para navegar e escolhê-la visualmente, ou colar o caminho completo. Esta deve ser a raiz do seu repositório — a pasta que contém o seu código e (normalmente) um diretório `.git`.
+
+**Nome do projeto** *(opcional)*
+
+Uma etiqueta amigável mostrada na barra lateral. Se a deixar em branco, o specrails usa o nome da pasta.
+
+**Fornecedores**
+
+Escolha que fornecedor(es) de IA este projeto deve usar. O specrails mostra-lhe os que detetou na sua máquina:
+
+- 🤖 **Claude**
+- ⚡ **Codex**
+- ✨ **Gemini**
+
+Os fornecedores que não encontrou aparecem a cinzento e marcados como *não encontrado* — instale e inicie sessão num deles e volte a abrir a janela. Por predefinição, todos os fornecedores disponíveis ficam pré-selecionados, mas pode desmarcar até ficar apenas com o que pretende. Se escolher mais do que um, o **primeiro** torna-se o fornecedor predefinido do projeto; mais tarde poderá escolher por tarefa.
+
+> Uma verificação rápida corre em segundo plano para confirmar que as ferramentas necessárias estão presentes. Se faltar algo essencial, o botão **Adicionar** permanece desativado e uma ligação **Mais informações** dá-lhe os comandos de instalação exatos.
+
+Clique em **Adicionar** para continuar.
+
+## Uma configuração que corre em segundos
+
+Se a pasta já tiver o specrails configurado, está concluído — o projeto aparece instantaneamente na sua barra lateral.
+
+Se for um projeto novo, corre um breve **assistente de configuração**. Tem três passos:
+
+1. **Configurar** — confirme o essencial para cada fornecedor que escolheu.
+2. **Instalar** — o specrails prepara o projeto automaticamente. Esta é a instalação *rápida*: agentes de template prontos a usar, instalados em segundos. Vai ver um log em direto enquanto corre.
+3. **Concluído** — um resumo a confirmar que está tudo pronto.
+
+Num projeto com vários fornecedores, a instalação corre uma vez por fornecedor, um a seguir ao outro, e o passo Concluído mostra um cartão para cada um.
+
+## O que é instalado
+
+A configuração é deliberadamente leve e **não invasiva**. O specrails acrescenta uma pequena quantidade de configuração ao seu projeto para que o pipeline saiba como funcionar:
+
+- Uma pasta `.specrails/` que contém os perfis de agentes e as definições locais do seu projeto.
+- Definições de agentes em `.claude/agents/` que dão vida ao pipeline Arquiteto → Developer → Revisor → Ship.
+
+E é só isto — o specrails não reescreve o seu código-fonte durante a configuração, e estes ficheiros podem ser incluídos no commit sem problemas, caso queira partilhar a configuração com a sua equipa.
+
+> **Prefere a configuração aprofundada?** A app traz de propósito a instalação rápida por templates. Se preferir o fluxo enriquecido por IA (análise da base de código e personas de agentes personalizadas), pode executar `npx specrails-core@latest init` a partir da pasta do projeto num terminal.
+
+## Está dentro
+
+Assim que a configuração terminar, o specrails leva-o diretamente para o dashboard do seu projeto. É hora do tour — veja [O tour pelo dashboard](the-dashboard-tour).

package/docs/guide/pt/getting-started/4-the-dashboard-tour.md

@@ -0,0 +1,53 @@
+# O tour pelo dashboard
+
+Com um projeto adicionado, está a olhar para o seu **dashboard do projeto** — a sua base para transformar specs em código entregue. Aqui fica como se orientar.
+
+## A visão geral
+
+A janela tem três zonas:
+
+- **Barra lateral esquerda** — a sua lista de projetos. Clique em qualquer projeto para mudar para ele instantaneamente; tudo o resto na janela se atualiza em conformidade. O botão **Adicionar projeto** também vive aqui.
+- **Área principal** — o dashboard do projeto ativo: as suas specs e o pipeline que as executa.
+- **Barra lateral direita** — a navegação entre as secções do projeto atual.
+
+## O dashboard principal
+
+É aqui que o trabalho acontece. O dashboard mostra:
+
+- **As suas specs** — os tickets que criou, organizados por estado (de Backlog / Por fazer até Concluído). Pode vê-los como uma lista, uma grelha ou cartões tipo post-it, conforme preferir.
+- **Uma forma de adicionar uma spec** — comece um novo trabalho. Pode escrever uma spec rápida diretamente, ou abrir um chat **Explorar** guiado que o ajuda a moldá-la através de conversa e redige o ticket por si.
+- **Rails** — estas são as pistas onde as specs são construídas. Largue uma spec num rail e lance-o para a enviar pelo pipeline Arquiteto → Developer → Revisor → Ship. Vários rails podem correr ao mesmo tempo, por isso pode trabalhar em várias coisas em paralelo.
+
+Quando uma spec está em execução, vai ver o progresso do seu pipeline e os logs em direto — a saída em tempo real da IA enquanto desenha, programa e revê a sua alteração.
+
+## A barra lateral direita: secções do projeto
+
+A barra lateral direita é o seu painel de comutação para o projeto atual. Passe o rato por cima para a expandir, ou afixe-a aberta. As secções que vai encontrar:
+
+- **Dashboard** — o quadro de specs e os rails (onde estava agora mesmo).
+- **Jobs** — todas as execuções do pipeline deste projeto, passadas e presentes, com estado, duração e a possibilidade de aprofundar o detalhe e os logs de qualquer execução.
+- **Analytics** — quanto lhe está a custar a utilização de IA. Gastos divididos por dia, por atividade, por modelo e por ticket — para que não haja surpresas.
+- **Agentes** — os perfis de agentes do seu projeto: que agentes correm no pipeline e que modelos de IA usam. *(Apenas projetos com Claude.)*
+- **Code** — um explorador de ficheiros só de leitura com resumos de IA em linguagem simples, e etiquetas a mostrar que ficheiros a IA tocou. Ótimo para quem não programa mas quer acompanhar.
+- **Integrações** — extras opcionais, como ligar as suas specs a um quadro do **Jira** ou ativar ferramentas adicionais para a IA.
+- **Definições** — opções por projeto (telemetria, orçamentos, configuração de fornecedores e muito mais).
+
+> Algumas secções só aparecem quando fazem sentido para os fornecedores que escolheu — por exemplo, **Agentes** é específico do Claude. Se não vir uma secção, é simplesmente porque não se aplica à configuração deste projeto.
+
+## A barra de estado
+
+Uma faixa fina percorre o fundo da janela. É pequena, mas prática:
+
+- **Indicador de ligação** (à esquerda) — um ponto colorido e uma etiqueta a mostrar que a app está ativa: verde para *ligado*, âmbar enquanto *reconecta*, azul enquanto *sincroniza* logo após uma reconexão. Raramente vai precisar dele, mas é tranquilizador quando precisa.
+- **Gasto total** (à direita) — um total acumulado do que gastou, para que o custo esteja sempre a um relance de distância.
+- **Botão do terminal** (à direita ao fundo) — abre o painel de terminal integrado. Carregue em **Cmd+J** (macOS) ou **Ctrl+J** (Windows/Linux) para o alternar a qualquer momento. É uma shell completa, aberta diretamente na pasta do seu projeto.
+
+## Alguns atalhos úteis
+
+- **Cmd/Ctrl+B** — afixar ou recolher as barras laterais.
+- **Cmd/Ctrl+J** — alternar o painel de terminal.
+- **Cmd/Ctrl+K** — abrir a pesquisa.
+
+## Para onde ir a seguir
+
+E aqui está a vista de conjunto. A partir daqui, o passo natural é **adicionar uma spec** e lançá-la num rail — veja o pipeline correr de ponta a ponta e, depois, consulte **Analytics** para ver quanto custou. Bem-vindo a bordo.