create-byan-agent 2.28.0 → 2.29.0

package/CHANGELOG.md

@@ -9,6 +9,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.29.0] - 2026-06-23
+
+### Added - Native opt-in RTK token optimizer (rtk-ai/rtk)
+
+- The yanstaller now offers RTK ("Rust Token Killer", Apache-2.0) during install:
+  a single zero-dep binary that compresses dev-command output before the LLM
+  context (-60/90% tokens) and wires into Claude Code via its own hook.
+- Integration is thin and delegating (`install/lib/rtk-integration.js` +
+  `native-helper.js`): the install is handed to rtk's own canonical installer
+  (brew / `cargo --tag v0.42.4` / the pinned `install.sh`, which passes
+  `RTK_VERSION` so the downloaded binary is pinned too), and the hook wiring to
+  rtk's own `rtk init -g`. No bespoke per-OS download/checksum logic.
+- Opt-in and safe: the prompt defaults to NO and discloses the install mechanism
+  and the global hook; gated on a TTY + an available installer; opt out with
+  `BYAN_SKIP_RTK=1`. Every failure path is a graceful no-op that leaves the BYAN
+  install intact. Retry anytime with `npm run setup-rtk`. 25 unit tests.
+
+### Added - Open Knowledge Format (OKF v0.1) adoption for the knowledge base
+
+- BYAN's knowledge is now interoperable with the Open Knowledge Format
+  (GoogleCloudPlatform/knowledge-catalog) — markdown + YAML frontmatter, vendor-
+  neutral, zero runtime deps. Only the FORMAT is adopted; the GCP reference agent
+  (Python + BigQuery/Gemini) is deliberately left out (not vendored).
+- `lib/okf-format.js` (parse/serialize/validate frontmatter + BYAN type mapping)
+  and `lib/okf-bundle.js` (pure, idempotent converter). `byan-okf build` emits a
+  normalized OKF bundle to the gitignored `_byan-output/okf-bundle/` (NON-
+  destructive — it leaves `_byan/connaissance` untouched); `byan-okf check`
+  validates a bundle. 24 unit tests; a real build over the 43 knowledge files
+  yields 41 valid OKF entries. The optional GCP enrichment bridge is parked as a
+  phase-2 follow-on.
+
 ## [2.28.0] - 2026-06-23
 
 ### Added - Advisory model-tiering lint for native workflows

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

@@ -16,6 +16,7 @@ const { generateProjectAgentsDoc } = require('../lib/project-agents-generator');
 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 { setupClaudeNative } = require('../lib/claude-native-setup');
 const { setupCodexNative } = require('../lib/codex-native-setup');
 const { setupMcpExtensions } = require('../lib/mcp-extensions');
@@ -1369,6 +1370,33 @@ async function install(options = {}) {
     }
   }
 
+  if (needsClaude && shouldOfferRtk()) {
+    console.log();
+    console.log(chalk.cyan('RTK token optimizer (optional — Rust binary, cuts dev-command tokens 60-90%)'));
+    try {
+      const { proceed } = await inquirer.prompt([
+        {
+          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`.',
+          default: false,
+        },
+      ]);
+      if (proceed) {
+        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`));
+        } else {
+          console.log(chalk.yellow(`  ⚠ rtk not wired (${r.reason}) — BYAN unaffected`));
+        }
+      } else {
+        console.log(chalk.gray('  rtk skipped — run `npm run setup-rtk` anytime to enable.'));
+      }
+    } catch (error) {
+      console.log(chalk.yellow(`  ⚠ rtk setup skipped: ${error.message}`));
+    }
+  }
+
   if (needsClaude) {
     console.log();
     console.log(chalk.cyan('Leantime board sync (optional — self-hosted)'));

package/install/lib/native-helper.js

@@ -0,0 +1,50 @@
+'use strict';
+
+/**
+ * native-helper — dependency-light helpers for installing OPTIONAL native
+ * components (rtk today; turbo-whisper/parakeet can adopt it later to retire
+ * their bespoke per-OS branches, shrinking the maintenance surface).
+ *
+ * Everything is PURE + injectable (the command runner is a parameter) so callers
+ * stay unit-testable without shelling out for real. WHY: the install path runs on
+ * every user machine across OSes — it must be exercised by tests, not hope.
+ */
+
+const { execSync } = require('child_process');
+
+/**
+ * commandExists(cmd) -> boolean. Is an executable resolvable on PATH?
+ * Uses POSIX `command -v` (and `where` on Windows). The runner is injectable.
+ */
+function commandExists(cmd, { run = execSync, platform = process.platform } = {}) {
+  const probe = platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
+  try {
+    run(probe, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * detectPlatform() -> 'mac' | 'windows' | 'linux'. Coarse bucket for choosing an
+ * install strategy. Keeps the platform string in ONE place.
+ */
+function detectPlatform(platform = process.platform) {
+  if (platform === 'darwin') return 'mac';
+  if (platform === 'win32') return 'windows';
+  return 'linux';
+}
+
+/**
+ * firstAvailable(candidates) -> the first candidate whose `tool` resolves on
+ * PATH, or null. `candidates` is an ordered preference list of
+ * { id, tool, ... }. This is the generic "pick the installer the machine has"
+ * primitive; the concrete strategy list stays with each component.
+ */
+function firstAvailable(candidates, { has = commandExists } = {}) {
+  if (!Array.isArray(candidates)) return null;
+  return candidates.find((c) => c && c.tool && has(c.tool)) || null;
+}
+
+module.exports = { commandExists, detectPlatform, firstAvailable };

package/install/lib/rtk-integration.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * rtk-integration — optional NATIVE token-optimizer integration (rtk-ai/rtk).
+ *
+ * RTK ("Rust Token Killer", Apache-2.0) is a single zero-dependency binary that
+ * filters/compresses dev-command output before it reaches the LLM context
+ * (-60/90% tokens). It wires into Claude Code through its OWN hook installer.
+ *
+ * MAINTAINABILITY by design (the whole point of choosing this shape):
+ *  - We do NOT reimplement per-OS download / checksum / version pinning. We
+ *    DELEGATE the install to rtk's own canonical installer (brew / cargo / the
+ *    official install.sh), and DELEGATE the Claude Code hook wiring to rtk's own
+ *    `rtk init -g`. BYAN maintains only "pick the available installer, run it,
+ *    verify, ask rtk to wire its hook" — a tiny surface, bumped via one constant.
+ *  - SUPPLY-CHAIN: we pin to a TAG, never a moving branch. cargo builds the
+ *    tagged source (`--tag`), and install.sh is fetched from the IMMUTABLE tag ref
+ *    (and that script itself checksum-verifies the binary it downloads). So the
+ *    fetched artifacts are reproducible, not "whatever master is today".
+ *  - Everything is graceful: a missing installer or a failed step is a no-op that
+ *    NEVER breaks the BYAN install (returns { ok:true, synced:false, reason }).
+ *  - The command runner + the PATH probe are injectable, so the whole flow is
+ *    unit-tested without shelling out (see install/__tests__/rtk-integration.test.js).
+ *
+ * Mirrors the ENTRY-POINT shape of byan-web-integration.js / byan-leantime-
+ * integration.js (one `setup*Integration`); the return contract is { ok, synced,
+ * reason, ... } because persistence is owned by rtk's own `rtk init -g`, not by
+ * byan-platform-config.
+ */
+
+const { execSync } = require('child_process');
+const { commandExists, firstAvailable } = require('./native-helper');
+
+// Pinned install target. Bumping rtk = change these two constants only. We pin a
+// TAG so the install is reproducible and supply-chain-bounded (see header).
+const RTK_VERSION = '0.42.4';
+const RTK_TAG = `v${RTK_VERSION}`;
+const RTK_REPO = 'https://github.com/rtk-ai/rtk';
+const RTK_INSTALL_SH = `https://raw.githubusercontent.com/rtk-ai/rtk/refs/tags/${RTK_TAG}/install.sh`;
+
+/**
+ * Ordered install strategies — each DELEGATES to rtk's own canonical installer,
+ * pinned to RTK_TAG where the mechanism allows. Preference: brew (cleanest
+ * upgrades, vetted formula) > cargo (any Rust dev, pinned --tag) > the official
+ * install.sh at the immutable tag ref (universal fallback, self-checksumming).
+ */
+function installStrategies() {
+  return [
+    { id: 'brew', tool: 'brew', cmd: 'brew install rtk' },
+    { id: 'cargo', tool: 'cargo', cmd: `cargo install --git ${RTK_REPO} --tag ${RTK_TAG}` },
+    // Pass RTK_VERSION into the script so it pins the BINARY too (the script
+    // builds releases/download/${VERSION}/...; without it, it resolves
+    // releases/latest). Pinning the URL alone is not enough — this pins both.
+    { id: 'script', tool: 'curl', cmd: `curl -fsSL ${RTK_INSTALL_SH} | RTK_VERSION=${RTK_TAG} sh` },
+  ];
+}
+
+function oneLine(err) {
+  return String((err && err.message) || err).split('\n')[0];
+}
+
+/**
+ * rtkStatus() -> { installed, version }. Never throws. Parses `rtk --version`
+ * ("rtk 0.42.4"). An installed-but-unparseable build yields { installed:true,
+ * version:null } (a real runtime possibility, handled downstream).
+ */
+function rtkStatus({ run = execSync } = {}) {
+  try {
+    const out = String(run('rtk --version', { stdio: 'pipe' }) || '');
+    const m = out.match(/rtk\s+v?([0-9]+\.[0-9]+\.[0-9]+)/i);
+    return { installed: true, version: m ? m[1] : null };
+  } catch {
+    return { installed: false, version: null };
+  }
+}
+
+/**
+ * pickStrategy() -> the first install strategy whose tool is on PATH, or null.
+ */
+function pickStrategy({ has = commandExists } = {}) {
+  return firstAvailable(installStrategies(), { has });
+}
+
+/**
+ * doctor() -> a status report for diagnostics / a `byan` doctor surface. `pinned`
+ * is the version BYAN installs/targets — NOT an enforced floor on a pre-existing
+ * rtk (we do not break a user's own older rtk).
+ */
+function doctor({ run = execSync } = {}) {
+  const s = rtkStatus({ run });
+  return {
+    component: 'rtk',
+    installed: s.installed,
+    version: s.version,
+    pinned: RTK_VERSION,
+    repo: RTK_REPO,
+    hookCommand: 'rtk init -g',
+  };
+}
+
+// Delegate the Claude Code hook wiring to rtk's OWN command (idempotent). This is
+// the maintainability win: no manual settings.json merge to keep in sync.
+function wireHook({ run, log, installedVia, version }) {
+  try {
+    run('rtk init -g', { stdio: 'pipe' });
+    log(`rtk: ready (${installedVia}, v${version || '?'}) — hook wired via 'rtk init -g'. Restart Claude Code to activate.`);
+    return { ok: true, synced: true, reason: 'wired', installed: true, installedVia, version, hook: true };
+  } catch (err) {
+    log(`rtk: installed (${installedVia}) but 'rtk init -g' failed (${oneLine(err)}) — run it manually, BYAN unaffected.`);
+    return { ok: true, synced: false, reason: 'hook-failed', installed: true, installedVia, version, hook: false };
+  }
+}
+
+/**
+ * setupRtkIntegration(options) -> { ok, synced, reason, ... }. The single entry.
+ *
+ * Flow: if rtk is already present, just (re)wire the hook (idempotent). Otherwise
+ * pick an available installer, delegate the install to rtk, verify, then wire the
+ * hook. Any missing tool / failed step degrades to a logged no-op — it NEVER
+ * throws and NEVER fails the surrounding BYAN install. `ok` is therefore always
+ * true; `synced` says whether rtk ended up wired.
+ *
+ * @param {object} [o]
+ * @param {Function} [o.run]  command runner (default execSync) — injected in tests
+ * @param {Function} [o.has]  PATH probe (default commandExists) — injected in tests
+ * @param {Function} [o.log]  one-line breadcrumb sink (default no-op)
+ */
+function setupRtkIntegration({ run = execSync, has = commandExists, log = () => {} } = {}) {
+  const before = rtkStatus({ run });
+  if (before.installed) {
+    return wireHook({ run, log, installedVia: 'already-present', version: before.version });
+  }
+
+  const strat = pickStrategy({ has });
+  if (!strat) {
+    log('rtk: no installer found (brew / cargo / curl) — skipped. BYAN install unaffected.');
+    return { ok: true, synced: false, reason: 'no-installer', installed: false, hook: false };
+  }
+
+  // Breadcrumb BEFORE the (silent, possibly slow) delegated install so the user
+  // is not left staring at a frozen prompt while rtk's installer runs.
+  log(`rtk: installing via ${strat.id} (pinned ${RTK_TAG}; this can take a moment)...`);
+  try {
+    run(strat.cmd, { stdio: 'pipe' });
+  } catch (err) {
+    log(`rtk: install via ${strat.id} failed (${oneLine(err)}) — skipped gracefully.`);
+    return { ok: true, synced: false, reason: `install-failed:${strat.id}`, installed: false, hook: false };
+  }
+
+  const after = rtkStatus({ run });
+  if (!after.installed) {
+    log(`rtk: install via ${strat.id} ran but 'rtk --version' did not confirm — skipped.`);
+    return { ok: true, synced: false, reason: 'install-unverified', installed: false, hook: false };
+  }
+
+  return wireHook({ run, log, installedVia: strat.id, version: after.version });
+}
+
+/**
+ * shouldOfferRtk() -> boolean. The installer asks this BEFORE prompting the user:
+ * offer rtk only when (a) interactive (a TTY), (b) not opted out
+ * (BYAN_SKIP_RTK=1), and (c) an installer is actually on PATH — so we never prompt
+ * for something we cannot deliver, and never block a non-interactive/CI install.
+ */
+function shouldOfferRtk({ env = process.env, isTTY = !!(process.stdin && process.stdin.isTTY), has = commandExists } = {}) {
+  if (env && env.BYAN_SKIP_RTK === '1') return false;
+  if (!isTTY) return false;
+  return Boolean(pickStrategy({ has }));
+}
+
+module.exports = {
+  setupRtkIntegration,
+  rtkStatus,
+  pickStrategy,
+  installStrategies,
+  doctor,
+  shouldOfferRtk,
+  RTK_VERSION,
+  RTK_TAG,
+  RTK_INSTALL_SH,
+  RTK_REPO,
+};

package/install/package.json

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

package/install/setup-rtk.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * setup-rtk — explicit opt-in installer for the RTK token optimizer (rtk-ai/rtk).
+ *
+ * Run on demand: `npm run setup-rtk` (or `node install/setup-rtk.js`). It delegates
+ * the install to rtk's own canonical installer (brew / cargo / official script) and
+ * the Claude Code hook wiring to rtk's own `rtk init -g`. It NEVER throws: a missing
+ * installer or a failed step is reported and exits 0 (RTK is optional; BYAN works
+ * without it). The real logic lives in lib/rtk-integration.js and is unit-tested.
+ */
+
+const chalk = require('chalk');
+const { setupRtkIntegration, doctor } = require('./lib/rtk-integration');
+
+function main() {
+  console.log(chalk.cyan('\nRTK token optimizer (rtk-ai/rtk) — optional native component'));
+  console.log(chalk.gray('  Cuts dev-command tokens 60-90%; wires its own Claude Code hook.\n'));
+
+  const result = setupRtkIntegration({ log: (m) => console.log(chalk.gray('  ' + m)) });
+
+  if (result.synced) {
+    console.log(chalk.green(`\n  rtk ready (${result.installedVia}, v${result.version || '?'}). Restart Claude Code to activate.`));
+  } else if (result.reason === 'no-installer') {
+    console.log(chalk.yellow('\n  No installer found (brew / cargo / curl). Install one, then re-run `npm run setup-rtk`.'));
+  } else {
+    console.log(chalk.yellow(`\n  rtk not wired (${result.reason}). BYAN is unaffected; you can retry later.`));
+  }
+
+  const d = doctor();
+  console.log(chalk.gray(`  doctor: installed=${d.installed} version=${d.version || '-'} (pinned ${d.pinned})`));
+  // Optional component -> always a clean exit; never fail the surrounding flow.
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { main };

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

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// byan-okf — produce / validate an Open Knowledge Format bundle from BYAN's
+// knowledge base (_byan/connaissance).
+//
+//   byan-okf build [--root <dir>] [--out <dir>]   build a bundle (non-destructive)
+//   byan-okf check [<dir>] [--root <dir>]          validate every .md is OKF
+//
+// `build` is NON-DESTRUCTIVE: it reads _byan/connaissance and writes a normalized
+// OKF bundle (frontmatter + index.md + log.md) to the OUT dir (default
+// _byan-output/okf-bundle/, which is gitignored). It never mutates the source.
+// The conversion logic is in lib/okf-bundle.js (pure, unit-tested).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildBundle } from '../lib/okf-bundle.js';
+import { parseFrontmatter, validateOkf, OKF_RESERVED } from '../lib/okf-format.js';
+
+function parseArgs(argv) {
+  const a = { _: [] };
+  for (let i = 2; i < argv.length; i++) {
+    const x = argv[i];
+    if (x === '--root') a.root = argv[++i];
+    else if (x === '--out') a.out = argv[++i];
+    else a._.push(x);
+  }
+  return a;
+}
+
+function walkMd(dir, base = dir, acc = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walkMd(full, base, acc);
+    else if (e.isFile() && e.name.endsWith('.md')) acc.push({ relPath: path.relative(base, full), text: fs.readFileSync(full, 'utf8') });
+  }
+  return acc;
+}
+
+function cmdBuild(args) {
+  const root = args.root || process.cwd();
+  const src = path.join(root, '_byan', 'connaissance');
+  const out = args.out || path.join(root, '_byan-output', 'okf-bundle');
+  const files = walkMd(src);
+  if (!files.length) {
+    process.stdout.write(`[byan-okf] no markdown found under ${src} — nothing to build\n`);
+    return 0;
+  }
+  const timestamp = new Date().toISOString();
+  const { entries, index, log, errors } = buildBundle(files, { timestamp });
+  fs.mkdirSync(out, { recursive: true });
+  for (const e of entries) {
+    const dest = path.join(out, e.path);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, e.serialized);
+  }
+  fs.writeFileSync(path.join(out, 'index.md'), index);
+  fs.writeFileSync(path.join(out, 'log.md'), log);
+  const warned = entries.filter((e) => e.validation.warnings.length).length;
+  process.stdout.write(`[byan-okf] wrote ${entries.length} OKF entries + index.md + log.md to ${out} (${warned} with warnings, ${errors.length} invalid)\n`);
+  return errors.length ? 1 : 0;
+}
+
+function cmdCheck(args) {
+  const root = args.root || process.cwd();
+  const dir = args._[1] || path.join(root, '_byan-output', 'okf-bundle');
+  const files = walkMd(dir);
+  let bad = 0;
+  for (const f of files) {
+    if (OKF_RESERVED.includes(path.basename(f.relPath))) continue;
+    const { data } = parseFrontmatter(f.text);
+    const v = validateOkf(data);
+    if (!v.ok) {
+      bad += 1;
+      process.stderr.write(`[byan-okf] INVALID ${f.relPath}: ${v.errors.join('; ')}\n`);
+    }
+  }
+  if (bad) {
+    process.stderr.write(`[byan-okf] ${bad} invalid OKF file(s) under ${dir}\n`);
+    return 1;
+  }
+  process.stdout.write(`[byan-okf] OK - ${files.length} markdown file(s) are valid OKF under ${dir}\n`);
+  return 0;
+}
+
+const args = parseArgs(process.argv);
+const cmd = args._[0] || 'build';
+let code = 0;
+if (cmd === 'build') code = cmdBuild(args);
+else if (cmd === 'check') code = cmdCheck(args);
+else {
+  process.stderr.write(`[byan-okf] unknown command '${cmd}' (use: build | check)\n`);
+  code = 2;
+}
+process.exit(code);

package/install/templates/_byan/mcp/byan-mcp-server/lib/okf-bundle.js

@@ -0,0 +1,118 @@
+// okf-bundle — pure converter that turns BYAN knowledge files into an Open
+// Knowledge Format bundle (normalized frontmatter + index.md + log.md).
+//
+// PURE (no fs): the bin (byan-okf.js) does the I/O and hands content in/out.
+// buildEntry is a FIXPOINT on its own output — feeding a normalized file back in
+// keeps its fields verbatim (no duplication, no churn). Note: the FIRST build of a
+// frontmatter-less source stamps a fresh timestamp, but once a file carries one,
+// rebuilds preserve it. Unknown/extension keys are always preserved (OKF spec).
+
+import path from 'node:path';
+import {
+  parseFrontmatter,
+  serializeFrontmatter,
+  validateOkf,
+  byanTypeFor,
+  deriveTitle,
+  deriveDescription,
+  OKF_VERSION,
+  OKF_RESERVED,
+} from './okf-format.js';
+
+const PREFERRED_ORDER = ['type', 'title', 'description', 'resource', 'tags', 'timestamp'];
+
+function basenameTitle(relPath) {
+  return path.basename(String(relPath || '')).replace(/\.md$/, '');
+}
+
+/**
+ * buildEntry(relPath, text, { timestamp }) -> { path, data, body, serialized,
+ * validation }. Fills the OKF frontmatter from existing values FIRST (idempotent),
+ * deriving type/title/description only when absent. Existing + unknown keys are
+ * preserved; keys are emitted in a stable, readable order.
+ */
+export function buildEntry(relPath, text, { timestamp } = {}) {
+  const { data: existing, body } = parseFrontmatter(text);
+  const data = { ...existing };
+
+  if (!data.type) data.type = byanTypeFor(relPath);
+  if (!data.title) data.title = deriveTitle(body) || basenameTitle(relPath);
+  if (data.description === undefined) {
+    const d = deriveDescription(body);
+    if (d) data.description = d;
+  }
+  if (!data.timestamp && timestamp) data.timestamp = timestamp;
+  // A YAML-coerced Date (unquoted source timestamp) -> canonical ISO string, so
+  // the emitted bundle always carries a string timestamp.
+  if (data.timestamp instanceof Date) data.timestamp = data.timestamp.toISOString();
+
+  const ordered = {};
+  for (const k of PREFERRED_ORDER) if (data[k] !== undefined) ordered[k] = data[k];
+  for (const k of Object.keys(data)) if (ordered[k] === undefined) ordered[k] = data[k];
+
+  return {
+    path: relPath,
+    data: ordered,
+    body,
+    serialized: serializeFrontmatter(ordered, body),
+    validation: validateOkf(ordered),
+  };
+}
+
+/**
+ * buildIndex(entries) -> the bundle-root index.md content. Carries the
+ * `okf_version` frontmatter (the one place the spec allows it) and groups entries
+ * by type with relative links — the progressive-disclosure listing.
+ */
+export function buildIndex(entries) {
+  const byType = new Map();
+  for (const e of entries) {
+    const t = (e.data && e.data.type) || 'Knowledge';
+    if (!byType.has(t)) byType.set(t, []);
+    byType.get(t).push(e);
+  }
+  const lines = [
+    '# BYAN Knowledge',
+    '',
+    'Open Knowledge Format bundle generated from `_byan/connaissance`.',
+    '',
+  ];
+  for (const t of [...byType.keys()].sort()) {
+    lines.push(`## ${t}`, '');
+    for (const e of byType.get(t).slice().sort((a, b) => a.path.localeCompare(b.path))) {
+      const title = (e.data && e.data.title) || e.path;
+      const desc = e.data && e.data.description ? ` — ${e.data.description}` : '';
+      lines.push(`- [${title}](${e.path})${desc}`);
+    }
+    lines.push('');
+  }
+  return serializeFrontmatter({ okf_version: OKF_VERSION }, lines.join('\n'));
+}
+
+/**
+ * buildLog(entries, timestamp) -> log.md content. Reserved file, no frontmatter,
+ * plain update history.
+ */
+export function buildLog(entries, timestamp) {
+  const stamp = timestamp || '(unstamped)';
+  return `# Update Log\n\n## ${stamp}\n\nGenerated OKF bundle from _byan/connaissance: ${entries.length} entries.\n`;
+}
+
+/**
+ * buildBundle(files, { timestamp }) -> { entries, index, log, errors }. `files`
+ * is [{ relPath, text }]. Reserved names (index.md/log.md) and non-markdown are
+ * skipped. `errors` lists entries that fail OKF validation (should be none, since
+ * we always set `type`).
+ */
+export function buildBundle(files, { timestamp } = {}) {
+  const entries = (files || [])
+    .filter((f) => f && typeof f.relPath === 'string' && /\.md$/.test(f.relPath))
+    .filter((f) => !OKF_RESERVED.includes(path.basename(f.relPath)))
+    .map((f) => buildEntry(f.relPath, f.text, { timestamp }));
+  const index = buildIndex(entries);
+  const log = buildLog(entries, timestamp);
+  const errors = entries
+    .filter((e) => !e.validation.ok)
+    .map((e) => ({ path: e.path, errors: e.validation.errors }));
+  return { entries, index, log, errors };
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/okf-format.js

@@ -0,0 +1,136 @@
+// okf-format — Open Knowledge Format v0.1 primitives (parse / serialize /
+// validate) + the BYAN knowledge type mapping.
+//
+// OKF (GoogleCloudPlatform/knowledge-catalog) represents knowledge as plain
+// markdown + YAML frontmatter, vendor-neutral and dependency-free for consumers.
+// We ADOPT the FORMAT for _byan/connaissance (the GCP reference AGENT, which needs
+// BigQuery/Gemini, is deliberately NOT vendored — see docs). This module is the
+// single source of truth for the frontmatter contract; the converter
+// (okf-bundle.js) builds on it.
+//
+// Spec v0.1: required `type` (free string); recommended `title`, `description`,
+// `resource`, `tags` (list), `timestamp` (ISO-8601); unknown keys MUST be
+// preserved. Reserved filenames: index.md (listing, okf_version at bundle root)
+// and log.md (history).
+
+import yaml from 'js-yaml';
+
+export const OKF_VERSION = '0.1';
+export const OKF_RESERVED = Object.freeze(['index.md', 'log.md']);
+
+const FM_RE = /^?---\n([\s\S]*?)\n---\n?/;
+const ISO_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?)?$/;
+
+/**
+ * parseFrontmatter(text) -> { data, body }. A leading `---\n...\n---` block is
+ * YAML-parsed into `data`; the rest is `body`. No block -> { data:{}, body:text }.
+ * Malformed YAML degrades to {} rather than throwing (a knowledge file is never
+ * worth crashing the tool over).
+ */
+export function parseFrontmatter(text) {
+  const s = String(text == null ? '' : text);
+  const m = s.match(FM_RE);
+  if (!m) return { data: {}, body: s.replace(/^/, '') };
+  let data;
+  try {
+    data = yaml.load(m[1]);
+  } catch {
+    data = {};
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
+  // Strip the blank line(s) the convention puts between `---` and the body, so
+  // body starts at real content and round-trips cleanly with serializeFrontmatter.
+  return { data, body: s.slice(m[0].length).replace(/^\n+/, '') };
+}
+
+/**
+ * serializeFrontmatter(data, body) -> a markdown string with a clean YAML
+ * frontmatter block followed by the body. Round-trips with parseFrontmatter.
+ */
+export function serializeFrontmatter(data, body) {
+  const fm = yaml.dump(data || {}, { lineWidth: -1, noRefs: true, sortKeys: false }).trimEnd();
+  const b = String(body == null ? '' : body).replace(/^\n+/, '');
+  return `---\n${fm}\n---\n\n${b}`.replace(/\n*$/, '\n');
+}
+
+/**
+ * isIsoTimestamp(v) -> true for an ISO-8601 date/datetime string OR a Date.
+ * js-yaml coerces an UNQUOTED YAML timestamp (`timestamp: 2026-06-23T10:00:00Z`)
+ * into a JS Date, so a valid hand-authored OKF file must not be rejected for it.
+ */
+export function isIsoTimestamp(v) {
+  if (v instanceof Date) return !Number.isNaN(v.getTime());
+  return typeof v === 'string' && ISO_RE.test(v);
+}
+
+/**
+ * validateOkf(data) -> { ok, errors, warnings }. Enforces the v0.1 contract:
+ * `type` is required; title/description must be strings if present; tags must be
+ * a string list; timestamp must be ISO-8601. Missing recommended fields are
+ * WARNINGS, not errors (the spec only hard-requires `type`).
+ */
+export function validateOkf(data) {
+  const errors = [];
+  const warnings = [];
+  const d = data && typeof data === 'object' ? data : {};
+
+  if (typeof d.type !== 'string' || !d.type.trim()) {
+    errors.push('missing required field: type (non-empty string)');
+  }
+  for (const k of ['title', 'description', 'resource']) {
+    if (d[k] !== undefined && typeof d[k] !== 'string') errors.push(`${k} must be a string`);
+  }
+  if (d.tags !== undefined && (!Array.isArray(d.tags) || d.tags.some((t) => typeof t !== 'string'))) {
+    errors.push('tags must be a list of strings');
+  }
+  if (d.timestamp !== undefined && !isIsoTimestamp(d.timestamp)) {
+    errors.push('timestamp must be ISO-8601');
+  }
+  for (const k of ['title', 'description', 'timestamp']) {
+    if (d[k] === undefined) warnings.push(`recommended field absent: ${k}`);
+  }
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+/**
+ * byanTypeFor(relPath) -> a sensible OKF `type` for a _byan/connaissance file.
+ * Types are free strings in OKF; this keeps BYAN's vocabulary consistent.
+ */
+export function byanTypeFor(relPath) {
+  const p = String(relPath || '').replace(/\\/g, '/');
+  const base = p.split('/').pop();
+  if (base === 'sources.md') return 'Reference: Source Registry';
+  if (base === 'blacklisted-sources.md') return 'Reference: Blacklist';
+  if (base === 'mantras-sources.md') return 'Reference: Mantra Sources';
+  if (base === 'axioms.md') return 'Axiom';
+  // Match by path SEGMENT (not '/testarch/') so it works for relative paths
+  // ('testarch/...') the converter passes AND absolute ones.
+  const segs = p.split('/');
+  if (segs.includes('testarch')) return 'Knowledge: Test Architecture';
+  if (segs.includes('excalidraw')) return 'Knowledge: Excalidraw';
+  return 'Knowledge';
+}
+
+/** deriveTitle(body) -> the first `# ` heading text, or null. */
+export function deriveTitle(body) {
+  const m = String(body || '').match(/^#\s+(.+?)\s*$/m);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * deriveDescription(body) -> the first prose sentence (skipping headings, the
+ * bold `**key:**` metadata lines, blockquotes and rules), capped at 200 chars,
+ * or null when the body has no prose. Best-effort only (description is a
+ * RECOMMENDED field): the sentence split is naive (an abbreviation like "e.g."
+ * truncates early) and a leading bullet is taken verbatim — acceptable for a
+ * derived default a human can override in the frontmatter.
+ */
+export function deriveDescription(body) {
+  for (const raw of String(body || '').split('\n')) {
+    const t = raw.trim();
+    if (!t || t.startsWith('#') || t.startsWith('---') || t.startsWith('**') || t.startsWith('>') || t.startsWith('|')) continue;
+    const sentence = t.split(/(?<=[.!?])\s/)[0];
+    return sentence.length > 200 ? `${sentence.slice(0, 197)}...` : sentence;
+  }
+  return null;
+}

package/install/templates/_byan/workflow/simple/interview-workflow.md

@@ -490,7 +490,7 @@ try {
 
 **Plan:** `BYAN-V2-MANUAL-TEST-PLAN.md`
 
-1. Run demo-byan-v2-simple.js
+1. Run examples/demo-byan-v2-simple.js
 2. Verify 12 questions asked
 3. Check profile generated
 4. Validate against GitHub Copilot CLI requirements
@@ -570,7 +570,7 @@ byan.setTemplate('my-custom-template');
 ### Tests
 - `__tests__/byan-v2/orchestrator/` - Tests unitaires
 - `__tests__/byan-v2/integration/` - Tests intégration
-- `demo-byan-v2-simple.js` - Démo complète
+- `examples/demo-byan-v2-simple.js` - Démo complète
 
 ---
 

package/install/templates/_byan/workflow/simple/validate-agent-workflow.md

@@ -271,7 +271,7 @@ Emojis not allowed in technical sections
 ### Integration Tests
 
 **Scenarios:**
-1. Validate demo agent (demo-byan-v2-simple.js output)
+1. Validate demo agent (examples/demo-byan-v2-simple.js output)
 2. Validate all BYAN agents in _byan/agents/
 3. Detect invalid agents (negative tests)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.28.0",
+  "version": "2.29.0",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {
@@ -17,6 +17,7 @@
     "test:watch": "jest --watch",
     "test:e2e": "jest install/__tests__/post-install.e2e.test.js",
     "setup-turbo-whisper": "node install/setup-turbo-whisper.js",
+    "setup-rtk": "node install/setup-rtk.js",
     "byan": "echo \"BYAN agent installed. Open Claude Code (or Codex) in this project.\"",
     "version": "node scripts/sync-install-version.js && git add install/package.json",
     "app:dev": "npm --prefix app run dev",
@@ -61,6 +62,7 @@
     "install/packages/platform-config/package.json",
     "install/setup-turbo-whisper.js",
     "install/setup-parakeet.js",
+    "install/setup-rtk.js",
     "install/install.sh",
     "install/package.json",
     "update-byan-agent/bin/",