create-byan-agent 2.54.0 → 2.58.1

package/CHANGELOG.md

@@ -9,6 +9,148 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.58.1] - 2026-07-21
+
+### Fixed — l'install auto en terminal gelait au controle des copies globales de skills
+- Symptome : `create-byan-agent --cli` restait bloque en chargement infini sur
+  `[6/8] Controle des copies globales de skills` quand des copies globales
+  `~/.claude/skills` divergeaient.
+- Cause : l'etape passait une question interactive (`inquirer`) au moteur, mais
+  l'install auto garde un indicateur de progression (`ora`) qui tourne pendant
+  chaque etape. La question s'affichait SOUS l'indicateur : invisible, en attente
+  d'une saisie que l'utilisateur ne voyait pas -> gel apparent.
+- Correctif : l'install automatique n'ouvre plus de question interactive. Par
+  defaut, elle SIGNALE les copies divergentes et affiche la commande de
+  synchronisation exacte, sans rien ecrire dans `~/.claude` et sans bloquer
+  (ligne rouge conservee : pas d'ecriture silencieuse dans le home). Nouveau
+  drapeau `--sync-skills` pour synchroniser sans demander (le drapeau EST le
+  consentement explicite), en approbation automatique sans prompt.
+- Nouvelle fonction pure `skillsSyncConsent` dans `install/lib/install-mode.js`,
+  testee (`install/__tests__/install-mode.test.js`) ; preuve de non-blocage des
+  deux branches (signalement seul / synchro opt-in) sur une maquette de
+  divergence.
+
+## [2.58.0] - 2026-07-21
+
+### Added — l'assistant par defaut ouvre l'app Desktop si elle est installee
+- `create-byan-agent` (sans argument) tente d'abord d'ouvrir l'app Desktop BYAN
+  dans une fenetre native ; si aucune app n'est detectee, il ouvre le meme
+  assistant dans le navigateur. Les deux visages partagent le meme serveur webui
+  — seule la fenetre change. Aucun blocage quand l'app n'est pas la.
+- Detection par emplacements d'installation concrets (electron-builder,
+  productName BYAN) : `/opt/BYAN/byan`, `/usr/bin/byan`, `/usr/local/bin/byan`
+  (Linux) ; `BYAN.app` (macOS, systeme et `~/Applications`) ; `BYAN.exe` sous
+  `Programs`/`PROGRAMFILES` (Windows). La variable `BYAN_DESKTOP_BIN` surcharge
+  pour une AppImage ou un chemin personnalise. Pas de recherche d'un `byan` nu
+  sur le PATH (trop de faux positifs).
+- `create-byan-agent web` force desormais le navigateur (echappatoire explicite,
+  ignore l'app Desktop).
+- Nouveau module pur `install/lib/desktop-app.js` (`detectDesktopApp`,
+  `candidatePaths`), injectable (platform/env/homedir/existsSync) et teste
+  (`install/__tests__/desktop-app.test.js`, 7 cas couvrant Linux/macOS/Windows,
+  l'override et le repli).
+- Note : les binaires de l'app Desktop ne sont pas encore distribues ; la
+  detection tombe donc sur le navigateur aujourd'hui, par conception. Le vrai
+  installateur (distribution des binaires) est un chantier separe a venir.
+
+## [2.57.0] - 2026-07-21
+
+### Changed — l'assistant web devient l'installation par defaut
+- `create-byan-agent` (sans argument) lance desormais l'assistant graphique dans
+  le navigateur : il demarre le serveur local (lie a `127.0.0.1`) et ouvre la
+  page d'installation. C'est l'inversion demandee — le graphique par defaut, le
+  terminal en option.
+- Les deux chemins terminal restent accessibles par drapeau :
+  - `--cli` : installation automatique en terminal, zero question (le comportement
+    qui etait le defaut en 2.56.0).
+  - `--legacy` : interview complet d'origine, question par question.
+- `create-byan-agent web` conserve son role d'alias explicite de l'action par
+  defaut ; il accepte `--port` et `--dir`.
+- Nouveau module pur `install/lib/install-mode.js` (`chooseInstallMode`) : la
+  decision de routage (web / cli / legacy) est isolee et testee
+  (`install/__tests__/install-mode.test.js`, 5 cas). `--legacy` prime sur `--cli`
+  si les deux sont passes.
+
+## [2.56.0] - 2026-07-21
+
+### Changed — installation refondue : un moteur, deux visages
+- Nouveau moteur d'installation `install/lib/install-engine.js` : options ->
+  actions reelles (detection, copie `_byan` + `.claude`, configurations natives
+  Claude/Codex, dependances MCP, controle des copies globales de skills,
+  verification finale). La progression est honnete par construction : un
+  evenement d'etape = une action reellement executee. Defauts sans question :
+  Claude + Codex quand detectes, tous les agents, soul createur, rtk installe
+  s'il manque, configuration memorisee reutilisee. Nom du projet et repertoire
+  cible en options. Teste sur fixtures disque (7 cas).
+- `npx create-byan-agent` = installation automatique directe (plus d'interview).
+  Options : `--name`, `--dir`, `--no-launch`, `--no-rtk` ; l'ancienne interview
+  reste accessible via `--legacy`. En fin d'installation, Claude Code est lance
+  (canal byan-channel quand la version du CLI le supporte, sinon `claude`
+  normal ; commande affichee en terminal non interactif).
+- WebUI d'installation branchee sur le MEME moteur : les boutons installer et
+  mettre a jour executaient une simulation (etapes diffusees autour de pauses,
+  echec de l'updater avale puis succes affiche) — ils executent desormais le
+  moteur et l'updater reels, la progression WebSocket relaie chaque etape
+  executee, et l'ecran d'options porte nom du projet + repertoire. 3 tests par
+  injection d'un moteur factice.
+- Memoire d'installation dans le home : `install/lib/home-credentials.js`
+  (`~/.byan/credentials.json`, memes cles que le resolveur du serveur MCP,
+  fichier en mode 600, fusion sans effacement de secret). L'installation
+  reutilise ce qui est memorise et n'exige plus de re-saisie machine par
+  machine.
+- Le client Leantime du serveur MCP resout sa config via `resolve-config`
+  (env -> `~/.byan/credentials.json`) au lieu de lire seulement
+  l'environnement de lancement — le fichier memorise l'atteint enfin. Cadrage
+  Google documente (cle de service account memorisee ; OAuth interactif hors
+  perimetre serveur).
+
+
+## [2.55.0] - 2026-07-21
+
+### Added — l'installation propose la synchro des copies globales divergentes
+- Constate sur le terrain : l'installation pose des skills projet a jour, mais
+  une copie manuelle homonyme sous `~/.claude/skills/` (plus ancienne) peut
+  rester celle que la commande `/<skill>` charge — les nouveautes fraichement
+  installees restent invisibles. La garde de fraicheur (2.54.0) le signale a la
+  session suivante ; l'installeur, lui, voit la divergence au moment ou il la
+  cree et a un terminal pour poser la question.
+- Nouveau module `install/lib/global-skills-sync.js` : en fin d'installation
+  Claude, compare les skills fraichement poses avec les copies globales
+  homonymes (reutilise `compareSkills` du payload `.claude` livre par le meme
+  paquet — zero duplication de la comparaison) et, en terminal interactif,
+  propose la synchronisation projet -> global avec consentement explicite.
+  Refus ou terminal non interactif : signalement clair + la commande exacte a
+  copier ; rien n'est ecrit dans le home sans accord recueilli pendant ce run.
+- Le chemin `update` (corrige en 2.54.1) recoit le meme controle en mode
+  signalement : le resultat porte la liste des skills globaux divergents et la
+  commande de synchro est affichee.
+- Tests jest : 6 cas (divergence detectee via le comparateur livre, oui ->
+  copie effective, non -> rien ecrit, non-interactif -> rien ecrit + commande,
+  pas de dossier global -> silencieux, copies identiques -> silencieux).
+
+## [2.54.1] - 2026-07-21
+
+### Fixed — la commande update ne deployait pas .claude/
+- Cause racine constatee sur le terrain et verifiee dans le code (updater.js
+  lignes 30-31, manifest.js : seule la racine `_byan/` etait comparee et
+  copiee). Tout ce qui vit sous `.claude/` — les skills (dont le rail
+  auto-dispatch 2.53.0), les workflows natifs, les hooks (dont la garde de
+  fraicheur 2.54.0), settings.json et le `.mcp.json` regenere par le setup
+  natif — restait hors du perimetre de `update`. Un projet pouvait donc etre
+  "a jour" avec un `.claude/` vieux de plusieurs mois : rail absent, MCP
+  absent, garde absente.
+- Correctif : `update()` rafraichit aussi `.claude/` comme le fait
+  l'installation complete — sauvegarde dediee `.claude.backup-<ts>` (prefixe
+  distinct de `_byan.backup-` pour ne pas polluer la purge/rollback), copie
+  `templates/.claude` -> projet avec ecrasement, puis `setupClaudeNative`
+  (regenere `.mcp.json`, installe les dependances du serveur MCP, cable les
+  githooks). En cas d'echec, le `.claude/` d'origine est restaure.
+- Testabilite : `options.templateDir` et `options.nativeSetup` injectables ;
+  nouveau test fonctionnel `install/__tests__/yanstaller/updater.test.js`
+  (4 cas : deploiement du rail, projet sans `.claude`, rollback, deja a jour).
+- La sortie de la commande affiche desormais le rafraichissement `.claude` et
+  le chemin de sa sauvegarde.
+
 ## [2.54.0] - 2026-07-21
 
 ### Added — Garde de fraicheur des skills (SessionStart)

package/README.md

@@ -76,7 +76,7 @@ Diversifier les personas elargit la surface de competence collective.
 Aucune installation préalable n'est nécessaire. Lancez simplement :
 
 ```bash
-# Crée un nouveau projet BYAN (via npx, sans installation préalable)
+# Assistant d'installation graphique dans le navigateur (par défaut)
 npx create-byan-agent
 
 # Ou installation globale
@@ -84,16 +84,32 @@ npm install -g create-byan-agent
 create-byan-agent
 ```
 
-L'installeur (Yanstaller) vous guide interactivement à travers le processus :
-
-```
-? Nom du projet : mon-projet
-? Langue de communication : Francais
-? Plateforme cible : Claude Code
-? Activer le fact-check scientifique ? [Y/n]
-? Activer le système ELO de confiance ? [Y/n]
-? Optimiser les coûts LLM automatiquement (~54% d'économies) ? [Y/n]
-```
+Par défaut, `create-byan-agent` ouvre l'assistant graphique. S'il détecte l'app
+Desktop BYAN installée, il l'ouvre dans une fenêtre native ; sinon il démarre un
+petit serveur local (lié à `127.0.0.1`) et ouvre la page d'installation dans le
+navigateur. Dans les deux cas c'est le même assistant : vous y choisissez le nom
+du projet, le répertoire et les options.
+
+Modes selon vos besoins :
+
+| Commande | Mode |
+|----------|------|
+| `create-byan-agent` | Assistant graphique : app Desktop si installée, sinon navigateur (par défaut) |
+| `create-byan-agent web` | Force l'assistant dans le navigateur (ignore l'app Desktop) |
+| `create-byan-agent --cli` | Installation automatique en terminal, zéro question (Claude+Codex, tous les agents, rtk) |
+| `create-byan-agent --cli --sync-skills` | Idem, en synchronisant sans demander les copies globales `~/.claude/skills` divergentes |
+| `create-byan-agent --legacy` | Interview complet d'origine, question par question en terminal |
+
+En mode `--cli`, si des copies globales de skills sous `~/.claude/skills`
+divergent de l'installation, l'assistant le signale et affiche la commande de
+synchronisation — sans bloquer et sans rien écrire dans votre home. Ajoutez
+`--sync-skills` pour qu'il les synchronise directement.
+
+Détection de l'app Desktop : emplacements d'installation standards par système
+(`/opt/BYAN/byan` et `/usr/bin/byan` sous Linux, `BYAN.app` sous macOS,
+`BYAN.exe` sous Windows). Pour une AppImage ou un chemin personnalisé, pointez la
+variable `BYAN_DESKTOP_BIN` sur l'exécutable. Tant que l'app Desktop n'est pas
+installée, l'assistant s'ouvre dans le navigateur — aucun blocage.
 
 ### Structure du projet après installation
 

package/install/bin/create-byan-agent-v2.js

@@ -24,6 +24,7 @@ const { setupCodexAutodelegate, DEVICE_FLOW_INSTRUCTION } = require('../lib/code
 const { setupMcpExtensions } = require('../lib/mcp-extensions');
 const { setupStagingConsent } = require('../lib/staging-consent');
 const { getLatestVersion, compareVersions } = require('../lib/utils/version-compare');
+const { chooseInstallMode, skillsSyncConsent } = require('../lib/install-mode');
 
 // Version source-of-truth is the root package.json (the one npm publishes).
 // install/package.json used to be read here, but it carries an unrelated
@@ -1320,6 +1321,20 @@ async function install(options = {}) {
         )
       );
     }
+
+    // Stale global copies check : a same-named ~/.claude/skills/<n> that
+    // diverges from what was JUST installed can be the copy the slash command
+    // loads — the fresh features would stay invisible. Ask (TTY) or notice
+    // (non-TTY) ; no silent write into the user's home, ever.
+    try {
+      const { offerGlobalSkillsSync } = require('../lib/global-skills-sync');
+      const ask = process.stdout.isTTY
+        ? async (message) => (await inquirer.prompt([{ type: 'confirm', name: 'ok', message, default: true }])).ok
+        : null;
+      await offerGlobalSkillsSync(projectRoot, templateDir, { ask, log: (l) => console.log(chalk.yellow(l)) });
+    } catch (error) {
+      console.log(chalk.gray(`  [INFO] Global skills check skipped: ${error.message}`));
+    }
   }
 
   if (needsCodex) {
@@ -1887,13 +1902,132 @@ async function install(options = {}) {
   console.log(chalk.blue('Happy agent building! '));
 }
 
+// Default path since 2.56.0: the zero-question automatic install running the
+// shared engine (install/lib/install-engine.js) — the same engine the web
+// wizard calls. Claude+Codex by default (when detected), every agent, creator
+// soul, rtk installed when missing, stored home credentials reused. The legacy
+// ~20-question interview stays reachable behind --legacy only.
+async function installAuto(options) {
+  const engine = require('../lib/install-engine');
+  const projectRoot = path.resolve(options.dir || process.cwd());
+
+  console.log(chalk.cyan.bold(`\n  BYAN ${BYAN_VERSION} — installation automatique (terminal)`));
+  console.log(chalk.gray(`  Projet : ${options.name || path.basename(projectRoot)}  |  Repertoire : ${projectRoot}`));
+  console.log(chalk.gray('  (assistant web par defaut : create-byan-agent ; interview complet : --legacy)\n'));
+
+  let spinner = null;
+  const isTTY = Boolean(process.stdout.isTTY);
+  // The automatic install never opens an interactive prompt: a question drawn
+  // under the live progress spinner froze the terminal at the skills-sync step.
+  // Default is notice-only ; --sync-skills opts in to an unattended sync.
+  const ask = skillsSyncConsent(options);
+
+  try {
+    const result = await engine.runInstall({
+      projectRoot,
+      projectName: options.name || undefined,
+      rtk: options.rtk !== false,
+    }, {
+      onStep: ({ index, total, label }) => {
+        if (spinner) spinner.succeed();
+        spinner = ora(`[${index}/${total}] ${label}`).start();
+      },
+      log: (line) => { if (spinner) spinner.info(chalk.gray(line)).start(); else console.log(chalk.gray(line)); },
+      ask,
+    });
+    if (spinner) spinner.succeed();
+
+    console.log('');
+    console.log(chalk.green.bold(`  Installation terminee — verification ${result.verify.passed}/${result.verify.total}`));
+
+    // End-of-install launch (F5): start Claude Code, with the byan-channel
+    // when this CLI version supports it. --no-launch or a non-interactive
+    // terminal prints the command instead of running it.
+    if (result.launch) {
+      if (options.launch !== false && isTTY) {
+        console.log(chalk.cyan(`  Lancement de Claude Code : ${result.launch.command}\n`));
+        const { spawnSync } = require('child_process');
+        spawnSync(result.launch.command, { stdio: 'inherit', shell: true });
+      } else {
+        console.log(chalk.gray(`  Pour lancer Claude Code : ${result.launch.command}`));
+      }
+    } else {
+      console.log(chalk.gray('  Claude Code introuvable sur cette machine — installe-le puis lance `claude` dans le projet.'));
+    }
+  } catch (error) {
+    if (spinner) spinner.fail();
+    console.error(chalk.red.bold('\nInstallation en echec :'));
+    console.error(chalk.red(`  ${error.message}`));
+    process.exit(1);
+  }
+}
+
+// Default path since 2.58.0: prefer the native Desktop app when it is installed
+// (option A), otherwise fall back to the browser wizard. Both wrap the SAME
+// webui server — the only difference is the window (native shell vs browser
+// tab). When no Desktop app is found, print a one-line discovery tip and open
+// the browser without blocking. The `web` subcommand skips this and forces the
+// browser (explicit escape hatch).
+function launchDesktopOrWeb(options = {}) {
+  const { detectDesktopApp } = require('../lib/desktop-app');
+  const desktop = detectDesktopApp();
+
+  if (desktop.found) {
+    console.log(chalk.cyan.bold(`\n  BYAN ${BYAN_VERSION} — ouverture de l app Desktop\n`));
+    console.log(chalk.gray(`  ${desktop.bin}`));
+    try {
+      const { spawn } = require('child_process');
+      const child = spawn(desktop.bin, [], { detached: true, stdio: 'ignore' });
+      child.unref();
+      return;
+    } catch (error) {
+      console.log(chalk.yellow(`  Echec du lancement de l app Desktop (${error.message}) — repli navigateur.`));
+      // fall through to the browser wizard
+    }
+  } else {
+    console.log(chalk.gray('\n  Astuce : l app Desktop BYAN offre une vraie fenetre native. Une fois installee,'));
+    console.log(chalk.gray('  cette commande l ouvrira automatiquement. Pour l instant, j ouvre le navigateur.'));
+  }
+
+  launchWeb(options);
+}
+
+// The browser wizard. Starts the local HTTP + WebSocket server (bound to
+// loopback) and opens the browser — the server owns the browser launch. Used
+// as the fallback of launchDesktopOrWeb and as the explicit `web` subcommand.
+function launchWeb(options = {}) {
+  const ByanWebUI = require('../src/webui/server');
+  const port = parseInt(options.port, 10) || 3000;
+  const projectRoot = path.resolve(options.dir || process.cwd());
+
+  console.log(chalk.cyan.bold(`\n  BYAN ${BYAN_VERSION} — assistant d installation (navigateur)\n`));
+  const server = new ByanWebUI({ port, projectRoot });
+  server.start();
+  console.log(chalk.green(`  Interface ouverte sur http://localhost:${port}`));
+  console.log(chalk.gray(`  Repertoire projet : ${projectRoot}`));
+  console.log(chalk.gray('  Installation en terminal : create-byan-agent --cli   |   Ctrl+C pour arreter\n'));
+}
+
 // CLI Program
 program
   .name('create-byan-agent')
-  .description('Install BYAN v2.2.0 - Builder of YAN with Model Selector and multi-platform support')
+  .description('Install BYAN - Builder of YAN. Default: graphical web wizard. --cli for the terminal install.')
   .version(BYAN_VERSION)
   .option('--skip-version-check', 'Bypass the npm freshness guard (not recommended)')
-  .action(install);
+  .option('--cli', 'Installation automatique en terminal (au lieu de l assistant web par defaut)')
+  .option('-p, --port <port>', 'Port de l assistant web (defaut : 3000)', '3000')
+  .option('--name <name>', 'Nom du projet (defaut : nom du dossier)')
+  .option('--dir <dir>', 'Repertoire d installation (defaut : dossier courant)')
+  .option('--no-launch', 'Ne pas lancer Claude Code en fin d installation (mode --cli)')
+  .option('--no-rtk', 'Ne pas installer rtk automatiquement (mode --cli)')
+  .option('--sync-skills', 'Mode --cli : synchroniser sans demander les copies globales ~/.claude/skills divergentes')
+  .option('--legacy', 'Interview complete d origine (l ancien parcours a questions)')
+  .action(async (options) => {
+    const mode = chooseInstallMode(options);
+    if (mode === 'legacy') return install(options);
+    if (mode === 'cli') return installAuto(options);
+    return launchDesktopOrWeb(options);
+  });
 
 // Update Command (Yanstaller v3)
 program
@@ -1957,6 +2091,20 @@ program
       if (result.filesSkipped > 0) {
         console.log(chalk.yellow(`  Files skipped: ${result.filesSkipped} (user-modified)`));
       }
+      if (result.claudeRefreshed) {
+        console.log(chalk.green('  Claude Code:   .claude/ refreshed (skills, workflows, hooks) + native setup (.mcp.json, MCP deps)'));
+        if (result.claudeBackupPath) {
+          console.log(chalk.gray(`  .claude backup: ${path.basename(result.claudeBackupPath)}`));
+        }
+      }
+      if (result.globalSkillsDiverged && result.globalSkillsDiverged.length > 0) {
+        const { syncCommand } = require('../lib/global-skills-sync');
+        console.log(chalk.yellow(`  [!] Copies globales ~/.claude/skills divergentes : ${result.globalSkillsDiverged.join(', ')}`));
+        console.log(chalk.yellow('      Elles peuvent masquer les skills fraichement mis a jour. Pour les synchroniser :'));
+        for (const line of syncCommand(result.globalSkillsDiverged).split('\n')) {
+          console.log(chalk.gray(`        ${line}`));
+        }
+      }
       if (result.backupPath) {
         console.log(chalk.gray(`  Backup: ${path.basename(result.backupPath)}`));
       }
@@ -2056,20 +2204,13 @@ program
     }
   });
 
+// Explicit alias for the default action — same graphical wizard, kept for
+// discoverability and backward compatibility with `create-byan-agent web`.
 program
   .command('web')
-  .description('Launch BYAN WebUI installer in the browser')
+  .description('Launch BYAN WebUI installer in the browser (same as the default action)')
   .option('-p, --port <port>', 'Port number', '3000')
-  .action(async (options) => {
-    const ByanWebUI = require('../src/webui/server');
-    const port = parseInt(options.port, 10);
-    const projectRoot = process.cwd();
-
-    console.log(chalk.cyan.bold('\n  BYAN WebUI\n'));
-    const server = new ByanWebUI({ port, projectRoot });
-    server.start();
-    console.log(chalk.green(`  Server running at http://localhost:${port}`));
-    console.log(chalk.gray('  Press Ctrl+C to stop\n'));
-  });
+  .option('--dir <dir>', 'Repertoire d installation (defaut : dossier courant)')
+  .action(async (options) => launchWeb(options));
 
 program.parse(process.argv);

package/install/lib/desktop-app.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const path = require('path');
+
+// Detection of an installed BYAN Desktop app (Electron, packaged by
+// electron-builder). productName is "BYAN", appId fr.acadenice.byan. We match
+// CONCRETE executables at the install locations electron-builder produces per
+// OS — NOT a bare `byan` on PATH, which would false-positive on any unrelated
+// binary of that name. The AppImage build has no fixed install path, so it is
+// covered by the BYAN_DESKTOP_BIN override (the user points at their AppImage).
+//
+// Pure and injectable: platform / env / homedir / existsSync are all overridable
+// so the detection is unit-testable without touching the real filesystem.
+
+function candidatePaths(platform, env, homedir) {
+  const out = [];
+
+  // Build the TARGET platform's paths, not the host's — so detection is correct
+  // and unit-testable regardless of the OS the check runs on.
+  const p = platform === 'win32' ? path.win32 : path.posix;
+
+  // Explicit override always wins (AppImage users, custom install prefixes).
+  if (env.BYAN_DESKTOP_BIN) out.push(env.BYAN_DESKTOP_BIN);
+
+  if (platform === 'darwin') {
+    out.push('/Applications/BYAN.app/Contents/MacOS/BYAN');
+    out.push(p.join(homedir, 'Applications', 'BYAN.app', 'Contents', 'MacOS', 'BYAN'));
+  } else if (platform === 'win32') {
+    if (env.LOCALAPPDATA) out.push(p.join(env.LOCALAPPDATA, 'Programs', 'BYAN', 'BYAN.exe'));
+    if (env.PROGRAMFILES) out.push(p.join(env.PROGRAMFILES, 'BYAN', 'BYAN.exe'));
+  } else {
+    // Linux deb/rpm: electron-builder installs to /opt/<productName> and drops
+    // a symlink /usr/bin/<executableName> (productName lowercased -> byan).
+    out.push('/opt/BYAN/byan');
+    out.push('/usr/bin/byan');
+    out.push('/usr/local/bin/byan');
+  }
+
+  return out;
+}
+
+function detectDesktopApp(opts = {}) {
+  const platform = opts.platform || process.platform;
+  const env = opts.env || process.env;
+  const homedir = opts.homedir || require('os').homedir();
+  const existsSync = opts.existsSync || require('fs').existsSync;
+
+  for (const candidate of candidatePaths(platform, env, homedir)) {
+    if (candidate && existsSync(candidate)) {
+      const source = env.BYAN_DESKTOP_BIN === candidate ? 'env' : 'path';
+      return { found: true, bin: candidate, source };
+    }
+  }
+
+  return { found: false, bin: null, source: null };
+}
+
+module.exports = { detectDesktopApp, candidatePaths };

package/install/lib/global-skills-sync.js

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * GLOBAL SKILLS SYNC — closes the "stale global copy masks the fresh install"
+ * trap at INSTALL TIME.
+ *
+ * Field failure (2026-07-21): the installer laid a fully up-to-date
+ * .claude/skills/ in the project, but the user's manual copies under
+ * ~/.claude/skills/ (same names, months old) kept being the ones the slash
+ * command loaded — the freshly installed features stayed invisible. The
+ * session-start freshness hook flags this at the NEXT session; the installer
+ * can flag it at the very moment it creates the situation, and it has a TTY to
+ * ask. Red line kept from the hook: no silent write into the user's home —
+ * consent is asked, refusal or a non-interactive terminal degrades to a clear
+ * notice with the exact command.
+ *
+ * The comparison core is NOT duplicated: we require compareSkills from the
+ * .claude payload this very package ships (templates/.claude/hooks/lib/
+ * skill-freshness.js), the same tested module the session hook uses.
+ */
+
+const fs = require('fs-extra');
+const os = require('os');
+const path = require('path');
+
+function loadComparator(templateDir) {
+  return require(path.join(templateDir, '.claude', 'hooks', 'lib', 'skill-freshness.js'));
+}
+
+/**
+ * Compare the project's freshly installed skills with same-named global copies.
+ * Silent-safe: any failure (no global dir, unreadable comparator) yields an
+ * empty result — this check must never break an install.
+ *
+ * @returns {Promise<{diverged: string[], checked: number}>}
+ */
+async function checkGlobalSkills(projectRoot, templateDir, { homeDir = os.homedir() } = {}) {
+  try {
+    const globalSkillsDir = path.join(homeDir, '.claude', 'skills');
+    if (!await fs.pathExists(globalSkillsDir)) return { diverged: [], checked: 0 };
+    const { compareSkills } = loadComparator(templateDir);
+    return compareSkills({
+      projectSkillsDir: path.join(projectRoot, '.claude', 'skills'),
+      globalSkillsDir,
+    });
+  } catch {
+    return { diverged: [], checked: 0 };
+  }
+}
+
+/**
+ * Copy the project SKILL.md over the global copy, per name. Only called after
+ * explicit consent. Returns the names actually synced (a per-name failure is
+ * skipped, never thrown).
+ */
+async function syncGlobalSkills(projectRoot, names, { homeDir = os.homedir() } = {}) {
+  const synced = [];
+  for (const name of names) {
+    try {
+      const src = path.join(projectRoot, '.claude', 'skills', name, 'SKILL.md');
+      const dest = path.join(homeDir, '.claude', 'skills', name, 'SKILL.md');
+      await fs.copy(src, dest, { overwrite: true });
+      synced.push(name);
+    } catch {
+      // one bad copy must not abort the others
+    }
+  }
+  return synced;
+}
+
+/** The exact copy-paste command shown when we do not write ourselves. */
+function syncCommand(names, { homeDir = os.homedir() } = {}) {
+  const globalDir = path.join(homeDir, '.claude', 'skills');
+  return names
+    .map((n) => `cp .claude/skills/${n}/SKILL.md ${path.join(globalDir, n, 'SKILL.md')}`)
+    .join('\n');
+}
+
+/**
+ * End-of-install offer.
+ *
+ * @param {string} projectRoot
+ * @param {string} templateDir
+ * @param {Object} opts
+ * @param {(question: string) => Promise<boolean>} [opts.ask] - Consent
+ *   collector (inquirer in the CLI). Absent (non-interactive) -> never write,
+ *   notice only.
+ * @param {(line: string) => void} [opts.log]
+ * @returns {Promise<{diverged: string[], synced: string[]}>}
+ */
+async function offerGlobalSkillsSync(projectRoot, templateDir, { ask = null, homeDir = os.homedir(), log = console.log } = {}) {
+  const { diverged } = await checkGlobalSkills(projectRoot, templateDir, { homeDir });
+  if (diverged.length === 0) return { diverged: [], synced: [] };
+
+  log(`  [!] ${diverged.length} skill(s) globaux divergents dans ~/.claude/skills : ${diverged.join(', ')}`);
+  log('      Ces copies datent d\'avant cette installation et peuvent etre celles que la');
+  log('      commande /<skill> charge — les nouveautes resteraient invisibles.');
+
+  let synced = [];
+  if (typeof ask === 'function') {
+    const yes = await ask('Synchroniser ces copies globales depuis le projet (sauvegarde du contenu : aucune — elles seront ecrasees) ?');
+    if (yes) {
+      synced = await syncGlobalSkills(projectRoot, diverged, { homeDir });
+      log(`  [OK] ${synced.length} copie(s) globale(s) synchronisee(s) depuis le projet`);
+      return { diverged, synced };
+    }
+  }
+  log('      Rien n\'a ete modifie dans ~/.claude. Pour synchroniser toi-meme :');
+  for (const line of syncCommand(diverged, { homeDir }).split('\n')) log(`        ${line}`);
+  return { diverged, synced };
+}
+
+module.exports = {
+  checkGlobalSkills,
+  syncGlobalSkills,
+  syncCommand,
+  offerGlobalSkillsSync,
+};