@skillcap/gdh 0.4.0 → 0.5.0

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

@@ -4,7 +4,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
-import { readProjectConfig, resolveProjectRoot, readWorktreeState, resolveAuthoringStatus, } from "@gdh/authoring";
+import { readProjectConfig, resolvePinnedVersion, resolvePinnedVersionOrNull, resolveProjectRoot, readWorktreeState, resolveAuthoringStatus, } from "@gdh/authoring";
 import { GDH_AGENT_CONTRACT_VERSION, GDH_CURSOR_RULE_VERSION, GDH_GUIDANCE_INDEX_VERSION, GDH_GUIDANCE_UNIT_VERSION, GDH_MCP_LAUNCHER_VERSION, GDH_PROJECT_CONFIG_VERSION, GDH_RECIPE_SCHEMA_VERSION, GDH_RULES_SCHEMA_VERSION, GDH_SCENARIO_SCHEMA_VERSION, definePackageBoundary, resolveCurrentGdhInstall, resolveGdhProductMetadata, } from "@gdh/core";
 import { createDefaultGuidanceUnits, getGuidanceStatus, resolveGuidanceQuery, } from "@gdh/docs";
 import { inspectGuidanceAudit } from "@gdh/observability";
@@ -48,6 +48,9 @@ export const CURSOR_MIGRATE_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-migrate/SK
 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_VERIFY_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-verify/SKILL.md";
+export const CLAUDE_SCAN_COMMAND_RELATIVE_PATH = ".claude/commands/gdh/scan.md";
+export const CODEX_SCAN_SKILL_RELATIVE_PATH = ".codex/skills/gdh-scan/SKILL.md";
+export const CURSOR_SCAN_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-scan/SKILL.md";
 export const LOCAL_PATH_HINTS_RELATIVE_PATH = ".gdh-state/local-paths.json";
 export const MCP_LAUNCHER_RELATIVE_PATH = ".gdh/bin/gdh-mcp.mjs";
 export const GDH_MCP_SERVER_NAME = "gdh";
@@ -56,16 +59,18 @@ export async function getSupportedAgentAdaptersStatus(targetPath, options = {})
     const includeUserLocal = options.includeUserLocal ?? true;
     const integrationRootPath = resolveIntegrationRootPath(targetPath, options.integrationRootPath);
     const guidance = await getGuidanceStatus(targetPath);
+    const pinnedVersion = await resolvePinnedVersionOrNull(targetPath);
     const projectMcp = await inspectProjectMcpSupport(targetPath, {
         includeUserLocal,
         integrationRootPath,
+        pinnedVersion,
     });
     const [codex, claude, cursor] = await Promise.all([
-        inspectCodexAdapter(targetPath, guidance, projectMcp, {
+        inspectCodexAdapter(targetPath, guidance, projectMcp, pinnedVersion, {
             includeUserLocal,
         }),
-        inspectClaudeAdapter(targetPath, guidance, projectMcp),
-        inspectCursorAdapter(targetPath, guidance, projectMcp),
+        inspectClaudeAdapter(targetPath, guidance, projectMcp, pinnedVersion),
+        inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVersion),
     ]);
     return {
         targetPath,
@@ -80,6 +85,7 @@ export async function installSupportedAgentAdapters(targetPath, options = {}) {
     const status = await getSupportedAgentAdaptersStatus(targetPath, {
         integrationRootPath,
     });
+    const pinnedVersion = await resolvePinnedVersion(targetPath);
     if (!hasReadyVisibilityChain(status.guidance) && options.allowBootstrap !== true) {
         return {
             targetPath,
@@ -96,26 +102,41 @@ export async function installSupportedAgentAdapters(targetPath, options = {}) {
         user: options.user ?? false,
         devRepoPath: options.devRepoPath ?? null,
         integrationRootPath,
+        pinnedVersion,
     });
+    let appliedActions = actions;
     if (!dryRun) {
+        const newActions = [];
         for (const action of actions) {
             if (action.state === "unchanged") {
+                newActions.push(action);
                 continue;
             }
-            if (action.kind === "ensure_symlink") {
-                await applySymlinkAction(action);
-                continue;
-            }
-            if (action.kind === "run_command") {
-                await applyRunCommandAction(action);
-                continue;
+            try {
+                if (action.kind === "ensure_symlink") {
+                    await applySymlinkAction(action);
+                }
+                else if (action.kind === "run_command") {
+                    await applyRunCommandAction(action);
+                }
+                else if (action.command?.[0] === "write_local_hints") {
+                    await applyLocalHintsAction(action);
+                }
+                else {
+                    await applyWriteFileAction(action);
+                }
+                newActions.push({ ...action, state: "applied" });
             }
-            if (action.command?.[0] === "write_local_hints") {
-                await applyLocalHintsAction(action);
-                continue;
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                newActions.push({
+                    ...action,
+                    state: "blocked",
+                    summary: `${action.summary} (failed: ${errorMessage})`,
+                });
             }
-            await applyWriteFileAction(action);
         }
+        appliedActions = newActions;
     }
     return {
         targetPath,
@@ -129,7 +150,7 @@ export async function installSupportedAgentAdapters(targetPath, options = {}) {
         requestedAgents,
         guidance: status.guidance,
         adapters: status.adapters,
-        actions,
+        actions: appliedActions,
     };
 }
 export async function inspectProjectLifecycleCompatibility(targetPath) {
@@ -285,7 +306,7 @@ export function renderCursorRule() {
         "",
     ].join("\n");
 }
-export function renderClaudeOnboardCommand() {
+export function renderClaudeOnboardCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:onboard",
@@ -298,17 +319,17 @@ export function renderClaudeOnboardCommand() {
         "  - AskUserQuestion",
         "---",
         "<objective>",
-        "Finish the first-time GDH handoff after `gdh setup` and turn the generated GDH surface into a trustworthy starting point for real work.",
+        `Finish the first-time GDH handoff after \`npx -y @skillcap/gdh@${pinnedVersion} setup\` and turn the generated GDH surface into a trustworthy starting point for real work.`,
         "</objective>",
         "",
         "<process>",
         "Follow this order:",
         "",
-        "1. Confirm the selected target and current GDH state with `gdh status`.",
+        `1. Confirm the selected target and current GDH state with \`npx -y @skillcap/gdh@${pinnedVersion} status\`.`,
         "2. Read `.gdh/project.yaml`, `docs/agent/README.md`, and `docs/agent/00-gdh-onboarding.md` before asking for facts GDH already knows.",
-        "3. Check immediate readiness with `gdh guidance status` and `gdh target prepare --dry-run`.",
-        "4. If authoring is available, run `gdh authoring check`; if LSP matters, run `gdh lsp status`.",
-        "5. Inspect `gdh run-config list` and `gdh verification-scenario list` and call out anything draft, missing, or blocked.",
+        `3. Check immediate readiness with \`npx -y @skillcap/gdh@${pinnedVersion} guidance status\` and \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\`.`,
+        `4. If authoring is available, run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\`; if LSP matters, run \`npx -y @skillcap/gdh@${pinnedVersion} lsp status\`.`,
+        `5. Inspect \`npx -y @skillcap/gdh@${pinnedVersion} run-config list\` and \`npx -y @skillcap/gdh@${pinnedVersion} verification-scenario list\` and call out anything draft, missing, or blocked.`,
         "6. If GDH reports `godot_editor_not_configured`, explain that the Godot binary path is machine-local and offer to record `.gdh-state/local-paths.json` `godotEditorBinPath` once the human provides the local path.",
         "7. Ask the human only for narrow unresolved environment or target facts.",
         "8. End with a concise readiness summary and the exact next development step.",
@@ -318,11 +339,12 @@ export function renderClaudeOnboardCommand() {
         "- Do not start editing code during `/gdh-onboard` unless the human explicitly asks.",
         "- Prefer GDH structured surfaces over repo guesswork.",
         "- Keep the output short, operational, and specific.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
-export function renderCodexOnboardSkill() {
+export function renderCodexOnboardSkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-onboard"',
@@ -342,20 +364,20 @@ export function renderCodexOnboardSkill() {
         "</codex_skill_adapter>",
         "",
         "<objective>",
-        "Finish the first-time GDH handoff after `gdh setup` and turn the generated GDH surface into a trustworthy starting point for real work.",
+        `Finish the first-time GDH handoff after \`npx -y @skillcap/gdh@${pinnedVersion} setup\` and turn the generated GDH surface into a trustworthy starting point for real work.`,
         "</objective>",
         "",
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh status`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\``,
         "- inspect `.gdh/project.yaml`, `docs/agent/README.md`, and `docs/agent/00-gdh-onboarding.md`",
-        "- run `gdh guidance status`",
-        "- run `gdh target prepare --dry-run`",
-        "- if authoring is available, run `gdh authoring check`",
-        "- if LSP matters, run `gdh lsp status`",
-        "- run `gdh run-config list`",
-        "- run `gdh verification-scenario list`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} guidance status\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\``,
+        `- if authoring is available, run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\``,
+        `- if LSP matters, run \`npx -y @skillcap/gdh@${pinnedVersion} lsp status\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} run-config list\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verification-scenario list\``,
         "- if GDH reports `godot_editor_not_configured`, explain that the Godot binary path is machine-local and offer to record `.gdh-state/local-paths.json` `godotEditorBinPath` once the user provides it",
         "- ask only for narrow unresolved environment or target facts",
         "- finish with a concise readiness summary and the exact next development step",
@@ -365,11 +387,12 @@ export function renderCodexOnboardSkill() {
         "- Do not start editing code during `/gdh-onboard` unless the human explicitly asks.",
         "- Prefer GDH structured surfaces over repo guesswork.",
         "- Keep output short, operational, and specific.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
-export function renderCursorOnboardSkill() {
+export function renderCursorOnboardSkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-onboard",
@@ -387,20 +410,20 @@ export function renderCursorOnboardSkill() {
         "</cursor_skill_adapter>",
         "",
         "<objective>",
-        "Finish the first-time GDH handoff after `gdh setup` and turn the generated GDH surface into a trustworthy starting point for real work.",
+        `Finish the first-time GDH handoff after \`npx -y @skillcap/gdh@${pinnedVersion} setup\` and turn the generated GDH surface into a trustworthy starting point for real work.`,
         "</objective>",
         "",
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh status`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\``,
         "- inspect `.gdh/project.yaml`, `docs/agent/README.md`, and `docs/agent/00-gdh-onboarding.md`",
-        "- run `gdh guidance status`",
-        "- run `gdh target prepare --dry-run`",
-        "- if authoring is available, run `gdh authoring check`",
-        "- if LSP matters, run `gdh lsp status`",
-        "- run `gdh run-config list`",
-        "- run `gdh verification-scenario list`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} guidance status\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\``,
+        `- if authoring is available, run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\``,
+        `- if LSP matters, run \`npx -y @skillcap/gdh@${pinnedVersion} lsp status\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} run-config list\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verification-scenario list\``,
         "- if GDH reports `godot_editor_not_configured`, explain that the Godot binary path is machine-local and offer to record `.gdh-state/local-paths.json` `godotEditorBinPath` once the user provides it",
         "- ask only for narrow unresolved environment or target facts",
         "- finish with a concise readiness summary and the exact next development step",
@@ -410,12 +433,13 @@ export function renderCursorOnboardSkill() {
         "- Do not start editing code during `/gdh-onboard` unless the human explicitly asks.",
         "- Prefer GDH structured surfaces over repo guesswork.",
         "- Keep output short, operational, and specific.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
 // --- gdh-status skill renders ---
-export function renderClaudeStatusCommand() {
+export function renderClaudeStatusCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:status",
@@ -433,8 +457,8 @@ export function renderClaudeStatusCommand() {
         "<process>",
         "Follow this order:",
         "",
-        "1. Run `gdh status` and explain each readiness field.",
-        "2. Check if migration is needed with `gdh migrate`.",
+        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field.`,
+        `2. Check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\`.`,
         "3. Surface any degraded or unavailable capabilities.",
         "4. Suggest the most productive next step based on current state.",
         "</process>",
@@ -443,11 +467,12 @@ export function renderClaudeStatusCommand() {
         "- Do not start editing code.",
         "- Prefer structured GDH surfaces over repo guesswork.",
         "- Keep output short and operational.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
-export function renderCodexStatusSkill() {
+export function renderCodexStatusSkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-status"',
@@ -473,8 +498,8 @@ export function renderCodexStatusSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh status` and explain each readiness field",
-        "- check if migration is needed with `gdh migrate`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field`,
+        `- check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\``,
         "- surface any degraded or unavailable capabilities",
         "- suggest the most productive next step based on current state",
         "</process>",
@@ -483,11 +508,12 @@ export function renderCodexStatusSkill() {
         "- Do not start editing code.",
         "- Prefer structured GDH surfaces over repo guesswork.",
         "- Keep output short and operational.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
-export function renderCursorStatusSkill() {
+export function renderCursorStatusSkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-status",
@@ -511,8 +537,8 @@ export function renderCursorStatusSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh status` and explain each readiness field",
-        "- check if migration is needed with `gdh migrate`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field`,
+        `- check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\``,
         "- surface any degraded or unavailable capabilities",
         "- suggest the most productive next step based on current state",
         "</process>",
@@ -521,12 +547,123 @@ export function renderCursorStatusSkill() {
         "- Do not start editing code.",
         "- Prefer structured GDH surfaces over repo guesswork.",
         "- Keep output short and operational.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+// --- gdh-scan skill renders ---
+export function renderClaudeScanCommand(pinnedVersion) {
+    return [
+        "---",
+        "name: gdh:scan",
+        "description: Refresh inventory cache and explain persistence effect",
+        "allowed-tools:",
+        "  - Read",
+        "  - Grep",
+        "  - Glob",
+        "  - Bash",
+        "---",
+        "<objective>",
+        "Refresh the inventory cache and explain the persistence effect of the scan.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} scan\` and parse the \`persisted\` field from the envelope.`,
+        "2. Check the `mode` field: `create`, `unchanged`, `overwrite`, or `null`.",
+        "3. Explain the persistence effect; if `null`, the target is not onboarded and no disk write occurred.",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do not edit the persisted inventory directly.",
+        "- Prefer the cached inventory for status reads; re-run scan only when freshness is in question.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+export function renderCodexScanSkill(pinnedVersion) {
+    return [
+        "---",
+        'name: "gdh-scan"',
+        'description: "Refresh inventory cache and explain persistence effect"',
+        "metadata:",
+        '  short-description: "Refresh inventory cache and explain persistence effect"',
+        "---",
+        "",
+        "<codex_skill_adapter>",
+        "## Invocation",
+        "- This skill is invoked when the user says `/gdh-scan` or mentions `$gdh-scan`.",
+        "- Treat any extra user text as additional scan context.",
+        "",
+        "## User questions",
+        "- Ask only narrow follow-up questions when GDH cannot infer the missing fact safely.",
+        "- If structured user-input tooling is unavailable, ask concise plain-text questions instead.",
+        "</codex_skill_adapter>",
+        "",
+        "<objective>",
+        "Refresh the inventory cache and explain the persistence effect of the scan.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} scan\``,
+        "- parse the `persisted` field from the envelope",
+        "- check `mode`: `create`, `unchanged`, `overwrite`, or `null`",
+        "- explain the persistence effect; if `null`, explain the target is not onboarded",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do not edit the persisted inventory directly.",
+        "- Prefer the cached inventory for status reads; re-run scan only when freshness is in question.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+export function renderCursorScanSkill(pinnedVersion) {
+    return [
+        "---",
+        "name: gdh-scan",
+        'description: "Refresh inventory cache and explain persistence effect"',
+        "---",
+        "",
+        "<cursor_skill_adapter>",
+        "## Invocation",
+        "- This skill is invoked when the user says `/gdh-scan` or mentions `gdh-scan`.",
+        "- Treat any extra user text as additional scan context.",
+        "",
+        "## User questions",
+        "- Ask only narrow follow-up questions when GDH cannot infer the missing fact safely.",
+        "- Keep questions conversational and concise.",
+        "</cursor_skill_adapter>",
+        "",
+        "<objective>",
+        "Refresh the inventory cache and explain the persistence effect of the scan.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} scan\``,
+        "- parse the `persisted` field from the envelope",
+        "- check `mode`: `create`, `unchanged`, `overwrite`, or `null`",
+        "- explain the persistence effect; if `null`, explain the target is not onboarded",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do not edit the persisted inventory directly.",
+        "- Prefer the cached inventory for status reads; re-run scan only when freshness is in question.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
 // --- gdh-migrate skill renders ---
-export function renderClaudeMigrateCommand() {
+export function renderClaudeMigrateCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:migrate",
@@ -545,10 +682,10 @@ export function renderClaudeMigrateCommand() {
         "<process>",
         "Follow this order:",
         "",
-        "1. Run `gdh migrate` to preview pending migrations.",
+        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations.`,
         "2. Explain what each migration step will change and why.",
-        "3. Offer to run `gdh migrate --apply` if the user approves.",
-        "4. After apply, run `gdh status` to verify the migration succeeded.",
+        `3. Offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves.`,
+        `4. After apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded.`,
         "</process>",
         "",
         "<rules>",
@@ -559,7 +696,7 @@ export function renderClaudeMigrateCommand() {
         "",
     ].join("\n");
 }
-export function renderCodexMigrateSkill() {
+export function renderCodexMigrateSkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-migrate"',
@@ -585,10 +722,10 @@ export function renderCodexMigrateSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh migrate` to preview pending migrations",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations`,
         "- explain what each migration step will change and why",
-        "- offer to run `gdh migrate --apply` if the user approves",
-        "- after apply, run `gdh status` to verify the migration succeeded",
+        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves`,
+        `- after apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded`,
         "</process>",
         "",
         "<rules>",
@@ -599,7 +736,7 @@ export function renderCodexMigrateSkill() {
         "",
     ].join("\n");
 }
-export function renderCursorMigrateSkill() {
+export function renderCursorMigrateSkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-migrate",
@@ -623,10 +760,10 @@ export function renderCursorMigrateSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh migrate` to preview pending migrations",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations`,
         "- explain what each migration step will change and why",
-        "- offer to run `gdh migrate --apply` if the user approves",
-        "- after apply, run `gdh status` to verify the migration succeeded",
+        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves`,
+        `- after apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded`,
         "</process>",
         "",
         "<rules>",
@@ -638,7 +775,7 @@ export function renderCursorMigrateSkill() {
     ].join("\n");
 }
 // --- gdh-check skill renders ---
-export function renderClaudeCheckCommand() {
+export function renderClaudeCheckCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:check",
@@ -656,7 +793,7 @@ export function renderClaudeCheckCommand() {
         "<process>",
         "Follow this order:",
         "",
-        "1. Run `gdh authoring check`.",
+        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\`.`,
         "2. Explain each diagnostic finding with severity and provenance.",
         "3. Surface any import-state caveats or editor-side warnings.",
         "4. If issues found, suggest concrete remediation steps.",
@@ -670,7 +807,7 @@ export function renderClaudeCheckCommand() {
         "",
     ].join("\n");
 }
-export function renderCodexCheckSkill() {
+export function renderCodexCheckSkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-check"',
@@ -696,7 +833,7 @@ export function renderCodexCheckSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh authoring check`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\``,
         "- explain each diagnostic finding with severity and provenance",
         "- surface any import-state caveats or editor-side warnings",
         "- if issues found, suggest concrete remediation steps",
@@ -710,7 +847,7 @@ export function renderCodexCheckSkill() {
         "",
     ].join("\n");
 }
-export function renderCursorCheckSkill() {
+export function renderCursorCheckSkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-check",
@@ -734,7 +871,7 @@ export function renderCursorCheckSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh authoring check`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\``,
         "- explain each diagnostic finding with severity and provenance",
         "- surface any import-state caveats or editor-side warnings",
         "- if issues found, suggest concrete remediation steps",
@@ -749,7 +886,7 @@ export function renderCursorCheckSkill() {
     ].join("\n");
 }
 // --- gdh-prepare skill renders ---
-export function renderClaudePrepareCommand() {
+export function renderClaudePrepareCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:prepare",
@@ -768,11 +905,11 @@ export function renderClaudePrepareCommand() {
         "<process>",
         "Follow this order:",
         "",
-        "1. Run `gdh target prepare --dry-run` first to preview planned actions.",
+        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\` first to preview planned actions.`,
         "2. Explain what hydration and import refresh will do.",
-        "3. If the user approves, run `gdh target prepare`.",
+        `3. If the user approves, run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare\`.`,
         "4. If a `--source-target` is relevant, explain when and why to use it.",
-        "5. Verify preparation succeeded with `gdh status`.",
+        `5. Verify preparation succeeded with \`npx -y @skillcap/gdh@${pinnedVersion} status\`.`,
         "</process>",
         "",
         "<rules>",
@@ -783,7 +920,7 @@ export function renderClaudePrepareCommand() {
         "",
     ].join("\n");
 }
-export function renderCodexPrepareSkill() {
+export function renderCodexPrepareSkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-prepare"',
@@ -809,11 +946,11 @@ export function renderCodexPrepareSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh target prepare --dry-run` first to preview planned actions",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\` first to preview planned actions`,
         "- explain what hydration and import refresh will do",
-        "- if the user approves, run `gdh target prepare`",
+        `- if the user approves, run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare\``,
         "- if a `--source-target` is relevant, explain when and why to use it",
-        "- verify preparation succeeded with `gdh status`",
+        `- verify preparation succeeded with \`npx -y @skillcap/gdh@${pinnedVersion} status\``,
         "</process>",
         "",
         "<rules>",
@@ -824,7 +961,7 @@ export function renderCodexPrepareSkill() {
         "",
     ].join("\n");
 }
-export function renderCursorPrepareSkill() {
+export function renderCursorPrepareSkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-prepare",
@@ -848,11 +985,11 @@ export function renderCursorPrepareSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh target prepare --dry-run` first to preview planned actions",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\` first to preview planned actions`,
         "- explain what hydration and import refresh will do",
-        "- if the user approves, run `gdh target prepare`",
+        `- if the user approves, run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare\``,
         "- if a `--source-target` is relevant, explain when and why to use it",
-        "- verify preparation succeeded with `gdh status`",
+        `- verify preparation succeeded with \`npx -y @skillcap/gdh@${pinnedVersion} status\``,
         "</process>",
         "",
         "<rules>",
@@ -864,7 +1001,7 @@ export function renderCursorPrepareSkill() {
     ].join("\n");
 }
 // --- gdh-verify skill renders ---
-export function renderClaudeVerifyCommand() {
+export function renderClaudeVerifyCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:verify",
@@ -883,8 +1020,8 @@ export function renderClaudeVerifyCommand() {
         "Follow this order:",
         "",
         "1. Identify changed files from git diff or user input.",
-        "2. Run `gdh verify recommend` with those files to get recommended validation kinds.",
-        "3. Run `gdh verify done` with performed validations to check done eligibility.",
+        `2. Run \`npx -y @skillcap/gdh@${pinnedVersion} verify recommend\` with those files to get recommended validation kinds.`,
+        `3. Run \`npx -y @skillcap/gdh@${pinnedVersion} verify done\` with performed validations to check done eligibility.`,
         "4. Summarize gaps between recommended and performed validation.",
         "5. Suggest specific next verification steps.",
         "</process>",
@@ -897,7 +1034,7 @@ export function renderClaudeVerifyCommand() {
         "",
     ].join("\n");
 }
-export function renderCodexVerifySkill() {
+export function renderCodexVerifySkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-verify"',
@@ -924,8 +1061,8 @@ export function renderCodexVerifySkill() {
         "Follow this order:",
         "",
         "- identify changed files from git diff or user input",
-        "- run `gdh verify recommend` with those files to get recommended validation kinds",
-        "- run `gdh verify done` with performed validations to check done eligibility",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verify recommend\` with those files to get recommended validation kinds`,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verify done\` with performed validations to check done eligibility`,
         "- summarize gaps between recommended and performed validation",
         "- suggest specific next verification steps",
         "</process>",
@@ -938,7 +1075,7 @@ export function renderCodexVerifySkill() {
         "",
     ].join("\n");
 }
-export function renderCursorVerifySkill() {
+export function renderCursorVerifySkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-verify",
@@ -963,8 +1100,8 @@ export function renderCursorVerifySkill() {
         "Follow this order:",
         "",
         "- identify changed files from git diff or user input",
-        "- run `gdh verify recommend` with those files to get recommended validation kinds",
-        "- run `gdh verify done` with performed validations to check done eligibility",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verify recommend\` with those files to get recommended validation kinds`,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verify done\` with performed validations to check done eligibility`,
         "- summarize gaps between recommended and performed validation",
         "- suggest specific next verification steps",
         "</process>",
@@ -980,11 +1117,13 @@ export function renderCursorVerifySkill() {
 async function inspectProjectMcpSupport(targetPath, options) {
     const projectConfig = await readProjectConfig(targetPath);
     const enabled = resolveProjectMcpEnabled(projectConfig);
-    const launcherContent = renderManagedMcpLauncher();
+    const launcherContent = options.pinnedVersion === null
+        ? null
+        : renderManagedMcpLauncher(options.pinnedVersion);
     const managedMcpEntry = buildManagedMcpServerEntry({
         targetPath,
         integrationRootPath: options.integrationRootPath,
-        launcherPathForConfig: `./${normalizePathForJson(path.relative(options.integrationRootPath, path.join(options.integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH)))}`,
+        launcherPathForConfig: path.resolve(options.integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH),
     });
     const [projectFile, cursorFile, launcherSource, localPathHints] = await Promise.all([
         inspectJsonFile(path.join(options.integrationRootPath, PROJECT_MCP_RELATIVE_PATH)),
@@ -1090,6 +1229,13 @@ function inspectLauncherFile(launcherSource, expectedContent, enabled, bootstrap
             summary: "The managed GDH MCP launcher is disabled for this target.",
         };
     }
+    if (expectedContent === null) {
+        return {
+            present: launcherSource !== null,
+            state: "missing",
+            summary: "The managed GDH MCP launcher is pending project onboard: no `gdh_version` is pinned yet, so there is no expected launcher content to compare against.",
+        };
+    }
     if (launcherSource === null) {
         return {
             present: false,
@@ -1182,6 +1328,20 @@ async function inspectCodexRegistration(targetPath, enabled, codexServerName, co
     };
 }
 function inspectCodexSkillSurface(targetPath, relativePath, content, expectedContent, skillName) {
+    if (expectedContent === null) {
+        return [
+            createSurfaceStatus({
+                kind: "skill_file",
+                scope: "repo",
+                targetPath,
+                relativePath,
+                present: content !== null,
+                state: "missing",
+                summary: `Codex ${skillName} skill cannot be validated yet: no \`gdh_version\` is pinned (run \`gdh setup\` or \`gdh migrate --apply\`).`,
+                version: null,
+            }),
+        ];
+    }
     return [
         createSurfaceStatus({
             kind: "skill_file",
@@ -1204,6 +1364,20 @@ function inspectCodexSkillSurface(targetPath, relativePath, content, expectedCon
     ];
 }
 function inspectClaudeCommandSurface(targetPath, relativePath, content, expectedContent, commandName) {
+    if (expectedContent === null) {
+        return [
+            createSurfaceStatus({
+                kind: "command_file",
+                scope: "repo",
+                targetPath,
+                relativePath,
+                present: content !== null,
+                state: "missing",
+                summary: `Claude ${commandName} command cannot be validated yet: no \`gdh_version\` is pinned (run \`gdh setup\` or \`gdh migrate --apply\`).`,
+                version: null,
+            }),
+        ];
+    }
     return [
         createSurfaceStatus({
             kind: "command_file",
@@ -1226,6 +1400,20 @@ function inspectClaudeCommandSurface(targetPath, relativePath, content, expected
     ];
 }
 function inspectCursorSkillSurface(targetPath, relativePath, content, expectedContent, skillName) {
+    if (expectedContent === null) {
+        return [
+            createSurfaceStatus({
+                kind: "skill_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\`).`,
+                version: null,
+            }),
+        ];
+    }
     return [
         createSurfaceStatus({
             kind: "skill_file",
@@ -1247,7 +1435,7 @@ function inspectCursorSkillSurface(targetPath, relativePath, content, expectedCo
         }),
     ];
 }
-async function inspectCodexAdapter(targetPath, guidance, projectMcp, options) {
+async function inspectCodexAdapter(targetPath, guidance, projectMcp, pinnedVersion, options) {
     const codexSkillPath = path.join(targetPath, CODEX_ONBOARD_SKILL_RELATIVE_PATH);
     const codexSkillContent = await fs.readFile(codexSkillPath, "utf8").catch(() => null);
     const codexStatusContent = await fs.readFile(path.join(targetPath, CODEX_STATUS_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
@@ -1255,6 +1443,14 @@ async function inspectCodexAdapter(targetPath, guidance, projectMcp, options) {
     const codexCheckContent = await fs.readFile(path.join(targetPath, CODEX_CHECK_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const codexPrepareContent = await fs.readFile(path.join(targetPath, CODEX_PREPARE_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const codexVerifyContent = await fs.readFile(path.join(targetPath, CODEX_VERIFY_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
+    const codexScanContent = await fs.readFile(path.join(targetPath, CODEX_SCAN_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
+    const expectedCodexOnboardSkill = pinnedVersion === null ? null : renderCodexOnboardSkill(pinnedVersion);
+    const expectedCodexStatusSkill = pinnedVersion === null ? null : renderCodexStatusSkill(pinnedVersion);
+    const expectedCodexMigrateSkill = pinnedVersion === null ? null : renderCodexMigrateSkill(pinnedVersion);
+    const expectedCodexCheckSkill = pinnedVersion === null ? null : renderCodexCheckSkill(pinnedVersion);
+    const expectedCodexPrepareSkill = pinnedVersion === null ? null : renderCodexPrepareSkill(pinnedVersion);
+    const expectedCodexVerifySkill = pinnedVersion === null ? null : renderCodexVerifySkill(pinnedVersion);
+    const expectedCodexScanSkill = pinnedVersion === null ? null : renderCodexScanSkill(pinnedVersion);
     const surfaces = [
         createSurfaceStatus({
             kind: "canonical_entrypoint",
@@ -1282,21 +1478,26 @@ async function inspectCodexAdapter(targetPath, guidance, projectMcp, options) {
             present: codexSkillContent !== null,
             state: codexSkillContent === null
                 ? "missing"
-                : codexSkillContent === renderCodexOnboardSkill()
-                    ? "ready"
-                    : "misconfigured",
+                : expectedCodexOnboardSkill === null
+                    ? "missing"
+                    : codexSkillContent === expectedCodexOnboardSkill
+                        ? "ready"
+                        : "misconfigured",
             summary: codexSkillContent === null
                 ? "Codex onboarding handoff is missing and should install `/gdh-onboard` under .codex/skills/."
-                : codexSkillContent === renderCodexOnboardSkill()
-                    ? "Codex can discover the managed `/gdh-onboard` handoff skill."
-                    : "Codex onboarding handoff exists but no longer matches the expected managed GDH skill.",
+                : expectedCodexOnboardSkill === null
+                    ? "Codex onboarding handoff cannot be validated yet: no `gdh_version` is pinned (run `gdh setup` or `gdh migrate --apply`)."
+                    : codexSkillContent === expectedCodexOnboardSkill
+                        ? "Codex can discover the managed `/gdh-onboard` handoff skill."
+                        : "Codex onboarding handoff exists but no longer matches the expected managed GDH skill.",
             version: null,
         }),
-        ...inspectCodexSkillSurface(targetPath, CODEX_STATUS_SKILL_RELATIVE_PATH, codexStatusContent, renderCodexStatusSkill(), "gdh-status"),
-        ...inspectCodexSkillSurface(targetPath, CODEX_MIGRATE_SKILL_RELATIVE_PATH, codexMigrateContent, renderCodexMigrateSkill(), "gdh-migrate"),
-        ...inspectCodexSkillSurface(targetPath, CODEX_CHECK_SKILL_RELATIVE_PATH, codexCheckContent, renderCodexCheckSkill(), "gdh-check"),
-        ...inspectCodexSkillSurface(targetPath, CODEX_PREPARE_SKILL_RELATIVE_PATH, codexPrepareContent, renderCodexPrepareSkill(), "gdh-prepare"),
-        ...inspectCodexSkillSurface(targetPath, CODEX_VERIFY_SKILL_RELATIVE_PATH, codexVerifyContent, renderCodexVerifySkill(), "gdh-verify"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_STATUS_SKILL_RELATIVE_PATH, codexStatusContent, expectedCodexStatusSkill, "gdh-status"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_MIGRATE_SKILL_RELATIVE_PATH, codexMigrateContent, expectedCodexMigrateSkill, "gdh-migrate"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_CHECK_SKILL_RELATIVE_PATH, codexCheckContent, expectedCodexCheckSkill, "gdh-check"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_PREPARE_SKILL_RELATIVE_PATH, codexPrepareContent, expectedCodexPrepareSkill, "gdh-prepare"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_VERIFY_SKILL_RELATIVE_PATH, codexVerifyContent, expectedCodexVerifySkill, "gdh-verify"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_SCAN_SKILL_RELATIVE_PATH, codexScanContent, expectedCodexScanSkill, "gdh-scan"),
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
@@ -1325,7 +1526,7 @@ async function inspectCodexAdapter(targetPath, guidance, projectMcp, options) {
     }
     return createAgentStatus("codex", guidance, surfaces);
 }
-async function inspectClaudeAdapter(targetPath, guidance, projectMcp) {
+async function inspectClaudeAdapter(targetPath, guidance, projectMcp, pinnedVersion) {
     const absolutePath = path.join(targetPath, CLAUDE_SHIM_RELATIVE_PATH);
     const onboardCommandPath = path.join(targetPath, CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH);
     const lstat = await fs.lstat(absolutePath).catch(() => null);
@@ -1335,10 +1536,18 @@ async function inspectClaudeAdapter(targetPath, guidance, projectMcp) {
     const claudeCheckContent = await fs.readFile(path.join(targetPath, CLAUDE_CHECK_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
     const claudePrepareContent = await fs.readFile(path.join(targetPath, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
     const claudeVerifyContent = await fs.readFile(path.join(targetPath, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
+    const claudeScanContent = await fs.readFile(path.join(targetPath, CLAUDE_SCAN_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
     let detectedTarget = null;
     if (lstat?.isSymbolicLink()) {
         detectedTarget = await fs.readlink(absolutePath).catch(() => null);
     }
+    const expectedClaudeOnboardCommand = pinnedVersion === null ? null : renderClaudeOnboardCommand(pinnedVersion);
+    const expectedClaudeStatusCommand = pinnedVersion === null ? null : renderClaudeStatusCommand(pinnedVersion);
+    const expectedClaudeMigrateCommand = pinnedVersion === null ? null : renderClaudeMigrateCommand(pinnedVersion);
+    const expectedClaudeCheckCommand = pinnedVersion === null ? null : renderClaudeCheckCommand(pinnedVersion);
+    const expectedClaudePrepareCommand = pinnedVersion === null ? null : renderClaudePrepareCommand(pinnedVersion);
+    const expectedClaudeVerifyCommand = pinnedVersion === null ? null : renderClaudeVerifyCommand(pinnedVersion);
+    const expectedClaudeScanCommand = pinnedVersion === null ? null : renderClaudeScanCommand(pinnedVersion);
     const surfaces = [
         createSurfaceStatus({
             kind: "symlink",
@@ -1368,21 +1577,26 @@ async function inspectClaudeAdapter(targetPath, guidance, projectMcp) {
             present: onboardCommandContent !== null,
             state: onboardCommandContent === null
                 ? "missing"
-                : onboardCommandContent === renderClaudeOnboardCommand()
-                    ? "ready"
-                    : "misconfigured",
+                : expectedClaudeOnboardCommand === null
+                    ? "missing"
+                    : onboardCommandContent === expectedClaudeOnboardCommand
+                        ? "ready"
+                        : "misconfigured",
             summary: onboardCommandContent === null
                 ? "Claude onboarding handoff is missing and should install `/gdh-onboard` under .claude/commands/."
-                : onboardCommandContent === renderClaudeOnboardCommand()
-                    ? "Claude can discover the managed `/gdh-onboard` handoff command."
-                    : "Claude onboarding handoff exists but no longer matches the expected managed GDH command.",
+                : expectedClaudeOnboardCommand === null
+                    ? "Claude onboarding handoff cannot be validated yet: no `gdh_version` is pinned (run `gdh setup` or `gdh migrate --apply`)."
+                    : onboardCommandContent === expectedClaudeOnboardCommand
+                        ? "Claude can discover the managed `/gdh-onboard` handoff command."
+                        : "Claude onboarding handoff exists but no longer matches the expected managed GDH command.",
             version: null,
         }),
-        ...inspectClaudeCommandSurface(targetPath, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, claudeStatusContent, renderClaudeStatusCommand(), "gdh-status"),
-        ...inspectClaudeCommandSurface(targetPath, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, claudeMigrateContent, renderClaudeMigrateCommand(), "gdh-migrate"),
-        ...inspectClaudeCommandSurface(targetPath, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, claudeCheckContent, renderClaudeCheckCommand(), "gdh-check"),
-        ...inspectClaudeCommandSurface(targetPath, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, claudePrepareContent, renderClaudePrepareCommand(), "gdh-prepare"),
-        ...inspectClaudeCommandSurface(targetPath, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, claudeVerifyContent, renderClaudeVerifyCommand(), "gdh-verify"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, claudeStatusContent, expectedClaudeStatusCommand, "gdh-status"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, claudeMigrateContent, expectedClaudeMigrateCommand, "gdh-migrate"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, claudeCheckContent, expectedClaudeCheckCommand, "gdh-check"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, claudePrepareContent, expectedClaudePrepareCommand, "gdh-prepare"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, claudeVerifyContent, expectedClaudeVerifyCommand, "gdh-verify"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_SCAN_COMMAND_RELATIVE_PATH, claudeScanContent, expectedClaudeScanCommand, "gdh-scan"),
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
@@ -1409,7 +1623,7 @@ async function inspectClaudeAdapter(targetPath, guidance, projectMcp) {
     }
     return createAgentStatus("claude", guidance, surfaces);
 }
-async function inspectCursorAdapter(targetPath, guidance, projectMcp) {
+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 content = await fs.readFile(absolutePath, "utf8").catch(() => null);
@@ -1419,8 +1633,16 @@ async function inspectCursorAdapter(targetPath, guidance, projectMcp) {
     const cursorCheckContent = await fs.readFile(path.join(targetPath, CURSOR_CHECK_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const cursorPrepareContent = await fs.readFile(path.join(targetPath, CURSOR_PREPARE_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const cursorVerifyContent = await fs.readFile(path.join(targetPath, CURSOR_VERIFY_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
+    const cursorScanContent = await fs.readFile(path.join(targetPath, CURSOR_SCAN_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const expectedContent = renderCursorRule();
     const version = readCursorRuleVersion(content);
+    const expectedCursorOnboardSkill = pinnedVersion === null ? null : renderCursorOnboardSkill(pinnedVersion);
+    const expectedCursorStatusSkill = pinnedVersion === null ? null : renderCursorStatusSkill(pinnedVersion);
+    const expectedCursorMigrateSkill = pinnedVersion === null ? null : renderCursorMigrateSkill(pinnedVersion);
+    const expectedCursorCheckSkill = pinnedVersion === null ? null : renderCursorCheckSkill(pinnedVersion);
+    const expectedCursorPrepareSkill = pinnedVersion === null ? null : renderCursorPrepareSkill(pinnedVersion);
+    const expectedCursorVerifySkill = pinnedVersion === null ? null : renderCursorVerifySkill(pinnedVersion);
+    const expectedCursorScanSkill = pinnedVersion === null ? null : renderCursorScanSkill(pinnedVersion);
     const surfaces = [
         createSurfaceStatus({
             kind: "rule_file",
@@ -1448,21 +1670,26 @@ async function inspectCursorAdapter(targetPath, guidance, projectMcp) {
             present: onboardSkillContent !== null,
             state: onboardSkillContent === null
                 ? "missing"
-                : onboardSkillContent === renderCursorOnboardSkill()
-                    ? "ready"
-                    : "misconfigured",
+                : expectedCursorOnboardSkill === null
+                    ? "missing"
+                    : onboardSkillContent === expectedCursorOnboardSkill
+                        ? "ready"
+                        : "misconfigured",
             summary: onboardSkillContent === null
                 ? "Cursor onboarding handoff is missing and should install `/gdh-onboard` under .cursor/skills/."
-                : onboardSkillContent === renderCursorOnboardSkill()
-                    ? "Cursor can discover the managed `/gdh-onboard` handoff skill."
-                    : "Cursor onboarding handoff exists but no longer matches the expected managed GDH skill.",
+                : 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.",
             version: null,
         }),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_STATUS_SKILL_RELATIVE_PATH, cursorStatusContent, renderCursorStatusSkill(), "gdh-status"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, cursorMigrateContent, renderCursorMigrateSkill(), "gdh-migrate"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_CHECK_SKILL_RELATIVE_PATH, cursorCheckContent, renderCursorCheckSkill(), "gdh-check"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_PREPARE_SKILL_RELATIVE_PATH, cursorPrepareContent, renderCursorPrepareSkill(), "gdh-prepare"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_VERIFY_SKILL_RELATIVE_PATH, cursorVerifyContent, renderCursorVerifySkill(), "gdh-verify"),
+        ...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_CHECK_SKILL_RELATIVE_PATH, cursorCheckContent, expectedCursorCheckSkill, "gdh-check"),
+        ...inspectCursorSkillSurface(targetPath, CURSOR_PREPARE_SKILL_RELATIVE_PATH, cursorPrepareContent, expectedCursorPrepareSkill, "gdh-prepare"),
+        ...inspectCursorSkillSurface(targetPath, CURSOR_VERIFY_SKILL_RELATIVE_PATH, cursorVerifyContent, expectedCursorVerifySkill, "gdh-verify"),
+        ...inspectCursorSkillSurface(targetPath, CURSOR_SCAN_SKILL_RELATIVE_PATH, cursorScanContent, expectedCursorScanSkill, "gdh-scan"),
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
@@ -1552,6 +1779,7 @@ async function planInstallActions(targetPath, adapters, requestedAgents, options
     const projectMcp = await inspectProjectMcpSupport(targetPath, {
         includeUserLocal: true,
         integrationRootPath: options.integrationRootPath,
+        pinnedVersion: options.pinnedVersion,
     });
     const actions = [];
     const effectiveDevRepoPath = options.devRepoPath ?? resolveCurrentGdhInstall(import.meta.url).defaultDevRepoPath;
@@ -1567,15 +1795,15 @@ async function planInstallActions(targetPath, adapters, requestedAgents, options
             continue;
         }
         if (adapter.agent === "codex") {
-            actions.push(...planCodexRepoInstallActions(targetPath, adapter));
+            actions.push(...planCodexRepoInstallActions(targetPath, adapter, options.pinnedVersion));
             continue;
         }
         if (adapter.agent === "claude") {
-            actions.push(...planClaudeInstallActions(targetPath, adapter));
+            actions.push(...planClaudeInstallActions(targetPath, adapter, options.pinnedVersion));
             continue;
         }
         if (adapter.agent === "cursor") {
-            actions.push(...planCursorInstallActions(targetPath, adapter));
+            actions.push(...planCursorInstallActions(targetPath, adapter, options.pinnedVersion));
         }
     }
     return dedupeInstallActions(actions);
@@ -1616,7 +1844,7 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
             content: renderManagedMcpConfig(path.join(integrationRootPath, PROJECT_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({
                 targetPath,
                 integrationRootPath,
-                launcherPathForConfig: `./${normalizePathForJson(MCP_LAUNCHER_RELATIVE_PATH)}`,
+                launcherPathForConfig: path.resolve(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH),
             })),
         }));
     }
@@ -1635,7 +1863,7 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
             content: renderManagedMcpConfig(path.join(integrationRootPath, CURSOR_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({
                 targetPath,
                 integrationRootPath,
-                launcherPathForConfig: `./${normalizePathForJson(MCP_LAUNCHER_RELATIVE_PATH)}`,
+                launcherPathForConfig: path.resolve(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH),
             })),
         }));
     }
@@ -1667,7 +1895,7 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
     }
     return actions;
 }
-function planSkillInstallAction(agent, targetPath, adapter, relativePath, renderFn, skillName) {
+function planSkillInstallAction(agent, targetPath, adapter, relativePath, renderFn, skillName, pinnedVersion) {
     const surface = adapter.surfaces.find((s) => s.relativePath === relativePath);
     if (!surface || surface.state === "ready") {
         return createInstallAction({
@@ -1679,7 +1907,7 @@ function planSkillInstallAction(agent, targetPath, adapter, relativePath, render
             state: "unchanged",
             mode: "unchanged",
             summary: `The managed ${agentLabel(agent)} \`/${skillName}\` ${agent === "claude" ? "command" : "skill"} already matches the expected GDH content.`,
-            content: renderFn(),
+            content: renderFn(pinnedVersion),
         });
     }
     return createInstallAction({
@@ -1693,7 +1921,7 @@ function planSkillInstallAction(agent, targetPath, adapter, relativePath, render
         summary: surface.present
             ? `Replace the existing ${agentLabel(agent)} \`/${skillName}\` ${agent === "claude" ? "command" : "skill"} with the managed GDH ${agent === "claude" ? "command" : "skill"}.`
             : `Create the managed ${agentLabel(agent)} \`/${skillName}\` ${agent === "claude" ? "command" : "skill"}.`,
-        content: renderFn(),
+        content: renderFn(pinnedVersion),
     });
 }
 function agentLabel(agent) {
@@ -1706,14 +1934,15 @@ function agentLabel(agent) {
             return "Cursor";
     }
 }
-function planCodexRepoInstallActions(targetPath, adapter) {
+function planCodexRepoInstallActions(targetPath, adapter, pinnedVersion) {
     return [
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_ONBOARD_SKILL_RELATIVE_PATH, renderCodexOnboardSkill, "gdh-onboard"),
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_STATUS_SKILL_RELATIVE_PATH, renderCodexStatusSkill, "gdh-status"),
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_MIGRATE_SKILL_RELATIVE_PATH, renderCodexMigrateSkill, "gdh-migrate"),
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_CHECK_SKILL_RELATIVE_PATH, renderCodexCheckSkill, "gdh-check"),
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_PREPARE_SKILL_RELATIVE_PATH, renderCodexPrepareSkill, "gdh-prepare"),
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_VERIFY_SKILL_RELATIVE_PATH, renderCodexVerifySkill, "gdh-verify"),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_ONBOARD_SKILL_RELATIVE_PATH, renderCodexOnboardSkill, "gdh-onboard", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_STATUS_SKILL_RELATIVE_PATH, renderCodexStatusSkill, "gdh-status", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_MIGRATE_SKILL_RELATIVE_PATH, renderCodexMigrateSkill, "gdh-migrate", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_CHECK_SKILL_RELATIVE_PATH, renderCodexCheckSkill, "gdh-check", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_PREPARE_SKILL_RELATIVE_PATH, renderCodexPrepareSkill, "gdh-prepare", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_VERIFY_SKILL_RELATIVE_PATH, renderCodexVerifySkill, "gdh-verify", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_SCAN_SKILL_RELATIVE_PATH, renderCodexScanSkill, "gdh-scan", pinnedVersion),
     ];
 }
 function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath) {
@@ -1764,7 +1993,7 @@ function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath
     }));
     return actions;
 }
-function planClaudeInstallActions(targetPath, adapter) {
+function planClaudeInstallActions(targetPath, adapter, pinnedVersion) {
     const actions = [];
     const claudeSurface = adapter.surfaces.find((surface) => surface.relativePath === CLAUDE_SHIM_RELATIVE_PATH);
     if (!claudeSurface || claudeSurface.state === "ready") {
@@ -1795,10 +2024,10 @@ function planClaudeInstallActions(targetPath, adapter) {
             expectedTarget: "AGENTS.md",
         }));
     }
-    actions.push(planSkillInstallAction("claude", targetPath, adapter, CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH, renderClaudeOnboardCommand, "gdh-onboard"), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, renderClaudeStatusCommand, "gdh-status"), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, renderClaudeMigrateCommand, "gdh-migrate"), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, renderClaudeCheckCommand, "gdh-check"), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, renderClaudePrepareCommand, "gdh-prepare"), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, renderClaudeVerifyCommand, "gdh-verify"));
+    actions.push(planSkillInstallAction("claude", targetPath, adapter, CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH, renderClaudeOnboardCommand, "gdh-onboard", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, renderClaudeStatusCommand, "gdh-status", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, renderClaudeMigrateCommand, "gdh-migrate", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, renderClaudeCheckCommand, "gdh-check", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, renderClaudePrepareCommand, "gdh-prepare", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, renderClaudeVerifyCommand, "gdh-verify", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_SCAN_COMMAND_RELATIVE_PATH, renderClaudeScanCommand, "gdh-scan", pinnedVersion));
     return actions;
 }
-function planCursorInstallActions(targetPath, adapter) {
+function planCursorInstallActions(targetPath, adapter, pinnedVersion) {
     const actions = [];
     const cursorRuleSurface = adapter.surfaces.find((surface) => surface.relativePath === CURSOR_RULE_RELATIVE_PATH);
     if (!cursorRuleSurface || cursorRuleSurface.state === "ready") {
@@ -1831,7 +2060,7 @@ function planCursorInstallActions(targetPath, adapter) {
             content: renderCursorRule(),
         }));
     }
-    actions.push(planSkillInstallAction("cursor", targetPath, adapter, CURSOR_ONBOARD_SKILL_RELATIVE_PATH, renderCursorOnboardSkill, "gdh-onboard"), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_STATUS_SKILL_RELATIVE_PATH, renderCursorStatusSkill, "gdh-status"), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, renderCursorMigrateSkill, "gdh-migrate"), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_CHECK_SKILL_RELATIVE_PATH, renderCursorCheckSkill, "gdh-check"), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_PREPARE_SKILL_RELATIVE_PATH, renderCursorPrepareSkill, "gdh-prepare"), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_VERIFY_SKILL_RELATIVE_PATH, renderCursorVerifySkill, "gdh-verify"));
+    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_CHECK_SKILL_RELATIVE_PATH, renderCursorCheckSkill, "gdh-check", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_PREPARE_SKILL_RELATIVE_PATH, renderCursorPrepareSkill, "gdh-prepare", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_VERIFY_SKILL_RELATIVE_PATH, renderCursorVerifySkill, "gdh-verify", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_SCAN_SKILL_RELATIVE_PATH, renderCursorScanSkill, "gdh-scan", pinnedVersion));
     return actions;
 }
 function dedupeInstallActions(actions) {
@@ -1929,7 +2158,7 @@ function resolveProjectMcpEnabled(projectConfig) {
 function createCodexServerName(projectKeySeed) {
     return `gdh-${projectKeySeed}`;
 }
-function renderManagedMcpLauncher() {
+export function renderManagedMcpLauncher(pinnedVersion) {
     return [
         "#!/usr/bin/env node",
         `// GDH MCP launcher v${GDH_MCP_LAUNCHER_VERSION}`,
@@ -1968,9 +2197,9 @@ function renderManagedMcpLauncher() {
         "  }",
         "}",
         "",
-        'const result = spawnSync("gdh", ["mcp", "serve", "--target", targetPath], { stdio: "inherit" });',
+        `const result = spawnSync("npx", ["-y", "@skillcap/gdh@${pinnedVersion}", "mcp", "serve", "--target", targetPath], { stdio: "inherit", cwd: targetPath });`,
         'if (result.error && result.error.code === "ENOENT") {',
-        '  console.error("GDH MCP launcher could not find a usable GDH server. Install `gdh` on PATH or run `gdh adapters install <target> --dev-repo <path-to-gdh>`.");',
+        `  console.error("GDH MCP launcher could not launch npx for @skillcap/gdh@${pinnedVersion}. Ensure Node.js 20+ is installed (npx ships with Node), or configure the contributor dev escape hatch via the GDH_DEV_REPO env var or .gdh-state/local-paths.json gdhDevRepoPath.");`,
         "  process.exit(1);",
         "}",
         "process.exit(result.status ?? 1);",
@@ -1985,7 +2214,7 @@ function buildManagedMcpServerEntry(input) {
             targetPath: input.targetPath,
             integrationRootPath: input.integrationRootPath,
             launcherPath: input.launcherPathForConfig,
-            useAbsoluteTargetPath: false,
+            useAbsoluteTargetPath: true,
         }),
     };
 }