summer-engine 3.1.0 → 3.2.0

package/dist/core/library-read.d.ts

@@ -1,11 +1,15 @@
 import { z } from "zod";
-import { type LibrarySearchDeps } from "./library-search.js";
+import { type LibraryIndexEntry, type LibrarySearchDeps } from "./library-search.js";
 import { type TemplateEntry } from "./templates.js";
 export declare const READ_PARTS: readonly ["skill", "resource", "all"];
 export type ReadPart = (typeof READ_PARTS)[number];
 /** How many content_hash hex chars the footer's entry_id carries. */
 export declare const FOOTER_HASH_LENGTH = 12;
 export declare const FOOTER_SUFFIX = "If this entry is wrong, stale, or you deviate from it, report via summer_library_feedback.";
+/** Text files read_library loads when an entry links them. */
+export declare const LINKED_FILE_EXTENSIONS: ReadonlySet<string>;
+/** A linked file larger than this is refused rather than dumped. */
+export declare const LINKED_FILE_MAX_BYTES: number;
 export declare const readLibraryInputShape: {
     id: z.ZodString;
     part: z.ZodOptional<z.ZodEnum<["skill", "resource", "all"]>>;
@@ -15,10 +19,10 @@ export declare const readLibraryInputSchema: z.ZodObject<{
     part: z.ZodOptional<z.ZodEnum<["skill", "resource", "all"]>>;
 }, "strict", z.ZodTypeAny, {
     id: string;
-    part?: "all" | "skill" | "resource" | undefined;
+    part?: "all" | "resource" | "skill" | undefined;
 }, {
     id: string;
-    part?: "all" | "skill" | "resource" | undefined;
+    part?: "all" | "resource" | "skill" | undefined;
 }>;
 export type ReadLibraryArgs = z.infer<typeof readLibraryInputSchema>;
 export interface LibraryReadDeps extends LibrarySearchDeps {
@@ -44,6 +48,15 @@ export interface LibraryReadOk {
     files: string[];
     /** The file the body came from, when the body is a file. */
     body_file?: string;
+    /** Set when the load is a file the entry ships rather than the entry body:
+     *  its path inside the entry directory, e.g. "references/kit-placement-tools.md". */
+    linked_file?: string;
+    /** Relative links in the body and the summer_read_library id that loads
+     *  each (null: the target is not shipped with this package). */
+    links?: Array<{
+        target: string;
+        id: string | null;
+    }>;
     /** Tool records: how to reach it. */
     mcp_tool_name?: string;
     cli_command?: string;
@@ -67,7 +80,26 @@ export type LibraryReadResult = LibraryReadOk | LibraryReadNotFound;
 export declare function feedbackFooter(id: string, contentHash: string | undefined): string;
 export declare function entryIdWithHash(id: string, contentHash: string | undefined): string;
 /**
- * Read one entry. `deps.entries`/`deps.packageRoot`/`deps.templates` let
- * tests point at a fixture; production reads the installed package.
+ * Relative link targets in a markdown body: markdown links outside code
+ * (`[x](references/y.md)`, fragment dropped) and inline code spans that name a
+ * library file by a relative path (`../../references/gd-style/gd-style.md`,
+ * `references/y.md`; a `./scripts/x.gd` span is a project path and is not
+ * one). URLs, anchors, absolute paths and fenced code blocks are skipped.
+ * Exported for the every-link-resolves test.
+ */
+export declare function relativeLinkTargets(markdown: string): string[];
+/**
+ * Where a link written in `fromFile` (a path inside `entry`'s directory, ""
+ * or "SKILL.md" for the body) points, as the id summer_read_library loads it
+ * by; null when the target is not shipped inside library/.
+ */
+export declare function resolveLibraryLink(entry: LibraryIndexEntry, fromFile: string, link: string, deps: {
+    entries: LibraryIndexEntry[];
+    packageRoot?: string;
+}): string | null;
+/**
+ * Read one entry, or a file an entry links. `deps.entries`/`deps.packageRoot`/
+ * `deps.templates` let tests point at a fixture; production reads the
+ * installed package.
  */
 export declare function readLibraryEntry(requestedId: string, part?: ReadPart, deps?: LibraryReadDeps): Promise<LibraryReadResult>;

package/dist/core/library-read.js

@@ -23,9 +23,18 @@
  * Metadata comes from registry/generated/index.json (no YAML parser at
  * runtime); resource.yaml is returned as text. Unknown id -> not_found with
  * the three nearest ids from searchLibrary.
+ *
+ * Linked files: a body links files its entry ships (a skill's
+ * `references/kit-placement-tools.md`) and other entries
+ * (`../multiplayer-project/SKILL.md`, `../../references/gd-style/gd-style.md`).
+ * Each loads by `<entry id>/<link as written>`, resolved inside library/ only
+ * and for text files only; by the relative path alone when exactly one entry
+ * ships it; and `reference/<slug>` that is no entry falls back to the one
+ * `references/<slug>.md` an entry ships. A body render ends with its links and
+ * the id that loads each. A linked file's footer names its entry.
  */
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join, posix, sep } from "node:path";
 import { z } from "zod";
 import { LIBRARY_KIND_DIRS, loadLibraryIndex, searchLibrary, } from "./library-search.js";
 import { PACKAGE_ROOT } from "./package-root.js";
@@ -34,12 +43,30 @@ export const READ_PARTS = ["skill", "resource", "all"];
 /** How many content_hash hex chars the footer's entry_id carries. */
 export const FOOTER_HASH_LENGTH = 12;
 export const FOOTER_SUFFIX = "If this entry is wrong, stale, or you deviate from it, report via summer_library_feedback.";
+/** Text files read_library loads when an entry links them. */
+export const LINKED_FILE_EXTENSIONS = new Set([
+    ".md",
+    ".markdown",
+    ".txt",
+    ".yaml",
+    ".yml",
+    ".json",
+    ".gd",
+    ".gdshader",
+    ".shader",
+    ".cfg",
+    ".tscn",
+    ".tres",
+    ".csv",
+]);
+/** A linked file larger than this is refused rather than dumped. */
+export const LINKED_FILE_MAX_BYTES = 256 * 1024;
 export const readLibraryInputShape = {
     id: z
         .string()
         .min(1)
         .max(200)
-        .describe("The entry id as returned by summer_search_library: <kind>/<slug>, e.g. skill/vfx-water-ripple or tool/screenshot."),
+        .describe("The entry id as returned by summer_search_library: <kind>/<slug>, e.g. skill/vfx-water-ripple or tool/screenshot. A file an entry links loads by <entry id>/<link as written>, e.g. skill/spatial-placement/references/kit-placement-tools.md; the 'linked files' list at the end of a body gives each id."),
     part: z
         .enum(READ_PARTS)
         .optional()
@@ -71,6 +98,111 @@ function resolveEntry(requested, entries) {
     }
     return null;
 }
+const KIND_BY_DIR = new Map(Object.entries(LIBRARY_KIND_DIRS).map(([kind, dir]) => [dir, kind]));
+const ENTRY_PATH_ID = /^(tool|skill|example|template|collection|reference)\/([a-z0-9]+(?:-[a-z0-9]+)*)\/(.+)$/;
+function entryDirOf(entry) {
+    const kind = entry.kind;
+    return `library/${LIBRARY_KIND_DIRS[kind] ?? `${kind}s`}/${entry.id.split("/").pop()}`;
+}
+/** Join a link onto a package-relative directory; null when it is absolute,
+ *  malformed, or leaves library/. */
+function joinInsideLibrary(baseDir, link) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(link.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!decoded || /[\u0000-\u001f\\]/.test(decoded) || decoded.startsWith("/") || /^[a-z][a-z0-9+.-]*:/i.test(decoded))
+        return null;
+    const joined = posix.normalize(posix.join(baseDir, decoded)).replace(/\/+$/, "");
+    return joined === "library" || joined.startsWith("library/") ? joined : null;
+}
+/** library/<dir>/<slug>[/<file>] -> the entry and the file inside it. */
+function targetFromLibraryPath(libPath, entries) {
+    const parts = libPath.split("/");
+    if (parts.length < 3 || parts[0] !== "library")
+        return null;
+    const kind = KIND_BY_DIR.get(parts[1]);
+    if (!kind)
+        return null;
+    const entry = entries.find((e) => e.id === `${kind}/${parts[2]}`);
+    return entry ? { entry, file: parts.slice(3).join("/") } : null;
+}
+function isFileInsideLibrary(root, libPath) {
+    const abs = join(root, ...libPath.split("/"));
+    try {
+        if (!statSync(abs).isFile())
+            return false;
+        const libraryRoot = realpathSync(join(root, "library"));
+        return realpathSync(abs).startsWith(libraryRoot + sep);
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve an id that names a file an entry ships (see the module comment). */
+function resolveLinkedFile(requested, entries, root) {
+    const bare = requested.trim();
+    const qualified = ENTRY_PATH_ID.exec(bare);
+    if (qualified) {
+        const entry = entries.find((e) => e.id === `${qualified[1]}/${qualified[2]}`);
+        if (entry) {
+            const libPath = joinInsideLibrary(entryDirOf(entry), qualified[3]);
+            const target = libPath ? targetFromLibraryPath(libPath, entries) : null;
+            if (!target || (target.file !== "" && !isFileInsideLibrary(root, libPath)))
+                return null;
+            return target;
+        }
+    }
+    const shipping = (relative) => entries
+        .map((entry) => ({ entry, libPath: joinInsideLibrary(entryDirOf(entry), relative) }))
+        .filter((c) => !!c.libPath && c.libPath.startsWith(`${entryDirOf(c.entry)}/`))
+        .filter((c) => isFileInsideLibrary(root, c.libPath))
+        .map((c) => ({ entry: c.entry, file: c.libPath.slice(entryDirOf(c.entry).length + 1) }));
+    // A relative path alone, when exactly one entry ships that file.
+    if ((bare.includes("/") || /\.[a-z0-9]+$/i.test(bare)) && !bare.startsWith("../")) {
+        const found = shipping(bare.replace(/^\.\//, ""));
+        if (found.length === 1)
+            return found[0];
+    }
+    // reference/<slug> that is no entry: the references/<slug>.md one entry ships.
+    const asReference = /^references?\/([a-z0-9]+(?:[-_][a-z0-9]+)*)(?:\.md)?$/.exec(bare);
+    if (asReference) {
+        const found = shipping(`references/${asReference[1]}.md`);
+        if (found.length === 1)
+            return found[0];
+    }
+    return null;
+}
+/**
+ * Relative link targets in a markdown body: markdown links outside code
+ * (`[x](references/y.md)`, fragment dropped) and inline code spans that name a
+ * library file by a relative path (`../../references/gd-style/gd-style.md`,
+ * `references/y.md`; a `./scripts/x.gd` span is a project path and is not
+ * one). URLs, anchors, absolute paths and fenced code blocks are skipped.
+ * Exported for the every-link-resolves test.
+ */
+export function relativeLinkTargets(markdown) {
+    const out = new Set();
+    const text = markdown.replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, "");
+    for (const match of text.matchAll(/`([^`\n]+)`/g)) {
+        const span = match[1].trim();
+        if (/^((\.\.\/)+|(\.\/)?references\/)[^\s*?<>|]+\.[A-Za-z0-9]+$/.test(span))
+            out.add(span);
+    }
+    const prose = text.replace(/`[^`\n]*`/g, "");
+    for (const match of prose.matchAll(/\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g)) {
+        const target = match[1];
+        if (target.startsWith("#") || target.startsWith("/") || /^[a-z][a-z0-9+.-]*:/i.test(target))
+            continue;
+        const path = target.split("#")[0];
+        if (path)
+            out.add(path);
+    }
+    return [...out];
+}
 // ── Rendering ──────────────────────────────────────────────────────────────
 function readText(file) {
     try {
@@ -109,6 +241,41 @@ function pickBodyFile(kind, slug, dir) {
             return null;
     }
 }
+/** The summer_read_library id that loads a target: the entry id for the
+ *  entry itself or its body file, else <entry id>/<file>. */
+function canonicalId(target, root) {
+    if (target.file === "")
+        return target.entry.id;
+    const slug = target.entry.id.split("/").pop();
+    const body = pickBodyFile(target.entry.kind, slug, join(root, ...entryDirOf(target.entry).split("/")));
+    return target.file === body ? target.entry.id : `${target.entry.id}/${target.file}`;
+}
+/**
+ * Where a link written in `fromFile` (a path inside `entry`'s directory, ""
+ * or "SKILL.md" for the body) points, as the id summer_read_library loads it
+ * by; null when the target is not shipped inside library/.
+ */
+export function resolveLibraryLink(entry, fromFile, link, deps) {
+    const root = deps.packageRoot ?? PACKAGE_ROOT;
+    const libPath = joinInsideLibrary(posix.dirname(posix.join(entryDirOf(entry), fromFile || "_")), link);
+    if (!libPath)
+        return null;
+    const target = targetFromLibraryPath(libPath, deps.entries);
+    if (!target)
+        return null;
+    if (target.file !== "" && !isFileInsideLibrary(root, libPath))
+        return null;
+    return canonicalId(target, root);
+}
+function linksOf(body, entry, fromFile, entries, root) {
+    return relativeLinkTargets(body).map((target) => ({ target, id: resolveLibraryLink(entry, fromFile, target, { entries, packageRoot: root }) }));
+}
+function linksSection(links) {
+    const lines = ["--- linked files (load each with summer_read_library and the id after the arrow) ---"];
+    for (const link of links)
+        lines.push(`${link.target} -> ${link.id ?? "(not shipped with this package)"}`);
+    return lines.join("\n");
+}
 function toolBody(entry, slug) {
     const lines = [];
     const mcpName = entry.mcp_tool_name ?? `summer_${slug.replace(/-/g, "_")}`;
@@ -179,36 +346,112 @@ function header(entry, slug, related) {
 }
 // ── Entry point ────────────────────────────────────────────────────────────
 /**
- * Read one entry. `deps.entries`/`deps.packageRoot`/`deps.templates` let
- * tests point at a fixture; production reads the installed package.
+ * Read one entry, or a file an entry links. `deps.entries`/`deps.packageRoot`/
+ * `deps.templates` let tests point at a fixture; production reads the
+ * installed package.
  */
 export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
     const entries = deps.entries ?? loadLibraryIndex();
     const root = deps.packageRoot ?? PACKAGE_ROOT;
-    const entry = resolveEntry(requestedId, entries);
+    let entry = resolveEntry(requestedId, entries);
+    let linkedFile;
     if (!entry) {
-        const query = requestedId.replace(/[/@_-]+/g, " ").replace(/[a-f0-9]{8,}/gi, " ").trim() || requestedId;
+        const target = resolveLinkedFile(requestedId, entries, root);
+        if (target) {
+            entry = target.entry;
+            const canonical = canonicalId(target, root);
+            // The entry's own body file and resource.yaml render as the entry.
+            if (target.file === "resource.yaml")
+                part = "resource";
+            else if (canonical !== entry.id)
+                linkedFile = target.file;
+        }
+    }
+    if (!entry) {
+        const query = requestedId.replace(/[/@_.-]+/g, " ").replace(/[a-f0-9]{8,}/gi, " ").replace(/\bmd\b/g, " ").trim() || requestedId;
         const nearest = (await searchLibrary(query, { limit: 3 }, deps)).map((hit) => hit.id);
         return {
             ok: false,
             error: "not_found",
             id: requestedId,
             nearest,
-            hint: nearest.length > 0
+            hint: (nearest.length > 0
                 ? `No library entry has id "${requestedId}". Nearest by search: ${nearest.join(", ")}. Ids are <kind>/<slug>; use summer_search_library to find the right one.`
-                : `No library entry has id "${requestedId}" and nothing similar was found. Ids are <kind>/<slug>; use summer_search_library.`,
+                : `No library entry has id "${requestedId}" and nothing similar was found. Ids are <kind>/<slug>; use summer_search_library.`) +
+                " A file an entry links loads by <entry id>/<link as written> (inside library/ only).",
         };
     }
     const kind = entry.kind;
     const slug = entry.id.split("/").pop();
-    const kindDir = LIBRARY_KIND_DIRS[kind] ?? `${kind}s`;
-    const relPath = `library/${kindDir}/${slug}`;
-    const dir = join(root, "library", kindDir, slug);
+    const relPath = entryDirOf(entry);
+    const dir = join(root, ...relPath.split("/"));
     const files = listFiles(dir);
     const related = relatedMap(entry);
+    const footer = feedbackFooter(entry.id, entry.content_hash);
+    const resourceYaml = readText(join(dir, "resource.yaml"))?.replace(/\s+$/, "") ?? "(resource.yaml not found in this install)";
+    const base = {
+        ok: true,
+        id: entry.id,
+        kind: entry.kind,
+        slug,
+        version: entry.version ?? "",
+        status: entry.status ?? "stable",
+        content_hash: entry.content_hash ?? "",
+        summary: entry.summary ?? "",
+        use_when: Array.isArray(entry.use_when) ? entry.use_when : [],
+        related,
+        part,
+        path: relPath,
+        files,
+        entry_id: entryIdWithHash(entry.id, entry.content_hash),
+        footer,
+    };
+    if (linkedFile !== undefined) {
+        const libPath = `${relPath}/${linkedFile}`;
+        const extension = posix.extname(linkedFile).toLowerCase();
+        const size = (() => {
+            try {
+                return statSync(join(root, ...libPath.split("/"))).size;
+            }
+            catch {
+                return Number.POSITIVE_INFINITY;
+            }
+        })();
+        const sections = [
+            `${entry.id}/${linkedFile} — a file shipped with ${entry.id} (${entry.kind} v${entry.version ?? "?"}, ${entry.status ?? "stable"}). The entry itself: summer_read_library id "${entry.id}".`,
+        ];
+        let links = [];
+        if (part === "resource") {
+            sections.push(`--- ${relPath}/resource.yaml ---\n${resourceYaml}`);
+        }
+        else if (!LINKED_FILE_EXTENSIONS.has(extension)) {
+            sections.push(`--- ${libPath} ---\n(not a text file read_library loads: ${extension || "no extension"}; it ships at ${libPath} in the package)`);
+        }
+        else if (size > LINKED_FILE_MAX_BYTES) {
+            sections.push(`--- ${libPath} ---\n(${size} bytes, over the ${LINKED_FILE_MAX_BYTES}-byte limit for a linked file; it ships at ${libPath} in the package)`);
+        }
+        else {
+            const text = readText(join(root, ...libPath.split("/")))?.replace(/\s+$/, "") ?? "(file could not be read)";
+            sections.push(`--- ${libPath} ---\n${text}`);
+            if (extension === ".md" || extension === ".markdown") {
+                links = linksOf(text, entry, linkedFile, entries, root);
+                if (links.length > 0)
+                    sections.push(linksSection(links));
+            }
+        }
+        sections.push(footer);
+        return {
+            ...base,
+            body_file: linkedFile,
+            linked_file: linkedFile,
+            ...(links.length > 0 ? { links } : {}),
+            text: sections.join("\n\n"),
+        };
+    }
     let bodyFile;
     let bodyTitle;
     let body;
+    let links = [];
     if (kind === "tool") {
         bodyTitle = "how to call";
         body = toolBody(entry, slug);
@@ -224,40 +467,28 @@ export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
             bodyFile = picked;
             bodyTitle = `${relPath}/${picked}`;
             body = text.replace(/\s+$/, "");
+            if (picked.toLowerCase().endsWith(".md"))
+                links = linksOf(body, entry, picked, entries, root);
         }
         else {
             bodyTitle = "body";
             body = `(no body file shipped for this ${kind}; the descriptor below is all there is)`;
         }
     }
-    const resourceYaml = readText(join(dir, "resource.yaml"))?.replace(/\s+$/, "") ?? "(resource.yaml not found in this install)";
-    const footer = feedbackFooter(entry.id, entry.content_hash);
     const sections = [header(entry, slug, related)];
-    if (part === "skill" || part === "all")
+    if (part === "skill" || part === "all") {
         sections.push(`--- ${bodyTitle} ---\n${body}`);
+        if (links.length > 0)
+            sections.push(linksSection(links));
+    }
     if (part === "resource" || part === "all")
         sections.push(`--- ${relPath}/resource.yaml ---\n${resourceYaml}`);
     sections.push(footer);
-    const result = {
-        ok: true,
-        id: entry.id,
-        kind: entry.kind,
-        slug,
-        version: entry.version ?? "",
-        status: entry.status ?? "stable",
-        content_hash: entry.content_hash ?? "",
-        summary: entry.summary ?? "",
-        use_when: Array.isArray(entry.use_when) ? entry.use_when : [],
-        related,
-        part,
-        path: relPath,
-        files,
-        entry_id: entryIdWithHash(entry.id, entry.content_hash),
-        footer,
-        text: sections.join("\n\n"),
-    };
+    const result = { ...base, text: sections.join("\n\n") };
     if (bodyFile)
         result.body_file = bodyFile;
+    if (links.length > 0 && part !== "resource")
+        result.links = links;
     if (kind === "tool") {
         if (entry.mcp_tool_name)
             result.mcp_tool_name = entry.mcp_tool_name;

package/dist/core/library-search.d.ts

@@ -96,12 +96,12 @@ export declare const searchLibraryInputSchema: z.ZodObject<{
     include_preview: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     query: string;
-    kinds?: ("template" | "tool" | "skill" | "reference" | "example" | "collection")[] | undefined;
+    kinds?: ("template" | "tool" | "reference" | "skill" | "example" | "collection")[] | undefined;
     limit?: number | undefined;
     include_preview?: boolean | undefined;
 }, {
     query: string;
-    kinds?: ("template" | "tool" | "skill" | "reference" | "example" | "collection")[] | undefined;
+    kinds?: ("template" | "tool" | "reference" | "skill" | "example" | "collection")[] | undefined;
     limit?: number | undefined;
     include_preview?: boolean | undefined;
 }>;

package/dist/installer/agent-config.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "fs";
 import { copyFile, mkdir, readFile, writeFile } from "fs/promises";
 import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
-import { isMap, parseDocument } from "yaml";
+import { Document, isMap, parseDocument } from "yaml";
 import { PACKAGE_ROOT } from "../core/package-root.js";
 import { agentAliasMap, agentSpec, defaultPathContext, resolveMcpPath, supportedAgents, } from "./agent-table.js";
 export { supportedAgents } from "./agent-table.js";
@@ -135,7 +135,7 @@ export function renderConfigSnippet(agent, server) {
         return renderJsonFile(geminiExtensionManifest(server, readBundledGeminiManifestSync()));
     }
     if (format === "yaml-goose" || format === "yaml-hermes") {
-        const doc = parseDocument("{}");
+        const doc = new Document({});
         doc.setIn([topLevelKey(format), SUMMER_MCP_SERVER_NAME], doc.createNode(mcpEntry(format, server)));
         return doc.toString();
     }
@@ -250,7 +250,9 @@ async function upsertJsonEntry(path, format, server, write) {
  */
 async function upsertYamlConfig(path, keyPath, entry, write) {
     const current = await readTextFileIfExists(path);
-    const doc = parseDocument(current.trim() === "" ? "{}" : current);
+    // An empty file starts from a fresh block-style document; parseDocument("{}")
+    // would make the root a flow mapping and the whole file would render as {}.
+    const doc = current.trim() === "" ? new Document({}) : parseDocument(current);
     if (doc.errors.length > 0) {
         throw new Error(`Could not parse YAML in ${path}: ${doc.errors[0].message}`);
     }

package/dist/installer/agent-table.d.ts

@@ -48,6 +48,16 @@ export interface SkillHome {
         project: ((ctx: PathContext) => string) | null;
         suffix: string;
     };
+    /**
+     * Skill folders Summer 3.1.0 wrote for this agent before it moved to the
+     * shared agentskills.io folder (~/.agents/skills). `skills install --force`
+     * removes Summer's own skill dirs there so the agent does not load the same
+     * skill twice.
+     */
+    legacyDirs?: {
+        user: (ctx: PathContext) => string;
+        project: ((ctx: PathContext) => string) | null;
+    };
 }
 export interface AgentSpec {
     id: SupportedAgent;
@@ -74,6 +84,10 @@ export interface AgentSpec {
     skills: SkillHome | null;
     noSkillsNote?: string;
 }
+/** True when this location is the shared agentskills.io folder. */
+export declare function isSharedSkillsPath(path: string): boolean;
+/** Agents that read the shared folder at the given scope (for the install summary). */
+export declare function agentsSharingSkills(scope: ConfigScope, ctx: PathContext): AgentSpec[];
 export declare function agentSpec(id: SupportedAgent): AgentSpec;
 export declare function allAgentSpecs(): readonly AgentSpec[];
 /** Ids shown in help and error messages (legacy ids still parse). */
@@ -94,6 +108,8 @@ export interface ResolvedMcpPath {
 export declare function resolveMcpPath(spec: AgentSpec, scope: ConfigScope, ctx: PathContext): ResolvedMcpPath;
 /** Rule files a pre-3.1 Summer wrote for this agent at this scope; `null` when the agent never had any. */
 export declare function legacyRuleFiles(spec: AgentSpec, scope: ConfigScope, ctx: PathContext, skillNames: Iterable<string>): string[] | null;
+/** Skill dirs a Summer 3.1.0 install may have written at this agent's old native location; `null` when it never moved. */
+export declare function legacySkillDirs(spec: AgentSpec, scope: ConfigScope, ctx: PathContext, skillNames: Iterable<string>): string[] | null;
 export interface ResolvedSkillPath {
     kind: SkillLocationKind;
     path: string;