@kuznai/inception-engine 0.18.0 → 0.20.0

package/dist/{core → src/core}/init.js

@@ -1,42 +1,82 @@
 import { access, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
+import { AGENT_REGISTRY } from "../config/agents.js";
 import { dryRunPrefix, logger } from "../logger.js";
 import { AGENT_IDS, AgentDefinitionEntrySchema, ConfigEntrySchema, FileEntrySchema, McpServerEntrySchema, } from "../schemas/manifest.js";
+import { parseFrontmatterDocument } from "./adapters/frontmatter.js";
+import { shouldInitIncludeAgent } from "./capabilities.js";
 const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 // Ordered list: first match wins. Catch-all is applied at call site.
-const AGENT_RULES_FILE_PATTERNS = [
-    {
-        fileNames: ["claude.md", "claude-instructions.md"],
-        agents: ["claude-code"],
-    },
-    {
-        fileNames: ["agents.md", "agents-instructions.md"],
-        agents: ["codex", "opencode"],
-    },
-    {
-        fileNames: ["gemini.md", "gemini-instructions.md"],
-        agents: ["gemini-cli", "antigravity"],
-    },
-    { fileNames: ["copilot-instructions.md"], agents: ["claude-code"] },
-];
+// Derived from the registry: group agents by the filename of their global
+// agentRulesSupport path. Agents with requiresPrimary (e.g. github-copilot)
+// are excluded because they cannot be deployed independently. The
+// copilot-instructions.md convention mapping is appended explicitly since it
+// is a well-known filename convention, not derivable from a path template.
+const AGENT_RULES_FILE_PATTERNS = (() => {
+    const filenameToAgents = new Map();
+    for (const agent of AGENT_REGISTRY) {
+        if (!shouldInitIncludeAgent(agent.id, "agentRules", "global"))
+            continue;
+        const support = agent.agentRulesSupport;
+        if (support?.status !== "supported")
+            continue;
+        const filename = support.path.posix[support.path.posix.length - 1]?.toLowerCase();
+        if (!filename)
+            continue;
+        const list = filenameToAgents.get(filename) ?? [];
+        list.push(agent.id);
+        filenameToAgents.set(filename, list);
+    }
+    return [
+        ...Array.from(filenameToAgents.entries()).map(([filename, agents]) => ({
+            fileNames: [filename, filename.replace(".md", "-instructions.md")],
+            agents,
+        })),
+        // Convention mapping: copilot-instructions.md → claude-code. Copilot reads
+        // CLAUDE.md natively; this filename is a well-known convention that cannot
+        // be derived from any agent path template.
+        {
+            fileNames: ["copilot-instructions.md"],
+            agents: ["claude-code"],
+        },
+    ];
+})();
 // Conventional subdirectory names to scan one level deep for .md files.
-const AGENT_RULES_SUBDIRS = [
-    "rules",
-    "instructions",
-    ".github",
-    ".agents/rules",
-];
+const AGENT_RULES_SUBDIRS = ["rules", "instructions", ".github"];
 // Conventional subdirectories that contain agent definition files.
-// These are the agent-specific directories that each agent scans for
-// subagent/persona definitions at runtime.
-const AGENT_DEFINITION_SUBDIRS = [
-    ".claude/agents",
-    ".gemini/agents",
-    ".agents/rules",
-    ".opencode/agents",
-    ".github/agents",
-];
+// Derived from the registry: for each agent with a supported agentDefinitions
+// surface, extract the directory prefix from its posix path template.
+// Includes the legacy ".github/agents" path for backward compatibility.
+const AGENT_DEFINITION_SUBDIRS = (() => {
+    const subdirs = new Set();
+    for (const agent of AGENT_REGISTRY) {
+        const support = agent.agentDefinitionsRepoSupport;
+        if (support?.status !== "supported")
+            continue;
+        const tmpl = support.path.posix;
+        const repoIdx = tmpl.indexOf("{repo}");
+        const nameIdx = tmpl.findIndex((s) => s.includes("{name}"));
+        if (repoIdx === -1 || nameIdx === -1 || nameIdx <= repoIdx)
+            continue;
+        const dirSegs = tmpl.slice(repoIdx + 1, nameIdx);
+        if (dirSegs.length > 0)
+            subdirs.add(dirSegs.join("/"));
+    }
+    subdirs.add(".github/agents");
+    return Array.from(subdirs);
+})();
+async function hasAntigravityMcpFrontmatter(absPath) {
+    let raw;
+    try {
+        raw = await readFile(absPath, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const { attributes } = parseFrontmatterDocument(raw);
+    return (Object.hasOwn(attributes, "mcp-servers") ||
+        Object.hasOwn(attributes, "mcpServers"));
+}
 async function findSkillDirs(baseDir, dir, found) {
     let entries;
     try {
@@ -75,6 +115,7 @@ function resolveSkillName(relPath, name, namesSeen) {
     return null;
 }
 function buildSkills(found, agents) {
+    const initAgents = agents.filter((agentId) => shouldInitIncludeAgent(agentId, "skills"));
     const namesSeen = new Set();
     const skills = [];
     for (const { relPath, name } of found) {
@@ -82,7 +123,7 @@ function buildSkills(found, agents) {
         if (skillName === null)
             continue;
         namesSeen.add(skillName);
-        skills.push({ name: skillName, path: relPath, agents });
+        skills.push({ name: skillName, path: relPath, agents: initAgents });
     }
     return skills;
 }
@@ -176,7 +217,7 @@ function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
 }
 /**
  * Derives the name for an agent definition entry from its file name.
- * For GitHub Copilot's `{name}.agent.md` naming convention, strips the
+ * For GitHub Copilot's legacy `{name}.agent.md` naming convention, strips the
  * `.agent` infix in addition to the `.md` extension.
  */
 function deriveAgentDefinitionName(relPath, fileName) {
@@ -196,24 +237,56 @@ function deriveAgentDefinitionName(relPath, fileName) {
 }
 /**
  * Maps a known agent-definition subdirectory to the agent IDs that own it.
- * Returns null when the subdir is not agent-specific (fall back to all agents
- * that support agentDefinitions).
+ * Derived from the registry by matching each agent's agentDefinitionsSupport
+ * path prefix. Includes legacy mapping for ".github/agents".
+ * Returns null when the subdir is not recognized.
  */
 function agentsForDefinitionSubdir(subdir) {
-    switch (subdir) {
-        case ".claude/agents":
-            return ["claude-code"];
-        case ".gemini/agents":
-            return ["gemini-cli"];
-        case ".agents/rules":
-            return ["antigravity"];
-        case ".opencode/agents":
-            return ["opencode"];
-        case ".github/agents":
-            return ["github-copilot"];
-        default:
-            return null;
+    if (subdir === ".github/agents")
+        return ["github-copilot"];
+    const matching = [];
+    for (const agent of AGENT_REGISTRY) {
+        const support = agent.agentDefinitionsRepoSupport;
+        if (support?.status !== "supported")
+            continue;
+        const tmpl = support.path.posix;
+        const repoIdx = tmpl.indexOf("{repo}");
+        const nameIdx = tmpl.findIndex((s) => s.includes("{name}"));
+        if (repoIdx === -1 || nameIdx === -1 || nameIdx <= repoIdx)
+            continue;
+        const agentSubdir = tmpl.slice(repoIdx + 1, nameIdx).join("/");
+        if (agentSubdir === subdir)
+            matching.push(agent.id);
+    }
+    return matching.length > 0 ? matching : null;
+}
+/**
+ * Returns true when a file in a definition subdir contains MCP-specific
+ * frontmatter and should be excluded from agentDefinitions discovery. Detects
+ * this by checking whether any registered agent uses the same directory as
+ * both its definition surface and its MCP surface (currently: Antigravity's
+ * .agents/rules/).
+ */
+async function isSkippedMcpFile(subdir, absPath, relPath) {
+    const hasMcpSurfaceHere = AGENT_REGISTRY.some((agent) => {
+        const support = agent.mcpSupport;
+        if (support?.status !== "supported")
+            return false;
+        const tmpl = support.path.posix;
+        const repoIdx = tmpl.indexOf("{repo}");
+        const nameIdx = tmpl.findIndex((s) => s.includes("{name}"));
+        if (repoIdx === -1 || nameIdx === -1 || nameIdx <= repoIdx)
+            return false;
+        const prefix = tmpl.slice(repoIdx + 1, nameIdx).join("/");
+        return prefix === subdir;
+    });
+    if (!hasMcpSurfaceHere)
+        return false;
+    const isMcp = await hasAntigravityMcpFrontmatter(absPath);
+    if (isMcp) {
+        logger.warn("init", `Skipping "${relPath}" as agentDefinitions: frontmatter contains "mcp-servers" — file is an MCP surface, not an agent definition`);
     }
+    return isMcp;
 }
 async function scanDefinitionSubdir(subdir, baseDir, seen, skillDirRelPaths, agentRulesRelPaths, candidates) {
     const suggestedAgents = agentsForDefinitionSubdir(subdir) ?? [];
@@ -237,6 +310,8 @@ async function scanDefinitionSubdir(subdir, baseDir, seen, skillDirRelPaths, age
             isInsideSkillDir(relPath, skillDirRelPaths) ||
             agentRulesRelPaths.has(relPath))
             continue;
+        if (await isSkippedMcpFile(subdir, absPath, relPath))
+            continue;
         const name = deriveAgentDefinitionName(relPath, entry.name);
         if (name === null)
             continue;
@@ -255,8 +330,7 @@ async function findAgentDefinitionCandidates(baseDir, skillDirRelPaths, agentRul
 function buildAgentDefinitions(candidates, activeAgents, namesSeen) {
     const definitions = [];
     const localNamesSeen = new Set(namesSeen);
-    const definitionsCapableAgents = activeAgents.filter((id) => AGENT_REGISTRY_BY_ID[id].agentDefinitionsSupport?.status !==
-        "unsupported");
+    const definitionsCapableAgents = activeAgents.filter((id) => shouldInitIncludeAgent(id, "agentDefinitions", "repo"));
     for (const { relPath, name: rawName, suggestedAgents } of candidates) {
         // Use suggested agents (from the dir that was scanned), intersected with
         // active agents that support agentDefinitions. Fall back to all capable
@@ -281,7 +355,7 @@ function buildAgentDefinitions(candidates, activeAgents, namesSeen) {
             }
         }
         localNamesSeen.add(name);
-        definitions.push({ name, path: relPath, agents });
+        definitions.push({ name, path: relPath, agents, scope: "repo" });
     }
     return definitions;
 }
@@ -478,7 +552,7 @@ function logVerboseManifest(skills, agentRules, mcpServers, files, configs, agen
 export async function runInit(options) {
     const { directory, dryRun, force, verbose } = options;
     const agents = options.agents ?? [...AGENT_IDS];
-    const agentRulesCapableAgents = agents.filter((id) => AGENT_REGISTRY_BY_ID[id].agentRulesSupport?.status !== "unsupported");
+    const agentRulesCapableAgents = agents.filter((id) => shouldInitIncludeAgent(id, "agentRules", "global"));
     const manifestPath = path.join(directory, "inception.json");
     if (!dryRun && (await manifestExists(manifestPath)) && !force) {
         logger.error(`Error: ${manifestPath} already exists. Use --force to overwrite.`);

package/dist/src/core/merge-patch.d.ts

@@ -0,0 +1,4 @@
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+export declare function computeUndoPatch(original: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+export declare function applyMergePatch(original: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+export declare function applyUndoPatch(current: Record<string, unknown>, undoPatch: Record<string, unknown>): Record<string, unknown>;

package/dist/src/core/merge-patch.js

@@ -0,0 +1,46 @@
+export function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+export function computeUndoPatch(original, patch) {
+    const undoPatch = {};
+    for (const key of Object.keys(patch)) {
+        const patchVal = patch[key];
+        if (isPlainObject(patchVal) && isPlainObject(original[key])) {
+            undoPatch[key] = computeUndoPatch(original[key], patchVal);
+        }
+        else {
+            undoPatch[key] = key in original ? original[key] : null;
+        }
+    }
+    return undoPatch;
+}
+export function applyMergePatch(original, patch) {
+    const patched = { ...original };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete patched[key];
+        }
+        else if (isPlainObject(value) && isPlainObject(patched[key])) {
+            patched[key] = applyMergePatch(patched[key], value);
+        }
+        else {
+            patched[key] = value;
+        }
+    }
+    return patched;
+}
+export function applyUndoPatch(current, undoPatch) {
+    const restored = { ...current };
+    for (const [key, originalValue] of Object.entries(undoPatch)) {
+        if (originalValue === null) {
+            delete restored[key];
+        }
+        else if (isPlainObject(originalValue) && isPlainObject(restored[key])) {
+            restored[key] = applyUndoPatch(restored[key], originalValue);
+        }
+        else {
+            restored[key] = originalValue;
+        }
+    }
+    return restored;
+}

package/dist/{core → src/core}/ownership.d.ts

@@ -1,4 +1,4 @@
-import { type ConfigPatchRegistryEntry, type FileWriteRegistryEntry, type Registry, type RegistryEntry, type SkillDirRegistryEntry } from "../schemas/registry.ts";
+import { type ConfigPatchRegistryEntry, type FileWriteRegistryEntry, type FrontmatterEmitRegistryEntry, type Registry, type RegistryEntry, type SkillDirRegistryEntry } from "../schemas/registry.ts";
 import type { AgentId } from "../types.ts";
 export type { RegistryEntry } from "../schemas/registry.ts";
 export interface RegistryPersistence {
@@ -22,7 +22,7 @@ export type VerifyExpected = {
 };
 export declare function registryPath(home: string): string;
 export declare const defaultRegistryPersistence: RegistryPersistence;
-export type RegisterEntry = Omit<SkillDirRegistryEntry, "deployed"> | Omit<FileWriteRegistryEntry, "deployed"> | Omit<ConfigPatchRegistryEntry, "deployed">;
+export type RegisterEntry = Omit<SkillDirRegistryEntry, "deployed"> | Omit<FileWriteRegistryEntry, "deployed"> | Omit<ConfigPatchRegistryEntry, "deployed"> | Omit<FrontmatterEmitRegistryEntry, "deployed">;
 export declare function registerDeployment(home: string, targetPath: string, entry: RegisterEntry, persistence?: RegistryPersistence): Promise<void>;
 export declare function unregisterDeployment(home: string, targetPath: string, persistence?: RegistryPersistence): Promise<void>;
 export declare function lookupDeployment(home: string, targetPath: string, persistence?: RegistryPersistence): Promise<RegistryEntry | null>;

package/dist/{core → src/core}/ownership.js

@@ -40,10 +40,23 @@ async function setFilePermissions(filePath) {
 function emptyRegistry() {
     return { version: 1, deployments: {} };
 }
+function surfaceIdForEntry(entry) {
+    return entry.surfaceId ?? `${entry.kind}:${entry.agent}:${entry.skill}`;
+}
 export async function registerDeployment(home, targetPath, entry, persistence = defaultRegistryPersistence) {
     const registry = await persistence.load(home);
+    const surfaceId = surfaceIdForEntry(entry);
+    for (const migratedTarget of entry.migratedFrom ?? []) {
+        if (migratedTarget === targetPath)
+            continue;
+        const existing = registry.deployments[migratedTarget];
+        if (existing?.surfaceId === surfaceId) {
+            delete registry.deployments[migratedTarget];
+        }
+    }
     registry.deployments[targetPath] = {
         ...entry,
+        surfaceId,
         deployed: new Date().toISOString(),
     };
     await persistence.save(home, registry);

package/dist/{core → src/core}/preflight.d.ts

@@ -3,4 +3,4 @@ export interface PreflightWarning {
     kind: "policy" | "config-authority" | "info" | "precedence" | "budget";
     message: string;
 }
-export declare function runPreflight(options: CliOptions, manifest: Manifest, _home: string, detectedAgents: AgentId[]): Promise<PreflightWarning[]>;
+export declare function runPreflight(options: CliOptions, manifest: Manifest, home: string, detectedAgents: AgentId[]): Promise<PreflightWarning[]>;

package/dist/src/core/preflight.js

@@ -0,0 +1,280 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
+import { describeCapabilityConfidence, planCapabilityForDeploy, } from "./capabilities.js";
+import { resolveRuntimePaths } from "./runtime-paths.js";
+const BUDGET_WARN_BYTES = 50 * 1024; // 50 KB
+async function detectEnterpriseManagement(agentId, home) {
+    if (!AGENT_REGISTRY_BY_ID[agentId]?.enterprisePolicyDetection)
+        return null;
+    // Check for common GitHub Enterprise environment variables
+    if (process.env.GITHUB_ENTERPRISE_URL ||
+        process.env.GH_ENTERPRISE_TOKEN ||
+        process.env.GITHUB_TOKEN_TYPE === "enterprise") {
+        return "GitHub Enterprise environment variables detected. Enterprise policies may override local configurations.";
+    }
+    const { xdgConfig, localAppdata } = resolveRuntimePaths(home);
+    const configPath = process.platform === "win32"
+        ? path.join(localAppdata, "github-copilot", "hosts.json")
+        : path.join(xdgConfig, "github-copilot", "hosts.json");
+    try {
+        const content = await readFile(configPath, "utf8");
+        const hosts = JSON.parse(content);
+        const hostNames = Object.keys(hosts);
+        const enterpriseHosts = hostNames.filter((h) => h !== "github.com" && h !== "localhost");
+        if (enterpriseHosts.length > 0) {
+            return `GitHub Copilot is authenticated against enterprise host(s): ${enterpriseHosts.join(", ")}. Enterprise policies may override local configurations.`;
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT" &&
+            code !== "EACCES" &&
+            code !== "EPERM" &&
+            code !== undefined) {
+            throw err;
+        }
+    }
+    return null;
+}
+/**
+ * Reads ~/.gemini/settings.json and warns when `instructionFilename` is set
+ * to a value other than "GEMINI.md". If the override is in effect, inception-
+ * engine's agentRules deployment to GEMINI.md will be silently ignored by the
+ * agent at runtime.
+ */
+async function detectGeminiCustomInstructionFilename(home) {
+    const settingsPath = path.join(home, ".gemini", "settings.json");
+    try {
+        const raw = await readFile(settingsPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            typeof parsed.instructionFilename ===
+                "string") {
+            const configured = parsed
+                .instructionFilename;
+            if (configured !== "GEMINI.md") {
+                return {
+                    kind: "config-authority",
+                    message: `Agent "gemini-cli": settings.json sets instructionFilename to "${configured}" but inception-engine deploys agentRules to "GEMINI.md". The deployed rules file may not be loaded by the agent. Remove the override or align the deploy target.`,
+                };
+            }
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT" && code !== "EACCES" && code !== "EPERM") {
+            throw err;
+        }
+    }
+    return null;
+}
+function groupRulesByPath(rulesForAgent) {
+    const entriesByPath = new Map();
+    for (const entry of rulesForAgent ?? []) {
+        const list = entriesByPath.get(entry.path) ?? [];
+        list.push({ name: entry.name, scope: entry.scope });
+        entriesByPath.set(entry.path, list);
+    }
+    return entriesByPath;
+}
+function detectScopeOverlaps(agentId, rulesForAgent) {
+    const warnings = [];
+    const entriesByPath = groupRulesByPath(rulesForAgent);
+    for (const [path, list] of entriesByPath) {
+        const scopes = new Set(list.map((l) => l.scope));
+        if (scopes.size < 2)
+            continue;
+        const scopeList = Array.from(scopes).sort();
+        for (let i = 0; i < scopeList.length; i++) {
+            for (let j = i + 1; j < scopeList.length; j++) {
+                const entryB = list.find((l) => l.scope === scopeList[j]);
+                if (entryB) {
+                    warnings.push({
+                        kind: "precedence",
+                        message: `Agent "${agentId}" has agentRules entry "${entryB.name}" deployed to both ${scopeList[i]} and ${scopeList[j]} scope from the same source path "${path}". The file will be written to two distinct targets — verify this is intentional and not a copy-paste mistake.`,
+                    });
+                }
+            }
+        }
+    }
+    return warnings;
+}
+function detectMultipleActiveInstructionScopes(agentId, rulesForAgent) {
+    const activeScopes = Array.from(new Set((rulesForAgent ?? []).map((e) => e.scope))).sort();
+    if (activeScopes.length <= 1)
+        return [];
+    const scopeDescriptions = activeScopes
+        .map((s) => {
+        const entries = (rulesForAgent ?? []).filter((e) => e.scope === s);
+        return `${s} [${entries.map((e) => `"${e.name}"`).join(", ")}]`;
+    })
+        .join(" and ");
+    return [
+        {
+            kind: "precedence",
+            message: `Agent "${agentId}" will have multiple instruction files active simultaneously across ${activeScopes.length} scopes: ${scopeDescriptions}. All will be loaded by the agent — ensure the content is intended to stack and does not conflict.`,
+        },
+    ];
+}
+function detectInstructionPrecedence(detectedAgents, manifest) {
+    const warnings = [];
+    for (const agentId of detectedAgents) {
+        const rulesForAgent = (manifest.agentRules ?? []).filter((e) => e.agents.includes(agentId));
+        warnings.push(...detectScopeOverlaps(agentId, rulesForAgent));
+        warnings.push(...detectMultipleActiveInstructionScopes(agentId, rulesForAgent));
+    }
+    return warnings;
+}
+async function detectInstructionBudgetRisk(detectedAgents, manifest, sourceDir) {
+    const warnings = [];
+    const checkedPaths = new Set();
+    async function checkEntry(entryPath, label, agentIds) {
+        if (!agentIds.some((id) => detectedAgents.includes(id)))
+            return;
+        const sourcePath = path.resolve(sourceDir, entryPath);
+        if (checkedPaths.has(sourcePath))
+            return;
+        checkedPaths.add(sourcePath);
+        try {
+            const fileStat = await stat(sourcePath);
+            if (fileStat.size > BUDGET_WARN_BYTES) {
+                const sizeKb = (fileStat.size / 1024).toFixed(1);
+                warnings.push({
+                    kind: "budget",
+                    message: `${label} source "${entryPath}" is ${sizeKb} KB — large instruction files risk crowding out code context in the agent's context window. Consider splitting into smaller focused files.`,
+                });
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT" && code !== "EACCES" && code !== "EPERM")
+                throw err;
+            // Missing/unreadable files are silently skipped; compileAgentRuleActions
+            // will produce the proper UserError during action compilation.
+        }
+    }
+    for (const entry of manifest.agentRules ?? []) {
+        await checkEntry(entry.path, "agentRules", entry.agents);
+    }
+    for (const entry of manifest.agentDefinitions ?? []) {
+        await checkEntry(entry.path, "agentDefinitions", entry.agents);
+    }
+    return warnings;
+}
+function pushCapabilityWarning(acc, kind, message) {
+    if (acc.seen.has(`${kind}:${message}`))
+        return;
+    acc.seen.add(`${kind}:${message}`);
+    acc.warnings.push({ kind, message });
+}
+function collectCapabilityWarningsForAgent(acc, agentId, capability, entryName, targetAgents, scope) {
+    const plan = planCapabilityForDeploy({
+        agentId,
+        capability,
+        entryName,
+        targetAgentIds: targetAgents,
+        scope,
+    });
+    if (plan.outcome === "warn") {
+        pushCapabilityWarning(acc, "info", plan.warning.message);
+        return;
+    }
+    // Evaluate undocumented/planned surfaces warning
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (agent?.unsupportedSurfaces) {
+        for (const surface of agent.unsupportedSurfaces) {
+            if (surface.status === "planned") {
+                pushCapabilityWarning(acc, "info", `Agent "${agentId}": ${surface.reason ?? surface.plannedSurface}`);
+            }
+            else if (surface.status === "unsupported") {
+                pushCapabilityWarning(acc, "config-authority", `Agent "${agentId}": ${surface.reason ?? surface.schemaLabel}`);
+            }
+        }
+    }
+    if (capability === "skills")
+        return;
+    const confidence = describeCapabilityConfidence(agentId, capability, scope);
+    if (confidence.message) {
+        pushCapabilityWarning(acc, "config-authority", confidence.message);
+    }
+}
+function collectCapabilityWarningsForTargets(acc, targetAgents, capability, entryName, scope) {
+    for (const agentId of targetAgents) {
+        collectCapabilityWarningsForAgent(acc, agentId, capability, entryName, targetAgents, scope);
+    }
+}
+function collectManifestCapabilityWarnings(manifest, detectedAgents) {
+    const acc = {
+        warnings: [],
+        seen: new Set(),
+    };
+    for (const entry of manifest.skills) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "skills", entry.name);
+    }
+    for (const entry of manifest.mcpServers ?? []) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "mcpServers", entry.name, entry.scope);
+    }
+    for (const entry of manifest.agentRules ?? []) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "agentRules", entry.name, entry.scope);
+    }
+    for (const entry of manifest.permissions ?? []) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "permissions", entry.name);
+    }
+    for (const entry of manifest.agentDefinitions ?? []) {
+        collectCapabilityWarningsForTargets(acc, entry.agents.filter((agentId) => detectedAgents.includes(agentId)), "agentDefinitions", entry.name, entry.scope);
+    }
+    return acc.warnings;
+}
+function detectCapabilityPlanningWarnings(manifest, detectedAgents) {
+    return collectManifestCapabilityWarnings(manifest, detectedAgents);
+}
+async function collectAgentWarnings(agentId, manifest, home) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (!agent)
+        return [];
+    const warnings = [];
+    const skillConfidence = describeCapabilityConfidence(agentId, "skills");
+    if (skillConfidence.confidence === "implementation-only" ||
+        skillConfidence.confidence === "provisional") {
+        warnings.push({
+            kind: "config-authority",
+            message: skillConfidence.message ??
+                `Agent "${agentId}" skill support is ${skillConfidence.confidence}.`,
+        });
+    }
+    const enterpriseWarning = await detectEnterpriseManagement(agentId, home);
+    if (enterpriseWarning) {
+        warnings.push({
+            kind: "policy",
+            message: `Agent "${agentId}": ${enterpriseWarning}`,
+        });
+    }
+    else if (agent.policyNote &&
+        !agent.policyNote.includes("Organization policies may override")) {
+        warnings.push({
+            kind: "policy",
+            message: `Agent "${agentId}": ${agent.policyNote}`,
+        });
+    }
+    if (agentId === "gemini-cli") {
+        const hasGeminiRules = (manifest.agentRules ?? []).some((e) => e.agents.includes("gemini-cli"));
+        if (hasGeminiRules) {
+            const filenameWarning = await detectGeminiCustomInstructionFilename(home);
+            if (filenameWarning)
+                warnings.push(filenameWarning);
+        }
+    }
+    return warnings;
+}
+export async function runPreflight(options, manifest, home, detectedAgents) {
+    const warnings = [];
+    for (const agentId of detectedAgents) {
+        warnings.push(...(await collectAgentWarnings(agentId, manifest, home)));
+    }
+    warnings.push(...detectCapabilityPlanningWarnings(manifest, detectedAgents));
+    warnings.push(...detectInstructionPrecedence(detectedAgents, manifest));
+    warnings.push(...(await detectInstructionBudgetRisk(detectedAgents, manifest, options.directory)));
+    return warnings;
+}

package/dist/{core → src/core}/resolve.d.ts

@@ -9,4 +9,4 @@ export declare function resolveAgentSkillPathFor(agent: AgentConfig, skillName:
 export declare function resolveAgentDetectPathFor(agent: AgentConfig, home: string, platform: "posix" | "windows"): string;
 export declare function resolveAgentSkillPath(agent: AgentConfig, skillName: string, home: string): string;
 export declare function resolveAgentDetectPath(agent: AgentConfig, home: string): string;
-export declare function resolvePlaceholders(segments: string[], skillName: string, home: string, repo?: string): string;
+export declare function resolvePlaceholders(segments: string[], skillName: string, home: string, repo?: string, workspace?: string): string;

package/dist/{core → src/core}/resolve.js

@@ -86,8 +86,10 @@ export function getDeployMethod() {
 }
 export function resolveAgentSkillPathFor(agent, skillName, home, platform) {
     if (!agent.skills) {
-        throw new Error(`Agent "${agent.id}" does not have a skills deployment path. ` +
-            `Deploy skills via another agent target that covers this agent natively (e.g. claude-code for github-copilot).`);
+        const hint = agent.skillsSurfaceKind?.kind === "shared-via"
+            ? ` Deploy skills via the "${agent.skillsSurfaceKind.via}" target, which covers this agent natively.`
+            : "";
+        throw new Error(`Agent "${agent.id}" does not have a skills deployment path.${hint}`);
     }
     return resolvePlaceholders(agent.skills[platform], skillName, home);
 }
@@ -100,14 +102,15 @@ export function resolveAgentSkillPath(agent, skillName, home) {
 export function resolveAgentDetectPath(agent, home) {
     return resolveAgentDetectPathFor(agent, home, getPlatformKey());
 }
-export function resolvePlaceholders(segments, skillName, home, repo) {
+export function resolvePlaceholders(segments, skillName, home, repo, workspace) {
     const { appdata, xdgConfig } = resolveRuntimePaths(home);
     const resolved = segments.map((seg) => seg
         .replace("{home}", home)
         .replace("{name}", skillName)
         .replace("{appdata}", appdata)
         .replace("{xdg_config}", xdgConfig)
-        .replace("{repo}", repo ?? ""));
+        .replace("{repo}", repo ?? "")
+        .replace("{workspace}", workspace ?? repo ?? ""));
     const root = resolved.find((segment) => segment.length > 0) ?? home;
     return getPathApi(root).join(...resolved);
 }