create-byan-agent 2.29.2 → 2.38.0

package/CHANGELOG.md

@@ -9,6 +9,367 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.38.0] - 2026-06-30
+
+### Added - yanstaller installs the byan-channel MCP entry by default (inert)
+
+`npx create-byan-agent` now registers a second MCP server, `byan-channel`,
+alongside `byan` in the project `.mcp.json`. It is a Claude Code RESEARCH PREVIEW
+channel (v2.1.80+) and ships INERT: registering it enables nothing on its own --
+it is only loaded when the user launches
+`claude --dangerously-load-development-channels server:byan-channel`. No
+`channelsEnabled`, no `allowedChannelPlugins`, no auto-activation flag is written.
+Codex is not covered by this feature.
+
+- **Port (read-only from byan_web)**: `channel-entry.js`, `lib/channel-server.js`,
+  `lib/channel-poll.js` brought into `_byan/mcp/byan-mcp-server/`. The entry
+  resolves its own config at boot via `resolve-config.js` (env ->
+  `~/.byan/credentials.json` -> defaults), so no secret is needed in `.mcp.json`.
+- **Wiring -- one shape, every writer**: the byan + byan-channel entry shape has a
+  single source of truth, `mcpConfig.mergeByanEntry`, with no `.mcp.json` template
+  to drift out of sync. Both writers route through it -- `generateMcpConfig` (the
+  primary native-setup path, a pure delegation) and `installDirectMCP` -- so they
+  are byte-coherent. Each writes a project-relative path (not absolute, not
+  `{{PROJECT_ROOT}}`), preserves an existing custom `command` and non-byan env,
+  strips `BYAN_API_URL`/`BYAN_API_TOKEN`, and merges into an existing `.mcp.json`
+  without clobbering other servers. Additional default MCP servers are registered
+  via `addMcpEntry` (mcp-extensions), not a template.
+- **Portable + secret-free**: relative paths survive a moved / npm-shipped repo;
+  the channel env is forced empty; no token shape can land in tracked `.mcp.json`.
+- **Shipped**: the 3 runtime files + 2 tests are in `TARGET_ADDITIONS` and
+  mirrored to `install/templates`, parity enforced by `byan-sync-template --check`.
+- **Honest post-install message**: states research-preview, version gate, inert
+  default, the activation flag, and that Codex is not covered.
+
+Files: `install/packages/platform-config/lib/mcp-config.js` (mergeByanEntry /
+mergeChannelEntry / mergeLeantimeRefs -- relative args, command preserved),
+`install/lib/claude-native-setup.js` (generateMcpConfig is a pure delegation to
+the shared merge), `install/lib/platforms/claude-code.js` (installDirectMCP),
+`install/bin/create-byan-agent-v2.js` (message),
+`_byan/mcp/byan-mcp-server/{channel-entry,lib/channel-server,lib/channel-poll}.js`,
+`_byan/mcp/byan-mcp-server/lib/template-sync.js`,
+`_byan/mcp/byan-mcp-server/test/{channel,channel-resolve}.test.js` (+ install
+templates). Adversarial review (bmad-compliance) caught 3 message/coherence gaps,
+all fixed before merge; a follow-up adversarial pass drove removal of the now-dead
+`.mcp.json.tmpl` so the byan/byan-channel shape has a single source of truth.
+jest root 2473/2473, MCP node --test 723/723.
+
+## [2.37.1] - 2026-06-30
+
+### Fixed - strict-stop-guard false positive on mentioned completion markers
+
+`claimsCompletion` matched a completion marker ANYWHERE in the assistant message,
+so a turn was blocked even when a marker was merely MENTIONED, not claimed:
+`complete` inside `byan_strict_complete`, `done` inside the `BYAN-BENCH:done`
+marker comment, or an accented marker embedded in another word (`fini` in
+`indefini`, `termine` in `determine`). Hit repeatedly in one session. Hardened: a
+working copy is denoised first (fenced + inline code, HTML comments, snake_case /
+namespaced identifiers stripped), then markers match only as a standalone claim
+with Unicode-aware boundaries and a permissive trailing inflection (`livre` ->
+`livree` / `livres`). Bias toward fewer false blocks -- the pre-commit gate stays
+the hard net for a real premature completion. Genuine claims (`done`,
+`c'est termine`, `feature livree`, `the build is complete`) still fire. +4
+regression tests.
+
+Files: `.claude/hooks/strict-stop-guard.js` (+ install template),
+`_byan/mcp/byan-mcp-server/test/strict-hooks.test.js`. MCP node --test 714/714,
+root jest 2466/2466.
+
+## [2.37.0] - 2026-06-30
+
+### Added - Prod-grade + maximal scope as the mechanical default (anti-downgrade)
+
+A 4-lens diagnosis workflow established WHY the agent kept drifting toward MVP /
+half-work despite the whole anti-downgrade arsenal: it was OPT-IN (every guard a
+no-op until a scope is locked), the strict loop was self-judged (agent writes the
+contract, grades its own verdict), and the cost model was anchored on human-2010
+time, generating the MVP-split reflex. This ships the mechanical, default-on fix.
+
+- **F1 -- delivery-contract anchor (LIVE).** New `inject-delivery-default.js`
+  (UserPromptSubmit) + pure lib `delivery-contract.js` re-inject a contract every
+  turn: grade=PROD, scope=MAXIMAL (proposing an MVP / short-deliverable /
+  dont-block-the-heavy split is forbidden unless the user types an opt-out word
+  THIS message), cost yardstick=AI-2026 (estimate in agent-time x10, not
+  human-by-hand). Opt-out wordlist in `_byan/_config/delivery-default.json`. The
+  opt-out parser is biased toward PROD: a single opt-out word counts only as a
+  short directive or with a go-cheap cue, is dropped when negated ("pas de mvp"),
+  and a mere mention in a long meta message leaves the anchor armed. Preserved
+  across compaction (CLAUDE.md) and mirrored to AGENTS.md (Codex).
+- **F2 -- non-agent completeness judge (built, DISARMED).** `completeness-evidence.js`
+  wired additively into strict `complete()` + the pre-commit gate: a "done" claim
+  is backed by a non-fabricable artifact (a real test-runner exit, a `git diff`
+  vs the locked paths, a file that exists), breaking the judge=defendant loop.
+  Ships behind `completenessGate.armed=false` (collect + ledger only) so it does
+  not change behavior or self-lock until the ledger validates arming.
+- **F3 -- punt-guard (built, DISARMED).** Stop hook + pure `punt-detect.js`
+  flags handing the user a runnable command the agent could run itself, with a
+  creds carve-out (git push / npm publish). Ships behind `puntGuard.armed=false`
+  (observe + ledger).
+
+Caught in build: F1's first live turn revealed a false positive (the anchor
+self-disabled on any message that merely mentioned an opt-out word). Fixed in
+place with the negation + directive-context hardening above + 3 regression tests.
+
+Files: `.claude/hooks/inject-delivery-default.js`, `.claude/hooks/lib/delivery-contract.js`,
+`.claude/hooks/punt-guard.js`, `.claude/hooks/lib/punt-detect.js`,
+`_byan/mcp/byan-mcp-server/lib/completeness-evidence.js`, wired into `strict-mode.js`
++ `precommit-gate.js`, `_byan/_config/delivery-default.json`, `.claude/settings.json`,
+CLAUDE.md + AGENTS.md (+ install templates) + tests. MCP node --test 710/710, root
+jest 2466/2466. Strict scope 9f8c6048.
+
+## [2.36.0] - 2026-06-29
+
+### Added - Leantime auto-sync: complexity, priority and description on task creation
+
+The FD->Leantime auto-sync (which already creates tasks and drives the
+todo/doing/review/done lifecycle) now enriches each created task with effort,
+priority and a traceable description -- no manual board work.
+
+- **F1 -- pure resolvers + enriched intent** (`leantime-fd-core.js`). Two
+  exported pure functions: `priorityToLeantime` (P1/P2/P3 -> 3/2/1, omitted when
+  unknown) and `complexityToStorypoints` (a finite `item.complexity` bucketed on
+  the Fibonacci scale <=15->2 / 16-39->5 / 40-69->8 / >=70->13, else derived from
+  priority P1->8 / P2->5 / P3->3, default 3 -- returns a numeric estimate).
+  `decideActions` now emits `{ priority?, storypoints, description }` in the
+  `task_create` intent (`description` = `BYAN FD <id> -- <headline>` +
+  ` [complexity:N]` when finite).
+- **F2 -- carrier + passthrough** (`leantime-sync.js` + the `leantime-fd-sync`
+  hook, source + install template). `createTask` accepts and sends `storypoints`;
+  the hook passes `description` / `priority` / `storypoints` through to it. The
+  lifecycle sync is untouched.
+
+Note: `storypoints` is the presumed Leantime effort field, `[UNVERIFIED]` against
+a live instance (Leantime unreachable at build time). An unknown key is at worst
+ignored by `addTicket` (no break), and the complexity is also carried in the
+description as a fallback. Flagged for a live-verify when reachable.
+
+Files: `_byan/mcp/byan-mcp-server/lib/leantime-fd-core.js`, `lib/leantime-sync.js`,
+`.claude/hooks/leantime-fd-sync.js` (+ install template), `test/leantime-fd-core.test.js`
++ `test/leantime-sync.test.js` (+7 tests). MCP node --test 696/696, root jest
+2441/2441. Strict scope 80405c59.
+
+## [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

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');
@@ -1295,6 +1296,21 @@ async function install(options = {}) {
     console.log(chalk.cyan('Claude Code native setup (hooks, skills, MCP server)'));
     try {
       await setupClaudeNative(projectRoot);
+      // Honest disclosure about the byan-channel entry now in .mcp.json. It is a
+      // Claude Code RESEARCH PREVIEW feature and ships INERT: registering it does
+      // not enable it. We tell the user exactly what it is, what it requires, how
+      // to turn it on, and that Codex is not covered — no overselling.
+      console.log(
+        chalk.gray(
+          '    - byan-channel = Claude Code RESEARCH PREVIEW channel (v2.1.80+), INERT by default.'
+        )
+      );
+      console.log(
+        chalk.gray(
+          '      To activate: claude --dangerously-load-development-channels server:byan-channel'
+        )
+      );
+      console.log(chalk.gray('      Codex is not covered by this feature.'));
     } catch (error) {
       console.log(chalk.red(`  ✘ Claude native setup failed: ${error.message}`));
       console.log(
@@ -1378,7 +1394,7 @@ 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,
         },
       ]);
@@ -1400,6 +1416,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/claude-native-setup.js

@@ -9,7 +9,8 @@
  *   - _byan/mcp/byan-mcp-server/** (no node_modules)
  *
  * Generates:
- *   - .mcp.json with the absolute path to the target project's MCP server
+ *   - .mcp.json with the RELATIVE path to the target project's MCP server
+ *     (byan + inert byan-channel entries, via the shared pure merge)
  *
  * Runs:
  *   - npm install inside the copied MCP server dir (with fallback warning)
@@ -22,6 +23,7 @@ const chalk = require('chalk');
 
 const TEMPLATE_ROOT = path.resolve(__dirname, '..', 'templates');
 const { whitelistMcpServer } = require('./settings-local');
+const { mcpConfig } = require('byan-platform-config');
 
 async function copyClaudeHooks(projectRoot) {
   const src = path.join(TEMPLATE_ROOT, '.claude', 'hooks');
@@ -78,30 +80,15 @@ async function copyMcpServer(projectRoot) {
 }
 
 async function generateMcpConfig(projectRoot, options = {}) {
-  const tmplPath = path.join(TEMPLATE_ROOT, '.mcp.json.tmpl');
   const dstPath = path.join(projectRoot, '.mcp.json');
 
-  let template;
-  if (await fs.pathExists(tmplPath)) {
-    template = await fs.readFile(tmplPath, 'utf8');
-  } else {
-    template = JSON.stringify(
-      {
-        mcpServers: {
-          byan: {
-            command: 'node',
-            args: ['{{PROJECT_ROOT}}/_byan/mcp/byan-mcp-server/server.js'],
-            env: { BYAN_API_URL: options.apiUrl || 'http://localhost:3737' },
-          },
-        },
-      },
-      null,
-      2
-    );
-  }
-
-  const rendered = template.replace(/\{\{PROJECT_ROOT\}\}/g, projectRoot);
-
+  // Read-merge-write through the single source of truth for the byan + inert
+  // byan-channel entry shape: mcpConfig.mergeByanEntry (relative args, secret-free,
+  // existing siblings + custom command + non-byan env preserved, channel added
+  // inert). This is byte-coherent with installDirectMCP, which routes through the
+  // same merge. Additional default MCP servers are registered via addMcpEntry
+  // (mcp-extensions), not here -- so there is no .mcp.json template to drift out
+  // of sync with the merge.
   let existing = {};
   if (await fs.pathExists(dstPath)) {
     try {
@@ -111,20 +98,7 @@ async function generateMcpConfig(projectRoot, options = {}) {
     }
   }
 
-  const merged = JSON.parse(rendered);
-  merged.mcpServers = { ...(existing.mcpServers || {}), ...merged.mcpServers };
-
-  // Security: BYAN_API_TOKEN is never written into .mcp.json (git-tracked); the
-  // token reaches the MCP server via .claude/settings.local.json env. Also honor
-  // the caller's apiUrl: the template URL is only a default.
-  const byanEntry = merged.mcpServers && merged.mcpServers.byan;
-  if (byanEntry && byanEntry.env) {
-    delete byanEntry.env.BYAN_API_TOKEN;
-    if (options.apiUrl) {
-      byanEntry.env.BYAN_API_URL = options.apiUrl;
-    }
-  }
-
+  const merged = mcpConfig.mergeByanEntry(existing, { apiUrl: options.apiUrl });
   await fs.writeJson(dstPath, merged, { spaces: 2 });
   return { path: dstPath };
 }
@@ -197,7 +171,7 @@ async function setupClaudeNative(projectRoot, options = {}) {
   );
 
   results.mcpConfig = await generateMcpConfig(projectRoot, options);
-  log(chalk.green(`  ✓ .mcp.json generated (absolute path)`));
+  log(chalk.green(`  byan + inert byan-channel entries in .mcp.json (relative paths)`));
 
   // Whitelist the byan MCP server: a project .mcp.json entry is inert in Claude
   // Code until its id is listed in .claude/settings.local.json.