skillrepo 4.5.2 → 4.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.5.2",
+  "version": "4.7.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/list.mjs

@@ -56,7 +56,14 @@ export async function runList(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
   const flags = resolveFlags(argv);
 
-  const libraryResponse = await getLibrary(flags.serverUrl, flags.apiKey);
+  // `list` is a read-only drift check — it must NEVER set sync state.
+  // Use the manifest read (#1832): metadata only, no file bodies, and the
+  // server records no delivery for it. Per-skill drift is computed from
+  // on-disk SHAs + `.last-sync` below, never from the response body, so
+  // the empty `files` array a manifest returns is irrelevant here.
+  const libraryResponse = await getLibrary(flags.serverUrl, flags.apiKey, {
+    manifest: true,
+  });
 
   // Defensive guard: `list` calls getLibrary without an If-None-Match
   // header so it can't legitimately receive a 304 today. But getLibrary's

package/src/lib/http.mjs

@@ -305,10 +305,20 @@ async function mapErrorResponse(res, url) {
   if (res.status === 401) {
     // Derive the auth URL from the request URL's origin so users
     // running against staging see a staging hint, not a prod hint.
-    // `url` here is the full request URL (e.g.
-    // https://staging.skillrepo.dev/api/v1/library); `new URL(...).origin`
-    // gives us "https://staging.skillrepo.dev" which is what
-    // `cliAuthUrl` expects.
+    // `url` here is the full request URL — typically
+    // `https://staging.skillrepo.dev/api/v1/library` (canonical) or
+    // `https://api.staging.skillrepo.dev/v1/library` (subdomain alias
+    // per #1588). `new URL(...).origin` strips back to the host —
+    // `https://staging.skillrepo.dev` or `https://api.staging.skillrepo.dev`
+    // — and `cliAuthUrl` builds the `/cli/auth` URL from there.
+    //
+    // Known limitation: if the request URL uses the api.* / mcp.*
+    // subdomain, the resulting auth hint URL points at that subdomain
+    // (`https://api.staging.skillrepo.dev/cli/auth`), which 404s
+    // because /cli/auth only lives on the canonical host. Today the
+    // CLI defaults to the canonical URL so this is latent; surfaces
+    // only when a user passes `--url https://api.<env>.skillrepo.dev`
+    // explicitly. Tracked separately — not blocking this PR.
     let authUrl = DEFAULT_CLI_AUTH_URL;
     try {
       authUrl = cliAuthUrl(new URL(url).origin);
@@ -526,12 +536,20 @@ export async function validateAccessKey(serverUrl, apiKey, source = "validate")
  * @param {object} [opts]
  * @param {string} [opts.ifNoneMatch] - ETag to send as If-None-Match
  * @param {string} [opts.since]       - ISO timestamp for delta filter
+ * @param {boolean} [opts.manifest]   - Request a metadata-only manifest:
+ *   the server returns empty `files` for every skill and records NO
+ *   delivery. Used by `skillrepo list` for a read-only drift check that
+ *   must not set sync state (#1832).
  * @returns {Promise<LibrarySyncResult>}
  */
 export async function getLibrary(serverUrl, apiKey, opts = {}) {
   const base = normalizeUrl(serverUrl);
   const params = new URLSearchParams();
   if (opts.since) params.set("since", opts.since);
+  // Manifest mode (#1832): metadata-only, non-recording read used by
+  // `skillrepo list`. A peek must not set sync state, so the server
+  // returns empty `files` and records no delivery for this request.
+  if (opts.manifest) params.set("manifest", "1");
   const url = params.toString()
     ? `${base}/api/v1/library?${params.toString()}`
     : `${base}/api/v1/library`;
@@ -573,6 +591,56 @@ export async function getLibrary(serverUrl, apiKey, opts = {}) {
   };
 }
 
+/**
+ * POST /api/v1/library/sync-receipts — report confirmed local writes (#1832).
+ *
+ * Called by `runSync` AFTER it successfully writes skill files to disk.
+ * Carries the (owner, name, version) pairs actually written so the server
+ * records sync state from a confirmed write, never from a fetch response.
+ *
+ * Best-effort + retryable: the receipt is telemetry and the files are
+ * already on disk by the time we call this, so callers treat a failure as
+ * a non-fatal warning. Transient 5xx / network failures retry — the server
+ * dedups by `(user, skill, version, UTC day)` and stamps idempotently, so
+ * a replay is safe. A non-2xx after retries throws a typed error.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {object} receipt
+ * @param {{owner: string, name: string, version: string}[]} receipt.skills
+ *   The skills written to disk this sync. Empty array is a valid no-op.
+ * @param {string} receipt.syncedAt - ISO timestamp of the sync.
+ * @returns {Promise<{recorded: number}>}
+ */
+export async function postSyncReceipt(serverUrl, apiKey, receipt) {
+  const url = `${normalizeUrl(serverUrl)}/api/v1/library/sync-receipts`;
+  const res = await safeFetch(url, {
+    method: "POST",
+    headers: {
+      ...(await authHeaders(apiKey)),
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      syncedAt: receipt.syncedAt,
+      skills: receipt.skills,
+    }),
+    // Idempotent server-side (dedup bucket + idempotent UPDATE), so a
+    // transient 5xx / network blip is safe to retry.
+    retry: true,
+  });
+  if (!res.ok) {
+    const err = await mapErrorResponse(res, url);
+    if (err === null) {
+      throw validationError(
+        `The server at ${normalizeUrl(serverUrl)} does not expose ` +
+          `/api/v1/library/sync-receipts. Is --url correct?`,
+      );
+    }
+    throw err;
+  }
+  return parseJsonOrThrow(res, url);
+}
+
 // ── /api/v1/skills/[owner]/[name] ───────────────────────────────────────
 
 /**

package/src/lib/sync.mjs

@@ -69,7 +69,14 @@
  *                                   render accurate user messages (see
  *                                   init.mjs step 7).
  * @property {string} [syncedAt]
- * @property {string} syncedAt    - ISO timestamp from the server response
+ * @property {string} syncedAt    - ISO timestamp of the sync: the server
+ *                                   response `syncedAt` on a 200, or the
+ *                                   previously-cached sync timestamp on a
+ *                                   304 (the server sends no body). NOTE:
+ *                                   this is distinct from the re-assertion
+ *                                   receipt's own timestamp on a 304, which
+ *                                   is the CLI's "now" (a liveness signal),
+ *                                   not this cached value.
  *
  * @typedef {Object} SyncedSkillEntry
  * @property {string} version       - Version of the skill as synced (e.g. "1.4.0").
@@ -87,7 +94,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { getLibrary } from "./http.mjs";
+import { getLibrary, postSyncReceipt } from "./http.mjs";
 import {
   writeSkillDir,
   removeSkillDir,
@@ -417,7 +424,8 @@ export function deleteLastSyncEntry(owner, name) {
  *   2. Read the last-sync state file
  *   3. Call GET /api/v1/library with `If-None-Match` (if we have a
  *      cached ETag) AND `since` (always, for delta semantics)
- *   4. Short-circuit on 304 — return `notModified: true`
+ *   4. On 304 — re-assert the on-disk state via a receipt (liveness +
+ *      heal) and short-circuit with `notModified: true`
  *   5. For each skill in the response:
  *      a. Write it via `writeSkillDir` — overwrites if changed
  *      b. Skip writing skills with `filesIncomplete: true` (see comment)
@@ -425,7 +433,9 @@ export function deleteLastSyncEntry(owner, name) {
  *      a. Call `removeSkillDir` — deletes from all configured targets
  *   7. Persist the new ETag (if the response was complete) for the
  *      next sync
- *   8. Return the summary
+ *   8. Re-assert the full on-disk state via a sync receipt (#1832) —
+ *      the confirmed-write signal that sets team sync state
+ *   9. Return the summary
  *
  * Error handling: any thrown error from the network or filesystem
  * layer propagates unchanged. The caller (a command) decides how to
@@ -536,6 +546,23 @@ export async function runSync(options) {
 
   // Step 4: 304 short-circuit
   if (result.notModified) {
+    // Re-assert the on-disk state even though nothing changed (#1832).
+    // The library is unchanged, so what's on disk is exactly the prior
+    // `.last-sync` skills map. This receipt:
+    //   • is the liveness signal that REPLACES the GET-side 304 heartbeat
+    //     for receipt-era servers (>= 4.7.0 CLIs no longer trigger it), so
+    //     a deliberately-stable library doesn't drift to "stale"; and
+    //   • heals any delivery the server missed (a receipt POST that failed
+    //     on a prior sync), correcting drift in the safe direction.
+    // Timestamp is the CLI's "now" so freshness advances; the server's
+    // 5-minute future tolerance absorbs ordinary clock skew. Best-effort.
+    await reportReceipt(
+      serverUrl,
+      apiKey,
+      receiptEntriesFromSkillsMap(lastSync?.skills),
+      new Date().toISOString(),
+      stderr,
+    );
     return {
       added: 0,
       updated: 0,
@@ -696,11 +723,92 @@ export async function runSync(options) {
     }
   }
 
+  // Re-assert the full on-disk state via a sync receipt (#1832). This
+  // confirmed-write signal — not the fetch itself — is what sets team
+  // sync state. We post the COMPLETE post-sync on-disk set (`skillsMap`:
+  // carry-forward skills + the skills written this round), not just what
+  // changed, so the receipt heals any delivery the server missed (a prior
+  // receipt POST that failed) and re-stamps freshness, replacing the
+  // GET-side heartbeat. `skillsMap` already reflects exactly what is on
+  // disk: skills skipped for `filesIncomplete` keep their prior carry-
+  // forward version (still on disk) and tombstoned skills were deleted
+  // from the map, so a partial or delta sync still re-asserts precisely
+  // what landed on disk. The server dedups (user, skill, version, UTC
+  // day), so re-asserting unchanged versions doesn't bloat the event log.
+  // Best-effort: files are already written, so a failed receipt is a
+  // non-fatal warning, never a sync failure.
+  await reportReceipt(
+    serverUrl,
+    apiKey,
+    receiptEntriesFromSkillsMap(skillsMap),
+    result.syncedAt,
+    stderr,
+  );
+
   return summary;
 }
 
 // ── Internals ──────────────────────────────────────────────────────────
 
+/**
+ * Build sync-receipt entries from a `.last-sync` skills map (#1832).
+ *
+ * Each key is `"<owner>/<name>"`; the value carries the version label of
+ * the skill as written to disk. The returned `[{ owner, name, version }]`
+ * array is the CLI's assertion of what it actually has on disk — the
+ * evidence the server treats as the single source of truth for sync
+ * state. Entries with no version label are skipped: a skill with no
+ * published version can't resolve to a delivery server-side. Malformed
+ * keys (no `/`, empty owner/name) are skipped defensively rather than
+ * producing a bogus receipt entry.
+ *
+ * @param {Record<string, {version?: string}> | null | undefined} skillsMap
+ * @returns {{owner: string, name: string, version: string}[]}
+ */
+function receiptEntriesFromSkillsMap(skillsMap) {
+  /** @type {{owner: string, name: string, version: string}[]} */
+  const entries = [];
+  if (!skillsMap || typeof skillsMap !== "object") return entries;
+  for (const [key, entry] of Object.entries(skillsMap)) {
+    if (!entry || typeof entry !== "object") continue;
+    const version = typeof entry.version === "string" ? entry.version : "";
+    if (version === "") continue;
+    const slashAt = key.indexOf("/");
+    if (slashAt < 0) continue;
+    const owner = key.slice(0, slashAt);
+    const name = key.slice(slashAt + 1);
+    if (!owner || !name) continue;
+    entries.push({ owner, name, version });
+  }
+  return entries;
+}
+
+/**
+ * Post a sync receipt, best-effort (#1832). A no-op when `skills` is
+ * empty (nothing on disk to assert — e.g. an empty library). The skill
+ * files are already on disk and the server dedups replays, so a failed
+ * receipt is a non-fatal warning surfaced via the injected stderr
+ * stream — never a sync failure.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {{owner: string, name: string, version: string}[]} skills
+ * @param {string} syncedAt - ISO timestamp for the delivery + dedup key.
+ * @param {NodeJS.WritableStream} stderr
+ */
+async function reportReceipt(serverUrl, apiKey, skills, syncedAt, stderr) {
+  if (skills.length === 0) return;
+  try {
+    await postSyncReceipt(serverUrl, apiKey, { skills, syncedAt });
+  } catch (err) {
+    stderr.write(
+      `  warning: failed to report sync receipt (${err.message}). ` +
+        `Your skills are synced locally; team sync status may lag until ` +
+        `your next sync.\n`,
+    );
+  }
+}
+
 /**
  * Check whether ANY of the configured placement targets already
  * contains a directory for the given skill name. Used to distinguish

package/src/test/commands/list.test.mjs

@@ -92,6 +92,20 @@ describe("runList — happy path", () => {
     assert.match(out, /2 skills in your library/);
   });
 
+  it("makes a non-recording manifest read (#1832)", async () => {
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    // `list` is a peek — it must hit the metadata-only manifest path so
+    // the server records no delivery for it...
+    assert.equal(server.getLastLibraryManifest(), "1");
+    // ...and it never posts a sync receipt (that's a write-confirm signal).
+    assert.equal(server.getReceiptRequestCount(), 0);
+  });
+
   it("sorts alphabetically by owner then name", async () => {
     server.setLibraryResponse({
       skills: [

package/src/test/e2e/mock-server.mjs

@@ -91,6 +91,19 @@ export function createMockServer(initialPayload, options = {}) {
   /** @type {string | null} */
   let lastLibrarySince = null;
   let libraryRequestCount = 0;
+  // #1832 — `?manifest=1` capture for the GET /api/v1/library route so
+  // tests can assert `skillrepo list` made the non-recording manifest read.
+  /** @type {string | null} */
+  let lastLibraryManifest = null;
+
+  // #1832 — POST /api/v1/library/sync-receipts inspection + response slot.
+  // `lastReceipt` holds the most recent JSON-parsed receipt body;
+  // `receiptResponse` overrides the default 200 so tests can simulate
+  // failures (the CLI treats a failed receipt as a non-fatal warning).
+  let lastReceipt = null;
+  let receiptRequestCount = 0;
+  /** @type {{ status: number, body: any } | null} */
+  let receiptResponse = null;
 
   // PR3a mutable slots for POST/DELETE library routes
   //
@@ -274,6 +287,41 @@ export function createMockServer(initialPayload, options = {}) {
       return;
     }
 
+    // ── #1832: POST /api/v1/library/sync-receipts (confirmed-write) ─
+    //
+    // The CLI posts this after `runSync` writes skills to disk. Default
+    // 200 echoes a `recorded` count; tests can override via
+    // setReceiptResponse to exercise the non-fatal-warning path.
+    if (
+      url.pathname === "/api/v1/library/sync-receipts" &&
+      req.method === "POST"
+    ) {
+      if (!checkAuth(req, res)) return;
+      let body;
+      try {
+        body = rawBody.length > 0 ? JSON.parse(rawBody) : {};
+      } catch {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({ error: "Body must be JSON", code: "bad_request" }),
+        );
+        return;
+      }
+      lastReceipt = body;
+      receiptRequestCount++;
+      if (receiptResponse) {
+        res.writeHead(receiptResponse.status, {
+          "Content-Type": "application/json",
+        });
+        res.end(JSON.stringify(receiptResponse.body ?? {}));
+        return;
+      }
+      const recorded = Array.isArray(body?.skills) ? body.skills.length : 0;
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ recorded }));
+      return;
+    }
+
     // ── #1452: POST /api/v1/library (multipart file-push) ──────────
     //
     // Accepts multipart/form-data and returns a synthesized
@@ -507,6 +555,7 @@ export function createMockServer(initialPayload, options = {}) {
       const sinceParam = url.searchParams.get("since");
       lastLibraryIfNoneMatch = ifNoneMatch ?? null;
       lastLibrarySince = sinceParam ?? null;
+      lastLibraryManifest = url.searchParams.get("manifest");
       libraryRequestCount++;
       if (libraryEtag && ifNoneMatch === libraryEtag) {
         res.writeHead(304, { ETag: libraryEtag });
@@ -673,9 +722,53 @@ export function createMockServer(initialPayload, options = {}) {
     resetLibraryInspection() {
       lastLibraryIfNoneMatch = null;
       lastLibrarySince = null;
+      lastLibraryManifest = null;
       libraryRequestCount = 0;
     },
 
+    /**
+     * Inspect the inbound `?manifest=` query param from the LAST request
+     * to GET /api/v1/library. `"1"` means the client made the
+     * non-recording manifest read (#1832, `skillrepo list`); `null`
+     * means a normal recording sync.
+     */
+    getLastLibraryManifest() {
+      return lastLibraryManifest;
+    },
+
+    // ── #1832: sync-receipt slots ─────────────────────────────────
+
+    /**
+     * Return the most recent POST /api/v1/library/sync-receipts body
+     * (JSON-parsed), or null if none received. Tests assert on
+     * `.skills` (the confirmed-write list) and `.syncedAt`.
+     */
+    getLastReceipt() {
+      return lastReceipt;
+    },
+
+    /** Count of sync-receipt POSTs since server start or reset. */
+    getReceiptRequestCount() {
+      return receiptRequestCount;
+    },
+
+    /**
+     * Override the sync-receipt response to simulate a failure (e.g.
+     * `{ status: 500, body: { error: "boom" } }`). The CLI treats a
+     * failed receipt as a non-fatal warning, so tests use this to
+     * assert the sync still succeeds. Pass null to restore the 200.
+     */
+    setReceiptResponse(override) {
+      receiptResponse = override;
+    },
+
+    /** Reset sync-receipt inspection slots. */
+    resetReceipts() {
+      lastReceipt = null;
+      receiptRequestCount = 0;
+      receiptResponse = null;
+    },
+
     /** Register a single-skill response keyed by `owner/name`. */
     setSkillResponse(owner, name, skill) {
       skillResponses.set(`${owner}/${name}`, skill);

package/src/test/lib/http.test.mjs

@@ -35,6 +35,7 @@ import { once } from "node:events";
 import {
   validateAccessKey,
   getLibrary,
+  postSyncReceipt,
   getSkill,
   searchSkills,
   addSkillToLibrary,
@@ -520,6 +521,20 @@ describe("getLibrary", () => {
     }
   });
 
+  it("sends manifest=1 when the manifest option is set (#1832)", async () => {
+    let capturedUrl;
+    const srv = await startServer((req, res) => {
+      capturedUrl = req.url;
+      jsonRes(res, 200, { skills: [], removals: [], syncedAt: "x" });
+    });
+    try {
+      await getLibrary(srv.url, VALID_KEY, { manifest: true });
+      assert.match(capturedUrl, /[?&]manifest=1/);
+    } finally {
+      await srv.close();
+    }
+  });
+
   it("tolerates missing fields in the response (defaults applied)", async () => {
     const srv = await startServer((req, res) => {
       jsonRes(res, 200, {});
@@ -563,6 +578,94 @@ describe("getLibrary", () => {
   });
 });
 
+// ── postSyncReceipt ─────────────────────────────────────────────────────
+
+describe("postSyncReceipt", () => {
+  it("POSTs the receipt body and returns the parsed result", async () => {
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 200, { recorded: 2 });
+    });
+    try {
+      const result = await postSyncReceipt(srv.url, VALID_KEY, {
+        syncedAt: "2025-06-01T00:00:00Z",
+        skills: [
+          { owner: "alice", name: "pdf-helper", version: "1.0" },
+          { owner: "bob", name: "code-review", version: "2.1" },
+        ],
+      });
+      assert.equal(result.recorded, 2);
+      assert.equal(srv.lastRequest.method, "POST");
+      assert.match(srv.lastRequest.url, /\/api\/v1\/library\/sync-receipts$/);
+      assert.equal(
+        srv.lastRequest.headers.authorization,
+        `Bearer ${VALID_KEY}`,
+      );
+      assert.match(
+        srv.lastRequest.headers["content-type"],
+        /application\/json/,
+      );
+      const sent = JSON.parse(srv.lastRequest.body);
+      assert.equal(sent.syncedAt, "2025-06-01T00:00:00Z");
+      assert.equal(sent.skills.length, 2);
+      assert.deepEqual(sent.skills[0], {
+        owner: "alice",
+        name: "pdf-helper",
+        version: "1.0",
+      });
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws authError on 401", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 401, { error: "nope" }),
+    );
+    try {
+      await assert.rejects(
+        () =>
+          postSyncReceipt(srv.url, VALID_KEY, { syncedAt: "x", skills: [] }),
+        (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws validationError on 404 (endpoint missing — wrong URL)", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 404, { error: "nope" }),
+    );
+    try {
+      await assert.rejects(
+        () =>
+          postSyncReceipt(srv.url, VALID_KEY, { syncedAt: "x", skills: [] }),
+        (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws networkError on a persistent 5xx (runSync treats it as non-fatal)", async () => {
+    // Pins the http-layer contract: a 5xx must THROW so runSync's
+    // try/catch surfaces the non-fatal warning. If this ever started
+    // returning null instead, the warning path would silently break.
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 500, { error: "boom" }),
+    );
+    try {
+      await assert.rejects(
+        () =>
+          postSyncReceipt(srv.url, VALID_KEY, { syncedAt: "x", skills: [] }),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+});
+
 // ── getSkill ────────────────────────────────────────────────────────────
 
 describe("getSkill", () => {

package/src/test/lib/mcp-merge.test.mjs

@@ -76,7 +76,7 @@ describe("mergeMcpForVendors — happy path", () => {
   it("creates .mcp.json when it does not exist (claudeCode)", async () => {
     const results = await mergeMcpForVendors({
       vendors: ["claudeCode"],
-      mcpUrl: "https://skillrepo.dev/api/mcp",
+      mcpUrl: "https://mcp.skillrepo.dev",
       yes: true,
       io: { stdout, stderr },
     });
@@ -88,7 +88,7 @@ describe("mergeMcpForVendors — happy path", () => {
     const mcp = JSON.parse(readFileSync(join(process.cwd(), ".mcp.json"), "utf-8"));
     assert.ok(mcp.mcpServers?.skillrepo);
     assert.equal(mcp.mcpServers.skillrepo.type, "http");
-    assert.equal(mcp.mcpServers.skillrepo.url, "https://skillrepo.dev/api/mcp");
+    assert.equal(mcp.mcpServers.skillrepo.url, "https://mcp.skillrepo.dev");
   });
 
   it("merges into existing .mcp.json preserving other servers", async () => {

package/src/test/lib/sync.test.mjs

@@ -390,6 +390,269 @@ describe("runSync — write skills", () => {
   });
 });
 
+// ── runSync — sync receipts (#1832) ────────────────────────────────────
+
+describe("runSync — sync receipts (#1832)", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("posts a receipt with the skills it wrote", async () => {
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper"), makeSkill("code-review")],
+      removals: [],
+      syncedAt: "2025-06-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.equal(receipt.syncedAt, "2025-06-01T00:00:00Z");
+    const names = receipt.skills.map((s) => s.name).sort();
+    assert.deepEqual(names, ["code-review", "pdf-helper"]);
+    for (const s of receipt.skills) {
+      assert.equal(s.owner, "alice");
+      assert.equal(s.version, "1.0.0");
+    }
+  });
+
+  it("re-asserts the on-disk state on a 304 (liveness + heal), not nothing", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper")],
+      removals: [],
+      syncedAt: "2025-06-01T00:00:00Z",
+    });
+    // First sync writes + posts a receipt.
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.equal(server.getReceiptRequestCount(), 1);
+    server.resetReceipts();
+
+    // Second sync 304-short-circuits (etag matches, placement present) but
+    // STILL posts a receipt re-asserting the on-disk set. This is the
+    // liveness signal that replaces the GET-side 304 heartbeat for
+    // receipt-era servers, and it heals any delivery a prior failed
+    // receipt POST lost (#1832 PR B).
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(result.notModified, true);
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name),
+      ["pdf-helper"],
+    );
+    assert.equal(receipt.skills[0].version, "1.0.0");
+    // syncedAt on a 304 is the CLI's "now" (the server sends no body),
+    // so freshness advances — not the stale first-sync timestamp.
+    assert.ok(
+      Number.isFinite(new Date(receipt.syncedAt).getTime()),
+      "304 receipt carries a valid ISO syncedAt",
+    );
+    assert.notEqual(
+      receipt.syncedAt,
+      "2025-06-01T00:00:00Z",
+      "304 receipt uses the CLI's now, not the prior sync timestamp",
+    );
+    // Stronger than "not the fixture": prove the timestamp is wall-clock
+    // FRESH. A regression that stamped the receipt with any stale cached
+    // value (e.g. lastSync.syncedAt) could differ from the fixture and
+    // still pass the notEqual above — but it would fail this. The liveness
+    // signal that replaces the 304 heartbeat must advance every sync.
+    assert.ok(
+      Date.now() - new Date(receipt.syncedAt).getTime() < 60_000,
+      "304 receipt syncedAt must be wall-clock fresh (within the last minute)",
+    );
+  });
+
+  it("re-asserts the full on-disk set (carry-forward + newly written) on a delta sync", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha"), makeSkill("beta")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    // Library changes: only `gamma` is new this round; alpha+beta are
+    // unchanged and arrive only via the carry-forward `.last-sync` map.
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [makeSkill("gamma")],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+
+    assert.equal(result.notModified, false);
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    // The receipt re-asserts EVERYTHING on disk, not just the changed
+    // skill — that is what heals server drift and keeps freshness honest.
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name).sort(),
+      ["alpha", "beta", "gamma"],
+    );
+    // A 200 uses the server's response syncedAt for the delivery time.
+    assert.equal(receipt.syncedAt, "2025-01-02T00:00:00Z");
+  });
+
+  it("re-asserts carry-forward on a 200 delta that writes nothing new", async () => {
+    // Distinct from the 304 short-circuit: here the ETag changes (a real
+    // 200) but the response carries no skills to write, so nothing new
+    // lands on disk. The receipt must still re-assert the full carry-
+    // forward set — the 200 path's re-assertion is driven by the on-disk
+    // `.last-sync` map, not by what was written this round.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha"), makeSkill("beta")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+
+    assert.equal(result.notModified, false);
+    assert.equal(result.added, 0);
+    assert.equal(result.updated, 0);
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name).sort(),
+      ["alpha", "beta"],
+    );
+    assert.equal(receipt.syncedAt, "2025-01-02T00:00:00Z");
+  });
+
+  it("excludes a filesIncomplete skill from the receipt", async () => {
+    const incomplete = makeSkill("incomplete");
+    incomplete.filesIncomplete = true;
+    server.setLibraryResponse({
+      skills: [incomplete, makeSkill("complete")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name),
+      ["complete"],
+    );
+  });
+
+  it("re-asserts the OLD on-disk version when a newer version fails to inline (filesIncomplete carry-forward)", async () => {
+    // First sync writes pdf-helper@1.0.0.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    // The server tries to deliver pdf-helper@1.1.0 but its files fail to
+    // inline. The CLI skips the write (1.0.0 stays on disk) and must
+    // re-assert the OLD version it still has — not the version it failed
+    // to write, and not nothing.
+    const newer = makeSkill("pdf-helper");
+    newer.version = "1.1.0";
+    newer.filesIncomplete = true;
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [newer],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(receipt.skills, [
+      { owner: "alice", name: "pdf-helper", version: "1.0.0" },
+    ]);
+    // Freshness still advances on a partial sync: the receipt carries the
+    // SERVER's 200 response syncedAt (the fresh sync time), not the stale
+    // carry-forward entry's own recorded syncedAt.
+    assert.equal(receipt.syncedAt, "2025-01-02T00:00:00Z");
+  });
+
+  it("does NOT post a receipt when ALL skills are filesIncomplete (nothing on disk to assert)", async () => {
+    // A first sync where every skill is filesIncomplete writes nothing
+    // and has no carry-forward `.last-sync` baseline, so the post-sync
+    // on-disk set is empty and `reportReceipt`'s empty-skills guard skips
+    // the POST.
+    const a = makeSkill("inc-a");
+    a.filesIncomplete = true;
+    const b = makeSkill("inc-b");
+    b.filesIncomplete = true;
+    server.setLibraryResponse({ skills: [a, b], removals: [], syncedAt: "x" });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.equal(server.getReceiptRequestCount(), 0);
+  });
+
+  it("omits skills with no version label from the receipt", async () => {
+    const draft = makeSkill("draft");
+    draft.version = null;
+    server.setLibraryResponse({
+      skills: [draft, makeSkill("published")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name),
+      ["published"],
+    );
+  });
+
+  it("a failed receipt POST is non-fatal — the sync still succeeds", async () => {
+    const { createCaptureStream } = await import(
+      "../helpers/capture-stream.mjs"
+    );
+    const stderr = createCaptureStream();
+    server.setReceiptResponse({ status: 500, body: { error: "boom" } });
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      io: { stderr },
+    });
+    // Files still written, summary intact despite the receipt failure.
+    assert.equal(result.added, 1);
+    const dir = resolvePlacementDir("claudeProject", "pdf-helper");
+    assert.ok(existsSync(join(dir, "SKILL.md")));
+    assert.match(stderr.text(), /failed to report sync receipt/);
+  });
+});
+
 // ── runSync — skills map population (v2) ───────────────────────────────
 //
 // #1553 — every successful sync populates `.last-sync.skills` with the
@@ -684,6 +947,9 @@ describe("runSync — tombstones", () => {
     });
     await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
     assert.ok(existsSync(resolvePlacementDir("claudeProject", "doomed")));
+    // Reset receipt tracking so the tombstone-only sync below is measured
+    // from zero (the first sync legitimately posted one).
+    server.resetReceipts();
 
     // Now the server says it's removed (the response has the tombstone
     // AND the skill is no longer in skills[])
@@ -700,6 +966,39 @@ describe("runSync — tombstones", () => {
     });
     assert.equal(result.removed, 1);
     assert.ok(!existsSync(resolvePlacementDir("claudeProject", "doomed")));
+    // The `.last-sync` baseline was reset (rm above) and the only skill
+    // was tombstoned, so the post-sync on-disk set is empty → the
+    // re-assertion receipt has nothing to send and is skipped (#1832).
+    assert.equal(server.getReceiptRequestCount(), 0);
+  });
+
+  it("re-asserts surviving skills but excludes a tombstoned one", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("keep"), makeSkill("drop")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    // `drop` is tombstoned; `keep` stays on disk and must be re-asserted.
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [],
+      removals: [
+        { owner: "alice", name: "drop", removedAt: "2025-01-02T00:00:00Z" },
+      ],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name),
+      ["keep"],
+    );
   });
 
   it("applies removals BEFORE writes (re-add scenario)", async () => {

package/src/test/mergers/claude-mcp.test.mjs

@@ -22,14 +22,14 @@ afterEach(() => {
 describe("Claude Code MCP config merger", () => {
   it("creates .mcp.json when file does not exist", async () => {
     const { mergeClaudeMcpConfig } = await import("../../lib/mergers/claude-mcp.mjs");
-    const result = mergeClaudeMcpConfig("https://skillrepo.dev/api/mcp");
+    const result = mergeClaudeMcpConfig("https://mcp.skillrepo.dev");
 
     assert.equal(result.action, "created");
     assert.equal(result.path, ".mcp.json");
 
     const content = JSON.parse(readFileSync(join(tempDir, ".mcp.json"), "utf-8"));
     assert.equal(content.mcpServers.skillrepo.type, "http");
-    assert.equal(content.mcpServers.skillrepo.url, "https://skillrepo.dev/api/mcp");
+    assert.equal(content.mcpServers.skillrepo.url, "https://mcp.skillrepo.dev");
     assert.equal(content.mcpServers.skillrepo.headers.Authorization, "Bearer ${SKILLREPO_ACCESS_KEY}");
   });
 
@@ -44,7 +44,7 @@ describe("Claude Code MCP config merger", () => {
     };
     writeFileSync(join(tempDir, ".mcp.json"), JSON.stringify(existing));
 
-    const result = mergeClaudeMcpConfig("https://skillrepo.dev/api/mcp");
+    const result = mergeClaudeMcpConfig("https://mcp.skillrepo.dev");
 
     assert.equal(result.action, "merged"); // adding to existing file
     const content = JSON.parse(readFileSync(join(tempDir, ".mcp.json"), "utf-8"));
@@ -73,6 +73,6 @@ describe("Claude Code MCP config merger", () => {
     const { mergeClaudeMcpConfig } = await import("../../lib/mergers/claude-mcp.mjs");
     writeFileSync(join(tempDir, ".mcp.json"), "not json");
 
-    assert.throws(() => mergeClaudeMcpConfig("https://skillrepo.dev/api/mcp"), /invalid JSON/);
+    assert.throws(() => mergeClaudeMcpConfig("https://mcp.skillrepo.dev"), /invalid JSON/);
   });
 });

package/src/test/mergers/uninstall-claude-mcp.test.mjs

@@ -59,7 +59,7 @@ describe("removeClaudeMcp", () => {
           mcpServers: {
             skillrepo: {
               type: "http",
-              url: "https://skillrepo.dev/api/mcp",
+              url: "https://mcp.skillrepo.dev",
               headers: { Authorization: "Bearer ${SKILLREPO_ACCESS_KEY}" },
             },
             otherTool: {

package/src/test/mergers/uninstall-vscode-mcp.test.mjs

@@ -61,7 +61,7 @@ describe("removeVscodeMcp", () => {
           servers: {
             skillrepo: {
               type: "http",
-              url: "https://skillrepo.dev/api/mcp",
+              url: "https://mcp.skillrepo.dev",
               headers: { Authorization: "Bearer ${input:skillrepo-api-key}" },
             },
             anotherTool: {