vskill 1.0.14 → 1.0.16

package/dist/clone/target-router.js

@@ -0,0 +1,200 @@
+// ---------------------------------------------------------------------------
+// vskill clone — target-router
+// ---------------------------------------------------------------------------
+// Three target writers, all `.tmp`-staged so the orchestrator can atomically
+// rename the staged copy into place once every other step (frontmatter
+// rewrite, provenance write, validation) has succeeded.
+//
+//   writeStandalone  → drop the cloned skill at <dir>
+//   writeToPlugin    → drop into <plugin>/skills/<skill> and append to manifest
+//   writeNewPlugin   → scaffold a fresh plugin with .claude-plugin/plugin.json + skills/<skill>
+//
+// All three return the absolute path of the *staging* `.tmp` directory so the
+// orchestrator can run subsequent in-place edits (frontmatter, sidecar) before
+// committing with `fs.rename`. The ONLY exception is `writeToPlugin` which
+// also returns a separate `manifestTmpPath` so the orchestrator can rename
+// both `.tmp` paths in sequence (two-phase commit).
+//
+// Filtering: the recursive copy reuses the public `shouldSkipFromCommands`
+// helper from src/shared/copy-plugin-filtered.ts plus a root-level filter for
+// the vskill-internal sidecars `.vskill-meta.json` and `.vskill-source.json`
+// (matching the OWN-scope copy semantics in src/studio/lib/scope-transfer.ts).
+//
+// See spec.md AC-US1-03 / AC-US2-01..03 / AC-US3-01, plan.md §5–§6.
+// ---------------------------------------------------------------------------
+import { promises as fs, existsSync, readdirSync, statSync, copyFileSync, mkdirSync, rmSync, } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { shouldSkipFromCommands } from "../shared/copy-plugin-filtered.js";
+/**
+ * Recursive skill-dir copy with sidecar filtering at the root and
+ * shouldSkipFromCommands filtering at every depth. Mirrors the OWN-scope
+ * helper in src/studio/lib/scope-transfer.ts (lines 101–119) — that helper is
+ * not exported, so we re-implement the same behavior rather than duplicate
+ * its file.
+ */
+function copySkillDirFiltered(sourceDir, targetDir, relBase = "") {
+    mkdirSync(targetDir, { recursive: true });
+    let filesCopied = 0;
+    for (const entry of readdirSync(sourceDir)) {
+        // Filter vskill internal sidecars at the skill root only — same asymmetric
+        // contract as scope-transfer.ts: OWN scope is a single skill dir, so
+        // sidecars only ever exist at the root.
+        if (!relBase && (entry === ".vskill-meta.json" || entry === ".vskill-source.json"))
+            continue;
+        const relPath = relBase ? `${relBase}/${entry}` : entry;
+        const sourcePath = join(sourceDir, entry);
+        const st = statSync(sourcePath);
+        if (st.isDirectory()) {
+            filesCopied += copySkillDirFiltered(sourcePath, join(targetDir, entry), relPath);
+        }
+        else if (st.isFile() && !shouldSkipFromCommands(relPath)) {
+            copyFileSync(sourcePath, join(targetDir, entry));
+            filesCopied += 1;
+        }
+    }
+    return filesCopied;
+}
+/** Compute the `.tmp` sibling of a final destination path. */
+export function tmpSibling(finalPath) {
+    return `${finalPath}.tmp`;
+}
+/**
+ * Best-effort cleanup of a `.tmp` path. Mirrors the rollback shape used by
+ * src/commands/add.ts:rollbackInstall — swallows per-call errors so a partial
+ * filesystem state doesn't suppress the underlying diagnostic the orchestrator
+ * is about to surface to the user.
+ */
+export function bestEffortRm(path) {
+    try {
+        if (existsSync(path))
+            rmSync(path, { recursive: true, force: true });
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Copy a source skill into a fresh standalone target dir, staged at
+ * `<finalDir>.tmp`. The orchestrator is responsible for the atomic
+ * rename and any pre-checks for collisions / `--force`.
+ */
+export async function writeStandalone(args) {
+    const stagingDir = tmpSibling(args.finalDir);
+    // Clear any leftover staging directory from a prior failed run before copying.
+    bestEffortRm(stagingDir);
+    await fs.mkdir(dirname(args.finalDir), { recursive: true });
+    const filesCopied = copySkillDirFiltered(args.sourceSkillDir, stagingDir);
+    return { stagingDir, filesCopied, finalDir: args.finalDir };
+}
+/**
+ * Copy a source skill into an existing user-owned plugin's skills/ directory
+ * AND stage an updated `plugin.json` at `<plugin.json>.tmp` so the
+ * orchestrator can rename both in sequence (two-phase commit).
+ *
+ * Pre-flight: detects malformed plugin.json BEFORE any copy is staged
+ * (AC-US2-03). Caller aborts on the thrown error; no skill files are written.
+ */
+export async function writeToPlugin(args) {
+    const manifestFinalPath = join(args.pluginRoot, ".claude-plugin", "plugin.json");
+    if (!existsSync(manifestFinalPath)) {
+        throw new Error(`target plugin manifest not found at ${manifestFinalPath} — pass a plugin root that contains .claude-plugin/plugin.json`);
+    }
+    // Pre-flight: parse the manifest BEFORE any copy is staged.
+    let manifestRaw;
+    try {
+        manifestRaw = await fs.readFile(manifestFinalPath, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`failed to read plugin manifest: ${err.message}`);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestRaw);
+    }
+    catch (err) {
+        throw new Error(`target plugin manifest is malformed JSON (${err.message}) — refusing to clone into ${args.pluginRoot}`);
+    }
+    // The "register the new skill" step appends to a `skills` array (creating
+    // one if absent). Existing entries are preserved; duplicate entries are
+    // collapsed.
+    const skills = Array.isArray(manifest.skills) ? [...manifest.skills] : [];
+    if (!skills.includes(args.newSkillName))
+        skills.push(args.newSkillName);
+    const updatedManifest = { ...manifest, skills };
+    const finalDir = join(args.pluginRoot, "skills", args.newSkillName);
+    const stagingDir = tmpSibling(finalDir);
+    bestEffortRm(stagingDir);
+    await fs.mkdir(dirname(finalDir), { recursive: true });
+    let filesCopied = 0;
+    try {
+        filesCopied = copySkillDirFiltered(args.sourceSkillDir, stagingDir);
+    }
+    catch (err) {
+        bestEffortRm(stagingDir);
+        throw err;
+    }
+    // Stage the updated manifest. The orchestrator commits both renames.
+    const manifestTmpPath = `${manifestFinalPath}.tmp`;
+    try {
+        await fs.writeFile(manifestTmpPath, JSON.stringify(updatedManifest, null, 2) + "\n", "utf-8");
+    }
+    catch (err) {
+        bestEffortRm(stagingDir);
+        bestEffortRm(manifestTmpPath);
+        throw err;
+    }
+    return {
+        stagingDir,
+        filesCopied,
+        finalDir,
+        manifestTmpPath,
+        manifestFinalPath,
+    };
+}
+/**
+ * Scaffold a fresh new plugin at `<pluginRoot>` containing
+ * `.claude-plugin/plugin.json` (with the requested name) plus
+ * `skills/<skill>/` subtree containing the cloned skill.
+ *
+ * The whole plugin tree is staged at `<pluginRoot>.tmp` and atomically
+ * renamed by the caller — there is no two-phase commit because the manifest
+ * and the skill files live under a common root (one `rename` is enough).
+ */
+export async function writeNewPlugin(args) {
+    const stagingDir = tmpSibling(args.pluginRoot);
+    bestEffortRm(stagingDir);
+    // Build the new plugin's manifest.
+    await fs.mkdir(join(stagingDir, ".claude-plugin"), { recursive: true });
+    const manifest = {
+        name: args.pluginName,
+        description: args.description ?? `Plugin scaffolded by 'vskill clone' containing forked skills.`,
+        skills: [args.newSkillName],
+    };
+    if (args.author) {
+        manifest.author = { name: args.author };
+    }
+    await fs.writeFile(join(stagingDir, ".claude-plugin", "plugin.json"), JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+    // Copy the skill into <stagingDir>/skills/<newSkillName>/.
+    const skillTargetDir = join(stagingDir, "skills", args.newSkillName);
+    let filesCopied = 0;
+    try {
+        filesCopied = copySkillDirFiltered(args.sourceSkillDir, skillTargetDir);
+    }
+    catch (err) {
+        bestEffortRm(stagingDir);
+        throw err;
+    }
+    return { stagingDir, filesCopied, finalDir: args.pluginRoot };
+}
+/**
+ * The `bareSkillName` helper extracts the unqualified skill name from a
+ * fully-qualified name like `anton/ado-mapper` → `ado-mapper`. Used by the
+ * orchestrator and by callers that need the directory-safe segment.
+ */
+export function bareSkillName(fullyQualified) {
+    const idx = fullyQualified.indexOf("/");
+    return idx >= 0 ? fullyQualified.slice(idx + 1) : fullyQualified;
+}
+/** Re-export for callers that want to validate basenames. */
+export { basename };
+//# sourceMappingURL=target-router.js.map

package/dist/clone/target-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-router.js","sourceRoot":"","sources":["../../src/clone/target-router.ts"],"names":[],"mappings":"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"}

package/dist/clone/types.d.ts

@@ -0,0 +1,82 @@
+import type { Provenance } from "../studio/types.js";
+/** Where a skill lives on disk. */
+export type SkillSourceLocation = "project" | "personal" | "cache";
+/** A discovered source skill, with absolute path and parsed identity. */
+export interface SkillSource {
+    location: SkillSourceLocation;
+    /** Absolute path to the skill directory (the dir containing SKILL.md). */
+    skillDir: string;
+    /** Skill name as parsed from frontmatter (or directory basename if frontmatter lacks `name`). */
+    skillName: string;
+    /** Original namespace if discoverable (e.g., "sw" for plugin-cache sources). undefined for personal/project. */
+    namespace?: string;
+    /** Original version from frontmatter (or "0.0.0" if absent). */
+    version: string;
+    /** Plugin context — present only for cache-located skills. */
+    plugin?: {
+        pluginNamespace: string;
+        pluginName: string;
+        pluginVersion: string;
+        pluginRoot: string;
+    };
+    /** Existing provenance read from .vskill-meta.json (null if no sidecar). */
+    existingProvenance: Provenance | null;
+}
+/** Where the cloned skill should be written. */
+export type CloneTargetKind = "standalone" | "plugin" | "new-plugin";
+export interface CloneTarget {
+    kind: CloneTargetKind;
+    /** Absolute path to the final skill directory (where files end up after atomic rename). */
+    targetSkillDir: string;
+    /** For "plugin" kind: absolute path to the existing plugin's .claude-plugin/plugin.json. */
+    existingPluginManifestPath?: string;
+    /** For "new-plugin" kind: absolute path to the plugin root being scaffolded. */
+    newPluginRoot?: string;
+    /** For "new-plugin" kind: name to use in the new plugin manifest. */
+    newPluginName?: string;
+}
+export interface CloneOptions {
+    /** New namespace for the cloned skill (e.g., "anton"). Required. */
+    namespace: string;
+    /** New author name. Required. */
+    author: string;
+    /** When true, overwrite existing target without confirmation. */
+    force: boolean;
+    /** When true, after files land, scaffold a GitHub repo via gh. */
+    github: boolean;
+    /** When true, do not write any files — just print the planned actions. */
+    dryRun: boolean;
+}
+/** Result returned by the clone orchestrator. */
+export interface CloneResult {
+    source: SkillSource;
+    target: CloneTarget;
+    /** Final skill name written (e.g., "anton/ado-mapper"). */
+    finalSkillName: string;
+    /** Number of files copied. */
+    filesCopied: number;
+    /** Cross-skill references found in the body (informational, not auto-rewritten). */
+    referenceReport: ReferenceMatch[];
+    /** Self-name occurrences in prose (informational). */
+    selfNameMatches: ReferenceMatch[];
+    /** GitHub repo URL if --github was used and succeeded; null if skipped. */
+    githubRepoUrl: string | null;
+    /** Provenance written to the cloned skill. */
+    provenance: Provenance;
+}
+export interface ReferenceMatch {
+    /** Path of the file the match was found in (relative to skill root). */
+    file: string;
+    /** Line number (1-indexed). */
+    line: number;
+    /** The matched text (e.g., "sw:ado-mapper"). */
+    match: string;
+    /** Pattern category. */
+    kind: "backtick" | "skill-call" | "slash-command" | "self-name";
+}
+/** Fork provenance metadata written to the cloned skill's .vskill-meta.json. */
+export interface ForkProvenance {
+    source: string;
+    version: string;
+    clonedAt: string;
+}

package/dist/clone/types.js

@@ -0,0 +1,11 @@
+// ---------------------------------------------------------------------------
+// vskill clone — shared type contracts
+// ---------------------------------------------------------------------------
+// Source of truth for the `vskill clone` command. Consumed by skill-locator,
+// frontmatter rewriter, provenance-fork, target-router, github-scaffold, and
+// the orchestrator in src/commands/clone.ts.
+//
+// See .specweave/increments/0822-vskill-clone-skill-fork/spec.md and plan.md.
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=types.js.map

package/dist/clone/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/clone/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,6CAA6C;AAC7C,EAAE;AACF,8EAA8E;AAC9E,8EAA8E"}

package/dist/commands/add.js

@@ -17,6 +17,7 @@ import { checkInstallSafety } from "../blocklist/blocklist.js";
 import { getSkill, searchSkills } from "../api/client.js";
 import { checkPlatformSecurity } from "../security/index.js";
 import { discoverSkills, getDefaultBranch, checkRepoExists, warnRateLimitOnce } from "../discovery/github-tree.js";
+import { githubFetch } from "../lib/github-fetch.js";
 import { parseGitHubSource } from "../utils/validation.js";
 import { parseSkillsShUrl, isCompleteParsed, isIncompleteParsed, } from "../resolvers/url-resolver.js";
 import { bold, green, red, yellow, dim, cyan, spinner, link, formatInstalls, } from "../utils/output.js";
@@ -32,7 +33,7 @@ import { extractFrontmatterVersion } from "../utils/version.js";
 // mutation to the claude CLI (ADR 0724-01), and we honour the --no-enable
 // flag to skip it. Uninstall is imported for F-003 rollback of earlier
 // already-enabled plugins on a partway failure.
-import { claudePluginInstall, claudePluginUninstall } from "../utils/claude-plugin.js";
+import { claudePluginInstall, claudePluginUninstall, claudePluginMarketplaceAdd, claudePluginMarketplaceList, } from "../utils/claude-plugin.js";
 import { buildPerAgentReport, resolvePluginId, } from "../lib/skill-lifecycle.js";
 // ---------------------------------------------------------------------------
 /** Validate that a download_url from GitHub Contents API points to a trusted GitHub domain. */
@@ -48,7 +49,7 @@ function isGitHubDownloadUrl(url) {
 async function parseManifestFromContentsApi(data) {
     // Prefer download_url for raw content — validate URL before fetching (SSRF prevention)
     if (data.download_url && isGitHubDownloadUrl(data.download_url)) {
-        const rawRes = await fetch(data.download_url);
+        const rawRes = await githubFetch(data.download_url);
         if (rawRes.ok) {
             const content = await rawRes.text();
             if (getAvailablePlugins(content).length > 0)
@@ -75,7 +76,7 @@ export async function detectMarketplaceRepo(owner, repo) {
     const headers = { Accept: "application/vnd.github.v3+json", "User-Agent": "vskill-cli" };
     // Attempt 1: Contents API
     try {
-        const res = await fetch(contentsUrl, { headers });
+        const res = await githubFetch(contentsUrl, { headers });
         if (res.status === 404)
             return { isMarketplace: false };
         if (res.status === 403)
@@ -93,7 +94,7 @@ export async function detectMarketplaceRepo(owner, repo) {
     // Attempt 2: Retry Contents API after 1s delay
     try {
         await new Promise((r) => setTimeout(r, 1000));
-        const res = await fetch(contentsUrl, { headers });
+        const res = await githubFetch(contentsUrl, { headers });
         if (res.status === 404)
             return { isMarketplace: false };
         if (res.status === 403)
@@ -112,7 +113,7 @@ export async function detectMarketplaceRepo(owner, repo) {
     try {
         const branch = await getDefaultBranch(owner, repo);
         const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/.claude-plugin/marketplace.json`;
-        const res = await fetch(rawUrl);
+        const res = await githubFetch(rawUrl);
         if (res.ok) {
             const content = await res.text();
             if (getAvailablePlugins(content).length > 0) {
@@ -191,7 +192,7 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
                 // Not in marketplace or unregistered list — probe plugins/<name>/ folder directly
                 let probeSource = null;
                 try {
-                    const probeRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/contents/plugins/${preSelected[0]}`, { headers: { "User-Agent": "vskill-cli" } });
+                    const probeRes = await githubFetch(`https://api.github.com/repos/${owner}/${repo}/contents/plugins/${preSelected[0]}`, { headers: { "User-Agent": "vskill-cli" } });
                     if (probeRes.ok) {
                         const data = await probeRes.json();
                         if (Array.isArray(data)) {
@@ -351,7 +352,7 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
                 // Discover skills: try nested {pluginPath}/skills/ first, fall back to flat {pluginPath}/SKILL.md
                 const skillsToSubmit = [];
                 const skillsUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${pluginPath}/skills`;
-                const skillsRes = await fetch(skillsUrl, { headers: { "User-Agent": "vskill-cli" } });
+                const skillsRes = await githubFetch(skillsUrl, { headers: { "User-Agent": "vskill-cli" } });
                 if (skillsRes.ok) {
                     const skillDirs = (await skillsRes.json())
                         .filter((e) => e.type === "dir");
@@ -450,24 +451,27 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
         })),
     ];
     for (const plugin of allPluginsToInstall) {
-        const pluginPath = plugin.source.replace(/^\.\//, "");
-        if (!pluginPath) {
-            results.push({ name: plugin.name, installed: false, method: "failed" });
-            continue;
-        }
+        // 0826: a marketplace plugin whose `source` is `"./"` lives at the repo
+        // root — the previous guard (`if (!pluginPath) … failed`) short-circuited
+        // those installs. Keep the path normalization but allow an empty value to
+        // mean "repo root" instead of treating it as a hard failure. Build URL
+        // segments with a leading-slash prefix only when there's a real path so
+        // we don't emit `//` between the contents-API base and `skills`.
+        const pluginPath = plugin.source.replace(/^\.\//, "").replace(/\/$/, "");
+        const pathSegment = pluginPath ? `/${pluginPath}` : "";
         const installSpin = spinner(`Installing skills: ${bold(plugin.name)}`);
         try {
             // Discover skills: try {pluginPath}/skills/ first, then fall back to {pluginPath}/SKILL.md
             const installedSkillNames = [];
-            const skillsUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${pluginPath}/skills`;
-            const skillsRes = await fetch(skillsUrl, { headers: { "User-Agent": "vskill-cli" } });
+            const skillsUrl = `https://api.github.com/repos/${owner}/${repo}/contents${pathSegment}/skills`;
+            const skillsRes = await githubFetch(skillsUrl, { headers: { "User-Agent": "vskill-cli" } });
             if (skillsRes.ok) {
                 // Nested layout: {pluginPath}/skills/{skillName}/SKILL.md
                 const skillDirs = (await skillsRes.json())
                     .filter((e) => e.type === "dir");
                 for (const sd of skillDirs) {
-                    const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${pluginPath}/skills/${sd.name}/SKILL.md`;
-                    const contentRes = await fetch(rawUrl);
+                    const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}${pathSegment}/skills/${sd.name}/SKILL.md`;
+                    const contentRes = await githubFetch(rawUrl);
                     if (!contentRes.ok)
                         continue;
                     const content = await contentRes.text();
@@ -488,8 +492,8 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
             }
             else {
                 // Flat layout: {pluginPath}/SKILL.md directly in the plugin root
-                const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${pluginPath}/SKILL.md`;
-                const contentRes = await fetch(rawUrl);
+                const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}${pathSegment}/SKILL.md`;
+                const contentRes = await githubFetch(rawUrl);
                 if (contentRes.ok) {
                     const content = await contentRes.text();
                     const processedContent = ensureFrontmatter(content, plugin.name);
@@ -565,7 +569,14 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
     // `enabledSoFar` so that a later failure rolls back all earlier
     // already-enabled plugins (otherwise we'd leave exactly the stale
     // `enabledPlugins` entries that `vskill cleanup` is meant to fix).
+    // 0826: include `opts.global` here. Previously a Studio "Global" install
+    // (or CLI `vskill install … --global`) wrote the SKILL.md stub to disk
+    // but never invoked `claude plugin install` — leaving the plugin
+    // unenabled. The user saw the skill on disk but Claude Code didn't load
+    // it. Treat --global as opt-in to the enable hook (scope = user, since
+    // --global is per-machine, not per-repo).
     const userOptedIn = opts.scope !== undefined ||
+        opts.global === true ||
         opts.dryRun === true ||
         opts.enable === false;
     if (userOptedIn) {
@@ -692,9 +703,62 @@ export function enableAfterInstall(skillName, entry, opts) {
         console.log(dim(`Dry-run: would invoke ${cyan(`claude plugin install --scope ${scope} -- ${pluginId}`)}`));
         return { invoked: false, pluginId, scope };
     }
+    // 0826: when the source repo is a Claude Code plugin marketplace that
+    // hasn't been registered yet, `claude plugin install foo@bar` fails with
+    // "Plugin foo not found in marketplace bar" — and the rollback then
+    // wipes the on-disk extraction we just succeeded at. Detect that case
+    // up-front from the lockfile entry's marketplace metadata and register
+    // the marketplace via `claude plugin marketplace add` before delegating
+    // the install. Best-effort — if the add fails (network, invalid source)
+    // we still attempt the install so the original error is surfaced.
+    ensureMarketplaceRegistered(entry, pluginId, scope);
     claudePluginInstall(pluginId, scope, scope === "project" ? { cwd: process.cwd() } : undefined);
     return { invoked: true, pluginId, scope };
 }
+/**
+ * 0826: Ensure the marketplace referenced by `entry` is registered with the
+ * claude CLI before we try to enable the plugin. The lockfile entry shape
+ * stores the marketplace name (e.g. `postiz-agent`) plus the originating
+ * `sourceRepoUrl` — we derive `<owner>/<repo>` from the URL and run
+ * `claude plugin marketplace add` if the name is missing from the current
+ * `claude plugin marketplace list`.
+ *
+ * Pure best-effort: any failure (network, parse) falls through silently and
+ * lets the subsequent `claudePluginInstall` surface the real error.
+ */
+function ensureMarketplaceRegistered(entry, pluginId, scope) {
+    const marketplaceName = entry.marketplace;
+    if (!marketplaceName)
+        return;
+    // Already registered — nothing to do.
+    let registered = [];
+    try {
+        registered = claudePluginMarketplaceList();
+    }
+    catch {
+        return;
+    }
+    if (registered.includes(marketplaceName))
+        return;
+    // Derive a `claude plugin marketplace add` source from the lockfile.
+    // GitHub URL → `owner/repo`; falls back to `marketplace@<id>` form which
+    // claude rejects with a clear message.
+    const repoSource = entry.sourceRepoUrl?.match(/github\.com\/([^/]+\/[^/]+?)(?:\.git)?\/?$/);
+    const source = repoSource ? repoSource[1] : "";
+    if (!source) {
+        console.error(dim(`  marketplace "${marketplaceName}" not registered and no source repo URL available — skipping auto-add (claude plugin install will likely fail).`));
+        return;
+    }
+    console.log(dim(`  Registering marketplace "${marketplaceName}" (${source}) — required for ${pluginId}`));
+    try {
+        claudePluginMarketplaceAdd(source, scope);
+    }
+    catch (err) {
+        // Surface the underlying error but keep going — claudePluginInstall
+        // will still throw a clearer "not found in marketplace" if needed.
+        console.error(dim(`  Failed to auto-register marketplace "${marketplaceName}": ${err.message.split("\n")[0]}`));
+    }
+}
 /**
  * 0724 T-006: rollback the on-disk extraction + lockfile entry when
  * `claudePluginInstall` throws (AC-US1-05). Best-effort — wraps each rm in
@@ -871,7 +935,7 @@ async function promptInstallOptions(agents, opts) {
 async function fetchSkillContent(url) {
     const spin = spinner("Fetching skill");
     try {
-        const res = await fetch(url);
+        const res = await githubFetch(url);
         if (!res.ok) {
             spin.stop();
             if (res.status === 404) {
@@ -1173,7 +1237,7 @@ sourceSkillPath) {
     // Fetch content (non-exiting for multi-skill support)
     let content;
     try {
-        const res = await fetch(rawUrl);
+        const res = await githubFetch(rawUrl);
         if (!res.ok) {
             return { skillName, installed: false, verdict: "FETCH_FAILED" };
         }
@@ -1221,7 +1285,7 @@ sourceSkillPath) {
         agentFiles = {};
         const fetches = Object.entries(agentRawUrls).map(async ([relPath, url]) => {
             try {
-                const res = await fetch(url);
+                const res = await githubFetch(url);
                 if (res.ok)
                     agentFiles[relPath] = await res.text();
             }
@@ -1264,7 +1328,7 @@ async function installAllRepoPlugins(ownerRepo, opts) {
     const manifestSpin = spinner("Fetching marketplace.json");
     let manifestContent;
     try {
-        const res = await fetch(manifestUrl);
+        const res = await githubFetch(manifestUrl);
         if (!res.ok) {
             manifestSpin.stop();
             console.error(red(`marketplace.json not found at ${owner}/${repo}\n`) +
@@ -1326,7 +1390,7 @@ async function installRepoPlugin(ownerRepo, pluginName, opts, overrideSource) {
     const manifestSpin = spinner("Fetching marketplace.json");
     let manifestContent;
     try {
-        const res = await fetch(manifestUrl);
+        const res = await githubFetch(manifestUrl);
         if (!res.ok) {
             manifestSpin.stop();
             throw new Error(`marketplace.json not found at ${owner}/${repo}. ` +
@@ -1347,7 +1411,7 @@ async function installRepoPlugin(ownerRepo, pluginName, opts, overrideSource) {
         // Not in marketplace.json — probe plugins/<name>/ folder in the repo
         const probeSpin = spinner(`Looking for "${pluginName}" folder in repo`);
         try {
-            const probeRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/contents/plugins/${pluginName}`, { headers: { "User-Agent": "vskill-cli" } });
+            const probeRes = await githubFetch(`https://api.github.com/repos/${owner}/${repo}/contents/plugins/${pluginName}`, { headers: { "User-Agent": "vskill-cli" } });
             if (probeRes.ok) {
                 const data = await probeRes.json();
                 if (Array.isArray(data)) {
@@ -1387,7 +1451,7 @@ async function installRepoPlugin(ownerRepo, pluginName, opts, overrideSource) {
     let skillEntries = [];
     let flatLayout = false;
     try {
-        const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/contents/${pluginPath}/skills`, { headers: { "User-Agent": "vskill-cli" } });
+        const res = await githubFetch(`https://api.github.com/repos/${owner}/${repo}/contents/${pluginPath}/skills`, { headers: { "User-Agent": "vskill-cli" } });
         if (res.ok) {
             skillEntries = (await res.json()).filter((e) => e.type === "dir");
         }
@@ -1396,7 +1460,7 @@ async function installRepoPlugin(ownerRepo, pluginName, opts, overrideSource) {
     // Flat layout fallback: check for SKILL.md directly at plugin root
     if (skillEntries.length === 0) {
         try {
-            const res = await fetch(`https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${pluginPath}/SKILL.md`);
+            const res = await githubFetch(`https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${pluginPath}/SKILL.md`);
             if (res.ok) {
                 flatLayout = true;
                 skillEntries = [{ name: pluginName, type: "dir" }];
@@ -1406,7 +1470,7 @@ async function installRepoPlugin(ownerRepo, pluginName, opts, overrideSource) {
     }
     let cmdEntries = [];
     try {
-        const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/contents/${pluginPath}/commands`, { headers: { "User-Agent": "vskill-cli" } });
+        const res = await githubFetch(`https://api.github.com/repos/${owner}/${repo}/contents/${pluginPath}/commands`, { headers: { "User-Agent": "vskill-cli" } });
         if (res.ok) {
             cmdEntries = (await res.json()).filter((e) => e.name.endsWith(".md"));
         }
@@ -1433,7 +1497,7 @@ async function installRepoPlugin(ownerRepo, pluginName, opts, overrideSource) {
             ? `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${pluginPath}/SKILL.md`
             : `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${pluginPath}/skills/${entry.name}/SKILL.md`;
         try {
-            const res = await fetch(rawUrl);
+            const res = await githubFetch(rawUrl);
             if (res.ok) {
                 const content = await res.text();
                 skills.push({ name: entry.name, content });
@@ -1446,7 +1510,7 @@ async function installRepoPlugin(ownerRepo, pluginName, opts, overrideSource) {
     for (const entry of cmdEntries) {
         const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${pluginPath}/commands/${entry.name}`;
         try {
-            const res = await fetch(rawUrl);
+            const res = await githubFetch(rawUrl);
             if (res.ok) {
                 const content = await res.text();
                 commands.push({ name: entry.name, content });
@@ -1630,7 +1694,7 @@ export async function addCommand(source, opts) {
                 const pluginPath = plugin.source.replace(/^\.\//, "");
                 const subpath = `${pluginPath}/skills/${threeSkill}/SKILL.md`;
                 const probeUrl = `https://raw.githubusercontent.com/${threeOwner}/${threeRepo}/${branch}/${subpath}`;
-                const probeRes = await fetch(probeUrl);
+                const probeRes = await githubFetch(probeUrl);
                 if (probeRes.ok) {
                     return installSingleSkillLegacy(threeOwner, threeRepo, threeSkill, opts, subpath, plugin.name);
                 }
@@ -2157,7 +2221,7 @@ async function installSingleSkillLegacy(owner, repo, skill, opts, skillSubpathOv
                 ? skillSubpathOverride.replace(/\/SKILL\.md$/, "/agents")
                 : `skills/${skill}/agents`;
             const agentsDirUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${agentsBasePath}`;
-            const dirRes = await fetch(agentsDirUrl, { headers: { Accept: "application/vnd.github.v3+json" } });
+            const dirRes = await githubFetch(agentsDirUrl, { headers: { Accept: "application/vnd.github.v3+json" } });
             if (dirRes.ok) {
                 const entries = (await dirRes.json());
                 const mdEntries = entries.filter((e) => e.name.endsWith(".md") && e.download_url && isGitHubDownloadUrl(e.download_url));
@@ -2165,7 +2229,7 @@ async function installSingleSkillLegacy(owner, repo, skill, opts, skillSubpathOv
                     legacyAgentFiles = {};
                     const fetches = mdEntries.map(async (entry) => {
                         try {
-                            const res = await fetch(entry.download_url);
+                            const res = await githubFetch(entry.download_url);
                             if (res.ok)
                                 legacyAgentFiles[`agents/${entry.name}`] = await res.text();
                         }