dsh-agent-plugins-market 0.6.2 → 0.7.1

package/lib/runtime/tool-registry-observer.js

@@ -1,31 +1,27 @@
-/** Host-private adapter for observing model-facing MCP tools. */
+/** Reading the model-facing MCP tools the host registry currently exposes. */
 /**
- * Read MCP tool names from the dsh-tools runtime when available.
+ * The MCP tools the host currently publishes to the model.
  *
- * The registry has no public listing API in the current host release. This
- * adapter uses the observed `layers.merge(...).tools.entries()` data shape and
- * returns an empty observation when a host changes it.
+ * Read through the tools service's own listing API rather than its internal
+ * layer structure. `schemas()` deep-clones each tool's parameter schema, which
+ * this snapshot has no use for, so a failure inside it degrades to an empty
+ * observation instead of taking the status surface down.
+ * @param tools - the host tools service, when it is mounted.
+ * @returns one entry per `mcp__`-namespaced tool.
  */
-export function inspectToolRegistry(runtime) {
-    if (typeof runtime !== 'object' || runtime === null)
+export function inspectToolRegistry(tools) {
+    const service = tools;
+    if (service === undefined || typeof service !== 'object' || service === null)
         return [];
-    const layers = runtime.layers;
-    if (typeof layers !== 'object' || layers === null)
+    if (typeof service.schemas !== 'function')
         return [];
-    const merge = layers.merge;
-    if (typeof merge !== 'function')
-        return [];
-    const empty = { entries: () => [] };
     try {
-        const visible = merge.call(layers, undefined, layer => layer.tools ?? empty);
         const output = [];
-        for (const [name, definition] of visible.entries()) {
-            if (!name.startsWith('mcp__'))
+        for (const schema of service.schemas()) {
+            if (!schema.name.startsWith('mcp__'))
                 continue;
-            const description = typeof definition === 'object' && definition !== null && typeof definition.description === 'string'
-                ? definition.description
-                : undefined;
-            output.push({ name, ...(description === undefined ? {} : { description }) });
+            const description = typeof schema.description === 'string' ? schema.description : undefined;
+            output.push({ name: schema.name, ...(description === undefined ? {} : { description }) });
         }
         return output;
     }
@@ -33,3 +29,7 @@ export function inspectToolRegistry(runtime) {
         return [];
     }
 }
+/** Read the tools service off the plugin context, when the host mounts one. */
+export function toolsServiceOf(ctx) {
+    return ctx.get?.('tools');
+}

package/lib/runtime/user-commands.js

@@ -6,6 +6,7 @@
  * change, keyed `user/<name>`.
  * @module runtime/user-commands
  */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { USER_ENTRY_NAME } from './user-store.js';
 /** Register/unregister user-panel commands to match the panel's enabled entries. */
 export class UserCommandMountRegistry {
@@ -62,9 +63,12 @@ export class UserCommandMountRegistry {
                     ...(spec.hint === undefined ? {} : { input: { hint: spec.hint } }),
                     handler: invocation => {
                         const agent = invocation.agent;
-                        const text = [this.t('userCommandForwardTitle', { command: spec.name }), '', spec.body.replaceAll('$ARGUMENTS', invocation.rawInput.trim())].join('\n');
-                        agent.followup({ content: [{ type: 'text', text }], source: { kind: 'plugin', plugin: 'dsh-agent-plugins-market' } });
-                        return { kind: 'success', text: this.t('userCommandAcknowledged', { command: spec.name }) };
+                        const text = spec.body.replaceAll('$ARGUMENTS', invocation.rawInput.trim());
+                        agent.followup(createUserMessage({
+                            content: [{ type: 'text', text }],
+                            source: { kind: 'plugin', plugin: 'dsh-agent-plugins-market' }
+                        }));
+                        return { kind: 'success', text: this.t('commandAcknowledged', { command: spec.name }) };
                     }
                 });
                 this.live.set(key, disposer);

package/lib/runtime/user-panels.js

@@ -1,8 +1,9 @@
 /**
  * User panel storage: the persistence layer behind the skills / commands /
- * agent-personas panels. Each surface owns one directory of Markdown files
- * under `<userRoot>/user/<kind>/`, so user-authored entries survive restarts,
- * are trivially hand-editable, and stay outside suite checkouts.
+ * agent-personas panels. Each surface owns one directory of Markdown
+ * documents under the shared Agent layout root (`~/.agents/<kind>/`), so
+ * user-authored entries survive restarts, are trivially hand-editable, and
+ * stay outside suite checkouts.
  *
  * Skills entries follow the SKILL.md frontmatter grammar (`name`,
  * `description`, optional `whenToUse`, invocation controls) plus a
@@ -10,75 +11,133 @@
  * frontmatter (`description`, optional `argument-hint`, `disabled`); agent
  * personas follow Claude Code agents frontmatter (`name`, `description`,
  * optional `whenToUse`, `tools`, `model`, `disabled`).
+ *
+ * Only the skills panel serves the cross-tool `<name>/SKILL.md` directory
+ * spelling beside its own flat entries; commands and personas stay flat.
+ *
+ * An entry's name is the one its document declares — the same name the
+ * harness reader derives from that file — and the panel addresses, edits, and
+ * deletes the entry by that name. A document that reader would reject is
+ * listed disabled with the reason instead of joining the catalog, and a skill
+ * is switched off by writing that reader's own invocation controls, so the off
+ * state lives in the file rather than in this provider.
  * @module runtime/user-panels
  */
-import { join } from 'node:path';
-import { deleteEntryFile, entryExists, listEntryFiles, readEntryFile, USER_ENTRY_NAME, userEntryDir, writeEntryFile } from './user-store.js';
+import { dirname } from 'node:path';
+import { skillEntryRejection } from '../catalog/skills-parse.js';
+import { deleteEntryDocument, entryExists, listEntryDocuments, listEntryFiles, readEntryDocument, resolveEntryDocument, SKILL_ENTRY_SHAPES, USER_ENTRY_NAME, userEntryDir, writeEntryDocument, writeEntryFile } from './user-store.js';
 /** The skill-source label user-panel entries carry into the skill registry. */
 export const USER_PANEL_SKILL_SOURCE = 'user-panel';
-/** Ranks sit behind every shipped root so real files always win a name clash. */
-const USER_PANEL_RANK = 600;
+/**
+ * Panel skills register ahead of the harness reader that maps this same
+ * directory (`dsh-skill-filesystem` roots `~/.agents/skills` as `user-agents`
+ * at rank 500), so the panel's localized description and its name precedence
+ * apply to the entries it serves. Project roots (100-300) and the user's
+ * `~/.dsh` skills (400) still outrank it, and it beats the suite user rank
+ * (450), so a skill the user wrote by hand wins over one an installed suite
+ * ships under the same name.
+ *
+ * Switching a skill off is not this provider's job: the panel writes the
+ * harness's own invocation pair into the document, which every reader of that
+ * file honors.
+ */
+const USER_PANEL_RANK = 440;
 /** Throwing CRUD over one panel directory, shared by the three panels. */
 export class UserPanelStore {
-    dataRoot;
+    agentsRoot;
     kind;
+    shapes;
     extraNameCheck;
-    constructor(dataRoot, kind, 
-    /** Extra name grammar for this panel (runs after USER_ENTRY_NAME). */
-    extraNameCheck = () => true) {
-        this.dataRoot = dataRoot;
+    validate;
+    honorInvocationControls;
+    constructor(agentsRoot, kind, options = {}) {
+        this.agentsRoot = agentsRoot;
         this.kind = kind;
-        this.extraNameCheck = extraNameCheck;
+        this.shapes = options.shapes ?? ['file'];
+        this.extraNameCheck = options.extraNameCheck ?? (() => true);
+        this.validate = options.validate;
+        this.honorInvocationControls = options.honorInvocationControls === true;
     }
-    /** The panel's directory under the data root. */
+    /** The panel's directory under the Agent layout root. */
     dirPath() {
-        return userEntryDir(this.dataRoot, this.kind);
-    }
-    /** The plugin data root the panel lives under. */
-    root() {
-        return this.dataRoot;
+        return userEntryDir(this.agentsRoot, this.kind);
     }
     get dir() {
         return this.dirPath();
     }
+    validName(name) {
+        return USER_ENTRY_NAME.test(name) && this.extraNameCheck(name);
+    }
+    /**
+     * Resolve the document one entry name addresses. The name a panel entry
+     * carries is the one its document declares, which is only the file name by
+     * convention, so a name that matches no path is matched against the
+     * declared names of the served documents.
+     */
+    async document(name) {
+        const direct = await resolveEntryDocument(this.dir, name, this.shapes);
+        if (direct !== undefined)
+            return direct;
+        for (const candidate of await listEntryDocuments(this.dir, false, this.shapes)) {
+            const file = await readEntryDocument(candidate);
+            if (file?.name === name)
+                return candidate;
+        }
+        return undefined;
+    }
     /** Every entry, sorted by name; strict snapshots propagate temporary I/O failures. */
     async list(strict = false) {
-        const files = await listEntryFiles(this.dir, strict);
+        const files = await listEntryFiles(this.dir, strict, this.shapes);
         return files.map(file => this.serialize(file));
     }
     /** One entry's full record, including the raw file text. */
     async get(name) {
-        if (!USER_ENTRY_NAME.test(name))
-            return undefined;
-        const file = await readEntryFile(join(this.dir, `${name}.md`), name);
-        if (file === undefined)
+        const document = await this.document(name);
+        if (document === undefined)
             return undefined;
-        return this.serialize(file);
+        const file = await readEntryDocument(document);
+        return file === undefined ? undefined : this.serialize(file);
     }
     /**
      * Project one parsed file onto the wire shape. The description prefers the
      * strict frontmatter parse (multi-line YAML like `description: |` survives
      * intact there) and falls back to the shallow line record.
+     *
+     * A document the panel must not register stays listed and editable but reads
+     * as disabled with the reason in its metadata, the same shape an unparseable
+     * frontmatter already produced — hiding it would leave the user no way to
+     * find or fix it.
      */
     serialize(file) {
         const strictDescription = typeof file.description === 'string' && file.description !== '' ? file.description : undefined;
         const shallowDescription = typeof file.meta['description'] === 'string' && file.meta['description'] !== '' ? file.meta['description'] : '';
+        const parseError = typeof file.meta['validationError'] === 'string' ? file.meta['validationError'] : undefined;
+        const rejection = parseError ?? this.validate?.(file);
+        // Both invocation controls off is the panel's off state as well: the switch
+        // writes that pair, and either key alone is an authoring choice (a
+        // user-invocable-only skill, for instance) that stays switched on.
+        const invocationOff = this.honorInvocationControls && file.invocation !== undefined && !file.invocation.modelInvocable && !file.invocation.userInvocable;
         return {
-            name: file.fallbackName,
+            // The declared name is the entry's name; a document that declares none
+            // the registry would accept is listed under its own file name, which is
+            // the name that keeps it addressable and fixable. `path` carries the
+            // document either way.
+            name: rejection === undefined ? file.name : file.documentName,
             description: strictDescription ?? shallowDescription,
-            disabled: file.meta['disabled'] === true,
-            metadata: file.meta,
+            disabled: file.meta['disabled'] === true || invocationOff || rejection !== undefined,
+            metadata: rejection === undefined ? file.meta : { ...file.meta, disabled: true, validationError: rejection },
             path: file.file,
+            shape: file.shape,
             content: file.body,
             rawText: file.text,
             origin: 'user'
         };
     }
-    /** Create an entry; refuses an occupied name. */
+    /** Create an entry; refuses an occupied name. New entries use the flat spelling. */
     async create(name, text) {
-        if (!USER_ENTRY_NAME.test(name) || !this.extraNameCheck(name))
+        if (!this.validName(name))
             throw new Error(`invalid name "${name}" — use lowercase letters, digits, and dashes, starting with a letter or digit`);
-        if (await entryExists(this.dir, name))
+        if (await entryExists(this.dir, name, this.shapes))
             throw new Error(`an entry named "${name}" already exists`);
         await writeEntryFile(this.dir, name, text);
         const created = await this.get(name);
@@ -86,27 +145,36 @@ export class UserPanelStore {
             throw new Error(`entry "${name}" vanished after write`);
         return created;
     }
-    /** Replace one entry's file content wholesale. */
+    /** Replace one entry's content wholesale, keeping the spelling it already has. */
     async update(name, text) {
-        if (!USER_ENTRY_NAME.test(name) || !this.extraNameCheck(name))
+        if (!this.validName(name))
             throw new Error(`invalid entry name "${name}"`);
-        if (!(await entryExists(this.dir, name)))
+        const document = await this.document(name);
+        if (document === undefined)
             throw new Error(`no entry named "${name}"`);
-        await writeEntryFile(this.dir, name, text);
+        await writeEntryDocument(document, text);
     }
     /** Delete one entry; a missing file is a no-op (idempotent delete). */
     async remove(name) {
         if (!USER_ENTRY_NAME.test(name))
             throw new Error(`invalid entry name "${name}"`);
-        await deleteEntryFile(this.dir, name);
+        const document = await this.document(name);
+        if (document === undefined)
+            return;
+        await deleteEntryDocument(document);
     }
 }
 /** Locate the three stores; constructed once per plugin activation. */
-export function createUserPanelStores(dataRoot) {
+export function createUserPanelStores(agentsRoot) {
     return {
-        skills: new UserPanelStore(dataRoot, 'skills', isUserSkillEntryName),
-        commands: new UserPanelStore(dataRoot, 'commands'),
-        agents: new UserPanelStore(dataRoot, 'agents', isUserSkillEntryName)
+        skills: new UserPanelStore(agentsRoot, 'skills', {
+            extraNameCheck: isUserSkillEntryName,
+            shapes: SKILL_ENTRY_SHAPES,
+            validate: file => skillEntryRejection(file.text),
+            honorInvocationControls: true
+        }),
+        commands: new UserPanelStore(agentsRoot, 'commands'),
+        agents: new UserPanelStore(agentsRoot, 'agents', { extraNameCheck: isUserSkillEntryName })
     };
 }
 /**
@@ -125,11 +193,9 @@ export function isUserSkillEntryName(name) {
  */
 export class UserPanelSkillProvider {
     skills;
-    t;
     name = 'user-panel';
-    constructor(skills, t) {
+    constructor(skills) {
         this.skills = skills;
-        this.t = t;
     }
     async list(_options) {
         const candidates = [];
@@ -138,8 +204,13 @@ export class UserPanelSkillProvider {
             if (entry.disabled || !isUserSkillEntryName(entry.name))
                 continue;
             candidates.push({
+                // The entry's name is the one its document declares, which is also the
+                // name the harness's own reader derives from the same file.
                 name: entry.name,
-                description: this.t('userSkillDescription', { description: entry.description === '' ? entry.name : entry.description }),
+                // The entry's own description verbatim; a user-entry label is our
+                // packaging, and this description reaches the same model-facing
+                // catalog a suite skill does.
+                description: entry.description === '' ? entry.name : entry.description,
                 ...(typeof entry.metadata['whenToUse'] === 'string' && entry.metadata['whenToUse'] !== '' ? { whenToUse: entry.metadata['whenToUse'] } : {}),
                 invocation: {
                     modelInvocable: entry.metadata['disable-model-invocation'] !== true,
@@ -150,7 +221,7 @@ export class UserPanelSkillProvider {
                 rank: USER_PANEL_RANK,
                 locator: { name: entry.name },
                 path: entry.path,
-                resourceBase: { kind: 'directory', path: this.skills.dirPath() }
+                resourceBase: { kind: 'directory', path: this.resourceDirectory(entry) }
             });
         }
         return candidates;
@@ -168,9 +239,17 @@ export class UserPanelSkillProvider {
             invocation: candidate.invocation,
             source: candidate.source,
             provider: this.name,
-            resourceBase: { kind: 'directory', path: store.dirPath() },
+            resourceBase: { kind: 'directory', path: this.resourceDirectory(entry) },
             path: entry.path,
             content: entry.content
         };
     }
+    /**
+     * Relative resources resolve beside the document that references them: a
+     * directory-shaped skill owns `references/`, `scripts/` and the like next to
+     * its `SKILL.md`, while a flat entry resolves against the panel directory.
+     */
+    resourceDirectory(entry) {
+        return entry.shape === 'skill-directory' ? dirname(entry.path) : this.skills.dirPath();
+    }
 }

package/lib/runtime/user-store.js

@@ -1,34 +1,102 @@
 /**
  * Shared persistence primitives for the market's user-authored panels:
  * skills, commands, and agent personas. Each panel owns one directory of
- * Markdown files under the plugin data root, parsed with the same frontmatter
- * rules the catalog uses, so user entries look exactly like suite entries to
- * the runtime mounts.
+ * Markdown documents under the Agent layout root, parsed with the same
+ * frontmatter rules the catalog uses, so user entries look exactly like suite
+ * entries to the runtime mounts.
+ *
+ * An entry is one document. Skills also accept the cross-tool directory
+ * spelling (`<name>/SKILL.md`) that other Agent tools and the harness's own
+ * reader of `~/.agents/skills` author; commands and personas are flat only.
  * @module runtime/user-store
  */
-import { mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readdir, readFile, rmdir, rm, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import { parseDocument, stringify } from 'yaml';
 import { parseSkillFrontmatter, stripFrontmatter } from '../catalog/skills-parse.js';
-/** Where user panel entries persist: `<userRoot>/user/<kind>/`. */
-export function userEntryDir(dataRoot, kind) {
-    return join(dataRoot, 'user', kind);
+/** Where user panel entries persist: `<agentsRoot>/<kind>/`. */
+export function userEntryDir(agentsRoot, kind) {
+    return join(agentsRoot, kind);
 }
 /** `[a-z][a-z0-9_-]*` — the grammar every panel entry name must satisfy. */
 export const USER_ENTRY_NAME = /^[a-z][a-z0-9_-]*$/;
-/** The enablement frontmatter key shared by skills and commands. */
-export const DISABLED_KEY = 'disabled';
+/** The file name of a directory-shaped skill's document. */
+export const SKILL_ENTRY_FILE = 'SKILL.md';
+/**
+ * The spellings the skills panel serves, most preferred first: a name present
+ * as both a directory and a file resolves to the directory, which is the
+ * canonical cross-tool spelling and the one the harness's own reader of
+ * `~/.agents/skills` reaches first.
+ */
+export const SKILL_ENTRY_SHAPES = ['skill-directory', 'file'];
+/** The document path one entry name maps to under its kind directory. */
+export function entryDocumentPath(dir, name, shape) {
+    return shape === 'skill-directory' ? join(dir, name, SKILL_ENTRY_FILE) : join(dir, `${name}.md`);
+}
+/** Whether a path is a regular file; strict runtime snapshots propagate real I/O failures. */
+async function isFile(file, strict) {
+    try {
+        return (await stat(file)).isFile();
+    }
+    catch (error) {
+        if (strict && error.code !== 'ENOENT')
+            throw error;
+        return false;
+    }
+}
+/**
+ * Resolve one entry name to its document, taking the first shape the path
+ * exists in. Names outside the entry grammar never touch the filesystem.
+ */
+export async function resolveEntryDocument(dir, name, shapes, strict = false) {
+    if (!USER_ENTRY_NAME.test(name))
+        return undefined;
+    for (const shape of shapes) {
+        const file = entryDocumentPath(dir, name, shape);
+        if (await isFile(file, strict))
+            return { name, file, directory: dirname(file), shape };
+    }
+    return undefined;
+}
+/** Every entry document the served shapes expose, deduplicated by name at the first shape that has it. */
+export async function listEntryDocuments(dir, strict = false, shapes = ['file']) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (strict && error.code !== 'ENOENT')
+            throw error;
+        return [];
+    }
+    const found = new Map();
+    for (const entry of entries.sort()) {
+        const name = entry.endsWith('.md') ? entry.slice(0, -3) : shapes.includes('skill-directory') ? entry : undefined;
+        if (name === undefined || !USER_ENTRY_NAME.test(name))
+            continue;
+        for (const shape of shapes) {
+            const file = entryDocumentPath(dir, name, shape);
+            if (!(await isFile(file, strict)))
+                continue;
+            found.set(name, { name, file, directory: dirname(file), shape });
+            break;
+        }
+    }
+    return [...found.values()];
+}
 /** Parse full YAML metadata without flattening arrays, mappings, or multiline strings. */
 export function parseFrontmatterRecord(text) {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
-    if (match === null) {
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text)?.[1];
+    if (frontmatter === undefined) {
         if (/^---(?:\r?\n|$)/.test(text))
             throw new Error('Invalid frontmatter: missing closing delimiter');
         return {};
     }
-    const doc = parseDocument(match[1]);
-    if (doc.errors.length > 0)
-        throw new Error(`Invalid frontmatter: ${doc.errors[0].message}`);
+    const doc = parseDocument(frontmatter);
+    const error = doc.errors[0];
+    if (error !== undefined)
+        throw new Error(`Invalid frontmatter: ${error.message}`);
     const value = doc.toJS({ maxAliasCount: 100 });
     if (value === null)
         return {};
@@ -36,13 +104,11 @@ export function parseFrontmatterRecord(text) {
         throw new Error('Frontmatter must be a mapping');
     return value;
 }
-/** Read one entry; strict runtime snapshots throw on I/O errors other than a vanished file. */
-export async function readEntryFile(file, fallbackName, strict = false) {
-    if (fallbackName !== '' && !USER_ENTRY_NAME.test(fallbackName))
-        return undefined;
+/** Read one resolved entry; strict runtime snapshots throw on I/O errors other than a vanished file. */
+export async function readEntryDocument(document, strict = false) {
     let text;
     try {
-        text = await readFile(file, 'utf8');
+        text = await readFile(document.file, 'utf8');
     }
     catch (error) {
         if (strict && error.code !== 'ENOENT')
@@ -56,56 +122,45 @@ export async function readEntryFile(file, fallbackName, strict = false) {
     catch (error) {
         meta = { disabled: true, validationError: String(error) };
     }
-    const parsed = parseSkillFrontmatter(text, fallbackName);
-    const name = typeof parsed === 'string' ? fallbackName : typeof parsed.name === 'string' && parsed.name !== '' ? parsed.name : fallbackName;
+    // The declared name is read without an expected-value check: the harness's
+    // own reader of this directory takes the frontmatter name as the skill's
+    // name and never compares it to the file or directory name.
+    const parsed = parseSkillFrontmatter(text, undefined);
+    const name = typeof parsed === 'string' ? document.name : typeof parsed.name === 'string' && parsed.name !== '' ? parsed.name : document.name;
     return {
-        fallbackName,
+        documentName: document.name,
         name,
-        file,
+        file: document.file,
+        directory: document.directory,
+        shape: document.shape,
         text,
         body: stripFrontmatter(text),
         meta,
         ...(typeof parsed === 'string' ? {} : parsed)
     };
 }
-/** List `.md` entries; strict runtime snapshots propagate I/O errors instead of publishing partial inventories. */
-export async function listEntryFiles(dir, strict = false) {
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch (error) {
-        if (strict && error.code !== 'ENOENT')
-            throw error;
-        return [];
-    }
+/** List entries across the served shapes; strict runtime snapshots propagate I/O errors instead of publishing partial inventories. */
+export async function listEntryFiles(dir, strict = false, shapes = ['file']) {
+    const documents = await listEntryDocuments(dir, strict, shapes);
     const found = [];
-    for (const entry of entries.sort()) {
-        if (!entry.endsWith('.md'))
-            continue;
-        const file = join(dir, entry);
-        try {
-            const info = await stat(file);
-            if (!info.isFile())
-                continue;
-        }
-        catch (error) {
-            if (strict && error.code !== 'ENOENT')
-                throw error;
-            continue;
-        }
-        const parsed = await readEntryFile(file, entry.slice(0, -3), strict);
+    for (const document of documents) {
+        const parsed = await readEntryDocument(document, strict);
         if (parsed !== undefined)
             found.push(parsed);
     }
     return found;
 }
-/** Write one panel entry; the name becomes `<name>.md`. */
-export async function writeEntryFile(dir, name, text) {
+/** Create one panel entry's document from its name: `<name>.md`, or `<name>/SKILL.md` in the directory shape. */
+export async function writeEntryFile(dir, name, text, shape = 'file') {
     assertEntryName(name);
+    const file = entryDocumentPath(dir, name, shape);
+    await writeEntryDocument({ name, file, directory: dirname(file), shape }, text);
+}
+/** Replace one resolved entry's document in place, wherever it lives. */
+export async function writeEntryDocument(document, text) {
+    assertEntryName(document.name);
     parseFrontmatterRecord(text);
-    await mkdir(dir, { recursive: true });
-    await writeFile(join(dir, `${name}.md`), text, 'utf8');
+    await writeFileAtomic(document.file, text, { mode: 0o644, dirMode: 0o700 });
 }
 /**
  * Enforce the entry-name grammar at every filesystem choke point. The name
@@ -117,22 +172,22 @@ function assertEntryName(name) {
     if (!USER_ENTRY_NAME.test(name))
         throw new Error(`invalid entry name "${name}" — use lowercase letters, digits, dashes, or underscores, starting with a letter`);
 }
-/** Delete one panel entry file; missing files resolve silently. */
-export async function deleteEntryFile(dir, name) {
-    assertEntryName(name);
-    await rm(join(dir, `${name}.md`), { force: true });
+/**
+ * Delete one resolved entry's document; a missing file resolves silently. A
+ * skill directory belongs to whichever tool authored it, so removal deletes
+ * the document it served and the directory only once nothing else is left in
+ * it — never the `references/`, `scripts/`, or persona files beside its
+ * `SKILL.md`.
+ */
+export async function deleteEntryDocument(document) {
+    assertEntryName(document.name);
+    await rm(document.file, { force: true });
+    if (document.shape === 'skill-directory')
+        await rmdir(dirname(document.file)).catch(() => undefined);
 }
-/** Whether an entry file with that name already exists. */
-export async function entryExists(dir, name) {
-    if (!USER_ENTRY_NAME.test(name))
-        return false;
-    try {
-        await stat(join(dir, `${name}.md`));
-        return true;
-    }
-    catch {
-        return false;
-    }
+/** Whether an entry document with that name exists in any served shape. */
+export async function entryExists(dir, name, shapes = ['file']) {
+    return (await resolveEntryDocument(dir, name, shapes)) !== undefined;
 }
 /** Serialize a frontmatter block from a shallow record (deterministic key order). */
 export function serializeFrontmatter(meta) {