studiograph 1.3.48-next.13 → 1.3.48-next.130

package/dist/core/graph.js

@@ -4,14 +4,34 @@
  * Provides unified entity management across any repo type.
  * Integrates Git, Markdown, and Asset services.
  */
-import { join, dirname } from 'path';
-import { existsSync, readdirSync, statSync, mkdirSync } from 'fs';
+import { join, dirname, relative } from 'path';
+import { existsSync, readdirSync, rmSync, statSync, writeFileSync, mkdirSync } from 'fs';
 import { GitService } from '../services/git.js';
 import { MarkdownService } from '../services/markdown.js';
 import { AssetService } from '../services/assets/index.js';
-import { ENTITY_SCHEMAS, EntityBaseSchema, SINGULAR_TO_PLURAL, PLURAL_TO_SINGULAR } from './validation.js';
-import { CSVService } from '../services/csv-service.js';
+import { ENTITY_SCHEMAS, EntityBaseSchema, PLURAL_TO_SINGULAR } from './validation.js';
+import { folderPathFromFile, normalizeFolderPath, validateFolderPath, InvalidFolderPathError } from './folder-paths.js';
+import { FOLDER_SIDECAR, folderSidecarPath, readFolderSidecar, removeFolderSidecar, writeFolderSidecar } from './folder-sidecar.js';
 import { z } from 'zod';
+/** Names skipped during recursive repo walks. */
+const WALK_IGNORE = new Set(['.git', '.studiograph', 'node_modules']);
+/**
+ * Thrown by `restoreFile` when the path the recreate would land at is
+ * currently occupied by a different entity. Carries the occupant's
+ * coordinates so callers (agent tool, REST endpoint) can surface a
+ * useful error to the user.
+ */
+export class PathConflictError extends Error {
+    path;
+    occupiedBy;
+    code = 'PATH_CONFLICT';
+    constructor(path, occupiedBy) {
+        super(`Path ${path} is occupied by ${occupiedBy.entityType}/${occupiedBy.entityId}`);
+        this.path = path;
+        this.occupiedBy = occupiedBy;
+        this.name = 'PathConflictError';
+    }
+}
 export class BaseGraphManager {
     repoPath;
     repoName;
@@ -20,9 +40,10 @@ export class BaseGraphManager {
     markdownService;
     assetService;
     gitUser;
-    csvService;
     vectorService;
     schemaRegistry;
+    workspaceRoot;
+    mutationCallbacks;
     constructor(config) {
         this.repoPath = config.repoPath;
         this.repoName = config.repoName;
@@ -30,12 +51,12 @@ export class BaseGraphManager {
         this.noGit = config.noGit ?? false;
         this.vectorService = config.vectorService;
         this.schemaRegistry = config.schemaRegistry;
+        this.workspaceRoot = config.workspaceRoot;
         // Initialize services
         if (!this.noGit) {
             this.gitService = new GitService(this.repoPath);
         }
         this.markdownService = new MarkdownService();
-        this.csvService = new CSVService();
         // Asset service is optional (can be disabled for repos without assets)
         if (config.assetConfig) {
             this.assetService = new AssetService(config.assetConfig);
@@ -43,10 +64,41 @@ export class BaseGraphManager {
         // Ensure repo is initialized
         this.ensureRepo();
     }
-    /** Expose git service for deferred commit operations (e.g. CommitScheduler). */
+    /** Expose git service for deferred commit operations (SessionManager). */
     getGitService() {
         return this.gitService;
     }
+    /** Absolute repo path on disk. Used by callers that need to convert
+     *  an entity's absolute path to a repo-relative one (e.g. for `git log`). */
+    getRepoPath() {
+        return this.repoPath;
+    }
+    /**
+     * Find an entity at a specific commit (existing or deleted) and
+     * return its repo-relative path + content. Public surface for the
+     * history tools — wraps the private `findEntityInCommit` walker.
+     * Returns null when no .md file at that commit matches the
+     * (entityType, entityId) pair.
+     */
+    getEntityAtCommit(entityType, entityId, commitHash) {
+        return this.findEntityInCommit(entityType, entityId, commitHash);
+    }
+    /** Workspace root passed in via GraphConfig. Used by the asset upload
+     *  service to anchor PDF text sidecars at workspace level (so all repos
+     *  share the same `assets-text/` tree, mirroring the shared
+     *  `.studiograph/assets/` directory the local backend uses). */
+    getWorkspaceRoot() {
+        return this.workspaceRoot;
+    }
+    /**
+     * Install post-mutation callbacks. Called once after construction by the
+     * server bootstrap (or test setup) so the Yjs persistence layer can react
+     * to structural mutations without route-layer code calling persistence
+     * APIs directly.
+     */
+    setMutationCallbacks(callbacks) {
+        this.mutationCallbacks = callbacks;
+    }
     /**
      * Ensure repository exists
      */
@@ -57,11 +109,127 @@ export class BaseGraphManager {
         // GitService automatically initializes in constructor
     }
     /**
-     * Get entity file path: {repo}/{plural-type}/{entityId}.md
+     * Compute the on-disk path for a new entity.
+     *
+     * - When `folderPath` is provided, the entry lives at {repo}/{folderPath}/{id}.md
+     *   regardless of type. This is the nested-folders layout.
+     * - Without `folderPath` (or empty string), the entry lands at the repo
+     *   root: {repo}/{id}.md. The historical {repo}/{plural-type}/{id}.md
+     *   fallback was confusing — entries hidden under a typed directory the
+     *   list view never showed at repo root, contradicting the agent tool
+     *   description that says "Omit to land at repo root."
+     *
+     * Note: this is for *new* paths only. Existing entries living under the
+     * legacy {plural-type}/ directories continue to be readable via
+     * findEntityFile() — only the create path moved.
+     */
+    getEntityPath(entityType, entityId, folderPath) {
+        const normalized = folderPath ? normalizeFolderPath(folderPath) : '';
+        if (normalized) {
+            return join(this.repoPath, normalized, `${entityId}.md`);
+        }
+        return join(this.repoPath, `${entityId}.md`);
+    }
+    // ────────────────────────────────────────────────────────────────────────────
+    // Recursive file walk + (type, id) → path index
+    //
+    // With nested folders, an entry can live at any depth under the repo root.
+    // We can't compute its path from (type, id) alone — we have to find it.
+    // The index caches that lookup; mutations invalidate it via invalidateIndex().
+    // ────────────────────────────────────────────────────────────────────────────
+    fileIndex;
+    /** Drop the cached file index so the next read rebuilds it. */
+    invalidateIndex() {
+        this.fileIndex = undefined;
+    }
+    /**
+     * Walk every .md file under this repo, calling `visit` with the absolute
+     * path. Skips hidden directories (.git, .studiograph, etc.) and files that
+     * start with ".".
+     */
+    walkMarkdownFiles(visit) {
+        if (!existsSync(this.repoPath))
+            return;
+        const stack = [this.repoPath];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            let entries;
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.startsWith('.'))
+                    continue;
+                if (WALK_IGNORE.has(entry))
+                    continue;
+                const full = join(dir, entry);
+                let st;
+                try {
+                    st = statSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (st.isDirectory()) {
+                    stack.push(full);
+                }
+                else if (st.isFile() && entry.endsWith('.md')) {
+                    visit(full);
+                }
+            }
+        }
+    }
+    /**
+     * Build (or fetch the cached) "type/id" → absolute path index.
+     * Type comes from frontmatter `entity_type`; if missing, falls back to the
+     * top-level plural-type directory name (legacy layout). Files without either
+     * (e.g. README.md) are skipped — they aren't entities.
      */
-    getEntityPath(entityType, entityId) {
-        const pluralDir = SINGULAR_TO_PLURAL[entityType] || `${entityType}s`;
-        return join(this.repoPath, pluralDir, `${entityId}.md`);
+    getFileIndex() {
+        if (this.fileIndex)
+            return this.fileIndex;
+        const index = new Map();
+        this.walkMarkdownFiles((filePath) => {
+            try {
+                const doc = this.markdownService.parseFile(filePath);
+                const fmType = doc.frontmatter.entity_type;
+                const inferred = this.inferLegacyType(filePath);
+                const type = fmType || inferred;
+                if (!type)
+                    return; // README, CONTRIBUTING, etc.
+                const id = filePath.split('/').pop().replace(/\.md$/, '');
+                index.set(`${type}/${id}`, filePath);
+            }
+            catch { /* skip unparsable */ }
+        });
+        this.fileIndex = index;
+        return index;
+    }
+    /**
+     * Infer entity type from a file's location for legacy layouts where the
+     * file sits directly inside a top-level plural-type directory
+     * ({repo}/meetings/foo.md). Returns undefined for any other layout.
+     */
+    inferLegacyType(absPath) {
+        const rel = relative(this.repoPath, absPath);
+        const parts = rel.split('/');
+        if (parts.length !== 2)
+            return undefined; // not at depth 1
+        return PLURAL_TO_SINGULAR[parts[0]];
+    }
+    /**
+     * Resolve an entity's absolute path by (type, id). Returns undefined if not
+     * found. Uses the file index — the index keys by `${entityType}/${entityId}`
+     * which is type-aware, unlike the on-disk filename. (We previously had a
+     * legacy {plural-type}/{id}.md fast path here; once the create path moved
+     * to flat repo-root layout, that fast path could return a different
+     * type's file at the same id.)
+     */
+    findEntityFile(entityType, entityId) {
+        return this.getFileIndex().get(`${entityType}/${entityId}`);
     }
     /**
      * Validate entity data against schema
@@ -111,7 +279,7 @@ export class BaseGraphManager {
         }
         catch (error) {
             if (error instanceof z.ZodError) {
-                const messages = error.errors.map(e => `${e.path.join('.')}: ${e.message}`);
+                const messages = error.issues.map(e => `${e.path.join('.')}: ${e.message}`);
                 throw new Error(`Validation failed for ${entityType}:\n${messages.join('\n')}`);
             }
             throw error;
@@ -121,12 +289,18 @@ export class BaseGraphManager {
      * Create a new entity
      */
     async create(options) {
-        const { entityType, entityId, data, content = '', commitMessage, skipCommit, user } = options;
+        const { entityType, entityId, data, content = '', commitMessage, skipCommit, folderPath, user } = options;
+        const normalizedFolder = folderPath ? validateFolderPath(folderPath) : '';
         // Prepopulate date from created_at if not provided
         if (!data.date && data.created_at) {
             data.date = String(data.created_at).split('T')[0];
         }
-        // Add missing schema fields with empty defaults so the frontmatter is complete
+        // Add missing schema fields with empty defaults so the frontmatter is complete.
+        // Only string and array fields get populated — empty string isn't a valid
+        // member of number/boolean/enum/url types, and seeding them with '' caused
+        // optional numeric fields like `deal_value` to fail validation as
+        // "Expected number, received string". Anything that can't legitimately
+        // hold '' is left absent so the optional check passes.
         const schema = ENTITY_SCHEMAS[entityType];
         if (schema) {
             const shape = schema.shape;
@@ -139,28 +313,44 @@ export class BaseGraphManager {
                     // Unwrap ZodOptional/ZodDefault to get the inner type
                     const inner = field instanceof z.ZodOptional ? field._def.innerType
                         : field instanceof z.ZodDefault ? field._def.innerType : field;
-                    if (inner instanceof z.ZodEnum) {
-                        // Don't populate enum fields with empty string — leave them unset
+                    if (inner instanceof z.ZodArray) {
+                        data[key] = [];
                         continue;
                     }
-                    const isArray = inner instanceof z.ZodArray;
-                    data[key] = isArray ? [] : '';
+                    if (inner instanceof z.ZodString) {
+                        // Skip URL-typed strings — empty string fails URL validation.
+                        if (inner._def.checks?.some((c) => c.def?.format === 'url'))
+                            continue;
+                        data[key] = '';
+                        continue;
+                    }
+                    // Numbers, booleans, enums, literals, unions: leave absent.
                 }
             }
         }
         // Validate data
         const validatedData = this.validateEntity(entityType, data);
-        // Check if entity already exists
-        const entityPath = this.getEntityPath(entityType, entityId);
-        if (existsSync(entityPath)) {
+        // Reject if (type, id) is already taken anywhere in the repo — IDs are
+        // unique within (repo, type) regardless of folder.
+        const existingPath = this.findEntityFile(entityType, entityId);
+        if (existingPath) {
             throw new Error(`Entity already exists: ${entityType}/${entityId}`);
         }
+        // Compute target path. With folderPath set, entries land at
+        // {repo}/{folderPath}/{id}.md (parents auto-created); without, fall back
+        // to legacy {plural-type}/{id}.md.
+        const entityPath = this.getEntityPath(entityType, entityId, normalizedFolder);
+        mkdirSync(dirname(entityPath), { recursive: true });
         // Write markdown file
         this.markdownService.writeFile(entityPath, {
             frontmatter: validatedData,
             content,
             wikilinks: this.markdownService.extractWikilinks(content, validatedData),
         });
+        // The folder now has an .md child, so any pre-existing .gitkeep is
+        // redundant. Drop it as part of the same commit so the repo stays tidy.
+        const removedMarker = this.removeFolderMarker(dirname(entityPath));
+        this.invalidateIndex();
         if (this.gitService && !skipCommit) {
             const transaction = this.gitService.createTransaction();
             transaction.add({
@@ -169,21 +359,42 @@ export class BaseGraphManager {
                 entityId,
                 filePath: entityPath,
             });
+            if (removedMarker) {
+                transaction.add({
+                    operation: 'delete',
+                    entityType,
+                    entityId,
+                    filePath: removedMarker,
+                });
+            }
             const message = commitMessage || `Create ${entityType}: ${entityId}`;
             await transaction.commit(user ?? this.gitUser, message);
         }
         // Return created entity
         const created = this.get(entityType, entityId);
-        // Update vector index (fire-and-forget, non-fatal)
-        this.vectorService?.upsert(this.repoName, created).catch(err => console.warn(`[vector] index failed for ${entityType}/${entityId}:`, err.message));
+        // Update vector index (fire-and-forget, non-fatal). Failures are
+        // tracked on VectorService for /api/health visibility — the audit
+        // (2026-05) flagged that silent .catch(console.warn) made a steady
+        // index-failure leak undetectable until search results went stale.
+        if (this.vectorService) {
+            const v = this.vectorService;
+            v.beginOp();
+            v.upsert(this.repoName, created)
+                .then(() => v.recordSuccess())
+                .catch(err => {
+                v.recordFailure('upsert', `${entityType}/${entityId}`, err);
+                console.warn(`[vector] index failed for ${entityType}/${entityId}:`, err.message);
+            });
+        }
         return created;
     }
     /**
-     * Get an entity by type and ID
+     * Get an entity by type and ID. Searches nested folders if the entry isn't
+     * at the legacy {plural-type}/{id}.md path.
      */
     get(entityType, entityId) {
-        const entityPath = this.getEntityPath(entityType, entityId);
-        if (!existsSync(entityPath)) {
+        const entityPath = this.findEntityFile(entityType, entityId);
+        if (!entityPath) {
             throw new Error(`Entity not found: ${entityType}/${entityId}`);
         }
         const document = this.markdownService.parseFile(entityPath);
@@ -205,53 +416,62 @@ export class BaseGraphManager {
         return {
             id: entityId,
             path: entityPath,
+            folder_path: folderPathFromFile(entityPath, this.repoPath),
             entityType,
             data: validatedData,
             document,
         };
     }
     /**
-     * Get an entity by ID only (type resolved from frontmatter)
+     * Get an entity by ID only (type resolved from the filesystem).
+     *
+     * Walks the file index to find any entry with this id, regardless of folder
+     * depth or type. Used by the agent's `get_entity` tool when the caller
+     * doesn't know the entity's type.
      */
     getById(entityId) {
-        const entityPath = this.getEntityPath('', entityId);
-        if (!existsSync(entityPath)) {
+        if (!existsSync(this.repoPath)) {
             throw new Error(`Entity not found: ${entityId}`);
         }
-        const document = this.markdownService.parseFile(entityPath);
-        const entityType = document.frontmatter.entity_type ?? this.repoName;
-        let validatedData;
-        try {
-            validatedData = this.validateEntity(entityType, document.frontmatter);
-        }
-        catch {
-            validatedData = this.validateEntity(entityType, document.frontmatter, true);
+        for (const [key] of this.getFileIndex()) {
+            const slash = key.indexOf('/');
+            if (slash === -1)
+                continue;
+            const id = key.slice(slash + 1);
+            if (id === entityId) {
+                const type = key.slice(0, slash);
+                return this.get(type, entityId);
+            }
         }
-        return {
-            id: entityId,
-            path: entityPath,
-            entityType,
-            data: validatedData,
-            document,
-        };
+        throw new Error(`Entity not found: ${entityId}`);
     }
     /**
      * Update an existing entity
      */
     async update(options) {
-        const { entityType, entityId, data, content, commitMessage, skipCommit, user } = options;
+        const { entityType, entityId, data, content, commitMessage, skipCommit, user, skipYjsSync } = options;
         // Get existing entity
         const existing = this.get(entityType, entityId);
-        // Merge data (if provided) and add update metadata
+        // Merge data (if provided) and always stamp update metadata. Even
+        // content-only edits (editor autosave) must update `updated_by` /
+        // `updated_at` — otherwise the audit trail freezes at whatever the
+        // last data-change user was, which for scaffolded files is
+        // "studiograph".
+        const updater = (user ?? this.gitUser).id;
+        const now = new Date().toISOString();
         const mergedData = data
             ? {
                 ...existing.data,
                 ...data,
                 entity_type: entityType,
-                updated_at: new Date().toISOString(),
-                updated_by: (user ?? this.gitUser).id,
+                updated_at: now,
+                updated_by: updater,
             }
-            : existing.data;
+            : {
+                ...existing.data,
+                updated_at: now,
+                updated_by: updater,
+            };
         // Validate merged data — use lenient validation when no new data is provided,
         // since the existing entity may have been stored without all required fields.
         // Raw fallback coerces Date objects to YYYY-MM-DD so gray-matter doesn't
@@ -281,13 +501,30 @@ export class BaseGraphManager {
         }
         // Merge content (if provided)
         const mergedContent = content !== undefined ? content : existing.document.content;
-        // Write updated markdown file
-        const entityPath = this.getEntityPath(entityType, entityId);
+        // Update in place — write to wherever the entry already lives, not
+        // wherever a fresh getEntityPath() computation would put it. Otherwise
+        // an entry in a nested folder gets duplicated to the legacy plural-type
+        // dir on first update.
+        const entityPath = existing.path;
         this.markdownService.writeFile(entityPath, {
             frontmatter: validatedData,
             content: mergedContent,
             wikilinks: this.markdownService.extractWikilinks(mergedContent, validatedData),
         });
+        // Fire onContentUpdate SYNCHRONOUSLY before the git commit's await yield.
+        // This guarantees the Y.Doc is reconciled with the new .md content before
+        // any concurrent autosave PUT can land and overwrite it. Without the
+        // strict ordering, an autosave that arrived during the git commit would
+        // write stale Y.Text content over the just-written .md, silently losing
+        // server-bypass writes (MCP, agent, event processor).
+        if (!skipYjsSync && this.mutationCallbacks?.onContentUpdate) {
+            try {
+                this.mutationCallbacks.onContentUpdate(this.repoName, entityType, entityId);
+            }
+            catch (err) {
+                console.warn(`[graph] onContentUpdate callback failed for ${entityType}/${entityId}:`, err);
+            }
+        }
         if (this.gitService && !skipCommit) {
             const transaction = this.gitService.createTransaction();
             transaction.add({
@@ -301,19 +538,150 @@ export class BaseGraphManager {
         }
         // Return updated entity
         const updated = this.get(entityType, entityId);
-        // Update vector index (fire-and-forget, non-fatal)
-        this.vectorService?.upsert(this.repoName, updated).catch(err => console.warn(`[vector] index failed for ${entityType}/${entityId}:`, err.message));
+        // Update vector index (fire-and-forget, non-fatal). Tracked on the
+        // service so /api/health surfaces a steady failure stream instead of
+        // burying it in stdout warnings.
+        if (this.vectorService) {
+            const v = this.vectorService;
+            v.beginOp();
+            v.upsert(this.repoName, updated)
+                .then(() => v.recordSuccess())
+                .catch(err => {
+                v.recordFailure('upsert', `${entityType}/${entityId}`, err);
+                console.warn(`[vector] index failed for ${entityType}/${entityId}:`, err.message);
+            });
+        }
         return updated;
     }
     /**
      * Delete an entity
      */
+    /**
+     * Delete multiple entities in a single git transaction. Each entity's
+     * file is removed from disk; folder markers (.gitkeep) are added where
+     * the deletion left a folder empty. Then everything commits as one
+     * atomic operation.
+     *
+     * Compared to looping `delete()` per entity, this is a real performance
+     * primitive: one fork of git, one index update, one commit, one ref
+     * advance — instead of N. Bulk delete of a few hundred entities goes
+     * from minutes to seconds.
+     *
+     * Errors per entity (e.g. "not found") don't abort the batch — they're
+     * collected in `errors` and the rest still commit. Returns both the
+     * successfully-deleted set (for vector cleanup + WS broadcast) and the
+     * errors so the caller can surface partial failures.
+     */
+    async bulkDelete(specs, options) {
+        const deleted = [];
+        const errors = [];
+        const transaction = this.gitService?.createTransaction();
+        for (const { entityType, entityId } of specs) {
+            try {
+                const existing = this.get(entityType, entityId);
+                rmSync(existing.path, { force: true });
+                // Folder marker if the deletion emptied the folder — same lifecycle
+                // semantics as single delete().
+                const addedMarker = this.ensureFolderMarker(dirname(existing.path));
+                if (transaction) {
+                    transaction.add({ operation: 'delete', entityType, entityId, filePath: existing.path });
+                    if (addedMarker) {
+                        transaction.add({ operation: 'create', entityType, entityId, filePath: addedMarker });
+                    }
+                }
+                deleted.push({ entityType, entityId, path: existing.path });
+            }
+            catch (err) {
+                errors.push({
+                    entityType,
+                    entityId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        this.invalidateIndex();
+        if (transaction && deleted.length > 0) {
+            const message = options?.commitMessage
+                ?? `Delete ${deleted.length} ${deleted.length === 1 ? 'entry' : 'entries'} from web UI`;
+            await transaction.commit(options?.user ?? this.gitUser, message);
+        }
+        // Vector index cleanup, fire-and-forget (matches single delete() behavior).
+        // Failures recorded on VectorService for /api/health visibility.
+        for (const { entityType, entityId } of deleted) {
+            if (!this.vectorService)
+                continue;
+            const v = this.vectorService;
+            v.beginOp();
+            v.delete(this.repoName, entityType, entityId)
+                .then(() => v.recordSuccess())
+                .catch(err => {
+                v.recordFailure('delete', `${entityType}/${entityId}`, err);
+                console.warn(`[vector] delete failed for ${entityType}/${entityId}:`, err.message);
+            });
+        }
+        return { deleted, errors };
+    }
+    /**
+     * Commit a set of already-on-disk file changes as a single git
+     * operation. Used by callers (e.g. the import route) that perform many
+     * `skipCommit: true` writes and want one transaction at the end instead
+     * of per-file commits.
+     *
+     * `entries` describes what each file represents so the transaction can
+     * be staged correctly. No-op when nothing is staged or git isn't
+     * available.
+     */
+    async commitPending(entries, options) {
+        if (!this.gitService)
+            return { committed: false };
+        if (entries.length === 0 && !options.extraPaths?.length)
+            return { committed: false };
+        const transaction = this.gitService.createTransaction();
+        for (const e of entries)
+            transaction.add(e);
+        // Auxiliary paths (folder-display sidecars from the import flow) are
+        // staged alongside the entity files so they land in the same commit.
+        // The transaction only uses `filePath` for staging — the other fields
+        // are metadata, so we fill them with sentinel values.
+        if (options.extraPaths?.length) {
+            for (const filePath of options.extraPaths) {
+                transaction.add({
+                    operation: 'create',
+                    entityType: '_sidecar',
+                    entityId: '_sidecar',
+                    filePath,
+                });
+            }
+        }
+        await transaction.commit(options.user ?? this.gitUser, options.commitMessage);
+        return { committed: true };
+    }
     async delete(entityType, entityId, commitMessage, user) {
         // Verify entity exists
         const existing = this.get(entityType, entityId);
         // Delete the flat entity file
-        const { rmSync } = await import('fs');
         rmSync(existing.path, { force: true });
+        // Asset entities own a binary blob (and optionally a PDF text sidecar).
+        // Both must be cleaned up — leaving them orphans the storage layer and
+        // poisons future entity_id reuse with a stale text dump. Fire-and-forget:
+        // the markdown is the system of record, so a stuck binary shouldn't
+        // block the delete commit. (Same approach as vector-index cleanup below.)
+        if (entityType === 'asset' && this.assetService) {
+            this.assetService.deleteAll('asset', entityId).catch(err => console.warn(`[asset] deleteAll failed for asset/${entityId}: ${err?.message ?? err}`));
+            if (this.workspaceRoot) {
+                const sidecarPath = join(this.workspaceRoot, '.studiograph', 'assets-text', 'asset', `${entityId}.txt`);
+                try {
+                    rmSync(sidecarPath, { force: true });
+                }
+                catch { /* sidecar cleanup is best-effort */ }
+            }
+        }
+        // Folder lifecycle: deleting an entry never deletes its containing folder.
+        // If this was the last .md in the folder, write a .gitkeep so it stays
+        // visible to listFolders() (and therefore to the sidebar). A user who
+        // wants the folder gone calls deleteFolder() explicitly.
+        const addedMarker = this.ensureFolderMarker(dirname(existing.path));
+        this.invalidateIndex();
         if (this.gitService) {
             const transaction = this.gitService.createTransaction();
             transaction.add({
@@ -322,11 +690,42 @@ export class BaseGraphManager {
                 entityId,
                 filePath: existing.path,
             });
+            if (addedMarker) {
+                transaction.add({
+                    operation: 'create',
+                    entityType,
+                    entityId,
+                    filePath: addedMarker,
+                });
+            }
             const message = commitMessage || `Delete ${entityType}: ${entityId}`;
             await transaction.commit(user ?? this.gitUser, message);
         }
-        // Remove from vector index (fire-and-forget, non-fatal)
-        this.vectorService?.delete(this.repoName, entityType, entityId).catch(err => console.warn(`[vector] delete failed for ${entityType}/${entityId}:`, err.message));
+        // Remove from vector index (fire-and-forget, non-fatal). Tracked on
+        // the service so a leaking error stream is visible at /api/health.
+        if (this.vectorService) {
+            const v = this.vectorService;
+            v.beginOp();
+            v.delete(this.repoName, entityType, entityId)
+                .then(() => v.recordSuccess())
+                .catch(err => {
+                v.recordFailure('delete', `${entityType}/${entityId}`, err);
+                console.warn(`[vector] delete failed for ${entityType}/${entityId}:`, err.message);
+            });
+        }
+        // Notify Yjs persistence. Awaited (not fire-and-forget) because docName
+        // reuse is a real scenario: delete X then create a new entity at X. If the
+        // delete callback fired async, it could race the new entity's snapshot and
+        // unlink it after creation. Failures are logged but don't throw — orphaned
+        // snapshot files are a leak, not a correctness issue.
+        if (this.mutationCallbacks?.onDelete) {
+            try {
+                await this.mutationCallbacks.onDelete(this.repoName, entityType, entityId);
+            }
+            catch (err) {
+                console.warn(`[graph] onDelete callback failed for ${entityType}/${entityId}:`, err);
+            }
+        }
     }
     /**
      * Rename an entity (change its ID). Preserves all data, content, and source_ref.
@@ -334,7 +733,8 @@ export class BaseGraphManager {
      */
     async rename(entityType, oldId, newId, commitMessage, user) {
         const existing = this.get(entityType, oldId);
-        const newPath = this.getEntityPath(entityType, newId);
+        // Rename keeps the entry in its current folder — only the filename changes.
+        const newPath = join(dirname(existing.path), `${newId}.md`);
         if (existsSync(newPath)) {
             throw new Error(`Entity ${entityType}/${newId} already exists`);
         }
@@ -348,27 +748,61 @@ export class BaseGraphManager {
         // Remove old file
         const { rmSync } = await import('fs');
         rmSync(existing.path, { force: true });
-        // Git: stage the rename
+        this.invalidateIndex();
         if (this.gitService) {
-            const { spawnSync } = await import('child_process');
-            spawnSync('git', ['add', newPath], { cwd: this.repoPath, stdio: 'ignore' });
-            spawnSync('git', ['add', existing.path], { cwd: this.repoPath, stdio: 'ignore' });
-            const transaction = this.gitService.createTransaction();
             const message = commitMessage || `Rename ${entityType}: ${oldId} → ${newId}`;
-            await transaction.commit(user ?? this.gitUser, message);
+            this.gitService.commitFiles([existing.path, newPath], message, user ?? this.gitUser);
+        }
+        // Update vector index — failure tracked on the service so a steady
+        // leak surfaces at /api/health rather than getting swallowed entirely.
+        if (this.vectorService) {
+            const v = this.vectorService;
+            v.beginOp();
+            v.delete(this.repoName, entityType, oldId)
+                .then(() => v.recordSuccess())
+                .catch(err => v.recordFailure('delete', `${entityType}/${oldId}`, err));
+        }
+        // Notify Yjs persistence to rename the snapshot file alongside. Awaited
+        // because rename oldId→newId followed by creating a new entity at oldId
+        // would otherwise let the async rename clobber the new oldId snapshot.
+        if (this.mutationCallbacks?.onRename) {
+            try {
+                await this.mutationCallbacks.onRename(this.repoName, entityType, oldId, newId);
+            }
+            catch (err) {
+                console.warn(`[graph] onRename callback failed for ${entityType}/${oldId}→${newId}:`, err);
+            }
         }
-        // Update vector index
-        this.vectorService?.delete(this.repoName, entityType, oldId).catch(() => { });
         return this.get(entityType, newId);
     }
     /**
-     * Change an entity's type. Moves the file from oldType/ to newType/ directory.
-     * Preserves all data and content. Updates entity_type in frontmatter.
+     * Change an entity's type. Updates frontmatter only — the file stays in
+     * its current folder. In the type-agnostic folder model, type is a
+     * frontmatter property independent of location. (Legacy behavior moved
+     * the file between {plural-type}/ dirs; that's no longer correct because
+     * those dirs are now ordinary user-visible folders, not type markers.)
+     *
+     * If the user wants the file to also move (e.g. out of a "meetings/"
+     * folder when changed to a note), they invoke move() separately.
      */
     async changeType(entityId, fromType, toType, commitMessage, user) {
+        // Asset entities are bound to a binary in the storage backend plus
+        // (for PDFs) a text sidecar. Changing TO asset would leave the entity
+        // without an asset_url / asset_kind / blob; changing FROM asset would
+        // orphan the binary and sidecar. Both directions must be a
+        // delete-and-recreate, not a type swap.
+        if (toType === 'asset' || fromType === 'asset') {
+            const direction = toType === 'asset' ? 'to' : 'from';
+            throw new Error(`Cannot change_type ${direction} 'asset' — assets are bound to a binary in storage. ` +
+                (toType === 'asset'
+                    ? 'Delete this entry and re-upload the file via the asset upload route to convert it to an asset.'
+                    : 'Delete this asset entry (which removes the binary) and create a fresh entry of the target type.'));
+        }
         const existing = this.get(fromType, entityId);
-        const newPath = this.getEntityPath(toType, entityId);
-        if (existsSync(newPath)) {
+        // (type, id) uniqueness check — if an entry with the new type already
+        // exists with this id, refuse rather than silently colliding in the index.
+        const collision = this.findEntityFile(toType, entityId);
+        if (collision && collision !== existing.path) {
             throw new Error(`Entity ${toType}/${entityId} already exists`);
         }
         // Read current content
@@ -408,40 +842,330 @@ export class BaseGraphManager {
                 }
             }
         }
-        // Ensure target directory exists and write new file
-        mkdirSync(dirname(newPath), { recursive: true });
-        this.markdownService.writeFile(newPath, doc);
-        // Remove old file
-        const { rmSync } = await import('fs');
-        rmSync(existing.path, { force: true });
-        // Git: stage the move and commit directly
+        // Write back to the same path — file stays in its current folder.
+        this.markdownService.writeFile(existing.path, doc);
+        this.invalidateIndex();
         if (this.gitService) {
-            const { spawnSync } = await import('child_process');
-            const gitUser = user ?? this.gitUser;
             const message = commitMessage || `Change type: ${entityId} (${fromType} → ${toType})`;
-            spawnSync('git', ['add', newPath], { cwd: this.repoPath, stdio: 'ignore' });
-            spawnSync('git', ['add', existing.path], { cwd: this.repoPath, stdio: 'ignore' });
-            spawnSync('git', [
-                '-c', `user.name=${gitUser.name}`,
-                '-c', `user.email=${gitUser.email}`,
-                'commit', '-m', message,
-            ], { cwd: this.repoPath, stdio: 'ignore' });
-        }
-        // Update vector index: remove old entry, re-index at new type
+            this.gitService.commitFiles([existing.path], message, user ?? this.gitUser);
+        }
+        // Update vector index: remove old entry, re-index at new type. Both ops
+        // tracked on the service so /api/health surfaces a leaking failure
+        // stream — previous .catch(() => {}) form was completely silent.
         const updated = this.get(toType, entityId);
-        this.vectorService?.delete(this.repoName, fromType, entityId).catch(() => { });
-        this.vectorService?.upsert(this.repoName, updated).catch(() => { });
+        if (this.vectorService) {
+            const v = this.vectorService;
+            v.beginOp();
+            v.delete(this.repoName, fromType, entityId)
+                .then(() => v.recordSuccess())
+                .catch(err => v.recordFailure('delete', `${fromType}/${entityId}`, err));
+            v.beginOp();
+            v.upsert(this.repoName, updated)
+                .then(() => v.recordSuccess())
+                .catch(err => v.recordFailure('upsert', `${toType}/${entityId}`, err));
+        }
+        // Notify Yjs persistence to move the snapshot from the old type's path to
+        // the new one (the docName changes, so the snapshot path changes). Awaited
+        // for the same reason as rename — preserves ordering when types are
+        // changed back and forth quickly.
+        if (this.mutationCallbacks?.onChangeType) {
+            try {
+                await this.mutationCallbacks.onChangeType(this.repoName, entityId, fromType, toType);
+            }
+            catch (err) {
+                console.warn(`[graph] onChangeType callback failed for ${entityId} (${fromType}→${toType}):`, err);
+            }
+        }
         return updated;
     }
     /**
-     * List entities of a given type
+     * Move an entry to a different folder within the same repo. The filename
+     * (and therefore the entity id) and type are unchanged. Auto-creates parent
+     * folders. Refuses if the target path already has an entry with this id.
+     */
+    async move(entityType, entityId, targetFolderPath, commitMessage, user) {
+        const existing = this.get(entityType, entityId);
+        const normalized = normalizeFolderPath(targetFolderPath);
+        const newPath = join(this.repoPath, normalized, `${entityId}.md`);
+        if (newPath === existing.path)
+            return existing; // no-op
+        if (existsSync(newPath)) {
+            throw new Error(`Path already occupied: ${normalized}/${entityId}.md`);
+        }
+        mkdirSync(dirname(newPath), { recursive: true });
+        const { renameSync } = await import('fs');
+        renameSync(existing.path, newPath);
+        // Folder lifecycle: source stays addressable via .gitkeep if it lost its
+        // last .md; destination drops any redundant .gitkeep now that it has one.
+        const filesToCommit = [existing.path, newPath];
+        const addedSourceMarker = this.ensureFolderMarker(dirname(existing.path));
+        if (addedSourceMarker)
+            filesToCommit.push(addedSourceMarker);
+        const removedDestMarker = this.removeFolderMarker(dirname(newPath));
+        if (removedDestMarker)
+            filesToCommit.push(removedDestMarker);
+        this.invalidateIndex();
+        if (this.gitService) {
+            const message = commitMessage || `Move ${entityType}: ${entityId} → ${normalized || '(root)'}`;
+            this.gitService.commitFiles(filesToCommit, message, user ?? this.gitUser);
+        }
+        return this.get(entityType, entityId);
+    }
+    /**
+     * Restore an entity to its content at a specific commit. Single-entity
+     * scope only — multi-entity rollback (e.g. "undo this commit's effects
+     * across all touched files") is a separate, more cautious flow that
+     * isn't built yet.
+     *
+     * Two paths through the method:
+     *   - **Overwrite**: the entity exists today at path `P`. Read content
+     *     from `git show <hash>:<P>` and write it back to `P`.
+     *   - **Recreate**: the entity is gone today. Walk the historical
+     *     commit's tree to find the .md file whose basename matches
+     *     `entityId` AND whose frontmatter `entity_type` matches
+     *     `entityType`. That path is the restore target. The walk only
+     *     fires when the entity is truly absent — overwrites stay cheap.
+     *
+     * Throws a `PathConflictError` if the recreate target path is now
+     * occupied by a DIFFERENT entity (different type+id) — recreating
+     * over it would silently overwrite unrelated work. Caller surfaces
+     * the conflict to the user; resolution is "move or delete the
+     * occupant first."
+     */
+    async restoreFile(entityType, entityId, commitHash, user) {
+        if (!this.gitService) {
+            throw new Error('Cannot restore — git service is not available for this repo');
+        }
+        const existingPath = this.findEntityFile(entityType, entityId);
+        let targetPath;
+        let action;
+        let content;
+        if (existingPath) {
+            // Overwrite path. Read content at the historical commit using the
+            // CURRENT path (git tracks files by content + path; if the entity
+            // was renamed or moved across the file's lifetime, --follow would
+            // be needed — out of scope for v1, the user can resolve by
+            // restoring at a commit where the path matched).
+            const relPath = relative(this.repoPath, existingPath);
+            content = this.gitService.getFileAtCommit(relPath, commitHash);
+            if (content === null) {
+                throw new Error(`File ${relPath} did not exist at commit ${commitHash}`);
+            }
+            targetPath = existingPath;
+            action = 'overwrite';
+        }
+        else {
+            // Recreate path. Walk the historical commit's tree to find the
+            // file whose basename matches entityId and frontmatter type
+            // matches entityType. This is the only place we do a full
+            // tree-walk — it only runs when the entity is gone today.
+            const found = this.findEntityInCommit(entityType, entityId, commitHash);
+            if (!found) {
+                throw new Error(`Entity ${entityType}/${entityId} not found at commit ${commitHash}`);
+            }
+            targetPath = join(this.repoPath, found.path);
+            content = found.content;
+            action = 'recreate';
+            // Path-conflict check: nothing else may occupy targetPath today.
+            if (existsSync(targetPath)) {
+                const occupant = this.identifyEntityAtPath(targetPath);
+                if (occupant && (occupant.entityType !== entityType || occupant.entityId !== entityId)) {
+                    throw new PathConflictError(found.path, occupant);
+                }
+            }
+        }
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, content);
+        // Folder lifecycle: if recreating dropped a file into a directory
+        // that had been emptied (and now carries .gitkeep), drop the marker
+        // so the directory exists via the .md file alone.
+        const filesToCommit = [targetPath];
+        if (action === 'recreate') {
+            const removedDestMarker = this.removeFolderMarker(dirname(targetPath));
+            if (removedDestMarker)
+                filesToCommit.push(removedDestMarker);
+        }
+        this.invalidateIndex();
+        const shortHash = commitHash.length > 8 ? commitHash.slice(0, 8) : commitHash;
+        const message = `Restore ${entityType}/${entityId} from ${shortHash}`;
+        this.gitService.commitFiles(filesToCommit, message, user ?? this.gitUser);
+        return { action, path: targetPath };
+    }
+    /**
+     * Walk a commit's tree looking for a .md file whose basename matches
+     * `entityId` AND whose frontmatter `entity_type` matches `entityType`.
+     * Returns repo-relative path + content when found, otherwise null.
+     * Used by `restoreFile` for the recreate-from-deletion case.
+     */
+    findEntityInCommit(entityType, entityId, commitHash) {
+        if (!this.gitService)
+            return null;
+        const filenameLower = `${entityId}.md`.toLowerCase();
+        const tree = this.gitService.listFilesAtCommit(commitHash);
+        for (const path of tree) {
+            if (!path.toLowerCase().endsWith(filenameLower))
+                continue;
+            // basename match — read content and check frontmatter type.
+            const content = this.gitService.getFileAtCommit(path, commitHash);
+            if (content === null)
+                continue;
+            try {
+                const doc = this.markdownService.parseContent(content);
+                const fmType = doc.frontmatter.entity_type;
+                const inferred = this.inferLegacyType(join(this.repoPath, path));
+                const type = fmType || inferred;
+                if (type === entityType)
+                    return { path, content };
+            }
+            catch {
+                // unparsable file — skip
+            }
+        }
+        return null;
+    }
+    /**
+     * Identify the entity (if any) currently occupying `absPath`. Returns
+     * null when the path holds something that isn't an entity (README, etc).
+     * Mirrors the inference rules used in `getFileIndex`.
+     */
+    identifyEntityAtPath(absPath) {
+        try {
+            const doc = this.markdownService.parseFile(absPath);
+            const fmType = doc.frontmatter.entity_type;
+            const inferred = this.inferLegacyType(absPath);
+            const type = fmType || inferred;
+            if (!type)
+                return null;
+            const id = absPath.split('/').pop().replace(/\.md$/, '');
+            return { entityType: type, entityId: id };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Enumerate the distinct entity types present in this repo. Used by
+     * /api/repos to let the sidebar render the Views list without a full
+     * entity fetch per folder.
+     *
+     * Derived from the file index (which reads frontmatter), so it works for
+     * entries in any folder — not just the legacy {plural-type}/ dirs.
+     */
+    listEntityTypes() {
+        if (!existsSync(this.repoPath))
+            return [];
+        const types = new Set();
+        for (const key of this.getFileIndex().keys()) {
+            const slash = key.indexOf('/');
+            if (slash > 0)
+                types.add(key.slice(0, slash));
+        }
+        return [...types].sort();
+    }
+    /**
+     * Folder lifecycle: a directory is treated as a first-class persistent
+     * object. It exists from the moment it's created (createFolder, the destination
+     * of a moved entry, etc.) until it's explicitly removed via a folder-level
+     * operation (deleteFolder, renameFolder, moveFolderToRepo). Entry-level
+     * operations (create, delete, move, transfer) never decide whether a folder
+     * lives or dies.
+     *
+     * `listFolders()` requires either a .md child or a .gitkeep marker for a
+     * directory to surface in the API, so the two helpers below are the single
+     * place that adds and removes the marker:
+     *
+     *  - `ensureFolderMarker` — call after an op that may have left `dir`
+     *    without .md children. Writes `.gitkeep` and returns its path so the
+     *    caller can stage it in the same commit.
+     *  - `removeFolderMarker` — call after an op that placed an .md into `dir`.
+     *    Drops a now-redundant `.gitkeep` so the repo stays tidy.
+     *
+     * Both no-op for the repo root (always implicit) and for paths that don't
+     * exist. Both return `null` when nothing changed.
+     */
+    ensureFolderMarker(dir) {
+        if (dir === this.repoPath)
+            return null;
+        if (!existsSync(dir))
+            return null;
+        const entries = readdirSync(dir);
+        const hasMd = entries.some(e => e.endsWith('.md') && !e.startsWith('.'));
+        if (hasMd)
+            return null;
+        const keepPath = join(dir, '.gitkeep');
+        if (existsSync(keepPath))
+            return null;
+        writeFileSync(keepPath, '');
+        return keepPath;
+    }
+    removeFolderMarker(dir) {
+        if (dir === this.repoPath)
+            return null;
+        if (!existsSync(dir))
+            return null;
+        const keepPath = join(dir, '.gitkeep');
+        if (!existsSync(keepPath))
+            return null;
+        const entries = readdirSync(dir);
+        const hasMd = entries.some(e => e.endsWith('.md') && !e.startsWith('.'));
+        if (!hasMd)
+            return null; // marker still load-bearing
+        rmSync(keepPath, { force: true });
+        return keepPath;
+    }
+    /**
+     * Walk up from `dir`, removing each directory that became empty after a
+     * folder-level removal (deleteFolder, renameFolder, moveFolderToRepo).
+     * Stops at the repo root. Silently no-ops if a directory is missing,
+     * non-empty, or can't be removed.
+     *
+     * NOT called by entry-level operations (create/delete/move/transfer) —
+     * they preserve folder structure regardless of whether they emptied a
+     * directory. Use `ensureFolderMarker` instead for those paths.
+     */
+    async pruneEmptyAncestors(dir) {
+        const { rmSync } = await import('fs');
+        const repoRoot = this.repoPath.replace(/\/+$/, '');
+        let current = dir;
+        while (current.startsWith(repoRoot + '/') && current !== repoRoot) {
+            if (!existsSync(current)) {
+                current = dirname(current);
+                continue;
+            }
+            let entries;
+            try {
+                entries = readdirSync(current);
+            }
+            catch {
+                return;
+            }
+            // Treat .gitkeep as "this folder is intentionally kept" — don't auto-prune.
+            if (entries.length > 0)
+                return;
+            try {
+                rmSync(current, { recursive: true, force: true });
+            }
+            catch {
+                return;
+            }
+            current = dirname(current);
+        }
+    }
+    /**
+     * List entities of a given type (or all types if not specified).
+     *
+     * Walks the entire repo tree so entries in nested folders are discovered.
+     * The type filter is applied against frontmatter `entity_type`; legacy
+     * entries without explicit frontmatter type fall back to the depth-1
+     * plural-type directory name (so `meetings/foo.md` still resolves as a
+     * meeting). Files with no inferable type (README.md, CONTRIBUTING.md, etc.)
+     * are skipped.
      */
     list(entityType, limit) {
         if (!existsSync(this.repoPath))
             return [];
         const results = [];
-        // Lenient validation for list(): try strict schema first, fall back to
-        // EntityBaseSchema, then raw data so app-defined types are still discovered.
+        const seen = new Set(); // "type/id" — dedup if a file ends up indexed twice
         const validateLenient = (type, data) => {
             try {
                 return this.validateEntity(type, data);
@@ -455,97 +1179,36 @@ export class BaseGraphManager {
                 }
             }
         };
-        const seenIds = new Set();
-        // Process a flat .md file as an entity
-        const tryAddFile = (filePath, id, inferredType) => {
-            if (seenIds.has(id))
-                return;
-            try {
-                const doc = this.markdownService.parseFile(filePath);
-                const fmType = doc.frontmatter.entity_type;
-                const resolvedType = entityType ?? fmType ?? inferredType ?? this.repoName;
-                if (entityType && fmType && fmType !== entityType)
-                    return;
-                const validatedData = validateLenient(resolvedType, doc.frontmatter);
-                seenIds.add(id);
-                results.push({
-                    id,
-                    path: filePath,
-                    entityType: resolvedType,
-                    data: validatedData,
-                    document: doc,
-                });
-            }
-            catch { /* skip invalid */ }
-        };
-        // Scan plural type subfolders for flat .md files
-        for (const entry of readdirSync(this.repoPath)) {
-            if (entry.startsWith('.'))
-                continue;
-            const fullPath = join(this.repoPath, entry);
+        this.walkMarkdownFiles((filePath) => {
+            let doc;
             try {
-                if (!statSync(fullPath).isDirectory())
-                    continue;
+                doc = this.markdownService.parseFile(filePath);
             }
             catch {
-                continue;
-            }
-            const singularType = PLURAL_TO_SINGULAR[entry];
-            if (!singularType)
-                continue; // skip unknown directories
-            try {
-                for (const file of readdirSync(fullPath)) {
-                    if (file.startsWith('.') || !file.endsWith('.md'))
-                        continue;
-                    const filePath = join(fullPath, file);
-                    try {
-                        if (!statSync(filePath).isFile())
-                            continue;
-                    }
-                    catch {
-                        continue;
-                    }
-                    const id = file.replace(/\.md$/, '');
-                    tryAddFile(filePath, id, singularType);
-                }
-            }
-            catch { /* skip unreadable */ }
-        }
-        // Also discover flat .md files at repo root (README, etc.)
-        for (const entry of readdirSync(this.repoPath)) {
-            if (entry.startsWith('.'))
-                continue;
-            if (!entry.endsWith('.md'))
-                continue;
-            const fullPath = join(this.repoPath, entry);
-            try {
-                if (!statSync(fullPath).isFile())
-                    continue;
-            }
-            catch {
-                continue;
-            }
-            const id = entry.replace(/\.md$/, '');
-            if (seenIds.has(id))
-                continue;
-            try {
-                const doc = this.markdownService.parseFile(fullPath);
-                const fmType = doc.frontmatter.entity_type;
-                const resolvedType = entityType ?? fmType ?? this.repoName;
-                if (entityType && fmType && fmType !== entityType)
-                    continue;
-                const validatedData = validateLenient(resolvedType, doc.frontmatter);
-                seenIds.add(id);
-                results.push({
-                    id,
-                    path: fullPath,
-                    entityType: resolvedType,
-                    data: validatedData,
-                    document: doc,
-                });
+                return;
             }
-            catch { /* skip invalid */ }
-        }
+            const fmType = doc.frontmatter.entity_type;
+            const inferred = this.inferLegacyType(filePath);
+            const resolvedType = (fmType ?? inferred);
+            if (!resolvedType)
+                return; // README, etc.
+            if (entityType && resolvedType !== entityType)
+                return;
+            const id = filePath.split('/').pop().replace(/\.md$/, '');
+            const key = `${resolvedType}/${id}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            const validatedData = validateLenient(resolvedType, doc.frontmatter);
+            results.push({
+                id,
+                path: filePath,
+                folder_path: folderPathFromFile(filePath, this.repoPath),
+                entityType: resolvedType,
+                data: validatedData,
+                document: doc,
+            });
+        });
         if (limit && limit > 0)
             return results.slice(0, limit);
         return results;
@@ -709,31 +1372,43 @@ export class BaseGraphManager {
         }
         return entities;
     }
+    /**
+     * Resolve a markdown file (anywhere under the repo) to its (type, id),
+     * tolerating both legacy {plural-type}/{id}.md and nested-folder layouts.
+     * Returns undefined for files without a recognizable entity type.
+     */
+    resolveFileToEntity(absPath) {
+        const filename = absPath.split('/').pop();
+        if (!filename || !filename.endsWith('.md'))
+            return undefined;
+        const id = filename.replace(/\.md$/, '');
+        let fmType;
+        try {
+            fmType = this.markdownService.parseFile(absPath).frontmatter.entity_type;
+        }
+        catch { /* unparsable — fall back to inference */ }
+        const type = fmType || this.inferLegacyType(absPath);
+        if (!type)
+            return undefined;
+        return { type: type, id };
+    }
     /**
      * Get entities related to a given entity (via wikilinks)
      */
     getRelated(entityType, entityId) {
         const entity = this.get(entityType, entityId);
         const related = [];
-        // Find all wikilinked entities
         for (const link of entity.document.wikilinks) {
-            // Try to find the linked entity in all type subfolders
             const found = this.markdownService.findEntity(link, [this.repoPath]);
-            if (found) {
-                const relPath = found.replace(this.repoPath + '/', '');
-                const parts = relPath.split('/');
-                // New layout: {plural-type}/{entityId}.md
-                if (parts.length === 2 && parts[1].endsWith('.md')) {
-                    const linkedId = parts[1].replace(/\.md$/, '');
-                    try {
-                        const doc = this.markdownService.parseFile(found);
-                        const linkedType = doc.frontmatter.entity_type ?? PLURAL_TO_SINGULAR[parts[0]] ?? this.repoName;
-                        const linkedEntity = this.get(linkedType, linkedId);
-                        related.push(linkedEntity);
-                    }
-                    catch { /* skip invalid */ }
-                }
+            if (!found)
+                continue;
+            const resolved = this.resolveFileToEntity(found);
+            if (!resolved)
+                continue;
+            try {
+                related.push(this.get(resolved.type, resolved.id));
             }
+            catch { /* skip invalid */ }
         }
         return related;
     }
@@ -744,19 +1419,13 @@ export class BaseGraphManager {
         const backlinks = this.markdownService.findBacklinks(entityId, [this.repoPath]);
         const results = [];
         for (const { file } of backlinks) {
-            const relPath = file.replace(this.repoPath + '/', '');
-            const parts = relPath.split('/');
-            // New layout: {plural-type}/{entityId}.md
-            if (parts.length === 2 && parts[1].endsWith('.md')) {
-                const linkedId = parts[1].replace(/\.md$/, '');
-                try {
-                    const doc = this.markdownService.parseFile(file);
-                    const linkedType = doc.frontmatter.entity_type ?? PLURAL_TO_SINGULAR[parts[0]] ?? this.repoName;
-                    const linkedEntity = this.get(linkedType, linkedId);
-                    results.push(linkedEntity);
-                }
-                catch { /* skip invalid */ }
+            const resolved = this.resolveFileToEntity(file);
+            if (!resolved)
+                continue;
+            try {
+                results.push(this.get(resolved.type, resolved.id));
             }
+            catch { /* skip invalid */ }
         }
         return results;
     }
@@ -771,26 +1440,20 @@ export class BaseGraphManager {
      * Refactor a wikilink (rename entity and update all references)
      */
     async refactorWikilink(oldId, newId, commitMessage) {
-        // Find all files that reference the old entity ID
         const backlinks = this.markdownService.findBacklinks(oldId, [this.repoPath]);
-        // Update each file
         if (this.gitService) {
             const transaction = this.gitService.createTransaction();
             for (const { file } of backlinks) {
                 this.markdownService.updateWikilinks(file, oldId, newId);
-                const relPath = file.replace(this.repoPath + '/', '');
-                const parts = relPath.split('/');
-                // New layout: {plural-type}/{entityId}.md
-                if (parts.length === 2 && parts[1].endsWith('.md')) {
-                    const entityId = parts[1].replace(/\.md$/, '');
-                    const doc = this.markdownService.parseFile(file);
-                    transaction.add({
-                        operation: 'update',
-                        entityType: doc.frontmatter.entity_type ?? PLURAL_TO_SINGULAR[parts[0]] ?? parts[0],
-                        entityId,
-                        filePath: file,
-                    });
-                }
+                const resolved = this.resolveFileToEntity(file);
+                if (!resolved)
+                    continue;
+                transaction.add({
+                    operation: 'update',
+                    entityType: resolved.type,
+                    entityId: resolved.id,
+                    filePath: file,
+                });
             }
             const message = commitMessage || `Refactor wikilink: ${oldId} → ${newId}`;
             await transaction.commit(this.gitUser, message);
@@ -802,6 +1465,491 @@ export class BaseGraphManager {
         }
         return { updated: backlinks.length };
     }
+    // ────────────────────────────────────────────────────────────────────────────
+    // Folder CRUD — operate on directories within the repo, not on entries.
+    // Sharing remains a repo-level concept; folders carry no permissions or
+    // metadata of their own. Empty folders are kept around via .gitkeep so git
+    // tracks them.
+    // ────────────────────────────────────────────────────────────────────────────
+    /**
+     * List every non-empty folder in this repo, plus folders explicitly kept
+     * via .gitkeep. Returns repo-relative POSIX paths, sorted, deduplicated.
+     * The repo root ("") is intentionally omitted — it's implicit.
+     */
+    listFolders() {
+        if (!existsSync(this.repoPath))
+            return [];
+        const folders = new Set();
+        const sidecarByPath = new Map();
+        const stack = [this.repoPath];
+        const repoRoot = this.repoPath.replace(/\/+$/, '');
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            let entries;
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                continue;
+            }
+            let kept = false;
+            let hasSidecar = false;
+            for (const entry of entries) {
+                if (entry === '.gitkeep')
+                    kept = true;
+                if (entry === FOLDER_SIDECAR)
+                    hasSidecar = true;
+                if (entry.startsWith('.'))
+                    continue;
+                if (WALK_IGNORE.has(entry))
+                    continue;
+                const full = join(dir, entry);
+                let st;
+                try {
+                    st = statSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (st.isDirectory())
+                    stack.push(full);
+            }
+            if (dir === repoRoot)
+                continue;
+            // Include this directory if it has any .md files OR a .gitkeep marker
+            // OR a sidecar (which carries display metadata even for empty folders).
+            const hasMarkdown = entries.some(e => e.endsWith('.md') && !e.startsWith('.'));
+            if (hasMarkdown || kept || hasSidecar) {
+                const folderPath = folderPathFromFile(join(dir, 'placeholder.md'), this.repoPath);
+                folders.add(folderPath);
+                if (hasSidecar) {
+                    const display = readFolderSidecar(dir);
+                    if (display !== null)
+                        sidecarByPath.set(folderPath, display);
+                }
+            }
+        }
+        return [...folders]
+            .filter(p => p.length > 0)
+            .sort()
+            .map(p => {
+            const entry = { path: p, name: p.slice(p.lastIndexOf('/') + 1) };
+            const display = sidecarByPath.get(p);
+            if (display)
+                entry.display_name = display;
+            return entry;
+        });
+    }
+    /**
+     * Read the display_name override for a single folder, or null if no sidecar
+     * exists / is unreadable. Used by mutation paths that need the current
+     * override before deciding whether to rewrite it.
+     */
+    readFolderDisplayName(folderPath) {
+        const normalized = validateFolderPath(folderPath);
+        if (!normalized)
+            return null;
+        return readFolderSidecar(join(this.repoPath, normalized));
+    }
+    /**
+     * Write or remove the per-folder display_name sidecar. Pass `null` /
+     * empty-string to remove (returns to slug fallback). Returns the absolute
+     * path of the sidecar (for git staging) when one was written or removed,
+     * or null when no change was needed (idempotent).
+     *
+     * Caller is responsible for committing — the helper only touches the
+     * filesystem. Folder must already exist; this never creates one.
+     */
+    writeFolderDisplayName(folderPath, displayName) {
+        const normalized = validateFolderPath(folderPath);
+        if (!normalized) {
+            throw new InvalidFolderPathError('Folder path cannot be empty');
+        }
+        const abs = join(this.repoPath, normalized);
+        if (!existsSync(abs)) {
+            throw new Error(`Folder not found: ${normalized}`);
+        }
+        const trimmed = displayName?.trim();
+        if (!trimmed) {
+            const removed = removeFolderSidecar(abs);
+            if (!removed)
+                return null;
+            this.invalidateIndex();
+            return removed;
+        }
+        const existing = readFolderSidecar(abs);
+        if (existing === trimmed)
+            return null;
+        const sidecarPath = writeFolderSidecar(abs, trimmed);
+        this.invalidateIndex();
+        return sidecarPath;
+    }
+    /**
+     * Bulk-write display_name sidecars for many folders at once. Used by the
+     * import path to record original-casing overrides for every nested
+     * directory it slugified. First-writer-wins: existing sidecars are NOT
+     * overwritten, so a second import doesn't clobber a user's manual rename.
+     *
+     * Returns the list of sidecar paths actually written (for git staging).
+     * Skipped paths (folder missing, slug already matches display, sidecar
+     * already exists) are quietly omitted.
+     */
+    recordFolderDisplays(entries) {
+        const written = [];
+        for (const entry of entries) {
+            const normalized = validateFolderPath(entry.path);
+            if (!normalized)
+                continue;
+            const abs = join(this.repoPath, normalized);
+            if (!existsSync(abs))
+                continue;
+            const sidecarPath = folderSidecarPath(abs);
+            if (existsSync(sidecarPath))
+                continue; // first-writer-wins
+            const display = entry.display_name.trim();
+            if (!display)
+                continue;
+            written.push(writeFolderSidecar(abs, display));
+        }
+        if (written.length > 0)
+            this.invalidateIndex();
+        return written;
+    }
+    /**
+     * Create a folder at the given path (mkdir -p semantics) and drop a
+     * .gitkeep so git tracks it even when empty. Validates the path. No-op if
+     * the folder already exists; .gitkeep is added if missing.
+     */
+    async createFolder(folderPath, commitMessage, user, options) {
+        const normalized = validateFolderPath(folderPath);
+        if (!normalized) {
+            throw new InvalidFolderPathError('Folder path cannot be empty (use the repo root directly)');
+        }
+        const abs = join(this.repoPath, normalized);
+        mkdirSync(abs, { recursive: true });
+        const keep = join(abs, '.gitkeep');
+        if (!existsSync(keep)) {
+            writeFileSync(keep, '');
+        }
+        // Sidecar is written here (not after the commit) so it joins the same
+        // commit as .gitkeep — folder creation is atomic from git's perspective.
+        const sidecarPath = options?.displayName
+            ? this.writeFolderDisplayName(normalized, options.displayName)
+            : null;
+        this.invalidateIndex();
+        if (this.gitService) {
+            const message = commitMessage || `Create folder: ${normalized}`;
+            const files = sidecarPath ? [keep, sidecarPath] : [keep];
+            this.gitService.commitFiles(files, message, user ?? this.gitUser);
+        }
+    }
+    /**
+     * Rename / move a folder within the repo. Moves the entire subtree
+     * atomically via filesystem rename. Refuses if the target path is already
+     * occupied.
+     */
+    async renameFolder(fromPath, toPath, commitMessage, user, options) {
+        const fromNormalized = validateFolderPath(fromPath);
+        const toNormalized = validateFolderPath(toPath);
+        if (!fromNormalized)
+            throw new InvalidFolderPathError('Source folder path required');
+        if (!toNormalized)
+            throw new InvalidFolderPathError('Target folder path required');
+        // Display-only update: same path, just rewrite the sidecar.
+        if (fromNormalized === toNormalized) {
+            if (options?.displayName === undefined)
+                return;
+            const sidecarPath = this.writeFolderDisplayName(fromNormalized, options.displayName);
+            if (sidecarPath && this.gitService) {
+                const message = commitMessage || `Update folder display name: ${fromNormalized}`;
+                this.gitService.commitFiles([sidecarPath], message, user ?? this.gitUser);
+            }
+            return;
+        }
+        const fromAbs = join(this.repoPath, fromNormalized);
+        const toAbs = join(this.repoPath, toNormalized);
+        if (!existsSync(fromAbs)) {
+            throw new Error(`Folder not found: ${fromNormalized}`);
+        }
+        if (existsSync(toAbs)) {
+            throw new Error(`Target folder already exists: ${toNormalized}`);
+        }
+        mkdirSync(dirname(toAbs), { recursive: true });
+        const { renameSync } = await import('fs');
+        renameSync(fromAbs, toAbs);
+        // The sidecar moved with the folder via FS rename. Update it now if the
+        // caller passed a new display name (or `null` to clear). Idempotent — no
+        // sidecar write happens when display matches the existing override.
+        let sidecarPath = null;
+        if (options?.displayName !== undefined) {
+            sidecarPath = this.writeFolderDisplayName(toNormalized, options.displayName);
+        }
+        this.invalidateIndex();
+        if (this.gitService) {
+            const message = commitMessage || `Rename folder: ${fromNormalized} → ${toNormalized}`;
+            const files = sidecarPath ? [fromAbs, toAbs, sidecarPath] : [fromAbs, toAbs];
+            this.gitService.commitFiles(files, message, user ?? this.gitUser);
+        }
+        await this.pruneEmptyAncestors(dirname(fromAbs));
+    }
+    /**
+     * Move a folder (and its full subtree) into a different repo at `targetFolderPath`.
+     *
+     * The naive way to do this is to iterate the source's entries and call
+     * `transfer` per entry — that's what the web UI used to do, and it costs
+     * 2 git commits per entry (1600 commits for 800 files), each blocking the
+     * Node event loop via `execSync`. This method performs the move as a
+     * single FS-level rename + one commit per repo, regardless of how many
+     * files are inside.
+     *
+     * Returns the count of entries + subfolders moved so the caller can
+     * surface progress.
+     */
+    async moveFolderToRepo(sourceFolderPath, target, targetFolderPath, options) {
+        const sourceNormalized = validateFolderPath(sourceFolderPath);
+        if (!sourceNormalized) {
+            throw new InvalidFolderPathError('Source folder path required');
+        }
+        const targetNormalized = targetFolderPath ? validateFolderPath(targetFolderPath) : '';
+        if (targetFolderPath && !targetNormalized) {
+            throw new InvalidFolderPathError('Invalid target folder path');
+        }
+        if (target === this && sourceNormalized === targetNormalized) {
+            return { entriesDeleted: 0, subfoldersDeleted: 0 };
+        }
+        const sourceAbs = join(this.repoPath, sourceNormalized);
+        if (!existsSync(sourceAbs)) {
+            throw new Error(`Source folder not found: ${sourceNormalized}`);
+        }
+        const targetAbs = targetNormalized
+            ? join(target.repoPath, targetNormalized)
+            : target.repoPath;
+        // Refuse if target already has visible content — caller must move into
+        // an empty / nonexistent folder. (Hidden files like .studiograph are OK.)
+        if (existsSync(targetAbs)) {
+            const visible = readdirSync(targetAbs).filter(n => !n.startsWith('.'));
+            if (visible.length > 0) {
+                throw new Error(`Target folder is not empty: ${targetNormalized || '/'}`);
+            }
+        }
+        const stats = this.countFolderContents(sourceAbs);
+        // Atomic FS rename if possible. Falls back to copy + delete if the two
+        // repos sit on different filesystems (rare, but possible on Docker
+        // bind mounts).
+        const { renameSync, cpSync, rmSync } = await import('fs');
+        mkdirSync(dirname(targetAbs), { recursive: true });
+        if (existsSync(targetAbs)) {
+            // Empty pre-existing dir — drop it so renameSync can take its place.
+            rmSync(targetAbs, { recursive: true, force: true });
+        }
+        try {
+            renameSync(sourceAbs, targetAbs);
+        }
+        catch (err) {
+            if (err?.code === 'EXDEV') {
+                cpSync(sourceAbs, targetAbs, { recursive: true });
+                rmSync(sourceAbs, { recursive: true, force: true });
+            }
+            else {
+                throw err;
+            }
+        }
+        this.invalidateIndex();
+        target.invalidateIndex();
+        const user = options?.user ?? this.gitUser;
+        const sourceMessage = options?.commitMessage
+            ?? `Move folder ${sourceNormalized} → ${target.repoName}:${targetNormalized || '/'}`;
+        const targetMessage = options?.commitMessage
+            ?? `Move folder from ${this.repoName}:${sourceNormalized} → ${targetNormalized || '/'}`;
+        if (this.gitService) {
+            this.gitService.commitFiles([sourceAbs], sourceMessage, user);
+        }
+        if (target.gitService) {
+            target.gitService.commitFiles([targetAbs], targetMessage, user);
+        }
+        await this.pruneEmptyAncestors(dirname(sourceAbs));
+        return stats;
+    }
+    /**
+     * Move a batch of entries (potentially across many source folders) into a
+     * single target folder, optionally in a different repo. The web UI's
+     * multi-select bulk move used to call /move or /transfer per entry — that
+     * was 1-2 sync git commits per entry, blocking the event loop on each one.
+     * This collapses the operation to a single FS rename per file plus one
+     * commit on each repo touched.
+     */
+    async moveEntitiesToRepo(entries, target, targetFolderPath, options) {
+        if (entries.length === 0)
+            return { moved: 0 };
+        const targetNormalized = targetFolderPath ? validateFolderPath(targetFolderPath) : '';
+        if (targetFolderPath && !targetNormalized) {
+            throw new InvalidFolderPathError('Invalid target folder path');
+        }
+        const targetDir = targetNormalized
+            ? join(target.repoPath, targetNormalized)
+            : target.repoPath;
+        // Resolve all source paths up front and validate target conflicts before
+        // any FS work — partial moves on conflict would leave the user with a
+        // confusing half-state.
+        const moves = [];
+        for (const entry of entries) {
+            const existing = this.get(entry.entityType, entry.entityId);
+            const dst = join(targetDir, `${entry.entityId}.md`);
+            if (existing.path === dst)
+                continue; // already there — no-op
+            if (existsSync(dst)) {
+                throw new Error(`Path already occupied: ${target.repoName}:${targetNormalized ? targetNormalized + '/' : ''}${entry.entityId}.md`);
+            }
+            moves.push({ src: existing.path, dst });
+        }
+        if (moves.length === 0)
+            return { moved: 0 };
+        const { renameSync, cpSync } = await import('fs');
+        mkdirSync(targetDir, { recursive: true });
+        for (const m of moves) {
+            try {
+                renameSync(m.src, m.dst);
+            }
+            catch (err) {
+                if (err?.code === 'EXDEV') {
+                    cpSync(m.src, m.dst);
+                    rmSync(m.src);
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        // Folder lifecycle: ensure markers in every source dir we may have
+        // emptied, drop the marker in the (single) target dir now that it has
+        // .md children. Helpers no-op for the repo root and for paths that
+        // are already in the right state, so calling them per dir is cheap.
+        const sourceMarkers = [];
+        const visitedSourceDirs = new Set();
+        for (const m of moves) {
+            const sourceDir = dirname(m.src);
+            if (visitedSourceDirs.has(sourceDir))
+                continue;
+            visitedSourceDirs.add(sourceDir);
+            const added = this.ensureFolderMarker(sourceDir);
+            if (added)
+                sourceMarkers.push(added);
+        }
+        const removedTargetMarker = target.removeFolderMarker(targetDir);
+        this.invalidateIndex();
+        if (target !== this)
+            target.invalidateIndex();
+        const user = options?.user ?? this.gitUser;
+        const where = target === this
+            ? (targetNormalized || '(root)')
+            : `${target.repoName}:${targetNormalized || '(root)'}`;
+        const sourceMessage = options?.commitMessage ?? `Move ${moves.length} entries → ${where}`;
+        if (this.gitService) {
+            const sourcePaths = [...moves.map(m => m.src), ...sourceMarkers];
+            const dstStaging = target === this
+                ? [...moves.map(m => m.dst), ...(removedTargetMarker ? [removedTargetMarker] : [])]
+                : [];
+            this.gitService.commitFiles([...sourcePaths, ...dstStaging], sourceMessage, user);
+        }
+        if (target !== this && target.gitService) {
+            const targetMessage = options?.commitMessage
+                ?? `Receive ${moves.length} entries from ${this.repoName}`;
+            const targetPaths = [...moves.map(m => m.dst), ...(removedTargetMarker ? [removedTargetMarker] : [])];
+            target.gitService.commitFiles(targetPaths, targetMessage, user);
+        }
+        return { moved: moves.length };
+    }
+    /**
+     * Delete a folder. Refuses non-empty folders unless `recursive: true`.
+     * Returns the count of entries + subfolders removed (for blast-radius UI).
+     */
+    async deleteFolder(folderPath, options) {
+        const normalized = validateFolderPath(folderPath);
+        if (!normalized) {
+            throw new InvalidFolderPathError('Cannot delete the repo root via deleteFolder');
+        }
+        const abs = join(this.repoPath, normalized);
+        if (!existsSync(abs)) {
+            throw new Error(`Folder not found: ${normalized}`);
+        }
+        const stats = this.countFolderContents(abs);
+        if (!options?.recursive && (stats.entriesDeleted > 0 || stats.subfoldersDeleted > 0)) {
+            const err = new Error(`Folder is not empty: ${normalized} (${stats.entriesDeleted} entries, ${stats.subfoldersDeleted} subfolders). Pass recursive: true to delete contents.`);
+            err.code = 'FOLDER_NOT_EMPTY';
+            err.blastRadius = stats;
+            throw err;
+        }
+        const { rmSync } = await import('fs');
+        rmSync(abs, { recursive: true, force: true });
+        this.invalidateIndex();
+        if (this.gitService) {
+            const message = options?.commitMessage || `Delete folder: ${normalized}`;
+            this.gitService.commitFiles([abs], message, options?.user ?? this.gitUser);
+        }
+        await this.pruneEmptyAncestors(dirname(abs));
+        return stats;
+    }
+    /**
+     * Count the entries (.md files with entity_type) and subfolders inside an
+     * absolute directory, recursively. Used to surface blast radius in the
+     * delete-folder approval UI.
+     */
+    countFolderContents(absDir) {
+        let entriesDeleted = 0;
+        const subfolders = new Set();
+        const stack = [absDir];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            let entries;
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.startsWith('.'))
+                    continue;
+                if (WALK_IGNORE.has(entry))
+                    continue;
+                const full = join(dir, entry);
+                let st;
+                try {
+                    st = statSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (st.isDirectory()) {
+                    subfolders.add(full);
+                    stack.push(full);
+                }
+                else if (st.isFile() && entry.endsWith('.md')) {
+                    entriesDeleted += 1;
+                }
+            }
+        }
+        return { entriesDeleted, subfoldersDeleted: subfolders.size };
+    }
+    /**
+     * Return the storage backend the graph is bound to, or `undefined` if
+     * no asset service is configured. Used by routes that need to branch
+     * between local-stream and R2-redirect behavior.
+     */
+    getAssetStorage() {
+        return this.assetService?.getStorage();
+    }
+    /**
+     * Mint a short-lived pre-signed URL for an asset. Only supported by
+     * remote backends (R2); the local backend throws. `method` selects
+     * the verb the URL is signed against — HEAD callers need a HEAD URL.
+     */
+    async getAssetSignedUrl(entityType, entityId, filename, keyPrefix, expiresIn, method = 'GET') {
+        if (!this.assetService) {
+            throw new Error('Asset service is not configured for this graph');
+        }
+        return await this.assetService.getSignedUrl(entityType, entityId, filename, keyPrefix, expiresIn, method);
+    }
     /**
      * Upload asset for an entity
      */
@@ -821,84 +1969,63 @@ export class BaseGraphManager {
         return await this.assetService.list(entityType, entityId, keyPrefix);
     }
     /**
-     * Delete an asset
+     * List every asset in the backend in one round-trip, tagged with
+     * (entityType, entityId) origin. Workspace-wide since the asset backend
+     * is shared across repos — callers filter by repo via {@link listEntityIds}.
      */
-    async deleteAsset(entityType, entityId, filename, keyPrefix) {
+    async listAllAssets() {
         if (!this.assetService) {
             throw new Error('Asset service is not configured for this graph');
         }
-        return await this.assetService.delete(entityType, entityId, filename, keyPrefix);
+        return await this.assetService.listAll();
     }
     /**
-     * Delete all assets for an entity (when entity is deleted)
+     * Enumerate (type, id) pairs in this repo. Used by endpoints (like
+     * /api/repos/:repo/assets) that need to answer "does entity X belong to
+     * this repo?".
+     *
+     * Backed by the file index, which reads frontmatter — so entries in
+     * nested folders are included alongside legacy {plural-type}/ entries.
      */
-    async deleteAllAssets(entityType, entityId, keyPrefix) {
-        if (!this.assetService) {
-            throw new Error('Asset service is not configured for this graph');
+    listEntityIds() {
+        if (!existsSync(this.repoPath))
+            return [];
+        const results = [];
+        for (const key of this.getFileIndex().keys()) {
+            const slash = key.indexOf('/');
+            if (slash <= 0)
+                continue;
+            results.push({ entityType: key.slice(0, slash), id: key.slice(slash + 1) });
         }
-        return await this.assetService.deleteAll(entityType, entityId, keyPrefix);
+        return results;
     }
     /**
-     * Get dataset rows, optionally filtered
+     * Resolve the absolute on-disk markdown path for an entity. Goes through
+     * the file index so it works for both the flat repo-root layout and
+     * arbitrary nested folders. Use this anywhere callers need a path —
+     * never reconstruct one from `${plural-type}/${id}.md`, which assumes
+     * the legacy typed-folder layout and silently misses everything else.
      */
-    getDatasetRows(entityId, filter) {
-        const entity = this.get('dataset', entityId);
-        if (entity.data.entity_type !== 'dataset') {
-            throw new Error(`Entity ${entityId} is not a dataset`);
-        }
-        const schema = entity.data.schema;
-        const rows = this.csvService.parseRows(entity.document.content, schema);
-        if (filter && Object.keys(filter).length > 0) {
-            return this.csvService.filterRows(rows, filter);
-        }
-        return rows;
+    getEntityFilePath(entityType, entityId) {
+        return this.findEntityFile(entityType, entityId);
     }
     /**
-     * Append rows to a dataset entity
+     * Delete an asset
      */
-    async appendDatasetRows(entityId, newRows, commitMessage) {
-        const entity = this.get('dataset', entityId);
-        if (entity.data.entity_type !== 'dataset') {
-            throw new Error(`Entity ${entityId} is not a dataset`);
+    async deleteAsset(entityType, entityId, filename, keyPrefix) {
+        if (!this.assetService) {
+            throw new Error('Asset service is not configured for this graph');
         }
-        const schema = entity.data.schema;
-        // Validate new rows against schema
-        const validatedRows = newRows.map(row => {
-            const stringRow = {};
-            for (const [k, v] of Object.entries(row)) {
-                stringRow[k] = v !== null && v !== undefined ? String(v) : '';
-            }
-            return this.csvService.validateRow(stringRow, schema);
-        });
-        // Parse existing rows and append
-        const existingRows = this.csvService.parseRows(entity.document.content, schema);
-        const allRows = [...existingRows, ...validatedRows];
-        // Stringify back to CSV
-        const newContent = this.csvService.stringifyRows(allRows, schema);
-        // Update the entity file (update content, bump updated_at)
-        const entityPath = this.getEntityPath('dataset', entityId);
-        const updatedData = {
-            ...entity.data,
-            updated_at: new Date().toISOString(),
-            updated_by: this.gitUser.id,
-        };
-        this.markdownService.writeFile(entityPath, {
-            frontmatter: updatedData,
-            content: newContent,
-            wikilinks: this.markdownService.extractWikilinks(newContent, updatedData),
-        });
-        if (this.gitService) {
-            const transaction = this.gitService.createTransaction();
-            transaction.add({
-                operation: 'update',
-                entityType: 'dataset',
-                entityId,
-                filePath: entityPath,
-            });
-            const message = commitMessage || `Append ${validatedRows.length} row(s) to dataset: ${entityId}`;
-            await transaction.commit(this.gitUser, message);
+        return await this.assetService.delete(entityType, entityId, filename, keyPrefix);
+    }
+    /**
+     * Delete all assets for an entity (when entity is deleted)
+     */
+    async deleteAllAssets(entityType, entityId, keyPrefix) {
+        if (!this.assetService) {
+            throw new Error('Asset service is not configured for this graph');
         }
-        return this.get('dataset', entityId);
+        return await this.assetService.deleteAll(entityType, entityId, keyPrefix);
     }
     /**
      * Get repository status