studiograph 1.3.48-next.21 → 1.3.48-next.210

package/dist/mcp/tools.js

@@ -5,11 +5,82 @@
  * methods — no new business logic. Results are returned as JSON text so the
  * MCP client (Claude Desktop) can process structured data.
  *
+ * Every tool enforces per-user access control via `services/access-control.ts`.
+ * Callers (the HTTP /mcp route, the stdio MCP server) must resolve a user
+ * identity before registering tools — `registerTools` requires a user in its
+ * `McpAccessContext` argument so there is no anonymous MCP path.
+ *
  * Note: `inputSchema` is cast to `any` at each call site because the MCP SDK's
  * ZodRawShapeCompat type does not accept ZodObject in TypeScript's strict mode.
  * Runtime schema validation is handled correctly by the SDK regardless.
  */
 import { z } from 'zod';
+import { ENTITY_SCHEMAS } from '../core/validation.js';
+import { getAccessibleRepos, hasRepoAccess, canWriteRepo, getAccessibleEntityIds, filterWikilinks, } from '../services/access-control.js';
+import { createSharedFolder, FolderCreationError } from '../services/folder-creation.js';
+import { validateFolderPath } from '../core/folder-paths.js';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { isCuratedEntityType } from '../core/entity-types-catalog.js';
+import { getAgentAllowedEntityTypes } from '../agent/prompts/entity-types-section.js';
+import * as commentVirtualEntity from '../services/comment-virtual-entity.js';
+import { buildActor, prepareCreatePayload, prepareUpdatePayload, diagnosedUpdate, DroppedAssetError, assertEntityRefs, } from '../services/entity-mutations.js';
+import { BridgeError, validateUserHandleInPayload, assertCanChangeUserHandle } from '../services/user-person-bridge.js';
+import { extractAssetEmbeds, stripFrontmatter, assetEmbed } from '../core/embeds.js';
+import { listRepoAssets } from '../services/asset-listing.js';
+import { presignAssetUpload } from '../services/asset-presign-service.js';
+import { finalizeAssetUpload } from '../services/asset-finalize-service.js';
+import { importAssetAsEntity } from '../services/asset-import-service.js';
+import { AssetUploadError } from '../services/asset-upload-errors.js';
+import { presignMimeAllowlist, inlineUploadMimeAllowlist, resolveFormat, isInlineUploadAllowed } from '../core/format-registry.js';
+import { resolveWorkspaceAssetsRepo } from '../services/workspace-assets-folder.js';
+import { Workspace } from '../core/workspace.js';
+import { validateArtifactBundle } from '../core/artifact-bundle.js';
+import { artifactExportFilename, buildArtifactHtmlExport } from '../core/artifact-export.js';
+import { ArtifactRenderExportUnavailableError, artifactPngArchiveFilename, inspectArtifactRender, nameArtifactPngFiles, renderArtifactPdf, renderArtifactPngFiles, zipArtifactPngFiles, } from '../services/artifact-render-export.js';
+import { artifactLibrarySourcesForBundle } from '../services/artifact-library-sources.js';
+/**
+ * Server identity passed to `new McpServer(...)` on BOTH transports (stdio
+ * `src/mcp/server.ts` + HTTP `src/server/routes/mcp.ts`). Centralized so the
+ * two surfaces can never drift on name/version.
+ */
+export const MCP_SERVER_INFO = { name: 'studiograph', version: '1.0.0' };
+/**
+ * Server-level `instructions` (MCP `ServerOptions.instructions`, surfaced in
+ * the `initialize` response). With Claude Code's tool-search/deferral on, this
+ * is what tells the client WHEN to search for Studiograph's tools — it loads
+ * even when individual tool schemas are deferred. Must be passed in McpServer's
+ * SECOND constructor arg (`new McpServer(MCP_SERVER_INFO, { instructions })`) —
+ * putting it in the serverInfo object silently drops it.
+ *
+ * Budget: Claude Code truncates server instructions at 2KB and front-loads
+ * matter most — keep this short and lead with category + when-to-reach-for-it.
+ */
+export const MCP_INSTRUCTIONS = 'Studiograph is the team\'s knowledge workspace: a Git-backed graph of entries ' +
+    '(people, organizations, projects, tasks, deals, events, notes, documents, ' +
+    'deliverables, skills, and uploaded assets) stored as markdown with YAML ' +
+    'frontmatter and connected by [[wikilinks]].\n\n' +
+    'Reach for these tools whenever the user wants to CAPTURE, FIND, READ, or ' +
+    'UPDATE workspace knowledge — search before concluding something is unavailable. ' +
+    'Common entry points:\n' +
+    '- Find / read: search_entities, list_entities, get_entity, find_related\n' +
+    '- Create / edit: create_entity, update_entity, patch_entity (small edits)\n' +
+    '- Organize: list_repos, create_repo, create_subfolder, move_entity\n' +
+    '- Assets (images/files): list_assets, attach_asset_to_entity, upload_asset_inline\n' +
+    '- Artifacts: create_artifact, inspect_artifact, export_artifact\n' +
+    '- History / undo: list_file_history, list_recent_deletions, restore_file\n' +
+    '- Saved workflows: list_skills, get_skill';
+/**
+ * Tools pinned against Claude Code's tool-search deferral via
+ * `_meta["anthropic/alwaysLoad"]=true` (see PIN_META). These are the handful an
+ * agent needs on essentially every turn, so they stay loaded even when the rest
+ * of the surface is deferred (verified: code.claude.com/docs/en/mcp.md, CC
+ * v2.1.121+). Keep this set SMALL — each pinned tool consumes upfront context.
+ * Exported so tests can assert the pin lands on exactly these tools.
+ */
+export const MCP_PINNED_TOOLS = ['search_entities', 'list_entities', 'get_entity', 'create_entity'];
+const PINNED_SET = new Set(MCP_PINNED_TOOLS);
+const PIN_META = { _meta: { 'anthropic/alwaysLoad': true } };
 // ── helpers ───────────────────────────────────────────────────────────────────
 function ok(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
@@ -18,30 +89,277 @@ function fail(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: [{ type: 'text', text: msg }], isError: true };
 }
-// Strip frontmatter fields that duplicate the top-level id/type keys
+/** Deny-without-leaking helper — same wording as a missing repo/entity. */
+function notFound(repo) {
+    return fail(new Error(`Folder "${repo}" not found`));
+}
+/**
+ * Map an AssetUploadError (or any Error with a stable `code` discriminator)
+ * onto the MCP `fail()` envelope, embedding the code so the client can
+ * branch programmatically. Wraps `fail()` rather than replacing it so any
+ * non-typed error falls through to the existing "unknown" path.
+ *
+ * The code makes its way into the text payload as a JSON object — MCP
+ * clients that parse the text get a structured shape; pure-text consumers
+ * still get a readable line.
+ */
+function errorToMcpResult(err) {
+    if (err instanceof AssetUploadError) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ error: err.message, code: err.code }, null, 2),
+                }],
+            isError: true,
+        };
+    }
+    return fail(err);
+}
+// Shape a graph entity into the MCP result. Strip the frontmatter fields that
+// duplicate the top-level keys: `id`, `entity_type`, AND `type`.
+//
+// `type` is the load-bearing one: it is NOT a duplicate of `entity_type` — it's
+// a real field on `event` entities (the sub-type: meeting/call/workshop). Left
+// in the spread it would land AFTER `type: entityType` and shadow the canonical
+// type, so search/list reported `type: "meeting"` for an event and the caller
+// couldn't round-trip that back into get_entity (`Entity not found:
+// meeting/<id>`). We re-expose it as `subtype` so the top-level `type` is always
+// the canonical entity type, which is what get_entity resolves against.
 function shape(id, entityType, data, extra) {
-    const { id: _id, entity_type: _et, ...rest } = data;
-    return { id, type: entityType, ...rest, ...extra };
+    const { id: _id, entity_type: _et, type: subtype, ...rest } = data;
+    return {
+        id,
+        type: entityType,
+        ...(subtype !== undefined ? { subtype } : {}),
+        ...rest,
+        ...extra,
+    };
+}
+/**
+ * Default subfolders for entity types when the caller omits `folder_path`.
+ * Existing entries with no folder live at the repo root; new entries of these
+ * types route into a typed subfolder so the repo stays organised by default.
+ * An explicit `folder_path: ""` (or any explicit value) overrides this map.
+ */
+const DEFAULT_FOLDER_BY_TYPE = {
+    person: 'People',
+    organization: 'Organizations',
+};
+/** Convert an absolute entity path to a repo-relative POSIX path. */
+function relPathOf(absPath, repoRoot) {
+    return absPath.startsWith(repoRoot + '/') ? absPath.slice(repoRoot.length + 1) : absPath;
+}
+function slugifyArtifactId(source) {
+    const slug = (source || 'artifact')
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80);
+    return slug || 'artifact';
+}
+function artifactFrontmatter(bundle, options = {}) {
+    const data = {
+        name: bundle.title,
+        kind: bundle.kind,
+        viewport_width: bundle.viewport.width,
+        viewport_height: bundle.viewport.height,
+        viewport_mode: bundle.viewport.mode,
+    };
+    if (options.includeStatus)
+        data.status = 'draft';
+    return data;
+}
+function parseArtifactBundleFromBody(content, label) {
+    let rawBundle;
+    try {
+        rawBundle = JSON.parse(content);
+    }
+    catch {
+        throw new Error(`${label} body is not a valid JSON bundle.`);
+    }
+    const validation = validateArtifactBundle(rawBundle);
+    if (!validation.ok || !validation.bundle) {
+        throw new Error(`Invalid artifact bundle: ${validation.errors.join('; ')}`);
+    }
+    return validation.bundle;
+}
+function exportedData(format, bytes, mimeType) {
+    if (format === 'html') {
+        return {
+            mime_type: 'text/html; charset=utf-8',
+            content: bytes.toString(),
+        };
+    }
+    const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+    return {
+        mime_type: mimeType ?? (format === 'png' ? 'image/png' : 'application/pdf'),
+        data_base64: buffer.toString('base64'),
+        byteLength: buffer.length,
+    };
 }
+/**
+ * Presign MIME enum for `create_asset_upload`, derived from the format registry
+ * (P4-V1) so the tool's accepted set can't drift from the presign service's gate.
+ * z.enum needs a non-empty tuple; the registry always yields ≥1 image MIME, but
+ * fall back to png/jpeg defensively so a registry edit can never produce an
+ * empty enum that throws at module load.
+ */
+const PRESIGN_MIME_TUPLE = (() => {
+    const mimes = presignMimeAllowlist();
+    return mimes.length > 0 ? mimes : ['image/png', 'image/jpeg'];
+})();
+/** Inline-upload (upload_asset_inline) caps + accepted-MIME display list,
+ *  computed once at module load from the registry (not per /mcp request). */
+const INLINE_MAX_BYTES = 6 * 1024 * 1024; // ~4.5MB pre-base64; keeps the model payload sane.
+const INLINE_UPLOAD_MIME_LIST = inlineUploadMimeAllowlist().sort();
 // ── tool registration ─────────────────────────────────────────────────────────
-export function registerTools(server, wm, authService) {
+export function registerTools(server, wm, authService, ctx) {
+    const { user, wsHub, apiTokenName, commentService } = ctx;
+    // Register through this wrapper instead of server.registerTool directly so
+    // the always-load pin (PIN_META) is injected from a SINGLE source
+    // (PINNED_SET / MCP_PINNED_TOOLS) and can't drift per-call. Non-pinned tools
+    // pass through untouched.
+    const baseRegisterTool = server.registerTool.bind(server);
+    const reg = ((name, def, handler) => baseRegisterTool(name, PINNED_SET.has(name) ? { ...def, ...PIN_META } : def, handler));
+    // External-agent identity: "<owner first name>'s <token name>", or
+    // "<owner first name>'s agent" as a fallback when the token has no name
+    // (older tokens or contexts that didn't thread the token through). First name
+    // only keeps the chip short while preserving cross-user disambiguation; the
+    // `userId` lets the client paint the chip with the owning user's avatar accent
+    // (so the full identity is still recoverable). Falls back to the whole
+    // displayName when there's no space to split on (handles, single names).
+    const ownerFirstName = user.displayName.trim().split(/\s+/)[0] || user.displayName;
+    const agentLabel = apiTokenName
+        ? `${ownerFirstName}'s ${apiTokenName}`
+        : `${ownerFirstName}'s agent`;
+    const agentIdentity = {
+        kind: 'external',
+        label: agentLabel,
+        userId: String(user.id),
+    };
+    // Match the broadcast shape used by src/server/routes/graph-api.ts so the
+    // realtime listener in web/src/lib/stores/realtime.svelte.ts treats MCP
+    // mutations identically to web-UI mutations. The `agent` tag lets clients
+    // distinguish agent-driven mutations from human-driven ones.
+    function emitEntityChange(action, repo, entityType, entityId) {
+        wsHub?.broadcast({
+            type: 'entity_change',
+            action,
+            repo,
+            entityType,
+            entityId,
+            actor: user.displayName,
+            source: 'api',
+            agent: agentIdentity,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Wrap a mutation tool call so the sidebar can show a live "X's agent is
+     * acting" chip in the affected folder. `enter` fires before the work,
+     * `leave` after — wsHub TTL-cleans on crash. `verb` shapes the chip copy.
+     */
+    async function withAgentActivity(repo, verb, fn) {
+        wsHub?.handleAgentActivity('enter', repo, agentIdentity, verb);
+        try {
+            return await fn();
+        }
+        finally {
+            wsHub?.handleAgentActivity('leave', repo, agentIdentity, verb);
+        }
+    }
+    // Entity types the MCP surface may create. Matches the agent's allowlist so
+    // a workspace looks identical across the main app and MCP clients: the full
+    // canonical catalog plus workspace custom types. See
+    // src/core/entity-types-catalog.ts.
+    const builtinTypeKeys = new Set(Object.keys(ENTITY_SCHEMAS));
+    const customWorkspaceTypes = wm.getSchemaRegistry().getAllTypes()
+        .filter(t => !builtinTypeKeys.has(t));
+    const mcpAllowedCreateTypes = getAgentAllowedEntityTypes(customWorkspaceTypes);
+    const mcpAllowedSet = new Set(mcpAllowedCreateTypes);
     // ── list_repos ────────────────────────────────────────────────────────────
-    server.registerTool('list_repos', { description: 'List all collections in the Studiograph workspace' }, async () => ok(wm.getAllRepoConfigs()));
+    reg('list_repos', { description: 'List folders in the Studiograph workspace that you have access to' }, async () => ok(getAccessibleRepos(user, wm, authService)));
+    // ── create_repo ───────────────────────────────────────────────────────────
+    //
+    // Creates a new shared folder in the workspace and grants the
+    // caller folder-admin access. Shares its implementation with the web route
+    // POST /api/repos via services/folder-creation.ts so both surfaces behave
+    // identically. After creation, use create_entity with the new folder name
+    // to add entries. Folder names are immutable slugs; the display name is
+    // editable later via the web UI.
+    const createRepoSchema = z.object({
+        name: z.string().describe('Folder slug — lowercase kebab-case (letters, digits, hyphens; must start with a letter or digit). ' +
+            'This becomes the folder id and directory name; it cannot be changed without a rename.'),
+        display_name: z.string().optional().describe('Human-readable name shown in the UI (e.g. "Client Projects"). Defaults to the slug.'),
+        description: z.string().optional().describe('Short description of what this folder is for.'),
+    });
+    reg('create_repo', {
+        description: 'Create a new shared folder in the workspace. Use this when an agent or ' +
+            'user needs a fresh container for a new project, client area, or topic and no existing ' +
+            'folder fits. The caller is automatically granted folder-admin access. ' +
+            'Follow up with create_entity (passing the new folder name as `repo`) to seed entries. ' +
+            'Folder names must be kebab-case and unique; the private per-user "entries-<id>" ' +
+            'namespace is reserved and will be rejected.',
+        inputSchema: createRepoSchema,
+    }, async (args) => {
+        const { name, display_name, description } = createRepoSchema.parse(args);
+        try {
+            const repo = await createSharedFolder(wm, authService, { name, display_name, description }, user, wsHub);
+            return ok({ success: true, ...repo });
+        }
+        catch (err) {
+            if (err instanceof FolderCreationError) {
+                return fail(new Error(err.message));
+            }
+            return fail(err);
+        }
+    });
     // ── list_entities ─────────────────────────────────────────────────────────
     const listEntitiesSchema = z.object({
-        repo: z.string().optional().describe('Collection name — omit to list across all collections'),
-        entity_type: z.string().optional().describe('Entity type filter (project, client, person, meeting…)'),
+        repo: z.string().optional().describe('Folder name — omit to list across all folders'),
+        entity_type: z.string().optional().describe('Entity type filter (project, client, person, event…)'),
         limit: z.number().int().positive().optional().describe('Maximum number of results'),
     });
-    server.registerTool('list_entities', { description: 'List entities in a collection (or all collections). Optionally filter by entity type.', inputSchema: listEntitiesSchema }, async (args) => {
+    reg('list_entities', { description: 'List entries in a folder (or all folders). Optionally filter by entity type. Each result carries the canonical `type` and a repo-relative `path` — pass either back to get_entity to open it.', inputSchema: listEntitiesSchema }, async (args) => {
         const { repo, entity_type, limit } = listEntitiesSchema.parse(args);
         try {
+            // Comments live in SQLite, not the filesystem graph — dispatch through
+            // the virtual-entity adapter when the caller asks for them explicitly.
+            if (entity_type === 'comment' && commentService) {
+                if (repo && !hasRepoAccess(user, repo, wm, authService))
+                    return notFound(repo);
+                const accessibleNames = new Set(getAccessibleRepos(user, wm, authService).map(r => r.name));
+                const envelopes = commentVirtualEntity.listComments(commentService, { repo, limit });
+                const filtered = envelopes.filter(e => accessibleNames.has(e.data.repo));
+                return ok(filtered.map(e => shape(e.id, e.entityType, e.data, { repo: e.data.repo })));
+            }
             if (repo) {
-                const entities = wm.getGraph(repo).list(entity_type, limit);
-                return ok(entities.map(e => shape(e.id, e.entityType, e.data)));
+                if (!hasRepoAccess(user, repo, wm, authService))
+                    return notFound(repo);
+                const graph = wm.getGraph(repo);
+                const repoRoot = graph.getRepoPath();
+                const entities = graph.list(entity_type, limit);
+                return ok(entities.map(e => shape(e.id, e.entityType, e.data, { path: relPathOf(e.path, repoRoot) })));
+            }
+            // No repo specified → iterate only over the user's accessible folders.
+            const accessible = getAccessibleRepos(user, wm, authService);
+            const results = [];
+            for (const r of accessible) {
+                try {
+                    const graph = wm.getGraph(r.name);
+                    const repoRoot = graph.getRepoPath();
+                    const list = graph.list(entity_type);
+                    for (const e of list) {
+                        results.push(shape(e.id, e.entityType, e.data, { repo: r.name, path: relPathOf(e.path, repoRoot) }));
+                        if (limit && results.length >= limit)
+                            return ok(results);
+                    }
+                }
+                catch { /* skip unmounted repos */ }
             }
-            const entities = wm.list(entity_type, limit);
-            return ok(entities.map(e => shape(e.id, e.entityType, e.data, { repo: e.repoName })));
+            return ok(results);
         }
         catch (err) {
             return fail(err);
@@ -49,15 +367,64 @@ export function registerTools(server, wm, authService) {
     });
     // ── get_entity ────────────────────────────────────────────────────────────
     const getEntitySchema = z.object({
-        repo: z.string().describe('Collection name'),
-        entity_type: z.string().describe('Entity type (project, client, person…)'),
-        entity_id: z.string().describe('Entity ID (kebab-case slug)'),
+        repo: z.string().describe('Folder name'),
+        entity_type: z.string().optional().describe('Canonical entity type as returned in a search/list result\'s `type` (e.g. "event" — NOT a category/subtype value like "meeting"). Optional: when omitted or wrong, the entity is resolved by id.'),
+        entity_id: z.string().optional().describe('Entity ID (kebab-case slug). Provide entity_id or path.'),
+        path: z.string().optional().describe('Repo-relative file path from a search/list result (`path` field). When given, resolves directly and ignores entity_type.'),
     });
-    server.registerTool('get_entity', { description: 'Get a specific entity — includes full markdown content and frontmatter', inputSchema: getEntitySchema }, async (args) => {
-        const { repo, entity_type, entity_id } = getEntitySchema.parse(args);
+    reg('get_entity', {
+        description: 'Get a specific entry — full markdown content and frontmatter. Robust resolution: pass the `type` and `id` ' +
+            '(or the `path`) exactly as returned by search_entities/list_entities. If the type is wrong or omitted, the ' +
+            'entry is still resolved by id, so a search hit never fails to open.',
+        inputSchema: getEntitySchema,
+    }, async (args) => {
+        const { repo, entity_type, entity_id, path } = getEntitySchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        if (!entity_id && !path)
+            return fail(new Error('get_entity requires entity_id or path'));
         try {
-            const entity = wm.getGraph(repo).get(entity_type, entity_id);
-            return ok({ id: entity.id, type: entity.entityType, data: entity.data, content: entity.document.content });
+            if (entity_type === 'comment' && commentService) {
+                const envelope = commentVirtualEntity.getComment(commentService, entity_id);
+                if (!envelope)
+                    return fail(new Error(`Comment "${entity_id}" not found`));
+                if (envelope.data.repo !== repo)
+                    return notFound(repo);
+                return ok({ id: envelope.id, type: envelope.entityType, data: envelope.data, content: envelope.document.content });
+            }
+            const graph = wm.getGraph(repo);
+            // Resolve robustly so any search/list result re-opens without the
+            // caller guessing the physical type: explicit path wins; else try the
+            // supplied type; on a miss (wrong/legacy type — e.g. an `event` whose
+            // `type` field is "meeting") fall back to id-only resolution.
+            let entity;
+            if (path) {
+                entity = graph.getByPath(path);
+            }
+            else if (entity_type) {
+                try {
+                    entity = graph.get(entity_type, entity_id);
+                }
+                catch {
+                    entity = graph.getById(entity_id);
+                }
+            }
+            else {
+                entity = graph.getById(entity_id);
+            }
+            // Prefer the live editor body when a seeded Y.Doc is open: graph reads
+            // disk, which lags the editor by the autosave debounce, so a user's
+            // freshly-placed image/asset embed may not be on disk yet. Use the
+            // RESOLVED type/id — getById/getByPath may differ from what was passed.
+            const liveBody = graph.getLiveBody(entity.entityType, entity.id);
+            const content = liveBody ?? entity.document.content;
+            return ok({
+                id: entity.id,
+                type: entity.entityType,
+                path: relPathOf(entity.path, graph.getRepoPath()),
+                data: entity.data,
+                content,
+            });
         }
         catch (err) {
             return fail(err);
@@ -67,76 +434,1053 @@ export function registerTools(server, wm, authService) {
     const searchSchema = z.object({
         query: z.string().optional().describe('Text search query'),
         entity_type: z.string().optional().describe('Filter by entity type'),
-        repos: z.array(z.string()).optional().describe('Limit to specific collection names'),
+        repos: z.array(z.string()).optional().describe('Limit to specific folder names'),
         limit: z.number().int().positive().optional().describe('Maximum number of results'),
     });
-    server.registerTool('search_entities', { description: 'Full-text search for entities across all collections', inputSchema: searchSchema }, async (args) => {
+    reg('search_entities', { description: 'Full-text search for entries across folders you can access. Each result carries the canonical `type` and a repo-relative `path` — pass either back to get_entity to open it.', inputSchema: searchSchema }, async (args) => {
         const { query, entity_type, repos, limit } = searchSchema.parse(args);
         try {
-            const results = await wm.search({ query, entityType: entity_type, repoNames: repos, limit });
-            return ok(results.map(e => shape(e.id, e.entityType, e.data, { repo: e.repoName })));
+            const accessibleNames = new Set(getAccessibleRepos(user, wm, authService).map(r => r.name));
+            const scoped = repos
+                ? repos.filter(r => accessibleNames.has(r))
+                : [...accessibleNames];
+            if (scoped.length === 0)
+                return ok([]);
+            const results = await wm.search({ query, entityType: entity_type, repoNames: scoped, limit });
+            return ok(results.map(e => shape(e.id, e.entityType, e.data, {
+                repo: e.repoName,
+                path: relPathOf(e.path, wm.getGraph(e.repoName).getRepoPath()),
+            })));
         }
         catch (err) {
             return fail(err);
         }
     });
     // ── create_entity ─────────────────────────────────────────────────────────
+    // Constrain `entity_type` to the allowlist so MCP clients (e.g. Claude Desktop)
+    // see the same type surface as the main agent. Existing canonical-type entities
+    // remain readable/updatable via other tools.
+    const createEntityTypeSchema = mcpAllowedCreateTypes.length > 0
+        ? z.enum(mcpAllowedCreateTypes)
+        : z.string();
     const createSchema = z.object({
-        repo: z.string().describe('Collection name'),
-        entity_type: z.string().describe('Entity type'),
+        repo: z.string().describe('Folder name'),
+        entity_type: createEntityTypeSchema.describe(`Entity type. Allowed: ${mcpAllowedCreateTypes.join(', ')}.`),
         entity_id: z.string().describe('Entity ID (kebab-case slug)'),
-        data: z.record(z.unknown()).describe('Frontmatter fields as a JSON object'),
-        content: z.string().optional().describe('Markdown body content'),
+        data: z.record(z.string(), z.unknown()).describe('Type-specific frontmatter fields (e.g. for person: name, email, organization, role). ' +
+            'Base fields (entity_id, entity_type, created_at, updated_at, created_by, updated_by) ' +
+            'are stamped automatically — do not include them.'),
+        content: z.string().optional().describe('Markdown body content. Write one line per paragraph — use newlines only for real paragraph/list breaks, not to wrap prose at a column width (entries render source line breaks literally).'),
+        folder_path: z.string().optional().describe('Repo-relative subfolder to place the entry in (e.g. "People", "clients/acme"). ' +
+            'Omit to use the per-type default (person → People, organization → Organizations); ' +
+            'pass an empty string to force the repo root. Parent folders are auto-created.'),
     });
-    server.registerTool('create_entity', { description: 'Create a new entity in a collection. Commits to git automatically.', inputSchema: createSchema }, async (args) => {
-        const { repo, entity_type, entity_id, data, content } = createSchema.parse(args);
+    reg('create_entity', {
+        description: 'Create a new entity (entry) in a folder — person, organization, project, task, note, document, etc. ' +
+            'Commits to git automatically. Base frontmatter (entity_id, timestamps, author) is stamped ' +
+            'automatically; `data` carries only type-specific fields. For person entries, `status` synonyms ' +
+            '(active/prospective/past/…) normalize to `current` | `former`. See the `folder_path` field for ' +
+            'placement defaults. Response includes the final repo-relative `path`.',
+        inputSchema: createSchema,
+    }, async (args) => {
+        const { repo, entity_type, entity_id, data, content, folder_path } = createSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        if (!canWriteRepo(user, repo, wm, authService)) {
+            return fail(new Error(`You do not have write access to folder "${repo}"`));
+        }
+        // Defense in depth: MCP SDK may not enforce zod enum strictly on all clients.
+        if (!mcpAllowedSet.has(entity_type)) {
+            const hint = isCuratedEntityType(entity_type)
+                ? '' // shouldn't happen for any other curated type — they're all allowed
+                : ` Allowed: ${mcpAllowedCreateTypes.join(', ')}.`;
+            return fail(new Error(`Entity type "${entity_type}" is not a known canonical or workspace custom type.${hint}`));
+        }
+        // Explicit folder_path (including "") wins; otherwise apply the per-type
+        // default so the agent doesn't have to know the workspace convention.
+        const effectiveFolder = folder_path !== undefined
+            ? folder_path
+            : (DEFAULT_FOLDER_BY_TYPE[entity_type] ?? '');
+        // Enforce the user↔person bridge invariant on person creates, matching
+        // graph-api + graph-tools: at most one person entity per auth handle
+        // workspace-wide (validateUserHandleInPayload), and only a workspace
+        // owner may stamp a handle (assertCanChangeUserHandle). Without this,
+        // create_entity over MCP was the one write path that could plant a
+        // SECOND linked record — violating "multiple person entries, but only
+        // one linked".
+        if (entity_type === 'person') {
+            try {
+                const incoming = (data ?? {});
+                validateUserHandleInPayload(wm, incoming);
+                if (Object.prototype.hasOwnProperty.call(incoming, 'user_handle')) {
+                    assertCanChangeUserHandle(user, '', incoming.user_handle);
+                }
+            }
+            catch (err) {
+                if (err instanceof BridgeError)
+                    return fail(err);
+                throw err;
+            }
+        }
+        // Scope ref fields (today: task.assignee → person). Reject a wikilink
+        // that resolves to a non-person; forward references are allowed.
         try {
-            const entity = await wm.getGraph(repo).create({
-                entityType: entity_type,
-                entityId: entity_id,
-                data: data,
-                content,
-            });
-            return ok({ success: true, id: entity.id, type: entity.entityType });
+            assertEntityRefs(wm, entity_type, data, { userExists: (id) => !!authService.findUserById(Number(id)) });
         }
         catch (err) {
             return fail(err);
         }
+        const actor = buildActor(user);
+        const options = prepareCreatePayload({
+            entityType: entity_type,
+            entityId: entity_id,
+            data: data,
+            content,
+            folderPath: effectiveFolder || undefined,
+        }, actor);
+        return withAgentActivity(repo, 'creating', async () => {
+            try {
+                const graph = wm.getGraph(repo);
+                // Detect implicit subfolder creation: if the entity lands in a folder
+                // that didn't exist yet, the entity_change below only refreshes the
+                // entry list — clients need a _folder event to refetch the folder
+                // tree (sidebar + list/gallery folder rows). Normalize the same way
+                // graph.create does so the existence check matches the real path.
+                const normFolder = effectiveFolder ? validateFolderPath(effectiveFolder) : '';
+                const folderExisted = !normFolder || existsSync(join(graph.getRepoPath(), normFolder));
+                const entity = await graph.create(options);
+                emitEntityChange('created', repo, entity.entityType, entity.id);
+                if (!folderExisted)
+                    emitEntityChange('created', repo, '_folder', normFolder);
+                return ok({
+                    success: true,
+                    id: entity.id,
+                    type: entity.entityType,
+                    repo,
+                    path: relPathOf(entity.path, graph.getRepoPath()),
+                    folder_path: entity.folder_path,
+                });
+            }
+            catch (err) {
+                return fail(err);
+            }
+        });
     });
     // ── update_entity ─────────────────────────────────────────────────────────
+    //
+    // Bare success envelopes were misleading agents: callers couldn't tell
+    // whether their write landed, whether validation silently dropped a field,
+    // or whether they'd just rewritten the file with identical bytes. The
+    // response now includes path, commit, before/after hashes, per-section
+    // changed flags, and the post-write entity snapshot so agents can verify
+    // their intent matches reality without a follow-up get_entity round-trip.
+    //
+    // No-op detection compares semantic frontmatter (excluding auto-stamped
+    // `updated_at` / `updated_by`) and raw content. A no-op is reported as
+    // success with `noop: true` — not an error — so idempotent re-runs are
+    // explicit. If the caller passed data or content but the on-disk file is
+    // byte-identical after the write, that's a silent-drop signal: the call
+    // fails loudly with a message that names which inputs were ignored.
     const updateSchema = z.object({
-        repo: z.string().describe('Collection name'),
+        repo: z.string().describe('Folder name'),
         entity_type: z.string().describe('Entity type'),
         entity_id: z.string().describe('Entity ID'),
-        data: z.record(z.unknown()).optional().describe('Frontmatter fields to update (merged with existing)'),
-        content: z.string().optional().describe('New markdown body content'),
+        data: z.record(z.string(), z.unknown()).optional().describe('Frontmatter fields to update (merged with existing)'),
+        content: z.string().optional().describe('New markdown body content (replaces the entire body). Write one line per paragraph — use newlines only for real paragraph/list breaks, not to wrap prose at a column width (entries render source line breaks literally).'),
+        allow_image_removal: z.boolean().optional().describe('Whole-body writes are rejected with code ASSET_REMOVAL_BLOCKED when the submitted content would drop ' +
+            'image/attachment embeds that the current document still has (a common silent-data-loss bug when an agent ' +
+            'edits stale content). Set true ONLY when you intend to delete those embeds. Prefer patch_entity for small edits.'),
+    });
+    reg('update_entity', {
+        description: 'Update (edit) an existing entity. `data` fields merge with existing frontmatter; `content` replaces the ' +
+            'whole markdown body. Immutable base fields are preserved from disk; `updated_at`/`updated_by` are stamped. ' +
+            'For small body edits prefer patch_entity (it can\'t drop image embeds). Returns the post-write snapshot plus ' +
+            'diagnostic flags (frontmatter_changed, content_changed, noop, commit) so you can verify the write landed ' +
+            'without a follow-up get_entity.',
+        inputSchema: updateSchema,
+    }, async (args) => {
+        const { repo, entity_type, entity_id, data, content, allow_image_removal } = updateSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        if (!canWriteRepo(user, repo, wm, authService)) {
+            return fail(new Error(`You do not have write access to folder "${repo}"`));
+        }
+        if (data === undefined && content === undefined) {
+            return fail(new Error('update_entity requires at least one of `data` or `content`'));
+        }
+        // Enforce the user↔person bridge invariant on person updates, matching
+        // graph-api + graph-tools: workspace-wide handle uniqueness (skipping the
+        // entity being written) + owner-only authz to change `user_handle`. Keeps
+        // update_entity from becoming a back door around "only one linked record".
+        if (entity_type === 'person' && data) {
+            try {
+                const incoming = data;
+                validateUserHandleInPayload(wm, incoming, { repo, entityId: entity_id });
+                if (Object.prototype.hasOwnProperty.call(incoming, 'user_handle')) {
+                    let currentHandle = '';
+                    try {
+                        currentHandle = (wm.getGraph(repo).get('person', entity_id)?.data?.user_handle ?? '');
+                    }
+                    catch { /* new/missing entity — treat as empty */ }
+                    assertCanChangeUserHandle(user, currentHandle, incoming.user_handle);
+                }
+            }
+            catch (err) {
+                if (err instanceof BridgeError)
+                    return fail(err);
+                throw err;
+            }
+        }
+        // Scope ref fields (today: task.assignee → person). Reject a wikilink
+        // that resolves to a non-person; forward references are allowed.
+        try {
+            assertEntityRefs(wm, entity_type, data, { userExists: (id) => !!authService.findUserById(Number(id)) });
+        }
+        catch (err) {
+            return fail(err);
+        }
+        const actor = buildActor(user);
+        const options = prepareUpdatePayload({
+            entityType: entity_type,
+            entityId: entity_id,
+            data: data,
+            content,
+        }, actor);
+        return withAgentActivity(repo, 'editing', async () => {
+            try {
+                const graph = wm.getGraph(repo);
+                // Diagnosed update (shared with the agent surface): snapshots
+                // before, runs the server-write path (disk + commit serialize via
+                // the per-doc lock; live clients get the post-commit broadcast),
+                // and throws SilentDropError when the caller intended a change
+                // that produced no on-disk diff. The outer catch maps that to fail.
+                const { entity, frontmatter_changed, content_changed, noop, broadcast } = await diagnosedUpdate(graph, options, { data, content }, { allowAssetRemoval: allow_image_removal });
+                emitEntityChange('updated', repo, entity.entityType, entity.id);
+                // Repo-relative path so external agents don't see the workspace
+                // absolute path. The HEAD commit is captured after graph.update
+                // commits the transaction — null when noGit is on or no commit
+                // was produced (e.g. transaction self-cleared because there was
+                // no staged diff).
+                const repoRoot = graph.getRepoPath();
+                const relPath = entity.path.startsWith(repoRoot + '/')
+                    ? entity.path.slice(repoRoot.length + 1)
+                    : entity.path;
+                const commit = graph.getGitService()?.getHeadCommit() ?? null;
+                return ok({
+                    success: true,
+                    id: entity.id,
+                    type: entity.entityType,
+                    repo,
+                    path: relPath,
+                    commit,
+                    frontmatter_changed,
+                    content_changed,
+                    noop,
+                    broadcast,
+                    updated_at: entity.data.updated_at ?? null,
+                    entity: {
+                        id: entity.id,
+                        type: entity.entityType,
+                        data: entity.data,
+                        content: entity.document.content,
+                    },
+                });
+            }
+            catch (err) {
+                if (err instanceof DroppedAssetError) {
+                    return ok({
+                        success: false,
+                        code: 'ASSET_REMOVAL_BLOCKED',
+                        droppedAssets: err.dropped,
+                        message: err.message,
+                    });
+                }
+                return fail(err);
+            }
+        });
+    });
+    // ── Artifact Canvas tools ────────────────────────────────────────────────
+    //
+    // MCP parity for the in-app artifact tools. External agents should not need
+    // to hand-roll graph entity JSON for artifacts or discover the HTTP export
+    // routes. These wrappers keep the same ArtifactBundle validation and commit
+    // semantics as the web/chat flow, while visual inspection reuses the shared
+    // Playwright renderer used by PDF/PNG export.
+    const createArtifactSchema = z.object({
+        repo: z.string().describe('Folder name where the artifact entry should be created or updated.'),
+        bundle: z.unknown().describe('ArtifactBundle object with schemaVersion, artifactId, title, kind, viewport, optional libraries (three, d3, motion), files, and entrypoint.'),
+        entity_id: z.string().optional().describe('Existing artifact entity id to update, or desired id for a new artifact. Defaults to a slug from bundle.artifactId/title.'),
+        folder_path: z.string().optional().describe('Repo-relative subfolder for a newly created artifact. Ignored when updating an existing artifact.'),
+    });
+    reg('create_artifact', {
+        description: 'Create or update a persisted sandboxed Artifact Canvas entry from an HTML/CSS/JS ArtifactBundle. ' +
+            'Use this for slide decks, documents, social graphics, prototypes, diagrams, small interactive tools, ' +
+            'artifacts using curated local libraries (three, d3, motion), and other visual outputs. ' +
+            'Validates the bundle, writes an artifact graph entry, commits to git, and ' +
+            'broadcasts the same live entity_change event as the web agent.',
+        inputSchema: createArtifactSchema,
+    }, async (args) => {
+        const { repo, bundle: rawBundle, entity_id, folder_path } = createArtifactSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        if (!canWriteRepo(user, repo, wm, authService)) {
+            return fail(new Error(`You do not have write access to folder "${repo}"`));
+        }
+        const validation = validateArtifactBundle(rawBundle);
+        if (!validation.ok || !validation.bundle) {
+            return fail(new Error(`Invalid artifact bundle: ${validation.errors.join('; ')}`));
+        }
+        const bundle = validation.bundle;
+        const graph = wm.getGraph(repo);
+        const actor = buildActor(user);
+        const body = `${JSON.stringify(bundle, null, 2)}\n`;
+        const createData = artifactFrontmatter(bundle, { includeStatus: true });
+        const updateData = artifactFrontmatter(bundle);
+        return withAgentActivity(repo, entity_id ? 'editing' : 'creating', async () => {
+            try {
+                const preferredId = entity_id || slugifyArtifactId(bundle.artifactId || bundle.title);
+                let resolvedId = preferredId;
+                let existing = false;
+                if (entity_id) {
+                    try {
+                        graph.get('artifact', preferredId);
+                        existing = true;
+                    }
+                    catch {
+                        existing = false;
+                    }
+                }
+                else {
+                    let suffix = 2;
+                    while (suffix < 1000) {
+                        try {
+                            graph.get('artifact', resolvedId);
+                            resolvedId = `${preferredId}-${suffix++}`;
+                        }
+                        catch {
+                            break;
+                        }
+                    }
+                }
+                if (existing) {
+                    const options = prepareUpdatePayload({
+                        entityType: 'artifact',
+                        entityId: resolvedId,
+                        data: updateData,
+                        content: body,
+                    }, actor);
+                    const { entity, frontmatter_changed, content_changed, noop, broadcast } = await diagnosedUpdate(graph, options, { data: updateData, content: body });
+                    emitEntityChange('updated', repo, entity.entityType, entity.id);
+                    return ok({
+                        success: true,
+                        action: 'updated',
+                        id: entity.id,
+                        type: entity.entityType,
+                        repo,
+                        path: relPathOf(entity.path, graph.getRepoPath()),
+                        commit: graph.getGitService()?.getHeadCommit() ?? null,
+                        frontmatter_changed,
+                        content_changed,
+                        noop,
+                        broadcast,
+                    });
+                }
+                const entity = await graph.create(prepareCreatePayload({
+                    entityType: 'artifact',
+                    entityId: resolvedId,
+                    data: createData,
+                    content: body,
+                    folderPath: folder_path || undefined,
+                }, actor));
+                emitEntityChange('created', repo, entity.entityType, entity.id);
+                return ok({
+                    success: true,
+                    action: 'created',
+                    id: entity.id,
+                    type: entity.entityType,
+                    repo,
+                    path: relPathOf(entity.path, graph.getRepoPath()),
+                    commit: graph.getGitService()?.getHeadCommit() ?? null,
+                });
+            }
+            catch (err) {
+                return fail(err);
+            }
+        });
+    });
+    const inspectArtifactSchema = z.object({
+        repo: z.string().optional().describe('Folder containing the persisted artifact entry. Required when bundle is omitted.'),
+        entity_id: z.string().optional().describe('Persisted artifact entity id. Required when bundle is omitted.'),
+        bundle: z.unknown().optional().describe('ArtifactBundle object to inspect without saving. If omitted, repo + entity_id are loaded from the graph.'),
+        context: z.enum(['editor', 'fullscreen']).optional().describe('"editor" renders the canvas overview/grid; "fullscreen" renders the share/fullscreen view. Defaults to editor.'),
+        frame_selector: z.string().optional().describe('CSS selector for individual frames/pages/slides. Defaults to display.controls.stepper.selector, then [data-artifact-frame], [data-artifact-page], .page.'),
+        frame_indexes: z.array(z.number()).optional().describe('Specific zero-based frame/page/slide indexes to screenshot.'),
+        max_frames: z.number().optional().describe('Maximum number of individual frames/pages/slides to screenshot. Defaults to 6, max 24.'),
+        include_page_screenshot: z.boolean().optional().describe('Whether to include a screenshot of the whole rendered page. Defaults to true.'),
+        include_frame_screenshots: z.boolean().optional().describe('Whether to include screenshots for selected frames/pages/slides. Defaults to true.'),
+        screenshot_format: z.enum(['jpeg', 'png']).optional().describe('Screenshot encoding. Defaults to jpeg to keep tool results compact.'),
+        base_url: z.string().optional().describe('Optional app origin such as http://localhost:3000, used only to allow same-origin /api/assets/* font/image loads during render.'),
     });
-    server.registerTool('update_entity', { description: 'Update an existing entity. Data fields are merged with existing frontmatter.', inputSchema: updateSchema }, async (args) => {
-        const { repo, entity_type, entity_id, data, content } = updateSchema.parse(args);
+    reg('inspect_artifact', {
+        description: 'Use Playwright to visually inspect an ArtifactBundle or persisted artifact entry. Returns a page screenshot, ' +
+            'frame/page/slide metadata, optional individual frame screenshots, console messages, page errors, and failed requests. ' +
+            'Use this after creating or revising artifacts to verify layout and individual slides/pages.',
+        inputSchema: inspectArtifactSchema,
+    }, async (args) => {
+        const parsed = inspectArtifactSchema.parse(args);
+        let bundle;
         try {
-            const entity = await wm.getGraph(repo).update({
-                entityType: entity_type,
-                entityId: entity_id,
-                data: data,
-                content,
+            if (parsed.bundle !== undefined) {
+                const validation = validateArtifactBundle(parsed.bundle);
+                if (!validation.ok || !validation.bundle) {
+                    return fail(new Error(`Invalid artifact bundle: ${validation.errors.join('; ')}`));
+                }
+                bundle = validation.bundle;
+            }
+            else {
+                if (!parsed.repo || !parsed.entity_id) {
+                    return fail(new Error('inspect_artifact requires either bundle or both repo and entity_id.'));
+                }
+                if (!hasRepoAccess(user, parsed.repo, wm, authService))
+                    return notFound(parsed.repo);
+                const entity = wm.getGraph(parsed.repo).get('artifact', parsed.entity_id);
+                bundle = parseArtifactBundleFromBody(entity.document.content, `Artifact ${parsed.repo}/${parsed.entity_id}`);
+            }
+            const options = {
+                context: parsed.context,
+                frameSelector: parsed.frame_selector,
+                frameIndexes: parsed.frame_indexes,
+                maxFrames: parsed.max_frames,
+                includePageScreenshot: parsed.include_page_screenshot,
+                includeFrameScreenshots: parsed.include_frame_screenshots,
+                screenshotFormat: parsed.screenshot_format,
+                baseUrl: parsed.base_url,
+            };
+            return ok({ success: true, inspection: await inspectArtifactRender(bundle, options) });
+        }
+        catch (err) {
+            if (err instanceof ArtifactRenderExportUnavailableError) {
+                return fail(new Error(`${err.message} Install with: npx playwright install chromium`));
+            }
+            return fail(err);
+        }
+    });
+    const exportArtifactSchema = z.object({
+        repo: z.string().describe('Folder containing the artifact entry.'),
+        entity_id: z.string().describe('Persisted artifact entity id.'),
+        format: z.enum(['html', 'png', 'pdf']).describe('Export format to produce. HTML returns text content; PNG/PDF return base64 bytes.'),
+        base_url: z.string().optional().describe('Optional app origin such as http://localhost:3000, used only to allow same-origin /api/assets/* font/image loads during PNG/PDF render.'),
+    });
+    reg('export_artifact', {
+        description: 'Export a persisted Artifact Canvas entry as HTML, PNG, or PDF. HTML returns text content. ' +
+            'PNG/PDF are rendered with Playwright and returned as base64 bytes so MCP clients can save them.',
+        inputSchema: exportArtifactSchema,
+    }, async (args) => {
+        const { repo, entity_id, format, base_url } = exportArtifactSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        try {
+            const entity = wm.getGraph(repo).get('artifact', entity_id);
+            const bundle = parseArtifactBundleFromBody(entity.document.content, `Artifact ${repo}/${entity_id}`);
+            const typedFormat = format;
+            let bytes;
+            let filename = artifactExportFilename(bundle, typedFormat);
+            let mimeType;
+            if (typedFormat === 'html') {
+                bytes = buildArtifactHtmlExport(bundle, {
+                    context: 'fullscreen',
+                    baseHref: base_url ? `${base_url.replace(/\/+$/, '')}/` : undefined,
+                    includeRenderHostStyles: true,
+                    librarySources: artifactLibrarySourcesForBundle(bundle),
+                });
+            }
+            else if (typedFormat === 'png') {
+                const pngFiles = await renderArtifactPngFiles(bundle, { baseUrl: base_url });
+                if (pngFiles.length > 1) {
+                    const namedFiles = nameArtifactPngFiles(bundle, pngFiles);
+                    bytes = await zipArtifactPngFiles(namedFiles);
+                    filename = artifactPngArchiveFilename(bundle);
+                    mimeType = 'application/zip';
+                }
+                else {
+                    bytes = pngFiles[0]?.bytes ?? Buffer.alloc(0);
+                }
+            }
+            else {
+                bytes = await renderArtifactPdf(bundle, { baseUrl: base_url });
+            }
+            return ok({
+                success: true,
+                repo,
+                entity_id,
+                format: typedFormat,
+                filename,
+                ...exportedData(typedFormat, bytes, mimeType),
             });
-            return ok({ success: true, id: entity.id, type: entity.entityType });
         }
         catch (err) {
+            if (err instanceof ArtifactRenderExportUnavailableError) {
+                return fail(new Error(`${err.message} Install with: npx playwright install chromium`));
+            }
             return fail(err);
         }
     });
+    // ── patch_entity ──────────────────────────────────────────────────────────
+    //
+    // Surgical body edit: replace an exact substring without resending the
+    // whole body. The motivating failure was an agent fetching content,
+    // renaming a heading, and resending the entire body — which dropped
+    // editor-placed image embeds it never saw. patch_entity can't drop what it
+    // doesn't send: it reads the CURRENT body (live editor when open, else
+    // disk), applies the literal find→replace, and writes the result through
+    // the same guarded server-write path. The asset-drop guard still runs, so
+    // a patch that happens to delete an embed is rejected unless the substring
+    // is itself the embed being intentionally removed.
+    const patchEntitySchema = z.object({
+        repo: z.string().describe('Folder name'),
+        entity_type: z.string().describe('Entity type'),
+        entity_id: z.string().describe('Entity ID'),
+        find: z.string().describe('Exact substring to locate in the current body (verbatim, including whitespace).'),
+        replace: z.string().describe('Replacement text. Empty string deletes the matched substring.'),
+        expected_count: z.number().int().positive().optional().describe('Optional safety check: require `find` to occur exactly this many times. The patch is rejected with ' +
+            'NO_MATCH / AMBIGUOUS_MATCH when the actual count differs, so you never edit the wrong occurrence.'),
+    });
+    reg('patch_entity', {
+        description: 'Surgically edit an entry body by replacing an exact substring — without rewriting the whole body. ' +
+            'Prefer this over update_entity for small edits (renaming a heading, fixing a sentence): it operates on ' +
+            'the live editor body and cannot drop image/asset embeds it did not touch. Returns the same diagnostic ' +
+            'flags as update_entity. Use `expected_count` to guard against ambiguous matches.',
+        inputSchema: patchEntitySchema,
+    }, async (args) => {
+        const { repo, entity_type, entity_id, find, replace, expected_count } = patchEntitySchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        if (!canWriteRepo(user, repo, wm, authService)) {
+            return fail(new Error(`You do not have write access to folder "${repo}"`));
+        }
+        if (find === '')
+            return fail(new Error('patch_entity requires a non-empty `find` string'));
+        if (find === replace)
+            return fail(new Error('patch_entity `find` and `replace` are identical — nothing to do'));
+        return withAgentActivity(repo, 'editing', async () => {
+            try {
+                const graph = wm.getGraph(repo);
+                const entity = graph.get(entity_type, entity_id);
+                // Patch against the live editor body when one is open, so we don't
+                // reintroduce the stale-read problem we're fixing.
+                const currentBody = graph.getLiveBody(entity_type, entity_id) ?? entity.document.content;
+                // Count occurrences of the literal substring (no regex).
+                let count = 0;
+                for (let i = currentBody.indexOf(find); i !== -1; i = currentBody.indexOf(find, i + find.length))
+                    count++;
+                if (count === 0) {
+                    return ok({ success: false, code: 'NO_MATCH', message: `\`find\` substring not present in ${entity_type}/${entity_id}.` });
+                }
+                if (expected_count !== undefined && count !== expected_count) {
+                    return ok({ success: false, code: 'AMBIGUOUS_MATCH', occurrences: count, message: `Expected ${expected_count} occurrence(s) of \`find\`, found ${count}.` });
+                }
+                const newBody = currentBody.split(find).join(replace);
+                const options = prepareUpdatePayload({ entityType: entity_type, entityId: entity_id, content: newBody }, buildActor(user));
+                const { entity: updated, frontmatter_changed, content_changed, noop, broadcast } = await diagnosedUpdate(graph, options, { content: newBody });
+                emitEntityChange('updated', repo, updated.entityType, updated.id);
+                const repoRoot = graph.getRepoPath();
+                const relPath = updated.path.startsWith(repoRoot + '/') ? updated.path.slice(repoRoot.length + 1) : updated.path;
+                return ok({
+                    success: true,
+                    id: updated.id, type: updated.entityType, repo, path: relPath,
+                    commit: graph.getGitService()?.getHeadCommit() ?? null,
+                    occurrences: count, frontmatter_changed, content_changed, noop, broadcast,
+                });
+            }
+            catch (err) {
+                if (err instanceof DroppedAssetError) {
+                    return ok({ success: false, code: 'ASSET_REMOVAL_BLOCKED', droppedAssets: err.dropped, message: err.message });
+                }
+                return fail(err);
+            }
+        });
+    });
+    // ── list_assets ─────────────────────────────────────────────────────────
+    //
+    // Read-only discovery of assets (images, PDFs, files) already uploaded to a
+    // folder. Shares listRepoAssets() with the HTTP asset endpoints, so the
+    // shape — including the render-safe `embed` string — is identical. Assets
+    // are created only through the upload routes / workspace UI; this tool never
+    // creates one, it only surfaces existing ones so an agent can reference them
+    // in an entry body without guessing a URL or embed syntax.
+    const listAssetsSchema = z.object({
+        repo: z.string().describe('Folder name'),
+        entity_type: z.string().optional().describe('Filter to assets owned by entries of this type'),
+        entity_id: z.string().optional().describe('Filter to assets owned by this entry id'),
+    });
+    reg('list_assets', {
+        description: 'List assets (images, PDFs, files) already uploaded to a folder. Each result includes a ready-to-paste ' +
+            '`embed` — standard markdown `![name](url)` — that renders in the editor. To display an asset in an entry, ' +
+            'place that exact `embed` string via attach_asset_to_entity (or patch_entity for append/insert). ' +
+            'NEVER write `![[filename]]` transclusion syntax: it does not resolve to a stored asset and shows as dead ' +
+            'text. Assets are uploaded via the workspace UI — this tool only references existing ones. Optionally ' +
+            'filter by entity_type and/or entity_id to list a single entry\'s assets.',
+        inputSchema: listAssetsSchema,
+    }, async (args) => {
+        const { repo, entity_type, entity_id } = listAssetsSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        try {
+            wm.getGraph(repo);
+        }
+        catch {
+            return notFound(repo);
+        }
+        let assets = await listRepoAssets(repo, wm);
+        if (entity_type)
+            assets = assets.filter(a => a.entityType === entity_type);
+        if (entity_id)
+            assets = assets.filter(a => a.entityId === entity_id);
+        return ok({
+            repo,
+            count: assets.length,
+            assets: assets.map(a => ({
+                asset_id: a.assetId,
+                filename: a.filename,
+                mime_type: a.contentType,
+                entity_type: a.entityType,
+                entity_id: a.entityId,
+                entity_name: a.entityName,
+                url: a.url,
+                embed: a.embed,
+            })),
+        });
+    });
+    // ── attach_asset_to_entity ──────────────────────────────────────────────
+    //
+    // Place an already-uploaded asset (from list_assets) into an entry body
+    // without rewriting the whole body. Thin convenience over the patch_entity
+    // machinery: it builds the render-safe `![alt](url)` embed and either
+    // appends it or swaps a placeholder for it, then writes through the same
+    // guarded server-write path.
+    //
+    // `replace_placeholder` is the sanctioned way to fix a dead `![[Foo.png]]`
+    // placeholder. Note: that swap necessarily *drops* the transclusion target
+    // (`Foo.png`) the asset-drop guard recognizes, so a plain patch_entity of
+    // the same span would be rejected with ASSET_REMOVAL_BLOCKED. Here we pass
+    // allowAssetRemoval for replace_placeholder only — the agent is explicitly
+    // targeting that placeholder and we're re-adding the image as a working
+    // embed, so no real asset is lost. `append` keeps the guard on.
+    const attachAssetSchema = z.object({
+        repo: z.string().describe('Folder name'),
+        entity_type: z.string().describe('Entity type of the target entry'),
+        entity_id: z.string().describe('Entity ID of the target entry'),
+        url: z.string().describe('Asset url, taken verbatim from list_assets (e.g. /api/assets/<id>/<file>)'),
+        alt: z.string().optional().describe('Alt text / caption for the embed. Defaults to the asset filename.'),
+        mode: z.enum(['append', 'replace_placeholder']).default('append').describe('"append" adds the embed at the end of the body. "replace_placeholder" swaps `placeholder` text ' +
+            '(e.g. a dead `![[Foo.png]]` written earlier) for the working embed.'),
+        placeholder: z.string().optional().describe('Required when mode="replace_placeholder": exact text to replace.'),
+        expected_count: z.number().int().positive().optional().describe('For replace_placeholder: require `placeholder` to occur exactly this many times, else reject (AMBIGUOUS_MATCH).'),
+    });
+    reg('attach_asset_to_entity', {
+        description: 'Embed an already-uploaded asset (from list_assets) into an entry body using its render-safe markdown, ' +
+            'without rewriting the whole body. mode="append" adds it at the end; mode="replace_placeholder" swaps dead ' +
+            'placeholder text (e.g. an `![[Foo.png]]` an agent wrote earlier) for the working embed. Drop-guarded on ' +
+            'append: rejects with ASSET_REMOVAL_BLOCKED if it would remove other image embeds.',
+        inputSchema: attachAssetSchema,
+    }, async (args) => {
+        const { repo, entity_type, entity_id, url, alt, mode, placeholder, expected_count } = attachAssetSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        if (!canWriteRepo(user, repo, wm, authService)) {
+            return fail(new Error(`You do not have write access to folder "${repo}"`));
+        }
+        if (!url.trim())
+            return fail(new Error('attach_asset_to_entity requires a non-empty `url`'));
+        if (mode === 'replace_placeholder' && !placeholder) {
+            return fail(new Error('mode="replace_placeholder" requires a non-empty `placeholder`'));
+        }
+        const filename = alt ?? (url.split('/').pop() || 'asset').split('?')[0];
+        const embed = assetEmbed(filename, url);
+        return withAgentActivity(repo, 'editing', async () => {
+            try {
+                const graph = wm.getGraph(repo);
+                const entity = graph.get(entity_type, entity_id);
+                const currentBody = graph.getLiveBody(entity_type, entity_id) ?? entity.document.content;
+                let newBody;
+                let occurrences;
+                let allowAssetRemoval = false;
+                if (mode === 'replace_placeholder') {
+                    const ph = placeholder;
+                    let count = 0;
+                    for (let i = currentBody.indexOf(ph); i !== -1; i = currentBody.indexOf(ph, i + ph.length))
+                        count++;
+                    if (count === 0) {
+                        return ok({ success: false, code: 'NO_MATCH', message: `placeholder not present in ${entity_type}/${entity_id}.` });
+                    }
+                    if (expected_count !== undefined && count !== expected_count) {
+                        return ok({ success: false, code: 'AMBIGUOUS_MATCH', occurrences: count, message: `Expected ${expected_count} occurrence(s) of placeholder, found ${count}.` });
+                    }
+                    occurrences = count;
+                    newBody = currentBody.split(ph).join(embed);
+                    // The placeholder we're removing is itself a recognized embed
+                    // target; swapping it for the working embed is the whole point.
+                    allowAssetRemoval = true;
+                }
+                else {
+                    if (currentBody.includes(embed)) {
+                        return ok({ success: false, code: 'ALREADY_PRESENT', message: `Asset embed already present in ${entity_type}/${entity_id}.` });
+                    }
+                    newBody = currentBody.trimEnd() + '\n\n' + embed + '\n';
+                }
+                const options = prepareUpdatePayload({ entityType: entity_type, entityId: entity_id, content: newBody }, buildActor(user));
+                const { entity: updated, frontmatter_changed, content_changed, noop, broadcast } = await diagnosedUpdate(graph, options, { content: newBody }, { allowAssetRemoval });
+                emitEntityChange('updated', repo, updated.entityType, updated.id);
+                const repoRoot = graph.getRepoPath();
+                const relPath = updated.path.startsWith(repoRoot + '/') ? updated.path.slice(repoRoot.length + 1) : updated.path;
+                return ok({
+                    success: true,
+                    id: updated.id, type: updated.entityType, repo, path: relPath,
+                    embed, mode, occurrences,
+                    commit: graph.getGitService()?.getHeadCommit() ?? null,
+                    frontmatter_changed, content_changed, noop, broadcast,
+                });
+            }
+            catch (err) {
+                if (err instanceof DroppedAssetError) {
+                    return ok({ success: false, code: 'ASSET_REMOVAL_BLOCKED', droppedAssets: err.dropped, message: err.message });
+                }
+                return fail(err);
+            }
+        });
+    });
+    // ── create_asset_upload ─────────────────────────────────────────────────
+    //
+    // Step 1 of 3 for the pre-signed asset upload flow. Validates request,
+    // resolves target folder (defaults to the workspace_wide Assets store),
+    // mints a pre-signed PUT URL the agent uploads to directly, and returns
+    // an HMAC token to pass back to finalize_asset_upload. Bytes never travel
+    // through this MCP server — only authz + indexing do.
+    //
+    // The tool description is load-bearing: it's what the agent reads to
+    // plan the three-step flow. Be explicit about each step and the exact
+    // shape of the PUT.
+    const createAssetUploadSchema = z.object({
+        repo: z.string().optional().describe('Folder name. Omit to upload into the shared "Assets" store (created on first use).'),
+        filename: z.string().describe('Filename including extension (e.g. "logo.png"). Sanitized server-side; no path segments.'),
+        // Registry-driven (P4-V1): the presign path only accepts formats safe as
+        // raw bytes (the app never holds them, so it can't sanitize). SVG +
+        // documents are excluded here and go through upload_asset_inline instead.
+        mime_type: z.enum(PRESIGN_MIME_TUPLE).describe(`Image MIME accepted by the presign flow: ${PRESIGN_MIME_TUPLE.join(', ')}. ` +
+            `SVG and documents are not presignable (use upload_asset_inline).`),
+    });
+    reg('create_asset_upload', {
+        description: 'Upload a large image (PNG/JPEG, max 20MB) via pre-signed PUT — STEP 1 of 3. ' +
+            'Returns { assetId, uploadUrl, headers, token, expiresAt, repo }.\n\n' +
+            'STEP 2 (not an MCP tool): HTTP PUT the raw image bytes to `uploadUrl` with the returned `headers` ' +
+            'verbatim (notably `Content-Type`). The URL expires in 15 minutes.\n\n' +
+            'STEP 3: call `finalize_asset_upload({ token })` to register the asset and get a permanent URL, then ' +
+            'optionally `attach_asset_to_entity({ url, ... })` to embed it in an entry body.\n\n' +
+            'For small files, prefer the one-call upload_asset_inline. ' +
+            'Errors with code "local_backend" when the workspace uses local filesystem storage (R2 only).',
+        inputSchema: createAssetUploadSchema,
+    }, async (args) => {
+        const parsed = createAssetUploadSchema.parse(args);
+        try {
+            // Asset-as-embed (B2): the upload always produces a FREE-STANDING,
+            // folder-owned asset. There is no entity-ownership handoff — embed it
+            // into an entry afterwards via attach_asset_to_entity.
+            const result = await presignAssetUpload({
+                workspaceManager: wm,
+                authService,
+                user,
+                repo: parsed.repo,
+                filename: parsed.filename,
+                mimeType: parsed.mime_type,
+            });
+            return ok({
+                assetId: result.assetId,
+                uploadUrl: result.uploadUrl,
+                headers: result.headers,
+                token: result.token,
+                expiresAt: result.expiresAt,
+                repo: result.repo,
+            });
+        }
+        catch (err) {
+            return errorToMcpResult(err);
+        }
+    });
+    // ── finalize_asset_upload ───────────────────────────────────────────────
+    //
+    // Step 3 of 3. Verifies the upload landed at the pre-signed URL,
+    // validates content-type + size at the wire, promotes the blob from
+    // `pending/` into the canonical keyspace, and registers a FREE-STANDING,
+    // folder-owned asset (no entity). Idempotent on token replay:
+    // a second call returns the existing assetId + URL.
+    //
+    // Identity-bound (R1): the user calling finalize must be the same user
+    // who minted the token — leaked tokens cannot be replayed by another
+    // folder-writer. Workspace owners are NOT exempt.
+    const finalizeAssetUploadSchema = z.object({
+        token: z.string().describe('HMAC token returned by create_asset_upload.'),
+        name: z.string().optional().describe('Optional display name for the asset entry. Defaults to a title-cased version of the filename stem.'),
+    });
+    reg('finalize_asset_upload', {
+        description: 'STEP 3 of 3. Call this after PUTting bytes to the uploadUrl returned by create_asset_upload. ' +
+            'Verifies the upload landed, validates content type and size, registers a free-standing asset, and returns ' +
+            '{ assetId, url, ownerType, ownerId, repo }. Embed it into an entry afterwards via attach_asset_to_entity. ' +
+            'Idempotent: calling with the same token twice returns the existing asset.\n\n' +
+            'Errors with code "upload_not_received" if the PUT never happened (or the 15-min window expired); ' +
+            '"upload_validation" if content type or size doesn\'t match the presign contract; "token_invalid" if ' +
+            'the token is tampered or expired; "forbidden" if the caller is not the original presigner or has lost ' +
+            'folder access in the interim.',
+        inputSchema: finalizeAssetUploadSchema,
+    }, async (args) => {
+        const parsed = finalizeAssetUploadSchema.parse(args);
+        try {
+            const result = await finalizeAssetUpload({
+                workspaceManager: wm,
+                authService,
+                user,
+                token: parsed.token,
+                name: parsed.name,
+            });
+            // Asset-as-embed (B2): finalize registers a FREE-STANDING asset, not an
+            // entity, so there's no entity_change to broadcast — it surfaces in the
+            // asset manager on its next load. Its image caption/OCR IS derived for
+            // search: finalize seeds an assetId-keyed index-state row + notifies the
+            // live caption drain, and the caption folds into any entry that embeds
+            // the asset.
+            return ok({
+                assetId: result.assetId,
+                url: result.url,
+                ownerType: result.ownerType,
+                ownerId: result.ownerId,
+                repo: result.repo,
+            });
+        }
+        catch (err) {
+            return errorToMcpResult(err);
+        }
+    });
+    // ── upload_asset_inline ─────────────────────────────────────────────────────
+    //
+    // V3: single-call asset upload for SMALL files where the bytes can ride
+    // inline (base64). Unlike create_asset_upload (R2-only presign, 3 steps,
+    // bytes never touch the app), this works on local OR R2 backends and is one
+    // round-trip — the tradeoff is a tight size cap (base64 inflates the model
+    // context ~33%, and the bytes traverse this server). For large files or when
+    // an R2 backend is available, prefer the presign flow.
+    //
+    // Indexing reaches web parity: after the asset entity is committed we enqueue
+    // the live caption/extract drain (same as a web upload), so an inline-
+    // uploaded image is captioned while the server runs.
+    const uploadAssetInlineSchema = z.object({
+        repo: z.string().optional().describe('Folder name. Omit to upload into the shared "Assets" store (created on first use).'),
+        filename: z.string().describe('Filename including extension (e.g. "diagram.png"). Sanitized server-side; no path segments.'),
+        data_base64: z.string().describe('The file bytes, base64-encoded. Keep under ~4.5MB raw (6MB base64) — larger files must use create_asset_upload.'),
+        name: z.string().optional().describe('Optional display name for the asset entry. Defaults to a title-cased filename stem.'),
+        folder_path: z.string().optional().describe('Optional repo-relative subfolder for the entry .md (e.g. "Diagrams"). Defaults to repo root.'),
+    });
+    reg('upload_asset_inline', {
+        description: 'Ingest a SMALL file (image or document) as a typed entry in ONE call by passing its bytes ' +
+            'base64-encoded. The file is stored as a free-standing asset and a typed entry that embeds it ' +
+            'is created — image→material, doc/pdf→document (extracted text in the body), xlsx/csv→dataset — ' +
+            'exactly as a web import would. Returns { assetId, url, repo, entities: [{ entityType, entityId }] }.\n\n' +
+            'Size limit ~4.5MB raw (6MB base64) — for larger files use create_asset_upload (R2 presign, 3 steps). ' +
+            'Accepted types are the workspace upload set (images + documents); SVG is not yet accepted here. ' +
+            'Images are captioned for search automatically in the background.',
+        inputSchema: uploadAssetInlineSchema,
+    }, async (args) => {
+        const parsed = uploadAssetInlineSchema.parse(args);
+        // 1. Format gate: resolve the filename to a registry format and check it
+        //    directly via isInlineUploadAllowed — NOT via detectContentType, whose
+        //    CONTENT_TYPES map returns application/octet-stream for several
+        //    registry-accepted assets (.tsv/.psd/.ai/.aac/...), which would wrongly
+        //    reject them. Both the gate and the allowlist now derive from the same
+        //    registry predicate, so they can't disagree. Rejects SVG (transitional
+        //    until sanitize-html), unaccepted docs, and unknown types (fallback).
+        const format = resolveFormat(parsed.filename);
+        if (!isInlineUploadAllowed(format)) {
+            return fail(new Error(`"${parsed.filename}" is not accepted by upload_asset_inline. ` +
+                `Accepted: ${INLINE_UPLOAD_MIME_LIST.join(', ')}.`));
+        }
+        // 2. Decode + size gate. Node's Buffer.from(..,'base64') silently DROPS
+        //    invalid characters instead of throwing, so a garbage string would
+        //    "decode" to junk bytes. Validate the shape first (strip one optional
+        //    data: prefix + whitespace, then assert the strict base64 charset),
+        //    and re-encode-compare to catch truncation.
+        const raw = parsed.data_base64.replace(/^data:[^;]+;base64,/, '').replace(/\s+/g, '');
+        if (raw.length === 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(raw) || raw.length % 4 !== 0) {
+            return fail(new Error('data_base64 is not valid base64.'));
+        }
+        const buffer = Buffer.from(raw, 'base64');
+        if (buffer.length === 0 || buffer.toString('base64') !== raw) {
+            return fail(new Error('data_base64 is not valid base64.'));
+        }
+        if (buffer.length > INLINE_MAX_BYTES) {
+            return fail(new Error(`Decoded size ${buffer.length} bytes exceeds the inline ${INLINE_MAX_BYTES}-byte cap. Use create_asset_upload for larger files.`));
+        }
+        // 3. Resolve the target repo (default → shared Assets store) + authz.
+        let repo;
+        try {
+            repo = parsed.repo
+                ?? await resolveWorkspaceAssetsRepo(new Workspace(wm.getWorkspacePath()), wm);
+        }
+        catch (err) {
+            return errorToMcpResult(err);
+        }
+        if (!canWriteRepo(user, repo, wm, authService)) {
+            return fail(`You don't have permission to write to "${repo}". Editor or admin role required.`);
+        }
+        let graph;
+        try {
+            graph = wm.getGraph(repo);
+        }
+        catch (err) {
+            return errorToMcpResult(err);
+        }
+        // 4. Ingest via the asset-as-embed import: store the bytes as a
+        //    free-standing folder-owned asset + create the typed entry(ies) whose
+        //    body embeds it (image→material, doc→document, xlsx→dataset×N).
+        //    Auto-commits. Same path as web import/drag-drop.
+        try {
+            const result = await withAgentActivity(repo, 'creating', () => importAssetAsEntity({
+                graph,
+                filename: parsed.filename,
+                buffer,
+                folderPath: parsed.folder_path || undefined,
+                name: parsed.name,
+                user: buildActor(user),
+                uploaderUserId: String(user.id),
+            }));
+            for (const e of result.entities)
+                emitEntityChange('created', repo, e.entityType, e.entityId);
+            // V3 indexing parity: the created entries' bodies are vector-indexed
+            // natively; the embedded image asset's caption drains in the background.
+            return ok({
+                assetId: result.assetId,
+                url: result.asset_url,
+                repo,
+                entities: result.entities.map(e => ({ entityType: e.entityType, entityId: e.entityId })),
+            });
+        }
+        catch (err) {
+            return errorToMcpResult(err);
+        }
+    });
+    // ── move_entity ───────────────────────────────────────────────────────────
+    //
+    // Relocate an entity to a different folder within the same repo. Wraps
+    // graph.move() which renames the file on disk and commits the rename so
+    // git's similarity detection preserves history. The (type, id) identity
+    // is unchanged — get_entity, search, list, validate_wikilinks, and the
+    // history tools all walk the entire repo tree and continue to find the
+    // entry at its new path. For cross-repo transfers, the web UI's bulk-move
+    // dialog or POST /api/repos/:repo/transfer is the right surface.
+    const moveEntitySchema = z.object({
+        repo: z.string().describe('Folder name containing the entry'),
+        entity_type: z.string().describe('Entity type'),
+        entity_id: z.string().describe('Entity ID'),
+        folder_path: z.string().describe('Target repo-relative folder path (e.g. "People", "Clients/Acme"). ' +
+            'Empty string moves the entry to the repo root. Parent folders are auto-created.'),
+        overwrite: z.boolean().optional().describe('When true, replace an existing entry at the destination. The occupant ' +
+            'must itself be a parseable entity — README/.gitkeep/etc. are never ' +
+            'clobbered. Defaults to false; the call errors with "Path already ' +
+            'occupied" when the destination is taken.'),
+    });
+    reg('move_entity', {
+        description: 'Move an existing entry to a different folder within the same folder/repo. ' +
+            'Preserves frontmatter, markdown content, entity ID, and git history (file is renamed, not rewritten). ' +
+            'Use this to organise entries into subfolders after creation — e.g. moving a person into People/. ' +
+            'By default, errors if the destination already has an entry; pass `overwrite: true` to replace.',
+        inputSchema: moveEntitySchema,
+    }, async (args) => {
+        const { repo, entity_type, entity_id, folder_path, overwrite } = moveEntitySchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        if (!canWriteRepo(user, repo, wm, authService)) {
+            return fail(new Error(`You do not have write access to folder "${repo}"`));
+        }
+        const actor = buildActor(user);
+        return withAgentActivity(repo, 'editing', async () => {
+            try {
+                const graph = wm.getGraph(repo);
+                // If the destination folder doesn't exist yet, the move creates it —
+                // emit a _folder event (alongside the entry update) so clients
+                // refetch the folder tree, not just the entry list.
+                const normTarget = folder_path ? validateFolderPath(folder_path) : '';
+                const targetExisted = !normTarget || existsSync(join(graph.getRepoPath(), normTarget));
+                const moved = await graph.move(entity_type, entity_id, folder_path, undefined, actor, overwrite);
+                emitEntityChange('updated', repo, moved.entityType, moved.id);
+                if (!targetExisted)
+                    emitEntityChange('created', repo, '_folder', normTarget);
+                return ok({
+                    success: true,
+                    id: moved.id,
+                    type: moved.entityType,
+                    repo,
+                    path: relPathOf(moved.path, graph.getRepoPath()),
+                    folder_path: moved.folder_path,
+                });
+            }
+            catch (err) {
+                return fail(err);
+            }
+        });
+    });
+    // ── create_subfolder ──────────────────────────────────────────────────────
+    //
+    // Create a nested subfolder inside an existing folder/collection. Wraps
+    // graph.createFolder(). Distinct from create_repo, which registers a new
+    // top-level collection. Emits the _folder sentinel so live clients refetch
+    // the folder tree (sidebar + list/gallery folder rows) without a reload.
+    const createSubfolderSchema = z.object({
+        repo: z.string().describe('Folder name (collection) to create the subfolder inside'),
+        path: z.string().describe('Repo-relative POSIX path of the new subfolder (e.g. "Clients/Acme"). Parent segments are auto-created.'),
+        display_name: z.string().optional().describe('Optional human-readable label. Omit when the title-cased folder name is the right display ' +
+            '(pass it for casing the slug can\'t express, e.g. "HR" or "Schema_OS").'),
+    });
+    reg('create_subfolder', {
+        description: 'Create a new subfolder inside an existing folder/collection. Path is repo-relative POSIX (e.g. "Clients/Acme"); parent segments are auto-created. ' +
+            'Use it to organise entries, then place entries inside via create_entity (folder_path) or move_entity. ' +
+            'For a brand-new top-level collection, use create_repo instead.',
+        inputSchema: createSubfolderSchema,
+    }, async (args) => {
+        const { repo, path, display_name } = createSubfolderSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        if (!canWriteRepo(user, repo, wm, authService)) {
+            return fail(new Error(`You do not have write access to folder "${repo}"`));
+        }
+        const actor = buildActor(user);
+        return withAgentActivity(repo, 'creating', async () => {
+            try {
+                const graph = wm.getGraph(repo);
+                await graph.createFolder(path, undefined, actor, { displayName: display_name });
+                emitEntityChange('created', repo, '_folder', path);
+                return ok({ success: true, repo, path, folder_path: path });
+            }
+            catch (err) {
+                return fail(err);
+            }
+        });
+    });
     // ── validate_wikilinks ────────────────────────────────────────────────────
     const validateWikilinksSchema = z.object({
-        repo: z.string().describe('Collection name'),
+        repo: z.string().describe('Folder name'),
         entity_type: z.string().describe('Entity type'),
         entity_id: z.string().describe('Entity ID'),
     });
-    server.registerTool('validate_wikilinks', { description: 'Check which wikilinks in an entity resolve to real entities and which are broken', inputSchema: validateWikilinksSchema }, async (args) => {
+    reg('validate_wikilinks', { description: 'Check which wikilinks in an entity resolve to real entities and which are broken', inputSchema: validateWikilinksSchema }, async (args) => {
         const { repo, entity_type, entity_id } = validateWikilinksSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
         try {
             const result = wm.getGraph(repo).validateWikilinks(entity_type, entity_id);
-            return ok({ entity_id, valid: result.valid, broken: result.broken, total: result.valid.length + result.broken.length });
+            const accessibleIds = getAccessibleEntityIds(user, wm, authService);
+            const valid = filterWikilinks(result.valid, accessibleIds);
+            // Anything the user can't see is reported as broken rather than valid —
+            // it shouldn't leak the target's existence.
+            const hiddenFromValid = result.valid.filter(id => !valid.includes(id));
+            const broken = [...result.broken, ...hiddenFromValid];
+            return ok({ entity_id, valid, broken, total: valid.length + broken.length });
         }
         catch (err) {
             return fail(err);
@@ -144,23 +1488,41 @@ export function registerTools(server, wm, authService) {
     });
     // ── find_related ──────────────────────────────────────────────────────────
     const relatedSchema = z.object({
-        repo: z.string().describe('Collection name'),
+        repo: z.string().describe('Folder name'),
         entity_type: z.string().describe('Entity type'),
         entity_id: z.string().describe('Entity ID'),
         direction: z.enum(['outgoing', 'incoming', 'both']).default('both')
             .describe('outgoing = links from this entity, incoming = links to this entity'),
     });
-    server.registerTool('find_related', { description: 'Find entities related via wikilinks (outgoing) or backlinks (incoming)', inputSchema: relatedSchema }, async (args) => {
+    reg('find_related', { description: 'Find entities related via wikilinks (outgoing) or backlinks (incoming)', inputSchema: relatedSchema }, async (args) => {
         const { repo, entity_type, entity_id, direction } = relatedSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
         try {
+            const accessibleIds = getAccessibleEntityIds(user, wm, authService);
             const results = [];
             if (direction === 'outgoing' || direction === 'both') {
                 const related = wm.getGraph(repo).getRelated(entity_type, entity_id);
-                results.push(...related.map(e => shape(e.id, e.entityType, e.data, { direction: 'outgoing' })));
+                for (const e of related) {
+                    if (accessibleIds && !accessibleIds.has(e.id))
+                        continue;
+                    results.push(shape(e.id, e.entityType, e.data, { direction: 'outgoing' }));
+                }
             }
             if (direction === 'incoming' || direction === 'both') {
+                // Comments anchored to this entry surface as incoming backlinks.
+                if (commentService) {
+                    const anchored = commentVirtualEntity.findRelatedComments(commentService, repo, entity_type, entity_id);
+                    for (const e of anchored) {
+                        results.push(shape(e.id, e.entityType, e.data, { direction: 'incoming', repo }));
+                    }
+                }
                 const backlinks = wm.getBacklinks(repo, entity_type, entity_id);
-                results.push(...backlinks.map(e => shape(e.id, e.entityType, e.data, { direction: 'incoming', repo: e.repoName })));
+                for (const e of backlinks) {
+                    if (!hasRepoAccess(user, e.repoName, wm, authService))
+                        continue;
+                    results.push(shape(e.id, e.entityType, e.data, { direction: 'incoming', repo: e.repoName }));
+                }
             }
             return ok(results);
         }
@@ -168,84 +1530,370 @@ export function registerTools(server, wm, authService) {
             return fail(err);
         }
     });
-    // ── View management tools ────────────────────────────────────────────────
-    if (authService) {
-        server.registerTool('list_views', { description: 'List the current user\'s saved views.', inputSchema: z.object({}) }, async () => {
-            try {
-                return ok(authService.getUserViews(0));
+    // ── list_skills ──────────────────────────────────────────────────────────
+    //
+    // Surfaces user-authored `skill` entities to external MCP clients so
+    // connected agents (Claude Desktop, Cursor, etc.) can discover and run
+    // the workspace's codified workflows. Only graph skills (entities) are
+    // exposed; bundled filesystem skills (onboarding/interview/enrichment
+    // prompts) stay internal to Studiograph's own agent.
+    const listSkillsSchema = z.object({
+        repo: z.string().optional().describe('Folder name — omit to list across all folders you have access to'),
+    });
+    function projectSkill(entity, repo) {
+        const data = entity.data;
+        return {
+            id: entity.id,
+            name: data.name || entity.id,
+            description: data.description ?? '',
+            repo,
+            loading: data.loading === 'eager' ? 'eager' : 'on-demand',
+        };
+    }
+    // `graph.list('skill')` is lenient — root-level .md files without a
+    // declared `entity_type` (READMEs, CHANGELOGs) get tagged as whatever the
+    // caller asks for. For MCP we want only real skills, so require the
+    // frontmatter to explicitly say `entity_type: skill`.
+    function isRealSkill(entity) {
+        return entity.data.entity_type === 'skill';
+    }
+    reg('list_skills', {
+        description: 'List skills (reusable agent instructions) available in the Studiograph workspace. ' +
+            'Skills are user-authored markdown — call get_skill to read the full body and follow ' +
+            'its instructions. Optionally filter by folder.',
+        inputSchema: listSkillsSchema,
+    }, async (args) => {
+        const { repo } = listSkillsSchema.parse(args);
+        try {
+            if (repo) {
+                if (!hasRepoAccess(user, repo, wm, authService))
+                    return notFound(repo);
+                const skills = wm.getGraph(repo).list('skill');
+                return ok(skills.filter(isRealSkill).map(e => projectSkill(e, repo)));
             }
-            catch (err) {
-                return fail(err);
+            const accessible = getAccessibleRepos(user, wm, authService);
+            const results = [];
+            for (const r of accessible) {
+                try {
+                    const skills = wm.getGraph(r.name).list('skill');
+                    for (const e of skills) {
+                        if (isRealSkill(e))
+                            results.push(projectSkill(e, r.name));
+                    }
+                }
+                catch { /* skip unmounted repos */ }
             }
-        });
-        const createViewSchema = z.object({
-            name: z.string().describe('View name'),
-            selected_type: z.string().optional().describe('Entity type filter (e.g. "task")'),
-            group_by: z.string().optional().describe('Column to group by (e.g. "status")'),
-        });
-        server.registerTool('create_view', { description: 'Create a new saved view. Views appear as tabs in the web UI toolbar.', inputSchema: createViewSchema }, async (args) => {
-            const { name, selected_type, group_by } = createViewSchema.parse(args);
-            try {
-                const config = {
-                    selectedType: selected_type ?? null,
-                    groupBy: group_by ?? null,
-                    sortKey: 'name',
-                    sortAsc: true,
-                    filters: { text: {}, enum: {}, date: {} },
-                };
-                const view = authService.createUserView(0, name, 'list', config);
-                return ok({ success: true, view: { id: view.id, name: view.name, config: view.config } });
+            return ok(results);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ── get_skill ────────────────────────────────────────────────────────────
+    //
+    // Returns the full markdown body of a skill alongside its metadata. The
+    // body is instructions to follow — the MCP client is the runtime. No
+    // server-side agent loop, no parameter substitution in v1.
+    const getSkillSchema = z.object({
+        name: z.string().describe('Skill id (the entity_id of the skill entity)'),
+        repo: z.string().optional().describe('Folder to look in. Omit to search across all accessible folders.'),
+    });
+    reg('get_skill', {
+        description: 'Fetch the full content of a skill. Returns the skill\'s markdown body along with its ' +
+            'metadata. The body contains instructions to follow — read it and apply it to the current task.',
+        inputSchema: getSkillSchema,
+    }, async (args) => {
+        const { name, repo } = getSkillSchema.parse(args);
+        try {
+            if (repo) {
+                if (!hasRepoAccess(user, repo, wm, authService))
+                    return notFound(repo);
+                try {
+                    const entity = wm.getGraph(repo).get('skill', name);
+                    if (!isRealSkill({ data: entity.data })) {
+                        return fail(new Error(`Skill "${name}" not found`));
+                    }
+                    return ok({
+                        ...projectSkill({ id: entity.id, data: entity.data }, repo),
+                        content: entity.document.content,
+                    });
+                }
+                catch {
+                    return fail(new Error(`Skill "${name}" not found`));
+                }
             }
-            catch (err) {
-                return fail(err);
+            // No repo — search accessible folders for the skill by id.
+            const accessible = getAccessibleRepos(user, wm, authService);
+            const matches = [];
+            for (const r of accessible) {
+                try {
+                    const entity = wm.getGraph(r.name).get('skill', name);
+                    if (!isRealSkill({ data: entity.data }))
+                        continue;
+                    matches.push({ repo: r.name, entity });
+                }
+                catch { /* not in this repo */ }
             }
-        });
-        const updateViewSchema = z.object({
-            id: z.number().describe('View ID'),
-            name: z.string().optional().describe('New view name'),
-            selected_type: z.string().optional().describe('Entity type filter (use "all" to clear)'),
-            group_by: z.string().optional().describe('Column to group by (use "none" to clear)'),
-        });
-        server.registerTool('update_view', { description: 'Update a saved view\'s name or configuration.', inputSchema: updateViewSchema }, async (args) => {
-            const { id, name, selected_type, group_by } = updateViewSchema.parse(args);
+            if (matches.length === 0)
+                return fail(new Error(`Skill "${name}" not found`));
+            if (matches.length > 1) {
+                const folders = matches.map(m => m.repo).join(', ');
+                return fail(new Error(`Skill "${name}" exists in multiple folders (${folders}). Specify repo.`));
+            }
+            const { repo: matchRepo, entity } = matches[0];
+            return ok({
+                ...projectSkill({ id: entity.id, data: entity.data }, matchRepo),
+                content: entity.document.content,
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ── Git history tools ──────────────────────────────────────────────────────
+    //
+    // Mirrors the agent's history-tools.ts surface so external MCP clients get
+    // the same primitives. Reads gated on hasRepoAccess; restore_file gated on
+    // canWriteRepo. Single-entity scope only — multi-entity rollback is
+    // intentionally absent (deferred to a future revert_commit).
+    const listFileHistorySchema = z.object({
+        repo: z.string().describe('Folder name'),
+        entity_type: z.string().optional().describe('Entity type as returned by search/list. Optional — resolved by id if omitted or wrong.'),
+        entity_id: z.string().optional().describe('Entry ID. Provide entity_id or path.'),
+        path: z.string().optional().describe('Repo-relative file path from a search/list result. When given, resolves directly.'),
+        limit: z.number().optional().describe('Max commits (default 20, max 100)'),
+    });
+    reg('list_file_history', { description: 'List commits that touched a single entry, newest first. Resolve by type+id or by path; a wrong/omitted type still resolves by id.', inputSchema: listFileHistorySchema }, async (args) => {
+        const { repo, entity_type, entity_id, path, limit } = listFileHistorySchema.parse(args);
+        try {
+            if (!hasRepoAccess(user, repo, wm, authService))
+                return fail(`Folder "${repo}" not found`);
+            if (!entity_id && !path)
+                return fail('list_file_history requires entity_id or path');
+            const graph = wm.getGraph(repo);
+            const gitService = graph.getGitService();
+            if (!gitService)
+                return fail('Folder is not git-backed');
+            let entityPath;
             try {
-                const existing = authService.getUserView(id, 0);
-                if (!existing)
-                    return fail(`View ${id} not found`);
-                const fields = {};
-                if (name)
-                    fields.name = name;
-                if (selected_type !== undefined || group_by !== undefined) {
-                    const config = { ...existing.config };
-                    if (selected_type !== undefined)
-                        config.selectedType = selected_type === 'all' ? null : selected_type;
-                    if (group_by !== undefined)
-                        config.groupBy = group_by === 'none' ? null : group_by;
-                    fields.config = config;
-                }
-                authService.updateUserView(id, 0, fields);
-                return ok({ success: true });
+                // Same robust resolution as get_entity: path wins; else try the
+                // supplied type; on a miss fall back to id-only.
+                let entity;
+                if (path)
+                    entity = graph.getByPath(path);
+                else if (entity_type) {
+                    try {
+                        entity = graph.get(entity_type, entity_id);
+                    }
+                    catch {
+                        entity = graph.getById(entity_id);
+                    }
+                }
+                else
+                    entity = graph.getById(entity_id);
+                entityPath = relPathOf(entity.path, graph.getRepoPath());
             }
-            catch (err) {
-                return fail(err);
+            catch {
+                // Live resolution failed (entry may be deleted) → search recent
+                // deletions by filename.
+                const lookupId = entity_id ?? (path ? path.split('/').pop().replace(/\.md$/, '') : '');
+                const idLower = `${lookupId}.md`.toLowerCase();
+                const match = gitService.listRecentDeletions(30).find((d) => d.filePath.toLowerCase().endsWith(idLower));
+                if (!match)
+                    return fail(`Entry ${entity_type ?? entity_id ?? path} not found in "${repo}".`);
+                entityPath = match.filePath;
             }
-        });
-        const deleteViewSchema = z.object({
-            id: z.number().describe('View ID to delete'),
-        });
-        server.registerTool('delete_view', { description: 'Delete a saved view.', inputSchema: deleteViewSchema }, async (args) => {
-            const { id } = deleteViewSchema.parse(args);
-            try {
-                const existing = authService.getUserView(id, 0);
-                if (!existing)
-                    return fail(`View ${id} not found`);
-                authService.deleteUserView(id, 0);
-                return ok({ success: true, message: `Deleted view "${existing.name}"` });
+            const cap = Math.min(100, Math.max(1, limit ?? 20));
+            const commits = gitService.getFileHistory(entityPath, cap).map((c) => ({
+                hash: c.hash.slice(0, 8),
+                fullHash: c.hash,
+                author: c.author,
+                timestamp: c.timestamp,
+                message: c.message,
+            }));
+            return ok({ repo, entityType: entity_type, entityId: entity_id, commits });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    const listFolderHistorySchema = z.object({
+        repo: z.string().describe('Folder name'),
+        limit: z.number().optional().describe('Max commits (default 30, max 200)'),
+    });
+    reg('list_folder_history', { description: 'List recent commits across an entire folder.', inputSchema: listFolderHistorySchema }, async (args) => {
+        const { repo, limit } = listFolderHistorySchema.parse(args);
+        try {
+            if (!hasRepoAccess(user, repo, wm, authService))
+                return fail(`Folder "${repo}" not found`);
+            const gitService = wm.getGraph(repo).getGitService();
+            if (!gitService)
+                return fail('Folder is not git-backed');
+            const cap = Math.min(200, Math.max(1, limit ?? 30));
+            const commits = gitService.getHistory(cap).map((c) => ({
+                hash: c.hash.slice(0, 8),
+                fullHash: c.hash,
+                author: c.author,
+                timestamp: c.timestamp,
+                message: c.message,
+            }));
+            return ok({ repo, commits });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    const listRecentDeletionsSchema = z.object({
+        repo: z.string().describe('Folder name'),
+        within_days: z.number().optional().describe('Lookback window (default 7, max 90)'),
+    });
+    reg('list_recent_deletions', { description: 'List entries deleted within the last N days. Use before restore_file to find a target.', inputSchema: listRecentDeletionsSchema }, async (args) => {
+        const { repo, within_days } = listRecentDeletionsSchema.parse(args);
+        try {
+            if (!hasRepoAccess(user, repo, wm, authService))
+                return fail(`Folder "${repo}" not found`);
+            const gitService = wm.getGraph(repo).getGitService();
+            if (!gitService)
+                return fail('Folder is not git-backed');
+            const days = Math.min(90, Math.max(1, within_days ?? 7));
+            const raw = gitService.listRecentDeletions(days);
+            // Naive coords: use filename basename for entity_id; entity_type
+            // sniffed from frontmatter at lastVersionCommit.
+            const deletions = raw.map((d) => {
+                const idMatch = d.filePath.match(/([^/]+)\.md$/i);
+                const entityId = idMatch ? idMatch[1] : null;
+                const content = entityId ? gitService.getFileAtCommit(d.filePath, d.lastVersionCommit) : null;
+                let entityType = null;
+                if (content) {
+                    const fm = content.match(/^---\s*\n([\s\S]*?)\n---/);
+                    const tm = fm?.[1].match(/^entity_type:\s*['"]?([\w-]+)['"]?\s*$/m);
+                    if (tm)
+                        entityType = tm[1];
+                }
+                if (!entityId || !entityType)
+                    return null;
+                return {
+                    entityType,
+                    entityId,
+                    deletedAt: d.deletedAt,
+                    deletedBy: d.deletedBy.name,
+                    deletedInCommit: d.deletedAtCommit.slice(0, 8),
+                    lastVersionCommit: d.lastVersionCommit,
+                    commitMessage: d.commitMessage,
+                    path: d.filePath,
+                };
+            }).filter((x) => x !== null);
+            return ok({ repo, withinDays: days, deletions });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    const readFileAtCommitSchema = z.object({
+        repo: z.string().describe('Folder name'),
+        entity_type: z.string().describe('Entity type'),
+        entity_id: z.string().describe('Entry ID'),
+        commit_hash: z.string().describe('Commit hash (short or full)'),
+    });
+    reg('read_file_at_commit', { description: 'Read an entry\'s full content at a specific commit.', inputSchema: readFileAtCommitSchema }, async (args) => {
+        const { repo, entity_type, entity_id, commit_hash } = readFileAtCommitSchema.parse(args);
+        try {
+            if (!hasRepoAccess(user, repo, wm, authService))
+                return fail(`Folder "${repo}" not found`);
+            const graph = wm.getGraph(repo);
+            const found = graph.getEntityAtCommit(entity_type, entity_id, commit_hash);
+            if (!found)
+                return fail(`Entry ${entity_type}/${entity_id} not found at commit ${commit_hash}`);
+            // Surface the image/asset embeds present in the body at this commit so
+            // a caller can verify whether images existed here without diffing the
+            // raw markdown by eye. Asset *binaries* aren't in git — these are the
+            // body references, the only image evidence git retains.
+            const embeds = extractAssetEmbeds(stripFrontmatter(found.content));
+            return ok({ repo, entityType: entity_type, entityId: entity_id, commitHash: commit_hash, path: found.path, content: found.content, embeds, embedCount: embeds.length });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    const restoreFileSchema = z.object({
+        repo: z.string().describe('Folder name'),
+        entity_type: z.string().describe('Entity type'),
+        entity_id: z.string().describe('Entry ID'),
+        commit_hash: z.string().describe('Commit hash to restore from'),
+        confirm: z.boolean().optional().describe('Set to true ONLY after the user has approved the preview. Defaults to false.'),
+    });
+    reg('restore_file', { description: 'Restore an entry to its content at a specific commit. Preview-then-confirm: first call returns the preview payload, re-invoke with confirm: true to execute.', inputSchema: restoreFileSchema }, async (args) => {
+        const { repo, entity_type, entity_id, commit_hash, confirm } = restoreFileSchema.parse(args);
+        try {
+            if (!hasRepoAccess(user, repo, wm, authService))
+                return fail(`Folder "${repo}" not found`);
+            if (!canWriteRepo(user, repo, wm, authService))
+                return fail(`You don't have permission to write to "${repo}". Editor or admin role required.`);
+            const graph = wm.getGraph(repo);
+            if (confirm !== true) {
+                const found = graph.getEntityAtCommit(entity_type, entity_id, commit_hash);
+                if (!found)
+                    return fail(`Entry ${entity_type}/${entity_id} not found at commit ${commit_hash}`);
+                let action = 'recreate';
+                try {
+                    graph.get(entity_type, entity_id);
+                    action = 'overwrite';
+                }
+                catch { }
+                const sizeBytes = Buffer.byteLength(found.content, 'utf-8');
+                const shortHash = commit_hash.length > 8 ? commit_hash.slice(0, 8) : commit_hash;
+                // Embeds the restored body will re-link. Restore rewrites the .md
+                // body only; asset binaries live outside git and are NOT touched by
+                // restore — they remain wherever they are (intact unless separately
+                // deleted), so restoring the body re-links any that still exist.
+                const embeds = extractAssetEmbeds(stripFrontmatter(found.content));
+                const assetNote = embeds.length
+                    ? `Restores the body and re-links ${embeds.length} embedded asset reference(s): ${embeds.join(', ')}. ` +
+                        `Asset binaries are stored outside git and are not modified by restore (they remain intact unless separately deleted). `
+                    : '';
+                return ok({
+                    success: false,
+                    code: 'PREVIEW_REQUIRED',
+                    preview: { action, targetPath: found.path, sizeBytes, commitHash: shortHash, embeds, embedCount: embeds.length },
+                    message: `Will ${action} ${entity_type}/${entity_id} from ${shortHash} (${sizeBytes} bytes). ${assetNote}Re-invoke with confirm: true after approval.`,
+                });
             }
-            catch (err) {
-                return fail(err);
+            const result = await withAgentActivity(repo, 'editing', async () => {
+                const { PathConflictError } = await import('../core/graph.js');
+                try {
+                    return await graph.restoreFile(entity_type, entity_id, commit_hash);
+                }
+                catch (err) {
+                    if (err instanceof PathConflictError) {
+                        return { conflict: { path: err.path, occupiedBy: err.occupiedBy } };
+                    }
+                    throw err;
+                }
+            });
+            if ('conflict' in result) {
+                return ok({
+                    success: false,
+                    code: 'PATH_CONFLICT',
+                    conflict: result.conflict,
+                    message: `Cannot restore — ${result.conflict.path} is occupied by ${result.conflict.occupiedBy.entityType}/${result.conflict.occupiedBy.entityId}.`,
+                });
             }
-        });
-    }
+            emitEntityChange(result.action === 'recreate' ? 'created' : 'updated', repo, entity_type, entity_id);
+            const shortHash = commit_hash.length > 8 ? commit_hash.slice(0, 8) : commit_hash;
+            return ok({
+                success: true,
+                repo,
+                entityType: entity_type,
+                entityId: entity_id,
+                action: result.action,
+                path: result.path,
+                commitHash: shortHash,
+                message: `Restored ${entity_type}/${entity_id} from ${shortHash} (${result.action}).`,
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
 }
 //# sourceMappingURL=tools.js.map