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

package/dist/server/routes/graph-api.js

@@ -2,132 +2,65 @@
  * Graph API routes
  *
  * REST façade over WorkspaceManager.
- * Enforces per-collection access when users are authenticated via JWT.
+ * Enforces per-folder access when users are authenticated via JWT.
  * API key / open mode → full access (no filtering).
  */
+import { isArchivedRepo } from '../../core/types.js';
 import { isWorkspaceOwner } from '../../services/auth-service.js';
+import { WorkspaceAccessService } from '../../services/workspace-access.js';
 import { Workspace } from '../../core/workspace.js';
-import { existsSync } from 'fs';
-import { join } from 'path';
-/** Convert an AuthUser from the request to a GitUser for commit attribution. */
-function reqGitUser(req) {
-    const user = req.user;
-    if (!user)
-        return undefined;
-    return { id: String(user.id), name: user.displayName, email: user.email };
-}
-/** Get the list of repos the current user can access (content visibility). */
-function getAccessibleRepos(req, workspaceManager, authService) {
-    const allRepos = workspaceManager.getAllRepoConfigs();
-    const user = req.user;
-    if (!user)
-        return allRepos; // API key / open mode → full access
-    // Folder membership is the sole source of truth for content visibility.
-    const allowed = new Set(authService.getUserFolders(user.id));
-    return allRepos.filter(r => allowed.has(r.name));
-}
-/** Check if the current user can access a specific repo's contents. */
-function hasRepoAccess(req, repoName, workspaceManager, authService) {
-    const user = req.user;
-    if (!user)
-        return true; // API key / open mode
-    return authService.getUserFolders(user.id).includes(repoName);
-}
-/** Check if the current user is a folder admin of the given repo, or the workspace owner. */
-function isFolderAdminOrOwner(req, repoName, authService) {
-    const user = req.user;
-    if (!user)
-        return true; // API key / open mode → admin-equivalent
-    if (authService.isFolderAdmin(user.id, repoName))
-        return true;
-    return isWorkspaceOwner(user.role);
-}
-/**
- * Build a set of all entity IDs visible to the current user.
- * Used to filter wikilinks so users don't see links to entities
- * in collections they can't access.
- */
-function getAccessibleEntityIds(req, workspaceManager, authService) {
-    const user = req.user;
-    if (!user)
-        return null; // API key / open mode → no filtering
-    const repos = getAccessibleRepos(req, workspaceManager, authService);
-    const ids = new Set();
-    for (const repo of repos) {
-        try {
-            const graph = workspaceManager.getGraph(repo.name);
-            for (const e of graph.search({})) {
-                ids.add(e.id);
-            }
-        }
-        catch { /* skip */ }
-    }
-    return ids;
-}
-/** Filter wikilinks to only those pointing to accessible entities. */
-function filterWikilinks(wikilinks, accessibleIds) {
-    if (!accessibleIds)
-        return wikilinks;
-    return wikilinks.filter(id => accessibleIds.has(id));
-}
-/**
- * Guard against non-admin members creating eager skills in shared folders —
- * they would bloat the system prompt for everyone with folder access.
- * Returns an error string or null if the operation is allowed.
- */
-function checkEagerSkillPermission(req, entityType, data, repoName, workspaceManager, authService) {
-    if (entityType !== 'skill')
-        return null;
-    if (!data || data.loading !== 'eager')
-        return null;
-    const user = req.user;
-    if (!user)
-        return null; // API key / open mode
-    const privateRepo = workspaceManager.getUserPrivateRepo(user.id);
-    if (privateRepo && privateRepo.name === repoName)
-        return null;
-    if (isFolderAdminOrOwner(req, repoName, authService))
-        return null;
-    return 'Creating an eager skill in a shared folder requires folder admin or workspace owner. Save this skill to your private folder or set loading to "on-demand".';
-}
-export async function registerGraphApiRoutes(fastify, workspaceManager, authService, wsHub, sessionManager, yjsManager) {
+import { seedFolderName, seedFolderUserId, resolveFolderDisplayName } from '../../core/seed-folder.js';
+import { createSharedFolder, FolderCreationError } from '../../services/folder-creation.js';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { basename, dirname, join } from 'path';
+import { RESERVED_ENTITY_TYPES } from '../../core/validation.js';
+import { validateFolderPath } from '../../core/folder-paths.js';
+import { deriveAssetDisplayName, stripFrontmatter } from '../../core/embeds.js';
+import { parseFrontmatterCacheFree } from '../../core/history-diff.js';
+import { StaleBaseRevisionError } from '../../core/graph.js';
+import { checkEagerSkillPermission, filterWikilinks, getAccessibleEntityIds, getAccessibleRepos, getContentRepos, graphForAdmin as resolveGraphForAdmin, graphForRead as resolveGraphForRead, graphForWrite as resolveGraphForWrite, hasRepoAccess, isFolderAdminOrOwner, reqGitUser, reqUser, } from './graph-api-access.js';
+import { buildFontSkill, isFontAssetRow } from '../../services/fonts/font-skill-service.js';
+import { BridgeError, assertCanChangeUserHandle, validateUserHandleInPayload } from '../../services/user-person-bridge.js';
+import { assertEntityRefs, EntityRefError, UnknownUserRefError } from '../../services/entity-mutations.js';
+import { assetDeleteDenial } from '../../services/asset-delete-authz.js';
+import { log } from '../../utils/log.js';
+export async function registerGraphApiRoutes(fastify, workspaceManager, authService, wsHub, sessionManager) {
+    // ARCHITECTURAL BOUNDARY: every per-route graph resolution flows through
+    // this service so the act of getting a graph IS the access check. Do not
+    // call `workspaceManager.getGraph(repo)` from a request-scoped handler —
+    // use `accessService.graphFor*(reqUser(req), repo)` instead. A security
+    // audit (2026-05) flagged the previous opt-in pattern (route had to
+    // remember `hasRepoAccess()` before `getGraph()`) as an architectural
+    // risk; if you find yourself reaching for the raw WM here, that's the
+    // smell the audit was about.
+    const accessService = new WorkspaceAccessService(workspaceManager, authService);
+    const graphForRead = (req, reply, repoName) => resolveGraphForRead(accessService, req, reply, repoName);
+    const graphForWrite = (req, reply, repoName) => resolveGraphForWrite(accessService, req, reply, repoName);
+    const graphForAdmin = (req, reply, repoName) => resolveGraphForAdmin(accessService, req, reply, repoName);
     // POST /api/repos — any authenticated user can create a folder.
     // The creator is granted folder-admin access automatically.
+    // Shared logic lives in services/folder-creation.ts so the MCP tool
+    // create_repo behaves identically.
     fastify.post('/api/repos', async (req, reply) => {
         const user = req.user;
         const { name, display_name, description } = req.body || {};
-        if (!name || !/^[a-z0-9][a-z0-9-]*$/.test(name)) {
-            return reply.status(400).send({ error: 'Folder name must be kebab-case' });
-        }
         try {
-            const workspace = new Workspace(workspaceManager['workspacePath']);
-            // Folders created here are shared team folders. Every user already
-            // has one auto-provisioned private "My Entries" folder (see
-            // ensurePrivateCollection in auth-api.ts) — passing private=true
-            // here would collide with the one-private-per-user rule.
-            const repo = await workspace.registerRepo({
-                name,
-                display_name: display_name || undefined,
-                description,
-                owner_id: user?.id,
-            });
-            workspaceManager.reloadConfig();
-            if (user)
-                authService.grantFolderAccess(user.id, name, 'admin');
-            wsHub?.broadcast({
-                type: 'collection_created', repo: name,
-                actor: user?.displayName ?? 'API',
-                timestamp: new Date().toISOString(),
-            });
+            const repo = await createSharedFolder(workspaceManager, authService, { name, display_name, description }, user, wsHub);
             return reply.status(201).send(repo);
         }
         catch (err) {
-            return reply.status(409).send({ error: err.message });
+            if (err instanceof FolderCreationError) {
+                const status = err.code === 'invalid_name' ? 400
+                    : err.code === 'duplicate' ? 409
+                        : 500;
+                return reply.status(status).send({ error: err.message });
+            }
+            return reply.status(500).send({ error: err?.message ?? String(err) });
         }
     });
     // DELETE /api/repos/:repo — folder admin or workspace owner only.
     fastify.delete('/api/repos/:repo', async (req, reply) => {
-        if (!isFolderAdminOrOwner(req, req.params.repo, authService)) {
+        if (!isFolderAdminOrOwner(req, req.params.repo, workspaceManager, authService)) {
             return reply.status(403).send({ error: 'Folder admin access required' });
         }
         const { repo } = req.params;
@@ -139,11 +72,63 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
                 return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
             }
             const repoConfig = config.repos[repoIndex];
+            // System folders (the reserved Workspace Assets store) are an app
+            // invariant — undeletable, so nothing needs to recreate them on boot.
+            if (repoConfig.system) {
+                return reply.status(403).send({ error: 'This is a system folder and cannot be deleted.' });
+            }
             const repoPath = join(workspaceManager['workspacePath'], repoConfig.path);
+            // Reclaim the repo's assets (assets.db rows + blobs) BEFORE destroying
+            // the repo dir. Assets are workspace-global — the index lives in
+            // .studiograph/assets.db and blobs live outside the repo dir (R2 bucket,
+            // or .studiograph/assets/{id}/ locally) — so the rmSync below does NOT
+            // reclaim them. Skipping this leaves orphan assets.db rows with a dead
+            // repo reference (the Meld-class bug) and orphan blobs. deleteAssetById
+            // deletes the blob + index row + caption state and is self-isolating
+            // (never throws), so a failed blob delete still drops the index row.
+            const assetIndex = workspaceManager.getAssetIndex();
+            try {
+                const graph = workspaceManager.getGraph(repo);
+                for (const row of assetIndex.listByRepo(repo)) {
+                    // Per-row isolation: one bad blob delete must not abort the sweep
+                    // and strand the rest. (deleteAssetById is already self-isolating,
+                    // but a rejected await would otherwise break the loop.)
+                    try {
+                        await graph.deleteAssetById(row.assetId, row.filename);
+                    }
+                    catch (err) {
+                        log.warn(`[repo-delete] blob ${row.assetId} for ${repo} failed: ${err?.message ?? err}`);
+                    }
+                }
+            }
+            catch (err) {
+                log.warn(`[repo-delete] asset blob cleanup for ${repo} failed: ${err?.message ?? err}`);
+            }
+            // Drop the index rows UNCONDITIONALLY — even if the blob loop above
+            // threw (e.g. getGraph failed, or no asset backend is configured so
+            // deleteAssetById short-circuits), orphan index rows with a dead repo
+            // reference are exactly the Meld-class bug we're closing. Idempotent
+            // when the loop already removed them.
+            try {
+                assetIndex.deleteByRepo(repo);
+            }
+            catch (err) {
+                log.warn(`[repo-delete] asset index cleanup for ${repo} failed: ${err?.message ?? err}`);
+            }
             // Remove from config
             config.repos.splice(repoIndex, 1);
             workspace.writeConfig(config);
-            workspace.pushWorkspaceConfig(`Remove collection: ${repo}`);
+            workspace.pushWorkspaceConfig(`Remove folder: ${repo}`);
+            // Durable seed deletion: if a user deletes THEIR OWN seed "My Folder",
+            // record a tombstone so the boot sweep + login provisioning don't
+            // resurrect it. Only the seed's owner deleting it counts — when a folder
+            // admin/workspace owner deletes someone else's (e.g. shared) seed, we do
+            // NOT tombstone, so that user's home re-provisions on their next login
+            // rather than being permanently removed by another person's action.
+            const seedUserId = seedFolderUserId(repo);
+            if (seedUserId != null && seedUserId === reqUser(req)?.id) {
+                authService.setSeedFolderDeleted(seedUserId, true);
+            }
             // Delete files
             const { rmSync } = await import('fs');
             if (existsSync(repoPath)) {
@@ -151,7 +136,7 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             }
             workspaceManager.reloadConfig();
             wsHub?.broadcast({
-                type: 'collection_deleted', repo,
+                type: 'folder_deleted', repo,
                 actor: req.user?.displayName ?? 'API',
                 timestamp: new Date().toISOString(),
             });
@@ -161,17 +146,82 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             return reply.status(500).send({ error: err.message });
         }
     });
+    // POST /api/repos/:repo/archive — reversible repo-level hide. Folder admin or
+    // workspace owner only. Unlike DELETE (permanent, human/web-only), archive is
+    // lossless + identity-preserving and is also exposed to agents/MCP. The
+    // archived folder drops out of the sidebar + knowledge surfaces on the next
+    // /api/repos fetch; the live-refresh + "Archived folders" management panel are
+    // a separate Tier-2 web PR.
+    fastify.post('/api/repos/:repo/archive', async (req, reply) => {
+        if (!isFolderAdminOrOwner(req, req.params.repo, workspaceManager, authService)) {
+            return reply.status(403).send({ error: 'Folder admin access required' });
+        }
+        try {
+            const updated = await workspaceManager.setRepoArchived(req.params.repo, true, reqUser(req)?.handle);
+            return reply.send({ success: true, repo: updated });
+        }
+        catch (err) {
+            const status = err?.message?.includes('not found') ? 404
+                : err?.message?.includes('System folders') ? 403
+                    : 500;
+            return reply.status(status).send({ error: err.message });
+        }
+    });
+    // POST /api/repos/:repo/unarchive — restore an archived folder. Same authz as
+    // archive (archived folders keep their folder_access rows, so folder-admin
+    // still resolves).
+    fastify.post('/api/repos/:repo/unarchive', async (req, reply) => {
+        if (!isFolderAdminOrOwner(req, req.params.repo, workspaceManager, authService)) {
+            return reply.status(403).send({ error: 'Folder admin access required' });
+        }
+        try {
+            const updated = await workspaceManager.setRepoArchived(req.params.repo, false, reqUser(req)?.handle);
+            return reply.send({ success: true, repo: updated });
+        }
+        catch (err) {
+            // Map the system-folder rejection to 403 consistently with /archive
+            // (setRepoArchived guards `system` before the idempotency no-op, so even
+            // an unarchive on a system folder surfaces it).
+            const status = err?.message?.includes('not found') ? 404
+                : err?.message?.includes('System folders') ? 403
+                    : 500;
+            return reply.status(status).send({ error: err.message });
+        }
+    });
+    // GET /api/repos/archived — list archived folders the caller can manage.
+    // Archived folders are excluded from /api/repos (getContentRepos), so this is
+    // the ONLY way the web Settings UI can see them to restore / permanently
+    // delete. Visibility mirrors who can unarchive: folder-admin or workspace
+    // owner on each folder (isFolderAdminOrOwner) — not just any member. Returns
+    // the archive metadata + member count + caller role for the Settings rows.
+    fastify.get('/api/repos/archived', async (req, reply) => {
+        workspaceManager.reloadConfig();
+        const user = reqUser(req);
+        const archived = workspaceManager.getAllRepoConfigs()
+            .filter(r => isArchivedRepo(r) && isFolderAdminOrOwner(req, r.name, workspaceManager, authService));
+        const enriched = archived.map(r => ({
+            name: r.name,
+            // Null when there's no explicit display name — the client applies the
+            // same title-cased-slug fallback the active folder cards use.
+            display_name: r.display_name ?? null,
+            description: r.description,
+            archived_at: r.archived_at ?? null,
+            archived_by: r.archived_by ?? null,
+            member_count: authService.getFolderMembers(r.name).length,
+            caller_role: user ? authService.getFolderRole(user.id, r.name) : null,
+        }));
+        return reply.send(enriched);
+    });
     // PATCH /api/repos/:repo — rename/update sync rules. Folder admin or workspace owner only.
     fastify.patch('/api/repos/:repo', async (req, reply) => {
-        if (!isFolderAdminOrOwner(req, req.params.repo, authService)) {
+        if (!isFolderAdminOrOwner(req, req.params.repo, workspaceManager, authService)) {
             return reply.status(403).send({ error: 'Folder admin access required' });
         }
         const { repo } = req.params;
         const body = req.body || {};
-        const { name: newName, display_name: newDisplayName, sync: newSync, ...rest } = body;
-        if ('private' in rest) {
-            return reply.status(400).send({ error: 'The private flag is immutable after creation' });
-        }
+        // Only name/display_name/sync are applied; any other field (incl. the
+        // deprecated/inert `personal`) is ignored.
+        const { name: newName, display_name: newDisplayName, sync: newSync } = body;
         if (newName === undefined && newSync === undefined && newDisplayName === undefined) {
             return reply.status(400).send({ error: 'Nothing to update' });
         }
@@ -185,6 +235,11 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             if (!repoConfig) {
                 return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
             }
+            // System folders (the reserved Workspace Assets store) have a reserved
+            // name + fixed display; renaming/reconfiguring them is not allowed.
+            if (repoConfig.system) {
+                return reply.status(403).send({ error: 'This is a system folder and cannot be renamed or reconfigured.' });
+            }
             // Handle rename
             if (newName !== undefined) {
                 if (config.repos.some(r => r.name === newName)) {
@@ -207,7 +262,7 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
                 if (existsSync(markerPath)) {
                     writeFS(markerPath, JSON.stringify({ repo_name: newName }, null, 2), 'utf-8');
                 }
-                // Update collection_access to follow the rename
+                // Update folder_access to follow the rename
                 authService.renameFolder(repo, newName);
             }
             // Handle display name update (without rename)
@@ -219,7 +274,7 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
                 repoConfig.sync = newSync.length > 0 ? newSync : undefined;
             }
             workspace.writeConfig(config);
-            workspace.pushWorkspaceConfig(newName !== undefined ? `Rename collection: ${repo} → ${newName}` : `Update collection: ${repo}`);
+            workspace.pushWorkspaceConfig(newName !== undefined ? `Rename folder: ${repo} → ${newName}` : `Update folder: ${repo}`);
             workspaceManager.reloadConfig();
             return reply.send(repoConfig);
         }
@@ -229,22 +284,57 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
     });
     // GET /api/repos — list accessible repos (re-reads config to pick up CLI changes).
     // Augments each repo with the caller's folder role ('admin' | 'editor'),
-    // member_count, and entity_types (distinct types present in the folder —
-    // derived from directory names, no file parsing). The entity_types list
-    // lets the sidebar render Views without a per-repo entity fetch on boot.
+    // member_count, entity_types (distinct types present), and folders (the
+    // flat list of nested-folder paths in the repo, used by the sidebar to
+    // render the active-path expansion).
     fastify.get('/api/repos', async (req, reply) => {
         workspaceManager.reloadConfig();
-        const repos = getAccessibleRepos(req, workspaceManager, authService);
+        // System folders (the reserved Workspace Assets store) are accessible but
+        // excluded from the sidebar — they're surfaced via the asset manager, not
+        // the folder list. They stay in getAccessibleRepos so authz + the asset
+        // manager (/api/workspace/assets) still see them.
+        const repos = getContentRepos(req, workspaceManager, authService);
         const user = req.user;
+        const users = authService.listUsers();
         const enriched = repos.map(r => {
             const memberCount = authService.getFolderMembers(r.name).length;
             const callerRole = user ? authService.getFolderRole(user.id, r.name) : null;
             let entityTypes = [];
+            // `folders` carries the per-folder display_name override (when one
+            // exists in the folder's .studiograph-folder.json sidecar); the client
+            // falls back to toDisplayName(slug) when display_name is absent.
+            let folders = [];
             try {
-                entityTypes = workspaceManager.getGraph(r.name).listEntityTypes();
+                // Direct WM access OK here — `repos` came from getAccessibleRepos
+                // above, so every iteration is over a folder the caller can read.
+                const graph = workspaceManager.getGraph(r.name);
+                entityTypes = graph.listEntityTypes();
+                folders = graph.listFolders().map(f => {
+                    const entry = { path: f.path };
+                    if (f.display_name)
+                        entry.display_name = f.display_name;
+                    if (f.id)
+                        entry.id = f.id;
+                    return entry;
+                });
             }
             catch { /* repo not mounted */ }
-            return { ...r, caller_role: callerRole, member_count: memberCount, entity_types: entityTypes };
+            return {
+                ...r,
+                // Seed folders read as their owner's "{name}'s Folder" for everyone
+                // (incl. the owner); every other folder keeps its stored display_name.
+                display_name: resolveFolderDisplayName(r, users),
+                caller_role: callerRole,
+                member_count: memberCount,
+                // True only for THE CALLER's own seed "My Folder" (resolvable as
+                // repo:"private") — not just any entries-<id> folder, so a peer's seed
+                // shared with the caller is never mistaken for the caller's home (the
+                // capture default keys off this). "Solo/private" is derived separately
+                // on the client from member_count === 1.
+                is_seed: !!user && r.name === seedFolderName(user.id),
+                entity_types: entityTypes,
+                folders,
+            };
         });
         return reply.send(enriched);
     });
@@ -258,6 +348,7 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         }
         workspaceManager.reloadConfig();
         const all = workspaceManager.getAllRepoConfigs();
+        const users = authService.listUsers();
         const result = all.map(r => {
             const members = authService.getFolderMembers(r.name);
             const admins = members.filter(m => m.role === 'admin');
@@ -265,13 +356,16 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
                 ? members.find(m => m.user.id === r.owner_id)?.user
                 : admins[0]?.user;
             let entryCount = 0;
+            // Direct WM access OK — this endpoint is owner-only (gated above) and
+            // returns metadata for every folder the workspace owner needs to see
+            // for admin purposes. No content is leaked: only entry counts.
             try {
                 entryCount = workspaceManager.getGraph(r.name).search({}).length;
             }
             catch { /* skip */ }
             return {
                 name: r.name,
-                display_name: r.display_name ?? r.name,
+                display_name: resolveFolderDisplayName(r, users) ?? r.name,
                 description: r.description,
                 member_count: members.length,
                 admin_count: admins.length,
@@ -282,44 +376,45 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         });
         return reply.send(result);
     });
+    // Build the lightweight summary objects used by /entities?summary=true.
+    // Extracted so the per-repo and bulk endpoints share the same shape.
+    const EXCLUDED_SUMMARY_FIELDS = new Set([
+        'entity_type', 'entity_id', 'created_by', 'updated_by',
+        'description', 'content', 'context', 'rationale', 'alternatives', 'consequences',
+        'steps', 'guidelines', 'bio', 'agenda', 'summary', 'decision', 'action_items',
+    ]);
+    function buildSummaries(entities, accessibleIds) {
+        return entities.map(e => {
+            const extra = Object.fromEntries(Object.entries(e.data ?? {}).filter(([k, v]) => !EXCLUDED_SUMMARY_FIELDS.has(k) && k !== 'name' && k !== 'created_at' && k !== 'updated_at' &&
+                (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || Array.isArray(v) || v instanceof Date)));
+            return {
+                id: e.id,
+                entityType: e.entityType,
+                folder_path: e.folder_path ?? '',
+                data: {
+                    name: e.data.name,
+                    created_at: e.data.created_at,
+                    updated_at: e.data.updated_at,
+                    ...extra,
+                },
+                document: { wikilinks: filterWikilinks(e.document?.wikilinks ?? [], accessibleIds) },
+            };
+        });
+    }
     // GET /api/repos/:repo/entities — list all entities in a repo
     // ?summary=true returns lightweight objects (no content, minimal data) for sidebar/graph
     fastify.get('/api/repos/:repo/entities', async (req, reply) => {
         const { repo } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
-        }
-        let graph;
-        try {
-            graph = workspaceManager.getGraph(repo);
-        }
-        catch (err) {
-            return reply.status(404).send({ error: err.message });
-        }
+        // Access enforced by graphForRead \u2014 do not call workspaceManager.getGraph
+        // directly here. The audit (2026-05) flagged direct WM access from routes
+        // as the primary architectural risk; the service is the gate.
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
         const entities = graph.search({});
         const accessibleIds = getAccessibleEntityIds(req, workspaceManager, authService);
         if (req.query.summary === 'true') {
-            const EXCLUDED_SUMMARY_FIELDS = new Set([
-                'entity_type', 'entity_id', 'created_by', 'updated_by',
-                'description', 'content', 'context', 'rationale', 'alternatives', 'consequences',
-                'steps', 'guidelines', 'bio', 'agenda', 'summary', 'decision', 'action_items',
-            ]);
-            const summaries = entities.map(e => {
-                const extra = Object.fromEntries(Object.entries(e.data ?? {}).filter(([k, v]) => !EXCLUDED_SUMMARY_FIELDS.has(k) && k !== 'name' && k !== 'created_at' && k !== 'updated_at' &&
-                    (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || Array.isArray(v) || v instanceof Date)));
-                return {
-                    id: e.id,
-                    entityType: e.entityType,
-                    data: {
-                        name: e.data.name,
-                        created_at: e.data.created_at,
-                        updated_at: e.data.updated_at,
-                        ...extra,
-                    },
-                    document: { wikilinks: filterWikilinks(e.document?.wikilinks ?? [], accessibleIds) },
-                };
-            });
-            return reply.send(summaries);
+            return reply.send(buildSummaries(entities, accessibleIds));
         }
         // Full response — filter wikilinks in document
         const filtered = entities.map(e => {
@@ -329,19 +424,57 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         });
         return reply.send(filtered);
     });
+    // GET /api/workspace/entities?summary=true — bulk entity summaries for ALL
+    // accessible repos in a single round-trip. Replaces 15+ parallel
+    // /api/repos/:repo/entities?summary=true calls. Important on dev where each
+    // request has Vite middleware overhead and the browser's HTTP/1.1 6-slot
+    // limit serializes them, blocking other navigation fetches.
+    // Response shape: `{ [repoName]: EntitySummary[] }`.
+    fastify.get('/api/workspace/entities', async (req, reply) => {
+        // Mirror the per-repo endpoint's contract: only summary=true is supported
+        // here. Returning full bodies for the whole workspace would be huge and
+        // isn't a use case we have today.
+        if (req.query.summary !== 'true') {
+            return reply.status(400).send({ error: 'summary=true is required for the bulk entities endpoint' });
+        }
+        const repos = getContentRepos(req, workspaceManager, authService);
+        // Single-pass: collect the per-repo entity arrays AND the accessible-ids
+        // set in one walk. The previous shape called graph.search({}) twice per
+        // repo (once via getAccessibleEntityIds, once in this loop), doubling
+        // disk I/O on the most-trafficked endpoint.
+        const user = reqUser(req);
+        const collectIds = user !== undefined; // unauthenticated → no wikilink filtering
+        const accessibleIds = collectIds ? new Set() : null;
+        const perRepoEntities = [];
+        for (const r of repos) {
+            let graph;
+            // Direct WM access OK — `repos` is the access-filtered list above.
+            try {
+                graph = workspaceManager.getGraph(r.name);
+            }
+            catch {
+                continue;
+            } // skip unmounted repos rather than failing the whole request
+            const entities = graph.search({});
+            perRepoEntities.push({ name: r.name, entities });
+            if (accessibleIds) {
+                for (const e of entities)
+                    accessibleIds.add(e.id);
+            }
+        }
+        const result = {};
+        for (const { name, entities } of perRepoEntities) {
+            result[name] = buildSummaries(entities, accessibleIds);
+        }
+        return reply.send(result);
+    });
     // GET /api/repos/:repo/entities/:type — list entities of a type
     fastify.get('/api/repos/:repo/entities/:type', async (req, reply) => {
         const { repo, type } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
-        }
-        let graph;
-        try {
-            graph = workspaceManager.getGraph(repo);
-        }
-        catch (err) {
-            return reply.status(404).send({ error: err.message });
-        }
+        // Access enforced by graphForRead (WorkspaceAccessService).
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
         const entities = graph.search({ entityType: type });
         const accessibleIds = getAccessibleEntityIds(req, workspaceManager, authService);
         const filtered = entities.map(e => {
@@ -354,16 +487,10 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
     // GET /api/repos/:repo/entities/:type/:id — get single entity
     fastify.get('/api/repos/:repo/entities/:type/:id', async (req, reply) => {
         const { repo, type, id } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
-        }
-        let graph;
-        try {
-            graph = workspaceManager.getGraph(repo);
-        }
-        catch (err) {
-            return reply.status(404).send({ error: err.message });
-        }
+        // Access enforced by graphForRead (WorkspaceAccessService).
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
         let entity;
         try {
             entity = graph.get(type, id);
@@ -371,6 +498,12 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         catch (err) {
             return reply.status(404).send({ error: err.message ?? `Entity not found: ${type}/${id}` });
         }
+        // graph.get may also return null for a missing entity without throwing
+        // (depends on the backing graph implementation). Treat that as 404 so
+        // we don't blow up on the wikilinks access below.
+        if (!entity) {
+            return reply.status(404).send({ error: `Entity not found: ${type}/${id}` });
+        }
         if (entity.document?.wikilinks?.length) {
             const accessibleIds = getAccessibleEntityIds(req, workspaceManager, authService);
             return reply.send({
@@ -380,36 +513,185 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         }
         return reply.send(entity);
     });
+    // GET /api/repos/:repo/entities/:type/:id/source — download the raw
+    // markdown file (frontmatter + body verbatim, exactly as on disk). For
+    // artifacts the body IS the embedded bundle JSON, so the download is a
+    // portable single-file copy of the whole entry. Read-gated like every
+    // other entity read; serialization fidelity comes from serving the disk
+    // bytes rather than re-emitting parsed frontmatter.
+    fastify.get('/api/repos/:repo/entities/:type/:id/source', async (req, reply) => {
+        const { repo, type, id } = req.params;
+        // Access enforced by graphForRead (WorkspaceAccessService).
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
+        const filePath = graph.getEntityFilePath(type, id);
+        if (!filePath || !existsSync(filePath)) {
+            return reply.status(404).send({ error: `Entity not found: ${type}/${id}` });
+        }
+        const raw = readFileSync(filePath);
+        // Name the download from the resolved on-disk basename, sanitized to a
+        // safe quoted-string token. Created/renamed ids are kebab-case slugs, but
+        // this route resolves EXISTING files via the index — a hand-authored/
+        // legacy/imported basename can carry characters that corrupt the header
+        // or, with CR/LF, allow header injection. Strip ALL ASCII control chars
+        // (Node's validateHeaderValue rejects NUL/VT/FF/DEL etc. → ERR_INVALID_CHAR
+        // at send time, not just CR/LF) plus the quoted-string delimiters
+        // (" \ ;). Fall back to a safe default if nothing usable remains.
+        const safeName = (basename(filePath) || `${id}.md`).replace(/[\x00-\x1f\x7f";\\]/g, '').trim() || `${id}.md`;
+        reply.header('Content-Disposition', `attachment; filename="${safeName}"`);
+        reply.header('Content-Type', 'text/markdown; charset=utf-8');
+        reply.header('X-Content-Type-Options', 'nosniff');
+        return reply.send(raw);
+    });
     // GET /api/repos/:repo/entities/:type/:id/history — entity commit history
     fastify.get('/api/repos/:repo/entities/:type/:id/history', async (req, reply) => {
         const { repo, type, id } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
+        // Access enforced by graphForRead (WorkspaceAccessService).
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
+        const gitService = graph.getGitService();
+        if (!gitService) {
+            return reply.send([]);
         }
-        let graph;
+        const limit = Math.min(parseInt(req.query.limit ?? '20', 10) || 20, 50);
+        // Resolve the actual on-disk path via graph.get() — it walks nested
+        // folders to find the file. The previous hardcoded `${plural}/${id}.md`
+        // missed any entry not at the legacy flat path (entries created in a
+        // sub-folder, MCP entries that landed elsewhere, etc.) and silently
+        // returned an empty history. Convert absolute path → repo-relative
+        // for git log.
+        let filePath;
         try {
-            graph = workspaceManager.getGraph(repo);
+            const entity = graph.get(type, id);
+            const repoRoot = graph.getRepoPath();
+            filePath = entity.path.startsWith(repoRoot + '/')
+                ? entity.path.slice(repoRoot.length + 1)
+                : entity.path;
         }
         catch (err) {
             return reply.status(404).send({ error: err.message });
         }
-        const gitService = graph.getGitService();
-        if (!gitService) {
-            return reply.send([]);
-        }
-        const limit = Math.min(parseInt(req.query.limit ?? '20', 10) || 20, 50);
-        const { PLURAL_TO_SINGULAR } = await import('../../core/validation.js');
-        // Reverse lookup: singular type → plural folder name
-        const pluralDir = Object.entries(PLURAL_TO_SINGULAR).find(([, v]) => v === type)?.[0] ?? `${type}s`;
-        const filePath = `${pluralDir}/${id}.md`;
         try {
             const history = gitService.getFileHistory(filePath, limit);
+            // Opt-in per-commit change summary for the History panel. Off by
+            // default so the eager gating fetch on every entity-page load stays
+            // cheap; the panel requests it only when expanded.
+            if (req.query.changes === 'true') {
+                return reply.send(history.map((c) => ({ ...c, changes: graph.getCommitChange(filePath, c.hash) })));
+            }
             return reply.send(history);
         }
         catch {
             return reply.send([]);
         }
     });
+    // GET /api/repos/:repo/entities/:type/:id/at-commit/:hash — full body content
+    // of an entry as it was at a past commit, for the History "version preview"
+    // (read-only Live Preview render). Same read gate as /history.
+    //
+    // Reuses graph.getEntityAtCommit, which walks the commit tree by IDENTITY
+    // (entityType, entityId) — so a rename/move between then and now resolves to
+    // the right historical file without the route duplicating path-slicing, and a
+    // commit where the entry didn't yet exist at this identity resolves to null.
+    // null → typed 404 VERSION_NOT_AT_PATH so the UI can show an honest "this
+    // version isn't viewable here" message instead of a misleading generic error.
+    fastify.get('/api/repos/:repo/entities/:type/:id/at-commit/:hash', async (req, reply) => {
+        const { repo, type, id, hash } = req.params;
+        // Defense-in-depth: the hash always comes from our own history list, but
+        // validate the shape before it reaches git.
+        if (!/^[0-9a-f]{7,40}$/.test(hash)) {
+            return reply.status(400).send({ error: 'Invalid commit hash' });
+        }
+        // Access enforced by graphForRead (WorkspaceAccessService).
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
+        const hit = graph.getEntityAtCommit(type, id, hash);
+        if (hit === null) {
+            return reply.status(404).send({ error: 'VERSION_NOT_AT_PATH' });
+        }
+        // Editor content is body-only (frontmatter stripped) — match it so the
+        // preview renders exactly what the live editor would. The parsed
+        // frontmatter rides along so the preview can also show the title + fields
+        // as they were at this commit. parseFrontmatterCacheFree (NOT the shared
+        // gray-matter MarkdownService) is required for historical content — the
+        // shared parser's module-level cache returns stale values for past commits.
+        return reply.send({
+            body: stripFrontmatter(hit.content),
+            frontmatter: parseFrontmatterCacheFree(hit.content),
+        });
+    });
+    // POST /api/repos/:repo/entities/:type/:id/restore — restore an entry to
+    // its content at a past commit. Single-entity scope. Editor-or-admin role
+    // required (canWriteRepo). Returns 200 with the restore result, 404 if
+    // the entry doesn't exist at that commit, 409 PATH_CONFLICT if a different
+    // entry now occupies the target path, 403 if the caller lacks write access.
+    fastify.post('/api/repos/:repo/entities/:type/:id/restore', async (req, reply) => {
+        const { repo, type, id } = req.params;
+        const { commitHash } = req.body ?? {};
+        if (!commitHash || typeof commitHash !== 'string') {
+            return reply.status(400).send({ error: 'commitHash is required' });
+        }
+        // Access enforced by graphForWrite: 404 if no read access, 403 if no write.
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
+        // Flush any deferred autosave for this repo first — otherwise a restore
+        // could overwrite a pending (uncommitted) edit on disk and commit only
+        // the restored version, silently discarding the in-flight work. Matches
+        // rename/move/change-type, which all flush before mutating.
+        if (sessionManager)
+            await sessionManager.flush(repo);
+        try {
+            // restoreFile reconciles any live editor Y.Doc against the restored disk
+            // content internally (via the BodyWriteCoordinator's per-doc lock), so an
+            // open editor shows the restored version instead of syncing stale content
+            // back over it. That lives in graph.restoreFile so every restore caller
+            // (this route, the agent tool, the MCP tool) gets it.
+            const result = await graph.restoreFile(type, id, commitHash, reqGitUser(req));
+            wsHub?.broadcast({
+                type: 'entity_change',
+                action: result.action === 'recreate' ? 'created' : 'updated',
+                repo,
+                entityType: type,
+                entityId: id,
+                actor: reqUser(req)?.displayName ?? 'API',
+                source: 'api',
+                timestamp: new Date().toISOString(),
+            });
+            return reply.send({
+                success: true,
+                action: result.action,
+                path: result.path,
+            });
+        }
+        catch (err) {
+            // PathConflictError carries an error code distinct from generic
+            // failures so the UI can render an actionable conflict message.
+            if (err?.code === 'PATH_CONFLICT' && err?.occupiedBy) {
+                return reply.status(409).send({
+                    error: 'PATH_CONFLICT',
+                    path: err.path,
+                    occupiedBy: err.occupiedBy,
+                });
+            }
+            const message = err instanceof Error ? err.message : 'Restore failed';
+            // "not found at commit" / "did not exist at commit" → 404 so the
+            // client can show "that version isn't available" instead of a
+            // generic 500.
+            if (/not found at commit|did not exist at commit/i.test(message)) {
+                return reply.status(404).send({ error: message });
+            }
+            // Type-mismatch refusal (restoring would silently change entity_type)
+            // is a client-actionable conflict, not a server fault → 409.
+            if (/would change its type|was type '/i.test(message)) {
+                return reply.status(409).send({ error: message });
+            }
+            return reply.status(500).send({ error: message });
+        }
+    });
     // GET /api/schema/:entityType/fields — field metadata for an entity type
     fastify.get('/api/schema/:entityType/fields', async (req, reply) => {
         const { entityType } = req.params;
@@ -417,20 +699,25 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         const fields = registry.getFieldMetadata(entityType);
         return reply.send(fields);
     });
+    // GET /api/formats — the format registry, serialized for the client.
+    //
+    // Single source of truth for ingestion: the web client builds its accept
+    // lists, disposition matrix, and supported-types copy from this instead of
+    // maintaining parallel (and drifting) constants. Mirrors the
+    // GET /api/schema/:type/fields pattern. Workspace-invariant + auth-gated
+    // by the global middleware; no per-repo access needed.
+    fastify.get('/api/formats', async (_req, reply) => {
+        const { serializeForClient } = await import('../../core/format-registry.js');
+        return reply.send(serializeForClient());
+    });
     // GET /api/repos/:repo/search?q=&type=&tags= — search within a repo
     fastify.get('/api/repos/:repo/search', async (req, reply) => {
         const { repo } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
-        }
+        // Access enforced by graphForRead (WorkspaceAccessService).
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
         const { q, type, tags } = req.query;
-        let graph;
-        try {
-            graph = workspaceManager.getGraph(repo);
-        }
-        catch (err) {
-            return reply.status(404).send({ error: err.message });
-        }
         const results = graph.search({
             query: q,
             entityType: type,
@@ -446,19 +733,18 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
     });
     // GET /api/graph — full workspace graph topology (nodes + edges)
     fastify.get('/api/graph', async (req, reply) => {
-        const repos = getAccessibleRepos(req, workspaceManager, authService);
+        const repos = getContentRepos(req, workspaceManager, authService);
         const nodes = [];
         const edgeSet = new Set();
         const edges = [];
         const entityIds = new Set();
         for (const repoConfig of repos) {
             try {
+                // Direct WM access OK — `repos` came from getAccessibleRepos above.
                 const graph = workspaceManager.getGraph(repoConfig.name);
                 const entities = graph.search({});
                 for (const entity of entities) {
                     const nodeId = entity.id;
-                    if (nodeId.toLowerCase().startsWith('readme'))
-                        continue;
                     if (!entityIds.has(nodeId)) {
                         entityIds.add(nodeId);
                         nodes.push({
@@ -486,10 +772,10 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         const validEdges = edges.filter(e => entityIds.has(e.source) && entityIds.has(e.target));
         return reply.send({ nodes, edges: validEdges });
     });
-    // GET /api/search?q=&type=&tags=&repos= — cross-repo search
+    // GET /api/search?q=&type=&tags=&repos=&mode= — cross-repo search
     fastify.get('/api/search', async (req, reply) => {
-        const { q, type, tags, repos } = req.query;
-        const accessibleNames = new Set(getAccessibleRepos(req, workspaceManager, authService).map(r => r.name));
+        const { q, type, tags, repos, mode } = req.query;
+        const accessibleNames = new Set(getContentRepos(req, workspaceManager, authService).map(r => r.name));
         // Filter requested repos to only accessible ones
         let repoNames = repos ? repos.split(',').map(r => r.trim()) : undefined;
         if (repoNames) {
@@ -498,12 +784,35 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         else {
             repoNames = [...accessibleNames];
         }
+        const keywordMode = mode === 'keyword';
         const results = await workspaceManager.search({
             query: q,
             entityType: type,
             tags: tags ? tags.split(',').map(t => t.trim()) : undefined,
             repoNames,
+            mode: keywordMode ? 'keyword' : undefined,
+            // Autosuggest dropdown caps at 20 visible rows; capping server-side
+            // avoids serializing a long tail the client throws away.
+            limit: keywordMode ? 20 : undefined,
         });
+        // Autosuggest doesn't need the markdown body or wikilinks — the
+        // dropdown renders {name, type, repo} only. Returning a slim shape
+        // cuts response size from ~hundreds of KB to a few KB on big
+        // workspaces, and skips the per-entity wikilink visibility filter.
+        if (keywordMode) {
+            const slim = results.map(e => ({
+                id: e.id,
+                path: e.path,
+                folder_path: e.folder_path,
+                entityType: e.entityType,
+                repoName: e.repoName,
+                data: {
+                    name: e.data?.name,
+                    updated_at: e.data?.updated_at,
+                },
+            }));
+            return reply.send(slim);
+        }
         const accessibleIds = getAccessibleEntityIds(req, workspaceManager, authService);
         const filtered = results.map((e) => {
             if (!e.document?.wikilinks?.length)
@@ -515,23 +824,29 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
     // PUT /api/repos/:repo/entities/:type/:id — update entity (data and/or content)
     fastify.put('/api/repos/:repo/entities/:type/:id', async (req, reply) => {
         const { repo, type, id } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
-        }
+        // Access enforced by graphForWrite \u2014 PUT updates an entity, write required.
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
         const eagerError = checkEagerSkillPermission(req, type, req.body.data, repo, workspaceManager, authService);
         if (eagerError)
             return reply.status(403).send({ error: eagerError });
-        let graph;
         try {
-            graph = workspaceManager.getGraph(repo);
-        }
-        catch (err) {
-            return reply.status(404).send({ error: err.message });
-        }
-        try {
-            // Optimistic concurrency: reject if entity was modified after client last fetched it
+            // Optimistic concurrency. Two preconditions:
+            //   - `X-Studiograph-Base-Body-Hash` (Phase 3a): sha256 hex of the
+            //     body the client last loaded. Enforced INSIDE the per-doc lock
+            //     by graph.update via `baseRevision`, so it composes with
+            //     serialization — two body-writing PUTs from the same baseline
+            //     can't both pass and back-stomp each other.
+            //   - `If-Unmodified-Since` (legacy): kept for non-web clients;
+            //     RFC-7231 second-precision so aliases sub-millisecond writes,
+            //     which is why the body-hash form is preferred.
+            // Body-hash header is IGNORED on metadata-only PUTs — a stale body
+            // baseline is irrelevant when the PUT doesn't touch the body, and
+            // enforcing it would cause spurious 412s after an agent body-write.
+            const baseBodyHash = req.headers['x-studiograph-base-body-hash'];
             const ifUnmodifiedSince = req.headers['if-unmodified-since'];
-            if (ifUnmodifiedSince) {
+            if (ifUnmodifiedSince && !baseBodyHash) {
                 const current = graph.get(type, id);
                 const entityUpdatedAt = current?.data?.updated_at;
                 if (entityUpdatedAt && new Date(entityUpdatedAt) > new Date(ifUnmodifiedSince)) {
@@ -539,6 +854,40 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
                 }
             }
             const gitUser = reqGitUser(req);
+            // Workspace-wide uniqueness check for `user_handle` on person entities.
+            // Skip the entity being updated so we don't reject it for clashing
+            // with itself. Also gate WHO can change the bridge: only workspace
+            // owners may stamp/clear/rewrite user_handle. Other folder-writers
+            // see the field but can't edit it (defense against impersonation
+            // through the agent's Current User prompt).
+            if (type === 'person' && req.body.data) {
+                try {
+                    validateUserHandleInPayload(workspaceManager, req.body.data, { repo, entityId: id });
+                    if (Object.prototype.hasOwnProperty.call(req.body.data, 'user_handle')) {
+                        const current = graph.get('person', id);
+                        const currentHandle = (current?.data?.user_handle ?? '');
+                        assertCanChangeUserHandle(reqUser(req), currentHandle, req.body.data.user_handle);
+                    }
+                }
+                catch (err) {
+                    if (err instanceof BridgeError) {
+                        const status = err.code === 'OWNER_REQUIRED' ? 403 : 409;
+                        return reply.status(status).send({ error: err.message, code: err.code, ...err.details });
+                    }
+                    throw err;
+                }
+            }
+            // Scope ref fields (today: task.assignee → person). Rejects a wikilink
+            // that resolves to a non-person; forward references are allowed.
+            try {
+                assertEntityRefs(workspaceManager, type, req.body.data, { userExists: (id) => !!authService.findUserById(Number(id)) });
+            }
+            catch (err) {
+                if (err instanceof EntityRefError || err instanceof UnknownUserRefError) {
+                    return reply.status(400).send({ error: err.message, code: err.code, field: err.field });
+                }
+                throw err;
+            }
             const updated = await graph.update({
                 entityType: type,
                 entityId: id,
@@ -547,16 +896,16 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
                 commitMessage: `Update ${type}/${id} from web UI`,
                 user: gitUser,
                 skipCommit: !!sessionManager, // defer commit if scheduler is active
+                source: 'autosave',
+                // Forward the body-hash precondition into graph.update so the
+                // check runs INSIDE the per-doc lock — see Phase 3 P1 fix.
+                // Only meaningful for body writes; ignored when content is
+                // undefined (graph.update gates on content !== undefined too).
+                baseRevision: req.body.content !== undefined ? baseBodyHash : undefined,
             });
             if (sessionManager && gitUser) {
                 sessionManager.markDirty(repo, gitUser, type, id, updated.path);
             }
-            // Push the new content into any active Y.Doc so other open tabs /
-            // browsers for the same entity see the update and the CRDT doesn't
-            // blend stale state on the next resync. No-op when no Y.Doc is live.
-            if (req.body.content !== undefined) {
-                yjsManager?.syncDocFromDisk(`${repo}/${type}/${id}`);
-            }
             wsHub?.broadcast({
                 type: 'entity_change', action: 'updated', repo, entityType: type, entityId: id,
                 actor: req.user?.displayName ?? 'API',
@@ -565,26 +914,36 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             return reply.send(updated);
         }
         catch (err) {
+            // Translate the locked-section baseRevision mismatch into the
+            // same 412 shape the route used to emit pre-lock. Preserves the
+            // client-side contract (code: STALE_BODY_HASH + currentBodyHash
+            // + entity).
+            if (err instanceof StaleBaseRevisionError) {
+                const current = graph.get(type, id);
+                return reply.status(412).send({
+                    error: 'Precondition Failed: body was modified',
+                    code: 'STALE_BODY_HASH',
+                    currentBodyHash: err.actual,
+                    entity: current,
+                });
+            }
             return reply.status(400).send({ error: err.message });
         }
     });
-    // POST /api/repos/:repo/change-type — change entity type (moves file between type dirs)
+    // POST /api/repos/:repo/change-type — change entity type. Rewrites the
+    // `entity_type` frontmatter + swaps type-specific fields IN PLACE (the file
+    // stays in its current folder; type lives in frontmatter, not the path). The
+    // (type,id) identity still moves, so the client renavigates to the new-type URL.
     fastify.post('/api/repos/:repo/change-type', async (req, reply) => {
         const { repo } = req.params;
         const { entityType: type, entityId: id, newType } = req.body ?? {};
         if (!type || !id || !newType) {
             return reply.status(400).send({ error: 'entityType, entityId, and newType are required' });
         }
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
-        }
-        let graph;
-        try {
-            graph = workspaceManager.getGraph(repo);
-        }
-        catch (err) {
-            return reply.status(404).send({ error: err.message });
-        }
+        // Access enforced by graphForRead (WorkspaceAccessService).
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
         try {
             // Flush any pending session saves before moving the file
             if (sessionManager) {
@@ -622,21 +981,15 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         if (id === newId) {
             return reply.status(400).send({ error: 'New ID must differ from the current ID' });
         }
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
-        }
+        // Access enforced by graphForWrite (WorkspaceAccessService).
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
         // Workspace-wide uniqueness — ids must be unique across all folders
         const conflict = workspaceManager.findEntityById(newId);
         if (conflict) {
             return reply.status(409).send({ error: `An entry with id "${newId}" already exists in folder "${conflict.repoName}".` });
         }
-        let graph;
-        try {
-            graph = workspaceManager.getGraph(repo);
-        }
-        catch (err) {
-            return reply.status(404).send({ error: err.message });
-        }
         try {
             // Flush pending session saves so we don't PUT to the old path after rename
             if (sessionManager) {
@@ -650,6 +1003,7 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             const refactorMsg = `Refactor wikilinks: ${id} \u2192 ${newId}`;
             for (const other of getAccessibleRepos(req, workspaceManager, authService)) {
                 try {
+                    // Direct WM access OK — iterating the access-filtered list.
                     const otherGraph = workspaceManager.getGraph(other.name);
                     await otherGraph.refactorWikilink(id, newId, refactorMsg);
                 }
@@ -672,45 +1026,63 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             return reply.status(status).send({ error: err.message });
         }
     });
-    // POST /api/repos/:repo/transfer — move or copy entity to another collection
+    // POST /api/repos/:repo/transfer — move or copy entity to another folder
     fastify.post('/api/repos/:repo/transfer', async (req, reply) => {
         const sourceRepo = req.params.repo;
-        const { entityType, entityId, targetRepo, mode } = req.body ?? {};
+        const { entityType, entityId, targetRepo, mode, targetFolderPath } = req.body ?? {};
         if (!entityType || !entityId || !targetRepo || !mode) {
             return reply.status(400).send({ error: 'entityType, entityId, targetRepo, and mode are required' });
         }
         if (sourceRepo === targetRepo) {
             return reply.status(400).send({ error: 'Source and target folders must be different' });
         }
-        if (!hasRepoAccess(req, sourceRepo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${sourceRepo}\u201D not found` });
-        }
-        if (!hasRepoAccess(req, targetRepo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${targetRepo}\u201D not found` });
-        }
-        let sourceGraph, targetGraph;
+        // Workspace Assets store ownership gate (codex P1 / D2). Moving an `asset`
+        // OUT of a workspace_wide store reassigns its index repo, after which the
+        // uploader/owner delete rule no longer applies — so the move itself must
+        // honor that rule. assetDeleteDenial is a no-op for non-workspace_wide
+        // sources, so normal folder→folder moves are unaffected.
+        if (entityType === 'asset') {
+            const denial = assetDeleteDenial(workspaceManager.getAssetIndex?.(), workspaceManager.getRepoConfig(sourceRepo), reqUser(req), sourceRepo, entityType, entityId);
+            if (denial)
+                return reply.status(403).send({ error: denial });
+        }
+        // Access enforced by graphForWrite — both source (delete on move)
+        // and target (create) require write access. Resolved up-front so a
+        // target-side denial never surfaces only after source has been
+        // mutated. Audit (2026-05) flagged the previous opt-in pattern.
+        const sourceGraph = graphForWrite(req, reply, sourceRepo);
+        if (!sourceGraph)
+            return;
+        const targetGraph = graphForWrite(req, reply, targetRepo);
+        if (!targetGraph)
+            return;
         try {
-            sourceGraph = workspaceManager.getGraph(sourceRepo);
-            targetGraph = workspaceManager.getGraph(targetRepo);
-        }
-        catch (err) {
-            return reply.status(404).send({ error: err.message });
-        }
-        try {
-            // Flush pending saves
-            if (sessionManager)
+            // Phase 0 — prevalidate. Audit (2026-05) required this: previously
+            // the route created in target, broadcast `created`, and only then
+            // tried to delete from source. A delete failure left a duplicate
+            // entry the client had already been told about.
+            if (sessionManager) {
                 await sessionManager.flush(sourceRepo);
-            // Read source entity
+                if (targetRepo !== sourceRepo)
+                    await sessionManager.flush(targetRepo);
+            }
+            // Source must exist; target must not collide. Both checks run BEFORE
+            // any mutation so we never enter phase 2 unless phase 1 will succeed.
             const source = sourceGraph.get(entityType, entityId);
-            // Check for conflicts in target
+            const sourcePath = source.path;
+            const sourceRawMarkdown = readFileSync(sourcePath, 'utf-8');
             try {
                 targetGraph.get(entityType, entityId);
                 return reply.status(409).send({ error: `"${entityId}" already exists in ${targetRepo}` });
             }
             catch { /* not found = good */ }
-            // Create in target
             const gitUser = reqGitUser(req);
             const { entity_type, entity_id, ...dataFields } = source.data;
+            // Phase 1 — create in target. No broadcast yet: a half-completed
+            // move (created in target, source still present) must NOT be
+            // observable to clients, or they will display two copies until the
+            // next refresh. `targetFolderPath` lets the caller drop the entry
+            // straight into a subfolder of the target repo.
             const created = await targetGraph.create({
                 entityType: entityType,
                 entityId,
@@ -718,21 +1090,120 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
                 content: source.document?.content ?? '',
                 commitMessage: `${mode === 'move' ? 'Move' : 'Copy'} ${entityType}: ${entityId} from ${sourceRepo}`,
                 user: gitUser,
+                folderPath: targetFolderPath,
             });
+            // Phase 2 — for `move` only: delete from source. If this fails, run
+            // a compensating delete on target so we don't leave a duplicate.
+            // The compensating delete is best-effort; if it also fails, surface
+            // a 500 with both error messages so the residue is visible (the
+            // previous behavior silently succeeded and left orphans).
+            if (mode === 'move') {
+                try {
+                    // delete() never touches assets (referenced, not owned), so the
+                    // moved entity's blobs are safe through the source-side delete.
+                    await sourceGraph.delete(entityType, entityId, undefined, gitUser);
+                    // Re-point ownership to the target repo ONLY after the source
+                    // delete succeeds. Doing it after means a failed source delete
+                    // (handled below) leaves the index pointing at the source repo,
+                    // which is correct for the entity we're about to restore there.
+                    // Blobs/URLs are unchanged (immutable keys); only the index's
+                    // repo column moves, which is what serve-time authz reads.
+                    workspaceManager.getAssetIndex?.()?.reassignOwner(sourceRepo, entityType, entityId, { repo: targetRepo });
+                }
+                catch (deleteErr) {
+                    const deleteMsg = deleteErr instanceof Error ? deleteErr.message : String(deleteErr);
+                    let recoveryMsg = null;
+                    try {
+                        let restoreSource = !existsSync(sourcePath);
+                        if (!restoreSource) {
+                            try {
+                                restoreSource = readFileSync(sourcePath, 'utf-8') !== sourceRawMarkdown;
+                            }
+                            catch {
+                                restoreSource = true;
+                            }
+                        }
+                        if (restoreSource) {
+                            mkdirSync(dirname(sourcePath), { recursive: true });
+                            writeFileSync(sourcePath, sourceRawMarkdown, 'utf-8');
+                            const recoveryPaths = [sourcePath];
+                            const folderMarkerPath = join(dirname(sourcePath), '.gitkeep');
+                            if (existsSync(folderMarkerPath)) {
+                                rmSync(folderMarkerPath, { force: true });
+                                recoveryPaths.push(folderMarkerPath);
+                            }
+                            const sourceAny = sourceGraph;
+                            const recoveryGit = sourceAny.gitService;
+                            const recoveryUser = gitUser ?? sourceAny.gitUser;
+                            if (!recoveryGit || !recoveryUser) {
+                                throw new Error('source graph git service or git user unavailable');
+                            }
+                            recoveryGit.commitFiles(recoveryPaths, `Recover ${entityType}: ${entityId} after failed move to ${targetRepo}`, recoveryUser);
+                        }
+                    }
+                    catch (recoveryErr) {
+                        recoveryMsg = recoveryErr instanceof Error ? recoveryErr.message : String(recoveryErr);
+                        log.error('[critical] cross-repo move source recovery failed', {
+                            sourceRepo,
+                            targetRepo,
+                            entityType,
+                            entityId,
+                            sourcePath,
+                            deleteError: deleteMsg,
+                            recoveryError: recoveryMsg,
+                            capturedContent: sourceRawMarkdown,
+                        });
+                    }
+                    try {
+                        // Compensating delete never touches assets either — the
+                        // recovered source entity keeps pointing at live URLs.
+                        await targetGraph.delete(entityType, entityId, undefined, gitUser);
+                        if (recoveryMsg) {
+                            return reply.status(500).send({
+                                error: `Move failed: source delete of ${entityType}/${entityId} failed (${deleteMsg}). Target rolled back, but source recovery commit failed (${recoveryMsg}); manual source repo recovery is required.`,
+                                code: 'MOVE_SOURCE_RECOVERY_FAILED',
+                                sourceRepo,
+                                targetRepo,
+                            });
+                        }
+                        return reply.status(500).send({
+                            error: `Move failed: source delete of ${entityType}/${entityId} failed (${deleteMsg}). Target rolled back; folders are back to their pre-move state.`,
+                        });
+                    }
+                    catch (compErr) {
+                        const compMsg = compErr instanceof Error ? compErr.message : String(compErr);
+                        if (recoveryMsg) {
+                            return reply.status(500).send({
+                                error: `Move failed and could not be rolled back. Source delete failed (${deleteMsg}); source recovery commit failed (${recoveryMsg}); compensating target delete also failed (${compMsg}). Captured source content was logged for manual recovery.`,
+                                code: 'MOVE_RECOVERY_AND_ROLLBACK_FAILED',
+                                sourceRepo,
+                                targetRepo,
+                            });
+                        }
+                        return reply.status(500).send({
+                            error: `Move failed and could not be rolled back. Source delete failed (${deleteMsg}); compensating target delete also failed (${compMsg}). Entry now exists in BOTH ${sourceRepo} and ${targetRepo} — manual cleanup required.`,
+                            code: 'MOVE_DUPLICATE',
+                            sourceRepo,
+                            targetRepo,
+                        });
+                    }
+                }
+            }
+            // Phase 3 — both phases succeeded; only now broadcast. Order:
+            // source-delete first so subscribers don't briefly observe the
+            // entity in both folders during the network race.
             const actor = req.user?.displayName ?? 'API';
             const ts = new Date().toISOString();
-            wsHub?.broadcast({
-                type: 'entity_change', action: 'created', repo: targetRepo, entityType, entityId,
-                actor, source: 'api', timestamp: ts,
-            });
-            // Delete from source if moving
             if (mode === 'move') {
-                await sourceGraph.delete(entityType, entityId, undefined, gitUser);
                 wsHub?.broadcast({
                     type: 'entity_change', action: 'deleted', repo: sourceRepo, entityType, entityId,
                     actor, source: 'api', timestamp: ts,
                 });
             }
+            wsHub?.broadcast({
+                type: 'entity_change', action: 'created', repo: targetRepo, entityType, entityId,
+                actor, source: 'api', timestamp: ts,
+            });
             return reply.send({
                 success: true,
                 entity: created,
@@ -743,27 +1214,211 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             return reply.status(400).send({ error: err.message });
         }
     });
-    // DELETE /api/repos/:repo/entities/:type/:id — delete an entity
-    fastify.delete('/api/repos/:repo/entities/:type/:id', async (req, reply) => {
-        const { repo, type, id } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
+    // POST /api/repos/:repo/transfer-entities — bulk move a list of entries
+    // into a single target folder (in this or another repo). The web UI's
+    // multi-select Move flow used to loop and POST per entry; this collapses
+    // to one round-trip per source repo and one commit per repo touched.
+    fastify.post('/api/repos/:repo/transfer-entities', async (req, reply) => {
+        const sourceRepo = req.params.repo;
+        const { entries, targetRepo, targetFolder } = req.body ?? {};
+        if (!Array.isArray(entries) || !targetRepo || targetFolder === undefined) {
+            return reply.status(400).send({ error: 'entries, targetRepo, and targetFolder are required' });
+        }
+        // Workspace Assets store ownership gate (codex P1 / D2): same rule as the
+        // single /transfer route, applied per asset entry. No-op when the source
+        // isn't workspace_wide.
+        for (const e of entries) {
+            if (e.entityType !== 'asset')
+                continue;
+            const denial = assetDeleteDenial(workspaceManager.getAssetIndex?.(), workspaceManager.getRepoConfig(sourceRepo), reqUser(req), sourceRepo, e.entityType, e.entityId);
+            if (denial)
+                return reply.status(403).send({ error: denial });
+        }
+        // Access enforced by graphForWrite — both source (mutate) and
+        // target (write) require write access. Resolved up-front so a
+        // target-side denial never surfaces only after source mutation.
+        const sourceGraph = graphForWrite(req, reply, sourceRepo);
+        if (!sourceGraph)
+            return;
+        const targetGraph = graphForWrite(req, reply, targetRepo);
+        if (!targetGraph)
+            return;
+        try {
+            if (sessionManager) {
+                await sessionManager.flush(sourceRepo);
+                if (targetRepo !== sourceRepo)
+                    await sessionManager.flush(targetRepo);
+            }
+            const result = await sourceGraph.moveEntitiesToRepo(entries.map(e => ({ entityType: e.entityType, entityId: e.entityId })), targetGraph, targetFolder, { user: reqGitUser(req) });
+            const actor = req.user?.displayName ?? 'API';
+            const ts = new Date().toISOString();
+            const summary = `moved ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`;
+            wsHub?.broadcast({ type: 'repo_sync', repo: sourceRepo, source: 'api', summary, workspaceWide: workspaceManager.getRepoConfig(sourceRepo)?.workspace_wide === true, actor, timestamp: ts });
+            if (targetRepo !== sourceRepo) {
+                wsHub?.broadcast({ type: 'repo_sync', repo: targetRepo, source: 'api', summary, workspaceWide: workspaceManager.getRepoConfig(targetRepo)?.workspace_wide === true, actor, timestamp: ts });
+            }
+            return reply.send({ success: true, ...result });
+        }
+        catch (err) {
+            const status = err?.name === 'InvalidFolderPathError' ? 400
+                : err.message?.includes('not found') ? 404
+                    : err.message?.includes('already occupied') ? 409
+                        : 400;
+            return reply.status(status).send({ error: err.message });
         }
-        let graph;
+    });
+    // POST /api/repos/:repo/transfer-folder — move an entire folder (with all
+    // descendants) into another repo in one shot. Replaces the per-entry loop
+    // the web UI used to run, which produced 2 git commits per entry; this
+    // route performs a single FS-level rename and one commit per repo.
+    fastify.post('/api/repos/:repo/transfer-folder', async (req, reply) => {
+        const sourceRepo = req.params.repo;
+        const { sourceFolder, targetRepo, targetFolder } = req.body ?? {};
+        if (!sourceFolder || !targetRepo || targetFolder === undefined) {
+            return reply.status(400).send({ error: 'sourceFolder, targetRepo, and targetFolder are required' });
+        }
+        if (sourceRepo === targetRepo && sourceFolder === targetFolder) {
+            return reply.status(400).send({ error: 'Source and target are the same' });
+        }
+        // Workspace Assets store gate (codex P1 / D2). Moving a folder OUT of a
+        // workspace_wide store relocates+reassigns every asset under it, escaping
+        // the per-asset uploader/owner delete rule. A folder-level bulk move in
+        // the shared store is an admin action — restrict it to a workspace owner.
+        // (No-op for normal folders; the manager never folder-moves the store.)
+        if (workspaceManager.getRepoConfig(sourceRepo)?.workspace_wide && !isWorkspaceOwner(reqUser(req)?.role ?? '')) {
+            return reply.status(403).send({ error: 'Only a workspace owner can move folders out of the shared Assets store.' });
+        }
+        // Access enforced by graphForWrite — both source (mutate) and
+        // target (write) require write access. Resolved up-front so a
+        // target-side denial never surfaces only after source mutation.
+        const sourceGraph = graphForWrite(req, reply, sourceRepo);
+        if (!sourceGraph)
+            return;
+        const targetGraph = graphForWrite(req, reply, targetRepo);
+        if (!targetGraph)
+            return;
         try {
-            graph = workspaceManager.getGraph(repo);
+            // Flush any deferred saves on either side so we don't strand a
+            // pending edit in the source folder mid-move.
+            if (sessionManager) {
+                await sessionManager.flush(sourceRepo);
+                if (targetRepo !== sourceRepo)
+                    await sessionManager.flush(targetRepo);
+            }
+            const stats = await sourceGraph.moveFolderToRepo(sourceFolder, targetGraph, targetFolder, { user: reqGitUser(req) });
+            const actor = req.user?.displayName ?? 'API';
+            const ts = new Date().toISOString();
+            // One refresh-trigger per repo. The receiving and sending lists
+            // both need to update; using `repo_sync` keeps the realtime
+            // handler simple — it already calls workspace.refreshEntities
+            // on this event type. Avoids emitting 2× entries-moved entity_change
+            // broadcasts (one created, one deleted) per file.
+            wsHub?.broadcast({ type: 'repo_sync', repo: sourceRepo, source: 'api', summary: 'moved a folder', workspaceWide: workspaceManager.getRepoConfig(sourceRepo)?.workspace_wide === true, actor, timestamp: ts });
+            if (targetRepo !== sourceRepo) {
+                wsHub?.broadcast({ type: 'repo_sync', repo: targetRepo, source: 'api', summary: 'moved a folder', workspaceWide: workspaceManager.getRepoConfig(targetRepo)?.workspace_wide === true, actor, timestamp: ts });
+            }
+            return reply.send({ success: true, ...stats });
         }
         catch (err) {
-            return reply.status(404).send({ error: err.message });
+            const status = err?.name === 'InvalidFolderPathError' ? 400
+                : err.message?.includes('not found') ? 404
+                    : err.message?.includes('not empty') ? 409
+                        : 400;
+            return reply.status(status).send({ error: err.message });
         }
+    });
+    // Workspace Assets store delete gate (codex P1 / D2) — uploader/owner only.
+    // Pure decision lives in services/asset-delete-authz.ts (unit-tested); this
+    // closure binds it to the route's workspaceManager.
+    const denyAssetDelete = (user, repo, entityType, entityId) => assetDeleteDenial(workspaceManager.getAssetIndex?.(), workspaceManager.getRepoConfig(repo), user, repo, entityType, entityId);
+    // DELETE /api/repos/:repo/entities/:type/:id — delete an entity
+    fastify.delete('/api/repos/:repo/entities/:type/:id', async (req, reply) => {
+        const { repo, type, id } = req.params;
+        const denial = denyAssetDelete(reqUser(req), repo, type, id);
+        if (denial)
+            return reply.status(403).send({ error: denial });
+        // Access enforced by graphForRead (WorkspaceAccessService).
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
         try {
+            // Soft bridge-awareness: deleting a person that's linked to an auth
+            // account orphans that user (their "My Tasks"/@mentions stop
+            // resolving). We don't BLOCK the delete — the link is a soft
+            // relationship — but we surface a warning so the caller knows, and the
+            // orphan is then caught by the Profile panel's unlinked affordance.
+            let bridgeWarning;
+            if (type === 'person') {
+                try {
+                    const handle = graph.get('person', id)?.data?.user_handle;
+                    if (typeof handle === 'string' && handle.length > 0) {
+                        bridgeWarning = `This record was linked to the "${handle}" account. Deleting it unlinks that user — their "My Tasks", @mentions, and task assignments stop resolving until they link a new record (Settings → Profile → "Create & link").`;
+                        log.warn(`[bridge] deleting linked person ${repo}/${id} (was user ${handle})`);
+                    }
+                }
+                catch { /* not readable / already gone — let graph.delete surface it */ }
+            }
             await graph.delete(type, id, `Delete ${type}/${id} from web UI`, reqGitUser(req));
+            // Entity deletion KEEPS assets (assets-referenced-not-owned P1) — a
+            // former `asset` entity's index row persists as a library asset
+            // (re-homed to its folder by `admin migrate-asset-owners`).
             wsHub?.broadcast({
                 type: 'entity_change', action: 'deleted', repo, entityType: type, entityId: id,
                 actor: req.user?.displayName ?? 'API',
                 source: 'api', timestamp: new Date().toISOString(),
             });
-            return reply.send({ ok: true });
+            return reply.send({ ok: true, ...(bridgeWarning ? { warning: bridgeWarning } : {}) });
+        }
+        catch (err) {
+            return reply.status(400).send({ error: err.message });
+        }
+    });
+    // POST /api/repos/:repo/entities/bulk-delete — delete many entities in
+    // one git transaction + one WS broadcast. Replaces N parallel
+    // DELETE /entities/:type/:id calls, which on a 500-entry bulk delete
+    // produced 500 git commits + 500 entity_change broadcasts and froze
+    // the UI for minutes.
+    fastify.post('/api/repos/:repo/entities/bulk-delete', async (req, reply) => {
+        const { repo } = req.params;
+        // Access enforced by graphForWrite (WorkspaceAccessService).
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
+        const body = req.body;
+        if (!body?.entities || !Array.isArray(body.entities)) {
+            return reply.status(400).send({ error: 'Expected { entities: [{ entityType, entityId }] }' });
+        }
+        // Apply the workspace-Assets delete gate per entity (codex P1 / D2):
+        // uploader/owner-only. Denied entries are reported, not silently dropped.
+        const deleteUser = reqUser(req);
+        const denied = [];
+        const allowed = body.entities.filter(e => {
+            const d = denyAssetDelete(deleteUser, repo, e.entityType, e.entityId);
+            if (d) {
+                denied.push({ entityType: e.entityType, entityId: e.entityId, error: d });
+                return false;
+            }
+            return true;
+        });
+        try {
+            const result = await graph.bulkDelete(allowed.map(e => ({ entityType: e.entityType, entityId: e.entityId })), {
+                user: reqGitUser(req),
+                commitMessage: `Bulk delete ${allowed.length} ${allowed.length === 1 ? 'entry' : 'entries'} from web UI`,
+            });
+            if (result.deleted.length > 0) {
+                wsHub?.broadcast({
+                    type: 'repo_sync', repo,
+                    actor: req.user?.displayName ?? 'API',
+                    source: 'api',
+                    summary: `deleted ${result.deleted.length} ${result.deleted.length === 1 ? 'entry' : 'entries'}`,
+                    workspaceWide: workspaceManager.getRepoConfig(repo)?.workspace_wide === true,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return reply.send({
+                deleted: result.deleted.length,
+                errors: [...result.errors, ...denied],
+            });
         }
         catch (err) {
             return reply.status(400).send({ error: err.message });
@@ -772,203 +1427,466 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
     // POST /api/repos/:repo/entities — create a new entity
     fastify.post('/api/repos/:repo/entities', async (req, reply) => {
         const { repo } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
-        }
-        const { entityType, entityId, data = {}, content = '' } = req.body;
+        // Access enforced by graphForWrite (WorkspaceAccessService).
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
+        const { entityType, entityId, data = {}, content = '', folder_path } = req.body;
         if (!entityType || !entityId) {
             return reply.status(400).send({ error: 'entityType and entityId are required' });
         }
+        // Refuse to re-mint a retired type (`asset`, Phase F). Otherwise an
+        // unknown entityType falls back to EntityBaseSchema and writes a
+        // base-only stub of exactly the type asset-as-embed removed.
+        if (RESERVED_ENTITY_TYPES.has(entityType)) {
+            return reply.status(400).send({ error: `Entity type '${entityType}' was retired and can no longer be created.` });
+        }
         const eagerError = checkEagerSkillPermission(req, entityType, data, repo, workspaceManager, authService);
         if (eagerError)
             return reply.status(403).send({ error: eagerError });
-        let graph;
+        // Person entities can carry a `user_handle` pointer to an auth account;
+        // enforce workspace-wide uniqueness AND owner-only authz before
+        // delegating to the per-repo create path. Stamping a handle on a new
+        // entity is the same trust action as stamping it on an existing one,
+        // so non-owners can't create a pre-linked person entity either.
+        if (entityType === 'person') {
+            try {
+                validateUserHandleInPayload(workspaceManager, data);
+                if (Object.prototype.hasOwnProperty.call(data, 'user_handle')) {
+                    assertCanChangeUserHandle(reqUser(req), '', data.user_handle);
+                }
+            }
+            catch (err) {
+                if (err instanceof BridgeError) {
+                    const status = err.code === 'OWNER_REQUIRED' ? 403 : 409;
+                    return reply.status(status).send({ error: err.message, code: err.code, ...err.details });
+                }
+                throw err;
+            }
+        }
+        // Scope ref fields (today: task.assignee → person). Rejects a wikilink
+        // that resolves to a non-person; forward references are allowed.
         try {
-            graph = workspaceManager.getGraph(repo);
+            assertEntityRefs(workspaceManager, entityType, data, { userExists: (id) => !!authService.findUserById(Number(id)) });
         }
         catch (err) {
-            return reply.status(404).send({ error: err.message });
+            if (err instanceof EntityRefError || err instanceof UnknownUserRefError) {
+                return reply.status(400).send({ error: err.message, code: err.code, field: err.field });
+            }
+            throw err;
         }
         try {
+            // Detect implicit subfolder creation: if the entry lands in a folder
+            // that didn't exist yet, the entity_change below only refreshes the
+            // entry list — clients need a _folder event to refetch the folder tree
+            // (sidebar + list/gallery folder rows). Mirrors the MCP create_entity
+            // path; normalize the same way graph.create does so the existence
+            // check matches the real on-disk path.
+            const normFolder = folder_path ? validateFolderPath(folder_path) : '';
+            const folderExisted = !normFolder || existsSync(join(graph.getRepoPath(), normFolder));
+            const now = new Date().toISOString();
+            const actorId = reqGitUser(req)?.id ?? 'web';
+            const stampedData = {
+                ...data,
+                entity_type: entityType,
+                entity_id: entityId,
+                created_at: data.created_at ?? now,
+                updated_at: data.updated_at ?? now,
+                created_by: data.created_by ?? actorId,
+                updated_by: data.updated_by ?? actorId,
+            };
             const entity = await graph.create({
                 entityType: entityType,
                 entityId,
-                data: { entity_type: entityType, entity_id: entityId, ...data },
+                data: stampedData,
                 content,
+                folderPath: folder_path,
                 commitMessage: `Create ${entityType}/${entityId} from web UI`,
                 user: reqGitUser(req),
             });
+            const actor = req.user?.displayName ?? 'API';
+            const ts = new Date().toISOString();
             wsHub?.broadcast({
                 type: 'entity_change', action: 'created', repo, entityType, entityId,
-                actor: req.user?.displayName ?? 'API',
-                source: 'api', timestamp: new Date().toISOString(),
+                actor, source: 'api', timestamp: ts,
             });
+            if (!folderExisted) {
+                wsHub?.broadcast({
+                    type: 'entity_change', action: 'created', repo, entityType: '_folder', entityId: normFolder,
+                    actor, source: 'api', timestamp: ts,
+                });
+            }
             return reply.status(201).send(entity);
         }
         catch (err) {
             return reply.status(400).send({ error: err.message });
         }
     });
-    // POST /api/repos/:repo/commit — flush deferred commits (navigate-away signal)
-    fastify.post('/api/repos/:repo/commit', async (req, reply) => {
-        if (!sessionManager) {
-            return reply.send({ committed: false });
-        }
+    // POST /api/repos/:repo/font-skills — package selected font assets into a
+    // `skill` entity. The server reads each file's REAL metadata (typographic
+    // family / weight / italic via fontkit), groups faces into families, and
+    // writes a skill whose markdown body carries an orienting note, the font
+    // files as chips, and the derived @font-face block. The skill is then
+    // auto-discovered by the agent (skill index) and used to make on-brand
+    // artifacts. `:repo` is the DESTINATION folder; each asset is downloaded from
+    // its own owning repo.
+    fastify.post('/api/repos/:repo/font-skills', async (req, reply) => {
         const { repo } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
+        const graph = graphForWrite(req, reply, repo); // dest-folder write access
+        if (!graph)
+            return;
+        const { name, folder_path } = req.body ?? {};
+        const requested = Array.isArray(req.body?.assets) ? req.body.assets : [];
+        if (requested.length === 0) {
+            return reply.status(400).send({ error: 'No font assets supplied.' });
+        }
+        // SECURITY: never trust the client-supplied `repo`. Asset blobs are keyed
+        // by an immutable workspace-global key, so downloadAssetById reads them
+        // regardless of which repo's graph you call — authorization MUST come from
+        // the asset INDEX (its real owning repo + filename), exactly like the
+        // exporter. Resolve every input here; unknown/filename-mismatch refs are
+        // dropped (reported as skipped), and the resolved owning-repo is what the
+        // per-asset read check + download then use.
+        const assetIndex = workspaceManager.getAssetIndex();
+        const indexSkipped = [];
+        const resolvedAssets = [];
+        for (const a of requested) {
+            const row = a?.assetId ? assetIndex.get(a.assetId) : undefined;
+            if (!row || row.filename !== a.filename) {
+                indexSkipped.push({ assetId: a?.assetId ?? '', filename: a?.filename ?? '', reason: 'unknown' });
+                continue;
+            }
+            // Reject non-font rows up front — don't download + fontkit-parse an
+            // arbitrary (possibly large) blob just to discard it as unparseable.
+            if (!isFontAssetRow(row)) {
+                indexSkipped.push({ assetId: a.assetId, filename: a.filename, reason: 'not-a-font' });
+                continue;
+            }
+            resolvedAssets.push({ assetId: a.assetId, filename: a.filename, repo: row.repo });
         }
-        const committed = await sessionManager.flush(repo);
-        return reply.send({ committed });
-    });
-    // POST /api/repos/:repo/import — import files via agent processing
-    fastify.post('/api/repos/:repo/import', async (req, reply) => {
-        const { repo } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(403).send({ error: 'Access denied' });
+        let result;
+        try {
+            result = await buildFontSkill({
+                assets: resolvedAssets,
+                nameOverride: name,
+                // Read authz against the asset's REAL owning repo (from the index),
+                // not the caller-supplied one. download() only runs after canRead.
+                canRead: (assetRepo) => hasRepoAccess(req, assetRepo, workspaceManager, authService),
+                download: (assetRepo, assetId, filename) => workspaceManager.getGraph(assetRepo).downloadAssetById(assetId, filename),
+            });
         }
-        const body = req.body;
-        if (!body?.files || !Array.isArray(body.files)) {
-            return reply.status(400).send({ error: 'Expected { files: [{ filename, content }] }' });
+        catch (err) {
+            return reply.status(400).send({ error: err?.message ?? String(err) });
+        }
+        const skipped = [...indexSkipped, ...result.skipped];
+        if (!result.draft) {
+            return reply.status(422).send({ error: 'No readable font files in the selection.', skipped });
+        }
+        const draft = result.draft;
+        const normFolder = folder_path ? validateFolderPath(folder_path) : '';
+        const folderExisted = !normFolder || existsSync(join(graph.getRepoPath(), normFolder));
+        const actor = req.user?.displayName ?? 'API';
+        // Avoid clobbering an existing skill at the slug — append -2, -3, ….
+        let entityId = draft.entityId;
+        for (let i = 2; i < 1000; i++) {
+            try {
+                graph.get('skill', entityId);
+                entityId = `${draft.entityId}-${i}`;
+            }
+            catch {
+                break;
+            }
         }
-        const captureRepo = body.agentDecides ? undefined : repo;
+        const now = new Date().toISOString();
+        const actorId = reqGitUser(req)?.id ?? 'web';
         try {
-            const { extractText, isSupportedFile } = await import('../../services/import-service.js');
-            const results = [];
-            const CONCURRENCY = 3;
-            async function processFile(file) {
-                if (!file.filename || !isSupportedFile(file.filename)) {
-                    return { filename: file.filename, status: 'error', error: `Unsupported file: ${file.filename}` };
-                }
-                try {
-                    const text = await extractText(file.filename, file.content);
-                    if (!text) {
-                        console.warn(`[import] No text extracted from ${file.filename}`);
-                        return { filename: file.filename, status: 'error', error: 'No text content extracted' };
-                    }
-                    console.log(`[import] Extracted ${text.length} chars from ${file.filename}`);
-                    const captureRes = await fastify.inject({
-                        method: 'POST',
-                        url: '/api/capture',
-                        headers: {
-                            'content-type': 'application/json',
-                            ...(req.headers.authorization ? { authorization: req.headers.authorization } : {}),
-                            ...(req.headers.cookie ? { cookie: req.headers.cookie } : {}),
-                        },
-                        payload: JSON.stringify({ text: `[Imported from ${file.filename}]\n\n${text}`, ...(captureRepo ? { repo: captureRepo } : {}) }),
-                    });
-                    const captureBody = JSON.parse(captureRes.body);
-                    if (captureRes.statusCode !== 200 || !captureBody.success) {
-                        console.warn(`[import] Capture failed for ${file.filename}: ${captureRes.statusCode} ${captureBody.error ?? JSON.stringify(captureBody).slice(0, 200)}`);
-                        return { filename: file.filename, status: 'error', error: captureBody.error ?? 'Agent processing failed' };
-                    }
-                    return { filename: file.filename, status: 'created', entities: captureBody.entities };
-                }
-                catch (err) {
-                    return { filename: file.filename, status: 'error', error: err.message ?? 'Processing failed' };
-                }
-            }
-            // Process files in batches of CONCURRENCY
-            for (let i = 0; i < body.files.length; i += CONCURRENCY) {
-                const batch = body.files.slice(i, i + CONCURRENCY);
-                const batchResults = await Promise.all(batch.map(processFile));
-                results.push(...batchResults);
+            await graph.create({
+                entityType: 'skill',
+                entityId,
+                data: {
+                    entity_type: 'skill',
+                    entity_id: entityId,
+                    name: draft.name,
+                    description: draft.description,
+                    applies_to: ['artifact', 'deck', 'document'],
+                    loading: 'on-demand',
+                    tags: ['fonts'],
+                    created_at: now, updated_at: now, created_by: actorId, updated_by: actorId,
+                },
+                content: draft.content,
+                folderPath: folder_path,
+                commitMessage: `Create font skill ${draft.name} from web UI`,
+                user: reqGitUser(req),
+            });
+        }
+        catch (err) {
+            return reply.status(400).send({ error: err?.message ?? String(err), skipped });
+        }
+        wsHub?.broadcast({ type: 'entity_change', action: 'created', repo, entityType: 'skill', entityId, actor, source: 'api', timestamp: now });
+        if (!folderExisted) {
+            wsHub?.broadcast({ type: 'entity_change', action: 'created', repo, entityType: '_folder', entityId: normFolder, actor, source: 'api', timestamp: new Date().toISOString() });
+        }
+        return reply.status(201).send({
+            created: { repo, entityId, name: draft.name, families: draft.familyNames, faces: draft.faceCount },
+            skipped,
+        });
+    });
+    // POST /api/repos/:repo/move — move entry to a different folder within the
+    // same repo. Distinct from /transfer (cross-repo) and /rename (id change).
+    // The entry's type and id are unchanged; only its folder_path moves.
+    fastify.post('/api/repos/:repo/move', async (req, reply) => {
+        const { repo } = req.params;
+        const { entityType, entityId, folder_path } = req.body ?? {};
+        if (!entityType || !entityId || folder_path === undefined) {
+            return reply.status(400).send({ error: 'entityType, entityId, and folder_path are required' });
+        }
+        // Access enforced by graphForWrite (WorkspaceAccessService).
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
+        try {
+            if (sessionManager)
+                await sessionManager.flush(repo);
+            // If the destination folder doesn't exist yet, the move creates it —
+            // emit a _folder event (alongside the entry update) so clients refetch
+            // the folder tree, not just the entry list. Mirrors MCP move_entity.
+            const normTarget = folder_path ? validateFolderPath(folder_path) : '';
+            const targetExisted = !normTarget || existsSync(join(graph.getRepoPath(), normTarget));
+            const moved = await graph.move(entityType, entityId, folder_path, undefined, reqGitUser(req));
+            const actor = req.user?.displayName ?? 'API';
+            const ts = new Date().toISOString();
+            wsHub?.broadcast({
+                type: 'entity_change', action: 'updated', repo, entityType, entityId,
+                actor, source: 'api', timestamp: ts,
+            });
+            if (!targetExisted) {
+                wsHub?.broadcast({
+                    type: 'entity_change', action: 'created', repo, entityType: '_folder', entityId: normTarget,
+                    actor, source: 'api', timestamp: ts,
+                });
             }
-            const created = results.filter(r => r.status === 'created').length;
-            const entityCount = results.reduce((sum, r) => sum + (r.entities?.length ?? 0), 0);
-            return {
-                success: true,
-                imported: created,
-                entityCount,
-                skipped: results.filter(r => r.status === 'error').length,
-                errors: results.filter(r => r.status === 'error').map(r => r.error),
-                results,
-            };
+            return reply.send({ success: true, entity: moved });
         }
         catch (err) {
-            return reply.status(400).send({
-                success: false,
-                error: err instanceof Error ? err.message : 'Unknown error',
+            const status = err?.name === 'InvalidFolderPathError' ? 400
+                : err.message?.includes('already occupied') ? 409
+                    : err.message?.includes('not found') ? 404
+                        : 400;
+            return reply.status(status).send({ error: err.message });
+        }
+    });
+    // POST /api/repos/:repo/folders — create a folder (with .gitkeep). Auto-creates parents.
+    // Optional display_name is written to the folder's .studiograph-folder.json
+    // sidecar when set; otherwise the client falls back to toDisplayName(slug).
+    fastify.post('/api/repos/:repo/folders', async (req, reply) => {
+        const { repo } = req.params;
+        const { path, display_name } = req.body ?? {};
+        if (!path || typeof path !== 'string') {
+            return reply.status(400).send({ error: 'path is required' });
+        }
+        // Access enforced by graphForWrite (WorkspaceAccessService).
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
+        try {
+            const { alreadyExisted } = await graph.createFolder(path, undefined, reqGitUser(req), {
+                displayName: display_name,
             });
+            // Emit the _folder sentinel so OTHER connected clients refetch the
+            // folder tree (sidebar + list/gallery folder rows). The local creator
+            // already updated optimistically via workspace.addFolder.
+            wsHub?.broadcast({
+                type: 'entity_change', action: 'created', repo, entityType: '_folder', entityId: validateFolderPath(path),
+                actor: req.user?.displayName ?? 'API',
+                source: 'api', timestamp: new Date().toISOString(),
+            });
+            // createFolder is an idempotent ensure; report reuse so the caller isn't
+            // misled into thinking a duplicate name minted a new folder.
+            return reply.status(201).send({ success: true, path, alreadyExisted });
+        }
+        catch (err) {
+            return reply.status(400).send({ error: err.message });
         }
     });
-    // POST /api/repos/:repo/import-bookmarks — import browser bookmark exports as reference entities
-    fastify.post('/api/repos/:repo/import-bookmarks', async (req, reply) => {
+    // PATCH /api/repos/:repo/folders — rename / move a folder within the repo,
+    // optionally updating its display_name in the same commit. Three shapes:
+    //   { from, to }                       — slug-only rename / move
+    //   { from, to, display_name }          — slug change + display update
+    //   { from, to: from, display_name }    — display-only update (no FS move)
+    // `display_name: ""` (or null) clears the override and reverts to the slug
+    // fallback.
+    fastify.patch('/api/repos/:repo/folders', async (req, reply) => {
         const { repo } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(403).send({ error: 'Access denied' });
+        const { from, to, display_name } = req.body ?? {};
+        if (!from || !to) {
+            return reply.status(400).send({ error: 'from and to are required' });
+        }
+        // Access enforced by graphForWrite (WorkspaceAccessService).
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
+        try {
+            if (sessionManager)
+                await sessionManager.flush(repo);
+            await graph.renameFolder(from, to, undefined, reqGitUser(req), {
+                displayName: display_name === undefined ? undefined : display_name,
+            });
+            // Rename/move relocates entries on disk, so the _folder sentinel's
+            // refreshRepoAfterFolderMutation (tree + entity summaries) is exactly
+            // what other clients need. Carries the new path as the entityId.
+            wsHub?.broadcast({
+                type: 'entity_change', action: 'updated', repo, entityType: '_folder', entityId: validateFolderPath(to),
+                actor: req.user?.displayName ?? 'API',
+                source: 'api', timestamp: new Date().toISOString(),
+            });
+            return reply.send({ success: true, from, to });
         }
-        const body = req.body;
-        if (!body?.content || typeof body.content !== 'string') {
-            return reply.status(400).send({ error: 'Expected { content: string }' });
+        catch (err) {
+            const status = err?.name === 'InvalidFolderPathError' ? 400
+                : err.message?.includes('not found') ? 404
+                    : err.message?.includes('already exists') ? 409
+                        : 400;
+            return reply.status(status).send({ error: err.message });
+        }
+    });
+    // DELETE /api/repos/:repo/folders?path=X&recursive=true — delete a folder.
+    // Without recursive=true, non-empty folders return 409 with blast-radius
+    // counts so the UI can confirm before retrying.
+    fastify.delete('/api/repos/:repo/folders', async (req, reply) => {
+        const { repo } = req.params;
+        const { path, recursive } = req.query;
+        if (!path) {
+            return reply.status(400).send({ error: 'path query parameter is required' });
+        }
+        // Access enforced by graphForWrite (WorkspaceAccessService).
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
+        // Workspace Assets store gate (codex P1 / D2). A recursive delete in a
+        // workspace_wide store destroys every asset under the folder, bypassing
+        // the per-asset uploader/owner rule — restrict it to a workspace owner.
+        // (Non-recursive delete is blocked on non-empty folders by FOLDER_NOT_EMPTY,
+        // so it can't take assets with it.)
+        if (recursive === 'true' && workspaceManager.getRepoConfig(repo)?.workspace_wide && !isWorkspaceOwner(reqUser(req)?.role ?? '')) {
+            return reply.status(403).send({ error: 'Only a workspace owner can recursively delete folders in the shared Assets store.' });
         }
         try {
-            const { isNetscapeBookmarkFile, importBookmarks } = await import('../../services/bookmark-import-service.js');
-            if (!isNetscapeBookmarkFile(body.content)) {
-                return reply.status(400).send({
-                    error: "This doesn't appear to be a browser bookmark export. Export bookmarks from your browser's bookmark manager to generate the correct format.",
+            if (sessionManager)
+                await sessionManager.flush(repo);
+            const result = await graph.deleteFolder(path, {
+                recursive: recursive === 'true',
+                user: reqGitUser(req),
+            });
+            // Emit the _folder sentinel so other clients drop the folder (and any
+            // entries it held, via the entity-summary refresh) from their view.
+            wsHub?.broadcast({
+                type: 'entity_change', action: 'deleted', repo, entityType: '_folder', entityId: validateFolderPath(path),
+                actor: req.user?.displayName ?? 'API',
+                source: 'api', timestamp: new Date().toISOString(),
+            });
+            return reply.send({ success: true, ...result });
+        }
+        catch (err) {
+            if (err?.code === 'FOLDER_NOT_EMPTY') {
+                return reply.status(409).send({
+                    error: err.message,
+                    code: 'FOLDER_NOT_EMPTY',
+                    blast_radius: err.blastRadius,
                 });
             }
-            const graph = workspaceManager.getGraph(repo);
-            const user = reqGitUser(req);
-            const result = await importBookmarks(graph, body.content, user);
-            // Single git commit for all created entities
-            if (result.created > 0) {
-                const git = graph.getGitService();
-                if (git) {
-                    const commitUser = user ?? { id: 'import', name: 'Import', email: 'import@studiograph' };
-                    git.commitAll(`Import ${result.created} bookmark${result.created !== 1 ? 's' : ''} as references`, commitUser);
-                }
-            }
-            return {
-                success: true,
-                created: result.created,
-                skipped: result.skipped,
-                errors: result.errors,
-            };
+            const status = err?.name === 'InvalidFolderPathError' ? 400
+                : err.message?.includes('not found') ? 404
+                    : 400;
+            return reply.status(status).send({ error: err.message });
         }
-        catch (err) {
-            return reply.status(400).send({
-                success: false,
-                error: err instanceof Error ? err.message : 'Unknown error',
-            });
+    });
+    // POST /api/repos/:repo/commit — flush deferred commits (navigate-away signal)
+    fastify.post('/api/repos/:repo/commit', async (req, reply) => {
+        if (!sessionManager) {
+            return reply.send({ committed: false });
+        }
+        const { repo } = req.params;
+        // Access enforced via accessService.canRead \u2014 flush operates on the
+        // SessionManager (no graph instance needed), so a boolean check is
+        // sufficient. Pending commits were already authored by an authenticated
+        // writer; this endpoint just flushes them on navigate-away.
+        if (!accessService.canRead(reqUser(req), repo)) {
+            return reply.status(404).send({ error: `Folder \u201C${repo}\u201D not found` });
         }
+        const committed = await sessionManager.flush(repo);
+        return reply.send({ committed });
     });
-    // POST /api/repos/:repo/import-images — import images as reference entities
-    fastify.post('/api/repos/:repo/import-images', { bodyLimit: 50 * 1024 * 1024 }, async (req, reply) => {
+    // POST /api/repos/:repo/assets — generic asset upload.
+    //
+    // Multipart `file` field. Asset-as-embed (B2): stores a FREE-STANDING,
+    // folder-owned asset (assets.db row + immutable-key blob) — NO wrapper
+    // entity. Returns { assetId, asset_url, ... } for the caller to embed.
+    // For an IMAGE, graph.uploadAsset fires the caption/OCR trigger (assetId-
+    // keyed), and the caption folds into any entry that embeds the asset. See
+    // docs/asset-architecture.md.
+    fastify.post('/api/repos/:repo/assets', async (req, reply) => {
         const { repo } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(403).send({ error: 'Access denied' });
+        // Access enforced by graphForWrite (WorkspaceAccessService).
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
+        // Per-route fileSize override — the global multipart limit (10MB) is
+        // tuned for inline image embeds; full asset uploads accept up to the
+        // 100MB cap enforced inside AssetService.upload().
+        let file;
+        try {
+            file = await req.file({ limits: { fileSize: 100 * 1024 * 1024 } });
         }
-        const body = req.body;
-        if (!body?.files || !Array.isArray(body.files)) {
-            return reply.status(400).send({ error: 'Expected { files: [{ filename, content }] }' });
+        catch (err) {
+            return reply.status(400).send({ error: err?.message ?? 'Invalid multipart upload' });
         }
+        if (!file)
+            return reply.status(400).send({ error: 'No file uploaded' });
+        const buffer = await file.toBuffer();
         try {
-            const { importImages } = await import('../../services/image-import-service.js');
-            const graph = workspaceManager.getGraph(repo);
-            const user = reqGitUser(req);
-            const result = await importImages(graph, body.files, user);
-            // Single git commit for all created entities
-            if (result.created > 0) {
-                const git = graph.getGitService();
-                if (git) {
-                    const commitUser = user ?? { id: 'import', name: 'Import', email: 'import@studiograph' };
-                    git.commitAll(`Import ${result.created} image${result.created !== 1 ? 's' : ''} as references`, commitUser);
-                }
-            }
-            return {
+            // Asset-as-embed (B2): uploading to the Assets store produces a
+            // FREE-STANDING, folder-owned asset — NOT an `asset` entity. The asset
+            // manager lists it directly; the homepage capture embeds its URL into
+            // the entry it creates and deletes it by assetId if unused. Folder-owned
+            // assets are repo-scoped, so the `folder` subpath doesn't apply here.
+            const displayName = req.query.name?.trim()
+                || deriveAssetDisplayName(file.filename)
+                || file.filename;
+            const stored = await graph.uploadAsset('material', // ignored for ownership when `owner` is set
+            'asset', // ignored
+            file.filename, buffer, undefined, {
+                owner: { type: 'folder', id: repo },
+                uploaderUserId: reqUser(req)?.id != null ? String(reqUser(req).id) : null,
+                name: displayName,
+            });
+            wsHub?.broadcast({
+                type: 'repo_sync',
+                repo,
+                actor: req.user?.displayName ?? 'API',
+                source: 'api',
+                summary: 'uploaded an asset',
+                workspaceWide: workspaceManager.getRepoConfig(repo)?.workspace_wide === true,
+                timestamp: new Date().toISOString(),
+            });
+            // NOTE: image caption/OCR indexing is NOT derived for this
+            // free-standing asset — the caption sweep + live drain key on `asset`
+            // ENTITIES, which this no longer creates. It stays filename-only in
+            // vector search until the caption pipeline is rewired to be
+            // assets.db-row-keyed (tracked follow-up).
+            return reply.send({
                 success: true,
-                created: result.created,
-                skipped: result.skipped,
-                errors: result.errors,
-            };
+                assetId: stored.assetId,
+                asset_url: stored.publicUrl,
+                asset_kind: stored.mediaType,
+                filename: stored.filename,
+            });
         }
         catch (err) {
-            return reply.status(400).send({
-                success: false,
-                error: err instanceof Error ? err.message : 'Unknown error',
-            });
+            const msg = err instanceof Error ? err.message : String(err);
+            const status = msg.includes('not configured') ? 501
+                : msg.includes('Unsupported asset extension') ? 415
+                    : 400;
+            return reply.status(status).send({ success: false, error: msg });
         }
     });
 }