studiograph 1.3.48-next.21 → 1.3.48-next.211

package/dist/agent/tools/graph-tools.js

@@ -7,11 +7,20 @@
  * - Manage wikilinks
  * - Upload assets
  */
-import { Type as T } from '@sinclair/typebox';
+import { Type as T } from 'typebox';
 import { ENTITY_SCHEMAS } from '../../core/validation.js';
+import { describeZodObject } from '../../core/schema-registry.js';
 import { lintWorkspace } from '../../services/lint-service.js';
 import { findOrphans } from '../../services/orphan-service.js';
-import { isAdminOrOwner } from '../../services/auth-service.js';
+import * as access from '../../services/access-control.js';
+import { isCuratedEntityType } from '../../core/entity-types-catalog.js';
+import { getAgentAllowedEntityTypes } from '../prompts/entity-types-section.js';
+import { BridgeError, assertCanChangeUserHandle, validateUserHandleInPayload } from '../../services/user-person-bridge.js';
+import { buildActor, prepareCreatePayload, prepareUpdatePayload, diagnosedUpdate, DroppedAssetError, assertEntityRefs, EntityRefError, UnknownUserRefError, } from '../../services/entity-mutations.js';
+import { listRepoAssets } from '../../services/asset-listing.js';
+import { assetEmbed } from '../../core/embeds.js';
+import * as commentVirtualEntity from '../../services/comment-virtual-entity.js';
+import { promoteScratchFileToAssets, PromoteScratchError } from '../../services/scratch-asset-promote.js';
 /**
  * Helper to wrap tool results in AgentToolResult format
  */
@@ -31,139 +40,251 @@ function cleanData(data) {
     return rest;
 }
 /**
- * Per-request user context for collection access filtering.
- * When getCurrentUser returns a non-admin user, tools filter results
- * to only collections the user has been granted access to.
+ * Undo JSON-string escapes that sometimes leak into content when the LLM
+ * serializes markdown as a quoted string instead of raw text. Handles `\n`,
+ * `\t`, `\r`, `\"`, `\\` in a single pass so escape sequences aren't
+ * re-processed. Also strips stray surrounding quotes from a fully-quoted
+ * payload.
  */
-/** Check if a user can see a private repo (only the owner can). */
-function canSeePrivateRepo(repoConfig, user) {
-    if (!repoConfig?.private)
-        return true;
-    if (!user)
-        return !repoConfig.owner_id; // API key / open mode — only if no owner set
-    if (!repoConfig.owner_id)
-        return false; // Private without owner — hidden from all users
-    return user.id === repoConfig.owner_id;
-}
-/** Check if the current user is an admin. Returns an error result if not. */
-function adminOnly(getUser) {
-    const user = getUser();
-    if (!user)
-        return null; // API key / open mode → allow
-    if (isAdminOrOwner(user.role))
-        return null;
-    return 'This operation requires admin access.';
+function sanitizeLlmContent(content) {
+    if (!content)
+        return '';
+    const unescaped = content.replace(/\\([ntr"\\])/g, (_, c) => {
+        if (c === 'n')
+            return '\n';
+        if (c === 't')
+            return '\t';
+        if (c === 'r')
+            return '\r';
+        return c;
+    });
+    return unescaped.replace(/^"+|"+$/g, '');
 }
+/**
+ * Per-request user context for folder access filtering.
+ * When getCurrentUser returns a user, tools filter results to only
+ * folders the user is a member of (via folder_access).
+ */
 function getAccessibleRepoNames(workspaceManager, getCurrentUser, authService) {
     const user = getCurrentUser();
     if (!user)
         return null; // API key / open mode → no filtering
     if (!authService)
         return null;
-    const allRepos = workspaceManager.getAllRepoConfigs();
-    if (isAdminOrOwner(user.role)) {
-        // Admins/owners see all non-private + their own private repos
-        const hidden = allRepos.filter(r => !canSeePrivateRepo(r, user)).map(r => r.name);
-        if (hidden.length === 0)
-            return null; // No filtering needed
-        const visible = new Set(allRepos.filter(r => canSeePrivateRepo(r, user)).map(r => r.name));
-        return visible;
-    }
-    const allowed = authService.getUserCollections(user.id);
-    const visible = allRepos.filter(r => canSeePrivateRepo(r, user) && (r.private && r.owner_id === user.id || allowed.includes(r.name)));
-    return new Set(visible.map(r => r.name));
+    // Delegate to the shared helper so personal-folder restrictions and
+    // owner-on-shared-folder semantics apply consistently with the HTTP layer.
+    return new Set(access.getAccessibleRepos(user, workspaceManager, authService).map(r => r.name));
 }
 function canAccessRepo(repoName, workspaceManager, getCurrentUser, authService) {
     const user = getCurrentUser();
-    const repoConfig = workspaceManager.getRepoConfig(repoName);
-    if (!canSeePrivateRepo(repoConfig, user))
-        return false;
     if (!user)
         return true;
-    if (repoConfig?.private && repoConfig?.owner_id === user.id)
-        return true;
-    if (isAdminOrOwner(user.role))
-        return true;
     if (!authService)
         return true;
-    return authService.getUserCollections(user.id).includes(repoName);
+    return access.hasRepoAccess(user, repoName, workspaceManager, authService);
 }
-export function createGraphTools(workspaceManager, gitUser, workspacePath, onHighlight, onMutation, getCurrentUser, authService) {
+export function createGraphTools(workspaceManager, gitUser, workspacePath, onHighlight, onMutation, getCurrentUser, authService, 
+/**
+ * Called at the start (`enter`) and end (`leave`) of any mutation tool
+ * call. Surfaces the active-agent chip in the sidebar via the WS hub. The
+ * orchestrator wires this through to wsHub.handleAgentActivity.
+ */
+onAgentActivity, 
+/**
+ * Optional CommentService. When supplied, the generic read tools
+ * (`get_entity`, `list_entities`, `get_related`) dispatch the virtual
+ * `comment` entity type through the shared adapter — exactly as the MCP
+ * surface does. A graceful no-op when absent (stdio / tests), so comments
+ * simply don't appear rather than erroring.
+ */
+commentService, 
+/**
+ * Optional ChatSessionService. When supplied (web chat), enables
+ * `save_file_to_assets` to promote a conversation-scratch image into the
+ * curated asset library. A graceful no-op when absent (stdio / tests).
+ */
+chatSessionService, 
+/**
+ * Resolves the active turn's RAW client session id. Lets `save_file_to_assets`
+ * scope "this image" to the current conversation's scratch images rather than
+ * the user's other chats. Returns null outside a web chat turn.
+ */
+getActiveSessionId) {
     const getUser = getCurrentUser ?? (() => null);
     const authSvc = authService ?? null;
-    /** Resolve "private" or "entries" to the current user's actual private collection name. */
+    const commentSvc = commentService ?? null;
+    const chatSessionSvc = chatSessionService ?? null;
+    const getSessionId = getActiveSessionId ?? (() => null);
+    /**
+     * Resolve the identity to stamp on writes. If the tool call is running on
+     * behalf of a real user (chat / quick-capture from the web), credit them
+     * by their handle via the shared `buildActor` so MCP and agent surfaces
+     * produce byte-identical git authors for the same user. Fall back to the
+     * orchestrator-level gitUser for unauthenticated contexts (CLI, tests,
+     * server-only automations).
+     */
+    function effectiveGitUser() {
+        const user = getUser();
+        if (user?.handle)
+            return buildActor(user);
+        return gitUser;
+    }
+    /** Resolve "private" or "entries" to the current user's actual private folder name. */
     function resolvePrivateRepo(repoName) {
         if (repoName !== 'private' && repoName !== 'entries')
             return repoName;
         const user = getUser();
         if (!user)
             return repoName;
-        const privateRepo = workspaceManager.getUserPrivateRepo(user.id);
-        return privateRepo?.name ?? repoName;
+        const personalRepo = workspaceManager.getUserPersonalRepo(user.id);
+        return personalRepo?.name ?? repoName;
+    }
+    /**
+     * Eager skills are inlined into every system prompt for everyone with folder
+     * access. Creating one in a shared folder requires admin/owner so a rogue
+     * member can't bloat everyone's context. Eager skills in the user's own
+     * private folder are fine — they only bloat that user's own prompt.
+     * Returns an error string or null if the operation is allowed.
+     */
+    function checkEagerSkillPermission(entityType, data, repoName) {
+        if (entityType !== 'skill')
+            return null;
+        if (!data || data.loading !== 'eager')
+            return null;
+        const user = getUser();
+        if (!user)
+            return null; // non-authenticated contexts (CLI, tests) bypass
+        const personalRepo = workspaceManager.getUserPersonalRepo(user.id);
+        if (personalRepo && personalRepo.name === repoName)
+            return null;
+        if (authSvc?.isFolderAdmin(user.id, repoName))
+            return null;
+        if (user.role === 'owner')
+            return null;
+        return `Creating an eager skill in a shared folder requires folder admin or workspace owner. Save this skill to your private folder (repo: "private") or set loading to "on-demand".`;
+    }
+    // Compute the set of entity types the agent is allowed to create in this
+    // workspace: the full canonical catalog plus any custom types defined via
+    // schema_extensions. The launch-time allowlist was removed — the catalog
+    // now grows with the user via the New Entry picker's progressive disclosure.
+    const builtinTypeKeys = new Set(Object.keys(ENTITY_SCHEMAS));
+    const customWorkspaceTypes = workspaceManager.getSchemaRegistry().getAllTypes()
+        .filter(t => !builtinTypeKeys.has(t));
+    const agentAllowedTypes = getAgentAllowedEntityTypes(customWorkspaceTypes);
+    const agentAllowedTypeSet = new Set(agentAllowedTypes);
+    function rejectDisallowedCreateType(entityType) {
+        if (agentAllowedTypeSet.has(entityType))
+            return null;
+        const hint = isCuratedEntityType(entityType)
+            ? '' // shouldn't happen for any other curated type — they're all allowed
+            : ` Allowed types: ${agentAllowedTypes.join(', ')}.`;
+        return wrapToolResult({
+            success: false,
+            error: `Entry type "${entityType}" is not a known canonical or workspace custom type.${hint}`,
+        });
     }
     return [
         // Create entity
         {
             name: 'create_entity',
             label: 'Create Entry',
-            description: 'Create a new entry in a collection. Always validate required fields before calling. Collection is auto-resolved for app-defined entry types.',
+            description: 'Create a new entry in a folder. Always validate required fields before calling. Folder is auto-resolved for app-defined entry types.',
             parameters: T.Object({
-                repo: T.Optional(T.String({ description: 'Collection name (auto-resolved for app entity types)' })),
-                entityType: T.String({ description: 'Entity type (project, client, decision, etc.)' }),
+                repo: T.Optional(T.String({ description: 'Folder name (auto-resolved for app entity types)' })),
+                entityType: T.Union(agentAllowedTypes.map(t => T.Literal(t)), { description: `Entity type. Must be one of: ${agentAllowedTypes.join(', ')}.` }),
                 entityId: T.String({ description: 'Unique entity ID in kebab-case' }),
                 data: T.Object({}, { description: 'Entity data (YAML frontmatter)', additionalProperties: true }),
-                content: T.Optional(T.String({ description: 'Markdown content (optional)' })),
+                content: T.Optional(T.String({ description: 'Markdown content (optional). Write one line per paragraph — newlines only for real paragraph/list breaks, not to wrap prose at a column width (entries render source line breaks literally).' })),
+                folder_path: T.Optional(T.String({ description: 'Repo-relative subfolder for the entry (e.g. "clients/acme"). Omit to land at repo root. Parent folders are auto-created.' })),
                 commitMessage: T.Optional(T.String({ description: 'Custom commit message (optional)' })),
             }),
             execute: async (toolCallId, params) => {
                 try {
+                    // Defense in depth: LLMs occasionally pass strings that don't match the
+                    // enum schema. Runtime check ensures the launch allowlist is enforced
+                    // even if the schema layer is bypassed.
+                    const typeRejection = rejectDisallowedCreateType(params.entityType);
+                    if (typeRejection)
+                        return typeRejection;
                     let repoName = params.repo;
                     if (!repoName) {
-                        repoName = workspaceManager.getAppForEntityType(params.entityType);
-                        if (!repoName)
-                            return wrapToolResult({ success: false, error: `repo is required — could not auto-resolve repo for type "${params.entityType}"` });
+                        return wrapToolResult({ success: false, error: `repo is required — must specify which folder to use for type "${params.entityType}"` });
                     }
                     repoName = resolvePrivateRepo(repoName);
                     if (!canAccessRepo(repoName, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${repoName}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${repoName}" not found` });
                     }
+                    const eagerError = checkEagerSkillPermission(params.entityType, params.data, repoName);
+                    if (eagerError)
+                        return wrapToolResult({ success: false, error: eagerError });
                     const graph = workspaceManager.getGraph(repoName);
                     // Workspace-level dedup: warn if an entity with this ID already exists elsewhere
                     const existing = workspaceManager.findEntityById(params.entityId);
                     if (existing && existing.repoName !== repoName) {
-                        return wrapToolResult({ success: false, error: `An entity with ID "${params.entityId}" already exists in the "${existing.repoName}" collection (type: ${existing.data?.entity_type}). Use a unique ID or link to the existing entity with [[${params.entityId}]].` });
+                        return wrapToolResult({ success: false, error: `An entity with ID "${params.entityId}" already exists in the "${existing.repoName}" folder (type: ${existing.data?.entity_type}). Use a unique ID or link to the existing entity with [[${params.entityId}]].` });
                     }
-                    // Add timestamps and user info
-                    const now = new Date().toISOString();
-                    const dataWithMeta = {
-                        ...params.data,
-                        entity_id: params.entityId,
-                        created_at: now,
-                        updated_at: now,
-                        created_by: gitUser.id,
-                        updated_by: gitUser.id,
-                    };
-                    // Sanitize LLM JSON output: double-escaped newlines and stray quotes
-                    let sanitizedContent = (params.content || '').replace(/\\n/g, '\n').replace(/^"+|"+$/g, '');
-                    const entity = await graph.create({
+                    const actor = effectiveGitUser();
+                    const sanitizedContent = sanitizeLlmContent(params.content);
+                    // Workspace-wide uniqueness check for `user_handle` on person
+                    // entities (one user ↔ one person, workspace-wide), plus owner-
+                    // only authz so a non-owner agent session can't stamp a
+                    // pre-linked person via generic create_entity.
+                    if (params.entityType === 'person') {
+                        try {
+                            const incoming = params.data ?? {};
+                            validateUserHandleInPayload(workspaceManager, incoming);
+                            if (Object.prototype.hasOwnProperty.call(incoming, 'user_handle')) {
+                                assertCanChangeUserHandle(getUser(), '', incoming.user_handle);
+                            }
+                        }
+                        catch (err) {
+                            if (err instanceof BridgeError) {
+                                return wrapToolResult({ success: false, error: err.message, code: err.code, ...err.details });
+                            }
+                            throw err;
+                        }
+                    }
+                    // Scope ref fields (today: task.assignee → person). Reject a wikilink
+                    // that resolves to a non-person; forward references are allowed.
+                    try {
+                        assertEntityRefs(workspaceManager, params.entityType, params.data ?? {}, authSvc ? { userExists: (id) => !!authSvc.findUserById(Number(id)) } : undefined);
+                    }
+                    catch (err) {
+                        if (err instanceof EntityRefError || err instanceof UnknownUserRefError) {
+                            return wrapToolResult({ success: false, error: err.message, code: err.code, field: err.field });
+                        }
+                        throw err;
+                    }
+                    const options = prepareCreatePayload({
                         entityType: params.entityType,
                         entityId: params.entityId,
-                        data: dataWithMeta,
+                        data: params.data ?? {},
                         content: sanitizedContent,
+                        folderPath: params.folder_path,
                         commitMessage: params.commitMessage,
-                    });
-                    onMutation?.({ action: 'created', repo: repoName, entityType: params.entityType, entityId: params.entityId });
-                    return wrapToolResult({
-                        success: true,
-                        entity: {
-                            entityId: entity.id,
-                            entityType: entity.entityType,
-                            repo: repoName,
-                            path: entity.path,
-                            data: cleanData(entity.data),
-                        },
-                        message: `Created ${params.entityType}: ${params.entityId} in ${repoName}. Auto-committed — ready to push.`,
-                    });
+                    }, actor);
+                    // Surface a live "<user>'s agent is acting" chip in the sidebar for
+                    // the duration of the mutation. `leave` is always emitted via the
+                    // inner finally so a thrown error doesn't leave the chip stuck.
+                    onAgentActivity?.('enter', repoName);
+                    try {
+                        const entity = await graph.create(options);
+                        onMutation?.({ action: 'created', repo: repoName, entityType: params.entityType, entityId: params.entityId });
+                        return wrapToolResult({
+                            success: true,
+                            entity: {
+                                entityId: entity.id,
+                                entityType: entity.entityType,
+                                repo: repoName,
+                                path: entity.path,
+                                data: cleanData(entity.data),
+                            },
+                            message: `Created ${params.entityType}: ${params.entityId} in ${repoName}. Auto-committed — ready to push.`,
+                        });
+                    }
+                    finally {
+                        onAgentActivity?.('leave', repoName);
+                    }
                 }
                 catch (error) {
                     return wrapToolResult({
@@ -179,7 +300,7 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
             label: 'Get Entry',
             description: 'Retrieve full entry details. Use repo, entityType, entityId from search/list results. entityType is optional — if omitted it is read from the file.',
             parameters: T.Object({
-                repo: T.String({ description: 'Collection name' }),
+                repo: T.String({ description: 'Folder name' }),
                 entityType: T.Optional(T.String({ description: 'Entity type (optional — resolved from frontmatter if omitted)' })),
                 entityId: T.String({ description: 'Entity ID' }),
             }),
@@ -187,12 +308,50 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                 try {
                     const repo = resolvePrivateRepo(params.repo);
                     if (!canAccessRepo(repo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${repo}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${repo}" not found` });
+                    }
+                    // Comments live in SQLite, not the filesystem graph — dispatch
+                    // through the shared virtual-entity adapter (mirrors the MCP surface).
+                    if (params.entityType === 'comment' && commentSvc) {
+                        const envelope = commentVirtualEntity.getComment(commentSvc, params.entityId);
+                        if (!envelope || envelope.data.repo !== repo) {
+                            return wrapToolResult({ success: false, error: `Comment "${params.entityId}" not found` });
+                        }
+                        return wrapToolResult({
+                            success: true,
+                            entity: {
+                                entityId: envelope.id,
+                                entityType: envelope.entityType,
+                                repo,
+                                data: cleanData(envelope.data),
+                                content: envelope.document.content,
+                                wikilinks: envelope.document.wikilinks,
+                            },
+                        });
                     }
                     const graph = workspaceManager.getGraph(repo);
-                    const entity = params.entityType
-                        ? graph.get(params.entityType, params.entityId)
-                        : graph.getById(params.entityId);
+                    // If the agent passes the wrong entityType (e.g. based on stale
+                    // search results), graph.get computes the wrong filesystem path
+                    // and throws. Fall back to getById, which scans all type subdirs
+                    // under the folder and resolves the actual location.
+                    let entity;
+                    if (params.entityType) {
+                        try {
+                            entity = graph.get(params.entityType, params.entityId);
+                        }
+                        catch {
+                            entity = graph.getById(params.entityId);
+                        }
+                    }
+                    else {
+                        entity = graph.getById(params.entityId);
+                    }
+                    // Prefer the live editor body when a seeded Y.Doc is open. graph.get
+                    // reads disk, which lags the editor by the autosave debounce — a
+                    // user's freshly-placed image embed lives in the Y.Doc before it's
+                    // committed. Returning disk content is what let the agent edit then
+                    // resend a body missing those embeds, silently dropping images.
+                    const liveBody = graph.getLiveBody(entity.entityType, entity.id);
                     return wrapToolResult({
                         success: true,
                         entity: {
@@ -201,7 +360,7 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                             repo,
                             path: entity.path,
                             data: cleanData(entity.data),
-                            content: entity.document.content,
+                            content: liveBody ?? entity.document.content,
                             wikilinks: entity.document.wikilinks,
                         },
                     });
@@ -218,73 +377,435 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'update_entity',
             label: 'Update Entry',
-            description: 'Update an existing entry. Collection is auto-resolved for app-defined types.',
+            description: 'Update an existing entry. Folder is auto-resolved for app-defined types.',
             parameters: T.Object({
-                repo: T.Optional(T.String({ description: 'Collection name (auto-resolved for app entity types)' })),
+                repo: T.Optional(T.String({ description: 'Folder name (auto-resolved for app entity types)' })),
                 entityType: T.String({ description: 'Entity type' }),
                 entityId: T.String({ description: 'Entity ID' }),
                 data: T.Optional(T.Object({}, { description: 'Updated data fields', additionalProperties: true })),
-                content: T.Optional(T.String({ description: 'Updated markdown content' })),
+                content: T.Optional(T.String({ description: 'Updated markdown body (replaces the entire body). Write one line per paragraph — newlines only for real paragraph/list breaks, not to wrap prose at a column width (entries render source line breaks literally).' })),
                 commitMessage: T.Optional(T.String({ description: 'Custom commit message' })),
+                allowImageRemoval: T.Optional(T.Boolean({ description: 'Set true only to deliberately delete image/asset embeds the document currently has; otherwise such a whole-body write is rejected (ASSET_REMOVAL_BLOCKED). Prefer get_entity then patch_entity for small edits.' })),
             }),
             execute: async (toolCallId, params) => {
                 try {
                     let repoName = params.repo;
                     if (!repoName) {
-                        repoName = workspaceManager.getAppForEntityType(params.entityType);
-                        if (!repoName)
-                            return wrapToolResult({ success: false, error: `repo is required — could not auto-resolve repo for type "${params.entityType}"` });
+                        return wrapToolResult({ success: false, error: `repo is required — must specify which folder to use for type "${params.entityType}"` });
                     }
                     repoName = resolvePrivateRepo(repoName);
                     if (!canAccessRepo(repoName, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${repoName}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${repoName}" not found` });
                     }
+                    const eagerError = checkEagerSkillPermission(params.entityType, params.data, repoName);
+                    if (eagerError)
+                        return wrapToolResult({ success: false, error: eagerError });
                     const graph = workspaceManager.getGraph(repoName);
-                    // Add update metadata
-                    const dataWithMeta = params.data
-                        ? {
-                            ...params.data,
-                            updated_at: new Date().toISOString(),
-                            updated_by: gitUser.id,
-                        }
-                        : undefined;
-                    // Sanitize LLM JSON output: double-escaped newlines and stray quotes
+                    const actor = effectiveGitUser();
                     const sanitizedContent = params.content !== undefined
-                        ? params.content.replace(/\\n/g, '\n').replace(/^"+|"+$/g, '') : params.content;
-                    const entity = await graph.update({
+                        ? sanitizeLlmContent(params.content)
+                        : params.content;
+                    // Workspace-wide uniqueness check + owner-only authz for
+                    // `user_handle` on person entities. Generic update_entity must
+                    // not be a back door around the ownerOnly() gate on the dedicated
+                    // link/unlink tools — otherwise a member could ask the agent to
+                    // "set this person's user_handle to mine" and bypass the gate.
+                    if (params.entityType === 'person' && params.data) {
+                        try {
+                            validateUserHandleInPayload(workspaceManager, params.data, { repo: repoName, entityId: params.entityId });
+                            if (Object.prototype.hasOwnProperty.call(params.data, 'user_handle')) {
+                                let currentHandle = '';
+                                try {
+                                    const current = graph.get('person', params.entityId);
+                                    currentHandle = (current?.data?.user_handle ?? '');
+                                }
+                                catch { /* new entity / missing — treat as empty */ }
+                                assertCanChangeUserHandle(getUser(), currentHandle, params.data.user_handle);
+                            }
+                        }
+                        catch (err) {
+                            if (err instanceof BridgeError) {
+                                return wrapToolResult({ success: false, error: err.message, code: err.code, ...err.details });
+                            }
+                            throw err;
+                        }
+                    }
+                    // Scope ref fields (today: task.assignee → person). Reject a wikilink
+                    // that resolves to a non-person; forward references are allowed.
+                    try {
+                        assertEntityRefs(workspaceManager, params.entityType, params.data, authSvc ? { userExists: (id) => !!authSvc.findUserById(Number(id)) } : undefined);
+                    }
+                    catch (err) {
+                        if (err instanceof EntityRefError || err instanceof UnknownUserRefError) {
+                            return wrapToolResult({ success: false, error: err.message, code: err.code, field: err.field });
+                        }
+                        throw err;
+                    }
+                    const options = prepareUpdatePayload({
                         entityType: params.entityType,
                         entityId: params.entityId,
-                        data: dataWithMeta,
+                        data: params.data,
                         content: sanitizedContent,
                         commitMessage: params.commitMessage,
+                    }, actor);
+                    onAgentActivity?.('enter', repoName);
+                    try {
+                        // Shared diagnosed update (c6ef9297 contract): throws
+                        // SilentDropError when the caller intended a change that left the
+                        // file byte-identical, surfaced via the outer catch so the agent
+                        // isn't misled by a success envelope.
+                        const { entity, frontmatter_changed, content_changed, noop, broadcast } = await diagnosedUpdate(graph, options, { data: params.data, content: sanitizedContent }, { allowAssetRemoval: params.allowImageRemoval });
+                        onMutation?.({ action: 'updated', repo: repoName, entityType: params.entityType, entityId: params.entityId });
+                        return wrapToolResult({
+                            success: true,
+                            entity: {
+                                entityId: entity.id,
+                                entityType: entity.entityType,
+                                repo: repoName,
+                                data: cleanData(entity.data),
+                            },
+                            frontmatter_changed,
+                            content_changed,
+                            noop,
+                            broadcast,
+                            message: noop
+                                ? `No change to ${params.entityType}: ${params.entityId} — on-disk state already matched.`
+                                : `Updated ${params.entityType}: ${params.entityId}. Auto-committed — ready to push.`,
+                        });
+                    }
+                    finally {
+                        onAgentActivity?.('leave', repoName);
+                    }
+                }
+                catch (error) {
+                    if (error instanceof DroppedAssetError) {
+                        return wrapToolResult({
+                            success: false,
+                            code: 'ASSET_REMOVAL_BLOCKED',
+                            droppedAssets: error.dropped,
+                            error: error.message,
+                        });
+                    }
+                    return wrapToolResult({
+                        success: false,
+                        error: error instanceof Error ? error.message : 'Unknown error',
                     });
-                    onMutation?.({ action: 'updated', repo: repoName, entityType: params.entityType, entityId: params.entityId });
+                }
+            },
+        },
+        // Surgical body edit (find/replace) — parity with the MCP patch_entity.
+        // Lets the in-app agent change a small slice of a long entry without
+        // regenerating (and risking dropping image embeds from) the whole body.
+        {
+            name: 'patch_entity',
+            label: 'Patch Entry',
+            description: 'Surgically edit an entry body by replacing an exact substring — without rewriting the whole body. ' +
+                'Prefer this over update_entity for small edits (rename a heading, fix a sentence): it edits the live ' +
+                'editor body and cannot drop image/asset embeds it did not touch. Use expectedCount to guard against ' +
+                'ambiguous matches. For data/frontmatter changes use update_entity.',
+            parameters: T.Object({
+                repo: T.String({ description: 'Folder name' }),
+                entityType: T.String({ description: 'Entity type' }),
+                entityId: T.String({ description: 'Entity ID' }),
+                find: T.String({ description: 'Exact substring to locate in the current body (verbatim, including whitespace).' }),
+                replace: T.String({ description: 'Replacement text. Empty string deletes the matched substring.' }),
+                expectedCount: T.Optional(T.Number({ description: 'Optional safety check: require `find` to occur exactly this many times, else reject with NO_MATCH / AMBIGUOUS_MATCH.' })),
+                commitMessage: T.Optional(T.String({ description: 'Custom commit message' })),
+            }),
+            execute: async (toolCallId, params) => {
+                try {
+                    const repoName = resolvePrivateRepo(params.repo);
+                    if (!canAccessRepo(repoName, workspaceManager, getUser, authSvc)) {
+                        return wrapToolResult({ success: false, error: `Folder "${repoName}" not found` });
+                    }
+                    if (params.find === '') {
+                        return wrapToolResult({ success: false, error: 'patch_entity requires a non-empty `find` string' });
+                    }
+                    if (params.find === params.replace) {
+                        return wrapToolResult({ success: false, error: 'patch_entity `find` and `replace` are identical — nothing to do' });
+                    }
+                    const graph = workspaceManager.getGraph(repoName);
+                    const entity = graph.get(params.entityType, params.entityId);
+                    // Patch against the live editor body when one is open, so we don't
+                    // reintroduce the stale-read problem (editing a body that lags the
+                    // user's in-editor typing / freshly-placed embeds).
+                    const currentBody = graph.getLiveBody(params.entityType, params.entityId) ?? entity.document.content;
+                    // Count literal (non-regex) occurrences.
+                    let count = 0;
+                    for (let i = currentBody.indexOf(params.find); i !== -1; i = currentBody.indexOf(params.find, i + params.find.length))
+                        count++;
+                    if (count === 0) {
+                        return wrapToolResult({ success: false, code: 'NO_MATCH', error: `\`find\` substring not present in ${params.entityType}/${params.entityId}.` });
+                    }
+                    if (params.expectedCount !== undefined && count !== params.expectedCount) {
+                        return wrapToolResult({ success: false, code: 'AMBIGUOUS_MATCH', occurrences: count, error: `Expected ${params.expectedCount} occurrence(s) of \`find\`, found ${count}.` });
+                    }
+                    const newBody = currentBody.split(params.find).join(params.replace);
+                    const actor = effectiveGitUser();
+                    const options = prepareUpdatePayload({
+                        entityType: params.entityType,
+                        entityId: params.entityId,
+                        content: newBody,
+                        commitMessage: params.commitMessage,
+                    }, actor);
+                    onAgentActivity?.('enter', repoName);
+                    try {
+                        const { entity: updated, frontmatter_changed, content_changed, noop, broadcast } = await diagnosedUpdate(graph, options, { content: newBody });
+                        onMutation?.({ action: 'updated', repo: repoName, entityType: params.entityType, entityId: params.entityId });
+                        return wrapToolResult({
+                            success: true,
+                            entity: {
+                                entityId: updated.id,
+                                entityType: updated.entityType,
+                                repo: repoName,
+                                data: cleanData(updated.data),
+                            },
+                            occurrences: count,
+                            frontmatter_changed,
+                            content_changed,
+                            noop,
+                            broadcast,
+                            message: `Patched ${params.entityType}: ${params.entityId} (${count} occurrence${count === 1 ? '' : 's'}). Auto-committed — ready to push.`,
+                        });
+                    }
+                    finally {
+                        onAgentActivity?.('leave', repoName);
+                    }
+                }
+                catch (error) {
+                    if (error instanceof DroppedAssetError) {
+                        return wrapToolResult({ success: false, code: 'ASSET_REMOVAL_BLOCKED', droppedAssets: error.dropped, error: error.message });
+                    }
+                    return wrapToolResult({ success: false, error: error instanceof Error ? error.message : 'Unknown error' });
+                }
+            },
+        },
+        // List assets already uploaded to a folder
+        {
+            name: 'list_assets',
+            label: 'List Assets',
+            description: 'List images/files already uploaded to a folder, with a ready-to-paste markdown embed for each. ' +
+                'Use this to find an asset a user placed (e.g. a screenshot) so you can embed it into an entry — ' +
+                'assets live in storage (R2/local), NOT on the local filesystem, so import_file cannot find them. ' +
+                'Each result has an `embed` string: use it verbatim and NEVER write ![[filename]] transclusion syntax ' +
+                '(it does not render). Optionally filter by entityType/entityId. This tool only references existing ' +
+                'assets — uploads happen via the workspace UI or import_file.',
+            parameters: T.Object({
+                repo: T.String({ description: 'Folder name' }),
+                entityType: T.Optional(T.String({ description: 'Filter to assets owned by entries of this type' })),
+                entityId: T.Optional(T.String({ description: 'Filter to assets owned by this entry id' })),
+            }),
+            execute: async (toolCallId, params) => {
+                try {
+                    const repoName = resolvePrivateRepo(params.repo);
+                    if (!canAccessRepo(repoName, workspaceManager, getUser, authSvc)) {
+                        return wrapToolResult({ success: false, error: `Folder "${repoName}" not found` });
+                    }
+                    let assets = await listRepoAssets(repoName, workspaceManager);
+                    if (params.entityType)
+                        assets = assets.filter(a => a.entityType === params.entityType);
+                    if (params.entityId)
+                        assets = assets.filter(a => a.entityId === params.entityId);
                     return wrapToolResult({
                         success: true,
-                        entity: {
-                            entityId: entity.id,
-                            entityType: entity.entityType,
-                            repo: repoName,
-                            data: cleanData(entity.data),
-                        },
-                        message: `Updated ${params.entityType}: ${params.entityId}. Auto-committed — ready to push.`,
+                        repo: repoName,
+                        count: assets.length,
+                        assets: assets.map(a => ({
+                            asset_id: a.assetId,
+                            filename: a.filename,
+                            mime_type: a.contentType,
+                            entityType: a.entityType,
+                            entityId: a.entityId,
+                            entityName: a.entityName,
+                            url: a.url,
+                            embed: a.embed,
+                        })),
                     });
                 }
                 catch (error) {
+                    return wrapToolResult({ success: false, error: error instanceof Error ? error.message : 'Unknown error' });
+                }
+            },
+        },
+        // Embed an already-uploaded asset into an entry body
+        {
+            name: 'attach_asset_to_entity',
+            label: 'Attach Asset',
+            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]] written earlier) for the working embed. Drop-guarded: rejects with ' +
+                'ASSET_REMOVAL_BLOCKED if it would remove other image embeds (append only — replace_placeholder is exempt ' +
+                'since the placeholder it removes is the dead reference being fixed).',
+            parameters: T.Object({
+                repo: T.String({ description: 'Folder name' }),
+                entityType: T.String({ description: 'Entity type of the target entry' }),
+                entityId: T.String({ description: 'Entity ID of the target entry' }),
+                url: T.String({ description: 'Asset url, taken verbatim from list_assets' }),
+                alt: T.Optional(T.String({ description: 'Alt text / caption. Defaults to the asset filename.' })),
+                mode: T.Optional(T.Union([T.Literal('append'), T.Literal('replace_placeholder')], { description: 'append (default) or replace_placeholder' })),
+                placeholder: T.Optional(T.String({ description: 'Required for replace_placeholder: exact text to replace' })),
+                expectedCount: T.Optional(T.Number({ description: 'For replace_placeholder: require this many occurrences, else reject' })),
+            }),
+            execute: async (toolCallId, params) => {
+                try {
+                    const repoName = resolvePrivateRepo(params.repo);
+                    if (!canAccessRepo(repoName, workspaceManager, getUser, authSvc)) {
+                        return wrapToolResult({ success: false, error: `Folder "${repoName}" not found` });
+                    }
+                    const url = params.url ?? '';
+                    if (!url.trim())
+                        return wrapToolResult({ success: false, error: 'url is required' });
+                    const mode = params.mode ?? 'append';
+                    if (mode === 'replace_placeholder' && !params.placeholder) {
+                        return wrapToolResult({ success: false, error: 'mode "replace_placeholder" requires a non-empty placeholder' });
+                    }
+                    const filename = params.alt ?? (url.split('/').pop() || 'asset').split('?')[0];
+                    const embed = assetEmbed(filename, url);
+                    const graph = workspaceManager.getGraph(repoName);
+                    const entity = graph.get(params.entityType, params.entityId);
+                    const currentBody = graph.getLiveBody(params.entityType, params.entityId) ?? entity.document.content;
+                    let newBody;
+                    let occurrences;
+                    let allowAssetRemoval = false;
+                    if (mode === 'replace_placeholder') {
+                        const ph = params.placeholder;
+                        let count = 0;
+                        for (let i = currentBody.indexOf(ph); i !== -1; i = currentBody.indexOf(ph, i + ph.length))
+                            count++;
+                        if (count === 0) {
+                            return wrapToolResult({ success: false, code: 'NO_MATCH', error: `placeholder not present in ${params.entityType}/${params.entityId}.` });
+                        }
+                        if (params.expectedCount !== undefined && count !== params.expectedCount) {
+                            return wrapToolResult({ success: false, code: 'AMBIGUOUS_MATCH', occurrences: count, error: `Expected ${params.expectedCount} 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 wrapToolResult({ success: false, code: 'ALREADY_PRESENT', error: `Asset embed already present in ${params.entityType}/${params.entityId}.` });
+                        }
+                        newBody = currentBody.trimEnd() + '\n\n' + embed + '\n';
+                    }
+                    const options = prepareUpdatePayload({
+                        entityType: params.entityType,
+                        entityId: params.entityId,
+                        content: newBody,
+                    }, effectiveGitUser());
+                    onAgentActivity?.('enter', repoName);
+                    try {
+                        const { entity: updated, frontmatter_changed, content_changed, noop, broadcast } = await diagnosedUpdate(graph, options, { content: newBody }, { allowAssetRemoval });
+                        onMutation?.({ action: 'updated', repo: repoName, entityType: params.entityType, entityId: params.entityId });
+                        return wrapToolResult({
+                            success: true,
+                            entity: { entityId: updated.id, entityType: updated.entityType, repo: repoName },
+                            embed,
+                            mode,
+                            occurrences,
+                            frontmatter_changed,
+                            content_changed,
+                            noop,
+                            broadcast,
+                            message: `Embedded ${filename} into ${params.entityType}: ${params.entityId}. Auto-committed — ready to push.`,
+                        });
+                    }
+                    finally {
+                        onAgentActivity?.('leave', repoName);
+                    }
+                }
+                catch (error) {
+                    if (error instanceof DroppedAssetError) {
+                        return wrapToolResult({ success: false, code: 'ASSET_REMOVAL_BLOCKED', droppedAssets: error.dropped, error: error.message });
+                    }
+                    return wrapToolResult({ success: false, error: error instanceof Error ? error.message : 'Unknown error' });
+                }
+            },
+        },
+        // Promote a composer/chat scratch file (image or doc) into the asset library.
+        {
+            name: 'save_file_to_assets',
+            label: 'Save File to Assets',
+            description: 'Save a file the user attached to THIS chat (a composer/scratch image or document) into the curated ' +
+                'asset library so it persists beyond the conversation. Use this when the user says something like "save ' +
+                'this to my assets". By default it saves the most-recently-attached file to the shared Assets folder ' +
+                '(the user can then move it wherever they like); pass `filename` to disambiguate when several are ' +
+                'attached, or `folder` to save into a specific folder you have write access to. Only works for files ' +
+                'the user attached to the chat (and not ones already picked from the library) — it cannot save arbitrary ' +
+                'URLs or filesystem paths.',
+            parameters: T.Object({
+                filename: T.Optional(T.String({ description: 'Which attached file to save, by filename (defaults to the most recent).' })),
+                folder: T.Optional(T.String({ description: 'Destination folder name. Defaults to the shared Assets library.' })),
+            }),
+            execute: async (toolCallId, params) => {
+                try {
+                    const user = getUser();
+                    if (!user)
+                        return wrapToolResult({ success: false, error: 'Saving files requires a signed-in user.' });
+                    if (!chatSessionSvc) {
+                        return wrapToolResult({ success: false, error: 'Saving chat files is not available in this context.' });
+                    }
+                    const sessionId = getSessionId();
+                    if (!sessionId) {
+                        return wrapToolResult({ success: false, code: 'NO_SESSION', error: 'No active conversation to save a file from.' });
+                    }
+                    // Scope to THIS conversation's OWN uploads (not library picks, which are
+                    // already saved; not the user's other chats).
+                    const files = chatSessionSvc.getScratchFilesBySession(sessionId)
+                        .filter((f) => f.userId === user.id && f.source === 'upload');
+                    if (files.length === 0) {
+                        return wrapToolResult({ success: false, code: 'NO_FILE', error: 'No uploaded file is attached to this chat to save.' });
+                    }
+                    // Resolve which scratch file: by filename if given, else most recent.
+                    let target = files[0];
+                    if (params.filename) {
+                        const want = String(params.filename).toLowerCase();
+                        const match = files.find(f => f.filename.toLowerCase() === want)
+                            ?? files.find(f => f.filename.toLowerCase().includes(want));
+                        if (!match) {
+                            return wrapToolResult({
+                                success: false, code: 'NO_MATCH',
+                                error: `No attached file matches "${params.filename}".`,
+                                attached: files.map(f => f.filename),
+                            });
+                        }
+                        target = match;
+                    }
+                    const folder = params.folder ? resolvePrivateRepo(params.folder) : undefined;
+                    const result = await promoteScratchFileToAssets(workspaceManager, chatSessionSvc, authSvc, {
+                        sessionId: target.sessionId,
+                        fileId: target.fileId,
+                        user,
+                        targetRepo: folder,
+                    });
+                    onMutation?.({ action: 'updated', repo: result.repo, entityType: 'material', entityId: result.assetId, repoSync: true });
                     return wrapToolResult({
-                        success: false,
-                        error: error instanceof Error ? error.message : 'Unknown error',
+                        success: true,
+                        asset_id: result.assetId,
+                        filename: result.filename,
+                        name: result.displayName,
+                        url: result.url,
+                        repo: result.repo,
+                        message: `Saved "${result.displayName}" to the ${result.repo} folder. You can move it to another folder from the asset library.`,
                     });
                 }
+                catch (error) {
+                    if (error instanceof PromoteScratchError) {
+                        return wrapToolResult({ success: false, code: error.code, error: error.message });
+                    }
+                    return wrapToolResult({ success: false, error: error instanceof Error ? error.message : 'Unknown error' });
+                }
             },
         },
         // Delete entity
         {
             name: 'delete_entity',
             label: 'Delete Entry',
-            description: 'Delete an entry. Use with caution! Collection is auto-resolved for app-defined types.',
+            description: 'Delete an entry. Use with caution! Folder is auto-resolved for app-defined types.',
             parameters: T.Object({
-                repo: T.Optional(T.String({ description: 'Collection name (auto-resolved for app entity types)' })),
+                repo: T.Optional(T.String({ description: 'Folder name (auto-resolved for app entity types)' })),
                 entityType: T.String({ description: 'Entity type' }),
                 entityId: T.String({ description: 'Entity ID' }),
                 commitMessage: T.Optional(T.String({ description: 'Custom commit message' })),
@@ -293,21 +814,39 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                 try {
                     let repoName = params.repo;
                     if (!repoName) {
-                        repoName = workspaceManager.getAppForEntityType(params.entityType);
-                        if (!repoName)
-                            return wrapToolResult({ success: false, error: `repo is required — could not auto-resolve repo for type "${params.entityType}"` });
+                        return wrapToolResult({ success: false, error: `repo is required — must specify which folder to use for type "${params.entityType}"` });
                     }
                     repoName = resolvePrivateRepo(repoName);
                     if (!canAccessRepo(repoName, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${repoName}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${repoName}" not found` });
                     }
                     const graph = workspaceManager.getGraph(repoName);
-                    await graph.delete(params.entityType, params.entityId, params.commitMessage);
-                    onMutation?.({ action: 'deleted', repo: repoName, entityType: params.entityType, entityId: params.entityId });
-                    return wrapToolResult({
-                        success: true,
-                        message: `Deleted ${params.entityType}: ${params.entityId}. Auto-committed — ready to push.`,
-                    });
+                    // 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, and the Profile panel catches the orphan after.
+                    let bridgeWarning;
+                    if (params.entityType === 'person') {
+                        try {
+                            const handle = graph.get('person', params.entityId)?.data?.user_handle;
+                            if (typeof handle === 'string' && handle.length > 0) {
+                                bridgeWarning = `Note: this record was linked to the "${handle}" user account. Deleting it unlinks them — their "My Tasks", @mentions, and assignments stop resolving until they link a new record.`;
+                            }
+                        }
+                        catch { /* not found — let graph.delete surface it */ }
+                    }
+                    onAgentActivity?.('enter', repoName);
+                    try {
+                        await graph.delete(params.entityType, params.entityId, params.commitMessage);
+                        onMutation?.({ action: 'deleted', repo: repoName, entityType: params.entityType, entityId: params.entityId });
+                        return wrapToolResult({
+                            success: true,
+                            message: `Deleted ${params.entityType}: ${params.entityId}. Auto-committed — ready to push.`,
+                            ...(bridgeWarning ? { warning: bridgeWarning } : {}),
+                        });
+                    }
+                    finally {
+                        onAgentActivity?.('leave', repoName);
+                    }
                 }
                 catch (error) {
                     return wrapToolResult({
@@ -321,46 +860,94 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'import_file',
             label: 'Import File',
-            description: 'Import a local file as a Studiograph entry. Supports .md and .txt (→ note) and .csv (→ dataset). The file is read from the local filesystem and converted to an entry with appropriate frontmatter.',
+            description: 'Import a local file as a Studiograph entry. Text formats become typed entries (.md/.txt → note, .csv → dataset). Binary formats become typed entries that embed a free-standing asset: images/opaque files → material, PDF/Word → document, spreadsheets → dataset.',
             parameters: T.Object({
                 path: T.String({ description: 'Absolute path or ~/relative path to the file' }),
-                collection: T.String({ description: 'Target collection name' }),
-                entityType: T.Optional(T.String({ description: 'Override entity type (default: auto-detect from extension)' })),
+                folder: T.String({ description: 'Target folder name' }),
+                entityType: T.Optional(T.String({ description: 'Override entity type (default: auto-detect from extension; ignored for binary imports, which route by kind)' })),
                 entityId: T.Optional(T.String({ description: 'Override entity ID (default: from filename)' })),
             }),
             execute: async (toolCallId, params) => {
                 try {
-                    if (!canAccessRepo(params.collection, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${params.collection}" not found` });
+                    if (!canAccessRepo(params.folder, workspaceManager, getUser, authSvc)) {
+                        return wrapToolResult({ success: false, error: `Folder "${params.folder}" not found` });
                     }
                     const { readFileSync, existsSync } = await import('fs');
-                    const { resolve } = await import('path');
+                    const { resolve, basename, sep } = await import('path');
                     const { homedir } = await import('os');
                     const { importFile, isSupportedFile } = await import('../../services/import-service.js');
+                    const { isAssetUploadExtension } = await import('../../services/assets/base.js');
+                    const { importAssetAsEntity } = await import('../../services/asset-import-service.js');
                     const filePath = params.path.startsWith('~/')
                         ? resolve(homedir(), params.path.slice(2))
                         : resolve(params.path);
                     if (!existsSync(filePath)) {
                         return wrapToolResult({ success: false, error: `File not found: ${filePath}` });
                     }
+                    const graph = workspaceManager.getGraph(params.folder);
+                    const fname = basename(filePath);
+                    // Path-exfil guard: the agent reads bytes off disk and uploads
+                    // them as a workspace asset, accessible via /api/assets/* by any
+                    // folder member. Without an allowlist, an LLM prompt injection in
+                    // an imported note can ask the agent to grab ~/.ssh/id_rsa, .env
+                    // files, kubeconfigs, etc. by renaming them to a permitted
+                    // extension. Restrict to roots a user would plausibly drop files
+                    // from: the workspace itself, ~/Downloads, ~/Documents.
+                    const home = homedir();
+                    const workspaceRoot = graph.getWorkspaceRoot();
+                    const allowedRoots = [
+                        workspaceRoot,
+                        resolve(home, 'Downloads'),
+                        resolve(home, 'Documents'),
+                    ].filter((r) => Boolean(r)).map(r => r.endsWith(sep) ? r : r + sep);
+                    const isInAllowedRoot = allowedRoots.some(root => filePath === root.slice(0, -1) || filePath.startsWith(root));
+                    if (!isInAllowedRoot) {
+                        return wrapToolResult({
+                            success: false,
+                            error: `Path "${filePath}" is outside the import allowlist. Files must live under the workspace, ~/Downloads, or ~/Documents.`,
+                        });
+                    }
+                    // Binary extensions → asset-as-embed import: store a free-standing
+                    // asset + create the typed entry(ies) that embed it (image→material,
+                    // doc/pdf→document, xlsx→dataset×N). The text-import path doesn't know
+                    // how to handle .indd / .pptx / etc. Parity with the web import
+                    // dispatcher (importAssetAsEntity).
+                    if (isAssetUploadExtension(fname)) {
+                        const buffer = readFileSync(filePath);
+                        const result = await importAssetAsEntity({
+                            graph,
+                            filename: fname,
+                            buffer,
+                        });
+                        for (const e of result.entities) {
+                            onMutation?.({ action: 'created', repo: params.folder, entityType: e.entityType, entityId: e.entityId });
+                        }
+                        const first = result.entities[0];
+                        return wrapToolResult({
+                            success: true,
+                            entityType: first?.entityType,
+                            entityId: first?.entityId,
+                            assetId: result.assetId,
+                            entities: result.entities.map(e => ({ entityType: e.entityType, entityId: e.entityId })),
+                            message: `Imported ${fname} as ${result.entities.map(e => `${e.entityType}/${e.entityId}`).join(', ')} in ${params.folder}`,
+                        });
+                    }
                     if (!isSupportedFile(filePath)) {
-                        return wrapToolResult({ success: false, error: `Unsupported file type. Supported: .md, .txt, .csv` });
+                        return wrapToolResult({ success: false, error: `Unsupported file type for ${fname}` });
                     }
-                    const graph = workspaceManager.getGraph(params.collection);
                     const content = readFileSync(filePath);
-                    const { basename } = await import('path');
-                    const result = await importFile(graph, basename(filePath), content, {
+                    const result = await importFile(graph, fname, content, {
                         entityType: params.entityType,
                         entityId: params.entityId,
                     });
                     if (result.status === 'created') {
-                        onMutation?.({ action: 'created', repo: params.collection, entityType: result.entityType, entityId: result.entityId });
+                        onMutation?.({ action: 'created', repo: params.folder, entityType: result.entityType, entityId: result.entityId });
                     }
                     return wrapToolResult({
                         success: result.status === 'created',
                         ...result,
                         message: result.status === 'created'
-                            ? `Imported ${basename(filePath)} as ${result.entityType}/${result.entityId} in ${params.collection}`
+                            ? `Imported ${fname} as ${result.entityType}/${result.entityId} in ${params.folder}`
                             : result.error,
                     });
                 }
@@ -376,9 +963,9 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'rename_entity',
             label: 'Rename Entry',
-            description: 'Rename an entry by changing its ID. Preserves all data, content, and source_ref. The old ID will no longer exist. Collection is auto-resolved for app-defined types.',
+            description: 'Rename an entry by changing its ID. Preserves all data, content, and source_ref. The old ID will no longer exist. Folder is auto-resolved for app-defined types.',
             parameters: T.Object({
-                repo: T.Optional(T.String({ description: 'Collection name (auto-resolved for app entity types)' })),
+                repo: T.Optional(T.String({ description: 'Folder name (auto-resolved for app entity types)' })),
                 entityType: T.String({ description: 'Entity type' }),
                 oldId: T.String({ description: 'Current entity ID' }),
                 newId: T.String({ description: 'New entity ID (kebab-case)' }),
@@ -387,13 +974,11 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                 try {
                     let repoName = params.repo;
                     if (!repoName) {
-                        repoName = workspaceManager.getAppForEntityType(params.entityType);
-                        if (!repoName)
-                            return wrapToolResult({ success: false, error: `repo is required — could not auto-resolve repo for type "${params.entityType}"` });
+                        return wrapToolResult({ success: false, error: `repo is required — must specify which folder to use for type "${params.entityType}"` });
                     }
                     repoName = resolvePrivateRepo(repoName);
                     if (!canAccessRepo(repoName, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${repoName}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${repoName}" not found` });
                     }
                     const graph = workspaceManager.getGraph(repoName);
                     const result = await graph.rename(params.entityType, params.oldId, params.newId);
@@ -413,41 +998,41 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                 }
             },
         },
-        // Move entity between repos
+        // Transfer entity across repos (cross-repo move). Distinct from
+        // folder-tools' `move_entity`, which relocates within one repo.
         {
-            name: 'move_entity',
-            label: 'Move Entry',
-            description: 'Move an entry from one collection to another (admin only). Preserves all data, content, and wikilinks.',
+            name: 'transfer_entity',
+            label: 'Transfer Entry',
+            description: 'Move an entry from one repo to another. Preserves all data, content, and wikilinks. Requires access to both folders. For relocating within the same repo (folder_path change), use move_entity instead.',
             parameters: T.Object({
-                sourceRepo: T.String({ description: 'Source collection name' }),
-                targetRepo: T.String({ description: 'Target collection name' }),
+                sourceRepo: T.String({ description: 'Source repo name' }),
+                targetRepo: T.String({ description: 'Target repo name' }),
                 entityType: T.String({ description: 'Entity type' }),
                 entityId: T.String({ description: 'Entity ID' }),
                 commitMessage: T.Optional(T.String({ description: 'Custom commit message (optional)' })),
             }),
             execute: async (toolCallId, params) => {
                 try {
-                    const denied = adminOnly(getUser);
-                    if (denied)
-                        return wrapToolResult({ success: false, error: denied });
                     if (!canAccessRepo(params.sourceRepo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${params.sourceRepo}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${params.sourceRepo}" not found` });
                     }
                     if (!canAccessRepo(params.targetRepo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${params.targetRepo}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${params.targetRepo}" not found` });
                     }
                     const sourceGraph = workspaceManager.getGraph(params.sourceRepo);
                     const targetGraph = workspaceManager.getGraph(params.targetRepo);
                     // Read the full entity from source
                     const entity = sourceGraph.get(params.entityType, params.entityId);
                     // Create in target repo
+                    const actor = effectiveGitUser();
                     const now = new Date().toISOString();
                     await targetGraph.create({
                         entityType: params.entityType,
                         entityId: params.entityId,
-                        data: { ...entity.data, updated_at: now, updated_by: gitUser.id },
+                        data: { ...entity.data, updated_at: now, updated_by: actor.id },
                         content: entity.document.content || '',
                         commitMessage: params.commitMessage || `Move ${params.entityType} ${params.entityId} from ${params.sourceRepo} to ${params.targetRepo}`,
+                        user: actor,
                     });
                     // Delete from source repo
                     await sourceGraph.delete(params.entityType, params.entityId, `Move ${params.entityType} ${params.entityId} to ${params.targetRepo}`);
@@ -470,11 +1055,11 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'search_entities',
             label: 'Search Entries',
-            description: 'Search for entries across collections with filters.',
+            description: 'Search for entries across folders with filters.',
             parameters: T.Object({
                 query: T.Optional(T.String({ description: 'Search query (full-text)' })),
                 entityType: T.Optional(T.String({ description: 'Filter by entity type' })),
-                repoNames: T.Optional(T.Array(T.String(), { description: 'Limit to specific collections' })),
+                repoNames: T.Optional(T.Array(T.String(), { description: 'Limit to specific folders' })),
                 visibility: T.Optional(T.Array(T.String(), { description: 'Filter by visibility (public, team, admin, restricted)' })),
                 tags: T.Optional(T.Array(T.String(), { description: 'Filter by tags' })),
                 dateRange: T.Optional(T.Object({
@@ -486,7 +1071,7 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
             }),
             execute: async (toolCallId, params) => {
                 try {
-                    // Scope search to accessible collections
+                    // Scope search to accessible folders
                     const allowed = getAccessibleRepoNames(workspaceManager, getUser, authSvc);
                     let repoNames = params.repoNames?.map((r) => resolvePrivateRepo(r));
                     if (allowed) {
@@ -534,8 +1119,32 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
             }),
             execute: async (toolCallId, params) => {
                 try {
+                    // Comments live in SQLite, not the filesystem graph — dispatch
+                    // through the shared virtual-entity adapter (mirrors the MCP surface),
+                    // filtering to the folders the caller can see.
+                    if (params.entityType === 'comment' && commentSvc) {
+                        const allowedComments = getAccessibleRepoNames(workspaceManager, getUser, authSvc);
+                        // Filter to accessible folders BEFORE applying the caller's limit:
+                        // a pre-filter SQL cap could be consumed entirely by comments in
+                        // folders the caller can't see, starving the visible ones. The
+                        // service still bounds the underlying fetch (<=500) as a backstop.
+                        const visible = commentVirtualEntity
+                            .listComments(commentSvc, {})
+                            .filter(e => !allowedComments || allowedComments.has(e.data.repo));
+                        const envelopes = params.limit ? visible.slice(0, params.limit) : visible;
+                        return wrapToolResult({
+                            success: true,
+                            count: envelopes.length,
+                            results: envelopes.map(e => ({
+                                repo: e.data.repo,
+                                entityId: e.id,
+                                entityType: e.entityType,
+                                data: cleanData(e.data),
+                            })),
+                        });
+                    }
                     let results = workspaceManager.list(params.entityType, params.limit);
-                    // Filter to accessible collections
+                    // Filter to accessible folders
                     const allowed = getAccessibleRepoNames(workspaceManager, getUser, authSvc);
                     if (allowed) {
                         results = results.filter(r => allowed.has(r.repoName));
@@ -563,9 +1172,9 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'get_related',
             label: 'Get Related Entries',
-            description: 'Get entries related to a given entry via wikilinks (cross-collection supported). Pass repo, entityType, entityId from search/list results.',
+            description: 'Get entries related to a given entry via wikilinks (cross-folder supported). Pass repo, entityType, entityId from search/list results.',
             parameters: T.Object({
-                repo: T.String({ description: 'Collection name' }),
+                repo: T.String({ description: 'Folder name' }),
                 entityType: T.String({ description: 'Entity type' }),
                 entityId: T.String({ description: 'Entity ID' }),
             }),
@@ -573,23 +1182,38 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                 try {
                     const repo = resolvePrivateRepo(params.repo);
                     if (!canAccessRepo(repo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${repo}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${repo}" not found` });
                     }
                     let related = workspaceManager.getRelated(repo, params.entityType, params.entityId);
-                    // Filter cross-collection results to accessible repos
+                    // Filter cross-folder results to accessible repos
                     const allowed = getAccessibleRepoNames(workspaceManager, getUser, authSvc);
                     if (allowed) {
                         related = related.filter(r => allowed.has(r.repoName));
                     }
+                    const relatedResults = related.map(r => ({
+                        repo: r.repoName,
+                        entityId: r.id,
+                        entityType: r.entityType,
+                        data: cleanData(r.data),
+                    }));
+                    // Comments anchored to this entry surface as related entries
+                    // (mirrors the MCP find_related incoming branch). The caller already
+                    // passed canAccessRepo for `repo`, so these are in-scope.
+                    if (commentSvc) {
+                        const anchored = commentVirtualEntity.findRelatedComments(commentSvc, repo, params.entityType, params.entityId);
+                        for (const e of anchored) {
+                            relatedResults.push({
+                                repo,
+                                entityId: e.id,
+                                entityType: e.entityType,
+                                data: cleanData(e.data),
+                            });
+                        }
+                    }
                     return wrapToolResult({
                         success: true,
-                        count: related.length,
-                        related: related.map(r => ({
-                            repo: r.repoName,
-                            entityId: r.id,
-                            entityType: r.entityType,
-                            data: cleanData(r.data),
-                        })),
+                        count: relatedResults.length,
+                        related: relatedResults,
                     });
                 }
                 catch (error) {
@@ -604,19 +1228,19 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'get_backlinks',
             label: 'Get Backlinks',
-            description: 'Get entries that link to a given entry (cross-collection supported). Pass repo, entityType, entityId from search/list results.',
+            description: 'Get entries that link to a given entry (cross-folder supported). Pass repo, entityType, entityId from search/list results.',
             parameters: T.Object({
-                repo: T.String({ description: 'Collection name' }),
+                repo: T.String({ description: 'Folder name' }),
                 entityType: T.String({ description: 'Entity type' }),
                 entityId: T.String({ description: 'Entity ID' }),
             }),
             execute: async (toolCallId, params) => {
                 try {
                     if (!canAccessRepo(params.repo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${params.repo}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${params.repo}" not found` });
                     }
                     let backlinks = workspaceManager.getBacklinks(params.repo, params.entityType, params.entityId);
-                    // Filter cross-collection results to accessible repos
+                    // Filter cross-folder results to accessible repos
                     const allowed = getAccessibleRepoNames(workspaceManager, getUser, authSvc);
                     if (allowed) {
                         backlinks = backlinks.filter(r => allowed.has(r.repoName));
@@ -644,16 +1268,16 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'validate_wikilinks',
             label: 'Validate Wikilinks',
-            description: 'Validate all wikilinks in an entry (checks same collection and cross-collection)',
+            description: 'Validate all wikilinks in an entry (checks same folder and cross-folder)',
             parameters: T.Object({
-                repo: T.String({ description: 'Collection name' }),
+                repo: T.String({ description: 'Folder name' }),
                 entityType: T.String({ description: 'Entity type' }),
                 entityId: T.String({ description: 'Entity ID' }),
             }),
             execute: async (toolCallId, params) => {
                 try {
                     if (!canAccessRepo(params.repo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${params.repo}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${params.repo}" not found` });
                     }
                     const validation = workspaceManager.validateWikilinks(params.repo, params.entityType, params.entityId);
                     return wrapToolResult({
@@ -688,7 +1312,7 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                     const summary = workspaceManager.getSummary();
                     const allowed = getAccessibleRepoNames(workspaceManager, getUser, authSvc);
                     if (allowed) {
-                        // Filter summary to accessible collections only
+                        // Filter summary to accessible folders only
                         const filteredByRepo = {};
                         let filteredTotal = 0;
                         for (const [repo, count] of Object.entries(summary.entitiesByRepo)) {
@@ -700,19 +1324,19 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                         return wrapToolResult({
                             success: true,
                             summary: {
-                                totalCollections: allowed.size,
+                                totalFolders: allowed.size,
                                 totalEntities: filteredTotal,
-                                entitiesByCollection: filteredByRepo,
+                                entitiesByFolder: filteredByRepo,
                             },
                         });
                     }
                     return wrapToolResult({
                         success: true,
                         summary: {
-                            totalCollections: summary.totalRepos,
+                            totalFolders: summary.totalRepos,
                             totalEntities: summary.totalEntities,
                             entitiesByType: summary.entitiesByType,
-                            entitiesByCollection: summary.entitiesByRepo,
+                            entitiesByFolder: summary.entitiesByRepo,
                         },
                     });
                 }
@@ -724,15 +1348,15 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                 }
             },
         },
-        // List collections
+        // List folders
         {
             name: 'list_repos',
-            label: 'List Collections',
-            description: 'List all collections in the workspace',
+            label: 'List Folders',
+            description: 'List all folders in the workspace',
             parameters: T.Object({}),
             execute: async (toolCallId, params) => {
                 try {
-                    let repos = workspaceManager.getAllRepoConfigs();
+                    let repos = workspaceManager.getContentRepoConfigs();
                     const allowed = getAccessibleRepoNames(workspaceManager, getUser, authSvc);
                     if (allowed) {
                         repos = repos.filter(r => allowed.has(r.name));
@@ -740,12 +1364,12 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                     return wrapToolResult({
                         success: true,
                         count: repos.length,
-                        collections: repos.map(r => ({
+                        folders: repos.map(r => ({
                             name: r.name,
                             type: r.type,
                             description: r.description,
                             path: r.path,
-                            private: r.private || false,
+                            personal: r.personal || false,
                         })),
                     });
                 }
@@ -757,40 +1381,35 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                 }
             },
         },
-        // Create a new collection
+        // Create a new folder
         {
-            name: 'create_collection',
-            label: 'Create Collection',
-            description: 'Create a new collection in the workspace. A collection is a git-backed container for entries. Private collections are only visible to the creating user.',
+            name: 'create_folder',
+            label: 'Create Folder',
+            description: 'Create a new shared folder in the workspace. Folders are git-backed containers for entries. New folders are shared with teammates who have access; the creator is granted admin. Every user already has a personal "My Folder" folder auto-provisioned — do not use this tool to create another one.',
             parameters: T.Object({
-                name: T.String({ description: 'Collection name in kebab-case (e.g., "client-projects")' }),
-                description: T.Optional(T.String({ description: 'Short description of the collection' })),
-                private: T.Optional(T.Boolean({ description: 'If true, creates a private collection visible only to you' })),
+                name: T.String({ description: 'Folder name in kebab-case (e.g., "client-projects")' }),
+                description: T.Optional(T.String({ description: 'Short description of the folder' })),
             }),
             execute: async (toolCallId, params) => {
                 try {
                     const user = getUser();
-                    // Non-private collections require admin; private collections can be created by anyone
-                    if (!params.private && user && !isAdminOrOwner(user.role)) {
-                        return wrapToolResult({ success: false, error: 'Only admins can create collections' });
-                    }
                     if (!/^[a-z0-9][a-z0-9-]*$/.test(params.name)) {
-                        return wrapToolResult({ success: false, error: 'Collection name must be kebab-case (lowercase letters, numbers, hyphens)' });
+                        return wrapToolResult({ success: false, error: 'Folder name must be kebab-case (lowercase letters, numbers, hyphens)' });
                     }
                     const { Workspace } = await import('../../core/workspace.js');
                     const workspace = new Workspace(workspacePath);
                     const repo = await workspace.registerRepo({
                         name: params.name,
                         description: params.description,
-                        private: params.private,
-                        ...(params.private && user ? { owner_id: user.id } : {}),
+                        owner_id: user?.id,
                     });
-                    // Reload workspace manager to pick up the new collection
                     workspaceManager.reloadConfig();
-                    onMutation?.({ action: 'created', repo: repo.name, entityType: '_collection', entityId: repo.name });
+                    if (user && authSvc)
+                        authSvc.grantFolderAccess(user.id, repo.name, 'admin');
+                    onMutation?.({ action: 'created', repo: repo.name, entityType: '_folder', entityId: repo.name });
                     return wrapToolResult({
                         success: true,
-                        collection: { name: repo.name, path: repo.path, description: repo.description },
+                        folder: { name: repo.name, path: repo.path, description: repo.description },
                     });
                 }
                 catch (error) {
@@ -804,7 +1423,7 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
             label: 'Query Dataset',
             description: 'Query rows from a dataset entity with optional filtering',
             parameters: T.Object({
-                repo: T.String({ description: 'Collection name' }),
+                repo: T.String({ description: 'Folder name' }),
                 entityId: T.String({ description: 'Dataset entity ID' }),
                 filter: T.Optional(T.Object({}, { description: 'Filter conditions (column: value or { gte, lte, contains })', additionalProperties: true })),
                 limit: T.Optional(T.Number({ description: 'Max rows to return' })),
@@ -812,21 +1431,24 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
             execute: async (toolCallId, params) => {
                 try {
                     if (!canAccessRepo(params.repo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${params.repo}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${params.repo}" not found` });
                     }
                     const graph = workspaceManager.getGraph(params.repo);
-                    const entity = graph.get('dataset', params.entityId);
-                    const schema = entity.data.schema;
+                    // Validates the entity exists and is a dataset before querying.
+                    graph.get('dataset', params.entityId);
                     let rows = graph.getDatasetRows(params.entityId, params.filter);
                     const total = rows.length;
                     if (params.limit && params.limit > 0) {
                         rows = rows.slice(0, params.limit);
                     }
+                    // Columns from the header, not the result rows — so a zero-match
+                    // filter or header-only dataset still reports the real columns.
+                    const columns = graph.getDatasetColumns(params.entityId);
                     return wrapToolResult({
                         success: true,
                         rows,
                         total,
-                        schema,
+                        columns,
                     });
                 }
                 catch (error) {
@@ -843,7 +1465,7 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
             label: 'Append Rows',
             description: 'Append rows to a dataset entity',
             parameters: T.Object({
-                repo: T.String({ description: 'Collection name' }),
+                repo: T.String({ description: 'Folder name' }),
                 entityId: T.String({ description: 'Dataset entity ID' }),
                 rows: T.Array(T.Object({}, { additionalProperties: true }), { description: 'Rows to append' }),
                 commitMessage: T.Optional(T.String({ description: 'Custom commit message' })),
@@ -851,13 +1473,14 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
             execute: async (toolCallId, params) => {
                 try {
                     if (!canAccessRepo(params.repo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${params.repo}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${params.repo}" not found` });
                     }
                     const graph = workspaceManager.getGraph(params.repo);
                     // Get current row count before appending
                     const beforeRows = graph.getDatasetRows(params.entityId);
                     await graph.appendDatasetRows(params.entityId, params.rows, params.commitMessage);
                     const afterRows = graph.getDatasetRows(params.entityId);
+                    onMutation?.({ action: 'updated', repo: params.repo, entityType: 'dataset', entityId: params.entityId });
                     return wrapToolResult({
                         success: true,
                         rowsAdded: afterRows.length - beforeRows.length,
@@ -877,30 +1500,22 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'get_entity_schema',
             label: 'Get Entry Schema',
-            description: 'Get the schema definition for an entry type (useful for understanding required fields)',
+            description: 'Get the authoritative schema for an entry type. Returns each field with its type, whether it is optional, the description from the Zod schema, the full enum value list when applicable, and any default. Call this before writing enum-shaped fields (stage, status, category, priority, etc.) — the validator only accepts the values listed under `enum`.',
             parameters: T.Object({
                 entityType: T.String({ description: 'Entity type' }),
             }),
             execute: async (toolCallId, params) => {
                 try {
-                    const schema = ENTITY_SCHEMAS[params.entityType];
-                    if (!schema) {
+                    const registry = workspaceManager.getSchemaRegistry();
+                    const knownTypes = new Set(registry.getAllTypes());
+                    if (!knownTypes.has(params.entityType)) {
                         return wrapToolResult({
                             success: false,
-                            error: `Unknown entity type: ${params.entityType}`,
+                            error: `Unknown entity type: ${params.entityType}. Known types: ${[...knownTypes].sort().join(', ')}`,
                         });
                     }
-                    // Extract schema shape (simplified)
-                    const shape = schema.shape || {};
-                    const fields = {};
-                    for (const [key, value] of Object.entries(shape)) {
-                        const field = value;
-                        fields[key] = {
-                            type: field._def.typeName || 'unknown',
-                            optional: field.isOptional() || false,
-                            description: field._def.description || '',
-                        };
-                    }
+                    const schema = registry.getSchema(params.entityType);
+                    const fields = describeZodObject(schema);
                     return wrapToolResult({
                         success: true,
                         entityType: params.entityType,
@@ -919,15 +1534,15 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'lint_entities',
             label: 'Lint Entries',
-            description: 'Check for missing recommended fields across entries. Returns incomplete entries with their missing fields. Use to discover entries that need enrichment. Optionally filter by collection or entry type.',
+            description: 'Check for missing recommended fields across entries. Returns incomplete entries with their missing fields. Use to discover entries that need enrichment. Optionally filter by folder or entry type.',
             parameters: T.Object({
-                repo: T.Optional(T.String({ description: 'Optional: limit to specific collection' })),
+                repo: T.Optional(T.String({ description: 'Optional: limit to specific folder' })),
                 entityType: T.Optional(T.String({ description: 'Optional: limit to specific entity type (e.g. "project", "deal")' })),
             }),
             execute: async (toolCallId, params) => {
                 try {
                     if (params.repo && !canAccessRepo(params.repo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${params.repo}" not found` });
+                        return wrapToolResult({ success: false, error: `Folder "${params.repo}" not found` });
                     }
                     let issues = await lintWorkspace(workspaceManager, {
                         repo: params.repo,
@@ -977,11 +1592,11 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
             parameters: T.Object({
                 entityTypes: T.Optional(T.Array(T.String(), { description: 'Entity types to check (e.g. ["person", "client"])' })),
                 minAgeDays: T.Optional(T.Number({ description: 'Only flag entities older than N days' })),
-                repos: T.Optional(T.Array(T.String(), { description: 'Collection names to scan (default: all)' })),
+                repos: T.Optional(T.Array(T.String(), { description: 'Folder names to scan (default: all)' })),
             }),
             execute: async (toolCallId, params) => {
                 try {
-                    // Scope to accessible collections
+                    // Scope to accessible folders
                     const allowed = getAccessibleRepoNames(workspaceManager, getUser, authSvc);
                     let repos = params.repos;
                     if (allowed) {
@@ -1032,98 +1647,6 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                 });
             },
         },
-        // ── View Management Tools ──
-        {
-            name: 'list_views',
-            label: 'List Views',
-            description: 'List the current user\'s saved views.',
-            parameters: T.Object({}),
-            execute: async () => {
-                if (!authSvc)
-                    return wrapToolResult({ success: false, error: 'Auth service not available' });
-                const userId = getUser()?.id ?? 0;
-                const views = authSvc.getUserViews(userId);
-                return wrapToolResult({ views });
-            },
-        },
-        {
-            name: 'create_view',
-            label: 'Create View',
-            description: 'Create a new saved view for the current user. Views appear as tabs in the toolbar.',
-            parameters: T.Object({
-                name: T.String({ description: 'View name (e.g. "My Tasks", "Open Projects")' }),
-                selectedType: T.Optional(T.String({ description: 'Entity type filter (e.g. "task", "project"). Omit for all types.' })),
-                groupBy: T.Optional(T.String({ description: 'Column key to group by (e.g. "status", "priority")' })),
-            }),
-            execute: async (_toolCallId, params) => {
-                if (!authSvc)
-                    return wrapToolResult({ success: false, error: 'Auth service not available' });
-                const userId = getUser()?.id ?? 0;
-                const config = {
-                    selectedType: params.selectedType ?? null,
-                    groupBy: params.groupBy ?? null,
-                    sortKey: 'name',
-                    sortAsc: true,
-                    filters: { text: {}, enum: {}, date: {} },
-                };
-                const view = authSvc.createUserView(userId, params.name, 'list', config);
-                return wrapToolResult({
-                    success: true,
-                    view: { id: view.id, name: view.name, viewType: view.viewType, config: view.config },
-                    message: `Created view "${params.name}". It will appear as a tab in the toolbar.`,
-                });
-            },
-        },
-        {
-            name: 'update_view',
-            label: 'Update View',
-            description: 'Update an existing saved view\'s name or configuration.',
-            parameters: T.Object({
-                id: T.Number({ description: 'View ID' }),
-                name: T.Optional(T.String({ description: 'New view name' })),
-                selectedType: T.Optional(T.String({ description: 'Entity type filter (use "all" to clear)' })),
-                groupBy: T.Optional(T.String({ description: 'Column key to group by (use "none" to clear)' })),
-            }),
-            execute: async (_toolCallId, params) => {
-                if (!authSvc)
-                    return wrapToolResult({ success: false, error: 'Auth service not available' });
-                const userId = getUser()?.id ?? 0;
-                const existing = authSvc.getUserView(params.id, userId);
-                if (!existing)
-                    return wrapToolResult({ success: false, error: `View ${params.id} not found` });
-                const fields = {};
-                if (params.name)
-                    fields.name = params.name;
-                if (params.selectedType !== undefined || params.groupBy !== undefined) {
-                    const config = { ...existing.config };
-                    if (params.selectedType !== undefined)
-                        config.selectedType = params.selectedType === 'all' ? null : params.selectedType;
-                    if (params.groupBy !== undefined)
-                        config.groupBy = params.groupBy === 'none' ? null : params.groupBy;
-                    fields.config = config;
-                }
-                authSvc.updateUserView(params.id, userId, fields);
-                return wrapToolResult({ success: true, message: `Updated view "${existing.name}".` });
-            },
-        },
-        {
-            name: 'delete_view',
-            label: 'Delete View',
-            description: 'Delete a saved view.',
-            parameters: T.Object({
-                id: T.Number({ description: 'View ID to delete' }),
-            }),
-            execute: async (_toolCallId, params) => {
-                if (!authSvc)
-                    return wrapToolResult({ success: false, error: 'Auth service not available' });
-                const userId = getUser()?.id ?? 0;
-                const existing = authSvc.getUserView(params.id, userId);
-                if (!existing)
-                    return wrapToolResult({ success: false, error: `View ${params.id} not found` });
-                authSvc.deleteUserView(params.id, userId);
-                return wrapToolResult({ success: true, message: `Deleted view "${existing.name}".` });
-            },
-        },
         // Mark onboarding complete
         {
             name: 'mark_onboarded',