studiograph 1.3.48-next.26 → 1.3.48-next.261

package/dist/mcp/tools.js

@@ -5,14 +5,96 @@
  * 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 { isLaunchVisibleEntityType } from '../core/launch-entity-types.js';
+import { isWorkspaceOwner } from '../services/auth-service.js';
+import { mintArtifactAssetTokenForBundle } from '../server/artifact-asset-mint.js';
+import { getAccessibleRepos, hasRepoAccess, canWriteRepo, isFolderAdminOrOwner, getAccessibleEntityIds, filterWikilinks, } from '../services/access-control.js';
+import { assetDeleteDenial } from '../services/asset-delete-authz.js';
+import { isArchivedRepo } from '../core/types.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 { describeZodObject } from '../core/schema-registry.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, applyPatchEntity, } from '../services/entity-mutations.js';
+import { ArtifactStore, ArtifactWriteError } from '../services/artifact-store.js';
+import { patchPersistedArtifact, ArtifactPatchBaseHashError } from '../services/artifact-patch-runner.js';
+import { hashArtifactBody } from '../agent/tools/artifact-tools.js';
+import { buildArtifactManifest } from '../core/artifact-manifest.js';
+import { summarizeArtifactWrite } from '../core/artifact-warnings.js';
+import { BridgeError, validateUserHandleInPayload, assertCanChangeUserHandle } from '../services/user-person-bridge.js';
+import { extractAssetEmbeds, stripFrontmatter, assetEmbed } from '../core/embeds.js';
+import { listRepoAssets, listWorkspaceAssets } 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-frame-model.js';
+import { ArtifactPatchError } from '../core/artifact-patch.js';
+import { buildFrameDocument, bundleNeedsPagination } from '../core/artifact-frame-document.js';
+import { ArtifactRenderExportUnavailableError, ArtifactRenderInstallingError, artifactExportFilename, artifactPngArchiveFilename, inspectArtifactRender, inspectionToModelPayload, nameArtifactPngFiles, renderArtifactPdf, renderArtifactPngFiles, zipArtifactPngFiles, } from '../services/artifact-render-export.js';
+import { artifactLibrarySourcesForBundle, artifactPagedSource } 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\n\n' +
+    'When the user refers to "this", "the selected frame/slide/element", or otherwise ' +
+    'points at something in an artifact they are viewing, call get_current_selection ' +
+    '(repo + entity_id of that artifact) FIRST to learn which frame they mean, then target it.';
+/**
+ * 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) }] };
@@ -21,38 +103,308 @@ 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;
+}
+/**
+ * Robustly resolve an entity from a search/list result so any hit re-opens
+ * without the caller guessing the physical type: explicit `path` wins; else try
+ * the supplied `entity_type`; on a miss (wrong/legacy type — e.g. an `event`
+ * whose `type` field is "meeting") fall back to id-only resolution. Shared by
+ * get_entity and delete_entity so the resolution can't drift between read and
+ * delete. Throws when nothing resolves (caller wraps via fail()).
+ */
+function resolveEntityRef(graph, ref) {
+    if (ref.path)
+        return graph.getByPath(ref.path);
+    if (ref.entity_type) {
+        try {
+            return graph.get(ref.entity_type, ref.entity_id);
+        }
+        catch {
+            return graph.getById(ref.entity_id);
+        }
+    }
+    return graph.getById(ref.entity_id);
+}
+/**
+ * MCP clients sometimes serialize an object/array tool argument to a JSON
+ * STRING. For the artifact args that carry structured payloads — an
+ * ArtifactBundle or a patch-ops array — a perfectly valid payload then arrives
+ * as a string. Used as a `z.preprocess` step on the REGISTERED schema (NOT only
+ * in the handler): the MCP SDK validates `arguments` against the registered
+ * inputSchema BEFORE the handler runs (server/mcp.js `safeParseAsync`), so a
+ * `z.array(z.unknown())` ops field would reject a stringified array before the
+ * handler could coerce it. Preprocessing on the schema fixes both the SDK
+ * pre-validation and the handler's own re-parse from ONE place.
+ *
+ * Parse a string value back to JSON so the inner schema sees the structured
+ * value; a non-string value (already an object/array) and a string that is NOT
+ * valid JSON both pass through unchanged so the inner schema / downstream
+ * validator still emits the real error. Deliberately scoped to these artifact
+ * args — NOT create_entity/update_entity.data, where `z.record` already rejects
+ * a string and blanket coercion could mangle an object whose own field value is
+ * a JSON-looking string.
+ */
+function coerceJsonArg(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
 }
+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) {
-    // Entity types the MCP surface may create. Matches the agent's allowlist so a
-    // workspace looks identical across the main app and MCP clients. See
-    // src/core/launch-entity-types.ts for policy rationale.
+export function registerTools(server, wm, authService, ctx) {
+    const { user, wsHub, apiTokenName, commentService, selectionStore } = 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 folders in the Studiograph workspace' }, async () => ok(wm.getAllRepoConfigs()));
+    reg('list_repos', { description: 'List folders in the Studiograph workspace that you have access to' }, 
+    // Archived folders are hidden from the inventory (parity with the sidebar +
+    // agent folder list); they stay reachable by name for unarchive.
+    async () => ok(getAccessibleRepos(user, wm, authService).filter(r => !isArchivedRepo(r))));
+    // ── 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('Folder name — omit to list across all folders'),
-        entity_type: z.string().optional().describe('Entity type filter (project, client, person, meeting…)'),
+        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 folder (or all folders). 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);
@@ -61,14 +413,88 @@ export function registerTools(server, wm, authService) {
     // ── get_entity ────────────────────────────────────────────────────────────
     const getEntitySchema = z.object({
         repo: z.string().describe('Folder name'),
-        entity_type: z.string().describe('Entity type (project, client, person…)'),
-        entity_id: z.string().describe('Entity ID (kebab-case slug)'),
+        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.'),
+    });
+    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 {
+            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 (shared with delete_entity).
+            const entity = resolveEntityRef(graph, { entity_type, entity_id, path });
+            // 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,
+                // Artifact entries: the staleness token for edits. Pass back to
+                // create_artifact as base_hash so an edit derived from this read
+                // fails loudly (instead of silently clobbering) if the artifact
+                // changed in between.
+                ...(entity.entityType === 'artifact' ? { artifact_hash: hashArtifactBody(content) } : {}),
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
     });
-    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);
+    // ── get_entity_schema ─────────────────────────────────────────────────────
+    const getEntitySchemaSchema = z.object({
+        entity_type: z.string().describe('Entity type (canonical or workspace custom)'),
+    });
+    reg('get_entity_schema', {
+        description: 'Get the authoritative schema for an entry type before creating or editing one. Returns each ' +
+            'frontmatter field with its type, whether it is optional, the Zod description, the full enum value ' +
+            'list when applicable, and any default — call this before writing enum-shaped fields (stage, status, ' +
+            'category, priority, etc.) since the validator only accepts the listed `enum` values. Also returns ' +
+            '`bodyTemplate`: a suggested markdown section scaffold for the entry body (e.g. a deal\'s ' +
+            '"## Opportunity / ## Scope / ## Next Actions / ## Notes"). The body template is a GUIDELINE, not a ' +
+            'requirement — use it, adapt it, add or drop sections, or ignore it entirely based on what the ' +
+            'specific entry needs.',
+        inputSchema: getEntitySchemaSchema,
+    }, async (args) => {
+        const { entity_type } = getEntitySchemaSchema.parse(args);
         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 });
+            const registry = wm.getSchemaRegistry();
+            const knownTypes = new Set(registry.getAllTypes());
+            if (!knownTypes.has(entity_type)) {
+                return fail(new Error(`Unknown entity type: ${entity_type}. Known types: ${[...knownTypes].sort().join(', ')}`));
+            }
+            const fields = describeZodObject(registry.getSchema(entity_type));
+            // Suggested body scaffold (guideline). null for types with no template
+            // (e.g. note, dataset) — omit the key rather than emit null.
+            const bodyTemplate = registry.getBodyTemplate(entity_type);
+            return ok({
+                entityType: entity_type,
+                fields,
+                ...(bodyTemplate != null ? { bodyTemplate } : {}),
+            });
         }
         catch (err) {
             return fail(err);
@@ -81,11 +507,20 @@ export function registerTools(server, wm, authService) {
         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 folders', 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);
@@ -102,49 +537,1476 @@ export function registerTools(server, wm, authService) {
         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). ' +
+            'EVERY type requires `name` — the display title of the entry. For content types ' +
+            '(note, document, deck, event) `name` IS the title; pass it as `name` (`title` is also ' +
+            'accepted and normalized to `name`). ' +
+            '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. Do NOT start the body with an H1 (`# Title`) or use `#` anywhere — the entry already has a title (from frontmatter) rendered above the body; a `#` heading just duplicates it. Any headings begin at `##` (H2). 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 folder. 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`. ' +
+            'Do NOT use this tool to make an `artifact` (Artifact Canvas: slide decks, documents, graphics, ' +
+            'prototypes, diagrams) — use create_artifact instead. An `artifact` body must be ArtifactBundle JSON, ' +
+            'never markdown; create_artifact assembles and validates it for you. For raw markdown/prose, use a ' +
+            '`document` entry.',
+        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 = isLaunchVisibleEntityType(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 available for creation.${hint}`));
+            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({
+            assertEntityRefs(wm, entity_type, data, { userExists: (id) => !!authService.findUserById(Number(id)) });
+        }
+        catch (err) {
+            return fail(err);
+        }
+        const actor = buildActor(user);
+        let options;
+        try {
+            // Rejects a markdown/malformed body on an `artifact` entry (ArtifactBodyError)
+            // with guidance to use create_artifact — see prepareCreatePayload.
+            options = prepareCreatePayload({
                 entityType: entity_type,
                 entityId: entity_id,
                 data: data,
                 content,
-            });
-            return ok({ success: true, id: entity.id, type: entity.entityType });
+                folderPath: effectiveFolder || undefined,
+            }, actor);
         }
         catch (err) {
             return fail(err);
         }
+        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('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). Set a field to null to DELETE it (omitting a key leaves the existing value untouched).'),
+        content: z.string().optional().describe('New markdown body content (replaces the entire body). Do NOT start the body with an H1 (`# Title`) or use `#` anywhere — the entry already has a title (from frontmatter) rendered above the body; a `#` heading just duplicates it. Any headings begin at `##` (H2). 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.'),
     });
-    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('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. ' +
+            'To edit an `artifact` entry, do NOT write its body here (it is ArtifactBundle JSON, not markdown) — ' +
+            'call read_artifact then create_artifact. Frontmatter-only `data` edits to an artifact are fine.',
+        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);
+        let options;
         try {
-            const entity = await wm.getGraph(repo).update({
+            // Rejects a markdown/malformed body on an `artifact` entry (ArtifactBodyError)
+            // with guidance to use create_artifact — see prepareUpdatePayload.
+            options = prepareUpdatePayload({
                 entityType: entity_type,
                 entityId: entity_id,
                 data: data,
                 content,
+            }, actor);
+        }
+        catch (err) {
+            return fail(err);
+        }
+        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.preprocess(coerceJsonArg, z.unknown()).nonoptional().describe('ArtifactBundle object with artifactId, title, and frames: an ordered, non-empty array of { id, title?, layout (slides|pages|artboard|app|whiteboard), geometry ({ width, height }), content (the frame\'s HTML fragment), background? (neutral|transparent|a safe CSS color or gradient — set it to the design\'s real surface so a dark/colored frame does not render white) }. A "pages" (document) frame also accepts furniture ({ header?: {first?,middle?,last?}, footer?: {first?,middle?,last?} } — per-page running header/footer for letterhead) and pageMargins ({ top?, right?, bottom?, left? } in px). Optional bundle-level: shared ({ files, head }), tokens (CSS design variables), libraries (three, d3, motion).'),
+        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.'),
+        base_hash: z.string().optional().describe('REQUIRED when updating an artifact that already has content: the artifact_hash returned by get_entity for that entry. It detects that the artifact changed since you read it (your edit would silently overwrite someone else\'s) and fails with guidance instead of clobbering. Optional only when filling a blank artifact.'),
+        replace: z.boolean().optional().describe('Set true to intentionally overwrite a non-blank artifact with a blank bundle (clearing it). Without it, blanking a populated artifact is refused. base_hash from get_entity is still required.'),
+    });
+    reg('create_artifact', {
+        description: 'Create or update a persisted sandboxed Artifact Canvas entry from an HTML/CSS/JS ArtifactBundle. ' +
+            'Use this for DESIGNED, laid-out, visual outputs: slide decks, social graphics, prototypes, diagrams, ' +
+            'small interactive tools, artifacts using curated local libraries (three, d3, motion), and documents the ' +
+            'user wants DESIGNED on letterhead / as a formatted PDF. A plain prose draft of a proposal, contract, memo, ' +
+            'or report is a "document" ENTRY (create_entity), NOT an artifact — build a document artifact only when the ' +
+            'user signals a designed/print output; when ambiguous, prefer the document entry or ask. ' +
+            'Match the artifact TYPE to its frame structure: a slide DECK is N "slides" frames, one per slide ' +
+            '(e.g. 1280×720); a designed DOCUMENT — a letter, contract, proposal, or report laid out on letterhead — ' +
+            'is ONE "pages" frame whose content is the WHOLE document body at a fixed page size (US-Letter 816×1056; ' +
+            'also Legal 816×1344, Tabloid 1056×1632, A4 794×1123, A3 1123×1587, A5 559×794): the platform flows the ' +
+            'text across as many pages as needed, numbers them, and exports a real multi-page PDF — so do NOT set a ' +
+            'document\'s height to "auto", do NOT split it into one frame per page, and do NOT build a page grid ' +
+            'inside an "app"/"artboard" frame. Style it as rich HTML/CSS; for repeating letterhead/headers/footers use ' +
+            'standard CSS Paged Media in a shared CSS file (@page margin boxes + position:running(); a full-bleed ' +
+            'branded band runs edge-to-edge with side page margins 0 + a padded body), which overrides the platform ' +
+            'defaults. (The "furniture"/"pageMargins" frame fields are an optional shortcut for a plain inset ' +
+            'header/footer.) A GRAPHIC, poster, or diagram is ' +
+            '"artboard" frame(s) at a fixed size; an APP or prototype is a single "app" frame with fill geometry; a ' +
+            'WHITEBOARD is a single "whiteboard" frame. Never hand-roll a stepper, filmstrip, pagination, or page ' +
+            'grid inside one frame. ' +
+            'Validates the bundle, writes an artifact graph entry, commits to git, and ' +
+            'broadcasts the same live entity_change event as the web agent. ' +
+            'To EDIT an existing artifact: call get_entity first, modify the full bundle from its content, and pass ' +
+            'its artifact_hash back as base_hash (REQUIRED when the artifact already has content) — a concurrent ' +
+            'change is then detected instead of silently overwritten. ' +
+            'The result reports the resolved frame structure (manifest) and any warnings — check the frame count and ' +
+            'per-frame layouts against what the user asked for (a deck is N "slides" frames, not one "app" frame) and ' +
+            'fix it before responding.',
+        inputSchema: createArtifactSchema,
+    }, async (args) => {
+        const { repo, bundle: rawBundle, entity_id, folder_path, base_hash, replace } = 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}"`));
+        }
+        // base_hash asserts "this is an edit of an entry I read" — without
+        // entity_id the id-collision loop below would mint a `-N` DUPLICATE and
+        // silently ignore the hash, forking the artifact instead of updating it.
+        if (base_hash && !entity_id) {
+            return fail(new Error('base_hash implies updating an existing artifact, but entity_id is missing — pass the entity_id you read with get_entity, or omit base_hash to create a new artifact.'));
+        }
+        const graph = wm.getGraph(repo);
+        const actor = buildActor(user);
+        return withAgentActivity(repo, entity_id ? 'editing' : 'creating', async () => {
+            try {
+                // The ArtifactStore owns the whole write lifecycle (validate, identity,
+                // blank-stub adoption, content-equality idempotency, the OCC rules, the
+                // diagnosed write). The MCP surface stays thin: access (above), the
+                // response envelope, and the change broadcast.
+                const result = await new ArtifactStore(graph).write({
+                    bundle: rawBundle,
+                    actor,
+                    // MCP entity_id is create-or-update-AT-id: a caller picks the id and
+                    // expects it created if absent (unless base_hash asserts an edit).
+                    target: entity_id ? { entityId: entity_id, createIfMissing: true } : null,
+                    baseHash: base_hash,
+                    replace,
+                    folderPath: folder_path || undefined,
+                });
+                const entity = result.entity;
+                // Broadcast only when something actually changed. `noop` covers BOTH the
+                // content-equality short-circuit (no write) AND a diagnosedUpdate that
+                // ran but changed nothing — neither should emit a phantom change. Matches
+                // the chat surface's `!location.noop` gate.
+                if (!result.noop)
+                    emitEntityChange(result.action, repo, entity.entityType, entity.id);
+                return ok({
+                    success: true,
+                    action: result.action,
+                    id: result.entityId,
+                    type: entity.entityType,
+                    repo,
+                    path: relPathOf(entity.path, graph.getRepoPath()),
+                    commit: graph.getGitService()?.getHeadCommit() ?? null,
+                    noop: result.noop,
+                    // Return-rich (P4.3): the resolved frame structure + warnings, built
+                    // from the bundle ArtifactStore actually persisted, so the agent can
+                    // self-verify (e.g. a deck that collapsed to one frame) without a
+                    // render. Structure-only (no per-frame source) → persists safely.
+                    ...summarizeArtifactWrite(result.bundle),
+                    ...(result.diagnostics ? {
+                        frontmatter_changed: result.diagnostics.frontmatterChanged,
+                        content_changed: result.diagnostics.contentChanged,
+                        broadcast: result.diagnostics.broadcast,
+                    } : {}),
+                });
+            }
+            catch (err) {
+                if (err instanceof ArtifactWriteError) {
+                    switch (err.code) {
+                        case 'needs-base-hash':
+                            return fail(new Error('This artifact already has content — call get_entity first and pass its artifact_hash as base_hash, so a concurrent change is detected instead of silently overwritten. (Intentionally clearing it requires base_hash plus replace: true.)'));
+                        case 'stale':
+                            return fail(new Error('Artifact changed since you read it (base_hash mismatch). Call get_entity again, re-apply your change to the current source, then retry with the new artifact_hash.'));
+                        case 'blank-overwrite':
+                            return fail(new Error('The new bundle is blank but this artifact has content. Pass replace: true only if you intend to clear it.'));
+                        case 'deleted':
+                            return fail(new Error(`Artifact "${entity_id}" no longer exists in "${repo}" (deleted or moved since you read it). Re-check with get_entity or search_entities before retrying — refusing to recreate it from a possibly stale copy.`));
+                        default:
+                            return fail(new Error(err.message));
+                    }
+                }
+                return fail(err);
+            }
+        });
+    });
+    const patchArtifactSchema = z.object({
+        repo: z.string().describe('Folder containing the persisted artifact entry to patch.'),
+        entity_id: z.string().describe('Persisted artifact entity id to patch.'),
+        base_hash: z.string().describe('REQUIRED: the artifact_hash returned by get_entity for the version your ops target. The patch is rejected (re-read and retry) if the artifact changed since that read.'),
+        ops: z.preprocess(coerceJsonArg, z.array(z.unknown())).nonoptional().describe('Ordered, non-empty list of patch operations applied in order to the current bundle. Each is an object with an `op` field: '
+            + 'set_frame_content { frameId, content } — replace a frame\'s HTML; '
+            + 'patch_frame_content { frameId, find, replace, expectedCount? } — replace every occurrence of an exact substring within ONE frame (cannot touch other frames); '
+            + 'set_frame_meta { frameId, title?, layout?, geometry?, background? } — empty title/background clears it; '
+            + 'add_frame { frame, atIndex? } — insert a new frame ({ id, layout, geometry, content, ... }); '
+            + 'remove_frame { frameId }; '
+            + 'reorder_frames { order } — order is a permutation of all current frame ids; '
+            + 'set_shared_file { path, content } / remove_shared_file { path }; '
+            + 'set_tokens { tokens } — replace the design-variable map.'),
+    });
+    reg('patch_artifact', {
+        description: 'Edit ONE frame (or a shared file / the token map) of an existing artifact WITHOUT re-emitting the whole bundle — the efficient way to revise a large artifact. To find which frame to edit cheaply, call get_artifact_manifest (frame ids + keyText + the artifact_hash, no full source). Pass that hash as base_hash plus an ordered list of ops; the ops apply in order, the result is validated, and it is saved as one revision with the same concurrency safety as create_artifact. Any frame you add must follow the same per-type structure as create_artifact (a document is ONE "pages" frame the platform flows across pages — never one frame per page, never a page grid inside an "app"/"artboard" frame). For a whole-bundle rewrite or a new artifact, use create_artifact. The result reports the resolved frame structure (manifest) and any warnings — check them against the user\'s intent and fix before responding.',
+        inputSchema: patchArtifactSchema,
+    }, async (args) => {
+        const { repo, entity_id, base_hash, ops } = patchArtifactSchema.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 graph = wm.getGraph(repo);
+        const actor = buildActor(user);
+        return withAgentActivity(repo, 'editing', async () => {
+            try {
+                // Friendly not-found before the shared runner (which throws a generic
+                // error from graph.get). The runner then loads the live body, verifies
+                // base_hash, applies the ops, and persists via ArtifactStore.write —
+                // the SAME path the web canvas's REST patch endpoint uses (P5).
+                try {
+                    graph.get('artifact', entity_id);
+                }
+                catch {
+                    return fail(new Error(`Artifact "${entity_id}" not found in "${repo}". Check with get_entity or search_entities first.`));
+                }
+                let applied;
+                let result;
+                try {
+                    ({ outcome: result, applied } = await patchPersistedArtifact({
+                        graph,
+                        actor,
+                        entityId: entity_id,
+                        baseHash: base_hash,
+                        ops,
+                        label: `Artifact ${repo}/${entity_id}`,
+                    }));
+                }
+                catch (err) {
+                    if (err instanceof ArtifactPatchBaseHashError) {
+                        return fail(new Error('Artifact changed since you read it (base_hash mismatch). Call get_entity again, recompute your ops against the current source, then retry with the new artifact_hash.'));
+                    }
+                    if (err instanceof ArtifactPatchError)
+                        return fail(err);
+                    throw err;
+                }
+                const written = result.entity;
+                if (!result.noop)
+                    emitEntityChange(result.action, repo, written.entityType, written.id);
+                return ok({
+                    success: true,
+                    action: result.action,
+                    id: result.entityId,
+                    type: written.entityType,
+                    repo,
+                    path: relPathOf(written.path, graph.getRepoPath()),
+                    commit: graph.getGitService()?.getHeadCommit() ?? null,
+                    noop: result.noop,
+                    changed_frame_ids: applied.changedFrameIds,
+                    removed_frame_ids: applied.removedFrameIds,
+                    reordered: applied.reordered,
+                    // Return-rich (P4.3): the change summary PLUS the full resolved
+                    // structure (manifest, with frameCount) + warnings, so the agent
+                    // verifies the patched result matches intent in the same turn.
+                    ...summarizeArtifactWrite(result.bundle),
+                });
+            }
+            catch (err) {
+                if (err instanceof ArtifactWriteError) {
+                    switch (err.code) {
+                        case 'needs-base-hash':
+                            return fail(new Error('This artifact already has content — call get_entity first and pass its artifact_hash as base_hash so a concurrent change is detected instead of silently overwritten.'));
+                        case 'stale':
+                            return fail(new Error('Artifact changed since you read it (base_hash mismatch). Call get_entity again, recompute your ops against the current source, then retry with the new artifact_hash.'));
+                        case 'blank-overwrite':
+                            return fail(new Error('These ops would blank the artifact. patch_artifact will not clear all content; rewrite it with create_artifact (replace: true) if that is intended.'));
+                        case 'deleted':
+                            return fail(new Error(`Artifact "${entity_id}" no longer exists in "${repo}" (deleted or moved since you read it).`));
+                        default:
+                            return fail(new Error(err.message));
+                    }
+                }
+                return fail(err);
+            }
+        });
+    });
+    const getArtifactManifestSchema = z.object({
+        repo: z.string().describe('Folder containing the persisted artifact entry.'),
+        entity_id: z.string().describe('Persisted artifact entity id.'),
+        frame_id: z.string().optional().describe('If set, also include this one frame\'s full HTML content (for a targeted patch_artifact). Errors if no frame has this id.'),
+    });
+    reg('get_artifact_manifest', {
+        description: 'Read an artifact\'s STRUCTURE cheaply, without pulling its full source — the fast way to find which frame to edit before patch_artifact. Returns each frame\'s index, id, title, layout, geometry, a short keyText snippet, contentChars, plus the artifact_hash (pass it to patch_artifact as base_hash). No browser, always available. Pass frame_id to also get that one frame\'s full content. For the whole bundle use get_entity; for a visual render use inspect_artifact.',
+        inputSchema: getArtifactManifestSchema,
+    }, async (args) => {
+        const { repo, entity_id, frame_id } = getArtifactManifestSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        try {
+            const graph = wm.getGraph(repo);
+            let entity;
+            try {
+                entity = graph.get('artifact', entity_id);
+            }
+            catch {
+                return fail(new Error(`Artifact "${entity_id}" not found in "${repo}".`));
+            }
+            // Live editor body preferred over disk (matches get_entity / patch_artifact),
+            // so the manifest + hash reflect what the user currently sees.
+            const body = graph.getLiveBody('artifact', entity_id) ?? entity.document.content;
+            const bundle = parseArtifactBundleFromBody(body, `Artifact ${repo}/${entity_id}`);
+            const manifest = buildArtifactManifest(bundle, { frameId: frame_id });
+            return ok({ success: true, artifact_hash: hashArtifactBody(body), ...manifest });
+        }
+        catch (err) {
+            // Unknown frame_id or unparseable body → clear recoverable error.
+            return fail(err);
+        }
+    });
+    const getCurrentSelectionSchema = z.object({
+        repo: z.string().describe('Folder containing the artifact the user is viewing.'),
+        entity_id: z.string().describe('Persisted artifact entity id the user is viewing.'),
+    });
+    reg('get_current_selection', {
+        description: 'Return the frame/element the user currently has SELECTED in the artifact canvas (for this user + artifact), so you can act on "this"/"the selected frame" without them describing it. '
+            + 'Returns selection.targets[]: each has a `frameId` (the frame to target with patch_artifact — e.g. "cover") plus selector/text/tagName to recognize the specific element within it. '
+            + '(`primaryTargetId` is an element-level id like "cover::h1", NOT a frame id — use `targets[].frameId` for patch_artifact.) '
+            + 'Returns selection: null when nothing is selected (or the selection has gone stale). '
+            + 'Only the live web app pushes selections, so this is empty unless the user has an artifact open and has clicked something.',
+        inputSchema: getCurrentSelectionSchema,
+    }, async (args) => {
+        const { repo, entity_id } = getCurrentSelectionSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        // No store on this transport (standalone stdio process) → no shared UI
+        // selection to read; report cleanly rather than erroring.
+        const selection = selectionStore?.get(String(user.id), repo, entity_id) ?? null;
+        return ok({ success: true, repo, entity_id, selection });
+    });
+    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.preprocess(coerceJsonArg, z.unknown()).optional().describe('ArtifactBundle object to inspect without saving. If omitted, repo + entity_id are loaded from the graph.'),
+        context: z.enum(['editor', 'present']).optional().describe('"editor" lays every frame out in the canvas grid (all frames visible — the default); "present" renders the present stage (the first frame full-bleed).'),
+        frame_indexes: z.array(z.number()).optional().describe('Specific zero-based frame/page indexes to screenshot.'),
+        max_frames: z.number().optional().describe('Maximum number of individual frames/pages 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.'),
+    });
+    reg('inspect_artifact', {
+        description: 'Use Playwright to visually inspect an ArtifactBundle or persisted artifact entry. Returns a page screenshot, ' +
+            'frame/page/slide metadata (including measured rendered height), optional individual frame screenshots, console messages, page errors, and failed requests. ' +
+            'Also reports framesOverflowing — frames whose content is taller than their declared height and is therefore CROPPED from view (set geometry.height to "auto" or split the content to fix; a "pages" document frame is never listed — it flows/paginates instead of cropping, so never set a document to height "auto"). ' +
+            'Use this after creating or revising artifacts — especially large or content-driven ones — to verify layout, catch cropped frames, and check individual slides/pages.',
+        inputSchema: inspectArtifactSchema,
+    }, async (args) => {
+        const parsed = inspectArtifactSchema.parse(args);
+        let bundle;
+        try {
+            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}`);
+            }
+            // With a base_url + a persisted target, mint a bundle-scoped asset token
+            // so the headless render's `/api/assets/...` image loads resolve
+            // (token-mode auth) instead of aborting to the broken-image placeholder.
+            const assetToken = (parsed.base_url && parsed.repo && parsed.entity_id)
+                ? mintArtifactAssetTokenForBundle(wm, authService, parsed.repo, parsed.entity_id, bundle, String(user.id)).token
+                : undefined;
+            const options = {
+                context: parsed.context,
+                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,
+                assetToken,
+            };
+            // Emit screenshots as real MCP image content blocks (vision) + a
+            // base64-free metadata text block, mirroring the in-app agent tool: the
+            // client model sees the frames for ~1.6k tokens each instead of ~300k of
+            // undecoded base64 text.
+            const { metadata, images } = inspectionToModelPayload(await inspectArtifactRender(bundle, options));
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify({ success: true, inspection: metadata }, null, 2) },
+                    ...images.map((img) => ({ type: 'image', data: img.data, mimeType: img.mimeType })),
+                ],
+            };
+        }
+        catch (err) {
+            // Browser unavailable (still installing on a fresh deploy, or not
+            // installed): degrade to a browser-free structural summary straight from
+            // the frame model so the agent keeps a feedback loop.
+            if (err instanceof ArtifactRenderExportUnavailableError && bundle) {
+                return {
+                    content: [
+                        { type: 'text', text: JSON.stringify({
+                                success: true,
+                                degraded: true,
+                                inspection: buildArtifactManifest(bundle),
+                                note: `VISUAL INSPECTION UNAVAILABLE — the browser render runtime could not run (${err.message}). This is a STRUCTURAL-ONLY summary from the frame model: it CANNOT measure rendered height, detect cropped/overflowing frames, or verify visual layout. You are effectively blind to how this renders — do NOT report the artifact as visually verified or claim its layout/pagination is correct.`,
+                            }, null, 2) },
+                    ],
+                };
+            }
+            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; workspace images ' +
+            'render as labeled placeholders in it (the text export cannot carry asset files — use PNG/PDF for faithful ' +
+            'images, or the app’s HTML export for a self-contained zip). ' +
+            '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') {
+                // MCP html export returns TEXT — it can't carry the asset zip the web
+                // export route ships — so workspace-asset refs render as labeled
+                // placeholders under the export's no-network CSP (D11b: a downloaded
+                // file is never absolutized back to the workspace and never phones
+                // home). Pixel-faithful output with images = png/pdf below; the
+                // self-contained zip = the web export endpoint.
+                bytes = buildFrameDocument(bundle, {
+                    host: 'none',
+                    interactive: true,
+                    librarySources: artifactLibrarySourcesForBundle(bundle),
+                    ...(bundleNeedsPagination(bundle) ? { pagedSource: artifactPagedSource() } : {}),
+                    assets: { mode: 'relative', bundledKeys: new Set() },
+                });
+            }
+            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),
+            });
+        }
+        catch (err) {
+            if (err instanceof ArtifactRenderInstallingError) {
+                return fail(err); // transient: message already says it's installing + retry
+            }
+            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. ' +
+            'Multiple edits to the SAME entry must be SEQUENTIAL — each patch rewrites the body, so parallel calls ' +
+            'to one entry conflict by design (optimistic concurrency); issue them one at a time, each after the ' +
+            'previous succeeds. Patches to different entries may run in parallel. ' +
+            'Do NOT patch an `artifact` body — it is ArtifactBundle JSON; a substring edit corrupts it. ' +
+            'Edit one frame via patch_artifact (get_entity first for its artifact_hash), or rewrite the whole bundle with create_artifact.',
+        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 (entity_type === 'artifact') {
+            // An artifact body is ArtifactBundle JSON; a substring find/replace that
+            // happens to keep the JSON valid would still be the wrong edit route (the
+            // write-time validity guard only catches a corrupt result). Reject up
+            // front and steer to the frame-addressable path.
+            return fail(new Error('Do not patch an `artifact` body with patch_entity — it is ArtifactBundle JSON, not markdown. Read it with get_entity (for its artifact_hash) and edit one frame via patch_artifact, or rewrite the whole bundle with create_artifact.'));
+        }
+        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 actor = buildActor(user);
+                // Shared read-modify-write-retry (optimistic concurrency, disk-hash
+                // baseRevision, parallel-patch compose) — see applyPatchEntity.
+                const outcome = await applyPatchEntity(graph, actor, {
+                    entityType: entity_type,
+                    entityId: entity_id,
+                    find,
+                    replace,
+                    expectedCount: expected_count,
+                });
+                if (outcome.status === 'no_match') {
+                    return ok({ success: false, code: 'NO_MATCH', message: `\`find\` substring not present in ${entity_type}/${entity_id}.` });
+                }
+                if (outcome.status === 'ambiguous') {
+                    return ok({ success: false, code: 'AMBIGUOUS_MATCH', occurrences: outcome.occurrences, message: `Expected ${expected_count} occurrence(s) of \`find\`, found ${outcome.occurrences}.` });
+                }
+                if (outcome.status === 'conflict') {
+                    return ok({ success: false, code: 'WRITE_CONFLICT', message: `Could not apply patch to ${entity_type}/${entity_id}: the entry kept changing under concurrent writes after ${outcome.attempts} attempts. Retry, or avoid editing the same entry in parallel.` });
+                }
+                const updated = outcome.entity;
+                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: outcome.occurrences, frontmatter_changed: outcome.frontmatter_changed, content_changed: outcome.content_changed, noop: outcome.noop, broadcast: outcome.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().optional().describe('Folder name. OMIT to list assets across ALL folders you can access, including the workspace-wide shared "Assets" store (where Studio-level shared images like logos live).'),
+        name: z.string().optional().describe('Filter to assets whose filename contains this text (case-insensitive). Use with no `repo` to find a shared asset by name across the workspace.'),
+        entity_type: z.string().optional().describe("Filter by owner kind. Assets are folder-homed (owner is 'folder'/'workspace'), so per-ENTRY filtering only matches legacy pre-migration rows — to find what an entry embeds, read its body instead."),
+        entity_id: z.string().optional().describe("Filter by owner id (the folder name for folder-homed assets; an entry id only for legacy pre-migration rows)"),
+    });
+    reg('list_assets', {
+        description: 'List assets (images, PDFs, files) already uploaded. Pass `repo` for one folder, or OMIT `repo` to list ' +
+            'across every folder you can access — INCLUDING the workspace-wide shared "Assets" store (the only way to ' +
+            'discover Studio-level shared images). Each result includes a ready-to-paste `embed` — standard markdown ' +
+            '`![name](url)` — that renders in the editor, plus the owning `repo`. 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 `name` (filename contains), `entity_type`, and/or `entity_id`.',
+        inputSchema: listAssetsSchema,
+    }, async (args) => {
+        const { repo, name, entity_type, entity_id } = listAssetsSchema.parse(args);
+        const nameNeedle = name?.trim().toLowerCase();
+        // Workspace scope: omit `repo` → every accessible folder, including the
+        // workspace-wide shared store (getAccessibleRepos returns workspace_wide
+        // repos for any member). Reuses the same listWorkspaceAssets primitive the
+        // /api/workspace/assets/manager endpoint uses, so shapes can't drift.
+        let assets;
+        if (repo === undefined) {
+            const accessible = getAccessibleRepos(user, wm, authService).map(r => r.name);
+            assets = await listWorkspaceAssets(accessible, wm);
+        }
+        else {
+            if (!hasRepoAccess(user, repo, wm, authService))
+                return notFound(repo);
+            try {
+                wm.getGraph(repo);
+            }
+            catch {
+                return notFound(repo);
+            }
+            // Tag with `repo` so single- and workspace-scope results share one shape.
+            assets = (await listRepoAssets(repo, wm)).map(a => ({ ...a, repo }));
+        }
+        if (entity_type)
+            assets = assets.filter(a => a.entityType === entity_type);
+        if (entity_id)
+            assets = assets.filter(a => a.entityId === entity_id);
+        if (nameNeedle)
+            assets = assets.filter(a => a.filename.toLowerCase().includes(nameNeedle));
+        return ok({
+            repo: repo ?? null,
+            scope: repo === undefined ? 'workspace' : 'repo',
+            count: assets.length,
+            assets: assets.map(a => ({
+                asset_id: a.assetId,
+                filename: a.filename,
+                mime_type: a.contentType,
+                repo: a.repo,
+                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`'));
+        }
+        // The URL's last segment is percent-encoded (encodeAssetFilename); decode
+        // it for the human-facing alt text (the embed keeps the original encoded
+        // url). Malformed `%` → keep raw rather than throw.
+        const altSegment = (url.split('/').pop() || 'asset').split('?')[0];
+        let derivedAlt = altSegment;
+        try {
+            derivedAlt = decodeURIComponent(altSegment);
+        }
+        catch { /* keep raw */ }
+        const filename = alt ?? derivedAlt;
+        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);
+                // createFolder is an idempotent ensure — report when the path already
+                // existed so the caller doesn't think it minted a new folder (and
+                // silently merge entries into the existing one).
+                const { alreadyExisted } = await graph.createFolder(path, undefined, actor, { displayName: display_name });
+                emitEntityChange('created', repo, '_folder', path);
+                return ok({
+                    success: true,
+                    alreadyExisted,
+                    repo,
+                    path,
+                    folder_path: path,
+                    message: alreadyExisted
+                        ? `Folder "${repo}/${path}" already exists — reusing it (nothing created).`
+                        : `Created folder "${repo}/${path}".`,
+                });
+            }
+            catch (err) {
+                return fail(err);
+            }
+        });
+    });
+    // ── delete_entity ─────────────────────────────────────────────────────────
+    //
+    // Delete an entry. Git-committed and recoverable from history
+    // (list_recent_deletions / restore_file). Embedded assets are KEPT — assets
+    // are folder-owned library citizens that entries only reference
+    // (assets-referenced-not-owned P1), so deleting an entry never destroys
+    // binaries. In the workspace_wide Assets store the per-asset uploader/owner
+    // delete gate still applies (D2). Robust resolution mirrors get_entity.
+    const deleteEntitySchema = z.object({
+        repo: z.string().describe('Folder name'),
+        entity_type: z.string().optional().describe('Canonical entity type (as returned by search/list `type`). Optional: when omitted or wrong, the entry 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. When given, resolves directly and ignores entity_type.'),
+    });
+    reg('delete_entity', {
+        description: 'Delete an entry. Git-committed and recoverable from history via list_recent_deletions / restore_file. ' +
+            'Embedded assets are NOT deleted — assets are folder-owned and only referenced by entries. ' +
+            'Robust resolution: pass type+id or path exactly as returned by search_entities/list_entities; a wrong or omitted type still resolves by id. ' +
+            'Destructive — only call on explicit user request.',
+        inputSchema: deleteEntitySchema,
+    }, async (args) => {
+        const { repo, entity_type, entity_id, path } = deleteEntitySchema.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 (!entity_id && !path)
+            return fail(new Error('delete_entity requires entity_id or path'));
+        const actor = buildActor(user);
+        return withAgentActivity(repo, 'deleting', async () => {
+            try {
+                const graph = wm.getGraph(repo);
+                // Resolve robustly (shared with get_entity): explicit path wins; else
+                // try the supplied type; on a miss fall back to id-only resolution.
+                const entity = resolveEntityRef(graph, { entity_type, entity_id, path });
+                const resolvedType = entity.entityType;
+                const resolvedId = entity.id;
+                // Workspace-Assets store gate (D2): in a workspace_wide folder only the
+                // uploader or a workspace owner may delete — folder-write is not enough.
+                const denial = assetDeleteDenial(wm.getAssetIndex(), wm.getRepoConfig(repo), user, repo, resolvedType, resolvedId);
+                if (denial)
+                    return fail(new Error(denial));
+                // Soft bridge-awareness: deleting a person linked to an auth account
+                // orphans that user. Don't block — surface a warning so the agent can
+                // tell the user (the Profile panel catches the orphan after).
+                let bridgeWarning;
+                if (resolvedType === 'person') {
+                    const handle = entity.data?.user_handle;
+                    if (typeof handle === 'string' && handle.length > 0) {
+                        bridgeWarning = `This record was linked to the "${handle}" account. Deleting it unlinks that user — their "My Tasks", @mentions, and assignments stop resolving until they link a new record.`;
+                    }
+                }
+                await graph.delete(resolvedType, resolvedId, undefined, actor);
+                emitEntityChange('deleted', repo, resolvedType, resolvedId);
+                return ok({
+                    success: true,
+                    repo,
+                    type: resolvedType,
+                    id: resolvedId,
+                    ...(bridgeWarning ? { warning: bridgeWarning } : {}),
+                });
+            }
+            catch (err) {
+                return fail(err);
+            }
+        });
+    });
+    // ── delete_subfolder ──────────────────────────────────────────────────────
+    //
+    // Delete a subfolder inside a folder/collection. Empty → delete; non-empty +
+    // recursive:false → refuse with a blast-radius payload; recursive:true →
+    // delete the folder + its entries. Deleted entries are git-recoverable; their
+    // referenced assets are kept (folder-owned). Distinct from archive_repo, which
+    // reversibly hides an entire top-level folder.
+    const deleteSubfolderSchema = z.object({
+        repo: z.string().describe('Folder name (collection) containing the subfolder'),
+        path: z.string().describe('Repo-relative POSIX path of the subfolder to delete (e.g. "Clients/Acme")'),
+        recursive: z.boolean().optional().describe('Delete the folder AND every entry/subfolder inside it. Defaults to false: a non-empty folder is REFUSED with a blast-radius payload (entriesDeleted, subfoldersDeleted) so you can confirm with the user first. NEVER pass true on the first attempt.'),
+    });
+    reg('delete_subfolder', {
+        description: 'Delete a subfolder inside a folder. Empty subfolders delete immediately. A non-empty subfolder is REFUSED unless recursive:true — the refusal returns the blast radius (entries + subfolders that would be removed) so you can confirm with the user before re-invoking. Deleted ENTRIES are git-recoverable; their referenced assets are kept. To remove a whole top-level folder, prefer archive_repo (reversible) — permanent folder deletion is web/human-only.',
+        inputSchema: deleteSubfolderSchema,
+    }, async (args) => {
+        const { repo, path, recursive } = deleteSubfolderSchema.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}"`));
+        }
+        // Workspace-Assets store gate (mirror the web route): a recursive delete in
+        // a workspace_wide store destroys every asset under the folder, bypassing
+        // the per-asset uploader/owner rule — restrict it to a workspace owner.
+        if (recursive === true && wm.getRepoConfig(repo)?.workspace_wide && !isWorkspaceOwner(user.role)) {
+            return fail(new Error('Only a workspace owner can recursively delete folders in the shared Assets store.'));
+        }
+        const actor = buildActor(user);
+        return withAgentActivity(repo, 'deleting', async () => {
+            try {
+                // Validate + normalize the path BEFORE the destructive call (don't
+                // rely on deleteFolder's internal check as the only guard against
+                // traversal/root/malformed paths). validateFolderPath throws
+                // InvalidFolderPathError for traversal and returns '' for the repo
+                // root, which deleteFolder also rejects. The throw lands in the catch
+                // below and surfaces as a fail() result. Pass the normalized path.
+                const normPath = validateFolderPath(path);
+                const graph = wm.getGraph(repo);
+                const result = await graph.deleteFolder(normPath, { recursive: recursive === true, user: actor });
+                emitEntityChange('deleted', repo, '_folder', normPath);
+                return ok({
+                    success: true,
+                    repo,
+                    path: normPath,
+                    entriesDeleted: result.entriesDeleted,
+                    subfoldersDeleted: result.subfoldersDeleted,
+                });
+            }
+            catch (err) {
+                // Surface the blast radius so the caller can confirm before retrying
+                // recursively (structured, like the web route's 409 body).
+                if (err?.code === 'FOLDER_NOT_EMPTY' && err.blastRadius) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    error: err.message,
+                                    code: 'FOLDER_NOT_EMPTY',
+                                    blast_radius: err.blastRadius,
+                                }, null, 2),
+                            }],
+                        isError: true,
+                    };
+                }
+                return fail(err);
+            }
+        });
+    });
+    // ── archive_repo / unarchive_repo ─────────────────────────────────────────
+    //
+    // Archive is a reversible, lossless, identity-preserving repo-level hide (a
+    // flag on the config, NOT a rename). An archived folder drops out of the
+    // sidebar, search, graph, and the agent inventory but keeps its entries,
+    // wikilinks, and assets. Agents/MCP may archive but may NEVER permanently
+    // delete a repo — permanent deletion stays a deliberate human action in the
+    // web UI. Folder admin or workspace owner only.
+    const archiveRepoSchema = z.object({
+        repo: z.string().describe('Folder name to archive'),
+    });
+    reg('archive_repo', {
+        description: 'Archive a folder — a reversible, lossless hide. The folder drops out of the sidebar, search, graph, and the agent folder inventory, but nothing is deleted (entries, wikilinks, and assets are preserved) and it can be restored with unarchive_repo. Use this instead of deleting a folder: permanent folder deletion is a human-only action in the web UI and is never available to agents. Requires folder admin or workspace owner.',
+        inputSchema: archiveRepoSchema,
+    }, async (args) => {
+        const { repo } = archiveRepoSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        if (!isFolderAdminOrOwner(user, repo, wm, authService)) {
+            return fail(new Error(`Archiving folder "${repo}" requires folder admin or workspace owner.`));
+        }
+        try {
+            const updated = await wm.setRepoArchived(repo, true, user.handle);
+            return ok({
+                success: true,
+                repo,
+                archived_at: updated.archived_at ?? null,
+                message: `Archived folder "${repo}". It's hidden from the workspace but fully recoverable — call unarchive_repo to restore it.`,
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    reg('unarchive_repo', {
+        description: 'Restore a previously archived folder so it reappears in the sidebar, search, graph, and the agent folder inventory. Requires folder admin or workspace owner.',
+        inputSchema: archiveRepoSchema,
+    }, async (args) => {
+        const { repo } = archiveRepoSchema.parse(args);
+        if (!hasRepoAccess(user, repo, wm, authService))
+            return notFound(repo);
+        if (!isFolderAdminOrOwner(user, repo, wm, authService)) {
+            return fail(new Error(`Unarchiving folder "${repo}" requires folder admin or workspace owner.`));
+        }
+        try {
+            const updated = await wm.setRepoArchived(repo, false, user.handle);
+            return ok({
+                success: true,
+                repo,
+                archived: isArchivedRepo(updated),
+                message: `Restored folder "${repo}".`,
             });
-            return ok({ success: true, id: entity.id, type: entity.entityType });
         }
         catch (err) {
             return fail(err);
@@ -156,11 +2018,19 @@ export function registerTools(server, wm, authService) {
         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);
@@ -174,17 +2044,35 @@ export function registerTools(server, wm, authService) {
         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);
         }
@@ -192,84 +2080,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