@khorsheed/dsh-capability-catalog 0.1.98 → 0.1.99

package/lib/index.js

@@ -1,11 +1,12 @@
 import { homedir, tmpdir } from "node:os";
-import { basename, dirname, join, relative } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { cp, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { cp, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import yaml from "js-yaml";
 import { inflateRawSync } from "node:zlib";
 import { existsSync, watch } from "node:fs";
 import { createScope } from "@deepseek-ai/dsh-scope";
@@ -248,6 +249,10 @@ async function skillBodySha(registry, name, options) {
 *
 * `bodySha` costs one registry load per skill, so it is opt-in: the browser
 * card wants a listing, and the capability fingerprint wants the bodies.
+*
+* `report`, when given, is filled with the collection's health (see
+* {@link SkillsCollectionReport}); the Remote verbs never pass one, so their
+* rows — and their digests — are exactly what they were.
 */
 async function collectSkills$1(registry, workdir, scopes = [void 0], collectOptions = {}) {
 	const byName = /* @__PURE__ */ new Map();
@@ -257,15 +262,19 @@ async function collectSkills$1(registry, workdir, scopes = [void 0], collectOpti
 			...base,
 			scope
 		};
+		if (collectOptions.report !== void 0) collectOptions.report.attemptedScopes += 1;
 		let snapshot;
 		try {
 			snapshot = await registry.snapshot(options);
 		} catch {
+			if (collectOptions.report !== void 0) collectOptions.report.failedScopes += 1;
 			continue;
 		}
+		if (snapshot.complete === false && collectOptions.report !== void 0) collectOptions.report.incompleteReads += 1;
 		for (const summary of snapshot.skills) {
 			if (byName.has(summary.name)) continue;
 			const bodySha = collectOptions.bodySha === true ? await skillBodySha(registry, summary.name, options) : void 0;
+			if (collectOptions.bodySha === true && bodySha === void 0 && collectOptions.report !== void 0) collectOptions.report.unreadableBodies += 1;
 			const row = skillRowFrom(summary, await skillUpdatedAt(summary), bodySha);
 			byName.set(row.name, row);
 		}
@@ -311,6 +320,28 @@ function sanitizeBundlePath(path) {
 	}
 	return safe.length === 0 ? void 0 : safe.join("/");
 }
+/**
+* Resolve an already-sanitized bundle-relative path to its real on-disk
+* target, refusing anything that escapes the bundle. {@link sanitizeBundlePath}
+* has already removed the lexical escapes (absolute forms, drive letters,
+* `..`); this closes what a lexical check cannot:
+*
+* - a symlink INSIDE the bundle whose target lives outside it (the bundle
+*   directory is user content), and
+* - a prefix collision — containment is a separator-terminated comparison on
+*   realpaths, so `/root/foobar` never contain-matches `/root/foo`.
+*
+* @param bundleDir - the skill's bundle directory (its resource base).
+* @param safe - a path that already passed {@link sanitizeBundlePath}.
+* @returns the resolved absolute target, or undefined when the file is absent
+*   or would escape the bundle.
+*/
+async function resolveBundleTarget(bundleDir, safe) {
+	const base = await realpath(bundleDir).catch(() => bundleDir);
+	const target = await realpath(join(bundleDir, safe)).catch(() => void 0);
+	if (target === void 0 || target !== base && !target.startsWith(base + sep)) return void 0;
+	return target;
+}
 /** Read one skill-bundle file's text content, on demand. */
 async function readSkillFileContent(registry, name, filePath, workdir, scope = void 0, fallback) {
 	const base = workdir === void 0 ? {} : { cwd: workdir };
@@ -325,10 +356,10 @@ async function readSkillFileContent(registry, name, filePath, workdir, scope = v
 	if (bundleDir === void 0) return void 0;
 	const safe = sanitizeBundlePath(filePath);
 	if (safe === void 0) return void 0;
-	const full = join(bundleDir, safe);
-	if (!full.startsWith(bundleDir)) return void 0;
+	const target = await resolveBundleTarget(bundleDir, safe);
+	if (target === void 0) return void 0;
 	try {
-		return { content: (await readFile(full)).toString("utf8") };
+		return { content: (await readFile(target)).toString("utf8") };
 	} catch {
 		return;
 	}
@@ -370,7 +401,8 @@ async function loadSkillDetail(ctx, registry, name, workdir, scope = void 0, fal
 	const def = await registry.get(name, lookup) ?? fallback;
 	if (def === void 0) return void 0;
 	const metadataDecls = decodeCredentialDecls(def.metadata);
-	const environmentRefs = decodeEnvDecls(def.content).map((decl) => decl.key);
+	const declaredKeys = new Set(metadataDecls.map((decl) => decl.key));
+	const environmentRefs = decodeEnvDecls(def.content).map((decl) => decl.key).filter((key) => !declaredKeys.has(key));
 	const { credentials } = resolveServices(ctx);
 	let credentialStates = [];
 	if (metadataDecls.length > 0 && credentials !== void 0) credentialStates = await Promise.all(metadataDecls.map(async (decl) => {
@@ -478,6 +510,175 @@ function resolveMcpServerName(name, serverNames) {
 	if (separator > 0) return rest.slice(0, separator);
 }
 //#endregion
+//#region lib/types/frontmatter.js
+/**
+* SKILL.md frontmatter: ONE real-YAML parse shared by every catalog reader.
+*
+* Before this module, each reader carried its own line-based scan: a regex
+* split plus per-key patterns that matched at any indentation, so a nested
+* same-named key could shadow a top-level one and a `presetScope` under an
+* unrelated key still counted. Everything here is derived from a single
+* js-yaml parse of the block (js-yaml is the repo's YAML convention and a
+* shipped runtime dependency), with the scalar semantics mirrored from the
+* host's skill loader (`skill-filesystem`): booleans accept true/false, 1/0,
+* yes/no, on/off.
+*
+* Two deliberate degradations, both pinned by specs:
+*
+* - A malformed `metadata:` block must not take the skill down. A bad metadata
+*   value usually poisons the whole YAML parse, so on a parse failure the
+*   block is retried once with the top-level `metadata:` section stripped:
+*   the skill delivers minus metadata rather than being rejected.
+* - A flag value outside the accepted variants reads as ABSENT (the caller's
+*   default applies) instead of rejecting the skill the way the host loader
+*   does — the catalog is a management/delivery surface, not the loader of
+*   record.
+* @module @khorsheed/dsh-capability-catalog/frontmatter
+*/
+/** Kebab-case skill / preset id grammar (the registry's own). */
+const KEBAB_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Whether a string is a usable skill / preset id. */
+function isKebabId(value) {
+	return KEBAB_ID.test(value);
+}
+/** Frontmatter block, then the body it precedes (CRLF-tolerant). */
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/** Split a SKILL.md into its frontmatter block and body. */
+function splitFrontmatter(content) {
+	const match = FRONTMATTER.exec(content);
+	if (match === null) return void 0;
+	return {
+		front: match[1] ?? "",
+		body: match[2] ?? ""
+	};
+}
+/**
+* Parse a SKILL.md's frontmatter block once, with js-yaml.
+* @param content - the whole file text.
+* @returns the parsed fields plus the body, or undefined when there is no
+*   frontmatter block or the block is not usable YAML even without its
+*   `metadata:` section.
+*/
+function parseSkillFrontmatter(content) {
+	const split = splitFrontmatter(content);
+	if (split === void 0) return void 0;
+	const parsed = parseFrontmatterData(split.front);
+	if (parsed === void 0) return void 0;
+	const { data, metadataDropped } = parsed;
+	const rawMetadata = data["metadata"];
+	const metadata = !metadataDropped && typeof rawMetadata === "object" && rawMetadata !== null && !Array.isArray(rawMetadata) ? rawMetadata : void 0;
+	const name = stringField(data, "name");
+	const description = stringField(data, "description");
+	const whenToUse = whenToUseOf(data);
+	const presetScope = presetScopeOf(data, metadata);
+	return {
+		...name === void 0 ? {} : { name },
+		...description === void 0 ? {} : { description },
+		...whenToUse === void 0 ? {} : { whenToUse },
+		modelInvocable: frontmatterBoolean(data, "disable-model-invocation") !== true,
+		userInvocable: frontmatterBoolean(data, "user-invocable") !== false,
+		...presetScope === void 0 ? {} : { presetScope },
+		...metadata === void 0 ? {} : { metadata },
+		body: split.body
+	};
+}
+/**
+* A frontmatter boolean with the host skill loader's accepted variants:
+* booleans, 1/0 (number or string), and yes/no/on/off (case-insensitive —
+* js-yaml 4 leaves those as strings, so the string branch carries them).
+* Absent or anything else reads as undefined: the catalog degrades to the
+* caller's default instead of rejecting the skill the way the host loader
+* does (`frontmatter field "<key>" must be a boolean` → file ignored).
+*/
+function frontmatterBoolean(data, key) {
+	if (!Object.hasOwn(data, key)) return void 0;
+	const value = data[key];
+	if (typeof value === "boolean") return value;
+	if (value === 1 || value === "1") return true;
+	if (value === 0 || value === "0") return false;
+	if (typeof value === "string") switch (value.toLowerCase()) {
+		case "true":
+		case "yes":
+		case "on": return true;
+		case "false":
+		case "no":
+		case "off": return false;
+	}
+}
+/** A frontmatter string field: non-empty strings only (the host's stringField). */
+function stringField(data, key) {
+	const value = data[key];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+/** The routing guidance, kebab spelling first (the catalog has always accepted both). */
+function whenToUseOf(data) {
+	return stringField(data, "when-to-use") ?? stringField(data, "whenToUse");
+}
+/** The declared preset scope; the canonical metadata-nested key wins over the legacy top-level one. */
+function presetScopeOf(data, metadata) {
+	const nested = metadata === void 0 ? void 0 : normalizePresetScope(metadata["presetScope"]);
+	if (nested !== void 0) return nested;
+	return normalizePresetScope(data["presetScope"]);
+}
+/** Normalize a raw presetScope value: arrays filter to kebab ids, a scalar is a one-item list. */
+function normalizePresetScope(value) {
+	if (Array.isArray(value)) return presetIdsOf(value.map(String));
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return presetIdsOf([String(value)]);
+}
+/** Normalize YAML scalars onto the preset-id grammar (deduped, order preserved). */
+function presetIdsOf(values) {
+	const ids = [];
+	for (const value of values) {
+		const id = value.trim().replace(/^['"]|['"]$/g, "");
+		if (id === "" || !KEBAB_ID.test(id)) continue;
+		if (!ids.includes(id)) ids.push(id);
+	}
+	return ids;
+}
+/** Parse the block as a YAML mapping; on a YAML failure retry once without the
+* top-level `metadata:` section (a malformed metadata value degrades to
+* no-metadata instead of rejecting the file). */
+function parseFrontmatterData(front) {
+	try {
+		const data = loadYamlMapping(front);
+		return data === void 0 ? void 0 : {
+			data,
+			metadataDropped: false
+		};
+	} catch {
+		const stripped = stripTopLevelBlock(front, "metadata");
+		if (stripped === void 0) return void 0;
+		try {
+			const data = loadYamlMapping(stripped);
+			return data === void 0 ? void 0 : {
+				data,
+				metadataDropped: true
+			};
+		} catch {
+			return;
+		}
+	}
+}
+/** js-yaml parse of the block; only a plain object is a usable frontmatter map. */
+function loadYamlMapping(front) {
+	const parsed = yaml.load(front);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+	return parsed;
+}
+/** Remove a top-level `key:` line and its indented block; undefined when the key is absent. */
+function stripTopLevelBlock(front, key) {
+	const lines = front.split("\n");
+	const start = lines.findIndex((line) => new RegExp(`^${key}\\s*:`).test(line));
+	if (start < 0) return void 0;
+	let end = start + 1;
+	while (end < lines.length) {
+		const line = lines[end] ?? "";
+		if (line.trim() !== "" && !/^\s/.test(line)) break;
+		end += 1;
+	}
+	return [...lines.slice(0, start), ...lines.slice(end)].join("\n");
+}
+//#endregion
 //#region lib/types/zip.js
 /**
 * Minimal, dependency-free ZIP reader: enough to unpack a skill archive
@@ -569,7 +770,6 @@ function findEocd(buf) {
 * @module @khorsheed/dsh-capability-catalog/import
 */
 const execFileAsync = promisify(execFile);
-const FRONTMATTER$1 = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
 /** First bytes of a ZIP archive (local file header / empty / spanned). */
 const ZIP_MAGIC_PK = 80;
 const ZIP_MAGIC_K = 75;
@@ -579,12 +779,10 @@ function managedRoot(root, dshHome) {
 }
 /** Extract the kebab-case `name` and `description` from a SKILL.md body. */
 function resolveSkillNameFromContent(content) {
-	const m = FRONTMATTER$1.exec(content);
-	if (m === null) return void 0;
-	const front = m[1] ?? "";
-	const name = /^name:\s*(.+)$/m.exec(front)?.[1]?.trim();
-	const description = /^description:\s*(.+)$/m.exec(front)?.[1]?.trim();
-	if (name === void 0 || description === void 0 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) return void 0;
+	const parsed = parseSkillFrontmatter(content);
+	if (parsed === void 0) return void 0;
+	const { name, description } = parsed;
+	if (name === void 0 || description === void 0 || !isKebabId(name)) return void 0;
 	return {
 		name,
 		description
@@ -596,10 +794,7 @@ function decodeBase64(payload) {
 }
 /** Read the frontmatter `disable-model-invocation` flag (default model-invocable true). */
 function inferModelInvocable(content) {
-	const m = FRONTMATTER$1.exec(content);
-	if (m === null) return true;
-	const front = m[1] ?? "";
-	return /^disable-model-invocation:\s*(true|false)$/m.exec(front)?.[1] !== "true";
+	return parseSkillFrontmatter(content)?.modelInvocable ?? true;
 }
 /** Whether a filesystem path exists (dir or file). */
 async function pathExists(p) {
@@ -633,13 +828,11 @@ function sanitizeRelPath(p) {
 }
 /** Apply the frontmatter `disable-model-invocation` line to match the request. */
 function finalizeSkillText(content, modelInvocable) {
-	const m = FRONTMATTER$1.exec(content);
-	if (m === null) return content;
-	const front = String(m[1] ?? "");
-	const body = String(m[2] ?? "");
+	const split = splitFrontmatter(content);
+	if (split === void 0) return content;
 	if (inferModelInvocable(content) === modelInvocable) return content;
-	const without = front.split("\n").filter((line) => !line.trim().startsWith("disable-model-invocation:")).join("\n");
-	return `---\n${modelInvocable ? without : `${without}${without.endsWith("\n") ? "" : "\n"}disable-model-invocation: true`}\n---\n${body}`;
+	const without = split.front.split("\n").filter((line) => !line.trim().startsWith("disable-model-invocation:")).join("\n");
+	return `---\n${modelInvocable ? without : `${without}${without.endsWith("\n") ? "" : "\n"}disable-model-invocation: true`}\n---\n${split.body}`;
 }
 /**
 * Add a skill from a base64 SKILL.md text payload into the managed root.
@@ -1302,7 +1495,17 @@ function projectTools(schemas, mcpServers, appearedAfterApply, toolOrigins = /*
 */
 async function catalogSnapshot(workdir, registry, toolsSchemas, mcpServers, appearedAfterApply, scopes = [void 0], toolOrigins = /* @__PURE__ */ new Map(), options = {}) {
 	const fingerprint = options.fingerprint === true;
-	const base = await collectSkills$1(registry, workdir, scopes, { bodySha: fingerprint });
+	const skillsReport = {
+		attemptedScopes: 0,
+		failedScopes: 0,
+		incompleteReads: 0,
+		unreadableBodies: 0
+	};
+	const base = await collectSkills$1(registry, workdir, scopes, {
+		bodySha: fingerprint,
+		report: skillsReport
+	});
+	if (options.report !== void 0) options.report.skills = skillsReport;
 	const tools = projectTools(toolsSchemas, mcpServers, appearedAfterApply, toolOrigins);
 	const snapshot = {
 		skills: base.skills,
@@ -1388,6 +1591,124 @@ async function catalogListDirSkills(dirPath) {
 	return listDirSkills(dirPath);
 }
 //#endregion
+//#region lib/types/tool-origin.js
+/**
+* Community tool-origin convention: a host-side tag a plugin attaches to a tool
+* definition BEFORE `ctx.tools.register`, so the catalog can attribute the tool
+* to `plugin` (and any channel) instead of relying on heuristics.
+*
+* The harness `ToolSchema` carries no source/owner field and the system-prompt
+* assembly projects tools to `{ name, description, parameters }`, so the tag must
+* live on the retained `ToolDefinition` and be read via `ctx.tools.get(name)`
+* (the registry keeps the definition by reference, so the symbol survives).
+* The key is `Symbol.for('dsh.tool.origin')` (global symbol registry) — a plugin
+* may tag without importing anything, using `def[Symbol.for('dsh.tool.origin')]`.
+* `setToolOrigin` is the convenience form exported for the catalog's own plugins.
+* @module @khorsheed/dsh-capability-catalog/tool-origin
+*/
+/** The global origin-tag key. `Symbol.for` returns the same symbol everywhere. */
+const TOOL_ORIGIN = Symbol.for("dsh.tool.origin");
+/** Convenience: attach an origin tag to a tool definition (before `register`). */
+function setToolOrigin(definition, origin) {
+	definition[TOOL_ORIGIN] = origin;
+	return definition;
+}
+/** Read the origin tag off a tool definition (host-side; never on the model wire). */
+function toolOrigin(definition) {
+	return definition[TOOL_ORIGIN];
+}
+/** Whether an origin's `channel` is one the catalog can honor (plugin/builtin/mcp). */
+function isValidOrigin(origin) {
+	return origin?.channel === "plugin" || origin?.channel === "builtin" || origin?.channel === "mcp";
+}
+//#endregion
+//#region lib/types/tool-face.js
+/**
+* Reading the tools side of the capability face: the visible schemas in a
+* scope, the author-declared origin tags behind them, and the MCP server
+* names the `mcp__` prefixes imply.
+*
+* Extracted from the service so the Remote verbs and the pure-data evidence
+* producer (`evidence.ts`) read the tools registry through ONE
+* implementation — the digest parity between them is by construction, not by
+* two copies agreeing today. Nothing here catches a `schemas()` failure:
+* whether a failed read rejects the call (the Remote verbs' choice) or is
+* recorded as an unavailable section (the evidence producer's choice) is the
+* caller's policy.
+* @module @khorsheed/dsh-capability-catalog/tool-face
+*/
+/**
+* The visible tool schemas in a scope, or the global layer when no scope is
+* given; an empty list when the registry is absent.
+*/
+function toolSchemasFacing(tools, scope) {
+	if (tools?.schemas === void 0) return [];
+	return scope === void 0 ? tools.schemas() : tools.schemas(scope);
+}
+/**
+* The origin tags behind the given schemas, read via `tools.get(name)` so the
+* `Symbol.for('dsh.tool.origin')` tag on the retained definition survives
+* (the system-prompt assembly strips it, but `get()` returns the full
+* definition). A schema the registry cannot hand back contributes no tag —
+* the tool falls back to heuristics and is named in `untaggedOrigins`.
+*/
+function toolOriginsFacing(tools, schemas, scope, warn) {
+	const out = /* @__PURE__ */ new Map();
+	const untagged = [];
+	if (tools?.get === void 0) return {
+		origins: out,
+		untaggedOrigins: untagged
+	};
+	for (const schema of schemas) {
+		const def = scope === void 0 ? tools.get(schema.name) : tools.get(schema.name, scope);
+		if (def === void 0) {
+			warn(`capability-catalog: tool "${schema.name}" is visible but ctx.tools.get() is undefined in this scope — its origin tag cannot be read; it will be classified by heuristics`);
+			untagged.push(schema.name);
+			continue;
+		}
+		const origin = toolOrigin(def);
+		if (origin !== void 0) {
+			if (!isValidOrigin(origin)) {
+				warn(`capability-catalog: tool "${schema.name}" origin channel "${String(origin.channel)}" is not a known channel (plugin/builtin/mcp) — ignoring the tag, falling back to heuristics`);
+				untagged.push(schema.name);
+				continue;
+			}
+			out.set(schema.name, origin);
+		}
+	}
+	return {
+		origins: out,
+		untaggedOrigins: untagged
+	};
+}
+/** MCP server names from live `mcp__`-prefixed tools (prefix-derived baseline). */
+function mcpServerNamesFacing(schemas) {
+	const names = [];
+	for (const schema of schemas) {
+		if (!schema.name.startsWith("mcp__")) continue;
+		const rest = schema.name.slice(5);
+		const sep = rest.indexOf("__");
+		const server = sep > 0 ? rest.slice(0, sep) : rest;
+		if (server.length > 0 && !names.includes(server)) names.push(server);
+	}
+	return names;
+}
+/**
+* Collect the whole tools side of one reading position with ONE `schemas()`
+* call, so the rows, the origin tags and the MCP names cannot disagree about
+* which registry state they read.
+*/
+function collectToolFace(tools, scope, warn) {
+	const schemas = toolSchemasFacing(tools, scope);
+	const { origins, untaggedOrigins } = toolOriginsFacing(tools, schemas, scope, warn);
+	return {
+		schemas,
+		origins,
+		mcpServerNames: mcpServerNamesFacing(schemas),
+		untaggedOrigins
+	};
+}
+//#endregion
 //#region lib/types/preset-scope.js
 /**
 * Resolving WHICH scope the catalog reads — and the one place where a listing
@@ -1558,106 +1879,37 @@ const MANAGED_SKILL_RANK = 300;
 const SCOPED_SKILLS_DIR = join("capability-catalog", "skills");
 /** Debounce for filesystem-triggered rescans. */
 const RESCAN_DEBOUNCE_MS = 150;
-/** Frontmatter block, then the body it precedes. */
-const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
-/** Kebab-case skill / preset id grammar (the registry's own). */
-const KEBAB_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** The managed root for one harness home. */
 function scopedSkillsRoot(dshHome) {
 	return join(dshHome, SCOPED_SKILLS_DIR);
 }
 /**
-* Read the `presetScope` list out of a frontmatter block.
-*
-* Accepted forms, at any indentation (the canonical one is
-* `metadata.presetScope`):
-*
-* ```yaml
-* metadata:
-*   presetScope: [dsh-writing, dev]
-*   presetScope:
-*     - dsh-writing
-* ```
-* @param front - the frontmatter text without its `---` fences.
-* @returns the declared ids, or undefined when the key is absent.
-*/
-function parsePresetScopeFrontmatter(front) {
-	const lines = front.split("\n");
-	for (let index = 0; index < lines.length; index += 1) {
-		const match = /^(\s*)presetScope\s*:\s*(.*)$/.exec(lines[index] ?? "");
-		if (match === null) continue;
-		const indent = (match[1] ?? "").length;
-		const rest = (match[2] ?? "").trim();
-		if (rest.startsWith("[")) return presetIdsOf(rest.slice(1, rest.lastIndexOf("]") === -1 ? void 0 : rest.lastIndexOf("]")).split(","));
-		if (rest !== "") return presetIdsOf([rest]);
-		const block = [];
-		for (let item = index + 1; item < lines.length; item += 1) {
-			const entry = /^(\s*)-\s*(.*?)\s*$/.exec(lines[item] ?? "");
-			if (entry === null) break;
-			if ((entry[1] ?? "").length <= indent) break;
-			block.push(entry[2] ?? "");
-		}
-		return presetIdsOf(block);
-	}
-}
-/** Normalize YAML scalars onto the preset-id grammar. */
-function presetIdsOf(values) {
-	const ids = [];
-	for (const value of values) {
-		const id = value.trim().replace(/^['"]|['"]$/g, "");
-		if (id === "" || !KEBAB_ID.test(id)) continue;
-		if (!ids.includes(id)) ids.push(id);
-	}
-	return ids;
-}
-/** Whether a string is a usable skill / preset id. */
-function isKebabId(value) {
-	return KEBAB_ID.test(value);
-}
-/** Split a SKILL.md into its frontmatter block and body. */
-function splitFrontmatter(content) {
-	const match = FRONTMATTER.exec(content);
-	if (match === null) return void 0;
-	return {
-		front: match[1] ?? "",
-		body: match[2] ?? ""
-	};
-}
-/** Read a boolean frontmatter flag (`key: true|false`). */
-function frontmatterFlag(front, key) {
-	const match = new RegExp(`^\\s*${key}\\s*:\\s*(true|false)\\s*$`, "m").exec(front);
-	if (match === null) return void 0;
-	return match[1] === "true";
-}
-/** Read a scalar frontmatter value, unquoting a simple quoted or plain form. */
-function frontmatterScalar(front, key) {
-	const match = new RegExp(`^\\s*${key}\\s*:\\s*(.+)$`, "m").exec(front);
-	if (match === null) return void 0;
-	const value = (match[1] ?? "").trim().replace(/^['"]|['"]$/g, "");
-	return value === "" ? void 0 : value;
-}
-/**
 * Parse one managed `SKILL.md` into its delivery record.
+*
+* The frontmatter is ONE real-YAML parse (see `./frontmatter.ts`): name and
+* description read top-level only, the invocation flags accept the host
+* loader's boolean variants, and the scope list comes from the canonical
+* `metadata.presetScope` (falling back to a legacy top-level key). A malformed
+* `metadata:` block degrades to no-metadata — the skill still delivers —
+* rather than rejecting a file the rest of the block could still serve.
 * @param content - the file text.
 * @param dir - the skill's directory (its resource base).
 * @param path - the absolute `SKILL.md` path.
 * @returns the record, or undefined when the frontmatter is unusable.
 */
 function managedSkillFrom(content, dir, path) {
-	const split = splitFrontmatter(content);
-	if (split === void 0) return void 0;
-	const name = frontmatterScalar(split.front, "name");
-	const description = frontmatterScalar(split.front, "description");
-	if (name === void 0 || description === void 0 || !KEBAB_ID.test(name)) return void 0;
-	const whenToUse = frontmatterScalar(split.front, "when-to-use") ?? frontmatterScalar(split.front, "whenToUse");
-	const presetScope = parsePresetScopeFrontmatter(split.front);
+	const parsed = parseSkillFrontmatter(content);
+	if (parsed === void 0) return void 0;
+	const { name, description } = parsed;
+	if (name === void 0 || description === void 0 || !isKebabId(name)) return void 0;
 	return {
 		name,
 		description,
-		...whenToUse === void 0 ? {} : { whenToUse },
-		modelInvocable: frontmatterFlag(split.front, "disable-model-invocation") !== true,
-		userInvocable: frontmatterFlag(split.front, "user-invocable") !== false,
-		presetScope,
+		...parsed.whenToUse === void 0 ? {} : { whenToUse: parsed.whenToUse },
+		modelInvocable: parsed.modelInvocable,
+		userInvocable: parsed.userInvocable,
+		presetScope: parsed.presetScope,
+		...parsed.metadata === void 0 ? {} : { metadata: parsed.metadata },
 		dir,
 		path,
 		content
@@ -1682,7 +1934,10 @@ function candidateFor(skill) {
 		rank: 300,
 		locator: skill.path,
 		path: skill.path,
-		metadata: { presetScope: [...skill.presetScope ?? []] },
+		metadata: {
+			...skill.metadata,
+			presetScope: [...skill.presetScope ?? []]
+		},
 		resourceBase: {
 			kind: "directory",
 			path: skill.dir
@@ -1738,7 +1993,7 @@ async function scanManagedSkills(root) {
 	}
 	const found = [];
 	for (const child of children) {
-		if (!child.isDirectory() || !KEBAB_ID.test(child.name)) continue;
+		if (!child.isDirectory() || !isKebabId(child.name)) continue;
 		const dir = join(root, child.name);
 		const path = join(dir, "SKILL.md");
 		try {
@@ -1775,6 +2030,9 @@ var ScopedSkillDelivery = class {
 	failure;
 	started = false;
 	disposed = false;
+	/** Reconcile gate: one pass in flight, one queued rerun (see reconcile). */
+	reconcileInFlight;
+	reconcileQueued = false;
 	/** The probed registry's mount list (undefined until start()'s probe resolves). */
 	presetMounts;
 	/**
@@ -1797,8 +2055,46 @@ var ScopedSkillDelivery = class {
 		});
 		await this.reconcile();
 	}
-	/** Re-read policy and files, then converge the delivery registrations. */
+	/**
+	* Re-read policy and files, then converge the delivery registrations.
+	*
+	* Triggers arrive concurrently — the filesystem watcher, the
+	* `agent-preset/selected` event, and the management Remotes — and two
+	* overlapping passes can both decide a preset has no registration and each
+	* register one, leaving two same-named providers serving one preset. The
+	* gate allows ONE pass in flight and coalesces every trigger that arrives
+	* during it into ONE queued rerun (the pass re-reads policy and files from
+	* scratch, so a rerun loses no update). A caller that finds a pass in
+	* flight waits for the chain its flag provoked, so an awaited reconcile
+	* still reflects the write that triggered it.
+	*/
 	async reconcile() {
+		if (this.disposed) return;
+		if (this.reconcileInFlight !== void 0) {
+			this.reconcileQueued = true;
+			let run = this.reconcileInFlight;
+			while (run !== void 0) {
+				await run;
+				if (this.disposed) return;
+				run = this.reconcileInFlight;
+			}
+			return;
+		}
+		const run = (async () => {
+			try {
+				do {
+					this.reconcileQueued = false;
+					await this.reconcileNow();
+				} while (this.reconcileQueued && !this.disposed);
+			} finally {
+				this.reconcileInFlight = void 0;
+			}
+		})();
+		this.reconcileInFlight = run;
+		return run;
+	}
+	/** One reconcile pass (call only through {@link reconcile}'s gate). */
+	async reconcileNow() {
 		if (this.disposed) return;
 		const registry = this.deps.registry();
 		const roster = this.deps.roster();
@@ -1985,6 +2281,7 @@ var ScopedSkillDelivery = class {
 				invalidate = control.invalidate;
 				return this.providerFor(presetId, control);
 			});
+			((await injectableScope(injected, TOOLS_SERVICE))?.get(TOOLS_SERVICE))?.register?.(this.bundleFileTool(presetId));
 			this.entries.push({
 				presetId,
 				key,
@@ -2039,6 +2336,62 @@ var ScopedSkillDelivery = class {
 	skillsFor(presetId) {
 		return this.managed.filter((skill) => !this.conflicts.has(skill.name) && (presetId === GLOBAL_PRESET ? !isScoped(skill) : (skill.presetScope ?? []).includes(presetId)));
 	}
+	/** The managed skills readable through one preset's reader: its own scoped
+	* delivery plus the unscoped ones every preset sees through the global layer. */
+	readableFor(presetId) {
+		return [...this.skillsFor(presetId), ...this.skillsFor(GLOBAL_PRESET)];
+	}
+	/** The read-only bundle-file reader served with one preset's delivery. */
+	bundleFileTool(presetId) {
+		return setToolOrigin(defineTool({
+			name: READ_SKILL_FILE_TOOL,
+			description: "Read a file from the bundle of a skill delivered to this mode — the reference documents and scripts beside its SKILL.md (a SKILL.md may point at them, e.g. \"see search.md\"). Omit path to list the bundle files.",
+			parameters: {
+				name: {
+					type: "string",
+					required: true,
+					description: "The exact skill name from the available skills list."
+				},
+				path: {
+					type: "string",
+					description: "The bundle-relative file path (e.g. search.md). Omit it to list the bundle files."
+				}
+			},
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: String(value)
+				}]
+			},
+			execute: async (args) => this.readBundleFile(presetId, args.name, args.path)
+		}), {
+			channel: "plugin",
+			owner: "@khorsheed/dsh-capability-catalog"
+		});
+	}
+	/** Serve one bundle file (or the bundle's file list) to a delivered skill's caller. */
+	async readBundleFile(presetId, name, filePath) {
+		const skill = this.readableFor(presetId).find((entry) => entry.name === name);
+		if (skill === void 0) return `skill "${name}" is not delivered to this mode by the capability catalog`;
+		if (filePath === void 0 || filePath.trim() === "") {
+			const files = [];
+			await collectSkillFiles(skill.dir, skill.dir, files, 0);
+			return files.length === 0 ? `skill "${name}" has no bundle files` : files.sort().join("\n");
+		}
+		const safe = sanitizeBundlePath(filePath);
+		if (safe === void 0) return `refused: "${filePath}" is not a bundle-relative path`;
+		const target = await resolveBundleTarget(skill.dir, safe);
+		if (target === void 0) return `no such bundle file: ${safe}`;
+		let content;
+		try {
+			content = await readFile(target, "utf8");
+		} catch {
+			return `no such bundle file: ${safe}`;
+		}
+		if (content.length > MAX_BUNDLE_FILE_CHARS) return `${content.slice(0, MAX_BUNDLE_FILE_CHARS)}\n…(truncated at ${MAX_BUNDLE_FILE_CHARS} characters)`;
+		return content;
+	}
 	/** Invalidate every registration's completed catalogs. */
 	invalidateAll() {
 		for (const entry of this.entries) entry.invalidate();
@@ -2069,6 +2422,12 @@ function describeError(error) {
 }
 /** The registry every delivery registration is made through. */
 const SKILLS_SERVICE = "skills";
+/** The tools registry the bundle-file reader registers through (optional). */
+const TOOLS_SERVICE = "tools";
+/** The scoped bundle-file reader's tool name. */
+const READ_SKILL_FILE_TOOL = "read_skill_file";
+/** A bundle file's served text is capped so a giant asset cannot flood a turn. */
+const MAX_BUNDLE_FILE_CHARS = 1e5;
 /** How long an injection may take before the registration is abandoned. */
 const INJECT_TIMEOUT_MS = 500;
 /**
@@ -2079,9 +2438,10 @@ const INJECT_TIMEOUT_MS = 500;
 * await, which gives `reconcile()` a settled answer instead of a registration
 * that appears at some later tick.
 * @param scopeCtx - the context minted for one preset's standing key.
+* @param service - the service the injected context must reach.
 * @returns the injected context, or undefined when it never became available.
 */
-function injectableScope(scopeCtx) {
+function injectableScope(scopeCtx, service = SKILLS_SERVICE) {
 	return new Promise((resolve) => {
 		let settled = false;
 		const finish = (value) => {
@@ -2091,7 +2451,7 @@ function injectableScope(scopeCtx) {
 			resolve(value);
 		};
 		const timer = setTimeout(() => finish(void 0), INJECT_TIMEOUT_MS);
-		scopeCtx.inject([SKILLS_SERVICE], (injected) => finish(injected));
+		scopeCtx.inject([service], (injected) => finish(injected));
 	});
 }
 //#endregion
@@ -2352,6 +2712,13 @@ function messageOf(error) {
 * model's context; it only becomes visible if the model (or a command) actively
 * prints it — a default-hide, not a hard secret boundary.
 *
+* Coverage: the registry snapshot is read at the catalog's preset scope, which
+* a preset-scoped managed skill never appears in — so the managed root is ALSO
+* scanned directly (its skills' declared keys join the same set). The injected
+* variables are instance-wide per execution: preset scope is a delivery policy,
+* not a secret boundary, and a value leaves the shell env only if a command
+* prints it.
+*
 * Constraint handling (shell-env/src/index.ts):
 * - keys must start `DSH_` and match `/^[A-Z][A-Z0-9_]*$/`; one owner per key;
 *   reserved built-ins (`DSH_HOME`/`DSH_SHELL`/`DSH_SESSION_ID`) are not ownable.
@@ -2402,7 +2769,7 @@ const RESERVED_ENV_KEYS = /* @__PURE__ */ new Set([
 * the impl only while its fiber is active) immediately before calling `register`,
 * and self-retries on `INACTIVE_EFFECT` so it self-heals once boot stabilizes.
 */
-function installSkillEnvInjection(ctx, getScope) {
+function installSkillEnvInjection(ctx, getScope, getDshHome) {
 	let disposed = false;
 	let envCache = /* @__PURE__ */ new Map();
 	let disposeEnv;
@@ -2458,15 +2825,8 @@ function installSkillEnvInjection(ctx, getScope) {
 				const occupied = new Set((shellEnv.list?.() ?? []).filter((e) => e.contributor !== "capability-catalog").map((e) => e.key));
 				const keys = /* @__PURE__ */ new Set();
 				const values = /* @__PURE__ */ new Map();
-				for (const row of snapshot.skills) {
-					if (row.invocation?.modelInvocable === false) continue;
-					let def;
-					try {
-						def = await skills.get(row.name, snapshotOptions);
-					} catch {
-						continue;
-					}
-					if (def === void 0) continue;
+				/** Fold one definition's declared env keys into the contributor's set. */
+				const collectDecls = async (def) => {
 					const decls = mergeCredentialDecls(decodeCredentialDecls(def.metadata), decodeEnvDecls(def.content ?? ""));
 					for (const decl of decls) {
 						if (!ENV_KEY_SUFFIX.test(decl.key)) continue;
@@ -2476,6 +2836,21 @@ function installSkillEnvInjection(ctx, getScope) {
 						const resolved = await credentials.resolve(decl.key).catch(() => void 0);
 						if (resolved !== void 0 && resolved.value.length > 0) values.set(dshKey, resolved.value);
 					}
+				};
+				for (const row of snapshot.skills) {
+					if (row.invocation?.modelInvocable === false) continue;
+					let def;
+					try {
+						def = await skills.get(row.name, snapshotOptions);
+					} catch {
+						continue;
+					}
+					if (def === void 0) continue;
+					await collectDecls(def);
+				}
+				for (const skill of await scanManagedSkills(scopedSkillsRoot(getDshHome())).catch(() => [])) {
+					if (!skill.modelInvocable) continue;
+					await collectDecls(definitionFor(skill));
 				}
 				if (disposed || gen !== refreshGen) return;
 				envCache = values;
@@ -2618,8 +2993,7 @@ var McpStore = class {
 			this.servers.set(server.config.serverName, {
 				config: server.config,
 				credentials: existing?.credentials ?? /* @__PURE__ */ new Map(),
-				tools,
-				error: void 0
+				tools
 			});
 		}
 		for (const [ref, value] of Object.entries(state.credentials ?? {})) {
@@ -2674,8 +3048,7 @@ var McpStore = class {
 		this.servers.set(config.serverName, {
 			config,
 			credentials: existing?.credentials ?? /* @__PURE__ */ new Map(),
-			tools: existing?.tools ?? [],
-			error: existing?.error
+			tools: existing?.tools ?? []
 		});
 		this.persist();
 	}
@@ -2717,51 +3090,38 @@ var McpStore = class {
 		if (s === void 0) return [];
 		try {
 			const { connectMcpServer } = await import("./mcpConnector-C2TbkPBY.js");
-			const connection = await connectMcpServer(await resolveConfigSecrets(s.config, async (ref) => {
-				const candidates = [
-					`mcp.${serverName}.env.${ref}`,
-					`mcp.${serverName}.header.${ref}`,
-					`mcp.${serverName}.query.${ref}`
-				];
-				for (const candidate of candidates) {
-					const value = s.credentials.get(candidate);
-					if (value !== void 0) return value;
-				}
-			}));
+			const connection = await connectMcpServer(await resolveConfigSecrets(s.config, this.secretResolver(serverName, s)));
 			const prevEnabled = new Map(s.tools.map((t) => [t.name, t.enabled]));
 			s.tools = connection.tools.map((t) => ({
 				...t,
 				enabled: prevEnabled.get(t.name) ?? true
 			}));
-			s.error = void 0;
 			await connection.close();
 			this.persist();
 			return s.tools;
-		} catch (error) {
-			s.error = String(error);
+		} catch {
 			this.persist();
 			return s.tools;
 		}
 	}
-	/** Re-connect + re-discover every enabled server — boot-time refill of the
-	* discovered descriptions/parameters (the persisted block stores only
-	* name+enabled). Preserves per-tool enable flags; per-server errors are
-	* recorded and do not stop the others. */
-	async reconnectAll() {
-		for (const server of this.list()) {
-			if (!server.enabled) continue;
-			await this.discover(server.serverName);
-		}
-	}
-	/** A server's most recent connection/dev error. */
-	errorOf(serverName) {
-		return this.servers.get(serverName)?.error;
-	}
 	/** Forward one tool call to a server (connect → call → close). Resolves secrets. */
 	async callTool(serverName, rawName, args) {
 		const s = this.servers.get(serverName);
 		if (s === void 0) throw new Error(`unknown MCP server: ${serverName}`);
-		const resolved = await resolveConfigSecrets(s.config, async (ref) => {
+		const resolved = await resolveConfigSecrets(s.config, this.secretResolver(serverName, s));
+		const { connectMcpServer } = await import("./mcpConnector-C2TbkPBY.js");
+		const connection = await connectMcpServer(resolved);
+		try {
+			return await connection.call(rawName, args);
+		} finally {
+			await connection.close();
+		}
+	}
+	/** The `resolveConfigSecrets` callback for one server: a bare secret ref
+	* resolves to the stored credential under the server's env/header/query
+	* namespace (the same namespaces {@link credentialRefsOf} writes). */
+	secretResolver(serverName, s) {
+		return async (ref) => {
 			const candidates = [
 				`mcp.${serverName}.env.${ref}`,
 				`mcp.${serverName}.header.${ref}`,
@@ -2771,14 +3131,7 @@ var McpStore = class {
 				const value = s.credentials.get(candidate);
 				if (value !== void 0) return value;
 			}
-		});
-		const { connectMcpServer } = await import("./mcpConnector-C2TbkPBY.js");
-		const connection = await connectMcpServer(resolved);
-		try {
-			return await connection.call(rawName, args);
-		} finally {
-			await connection.close();
-		}
+		};
 	}
 	/** Extract credential reference paths from a config (env/header/url-query).
 	* Namespaced `mcp.<serverName>.env.<KEY>` so multiple servers don't collide. */
@@ -2928,7 +3281,8 @@ function desiredMcpTools(servers, toolsByServer) {
 //#region lib/types/envHint.js
 /**
 * Skill env hint via `tools/post-execute` — a runtime companion context that
-* tells the model about any skill's configured credential env mappings.
+* tells the model about any skill's configured credential env mappings, and a
+* scoped-delivered skill's bundle files.
 *
 * The catalog injects credentials as trusted per-execution `DSH_<KEY>` env
 * vars (see shellEnv.ts), but a skill's own text references the original
@@ -2937,6 +3291,11 @@ function desiredMcpTools(servers, toolsByServer) {
 * a generic, per-skill note listing each configured mapping, so the model can
 * use the value without us modifying the user's SKILL.md.
 *
+* A second block covers scoped-delivered skills (provider `capability-catalog`):
+* their SKILL.md may reference bundle files (search.md etc.) in a mode that
+* mounts no fs tools, so the note lists those files and names the scoped
+* `read_skill_file` reader — only when the caller's own scope carries it.
+*
 * Generic: it derives the mappings from the loaded skill's own env-decl keys
 * (decodeEnvDecls) + the credential store, so any future key / skill is
 * covered. It never touches the skill file or the provider's returned content.
@@ -2952,9 +3311,9 @@ function installSkillEnvHint(ctx, getScope) {
 			if (exec?.name !== "skill") return next();
 			const skillName = exec.arguments?.name;
 			if (typeof skillName !== "string" || skillName.length === 0) return next();
-			const scope = await getScope().catch(() => void 0);
+			const scope = exec.agent ?? await getScope().catch(() => void 0);
 			const { registry, credentials } = resolveServices(ctx);
-			if (registry === void 0 || credentials === void 0) return next();
+			if (registry === void 0) return next();
 			const lookup = scope === void 0 ? {} : { scope };
 			let def;
 			try {
@@ -2963,15 +3322,27 @@ function installSkillEnvHint(ctx, getScope) {
 				return next();
 			}
 			if (def === void 0) return next();
-			const decls = mergeCredentialDecls(decodeCredentialDecls(def.metadata), decodeEnvDecls(def.content ?? ""));
-			const configured = [];
-			for (const decl of decls) if ((await credentials.describe(decl.key).catch(() => void 0))?.configured === true) configured.push(decl.key);
-			if (configured.length === 0) return next();
-			const hint = [
-				`Runtime credential mapping for ${skillName}:`,
-				...configured.map((k) => `- ${k} is configured; in the model shell it is available as ${DSH_PREFIX}${k}. Use it as ${k}="${DSH_PREFIX}${k}" <command>.`),
-				`Do not search dotenv files or ask the user for this credential, and do not print either variable.`
-			].join("\n");
+			const blocks = [];
+			if (credentials !== void 0) {
+				const decls = mergeCredentialDecls(decodeCredentialDecls(def.metadata), decodeEnvDecls(def.content ?? ""));
+				const configured = [];
+				for (const decl of decls) if ((await credentials.describe(decl.key).catch(() => void 0))?.configured === true) configured.push(decl.key);
+				if (configured.length > 0) blocks.push([
+					`Runtime credential mapping for ${skillName}:`,
+					...configured.map((k) => `- ${k} is configured; in the model shell it is available as ${DSH_PREFIX}${k}. Use it as ${k}="${DSH_PREFIX}${k}" <command>.`),
+					`Do not search dotenv files or ask the user for this credential, and do not print either variable.`
+				].join("\n"));
+			}
+			const bundleDir = def.resourceBase?.kind === "directory" ? def.resourceBase.path : void 0;
+			if (def.provider === "capability-catalog" && bundleDir !== void 0 && exec.agent !== void 0) {
+				if ((ctx.get?.("tools"))?.schemas?.(exec.agent)?.some((schema) => schema.name === "read_skill_file") === true) {
+					const files = [];
+					await collectSkillFiles(bundleDir, bundleDir, files, 0);
+					const rest = files.filter((file) => file !== "SKILL.md").sort();
+					if (rest.length > 0) blocks.push([`Bundle files for ${skillName}: ${rest.join(", ")}`, `Read them with ${READ_SKILL_FILE_TOOL} (name: "${skillName}", path: "<file>") — this mode may have no fs tools.`].join("\n"));
+				}
+			}
+			if (blocks.length === 0) return next();
 			return {
 				kind: "accept",
 				additionalContexts: [{
@@ -2979,7 +3350,7 @@ function installSkillEnvHint(ctx, getScope) {
 					role: "user",
 					content: [{
 						type: "text",
-						text: hint
+						text: blocks.join("\n\n")
 					}],
 					source: {
 						kind: "capability-catalog",
@@ -2992,43 +3363,11 @@ function installSkillEnvHint(ctx, getScope) {
 	});
 }
 //#endregion
-//#region lib/types/tool-origin.js
-/**
-* Community tool-origin convention: a host-side tag a plugin attaches to a tool
-* definition BEFORE `ctx.tools.register`, so the catalog can attribute the tool
-* to `plugin` (and any channel) instead of relying on heuristics.
-*
-* The harness `ToolSchema` carries no source/owner field and the system-prompt
-* assembly projects tools to `{ name, description, parameters }`, so the tag must
-* live on the retained `ToolDefinition` and be read via `ctx.tools.get(name)`
-* (the registry keeps the definition by reference, so the symbol survives).
-* The key is `Symbol.for('dsh.tool.origin')` (global symbol registry) — a plugin
-* may tag without importing anything, using `def[Symbol.for('dsh.tool.origin')]`.
-* `setToolOrigin` is the convenience form exported for the catalog's own plugins.
-* @module @khorsheed/dsh-capability-catalog/tool-origin
-*/
-/** The global origin-tag key. `Symbol.for` returns the same symbol everywhere. */
-const TOOL_ORIGIN = Symbol.for("dsh.tool.origin");
-/** Convenience: attach an origin tag to a tool definition (before `register`). */
-function setToolOrigin(definition, origin) {
-	definition[TOOL_ORIGIN] = origin;
-	return definition;
-}
-/** Read the origin tag off a tool definition (host-side; never on the model wire). */
-function toolOrigin(definition) {
-	return definition[TOOL_ORIGIN];
-}
-/** Whether an origin's `channel` is one the catalog can honor (plugin/builtin/mcp). */
-function isValidOrigin(origin) {
-	return origin?.channel === "plugin" || origin?.channel === "builtin" || origin?.channel === "mcp";
-}
-//#endregion
 //#region lib/types/namespace.js
 /**
 * The settings namespace owned by the capability-catalog plugin. Plain string
-* so both the host half (settings registration) and the browser half (the
-* settings.plugin.item card key) import it without dragging host-only
-* dependencies into the client bundle.
+* so both the host half (settings registration) and the browser half import
+* it without dragging host-only dependencies into the client bundle.
 */
 /** Settings namespace owned by the capability-catalog plugin. */
 const CAPABILITY_CATALOG_NS = "capability-catalog";
@@ -3144,6 +3483,191 @@ async function readModeFaces(options, readFace) {
 	return faces;
 }
 //#endregion
+//#region lib/types/evidence.js
+/**
+* The PRODUCER side of capability-composition evidence: pure data, computed
+* where the composition runs, for a consumer in another process to verify.
+*
+* {@link produceCapabilityEvidence} answers "what is the capability face of
+* THIS composition, and how completely was it measured?" — the composition
+* digest plus a per-section completeness descriptor, the measurement object
+* (what claims to have been measured), and the caller's coverage declaration
+* (what directories/services were read). It reuses this package's own
+* snapshot and digest algorithms (`catalogSnapshot`, `hashOf` — via
+* `remote.ts` and `capabilities.ts`), so the digest it reports is the digest
+* `snapshotFor` would stamp over the same registries: parity is by
+* construction, and a test pins it.
+*
+* Two deliberate absences, both by design:
+*
+* - **No standing-scope mount.** The function takes no roster and no cordis
+*   Context, so it CANNOT resolve a preset's standing scope — resolving one
+*   mounts the preset (see `preset-scope.ts`), and a target-side producer
+*   must not pay that side effect to measure. The normal target-side
+*   topology needs no scope at all: the producer's own registries already
+*   ARE the composition's face. A caller holding an already-resolved scope
+*   may pass it as `scope`; resolution and release stay the caller's
+*   business.
+* - **No service registration.** Nothing is mounted, provided or injected as
+*   a side effect; the function reads the slices it is handed and returns
+*   plain JSON-safe data. It runs in a bare process (node builtins and this
+*   package's existing dependencies only).
+*
+* The digest algorithm is owned by THIS package. A consumer MUST NOT
+* recompute it from the rows, and MUST treat a `partial` or `unavailable`
+* section as "not verified" — never as complete, and never as "the section
+* is empty". An empty-but-complete section (scanned, zero found) and an
+* unmeasured section produce distinguishable descriptors, which is the
+* point: an empty digest is not a complete one unless every section says so.
+* @module @khorsheed/dsh-capability-catalog/evidence
+*/
+/** The registry that measures as "no skills", for a composition without a skills service. */
+const EMPTY_REGISTRY = {
+	snapshot: async () => ({
+		skills: [],
+		complete: true
+	}),
+	get: async () => void 0
+};
+/**
+* Wrap the caller's tools slice so a `get()` that throws degrades to an
+* unreadable origin tag (a partial section) instead of failing the whole
+* measurement. Member-call semantics are preserved — the slice may be a
+* traceable proxy whose methods need their receiver.
+*/
+function guardToolReads(tools) {
+	if (tools.get === void 0) return tools;
+	const get = tools.get;
+	return {
+		schemas: (scope) => tools.schemas(scope),
+		get: (name, scope) => {
+			try {
+				return get.call(tools, name, scope);
+			} catch {
+				return;
+			}
+		}
+	};
+}
+/** The skills section's descriptor, from the collection's own report. */
+function skillsCompleteness(skills, report) {
+	if (skills === void 0) return {
+		state: "unavailable",
+		reason: "the skills service is not installed"
+	};
+	if (report === void 0 || report.attemptedScopes === 0) return {
+		state: "unavailable",
+		reason: "no skill scope was read"
+	};
+	if (report.failedScopes === report.attemptedScopes) return {
+		state: "unavailable",
+		reason: `the skill registry read failed for every scope (${report.attemptedScopes} attempted)`
+	};
+	const problems = [];
+	if (report.failedScopes > 0) problems.push(`the skill registry read failed for ${report.failedScopes} of ${report.attemptedScopes} scopes`);
+	if (report.incompleteReads > 0) problems.push("the registry reported incomplete skill discovery");
+	if (report.unreadableBodies > 0) problems.push(`${report.unreadableBodies} skill bodies could not be read`);
+	return problems.length === 0 ? { state: "complete" } : {
+		state: "partial",
+		reason: problems.join("; ")
+	};
+}
+/** The tools section's descriptor, from how the tools-side read went. */
+function toolsCompleteness(tools, readFailed, face) {
+	if (tools === void 0) return {
+		state: "unavailable",
+		reason: "the tools service is not installed"
+	};
+	if (readFailed || face === void 0) return {
+		state: "unavailable",
+		reason: "the tool registry read failed"
+	};
+	if (face.untaggedOrigins.length > 0) return {
+		state: "partial",
+		reason: `origin tags unreadable for ${face.untaggedOrigins.length} visible tools — channel attribution fell back to heuristics`
+	};
+	return { state: "complete" };
+}
+/** The MCP section is derived from the tools section, so it inherits its failures. */
+function mcpCompleteness(tools) {
+	if (tools.state === "unavailable") return {
+		state: "unavailable",
+		reason: "MCP servers are derived from the tools section, which is unavailable"
+	};
+	if (tools.state === "partial") return {
+		state: "partial",
+		reason: "derived from a partially measured tools section"
+	};
+	return { state: "complete" };
+}
+/** The channel summary is derived from the skills and tools rows, so it is only as strong as they are. */
+function channelsCompleteness(skills, tools) {
+	if (skills.state === "unavailable" && tools.state === "unavailable") return {
+		state: "unavailable",
+		reason: "neither the skills nor the tools section could be measured"
+	};
+	if (skills.state !== "complete" || tools.state !== "complete") return {
+		state: "partial",
+		reason: `summarizes sections that are not fully measured (skills: ${skills.state}, tools: ${tools.state})`
+	};
+	return { state: "complete" };
+}
+/**
+* Produce the capability-composition evidence of the composition THIS
+* process runs, as plain data another process can verify.
+*
+* The measurement reuses the package's own algorithms end to end: the tools
+* side is read by `tool-face.ts` (the same reads the Remote verbs make), the
+* snapshot is `catalogSnapshot` in fingerprint mode, and the digest is its
+* stamped `sha` — nothing is re-implemented, so the answer is comparable
+* with a `snapshotFor` digest taken over the same registries.
+* @param options - every input, explicit; see {@link ProduceCapabilityEvidenceOptions}.
+* @returns the evidence bundle — digest, completeness, measurement, coverage.
+* @throws when `workdir` is given but not absolute, when `presetId` is given
+*   but blank, or when the coverage declaration is missing — the caller
+*   verifies identity and coverage; this function only measures.
+*/
+async function produceCapabilityEvidence(options) {
+	if (options.workdir !== void 0 && !isAbsolute(options.workdir)) throw new Error(`produceCapabilityEvidence needs an absolute workdir (caller-verified); got ${JSON.stringify(options.workdir)}`);
+	if (options.presetId !== void 0 && options.presetId.trim() === "") throw new Error(`produceCapabilityEvidence needs a non-empty presetId when one is given; got ${JSON.stringify(options.presetId)}`);
+	if (options.coverage === void 0 || options.coverage === null) throw new Error("produceCapabilityEvidence needs the caller's coverage declaration (what directories/services were measured)");
+	const warn = options.warn ?? (() => {});
+	let toolFace;
+	let toolsReadFailed = false;
+	if (options.tools !== void 0) try {
+		toolFace = collectToolFace(guardToolReads(options.tools), options.scope, warn);
+	} catch {
+		toolsReadFailed = true;
+	}
+	const report = {};
+	const snapshot = await catalogSnapshot(options.workdir, options.skills ?? EMPTY_REGISTRY, toolFace?.schemas ?? [], toolFace?.mcpServerNames ?? [], options.appearedAfterApply ?? /* @__PURE__ */ new Set(), [options.scope], toolFace?.origins ?? /* @__PURE__ */ new Map(), {
+		fingerprint: true,
+		report,
+		...options.presetId !== void 0 ? { preset: options.presetId } : {}
+	});
+	const skills = skillsCompleteness(options.skills, report.skills);
+	const tools = toolsCompleteness(options.tools, toolsReadFailed, toolFace);
+	return {
+		measurement: {
+			kind: "preset-composition",
+			...options.presetId !== void 0 ? { presetId: options.presetId } : {},
+			...options.workdir !== void 0 ? { workdir: options.workdir } : {},
+			...options.revision !== void 0 ? { revision: options.revision } : {}
+		},
+		sha: snapshot.sha,
+		completeness: {
+			skills,
+			tools,
+			mcpServers: mcpCompleteness(tools),
+			channels: channelsCompleteness(skills, tools)
+		},
+		coverage: {
+			...options.coverage.directories !== void 0 ? { directories: [...options.coverage.directories] } : {},
+			...options.coverage.services !== void 0 ? { services: [...options.coverage.services] } : {}
+		}
+	};
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Capability catalog host service: a Typert Remote over the running skill and
@@ -3227,7 +3751,6 @@ let CapabilityCatalogService = (() => {
 	let _addSkill_decorators;
 	let _deleteSkill_decorators;
 	let _pickDirectory_decorators;
-	let _mcpList_decorators;
 	let _mcpAdd_decorators;
 	let _mcpRemove_decorators;
 	let _mcpSetEnabled_decorators;
@@ -3254,7 +3777,6 @@ let CapabilityCatalogService = (() => {
 			_addSkill_decorators = [Remote("addSkill")];
 			_deleteSkill_decorators = [Remote("deleteSkill")];
 			_pickDirectory_decorators = [Remote("pickDirectory")];
-			_mcpList_decorators = [Remote("mcpList")];
 			_mcpAdd_decorators = [Remote("mcpAdd")];
 			_mcpRemove_decorators = [Remote("mcpRemove")];
 			_mcpSetEnabled_decorators = [Remote("mcpSetEnabled")];
@@ -3438,17 +3960,6 @@ let CapabilityCatalogService = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
-			__esDecorate(this, null, _mcpList_decorators, {
-				kind: "method",
-				name: "mcpList",
-				static: false,
-				private: false,
-				access: {
-					has: (obj) => "mcpList" in obj,
-					get: (obj) => obj.mcpList
-				},
-				metadata: _metadata
-			}, null, _instanceExtraInitializers);
 			__esDecorate(this, null, _mcpAdd_decorators, {
 				kind: "method",
 				name: "mcpAdd",
@@ -3600,7 +4111,7 @@ let CapabilityCatalogService = (() => {
 				"credentials",
 				"skills"
 			], () => {
-				installSkillEnvInjection(ctx, () => this.catalogScope());
+				installSkillEnvInjection(ctx, () => this.catalogScope(), () => this.dshHome());
 			});
 			installSkillEnvHint(ctx, () => this.catalogScope());
 			ctx.inject(["skills"], (skillsCtx) => {
@@ -3711,7 +4222,7 @@ let CapabilityCatalogService = (() => {
 		/** Record tools that appeared after the apply-time baseline (reads the live
 		* registry each time, so a change event never sees a stale/undefined ref). */
 		markNewTools() {
-			const tools = this.ctx.get?.("tools");
+			const tools = this.toolsRegistry();
 			const current = new Set(tools?.schemas().map((t) => t.name) ?? []);
 			for (const name of current) if (!this.baseline.has(name)) this.appearedAfterApply.add(name);
 		}
@@ -3909,9 +4420,6 @@ let CapabilityCatalogService = (() => {
 		async pickDirectory() {
 			return catalogPickDirectory(this.ctx);
 		}
-		async mcpList() {
-			return this.mcp.list().map(maskConfig);
-		}
 		async mcpAdd(config) {
 			if (config.serverName.trim() === "") return false;
 			this.mcp.add(config);
@@ -3947,51 +4455,28 @@ let CapabilityCatalogService = (() => {
 				credentials: this.mcp.credentials()
 			};
 		}
+		/** The live tools registry, when the composition provides one. */
+		toolsRegistry() {
+			return this.ctx.get?.("tools");
+		}
 		/** The visible tool schemas in the standing scope (the set the model sees),
 		* or the global layer when no preset standing key resolves. Skills already
 		* enumerate through the same scope; tools must use it too so the
 		* settings reader sees the official/plugin/MCP tools the model actually has. */
 		toolSchemasIn(scope) {
-			const tools = this.ctx.get?.("tools");
-			if (tools?.schemas === void 0) return [];
-			return scope === void 0 ? tools.schemas() : tools.schemas(scope);
+			return toolSchemasFacing(this.toolsRegistry(), scope);
 		}
 		/** tool name → author-declared origin, read via `ctx.tools.get(name)` so the
 		* `Symbol.for('dsh.tool.origin')` tag on the retained definition survives (the
 		* system-prompt assembly strips it, but `get()` returns the full definition). */
 		toolOriginsMap(scope) {
-			const tools = this.ctx.get?.("tools");
-			if (tools?.get === void 0) return /* @__PURE__ */ new Map();
-			const schemas = scope === void 0 ? tools.schemas() : tools.schemas(scope);
-			const out = /* @__PURE__ */ new Map();
-			for (const schema of schemas) {
-				const def = scope === void 0 ? tools.get(schema.name) : tools.get(schema.name, scope);
-				if (def === void 0) {
-					this.ctx.logger.warn(`capability-catalog: tool "${schema.name}" is visible but ctx.tools.get() is undefined in this scope — its origin tag cannot be read; it will be classified by heuristics`);
-					continue;
-				}
-				const origin = toolOrigin(def);
-				if (origin !== void 0) {
-					if (!isValidOrigin(origin)) {
-						this.ctx.logger.warn(`capability-catalog: tool "${schema.name}" origin channel "${String(origin.channel)}" is not a known channel (plugin/builtin/mcp) — ignoring the tag, falling back to heuristics`);
-						continue;
-					}
-					out.set(schema.name, origin);
-				}
-			}
-			return out;
+			const tools = this.toolsRegistry();
+			const { origins } = toolOriginsFacing(tools, toolSchemasFacing(tools, scope), scope, (message) => this.ctx.logger.warn(message));
+			return origins;
 		}
 		/** MCP server names from live `mcp__`-prefixed tools (prefix-derived baseline). */
 		mcpServerNamesIn(scope) {
-			const names = [];
-			for (const schema of this.toolSchemasIn(scope)) {
-				if (!schema.name.startsWith("mcp__")) continue;
-				const rest = schema.name.slice(5);
-				const sep = rest.indexOf("__");
-				const server = sep > 0 ? rest.slice(0, sep) : rest;
-				if (server.length > 0 && !names.includes(server)) names.push(server);
-			}
-			return names;
+			return mcpServerNamesFacing(this.toolSchemasIn(scope));
 		}
 		/**
 		* Reconcile which discovered MCP tools are registered on `ctx.tools` so the
@@ -4029,4 +4514,4 @@ let CapabilityCatalogService = (() => {
 	};
 })();
 //#endregion
-export { CAPS_TAG_PREFIX, CapabilityCatalogService, CapabilityCatalogService as default, MANAGED_SKILL_RANK, REMOTE_NS, SCOPED_PROVIDER_NAME, ScopedSkillDelivery, TOOL_ORIGIN, adoptManagedSkill, canonicalCapabilities, canonicalJson, capsTag, defaultSkillRoots, detectConflicts, findSkillSource, hashOf, hashSkillBody, isDirectory, managedLocation, managedSkillFrom, modeOptions, parsePresetScopeFrontmatter, readModeFaces, releaseManagedSkill, resolvePresetScope, resolveSkillNameFromContent, scanManagedSkills, scopedSkillsRoot, setManagedPresetScope, setToolOrigin, toolOrigin, withPresetScope };
+export { CAPS_TAG_PREFIX, CapabilityCatalogService, CapabilityCatalogService as default, MANAGED_SKILL_RANK, REMOTE_NS, SCOPED_PROVIDER_NAME, ScopedSkillDelivery, TOOL_ORIGIN, adoptManagedSkill, canonicalCapabilities, canonicalJson, capsTag, defaultSkillRoots, detectConflicts, findSkillSource, hashOf, hashSkillBody, isDirectory, managedLocation, managedSkillFrom, modeOptions, produceCapabilityEvidence, readModeFaces, releaseManagedSkill, resolvePresetScope, resolveSkillNameFromContent, scanManagedSkills, scopedSkillsRoot, setManagedPresetScope, setToolOrigin, toolOrigin, withPresetScope };