Instalar Sanad

O que Instalar Sanad faz?

Guie o usuário desde a inspeção até uma instalação ou atualização verificada do Sanad. Mantenha os fluxos de trabalho de versão estável (release-user) e desenvolvimento (developer-source) separados.

Regras de Segurança

• Inspecione antes de alterar qualquer coisa. Trate instalação, substituição de pacotes, registro de serviço, inicialização de aplicativo e atualizações Git como mutações que exigem aprovação informada do usuário.
• Nunca pesquise um diretório home inteiro ou disco em busca de um checkout. Inspecione apenas o diretório atual, um caminho fornecido pelo usuário e locais padrão de comandos instalados. Pergunte pelo caminho do projeto quando não puder ser identificado com segurança.
• Nunca sobrescreva, redefina, limpe, stash, faça commit ou descarte um repositório sujo a menos que o usuário autorize explicitamente essa ação exata.
• Nunca solicite, cite, registre ou reconstrua tokens de acesso, tokens de atualização, credenciais de provedor, segredos de assinatura ou conteúdo do usuário. Apenas para uma instalação remota operada por agente e explicitamente autorizada, aceite o comando completo Adicionar dispositivo do usuário contendo seu token de criação de uso único e curta duração. Valide o bootstrap oficial, transmita-o sem eco, rastreamento ou persistência em artefatos do projeto, e nunca extraia/reconstrua seu token. Explique que este consentimento cobre a exposição do comando de criação no histórico de chat/ferramenta e que o comando do instalador gerado pode usar argumentos de token; não afirme exposição zero. Mantenha os argumentos de transporte SSH livres de credenciais. Se o usuário não aceitar essa exposição, peça para ele executar diretamente ou usar o login interativo do Portal. Esta exceção nunca cobre credenciais duráveis.
• Use apenas fontes oficiais do Sanad:
  • repositório: https://github.com/EastStarAI/sanad-agent
  • releases: https://github.com/EastStarAI/sanad-agent/releases/latest
  • instaladores: https://sanad.eaststarai.com/install.sh e https://sanad.eaststarai.com/install.ps1
• Não desabilite controles de segurança do sistema operacional. Leia as notas de versão mais recentes antes de descrever a assinatura atual ou suporte de plataforma.
• Preserve o diretório Home do Sanad e os espaços de trabalho do usuário durante instalação e atualização.

Caminho Rápido para Google Cloud

Para uma solicitação de servidor Google Cloud / GCP / nuvem gratuita, leia references/google-cloud-free-tier.md e siga essa rota especializada de versão estável em vez de repetir o questionário genérico local/fonte abaixo. Ela gerencia pré-requisitos, no máximo duas perguntas iniciais, reutilização de recursos, provisionamento elegível, pareamento just-in-time e verificação mínima integrada. Mantenha as regras de segurança acima. Não prometa uma conta zero incondicional ou duplique uma franquia gratuita existente.

1. Inspecione o Alvo

Determine se os comandos serão executados na máquina atual do usuário ou em uma máquina remota. Não presuma que a máquina que hospeda o Sanad Client é a máquina que deve hospedar o Sanad Agent.

Colete evidências somente leitura:

1. Identifique o sistema operacional e a arquitetura.
2. Verifique se sanad e sanad-dev estão no PATH.
3. Verifique o executável de propriedade do instalador quando relevante:
   • macOS/Linux: ${SANAD_HOME:-$HOME/.sanad}/bin/sanad
   • Windows: $env:SANAD_HOME\bin\sanad.exe, ou $HOME\.sanad\bin\sanad.exe quando SANAD_HOME não estiver definido.
4. Se o diretório atual ou fornecido for um checkout Git, inspecione: git rev-parse --show-toplevel, git remote -v, git status --short --branch e git worktree list. Aceite como fonte do Sanad apenas quando sua identidade de repositório corresponder a EastStarAI/sanad-agent ou o usuário confirmar um fork intencional.
5. Consulte versões instaladas e status do serviço apenas através de um executável Sanad resolvido. Não falhe apenas porque sanad está ausente do PATH.

Resuma o que existe antes de propor uma alteração.

2. Selecione o Fluxo de Trabalho

Se a solicitação do usuário já tornar o fluxo de trabalho explícito, confirme o alvo e continue. Caso contrário, apresente estas opções e pergunte qual delas o usuário deseja:

Caminho	Melhor para	Resultado	Desvantagem
Versão estável / usuário	Uso normal diário	Cliente empacotado e versão de Agente verificada	Estável e simples; a fonte não é editável
Fonte / desenvolvedor	Contribuir, depurar ou alterar o Sanad	Checkout do repositório executado via sanad-dev	Editável e testável; requer ferramentas de desenvolvimento e mais espaço em disco

Para o caminho de versão estável, determine a topologia:

• Este desktop: instale o Sanad Client; Executar Localmente instala e inicia o Agente correspondente no mesmo computador.
• Outro computador ou servidor: mantenha o Cliente no desktop, celular ou web e instale apenas o Sanad Agent na máquina de destino.
• Apenas Cliente: instale um Cliente desktop/móvel ou use o Web Client sem instalar um Agente nesse dispositivo.

Indique as ações exatas, destinos e impacto no serviço. Obtenha aprovação antes de baixar, instalar, substituir, registrar, iniciar ou reiniciar.

3. Caminho de Versão Estável / Usuário

Instalar o Cliente e o Agente Local

1. Leia a versão oficial mais recente e seu manifesto. Selecione apenas o pacote do Cliente correspondente à plataforma e arquitetura confirmadas.
2. Verifique o artefato usando as somas de verificação, assinaturas e orientações de plataforma publicadas por essa versão. Não generalize o status de assinatura de uma versão mais antiga para a versão atual.
3. Instale o Cliente usando o fluxo normal do sistema operacional. Não ignore silenciosamente os prompts de revisão de aplicativo ou segurança.
4. Peça ao usuário para iniciar o Sanad Client e escolher Executar Localmente. Explique que o Cliente baixa, verifica, registra, inicia e conecta ao Agente local correspondente; uma conta Sanad e token de pareamento não são necessários.
5. Verifique se o Cliente pode alcançar o Agente local antes de declarar sucesso.

Para Android, iOS e Web, siga a disponibilidade indicada nas notas de versão atuais. Essas plataformas fornecem a interface, mas não hospedam o serviço nativo do Agente.

Instalar um Agente em Outro Computador ou Servidor

Ofereça duas opções iguais:

1. Parear através do Sanad Client: abra Configurações, depois clique em + ao lado de Dispositivos na barra lateral de Configurações para abrir Adicionar dispositivo. Peça ao usuário para executar o comando gerado completo na máquina de destino, ou aceite o comando gerado completo para uma instalação remota autorizada sob a exceção de token de criação de uso único acima. Nunca peça pela credencial separadamente ou faça eco do comando em relatórios.
2. Instalar o Agente diretamente: escolha o modo de login via Portal ou somente local e execute o instalador oficial correspondente após aprovação.

Para um terminal macOS/Linux operado por agente, evite um prompt ambíguo:

curl -fsSL https://sanad.eaststarai.com/install.sh | bash -s -- --login

Use --no-login quando o usuário escolher explicitamente o modo somente local.

Para um terminal Windows PowerShell operado por agente:

& ([scriptblock]::Create((irm https://sanad.eaststarai.com/install.ps1))) -Login

Use -NoLogin quando o usuário escolher explicitamente o modo somente local. Um humano executando qualquer um dos instaladores interativamente pode omitir a opção de login explícita e responder ao seu prompt.

O login via Portal pode exigir que o usuário abra uma URL ou insira um código. Aguarde essa ação humana sem expor as credenciais retornadas. Após a instalação, verifique a versão do executável resolvido e o service status. Confirme o dispositivo a partir do Sanad Client quando a conexão em nuvem foi selecionada.

Atualizar uma Instalação Empacotada

1. Inspecione as versões instaladas do Cliente e do Agente e leia as notas de versão mais recentes antes de alterá-las.

2. Atualize o Sanad Client através de seu fluxo de atualização de propriedade da plataforma. Não substitua um Cliente empacotado com saída de fonte.

3. Atualize um Agente autônomo através do executável resolvido:

   sanad update
   

   Use o caminho completo do executável quando sanad não estiver no PATH. Se o atualizador relatar restart_required, obtenha aprovação e execute sanad service restart.

4. Verifique a versão final, estado do serviço, conexão Cliente-Agente e a preservação do Sanad Home. Relate qualquer etapa da plataforma que permanecer manual.

4. Caminho de Desenvolvimento / Fonte

Preparar o Checkout

Se um checkout correspondente já existir, use-o apenas após relatar seu caminho, ramo, worktree, remotos e estado sujo. Não clone um duplicado silenciosamente.

Se nenhum checkout existir, proponha um destino e obtenha aprovação, depois execute:

git clone https://github.com/EastStarAI/sanad-agent.git sanad-agent
cd sanad-agent

Leia o AGENTS.md, docs/llms.txt do repositório e os contratos aninhados mais próximos antes de continuar. Use FVM para cada operação Dart ou Flutter.

Instale o comando de desenvolvimento no escopo do usuário uma vez.

No macOS/Linux:

scripts/sanad-dev install

No Windows PowerShell:

.\scripts\sanad-dev.ps1 install

Em seguida, execute o par Agente e Cliente correspondente em todas as plataformas:

sanad-dev run

Use sanad-dev run --no-cloud apenas quando o usuário quiser explicitamente desenvolvimento somente local. Use sanad-dev status e chamadas limitadas de sanad-dev logs agent -n 50 e sanad-dev logs client -n 50 para verificação. Nunca use modo de acompanhamento de log em uma chamada de ferramenta de IA.

Atualizar um Checkout de Desenvolvimento

1. Inspecione o ramo ativo, upstream, worktrees e arquivos sujos.
2. Execute git fetch apenas após confirmar o remoto pretendido. Explique os commits recebidos antes da integração.
3. Para um checkout limpo no ramo de rastreamento pretendido, proponha git pull --ff-only. Não crie commits de mesclagem implicitamente.
4. Para um checkout sujo, pare e apresente opções de preservação. Não faça stash, commit, rebase, switch, reset ou descarte sem autorização explícita.
5. Após uma atualização de fonte bem-sucedida, execute novamente o comando sanad-dev install específico da plataforma; em seguida, use sanad-dev run ou o comando de verificação limitada solicitado pelo usuário.
6. Nunca use sanad update para um runtime de fonte/FVM; atualizações de fonte pertencem ao Git e ao sanad-dev.

5. Relate o Resultado

Relate:

• fluxo de trabalho selecionado e máquina de destino;
• versões detectadas e finais;
• estado do Cliente, Agente, repositório e serviço;
• comandos de verificação e resultados;
• qualquer ação manual do usuário ainda necessária;
• arquivos, serviços ou estado Git alterados.

Nunca reivindique sucesso apenas a partir de uma saída de download ou comando. Exija evidências relevantes de saúde do serviço ou da conexão Cliente-Agente. Não faça commit, push, publique ou remova dados do usuário a menos que o usuário tenha solicitado essa ação separada explicitamente.