diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
index 58fd978..964ec6f 100644
--- a/.cursor-plugin/marketplace.json
+++ b/.cursor-plugin/marketplace.json
@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "JFrog Platform plugins for Cursor",
-    "version": "0.5.4",
+    "version": "0.5.5",
     "pluginRoot": "plugins"
   },
   "plugins": [
diff --git a/.github/scripts/sync-modules-vendor.json b/.github/scripts/sync-modules-vendor.json
new file mode 100644
index 0000000..c79ea0e
--- /dev/null
+++ b/.github/scripts/sync-modules-vendor.json
@@ -0,0 +1,7 @@
+{
+  "repo": "JFROG/jfrog-agent-hooks",
+  "pin": "jfrog-agent-hooks/v0.5.0",
+  "paths": [
+    "modules"
+  ]
+}
diff --git a/plugins/jfrog/.cursor-plugin/plugin.json b/plugins/jfrog/.cursor-plugin/plugin.json
index e24c846..5752f7e 100644
--- a/plugins/jfrog/.cursor-plugin/plugin.json
+++ b/plugins/jfrog/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "jfrog",
   "displayName": "JFrog Platform",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "JFrog Platform integration with MCP, security skills, supply-chain best practices, and JFrog Agent Guard governance for adding, removing, and listing MCP servers.",
   "author": {
     "name": "JFrog",
diff --git a/plugins/jfrog/modules/assets/agents-default-conf.json b/plugins/jfrog/modules/assets/agents-default-conf.json
new file mode 100644
index 0000000..2f0f0a8
--- /dev/null
+++ b/plugins/jfrog/modules/assets/agents-default-conf.json
@@ -0,0 +1,17 @@
+{
+  "logLevel": "info",
+  "packageResolution": {
+    "enabled": false,
+    "verifyRepos": true,
+    "cacheTtlDays": 7,
+    "defaultGlobalRepos": {
+      "npm": "npm-virtual",
+      "pypi": "pypi-virtual",
+      "maven": "maven-virtual",
+      "go": "go-virtual",
+      "docker": "docker-virtual",
+      "helm": "helm-virtual",
+      "nuget": "nuget-virtual"
+    }
+  }
+}
diff --git a/plugins/jfrog/modules/claude-session-start.mjs b/plugins/jfrog/modules/claude-session-start.mjs
new file mode 100644
index 0000000..4a31144
--- /dev/null
+++ b/plugins/jfrog/modules/claude-session-start.mjs
@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Claude Code SessionStart hook runner.
+//
+// Usage: node claude-session-start.mjs <capability>
+// Example: node claude-session-start.mjs package-resolution
+//
+// stdout: JSON with hookSpecificOutput.additionalContext. No stdout is a no-op.
+
+import process from "node:process";
+
+import { runCapability } from "./core/run-capability.mjs";
+import { ensureAgentsConfigScaffold, agentsConfigLoadWarnings } from "./core/agents-config.mjs";
+import { readStdin, parseSessionId, detectHarness, parseWorkspaceRoots } from "./core/io.mjs";
+import { setLogContext, createLogger } from "./core/logger.mjs";
+
+const HARNESS_ID = "claude_code";
+const log = createLogger("session-start");
+
+/** @returns {string | null} JSON stdout payload, or null when there is nothing to inject. */
+function formatSessionStartStdout(text) {
+  if (!text?.trim()) return null;
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: text,
+    },
+  });
+}
+
+function writeStdout(payload) {
+  if (payload !== null) process.stdout.write(payload);
+}
+
+function writeNoOp() {
+  // Claude SessionStart: no stdout on no-op.
+}
+
+async function main() {
+  const capability = process.argv[2];
+  if (!capability) {
+    writeNoOp();
+    return;
+  }
+
+  const startedAtMs = Date.now();
+  const stdinRaw = await readStdin();
+  const harness = detectHarness(stdinRaw);
+  if (harness && harness !== HARNESS_ID) {
+    writeNoOp();
+    return;
+  }
+  const sessionId = parseSessionId(stdinRaw);
+  const workspaceRoots = parseWorkspaceRoots(stdinRaw);
+  setLogContext({ ide: HARNESS_ID, sessionId });
+  ensureAgentsConfigScaffold();
+  for (const w of agentsConfigLoadWarnings()) {
+    log.warn(w.message, { path: w.path });
+  }
+  const text = await runCapability(capability, {
+    ide: HARNESS_ID,
+    sessionId,
+    workspaceRoots,
+    startedAtMs,
+  });
+  writeStdout(formatSessionStartStdout(text));
+}
+
+main().catch(() => {
+  writeNoOp();
+  process.exit(0);
+});
diff --git a/plugins/jfrog/modules/core/agents-config.mjs b/plugins/jfrog/modules/core/agents-config.mjs
new file mode 100644
index 0000000..dab3898
--- /dev/null
+++ b/plugins/jfrog/modules/core/agents-config.mjs
@@ -0,0 +1,184 @@
+// Local admin config at ~/.jfrog/agents-conf.json (shipped template: assets/agents-default-conf.json).
+//
+// Read-only helpers — no network. Session starters call ensureAgentsConfigScaffold()
+// before capabilities run so first-time installs get a writable config file.
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** modules bundle root (parent of core/ and assets/). */
+const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const TEMPLATE_PATH = path.join(PLUGIN_ROOT, "assets", "agents-default-conf.json");
+
+const DEFAULT_LOG_LEVEL = "info";
+const DEFAULT_CACHE_TTL_DAYS = 7;
+
+let memoizedRaw = undefined;
+let memoizedForPath = null;
+/** @type {{ source: 'missing' | 'user' | 'template', parseFailed: boolean, path: string }} */
+let loadMeta = { source: "missing", parseFailed: false, path: "" };
+
+function agentsConfigPath() {
+  return path.join(homedir(), ".jfrog", "agents-conf.json");
+}
+
+function resetLoadMeta(configPath) {
+  loadMeta = { source: "missing", parseFailed: false, path: configPath };
+}
+
+/**
+ * Copy the shipped template to ~/.jfrog/agents-conf.json when missing.
+ * Never overwrites an existing file.
+ */
+export function ensureAgentsConfigScaffold() {
+  const configPath = agentsConfigPath();
+  if (existsSync(configPath)) return { created: false, path: configPath };
+  try {
+    mkdirSync(path.dirname(configPath), { recursive: true });
+    copyFileSync(TEMPLATE_PATH, configPath);
+    memoizedRaw = undefined;
+    return { created: true, path: configPath };
+  } catch {
+    return { created: false, path: configPath };
+  }
+}
+
+export { agentsConfigPath };
+
+export function agentsConfigTemplatePath() {
+  return TEMPLATE_PATH;
+}
+
+/** @returns {number | null} mtime in ms, or null when the file is absent */
+export function getAgentsConfigMtimeMs() {
+  try {
+    return statSync(agentsConfigPath()).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function parseAgentsJson(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function readAgentsConfigRaw() {
+  const configPath = agentsConfigPath();
+  if (memoizedForPath !== configPath) {
+    memoizedRaw = undefined;
+    memoizedForPath = configPath;
+    resetLoadMeta(configPath);
+  }
+  if (memoizedRaw !== undefined) return memoizedRaw;
+
+  const userExists = existsSync(configPath);
+  if (userExists) {
+    try {
+      const parsed = parseAgentsJson(readFileSync(configPath, "utf8"));
+      if (parsed) {
+        memoizedRaw = parsed;
+        loadMeta = { source: "user", parseFailed: false, path: configPath };
+        return memoizedRaw;
+      }
+      loadMeta = { source: "template", parseFailed: true, path: configPath };
+    } catch {
+      loadMeta = { source: "template", parseFailed: true, path: configPath };
+    }
+  }
+
+  try {
+    memoizedRaw = parseAgentsJson(readFileSync(TEMPLATE_PATH, "utf8"));
+    if (!userExists) {
+      loadMeta = { source: memoizedRaw ? "template" : "missing", parseFailed: false, path: configPath };
+    }
+  } catch {
+    memoizedRaw = null;
+    if (!userExists) loadMeta = { source: "missing", parseFailed: false, path: configPath };
+  }
+  return memoizedRaw;
+}
+
+/** Call after loadAgentsConfig() — surfaces user-file parse failures. */
+export function getAgentsConfigLoadMeta() {
+  readAgentsConfigRaw();
+  return { ...loadMeta };
+}
+
+/** @returns {Array<{ message: string, path: string }>} */
+export function agentsConfigLoadWarnings() {
+  loadAgentsConfig();
+  if (!loadMeta.parseFailed) return [];
+  return [
+    {
+      message: "agents-conf.json unreadable; using shipped template defaults",
+      path: loadMeta.path,
+    },
+  ];
+}
+
+/** @returns {object | null} raw section or null */
+export function getAgentsConfigSection(name) {
+  const config = readAgentsConfigRaw();
+  if (!config) return null;
+  const section = config[name];
+  return section && typeof section === "object" ? section : null;
+}
+
+/** @returns {{ logLevel: string, packageResolution: object }} merged with documented defaults */
+export function loadAgentsConfig() {
+  const file = readAgentsConfigRaw() ?? {};
+  const pr =
+    file.packageResolution && typeof file.packageResolution === "object"
+      ? file.packageResolution
+      : {};
+  const defaultGlobalRepos =
+    pr.defaultGlobalRepos && typeof pr.defaultGlobalRepos === "object"
+      ? normalizeRepoMap(pr.defaultGlobalRepos)
+      : {};
+
+  return {
+    logLevel: normalizeLogLevel(file.logLevel),
+    packageResolution: {
+      enabled: pr.enabled === true,
+      verifyRepos: pr.verifyRepos !== false,
+      cacheTtlDays: normalizeCacheTtlDays(pr.cacheTtlDays),
+      defaultGlobalRepos,
+    },
+  };
+}
+
+export function getGlobalLogLevel() {
+  return loadAgentsConfig().logLevel;
+}
+
+function normalizeLogLevel(level) {
+  const s = typeof level === "string" ? level.toLowerCase() : "";
+  const allowed = new Set(["silent", "debug", "info", "warn", "error"]);
+  return allowed.has(s) ? s : DEFAULT_LOG_LEVEL;
+}
+
+function normalizeCacheTtlDays(days) {
+  if (days === 0) return 0;
+  if (typeof days !== "number" || !Number.isFinite(days) || days < 0) {
+    return DEFAULT_CACHE_TTL_DAYS;
+  }
+  return Math.floor(days);
+}
+
+/** Trim string repo keys; drop empty values. */
+export function normalizeRepoMap(raw) {
+  if (!raw || typeof raw !== "object") return {};
+  const out = {};
+  for (const [type, key] of Object.entries(raw)) {
+    if (typeof key === "string" && key.trim()) out[type] = key.trim();
+  }
+  return out;
+}
diff --git a/plugins/jfrog/modules/core/io.mjs b/plugins/jfrog/modules/core/io.mjs
new file mode 100644
index 0000000..5127bae
--- /dev/null
+++ b/plugins/jfrog/modules/core/io.mjs
@@ -0,0 +1,95 @@
+// Shared stdin helpers for the subprocess-style adapters (Claude, Cursor).
+//
+// Hooks deliver their JSON payload on stdin immediately; in non-hook contexts
+// (CI, npm scripts, terminal smoke tests) nothing arrives, so we bail out after
+// a short idle window rather than hang.
+
+import process from "node:process";
+
+export function readStdin({ idleMs = 50 } = {}) {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve("");
+    let data = "";
+    let settled = false;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      resolve(data);
+    };
+    const idleTimer = setTimeout(settle, idleMs);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+      idleTimer.refresh();
+    });
+    process.stdin.on("end", () => {
+      clearTimeout(idleTimer);
+      settle();
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(idleTimer);
+      settle();
+    });
+  });
+}
+
+export function parseSessionId(stdinRaw) {
+  if (!stdinRaw) return undefined;
+  try {
+    return JSON.parse(stdinRaw)?.session_id;
+  } catch {
+    return undefined;
+  }
+}
+
+// Positively identify the harness that invoked this hook from its stdin
+// payload. Returns "cursor", "claude_code", or null when it can't tell
+// (no stdin — e.g. terminal smoke tests — or an unrecognized shape).
+//
+// Why this matters: Cursor reads sessionStart hooks from BOTH
+// ~/.cursor/hooks.json AND ~/.claude/settings.json. Without this, a Cursor
+// session fires the Claude adapter too, double-injecting the policy. Each
+// adapter uses this to no-op when a different harness invoked it.
+//
+// Cursor: cursor_version / agent_type. Claude: transcript_path / hook_event_name /
+// session_id. Cursor also reads ~/.claude/settings.json, so each adapter no-ops
+// when a different harness invoked it.
+export function detectHarness(stdinRaw) {
+  if (!stdinRaw) return null;
+  try {
+    const p = JSON.parse(stdinRaw);
+    if (!p) return null;
+    if (p.cursor_version || p.agent_type === "cursor") {
+      return "cursor";
+    }
+    if (p.transcript_path || p.hook_event_name || p.session_id) {
+      return "claude_code";
+    }
+  } catch {
+    // stdin wasn't JSON — can't tell.
+  }
+  return null;
+}
+
+/**
+ * Workspace roots for this hook invocation.
+ * Cursor: workspace_roots[]. Claude: payload cwd. Fallback: process.cwd().
+ *
+ * @param {string} [stdinRaw]
+ * @returns {string[]}
+ */
+export function parseWorkspaceRoots(stdinRaw) {
+  if (stdinRaw?.trim()) {
+    try {
+      const p = JSON.parse(stdinRaw);
+      if (Array.isArray(p.workspace_roots) && p.workspace_roots.length) {
+        return p.workspace_roots.filter((r) => typeof r === "string" && r);
+      }
+      if (typeof p.cwd === "string" && p.cwd) return [p.cwd];
+    } catch {
+      // fall through
+    }
+  }
+
+  return [process.cwd()];
+}
diff --git a/plugins/jfrog/modules/core/jf-identity.mjs b/plugins/jfrog/modules/core/jf-identity.mjs
new file mode 100644
index 0000000..b63a0a6
--- /dev/null
+++ b/plugins/jfrog/modules/core/jf-identity.mjs
@@ -0,0 +1,166 @@
+// Platform identity — single source of truth for "where is JFrog and how do
+// we auth to it?". Used by feature-flag.mjs and resolver.mjs.
+//
+// Identity ALWAYS comes from `jf config`. `jf config export [serverId]` returns
+// base64(JSON({ url, accessToken, serverId, ... })) for the chosen (or default)
+// server. We require both `url` AND `accessToken` (Bearer-only path).
+//
+// If `jf` is not on PATH, has no configured servers, or the chosen server has
+// no access token, identity is null and the feature flag falls into the
+// `missing-identity` path (hook goes no-op, fail closed). Same behaviour as
+// before — only the configuration mechanism is simpler.
+//
+// One subprocess per hook process. Cached after first call within the same
+// process (feature-flag + resolver share one export). Not persisted across
+// sessions — `jf config export` is local and fast enough to run every time.
+
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+
+import { createLogger } from "./logger.mjs";
+
+const log = createLogger("jf-identity");
+
+// Module-scope cache. Keyed by the requested serverId hint (`undefined`
+// means "whatever jf considers default"). Stores the full resolved object,
+// including null when jf config produced nothing usable.
+const CACHE = new Map();
+
+function normalizeUrl(u) {
+  if (!u) return "";
+  return String(u).replace(/\/+$/, "");
+}
+
+// Resolution cause. `ok` means identity is present; the two failure causes
+// drive cause-aware remediation in the enforce path:
+//   jf-not-installed   — `jf` is not on PATH / could not be executed.
+//   jf-not-configured  — `jf` ran but produced no usable server identity
+//                        (non-zero exit, empty/undecodable export, or a
+//                        server entry missing url/accessToken).
+function jfConfigIdentity(serverId) {
+  // `jf config export` writes base64(JSON) to stdout for the requested
+  // server (or the default when no arg). We split the failure space into
+  // "jf could not be run" (not-installed) vs "jf ran but has no usable
+  // server" (not-configured) so the caller can give targeted remediation.
+  const args = ["config", "export"];
+  if (serverId) args.push(serverId);
+
+  let result;
+  try {
+    result = spawnSync("jf", args, {
+      encoding: "utf8",
+      // jf config export reads no stdin and writes a single base64 line
+      // (no terminal interaction). 2s is plenty even for cold spawns.
+      timeout: 2000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (err) {
+    log.debug("jf spawn threw", { error: err?.message ?? String(err) });
+    return { identity: null, cause: "jf-not-installed" };
+  }
+
+  if (result.error) {
+    // ENOENT (and any other spawn error) means the binary could not be
+    // executed — treat as not installed.
+    log.debug("jf spawn error", { code: result.error.code, message: result.error.message });
+    return { identity: null, cause: "jf-not-installed" };
+  }
+  if (result.status !== 0) {
+    log.debug("jf config export non-zero exit", {
+      status: result.status,
+      stderr: (result.stderr || "").trim().slice(0, 200),
+    });
+    return { identity: null, cause: "jf-not-configured" };
+  }
+
+  const blob = (result.stdout || "").trim();
+  if (!blob) {
+    log.debug("jf config export returned empty stdout");
+    return { identity: null, cause: "jf-not-configured" };
+  }
+
+  let parsed;
+  try {
+    const json = Buffer.from(blob, "base64").toString("utf8");
+    parsed = JSON.parse(json);
+  } catch (err) {
+    log.warn("jf config export blob not decodable", { error: err?.message ?? String(err) });
+    return { identity: null, cause: "jf-not-configured" };
+  }
+
+  const url = normalizeUrl(parsed?.url);
+  const token = parsed?.accessToken ?? "";
+  const resolvedServerId = parsed?.serverId ?? serverId ?? null;
+
+  if (!url || !token) {
+    log.debug("jf config export missing url or accessToken", {
+      serverId: resolvedServerId,
+      hasUrl: Boolean(url),
+      hasToken: Boolean(token),
+    });
+    return { identity: null, cause: "jf-not-configured" };
+  }
+
+  return {
+    identity: { url, token, serverId: resolvedServerId, source: "jf-config" },
+    cause: "ok",
+  };
+}
+
+// Public — returns { identity, cause }:
+//   identity: { url, token, serverId, source } | null
+//   cause:    "ok" | "jf-not-installed" | "jf-not-configured"
+export function getPlatformIdentity() {
+  const hint = undefined;
+  if (CACHE.has(hint)) return CACHE.get(hint);
+
+  const status = jfConfigIdentity(hint);
+  if (status.identity) {
+    log.debug("identity from jf-config", {
+      serverId: status.identity.serverId,
+      url: status.identity.url,
+    });
+  } else {
+    log.debug("no platform identity", { cause: status.cause });
+  }
+  CACHE.set(hint, status);
+  return status;
+}
+
+/** Test-only — reset module cache between in-process scenarios. */
+export function clearPlatformIdentityCache() {
+  CACHE.clear();
+}
+
+// Short label for log lines / status output, e.g. "jf-config:<your-server-id>".
+export function identityLabel(identity) {
+  if (!identity) return "none";
+  return identity.serverId ? `jf-config:${identity.serverId}` : "jf-config";
+}
+
+// CLI:
+//   node lib/jf-identity.mjs           — JSON with token redacted
+//   node lib/jf-identity.mjs --label   — single line: "<label>\t<url>"  (or "none")
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const labelOnly = process.argv.includes("--label");
+  const { identity, cause } = getPlatformIdentity();
+  if (labelOnly) {
+    if (!identity) {
+      console.log("none");
+      process.exit(0);
+    }
+    console.log(`${identityLabel(identity)}\t${identity.url}`);
+    process.exit(0);
+  }
+  if (!identity) {
+    const hint =
+      cause === "jf-not-installed"
+        ? "`jf` is not installed. Install the JFrog CLI, then run `jf config add`."
+        : "No configured JFrog server. Run `jf config add` (must use access-token auth).";
+    console.error(`No platform identity (${cause}). ${hint}`);
+    process.exit(2);
+  }
+  const safe = { ...identity, token: identity.token ? `<${identity.token.length} chars>` : "" };
+  console.log(JSON.stringify(safe, null, 2));
+}
diff --git a/plugins/jfrog/modules/core/logger.mjs b/plugins/jfrog/modules/core/logger.mjs
new file mode 100644
index 0000000..f1a4bd8
--- /dev/null
+++ b/plugins/jfrog/modules/core/logger.mjs
@@ -0,0 +1,202 @@
+// Shared logger — every hook, resolver call, and feature-flag check writes here.
+//
+// Log file: ~/.jfrog/logs/agent-hooks.log
+// Format:   <iso-timestamp>  <LEVEL>  [component]  <message>  k1=v1 k2=v2 ...
+//
+// One line per event, append-only, sync writes so short-lived hook processes
+// flush before exit. Tail with `make logs` / `tail -F ~/.jfrog/logs/agent-hooks.log`.
+//
+// Errors from the logger itself are swallowed — a misbehaving log MUST NOT
+// break the hook (otherwise the agent session breaks).
+//
+// Log level: `logLevel` in ~/.jfrog/agents-conf.json (default info).
+// Undocumented; for test isolation only — not a customer-facing control:
+// JFROG_AGENT_HOOKS_LOG_FILE overrides the log path.
+//
+// Levels:
+//   silent  no output at all
+//   debug   step-by-step internals (resolver probes, feature-flag detail)
+//   info    user-visible events (hook fired, rewrite applied)
+//   event   one-line header + indented fields (hook summaries; easy to scan)
+//   warn    recoverable issues (unresolved repo, conflict, fallback)
+//   error   unexpected failures (caught exceptions, IO errors)
+
+import { mkdirSync, appendFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { randomBytes } from "node:crypto";
+
+import { getGlobalLogLevel } from "./agents-config.mjs";
+
+function defaultLogFile() {
+  return path.join(homedir(), ".jfrog", "logs", "agent-hooks.log");
+}
+
+function logFile() {
+  return process.env.JFROG_AGENT_HOOKS_LOG_FILE || defaultLogFile();
+}
+
+// `silent` is a sentinel above every numeric level — nothing matches it.
+const LEVELS = { debug: 10, info: 20, event: 25, warn: 30, error: 40, silent: 1000 };
+
+let minLevelResolved = false;
+let minLevel = LEVELS.info;
+let disabled = false;
+
+function resolveMinLevel() {
+  if (minLevelResolved) return;
+  minLevelResolved = true;
+  const envLevel = getGlobalLogLevel();
+  minLevel = LEVELS[envLevel] ?? LEVELS.info;
+  disabled = minLevel >= LEVELS.silent;
+}
+
+// Short trace id per process — lets you correlate a single hook invocation's
+// multi-line output (resolver + feature flag + outcome).
+const TRACE_ID = randomBytes(4).toString("hex");
+
+// Per-process context that imported modules inherit. The session hook
+// (inject-instructions) calls setLogContext({ ide, sessionId }) after
+// detecting them, so feature-flag and resolver log lines pick up the same
+// IDE / session tag automatically.
+const CONTEXT = {};
+export function setLogContext(ctx) {
+  if (!ctx) return;
+  for (const [k, v] of Object.entries(ctx)) {
+    if (v !== undefined && v !== null) CONTEXT[k] = v;
+  }
+}
+
+let ensuredDir = false;
+let ensuredDirFor = "";
+function ensureDir() {
+  const file = logFile();
+  if (ensuredDir && ensuredDirFor === file) return;
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    ensuredDir = true;
+    ensuredDirFor = file;
+  } catch {
+    // ignore — write attempt below will also swallow
+  }
+}
+
+// Tags we promote to fixed-width bracket prefixes for scannability.
+// Everything else in kv goes to the tail as key=value.
+const PREFIX_TAGS = ["ide", "sessionId", "trace"];
+
+// Column widths — every line uses these exactly so brackets line up across
+// the file. Sized for current values with a small safety margin; any value
+// longer than its column is truncated with an ellipsis by `fitCol` so a
+// future long component / IDE name can never silently break alignment.
+//
+//   COL_LEVEL    — log level inside two spaces (e.g. "EVENT", "DEBUG")
+//   COL_COMPONENT — "[component]" bracketed, e.g. "[session-policy]"
+//   COL_IDE      — inside the [...] (the brackets themselves are added later)
+//   COL_SESSION  — "sess:<8 hex>", inside [...]
+//   COL_TRACE    — "trace:<8 hex>", inside [...]
+const COL_LEVEL = 5;
+const COL_COMPONENT = 20;
+const COL_IDE = 12;
+const COL_SESSION = 13; // "sess:" (5) + 8-char shortId
+const COL_TRACE = 14;   // "trace:" (6) + 8-char shortId
+
+function fitCol(s, width) {
+  if (s.length === width) return s;
+  if (s.length < width) return s.padEnd(width);
+  // Truncate with an ellipsis so overflow is visible but doesn't break the
+  // column. (Single char ellipsis keeps width exact.)
+  return s.slice(0, width - 1) + "…";
+}
+
+function shortId(s) {
+  if (!s) return "";
+  return String(s).split("-")[0].slice(0, 8);
+}
+
+function formatKV(kv) {
+  if (!kv) return "";
+  const parts = [];
+  for (const [k, v] of Object.entries(kv)) {
+    if (v === undefined || v === null) continue;
+    const s = typeof v === "string" ? v : JSON.stringify(v);
+    const needsQuote = /[\s="']/.test(s);
+    const escaped = s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    parts.push(`${k}=${needsQuote ? `"${escaped}"` : escaped}`);
+  }
+  return parts.length ? " " + parts.join(" ") : "";
+}
+
+function formatKVLines(kv, indent = "  ") {
+  if (!kv) return "";
+  const lines = [];
+  for (const [k, v] of Object.entries(kv)) {
+    if (v === undefined || v === null) continue;
+    const s = typeof v === "string" ? v : JSON.stringify(v);
+    lines.push(`${indent}${k}: ${s}`);
+  }
+  return lines.length ? `\n${lines.join("\n")}` : "";
+}
+
+function bracketPrefixes(kv) {
+  // Bracketed columns in fixed order: [ide] [sess:xxxx] [trace:xxxx]
+  // Each inner value is padded/truncated to a fixed width by fitCol so the
+  // brackets themselves always land at the same byte column.
+  const ide = fitCol(kv.ide ?? "-", COL_IDE);
+  const sess = fitCol(`sess:${shortId(kv.sessionId) || "-"}`, COL_SESSION);
+  const trace = fitCol(`trace:${kv.trace || "-"}`, COL_TRACE);
+  return `[${ide}]  [${sess}]  [${trace}]`;
+}
+
+function write(level, component, message, kv) {
+  resolveMinLevel();
+  if (disabled) return;
+  const num = LEVELS[level] ?? LEVELS.info;
+  if (num < minLevel) return;
+
+  const ts = new Date().toISOString();
+  const lvl = fitCol(level.toUpperCase(), COL_LEVEL);
+  const comp = fitCol(`[${component}]`, COL_COMPONENT);
+
+  const allKv = { trace: TRACE_ID, ide: CONTEXT.ide, sessionId: CONTEXT.sessionId, ...kv };
+  const prefix = bracketPrefixes(allKv);
+
+  // Strip promoted tags from the kv tail so we don't print them twice.
+  const tailKv = { ...allKv, pid: process.pid };
+  for (const k of PREFIX_TAGS) delete tailKv[k];
+  delete tailKv.trace;
+
+  // EVENT summaries (sessionStart / preToolUse) use a short header plus one
+  // field per indented line — much easier to scan than a long k=v tail.
+  const line =
+    level === "event"
+      ? `${ts}  ${lvl}  ${comp}  ${prefix}  ${message}${formatKVLines(tailKv)}\n`
+      : `${ts}  ${lvl}  ${comp}  ${prefix}  ${message}${formatKV(tailKv)}\n`;
+
+  try {
+    ensureDir();
+    appendFileSync(logFile(), line);
+  } catch {
+    // swallow — the hook must keep working
+  }
+}
+
+export function createLogger(component) {
+  return {
+    debug: (msg, kv) => write("debug", component, msg, kv),
+    info: (msg, kv) => write("info", component, msg, kv),
+    warn: (msg, kv) => write("warn", component, msg, kv),
+    error: (msg, kv) => write("error", component, msg, kv),
+    event: (msg, kv) => write("event", component, msg, kv),
+    child: (sub) => createLogger(`${component}/${sub}`),
+  };
+}
+
+export function logFilePath() {
+  return logFile();
+}
+
+export function traceId() {
+  return TRACE_ID;
+}
diff --git a/plugins/jfrog/modules/core/run-capability.mjs b/plugins/jfrog/modules/core/run-capability.mjs
new file mode 100644
index 0000000..0c4879c
--- /dev/null
+++ b/plugins/jfrog/modules/core/run-capability.mjs
@@ -0,0 +1,90 @@
+// Run a single capability's sessionStart by name (argv from hook runner).
+//
+// Static allowlist only — no arbitrary dynamic imports. Each capability is a
+// separate hooks.json entry (separate subprocess); this module does not merge
+// multiple capabilities in one process.
+//
+// Entry path convention (dev repo and plugin copy are identical):
+//   {pluginRoot}/{name}/scripts/index.mjs
+
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { setLogContext, createLogger } from "./logger.mjs";
+
+const log = createLogger("run-capability");
+
+/** modules bundle root (parent of core/ and package-resolution/). */
+const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Shipped capabilities — add a name here; folder layout must match convention. */
+const ALLOWLIST = new Set(["package-resolution"]);
+
+/**
+ * @param {string} name — capability id
+ * @returns {string} absolute path to index.mjs
+ */
+export function capabilityEntryPath(name) {
+  return path.join(PLUGIN_ROOT, name, "scripts", "index.mjs");
+}
+
+/** @returns {(() => Promise<module>) | null} */
+function loadCapabilityModule(name) {
+  if (!ALLOWLIST.has(name)) return null;
+  const href = pathToFileURL(capabilityEntryPath(name)).href;
+  return () => import(href);
+}
+
+function hookDurMs(ctx) {
+  return typeof ctx.startedAtMs === "number" ? Date.now() - ctx.startedAtMs : undefined;
+}
+
+/**
+ * @param {string} name — capability id from process.argv[2]
+ * @param {object} ctx — shared session context (ide, sessionId, workspaceRoots, …)
+ * @returns {Promise<string>} markdown to inject, or "" on no-op / failure
+ */
+export async function runCapability(name, ctx = {}) {
+  const load = loadCapabilityModule(name);
+  if (!load) {
+    log.error("unknown capability", { name });
+    return "";
+  }
+
+  setLogContext({ ide: ctx.ide, sessionId: ctx.sessionId });
+
+  try {
+    const mod = await load();
+    const cap = mod.default;
+    if (!cap?.sessionStart) {
+      log.error("capability missing sessionStart", { name });
+      return "";
+    }
+
+    const text = await cap.sessionStart(ctx);
+    const trimmed = text?.trim() ? text : "";
+
+    if (trimmed) {
+      log.debug("sessionStart injected", {
+        enabled: true,
+        capabilities: name,
+        mode: cap.mode,
+        ...(cap.meta ?? {}),
+        bytes: trimmed.length,
+        durMs: hookDurMs(ctx),
+      });
+    } else {
+      log.debug("sessionStart no-op", { capabilities: name, durMs: hookDurMs(ctx) });
+    }
+
+    return trimmed;
+  } catch (err) {
+    log.error("capability sessionStart failed", {
+      capability: name,
+      error: err?.message ?? String(err),
+    });
+    return "";
+  }
+}
+
+export { ALLOWLIST, PLUGIN_ROOT };
diff --git a/plugins/jfrog/modules/cursor-session-start.mjs b/plugins/jfrog/modules/cursor-session-start.mjs
new file mode 100644
index 0000000..2080efa
--- /dev/null
+++ b/plugins/jfrog/modules/cursor-session-start.mjs
@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Cursor sessionStart hook runner.
+//
+// Usage: node cursor-session-start.mjs <capability>
+// Example: node cursor-session-start.mjs package-resolution
+//
+// stdout: JSON with additional_context. Empty object ("{}") is a no-op.
+
+import process from "node:process";
+
+import { runCapability } from "./core/run-capability.mjs";
+import { ensureAgentsConfigScaffold, agentsConfigLoadWarnings } from "./core/agents-config.mjs";
+import { readStdin, parseSessionId, detectHarness, parseWorkspaceRoots } from "./core/io.mjs";
+import { setLogContext, createLogger } from "./core/logger.mjs";
+
+const HARNESS_ID = "cursor";
+const log = createLogger("session-start");
+
+/** @returns {string | null} JSON stdout payload, or null when there is nothing to inject. */
+function formatSessionStartStdout(text) {
+  if (!text?.trim()) return null;
+  return JSON.stringify({ additional_context: text });
+}
+
+function writeStdout(payload) {
+  if (payload !== null) process.stdout.write(payload);
+}
+
+function writeNoOp() {
+  process.stdout.write("{}");
+}
+
+async function main() {
+  const capability = process.argv[2];
+  if (!capability) {
+    writeNoOp();
+    return;
+  }
+
+  const startedAtMs = Date.now();
+  const stdinRaw = await readStdin();
+  const harness = detectHarness(stdinRaw);
+  if (harness && harness !== HARNESS_ID) {
+    writeNoOp();
+    return;
+  }
+  const sessionId = parseSessionId(stdinRaw);
+  const workspaceRoots = parseWorkspaceRoots(stdinRaw);
+  setLogContext({ ide: HARNESS_ID, sessionId });
+  ensureAgentsConfigScaffold();
+  for (const w of agentsConfigLoadWarnings()) {
+    log.warn(w.message, { path: w.path });
+  }
+  const text = await runCapability(capability, {
+    ide: HARNESS_ID,
+    sessionId,
+    workspaceRoots,
+    startedAtMs,
+  });
+  writeStdout(formatSessionStartStdout(text));
+}
+
+main().catch(() => {
+  writeNoOp();
+  process.exit(0);
+});
diff --git a/plugins/jfrog/modules/package-resolution/scripts/feature-flag.mjs b/plugins/jfrog/modules/package-resolution/scripts/feature-flag.mjs
new file mode 100644
index 0000000..9518969
--- /dev/null
+++ b/plugins/jfrog/modules/package-resolution/scripts/feature-flag.mjs
@@ -0,0 +1,65 @@
+// Feature-flag check — decides the operating `mode` for the session-policy
+// hook (instruction injection).
+//
+// Resolution order (first match wins):
+//
+//   1. JF_AGENT_PACKAGE_RESOLUTION_DISABLE=1 → mode="off" (env kill switch)
+//   2. packageResolution.enabled !== true in      → mode="off" (file-primary gate;
+//      ~/.jfrog/agents-conf.json                   default off in shipped template)
+//   3. jf config (via jf-identity)                → mode="active" when identity is
+//      usable; otherwise mode="enforce" with a `cause` (jf-not-installed /
+//      jf-not-configured) so the session hook can inject a targeted,
+//      remediation-focused advisory notice.
+//
+// Modes:
+//   "off"     — do nothing (no injection).
+//   "active"  — inject resolved Artifactory URLs + routing policy.
+//   "enforce" — jf missing/unconfigured: inject the advisory "routing not
+//               ready" notice (no resolved URLs). This is advisory steering,
+//               not a hard block — real enforcement is durable PM config
+//               (jf setup) + server-side Curation.
+//
+// Repo keys come from agents-conf.json defaultGlobalRepos (resolver.mjs).
+
+import process from "node:process";
+
+import { createLogger } from "../../core/logger.mjs";
+import { getAgentsConfigSection } from "../../core/agents-config.mjs";
+import { getPlatformIdentity, identityLabel } from "../../core/jf-identity.mjs";
+
+const log = createLogger("feature-flag");
+
+function isEnvDisabled() {
+  return process.env.JF_AGENT_PACKAGE_RESOLUTION_DISABLE === "1";
+}
+
+function isEnabledInConfig() {
+  const pr = getAgentsConfigSection("packageResolution");
+  return pr?.enabled === true;
+}
+
+export async function isPackageResolutionEnabled() {
+  if (isEnvDisabled()) {
+    log.debug("off", { reason: "DISABLE" });
+    return { mode: "off", reason: "DISABLE", identity: "none", cause: "ok" };
+  }
+
+  if (!isEnabledInConfig()) {
+    log.debug("off", { reason: "NOT_ENABLED" });
+    return { mode: "off", reason: "NOT_ENABLED", identity: "none", cause: "ok" };
+  }
+
+  const { identity, cause } = getPlatformIdentity();
+  if (!identity) {
+    log.debug("enforce", { reason: "missing-identity", cause });
+    return { mode: "enforce", reason: "missing-identity", identity: "none", cause };
+  }
+
+  log.debug("active", { reason: "jf-config", identity: identityLabel(identity) });
+  return {
+    mode: "active",
+    reason: "jf-config",
+    identity: identityLabel(identity),
+    cause: "ok",
+  };
+}
diff --git a/plugins/jfrog/modules/package-resolution/scripts/index.mjs b/plugins/jfrog/modules/package-resolution/scripts/index.mjs
new file mode 100644
index 0000000..1d55fea
--- /dev/null
+++ b/plugins/jfrog/modules/package-resolution/scripts/index.mjs
@@ -0,0 +1,31 @@
+// package-resolution capability — harness-agnostic entrypoint.
+//
+// Invoked by modules/*-session-start.mjs via run-capability.mjs (argv capability name).
+// Performs NO harness-specific I/O (no stdin/stdout).
+
+import { isPackageResolutionEnabled } from "./feature-flag.mjs";
+import { renderInstruction } from "./render-instruction.mjs";
+
+export const packageResolution = {
+  name: "package-resolution",
+
+  // Last resolved feature-flag mode ("off"|"enforce"|"active") and render detail
+  // for the dispatcher EVENT log line.
+  mode: undefined,
+  meta: undefined,
+
+  /** @returns {Promise<string>} markdown instruction text, or "" when no-op */
+  async sessionStart(ctx = {}) {
+    const flag = await isPackageResolutionEnabled();
+    this.mode = flag.mode;
+    const { text, meta } = await renderInstruction(flag, ctx);
+    this.meta = {
+      reason: flag.reason,
+      identity: flag.identity ?? "-",
+      ...meta,
+    };
+    return text;
+  },
+};
+
+export default packageResolution;
diff --git a/plugins/jfrog/modules/package-resolution/scripts/render-instruction.mjs b/plugins/jfrog/modules/package-resolution/scripts/render-instruction.mjs
new file mode 100644
index 0000000..0780a82
--- /dev/null
+++ b/plugins/jfrog/modules/package-resolution/scripts/render-instruction.mjs
@@ -0,0 +1,175 @@
+// Render the package-resolution session-start instruction text.
+//
+// Extracted from the poc `inject-instructions.mjs` main(): this is the pure,
+// harness-agnostic renderer. It returns a markdown STRING (no stdin/stdout, no
+// IDE-specific shaping) so every per-harness adapter can reuse it.
+//
+//   mode "off"      → "" (nothing to inject)
+//   mode "enforce"  → the advisory "routing not ready" notice
+//   mode "active"   → the routing policy with resolved Artifactory URLs
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import {
+  resolve as resolveRepo,
+  getResolveSessionMeta,
+  prepareSessionResolve,
+  PACKAGE_TYPES,
+} from "./resolver.mjs";
+import { createLogger } from "../../core/logger.mjs";
+
+const log = createLogger("render-instruction");
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(here, "../templates");
+const ACTIVE_TEMPLATE = "package-resolution.md";
+const ENFORCE_TEMPLATE = "package-resolution-unconfigured.md";
+
+// Prose fragment for the enforce-notice {{CAUSE_REMEDIATION}} placeholder.
+function causeRemediation(cause) {
+  if (cause === "jf-not-installed") {
+    return (
+      "Begin by installing the JFrog CLI (`jf`) and adding it to PATH, then " +
+      "configure a JFrog server by following the login flow in the base " +
+      "`jfrog` skill."
+    );
+  }
+  return (
+    "The JFrog CLI is installed and ready. Configure a JFrog server by " +
+    "following the login flow in the base `jfrog` skill to finish enabling " +
+    "routing."
+  );
+}
+
+function jfrogPlatformUrlHint() {
+  const raw = process.env.JFROG_PLATFORM_URL?.trim();
+  if (!raw) {
+    return (
+      "When configuring `jf`, check whether `JFROG_PLATFORM_URL` is set in the " +
+      "IDE launch environment and use it as the platform URL (`jfrog-login-flow.md`)."
+    );
+  }
+  return (
+    "IDE launch env `JFROG_PLATFORM_URL` is `" +
+    raw +
+    "` — use this when configuring `jf` (web login or `jf config add --url`; " +
+    "prefix `https://` if the value is hostname-only)."
+  );
+}
+
+// Rewrite "## Rewrite templates" bullets that still reference an unresolved PM
+// so the agent never sees a usable-but-wrong example URL. Operates only on that
+// section so the resolved-URLs table (which intentionally surfaces the
+// placeholder) is untouched.
+function rewriteUnresolvedBullets(markdown) {
+  const lines = markdown.split("\n");
+  let inSection = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^##\s+Rewrite templates\s*$/.test(line)) {
+      inSection = true;
+      continue;
+    }
+    if (inSection && /^##\s+/.test(line)) {
+      inSection = false;
+      continue;
+    }
+    if (!inSection) continue;
+    const m = line.match(/<no\s+(\w+)\s+repo\s+resolved>/);
+    if (!m) continue;
+    const pm = m[1].toLowerCase();
+    lines[i] =
+      `- \`${pm}\` — **unresolved** (no Artifactory repo for this PM yet). ` +
+      `Per hard rule #5, do not invent a URL: invoke \`jfrog-setup-package-managers\` ` +
+      `for \`${pm}\` BEFORE any direct command. Once the binding is recorded, ` +
+      `route subsequent \`${pm}\` commands through the resolved URL yourself.`;
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Render the instruction text for a resolved feature-flag result.
+ *
+ * Returns BOTH the markdown and a flat `meta` object describing what happened
+ * (cause / resolved repos / cache file / source …). The dispatcher folds `meta`
+ * into its single "sessionStart injected" EVENT line so the default-level log
+ * stays one line but still carries the detail the POC printed.
+ *
+ * @param {{ mode: "off"|"enforce"|"active", cause?: string }} flag
+ * @param {{ workspaceRoots?: string[] }} [ctx]
+ * @returns {Promise<{ text: string, meta: object }>} text is "" when there is
+ *   nothing to inject.
+ */
+export async function renderInstruction(flag, ctx = {}) {
+  if (!flag || flag.mode === "off") return { text: "", meta: { mode: "off" } };
+
+  if (flag.mode === "enforce") {
+    let notice = await readFile(path.join(TEMPLATES_DIR, ENFORCE_TEMPLATE), "utf8");
+    notice = notice.replace(/\{\{CAUSE_REMEDIATION\}\}/g, causeRemediation(flag.cause));
+    notice = notice.replace(/\{\{JFROG_PLATFORM_URL_HINT\}\}/g, jfrogPlatformUrlHint());
+    // Detail line — kept at debug so the default level shows a single EVENT per
+    // session (the dispatcher's "sessionStart injected"). Raise the level to see
+    // the cause/byte breakdown.
+    log.debug("enforce notice rendered", { cause: flag.cause, bytes: notice.length });
+    return {
+      text: notice,
+      meta: { cause: flag.cause, template: ENFORCE_TEMPLATE },
+    };
+  }
+
+  // active: pre-resolve every package type and substitute concrete URLs.
+  await prepareSessionResolve({ workspaceRoots: ctx.workspaceRoots });
+  const resolved = {};
+  const unresolved = [];
+  for (const t of PACKAGE_TYPES) {
+    const r = await resolveRepo(t);
+    if (r) resolved[t] = r;
+    else unresolved.push(t);
+  }
+
+  let template = await readFile(path.join(TEMPLATES_DIR, ACTIVE_TEMPLATE), "utf8");
+  template = template.replace(/\{\{(\w+)_URL\}\}/g, (_, type) => {
+    const r = resolved[type.toLowerCase()];
+    return r ? r.baseUrl : `<no ${type} repo resolved>`;
+  });
+  template = rewriteUnresolvedBullets(template);
+
+  const resolvedCompact =
+    Object.entries(resolved).map(([t, r]) => `${t}:${r.repoKey}`).join(",") || "-";
+  const unresolvedCompact = unresolved.join(",") || "-";
+
+  const rm = getResolveSessionMeta();
+  // Detail line — kept at debug (see the enforce branch above) so the default
+  // level shows a single EVENT per session.
+  log.debug("active instruction rendered", {
+    resolved: resolvedCompact,
+    unresolved: unresolvedCompact,
+    source: rm?.source ?? "-",
+    bytes: template.length,
+  });
+
+  const meta = {
+    source: rm?.source ?? "-",
+    serverId: rm?.serverId ?? "-",
+    cacheFile: rm?.cacheFile ?? "-",
+    cacheHit: rm?.cacheHit ?? false,
+    resolveSource: rm?.resolveSource ?? "-",
+    resolved: resolvedCompact,
+    unresolved: unresolvedCompact,
+    template: ACTIVE_TEMPLATE,
+  };
+
+  // Workspace fields only when a local file was read and applied to resolution.
+  if (rm?.workspaceConfigFile) {
+    meta.workspaceRootsCount = rm.workspaceRootsCount;
+    meta.workspaceConfigFile = rm.workspaceConfigFile;
+    meta.workspaceOverrides = rm.workspaceOverrides;
+  }
+
+  return { text: template, meta };
+}
+
+export { getResolveSessionMeta };
diff --git a/plugins/jfrog/modules/package-resolution/scripts/repo-types.mjs b/plugins/jfrog/modules/package-resolution/scripts/repo-types.mjs
new file mode 100644
index 0000000..6b0a7de
--- /dev/null
+++ b/plugins/jfrog/modules/package-resolution/scripts/repo-types.mjs
@@ -0,0 +1,19 @@
+// Package-type constants shared by resolver and workspace overlay.
+
+export const PACKAGE_TYPES = ["npm", "pypi", "maven", "go", "docker", "helm", "nuget"];
+
+const TYPE_PACKAGE_TYPE = {
+  npm: "npm",
+  pypi: "pypi",
+  maven: "maven",
+  go: "go",
+  docker: "docker",
+  helm: "helm",
+  nuget: "nuget",
+};
+
+export function repoMatchesPackageType(config, type) {
+  const expected = TYPE_PACKAGE_TYPE[type];
+  if (!expected || !config?.packageType) return true;
+  return String(config.packageType).toLowerCase() === expected;
+}
diff --git a/plugins/jfrog/modules/package-resolution/scripts/resolver.mjs b/plugins/jfrog/modules/package-resolution/scripts/resolver.mjs
new file mode 100644
index 0000000..aee1536
--- /dev/null
+++ b/plugins/jfrog/modules/package-resolution/scripts/resolver.mjs
@@ -0,0 +1,400 @@
+// Repo resolver — maps package type → Artifactory repo key (+ URL for the
+// session-policy instruction injection and the jf-setup skill).
+//
+// Session resolution (once per hook process, per jf server id).
+// Identity comes from a separate local `jf config export` (always runs; cheap).
+// This module only controls Artifactory HTTP:
+//   1. Valid local cache ~/.jfrog/skills-cache/package-resolution.json → no HTTP
+//   2. Else read defaultGlobalRepos from ~/.jfrog/agents-conf.json
+//   3. Optional verify via GET …/api/repositories/{key} (verifyRepos, default true)
+//   4. Write snapshot to cache file (TTL from agents-conf.json cacheTtlDays)
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+import { createLogger } from "../../core/logger.mjs";
+import { getAgentsConfigMtimeMs, loadAgentsConfig } from "../../core/agents-config.mjs";
+import { getPlatformIdentity } from "../../core/jf-identity.mjs";
+import { PACKAGE_TYPES, repoMatchesPackageType } from "./repo-types.mjs";
+import { pickWorkspaceConfigRoot, loadWorkspaceConfig } from "./workspace-config.mjs";
+
+const log = createLogger("resolver");
+
+function cacheDir() {
+  return path.join(homedir(), ".jfrog", "skills-cache");
+}
+
+function cacheFile() {
+  return path.join(cacheDir(), "package-resolution.json");
+}
+
+const CACHE_SCHEMA_VERSION = 1;
+
+/** Default cache TTL in ms (7 days) — used when agents-conf.json omits cacheTtlDays. */
+export const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+export { PACKAGE_TYPES };
+
+/** In-process snapshot after first resolve pass in this hook invocation. */
+const SESSION = {
+  serverId: null,
+  meta: null,
+  byType: null,
+};
+
+function identityOrNull() {
+  return getPlatformIdentity().identity;
+}
+
+function effectiveServerId(hint) {
+  if (hint) return hint;
+  return identityOrNull()?.serverId ?? "default";
+}
+
+function packageResolveSource(serverId, { via } = {}) {
+  const suffix = via ? ` via=${via}` : "";
+  return `package-resolution:${cacheFile()}#${serverId}${suffix}`;
+}
+
+/** Last session-wide resolve metadata (for inject-instructions EVENT log). */
+export function getResolveSessionMeta() {
+  return SESSION.meta;
+}
+
+function urlFor(type, repoKey, base) {
+  switch (type) {
+    case "npm":
+      return `${base}/api/npm/${repoKey}/`;
+    case "pypi":
+      return `${base}/api/pypi/${repoKey}/simple/`;
+    case "maven":
+      return `${base}/${repoKey}/`;
+    case "go":
+      return `${base}/api/go/${repoKey}`;
+    case "docker":
+      return new URL(base).host + "/" + repoKey;
+    case "helm":
+      return `${base}/${repoKey}/`;
+    case "nuget":
+      return `${base}/api/nuget/v3/${repoKey}/index.json`;
+    default:
+      return `${base}/${repoKey}/`;
+  }
+}
+
+async function readCacheFile() {
+  const file = cacheFile();
+  try {
+    const raw = await readFile(file, "utf8");
+    return { data: JSON.parse(raw), file };
+  } catch {
+    return { data: null, file };
+  }
+}
+
+async function writeCacheFile(root) {
+  const file = cacheFile();
+  const payload = {
+    schemaVersion: CACHE_SCHEMA_VERSION,
+    servers: root.servers ?? {},
+  };
+  const creating = !existsSync(file);
+  await mkdir(cacheDir(), { recursive: true });
+  await writeFile(file, JSON.stringify(payload, null, 2));
+  if (creating) {
+    log.info("created global cache file", { cache: file });
+  }
+}
+
+function normalizeServerEntry(entry) {
+  if (!entry?.repositories || typeof entry.repositories !== "object") return null;
+  return {
+    repositories: { ...entry.repositories },
+    cached_at: entry.cached_at,
+    source: entry.source,
+    agentsConfigMtimeMs: entry.agentsConfigMtimeMs,
+  };
+}
+
+function isEntryFresh(entry, agentsConfigMtimeMs, cacheTtlDays) {
+  if (!entry?.cached_at) return false;
+  if (cacheTtlDays === 0) return false;
+  if (entry.agentsConfigMtimeMs !== agentsConfigMtimeMs) return false;
+  const ttlMs = cacheTtlDays * 24 * 60 * 60 * 1000;
+  const age = Date.now() - new Date(entry.cached_at).getTime();
+  return age >= 0 && age < ttlMs;
+}
+
+/** Normalize on-disk cache to `{ schemaVersion, servers }` (migrates legacy flat layout). */
+function normalizeCacheRoot(data) {
+  const servers = {};
+  if (!data || typeof data !== "object") {
+    return { schemaVersion: CACHE_SCHEMA_VERSION, servers };
+  }
+  if (data.servers && typeof data.servers === "object") {
+    for (const [serverId, entry] of Object.entries(data.servers)) {
+      const normalized = normalizeServerEntry(entry);
+      if (normalized) servers[serverId] = normalized;
+    }
+    return {
+      schemaVersion:
+        typeof data.schemaVersion === "number" ? data.schemaVersion : CACHE_SCHEMA_VERSION,
+      servers,
+    };
+  }
+  for (const [key, val] of Object.entries(data)) {
+    if (key === "schemaVersion") continue;
+    const normalized = normalizeServerEntry(val);
+    if (normalized) servers[key] = normalized;
+  }
+  return { schemaVersion: CACHE_SCHEMA_VERSION, servers };
+}
+
+async function fetchRepoConfig(repoKey) {
+  const id = identityOrNull();
+  if (!id) return null;
+  const url = `${id.url}/artifactory/api/repositories/${encodeURIComponent(repoKey)}`;
+  log.debug("verifying repo", { repoKey, url });
+  try {
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${id.token}`, Accept: "application/json" },
+    });
+    if (!res.ok) {
+      log.debug("repo verify miss", { repoKey, status: res.status });
+      return null;
+    }
+    return await res.json();
+  } catch (err) {
+    log.warn("repo verify threw", { repoKey, error: err?.message ?? String(err) });
+    return null;
+  }
+}
+
+function buildResolveMeta(serverId, entry, { via, cacheFile }) {
+  return {
+    serverId,
+    source: packageResolveSource(serverId, { via }),
+    cacheFile,
+    resolveSource: entry.source ?? via,
+    cached_at: entry.cached_at,
+    cacheHit: via === "cache",
+  };
+}
+
+function entryToByType(entry, base) {
+  const byType = {};
+  for (const [type, repoKey] of Object.entries(entry.repositories ?? {})) {
+    if (!repoKey) continue;
+    byType[type] = {
+      type,
+      repoKey,
+      baseUrl: urlFor(type, repoKey, base),
+    };
+  }
+  return byType;
+}
+
+async function refreshServerCache(serverId) {
+  const id = identityOrNull();
+  const base = id ? `${id.url}/artifactory` : "";
+  const repositories = {};
+  const pr = loadAgentsConfig().packageResolution;
+  const verifyRepos = pr.verifyRepos;
+  const adminRepos = pr.defaultGlobalRepos ?? {};
+  const agentsConfigMtimeMs = getAgentsConfigMtimeMs();
+
+  for (const type of PACKAGE_TYPES) {
+    const repoKey = adminRepos[type];
+    if (!repoKey) {
+      log.debug("unconfigured type", { type });
+      continue;
+    }
+
+    if (verifyRepos) {
+      const config = await fetchRepoConfig(repoKey);
+      if (!config || !repoMatchesPackageType(config, type)) {
+        log.warn("repo verify failed", { type, repoKey, serverId });
+        continue;
+      }
+      repositories[type] = repoKey;
+      log.debug("resolved from agents-conf.json (verified)", { type, repoKey });
+    } else {
+      repositories[type] = repoKey;
+      log.debug("resolved from agents-conf.json (trusted)", { type, repoKey });
+    }
+  }
+
+  const source = verifyRepos ? "verified" : "agents-config";
+
+  const entry = {
+    repositories,
+    cached_at: new Date().toISOString(),
+    source,
+    agentsConfigMtimeMs,
+  };
+
+  const { data: cacheRoot } = await readCacheFile();
+  const root = normalizeCacheRoot(cacheRoot);
+  root.servers[serverId] = entry;
+  await writeCacheFile(root);
+
+  const via = verifyRepos ? "refresh-verified" : "refresh-agents-config";
+  const file = cacheFile();
+  SESSION.serverId = serverId;
+  SESSION.byType = entryToByType(entry, base);
+  SESSION.meta = buildResolveMeta(serverId, entry, { via, cacheFile: file });
+  log.debug("cache refreshed", {
+    serverId,
+    source,
+    resolved: Object.keys(repositories).join(","),
+    cache: file,
+  });
+}
+
+async function loadFreshCacheEntry(serverId) {
+  const pr = loadAgentsConfig().packageResolution;
+  const agentsConfigMtimeMs = getAgentsConfigMtimeMs();
+  const { data, file } = await readCacheFile();
+  const entry = normalizeServerEntry(normalizeCacheRoot(data).servers[serverId]);
+  if (!entry || !isEntryFresh(entry, agentsConfigMtimeMs, pr.cacheTtlDays)) return null;
+
+  const id = identityOrNull();
+  const base = id ? `${id.url}/artifactory` : "";
+  SESSION.serverId = serverId;
+  SESSION.byType = entryToByType(entry, base);
+  SESSION.meta = buildResolveMeta(serverId, entry, { via: "cache", cacheFile: file });
+  log.debug("cache hit", {
+    serverId,
+    source: entry.source,
+    ageMs: Date.now() - new Date(entry.cached_at).getTime(),
+    cache: file,
+  });
+  return entry;
+}
+
+async function ensureSessionResolved(serverIdHint) {
+  const serverId = effectiveServerId(serverIdHint);
+  if (SESSION.serverId === serverId && SESSION.byType) return;
+
+  const cached = await loadFreshCacheEntry(serverId);
+  if (cached) return;
+
+  await refreshServerCache(serverId);
+}
+
+function workspaceOverlayMetaApplied(workspaceRoots, pick, overridden) {
+  return {
+    workspaceRootsCount: workspaceRoots.length,
+    workspaceConfigFile: pick.configFile,
+    workspaceOverrides: overridden.join(","),
+  };
+}
+
+async function applyWorkspaceOverlay(workspaceRoots) {
+  const roots = workspaceRoots?.length ? workspaceRoots : [];
+  const pick = pickWorkspaceConfigRoot(roots);
+
+  if (!pick) return;
+
+  const ws = await loadWorkspaceConfig(pick);
+  if (!ws) {
+    log.debug("workspace overlay skipped", { reason: "unreadable", root: pick.root });
+    return;
+  }
+
+  const id = identityOrNull();
+  const base = id ? `${id.url}/artifactory` : "";
+  const overridden = [];
+
+  for (const [type, repoKey] of Object.entries(ws.repositories)) {
+    if (!repoKey || !PACKAGE_TYPES.includes(type)) continue;
+    SESSION.byType[type] = {
+      type,
+      repoKey,
+      baseUrl: urlFor(type, repoKey, base),
+    };
+    overridden.push(`${type}:${repoKey}`);
+  }
+
+  if (!overridden.length) {
+    log.debug("workspace overlay skipped", { reason: "no-repositories", root: pick.root });
+    return;
+  }
+
+  const hadGlobal = SESSION.meta?.resolveSource;
+  SESSION.meta = {
+    ...SESSION.meta,
+    ...workspaceOverlayMetaApplied(roots, pick, overridden),
+    resolveSource: hadGlobal ? "mixed-workspace" : "workspace-override",
+  };
+
+  log.debug("workspace overlay applied", {
+    root: pick.root,
+    file: pick.configFile,
+    overridden: overridden.join(","),
+  });
+}
+
+/**
+ * Global cache resolve + optional workspace-local overlay (first root with a config file).
+ * Call once per sessionStart before resolve(type) loops.
+ */
+export async function prepareSessionResolve({ serverId, workspaceRoots } = {}) {
+  await ensureSessionResolved(serverId);
+  await applyWorkspaceOverlay(workspaceRoots);
+}
+
+export async function resolve(type, { serverId: serverIdHint } = {}) {
+  log.debug("resolve start", { type, serverId: effectiveServerId(serverIdHint) });
+
+  await ensureSessionResolved(serverIdHint);
+
+  const hit = SESSION.byType?.[type];
+  if (!hit) {
+    log.debug("resolve miss", { type });
+    return null;
+  }
+
+  const result = {
+    ...hit,
+    source: SESSION.meta?.source ?? "unknown",
+    serverId: SESSION.meta?.serverId,
+    cacheFile: SESSION.meta?.cacheFile,
+  };
+  log.debug("resolved", result);
+  return result;
+}
+
+/** Force cache refresh (e.g. tests or future --refresh flag). */
+export async function invalidateResolveCache(serverIdHint) {
+  SESSION.serverId = null;
+  SESSION.byType = null;
+  SESSION.meta = null;
+  const serverId = effectiveServerId(serverIdHint);
+  const { data } = await readCacheFile();
+  const root = normalizeCacheRoot(data);
+  if (root.servers[serverId]) {
+    delete root.servers[serverId];
+    await writeCacheFile(root);
+  }
+}
+
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const type = process.argv[2];
+  if (!type) {
+    console.error("usage: node lib/resolver.mjs <type>");
+    console.error("       types: npm pypi maven go docker helm nuget");
+    process.exit(1);
+  }
+  const result = await resolve(type);
+  if (!result) {
+    console.error(`No repo resolved for type=${type}.`);
+    console.error("Live mode needs a configured `jf` server with an access token (run `jf c add`).");
+    process.exit(2);
+  }
+  console.log(JSON.stringify(result, null, 2));
+}
diff --git a/plugins/jfrog/modules/package-resolution/scripts/workspace-config.mjs b/plugins/jfrog/modules/package-resolution/scripts/workspace-config.mjs
new file mode 100644
index 0000000..e449f6f
--- /dev/null
+++ b/plugins/jfrog/modules/package-resolution/scripts/workspace-config.mjs
@@ -0,0 +1,52 @@
+// Workspace-local repo overrides — `.jfrog/local/package-resolution.json`
+// Schema: `{ "repositories": { "<pkgType>": "<repoKey>", ... } }` only.
+//
+// Multi-root: first root (in harness order) that has the file wins.
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export const WORKSPACE_CONFIG_FILE = "package-resolution.json";
+
+/**
+ * First workspace root that has `.jfrog/local/package-resolution.json`.
+ *
+ * @param {string[]} workspaceRoots
+ * @returns {{ root: string, configFile: string } | null}
+ */
+export function pickWorkspaceConfigRoot(workspaceRoots) {
+  if (!workspaceRoots?.length) return null;
+  for (const root of workspaceRoots) {
+    if (typeof root !== "string" || !root) continue;
+    const configFile = path.join(root, ".jfrog", "local", WORKSPACE_CONFIG_FILE);
+    if (existsSync(configFile)) {
+      return { root, configFile };
+    }
+  }
+  return null;
+}
+
+function normalizeWorkspaceConfig(data) {
+  if (!data?.repositories || typeof data.repositories !== "object") return null;
+  const repositories = {};
+  for (const [type, repoKey] of Object.entries(data.repositories)) {
+    if (typeof repoKey === "string" && repoKey) repositories[type] = repoKey;
+  }
+  if (!Object.keys(repositories).length) return null;
+  return { repositories };
+}
+
+/**
+ * @param {{ root: string, configFile: string }} pick
+ * @returns {Promise<{ repositories: Record<string, string> } | null>}
+ */
+export async function loadWorkspaceConfig(pick) {
+  if (!pick?.configFile) return null;
+  try {
+    const raw = await readFile(pick.configFile, "utf8");
+    return normalizeWorkspaceConfig(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
diff --git a/plugins/jfrog/modules/package-resolution/templates/package-resolution-unconfigured.md b/plugins/jfrog/modules/package-resolution/templates/package-resolution-unconfigured.md
new file mode 100644
index 0000000..ddd26f0
--- /dev/null
+++ b/plugins/jfrog/modules/package-resolution/templates/package-resolution-unconfigured.md
@@ -0,0 +1,35 @@
+# Package Resolution — JFrog Artifactory routing is NOT READY
+
+Your organization routes every package fetch through JFrog Artifactory, but routing
+cannot run yet — `jf` has no configured server. Package managers still point at
+**public** registries until setup completes.
+
+**Do not run direct package installs** (including `docker pull` / `docker run`) while routing is not ready. When asked to
+install or pull images, tell the user routing is blocked and complete setup first.
+
+## Read this first
+
+Authoritative procedure:
+
+1. **`jfrog-setup-package-managers`** skill — **Step 0** for this state.
+2. Base **`jfrog`** skill — `references/jfrog-login-flow.md` for server login.
+
+## What to do instead
+
+{{CAUSE_REMEDIATION}}
+
+{{JFROG_PLATFORM_URL_HINT}}
+
+1. Confirm `jf` is installed (`jf --version`).
+2. Configure a JFrog server (login flow or `jf config add` with access token);
+   confirm with `jf config show`.
+3. Invoke **`jfrog-setup-package-managers`** to bind PMs this workspace needs.
+
+Start a **new session** after setup — concrete Artifactory URLs are injected.
+Then re-issue the install.
+
+## Enablement
+
+Routing is opt-in. Set `packageResolution.enabled: true` in `~/.jfrog/agents-conf.json`.
+On first session, if that file is missing, the hook scaffolds it from the shipped
+template (`packageResolution.enabled` defaults to `false`).
diff --git a/plugins/jfrog/modules/package-resolution/templates/package-resolution.md b/plugins/jfrog/modules/package-resolution/templates/package-resolution.md
new file mode 100644
index 0000000..69dda99
--- /dev/null
+++ b/plugins/jfrog/modules/package-resolution/templates/package-resolution.md
@@ -0,0 +1,68 @@
+# Package Resolution — Artifactory First
+
+Your organization mediates **every package fetch** through JFrog Artifactory. Before
+any package install — shell, sub-agent, or MCP tool — route through the resolved
+Artifactory repository below.
+
+## Resolved URLs for this session
+
+| Type | Use this URL |
+|---|---|
+| npm | `{{NPM_URL}}` |
+| pypi | `{{PYPI_URL}}` |
+| maven | `{{MAVEN_URL}}` |
+| go | `{{GO_URL}}` |
+| docker | `{{DOCKER_URL}}` |
+| helm | `{{HELM_URL}}` |
+| nuget | `{{NUGET_URL}}` |
+
+If any row shows `<no … repo resolved>`, ask the user which repo to use and invoke
+`jfrog-setup-package-managers` — do not guess or call public registries.
+
+## Rewrite templates
+
+Direct installs — form the command yourself (no automatic rewriter; `jf setup` PM
+config and server-side Curation back this):
+
+- `npm install <pkg>` → `npm install <pkg> --registry {{NPM_URL}}`
+- `pip install <pkg>` → `pip install <pkg> --index-url {{PYPI_URL}}`
+- `poetry add <pkg>` → first `poetry source add jfrog {{PYPI_URL}} --priority=primary`
+- `go get <mod>` → `GOPROXY={{GO_URL}},direct go get <mod>`
+- `docker pull <img>` → `docker pull {{DOCKER_URL}}/<img>` (bare refs only — no explicit registry host)
+- `mvn ...` / `gradle ...` → config-driven; run `jfrog-setup-package-managers` if not yet bound.
+
+## Hard rules
+
+1. **Only URLs in the table above.** No default upstream registries, mirrors, or CDNs.
+2. **Never override flags the user typed** (`--registry`, `--index-url`, `GOPROXY=…`) — surface and ask first.
+3. **Indirect installs** (`npx`, `pip install -r`, `docker build`, postinstall scripts) — trust PM config files; if missing, run `jfrog-setup-package-managers`.
+4. **Curation block** — surface the reason verbatim; do not retry another host.
+5. **Unresolved PM** — if the table shows `<no … repo resolved>` for the PM the user
+   requested, **do not run the original command** (`docker pull …`, `npm install …`,
+   etc.). In order: (a) invoke `jfrog-setup-package-managers` for that PM,
+   (b) wait until `.jfrog/local/package-resolution.json` records the binding,
+   (c) re-issue routed via the templates above. A successful exit from an unrouted
+   command still violates policy — including local Docker cache hits.
+6. **401/403 from JFrog** — run `jfrog-setup-package-managers` (`jf setup`); never raw `docker login` / `npm login` / `pip config`.
+
+## Docker (before any `docker pull`)
+
+- **Bare refs go to Docker Hub.** `docker pull alpine:latest` (no registry host) uses
+  `docker.io` — `jf setup docker` does **not** change that. You must prefix:
+  `docker pull <host>/<repoKey>/<img>` using the docker row above (`host/repoKey`, not
+  `https://…`).
+- **Unresolved docker ⇒ no docker commands.** If the docker row shows
+  `<no … repo resolved>`, do not run `docker pull/run/create` until setup completes
+  and you have a prefixed ref. Do not “try first, fix later.”
+- **Explicit host = user choice.** `docker pull ghcr.io/foo/bar` — leave as-is; do not
+  re-prefix to JFrog.
+
+When a package manifest appears and `.jfrog/local/package-resolution.json` lacks the
+matching PM, invoke `jfrog-setup-package-managers` proactively (see that skill for
+manifest → PM mapping).
+
+## Enablement
+
+Opt-in via admin config. Set `packageResolution.enabled: true` in `~/.jfrog/agents-conf.json`.
+On first session, if that file is missing, the hook scaffolds it from the shipped
+template (`packageResolution.enabled` defaults to `false`).