create-byan-agent 2.29.1 → 2.35.0

package/CHANGELOG.md

@@ -9,6 +9,256 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.35.0] - 2026-06-26
+
+### Added - Portable core / native projection doctrine + degradation litmus
+
+BYAN's memory/identity is now governed by an explicit architecture doctrine: a
+portable in-repo core, with native Claude features as opportunistic write-through
+accelerators rather than dependencies.
+
+- **F1 -- doctrine.** New `.claude/rules/portable-core.md` (+ install template)
+  states the boundary: source of truth lives under `_byan/` (+ byan_web); native
+  features (prompt caching, `@-import` memory files, hooks, subagent isolation)
+  are write-through accelerators; the native AutoMem
+  (`~/.claude/projects/<hash>/memory/`) is explicitly out-of-perimeter
+  (per-machine, not shippable, not a BYAN source). Carries a feature -> adapter
+  -> degraded-path table. Mirrored to `AGENTS.md` (Codex) and pointed to from
+  `.claude/CLAUDE.md` WITHOUT an `@-import` (token budget).
+- **F2 -- degradation litmus.** New `.claude/__tests__/portable-core.test.js`
+  makes independence mechanical: identity (soul/tao/soul-memory) reconstructs from
+  portable `_byan/` artifacts alone, and no critical read path depends on the
+  native AutoMem (regression guard).
+
+Origin: a memory-integration audit found BYAN runs a parallel memory stack that
+does not touch the native AutoMem -- largely justified by npm portability, but
+undocumented and drift-prone. This codifies the boundary instead of syncing two
+stores (F3 anti-drift guard cut, YAGNI).
+
+Files: `.claude/rules/portable-core.md` (+ template), `AGENTS.md`,
+`.claude/CLAUDE.md` (+ template), `.claude/__tests__/portable-core.test.js`.
+root jest 2441/2441, MCP node --test 689/689. Strict mode: scope 591e6e49.
+
+## [2.34.0] - 2026-06-25
+
+### Changed - Context engineering: do more with less (compaction + subagent isolation)
+
+Two context-engineering moves from Anthropic's guidance, applied without touching
+BYAN's persistent identity.
+
+- **G2 -- compaction directive.** A `## Compact instructions` section in
+  `.claude/CLAUDE.md` tells the compaction what to preserve when a long session is
+  summarized: the active FD state (phase, backlog, verdicts -- `_byan-output/fd-state.json`),
+  the active Strict Mode session, BYAN's soul/tao voice, and recent commits. It
+  complements the `pre-compact-save` PreCompact hook (which writes a file snapshot):
+  one says what to keep in-context, the other persists a snapshot to disk.
+- **G3 -- subagent isolation doctrine in hermes.** The dispatcher's worktree path
+  already capped the subagent's return; the `mcp-worker` path did not, and the
+  isolation principle was unnamed. Both spawn paths now cap the return to a
+  distilled summary (< 200 words / ~1-2k tokens) -- verbose tool output and
+  intermediate reasoning stay in the subagent's own context. A new "Subagent
+  isolation (token leverage)" section + a hard rule codify it (Anthropic: a
+  subagent may burn ~9k tokens internally yet return ~1-2k).
+
+Files: `.claude/CLAUDE.md` (+ template), `.claude/skills/byan-hermes-dispatch/SKILL.md`
+(+ template), skill-bundles manifest + ZIP rebuilt, `.claude/__tests__/claude-md-context-budget.test.js`.
+root jest 2432/2432, MCP node --test 689/689. Source: Anthropic "Effective context engineering for AI agents".
+
+## [2.33.0] - 2026-06-25
+
+### Changed - Keep BYAN's voice alive on long sessions (tao persistence)
+
+Hardens the 2.32.0 tao cache-alignment so BYAN's voice does not fade on a long
+session, without re-introducing the per-turn cost.
+
+- **F1 -- heart-survival pinned.** A test (`.claude/__tests__/soul-hooks.test.js`)
+  now fails if `inject-tao.js` stops being wired under SessionStart with an
+  all-sources matcher (so it keeps re-firing on `source: "compact"`) or stops
+  emitting the full tao. Claude Code re-fires SessionStart after each compaction
+  (per its docs), re-injecting the full tao then; this test guards that floor
+  against a silent refactor.
+- **F2 -- periodic refresh.** `inject-voice-anchor.js` re-injects the FULL tao
+  every N turns (N via `BYAN_TAO_REFRESH_EVERY`, default 12); the other turns keep
+  the compact anchor. A per-turn counter under `_byan-output/` (gitignored), reset
+  at SessionStart by `inject-tao.js`, drives the cadence -- so the voice is
+  refreshed close to the live edge at least every N turns, between compactions.
+  Amortized cost stays well under the pre-2.32.0 per-turn tao.
+- **Honest floor.** The periodic refresh is best-effort: it needs a writable
+  counter, and each turn is a separate process. If `_byan-output/` is not writable
+  the hook degrades to the anchor (exit 0, no crash) and the SessionStart /
+  compaction re-injection remains the floor. A test pins that degradation.
+
+Built under BYAN Strict Mode; reviewed by bmad-compliance (one CHANGES round on the
+FS-degradation honesty, then approve). root jest 2430/2430, MCP node --test 689/689.
+
+## [2.32.0] - 2026-06-25
+
+### Changed - Token cost reduction for BYAN's persistent identity (cache + dedup)
+
+Cuts the per-turn token cost of BYAN's persistent identity payload without making
+any of it conditional: tao, mantras, skeptic, ELO and fact-check stay applied each
+turn. Two levers attack the transport/representation cost, not the presence.
+
+- **Cache-align tao injection.** The full tao was re-injected each turn via a
+  UserPromptSubmit hook (~14.9 KB per turn, re-billed at the growing edge of the
+  conversation). It now loads once at SessionStart (`inject-tao.js` -> SessionStart,
+  the cacheable prefix), and a new `inject-voice-anchor.js` injects a compact
+  ~95-token voice anchor each turn (register + signatures + tutoiement + zero-emoji
+  + IA-16). Per-turn tao transport drops 14898 -> 383 chars (97.4% lower); the full
+  tao stays present, moved to the session prefix.
+- **De-duplicate the persistent doctrine.** `strict-mode.md`, `benchmark.md` and
+  `fact-check.md` were `@`-imported by `CLAUDE.md`, force-loading the full files
+  into every turn (~5964 tokens). The `@`-imports become lean plain pointers. The
+  behavioral summary stays inline in `CLAUDE.md` and the enforcement lives in the
+  hooks (`strict-*-guard`, `autobench-stop-guard`, `fact-check-*`); the full rule
+  files stay reachable on demand via their skills. The benchmark pointer is
+  regenerated from the `sync-rules` renderer. `elo-trust` and `team-doctrine` keep
+  their `@`-import.
+
+A third idea (output-side filtering) was closed as already covered by RTK + Claude
+Code's native large-output truncation -- a documented redundancy, not a cut.
+
+Files: `.claude/hooks/inject-tao.js` (now SessionStart), `.claude/hooks/inject-voice-anchor.js`
+(new), `.claude/settings.json`, `.claude/CLAUDE.md`, `_byan/mcp/byan-mcp-server/lib/sync-rules.js`
+(renderer), `_byan/mcp/byan-mcp-server/lib/template-sync.js` (ships the new hook), `AGENTS.md`
+(regenerated), plus the template mirrors. Built under BYAN Strict Mode; reviewed by bmad-compliance
+(approve, identity line held); root jest 2420/2420, MCP node --test 689/689, zero emoji. Token
+figures are char/4 estimates; `/context` is the exact counter-test.
+
+## [2.31.0] - 2026-06-24
+
+### Added - Install-time service-account key setup for byan_publish
+
+BYAN is open-source, so no Google key ships in the npm package: each user
+provides their own service-account key, on their own machine. This release adds
+the install-time setup that wires that key for `byan_publish` (the headless
+Google Docs publisher from 2.30.0).
+
+- `install/lib/gdoc-setup.js` (new) : `setupGdocPublish` guides the user to the
+  Google Cloud console, imports the downloaded SA JSON into
+  `~/.byan/google-sa.json` (mode `0600`, dir `0700`), validates it
+  (`client_email` + `private_key`), then persists the path via `writeCredentials`
+  (`GOOGLE_APPLICATION_CREDENTIALS` + optional `GDOC_TEMPLATE_ID` /
+  `GDOC_LOGO_PNG_URL`). Every side-effecting dep (prompt / fs / writeCredentials)
+  is injected; the function stays graceful (a missing, invalid, or unreadable key
+  degrades to `configured:false` rather than throwing). Only the key path is
+  persisted -- the secret stays on disk in `~/.byan/`, out of the repo.
+- `install/setup-gdoc.js` (new) + `npm run setup-gdoc` : run the setup on demand,
+  outside the installer.
+- `install/bin/create-byan-agent-v2.js` : opt-in block (prompt default no, mirrors
+  the RTK block; gated by `shouldOfferGdoc` -- TTY only, skipped on
+  `BYAN_SKIP_GDOC=1`).
+- `@byan/platform-config` : `KNOWN_KEYS` extended with
+  `GOOGLE_APPLICATION_CREDENTIALS`, `GDOC_TEMPLATE_ID`, `GDOC_LOGO_PNG_URL` so
+  `writeCredentials` persists them (covered by test).
+- Guide : `docs/google-docs-publish.md` documents the open-source per-user key
+  model and the `npm run setup-gdoc` path (mirrored to `install/templates/docs/`).
+
+Built under BYAN Strict Mode (scope locked, self-verified) ; secrets and
+never-throws self-reviewed PASS (independent compliance pass to re-run before
+publish, transient API outage at review time). Root jest 2389/0.
+
+## [2.30.0] - 2026-06-24
+
+### Added - byan_publish : Google Docs brandés, headless (service account)
+
+New MCP tool `byan_publish` : a byan-owned, headless Google Docs publisher. A
+service-account JWT (durable, no OAuth, no browser, no 7-day refresh-token expiry)
+creates a branded Google Doc from a content object and returns its URL, optionally
+sharing it. Distinct from the gw OAuth connector.
+
+- `lib/gdoc-content.js` (pure) : content -> Docs `batchUpdate` requests. Template
+  mode (`replaceAllText` over a branded template) or programmatic mode (insert +
+  the AcadéNice palette : marine `#0e2656`, teal `#24947a`, turquoise `#4cccb8`).
+- `lib/gdoc-client.js` : service-account auth (google-auth-library JWT, scopes
+  `documents` + `drive.file`) + create-or-copy + `batchUpdate` +
+  `permissions.create`. googleapis is lazy-loaded so the server boots without it ;
+  every failure path returns `{ ok:false, reason }` (no-credentials /
+  bad-credentials / invalid-content / dep-missing / api-error) rather than
+  throwing. The SA key is read from a path (`GOOGLE_APPLICATION_CREDENTIALS`, via
+  resolve-config) and stays on disk -- not serialized into any output.
+- `byan_publish` registered in server.js, kept OUT of `REMOTE_SAFE_TOOLS`
+  (network+auth, stdio-only). New deps : `googleapis` + `google-auth-library`.
+- Guide : `docs/google-docs-publish.md` (SA key recipe + usage + branding/template
+  + the standalone-vs-Workspace ownership model).
+
+The single manual step is creating the SA key (Google Cloud IAM). RNCP/eval
+content plugs in later as a thin adapter. Built under BYAN Strict Mode (scope
+locked, self-verified) ; reviewed by bmad-compliance (security : secrets +
+no-throw PASS, narrow scopes, fact-check floor L1). MCP suite 687/687, root jest
+2378/0.
+
+## [2.29.4] - 2026-06-24
+
+### Changed - Google Workspace (gdrive) install: durable OAuth "Internal"
+
+The installer's Google Workspace setup guide now points to an OAuth consent
+screen in "Internal" mode instead of "External / Testing". "External + Testing"
+expires the refresh token in ~7 days for scopes beyond openid/email/profile (all
+of gw's Drive/Docs/... scopes qualify); "Internal" removes that expiry and skips
+Google app verification (source: developers.google.com/identity/protocols/oauth2).
+The result: ONE durable OAuth client is byan's single Google credential, and the
+claude.ai Drive connector becomes redundant.
+
+- `install/lib/mcp-extensions/gdrive.js`: `SETUP_LINKS` + `printSetupGuide` guide
+  to Internal, with the durability rationale, the org-Workspace prerequisite, and
+  the honest limit (one browser login at setup, org-only). A durability reminder
+  fires on the reuse path too.
+- The package `google-workspace-mcp` does not support service accounts (its
+  README), so "Internal" is the durable path that keeps its 95+ tools. A
+  service-account route (for fully headless publishing) would be a separate,
+  byan-owned Google client — out of scope here.
+- New guide: `docs/google-workspace-setup.md` (one-time Internal recipe + the
+  mutualization rationale).
+
+Reviewed by bmad-compliance (auth domain, fact-check floor L1). 2378 tests green.
+
+## [2.29.3] - 2026-06-24
+
+### Fixed - RTK hook now actually installed (--auto-patch)
+
+2.29.2 wired only the RTK instruction layer, not the transparent hook. `wireHook`
+ran `rtk init -g` with stdio piped (no TTY), but bare `rtk init -g` PROMPTS before
+patching `settings.json`, so the prompt was skipped and rtk wrote `RTK.md` + the
+`@RTK.md` reference WITHOUT the PreToolUse hook — `rtk init --show` reported
+"Hook: not found". `wireHook` now calls `rtk init -g --auto-patch`, which patches
+`settings.json` non-interactively, so the command-rewriting hook is installed. An
+older rtk lacking the flag degrades gracefully (reason `hook-failed`; the install
+still succeeds). `doctor()` and the installer consent prompt were updated to match.
+Verified live on a Debian/zsh host: `rtk init --show` reports "Hook: configured"
+after the fix.
+
+If you installed 2.29.x before this and RTK feels inactive, re-run
+`rtk init -g --auto-patch`.
+
+## [2.29.2] - 2026-06-23
+
+### Fixed - RTK optional install: fail-proof, off-PATH, shell-aware
+
+The 2.29.x RTK installer could hang silently and mis-report a successful build.
+
+- **Bounded + visible.** The delegated install now runs with a per-strategy
+  timeout (brew/script 5min, cargo 20min; override via `BYAN_RTK_TIMEOUT_MS`,
+  positive integers only) and inherited stdio, so progress streams live instead
+  of a frozen line. Inherited stdio also sidesteps execSync's 1MB maxBuffer cap a
+  verbose build would blow.
+- **Off-PATH resolution.** `cargo install` drops the binary in `~/.cargo/bin`,
+  which a Debian non-login PATH does not include — the install succeeded but
+  `rtk --version` reported "unverified". The installer now resolves rtk across
+  known dirs (PATH, `~/.cargo/bin`, `~/.local/bin`, `/usr/local/bin`, brew prefix,
+  `CARGO_HOME`), verifies + wires the hook by the resolved path, and prints a
+  shell-correct PATH hint (`fish_add_path` on fish, `export` on bash/zsh,
+  `$env:PATH` on Windows).
+- **Prebuilt preferred.** Strategy order is now brew > script > cargo: the
+  prebuilt-binary script (pinned to the immutable tag ref, which SHA-256-verifies
+  the binary per refs/tags/v0.42.4/install.sh) is fast and PATH-stable; cargo
+  (from-source, off-PATH, slow) becomes the last-resort fallback.
+- **Stays graceful.** Hardened the no-throw contract: a HOME-less environment
+  (`os.homedir()` throwing) no longer propagates out of `setup-rtk.js`.
+
+Reviewed by an adversarial workflow (correctness + supply-chain + mantras) plus a
+compliance pass; 2375/2375 tests green (49 dedicated to RTK).
+
 ## [2.29.1] - 2026-06-23
 
 ### Fixed - Republish (the 2.29.0 npm tarball was missing)

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

@@ -17,6 +17,7 @@ const { launchPhase2Chat, generateDefaultConfig } = require('../lib/phase2-chat'
 const { setupByanWebIntegration, validateByanWebReachability } = require('../lib/byan-web-integration');
 const { setupLeantimeIntegration, validateLeantimeReachability } = require('../lib/byan-leantime-integration');
 const { setupRtkIntegration, shouldOfferRtk } = require('../lib/rtk-integration');
+const { setupGdocPublish, shouldOfferGdoc } = require('../lib/gdoc-setup');
 const { setupClaudeNative } = require('../lib/claude-native-setup');
 const { setupCodexNative } = require('../lib/codex-native-setup');
 const { setupMcpExtensions } = require('../lib/mcp-extensions');
@@ -1378,16 +1379,19 @@ async function install(options = {}) {
         {
           type: 'confirm',
           name: 'proceed',
-          message: 'Install rtk now? Runs its official installer (brew/cargo, or a pinned curl|sh) and adds a GLOBAL Claude Code hook via `rtk init -g`.',
+          message: 'Install rtk now? Runs its official installer (brew/cargo, or a pinned curl|sh) and adds a GLOBAL Claude Code hook via `rtk init -g --auto-patch`.',
           default: false,
         },
       ]);
       if (proceed) {
+        console.log(chalk.gray('  Installing... progress streams below. The cargo fallback compiles from source (can take minutes); Ctrl+C is safe — BYAN is already installed.'));
         const r = setupRtkIntegration({ log: (m) => console.log(chalk.gray('  ' + m)) });
         if (r.synced) {
           console.log(chalk.green(`  ✓ rtk ready (${r.installedVia}, v${r.version || '?'}) — restart Claude Code to activate`));
+          if (r.pathHint) console.log(chalk.yellow(`  ⚠ rtk is not on your PATH — add it: ${r.pathHint}`));
         } else {
-          console.log(chalk.yellow(`  ⚠ rtk not wired (${r.reason}) — BYAN unaffected`));
+          console.log(chalk.yellow(`  ⚠ rtk not wired (${r.reason}) — BYAN unaffected; re-run \`npm run setup-rtk\` anytime`));
+          if (r.pathHint) console.log(chalk.yellow(`  ⚠ rtk found off-PATH — add it then re-run: ${r.pathHint}`));
         }
       } else {
         console.log(chalk.gray('  rtk skipped — run `npm run setup-rtk` anytime to enable.'));
@@ -1397,6 +1401,33 @@ async function install(options = {}) {
     }
   }
 
+  if (needsClaude && shouldOfferGdoc()) {
+    console.log();
+    console.log(chalk.cyan('byan_publish — clé service account Google Docs (optionnel, headless)'));
+    try {
+      const { proceed } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'proceed',
+          message: 'Configurer ta clé service account maintenant (chacun la sienne ; rien de secret ne ship) ?',
+          default: false,
+        },
+      ]);
+      if (proceed) {
+        const r = await setupGdocPublish({ log: (...a) => console.log(...a) });
+        if (r.configured) {
+          console.log(chalk.green(`  ✓ byan_publish prêt (clé : ${r.path})`));
+        } else {
+          console.log(chalk.yellow(`  ⚠ byan_publish non configuré (${r.skipReason}) — \`npm run setup-gdoc\` à tout moment`));
+        }
+      } else {
+        console.log(chalk.gray('  byan_publish ignoré — `npm run setup-gdoc` à tout moment pour activer.'));
+      }
+    } catch (error) {
+      console.log(chalk.yellow(`  ⚠ byan_publish setup skipped: ${error.message}`));
+    }
+  }
+
   if (needsClaude) {
     console.log();
     console.log(chalk.cyan('Leantime board sync (optional — self-hosted)'));

package/install/lib/gdoc-setup.js

@@ -0,0 +1,210 @@
+'use strict';
+
+/**
+ * gdoc-setup -- install-time setup of the byan_publish service-account key.
+ *
+ * BYAN is open source : NO key ships. Each user provides THEIR OWN Google service
+ * account at install time. This module walks the user through creating the SA +
+ * key in the Google Cloud console, imports the downloaded JSON to
+ * ~/.byan/google-sa.json (chmod 0600), and persists the publish config
+ * (GOOGLE_APPLICATION_CREDENTIALS + optional GDOC_TEMPLATE_ID / GDOC_LOGO_PNG_URL)
+ * into ~/.byan/credentials.json via byan-platform-config's writeCredentials. The
+ * byan MCP server then reads them through resolve-config.
+ *
+ * Mirrors the shape of rtk-integration.js : graceful (NEVER throws, ok stays
+ * true so a failed step never breaks the BYAN install), and every side-effecting
+ * dep (prompt / fs / writeCredentials) is injectable, so the whole flow is
+ * unit-tested without touching a real key, the network, or the user HOME.
+ */
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const { writeCredentials } = require('byan-platform-config');
+
+const SA_FILENAME = 'google-sa.json';
+
+const SETUP_LINKS = [
+  {
+    step: "Projet Google Cloud (idéalement rattaché à ton org Workspace)",
+    url: 'https://console.cloud.google.com/projectcreate',
+  },
+  {
+    step: 'Activer les APIs Google Docs + Google Drive',
+    url: 'https://console.cloud.google.com/apis/library',
+  },
+  {
+    step: 'Créer un service account',
+    url: 'https://console.cloud.google.com/iam-admin/serviceaccounts',
+  },
+  {
+    step: 'Sur le service account -> Keys -> Add key -> Create new key -> JSON -> télécharger',
+    url: 'https://console.cloud.google.com/iam-admin/serviceaccounts',
+  },
+];
+
+function saDestPath(homedir = os.homedir()) {
+  return path.join(homedir, '.byan', SA_FILENAME);
+}
+
+/**
+ * A plausible service-account key : an object carrying a client_email and a
+ * private_key. Shape-only -- we never validate the key cryptographically.
+ */
+function validateServiceAccount(parsed) {
+  return Boolean(
+    parsed &&
+      typeof parsed === 'object' &&
+      typeof parsed.client_email === 'string' &&
+      parsed.client_email.trim() &&
+      typeof parsed.private_key === 'string' &&
+      parsed.private_key.includes('PRIVATE KEY')
+  );
+}
+
+/**
+ * shouldOfferGdoc() -> offer the setup only when interactive and not opted out
+ * (BYAN_SKIP_GDOC=1). Never prompts in CI / non-TTY.
+ */
+function shouldOfferGdoc({ env = process.env, isTTY = !!(process.stdin && process.stdin.isTTY) } = {}) {
+  if (env && env.BYAN_SKIP_GDOC === '1') return false;
+  return Boolean(isTTY);
+}
+
+function printSetupGuide(log) {
+  log();
+  log(chalk.cyan('Clé service account pour byan_publish (Google Docs headless) :'));
+  log(chalk.gray('  Open source -> tu fournis TA clé ; rien de secret ne ship. ~2 min, une fois.'));
+  SETUP_LINKS.forEach((s, i) => {
+    log(chalk.gray(`  ${i + 1}. ${s.step}`));
+    log(chalk.gray(`     -> ${s.url}`));
+  });
+  log();
+}
+
+/**
+ * setupGdocPublish(deps) -> { ok, configured, ... }. Never throws ; ok stays
+ * true on every path. configured=true only when a valid key was imported and
+ * persisted.
+ *
+ * @param {object} [deps]
+ * @param {Function} [deps.prompt]            inquirer.prompt (injected in tests)
+ * @param {Function} [deps.log]               line sink
+ * @param {string}   [deps.homedir]
+ * @param {object}   [deps.fsImpl]            fs-extra-like (readJson/ensureDir/writeFile/chmod)
+ * @param {Function} [deps.persist]           writeCredentials (injected in tests)
+ * @param {boolean}  [deps.quiet]
+ */
+async function setupGdocPublish(deps = {}) {
+  const prompt = deps.prompt || inquirer.prompt;
+  const homedir = deps.homedir || os.homedir();
+  const fsImpl = deps.fsImpl || fs;
+  const persist = deps.persist || writeCredentials;
+  const log = deps.quiet ? () => {} : deps.log || ((...a) => console.log(...a));
+
+  try {
+    printSetupGuide(log);
+
+    const { hasKey } = await prompt([
+      {
+        type: 'confirm',
+        name: 'hasKey',
+        message: 'Tu as téléchargé le JSON de la clé service account ?',
+        default: false,
+      },
+    ]);
+    if (!hasKey) {
+      return {
+        ok: true,
+        configured: false,
+        skipReason: "Setup reporté -- relance `npm run setup-gdoc` une fois le JSON téléchargé.",
+      };
+    }
+
+    const { jsonPath } = await prompt([
+      {
+        type: 'input',
+        name: 'jsonPath',
+        message: 'Chemin local vers le JSON de la clé SA :',
+        validate: (v) => (v && v.trim().length > 0) || 'Chemin requis',
+      },
+    ]);
+
+    let parsed;
+    try {
+      parsed = await fsImpl.readJson(path.resolve(jsonPath.trim()));
+    } catch (e) {
+      return { ok: true, configured: false, skipReason: `JSON illisible : ${e.message}` };
+    }
+    if (!validateServiceAccount(parsed)) {
+      return {
+        ok: true,
+        configured: false,
+        skipReason:
+          'Ce fichier ne ressemble pas à une clé service account (client_email + private_key requis).',
+      };
+    }
+
+    // Store the key OUTSIDE any repo, in ~/.byan/, at 0600 (created restrictively).
+    const dir = path.join(homedir, '.byan');
+    const dest = saDestPath(homedir);
+    await fsImpl.ensureDir(dir);
+    try {
+      await fsImpl.chmod(dir, 0o700);
+    } catch {
+      // POSIX modes unsupported -> proceed without the dir tightening.
+    }
+    await fsImpl.writeFile(dest, JSON.stringify(parsed, null, 2) + '\n', { mode: 0o600 });
+    try {
+      await fsImpl.chmod(dest, 0o600);
+    } catch {
+      // see above
+    }
+
+    const { templateId } = await prompt([
+      {
+        type: 'input',
+        name: 'templateId',
+        message: 'ID d\'un Google Doc template brandé (optionnel, Entrée pour passer) :',
+        default: '',
+      },
+    ]);
+    const { logoUrl } = await prompt([
+      {
+        type: 'input',
+        name: 'logoUrl',
+        message: 'URL PNG du logo (optionnel, Entrée pour passer) :',
+        default: '',
+      },
+    ]);
+
+    const values = { GOOGLE_APPLICATION_CREDENTIALS: dest };
+    if (templateId && templateId.trim()) values.GDOC_TEMPLATE_ID = templateId.trim();
+    if (logoUrl && logoUrl.trim()) values.GDOC_LOGO_PNG_URL = logoUrl.trim();
+
+    const res = await persist(values, { homedir });
+    log(chalk.green(`  clé SA -> ${dest} (0600)`));
+    log(chalk.gray(`  persisté dans ~/.byan/credentials.json : ${(res.written || []).join(', ')}`));
+    return {
+      ok: true,
+      configured: true,
+      path: dest,
+      persisted: res.written || [],
+      clientEmail: parsed.client_email,
+    };
+  } catch (err) {
+    return { ok: true, configured: false, skipReason: `setup gdoc échoué : ${err.message}` };
+  }
+}
+
+module.exports = {
+  setupGdocPublish,
+  shouldOfferGdoc,
+  validateServiceAccount,
+  printSetupGuide,
+  saDestPath,
+  SETUP_LINKS,
+  SA_FILENAME,
+};

package/install/lib/mcp-extensions/gdrive.js

@@ -16,6 +16,17 @@
  *
  * No credential ever touches the project tree. The .mcp.json entry only
  * declares command/args — every secret stays in ~/.google-mcp/.
+ *
+ * DURABLE + MUTUALIZED AUTH (the design choice): we guide the user to an OAuth
+ * consent screen in "Internal" mode (Workspace-org only). "External + Testing"
+ * expires the refresh token in ~7 days for scopes beyond openid/email/profile
+ * (all of gw's Drive/Docs/... scopes qualify) ; "Internal" does not, and skips
+ * Google app verification (source: developers.google.com/identity/protocols/oauth2).
+ * This OAuth client is THE single Google credential of byan — the claude.ai Drive
+ * connector becomes redundant. NOTE: this package (pm990320/google-workspace-mcp)
+ * does NOT support service accounts (README: "Service account authentication is
+ * not currently supported"), so a service-account JSON is not an option here ;
+ * "Internal" is the durable path that keeps the package's 95+ tools.
  */
 
 'use strict';
@@ -33,7 +44,7 @@ const CREDENTIALS_PATH = path.join(CONFIG_DIR, 'credentials.json');
 
 const SETUP_LINKS = [
   {
-    step: 'Créer un projet Google Cloud',
+    step: 'Créer un projet Google Cloud RATTACHÉ à ton organisation Workspace (ex : acadenice.fr) — pas un compte Gmail perso',
     url: 'https://console.cloud.google.com/projectcreate',
   },
   {
@@ -41,7 +52,7 @@ const SETUP_LINKS = [
     url: 'https://console.cloud.google.com/apis/library',
   },
   {
-    step: 'Configurer l\'écran de consentement OAuth (External, mode Test)',
+    step: 'Écran de consentement OAuth : User type = "Internal" (durable : pas d\'expiration 7 j, pas de vérification Google)',
     url: 'https://console.cloud.google.com/apis/credentials/consent',
   },
   {
@@ -93,6 +104,16 @@ function printSetupGuide(log) {
   log(chalk.gray(`  6. Renommer ce fichier en : credentials.json`));
   log(chalk.gray(`  7. Le placer dans : ${CREDENTIALS_PATH}`));
   log();
+  // The single thing that makes the credential durable. "External + Testing"
+  // expires the refresh token in ~7 days for scopes beyond openid/email/profile
+  // (all gw scopes qualify) ; "Internal" does not, and skips Google app
+  // verification. Source: developers.google.com/identity/protocols/oauth2.
+  log(chalk.yellow('  Durabilité — LE point qui compte :'));
+  log(chalk.yellow('    Écran de consentement en "Internal" → credential pérenne (token qui ne meurt pas).'));
+  log(chalk.yellow('    "External + Testing" → refresh token expiré sous ~7 jours (scopes hors openid/email/profile, donc tous ceux de gw). À éviter.'));
+  log(chalk.gray('    Limite "Internal" : seuls les comptes de ton org Workspace peuvent autoriser, et il faut UN login navigateur au premier setup.'));
+  log(chalk.gray('    Ce client OAuth devient LE credential Google unique de byan (le connecteur claude.ai Drive devient redondant).'));
+  log();
 }
 
 async function importCredentialsFromPath(srcPath, log) {
@@ -174,6 +195,8 @@ async function setup({ quiet } = {}) {
       },
     ]);
     if (reuse) {
+      log(chalk.gray('  Rappel durabilité : si ce client OAuth est en "External + Testing", son token meurt sous ~7 j (scopes Workspace gw concernés).'));
+      log(chalk.gray('  Pour un credential pérenne, l\'écran de consentement doit être en "Internal" (org Workspace).'));
       return { configured: true, message: 'reused existing credentials' };
     }
   } else {
@@ -250,7 +273,9 @@ module.exports = {
   buildMcpEntry,
   // exposed for tests
   buildEntry,
+  printSetupGuide,
   CONFIG_DIR,
   CREDENTIALS_PATH,
   PACKAGE_NAME,
+  SETUP_LINKS,
 };