prism-mcp-server 20.8.1 → 20.9.0

package/README.md

@@ -116,6 +116,31 @@ or by re-enabling after each run.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.9.0
+
+- **Your skills follow your account.** `skill_save` stores a skill at the
+  scope you choose: this machine only (`local`, works offline and signed out),
+  your account (`user` — every machine you sign into receives it), or a
+  workspace (`team` — shared with members, admin-managed, optionally targeted
+  to specific people).
+- **Trim the catalog you don't use.** `skill_manage` can release platform
+  skills you never touch — freeing host skill-catalog budget — and restore
+  them any time, losslessly. Deleting a scoped skill archives its final
+  content locally first, so nothing is ever silently unrecoverable.
+
+## What's New in v20.8.2
+
+- **Skill delivery now admits failure instead of hiding it.** A filesystem
+  permission edge case (a umask stripping the owner-execute bit) could leave
+  skill sync writing nothing while reporting itself current — measured at nine
+  days on a real machine. Broken managed directories are repaired in place,
+  every directory is created umask-proof, and the repair path refuses symlinks
+  via an `O_NOFOLLOW` descriptor.
+- **A stale install tells you at startup.** Prism now tracks the generation
+  that actually reached disk separately from the one the database accepted; if
+  they diverge, the startup banner says so in a warning placed where display
+  truncation cannot cut it. A successful sync clears it automatically.
+
 ## What's New in v20.7 – v20.8.0
 
 - **First run proves the memory instead of describing it** — `session_bootstrap`
@@ -608,10 +633,10 @@ for manual configuration and host-specific paths.
 **Optional — local model fleet** for offline tool-routing. Pull whichever fits your hardware:
 
 ```bash
-ollama pull dcostenco/prism-coder:2b    # 2.3 GB · mobile / lightweight (99.1% routing accuracy)
-ollama pull dcostenco/prism-coder:4b    # 3.4 GB · verifier (100% accuracy)
-ollama pull dcostenco/prism-coder:9b    # 5.8 GB · default router (100% accuracy, Qwen3.5)
-ollama pull dcostenco/prism-coder:27b   # 16 GB  · complex tasks (100% accuracy)
+ollama pull dcostenco/prism-coder:2b    # 2.3 GB · mobile / lightweight (99.1% on our routing suite)
+ollama pull dcostenco/prism-coder:4b    # 3.4 GB · verifier (100% on our routing suite)
+ollama pull dcostenco/prism-coder:9b    # 5.8 GB · default router (100% on our routing suite, Qwen3.5)
+ollama pull dcostenco/prism-coder:27b   # 16 GB  · complex tasks (100% on our routing suite)
 ```
 
 Prism detects both the namespaced (`dcostenco/prism-coder:9b`) and bare (`prism-coder:9b`) Ollama tags automatically.
@@ -632,6 +657,23 @@ Every conversation feeds a persistent store. The next session loads the right co
 
 The dashboard shows your current project state, pending TODOs, intent health, and a neural knowledge graph — all built automatically from your agent sessions.
 
+### Export — read the record outside the agent
+
+`session_export_memory` writes your memory out as plain files you can read,
+diff, and commit. Nothing goes through a model to produce it.
+
+```
+markdown   human-readable — drop it in a PR to show what the agent actually did
+json       machine-readable — import into another Prism instance
+vault      zipped Markdown with YAML frontmatter and [[wikilinks]] (Obsidian, Logseq)
+```
+
+This is the surface to reach for when you want to answer "did the agent verify
+this, or is it claiming it did?" — the export is a record you review after the
+fact, in a diff or a pull request, rather than a live view you have to go and
+open. The same data is available from the dashboard's **Export ZIP** and
+**Export Vault** buttons.
+
 ### Knowledge Graph — semantic + keyword + graph search
 
 Ask "what did I decide about the auth flow last month?" and get an answer with citations, combining vector similarity, full-text search, and graph traversal.
@@ -741,7 +783,7 @@ air-gap. **Enterprise** includes a HIPAA Business Associate Agreement.
 
 ## Models
 
-The `prism-coder` fleet uses Qwen3.5 for MCP tool-routing AND general inference. The 9B and 27B are fine-tuned with LoRA (r=128, all 64 layers including DeltaNet); the 2B and 4B use stock Qwen3.5-4B at different quantization levels. The 27B scored 100% on BFCL function-calling and 100% on an internal 15-problem coding eval at $0 inference cost.
+The `prism-coder` fleet uses Qwen3.5 for MCP tool-routing AND general inference. The 9B and 27B are fine-tuned with LoRA (r=128, all 64 layers including DeltaNet); the 2B and 4B use stock Qwen3.5-4B at different quantization levels. The 27B scored 100% on our internal 115-case tool-routing suite and 100% on an internal 15-problem coding eval, at $0 inference cost. These are self-run evaluations, not [BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html) leaderboard submissions.
 
 `prism_infer` supports three modes: `route` (tool routing, fast, nothink), `chat` (conversation with thinking), and `code` (code generation with thinking). In chat/code modes, the model uses `<think>` blocks for chain-of-thought reasoning, which are stripped before the response is served. If the local model fails a quality gate (empty, think-only, or truncated), paid tiers automatically escalate to Gemini 3.6 Flash via the Synalux portal.
 
@@ -753,13 +795,17 @@ draft that may need correction—to Synalux for authenticated deterministic
 correction. Advertised custom host tools remain local. Set
 `route_guard: "local"` for a fully on-device route path.
 
-| Model | Ollama tag | Size | [BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html) Accuracy | Role | Automatic routing tier |
+| Model | Ollama tag | Size | Routing accuracy¹ | Role | Automatic routing tier |
 |---|---|---|---|---|---|
 | Qwen3.5-4B Q3_K_M | `prism-coder:2b` | 2.3 GB | 99.1% × 3 seeds | iPhone / mobile first gate | Free |
 | Qwen3.5-4B Q4_K_M | `prism-coder:4b` | 3.4 GB | 100% × 3 seeds | Verifier | Free |
 | Qwen3.5-9B (LoRA) | `prism-coder:9b` | 5.8 GB | 100% × 3 seeds | Default router | Standard+ |
 | Qwen3.5-27B (LoRA) | `prism-coder:27b` | 16 GB | 100% × 3 seeds | Quality tier (DeltaNet, 28.5 tok/s) | Advanced+ |
 
+¹ Self-run on a narrow 115-case MCP tool-selection suite, 3 seeds. It says these
+models pick the right tool on our own eval, nothing more — not a general capability
+measure, and not an independent benchmark result. Full methodology caveats below.
+
 These tiers control automatic `prism_infer` selection, not Ollama itself. Any
 user can run any downloaded on-device model directly through Ollama on every
 plan.

package/dist/agentManifestSync.js

@@ -20,7 +20,8 @@
  * side.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { link, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdirUsable, repairOwnerAccess } from "./utils/usableDirectory.js";
+import { link, lstat, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const OWNER = "prism-mcp";
@@ -306,11 +307,14 @@ function isErrno(error, code) {
  * mid-run leaves files that the next run re-proves ownership of by digest.
  */
 export async function materializeAgentDefinitions(section, targetDir, render = renderClaudeAgent) {
-    await mkdir(targetDir, { recursive: true, mode: 0o700 });
+    // Same umask trap as the skill roots: a masked mkdir leaves a directory
+    // nothing can enter, and every write below it then fails.
+    await mkdirUsable(targetDir);
     const rootStat = await lstat(targetDir);
     if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
         throw new Error("agent root must be a real directory");
     }
+    await repairOwnerAccess(targetDir, rootStat.mode);
     const indexPath = join(targetDir, INDEX);
     const index = await readIndex(indexPath);
     const owned = index?.files ?? {};

package/dist/server.js

@@ -68,6 +68,7 @@ import { getSyncBus } from "./sync/factory.js";
 import { startDashboardServer } from "./dashboard/server.js";
 import { acquireLock, registerShutdownHandlers } from "./lifecycle.js";
 import { verifyBehaviorHandler } from "./tools/behavioralVerifierHandler.js";
+import { SKILL_SAVE_TOOL, SKILL_MANAGE_TOOL, skillSaveHandler, skillManageHandler } from "./tools/skillScopeHandlers.js";
 // ─── v2.3.6 FIX: Use Storage Abstraction for Prompts/Resources ───
 // CRITICAL FIX: Previously imported supabaseRpc/supabaseGet directly,
 // which bypassed the storage abstraction layer and caused the server
@@ -185,6 +186,8 @@ const BASE_TOOLS = [
 function buildSessionMemoryTools() {
     return [
         SESSION_BOOTSTRAP_TOOL, // session_bootstrap — hook-free configured first-turn greeting + context
+        SKILL_SAVE_TOOL, // skill_save — save a skill at local/user/team scope
+        SKILL_MANAGE_TOOL, // skill_manage — list/delete scoped skills, release/restore platform skills
         SESSION_SAVE_LEDGER_TOOL, // session_save_ledger — append immutable session log
         SESSION_SAVE_HANDOFF_TOOL, // session_save_handoff — upsert latest project state (now with OCC)
         SESSION_LOAD_CONTEXT_TOOL, // session_load_context — explicit project reload / legacy fallback
@@ -750,6 +753,12 @@ export function createServer() {
                         contextLoadedByClient = true; // v5.2.1: suppress deferred auto-push
                         result = await sessionLoadContextHandler(args);
                         break;
+                    case "skill_save":
+                        result = await skillSaveHandler(args);
+                        break;
+                    case "skill_manage":
+                        result = await skillManageHandler(args);
+                        break;
                     case "session_bootstrap":
                         if (!SESSION_MEMORY_ENABLED)
                             throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");

package/dist/skillManifestSync.js

@@ -1,12 +1,23 @@
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { access, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import { access, lstat, mkdtemp, open, readFile, readdir, readlink, realpath, rename, rm, writeFile, } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { applyManagedSkillManifest, getSetting, refreshConfigStorageCache, } from "./storage/configStorage.js";
+import { applyManagedSkillManifest, getSetting, refreshConfigStorageCache, setSetting, } from "./storage/configStorage.js";
 import { materializeAgentDefinitions, renderClaudeAgent, renderCodexAgent, renderGeminiAgent, resolveClaudeAgentsDir, resolveCodexAgentsDir, resolveGeminiAgentsDir, validateAgentSection, } from "./agentManifestSync.js";
 import { FREE_NATIVE_SKILL_NAMES, REQUIRED_NATIVE_SKILL_NAMES } from "./tools/skillRouting.js";
 import { getSynaluxJwt, invalidateSynaluxJwt } from "./utils/synaluxJwt.js";
+import { mkdirUsable, repairOwnerAccess } from "./utils/usableDirectory.js";
+/**
+ * Generation whose files actually reached disk, as opposed to the generation
+ * the config DB accepted. They diverge exactly when materialization fails, and
+ * that divergence is what made the 2026-08-10 outage invisible: the DB half
+ * commits first (deliberately -- committed names are what let a crashed run
+ * prune obsolete skills offline on restart), so the client reported the new
+ * generation while every managed root stayed frozen for nine days. Only a
+ * completed materialization advances this key.
+ */
+export const MATERIALIZED_GENERATION_KEY = "skill_manifest:materialized_generation";
 const OWNER = "prism-skill-sync-v1";
 const MARKER = ".prism-managed.json";
 const INDEX = ".prism-managed-skills.json";
@@ -279,13 +290,13 @@ async function matchesIncomingSkill(path, skill) {
 }
 async function stageSkill(root, skill, generation) {
     const target = join(root, skill.name);
-    await mkdir(target, { recursive: true, mode: 0o700 });
+    await mkdirUsable(target);
     const digests = Object.create(null);
     for (const [file, encoded] of Object.entries(skill.files)) {
         const path = resolve(target, file);
         if (!path.startsWith(`${target}${sep}`))
             throw new Error(`unsafe resolved path: ${file}`);
-        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        await mkdirUsable(dirname(path));
         await writeFile(path, decodeFile(encoded), { mode: 0o600 });
         digests[file] = encoded.digest;
     }
@@ -295,10 +306,23 @@ async function stageSkill(root, skill, generation) {
 }
 async function ensureRealDirectory(path) {
     if (!(await exists(path)))
-        await mkdir(path, { recursive: true, mode: 0o700 });
+        await mkdirUsable(path);
     const stat = await lstat(path);
     if (!stat.isDirectory() || stat.isSymbolicLink())
         throw new Error(`managed path must be a real directory: ${path}`);
+    // Existing-but-unusable is the failure this repairs. mkdir's mode is masked
+    // by the creating process's umask, so a umask carrying the owner-execute bit
+    // (0o100) yields drw------- — a directory nothing can enter. Every later
+    // mkdtemp then throws EACCES, materialization aborts, and the run reports
+    // "partial" to stderr the host does not surface.
+    //
+    // Measured 2026-08-10: this exact directory sat at 0o600 for NINE days.
+    // The config DB half of each sync committed the new generation and digests
+    // while the file half never ran, so the client reported itself current while
+    // every managed skill root stayed frozen at its 2026-08-01 content. Checking
+    // "is a real directory" without checking "can I use it" made the outage
+    // permanent — nothing in the loop ever repaired the mode.
+    await repairOwnerAccess(path, stat.mode);
 }
 async function removeExpiredTransactions(base) {
     const cutoff = Date.now() - TRANSACTION_RETENTION_MS;
@@ -517,10 +541,12 @@ async function readCommittedManifestNames() {
     }
 }
 async function materializeNative(manifest, agentsSkillsDir, hooks) {
-    await mkdir(agentsSkillsDir, { recursive: true, mode: 0o700 });
+    await mkdirUsable(agentsSkillsDir);
     const rootStat = await lstat(agentsSkillsDir);
     if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
         throw new Error("native skills root must be a real directory");
+    // The readdir immediately below is the first thing an unusable root breaks.
+    await repairOwnerAccess(agentsSkillsDir, rootStat.mode);
     await quarantineLegacyDiscoveryArtifacts(agentsSkillsDir);
     // Transaction content must remain outside the native discovery root: some
     // hosts recursively scan it and would otherwise discover staged/pruned paid
@@ -529,6 +555,10 @@ async function materializeNative(manifest, agentsSkillsDir, hooks) {
     await ensureRealDirectory(transactionBase);
     await removeExpiredTransactions(transactionBase);
     const transactionRoot = await mkdtemp(join(transactionBase, "txn-"));
+    // mkdtemp is umask-masked too, and nothing else revisits this path. A
+    // persistent restrictive umask therefore produced a REPAIRED base holding a
+    // brand-new unusable txn-* directory -- the original outage one level deeper.
+    await repairOwnerAccess(transactionRoot, (await lstat(transactionRoot)).mode);
     const stageRoot = join(transactionRoot, "stage");
     const backupRoot = join(transactionRoot, "backup");
     await ensureRealDirectory(stageRoot);
@@ -771,10 +801,15 @@ async function fetchManifest(options) {
     return manifest;
 }
 async function acquireSyncLock(agentsSkillsDir, waitMs = LOCK_WAIT_MS) {
-    await mkdir(agentsSkillsDir, { recursive: true, mode: 0o700 });
+    await mkdirUsable(agentsSkillsDir);
     const rootStat = await lstat(agentsSkillsDir);
     if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
         throw new Error("native skills root must be a real directory");
+    // Same repair as ensureRealDirectory. This site takes the lock before any
+    // materialization, so a root that exists without owner rwx fails here first —
+    // mkdir no-ops on an existing directory and every open below throws EACCES,
+    // with nothing in the loop restoring the mode.
+    await repairOwnerAccess(agentsSkillsDir, rootStat.mode);
     const lockPath = join(agentsSkillsDir, ".prism-sync.lock");
     const deadline = Date.now() + Math.max(0, waitMs);
     const token = randomUUID();
@@ -936,6 +971,10 @@ export async function synchronizeSkillManifest(options = {}) {
             native.conflicts.push(...outcome.conflicts);
         }
         const status = native.installed.length || native.updated.length || native.pruned.length ? "applied" : "unchanged";
+        // Reached only when every native root materialized. A failure above throws
+        // past this point, leaving the previous value so the mismatch persists and
+        // stays visible until a sync genuinely succeeds.
+        await setSetting(MATERIALIZED_GENERATION_KEY, manifest.generation);
         return {
             status,
             tier: manifest.tier,

package/dist/storage/configStorage.js

@@ -1,7 +1,8 @@
 import { createClient } from "@libsql/client";
 import { resolve, dirname } from "path";
 import { homedir } from "os";
-import { existsSync, mkdirSync } from "fs";
+import { existsSync } from "fs";
+import { mkdirUsableSync } from "../utils/usableDirectory.js";
 const PROTO_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 // We use a small, dedicated DB just for configuration settings.
 // This solves the chicken-and-egg problem: we need to know WHICH
@@ -33,7 +34,10 @@ function getClient() {
         // and libSQL throws SQLITE_CANTOPEN (error 14) without it.
         const dir = dirname(CONFIG_PATH);
         if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
+            // Not plain mkdirSync: recursive creation is umask-masked at every level,
+            // and this directory holds the entitlement snapshot, so it must be private
+            // and enterable regardless of the umask Prism happens to inherit.
+            mkdirUsableSync(dir);
         }
         configClient = createClient({
             url: `file:${CONFIG_PATH}`,

package/dist/tools/ledgerHandlers.js

@@ -31,6 +31,7 @@ import { toKeywordArray } from "../utils/keywordExtractor.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
 import { getCurrentGitState, getGitDrift } from "../utils/git.js";
 import { getSetting, setSetting, getAllSettings, refreshConfigStorageCache } from "../storage/configStorage.js";
+import { MATERIALIZED_GENERATION_KEY } from "../skillManifestSync.js";
 import { mergeHandoff, dbToHandoffSchema, sanitizeForMerge } from "../utils/crdtMerge.js";
 import { resolveProject } from "../utils/projectResolver.js";
 import { isRecoverableStartupStorageError, LOCAL_STARTUP_FALLBACK_NOTICE, } from "../utils/startupRecovery.js";
@@ -205,10 +206,34 @@ function parseNativeSkillNames(value) {
 }
 async function resolveNativeSkillManifestSnapshot(syncResult) {
     const { FREE_NATIVE_SKILL_NAMES, REQUIRED_NATIVE_SKILL_NAMES } = await import("./skillRouting.js");
-    const [storedNamesValue, storedTierValue] = await Promise.all([
+    const [storedNamesValue, storedTierValue, committedGeneration, materializedGeneration] = await Promise.all([
         getSetting("skill_manifest:names", "[]"),
         getSetting("skill_manifest:tier", ""),
+        getSetting("skill_manifest:generation", ""),
+        // The exported constant, not a copied literal: a key rename on either
+        // side would otherwise leave this read returning "" forever -- warning
+        // permanently silent -- with both sides' tests still green, because each
+        // asserts against its own copy of the string.
+        getSetting(MATERIALIZED_GENERATION_KEY, ""),
     ]);
+    // The DB half of a sync commits before files are written, by design: the
+    // committed names are what let a crashed run prune obsolete skills offline on
+    // restart. The cost is that this snapshot can describe an entitlement whose
+    // files never landed. A DIVERGENCE here is that exact state, and it persists
+    // across sessions -- a later sync reports "unchanged" because nothing needed
+    // writing, while the roots agents actually read stay frozen. Unreported, it
+    // ran for nine days on 2026-08-10.
+    // An EMPTY marker is "never recorded", not "never delivered": every install
+    // that predates the marker has a committed generation and no marker at all,
+    // and an offline user's failed fetch must not scream STALE at them on
+    // upgrade day. A false alarm here trains people to ignore the line, which is
+    // how the real one gets waved through. The fresh-install failure case is
+    // still covered -- that run's own syncStatus is "partial" and the
+    // validated-partial branch already reports materialization incomplete.
+    const undeliveredGeneration = Boolean(committedGeneration) && Boolean(materializedGeneration) &&
+        committedGeneration !== materializedGeneration
+        ? committedGeneration
+        : "";
     const partialNamesInput = syncResult.status === "partial" && Array.isArray(syncResult.entitledNames)
         ? syncResult.entitledNames
         : null;
@@ -245,6 +270,7 @@ async function resolveNativeSkillManifestSnapshot(syncResult) {
         tier,
         source,
         syncStatus: syncResult.status,
+        undeliveredGeneration,
         conflicts: [...new Set(syncResult.conflicts)],
     };
 }
@@ -293,8 +319,24 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
             `directory out of the native skills folder and rerun \`prism connect\` ` +
             `(or a session bootstrap) to reinstall the managed copy.`
         : "";
+    // Durable, not per-run: a later sync reports "unchanged" while the roots stay
+    // frozen from an earlier failed materialization. This line is the difference
+    // between that outage being visible on the next startup and it running for
+    // nine days.
+    //
+    // Rendered directly UNDER the header, never appended at the tail:
+    // capNativeStartupText keeps the head and cuts the tail, so a tail-placed
+    // warning is the first thing truncated at capped depths -- observed live in
+    // the divergence simulation (STALE was line 19 of 20). The most important
+    // line goes where truncation cannot reach it.
+    const undeliveredWarning = snapshot.undeliveredGeneration
+        ? `\n> - ⚠️ **Skill files are STALE:** the entitlement DB is at generation ` +
+            `\`${snapshot.undeliveredGeneration.slice(0, 12)}…\` but its files never finished ` +
+            `reaching the skill roots. Agents are reading older skills. Run a sync ` +
+            `(restart the host or \`prism connect\`) and report this if it persists.`
+        : "";
     if (snapshot.source === "validated-partial") {
-        return `> **Prism System Ready**\n>\n` +
+        return `> **Prism System Ready**\n>` + undeliveredWarning + `\n` +
             `> - 🪪 **Subscription tier:** ${snapshot.tier}\n` +
             `> - 📦 **Entitled skills (materialization incomplete):** ${snapshot.names.length}\n` +
             `> - 📚 **Core/protected entitlements:** ${formatBoundedSkillNames(coreSkills, "entitled")}\n` +
@@ -306,7 +348,7 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
             freeTierUpgradeLine(snapshot.tier);
     }
     if (snapshot.source === "tier-fallback") {
-        return `> **Prism System Ready**\n>\n` +
+        return `> **Prism System Ready**\n>` + undeliveredWarning + `\n` +
             `> - 🪪 **Subscription tier:** ${snapshot.tier}\n` +
             `> - 🛡️ **Fallback skill names:** ${formatBoundedSkillNames(snapshot.names, "fallback")}\n` +
             `> - 🧠 **Context depth:** ${depth}\n` +
@@ -314,7 +356,7 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
             conflictWarning +
             freeTierUpgradeLine(snapshot.tier);
     }
-    return `> **Prism System Ready**\n>\n` +
+    return `> **Prism System Ready**\n>` + undeliveredWarning + `\n` +
         `> - 🪪 **Subscription tier:** ${snapshot.tier}\n` +
         `> - 📦 **Provisioned skills:** ${snapshot.names.length}\n` +
         `> - 📚 **Core/protected skills provisioned:** ${formatBoundedSkillNames(coreSkills, "provisioned")}\n` +

package/dist/tools/skillScopeHandlers.js

@@ -0,0 +1,288 @@
+/**
+ * skill_save / skill_manage — scoped skill management.
+ *
+ * A skill can live at three scopes:
+ *   local — a plain file on this machine only (works signed-out; local-first)
+ *   user  — the signed-in account; follows the user to every machine
+ *   team  — a workspace; delivered to its members (admins may target a subset)
+ *
+ * Classification policy: an explicit scope always wins. Signed in without a
+ * scope → `user` (private, reversible; the result says so and how to share).
+ * Signed out → `local`. `team` is never a default: writing to shared state is
+ * an explicit act, and the server enforces the owner/admin role.
+ *
+ * skill_manage covers the recall paths: `release` excludes a PLATFORM skill
+ * from your (or your team's) delivery to free host catalog budget — fully
+ * reversible with `restore` because platform content never leaves the bundle.
+ * `delete` removes a scoped skill everywhere; because the stored row IS the
+ * content, the handler archives the final content locally before anything is
+ * discarded.
+ */
+import { readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getSetting } from "../storage/configStorage.js";
+import { getSynaluxJwt } from "../utils/synaluxJwt.js";
+import { triggerSkillManifestSync } from "../skillManifestSync.js";
+import { mkdirUsable } from "../utils/usableDirectory.js";
+const STRICT_SKILL_NAME = /^[a-z0-9][a-z0-9_-]{0,127}$/;
+// Mirrors the platform's context-fit bar so a save refused by the server is
+// refused here first, with the same explanation.
+const MAX_CONTENT_BYTES = 25_000;
+const MAX_DESCRIPTION_CHARS = 500;
+const API_PATH = "/api/v1/prism/user-skills";
+function text(message, extra, isError = false) {
+    return { content: [{ type: "text", text: message }], ...(isError ? { isError } : {}), ...(extra ? { structuredContent: extra } : {}) };
+}
+async function synaluxBaseUrl() {
+    const configured = process.env.PRISM_SYNALUX_BASE_URL?.trim() || process.env.SYNALUX_BASE_URL?.trim() ||
+        (await getSetting("PRISM_SYNALUX_BASE_URL", "")).trim() || (await getSetting("SYNALUX_BASE_URL", "")).trim() ||
+        "https://synalux.ai";
+    if (!/^https?:\/\//i.test(configured))
+        throw new Error("invalid Synalux base URL");
+    return configured.replace(/\/+$/, "");
+}
+function frontmatterProblems(name, content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+    if (!match)
+        return "content must open with YAML frontmatter (---) carrying name and description";
+    const fields = {};
+    for (const line of match[1].split("\n")) {
+        const field = line.match(/^([A-Za-z_-]+):\s*(.*)$/);
+        if (!field)
+            continue;
+        const raw = field[2].trim();
+        const quoted = raw.match(/^"(.*)"$/) ?? raw.match(/^'(.*)'$/);
+        fields[field[1]] = quoted ? quoted[1] : raw;
+    }
+    if (fields.name !== name)
+        return "frontmatter name must match the skill name";
+    if (!fields.description)
+        return "frontmatter must carry a non-empty description";
+    if (fields.description.length > MAX_DESCRIPTION_CHARS) {
+        return `frontmatter description exceeds ${MAX_DESCRIPTION_CHARS} chars (hosts budget catalog space by description length)`;
+    }
+    return null;
+}
+function validateSkillInput(name, content) {
+    if (typeof name !== "string" || !STRICT_SKILL_NAME.test(name)) {
+        return "invalid skill name: lowercase letters, digits, - and _ only (max 128 chars)";
+    }
+    if (typeof content !== "string" || !content.trim())
+        return "content is required";
+    if (Buffer.byteLength(content, "utf8") > MAX_CONTENT_BYTES) {
+        return `content exceeds the ${MAX_CONTENT_BYTES}-byte context-fit limit shared by every delivered skill; move reference material out or split it`;
+    }
+    return frontmatterProblems(name, content);
+}
+/** Local skill roots that hosts read natively. Never Prism-managed dirs. */
+function localSkillRoots() {
+    return [join(homedir(), ".agents", "skills"), join(homedir(), ".claude", "skills")];
+}
+function archiveDir() {
+    return join(homedir(), ".prism-mcp", "skill-archive");
+}
+async function archiveContent(name, content) {
+    const dir = archiveDir();
+    await mkdirUsable(dir);
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const path = join(dir, `${name}-${stamp}.md`);
+    await writeFile(path, content, { mode: 0o600 });
+    return path;
+}
+async function saveLocal(name, content) {
+    const written = [];
+    for (const root of localSkillRoots()) {
+        const dir = join(root, name);
+        await mkdirUsable(dir);
+        await writeFile(join(dir, "SKILL.md"), content, { mode: 0o600 });
+        written.push(dir);
+    }
+    return text(`Saved LOCALLY (this machine only): ${written.join(", ")}. ` +
+        `Not uploaded anywhere. Sign in and re-save with scope "user" to make it follow your account, ` +
+        `or scope "team" (workspace admins) to share it.`, { scope: "local", name, paths: written });
+}
+async function apiAuth() {
+    const jwt = await getSynaluxJwt().catch(() => null);
+    if (!jwt)
+        return null;
+    return { baseUrl: await synaluxBaseUrl(), jwt };
+}
+async function callApi(auth, method, body, query = "") {
+    const response = await fetch(`${auth.baseUrl}${API_PATH}${query}`, {
+        method,
+        headers: { Authorization: `Bearer ${auth.jwt}`, "Content-Type": "application/json" },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    let parsed = {};
+    try {
+        parsed = await response.json();
+    }
+    catch { /* non-JSON error body */ }
+    return { status: response.status, body: parsed };
+}
+/**
+ * A sync started BEFORE the save cannot contain it; joining one would report
+ * success while delivering nothing. Trigger has no TTL cache (single-flight
+ * only), so run-then-verify: if the saved name did not arrive, run once more —
+ * the second call cannot join a pre-save run because the first one completed.
+ */
+async function syncUntilDelivered(name) {
+    const first = await triggerSkillManifestSync().catch(error => ({ status: "failed", installed: [], updated: [], pruned: [], conflicts: [], error: String(error) }));
+    const delivered = (result) => result.installed.includes(name) || result.updated.includes(name);
+    if (first.status !== "failed" && delivered(first))
+        return "delivered to this machine now; other machines receive it at their next sync";
+    const second = await triggerSkillManifestSync().catch(() => null);
+    if (second && second.status !== "failed" && delivered(second))
+        return "delivered to this machine now; other machines receive it at their next sync";
+    if (second && (second.status === "unchanged" || second.status === "applied")) {
+        return "saved server-side; local delivery reported no change (it may already be current) — verify with your host's skill list";
+    }
+    return "saved server-side; local sync did not complete — it will arrive on the next successful sync";
+}
+export const SKILL_SAVE_TOOL = {
+    name: "skill_save",
+    description: "Save a skill at one of three scopes: local (this machine only, works signed out), " +
+        "user (your account — follows you to every machine), or team (a workspace — delivered to its members; " +
+        "owner/admin only, optionally targeted with assign_to). Default when signed in is USER; team is never " +
+        "a default. Content must be a SKILL.md body with frontmatter (name, description).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: { type: "string", description: "Skill name (lowercase letters, digits, - and _)" },
+            content: { type: "string", description: "Full SKILL.md content including frontmatter" },
+            scope: { type: "string", enum: ["local", "user", "team"], description: "Where the skill lives. Omit to default: user when signed in, local otherwise." },
+            workspace_id: { type: "string", description: "Required for team scope" },
+            assign_to: { type: "array", items: { type: "string" }, description: "Team scope only (admin): deliver ONLY to these member user ids; omit for all members" },
+        },
+        required: ["name", "content"],
+    },
+};
+export async function skillSaveHandler(args) {
+    const { name, content, scope, workspace_id: workspaceId, assign_to: assignTo } = args;
+    const problem = validateSkillInput(name, content);
+    if (problem)
+        return text(`Not saved: ${problem}`, undefined, true);
+    const skillName = name;
+    const skillContent = content;
+    if (scope !== undefined && scope !== "local" && scope !== "user" && scope !== "team") {
+        return text("Not saved: scope must be local, user, or team", undefined, true);
+    }
+    if (scope === "local")
+        return saveLocal(skillName, skillContent);
+    const auth = await apiAuth();
+    if (!auth) {
+        if (scope === "user" || scope === "team") {
+            return text("Not saved: this scope needs a signed-in Synalux account, and no credential is configured. Save with scope \"local\" to keep it on this machine.", undefined, true);
+        }
+        return saveLocal(skillName, skillContent);
+    }
+    const effectiveScope = scope ?? "user";
+    if (effectiveScope === "team" && (typeof workspaceId !== "string" || !workspaceId)) {
+        return text("Not saved: team scope requires workspace_id", undefined, true);
+    }
+    const { status, body } = await callApi(auth, "PUT", {
+        scope: effectiveScope,
+        ...(effectiveScope === "team" ? { workspace_id: workspaceId } : {}),
+        ...(assignTo !== undefined ? { assign_to: assignTo } : {}),
+        name: skillName,
+        content: skillContent,
+    });
+    if (status !== 200) {
+        return text(`Not saved (server ${status}): ${String(body.error ?? "unknown error")}`, undefined, true);
+    }
+    const delivery = await syncUntilDelivered(skillName);
+    const where = effectiveScope === "user"
+        ? `saved as YOUR account skill (version ${String(body.version)}) — say "make it a team skill" to share it with a workspace`
+        : `saved as a TEAM skill for workspace ${String(workspaceId)} (version ${String(body.version)})${Array.isArray(assignTo) && assignTo.length > 0 ? `, targeted to ${assignTo.length} member(s)` : ", delivered to all members"}`;
+    return text(`${where}. Delivery: ${delivery}.`, { scope: effectiveScope, name: skillName, version: body.version });
+}
+export const SKILL_MANAGE_TOOL = {
+    name: "skill_manage",
+    description: "Manage scoped skills and platform-skill activation. Actions: list (your skills, team skills, releases); " +
+        "delete (remove a user/team/local skill — the final content is archived locally first); " +
+        "release (deactivate a PLATFORM skill you never use, freeing host catalog budget — per user, or per team by admins); " +
+        "restore (re-activate a released platform skill; lossless).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: { type: "string", enum: ["list", "delete", "release", "restore"] },
+            name: { type: "string", description: "Skill name (all actions except list)" },
+            scope: { type: "string", enum: ["local", "user", "team"], description: "delete: where the skill lives; release/restore: user (yourself) or team (admin)" },
+            workspace_id: { type: "string", description: "Required for team scope" },
+        },
+        required: ["action"],
+    },
+};
+export async function skillManageHandler(args) {
+    const { action, name, scope, workspace_id: workspaceId } = args;
+    if (action === "list") {
+        const localEntries = [];
+        for (const root of localSkillRoots()) {
+            const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+            for (const entry of entries) {
+                if (entry.isDirectory() && !entry.name.startsWith("."))
+                    localEntries.push(`${entry.name} (${root})`);
+            }
+        }
+        const auth = await apiAuth();
+        if (!auth) {
+            return text(`Signed out — local skill directories only:\n${localEntries.join("\n") || "(none)"}`, { local: localEntries });
+        }
+        const { status, body } = await callApi(auth, "GET");
+        if (status !== 200)
+            return text(`Listing failed (server ${status}): ${String(body.error ?? "unknown")}`, undefined, true);
+        return text(`Account skills: ${JSON.stringify(body.user_skills)}\nTeam skills: ${JSON.stringify(body.team_skills)}\nReleased platform skills: ${JSON.stringify(body.released)}\nLocal-only dirs: ${localEntries.length}`, { ...body, local: localEntries });
+    }
+    if (typeof name !== "string" || !STRICT_SKILL_NAME.test(name)) {
+        return text("Invalid skill name", undefined, true);
+    }
+    if (action === "delete") {
+        if (scope === "local") {
+            const archived = [];
+            for (const root of localSkillRoots()) {
+                const path = join(root, name, "SKILL.md");
+                const body = await readFile(path, "utf8").catch(() => null);
+                if (body !== null) {
+                    archived.push(await archiveContent(name, body));
+                    await rm(join(root, name), { recursive: true, force: true });
+                }
+            }
+            if (archived.length === 0)
+                return text(`No local skill named ${name} found`, undefined, true);
+            return text(`Deleted local skill ${name}. Final content archived at: ${archived[0]} — re-save from there to recall it.`, { archived });
+        }
+        const auth = await apiAuth();
+        if (!auth)
+            return text("Deleting account/team skills needs a signed-in Synalux account", undefined, true);
+        const query = `?name=${encodeURIComponent(name)}&scope=${scope === "team" ? "team" : "user"}` +
+            (scope === "team" && typeof workspaceId === "string" ? `&workspace_id=${encodeURIComponent(workspaceId)}` : "");
+        const { status, body } = await callApi(auth, "DELETE", undefined, query);
+        if (status !== 200)
+            return text(`Not deleted (server ${status}): ${String(body.error ?? "unknown")}`, undefined, true);
+        const deleted = body.deleted;
+        let archivedAt = "server returned no content";
+        if (deleted?.content)
+            archivedAt = await archiveContent(name, deleted.content);
+        await triggerSkillManifestSync().catch(() => null); // prune from this machine
+        return text(`Deleted ${scope === "team" ? "team" : "account"} skill ${name}; it prunes from every machine at next sync. Final content archived at: ${archivedAt} — re-save from there to recall it.`, { archived: archivedAt });
+    }
+    if (action === "release" || action === "restore") {
+        const auth = await apiAuth();
+        if (!auth)
+            return text("Releasing platform skills needs a signed-in Synalux account (local installs are managed by deleting the local copy)", undefined, true);
+        const { status, body } = await callApi(auth, "PATCH", {
+            action,
+            scope: scope === "team" ? "team" : "user",
+            ...(scope === "team" ? { workspace_id: workspaceId } : {}),
+            name,
+        });
+        if (status !== 200)
+            return text(`${action} failed (server ${status}): ${String(body.error ?? "unknown")}`, undefined, true);
+        await triggerSkillManifestSync().catch(() => null);
+        return text(action === "release"
+            ? `Released ${name}: it leaves your delivered set and prunes from your machines at next sync, freeing host catalog budget. Fully reversible with action "restore".`
+            : `Restored ${name}: it returns with your next sync on every machine.`, { action, name });
+    }
+    return text("action must be list, delete, release, or restore", undefined, true);
+}

package/dist/utils/usableDirectory.js

@@ -0,0 +1,150 @@
+/**
+ * Directory creation and repair that a restrictive umask cannot defeat.
+ *
+ * WHY THIS EXISTS (2026-08-10)
+ * Skill delivery died silently for nine days. `.prism-skill-transactions` had
+ * been created with `mkdir(..., { mode: 0o700 })`, but mkdir's mode is masked by
+ * the process umask: a umask carrying the owner-execute bit yields drw-------,
+ * a directory that can be read and written but never entered. Every subsequent
+ * mkdtemp threw EACCES, materialization aborted, and — because the config DB
+ * half of a sync commits before the file half — the client went on reporting the
+ * new generation while every managed skill root stayed frozen at older content.
+ *
+ * The first fix repaired a directory that was already broken and left the cause
+ * alone: a umask that is still restrictive masks every directory created after
+ * it, so a repaired base simply gained a brand-new unusable child. Node exposes
+ * no per-call umask, so the only portable defeat is to create one level at a
+ * time and repair what we just made.
+ *
+ * These helpers are shared rather than duplicated because the same trap exists
+ * anywhere Prism creates a private directory — skill roots, agent roots, and the
+ * config DB's parent — and a guard applied at two of three sites is not a guard.
+ */
+import { constants as fsConstants, chmodSync, lstatSync, mkdirSync } from "node:fs";
+import { chmod, lstat, mkdir, open } from "node:fs/promises";
+import { isAbsolute, sep } from "node:path";
+/** Mode every Prism-managed directory is created with and repaired to. */
+export const MANAGED_DIR_MODE = 0o700;
+function isErrno(error, code) {
+    return typeof error === "object" && error !== null && "code" in error
+        && error.code === code;
+}
+/**
+ * Restore owner rwx on a managed directory that exists but cannot be entered.
+ *
+ * Restores 0o700 EXACTLY rather than OR-ing owner bits onto whatever is there.
+ * These directories hold entitled skill content and pre-rollback backups;
+ * repairing 0o066 to 0o766 would "fix" an outage by leaving them world-readable.
+ *
+ * Prism-managed directories REQUIRE owner rwx, so a deliberate sharing mode that
+ * withholds it — 0o670, say — is discarded rather than preserved. Conventional
+ * sharing is unaffected: this only fires on a directory the owner cannot use,
+ * which is broken by any definition. A 0o770 directory is left untouched.
+ *
+ * Applies the change through an open descriptor, not the pathname. A pathname
+ * chmod re-resolves the path, so a process able to swap the directory for a
+ * symlink between the check and the change could redirect the permission change
+ * somewhere else entirely. fchmod acts on the object already opened.
+ *
+ * POSIX only. On Windows chmod maps to the read-only attribute alone and lstat
+ * reports 0o666 for every writable directory, so the condition can never be
+ * satisfied and the failure being repaired has no analogue there.
+ */
+export async function repairOwnerAccess(path, mode) {
+    if (process.platform === "win32")
+        return;
+    if ((mode & MANAGED_DIR_MODE) === MANAGED_DIR_MODE)
+        return;
+    let handle;
+    try {
+        // O_NOFOLLOW: a symlink at this path must fail the open rather than hand us
+        // a descriptor to whatever it points at.
+        handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    }
+    catch {
+        // Opening a directory needs owner-read, so the very modes this exists to
+        // repair (0o000, 0o300) land here — as does any symlink, via O_NOFOLLOW.
+        // An unguarded pathname chmod at this point re-opens the symlink hole: a
+        // link to an UNREADABLE file skipped the descriptor path entirely and got
+        // its target chmodded to 0o700. Proven with a live attack against the
+        // built helper during review, not hypothesized. lstat separates the two
+        // cases; the remaining lstat→chmod race is confined to unreadable real
+        // directories inside the user's own home.
+        const entry = await lstat(path);
+        if (!entry.isDirectory() || entry.isSymbolicLink()) {
+            throw new Error(`managed path is not a directory: ${path}`);
+        }
+        await chmod(path, MANAGED_DIR_MODE);
+        return;
+    }
+    try {
+        const opened = await handle.stat();
+        if (!opened.isDirectory())
+            throw new Error(`managed path is not a directory: ${path}`);
+        await handle.chmod(MANAGED_DIR_MODE);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Create a directory, and any missing ancestors, that the owner can enter.
+ *
+ * `recursive: true` applies the same masked mode to every level it creates, so
+ * under a hostile umask the first new ancestor is already untraversable and the
+ * call fails partway with EACCES before anything can repair it.
+ *
+ * Repairs ONLY directories this call creates. A pre-existing ancestor — $HOME
+ * and everything above it — keeps exactly the mode the user configured; silently
+ * widening those would be a worse bug than the one being fixed.
+ */
+export async function mkdirUsable(target) {
+    if (process.platform === "win32") {
+        await mkdir(target, { recursive: true, mode: MANAGED_DIR_MODE });
+        return;
+    }
+    const segments = target.split(sep).filter(Boolean);
+    let current = isAbsolute(target) ? "" : ".";
+    for (const segment of segments) {
+        current = current === "" ? `${sep}${segment}` : `${current}${sep}${segment}`;
+        try {
+            await mkdir(current, { mode: MANAGED_DIR_MODE });
+        }
+        catch (error) {
+            if (isErrno(error, "EEXIST"))
+                continue; // not ours — do not touch its mode
+            throw error;
+        }
+        await repairOwnerAccess(current, (await lstat(current)).mode);
+    }
+}
+/**
+ * Synchronous twin of {@link mkdirUsable}, for callers on a sync path.
+ *
+ * The config DB's parent is created before any await is possible, and it holds
+ * the entitlement snapshot, so it needs the same umask defeat and the same
+ * private mode. Kept beside the async version deliberately: two implementations
+ * of this rule in different files is how one of them ends up wrong.
+ */
+export function mkdirUsableSync(target) {
+    if (process.platform === "win32") {
+        mkdirSync(target, { recursive: true, mode: MANAGED_DIR_MODE });
+        return;
+    }
+    const segments = target.split(sep).filter(Boolean);
+    let current = isAbsolute(target) ? "" : ".";
+    for (const segment of segments) {
+        current = current === "" ? `${sep}${segment}` : `${current}${sep}${segment}`;
+        try {
+            mkdirSync(current, { mode: MANAGED_DIR_MODE });
+        }
+        catch (error) {
+            if (isErrno(error, "EEXIST"))
+                continue; // not ours — do not touch its mode
+            throw error;
+        }
+        if ((lstatSync(current).mode & MANAGED_DIR_MODE) !== MANAGED_DIR_MODE) {
+            chmodSync(current, MANAGED_DIR_MODE);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.8.1",
+  "version": "20.9.0",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Persistent session memory for AI coding agents that never leaves your machine \u2014 including the on-device model that reasons over it. Restores your prior decisions, open TODOs, and changed files across sessions; adds associative recall of related past work, semantic drift detection, and local inference. Local-first by default. Works with Claude Code, Cursor, and Codex.",
   "module": "index.ts",
@@ -82,7 +82,8 @@
     "ip-address": "^10.2.0",
     "protobufjs": "^7.6.5",
     "sharp": "^0.35.0",
-    "tar": "^7.5.19"
+    "tar": "^7.5.19",
+    "nanoid": "^3.3.17"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.92.0",