mcp-memory-bucket 0.8.4 → 0.8.7

package/dist/client/index.html

@@ -33,7 +33,7 @@
       z-index: 2147483000;
     }
   </style>
-  <script type="module" crossorigin src="/assets/index-_w_b_MQl.js"></script>
+  <script type="module" crossorigin src="/assets/index-y6XKwUMi.js"></script>
 </head>
 <body>
   <mem-bucket-app></mem-bucket-app>

package/dist/src/config.js

@@ -162,6 +162,51 @@ export function sanitizeFolderName(raw) {
         .replace(/^-+|-+$/g, '')
         .slice(0, 64);
 }
+/**
+ * Rewrites a REMOTE source's stored `folderPath` in the config file after it was renamed/moved on
+ * folderfoo — matched by the source's `name` (mem-bucket's own local identifier, immutable across
+ * a folderfoo-side rename), not by the old `folderPath` (which is exactly what just changed and so
+ * can no longer be used to find the entry). No-op if `name` isn't found or isn't a remote entry.
+ *
+ * `oldFolderPath`/`newFolderPath` describe the RENAMED FOLDER ITSELF, which may be an ancestor of
+ * (not necessarily equal to) the source's own `folderPath` — folderfoo's rename is recursive
+ * (renaming `work` also moves everything under `work/`), so a source registered at
+ * `work/project-x` must become `work2/project-x` when `work` itself is renamed to `work2`, not
+ * just when the source's exact path matches. Only rewrites when the source's folderPath is the
+ * renamed folder itself or nested under it — an unrelated source elsewhere in the tree is untouched.
+ */
+export function updateRemoteFolderPath(config, kind, name, oldFolderPath, newFolderPath) {
+    const current = readConfigFile(config.configPath);
+    const key = kind === 'skill' ? 'skill_sources' : 'memory_sources';
+    const existing = current[key];
+    if (!existing)
+        return;
+    let changed = false;
+    const next = existing.map((entry) => {
+        if (typeof entry === 'string' || entry.name !== name || !isRemoteEntry(entry))
+            return entry;
+        const rebased = rebaseFolderPath(entry.remote.folderPath, oldFolderPath, newFolderPath);
+        if (rebased === entry.remote.folderPath)
+            return entry;
+        changed = true;
+        return { ...entry, remote: { ...entry.remote, folderPath: rebased } };
+    });
+    if (!changed)
+        return;
+    fs.writeFileSync(config.configPath, JSON.stringify({ ...current, [key]: next }, null, 2) + '\n');
+}
+/**
+ * Rewrites `path` to reflect `oldPrefix` having been renamed to `newPrefix` — returns `path`
+ * unchanged if it isn't `oldPrefix` itself or nested under it. Shared by updateRemoteFolderPath
+ * (config file) and the repository-layer equivalent that repoints the in-memory RemoteFolder[].
+ */
+export function rebaseFolderPath(path, oldPrefix, newPrefix) {
+    if (path === oldPrefix)
+        return newPrefix;
+    if (oldPrefix && path.startsWith(`${oldPrefix}/`))
+        return `${newPrefix}${path.slice(oldPrefix.length)}`;
+    return path;
+}
 /**
  * Removes a named folder from the config file by name. Matches both explicit
  * {name, path} entries and bare-string entries (via their derived name).

package/dist/src/memory/repository.js

@@ -9,8 +9,9 @@ import { upsertFile, removeFile, scanSingleFolder, unregisterFolder, memorySyncS
 import { SearchQueryError, sanitizeFtsQuery } from '../store/search.js';
 import { applyBodyEdits } from '../shared/body-edits.js';
 import { attachmentsDirFor } from '../attachments/storage.js';
+import { rebaseFolderPath } from '../config.js';
 import { normalizeKey } from '../types.js';
-import { readFile as readRemoteFile, writeFile as writeRemoteFile, joinRemoteFolderPath } from '../remote/folderfoo-client.js';
+import { readFile as readRemoteFile, writeFile as writeRemoteFile, joinRemoteFolderPath, assertRemoteFolderExists } from '../remote/folderfoo-client.js';
 import { isFolderVisible } from '../remote/identity.js';
 /** Uppercases and strips everything but letters/digits — used to compare keys that differ only in
  * punctuation/whitespace formatting (e.g. `RMXS-15` and `RMXS15` strip to the same `RMXS15`). */
@@ -149,9 +150,25 @@ export class MemoryRepository {
             fs.rmSync(removedRemote.mirrorDir, { recursive: true, force: true });
         }
     }
+    /**
+     * Repoints a registered remote source's `folderPath` in place after it was renamed/moved on
+     * folderfoo — see SkillRepository's identical method for the full rationale (kept in sync with
+     * that one; this file has its own remoteFolders array, not shared state).
+     */
+    updateRemoteFolderPath(name, renamedFolderPath, newFolderPath) {
+        const remote = this.remoteFolders.find((f) => f.name === name);
+        if (!remote)
+            return;
+        remote.folderPath = rebaseFolderPath(remote.folderPath, renamedFolderPath, newFolderPath);
+    }
     /**
      * Exact-match lookup by normalized key, per V0 (no fuzzy matching).
      * `includePaused` defaults to false: paused docs are hidden from discovery (see setPaused).
+     * `folder`, when passed, restricts to docs in that one folder — memory_docs.id never collides
+     * across folders (it bakes in a random UUID suffix), but a human-facing `key` can legitimately
+     * repeat in different folders, so any caller treating "same key+description" as "the same doc"
+     * (e.g. relocate's already-relocated check) needs this to avoid a false match against an
+     * unrelated doc that just happens to share a key/description in a different folder.
      */
     getByKey(key, docType, opts = {}) {
         const normalized = normalizeKey(key);
@@ -161,6 +178,10 @@ export class MemoryRepository {
             conditions.push('doc_type = ?');
             params.push(docType);
         }
+        if (opts.folder) {
+            conditions.push('folder = ?');
+            params.push(opts.folder);
+        }
         if (!opts.includePaused) {
             conditions.push('paused = 0');
         }
@@ -339,11 +360,24 @@ export class MemoryRepository {
         // gets writeMarkdownFile's own formatting verbatim, not a hand-reconstructed string.
         const remote = this.remoteFor(targetFolder.name);
         if (remote && this.credentialsBaseDir) {
-            const relPath = path.relative(remote.mirrorDir, filePath).replace(/\.md$/, '');
-            const dir = joinRemoteFolderPath(remote.folderPath, path.dirname(relPath));
-            const name = path.basename(relPath);
-            const fileContents = fs.readFileSync(filePath, 'utf-8');
-            await writeRemoteFile(remote.server, this.credentialsBaseDir, remote.tenantId, dir, name, fileContents);
+            try {
+                // Confirms the remote folder still exists before writing — folderfoo's own save endpoint
+                // would otherwise silently recreate a deleted folder rather than failing (see
+                // assertRemoteFolderExists's doc comment).
+                await assertRemoteFolderExists(remote.server, this.credentialsBaseDir, remote.tenantId, remote.folderPath, targetFolder.name);
+                const relPath = path.relative(remote.mirrorDir, filePath).replace(/\.md$/, '');
+                const dir = joinRemoteFolderPath(remote.folderPath, path.dirname(relPath));
+                const name = path.basename(relPath);
+                const fileContents = fs.readFileSync(filePath, 'utf-8');
+                await writeRemoteFile(remote.server, this.credentialsBaseDir, remote.tenantId, dir, name, fileContents);
+            }
+            catch (err) {
+                // Remote push failed after the local mirror file was already written — remove the orphaned
+                // local file synchronously rather than leaving it for the next poll tick's
+                // reconcileDeletions to eventually clean up, so a failed create leaves zero trace immediately.
+                fs.unlinkSync(filePath);
+                throw err;
+            }
         }
         upsertFile(this.db, this.syncSpec, filePath);
         return { ...fm, body: input.body, paused: false };
@@ -383,6 +417,7 @@ export class MemoryRepository {
         writeMarkdownFile(existing.source_path, stripSourcePath(merged), newBody);
         const remote = this.remoteFor(existing.folder);
         if (remote && this.credentialsBaseDir) {
+            await assertRemoteFolderExists(remote.server, this.credentialsBaseDir, remote.tenantId, remote.folderPath, existing.folder);
             const relPath = path.relative(remote.mirrorDir, existing.source_path).replace(/\.md$/, '');
             const dir = joinRemoteFolderPath(remote.folderPath, path.dirname(relPath));
             const name = path.basename(relPath);

package/dist/src/remote/folderfoo-client.js

@@ -104,6 +104,31 @@ export async function getLastChanged(server, baseDir, tenantId, folderPath) {
 export async function listFolders(server, baseDir, tenantId) {
     return withAuth(server, baseDir, (jwt) => fetch(`${server}/folders`, { headers: { authorization: `Bearer ${jwt}`, 'x-tenant-id': tenantId } }), (res) => res.json());
 }
+/** Thrown when a write targets a remote folder that no longer exists on folderfoo (deleted server-side since the last connect/UI-open sync). */
+export class RemoteFolderGoneError extends Error {
+    constructor(folderName) {
+        super(`remote folder "${folderName}" no longer exists on folderfoo — reconnect or remove this source`);
+        this.name = 'RemoteFolderGoneError';
+    }
+}
+/**
+ * Confirms `folderPath` still exists on `server` before a write proceeds. folderfoo's own
+ * POST /save/:filename can never fail for a gone folder path — it unconditionally
+ * `mkdirSync(userDir, { recursive: true })`s before writing, silently recreating (un-deleting) the
+ * folder rather than erroring — so this is the only way to catch "the folder was deleted since we
+ * last checked" before a write silently resurrects it. Per the settled design, a write into a
+ * confirmed-gone folder should fail loudly (RemoteFolderGoneError), not silently recreate the
+ * folder — the user may have deleted it deliberately. `folderPath === ''` (a source's own root) is
+ * never gone (the user's account root always exists), so this only ever checks a non-root path.
+ */
+export async function assertRemoteFolderExists(server, baseDir, tenantId, folderPath, folderName) {
+    if (!folderPath)
+        return;
+    const folders = await listFolders(server, baseDir, tenantId);
+    if (!folders.some((f) => f.path === folderPath)) {
+        throw new RemoteFolderGoneError(folderName);
+    }
+}
 export async function getChangedSince(server, baseDir, tenantId, folderPath, since) {
     return withAuth(server, baseDir, (jwt) => fetch(`${server}/folders/changed-since?${folderQuery(tenantId, folderPath, { since: String(since) })}`, {
         headers: { authorization: `Bearer ${jwt}`, 'x-tenant-id': tenantId },

package/dist/src/server.js

@@ -64,6 +64,14 @@ const attachmentRepo = new AttachmentRepository(memoryRepo, skillRepo);
 // same upsertFile/removeFile path a local file-watch event would.
 const remoteSkillPoller = config.remoteSkillFolders.length > 0 ? startRemotePolling(db, skillSpec, config.remoteSkillFolders, config.baseDir) : undefined;
 const remoteMemoryPoller = config.remoteMemoryFolders.length > 0 ? startRemotePolling(db, memorySpec, config.remoteMemoryFolders, config.baseDir) : undefined;
+// Forces one immediate poll of every remote source at process start, instead
+// of leaving the cache to show whatever was last synced until the first
+// fixed interval tick (up to POLL_INTERVAL_MS later) - this is effectively
+// "login" for a background server: a fresh process (laptop wake, editor
+// reopened) is exactly when another device's writes are most likely to be
+// unseen locally yet.
+remoteSkillPoller?.resyncAll().catch((err) => console.error('[memory-bucket] initial remote skill resync failed:', err));
+remoteMemoryPoller?.resyncAll().catch((err) => console.error('[memory-bucket] initial remote memory resync failed:', err));
 if (config.skillFolders.length === 0 && config.memoryFolders.length === 0) {
     console.error(`[memory-bucket] no folders configured — open http://localhost:${PORT} to add one`);
 }

package/dist/src/shared/bucket-root-tool.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { saveRoot, removeRoot as removeRootFromConfig, sanitizeRootName } from '../config.js';
+import { initialScan } from '../store/sync.js';
+const KIND = z.enum(['skill', 'memory']);
+export function registerBucketRootTools(mcp, config, skillRepo, memoryRepo, db, skillSpec, memorySpec) {
+    mcp.tool('bucket_list_roots', 'Lists the configured skill and memory roots (the named source directories skills/memory docs live under, e.g. "super-skills", "demo-skills", "builtin") — use this to see what roots exist before passing a `root` argument to a create/list/search tool, or before adding/removing one.', {}, async () => {
+        const skill = skillRepo.listRoots().map((r) => ({ ...r, kind: 'skill' }));
+        const memory = memoryRepo.listRoots().map((r) => ({ ...r, kind: 'memory' }));
+        return { content: [{ type: 'text', text: JSON.stringify({ skill, memory }, null, 2) }] };
+    });
+    mcp.tool('bucket_create_root', 'Registers a new skill or memory root: an existing absolute directory path becomes a new named source that skill_create/memory_create can target via `root`. Scans it once and starts watching it live — never creates the directory itself, it must already exist.', {
+        kind: KIND,
+        path: z.string().describe('absolute path to an existing directory'),
+        name: z.string().optional().describe('name for the root; defaults to a sanitized version of the directory\'s basename'),
+    }, async ({ kind, path: dirPath, name }) => {
+        try {
+            if (!path.isAbsolute(dirPath)) {
+                return { content: [{ type: 'text', text: 'path must be an absolute directory path' }], isError: true };
+            }
+            if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
+                return { content: [{ type: 'text', text: `not a directory: ${dirPath}` }], isError: true };
+            }
+            const rootName = sanitizeRootName(name || path.basename(dirPath));
+            if (!rootName) {
+                return { content: [{ type: 'text', text: 'could not derive a valid root name — provide one explicitly' }], isError: true };
+            }
+            const repo = kind === 'skill' ? skillRepo : memoryRepo;
+            repo.addRoot({ name: rootName, path: dirPath });
+            saveRoot(config, kind, { name: rootName, path: dirPath });
+            return { content: [{ type: 'text', text: JSON.stringify({ name: rootName, path: dirPath, kind }, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('bucket_delete_root', 'Unregisters a skill or memory root by name: stops watching it and drops its cached entries from the index. Never touches files on disk — the directory and its contents are left in place.', { kind: KIND, name: z.string() }, async ({ kind, name }) => {
+        try {
+            const repo = kind === 'skill' ? skillRepo : memoryRepo;
+            repo.removeRoot(name);
+            removeRootFromConfig(config, kind, name);
+            return { content: [{ type: 'text', text: `Removed ${kind} root "${name}"` }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('bucket_rebuild_cache', 'EMERGENCY USE ONLY. Wipes the entire SQLite cache (all skills, memory docs, the full-text search index, and the date index) and rebuilds it from scratch by rescanning every configured root from disk. Source markdown files on disk are never touched — this only affects the derived cache, which is always safe to discard and regenerate. Use this only when other tools return results that contradict what you can see in the actual files (e.g. stale search hits, a doc that clearly exists on disk but skill_get/memory_get can\'t find, or search_by_date returning wrong dates) and a normal create/update/relocate call hasn\'t resolved it — this is a last resort, not a routine maintenance step. Takes a moment to complete on a large root; nothing else should be called until it returns.', {}, async () => {
+        try {
+            db.exec(`DELETE FROM skills; DELETE FROM memory_docs; DELETE FROM search_index; DELETE FROM doc_dates;`);
+            initialScan(db, skillSpec);
+            initialScan(db, memorySpec);
+            const skillCount = db.prepare(`SELECT COUNT(*) AS n FROM skills`).get().n;
+            const memoryCount = db.prepare(`SELECT COUNT(*) AS n FROM memory_docs`).get().n;
+            return {
+                content: [
+                    { type: 'text', text: `Cache rebuilt from disk: ${skillCount} skill(s), ${memoryCount} memory doc(s) reindexed.` },
+                ],
+            };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+}

package/dist/src/shared/relocate.js

@@ -64,6 +64,14 @@ export async function relocate(opts, skillRepo, memoryRepo) {
             trigger_phrases: [],
             extends: null,
         }, body, opts.overrides?.subfolder, opts.overrides?.folder);
+        // Belt-and-suspenders per the "never lose the source file" requirement: create() already
+        // throws (skipping the unlink below) on any failure, so this positive re-fetch is redundant
+        // today — but it guards against a future refactor of create()'s error handling silently
+        // swallowing a failure instead of throwing, which would otherwise make the unlink below
+        // fire despite the target write never actually landing.
+        if (!(await skillRepo.get(doc.name, doc.folder))) {
+            throw new Error(`relocate: skill "${doc.name}" create() reported success but is not readable back — refusing to delete the source file`);
+        }
         if (!opts.keep_original)
             fs.unlinkSync(opts.path);
         return { moved: true, id: doc.name, target: 'skill' };
@@ -80,7 +88,11 @@ export async function relocate(opts, skillRepo, memoryRepo) {
             reason: `filename does not clearly match the ticket-key naming pattern — ask the user for an explicit key and description, then retry with overrides.key/overrides.description`,
         };
     }
-    const already = memoryRepo.getByKey(key, docType).find((d) => d.description === description);
+    // Scoped to the destination folder: a same-key/description doc in a DIFFERENT folder is not
+    // "this file already relocated" — memory_docs ids never collide (see getByKey's doc comment),
+    // so without this scoping a genuinely new file could be silently refused because an unrelated
+    // doc elsewhere happens to share the same key+description.
+    const already = memoryRepo.getByKey(key, docType, { folder: opts.overrides?.folder }).find((d) => d.description === description);
     if (already) {
         return { moved: false, reason: `already relocated as memory doc "${already.id}"`, id: already.id, target: 'memory' };
     }
@@ -94,6 +106,10 @@ export async function relocate(opts, skillRepo, memoryRepo) {
         subfolder: opts.overrides?.subfolder,
         folder: opts.overrides?.folder,
     });
+    // Same belt-and-suspenders re-fetch as the skill branch above.
+    if (!(await memoryRepo.get(doc.id))) {
+        throw new Error(`relocate: memory doc "${doc.id}" create() reported success but is not readable back — refusing to delete the source file`);
+    }
     if (!opts.keep_original)
         fs.unlinkSync(opts.path);
     return { moved: true, id: doc.id, target: 'memory' };

package/dist/src/skills/repository.js

@@ -7,7 +7,8 @@ import { resolveWithinBase } from '../store/safe-path.js';
 import { upsertFile, removeFile, scanSingleFolder, unregisterFolder, skillSyncSpec } from '../store/sync.js';
 import { SearchQueryError, sanitizeFtsQuery } from '../store/search.js';
 import { applyBodyEdits } from '../shared/body-edits.js';
-import { readFile as readRemoteFile, writeFile as writeRemoteFile, joinRemoteFolderPath } from '../remote/folderfoo-client.js';
+import { rebaseFolderPath } from '../config.js';
+import { readFile as readRemoteFile, writeFile as writeRemoteFile, joinRemoteFolderPath, assertRemoteFolderExists } from '../remote/folderfoo-client.js';
 import { isFolderVisible } from '../remote/identity.js';
 function rowToDoc(row) {
     return {
@@ -62,11 +63,20 @@ export class SkillRepository {
         const identity = this.identity.current();
         return this.remoteFolders.filter((f) => !isFolderVisible(f, identity)).map((f) => f.name);
     }
-    /** Pushes the just-written SKILL.md at filePath to folderfoo, if targetFolderName resolves to a remote source. No-op for a local folder. See get()'s comment on the folderPath/name split for a skill's directory-per-skill layout. */
+    /**
+     * Pushes the just-written SKILL.md at filePath to folderfoo, if targetFolderName resolves to a
+     * remote source. No-op for a local folder. See get()'s comment on the folderPath/name split for
+     * a skill's directory-per-skill layout.
+     *
+     * Confirms the remote folder still exists before writing: folderfoo's own save endpoint would
+     * otherwise silently recreate a deleted folder rather than failing (see assertRemoteFolderExists's
+     * doc comment) — this turns that into a loud, specific RemoteFolderGoneError instead.
+     */
     async pushToRemoteIfNeeded(targetFolderName, filePath) {
         const remote = this.remoteFor(targetFolderName);
         if (!remote || !this.credentialsBaseDir)
             return;
+        await assertRemoteFolderExists(remote.server, this.credentialsBaseDir, remote.tenantId, remote.folderPath, targetFolderName);
         const skillDirRelPath = joinRemoteFolderPath(remote.folderPath, path.relative(remote.mirrorDir, path.dirname(filePath)));
         const fileContents = fs.readFileSync(filePath, 'utf-8');
         await writeRemoteFile(remote.server, this.credentialsBaseDir, remote.tenantId, skillDirRelPath, 'SKILL', fileContents);
@@ -152,6 +162,24 @@ export class SkillRepository {
             fs.rmSync(removedRemote.mirrorDir, { recursive: true, force: true });
         }
     }
+    /**
+     * Repoints a registered remote source's `folderPath` in place after it was renamed/moved on
+     * folderfoo — e.g. the embedded File Open dialog's `folderfoo-folder-changed` event. Unlike
+     * removeFolder, this keeps the source's local mirror directory, cached rows, and content
+     * completely untouched: only WHERE ON FOLDERFOO future polls/writes target changes, matching
+     * folderfoo's own rename (same content, new path) rather than a delete+reconnect.
+     *
+     * `renamedFolderPath`/`newFolderPath` describe the folder that was actually renamed on
+     * folderfoo, which may be an ancestor of this source's own `folderPath` (folderfoo's rename is
+     * recursive) — see config.ts's rebaseFolderPath for the shared prefix-rewrite logic. No-op if
+     * this source's folderPath isn't the renamed folder or nested under it.
+     */
+    updateRemoteFolderPath(name, renamedFolderPath, newFolderPath) {
+        const remote = this.remoteFolders.find((f) => f.name === name);
+        if (!remote)
+            return;
+        remote.folderPath = rebaseFolderPath(remote.folderPath, renamedFolderPath, newFolderPath);
+    }
     /** `includePaused` defaults to false: paused skills are hidden from discovery (see setPaused). */
     list(query, folder, opts = {}) {
         const conditions = [];
@@ -231,7 +259,7 @@ export class SkillRepository {
                   snippet(search_index, 3, '<<', '>>', '…', 20) AS snippet,
                   -bm25(search_index) AS score
            FROM search_index
-           JOIN skills s ON s.id = search_index.ref_id
+           JOIN skills s ON s.id = search_index.ref_id AND s.folder = search_index.ref_folder
            WHERE search_index.ref_table = 'skills' AND search_index MATCH ? ${conditions.map((c) => `AND ${c}`).join(' ')}
            ORDER BY bm25(search_index)
            LIMIT ? OFFSET ?`)
@@ -242,14 +270,34 @@ export class SkillRepository {
             throw new SearchQueryError(query, err);
         }
     }
+    /**
+     * Names are unique PER FOLDER, not globally (skills table key is (folder, id)) — so a bare `name`
+     * can match more than one row across configured folders. When `folder` is omitted and the name is
+     * unambiguous (unique across every configured folder, or only one folder configured), resolution
+     * works exactly as before. When it's genuinely ambiguous, this throws a disambiguation error
+     * listing the matching folders rather than silently picking one — per the settled multi-folder
+     * design (see FOLDERFOO-MULTI-FOLDER-SUPPORT's "Name collisions across sources" section).
+     */
+    resolveRow(name, folder) {
+        if (folder) {
+            return this.db.prepare(`SELECT * FROM skills WHERE folder = ? AND id = ?`).get(folder, name) ?? null;
+        }
+        const rows = this.db.prepare(`SELECT * FROM skills WHERE id = ?`).all(name);
+        if (rows.length === 0)
+            return null;
+        if (rows.length === 1)
+            return rows[0];
+        const folders = rows.map((r) => r.folder).join(', ');
+        throw new Error(`skill "${name}" exists in multiple folders (${folders}) — specify folder to disambiguate`);
+    }
     /**
      * For a skill in a LOCAL folder, returns the cached row unchanged (identical behavior to before
      * remote sources existed). For a skill in a REMOTE folder, the cached `body` is only ever a
      * poll-interval-stale mirror snapshot — per the settled design, `get` always fetches the current
      * body live from folderfoo instead of trusting it.
      */
-    async get(name) {
-        const row = this.db.prepare(`SELECT * FROM skills WHERE id = ?`).get(name);
+    async get(name, folder) {
+        const row = this.resolveRow(name, folder);
         if (!row)
             return null;
         const doc = rowToDoc(row);
@@ -282,14 +330,16 @@ export class SkillRepository {
      * Creates <folder>/[subfolder/]<name>/SKILL.md — folder-per-skill, per the
      * agentskills.io spec (`name` must equal the containing folder's name).
      * `folder` selects which configured skill folder to write into; required only
-     * when more than one user folder is configured.
+     * when more than one user folder is configured. Name uniqueness is checked only
+     * WITHIN that target folder — the same name existing in a different configured
+     * folder is not a collision (skills key on (folder, id), not on id alone).
      */
     async create(frontmatter, body, subfolder, folder) {
         assertValidSkillName(frontmatter.name);
-        if (await this.get(frontmatter.name)) {
-            throw new Error(`skill with name "${frontmatter.name}" already exists`);
-        }
         const targetFolder = this.resolveFolder(folder);
+        if (await this.get(frontmatter.name, targetFolder.name)) {
+            throw new Error(`skill with name "${frontmatter.name}" already exists in folder "${targetFolder.name}"`);
+        }
         const skillDir = resolveWithinBase(targetFolder.path, subfolder, frontmatter.name);
         if (fs.existsSync(skillDir)) {
             throw new Error(`skill directory already exists at ${skillDir}`);
@@ -314,9 +364,18 @@ export class SkillRepository {
             folder: targetFolder.name,
         };
         writeMarkdownFile(filePath, stripSourcePath(fm), body);
-        // Live/synchronous per the settled design — a folderfoo rejection here throws before upsertFile
-        // indexes the mirror as if the skill were successfully saved remotely.
-        await this.pushToRemoteIfNeeded(targetFolder.name, filePath);
+        try {
+            // Live/synchronous per the settled design — a folderfoo rejection here throws before upsertFile
+            // indexes the mirror as if the skill were successfully saved remotely.
+            await this.pushToRemoteIfNeeded(targetFolder.name, filePath);
+        }
+        catch (err) {
+            // Remote push failed after the local mirror was already written — remove the orphaned local
+            // dir synchronously rather than leaving it for the next poll tick's reconcileDeletions to
+            // eventually clean up, so a failed create leaves zero trace immediately.
+            fs.rmSync(skillDir, { recursive: true, force: true });
+            throw err;
+        }
         upsertFile(this.db, this.syncSpec, filePath);
         return { ...fm, body, paused: false };
     }
@@ -342,8 +401,8 @@ export class SkillRepository {
     isBuiltin(doc) {
         return doc.folder === this.folders[0]?.name;
     }
-    async update(name, frontmatter, body, bodyEdits) {
-        const existing = await this.get(name);
+    async update(name, frontmatter, body, bodyEdits, folder) {
+        const existing = await this.get(name, folder);
         if (!existing)
             throw new Error(`skill with name "${name}" not found`);
         // `paused` is local-cache-only and must never reach writeMarkdownFile — split it off of
@@ -381,15 +440,17 @@ export class SkillRepository {
      * attachment writes, not rename). Renaming a remote-sourced skill currently leaves a stale copy
      * under the old name on folderfoo; flagged here rather than silently incomplete.
      */
-    async rename(name, newName) {
+    async rename(name, newName, folder) {
         assertValidSkillName(newName);
-        const existing = await this.get(name);
+        const existing = await this.get(name, folder);
         if (!existing)
             throw new Error(`skill with name "${name}" not found`);
         if (newName === name)
             return existing;
-        if (await this.get(newName)) {
-            throw new Error(`skill with name "${newName}" already exists`);
+        // The rename target's collision check is scoped to the SAME folder the existing skill lives
+        // in — a rename never moves a skill to a different folder, so only that folder's names matter.
+        if (await this.get(newName, existing.folder)) {
+            throw new Error(`skill with name "${newName}" already exists in folder "${existing.folder}"`);
         }
         const oldDir = path.dirname(existing.source_path);
         const newDir = path.join(path.dirname(oldDir), newName);
@@ -461,7 +522,9 @@ export class SkillRepository {
                     throw new Error(`skill with name "${name}" not found`);
                 if (this.isBuiltin(existing))
                     throw new Error(`skill "${name}" is builtin and cannot be paused`);
-                this.db.prepare(`UPDATE skills SET paused = ? WHERE id = ?`).run(paused ? 1 : 0, name);
+                // Scoped to the resolved row's own folder — a bare `WHERE id = ?` would flip paused on
+                // EVERY folder's same-named skill at once now that names are only unique per folder.
+                this.db.prepare(`UPDATE skills SET paused = ? WHERE folder = ? AND id = ?`).run(paused ? 1 : 0, existing.folder, name);
                 results.push({ name, ok: true });
             }
             catch (err) {
@@ -489,8 +552,8 @@ export class SkillRepository {
         return results;
     }
     /** Removes the whole skill directory, including any scripts/references/assets alongside SKILL.md. Remote-folder note: does not delete the corresponding content on folderfoo — deletion isn't in the settled design's remote write scope (create/update/attachment writes only), same gap flagged on rename(). */
-    async delete(name) {
-        const existing = await this.get(name);
+    async delete(name, folder) {
+        const existing = await this.get(name, folder);
         if (!existing)
             throw new Error(`skill with name "${name}" not found`);
         if (this.isBuiltin(existing))

package/dist/src/skills/tools.js

@@ -51,12 +51,17 @@ export function registerSkillTools(mcp, repo) {
         const results = await repo.bulkUpdate(names, { add_tags, remove_tags, owner, status, extends: extendsId, deprecated });
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
-    mcp.tool('skill_get', 'Fetches a single skill by name, including its full markdown body.', { name: z.string() }, async ({ name }) => {
-        const doc = await repo.get(name);
-        if (!doc) {
-            return { content: [{ type: 'text', text: `No skill found with name "${name}"` }], isError: true };
+    mcp.tool('skill_get', `Fetches a single skill by name, including its full markdown body.${multiFolder ? ` Names are unique per folder, not globally — if "${folderNames}" has more than one skill sharing this name, pass folder to disambiguate; omitting it errors out when the name is ambiguous instead of guessing.` : ''}`, multiFolder ? { name: z.string(), folder: z.string().optional().describe(`disambiguates when the name exists in more than one folder: ${folderNames}`) } : { name: z.string() }, async ({ name, folder }) => {
+        try {
+            const doc = await repo.get(name, folder);
+            if (!doc) {
+                return { content: [{ type: 'text', text: `No skill found with name "${name}"` }], isError: true };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
         }
-        return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
     });
     mcp.tool('skill_bulk_get', 'Fetches many skills by name in one call, including full markdown bodies — e.g. hydrating a batch of skill_search hits. Missing names are simply omitted from the result, not errors.', { names: z.array(z.string()).min(1) }, async ({ names }) => {
         const docs = await repo.bulkGet(names);
@@ -133,21 +138,22 @@ export function registerSkillTools(mcp, repo) {
         trigger_phrases: z.array(z.string()).optional(),
         extends: z.string().optional(),
         deprecated: z.boolean().optional().describe('marks the skill as deprecated (or un-deprecates when false) — independent of status'),
-    }, async ({ name, body, body_edits, ...frontmatterFields }) => {
+        ...(multiFolder ? { folder: z.string().optional().describe(`disambiguates when the name exists in more than one folder: ${folderNames}`) } : {}),
+    }, async ({ name, body, body_edits, folder, ...frontmatterFields }) => {
         if (body !== undefined && body_edits !== undefined) {
             return { content: [{ type: 'text', text: 'Pass either body or body_edits, not both.' }], isError: true };
         }
         try {
             let diff;
             if (body_edits) {
-                const existing = await repo.get(name);
+                const existing = await repo.get(name, folder);
                 if (!existing)
                     throw new Error(`skill with name "${name}" not found`);
                 const { body: patchedBody, applied } = applyBodyEdits(existing.body, body_edits);
                 diff = formatBodyEditsDiff(applied);
                 body = patchedBody;
             }
-            const doc = await repo.update(name, frontmatterFields, body);
+            const doc = await repo.update(name, frontmatterFields, body, undefined, folder);
             // Body is omitted from the response: the caller either just sent it (full replacement),
             // already has it, or has `diff` — echoing a potentially large body back is pure waste.
             // Fetch skill_get(name) if the fresh full body is actually needed.
@@ -159,12 +165,18 @@ export function registerSkillTools(mcp, repo) {
             return { content: [{ type: 'text', text: err.message }], isError: true };
         }
     });
-    mcp.tool('skill_rename', 'Renames a skill: moves its folder to the new name and updates the frontmatter `name` field to match, preserving any scripts/references/assets alongside SKILL.md.', {
-        name: z.string().describe('current skill name'),
-        new_name: z.string().describe(SKILL_NAME_DESCRIPTION),
-    }, async ({ name, new_name }) => {
+    mcp.tool('skill_rename', `Renames a skill: moves its folder to the new name and updates the frontmatter \`name\` field to match, preserving any scripts/references/assets alongside SKILL.md.${multiFolder ? ` If the current name exists in more than one folder, pass folder to disambiguate which one to rename.` : ''}`, multiFolder
+        ? {
+            name: z.string().describe('current skill name'),
+            new_name: z.string().describe(SKILL_NAME_DESCRIPTION),
+            folder: z.string().optional().describe(`disambiguates when the current name exists in more than one folder: ${folderNames}`),
+        }
+        : {
+            name: z.string().describe('current skill name'),
+            new_name: z.string().describe(SKILL_NAME_DESCRIPTION),
+        }, async ({ name, new_name, folder }) => {
         try {
-            const doc = await repo.rename(name, new_name);
+            const doc = await repo.rename(name, new_name, folder);
             return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
         }
         catch (err) {
@@ -186,9 +198,11 @@ export function registerSkillTools(mcp, repo) {
         const results = await repo.setPaused(names, paused);
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
-    mcp.tool('skill_delete', 'Hard-deletes a skill by name — removes the whole skill folder (SKILL.md plus any scripts/references/assets), no tombstone.', { name: z.string() }, async ({ name }) => {
+    mcp.tool('skill_delete', `Hard-deletes a skill by name — removes the whole skill folder (SKILL.md plus any scripts/references/assets), no tombstone.${multiFolder ? ` If the name exists in more than one folder, pass folder to disambiguate which one to delete.` : ''}`, multiFolder
+        ? { name: z.string(), folder: z.string().optional().describe(`disambiguates when the name exists in more than one folder: ${folderNames}`) }
+        : { name: z.string() }, async ({ name, folder }) => {
         try {
-            await repo.delete(name);
+            await repo.delete(name, folder);
             return { content: [{ type: 'text', text: `Deleted skill "${name}"` }] };
         }
         catch (err) {