@stigmer/cli 3.12.0 → 3.12.2

package/src/resources/apply/apply.ts

@@ -9,6 +9,8 @@
 import { create, fromJson, type JsonValue, type Message } from "@bufbuild/protobuf";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import {
   type ApiResourceMetadata,
   ApiResourceMetadataSchema,
@@ -131,14 +133,16 @@ export async function applyMessage(
   org: string,
   dryRun: boolean,
 ): Promise<ApplyOutcome> {
-  const warning = injectOrg(message, org);
+  const orgWarning = injectOrg(message, org);
   const created = (metaOf(message)?.id ?? "") === "";
 
   if (dryRun) {
-    return { result: buildDryRunResult(handler, message), warning };
+    return { result: buildDryRunResult(handler, message), warning: orgWarning };
   }
 
   const applied = await handler.apply(controller, message);
+  const visibilityWarning = await applyDeclaredVisibility(controller, handler, message, applied);
+  const warning = combineWarnings(orgWarning, visibilityWarning);
   const result = buildApplyResult(handler, applied, created);
   if (handler.kind === ApiResourceKind.mcp_server) {
     return { result, appliedMcpServer: applied as McpServer, warning, applied };
@@ -146,6 +150,63 @@ export async function applyMessage(
   return { result, warning, applied };
 }
 
+/**
+ * Land a manifest-declared visibility through the guarded door. Plain
+ * updates preserve the stored visibility on both editions (oss#573) — the
+ * `updateVisibility` RPC is the only mutation path, so when the applied
+ * resource comes back with a different level than the manifest declared,
+ * follow up with one RPC (the skill-push precedent: no-ops are skipped, an
+ * unchanged manifest costs nothing extra). Server-side guard rejections
+ * (unsupported level, default-instance) propagate as command failures —
+ * the spec update has landed at that point, and the error says so.
+ *
+ * Returns a warning (instead of following up) for kinds without the RPC:
+ * their manifests can only carry a level the create path already rejected,
+ * so a diff here means a pre-existing resource and an unsupported ask.
+ */
+async function applyDeclaredVisibility(
+  controller: ControllerFn,
+  handler: ApplyHandler,
+  message: Message,
+  applied: Message,
+): Promise<string | undefined> {
+  const declared = metaOf(message)?.visibility ?? ApiResourceVisibility.api_resource_visibility_unspecified;
+  if (declared === ApiResourceVisibility.api_resource_visibility_unspecified) return undefined;
+
+  const appliedMeta = metaOf(applied);
+  const resourceId = appliedMeta?.id ?? "";
+  if (resourceId === "" || appliedMeta?.visibility === declared) return undefined;
+
+  if (handler.updateVisibility === undefined) {
+    return (
+      `${handler.displayName} visibility cannot be changed declaratively — ` +
+      "the manifest's metadata.visibility was ignored (the stored value is kept)"
+    );
+  }
+
+  try {
+    const updated = await handler.updateVisibility(
+      controller,
+      create(UpdateVisibilityInputSchema, { resourceId, visibility: declared }),
+    );
+    // Reflect the landed level on the outcome the caller already holds.
+    const updatedMeta = metaOf(updated);
+    if (appliedMeta !== undefined && updatedMeta !== undefined) {
+      appliedMeta.visibility = updatedMeta.visibility;
+    }
+    return undefined;
+  } catch (err) {
+    throw new UsageError(
+      `${handler.displayName} spec applied, but the manifest's visibility change was rejected: ${(err as Error).message}`,
+    );
+  }
+}
+
+function combineWarnings(...warnings: (string | undefined)[]): string | undefined {
+  const present = warnings.filter((w): w is string => w !== undefined);
+  return present.length > 0 ? present.join("; ") : undefined;
+}
+
 /** Read a resource message's metadata (id/name/slug/org), if present. */
 export function resourceMetadata(message: Message): ApiResourceMetadata | undefined {
   return metaOf(message);

package/src/resources/apply/declarative.integration.test.ts

@@ -16,6 +16,7 @@ import { create } from "@bufbuild/protobuf";
 import { type ConnectRouter, createClient } from "@connectrpc/connect";
 import { connectNodeAdapter } from "@connectrpc/connect-node";
 import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
 import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import { SkillCommandController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/command_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -34,8 +35,12 @@ const openSessions = new Set<ServerHttp2Session>();
 
 let appliedProject: Project | undefined;
 
+// Ordered log of backend calls, for the discovery-before-dependents contract.
+let events: string[] = [];
+
 beforeEach(() => {
   appliedProject = undefined;
+  events = [];
 });
 
 function makeProject(dir: string): void {
@@ -53,7 +58,22 @@ function makeProject(dir: string): void {
 
 beforeAll(async () => {
   const routes = (router: ConnectRouter) => {
-    router.service(AgentCommandController, { apply: (req) => req });
+    router.service(AgentCommandController, {
+      apply: (req) => {
+        events.push("agent.apply");
+        return req;
+      },
+    });
+    router.service(McpServerCommandController, {
+      apply: (req) => {
+        events.push("mcpserver.apply");
+        return req;
+      },
+      connect: () => {
+        events.push("mcpserver.connect");
+        return {};
+      },
+    });
     router.service(SkillCommandController, {
       push: (req) =>
         create(SkillSchema, {
@@ -123,4 +143,62 @@ describe("applyDeclarative", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  it("discovers MCP capabilities before applying dependent resources", async () => {
+    // Pins the ordering contract behind apply-time enabled_tools validation
+    // (stigmer/stigmer#402): the server rejects agent enabled_tools against
+    // STORED capabilities, so discovery must refresh them between the MCP
+    // server applies and the applies that depend on them. Regressing to
+    // discovery-at-the-end resurrects the stale-capabilities race (a seedpack
+    // upgrade adding a tool + enabling it in an agent would fail bootstrap).
+    const dir = mkdtempSync(join(tmpdir(), "decl-it-order-"));
+    try {
+      writeFileSync(
+        join(dir, "stigmer.yaml"),
+        ["kind: Project", "metadata:", "  name: Ordered", "  slug: ordered", "spec:", "  description: d", ""].join("\n"),
+      );
+      // Named so a naive filename sort would apply the agent first — the
+      // reconciler must order by dependency, not by scan order.
+      writeFileSync(
+        join(dir, "a-agent.yaml"),
+        [
+          "kind: Agent",
+          "metadata:",
+          "  name: Consumer",
+          "  slug: consumer",
+          "spec:",
+          "  description: c",
+          "",
+        ].join("\n"),
+      );
+      writeFileSync(
+        join(dir, "z-server.yaml"),
+        [
+          "kind: McpServer",
+          "metadata:",
+          "  name: Tools",
+          "  slug: tools",
+          "spec:",
+          "  description: t",
+          "  stdio:",
+          "    command: npx",
+          "",
+        ].join("\n"),
+      );
+
+      const detect = detectTrack(dir);
+      const result = await applyDeclarative(detect, {
+        controller: controllerFn,
+        stigmer,
+        org: "acme",
+        info: () => {},
+        warn: () => {},
+      });
+
+      expect(result.status).toBe("success");
+      expect(events).toEqual(["mcpserver.apply", "mcpserver.connect", "agent.apply"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

package/src/resources/apply/declarative.ts

@@ -276,9 +276,9 @@ const DEFAULT_IGNORE_OPTIONS = { respectGitignore: true, extraIgnore: [] as stri
 
 /**
  * Reconcile a project's membership: push skills first (agents may reference
- * them), apply each resource through the shared apply core, collect references
- * to the member-eligible ones, run post-apply MCP discovery, then apply the
- * project with that exact member set so the server can reconcile by
+ * them), apply MCP servers and run capability discovery on them, apply the
+ * remaining resources, collect references to the member-eligible ones, then
+ * apply the project with that exact member set so the server can reconcile by
  * set-difference (orphan pruning is server-side; see S1 in commands/apply.ts).
  */
 export async function reconcileProjectMembers(
@@ -295,13 +295,14 @@ export async function reconcileProjectMembers(
     members.push(reference(deps.org, ApiResourceKind.skill, pushed.slug));
   }
 
-  // Then each resource, collecting member references from the APPLIED result so
-  // membership carries the server's authoritative slug. (This is the unified
-  // policy: the declarative track used to read the pre-apply YAML slug, the Go
-  // synthesis track read the applied result — converging on the applied result
-  // is correct for both and matches what the backend actually stored.)
+  // Each resource is applied through the shared apply core, collecting member
+  // references from the APPLIED result so membership carries the server's
+  // authoritative slug. (This is the unified policy: the declarative track
+  // used to read the pre-apply YAML slug, the Go synthesis track read the
+  // applied result — converging on the applied result is correct for both and
+  // matches what the backend actually stored.)
   const appliedMcpServers: McpServer[] = [];
-  for (const res of resources) {
+  const applyOne = async (res: ReconcileResource): Promise<void> => {
     const outcome = await applyMessage(deps.controller, res.handler, res.message, deps.org, false);
     if (outcome.warning !== undefined) deps.warn(outcome.warning);
     if (outcome.appliedMcpServer !== undefined) appliedMcpServers.push(outcome.appliedMcpServer);
@@ -309,9 +310,25 @@ export async function reconcileProjectMembers(
       const slug = memberSlugOf(outcome.applied);
       if (slug) members.push(reference(deps.org, res.handler.kind, slug));
     }
-  }
+  };
 
+  // MCP servers first, then capability discovery, then everything else — the
+  // dependency principle applied to capabilities, not just existence. The
+  // server validates agent enabled_tools against discovered capabilities at
+  // apply time (stigmer/stigmer#402), and the backend's own post-apply
+  // connect is asynchronous; discovering here means agents in this apply
+  // validate against the toolset this apply just shipped, not the previous
+  // generation's (which would falsely reject e.g. a seedpack upgrade that
+  // adds a tool and enables it in the same pass). Discovery stays
+  // best-effort: a failed connect warns, capabilities stay stale, and the
+  // dependent apply surfaces an actionable error listing last-known tools.
+  for (const res of resources) {
+    if (res.handler.kind === ApiResourceKind.mcp_server) await applyOne(res);
+  }
   await discoverAppliedMcpServers(deps.stigmer, appliedMcpServers, deps.org, deps.info);
+  for (const res of resources) {
+    if (res.handler.kind !== ApiResourceKind.mcp_server) await applyOne(res);
+  }
 
   injectOrg(project, deps.org);
   if (project.spec === undefined) project.spec = create(ProjectSpecSchema, {});

package/src/resources/apply/handlers.ts

@@ -24,6 +24,7 @@
 
 import type { DescMessage, DescService, Message } from "@bufbuild/protobuf";
 import type { Client } from "@connectrpc/connect";
+import type { UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import { type Session, SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import { SessionCommandController } from "@stigmer/protos/ai/stigmer/agentic/session/v1/command_pb";
 import {
@@ -54,6 +55,14 @@ export interface ApplyHandler {
   readonly applyOrder: number;
   /** Drive the controller's `apply` RPC with the full resource message. */
   apply(controller: ControllerFn, message: Message): Promise<Message>;
+  /**
+   * Drive the controller's `updateVisibility` RPC — the only door for
+   * visibility changes (plain updates preserve stored visibility, oss#573).
+   * Present exactly when the kind has the RPC; the apply core follows up
+   * through it when a manifest-declared level differs from the stored one.
+   * Manifest kinds inherit the binding from the SDK registry.
+   */
+  updateVisibility?(controller: ControllerFn, input: UpdateVisibilityInput): Promise<Message>;
 }
 
 // The SDK registry's applyOrder values end at schedule = 12; the extras slot
@@ -72,6 +81,7 @@ const CLI_EXTRA_HANDLERS: readonly ApplyHandler[] = [
     schema: WorkflowInstanceSchema,
     applyOrder: 13,
     apply: (c, m) => c(WorkflowInstanceCommandController).apply(m as WorkflowInstance),
+    updateVisibility: (c, i) => c(WorkflowInstanceCommandController).updateVisibility(i),
   },
   {
     kind: ApiResourceKind.session,

package/src/resources/skill.test.ts

@@ -1,13 +1,13 @@
 // Unit tests for the skill packaging layer: SKILL.md frontmatter parsing, the
 // ignore-filtered zip walk, dry-run analysis, and byte/hash formatting.
 
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import type { Stigmer } from "@stigmer/sdk";
-import { unzipSync } from "fflate";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { unzipSync, zipSync } from "fflate";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { classify, ExitCode } from "../errors/index.js";
 import {
   analyzeDryRun,
@@ -17,6 +17,8 @@ import {
   parseSkillMetadata,
   parseVisibility,
   pushSkill,
+  pushSkillFromArchive,
+  readSkillArchive,
   shortHash,
 } from "./skill.js";
 
@@ -113,12 +115,17 @@ describe("parseVisibility", () => {
 
 // A minimal fake of the SDK surface pushSkill touches: skill.push + skill.updateVisibility.
 function fakeClient(pushMeta: { id?: string; visibility?: ApiResourceVisibility }) {
-  const calls = { push: 0, updateVisibility: [] as Array<{ resourceId: string; visibility: ApiResourceVisibility }> };
+  const calls = {
+    push: 0,
+    pushedArtifacts: [] as Uint8Array[],
+    updateVisibility: [] as Array<{ resourceId: string; visibility: ApiResourceVisibility }>,
+  };
   const skillMessage = { metadata: { ...pushMeta } };
   const client = {
     skill: {
-      async push() {
+      async push(request?: { artifact?: Uint8Array }) {
         calls.push++;
+        if (request?.artifact !== undefined) calls.pushedArtifacts.push(request.artifact);
         return skillMessage;
       },
       async updateVisibility(input: { resourceId: string; visibility: ApiResourceVisibility }) {
@@ -199,6 +206,113 @@ describe("createSkillZip", () => {
   });
 });
 
+describe("createSkillZip determinism", () => {
+  // Version identity is the server-side SHA-256 of the zip bytes, so identical
+  // content must produce identical bytes no matter when or where it was
+  // checked out (stigmer/stigmer#671). Distinct source mtimes model the fresh
+  // CI checkout; distinct wall-clock runs are inherent to running twice.
+  it("produces byte-identical zips for identical content across mtimes and wall-clock time", () => {
+    const otherDir = mkdtempSync(join(tmpdir(), "skill-test-b-"));
+    vi.useFakeTimers();
+    try {
+      for (const d of [dir, otherDir]) {
+        writeFileSync(join(d, "SKILL.md"), SKILL_MD);
+        mkdirSync(join(d, "references"));
+        writeFileSync(join(d, "references", "guide.md"), "# Guide\n");
+      }
+      // Backdate one copy: same content, different filesystem timestamps
+      // (models a fresh CI checkout).
+      const past = new Date("2020-06-15T12:00:00Z");
+      utimesSync(join(otherDir, "SKILL.md"), past, past);
+      utimesSync(join(otherDir, "references", "guide.md"), past, past);
+
+      // Advance the clock between runs: without a pinned mtime, fflate stamps
+      // zip-creation time into every entry (DOS 2-second granularity), so two
+      // pushes minutes apart would differ even from the same directory.
+      vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+      const a = createSkillZip(dir, NO_IGNORE).bytes;
+      vi.setSystemTime(new Date("2026-01-01T00:05:00Z"));
+      const b = createSkillZip(otherDir, NO_IGNORE).bytes;
+      expect(Buffer.from(a).equals(Buffer.from(b))).toBe(true);
+    } finally {
+      vi.useRealTimers();
+      rmSync(otherDir, { recursive: true, force: true });
+    }
+  });
+
+  it("changes bytes when content changes", () => {
+    writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+    const before = createSkillZip(dir, NO_IGNORE).bytes;
+    writeFileSync(join(dir, "extra.md"), "new content\n");
+    const after = createSkillZip(dir, NO_IGNORE).bytes;
+    expect(Buffer.from(before).equals(Buffer.from(after))).toBe(false);
+  });
+});
+
+describe("readSkillArchive", () => {
+  function writeArchive(files: Record<string, string>): string {
+    const zipped = zipSync(
+      Object.fromEntries(Object.entries(files).map(([p, c]) => [p, new TextEncoder().encode(c)])),
+    );
+    const archivePath = join(dir, "skill.zip");
+    writeFileSync(archivePath, zipped);
+    return archivePath;
+  }
+
+  it("accepts an archive with a root SKILL.md and reports entry stats", () => {
+    const archivePath = writeArchive({
+      "SKILL.md": SKILL_MD,
+      "references/guide.md": "# Guide\n",
+    });
+    const archive = readSkillArchive(archivePath);
+    expect(archive.meta.name).toBe("my-skill");
+    expect(archive.fileCount).toBe(2);
+    expect(archive.totalSize).toBeGreaterThan(0);
+  });
+
+  it("rejects an archive whose SKILL.md is only nested (root-only contract, DD-018)", () => {
+    const archivePath = writeArchive({ "my-skill/SKILL.md": SKILL_MD });
+    expect(() => readSkillArchive(archivePath)).toThrow(/root of/);
+  });
+
+  it("rejects a file that is not a ZIP archive", () => {
+    const archivePath = join(dir, "not-a-zip.zip");
+    writeFileSync(archivePath, "plain text");
+    expect(() => readSkillArchive(archivePath)).toThrow(/not a valid ZIP/);
+  });
+
+  it("rejects a missing file with a usage error", () => {
+    const err = (() => {
+      try {
+        readSkillArchive(join(dir, "absent.zip"));
+      } catch (e) {
+        return e;
+      }
+    })();
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+});
+
+describe("pushSkillFromArchive", () => {
+  it("uploads the archive bytes untouched (checksum parity) and applies declared visibility", async () => {
+    const zipped = zipSync({
+      "SKILL.md": new TextEncoder().encode("---\nname: my-skill\nvisibility: public\n---\n# S\n"),
+    });
+    const archivePath = join(dir, "skill.zip");
+    writeFileSync(archivePath, zipped);
+    const { client, calls } = fakeClient({ id: "skill-123", visibility: ApiResourceVisibility.visibility_private });
+
+    const result = await pushSkillFromArchive(client, archivePath, "stigmer", "", "release v1.2.3");
+
+    expect(calls.push).toBe(1);
+    expect(Buffer.from(calls.pushedArtifacts[0]).equals(Buffer.from(zipped))).toBe(true);
+    expect(calls.updateVisibility).toEqual([
+      { resourceId: "skill-123", visibility: ApiResourceVisibility.visibility_public },
+    ]);
+    expect(result.skillName).toBe("my-skill");
+  });
+});
+
 describe("analyzeDryRun", () => {
   it("reports counts and pattern sources without producing bytes", () => {
     writeFileSync(join(dir, "SKILL.md"), SKILL_MD);

package/src/resources/skill.ts

@@ -14,13 +14,24 @@ import { GitProvenanceSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { Stigmer } from "@stigmer/sdk";
-import { zipSync } from "fflate";
+import { strFromU8, unzipSync, zipSync } from "fflate";
 import { parse as parseYaml } from "yaml";
 import { UsageError } from "../errors/index.js";
 import { getGitBranchName, getGitCommit, getGitRemoteUrl, getGitRepoRoot } from "./git.js";
 import { createMatcher, REASON_TEXT, type Reason } from "./ignore/index.js";
 
 export const SKILL_FILE = "SKILL.md";
+
+// A skill version's identity is the server-side SHA-256 of the uploaded zip
+// bytes, so packaging must be a pure function of content — otherwise
+// re-pushing unchanged content registers a new version and the server's
+// unchanged-content no-op never fires (stigmer/stigmer#671). fflate stamps
+// zip-creation time into every entry when no mtime is given; pinning the DOS
+// epoch (the earliest representable zip timestamp) removes the only
+// byte-level variance. Local-field Date construction is deliberate: DOS
+// timestamps store wall-clock fields, so this encodes identically in every
+// timezone.
+const DETERMINISTIC_ZIP_MTIME = new Date(1980, 0, 1);
 // Kebab-case, optionally scoped with dot-separated namespaces (e.g.
 // "platform.planton-architecture"). Every segment must be alphanumeric, so no
 // leading/trailing/consecutive separators. The derived slug renders dots as hyphens.
@@ -102,7 +113,16 @@ export function parseSkillMetadata(dir: string): SkillMetadata {
   } catch (err) {
     throw new Error(`failed to read ${SKILL_FILE}: ${(err as Error).message}`);
   }
+  return parseSkillMetadataContent(content);
+}
 
+/**
+ * Parse SKILL.md content directly — the shared core behind the directory
+ * path (`parseSkillMetadata`) and the pre-packaged archive path
+ * (`pushSkillFromArchive`), where the content comes out of a zip entry
+ * rather than the filesystem.
+ */
+export function parseSkillMetadataContent(content: string): SkillMetadata {
   const frontmatter = extractFrontmatter(content);
   const parsed = (parseYaml(frontmatter) ?? {}) as Record<string, unknown>;
   const name = typeof parsed.name === "string" ? parsed.name : "";
@@ -233,7 +253,7 @@ export function createSkillZip(
   };
   walk(dir, "");
 
-  const bytes = zipSync(files, { level: 6 });
+  const bytes = zipSync(files, { level: 6, mtime: DETERMINISTIC_ZIP_MTIME });
   return { bytes, stats };
 }
 
@@ -373,6 +393,92 @@ export async function pushSkillFromClone(
   return toResult(applied, name, params.message, stats.totalSize, visibility);
 }
 
+/** A validated pre-packaged skill archive (`--archive`), ready to upload. */
+export interface SkillArchive {
+  /** The archive file's exact bytes — uploaded untouched. */
+  readonly bytes: Uint8Array;
+  /** Metadata parsed from the archive's root SKILL.md. */
+  readonly meta: SkillMetadata;
+  /** Number of file entries (directory markers excluded). */
+  readonly fileCount: number;
+  /** Total uncompressed size of all file entries, in bytes. */
+  readonly totalSize: number;
+}
+
+/**
+ * Read and validate a pre-packaged skill archive.
+ *
+ * Client-side validation is deliberately minimal — root SKILL.md present and
+ * frontmatter parses (the same contract the console's upload preview checks);
+ * the server remains the authoritative validator. The unzip filter inflates
+ * ONLY SKILL.md: entry metadata is enough for the count/size summary, and
+ * validation must not pay for decompressing a large artifact.
+ */
+export function readSkillArchive(archivePath: string): SkillArchive {
+  let raw: Buffer;
+  try {
+    raw = readFileSync(archivePath);
+  } catch (err) {
+    throw new UsageError(`failed to read archive ${archivePath}: ${(err as Error).message}`);
+  }
+  const bytes = new Uint8Array(raw);
+
+  let fileCount = 0;
+  let totalSize = 0;
+  let unzipped: Record<string, Uint8Array>;
+  try {
+    unzipped = unzipSync(bytes, {
+      filter: (info) => {
+        if (!info.name.endsWith("/")) {
+          fileCount++;
+          totalSize += info.originalSize;
+        }
+        return info.name === SKILL_FILE;
+      },
+    });
+  } catch (err) {
+    throw new UsageError(`${archivePath} is not a valid ZIP archive: ${(err as Error).message}`);
+  }
+
+  const skillMd = unzipped[SKILL_FILE];
+  if (skillMd === undefined) {
+    throw new UsageError(
+      `${SKILL_FILE} not found at the root of ${archivePath}\n\n` +
+        `A skill archive must contain ${SKILL_FILE} at its root (not inside a directory) defining the skill interface`,
+    );
+  }
+
+  return { bytes, meta: parseSkillMetadataContent(strFromU8(skillMd)), fileCount, totalSize };
+}
+
+/**
+ * Push a pre-packaged skill archive as-is (`--archive`).
+ *
+ * The bytes are uploaded untouched, so the engine's version hash is the
+ * SHA-256 of the file on disk — release pipelines that publish checksums get
+ * engine version identities that match them (stigmer/stigmer#671). Git
+ * provenance is deliberately omitted: the archive was built elsewhere, so the
+ * local checkout says nothing about the artifact's origin.
+ */
+export async function pushSkillFromArchive(
+  client: Stigmer,
+  archivePath: string,
+  org: string,
+  tag: string,
+  message: string,
+): Promise<PushResult> {
+  const archive = readSkillArchive(archivePath);
+  const request = create(PushSkillRequestSchema, {
+    org,
+    artifact: archive.bytes,
+    tag: tag === "" ? "latest" : tag,
+    message,
+  });
+  const response = await client.skill.push(request);
+  const applied = await applyDeclaredVisibility(client, response, archive.meta.visibility);
+  return toResult(applied, archive.meta.name, message, archive.totalSize, archive.meta.visibility);
+}
+
 /**
  * Apply the SKILL.md-declared visibility after a push. The push RPC carries
  * artifact + provenance but not access level (visibility is metadata, not part