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

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

@@ -2,132 +2,64 @@
  * 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 { isAdminOrOwner } from '../../services/auth-service.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 };
-}
-/** Check if a user can see a private repo (only the owner can). */
-function canSeePrivateRepo(repo, user) {
-    if (!repo.private)
-        return true;
-    if (!user)
-        return !repo.owner_id; // API key / open mode — only if no owner set
-    if (!repo.owner_id)
-        return false; // Private without owner — hidden from all users
-    return user.id === repo.owner_id;
-}
-/** Get the list of repos the current user can access. */
-function getAccessibleRepos(req, workspaceManager, authService) {
-    const allRepos = workspaceManager.getAllRepoConfigs();
-    const user = req.user;
-    // Filter out private repos owned by other users (applies to all roles)
-    const visible = allRepos.filter(r => canSeePrivateRepo(r, user));
-    if (!user)
-        return visible; // API key / open mode → full access
-    if (isAdminOrOwner(user.role))
-        return visible;
-    const allowed = new Set(authService.getUserCollections(user.id));
-    return visible.filter(r => r.private || allowed.has(r.name));
-}
-/** Check if the current user can access a specific repo. */
-function hasRepoAccess(req, repoName, workspaceManager, authService) {
-    const user = req.user;
-    const repoConfig = workspaceManager.getRepoConfig(repoName);
-    if (repoConfig && !canSeePrivateRepo(repoConfig, user))
-        return false;
-    if (!user)
-        return true; // API key / open mode
-    if (repoConfig?.private && repoConfig?.owner_id === user.id)
-        return true; // Owner of private repo
-    if (isAdminOrOwner(user.role))
-        return true;
-    return authService.getUserCollections(user.id).includes(repoName);
-}
-/** Check if the current user is an admin. */
-function isAdmin(req) {
-    const user = req.user;
-    if (!user)
-        return true; // API key / open mode → admin-equivalent
-    return isAdminOrOwner(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
-    if (isAdminOrOwner(user.role)) {
-        // Admins see everything except other users' private repos
-        const allRepos = workspaceManager.getAllRepoConfigs();
-        const hasHiddenPrivate = allRepos.some(r => r.private && r.owner_id && r.owner_id !== user.id);
-        if (!hasHiddenPrivate)
-            return null; // No filtering needed
-    }
-    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));
-}
+import { createSharedFolder, FolderCreationError } from '../../services/folder-creation.js';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { 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, isFolderAdminOrOwner, reqGitUser, reqUser, } from './graph-api-access.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 { clearLegacyBucketCache } from '../../services/asset-listing.js';
+import { log } from '../../utils/log.js';
 export async function registerGraphApiRoutes(fastify, workspaceManager, authService, wsHub, sessionManager) {
-    // POST /api/repos — create a new collection (admin/owner only)
+    // 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) => {
-        if (!isAdmin(req)) {
-            return reply.status(403).send({ error: 'Admin access required' });
-        }
+        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: 'Collection name must be kebab-case' });
-        }
         try {
-            const workspace = new Workspace(workspaceManager['workspacePath']);
-            const repo = await workspace.registerRepo({
-                name,
-                display_name: display_name || undefined,
-                description,
-            });
-            workspaceManager.reloadConfig();
-            wsHub?.broadcast({
-                type: 'collection_created', repo: name,
-                actor: req.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 — remove a collection and delete its files (admin only)
+    // DELETE /api/repos/:repo — folder admin or workspace owner only.
     fastify.delete('/api/repos/:repo', async (req, reply) => {
-        if (!isAdmin(req)) {
-            return reply.status(403).send({ error: 'Admin access required' });
+        if (!isFolderAdminOrOwner(req, req.params.repo, workspaceManager, authService)) {
+            return reply.status(403).send({ error: 'Folder admin access required' });
         }
         const { repo } = req.params;
         try {
@@ -135,14 +67,19 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             const config = await workspace.loadConfig();
             const repoIndex = config.repos.findIndex(r => r.name === repo);
             if (repoIndex === -1) {
-                return reply.status(404).send({ error: `Collection "${repo}" not found` });
+                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);
             // Remove from config
             config.repos.splice(repoIndex, 1);
             workspace.writeConfig(config);
-            workspace.pushWorkspaceConfig(`Remove collection: ${repo}`);
+            workspace.pushWorkspaceConfig(`Remove folder: ${repo}`);
             // Delete files
             const { rmSync } = await import('fs');
             if (existsSync(repoPath)) {
@@ -150,7 +87,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(),
             });
@@ -160,16 +97,16 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             return reply.status(500).send({ error: err.message });
         }
     });
-    // PATCH /api/repos/:repo — update a collection (rename, sync rules) (admin only)
+    // PATCH /api/repos/:repo — rename/update sync rules. Folder admin or workspace owner only.
     fastify.patch('/api/repos/:repo', async (req, reply) => {
-        if (!isAdmin(req)) {
-            return reply.status(403).send({ error: 'Admin access required' });
+        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' });
+        if ('personal' in rest) {
+            return reply.status(400).send({ error: 'The personal flag is immutable after creation' });
         }
         if (newName === undefined && newSync === undefined && newDisplayName === undefined) {
             return reply.status(400).send({ error: 'Nothing to update' });
@@ -182,12 +119,17 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             const config = await workspace.loadConfig();
             const repoConfig = config.repos.find(r => r.name === repo);
             if (!repoConfig) {
-                return reply.status(404).send({ error: `Collection "${repo}" not found` });
+                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)) {
-                    return reply.status(409).send({ error: `Collection "${newName}" already exists` });
+                    return reply.status(409).send({ error: `Folder \u201C${newName}\u201D already exists` });
                 }
                 const wsPath = workspaceManager['workspacePath'];
                 const oldPath = join(wsPath, repoConfig.path);
@@ -206,8 +148,8 @@ 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
-                authService.renameCollection(repo, newName);
+                // Update folder_access to follow the rename
+                authService.renameFolder(repo, newName);
             }
             // Handle display name update (without rename)
             if (newDisplayName !== undefined && newName === undefined) {
@@ -218,7 +160,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);
         }
@@ -226,50 +168,128 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             return reply.status(500).send({ error: err.message });
         }
     });
-    // GET /api/repos — list accessible repos (re-reads config to pick up CLI changes)
+    // 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, 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);
-        return reply.send(repos);
+        // 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 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 {
+                // 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,
+                folders,
+            };
+        });
+        return reply.send(enriched);
+    });
+    // GET /api/admin/folders — workspace-owner-only metadata list of every folder
+    // (name, display_name, creator, member count). No content access implied —
+    // owners still need to join a folder to read its entries.
+    fastify.get('/api/admin/folders', async (req, reply) => {
+        const user = req.user;
+        if (user && !isWorkspaceOwner(user.role)) {
+            return reply.status(403).send({ error: 'Workspace owner access required' });
+        }
+        workspaceManager.reloadConfig();
+        const all = workspaceManager.getAllRepoConfigs();
+        const result = all.map(r => {
+            const members = authService.getFolderMembers(r.name);
+            const admins = members.filter(m => m.role === 'admin');
+            const creator = r.owner_id
+                ? 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,
+                description: r.description,
+                member_count: members.length,
+                admin_count: admins.length,
+                entry_count: entryCount,
+                creator: creator ? { id: creator.id, displayName: creator.displayName, email: creator.email } : null,
+                caller_is_member: user ? members.some(m => m.user.id === user.id) : true,
+            };
+        });
+        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: `Collection "${repo}" 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 => {
@@ -279,19 +299,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: `Collection "${repo}" 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 => {
@@ -304,17 +362,20 @@ 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: `Collection "${repo}" not found` });
-        }
-        let graph;
+        // Access enforced by graphForRead (WorkspaceAccessService).
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
+        let entity;
         try {
-            graph = workspaceManager.getGraph(repo);
+            entity = graph.get(type, id);
         }
         catch (err) {
-            return reply.status(404).send({ error: err.message });
+            return reply.status(404).send({ error: err.message ?? `Entity not found: ${type}/${id}` });
         }
-        const entity = graph.get(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}` });
         }
@@ -330,33 +391,151 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
     // 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: `Collection "${repo}" 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;
@@ -364,20 +543,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: `Collection "${repo}" 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,
@@ -393,19 +577,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({
@@ -433,10 +616,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) {
@@ -445,12 +628,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)
@@ -462,20 +668,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: `Collection "${repo}" not found` });
-        }
-        let graph;
-        try {
-            graph = workspaceManager.getGraph(repo);
-        }
-        catch (err) {
-            return reply.status(404).send({ error: err.message });
-        }
+        // 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 });
         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)) {
@@ -483,6 +698,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,
@@ -491,6 +740,12 @@ 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);
@@ -503,6 +758,19 @@ 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 });
         }
     });
@@ -513,16 +781,10 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         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: `Collection "${repo}" 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) {
@@ -547,45 +809,121 @@ 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
-    fastify.post('/api/repos/:repo/transfer', async (req, reply) => {
-        const sourceRepo = req.params.repo;
-        const { entityType, entityId, targetRepo, mode } = req.body ?? {};
-        if (!entityType || !entityId || !targetRepo || !mode) {
-            return reply.status(400).send({ error: 'entityType, entityId, targetRepo, and mode are required' });
+    // POST /api/repos/:repo/rename — rename an entity (changes its id/filename)
+    fastify.post('/api/repos/:repo/rename', async (req, reply) => {
+        const { repo } = req.params;
+        const { entityType: type, entityId: id, newId } = req.body ?? {};
+        if (!type || !id || !newId) {
+            return reply.status(400).send({ error: 'entityType, entityId, and newId are required' });
         }
-        if (sourceRepo === targetRepo) {
-            return reply.status(400).send({ error: 'Source and target collections must be different' });
+        if (!/^[a-z0-9][a-z0-9_-]*$/.test(newId)) {
+            return reply.status(400).send({ error: 'New ID must be kebab-case (lowercase letters, numbers, hyphens, underscores)' });
         }
-        if (!hasRepoAccess(req, sourceRepo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Collection "${sourceRepo}" not found` });
+        if (id === newId) {
+            return reply.status(400).send({ error: 'New ID must differ from the current ID' });
         }
-        if (!hasRepoAccess(req, targetRepo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Collection "${targetRepo}" 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 sourceGraph, targetGraph;
         try {
-            sourceGraph = workspaceManager.getGraph(sourceRepo);
-            targetGraph = workspaceManager.getGraph(targetRepo);
+            // Flush pending session saves so we don't PUT to the old path after rename
+            if (sessionManager) {
+                await sessionManager.flush(repo);
+            }
+            const gitUser = reqGitUser(req);
+            const renamed = await graph.rename(type, id, newId, undefined, gitUser);
+            // Rewrite any [[wikilinks]] that still point at the old id, across
+            // every folder the caller can access. Per-repo — cross-folder links
+            // are rare but supported.
+            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);
+                }
+                catch { /* skip unloadable repo */ }
+            }
+            wsHub?.broadcast({
+                type: 'entity_change', action: 'deleted', repo, entityType: type, entityId: id,
+                actor: req.user?.displayName ?? 'API',
+                source: 'api', timestamp: new Date().toISOString(),
+            });
+            wsHub?.broadcast({
+                type: 'entity_change', action: 'created', repo, entityType: type, entityId: newId,
+                actor: req.user?.displayName ?? 'API',
+                source: 'api', timestamp: new Date().toISOString(),
+            });
+            return reply.send({ success: true, entity: renamed, newUrl: `/${repo}/${type}/${newId}` });
         }
         catch (err) {
-            return reply.status(404).send({ error: err.message });
+            const status = err.message?.includes('already exists') ? 409 : 400;
+            return reply.status(status).send({ error: err.message });
+        }
+    });
+    // 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, 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' });
+        }
+        // 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 {
-            // 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,
@@ -593,21 +931,123 @@ 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 {
+                    // keepAssets: the moved entity's immutable-keyed blobs are shared
+                    // (same assetId in both repos' bodies during the window); the
+                    // source delete must not destroy them.
+                    await sourceGraph.delete(entityType, entityId, undefined, gitUser, { keepAssets: true });
+                    // 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 {
+                        // keepAssets: ownership was NOT reassigned (that happens only
+                        // after a successful source delete), so the blobs still belong
+                        // to the source entity we just restored. Destroying them here
+                        // would leave the recovered source pointing at dead URLs.
+                        await targetGraph.delete(entityType, entityId, undefined, gitUser, { keepAssets: true });
+                        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,
@@ -618,27 +1058,208 @@ 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: `Collection "${repo}" 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();
+            wsHub?.broadcast({ type: 'repo_sync', repo: sourceRepo, source: 'api', actor, timestamp: ts });
+            if (targetRepo !== sourceRepo) {
+                wsHub?.broadcast({ type: 'repo_sync', repo: targetRepo, source: 'api', 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', actor, timestamp: ts });
+            if (targetRepo !== sourceRepo) {
+                wsHub?.broadcast({ type: 'repo_sync', repo: targetRepo, source: 'api', 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));
+            // Deleting an asset entity removes its blob(s); drop the cached bucket
+            // walk so a legacy twin doesn't linger in the manager (codex P2).
+            if (type === 'asset')
+                clearLegacyBucketCache();
             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', 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 });
@@ -647,78 +1268,418 @@ 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: `Collection "${repo}" 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' });
         }
-        let graph;
+        // 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 });
+        // 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, 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/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,
+                });
+            }
+            return reply.send({ success: true, entity: moved });
+        }
+        catch (err) {
+            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 {
+            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(),
             });
-            return reply.status(201).send(entity);
+            return reply.status(201).send({ success: true, path });
         }
         catch (err) {
             return reply.status(400).send({ error: err.message });
         }
     });
+    // 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;
+        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 });
+        }
+        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 {
+            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 status = err?.name === 'InvalidFolderPathError' ? 400
+                : err.message?.includes('not found') ? 404
+                    : 400;
+            return reply.status(status).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 });
         }
         const { repo } = req.params;
-        if (!hasRepoAccess(req, repo, workspaceManager, authService)) {
-            return reply.status(404).send({ error: `Collection "${repo}" not found` });
+        // 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 — import files via agent processing
+    // POST /api/repos/:repo/import — import files into a folder.
+    //
+    // Routing by extension:
+    //   .md / .txt / .csv          → direct write via importFile() — no LLM
+    //     round-trip, preserves the source faithfully. Markdown frontmatter
+    //     (entity_type, entity_id) is honored when present; otherwise
+    //     sensible defaults.
+    //   .pdf + opaque binaries     → asset wrapper via uploadAsset() —
+    //     creates an `asset` entity, stores the binary in R2 or the local
+    //     volume, writes a PDF text sidecar for vector indexing.
+    //   .docx                      → text extraction + agent capture
+    //     pipeline (until the mammoth → markdown workstream lands).
     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' });
-        }
+        // Access enforced by graphForWrite — import creates entities, so write
+        // is required. Graph captured here is reused by the inner closures so
+        // they don't need to re-resolve (which would also bypass the gate).
+        const repoGraph = graphForWrite(req, reply, repo);
+        if (!repoGraph)
+            return;
         const body = req.body;
         if (!body?.files || !Array.isArray(body.files)) {
             return reply.status(400).send({ error: 'Expected { files: [{ filename, content }] }' });
         }
+        // Reject paths with traversal segments; importFile slugifies the rest.
+        // Empty / undefined = repo root (existing behavior).
+        const targetFolderPath = (body.targetFolderPath ?? '').trim();
+        if (targetFolderPath.split('/').some(seg => seg === '..' || seg === '.')) {
+            return reply.status(400).send({ error: 'Invalid targetFolderPath: contains traversal segments' });
+        }
         const captureRepo = body.agentDecides ? undefined : repo;
+        const gitUser = reqGitUser(req);
+        // Cancel support (CANCEL): the web client aborts the fetch via an
+        // AbortController. Listen on the RESPONSE stream's `close` — it fires when
+        // the connection drops, and `writableEnded` is false iff we haven't
+        // finished sending the response yet, i.e. a genuine mid-import client
+        // abort (vs the normal post-response close, where writableEnded is true).
+        // `reply.raw` is the ServerResponse, the canonical place to detect that
+        // the peer went away while we're still working; `req.raw` (the parsed
+        // request) is a less reliable signal for an abort during processing.
+        // Best-effort: the batch runner only reads this between batches, so a
+        // single-batch import still commits its completed prefix (additive +
+        // collision-safe). The listener is on this request's per-request
+        // ServerResponse, so it's GC'd with the request — no cross-request leak.
+        let clientGone = false;
+        reply.raw.on('close', () => {
+            if (!reply.raw.writableEnded)
+                clientGone = true;
+        });
         try {
-            const { extractText, isSupportedFile } = await import('../../services/import-service.js');
+            const { extractText, importFile } = await import('../../services/import-service.js');
+            const { importAssetAsEntity } = await import('../../services/asset-import-service.js');
+            const { resolveFormat, isIndexable, FALLBACK_ASSET_ENTRY } = await import('../../core/format-registry.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}` };
+            async function processDirect(file) {
+                // Reuse the access-checked graph captured in the outer scope. Do
+                // NOT re-resolve via workspaceManager.getGraph here — the audit's
+                // boundary is the outer graphForWrite call.
+                const graph = repoGraph;
+                const result = await importFile(graph, file.filename, file.content, {
+                    user: gitUser,
+                    // Caller-chosen destination subfolder; importFile combines it
+                    // with each file's own relative directory.
+                    folderPath: targetFolderPath || undefined,
+                    // Defer commits — we batch them into one transaction at the
+                    // end of the request so a 500-file import is one git commit
+                    // instead of 500. Per-file commits dominated wall time
+                    // (~50-200ms each) before this; batching collapses that to
+                    // one commit for the whole batch.
+                    skipCommit: true,
+                });
+                if (result.status === 'created' && result.path) {
+                    return {
+                        filename: file.filename,
+                        status: 'created',
+                        entities: [{ entityId: result.entityId, entityType: result.entityType }],
+                        entry: {
+                            operation: 'create',
+                            entityType: result.entityType,
+                            entityId: result.entityId,
+                            filePath: result.path,
+                        },
+                        sidecarPaths: result.sidecarPaths,
+                    };
                 }
+                return { filename: file.filename, status: result.status, error: result.error };
+            }
+            async function processAsset(file) {
+                // Reuse the outer access-checked graph; re-resolving would bypass
+                // the architectural boundary even though the closure captures repo.
+                const graph = repoGraph;
+                try {
+                    const buffer = Buffer.from(file.content, 'base64');
+                    // Asset-as-embed (Phase B): store the binary folder-owned + create a
+                    // properly-TYPED entity (document / dataset×N / material) that embeds
+                    // it via asset_ref. No self-owning `asset` entity, no text sidecar
+                    // (the seeded body is indexed natively). xlsx fans out to N datasets,
+                    // so this returns 1..N entities — `commitEntries` carries them all.
+                    const result = await importAssetAsEntity({
+                        graph,
+                        filename: file.filename,
+                        buffer,
+                        folderPath: targetFolderPath || undefined,
+                        user: gitUser,
+                        uploaderUserId: reqUser(req)?.id != null ? String(reqUser(req).id) : null,
+                        // Defer commits — the dispatcher's batched commitPending call at
+                        // the bottom of the route covers every entry in one transaction.
+                        skipCommit: true,
+                    });
+                    return {
+                        filename: file.filename,
+                        status: 'created',
+                        entities: result.entities.map(e => ({ entityId: e.entityId, entityType: e.entityType })),
+                        commitEntries: result.entities.map(e => ({
+                            operation: 'create',
+                            entityType: e.entityType,
+                            entityId: e.entityId,
+                            filePath: e.filePath,
+                        })),
+                    };
+                }
+                catch (err) {
+                    return { filename: file.filename, status: 'error', error: err.message ?? 'Asset import failed' };
+                }
+            }
+            async function processViaAgent(file) {
                 try {
                     const text = await extractText(file.filename, file.content);
                     if (!text) {
-                        console.warn(`[import] No text extracted from ${file.filename}`);
+                        log.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}`);
+                    log.info(`[import] Extracted ${text.length} chars from ${file.filename}`);
                     const captureRes = await fastify.inject({
                         method: 'POST',
                         url: '/api/capture',
@@ -731,7 +1692,7 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
                     });
                     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)}`);
+                        log.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 };
@@ -740,21 +1701,156 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
                     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);
+            // Route a single file off the format registry — the one source of
+            // truth for every ingestion surface. P0 is a parity refactor: the
+            // routing below reproduces today's behavior exactly. The only
+            // intentional follow-ups are flagged inline (docx/svg transitional
+            // paths; the FALLBACK reject that P0b flips to lenient).
+            async function routeByFormat(file, entry) {
+                // Transitional formats keep the current agent-extraction path until
+                // their real handler lands. After P2 this is svg only — it routes
+                // here until sanitize-html is wired (P3); routing it to uploadAsset
+                // before then would store unsanitized svg (stored-XSS). docx flipped
+                // to the asset path in P2 (uploads as asset, converts on demand).
+                if (entry.transitional === 'agent-extract') {
+                    return processViaAgent(file);
+                }
+                switch (entry.handler) {
+                    case 'importDirect':
+                        return processDirect(file);
+                    case 'uploadAsset':
+                        // P0 parity: genuinely-unknown types are still rejected. The
+                        // lenient generic-asset fallback (accept unknowns as assets) is
+                        // P0b — a deliberate behavior change made by removing exactly
+                        // this guard.
+                        if (entry === FALLBACK_ASSET_ENTRY) {
+                            return { filename: file.filename, status: 'error', error: `Unsupported file: ${file.filename}` };
+                        }
+                        return processAsset(file);
+                    default:
+                        // importBookmarks is not routed through the dispatcher until
+                        // P8 (content-sniff); bookmark exports still use the dedicated
+                        // POST /api/repos/:repo/import-bookmarks endpoint, so a bare
+                        // .html lands here and is rejected — matching today.
+                        return { filename: file.filename, status: 'error', error: `Unsupported file: ${file.filename}` };
+                }
+            }
+            async function processFile(file) {
+                if (!file.filename) {
+                    return { filename: file.filename, status: 'error', error: 'Missing filename' };
+                }
+                // Resolve the format once and thread it through routing.
+                // `searchable` (OV3 server contract) reflects the registry's
+                // DECLARED indexability for the file — the client (P5) renders the
+                // honest "stored as-is / not searchable" callouts from it.
+                // KNOWN LIMITATION: this is declared, not actual. A scanned/encrypted
+                // PDF declares searchable:true (indexAs:'sidecar') but yields no text,
+                // so it won't be flagged "stored as-is" even though its content is
+                // effectively filename-only. Closing that gap needs the extractor to
+                // report actual text-yield back into this flag (P3-indexing scope);
+                // the negative claim stays accurate, the positive one is best-effort.
+                const entry = resolveFormat(file.filename);
+                const searchable = isIndexable(entry);
+                const result = await routeByFormat(file, entry);
+                return { ...result, searchable };
+            }
+            // Process files in cancellable batches of CONCURRENCY. The runner
+            // checks the abort flag between batches: if the client disconnected
+            // (web AbortController), it stops dispatching the remainder, lets the
+            // in-flight batch settle, and returns the completed prefix — which the
+            // commitPending step below commits in one transaction (no uncommitted
+            // files left behind). Cancel is partial + honest: import is additive
+            // and collision-safe.
+            const { runImportBatches } = await import('./import-batch.js');
+            const { results: batched, cancelled } = await runImportBatches(body.files, processFile, { concurrency: CONCURRENCY, isAborted: () => clientGone });
+            results.push(...batched);
+            // Direct-write path deferred git commits — flush them all in one
+            // transaction now. Collapses N per-file commits into one batch
+            // commit (~50ms vs N×50ms). Agent-path files committed inline via
+            // /api/capture so they're not in this set.
+            const pendingEntries = results.flatMap(r => {
+                const pf = r;
+                // Asset-import files carry commitEntries (1..N); direct-write files
+                // carry a single entry. Prefer the plural, fall back to the singular.
+                if (pf.commitEntries && pf.commitEntries.length > 0)
+                    return pf.commitEntries;
+                return pf.entry ? [pf.entry] : [];
+            });
+            // Collect every sidecar path produced by the import — these stage in
+            // the same commit as the entity files, so the folder display name
+            // and the entries it labels land atomically. De-dup because two
+            // imported files inside the same Schema_OS/widgets/ would otherwise
+            // produce duplicate sidecar entries.
+            const sidecarPaths = Array.from(new Set(results.flatMap(r => r.sidecarPaths ?? [])));
+            // commitPending failure used to be swallowed and the route returned
+            // success=true even though the files were never committed. The audit
+            // (2026-05) flagged this: a 500-file import that failed mid-commit
+            // looked successful to the client but left N untracked files. Now
+            // the failure propagates as 500 with a partial-failure shape so the
+            // caller knows which entries are stranded.
+            let commitError = null;
+            if (pendingEntries.length > 0) {
+                try {
+                    await repoGraph.commitPending(pendingEntries, {
+                        commitMessage: `Import ${pendingEntries.length} ${pendingEntries.length === 1 ? 'entry' : 'entries'} from web UI`,
+                        user: gitUser,
+                        extraPaths: sidecarPaths.length > 0 ? sidecarPaths : undefined,
+                    });
+                }
+                catch (err) {
+                    commitError = err instanceof Error ? err.message : String(err);
+                    log.warn(`[import] batch commit failed for ${repo}: ${commitError}`);
+                }
             }
             const created = results.filter(r => r.status === 'created').length;
             const entityCount = results.reduce((sum, r) => sum + (r.entities?.length ?? 0), 0);
+            // Single repo_sync broadcast for the whole import. The realtime
+            // store's repo_sync handler refreshes the repo's entity list once
+            // — vs. one entity_change per file, which would do N re-renders
+            // on every connected client and freeze the UI for large imports.
+            // Skip when commit failed: there's nothing for clients to refresh
+            // beyond stranded uncommitted files, and the broadcast would lie
+            // about persistence.
+            if (created > 0 && !commitError) {
+                wsHub?.broadcast({
+                    type: 'repo_sync', repo,
+                    actor: req.user?.displayName ?? 'API',
+                    source: 'api', timestamp: new Date().toISOString(),
+                });
+                // Asset caption/extract enqueue is no longer wired here — it fires
+                // from the single VectorService.onAssetPending chokepoint when the
+                // asset's index state is seeded (covers every upload path uniformly).
+            }
+            const errors = results.filter(r => r.status === 'error').map(r => r.error);
+            if (commitError) {
+                // Files are on disk but uncommitted — partial failure. Surface as
+                // 500 with details so the client doesn't show "imported N entries"
+                // for entries that won't survive a server restart.
+                return reply.status(500).send({
+                    success: false,
+                    error: `Import wrote ${pendingEntries.length} entries to disk but the git commit failed: ${commitError}`,
+                    commitError,
+                    uncommittedEntries: pendingEntries.length,
+                    imported: created,
+                    entityCount,
+                    skipped: errors.length,
+                    errors,
+                    results,
+                });
+            }
             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),
+                skipped: errors.length,
+                errors,
                 results,
+                // Cancel summary (CANCEL): when the client disconnected mid-import we
+                // committed the completed prefix above and report N of M honestly.
+                // The aborting client typically won't read this (its fetch rejected),
+                // but it keeps the contract honest for any caller that does.
+                cancelled,
+                total: body.files.length,
             };
         }
         catch (err) {
@@ -767,9 +1863,10 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
     // POST /api/repos/:repo/import-bookmarks — import browser bookmark exports as reference entities
     fastify.post('/api/repos/:repo/import-bookmarks', 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 — bookmark import creates entities.
+        const graph = graphForWrite(req, reply, repo);
+        if (!graph)
+            return;
         const body = req.body;
         if (!body?.content || typeof body.content !== 'string') {
             return reply.status(400).send({ error: 'Expected { content: string }' });
@@ -781,7 +1878,6 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
                     error: "This doesn't appear to be a browser bookmark export. Export bookmarks from your browser's bookmark manager to generate the correct format.",
                 });
             }
-            const graph = workspaceManager.getGraph(repo);
             const user = reqGitUser(req);
             const result = await importBookmarks(graph, body.content, user);
             // Single git commit for all created entities
@@ -806,41 +1902,75 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
             });
         }
     });
-    // 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',
+                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 });
         }
     });
 }