@khorsheed/dsh-capability-catalog 0.1.98 → 0.1.99

package/lib/types/client/CapabilityCatalogCard.js

@@ -27,6 +27,9 @@ export function CapabilityCatalogCard({ useCatalog, detail, readSkillFile, listD
     const [kind, setKind] = useState('skills');
     const [selectedName, setSelectedName] = useState(null);
     const [claim, setClaim] = useState({ status: 'idle', data: undefined });
+    /** The mode the open detail was read at (see openDetail); the modal's bundle
+     * file reads must resolve at the same scope. */
+    const [detailMode, setDetailMode] = useState(undefined);
     const [showAdd, setShowAdd] = useState(false);
     const [showAddMcp, setShowAddMcp] = useState(false);
     const [deleteTarget, setDeleteTarget] = useState(null);
@@ -301,14 +304,20 @@ export function CapabilityCatalogCard({ useCatalog, detail, readSkillFile, listD
         });
     };
     const openDetail = async (name) => {
+        // The mode this detail is read at: the body AND any bundle file it points
+        // at resolve at the same scope, or a file that exists only in this mode
+        // reads as missing.
+        const readMode = readModeFor(name);
         setSelectedName(name);
+        setDetailMode(readMode);
         setClaim({ status: 'loading', data: undefined });
         void loadDetailModes(name);
-        const data = await detail(name, readModeFor(name));
+        const data = await detail(name, readMode);
         setClaim({ status: 'done', data });
     };
     const closeDetail = () => {
         setSelectedName(null);
+        setDetailMode(undefined);
         setClaim({ status: 'idle', data: undefined });
         setDetailModes(null);
     };
@@ -329,7 +338,7 @@ export function CapabilityCatalogCard({ useCatalog, detail, readSkillFile, listD
                             .replace('{skills}', String(skills.length))
                             .replace('{tools}', String(tools.length)), !modeBusy && comparison !== null && comparison.unavailable.length > 0 ? (_jsx("span", { className: css.modeWarn, title: comparison.unavailable.map(entry => `${entry.label}: ${entry.reason}`).join('\n'), children: t('modeUnavailableNote').replace('{n}', String(comparison.unavailable.length)) })) : null, !modeBusy ? _jsx("span", { className: css.modeHint, children: t('modeCompareCost') }) : null] })) : null, !comparing && modeBusy ? _jsx("div", { className: css.modeNote, children: t('modeBusy') }) : null, modeFellBack ? _jsx("div", { className: css.modeNote, children: t('modeFallback') }) : null, loading ? _jsx("div", { className: css.empty, children: t('loading') }) : null, !loading && kind === 'skills' && skills.length === 0 ? _jsx("div", { className: css.empty, children: t('empty') }) : null, !loading && kind === 'tools' && tools.length === 0 ? _jsx("div", { className: css.empty, children: t('toolNoMatch') }) : null, !loading && kind === 'skills' && skills.length > 0 ? (visibleSkills.length === 0
                 ? _jsx("div", { className: css.empty, children: t('noFilterMatch') })
-                : (_jsx("div", { className: css.grid, children: visibleSkills.map((skill) => (_jsx(SkillPreviewCard, { skill: skill, modes: cardModeChips(comparison?.skillModes.get(skill.name)), modeTotal: comparison?.modes ?? 0, onMode: handleModeChange, onOpen: () => void openDetail(skill.name), onDelete: () => setDeleteTarget(skill.name), t: t }, skill.name))) }))) : null, !loading && kind === 'skills' && orphans.length > 0 ? (_jsxs("details", { className: css.orphanGroup, children: [_jsx("summary", { className: css.orphanSummary, children: t('orphanManaged').replace('{n}', String(orphans.length)) }), _jsx("p", { className: css.confHint, children: t('orphanManagedHint') }), _jsx("div", { className: css.grid, children: orphans.map(orphan => (_jsx(SkillPreviewCard, { skill: orphanSkillRow(orphan), tag: scopeTagOf(orphan.name), onMode: handleModeChange, onOpen: () => void openDetail(orphan.name), onDelete: () => setDeleteTarget(orphan.name), t: t }, orphan.name))) })] })) : null, kind === 'tools' ? (_jsx(ToolCards, { loading: loading, visibleTools: visibleTools, mcpGroups: mcpGroups, segment: toolSegment, comparison: comparison, modeChipsFor: modeChipsFor, onMode: handleModeChange, onOpenTool: (tool) => setToolDetail(tool), onOpenServer: (name) => setMcpDetailName(name), onSetEnabled: setMcpEnabled, onRemove: removeMcp, t: t })) : null, mcpDetail !== null ? (_jsx(McpServerManageModal, { group: mcpDetail, discovering: discoveringMcp.has(mcpDetail.serverName), onClose: () => setMcpDetailName(null), onSetCredential: mcpSetCredential, onSetToolEnabled: setMcpToolEnabled, onDiscover: discoverMcp, onOpenTool: (tool) => setToolDetail(tool), t: t })) : null, toolDetail !== null ? (_jsx(ToolDetailModal, { tool: toolDetail, onClose: () => setToolDetail(null), t: t })) : null, selectedName !== null ? (_jsx(SkillDetailModal, { name: selectedName, claim: claim, onClose: closeDetail, setCredential: setCredential, readSkillFile: readSkillFile, t: t, scope: scopeEditorFor(selectedName, skills, scopeStatus, localizedOptions, {
+                : (_jsx("div", { className: css.grid, children: visibleSkills.map((skill) => (_jsx(SkillPreviewCard, { skill: skill, modes: cardModeChips(comparison?.skillModes.get(skill.name)), modeTotal: comparison?.modes ?? 0, onMode: handleModeChange, onOpen: () => void openDetail(skill.name), onDelete: () => setDeleteTarget(skill.name), t: t }, skill.name))) }))) : null, !loading && kind === 'skills' && orphans.length > 0 ? (_jsxs("details", { className: css.orphanGroup, children: [_jsx("summary", { className: css.orphanSummary, children: t('orphanManaged').replace('{n}', String(orphans.length)) }), _jsx("p", { className: css.confHint, children: t('orphanManagedHint') }), _jsx("div", { className: css.grid, children: orphans.map(orphan => (_jsx(SkillPreviewCard, { skill: orphanSkillRow(orphan), tag: scopeTagOf(orphan.name), onMode: handleModeChange, onOpen: () => void openDetail(orphan.name), onDelete: () => setDeleteTarget(orphan.name), t: t }, orphan.name))) })] })) : null, kind === 'tools' ? (_jsx(ToolCards, { loading: loading, visibleTools: visibleTools, mcpGroups: mcpGroups, segment: toolSegment, comparison: comparison, modeChipsFor: modeChipsFor, onMode: handleModeChange, onOpenTool: (tool) => setToolDetail(tool), onOpenServer: (name) => setMcpDetailName(name), onSetEnabled: setMcpEnabled, onRemove: removeMcp, t: t })) : null, mcpDetail !== null ? (_jsx(McpServerManageModal, { group: mcpDetail, discovering: discoveringMcp.has(mcpDetail.serverName), onClose: () => setMcpDetailName(null), onSetCredential: mcpSetCredential, onSetToolEnabled: setMcpToolEnabled, onDiscover: discoverMcp, onOpenTool: (tool) => setToolDetail(tool), t: t })) : null, toolDetail !== null ? (_jsx(ToolDetailModal, { tool: toolDetail, onClose: () => setToolDetail(null), t: t })) : null, selectedName !== null ? (_jsx(SkillDetailModal, { name: selectedName, claim: claim, onClose: closeDetail, setCredential: setCredential, readSkillFile: readSkillFile, presetId: detailMode, t: t, scope: scopeEditorFor(selectedName, skills, scopeStatus, localizedOptions, {
                     save: async (presets) => {
                         const result = await presetScopeSet(selectedName, presets);
                         await Promise.all([refreshScope(), reloadView()]);
@@ -472,8 +481,14 @@ export function scopeEditorFor(name, skills, status, options, actions) {
         declared: managedRow?.presets ?? [],
         ...managedRow?.conflict === undefined ? {} : { conflict: managedRow.conflict },
         options,
-        save: actions.save,
-        adopt: actions.adopt,
-        release: actions.release,
+        // One action for the modal, the managed-root mechanics hidden behind it:
+        // an emptied selection on a managed skill releases it back to the user
+        // root ("every preset" needs no managed delivery); an empty pick on an
+        // unmanaged skill is already the truth and needs no write at all.
+        apply: async (presets) => {
+            if (managedRow !== undefined)
+                return presets.length === 0 ? actions.release() : actions.save(presets);
+            return presets.length === 0 ? { ok: true } : actions.adopt(presets);
+        },
     };
 }

package/lib/types/client/SkillDetailModal.d.ts

@@ -25,17 +25,25 @@ export interface ScopeEditor {
     provider?: string;
     /** Every preset the roster supplies. */
     options: readonly CatalogPresetOption[];
-    save: (presets: readonly string[]) => Promise<CatalogPresetScopeEditResult>;
-    adopt: (presets: readonly string[]) => Promise<CatalogPresetScopeEditResult>;
-    release: () => Promise<CatalogPresetScopeEditResult>;
+    /**
+     * Apply the picked presets. The routing stays invisible to the user: adopt
+     * for a skill outside the managed root, re-scope for a managed one, and
+     * release back to the user skill root when a managed skill's selection is
+     * emptied — an empty selection means "every preset", which needs no managed
+     * delivery. An empty pick on an unmanaged skill is already the truth and
+     * reports success without a write.
+     */
+    apply: (presets: readonly string[]) => Promise<CatalogPresetScopeEditResult>;
 }
 /** Centered modal with a skill's full detail, source browser, metadata and credential config. */
-export declare function SkillDetailModal({ name, claim, onClose, setCredential, readSkillFile, t, scope, modeChips, modesLoading, onModeSelect }: {
+export declare function SkillDetailModal({ name, claim, onClose, setCredential, readSkillFile, presetId, t, scope, modeChips, modesLoading, onModeSelect }: {
     name: string;
     claim: DetailClaim;
     onClose: () => void;
     setCredential: (key: string, value: string) => Promise<boolean>;
-    readSkillFile: (name: string, path: string) => Promise<CatalogSkillFileRead | undefined>;
+    readSkillFile: (name: string, path: string, presetId?: string) => Promise<CatalogSkillFileRead | undefined>;
+    /** The mode this detail was read at; bundle files resolve at the same scope. */
+    presetId?: string | undefined;
     t: (key: CapabilityCatalogKey) => string;
     scope?: ScopeEditor | undefined;
     /** The modes that load this skill, when its scope section cannot say (a

package/lib/types/client/SkillDetailModal.js

@@ -13,7 +13,7 @@ function providedScopeNote(t, provider) {
         : t('scopeProvided').replace('{provider}', provider);
 }
 /** Centered modal with a skill's full detail, source browser, metadata and credential config. */
-export function SkillDetailModal({ name, claim, onClose, setCredential, readSkillFile, t, scope, modeChips, modesLoading, onModeSelect }) {
+export function SkillDetailModal({ name, claim, onClose, setCredential, readSkillFile, presetId, t, scope, modeChips, modesLoading, onModeSelect }) {
     const [credValues, setCredValues] = useState({});
     const [credState, setCredState] = useState({});
     const [copied, setCopied] = useState(false);
@@ -47,6 +47,10 @@ export function SkillDetailModal({ name, claim, onClose, setCredential, readSkil
         catch { /* clipboard may be blocked */ }
     };
     const pickedScope = scopePick ?? scope?.declared ?? [];
+    /** The pick matches the declared scope set-for-set (order-insensitive). */
+    const sameAsDeclared = scope !== undefined
+        && pickedScope.length === scope.declared.length
+        && pickedScope.every(id => scope.declared.includes(id));
     /** Run one scope mutation, then report its outcome in place. */
     const runScope = async (action) => {
         setScopeBusy(true);
@@ -75,7 +79,7 @@ export function SkillDetailModal({ name, claim, onClose, setCredential, readSkil
         }
         setSrcLoading(true);
         setSrcContent(undefined);
-        void readSkillFile(name, path).then(res => {
+        void readSkillFile(name, path, presetId).then(res => {
             setSrcContent(res?.content);
             setSrcLoading(false);
         });
@@ -85,7 +89,9 @@ export function SkillDetailModal({ name, claim, onClose, setCredential, readSkil
                             { label: t('provider'), value: data.provider },
                             { label: t('modelInvocable'), value: data.modelInvocable ? t('yes') : t('no') },
                             ...(data.whenToUse !== undefined ? [{ label: t('whenToUse'), value: data.whenToUse }] : []),
-                        ] }), _jsx("p", { className: css.detailDesc, children: data.description }), scope !== undefined ? (_jsxs("section", { className: css.scopeBox, children: [_jsxs("div", { className: css.scopeHead, children: [_jsx("span", { className: css.scopeTitle, children: t('scopeSection') }), _jsx("button", { type: "button", className: css.scopeInfo, title: `${t('scopeHint')}\n\n${t('scopeProbe')}`, "aria-label": t('scopeInfoLabel'), children: "i" })] }), scope.options.length === 0 ? (_jsx("div", { className: css.scopeHint, children: t('scopeUnavailable') })) : !scope.writable ? (_jsxs(_Fragment, { children: [_jsx("div", { className: css.scopeHint, children: providedScopeNote(t, scope.provider) }), modesLoading === true ? (_jsx("div", { className: css.scopeHint, children: t('modeBusy') })) : modeChips === undefined ? null : modeChips.length === 0 ? (_jsx("div", { className: css.scopeHint, children: t('modeNone') })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: css.scopeModes, children: [_jsx("span", { className: css.pvModesLabel, children: t('modeIn') }), modeChips.map(chip => (_jsx("button", { type: "button", className: css.modeChip, title: chip.isDefault ? t('modeChipDefaultHint') : t('modeChipHint'), onClick: () => onModeSelect?.(chip.id), children: chip.label }, chip.id)))] }), _jsx("div", { className: css.scopeHint, children: t('modeChipsCost') })] }))] })) : (_jsxs(_Fragment, { children: [_jsx("div", { className: css.scopeGrid, children: scope.options.map((option) => (_jsxs("label", { className: css.scopeItem, title: option.description, children: [_jsx("input", { type: "checkbox", checked: pickedScope.includes(option.id), disabled: scopeBusy, onChange: () => toggleScope(option.id) }), _jsx("span", { children: option.name ?? option.id }), option.broken !== undefined ? _jsx("span", { className: css.scopeBadge, children: t('scopeBroken') }) : null] }, option.id))) }), _jsxs("div", { className: css.scopeActions, children: [scope.managed ? (_jsx("button", { type: "button", className: css.addBtn, disabled: scopeBusy, onClick: () => void runScope(() => scope.save(pickedScope)), children: scopeBusy ? t('scopeSaving') : t('scopeSave') })) : null, scope.managed ? (_jsx("button", { type: "button", className: css.addBtn, disabled: scopeBusy, onClick: () => void runScope(() => scope.release()), children: t('scopeRelease') })) : scope.adoptable ? (_jsx("button", { type: "button", className: css.addBtn, disabled: scopeBusy, onClick: () => void runScope(() => scope.adopt(pickedScope)), children: t('scopeAdopt') })) : null, scopeMsg !== null ? _jsx("span", { className: css.scopeHint, children: scopeMsg }) : null] }), scope.conflict !== undefined ? (_jsxs("div", { className: css.scopeConflict, children: [t('scopeConflict'), ": ", scope.conflict] })) : null] }))] })) : null, data.metadataText !== undefined && hasUnrenderedMetadata(data.metadataText) ? (_jsxs("details", { className: css.source, children: [_jsx("summary", { className: css.sourceTitle, children: t('frontmatterMetadata') }), _jsx("pre", { className: css.codeBlk, children: formatMetadata(data.metadataText) })] })) : null, data.credentials !== undefined && data.credentials.length > 0 ? (_jsxs("details", { className: css.conf, open: true, children: [_jsx("summary", { className: css.confTitle, children: t('credentials') }), _jsx("div", { className: css.confHint, children: t('credentialsHint') }), data.credentials.map((decl) => {
+                        ] }), _jsx("p", { className: css.detailDesc, children: data.description }), scope !== undefined ? (_jsxs("section", { className: css.scopeBox, children: [_jsxs("div", { className: css.scopeHead, children: [_jsx("span", { className: css.scopeTitle, children: t('scopeSection') }), _jsx("button", { type: "button", className: css.scopeInfo, title: `${t('scopeHint')}\n\n${t('scopeProbe')}`, "aria-label": t('scopeInfoLabel'), children: "i" })] }), scope.options.length === 0 ? (_jsx("div", { className: css.scopeHint, children: t('scopeUnavailable') })) : !scope.writable ? (_jsxs(_Fragment, { children: [_jsx("div", { className: css.scopeHint, children: providedScopeNote(t, scope.provider) }), modesLoading === true ? (_jsx("div", { className: css.scopeHint, children: t('modeBusy') })) : modeChips === undefined ? null : modeChips.length === 0 ? (_jsx("div", { className: css.scopeHint, children: t('modeNone') })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: css.scopeModes, children: [_jsx("span", { className: css.pvModesLabel, children: t('modeIn') }), modeChips.map(chip => (_jsx("button", { type: "button", className: css.modeChip, title: chip.isDefault ? t('modeChipDefaultHint') : t('modeChipHint'), onClick: () => onModeSelect?.(chip.id), children: chip.label }, chip.id)))] }), _jsx("div", { className: css.scopeHint, children: t('modeChipsCost') })] }))] })) : (_jsxs(_Fragment, { children: [_jsx("div", { className: css.scopeGrid, children: scope.options.map((option) => (_jsxs("label", { className: css.scopeItem, title: option.description, children: [_jsx("input", { type: "checkbox", checked: pickedScope.includes(option.id), disabled: scopeBusy, onChange: () => toggleScope(option.id) }), _jsx("span", { children: option.name ?? option.id }), option.broken !== undefined ? _jsx("span", { className: css.scopeBadge, children: t('scopeBroken') }) : null] }, option.id))) }), _jsxs("div", { className: css.scopeActions, children: [_jsx("button", { type: "button", className: css.addBtn, disabled: scopeBusy || (scope.managed
+                                                    ? sameAsDeclared && scope.declared.length > 0
+                                                    : pickedScope.length === 0), onClick: () => void runScope(() => scope.apply(pickedScope)), children: scopeBusy ? t('scopeSaving') : t('scopeSave') }), scopeMsg !== null ? _jsx("span", { className: css.scopeHint, children: scopeMsg }) : null] }), scope.conflict !== undefined ? (_jsxs("div", { className: css.scopeConflict, children: [t('scopeConflict'), ": ", scope.conflict] })) : null] }))] })) : null, data.metadataText !== undefined && hasUnrenderedMetadata(data.metadataText) ? (_jsxs("details", { className: css.source, children: [_jsx("summary", { className: css.sourceTitle, children: t('frontmatterMetadata') }), _jsx("pre", { className: css.codeBlk, children: formatMetadata(data.metadataText) })] })) : null, data.credentials !== undefined && data.credentials.length > 0 ? (_jsxs("details", { className: css.conf, open: true, children: [_jsx("summary", { className: css.confTitle, children: t('credentials') }), _jsx("div", { className: css.confHint, children: t('credentialsHint') }), data.credentials.map((decl) => {
                                 const key = decl.key;
                                 const label = decl.label ?? key;
                                 const state = credState[key] ?? 'idle';

package/lib/types/client/locales.d.ts

@@ -165,8 +165,6 @@ export declare const zh: {
     scopeSave: string;
     scopeSaving: string;
     scopeSaved: string;
-    scopeAdopt: string;
-    scopeRelease: string;
     scopeConflict: string;
     scopeUnavailable: string;
     scopeBroken: string;
@@ -355,8 +353,6 @@ export declare const en: {
     scopeSave: string;
     scopeSaving: string;
     scopeSaved: string;
-    scopeAdopt: string;
-    scopeRelease: string;
     scopeConflict: string;
     scopeUnavailable: string;
     scopeBroken: string;

package/lib/types/client/locales.js

@@ -57,7 +57,7 @@ export const zh = {
     credentials: '凭据配置',
     credentialsHint: '该 skill 的 metadata 声明了以下凭据，配置后模型可读取。',
     envRefs: '引用的环境变量',
-    envRefsHint: '该 skill 的说明引用了以下变量；它们通常由运行环境或调用方提供，不在此页配置。',
+    envRefsHint: '该 skill 的说明引用了以下变量；它们通常由运行环境或调用方提供，不在此页配置。若某项是需要用户提供的密钥，在该 skill 的 SKILL.md frontmatter 中以 metadata.credentials 声明（key 填变量名）后即可在此页配置。',
     configured: '已配置',
     notConfigured: '未配置',
     configuredReplace: '已配置——输入新值可替换',
@@ -153,14 +153,12 @@ export const zh = {
     scopeAllPresets: '全部',
     scopeSection: '生效的 preset',
     scopeEvery: '所有 preset',
-    scopeHint: '勾选这个 skill 生效的 preset；一个都不勾表示所有模式可见。改的是 skill 自己的 frontmatter。',
+    scopeHint: '勾选这个 skill 生效的 preset；一个都不勾表示所有模式可见。被限定的 skill 由本插件代管投递；把勾选全部取消并保存，即还原为所有模式可见的普通用户技能。',
     scopeProvided: '该 skill 由插件「{provider}」提供：它在哪些模式生效取决于该插件挂在哪些预设的组合里，不能在这里单独限定。',
     scopeBuiltin: '该 skill 由部署内置提供：生效模式跟随部署组合，不能在这里单独限定。',
     scopeSave: '保存',
     scopeSaving: '保存中…',
     scopeSaved: '已保存',
-    scopeAdopt: '移入受管目录并可限定 preset',
-    scopeRelease: '释放回用户技能目录',
     scopeConflict: '已拒绝投递：默认根里还有一份同名副本（迁移没完成的残留）',
     scopeUnavailable: '此部署没有可用的 preset 名单，或受管投递未启用。',
     scopeBroken: '加载失败',
@@ -253,7 +251,7 @@ export const en = {
     credentials: 'Credential config',
     credentialsHint: 'The skill metadata declares these credentials; configure them so the model can read them.',
     envRefs: 'Referenced environment variables',
-    envRefsHint: 'The skill description references these variables; they are typically provided by the runtime or caller and are not configured here.',
+    envRefsHint: 'The skill description references these variables; they are typically provided by the runtime or caller and are not configured here. A user-supplied secret becomes configurable once declared under metadata.credentials in the SKILL.md frontmatter (key = the variable name).',
     configured: 'Configured',
     notConfigured: 'Not configured',
     configuredReplace: 'Configured — enter a new value to replace',
@@ -349,14 +347,12 @@ export const en = {
     scopeAllPresets: 'all',
     scopeSection: 'Effective presets',
     scopeEvery: 'All presets',
-    scopeHint: 'Tick the presets this skill is delivered to; none ticked means every preset sees it. This edits the skill\'s own frontmatter.',
+    scopeHint: 'Tick the presets this skill is delivered to; none ticked means every preset sees it. A scoped skill\'s delivery is managed by this plugin — untick everything and save to restore it as a plain user skill visible everywhere.',
     scopeProvided: 'This skill comes from the plugin "{provider}": which modes load it follows the plugin\'s row in each preset\'s composition, so its scope cannot be set here.',
     scopeBuiltin: 'This skill ships with the deployment: its modes follow the deployment composition and cannot be set here.',
     scopeSave: 'Save',
     scopeSaving: 'Saving…',
     scopeSaved: 'Saved',
-    scopeAdopt: 'Move into the managed root (preset-scoped)',
-    scopeRelease: 'Release back to the user skill root',
     scopeConflict: 'Delivery refused: a same-named copy still exists in a default root',
     scopeUnavailable: 'No preset roster is available in this deployment, or managed delivery is off.',
     scopeBroken: 'Failed to load',

package/lib/types/envHint.d.ts

@@ -1,6 +1,7 @@
 /**
  * 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
@@ -9,6 +10,11 @@
  * 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.

package/lib/types/envHint.js

@@ -1,6 +1,7 @@
 /**
  * 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
@@ -9,12 +10,18 @@
  * 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.
  * @module @khorsheed/dsh-capability-catalog/envHint
  */
-import { decodeCredentialDecls, decodeEnvDecls, mergeCredentialDecls, resolveServices } from './skills.js';
+import { collectSkillFiles, decodeCredentialDecls, decodeEnvDecls, mergeCredentialDecls, resolveServices } from './skills.js';
+import { READ_SKILL_FILE_TOOL, SCOPED_PROVIDER_NAME } from './scoped-delivery.js';
 const DSH_PREFIX = 'DSH_';
 /** Subscribe to `tools/post-execute`; appends an env-mapping hint for the
  * loaded skill. Returns a disposer. Degrades silently when tools/registry/
@@ -31,9 +38,12 @@ export function installSkillEnvHint(ctx, getScope) {
             const skillName = exec.arguments?.name;
             if (typeof skillName !== 'string' || skillName.length === 0)
                 return next();
-            const scope = await getScope().catch(() => undefined);
+            // Read at the CALLER's scope, not the catalog's settings scope: a skill
+            // scoped to a non-default preset is invisible to the latter, and the hint
+            // would never fire exactly where that skill actually loads.
+            const scope = exec.agent ?? await getScope().catch(() => undefined);
             const { registry, credentials } = resolveServices(ctx);
-            if (registry === undefined || credentials === undefined)
+            if (registry === undefined)
                 return next();
             const lookup = scope === undefined ? {} : { scope };
             let def;
@@ -45,27 +55,51 @@ export function installSkillEnvHint(ctx, getScope) {
             }
             if (def === undefined)
                 return next();
-            const decls = mergeCredentialDecls(decodeCredentialDecls(def.metadata), decodeEnvDecls(def.content ?? ''));
-            const configured = [];
-            for (const decl of decls) {
-                const info = await credentials.describe(decl.key).catch(() => undefined);
-                if (info?.configured === true)
-                    configured.push(decl.key);
+            const blocks = [];
+            if (credentials !== undefined) {
+                const decls = mergeCredentialDecls(decodeCredentialDecls(def.metadata), decodeEnvDecls(def.content ?? ''));
+                const configured = [];
+                for (const decl of decls) {
+                    const info = await credentials.describe(decl.key).catch(() => undefined);
+                    if (info?.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'));
+                }
+            }
+            // A scoped-delivered skill's SKILL.md may point at bundle files (search.md
+            // etc.) while the mode mounts no fs tools to read them. Name the reader
+            // only when the caller's own scope carries it — naming an absent tool
+            // teaches the model a call that can only fail.
+            const bundleDir = def.resourceBase?.kind === 'directory' ? def.resourceBase.path : undefined;
+            if (def.provider === SCOPED_PROVIDER_NAME && bundleDir !== undefined && exec.agent !== undefined) {
+                const tools = ctx.get?.('tools');
+                const hasReader = tools?.schemas?.(exec.agent)?.some(schema => schema.name === READ_SKILL_FILE_TOOL) === true;
+                if (hasReader) {
+                    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 (configured.length === 0)
+            if (blocks.length === 0)
                 return next();
-            const lines = [
-                `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.`,
-            ];
-            const hint = lines.join('\n');
             return {
                 kind: 'accept',
                 additionalContexts: [{
                         id: `capability-catalog-env-hint-${skillName}`,
                         role: 'user',
-                        content: [{ type: 'text', text: hint }],
+                        content: [{ type: 'text', text: blocks.join('\n\n') }],
                         // Producer-owned kind: the retired {kind: 'plugin'} wrapper fails the
                         // rc.1 native source admission at the durable write (turn-killing).
                         source: { kind: 'capability-catalog', plugin: 'capability-catalog', form: 'env-hint' },

package/lib/types/evidence.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 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
+ */
+import type { RegistrySlice } from './skills.ts';
+import { type CatalogToolsSlice } from './tool-face.ts';
+import type { CatalogSectionCompleteness } from './types.ts';
+/**
+ * What the evidence claims was measured: a preset composition at a given
+ * presetId and workdir, plus the caller-declared revision of that
+ * composition when one is available (e.g. its configuration digest). Every
+ * field is caller-verified input, echoed — the producer measures, it does
+ * not authenticate.
+ */
+export interface CapabilityEvidenceMeasurement {
+    readonly kind: 'preset-composition';
+    /** The preset the measured composition runs, as verified by the caller. */
+    readonly presetId?: string;
+    /** The workdir whose project-scoped roots were measured (absolute). */
+    readonly workdir?: string;
+    /** The measured composition's revision, when the caller has one. */
+    readonly revision?: string;
+}
+/**
+ * The caller's declaration of what was measured: which directories and which
+ * services the measurement read. Echoed into the evidence verbatim so a
+ * consumer can check the measurement against what it expected to be
+ * measured — a digest says nothing about its own coverage.
+ */
+export interface CapabilityEvidenceCoverage {
+    /** Directories the measurement read (skill roots, project roots). */
+    readonly directories?: readonly string[];
+    /** Services the measurement read (e.g. `skills`, `tools`). */
+    readonly services?: readonly string[];
+}
+/** What {@link produceCapabilityEvidence} needs. Every input is explicit. */
+export interface ProduceCapabilityEvidenceOptions {
+    /**
+     * The preset the measured composition runs — caller-verified. Stamped onto
+     * the snapshot (and echoed into the measurement) as given; it never enters
+     * the digest, the way `snapshotFor`'s `preset` stamp never does.
+     */
+    readonly presetId?: string;
+    /**
+     * The workdir whose project-scoped skill roots were measured — absolute
+     * and caller-verified. A relative path is refused rather than resolved:
+     * what it would resolve to depends on a cwd nobody verified.
+     */
+    readonly workdir?: string;
+    /** The measured composition's revision, when the caller has one. */
+    readonly revision?: string;
+    /**
+     * An already-resolved reading scope (opaque to this package), passed
+     * through to the registry reads. Never resolved here — resolution mounts,
+     * and mounting is the caller's decision. The caller owns any lease.
+     */
+    readonly scope?: unknown;
+    /** The skills registry to measure; absent = the skills section is `unavailable`. */
+    readonly skills?: RegistrySlice;
+    /** The tools registry to measure; absent = the tools section is `unavailable`. */
+    readonly tools?: CatalogToolsSlice;
+    /** Tools that appeared after the registry baseline (channel-heuristic input). */
+    readonly appearedAfterApply?: ReadonlySet<string>;
+    /** The caller's coverage declaration — required, because a digest without one cannot be checked against expectations. */
+    readonly coverage: CapabilityEvidenceCoverage;
+    /** Optional warning sink for the same diagnostics the Remote verbs log; dropped when absent. */
+    readonly warn?: (message: string) => void;
+}
+/** The per-section completeness of one produced evidence bundle (all four sections, always). */
+export interface CapabilityEvidenceCompleteness {
+    readonly skills: CatalogSectionCompleteness;
+    readonly tools: CatalogSectionCompleteness;
+    readonly mcpServers: CatalogSectionCompleteness;
+    readonly channels: CatalogSectionCompleteness;
+}
+/**
+ * What {@link produceCapabilityEvidence} answers. Plain JSON-safe data; safe
+ * across a JSON boundary, and the round-trip is pinned by a test.
+ */
+export interface ProducedCapabilityEvidence {
+    /** What claims to have been measured. */
+    readonly measurement: CapabilityEvidenceMeasurement;
+    /**
+     * The composition digest: `hashOf` over the fingerprinted snapshot, by this
+     * package's own algorithm. Consumers compare it, they never recompute it.
+     */
+    readonly sha: string;
+    /** How completely each snapshot section was measured. */
+    readonly completeness: CapabilityEvidenceCompleteness;
+    /** The caller's coverage declaration, echoed. */
+    readonly coverage: CapabilityEvidenceCoverage;
+}
+/**
+ * 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.
+ */
+export declare function produceCapabilityEvidence(options: ProduceCapabilityEvidenceOptions): Promise<ProducedCapabilityEvidence>;
+//# sourceMappingURL=evidence.d.ts.map