AhmedAttia3/agent-skills

Instalar Sanad

Guía al usuario desde la inspección hasta una instalación o actualización verificada de Sanad. Mantén separados los flujos de trabajo de lanzamiento para usuario y de desarrollo.

Reglas de seguridad

• Inspecciona antes de cambiar nada. Trata la instalación, el reemplazo de paquetes, el registro de servicios, el lanzamiento de aplicaciones y las actualizaciones de Git como mutaciones que requieren la aprobación informada del usuario.
• Nunca busques un clon en todo un directorio home o disco. Inspecciona el directorio actual, una ruta proporcionada por el usuario y las ubicaciones estándar de comandos instalados únicamente. Pregunta por la ruta del proyecto cuando no se pueda identificar de forma segura.
• Nunca sobrescribas, reinicies, limpies, hagas stash, commits, o descartes un repositorio sucio a menos que el usuario autorice explícitamente esa acción exacta.
• Nunca solicites, cites, registres o reconstruyas tokens de acceso, tokens de actualización, credenciales de proveedores, secretos de firma o contenido del usuario. Solo para una instalación remota operada por agente explícitamente autorizada, acepta el comando completo Add device del usuario que contenga su token de creación de un solo uso y corta duración. Valida el bootstrap oficial, transmítelo sin eco, rastreo ni persistencia en artefactos del proyecto, y nunca extraigas/reconstruyas su token. Explica que este consentimiento cubre la exposición del comando de creación en el historial de chat/herramienta y que el comando del instalador generado puede usar argumentos de token; no afirmes exposición cero. Mantén los argumentos de transporte SSH libres de credenciales. Si el usuario no acepta esa exposición, haz que lo ejecute directamente o use el inicio de sesión interactivo de Portal. Esta excepción nunca cubre credenciales duraderas.
• Usa solo fuentes oficiales de Sanad:
  • repositorio: https://github.com/EastStarAI/sanad-agent
  • lanzamientos: https://github.com/EastStarAI/sanad-agent/releases/latest
  • instaladores: https://sanad.eaststarai.com/install.sh y https://sanad.eaststarai.com/install.ps1
• No deshabilites los controles de seguridad del sistema operativo. Lee las últimas notas de la versión antes de describir la firma o compatibilidad actual de la plataforma.
• Preserva el directorio Sanad Home y los espacios de trabajo del usuario durante la instalación y actualización.

Ruta rápida de Google Cloud

Para una solicitud de Google Cloud / GCP / servidor cloud gratuito, lee references/google-cloud-free-tier.md y sigue esa ruta especializada de lanzamiento para usuario en lugar de repetir el cuestionario genérico local/fuente a continuación. Ella gestiona los prerrequisitos, como máximo dos preguntas iniciales, la reutilización de recursos, el aprovisionamiento elegible, el emparejamiento justo a tiempo y la verificación mínima incorporada. Mantén las reglas de seguridad anteriores. No prometas una factura cero incondicional ni dupliques una asignación gratuita existente.

1. Inspeccionar el destino

Determina si los comandos se ejecutarán en la máquina actual del usuario o en una máquina remota. No asumas que la máquina que aloja el Cliente Sanad es la máquina que debe alojar el Agente Sanad.

Recopila evidencia de solo lectura:

1. Identifica el sistema operativo y la arquitectura.
2. Comprueba si sanad y sanad-dev se resuelven en PATH.
3. Comprueba el ejecutable propiedad del instalador cuando sea relevante:
   • macOS/Linux: ${SANAD_HOME:-$HOME/.sanad}/bin/sanad
   • Windows: $env:SANAD_HOME\bin\sanad.exe, o $HOME\.sanad\bin\sanad.exe cuando SANAD_HOME no está establecido.
4. Si el directorio actual o proporcionado es un clon de Git, inspecciona: git rev-parse --show-toplevel, git remote -v, git status --short --branch y git worktree list. Acéptalo como fuente de Sanad solo cuando su identidad de repositorio coincida con EastStarAI/sanad-agent o el usuario confirme un fork intencional.
5. Consulta las versiones instaladas y el estado del servicio solo a través de un ejecutable Sanad resuelto. No falles simplemente porque sanad esté ausente de PATH.

Resume lo que existe antes de proponer un cambio.

2. Seleccionar el flujo de trabajo

Si la solicitud del usuario ya hace explícito el flujo de trabajo, confirma el destino y continúa. De lo contrario, presenta estas opciones y pregunta cuál quiere:

Ruta	Mejor para	Resultado	Compensación
Lanzamiento / usuario	Uso diario normal	Cliente empaquetado y versión de Agente verificada	Estable y simple; la fuente no es editable
Fuente / desarrollador	Contribuir, depurar o cambiar Sanad	Clon del repositorio ejecutado con sanad-dev	Editable y comprobable; requiere herramientas de desarrollo y más espacio en disco

Para la ruta de lanzamiento, determina la topología:

• Este escritorio: instala el Cliente Sanad; Ejecutar localmente instala e inicia el Agente coincidente en el mismo ordenador.
• Otro ordenador o servidor: mantén el Cliente en el escritorio, móvil o web e instala solo el Agente Sanad en la máquina de destino.
• Solo Cliente: instala un Cliente de escritorio/móvil o usa el Cliente Web sin instalar un Agente en ese dispositivo.

Indica las acciones exactas, destinos e impacto en el servicio. Obtén aprobación antes de descargar, instalar, reemplazar, registrar, iniciar o reiniciar.

3. Ruta de lanzamiento / usuario

Instalar el Cliente y el Agente local

1. Lee la última versión oficial y su manifiesto. Selecciona solo el paquete del Cliente que coincida con la plataforma y arquitectura confirmadas.
2. Verifica el artefacto usando las sumas de verificación, firmas y guía de plataforma publicadas por esa versión. No generalices el estado de firma de una versión anterior a la versión actual.
3. Instala el Cliente usando el flujo normal del sistema operativo. No omitas en silencio las indicaciones de revisión de aplicaciones o seguridad.
4. Pide al usuario que inicie el Cliente Sanad y elija Ejecutar localmente. Explica que el Cliente descarga, verifica, registra, inicia y conecta con el Agente local coincidente; no se requiere una cuenta de Sanad ni un token de emparejamiento.
5. Verifica que el Cliente pueda alcanzar al Agente local antes de declarar el éxito.

Para Android, iOS y Web, sigue la disponibilidad indicada en las notas de la versión actual. Estas plataformas proporcionan la interfaz pero no alojan el servicio nativo del Agente.

Instalar un Agente en otro ordenador o servidor

Ofrece dos opciones iguales:

1. Emparejar a través del Cliente Sanad: abre Configuración, luego haz clic en + junto a Dispositivos en la barra lateral de Configuración para abrir Agregar dispositivo. Haz que el usuario ejecute el comando generado completo en la máquina de destino, o acepta su comando generado completo para una instalación remota autorizada bajo la excepción de token de creación de un solo uso anterior. Nunca pidas la credencial por separado ni hagas eco del comando en los informes.
2. Instalar el Agente directamente: elige el modo de inicio de sesión en Portal o solo local y ejecuta el instalador oficial correspondiente después de la aprobación.

Para un terminal macOS/Linux operado por agente, evita una solicitud ambigua:

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

Usa --no-login en su lugar cuando el usuario elija explícitamente el modo solo local.

Para un terminal Windows PowerShell operado por agente:

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

Usa -NoLogin en su lugar cuando el usuario elija explícitamente el modo solo local. Un humano que ejecute cualquiera de los instaladores de forma interactiva puede omitir la opción de inicio de sesión explícita y responder a su solicitud.

El inicio de sesión en Portal puede requerir que el usuario abra una URL o ingrese un código. Haz una pausa para esa acción humana sin exponer las credenciales devueltas. Después de la instalación, verifica la versión del ejecutable resuelto y service status. Confirma el dispositivo desde el Cliente Sanad cuando se haya seleccionado la conexión en la nube.

Actualizar una instalación empaquetada

1. Inspecciona las versiones instaladas del Cliente y el Agente y lee las últimas notas de la versión antes de cambiarlas.

2. Actualiza el Cliente Sanad a través de su flujo de actualización propio de la plataforma. No reemplaces un Cliente empaquetado con la salida de la fuente.

3. Actualiza un Agente independiente a través del ejecutable resuelto:

   sanad update
   

   Usa la ruta completa del ejecutable cuando sanad no esté en PATH. Si el actualizador informa restart_required, obtén aprobación y ejecuta sanad service restart.

4. Verifica la versión final, el estado del servicio, la conexión Cliente-Agente y la conservación de Sanad Home. Informa de cualquier paso de la plataforma que siga siendo manual.

4. Ruta de fuente / desarrollador

Preparar el clon

Si ya existe un clon coincidente, úsalo solo después de informar su ruta, rama, árbol de trabajo, remotos y estado sucio. No clones un duplicado en silencio.

Si no existe ningún clon, propón un destino y obtén aprobación, luego ejecuta:

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

Lee el repositorio AGENTS.md, docs/llms.txt y los contratos anidados más cercanos antes de continuar. Usa FVM para cada operación de Dart o Flutter.

Instala el comando de desarrollo con alcance de usuario una vez.

En macOS/Linux:

scripts/sanad-dev install

En Windows PowerShell:

.\scripts\sanad-dev.ps1 install

Luego ejecuta el par de Agente y Cliente coincidentes en cada plataforma:

sanad-dev run

Usa sanad-dev run --no-cloud solo cuando el usuario quiera explícitamente desarrollo solo local. Usa sanad-dev status y llamadas acotadas sanad-dev logs agent -n 50 y sanad-dev logs client -n 50 para verificación. Nunca uses el modo de seguimiento de registros desde una llamada de herramienta de IA.

Actualizar un clon de desarrollador

1. Inspecciona la rama activa, el upstream, los árboles de trabajo y los archivos sucios.
2. Ejecuta git fetch solo después de confirmar el remoto previsto. Explica las confirmaciones entrantes antes de la integración.
3. Para un clon limpio en la rama de seguimiento prevista, propón git pull --ff-only. No crees confirmaciones de fusión implícitamente.
4. Para un clon sucio, detente y presenta opciones de preservación. No hagas stash, commit, rebase, switch, reset o descartes sin autorización explícita.
5. Después de una actualización de fuente exitosa, vuelve a ejecutar el comando específico de la plataforma sanad-dev install; luego usa sanad-dev run o el comando de verificación acotado solicitado por el usuario.
6. Nunca uses sanad update para un runtime de fuente/FVM; las actualizaciones de fuente pertenecen a Git y sanad-dev.

5. Informar el resultado

Informa:

• flujo de trabajo seleccionado y máquina de destino;
• versiones detectadas y finales;
• estado del Cliente, Agente, repositorio y servicio;
• comandos de verificación y resultados;
• cualquier acción manual del usuario aún requerida;
• archivos, servicios o estado de Git modificados.

Nunca declares éxito solo a partir de una descarga o código de salida de comando. Requiere la evidencia de salud del servicio relevante o de la conexión Cliente-Agente. No hagas commit, push, publiques o elimines datos del usuario a menos que el usuario haya solicitado esa acción separada explícitamente.