AhmedAttia3/agent-skills

Installer Sanad

Guider l'utilisateur de l'inspection jusqu'à une installation ou une mise à jour vérifiée de Sanad. Garder les workflows de publication utilisateur et de développement source séparés.

Règles de sécurité

• Inspecter avant de modifier quoi que ce soit. Traiter l'installation, le remplacement de packages, l'enregistrement de services, le lancement d'applications et les mises à jour Git comme des mutations qui nécessitent l'approbation éclairée de l'utilisateur.
• Ne jamais rechercher un checkout dans tout un répertoire personnel ou un disque. Inspecter uniquement le répertoire courant, un chemin fourni par l'utilisateur et les emplacements standard des commandes installées. Demander le chemin du projet lorsqu'il ne peut pas être identifié en toute sécurité.
• Ne jamais écraser, réinitialiser, nettoyer, remiser (stash), commiter ou jeter un dépôt sale (dirty) à moins que l'utilisateur n'autorise explicitement cette action exacte.
• Ne jamais demander, citer, journaliser ou reconstruire des jetons d'accès, des jetons de rafraîchissement, des identifiants de fournisseur, des secrets de signature ou du contenu utilisateur. Pour une installation à distance opérée par un agent explicitement autorisé, accepter uniquement la commande complète Ajouter un appareil de l'utilisateur contenant son jeton de création à usage unique et de courte durée. Valider le bootstrap officiel, le transmettre sans l'afficher, le tracer ou le persister dans les artefacts du projet, et ne jamais extraire/reconstruire son jeton. Expliquer que ce consentement couvre l'exposition de la commande de création dans l'historique du chat/outil et que la commande d'installation générée peut utiliser des arguments de jeton ; ne pas prétendre à une exposition nulle. Conserver les arguments de transport SSH sans informations d'identification. Si l'utilisateur n'accepte pas cette exposition, lui faire exécuter directement la commande ou utiliser la connexion interactive par portail. Cette exception ne couvre jamais les informations d'identification durables.
• Utiliser uniquement les sources officielles de Sanad :
  • dépôt : https://github.com/EastStarAI/sanad-agent
  • versions : https://github.com/EastStarAI/sanad-agent/releases/latest
  • installateurs : https://sanad.eaststarai.com/install.sh et https://sanad.eaststarai.com/install.ps1
• Ne pas désactiver les contrôles de sécurité du système d'exploitation. Lire les dernières notes de version avant de décrire la signature actuelle ou la prise en charge de la plateforme.
• Préserver le répertoire personnel (Sanad Home) et les espaces de travail utilisateur pendant l'installation et la mise à jour.

Itinéraire rapide Google Cloud

Pour une demande de serveur cloud Google Cloud / GCP / gratuit, lire references/google-cloud-free-tier.md et suivre cet itinéraire spécialisé de publication utilisateur au lieu de répéter le questionnaire générique local/source ci-dessous. Il gère les prérequis, au plus deux questions initiales, la réutilisation des ressources, le provisionnement éligible, l'appairage juste-à-temps et une vérification minimale intégrée. Respecter les règles de sécurité ci-dessus. Ne pas promettre une facture nulle inconditionnelle ni dupliquer une allocation gratuite existante.

1. Inspecter la cible

Déterminer si les commandes seront exécutées sur la machine actuelle de l'utilisateur ou sur une machine distante. Ne pas supposer que la machine hébergeant le client Sanad est celle qui doit héberger l'agent Sanad.

Collecter des preuves en lecture seule :

1. Identifier le système d'exploitation et l'architecture.
2. Vérifier si sanad et sanad-dev sont résolus dans le PATH.
3. Vérifier l'exécutable propriétaire de l'installateur le cas échéant :
   • macOS/Linux : ${SANAD_HOME:-$HOME/.sanad}/bin/sanad
   • Windows : $env:SANAD_HOME\bin\sanad.exe, ou $HOME\.sanad\bin\sanad.exe lorsque SANAD_HOME n'est pas défini.
4. Si le répertoire courant ou fourni est un checkout Git, inspecter : git rev-parse --show-toplevel, git remote -v, git status --short --branch, et git worktree list. L'accepter comme source Sanad uniquement lorsque son identité de dépôt correspond à EastStarAI/sanad-agent ou que l'utilisateur confirme un fork intentionnel.
5. Interroger les versions installées et l'état du service uniquement via un exécutable Sanad résolu. Ne pas échouer simplement parce que sanad est absent du PATH.

Résumer ce qui existe avant de proposer un changement.

2. Sélectionner le workflow

Si la demande de l'utilisateur rend déjà le workflow explicite, confirmer la cible et continuer. Sinon, présenter ces choix et demander celui qu'il souhaite :

Chemin	Meilleur pour	Résultat	Compromis
Publication / utilisateur	Utilisation quotidienne normale	Client packagé et version d'agent vérifiée	Stable et simple ; la source n'est pas modifiable
Source / développeur	Contribuer, déboguer ou modifier Sanad	Checkout du dépôt exécuté via sanad-dev	Modifiable et testable ; nécessite des outils de développement et plus d'espace disque

Pour le chemin publication, déterminer la topologie :

• Ce bureau : installer le client Sanad ; Exécuter localement installe et démarre l'agent correspondant sur le même ordinateur.
• Un autre ordinateur ou serveur : garder le client sur le bureau, mobile ou web et installer uniquement l'agent Sanad sur la machine cible.
• Client uniquement : installer un client de bureau/mobile ou utiliser le client web sans installer d'agent sur cet appareil.

Indiquer les actions exactes, les destinations et l'impact sur les services. Obtenir l'approbation avant de télécharger, installer, remplacer, enregistrer, démarrer ou redémarrer.

3. Chemin Publication / Utilisateur

Installer le client et l'agent local

1. Lire la dernière version officielle et son manifeste. Sélectionner uniquement le package client correspondant à la plateforme et à l'architecture confirmées.
2. Vérifier l'artefact à l'aide des sommes de contrôle, des signatures et des instructions de plateforme publiées par cette version. Ne pas généraliser le statut de signature d'une version antérieure à la version actuelle.
3. Installer le client en utilisant le flux normal du système d'exploitation. Ne pas contourner silencieusement les invites de révision d'application ou de sécurité.
4. Demander à l'utilisateur de lancer le client Sanad et de choisir Exécuter localement. Expliquer que le client télécharge, vérifie, enregistre, démarre et se connecte à l'agent local correspondant ; un compte Sanad et un jeton d'appairage ne sont pas requis.
5. Vérifier que le client peut atteindre l'agent local avant de déclarer le succès.

Pour Android, iOS et Web, suivre la disponibilité indiquée dans les notes de version actuelles. Ces plates-formes fournissent l'interface mais n'hébergent pas le service agent natif.

Installer un agent sur un autre ordinateur ou serveur

Proposer deux choix égaux :

1. Appairer via le client Sanad : ouvrir Paramètres, puis cliquer sur + à côté de Appareils dans la barre latérale des paramètres pour ouvrir Ajouter un appareil. Demander à l'utilisateur d'exécuter la commande générée complète sur la machine cible, ou accepter sa commande générée complète pour une installation à distance autorisée dans le cadre de l'exception de jeton de création à usage unique ci-dessus. Ne jamais demander l'identifiant séparément ni afficher la commande dans les rapports.
2. Installer l'agent directement : choisir le mode de connexion au portail ou le mode local uniquement et exécuter l'installateur officiel correspondant après approbation.

Pour un terminal macOS/Linux opéré par un agent, éviter une invite ambiguë :

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

Utiliser --no-login à la place lorsque l'utilisateur choisit explicitement le mode local uniquement.

Pour un terminal Windows PowerShell opéré par un agent :

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

Utiliser -NoLogin à la place lorsque l'utilisateur choisit explicitement le mode local uniquement. Un humain exécutant l'un ou l'autre installateur de manière interactive peut omettre l'option de connexion explicite et répondre à son invite.

La connexion au portail peut nécessiter que l'utilisateur ouvre une URL ou saisisse un code. Faire une pause pour cette action humaine sans exposer les informations d'identification renvoyées. Après l'installation, vérifier la version de l'exécutable résolu et service status. Confirmer l'appareil depuis le client Sanad lorsque la connexion cloud a été sélectionnée.

Mettre à jour une installation packagée

1. Inspecter les versions installées du client et de l'agent et lire les dernières notes de version avant de les modifier.

2. Mettre à jour le client Sanad via son flux de mise à jour propre à la plateforme. Ne pas remplacer un client packagé par une sortie source.

3. Mettre à jour un agent autonome via l'exécutable résolu :

   sanad update
   

   Utiliser le chemin complet de l'exécutable lorsque sanad n'est pas dans le PATH. Si le programme de mise à jour signale restart_required, obtenir l'approbation et exécuter sanad service restart.

4. Vérifier la version finale, l'état du service, la connexion client-agent et la préservation de Sanad Home. Signaler toute étape de plateforme qui reste manuelle.

4. Chemin Source / Développeur

Préparer le checkout

Si un checkout correspondant existe déjà, l'utiliser uniquement après avoir signalé son chemin, sa branche, son arbre de travail, ses dépôts distants et son état sale. Ne pas cloner un doublon silencieusement.

Si aucun checkout n'existe, proposer une destination et obtenir l'approbation, puis exécuter :

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

Lire le AGENTS.md, docs/llms.txt du dépôt et les contrats imbriqués les plus proches avant de poursuivre le travail. Utiliser FVM pour toute opération Dart ou Flutter.

Installer la commande de développement au niveau de l'utilisateur une fois.

Sur macOS/Linux :

scripts/sanad-dev install

Sur Windows PowerShell :

.\scripts\sanad-dev.ps1 install

Ensuite, exécuter la paire agent et client correspondante sur chaque plateforme :

sanad-dev run

Utiliser sanad-dev run --no-cloud uniquement lorsque l'utilisateur souhaite explicitement un développement local uniquement. Utiliser sanad-dev status et les appels limités sanad-dev logs agent -n 50 et sanad-dev logs client -n 50 pour la vérification. Ne jamais utiliser le mode de suivi des journaux (follow) à partir d'un appel d'outil IA.

Mettre à jour un checkout de développement

1. Inspecter la branche active, l'amont, les arbres de travail et les fichiers sales.
2. Exécuter git fetch uniquement après avoir confirmé le dépôt distant prévu. Expliquer les commits entrants avant l'intégration.
3. Pour un checkout propre sur la branche de suivi prévue, proposer git pull --ff-only. Ne pas créer implicitement de commits de fusion (merge).
4. Pour un checkout sale, s'arrêter et présenter les options de préservation. Ne pas remiser (stash), commiter, rebaser, changer de branche, réinitialiser ou jeter sans autorisation explicite.
5. Après une mise à jour réussie de la source, réexécuter la commande sanad-dev install spécifique à la plateforme ; puis utiliser sanad-dev run ou la commande de vérification limitée demandée par l'utilisateur.
6. Ne jamais utiliser sanad update pour un runtime source/FVM ; les mises à jour source appartiennent à Git et à sanad-dev.

5. Rapporter le résultat

Rapporter :

• le workflow sélectionné et la machine cible ;
• les versions détectées et finales ;
• l'état du client, de l'agent, du dépôt et du service ;
• les commandes de vérification et leurs résultats ;
• toute action manuelle utilisateur encore nécessaire ;
• les fichiers, services ou état Git modifiés.

Ne jamais prétendre au succès à partir d'un téléchargement ou d'une sortie de commande seule. Exiger la preuve de l'état de santé du service ou de la connexion client-agent. Ne pas commiter, pousser, publier ou supprimer des données utilisateur à moins que l'utilisateur n'ait explicitement demandé cette action distincte.