luciazero 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -7,6 +7,39 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.0.2] - 2026-08-13
+
+### Fixed
+
+- `/lucia-relay` now records whether its recipient is on the same machine or a
+  different one before producing pointers. Schema 2 permits full paths only
+  for same-machine delivery; cross-machine validation requires a clean HEAD
+  reachable from a locally known remote branch, rejects machine-only paths,
+  and provides `knowledge.inline` for otherwise-local context. Schema 1 relays
+  remain readable as same-machine-only legacy artifacts, and legacy `draft`
+  callers without `--recipient` safely default to same-machine delivery.
+
+## [2.0.1] - 2026-08-13
+
+### Added
+
+- **Explicit, channel-aware updates.** `npx luciazero@latest check-update`
+  performs a read-only, five-second npm registry check only when invoked;
+  `npx luciazero@latest update` detects classic Claude, its hook mode, and
+  Codex, then refreshes every detected install through the existing audited
+  installers. It refuses to create a fresh install, downgrade a recognized
+  newer one, or trust a malformed version sidecar. Legacy installs without the
+  sidecar remain updatable. Classic doctrine customization now receives the
+  same managed-snapshot backup protection as skills and agents.
+  Plugin and skills-only update commands, Claude plugin auto-update, and GitHub
+  release notifications are documented separately in both READMEs.
+
+### Changed
+
+- The release workflow uses the runner's GitHub CLI instead of a Node 20-based
+  release action. Re-runs replace the existing zip without recreating the
+  release, and GitHub Actions no longer emits the deprecated-runtime warning.
+
 ## [2.0.0] - 2026-08-13
 
 ### Changed

package/README.md

@@ -57,6 +57,11 @@ human view; session B checks the Git fingerprint, reads the exact next action
 and refuted hypotheses, re-runs verification, then explicitly consumes the
 relay.
 
+Relay decides where the recipient is before it writes pointers. Same-machine
+receivers may use full local paths. Cross-machine relays require a clean pushed
+commit, reject machine-only paths, and carry otherwise-local knowledge inline
+in the JSON.
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/ohm41321/luciazero/main/docs/assets/relay-demo.gif" width="720" alt="One session creates a Lucia Relay; another validates it, detects repository drift, re-runs evidence, and consumes it">
 </p>
@@ -106,6 +111,35 @@ Classic installs support `--status`; Codex receives the doctrine and skills but
 not Claude-only hooks/statusline. Installers back up name collisions and remove
 only exact Luciazero-managed copies on uninstall.
 
+## Update
+
+Luciazero never changes classic or Codex files in the background.
+
+```bash
+npx luciazero@latest check-update   # read-only; contacts npm only now
+npx luciazero@latest update         # updates every detected classic/Codex install
+```
+
+`update` preserves whether the Claude classic install uses hooks, repairs stale
+managed files, starts no fresh install when it cannot find one, and stops on a
+known newer version or malformed version metadata. Start a new agent session
+afterward.
+
+Other install channels use their own updater:
+
+```bash
+claude plugin update luciazero@luciazero   # then run /reload-plugins
+npx skills update                          # review the scope prompt
+```
+
+The skills command updates every installed skill in the selected scope, not
+only Luciazero; review its prompt before confirming.
+
+Claude Code can auto-update the plugin at startup: open `/plugin` →
+**Marketplaces** → **luciazero** → **Enable auto-update**. Third-party
+marketplaces leave this off by default. For release-only notifications, use
+GitHub **Watch → Custom → Releases**.
+
 ## The 9 skills
 
 Run `/luciazero-bootstrap` first; the rest activate when their moment arrives.

package/README.th.md

@@ -56,6 +56,10 @@ Session A สร้าง `LUCIA_RELAY.json` ที่เป็น canonical พ
 ที่ generate จากไฟล์นั้น ส่วน Session B ตรวจ Git fingerprint, อ่าน next action
 กับสมมติฐานที่ถูกหักล้าง, รัน verification ซ้ำ แล้ว consume relay อย่างชัดเจน
 
+Relay ต้องตัดสินก่อนว่าผู้รับอยู่ที่ไหน: ถ้าอยู่เครื่องเดิมใช้ full local path
+ได้ แต่ถ้าข้ามเครื่องต้องเป็น commit ที่ clean และ push แล้วเท่านั้น ตัวตรวจจะ
+ปฏิเสธ path เฉพาะเครื่อง และให้ใส่ความรู้ที่อยู่นอก repo ลงใน JSON โดยตรง
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/ohm41321/luciazero/main/docs/assets/relay-demo.gif" width="720" alt="Session หนึ่งสร้าง Lucia Relay อีก session ตรวจสอบ พบ repository drift รันหลักฐานซ้ำ และ consume relay">
 </p>
@@ -104,6 +108,34 @@ npx luciazero uninstall-codex
 เฉพาะ Claude Installer สำรองชื่อที่ชน และตอนถอนจะลบเฉพาะสำเนาที่ Luciazero
 ยืนยันความเป็นเจ้าของได้
 
+## อัปเดต
+
+Luciazero จะไม่แก้ไฟล์ของ classic หรือ Codex อยู่เบื้องหลัง
+
+```bash
+npx luciazero@latest check-update   # อ่านอย่างเดียว ติดต่อ npm เฉพาะตอนนี้
+npx luciazero@latest update         # อัปเดต classic/Codex ทุกชุดที่ตรวจพบ
+```
+
+`update` รักษาโหมดเดิมว่า Claude classic ใช้ hook หรือไม่ ซ่อมไฟล์ managed ที่
+เก่า จะไม่เริ่มติดตั้งใหม่ถ้าหา installation เดิมไม่พบ และจะหยุดเมื่อพบเวอร์ชัน
+ที่ใหม่กว่าหรือข้อมูลเวอร์ชันเสีย หลังอัปเดตให้เริ่ม agent session ใหม่
+
+ช่องทางอื่นใช้ตัวอัปเดตของช่องทางนั้น:
+
+```bash
+claude plugin update luciazero@luciazero   # แล้วรัน /reload-plugins
+npx skills update                          # ตรวจ scope ใน prompt ก่อนยืนยัน
+```
+
+คำสั่ง skills จะอัปเดต skill ทุกตัวใน scope ที่เลือก ไม่ใช่เฉพาะ Luciazero
+จึงควรตรวจ prompt ก่อนยืนยัน
+
+Claude Code อัปเดต plugin ตอนเริ่มโปรแกรมอัตโนมัติได้: เปิด `/plugin` →
+**Marketplaces** → **luciazero** → **Enable auto-update** โดย marketplace
+ภายนอกจะปิดตัวเลือกนี้เป็นค่าเริ่มต้น ถ้าต้องการเพียงการแจ้งเตือน release ให้ใช้
+GitHub **Watch → Custom → Releases**
+
 ## Skill ทั้ง 9 ตัว
 
 รัน `/luciazero-bootstrap` ก่อนหนึ่งครั้ง ที่เหลือใช้เมื่อถึงจังหวะของมัน

package/bin/luciazero.js

@@ -7,6 +7,8 @@
 //   npx luciazero uninstall                 -> uninstall.sh
 //   npx luciazero uninstall-codex           -> uninstall-codex.sh
 //   npx luciazero discipline [options]       -> local stats report
+//   npx luciazero check-update [--json]       -> explicit npm version check
+//   npx luciazero update                      -> update detected classic installs
 const { spawnSync } = require("node:child_process");
 const path = require("node:path");
 
@@ -16,13 +18,18 @@ const ROUTES = {
   uninstall: { runtime: "bash", script: "uninstall.sh" },
   "uninstall-codex": { runtime: "bash", script: "uninstall-codex.sh" },
   discipline: { runtime: process.execPath, script: "bin/discipline-report.js" },
+  "check-update": { runtime: process.execPath, script: "bin/update.js", args: ["check"] },
+  update: { runtime: process.execPath, script: "bin/update.js", args: ["update"] },
 };
 
 const args = process.argv.slice(2);
 let route = "install";
 if (args[0] && !args[0].startsWith("-")) {
   if (!Object.prototype.hasOwnProperty.call(ROUTES, args[0])) {
-    console.error(`luciazero: unknown command '${args[0]}' (install, codex, discipline, uninstall, uninstall-codex)`);
+    console.error(
+      `luciazero: unknown command '${args[0]}' ` +
+      "(install, codex, discipline, check-update, update, uninstall, uninstall-codex)"
+    );
     process.exit(64);
   }
   route = args.shift();
@@ -37,7 +44,7 @@ if (process.platform === "win32" && selected.runtime === "bash") {
   process.exit(1);
 }
 
-const result = spawnSync(selected.runtime, [script, ...args], { stdio: "inherit" });
+const result = spawnSync(selected.runtime, [script, ...(selected.args || []), ...args], { stdio: "inherit" });
 if (result.error) {
   console.error("luciazero: could not run bash: " + result.error.message);
   process.exit(1);

package/bin/update.js

@@ -0,0 +1,366 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const ROOT = path.resolve(__dirname, "..");
+const PACKAGE_NAME = "luciazero";
+const PACKAGE_VERSION = require(path.join(ROOT, "package.json")).version;
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") return "";
+    throw error;
+  }
+}
+
+function readVersion(directory) {
+  const value = readText(path.join(directory, ".luciazero-version")).split(/\r?\n/, 1)[0].trim();
+  return value || null;
+}
+
+function versionMetadata(directory) {
+  const file = path.join(directory, ".luciazero-version");
+  return { installedVersion: readVersion(directory), versionFilePresent: fs.existsSync(file) };
+}
+
+function detectInstallations(options = {}) {
+  const env = options.env || process.env;
+  const home = options.home || os.homedir();
+  const claudeDir = options.claudeDir || env.CLAUDE_CONFIG_DIR || path.join(home, ".claude");
+  const codexDir = options.codexDir || env.CODEX_HOME || path.join(home, ".codex");
+  const installations = [];
+
+  const claudeSettings = readText(path.join(claudeDir, "settings.json"));
+  const claudeInstalled =
+    fs.existsSync(path.join(claudeDir, ".luciazero-version")) ||
+    fs.existsSync(path.join(claudeDir, "luciazero.md")) ||
+    fs.existsSync(path.join(claudeDir, ".luciazero-managed"));
+  if (claudeInstalled) {
+    installations.push({
+      channel: "claude-classic",
+      configDir: claudeDir,
+      ...versionMetadata(claudeDir),
+      hooks:
+        fs.existsSync(path.join(claudeDir, "hooks", "luciazero-verify.sh")) ||
+        claudeSettings.includes("hooks/luciazero-verify.sh"),
+    });
+  }
+
+  const codexAgents = readText(path.join(codexDir, "AGENTS.md"));
+  const codexInstalled =
+    fs.existsSync(path.join(codexDir, ".luciazero-version")) ||
+    fs.existsSync(path.join(codexDir, ".luciazero-managed")) ||
+    codexAgents.includes("<!-- luciazero:start -->");
+  if (codexInstalled) {
+    installations.push({
+      channel: "codex",
+      configDir: codexDir,
+      ...versionMetadata(codexDir),
+      hooks: false,
+    });
+  }
+
+  return installations;
+}
+
+function parseSemver(value) {
+  const match = String(value || "").match(
+    /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+  );
+  if (!match) return null;
+  return {
+    core: match.slice(1, 4).map(Number),
+    prerelease: match[4] ? match[4].split(".") : [],
+  };
+}
+
+function comparePrerelease(left, right) {
+  if (left.length === 0 && right.length === 0) return 0;
+  if (left.length === 0) return 1;
+  if (right.length === 0) return -1;
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    if (left[index] === undefined) return -1;
+    if (right[index] === undefined) return 1;
+    if (left[index] === right[index]) continue;
+    const leftNumber = /^\d+$/.test(left[index]);
+    const rightNumber = /^\d+$/.test(right[index]);
+    if (leftNumber && rightNumber) return Number(left[index]) < Number(right[index]) ? -1 : 1;
+    if (leftNumber !== rightNumber) return leftNumber ? -1 : 1;
+    return left[index] < right[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+function compareSemver(leftValue, rightValue) {
+  const left = parseSemver(leftValue);
+  const right = parseSemver(rightValue);
+  if (!left || !right) return null;
+  for (let index = 0; index < left.core.length; index += 1) {
+    if (left.core[index] !== right.core[index]) {
+      return left.core[index] < right.core[index] ? -1 : 1;
+    }
+  }
+  return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+function installationStatus(installation, latestVersion) {
+  const comparison = compareSemver(installation.installedVersion, latestVersion);
+  let status = "unknown";
+  if (comparison === 0) status = "current";
+  else if (comparison === -1) status = "update-available";
+  else if (comparison === 1) status = "ahead";
+  return { ...installation, status };
+}
+
+function buildCheckResult(installations, latestVersion) {
+  const checked = installations.map((installation) => installationStatus(installation, latestVersion));
+  return {
+    package: PACKAGE_NAME,
+    bundledVersion: PACKAGE_VERSION,
+    latestVersion,
+    cliUpdateAvailable: compareSemver(PACKAGE_VERSION, latestVersion) === -1,
+    updateAvailable:
+      compareSemver(PACKAGE_VERSION, latestVersion) === -1 ||
+      checked.some((installation) => installation.status === "update-available"),
+    installations: checked,
+  };
+}
+
+async function fetchLatestVersion(options = {}) {
+  const registry = options.registry || process.env.npm_config_registry || "https://registry.npmjs.org/";
+  const request = options.fetch || globalThis.fetch;
+  if (typeof request !== "function") throw new Error("this Node.js runtime has no fetch support");
+  const base = registry.endsWith("/") ? registry : `${registry}/`;
+  const endpoint = new URL(`${PACKAGE_NAME}/latest`, base);
+  if (!["http:", "https:"].includes(endpoint.protocol)) {
+    throw new Error("npm registry must use http or https");
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs || 5000);
+  try {
+    const response = await request(endpoint, {
+      headers: { Accept: "application/json", "User-Agent": `luciazero/${PACKAGE_VERSION}` },
+      redirect: "follow",
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new Error(`registry returned HTTP ${response.status}`);
+    const payload = await response.json();
+    if (!payload || !parseSemver(payload.version)) throw new Error("registry returned an invalid version");
+    return payload.version;
+  } catch (error) {
+    if (error && error.name === "AbortError") throw new Error("registry request timed out");
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function channelLabel(installation) {
+  if (installation.channel === "codex") return "Codex";
+  return installation.hooks ? "Claude classic + hooks" : "Claude classic";
+}
+
+function writeLine(stream, line = "") {
+  stream.write(`${line}\n`);
+}
+
+function printSeparateChannelHelp(stream) {
+  writeLine(stream, "Claude plugin: claude plugin update luciazero@luciazero, then /reload-plugins");
+  writeLine(stream, "Skills only:  npx skills update   (updates all skills in the selected scope; review the prompt)");
+}
+
+function checkHelp(stream) {
+  writeLine(stream, "Usage: npx luciazero@latest check-update [--json]");
+  writeLine(stream, "Checks the npm registry only when this command is run; it never changes files.");
+}
+
+async function runCheck(args = [], dependencies = {}) {
+  const stdout = dependencies.stdout || process.stdout;
+  const stderr = dependencies.stderr || process.stderr;
+  if (args.includes("--help") || args.includes("-h")) {
+    checkHelp(stdout);
+    return 0;
+  }
+  const unknown = args.filter((arg) => arg !== "--json");
+  if (unknown.length > 0) {
+    writeLine(stderr, `luciazero check-update: unknown option '${unknown[0]}'`);
+    checkHelp(stderr);
+    return 64;
+  }
+
+  const findInstallations = dependencies.detectInstallations || detectInstallations;
+  const getLatestVersion = dependencies.fetchLatestVersion || fetchLatestVersion;
+  let latestVersion;
+  try {
+    latestVersion = await getLatestVersion();
+  } catch (error) {
+    writeLine(stderr, `luciazero check-update: ${error.message}`);
+    writeLine(stderr, "No files were changed. Retry later or check https://www.npmjs.com/package/luciazero.");
+    return 1;
+  }
+
+  const result = buildCheckResult(findInstallations(), latestVersion);
+  if (args.includes("--json")) {
+    writeLine(stdout, JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  writeLine(stdout, "Luciazero update check");
+  writeLine(stdout, `  latest npm release   ${result.latestVersion}`);
+  writeLine(stdout, `  this command carries ${result.bundledVersion}`);
+  if (result.installations.length === 0) {
+    writeLine(stdout, "  no classic Claude/Codex installation detected");
+  } else {
+    for (const installation of result.installations) {
+      const installed = installation.installedVersion || "unknown version";
+      const suffix = {
+        current: "current",
+        "update-available": `update available -> ${result.latestVersion}`,
+        ahead: "ahead of the latest public release",
+        unknown: `cannot compare -> ${result.latestVersion}`,
+      }[installation.status];
+      writeLine(stdout, `  ${channelLabel(installation)}: ${installed} (${suffix})`);
+    }
+  }
+  const malformed = result.installations.filter(
+    (item) => item.versionFilePresent && item.status === "unknown"
+  );
+  const updatable = result.installations.filter(
+    (item) => item.status === "update-available" || (!item.versionFilePresent && item.status === "unknown")
+  );
+  if (malformed.length > 0) {
+    writeLine(stdout);
+    writeLine(stdout, "Cannot update installs with a malformed .luciazero-version file.");
+    writeLine(stdout, "Repair it, or remove it only after confirming the installed version.");
+  }
+  if (updatable.length > 0) {
+    writeLine(stdout);
+    writeLine(stdout, "Update detected classic/Codex installs with:");
+    writeLine(stdout, "  npx luciazero@latest update");
+  } else if (result.cliUpdateAvailable) {
+    writeLine(stdout);
+    writeLine(stdout, "This command is older than the latest release. Re-run it with:");
+    writeLine(stdout, "  npx luciazero@latest check-update");
+  }
+  writeLine(stdout);
+  printSeparateChannelHelp(stdout);
+  return 0;
+}
+
+function updateHelp(stream) {
+  writeLine(stream, "Usage: npx luciazero@latest update");
+  writeLine(stream, "Updates every detected classic Claude/Codex install and preserves Claude hook mode.");
+}
+
+function runInstaller(installation, dependencies = {}) {
+  const spawn = dependencies.spawnSync || spawnSync;
+  const script = installation.channel === "codex" ? "install-codex.sh" : "install.sh";
+  const args = [path.join(ROOT, script)];
+  if (installation.channel === "claude-classic" && installation.hooks) args.push("--with-hooks");
+  return spawn("bash", args, { env: process.env, stdio: "inherit" });
+}
+
+function runUpdate(args = [], dependencies = {}) {
+  const stdout = dependencies.stdout || process.stdout;
+  const stderr = dependencies.stderr || process.stderr;
+  if (args.includes("--help") || args.includes("-h")) {
+    updateHelp(stdout);
+    return 0;
+  }
+  if (args.length > 0) {
+    writeLine(stderr, `luciazero update: unknown option '${args[0]}'`);
+    updateHelp(stderr);
+    return 64;
+  }
+
+  const findInstallations = dependencies.detectInstallations || detectInstallations;
+  const installations = findInstallations();
+  if (installations.length === 0) {
+    writeLine(stderr, "No classic Claude/Codex installation detected; nothing changed.");
+    printSeparateChannelHelp(stderr);
+    return 1;
+  }
+  const newerInstallations = installations.filter(
+    (installation) => compareSemver(installation.installedVersion, PACKAGE_VERSION) === 1
+  );
+  if (newerInstallations.length > 0) {
+    for (const installation of newerInstallations) {
+      writeLine(
+        stderr,
+        `Refusing to downgrade ${channelLabel(installation)} from ` +
+          `${installation.installedVersion} to bundled ${PACKAGE_VERSION}.`
+      );
+    }
+    writeLine(stderr, "Run npx luciazero@latest update so the updater itself is current.");
+    return 1;
+  }
+  const invalidMetadata = installations.filter(
+    (installation) => installation.versionFilePresent && !parseSemver(installation.installedVersion)
+  );
+  if (invalidMetadata.length > 0) {
+    for (const installation of invalidMetadata) {
+      writeLine(
+        stderr,
+        `Refusing to update ${channelLabel(installation)}: .luciazero-version is malformed.`
+      );
+    }
+    writeLine(stderr, "Repair or remove the malformed sidecar after confirming the installed version, then retry.");
+    return 1;
+  }
+  if (process.platform === "win32") {
+    writeLine(stderr, "Luciazero installers need Bash. Run this command inside WSL.");
+    return 1;
+  }
+
+  writeLine(stdout, `Updating detected installations with Luciazero ${PACKAGE_VERSION}:`);
+  let failed = false;
+  for (const installation of installations) {
+    writeLine(stdout, `\n-- ${channelLabel(installation)} (${installation.configDir})`);
+    const result = runInstaller(installation, dependencies);
+    if (result.error || result.status !== 0) {
+      failed = true;
+      const detail = result.error ? `: ${result.error.message}` : ` (exit ${result.status})`;
+      writeLine(stderr, `luciazero update: ${channelLabel(installation)} failed${detail}`);
+    }
+  }
+  if (failed) return 1;
+
+  writeLine(stdout, "\nUpdated all detected classic/Codex installations.");
+  writeLine(stdout, "Start a new agent session so the refreshed doctrine and skills are loaded.");
+  return 0;
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  let status;
+  if (command === "check") status = await runCheck(args);
+  else if (command === "update") status = runUpdate(args);
+  else {
+    writeLine(process.stderr, `luciazero update helper: unknown command '${command || ""}'`);
+    status = 64;
+  }
+  process.exitCode = status;
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    writeLine(process.stderr, `luciazero update helper: ${error.message}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  buildCheckResult,
+  compareSemver,
+  detectInstallations,
+  fetchLatestVersion,
+  runCheck,
+  runUpdate,
+};

package/install.sh

@@ -183,7 +183,8 @@ echo "Installing into ${CLAUDE_DIR}"
 mkdir -p "${CLAUDE_DIR}/skills"
 
 # 1. doctrine
-cp "${SRC}/claude/${DOCTRINE}" "${CLAUDE_DIR}/${DOCTRINE}"
+install_file "${SRC}/claude/${DOCTRINE}" "${CLAUDE_DIR}/${DOCTRINE}" \
+  "${MANAGED_DIR}/${DOCTRINE}" "${DOCTRINE}"
 echo "  ok  ${DOCTRINE}"
 
 # 2. skills — catalog.txt is the single install/status/uninstall inventory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luciazero",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Verification-first discipline for coding agents (Claude Code + Codex CLI): 9-rule doctrine, 9 skills, risk-routed reviewer, fail-open enforcement hooks. npx luciazero installs it.",
   "repository": { "type": "git", "url": "git+https://github.com/ohm41321/luciazero.git" },
   "homepage": "https://github.com/ohm41321/luciazero#readme",

package/skills/lucia-relay/SKILL.md

@@ -7,24 +7,34 @@ description: Package unfinished work and non-obvious knowledge into a portable,
 
 `/retro` stores permanent lessons. `/lucia-relay` transfers task-local state. The canonical artifact is `LUCIA_RELAY.json`; `LUCIA_RELAY.md` is its generated human view. A receiver trusts neither until the tree and verification evidence agree.
 
+## Decide the route first
+
+Before writing or pointing anywhere, answer: **Where is the recipient?**
+
+- `same-machine`: the receiver shares this machine. Full local paths are allowed.
+- `cross-machine`: the receiver cannot open anything local. Every pointer must be repo-relative and present in a pushed commit, or the needed knowledge must be copied into `knowledge.inline` in `LUCIA_RELAY.json`.
+
+If the destination is not explicit and cannot be inferred, ask the user. Never assume a local path will travel.
+
 ## Produce
 
-1. Locate this skill's installed directory and run `<this-skill-dir>/scripts/relay.py draft --root .` to see the schema and captured repository fingerprint.
-2. Create `LUCIA_RELAY.json` at the repo root. Fill the original goal, completed and in-progress work, one literal next action, verification evidence, relevant files, read-first pointers, open **and refuted** hypotheses, and landmines. Keep the captured `repository` object from the draft.
-3. Run `<this-skill-dir>/scripts/relay.py render --root .`; fix every validation error and review both artifacts for secrets or machine-only paths.
+1. Locate this skill's installed directory and run `<this-skill-dir>/scripts/relay.py draft --root . --recipient <same-machine|cross-machine>`. Always pass the route explicitly; the CLI's `same-machine` default exists only so older callers keep working.
+2. Create `LUCIA_RELAY.json` at the repo root. Fill the original goal, completed and in-progress work, one literal next action, verification evidence, relevant files, read-first pointers, inline knowledge, open **and refuted** hypotheses, and landmines. Keep the captured `route` and `repository` objects from the draft.
+3. For `cross-machine`, commit and push every task file first. Start each `read_first` entry with its repo-relative tracked path; an optional note may follow ` — `. Replace machine-local document, memory, or artifact pointers with a short `{ "label": "...", "content": "..." }` entry in `knowledge.inline`. Do not include credentials.
+4. Run `<this-skill-dir>/scripts/relay.py render --root .`; fix every validation error and review both artifacts for secrets and route mistakes.
 
 Evidence rules:
 
 - A verification entry includes the exact command, exit code, shortest decisive line, and run time. Never turn “not run” into implied green.
 - The next action is executable: a command, exact edit, or decision. “Continue the refactor” is invalid.
 - Preserve refuted hypotheses and why they failed. They are the knowledge most likely to save the receiver time.
-- Point to relevant `docs/lessons.md` entries. Copy a machine-local heuristic only when it is essential and contains no secret, credential location, personal path, or preference.
+- Point to relevant `docs/lessons.md` entries. For cross-machine delivery, inline an essential machine-local heuristic instead of pointing to its local file; omit secrets, credential locations, personal paths, and preferences.
 
 ## Route
 
 - Same worktree/session boundary: leave both files uncommitted; the SessionStart hook points at them.
-- Another local agent or harness sharing the tree: give it both paths and ask it to run `inspect` before editing.
-- Cross-machine/person: attach both files. If repository policy requires a branch transfer, review both files for secrets, then force-add the ignored transient artifacts with `git add -f LUCIA_RELAY.json LUCIA_RELAY.md`. State explicitly that they must be consumed and removed after re-verification.
+- Another local agent or harness sharing the tree: give it both full paths and ask it to run `inspect` before editing.
+- Cross-machine/person: give the pushed repository ref plus both artifacts. The validator rejects a dirty tree, a HEAD absent from locally known remote branches, and machine-only paths. If repository policy requires the relay files on the branch, review them for secrets, then force-add the ignored transient artifacts with `git add -f LUCIA_RELAY.json LUCIA_RELAY.md`. State explicitly that they must be consumed and removed after re-verification.
 - Chat-only channel: paste the JSON artifact; it is canonical and can regenerate the Markdown view.
 
 Do not copy the conversation transcript. Transfer decisions, evidence, negative knowledge, and pointers to source-of-truth files.

package/skills/lucia-relay/scripts/relay.py

@@ -9,11 +9,11 @@ import hashlib
 import html
 import json
 import os
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 import re
 import subprocess
 import sys
-from typing import Any
+from typing import Any, Optional
 
 
 MANIFEST = "LUCIA_RELAY.json"
@@ -24,7 +24,13 @@ SECRET_PATTERNS = (
     re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"),
     re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
 )
-MACHINE_PATH = re.compile(r"(?:/Users/[^/\s]+|/home/[^/\s]+|[A-Za-z]:\\Users\\[^\\\s]+)")
+POSIX_ABSOLUTE_PATH = re.compile(
+    r"(?<![A-Za-z0-9+.\-:/~$%])/(?!/)[^\s\"'`<>]+"
+)
+WINDOWS_ABSOLUTE_PATH = re.compile(r"(?<![A-Za-z0-9])[A-Za-z]:[\\/][^\s\"'`<>]+")
+UNC_PATH = re.compile(r"(?<!\\)\\\\[^\\\s\"'`<>]+\\[^\s\"'`<>]+")
+HOME_PATH = re.compile(r"(?<![A-Za-z0-9])(?:~|\$HOME|%USERPROFILE%)[\\/][^\s\"'`<>]+")
+FILE_URI_PATH = re.compile(r"\bfile:[^\s\"'`<>]+", re.IGNORECASE)
 
 
 def git(root: Path, *args: str) -> tuple[int, str]:
@@ -42,7 +48,13 @@ def git(root: Path, *args: str) -> tuple[int, str]:
 def repository_snapshot(root: Path) -> dict[str, Any]:
     rc, top = git(root, "rev-parse", "--show-toplevel")
     if rc != 0:
-        return {"head": None, "branch": None, "dirty": None, "diff_sha256": None}
+        return {
+            "head": None,
+            "branch": None,
+            "dirty": None,
+            "diff_sha256": None,
+            "known_remote_refs": [],
+        }
     repo = Path(top)
     head_rc, head = git(repo, "rev-parse", "HEAD")
     _, branch = git(repo, "branch", "--show-current")
@@ -82,22 +94,38 @@ def repository_snapshot(root: Path) -> dict[str, Any]:
         except OSError as exc:
             digest.update(f"unreadable:{exc.errno}".encode())
     fingerprint = digest.hexdigest()
+    known_remote_refs: list[str] = []
+    if head_rc == 0:
+        _, remote_refs = git(
+            repo,
+            "for-each-ref",
+            "--contains=HEAD",
+            "--format=%(refname)",
+            "refs/remotes",
+        )
+        known_remote_refs = sorted(
+            ref[len("refs/remotes/") :]
+            for ref in remote_refs.splitlines()
+            if ref.startswith("refs/remotes/") and not ref.endswith("/HEAD")
+        )
     return {
         "head": head if head_rc == 0 else None,
         "branch": branch or "(detached)",
         "dirty": bool(modified or untracked),
         "diff_sha256": fingerprint,
+        "known_remote_refs": known_remote_refs,
         "files": {"modified": modified, "untracked": untracked},
     }
 
 
-def draft(root: Path) -> dict[str, Any]:
+def draft(root: Path, recipient: str) -> dict[str, Any]:
     snap = repository_snapshot(root)
     files = snap.pop("files", {"modified": [], "untracked": []})
     return {
-        "schema": 1,
+        "schema": 2,
         "kind": "luciazero-relay",
         "created_at": dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds"),
+        "route": {"recipient": recipient},
         "source": {
             "harness": os.environ.get("LUCIAZERO_HARNESS", "unknown"),
             "agent": None,
@@ -111,7 +139,7 @@ def draft(root: Path) -> dict[str, Any]:
             "next_step": {"kind": "command", "value": ""},
         },
         "verification": [],
-        "knowledge": {"read_first": [], "hypotheses": [], "landmines": []},
+        "knowledge": {"read_first": [], "inline": [], "hypotheses": [], "landmines": []},
         "files": files,
     }
 
@@ -135,13 +163,105 @@ def nonempty(value: Any) -> bool:
     return isinstance(value, str) and bool(value.strip())
 
 
+def string_values(value: Any):
+    if isinstance(value, str):
+        yield value
+    elif isinstance(value, dict):
+        for nested in value.values():
+            yield from string_values(nested)
+    elif isinstance(value, list):
+        for nested in value:
+            yield from string_values(nested)
+
+
+def machine_paths(data: dict[str, Any]) -> list[str]:
+    found: set[str] = set()
+    for value in string_values(data):
+        for pattern in (
+            POSIX_ABSOLUTE_PATH,
+            WINDOWS_ABSOLUTE_PATH,
+            UNC_PATH,
+            HOME_PATH,
+            FILE_URI_PATH,
+        ):
+            found.update(match.group(0) for match in pattern.finditer(value))
+    return sorted(found)
+
+
+def repo_pointer(value: Any) -> Optional[str]:
+    if not nonempty(value):
+        return None
+    # A short annotation may follow the path, as in
+    # "docs/lessons.md — quoted delimiters are parser syntax".
+    candidate = str(value).split(" — ", 1)[0].strip()
+    path = PurePosixPath(candidate)
+    if (
+        not candidate
+        or "\\" in candidate
+        or ":" in candidate
+        or path.is_absolute()
+        or any(part in ("", ".", "..") for part in path.parts)
+    ):
+        return None
+    return candidate
+
+
+def cross_machine_repository_errors(root: Path, data: dict[str, Any]) -> list[str]:
+    route = data.get("route") if isinstance(data.get("route"), dict) else {}
+    if route.get("recipient") != "cross-machine":
+        return []
+    repository = data.get("repository") if isinstance(data.get("repository"), dict) else {}
+    head = repository.get("head")
+    knowledge = data.get("knowledge") if isinstance(data.get("knowledge"), dict) else {}
+    read_first = knowledge.get("read_first")
+    if not isinstance(read_first, list):
+        return []
+    errors: list[str] = []
+    for index, item in enumerate(read_first):
+        path = repo_pointer(item)
+        if path is None:
+            errors.append(
+                f"knowledge.read_first[{index}] must start with one repo-relative path; move prose or local knowledge to knowledge.inline"
+            )
+            continue
+        if not nonempty(head):
+            errors.append(f"knowledge.read_first[{index}] cannot be checked without repository.head")
+            continue
+        rc, _ = git(root, "cat-file", "-e", f"{head}:{path}")
+        if rc != 0:
+            errors.append(
+                f"knowledge.read_first[{index}] path is not present in the pushed relay commit: {path}"
+            )
+            continue
+        _, entry = git(root, "ls-tree", str(head), "--", path)
+        if entry.startswith("120000 "):
+            errors.append(
+                f"knowledge.read_first[{index}] must not use a symlink for cross-machine delivery: {path}"
+            )
+    return errors
+
+
 def validate(data: dict[str, Any]) -> tuple[list[str], list[str]]:
     errors: list[str] = []
     warnings: list[str] = []
-    if data.get("schema") != 1:
-        errors.append("schema must equal 1")
+    schema = data.get("schema")
+    if schema not in (1, 2):
+        errors.append("schema must equal 1 or 2")
     if data.get("kind") != "luciazero-relay":
         errors.append("kind must equal luciazero-relay")
+    recipient = None
+    route = data.get("route")
+    if schema == 2:
+        if not isinstance(route, dict):
+            errors.append("route must be an object")
+        else:
+            recipient = route.get("recipient")
+            if recipient not in ("same-machine", "cross-machine"):
+                errors.append("route.recipient must be same-machine or cross-machine")
+    elif schema == 1:
+        warnings.append(
+            "legacy schema 1 has no recipient location; treat it as same-machine and create a new relay before routing cross-machine"
+        )
     if not nonempty(data.get("created_at")):
         errors.append("created_at is required")
     else:
@@ -202,6 +322,17 @@ def validate(data: dict[str, Any]) -> tuple[list[str], list[str]]:
         for key in ("read_first", "hypotheses", "landmines"):
             if not isinstance(knowledge.get(key), list):
                 errors.append(f"knowledge.{key} must be an array")
+        inline = knowledge.get("inline")
+        if schema == 2 and not isinstance(inline, list):
+            errors.append("knowledge.inline must be an array")
+        elif isinstance(inline, list):
+            for index, item in enumerate(inline):
+                prefix = f"knowledge.inline[{index}]"
+                if not isinstance(item, dict):
+                    errors.append(f"{prefix} must be an object")
+                    continue
+                if not nonempty(item.get("label")) or not nonempty(item.get("content")):
+                    errors.append(f"{prefix} requires label and content")
         hypotheses = knowledge.get("hypotheses")
         if isinstance(hypotheses, list):
             for index, item in enumerate(hypotheses):
@@ -224,6 +355,12 @@ def validate(data: dict[str, Any]) -> tuple[list[str], list[str]]:
         for key in ("head", "branch", "dirty", "diff_sha256"):
             if key not in repository:
                 errors.append(f"repository.{key} is required")
+        if schema == 2:
+            known_remote_refs = repository.get("known_remote_refs")
+            if not isinstance(known_remote_refs, list):
+                errors.append("repository.known_remote_refs must be an array")
+            elif not all(nonempty(ref) for ref in known_remote_refs):
+                errors.append("repository.known_remote_refs entries must be non-empty strings")
     files = data.get("files")
     if not isinstance(files, dict):
         errors.append("files must be an object")
@@ -235,8 +372,26 @@ def validate(data: dict[str, Any]) -> tuple[list[str], list[str]]:
     serialized = json.dumps(data, ensure_ascii=False)
     if any(pattern.search(serialized) for pattern in SECRET_PATTERNS):
         errors.append("possible secret or private key detected; remove it before routing")
-    if MACHINE_PATH.search(serialized):
-        warnings.append("machine-specific absolute path detected; prefer a repo-relative path")
+    local_paths = machine_paths(data)
+    if recipient == "cross-machine":
+        if local_paths:
+            errors.append(
+                "cross-machine relay contains machine-only paths: "
+                + ", ".join(local_paths[:3])
+                + (" ..." if len(local_paths) > 3 else "")
+                + "; use pushed repo-relative paths or copy the knowledge into knowledge.inline"
+            )
+        if isinstance(repository, dict):
+            if repository.get("dirty") is True:
+                errors.append(
+                    "cross-machine relay cannot depend on a dirty worktree; commit and push task files, then keep machine-local knowledge in knowledge.inline"
+                )
+            if not repository.get("known_remote_refs"):
+                errors.append(
+                    "cross-machine relay HEAD is not reachable from a locally known remote branch; push it before routing"
+                )
+    elif schema == 1 and local_paths:
+        warnings.append("legacy relay contains a machine-specific path and is not portable cross-machine")
     return errors, warnings
 
 
@@ -262,6 +417,20 @@ def bullets(values: Any, empty: str = "None recorded.") -> list[str]:
     return lines
 
 
+def inline_knowledge(values: Any) -> list[str]:
+    if not isinstance(values, list) or not values:
+        return ["None recorded."]
+    lines = []
+    for item in values:
+        if not isinstance(item, dict):
+            lines.append(f"- {code_inline(json.dumps(item, ensure_ascii=False, sort_keys=True))}")
+            continue
+        label = markdown_text(item.get("label", "unlabelled"))
+        content = markdown_text(item.get("content", "")).replace("\n", "<br>\n")
+        lines.append(f"- {label}: {content}")
+    return lines
+
+
 def table_cell(value: Any) -> str:
     text = str(value if value is not None else "not recorded").replace("\n", " ")
     return markdown_text(text)
@@ -274,6 +443,10 @@ def render_markdown(data: dict[str, Any]) -> str:
     knowledge = data.get("knowledge") if isinstance(data.get("knowledge"), dict) else {}
     files = data.get("files") if isinstance(data.get("files"), dict) else {}
     next_step = state.get("next_step") if isinstance(state.get("next_step"), dict) else {}
+    route = data.get("route") if isinstance(data.get("route"), dict) else {}
+    known_remote_refs = repo.get("known_remote_refs")
+    if not isinstance(known_remote_refs, list):
+        known_remote_refs = []
     out = [
         "# Lucia Relay",
         "",
@@ -281,6 +454,10 @@ def render_markdown(data: dict[str, Any]) -> str:
         "",
         f"Created: {markdown_text(data.get('created_at', 'not recorded'))}",
         f"Source: {markdown_text(source.get('harness', 'unknown'))} / {markdown_text(source.get('agent') or 'agent not named')}",
+    ]
+    if data.get("schema") == 2:
+        out.append(f"Recipient: {markdown_text(route.get('recipient', 'not recorded'))}")
+    out.extend([
         "",
         "## Goal",
         "",
@@ -292,6 +469,10 @@ def render_markdown(data: dict[str, Any]) -> str:
         f"- Branch: {code_inline(repo.get('branch') or 'not recorded')}",
         f"- Dirty: {code_inline(repo.get('dirty'))}",
         f"- Diff SHA-256: {code_inline(repo.get('diff_sha256') or 'not recorded')}",
+    ])
+    if data.get("schema") == 2:
+        out.append(f"- Known remote refs: {code_inline(', '.join(str(ref) for ref in known_remote_refs) or 'none')}")
+    out.extend([
         "",
         "## Done",
         "",
@@ -309,7 +490,7 @@ def render_markdown(data: dict[str, Any]) -> str:
         "",
         "| Command | Exit | Decisive line | Run at |",
         "|---|---:|---|---|",
-    ]
+    ])
     verification = data.get("verification")
     if isinstance(verification, list) and verification:
         for item in verification:
@@ -324,6 +505,8 @@ def render_markdown(data: dict[str, Any]) -> str:
     else:
         out.append("| Not run | — | No verification evidence recorded | — |")
     out.extend(["", "## Read first", "", *bullets(knowledge.get("read_first"))])
+    if data.get("schema") == 2:
+        out.extend(["", "## Inline knowledge", "", *inline_knowledge(knowledge.get("inline"))])
     out.extend(["", "## Hypotheses", "", *bullets(knowledge.get("hypotheses"))])
     out.extend(["", "## Landmines", "", *bullets(knowledge.get("landmines"))])
     out.extend(["", "## Files", "", "Modified:", "", *bullets(files.get("modified"))])
@@ -348,9 +531,20 @@ def inspect(root: Path, data: dict[str, Any], check_human: bool = False) -> dict
                 if actual != render_markdown(data):
                     errors.append(f"{HUMAN} does not match {MANIFEST}; regenerate it before trusting or consuming the relay")
     current = repository_snapshot(root)
+    errors.extend(cross_machine_repository_errors(root, data))
     recorded = data.get("repository") if isinstance(data.get("repository"), dict) else {}
+    route = data.get("route") if isinstance(data.get("route"), dict) else {}
+    if route.get("recipient") == "cross-machine":
+        if current.get("dirty") is True:
+            errors.append("current cross-machine worktree is dirty; create a fresh relay after committing")
+        if not current.get("known_remote_refs"):
+            errors.append("current cross-machine HEAD is not reachable from a locally known remote branch")
     compared = ("head", "branch", "dirty", "diff_sha256")
     drift_fields = [key for key in compared if recorded.get(key) != current.get(key)]
+    if route.get("recipient") == "cross-machine" and drift_fields:
+        errors.append(
+            "cross-machine relay repository fingerprint is stale; create a fresh relay from the clean pushed tree"
+        )
     age_days = None
     try:
         created = dt.datetime.fromisoformat(str(data.get("created_at", "")).replace("Z", "+00:00"))
@@ -368,13 +562,26 @@ def inspect(root: Path, data: dict[str, Any], check_human: bool = False) -> dict
         "recorded_repository": recorded,
         "current_repository": current,
         "next_step": state.get("next_step"),
+        "recipient": (
+            data.get("route", {}).get("recipient")
+            if isinstance(data.get("route"), dict)
+            else "legacy / same-machine only"
+        ),
     }
 
 
 def parser() -> argparse.ArgumentParser:
     top = argparse.ArgumentParser(description=__doc__)
     sub = top.add_subparsers(dest="command", required=True)
-    for name in ("draft", "render", "validate", "inspect"):
+    draft_command = sub.add_parser("draft")
+    draft_command.add_argument("--root", default=".")
+    draft_command.add_argument(
+        "--recipient",
+        default="same-machine",
+        choices=("same-machine", "cross-machine"),
+        help="where the receiver will consume this relay (default: same-machine for legacy callers)",
+    )
+    for name in ("render", "validate", "inspect"):
         command = sub.add_parser(name)
         command.add_argument("--root", default=".")
         if name == "inspect":
@@ -389,7 +596,7 @@ def main() -> int:
     args = parser().parse_args()
     root = Path(args.root).resolve()
     if args.command == "draft":
-        print(json.dumps(draft(root), ensure_ascii=False, indent=2))
+        print(json.dumps(draft(root, args.recipient), ensure_ascii=False, indent=2))
         return 0
     try:
         data = load_manifest(root)
@@ -403,7 +610,7 @@ def main() -> int:
         for message in result["warnings"]:
             print(f"WARN  {message}", file=sys.stderr)
         if result["valid"]:
-            print("VALID luciazero-relay schema=1")
+            print(f"VALID luciazero-relay schema={data.get('schema')}")
         return 0 if result["valid"] else 1
     if args.command == "render":
         if not result["valid"]:
@@ -424,6 +631,7 @@ def main() -> int:
             print(json.dumps(result, ensure_ascii=False, indent=2))
         else:
             print(f"Relay: {'valid' if result['valid'] else 'invalid'}, age={result['age_days']}d")
+            print(f"Recipient: {result['recipient']}")
             print(f"Repository drift: {'yes' if result['repository_drift'] else 'no'}")
             if result["drift_fields"]:
                 print("Changed fingerprint fields: " + ", ".join(result["drift_fields"]))

package/uninstall.sh

@@ -59,9 +59,9 @@ remove_managed_file() {
 
 echo "Removing from ${CLAUDE_DIR}"
 
-rm -f "${CLAUDE_DIR}/${DOCTRINE}"
+remove_managed_file "${CLAUDE_DIR}/${DOCTRINE}" \
+  "${MANAGED_DIR}/${DOCTRINE}" "${SRC}/claude/${DOCTRINE}" "${DOCTRINE}"
 rm -f "${CLAUDE_DIR}/.luciazero-version"
-echo "  ok  ${DOCTRINE}"
 
 while IFS= read -r SKILL; do
   remove_managed_tree "${CLAUDE_DIR}/skills/${SKILL}" \