@promptscript/cli 1.20.0 → 1.21.0

package/index.js

@@ -311,6 +311,13 @@ var init_manifest = __esm({
   }
 });
 
+// packages/core/src/types/models.ts
+var init_models = __esm({
+  "packages/core/src/types/models.ts"() {
+    "use strict";
+  }
+});
+
 // packages/core/src/types/policy.ts
 var init_policy = __esm({
   "packages/core/src/types/policy.ts"() {
@@ -362,6 +369,7 @@ var init_types = __esm({
     init_convention();
     init_lockfile();
     init_manifest();
+    init_models();
     init_policy();
     init_prettier();
     init_provenance();
@@ -7649,6 +7657,651 @@ var init_agent_capabilities = __esm({
   }
 });
 
+// packages/core/src/model-profiles.ts
+function release(provider, family, version, id, displayName, fields = {}) {
+  return {
+    id,
+    provider,
+    family,
+    version,
+    displayName,
+    apiId: id,
+    aliases: [],
+    // A release with a successor is legacy unless it says otherwise.
+    status: fields.successor === void 0 ? "current" : "legacy",
+    targets: {},
+    ...fields
+  };
+}
+function claude(line, version, fields = {}) {
+  const { id = `claude-${line}-${version.replaceAll(".", "-")}`, displayName, ...rest } = fields;
+  const name = `${line.charAt(0).toUpperCase()}${line.slice(1)}`;
+  return release(
+    "anthropic",
+    `claude-${line}`,
+    version,
+    id,
+    displayName ?? `Claude ${name} ${version}`,
+    {
+      aliases: [`${line}-${version}`],
+      ...rest
+    }
+  );
+}
+var openai, google, xai, MODEL_PROFILES;
+var init_model_profiles = __esm({
+  "packages/core/src/model-profiles.ts"() {
+    "use strict";
+    openai = (family, version, id, displayName, fields) => release("openai", family, version, id, displayName, fields);
+    google = (family, version, id, displayName, fields) => release("google", family, version, id, displayName, fields);
+    xai = (family, version, id, displayName, fields) => release("xai", family, version, id, displayName, fields);
+    MODEL_PROFILES = [
+      // Anthropic
+      claude("opus", "4", {
+        apiId: "claude-opus-4-20250514",
+        status: "retired",
+        successor: "claude-opus-4-1",
+        releaseDate: "2025-05-22",
+        retirementDate: "2026-06-15"
+      }),
+      claude("opus", "4.1", {
+        apiId: "claude-opus-4-1-20250805",
+        status: "retired",
+        successor: "claude-opus-4-5",
+        releaseDate: "2025-08-05",
+        retirementDate: "2026-08-05"
+      }),
+      claude("opus", "4.5", {
+        apiId: "claude-opus-4-5-20251101",
+        successor: "claude-opus-4-6",
+        releaseDate: "2025-11-24"
+      }),
+      claude("opus", "4.6", { successor: "claude-opus-4-7" }),
+      claude("opus", "4.7", { successor: "claude-opus-4-8" }),
+      claude("opus", "4.8", { successor: "claude-opus-5" }),
+      claude("opus", "5", { successor: "claude-opus-5-5", releaseDate: "2026-07-24" }),
+      claude("opus", "5.5", { releaseDate: "2026-09-22" }),
+      claude("sonnet", "3.5", {
+        id: "claude-3-5-sonnet",
+        apiId: "claude-3-5-sonnet-20241022",
+        displayName: "Claude 3.5 Sonnet",
+        aliases: ["sonnet-3.5", "claude-3-5-sonnet-latest"],
+        status: "retired",
+        successor: "claude-3-7-sonnet",
+        releaseDate: "2024-10-22",
+        retirementDate: "2025-10-28"
+      }),
+      claude("sonnet", "3.7", {
+        id: "claude-3-7-sonnet",
+        apiId: "claude-3-7-sonnet-20250219",
+        displayName: "Claude 3.7 Sonnet",
+        aliases: ["sonnet-3.7", "claude-3-7-sonnet-latest"],
+        status: "retired",
+        successor: "claude-sonnet-4",
+        releaseDate: "2025-02-24",
+        retirementDate: "2026-02-19"
+      }),
+      claude("sonnet", "4", {
+        apiId: "claude-sonnet-4-20250514",
+        status: "retired",
+        successor: "claude-sonnet-4-5",
+        releaseDate: "2025-05-22",
+        retirementDate: "2026-06-15"
+      }),
+      claude("sonnet", "4.5", {
+        apiId: "claude-sonnet-4-5-20250929",
+        successor: "claude-sonnet-4-6",
+        releaseDate: "2025-09-29"
+      }),
+      claude("sonnet", "4.6", { successor: "claude-sonnet-5" }),
+      claude("sonnet", "5", { releaseDate: "2026-06-30" }),
+      claude("haiku", "3.5", {
+        id: "claude-3-5-haiku",
+        apiId: "claude-3-5-haiku-20241022",
+        displayName: "Claude 3.5 Haiku",
+        aliases: ["haiku-3.5", "claude-3-5-haiku-latest"],
+        status: "retired",
+        successor: "claude-haiku-4-5",
+        releaseDate: "2024-10-22",
+        retirementDate: "2026-02-19"
+      }),
+      claude("haiku", "4.5", { apiId: "claude-haiku-4-5-20251001", releaseDate: "2025-10-15" }),
+      claude("fable", "5", { successor: "claude-fable-5-1", releaseDate: "2026-06-09" }),
+      claude("fable", "5.1", { releaseDate: "2026-09-01" }),
+      claude("mythos", "5", { successor: "claude-mythos-5-1", releaseDate: "2026-06-09" }),
+      claude("mythos", "5.1", { releaseDate: "2026-09-01" }),
+      // OpenAI
+      openai("gpt-4o", "4o", "gpt-4o", "GPT-4o", { successor: "gpt-4.1", releaseDate: "2024-05-13" }),
+      openai("gpt", "4.1", "gpt-4.1", "GPT-4.1", { successor: "gpt-5.5", releaseDate: "2025-04-14" }),
+      openai("gpt", "5", "gpt-5", "GPT-5", {
+        status: "deprecated",
+        successor: "gpt-5.1",
+        releaseDate: "2025-08-07",
+        retirementDate: "2026-12-11"
+      }),
+      openai("gpt", "5.1", "gpt-5.1", "GPT-5.1", {
+        status: "deprecated",
+        successor: "gpt-5.2",
+        releaseDate: "2025-11-13"
+      }),
+      openai("gpt", "5.2", "gpt-5.2", "GPT-5.2", { successor: "gpt-5.4", releaseDate: "2025-12-11" }),
+      openai("gpt", "5.4", "gpt-5.4", "GPT-5.4", { successor: "gpt-5.5", releaseDate: "2026-03-05" }),
+      openai("gpt", "5.5", "gpt-5.5", "GPT-5.5", {
+        successor: "gpt-5.6-sol",
+        releaseDate: "2026-04-24"
+      }),
+      openai("gpt-mini", "5", "gpt-5-mini", "GPT-5 mini", {
+        status: "deprecated",
+        successor: "gpt-5.4-mini",
+        releaseDate: "2025-08-07",
+        retirementDate: "2026-12-11"
+      }),
+      openai("gpt-mini", "5.4", "gpt-5.4-mini", "GPT-5.4 mini", {
+        successor: "gpt-5.6-terra",
+        releaseDate: "2026-03-17"
+      }),
+      openai("gpt-nano", "5", "gpt-5-nano", "GPT-5 nano", {
+        status: "deprecated",
+        successor: "gpt-5.4-nano",
+        releaseDate: "2025-08-07",
+        retirementDate: "2026-12-11"
+      }),
+      openai("gpt-nano", "5.4", "gpt-5.4-nano", "GPT-5.4 nano", {
+        successor: "gpt-5.6-luna",
+        releaseDate: "2026-03-17"
+      }),
+      openai("gpt-codex", "5", "gpt-5-codex", "GPT-5-Codex", { successor: "gpt-5.1-codex" }),
+      openai("gpt-codex", "5.1", "gpt-5.1-codex", "GPT-5.1-Codex", {
+        successor: "gpt-5.2-codex",
+        releaseDate: "2025-11-13"
+      }),
+      openai("gpt-codex", "5.2", "gpt-5.2-codex", "GPT-5.2-Codex", {
+        status: "deprecated",
+        successor: "gpt-5.3-codex",
+        releaseDate: "2026-01-14"
+      }),
+      openai("gpt-codex", "5.3", "gpt-5.3-codex", "GPT-5.3-Codex", { releaseDate: "2026-02-24" }),
+      openai("gpt-codex-max", "5.1", "gpt-5.1-codex-max", "GPT-5.1-Codex-Max", {
+        successor: "gpt-5.2-codex",
+        releaseDate: "2025-12-04"
+      }),
+      openai("gpt-codex-mini", "5.1", "gpt-5.1-codex-mini", "GPT-5.1-Codex-Mini", {
+        successor: "gpt-5.3-codex",
+        releaseDate: "2025-11-13"
+      }),
+      openai("gpt-sol", "5.6", "gpt-5.6-sol", "GPT-5.6 Sol", {
+        successor: "gpt-6-astra",
+        releaseDate: "2026-07-09"
+      }),
+      openai("gpt-sol", "6", "gpt-6-sol", "GPT-6 Sol", { releaseDate: "2026-09-22" }),
+      openai("gpt-terra", "5.6", "gpt-5.6-terra", "GPT-5.6 Terra", {
+        successor: "gpt-6-sol",
+        releaseDate: "2026-07-09"
+      }),
+      openai("gpt-luna", "5.6", "gpt-5.6-luna", "GPT-5.6 Luna", {
+        successor: "gpt-6-luna",
+        releaseDate: "2026-07-09"
+      }),
+      openai("gpt-luna", "6", "gpt-6-luna", "GPT-6 Luna", { releaseDate: "2026-09-22" }),
+      openai("gpt-astra", "6", "gpt-6-astra", "GPT-6 Astra", { releaseDate: "2026-09-03" }),
+      openai("o3", "3", "o3", "o3", {
+        status: "deprecated",
+        successor: "gpt-5.5",
+        releaseDate: "2025-04-16",
+        retirementDate: "2026-12-11"
+      }),
+      openai("o4-mini", "4", "o4-mini", "o4-mini", {
+        status: "deprecated",
+        successor: "gpt-5.4-mini",
+        releaseDate: "2025-04-16",
+        retirementDate: "2026-10-23"
+      }),
+      // Google
+      google("gemini-pro", "2.5", "gemini-2.5-pro", "Gemini 2.5 Pro", {
+        successor: "gemini-3.1-pro-preview",
+        releaseDate: "2025-06-17"
+      }),
+      google("gemini-pro", "3.1", "gemini-3.1-pro-preview", "Gemini 3.1 Pro", {
+        aliases: ["Gemini 3.1 Pro Preview"],
+        releaseDate: "2026-02-19"
+      }),
+      google("gemini-flash", "2.5", "gemini-2.5-flash", "Gemini 2.5 Flash", {
+        successor: "gemini-3.5-flash",
+        releaseDate: "2025-06-17"
+      }),
+      google("gemini-flash", "3.5", "gemini-3.5-flash", "Gemini 3.5 Flash", {
+        successor: "gemini-3.6-flash",
+        releaseDate: "2026-05-19"
+      }),
+      google("gemini-flash", "3.6", "gemini-3.6-flash", "Gemini 3.6 Flash", {
+        successor: "gemini-3.7-flash",
+        releaseDate: "2026-07-21"
+      }),
+      google("gemini-flash", "3.7", "gemini-3.7-flash", "Gemini 3.7 Flash", {
+        successor: "gemini-3.8-flash",
+        releaseDate: "2026-08-13"
+      }),
+      google("gemini-flash", "3.8", "gemini-3.8-flash", "Gemini 3.8 Flash", {
+        releaseDate: "2026-09-02"
+      }),
+      google("gemini-flash-lite", "2.5", "gemini-2.5-flash-lite", "Gemini 2.5 Flash-Lite", {
+        successor: "gemini-3.1-flash-lite",
+        releaseDate: "2025-07-22"
+      }),
+      google("gemini-flash-lite", "3.1", "gemini-3.1-flash-lite", "Gemini 3.1 Flash-Lite", {
+        status: "deprecated",
+        successor: "gemini-3.5-flash-lite",
+        releaseDate: "2026-05-07",
+        retirementDate: "2027-05-07"
+      }),
+      google("gemini-flash-lite", "3.5", "gemini-3.5-flash-lite", "Gemini 3.5 Flash-Lite", {
+        releaseDate: "2026-07-21"
+      }),
+      // xAI
+      xai("grok", "4.5", "grok-4.5", "Grok 4.5", { successor: "grok-4.6" }),
+      xai("grok", "4.6", "grok-4.6", "Grok 4.6", { successor: "grok-4.7" }),
+      xai("grok", "4.7", "grok-4.7", "Grok 4.7")
+    ];
+  }
+});
+
+// packages/core/src/model-catalog.ts
+function normalizeModelName(name) {
+  return name.trim().toLowerCase();
+}
+function ownValue(record, key) {
+  return Object.hasOwn(record, key) ? record[key] : void 0;
+}
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function stringList(value) {
+  if (!Array.isArray(value)) return void 0;
+  return value.flatMap((item) => {
+    const name = nonEmptyString(item);
+    return name ? [name] : [];
+  });
+}
+function targetNames(value) {
+  if (!isRecord4(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([key, item]) => {
+      const target = key.trim().toLowerCase();
+      const name = nonEmptyString(item);
+      return target && name ? [[target, name]] : [];
+    })
+  );
+}
+function modelStatus(value) {
+  return MODEL_STATUSES.find((status) => status === value);
+}
+function optionalFields(input2) {
+  const fields = {};
+  const provider = nonEmptyString(input2.provider);
+  if (provider) fields.provider = provider;
+  const family = nonEmptyString(input2.family);
+  if (family) fields.family = family;
+  const version = nonEmptyString(input2.version);
+  if (version) fields.version = version;
+  const displayName = nonEmptyString(input2.displayName);
+  if (displayName) fields.displayName = displayName;
+  const apiId = nonEmptyString(input2.apiId);
+  if (apiId) fields.apiId = apiId;
+  const aliases = stringList(input2.aliases);
+  if (aliases) fields.aliases = aliases;
+  const status = modelStatus(input2.status);
+  if (status) fields.status = status;
+  const successor = nonEmptyString(input2.successor);
+  if (successor) fields.successor = successor;
+  const releaseDate = nonEmptyString(input2.releaseDate);
+  if (releaseDate) fields.releaseDate = releaseDate;
+  const retirementDate = nonEmptyString(input2.retirementDate);
+  if (retirementDate) fields.retirementDate = retirementDate;
+  return fields;
+}
+function applyProfileInput(base, input2) {
+  return {
+    ...base,
+    ...optionalFields(input2),
+    // Per-target names merge so one override keeps the other targets.
+    targets: { ...base.targets, ...targetNames(input2.targets) }
+  };
+}
+function createCustomProfile(id, input2) {
+  const fields = optionalFields(input2);
+  return {
+    id,
+    provider: "custom",
+    family: id,
+    version: "",
+    displayName: id,
+    apiId: id,
+    aliases: [],
+    status: "current",
+    ...fields,
+    targets: targetNames(input2.targets)
+  };
+}
+function mergeProfiles(builtIns, overrides) {
+  if (!isRecord4(overrides)) return builtIns;
+  const pending = /* @__PURE__ */ new Map();
+  for (const [key, input2] of Object.entries(overrides)) {
+    const id = nonEmptyString(key);
+    if (id && isRecord4(input2)) {
+      pending.set(normalizeModelName(id), { id, input: input2 });
+    }
+  }
+  const merged = builtIns.map((profile) => {
+    const key = normalizeModelName(profile.id);
+    const override = pending.get(key);
+    if (!override) return profile;
+    pending.delete(key);
+    return applyProfileInput(profile, override.input);
+  });
+  for (const { id, input: input2 } of pending.values()) {
+    merged.push(createCustomProfile(id, input2));
+  }
+  return merged;
+}
+function splitVersionPart(part) {
+  let end = 0;
+  while (end < part.length) {
+    const character = part[end];
+    if (character === void 0 || character < "0" || character > "9") break;
+    end++;
+  }
+  const digits = part.slice(0, end);
+  return { number: digits.length > 0 ? Number(digits) : 0, suffix: part.slice(end) };
+}
+function compareVersionParts(leftPart, rightPart) {
+  const left = splitVersionPart(leftPart);
+  const right = splitVersionPart(rightPart);
+  if (left.number !== right.number) return left.number - right.number;
+  const leftSuffix = left.suffix;
+  const rightSuffix = right.suffix;
+  if (leftSuffix === rightSuffix) return 0;
+  if (leftSuffix === "") return 1;
+  if (rightSuffix === "") return -1;
+  return leftSuffix.localeCompare(rightSuffix);
+}
+function compareModelVersions(a, b) {
+  const left = a.split(".");
+  const right = b.split(".");
+  for (let index = 0; index < Math.max(left.length, right.length); index++) {
+    const diff = compareVersionParts(left[index] ?? "0", right[index] ?? "0");
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+function compareModelReleases(a, b) {
+  return compareModelVersions(a.version, b.version) || (a.releaseDate ?? "").localeCompare(b.releaseDate ?? "");
+}
+function createModelCatalog(config, builtIns = MODEL_PROFILES) {
+  const profiles = mergeProfiles(builtIns, config?.profiles);
+  const byId = /* @__PURE__ */ new Map();
+  const byName = /* @__PURE__ */ new Map();
+  for (const profile of profiles) {
+    byId.set(normalizeModelName(profile.id), profile);
+    for (const name of [profile.apiId, profile.displayName, ...profile.aliases]) {
+      byName.set(normalizeModelName(name), profile);
+    }
+  }
+  const getProfile = (id) => byId.get(normalizeModelName(id));
+  const getLatest = (family) => {
+    const members = profiles.filter((profile) => profile.family === family);
+    const served = members.filter((profile) => profile.status !== "retired");
+    const pool = served.length > 0 ? served : members;
+    return pool.reduce(
+      (newest, profile) => newest === void 0 || compareModelReleases(profile, newest) > 0 ? profile : newest,
+      void 0
+    );
+  };
+  const resolve45 = (reference) => {
+    const name = normalizeModelName(reference);
+    if (!name) return void 0;
+    if (name === INHERIT_MODEL) return { kind: "inherit" };
+    const exact = byId.get(name);
+    if (exact) return { kind: "profile", profile: exact };
+    const family = ownValue(FLOATING_MODEL_ALIASES, name);
+    const latest = family ? getLatest(family) : void 0;
+    if (latest) return { kind: "floating", alias: name, profile: latest };
+    const named = byName.get(name);
+    return named ? { kind: "profile", profile: named } : void 0;
+  };
+  const getReplacement = (id) => {
+    const visited = /* @__PURE__ */ new Set();
+    let current = getProfile(id);
+    while (current?.successor && !visited.has(current.id)) {
+      visited.add(current.id);
+      const next = getProfile(current.successor);
+      if (!next) break;
+      if (next.status === "current") return next;
+      current = next;
+    }
+    return void 0;
+  };
+  return { profiles, getProfile, getLatest, resolve: resolve45, getReplacement };
+}
+function getModelCatalog(config) {
+  if (!config?.profiles) {
+    defaultCatalog ??= createModelCatalog();
+    return defaultCatalog;
+  }
+  let catalog = catalogCache.get(config);
+  if (!catalog) {
+    catalog = createModelCatalog(config);
+    catalogCache.set(config, catalog);
+  }
+  return catalog;
+}
+function duplicateIdIssues(profiles) {
+  const issues = [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const profile of profiles) {
+    const id = normalizeModelName(profile.id);
+    if (ids.has(id)) issues.push(`duplicate model id "${profile.id}"`);
+    ids.add(id);
+  }
+  return issues;
+}
+function nameIssues(profile, owners) {
+  const issues = [];
+  const names = new Set(
+    [profile.id, profile.apiId, profile.displayName, ...profile.aliases].map(normalizeModelName)
+  );
+  for (const name of names) {
+    const owner = owners.get(name);
+    if (Object.hasOwn(FLOATING_MODEL_ALIASES, name) || name === INHERIT_MODEL) {
+      issues.push(`model "${profile.id}" uses reserved name "${name}"`);
+    } else if (owner === void 0) {
+      owners.set(name, profile.id);
+    } else if (owner !== profile.id) {
+      issues.push(`model name "${name}" is used by "${owner}" and "${profile.id}"`);
+    }
+  }
+  return issues;
+}
+function successorIssues(profile, ids) {
+  if (profile.successor === void 0) return [];
+  const successor = normalizeModelName(profile.successor);
+  if (successor === normalizeModelName(profile.id)) {
+    return [`model "${profile.id}" names itself as successor`];
+  }
+  if (ids.has(successor)) return [];
+  return [`model "${profile.id}" names unknown successor "${profile.successor}"`];
+}
+function dateIssues(profile) {
+  const dates = [
+    ["release date", profile.releaseDate],
+    ["retirement date", profile.retirementDate]
+  ];
+  return dates.flatMap(
+    ([label, date]) => date === void 0 || DATE_PATTERN.test(date) ? [] : [`model "${profile.id}" has invalid ${label} "${date}", expected YYYY-MM-DD`]
+  );
+}
+function targetIssues(profile) {
+  const writers = Object.keys(MODEL_TARGET_SCHEMES).join(", ");
+  return Object.keys(profile.targets).filter((target) => !getModelTargetScheme(target)).map(
+    (target) => `model "${profile.id}" sets a name for "${target}", which is not a target that writes model names (${writers})`
+  );
+}
+function successorLoopIssues(profiles) {
+  const byId = new Map(profiles.map((profile) => [normalizeModelName(profile.id), profile]));
+  const successorOf = (profile) => profile.successor ? byId.get(normalizeModelName(profile.successor)) : void 0;
+  const issues = [];
+  for (const profile of profiles) {
+    const visited = /* @__PURE__ */ new Set([normalizeModelName(profile.id)]);
+    let next = successorOf(profile);
+    while (next) {
+      const id = normalizeModelName(next.id);
+      if (visited.has(id)) {
+        issues.push(`successor chain of "${profile.id}" loops`);
+        break;
+      }
+      visited.add(id);
+      next = successorOf(next);
+    }
+  }
+  return issues;
+}
+function floatingAliasIssues(profiles) {
+  return Object.entries(FLOATING_MODEL_ALIASES).filter(([, family]) => !profiles.some((profile) => profile.family === family)).map(([alias, family]) => `floating alias "${alias}" names unknown family "${family}"`);
+}
+function validateModelCatalog(profiles = MODEL_PROFILES) {
+  const ids = new Set(profiles.map((profile) => normalizeModelName(profile.id)));
+  const owners = /* @__PURE__ */ new Map();
+  const profileIssues = profiles.flatMap((profile) => [
+    ...nameIssues(profile, owners),
+    ...successorIssues(profile, ids),
+    ...dateIssues(profile),
+    ...targetIssues(profile)
+  ]);
+  return [
+    ...duplicateIdIssues(profiles),
+    ...profileIssues,
+    ...successorLoopIssues(profiles),
+    ...floatingAliasIssues(profiles)
+  ];
+}
+function resolveModelSet(entries, catalog) {
+  const profileIds = /* @__PURE__ */ new Set();
+  const floatingAliases = /* @__PURE__ */ new Set();
+  const unknown = [];
+  for (const entry of entries) {
+    const resolution = catalog.resolve(entry);
+    if (!resolution) {
+      unknown.push(entry);
+      continue;
+    }
+    if (resolution.kind === "inherit") continue;
+    if (resolution.kind === "floating") floatingAliases.add(resolution.alias);
+    profileIds.add(resolution.profile.id);
+  }
+  return { profileIds, floatingAliases, unknown };
+}
+function isInModelSet(resolution, set) {
+  if (resolution.kind === "inherit") return true;
+  if (resolution.kind === "floating" && set.floatingAliases.has(resolution.alias)) return true;
+  return set.profileIds.has(resolution.profile.id);
+}
+function getModelTargetScheme(target) {
+  return Object.hasOwn(MODEL_TARGET_SCHEMES, target) ? MODEL_TARGET_SCHEMES[target] : void 0;
+}
+function profileName(value, profile) {
+  return UNSAFE_MODEL_NAME.test(value) ? { issue: "invalid-name", profile } : { value, profile };
+}
+function mapProfileToTarget(resolution, target, scheme) {
+  const { profile } = resolution;
+  const explicit = ownValue(profile.targets, target);
+  if (explicit !== void 0) return profileName(explicit, profile);
+  if (resolution.kind === "floating" && scheme.keepsFloatingAliases) {
+    return { value: resolution.alias, profile };
+  }
+  if (scheme.providers && !scheme.providers.includes(profile.provider)) {
+    return { issue: "unsupported-provider", profile };
+  }
+  return profileName(profile[scheme.naming], profile);
+}
+function mapModelToTarget(reference, target, catalog = getModelCatalog()) {
+  const written = reference.trim();
+  if (!written) return {};
+  if (UNSAFE_MODEL_NAME.test(written)) return { issue: "invalid-name" };
+  const scheme = getModelTargetScheme(target);
+  if (!scheme) return { value: written };
+  const resolution = catalog.resolve(written);
+  if (!resolution) {
+    const native = ownValue(scheme.nativeValues ?? {}, normalizeModelName(written));
+    return native !== void 0 ? { value: native } : { value: written, issue: "unknown-model" };
+  }
+  if (resolution.kind === "inherit") {
+    return scheme.writesInherit ? { value: INHERIT_MODEL } : {};
+  }
+  return mapProfileToTarget(resolution, target, scheme);
+}
+var FLOATING_MODEL_ALIASES, INHERIT_MODEL, MODEL_STATUSES, defaultCatalog, catalogCache, DATE_PATTERN, CLAUDE_MODEL_SCHEME, MODEL_TARGET_SCHEMES, UNSAFE_MODEL_NAME;
+var init_model_catalog = __esm({
+  "packages/core/src/model-catalog.ts"() {
+    "use strict";
+    init_model_profiles();
+    FLOATING_MODEL_ALIASES = {
+      opus: "claude-opus",
+      sonnet: "claude-sonnet",
+      haiku: "claude-haiku",
+      fable: "claude-fable"
+    };
+    INHERIT_MODEL = "inherit";
+    MODEL_STATUSES = ["current", "legacy", "deprecated", "retired"];
+    catalogCache = /* @__PURE__ */ new WeakMap();
+    DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+    CLAUDE_MODEL_SCHEME = {
+      providers: ["anthropic"],
+      naming: "apiId",
+      keepsFloatingAliases: true,
+      writesInherit: true
+    };
+    MODEL_TARGET_SCHEMES = {
+      claude: CLAUDE_MODEL_SCHEME,
+      // Grok delegates agent files to the Claude formatter.
+      grok: CLAUDE_MODEL_SCHEME,
+      github: {
+        naming: "displayName",
+        keepsFloatingAliases: false,
+        writesInherit: false,
+        nativeValues: { auto: "Auto" }
+      },
+      factory: {
+        naming: "apiId",
+        keepsFloatingAliases: false,
+        writesInherit: true
+      },
+      codex: {
+        providers: ["openai"],
+        naming: "apiId",
+        keepsFloatingAliases: false,
+        writesInherit: false
+      },
+      // Cursor has its own model ids and documents them without snapshot dates.
+      cursor: {
+        naming: "id",
+        keepsFloatingAliases: false,
+        writesInherit: true
+      }
+    };
+    UNSAFE_MODEL_NAME = /[\p{Cc}\u2028\u2029]/u;
+  }
+});
+
+// packages/core/src/model-drift.ts
+var init_model_drift = __esm({
+  "packages/core/src/model-drift.ts"() {
+    "use strict";
+    init_model_catalog();
+  }
+});
+
 // packages/core/src/git-timeout.ts
 function isGitTimeoutError(error) {
   const errorWithCode = error;
@@ -7727,7 +8380,7 @@ function normalizeManagedPaths(output) {
     ...files.length > 0 ? { files } : {}
   };
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null;
 }
 function valuesEqual(left, right) {
@@ -7739,7 +8392,7 @@ function valuesEqual(left, right) {
     }
     return left.every((value, index) => valuesEqual(value, right[index]));
   }
-  if (!isRecord4(left) || !isRecord4(right)) return false;
+  if (!isRecord5(left) || !isRecord5(right)) return false;
   const leftKeys = Object.keys(left).sort();
   const rightKeys = Object.keys(right).sort();
   if (leftKeys.length !== rightKeys.length) return false;
@@ -7985,6 +8638,9 @@ var init_src = __esm({
     init_target_catalog();
     init_target_capabilities();
     init_agent_capabilities();
+    init_model_catalog();
+    init_model_drift();
+    init_model_profiles();
     init_hook_capabilities();
     init_git_timeout();
     init_structured_output();
@@ -8044,7 +8700,7 @@ var PROMPTSCRIPT_SKILL_CONTENT;
 var init_promptscript_skill = __esm({
   "packages/cli/src/generated/promptscript-skill.ts"() {
     "use strict";
-    PROMPTSCRIPT_SKILL_CONTENT = '---\nname: promptscript\ndescription: >-\n  PromptScript language expert for reading, writing, modifying, and\n  troubleshooting .prs files. Use when working with PromptScript syntax,\n  creating or editing .prs files, adding blocks like @identity, @standards,\n  @restrictions, @shortcuts, @skills, or @agents, configuring\n  promptscript.yaml, resolving compilation errors, understanding inheritance\n  (@inherit), composition (@use, @extend, @override), contextual @header\n  metadata, or migrating AI instructions\n  to PromptScript. Also use when asked about the 50 built-in compilation\n  targets, including GitHub Copilot, Claude Code, Cursor, Antigravity,\n  Factory AI, and AGENTS.md-based platforms.\nlicense: MIT\nmetadata:\n  author: PromptScript\n  homepage: https://getpromptscript.dev\ncompatibility:\n  - claude-code\n  - github-copilot\n  - cursor\n  - factory-ai\n  - gemini-cli\n  - opencode\n  - windsurf\n  - cline\n  - roo\n  - codex\n  - continue\n  - augment\n  - goose\n  - kilo\n  - amp\n  - trae\n  - junie\n  - kiro-cli\nallowed-tools:\n  - Read\n  - Write\n  - Glob\n  - Grep\n  - Bash\nuser-invocable: true\n---\n\n# PromptScript Language Guide\n\nPromptScript is a domain-specific language that compiles `.prs` files into native instruction formats for AI coding assistants (GitHub Copilot, Claude Code, Cursor, Antigravity, Factory AI, OpenCode, Gemini CLI). One source of truth, multiple outputs.\n\n## File Structure\n\nA `.prs` file contains ordered declarations. Syntax `1.5.0` applies `@inherit`,\n`@use`, local blocks, `@extend`, and `@override` in source order. Put `@meta`\nfirst.\n\n```\n# Comments start with #\n\n@meta { ... }           # Required metadata\n@inherit @path          # Single inheritance (optional)\n@use @path [as alias]   # Imports/mixins (optional, multiple)\n\n@identity { ... }       # AI persona\n@context { ... }        # Project context\n@standards { ... }      # Coding conventions\n@restrictions { ... }   # Hard rules\n@shortcuts { ... }      # Command aliases\n@knowledge { ... }      # Reference documentation\n@skills { ... }         # Reusable skill definitions\n@agents { ... }         # Subagent definitions\n@workflows { ... }      # Repeatable agent procedures\n@examples { ... }       # Few-shot input/output examples (syntax 1.2.0+)\n@params { ... }         # Template parameters\n@guards { ... }         # File globs and priorities\n@hooks { ... }          # Portable lifecycle hooks (syntax 1.4.0+)\n@mcpServers { ... }     # MCP server configurations (syntax 1.4.0+)\n@plugins { ... }        # Capability bundles (syntax 1.4.0+)\n@local { ... }          # Private config (not committed)\n@extend path { ... }    # Modify imported blocks\n@override path { ... }  # Replace one complete existing target (syntax 1.5.0+)\n@custom-name { ... }    # Arbitrary named blocks\n```\n\nContextual `@header` entries appear inside supported owner blocks, not at the\ntop level.\n\n## Content Types\n\nPromptScript has four canonical content shapes inside blocks:\n\n### Text Content\n\nUse triple quotes (three double-quote characters) to wrap multiline text.\nText is automatically dedented - leading whitespace from source indentation is stripped.\nUse for prose, markdown, or freeform content.\n\nExample: `@identity` with a text block describing an AI persona starting with "You are..."\n\n### Object Content (key-value pairs)\n\n```\n@context {\n  project: "My App"\n  team: "Frontend"\n  monorepo: {\n    tool: "Nx"\n    packageManager: "pnpm"\n  }\n}\n```\n\nValues can be strings (quoted or unquoted), numbers, booleans, nested objects, or arrays.\n\n### Array Content\n\n```\n@standards {\n  code: [\n    "Use strict TypeScript",\n    "Named exports only"\n  ]\n}\n\n@restrictions {\n  - "Never use any type"\n  - "Never commit secrets"\n}\n```\n\n### Mixed Content\n\nBlocks can contain both object properties and text in the same block.\nPlace the triple-quoted text block alongside key-value pairs.\n\n## Block Reference\n\n### @meta (required)\n\n```\n@meta {\n  id: "project-id"        # Required: unique identifier\n  syntax: "1.0.0"         # Required: syntax version (semver)\n  org: "Company Name"     # Optional\n  team: "Frontend"        # Optional\n  tags: [react, ts]       # Optional\n  params: {               # Optional: template parameters\n    projectName: string\n    port: number = 3000\n    debug?: boolean\n    framework: enum("react", "vue") = "react"\n  }\n}\n```\n\n### @identity\n\nDefines AI persona. Start with "You are..." for consistent output across all formatters.\nContains a triple-quoted text block with the persona description.\n\n### @context\n\nProject context with structured properties (project, team, languages, runtime)\nplus optional triple-quoted text for architecture details, diagrams, etc.\n\n### @standards\n\nCategory-based conventions. Any category name is valid:\n\n```\n@standards {\n  typescript: ["Strict mode", "No any type"]\n  naming: ["Files: kebab-case.ts", "Classes: PascalCase"]\n  git: {\n    format: "Conventional Commits"\n    types: [feat, fix, docs, refactor, test, chore]\n  }\n}\n```\n\nCategory names are arbitrary. `@standards` can also contain free-form text:\n\n```\n@standards {\n  """\n  ## Formatting\n  Preserve heading structure and use four-space indentation.\n\n  ## Testing\n  Add regression coverage for every behavior change.\n  """\n  typescript: ["Strict mode", "Named exports only"]\n  git: {\n    format: "Conventional Commits"\n  }\n}\n```\n\nFree-form text is dedented and rendered with its Markdown heading structure. Factory\nmonolith output nests it under `Conventions & Patterns`; split Factory rules adjust\nheading levels relative to the generated section. Custom structured categories remain\navailable to formatters that support them.\n\n### @restrictions\n\nHard rules as a list of dash-prefixed strings:\n\n```\n@restrictions {\n  - "Never expose API keys"\n  - "Never commit secrets to version control"\n  - "Always validate user input"\n}\n```\n\n### @shortcuts\n\nSimple strings appear as documentation. Objects with `prompt: true` generate\nexecutable prompt/command files for GitHub Copilot and Cursor:\n\n```\n@shortcuts {\n  "/review": "Review code for quality"\n  "/test": {\n    prompt: true\n    description: "Write unit tests"\n    content: (triple-quoted text with instructions)\n  }\n}\n```\n\n> `@commands` is a backwards-compatible alias for `@shortcuts` \u2014 prefer `@shortcuts` in new files.\n\n### @skills\n\nReusable skill definitions with metadata:\n\n```\n@skills {\n  commit: {\n    description: "Create git commits"\n    trigger: "commit, git commit"\n    disableModelInvocation: true\n    userInvocable: true\n    allowedTools: ["Bash", "Read"]\n    content: (triple-quoted text with skill instructions)\n  }\n}\n```\n\nProperties: description (required), content (required), trigger, disableModelInvocation,\nuserInvocable, allowedTools, context ("fork" or "inherit"), agent, requires, references, inputs, outputs.\n\nThe `references` property attaches external files to the skill\'s context:\n\n```\n@skills {\n  architecture-review: {\n    description: "Review architecture decisions"\n    references: [\n      ./references/architecture.md\n      ./references/modules.md\n    ]\n    content: (triple-quoted text)\n  }\n}\n```\n\nAllowed file types: `.md`, `.json`, `.yaml`, `.yml`, `.txt`, `.csv`. Paths are resolved relative\nto the `.prs` file. Formatters emit referenced files alongside SKILL.md in the output directory.\n\n### Parameterized Skills\n\nSkills in `.promptscript/skills/<name>/SKILL.md` support template parameters via\nYAML frontmatter. Define `params` in frontmatter and use `{{variable}}` in content:\n\n```yaml\n---\nname: review\ndescription: \'Review {{language}} code for {{standard}}\'\nparams:\n  language:\n    type: string\n  standard:\n    type: string\n    default: \'best practices\'\nreferences:\n  - references/architecture.md\n---\nReview the code using {{language}} conventions following {{standard}}.\n```\n\nThe `references` field in SKILL.md frontmatter lists files to attach to the skill\'s context.\nPaths are relative to the SKILL.md file.\n\nImported SKILL.md frontmatter is bounded: 256 KiB per document, 10,000 YAML nodes, 32 nesting\nlevels, 2,000 entries per mapping or sequence, and 64 KiB per string value. Documents over any\nlimit are rejected before their YAML values are converted.\n\nPass values in `@skills` block:\n\n```\n@skills {\n  review: {\n    description: "Review code"\n    language: "typescript"\n    standard: "strict mode"\n  }\n}\n```\n\nNon-reserved properties (anything other than description, content, trigger,\nuserInvocable, allowedTools, disableModelInvocation, context, agent, requires,\ninputs, outputs) are treated as skill parameter arguments.\n\n### Skill Dependencies\n\nSkills can declare dependencies on other skills via `requires`:\n\n```\n@skills {\n  deploy: {\n    description: "Deploy service"\n    requires: ["lint-check", "test-suite"]\n    content: (triple-quoted text)\n  }\n}\n```\n\nThe validator (PS016) checks that required skills exist, detects self-references,\nand catches circular dependency chains.\n\n### Skill Contracts (Inputs/Outputs)\n\nSkills can declare typed inputs and outputs in SKILL.md frontmatter:\n\n```yaml\n---\nname: security-scan\ndescription: \'Scan for vulnerabilities\'\ninputs:\n  files:\n    description: \'Files to scan\'\n    type: string\n  severity:\n    description: \'Minimum severity\'\n    type: enum\n    options: [low, medium, high]\n    default: medium\noutputs:\n  report:\n    description: \'Scan report\'\n    type: string\n  passed:\n    description: \'Whether scan passed\'\n    type: boolean\n---\n```\n\nField types: `string`, `number`, `boolean`, `enum` (with `options` list).\nThe validator (PS017) checks field types, ensures enum fields have options,\nand warns if param names collide with input names.\n\n### Shared Resources\n\nSkills in a folder can share common resources via `.promptscript/shared/`:\n\n```\n.promptscript/\n  shared/\n    templates.md         # Shared across all skills\n    style-guide.md\n  skills/\n    review/\n      SKILL.md           # Gets @shared/templates.md, @shared/style-guide.md\n    deploy/\n      SKILL.md           # Also gets shared resources\n```\n\nFiles in `shared/` are automatically included in every skill with `@shared/` prefix.\n\n### @agents\n\nCustom subagent definitions. Compiles to `.claude/agents/` for Claude Code,\n`.github/agents/` for GitHub Copilot, `.factory/droids/` for Factory AI, etc.\n\n```\n@agents {\n  code-reviewer: {\n    description: "Reviews code quality"\n    tools: ["Read", "Grep", "Glob", "Bash"]\n    model: "sonnet"\n    permissionMode: "default"\n    content: (triple-quoted text with agent instructions)\n  }\n}\n```\n\nImported agent definitions are qualified by an aliased `@use`:\n\n```\n@use ./frontend-team as frontend\n@use ./backend-team as backend\n```\n\nIf both imports define `reviewer`, the resolved names are `frontend.reviewer` and\n`backend.reviewer`. Unique unaliased imports keep their original names. Conflicting unaliased\ndefinitions stop compilation with source and import diagnostics instead of silently overwriting\none another. Native targets map dots to hyphens, so `frontend.reviewer` becomes\n`frontend-reviewer`.\n\nSupports mixed models per agent: `specModel` sets a different model for\nSpecification/planning mode (GitHub, Factory), `specReasoningEffort` sets reasoning\neffort for the spec model (Factory only, values: "low", "medium", "high").\n\nFactory AI droids support additional properties: `model` (any model ID or "inherit"),\n`reasoningEffort` ("low", "medium", "high"), and `tools` (category name like "read-only"\nor array of tool IDs).\n\n### @workflows\n\nRepeatable multi-step agent procedures. Requires syntax `1.1.0`.\n\n```\n@workflows {\n  release: {\n    description: "Prepare a validated release"\n    content: """\n      1. Run formatting, linting, type checks, and tests.\n      2. Validate compiled output.\n      3. Stop before publishing and request approval.\n    """\n  }\n}\n```\n\nTargets with native workflow discovery emit dedicated workflow files. Other targets\nretain workflow instructions in their main output when supported.\n\n### @examples\n\nStructured few-shot examples for AI assistants (requires syntax `1.2.0`):\n\n```\n@meta {\n  id: "commit-style"\n  syntax: "1.2.0"\n}\n\n@examples {\n  feat-commit: {\n    description: "Feature commit with scope"\n    input: "Added user authentication with JWT tokens"\n    output: "feat(auth): add JWT-based user authentication"\n  }\n}\n```\n\nEach entry is a named example with `input` and `output` (both required),\nplus optional `description`. Multi-line content uses triple-quoted strings.\n\nExamples can also be attached to skills via the `examples` property:\n\n```\n@skills {\n  commit: {\n    description: "Create conventional commits"\n    examples: {\n      basic: {\n        input: "Added dark mode toggle"\n        output: "feat(settings): add dark mode toggle"\n      }\n    }\n    content: (triple-quoted text)\n  }\n}\n```\n\n### @knowledge\n\nReference documentation as triple-quoted text. Used for command references,\nAPI docs, and other material that should appear in the output.\n\n### @params\n\nTemplate parameter definitions with types: string, number, boolean, enum("a", "b").\nOptional parameters use `?` suffix. Defaults use `= value`.\n\n### @guards\n\nFile glob patterns and priority rules for path-specific instructions.\n\n### @hooks\n\nPortable lifecycle hooks. Requires syntax `1.4.0`. Each hook needs exactly one of\n`command` or `script`.\n\n```\n@hooks {\n  validate-types: {\n    event: "post-tool-use"\n    matcher: "Edit|Write"\n    script: {\n      path: ".promptscript/scripts/validate.py"\n      interpreter: "python3"\n      args: ["--strict"]\n    }\n    cwd: "project"\n    timeoutMs: 120000\n    statusMessage: "Checking TypeScript"\n    continueOnFailure: false\n    enabled: true\n    targets: {\n      factory: { matcher: "Execute" }\n      vscode: { matcher: "run_in_terminal" }\n      github: { enabled: false }\n    }\n  }\n}\n```\n\nPortable events:\n\n| Event                  | Meaning                   |\n| ---------------------- | ------------------------- |\n| `pre-terminal-command` | Before a terminal command |\n| `pre-tool-use`         | Before a tool invocation  |\n| `post-tool-use`        | After a tool invocation   |\n| `session-start`        | Agent session start       |\n| `setup`                | Session setup             |\n| `subagent-start`       | Subagent start            |\n| `notification`         | Agent notification        |\n| `stop`                 | Agent stop                |\n\n`command` is a non-empty string array. Shell interpolation (`$()`, backticks,\n`${...}`) is forbidden. `script` requires:\n\n- `path` under `.promptscript/scripts/`, using forward slashes.\n- Existing regular file at compile time.\n- No traversal, absolute path, invalid segment, or symlink escape.\n- Explicit interpreter: `python3`, `python`, `node`, `deno`, `bun`, `ruby`, `php`,\n  `perl`, `bash`, `sh`, `zsh`, `pwsh`, or `powershell`.\n- Optional `args` string array; each argument remains one argument.\n\n`cwd: "project"` runs from project root. Other values are portable forward-slash\npaths relative to project root. Hook config file location does not set command cwd.\nEnvironment-root and Git-root wrappers exit before script or command execution when\nthe required root is unavailable. Native-cwd and workspace-cwd targets retain host\ncwd fields and report `PS4002` when PromptScript cannot verify that cwd.\n`timeoutMs` range is 100-600000. `matcher` uses target-native tool names, so a\nmatcher valid for one target may match nothing on another.\n\n`pre-terminal-command` supplies native defaults: Factory `Execute`, Claude and\nCodex `Bash`, Windsurf `pre_run_command`, Cursor `run_terminal_cmd`, Gemini\n`run_shell_command`, and VS Code `run_in_terminal`. Override a native tool name\nwith `targets.<name>.matcher`. Cursor, Gemini, and VS Code report best-effort\n`PS4002` warnings. GitHub and Grok omit the event with `PS4002`.\n\nTarget overrides may change `event`, `matcher`, `timeoutMs`, `statusMessage`,\n`continueOnFailure`, `enabled`, or `cwd`. Native hook files are emitted only in\ntarget modes that support additional files:\n\n| Target         | Hook output                                                            | Mode                |\n| -------------- | ---------------------------------------------------------------------- | ------------------- |\n| Claude Code    | `.claude/settings.json`                                                | `full`              |\n| Factory AI     | `.factory/hooks.json`                                                  | `multifile`, `full` |\n| GitHub Copilot | `.github/hooks/promptscript.json`                                      | `multifile`, `full` |\n| Cursor         | `.cursor/hooks.json`                                                   | `full`              |\n| Codex          | `.codex/hooks.json`                                                    | `multifile`, `full` |\n| Gemini CLI     | `.gemini/settings.json`                                                | `multifile`, `full` |\n| Windsurf       | `.windsurf/hooks.json`                                                 | `multifile`, `full` |\n| Grok Build     | `.grok/hooks/promptscript.json`                                        | `full`              |\n| OpenCode       | `.opencode/plugins/promptscript.ts` (generated plugin)                 | `multifile`, `full` |\n| VS Code Agent  | `.github/hooks/promptscript-vscode.json` when `vscode` override exists | target-specific     |\n\nOpenCode starts generated hook commands asynchronously. It enforces authored\ntimeouts or a 30-second default, then escalates from `SIGTERM` to `SIGKILL`.\nPayloads are bounded by UTF-8 byte length. OpenCode tool hooks expose tool\narguments, session ID, and call ID, but no model or agent context; compilation\nreports that limitation with `PS4002`.\n\nSimple mode and targets without native project hooks report `PS4002` instead of\nsilently dropping hooks. Use `prs compile --watch` as fallback. Plugin-only and\nagent-scoped integrations are not emitted as universal project hooks.\n\nEach generated command carries a PromptScript ownership marker. CLI cleanup removes\nonly marked entries and preserves user hooks/settings. Removing `@hooks` removes a\nfully owned generated hook file and prunes directories left empty. `prs hooks install factory`\nmigrates unambiguous legacy hooks from `.factory/settings.json`; ambiguous\nentries remain for manual review.\n\nFactory compilation performs the same migration when `.factory/hooks.json` is\nabsent. Use `prs compile --dry-run` to preview the changes or\n`--no-migrate-factory-hooks` to keep warning-only behavior. Unknown events,\nmalformed entries, and mixed ownership abort without a partial migration.\n\n`@hooks` compilation is separate from `prs hooks install`. The latter installs\nauto-compilation and generated-output protection for supported AI tools. Copilot VS\nCode Agent hooks use `promptscript-vscode.json`; GitHub Copilot repository hooks use\n`promptscript.json`.\n\n### @mcpServers\n\nProject-local Model Context Protocol servers. Requires syntax `1.4.0`.\n\n```\n@mcpServers {\n  issue-tracker: {\n    transport: "stdio"\n    command: ["node", "./tools/issues.mjs"]\n    env: { LOG_LEVEL: "info" }\n  }\n}\n```\n\nUse `stdio` with `command`, or `http`/`sse` with `url`. Keep credentials out of\n`.prs` files and provide them through target-native secret management.\n\n### @plugins\n\nPortable capability bundles. Requires syntax `1.4.0`.\n\n```\n@plugins {\n  security-suite: {\n    description: "Security review tooling"\n    version: "1.0.0"\n    skills: ["security-review"]\n    hooks: ["validate-types"]\n    mcpServers: ["issue-tracker"]\n  }\n}\n```\n\n### @local\n\nPrivate local configuration. Not included in compiled output or committed to git.\n\n## Inheritance and Composition\n\n### @inherit (single, linear)\n\nOne per file. Child blocks merge on top of parent:\n\n```\n@inherit @company/frontend-team\n@inherit ./parent\n@inherit @stacks/react-app(projectName: "my-app", port: 3000)\n```\n\n### @use (multiple, mixins)\n\nImport and merge fragments:\n\n```\n@use @core/security\n@use @core/quality\n@use ./local-config\n@use @core/typescript as ts   # alias enables @extend access\n```\n\n#### URL imports (Go-module style)\n\nImport directly from any Git repository by host path - no alias required:\n\n```\n@use github.com/acme/shared-standards/@fragments/security\n@use gitlab.com/myorg/prompts/@stacks/python\n```\n\nVersion pinning with `@`:\n\n```\n@use github.com/acme/shared-standards/@org/base@1.2.0    # exact version\n@use github.com/acme/shared-standards/@org/base@^1.0.0   # semver range\n@use github.com/acme/shared-standards/@org/base@main     # branch\n```\n\n#### Registry aliases\n\nShort names for Git repository URLs, configured in `promptscript.yaml`:\n\n```yaml\nregistries:\n  company:\n    url: github.com/acme/promptscript-registry\n```\n\nThen use the alias as scope prefix:\n\n```\n@use @company/security\n@inherit @company/base-config\n```\n\nMerge rules:\n\n- Text: concatenated with deduplication\n- Objects: deep merged (imported source wins same-shape conflicts)\n- Arrays: unique concatenation\n- Shape mismatch: existing target body wins\n\nUnder syntax `1.5.0`, later local blocks, `@extend`, and `@override`\noperations apply to the accumulated import result in declaration order.\n\n### Block Filtering\n\nControl which blocks are imported using the reserved `only` and `exclude` parameters:\n\n```\n@use ./shared-config(only: ["skills", "context"])\n@use ./shared-config(exclude: ["knowledge"])\n@use ./shared-config(exclude: ["knowledge"], mode: "strict")\n```\n\nRules:\n\n- `only` and `exclude` are mutually exclusive \u2014 using both is a validation error (PS021)\n- Values are block type names: `identity`, `context`, `standards`, `knowledge`, `skills`, `shortcuts`, `agents`, etc.\n- Block filtering does not apply to `@inherit` directives\n\n### Markdown Imports\n\nImport skills directly from `.md` files (v1.8+). No external tools needed:\n\n```\n@use ./skills/frontend-design.md\n@use ./shared/commit.md as commit\n@use github.com/anthropics/skills/commit@1.0.0\n@use github.com/repo/skills/gitnexus         # directory \u2192 SKILL.md\n```\n\nContent detection: PromptScript blocks in `.md` are parsed as a `.prs` fragment;\nYAML frontmatter with `name`/`description` is loaded as a skill definition;\notherwise content is treated as free-form knowledge.\n\nCLI management:\n\n```\nprs skills add github.com/anthropics/skills/commit@1.0.0\nprs skills remove commit\nprs skills list\nprs skills update\n```\n\n### @extend (modify existing or imported blocks)\n\nUse a direct path for inherited or local blocks:\n\n```\n@extend standards.testing {\n  coverage: 95\n}\n```\n\nUse an alias when targeting a specific imported block:\n\n```\n@use @core/typescript as ts\n\n@extend ts.standards {\n  testing: { coverage: 95 }\n}\n```\n\n#### Replacing regular block fields\n\nSyntax `1.3.0` supports explicit replacement of complete regular block field values:\n\n```\n@meta { id: "project" syntax: "1.3.0" }\n\n@inherit ./company-base\n\n@extend standards {\n  testing!: ["Use Vitest"]\n  linting: ["Use ESLint"]\n}\n```\n\n`testing!` replaces the inherited value. Fields without `!` keep normal merge behavior.\nReplacement works after `@inherit` and `@use`, including aliases and nested target paths.\nA missing field is set. The modifier is rejected for `@skills`, which retain their dedicated\nmerge and sealing semantics.\n\n#### Replacing complete targets with @override\n\nSyntax `1.5.0` adds atomic replacement for an existing block or nested value:\n\n```\n@meta { id: "project" syntax: "1.5.0" }\n\n@standards {\n  testing: ["Use Jest", "Use Mocha"]\n}\n\n@override standards.testing {\n  ["Use Vitest"]\n}\n```\n\n`@override` requires the complete target path to exist, applies in declaration\norder, and cannot bypass sealed skill properties. Later `@extend` declarations\nmerge into the replacement. Use `@extend` for additive changes, `field!` for\ncompatibility replacement of one direct regular field, and `@override` for\nintentional complete replacement.\n\n#### Skill-aware @extend semantics\n\nWhen extending a skill definition via `@extend`, individual skill properties follow specific merge\nstrategies rather than the generic block merge rules:\n\n| Strategy          | Properties                                                                                                  |\n| ----------------- | ----------------------------------------------------------------------------------------------------------- |\n| **Replace**       | content, description, trigger, userInvocable, allowedTools, disableModelInvocation, context, agent, license |\n| **Append**        | references, examples, requires                                                                              |\n| **Shallow merge** | params, inputs, outputs                                                                                     |\n\nExample \u2014 extending a base skill to add references and override content:\n\n```\n@use @company/skills as skills\n\n@extend skills.code-review {\n  content: (triple-quoted text with overridden instructions)\n  references: [\n    ./extra-context.md\n  ]\n}\n```\n\nThe `references` array from the base skill and the overlay are combined (append). The `content`\nfield from the overlay replaces the base (replace).\n\n#### Reference negation\n\nUse `!` prefix in `@extend` to remove entries from a lower layer\'s append-strategy arrays:\n\n```\n@extend skills.code-review {\n  references: [\n    "!references/deprecated.md"\n    "references/replacement.md"\n  ]\n}\n```\n\nPath matching is normalized (`"!./foo.md"` matches `"foo.md"`). Only works in `@extend` blocks\non `references` and `requires`. Validator PS028 warns about `!` in base definitions.\n\n#### Overlay consistency warnings\n\nThe resolver emits warnings during compile when an overlay drifts from its base. Always shown\n(not gated by `--verbose`):\n\n- **Orphaned extend** \u2014 `@extend target "X" not found \u2014 overlay will be ignored.` Triggered when\n  the targeted block doesn\'t exist (base removed or renamed).\n- **Stale skill target** \u2014 `@extend creates new skill "X" \u2014 base does not define it.` Triggered\n  when an `@extend` inside `@skills` would create a new skill instead of extending an existing one.\n- **Negation orphan** \u2014 `Negation "!path" did not match any base entry \u2014 it may be stale.`\n  Triggered when a `!entry` in references/requires doesn\'t match anything in the base.\n\nThese come from the resolver, not the validator (PS0XX rules). They appear during `prs compile`,\nnot `prs validate`.\n\n#### Sealed properties\n\nPrevent `@extend` from overriding specified replace-strategy properties:\n\n```\n@skills {\n  deploy: {\n    content: (triple-quoted text with critical workflow)\n    sealed: ["content", "description"]\n  }\n}\n```\n\n`sealed: true` seals all replace-strategy properties. Attempting to override a sealed\nproperty is a hard compilation error. Only the base skill author can set `sealed` \u2014\noverlays cannot add or modify it. Append-strategy properties remain extendable.\nValidator PS029 warns about invalid entries in `sealed`.\n\n#### Skill composition (inline @use)\n\nImport sub-skills within a `@skills` block to compose multi-phase workflows:\n\n```\n@skills {\n  ops: {\n    description: "Production triage"\n    content: (triple-quoted text with orchestrator instructions)\n  }\n  @use ./phases/health-scan\n  @use ./phases/triage\n  @use ./phases/code-fix as autofix\n}\n```\n\nEach `@use` resolves the referenced `.prs` file, extracts its skill definition and context\nblocks, and flattens them as numbered phase sections into the parent skill\'s content. The\n`as alias` form controls the phase display name. Validator PS027 checks composition validity.\n\n### Parameterized Inheritance (Template Variables)\n\nUse `{{variable}}` placeholders in a **parent/template** file, and pass values\nfrom the **child** file via `@inherit` or `@use` with `(key: value)` syntax.\n\n**IMPORTANT:** Variables are NOT set from `promptscript.yaml` or CLI. They are\npassed from one `.prs` file to another through `@inherit` or `@use`.\n\n**Step 1: Create the template** (parent file with `params` in `@meta`):\n\n```\n# base.prs - reusable template\n@meta {\n  id: "service-template"\n  syntax: "1.0.0"\n  params: {\n    serviceName: string\n    port?: number = 3000\n  }\n}\n\n@identity {\n  """\n  You are working on {{serviceName}} running on port {{port}}.\n  """\n}\n```\n\n**Step 2: Inherit with values** (child file passes params):\n\n```\n# project.prs - concrete project\n@meta { id: "user-api" syntax: "1.0.0" }\n\n@inherit ./base(serviceName: "user-api", port: 8080)\n```\n\nAfter compilation, `{{serviceName}}` becomes `user-api` and `{{port}}` becomes `8080`.\n\nThe same works with `@use`:\n\n```\n@use ./base(serviceName: "auth-service") as auth\n```\n\n**Parameter types:** `string`, `number`, `boolean`, `enum("a", "b")`.\nOptional params use `?` suffix. Defaults use `= value`.\nMissing required params produce a compile error.\n\n**Multi-service pattern** - reuse one template across many projects:\n\n```\nservices/\n  base.prs                          # template with params\n  user-api/\n    promptscript.yaml               # source: project.prs\n    project.prs                     # @inherit ../base(serviceName: "user-api")\n  auth-service/\n    promptscript.yaml\n    project.prs                     # @inherit ../base(serviceName: "auth-service")\n```\n\n## Configuration: promptscript.yaml\n\n### Auto-injection\n\nThis skill is automatically included when compiling with `prs compile`. No manual copying needed.\nTo disable, set `includePromptScriptSkill: false` in your `promptscript.yaml`.\n\n```\nid: my-project\nsyntax: "1.1.0"\ndescription: "My project description"\ninput:\n  entry: .promptscript/project.prs\n  include: [\'.promptscript/**/*.prs\']\ntargets:\n  github:\n    version: full      # simple | multifile | full\n  claude:\n    version: full\n  cursor:\n    version: standard\n  antigravity:\n    version: frontmatter\n  factory:\n    version: full\n  windsurf:             # 41 additional targets supported\n    version: simple\n  cline:\n    version: simple\nregistry:\n  git: https://github.com/org/registry.git\n  ref: main\nregistries:\n  company:\n    url: github.com/acme/promptscript-registry\n  oss:\n    url: github.com/prscrpt/community-registry\n    ref: v2\npolicies:\n  - name: adjacent-layers-only\n    kind: layer-boundary\n    severity: error\n    layers: [\'@core\', \'@team\', \'@project\']\n    maxDistance: 1\n```\n\n### Lockfile: `promptscript.lock`\n\nWhen remote imports are used, run `prs lock` to generate or update the lockfile\nbefore compilation. It records the exact resolved commit for each dependency.\nIntegrity hashes (SHA-256) are included for registry references to detect\ntampering or drift. This enables reproducible builds across machines and CI.\nCommit `promptscript.lock` to version control.\n\nUse `--ignore-hashes` on `prs compile` or `prs validate` to skip integrity\nhash verification when needed.\n\n### Policy Engine\n\nDefine organizational policies in `promptscript.yaml` to validate skill extensions:\n\n```yaml\npolicies:\n  - name: adjacent-layers-only\n    kind: layer-boundary\n    description: \'Only adjacent layers can extend each other\'\n    severity: error\n    layers: [\'@core\', \'@team\', \'@project\']\n    maxDistance: 1\n\n  - name: protect-content\n    kind: property-protection\n    description: \'Content override requires explicit approval\'\n    severity: warning\n    properties: [\'content\', \'description\']\n\n  - name: approved-registries\n    kind: registry-allowlist\n    description: \'Extensions must come from approved registries\'\n    severity: error\n    allowed: [\'@core\', \'@team\']\n```\n\nPolicy kinds: `layer-boundary` (controls layer distance), `property-protection`\n(prevents overriding specific properties), `registry-allowlist` (restricts extension sources).\nSeverity: `error` (fails validation) or `warning` (reported only).\nSkip with `--skip-policies` during development (never in CI).\n\n## Syntax Version Validation\n\nThe `syntax` field in `@meta` declares the PromptScript language version (semver).\n\n### Known Versions\n\n| Version | What it adds                                                                                                            |\n| ------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `1.0.0` | Core blocks (identity, context, standards, restrictions, knowledge, shortcuts, commands, guards, params, skills, local) |\n| `1.1.0` | Adds `@agents` and `@workflows`; reserves internal `@prompts`                                                           |\n| `1.2.0` | Adds `@examples` (few-shot input/output pairs)                                                                          |\n| `1.3.0` | Adds explicit regular block field replacement in `@extend`                                                              |\n| `1.4.0` | Adds `@hooks`, `@mcpServers`, and `@plugins`                                                                            |\n| `1.5.0` | Adds `@header` section titles, `@override` replacement, and unquoted `${VAR}` values                                    |\n\n### Block Version Requirements\n\n| Block         | Minimum Syntax Version |\n| ------------- | ---------------------- |\n| `@agents`     | `1.1.0`                |\n| `@workflows`  | `1.1.0`                |\n| `@examples`   | `1.2.0`                |\n| `@hooks`      | `1.4.0`                |\n| `@mcpServers` | `1.4.0`                |\n| `@plugins`    | `1.4.0`                |\n\nAll other built-in blocks are available from `1.0.0`.\nRegular block field replacement with `field!: value` requires syntax `1.3.0`.\nGenerated section title overrides with `@header` require syntax `1.5.0`.\nAtomic replacement with `@override` requires syntax `1.5.0`.\nUnquoted `${VAR}` references as values require syntax `1.5.0`.\n\n### Generated Section Headers\n\nUse `@header` inside a registered owner block to rename human-readable output\nsections without changing filenames, frontmatter, XML tags, or structured keys:\n\n```promptscript\n@meta { id: "localized" syntax: "1.5.0" }\n\n@standards {\n  @header "Coding Rules"\n  @header git-commits "Commit Rules"\n  code: ["Use strict TypeScript"]\n}\n```\n\n- `@header "Title"` targets the block\'s primary section.\n- `@header <section-key> "Title"` targets an owned derived section.\n- Titles must be non-empty, single-line strings.\n- Source overrides take precedence over formatter configuration and target defaults.\n- Child inheritance, imported source, and the latest root extension take precedence.\n- An initial `## Heading` in a registered text-only primary owner is a syntax\n  `1.5.0` compatibility fallback. Explicit `@header` metadata wins.\n- Ordinary `header` and `headers` fields remain domain data.\n\n### Validation Rules\n\n- **PS018 (`syntax-version-compat`)**: warns when resolved blocks or syntax features require a higher version than declared. Requirements from inheritance, imports, and skill composition are included. Suggestion: run `prs validate --fix`.\n- **PS019 (`unknown-block-name`)**: warns when a block name is not a known PromptScript type, with fuzzy-match suggestions for typos.\n- **PS037 (`valid-section-headers`)**: rejects invalid titles, unknown or unowned section keys, duplicate overrides, and nested extension overrides.\n- **PS038 (`valid-block-shape`)**: rejects unsupported built-in block shapes and warns about formatter-sensitive legacy shapes or multiline shortcut scalars.\n- **PS039 (`agent-namespaces`)**: validates qualified agent name segments and checks them against recorded import provenance.\n- **PS040 (`import-excludes`)**: errors when a `validation.excludes` entry for an import does not record the commit pinned in promptscript.lock, so consumers re-review imports whose pinned commit changed.\n- **PS021 (`use-block-filter`)**: errors when `only` and `exclude` are both specified in `@use` parameters.\n- **PS025 (`valid-skill-references`)**: errors when a `references` entry points to a file with a disallowed extension or a path that cannot be resolved.\n- **PS026 (`safe-reference-content`)**: warns when a referenced file contains potentially sensitive content (e.g., secrets, credentials).\n- **PS027 (`valid-skill-composition`)**: warns about conflicting phase names or excessive phases in composed skills.\n- **PS028 (`valid-append-negation`)**: warns when negation prefix `!` appears in base skill definitions (only effective in `@extend`).\n- **PS029 (`valid-sealed-property`)**: warns when `sealed` contains non-replace-strategy property names.\n- **PS030 (`policy-compliance`)**: validates skill extensions against organizational policies defined in `promptscript.yaml`.\n- **PS034 (`valid-hooks`)**: validates portable hook events, commands/scripts, paths, interpreters, timeouts, cwd, and target overrides.\n\nTarget formatters report **PS4002** when a hook event or field has no native equivalent,\nwhen a target cannot guarantee project-root execution, or when output mode cannot emit\nthe additional hook file.\n\n### Fixing Syntax Versions\n\n```\nprs validate --fix          # Auto-fix syntax versions in .prs files\nprs upgrade                 # Upgrade all .prs files to the latest version\n```\n\n`--fix` rewrites the `syntax: "..."` line in each file\'s `@meta` block to match the minimum version required by resolved blocks and syntax features. It follows inheritance, imports, and skill composition. It only upgrades, never downgrades.\n\n`prs upgrade` upgrades all files to the latest known syntax version regardless of what blocks they use.\n\n## CLI Commands\n\n```\nprs init                    # Initialize project (auto-detects existing files)\nprs init --yes --targets claude factory\nprs init --dry-run          # Preview initialization\nprs init --auto-import      # Initialize + static import of existing files\nprs migrate                 # Interactive migration flow\nprs migrate --static        # Non-interactive static import\nprs migrate --llm           # Generate AI-assisted migration prompt\nprs migrate --static --dry-run\nprs compile                 # Compile to all targets\nprs compile --watch         # Watch mode\nprs compile --ignore-hashes # Skip integrity hash verification\nprs build <name>            # Compile a named build profile\nprs validate --strict       # Validate syntax\nprs validate --fix          # Auto-fix syntax version declarations\nprs validate --skip-policies # Skip policy engine evaluation\nprs upgrade                 # Upgrade all .prs files to latest syntax version\nprs import CLAUDE.md        # Import existing AI instructions\nprs import CLAUDE.md --dry-run # Preview import conversion\nprs inspect <skill>         # Show skill composition provenance\nprs inspect <skill> --layers # Show layer-level breakdown\nprs explain <path>          # Explain source and composition provenance\nprs explain <path> --format json # Machine-readable provenance history\nprs hooks install           # Install auto-compilation hooks for AI tools\nprs hooks install claude    # Install hooks for a specific tool\nprs hooks uninstall         # Remove installed auto-compilation hooks\nprs hooks uninstall claude  # Remove hooks for a specific tool\nprs skills add <source>     # Add a remote skill (@use + lock update + SKILL.md validation)\nprs skills add <source> --strict          # Treat validation warnings as errors\nprs skills add <source> --skip-validation # Bypass Agent Skills spec checks (not recommended)\nprs skills remove <name>    # Remove a skill (@use line + lock entry)\nprs skills list             # List all imported skills\nprs skills update           # Re-resolve markdown-imported skills (re-validates + re-hashes)\nprs pull                    # Update registry\nprs diff --target claude    # Show compilation diff\nprs diff --all --format json # Machine-readable diff report for CI\nprs diff --format json --include-content # Include generated content in the report\nprs lock                    # Generate/update promptscript.lock\nprs lock --dry-run          # Preview lockfile changes\nprs update                  # Re-resolve all remote imports to latest\nprs update <url>            # Update a specific registry\nprs vendor sync             # Copy cached deps to .promptscript/vendor/\nprs vendor check            # Verify vendor matches lockfile\nprs resolve @alias/path     # Debug: show how an import resolves\nprs registry list           # Show configured registries and aliases\nprs registry add <alias> <url>  # Add a registry alias\n```\n\n`prs init --yes` requires explicit, detected, or user-configured targets. It does not invent\ndefault tools. For existing projects, `prs migrate` preserves `promptscript.yaml`, isolates static\noutput under `.promptscript/migrated/`, leaves source instructions untouched, and performs no\nwrites when no candidates are detected.\n\n## Output Targets\n\n50 supported targets. Key examples:\n\n| Target      | Main File                       | Skills                                             |\n| ----------- | ------------------------------- | -------------------------------------------------- |\n| GitHub      | .github/copilot-instructions.md | .github/skills/\\*/SKILL.md                         |\n| Claude      | CLAUDE.md                       | .claude/skills/\\*/SKILL.md                         |\n| Cursor      | .cursor/rules/project.mdc       | .agents/skills/\\*/SKILL.md                         |\n| Antigravity | .agent/rules/project.md         | -                                                  |\n| Factory     | AGENTS.md                       | .factory/skills/\\*/SKILL.md, .factory/droids/\\*.md |\n| OpenCode    | OPENCODE.md                     | .opencode/skills/\\*/SKILL.md                       |\n| Gemini      | GEMINI.md                       | .agents/skills/\\*/skill.md                         |\n| Windsurf    | .windsurf/rules/project.md      | .windsurf/skills/\\*/SKILL.md                       |\n| Cline       | .clinerules                     | -                                                  |\n| Roo Code    | .roorules                       | -                                                  |\n| Codex       | AGENTS.md                       | .agents/skills/\\*/SKILL.md                         |\n| Continue    | .continue/rules/project.md      | -                                                  |\n| Hermes      | AGENTS.md                       | -                                                  |\n| + 37 more   |                                 | See full list in documentation                     |\n\nTargets that share an output path (for example Factory, Codex, and every AGENTS.md target) are\nreconciled in one output plan before anything is written. Identical content merges silently;\ndiffering content reports `PS4001`, where a formatter output replaces an earlier one and a\nresource or the auto-injected PromptScript skill keeps the file already planned. Paths are compared\ncase-insensitively and NFC-normalized on every platform.\n\n### Formatter Documentation\n\nFor detailed information about each formatter\'s output paths, supported features, quirks, and example outputs:\n\n- **Full formatter reference:** `docs/reference/formatters/` (7 dedicated pages + index of all 50)\n- **llms-full.txt:** Available at the docs site root - contains all documentation in a single file for LLM consumption\n- **Dedicated pages exist for:** Claude Code, GitHub Copilot, Cursor, Antigravity, Factory AI, Gemini CLI, OpenCode\n- **All 50 formatters indexed at:** `docs/reference/formatters/index.md` with output paths, tier, and feature flags\n\n### Auto-Compilation Hooks\n\nInstead of running `prs compile --watch` manually, install hooks so your AI tool\ntriggers compilation automatically when you edit `.prs` files:\n\n```\nprs hooks install          # Auto-detect and install for all detected tools\nprs hooks install claude   # Install for a specific tool\n```\n\nHooks also protect generated files from direct edits \u2014 when an AI agent tries\nto edit a compiled output (e.g., CLAUDE.md), the write is blocked with a message\npointing to the source `.prs` file. Supported tools: Claude Code, Factory AI,\nCursor, Windsurf, Cline, GitHub Copilot, Gemini CLI.\n\n## Project Organization\n\nTypical modular structure:\n\n```\n.promptscript/\n  project.prs      # Entry: @meta, @inherit, @use, @identity, @agents\n  context.prs      # @context (architecture, tech stack)\n  standards.prs    # @standards (coding conventions)\n  restrictions.prs # @restrictions (hard rules)\n  commands.prs     # @shortcuts and @knowledge\n```\n\nThe entry file uses `@use ./context`, `@use ./standards`, etc. to compose them.\n\n## Common Mistakes\n\n1. Missing @meta block - every .prs file needs `@meta` with `id` and `syntax`\n2. Multiple @inherit - only one per file; use `@use` for additional imports\n3. Extending an unknown path - target an inherited or local block, or use an imported alias\n4. Unquoted strings with special chars - quote strings containing `:`, `#`, `{`, `}`\n5. Forgetting to compile - `.prs` changes need `prs compile` to take effect\n6. Triple quotes inside triple quotes - not supported; describe content textually instead\n7. Using `{{var}}` in the root file without `@inherit` - template variables only work\n   in a parent file that defines `params` in `@meta`, with values passed by the child\n   via `@inherit ./parent(key: value)` or `@use ./fragment(key: value)`. They are NOT\n   set from `promptscript.yaml` or CLI flags\n8. Using `@examples` with `syntax: "1.0.0"` or `"1.1.0"` - `@examples` requires\n   syntax version `1.2.0`. Run `prs validate --fix` to auto-upgrade\n\n## Migrating Existing AI Instructions to PromptScript\n\n### Automated: `prs import`\n\nThe fastest way to convert existing AI instructions to PromptScript:\n\n```\nprs import CLAUDE.md                    # Convert a single file\nprs import .github/copilot-instructions.md\nprs import AGENTS.md --output ./imported\nprs import --dry-run CLAUDE.md          # Preview without writing\n```\n\n`prs import` automatically:\n\n- Detects the source format (Claude, GitHub Copilot, Cursor, Factory, etc.)\n- Maps content to appropriate PromptScript blocks (@identity, @standards, etc.)\n- Generates a valid `.prs` file with `@meta` block\n- Preserves the original intent and structure\n\nSupported source formats:\n\n- `CLAUDE.md` (Claude Code)\n- `.github/copilot-instructions.md` (GitHub Copilot)\n- `.cursorrules` or `.cursor/rules/*.mdc` (Cursor)\n- `AGENTS.md` (Factory AI / Codex)\n- `.clinerules` (Cline), `.roorules` (Roo Code)\n- `.windsurf/rules/*.md` (Windsurf)\n- Any Markdown-based AI instruction file\n\n### Manual Migration\n\nFor complex migrations or when `prs import` needs refinement:\n\n| Source Pattern                      | PromptScript Block |\n| ----------------------------------- | ------------------ |\n| "You are..." persona text           | `@identity`        |\n| Project description, tech stack     | `@context`         |\n| Coding conventions, style rules     | `@standards`       |\n| "Never...", "Always...", hard rules | `@restrictions`    |\n| `/command` definitions              | `@shortcuts`       |\n| Skill/tool definitions              | `@skills`          |\n| Agent/subagent configs              | `@agents`          |\n| Reference docs, API specs           | `@knowledge`       |\n\nAfter import, split into modular files (`context.prs`, `standards.prs`, etc.)\nand compose with `@use` in `project.prs`. Run `prs validate --strict` then\n`prs compile` to verify output matches the original.\n';
+    PROMPTSCRIPT_SKILL_CONTENT = '---\nname: promptscript\ndescription: >-\n  PromptScript language expert for reading, writing, modifying, and\n  troubleshooting .prs files. Use when working with PromptScript syntax,\n  creating or editing .prs files, adding blocks like @identity, @standards,\n  @restrictions, @shortcuts, @skills, or @agents, configuring\n  promptscript.yaml, resolving compilation errors, understanding inheritance\n  (@inherit), composition (@use, @extend, @override), contextual @header\n  metadata, or migrating AI instructions\n  to PromptScript. Also use when asked about the 50 built-in compilation\n  targets, including GitHub Copilot, Claude Code, Cursor, Antigravity,\n  Factory AI, and AGENTS.md-based platforms.\nlicense: MIT\nmetadata:\n  author: PromptScript\n  homepage: https://getpromptscript.dev\ncompatibility:\n  - claude-code\n  - github-copilot\n  - cursor\n  - factory-ai\n  - gemini-cli\n  - opencode\n  - windsurf\n  - cline\n  - roo\n  - codex\n  - continue\n  - augment\n  - goose\n  - kilo\n  - amp\n  - trae\n  - junie\n  - kiro-cli\nallowed-tools:\n  - Read\n  - Write\n  - Glob\n  - Grep\n  - Bash\nuser-invocable: true\n---\n\n# PromptScript Language Guide\n\nPromptScript is a domain-specific language that compiles `.prs` files into native instruction formats for AI coding assistants (GitHub Copilot, Claude Code, Cursor, Antigravity, Factory AI, OpenCode, Gemini CLI). One source of truth, multiple outputs.\n\n## File Structure\n\nA `.prs` file contains ordered declarations. Syntax `1.5.0` applies `@inherit`,\n`@use`, local blocks, `@extend`, and `@override` in source order. Put `@meta`\nfirst.\n\n```\n# Comments start with #\n\n@meta { ... }           # Required metadata\n@inherit @path          # Single inheritance (optional)\n@use @path [as alias]   # Imports/mixins (optional, multiple)\n\n@identity { ... }       # AI persona\n@context { ... }        # Project context\n@standards { ... }      # Coding conventions\n@restrictions { ... }   # Hard rules\n@shortcuts { ... }      # Command aliases\n@knowledge { ... }      # Reference documentation\n@skills { ... }         # Reusable skill definitions\n@agents { ... }         # Subagent definitions\n@workflows { ... }      # Repeatable agent procedures\n@examples { ... }       # Few-shot input/output examples (syntax 1.2.0+)\n@params { ... }         # Template parameters\n@guards { ... }         # File globs and priorities\n@hooks { ... }          # Portable lifecycle hooks (syntax 1.4.0+)\n@mcpServers { ... }     # MCP server configurations (syntax 1.4.0+)\n@plugins { ... }        # Capability bundles (syntax 1.4.0+)\n@local { ... }          # Private config (not committed)\n@extend path { ... }    # Modify imported blocks\n@override path { ... }  # Replace one complete existing target (syntax 1.5.0+)\n@custom-name { ... }    # Arbitrary named blocks\n```\n\nContextual `@header` entries appear inside supported owner blocks, not at the\ntop level.\n\n## Content Types\n\nPromptScript has four canonical content shapes inside blocks:\n\n### Text Content\n\nUse triple quotes (three double-quote characters) to wrap multiline text.\nText is automatically dedented - leading whitespace from source indentation is stripped.\nUse for prose, markdown, or freeform content.\n\nExample: `@identity` with a text block describing an AI persona starting with "You are..."\n\n### Object Content (key-value pairs)\n\n```\n@context {\n  project: "My App"\n  team: "Frontend"\n  monorepo: {\n    tool: "Nx"\n    packageManager: "pnpm"\n  }\n}\n```\n\nValues can be strings (quoted or unquoted), numbers, booleans, nested objects, or arrays.\n\n### Array Content\n\n```\n@standards {\n  code: [\n    "Use strict TypeScript",\n    "Named exports only"\n  ]\n}\n\n@restrictions {\n  - "Never use any type"\n  - "Never commit secrets"\n}\n```\n\n### Mixed Content\n\nBlocks can contain both object properties and text in the same block.\nPlace the triple-quoted text block alongside key-value pairs.\n\n## Block Reference\n\n### @meta (required)\n\n```\n@meta {\n  id: "project-id"        # Required: unique identifier\n  syntax: "1.0.0"         # Required: syntax version (semver)\n  org: "Company Name"     # Optional\n  team: "Frontend"        # Optional\n  tags: [react, ts]       # Optional\n  params: {               # Optional: template parameters\n    projectName: string\n    port: number = 3000\n    debug?: boolean\n    framework: enum("react", "vue") = "react"\n  }\n}\n```\n\n### @identity\n\nDefines AI persona. Start with "You are..." for consistent output across all formatters.\nContains a triple-quoted text block with the persona description.\n\n### @context\n\nProject context with structured properties (project, team, languages, runtime)\nplus optional triple-quoted text for architecture details, diagrams, etc.\n\n### @standards\n\nCategory-based conventions. Any category name is valid:\n\n```\n@standards {\n  typescript: ["Strict mode", "No any type"]\n  naming: ["Files: kebab-case.ts", "Classes: PascalCase"]\n  git: {\n    format: "Conventional Commits"\n    types: [feat, fix, docs, refactor, test, chore]\n  }\n}\n```\n\nCategory names are arbitrary. `@standards` can also contain free-form text:\n\n```\n@standards {\n  """\n  ## Formatting\n  Preserve heading structure and use four-space indentation.\n\n  ## Testing\n  Add regression coverage for every behavior change.\n  """\n  typescript: ["Strict mode", "Named exports only"]\n  git: {\n    format: "Conventional Commits"\n  }\n}\n```\n\nFree-form text is dedented and rendered with its Markdown heading structure. Factory\nmonolith output nests it under `Conventions & Patterns`; split Factory rules adjust\nheading levels relative to the generated section. Custom structured categories remain\navailable to formatters that support them.\n\n### @restrictions\n\nHard rules as a list of dash-prefixed strings:\n\n```\n@restrictions {\n  - "Never expose API keys"\n  - "Never commit secrets to version control"\n  - "Always validate user input"\n}\n```\n\n### @shortcuts\n\nSimple strings appear as documentation. Objects with `prompt: true` generate\nexecutable prompt/command files for GitHub Copilot and Cursor:\n\n```\n@shortcuts {\n  "/review": "Review code for quality"\n  "/test": {\n    prompt: true\n    description: "Write unit tests"\n    content: (triple-quoted text with instructions)\n  }\n}\n```\n\n> `@commands` is a backwards-compatible alias for `@shortcuts` \u2014 prefer `@shortcuts` in new files.\n\n### @skills\n\nReusable skill definitions with metadata:\n\n```\n@skills {\n  commit: {\n    description: "Create git commits"\n    trigger: "commit, git commit"\n    disableModelInvocation: true\n    userInvocable: true\n    allowedTools: ["Bash", "Read"]\n    content: (triple-quoted text with skill instructions)\n  }\n}\n```\n\nProperties: description (required), content (required), trigger, disableModelInvocation,\nuserInvocable, allowedTools, context ("fork" or "inherit"), agent, model (Claude Code and Grok\nBuild, mapped through the model catalog), requires, references, inputs, outputs.\n\nThe `references` property attaches external files to the skill\'s context:\n\n```\n@skills {\n  architecture-review: {\n    description: "Review architecture decisions"\n    references: [\n      ./references/architecture.md\n      ./references/modules.md\n    ]\n    content: (triple-quoted text)\n  }\n}\n```\n\nAllowed file types: `.md`, `.json`, `.yaml`, `.yml`, `.txt`, `.csv`. Paths are resolved relative\nto the `.prs` file. Formatters emit referenced files alongside SKILL.md in the output directory.\n\n### Parameterized Skills\n\nSkills in `.promptscript/skills/<name>/SKILL.md` support template parameters via\nYAML frontmatter. Define `params` in frontmatter and use `{{variable}}` in content:\n\n```yaml\n---\nname: review\ndescription: \'Review {{language}} code for {{standard}}\'\nparams:\n  language:\n    type: string\n  standard:\n    type: string\n    default: \'best practices\'\nreferences:\n  - references/architecture.md\n---\nReview the code using {{language}} conventions following {{standard}}.\n```\n\nThe `references` field in SKILL.md frontmatter lists files to attach to the skill\'s context.\nPaths are relative to the SKILL.md file.\n\nImported SKILL.md frontmatter is bounded: 256 KiB per document, 10,000 YAML nodes, 32 nesting\nlevels, 2,000 entries per mapping or sequence, and 64 KiB per string value. Documents over any\nlimit are rejected before their YAML values are converted.\n\nPass values in `@skills` block:\n\n```\n@skills {\n  review: {\n    description: "Review code"\n    language: "typescript"\n    standard: "strict mode"\n  }\n}\n```\n\nNon-reserved properties (anything other than description, content, trigger,\nuserInvocable, allowedTools, disableModelInvocation, context, agent, requires,\ninputs, outputs, model) are treated as skill parameter arguments.\n\n### Skill Dependencies\n\nSkills can declare dependencies on other skills via `requires`:\n\n```\n@skills {\n  deploy: {\n    description: "Deploy service"\n    requires: ["lint-check", "test-suite"]\n    content: (triple-quoted text)\n  }\n}\n```\n\nThe validator (PS016) checks that required skills exist, detects self-references,\nand catches circular dependency chains.\n\n### Skill Contracts (Inputs/Outputs)\n\nSkills can declare typed inputs and outputs in SKILL.md frontmatter:\n\n```yaml\n---\nname: security-scan\ndescription: \'Scan for vulnerabilities\'\ninputs:\n  files:\n    description: \'Files to scan\'\n    type: string\n  severity:\n    description: \'Minimum severity\'\n    type: enum\n    options: [low, medium, high]\n    default: medium\noutputs:\n  report:\n    description: \'Scan report\'\n    type: string\n  passed:\n    description: \'Whether scan passed\'\n    type: boolean\n---\n```\n\nField types: `string`, `number`, `boolean`, `enum` (with `options` list).\nThe validator (PS017) checks field types, ensures enum fields have options,\nand warns if param names collide with input names.\n\n### Shared Resources\n\nSkills in a folder can share common resources via `.promptscript/shared/`:\n\n```\n.promptscript/\n  shared/\n    templates.md         # Shared across all skills\n    style-guide.md\n  skills/\n    review/\n      SKILL.md           # Gets @shared/templates.md, @shared/style-guide.md\n    deploy/\n      SKILL.md           # Also gets shared resources\n```\n\nFiles in `shared/` are automatically included in every skill with `@shared/` prefix.\n\n### @agents\n\nCustom subagent definitions. Compiles to `.claude/agents/` for Claude Code,\n`.github/agents/` for GitHub Copilot, `.factory/droids/` for Factory AI, etc.\n\n```\n@agents {\n  code-reviewer: {\n    description: "Reviews code quality"\n    tools: ["Read", "Grep", "Glob", "Bash"]\n    model: "sonnet"\n    permissionMode: "default"\n    content: (triple-quoted text with agent instructions)\n  }\n}\n```\n\nImported agent definitions are qualified by an aliased `@use`:\n\n```\n@use ./frontend-team as frontend\n@use ./backend-team as backend\n```\n\nIf both imports define `reviewer`, the resolved names are `frontend.reviewer` and\n`backend.reviewer`. Unique unaliased imports keep their original names. Conflicting unaliased\ndefinitions stop compilation with source and import diagnostics instead of silently overwriting\none another. Native targets map dots to hyphens, so `frontend.reviewer` becomes\n`frontend-reviewer`.\n\nSupports mixed models per agent: `specModel` sets a different model for\nSpecification/planning mode (GitHub, Factory), `specReasoningEffort` sets reasoning\neffort for the spec model (Factory only, values: "low", "medium", "high").\n\nFactory AI droids support additional properties: `model` (any model ID or "inherit"),\n`reasoningEffort` ("low", "medium", "high"), and `tools` (category name like "read-only"\nor array of tool IDs).\n\nAgent `model`/`specModel` and skill `model` values resolve against the model catalog\n(built-in profiles plus `models.profiles` in promptscript.yaml). Write a floating alias\n(`sonnet`, `opus`, `haiku`, `fable` - newest Claude release), a pinned model (profile id,\nalias, API id, or display name such as `claude-opus-5-5` or `Claude Opus 5.5`), or\n`inherit`. Each target gets its native name: Claude Code keeps aliases and uses API ids\nfor pinned Claude models, GitHub Copilot gets display names (`Claude Sonnet 5`), Factory\nAI and Codex get API ids, and Cursor gets dateless ids. Names outside the catalog pass\nthrough unchanged, unless the target has its own spelling for them (GitHub Copilot writes\n`auto` as `Auto`). A model from a provider the target cannot run (a GPT model on Claude\nCode, a Claude model on Codex), or a name with a line break or control character, is\nomitted with a PS4004 warning.\n\n### @workflows\n\nRepeatable multi-step agent procedures. Requires syntax `1.1.0`.\n\n```\n@workflows {\n  release: {\n    description: "Prepare a validated release"\n    content: """\n      1. Run formatting, linting, type checks, and tests.\n      2. Validate compiled output.\n      3. Stop before publishing and request approval.\n    """\n  }\n}\n```\n\nTargets with native workflow discovery emit dedicated workflow files. Other targets\nretain workflow instructions in their main output when supported.\n\n### @examples\n\nStructured few-shot examples for AI assistants (requires syntax `1.2.0`):\n\n```\n@meta {\n  id: "commit-style"\n  syntax: "1.2.0"\n}\n\n@examples {\n  feat-commit: {\n    description: "Feature commit with scope"\n    input: "Added user authentication with JWT tokens"\n    output: "feat(auth): add JWT-based user authentication"\n  }\n}\n```\n\nEach entry is a named example with `input` and `output` (both required),\nplus optional `description`. Multi-line content uses triple-quoted strings.\n\nExamples can also be attached to skills via the `examples` property:\n\n```\n@skills {\n  commit: {\n    description: "Create conventional commits"\n    examples: {\n      basic: {\n        input: "Added dark mode toggle"\n        output: "feat(settings): add dark mode toggle"\n      }\n    }\n    content: (triple-quoted text)\n  }\n}\n```\n\n### @knowledge\n\nReference documentation as triple-quoted text. Used for command references,\nAPI docs, and other material that should appear in the output.\n\n### @params\n\nTemplate parameter definitions with types: string, number, boolean, enum("a", "b").\nOptional parameters use `?` suffix. Defaults use `= value`.\n\n### @guards\n\nFile glob patterns and priority rules for path-specific instructions.\n\n### @hooks\n\nPortable lifecycle hooks. Requires syntax `1.4.0`. Each hook needs exactly one of\n`command` or `script`.\n\n```\n@hooks {\n  validate-types: {\n    event: "post-tool-use"\n    matcher: "Edit|Write"\n    script: {\n      path: ".promptscript/scripts/validate.py"\n      interpreter: "python3"\n      args: ["--strict"]\n    }\n    cwd: "project"\n    timeoutMs: 120000\n    statusMessage: "Checking TypeScript"\n    continueOnFailure: false\n    enabled: true\n    targets: {\n      factory: { matcher: "Execute" }\n      vscode: { matcher: "run_in_terminal" }\n      github: { enabled: false }\n    }\n  }\n}\n```\n\nPortable events:\n\n| Event                  | Meaning                   |\n| ---------------------- | ------------------------- |\n| `pre-terminal-command` | Before a terminal command |\n| `pre-tool-use`         | Before a tool invocation  |\n| `post-tool-use`        | After a tool invocation   |\n| `session-start`        | Agent session start       |\n| `setup`                | Session setup             |\n| `subagent-start`       | Subagent start            |\n| `notification`         | Agent notification        |\n| `stop`                 | Agent stop                |\n\n`command` is a non-empty string array. Shell interpolation (`$()`, backticks,\n`${...}`) is forbidden. `script` requires:\n\n- `path` under `.promptscript/scripts/`, using forward slashes.\n- Existing regular file at compile time.\n- No traversal, absolute path, invalid segment, or symlink escape.\n- Explicit interpreter: `python3`, `python`, `node`, `deno`, `bun`, `ruby`, `php`,\n  `perl`, `bash`, `sh`, `zsh`, `pwsh`, or `powershell`.\n- Optional `args` string array; each argument remains one argument.\n\n`cwd: "project"` runs from project root. Other values are portable forward-slash\npaths relative to project root. Hook config file location does not set command cwd.\nEnvironment-root and Git-root wrappers exit before script or command execution when\nthe required root is unavailable. Native-cwd and workspace-cwd targets retain host\ncwd fields and report `PS4002` when PromptScript cannot verify that cwd.\n`timeoutMs` range is 100-600000. `matcher` uses target-native tool names, so a\nmatcher valid for one target may match nothing on another.\n\n`pre-terminal-command` supplies native defaults: Factory `Execute`, Claude and\nCodex `Bash`, Windsurf `pre_run_command`, Cursor `run_terminal_cmd`, Gemini\n`run_shell_command`, and VS Code `run_in_terminal`. Override a native tool name\nwith `targets.<name>.matcher`. Cursor, Gemini, and VS Code report best-effort\n`PS4002` warnings. GitHub and Grok omit the event with `PS4002`.\n\nTarget overrides may change `event`, `matcher`, `timeoutMs`, `statusMessage`,\n`continueOnFailure`, `enabled`, or `cwd`. Native hook files are emitted only in\ntarget modes that support additional files:\n\n| Target         | Hook output                                                            | Mode                |\n| -------------- | ---------------------------------------------------------------------- | ------------------- |\n| Claude Code    | `.claude/settings.json`                                                | `full`              |\n| Factory AI     | `.factory/hooks.json`                                                  | `multifile`, `full` |\n| GitHub Copilot | `.github/hooks/promptscript.json`                                      | `multifile`, `full` |\n| Cursor         | `.cursor/hooks.json`                                                   | `full`              |\n| Codex          | `.codex/hooks.json`                                                    | `multifile`, `full` |\n| Gemini CLI     | `.gemini/settings.json`                                                | `multifile`, `full` |\n| Windsurf       | `.windsurf/hooks.json`                                                 | `multifile`, `full` |\n| Grok Build     | `.grok/hooks/promptscript.json`                                        | `full`              |\n| OpenCode       | `.opencode/plugins/promptscript.ts` (generated plugin)                 | `multifile`, `full` |\n| VS Code Agent  | `.github/hooks/promptscript-vscode.json` when `vscode` override exists | target-specific     |\n\nOpenCode starts generated hook commands asynchronously. It enforces authored\ntimeouts or a 30-second default, then escalates from `SIGTERM` to `SIGKILL`.\nPayloads are bounded by UTF-8 byte length. OpenCode tool hooks expose tool\narguments, session ID, and call ID, but no model or agent context; compilation\nreports that limitation with `PS4002`.\n\nSimple mode and targets without native project hooks report `PS4002` instead of\nsilently dropping hooks. Use `prs compile --watch` as fallback. Plugin-only and\nagent-scoped integrations are not emitted as universal project hooks.\n\nEach generated command carries a PromptScript ownership marker. CLI cleanup removes\nonly marked entries and preserves user hooks/settings. Removing `@hooks` removes a\nfully owned generated hook file and prunes directories left empty. `prs hooks install factory`\nmigrates unambiguous legacy hooks from `.factory/settings.json`; ambiguous\nentries remain for manual review.\n\nFactory compilation performs the same migration when `.factory/hooks.json` is\nabsent. Use `prs compile --dry-run` to preview the changes or\n`--no-migrate-factory-hooks` to keep warning-only behavior. Unknown events,\nmalformed entries, and mixed ownership abort without a partial migration.\n\n`@hooks` compilation is separate from `prs hooks install`. The latter installs\nauto-compilation and generated-output protection for supported AI tools. Copilot VS\nCode Agent hooks use `promptscript-vscode.json`; GitHub Copilot repository hooks use\n`promptscript.json`.\n\n### @mcpServers\n\nProject-local Model Context Protocol servers. Requires syntax `1.4.0`.\n\n```\n@mcpServers {\n  issue-tracker: {\n    transport: "stdio"\n    command: ["node", "./tools/issues.mjs"]\n    env: { LOG_LEVEL: "info" }\n  }\n}\n```\n\nUse `stdio` with `command`, or `http`/`sse` with `url`. Keep credentials out of\n`.prs` files and provide them through target-native secret management.\n\n### @plugins\n\nPortable capability bundles. Requires syntax `1.4.0`.\n\n```\n@plugins {\n  security-suite: {\n    description: "Security review tooling"\n    version: "1.0.0"\n    skills: ["security-review"]\n    hooks: ["validate-types"]\n    mcpServers: ["issue-tracker"]\n  }\n}\n```\n\n### @local\n\nPrivate local configuration. Not included in compiled output or committed to git.\n\n## Inheritance and Composition\n\n### @inherit (single, linear)\n\nOne per file. Child blocks merge on top of parent:\n\n```\n@inherit @company/frontend-team\n@inherit ./parent\n@inherit @stacks/react-app(projectName: "my-app", port: 3000)\n```\n\n### @use (multiple, mixins)\n\nImport and merge fragments:\n\n```\n@use @core/security\n@use @core/quality\n@use ./local-config\n@use @core/typescript as ts   # alias enables @extend access\n```\n\n#### URL imports (Go-module style)\n\nImport directly from any Git repository by host path - no alias required:\n\n```\n@use github.com/acme/shared-standards/@fragments/security\n@use gitlab.com/myorg/prompts/@stacks/python\n```\n\nVersion pinning with `@`:\n\n```\n@use github.com/acme/shared-standards/@org/base@1.2.0    # exact version\n@use github.com/acme/shared-standards/@org/base@^1.0.0   # semver range\n@use github.com/acme/shared-standards/@org/base@main     # branch\n```\n\n#### Registry aliases\n\nShort names for Git repository URLs, configured in `promptscript.yaml`:\n\n```yaml\nregistries:\n  company:\n    url: github.com/acme/promptscript-registry\n```\n\nThen use the alias as scope prefix:\n\n```\n@use @company/security\n@inherit @company/base-config\n```\n\nMerge rules:\n\n- Text: concatenated with deduplication\n- Objects: deep merged (imported source wins same-shape conflicts)\n- Arrays: unique concatenation\n- Shape mismatch: existing target body wins\n\nUnder syntax `1.5.0`, later local blocks, `@extend`, and `@override`\noperations apply to the accumulated import result in declaration order.\n\n### Block Filtering\n\nControl which blocks are imported using the reserved `only` and `exclude` parameters:\n\n```\n@use ./shared-config(only: ["skills", "context"])\n@use ./shared-config(exclude: ["knowledge"])\n@use ./shared-config(exclude: ["knowledge"], mode: "strict")\n```\n\nRules:\n\n- `only` and `exclude` are mutually exclusive \u2014 using both is a validation error (PS021)\n- Values are block type names: `identity`, `context`, `standards`, `knowledge`, `skills`, `shortcuts`, `agents`, etc.\n- Block filtering does not apply to `@inherit` directives\n\n### Markdown Imports\n\nImport skills directly from `.md` files (v1.8+). No external tools needed:\n\n```\n@use ./skills/frontend-design.md\n@use ./shared/commit.md as commit\n@use github.com/anthropics/skills/commit@1.0.0\n@use github.com/repo/skills/gitnexus         # directory \u2192 SKILL.md\n```\n\nContent detection: PromptScript blocks in `.md` are parsed as a `.prs` fragment;\nYAML frontmatter with `name`/`description` is loaded as a skill definition;\notherwise content is treated as free-form knowledge.\n\nCLI management:\n\n```\nprs skills add github.com/anthropics/skills/commit@1.0.0\nprs skills remove commit\nprs skills list\nprs skills update\n```\n\n### @extend (modify existing or imported blocks)\n\nUse a direct path for inherited or local blocks:\n\n```\n@extend standards.testing {\n  coverage: 95\n}\n```\n\nUse an alias when targeting a specific imported block:\n\n```\n@use @core/typescript as ts\n\n@extend ts.standards {\n  testing: { coverage: 95 }\n}\n```\n\n#### Replacing regular block fields\n\nSyntax `1.3.0` supports explicit replacement of complete regular block field values:\n\n```\n@meta { id: "project" syntax: "1.3.0" }\n\n@inherit ./company-base\n\n@extend standards {\n  testing!: ["Use Vitest"]\n  linting: ["Use ESLint"]\n}\n```\n\n`testing!` replaces the inherited value. Fields without `!` keep normal merge behavior.\nReplacement works after `@inherit` and `@use`, including aliases and nested target paths.\nA missing field is set. The modifier is rejected for `@skills`, which retain their dedicated\nmerge and sealing semantics.\n\n#### Replacing complete targets with @override\n\nSyntax `1.5.0` adds atomic replacement for an existing block or nested value:\n\n```\n@meta { id: "project" syntax: "1.5.0" }\n\n@standards {\n  testing: ["Use Jest", "Use Mocha"]\n}\n\n@override standards.testing {\n  ["Use Vitest"]\n}\n```\n\n`@override` requires the complete target path to exist, applies in declaration\norder, and cannot bypass sealed skill properties. Later `@extend` declarations\nmerge into the replacement. Use `@extend` for additive changes, `field!` for\ncompatibility replacement of one direct regular field, and `@override` for\nintentional complete replacement.\n\n#### Skill-aware @extend semantics\n\nWhen extending a skill definition via `@extend`, individual skill properties follow specific merge\nstrategies rather than the generic block merge rules:\n\n| Strategy          | Properties                                                                                                  |\n| ----------------- | ----------------------------------------------------------------------------------------------------------- |\n| **Replace**       | content, description, trigger, userInvocable, allowedTools, disableModelInvocation, context, agent, license |\n| **Append**        | references, examples, requires                                                                              |\n| **Shallow merge** | params, inputs, outputs                                                                                     |\n\nExample \u2014 extending a base skill to add references and override content:\n\n```\n@use @company/skills as skills\n\n@extend skills.code-review {\n  content: (triple-quoted text with overridden instructions)\n  references: [\n    ./extra-context.md\n  ]\n}\n```\n\nThe `references` array from the base skill and the overlay are combined (append). The `content`\nfield from the overlay replaces the base (replace).\n\n#### Reference negation\n\nUse `!` prefix in `@extend` to remove entries from a lower layer\'s append-strategy arrays:\n\n```\n@extend skills.code-review {\n  references: [\n    "!references/deprecated.md"\n    "references/replacement.md"\n  ]\n}\n```\n\nPath matching is normalized (`"!./foo.md"` matches `"foo.md"`). Only works in `@extend` blocks\non `references` and `requires`. Validator PS028 warns about `!` in base definitions.\n\n#### Overlay consistency warnings\n\nThe resolver emits warnings during compile when an overlay drifts from its base. Always shown\n(not gated by `--verbose`):\n\n- **Orphaned extend** \u2014 `@extend target "X" not found \u2014 overlay will be ignored.` Triggered when\n  the targeted block doesn\'t exist (base removed or renamed).\n- **Stale skill target** \u2014 `@extend creates new skill "X" \u2014 base does not define it.` Triggered\n  when an `@extend` inside `@skills` would create a new skill instead of extending an existing one.\n- **Negation orphan** \u2014 `Negation "!path" did not match any base entry \u2014 it may be stale.`\n  Triggered when a `!entry` in references/requires doesn\'t match anything in the base.\n\nThese come from the resolver, not the validator (PS0XX rules). They appear during `prs compile`,\nnot `prs validate`.\n\n#### Sealed properties\n\nPrevent `@extend` from overriding specified replace-strategy properties:\n\n```\n@skills {\n  deploy: {\n    content: (triple-quoted text with critical workflow)\n    sealed: ["content", "description"]\n  }\n}\n```\n\n`sealed: true` seals all replace-strategy properties. Attempting to override a sealed\nproperty is a hard compilation error. Only the base skill author can set `sealed` \u2014\noverlays cannot add or modify it. Append-strategy properties remain extendable.\nValidator PS029 warns about invalid entries in `sealed`.\n\n#### Skill composition (inline @use)\n\nImport sub-skills within a `@skills` block to compose multi-phase workflows:\n\n```\n@skills {\n  ops: {\n    description: "Production triage"\n    content: (triple-quoted text with orchestrator instructions)\n  }\n  @use ./phases/health-scan\n  @use ./phases/triage\n  @use ./phases/code-fix as autofix\n}\n```\n\nEach `@use` resolves the referenced `.prs` file, extracts its skill definition and context\nblocks, and flattens them as numbered phase sections into the parent skill\'s content. The\n`as alias` form controls the phase display name. Validator PS027 checks composition validity.\n\n### Parameterized Inheritance (Template Variables)\n\nUse `{{variable}}` placeholders in a **parent/template** file, and pass values\nfrom the **child** file via `@inherit` or `@use` with `(key: value)` syntax.\n\n**IMPORTANT:** Variables are NOT set from `promptscript.yaml` or CLI. They are\npassed from one `.prs` file to another through `@inherit` or `@use`.\n\n**Step 1: Create the template** (parent file with `params` in `@meta`):\n\n```\n# base.prs - reusable template\n@meta {\n  id: "service-template"\n  syntax: "1.0.0"\n  params: {\n    serviceName: string\n    port?: number = 3000\n  }\n}\n\n@identity {\n  """\n  You are working on {{serviceName}} running on port {{port}}.\n  """\n}\n```\n\n**Step 2: Inherit with values** (child file passes params):\n\n```\n# project.prs - concrete project\n@meta { id: "user-api" syntax: "1.0.0" }\n\n@inherit ./base(serviceName: "user-api", port: 8080)\n```\n\nAfter compilation, `{{serviceName}}` becomes `user-api` and `{{port}}` becomes `8080`.\n\nThe same works with `@use`:\n\n```\n@use ./base(serviceName: "auth-service") as auth\n```\n\n**Parameter types:** `string`, `number`, `boolean`, `enum("a", "b")`.\nOptional params use `?` suffix. Defaults use `= value`.\nMissing required params produce a compile error.\n\n**Multi-service pattern** - reuse one template across many projects:\n\n```\nservices/\n  base.prs                          # template with params\n  user-api/\n    promptscript.yaml               # source: project.prs\n    project.prs                     # @inherit ../base(serviceName: "user-api")\n  auth-service/\n    promptscript.yaml\n    project.prs                     # @inherit ../base(serviceName: "auth-service")\n```\n\n## Configuration: promptscript.yaml\n\n### Auto-injection\n\nThis skill is automatically included when compiling with `prs compile`. No manual copying needed.\nTo disable, set `includePromptScriptSkill: false` in your `promptscript.yaml`.\n\n```\nid: my-project\nsyntax: "1.1.0"\ndescription: "My project description"\ninput:\n  entry: .promptscript/project.prs\n  include: [\'.promptscript/**/*.prs\']\ntargets:\n  github:\n    version: full      # simple | multifile | full\n  claude:\n    version: full\n  cursor:\n    version: standard\n  antigravity:\n    version: frontmatter\n  factory:\n    version: full\n  windsurf:             # 41 additional targets supported\n    version: simple\n  cline:\n    version: simple\nregistry:\n  git: https://github.com/org/registry.git\n  ref: main\nregistries:\n  company:\n    url: github.com/acme/promptscript-registry\n  oss:\n    url: github.com/prscrpt/community-registry\n    ref: v2\npolicies:\n  - name: adjacent-layers-only\n    kind: layer-boundary\n    severity: error\n    layers: [\'@core\', \'@team\', \'@project\']\n    maxDistance: 1\nmodels:\n  supported: [opus, sonnet, gpt-5.3-codex]  # PS041 reports models outside this set\n  profiles:                                 # add models or override built-in profiles\n    claude-opus-9:\n      provider: anthropic\n      family: claude-opus                   # joins the family, so `opus` now resolves here\n      version: \'9\'\n      displayName: Claude Opus 9\n      targets:\n        github: Claude Opus 9 (Preview)     # per-target name always wins\n```\n\n### Lockfile: `promptscript.lock`\n\nWhen remote imports are used, run `prs lock` to generate or update the lockfile\nbefore compilation. It records the exact resolved commit for each dependency.\nIntegrity hashes (SHA-256) are included for registry references to detect\ntampering or drift. This enables reproducible builds across machines and CI.\nCommit `promptscript.lock` to version control.\n\nUse `--ignore-hashes` on `prs compile` or `prs validate` to skip integrity\nhash verification when needed.\n\n### Policy Engine\n\nDefine organizational policies in `promptscript.yaml` to validate skill extensions:\n\n```yaml\npolicies:\n  - name: adjacent-layers-only\n    kind: layer-boundary\n    description: \'Only adjacent layers can extend each other\'\n    severity: error\n    layers: [\'@core\', \'@team\', \'@project\']\n    maxDistance: 1\n\n  - name: protect-content\n    kind: property-protection\n    description: \'Content override requires explicit approval\'\n    severity: warning\n    properties: [\'content\', \'description\']\n\n  - name: approved-registries\n    kind: registry-allowlist\n    description: \'Extensions must come from approved registries\'\n    severity: error\n    allowed: [\'@core\', \'@team\']\n```\n\nPolicy kinds: `layer-boundary` (controls layer distance), `property-protection`\n(prevents overriding specific properties), `registry-allowlist` (restricts extension sources).\nSeverity: `error` (fails validation) or `warning` (reported only).\nSkip with `--skip-policies` during development (never in CI).\n\n## Syntax Version Validation\n\nThe `syntax` field in `@meta` declares the PromptScript language version (semver).\n\n### Known Versions\n\n| Version | What it adds                                                                                                            |\n| ------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `1.0.0` | Core blocks (identity, context, standards, restrictions, knowledge, shortcuts, commands, guards, params, skills, local) |\n| `1.1.0` | Adds `@agents` and `@workflows`; reserves internal `@prompts`                                                           |\n| `1.2.0` | Adds `@examples` (few-shot input/output pairs)                                                                          |\n| `1.3.0` | Adds explicit regular block field replacement in `@extend`                                                              |\n| `1.4.0` | Adds `@hooks`, `@mcpServers`, and `@plugins`                                                                            |\n| `1.5.0` | Adds `@header` section titles, `@override` replacement, and unquoted `${VAR}` values                                    |\n\n### Block Version Requirements\n\n| Block         | Minimum Syntax Version |\n| ------------- | ---------------------- |\n| `@agents`     | `1.1.0`                |\n| `@workflows`  | `1.1.0`                |\n| `@examples`   | `1.2.0`                |\n| `@hooks`      | `1.4.0`                |\n| `@mcpServers` | `1.4.0`                |\n| `@plugins`    | `1.4.0`                |\n\nAll other built-in blocks are available from `1.0.0`.\nRegular block field replacement with `field!: value` requires syntax `1.3.0`.\nGenerated section title overrides with `@header` require syntax `1.5.0`.\nAtomic replacement with `@override` requires syntax `1.5.0`.\nUnquoted `${VAR}` references as values require syntax `1.5.0`.\n\n### Generated Section Headers\n\nUse `@header` inside a registered owner block to rename human-readable output\nsections without changing filenames, frontmatter, XML tags, or structured keys:\n\n```promptscript\n@meta { id: "localized" syntax: "1.5.0" }\n\n@standards {\n  @header "Coding Rules"\n  @header git-commits "Commit Rules"\n  code: ["Use strict TypeScript"]\n}\n```\n\n- `@header "Title"` targets the block\'s primary section.\n- `@header <section-key> "Title"` targets an owned derived section.\n- Titles must be non-empty, single-line strings.\n- Source overrides take precedence over formatter configuration and target defaults.\n- Child inheritance, imported source, and the latest root extension take precedence.\n- An initial `## Heading` in a registered text-only primary owner is a syntax\n  `1.5.0` compatibility fallback. Explicit `@header` metadata wins.\n- Ordinary `header` and `headers` fields remain domain data.\n\n### Validation Rules\n\n- **PS018 (`syntax-version-compat`)**: warns when resolved blocks or syntax features require a higher version than declared. Requirements from inheritance, imports, and skill composition are included. Suggestion: run `prs validate --fix`.\n- **PS019 (`unknown-block-name`)**: warns when a block name is not a known PromptScript type, with fuzzy-match suggestions for typos.\n- **PS037 (`valid-section-headers`)**: rejects invalid titles, unknown or unowned section keys, duplicate overrides, and nested extension overrides.\n- **PS038 (`valid-block-shape`)**: rejects unsupported built-in block shapes and warns about formatter-sensitive legacy shapes or multiline shortcut scalars.\n- **PS039 (`agent-namespaces`)**: validates qualified agent name segments and checks them against recorded import provenance.\n- **PS040 (`import-excludes`)**: errors when a `validation.excludes` entry for an import does not record the commit pinned in promptscript.lock, so consumers re-review imports whose pinned commit changed.\n- **PS041 (`valid-model-reference`)**: warns when an agent `model`/`specModel` or skill `model` resolves to a deprecated or retired model, suggesting the successor. With `models.supported` set, it also warns about models outside the set, models missing from the catalog, and unknown `models.supported` entries. It also reports `models.profiles` problems: a name shared by two profiles or taken from a floating alias or `inherit`, unknown or looping successors, dates not in `YYYY-MM-DD`, and `targets` keys for targets that write no model names.\n- **PS021 (`use-block-filter`)**: errors when `only` and `exclude` are both specified in `@use` parameters.\n- **PS025 (`valid-skill-references`)**: errors when a `references` entry points to a file with a disallowed extension or a path that cannot be resolved.\n- **PS026 (`safe-reference-content`)**: warns when a referenced file contains potentially sensitive content (e.g., secrets, credentials).\n- **PS027 (`valid-skill-composition`)**: warns about conflicting phase names or excessive phases in composed skills.\n- **PS028 (`valid-append-negation`)**: warns when negation prefix `!` appears in base skill definitions (only effective in `@extend`).\n- **PS029 (`valid-sealed-property`)**: warns when `sealed` contains non-replace-strategy property names.\n- **PS030 (`policy-compliance`)**: validates skill extensions against organizational policies defined in `promptscript.yaml`.\n- **PS034 (`valid-hooks`)**: validates portable hook events, commands/scripts, paths, interpreters, timeouts, cwd, and target overrides.\n\nTarget formatters report **PS4002** when a hook event or field has no native equivalent,\nwhen a target cannot guarantee project-root execution, or when output mode cannot emit\nthe additional hook file. They report **PS4004** when an agent or skill model comes from\na provider the target cannot run, or when its name has a line break or control character;\nthe model field is omitted for that target.\n\n### Fixing Syntax Versions\n\n```\nprs validate --fix          # Auto-fix syntax versions in .prs files\nprs upgrade                 # Upgrade all .prs files to the latest version\n```\n\n`--fix` rewrites the `syntax: "..."` line in each file\'s `@meta` block to match the minimum version required by resolved blocks and syntax features. It follows inheritance, imports, and skill composition. It only upgrades, never downgrades.\n\n`prs upgrade` upgrades all files to the latest known syntax version regardless of what blocks they use.\n\n## CLI Commands\n\n```\nprs init                    # Initialize project (auto-detects existing files)\nprs init --yes --targets claude factory\nprs init --dry-run          # Preview initialization\nprs init --auto-import      # Initialize + static import of existing files\nprs migrate                 # Interactive migration flow\nprs migrate --static        # Non-interactive static import\nprs migrate --llm           # Generate AI-assisted migration prompt\nprs migrate --static --dry-run\nprs compile                 # Compile to all targets\nprs compile --watch         # Watch mode\nprs compile --ignore-hashes # Skip integrity hash verification\nprs build <name>            # Compile a named build profile\nprs validate --strict       # Validate syntax\nprs validate --fix          # Auto-fix syntax version declarations\nprs validate --skip-policies # Skip policy engine evaluation\nprs upgrade                 # Upgrade all .prs files to latest syntax version\nprs import CLAUDE.md        # Import existing AI instructions\nprs import CLAUDE.md --dry-run # Preview import conversion\nprs inspect <skill>         # Show skill composition provenance\nprs inspect <skill> --layers # Show layer-level breakdown\nprs explain <path>          # Explain source and composition provenance\nprs explain <path> --format json # Machine-readable provenance history\nprs hooks install           # Install auto-compilation hooks for AI tools\nprs hooks install claude    # Install hooks for a specific tool\nprs hooks uninstall         # Remove installed auto-compilation hooks\nprs hooks uninstall claude  # Remove hooks for a specific tool\nprs skills add <source>     # Add a remote skill (@use + lock update + SKILL.md validation)\nprs skills add <source> --strict          # Treat validation warnings as errors\nprs skills add <source> --skip-validation # Bypass Agent Skills spec checks (not recommended)\nprs skills remove <name>    # Remove a skill (@use line + lock entry)\nprs skills list             # List all imported skills\nprs skills update           # Re-resolve markdown-imported skills (re-validates + re-hashes)\nprs pull                    # Update registry\nprs diff --target claude    # Show compilation diff\nprs diff --all --format json # Machine-readable diff report for CI\nprs diff --format json --include-content # Include generated content in the report\nprs lock                    # Generate/update promptscript.lock\nprs lock --dry-run          # Preview lockfile changes\nprs update                  # Re-resolve all remote imports to latest\nprs update <url>            # Update a specific registry\nprs vendor sync             # Copy cached deps to .promptscript/vendor/\nprs vendor check            # Verify vendor matches lockfile\nprs resolve @alias/path     # Debug: show how an import resolves\nprs registry list           # Show configured registries and aliases\nprs registry add <alias> <url>  # Add a registry alias\n```\n\n`prs init --yes` requires explicit, detected, or user-configured targets. It does not invent\ndefault tools. For existing projects, `prs migrate` preserves `promptscript.yaml`, isolates static\noutput under `.promptscript/migrated/`, leaves source instructions untouched, and performs no\nwrites when no candidates are detected.\n\n## Output Targets\n\n50 supported targets. Key examples:\n\n| Target      | Main File                       | Skills                                             |\n| ----------- | ------------------------------- | -------------------------------------------------- |\n| GitHub      | .github/copilot-instructions.md | .github/skills/\\*/SKILL.md                         |\n| Claude      | CLAUDE.md                       | .claude/skills/\\*/SKILL.md                         |\n| Cursor      | .cursor/rules/project.mdc       | .agents/skills/\\*/SKILL.md                         |\n| Antigravity | .agent/rules/project.md         | -                                                  |\n| Factory     | AGENTS.md                       | .factory/skills/\\*/SKILL.md, .factory/droids/\\*.md |\n| OpenCode    | OPENCODE.md                     | .opencode/skills/\\*/SKILL.md                       |\n| Gemini      | GEMINI.md                       | .agents/skills/\\*/skill.md                         |\n| Windsurf    | .windsurf/rules/project.md      | .windsurf/skills/\\*/SKILL.md                       |\n| Cline       | .clinerules                     | -                                                  |\n| Roo Code    | .roorules                       | -                                                  |\n| Codex       | AGENTS.md                       | .agents/skills/\\*/SKILL.md                         |\n| Continue    | .continue/rules/project.md      | -                                                  |\n| Hermes      | AGENTS.md                       | -                                                  |\n| + 37 more   |                                 | See full list in documentation                     |\n\nTargets that share an output path (for example Factory, Codex, and every AGENTS.md target) are\nreconciled in one output plan before anything is written. Identical content merges silently;\ndiffering content reports `PS4001`, where a formatter output replaces an earlier one and a\nresource or the auto-injected PromptScript skill keeps the file already planned. Paths are compared\ncase-insensitively and NFC-normalized on every platform.\n\n### Formatter Documentation\n\nFor detailed information about each formatter\'s output paths, supported features, quirks, and example outputs:\n\n- **Full formatter reference:** `docs/reference/formatters/` (7 dedicated pages + index of all 50)\n- **llms-full.txt:** Available at the docs site root - contains all documentation in a single file for LLM consumption\n- **Dedicated pages exist for:** Claude Code, GitHub Copilot, Cursor, Antigravity, Factory AI, Gemini CLI, OpenCode\n- **All 50 formatters indexed at:** `docs/reference/formatters/index.md` with output paths, tier, and feature flags\n\n### Auto-Compilation Hooks\n\nInstead of running `prs compile --watch` manually, install hooks so your AI tool\ntriggers compilation automatically when you edit `.prs` files:\n\n```\nprs hooks install          # Auto-detect and install for all detected tools\nprs hooks install claude   # Install for a specific tool\n```\n\nHooks also protect generated files from direct edits \u2014 when an AI agent tries\nto edit a compiled output (e.g., CLAUDE.md), the write is blocked with a message\npointing to the source `.prs` file. Supported tools: Claude Code, Factory AI,\nCursor, Windsurf, Cline, GitHub Copilot, Gemini CLI.\n\n## Project Organization\n\nTypical modular structure:\n\n```\n.promptscript/\n  project.prs      # Entry: @meta, @inherit, @use, @identity, @agents\n  context.prs      # @context (architecture, tech stack)\n  standards.prs    # @standards (coding conventions)\n  restrictions.prs # @restrictions (hard rules)\n  commands.prs     # @shortcuts and @knowledge\n```\n\nThe entry file uses `@use ./context`, `@use ./standards`, etc. to compose them.\n\n## Common Mistakes\n\n1. Missing @meta block - every .prs file needs `@meta` with `id` and `syntax`\n2. Multiple @inherit - only one per file; use `@use` for additional imports\n3. Extending an unknown path - target an inherited or local block, or use an imported alias\n4. Unquoted strings with special chars - quote strings containing `:`, `#`, `{`, `}`\n5. Forgetting to compile - `.prs` changes need `prs compile` to take effect\n6. Triple quotes inside triple quotes - not supported; describe content textually instead\n7. Using `{{var}}` in the root file without `@inherit` - template variables only work\n   in a parent file that defines `params` in `@meta`, with values passed by the child\n   via `@inherit ./parent(key: value)` or `@use ./fragment(key: value)`. They are NOT\n   set from `promptscript.yaml` or CLI flags\n8. Using `@examples` with `syntax: "1.0.0"` or `"1.1.0"` - `@examples` requires\n   syntax version `1.2.0`. Run `prs validate --fix` to auto-upgrade\n\n## Migrating Existing AI Instructions to PromptScript\n\n### Automated: `prs import`\n\nThe fastest way to convert existing AI instructions to PromptScript:\n\n```\nprs import CLAUDE.md                    # Convert a single file\nprs import .github/copilot-instructions.md\nprs import AGENTS.md --output ./imported\nprs import --dry-run CLAUDE.md          # Preview without writing\n```\n\n`prs import` automatically:\n\n- Detects the source format (Claude, GitHub Copilot, Cursor, Factory, etc.)\n- Maps content to appropriate PromptScript blocks (@identity, @standards, etc.)\n- Generates a valid `.prs` file with `@meta` block\n- Preserves the original intent and structure\n\nSupported source formats:\n\n- `CLAUDE.md` (Claude Code)\n- `.github/copilot-instructions.md` (GitHub Copilot)\n- `.cursorrules` or `.cursor/rules/*.mdc` (Cursor)\n- `AGENTS.md` (Factory AI / Codex)\n- `.clinerules` (Cline), `.roorules` (Roo Code)\n- `.windsurf/rules/*.md` (Windsurf)\n- Any Markdown-based AI instruction file\n\n### Manual Migration\n\nFor complex migrations or when `prs import` needs refinement:\n\n| Source Pattern                      | PromptScript Block |\n| ----------------------------------- | ------------------ |\n| "You are..." persona text           | `@identity`        |\n| Project description, tech stack     | `@context`         |\n| Coding conventions, style rules     | `@standards`       |\n| "Never...", "Always...", hard rules | `@restrictions`    |\n| `/command` definitions              | `@shortcuts`       |\n| Skill/tool definitions              | `@skills`          |\n| Agent/subagent configs              | `@agents`          |\n| Reference docs, API specs           | `@knowledge`       |\n\nAfter import, split into modular files (`context.prs`, `standards.prs`, etc.)\nand compose with `@use` in `project.prs`. Run `prs validate --strict` then\n`prs compile` to verify output matches the original.\n';
   }
 });
 
@@ -20767,6 +21423,214 @@ var init_agent_capability_warnings = __esm({
   }
 });
 
+// packages/formatters/src/model-mapping.ts
+function unquoteYamlToken(token) {
+  const quote = token[0];
+  if ((quote === "'" || quote === '"') && token.at(-1) === quote && token.length >= 2) {
+    return token.slice(1, -1);
+  }
+  return token;
+}
+function stripYamlComment(value) {
+  let quote;
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i];
+    if (quote === void 0) {
+      if (char === "'" || char === '"') {
+        quote = char;
+      } else if (char === "#" && (i === 0 || value[i - 1] === " " || value[i - 1] === "	")) {
+        return value.slice(0, i);
+      }
+    } else if (char === quote) {
+      quote = void 0;
+    }
+  }
+  return value;
+}
+function splitYamlMapping(line) {
+  if (line.startsWith(" ") || line.startsWith("	")) return void 0;
+  const colon = line.indexOf(":");
+  if (colon < 0) return void 0;
+  const rest = line.slice(colon + 1);
+  if (rest !== "" && !rest.startsWith(" ") && !rest.startsWith("	")) return void 0;
+  return [unquoteYamlToken(line.slice(0, colon).trim()), rest];
+}
+function isFrontmatterModelLine(line) {
+  return splitYamlMapping(line)?.[0] === MODEL_KEY;
+}
+function blockScalarKind(value) {
+  const first2 = value[0];
+  if (first2 !== "|" && first2 !== ">") return void 0;
+  for (const char of value.slice(1)) {
+    if (char !== "-" && char !== "+" && (char < "1" || char > "9")) return void 0;
+  }
+  return first2 === "|" ? "literal" : "folded";
+}
+function blockScalarLines(lines, keyIndex) {
+  const block = [];
+  for (const line of lines.slice(keyIndex + 1)) {
+    if (line === "" || line.startsWith(" ") || line.startsWith("	")) {
+      block.push(line);
+    } else {
+      break;
+    }
+  }
+  while (block.length > 0 && block.at(-1) === "") block.pop();
+  return block;
+}
+function blockScalarValue(block, kind) {
+  const indents = block.filter((line) => line !== "").map((line) => line.length - line.trimStart().length);
+  const indent = indents.length > 0 ? Math.min(...indents) : 0;
+  const content = block.map((line) => line === "" ? "" : line.slice(indent));
+  if (kind === "literal") {
+    return content.join("\n").trim();
+  }
+  const paragraphs = [[]];
+  for (const line of content) {
+    if (line === "") {
+      paragraphs.push([]);
+    } else {
+      paragraphs.at(-1)?.push(line.trim());
+    }
+  }
+  return paragraphs.map((lines) => lines.join(" ")).join("\n").trim();
+}
+function findRawFrontmatterModel(frontmatter) {
+  const lines = frontmatter.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === void 0 || !isFrontmatterModelLine(line)) continue;
+    const valuePart = stripYamlComment(line.slice(line.indexOf(":") + 1)).trim();
+    if (!valuePart) {
+      return { keyIndex: i, lineCount: 1, value: void 0 };
+    }
+    const kind = blockScalarKind(valuePart);
+    if (kind === void 0) {
+      return { keyIndex: i, lineCount: 1, value: unquoteYamlToken(valuePart) };
+    }
+    const block = blockScalarLines(lines, i);
+    const value = blockScalarValue(block, kind);
+    return { keyIndex: i, lineCount: 1 + block.length, value: value === "" ? void 0 : value };
+  }
+  return void 0;
+}
+function extractRawFrontmatterModel(frontmatter) {
+  return findRawFrontmatterModel(frontmatter)?.value;
+}
+function toTargetModel(model, target, models) {
+  if (model === void 0) return void 0;
+  return mapModelToTarget(model, target, getModelCatalog(models)).value;
+}
+function describeInvalidName(label, target, profile) {
+  if (!profile) {
+    return {
+      message: `${label} has a line break or control character, so it is omitted.`,
+      suggestion: "Write the model name on one line, without control characters."
+    };
+  }
+  return {
+    message: `${label} maps to a name with a line break or control character on target "${target}", so it is omitted.`,
+    suggestion: `Remove line breaks and control characters from models.profiles.${profile.id} in promptscript.yaml.`
+  };
+}
+function describeOmission(label, target, mapped) {
+  if (mapped.issue === "invalid-name") return describeInvalidName(label, target, mapped.profile);
+  if (mapped.issue !== "unsupported-provider" || !mapped.profile) return void 0;
+  const providers = (getModelTargetScheme(target)?.providers ?? []).map((provider) => `"${provider}"`).join(" or ");
+  return {
+    message: `${label} comes from provider "${mapped.profile.provider}", which target "${target}" cannot run, so it is omitted.`,
+    suggestion: `Use a model from provider ${providers}, or set models.profiles.${mapped.profile.id}.targets.${target} in promptscript.yaml.`
+  };
+}
+function blockEntries(ast, name) {
+  const block = ast.blocks.find((candidate) => candidate.name === name);
+  if (!block) return [];
+  if (block.content.type !== "ObjectContent" && block.content.type !== "MixedContent") return [];
+  return Object.entries(block.content.properties).flatMap(
+    ([entryName, value]) => value && typeof value === "object" && !Array.isArray(value) ? [
+      [entryName, value, block]
+    ] : []
+  );
+}
+function emitsResource(target, kind, version) {
+  return TARGET_CAPABILITIES[target].resources.some(
+    (resource) => resource.kind === kind && resource.versions.includes(version)
+  );
+}
+function modelReferenceWarning(owner, field, value, block, target, catalog) {
+  if (typeof value !== "string") return void 0;
+  const described = describeOmission(
+    `${owner}: ${field} ${JSON.stringify(value.trim())}`,
+    target,
+    mapModelToTarget(value, target, catalog)
+  );
+  return described && {
+    code: MODEL_COMPATIBILITY_CODE,
+    ruleName: "model-compatibility",
+    ...described,
+    location: block.loc
+  };
+}
+function agentModelWarnings(ast, target, version, catalog) {
+  if (!emitsResource(target, "agents", version)) return [];
+  const fields = AGENT_MODEL_FIELDS.filter(
+    (field) => getAgentFieldStatus(target, field) !== "not-supported"
+  );
+  return blockEntries(ast, "agents").flatMap(
+    ([name, entry, block]) => fields.flatMap((field) => {
+      const warning = modelReferenceWarning(
+        `Agent "${name}"`,
+        field,
+        entry[field],
+        block,
+        target,
+        catalog
+      );
+      return warning ? [warning] : [];
+    })
+  );
+}
+function frontmatterModelWarning(name, entry, block, target, catalog) {
+  if (entry["model"] !== void 0) return void 0;
+  const frontmatter = typeof entry["__rawFrontmatter"] === "string" ? entry["__rawFrontmatter"] : void 0;
+  const rawModel = frontmatter !== void 0 ? extractRawFrontmatterModel(frontmatter) : void 0;
+  return rawModel === void 0 ? void 0 : modelReferenceWarning(`Skill "${name}"`, "model", rawModel, block, target, catalog);
+}
+function skillModelWarnings(ast, target, version, catalog) {
+  if (!SKILL_MODEL_TARGETS.has(target) || !emitsResource(target, "skills", version)) return [];
+  return blockEntries(ast, "skills").flatMap(([name, entry, block]) => {
+    const warnings = [
+      modelReferenceWarning(`Skill "${name}"`, "model", entry["model"], block, target, catalog),
+      frontmatterModelWarning(name, entry, block, target, catalog)
+    ].flatMap((warning) => warning ? [warning] : []);
+    return warnings;
+  });
+}
+function getModelCompatibilityWarnings(ast, target, version, models) {
+  if (!isKnownTarget(target) || !getModelTargetScheme(target)) return [];
+  const catalog = getModelCatalog(models);
+  return [
+    ...agentModelWarnings(ast, target, version, catalog),
+    ...skillModelWarnings(ast, target, version, catalog)
+  ];
+}
+function appendModelCompatibilityWarnings(output, ast, target, version, models) {
+  const warnings = getModelCompatibilityWarnings(ast, target, version, models);
+  if (warnings.length === 0) return output;
+  return { ...output, warnings: [...output.warnings ?? [], ...warnings] };
+}
+var MODEL_COMPATIBILITY_CODE, AGENT_MODEL_FIELDS, SKILL_MODEL_TARGETS, MODEL_KEY;
+var init_model_mapping = __esm({
+  "packages/formatters/src/model-mapping.ts"() {
+    "use strict";
+    init_src();
+    MODEL_COMPATIBILITY_CODE = "PS4004";
+    AGENT_MODEL_FIELDS = ["model", "specModel"];
+    SKILL_MODEL_TARGETS = /* @__PURE__ */ new Set(["claude", "grok"]);
+    MODEL_KEY = "model";
+  }
+});
+
 // packages/formatters/src/mcp-helpers.ts
 function findMcpServersBlock(ast) {
   return ast.blocks.find((b) => b.name === "mcpServers");
@@ -20951,6 +21815,7 @@ var init_markdown_instruction_formatter = __esm({
     init_hook_adapters();
     init_hook_capability_warnings();
     init_agent_capability_warnings();
+    init_model_mapping();
     init_mcp_helpers();
     init_section_title_resolver();
     MarkdownInstructionFormatter = class extends BaseFormatter {
@@ -20998,7 +21863,14 @@ var init_markdown_instruction_formatter = __esm({
         const agentOutput = appendAgentCapabilityWarnings(warnedOutput, ast, this.name, version, {
           blockWarningHandled: (this.config.unsupportedBlocks ?? []).includes("agents")
         });
-        return appendTargetHookCapabilityWarnings(agentOutput, ast, this.name, version);
+        const modelOutput = appendModelCompatibilityWarnings(
+          agentOutput,
+          ast,
+          this.name,
+          version,
+          options?.models
+        );
+        return appendTargetHookCapabilityWarnings(modelOutput, ast, this.name, version);
       }
       hasEnabledHooks(ast) {
         const hooksBlock = ast.blocks.find((block) => block.name === "hooks");
@@ -21138,7 +22010,7 @@ var init_markdown_instruction_formatter = __esm({
           }
         }
         if (this.config.hasAgents) {
-          const agents = this.extractAgents(ast);
+          const agents = this.extractAgents(ast, options);
           for (const agent of agents) {
             additionalFiles.push(this.generateAgentFile(agent));
           }
@@ -21278,27 +22150,32 @@ var init_markdown_instruction_formatter = __esm({
       // ============================================================
       // Agent Extraction & File Generation
       // ============================================================
-      extractAgents(ast) {
+      extractAgents(ast, _options) {
         const agentsBlock = this.findBlock(ast, "agents");
         if (!agentsBlock) return [];
         const agents = [];
         const props = this.getProps(agentsBlock.content);
         const nativeNames = this.getNativeAgentNameMap(ast);
         for (const [name, value] of Object.entries(props)) {
-          if (value && typeof value === "object" && !Array.isArray(value)) {
-            if (!this.isSafeAgentName(name)) continue;
-            const obj = value;
-            const description = obj["description"] ? this.valueToString(obj["description"]) : "";
-            if (!description) continue;
-            agents.push({
-              name: nativeNames.get(name) ?? name,
-              description,
-              content: obj["content"] ? this.valueToString(obj["content"]) : ""
-            });
-          }
+          if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+          if (!this.isSafeAgentName(name)) continue;
+          const agent = this.parseAgent(nativeNames.get(name) ?? name, value);
+          if (agent) agents.push(agent);
         }
         return agents;
       }
+      /**
+       * Build one agent config, or undefined when it has no description.
+       */
+      parseAgent(nativeName, obj) {
+        const description = obj["description"] ? this.valueToString(obj["description"]) : "";
+        if (!description) return void 0;
+        return {
+          name: nativeName,
+          description,
+          content: obj["content"] ? this.valueToString(obj["content"]) : ""
+        };
+      }
       generateAgentFile(config) {
         const lines = [];
         lines.push("---");
@@ -22247,7 +23124,7 @@ var init_feature_matrix = __esm({
 });
 
 // packages/formatters/src/formatters/github.ts
-var GITHUB_VERSIONS, TOOL_NAME_MAPPING, MODEL_NAME_MAPPING, GitHubFormatter;
+var GITHUB_VERSIONS, TOOL_NAME_MAPPING, GitHubFormatter;
 var init_github2 = __esm({
   "packages/formatters/src/formatters/github.ts"() {
     "use strict";
@@ -22257,6 +23134,7 @@ var init_github2 = __esm({
     init_hook_adapters();
     init_hook_capability_warnings();
     init_agent_capability_warnings();
+    init_model_mapping();
     init_section_title_resolver();
     GITHUB_VERSIONS = {
       simple: {
@@ -22298,28 +23176,6 @@ var init_github2 = __esm({
       TodoWrite: "todo",
       TodoRead: "todo"
     };
-    MODEL_NAME_MAPPING = {
-      // Claude models - default aliases map to latest versions (4.5)
-      sonnet: "Claude Sonnet 4.5",
-      opus: "Claude Opus 4.5",
-      haiku: "Claude Haiku 4.5",
-      // Explicit version mappings
-      "sonnet-4": "Claude Sonnet 4",
-      "sonnet-4.5": "Claude Sonnet 4.5",
-      "opus-4": "Claude Opus 4",
-      "opus-4.5": "Claude Opus 4.5",
-      "haiku-4": "Claude Haiku 4",
-      "haiku-4.5": "Claude Haiku 4.5",
-      // OpenAI models (pass through if already in correct format)
-      "gpt-4o": "GPT-4o",
-      "gpt-4.1": "GPT-4.1",
-      "gpt-5": "GPT-5",
-      "gpt-5-mini": "GPT-5 mini",
-      // Special values
-      inherit: "",
-      // Empty string means omit the model property
-      auto: "Auto"
-    };
     GitHubFormatter = class extends BaseFormatter {
       name = "github";
       outputPath = ".github/copilot-instructions.md";
@@ -22352,6 +23208,7 @@ var init_github2 = __esm({
         }
         output = appendTargetHookCapabilityWarnings(output, ast, this.name, version);
         output = appendAgentCapabilityWarnings(output, ast, this.name, version);
+        output = appendModelCompatibilityWarnings(output, ast, this.name, version, options?.models);
         const hooksBlock = ast.blocks.find((block) => block.name === "hooks");
         const hooks = hooksBlock ? extractHooks(hooksBlock) : [];
         const hookWarnings = hooksBlock && version !== "simple" ? [
@@ -22450,7 +23307,7 @@ var init_github2 = __esm({
         for (const skill of skills2) {
           additionalFiles.push(this.generateCopilotSkillFile(skill, options));
         }
-        const customAgents = this.extractCustomAgents(ast);
+        const customAgents = this.extractCustomAgents(ast, options);
         for (const agent of customAgents) {
           additionalFiles.push(this.generateCustomAgentFile(agent));
         }
@@ -22824,7 +23681,7 @@ ${f.content}`
        *
        * @see https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-custom-agents
        */
-      extractCustomAgents(ast) {
+      extractCustomAgents(ast, options) {
         const agentsBlock = this.findBlock(ast, "agents");
         if (!agentsBlock) return [];
         const agents = [];
@@ -22833,36 +23690,43 @@ ${f.content}`
         const mcpServersBlock = findMcpServersBlock(ast);
         const availableMcpServers = mcpServersBlock ? extractMcpServers(mcpServersBlock) : [];
         for (const [name, value] of Object.entries(props)) {
-          if (value && typeof value === "object" && !Array.isArray(value)) {
-            if (!this.isSafeAgentName(name)) continue;
-            const obj = value;
-            const description = obj["description"] ? this.valueToString(obj["description"]) : "";
-            if (!description) continue;
-            const handoffs = this.extractHandoffs(obj["handoffs"]).map((handoff) => ({
-              ...handoff,
-              agent: this.getNativeAgentName(ast, handoff.agent)
-            }));
-            const mcpServersValue = obj["mcpServers"];
-            const mcpServerNames = Array.isArray(mcpServersValue) ? mcpServersValue.filter(
-              (serverName) => typeof serverName === "string"
-            ) : [];
-            const mcpServers = availableMcpServers.filter(
-              (server) => mcpServerNames.includes(server.name)
-            );
-            agents.push({
-              name: nativeNames.get(name) ?? name,
-              description,
-              tools: this.parseToolsArray(obj["tools"]),
-              model: obj["model"] ? this.valueToString(obj["model"]) : void 0,
-              specModel: obj["specModel"] ? this.valueToString(obj["specModel"]) : void 0,
-              handoffs: handoffs.length > 0 ? handoffs : void 0,
-              mcpServers: mcpServers.length > 0 ? mcpServers : void 0,
-              content: obj["content"] ? this.valueToString(obj["content"]) : ""
-            });
-          }
+          if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+          if (!this.isSafeAgentName(name)) continue;
+          const agent = this.parseCustomAgent(
+            ast,
+            nativeNames.get(name) ?? name,
+            value,
+            availableMcpServers,
+            options
+          );
+          if (agent) agents.push(agent);
         }
         return agents;
       }
+      /**
+       * Build one custom agent config, or undefined when it has no description.
+       */
+      parseCustomAgent(ast, nativeName, obj, availableMcpServers, options) {
+        const description = obj["description"] ? this.valueToString(obj["description"]) : "";
+        if (!description) return void 0;
+        const handoffs = this.extractHandoffs(obj["handoffs"]).map((handoff) => ({
+          ...handoff,
+          agent: this.getNativeAgentName(ast, handoff.agent)
+        }));
+        const mcpServersValue = obj["mcpServers"];
+        const mcpServerNames = Array.isArray(mcpServersValue) ? mcpServersValue.filter((serverName) => typeof serverName === "string") : [];
+        const mcpServers = availableMcpServers.filter((server) => mcpServerNames.includes(server.name));
+        return {
+          name: nativeName,
+          description,
+          tools: this.parseToolsArray(obj["tools"]),
+          model: this.copilotModel(obj["model"], options),
+          specModel: this.copilotModel(obj["specModel"], options),
+          handoffs: handoffs.length > 0 ? handoffs : void 0,
+          mcpServers: mcpServers.length > 0 ? mcpServers : void 0,
+          content: obj["content"] ? this.valueToString(obj["content"]) : ""
+        };
+      }
       /**
        * Parse tools array from a Value and map to GitHub Copilot canonical names.
        *
@@ -22919,15 +23783,14 @@ ${f.content}`
         return lines;
       }
       /**
-       * Map a model name from PromptScript/Claude Code format to GitHub Copilot format.
+       * Map a model reference to its Copilot model name through the model catalog.
+       * Names missing from the catalog pass through, so Copilot names work as-is.
        *
-       * @returns The mapped model name, or undefined if the model should be omitted (e.g., "inherit")
+       * @returns The Copilot model name, or undefined when the model is omitted (e.g., "inherit")
        */
-      mapModelName(model) {
-        if (!model) return void 0;
-        const mapped = MODEL_NAME_MAPPING[model.toLowerCase()];
-        if (mapped === "") return void 0;
-        return mapped ?? model;
+      copilotModel(value, options) {
+        if (!value) return void 0;
+        return toTargetModel(this.valueToString(value), this.name, options?.models);
       }
       /**
        * Generate a .github/agents/<name>.md file.
@@ -22943,13 +23806,11 @@ ${f.content}`
           const toolsArray = config.tools.map((t) => `'${t}'`).join(", ");
           lines.push(`tools: [${toolsArray}]`);
         }
-        const mappedModel = this.mapModelName(config.model);
-        if (mappedModel) {
-          lines.push(`model: ${mappedModel}`);
+        if (config.model) {
+          lines.push(`model: ${this.yamlString(config.model)}`);
         }
-        const mappedSpecModel = this.mapModelName(config.specModel);
-        if (mappedSpecModel) {
-          lines.push(`specModel: ${mappedSpecModel}`);
+        if (config.specModel) {
+          lines.push(`specModel: ${this.yamlString(config.specModel)}`);
         }
         if (config.handoffs && config.handoffs.length > 0) {
           lines.push(...this.renderHandoffsYaml(config.handoffs));
@@ -23423,6 +24284,7 @@ var init_claude2 = __esm({
     init_hook_adapters();
     init_hook_capability_warnings();
     init_agent_capability_warnings();
+    init_model_mapping();
     init_mcp_helpers();
     init_section_title_resolver();
     CLAUDE_VERSIONS = {
@@ -23443,6 +24305,16 @@ var init_claude2 = __esm({
       }
     };
     ClaudeFormatter = class extends BaseFormatter {
+      /**
+       * @param modelTarget - Target whose model names agent and skill files use.
+       *   Grok writes its agent and skill files through this formatter, so its
+       *   `models.profiles` names must apply to them.
+       */
+      constructor(modelTarget = "claude") {
+        super();
+        this.modelTarget = modelTarget;
+      }
+      modelTarget;
       name = "claude";
       outputPath = "CLAUDE.md";
       description = "Claude Code instructions (concise Markdown)";
@@ -23474,6 +24346,7 @@ var init_claude2 = __esm({
         }
         output = appendTargetHookCapabilityWarnings(output, ast, this.name, version);
         output = appendAgentCapabilityWarnings(output, ast, this.name, version);
+        output = appendModelCompatibilityWarnings(output, ast, this.name, version, options?.models);
         output = {
           ...output,
           managedOutputFiles: [
@@ -23549,7 +24422,7 @@ var init_claude2 = __esm({
         for (const skill of skills2) {
           additionalFiles.push(this.generateClaudeSkillFile(skill, options));
         }
-        const agents = this.extractAgents(ast);
+        const agents = this.extractAgents(ast, options);
         for (const agent of agents) {
           additionalFiles.push(this.generateAgentFile(agent));
         }
@@ -23790,7 +24663,7 @@ var init_claude2 = __esm({
               userInvocable: obj["userInvocable"] === true,
               disableModelInvocation: obj["disableModelInvocation"] === true,
               argumentHint: obj["argumentHint"] ? this.valueToString(obj["argumentHint"]) : void 0,
-              model: obj["model"] ? this.valueToString(obj["model"]) : void 0,
+              model: this.claudeModel(obj["model"], options),
               content: obj["content"] ? this.valueToString(obj["content"]) : "",
               resources: obj["resources"] && Array.isArray(obj["resources"]) ? obj["resources"].map((r) => ({
                 relativePath: r["relativePath"],
@@ -23804,6 +24677,31 @@ var init_claude2 = __esm({
         }
         return skills2;
       }
+      /**
+       * Apply the model field to raw SKILL.md frontmatter.
+       *
+       * A `.prs` model wins over the frontmatter one; without it, the
+       * frontmatter value is mapped through the model catalog for this target.
+       * Unmappable values drop the whole property, block scalars included,
+       * and PS4004 reports why; frontmatter without a model line gains one
+       * from `.prs`. Empty values are left untouched.
+       */
+      applyRawFrontmatterModel(rawFrontmatter, prsModel, options) {
+        const field = findRawFrontmatterModel(rawFrontmatter);
+        if (field === void 0) {
+          return prsModel === void 0 ? rawFrontmatter : `${rawFrontmatter}
+model: ${this.yamlString(prsModel)}`;
+        }
+        if (field.value === void 0) return rawFrontmatter;
+        const lines = rawFrontmatter.split(/\r?\n/);
+        const mapped = prsModel ?? this.claudeModel(field.value, options);
+        if (mapped === void 0) {
+          lines.splice(field.keyIndex, field.lineCount);
+        } else {
+          lines.splice(field.keyIndex, field.lineCount, `model: ${this.yamlString(mapped)}`);
+        }
+        return lines.join("\n");
+      }
       /**
        * Generate a .claude/skills/<name>/SKILL.md file.
        */
@@ -23811,7 +24709,7 @@ var init_claude2 = __esm({
         const lines = [];
         lines.push("---");
         if (config.rawFrontmatter) {
-          lines.push(config.rawFrontmatter);
+          lines.push(this.applyRawFrontmatterModel(config.rawFrontmatter, config.model, options));
         } else {
           lines.push(`name: '${config.name}'`);
           const descQuote = config.description.includes("'") ? '"' : "'";
@@ -23838,7 +24736,7 @@ var init_claude2 = __esm({
             lines.push(`argument-hint: '${config.argumentHint}'`);
           }
           if (config.model) {
-            lines.push(`model: ${config.model}`);
+            lines.push(`model: ${this.yamlString(config.model)}`);
           }
         }
         lines.push("---");
@@ -23936,7 +24834,7 @@ ${f.content}`
       /**
        * Extract agent configurations from @agents block.
        */
-      extractAgents(ast) {
+      extractAgents(ast, options) {
         const agentsBlock = this.findBlock(ast, "agents");
         if (!agentsBlock) return [];
         const agents = [];
@@ -23946,7 +24844,7 @@ ${f.content}`
           if (value && typeof value === "object" && !Array.isArray(value)) {
             if (!this.isSafeAgentName(name)) continue;
             const obj = value;
-            const agent = this.parseAgentConfig(nativeNames.get(name) ?? name, obj);
+            const agent = this.parseAgentConfig(nativeNames.get(name) ?? name, obj, options);
             if (agent) {
               agents.push(agent);
             }
@@ -23957,7 +24855,7 @@ ${f.content}`
       /**
        * Parse a single agent configuration from object properties.
        */
-      parseAgentConfig(name, obj) {
+      parseAgentConfig(name, obj, options) {
         const description = obj["description"] ? this.valueToString(obj["description"]) : "";
         if (!description) return null;
         return {
@@ -23965,7 +24863,7 @@ ${f.content}`
           description,
           tools: this.parseStringArray(obj["tools"]),
           disallowedTools: this.parseStringArray(obj["disallowedTools"]),
-          model: this.parseAgentModel(obj["model"]),
+          model: this.claudeModel(obj["model"], options),
           permissionMode: this.parsePermissionMode(obj["permissionMode"]),
           skills: this.parseStringArray(obj["skills"]),
           maxTurns: obj["maxTurns"] !== void 0 && typeof obj["maxTurns"] === "number" ? obj["maxTurns"] : void 0,
@@ -23985,13 +24883,13 @@ ${f.content}`
         return arr.length > 0 ? arr : void 0;
       }
       /**
-       * Parse model value, validating it's a known model.
+       * Map a model reference to a Claude Code model value through the model
+       * catalog. Floating aliases, inherit, and names missing from the catalog
+       * stay as written; models from other providers are omitted (PS4004).
        */
-      parseAgentModel(value) {
+      claudeModel(value, options) {
         if (!value) return void 0;
-        const str = this.valueToString(value);
-        const validModels = ["sonnet", "opus", "haiku", "inherit"];
-        return validModels.includes(str) ? str : void 0;
+        return toTargetModel(this.valueToString(value), this.modelTarget, options?.models);
       }
       /**
        * Parse permission mode value.
@@ -24036,7 +24934,7 @@ ${f.content}`
           lines.push(`disallowedTools: [${arr}]`);
         }
         if (config.model) {
-          lines.push(`model: ${config.model}`);
+          lines.push(`model: ${this.yamlString(config.model)}`);
         }
         if (config.permissionMode) {
           lines.push(`permissionMode: ${config.permissionMode}`);
@@ -24520,6 +25418,7 @@ var init_cursor2 = __esm({
     init_hook_adapters();
     init_hook_capability_warnings();
     init_agent_capability_warnings();
+    init_model_mapping();
     init_mcp_helpers();
     init_plugin_helpers();
     init_section_title_resolver();
@@ -24628,6 +25527,7 @@ var init_cursor2 = __esm({
         }
         output = appendTargetHookCapabilityWarnings(output, ast, this.name, version);
         output = appendAgentCapabilityWarnings(output, ast, this.name, version);
+        output = appendModelCompatibilityWarnings(output, ast, this.name, version, options?.models);
         return {
           ...output,
           managedOutputFiles: [
@@ -24797,7 +25697,8 @@ ${content}`);
               agentLines.push(`name: ${nativeAgentName}`);
               if (description) agentLines.push(`description: ${JSON.stringify(description)}`);
               const model = obj["model"];
-              if (typeof model === "string") agentLines.push(`model: ${model}`);
+              const cursorModel = typeof model === "string" ? toTargetModel(model, this.name, options?.models) : void 0;
+              if (cursorModel) agentLines.push(`model: ${this.yamlString(cursorModel)}`);
               const agentMcp = obj["mcpServers"];
               if (agentMcp && typeof agentMcp === "object" && !Array.isArray(agentMcp)) {
                 const mcpNames = Object.keys(agentMcp);
@@ -26355,6 +27256,7 @@ var init_factory = __esm({
     init_mcp_helpers();
     init_plugin_helpers();
     init_section_title_resolver();
+    init_model_mapping();
     FACTORY_VERSIONS = {
       simple: {
         name: "simple",
@@ -26702,32 +27604,45 @@ ${f.content}`
       // ============================================================
       // Droid File Generation (Factory-specific)
       // ============================================================
-      extractAgents(ast) {
+      extractAgents(ast, options) {
         const agentsBlock = this.findBlock(ast, "agents");
         if (!agentsBlock) return [];
         const droids = [];
         const props = this.getProps(agentsBlock.content);
         for (const [name, value] of Object.entries(props)) {
           if (!this.isSafeAgentName(name)) continue;
-          if (value && typeof value === "object" && !Array.isArray(value)) {
-            const obj = value;
-            const description = obj["description"] ? this.valueToString(obj["description"]) : "";
-            if (!description) continue;
-            droids.push({
-              name: this.getNativeAgentName(ast, name),
-              description,
-              content: obj["content"] ? this.valueToString(obj["content"]) : "",
-              model: obj["model"] ? this.valueToString(obj["model"]) : void 0,
-              reasoningEffort: this.parseReasoningEffort(obj["reasoningEffort"]),
-              specModel: obj["specModel"] ? this.valueToString(obj["specModel"]) : void 0,
-              specReasoningEffort: this.parseReasoningEffort(obj["specReasoningEffort"]),
-              tools: this.parseDroidTools(obj["tools"]),
-              mcpServers: this.parseMcpServerNames(obj["mcpServers"])
-            });
-          }
+          if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+          const droid = this.parseDroid(ast, name, value, options);
+          if (droid) droids.push(droid);
         }
         return droids;
       }
+      /**
+       * Build one droid config, or undefined when it has no description.
+       */
+      parseDroid(ast, name, obj, options) {
+        const description = obj["description"] ? this.valueToString(obj["description"]) : "";
+        if (!description) return void 0;
+        return {
+          name: this.getNativeAgentName(ast, name),
+          description,
+          content: obj["content"] ? this.valueToString(obj["content"]) : "",
+          model: this.droidModel(obj["model"], options),
+          reasoningEffort: this.parseReasoningEffort(obj["reasoningEffort"]),
+          specModel: this.droidModel(obj["specModel"], options),
+          specReasoningEffort: this.parseReasoningEffort(obj["specReasoningEffort"]),
+          tools: this.parseDroidTools(obj["tools"]),
+          mcpServers: this.parseMcpServerNames(obj["mcpServers"])
+        };
+      }
+      /**
+       * Map a model reference to a Factory model ID through the model catalog.
+       * Names missing from the catalog pass through unchanged.
+       */
+      droidModel(value, options) {
+        if (!value) return void 0;
+        return toTargetModel(this.valueToString(value), this.name, options?.models);
+      }
       generateAgentFile(config) {
         const droidConfig = config;
         const lines = [];
@@ -26737,13 +27652,13 @@ ${f.content}`
           lines.push(`description: ${this.yamlString(droidConfig.description)}`);
         }
         if (droidConfig.model) {
-          lines.push(`model: ${droidConfig.model}`);
+          lines.push(`model: ${this.yamlString(droidConfig.model)}`);
         }
         if (droidConfig.reasoningEffort) {
           lines.push(`reasoningEffort: ${droidConfig.reasoningEffort}`);
         }
         if (droidConfig.specModel) {
-          lines.push(`specModel: ${droidConfig.specModel}`);
+          lines.push(`specModel: ${this.yamlString(droidConfig.specModel)}`);
         }
         if (droidConfig.specReasoningEffort) {
           lines.push(`specReasoningEffort: ${droidConfig.specReasoningEffort}`);
@@ -27078,7 +27993,7 @@ ${trimmed}`;
           additionalFiles.push(this.generateSkillFile(skill, options));
         }
         if (this.config.hasAgents) {
-          const agents = this.extractAgents(ast);
+          const agents = this.extractAgents(ast, options);
           for (const agent of agents) {
             additionalFiles.push(this.generateAgentFile(agent));
           }
@@ -27736,7 +28651,7 @@ function agentMcpServerLines(mcpServers, resolvedMcpServers) {
   }
   return [];
 }
-function serializeAgentToml(agentName, agent, resolvedMcpServers) {
+function serializeAgentToml(agentName, agent, resolvedMcpServers, models) {
   const lines = [];
   lines.push(`name = "${escapeTomlString2(agentName)}"`);
   const description = agent["description"];
@@ -27745,8 +28660,9 @@ function serializeAgentToml(agentName, agent, resolvedMcpServers) {
   }
   lines.push(...agentInstructionsLines(agent["content"]));
   const model = agent["model"];
-  if (typeof model === "string") {
-    lines.push(`model = "${escapeTomlString2(model)}"`);
+  const codexModel = typeof model === "string" ? toTargetModel(model, "codex", models) : void 0;
+  if (codexModel) {
+    lines.push(`model = "${escapeTomlString2(codexModel)}"`);
   }
   const reasoningEffort = agent["reasoningEffort"];
   if (typeof reasoningEffort === "string") {
@@ -27786,6 +28702,7 @@ var init_codex = __esm({
     init_hook_adapters();
     init_hook_capability_warnings();
     init_agent_capability_warnings();
+    init_model_mapping();
     init_mcp_helpers();
     init_plugin_helpers();
     CODEX_VERSIONS = {
@@ -27974,7 +28891,12 @@ var init_codex = __esm({
             if (!isValidAgentName(agentName)) continue;
             const agent = agentValue;
             const nativeAgentName = nativeNames.get(agentName) ?? agentName;
-            const toml = serializeAgentToml(nativeAgentName, agent, resolvedMcpServers);
+            const toml = serializeAgentToml(
+              nativeAgentName,
+              agent,
+              resolvedMcpServers,
+              options?.models
+            );
             extraFiles.push({
               path: `.codex/agents/${nativeAgentName}.toml`,
               content: toml
@@ -28729,6 +29651,7 @@ var init_grok = __esm({
     init_hook_adapters();
     init_hook_capability_warnings();
     init_agent_capability_warnings();
+    init_model_mapping();
     GROK_VERSIONS = {
       simple: {
         name: "simple",
@@ -28751,7 +29674,7 @@ var init_grok = __esm({
       outputPath = "AGENTS.md";
       description = "Grok Build instructions (AGENTS.md + Claude delegation)";
       defaultConvention = "markdown";
-      claudeFormatter = new ClaudeFormatter();
+      claudeFormatter = new ClaudeFormatter("grok");
       static getSupportedVersions() {
         return GROK_VERSIONS;
       }
@@ -28776,6 +29699,7 @@ var init_grok = __esm({
         }
         output = appendTargetHookCapabilityWarnings(output, ast, this.name, version);
         output = appendAgentCapabilityWarnings(output, ast, this.name, version);
+        output = appendModelCompatibilityWarnings(output, ast, this.name, version, options?.models);
         return {
           ...output,
           managedOutputFiles: [
@@ -28809,7 +29733,7 @@ var init_grok = __esm({
         });
         const additionalFiles = [];
         if (claudeMultifile.path !== "AGENTS.md") {
-          additionalFiles.push(claudeMultifile);
+          additionalFiles.push({ ...claudeMultifile, warnings: void 0 });
         }
         if (claudeMultifile.additionalFiles) {
           additionalFiles.push(...claudeMultifile.additionalFiles);
@@ -28833,7 +29757,7 @@ var init_grok = __esm({
         });
         const additionalFiles = [];
         if (claudeFull.path !== "AGENTS.md") {
-          additionalFiles.push({ ...claudeFull, additionalFiles: void 0 });
+          additionalFiles.push({ ...claudeFull, additionalFiles: void 0, warnings: void 0 });
         }
         if (claudeFull.additionalFiles) {
           additionalFiles.push(
@@ -29341,7 +30265,7 @@ function formatMigrationHint(detection) {
   lines.push("");
   lines.push("   These can be migrated to PromptScript for unified management.");
   lines.push("   Run: prs migrate");
-  lines.push("   See: https://getpromptscript.dev/latest/guides/ai-migration-best-practices");
+  lines.push("   See: https://getpromptscript.dev/guides/ai-migration-best-practices");
   return lines;
 }
 var PROMPTSCRIPT_MARKERS, INSTRUCTION_FILES, FILE_TOOL_NAMES, AI_TOOL_PATTERNS, INSTRUCTION_DIRECTORY_PATTERNS;
@@ -33577,7 +34501,7 @@ import { pathToFileURL as pathToFileURL2 } from "node:url";
 // packages/cli/package.json
 var package_default = {
   name: "@promptscript/cli",
-  version: "1.20.0",
+  version: "1.21.0",
   description: "CLI for PromptScript - standardize AI instructions across GitHub Copilot, Claude, Cursor and other AI tools",
   keywords: [
     "cli",
@@ -33629,12 +34553,12 @@ var package_default = {
     commander: "^15.0.0",
     minimatch: "^10.2.6",
     ora: "^9.4.1",
-    prettier: "^3.9.8",
+    prettier: "^3.9.9",
     yaml: "^2.9.1"
   },
   devDependencies: {
     "@codecov/bundle-analyzer": "^2.0.1",
-    memfs: "^4.78.1"
+    memfs: "^4.79.0"
   }
 };
 
@@ -36977,7 +37901,7 @@ function parseYamlFrontmatter(frontmatter, sourceFile) {
   if (document.contents === null) {
     return { fields: {}, fieldLocations, fieldItemLocations, fieldValueLocations };
   }
-  if (!isRecord5(value)) {
+  if (!isRecord6(value)) {
     throw frontmatterError(
       "top-level frontmatter value must be a YAML mapping",
       sourceFile,
@@ -37135,7 +38059,7 @@ function enforceFrontmatterLimits(value, sourceFile, frontmatter, depth = 0, sta
     }
   }
 }
-function isRecord5(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function createSafeRecord() {
@@ -37278,7 +38202,7 @@ function parseParamsField(fields, sourceFile, location) {
   if (!Object.hasOwn(fields, "params")) return void 0;
   const value = fields["params"];
   if (value === null) return [];
-  if (!isRecord5(value)) {
+  if (!isRecord6(value)) {
     throw frontmatterError(
       'field "params" must be a mapping of parameter names',
       sourceFile,
@@ -37294,7 +38218,7 @@ function parseParamsField(fields, sourceFile, location) {
         location
       );
     }
-    if (!isRecord5(definition)) {
+    if (!isRecord6(definition)) {
       throw frontmatterError(`parameter "${name}" must be a mapping`, sourceFile, location);
     }
     const paramType = parseTypedFieldType(definition, `parameter "${name}"`, sourceFile, location);
@@ -37333,7 +38257,7 @@ function parseContractFieldsField(fields, fieldName, sourceFile, location) {
   if (!Object.hasOwn(fields, fieldName)) return void 0;
   const value = fields[fieldName];
   if (value === null) return createSafeRecord();
-  if (!isRecord5(value)) {
+  if (!isRecord6(value)) {
     throw frontmatterError(
       `field "${fieldName}" must be a mapping of fields`,
       sourceFile,
@@ -37342,7 +38266,7 @@ function parseContractFieldsField(fields, fieldName, sourceFile, location) {
   }
   const result = createSafeRecord();
   for (const [name, definition] of Object.entries(value)) {
-    if (!isRecord5(definition)) {
+    if (!isRecord6(definition)) {
       throw frontmatterError(
         `${fieldName} field "${name}" must be a mapping`,
         sourceFile,
@@ -37446,7 +38370,7 @@ function toPromptValue(value, context, sourceFile, location) {
   if (Array.isArray(value)) {
     return value.map((item) => toPromptValue(item, context, sourceFile, location));
   }
-  if (isRecord5(value)) {
+  if (isRecord6(value)) {
     const result = createSafeRecord();
     for (const [key, item] of Object.entries(value)) {
       result[key] = toPromptValue(item, context, sourceFile, location);
@@ -37472,7 +38396,7 @@ function readOptionalStringFromRecord(record, field, context, sourceFile, locati
 function parseMetadataField(fields, sourceFile, location, valueLocations) {
   if (!Object.hasOwn(fields, "metadata")) return void 0;
   const value = fields["metadata"];
-  if (!isRecord5(value)) {
+  if (!isRecord6(value)) {
     throw frontmatterError('field "metadata" must be a mapping', sourceFile, location);
   }
   const metadata = createSafeRecord();
@@ -41537,7 +42461,7 @@ function createResolutionContext() {
     parsedFiles: /* @__PURE__ */ new Map()
   };
 }
-function isRecord6(value) {
+function isRecord7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function collectDependencyPaths(value, dependencies) {
@@ -41547,9 +42471,9 @@ function collectDependencyPaths(value, dependencies) {
     }
     return;
   }
-  if (!isRecord6(value)) return;
+  if (!isRecord7(value)) return;
   const loc = value["loc"];
-  if (isRecord6(loc) && typeof loc["file"] === "string") {
+  if (isRecord7(loc) && typeof loc["file"] === "string") {
     const file = loc["file"];
     if (isAbsolute7(file)) dependencies.add(file);
   }
@@ -46921,7 +47845,7 @@ var VALID_KINDS = [
   "registry-allowlist"
 ];
 var VALID_SEVERITIES = ["error", "warning"];
-function isRecord7(value) {
+function isRecord8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isStringArray(value) {
@@ -46998,7 +47922,7 @@ function validateRegistryAllowlist(raw, name) {
 }
 function parseOnePolicy(raw, index, seenNames) {
   const errors = [];
-  if (!isRecord7(raw)) {
+  if (!isRecord8(raw)) {
     errors.push(`Policy at index ${index}: must be an object`);
     return { policy: null, errors };
   }
@@ -47051,15 +47975,15 @@ function parsePolicies(input2) {
 }
 
 // packages/validator/src/policy/evaluator.ts
-function isRecord8(value) {
+function isRecord9(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isLayerTraceEntry(value) {
-  if (!isRecord8(value)) return false;
+  if (!isRecord9(value)) return false;
   return typeof value["property"] === "string" && typeof value["source"] === "string" && typeof value["strategy"] === "string" && typeof value["action"] === "string";
 }
 function isComposedFromEntry(value) {
-  if (!isRecord8(value)) return false;
+  if (!isRecord9(value)) return false;
   return typeof value["source"] === "string" && typeof value["phase"] === "string";
 }
 function getLayerTrace(skill) {
@@ -47167,7 +48091,7 @@ function evaluatePolicies(policies, ast) {
   const content = skillsBlock.content;
   const violations = [];
   for (const [skillName, skillValue] of Object.entries(content.properties)) {
-    if (!isRecord8(skillValue)) continue;
+    if (!isRecord9(skillValue)) continue;
     const skill = skillValue;
     const baseSource = typeof skill["__baseSource"] === "string" ? skill["__baseSource"] : null;
     for (const policy of policies) {
@@ -48209,7 +49133,7 @@ function isShortcutObject(value) {
 function isShortcutNameConflict(existing, blockName, sourceName) {
   return existing.sourceName !== sourceName || existing.blockName === blockName;
 }
-function validateShortcutValues(ctx, block, normalizedNames, targetNames) {
+function validateShortcutValues(ctx, block, normalizedNames, targetNames2) {
   if (block.content.type !== "ObjectContent") return;
   for (const [name, value] of Object.entries(block.content.properties)) {
     const normalizedName = name.replace(/^\/+/, "");
@@ -48229,7 +49153,7 @@ function validateShortcutValues(ctx, block, normalizedNames, targetNames) {
       });
     }
     const targetName = normalizedName.toLowerCase().replace(/\s+/g, "-");
-    const existingTargetName = targetNames.get(targetName);
+    const existingTargetName = targetNames2.get(targetName);
     if (!hasNormalizedConflict && existingTargetName && isShortcutNameConflict(existingTargetName, block.name, name)) {
       ctx.report({
         message: `@${block.name} entry "${name}" resolves to the same target-normalized file name as @${existingTargetName.blockName} entry "${existingTargetName.sourceName}".`,
@@ -48238,7 +49162,7 @@ function validateShortcutValues(ctx, block, normalizedNames, targetNames) {
         severity: "error"
       });
     } else if (!existingTargetName) {
-      targetNames.set(targetName, {
+      targetNames2.set(targetName, {
         blockName: block.name,
         sourceName: name
       });
@@ -48386,6 +49310,108 @@ var importExcludes = {
   }
 };
 
+// packages/validator/src/rules/valid-model-reference.ts
+init_src();
+var MODEL_FIELDS = {
+  agents: { label: "Agent", fields: ["model", "specModel"] },
+  skills: { label: "Skill", fields: ["model"] }
+};
+function blockEntries2(block) {
+  if (block.content.type !== "ObjectContent" && block.content.type !== "MixedContent") return [];
+  return Object.entries(block.content.properties).flatMap(
+    ([name, value]) => value && typeof value === "object" && !Array.isArray(value) ? [[name, value]] : []
+  );
+}
+function collectReferences(ctx) {
+  const references = [];
+  for (const block of ctx.ast.blocks) {
+    const spec = Object.hasOwn(MODEL_FIELDS, block.name) ? MODEL_FIELDS[block.name] : void 0;
+    if (!spec) continue;
+    for (const [name, entry] of blockEntries2(block)) {
+      for (const field of spec.fields) {
+        const value = entry[field];
+        if (typeof value === "string" && value.trim().length > 0) {
+          references.push({
+            owner: `${spec.label} "${name}"`,
+            field,
+            value: value.trim(),
+            location: block.loc
+          });
+        }
+      }
+    }
+  }
+  return references;
+}
+var PROFILES_HINT = "or declare it under models.profiles in promptscript.yaml";
+var MODELS_DOC_LINK = "https://getpromptscript.dev/reference/models/";
+function readSupportedModels(config, catalog) {
+  if (!Array.isArray(config?.supported)) return void 0;
+  const entries = config.supported.filter((entry) => typeof entry === "string");
+  return { entries, set: resolveModelSet(entries, catalog) };
+}
+function reportProfileIssues(ctx, catalog) {
+  for (const issue of validateModelCatalog(catalog.profiles)) {
+    ctx.report({
+      message: `models.profiles: ${issue}`,
+      suggestion: "Update the profile under models.profiles in promptscript.yaml."
+    });
+  }
+}
+function reportLifecycle(ctx, label, location, profile, catalog) {
+  if (profile.status !== "retired" && profile.status !== "deprecated") return;
+  const replacement = catalog.getReplacement(profile.id);
+  ctx.report({
+    message: `${label} resolves to ${profile.displayName}, which is ${profile.status}`,
+    location,
+    suggestion: replacement ? `Switch to ${replacement.id} (${replacement.displayName}).` : "Switch to a current model."
+  });
+}
+function checkReference(ctx, reference, catalog, supported) {
+  const label = `${reference.owner}: ${reference.field} "${reference.value}"`;
+  const resolution = catalog.resolve(reference.value);
+  if (!resolution) {
+    if (supported) {
+      ctx.report({
+        message: `${label} is not in the model catalog`,
+        location: reference.location,
+        suggestion: `Use a model from models.supported, ${PROFILES_HINT}. See the model list: ${MODELS_DOC_LINK}`
+      });
+    }
+    return;
+  }
+  if (resolution.kind === "inherit") return;
+  reportLifecycle(ctx, label, reference.location, resolution.profile, catalog);
+  if (supported && !isInModelSet(resolution, supported.set)) {
+    ctx.report({
+      message: `${label} is outside the supported model set`,
+      location: reference.location,
+      suggestion: `Use one of: ${supported.entries.join(", ")}; or add it to models.supported.`
+    });
+  }
+}
+var validModelReference = {
+  id: "PS041",
+  name: "valid-model-reference",
+  description: "Model references must name served models from the project model set",
+  defaultSeverity: "warning",
+  validate: (ctx) => {
+    const config = ctx.config.models;
+    const catalog = getModelCatalog(config);
+    const supported = readSupportedModels(config, catalog);
+    if (config?.profiles !== void 0) reportProfileIssues(ctx, catalog);
+    for (const entry of supported?.set.unknown ?? []) {
+      ctx.report({
+        message: `models.supported entry "${entry}" is not in the model catalog`,
+        suggestion: `Use a catalog model id or alias, ${PROFILES_HINT}. See the model list: ${MODELS_DOC_LINK}`
+      });
+    }
+    for (const reference of collectReferences(ctx)) {
+      checkReference(ctx, reference, catalog, supported);
+    }
+  }
+};
+
 // packages/validator/src/rules/index.ts
 var allRules = [
   // Required meta rules (PS001, PS002)
@@ -48457,6 +49483,8 @@ var allRules = [
   agentNamespaces,
   // Import validation excludes bound to lockfile commits (PS040)
   importExcludes,
+  // Valid model references (PS041)
+  validModelReference,
   // Security rules (PS010, PS011, PS012, PS013, PS014)
   suspiciousUrls,
   authorityInjection,
@@ -48857,8 +49885,13 @@ var Compiler = class _Compiler {
   constructor(options) {
     this.options = options;
     this.logger = options.logger ?? noopLogger;
+    this.models = options.validator?.models ?? options.models;
     this.resolver = new Resolver({ ...options.resolver, logger: this.logger });
-    this.validator = new Validator({ ...options.validator, logger: this.logger });
+    this.validator = new Validator({
+      ...options.validator,
+      models: this.models,
+      logger: this.logger
+    });
     this.loadedFormatters = this.loadFormatters(options.formatters);
     this.logger.debug(`Compiler initialized with ${this.loadedFormatters.length} formatters`);
   }
@@ -48868,6 +49901,9 @@ var Compiler = class _Compiler {
   validator;
   loadedFormatters;
   logger;
+  // Validation and formatting share one catalog, so PS041 and the target
+  // model mapping agree about every name.
+  models;
   resolvedDependencies = /* @__PURE__ */ new Map();
   hasExplicitResolverScope() {
     return Boolean(this.options.resolver.localPath || this.options.resolver.projectRoot);
@@ -49669,7 +50705,8 @@ var Compiler = class _Compiler {
       outputPath: config?.output,
       version: config?.version,
       prettier: prettierOptions,
-      targetConfig: config
+      targetConfig: config,
+      models: this.models
     };
     const conventionName = config?.convention;
     if (conventionName && customConventions?.[conventionName]) {
@@ -50108,11 +51145,11 @@ import { fileURLToPath } from "node:url";
 import { promisify as promisify2 } from "node:util";
 
 // packages/cli/src/runtime/runtime-info.ts
-function isRecord9(value) {
+function isRecord10(value) {
   return typeof value === "object" && value !== null;
 }
 function isDenoNamespace(value) {
-  return isRecord9(value) && isRecord9(value["build"]);
+  return isRecord10(value) && isRecord10(value["build"]);
 }
 function getDenoNamespace() {
   const denoCandidate = "Deno" in globalThis ? globalThis.Deno : void 0;
@@ -50130,7 +51167,7 @@ function getRuntimeVersion() {
   if (denoNamespace === void 0) {
     return process.versions.node;
   }
-  return isRecord9(denoNamespace.version) && typeof denoNamespace.version["deno"] === "string" ? denoNamespace.version["deno"] : "0";
+  return isRecord10(denoNamespace.version) && typeof denoNamespace.version["deno"] === "string" ? denoNamespace.version["deno"] : "0";
 }
 
 // packages/cli/src/runtime/self-invocation.ts
@@ -51835,6 +52872,9 @@ function printWarnings(warnings) {
     console.log(`Warnings (${warnings.length}):`);
     for (const warn of warnings) {
       ConsoleOutput.warning(`${warn.ruleId}: ${warn.message}`);
+      if (warn.suggestion) {
+        ConsoleOutput.muted(`suggestion: ${warn.suggestion}`);
+      }
     }
   }
 }
@@ -52013,6 +53053,7 @@ Disable one of the conflicting targets or assign a custom output path.`
       formatters: targets,
       customConventions: config.customConventions,
       prettier: prettierOptions,
+      models: config.models,
       logger,
       skillContent,
       ignoreHashes: options.ignoreHashes
@@ -52521,6 +53562,7 @@ async function validateCommand2(options) {
         policies: options.skipPolicies ? void 0 : config.policies,
         skipPolicies: options.skipPolicies
       },
+      models: config.models,
       ignoreHashes: options.ignoreHashes,
       formatters: []
       // No formatters needed for validation only
@@ -53341,6 +54383,7 @@ async function diffCommand(options) {
       formatters: targets,
       customConventions: config.customConventions,
       prettier: prettierOptions,
+      models: config.models,
       logger,
       skillContent
     });
@@ -53697,8 +54740,8 @@ async function checkCommand(_options) {
         hasErrors = true;
       }
     }
-    const targetIssues = [];
-    const targetNames = /* @__PURE__ */ new Set();
+    const targetIssues2 = [];
+    const targetNames2 = /* @__PURE__ */ new Set();
     const rootTargetValue = config.targets;
     const rootTargets = Array.isArray(rootTargetValue) ? rootTargetValue : [];
     const buildsValue = config.builds;
@@ -53706,50 +54749,50 @@ async function checkCommand(_options) {
     const appendTargetAnalysis = (location, entries) => {
       const analysis = analyzeTargetEntries(entries);
       for (const name of analysis.names) {
-        targetNames.add(name);
+        targetNames2.add(name);
       }
-      targetIssues.push(...analysis.errors.map((error) => `${location}: ${error}`));
+      targetIssues2.push(...analysis.errors.map((error) => `${location}: ${error}`));
       if (entries.length > 0 && analysis.names.length === 0 && analysis.errors.length === 0) {
-        targetIssues.push(`${location}: no enabled targets`);
+        targetIssues2.push(`${location}: no enabled targets`);
       }
     };
     if (rootTargetValue !== void 0 && !Array.isArray(rootTargetValue)) {
-      targetIssues.push("config.targets must be an array");
+      targetIssues2.push("config.targets must be an array");
     } else if (rootTargets.length > 0) {
       appendTargetAnalysis("config.targets", rootTargets);
     }
     if (buildsValue !== void 0 && (buildsValue === null || typeof buildsValue !== "object" || Array.isArray(buildsValue))) {
-      targetIssues.push("config.builds must be an object");
+      targetIssues2.push("config.builds must be an object");
     }
     for (const [buildName, profile] of builds) {
       if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
-        targetIssues.push(`config.builds.${buildName} must be an object`);
+        targetIssues2.push(`config.builds.${buildName} must be an object`);
         continue;
       }
       const profileTargetValue = profile.targets;
       if (profileTargetValue === void 0) {
         if (rootTargets.length === 0) {
-          targetIssues.push(
+          targetIssues2.push(
             `config.builds.${buildName}.targets is missing and config.targets is empty`
           );
         }
         continue;
       }
       if (!Array.isArray(profileTargetValue)) {
-        targetIssues.push(`config.builds.${buildName}.targets must be an array`);
+        targetIssues2.push(`config.builds.${buildName}.targets must be an array`);
         continue;
       }
       if (profileTargetValue.length === 0) {
-        targetIssues.push(`config.builds.${buildName}.targets is empty`);
+        targetIssues2.push(`config.builds.${buildName}.targets is empty`);
         continue;
       }
       appendTargetAnalysis(`config.builds.${buildName}.targets`, profileTargetValue);
     }
-    if (targetIssues.length > 0) {
+    if (targetIssues2.length > 0) {
       results.push({
         name: "Targets",
         status: "error",
-        message: targetIssues.join("; ")
+        message: targetIssues2.join("; ")
       });
       hasErrors = true;
     } else if (rootTargets.length === 0 && builds.length === 0) {
@@ -53763,7 +54806,7 @@ async function checkCommand(_options) {
       results.push({
         name: "Targets",
         status: "ok",
-        message: rootTargets.length === 0 ? `${targetNames.size} target(s) configured in build profiles` : `${targetNames.size} target(s) configured`
+        message: rootTargets.length === 0 ? `${targetNames2.size} target(s) configured in build profiles` : `${targetNames2.size} target(s) configured`
       });
     }
     const existingEntries = effectiveEntries.filter((entry) => existsSync18(resolve28(entry)));
@@ -53800,6 +54843,7 @@ async function checkCommand(_options) {
             ...config.validation,
             policies: config.policies
           },
+          models: config.models,
           formatters: []
         });
         for (const entry of existingEntries) {
@@ -56318,7 +57362,7 @@ function tokenizePath(path2) {
   }
   return tokens;
 }
-function isRecord10(value) {
+function isRecord11(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function readValueAtPath(ast, path2) {
@@ -56329,7 +57373,7 @@ function readValueAtPath(ast, path2) {
   if (!block) return void 0;
   let value = block.content;
   for (const token of tokens) {
-    if (token === "text" && isRecord10(value)) {
+    if (token === "text" && isRecord11(value)) {
       const contentType = value["type"];
       if (contentType === "TextContent") {
         value = value["value"];
@@ -56343,21 +57387,21 @@ function readValueAtPath(ast, path2) {
         value = value[token];
       } else if (typeof value === "string") {
         value = value[token];
-      } else if (isRecord10(value) && value["type"] === "TextContent") {
+      } else if (isRecord11(value) && value["type"] === "TextContent") {
         value = value["value"];
       } else {
         return void 0;
       }
       continue;
     }
-    if (isRecord10(value)) {
+    if (isRecord11(value)) {
       if (value["type"] === "TextContent" && token === "value") {
         value = value["value"];
       } else if (Object.hasOwn(value, token)) {
         value = value[token];
-      } else if (value["type"] === "ObjectContent" && isRecord10(value["properties"])) {
+      } else if (value["type"] === "ObjectContent" && isRecord11(value["properties"])) {
         value = value["properties"][token];
-      } else if (value["type"] === "MixedContent" && isRecord10(value["properties"])) {
+      } else if (value["type"] === "MixedContent" && isRecord11(value["properties"])) {
         value = value["properties"][token];
       } else {
         return void 0;
@@ -56398,7 +57442,7 @@ function sanitizeValue(value, options, seen = /* @__PURE__ */ new WeakSet()) {
     seen.add(value);
     return value.map((item) => sanitizeValue(item, options, seen));
   }
-  if (isRecord10(value)) {
+  if (isRecord11(value)) {
     if (seen.has(value)) return value;
     seen.add(value);
     return Object.fromEntries(