architectonic 0.0.4 → 0.0.6

package/README.md

@@ -12,8 +12,11 @@ skills     -- reusable procedures and capabilities
 ```
 
 The initial placeholder releases were intentionally minimal. Starting in
-`0.0.4`, `architectonic add` installs the selected layer repositories from
-either git or npm sources and records them in `architectonic.json`.
+`0.0.5`, `architectonic` can initialize a workspace, add layers, inspect the
+local manifest, repair light manifest drift, update safely, and remove layers
+without trampling local forks.
+
+Starting in `0.0.6`, it can also inspect drift with `status` and `diff`.
 
 ## Command shape
 
@@ -25,9 +28,13 @@ architectonic add identity
 architectonic add project
 architectonic add skills
 architectonic add teleology identity skills
+architectonic init
 architectonic doctor
+architectonic status
+architectonic diff
 architectonic list
 architectonic update
+architectonic remove
 ```
 
 `add` is explicit and leaves room for future verbs such as `doctor`, `list`,
@@ -45,8 +52,16 @@ npx architectonic add skills
 npx architectonic add teleology identity skills
 npx architectonic add skills --dir ./vendor
 npx architectonic add teleology --source npm
+npx architectonic init MyWorkspace
+npx architectonic init --preset company
 npx architectonic list
 npx architectonic doctor
+npx architectonic doctor --fix
+npx architectonic status
+npx architectonic diff teleology
+npx architectonic update
+npx architectonic update --dry-run
+npx architectonic remove skills
 ```
 
 `add` installs from the Architectonic GitHub organization into the current
@@ -87,7 +102,47 @@ ARCHITECTONIC_ADD_SOURCE    # change the default source mode
 `list` reads `architectonic.json` and shows installed layers.
 
 `doctor` verifies that each recorded layer still exists and that the installed
-package metadata matches the expected layer.
+package metadata matches the expected layer. `doctor --fix` repairs light
+manifest drift such as stale package names or recoverable default paths.
+
+`status` gives a read-only summary of each layer:
+
+```text
+git layers: branch, dirty/clean, ahead/behind upstream
+npm layers: installed version vs published version
+```
+
+`diff <layer>` drills into one layer:
+
+```text
+git layers: local status lines plus ahead/behind numbers
+npm layers: installed version vs published version
+```
+
+`init` creates a workspace root, installs a preset, and seeds a top-level
+`README.md` and `AGENTS.md`.
+
+Supported presets:
+
+```text
+solo     # teleology + identity + project + skills
+company  # teleology + project + skills
+project  # project + skills
+agent    # identity + skills
+```
+
+`update` is conservative by design:
+
+```text
+git layers: only fast-forward clean git worktrees
+npm layers: report newer packages but do not overwrite local forks
+```
+
+If a user has modified an installed instance, `update` should skip it rather
+than flatten their divergence.
+
+`remove` deletes a recorded layer and updates the manifest. If the layer is a
+dirty git worktree, it refuses unless `--force` is explicit.
 
 ## Run vs install
 

package/bin/architectonic.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
-const VERSION = "0.0.4";
+const VERSION = "0.0.6";
 const args = process.argv.slice(2);
 const [command, ...rest] = args;
 const supported = ["teleology", "identity", "project", "skills"];
@@ -30,8 +30,14 @@ Usage:
   npx architectonic add teleology identity skills
   npx architectonic add skills --dir ./vendor
   npx architectonic add teleology --source npm
+  npx architectonic init [name]
   npx architectonic list
   npx architectonic doctor
+  npx architectonic doctor --fix
+  npx architectonic status
+  npx architectonic diff <layer>
+  npx architectonic update
+  npx architectonic remove <layer>
 
 Layers:
   teleology  purpose, principles, doctrine, governance
@@ -46,7 +52,14 @@ Run vs install:
 
 What add does:
   Installs the selected layer repositories into the target directory
-  from git or npm sources and records them in architectonic.json.`);
+  from git or npm sources and records them in architectonic.json.
+
+What status and diff do:
+  Inspect local drift from recorded sources without mutating anything.`);
+}
+
+function printUsageError(message) {
+  throw new Error(`${message}\nRun \`architectonic help\` for usage.`);
 }
 
 function parseAddArgs(tokens) {
@@ -95,6 +108,203 @@ function parseAddArgs(tokens) {
   return { targets, installDir, source };
 }
 
+function parseInitArgs(tokens) {
+  let installDir = process.cwd();
+  let source = process.env.ARCHITECTONIC_ADD_SOURCE || "git";
+  let preset = "solo";
+  let workspaceName = "";
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--dir" || token === "--out") {
+      const next = tokens[index + 1];
+      if (!next) {
+        throw new Error(`Missing value for ${token}`);
+      }
+      installDir = path.resolve(next);
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--dir=")) {
+      installDir = path.resolve(token.slice("--dir=".length));
+      continue;
+    }
+    if (token.startsWith("--out=")) {
+      installDir = path.resolve(token.slice("--out=".length));
+      continue;
+    }
+    if (token === "--source") {
+      const next = tokens[index + 1];
+      if (!next) {
+        throw new Error("Missing value for --source");
+      }
+      source = next;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--source=")) {
+      source = token.slice("--source=".length);
+      continue;
+    }
+    if (token === "--preset") {
+      const next = tokens[index + 1];
+      if (!next) {
+        throw new Error("Missing value for --preset");
+      }
+      preset = next;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--preset=")) {
+      preset = token.slice("--preset=".length);
+      continue;
+    }
+    if (token.startsWith("-")) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    if (!workspaceName) {
+      workspaceName = token;
+      continue;
+    }
+    throw new Error(`Unexpected argument: ${token}`);
+  }
+
+  if (workspaceName) {
+    installDir = path.resolve(installDir, workspaceName);
+  }
+
+  return { installDir, source, preset, workspaceName };
+}
+
+function parseDoctorArgs(tokens) {
+  let installDir = process.cwd();
+  let fix = false;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--fix") {
+      fix = true;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    installDir = path.resolve(token);
+  }
+
+  return { installDir, fix };
+}
+
+function parseUpdateArgs(tokens) {
+  let installDir = process.cwd();
+  let dryRun = false;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    installDir = path.resolve(token);
+  }
+
+  return { installDir, dryRun };
+}
+
+function parseStatusArgs(tokens) {
+  let installDir = process.cwd();
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token.startsWith("-")) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    installDir = path.resolve(token);
+  }
+
+  return { installDir };
+}
+
+function parseDiffArgs(tokens) {
+  let installDir = process.cwd();
+  let target = "";
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--dir" || token === "--out") {
+      const next = tokens[index + 1];
+      if (!next) {
+        throw new Error(`Missing value for ${token}`);
+      }
+      installDir = path.resolve(next);
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--dir=")) {
+      installDir = path.resolve(token.slice("--dir=".length));
+      continue;
+    }
+    if (token.startsWith("--out=")) {
+      installDir = path.resolve(token.slice("--out=".length));
+      continue;
+    }
+    if (token.startsWith("-")) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    if (!target) {
+      target = token;
+      continue;
+    }
+    throw new Error(`Unexpected argument: ${token}`);
+  }
+
+  return { installDir, target };
+}
+
+function parseRemoveArgs(tokens) {
+  let installDir = process.cwd();
+  let force = false;
+  let target = "";
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--force") {
+      force = true;
+      continue;
+    }
+    if (token === "--dir" || token === "--out") {
+      const next = tokens[index + 1];
+      if (!next) {
+        throw new Error(`Missing value for ${token}`);
+      }
+      installDir = path.resolve(next);
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--dir=")) {
+      installDir = path.resolve(token.slice("--dir=".length));
+      continue;
+    }
+    if (token.startsWith("--out=")) {
+      installDir = path.resolve(token.slice("--out=".length));
+      continue;
+    }
+    if (token.startsWith("-")) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    if (!target) {
+      target = token;
+      continue;
+    }
+    throw new Error(`Unexpected argument: ${token}`);
+  }
+
+  return { installDir, force, target };
+}
+
 function ensureGitAvailable() {
   const result = spawnSync("git", ["--version"], { encoding: "utf8" });
   if (result.status !== 0) {
@@ -165,6 +375,14 @@ function writeManifest(manifestPath, manifest) {
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
 }
 
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function pathExists(filePath) {
+  return fs.existsSync(filePath);
+}
+
 function cloneLayer(target, installDir) {
   const repoUrl = repoUrlFor(target);
   const targetPath = targetPathFor(installDir, target);
@@ -261,51 +479,170 @@ function readInstalledPackageName(layerPath) {
     return null;
   }
   try {
-    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8")).name || null;
+    return readJson(packageJsonPath).name || null;
   } catch {
     return null;
   }
 }
 
-function installLayer(target, installDir, source) {
+function readInstalledVersion(layerPath) {
+  const packageJsonPath = path.join(layerPath, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return null;
+  }
+  try {
+    return readJson(packageJsonPath).version || null;
+  } catch {
+    return null;
+  }
+}
+
+function hasGitRepo(layerPath) {
+  return pathExists(path.join(layerPath, ".git"));
+}
+
+function gitResult(args, cwd) {
+  return spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: "pipe",
+  });
+}
+
+function isGitWorktreeDirty(layerPath) {
+  const result = gitResult(["status", "--porcelain"], layerPath);
+  if (result.status !== 0) {
+    return null;
+  }
+  return Boolean((result.stdout || "").trim());
+}
+
+function packageMetaFor(target, layerPath) {
+  return {
+    expectedPackageName: packageMap[target] || null,
+    packageName: readInstalledPackageName(layerPath),
+    version: readInstalledVersion(layerPath),
+  };
+}
+
+function relativeManifestPath(installDir, absolutePath) {
+  return `./${path.relative(installDir, absolutePath).replace(/\\/g, "/")}`;
+}
+
+function ensureInstallPrereqs(source) {
   if (source === "git") {
-    return cloneLayer(target, installDir);
+    ensureGitAvailable();
+    return;
   }
   if (source === "npm") {
-    return packNpmLayer(target, installDir);
+    ensureNpmAvailable();
+    ensureTarAvailable();
+    return;
   }
   throw new Error(`Unsupported source: ${source}. Use git or npm.`);
 }
 
-function loadManifestFromDir(installDir) {
-  const manifestPath = manifestPathFor(installDir);
-  if (!fs.existsSync(manifestPath)) {
-    throw new Error(`No architectonic.json found in ${installDir}`);
+function updateManifestLayerRecord(manifest, installDir, layerName, absoluteLayerPath, source, refOverride = null) {
+  manifest.layers[layerName] = {
+    source,
+    ref: refOverride ?? manifest.layers[layerName]?.ref ?? (source === "git" ? repoUrlFor(layerName) : packageSpecFor(layerName)),
+    path: relativeManifestPath(installDir, absoluteLayerPath),
+    installed_at: new Date().toISOString(),
+    package_name: readInstalledPackageName(absoluteLayerPath),
+  };
+}
+
+function getGitHead(layerPath) {
+  const result = gitResult(["rev-parse", "HEAD"], layerPath);
+  if (result.status !== 0) {
+    return null;
   }
-  return { manifestPath, manifest: readManifest(manifestPath) };
+  return (result.stdout || "").trim() || null;
 }
 
-function addCommand(tokens) {
-  const { targets, installDir, source } = parseAddArgs(tokens);
+function getGitBranch(layerPath) {
+  const result = gitResult(["rev-parse", "--abbrev-ref", "HEAD"], layerPath);
+  if (result.status !== 0) {
+    return null;
+  }
+  return (result.stdout || "").trim() || null;
+}
 
-  if (!targets.length) {
-    throw new Error("Specify one or more layers: teleology, identity, project, skills");
+function getGitUpstream(layerPath) {
+  const result = gitResult(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], layerPath);
+  if (result.status !== 0) {
+    return null;
   }
+  return (result.stdout || "").trim() || null;
+}
 
-  const invalid = targets.filter((target) => !supportedSet.has(target));
-  if (invalid.length) {
-    throw new Error(`Unknown layer(s): ${invalid.join(", ")}\nSupported layers: ${supported.join(", ")}`);
+function getGitAheadBehind(layerPath) {
+  const upstream = getGitUpstream(layerPath);
+  if (!upstream) {
+    return null;
   }
+  const result = gitResult(["rev-list", "--left-right", "--count", `${upstream}...HEAD`], layerPath);
+  if (result.status !== 0) {
+    return null;
+  }
+  const [behindRaw, aheadRaw] = (result.stdout || "").trim().split(/\s+/);
+  return {
+    upstream,
+    behind: Number.parseInt(behindRaw || "0", 10),
+    ahead: Number.parseInt(aheadRaw || "0", 10),
+  };
+}
 
-  if (source === "git") {
-    ensureGitAvailable();
-  } else if (source === "npm") {
-    ensureNpmAvailable();
-    ensureTarAvailable();
-  } else {
-    throw new Error(`Unsupported source: ${source}. Use git or npm.`);
+function getGitDiffSummary(layerPath) {
+  const result = gitResult(["status", "--short"], layerPath);
+  if (result.status !== 0) {
+    return null;
   }
+  const lines = (result.stdout || "").split(/\r?\n/).filter(Boolean);
+  return {
+    dirty: lines.length > 0,
+    lines,
+  };
+}
 
+function getNpmPublishedVersion(packageSpec) {
+  const result = spawnSync("npm", ["view", packageSpec, "version"], {
+    encoding: "utf8",
+    stdio: "pipe",
+    shell: true,
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  return (result.stdout || "").trim() || null;
+}
+
+function describeGitLayerState(layerPath) {
+  const branch = getGitBranch(layerPath);
+  const head = getGitHead(layerPath);
+  const diffSummary = getGitDiffSummary(layerPath);
+  const aheadBehind = getGitAheadBehind(layerPath);
+  return {
+    branch,
+    head,
+    dirty: diffSummary?.dirty ?? false,
+    diffLines: diffSummary?.lines ?? [],
+    aheadBehind,
+  };
+}
+
+function describeNpmLayerState(layerName, layerPath) {
+  const installedVersion = readInstalledVersion(layerPath);
+  const publishedVersion = getNpmPublishedVersion(packageSpecFor(layerName));
+  return {
+    installedVersion,
+    publishedVersion,
+    outdated: Boolean(installedVersion && publishedVersion && installedVersion !== publishedVersion),
+  };
+}
+
+function installTargets(targets, installDir, source) {
+  ensureInstallPrereqs(source);
   fs.mkdirSync(installDir, { recursive: true });
 
   const installed = [];
@@ -322,13 +659,7 @@ function addCommand(tokens) {
   manifest.npm_source_base = npmBase || "registry";
 
   for (const item of installed) {
-    manifest.layers[item.name] = {
-      source: item.source,
-      ref: item.repo,
-      path: `./${path.relative(installDir, item.path).replace(/\\/g, "/")}`,
-      installed_at: manifest.installed_at,
-      package_name: readInstalledPackageName(item.path),
-    };
+    updateManifestLayerRecord(manifest, installDir, item.name, item.path, item.source, item.repo);
   }
 
   writeManifest(manifestPath, manifest);
@@ -338,6 +669,86 @@ function addCommand(tokens) {
   console.log(`Wrote ${manifestPath}`);
 }
 
+function installLayer(target, installDir, source) {
+  if (source === "git") {
+    return cloneLayer(target, installDir);
+  }
+  if (source === "npm") {
+    return packNpmLayer(target, installDir);
+  }
+  throw new Error(`Unsupported source: ${source}. Use git or npm.`);
+}
+
+function loadManifestFromDir(installDir) {
+  const manifestPath = manifestPathFor(installDir);
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`No architectonic.json found in ${installDir}`);
+  }
+  return { manifestPath, manifest: readManifest(manifestPath) };
+}
+
+function addCommand(tokens) {
+  const { targets, installDir, source } = parseAddArgs(tokens);
+
+  if (!targets.length) {
+    throw new Error("Specify one or more layers: teleology, identity, project, skills");
+  }
+
+  const invalid = targets.filter((target) => !supportedSet.has(target));
+  if (invalid.length) {
+    throw new Error(`Unknown layer(s): ${invalid.join(", ")}\nSupported layers: ${supported.join(", ")}`);
+  }
+
+  installTargets(targets, installDir, source);
+}
+
+function resolvePreset(preset) {
+  const presets = {
+    solo: ["teleology", "identity", "project", "skills"],
+    company: ["teleology", "project", "skills"],
+    project: ["project", "skills"],
+    agent: ["identity", "skills"],
+  };
+  const layers = presets[preset];
+  if (!layers) {
+    throw new Error(`Unknown preset: ${preset}. Supported presets: ${Object.keys(presets).join(", ")}`);
+  }
+  return layers;
+}
+
+function writeInitFiles(installDir, workspaceName, layers) {
+  const displayName = workspaceName || path.basename(installDir);
+  const readmePath = path.join(installDir, "README.md");
+  const agentsPath = path.join(installDir, "AGENTS.md");
+
+  if (!pathExists(readmePath)) {
+    fs.writeFileSync(
+      readmePath,
+      `# ${displayName}\n\nThis workspace was initialized by \`architectonic\`.\n\nInstalled layers:\n\n${layers.map((layer) => `- ${layer}`).join("\n")}\n`,
+      "utf8",
+    );
+  }
+
+  if (!pathExists(agentsPath)) {
+    fs.writeFileSync(
+      agentsPath,
+      `# Agent Instructions\n\nRead installed layers before making structural changes.\n\nPriority order:\n1. teleology\n2. identity\n3. project\n4. skills\n`,
+      "utf8",
+    );
+  }
+}
+
+function initCommand(tokens) {
+  const { installDir, source, preset, workspaceName } = parseInitArgs(tokens);
+  if (pathExists(installDir) && fs.readdirSync(installDir).length > 0) {
+    throw new Error(`Refusing to initialize into a non-empty directory: ${installDir}`);
+  }
+  fs.mkdirSync(installDir, { recursive: true });
+  const layers = resolvePreset(preset);
+  writeInitFiles(installDir, workspaceName, layers);
+  installTargets(layers, installDir, source);
+}
+
 function listCommand(tokens) {
   const installDir = tokens[0] ? path.resolve(tokens[0]) : process.cwd();
   const { manifest } = loadManifestFromDir(installDir);
@@ -359,11 +770,65 @@ function listCommand(tokens) {
   }
 }
 
+function statusCommand(tokens) {
+  const { installDir } = parseStatusArgs(tokens);
+  const { manifest } = loadManifestFromDir(installDir);
+  const entries = Object.entries(manifest.layers || {});
+
+  if (!entries.length) {
+    console.log("No layers installed.");
+    return;
+  }
+
+  ensureGitAvailable();
+  ensureNpmAvailable();
+
+  console.log(`architectonic status`);
+  console.log(`  root: ${installDir}`);
+
+  for (const [name, layer] of entries) {
+    const layerPath = path.resolve(installDir, String(layer.path || ""));
+    if (!pathExists(layerPath)) {
+      console.log(`  [missing] ${name}: ${layer.path || "unknown path"}`);
+      continue;
+    }
+
+    if (layer.source === "git") {
+      const state = describeGitLayerState(layerPath);
+      const dirtyLabel = state.dirty ? "dirty" : "clean";
+      const branchLabel = state.branch || "detached";
+      let relation = "no-upstream";
+      if (state.aheadBehind) {
+        relation = `ahead ${state.aheadBehind.ahead}, behind ${state.aheadBehind.behind}`;
+      }
+      console.log(`  [git] ${name}: ${branchLabel}, ${dirtyLabel}, ${relation}`);
+      continue;
+    }
+
+    if (layer.source === "npm") {
+      const state = describeNpmLayerState(name, layerPath);
+      const installed = state.installedVersion || "unknown";
+      const published = state.publishedVersion || "unknown";
+      const relation = state.outdated ? "outdated" : "current-or-unknown";
+      console.log(`  [npm] ${name}: installed ${installed}, published ${published}, ${relation}`);
+      continue;
+    }
+
+    console.log(`  [unknown] ${name}: unsupported source ${layer.source || "unknown"}`);
+  }
+}
+
+function inferLayerPath(installDir, layerName) {
+  const candidate = targetPathFor(installDir, layerName);
+  return pathExists(candidate) ? candidate : null;
+}
+
 function doctorCommand(tokens) {
-  const installDir = tokens[0] ? path.resolve(tokens[0]) : process.cwd();
+  const { installDir, fix } = parseDoctorArgs(tokens);
   const { manifestPath, manifest } = loadManifestFromDir(installDir);
   const entries = Object.entries(manifest.layers || {});
   let failures = 0;
+  let changed = false;
 
   console.log(`architectonic doctor`);
   console.log(`  root: ${installDir}`);
@@ -384,6 +849,13 @@ function doctorCommand(tokens) {
     const expectedPackageName = packageMap[name];
 
     if (!exists) {
+      const inferredPath = inferLayerPath(installDir, name);
+      if (fix && inferredPath) {
+        updateManifestLayerRecord(manifest, installDir, name, inferredPath, layer.source || "unknown", layer.ref || null);
+        changed = true;
+        console.log(`  [fix] ${name}: repointed path to ${relativeManifestPath(installDir, inferredPath)}`);
+        continue;
+      }
       console.log(`  [fail] ${name}: missing directory ${layerPath}`);
       failures += 1;
       continue;
@@ -396,25 +868,238 @@ function doctorCommand(tokens) {
     }
 
     if (packageName && expectedPackageName && packageName !== expectedPackageName) {
+      if (fix) {
+        manifest.layers[name].package_name = packageName;
+        manifest.layers[name].path = relativeManifestPath(installDir, layerPath);
+        changed = true;
+        console.log(`  [fix] ${name}: synced manifest package name to ${packageName}`);
+        continue;
+      }
       console.log(`  [fail] ${name}: expected package ${expectedPackageName}, found ${packageName}`);
       failures += 1;
       continue;
     }
 
+    if (fix) {
+      const normalizedPath = relativeManifestPath(installDir, layerPath);
+      if (manifest.layers[name].path !== normalizedPath || manifest.layers[name].package_name !== packageName) {
+        manifest.layers[name].path = normalizedPath;
+        manifest.layers[name].package_name = packageName;
+        changed = true;
+      }
+    }
+
     console.log(`  [ok] ${name}: ${relativePath} (${layer.source || "unknown"})`);
   }
 
+  if (fix && changed) {
+    writeManifest(manifestPath, manifest);
+    console.log(`  [write] updated manifest repairs`);
+  }
+
   if (failures > 0) {
     process.exit(1);
   }
 }
 
+function updateGitLayer(layerName, layerPath, dryRun) {
+  if (!hasGitRepo(layerPath)) {
+    return { status: "skip", detail: "not a git repository" };
+  }
+  const dirty = isGitWorktreeDirty(layerPath);
+  if (dirty === null) {
+    return { status: "skip", detail: "unable to inspect git status" };
+  }
+  if (dirty) {
+    return { status: "skip", detail: "local changes detected; preserving fork" };
+  }
+  if (dryRun) {
+    return { status: "plan", detail: "would run git pull --ff-only" };
+  }
+  const result = gitResult(["pull", "--ff-only"], layerPath);
+  if (result.status !== 0) {
+    return { status: "fail", detail: (result.stderr || result.stdout || "").trim() || "git pull failed" };
+  }
+  return { status: "ok", detail: (result.stdout || "").trim() || "up to date" };
+}
+
+function getLatestNpmVersion(packageSpec) {
+  const result = spawnSync("npm", ["view", packageSpec, "version"], {
+    encoding: "utf8",
+    stdio: "pipe",
+    shell: true,
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  return (result.stdout || "").trim() || null;
+}
+
+function updateNpmLayer(layerName, layerPath) {
+  const installedVersion = readInstalledVersion(layerPath);
+  const packageSpec = packageSpecFor(layerName);
+  const latestVersion = getLatestNpmVersion(packageSpec);
+  if (!latestVersion) {
+    return { status: "skip", detail: "unable to resolve latest npm version" };
+  }
+  if (!installedVersion) {
+    return { status: "skip", detail: `latest ${latestVersion} available; local version unknown` };
+  }
+  if (installedVersion === latestVersion) {
+    return { status: "ok", detail: `already at ${installedVersion}` };
+  }
+  return {
+    status: "skip",
+    detail: `newer package ${latestVersion} available; skipped to preserve local fork (${installedVersion} installed)`,
+  };
+}
+
+function updateCommand(tokens) {
+  const { installDir, dryRun } = parseUpdateArgs(tokens);
+  const { manifestPath, manifest } = loadManifestFromDir(installDir);
+  const entries = Object.entries(manifest.layers || {});
+
+  if (!entries.length) {
+    throw new Error("No installed layers recorded.");
+  }
+
+  ensureGitAvailable();
+  ensureNpmAvailable();
+
+  let changed = false;
+  console.log(`architectonic update${dryRun ? " --dry-run" : ""}`);
+  console.log(`  root: ${installDir}`);
+
+  for (const [name, layer] of entries) {
+    const layerPath = path.resolve(installDir, String(layer.path || ""));
+    if (!pathExists(layerPath)) {
+      console.log(`  [skip] ${name}: missing directory`);
+      continue;
+    }
+
+    let outcome;
+    if (layer.source === "git") {
+      outcome = updateGitLayer(name, layerPath, dryRun);
+    } else if (layer.source === "npm") {
+      outcome = updateNpmLayer(name, layerPath);
+    } else {
+      outcome = { status: "skip", detail: `unsupported source ${layer.source || "unknown"}` };
+    }
+
+    console.log(`  [${outcome.status}] ${name}: ${outcome.detail}`);
+    if (outcome.status === "ok" && !dryRun) {
+      manifest.layers[name].installed_at = new Date().toISOString();
+      manifest.layers[name].package_name = readInstalledPackageName(layerPath);
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    writeManifest(manifestPath, manifest);
+    console.log(`  [write] refreshed manifest timestamps`);
+  }
+}
+
+function removeCommand(tokens) {
+  const { installDir, force, target } = parseRemoveArgs(tokens);
+  if (!target) {
+    throw new Error("Specify a layer to remove.");
+  }
+  if (!supportedSet.has(target)) {
+    throw new Error(`Unknown layer: ${target}`);
+  }
+  const { manifestPath, manifest } = loadManifestFromDir(installDir);
+  const layer = manifest.layers[target];
+  if (!layer) {
+    throw new Error(`Layer not recorded in manifest: ${target}`);
+  }
+  const layerPath = path.resolve(installDir, String(layer.path || ""));
+  if (pathExists(layerPath) && hasGitRepo(layerPath) && !force) {
+    const dirty = isGitWorktreeDirty(layerPath);
+    if (dirty) {
+      throw new Error(`Refusing to remove ${target}: local git changes detected. Re-run with --force if you really want to delete it.`);
+    }
+  }
+  if (pathExists(layerPath)) {
+    fs.rmSync(layerPath, { recursive: true, force: true });
+  }
+  delete manifest.layers[target];
+  writeManifest(manifestPath, manifest);
+  console.log(`Removed ${target}`);
+  console.log(`Updated ${manifestPath}`);
+}
+
+function diffCommand(tokens) {
+  const { installDir, target } = parseDiffArgs(tokens);
+  if (!target) {
+    throw new Error("Specify a layer to diff.");
+  }
+  if (!supportedSet.has(target)) {
+    throw new Error(`Unknown layer: ${target}`);
+  }
+  const { manifest } = loadManifestFromDir(installDir);
+  const layer = manifest.layers[target];
+  if (!layer) {
+    throw new Error(`Layer not recorded in manifest: ${target}`);
+  }
+  const layerPath = path.resolve(installDir, String(layer.path || ""));
+  if (!pathExists(layerPath)) {
+    throw new Error(`Layer path does not exist: ${layerPath}`);
+  }
+
+  if (layer.source === "git") {
+    ensureGitAvailable();
+    const summary = getGitDiffSummary(layerPath);
+    const aheadBehind = getGitAheadBehind(layerPath);
+    console.log(`architectonic diff ${target}`);
+    console.log(`  source: git`);
+    console.log(`  path: ${layerPath}`);
+    if (aheadBehind) {
+      console.log(`  upstream: ${aheadBehind.upstream}`);
+      console.log(`  ahead: ${aheadBehind.ahead}`);
+      console.log(`  behind: ${aheadBehind.behind}`);
+    }
+    if (!summary || !summary.lines.length) {
+      console.log(`  local changes: none`);
+      return;
+    }
+    console.log(`  local changes:`);
+    for (const line of summary.lines) {
+      console.log(`    ${line}`);
+    }
+    return;
+  }
+
+  if (layer.source === "npm") {
+    ensureNpmAvailable();
+    const state = describeNpmLayerState(target, layerPath);
+    console.log(`architectonic diff ${target}`);
+    console.log(`  source: npm`);
+    console.log(`  path: ${layerPath}`);
+    console.log(`  installed version: ${state.installedVersion || "unknown"}`);
+    console.log(`  published version: ${state.publishedVersion || "unknown"}`);
+    if (state.outdated) {
+      console.log(`  drift: newer package available`);
+    } else {
+      console.log(`  drift: none detected from package version`);
+    }
+    return;
+  }
+
+  throw new Error(`Unsupported source for diff: ${layer.source || "unknown"}`);
+}
+
 try {
   if (!command || command === "help" || command === "--help" || command === "-h") {
     printHelp();
     process.exit(0);
   }
 
+  if (command === "init") {
+    initCommand(rest);
+    process.exit(0);
+  }
+
   if (command === "add") {
     addCommand(rest);
     process.exit(0);
@@ -430,7 +1115,27 @@ try {
     process.exit(0);
   }
 
-  throw new Error(`Unknown command: ${command}\nRun \`architectonic help\` for usage.`);
+  if (command === "status") {
+    statusCommand(rest);
+    process.exit(0);
+  }
+
+  if (command === "diff") {
+    diffCommand(rest);
+    process.exit(0);
+  }
+
+  if (command === "update") {
+    updateCommand(rest);
+    process.exit(0);
+  }
+
+  if (command === "remove") {
+    removeCommand(rest);
+    process.exit(0);
+  }
+
+  printUsageError(`Unknown command: ${command}`);
 } catch (error) {
   console.error(error.message);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "architectonic",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "CLI for composing agentic system layers such as teleology, identity, project, and skills.",
   "license": "Apache-2.0",
   "type": "module",