vskill 1.0.13 → 1.0.15

package/README.md

@@ -9,8 +9,8 @@
   <a href="https://www.npmjs.com/package/vskill"><img src="https://img.shields.io/npm/v/vskill?color=cb3837&logo=npm" alt="npm" /></a>
   <a href="https://www.npmjs.com/package/vskill"><img src="https://img.shields.io/npm/dw/vskill?color=cb3837&logo=npm&label=downloads" alt="downloads" /></a>
   <img src="https://img.shields.io/badge/agents-53_platforms-0969DA" alt="53 agents" />
-  <img src="https://img.shields.io/badge/plugins-8-8B5CF6" alt="8 plugins" />
-  <img src="https://img.shields.io/badge/skills-14-10B981" alt="14 skills" />
+  <img src="https://img.shields.io/badge/plugins-9-8B5CF6" alt="9 plugins" />
+  <img src="https://img.shields.io/badge/skills-16-10B981" alt="16 skills" />
   <a href="https://verified-skill.com"><img src="https://img.shields.io/badge/registry-verified--skill.com-F59E0B" alt="registry" /></a>
   <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT" />
 </p>
@@ -133,12 +133,73 @@ npx vskill@latest skill new            # create a new skill (AI-assisted)
 npx vskill@latest eval sweep <skill>   # benchmark across models
 npx vskill@latest audit --ci           # SARIF v2.1.0 for CI
 npx vskill@latest keys set anthropic   # store API keys in ~/.vskill/keys.env
+npx vskill@latest auth login           # sign in to GitHub for private skills
 ```
 
 Full reference → [verified-skill.com/docs/cli-reference](https://verified-skill.com/docs/cli-reference)
 
 <br/>
 
+## Authentication (GitHub, for private skills)
+
+`vskill auth` signs you in to GitHub using the official Device Flow so the CLI
+can install skills from private repos and the local Studio can list your org's
+private catalog.
+
+```bash
+npx vskill@latest auth login    # interactive Device Flow — copy code, visit URL
+npx vskill@latest auth status   # show the current GitHub identity
+npx vskill@latest auth logout   # forget the GitHub token
+```
+
+How it works:
+
+1. `vskill auth login` requests a device + user code from `github.com/login/device/code`.
+2. You visit `https://github.com/login/device` and enter the 8-character code (rendered as `XXXX-XXXX`).
+3. The CLI polls `github.com/login/oauth/access_token` until you authorize, then validates against `api.github.com/user`.
+4. The resulting token is stored in your **OS keychain** (macOS Keychain / Windows DPAPI / libsecret).
+   On systems without a keyring daemon, the token falls back to `~/.vskill/keys.env` with mode `0600` and a startup warning.
+
+Where the token is used:
+
+- **`vskill install <github-url>`** — added as `Authorization: Bearer …` on every fetch to `api.github.com` and `raw.githubusercontent.com`. Public skills still install anonymously.
+- **`vskill studio`** — the local eval-server proxies private routes (`/api/v1/private/*`, `/api/v1/tenants/*`) to verified-skill.com with the bearer header injected at the proxy boundary. Your browser never holds the token.
+
+Configuration:
+
+- `VSKILL_GITHUB_CLIENT_ID` — the OAuth/App `client_id` used during Device Flow. Defaults are baked in for the public Skill Studio App; set this only if you are running a self-hosted variant.
+
+Inspect status of all credentials in one place:
+
+```bash
+npx vskill@latest keys list      # shows AI provider keys + the github slot
+```
+
+### Private skill workflow
+
+Once authenticated, installing a private org skill is identical to a public one — the CLI silently attaches the keychain token to every `api.github.com` and `raw.githubusercontent.com` request:
+
+```bash
+npx vskill@latest auth login                                # one-time setup
+npx vskill@latest add https://github.com/<org>/<repo>       # private skill installs same as public
+```
+
+The local skill bundle on disk **never contains** your GitHub token — the token is used only at fetch time. Your project's `vskill.lock` records `source: "private"` and the org name so future updates re-authenticate correctly.
+
+Customer-facing setup walkthrough → [`.specweave/docs/external/private-repos-quickstart.md`](../../../.specweave/docs/external/private-repos-quickstart.md) (in the umbrella repo).
+
+## Security & Compliance
+
+Skill Studio private-repo support (increment 0826) ships with documented threat model, verification checklist, SOC 2 evidence map, and operational runbooks — all in the umbrella repo under `.specweave/docs/`:
+
+- **Customer quickstart** — `.specweave/docs/external/private-repos-quickstart.md`
+- **Vendor security questionnaire** — `.specweave/docs/external/security-questionnaire-template.md`
+- **Threat model & verification checklist** — `.specweave/docs/internal/security/0826-*.md`
+- **SOC 2 evidence map** — `.specweave/docs/internal/compliance/0826-soc2-evidence-map.md`
+- **Operations + rotation runbooks** — `.specweave/docs/internal/runbooks/0826-*.md`
+
+<br/>
+
 ## Recent highlights (0.5.x)
 
 - **0.5.129** — Studio Publish: one-click `git push` + open verified-skill.com submit pre-filled

package/agents.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-04-30T05:35:27.559Z",
+  "generatedAt": "2026-05-04T18:28:29.605Z",
   "agentPrefixes": [
     ".adal",
     ".agent",

package/dist/clone/github-scaffold.d.ts

@@ -0,0 +1,38 @@
+export interface RunGhResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+export type RunGh = (args: string[], opts?: {
+    cwd?: string;
+}) => Promise<RunGhResult>;
+export interface ScaffoldGitHubArgs {
+    /** Local path to the directory that will become the GitHub repo root. */
+    pluginDir: string;
+    /** Repo name (without owner). The owner is whatever `gh` is currently authenticated as. */
+    repoName: string;
+    /** Optional repo description (passed to `gh repo create -d`). */
+    description?: string;
+    /** Whether the new repo should be public. Defaults to true. */
+    public?: boolean;
+    /** Injectable `gh` adapter — defaults to spawning the local `gh` binary. */
+    runGh?: RunGh;
+}
+export interface ScaffoldGitHubResult {
+    skipped: boolean;
+    /** When skipped, a short human-readable reason. */
+    reason?: string;
+    /** Repo URL when the create step succeeded. */
+    repoUrl?: string;
+    /** Argv recorded for each `gh` invocation — useful for debugging and tests. */
+    invocations: string[][];
+}
+/**
+ * Run `gh repo create <name> --public/--private --source <pluginDir> --push`.
+ *
+ * The `--source <dir> --push` form initializes a git repo if needed and pushes
+ * the initial commit in one step. When `gh` is missing or the create step
+ * fails, the function resolves with `skipped: true` and a clear reason —
+ * never throws.
+ */
+export declare function scaffoldGitHub(args: ScaffoldGitHubArgs): Promise<ScaffoldGitHubResult>;

package/dist/clone/github-scaffold.js

@@ -0,0 +1,108 @@
+// ---------------------------------------------------------------------------
+// vskill clone — github-scaffold
+// ---------------------------------------------------------------------------
+// Optional `gh repo create` + initial commit/push for a freshly-scaffolded
+// new-plugin directory. The `runGh` adapter is injectable so unit tests can
+// substitute a recording fake; the default adapter shells out to the local
+// `gh` binary via node:child_process.
+//
+// Failure modes:
+//   - `gh` not installed (ENOENT) → resolve with { skipped: true, reason }
+//   - `gh repo create` rejects (non-zero exit) → resolve with { skipped: true, reason }
+//
+// In both cases the on-disk plugin remains intact — the orchestrator surfaces
+// the warning but reports the overall clone as a success (AC-US3-02).
+//
+// Sequencing: this function is called ONLY after the plugin's `.tmp` has been
+// atomically renamed into place (AC-US3-03), so a partial-state failure here
+// can never corrupt the destination plugin.
+// ---------------------------------------------------------------------------
+import { spawn } from "node:child_process";
+/**
+ * Default `runGh` adapter — spawn the local `gh` binary.
+ *
+ * Surfacing semantics: never throws on a non-zero exit. ENOENT (binary not on
+ * PATH) is forwarded as a thrown error so the caller can convert it to a
+ * graceful skip with a clear "gh not installed" message.
+ */
+function defaultRunGh(args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("gh", args, {
+            cwd: opts.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (err) => {
+            reject(err);
+        });
+        child.on("close", (code) => {
+            resolve({ stdout, stderr, code: code ?? 0 });
+        });
+    });
+}
+function isENOENT(err) {
+    return Boolean(err) && err.code === "ENOENT";
+}
+/**
+ * Run `gh repo create <name> --public/--private --source <pluginDir> --push`.
+ *
+ * The `--source <dir> --push` form initializes a git repo if needed and pushes
+ * the initial commit in one step. When `gh` is missing or the create step
+ * fails, the function resolves with `skipped: true` and a clear reason —
+ * never throws.
+ */
+export async function scaffoldGitHub(args) {
+    const runGh = args.runGh ?? defaultRunGh;
+    const isPublic = args.public !== false;
+    const visibilityFlag = isPublic ? "--public" : "--private";
+    const invocations = [];
+    const createArgv = ["repo", "create", args.repoName, visibilityFlag];
+    if (args.description) {
+        createArgv.push("--description", args.description);
+    }
+    // --source + --push will initialize a git repo (if absent), commit, and push.
+    createArgv.push("--source", args.pluginDir, "--push");
+    let createResult;
+    try {
+        invocations.push([...createArgv]);
+        createResult = await runGh(createArgv, { cwd: args.pluginDir });
+    }
+    catch (err) {
+        if (isENOENT(err)) {
+            return {
+                skipped: true,
+                reason: "gh CLI not installed (binary not found on PATH)",
+                invocations,
+            };
+        }
+        return {
+            skipped: true,
+            reason: `gh invocation failed: ${err.message}`,
+            invocations,
+        };
+    }
+    if (createResult.code !== 0) {
+        return {
+            skipped: true,
+            reason: `gh repo create exited ${createResult.code}: ${createResult.stderr.trim() || createResult.stdout.trim()}`,
+            invocations,
+        };
+    }
+    // `gh repo create --source --push` prints the repo URL to stdout. The exact
+    // line varies but always contains a `https://github.com/<owner>/<name>`
+    // segment — extract the first such occurrence as the repoUrl.
+    const urlMatch = createResult.stdout.match(/https:\/\/github\.com\/[\w.-]+\/[\w.-]+/);
+    return {
+        skipped: false,
+        repoUrl: urlMatch ? urlMatch[0] : undefined,
+        invocations,
+    };
+}
+//# sourceMappingURL=github-scaffold.js.map

package/dist/clone/github-scaffold.js.map

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

package/dist/clone/provenance-fork.d.ts

@@ -0,0 +1,34 @@
+import type { Provenance } from "../studio/types.js";
+import type { ForkProvenance } from "./types.js";
+export interface WriteForkProvenanceArgs {
+    /** Where to write the .vskill-meta.json (typically the .tmp staging dir). */
+    targetSkillDir: string;
+    /** New `forkedFrom` record describing the immediate parent. */
+    forkedFrom: ForkProvenance;
+    /** Optional pre-read source provenance — when omitted, the helper reads it from `sourceSkillDir`. */
+    sourceProvenance?: Provenance | null;
+    /** Source skill directory. Used to read prior sidecar when `sourceProvenance` is not supplied. */
+    sourceSkillDir?: string;
+    /** Source absolute path — recorded as `sourcePath` for compatibility with the existing schema. */
+    sourcePath: string;
+    /** Source version — recorded as `sourceSkillVersion`. */
+    sourceVersion?: string;
+}
+/**
+ * Compute the merged Provenance object for a fresh fork without writing.
+ * Exposed for unit tests and dry-run mode.
+ */
+export declare function computeForkProvenance(args: {
+    forkedFrom: ForkProvenance;
+    sourceProvenance: Provenance | null;
+    sourcePath: string;
+    sourceVersion?: string;
+}): Provenance;
+/**
+ * Read the source skill's existing `.vskill-meta.json` (if any), compute the
+ * merged fork provenance, and write it to the target directory's sidecar.
+ *
+ * The write is delegated to `writeProvenance` so the on-disk JSON shape is
+ * identical to every other vskill flow that produces a sidecar.
+ */
+export declare function writeForkProvenance(args: WriteForkProvenanceArgs): Promise<Provenance>;

package/dist/clone/provenance-fork.js

@@ -0,0 +1,97 @@
+// ---------------------------------------------------------------------------
+// vskill clone — provenance-fork
+// ---------------------------------------------------------------------------
+// Thin helper around the existing `writeProvenance` / `readProvenance`
+// primitives in src/studio/lib/provenance.ts. Computes the `forkedFrom`,
+// `originalSource`, and `forkChain` fork-lineage fields for a cloned skill,
+// then delegates the write to `writeProvenance` so the on-disk format is
+// unchanged.
+//
+// Lineage rules (settled in plan.md §3 + spec AC-US5-02):
+//   - `forkedFrom` always refers to the IMMEDIATE parent we just copied from.
+//   - `forkChain[]` is the ancestry trail. When the source was already a fork
+//     (i.e. its existing sidecar has a `forkedFrom`), append the source's
+//     `forkedFrom.source` to the source's prior `forkChain[]`. When the
+//     source was a root (no sidecar or no `forkedFrom`), `forkChain` is left
+//     undefined.
+//   - `originalSource` is carried forward unchanged from the source's sidecar
+//     when present (it always points to the chain's deepest known ancestor).
+//
+// Existing `Provenance` fields written by other vskill flows
+// (`promotedFrom`, `sourcePath`, `promotedAt`, `sourceSkillVersion`) are
+// preserved when present on the source's sidecar, with sensible defaults
+// for fresh clones.
+//
+// See ADR 0688-02 (sidecar provenance) for the underlying contract.
+// ---------------------------------------------------------------------------
+import { readProvenance, writeProvenance } from "../studio/lib/provenance.js";
+/**
+ * Compute the merged Provenance object for a fresh fork without writing.
+ * Exposed for unit tests and dry-run mode.
+ */
+export function computeForkProvenance(args) {
+    const { forkedFrom, sourceProvenance, sourcePath, sourceVersion } = args;
+    const next = {
+        // The existing schema requires these — for a brand-new fork the sensible
+        // defaults are "global" (the cloned skill is now globally-authored by the
+        // new author) and a fresh timestamp. When the source has its own sidecar,
+        // we DO NOT inherit its `promotedFrom`/`sourcePath` because those refer
+        // to the source's own promotion lineage, not the fork's.
+        promotedFrom: "global",
+        sourcePath,
+        promotedAt: Date.now(),
+        sourceSkillVersion: sourceVersion ?? forkedFrom.version,
+        forkedFrom: { ...forkedFrom },
+    };
+    if (!sourceProvenance) {
+        // Source is a root (no prior sidecar) — no forkChain, no originalSource.
+        return next;
+    }
+    // Carry forward originalSource unchanged when present. It always points to
+    // the chain's deepest known ancestor, so it is invariant under forking.
+    if (sourceProvenance.originalSource) {
+        next.originalSource = { ...sourceProvenance.originalSource };
+    }
+    if (sourceProvenance.forkedFrom) {
+        // Source itself was a fork — extend the chain by its `forkedFrom.source`.
+        // Order: oldest-first (the deepest ancestor is `forkChain[0]`, the most
+        // recent intermediate parent — i.e. the source's own forkedFrom — is the
+        // last entry). This ordering is consistent across rounds because each
+        // clone appends only one entry.
+        const priorChain = Array.isArray(sourceProvenance.forkChain)
+            ? [...sourceProvenance.forkChain]
+            : [];
+        priorChain.push(sourceProvenance.forkedFrom.source);
+        next.forkChain = priorChain;
+        // If the source had no `originalSource` recorded but did have a chain,
+        // synthesize one pointing at the chain head (best available ancestor).
+        if (!next.originalSource && priorChain.length > 0) {
+            next.originalSource = { skillPath: priorChain[0] };
+        }
+    }
+    return next;
+}
+/**
+ * Read the source skill's existing `.vskill-meta.json` (if any), compute the
+ * merged fork provenance, and write it to the target directory's sidecar.
+ *
+ * The write is delegated to `writeProvenance` so the on-disk JSON shape is
+ * identical to every other vskill flow that produces a sidecar.
+ */
+export async function writeForkProvenance(args) {
+    let sourceProvenance = args.sourceProvenance ?? null;
+    if (sourceProvenance === undefined || (sourceProvenance === null && args.sourceSkillDir)) {
+        if (args.sourceSkillDir) {
+            sourceProvenance = await readProvenance(args.sourceSkillDir);
+        }
+    }
+    const merged = computeForkProvenance({
+        forkedFrom: args.forkedFrom,
+        sourceProvenance,
+        sourcePath: args.sourcePath,
+        sourceVersion: args.sourceVersion,
+    });
+    await writeProvenance(args.targetSkillDir, merged);
+    return merged;
+}
+//# sourceMappingURL=provenance-fork.js.map

package/dist/clone/provenance-fork.js.map

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

package/dist/clone/reference-scanner.d.ts

@@ -0,0 +1,19 @@
+import type { ReferenceMatch } from "./types.js";
+export interface ScanOptions {
+    /** Old fully-qualified skill name (e.g. "sw/ado-mapper" or "ado-mapper"). */
+    oldSkillName: string;
+    /** Logical filename (relative to skill root) — recorded in each match. */
+    file?: string;
+}
+/**
+ * Scan SKILL.md content for cross-skill references and self-name occurrences.
+ * Returns matches in document order with line numbers (1-indexed).
+ */
+export declare function scanReferences(content: string, opts: ScanOptions): ReferenceMatch[];
+/**
+ * Scan for literal occurrences of the OLD skill name in prose.
+ * Suppressed inside fenced code blocks. Returned as a separate array because
+ * it's informational at a different level (manual rename candidates, not
+ * cross-skill dependencies).
+ */
+export declare function scanSelfNameOccurrences(content: string, opts: ScanOptions): ReferenceMatch[];

package/dist/clone/reference-scanner.js

@@ -0,0 +1,144 @@
+// ---------------------------------------------------------------------------
+// vskill clone — reference-scanner (READ-ONLY)
+// ---------------------------------------------------------------------------
+// Detects cross-skill reference patterns and self-name occurrences in
+// SKILL.md prose. **Reports only — never rewrites anything.** The orchestrator
+// appends the report to the success summary so the user can decide what to do.
+//
+// Patterns:
+//   - backtick:       `sw:foo`             (single-backtick inline code)
+//   - skill-call:     Skill({ skill: "sw:foo" })  /  Skill({ skill: 'sw:foo' })
+//   - slash-command:  /sw:foo
+//   - self-name:      literal occurrence of the OLD skill name in prose
+//
+// False-positive guard: matches inside fenced code blocks (```...```) are
+// excluded for the slash-command and self-name patterns. Backtick and
+// Skill({...}) patterns are themselves code-shaped, so they are reported
+// unconditionally — that's the user's signal that an actual cross-skill
+// dependency exists in the source.
+//
+// See spec.md AC-US1-04, plan.md §6.
+// ---------------------------------------------------------------------------
+const BACKTICK_RE = /`([a-z][a-z0-9-]*:[a-z][a-z0-9-]*)`/g;
+const SKILL_CALL_RE = /Skill\s*\(\s*\{\s*skill\s*:\s*["']([^"']+)["']/g;
+const SLASH_COMMAND_RE = /(?:^|\s)(\/[a-z][a-z0-9-]*:[a-z][a-z0-9-]*)\b/g;
+/**
+ * Build a regex that matches the OLD skill name as a whole "word", where word
+ * boundaries here mean the surrounding chars are not [A-Za-z0-9-/] (so
+ * "ado-mapper" matches but "ado-mapperx" or "my-ado-mapper-thing" do not).
+ *
+ * The `oldSkillName` is escaped before being embedded in the pattern so any
+ * regex metacharacters in the skill name are treated literally.
+ */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Detect lines covered by fenced code blocks (triple-backtick). Returns a Set
+ * of 1-indexed line numbers that are INSIDE a fence. Used to suppress
+ * slash-command and self-name false positives that live in code samples.
+ *
+ * The opening/closing fence lines themselves are also considered "inside"
+ * for the purpose of suppression — they don't contain meaningful prose
+ * references, so this is a deliberate slight overreach.
+ */
+function computeFencedLines(lines) {
+    const fenced = new Set();
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trimStart();
+        if (trimmed.startsWith("```")) {
+            // The fence-opening line and fence-closing line are both fenced.
+            fenced.add(i + 1);
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            fenced.add(i + 1);
+    }
+    return fenced;
+}
+/**
+ * Scan SKILL.md content for cross-skill references and self-name occurrences.
+ * Returns matches in document order with line numbers (1-indexed).
+ */
+export function scanReferences(content, opts) {
+    const file = opts.file ?? "SKILL.md";
+    const normalized = content.replace(/^/, "").replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    const fenced = computeFencedLines(lines);
+    const out = [];
+    // Pattern 1: backtick `sw:foo` — reported unconditionally (already code-shaped).
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        BACKTICK_RE.lastIndex = 0;
+        let m;
+        while ((m = BACKTICK_RE.exec(line)) !== null) {
+            out.push({ file, line: i + 1, match: m[1], kind: "backtick" });
+        }
+    }
+    // Pattern 2: Skill({ skill: "sw:foo" }) — reported unconditionally.
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        SKILL_CALL_RE.lastIndex = 0;
+        let m;
+        while ((m = SKILL_CALL_RE.exec(line)) !== null) {
+            out.push({ file, line: i + 1, match: m[1], kind: "skill-call" });
+        }
+    }
+    // Pattern 3: /sw:foo — slash-command. Suppressed inside fenced code blocks.
+    for (let i = 0; i < lines.length; i++) {
+        if (fenced.has(i + 1))
+            continue;
+        const line = lines[i];
+        SLASH_COMMAND_RE.lastIndex = 0;
+        let m;
+        while ((m = SLASH_COMMAND_RE.exec(line)) !== null) {
+            // Strip the leading "/" so the recorded match is the bare slash-command name.
+            const matched = m[1];
+            out.push({ file, line: i + 1, match: matched, kind: "slash-command" });
+        }
+    }
+    return out;
+}
+/**
+ * Scan for literal occurrences of the OLD skill name in prose.
+ * Suppressed inside fenced code blocks. Returned as a separate array because
+ * it's informational at a different level (manual rename candidates, not
+ * cross-skill dependencies).
+ */
+export function scanSelfNameOccurrences(content, opts) {
+    const file = opts.file ?? "SKILL.md";
+    const normalized = content.replace(/^/, "").replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    const fenced = computeFencedLines(lines);
+    // The full name may contain "/" (e.g. "sw/ado-mapper") — we scan for both
+    // the bare skill segment and the full name. Bare segment first ensures we
+    // catch occurrences like "the ado-mapper does X" in prose.
+    const slashIdx = opts.oldSkillName.indexOf("/");
+    const bareSkill = slashIdx >= 0 ? opts.oldSkillName.slice(slashIdx + 1) : opts.oldSkillName;
+    const patterns = new Set();
+    patterns.add(opts.oldSkillName);
+    if (bareSkill !== opts.oldSkillName)
+        patterns.add(bareSkill);
+    const out = [];
+    for (const pattern of patterns) {
+        const escaped = escapeRegex(pattern);
+        // Word-boundary that treats letters, digits, hyphen, slash as part of the "word".
+        // (?<![A-Za-z0-9-/])  — preceded by neither a name char nor a slash
+        // (?![A-Za-z0-9-/])   — followed by neither a name char nor a slash
+        const re = new RegExp(`(?<![A-Za-z0-9\\-/])${escaped}(?![A-Za-z0-9\\-/])`, "g");
+        for (let i = 0; i < lines.length; i++) {
+            if (fenced.has(i + 1))
+                continue;
+            const line = lines[i];
+            re.lastIndex = 0;
+            let m;
+            while ((m = re.exec(line)) !== null) {
+                out.push({ file, line: i + 1, match: m[0], kind: "self-name" });
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=reference-scanner.js.map

package/dist/clone/reference-scanner.js.map

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

package/dist/clone/skill-locator.d.ts

@@ -0,0 +1,26 @@
+import type { SkillSource } from "./types.js";
+export interface LocateOptions {
+    /** Working directory to use as the project root (defaults to process.cwd()). */
+    cwd?: string;
+    /** Home directory (defaults to os.homedir() — explicit for testability). */
+    home: string;
+}
+/**
+ * Split a source identifier like "sw/ado-mapper" into namespace + skill, or
+ * return only the skill when no namespace is present.
+ */
+export declare function parseSourceIdent(source: string): {
+    namespace?: string;
+    skill: string;
+};
+/**
+ * Discover a skill across project / personal / cache. Returns every match in
+ * search order — the orchestrator handles disambiguation when there is more
+ * than one and `--source` was not explicitly provided.
+ */
+export declare function locateSkill(source: string, opts: LocateOptions): Promise<SkillSource[]>;
+/**
+ * Enumerate every skill inside a cached plugin. Used by the whole-plugin
+ * clone path (T-010). Returns a list of SkillSource entries (one per skill).
+ */
+export declare function enumeratePluginSkills(pluginName: string, opts: LocateOptions): Promise<SkillSource[]>;