agentic-workflow-manager 3.11.0 → 3.13.0

package/dist/src/core/init/mutation-targets.js

@@ -26,6 +26,7 @@ const artifact_state_1 = require("../artifact-state");
 const paths_1 = require("../paths");
 const profile_1 = require("../profile");
 const registries_1 = require("../registries");
+const materializer_1 = require("../context/materializer");
 // Thin wrapper over install-planner.ts's `physicalTarget` (the single source
 // of truth for the dir+filename computation, including the `.toml` rename for
 // codex-agent-toml) — adapts its throw-on-unsupported contract to this
@@ -92,13 +93,14 @@ function planInitMutationTargets(params) {
     // whole tree (backupEntryFor does a recursive fs.cpSync for directory
     // targets — verified in install-transaction.ts), covering any entry that
     // repair might mutate. Broad-but-safe, per this module's own philosophy.
-    targets.add(provider.skill.global);
+    if (provider.skill.global !== null)
+        targets.add(provider.skill.global);
     // global context / AGENTS.md injection (covered by the hook for claude-code)
     const injection = provider.injection;
     if (injection) {
         if (injection.type === 'config-instructions')
             targets.add(injection.configPath);
-        if (injection.type === 'managed-agents-md')
+        if (injection.type === 'managed-agents-md' && injection.globalPath !== null)
             targets.add(injection.globalPath);
     }
     // machine-level bundle targets: baseline (dev-core) + ambient, global scope
@@ -119,6 +121,20 @@ function planInitMutationTargets(params) {
         }
         if (injection?.type === 'managed-agents-md') {
             targets.add(path_1.default.join(projectRoot, path_1.default.basename(injection.localFile)));
+            if (injection.globalPath === null) {
+                // Local-scope context injection (Cursor/Copilot — stepContextInjection,
+                // steps.ts) materializes its source content under the project root before
+                // writing it into the AGENTS.md target above; that materialized file is a
+                // real write this run can make and was previously absent from this
+                // enumeration entirely.
+                targets.add((0, materializer_1.projectContextPath)(projectRoot));
+            }
+        }
+        if (agent === 'cursor') {
+            // CodexAgentsStrategy.injectProject's redundant always-on carrier
+            // (codex-agents.ts) — written whenever agent === 'cursor', independent of
+            // the managed-agents-md branch above.
+            targets.add(path_1.default.join(projectRoot, '.cursor', 'rules', 'awm.mdc'));
         }
         let profile;
         try {

package/dist/src/core/init/provider-facts.js

@@ -127,14 +127,15 @@ function providerManagedPaths(agent) {
     if (provider.injection) {
         if (provider.injection.type === 'config-instructions')
             paths.add(provider.injection.configPath);
-        if (provider.injection.type === 'managed-agents-md')
+        if (provider.injection.type === 'managed-agents-md' && provider.injection.globalPath !== null) {
             paths.add(provider.injection.globalPath);
+        }
     }
-    if (provider.skill)
+    if (provider.skill && provider.skill.global !== null)
         paths.add(provider.skill.global);
-    if (provider.workflow)
+    if (provider.workflow && provider.workflow.global !== null)
         paths.add(provider.workflow.global);
-    if (provider.agent)
+    if (provider.agent && provider.agent.global !== null)
         paths.add(provider.agent.global);
     return Array.from(paths).sort();
 }

package/dist/src/core/init/steps.js

@@ -76,7 +76,7 @@ exports.defaultActions = {
     repairGlobalSkills: (skillsDir, registryContentDirs) => (0, skill_integrity_1.repairGlobalSkills)(skillsDir, registryContentDirs),
     injectProjectConstitution: (o) => {
         if ((0, providers_1.getInjection)(o.agent)?.type === 'managed-agents-md') {
-            return new codex_agents_1.CodexAgentsStrategy().injectProject(o.projectRoot) === 'injected' ? 'injected' : 'already';
+            return new codex_agents_1.CodexAgentsStrategy().injectProject(o.projectRoot, (0, providers_1.providerFor)(o.agent), o.agent) === 'injected' ? 'injected' : 'already';
         }
         return (0, project_constitution_inject_1.injectProjectConstitution)(o.projectRoot, o.agent);
     },
@@ -208,6 +208,8 @@ function stepGlobalSkillsRepair(d) {
     if (broken === 0)
         return ok('machine.globalSkills', 'machine', 'skipped');
     const skillsDir = (0, providers_1.providerFor)(d.agent).skill.global;
+    if (skillsDir === null)
+        return ok('machine.globalSkills', 'machine', 'skipped');
     const r = d.actions.repairGlobalSkills(skillsDir, (0, registries_2.contentRoots)());
     return ok('machine.globalSkills', 'machine', 'applied', `re-linked ${r.relinked.length}, pruned ${r.pruned.length}`);
 }
@@ -337,12 +339,24 @@ function stepContextInjection(d) {
         return ok('machine.contextInjection', 'machine', 'skipped', 'no injection mechanism');
     if (inj.type === 'cc-settings-merge')
         return ok('machine.contextInjection', 'machine', 'skipped', 'covered by hook');
+    // Providers with no global AGENTS.md-equivalent (managed-agents-md with a null
+    // globalPath — today: Copilot, and Cursor's global scope) deliver context at
+    // project scope instead.
+    const scope = inj.type === 'managed-agents-md' && inj.globalPath === null ? 'local' : 'global';
+    // d.ctx.project?.root (computed via findProjectRoot, diagnostics/context.ts) rather
+    // than raw d.cwd: mutation-targets.ts's planInitMutationTargets computes the local
+    // AGENTS.md backup target via the same findProjectRoot(cwd) call, so using d.cwd here
+    // whenever it differs from the walked-up project root (e.g. `awm init` run from a
+    // subdirectory) would write to a path the backup session never snapshotted — a failed
+    // init couldn't roll it back. Falls back to d.cwd only when there's no discovered
+    // project yet, matching this op's own pre-existing behavior in that case.
     const op = {
         agent: d.agent,
-        scope: 'global',
+        scope,
         registryRoot: d.registryRoot,
         installMethod: d.installMethod,
         profileExtensions: [],
+        projectRoot: d.ctx.project?.root ?? d.cwd,
     };
     if (d.actions.contextStatus(op) === 'injected')
         return ok('machine.contextInjection', 'machine', 'skipped');

package/dist/src/core/install-planner.js

@@ -26,7 +26,8 @@ const providers_1 = require("../providers");
 /** Resolves the single physical filesystem location an intent renders to for one agent. */
 /**
  * Resolves the physical target path + renderer for one artifact intent on one
- * agent (dir + filename, applying the `.toml` rename for `codex-agent-toml`).
+ * agent (dir + filename, applying the renderer-specific extension rename for
+ * `codex-agent-toml`/`cursor-mdc`/`copilot-instructions`).
  * Shared with `core/init/mutation-targets.ts`, which needs the exact same
  * dir/filename computation to enumerate paths before a real `awm init` run —
  * duplicating this logic there would let the two silently diverge.
@@ -36,9 +37,27 @@ function physicalTarget(intent, agent, scope, projectRoot) {
     if (!config)
         throw new Error(`${intent.type}s are not supported by ${(0, providers_1.providerFor)(agent).label}`);
     const dir = scope === 'local' ? path_1.default.join(projectRoot, config.local) : config.global;
-    const filename = config.renderer === 'codex-agent-toml'
-        ? `${path_1.default.parse(intent.installName).name}.toml`
+    if (dir === null) {
+        throw (0, providers_1.unsupportedScopeError)(intent.type, scope, (0, providers_1.providerFor)(agent).label, config.globalUnsupportedReason);
+    }
+    // Rendered targets get a provider-specific extension in place of a
+    // trailing `.md` (if any) on intent.installName, so e.g. `using-awm`
+    // (skills carry no extension) or `using-awm.md` both become
+    // `using-awm.instructions.md`, never `using-awm.md.instructions.md`.
+    // Deliberately NOT path.parse(...).name: it strips everything after the
+    // LAST dot, not just a real trailing extension — a skill literally named
+    // `v1.2-migration` would silently truncate to `v1.mdc`, dropping
+    // `2-migration` and risking a collision with any other skill named `v1`.
+    // `.md` is the only extension a skill's installName is ever expected to
+    // carry (skills are markdown files), so stripping that literal suffix is
+    // both sufficient and precise.
+    const baseName = intent.installName.endsWith('.md')
+        ? intent.installName.slice(0, -'.md'.length)
         : intent.installName;
+    const filename = config.renderer === 'codex-agent-toml' ? `${baseName}.toml`
+        : config.renderer === 'cursor-mdc' ? `${baseName}.mdc`
+            : config.renderer === 'copilot-instructions' ? `${baseName}.instructions.md`
+                : intent.installName;
     return { targetPath: path_1.default.join(dir, filename), renderer: config.renderer };
 }
 /**
@@ -53,7 +72,12 @@ function physicalTarget(intent, agent, scope, projectRoot) {
  */
 function skillTargetDir(agent, scope, projectRoot) {
     const config = (0, providers_1.providerFor)(agent).skill;
-    return scope === 'local' ? path_1.default.join(projectRoot, config.local) : config.global;
+    if (scope === 'local')
+        return path_1.default.join(projectRoot, config.local);
+    if (config.global === null) {
+        throw (0, providers_1.unsupportedScopeError)('skill', scope, (0, providers_1.providerFor)(agent).label, config.globalUnsupportedReason);
+    }
+    return config.global;
 }
 /**
  * Of `candidates`, the ones that share `agent`'s skill physical target at
@@ -69,7 +93,20 @@ function skillTargetDir(agent, scope, projectRoot) {
  */
 function agentsSharingSkillTarget(agent, candidates, scope, projectRoot) {
     const target = skillTargetDir(agent, scope, projectRoot);
-    return candidates.filter((candidate) => skillTargetDir(candidate, scope, projectRoot) === target);
+    return candidates.filter((candidate) => {
+        // A candidate that doesn't support this scope at all (e.g. Copilot at
+        // `global` — skillTargetDir throws) trivially can't share `agent`'s
+        // target; it just isn't part of the group. Without this guard, a
+        // Copilot in `candidates` (enabled for some OTHER, valid install) would
+        // crash this whole computation for every unrelated agent, since the
+        // exception surfaces from inside `.filter()`'s callback uncaught.
+        try {
+            return skillTargetDir(candidate, scope, projectRoot) === target;
+        }
+        catch {
+            return false;
+        }
+    });
 }
 /**
  * Skills are, today, the only artifact type where two agents' provider
@@ -85,7 +122,20 @@ function assertCompleteSharedGroup(intent, selected, enabled, scope, projectRoot
         return;
     for (const agent of selected) {
         const target = physicalTarget(intent, agent, scope, projectRoot).targetPath;
-        const group = enabled.filter((candidate) => physicalTarget(intent, candidate, scope, projectRoot).targetPath === target);
+        // Same reasoning as agentsSharingSkillTarget above: a candidate in
+        // `enabled` that doesn't support this scope (e.g. Copilot at `global`)
+        // can't be part of the shared-target group — it just isn't a
+        // candidate, not a hard failure of this assertion. Without this
+        // guard, having Copilot enabled at all would crash every OTHER
+        // agent's shared-group check.
+        const group = enabled.filter((candidate) => {
+            try {
+                return physicalTarget(intent, candidate, scope, projectRoot).targetPath === target;
+            }
+            catch {
+                return false;
+            }
+        });
         if (group.some((candidate) => !selected.includes(candidate))) {
             throw new Error(`Shared skill target cannot diverge; select the complete shared target group: ${group.join(',')}`);
         }

package/dist/src/core/install-transaction.js

@@ -31,6 +31,8 @@ const artifact_state_1 = require("./artifact-state");
 const paths_1 = require("./paths");
 const atomic_file_1 = require("./atomic-file");
 const codex_agent_1 = require("./renderers/codex-agent");
+const cursor_mdc_1 = require("./renderers/cursor-mdc");
+const copilot_instructions_1 = require("./renderers/copilot-instructions");
 const executor_1 = require("./executor");
 /**
  * The single timestamp-sanitization rule for transaction IDs, shared by
@@ -225,12 +227,25 @@ function stageRenderedFile(content, targetPath) {
     fs_1.default.writeFileSync(staged, content, 'utf8');
     return staged;
 }
+/**
+ * `cursor-mdc`/`copilot-instructions` targets are always 'skill'-type
+ * operations (providers/index.ts only assigns these renderers to a
+ * provider's `skill` ArtifactConfig), whose `sourcePath` is the skill's
+ * DIRECTORY (discovery.ts's `discoverSkills`/bundle-install.ts's
+ * `expandBundleArtifacts` both set it that way — the whole directory is what
+ * a `link` renderer symlinks), not the SKILL.md file itself. Both renderers
+ * are sourced from that directory's SKILL.md, so every call site needs this
+ * same one-line join instead of reading `op.sourcePath` directly.
+ */
+function readSkillMdSource(op) {
+    return fs_1.default.readFileSync(path_1.default.join(op.sourcePath, 'SKILL.md'), 'utf8');
+}
 /**
  * The real, filesystem-touching TransactionDeps used by applyInstallPlan by
- * default. Renders `codex-agent-toml` targets from the canonical agent
- * Markdown source at stage time; every other renderer uses the plain
- * symlink/copy staging from executor.ts. Never logs target contents or
- * environment variables.
+ * default. Renders `codex-agent-toml`/`cursor-mdc`/`copilot-instructions`
+ * targets from their respective canonical sources at stage time; every other
+ * renderer ('link') uses the plain symlink/copy staging from executor.ts.
+ * Never logs target contents or environment variables.
  */
 function defaultTransactionDeps() {
     let index = 0;
@@ -241,11 +256,17 @@ function defaultTransactionDeps() {
             if (!fs_1.default.existsSync(op.sourcePath)) {
                 throw new Error(`Source path does not exist: ${op.sourcePath}`);
             }
+            // Renders without writing anything, purely to surface parse errors
+            // before any backup/replace happens.
             if (op.renderer === 'codex-agent-toml') {
-                // Renders without writing anything, purely to surface parse errors
-                // before any backup/replace happens.
                 (0, codex_agent_1.renderCodexAgent)(fs_1.default.readFileSync(op.sourcePath, 'utf8'));
             }
+            else if (op.renderer === 'cursor-mdc') {
+                (0, cursor_mdc_1.renderCursorMdc)(readSkillMdSource(op));
+            }
+            else if (op.renderer === 'copilot-instructions') {
+                (0, copilot_instructions_1.renderCopilotInstructions)(readSkillMdSource(op));
+            }
         },
         backup(op, backupDir) {
             if (createdAt === null)
@@ -266,6 +287,14 @@ function defaultTransactionDeps() {
                 const rendered = (0, codex_agent_1.renderCodexAgent)(fs_1.default.readFileSync(op.sourcePath, 'utf8'));
                 return stageRenderedFile(rendered, op.targetPath);
             }
+            if (op.renderer === 'cursor-mdc') {
+                const rendered = (0, cursor_mdc_1.renderCursorMdc)(readSkillMdSource(op));
+                return stageRenderedFile(rendered, op.targetPath);
+            }
+            if (op.renderer === 'copilot-instructions') {
+                const rendered = (0, copilot_instructions_1.renderCopilotInstructions)(readSkillMdSource(op));
+                return stageRenderedFile(rendered, op.targetPath);
+            }
             return (0, executor_1.stageArtifact)(op.sourcePath, op.targetPath, op.method);
         },
         replace(op, staged) {
@@ -289,6 +318,26 @@ function defaultTransactionDeps() {
                 }
                 return;
             }
+            if (op.renderer === 'cursor-mdc') {
+                if (!stat.isFile()) {
+                    throw new Error(`verification failed: ${op.targetPath} is not a regular file`);
+                }
+                const content = fs_1.default.readFileSync(op.targetPath, 'utf8');
+                if (!content.startsWith('---\n') || !content.includes('alwaysApply:')) {
+                    throw new Error(`verification failed: ${op.targetPath} does not look like rendered Cursor .mdc`);
+                }
+                return;
+            }
+            if (op.renderer === 'copilot-instructions') {
+                if (!stat.isFile()) {
+                    throw new Error(`verification failed: ${op.targetPath} is not a regular file`);
+                }
+                const content = fs_1.default.readFileSync(op.targetPath, 'utf8');
+                if (!content.startsWith('---\n') || !content.includes('applyTo:')) {
+                    throw new Error(`verification failed: ${op.targetPath} does not look like rendered Copilot instructions`);
+                }
+                return;
+            }
             if (op.method === 'symlink' && !stat.isSymbolicLink()) {
                 throw new Error(`verification failed: ${op.targetPath} is not a symlink`);
             }

package/dist/src/core/provider-artifacts.js

@@ -30,7 +30,7 @@ function scanLegacyArtifacts(agents, scope) {
             if (!config)
                 continue;
             const dir = config[scope];
-            if (!fs_1.default.existsSync(dir))
+            if (dir === null || !fs_1.default.existsSync(dir))
                 continue;
             for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
                 const fullPath = path_1.default.join(dir, entry.name);

package/dist/src/core/renderers/copilot-instructions.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCopilotInstructions = renderCopilotInstructions;
+// src/core/renderers/copilot-instructions.ts
+//
+// Renders a SKILL.md source into GitHub Copilot's `.instructions.md` format.
+// Copilot's instructions format is fundamentally file-glob-triggered
+// (`applyTo` matches file paths against the current edit), which doesn't map
+// cleanly onto AWM's trigger-phrase-based skill activation — a real format
+// mismatch this task cannot fully resolve (D4: this whole tier is "context
+// read, not enforced", not runtime-gated the way Claude Code's own skill
+// invocation is). `applyTo: "**"` (match every file) is the practical
+// default: it keeps the skill's guidance always present in Copilot's context
+// rather than guessing a file-type restriction that doesn't correspond to
+// anything in the skill's actual metadata. A future task revisiting this
+// tier should start from this note, not rediscover the mismatch.
+const skill_source_1 = require("./skill-source");
+function renderCopilotInstructions(source) {
+    const { body } = (0, skill_source_1.parseSkillSource)(source);
+    return [
+        '---',
+        'applyTo: "**"',
+        '---',
+        '',
+        body,
+        '',
+    ].join('\n');
+}

package/dist/src/core/renderers/cursor-mdc.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCursorMdc = renderCursorMdc;
+// src/core/renderers/cursor-mdc.ts
+//
+// Renders a SKILL.md source into Cursor's `.mdc` rule format. Per this
+// session's D4 correction note (docs/plans/2026-08-07-team-rollout-hardening-design.md),
+// Cursor's current rule frontmatter has three keys: `description`, `globs`,
+// `alwaysApply`. For an individual skill rule (not the Task 4.2 always-on
+// `awm.mdc` context carrier), the correct activation mode is "Agent
+// Requested": `description` set to the skill's own description (so Cursor
+// can decide relevance), `globs` left blank, `alwaysApply: false` — letting
+// Cursor pull the skill in contextually instead of force-loading every
+// installed skill's full content into every request.
+const skill_source_1 = require("./skill-source");
+// YAML plain scalars break on a bare colon-followed-by-space (parsed as a
+// mapping), a `#` preceded by whitespace ANYWHERE in the string — not just
+// at the start — (starts a comment, silently truncating everything after
+// it), a leading YAML-special indicator character, an embedded double
+// quote, or an embedded control/null/DEL byte (invalid in a YAML plain
+// scalar regardless of position, and would otherwise be emitted unquoted
+// straight into the frontmatter) — the same class of problem tomlString/
+// escapeControlChars (codex-agent.ts) guard against for TOML, adapted to
+// YAML's own rules. JSON.stringify produces a YAML-1.1/1.2-compatible
+// double-quoted scalar (YAML's double-quoted flow scalar is a superset of
+// JSON string syntax), so it doubles as the escaping/quoting mechanism once
+// quoting is needed — it \u-escapes \x00-\x1F, but NOT \x7F (DEL is not in
+// JSON's own list of characters requiring escape), so yamlString below
+// escapes that one byte itself after JSON.stringify runs.
+const YAML_UNSAFE = /:(\s|$)|(?:^|\s)#|^[\s\-?:,[\]{}#&*!|>'"%@`]|"|[\x00-\x1f\x7f]/;
+function yamlString(value) {
+    if (value !== value.trim() || value === '' || YAML_UNSAFE.test(value)) {
+        return JSON.stringify(value).replace(/\x7f/g, '\\u007f');
+    }
+    return value;
+}
+function renderCursorMdc(source) {
+    const { description, body } = (0, skill_source_1.parseSkillSource)(source);
+    return [
+        '---',
+        `description: ${yamlString(description)}`,
+        'globs:',
+        'alwaysApply: false',
+        '---',
+        '',
+        body,
+        '',
+    ].join('\n');
+}

package/dist/src/core/renderers/skill-source.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSkillSource = parseSkillSource;
+// src/core/renderers/skill-source.ts
+//
+// Shared parsing for the two provider-specific skill renderers
+// (cursor-mdc.ts, copilot-instructions.ts): both are sourced from a
+// SKILL.md's frontmatter + body, the same relationship renderCodexAgent
+// (codex-agent.ts) has with its canonical agent source — transform, not
+// link. Reuses discovery.ts's `matchFrontmatterBlock` (already the single
+// source of truth for locating the frontmatter block elsewhere in this
+// codebase) rather than writing a second frontmatter parser.
+const discovery_1 = require("../discovery");
+/**
+ * Parses a raw SKILL.md source into its `description` frontmatter field and
+ * body content. Mirrors discovery.ts's `readArtifactDescription` for the
+ * quote-stripping/block-scalar handling of the `description` line, and
+ * canonical-agent.ts's `parseCanonicalAgent` for the "throw on missing
+ * required piece" discipline — a renderer should never silently embed an
+ * empty description or body.
+ */
+function parseSkillSource(source) {
+    const frontmatter = (0, discovery_1.matchFrontmatterBlock)(source);
+    if (frontmatter === null)
+        throw new Error('skill source requires YAML frontmatter');
+    const line = frontmatter.split(/\r?\n/).find((l) => /^description\s*:/.test(l));
+    if (!line)
+        throw new Error('skill source requires a non-empty description');
+    let description = line.replace(/^description\s*:/, '').trim();
+    if ((description.startsWith('"') && description.endsWith('"')) ||
+        (description.startsWith("'") && description.endsWith("'"))) {
+        description = description.slice(1, -1);
+    }
+    // A YAML block scalar indicator (`>-`, `|-`, `>`, `|`, `>+`, `|+`) means the
+    // real description text lives on the FOLLOWING indented lines, not on this
+    // line at all — treating the bare indicator as the description would embed
+    // literal "|-" into every rendered skill. Mirrors discovery.ts's
+    // readArtifactDescription, which detects the same shape and treats it as
+    // absent rather than mis-parsing it.
+    const BLOCK_INDICATORS = new Set(['>-', '>', '|-', '|', '>+', '|+']);
+    if (BLOCK_INDICATORS.has(description))
+        description = '';
+    if (!description)
+        throw new Error('skill source requires a non-empty description');
+    const bodyMatch = source.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n([\s\S]*)$/);
+    const body = bodyMatch ? bodyMatch[1].trim() : '';
+    if (!body)
+        throw new Error('skill source requires a non-empty body');
+    return { description, body };
+}

package/dist/src/core/skill-integrity.js

@@ -90,7 +90,7 @@ function reconcileAllSkillLinks(registryContentDirs) {
     const out = [];
     for (const agent of providers_1.AGENT_TARGETS) {
         const skillsDir = (0, providers_1.providerFor)(agent).skill.global;
-        if (!fs_1.default.existsSync(skillsDir))
+        if (skillsDir === null || !fs_1.default.existsSync(skillsDir))
             continue;
         out.push({ agent, result: repairGlobalSkills(skillsDir, registryContentDirs) });
     }

package/dist/src/index.js

@@ -183,6 +183,10 @@ program.command('add [name]')
                         continue;
                     }
                     const targetDir = config[scopeVal];
+                    if (targetDir === null) {
+                        skipped.push(`${artifact.name} (${currentAgent})`);
+                        continue;
+                    }
                     const finalDest = path_1.default.join(targetDir, artifact.name);
                     (0, executor_1.installArtifact)(artifact.sourcePath, finalDest, methodVal);
                     installed.push(`${artifact.name} → ${currentAgent} (${scopeVal})`);
@@ -350,6 +354,10 @@ program.command('add [name]')
                     continue;
                 }
                 const targetDir = config[scopeVal];
+                if (targetDir === null) {
+                    skipped.push(`${artifact.name} (${currentAgent})`);
+                    continue;
+                }
                 const finalDest = path_1.default.join(targetDir, artifact.name);
                 (0, executor_1.installArtifact)(artifact.sourcePath, finalDest, methodVal);
                 installed.push(`${artifact.name} → ${currentAgent} (${scopeVal})`);

package/dist/src/providers/index.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.UnsupportedRendererError = exports.AGENT_TARGETS = void 0;
 exports.isAgentTarget = isAgentTarget;
 exports.requireAgentTarget = requireAgentTarget;
+exports.unsupportedScopeError = unsupportedScopeError;
 exports.providers = providers;
 exports.providerFor = providerFor;
 exports.getTargetPath = getTargetPath;
@@ -16,7 +17,7 @@ exports.getInjection = getInjection;
 // src/providers/index.ts
 const path_1 = __importDefault(require("path"));
 const paths_1 = require("../core/paths");
-exports.AGENT_TARGETS = ['antigravity', 'opencode', 'claude-code', 'codex'];
+exports.AGENT_TARGETS = ['antigravity', 'opencode', 'claude-code', 'codex', 'cursor', 'copilot'];
 function isAgentTarget(value) {
     return typeof value === 'string' &&
         exports.AGENT_TARGETS.includes(value);
@@ -31,6 +32,14 @@ function requireAgentTarget(value) {
 class UnsupportedRendererError extends Error {
 }
 exports.UnsupportedRendererError = UnsupportedRendererError;
+/** Shared message shape for "this scope isn't supported by this provider" —
+ *  used everywhere a `null` `ArtifactConfig.global` is resolved (this file's
+ *  `getTargetPath`, and `install-planner.ts`'s `physicalTarget`/`skillTargetDir`,
+ *  which duplicate the resolution logic for their own return-shape needs). */
+function unsupportedScopeError(artifactType, scope, providerLabel, reason) {
+    return new Error(`${artifactType} ${scope} scope is not supported by ${providerLabel}` +
+        (reason ? `: ${reason}` : '.'));
+}
 function providers() {
     const home = (0, paths_1.homeDir)();
     const awm = (0, paths_1.awmHome)();
@@ -118,6 +127,44 @@ function providers() {
                 localFile: 'AGENTS.md',
             },
         },
+        cursor: {
+            label: 'Cursor',
+            skill: {
+                global: path_1.default.join(home, '.cursor/rules'),
+                local: '.cursor/rules',
+                renderer: 'cursor-mdc',
+            },
+            workflow: null,
+            agent: null,
+            injection: {
+                type: 'managed-agents-md',
+                // Cursor has no confirmed user-level/global AGENTS.md-equivalent file — its
+                // "User Rules" live inside Cursor's own app settings, not a plain file on disk
+                // (per docs research done for this task, R4 Task 4.1). Until a primary source
+                // confirms a real global path, `null` here is the honest answer, not a guess.
+                globalPath: null,
+                localFile: 'AGENTS.md',
+            },
+        },
+        copilot: {
+            label: 'Copilot',
+            skill: {
+                global: null,
+                globalUnsupportedReason: 'GitHub Copilot has no user-level skill discovery mechanism — skills must be installed per-project.',
+                local: '.github/instructions',
+                renderer: 'copilot-instructions',
+            },
+            workflow: null,
+            agent: null,
+            injection: {
+                type: 'managed-agents-md',
+                // Copilot is inherently repository-scoped — confirmed no ~/.copilot or
+                // equivalent user-level AGENTS.md file exists. Task 4.2 owns the actual
+                // runtime handling of a null globalPath (project-only injection).
+                globalPath: null,
+                localFile: 'AGENTS.md',
+            },
+        },
     };
 }
 function providerFor(agent) {
@@ -137,7 +184,11 @@ function getTargetPath(type, agent, scope) {
     const config = provider[type];
     if (!config)
         throw new Error(`${type}s are not supported by ${provider.label}.`);
-    return config[scope];
+    const targetPath = scope === 'global' ? config.global : config.local;
+    if (targetPath === null) {
+        throw unsupportedScopeError(type, scope, provider.label, config.globalUnsupportedReason);
+    }
+    return targetPath;
 }
 function getHookConfig(agent) {
     return providerFor(agent).hooks;
@@ -152,6 +203,22 @@ function getSettingsMergeHookConfig(agent) {
     }
     return config;
 }
+/**
+ * Guards callers that only know how to stage a target via a plain
+ * symlink/copy (`core/executor.ts`'s stageArtifact) — today, that means
+ * `core/provider-artifacts.ts`'s legacy single-artifact scan/preflight and
+ * `src/index.ts`'s legacy interactive `awm add` flow, neither of which goes
+ * through install-planner.ts/install-transaction.ts's render-at-stage-time
+ * pipeline. Throws for ANY non-'link' renderer, including cursor-mdc/
+ * copilot-instructions (Task 4.3): a raw, unrendered copy of a SKILL.md into
+ * `.cursor/rules/` or `.github/instructions/` is not a degraded-but-usable
+ * install the way it might first appear — it lacks the frontmatter
+ * (`alwaysApply`/`applyTo`) and filename extension (`.mdc`/`.instructions.md`)
+ * both providers require to even recognize the file, so it would silently
+ * install something neither Cursor nor Copilot ever reads. These two
+ * renderers are only reachable through commands/add.ts's proper pipeline,
+ * which never calls this function.
+ */
 function assertLinkRenderer(type, agent) {
     if (!['skill', 'workflow', 'agent'].includes(type)) {
         throw new Error(`Unknown artifact type: ${String(type)}`);