metergraph-cli 0.2.0-preview.4 → 0.2.0-preview.6

package/src/setup-deployment.js

@@ -1,6 +1,9 @@
+import { detectRemoteSession } from "./auth-browser.js";
 import { runDoctor } from "./doctor.js";
-import { planDeploymentRoute, verifyDeploymentRoute } from "./deployment-route.js";
+import { action, planDeploymentRoute, verifyDeploymentRoute } from "./deployment-route.js";
 import { AUTH_HTTP_TIMEOUT_MS } from "./constants.js";
+import { resolveProject } from "./auth-binding.js";
+import { readSetupState } from "./setup-state.js";
 
 // Setup routing uses the same deployment model and Metadata credential checks
 // as the standalone routing contract. Operator prerequisites are assertions,
@@ -24,6 +27,55 @@ const PREREQUISITES = Object.freeze({
 
 const EXPECTED_PROFILE = Object.freeze({ "customer-local": "local", byoc: "byoc-core", oss: "oss" });
 
+const DEPLOYMENT_FOR_PROFILE = Object.freeze({ local: "customer-local", "byoc-core": "byoc" });
+
+// Fixed guidance for each prerequisite, so a person or agent can act on a
+// handoff without the docs. None of it names a credential value, and none of
+// it asks for a credential to be passed to this CLI.
+const PREREQUISITE_GUIDE = Object.freeze({
+  released_signed_bundle: "Download the released customer-local bundle and its signed manifest, and verify the signature before starting it. A bundle built from source is not a release.",
+  registry_invitation: "Accept the workspace's registry invitation so the bundle can pull its images. The registry pull credential is only for pulling images: never give it to this CLI or put it in the project env file.",
+  bundle_started_verified: "Start the bundle with bin/start and wait until bin/status reports it healthy. Pass its origin as --url and the workspace ID that bin/status shows as --workspace.",
+  local_admin_configured: "Sign in to the installation once as its local admin, in a browser on this machine. Setup asks that account to approve sign in and an ingest-only key.",
+  operator_provisioning: "The operator must already have provisioned the customer-owned AWS deployment. Setup connects to it and never provisions anything.",
+  private_network_reachability: "Run setup from a machine that reaches the deployment's private HTTPS origin, for example over the customer VPN. Setup never opens a tunnel or a public endpoint.",
+  identity_membership_configured: "The operator must already have given your identity membership of the workspace through the deployment's configured identity provider.",
+  server_distribution_installed: "The open source server must already be installed and running under the operator's management.",
+  deployment_discovery_supported: "The open source server must answer GET /v1/deployment with the oss profile. If it does not, ask the operator to upgrade it.",
+  metadata_scope_supported: "The open source server must advertise the agent:metadata scope in its OAuth metadata. If it does not, ask the operator to upgrade it.",
+  ingestion_tokens_configured: "The operator configures ingestion tokens in MG_TOKENS and gives the application one as METERGRAPH_APP_TOKEN. Setup never issues or writes open source ingest tokens.",
+  agent_read_tokens_configured: "The operator configures agent read tokens in MG_AGENT_TOKENS, separately from MG_TOKENS. Never reuse an ingestion token for agent reads.",
+});
+const METADATA_CREDENTIAL_GUIDE = Object.freeze({
+  local: "Setup obtains its own Metadata-only sign in through the browser. --agent-token-file is optional and must hold a Metadata-only agent token.",
+  "byoc-core": "Setup obtains its own Metadata-only sign in through the browser. --agent-token-file is optional and must hold a Metadata-only agent token.",
+  oss: "Put one MG_AGENT_TOKENS value in a private file (mode 0600) and pass its absolute path as --agent-token-file.",
+});
+const ACTION_GUIDE = Object.freeze({
+  complete_prerequisite: "Complete the named prerequisite, then rerun setup with --confirm-prerequisites.",
+  oss_operator_handoff: "Ask the open source server operator to complete this step. This CLI does not create open source credentials or change the server.",
+  run_on_customer_machine: "Run setup in a terminal on the machine that reaches the deployment. Setup does not tunnel or forward credentials from a remote or cloud session.",
+  use_https_origin: "Pass the deployment's HTTPS origin. A customer-owned AWS deployment is never reached over plain HTTP.",
+  connection_guide: "Check that --url is the installation's own origin and that it reports the expected deployment profile.",
+  check_private_network: "This machine cannot reach the private origin. Connect to the deployment's network, for example over the customer VPN, and rerun. Do not expose the deployment publicly.",
+  platform_credential_handoff: "This platform cannot prove the agent token file is private. Rerun without --agent-token-file, or on macOS or Linux.",
+  fix_credential_file: "Make --agent-token-file an absolute path to a regular file you own, with mode 0600, holding one token.",
+  use_metadata_only_credential: "The agent token was refused or has more than Metadata access. Use a Metadata-only agent token for this workspace.",
+  retry: "Rerun the same command.",
+});
+
+export function prerequisiteGuide(name, profile) {
+  if (name === "metadata_agent_credential") return METADATA_CREDENTIAL_GUIDE[profile] ?? null;
+  return PREREQUISITE_GUIDE[name] ?? null;
+}
+
+function guided(nextAction, profile) {
+  if (nextAction === null) return null;
+  const message = nextAction.kind === "complete_prerequisite" && nextAction.prerequisite !== null
+    ? prerequisiteGuide(nextAction.prerequisite, profile) : ACTION_GUIDE[nextAction.kind] ?? null;
+  return { ...nextAction, message };
+}
+
 const handoff = (outcome, reason, nextAction = null, details = {}) => ({
   proceed: false,
   outcome,
@@ -38,10 +90,21 @@ const handoff = (outcome, reason, nextAction = null, details = {}) => ({
     pending_prerequisites: details.pendingPrerequisites ?? [],
     metadata_access: details.metadataAccess ?? "not_checked",
     ingest_credential: "not_checked",
-    next_action: nextAction,
+    next_action: guided(nextAction, details.profile ?? null),
   },
 });
 
+// The next action when the service did not answer as a healthy deployment.
+// An unreachable customer-local origin usually means the bundle is not
+// running; an unreachable BYOC origin is private networking. Neither is
+// tunnelled or relaxed.
+function unreachedAction(deployment, outcome) {
+  if (deployment === "oss") return action("oss_operator_handoff");
+  if (outcome !== "connection_failed") return action("connection_guide");
+  if (deployment === "byoc") return action("check_private_network");
+  return action("complete_prerequisite", "bundle_started_verified");
+}
+
 // The static agent token can be any printable string of at least 16 bytes.
 // Even a fixed status such as "operator_handoff" might equal that token. Keep
 // the verifier's non-enumerable knownCredentials on every later result and
@@ -94,13 +157,21 @@ export function planNonHostedSetup(options) {
   return { proceed: true, plan: planned.plan, prerequisites };
 }
 
-export async function preflightNonHostedSetup(options) {
+export async function preflightNonHostedSetup(options, { env = process.env } = {}) {
   const planned = planNonHostedSetup(options);
   if (!planned.proceed) return planned;
   const { plan, prerequisites } = planned;
+  // Setup itself refuses a remote session, but only after this preflight.
+  // Refuse here first, so a remote shell sends no request and never reads the
+  // separate agent token file.
+  if (detectRemoteSession(env) !== null) {
+    return handoff("unsupported", "run_on_local_machine", action("run_on_customer_machine"), {
+      profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
+    });
+  }
   const timeoutMs = Math.min(options.timeoutMs, AUTH_HTTP_TIMEOUT_MS);
   if (options.deployment === "oss" && !options.agentTokenFile) {
-    return handoff("unsupported", "oss_agent_token_file_required", "oss_operator_handoff", {
+    return handoff("unsupported", "oss_agent_token_file_required", action("oss_operator_handoff"), {
       profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
       prerequisites: "operator_confirmed",
     });
@@ -123,7 +194,7 @@ export async function preflightNonHostedSetup(options) {
     // The OSS operator provisions MG_TOKENS and MG_AGENT_TOKENS separately.
     // No released OSS server implements the purpose-bound ingest bootstrap,
     // and a Metadata agent token cannot issue a key. Keep this a handoff.
-    return guardKnownCredentials(handoff("unsupported", "oss_ingest_operator_handoff", "oss_operator_handoff", {
+    return guardKnownCredentials(handoff("unsupported", "oss_ingest_operator_handoff", action("oss_operator_handoff"), {
       profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
       prerequisites: "operator_confirmed", metadataAccess: "verified",
     }), verified);
@@ -134,13 +205,13 @@ export async function preflightNonHostedSetup(options) {
   // and unsafe network responses and reports only a fixed profile token.
   const doctor = await runDoctor({ origin: plan.origin, timeoutMs });
   if (doctor.report.deployment_profile !== null && doctor.report.deployment_profile !== plan.deployment_profile) {
-    return handoff("unsupported", "deployment_profile_mismatch", "connection_guide", {
+    return handoff("unsupported", "deployment_profile_mismatch", action("connection_guide"), {
       profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
       prerequisites: "operator_confirmed",
     });
   }
   if (doctor.outcome !== "authentication_required") {
-    return handoff(doctor.outcome, doctor.reason, options.deployment === "oss" ? "oss_operator_handoff" : "connection_guide", {
+    return handoff(doctor.outcome, doctor.reason, unreachedAction(options.deployment, doctor.outcome), {
       profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
       prerequisites: "operator_confirmed",
     });
@@ -176,3 +247,28 @@ export async function preflightNonHostedSetup(options) {
     metadataAccess: "pending_login",
   };
 }
+
+// A rerun of non-hosted setup may omit the route it was first given, as a
+// hosted rerun does. Only a saved setup state for a customer-local or BYOC
+// route is resumed, and only to that same origin and workspace. The earlier
+// run's operator confirmation stands for that route; every live check still
+// runs again. Anything else is left for setup's own conflict checks.
+export function resumeNonHostedRoute(options) {
+  let saved;
+  try {
+    saved = readSetupState(resolveProject(options.project));
+  } catch {
+    return options;
+  }
+  const deployment = DEPLOYMENT_FOR_PROFILE[saved?.value.deployment_profile];
+  if (deployment === undefined) return options;
+  const { origin, workspace_id: workspaceId } = saved.value;
+  const sameRoute = (!options.originExplicit || options.origin === origin) &&
+    (options.workspace === null || options.workspace === workspaceId);
+  if (!sameRoute) return options;
+  if (!options.deploymentExplicit) {
+    return { ...options, deployment, origin, originExplicit: true, workspace: workspaceId, confirmPrerequisites: true };
+  }
+  if (options.deployment === deployment && options.originExplicit) return { ...options, confirmPrerequisites: true };
+  return options;
+}

package/src/setup.js

@@ -1,7 +1,7 @@
 import { detectRemoteSession, openBrowser } from "./auth-browser.js";
 import { readBinding, resolveProject } from "./auth-binding.js";
 import { startCallbackListener } from "./auth-callback.js";
-import { runLogin } from "./auth-login.js";
+import { openUrl, runLogin } from "./auth-login.js";
 import { clientFor, endpointsFor, newPkce, offeredClientId } from "./auth-oauth.js";
 import { Stop } from "./auth-store.js";
 import { verifiedSession } from "./auth-session.js";
@@ -24,26 +24,26 @@ const PURPOSE = "ingest-bootstrap-v1";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const RECEIPT = /^mgbs_[A-Za-z0-9_-]{32,256}$/;
 const KEY = (value) => typeof value === "string" && UUID.test(value);
-// --json cannot show a person the --no-browser approval URL. The refusal names
-// a fixed, secret-free next step instead of only a reason token.
-const RUN_IN_TERMINAL = Object.freeze({
-  kind: "run_in_terminal",
-  message: "Run the same setup command in a terminal without --json to see the approval URL.",
-});
-const fail = (outcome, reason, status = "not_ready", receipt = null) => ({ outcome, reason,
-  data: { status, application_traffic_verified: false, receipt,
-    next_action: reason === "no_browser_requires_terminal" ? RUN_IN_TERMINAL : null } });
+const fail = (outcome, reason, status = "not_ready", receipt = null, next = null) => ({ outcome, reason,
+  data: { status, application_traffic_verified: false, receipt, next_action: next } });
 
 // This command never receives an ingest key from argv, stdin, an environment
 // variable or a Metadata OAuth grant. Only the purpose-bound redemption
 // response can supply it. Every returned string is fixed and non-secret.
+//
+// With --json --no-browser the caller passes options.announce(data). The
+// first approval this run needs (sign in, or ingest-only setup approval) is
+// announced as setup data with an open_url next action while the listener
+// keeps waiting; stdout has room for one line, so a second approval in the
+// same run is not started. The person approves, the run saves what it
+// finished, and the agent reruns setup, which resumes from the saved state.
 export async function runSetup(options, progress = () => {}) {
   if (options.runtime !== "local" || detectRemoteSession() !== null) return fail("unsupported", "run_on_local_machine");
   const trap = trapSignals();
   let receipt = null;
   let loginVerified = false;
   let credentialVerified = false;
-  const stop = (outcome, reason, status = "not_ready") => {
+  const currentReceipt = () => {
     let current = receipt;
     if (current !== null && (!loginVerified || !credentialVerified)) {
       const completed = loginVerified ? ["login"] : [];
@@ -52,8 +52,14 @@ export async function runSetup(options, progress = () => {}) {
           ...(!loginVerified ? ["login"] : []), "credential", "skill", "instrument", "verify", "view",
         ] };
     }
-    return fail(outcome, reason, status, current);
+    return current;
   };
+  const stop = (outcome, reason, status = "not_ready") => fail(outcome, reason, status, currentReceipt());
+  let announced = false;
+  const announce = options.announce ? (status, next) => {
+    announced = true;
+    options.announce(fail("action_required", "browser_approval_required", status, currentReceipt(), next).data);
+  } : null;
   try {
     const root = resolveProject(options.project);
     const saved = readSetupState(root);
@@ -67,6 +73,13 @@ export async function runSetup(options, progress = () => {}) {
         (bound !== null && (bound.origin !== saved.value.origin || bound.workspace_id !== saved.value.workspace_id)))) {
       return stop("conflict", "setup_binding_changed");
     }
+    // An env key this setup does not own stops before any sign in, so the
+    // refusal costs no approval and leaves the binding untouched. The check
+    // after sign in stays, against a fresh read.
+    if (!saved) {
+      const early = currentEnvValues(preflightEnv({ project: root, envFile: options.envFile, signal: trap.signal }));
+      if (early.token !== null) return stop("conflict", "existing_ingest_key_unowned");
+    }
     const bindingDiffers = bound !== null && (bound.origin !== intendedOrigin ||
       (intendedWorkspace !== null && bound.workspace_id !== intendedWorkspace));
     if (bindingDiffers && !options.reconnect) return stop("conflict", "bound_to_other_workspace");
@@ -74,7 +87,8 @@ export async function runSetup(options, progress = () => {}) {
       await verifiedSession({ project: root, configDir: options.configDir, cancel: trap.signal });
     if (!signedIn.ok && signedIn.outcome === "login_required") {
       const login = await runLogin({ ...options, origin: intendedOrigin, workspace: intendedWorkspace,
-        project: root, reconnect: options.reconnect, expectedProfile: options.expectedProfile ?? null }, progress);
+        project: root, reconnect: options.reconnect, expectedProfile: options.expectedProfile ?? null,
+        announce: announce && ((data) => announce("login_pending", data.next_action)) }, progress);
       if (login.outcome !== "ok") return stop(login.outcome, login.reason, "login_pending");
       signedIn = await verifiedSession({ project: root, configDir: options.configDir, cancel: trap.signal });
     }
@@ -146,8 +160,9 @@ export async function runSetup(options, progress = () => {}) {
     }
 
     // A verified rerun returned above without approval. From here a person
-    // must open an approval URL, which --json cannot show with --no-browser.
-    if (options.json && options.noBrowser) return stop("unsupported", "no_browser_requires_terminal");
+    // must open an approval URL. A run that already announced its sign in URL
+    // has used its one JSON line, so it stops here and the rerun continues.
+    if (announced) return stop("action_required", "browser_approval_required", "approval_pending");
     const setup = await discoverSetup(origin, profile, trap.signal);
     if (!setup.ok) return stop(setup.outcome, setup.reason);
 
@@ -183,7 +198,9 @@ export async function runSetup(options, progress = () => {}) {
       if (intent === "repair") params.expected_key_id = state.key_id;
       url.search = new URLSearchParams(params).toString();
       if (trap.signal.aborted) return stop("authorization_failed", "cancelled");
-      if (options.noBrowser) progress(`Open this URL on this machine to approve ingest-only setup:\n${url.href}`);
+      if (options.noBrowser && announce) {
+        announce("approval_pending", openUrl(url.href, Math.round(options.timeoutMs / 1000), "approve ingest-only setup"));
+      } else if (options.noBrowser) progress(`Open this URL on this machine to approve ingest-only setup:\n${url.href}`);
       else if (!(await openBrowser(url.href))) return stop("authorization_failed", "browser_unavailable");
       else progress("Opened your browser for ingest-only setup approval.");
       callback = await pending;

package/src/skill-bundle.js

@@ -5,7 +5,7 @@ import { readFileSync } from "node:fs";
 // public skill at the manifest's source_url. The source has no version of its
 // own, so the revision is derived from the content hash. The hash is pinned
 // here as well as in the manifest, so editing either file alone is detected.
-const PINNED_SHA256 = "8b81eb27b6159c4447a5c300409c4c64917238b7797f5ee37a35248cba50fcae";
+const PINNED_SHA256 = "e7fc4eb7a22eeb16c357bede9d0a080ad3b415aaab1d9c72f164d5350d48c4b1";
 
 const ASSET_DIR = new URL("../assets/skill/", import.meta.url);
 const MANIFEST_KEYS = ["file", "manifest_version", "name", "revision", "sha256", "size", "source_url"];
@@ -51,3 +51,70 @@ export function loadBundledSkill() {
   if (!content.toString("utf8").startsWith(`---\nname: ${manifest.name}\ndescription: `)) return null;
   return { name: manifest.name, revision: manifest.revision, sha256, content };
 }
+
+// The workflow skills that "skills install" writes, vendored from the public
+// skills repository at one commit. The manifest's own hash is pinned here, and
+// the manifest pins each skill's hash, so changing any file alone is detected.
+const PINNED_PACK_SHA256 = "f08a188abba2018770dc3ba071509ff22f3af76ebc5c30a9f3a2ec2b2eae75b5";
+
+const PACK_DIR = new URL("../assets/skills/", import.meta.url);
+const PACK_KEYS = ["commit", "manifest_version", "repository", "skills"];
+const PACK_ENTRY_KEYS = ["name", "revision", "sha256", "size"];
+
+// Returns { repository, commit, skills: [{ name, revision, sha256, content }] }
+// sorted by name, or null when the manifest or any skill file is missing,
+// malformed or does not match its pinned hash. Never downloads anything.
+export function loadBundledPack() {
+  let manifestBytes;
+  let manifest;
+  try {
+    manifestBytes = readFileSync(new URL("manifest.json", PACK_DIR));
+    manifest = JSON.parse(manifestBytes.toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (
+    sha256Hex(manifestBytes) !== PINNED_PACK_SHA256 ||
+    manifest === null ||
+    typeof manifest !== "object" ||
+    Array.isArray(manifest) ||
+    Object.keys(manifest).sort().join() !== PACK_KEYS.join() ||
+    manifest.manifest_version !== 1 ||
+    manifest.repository !== "metergraph/skills" ||
+    typeof manifest.commit !== "string" ||
+    !/^[0-9a-f]{40}$/.test(manifest.commit) ||
+    !Array.isArray(manifest.skills) ||
+    manifest.skills.length === 0
+  ) {
+    return null;
+  }
+  const skills = [];
+  const seen = new Set();
+  for (const entry of manifest.skills) {
+    if (
+      entry === null ||
+      typeof entry !== "object" ||
+      Object.keys(entry).sort().join() !== PACK_ENTRY_KEYS.join() ||
+      typeof entry.name !== "string" ||
+      !/^[a-z0-9-]{1,64}$/.test(entry.name) ||
+      entry.name === "metergraph" ||
+      seen.has(entry.name) ||
+      typeof entry.sha256 !== "string" ||
+      entry.revision !== revisionFor(entry.sha256)
+    ) {
+      return null;
+    }
+    seen.add(entry.name);
+    let content;
+    try {
+      content = readFileSync(new URL(`${entry.name}/SKILL.md`, PACK_DIR));
+    } catch {
+      return null;
+    }
+    if (content.length !== entry.size || sha256Hex(content) !== entry.sha256) return null;
+    if (!content.toString("utf8").startsWith(`---\nname: ${entry.name}\ndescription: `)) return null;
+    skills.push({ name: entry.name, revision: entry.revision, sha256: entry.sha256, content });
+  }
+  skills.sort((a, b) => (a.name < b.name ? -1 : 1));
+  return { repository: manifest.repository, commit: manifest.commit, skills };
+}

package/src/skill.js

@@ -2,11 +2,19 @@ import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
-import { CONNECTION_GUIDE_URL, SKILL_CLIENTS, SKILL_RUNTIMES } from "./constants.js";
-import { loadBundledSkill, revisionFor, sha256Hex } from "./skill-bundle.js";
+import {
+  CONNECTION_GUIDE_URL,
+  SKILLS_REPOSITORY_URL,
+  SKILL_CLIENTS,
+  SKILL_RUNTIMES,
+} from "./constants.js";
+import { loadBundledPack, loadBundledSkill, revisionFor, sha256Hex } from "./skill-bundle.js";
 
-// Project-scoped skill installer. It writes exactly two things inside the
-// project: the client's SKILL.md and a secret-free ownership receipt. It never
+// Project-scoped skill installer. For each skill it writes exactly two things
+// inside the project: the client's SKILL.md and a secret-free ownership
+// receipt. "skill" installs the setup skill with the receipt below; "skills"
+// installs each skill of the workflow pack with its own receipt in
+// .metergraph/skills/. It never
 // touches client settings, AGENTS.md, CLAUDE.md or any other file, never
 // follows a symbolic link below the resolved project directory and makes no
 // network request. All file work is synchronous, so a signal cannot run
@@ -15,6 +23,8 @@ import { loadBundledSkill, revisionFor, sha256Hex } from "./skill-bundle.js";
 const RECEIPT_DIR = ".metergraph";
 const RECEIPT_FILE = "skill-installations.json";
 const LOCK_FILE = "skill-installations.lock";
+const PACK_RECEIPT_DIRS = [RECEIPT_DIR, "skills"];
+const CORE_RECEIPT = Object.freeze({ dirs: [RECEIPT_DIR], file: RECEIPT_FILE, lock: LOCK_FILE });
 const MAX_RECEIPT_BYTES = 64 * 1024;
 const MAX_SKILL_BYTES = 1024 * 1024;
 const ENTRY_KEYS = ["client", "path", "revision", "runtimes", "sha256", "skill"];
@@ -57,7 +67,7 @@ class Stop extends Error {
 // Returns { outcome, reason, message, data }. Every string comes from this
 // package. Paths in data are relative to the project.
 export function runSkill({ action, client, runtime, project }) {
-  const context = { action, client, runtime, target: null, bundle: null };
+  const context = { action, client, runtime, target: null, bundle: null, receipt: CORE_RECEIPT };
   if (!Object.hasOwn(SKILL_CLIENTS, client)) {
     return handoff(context, "client_not_supported");
   }
@@ -73,20 +83,25 @@ export function runSkill({ action, client, runtime, project }) {
 }
 
 function execute(context, project) {
-  const { action, client, runtime } = context;
   context.bundle = loadBundledSkill();
   if (context.bundle === null) throw new Stop("internal_error", "bundled_skill_invalid");
-  context.target = targetFor(client, context.bundle.name);
+  context.target = targetFor(context.client, context.bundle.name);
   const root = resolveProject(project);
+  return success(context, apply(root, context));
+}
+
+// Installs or updates one skill and returns its status, or throws a Stop.
+function apply(root, context) {
+  const { action, runtime, receipt } = context;
 
   // Decide from a read-only look first, so a matching rerun writes nothing.
   let state = inspect(root, context);
   let plan = decide(action, runtime, state, context.bundle);
-  if (plan.noop) return success(context, plan.status);
+  if (plan.noop) return plan.status;
 
   return deferSignals(() => {
-    const createdMeta = ensureDirs(root, [RECEIPT_DIR]);
-    const lockPath = path.join(root, RECEIPT_DIR, LOCK_FILE);
+    const createdMeta = ensureDirs(root, receipt.dirs);
+    const lockPath = path.join(root, ...receipt.dirs, receipt.lock);
     let done = false;
     try {
       acquireLock(lockPath);
@@ -96,7 +111,7 @@ function execute(context, project) {
         plan = decide(action, runtime, state, context.bundle);
         if (!plan.noop) commit(root, context, state, plan);
         done = true;
-        return success(context, plan.status);
+        return plan.status;
       } finally {
         try {
           fs.unlinkSync(lockPath);
@@ -129,8 +144,8 @@ function resolveProject(project) {
 // non-regular entry on either path stops the run.
 function inspect(root, context) {
   try {
-    checkDirs(root, [RECEIPT_DIR]);
-    const receiptFile = readRegular(path.join(root, RECEIPT_DIR, RECEIPT_FILE), MAX_RECEIPT_BYTES);
+    checkDirs(root, context.receipt.dirs);
+    const receiptFile = readRegular(path.join(root, ...context.receipt.dirs, context.receipt.file), MAX_RECEIPT_BYTES);
     let receipt = null;
     if (receiptFile !== null) {
       receipt = receiptFile.content === null ? null : parseReceipt(receiptFile.content, context.bundle.name);
@@ -181,7 +196,7 @@ function decide(action, runtime, state, bundle) {
 function commit(root, context, state, plan) {
   const { bundle, target } = context;
   const skillPath = path.join(root, ...target.dirs, "SKILL.md");
-  const receiptPath = path.join(root, RECEIPT_DIR, RECEIPT_FILE);
+  const receiptPath = path.join(root, ...context.receipt.dirs, context.receipt.file);
   const receipt = nextReceipt(state.receipt, context, target.relative);
   let createdDirs = [];
   let skillWritten = false;
@@ -447,3 +462,149 @@ function handoff(context, reason) {
 function failure(context, outcome, reason) {
   return { outcome, reason, message: MESSAGES[reason], data: data(context) };
 }
+
+// ---------------------------------------------------------------------------
+// The workflow skill pack ("metergraph skills"). Each skill runs through the
+// same engine as the setup skill, with its own receipt and lock in
+// .metergraph/skills/, so one skill's conflict never blocks or rolls back
+// another, and the setup skill's receipt is never touched.
+
+const PACK_HANDOFF_MESSAGE =
+  "In Claude Desktop, open Customize → Plugins → Add marketplace and enter metergraph/skills, " +
+  "or upload a skill zip from https://github.com/metergraph/skills/releases/latest under Customize → Skills.";
+
+function packReceipt(name) {
+  return { dirs: PACK_RECEIPT_DIRS, file: `${name}.json`, lock: `${name}.lock` };
+}
+
+function packMessage(name, reason) {
+  const receipt = `${PACK_RECEIPT_DIRS.join("/")}/${name}.json`;
+  const lock = `${PACK_RECEIPT_DIRS.join("/")}/${name}.lock`;
+  if (reason === "receipt_invalid") return `The receipt ${receipt} is not valid. Nothing was changed.`;
+  if (reason === "locked") return `Another skill install may be running. If none is, delete ${lock} and retry.`;
+  if (reason === "rollback_failed") {
+    return `The skill could not be written and the rollback did not finish. Check the skill path and ${receipt}.`;
+  }
+  return MESSAGES[reason];
+}
+
+// Returns { outcome, reason, message, data } like runSkill. data.skills has
+// one entry per bundled skill, in name order.
+export function runSkillPack({ action, client, runtime, project }) {
+  const base = { client, runtime, source: null, skills: [], discovery: null, authenticated: false, next_action: null };
+  if (client === "claude-desktop") {
+    return {
+      outcome: "unsupported",
+      reason: "client_not_supported",
+      message:
+        "Claude Desktop loads Metergraph skills from the plugin marketplace or an uploaded zip, not from project files. Nothing was written.",
+      data: { ...base, next_action: { kind: "plugin_marketplace", message: PACK_HANDOFF_MESSAGE, url: SKILLS_REPOSITORY_URL } },
+    };
+  }
+  if (!Object.hasOwn(SKILL_CLIENTS, client)) {
+    return { outcome: "unsupported", reason: "client_not_supported", message: MESSAGES.client_not_supported,
+      data: { ...base, next_action: { kind: "connection_guide", url: CONNECTION_GUIDE_URL } } };
+  }
+  if (!SKILL_RUNTIMES.includes(runtime)) {
+    return { outcome: "unsupported", reason: "runtime_not_supported", message: MESSAGES.runtime_not_supported,
+      data: { ...base, next_action: { kind: "connection_guide", url: CONNECTION_GUIDE_URL } } };
+  }
+  const pack = loadBundledPack();
+  if (pack === null) {
+    return { outcome: "internal_error", reason: "bundled_skill_invalid", message: MESSAGES.bundled_skill_invalid, data: base };
+  }
+  base.source = { repository: pack.repository, commit: pack.commit };
+  let root;
+  try {
+    root = resolveProject(project);
+  } catch (error) {
+    return { outcome: error.outcome, reason: error.reason, message: MESSAGES[error.reason], data: base };
+  }
+
+  let failed = null;
+  for (const bundle of pack.skills) {
+    const context = {
+      action,
+      client,
+      runtime,
+      bundle,
+      receipt: packReceipt(bundle.name),
+      target: targetFor(client, bundle.name),
+    };
+    const entry = { name: bundle.name, path: context.target.relative, status: null, revision: bundle.revision, reason: null };
+    try {
+      try {
+        entry.status = apply(root, context);
+      } catch (error) {
+        // A skill added to the pack since the last install is installed by update.
+        if (!(error instanceof Stop) || error.reason !== "not_installed") throw error;
+        entry.status = apply(root, { ...context, action: "install" });
+      }
+    } catch (error) {
+      const stop = error instanceof Stop ? error : new Stop("filesystem_error", "write_failed");
+      entry.status = "failed";
+      entry.reason = stop.reason;
+      failed ??= { outcome: stop.outcome, reason: stop.reason, message: packMessage(bundle.name, stop.reason) };
+    }
+    base.skills.push(entry);
+  }
+
+  const label = SKILL_CLIENTS[client].label;
+  if (failed !== null) {
+    return { ...failed, data: { ...base, discovery: "pending", next_action: null } };
+  }
+  const message =
+    runtime === "local"
+      ? `Start or restart ${label} in this project, then confirm that it lists the Metergraph skills.`
+      : `Make sure the cloud checkout includes ${SKILL_CLIENTS[client].dir}/skills (commit it if you installed it elsewhere), ` +
+        `then start a new ${label} cloud session and confirm that it lists the Metergraph skills.`;
+  return {
+    outcome: "ok",
+    reason: null,
+    message:
+      `Skills ready. Discovery is pending until ${label} loads them. ` +
+      "This does not sign in, connect a workspace or configure MCP.",
+    data: { ...base, discovery: "pending", next_action: { kind: "reload_client", message } },
+  };
+}
+
+// Read-only: what the pack bundles, and its state for every client in the
+// project. Never writes, never takes a lock.
+export function listSkillPack({ project }) {
+  const pack = loadBundledPack();
+  const data = { source: null, skills: [], clients: Object.keys(SKILL_CLIENTS) };
+  if (pack === null) {
+    return { outcome: "internal_error", reason: "bundled_skill_invalid", message: MESSAGES.bundled_skill_invalid, data };
+  }
+  data.source = { repository: pack.repository, commit: pack.commit };
+  let root;
+  try {
+    root = resolveProject(project);
+  } catch (error) {
+    return { outcome: error.outcome, reason: error.reason, message: MESSAGES[error.reason], data };
+  }
+  for (const bundle of pack.skills) {
+    const installs = {};
+    for (const client of Object.keys(SKILL_CLIENTS)) {
+      installs[client] = packState(root, { client, bundle, receipt: packReceipt(bundle.name), target: targetFor(client, bundle.name) });
+    }
+    data.skills.push({ name: bundle.name, revision: bundle.revision, sha256: bundle.sha256, installs });
+  }
+  return { outcome: "ok", reason: null, message: null, data };
+}
+
+// One of not_installed, installed, outdated, modified, missing, not_owned,
+// receipt_invalid or unsafe_path.
+function packState(root, context) {
+  let state;
+  try {
+    state = inspect(root, context);
+  } catch (error) {
+    return error instanceof Stop && error.reason === "receipt_invalid" ? "receipt_invalid" : "unsafe_path";
+  }
+  const { entry, file, skillDirExists } = state;
+  if (entry === null) return file !== null || skillDirExists ? "not_owned" : "not_installed";
+  if (file === null) return "missing";
+  if (file.content === null || sha256Hex(file.content) !== entry.sha256) return "modified";
+  return entry.revision === context.bundle.revision ? "installed" : "outdated";
+}