# Instalar o Ampliar

Guia oficial de instalação da Verbo. Endereço permanente: https://www.verbolab.co/dev/ampliar.
Versão desta receita: **v0.2.0**. Destinado ao responsável técnico da organização e ao agente
que o acompanha. Não exige acesso ao repositório privado do produto.

O Ampliar coleta documentos de pastas autorizadas, extrai seu conteúdo e indexa um acervo
persistente. As pessoas consultam esse acervo pela porta MCP, com credenciais individuais.
Esta entrega prepara o piloto com **Google Drive** e cliente MCP que aceite Bearer token.
A instalação remota precisa ser validada na sua infraestrutura antes de convidar usuários.

## 1. Confirme o ambiente e os responsáveis

Antes de executar, confirme com a pessoa responsável:

- Organização, plataforma (Railway, AWS EC2 ou host próprio), projeto e ambiente de destino.
- Pastas Drive autorizadas e sensibilidade de cada fonte: aberta, restrita ou pessoal.
  Para fonte pessoal, confirme também o dono. Não infira permissões pelo nome da pasta.
- Pessoas que consultarão o acervo, organizações e nível de sensibilidade de cada uma.
- Conta GitHub do instalador com acesso de leitura concedido pela Verbo à imagem Ampliar.
- Duas chaves OpenAI reais e distintas, uma para ingestão e outra para consulta.
- Service account Google com acesso de leitura às pastas escolhidas e seu JSON de credencial.
- PostgreSQL com pgvector, disco persistente para `/brain` e HTTPS para a porta MCP.

No host próprio/EC2, instale Docker Engine e Docker Compose v2. A imagem da aplicação é
Linux AMD64; escolha infraestrutura compatível. O Railway executa a mesma imagem, com
banco e volume configurados na plataforma. Custos de infraestrutura e modelos ficam na
conta da organização. Não crie recursos pagos antes de confirmar o ambiente com ela.

## 2. Baixe a versão e verifique o pacote

Os documentos e exemplos são públicos. A imagem executável exige a autorização da Verbo.
Baixe estes dois anexos da mesma release:

- [Pacote de instalação v0.2.0](https://github.com/verbo-lab/verbo-ampliar-notas/releases/download/v0.2.0/ampliar-instalacao-v0.2.0.zip)
- [SHA256SUMS.txt](https://github.com/verbo-lab/verbo-ampliar-notas/releases/download/v0.2.0/SHA256SUMS.txt)
- [Notas da versão, digest e limitações](https://github.com/verbo-lab/verbo-ampliar-notas/releases/tag/v0.2.0)

Em um diretório vazio, com os dois arquivos baixados:

```sh
sha256sum -c SHA256SUMS.txt
unzip ampliar-instalacao-v0.2.0.zip
chmod +x infra/operar.sh
```

No macOS, use `shasum -a 256 -c SHA256SUMS.txt` para a conferência.
O resultado deve ser `OK`. `IMAGEM.txt` contém a referência por digest, também presente em
`.env.example`. Confira a correspondência com as notas da versão. Não use uma tag flutuante.
Os demais documentos necessários estão dentro do ZIP; seus caminhos abaixo são locais.

## 3. Autorize o download da imagem

A Verbo concede **Read** à conta GitHub do instalador no pacote privado
`ghcr.io/verbo-lab/ampliar`. Na própria conta, o instalador cria um **personal access token
classic**, com `read:packages`; autorize SSO quando exigido. O token fica com o instalador,
não é uma credencial MCP e não deve ser enviado por e-mail ou colado na conversa do agente.
Referência: [autenticação do GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry).

No host de instalação, execute interativamente:

```sh
docker login ghcr.io -u SEU_USUARIO_GITHUB
# Cole o token somente no prompt de senha do Docker.
docker pull "$(cat IMAGEM.txt)"
```

No Railway, o download de imagens privadas exige o plano Pro, conforme a
[documentação de registros privados](https://docs.railway.com/builds/private-registries).
Confirme esse pré-requisito com o responsável. Configure a mesma conta/token no acesso ao registro privado da origem Docker
Image do serviço. Use a imagem por digest de `IMAGEM.txt`. Não use deploy por código-fonte.
Falha `denied` exige conferir conta autorizada, escopo do token e SSO com a Verbo; não crie
credencial fictícia nem torne a imagem pública para contornar a falha.

## 4. Siga a receita da plataforma

Leia `AGENTS.md` do pacote. Ele aponta para a ordem de instalação e suas verificações.

- **Railway:** siga `docs/deploy-railway.md`. Crie banco com pgvector e serviço `estante`,
  com volume em `/brain`, uma réplica e origem na imagem privada. Configure as variáveis
  usando `.env.example` como referência; o descritor não cria banco nem volume.
- **AWS EC2:** siga `docs/deploy-aws.md`. O template de infraestrutura é um ponto de partida;
  exige preparar Docker, montar o disco e configurar HTTPS. ECS/Fargate ainda não têm
  adaptador ensaiado nesta entrega.
- **Host próprio:** siga `docs/instalacao/roteiro.md`, `docs/instalacao/pacote.md` e
  `docs/instalacao/operar.md`. Copie `.env.example` para `.env`, preencha os valores reais,
  prepare os dois cadastros no volume e execute `./infra/operar.sh subir`.

A configuração válida vive em `/brain/_config/`, fora da imagem e do Git. O pacote traz
somente exemplos de fontes e usuários: substitua placeholders. Confirme sensibilidade e dono
com o responsável antes de preencher. Gere uma credencial aleatória individual forte e
registre somente seu hash SHA-256 no cadastro, conforme os exemplos. Entregue o valor
original a cada pessoa por canal seguro. Reiniciar não substitui os cadastros existentes.

Não salve `.env`, tokens, JSON Google nem cadastros reais em repositório. A porta MCP de
usuário usa `/mcp`; o servidor nativo GBrain não deve ser exposto aos usuários.

## 5. Prove que a instalação funciona

Siga os comandos canônicos de `docs/instalacao/operar.md`, usando o adaptador escolhido:
provisionar, doutor, inventário, ingestão e relatório. Antes da primeira ingestão,
`nunca_rodou_ingestao` é uma pendência esperada; depois dela, investigue qualquer falha.
Conecte o cliente conforme `docs/conectar-mcp.md`.

A instalação só está pronta para o piloto quando houver evidência de:

1. Inventário da pasta real e relatório que explique todos os arquivos encontrados.
2. Busca e abertura via MCP de um documento conhecido, com credencial individual.
3. Recusa de acesso fora do escopo e revogação válida na próxima chamada.
4. Atualização de documento refletida após nova ingestão, sem duplicação na repetição.
5. Reinício preservando acervo, cadastros, trilha e consulta.
6. Backup e restauração em destino isolado, com consulta funcionando no destino restaurado.

`/health` sozinho não aprova a instalação. OAuth para conectores web/Desktop e consulta de
fontes Microsoft ainda estão pendentes nesta versão; use o piloto Drive/Bearer descrito aqui.

## 6. Entregue o registro ao responsável

Informe plataforma e ambiente, versão/digest, URL MCP, fontes e escopos aprovados, resultado
do doutor e relatório, evidências de consulta/revogação/restauração e pendências.
Não inclua segredos. A rotina está em `docs/operacao-semanal.md`.

Se travar, leia `docs/instalacao/falhas.md`, registre comando, erro sem segredos e versão.
Encaminhe ao contato da Verbo que acompanhou a contratação. Não declare sucesso parcial
como instalação concluída. O portal de clientes e a concessão automática de acesso ainda
não fazem parte desta entrega; a liberação inicial é feita pela Verbo.