@kntic/kntic 0.4.7 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kntic/kntic",
-  "version": "0.4.7",
+  "version": "0.5.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

@@ -30,7 +30,10 @@ if (!subcommand || subcommand === "usage") {
     process.exit(1);
   }
 } else if (subcommand === "update") {
-  const updateOpts = { libOnly: args.includes("--lib-only") };
+  const updateOpts = {
+    libOnly: args.includes("--lib-only"),
+    compose: args.includes("--compose"),
+  };
   commands.update(updateOpts).catch((err) => {
     console.error(`Error: ${err.message}`);
     process.exit(1);

package/src/commands/update.js

@@ -189,6 +189,8 @@ function extractLibOnly(tarball, destDir) {
  * - .kntic/lib and .kntic/adrs are **replaced** (cleared first, then extracted).
  * - .kntic/hooks/gia/internal is **updated** (existing files are overwritten or new files
  *   added, but files not present in the archive are preserved).
+ * - .kntic/hooks/gia/specific is **extracted only if the directory does not already exist**
+ *   (one-time bootstrap; user customizations are never overwritten).
  * - .kntic/gia/weights.json is **replaced** if present in the archive.
  *
  * @param {string} tarball  – path to the .tar.gz file
@@ -198,6 +200,7 @@ function extractUpdate(tarball, destDir) {
   const libDir = path.join(destDir, ".kntic", "lib");
   const adrsDir = path.join(destDir, ".kntic", "adrs");
   const giaInternalDir = path.join(destDir, ".kntic", "hooks", "gia", "internal");
+  const giaSpecificDir = path.join(destDir, ".kntic", "hooks", "gia", "specific");
   const giaDir = path.join(destDir, ".kntic", "gia");
 
   // Ensure target directories exist
@@ -211,6 +214,7 @@ function extractUpdate(tarball, destDir) {
   clearDirectory(adrsDir);
 
   // Note: gia/internal hooks are NOT cleared — update semantics (overwrite/add, preserve others)
+  // Note: gia/specific hooks are only extracted if the directory does NOT already exist
   // Note: gia is NOT cleared — only weights.json is replaced
 
   // Extract .kntic/lib/ and .kntic/adrs/ (guaranteed to be in the archive)
@@ -229,6 +233,20 @@ function extractUpdate(tarball, destDir) {
     // No .kntic/hooks/gia/internal/ in the archive — that's fine
   }
 
+  // Extract .kntic/hooks/gia/specific/ only if it does not already exist on disk.
+  // This is a one-time bootstrap — once the user has specific hooks, they are never
+  // overwritten by update.
+  if (!fs.existsSync(giaSpecificDir)) {
+    try {
+      execSync(
+        `tar xzf "${tarball}" -C "${destDir}" "./.kntic/hooks/gia/specific/"`,
+        { stdio: "pipe" }
+      );
+    } catch (_) {
+      // No .kntic/hooks/gia/specific/ in the archive — that's fine
+    }
+  }
+
   // Extract .kntic/gia/weights.json separately — archive may not contain it
   try {
     execSync(
@@ -240,6 +258,153 @@ function extractUpdate(tarball, destDir) {
   }
 }
 
+/**
+ * Parse an env file into an ordered list of entries.
+ * Each entry is either:
+ *   { type: "comment", lines: ["# ...", "# ..."] }
+ *   { type: "variable", key: "KEY", line: "KEY=VALUE", commentLines: [] }
+ *   { type: "blank", lines: [""] }
+ *
+ * Comment lines immediately preceding a variable are attached to that variable.
+ */
+function parseEnvEntries(content) {
+  const rawLines = content.split("\n");
+  // Remove trailing empty string from final newline
+  if (rawLines.length > 0 && rawLines[rawLines.length - 1] === "") {
+    rawLines.pop();
+  }
+
+  const entries = [];
+  let pendingComments = [];
+
+  for (const line of rawLines) {
+    if (line === "" || (line.trim() === "" && !line.startsWith("#"))) {
+      // Blank line — if we're accumulating comments, treat blanks between
+      // comments as part of the comment block
+      pendingComments.push(line);
+    } else if (line.startsWith("#")) {
+      pendingComments.push(line);
+    } else {
+      // Variable line — KEY=VALUE (possibly with trailing comment)
+      const eqIdx = line.indexOf("=");
+      if (eqIdx !== -1) {
+        const key = line.substring(0, eqIdx).trim();
+        entries.push({
+          type: "variable",
+          key,
+          line,
+          commentLines: pendingComments.length > 0 ? [...pendingComments] : [],
+        });
+        pendingComments = [];
+      } else {
+        // Unknown line — treat as comment
+        pendingComments.push(line);
+      }
+    }
+  }
+
+  // Any trailing comments/blanks that didn't precede a variable
+  if (pendingComments.length > 0) {
+    entries.push({ type: "comment", lines: pendingComments });
+  }
+
+  return entries;
+}
+
+/**
+ * Extract the set of variable keys from parsed entries.
+ */
+function extractKeys(entries) {
+  const keys = new Set();
+  for (const entry of entries) {
+    if (entry.type === "variable") {
+      keys.add(entry.key);
+    }
+  }
+  return keys;
+}
+
+/**
+ * Merge new environment variables from a template .kntic.env into the user's .kntic.env.
+ *
+ * - Variables that exist in the user's file are never overwritten.
+ * - Variables in the template that are missing from the user's file are appended,
+ *   along with any preceding comment lines from the template.
+ *
+ * @param {string} templatePath – path to the template .kntic.env (from archive)
+ * @param {string} userEnvPath  – path to the user's .kntic.env
+ * @returns {string[]} list of newly added variable keys
+ */
+function mergeEnvFile(templatePath, userEnvPath) {
+  const templateContent = fs.readFileSync(templatePath, "utf8");
+  const templateEntries = parseEnvEntries(templateContent);
+
+  let userContent = "";
+  if (fs.existsSync(userEnvPath)) {
+    userContent = fs.readFileSync(userEnvPath, "utf8");
+  }
+
+  const userKeys = extractKeys(parseEnvEntries(userContent));
+  const newVars = [];
+
+  // Build the block to append
+  let appendBlock = "";
+
+  for (const entry of templateEntries) {
+    if (entry.type !== "variable") continue;
+    if (userKeys.has(entry.key)) continue;
+
+    // This is a new variable — append its comment lines + variable line
+    newVars.push(entry.key);
+
+    if (entry.commentLines.length > 0) {
+      appendBlock += entry.commentLines.join("\n") + "\n";
+    }
+    appendBlock += entry.line + "\n";
+  }
+
+  if (newVars.length === 0) {
+    console.log(".kntic.env is up to date.");
+    return newVars;
+  }
+
+  // Ensure user file ends with a newline before appending
+  let separator = "";
+  if (userContent.length > 0 && !userContent.endsWith("\n")) {
+    separator = "\n";
+  }
+  // Add blank line separator if user file doesn't end with a blank line
+  if (userContent.length > 0 && !userContent.endsWith("\n\n") && !(userContent.endsWith("\n") && userContent.length === 0)) {
+    separator += "\n";
+  }
+
+  fs.writeFileSync(userEnvPath, userContent + separator + appendBlock);
+
+  console.log(`Added new environment variables to .kntic.env: ${newVars.join(", ")}`);
+  return newVars;
+}
+
+/**
+ * Extract kntic.yml from the bootstrap archive, backing up any existing copy.
+ *
+ * @param {string} tarball  – path to the .tar.gz file
+ * @param {string} destDir  – target directory (usually ".")
+ */
+function extractCompose(tarball, destDir) {
+  const composePath = path.join(destDir, "kntic.yml");
+  // Backup existing
+  if (fs.existsSync(composePath)) {
+    fs.copyFileSync(composePath, composePath + ".bak");
+    console.log("Backing up kntic.yml → kntic.yml.bak");
+  }
+  // Extract from archive
+  execSync(
+    `tar xzf "${tarball}" -C "${destDir}" "./kntic.yml"`,
+    { stdio: "pipe" }
+  );
+  console.log("Updated kntic.yml from bootstrap template.");
+}
+
 async function update(options = {}) {
   const libOnly = options.libOnly || false;
 
@@ -256,10 +421,42 @@ async function update(options = {}) {
     console.log("Updating .kntic/lib …");
     extractLibOnly(tmpFile, ".");
   } else {
-    console.log("Updating .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, and .kntic/gia/weights.json …");
+    console.log("Updating .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, .kntic/hooks/gia/specific (if new), and .kntic/gia/weights.json …");
     extractUpdate(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-"));
+    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 {
+        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 });
+    }
+  } finally {
+    try { fs.unlinkSync(tmpEnvTemplate); } catch (_) {}
+  }
+
+  // Replace kntic.yml from archive if --compose flag is set
+  if (options.compose) {
+    try {
+      extractCompose(tmpFile, ".");
+    } catch (_) {
+      console.log("No kntic.yml in archive, skipping compose update.");
+    }
+  }
+
   // Update KNTIC_VERSION in .kntic.env
   updateEnvVersion(version);
 
@@ -270,13 +467,15 @@ 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, and .kntic/gia/weights.json updated successfully.");
+    console.log("Done. .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, .kntic/hooks/gia/specific (if new), and .kntic/gia/weights.json updated successfully.");
   }
 }
 
 module.exports = update;
 module.exports.extractLibOnly = extractLibOnly;
 module.exports.extractUpdate = extractUpdate;
+module.exports.extractCompose = extractCompose;
 module.exports.extractVersion = extractVersion;
 module.exports.clearDirectory = clearDirectory;
 module.exports.updateEnvVersion = updateEnvVersion;
+module.exports.mergeEnvFile = mergeEnvFile;

package/src/commands/update.test.js

@@ -7,7 +7,7 @@ const path = require("path");
 const os = require("os");
 const { execSync } = require("child_process");
 
-const { extractLibOnly, extractUpdate, extractVersion, clearDirectory, updateEnvVersion } = require("./update");
+const { extractLibOnly, extractUpdate, extractCompose, extractVersion, clearDirectory, updateEnvVersion, mergeEnvFile } = require("./update");
 
 /**
  * Helper — create a tar.gz archive in `tmpDir` containing the given files.
@@ -408,6 +408,75 @@ describe("extractUpdate", () => {
     );
   });
 
+  it("extracts .kntic/hooks/gia/specific when the directory does not exist", () => {
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+      ".kntic/adrs/ADR-001.md": "# ADR 001\n",
+      ".kntic/hooks/gia/specific/my-hook.sh": "#!/bin/sh\necho specific\n",
+      ".kntic/hooks/gia/specific/another.sh": "#!/bin/sh\necho another\n",
+    });
+
+    // specific dir does not exist yet
+    const specificDir = path.join(destDir, ".kntic", "hooks", "gia", "specific");
+    assert.ok(!fs.existsSync(specificDir), "specific dir must not exist before extraction");
+
+    extractUpdate(tarball, destDir);
+
+    // specific hooks must be extracted
+    assert.equal(
+      fs.readFileSync(path.join(specificDir, "my-hook.sh"), "utf8"),
+      "#!/bin/sh\necho specific\n"
+    );
+    assert.equal(
+      fs.readFileSync(path.join(specificDir, "another.sh"), "utf8"),
+      "#!/bin/sh\necho another\n"
+    );
+  });
+
+  it("does NOT overwrite .kntic/hooks/gia/specific when the directory already exists", () => {
+    const specificDir = path.join(destDir, ".kntic", "hooks", "gia", "specific");
+    fs.mkdirSync(specificDir, { recursive: true });
+    fs.writeFileSync(path.join(specificDir, "custom.sh"), "#!/bin/sh\necho custom\n");
+
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+      ".kntic/adrs/ADR-001.md": "# ADR 001\n",
+      ".kntic/hooks/gia/specific/my-hook.sh": "#!/bin/sh\necho from-archive\n",
+    });
+
+    extractUpdate(tarball, destDir);
+
+    // User's custom hook must be preserved
+    assert.equal(
+      fs.readFileSync(path.join(specificDir, "custom.sh"), "utf8"),
+      "#!/bin/sh\necho custom\n",
+      "user's custom specific hook must be preserved"
+    );
+
+    // Archive's specific hook must NOT be extracted
+    assert.ok(
+      !fs.existsSync(path.join(specificDir, "my-hook.sh")),
+      "archive specific hook must not be extracted when directory already exists"
+    );
+  });
+
+  it("works when archive has no .kntic/hooks/gia/specific and directory does not exist", () => {
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+      ".kntic/adrs/ADR-001.md": "# ADR 001\n",
+    });
+
+    // Should not throw
+    extractUpdate(tarball, destDir);
+
+    // specific dir should not be created
+    const specificDir = path.join(destDir, ".kntic", "hooks", "gia", "specific");
+    assert.ok(
+      !fs.existsSync(specificDir),
+      "specific dir must not be created when not in archive"
+    );
+  });
+
   it("preserves files outside .kntic/lib, .kntic/adrs, and .kntic/hooks/gia/internal", () => {
     const knticDir = path.join(destDir, ".kntic");
     fs.mkdirSync(knticDir, { recursive: true });
@@ -504,3 +573,274 @@ describe("extractVersion (update module)", () => {
     assert.throws(() => extractVersion("no-version-here.tar.gz"));
   });
 });
+
+describe("mergeEnvFile", () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-test-merge-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("appends new keys and their preceding comments from the template", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, [
+      "# Existing var",
+      "UID=1000",
+      "",
+      "# Project prefix used for naming",
+      "KNTIC_PRJ_PREFIX=myproject",
+      "",
+      "# UI port for the dashboard",
+      "KNTIC_UI_PORT=8080",
+      "",
+    ].join("\n"));
+
+    fs.writeFileSync(userPath, "UID=5000\n");
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, ["KNTIC_PRJ_PREFIX", "KNTIC_UI_PORT"]);
+
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("UID=5000"), "existing var must be preserved");
+    assert.ok(content.includes("# Project prefix used for naming"), "comment for new var must be included");
+    assert.ok(content.includes("KNTIC_PRJ_PREFIX=myproject"), "new var must be appended");
+    assert.ok(content.includes("# UI port for the dashboard"), "comment for second new var must be included");
+    assert.ok(content.includes("KNTIC_UI_PORT=8080"), "second new var must be appended");
+  });
+
+  it("preserves user keys not in the template", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, "UID=1000\n");
+    fs.writeFileSync(userPath, "UID=5000\nMY_CUSTOM_VAR=hello\n");
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, []);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("MY_CUSTOM_VAR=hello"), "user's extra key must be preserved");
+    assert.ok(content.includes("UID=5000"), "existing var must be preserved");
+  });
+
+  it("does not overwrite overlapping keys — user's value wins", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, "UID=1000\nGID=1000\n");
+    fs.writeFileSync(userPath, "UID=5000\nGID=5000\n");
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, []);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("UID=5000"), "user's UID must be preserved");
+    assert.ok(content.includes("GID=5000"), "user's GID must be preserved");
+    assert.ok(!content.includes("UID=1000"), "template UID must not appear");
+    assert.ok(!content.includes("GID=1000"), "template GID must not appear");
+  });
+
+  it("writes all template entries when user file does not exist", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, [
+      "# User ID",
+      "UID=1000",
+      "# Group ID",
+      "GID=1000",
+      "",
+    ].join("\n"));
+
+    // user file does not exist
+    assert.ok(!fs.existsSync(userPath));
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, ["UID", "GID"]);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("# User ID"), "comment must be included");
+    assert.ok(content.includes("UID=1000"), "UID must be written");
+    assert.ok(content.includes("# Group ID"), "comment must be included");
+    assert.ok(content.includes("GID=1000"), "GID must be written");
+  });
+
+  it("includes comment lines that immediately precede a new key", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, [
+      "UID=1000",
+      "",
+      "# Branch strategy for the project",
+      "# Allowed values: trunk, gitflow",
+      "KNTIC_BRANCH_STRATEGY=trunk",
+      "",
+    ].join("\n"));
+
+    fs.writeFileSync(userPath, "UID=5000\n");
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, ["KNTIC_BRANCH_STRATEGY"]);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("# Branch strategy for the project"), "first comment line must be included");
+    assert.ok(content.includes("# Allowed values: trunk, gitflow"), "second comment line must be included");
+    assert.ok(content.includes("KNTIC_BRANCH_STRATEGY=trunk"), "new var must be appended");
+  });
+
+  it("leaves file unchanged when there are no new keys", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, "UID=1000\nGID=1000\n");
+    fs.writeFileSync(userPath, "UID=5000\nGID=5000\n");
+
+    const originalContent = fs.readFileSync(userPath, "utf8");
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, []);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.equal(content, originalContent, "file must not be modified");
+  });
+
+  it("writes all template entries when user file is empty", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, "# Port\nPORT=3000\n");
+    fs.writeFileSync(userPath, "");
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, ["PORT"]);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("# Port"), "comment must be included");
+    assert.ok(content.includes("PORT=3000"), "variable must be written");
+  });
+});
+
+describe("extractCompose", () => {
+  let tmpDir;
+  let destDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-test-compose-"));
+    destDir = path.join(tmpDir, "dest");
+    fs.mkdirSync(destDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("extracts kntic.yml from archive", () => {
+    const composeContent = "services:\n  dashboard:\n    image: kntic/dashboard:latest\n";
+    const tarball = createTarball(tmpDir, {
+      "kntic.yml": composeContent,
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+    });
+
+    extractCompose(tarball, destDir);
+
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml"), "utf8"),
+      composeContent,
+      "kntic.yml content must match archive"
+    );
+  });
+
+  it("creates .bak backup of existing kntic.yml", () => {
+    const oldContent = "services:\n  dashboard:\n    image: old:v1\n";
+    const newContent = "services:\n  dashboard:\n    image: new:v2\n";
+    fs.writeFileSync(path.join(destDir, "kntic.yml"), oldContent);
+
+    const tarball = createTarball(tmpDir, {
+      "kntic.yml": newContent,
+    });
+
+    extractCompose(tarball, destDir);
+
+    // Backup must contain old content
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml.bak"), "utf8"),
+      oldContent,
+      "backup must contain previous content"
+    );
+    // New file must contain archive content
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml"), "utf8"),
+      newContent,
+      "kntic.yml must be replaced with archive content"
+    );
+  });
+
+  it("overwrites existing .bak file", () => {
+    const veryOldContent = "services:\n  old: true\n";
+    const oldContent = "services:\n  current: true\n";
+    const newContent = "services:\n  new: true\n";
+
+    fs.writeFileSync(path.join(destDir, "kntic.yml.bak"), veryOldContent);
+    fs.writeFileSync(path.join(destDir, "kntic.yml"), oldContent);
+
+    const tarball = createTarball(tmpDir, {
+      "kntic.yml": newContent,
+    });
+
+    extractCompose(tarball, destDir);
+
+    // .bak must now have the oldContent (not veryOldContent)
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml.bak"), "utf8"),
+      oldContent,
+      "backup must be overwritten with latest previous content"
+    );
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml"), "utf8"),
+      newContent,
+      "kntic.yml must contain archive content"
+    );
+  });
+
+  it("works when no existing kntic.yml on disk", () => {
+    const newContent = "services:\n  dashboard:\n    image: kntic/dashboard:latest\n";
+    const tarball = createTarball(tmpDir, {
+      "kntic.yml": newContent,
+    });
+
+    // No kntic.yml exists
+    assert.ok(!fs.existsSync(path.join(destDir, "kntic.yml")));
+
+    extractCompose(tarball, destDir);
+
+    // File must be extracted
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml"), "utf8"),
+      newContent,
+      "kntic.yml must be extracted from archive"
+    );
+    // No backup should exist
+    assert.ok(
+      !fs.existsSync(path.join(destDir, "kntic.yml.bak")),
+      "no backup must be created when original did not exist"
+    );
+  });
+
+  it("throws when archive has no kntic.yml", () => {
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+    });
+
+    assert.throws(
+      () => extractCompose(tarball, destDir),
+      "must throw when archive does not contain kntic.yml"
+    );
+  });
+});

package/src/commands/usage.js

@@ -9,8 +9,9 @@ function usage() {
   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("  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, and .kntic/gia/weights.json");
-  console.log("             --lib-only   Update only .kntic/lib (skip .kntic/adrs, .kntic/hooks/gia/internal, and .kntic/gia/weights.json)");
+  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("");
 }