@kntic/kntic 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kntic/kntic",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "author": "Thomas Robak <contact@kntic.ai> (https://kntic.ai)",
   "description": "KNTIC CLI — bootstrap and manage KNTIC projects",
   "main": "src/index.js",

package/src/cli.js

@@ -17,7 +17,10 @@ if (!subcommand || subcommand === "usage") {
   });
 } else if (subcommand === "start") {
   try {
-    const startOpts = { screen: args.includes("--screen") };
+    const startOpts = {
+      screen: args.includes("--screen"),
+      tmux: args.includes("--tmux"),
+    };
     commands.start(startOpts);
   } catch (err) {
     console.error(`Error: ${err.message}`);

package/src/commands/start.js

@@ -14,11 +14,24 @@ function isScreenAvailable() {
   }
 }
 
+function isTmuxAvailable() {
+  try {
+    execSync("which tmux", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function isInsideScreen() {
   return !!process.env.STY;
 }
 
-function getScreenName() {
+function isInsideTmux() {
+  return !!process.env.TMUX;
+}
+
+function getSessionName() {
   try {
     const content = readFileSync(".kntic.env", "utf8");
     const match = content.match(/^KNTIC_PRJ_PREFIX=(.+)$/m);
@@ -31,24 +44,54 @@ function getScreenName() {
   return basename(process.cwd());
 }
 
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
 function start(options = {}) {
+  const useScreen = !!options.screen;
+  const useTmux = !!options.tmux;
+
+  if (useScreen && useTmux) {
+    throw new Error("--screen and --tmux cannot be used together");
+  }
+
   const provider = getComposeProvider();
   const composeCmd = `${provider} -f kntic.yml --env-file .kntic.env up --build`;
-  const useScreen = !!options.screen;
 
   if (useScreen && isScreenAvailable() && !isInsideScreen()) {
-    const screenName = getScreenName();
-    console.log(`Starting KNTIC services in screen session "${screenName}"…`);
-    execSync(`screen -S ${screenName} ${composeCmd}`, { stdio: "inherit" });
-  } else {
-    if (useScreen && isInsideScreen()) {
-      console.log("Already inside a screen session, skipping screen wrapper.");
-    } else if (useScreen && !isScreenAvailable()) {
-      console.log("screen is not available, starting without screen wrapper.");
-    }
-    console.log("Starting KNTIC services…");
-    execSync(composeCmd, { stdio: "inherit" });
+    const sessionName = getSessionName();
+    console.log(`Starting KNTIC services in screen session "${sessionName}"…`);
+    execSync(`screen -S ${shellQuote(sessionName)} ${composeCmd}`, { stdio: "inherit" });
+    return;
   }
+
+  if (useTmux && isTmuxAvailable() && !isInsideTmux()) {
+    const sessionName = getSessionName();
+    console.log(`Starting KNTIC services in tmux session "${sessionName}"…`);
+    execSync(`tmux new-session -s ${shellQuote(sessionName)} ${shellQuote(composeCmd)}`, { stdio: "inherit" });
+    return;
+  }
+
+  if (useScreen && isInsideScreen()) {
+    console.log("Already inside a screen session, skipping screen wrapper.");
+  } else if (useScreen && !isScreenAvailable()) {
+    console.log("screen is not available, starting without screen wrapper.");
+  } else if (useTmux && isInsideTmux()) {
+    console.log("Already inside a tmux session, skipping tmux wrapper.");
+  } else if (useTmux && !isTmuxAvailable()) {
+    console.log("tmux is not available, starting without tmux wrapper.");
+  }
+
+  console.log("Starting KNTIC services…");
+  execSync(composeCmd, { stdio: "inherit" });
 }
 
-module.exports = start;
+module.exports = Object.assign(start, {
+  isScreenAvailable,
+  isTmuxAvailable,
+  isInsideScreen,
+  isInsideTmux,
+  getSessionName,
+  shellQuote,
+});

package/src/commands/start.test.js

@@ -5,18 +5,38 @@ const assert = require("node:assert/strict");
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const childProcess = require("child_process");
 
-// Helper: extract a named function from start.js source by evaluating it in isolation.
-function extractFn(fnName) {
-  const src = fs.readFileSync(require.resolve("./start"), "utf8");
-  return new Function("require", "process",
-    src.replace(/^"use strict";\s*/, "")
-       .replace(/module\.exports\s*=\s*start;/, `return ${fnName};`)
-  )(require, process);
+function withMockedExecSync(mockImpl, run) {
+  const originalExecSync = childProcess.execSync;
+  childProcess.execSync = mockImpl;
+  delete require.cache[require.resolve("./start")];
+
+  try {
+    return run(require("./start"));
+  } finally {
+    childProcess.execSync = originalExecSync;
+    delete require.cache[require.resolve("./start")];
+  }
 }
 
-describe("start — getScreenName resolution", () => {
-  let tmpDir, origCwd;
+function captureConsoleLogs(run) {
+  const originalLog = console.log;
+  const logs = [];
+  console.log = (...args) => logs.push(args.join(" "));
+
+  try {
+    run(logs);
+  } finally {
+    console.log = originalLog;
+  }
+
+  return logs;
+}
+
+describe("start — session name resolution", () => {
+  let tmpDir;
+  let origCwd;
 
   beforeEach(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-start-test-"));
@@ -31,34 +51,31 @@ describe("start — getScreenName resolution", () => {
 
   it("uses KNTIC_PRJ_PREFIX from .kntic.env when present", () => {
     fs.writeFileSync(path.join(tmpDir, ".kntic.env"), "UID=1000\nKNTIC_PRJ_PREFIX=myproject\nGID=1000\n");
-    delete require.cache[require.resolve("./start")];
-    const getScreenName = extractFn("getScreenName");
-    assert.equal(getScreenName(), "myproject");
+    const start = require("./start");
+    assert.equal(start.getSessionName(), "myproject");
   });
 
   it("falls back to current directory name when KNTIC_PRJ_PREFIX is missing", () => {
     fs.writeFileSync(path.join(tmpDir, ".kntic.env"), "UID=1000\nGID=1000\n");
-    delete require.cache[require.resolve("./start")];
-    const getScreenName = extractFn("getScreenName");
-    assert.equal(getScreenName(), path.basename(tmpDir));
+    const start = require("./start");
+    assert.equal(start.getSessionName(), path.basename(tmpDir));
   });
 
   it("falls back to current directory name when .kntic.env does not exist", () => {
-    delete require.cache[require.resolve("./start")];
-    const getScreenName = extractFn("getScreenName");
-    assert.equal(getScreenName(), path.basename(tmpDir));
+    const start = require("./start");
+    assert.equal(start.getSessionName(), path.basename(tmpDir));
   });
 
   it("ignores empty KNTIC_PRJ_PREFIX value", () => {
     fs.writeFileSync(path.join(tmpDir, ".kntic.env"), "KNTIC_PRJ_PREFIX=\nUID=1000\n");
-    delete require.cache[require.resolve("./start")];
-    const getScreenName = extractFn("getScreenName");
-    assert.equal(getScreenName(), path.basename(tmpDir));
+    const start = require("./start");
+    assert.equal(start.getSessionName(), path.basename(tmpDir));
   });
 });
 
 describe("start — compose provider from .kntic.env", () => {
-  let tmpDir, origCwd;
+  let tmpDir;
+  let origCwd;
 
   beforeEach(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-start-compose-"));
@@ -89,11 +106,13 @@ describe("start — compose provider from .kntic.env", () => {
   });
 });
 
-describe("start — isInsideScreen detection", () => {
+describe("start — session detection helpers", () => {
   let origSTY;
+  let origTMUX;
 
   beforeEach(() => {
     origSTY = process.env.STY;
+    origTMUX = process.env.TMUX;
   });
 
   afterEach(() => {
@@ -102,19 +121,142 @@ describe("start — isInsideScreen detection", () => {
     } else {
       process.env.STY = origSTY;
     }
+
+    if (origTMUX === undefined) {
+      delete process.env.TMUX;
+    } else {
+      process.env.TMUX = origTMUX;
+    }
   });
 
   it("returns true when STY environment variable is set", () => {
     process.env.STY = "12345.myscreen";
-    delete require.cache[require.resolve("./start")];
-    const isInsideScreen = extractFn("isInsideScreen");
-    assert.equal(isInsideScreen(), true);
+    const start = require("./start");
+    assert.equal(start.isInsideScreen(), true);
   });
 
   it("returns false when STY environment variable is not set", () => {
     delete process.env.STY;
-    delete require.cache[require.resolve("./start")];
-    const isInsideScreen = extractFn("isInsideScreen");
-    assert.equal(isInsideScreen(), false);
+    const start = require("./start");
+    assert.equal(start.isInsideScreen(), false);
+  });
+
+  it("returns true when TMUX environment variable is set", () => {
+    process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+    const start = require("./start");
+    assert.equal(start.isInsideTmux(), true);
+  });
+
+  it("returns false when TMUX environment variable is not set", () => {
+    delete process.env.TMUX;
+    const start = require("./start");
+    assert.equal(start.isInsideTmux(), false);
+  });
+});
+
+describe("start — tmux wrapper behavior", () => {
+  let tmpDir;
+  let origCwd;
+  let origTMUX;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-start-tmux-"));
+    origCwd = process.cwd();
+    origTMUX = process.env.TMUX;
+    process.chdir(tmpDir);
+    delete process.env.TMUX;
+    fs.writeFileSync(path.join(tmpDir, ".kntic.env"), "KNTIC_COMPOSE_PROVIDER=docker compose\nKNTIC_PRJ_PREFIX=demo\n");
+  });
+
+  afterEach(() => {
+    process.chdir(origCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+
+    if (origTMUX === undefined) {
+      delete process.env.TMUX;
+    } else {
+      process.env.TMUX = origTMUX;
+    }
+  });
+
+  it("starts inside tmux when tmux is available and not already inside tmux", () => {
+    const calls = [];
+
+    const logs = captureConsoleLogs(() => {
+      withMockedExecSync((command, options) => {
+        calls.push({ command, options });
+        return Buffer.from("");
+      }, (start) => {
+        start({ tmux: true });
+      });
+    });
+
+    assert.equal(calls.length, 2);
+    assert.equal(calls[0].command, "which tmux");
+    assert.match(calls[1].command, /^tmux new-session -s 'demo' 'docker compose -f kntic\.yml --env-file \.kntic\.env up --build'$/);
+    assert.equal(calls[1].options.stdio, "inherit");
+    assert.deepEqual(logs, ['Starting KNTIC services in tmux session "demo"…']);
+  });
+
+  it("falls back to foreground mode when tmux is unavailable", () => {
+    const calls = [];
+
+    const logs = captureConsoleLogs(() => {
+      withMockedExecSync((command, options) => {
+        calls.push({ command, options });
+        if (command === "which tmux") {
+          throw new Error("tmux not found");
+        }
+        return Buffer.from("");
+      }, (start) => {
+        start({ tmux: true });
+      });
+    });
+
+    assert.equal(calls.length, 3);
+    assert.equal(calls[0].command, "which tmux");
+    assert.equal(calls[1].command, "which tmux");
+    assert.equal(calls[2].command, "docker compose -f kntic.yml --env-file .kntic.env up --build");
+    assert.deepEqual(logs, [
+      "tmux is not available, starting without tmux wrapper.",
+      "Starting KNTIC services…",
+    ]);
+  });
+
+  it("bypasses tmux wrapper when already inside tmux", () => {
+    process.env.TMUX = "/tmp/tmux-1000/default,456,0";
+    const calls = [];
+
+    const logs = captureConsoleLogs(() => {
+      withMockedExecSync((command, options) => {
+        calls.push({ command, options });
+        return Buffer.from("");
+      }, (start) => {
+        start({ tmux: true });
+      });
+    });
+
+    assert.equal(calls.length, 2);
+    assert.equal(calls[0].command, "which tmux");
+    assert.equal(calls[1].command, "docker compose -f kntic.yml --env-file .kntic.env up --build");
+    assert.deepEqual(logs, [
+      "Already inside a tmux session, skipping tmux wrapper.",
+      "Starting KNTIC services…",
+    ]);
+  });
+
+  it("rejects using --screen and --tmux together", () => {
+    const calls = [];
+
+    assert.throws(() => {
+      withMockedExecSync((command) => {
+        calls.push(command);
+        return Buffer.from("");
+      }, (start) => {
+        start({ screen: true, tmux: true });
+      });
+    }, /--screen and --tmux cannot be used together/);
+
+    assert.deepEqual(calls, []);
   });
 });

package/src/commands/update.js

@@ -405,60 +405,74 @@ function extractCompose(tarball, destDir) {
   console.log("Updated kntic.yml from bootstrap template.");
 }
 
-async function update(options = {}) {
+async function update(options = {}, deps = {}) {
   const libOnly = options.libOnly || false;
+  const composeFlagUsed = options.compose || false;
+  const fetchTextImpl = deps.fetchText || fetchText;
+  const downloadImpl = deps.download || download;
+  const extractLibOnlyImpl = deps.extractLibOnly || extractLibOnly;
+  const extractUpdateImpl = deps.extractUpdate || extractUpdate;
+  const mergeEnvFileImpl = deps.mergeEnvFile || mergeEnvFile;
+  const extractComposeImpl = deps.extractCompose || extractCompose;
+  const updateEnvVersionImpl = deps.updateEnvVersion || updateEnvVersion;
+
+  if (composeFlagUsed) {
+    console.warn("Warning: --compose is deprecated because kntic.yml is now included in the default update path.");
+    if (libOnly) {
+      console.log("Info: --lib-only skips kntic.yml updates.");
+    }
+  }
 
   // Resolve current version from the artifact metadata file
-  const artifactFilename = await fetchText(BOOTSTRAP_ARTIFACT_URL);
+  const artifactFilename = await fetchTextImpl(BOOTSTRAP_ARTIFACT_URL);
   const version = extractVersion(artifactFilename);
 
   const tmpFile = path.join(os.tmpdir(), `kntic-bootstrap-${Date.now()}.tar.gz`);
 
   console.log(`Downloading KNTIC bootstrap archive… (v${version})`);
-  await download(BOOTSTRAP_URL, tmpFile);
+  await downloadImpl(BOOTSTRAP_URL, tmpFile);
 
   if (libOnly) {
     console.log("Updating .kntic/lib …");
-    extractLibOnly(tmpFile, ".");
+    extractLibOnlyImpl(tmpFile, ".");
   } else {
     console.log("Updating .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, .kntic/hooks/gia/specific (if new), and .kntic/gia/weights.json …");
-    extractUpdate(tmpFile, ".");
+    extractUpdateImpl(tmpFile, ".");
   }
 
-  // Merge new env variables from the archive's .kntic.env template
-  const timestamp = Date.now();
-  const tmpEnvTemplate = path.join(os.tmpdir(), `kntic-env-template-${timestamp}`);
-  try {
-    const tmpExtractDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-env-extract-"));
+  if (!libOnly) {
+    // Merge new env variables from the archive's .kntic.env template
+    const timestamp = Date.now();
+    const tmpEnvTemplate = path.join(os.tmpdir(), `kntic-env-template-${timestamp}`);
     try {
-      execSync(`tar xzf "${tmpFile}" -C "${tmpExtractDir}" "./.kntic.env"`, { stdio: "pipe" });
-      const extractedEnv = path.join(tmpExtractDir, ".kntic.env");
-      if (fs.existsSync(extractedEnv)) {
-        fs.copyFileSync(extractedEnv, tmpEnvTemplate);
-        mergeEnvFile(tmpEnvTemplate, ".kntic.env");
-      } else {
+      const tmpExtractDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-env-extract-"));
+      try {
+        execSync(`tar xzf "${tmpFile}" -C "${tmpExtractDir}" "./.kntic.env"`, { stdio: "pipe" });
+        const extractedEnv = path.join(tmpExtractDir, ".kntic.env");
+        if (fs.existsSync(extractedEnv)) {
+          fs.copyFileSync(extractedEnv, tmpEnvTemplate);
+          mergeEnvFileImpl(tmpEnvTemplate, ".kntic.env");
+        } else {
+          console.log("No .kntic.env template in archive, skipping env merge.");
+        }
+      } catch (_) {
         console.log("No .kntic.env template in archive, skipping env merge.");
+      } finally {
+        fs.rmSync(tmpExtractDir, { recursive: true, force: true });
       }
-    } catch (_) {
-      console.log("No .kntic.env template in archive, skipping env merge.");
     } finally {
-      fs.rmSync(tmpExtractDir, { recursive: true, force: true });
+      try { fs.unlinkSync(tmpEnvTemplate); } catch (_) {}
     }
-  } finally {
-    try { fs.unlinkSync(tmpEnvTemplate); } catch (_) {}
-  }
 
-  // Replace kntic.yml from archive if --compose flag is set
-  if (options.compose) {
     try {
-      extractCompose(tmpFile, ".");
+      extractComposeImpl(tmpFile, ".");
     } catch (_) {
       console.log("No kntic.yml in archive, skipping compose update.");
     }
   }
 
   // Update KNTIC_VERSION in .kntic.env
-  updateEnvVersion(version);
+  updateEnvVersionImpl(version);
 
   // Clean up
   fs.unlinkSync(tmpFile);
@@ -467,7 +481,7 @@ async function update(options = {}) {
   if (libOnly) {
     console.log("Done. .kntic/lib updated successfully.");
   } else {
-    console.log("Done. .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, .kntic/hooks/gia/specific (if new), and .kntic/gia/weights.json updated successfully.");
+    console.log("Done. .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, .kntic/hooks/gia/specific (if new), .kntic/gia/weights.json, and kntic.yml updated successfully.");
   }
 }
 

package/src/commands/update.test.js

@@ -7,7 +7,9 @@ const path = require("path");
 const os = require("os");
 const { execSync } = require("child_process");
 
-const { extractLibOnly, extractUpdate, extractCompose, extractVersion, clearDirectory, updateEnvVersion, mergeEnvFile } = require("./update");
+const update = require("./update");
+const usage = require("./usage");
+const { extractLibOnly, extractUpdate, extractCompose, extractVersion, clearDirectory, updateEnvVersion, mergeEnvFile } = update;
 
 /**
  * Helper — create a tar.gz archive in `tmpDir` containing the given files.
@@ -727,6 +729,148 @@ describe("mergeEnvFile", () => {
   });
 });
 
+describe("update", () => {
+  let tmpDir;
+  let cwd;
+  let originalLog;
+  let originalWarn;
+  let logs;
+  let warnings;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-test-update-flow-"));
+    cwd = process.cwd();
+    process.chdir(tmpDir);
+    logs = [];
+    warnings = [];
+    originalLog = console.log;
+    originalWarn = console.warn;
+    console.log = (message) => logs.push(message);
+    console.warn = (message) => warnings.push(message);
+  });
+
+  afterEach(() => {
+    console.log = originalLog;
+    console.warn = originalWarn;
+    process.chdir(cwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  async function runUpdate(options = {}, tarballFiles = {}) {
+    const tarball = createTarball(tmpDir, tarballFiles);
+    await update(options, {
+      fetchText: async () => "kntic-bootstrap-v1.2.3.tar.gz",
+      download: async (_url, dest) => fs.copyFileSync(tarball, dest),
+    });
+  }
+
+  it("replaces kntic.yml by default and creates a backup", async () => {
+    fs.writeFileSync("kntic.yml", "services:\n  app:\n    image: old\n");
+    fs.writeFileSync(".kntic.env", "UID=1000\n");
+
+    await runUpdate({}, {
+      ".kntic/lib/orchestrator.py": "# new lib\n",
+      ".kntic/adrs/ADR-001.md": "# adr\n",
+      ".kntic.env": "UID=1000\nNEW_VAR=yes\n",
+      "kntic.yml": "services:\n  app:\n    image: new\n",
+    });
+
+    assert.equal(fs.readFileSync("kntic.yml", "utf8"), "services:\n  app:\n    image: new\n");
+    assert.equal(fs.readFileSync("kntic.yml.bak", "utf8"), "services:\n  app:\n    image: old\n");
+    assert.ok(logs.includes("Backing up kntic.yml → kntic.yml.bak"));
+    assert.ok(logs.includes("Updated kntic.yml from bootstrap template."));
+  });
+
+  it("prints one deprecation warning for --compose without doing duplicate compose work", async () => {
+    fs.writeFileSync("kntic.yml", "services:\n  app:\n    image: old\n");
+    fs.writeFileSync(".kntic.env", "UID=1000\n");
+
+    await runUpdate({ compose: true }, {
+      ".kntic/lib/orchestrator.py": "# new lib\n",
+      ".kntic/adrs/ADR-001.md": "# adr\n",
+      ".kntic.env": "UID=1000\n",
+      "kntic.yml": "services:\n  app:\n    image: new\n",
+    });
+
+    assert.deepEqual(warnings, [
+      "Warning: --compose is deprecated because kntic.yml is now included in the default update path.",
+    ]);
+    assert.equal(
+      logs.filter((message) => message === "Backing up kntic.yml → kntic.yml.bak").length,
+      1,
+      "compose backup must run only once"
+    );
+    assert.equal(
+      logs.filter((message) => message === "Updated kntic.yml from bootstrap template.").length,
+      1,
+      "compose extraction must run only once"
+    );
+  });
+
+  it("keeps --lib-only strict and skips kntic.yml replacement", async () => {
+    fs.writeFileSync("kntic.yml", "services:\n  app:\n    image: old\n");
+    fs.writeFileSync(".kntic.env", "UID=1000\n");
+
+    await runUpdate({ libOnly: true }, {
+      ".kntic/lib/orchestrator.py": "# new lib\n",
+      ".kntic/adrs/ADR-001.md": "# adr\n",
+      ".kntic.env": "UID=1000\nNEW_VAR=yes\n",
+      "kntic.yml": "services:\n  app:\n    image: new\n",
+    });
+
+    assert.equal(fs.readFileSync("kntic.yml", "utf8"), "services:\n  app:\n    image: old\n");
+    assert.ok(!fs.existsSync("kntic.yml.bak"), "backup must not be created in lib-only mode");
+    assert.equal(fs.readFileSync(".kntic.env", "utf8"), "UID=1000\nKNTIC_VERSION=1.2.3\n");
+    assert.equal(
+      logs.filter((message) => message === "Updated kntic.yml from bootstrap template.").length,
+      0,
+      "compose extraction must be skipped in lib-only mode"
+    );
+  });
+
+  it("does not replace kntic.yml for --lib-only --compose, but warns clearly", async () => {
+    fs.writeFileSync("kntic.yml", "services:\n  app:\n    image: old\n");
+    fs.writeFileSync(".kntic.env", "UID=1000\n");
+
+    await runUpdate({ libOnly: true, compose: true }, {
+      ".kntic/lib/orchestrator.py": "# new lib\n",
+      ".kntic/adrs/ADR-001.md": "# adr\n",
+      ".kntic.env": "UID=1000\nNEW_VAR=yes\n",
+      "kntic.yml": "services:\n  app:\n    image: new\n",
+    });
+
+    assert.equal(fs.readFileSync("kntic.yml", "utf8"), "services:\n  app:\n    image: old\n");
+    assert.ok(!fs.existsSync("kntic.yml.bak"), "backup must not be created in lib-only mode");
+    assert.deepEqual(warnings, [
+      "Warning: --compose is deprecated because kntic.yml is now included in the default update path.",
+    ]);
+    assert.ok(logs.includes("Info: --lib-only skips kntic.yml updates."));
+    assert.equal(
+      logs.filter((message) => message === "Updated kntic.yml from bootstrap template.").length,
+      0,
+      "compose extraction must still be skipped when --compose is combined with --lib-only"
+    );
+  });
+});
+
+describe("usage", () => {
+  it("documents kntic.yml as part of the default update path and marks --compose deprecated", () => {
+    const originalLog = console.log;
+    const lines = [];
+    console.log = (message) => lines.push(message);
+
+    try {
+      usage();
+    } finally {
+      console.log = originalLog;
+    }
+
+    assert.ok(lines.some((line) => line.includes("and kntic.yml")), "usage must mention default kntic.yml updates");
+    assert.ok(lines.some((line) => line.includes("--compose") && line.includes("Deprecated alias")), "usage must mark --compose deprecated");
+    assert.ok(lines.some((line) => line.includes("--lib-only") && line.includes("kntic.yml")), "usage must explain that --lib-only skips kntic.yml");
+  });
+});
+
 describe("extractCompose", () => {
   let tmpDir;
   let destDir;

package/src/commands/usage.js

@@ -7,13 +7,14 @@ function usage() {
   console.log("  usage    List all available sub-commands");
   console.log("  init     Download and extract the KNTIC bootstrap template into the current directory");
   console.log("             --interactive   Default mode — walk through .kntic.env values interactively (-i)");
-  console.log("             --quick         Non-interactive mode, auto-detects git remote only (-q)");
+  console.log("             --quick         Non-interactive mode, auto-detects git remote info and compose provider (-q)");
   console.log("  start    Build and start KNTIC services via docker compose (uses kntic.yml + .kntic.env)");
-  console.log("             --screen   Run inside a GNU screen session");
+  console.log("             --screen   Run inside a GNU screen session wrapper");
+  console.log("             --tmux     Run inside a tmux session wrapper (alternative to --screen)");
   console.log("  stop     Stop KNTIC services via docker compose");
-  console.log("  update   Download the latest KNTIC bootstrap and update .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, .kntic/hooks/gia/specific (if new), and .kntic/gia/weights.json");
-  console.log("             --lib-only   Update only .kntic/lib (skip adrs, hooks, and weights)");
-  console.log("             --compose    Also replace kntic.yml from the bootstrap template (backs up to kntic.yml.bak)");
+  console.log("  update   Download the latest KNTIC bootstrap and update .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, .kntic/hooks/gia/specific (if new), .kntic/gia/weights.json, and kntic.yml");
+  console.log("             --lib-only   Update only .kntic/lib (skips adrs, hooks, env merge, weights, and kntic.yml)");
+  console.log("             --compose    Deprecated alias; kntic.yml is already included in the default update path");
   console.log("");
 }