@daldindev/agentic-skills 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ The format is based on Keep a Changelog and this project follows Semantic Versio
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-05
+
+### Added
+
+- `update` and `sync` now keep both changes when a local edit and an upstream change never wrote in the same place, instead of freezing the file for either. A file is only ever combined when the version it was installed from can be read and hashes to exactly what the manifest recorded, and only when no two changes touch; otherwise it stays frozen, exactly as before. Nothing local is ever dropped to make a merge possible, and no file is left half-combined.
+- `--no-merge` turns that off, leaving every edited file frozen the way earlier versions did.
+- `agentic-skills diff`: for every file a local edit froze, compares three versions - the commit you installed from, your copy, and current upstream - so every difference has a known author. Without a path it lists the frozen files and says whether each is blocked by a real overlap or only by the per-file rule; with a path it prints all three versions of every changed region. Nothing is written, and nothing is merged.
+- `--base-archive` supplies the version you installed from as a local tarball or URL, instead of downloading the commit recorded in the manifest. Used by `update`, `sync`, and `diff`.
+
+### Fixed
+
+- The manifest no longer advances the recorded hash of a file that was skipped. Nothing was written to that file, so the version it descends from has not changed; recording the newer one made it look as though the user had deleted an upstream change they had merely not taken yet.
+
+## [0.2.0] - 2026-09-05
+
+### Added
+
+- `agentic-skills sync`: installs when the target is missing and updates when it is already there, so one command covers both states. It is the command for a `postinstall` hook, a CI step, or a container build, where the run cannot stop to ask which state it is in. Local edits are preserved as with `update`; `--force` overwrites them, so exit code 2 cannot happen.
+
+### Changed
+
+- The note about a missing manifest is printed only when files were actually skipped, and now appears for every command rather than only `update`.
+- The error `init` raises on a non-empty target points at `sync` for unattended runs.
+
 ## [0.1.0] - 2026-09-03
 
 ### Added

package/README.md

@@ -31,7 +31,7 @@ npx agentic-skills init
 Requirements:
 
 - Node.js `>=20.11`
-- Network access to `codeload.github.com`, where GitHub serves source archives, when you run `init` or `update`
+- Network access to `codeload.github.com`, where GitHub serves source archives, when you run `init`, `update`, `sync`, or `diff`
 
 ## Quick Start
 
@@ -55,7 +55,9 @@ Point your assistant at `.agents/ARCHITECTURE.md`. It lists every component with
 | --- | --- |
 | `agentic-skills init` | Download ag-kit and install the content. Refuses a non-empty target unless `--force` |
 | `agentic-skills update` | Download ag-kit again and update installed files, keeping the ones you edited |
+| `agentic-skills sync` | Install if missing, update if present. One command that works in both states, for unattended runs |
 | `agentic-skills status` | Show what is installed, from which upstream commit, and which files were changed locally |
+| `agentic-skills diff` | Show why your edits froze a file, and what they are holding back |
 
 | Option | Purpose |
 | --- | --- |
@@ -63,7 +65,9 @@ Point your assistant at `.agents/ARCHITECTURE.md`. It lists every component with
 | `-d, --dir <name>` | Install directory inside the project, default `.agents` |
 | `-r, --ref <git-ref>` | Upstream branch, tag, or commit to install, default `main` |
 | `--archive <source>` | Install from a local ag-kit `.tar.gz` or a URL instead of GitHub |
+| `--base-archive <source>` | The version you installed from, instead of downloading the commit in the manifest |
 | `-f, --force` | Overwrite files that were modified locally |
+| `--no-merge` | Never combine a local edit with an upstream change; leave every edited file frozen |
 | `--dry-run` | Download and print the plan without writing anything |
 | `--json` | Print machine-readable output |
 
@@ -82,16 +86,51 @@ For each file it compares what is installed, what upstream now has, and the hash
 | Situation | Result |
 | --- | --- |
 | You never touched the file | Updated, or deleted when upstream dropped it |
-| You edited the file | Skipped and listed, unless `--force` |
+| You edited it somewhere upstream did not | Both changes kept |
+| You edited it where upstream also changed it | Skipped and listed, unless `--force` |
 | You created the file yourself | Never touched |
 | Upstream added a file | Installed |
 
+Both are only kept when the two changes can be told apart and never touch. Anywhere they do touch, or where the version you installed from cannot be read, the file stays frozen instead. **Nothing you wrote is ever dropped to make that work**, and a file is never left half-combined: it is reconciled whole or left exactly as it was. `--no-merge` turns the attempt off entirely.
+
+`diff` shows what a skipped file is holding back, and whose text is whose. It reads three versions — the commit you installed from, your copy, and current upstream — so every difference has a known author:
+
+```bash
+npx @daldindev/agentic-skills diff
+```
+
+That lists the frozen files and what each one is stuck on. Pass a path to see the three versions of every changed region in one file.
+
+Nothing is written and nothing is merged, so the decision stays yours: fold the upstream change in by hand, or take upstream and lose your edit with `--force`. Until you do one or the other, that file sits out every update.
+
 To stay on a known upstream state instead of `main`, pass a tag or commit. The same flag reproduces an earlier install exactly:
 
 ```bash
 npx @daldindev/agentic-skills update --ref v2026.8.31
 ```
 
+### Unattended runs
+
+`sync` reconciles the install against upstream whatever state it is in: it creates the directory when it is missing and updates it when it is already there. Nothing has to be known about the target beforehand, which is what makes it the command to put where no one is watching — a `postinstall` hook, a CI step, a container build:
+
+```json
+{
+  "scripts": {
+    "postinstall": "agentic-skills sync"
+  }
+}
+```
+
+Every `npm i` then brings the install to the current upstream, on a fresh clone and on a checkout that already has the content alike.
+
+Your edits survive it: a file you changed is kept, listed, and the command exits `2`. Reach for `--force` only when the install is a derived tree your project regenerates and never edits by hand, `.agents/` in `.gitignore` for instance:
+
+```bash
+agentic-skills sync --force
+```
+
+Copying that second line into a project where `.agents/` is committed means losing an edited skill on every `npm i`, silently. And `--force` only removes exit `2`: a download that cannot reach GitHub still exits `1`.
+
 ## What gets installed
 
 | Upstream path | Installed as |
@@ -127,6 +166,7 @@ In scope:
 - Downloading the upstream roles, skills, and workflows and installing them anywhere
 - Updating an install while preserving local edits
 - Recording upstream provenance with every install
+- Running unattended, from a postinstall hook or a CI step, with one command that works in either state
 
 Out of scope:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daldindev/agentic-skills",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Install the ag-kit agent roles, skills, and workflows into any project, for any model and any agent harness.",
   "author": "daldindev",
   "license": "MIT",

package/src/cli.mjs

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { PACKAGE_ROOT, readJson } from "./fs-utils.mjs";
-import { DEFAULT_INSTALL_DIR, init, status, update } from "./install.mjs";
+import { DEFAULT_INSTALL_DIR, init, inspect, status, sync, update } from "./install.mjs";
 import { UPSTREAM, extractPort, loadArchive, materialize } from "./upstream.mjs";
 
 const HELP = `agentic-skills - install the ag-kit agent roles, skills, and workflows into any project
@@ -12,14 +12,21 @@ const HELP = `agentic-skills - install the ag-kit agent roles, skills, and workf
 Usage:
   agentic-skills init    [options]   Download ag-kit and install the content into <path>/<dir>
   agentic-skills update  [options]   Download ag-kit again and update installed files, preserving local edits
+  agentic-skills sync    [options]   Install if missing, update if present; safe to run unattended
   agentic-skills status  [options]   Show what is installed and which files were changed locally
+  agentic-skills diff    [path]      Show why your edits froze a file, and what they are holding back
 
 Options:
   -p, --path <dir>        Project directory (default: current directory)
   -d, --dir <name>        Install directory inside the project (default: ${DEFAULT_INSTALL_DIR})
   -r, --ref <git-ref>     Upstream branch, tag, or commit to install (default: ${UPSTREAM.ref})
       --archive <source>  Install from a local ag-kit .tar.gz or a URL instead of GitHub
+      --base-archive <s>  The version you installed from, as a local .tar.gz or URL, instead of
+                          downloading the commit in the manifest. Used to tell your changes
+                          from upstream's, by update, sync, and diff
   -f, --force             Overwrite locally modified files
+      --no-merge          Never combine a local edit with an upstream change; leave every
+                          edited file frozen, whether or not the two touch
       --dry-run           Download and show the plan without writing anything
       --json              Print machine-readable output
   -h, --help              Show this help
@@ -39,7 +46,9 @@ const { values, positionals } = parseArgs({
     dir: { type: "string", short: "d" },
     ref: { type: "string", short: "r", default: UPSTREAM.ref },
     archive: { type: "string" },
+    "base-archive": { type: "string" },
     force: { type: "boolean", short: "f", default: false },
+    "no-merge": { type: "boolean", default: false },
     "dry-run": { type: "boolean", default: false },
     json: { type: "boolean", default: false },
     help: { type: "boolean", short: "h", default: false },
@@ -58,10 +67,10 @@ const list = (label, items, format = (item) => item) => {
   for (const item of items) console.log(`  ${format(item)}`);
 };
 
-/** Download the upstream archive and lay the ported tree out in a temp dir. */
-const fetchIncoming = async () => {
-  log(values.archive ? `Reading ${values.archive}` : `Downloading ${UPSTREAM.repository} at ${values.ref}`);
-  const buffer = await loadArchive({ ref: values.ref, archive: values.archive });
+/** Download one upstream archive and lay the ported tree out in a temp dir. */
+const fetchTree = async ({ ref = null, archive = null }) => {
+  log(archive ? `Reading ${archive}` : `Downloading ${UPSTREAM.repository} at ${ref}`);
+  const buffer = await loadArchive({ ref, archive });
   const port = extractPort(buffer);
   const dir = await fs.mkdtemp(path.join(os.tmpdir(), "agentic-skills-"));
   try {
@@ -75,7 +84,7 @@ const fetchIncoming = async () => {
     dir,
     upstream: {
       repository: UPSTREAM.repository,
-      ref: values.archive ? null : values.ref,
+      ref: archive ? null : ref,
       commit: port.commit,
       version: port.version,
     },
@@ -83,6 +92,31 @@ const fetchIncoming = async () => {
   };
 };
 
+/**
+ * The version the install came from, so both sides of a local edit can be told
+ * apart. Called only once something is actually frozen, and never fatal: without
+ * it the run just stays as conservative as it was before.
+ *
+ * `--archive` means this run was asked not to reach for the network, so the base
+ * has to come from `--base-archive` or not at all.
+ */
+let loadedBase = null;
+const loadBase = async (manifest) => {
+  const archive = values["base-archive"];
+  if (!archive && values.archive) return null;
+
+  const commit = manifest?.upstream?.commit;
+  if (!archive && !commit) return null;
+
+  try {
+    loadedBase = await fetchTree(archive ? { archive } : { ref: commit });
+    return loadedBase;
+  } catch (error) {
+    console.error(`warning: could not read the version you installed from: ${error.message}`);
+    return null;
+  }
+};
+
 const describeUpstream = (upstream) => {
   if (!upstream) return "unknown upstream";
   const commit = upstream.commit ? ` (${upstream.commit.slice(0, 7)})` : "";
@@ -95,19 +129,101 @@ const printPlan = (result) => {
   console.log(`${prefix}${result.mode}: ${result.installDir}`);
   console.log(`${prefix}source: ${describeUpstream(result.upstream)}`);
   console.log(
-    `${prefix}added ${plan.add.length}, updated ${plan.update.length}, removed ${plan.remove.length}, ` +
-    `skipped ${plan.skip.length}, kept ${plan.keep.length}, unchanged ${plan.unchanged.length}`,
+    `${prefix}added ${plan.add.length}, updated ${plan.update.length}, merged ${plan.merge.length}, ` +
+    `removed ${plan.remove.length}, skipped ${plan.skip.length}, kept ${plan.keep.length}, ` +
+    `unchanged ${plan.unchanged.length}`,
   );
-  list("Skipped (modified locally; use --force to overwrite)", plan.skip, (item) => `${item.file}: ${item.reason}`);
+  list("Merged (your change and upstream's did not touch)", plan.merge, (item) => item.file);
+  list("Skipped (left frozen; use --force to overwrite)", plan.skip, (item) => `${item.file}: ${item.reason}`);
   list("Kept (removed upstream but modified locally)", plan.keep, (item) => `${item.file}: ${item.reason}`);
-  if (result.mode === "update" && result.hadManifest === false) {
+  if (result.hadManifest === false && plan.skip.length) {
     console.log("\nNo manifest was found, so files that differ from upstream were skipped. Re-run with --force to overwrite them.");
   }
-  if (result.mode === "init" && !result.dryRun) {
+  if (result.created && !result.dryRun) {
     console.log(`\nPoint your assistant at ${path.join(result.installDir, "ARCHITECTURE.md")} to get the inventory.`);
   }
 };
 
+const SIDE = { base: "base ", yours: "yours", upstream: "upstr" };
+const REGION_LINES = 20;
+const plural = (count, word) => `${count} ${count === 1 ? word : `${word}s`}`;
+
+const authorPhrase = (authors) => {
+  if (authors.length === 2) return "both sides wrote here";
+  return authors[0] === "yours" ? "only you wrote here" : "only upstream wrote here";
+};
+
+/** One side of a region. A bare `|` is a blank line; no `|` means the side has nothing here. */
+const printSide = (side, lines) => {
+  if (!lines.length) {
+    console.log(`      ${SIDE[side]}   nothing here`);
+    return;
+  }
+  for (const line of lines.slice(0, REGION_LINES)) console.log(`      ${SIDE[side]} | ${line}`);
+  const rest = lines.length - REGION_LINES;
+  if (rest > 0) console.log(`      ${SIDE[side]}   ~ ${plural(rest, "more line")} ~`);
+};
+
+const printDiffFile = (report, entry) => {
+  console.log(entry.file);
+  console.log(`  installed ${describeUpstream(report.base)} -> upstream ${describeUpstream(report.upstream)}`);
+  console.log(`  ${plural(entry.regions.length, "region")} changed, ${entry.collisions} written by both sides`);
+
+  entry.regions.forEach((region, index) => {
+    console.log(`\n  [${index + 1}] ${region.where.padEnd(38)} ${authorPhrase(region.authors)}`);
+    printSide("base", region.base);
+    printSide("yours", region.yours);
+    printSide("upstream", region.upstream);
+    if (region.authors.length === 2) {
+      console.log("\n      note: no untouched line separates your lines from upstream's here,");
+      console.log("            so neither side can be applied without deciding about the other.");
+    }
+  });
+
+  console.log("\ndiff only reads - nothing was written.");
+};
+
+const printDiffSummary = (report) => {
+  console.log(`diff:   ${report.installDir}`);
+  console.log(`source: ${describeUpstream(report.upstream)}`);
+  if (report.comparedAgainstBase) console.log(`base:   ${describeUpstream(report.base)}`);
+
+  const entries = [...report.frozen, ...report.removedUpstream];
+  if (!entries.length) {
+    console.log("\nNothing is frozen: every installed file either matches upstream, tracks it cleanly, or is your own.");
+    return;
+  }
+
+  const width = Math.max(...entries.map((entry) => entry.file.length));
+  if (!report.comparedAgainstBase) {
+    console.log(`\n${plural(entries.length, "frozen file")}, and no way to tell your changes from upstream's:`);
+    console.log(report.hadManifest
+      ? "the version this install came from could not be read. Pass --base-archive to supply it."
+      : "this install has no manifest saying which version it came from.");
+    for (const entry of entries) console.log(`  ${entry.file}`);
+    return;
+  }
+
+  const blocked = report.frozen.filter((entry) => entry.collisions > 0).length;
+  const byRule = report.frozen.length - blocked;
+  const parts = [];
+  if (blocked) parts.push(`${blocked} blocked by an overlap`);
+  if (byRule) parts.push(`${byRule} frozen by the per-file rule alone`);
+  if (report.removedUpstream.length) parts.push(`${report.removedUpstream.length} removed upstream`);
+
+  console.log(`\n${plural(entries.length, "frozen file")}. ${parts.join(", ")}.`);
+  console.log("diff only reads - nothing was written.\n");
+
+  for (const entry of report.frozen) {
+    const both = entry.collisions ? `${entry.collisions} written by both sides` : "none written by both sides";
+    console.log(`  ${entry.file.padEnd(width)}  ${plural(entry.regions.length, "region")} changed, ${both}`);
+  }
+  for (const entry of report.removedUpstream) {
+    console.log(`  ${entry.file.padEnd(width)}  removed upstream, kept because you edited it`);
+  }
+  console.log('\nRun "agentic-skills diff <path>" to see the three versions of one file.');
+};
+
 const printStatus = (info) => {
   console.log(`package:   ${info.package.packageName} ${info.package.packageVersion}`);
   console.log(`target:    ${info.installDir}`);
@@ -133,8 +249,9 @@ try {
     console.log(pkg.version);
   } else if (values.help || !command || command === "help") {
     process.stdout.write(HELP);
-  } else if (command === "init" || command === "update") {
-    const incoming = await fetchIncoming();
+  } else if (command === "init" || command === "update" || command === "sync") {
+    const merging = !values.force && !values["no-merge"];
+    const incoming = await fetchTree({ ref: values.ref, archive: values.archive });
     try {
       const options = {
         path: values.path,
@@ -142,14 +259,44 @@ try {
         force: values.force,
         dryRun: values["dry-run"],
         incomingDir: incoming.dir,
+        loadBase: merging ? loadBase : null,
         upstream: incoming.upstream,
       };
-      const result = command === "init" ? await init(options) : await update(options);
+      const run = { init, update, sync }[command];
+      const result = await run(options);
       if (values.json) console.log(JSON.stringify(result, null, 2));
       else printPlan(result);
       if (result.plan.skip.length || result.plan.keep.length) process.exitCode = 2;
     } finally {
       await incoming.cleanup();
+      if (loadedBase) await loadedBase.cleanup();
+    }
+  } else if (command === "diff") {
+    const target = { path: values.path, dir: values.dir };
+    const incoming = await fetchTree({ ref: values.ref, archive: values.archive });
+    try {
+      const report = await inspect({
+        ...target,
+        incomingDir: incoming.dir,
+        loadBase,
+        upstream: incoming.upstream,
+      });
+
+      const wanted = positionals[1]?.replaceAll("\\", "/");
+      if (values.json) console.log(JSON.stringify(report, null, 2));
+      else if (!wanted) printDiffSummary(report);
+      else {
+        const entry = report.frozen.find((item) => item.file === wanted);
+        if (entry?.regions) printDiffFile(report, entry);
+        else if (entry) console.error(`${wanted} is frozen, but the version you installed from could not be read.`);
+        else {
+          console.error(`${wanted} is not frozen. Run "agentic-skills diff" to list the files that are.`);
+          process.exitCode = 1;
+        }
+      }
+    } finally {
+      await incoming.cleanup();
+      if (loadedBase) await loadedBase.cleanup();
     }
   } else if (command === "status") {
     const info = await status({ path: values.path, dir: values.dir });

package/src/diff.mjs

@@ -0,0 +1,219 @@
+/**
+ * Three-way comparison of one file, used to explain why a local edit froze it.
+ *
+ * Everything is measured against the version the user installed from, so every
+ * difference has a known author: the installed tree changed it, upstream
+ * changed it, or both wrote in the same place. A two-way comparison cannot
+ * tell those apart, which is the whole reason this exists.
+ *
+ * Nothing here merges anything. It only describes.
+ */
+
+/** Above this many table cells the alignment degrades to "replaced wholesale". */
+const MAX_CELLS = 4_000_000;
+
+export const toLines = (text) => {
+  const lines = text.split(/\r?\n/);
+  if (lines.length && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+};
+
+const mark = (type) => (line) => ({ type, line });
+
+/** Longest common subsequence alignment of two line arrays. */
+function align(a, b) {
+  if (!a.length) return b.map(mark("add"));
+  if (!b.length) return a.map(mark("remove"));
+  if (a.length * b.length > MAX_CELLS) return [...a.map(mark("remove")), ...b.map(mark("add"))];
+
+  const width = b.length + 1;
+  const table = new Uint32Array((a.length + 1) * width);
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i * width + j] = a[i] === b[j]
+        ? table[(i + 1) * width + j + 1] + 1
+        : Math.max(table[(i + 1) * width + j], table[i * width + j + 1]);
+    }
+  }
+
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      ops.push({ type: "context", line: a[i] });
+      i++;
+      j++;
+    } else if (table[(i + 1) * width + j] >= table[i * width + j + 1]) {
+      ops.push({ type: "remove", line: a[i++] });
+    } else {
+      ops.push({ type: "add", line: b[j++] });
+    }
+  }
+  while (i < a.length) ops.push({ type: "remove", line: a[i++] });
+  while (j < b.length) ops.push({ type: "add", line: b[j++] });
+  return ops;
+}
+
+/**
+ * Compare two texts line by line. Identical head and tail are trimmed first,
+ * so an edit in one section does not pay for the rest of the file.
+ */
+export function diffLines(before, after) {
+  const a = toLines(before);
+  const b = toLines(after);
+
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA--;
+    endB--;
+  }
+
+  return [
+    ...a.slice(0, start).map(mark("context")),
+    ...align(a.slice(start, endA), b.slice(start, endB)),
+    ...a.slice(endA).map(mark("context")),
+  ];
+}
+
+/**
+ * Rewrite the comparison as an edit script against the base: a list of
+ * `[start, end)` base ranges and the lines that replace each one. An insertion
+ * is an empty range, which is what lets two insertions at the same point be
+ * recognised as the same place.
+ */
+function editsAgainstBase(baseLines, otherLines) {
+  // Trim the identical head and tail first, so a one-line change in a long file
+  // never pays for the whole file, and never trips the size cap in `align`.
+  let start = 0;
+  while (start < baseLines.length && start < otherLines.length && baseLines[start] === otherLines[start]) start++;
+
+  let endBase = baseLines.length;
+  let endOther = otherLines.length;
+  while (endBase > start && endOther > start && baseLines[endBase - 1] === otherLines[endOther - 1]) {
+    endBase--;
+    endOther--;
+  }
+
+  const ops = align(baseLines.slice(start, endBase), otherLines.slice(start, endOther));
+  const edits = [];
+  let index = start;
+  let current = null;
+
+  for (const op of ops) {
+    if (op.type === "context") {
+      if (current) edits.push(current);
+      current = null;
+      index++;
+      continue;
+    }
+    current ||= { start: index, end: index, lines: [] };
+    if (op.type === "remove") current.end = ++index;
+    else current.lines.push(op.line);
+  }
+  if (current) edits.push(current);
+
+  return edits;
+}
+
+/** Replay one side's edits over a slice of the base. */
+function applyEdits(baseLines, start, end, edits) {
+  const out = [];
+  let cursor = start;
+  for (const edit of edits) {
+    out.push(...baseLines.slice(cursor, edit.start));
+    out.push(...edit.lines);
+    cursor = edit.end;
+  }
+  out.push(...baseLines.slice(cursor, end));
+  return out;
+}
+
+/**
+ * Every place the two sides diverged from the base, with all three versions of
+ * that place and who wrote there.
+ *
+ * Ranges that touch are one region, the way a merge tool treats them: two
+ * changes with no untouched line between them cannot be applied independently.
+ */
+export function changedRegions({ base, yours, upstream }) {
+  const baseLines = toLines(base);
+  const sides = {
+    yours: editsAgainstBase(baseLines, toLines(yours)),
+    upstream: editsAgainstBase(baseLines, toLines(upstream)),
+  };
+
+  const all = Object.entries(sides)
+    .flatMap(([side, edits]) => edits.map((edit) => ({ ...edit, side })))
+    .sort((a, b) => a.start - b.start || a.end - b.end);
+
+  const grouped = [];
+  for (const edit of all) {
+    const last = grouped[grouped.length - 1];
+    if (last && edit.start <= last.end) {
+      last.end = Math.max(last.end, edit.end);
+      last.parts.push(edit);
+    } else {
+      grouped.push({ start: edit.start, end: edit.end, parts: [edit] });
+    }
+  }
+
+  return grouped.map((region) => {
+    const authors = [...new Set(region.parts.map((part) => part.side))].sort();
+    const partsFor = (side) => region.parts.filter((part) => part.side === side);
+    return {
+      baseStart: region.start,
+      baseEnd: region.end,
+      authors,
+      base: baseLines.slice(region.start, region.end),
+      yours: applyEdits(baseLines, region.start, region.end, partsFor("yours")),
+      upstream: applyEdits(baseLines, region.start, region.end, partsFor("upstream")),
+    };
+  });
+}
+
+/**
+ * Combine both sides when, and only when, they never wrote in the same place.
+ *
+ * A region with one author is unambiguous: taking that author's text is the
+ * same operation `update` performs on a file nobody edited, with the scope
+ * corrected from the file to the region. A region with two authors has no
+ * answer that is not a guess, so the whole file is refused rather than
+ * half-merged. Nothing the user wrote is ever dropped by this function.
+ */
+export function mergeClean({ base, yours, upstream }) {
+  const regions = changedRegions({ base, yours, upstream });
+  const conflicts = regions.filter((region) => region.authors.length === 2);
+  if (conflicts.length) return { merged: null, conflicts: conflicts.length };
+
+  const baseLines = toLines(base);
+  const out = [];
+  let cursor = 0;
+  for (const region of regions) {
+    out.push(...baseLines.slice(cursor, region.baseStart));
+    out.push(...(region.authors[0] === "yours" ? region.yours : region.upstream));
+    cursor = region.baseEnd;
+  }
+  out.push(...baseLines.slice(cursor));
+
+  // The result replaces the reader's file, so it keeps the reader's line endings
+  // and their choice about a final newline. A merge should change what it says,
+  // not how every line in the file is terminated.
+  const eol = yours.includes("\r\n") ? "\r\n" : "\n";
+  const trailing = /\r?\n$/.test(yours) ? eol : "";
+  return { merged: out.length ? out.join(eol) + trailing : "", conflicts: 0 };
+}
+
+/** The nearest Markdown heading above a region, to say where in the file it sits. */
+export function locate(base, region) {
+  const baseLines = toLines(base);
+  if (region.baseStart >= baseLines.length) return "end of file";
+  for (let i = region.baseStart; i >= 0; i--) {
+    if (baseLines[i].startsWith("#")) return `line ${region.baseStart + 1}, in "${baseLines[i].trim()}"`;
+  }
+  return `line ${region.baseStart + 1}`;
+}

package/src/install.mjs

@@ -1,9 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { changedRegions, locate, mergeClean } from "./diff.mjs";
 import {
   PACKAGE_ROOT,
   copyFile,
   exists,
+  hashFile,
   readJson,
   removeEmptyParents,
   snapshotTree,
@@ -54,6 +56,29 @@ async function writeManifest(installDir, files, { previous = null, upstream = nu
   return manifest;
 }
 
+/**
+ * What each installed file descends from after this run.
+ *
+ * Only files this run actually wrote move to the incoming hash. A file left
+ * frozen keeps the hash it had, because its ancestor is still the version it was
+ * last written from; recording the new one would make a later merge read
+ * upstream's change as the user having deleted it.
+ */
+function nextManifestFiles({ previous, plan }) {
+  const kept = new Set(plan.keep.map((item) => item.file));
+  const files = {};
+
+  // Carry an entry forward only while the file is still something to track:
+  // upstream still ships it, or it is on disk because an edit saved it.
+  for (const [file, hash] of Object.entries(previous)) {
+    if (plan.incoming[file] !== undefined || kept.has(file)) files[file] = hash;
+  }
+
+  for (const file of [...plan.add, ...plan.update, ...plan.unchanged]) files[file] = plan.incoming[file];
+  for (const { file } of plan.merge ?? []) files[file] = plan.incoming[file];
+  return files;
+}
+
 /**
  * Three-way comparison between the installed tree, the incoming tree fetched
  * from upstream, and the hashes recorded at the last install or update.
@@ -103,10 +128,53 @@ export async function planUpdate({ installDir, incomingDir, manifest = null, for
   return plan;
 }
 
+/**
+ * Try to combine both sides for the files the plan would otherwise skip.
+ *
+ * A file is only ever a merge candidate when the downloaded base hashes to the
+ * exact value the manifest recorded for it. That proves the text being used as
+ * the common ancestor is the text that was installed; without that proof the
+ * file is left frozen, because a wrong ancestor is how a merge loses work.
+ */
+export async function resolveMerges({ installDir, incomingDir, baseDir, plan, manifest }) {
+  if (!baseDir || !manifest) return { merge: [], skip: plan.skip };
+
+  const merge = [];
+  const skip = [];
+
+  for (const item of plan.skip) {
+    const recorded = manifest.files?.[item.file];
+    const basePath = path.join(baseDir, item.file);
+    const provable = recorded && (await exists(basePath)) && (await hashFile(basePath)) === recorded;
+    if (!provable) {
+      skip.push({ ...item, reason: `${item.reason}; no proven common ancestor to merge from` });
+      continue;
+    }
+
+    const [base, yours, incoming] = await Promise.all([
+      fs.readFile(basePath, "utf8"),
+      fs.readFile(path.join(installDir, item.file), "utf8"),
+      fs.readFile(path.join(incomingDir, item.file), "utf8"),
+    ]);
+
+    const { merged, conflicts } = mergeClean({ base, yours, upstream: incoming });
+    if (merged === null) {
+      skip.push({ ...item, reason: `your change and upstream's overlap in ${conflicts === 1 ? "one place" : `${conflicts} places`}` });
+      continue;
+    }
+    merge.push({ file: item.file, text: merged });
+  }
+
+  return { merge, skip };
+}
+
 export async function applyPlan({ installDir, incomingDir, plan }) {
   for (const file of [...plan.add, ...plan.update]) {
     await copyFile(path.join(incomingDir, file), path.join(installDir, file));
   }
+  for (const { file, text } of plan.merge ?? []) {
+    await fs.writeFile(path.join(installDir, file), text);
+  }
   for (const file of plan.remove) {
     const target = path.join(installDir, file);
     await fs.rm(target, { force: true });
@@ -114,35 +182,106 @@ export async function applyPlan({ installDir, incomingDir, plan }) {
   }
 }
 
+/**
+ * Where the version this install came from can be read, if anywhere. `loadBase`
+ * is only called once the plan actually has something frozen, so an install with
+ * no local edits never pays for a second download.
+ */
+async function baseFor(options, plan, manifest) {
+  if (options.baseDir) return { dir: options.baseDir, upstream: options.base || null };
+  if (!plan.skip.length || !options.loadBase) return null;
+  return (await options.loadBase(manifest)) || null;
+}
+
 async function hasContent(dir) {
   if (!(await exists(dir))) return false;
   const entries = await fs.readdir(dir);
   return entries.length > 0;
 }
 
-export async function init(options = {}) {
+/**
+ * Plan against the incoming tree, apply it, and record the manifest.
+ * The three commands differ only in the preconditions they enforce first.
+ */
+async function reconcile(mode, options) {
   const { installDir } = resolveTarget(options);
   const { incomingDir, upstream = null } = options;
-  const force = Boolean(options.force);
 
-  if (!force && (await hasContent(installDir))) {
+  const created = !(await hasContent(installDir));
+  const manifest = await loadManifest(installDir);
+  const plan = await planUpdate({ installDir, incomingDir, manifest, force: Boolean(options.force) });
+
+  const base = await baseFor(options, plan, manifest);
+  const resolved = await resolveMerges({
+    installDir,
+    incomingDir,
+    baseDir: base?.dir || null,
+    plan,
+    manifest,
+  });
+  plan.merge = resolved.merge;
+  plan.skip = resolved.skip;
+
+  if (!options.dryRun) {
+    await applyPlan({ installDir, incomingDir, plan });
+    const files = nextManifestFiles({ previous: manifest?.files || {}, plan });
+    await writeManifest(installDir, files, { previous: manifest, upstream });
+  }
+  return {
+    mode,
+    installDir,
+    plan,
+    upstream,
+    created,
+    hadManifest: Boolean(manifest),
+    dryRun: Boolean(options.dryRun),
+  };
+}
+
+export async function init(options = {}) {
+  const { installDir } = resolveTarget(options);
+
+  if (!options.force && (await hasContent(installDir))) {
     throw new Error(
       `${installDir} already exists and is not empty. Run "agentic-skills update" to update it, ` +
-      "or pass --force to overwrite managed files in place.",
+      '"agentic-skills sync" if this runs unattended, or pass --force to overwrite managed files in place.',
     );
   }
 
-  const manifest = await loadManifest(installDir);
-  const plan = await planUpdate({ installDir, incomingDir, manifest, force });
-  if (!options.dryRun) {
-    await applyPlan({ installDir, incomingDir, plan });
-    await writeManifest(installDir, plan.incoming, { previous: manifest, upstream });
-  }
-  return { mode: "init", installDir, plan, upstream, dryRun: Boolean(options.dryRun) };
+  return reconcile("init", options);
 }
 
 export async function update(options = {}) {
   const { installDir } = resolveTarget(options);
+
+  if (!(await exists(installDir))) {
+    throw new Error(`${installDir} does not exist. Run "agentic-skills init" first.`);
+  }
+
+  return reconcile("update", options);
+}
+
+/**
+ * Reconcile whatever state the target is in: install it when missing, update it
+ * when it is already there. Neither precondition applies, so this is the command
+ * to run unattended - a postinstall, a CI step, a container build - where one
+ * line has to work on a fresh clone and on an existing tree alike. Local edits
+ * are preserved exactly as with update, and --force overwrites them.
+ */
+export async function sync(options = {}) {
+  return reconcile("sync", options);
+}
+
+/**
+ * Report what upstream changed in the files a local edit froze.
+ *
+ * `status` says which files stopped receiving updates; this says what they
+ * stopped receiving. Nothing is written, and nothing is merged: the installer
+ * never reconciles an edited file on its own, so this is the input a person
+ * needs to do it by hand.
+ */
+export async function inspect(options = {}) {
+  const { installDir } = resolveTarget(options);
   const { incomingDir, upstream = null } = options;
 
   if (!(await exists(installDir))) {
@@ -150,18 +289,40 @@ export async function update(options = {}) {
   }
 
   const manifest = await loadManifest(installDir);
-  const plan = await planUpdate({ installDir, incomingDir, manifest, force: Boolean(options.force) });
-  if (!options.dryRun) {
-    await applyPlan({ installDir, incomingDir, plan });
-    await writeManifest(installDir, plan.incoming, { previous: manifest, upstream });
+  const plan = await planUpdate({ installDir, incomingDir, manifest, force: false });
+  const base = await baseFor(options, plan, manifest);
+  const baseDir = base?.dir || null;
+  const read = async (dir, file) => (dir ? fs.readFile(path.join(dir, file), "utf8").catch(() => null) : null);
+
+  const frozen = [];
+  for (const { file, reason } of plan.skip) {
+    const yours = await read(installDir, file);
+    const incoming = await read(incomingDir, file);
+    // A file upstream added after this install has no base text; treat it as empty
+    // so both sides read as having written the whole thing, which is the truth.
+    const baseText = (await read(baseDir, file)) ?? "";
+
+    const regions = baseDir
+      ? changedRegions({ base: baseText, yours, upstream: incoming })
+        .map((region) => ({ ...region, where: locate(baseText, region) }))
+      : null;
+
+    frozen.push({
+      file,
+      reason,
+      regions,
+      collisions: regions ? regions.filter((region) => region.authors.length === 2).length : null,
+    });
   }
+
   return {
-    mode: "update",
     installDir,
-    plan,
     upstream,
+    base: base?.upstream || null,
+    comparedAgainstBase: Boolean(baseDir),
     hadManifest: Boolean(manifest),
-    dryRun: Boolean(options.dryRun),
+    frozen,
+    removedUpstream: plan.keep,
   };
 }