create-byan-agent 2.29.1 → 2.35.0

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

@@ -1,38 +1,78 @@
 #!/usr/bin/env node
 /**
- * UserPromptSubmit hook — injects BYAN tao voice directives into every
- * user prompt so Claude's response respects the register even when BYAN
- * agent isn't explicitly invoked.
+ * SessionStart hook — injects BYAN's FULL tao (voice directives) ONCE into the
+ * session's initial context, so it lands in the stable, cacheable prefix instead
+ * of being re-sent on every turn.
  *
- * Reads _byan/tao.md. If absent or empty, emits empty additionalContext
- * (no-op). Always exits 0.
+ * Cache rationale: a UserPromptSubmit injection is appended at the growing edge
+ * each turn, so the full ~3.6k-token tao was re-billed N times over a session.
+ * Loaded once at SessionStart it sits in the stable prefix (cache read at 10%).
+ * The per-turn voice freshness is carried by the tiny inject-voice-anchor.js
+ * (UserPromptSubmit): full tao here, compact anchor there. The voice stays 100%
+ * present every turn — nothing about it becomes conditional.
+ *
+ * Reads _byan/agent/byan/tao.md (Gen3) then _byan/tao.md (Gen2). Missing/empty ->
+ * empty additionalContext (no-op). Always exits 0.
  */
 
 const fs = require('fs');
 const path = require('path');
 
-const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-// Gen3 _byan/agent/byan/tao.md first, Gen2 _byan/tao.md fallback.
-const taoGen3 = path.join(projectDir, '_byan', 'agent', 'byan', 'tao.md');
-const taoPath = fs.existsSync(taoGen3) ? taoGen3 : path.join(projectDir, '_byan', 'tao.md');
+// Gen3 puts tao under _byan/agent/byan/; Gen2 keeps it at the _byan/ root.
+function taoFile(projectDir) {
+  const g3 = path.join(projectDir, '_byan', 'agent', 'byan', 'tao.md');
+  const g2 = path.join(projectDir, '_byan', 'tao.md');
+  return fs.existsSync(g3) ? g3 : g2;
+}
 
-let additionalContext = '';
-try {
-  if (fs.existsSync(taoPath)) {
-    const content = fs.readFileSync(taoPath, 'utf8').trim();
-    if (content.length > 0) {
-      additionalContext = `BYAN tao directives (active for this turn — follow register, signatures, forbidden vocabulary):\n\n${content}`;
+function buildTaoContext(projectDir) {
+  try {
+    const p = taoFile(projectDir);
+    if (fs.existsSync(p)) {
+      const content = fs.readFileSync(p, 'utf8').trim();
+      if (content.length > 0) {
+        return `BYAN tao (voice directives, loaded once at session start — register, signatures, forbidden vocabulary):\n\n${content}`;
+      }
     }
+  } catch {
+    // Hook must never block session start.
+  }
+  return '';
+}
+
+// Per-session turn counter for the voice-anchor refresh cadence (inject-voice-anchor.js).
+// It lives under _byan-output/ (gitignored). inject-tao OWNS the path and the reset
+// because the full tao it injects at SessionStart (including source=compact) restarts
+// the cadence: the next periodic full-tao refresh is then N turns later. The anchor hook
+// reads/writes the same path via require('./inject-tao') -- single source, no drift.
+function turnCounterPath(projectDir) {
+  return path.join(projectDir, '_byan-output', '.tao-refresh-turn');
+}
+
+function resetTurnCounter(projectDir) {
+  try {
+    const p = turnCounterPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, '0');
+  } catch {
+    // Never block session start.
+  }
+}
+
+if (require.main === module) {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  // A fresh full tao is about to be injected -> restart the voice-anchor cadence.
+  resetTurnCounter(projectDir);
+  const additionalContext = buildTaoContext(projectDir);
+  if (additionalContext) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext },
+      })
+    );
+  } else {
+    process.stdout.write('{}');
   }
-} catch {
-  // Hook must never block prompt submission.
 }
 
-process.stdout.write(
-  JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'UserPromptSubmit',
-      additionalContext: additionalContext || '',
-    },
-  })
-);
+module.exports = { taoFile, buildTaoContext, turnCounterPath, resetTurnCounter };

package/install/templates/.claude/hooks/inject-voice-anchor.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit hook — keeps BYAN's voice present near the live edge each turn.
+ *
+ * Most turns inject a COMPACT voice anchor (~95 tokens). Every Nth turn re-inject
+ * the FULL tao instead, so on a long session the heart is refreshed close to the
+ * live edge. N defaults to 12 (override with BYAN_TAO_REFRESH_EVERY; <= 0 disables
+ * the refresh, anchor every turn). The per-turn counter lives under _byan-output/
+ * (gitignored) and is reset at SessionStart by inject-tao.js, so the cadence
+ * restarts from each fresh full-tao load.
+ *
+ * Layered guarantee (best-effort, honest about its floor): each turn is a separate
+ * process, so the cadence needs a WRITABLE counter file to advance. If _byan-output/
+ * cannot be written, the counter cannot advance and this hook degrades to the anchor
+ * every turn -- it never crashes (exit 0), and the full heart still returns via
+ * inject-tao at SessionStart AND after every compaction (source=compact, pinned by
+ * the F1 test). So the periodic refresh is the in-window ENHANCEMENT; the
+ * SessionStart/compaction re-injection is the FLOOR that always holds. A persistent
+ * degradation means _byan-output/ is not writable -- check its permissions.
+ *
+ * The full tao is read via inject-tao.buildTaoContext (single source, no
+ * duplication; require is side-effect-free thanks to its require.main guard).
+ * Always exits 0 ; never blocks prompt submission.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { buildTaoContext, turnCounterPath } = require('./inject-tao');
+
+const ANCHOR = [
+  'Voix BYAN (rappel par tour ; tao complet chargé au démarrage de session) :',
+  '- Tutoiement, registre artisan-senior, direct sans être brusque, concis.',
+  '- Challenge avant de confirmer ; questionne les absolus (Mantra IA-16).',
+  '- Signatures : "Attends — pourquoi ?", "OK. On construit.", "Ça, c\'est du générique.".',
+  '- Zéro emoji. Orienté solution : on cherche la meilleure option, pas le mur.',
+].join('\n');
+
+const DEFAULT_REFRESH_EVERY = 12;
+
+function buildVoiceAnchor() {
+  return ANCHOR;
+}
+
+// Turns between full-tao refreshes. Invalid/absent env -> default. A value <= 0
+// disables the periodic refresh (anchor every turn) -- an explicit opt-out.
+function refreshEvery(env = process.env) {
+  const n = parseInt(env.BYAN_TAO_REFRESH_EVERY, 10);
+  return Number.isInteger(n) ? n : DEFAULT_REFRESH_EVERY;
+}
+
+function readTurn(projectDir) {
+  try {
+    const n = parseInt(fs.readFileSync(turnCounterPath(projectDir), 'utf8').trim(), 10);
+    return Number.isInteger(n) && n >= 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function writeTurn(projectDir, n) {
+  try {
+    const p = turnCounterPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, String(n));
+  } catch {
+    // Never block prompt submission.
+  }
+}
+
+// Pure cadence decision. Every Nth turn (N > 0) surfaces the full tao when it is
+// available; otherwise the compact anchor. Kept pure so the cadence is unit-testable
+// without fs.
+function decideAnchor({ turn, every, fullTao }) {
+  if (every > 0 && turn % every === 0 && fullTao) {
+    return { mode: 'full', additionalContext: fullTao };
+  }
+  return { mode: 'anchor', additionalContext: ANCHOR };
+}
+
+if (require.main === module) {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const every = refreshEvery();
+  const turn = readTurn(projectDir) + 1;
+  writeTurn(projectDir, turn);
+  const fullTao = every > 0 && turn % every === 0 ? buildTaoContext(projectDir) : '';
+  const { additionalContext } = decideAnchor({ turn, every, fullTao });
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext },
+    })
+  );
+}
+
+module.exports = {
+  buildVoiceAnchor,
+  ANCHOR,
+  refreshEvery,
+  readTurn,
+  writeTurn,
+  decideAnchor,
+  DEFAULT_REFRESH_EVERY,
+};

package/install/templates/.claude/rules/portable-core.md

@@ -0,0 +1,81 @@
+# BYAN Portable Core — Noyau portable, projection native
+
+> BYAN est livre via npm et tourne sur deux plateformes (Claude Code, Codex).
+> Son identite et son etat doivent survivre a l'absence de toute feature native.
+> Les features natives sont un accelerateur opportuniste, pas une bequille.
+
+## Principe (hexagonal / ports-and-adapters)
+
+Le noyau de BYAN — identite (soul, tao, soul-memory), etat (FD, strict, ELO),
+connaissance — vit dans des artefacts **portables, in-repo**, sous `_byan/` et
+`_byan-output/`, plus l'API `byan_web` quand le reseau est la. Ce noyau est la
+**source de verite**. Il est shippe, il marche offline, il marche sur une machine
+neuve, il marche sur Codex.
+
+Les fonctionnalites natives de la plateforme (Claude Code) sont une **couche
+d'acceleration en write-through** : BYAN ecrit *vers* elles pour en tirer le
+benefice (cache, recall, isolation), mais ne les lit pas comme autorite. Si la
+couche native est absente ou videe, BYAN se reconstruit depuis le noyau portable
+sans rien perdre de son identite ni de son etat.
+
+```
+        +---------------------- noyau portable (source de verite) ----------------------+
+        |  _byan/agent/byan/{soul,tao,soul-memory}.md   _byan-output/fd-state.json       |
+        |  _byan/memoire/{elo,fact-graph}.json          byan_web API (autorite reseau)   |
+        +-------------------------------------------------------------------------------+
+                 |  (write-through, pas une dependance)            ^  (reconstruction)
+                 v                                                |
+        +---------------------- adaptateurs natifs (accelerateurs) ---------------------+
+        |  injection prefix-cache   @-import memory files   hooks   subagent isolation   |
+        +-------------------------------------------------------------------------------+
+```
+
+## Les trois frontieres
+
+1. **Source de verite portable.** Toute chose dont BYAN a besoin pour etre
+   lui-meme est un fichier sous `_byan/` (ou une entree `byan_web`). Rien
+   d'essentiel ne vit uniquement dans une couche native.
+2. **Le natif est un accelerateur write-through.** On projette l'etat portable
+   *vers* le natif pour la vitesse / le cache / le recall. On ne doit pas dependre
+   du natif en lecture pour une fonction essentielle. La projection est derivee et
+   regenerable depuis le noyau.
+3. **L'AutoMem est hors-perimetre.** Le repertoire AutoMem natif de Claude Code
+   (`~/.claude/projects/<hash>/memory/`) est local a l'assistant, par-machine,
+   indexe par un hash du chemin projet — **non shippable** via npm. Il n'est pas
+   une source de verite BYAN, et aucun chemin de lecture critique n'en depend. Ce
+   qui doit etre portable vit dans `soul-memory` / `_byan/`.
+
+## Table : feature native -> adaptateur -> chemin degrade
+
+| Feature native Claude | Adaptateur BYAN (write-through) | Chemin degrade (natif absent / Codex) |
+|-----------------------|--------------------------------|----------------------------------------|
+| Prompt caching (prefixe stable) | `inject-soul.js` / `inject-tao.js` injectent soul+tao depuis `_byan/` au SessionStart | la voix reste lue depuis `_byan/` ; `inject-voice-anchor` re-pose l'ancre par tour |
+| Memory files (`@-import`) | fichiers in-repo (`_byan/`, `.claude/rules/`) charges nativement par Claude | sur Codex, le bloc `AGENTS.md` porte l'equivalent ; les regles restent des fichiers lisibles |
+| Hooks (SessionStart / PreCompact / Stop) | `.claude/hooks/*.js` | sur Codex (pas de hook), le contexte est porte par `AGENTS.md` ; le filet pre-commit reste actif |
+| Subagent isolation | `byan-hermes-dispatch` delegue et ne ramene qu'un distillat | si pas de subagent, execution inline main-thread (meme resultat, plus de tokens) |
+| Compaction | `pre-compact-save.js` ecrit un snapshot sous `_byan-output/` | l'etat FD vit dans `_byan-output/fd-state.json`, relisible sans la couche native |
+
+L'AutoMem n'a **pas** de ligne : ce n'est pas un adaptateur, il est hors-perimetre.
+
+## Le test de degradation (litmus)
+
+L'independance n'est pas une promesse, c'est un test. Wipe la couche native
+(hooks off, `~/.claude/` absent, Codex) : l'identite (soul/tao/soul-memory) et
+l'etat FD doivent se reconstruire depuis les artefacts portables `_byan/` seuls.
+Rebranche le natif : BYAN tourne plus lean (cache, distillat). **Les deux doivent
+tenir.** Garde-fou mecanique : `.claude/__tests__/portable-core.test.js` echoue
+si un chemin critique se met a dependre de l'AutoMem natif.
+
+## Mantras
+
+- `PORTABLE-1` Source de verite in-repo. Le noyau vit sous `_byan/`, pas dans le natif.
+- `PORTABLE-2` Natif = accelerateur, pas une dependance. On ecrit vers, on ne lit pas comme autorite.
+- `PORTABLE-3` AutoMem hors-perimetre. `~/.claude/projects/.../memory/` n'est pas une source BYAN.
+- `PORTABLE-4` Projection derivee. Toute copie native est regenerable depuis le noyau.
+- `PORTABLE-5` Degradation testee. L'independance passe un test, elle ne se decrete pas.
+
+## References
+
+- Doctrine token (pourquoi un pointeur sans `@-import`) : CLAUDE.md, section `## Compact instructions` (chantier context-engineering).
+- Isolation subagent (levier "plus avec moins") : `.claude/skills/byan-hermes-dispatch/SKILL.md`.
+- Etat FD portable : `_byan/mcp/byan-mcp-server/lib/fd-state.js` -> `_byan-output/fd-state.json`.

package/install/templates/.claude/settings.json

@@ -8,6 +8,10 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-soul.js"
           },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-tao.js"
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/soul-memory-check.js"
@@ -21,7 +25,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-tao.js"
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-voice-anchor.js"
           },
           {
             "type": "command",

package/install/templates/.claude/skills/byan-hermes-dispatch/SKILL.md

@@ -73,10 +73,12 @@ prompt: |
   Load persona first : read <specialist stub path>.
   Task : <full goal>
   Deliverables : <list>
-  When done, write a concise report (< 200 words).
+  When done, return ONLY a distilled summary (< 200 words, ~1-2k tokens) :
+  the verbose tool output, file contents and intermediate reasoning stay in
+  YOUR context and do not cross back -- only the distillate returns.
 ```
 
-**`mcp-worker`** : same Agent tool call but without `isolation`. Set the Agent's `model` to the returned `model` — `haiku` for exploration nature, otherwise omit `model` to inherit the session model. The tier follows the task nature, not its size.
+**`mcp-worker`** : same Agent tool call but without `isolation` — including the SAME distilled-summary cap in the prompt (the subagent returns only the distillate, not its verbose work). Set the Agent's `model` to the returned `model` — `haiku` for exploration nature, otherwise omit `model` to inherit the session model. The tier follows the task nature, not its size.
 
 For any spawned strategy : pass `model` to the Agent tool when it is non-null; omit it when null so the subagent inherits the session model.
 
@@ -110,9 +112,21 @@ If the user (or calling agent) provides N independent subtasks and `parallelizab
 2. Dispatch all N Agent tool calls **in one message**.
 3. Aggregate via `coordination.aggregate` and `writeSummary`.
 
+## Subagent isolation (token leverage)
+
+A subagent runs in its OWN context window — use that. Let it explore verbosely
+(read files, run tools, reason at length) inside its own context, and have it
+return ONLY a distilled summary (< 200 words, ~1-2k tokens) to the main thread.
+The verbose work does not land in the lead context : this is the Anthropic
+context-isolation principle (a subagent may burn ~9k tokens internally yet return
+~1-2k). It applies to BOTH spawn paths (worktree and mcp-worker), and it is why
+heavy, verbose or exploratory work is worth delegating even when the lead could
+do it inline — the delegation keeps the lead context lean ("plus avec moins").
+
 ## Hard rules
 
 - **Never ask for confirmation** before spawning. User opted into autonomous mode (Q1.b).
 - **Never execute the specialist's work yourself** unless strategy says `main-thread*`. You dispatch, you do not become the specialist.
 - **Never spawn with `isolation: "worktree"` for tasks < score 15** — the boot cost exceeds the gain.
 - **Never fabricate a specialist name**. If no match, say so and use `general-purpose`.
+- **Cap every subagent return.** Both spawn paths (worktree AND mcp-worker) instruct the subagent to return only a distilled summary (< 200 words / ~1-2k tokens) — the raw exploration stays in the subagent's context.

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

@@ -0,0 +1,203 @@
+// gdoc-client -- headless, byan-owned Google Docs publisher (service account).
+//
+// Turns a content object (see gdoc-content) into a branded Google Doc and returns
+// its URL. Auth is a SERVICE ACCOUNT key (JWT, durable, no browser, no refresh
+// token, no ~7-day expiry) -- distinct from the gw OAuth path. The SA key path is
+// resolved with the same precedence as the rest of the server (env ->
+// ~/.byan/credentials.json), via resolve-config.
+//
+// CONTRACT : never throws. Every failure (no key, dep not installed, API error)
+// is returned as { ok:false, reason, message } so the MCP tool surfaces a clean
+// message instead of crashing the server. On success : { ok:true, documentId,
+// url }.
+//
+// TESTABILITY : googleapis is LAZY-loaded through an injectable `load()` so (a)
+// the server boots even when googleapis is not installed, and (b) tests inject a
+// mock and never touch the network or the real dependency.
+
+import fs from 'node:fs';
+import { resolveConfig } from './resolve-config.js';
+
+// Narrowest scopes that let the SA create a Doc and share it : per-file Drive
+// access + Docs editing. Not the broad .../auth/drive.
+const SCOPES = [
+  'https://www.googleapis.com/auth/documents',
+  'https://www.googleapis.com/auth/drive.file',
+];
+
+function oneLine(err) {
+  return String((err && err.message) || err).split('\n')[0];
+}
+
+// Default lazy loader : import googleapis only when a publish actually runs. A
+// missing dependency is caught by the caller and turned into reason:'dep-missing'
+// -- it must NOT crash the server at import time.
+async function defaultLoad() {
+  const mod = await import('googleapis');
+  return { google: mod.google || (mod.default && mod.default.google) };
+}
+
+/**
+ * Read + parse the service-account JSON key at `keyPath`. Returns the parsed
+ * credentials object, or null on any failure (missing/unreadable/invalid).
+ */
+function readServiceAccount(keyPath, readFileSync) {
+  try {
+    const raw = readFileSync(keyPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && parsed.client_email && parsed.private_key) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * createPublisher(deps) -> { publish, status }. All side-effecting deps are
+ * injectable so the flow is fully unit-testable.
+ * @param {object} [deps]
+ * @param {Function} [deps.load]          async () => ({ google }) ; default lazy-imports googleapis
+ * @param {Function} [deps.resolve]       () => config ; default resolveConfig
+ * @param {Function} [deps.readFileSync]  default fs.readFileSync (reads the SA key)
+ */
+function createPublisher(deps = {}) {
+  const load = deps.load || defaultLoad;
+  const resolve = deps.resolve || resolveConfig;
+  const readFileSync = deps.readFileSync || fs.readFileSync;
+
+  // Read-only view of whether a SA key is configured (for a doctor/status surface).
+  function status() {
+    const cfg = resolve();
+    const keyPath = cfg.GOOGLE_APPLICATION_CREDENTIALS || '';
+    const sa = keyPath ? readServiceAccount(keyPath, readFileSync) : null;
+    return {
+      credentialsConfigured: Boolean(keyPath),
+      credentialsValid: Boolean(sa),
+      clientEmail: sa ? sa.client_email : null,
+      templateConfigured: Boolean(cfg.GDOC_TEMPLATE_ID),
+    };
+  }
+
+  /**
+   * publish(content, opts) -> { ok, documentId?, url?, mode?, shared?, reason?, message? }.
+   * opts : { templateId?, shareWith?, role? }. Never throws.
+   */
+  async function publish(content, opts = {}) {
+    const cfg = resolve();
+
+    // 1. SA key present + valid ?
+    const keyPath = cfg.GOOGLE_APPLICATION_CREDENTIALS || '';
+    if (!keyPath) {
+      return {
+        ok: false,
+        reason: 'no-credentials',
+        message:
+          'Aucune cle service account. Definis GOOGLE_APPLICATION_CREDENTIALS (chemin du JSON) dans l\'env ou ~/.byan/credentials.json. Voir docs/google-docs-publish.md.',
+      };
+    }
+    const credentials = readServiceAccount(keyPath, readFileSync);
+    if (!credentials) {
+      return {
+        ok: false,
+        reason: 'bad-credentials',
+        message: `La cle service account a ${keyPath} est introuvable ou invalide (client_email + private_key requis).`,
+      };
+    }
+
+    // 2. content shape (pure) -- import lazily to keep this module's top clean.
+    let content$;
+    let buildReplaceRequests;
+    let buildDocumentRequests;
+    try {
+      const gc = await import('./gdoc-content.js');
+      content$ = gc.normalizeContent(content);
+      buildReplaceRequests = gc.buildReplaceRequests;
+      buildDocumentRequests = gc.buildDocumentRequests;
+    } catch (err) {
+      return { ok: false, reason: 'invalid-content', message: oneLine(err) };
+    }
+
+    // 3. googleapis available ?
+    let google;
+    try {
+      ({ google } = await load());
+      if (!google) throw new Error('googleapis loaded but google export missing');
+    } catch {
+      return {
+        ok: false,
+        reason: 'dep-missing',
+        message:
+          'googleapis non installe. Lance : npm install googleapis google-auth-library (dans _byan/mcp/byan-mcp-server).',
+      };
+    }
+
+    // 4. auth + API + publish. Any API failure -> graceful api-error.
+    try {
+      const auth = new google.auth.GoogleAuth({ credentials, scopes: SCOPES });
+      const docs = google.docs({ version: 'v1', auth });
+      const drive = google.drive({ version: 'v3', auth });
+
+      const templateId = opts.templateId || cfg.GDOC_TEMPLATE_ID || '';
+      let documentId;
+      let mode;
+
+      if (templateId) {
+        const copy = await drive.files.copy({
+          fileId: templateId,
+          requestBody: { name: content$.title },
+          fields: 'id',
+        });
+        documentId = copy.data.id;
+        mode = 'template';
+        await docs.documents.batchUpdate({
+          documentId,
+          requestBody: { requests: buildReplaceRequests(content) },
+        });
+      } else {
+        const created = await docs.documents.create({
+          requestBody: { title: content$.title },
+        });
+        documentId = created.data.documentId;
+        mode = 'programmatic';
+        await docs.documents.batchUpdate({
+          documentId,
+          requestBody: {
+            requests: buildDocumentRequests(content, {
+              logoPngUrl: opts.logoPngUrl || cfg.GDOC_LOGO_PNG_URL || '',
+            }),
+          },
+        });
+      }
+
+      let shared = false;
+      if (opts.shareWith) {
+        await drive.permissions.create({
+          fileId: documentId,
+          requestBody: {
+            type: 'user',
+            role: opts.role === 'commenter' || opts.role === 'writer' ? opts.role : 'reader',
+            emailAddress: opts.shareWith,
+          },
+          sendNotificationEmail: false,
+        });
+        shared = true;
+      }
+
+      return {
+        ok: true,
+        documentId,
+        url: `https://docs.google.com/document/d/${documentId}/edit`,
+        mode,
+        shared,
+      };
+    } catch (err) {
+      return { ok: false, reason: 'api-error', message: oneLine(err) };
+    }
+  }
+
+  return { publish, status };
+}
+
+export { createPublisher, readServiceAccount, SCOPES };