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

package/dist/core/graph.js

@@ -4,25 +4,121 @@
  * 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, isAbsolute } from 'path';
+import { existsSync, readdirSync, rmSync, statSync, writeFileSync, mkdirSync } from 'fs';
+import { createHash, randomUUID } from 'node:crypto';
 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 { AssetService, publicUrlForAssetId } from '../services/assets/index.js';
+import { FREE_STANDING_OWNER_TYPES } from '../services/assets/asset-index-service.js';
+import { ENTITY_SCHEMAS, EntityBaseSchema, PLURAL_TO_SINGULAR, RESERVED_ENTITY_TYPES, assertValidTaskDates } from './validation.js';
+import { isInternalField } from './schema-registry.js';
 import { CSVService } from '../services/csv-service.js';
+import { commitMessage as commitMsg, titleCaseType } from './commit-messages.js';
+import { computeChange, parseFrontmatterCacheFree } from './history-diff.js';
+import { folderPathFromFile, normalizeFolderPath, validateFolderPath, InvalidFolderPathError } from './folder-paths.js';
+import { FOLDER_SIDECAR, readFolderSidecar, readFolderSidecarData, readFolderSidecarId, writeFolderSidecar, writeFolderSidecarData } from './folder-sidecar.js';
 import { z } from 'zod';
+/** Names skipped during recursive repo walks. */
+const WALK_IGNORE = new Set(['.git', '.studiograph', 'node_modules']);
+/**
+ * Compute the canonical revision hash for a body string. Used by the
+ * Phase 2 baseRevision precondition. SHA-256 hex (64 chars), matches the
+ * format Phase 3's `X-Studiograph-Base-Body-Hash` header expects.
+ */
+function sha256OfBody(body) {
+    return createHash('sha256').update(body, 'utf-8').digest('hex');
+}
+/**
+ * Thrown by `graph.update` when the git commit fails after the disk write
+ * has already landed. The .md is updated and observable to subsequent
+ * readers via `graph.get`, but no commit exists — the repo is dirty.
+ *
+ * The caller MUST surface this typed error so an operator can recover
+ * (manual `git add && git commit`, or `git checkout -- <path>` to revert
+ * disk). v3-of-the-plan claim of "auto-convergence via sessionManager"
+ * was false outside the autosave PUT path; Phase 2 explicitly registers
+ * server-side dirty files with sessionManager when available, but the
+ * caller still gets the typed error so it knows the write was partial.
+ */
+export class CommitFailedDirtyError extends Error {
+    entityType;
+    entityId;
+    path;
+    code = 'COMMIT_FAILED_DIRTY';
+    constructor(entityType, entityId, path, cause) {
+        const causeMsg = cause instanceof Error ? cause.message : String(cause);
+        super(`Commit failed after disk write for ${entityType}/${entityId} (${path}). ` +
+            `Disk is updated but uncommitted (dirty). Recover with \`git add ${path} && git commit\` ` +
+            `or \`git checkout -- ${path}\` to revert. Underlying error: ${causeMsg}`);
+        this.entityType = entityType;
+        this.entityId = entityId;
+        this.path = path;
+        this.name = 'CommitFailedDirtyError';
+        this.cause = cause;
+    }
+}
+/**
+ * Thrown by `graph.update` when a body write supplies a `baseRevision`
+ * that doesn't match the current body's content hash. Caller (autosave,
+ * MCP, agent, event processor) refetches and retries against the new
+ * revision.
+ */
+export class StaleBaseRevisionError extends Error {
+    entityType;
+    entityId;
+    expected;
+    actual;
+    code = 'STALE_BASE_REVISION';
+    constructor(entityType, entityId, expected, actual) {
+        super(`Stale base_revision for ${entityType}/${entityId}: caller supplied ${expected.slice(0, 12)}…, ` +
+            `current is ${actual.slice(0, 12)}…. Refetch current content and retry.`);
+        this.entityType = entityType;
+        this.entityId = entityId;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = 'StaleBaseRevisionError';
+    }
+}
+/**
+ * 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;
     gitService;
     noGit;
     markdownService;
+    csvService;
     assetService;
+    /** Workspace-global ownership index for immutable-keyed assets. Injected by
+     *  WorkspaceManager (one per workspace). Undefined in coordinator-less test
+     *  / CLI graphs — those fall back to the legacy `{type}/{id}` key scheme. */
+    assetIndex;
     gitUser;
-    csvService;
     vectorService;
     schemaRegistry;
+    workspaceRoot;
+    /** Cache for history-panel change summaries, keyed by `${relPath}@${hash}`.
+     *  A commit's diff against its parent is immutable, so this never needs
+     *  invalidation — entries only accumulate as history is viewed. */
+    historyChangeCache = new Map();
+    persistenceCallbacks;
+    bodyWriteCoordinator;
     constructor(config) {
         this.repoPath = config.repoPath;
         this.repoName = config.repoName;
@@ -30,6 +126,7 @@ 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);
@@ -43,10 +140,185 @@ export class BaseGraphManager {
         // Ensure repo is initialized
         this.ensureRepo();
     }
-    /** Expose git service for deferred commit operations (e.g. CommitScheduler). */
+    /**
+     * Friendly display label for an entity type — custom-type label when the
+     * workspace defines one, otherwise the title-cased key ("deal" → "Deal").
+     * Used to build human-readable commit messages.
+     */
+    typeLabel(type) {
+        return this.schemaRegistry?.getCustomTypeLabel(type) ?? titleCaseType(type);
+    }
+    /** Build an EntityRef for a commit message from a type, id, and optional title. */
+    commitRef(type, id, title) {
+        return { typeLabel: this.typeLabel(type), title: typeof title === 'string' ? title : undefined, id };
+    }
+    /**
+     * Build the friendly "Edited …" message for a deferred (batched) commit,
+     * given the "type/id" pairs accumulated by the SessionManager. Each title is
+     * resolved from the in-memory index at flush time (cheap lookup); an entity
+     * deleted before the flush falls back to its slug id.
+     */
+    buildEditedBatchMessage(entities) {
+        const refs = entities.map(({ type, id }) => {
+            let title;
+            try {
+                title = this.get(type, id).data?.name;
+            }
+            catch { /* gone → slug */ }
+            return this.commitRef(type, id, title);
+        });
+        return commitMsg.editedBatch(refs);
+    }
+    /**
+     * Change summary for one commit in a file's history — which frontmatter
+     * fields moved and whether the body changed — by diffing the file at `hash`
+     * against its true git parent (`hash^`). Used by the entity History panel.
+     *
+     * `relPath` is repo-relative. Null parent (root commit, or file absent at the
+     * parent) → `created`. Result is immutable per (path, hash), so it's cached.
+     * Returns null only when the file isn't present at `hash`.
+     */
+    getCommitChange(relPath, hash) {
+        if (!this.gitService)
+            return null;
+        const cacheKey = `${relPath}@${hash}`;
+        const cached = this.historyChangeCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const current = this.gitService.getFileAtCommit(relPath, hash);
+        if (current === null)
+            return null;
+        // getFileAtCommit returns null when `hash^` has no commit (root) OR the
+        // file didn't exist there — both mean "created at this commit".
+        const parent = this.gitService.getFileAtCommit(relPath, `${hash}^`);
+        const change = computeChange(current, parent);
+        this.historyChangeCache.set(cacheKey, change);
+        return change;
+    }
+    /** 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);
+    }
+    /**
+     * `git pull` this repo, then reconcile any live editor Y.Doc whose .md the
+     * pull rewrote. Mirrors the restore-reconcile fix (see `restoreFile`): a
+     * pull changes files on disk WITHOUT flowing through the coordinator's
+     * body-write path, so an open editor still holds the pre-pull content and
+     * would sync it back over the pull on its next autosave (silent loss of the
+     * pulled-in changes). Routing each changed entity through the coordinator
+     * acquires the per-doc lock and smart-merges disk into the live Y.Doc.
+     *
+     * The wrinkle vs. restore: a pull is repo-wide, so we diff HEAD before/after
+     * to find the changed .md files and reconcile EACH one's docName rather than
+     * a single known entity. To avoid parsing every changed file on a large pull
+     * when nobody is editing, the loop is gated to the entities that actually
+     * have a live Y.Doc open (`coordinator.activeDocNames()`).
+     *
+     * Throws if the pull itself fails (merge conflict, no upstream, etc.) — the
+     * caller (POST /api/pull) catches per-repo. Reconcile only runs after a
+     * successful pull, so a conflicted/aborted pull never reconciles.
+     *
+     * Returns the docNames that were reconciled (empty when nothing was open,
+     * the repo has no git service, or the pull was a no-op fast-forward to the
+     * same HEAD).
+     */
+    async pullAndReconcile() {
+        if (!this.gitService)
+            return { reconciled: [] };
+        const before = this.gitService.getHeadCommit();
+        this.gitService.pull();
+        const after = this.gitService.getHeadCommit();
+        // No new commits (already up to date) or no coordinator wired → the pull
+        // is the only effect; freshly-opened editors seed from the new disk state.
+        const coordinator = this.bodyWriteCoordinator;
+        if (!coordinator || !before || !after || before === after) {
+            return { reconciled: [] };
+        }
+        // The pull changed files on disk behind the in-memory file index (entity →
+        // path). Drop it before reconciling: reconcileFromDisk reads through
+        // `graph.get`, which resolves the entity's path via that index, so a stale
+        // path after a remote MOVE/RENAME/DELETE would make `graph.get` read a
+        // now-gone file, return '', and wipe the live Y.Doc. Mirrors the
+        // invalidateIndex() every local mutation already does.
+        this.invalidateIndex();
+        // Gate to the entities with a live Y.Doc open in THIS repo. When nobody is
+        // editing here, skip the per-file parse loop entirely — the pull already
+        // updated disk and later openers seed from it.
+        const prefix = `${this.repoName}/`;
+        const activeDocs = new Set(coordinator.activeDocNames().filter(d => d.startsWith(prefix)));
+        if (activeDocs.size === 0)
+            return { reconciled: [] };
+        // entityId (the .md basename) of each open doc — lets us skip parsing a
+        // changed file whose id isn't open before identifying its type.
+        const activeIds = new Set([...activeDocs].map(d => d.split('/').slice(2).join('/')));
+        const reconciled = [];
+        for (const rel of this.gitService.diffNameOnly(before, after)) {
+            if (!rel.endsWith('.md'))
+                continue;
+            const stem = rel.split('/').pop().replace(/\.md$/, '');
+            if (!activeIds.has(stem))
+                continue; // no open editor by this id
+            const absPath = join(this.repoPath, rel);
+            if (!existsSync(absPath))
+                continue; // deleted by the pull — no live body to reconcile to
+            const ent = this.identifyEntityAtPath(absPath);
+            if (!ent)
+                continue;
+            const docName = `${this.repoName}/${ent.entityType}/${ent.entityId}`;
+            if (!activeDocs.has(docName))
+                continue; // same id, different type — not the open doc
+            await coordinator.reconcileFromDisk({
+                repo: this.repoName,
+                entityType: ent.entityType,
+                entityId: ent.entityId,
+                entityPath: absPath,
+            });
+            reconciled.push(docName);
+        }
+        return { reconciled };
+    }
+    /** 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 structural-mutation callbacks. Called once after construction by
+     * the server bootstrap (or test setup) so the Yjs persistence layer can
+     * react to rename/delete/changeType without route-layer code calling
+     * persistence APIs directly.
+     */
+    setPersistenceCallbacks(callbacks) {
+        this.persistenceCallbacks = callbacks;
+    }
+    /**
+     * Install the body-write coordinator. graph.update delegates the body-write
+     * critical section (lock, base-hash, atomic disk write, commit, broadcast,
+     * mdRevisionHash bookkeeping, assertWritable) to the coordinator. When
+     * unset (test fixtures without a Y.Doc layer), body writes fall back to a
+     * direct disk-write + commit path with no lock/broadcast — preserves the
+     * legacy "no callbacks" behavior some test setups rely on.
+     */
+    setBodyWriteCoordinator(coordinator) {
+        this.bodyWriteCoordinator = coordinator;
+    }
     /**
      * Ensure repository exists
      */
@@ -57,11 +329,140 @@ 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;
+    /**
+     * Cache of the parsed `list()` view, keyed by `entityType ?? '*'`. Built
+     * lazily on first read; invalidated alongside `fileIndex` on every
+     * mutation. Without this, autosuggest walks the entire markdown tree
+     * and parses YAML frontmatter for every entry on every keystroke (5–7s
+     * on workspaces with a few thousand entries).
+     *
+     * Staleness contract: identical to `fileIndex` — single-process trust
+     * model. Git pulls and out-of-process file edits would equally miss
+     * the existing `fileIndex` cache; no regression there.
+     */
+    listCache;
+    /** Drop the cached file index so the next read rebuilds it. */
+    invalidateIndex() {
+        this.fileIndex = undefined;
+        this.listCache = 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 ".".
      */
-    getEntityPath(entityType, entityId) {
-        const pluralDir = SINGULAR_TO_PLURAL[entityType] || `${entityType}s`;
-        return join(this.repoPath, pluralDir, `${entityId}.md`);
+    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.
+     */
+    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
@@ -80,12 +481,19 @@ export class BaseGraphManager {
         try {
             // Add entity_type and preprocess YAML parsing artefacts:
             // - null → undefined (Zod .optional() doesn't accept null)
+            // - empty string on a date field → undefined (the date vocabulary's
+            //   `date` / `start_date` are `.date()`-typed and reject ''; old create
+            //   code seeded '' for absent optional strings, so existing entities
+            //   carry empty date fields. Coercing to undefined keeps their next
+            //   update from failing validation and self-heals the stored frontmatter.)
             // - Date objects → ISO date string (unquoted YAML dates parse as Date)
             // - bare string for array field → wrap in array (single-value YAML list)
             const raw = { ...data, entity_type: entityType };
             const dataWithType = Object.fromEntries(Object.entries(raw).map(([k, v]) => {
                 if (v === null)
                     return [k, undefined];
+                if ((k === 'date' || k === 'start_date') && v === '')
+                    return [k, undefined];
                 if (typeof v === 'object' && v !== null && Object.prototype.toString.call(v) === '[object Date]')
                     return [k, v.toISOString().split('T')[0]];
                 // Coerce scalar string to array for known array-typed fields
@@ -107,11 +515,19 @@ export class BaseGraphManager {
                     return [k, v.toLowerCase()];
                 return [k, v];
             }));
-            return schema.parse(dataWithType);
+            const result = schema.parse(dataWithType);
+            // Cross-field task rule (start <= due). Skipped in lenient mode, which
+            // exists to keep already-stored entities discoverable — we don't want a
+            // historical bad-ordering to make an entity unreadable. See
+            // assertValidTaskDates for why this isn't a Zod refinement.
+            if (!lenient && entityType === 'task') {
+                assertValidTaskDates(result);
+            }
+            return result;
         }
         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 +537,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, skipVectorIndex } = 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;
@@ -134,37 +556,56 @@ export class BaseGraphManager {
             for (const key of Object.keys(shape)) {
                 if (BASE_KEYS.has(key))
                     continue;
+                // System-managed fields (source_file, indexable) are never seeded with
+                // an empty default — a directly-created entry has NO such field rather
+                // than a junk `''`. They're set only by the import/convert path.
+                if (isInternalField(shape[key]))
+                    continue;
                 if (!(key in data)) {
                     const field = shape[key];
                     // 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;
                     }
-                    // Don't populate URL-typed strings with '' — empty string fails URL validation.
-                    if (inner instanceof z.ZodString && inner._def.checks?.some((c) => c.kind === 'url')) {
+                    if (inner instanceof z.ZodString) {
+                        // Skip format-constrained strings — empty string fails url/date/
+                        // datetime validation (e.g. `start_date` is now `.date()`-typed).
+                        const FORMATS = new Set(['url', 'date', 'datetime']);
+                        if (inner._def.checks?.some((c) => FORMATS.has(c.def?.format)))
+                            continue;
+                        data[key] = '';
                         continue;
                     }
-                    const isArray = inner instanceof z.ZodArray;
-                    data[key] = isArray ? [] : '';
+                    // 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({
@@ -173,21 +614,44 @@ export class BaseGraphManager {
                 entityId,
                 filePath: entityPath,
             });
-            const message = commitMessage || `Create ${entityType}: ${entityId}`;
+            if (removedMarker) {
+                transaction.add({
+                    operation: 'delete',
+                    entityType,
+                    entityId,
+                    filePath: removedMarker,
+                });
+            }
+            const message = commitMessage || commitMsg.created(this.commitRef(entityType, entityId, data?.name));
             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.
+        // `skipVectorIndex` opts out for the asset-upload stub create — see the
+        // CreateEntityOptions doc; the finalizing update is the single upsert.
+        if (this.vectorService && !skipVectorIndex) {
+            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);
@@ -209,113 +673,419 @@ export class BaseGraphManager {
         return {
             id: entityId,
             path: entityPath,
+            folder_path: folderPathFromFile(entityPath, this.repoPath),
             entityType,
             data: validatedData,
             document,
         };
     }
+    /**
+     * The live editor body for an entity when a seeded Y.Doc is open, else
+     * null. `get` reads disk, which lags the live Y.Doc by the autosave
+     * debounce + commit — so a user's freshly-placed image/asset embed exists
+     * in the editor before it reaches disk. Callers that must reflect what the
+     * user is actually looking at (the get_entity surfaces, the whole-body
+     * asset-drop guard) prefer this and fall back to disk on null.
+     *
+     * Returns null when no coordinator is wired (CLI / test fixtures) — those
+     * setups have no live editor layer, so disk IS the authoritative body.
+     */
+    getLiveBody(entityType, entityId) {
+        if (!this.bodyWriteCoordinator?.peekLiveBody)
+            return null;
+        return this.bodyWriteCoordinator.peekLiveBody({
+            repo: this.repoName,
+            entityType,
+            entityId,
+        });
+    }
     /**
      * Get an entity by ID only (type resolved from the filesystem).
      *
-     * Scans every plural-type subdirectory under this repo for `{id}.md`.
-     * Bounded by the number of entity types (~17), not the number of entities,
-     * so still fast. Previously this computed `{repo}/s/{id}.md` by passing an
-     * empty entity type to getEntityPath, which meant getById never found
-     * anything — the agent's `get_entity` tool would silently fail when
-     * called without an explicit type, producing the "search finds it but
-     * get_entity can't resolve it" symptom.
+     * 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) {
         if (!existsSync(this.repoPath)) {
             throw new Error(`Entity not found: ${entityId}`);
         }
-        for (const [plural, singular] of Object.entries(PLURAL_TO_SINGULAR)) {
-            const candidate = join(this.repoPath, plural, `${entityId}.md`);
-            if (existsSync(candidate)) {
-                return this.get(singular, entityId);
+        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);
             }
         }
         throw new Error(`Entity not found: ${entityId}`);
     }
+    /**
+     * Get an entity by its file path — repo-relative (as returned by the
+     * search/list tools) or absolute. The most direct resolver: the caller
+     * never needs the canonical type, which closes the search→get_entity
+     * round-trip for entries whose frontmatter `type` field differs from
+     * `entity_type` (e.g. an `event` carrying `type: meeting`). The path is
+     * contained to this repo — a `..` escape or out-of-repo path is rejected
+     * as not-found rather than read.
+     */
+    getByPath(filePath) {
+        const abs = isAbsolute(filePath) ? filePath : join(this.repoPath, filePath);
+        const rel = relative(this.repoPath, abs);
+        if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+            throw new Error(`Entity not found: ${filePath}`);
+        }
+        if (!existsSync(abs)) {
+            throw new Error(`Entity not found: ${filePath}`);
+        }
+        const document = this.markdownService.parseFile(abs);
+        const entityType = (document.frontmatter.entity_type
+            || this.inferLegacyType(abs)
+            || 'note');
+        const entityId = abs.split('/').pop().replace(/\.md$/, '');
+        let validatedData;
+        try {
+            validatedData = this.validateEntity(entityType, document.frontmatter);
+        }
+        catch {
+            try {
+                validatedData = this.validateEntity(entityType, document.frontmatter, true);
+            }
+            catch {
+                validatedData = document.frontmatter;
+            }
+        }
+        return {
+            id: entityId,
+            path: abs,
+            folder_path: folderPathFromFile(abs, this.repoPath),
+            entityType,
+            data: validatedData,
+            document,
+        };
+    }
+    /**
+     * Merge a caller's `data` onto a base frontmatter, always stamping
+     * `updated_at` / `updated_by`, then validate. Even content-only edits
+     * (editor autosave, where `data` is undefined) re-stamp the audit fields —
+     * otherwise the trail freezes at whatever the last data-change user was,
+     * which for scaffolded files is "studiograph".
+     *
+     * `baseFrontmatter` is the frontmatter to merge onto. The body-write path
+     * passes the CURRENT on-disk frontmatter (read inside the per-doc lock) so
+     * a concurrent metadata-only edit isn't clobbered; the frontmatter-only
+     * path passes `existing.data` (synchronous, no lock window).
+     *
+     * Validation uses lenient mode + a Date-coercion fallback when no new data
+     * is supplied, since the existing entity may have been stored without all
+     * required fields, and gray-matter would otherwise serialize Date objects
+     * as full ISO timestamps.
+     */
+    composeUpdatedFrontmatter(entityType, baseFrontmatter, data, user) {
+        const updater = (user ?? this.gitUser).id;
+        const now = new Date().toISOString();
+        const mergedData = data
+            ? { ...baseFrontmatter, ...data, entity_type: entityType, updated_at: now, updated_by: updater }
+            : { ...baseFrontmatter, updated_at: now, updated_by: updater };
+        // JSON Merge Patch convention: an incoming `null` means "delete this field",
+        // not "store null". Updates MERGE onto the existing frontmatter, so omitting
+        // a key can't clear it — the merge keeps the old value. A caller (the web
+        // editor's "Clear" button, MCP/agent field deletion) sends `null` to remove
+        // it. `null` was never a valid stored value (schemas use `.optional()`, not
+        // `.nullable()`), so stripping it here only adds a deletion path and can't
+        // discard a meaningful value. Done before validation so a removed required
+        // field surfaces as the normal "missing field" error.
+        const deletedKeys = [];
+        if (data) {
+            for (const [key, value] of Object.entries(data)) {
+                if (value === null) {
+                    delete mergedData[key];
+                    deletedKeys.push(key);
+                }
+            }
+        }
+        // Task completion stamp: when a data change moves status to/from `done`,
+        // manage `completed_at` here so every surface (app, MCP, agent) gets it
+        // for free. Only on a real transition, and never when the caller supplied
+        // completed_at explicitly (respect their intent). Skipped for content-only
+        // edits (data undefined) so autosave never touches it.
+        if (data && entityType === 'task' && !Object.prototype.hasOwnProperty.call(data, 'completed_at')) {
+            const priorStatus = baseFrontmatter.status;
+            const newStatus = mergedData.status;
+            if (newStatus === 'done' && priorStatus !== 'done') {
+                mergedData.completed_at = now;
+            }
+            else if (newStatus !== 'done' && 'completed_at' in mergedData) {
+                delete mergedData.completed_at;
+            }
+        }
+        if (data) {
+            const validated = this.validateEntity(entityType, mergedData);
+            // A deletion key that reappears after validation was re-supplied by a
+            // schema `.default()` (e.g. task.status → 'backlog', event.type →
+            // 'meeting'). The field can't actually be cleared — its absence is
+            // re-materialized on every read. Reject loudly rather than silently
+            // resetting it to the default (and firing side effects like the
+            // completed_at stamp above, which never lands because we throw here).
+            // `hasOwnProperty`, not `in`: schemas are `.passthrough()`, so a custom
+            // field literally named `constructor`/`toString`/etc. is clearable, but
+            // `in` would match it on the prototype chain and wrongly reject it.
+            const undeletable = deletedKeys.filter((k) => Object.prototype.hasOwnProperty.call(validated, k));
+            if (undeletable.length > 0) {
+                throw new Error(`Cannot clear field${undeletable.length > 1 ? 's' : ''} ` +
+                    `${undeletable.join(', ')} on ${entityType}: ` +
+                    `${undeletable.length > 1 ? 'they have' : 'it has'} a default value.`);
+            }
+            return validated;
+        }
+        try {
+            return this.validateEntity(entityType, mergedData);
+        }
+        catch {
+            try {
+                return this.validateEntity(entityType, mergedData, true);
+            }
+            catch {
+                const coerced = Object.fromEntries(Object.entries(mergedData).map(([k, v]) => {
+                    if (v !== null && typeof v === 'object' && Object.prototype.toString.call(v) === '[object Date]') {
+                        return [k, v.toISOString().split('T')[0]];
+                    }
+                    return [k, v];
+                }));
+                return coerced;
+            }
+        }
+    }
     /**
      * Update an existing entity
      */
     async update(options) {
-        const { entityType, entityId, data, content, commitMessage, skipCommit, user } = options;
+        const { entityType, entityId, data, content, commitMessage, skipCommit, user, source, baseRevision } = options;
+        // Hard contract: body writes must declare provenance. A missing source
+        // used to warn-and-default to 'server-write', but a warning leaves a
+        // bypass-shaped footpath for future callers. Every production caller
+        // (autosave PUT, event processor, entity-mutations helper) already
+        // declares it; throw so a new body-write surface can't silently drift
+        // back into ambiguity.
+        if (content !== undefined && source === undefined) {
+            throw new Error(`update() for ${entityType}/${entityId} passed content without a source. ` +
+                `Body writes must declare source: 'autosave' | 'server-write'.`);
+        }
         // Get existing entity
         const existing = this.get(entityType, entityId);
-        // Merge data (if provided) and add update metadata
-        const mergedData = data
-            ? {
-                ...existing.data,
-                ...data,
-                entity_type: entityType,
-                updated_at: new Date().toISOString(),
-                updated_by: (user ?? this.gitUser).id,
-            }
-            : existing.data;
-        // 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
-        // serialize them as full ISO timestamps.
-        let validatedData;
-        if (data) {
-            validatedData = this.validateEntity(entityType, mergedData);
+        // 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;
+        if (content !== undefined && this.bodyWriteCoordinator) {
+            // Body write: delegate the critical section to the coordinator.
+            // assertWritable, per-doc lock, base-hash precondition, atomic write,
+            // commit, dirty-recovery, and post-commit applyAgentContent all live
+            // there now.
+            //
+            // Frontmatter is merged + validated INSIDE the coordinator's per-doc
+            // lock (via prepareFrontmatter) against the CURRENT on-disk
+            // frontmatter — not a snapshot read here, before the lock. Editor
+            // autosave sends `{ content }` only; if we merged against a pre-lock
+            // snapshot, a metadata-only edit that commits while this write waits
+            // for the lock would be silently clobbered by the stale snapshot.
+            const result = await this.bodyWriteCoordinator.writeBody({ repo: this.repoName, entityType, entityId, entityPath }, content, {
+                prepareFrontmatter: (currentDiskFrontmatter) => this.composeUpdatedFrontmatter(entityType, currentDiskFrontmatter, data, user),
+                baseHash: baseRevision,
+                // Guaranteed defined: the guard at the top throws when content is
+                // present without a source, and this branch requires content.
+                source: source,
+                actor: user ?? this.gitUser,
+                skipCommit,
+                // Default to the friendly "Edited …" subject so server-write body
+                // edits (MCP/agent) match create/update/etc. The skipCommit path
+                // ignores this and defers to the SessionManager's batch message.
+                commitMessage: commitMessage ??
+                    commitMsg.edited(this.commitRef(entityType, entityId, data?.name ?? existing.data?.name)),
+            });
+            options.onBroadcast?.(result.broadcast);
         }
         else {
-            try {
-                validatedData = this.validateEntity(entityType, mergedData);
+            // Frontmatter-only write (content === undefined) OR a test fixture
+            // running without a coordinator. No concurrent-lock window here: the
+            // read-merge-write below is synchronous, so it can't interleave with
+            // the coordinator's (also synchronous) critical section.
+            const validatedData = this.composeUpdatedFrontmatter(entityType, existing.data, data, user);
+            const mergedContent = content !== undefined ? content : existing.document.content;
+            // baseRevision is meaningless without a body change; coordinator-less
+            // setups exist solely for tests that don't exercise the autosave 412
+            // contract.
+            if (baseRevision !== undefined && content !== undefined) {
+                const currentBody = this.markdownService.parseFile(entityPath).content;
+                const currentHash = sha256OfBody(currentBody);
+                if (currentHash !== baseRevision) {
+                    throw new StaleBaseRevisionError(entityType, entityId, baseRevision, currentHash);
+                }
             }
-            catch {
+            this.markdownService.writeFile(entityPath, {
+                frontmatter: validatedData,
+                content: mergedContent,
+                wikilinks: this.markdownService.extractWikilinks(mergedContent, validatedData),
+            });
+            if (this.gitService && !skipCommit) {
+                const transaction = this.gitService.createTransaction();
+                transaction.add({
+                    operation: 'update',
+                    entityType,
+                    entityId,
+                    filePath: entityPath,
+                });
+                const message = commitMessage || commitMsg.edited(this.commitRef(entityType, entityId, validatedData?.name));
                 try {
-                    validatedData = this.validateEntity(entityType, mergedData, true);
+                    await transaction.commit(user ?? this.gitUser, message);
                 }
-                catch {
-                    const coerced = Object.fromEntries(Object.entries(mergedData).map(([k, v]) => {
-                        if (v !== null && typeof v === 'object' && Object.prototype.toString.call(v) === '[object Date]') {
-                            return [k, v.toISOString().split('T')[0]];
-                        }
-                        return [k, v];
-                    }));
-                    validatedData = coerced;
+                catch (err) {
+                    throw new CommitFailedDirtyError(entityType, entityId, entityPath, err);
                 }
             }
         }
-        // Merge content (if provided)
-        const mergedContent = content !== undefined ? content : existing.document.content;
-        // Write updated markdown file
-        const entityPath = this.getEntityPath(entityType, entityId);
-        this.markdownService.writeFile(entityPath, {
-            frontmatter: validatedData,
-            content: mergedContent,
-            wikilinks: this.markdownService.extractWikilinks(mergedContent, validatedData),
-        });
-        if (this.gitService && !skipCommit) {
-            const transaction = this.gitService.createTransaction();
-            transaction.add({
-                operation: 'update',
-                entityType,
-                entityId,
-                filePath: entityPath,
-            });
-            const message = commitMessage || `Update ${entityType}: ${entityId}`;
-            await transaction.commit(user ?? this.gitUser, message);
-        }
+        // The on-disk frontmatter has changed, so the parsed-EntityFile cache
+        // that list() serves from is stale until invalidated. Without this, the
+        // next list_entities call returns pre-update frontmatter while
+        // get_entity (which reads fresh from disk) returns post-update — every
+        // other mutation in this file already invalidates after its write.
+        this.invalidateIndex();
         // 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, title: existing.data?.name });
+            }
+            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
+                ?? commitMsg.deletedBatch(deleted.map(d => this.commitRef(d.entityType, d.entityId, d.title)));
+            await transaction.commit(options?.user ?? this.gitUser, message);
+        }
+        // No asset cleanup: deleting entries keeps their assets (assets-
+        // referenced-not-owned P1 — same semantics as single delete()).
+        // 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 });
+        // 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({
@@ -324,11 +1094,45 @@ export class BaseGraphManager {
                 entityId,
                 filePath: existing.path,
             });
-            const message = commitMessage || `Delete ${entityType}: ${entityId}`;
+            if (addedMarker) {
+                transaction.add({
+                    operation: 'create',
+                    entityType,
+                    entityId,
+                    filePath: addedMarker,
+                });
+            }
+            const message = commitMessage || commitMsg.deleted(this.commitRef(entityType, entityId, existing.data?.name));
             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));
+        // Assets are never deleted here: assets are library citizens (folder/
+        // workspace-homed) that entries only REFERENCE, so entry deletion never
+        // destroys binaries. Deliberate asset deletion is by-id (deleteAssetById).
+        // 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.persistenceCallbacks?.onDelete) {
+            try {
+                await this.persistenceCallbacks.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.
@@ -336,7 +1140,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`);
         }
@@ -350,33 +1155,61 @@ export class BaseGraphManager {
         // Remove old file
         const { rmSync } = await import('fs');
         rmSync(existing.path, { force: true });
-        // Git: stage the rename and commit directly (mirrors changeType). The
-        // older transaction-based path never called transaction.add() and threw
-        // "No changes to commit" every time.
+        this.invalidateIndex();
         if (this.gitService) {
-            const { spawnSync } = await import('child_process');
-            const gitUser = user ?? this.gitUser;
-            const message = commitMessage || `Rename ${entityType}: ${oldId} → ${newId}`;
-            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
-        this.vectorService?.delete(this.repoName, entityType, oldId).catch(() => { });
+            const message = commitMessage || commitMsg.renamed(this.typeLabel(entityType), oldId, newId);
+            this.gitService.commitFiles([existing.path, newPath], message, user ?? this.gitUser);
+        }
+        // Re-point asset ownership to the new id. Keys are immutable, so no blob
+        // moves and the embed URLs in the body keep resolving — this just keeps
+        // listByOwner/delete/transfer correct after the rename.
+        this.reassignOwnedAssets(entityType, oldId, { ownerId: newId });
+        // 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.persistenceCallbacks?.onRename) {
+            try {
+                await this.persistenceCallbacks.onRename(this.repoName, entityType, oldId, newId);
+            }
+            catch (err) {
+                console.warn(`[graph] onRename callback failed for ${entityType}/${oldId}→${newId}:`, err);
+            }
+        }
         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) {
+        // Don't let change-type re-mint a retired type (`asset`, Phase F). Without
+        // this, `toType: 'asset'` would fall back to EntityBaseSchema and write a
+        // base-only stub of exactly the type we removed. (Only the retired-type
+        // reservation is enforced here; general unknown-target validation incl.
+        // custom types stays a route-level concern.)
+        if (RESERVED_ENTITY_TYPES.has(toType)) {
+            throw new Error(`Cannot change_type to '${toType}' — that entity type was retired.`);
+        }
         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
@@ -405,6 +1238,10 @@ export class BaseGraphManager {
             for (const key of Object.keys(shape)) {
                 if (BASE_KEYS.has(key))
                     continue;
+                // Don't seed system-managed fields (source_file, indexable) — same
+                // rule as the create path.
+                if (isInternalField(shape[key]))
+                    continue;
                 if (!(key in doc.frontmatter)) {
                     const field = shape[key];
                     const inner = field instanceof z.ZodOptional ? field._def.innerType
@@ -416,70 +1253,415 @@ 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
+            const message = commitMessage || commitMsg.changedType(this.commitRef(fromType, entityId, existing.data?.name), this.typeLabel(fromType), this.typeLabel(toType));
+            this.gitService.commitFiles([existing.path], message, user ?? this.gitUser);
+        }
+        // Re-point asset ownership to the new type (keys immutable; no blob moves).
+        // The `asset` entity type was retired (Phase F), so no entity carries a PDF
+        // text sidecar keyed under assets-text/asset/ — nothing to move here.
+        this.reassignOwnedAssets(fromType, entityId, { ownerType: toType });
+        // 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.persistenceCallbacks?.onChangeType) {
+            try {
+                await this.persistenceCallbacks.onChangeType(this.repoName, entityId, fromType, toType);
+            }
+            catch (err) {
+                console.warn(`[graph] onChangeType callback failed for ${entityId} (${fromType}→${toType}):`, err);
+            }
+        }
         return updated;
     }
     /**
-     * Enumerate the distinct entity types present in this repo, without
-     * parsing any markdown files. Derived from the plural-named subdirectories
-     * directly (e.g. `meetings/`, `projects/`). Used by /api/repos to let the
-     * sidebar render the Views list without a full entity fetch per folder.
+     * 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 —
+     * pass `overwrite: true` to replace it, but only when the occupant is
+     * itself a parseable entity (never silently clobber arbitrary files like
+     * README.md or .gitkeep).
      */
-    listEntityTypes() {
-        if (!existsSync(this.repoPath))
-            return [];
-        const types = new Set();
-        try {
-            for (const entry of readdirSync(this.repoPath)) {
-                if (entry.startsWith('.'))
-                    continue;
-                const fullPath = join(this.repoPath, entry);
-                try {
-                    if (!statSync(fullPath).isDirectory())
-                        continue;
-                }
-                catch {
-                    continue;
-                }
-                const singularType = PLURAL_TO_SINGULAR[entry];
-                if (singularType)
-                    types.add(singularType);
+    async move(entityType, entityId, targetFolderPath, commitMessage, user, overwrite) {
+        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)) {
+            if (!overwrite) {
+                throw new Error(`Path already occupied: ${normalized}/${entityId}.md`);
+            }
+            // Safety guard: only overwrite when the destination is itself an
+            // entity .md (parseable frontmatter or legacy plural-type dir). Refuse
+            // to clobber README.md, CHANGELOG.md, .gitkeep, or anything else that
+            // isn't a tracked entry — that would be data loss the caller didn't
+            // ask for.
+            const occupant = this.identifyEntityAtPath(newPath);
+            if (!occupant) {
+                throw new Error(`Refusing to overwrite non-entity file at ${normalized}/${entityId}.md — ` +
+                    `destination must be a parseable entity for overwrite to be safe.`);
             }
         }
-        catch { /* repo path unreadable */ }
-        return [...types].sort();
+        mkdirSync(dirname(newPath), { recursive: true });
+        const { renameSync } = await import('fs');
+        // On POSIX, renameSync atomically replaces the destination if it exists.
+        // The overwrite gate above ensures we only reach this point when the
+        // occupant is a tracked entity (or the path is empty).
+        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 || commitMsg.movedTo(this.commitRef(entityType, entityId, existing.data?.name), 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}`);
+            }
+            // Guard: if the entry was change_type'd after this commit, the file path
+            // is unchanged but the historical frontmatter carries the OLD
+            // entity_type. Writing it back would silently revert the type, bypassing
+            // change_type's collision checks, asset re-ownership, vector reindex, and
+            // persistence callbacks — and the route would still broadcast an update
+            // for the current type. Refuse rather than corrupt.
+            // Read entity_type straight from the raw frontmatter block (no shared
+            // markdown-parse layer) so this reflects exactly what's on disk at the
+            // historical commit.
+            const fmBlock = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+            const historicalType = fmBlock?.[1]
+                .match(/^entity_type:\s*["']?([^"'\r\n]+)["']?\s*$/m)?.[1]
+                ?.trim();
+            if (historicalType && historicalType !== entityType) {
+                throw new Error(`Cannot restore: the entry was type '${historicalType}' at that commit but is '${entityType}' now. ` +
+                    `Restoring would change its type without the safeguards of change_type. ` +
+                    `Convert it explicitly with change_type if that's intended.`);
+            }
+            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) {
+                    // A non-entity file (README, stray .md, .gitkeep) now sits at the
+                    // restore path. identifyEntityAtPath returning null previously fell
+                    // through and writeFileSync clobbered it — silent data loss. Treat
+                    // any unidentifiable occupant as a conflict.
+                    throw new PathConflictError(found.path, {
+                        entityType: 'file',
+                        entityId: relative(this.repoPath, targetPath),
+                    });
+                }
+                if (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 restoredName = content ? this.markdownService.parseContent(content).frontmatter?.name : undefined;
+        const message = commitMsg.restored(this.commitRef(entityType, entityId, restoredName), shortHash);
+        this.gitService.commitFiles(filesToCommit, message, user ?? this.gitUser);
+        // Reconcile any live editor Y.Doc against the restored disk content. restoreFile
+        // writes the file directly — it does NOT flow through update()'s coordinator
+        // body-write path — so an editor with a live Y.Doc still holds the pre-restore
+        // content and would sync it back over the restore on the next autosave, making
+        // the restore look like a no-op. Routing through the coordinator acquires the
+        // per-doc lock (serializing the smart-merge against any in-flight autosave) and,
+        // crucially, covers EVERY restore caller — the HTTP route, the agent history
+        // tool, and the MCP tool — not just one. No-ops when no coordinator is wired
+        // (CLI/tests) or no editor doc is currently active (later openers seed from disk).
+        await this.bodyWriteCoordinator?.reconcileFromDisk({
+            repo: this.repoName,
+            entityType,
+            entityId,
+            entityPath: targetPath,
+        });
+        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 {
+                // Cache-free parse: this is historical content, and the shared
+                // gray-matter layer returned a stale entity_type for past-commit
+                // content (see parseFrontmatterCacheFree), which would mis-match here.
+                const fmType = parseFrontmatterCacheFree(content).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();
     }
     /**
-     * List entities of a given type
+     * 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 cacheKey = entityType ?? '*';
+        const cached = this.listCache?.get(cacheKey);
+        if (cached) {
+            return limit && limit > 0 ? cached.slice(0, limit) : cached;
+        }
+        // Serve a type-filtered request from the unfiltered cache if present —
+        // avoids re-walking the tree for each entity type on the same warm cache.
+        if (entityType) {
+            const all = this.listCache?.get('*');
+            if (all) {
+                const filtered = all.filter(e => e.entityType === entityType);
+                if (!this.listCache)
+                    this.listCache = new Map();
+                this.listCache.set(cacheKey, filtered);
+                return limit && limit > 0 ? filtered.slice(0, limit) : filtered;
+            }
+        }
         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);
@@ -493,97 +1675,39 @@ 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 (!this.listCache)
+            this.listCache = new Map();
+        this.listCache.set(cacheKey, results);
         if (limit && limit > 0)
             return results.slice(0, limit);
         return results;
@@ -592,7 +1716,7 @@ export class BaseGraphManager {
      * Search entities
      */
     search(options) {
-        const { entityType, query, filters, visibility, tags, dateRange, sortBy, limit } = options;
+        const { entityType, query, filters, visibility, tags, dateRange, sortBy, limit, nameOnly } = options;
         // Get all entities (optionally filtered by type)
         let entities = this.list(entityType);
         // Apply query filter (search across content + all string frontmatter fields)
@@ -602,7 +1726,7 @@ export class BaseGraphManager {
             const lowerQuery = query.toLowerCase();
             const EXCLUDED_SEARCH_FIELDS = new Set([
                 'entity_type', 'entity_id', 'created_by', 'updated_by',
-                'created_at', 'updated_at', 'date', 'start_date', 'end_date', 'due_date', 'expected_close',
+                'created_at', 'updated_at', 'date', 'start_date',
                 'deal_value', 'email', 'website', 'url', 'link', 'schema',
             ]);
             scored = [];
@@ -619,8 +1743,8 @@ export class BaseGraphManager {
                 else if (name.includes(lowerQuery)) {
                     score = 2;
                 }
-                // Frontmatter field match
-                if (score < 0) {
+                // Frontmatter field match — skipped in nameOnly mode (autosuggest).
+                if (score < 0 && !nameOnly) {
                     const data = e.data;
                     for (const [key, val] of Object.entries(data)) {
                         if (EXCLUDED_SEARCH_FIELDS.has(key) || key === 'name')
@@ -641,8 +1765,11 @@ export class BaseGraphManager {
                         }
                     }
                 }
-                // Body content match
-                if (score < 0 && e.document.content.toLowerCase().includes(lowerQuery)) {
+                // Body content match — skipped in nameOnly mode. Scanning every
+                // entity's full markdown body is the dominant cost for keyword
+                // search and is wasted on autosuggest, where the dropdown only
+                // shows the name.
+                if (score < 0 && !nameOnly && e.document.content.toLowerCase().includes(lowerQuery)) {
                     score = 0;
                 }
                 if (score >= 0)
@@ -747,31 +1874,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;
     }
@@ -782,19 +1921,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;
     }
@@ -809,28 +1942,22 @@ 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}`;
+            const message = commitMessage || commitMsg.relinked(oldId, newId);
             await transaction.commit(this.gitUser, message);
         }
         else {
@@ -840,14 +1967,772 @@ 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 sidecarIdByPath = 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 data = readFolderSidecarData(dir);
+                    if (data?.display_name)
+                        sidecarByPath.set(folderPath, data.display_name);
+                    if (data?.id)
+                        sidecarIdByPath.set(folderPath, data.id);
+                }
+            }
+        }
+        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;
+            const id = sidecarIdByPath.get(p);
+            if (id)
+                entry.id = id;
+            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) {
+            // Clear the override but keep the sidecar (and its id) when one exists —
+            // writeFolderSidecarData drops display_name and removes the file only if
+            // nothing (no id) remains.
+            const existing = readFolderSidecar(abs);
+            if (existing === null)
+                return null; // nothing to clear
+            const result = writeFolderSidecarData(abs, { display_name: undefined });
+            this.invalidateIndex();
+            return result;
+        }
+        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, empty display, display_name override
+     * already set) 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;
+            // First-writer-wins on the display_name specifically — skip when an
+            // override already exists (don't clobber a manual rename), but still
+            // record onto an id-only sidecar (every folder now has one for its id).
+            if (readFolderSidecar(abs) !== null)
+                continue;
+            const display = entry.display_name.trim();
+            if (!display)
+                continue;
+            // Merge-safe: preserves the folder's id alongside the new display_name.
+            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);
+        // Report whether the folder was already there so the create_subfolder tools
+        // can say "already exists — reusing it" instead of silently claiming they
+        // created a new folder (which would hide that entries are merging into an
+        // existing one). createFolder still doubles as an idempotent ensure-folder
+        // no-op for internal callers (personal-folder provisioning, rename), which
+        // ignore this flag.
+        const alreadyExisted = existsSync(abs);
+        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.
+        // A stable id is assigned eagerly when the folder doesn't already have one;
+        // an existing id is never regenerated (createFolder doubles as an
+        // ensure-folder no-op for paths that already exist).
+        const sidecarPatch = {};
+        if (!readFolderSidecarId(abs))
+            sidecarPatch.id = randomUUID();
+        if (options?.displayName !== undefined)
+            sidecarPatch.display_name = options.displayName;
+        const sidecarPath = Object.keys(sidecarPatch).length > 0
+            ? writeFolderSidecarData(abs, sidecarPatch)
+            : null;
+        this.invalidateIndex();
+        if (this.gitService) {
+            const message = commitMessage || commitMsg.folderCreated(normalized);
+            const files = sidecarPath ? [keep, sidecarPath] : [keep];
+            this.gitService.commitFiles(files, message, user ?? this.gitUser);
+        }
+        return { alreadyExisted };
+    }
+    /**
+     * Ensure the folder at `folderPath` (or the repo root when empty) carries a
+     * stable sidecar id, minting + committing one if absent. Returns the id.
+     *
+     * Saved views key folder scopes on this id (D2) so a view survives folder
+     * rename / move — the sidecar travels with the directory the same way an
+     * entity's frontmatter travels with its .md file. Idempotent: an existing id
+     * is returned untouched, never regenerated.
+     */
+    ensureFolderId(folderPath, user) {
+        const normalized = folderPath ? validateFolderPath(folderPath) : '';
+        const abs = normalized ? join(this.repoPath, normalized) : this.repoPath;
+        // Never materialize a phantom folder: writeFolderSidecarData mkdirSyncs the
+        // path, so minting an id for a folder that no longer exists on disk (e.g. a
+        // stale folder scope after another user renamed/deleted it) would silently
+        // resurrect + commit an empty directory. Refuse instead — the route turns
+        // this into a 400 rather than corrupting the tree.
+        if (!existsSync(abs)) {
+            throw new InvalidFolderPathError(`Folder no longer exists: ${normalized || '(root)'}`);
+        }
+        const existing = readFolderSidecarId(abs);
+        if (existing)
+            return existing;
+        const id = randomUUID();
+        // Non-null: writing a non-empty id always leaves the sidecar non-empty.
+        const sidecarPath = writeFolderSidecarData(abs, { id });
+        this.invalidateIndex();
+        if (this.gitService) {
+            this.gitService.commitFiles([sidecarPath], `Assign stable id to folder ${normalized || '(root)'}`, user ?? this.gitUser);
+        }
+        return id;
+    }
+    /**
+     * Resolve a stable sidecar folder id to its repo-relative path within this
+     * repo, or null when no folder here carries that id. Returns `''` when the
+     * id belongs to the repo root.
+     */
+    findFolderPathById(id) {
+        if (readFolderSidecarId(this.repoPath) === id)
+            return '';
+        for (const f of this.listFolders()) {
+            if (f.id === id)
+                return f.path;
+        }
+        return null;
+    }
+    /**
+     * All folder ids carried in this repo — the root sidecar (path `''`) plus
+     * every subfolder — as `{ id, path }` pairs. Built from a single
+     * `listFolders()` walk so a caller resolving many ids at once (e.g. the saved
+     * views GET) can index once instead of re-walking the tree per id.
+     */
+    folderIdEntries() {
+        const out = [];
+        const rootId = readFolderSidecarId(this.repoPath);
+        if (rootId)
+            out.push({ id: rootId, path: '' });
+        for (const f of this.listFolders()) {
+            if (f.id)
+                out.push({ id: f.id, path: f.path });
+        }
+        return out;
+    }
+    /**
+     * 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 || commitMsg.folderDisplayRenamed(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 || commitMsg.folderRenamed(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);
+        // For a cross-repo move, capture the entities in the tree BEFORE the
+        // rename so we can re-point their asset ownership to the target repo
+        // afterward (serve-time authz reads the index's repo column).
+        const ownersToReassign = [];
+        if (this.assetIndex && target.repoName !== this.repoName) {
+            const stack = [sourceAbs];
+            while (stack.length > 0) {
+                const dir = stack.pop();
+                let names;
+                try {
+                    names = readdirSync(dir);
+                }
+                catch {
+                    continue;
+                }
+                for (const name of names) {
+                    if (name.startsWith('.') || WALK_IGNORE.has(name))
+                        continue;
+                    const full = join(dir, name);
+                    let st;
+                    try {
+                        st = statSync(full);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (st.isDirectory())
+                        stack.push(full);
+                    else if (st.isFile() && name.endsWith('.md')) {
+                        const ent = this.identifyEntityAtPath(full);
+                        if (ent)
+                            ownersToReassign.push({ entityType: ent.entityType, entityId: ent.entityId });
+                    }
+                }
+            }
+        }
+        // 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
+            ?? commitMsg.folderMoved(sourceNormalized, target.repoName, targetNormalized);
+        const targetMessage = options?.commitMessage
+            ?? commitMsg.folderReceived(this.repoName, sourceNormalized, targetNormalized);
+        if (this.gitService) {
+            this.gitService.commitFiles([sourceAbs], sourceMessage, user);
+        }
+        if (target.gitService) {
+            target.gitService.commitFiles([targetAbs], targetMessage, user);
+        }
+        // Cross-repo: re-point asset ownership to the target repo (see capture above).
+        for (const o of ownersToReassign) {
+            this.assetIndex?.reassignOwner(this.repoName, o.entityType, o.entityId, { repo: target.repoName });
+        }
+        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 ?? commitMsg.movedBatch(moves.length, 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
+                ?? commitMsg.receivedBatch(moves.length, this.repoName);
+            const targetPaths = [...moves.map(m => m.dst), ...(removedTargetMarker ? [removedTargetMarker] : [])];
+            target.gitService.commitFiles(targetPaths, targetMessage, user);
+        }
+        // Cross-repo move: re-point asset ownership to the target repo so the
+        // serve route's per-repo authz resolves against the new repo. No blob
+        // movement (keys are immutable); the index is workspace-global so source
+        // and target share it. Same-repo folder moves leave repo unchanged.
+        if (target.repoName !== this.repoName) {
+            for (const entry of entries) {
+                this.assetIndex?.reassignOwner(this.repoName, entry.entityType, entry.entityId, { repo: target.repoName });
+            }
+        }
+        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 || commitMsg.folderDeleted(normalized);
+            this.gitService.commitFiles([abs], message, options?.user ?? this.gitUser);
+        }
+        // No asset cleanup: deleting a subfolder deletes its ENTRIES, and entries
+        // only reference assets (assets-referenced-not-owned P1). The assets are
+        // homed to the repo (not the subfolder) and persist in the library.
+        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();
+    }
+    /** The asset storage service (raw key copy/exists), if configured. Used by
+     *  the one-time key migration, which operates on raw `{...}/{file}` keys. */
+    getAssetService() {
+        return this.assetService;
+    }
+    /**
+     * Download the bytes of an asset OWNED by `assetEntityId` in THIS repo.
+     * Used by the convert flow to turn a stored .docx/.xlsx into a derived
+     * note/dataset. Backend-agnostic (local reads disk, R2 GetObjects).
+     *
+     * SECURITY: the asset's `asset_url` frontmatter is attacker-influenceable
+     * (a folder member can create an `asset` entity whose url points at another
+     * folder's storage key). So ownership is NOT taken from the url — it's
+     * resolved through the authoritative asset index, scoped to
+     * `(this.repoName, 'asset', assetEntityId)`, exactly like the GET
+     * /api/assets serve route. The url is used only to disambiguate which of the
+     * entity's own files to fetch (by filename). Unindexed legacy assets fall
+     * back to the legacy `asset/{entityId}/{file}` key bound to this same entity
+     * id; anything else is refused.
+     */
+    /**
+     * Download an immutable-keyed asset's bytes by its assetId + filename. The
+     * blob store is workspace-global (the key `{assetId}/{filename}` is
+     * independent of repo), so any graph can fetch any asset; the caller — the
+     * caption sweep — scopes to the rows it enumerated from assets.db.
+     */
+    async downloadAssetById(assetId, filename) {
+        if (!this.assetService) {
+            throw new Error('Asset service is not configured for this graph');
+        }
+        return await this.assetService.download(`${assetId}/${filename}`);
+    }
+    /** Pre-signed URL for an immutable-key asset ({assetId}/{filename}). */
+    async getAssetSignedUrlByAssetId(assetId, filename, method = 'GET', expiresIn) {
+        if (!this.assetService) {
+            throw new Error('Asset service is not configured for this graph');
+        }
+        return await this.assetService.getSignedUrlByAssetId(assetId, filename, expiresIn, method);
+    }
+    /**
+     * 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
      */
-    async uploadAsset(entityType, entityId, filename, buffer, keyPrefix) {
+    async uploadAsset(entityType, entityId, filename, buffer, keyPrefix, 
+    /** Auth user id of the uploader (web). Recorded in the asset index for
+     *  the "delete by uploader + workspace owner" rule. Omit for CLI/import/
+     *  agent uploads — stored as null (unknown → owner-only delete). */
+    opts) {
         if (!this.assetService) {
             throw new Error('Asset service is not configured for this graph');
         }
-        return await this.assetService.upload(entityType, entityId, filename, buffer, keyPrefix);
+        // Immutable-key path: generate a permanent assetId, store under
+        // {assetId}/{filename}, and record authoritative ownership in the index.
+        // The (entityType, entityId) args never shape ownership — renaming or
+        // retyping the entity never moves the blob. `keyPrefix` is irrelevant here
+        // (it only shaped the legacy {prefix}/{id} key).
+        if (this.assetIndex) {
+            // The model invariant is structural: no caller can mint an entity-owned
+            // row. Omitting `owner` homes the asset to this graph's folder.
+            const owner = opts?.owner ?? { type: 'folder', id: this.repoName };
+            if (!FREE_STANDING_OWNER_TYPES.has(owner.type)) {
+                throw new Error(`Asset owner must be free-standing (folder or workspace), got "${owner.type}" — entries reference assets, they never own them.`);
+            }
+            const assetId = randomUUID();
+            const info = await this.assetService.uploadByAssetId(assetId, filename, buffer);
+            this.assetIndex.put({
+                assetId,
+                repo: this.repoName,
+                ownerType: owner.type,
+                ownerId: owner.id,
+                filename: info.filename,
+                contentType: info.contentType,
+                mediaType: info.mediaType,
+                name: opts?.name ?? filename,
+                uploaderUserId: opts?.uploaderUserId ?? null,
+                size: buffer.length,
+            });
+            // Caption/OCR trigger (asset-as-embed): for an IMAGE row, seed a pending
+            // index-state row keyed by this assetId + notify the live caption drain.
+            // Fire-and-forget + image-gated inside ensureInitialAssetIndexState —
+            // captioning must never block or fail the upload. Covers every path that
+            // funnels through uploadAsset: import, manager upload, and editor embeds
+            // (all folder-owned under assets-referenced-not-owned P1).
+            this.vectorService?.ensureInitialAssetIndexState(assetId, {
+                mediaType: info.mediaType,
+                filename: info.filename,
+                repo: this.repoName,
+            }).catch(() => { });
+            return { ...info, assetId, publicUrl: publicUrlForAssetId(assetId, info.filename) };
+        }
+        // The ownership index is a hard invariant — WorkspaceManager wires it onto
+        // every graph. The old no-index branch wrote legacy {type}/{id}/{file}
+        // blobs; that scheme (and its serve route) is retired, so a graph without an
+        // index can no longer mint assets. Fail loud rather than write an unservable
+        // legacy blob.
+        throw new Error('uploadAsset requires the asset ownership index to be wired');
+    }
+    /** Inject the workspace-global asset ownership index (WorkspaceManager). */
+    setAssetIndex(index) {
+        this.assetIndex = index;
+    }
+    /** The asset ownership index, if wired. */
+    getAssetIndex() {
+        return this.assetIndex;
+    }
+    /** Delete a single index-tracked asset by its immutable id: blob + index row.
+     *  THE asset delete path (assets-referenced-not-owned: deleting an entry
+     *  never deletes assets, so deliberate asset deletion is always by-id).
+     *  Blob errors are non-fatal (the index row is the manager's source of
+     *  truth). No-op without an index/service. */
+    async deleteAssetById(assetId, filename) {
+        if (!this.assetIndex || !this.assetService)
+            return;
+        try {
+            await this.assetService.deleteByAssetId(assetId, filename);
+        }
+        catch (err) {
+            console.warn(`[asset] delete blob ${assetId} failed: ${err?.message ?? err}`);
+        }
+        // Isolated like the blob delete: when this runs from the import-failure
+        // rollback, a throw here would mask the original import error the caller
+        // must surface (mirrors the old rollback helper).
+        try {
+            this.assetIndex.delete(assetId);
+        }
+        catch (err) {
+            console.warn(`[asset] delete index row ${assetId} failed: ${err?.message ?? err}`);
+        }
+        // Reap the caption index-state row (assetId-keyed). Fire-and-forget +
+        // self-isolating so it can't mask the caller's error (e.g. import rollback).
+        void this.vectorService?.deleteIndexStateSafe(assetId);
+    }
+    /** Re-point the owning coordinates of every asset owned by an entity, with
+     *  no blob movement (keys are immutable). Used by rename (ownerId),
+     *  changeType (ownerType), and cross-repo move/transfer (repo). No-op
+     *  without an index. */
+    reassignOwnedAssets(fromType, fromId, changes) {
+        this.assetIndex?.reassignOwner(this.repoName, fromType, fromId, changes);
     }
     /**
      * List assets for an entity
@@ -870,61 +2755,34 @@ export class BaseGraphManager {
         return await this.assetService.listAll();
     }
     /**
-     * Enumerate (type, id) pairs in this repo by scanning the directory
-     * structure only — no markdown parse, no frontmatter validation. Used
-     * by endpoints (like /api/repos/:repo/assets) that need to answer
-     * "does entity X belong to this repo?" without paying the cost of
-     * parsing every file in the repo.
+     * 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.
      */
     listEntityIds() {
         if (!existsSync(this.repoPath))
             return [];
         const results = [];
-        let types = [];
-        try {
-            types = readdirSync(this.repoPath);
-        }
-        catch {
-            return [];
-        }
-        for (const entry of types) {
-            if (entry.startsWith('.'))
-                continue;
-            const typeDir = join(this.repoPath, entry);
-            try {
-                if (!statSync(typeDir).isDirectory())
-                    continue;
-            }
-            catch {
-                continue;
-            }
-            const singularType = PLURAL_TO_SINGULAR[entry];
-            if (!singularType)
-                continue;
-            let files = [];
-            try {
-                files = readdirSync(typeDir);
-            }
-            catch {
+        for (const key of this.getFileIndex().keys()) {
+            const slash = key.indexOf('/');
+            if (slash <= 0)
                 continue;
-            }
-            for (const file of files) {
-                if (file.startsWith('.') || !file.endsWith('.md'))
-                    continue;
-                const id = file.replace(/\.md$/, '');
-                results.push({ entityType: singularType, id });
-            }
+            results.push({ entityType: key.slice(0, slash), id: key.slice(slash + 1) });
         }
         return results;
     }
     /**
-     * Delete an asset
+     * 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.
      */
-    async deleteAsset(entityType, entityId, filename, keyPrefix) {
-        if (!this.assetService) {
-            throw new Error('Asset service is not configured for this graph');
-        }
-        return await this.assetService.delete(entityType, entityId, filename, keyPrefix);
+    getEntityFilePath(entityType, entityId) {
+        return this.findEntityFile(entityType, entityId);
     }
     /**
      * Delete all assets for an entity (when entity is deleted)
@@ -936,66 +2794,104 @@ export class BaseGraphManager {
         return await this.assetService.deleteAll(entityType, entityId, keyPrefix);
     }
     /**
-     * Get dataset rows, optionally filtered
+     * Resolve the authoritative CSV body for a dataset: the live editor body
+     * when one exists (the grid may be ahead of disk), else the on-disk body.
+     */
+    datasetBody(entity, entityId) {
+        return this.getLiveBody('dataset', entityId) ?? entity.document.content;
+    }
+    /**
+     * Get dataset rows, optionally filtered. Columns come from the CSV header.
      */
     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);
+        const rows = this.csvService.parseRows(this.datasetBody(entity, entityId));
         if (filter && Object.keys(filter).length > 0) {
             return this.csvService.filterRows(rows, filter);
         }
         return rows;
     }
     /**
-     * Append rows to a dataset entity
+     * Column names for a dataset, read from the CSV header. Independent of the
+     * rows so callers get the real columns even for a header-only dataset or a
+     * zero-match filter (where deriving columns from result rows would be empty).
+     */
+    getDatasetColumns(entityId) {
+        const entity = this.get('dataset', entityId);
+        if (entity.data.entity_type !== 'dataset') {
+            throw new Error(`Entity ${entityId} is not a dataset`);
+        }
+        return this.csvService.columns(this.datasetBody(entity, entityId));
+    }
+    /**
+     * Append rows to a dataset entity.
+     *
+     * The existing CSV body is preserved verbatim and the new rows are appended
+     * after it — we do NOT re-parse and re-stringify existing rows. That keeps
+     * datasets with duplicate column headers from collapsing (csv-parse's
+     * object mode keeps only the last same-named column) and avoids reformatting
+     * unrelated cells. New rows are mapped to the existing header columns; keys
+     * not in the header are dropped (query the columns first). When the body has
+     * no header yet, the columns are taken from the new rows.
+     *
+     * The write routes through `update()` so it shares the BodyWriteCoordinator
+     * contract (per-doc lock, base-hash precondition, applyAgentContent, commit)
+     * instead of writing to disk directly — same guarantees the agent's markdown
+     * writes get. `baseRevision` makes a concurrent change since our read fail
+     * loudly rather than silently back-stomp.
      */
     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`);
         }
-        const schema = entity.data.schema;
-        // Validate new rows against schema
-        const validatedRows = newRows.map(row => {
-            const stringRow = {};
+        const base = this.datasetBody(entity, entityId);
+        // Normalize incoming rows to string cells (agents may send numbers/bools).
+        const normalizedRows = newRows.map(row => {
+            const out = {};
             for (const [k, v] of Object.entries(row)) {
-                stringRow[k] = v !== null && v !== undefined ? String(v) : '';
+                out[k] = v !== null && v !== undefined ? String(v) : '';
             }
-            return this.csvService.validateRow(stringRow, schema);
+            return out;
         });
-        // 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,
+        let newContent;
+        const headerColumns = this.csvService.columns(base);
+        if (headerColumns.length === 0) {
+            // No header yet: derive columns from the new rows and write a fresh CSV.
+            const columns = [];
+            for (const row of normalizedRows) {
+                for (const key of Object.keys(row)) {
+                    if (!columns.includes(key))
+                        columns.push(key);
+                }
+            }
+            newContent = this.csvService.stringifyRows(normalizedRows, columns);
+        }
+        else {
+            // Preserve the existing body byte-for-byte; append only the new rows.
+            const appended = this.csvService.stringifyRows(normalizedRows, headerColumns, false);
+            const baseTrimmed = base.replace(/\n+$/, '');
+            newContent = appended ? `${baseTrimmed}\n${appended}` : `${baseTrimmed}\n`;
+        }
+        return this.update({
+            entityType: 'dataset',
+            entityId,
             content: newContent,
-            wikilinks: this.markdownService.extractWikilinks(newContent, updatedData),
+            source: 'server-write',
+            // Precondition is checked against DISK inside the coordinator's lock, so
+            // baseRevision must be the DISK hash — not `base`, which is the LIVE body
+            // (datasetBody prefers the live ytext). When the CSV editor has unsaved
+            // edits the live body is ahead of disk; hashing it here would always
+            // mismatch the disk check and throw StaleBaseRevisionError (masked today
+            // by the live-typing gate, exposed once that gate is removed). The
+            // appended `newContent` still derives from the live body, so live edits
+            // are preserved; applyAgentContent then merges the rows into the editor.
+            baseRevision: sha256OfBody(entity.document.content),
+            commitMessage: commitMessage || `Append ${normalizedRows.length} row(s) to dataset: ${entityId}`,
         });
-        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 this.get('dataset', entityId);
     }
     /**
      * Get repository status