From e6e6a253f89977ef73ba91a0b98ee064dce6831d Mon Sep 17 00:00:00 2001
From: Rhuan Barreto <rhuan@barreto.work>
Date: Fri, 20 Mar 2026 21:15:08 +0100
Subject: [PATCH] docs: add GitHub Actions and proto plugin to installation and
 CI guides

Document the official archgate/check-action and archgate/setup-action
GitHub Actions as the recommended CI integration method. Replace the
proto npm-globals workaround with the native archgate/proto-plugin as
the primary proto installation method. Updates both EN and PT-BR pages.
---
 docs/public/llms-full.txt                     | 99 ++++++++++++++++---
 .../docs/getting-started/installation.mdx     | 37 +++++--
 .../content/docs/guides/ci-integration.mdx    | 65 ++++++++++--
 .../pt-br/getting-started/installation.mdx    | 37 +++++--
 .../docs/pt-br/guides/ci-integration.mdx      | 65 ++++++++++--
 5 files changed, 258 insertions(+), 45 deletions(-)

diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt
index 7697ea7d..b4e5dcdf 100644
--- a/docs/public/llms-full.txt
+++ b/docs/public/llms-full.txt
@@ -226,25 +226,42 @@ archgate --version
 
 You should see the installed version printed to stdout.
 
-## Proto toolchain users
+## Install via proto
 
-If you manage Node.js with [proto](https://moonrepo.dev/proto) (moonrepo's toolchain manager), globally installed npm binaries require an additional setup step.
+If you use [proto](https://moonrepo.dev/proto) (moonrepo's toolchain manager), you can install Archgate directly as a proto plugin — no Node.js or npm required.
 
-Add to your proto configuration:
+Add the plugin to your `.prototools`:
 
 ```toml
-# ~/.proto/config.toml
-[tools.npm]
-shared-globals-dir = true
+[plugins.tools]
+archgate = "github://archgate/proto-plugin"
 ```
 
-Then add the globals directory to your shell profile (`.bashrc`, `.zshrc`, or equivalent):
+Then install and use it like any other proto tool:
 
 ```bash
-export PATH="$HOME/.proto/tools/node/globals/bin:$PATH"
+proto install archgate
+archgate check
+```
+
+Proto manages the binary for you, including version pinning and auto-installation. To pin a specific version, add it at the root of `.prototools`:
+
+```toml
+archgate = "0.15.0"
+
+[plugins.tools]
+archgate = "github://archgate/proto-plugin"
 ```
 
-Restart your shell, then run `npm install -g archgate` again. The `archgate` command should now be available globally.
+You can also list available versions and manage installations with proto commands:
+
+```bash
+proto list-remote archgate   # list available versions
+proto install archgate 0.15.0  # install a specific version
+proto pin archgate 0.15.0      # pin version in .prototools
+```
+
+If you prefer `npm install -g archgate` instead of the proto plugin, you need to configure proto to expose global npm binaries. Add `shared-globals-dir = true` under `[tools.npm]` in `~/.proto/config.toml`, then add `$HOME/.proto/tools/node/globals/bin` to your shell PATH.
 
 ## Next steps
 
@@ -856,22 +873,71 @@ Archgate checks fit into any CI system that respects exit codes. Add a single st
 
 ## GitHub Actions
 
-The simplest setup is a dedicated job that installs Archgate and runs `archgate check`:
+The fastest way to add Archgate to GitHub Actions is with the official [`archgate/check-action`](https://github.com/archgate/check-action). It installs the CLI, runs `archgate check --ci`, and outputs violations as inline annotations on the pull request's "Files changed" tab:
 
 ```yaml
-name: ADR Compliance
-on: [push, pull_request]
+name: Archgate
+on:
+  pull_request:
+  push:
+    branches: [main]
 
 jobs:
   check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npm install -g archgate
-      - run: archgate check
+      - uses: archgate/check-action@v1
 ```
 
-This installs the CLI globally and runs all ADR rules. If any rule reports a violation with `error` severity, the step exits with code 1 and the job fails.
+That's it — no Node.js setup, no install step. If any rule reports a violation with `error` severity, the job fails with exit code 1.
+
+### Pin a version
+
+```yaml
+- uses: archgate/check-action@v1
+  with:
+    version: v0.15.0
+```
+
+### Setup-only action
+
+If you need to run Archgate commands beyond `check` (e.g. `archgate adr list --json`), use [`archgate/setup-action`](https://github.com/archgate/setup-action) to install the CLI and add it to PATH, then run whatever commands you need:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: archgate/setup-action@v1
+  - run: archgate check --ci
+  - run: archgate adr list --json
+```
+
+### Cross-platform workflow
+
+Both actions support Ubuntu, macOS, and Windows runners:
+
+```yaml
+jobs:
+  check:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: archgate/check-action@v1
+```
+
+### Manual setup
+
+If you prefer not to use the official actions, you can install Archgate manually:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - run: npm install -g archgate
+  - run: archgate check
+```
 
 ## GitHub Actions annotations
 
@@ -883,6 +949,9 @@ Use `--ci` to output violations as GitHub Actions workflow annotations. These ap
 
 The `--ci` flag produces `::error` and `::warning` annotations in the format GitHub Actions expects. Each annotation includes the ADR ID, rule ID, file path, and line number.
 
+:::note
+The `archgate/check-action` passes `--ci` automatically — you only need this flag when running `archgate check` manually.
+
 ## Machine-readable output
 
 Use `--json` for structured output that other tools can parse:
diff --git a/docs/src/content/docs/getting-started/installation.mdx b/docs/src/content/docs/getting-started/installation.mdx
index a00e4a03..2a150388 100644
--- a/docs/src/content/docs/getting-started/installation.mdx
+++ b/docs/src/content/docs/getting-started/installation.mdx
@@ -113,25 +113,44 @@ archgate --version
 
 You should see the installed version printed to stdout.
 
-## Proto toolchain users
+## Install via proto
 
-If you manage Node.js with [proto](https://moonrepo.dev/proto) (moonrepo's toolchain manager), globally installed npm binaries require an additional setup step.
+If you use [proto](https://moonrepo.dev/proto) (moonrepo's toolchain manager), you can install Archgate directly as a proto plugin — no Node.js or npm required.
 
-Add to your proto configuration:
+Add the plugin to your `.prototools`:
 
 ```toml
-# ~/.proto/config.toml
-[tools.npm]
-shared-globals-dir = true
+[plugins.tools]
+archgate = "github://archgate/proto-plugin"
 ```
 
-Then add the globals directory to your shell profile (`.bashrc`, `.zshrc`, or equivalent):
+Then install and use it like any other proto tool:
 
 ```bash
-export PATH="$HOME/.proto/tools/node/globals/bin:$PATH"
+proto install archgate
+archgate check
 ```
 
-Restart your shell, then run `npm install -g archgate` again. The `archgate` command should now be available globally.
+Proto manages the binary for you, including version pinning and auto-installation. To pin a specific version, add it at the root of `.prototools`:
+
+```toml
+archgate = "0.15.0"
+
+[plugins.tools]
+archgate = "github://archgate/proto-plugin"
+```
+
+You can also list available versions and manage installations with proto commands:
+
+```bash
+proto list-remote archgate   # list available versions
+proto install archgate 0.15.0  # install a specific version
+proto pin archgate 0.15.0      # pin version in .prototools
+```
+
+:::note[Using npm globals with proto?]
+If you prefer `npm install -g archgate` instead of the proto plugin, you need to configure proto to expose global npm binaries. Add `shared-globals-dir = true` under `[tools.npm]` in `~/.proto/config.toml`, then add `$HOME/.proto/tools/node/globals/bin` to your shell PATH.
+:::
 
 ## Next steps
 
diff --git a/docs/src/content/docs/guides/ci-integration.mdx b/docs/src/content/docs/guides/ci-integration.mdx
index 3fb90f87..f47361b9 100644
--- a/docs/src/content/docs/guides/ci-integration.mdx
+++ b/docs/src/content/docs/guides/ci-integration.mdx
@@ -7,22 +7,71 @@ Archgate checks fit into any CI system that respects exit codes. Add a single st
 
 ## GitHub Actions
 
-The simplest setup is a dedicated job that installs Archgate and runs `archgate check`:
+The fastest way to add Archgate to GitHub Actions is with the official [`archgate/check-action`](https://github.com/archgate/check-action). It installs the CLI, runs `archgate check --ci`, and outputs violations as inline annotations on the pull request's "Files changed" tab:
 
 ```yaml
-name: ADR Compliance
-on: [push, pull_request]
+name: Archgate
+on:
+  pull_request:
+  push:
+    branches: [main]
 
 jobs:
   check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npm install -g archgate
-      - run: archgate check
+      - uses: archgate/check-action@v1
+```
+
+That's it — no Node.js setup, no install step. If any rule reports a violation with `error` severity, the job fails with exit code 1.
+
+### Pin a version
+
+```yaml
+- uses: archgate/check-action@v1
+  with:
+    version: v0.15.0
+```
+
+### Setup-only action
+
+If you need to run Archgate commands beyond `check` (e.g. `archgate adr list --json`), use [`archgate/setup-action`](https://github.com/archgate/setup-action) to install the CLI and add it to PATH, then run whatever commands you need:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: archgate/setup-action@v1
+  - run: archgate check --ci
+  - run: archgate adr list --json
+```
+
+### Cross-platform workflow
+
+Both actions support Ubuntu, macOS, and Windows runners:
+
+```yaml
+jobs:
+  check:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: archgate/check-action@v1
 ```
 
-This installs the CLI globally and runs all ADR rules. If any rule reports a violation with `error` severity, the step exits with code 1 and the job fails.
+### Manual setup
+
+If you prefer not to use the official actions, you can install Archgate manually:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - run: npm install -g archgate
+  - run: archgate check
+```
 
 ## GitHub Actions annotations
 
@@ -34,6 +83,10 @@ Use `--ci` to output violations as GitHub Actions workflow annotations. These ap
 
 The `--ci` flag produces `::error` and `::warning` annotations in the format GitHub Actions expects. Each annotation includes the ADR ID, rule ID, file path, and line number.
 
+:::note
+The `archgate/check-action` passes `--ci` automatically — you only need this flag when running `archgate check` manually.
+:::
+
 ## Machine-readable output
 
 Use `--json` for structured output that other tools can parse:
diff --git a/docs/src/content/docs/pt-br/getting-started/installation.mdx b/docs/src/content/docs/pt-br/getting-started/installation.mdx
index c0f1f85f..adb2da62 100644
--- a/docs/src/content/docs/pt-br/getting-started/installation.mdx
+++ b/docs/src/content/docs/pt-br/getting-started/installation.mdx
@@ -113,25 +113,44 @@ archgate --version
 
 Você deverá ver a versão instalada impressa no stdout.
 
-## Usuários do Proto toolchain
+## Instalar via proto
 
-Se você gerencia o Node.js com o [proto](https://moonrepo.dev/proto) (gerenciador de toolchain do moonrepo), binários npm instalados globalmente requerem um passo adicional de configuração.
+Se você usa o [proto](https://moonrepo.dev/proto) (gerenciador de toolchain do moonrepo), pode instalar o Archgate diretamente como um plugin proto — sem necessidade de Node.js ou npm.
 
-Adicione à sua configuração do proto:
+Adicione o plugin ao seu `.prototools`:
 
 ```toml
-# ~/.proto/config.toml
-[tools.npm]
-shared-globals-dir = true
+[plugins.tools]
+archgate = "github://archgate/proto-plugin"
 ```
 
-Depois adicione o diretório de globais ao perfil do seu shell (`.bashrc`, `.zshrc` ou equivalente):
+Depois instale e use como qualquer outra ferramenta proto:
 
 ```bash
-export PATH="$HOME/.proto/tools/node/globals/bin:$PATH"
+proto install archgate
+archgate check
 ```
 
-Reinicie seu shell e execute `npm install -g archgate` novamente. O comando `archgate` agora deverá estar disponível globalmente.
+O proto gerencia o binário para você, incluindo fixação de versão e instalação automática. Para fixar uma versão específica, adicione na raiz do `.prototools`:
+
+```toml
+archgate = "0.15.0"
+
+[plugins.tools]
+archgate = "github://archgate/proto-plugin"
+```
+
+Você também pode listar versões disponíveis e gerenciar instalações com comandos do proto:
+
+```bash
+proto list-remote archgate     # listar versões disponíveis
+proto install archgate 0.15.0  # instalar uma versão específica
+proto pin archgate 0.15.0      # fixar versão no .prototools
+```
+
+:::note[Usando npm globals com proto?]
+Se você preferir `npm install -g archgate` ao invés do plugin proto, precisa configurar o proto para expor binários npm globais. Adicione `shared-globals-dir = true` em `[tools.npm]` no `~/.proto/config.toml`, e depois adicione `$HOME/.proto/tools/node/globals/bin` ao PATH do seu shell.
+:::
 
 ## Próximos passos
 
diff --git a/docs/src/content/docs/pt-br/guides/ci-integration.mdx b/docs/src/content/docs/pt-br/guides/ci-integration.mdx
index b26fa559..300eac83 100644
--- a/docs/src/content/docs/pt-br/guides/ci-integration.mdx
+++ b/docs/src/content/docs/pt-br/guides/ci-integration.mdx
@@ -7,22 +7,71 @@ As verificações do Archgate funcionam em qualquer sistema de CI que respeite c
 
 ## GitHub Actions
 
-A configuração mais simples é um job dedicado que instala o Archgate e executa `archgate check`:
+A forma mais rápida de adicionar o Archgate ao GitHub Actions é com a action oficial [`archgate/check-action`](https://github.com/archgate/check-action). Ela instala o CLI, executa `archgate check --ci` e exibe violações como anotações inline na aba "Files changed" do pull request:
 
 ```yaml
-name: ADR Compliance
-on: [push, pull_request]
+name: Archgate
+on:
+  pull_request:
+  push:
+    branches: [main]
 
 jobs:
   check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npm install -g archgate
-      - run: archgate check
+      - uses: archgate/check-action@v1
+```
+
+Isso é tudo — sem configuração de Node.js, sem passo de instalação. Se qualquer regra reportar uma violação com severidade `error`, o job falha com código de saída 1.
+
+### Fixar uma versão
+
+```yaml
+- uses: archgate/check-action@v1
+  with:
+    version: v0.15.0
+```
+
+### Action apenas de setup
+
+Se você precisa executar comandos do Archgate além do `check` (ex: `archgate adr list --json`), use [`archgate/setup-action`](https://github.com/archgate/setup-action) para instalar o CLI e adicioná-lo ao PATH, e depois execute os comandos necessários:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: archgate/setup-action@v1
+  - run: archgate check --ci
+  - run: archgate adr list --json
+```
+
+### Workflow multiplataforma
+
+Ambas as actions suportam runners Ubuntu, macOS e Windows:
+
+```yaml
+jobs:
+  check:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: archgate/check-action@v1
 ```
 
-Isso instala o CLI globalmente e executa todas as regras de ADR. Se qualquer regra reportar uma violação com severidade `error`, o passo termina com código 1 e o job falha.
+### Configuração manual
+
+Se você preferir não usar as actions oficiais, pode instalar o Archgate manualmente:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - run: npm install -g archgate
+  - run: archgate check
+```
 
 ## Anotações do GitHub Actions
 
@@ -34,6 +83,10 @@ Use `--ci` para exibir violações como anotações de workflow do GitHub Action
 
 A flag `--ci` produz anotações `::error` e `::warning` no formato esperado pelo GitHub Actions. Cada anotação inclui o ID do ADR, o ID da regra, o caminho do arquivo e o número da linha.
 
+:::note
+A `archgate/check-action` passa `--ci` automaticamente — você só precisa dessa flag ao executar `archgate check` manualmente.
+:::
+
 ## Saída legível por máquina
 
 Use `--json` para saída estruturada que outras ferramentas podem processar: