create-byan-agent 2.29.2 → 2.38.0

package/install/templates/_byan/mcp/byan-mcp-server/lib/gdoc-content.js

@@ -0,0 +1,203 @@
+// gdoc-content -- PURE content -> Google Docs API request builders.
+//
+// No network, no googleapis, no I/O : this module turns a plain content object
+// into the deterministic arrays of Docs `batchUpdate` requests that gdoc-client
+// sends. Kept pure so the whole shaping logic is unit-tested without a service
+// account or a network (see test/gdoc-content.test.js).
+//
+// Two modes, mirroring gdoc-client's two paths :
+//   - TEMPLATE mode  : buildReplaceRequests() -> replaceAllText over a branded
+//     template Doc (logo + palette live IN the template ; we only fill text).
+//   - NO-TEMPLATE     : buildDocumentRequests() -> insert a structured text doc
+//     and colour the title + headings from the AcadeNice palette. A logo is
+//     inserted at the top when a PNG URL is provided (opts.logoPngUrl /
+//     GDOC_LOGO_PNG_URL) ; Docs accepts a raster URL (PNG/JPG/GIF), not SVG, so
+//     the URL must point at a PNG. Absent -> the doc is text branded by colour
+//     only (graceful, no image request).
+
+// AcadeNice palette (from the brand charter). Hex here ; converted to the Docs
+// API rgbColor (0..1 floats) by hexToRgbColor.
+const BRANDING = {
+  marine: '#0e2656',
+  teal: '#24947a',
+  turquoise: '#4cccb8',
+};
+
+/**
+ * hexToRgbColor('#0e2656') -> { red, green, blue } each in [0,1], the shape the
+ * Docs API expects under textStyle.foregroundColor.color.rgbColor. Accepts an
+ * optional leading '#' and 3- or 6-digit hex. Throws on malformed input (a bad
+ * palette constant is a programming error, surfaced loudly in tests).
+ * @param {string} hex
+ */
+function hexToRgbColor(hex) {
+  if (typeof hex !== 'string') throw new TypeError('hex must be a string');
+  let h = hex.trim().replace(/^#/, '');
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  if (!/^[0-9a-fA-F]{6}$/.test(h)) throw new Error(`invalid hex colour: ${hex}`);
+  const n = parseInt(h, 16);
+  return {
+    red: ((n >> 16) & 255) / 255,
+    green: ((n >> 8) & 255) / 255,
+    blue: (n & 255) / 255,
+  };
+}
+
+/**
+ * Normalize + validate the content object. Returns { title, sections, resources,
+ * fields }. Throws a clear error when the minimum (a non-empty title) is missing
+ * -- the caller turns that into a tool error, never a crash.
+ * @param {object} content
+ */
+function normalizeContent(content) {
+  const c = content || {};
+  const title = typeof c.title === 'string' ? c.title.trim() : '';
+  if (!title) throw new Error('content.title is required (non-empty string)');
+  const sections = Array.isArray(c.sections)
+    ? c.sections
+        .map((s) => ({
+          heading: typeof s?.heading === 'string' ? s.heading.trim() : '',
+          body: typeof s?.body === 'string' ? s.body : '',
+        }))
+        .filter((s) => s.heading || s.body)
+    : [];
+  const resources = Array.isArray(c.resources)
+    ? c.resources
+        .map((r) => ({
+          label: typeof r?.label === 'string' ? r.label.trim() : '',
+          url: typeof r?.url === 'string' ? r.url.trim() : '',
+        }))
+        .filter((r) => r.label || r.url)
+    : [];
+  const fields = c.fields && typeof c.fields === 'object' ? c.fields : {};
+  return { title, sections, resources, fields };
+}
+
+/**
+ * TEMPLATE mode. Map the content onto {{PLACEHOLDER}} tokens and emit one
+ * replaceAllText request per token. The template Doc carries the branding ; we
+ * only substitute text. `fields` lets a caller fill arbitrary {{KEY}} tokens
+ * (e.g. {{CANDIDAT}}). Deterministic order (stable for tests).
+ * @param {object} content
+ */
+function buildReplaceRequests(content) {
+  const { title, sections, resources, fields } = normalizeContent(content);
+  const map = {
+    TITLE: title,
+    BLOCS: sections.map((s) => `${s.heading}\n${s.body}`.trim()).join('\n\n'),
+    RESSOURCES: resources.map((r) => (r.url ? `${r.label} : ${r.url}` : r.label)).join('\n'),
+  };
+  for (const [k, v] of Object.entries(fields)) {
+    if (v != null) map[String(k).toUpperCase()] = String(v);
+  }
+  return Object.entries(map).map(([key, value]) => ({
+    replaceAllText: {
+      containsText: { text: `{{${key}}}`, matchCase: true },
+      replaceText: value,
+    },
+  }));
+}
+
+/**
+ * Assemble the flat document text + the index ranges to colour, for NO-TEMPLATE
+ * mode. Docs is 1-indexed (index 1 = first insertable position), so every range
+ * is offset by +1 against the assembled string. Returns { text, titleRange,
+ * headingRanges } with ranges as { startIndex, endIndex } in Docs coordinates.
+ * @param {object} content
+ */
+function assembleDocument(content) {
+  const { title, sections, resources } = normalizeContent(content);
+  const headingRanges = [];
+  let text = '';
+  const DOC_START = 1; // Docs body first insertable index
+
+  const titleStart = DOC_START + text.length;
+  text += `${title}\n\n`;
+  const titleRange = { startIndex: titleStart, endIndex: titleStart + title.length };
+
+  for (const s of sections) {
+    if (s.heading) {
+      const hs = DOC_START + text.length;
+      text += `${s.heading}\n`;
+      headingRanges.push({ startIndex: hs, endIndex: hs + s.heading.length });
+    }
+    if (s.body) text += `${s.body}\n`;
+    text += '\n';
+  }
+
+  if (resources.length) {
+    const rh = 'Ressources';
+    const rhs = DOC_START + text.length;
+    text += `${rh}\n`;
+    headingRanges.push({ startIndex: rhs, endIndex: rhs + rh.length });
+    for (const r of resources) {
+      text += `${r.url ? `${r.label} : ${r.url}` : r.label}\n`;
+    }
+  }
+
+  return { text, titleRange, headingRanges };
+}
+
+/**
+ * NO-TEMPLATE mode. Insert the assembled text at index 1, then colour the title
+ * (marine, bold, larger) and each heading (teal, bold) from the palette. Indices
+ * are valid because the single insertText happens first and every style range is
+ * computed against that one block. Returns the batchUpdate requests array.
+ * @param {object} content
+ * @param {object} [opts]
+ * @param {object} [opts.branding=BRANDING]
+ * @param {string} [opts.logoPngUrl]  PNG URL inserted at the top ; absent -> skipped
+ */
+function buildDocumentRequests(content, opts = {}) {
+  const branding = opts.branding || BRANDING;
+  const { text, titleRange, headingRanges } = assembleDocument(content);
+
+  const requests = [{ insertText: { location: { index: 1 }, text } }];
+
+  requests.push({
+    updateTextStyle: {
+      range: titleRange,
+      textStyle: {
+        bold: true,
+        fontSize: { magnitude: 20, unit: 'PT' },
+        foregroundColor: { color: { rgbColor: hexToRgbColor(branding.marine) } },
+      },
+      fields: 'bold,fontSize,foregroundColor',
+    },
+  });
+
+  for (const range of headingRanges) {
+    requests.push({
+      updateTextStyle: {
+        range,
+        textStyle: {
+          bold: true,
+          fontSize: { magnitude: 14, unit: 'PT' },
+          foregroundColor: { color: { rgbColor: hexToRgbColor(branding.teal) } },
+        },
+        fields: 'bold,fontSize,foregroundColor',
+      },
+    });
+  }
+
+  // Logo last : inserted at index 1 AFTER text+styles, so it lands at the very
+  // top and the already-styled text simply shifts down (styles stay bound to the
+  // characters). Skipped when no PNG URL is configured (graceful). Docs needs a
+  // raster URL (PNG/JPG/GIF) -- a non-PNG/SVG URL is rejected by the API and
+  // surfaces as gdoc-client's api-error, not a crash here.
+  const logoPngUrl = typeof opts.logoPngUrl === 'string' ? opts.logoPngUrl.trim() : '';
+  if (logoPngUrl) {
+    requests.push({ insertInlineImage: { location: { index: 1 }, uri: logoPngUrl } });
+  }
+
+  return requests;
+}
+
+export {
+  BRANDING,
+  hexToRgbColor,
+  normalizeContent,
+  buildReplaceRequests,
+  assembleDocument,
+  buildDocumentRequests,
+};

package/install/templates/_byan/mcp/byan-mcp-server/lib/leantime-fd-core.js

@@ -70,6 +70,47 @@ const PHASE_RANK = {
   ABORTED: 9,
 };
 
+// Map an FD backlog item's priority (P1/P2/P3) to a Leantime priority int.
+// Leantime priority is high=3 .. low=1; an unknown priority yields undefined so
+// the caller can OMIT the key (an absent priority must not be forced to a value).
+export function priorityToLeantime(priority) {
+  switch (priority) {
+    case 'P1':
+      return 3;
+    case 'P2':
+      return 2;
+    case 'P3':
+      return 1;
+    default:
+      return undefined;
+  }
+}
+
+// Map an FD backlog item to a Leantime story-points effort estimate. Prefers a
+// finite numeric `complexity` (0-100 scale, bucketed onto the Fibonacci scale
+// Leantime uses for estimates), and falls back to the coarse priority signal
+// when complexity is absent. ALWAYS returns a number so the caller can post a
+// non-null estimate on every created task.
+export function complexityToStorypoints(item) {
+  if (item && Number.isFinite(item.complexity)) {
+    const c = item.complexity;
+    if (c <= 15) return 2;
+    if (c <= 39) return 5;
+    if (c <= 69) return 8;
+    return 13;
+  }
+  switch (item && item.priority) {
+    case 'P1':
+      return 8;
+    case 'P2':
+      return 5;
+    case 'P3':
+      return 3;
+    default:
+      return 3;
+  }
+}
+
 function lastReviewStatus(state) {
   const arr = Array.isArray(state.review_findings) ? state.review_findings : [];
   for (let i = arr.length - 1; i >= 0; i -= 1) {
@@ -126,7 +167,7 @@ export function columnForState(state) {
 // Intent ops (the shell maps each to a leantime-sync call):
 //   { op:'project_ensure', name, slug, details }
 //   { op:'assign_user' }                              // only if configured (shell sequences it after project_ensure)
-//   { op:'task_create', backlogId, headline }
+//   { op:'task_create', backlogId, headline, storypoints, description, priority? }
 //   { op:'task_move', backlogId, column }
 export function decideActions({ toolName, state, sidecar = {}, assignUserConfigured = false } = {}) {
   const kind = fdToolKind(toolName);
@@ -161,7 +202,24 @@ export function decideActions({ toolName, state, sidecar = {}, assignUserConfigu
       if (!item || !item.id) continue;
       if (item.status === 'skipped') continue;
       if (!tasks[item.id]) {
-        intents.push({ op: 'task_create', backlogId: item.id, headline: item.title || item.id });
+        const headline = item.title || item.id;
+        // Enrich the create with effort + priority + a traceable description so
+        // the board item carries the BYAN signal, not just a bare title.
+        const priority = priorityToLeantime(item.priority);
+        const hasComplexity = Number.isFinite(item.complexity);
+        const description =
+          `BYAN FD ${state.fd_id || ''} -- ${headline}`.trim() +
+          (hasComplexity ? ` [complexity:${item.complexity}]` : '');
+        const intent = {
+          op: 'task_create',
+          backlogId: item.id,
+          headline,
+          storypoints: complexityToStorypoints(item),
+          description,
+        };
+        // priority is OMITTED when unknown (do not force an absent priority).
+        if (priority !== undefined) intent.priority = priority;
+        intents.push(intent);
       }
     }
   }

package/install/templates/_byan/mcp/byan-mcp-server/lib/leantime-sync.js

@@ -216,7 +216,7 @@ export async function ensureProject({ name, slug, clientId, details } = {}, opts
 // `id` so the caller can store it back into fd-state (idempotency lives in the
 // caller: create-only-if the backlog item has no leantime_task_id yet).
 export async function createTask(
-  { projectId, headline, description, status, priority, editorId, tags, type = 'task' } = {},
+  { projectId, headline, description, status, priority, storypoints, editorId, tags, type = 'task' } = {},
   opts = {},
 ) {
   if (!projectId) return { ok: false, synced: false, reason: 'no_project_id' };
@@ -226,6 +226,9 @@ export async function createTask(
   if (description != null) values.description = description;
   if (status != null) values.status = status;
   if (priority != null) values.priority = priority;
+  // storypoints is the presumed Leantime effort field (UNVERIFIED against a live
+  // instance); an unknown key is at worst ignored by addTicket, so this is safe.
+  if (storypoints != null) values.storypoints = storypoints;
   // Default the assignee to the configured human (LEANTIME_ASSIGN_USER_ID) so an
   // auto-created task shows on a person's board, not only the API service user.
   const resolvedEditor = editorId != null ? editorId : assignUserId();

package/install/templates/_byan/mcp/byan-mcp-server/lib/precommit-gate.js

@@ -1,6 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { getStatus, MIN_PASSES } from './strict-mode.js';
 import { fetchSession, syncEnabled } from './strict-sync.js';
 
+// F2 (additive): the completeness-evidence gate at commit time. Reads the
+// completeness ledger written by strict complete(). It only ever BLOCKS when
+// delivery-default.json completenessGate.armed === true (default false). With
+// the gate disarmed this is a no-op and the gate decision is exactly as before.
+const DELIVERY_CONFIG_REL = path.join('_byan', '_config', 'delivery-default.json');
+const COMPLETENESS_LEDGER_REL = path.join('_byan-output', 'completeness-ledger.jsonl');
+
+function completenessGateArmed(projectRoot) {
+  try {
+    const p = path.join(projectRoot || process.cwd(), DELIVERY_CONFIG_REL);
+    if (!fs.existsSync(p)) return false;
+    const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return !!(cfg && cfg.completenessGate && cfg.completenessGate.armed === true);
+  } catch {
+    return false; // A broken/absent config never arms the gate.
+  }
+}
+
+// Last completeness-ledger entry for the given scope_hash, or null. Best-effort.
+function lastCompletenessEntry(projectRoot, scopeHash) {
+  try {
+    const p = path.join(projectRoot || process.cwd(), COMPLETENESS_LEDGER_REL);
+    if (!fs.existsSync(p)) return null;
+    const lines = fs
+      .readFileSync(p, 'utf8')
+      .split('\n')
+      .filter((l) => l.trim());
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const e = JSON.parse(lines[i]);
+        if (!scopeHash || e.scope_hash === scopeHash) return e;
+      } catch {
+        // skip a malformed line
+      }
+    }
+  } catch {
+    // unreadable ledger -> treat as no evidence record
+  }
+  return null;
+}
+
+// Pure overlay: given a base decision (PASS), apply the armed completeness gate.
+// Returns the base decision untouched when disarmed or when the base already
+// blocks; otherwise blocks when the completeness ledger shows missing criteria.
+export function applyCompletenessGate(base, { armed, entry }) {
+  if (!base.pass || !armed) return base;
+  if (entry && Array.isArray(entry.missing) && entry.missing.length) {
+    return {
+      pass: false,
+      reason:
+        `Completeness gate ARMED: the completed strict session left ` +
+        `${entry.missing.length} code-shaped criteria without evidence ` +
+        `(${entry.missing.join('; ')}). Provide the artifacts before committing.`,
+    };
+  }
+  return base;
+}
+
 // BYAN Strict Mode pre-commit gate.
 //
 // The final, platform-agnostic net. Claude Code has in-session hooks; Codex
@@ -104,6 +164,7 @@ export async function evaluateGate({ projectRoot, fetchImpl } = {}) {
   const local = getStatus({ projectRoot });
   const normalizedLocal = normalizeLocal(local);
 
+  let base;
   // Consult the authority when there is a session to check and a token is set.
   if (normalizedLocal.sessionId && syncEnabled()) {
     const remote = await fetchSession(
@@ -111,10 +172,15 @@ export async function evaluateGate({ projectRoot, fetchImpl } = {}) {
       fetchImpl ? { fetchImpl } : {}
     );
     if (remote.ok && remote.data) {
-      return decide(normalizeApi(remote.data));
+      base = decide(normalizeApi(remote.data));
     }
     // API unreachable / not found -> fall back to local mirror.
   }
+  if (!base) base = decide(normalizedLocal);
 
-  return decide(normalizedLocal);
+  // F2 overlay: disarmed by default -> returns `base` unchanged.
+  const armed = completenessGateArmed(projectRoot);
+  if (!armed) return base;
+  const entry = lastCompletenessEntry(projectRoot, local.scope_hash);
+  return applyCompletenessGate(base, { armed, entry });
 }

package/install/templates/_byan/mcp/byan-mcp-server/lib/resolve-config.js

@@ -26,8 +26,18 @@ import nodePath from 'node:path';
 const DEFAULT_API_URL = 'http://localhost:3737';
 
 // Keys the resolver understands. BYAN_API_URL is the only one with a non-empty
-// default; tokens and the optional Leantime URL stay empty when unset.
-const KEYS = ['BYAN_API_URL', 'BYAN_API_TOKEN', 'LEANTIME_API_URL', 'LEANTIME_API_TOKEN'];
+// default; tokens, the optional Leantime URL, and the optional Google Docs
+// publish config (service-account key path, template id, logo URL) stay empty
+// when unset.
+const KEYS = [
+  'BYAN_API_URL',
+  'BYAN_API_TOKEN',
+  'LEANTIME_API_URL',
+  'LEANTIME_API_TOKEN',
+  'GOOGLE_APPLICATION_CREDENTIALS',
+  'GDOC_TEMPLATE_ID',
+  'GDOC_LOGO_PNG_URL',
+];
 
 /**
  * An unexpanded `${...}` placeholder is NOT a real value. It is what a launcher
@@ -98,6 +108,9 @@ function resolveConfig(opts = {}) {
   out.BYAN_API_TOKEN = out.BYAN_API_TOKEN || '';
   out.LEANTIME_API_URL = out.LEANTIME_API_URL || '';
   out.LEANTIME_API_TOKEN = out.LEANTIME_API_TOKEN || '';
+  out.GOOGLE_APPLICATION_CREDENTIALS = out.GOOGLE_APPLICATION_CREDENTIALS || '';
+  out.GDOC_TEMPLATE_ID = out.GDOC_TEMPLATE_ID || '';
+  out.GDOC_LOGO_PNG_URL = out.GDOC_LOGO_PNG_URL || '';
   return out;
 }
 

package/install/templates/_byan/mcp/byan-mcp-server/lib/strict-mode.js

@@ -1,12 +1,50 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { buildEvidence } from './completeness-evidence.js';
 
 const STRICT_DIR = '.byan-strict';
 const STATE_FILE = 'state.json';
 const AUDIT_FILE = 'audit.log';
 const MIN_SELF_VERIFY_PASSES = 3;
 
+// F2 completeness-evidence gate. complete() ATTACHES an evidence report and, when
+// the gate is ARMED (delivery-default.json completenessGate.armed === true),
+// hard-rejects a completion that leaves code-shaped criteria without evidence.
+// Default DISARMED: complete() behaves exactly as before (passCount >= 3 + last
+// verdict ok), the report is pure observation, and every completion appends one
+// line to the completeness ledger so arming later is data-informed.
+const DELIVERY_CONFIG_REL = path.join('_byan', '_config', 'delivery-default.json');
+const COMPLETENESS_LEDGER_REL = path.join('_byan-output', 'completeness-ledger.jsonl');
+
+function readDeliveryConfig(projectRoot) {
+  try {
+    const p = path.join(resolveRoot(projectRoot), DELIVERY_CONFIG_REL);
+    if (fs.existsSync(p)) {
+      const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+      if (cfg && typeof cfg === 'object') return cfg;
+    }
+  } catch {
+    // A broken config must NOT arm the gate — fail safe toward disarmed.
+  }
+  return {};
+}
+
+function completenessGateArmed(config) {
+  const g = config && config.completenessGate;
+  return !!(g && g.armed === true);
+}
+
+function appendCompletenessLedger(entry, projectRoot) {
+  try {
+    const p = path.join(resolveRoot(projectRoot), COMPLETENESS_LEDGER_REL);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+  } catch {
+    // The observation ledger is best-effort — never break completion.
+  }
+}
+
 function resolveRoot(projectRoot) {
   return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
@@ -234,7 +272,7 @@ export function selfVerify({
   };
 }
 
-export function complete({ projectRoot, now = new Date() } = {}) {
+export function complete({ projectRoot, now = new Date(), context = {}, evidenceIo } = {}) {
   const state = readState(projectRoot);
   if (!state || !state.active) {
     throw new Error('No active strict session.');
@@ -258,6 +296,42 @@ export function complete({ projectRoot, now = new Date() } = {}) {
     );
   }
 
+  // F2 (additive): collect the completeness-evidence report over the locked
+  // criteria + allowed paths. Always observed + ledgered; only ENFORCED when the
+  // gate is armed in delivery-default.json (default false -> behaviour unchanged).
+  const deliveryConfig = readDeliveryConfig(projectRoot);
+  const gateArmed = completenessGateArmed(deliveryConfig);
+  const evidence = buildEvidence({
+    criteria: state.scope_lock.acceptance_criteria || [],
+    allowedPaths: state.scope_lock.allowed_paths || [],
+    context,
+    projectRoot: resolveRoot(projectRoot),
+    io: evidenceIo,
+  });
+  appendCompletenessLedger(
+    {
+      ts: now.toISOString(),
+      event: gateArmed ? (evidence.missing.length ? 'would-reject' : 'pass') : 'observed-disarmed',
+      strict_session_id: state.strict_session_id,
+      scope_hash: state.scope_lock.scope_hash,
+      armed: gateArmed,
+      missing: evidence.missing,
+      per_criterion: evidence.perCriterion.map((c) => ({
+        criterion: c.criterion,
+        kind: c.kind,
+        hasEvidence: c.hasEvidence,
+      })),
+    },
+    projectRoot
+  );
+  if (gateArmed && evidence.missing.length) {
+    throw new Error(
+      `Cannot complete: completeness gate is ARMED and ${evidence.missing.length} ` +
+        `code-shaped criteria have no evidence (file / green test / diff): ` +
+        `${evidence.missing.join('; ')}. Provide the missing artifacts or re-lock the scope.`
+    );
+  }
+
   const auditEntries = readAuditLog(projectRoot);
   const auditPayload = JSON.stringify({
     scope_hash: state.scope_lock.scope_hash,
@@ -296,6 +370,9 @@ export function complete({ projectRoot, now = new Date() } = {}) {
     // Surfaced for the C3 learning-loop feed: an explicit ELO domain on the
     // locked scope means a completed session is a VALIDATED outcome.
     domain: state.scope_lock.domain || '',
+    // F2 (additive): the completeness-evidence report. Attached whether or not
+    // the gate is armed; with the gate disarmed it is pure observation.
+    evidence,
   };
 }
 

package/install/templates/_byan/mcp/byan-mcp-server/lib/sync-rules.js

@@ -271,7 +271,7 @@ 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`;
 }
 
 // ---------------------------------------------------------------------------

package/install/templates/_byan/mcp/byan-mcp-server/package.json

@@ -14,6 +14,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "google-auth-library": "^9.15.1",
+    "googleapis": "^148.0.0",
     "js-yaml": "^4.1.1"
   },
   "engines": {

package/install/templates/_byan/mcp/byan-mcp-server/server.js

@@ -14,6 +14,7 @@ import { harvest as harvestInsights, renderDigest as renderInsightDigest } from
 import { appendOutcome } from './lib/outcome-buffer.js';
 import { validateForLog, eloOutcomeForStrictComplete } from './lib/advisory-autofeed.js';
 import { readSoul, appendSoulMemory } from './lib/soul.js';
+import { createPublisher as createGdocPublisher } from './lib/gdoc-client.js';
 import {
   start as fdStart,
   status as fdStatus,
@@ -1353,6 +1354,56 @@ const tools = [
       additionalProperties: false,
     },
   },
+
+  // ─── Google Docs publish (service account, headless) ──────────────────
+  // byan-owned, durable publishing : a service-account JWT (no OAuth, no 7-day
+  // expiry) creates a branded Google Doc and returns its URL. Branding via a
+  // template (GDOC_TEMPLATE_ID) or the AcadeNice palette programmatically.
+  {
+    name: 'byan_publish',
+    description:
+      'Publish a branded Google Doc from content via a byan-owned SERVICE ACCOUNT (headless, durable, no OAuth). Copies a branded template when GDOC_TEMPLATE_ID is set (logo+palette in the template), else builds a programmatic doc branded by the AcadeNice palette. Returns the Doc URL; optionally shares it. Needs GOOGLE_APPLICATION_CREDENTIALS (SA key path). Degrades gracefully (ok:false + reason) when unconfigured. NOT remote-safe (network+auth).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Document title (required).' },
+        sections: {
+          type: 'array',
+          description: 'Ordered sections of the document.',
+          items: {
+            type: 'object',
+            properties: {
+              heading: { type: 'string' },
+              body: { type: 'string' },
+            },
+            additionalProperties: false,
+          },
+        },
+        resources: {
+          type: 'array',
+          description: 'Resource links rendered at the end.',
+          items: {
+            type: 'object',
+            properties: { label: { type: 'string' }, url: { type: 'string' } },
+            additionalProperties: false,
+          },
+        },
+        fields: {
+          type: 'object',
+          description: 'Extra {{KEY}} placeholder values for template mode.',
+        },
+        templateId: { type: 'string', description: 'Override GDOC_TEMPLATE_ID for this call.' },
+        shareWith: { type: 'string', description: 'Email address to share the Doc with.' },
+        role: {
+          type: 'string',
+          enum: ['reader', 'commenter', 'writer'],
+          description: 'Share role (default reader).',
+        },
+      },
+      required: ['title'],
+      additionalProperties: false,
+    },
+  },
 ];
 
 // Remote-safe MVP allowlist: the ONLY tools exposed on the remote Org Connector
@@ -2092,6 +2143,25 @@ export function createByanServer({ token, remoteOnly = false } = {}) {
       return { content: [{ type: 'text', text: JSON.stringify(instructions, null, 2) }] };
     }
 
+    // ─── Google Docs publish (service account, headless) ──────────────
+    if (name === 'byan_publish') {
+      const publisher = createGdocPublisher();
+      const result = await publisher.publish(
+        {
+          title: args.title,
+          sections: args.sections,
+          resources: args.resources,
+          fields: args.fields,
+        },
+        {
+          templateId: args.templateId,
+          shareWith: args.shareWith,
+          role: args.role,
+        }
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+
     // ─── Leantime tools ───────────────────────────────────────────────
     if (name === 'byan_leantime_ping') {
       const status = {

package/install/templates/_byan/mcp/byan-mcp-server/skill-bundles-manifest.json

@@ -184,7 +184,7 @@
       "name": "byan-hermes-dispatch",
       "module": "core",
       "tier": "connector-bound",
-      "sourceHash": "62b9c959c77468c0e14e3dfd45039151d29b1bcdc18b04b4d0deac606052a976"
+      "sourceHash": "45003e8a525a792d1a5dbe34ecb8e1443061fa5036a81a38a841598ce5aaf5ff"
     },
     "byan-insight": {
       "name": "byan-insight",