studiograph 1.3.47 → 1.3.48-beta.0

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

@@ -7,11 +7,18 @@
  * - 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 { SyncStateManager } from '../../services/sync/sync-state.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, } from '../../services/entity-mutations.js';
+import { listRepoAssets } from '../../services/asset-listing.js';
+import { assetEmbed } from '../../core/embeds.js';
 /**
  * Helper to wrap tool results in AgentToolResult format
  */
@@ -31,128 +38,226 @@ 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 (user.role === 'admin')
-        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 (user.role === 'admin') {
-        // Admins 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 (user.role === 'admin')
-        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) {
     const getUser = getCurrentUser ?? (() => null);
     const authSvc = authService ?? 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 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;
+        if (entityType === 'asset') {
+            // The schema enum already excludes `asset` (see
+            // getAgentAllowedEntityTypes). This is the runtime defense-in-depth
+            // path for clients that bypass the enum.
+            return wrapToolResult({
+                success: false,
+                error: 'Asset entries cannot be created via create_entity — they require a binary blob plus a sidecar text file. Use the import_file tool with a local file path, or have the user upload via the workspace import dialog.',
+            });
+        }
+        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 Entity',
-            description: 'Create a new entity in a collection. Always validate required fields before calling. Collection is auto-resolved for app-defined entity types.',
+            label: 'Create Entry',
+            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)' })),
+                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 double-escaped newlines from LLM JSON output
-                    const sanitizedContent = (params.content || '').replace(/\\n/g, '\n');
-                    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;
+                        }
+                    }
+                    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({
@@ -165,31 +270,51 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         // Get entity
         {
             name: 'get_entity',
-            label: 'Get Entity',
-            description: 'Retrieve full entity details. Use repo, entityType, entityId from search/list results. entityType is optional — if omitted it is read from the file.',
+            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' }),
             }),
             execute: async (toolCallId, params) => {
                 try {
-                    if (!canAccessRepo(params.repo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${params.repo}" not found` });
+                    const repo = resolvePrivateRepo(params.repo);
+                    if (!canAccessRepo(repo, workspaceManager, getUser, authSvc)) {
+                        return wrapToolResult({ success: false, error: `Folder "${repo}" not found` });
                     }
-                    const graph = workspaceManager.getGraph(params.repo);
-                    const entity = params.entityType
-                        ? graph.get(params.entityType, params.entityId)
-                        : graph.getById(params.entityId);
+                    const graph = workspaceManager.getGraph(repo);
+                    // 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: {
                             entityId: entity.id,
                             entityType: entity.entityType,
-                            repo: params.repo,
+                            repo,
                             path: entity.path,
                             data: cleanData(entity.data),
-                            content: entity.document.content,
+                            content: liveBody ?? entity.document.content,
                             wikilinks: entity.document.wikilinks,
                         },
                     });
@@ -205,59 +330,105 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         // Update entity
         {
             name: 'update_entity',
-            label: 'Update Entity',
-            description: 'Update an existing entity. Collection is auto-resolved for app-defined types.',
+            label: 'Update Entry',
+            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)' })),
                 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 double-escaped newlines from LLM JSON output
+                    const actor = effectiveGitUser();
                     const sanitizedContent = params.content !== undefined
-                        ? params.content.replace(/\\n/g, '\n') : 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;
+                        }
+                    }
+                    const options = prepareUpdatePayload({
                         entityType: params.entityType,
                         entityId: params.entityId,
-                        data: dataWithMeta,
+                        data: params.data,
                         content: sanitizedContent,
                         commitMessage: params.commitMessage,
-                    });
-                    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),
-                        },
-                        message: `Updated ${params.entityType}: ${params.entityId}. Auto-committed — ready to push.`,
-                    });
+                    }, 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',
@@ -265,13 +436,157 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                 }
             },
         },
+        // 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,
+                        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' });
+                }
+            },
+        },
         // Delete entity
         {
             name: 'delete_entity',
-            label: 'Delete Entity',
-            description: 'Delete an entity. Use with caution! Collection is auto-resolved for app-defined types.',
+            label: 'Delete Entry',
+            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' })),
@@ -280,20 +595,25 @@ 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.`,
-                    });
+                    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.`,
+                        });
+                    }
+                    finally {
+                        onAgentActivity?.('leave', repoName);
+                    }
                 }
                 catch (error) {
                     return wrapToolResult({
@@ -307,46 +627,93 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'import_file',
             label: 'Import File',
-            description: 'Import a local file as a Studiograph entity. Supports .md and .txt (→ note) and .csv (→ dataset). The file is read from the local filesystem and converted to an entity with appropriate frontmatter.',
+            description: 'Import a local file as a Studiograph entry. Text formats become typed entries (.md/.txt → note, .csv → dataset). Binary formats (PDF, images, design files, video, audio, archives) become asset entries.',
             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 asset uploads)' })),
                 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 { uploadAsset } = await import('../../services/asset-upload-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 wrapper. The text-import path doesn't
+                    // know how to handle .indd / .pptx / etc. and would either reject
+                    // them or (for .pdf) mistakenly land them as a `note` entity with
+                    // extracted body text. Route to uploadAsset for parity with the
+                    // web import dispatcher.
+                    if (isAssetUploadExtension(fname)) {
+                        const buffer = readFileSync(filePath);
+                        const result = await uploadAsset({
+                            graph,
+                            filename: fname,
+                            buffer,
+                            workspacePath: graph.getWorkspaceRoot(),
+                        });
+                        onMutation?.({ action: 'created', repo: params.folder, entityType: 'asset', entityId: result.entityId });
+                        return wrapToolResult({
+                            success: true,
+                            entityType: 'asset',
+                            entityId: result.entityId,
+                            asset_kind: result.asset_kind,
+                            asset_size: result.asset_size,
+                            pages: result.pages,
+                            message: `Imported ${fname} as asset/${result.entityId} 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,
                     });
                 }
@@ -361,10 +728,10 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         // Rename entity (change ID)
         {
             name: 'rename_entity',
-            label: 'Rename Entity',
-            description: 'Rename an entity 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.',
+            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. 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)' }),
@@ -373,12 +740,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);
@@ -398,41 +764,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 Entity',
-            description: 'Move an entity 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}`);
@@ -454,12 +820,12 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         // Search entities
         {
             name: 'search_entities',
-            label: 'Search Entities',
-            description: 'Search for entities across collections with filters.',
+            label: 'Search Entries',
+            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({
@@ -471,9 +837,9 @@ 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;
+                    let repoNames = params.repoNames?.map((r) => resolvePrivateRepo(r));
                     if (allowed) {
                         repoNames = repoNames
                             ? repoNames.filter((r) => allowed.has(r))
@@ -511,8 +877,8 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         // List entities
         {
             name: 'list_entities',
-            label: 'List Entities',
-            description: 'List all entities of a given type (or all types)',
+            label: 'List Entries',
+            description: 'List all entries of a given type (or all types)',
             parameters: T.Object({
                 entityType: T.Optional(T.String({ description: 'Entity type to list (omit for all)' })),
                 limit: T.Optional(T.Number({ description: 'Max results' })),
@@ -520,7 +886,7 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
             execute: async (toolCallId, params) => {
                 try {
                     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));
@@ -547,20 +913,21 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         // Get related entities
         {
             name: 'get_related',
-            label: 'Get Related Entities',
-            description: 'Get entities related to a given entity via wikilinks (cross-collection supported). Pass repo, entityType, entityId from search/list results.',
+            label: 'Get Related Entries',
+            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' }),
             }),
             execute: async (toolCallId, params) => {
                 try {
-                    if (!canAccessRepo(params.repo, workspaceManager, getUser, authSvc)) {
-                        return wrapToolResult({ success: false, error: `Collection "${params.repo}" not found` });
+                    const repo = resolvePrivateRepo(params.repo);
+                    if (!canAccessRepo(repo, workspaceManager, getUser, authSvc)) {
+                        return wrapToolResult({ success: false, error: `Folder "${repo}" not found` });
                     }
-                    let related = workspaceManager.getRelated(params.repo, params.entityType, params.entityId);
-                    // Filter cross-collection results to accessible repos
+                    let related = workspaceManager.getRelated(repo, params.entityType, params.entityId);
+                    // Filter cross-folder results to accessible repos
                     const allowed = getAccessibleRepoNames(workspaceManager, getUser, authSvc);
                     if (allowed) {
                         related = related.filter(r => allowed.has(r.repoName));
@@ -588,19 +955,19 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'get_backlinks',
             label: 'Get Backlinks',
-            description: 'Get entities that link to a given entity (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));
@@ -628,16 +995,16 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'validate_wikilinks',
             label: 'Validate Wikilinks',
-            description: 'Validate all wikilinks in an entity (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({
@@ -672,7 +1039,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)) {
@@ -684,19 +1051,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,
                         },
                     });
                 }
@@ -708,11 +1075,11 @@ 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 {
@@ -724,12 +1091,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,
                         })),
                     });
                 }
@@ -741,40 +1108,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 entities. 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 && user.role !== 'admin') {
-                        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) {
@@ -788,7 +1150,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' })),
@@ -796,21 +1158,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) {
@@ -827,7 +1192,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' })),
@@ -835,13 +1200,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,
@@ -860,31 +1226,23 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         // Get entity schema
         {
             name: 'get_entity_schema',
-            label: 'Get Entity Schema',
-            description: 'Get the schema definition for an entity type (useful for understanding required fields)',
+            label: 'Get Entry Schema',
+            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,
@@ -902,16 +1260,16 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         // Lint entities
         {
             name: 'lint_entities',
-            label: 'Lint Entities',
-            description: 'Check for missing recommended fields across entities. Returns incomplete entities with their missing fields. Use to discover entities that need enrichment. Optionally filter by collection or entity type.',
+            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 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,
@@ -957,16 +1315,15 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         {
             name: 'find_orphans',
             label: 'Find Orphans',
-            description: 'Find entities with zero inbound wikilink references. Optionally tombstone them to exclude from future syncs.',
+            description: 'Find entries with zero inbound wikilink references.',
             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)' })),
-                tombstone: T.Optional(T.Boolean({ description: 'Add orphans to sync-state tombstones' })),
+                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) {
@@ -977,13 +1334,6 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                         minAgeDays: params.minAgeDays,
                         repos,
                     });
-                    // Tombstone if requested
-                    if (params.tombstone && workspacePath && result.orphans.length > 0) {
-                        const syncState = new SyncStateManager(workspacePath);
-                        for (const orphan of result.orphans) {
-                            syncState.addTombstone(orphan.entityId);
-                        }
-                    }
                     // Group by type for summary
                     const byType = {};
                     for (const o of result.orphans) {
@@ -993,7 +1343,6 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                         success: true,
                         totalScanned: result.totalScanned,
                         totalOrphans: result.totalOrphans,
-                        tombstoned: params.tombstone ? result.totalOrphans : 0,
                         byType,
                         orphans: result.orphans.slice(0, 50), // limit response size
                     });
@@ -1009,8 +1358,8 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
         // Highlight entities in graph view
         {
             name: 'highlight_entities',
-            label: 'Highlight Entities',
-            description: 'Highlight specific entities in the graph view. Pass entity IDs to highlight them (dimming all others). Pass an empty array to clear highlights.',
+            label: 'Highlight Entries',
+            description: 'Highlight specific entries in the graph view. Pass entry IDs to highlight them (dimming all others). Pass an empty array to clear highlights.',
             parameters: T.Object({
                 entityIds: T.Array(T.String(), { description: 'Entity IDs to highlight in the graph' }),
             }),
@@ -1025,96 +1374,50 @@ export function createGraphTools(workspaceManager, gitUser, workspacePath, onHig
                 });
             },
         },
-        // ── View Management Tools ──
+        // Mark onboarding complete
         {
-            name: 'list_views',
-            label: 'List Views',
-            description: 'List the current user\'s saved views.',
+            name: 'mark_onboarded',
+            label: 'Mark Onboarded',
+            description: 'Mark the current user as onboarded. Call this when the interview/onboarding flow is complete.',
             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) => {
+            execute: async (_toolCallId) => {
                 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.`,
-                });
+                authSvc.setOnboarded(userId, true);
+                return wrapToolResult({ success: true, message: 'User marked as onboarded.' });
             },
         },
+        // Update workspace description (ABOUT.md)
         {
-            name: 'update_view',
-            label: 'Update View',
-            description: 'Update an existing saved view\'s name or configuration.',
+            name: 'update_workspace_about',
+            label: 'Update Workspace Description',
+            description: 'Write or update the workspace description (ABOUT.md). Use this to synthesize a description from the knowledge graph after onboarding, or when asked to sync the workspace description. The content should be a concise narrative covering the organization\'s identity, team, capabilities, and values — written in markdown.',
             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)' })),
+                content: T.String({ description: 'The full markdown content for the workspace description' }),
             }),
             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;
+                try {
+                    const { Workspace } = await import('../../core/workspace.js');
+                    const workspace = new Workspace(workspacePath);
+                    workspace.writeAbout(params.content);
+                    onMutation?.({ action: 'updated', repo: '_workspace', entityType: '_workspace', entityId: 'about' });
+                    return wrapToolResult({ success: true, message: 'Workspace description updated.' });
+                }
+                catch (err) {
+                    return wrapToolResult({ success: false, error: err.message || 'Failed to write ABOUT.md' });
                 }
-                authSvc.updateUserView(params.id, userId, fields);
-                return wrapToolResult({ success: true, message: `Updated view "${existing.name}".` });
             },
         },
+        // Reset conversation
         {
-            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}".` });
+            name: 'reset_conversation',
+            label: 'Reset Conversation',
+            description: 'Clear the current conversation and start fresh. Use when the user asks to "start over", "reset", "clear the chat", or "new conversation".',
+            parameters: T.Object({}),
+            execute: async (_toolCallId) => {
+                onMutation?.({ action: 'deleted', repo: '_conversation', entityType: '_conversation', entityId: 'reset' });
+                return wrapToolResult({ success: true, message: 'Conversation reset.' });
             },
         },
     ];