relic-mcp 0.3.1 → 0.3.3

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "relic",
       "description": "Publish a file from your machine as an encrypted, shareable link. The agent encrypts locally, uploads only ciphertext, and hands back a URL whose fragment holds the key, so the service stores something it cannot read.",
-      "version": "0.3.1",
+      "version": "0.3.3",
       "source": "./",
       "author": {
         "name": "The Bushido Collective",
@@ -21,6 +21,6 @@
     }
   ],
   "metadata": {
-    "version": "0.3.1"
+    "version": "0.3.3"
   }
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "relic",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Publish a file from your machine as an encrypted, shareable link. The agent encrypts locally, uploads only ciphertext, and hands back a URL whose fragment holds the key, so the service stores something it cannot read.",
   "mcpServers": "./mcp-servers.json",
   "author": {

package/dist/relic-mcp.js

@@ -642,9 +642,19 @@ function deriveRendererClass(content, filename) {
   return "binary";
 }
 // src/state.ts
-import { mkdir, readFile as readFile2, rename, stat, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import {
+  mkdir,
+  readFile as readFile2,
+  realpath,
+  rename,
+  stat,
+  writeFile
+} from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
 function publishStatePath() {
   const override = process.env["RELIC_PUBLISH_STATE"];
   if (override !== undefined && override.length > 0)
@@ -652,27 +662,137 @@ function publishStatePath() {
   const configRoot = process.env["XDG_CONFIG_HOME"] !== undefined && process.env["XDG_CONFIG_HOME"].length > 0 ? process.env["XDG_CONFIG_HOME"] : join(homedir(), ".config");
   return join(configRoot, "relic-mcp", "publish-state.json");
 }
-var writeChain = Promise.resolve();
-async function loadPublishState(relicId) {
-  let parsed;
+var runFile = promisify(execFile);
+function normalizeGitRemote(remote) {
+  const value = remote.trim().replace(/^git\+/i, "");
   try {
-    parsed = JSON.parse(await readFile2(publishStatePath(), "utf8"));
-  } catch (error) {
-    const code = error.code;
-    if (code === "ENOENT")
-      return;
-    if (error instanceof SyntaxError) {
-      throw new Error(`publish state at ${publishStatePath()} is not valid JSON. It cannot ` + "be read, so relics recorded in it cannot be republished from this " + "machine until it is fixed or removed.");
+    const url = new URL(value);
+    if (url.protocol === "file:") {
+      return fileURLToPath(url).replaceAll("\\", "/").replace(/\/+$/g, "").replace(/\.git$/i, "");
+    }
+    if (url.hostname.length > 0) {
+      const host = url.port.length > 0 ? `${url.hostname}:${url.port}` : url.hostname;
+      const path = url.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/i, "");
+      return `${host}/${path}`.toLowerCase();
+    }
+  } catch {}
+  const scp = value.match(/^(?:[^@/\s]+@)?([^:/\s]+):(.+)$/);
+  if (scp?.[1] !== undefined && scp[2] !== undefined) {
+    const path = scp[2].replace(/^\/+|\/+$/g, "").replace(/\.git$/i, "");
+    return `${scp[1]}/${path}`.toLowerCase();
+  }
+  return value.replaceAll("\\", "/").replace(/\/+$/g, "").replace(/\.git$/i, "");
+}
+async function gitOutput(directory, args) {
+  try {
+    const { stdout } = await runFile("git", ["-C", directory, ...args], {
+      encoding: "utf8",
+      maxBuffer: 1024 * 1024
+    });
+    const output = String(stdout).trim();
+    return output.length === 0 ? undefined : output;
+  } catch {
+    return;
+  }
+}
+async function resolveSourceIdentity(path) {
+  const absolutePath = resolve(path);
+  const sourceDirectory = dirname(absolutePath);
+  const repositoryRoot = await gitOutput(sourceDirectory, [
+    "rev-parse",
+    "--show-toplevel"
+  ]);
+  if (repositoryRoot !== undefined) {
+    const repositoryPrefix = await gitOutput(sourceDirectory, [
+      "rev-parse",
+      "--show-prefix"
+    ]);
+    const repositoryPath = `${repositoryPrefix ?? ""}${basename(absolutePath)}`.replaceAll("\\", "/");
+    const remoteNames = (await gitOutput(repositoryRoot, ["remote"]) ?? "").split(/\r?\n/).filter((name) => name.length > 0).sort();
+    const remoteName = remoteNames.includes("origin") ? "origin" : remoteNames[0];
+    if (remoteName !== undefined) {
+      const remote = await gitOutput(repositoryRoot, [
+        "remote",
+        "get-url",
+        remoteName
+      ]);
+      if (remote !== undefined) {
+        const repository = normalizeGitRemote(remote);
+        return {
+          identity: `git-remote:${encodeURIComponent(repository)}:` + encodeURIComponent(repositoryPath),
+          kind: "git_remote",
+          path: repositoryPath,
+          repository,
+          description: `${repositoryPath} in ${repository}`
+        };
+      }
+    }
+    const commonDirectory = await gitOutput(repositoryRoot, [
+      "rev-parse",
+      "--git-common-dir"
+    ]);
+    if (commonDirectory !== undefined) {
+      const repository = await realpath(isAbsolute(commonDirectory) ? commonDirectory : resolve(repositoryRoot, commonDirectory));
+      return {
+        identity: `git-common-dir:${encodeURIComponent(repository)}:` + encodeURIComponent(repositoryPath),
+        kind: "git_common_dir",
+        path: repositoryPath,
+        repository,
+        description: `${repositoryPath} in Git repository ${repository}`
+      };
     }
-    throw new Error(`could not read publish state at ${publishStatePath()}: ${code}`);
   }
-  const entry = parsed?.relics?.[relicId];
+  const canonicalPath = await realpath(absolutePath);
+  return {
+    identity: `realpath:${encodeURIComponent(canonicalPath)}`,
+    kind: "realpath",
+    path: canonicalPath,
+    description: canonicalPath
+  };
+}
+var writeChain = Promise.resolve();
+async function loadPublishState(relicId) {
+  const parsed = await readWholeFile(publishStatePath());
+  return validatePublishStateEntry(parsed?.relics?.[relicId], relicId);
+}
+function isSourceIdentity(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const source = value;
+  return typeof source["identity"] === "string" && (source["kind"] === "git_remote" || source["kind"] === "git_common_dir" || source["kind"] === "realpath") && typeof source["path"] === "string" && (source["repository"] === undefined || typeof source["repository"] === "string") && typeof source["description"] === "string";
+}
+function validatePublishStateEntry(entry, relicId) {
   if (entry === undefined)
     return;
-  if (typeof entry !== "object" || typeof entry.key !== "string" || typeof entry.publish_token !== "string" || typeof entry.version !== "number" || !Number.isSafeInteger(entry.version) || entry.version < 1) {
-    throw new Error(`publish state at ${publishStatePath()} holds a malformed entry for ` + "this relic id.");
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    throw new Error(`publish state at ${publishStatePath()} holds a malformed entry for ` + `relic ${relicId}.`);
   }
-  return entry;
+  const candidate = entry;
+  if (typeof candidate["key"] !== "string" || typeof candidate["publish_token"] !== "string" || typeof candidate["version"] !== "number" || !Number.isSafeInteger(candidate["version"]) || candidate["version"] < 1 || candidate["source"] !== undefined && !isSourceIdentity(candidate["source"])) {
+    throw new Error(`publish state at ${publishStatePath()} holds a malformed entry for ` + `relic ${relicId}.`);
+  }
+  return candidate;
+}
+async function loadPublishedSource(source) {
+  const parsed = await readWholeFile(publishStatePath());
+  const sources = parsed?.sources;
+  if (sources === undefined)
+    return;
+  if (sources === null || typeof sources !== "object" || Array.isArray(sources)) {
+    throw new Error(`publish state at ${publishStatePath()} holds a malformed source index.`);
+  }
+  const relicId = sources[source.identity];
+  if (relicId === undefined)
+    return;
+  if (typeof relicId !== "string" || relicId.length === 0) {
+    throw new Error(`publish state at ${publishStatePath()} holds a malformed source match.`);
+  }
+  const state = validatePublishStateEntry(parsed?.relics?.[relicId], relicId);
+  if (state?.source?.identity !== source.identity) {
+    throw new Error(`publish state at ${publishStatePath()} holds a source match without ` + "its relic entry.");
+  }
+  return { relic_id: relicId, state, source: state.source };
 }
 async function savePublishState(relicId, state) {
   const run = writeChain.then(() => writeEntry(relicId, state));
@@ -686,9 +806,33 @@ async function writeEntry(relicId, state) {
   const dir = dirname(path);
   await mkdir(dir, { mode: 448, recursive: true });
   const existing = await readWholeFile(path);
-  const relics = { ...existing?.relics, [relicId]: state };
+  const storedRelics = existing?.["relics"];
+  if (storedRelics !== undefined && (storedRelics === null || typeof storedRelics !== "object" || Array.isArray(storedRelics))) {
+    throw new Error(`publish state at ${path} holds malformed relic entries.`);
+  }
+  const oldEntry = storedRelics?.[relicId];
+  const relics = {
+    ...storedRelics,
+    [relicId]: {
+      ...oldEntry !== null && typeof oldEntry === "object" && !Array.isArray(oldEntry) ? oldEntry : {},
+      ...state
+    }
+  };
+  const storedSources = existing?.["sources"];
+  if (storedSources !== undefined && (storedSources === null || typeof storedSources !== "object" || Array.isArray(storedSources))) {
+    throw new Error(`publish state at ${path} holds a malformed source index.`);
+  }
+  const sources = {
+    ...storedSources,
+    ...state.source === undefined ? {} : { [state.source.identity]: relicId }
+  };
+  const next = {
+    ...existing,
+    relics,
+    ...storedSources === undefined && state.source === undefined ? {} : { sources }
+  };
   const temp = `${path}.tmp`;
-  await writeFile(temp, `${JSON.stringify({ relics }, null, 2)}
+  await writeFile(temp, `${JSON.stringify(next, null, 2)}
 `, {
     mode: 384
   });
@@ -706,7 +850,7 @@ async function readWholeFile(path) {
   }
   try {
     const parsed = JSON.parse(raw);
-    if (parsed === null || typeof parsed !== "object") {
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new Error("not an object");
     }
     return parsed;
@@ -739,8 +883,56 @@ class ServerRefusal extends Error {
     this.problem = problem;
   }
 }
+function republishToolCall(relicId, path) {
+  return {
+    name: "relic_republish",
+    arguments: { relic_id: relicId, path }
+  };
+}
+async function lookupResolvedSource(resolvedPath, deps) {
+  let source;
+  try {
+    source = await (deps.identifySource ?? resolveSourceIdentity)(resolvedPath);
+  } catch (error) {
+    const code = error.code;
+    throw new PublishError(code === "ENOENT" ? "source_not_found" : "source_unreadable", `could not resolve source identity for ${resolvedPath}: ` + error.message, { path: resolvedPath });
+  }
+  try {
+    const published = await loadPublishedSource(source);
+    return {
+      resolved_path: resolvedPath,
+      source,
+      ...published === undefined ? {} : {
+        match: {
+          relic_id: published.relic_id,
+          version: published.state.version,
+          source: published.source
+        }
+      }
+    };
+  } catch (error) {
+    throw new PublishError("local_state_unreadable", error.message);
+  }
+}
+async function lookupPublishedSource(path, deps) {
+  return lookupResolvedSource(deps.files.resolve(path), deps);
+}
 async function publish(input, deps) {
   const source = await readSource(input.path, deps.files);
+  const sourceLookup = await lookupResolvedSource(source.resolvedPath, deps);
+  if (sourceLookup.match !== undefined && input.force_new !== true) {
+    const match = sourceLookup.match;
+    const republishCall = republishToolCall(match.relic_id, source.resolvedPath);
+    const cost = "a second URL that nobody holding the first one will ever see";
+    throw new PublishError("source_already_published", `${match.source.description} is already version ${match.version} of ` + `relic ${match.relic_id}. Publishing it as new would cost ${cost}. ` + `Call relic_republish(${JSON.stringify(republishCall.arguments)}) ` + "instead. Set force_new to true only when you intend a separate relic.", {
+      relic_id: match.relic_id,
+      version: match.version,
+      source_identity: match.source.identity,
+      source_description: match.source.description,
+      cost,
+      republish_call: republishCall
+    });
+  }
   const challenge = await postJson(deps, `${deps.serviceOrigin}/api/challenge`, {});
   const sizeLimit = Number(challenge["size_limit_bytes"]);
   const sizeBasis = String(challenge["size_basis"]);
@@ -793,7 +985,8 @@ async function publish(input, deps) {
       await savePublishState(relicId, {
         key: encodeKey(key),
         publish_token: publishToken,
-        version: 1
+        version: 1,
+        source: sourceLookup.source
       });
     } catch (error) {
       throw new PublishError("local_state_write_failed", "the relic is published and the link works, but recording it for " + `later republishing failed, so it cannot be republished from this ` + `machine: ${error.message}`, { relic_id: relicId, url });
@@ -968,11 +1161,13 @@ async function republish(input, deps) {
 var TOOL_NAME = "relic_publish";
 var DESCRIBE_TOOL_NAME = "relic_describe_client";
 var REPUBLISH_TOOL_NAME = "relic_republish";
+var LOOKUP_TOOL_NAME = "relic_lookup_source";
 var MAX_TTL_DAYS = 3650;
+var VERSION_HISTORY_DISCLOSURE = "Anyone holding a relic's link can fetch every version it has ever held, " + "so republishing does not withdraw earlier content.";
 var TOOL_DEFINITION = {
   name: TOOL_NAME,
   title: "Publish a relic",
-  description: "Encrypt a file on this machine and publish it as a relic, returning a " + "shareable URL. The encryption key is generated locally and never sent " + "to the service. Takes a filesystem path, never inline content.",
+  description: "Encrypt a file on this machine and publish it as a new relic, returning " + "a shareable URL. Publishing an update this way costs a second URL that " + "nobody holding the first one will ever see; use relic_republish instead " + "so the existing URL keeps working. " + VERSION_HISTORY_DISCLOSURE + " The encryption key is generated locally and never sent to the service. " + "Takes a filesystem path, never " + "inline content.",
   inputSchema: {
     type: "object",
     properties: {
@@ -989,6 +1184,11 @@ var TOOL_DEFINITION = {
         minimum: 1,
         maximum: MAX_TTL_DAYS,
         description: "Optional. Gives the relic a lifetime in days. Omit it and the " + "relic is kept until it is deleted. Shorter is better for " + "sensitive content."
+      },
+      force_new: {
+        type: "boolean",
+        default: false,
+        description: "Optional. Publish a deliberately separate relic even when this " + "machine already published the same source. Defaults to false. Use " + "only when you want two independent URLs for one file."
       }
     },
     required: ["path"],
@@ -1028,7 +1228,7 @@ var TOOL_DEFINITION = {
 var REPUBLISH_TOOL_DEFINITION = {
   name: REPUBLISH_TOOL_NAME,
   title: "Republish a relic",
-  description: "Publish a new version of a relic this machine originally published, " + "encrypting under the same key so the existing share URL keeps working. " + "Only possible from the machine that holds the relic's key and publish " + "token; a relic that was taken down can never be revived.",
+  description: "Publish a new version of a relic this machine originally published, " + "encrypting under the same key so the existing share URL keeps working. " + VERSION_HISTORY_DISCLOSURE + " Only possible from the machine that holds the relic's key and publish " + "token; a relic that was taken down can never be revived.",
   inputSchema: {
     type: "object",
     properties: {
@@ -1083,6 +1283,60 @@ var REPUBLISH_TOOL_DEFINITION = {
     additionalProperties: false
   }
 };
+var LOOKUP_TOOL_DEFINITION = {
+  name: LOOKUP_TOOL_NAME,
+  title: "Look up a published source",
+  description: "Look up whether this machine already published a file and return the " + "relic id needed by relic_republish. Reads local publish state only and " + "never calls the service.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Filesystem path to the source to look up."
+      }
+    },
+    required: ["path"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      found: { type: "boolean" },
+      relic_id: { type: ["string", "null"] },
+      version: { type: ["integer", "null"], minimum: 1 },
+      resolved_path: { type: "string" },
+      source_identity: { type: "string" },
+      source_description: { type: "string" },
+      republish_call: {
+        type: ["object", "null"],
+        properties: {
+          name: { type: "string", const: REPUBLISH_TOOL_NAME },
+          arguments: {
+            type: "object",
+            properties: {
+              relic_id: { type: "string" },
+              path: { type: "string" }
+            },
+            required: ["relic_id", "path"],
+            additionalProperties: false
+          }
+        },
+        required: ["name", "arguments"],
+        additionalProperties: false
+      }
+    },
+    required: [
+      "found",
+      "relic_id",
+      "version",
+      "resolved_path",
+      "source_identity",
+      "source_description",
+      "republish_call"
+    ],
+    additionalProperties: false
+  }
+};
 var DESCRIBE_TOOL_DEFINITION = {
   name: DESCRIBE_TOOL_NAME,
   title: "Describe the Relic client",
@@ -1093,21 +1347,22 @@ var DESCRIBE_TOOL_DEFINITION = {
     additionalProperties: false
   }
 };
-var SERVER_VERSION = "0.3.1";
+var SERVER_VERSION = "0.3.3";
 var SERVER_INFO = {
   name: "relic",
   title: "Relic",
   version: SERVER_VERSION
 };
 var CAPABILITIES = { tools: {} };
-var INSTRUCTIONS = `Relic turns a file on this machine into an encrypted link. Encryption happens locally, only ciphertext is uploaded, and the key lives in the URL fragment, which browsers never send to a server.
+var INSTRUCTIONS = `Relic encrypts a file on this machine and uploads only ciphertext. The key lives in the URL fragment, which browsers never send to a server.
 
-Four things that change how you should act:
+Five things that change how you should act:
 
 1. The link is the credential. Anyone holding it, fragment included, can read the file. Do not paste it into a tracker, a log, or a public channel.
 2. Publishing puts the key in this transcript. That is structural rather than a defect, and worth saying plainly when you hand the link over.
-3. A relic can be republished only from the machine that published it, which is where its key and publish token are stored. Anywhere else it refuses, and no retry changes that.
-4. Rendered HTML and JSX run in an isolated frame with no network access. Inline the styles, scripts, fonts, and images a page needs, because a CDN reference renders as nothing. Decide that before you write the file.`;
+3. Check existing sources with relic_lookup_source. Use relic_republish when found; relic_publish otherwise costs a second URL. ${VERSION_HISTORY_DISCLOSURE}
+4. A relic can be republished only from the machine that published it, which is where its key and publish token are stored. Anywhere else it refuses, and no retry changes that.
+5. Rendered HTML and JSX run in an isolated frame with no network access. Inline the styles, scripts, fonts, and images a page needs, because a CDN reference renders as nothing. Decide that before you write the file.`;
 async function handleMessage(message, deps) {
   if (message.id === undefined)
     return;
@@ -1151,6 +1406,7 @@ async function handleMessage(message, deps) {
         result: {
           tools: [
             TOOL_DEFINITION,
+            LOOKUP_TOOL_DEFINITION,
             REPUBLISH_TOOL_DEFINITION,
             DESCRIBE_TOOL_DEFINITION
           ]
@@ -1181,13 +1437,16 @@ async function callTool(id2, params, deps) {
           key_transmitted_to_service: false,
           plaintext_transmitted_to_service: false,
           ciphertext_destination: "object storage, via a signed URL",
-          local_publish_state: "relic id, key, and publish token per relic, written 0600 under " + "the user config directory; never printed, never sent",
+          local_publish_state: "relic id, source identity, key, and publish token per relic, " + "written 0600 under the user config directory; key and token " + "are never printed or sent",
           service_origin: deps.serviceOrigin
         },
         isError: false
       }
     };
   }
+  if (params["name"] === LOOKUP_TOOL_NAME) {
+    return callLookup(id2, params, deps);
+  }
   if (params["name"] === REPUBLISH_TOOL_NAME) {
     return callRepublish(id2, params, deps);
   }
@@ -1204,8 +1463,17 @@ async function callTool(id2, params, deps) {
   if (!ttlDays.ok) {
     return errorResponse(id2, ERROR_CODES.invalidParams, `\`ttl_days\` must be an integer between 1 and ${MAX_TTL_DAYS}, or ` + "omitted to keep the relic until it is deleted");
   }
+  const forceNew = args["force_new"];
+  if (forceNew !== undefined && typeof forceNew !== "boolean") {
+    return errorResponse(id2, ERROR_CODES.invalidParams, "`force_new` must be a boolean or omitted");
+  }
   try {
-    const result = await publish({ path, filename, ttl_days: ttlDays.days }, deps);
+    const result = await publish({
+      path,
+      filename,
+      ttl_days: ttlDays.days,
+      force_new: forceNew === true
+    }, deps);
     return {
       jsonrpc: "2.0",
       id: id2,
@@ -1219,7 +1487,8 @@ async function callTool(id2, params, deps) {
 
 ` + (result.relic_expires_at === null ? "It does not expire; it is kept until it is deleted. " : `Expires ${result.relic_expires_at}. `) + "Anyone with this link, " + "including its fragment, can read the file. The key is in the " + "fragment and it is now in this transcript. This machine can " + `republish it later; the link will not change.
 ` + isolationNote(result.renderer_class) + `What Relic knows: ${result.disclosure_url}`
-          }
+          },
+          { type: "text", text: VERSION_HISTORY_DISCLOSURE }
         ],
         structuredContent: result,
         isError: false
@@ -1229,6 +1498,44 @@ async function callTool(id2, params, deps) {
     return { jsonrpc: "2.0", id: id2, result: toolError(error) };
   }
 }
+async function callLookup(id2, params, deps) {
+  const args = params["arguments"] ?? {};
+  const path = args["path"];
+  if (typeof path !== "string" || path.length === 0) {
+    return errorResponse(id2, ERROR_CODES.invalidParams, "`path` is required and must be a string");
+  }
+  try {
+    const lookup = await lookupPublishedSource(path, deps);
+    const match = lookup.match;
+    const republishCall = match === undefined ? null : republishToolCall(match.relic_id, lookup.resolved_path);
+    const structuredContent = {
+      found: match !== undefined,
+      relic_id: match?.relic_id ?? null,
+      version: match?.version ?? null,
+      resolved_path: lookup.resolved_path,
+      source_identity: lookup.source.identity,
+      source_description: lookup.source.description,
+      republish_call: republishCall
+    };
+    return {
+      jsonrpc: "2.0",
+      id: id2,
+      result: {
+        content: [
+          {
+            type: "text",
+            text: match === undefined ? `No prior relic is recorded for ${lookup.source.description}.` : `Found ${lookup.source.description} as version ` + `${match.version} of relic ${match.relic_id}.
+` + `Call relic_republish(${JSON.stringify(republishCall?.arguments)}).`
+          }
+        ],
+        structuredContent,
+        isError: false
+      }
+    };
+  } catch (error) {
+    return { jsonrpc: "2.0", id: id2, result: toolError(error) };
+  }
+}
 async function callRepublish(id2, params, deps) {
   const args = params["arguments"] ?? {};
   const relicId = args["relic_id"];
@@ -1259,7 +1566,8 @@ async function callRepublish(id2, params, deps) {
 
 ` + (result.relic_expires_at === null ? "The relic does not expire; it is kept until it is deleted." : `Expires ${result.relic_expires_at}.`) + `
 ` + `What Relic knows: ${result.disclosure_url}`
-          }
+          },
+          { type: "text", text: VERSION_HISTORY_DISCLOSURE }
         ],
         structuredContent: result,
         isError: false
@@ -1333,13 +1641,14 @@ What the service operator can see: that a relic exists, roughly how big it is,
 what coarse class it was declared as, the publishing IP, and when it was
 fetched. Never the contents, and never the key.
 
-What this keeps on disk: for each relic you publish, its id, its key, and a
-publish token, in a 0600 file under your user config directory. That record
-is what lets a relic be republished later, and it is why republishing works
+What this keeps on disk: for each relic you publish, its id, source identity,
+key, and publish token, in a 0600 file under your user config directory. The
+source index lets a fresh session find the id for relic_republish. The key and
+token let that republish keep the same URL, and they are why republishing works
 only on the machine that published. The token's SHA-256 is the only copy the
-service ever holds, and neither secret is ever printed or logged. Deleting
-the file changes nothing for existing links; it only ends this machine's
-ability to update those relics.
+service ever holds, and neither secret is ever printed or logged. Deleting the
+file changes nothing for existing links; it only ends this machine's ability
+to update those relics.
 
 What this does NOT protect against: the key is returned to your agent in the
 URL, so it enters the model's context and your session transcript. That is
@@ -1450,8 +1759,8 @@ function createHttpHandler(deps, options = {}) {
 import { spawnSync } from "node:child_process";
 import { copyFile, mkdir as mkdir2, readFile as readFile3, stat as stat2, writeFile as writeFile2 } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname2, join as join2, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/install.ts
 var HARNESSES = [
@@ -1679,7 +1988,7 @@ function parseArgs(argv) {
   return options;
 }
 function packageRoot() {
-  return resolve(dirname2(fileURLToPath(import.meta.url)), "..");
+  return resolve2(dirname2(fileURLToPath2(import.meta.url)), "..");
 }
 async function exists(path) {
   return readFile3(path).then(() => true).catch(() => false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relic-mcp",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Publish a file as an encrypted relic. The key is generated on your machine and never sent to the service.",
   "license": "MIT",
   "type": "module",

package/skills/relic/SKILL.md

@@ -24,16 +24,39 @@ enters the conversation, so it is never in the transcript, never in a model
 context window, and never in whatever stores those. Do not read a file into
 context and pass its text; pass where it lives.
 
+When the task is to update the same source, call `relic_lookup_source` first:
+
+```
+relic_lookup_source(path: "/Users/me/Downloads/report.html")
+```
+
+It reads local machine state only. If the source was published before, it
+returns the relic id and the exact `relic_republish` call. This works across
+Git worktrees and clones of the same remote, so a fresh session does not need
+to retain the id from the first publish.
+
+Do not publish an update as a new relic. That costs a second URL that nobody
+holding the first one will ever see. `relic_publish` enforces this: when local
+state matches the source, it refuses and points to `relic_republish`.
+
+Anyone holding a relic's link can fetch every version it has ever held, so
+republishing does not withdraw earlier content. Republishing moves the artifact
+forward without retracting what came before. Deleting the relic still removes
+every version.
+
 Optional arguments worth knowing:
 
 - `filename` overrides the display name shown to the recipient.
 - `ttl_days` gives the link a lifetime in days, 1 to 3650. A relic is kept
   until it is deleted unless you set one. Shorter is better for anything
   sensitive: when the content should stop being available, say when.
+- `force_new` deliberately creates a separate relic from a source this machine
+  already published. Use it only when two independent URLs are the goal, never
+  to get past the update refusal.
 
-The result reports the relic as version 1 and its id. Keep the id if a later
-version of the same content will replace this one; that is what
-`relic_republish` is for.
+The result reports the relic as version 1 and its id. The client records that
+id with the source locally, so a later session can recover it with
+`relic_lookup_source`.
 
 ## Republishing