@skillcap/gdh 0.25.1 → 0.25.3

package/node_modules/@gdh/adapters/dist/index.js

@@ -54,7 +54,7 @@ export const CLAUDE_ONBOARD_SKILL_RELATIVE_PATH = ".claude/skills/gdh-onboard/SK
 export const PROJECT_MCP_RELATIVE_PATH = ".mcp.json";
 export const CURSOR_MCP_RELATIVE_PATH = ".cursor/mcp.json";
 export const CURSOR_RULE_RELATIVE_PATH = ".cursor/rules/gdh-agent.mdc";
-export const CURSOR_ONBOARD_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-onboard/SKILL.md";
+export const CURSOR_ONBOARD_COMMAND_RELATIVE_PATH = ".cursor/commands/gdh-onboard.md";
 export const CODEX_ONBOARD_SKILL_RELATIVE_PATH = ".agents/skills/gdh-onboard/SKILL.md";
 export const CLAUDE_STATUS_SKILL_RELATIVE_PATH = ".claude/skills/gdh-status/SKILL.md";
 export const CLAUDE_MIGRATE_SKILL_RELATIVE_PATH = ".claude/skills/gdh-migrate/SKILL.md";
@@ -66,11 +66,10 @@ export const CODEX_MIGRATE_SKILL_RELATIVE_PATH = ".agents/skills/gdh-migrate/SKI
 export const CODEX_CHECK_SKILL_RELATIVE_PATH = ".agents/skills/gdh-check/SKILL.md";
 export const CODEX_PREPARE_SKILL_RELATIVE_PATH = ".agents/skills/gdh-prepare/SKILL.md";
 export const CODEX_RUN_GAME_SKILL_RELATIVE_PATH = ".agents/skills/gdh-run-game/SKILL.md";
-export const CURSOR_STATUS_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-status/SKILL.md";
-export const CURSOR_MIGRATE_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-migrate/SKILL.md";
-export const CURSOR_CHECK_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-check/SKILL.md";
-export const CURSOR_PREPARE_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-prepare/SKILL.md";
-export const CURSOR_RUN_GAME_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-run-game/SKILL.md";
+export const CURSOR_STATUS_COMMAND_RELATIVE_PATH = ".cursor/commands/gdh-status.md";
+export const CURSOR_MIGRATE_COMMAND_RELATIVE_PATH = ".cursor/commands/gdh-migrate.md";
+export const CURSOR_PREPARE_COMMAND_RELATIVE_PATH = ".cursor/commands/gdh-prepare.md";
+export const CURSOR_RUN_GAME_COMMAND_RELATIVE_PATH = ".cursor/commands/gdh-run-game.md";
 // Phase 13 SELF-01: /gdh-update skill surface path constants. The rendered
 // bodies shell out to `npx -y @skillcap/gdh@latest self-update` (LITERAL
 // @latest, not the pinned version — D-10) so the NEW CLI performs the update,
@@ -79,7 +78,7 @@ export const CURSOR_RUN_GAME_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-run-game/
 // rendered bodies are version-agnostic by design.
 export const CLAUDE_UPDATE_SKILL_RELATIVE_PATH = ".claude/skills/gdh-update/SKILL.md";
 export const CODEX_UPDATE_SKILL_RELATIVE_PATH = ".agents/skills/gdh-update/SKILL.md";
-export const CURSOR_UPDATE_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-update/SKILL.md";
+export const CURSOR_UPDATE_COMMAND_RELATIVE_PATH = ".cursor/commands/gdh-update.md";
 export const CLAUDE_SCAN_SKILL_RELATIVE_PATH = ".claude/skills/gdh-scan/SKILL.md";
 export const CODEX_SCAN_SKILL_RELATIVE_PATH = ".agents/skills/gdh-scan/SKILL.md";
 export const CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH = CLAUDE_ONBOARD_SKILL_RELATIVE_PATH;
@@ -111,7 +110,36 @@ const LEGACY_CODEX_SKILL_RELATIVE_PATHS = [
     [".codex/skills/gdh-verify/SKILL.md", "gdh-verify"],
     [".codex/skills/gdh-scan/SKILL.md", "gdh-scan"],
 ];
-export const CURSOR_SCAN_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-scan/SKILL.md";
+const LEGACY_CURSOR_SKILL_RELATIVE_PATHS = [
+    [".cursor/skills/gdh-onboard/SKILL.md", "gdh-onboard"],
+    [".cursor/skills/gdh-status/SKILL.md", "gdh-status"],
+    [".cursor/skills/gdh-migrate/SKILL.md", "gdh-migrate"],
+    [".cursor/skills/gdh-update/SKILL.md", "gdh-update"],
+    [".cursor/skills/gdh-check/SKILL.md", "gdh-check"],
+    [".cursor/skills/gdh-prepare/SKILL.md", "gdh-prepare"],
+    [".cursor/skills/gdh-run-game/SKILL.md", "gdh-run-game"],
+    [".cursor/skills/gdh-verify/SKILL.md", "gdh-verify"],
+    [".cursor/skills/gdh-scan/SKILL.md", "gdh-scan"],
+];
+export const CURSOR_SCAN_COMMAND_RELATIVE_PATH = ".cursor/commands/gdh-scan.md";
+const CODEX_SKILL_RELATIVE_PATHS = [
+    path.dirname(CODEX_ONBOARD_SKILL_RELATIVE_PATH),
+    path.dirname(CODEX_STATUS_SKILL_RELATIVE_PATH),
+    path.dirname(CODEX_MIGRATE_SKILL_RELATIVE_PATH),
+    path.dirname(CODEX_UPDATE_SKILL_RELATIVE_PATH),
+    path.dirname(CODEX_PREPARE_SKILL_RELATIVE_PATH),
+    path.dirname(CODEX_RUN_GAME_SKILL_RELATIVE_PATH),
+    path.dirname(CODEX_SCAN_SKILL_RELATIVE_PATH),
+];
+const CURSOR_COMMAND_RELATIVE_PATHS = [
+    CURSOR_ONBOARD_COMMAND_RELATIVE_PATH,
+    CURSOR_STATUS_COMMAND_RELATIVE_PATH,
+    CURSOR_MIGRATE_COMMAND_RELATIVE_PATH,
+    CURSOR_UPDATE_COMMAND_RELATIVE_PATH,
+    CURSOR_PREPARE_COMMAND_RELATIVE_PATH,
+    CURSOR_RUN_GAME_COMMAND_RELATIVE_PATH,
+    CURSOR_SCAN_COMMAND_RELATIVE_PATH,
+];
 export const LOCAL_PATH_HINTS_RELATIVE_PATH = ".gdh-state/local-paths.json";
 export const CODEX_PROJECT_CONFIG_RELATIVE_PATH = ".codex/config.toml";
 export const GDH_MCP_SERVER_NAME = "gdh";
@@ -122,23 +150,23 @@ const PREVIEW_HEADER_LITERAL = "Preview (dry-run) — not applied";
 const execFile = promisify(execFileCallback);
 export async function getSupportedAgentAdaptersStatus(targetPath, options = {}) {
     const includeUserLocal = options.includeUserLocal ?? false;
-    const integrationRootPath = resolveIntegrationRootPath(targetPath, options.integrationRootPath);
-    const guidance = await getGuidanceStatus(targetPath);
-    const pinnedVersion = await resolvePinnedVersionOrNull(targetPath);
-    const projectMcp = await inspectProjectMcpSupport(targetPath, {
+    const context = await resolveAdapterTargetContext(targetPath, options.integrationRootPath);
+    const guidance = await getGuidanceStatus(context.targetPath);
+    const pinnedVersion = await resolvePinnedVersionOrNull(context.targetPath);
+    const projectMcp = await inspectProjectMcpSupport(context.targetPath, {
         includeUserLocal,
-        integrationRootPath,
+        integrationRootPath: context.integrationRootPath,
         pinnedVersion,
     });
     const [codex, claude, cursor] = await Promise.all([
-        inspectCodexAdapter(targetPath, guidance, projectMcp, pinnedVersion, {
+        inspectCodexAdapter(context.targetPath, guidance, projectMcp, pinnedVersion, {
             includeUserLocal,
         }),
-        inspectClaudeAdapter(targetPath, guidance, projectMcp, pinnedVersion),
-        inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVersion),
+        inspectClaudeAdapter(context.targetPath, guidance, projectMcp, pinnedVersion),
+        inspectCursorAdapter(context.targetPath, guidance, projectMcp, pinnedVersion),
     ]);
     return {
-        targetPath,
+        targetPath: context.targetPath,
         guidance,
         adapters: [codex, claude, cursor],
     };
@@ -146,14 +174,14 @@ export async function getSupportedAgentAdaptersStatus(targetPath, options = {})
 export async function installSupportedAgentAdapters(targetPath, options = {}) {
     const dryRun = options.dryRun ?? false;
     const requestedAgents = normalizeRequestedAgents(options.agents);
-    const integrationRootPath = resolveIntegrationRootPath(targetPath, options.integrationRootPath);
-    const status = await getSupportedAgentAdaptersStatus(targetPath, {
-        integrationRootPath,
+    const context = await resolveAdapterTargetContext(targetPath, options.integrationRootPath);
+    const status = await getSupportedAgentAdaptersStatus(context.targetPath, {
+        integrationRootPath: context.integrationRootPath,
     });
-    const pinnedVersion = await resolvePinnedVersion(targetPath);
+    const pinnedVersion = await resolvePinnedVersion(context.targetPath);
     if (!hasReadyVisibilityChain(status.guidance) && options.allowBootstrap !== true) {
         return {
-            targetPath,
+            targetPath: context.targetPath,
             dryRun,
             state: "blocked",
             summary: "The canonical GDH visibility chain is not ready, so agent reinforcement cannot be installed safely.",
@@ -163,10 +191,10 @@ export async function installSupportedAgentAdapters(targetPath, options = {}) {
             actions: [],
         };
     }
-    const actions = await planInstallActions(targetPath, status.adapters, requestedAgents, {
+    const actions = await planInstallActions(context.targetPath, status.adapters, requestedAgents, {
         user: options.user ?? false,
         devRepoPath: options.devRepoPath ?? null,
-        integrationRootPath,
+        integrationRootPath: context.integrationRootPath,
         pinnedVersion,
     });
     let appliedActions = actions;
@@ -207,7 +235,7 @@ export async function installSupportedAgentAdapters(targetPath, options = {}) {
         appliedActions = newActions;
     }
     return {
-        targetPath,
+        targetPath: context.targetPath,
         dryRun,
         state: dryRun ? "planned" : "applied",
         summary: actions.length === 0 || actions.every((action) => action.state === "unchanged")
@@ -375,7 +403,15 @@ export async function createGsdSnapshot(targetPath, options = {}) {
         guidanceResolve,
     };
 }
-export function renderCursorRule() {
+function normalizePortableRelativePath(relativePath) {
+    const normalized = relativePath.split(path.sep).join("/");
+    return normalized === "" ? "." : normalized.replace(/\/+$/, "");
+}
+export function renderCursorRule(input) {
+    const targetPrefix = input?.targetRelativePath
+        ? normalizePortableRelativePath(input.targetRelativePath)
+        : ".";
+    const prefixed = (relativePath) => targetPrefix === "." ? relativePath : `${targetPrefix}/${relativePath}`;
     return [
         "---",
         "description: GDH visibility reinforcement",
@@ -386,8 +422,8 @@ export function renderCursorRule() {
         "",
         "This GDH-managed Godot target uses GDH.",
         "Apply this rule only for files inside this Godot target or when the user explicitly asks for GDH work on this target.",
-        "Follow the canonical target-local entrypoint in [AGENTS.md](../../AGENTS.md), then load the canonical guidance index at [.gdh/guidance/README.md](../../.gdh/guidance/README.md) before substantive Godot work.",
-        "For runtime bridge usage, load [.gdh/guidance/authoring-and-validation.md](../../.gdh/guidance/authoring-and-validation.md) and follow its runtime bridge section.",
+        `Follow the canonical target-local entrypoint in [AGENTS.md](../../${prefixed("AGENTS.md")}), then load the canonical guidance index at [.gdh/guidance/README.md](../../${prefixed(".gdh/guidance/README.md")}) before substantive Godot work.`,
+        `For runtime bridge usage, load [.gdh/guidance/authoring-and-validation.md](../../${prefixed(".gdh/guidance/authoring-and-validation.md")}) and follow its runtime bridge section.`,
         "Do not duplicate or override the canonical GDH guidance chain here.",
         "",
     ].join("\n");
@@ -419,9 +455,16 @@ async function inspectProjectMcpSupport(targetPath, options) {
     const managedMcpEntry = buildManagedMcpServerEntry({
         pinnedVersion: options.pinnedVersion ?? "latest",
     });
-    const [projectFile, cursorFile, codexProjectContent, localPathHints] = await Promise.all([
+    const nestedTarget = path.resolve(targetPath) !== path.resolve(options.integrationRootPath);
+    const [projectFile, cursorFile, targetProjectFile, targetCursorFile, codexProjectContent, localPathHints,] = await Promise.all([
         inspectJsonFile(path.join(options.integrationRootPath, PROJECT_MCP_RELATIVE_PATH)),
         inspectJsonFile(path.join(options.integrationRootPath, CURSOR_MCP_RELATIVE_PATH)),
+        nestedTarget
+            ? inspectJsonFile(path.join(targetPath, PROJECT_MCP_RELATIVE_PATH))
+            : inspectJsonFile(path.join(options.integrationRootPath, PROJECT_MCP_RELATIVE_PATH)),
+        nestedTarget
+            ? inspectJsonFile(path.join(targetPath, CURSOR_MCP_RELATIVE_PATH))
+            : inspectJsonFile(path.join(options.integrationRootPath, CURSOR_MCP_RELATIVE_PATH)),
         fs
             .readFile(path.join(options.integrationRootPath, CODEX_PROJECT_CONFIG_RELATIVE_PATH), "utf8")
             .catch(() => null),
@@ -435,6 +478,8 @@ async function inspectProjectMcpSupport(targetPath, options) {
         localPathHints,
         projectFile: inspectManagedMcpFile(projectFile, enabled, PROJECT_MCP_RELATIVE_PATH, "Claude project MCP config", managedMcpEntry),
         cursorFile: inspectManagedMcpFile(cursorFile, enabled, CURSOR_MCP_RELATIVE_PATH, "Cursor project MCP config", managedMcpEntry),
+        targetProjectFile: inspectManagedMcpFile(targetProjectFile, enabled, PROJECT_MCP_RELATIVE_PATH, "target-local Claude project MCP config", managedMcpEntry),
+        targetCursorFile: inspectManagedMcpFile(targetCursorFile, enabled, CURSOR_MCP_RELATIVE_PATH, "target-local Cursor project MCP config", managedMcpEntry),
         codexProjectFile: inspectManagedCodexProjectFile(codexProjectContent, enabled, options.pinnedVersion),
         codexRegistration: options.includeUserLocal
             ? await inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, options.integrationRootPath, options.pinnedVersion)
@@ -731,34 +776,34 @@ function inspectClaudeSkillSurface(targetPath, relativePath, content, expectedCo
         }),
     ];
 }
-function inspectCursorSkillSurface(targetPath, relativePath, content, expectedContent, skillName) {
+function inspectCursorCommandSurface(targetPath, relativePath, content, expectedContent, commandName) {
     if (expectedContent === null) {
         return [
             createSurfaceStatus({
-                kind: "skill_file",
+                kind: "command_file",
                 scope: "repo",
                 targetPath,
                 relativePath,
                 present: content !== null,
                 state: "missing",
-                summary: `Cursor ${skillName} skill cannot be validated yet: no \`gdh_version\` is pinned (run \`gdh setup\` or \`gdh migrate --apply\`).`,
+                summary: `Cursor ${commandName} command cannot be validated yet: no \`gdh_version\` is pinned (run \`gdh setup\` or \`gdh migrate --apply\`).`,
                 version: null,
             }),
         ];
     }
     return [
         createSurfaceStatus({
-            kind: "skill_file",
+            kind: "command_file",
             scope: "repo",
             targetPath,
             relativePath,
             present: content !== null,
             state: content === null ? "missing" : content === expectedContent ? "ready" : "misconfigured",
             summary: content === null
-                ? `Cursor \`/${skillName}\` skill is missing and should install under .cursor/skills/.`
+                ? `Cursor \`/${commandName}\` command is missing and should install under .cursor/commands/.`
                 : content === expectedContent
-                    ? `Cursor can discover the managed \`/${skillName}\` skill.`
-                    : `Cursor \`/${skillName}\` skill exists but no longer matches the expected managed GDH skill.`,
+                    ? `Cursor can discover the managed \`/${commandName}\` command.`
+                    : `Cursor \`/${commandName}\` command exists but no longer matches the expected managed GDH command.`,
             version: null,
         }),
     ];
@@ -1012,35 +1057,47 @@ async function inspectClaudeAdapter(targetPath, guidance, projectMcp, pinnedVers
                 : projectMcp.projectFile.summary,
             version: null,
         }));
+        if (path.resolve(projectMcp.integrationRootPath) !== path.resolve(targetPath)) {
+            surfaces.push(createSurfaceStatus({
+                kind: "mcp_file",
+                scope: "repo",
+                targetPath,
+                relativePath: PROJECT_MCP_RELATIVE_PATH,
+                present: projectMcp.targetProjectFile.present,
+                state: projectMcp.targetProjectFile.state,
+                summary: projectMcp.targetProjectFile.summary,
+                version: null,
+            }));
+        }
     }
     return createAgentStatus("claude", guidance, surfaces);
 }
 async function inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVersion) {
     const absolutePath = path.join(targetPath, CURSOR_RULE_RELATIVE_PATH);
-    const onboardSkillPath = path.join(targetPath, CURSOR_ONBOARD_SKILL_RELATIVE_PATH);
+    const onboardCommandPath = path.join(targetPath, CURSOR_ONBOARD_COMMAND_RELATIVE_PATH);
     const content = await fs.readFile(absolutePath, "utf8").catch(() => null);
-    const onboardSkillContent = await fs.readFile(onboardSkillPath, "utf8").catch(() => null);
+    const onboardCommandContent = await fs.readFile(onboardCommandPath, "utf8").catch(() => null);
     const cursorStatusContent = await fs
-        .readFile(path.join(targetPath, CURSOR_STATUS_SKILL_RELATIVE_PATH), "utf8")
+        .readFile(path.join(targetPath, CURSOR_STATUS_COMMAND_RELATIVE_PATH), "utf8")
         .catch(() => null);
     const cursorMigrateContent = await fs
-        .readFile(path.join(targetPath, CURSOR_MIGRATE_SKILL_RELATIVE_PATH), "utf8")
+        .readFile(path.join(targetPath, CURSOR_MIGRATE_COMMAND_RELATIVE_PATH), "utf8")
         .catch(() => null);
     // Phase 13 Plan 13-03 deliverable — /gdh-update skill for Cursor. Inspection
     // wiring required so planSkillInstallAction sees the surface state; otherwise
     // the planner returns `unchanged` for a missing file and install becomes a
     // no-op (Plan 13-05 integration-test Rule 2 fix).
     const cursorUpdateContent = await fs
-        .readFile(path.join(targetPath, CURSOR_UPDATE_SKILL_RELATIVE_PATH), "utf8")
+        .readFile(path.join(targetPath, CURSOR_UPDATE_COMMAND_RELATIVE_PATH), "utf8")
         .catch(() => null);
     const cursorPrepareContent = await fs
-        .readFile(path.join(targetPath, CURSOR_PREPARE_SKILL_RELATIVE_PATH), "utf8")
+        .readFile(path.join(targetPath, CURSOR_PREPARE_COMMAND_RELATIVE_PATH), "utf8")
         .catch(() => null);
     const cursorRunGameContent = await fs
-        .readFile(path.resolve(targetPath, CURSOR_RUN_GAME_SKILL_RELATIVE_PATH), "utf8")
+        .readFile(path.resolve(targetPath, CURSOR_RUN_GAME_COMMAND_RELATIVE_PATH), "utf8")
         .catch(() => null);
     const cursorScanContent = await fs
-        .readFile(path.join(targetPath, CURSOR_SCAN_SKILL_RELATIVE_PATH), "utf8")
+        .readFile(path.join(targetPath, CURSOR_SCAN_COMMAND_RELATIVE_PATH), "utf8")
         .catch(() => null);
     const expectedContent = renderCursorRule();
     const version = readCursorRuleVersion(content);
@@ -1067,33 +1124,33 @@ async function inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVers
             version,
         }),
         createSurfaceStatus({
-            kind: "skill_file",
+            kind: "command_file",
             scope: "repo",
             targetPath,
-            relativePath: CURSOR_ONBOARD_SKILL_RELATIVE_PATH,
-            present: onboardSkillContent !== null,
-            state: onboardSkillContent === null
+            relativePath: CURSOR_ONBOARD_COMMAND_RELATIVE_PATH,
+            present: onboardCommandContent !== null,
+            state: onboardCommandContent === null
                 ? "missing"
                 : expectedCursorOnboardSkill === null
                     ? "missing"
-                    : onboardSkillContent === expectedCursorOnboardSkill
+                    : onboardCommandContent === expectedCursorOnboardSkill
                         ? "ready"
                         : "misconfigured",
-            summary: onboardSkillContent === null
-                ? "Cursor onboarding handoff is missing and should install `/gdh-onboard` under .cursor/skills/."
+            summary: onboardCommandContent === null
+                ? "Cursor onboarding handoff is missing and should install `/gdh-onboard` under .cursor/commands/."
                 : expectedCursorOnboardSkill === null
                     ? "Cursor onboarding handoff cannot be validated yet: no `gdh_version` is pinned (run `gdh setup` or `gdh migrate --apply`)."
-                    : onboardSkillContent === expectedCursorOnboardSkill
-                        ? "Cursor can discover the managed `/gdh-onboard` handoff skill."
-                        : "Cursor onboarding handoff exists but no longer matches the expected managed GDH skill.",
+                    : onboardCommandContent === expectedCursorOnboardSkill
+                        ? "Cursor can discover the managed `/gdh-onboard` handoff command."
+                        : "Cursor onboarding handoff exists but no longer matches the expected managed GDH command.",
             version: null,
         }),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_STATUS_SKILL_RELATIVE_PATH, cursorStatusContent, expectedCursorStatusSkill, "gdh-status"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, cursorMigrateContent, expectedCursorMigrateSkill, "gdh-migrate"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_UPDATE_SKILL_RELATIVE_PATH, cursorUpdateContent, expectedCursorUpdateSkill, "gdh-update"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_PREPARE_SKILL_RELATIVE_PATH, cursorPrepareContent, expectedCursorPrepareSkill, "gdh-prepare"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_RUN_GAME_SKILL_RELATIVE_PATH, cursorRunGameContent, expectedCursorRunGameSkill, "gdh-run-game"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_SCAN_SKILL_RELATIVE_PATH, cursorScanContent, expectedCursorScanSkill, "gdh-scan"),
+        ...inspectCursorCommandSurface(targetPath, CURSOR_STATUS_COMMAND_RELATIVE_PATH, cursorStatusContent, expectedCursorStatusSkill, "gdh-status"),
+        ...inspectCursorCommandSurface(targetPath, CURSOR_MIGRATE_COMMAND_RELATIVE_PATH, cursorMigrateContent, expectedCursorMigrateSkill, "gdh-migrate"),
+        ...inspectCursorCommandSurface(targetPath, CURSOR_UPDATE_COMMAND_RELATIVE_PATH, cursorUpdateContent, expectedCursorUpdateSkill, "gdh-update"),
+        ...inspectCursorCommandSurface(targetPath, CURSOR_PREPARE_COMMAND_RELATIVE_PATH, cursorPrepareContent, expectedCursorPrepareSkill, "gdh-prepare"),
+        ...inspectCursorCommandSurface(targetPath, CURSOR_RUN_GAME_COMMAND_RELATIVE_PATH, cursorRunGameContent, expectedCursorRunGameSkill, "gdh-run-game"),
+        ...inspectCursorCommandSurface(targetPath, CURSOR_SCAN_COMMAND_RELATIVE_PATH, cursorScanContent, expectedCursorScanSkill, "gdh-scan"),
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
@@ -1106,6 +1163,18 @@ async function inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVers
             summary: projectMcp.cursorFile.summary,
             version: null,
         }));
+        if (path.resolve(projectMcp.integrationRootPath) !== path.resolve(targetPath)) {
+            surfaces.push(createSurfaceStatus({
+                kind: "mcp_file",
+                scope: "repo",
+                targetPath,
+                relativePath: CURSOR_MCP_RELATIVE_PATH,
+                present: projectMcp.targetCursorFile.present,
+                state: projectMcp.targetCursorFile.state,
+                summary: projectMcp.targetCursorFile.summary,
+                version: null,
+            }));
+        }
     }
     return createAgentStatus("cursor", guidance, surfaces);
 }
@@ -1170,6 +1239,31 @@ function normalizeRequestedAgents(agents) {
 function resolveIntegrationRootPath(targetPath, integrationRootPath) {
     return path.resolve(integrationRootPath ?? targetPath);
 }
+async function resolveAdapterTargetContext(targetPath, integrationRootPath) {
+    const rawTargetPath = path.resolve(targetPath);
+    const projectRoot = await resolveProjectRoot(rawTargetPath);
+    const resolvedIntegrationRootPath = path.resolve(integrationRootPath ?? projectRoot ?? rawTargetPath);
+    const guidance = await getGuidanceStatus(rawTargetPath).catch(() => null);
+    if (guidance?.state === "ready") {
+        return {
+            targetPath: path.resolve(guidance.guidanceRootPath),
+            integrationRootPath: path.resolve(guidance.integrationRootPath),
+        };
+    }
+    const projectConfig = await readProjectConfig(resolvedIntegrationRootPath);
+    if (projectConfig === null || projectConfig.primaryGodotProjectPath === ".") {
+        return {
+            targetPath: projectRoot !== null && integrationRootPath === undefined
+                ? path.resolve(projectRoot)
+                : rawTargetPath,
+            integrationRootPath: resolvedIntegrationRootPath,
+        };
+    }
+    return {
+        targetPath: path.resolve(resolvedIntegrationRootPath, projectConfig.primaryGodotProjectPath),
+        integrationRootPath: resolvedIntegrationRootPath,
+    };
+}
 async function planInstallActions(targetPath, adapters, requestedAgents, options) {
     const projectMcp = await inspectProjectMcpSupport(targetPath, {
         includeUserLocal: options.user,
@@ -1198,10 +1292,15 @@ async function planInstallActions(targetPath, adapters, requestedAgents, options
             continue;
         }
         if (adapter.agent === "cursor") {
-            actions.push(...planCursorInstallActions(targetPath, adapter, options.pinnedVersion));
+            actions.push(...planCursorInstallActions(targetPath, adapter, options.pinnedVersion, options.integrationRootPath));
         }
     }
     actions.push(...planRetiredManagedSurfaceCleanupActions(targetPath));
+    if (path.resolve(options.integrationRootPath) !== path.resolve(targetPath)) {
+        actions.push(...planRetiredManagedSurfaceCleanupActions(options.integrationRootPath));
+        actions.push(...planLegacyCodexSkillCleanupActions(options.integrationRootPath, options.pinnedVersion));
+        actions.push(...planLegacyCursorSkillCleanupActions(options.integrationRootPath));
+    }
     return dedupeInstallActions(actions);
 }
 function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDevRepoPath, integrationRootPath, pinnedVersion) {
@@ -1209,6 +1308,8 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
         return [];
     }
     const actions = [];
+    const managedMcpEntry = buildManagedMcpServerEntry({ pinnedVersion });
+    const nestedTarget = path.resolve(targetPath) !== path.resolve(integrationRootPath);
     if (projectMcp.projectFile.state !== "ready") {
         actions.push(createInstallAction({
             agent,
@@ -1221,7 +1322,7 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
             summary: projectMcp.projectFile.present
                 ? "Replace the managed `gdh` MCP entry in .mcp.json while preserving any non-GDH servers."
                 : "Create .mcp.json with the managed `gdh` MCP entry.",
-            content: renderManagedMcpConfig(path.join(integrationRootPath, PROJECT_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({ pinnedVersion })),
+            content: renderManagedMcpConfig(path.join(integrationRootPath, PROJECT_MCP_RELATIVE_PATH), managedMcpEntry),
         }));
     }
     if (projectMcp.cursorFile.state !== "ready") {
@@ -1236,7 +1337,37 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
             summary: projectMcp.cursorFile.present
                 ? "Replace the managed `gdh` MCP entry in .cursor/mcp.json while preserving any non-GDH servers."
                 : "Create .cursor/mcp.json with the managed `gdh` MCP entry.",
-            content: renderManagedMcpConfig(path.join(integrationRootPath, CURSOR_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({ pinnedVersion })),
+            content: renderManagedMcpConfig(path.join(integrationRootPath, CURSOR_MCP_RELATIVE_PATH), managedMcpEntry),
+        }));
+    }
+    if (nestedTarget && projectMcp.targetProjectFile.state !== "ready") {
+        actions.push(createInstallAction({
+            agent,
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath: PROJECT_MCP_RELATIVE_PATH,
+            state: "planned",
+            mode: projectMcp.targetProjectFile.present ? "replace" : "create",
+            summary: projectMcp.targetProjectFile.present
+                ? "Replace the managed `gdh` MCP entry in target-local .mcp.json while preserving any non-GDH servers."
+                : "Create target-local .mcp.json so Claude can discover GDH when launched from the Godot target.",
+            content: renderManagedMcpConfig(path.join(targetPath, PROJECT_MCP_RELATIVE_PATH), managedMcpEntry),
+        }));
+    }
+    if (nestedTarget && projectMcp.targetCursorFile.state !== "ready") {
+        actions.push(createInstallAction({
+            agent,
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CURSOR_MCP_RELATIVE_PATH,
+            state: "planned",
+            mode: projectMcp.targetCursorFile.present ? "replace" : "create",
+            summary: projectMcp.targetCursorFile.present
+                ? "Replace the managed `gdh` MCP entry in target-local .cursor/mcp.json while preserving any non-GDH servers."
+                : "Create target-local .cursor/mcp.json so Cursor can discover GDH when opened at the Godot target.",
+            content: renderManagedMcpConfig(path.join(targetPath, CURSOR_MCP_RELATIVE_PATH), managedMcpEntry),
         }));
     }
     if (projectMcp.localPathHints.gdhDevRepoPath !== effectiveDevRepoPath) {
@@ -1296,6 +1427,35 @@ function planSkillInstallAction(agent, targetPath, adapter, relativePath, render
         content: renderFn(pinnedVersion),
     });
 }
+function planCommandInstallAction(agent, targetPath, adapter, relativePath, renderFn, commandName, pinnedVersion) {
+    const surface = adapter.surfaces.find((s) => s.relativePath === relativePath);
+    if (!surface || surface.state === "ready") {
+        return createInstallAction({
+            agent,
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath,
+            state: "unchanged",
+            mode: "unchanged",
+            summary: `The managed ${agentLabel(agent)} \`/${commandName}\` command already matches the expected GDH content.`,
+            content: renderFn(pinnedVersion),
+        });
+    }
+    return createInstallAction({
+        agent,
+        kind: "write_file",
+        scope: "repo",
+        targetPath,
+        relativePath,
+        state: "planned",
+        mode: surface.present ? "replace" : "create",
+        summary: surface.present
+            ? `Replace the existing ${agentLabel(agent)} \`/${commandName}\` command with the managed GDH command.`
+            : `Create the managed ${agentLabel(agent)} \`/${commandName}\` command.`,
+        content: renderFn(pinnedVersion),
+    });
+}
 function planHookInstallAction(agent, targetPath, adapter, relativePath, renderFn, hookName, pinnedVersion) {
     const surface = adapter.surfaces.find((entry) => entry.relativePath === relativePath);
     if (!surface || surface.state === "ready") {
@@ -1369,6 +1529,15 @@ function planCodexRepoInstallActions(targetPath, adapter, pinnedVersion, project
             content: renderManagedCodexProjectConfig(existingContent, pinnedVersion),
         }));
     }
+    if (path.resolve(integrationRootPath) !== path.resolve(targetPath)) {
+        actions.push(...planRootSymlinkActions({
+            agent: "codex",
+            integrationRootPath,
+            targetPath,
+            relativePaths: CODEX_SKILL_RELATIVE_PATHS,
+            noun: "Codex skill",
+        }));
+    }
     actions.push(...planLegacyCodexSkillCleanupActions(targetPath, pinnedVersion));
     return actions;
 }
@@ -1387,6 +1556,10 @@ function isManagedLegacyCodexSkillContent(content) {
     return (content.includes(GDH_MANAGED_AGENT_SKILL_MARKER) ||
         content.includes(LEGACY_CODEX_MANAGED_SKILL_MARKER));
 }
+function isManagedLegacyCursorSkillContent(content) {
+    return (content.includes(GDH_MANAGED_AGENT_SKILL_MARKER) ||
+        content.includes(LEGACY_CURSOR_MANAGED_SKILL_MARKER));
+}
 function isManagedLegacyClaudeCommandContent(content, skillName) {
     const slashName = skillName.replace("gdh-", "gdh:");
     return (content.includes(`name: ${slashName}`) &&
@@ -1471,6 +1644,7 @@ function planRetiredManagedSurfaceCleanupActions(targetPath) {
             summary: `Remove retired managed \`${entry.skillName}\` surface. ${entry.replacementSummary}`,
         }));
     }
+    actions.push(...planLegacyCursorSkillCleanupActions(targetPath));
     return actions;
 }
 function planLegacyCodexSkillCleanupActions(targetPath, _pinnedVersion) {
@@ -1502,6 +1676,29 @@ function planLegacyCodexSkillCleanupActions(targetPath, _pinnedVersion) {
     }
     return actions;
 }
+function planLegacyCursorSkillCleanupActions(targetPath) {
+    const actions = [];
+    for (const [relativePath, skillName] of LEGACY_CURSOR_SKILL_RELATIVE_PATHS) {
+        const absolutePath = path.join(targetPath, relativePath);
+        const content = fsSync.existsSync(absolutePath)
+            ? fsSync.readFileSync(absolutePath, "utf8")
+            : null;
+        if (content === null || !isManagedLegacyCursorSkillContent(content)) {
+            continue;
+        }
+        actions.push(createInstallAction({
+            agent: "cursor",
+            kind: "remove_file",
+            scope: "repo",
+            targetPath,
+            relativePath,
+            state: "planned",
+            mode: "delete",
+            summary: `Remove legacy managed Cursor \`/${skillName}\` skill from .cursor/skills after installing the documented .cursor/commands location.`,
+        }));
+    }
+    return actions;
+}
 function planLegacyClaudeCommandCleanupActions(targetPath) {
     const actions = [];
     for (const [relativePath, skillName] of LEGACY_CLAUDE_SKILL_COMMAND_RELATIVE_PATHS) {
@@ -1705,6 +1902,22 @@ function planDirectSymlinkAction(input) {
         expectedTarget: input.expectedTarget,
     });
 }
+function planRootSymlinkActions(input) {
+    return input.relativePaths.map((relativePath) => {
+        const rootLinkDirectory = path.dirname(path.join(input.integrationRootPath, relativePath));
+        const targetFilePath = path.join(input.targetPath, relativePath);
+        const expectedTarget = normalizePortableRelativePath(path.relative(rootLinkDirectory, targetFilePath));
+        return planDirectSymlinkAction({
+            agent: input.agent,
+            targetPath: input.integrationRootPath,
+            relativePath,
+            expectedTarget,
+            readySummary: `Root-launched ${input.noun} ${relativePath} already points to the target-local managed surface.`,
+            createSummary: `Create root-launched ${input.noun} symlink ${relativePath} to the target-local managed surface.`,
+            replaceSummary: `Replace root-launched ${input.noun} ${relativePath} with a symlink to the target-local managed surface.`,
+        });
+    });
+}
 function planDirectWriteFileAction(input) {
     const absolutePath = path.resolve(input.targetPath, input.relativePath);
     let existingContent = null;
@@ -1758,9 +1971,10 @@ function planRootClaudeAuthoringSettingsAction(integrationRootPath) {
         content: patchedSettings,
     });
 }
-function planCursorInstallActions(targetPath, adapter, pinnedVersion) {
+function planCursorInstallActions(targetPath, adapter, pinnedVersion, integrationRootPath) {
     const actions = [];
     const cursorRuleSurface = adapter.surfaces.find((surface) => surface.relativePath === CURSOR_RULE_RELATIVE_PATH);
+    const targetRelativePath = path.relative(integrationRootPath, targetPath) || ".";
     if (!cursorRuleSurface || cursorRuleSurface.state === "ready") {
         actions.push(createInstallAction({
             agent: "cursor",
@@ -1791,7 +2005,24 @@ function planCursorInstallActions(targetPath, adapter, pinnedVersion) {
             content: renderCursorRule(),
         }));
     }
-    actions.push(planSkillInstallAction("cursor", targetPath, adapter, CURSOR_ONBOARD_SKILL_RELATIVE_PATH, renderCursorOnboardSkill, "gdh-onboard", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_STATUS_SKILL_RELATIVE_PATH, renderCursorStatusSkill, "gdh-status", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, renderCursorMigrateSkill, "gdh-migrate", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_UPDATE_SKILL_RELATIVE_PATH, renderCursorUpdateSkill, "gdh-update", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_PREPARE_SKILL_RELATIVE_PATH, renderCursorPrepareSkill, "gdh-prepare", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_RUN_GAME_SKILL_RELATIVE_PATH, renderCursorRunGameSkill, "gdh-run-game", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_SCAN_SKILL_RELATIVE_PATH, renderCursorScanSkill, "gdh-scan", pinnedVersion));
+    actions.push(planCommandInstallAction("cursor", targetPath, adapter, CURSOR_ONBOARD_COMMAND_RELATIVE_PATH, renderCursorOnboardSkill, "gdh-onboard", pinnedVersion), planCommandInstallAction("cursor", targetPath, adapter, CURSOR_STATUS_COMMAND_RELATIVE_PATH, renderCursorStatusSkill, "gdh-status", pinnedVersion), planCommandInstallAction("cursor", targetPath, adapter, CURSOR_MIGRATE_COMMAND_RELATIVE_PATH, renderCursorMigrateSkill, "gdh-migrate", pinnedVersion), planCommandInstallAction("cursor", targetPath, adapter, CURSOR_UPDATE_COMMAND_RELATIVE_PATH, renderCursorUpdateSkill, "gdh-update", pinnedVersion), planCommandInstallAction("cursor", targetPath, adapter, CURSOR_PREPARE_COMMAND_RELATIVE_PATH, renderCursorPrepareSkill, "gdh-prepare", pinnedVersion), planCommandInstallAction("cursor", targetPath, adapter, CURSOR_RUN_GAME_COMMAND_RELATIVE_PATH, renderCursorRunGameSkill, "gdh-run-game", pinnedVersion), planCommandInstallAction("cursor", targetPath, adapter, CURSOR_SCAN_COMMAND_RELATIVE_PATH, renderCursorScanSkill, "gdh-scan", pinnedVersion));
+    if (path.resolve(integrationRootPath) !== path.resolve(targetPath)) {
+        actions.push(planDirectWriteFileAction({
+            agent: "cursor",
+            targetPath: integrationRootPath,
+            relativePath: CURSOR_RULE_RELATIVE_PATH,
+            content: renderCursorRule({ targetRelativePath }),
+            readySummary: "Root-launched Cursor rule already routes to the managed Godot target.",
+            createSummary: "Create root-launched Cursor rule that routes to the managed Godot target.",
+            replaceSummary: "Replace root-launched Cursor rule with target-aware links to the managed Godot target.",
+        }), ...planRootSymlinkActions({
+            agent: "cursor",
+            integrationRootPath,
+            targetPath,
+            relativePaths: CURSOR_COMMAND_RELATIVE_PATHS,
+            noun: "Cursor command",
+        }));
+    }
     return actions;
 }
 function dedupeInstallActions(actions) {
@@ -1837,7 +2068,8 @@ async function applySymlinkAction(action) {
     if (action.absolutePath === null) {
         throw new Error("Symlink install action is missing an absolute path.");
     }
-    await fs.rm(action.absolutePath, { force: true });
+    await fs.mkdir(path.dirname(action.absolutePath), { recursive: true });
+    await fs.rm(action.absolutePath, { recursive: true, force: true });
     await fs.symlink(action.expectedTarget ?? "AGENTS.md", action.absolutePath);
 }
 async function applyWriteFileAction(action) {