create-byan-agent 2.29.1 → 2.35.0

package/install/lib/native-helper.js

@@ -11,6 +11,9 @@
  */
 
 const { execSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 
 /**
  * commandExists(cmd) -> boolean. Is an executable resolvable on PATH?
@@ -26,6 +29,70 @@ function commandExists(cmd, { run = execSync, platform = process.platform } = {}
   }
 }
 
+/**
+ * safeHomedir() -> the home directory, or '' if it cannot be determined. WHY:
+ * os.homedir() THROWS on an env with no $HOME/$USERPROFILE AND no passwd entry
+ * for the effective uid (distroless / random-uid containers). An optional install
+ * helper must never throw on that — it degrades to "no home dir to scan".
+ */
+function safeHomedir() {
+  try {
+    return os.homedir();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * knownBinDirs() -> ordered list of directories where installers commonly drop a
+ * binary that is NOT on a non-login shell's PATH. The canonical case: `cargo
+ * install` lands in ~/.cargo/bin, which Debian's apt-packaged cargo does NOT add
+ * to PATH — so a freshly built binary is present yet invisible to a bare probe.
+ * fs/env/home are injectable for tests. `home` defaults via safeHomedir so a
+ * HOME-less environment yields a shorter scan instead of a throw.
+ */
+function knownBinDirs({ env = process.env, home = safeHomedir(), platform = process.platform } = {}) {
+  const dirs = [];
+  if (env && env.CARGO_HOME) dirs.push(path.join(env.CARGO_HOME, 'bin'));
+  dirs.push(path.join(home, '.cargo', 'bin')); // cargo install
+  dirs.push(path.join(home, '.local', 'bin')); // pip/pipx + many curl scripts
+  if (platform === 'win32') {
+    if (env && env.LOCALAPPDATA) dirs.push(path.join(env.LOCALAPPDATA, 'Programs'));
+  } else {
+    dirs.push('/usr/local/bin'); // common script target + brew (intel mac)
+    dirs.push('/opt/homebrew/bin'); // brew (apple silicon)
+    dirs.push('/usr/bin');
+  }
+  return dirs;
+}
+
+/**
+ * resolveBinary(name) -> the command to invoke the executable, or null if it
+ * cannot be located. Returns the BARE name when it is on PATH (let the shell
+ * resolve it), else an ABSOLUTE path found in a knownBinDir. WHY: an optional
+ * native install can succeed yet leave the binary off PATH; callers must verify
+ * and wire it by its real location, not declare failure. All I/O is injectable.
+ */
+function resolveBinary(name, {
+  has = commandExists,
+  existsSync = fs.existsSync,
+  env = process.env,
+  home = safeHomedir(),
+  platform = process.platform,
+} = {}) {
+  if (has(name)) return name;
+  const exe = platform === 'win32' ? `${name}.exe` : name;
+  for (const dir of knownBinDirs({ env, home, platform })) {
+    const full = path.join(dir, exe);
+    try {
+      if (existsSync(full)) return full;
+    } catch {
+      // a stat error on one candidate must not abort the scan
+    }
+  }
+  return null;
+}
+
 /**
  * detectPlatform() -> 'mac' | 'windows' | 'linux'. Coarse bucket for choosing an
  * install strategy. Keeps the platform string in ONE place.
@@ -47,4 +114,4 @@ function firstAvailable(candidates, { has = commandExists } = {}) {
   return candidates.find((c) => c && c.tool && has(c.tool)) || null;
 }
 
-module.exports = { commandExists, detectPlatform, firstAvailable };
+module.exports = { commandExists, detectPlatform, firstAvailable, knownBinDirs, resolveBinary, safeHomedir };

package/install/lib/rtk-integration.js

@@ -9,27 +9,43 @@
  *
  * MAINTAINABILITY by design (the whole point of choosing this shape):
  *  - We do NOT reimplement per-OS download / checksum / version pinning. We
- *    DELEGATE the install to rtk's own canonical installer (brew / cargo / the
- *    official install.sh), and DELEGATE the Claude Code hook wiring to rtk's own
- *    `rtk init -g`. BYAN maintains only "pick the available installer, run it,
- *    verify, ask rtk to wire its hook" — a tiny surface, bumped via one constant.
+ *    DELEGATE the install to rtk's own canonical installer (brew / the official
+ *    install.sh / cargo), and DELEGATE the Claude Code hook wiring to rtk's own
+ *    `rtk init -g --auto-patch` (the `--auto-patch` is what makes it non-
+ *    interactive — see wireHook). BYAN maintains only "pick the available
+ *    installer, run it bounded + visible, locate the binary, ask rtk to wire its
+ *    hook" — a tiny surface, bumped via one constant.
  *  - SUPPLY-CHAIN: we pin to a TAG, never a moving branch. cargo builds the
- *    tagged source (`--tag`), and install.sh is fetched from the IMMUTABLE tag ref
- *    (and that script itself checksum-verifies the binary it downloads). So the
- *    fetched artifacts are reproducible, not "whatever master is today".
- *  - Everything is graceful: a missing installer or a failed step is a no-op that
- *    NEVER breaks the BYAN install (returns { ok:true, synced:false, reason }).
- *  - The command runner + the PATH probe are injectable, so the whole flow is
- *    unit-tested without shelling out (see install/__tests__/rtk-integration.test.js).
+ *    tagged source (`--tag`), and install.sh is fetched from the IMMUTABLE tag ref.
+ *    That script verifies a SHA-256 of the downloaded binary against a published
+ *    checksums.txt and aborts on mismatch (source: refs/tags/v0.42.4/install.sh,
+ *    fetched + verified 2026-06-23). So the fetched artifacts are reproducible and
+ *    integrity-checked, not "whatever master is today".
+ *  - FAIL-PROOF: the delegated install runs with a per-strategy TIMEOUT (a hung
+ *    network/build is bounded, not infinite) and with INHERITED stdio (the user
+ *    SEES the installer's progress instead of staring at a frozen line; this also
+ *    sidesteps execSync's 1MB maxBuffer cap that a verbose build would blow). Any
+ *    missing installer / failed / timed-out step is a logged no-op that NEVER
+ *    breaks the BYAN install (returns { ok:true, synced:false, reason }).
+ *  - OFF-PATH SAFE: a successful install can leave the binary off PATH (the
+ *    classic: cargo drops it in ~/.cargo/bin, which Debian's apt-cargo does not
+ *    add to PATH). We RESOLVE the binary across known install dirs before
+ *    declaring "unverified", verify + wire it by its real path, and hand the user
+ *    a one-line PATH hint. The user's own report (rtk installed at ~/.cargo/bin,
+ *    invisible to a bare probe) is exactly this case.
+ *  - The command runner + the PATH probe + the resolver are injectable, so the
+ *    whole flow is unit-tested without shelling out (see
+ *    install/__tests__/rtk-integration.test.js).
  *
  * Mirrors the ENTRY-POINT shape of byan-web-integration.js / byan-leantime-
  * integration.js (one `setup*Integration`); the return contract is { ok, synced,
- * reason, ... } because persistence is owned by rtk's own `rtk init -g`, not by
+ * reason, ... } because persistence is owned by rtk's own `rtk init -g --auto-patch`, not by
  * byan-platform-config.
  */
 
 const { execSync } = require('child_process');
-const { commandExists, firstAvailable } = require('./native-helper');
+const path = require('path');
+const { commandExists, resolveBinary, firstAvailable } = require('./native-helper');
 
 // Pinned install target. Bumping rtk = change these two constants only. We pin a
 // TAG so the install is reproducible and supply-chain-bounded (see header).
@@ -38,20 +54,37 @@ const RTK_TAG = `v${RTK_VERSION}`;
 const RTK_REPO = 'https://github.com/rtk-ai/rtk';
 const RTK_INSTALL_SH = `https://raw.githubusercontent.com/rtk-ai/rtk/refs/tags/${RTK_TAG}/install.sh`;
 
+// Per-strategy timeout (ms). A prebuilt-binary path (brew / script) should be
+// quick; cargo COMPILES from source and is legitimately slow, so it gets a wide
+// budget. The bound exists to cap a genuine HANG, not to race a normal build.
+const MIN = 60 * 1000;
+const RTK_TIMEOUT_MS = { brew: 5 * MIN, script: 5 * MIN, cargo: 20 * MIN };
+const RTK_DEFAULT_TIMEOUT_MS = 10 * MIN;
+
 /**
  * Ordered install strategies — each DELEGATES to rtk's own canonical installer,
- * pinned to RTK_TAG where the mechanism allows. Preference: brew (cleanest
- * upgrades, vetted formula) > cargo (any Rust dev, pinned --tag) > the official
- * install.sh at the immutable tag ref (universal fallback, self-checksumming).
+ * pinned to RTK_TAG where the mechanism allows.
+ *
+ * Order = brew > script > cargo. WHY this order (not brew > cargo > script):
+ *  - brew first: vetted formula, cleanest upgrades, prebuilt.
+ *  - script second: the official install.sh downloads a PREBUILT binary to a
+ *    PATH-stable location in seconds. It is pinned to the immutable tag ref and
+ *    verifies the binary's SHA-256 before installing (see the cited check above)
+ *    — a bounded supply-chain surface.
+ *  - cargo LAST: it COMPILES from source (minutes) AND drops the binary in
+ *    ~/.cargo/bin, frequently off a non-login PATH. It stays as a build-from-
+ *    source fallback for machines without brew/curl, not the default path.
  */
 function installStrategies() {
   return [
-    { id: 'brew', tool: 'brew', cmd: 'brew install rtk' },
-    { id: 'cargo', tool: 'cargo', cmd: `cargo install --git ${RTK_REPO} --tag ${RTK_TAG}` },
+    { id: 'brew', tool: 'brew', cmd: 'brew install rtk', timeoutMs: RTK_TIMEOUT_MS.brew },
     // Pass RTK_VERSION into the script so it pins the BINARY too (the script
     // builds releases/download/${VERSION}/...; without it, it resolves
     // releases/latest). Pinning the URL alone is not enough — this pins both.
-    { id: 'script', tool: 'curl', cmd: `curl -fsSL ${RTK_INSTALL_SH} | RTK_VERSION=${RTK_TAG} sh` },
+    // The script verifies a SHA-256 of the binary (vs checksums.txt) before
+    // installing — verified at refs/tags/v0.42.4/install.sh, 2026-06-23.
+    { id: 'script', tool: 'curl', cmd: `curl -fsSL ${RTK_INSTALL_SH} | RTK_VERSION=${RTK_TAG} sh`, timeoutMs: RTK_TIMEOUT_MS.script },
+    { id: 'cargo', tool: 'cargo', cmd: `cargo install --git ${RTK_REPO} --tag ${RTK_TAG}`, timeoutMs: RTK_TIMEOUT_MS.cargo },
   ];
 }
 
@@ -59,19 +92,78 @@ function oneLine(err) {
   return String((err && err.message) || err).split('\n')[0];
 }
 
+// A bounded, env-overridable timeout for a strategy. BYAN_RTK_TIMEOUT_MS (ms)
+// lets a user widen the bound (e.g. a slow machine compiling via cargo). Only a
+// POSITIVE integer is honored: Node treats timeout:0 as "no timeout", so a 0
+// override would silently re-introduce the unbounded hang the bound exists to
+// prevent — it falls back to the strategy budget instead.
+function timeoutFor(strat, { env = process.env } = {}) {
+  const raw = env && env.BYAN_RTK_TIMEOUT_MS;
+  if (raw != null && /^[0-9]+$/.test(String(raw))) {
+    const n = Number(raw);
+    if (n > 0) return n;
+  }
+  return (strat && strat.timeoutMs) || RTK_DEFAULT_TIMEOUT_MS;
+}
+
+// Did execSync throw because WE killed it on timeout (vs the command failing on
+// its own)? Node sets `killed=true` and code 'ETIMEDOUT' when it kills the child
+// on timeout; a build error sets a non-zero exit status with killed=false. We do
+// NOT match a bare 'SIGTERM' signal: a sub-process self-terminating with SIGTERM
+// for an unrelated reason would otherwise be mislabelled a timeout.
+function isTimeout(err) {
+  return Boolean(err && (err.killed === true || err.code === 'ETIMEDOUT'));
+}
+
+// A shell/platform-correct "add this dir to PATH" hint. The resolved binary can
+// live off PATH (cargo -> ~/.cargo/bin); the user needs the line that actually
+// works in THEIR shell — fish rejects POSIX `export`, Windows rejects both.
+function pathHintFor(bin, { env = process.env, platform = process.platform } = {}) {
+  // Parse the dir with the TARGET platform's rules, not the host's — so a win32
+  // path yields the right dir even when this code runs on a POSIX CI host.
+  const dir = (platform === 'win32' ? path.win32 : path.posix).dirname(bin);
+  if (platform === 'win32') return `$env:PATH = "${dir};$env:PATH"`;
+  const shell = String((env && env.SHELL) || '');
+  if (/(^|\/)fish$/.test(shell)) return `fish_add_path ${dir}`;
+  return `export PATH="${dir}:$PATH"`;
+}
+
 /**
- * rtkStatus() -> { installed, version }. Never throws. Parses `rtk --version`
- * ("rtk 0.42.4"). An installed-but-unparseable build yields { installed:true,
- * version:null } (a real runtime possibility, handled downstream).
+ * rtkStatus() -> { installed, version, bin }. Never throws. Probes `<bin>
+ * --version` ("rtk 0.42.4"), default bin "rtk" (on PATH). An installed-but-
+ * unparseable build yields { installed:true, version:null }.
  */
-function rtkStatus({ run = execSync } = {}) {
+function rtkStatus({ run = execSync, bin = 'rtk' } = {}) {
   try {
-    const out = String(run('rtk --version', { stdio: 'pipe' }) || '');
+    const out = String(run(`${bin} --version`, { stdio: 'pipe' }) || '');
     const m = out.match(/rtk\s+v?([0-9]+\.[0-9]+\.[0-9]+)/i);
-    return { installed: true, version: m ? m[1] : null };
+    return { installed: true, version: m ? m[1] : null, bin };
   } catch {
-    return { installed: false, version: null };
+    return { installed: false, version: null, bin: null };
+  }
+}
+
+/**
+ * locateRtk() -> a verified { installed, version, bin } by trying the bare name
+ * first (on PATH), then resolving across known install dirs (off-PATH). Returns
+ * the off-PATH absolute path in `bin` when that is where it was found.
+ */
+function locateRtk({ run = execSync, has = commandExists, resolve = resolveBinary, env = process.env } = {}) {
+  const onPath = rtkStatus({ run, bin: 'rtk' });
+  if (onPath.installed) return onPath;
+  // The resolver must never break the never-throws contract; degrade to not-found
+  // if it (or a misbehaving injected resolver) throws.
+  let resolved = null;
+  try {
+    resolved = resolve('rtk', { has, env });
+  } catch {
+    resolved = null;
+  }
+  if (resolved && resolved !== 'rtk') {
+    const s = rtkStatus({ run, bin: resolved });
+    if (s.installed) return s;
   }
+  return { installed: false, version: null, bin: null };
 }
 
 /**
@@ -82,78 +174,116 @@ function pickStrategy({ has = commandExists } = {}) {
 }
 
 /**
- * doctor() -> a status report for diagnostics / a `byan` doctor surface. `pinned`
- * is the version BYAN installs/targets — NOT an enforced floor on a pre-existing
- * rtk (we do not break a user's own older rtk).
+ * doctor() -> a status report for diagnostics / a `byan` doctor surface. Resolves
+ * the binary across known dirs so an off-PATH install is reported as installed
+ * (with its real path), not as missing. `pinned` is the version BYAN targets —
+ * NOT an enforced floor on a pre-existing rtk.
  */
-function doctor({ run = execSync } = {}) {
-  const s = rtkStatus({ run });
+function doctor({ run = execSync, has = commandExists, resolve = resolveBinary, env = process.env } = {}) {
+  const s = locateRtk({ run, has, resolve, env });
   return {
     component: 'rtk',
     installed: s.installed,
     version: s.version,
+    bin: s.bin,
     pinned: RTK_VERSION,
     repo: RTK_REPO,
-    hookCommand: 'rtk init -g',
+    hookCommand: 'rtk init -g --auto-patch',
   };
 }
 
 // Delegate the Claude Code hook wiring to rtk's OWN command (idempotent). This is
-// the maintainability win: no manual settings.json merge to keep in sync.
-function wireHook({ run, log, installedVia, version }) {
+// the maintainability win: no manual settings.json merge to keep in sync. Wires
+// via the resolved `bin` so an off-PATH install still gets its hook.
+//
+// `--auto-patch` is REQUIRED: bare `rtk init -g` PROMPTS before patching
+// settings.json, and we run it non-interactively (stdio:'pipe', no TTY) — so the
+// prompt gets no answer and rtk silently writes only the instruction layer
+// (RTK.md + @RTK.md) WITHOUT the PreToolUse hook. `--auto-patch` patches
+// settings.json non-interactively, so the transparent command-rewriting hook is
+// actually installed. (Verified live: `rtk init --show` reports "Hook: not found"
+// after bare `-g` piped, "Hook: ... configured" after `-g --auto-patch`.)
+function wireHook({ run, log, installedVia, version, bin = 'rtk', env = process.env, platform = process.platform }) {
+  const offPath = bin !== 'rtk';
+  const initCmd = `${bin} init -g --auto-patch`;
   try {
-    run('rtk init -g', { stdio: 'pipe' });
-    log(`rtk: ready (${installedVia}, v${version || '?'}) — hook wired via 'rtk init -g'. Restart Claude Code to activate.`);
-    return { ok: true, synced: true, reason: 'wired', installed: true, installedVia, version, hook: true };
+    run(initCmd, { stdio: 'pipe' });
+    log(`rtk: ready (${installedVia}, v${version || '?'}) — hook wired via '${initCmd}'. Restart Claude Code to activate.`);
+    const r = { ok: true, synced: true, reason: 'wired', installed: true, installedVia, version, hook: true, bin };
+    if (offPath) {
+      r.pathHint = pathHintFor(bin, { env, platform });
+      log(`rtk: note — installed at ${bin}, not on your PATH. Add it: ${r.pathHint}`);
+    }
+    return r;
   } catch (err) {
-    log(`rtk: installed (${installedVia}) but 'rtk init -g' failed (${oneLine(err)}) — run it manually, BYAN unaffected.`);
-    return { ok: true, synced: false, reason: 'hook-failed', installed: true, installedVia, version, hook: false };
+    log(`rtk: installed (${installedVia}) but '${initCmd}' failed (${oneLine(err)}) — run it manually, BYAN unaffected.`);
+    const r = { ok: true, synced: false, reason: 'hook-failed', installed: true, installedVia, version, hook: false, bin };
+    if (offPath) r.pathHint = pathHintFor(bin, { env, platform });
+    return r;
   }
 }
 
 /**
  * setupRtkIntegration(options) -> { ok, synced, reason, ... }. The single entry.
  *
- * Flow: if rtk is already present, just (re)wire the hook (idempotent). Otherwise
- * pick an available installer, delegate the install to rtk, verify, then wire the
- * hook. Any missing tool / failed step degrades to a logged no-op — it NEVER
- * throws and NEVER fails the surrounding BYAN install. `ok` is therefore always
- * true; `synced` says whether rtk ended up wired.
+ * Flow: if rtk is already present (on PATH or off-PATH in a known dir), just
+ * (re)wire the hook (idempotent). Otherwise pick an available installer, delegate
+ * the install (BOUNDED by a timeout + VISIBLE via inherited stdio), LOCATE the
+ * binary, verify, then wire the hook. Any missing tool / failed / timed-out step
+ * degrades to a logged no-op — it NEVER throws and NEVER fails the surrounding
+ * BYAN install. `ok` is therefore always true; `synced` says whether rtk ended
+ * up wired. An off-PATH install carries a `pathHint`.
  *
  * @param {object} [o]
- * @param {Function} [o.run]  command runner (default execSync) — injected in tests
- * @param {Function} [o.has]  PATH probe (default commandExists) — injected in tests
- * @param {Function} [o.log]  one-line breadcrumb sink (default no-op)
+ * @param {Function} [o.run]      command runner (default execSync) — injected in tests
+ * @param {Function} [o.has]      PATH probe (default commandExists) — injected in tests
+ * @param {Function} [o.resolve]  binary resolver (default resolveBinary) — injected in tests
+ * @param {Function} [o.log]      one-line breadcrumb sink (default no-op)
+ * @param {object}   [o.env]      environment (default process.env) — for the timeout override
  */
-function setupRtkIntegration({ run = execSync, has = commandExists, log = () => {} } = {}) {
-  const before = rtkStatus({ run });
+function setupRtkIntegration({
+  run = execSync,
+  has = commandExists,
+  resolve = resolveBinary,
+  log = () => {},
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  const before = locateRtk({ run, has, resolve, env });
   if (before.installed) {
-    return wireHook({ run, log, installedVia: 'already-present', version: before.version });
+    return wireHook({ run, log, installedVia: 'already-present', version: before.version, bin: before.bin, env, platform });
   }
 
   const strat = pickStrategy({ has });
   if (!strat) {
-    log('rtk: no installer found (brew / cargo / curl) — skipped. BYAN install unaffected.');
+    log('rtk: no installer found (brew / curl / cargo) — skipped. BYAN install unaffected.');
     return { ok: true, synced: false, reason: 'no-installer', installed: false, hook: false };
   }
 
-  // Breadcrumb BEFORE the (silent, possibly slow) delegated install so the user
-  // is not left staring at a frozen prompt while rtk's installer runs.
-  log(`rtk: installing via ${strat.id} (pinned ${RTK_TAG}; this can take a moment)...`);
+  // Breadcrumb BEFORE the delegated install. stdio is INHERITED so the installer's
+  // own progress streams to the user (no frozen line), bounded by a timeout.
+  const timeoutMs = timeoutFor(strat, { env });
+  log(`rtk: installing via ${strat.id} (pinned ${RTK_TAG}; up to ${Math.round(timeoutMs / MIN)}min, Ctrl+C is safe)...`);
   try {
-    run(strat.cmd, { stdio: 'pipe' });
+    run(strat.cmd, { stdio: 'inherit', timeout: timeoutMs });
   } catch (err) {
+    if (isTimeout(err)) {
+      log(`rtk: install via ${strat.id} exceeded ${Math.round(timeoutMs / MIN)}min — stopped (a background build may still continue). Retry with 'npm run setup-rtk' (or widen BYAN_RTK_TIMEOUT_MS). BYAN unaffected.`);
+      return { ok: true, synced: false, reason: `install-timeout:${strat.id}`, installed: false, hook: false };
+    }
     log(`rtk: install via ${strat.id} failed (${oneLine(err)}) — skipped gracefully.`);
     return { ok: true, synced: false, reason: `install-failed:${strat.id}`, installed: false, hook: false };
   }
 
-  const after = rtkStatus({ run });
+  // The binary may be installed but OFF PATH (cargo -> ~/.cargo/bin). Resolve it
+  // before declaring failure, and wire it by its real location.
+  const after = locateRtk({ run, has, resolve, env });
   if (!after.installed) {
     log(`rtk: install via ${strat.id} ran but 'rtk --version' did not confirm — skipped.`);
     return { ok: true, synced: false, reason: 'install-unverified', installed: false, hook: false };
   }
 
-  return wireHook({ run, log, installedVia: strat.id, version: after.version });
+  return wireHook({ run, log, installedVia: strat.id, version: after.version, bin: after.bin, env, platform });
 }
 
 /**
@@ -171,12 +301,18 @@ function shouldOfferRtk({ env = process.env, isTTY = !!(process.stdin && process
 module.exports = {
   setupRtkIntegration,
   rtkStatus,
+  locateRtk,
   pickStrategy,
   installStrategies,
+  timeoutFor,
+  isTimeout,
+  pathHintFor,
   doctor,
   shouldOfferRtk,
   RTK_VERSION,
   RTK_TAG,
   RTK_INSTALL_SH,
   RTK_REPO,
+  RTK_TIMEOUT_MS,
+  RTK_DEFAULT_TIMEOUT_MS,
 };

package/install/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.29.1",
+  "version": "2.35.0",
   "description": "BYAN - Intelligent AI agent installer with multi-platform native support (Claude Code, Codex/OpenCode)",
   "bin": {
     "create-byan-agent": "bin/create-byan-agent-v2.js"

package/install/packages/platform-config/lib/credentials.js

@@ -18,7 +18,19 @@ const path = require('path');
 const fs = require('fs-extra');
 
 // Keys the credentials file understands. Any other key passed in is ignored.
-const KNOWN_KEYS = ['BYAN_API_URL', 'BYAN_API_TOKEN', 'LEANTIME_API_URL', 'LEANTIME_API_TOKEN'];
+// The Google Docs publish keys (byan_publish) live here too so a per-user
+// service-account setup persists alongside the byan_web / Leantime config; the
+// MCP server reads them via resolve-config. GOOGLE_APPLICATION_CREDENTIALS is a
+// PATH to the SA JSON (not the key itself) -- the key file stays separate, 0600.
+const KNOWN_KEYS = [
+  'BYAN_API_URL',
+  'BYAN_API_TOKEN',
+  'LEANTIME_API_URL',
+  'LEANTIME_API_TOKEN',
+  'GOOGLE_APPLICATION_CREDENTIALS',
+  'GDOC_TEMPLATE_ID',
+  'GDOC_LOGO_PNG_URL',
+];
 
 function credentialsDir(homedir = os.homedir()) {
   return path.join(homedir, '.byan');

package/install/setup-gdoc.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * setup-gdoc -- explicit opt-in setup for the byan_publish service-account key.
+ *
+ * Run on demand: `npm run setup-gdoc` (or `node install/setup-gdoc.js`). Walks
+ * the user through creating a Google service account + key, imports the JSON to
+ * ~/.byan/google-sa.json (0600), and persists the publish config into
+ * ~/.byan/credentials.json. It NEVER throws and exits 0 : the SA setup is
+ * optional and must not fail the surrounding flow. The real logic lives in
+ * lib/gdoc-setup.js and is unit-tested.
+ */
+
+const chalk = require('chalk');
+const { setupGdocPublish } = require('./lib/gdoc-setup');
+
+async function main() {
+  console.log(chalk.cyan('\nbyan_publish -- clé service account (Google Docs headless)'));
+  console.log(chalk.gray('  Open source : tu fournis ta clé ; rien de secret ne ship.\n'));
+
+  const result = await setupGdocPublish({ log: (...a) => console.log(...a) });
+
+  if (result.configured) {
+    console.log(chalk.green(`\n  Configuré. Clé : ${result.path}`));
+    console.log(chalk.gray('  Installe aussi googleapis dans le MCP server : (cd _byan/mcp/byan-mcp-server && npm install googleapis google-auth-library)'));
+  } else {
+    console.log(chalk.yellow(`\n  Non configuré (${result.skipReason || 'ignoré'}). BYAN reste fonctionnel.`));
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    // Last-resort guard : an optional setup must not crash with a non-zero exit.
+    console.log(chalk.yellow(`  setup-gdoc ignoré : ${err.message}`));
+    process.exit(0);
+  });
+}
+
+module.exports = { main };

package/install/setup-rtk.js

@@ -6,7 +6,7 @@
  *
  * Run on demand: `npm run setup-rtk` (or `node install/setup-rtk.js`). It delegates
  * the install to rtk's own canonical installer (brew / cargo / official script) and
- * the Claude Code hook wiring to rtk's own `rtk init -g`. It NEVER throws: a missing
+ * the Claude Code hook wiring to rtk's own `rtk init -g --auto-patch`. It NEVER throws: a missing
  * installer or a failed step is reported and exits 0 (RTK is optional; BYAN works
  * without it). The real logic lives in lib/rtk-integration.js and is unit-tested.
  */
@@ -16,14 +16,18 @@ const { setupRtkIntegration, doctor } = require('./lib/rtk-integration');
 
 function main() {
   console.log(chalk.cyan('\nRTK token optimizer (rtk-ai/rtk) — optional native component'));
-  console.log(chalk.gray('  Cuts dev-command tokens 60-90%; wires its own Claude Code hook.\n'));
+  console.log(chalk.gray('  Cuts dev-command tokens 60-90%; wires its own Claude Code hook.'));
+  console.log(chalk.gray('  Progress streams below. The cargo fallback compiles from source (minutes); Ctrl+C is safe.\n'));
 
   const result = setupRtkIntegration({ log: (m) => console.log(chalk.gray('  ' + m)) });
 
   if (result.synced) {
     console.log(chalk.green(`\n  rtk ready (${result.installedVia}, v${result.version || '?'}). Restart Claude Code to activate.`));
+    if (result.pathHint) console.log(chalk.yellow(`  rtk is not on your PATH — add it: ${result.pathHint}`));
   } else if (result.reason === 'no-installer') {
-    console.log(chalk.yellow('\n  No installer found (brew / cargo / curl). Install one, then re-run `npm run setup-rtk`.'));
+    console.log(chalk.yellow('\n  No installer found (brew / curl / cargo). Install one, then re-run `npm run setup-rtk`.'));
+  } else if (result.pathHint) {
+    console.log(chalk.yellow(`\n  rtk found off-PATH (${result.reason}) — add it then re-run: ${result.pathHint}`));
   } else {
     console.log(chalk.yellow(`\n  rtk not wired (${result.reason}). BYAN is unaffected; you can retry later.`));
   }

package/install/templates/.claude/CLAUDE.md

@@ -62,8 +62,9 @@ Doctrine d'equipe complete (template role-in-team, analogie orchestre, principes
 - Doctrine d'equipe: voir @.claude/rules/team-doctrine.md
 - Methodologie: voir @.claude/rules/merise-agile.md
 - Systeme de confiance epistemique: voir @.claude/rules/elo-trust.md
-- Protocol fact-check scientifique: voir @.claude/rules/fact-check.md
-- Mode strict anti-downgrade: voir @.claude/rules/strict-mode.md
+- Protocol fact-check scientifique: voir .claude/rules/fact-check.md (charge a la demande via le skill byan-fact-check)
+- Mode strict anti-downgrade: voir .claude/rules/strict-mode.md (charge a la demande via le skill byan-strict)
+- Architecture portable (noyau portable, projection native): voir .claude/rules/portable-core.md (charge a la demande)
 - Systeme API byan_web: voir @.claude/rules/byan-api.md
 
 ## API byan_web
@@ -109,7 +110,7 @@ Protocole : lock du scope -> build complet -> self-verify >= 3 passes -> complet
 - Filet final : `.githooks/pre-commit` bloque le commit si une session strict est engagee mais non completee
 - Persistance : sessions poussees vers l'API byan_web (autorite ; local = miroir/fallback offline) via `lib/strict-sync.js` ; migration `033` + `routes/strict-sessions.js` cote byan_web
 
-Detail complet : voir @.claude/rules/strict-mode.md
+Detail complet (hors contexte par defaut, charge a la demande via le skill byan-strict) : voir .claude/rules/strict-mode.md
 
 <!-- BYAN-AUTOBENCH:BEGIN (Generated by byan-sync-rules from _byan/_config/autobench.yaml. Do not hand-edit.) -->
 ## BYAN Auto-Benchmark
@@ -120,5 +121,15 @@ both gates hold (>= 2 non-substitutable options diverging on >= 1 weighted
 criterion). Emit the marker verbatim before the table:
 `<!-- BYAN-BENCH:done g1=<#options> g2=<#divergent-criteria> scope=<internal|external> conf=<assertive|lean> -->`.
 A confirm, a destructive prompt, or an obvious default is not a fork — emit
-`<!-- BYAN-BENCH:skip reason=.. -->` instead. Full doctrine: see @.claude/rules/benchmark.md
+`<!-- BYAN-BENCH:skip reason=.. -->` instead. Full doctrine (loaded on demand): see .claude/rules/benchmark.md
 <!-- BYAN-AUTOBENCH:END -->
+
+## Compact instructions
+
+Quand tu compactes cette conversation, PRESERVE en priorite :
+- l'etat FD BYAN actif s'il existe : phase courante, feature_name, le backlog avec le statut par item, le dernier verdict review/validate (source : `_byan-output/fd-state.json`).
+- la session Strict Mode active s'il y en a une : scope_hash, criteres d'acceptation, nombre de passes, completion (source : `.byan-strict/state.json` + API byan_web).
+- l'identite BYAN : le noyau immuable du soul + la voix tao (registre, signatures, tutoiement, zero emoji). `inject-tao` la reinjecte au SessionStart, mais garde la voix active dans le resume aussi.
+- les derniers commits et tout travail non committe en cours.
+
+Jette : les sorties d'outils deja exploitees, les dumps de fichiers verbeux, les sous-etapes resolues. Garde les decisions et les fils non resolus (recall d'abord, precision ensuite).

package/install/templates/.claude/hooks/inject-soul.js

@@ -2,9 +2,10 @@
 /**
  * SessionStart hook — loads BYAN soul + soul-memory and injects them into
  * the session's initial context via additionalContext. Tao is intentionally
- * NOT bundled here: inject-tao.js injects the full tao on every
- * UserPromptSubmit (including the first), so duplicating it at SessionStart
- * would double-spend ~15 KB per session for no gain.
+ * NOT bundled here: inject-tao.js is its own SessionStart hook that injects the
+ * full tao once into the cacheable prefix, and inject-voice-anchor.js carries a
+ * compact per-turn voice reminder. Keeping them separate avoids double-spending
+ * the tao payload while leaving each hook single-purpose and testable.
  *
  * Also resets the per-session mid-session-nudge one-shot marker so the
  * soul-memory-triggers nudge is per-session (not per-lifetime). Without