@ncukondo/reference-manager 0.14.1 → 0.15.1

package/dist/chunks/{index-CXoDLO8W.js → index-B4RmLBI1.js}

@@ -1,23 +1,23 @@
 import { Command } from "commander";
-import { L as Library, p as pickDefined, q as sortOrderSchema, r as paginationOptionsSchema, F as FileWatcher, u as sortFieldSchema, v as searchSortFieldSchema } from "./file-watcher-D2Y-SlcE.js";
+import { L as Library, p as pickDefined, a as sortOrderSchema, v as paginationOptionsSchema, F as FileWatcher, b as sortFieldSchema, u as searchSortFieldSchema } from "./file-watcher-B_WpVHSV.js";
 import * as fs from "node:fs";
 import { promises, readFileSync, existsSync, writeFileSync, mkdirSync, mkdtempSync } from "node:fs";
 import * as os from "node:os";
 import { tmpdir } from "node:os";
 import * as path from "node:path";
-import { join, dirname, extname } from "node:path";
+import path__default, { extname, join, basename, dirname } from "node:path";
+import fs__default, { stat, rename, copyFile, readFile, unlink, readdir, mkdir, rm } from "node:fs/promises";
+import { g as getExtension, i as isValidFulltextFiles, a as isReservedRole, F as FULLTEXT_ROLE, b as formatToExtension, c as findFulltextFiles, d as findFulltextFile, e as extensionToFormat, B as BUILTIN_STYLES, h as getFulltextAttachmentTypes, s as startServerWithFileWatcher } from "./index-DHgeuWGP.js";
+import { o as openWithSystemApp, l as loadConfig, e as getDefaultCurrentDirConfigFilename, h as getDefaultUserConfigPath } from "./loader-DStZe-OB.js";
 import { spawn, spawnSync } from "node:child_process";
 import process$1, { stdin, stdout } from "node:process";
-import { l as loadConfig, e as getDefaultCurrentDirConfigFilename, h as getDefaultUserConfigPath, o as openWithSystemApp } from "./loader-C1EpnyPm.js";
-import { mkdir, unlink, rename, copyFile, rm, readFile } from "node:fs/promises";
 import { parse as parse$2, stringify as stringify$2 } from "@iarna/toml";
-import { u as updateReference, B as BUILTIN_STYLES, g as getFulltextAttachmentTypes, s as startServerWithFileWatcher } from "./index-DapYyqAC.js";
 import "@citation-js/core";
 import "@citation-js/plugin-csl";
 import { ZodOptional as ZodOptional$2, z } from "zod";
 import { serve } from "@hono/node-server";
 const name = "@ncukondo/reference-manager";
-const version$1 = "0.14.1";
+const version$1 = "0.15.1";
 const description$1 = "A local reference management tool using CSL-JSON as the single source of truth";
 const packageJson = {
   name,
@@ -261,6 +261,598 @@ function getExitCode(result) {
   }
   return 0;
 }
+function normalizePathForOutput(p) {
+  return p.replace(/\\/g, "/");
+}
+function extractUuidPrefix(uuid2) {
+  const normalized = uuid2.replace(/-/g, "");
+  return normalized.slice(0, 8);
+}
+function generateDirectoryName(ref2) {
+  const uuid2 = ref2.custom?.uuid;
+  if (!uuid2) {
+    throw new Error("Reference must have custom.uuid");
+  }
+  const uuidPrefix = extractUuidPrefix(uuid2);
+  const pmid = ref2.PMID?.trim();
+  if (pmid) {
+    return `${ref2.id}-PMID${pmid}-${uuidPrefix}`;
+  }
+  return `${ref2.id}-${uuidPrefix}`;
+}
+function getDirectoryPath(ref2, baseDir) {
+  const existingDir = ref2.custom?.attachments?.directory;
+  if (existingDir) {
+    return normalizePathForOutput(path__default.join(baseDir, existingDir));
+  }
+  const dirName = generateDirectoryName(ref2);
+  return normalizePathForOutput(path__default.join(baseDir, dirName));
+}
+async function ensureDirectory(ref2, baseDir) {
+  const dirPath = getDirectoryPath(ref2, baseDir);
+  try {
+    await fs__default.mkdir(dirPath, { recursive: true });
+  } catch (error) {
+    if (error.code !== "EEXIST") {
+      throw error;
+    }
+  }
+  return dirPath;
+}
+async function deleteDirectoryIfEmpty(dirPath) {
+  try {
+    const files = await fs__default.readdir(dirPath);
+    if (files.length === 0) {
+      await fs__default.rmdir(dirPath);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+function slugifyLabel(label) {
+  return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+function generateFilename(role, ext, label) {
+  if (label) {
+    const slug = slugifyLabel(label);
+    return `${role}-${slug}.${ext}`;
+  }
+  return `${role}.${ext}`;
+}
+function parseFilename(filename) {
+  if (!filename) {
+    return null;
+  }
+  const ext = path__default.extname(filename);
+  const extWithoutDot = ext.startsWith(".") ? ext.slice(1) : ext;
+  const basename2 = ext ? filename.slice(0, -ext.length) : filename;
+  const firstHyphenIndex = basename2.indexOf("-");
+  if (firstHyphenIndex === -1) {
+    return {
+      role: basename2,
+      ext: extWithoutDot
+    };
+  }
+  const role = basename2.slice(0, firstHyphenIndex);
+  const label = basename2.slice(firstHyphenIndex + 1);
+  if (label) {
+    return {
+      role,
+      ext: extWithoutDot,
+      label
+    };
+  }
+  return {
+    role,
+    ext: extWithoutDot
+  };
+}
+async function checkSourceFile(filePath) {
+  try {
+    await stat(filePath);
+    return null;
+  } catch {
+    return `Source file not found: ${filePath}`;
+  }
+}
+function validateFulltextConstraint(existingFiles, newFile) {
+  if (newFile.role !== "fulltext") {
+    return null;
+  }
+  const newExt = getExtension(newFile.filename);
+  const existingFulltexts = existingFiles.filter((f) => f.role === "fulltext");
+  for (const existing of existingFulltexts) {
+    const existingExt = getExtension(existing.filename);
+    if (existingExt === newExt) {
+      return `A fulltext ${newExt.toUpperCase()} already exists. Use --force to overwrite.`;
+    }
+  }
+  const testFiles = [...existingFiles, newFile];
+  if (!isValidFulltextFiles(testFiles)) {
+    return "fulltext role allows max 2 files (1 PDF + 1 Markdown)";
+  }
+  return null;
+}
+function findExistingFile(files, filename) {
+  return files.find((f) => f.filename === filename);
+}
+async function copyOrMoveFile(sourcePath, destPath, move) {
+  try {
+    if (move) {
+      await rename(sourcePath, destPath);
+    } else {
+      await copyFile(sourcePath, destPath);
+    }
+    return null;
+  } catch (error) {
+    return `Failed to ${move ? "move" : "copy"} file: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+async function updateAttachmentMetadata$1(library, item, updatedAttachments) {
+  await library.update(item.id, {
+    custom: {
+      ...item.custom,
+      attachments: updatedAttachments
+    }
+  });
+}
+function buildUpdatedFiles$1(existingFiles, newFile, existingFile) {
+  if (existingFile) {
+    return existingFiles.map((f) => f.filename === newFile.filename ? newFile : f);
+  }
+  return [...existingFiles, newFile];
+}
+async function addAttachment(library, options) {
+  const {
+    identifier,
+    filePath,
+    role,
+    label,
+    move = false,
+    force = false,
+    idType = "id",
+    attachmentsDirectory
+  } = options;
+  const item = await library.find(identifier, { idType });
+  if (!item) {
+    return { success: false, error: `Reference '${identifier}' not found` };
+  }
+  const uuid2 = item.custom?.uuid;
+  if (!uuid2) {
+    return { success: false, error: "Reference has no UUID. Cannot create attachment directory." };
+  }
+  const sourceError = await checkSourceFile(filePath);
+  if (sourceError) {
+    return { success: false, error: sourceError };
+  }
+  const ext = extname(filePath).slice(1).toLowerCase();
+  const filename = generateFilename(role, ext, label);
+  const existingAttachments = item.custom?.attachments;
+  const existingFiles = existingAttachments?.files ?? [];
+  const newFile = {
+    filename,
+    role,
+    ...label && { label }
+  };
+  const existingFile = findExistingFile(existingFiles, filename);
+  if (!existingFile || !force) {
+    const constraintError = validateFulltextConstraint(existingFiles, newFile);
+    if (constraintError) {
+      return { success: false, error: constraintError };
+    }
+  }
+  if (existingFile && !force) {
+    return {
+      success: false,
+      existingFile: filename,
+      requiresConfirmation: true
+    };
+  }
+  const ref2 = item;
+  const dirPath = await ensureDirectory(ref2, attachmentsDirectory);
+  const dirName = existingAttachments?.directory ?? generateDirectoryName(ref2);
+  const destPath = join(dirPath, filename);
+  const copyError = await copyOrMoveFile(filePath, destPath, move);
+  if (copyError) {
+    return { success: false, error: copyError };
+  }
+  const updatedFiles = buildUpdatedFiles$1(existingFiles, newFile, existingFile);
+  const updatedAttachments = {
+    directory: dirName,
+    files: updatedFiles
+  };
+  await updateAttachmentMetadata$1(library, item, updatedAttachments);
+  await library.save();
+  return {
+    success: true,
+    filename,
+    directory: dirName,
+    overwritten: !!existingFile
+  };
+}
+async function listAttachments(library, options) {
+  const { identifier, idType = "id", role } = options;
+  const item = await library.find(identifier, { idType });
+  if (!item) {
+    return { success: false, files: [], error: `Reference '${identifier}' not found` };
+  }
+  const attachments = item.custom?.attachments;
+  if (!attachments || attachments.files.length === 0) {
+    return { success: false, files: [], error: `No attachments for reference '${identifier}'` };
+  }
+  let files = attachments.files;
+  if (role) {
+    files = files.filter((f) => f.role === role);
+    if (files.length === 0) {
+      return {
+        success: false,
+        files: [],
+        error: `No ${role} attachments for reference '${identifier}'`
+      };
+    }
+  }
+  return {
+    success: true,
+    directory: attachments.directory,
+    files
+  };
+}
+function findAttachment(files, filename, role) {
+  if (filename) {
+    return files.find((f) => f.filename === filename);
+  }
+  if (role) {
+    return files.find((f) => f.role === role);
+  }
+  return void 0;
+}
+async function getAttachment(library, options) {
+  const {
+    identifier,
+    filename,
+    role,
+    idType = "id",
+    stdout: stdout2 = false,
+    attachmentsDirectory
+  } = options;
+  const item = await library.find(identifier, { idType });
+  if (!item) {
+    return { success: false, error: `Reference '${identifier}' not found` };
+  }
+  const attachments = item.custom?.attachments;
+  if (!attachments || attachments.files.length === 0) {
+    return { success: false, error: `No attachments for reference '${identifier}'` };
+  }
+  const attachment = findAttachment(attachments.files, filename, role);
+  if (!attachment) {
+    if (filename) {
+      return { success: false, error: `Attachment '${filename}' not found` };
+    }
+    if (role) {
+      return { success: false, error: `No ${role} attachment found` };
+    }
+    return { success: false, error: "No filename or role specified" };
+  }
+  const filePath = join(attachmentsDirectory, attachments.directory, attachment.filename);
+  const normalizedPath = normalizePathForOutput(filePath);
+  if (stdout2) {
+    try {
+      const content = await readFile(filePath);
+      return { success: true, path: normalizedPath, content };
+    } catch {
+      return {
+        success: false,
+        error: `File not found on disk: ${normalizedPath}`
+      };
+    }
+  }
+  return { success: true, path: normalizedPath };
+}
+function findFilesToDetach(files, filename, role, all) {
+  if (filename) {
+    const file = files.find((f) => f.filename === filename);
+    return file ? [file] : [];
+  }
+  if (role && all) {
+    return files.filter((f) => f.role === role);
+  }
+  return [];
+}
+async function deleteFiles(dirPath, filenames) {
+  const deleted = [];
+  for (const filename of filenames) {
+    try {
+      await unlink(join(dirPath, filename));
+      deleted.push(filename);
+    } catch {
+    }
+  }
+  return deleted;
+}
+async function updateMetadata(library, item, attachments, remainingFiles) {
+  const updatedAttachments = remainingFiles.length > 0 ? { directory: attachments.directory, files: remainingFiles } : void 0;
+  await library.update(item.id, {
+    custom: {
+      ...item.custom,
+      attachments: updatedAttachments
+    }
+  });
+}
+async function tryDeleteEmptyDirectory(dirPath) {
+  try {
+    await deleteDirectoryIfEmpty(dirPath);
+    try {
+      await stat(dirPath);
+      return false;
+    } catch {
+      return true;
+    }
+  } catch {
+    return false;
+  }
+}
+function errorResult$1(error) {
+  return { success: false, detached: [], deleted: [], error };
+}
+async function detachAttachment(library, options) {
+  const {
+    identifier,
+    filename,
+    role,
+    all = false,
+    removeFiles = false,
+    idType = "id",
+    attachmentsDirectory
+  } = options;
+  if (!filename && !role) {
+    return errorResult$1("Either filename or role must be specified");
+  }
+  const item = await library.find(identifier, { idType });
+  if (!item) {
+    return errorResult$1(`Reference '${identifier}' not found`);
+  }
+  const attachments = item.custom?.attachments;
+  if (!attachments || attachments.files.length === 0) {
+    return errorResult$1(`No attachments for reference '${identifier}'`);
+  }
+  const filesToDetach = findFilesToDetach(attachments.files, filename, role, all);
+  if (filesToDetach.length === 0) {
+    if (filename) {
+      return errorResult$1(`Attachment '${filename}' not found`);
+    }
+    return errorResult$1(`No ${role} attachments found`);
+  }
+  const detachedFilenames = filesToDetach.map((f) => f.filename);
+  const dirPath = join(attachmentsDirectory, attachments.directory);
+  const deletedFiles = removeFiles ? await deleteFiles(dirPath, detachedFilenames) : [];
+  const remainingFiles = attachments.files.filter((f) => !detachedFilenames.includes(f.filename));
+  await updateMetadata(library, item, attachments, remainingFiles);
+  await library.save();
+  const directoryDeleted = removeFiles && remainingFiles.length === 0 ? await tryDeleteEmptyDirectory(dirPath) : false;
+  return {
+    success: true,
+    detached: detachedFilenames,
+    deleted: deletedFiles,
+    directoryDeleted
+  };
+}
+function errorResult(error) {
+  return { success: false, newFiles: [], missingFiles: [], applied: false, error };
+}
+function inferFromFilename(filename) {
+  const parsed = parseFilename(filename);
+  if (!parsed) {
+    return { filename, role: "other", label: filename };
+  }
+  const { role, label } = parsed;
+  if (isReservedRole(role)) {
+    return label ? { filename, role, label } : { filename, role };
+  }
+  const basename2 = label ? `${role}-${label}` : role;
+  return { filename, role: "other", label: basename2 };
+}
+async function getFilesOnDisk(dirPath) {
+  try {
+    const entries = await readdir(dirPath);
+    const files = [];
+    for (const entry of entries) {
+      const entryPath = join(dirPath, entry);
+      const stats = await stat(entryPath);
+      if (stats.isFile()) {
+        files.push(entry);
+      }
+    }
+    return files;
+  } catch {
+    return [];
+  }
+}
+async function directoryExists(dirPath) {
+  try {
+    const stats = await stat(dirPath);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+function findNewFiles(diskFiles, metadataFilenames) {
+  return diskFiles.filter((f) => !metadataFilenames.has(f)).map(inferFromFilename);
+}
+function findMissingFiles(metadataFiles, diskFilenames) {
+  return metadataFiles.filter((f) => !diskFilenames.has(f.filename)).map((f) => f.filename);
+}
+function buildUpdatedFiles(metadataFiles, newFiles, missingFiles, shouldApplyNew, shouldApplyFix) {
+  let updatedFiles = [...metadataFiles];
+  if (shouldApplyNew) {
+    for (const newFile of newFiles) {
+      const attachmentFile = {
+        filename: newFile.filename,
+        role: newFile.role,
+        ...newFile.label && { label: newFile.label }
+      };
+      updatedFiles.push(attachmentFile);
+    }
+  }
+  if (shouldApplyFix) {
+    const missingSet = new Set(missingFiles);
+    updatedFiles = updatedFiles.filter((f) => !missingSet.has(f.filename));
+  }
+  return updatedFiles;
+}
+async function updateAttachmentMetadata(library, item, attachments, updatedFiles) {
+  await library.update(item.id, {
+    custom: {
+      ...item.custom,
+      attachments: {
+        ...attachments,
+        files: updatedFiles
+      }
+    }
+  });
+}
+async function syncAttachments(library, options) {
+  const { identifier, yes = false, fix = false, idType = "id", attachmentsDirectory } = options;
+  const item = await library.find(identifier, { idType });
+  if (!item) {
+    return errorResult(`Reference '${identifier}' not found`);
+  }
+  const attachments = item.custom?.attachments;
+  if (!attachments?.directory) {
+    return errorResult(`No attachments for reference: ${identifier}`);
+  }
+  const dirPath = join(attachmentsDirectory, attachments.directory);
+  if (!await directoryExists(dirPath)) {
+    return errorResult(`Attachments directory does not exist: ${attachments.directory}`);
+  }
+  const metadataFiles = attachments.files || [];
+  const metadataFilenames = new Set(metadataFiles.map((f) => f.filename));
+  const diskFiles = await getFilesOnDisk(dirPath);
+  const diskFilenames = new Set(diskFiles);
+  const newFiles = findNewFiles(diskFiles, metadataFilenames);
+  const missingFiles = findMissingFiles(metadataFiles, diskFilenames);
+  const shouldApplyNew = yes && newFiles.length > 0;
+  const shouldApplyFix = fix && missingFiles.length > 0;
+  const shouldApply = shouldApplyNew || shouldApplyFix;
+  if (shouldApply) {
+    const updatedFiles = buildUpdatedFiles(
+      metadataFiles,
+      newFiles,
+      missingFiles,
+      shouldApplyNew,
+      shouldApplyFix
+    );
+    await updateAttachmentMetadata(library, item, attachments, updatedFiles);
+    await library.save();
+  }
+  return { success: true, newFiles, missingFiles, applied: shouldApply };
+}
+async function pathExists(path2) {
+  try {
+    await stat(path2);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function findFileByRole(attachments, role) {
+  if (!attachments?.files) {
+    return null;
+  }
+  const file = attachments.files.find((f) => f.role === role);
+  return file?.filename ?? null;
+}
+async function resolveDirectory(ref2, attachmentsDirectory) {
+  const attachments = ref2.custom?.attachments;
+  let dirPath;
+  let directoryCreated = false;
+  if (attachments?.directory) {
+    dirPath = join(attachmentsDirectory, attachments.directory);
+  } else {
+    dirPath = await ensureDirectory(ref2, attachmentsDirectory);
+    directoryCreated = true;
+  }
+  if (!await pathExists(dirPath)) {
+    dirPath = await ensureDirectory(ref2, attachmentsDirectory);
+    directoryCreated = true;
+  }
+  return { dirPath, directoryCreated };
+}
+async function updateDirectoryMetadata(library, ref2, dirPath) {
+  const dirName = basename(dirPath);
+  const item = ref2;
+  await library.update(ref2.id, {
+    custom: {
+      ...item.custom,
+      attachments: {
+        directory: dirName,
+        files: []
+      }
+    }
+  });
+  await library.save();
+}
+async function resolveTargetPath(dirPath, filename, role, attachments) {
+  if (filename) {
+    const targetPath = join(dirPath, filename);
+    if (!await pathExists(targetPath)) {
+      return { error: `Attachment file not found: ${filename}` };
+    }
+    return { path: targetPath };
+  }
+  if (role) {
+    const foundFilename = findFileByRole(attachments, role);
+    if (!foundFilename) {
+      return { error: `No ${role} attachment found` };
+    }
+    const targetPath = join(dirPath, foundFilename);
+    if (!await pathExists(targetPath)) {
+      return { error: `Attachment file not found: ${foundFilename}` };
+    }
+    return { path: targetPath };
+  }
+  return { path: dirPath };
+}
+async function openAttachment(library, options) {
+  const {
+    identifier,
+    filename,
+    role,
+    print = false,
+    idType = "id",
+    attachmentsDirectory
+  } = options;
+  const item = await library.find(identifier, { idType });
+  if (!item) {
+    return { success: false, error: `Reference '${identifier}' not found` };
+  }
+  const ref2 = item;
+  if (!ref2.custom?.uuid) {
+    return {
+      success: false,
+      error: "Reference has no UUID. Cannot determine attachment directory."
+    };
+  }
+  const attachments = ref2.custom?.attachments;
+  const { dirPath, directoryCreated } = await resolveDirectory(ref2, attachmentsDirectory);
+  if (directoryCreated && !attachments?.directory) {
+    await updateDirectoryMetadata(library, ref2, dirPath);
+  }
+  const targetResult = await resolveTargetPath(dirPath, filename, role, attachments);
+  if ("error" in targetResult) {
+    return { success: false, error: targetResult.error };
+  }
+  if (!print) {
+    await openWithSystemApp(targetResult.path);
+  }
+  return {
+    success: true,
+    // Normalize for output (forward slashes for cross-platform consistency)
+    path: normalizePathForOutput(targetResult.path),
+    directoryCreated
+  };
+}
 class OperationsLibrary {
   constructor(library, citationConfig) {
     this.library = library;
@@ -287,15 +879,15 @@ class OperationsLibrary {
   }
   // High-level operations
   async search(options) {
-    const { searchReferences } = await import("./index-DapYyqAC.js").then((n) => n.d);
+    const { searchReferences } = await import("./index-DHgeuWGP.js").then((n) => n.n);
     return searchReferences(this.library, options);
   }
   async list(options) {
-    const { listReferences } = await import("./index-DapYyqAC.js").then((n) => n.l);
+    const { listReferences } = await import("./index-DHgeuWGP.js").then((n) => n.m);
     return listReferences(this.library, options ?? {});
   }
   async cite(options) {
-    const { citeReferences } = await import("./index-DapYyqAC.js").then((n) => n.b);
+    const { citeReferences } = await import("./index-DHgeuWGP.js").then((n) => n.l);
     const defaultStyle = options.defaultStyle ?? this.citationConfig?.defaultStyle;
     const cslDirectory = options.cslDirectory ?? this.citationConfig?.cslDirectory;
     const mergedOptions = {
@@ -306,9 +898,34 @@ class OperationsLibrary {
     return citeReferences(this.library, mergedOptions);
   }
   async import(inputs, options) {
-    const { addReferences } = await import("./index-DapYyqAC.js").then((n) => n.a);
+    const { addReferences } = await import("./index-DHgeuWGP.js").then((n) => n.k);
     return addReferences(inputs, this.library, options ?? {});
   }
+  // Attachment operations
+  async attachAdd(options) {
+    const { addAttachment: addAttachment2 } = await import("./index-DEd6F5Rr.js");
+    return addAttachment2(this.library, options);
+  }
+  async attachList(options) {
+    const { listAttachments: listAttachments2 } = await import("./index-DEd6F5Rr.js");
+    return listAttachments2(this.library, options);
+  }
+  async attachGet(options) {
+    const { getAttachment: getAttachment2 } = await import("./index-DEd6F5Rr.js");
+    return getAttachment2(this.library, options);
+  }
+  async attachDetach(options) {
+    const { detachAttachment: detachAttachment2 } = await import("./index-DEd6F5Rr.js");
+    return detachAttachment2(this.library, options);
+  }
+  async attachSync(options) {
+    const { syncAttachments: syncAttachments2 } = await import("./index-DEd6F5Rr.js");
+    return syncAttachments2(this.library, options);
+  }
+  async attachOpen(options) {
+    const { openAttachment: openAttachment2 } = await import("./index-DEd6F5Rr.js");
+    return openAttachment2(this.library, options);
+  }
 }
 class ServerClient {
   constructor(baseUrl) {
@@ -495,20 +1112,125 @@ class ServerClient {
     }
     return await response.json();
   }
-}
-async function getServerConnection(libraryPath, config2) {
-  const portfilePath = getPortfilePath();
-  const portfileData = await readPortfile(portfilePath);
-  if (!portfileData) {
-    if (config2.server.autoStart) {
-      await startServerDaemon$1(libraryPath);
-      await waitForPortfile(5e3);
-      return await getServerConnection(libraryPath, config2);
+  // ─────────────────────────────────────────────────────────────────────────
+  // Attachment operations
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Add attachment to a reference.
+   * @param options - Add attachment options
+   * @returns Result of the add operation
+   */
+  async attachAdd(options) {
+    const url = `${this.baseUrl}/api/attachments/add`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    if (!response.ok) {
+      throw new Error(await response.text());
     }
-    return null;
+    return await response.json();
   }
-  if (!isProcessRunning(portfileData.pid)) {
-    await removePortfile(portfilePath);
+  /**
+   * List attachments for a reference.
+   * @param options - List attachments options
+   * @returns List of attachments
+   */
+  async attachList(options) {
+    const url = `${this.baseUrl}/api/attachments/list`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+    return await response.json();
+  }
+  /**
+   * Get attachment file path or content.
+   * @param options - Get attachment options
+   * @returns Attachment file path or content
+   */
+  async attachGet(options) {
+    const url = `${this.baseUrl}/api/attachments/get`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+    return await response.json();
+  }
+  /**
+   * Detach attachment from a reference.
+   * @param options - Detach attachment options
+   * @returns Result of the detach operation
+   */
+  async attachDetach(options) {
+    const url = `${this.baseUrl}/api/attachments/detach`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+    return await response.json();
+  }
+  /**
+   * Sync attachments with files on disk.
+   * @param options - Sync attachment options
+   * @returns Sync result
+   */
+  async attachSync(options) {
+    const url = `${this.baseUrl}/api/attachments/sync`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+    return await response.json();
+  }
+  /**
+   * Open attachment directory or file.
+   * @param options - Open attachment options
+   * @returns Result of the open operation
+   */
+  async attachOpen(options) {
+    const url = `${this.baseUrl}/api/attachments/open`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+    return await response.json();
+  }
+}
+async function getServerConnection(libraryPath, config2) {
+  const portfilePath = getPortfilePath();
+  const portfileData = await readPortfile(portfilePath);
+  if (!portfileData) {
+    if (config2.server.autoStart) {
+      await startServerDaemon$1(libraryPath);
+      await waitForPortfile(5e3);
+      return await getServerConnection(libraryPath, config2);
+    }
+    return null;
+  }
+  if (!isProcessRunning(portfileData.pid)) {
+    await removePortfile(portfilePath);
     return null;
   }
   if (!portfileData.library || portfileData.library !== libraryPath) {
@@ -615,47 +1337,566 @@ async function readIdentifiersFromStdin() {
   if (!content) {
     return [];
   }
-  return content.split(/[\s\n]+/).filter((id2) => id2.length > 0);
-}
-async function readIdentifierFromStdin() {
-  const content = await readStdinContent();
-  const firstLine = content.split("\n")[0]?.trim();
-  return firstLine || void 0;
+  return content.split(/[\s\n]+/).filter((id2) => id2.length > 0);
+}
+async function readIdentifierFromStdin() {
+  const content = await readStdinContent();
+  const firstLine = content.split("\n")[0]?.trim();
+  return firstLine || void 0;
+}
+async function readConfirmation(prompt) {
+  if (!isTTY()) {
+    return true;
+  }
+  const enquirer = await import("enquirer");
+  const Confirm = enquirer.default.Confirm;
+  const confirmPrompt = new Confirm({
+    name: "confirm",
+    message: prompt,
+    initial: false
+  });
+  try {
+    return await confirmPrompt.run();
+  } catch {
+    return false;
+  }
+}
+async function readStdinContent() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8").trim();
+}
+async function readStdinBuffer() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+const ExitCode = {
+  /** Success */
+  SUCCESS: 0,
+  /** General error (e.g., not found, validation failed) */
+  ERROR: 1,
+  /** Internal/unexpected error */
+  INTERNAL_ERROR: 4,
+  /** Interrupted by SIGINT */
+  SIGINT: 130
+};
+function setExitCode(code2) {
+  process.exitCode = code2;
+}
+function exitWithError(message, code2 = ExitCode.ERROR) {
+  process.stderr.write(`Error: ${message}
+`);
+  setExitCode(code2);
+}
+async function executeAttachOpen(options, context) {
+  const operationOptions = {
+    identifier: options.identifier,
+    attachmentsDirectory: options.attachmentsDirectory,
+    ...options.filename !== void 0 && { filename: options.filename },
+    ...options.role !== void 0 && { role: options.role },
+    ...options.print !== void 0 && { print: options.print },
+    ...options.idType !== void 0 && { idType: options.idType }
+  };
+  return openAttachment(context.library, operationOptions);
+}
+async function executeAttachAdd(options, context) {
+  const operationOptions = {
+    identifier: options.identifier,
+    filePath: options.filePath,
+    role: options.role,
+    attachmentsDirectory: options.attachmentsDirectory,
+    ...options.label !== void 0 && { label: options.label },
+    ...options.move !== void 0 && { move: options.move },
+    ...options.force !== void 0 && { force: options.force },
+    ...options.idType !== void 0 && { idType: options.idType }
+  };
+  return addAttachment(context.library, operationOptions);
+}
+async function executeAttachList(options, context) {
+  const operationOptions = {
+    identifier: options.identifier,
+    ...options.role !== void 0 && { role: options.role },
+    ...options.idType !== void 0 && { idType: options.idType }
+  };
+  return listAttachments(context.library, operationOptions);
+}
+async function executeAttachGet(options, context) {
+  const operationOptions = {
+    identifier: options.identifier,
+    attachmentsDirectory: options.attachmentsDirectory,
+    ...options.filename !== void 0 && { filename: options.filename },
+    ...options.role !== void 0 && { role: options.role },
+    ...options.stdout !== void 0 && { stdout: options.stdout },
+    ...options.idType !== void 0 && { idType: options.idType }
+  };
+  return getAttachment(context.library, operationOptions);
+}
+async function executeAttachDetach(options, context) {
+  const operationOptions = {
+    identifier: options.identifier,
+    attachmentsDirectory: options.attachmentsDirectory,
+    ...options.filename !== void 0 && { filename: options.filename },
+    ...options.role !== void 0 && { role: options.role },
+    ...options.all !== void 0 && { all: options.all },
+    ...options.removeFiles !== void 0 && { removeFiles: options.removeFiles },
+    ...options.idType !== void 0 && { idType: options.idType }
+  };
+  return detachAttachment(context.library, operationOptions);
+}
+async function executeAttachSync(options, context) {
+  const operationOptions = {
+    identifier: options.identifier,
+    attachmentsDirectory: options.attachmentsDirectory,
+    ...options.yes !== void 0 && { yes: options.yes },
+    ...options.fix !== void 0 && { fix: options.fix },
+    ...options.idType !== void 0 && { idType: options.idType }
+  };
+  return syncAttachments(context.library, operationOptions);
+}
+function formatAttachOpenOutput(result) {
+  if (!result.success) {
+    return `Error: ${result.error}`;
+  }
+  if (result.directoryCreated) {
+    return `Created and opened: ${result.path}`;
+  }
+  return `Opened: ${result.path}`;
+}
+function formatAttachAddOutput(result) {
+  if (result.requiresConfirmation) {
+    return `File already exists: ${result.existingFile}
+Use --force to overwrite.`;
+  }
+  if (!result.success) {
+    return `Error: ${result.error}`;
+  }
+  if (result.overwritten) {
+    return `Added (overwritten): ${result.filename}`;
+  }
+  return `Added: ${result.filename}`;
+}
+function formatAttachListOutput(result, identifier) {
+  if (!result.success) {
+    return `Error: ${result.error}`;
+  }
+  if (result.files.length === 0) {
+    return `No attachments for reference: ${identifier}`;
+  }
+  const grouped = /* @__PURE__ */ new Map();
+  for (const file of result.files) {
+    const existing = grouped.get(file.role) ?? [];
+    existing.push(file);
+    grouped.set(file.role, existing);
+  }
+  const lines = [];
+  lines.push(`Attachments for ${identifier} (${result.directory}/):`);
+  lines.push("");
+  for (const [role, files] of grouped) {
+    lines.push(`${role}:`);
+    for (const file of files) {
+      if (file.label) {
+        lines.push(`  ${file.filename} - "${file.label}"`);
+      } else {
+        lines.push(`  ${file.filename}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+function formatAttachDetachOutput(result) {
+  if (!result.success) {
+    return `Error: ${result.error}`;
+  }
+  const lines = [];
+  for (const filename of result.detached) {
+    if (result.deleted.includes(filename)) {
+      lines.push(`Detached and deleted: ${filename}`);
+    } else {
+      lines.push(`Detached: ${filename}`);
+    }
+  }
+  if (result.directoryDeleted) {
+    lines.push("Directory removed.");
+  }
+  return lines.join("\n");
+}
+function pluralize(count, singular) {
+  return count > 1 ? `${singular}s` : singular;
+}
+function formatNewFilesSection(result, lines) {
+  const count = result.newFiles.length;
+  if (count === 0) return;
+  const verb = result.applied ? "Added" : "Found";
+  const suffix = result.applied ? "" : " new";
+  lines.push(`${verb} ${count}${suffix} ${pluralize(count, "file")}:`);
+  for (const file of result.newFiles) {
+    const labelPart = file.label ? `, label: "${file.label}"` : "";
+    lines.push(`  ${file.filename} → role: ${file.role}${labelPart}`);
+  }
+  lines.push("");
+}
+function formatMissingFilesSection(result, lines) {
+  const count = result.missingFiles.length;
+  if (count === 0) return;
+  const header = result.applied ? `Removed ${count} missing ${pluralize(count, "file")} from metadata:` : `Missing ${count} ${pluralize(count, "file")} (in metadata but not on disk):`;
+  lines.push(header);
+  for (const filename of result.missingFiles) {
+    lines.push(`  ${filename}`);
+  }
+  lines.push("");
+}
+function formatAttachSyncOutput(result) {
+  if (!result.success) {
+    return `Error: ${result.error}`;
+  }
+  const hasNewFiles = result.newFiles.length > 0;
+  const hasMissingFiles = result.missingFiles.length > 0;
+  if (!hasNewFiles && !hasMissingFiles) {
+    return "Already in sync.";
+  }
+  const lines = [];
+  formatNewFilesSection(result, lines);
+  formatMissingFilesSection(result, lines);
+  if (result.applied) {
+    lines.push("Changes applied.");
+  } else {
+    lines.push("");
+    lines.push("(dry-run: no changes made)");
+    if (hasNewFiles) {
+      lines.push("Run with --yes to add new files");
+    }
+    if (hasMissingFiles) {
+      lines.push("Run with --fix to remove missing files from metadata");
+    }
+  }
+  return lines.join("\n").trimEnd();
+}
+function getAttachExitCode(result) {
+  return result.success ? 0 : 1;
+}
+async function executeInteractiveSelect$1(context, config2) {
+  const { selectReferencesOrExit } = await import("./reference-select-B9w9CLa1.js");
+  const allReferences = await context.library.getAll();
+  const identifiers = await selectReferencesOrExit(
+    allReferences,
+    { multiSelect: false },
+    config2.cli.tui
+  );
+  return identifiers[0];
+}
+async function resolveIdentifier(identifierArg, context, config2) {
+  if (identifierArg) {
+    return identifierArg;
+  }
+  if (isTTY()) {
+    return executeInteractiveSelect$1(context, config2);
+  }
+  const stdinId = await readIdentifierFromStdin();
+  if (!stdinId) {
+    process.stderr.write(
+      "Error: No identifier provided. Provide an ID, pipe one via stdin, or run interactively in a TTY.\n"
+    );
+    setExitCode(ExitCode.ERROR);
+    return "";
+  }
+  return stdinId;
+}
+function displayNamingConvention(identifier, dirPath) {
+  process.stderr.write(`
+Opening attachments directory for ${identifier}...
+
+`);
+  process.stderr.write("File naming convention:\n");
+  process.stderr.write("  fulltext.pdf / fulltext.md    - Paper body\n");
+  process.stderr.write("  supplement-{label}.ext        - Supplementary materials\n");
+  process.stderr.write("  notes-{label}.ext             - Your notes\n");
+  process.stderr.write("  draft-{label}.ext             - Draft versions\n");
+  process.stderr.write("  {custom}-{label}.ext          - Custom role\n\n");
+  process.stderr.write(`Directory: ${dirPath}/
+
+`);
+}
+async function waitForEnter() {
+  return new Promise((resolve2) => {
+    process.stderr.write("Press Enter when done editing...");
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.once("data", () => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stderr.write("\n\n");
+      resolve2();
+    });
+  });
+}
+function displayInteractiveSyncResult(result, identifier) {
+  if (result.newFiles.length === 0) {
+    process.stderr.write("No new files detected.\n");
+    return;
+  }
+  process.stderr.write("Scanning directory...\n\n");
+  process.stderr.write(
+    `Found ${result.newFiles.length} new file${result.newFiles.length > 1 ? "s" : ""}:
+`
+  );
+  for (const file of result.newFiles) {
+    const labelPart = file.label ? `, label: "${file.label}"` : "";
+    process.stderr.write(`  ✓ ${file.filename} → role: ${file.role}${labelPart}
+`);
+  }
+  process.stderr.write(`
+Updated metadata for ${identifier}.
+`);
+}
+async function runInteractiveMode(identifier, dirPath, attachmentsDirectory, idType, context) {
+  displayNamingConvention(identifier, dirPath);
+  await waitForEnter();
+  const syncResult = await executeAttachSync(
+    {
+      identifier,
+      attachmentsDirectory,
+      yes: true,
+      ...idType && { idType }
+    },
+    context
+  );
+  if (syncResult.success) {
+    displayInteractiveSyncResult(syncResult, identifier);
+  } else {
+    process.stderr.write(`Sync error: ${syncResult.error}
+`);
+  }
+}
+function buildOpenOptions(identifier, filenameArg, options, attachmentsDirectory) {
+  return {
+    identifier,
+    attachmentsDirectory,
+    ...filenameArg && { filename: filenameArg },
+    ...options.print && { print: options.print },
+    ...options.role && { role: options.role },
+    ...options.uuid && { idType: "uuid" }
+  };
+}
+async function handleAttachOpenAction(identifierArg, filenameArg, options, globalOpts) {
+  try {
+    const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config2, Library.load);
+    const identifier = await resolveIdentifier(identifierArg, context, config2);
+    const isDirectoryMode = !filenameArg && !options.role;
+    const shouldUseInteractive = isTTY() && isDirectoryMode && !options.print && !options.noSync;
+    const openOptions = buildOpenOptions(
+      identifier,
+      filenameArg,
+      options,
+      config2.attachments.directory
+    );
+    const result = await executeAttachOpen(openOptions, context);
+    if (!result.success) {
+      process.stderr.write(`Error: ${result.error}
+`);
+      setExitCode(ExitCode.ERROR);
+      return;
+    }
+    if (options.print) {
+      process.stdout.write(`${result.path}
+`);
+      setExitCode(ExitCode.SUCCESS);
+    }
+    if (shouldUseInteractive) {
+      await runInteractiveMode(
+        identifier,
+        result.path ?? "",
+        config2.attachments.directory,
+        options.uuid ? "uuid" : void 0,
+        context
+      );
+    } else {
+      process.stderr.write(`${formatAttachOpenOutput(result)}
+`);
+    }
+    setExitCode(ExitCode.SUCCESS);
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    setExitCode(ExitCode.INTERNAL_ERROR);
+  }
+}
+async function handleAttachAddAction(identifierArg, filePathArg, options, globalOpts) {
+  try {
+    const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config2, Library.load);
+    const identifier = await resolveIdentifier(identifierArg, context, config2);
+    const addOptions = {
+      identifier,
+      filePath: filePathArg,
+      role: options.role,
+      attachmentsDirectory: config2.attachments.directory,
+      ...options.label && { label: options.label },
+      ...options.move && { move: options.move },
+      ...options.force && { force: options.force },
+      ...options.uuid && { idType: "uuid" }
+    };
+    const result = await executeAttachAdd(addOptions, context);
+    const output = formatAttachAddOutput(result);
+    process.stderr.write(`${output}
+`);
+    setExitCode(getAttachExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    setExitCode(ExitCode.INTERNAL_ERROR);
+  }
+}
+async function handleAttachListAction(identifierArg, options, globalOpts) {
+  try {
+    const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config2, Library.load);
+    const identifier = await resolveIdentifier(identifierArg, context, config2);
+    const listOptions = {
+      identifier,
+      attachmentsDirectory: config2.attachments.directory,
+      ...options.role && { role: options.role },
+      ...options.uuid && { idType: "uuid" }
+    };
+    const result = await executeAttachList(listOptions, context);
+    const output = formatAttachListOutput(result, identifier);
+    process.stdout.write(`${output}
+`);
+    setExitCode(getAttachExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    setExitCode(ExitCode.INTERNAL_ERROR);
+  }
+}
+async function handleAttachGetAction(identifierArg, filenameArg, options, globalOpts) {
+  try {
+    const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config2, Library.load);
+    const identifier = await resolveIdentifier(identifierArg, context, config2);
+    const getOptions = {
+      identifier,
+      attachmentsDirectory: config2.attachments.directory,
+      ...filenameArg && { filename: filenameArg },
+      ...options.role && { role: options.role },
+      ...options.stdout && { stdout: options.stdout },
+      ...options.uuid && { idType: "uuid" }
+    };
+    const result = await executeAttachGet(getOptions, context);
+    if (result.success && result.content && options.stdout) {
+      process.stdout.write(result.content);
+    } else if (result.success) {
+      process.stdout.write(`${result.path}
+`);
+    } else {
+      process.stderr.write(`Error: ${result.error}
+`);
+    }
+    setExitCode(getAttachExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    setExitCode(ExitCode.INTERNAL_ERROR);
+  }
 }
-async function readConfirmation(prompt) {
-  if (!isTTY()) {
-    return true;
-  }
-  const enquirer = await import("enquirer");
-  const Confirm = enquirer.default.Confirm;
-  const confirmPrompt = new Confirm({
-    name: "confirm",
-    message: prompt,
-    initial: false
-  });
+async function handleAttachDetachAction(identifierArg, filenameArg, options, globalOpts) {
   try {
-    return await confirmPrompt.run();
-  } catch {
-    return false;
+    const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config2, Library.load);
+    const identifier = await resolveIdentifier(identifierArg, context, config2);
+    const detachOptions = {
+      identifier,
+      attachmentsDirectory: config2.attachments.directory,
+      ...filenameArg && { filename: filenameArg },
+      ...options.role && { role: options.role },
+      ...options.all && { all: options.all },
+      ...options.removeFiles && { removeFiles: options.removeFiles },
+      ...options.uuid && { idType: "uuid" }
+    };
+    const result = await executeAttachDetach(detachOptions, context);
+    const output = formatAttachDetachOutput(result);
+    process.stderr.write(`${output}
+`);
+    setExitCode(getAttachExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    setExitCode(ExitCode.INTERNAL_ERROR);
   }
 }
-async function readStdinContent() {
-  const chunks = [];
-  for await (const chunk of stdin) {
-    chunks.push(chunk);
+async function runInteractiveSyncMode(identifier, attachmentsDirectory, idType, context) {
+  const dryRunOptions = {
+    identifier,
+    attachmentsDirectory,
+    ...idType && { idType }
+  };
+  const dryRunResult = await executeAttachSync(dryRunOptions, context);
+  const hasNewFiles = dryRunResult.newFiles.length > 0;
+  const hasMissingFiles = dryRunResult.missingFiles.length > 0;
+  if (!dryRunResult.success || !hasNewFiles && !hasMissingFiles) {
+    process.stderr.write(`${formatAttachSyncOutput(dryRunResult)}
+`);
+    return;
   }
-  return Buffer.concat(chunks).toString("utf-8").trim();
+  process.stderr.write(`${formatAttachSyncOutput(dryRunResult)}
+
+`);
+  const shouldApplyNew = hasNewFiles && await readConfirmation("Add new files to metadata?");
+  const shouldApplyFix = hasMissingFiles && shouldApplyNew && await readConfirmation("Remove missing files?");
+  if (!shouldApplyNew && !shouldApplyFix) {
+    process.stderr.write("No changes applied.\n");
+    return;
+  }
+  const applyOptions = {
+    identifier,
+    attachmentsDirectory,
+    ...shouldApplyNew && { yes: true },
+    ...shouldApplyFix && { fix: true },
+    ...idType && { idType }
+  };
+  const result = await executeAttachSync(applyOptions, context);
+  process.stderr.write(`${formatAttachSyncOutput(result)}
+`);
 }
-async function readStdinBuffer() {
-  const chunks = [];
-  for await (const chunk of stdin) {
-    chunks.push(chunk);
+async function handleAttachSyncAction(identifierArg, options, globalOpts) {
+  try {
+    const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config2, Library.load);
+    const identifier = await resolveIdentifier(identifierArg, context, config2);
+    const attachmentsDirectory = config2.attachments.directory;
+    const idType = options.uuid ? "uuid" : void 0;
+    const shouldUseInteractive = isTTY() && !options.yes && !options.fix;
+    if (shouldUseInteractive) {
+      await runInteractiveSyncMode(identifier, attachmentsDirectory, idType, context);
+      setExitCode(ExitCode.SUCCESS);
+      return;
+    }
+    const syncOptions = {
+      identifier,
+      attachmentsDirectory,
+      ...options.yes && { yes: true },
+      ...options.fix && { fix: true },
+      ...idType && { idType }
+    };
+    const result = await executeAttachSync(syncOptions, context);
+    process.stderr.write(`${formatAttachSyncOutput(result)}
+`);
+    setExitCode(getAttachExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    setExitCode(ExitCode.INTERNAL_ERROR);
   }
-  return Buffer.concat(chunks);
 }
 async function validateOptions$2(options) {
-  if (options.format && !["text", "html", "rtf"].includes(options.format)) {
-    throw new Error(`Invalid format '${options.format}'. Must be one of: text, html, rtf`);
+  if (options.output && !["text", "html", "rtf"].includes(options.output)) {
+    throw new Error(`Invalid output format '${options.output}'. Must be one of: text, html, rtf`);
   }
   if (options.cslFile) {
     const fs2 = await import("node:fs");
@@ -671,7 +1912,7 @@ function buildCiteOptions(options) {
     ...options.style !== void 0 && { style: options.style },
     ...options.cslFile !== void 0 && { cslFile: options.cslFile },
     ...options.locale !== void 0 && { locale: options.locale },
-    ...options.format !== void 0 && { format: options.format },
+    ...options.output !== void 0 && { format: options.output },
     ...options.inText !== void 0 && { inText: options.inText }
   };
 }
@@ -709,13 +1950,13 @@ function getCiteExitCode(result) {
   return 0;
 }
 async function executeInteractiveCite(options, context, config2) {
-  const { selectReferencesOrExit } = await import("./reference-select-DSVwE9iu.js");
-  const { runStyleSelect } = await import("./style-select-CYo0O7MZ.js");
+  const { selectReferencesOrExit } = await import("./reference-select-B9w9CLa1.js");
+  const { runStyleSelect } = await import("./style-select-BNQHC79W.js");
   const allReferences = await context.library.getAll();
   const identifiers = await selectReferencesOrExit(
     allReferences,
     { multiSelect: true },
-    config2.cli.interactive
+    config2.cli.tui
   );
   let style = options.style;
   if (!style && !options.cslFile) {
@@ -724,7 +1965,8 @@ async function executeInteractiveCite(options, context, config2) {
       defaultStyle: config2.citation.defaultStyle
     });
     if (styleResult.cancelled) {
-      process.exit(0);
+      setExitCode(ExitCode.SUCCESS);
+      return { results: [] };
     }
     style = styleResult.style;
   }
@@ -744,7 +1986,8 @@ async function handleCiteAction(identifiers, options, globalOpts) {
           process.stderr.write(
             "Error: No identifiers provided. Provide IDs, pipe them via stdin, or run interactively in a TTY.\n"
           );
-          process.exit(1);
+          setExitCode(ExitCode.ERROR);
+          return;
         }
         result = await executeCite({ ...options, identifiers: stdinIds }, context);
       }
@@ -761,16 +2004,16 @@ async function handleCiteAction(identifiers, options, globalOpts) {
       process.stderr.write(`${errors2}
 `);
     }
-    process.exit(getCiteExitCode(result));
+    setExitCode(getCiteExitCode(result));
   } catch (error) {
     process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(4);
+    setExitCode(ExitCode.INTERNAL_ERROR);
   }
 }
 const ENV_OVERRIDE_MAP = {
   REFERENCE_MANAGER_LIBRARY: "library",
-  REFERENCE_MANAGER_FULLTEXT_DIR: "fulltext.directory",
+  REFERENCE_MANAGER_ATTACHMENTS_DIR: "attachments.directory",
   REFERENCE_MANAGER_CLI_DEFAULT_LIMIT: "cli.default_limit",
   REFERENCE_MANAGER_MCP_DEFAULT_LIMIT: "mcp.default_limit",
   PUBMED_EMAIL: "pubmed.email",
@@ -852,14 +2095,14 @@ const CONFIG_KEY_REGISTRY = [
     description: "Default sort order",
     enumValues: ["asc", "desc"]
   },
-  // cli.interactive section
+  // cli.tui section
   {
-    key: "cli.interactive.limit",
+    key: "cli.tui.limit",
     type: "integer",
-    description: "Result limit in interactive mode"
+    description: "Result limit in TUI mode"
   },
   {
-    key: "cli.interactive.debounce_ms",
+    key: "cli.tui.debounce_ms",
     type: "integer",
     description: "Search debounce delay (ms)"
   },
@@ -1064,7 +2307,7 @@ function createConfigTemplate() {
 # default_sort = "updated"  # created, updated, published, author, title
 # default_order = "desc"  # asc, desc
 
-[cli.interactive]
+[cli.tui]
 # limit = 20
 # debounce_ms = 200
 
@@ -1307,9 +2550,9 @@ function toSnakeCaseConfig(config2) {
     default_limit: config2.cli.defaultLimit,
     default_sort: config2.cli.defaultSort,
     default_order: config2.cli.defaultOrder,
-    interactive: {
-      limit: config2.cli.interactive.limit,
-      debounce_ms: config2.cli.interactive.debounceMs
+    tui: {
+      limit: config2.cli.tui.limit,
+      debounce_ms: config2.cli.tui.debounceMs
     },
     edit: {
       default_format: config2.cli.edit.defaultFormat
@@ -1466,21 +2709,21 @@ function resolveEditor(platform) {
 }
 function registerConfigCommand(program) {
   const configCmd = program.command("config").description("Manage configuration settings");
-  configCmd.command("show").description("Display effective configuration").option("--json", "Output in JSON format").option("--section <name>", "Show only a specific section").option("--sources", "Include source information for each value").action(async (options) => {
+  configCmd.command("show").description("Display effective configuration").option("-o, --output <format>", "Output format: text|json").option("--section <name>", "Show only a specific section").option("--sources", "Include source information for each value").action(async (options) => {
     try {
       const config2 = loadConfig();
       const output = showConfig(config2, {
-        json: options.json,
+        json: options.output === "json",
         section: options.section,
         sources: options.sources
       });
       process.stdout.write(`${output}
 `);
-      process.exit(0);
+      setExitCode(ExitCode.SUCCESS);
     } catch (error) {
       process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
     }
   });
   configCmd.command("get <key>").description("Get a specific configuration value").option("--config-only", "Return only the config file value (ignore env vars)").action(async (key, options) => {
@@ -1498,14 +2741,14 @@ function registerConfigCommand(program) {
         const { formatValue: formatValue2 } = await Promise.resolve().then(() => get);
         process.stdout.write(`${formatValue2(result.value)}
 `);
-        process.exit(0);
+        setExitCode(ExitCode.SUCCESS);
       } else {
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
       }
     } catch (error) {
       process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
     }
   });
   configCmd.command("set <key> <value>").description("Set a configuration value").option("--local", "Write to current directory config (create if not exists)").option("--user", "Write to user config (ignore local config even if exists)").action(async (key, value, options) => {
@@ -1523,17 +2766,18 @@ function registerConfigCommand(program) {
       if (!result.success) {
         process.stderr.write(`Error: ${result.error}
 `);
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
+        return;
       }
       if (result.warning) {
         process.stderr.write(`${result.warning}
 `);
       }
-      process.exit(0);
+      setExitCode(ExitCode.SUCCESS);
     } catch (error) {
       process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
     }
   });
   configCmd.command("unset <key>").description("Remove a configuration value (revert to default)").option("--local", "Remove from current directory config").option("--user", "Remove from user config (ignore local config even if exists)").action(async (key, options) => {
@@ -1548,27 +2792,28 @@ function registerConfigCommand(program) {
       if (!result.success) {
         process.stderr.write(`Error: ${result.error}
 `);
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
+        return;
       }
-      process.exit(0);
+      setExitCode(ExitCode.SUCCESS);
     } catch (error) {
       process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
     }
   });
-  configCmd.command("list-keys").description("List all available configuration keys").option("--section <name>", "List keys only in a specific section").action(async (options) => {
+  configCmd.command("keys").description("List all available configuration keys").option("--section <name>", "List keys only in a specific section").action(async (options) => {
     try {
       const output = listConfigKeys({ section: options.section });
       if (output) {
         process.stdout.write(`${output}
 `);
       }
-      process.exit(0);
+      setExitCode(ExitCode.SUCCESS);
     } catch (error) {
       process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
     }
   });
   configCmd.command("path").description("Show configuration file paths").option("--user", "Show only user config path").option("--local", "Show only local config path").action(async (options) => {
@@ -1576,18 +2821,19 @@ function registerConfigCommand(program) {
       const output = showConfigPaths({ user: options.user, local: options.local });
       process.stdout.write(`${output}
 `);
-      process.exit(0);
+      setExitCode(ExitCode.SUCCESS);
     } catch (error) {
       process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
     }
   });
   configCmd.command("edit").description("Open configuration file in editor").option("--local", "Edit current directory config").action(async (options) => {
     try {
       if (!process.stdin.isTTY) {
         process.stderr.write("Error: config edit requires a terminal (TTY)\n");
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
+        return;
       }
       const target = getConfigEditTarget({ local: options.local });
       if (!target.exists) {
@@ -1597,11 +2843,11 @@ function registerConfigCommand(program) {
       }
       const editor = resolveEditor();
       const exitCode = openEditor(editor, target.path);
-      process.exit(exitCode);
+      setExitCode(exitCode);
     } catch (error) {
       process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
     }
   });
 }
@@ -4542,12 +5788,12 @@ function formatEditOutput(result) {
   return lines.join("\n");
 }
 async function executeInteractiveEdit(options, context, config2) {
-  const { selectReferencesOrExit } = await import("./reference-select-DSVwE9iu.js");
+  const { selectReferencesOrExit } = await import("./reference-select-B9w9CLa1.js");
   const allReferences = await context.library.getAll();
   const identifiers = await selectReferencesOrExit(
     allReferences,
     { multiSelect: true },
-    config2.cli.interactive
+    config2.cli.tui
   );
   const format2 = options.format ?? config2.cli.edit.defaultFormat;
   return executeEditCommand(
@@ -4572,7 +5818,7 @@ async function handleEditAction(identifiers, options, globalOpts) {
       const output2 = formatEditOutput(result2);
       process.stderr.write(`${output2}
 `);
-      process.exit(result2.success ? 0 : 1);
+      setExitCode(result2.success ? ExitCode.SUCCESS : ExitCode.ERROR);
       return;
     } else {
       const stdinIds = await readIdentifiersFromStdin();
@@ -4580,13 +5826,15 @@ async function handleEditAction(identifiers, options, globalOpts) {
         process.stderr.write(
           "Error: No identifiers provided. Provide IDs, pipe them via stdin, or run interactively in a TTY.\n"
         );
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
+        return;
       }
       resolvedIdentifiers = stdinIds;
     }
     if (!isTTY()) {
       process.stderr.write("Error: Edit command requires a TTY to open the editor.\n");
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
+      return;
     }
     const format2 = options.format ?? config2.cli.edit.defaultFormat;
     const result = await executeEditCommand(
@@ -4601,11 +5849,11 @@ async function handleEditAction(identifiers, options, globalOpts) {
     const output = formatEditOutput(result);
     process.stderr.write(`${output}
 `);
-    process.exit(result.success ? 0 : 1);
+    setExitCode(result.success ? ExitCode.SUCCESS : ExitCode.ERROR);
   } catch (error) {
     process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(4);
+    setExitCode(ExitCode.INTERNAL_ERROR);
   }
 }
 const ALIAS = Symbol.for("yaml.alias");
@@ -7778,7 +9026,7 @@ async function executeExport(options, context) {
   return { items: items2, notFound };
 }
 function formatExportOutput(result, options) {
-  const format2 = options.format ?? "json";
+  const format2 = options.output ?? "json";
   const singleIdRequest = (options.ids?.length ?? 0) === 1 && !options.all && !options.search;
   const data = result.items.length === 1 && singleIdRequest ? result.items[0] : result.items;
   if (format2 === "json") {
@@ -7795,183 +9043,6 @@ function formatExportOutput(result, options) {
 function getExportExitCode(result) {
   return result.notFound.length > 0 ? 1 : 0;
 }
-const FULLTEXT_EXTENSIONS = {
-  pdf: ".pdf",
-  markdown: ".md"
-};
-function generateFulltextFilename(item, type2) {
-  const uuid2 = item.custom?.uuid;
-  if (!uuid2) {
-    throw new Error("Missing uuid in custom field");
-  }
-  const parts = [item.id];
-  if (item.PMID && item.PMID.length > 0) {
-    parts.push(`PMID${item.PMID}`);
-  }
-  parts.push(uuid2);
-  return parts.join("-") + FULLTEXT_EXTENSIONS[type2];
-}
-class FulltextIOError extends Error {
-  constructor(message, cause) {
-    super(message);
-    this.cause = cause;
-    this.name = "FulltextIOError";
-  }
-}
-class FulltextNotAttachedError extends Error {
-  constructor(itemId, type2) {
-    super(`No ${type2} attached to reference ${itemId}`);
-    this.itemId = itemId;
-    this.type = type2;
-    this.name = "FulltextNotAttachedError";
-  }
-}
-class FulltextManager {
-  constructor(fulltextDirectory) {
-    this.fulltextDirectory = fulltextDirectory;
-  }
-  /**
-   * Ensure the fulltext directory exists
-   */
-  async ensureDirectory() {
-    await mkdir(this.fulltextDirectory, { recursive: true });
-  }
-  /**
-   * Attach a file to a reference
-   */
-  async attachFile(item, sourcePath, type2, options) {
-    const { move = false, force = false } = options ?? {};
-    const newFilename = generateFulltextFilename(item, type2);
-    this.validateSourceFile(sourcePath);
-    const existingFilename = this.getExistingFilename(item, type2);
-    if (existingFilename && !force) {
-      return {
-        filename: newFilename,
-        existingFile: existingFilename,
-        overwritten: false
-      };
-    }
-    await this.ensureDirectory();
-    const deletedOldFile = await this.deleteOldFileIfNeeded(existingFilename, newFilename, force);
-    const destPath = join(this.fulltextDirectory, newFilename);
-    await this.copyOrMoveFile(sourcePath, destPath, move);
-    const result = {
-      filename: newFilename,
-      overwritten: existingFilename !== void 0
-    };
-    if (deletedOldFile) {
-      result.deletedOldFile = deletedOldFile;
-    }
-    return result;
-  }
-  /**
-   * Validate that source file exists
-   */
-  validateSourceFile(sourcePath) {
-    if (!existsSync(sourcePath)) {
-      throw new FulltextIOError(`Source file not found: ${sourcePath}`);
-    }
-  }
-  /**
-   * Delete old file if force mode and filename changed
-   * @returns Deleted filename or undefined
-   */
-  async deleteOldFileIfNeeded(existingFilename, newFilename, force) {
-    if (!force || !existingFilename || existingFilename === newFilename) {
-      return void 0;
-    }
-    const oldPath = join(this.fulltextDirectory, existingFilename);
-    try {
-      await unlink(oldPath);
-    } catch {
-    }
-    return existingFilename;
-  }
-  /**
-   * Copy or move file to destination
-   */
-  async copyOrMoveFile(sourcePath, destPath, move) {
-    try {
-      if (move) {
-        await rename(sourcePath, destPath);
-      } else {
-        await copyFile(sourcePath, destPath);
-      }
-    } catch (error) {
-      const operation = move ? "move" : "copy";
-      throw new FulltextIOError(
-        `Failed to ${operation} file to ${destPath}`,
-        error instanceof Error ? error : void 0
-      );
-    }
-  }
-  /**
-   * Get the full path for an attached file
-   * @returns Full path or null if not attached
-   */
-  getFilePath(item, type2) {
-    const filename = this.getExistingFilename(item, type2);
-    if (!filename) {
-      return null;
-    }
-    return join(this.fulltextDirectory, filename);
-  }
-  /**
-   * Detach a file from a reference
-   */
-  async detachFile(item, type2, options) {
-    const { delete: deleteFile = false } = options ?? {};
-    const filename = this.getExistingFilename(item, type2);
-    if (!filename) {
-      throw new FulltextNotAttachedError(item.id, type2);
-    }
-    if (deleteFile) {
-      const filePath = join(this.fulltextDirectory, filename);
-      try {
-        await unlink(filePath);
-      } catch {
-      }
-    }
-    return {
-      filename,
-      deleted: deleteFile
-    };
-  }
-  /**
-   * Get list of attached fulltext types
-   */
-  getAttachedTypes(item) {
-    const types2 = [];
-    const fulltext = item.custom?.fulltext;
-    if (fulltext?.pdf) {
-      types2.push("pdf");
-    }
-    if (fulltext?.markdown) {
-      types2.push("markdown");
-    }
-    return types2;
-  }
-  /**
-   * Check if item has attachment
-   * @param type Optional type to check; if omitted, checks for any attachment
-   */
-  hasAttachment(item, type2) {
-    if (type2) {
-      return this.getExistingFilename(item, type2) !== void 0;
-    }
-    return this.getAttachedTypes(item).length > 0;
-  }
-  /**
-   * Get existing filename from item metadata
-   */
-  getExistingFilename(item, type2) {
-    const fulltext = item.custom?.fulltext;
-    if (!fulltext) {
-      return void 0;
-    }
-    return fulltext[type2];
-  }
-}
 function detectType(filePath) {
   const ext = extname(filePath).toLowerCase();
   if (ext === ".pdf") return "pdf";
@@ -7996,8 +9067,8 @@ function resolveFileType(explicitType, filePath, stdinContent) {
 function prepareStdinSource(stdinContent, fileType) {
   try {
     const tempDir = mkdtempSync(join(tmpdir(), "refmgr-"));
-    const ext = fileType === "pdf" ? ".pdf" : ".md";
-    const sourcePath = join(tempDir, `stdin${ext}`);
+    const ext = formatToExtension(fileType);
+    const sourcePath = join(tempDir, `stdin.${ext}`);
     writeFileSync(sourcePath, stdinContent);
     return { sourcePath, tempDir };
   } catch (error) {
@@ -8012,13 +9083,6 @@ async function cleanupTempDir(tempDir) {
     });
   }
 }
-function buildNewFulltext(currentFulltext, fileType, filename) {
-  const newFulltext = {};
-  if (currentFulltext.pdf) newFulltext.pdf = currentFulltext.pdf;
-  if (currentFulltext.markdown) newFulltext.markdown = currentFulltext.markdown;
-  newFulltext[fileType] = filename;
-  return newFulltext;
-}
 function prepareSourcePath(filePath, stdinContent, fileType) {
   if (stdinContent) {
     return prepareStdinSource(stdinContent, fileType);
@@ -8028,12 +9092,26 @@ function prepareSourcePath(filePath, stdinContent, fileType) {
   }
   return { sourcePath: filePath };
 }
-async function performAttach(manager, item, sourcePath, fileType, move, force) {
-  const attachOptions = {
-    ...move !== void 0 && { move },
-    ...force !== void 0 && { force }
+function convertResult(result, fileType) {
+  if (result.success) {
+    return {
+      success: true,
+      filename: result.filename,
+      type: fileType,
+      overwritten: result.overwritten
+    };
+  }
+  if (result.requiresConfirmation) {
+    return {
+      success: false,
+      existingFile: result.existingFile,
+      requiresConfirmation: true
+    };
+  }
+  return {
+    success: false,
+    error: result.error
   };
-  return manager.attachFile(item, sourcePath, fileType, attachOptions);
 }
 async function fulltextAttach(library, options) {
   const {
@@ -8046,71 +9124,78 @@ async function fulltextAttach(library, options) {
     fulltextDirectory,
     stdinContent
   } = options;
-  const item = await library.find(identifier, { idType });
-  if (!item) {
-    return { success: false, error: `Reference '${identifier}' not found` };
-  }
   const fileTypeResult = resolveFileType(explicitType, filePath, stdinContent);
   if (typeof fileTypeResult === "object" && "error" in fileTypeResult) {
+    const item = await library.find(identifier, { idType });
+    if (!item) {
+      return { success: false, error: `Reference '${identifier}' not found` };
+    }
     return { success: false, error: fileTypeResult.error };
   }
   const fileType = fileTypeResult;
   const sourceResult = prepareSourcePath(filePath, stdinContent, fileType);
   if ("error" in sourceResult) {
+    const item = await library.find(identifier, { idType });
+    if (!item) {
+      return { success: false, error: `Reference '${identifier}' not found` };
+    }
     return { success: false, error: sourceResult.error };
   }
   const { sourcePath, tempDir } = sourceResult;
-  const manager = new FulltextManager(fulltextDirectory);
   try {
-    const result = await performAttach(manager, item, sourcePath, fileType, move, force);
-    if (result.existingFile && !result.overwritten) {
-      await cleanupTempDir(tempDir);
-      return { success: false, existingFile: result.existingFile, requiresConfirmation: true };
-    }
-    const newFulltext = buildNewFulltext(item.custom?.fulltext ?? {}, fileType, result.filename);
-    await updateReference(library, {
+    const result = await addAttachment(library, {
       identifier,
-      updates: {
-        custom: { fulltext: newFulltext }
-      },
-      idType
+      filePath: sourcePath,
+      role: FULLTEXT_ROLE,
+      move: move ?? false,
+      force: force ?? false,
+      idType,
+      attachmentsDirectory: fulltextDirectory
     });
     await cleanupTempDir(tempDir);
-    return {
-      success: true,
-      filename: result.filename,
-      type: fileType,
-      overwritten: result.overwritten
-    };
+    return convertResult(result, fileType);
   } catch (error) {
     await cleanupTempDir(tempDir);
-    if (error instanceof FulltextIOError) {
-      return { success: false, error: error.message };
-    }
     throw error;
   }
 }
-async function getFileContent(manager, item, type2, identifier) {
-  const filePath = manager.getFilePath(item, type2);
-  if (!filePath) {
+function buildFilePath$1(attachmentsDirectory, directory, filename) {
+  return normalizePathForOutput(join(attachmentsDirectory, directory, filename));
+}
+async function getFileContent(filePath) {
+  const content = await readFile(filePath);
+  return { success: true, content };
+}
+async function handleStdoutMode(attachments, type2, identifier, fulltextDirectory) {
+  const file = findFulltextFile(attachments, type2);
+  if (!file || !attachments?.directory) {
     return { success: false, error: `No ${type2} fulltext attached to '${identifier}'` };
   }
+  const filePath = buildFilePath$1(fulltextDirectory, attachments.directory, file.filename);
   try {
-    const content = await readFile(filePath);
-    return { success: true, content };
-  } catch (error) {
-    return {
-      success: false,
-      error: `Failed to read file: ${error instanceof Error ? error.message : String(error)}`
-    };
+    return await getFileContent(filePath);
+  } catch {
+    return { success: false, error: `No ${type2} fulltext attached to '${identifier}'` };
   }
 }
-function getFilePaths(manager, item, types2, identifier) {
+function getSingleTypePath(attachments, type2, identifier, fulltextDirectory) {
+  const file = findFulltextFile(attachments, type2);
+  if (!file || !attachments?.directory) {
+    return { success: false, error: `No ${type2} fulltext attached to '${identifier}'` };
+  }
+  const filePath = buildFilePath$1(fulltextDirectory, attachments.directory, file.filename);
+  const paths = {};
+  paths[type2] = filePath;
+  return { success: true, paths };
+}
+function getAllFulltextPaths(attachments, fulltextFiles, fulltextDirectory, identifier) {
   const paths = {};
-  for (const t of types2) {
-    const filePath = manager.getFilePath(item, t);
-    if (filePath) {
-      paths[t] = filePath;
+  for (const file of fulltextFiles) {
+    const ext = file.filename.split(".").pop() || "";
+    const format2 = extensionToFormat(ext);
+    if (format2) {
+      const filePath = buildFilePath$1(fulltextDirectory, attachments.directory, file.filename);
+      paths[format2] = filePath;
     }
   }
   if (Object.keys(paths).length === 0) {
@@ -8124,92 +9209,98 @@ async function fulltextGet(library, options) {
   if (!item) {
     return { success: false, error: `Reference '${identifier}' not found` };
   }
-  const manager = new FulltextManager(fulltextDirectory);
+  const attachments = item.custom?.attachments;
   if (stdout2 && type2) {
-    return getFileContent(manager, item, type2, identifier);
+    return handleStdoutMode(attachments, type2, identifier, fulltextDirectory);
+  }
+  const fulltextFiles = findFulltextFiles(attachments);
+  if (fulltextFiles.length === 0) {
+    return { success: false, error: `No fulltext attached to '${identifier}'` };
+  }
+  if (type2) {
+    return getSingleTypePath(attachments, type2, identifier, fulltextDirectory);
   }
-  const attachedTypes = type2 ? [type2] : manager.getAttachedTypes(item);
-  if (attachedTypes.length === 0) {
+  if (!attachments) {
     return { success: false, error: `No fulltext attached to '${identifier}'` };
   }
-  return getFilePaths(manager, item, attachedTypes, identifier);
+  return getAllFulltextPaths(attachments, fulltextFiles, fulltextDirectory, identifier);
 }
-async function performDetachOperations(manager, item, typesToDetach, deleteFile) {
+function getFilesToDetach(attachments, type2) {
+  if (type2) {
+    const file = findFulltextFile(attachments, type2);
+    return file ? [file] : [];
+  }
+  return findFulltextFiles(attachments);
+}
+async function detachFiles(library, files, identifier, removeFiles, idType, fulltextDirectory) {
   const detached = [];
   const deleted = [];
-  for (const t of typesToDetach) {
-    const detachOptions = deleteFile ? { delete: deleteFile } : {};
-    const result = await manager.detachFile(item, t, detachOptions);
-    detached.push(t);
-    if (result.deleted) {
-      deleted.push(t);
+  for (const file of files) {
+    const result = await detachAttachment(library, {
+      identifier,
+      filename: file.filename,
+      removeFiles: removeFiles ?? false,
+      idType,
+      attachmentsDirectory: fulltextDirectory
+    });
+    if (result.success) {
+      const ext = file.filename.split(".").pop() || "";
+      const format2 = extensionToFormat(ext);
+      if (format2) {
+        detached.push(format2);
+        if (result.deleted.length > 0) {
+          deleted.push(format2);
+        }
+      }
     }
   }
   return { detached, deleted };
 }
-function buildRemainingFulltext(currentFulltext, detached) {
-  const newFulltext = {};
-  if (currentFulltext.pdf && !detached.includes("pdf")) {
-    newFulltext.pdf = currentFulltext.pdf;
-  }
-  if (currentFulltext.markdown && !detached.includes("markdown")) {
-    newFulltext.markdown = currentFulltext.markdown;
+function buildResult(detached, deleted, identifier) {
+  if (detached.length === 0) {
+    return { success: false, error: `Failed to detach fulltext from '${identifier}'` };
   }
-  return Object.keys(newFulltext).length > 0 ? newFulltext : void 0;
-}
-function handleDetachError(error) {
-  if (error instanceof FulltextNotAttachedError || error instanceof FulltextIOError) {
-    return { success: false, error: error.message };
+  const result = { success: true, detached };
+  if (deleted.length > 0) {
+    result.deleted = deleted;
   }
-  throw error;
+  return result;
 }
 async function fulltextDetach(library, options) {
-  const { identifier, type: type2, delete: deleteFile, idType = "id", fulltextDirectory } = options;
+  const { identifier, type: type2, removeFiles, idType = "id", fulltextDirectory } = options;
   const item = await library.find(identifier, { idType });
   if (!item) {
     return { success: false, error: `Reference '${identifier}' not found` };
   }
-  const manager = new FulltextManager(fulltextDirectory);
-  const typesToDetach = type2 ? [type2] : manager.getAttachedTypes(item);
-  if (typesToDetach.length === 0) {
+  const attachments = item.custom?.attachments;
+  const fulltextFiles = findFulltextFiles(attachments);
+  if (fulltextFiles.length === 0) {
     return { success: false, error: `No fulltext attached to '${identifier}'` };
   }
-  try {
-    const { detached, deleted } = await performDetachOperations(
-      manager,
-      item,
-      typesToDetach,
-      deleteFile
-    );
-    const updatedFulltext = buildRemainingFulltext(item.custom?.fulltext ?? {}, detached);
-    await updateReference(library, {
-      identifier,
-      updates: {
-        custom: { fulltext: updatedFulltext }
-      },
-      idType
-    });
-    const resultData = { success: true, detached };
-    if (deleted.length > 0) {
-      resultData.deleted = deleted;
-    }
-    return resultData;
-  } catch (error) {
-    return handleDetachError(error);
+  const filesToDetach = getFilesToDetach(attachments, type2);
+  if (filesToDetach.length === 0) {
+    return { success: false, error: `No ${type2} fulltext attached to '${identifier}'` };
   }
-}
-function getFulltextPath(item, type2, fulltextDirectory) {
-  const fulltext = item.custom?.fulltext;
-  if (!fulltext) return void 0;
-  const filename = type2 === "pdf" ? fulltext.pdf : fulltext.markdown;
-  if (!filename) return void 0;
-  return join(fulltextDirectory, filename);
-}
-function determineTypeToOpen(item) {
-  const fulltext = item.custom?.fulltext;
-  if (!fulltext) return void 0;
-  if (fulltext.pdf) return "pdf";
-  if (fulltext.markdown) return "markdown";
+  const { detached, deleted } = await detachFiles(
+    library,
+    filesToDetach,
+    identifier,
+    removeFiles,
+    idType,
+    fulltextDirectory
+  );
+  return buildResult(detached, deleted, identifier);
+}
+function buildFilePath(attachmentsDirectory, directory, filename) {
+  return join(attachmentsDirectory, directory, filename);
+}
+function determineTypeToOpen(attachments) {
+  const files = findFulltextFiles(attachments);
+  if (files.length === 0) return void 0;
+  const pdfFile = files.find((f) => f.filename.endsWith(".pdf"));
+  if (pdfFile) return "pdf";
+  const mdFile = files.find((f) => f.filename.endsWith(".md"));
+  if (mdFile) return "markdown";
   return void 0;
 }
 async function fulltextOpen(library, options) {
@@ -8218,14 +9309,16 @@ async function fulltextOpen(library, options) {
   if (!item) {
     return { success: false, error: `Reference not found: ${identifier}` };
   }
-  const typeToOpen = type2 ?? determineTypeToOpen(item);
+  const attachments = item.custom?.attachments;
+  const typeToOpen = type2 ?? determineTypeToOpen(attachments);
   if (!typeToOpen) {
     return { success: false, error: `No fulltext attached to reference: ${identifier}` };
   }
-  const filePath = getFulltextPath(item, typeToOpen, fulltextDirectory);
-  if (!filePath) {
+  const file = findFulltextFile(attachments, typeToOpen);
+  if (!file || !attachments?.directory) {
     return { success: false, error: `No ${typeToOpen} attached to reference: ${identifier}` };
   }
+  const filePath = buildFilePath(fulltextDirectory, attachments.directory, file.filename);
   if (!existsSync(filePath)) {
     return {
       success: false,
@@ -8273,7 +9366,7 @@ async function executeFulltextDetach(options, context) {
   const operationOptions = {
     identifier: options.identifier,
     type: options.type,
-    delete: options.delete,
+    removeFiles: options.removeFiles,
     idType: options.idType,
     fulltextDirectory: options.fulltextDirectory
   };
@@ -8344,12 +9437,12 @@ function getFulltextExitCode(result) {
   return result.success ? 0 : 1;
 }
 async function executeInteractiveSelect(context, config2) {
-  const { selectReferencesOrExit } = await import("./reference-select-DSVwE9iu.js");
+  const { selectReferencesOrExit } = await import("./reference-select-B9w9CLa1.js");
   const allReferences = await context.library.getAll();
   const identifiers = await selectReferencesOrExit(
     allReferences,
     { multiSelect: false },
-    config2.cli.interactive
+    config2.cli.tui
   );
   return identifiers[0];
 }
@@ -8380,7 +9473,8 @@ async function handleFulltextAttachAction(identifierArg, filePathArg, options, g
         process.stderr.write(
           "Error: No identifier provided. Provide an ID or run interactively in a TTY.\n"
         );
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
+        return;
       }
       identifier = await executeInteractiveSelect(context, config2);
     }
@@ -8388,7 +9482,7 @@ async function handleFulltextAttachAction(identifierArg, filePathArg, options, g
     const stdinContent = !filePath && type2 ? await readStdinBuffer() : void 0;
     const attachOptions = {
       identifier,
-      fulltextDirectory: config2.fulltext.directory,
+      fulltextDirectory: config2.attachments.directory,
       ...filePath && { filePath },
       ...type2 && { type: type2 },
       ...options.move && { move: options.move },
@@ -8400,11 +9494,11 @@ async function handleFulltextAttachAction(identifierArg, filePathArg, options, g
     const output = formatFulltextAttachOutput(result);
     process.stderr.write(`${output}
 `);
-    process.exit(getFulltextExitCode(result));
+    setExitCode(getFulltextExitCode(result));
   } catch (error) {
     process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(4);
+    setExitCode(ExitCode.INTERNAL_ERROR);
   }
 }
 function outputFulltextGetResult(result, useStdout) {
@@ -8436,13 +9530,14 @@ async function handleFulltextGetAction(identifierArg, options, globalOpts) {
         process.stderr.write(
           "Error: No identifier provided. Provide an ID, pipe one via stdin, or run interactively in a TTY.\n"
         );
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
+        return;
       }
       identifier = stdinId;
     }
     const getOptions = {
       identifier,
-      fulltextDirectory: config2.fulltext.directory,
+      fulltextDirectory: config2.attachments.directory,
       ...options.pdf && { type: "pdf" },
       ...options.markdown && { type: "markdown" },
       ...options.stdout && { stdout: options.stdout },
@@ -8450,11 +9545,11 @@ async function handleFulltextGetAction(identifierArg, options, globalOpts) {
     };
     const result = await executeFulltextGet(getOptions, context);
     outputFulltextGetResult(result, Boolean(options.stdout));
-    process.exit(getFulltextExitCode(result));
+    setExitCode(getFulltextExitCode(result));
   } catch (error) {
     process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(4);
+    setExitCode(ExitCode.INTERNAL_ERROR);
   }
 }
 async function handleFulltextDetachAction(identifierArg, options, globalOpts) {
@@ -8472,16 +9567,17 @@ async function handleFulltextDetachAction(identifierArg, options, globalOpts) {
         process.stderr.write(
           "Error: No identifier provided. Provide an ID, pipe one via stdin, or run interactively in a TTY.\n"
         );
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
+        return;
       }
       identifier = stdinId;
     }
     const detachOptions = {
       identifier,
-      fulltextDirectory: config2.fulltext.directory,
+      fulltextDirectory: config2.attachments.directory,
       ...options.pdf && { type: "pdf" },
       ...options.markdown && { type: "markdown" },
-      ...options.delete && { delete: options.delete },
+      ...options.removeFiles && { removeFiles: options.removeFiles },
       ...options.force && { force: options.force },
       ...options.uuid && { idType: "uuid" }
     };
@@ -8489,11 +9585,11 @@ async function handleFulltextDetachAction(identifierArg, options, globalOpts) {
     const output = formatFulltextDetachOutput(result);
     process.stderr.write(`${output}
 `);
-    process.exit(getFulltextExitCode(result));
+    setExitCode(getFulltextExitCode(result));
   } catch (error) {
     process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(4);
+    setExitCode(ExitCode.INTERNAL_ERROR);
   }
 }
 async function handleFulltextOpenAction(identifierArg, options, globalOpts) {
@@ -8511,13 +9607,14 @@ async function handleFulltextOpenAction(identifierArg, options, globalOpts) {
         process.stderr.write(
           "Error: No identifier provided. Provide an ID, pipe one via stdin, or run interactively in a TTY.\n"
         );
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
+        return;
       }
       identifier = stdinId;
     }
     const openOptions = {
       identifier,
-      fulltextDirectory: config2.fulltext.directory,
+      fulltextDirectory: config2.attachments.directory,
       ...options.pdf && { type: "pdf" },
       ...options.markdown && { type: "markdown" },
       ...options.uuid && { idType: "uuid" }
@@ -8526,11 +9623,11 @@ async function handleFulltextOpenAction(identifierArg, options, globalOpts) {
     const output = formatFulltextOpenOutput(result);
     process.stderr.write(`${output}
 `);
-    process.exit(getFulltextExitCode(result));
+    setExitCode(getFulltextExitCode(result));
   } catch (error) {
     process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(4);
+    setExitCode(ExitCode.INTERNAL_ERROR);
   }
 }
 function formatAuthor(author) {
@@ -8624,21 +9721,28 @@ const VALID_LIST_SORT_FIELDS = /* @__PURE__ */ new Set([
   "pub"
 ]);
 function getOutputFormat$1(options) {
+  if (options.output) {
+    if (options.output === "ids") return "ids-only";
+    return options.output;
+  }
   if (options.json) return "json";
   if (options.idsOnly) return "ids-only";
-  if (options.uuid) return "uuid";
+  if (options.uuidOnly) return "uuid";
   if (options.bibtex) return "bibtex";
   return "pretty";
 }
 function validateOptions$1(options) {
-  const outputOptions = [options.json, options.idsOnly, options.uuid, options.bibtex].filter(
+  const outputOptions = [options.json, options.idsOnly, options.uuidOnly, options.bibtex].filter(
     Boolean
   );
   if (outputOptions.length > 1) {
     throw new Error(
-      "Multiple output formats specified. Only one of --json, --ids-only, --uuid, --bibtex can be used."
+      "Multiple output formats specified. Only one of --json, --ids-only, --uuid-only, --bibtex can be used."
     );
   }
+  if (options.output && outputOptions.length > 0) {
+    throw new Error("Cannot combine --output with convenience flags (--json, --ids-only, etc.)");
+  }
   if (options.sort !== void 0) {
     const sortStr = String(options.sort);
     if (!VALID_LIST_SORT_FIELDS.has(sortStr)) {
@@ -29050,7 +30154,7 @@ function registerFulltextAttachTool(server, getLibraryOperations, getConfig) {
         filePath: args.path,
         force: true,
         // MCP tools don't support interactive confirmation
-        fulltextDirectory: config2.fulltext.directory
+        fulltextDirectory: config2.attachments.directory
       });
       if (!result.success) {
         return {
@@ -29083,7 +30187,7 @@ function registerFulltextGetTool(server, getLibraryOperations, getConfig) {
       const config2 = getConfig();
       const pathResult = await fulltextGet(libraryOps, {
         identifier: args.id,
-        fulltextDirectory: config2.fulltext.directory
+        fulltextDirectory: config2.attachments.directory
       });
       if (!pathResult.success) {
         return {
@@ -29097,7 +30201,7 @@ function registerFulltextGetTool(server, getLibraryOperations, getConfig) {
           identifier: args.id,
           type: "markdown",
           stdout: true,
-          fulltextDirectory: config2.fulltext.directory
+          fulltextDirectory: config2.attachments.directory
         });
         if (contentResult.success && contentResult.content) {
           responses.push({
@@ -29136,7 +30240,7 @@ function registerFulltextDetachTool(server, getLibraryOperations, getConfig) {
       const config2 = getConfig();
       const result = await fulltextDetach(libraryOps, {
         identifier: args.id,
-        fulltextDirectory: config2.fulltext.directory
+        fulltextDirectory: config2.attachments.directory
       });
       if (!result.success) {
         return {
@@ -29342,7 +30446,7 @@ async function mcpStart(options) {
 async function executeRemove(options, context) {
   const { identifier, idType = "id", fulltextDirectory, deleteFulltext = false } = options;
   if (context.mode === "local" && deleteFulltext && fulltextDirectory) {
-    const { removeReference } = await import("./index-DapYyqAC.js").then((n) => n.r);
+    const { removeReference } = await import("./index-DHgeuWGP.js").then((n) => n.r);
     return removeReference(context.library, {
       identifier,
       idType,
@@ -29396,12 +30500,12 @@ Continue?`;
   return readConfirmation(confirmMsg);
 }
 async function executeInteractiveRemove(context, config2) {
-  const { selectReferenceItemsOrExit } = await import("./reference-select-DSVwE9iu.js");
+  const { selectReferenceItemsOrExit } = await import("./reference-select-B9w9CLa1.js");
   const allReferences = await context.library.getAll();
   const selectedItems = await selectReferenceItemsOrExit(
     allReferences,
     { multiSelect: false },
-    config2.cli.interactive
+    config2.cli.tui
   );
   const selectedItem = selectedItems[0];
   return { identifier: selectedItem.id, item: selectedItem };
@@ -29452,7 +30556,7 @@ function handleRemoveError(error, identifierArg, outputFormat) {
 `);
   }
   const isUserError = message.includes("not found") || message.includes("No identifier");
-  process.exit(isUserError ? 1 : 4);
+  setExitCode(isUserError ? ExitCode.ERROR : ExitCode.INTERNAL_ERROR);
 }
 async function handleRemoveAction(identifierArg, options, globalOpts) {
   const { formatRemoveJsonOutput: formatRemoveJsonOutput2 } = await Promise.resolve().then(() => jsonOutput);
@@ -29473,22 +30577,24 @@ async function handleRemoveAction(identifierArg, options, globalOpts) {
     if (hasFulltext && !isTTY() && !force) {
       process.stderr.write(`Error: ${formatFulltextWarning(fulltextTypes)}
 `);
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
+      return;
     }
     const confirmed = await confirmRemoveIfNeeded(refToRemove, hasFulltext, force);
     if (!confirmed) {
       process.stderr.write("Cancelled.\n");
-      process.exit(2);
+      setExitCode(2);
+      return;
     }
     const removeOptions = {
       identifier,
       idType: useUuid ? "uuid" : "id",
-      fulltextDirectory: config2.fulltext.directory,
+      fulltextDirectory: config2.attachments.directory,
       deleteFulltext: force && hasFulltext
     };
     const result = await executeRemove(removeOptions, context);
     outputResult(result, identifier, outputFormat, options.full, formatRemoveJsonOutput2);
-    process.exit(result.removed ? 0 : 1);
+    setExitCode(result.removed ? ExitCode.SUCCESS : ExitCode.ERROR);
   } catch (error) {
     handleRemoveError(error, identifierArg, outputFormat);
   }
@@ -29506,21 +30612,28 @@ const VALID_SEARCH_SORT_FIELDS = /* @__PURE__ */ new Set([
   "rel"
 ]);
 function getOutputFormat(options) {
+  if (options.output) {
+    if (options.output === "ids") return "ids-only";
+    return options.output;
+  }
   if (options.json) return "json";
   if (options.idsOnly) return "ids-only";
-  if (options.uuid) return "uuid";
+  if (options.uuidOnly) return "uuid";
   if (options.bibtex) return "bibtex";
   return "pretty";
 }
 function validateOptions(options) {
-  const outputOptions = [options.json, options.idsOnly, options.uuid, options.bibtex].filter(
+  const outputOptions = [options.json, options.idsOnly, options.uuidOnly, options.bibtex].filter(
     Boolean
   );
   if (outputOptions.length > 1) {
     throw new Error(
-      "Multiple output formats specified. Only one of --json, --ids-only, --uuid, --bibtex can be used."
+      "Multiple output formats specified. Only one of --json, --ids-only, --uuid-only, --bibtex can be used."
     );
   }
+  if (options.output && outputOptions.length > 0) {
+    throw new Error("Cannot combine --output with convenience flags (--json, --ids-only, etc.)");
+  }
   if (options.sort !== void 0) {
     const sortStr = String(options.sort);
     if (!VALID_SEARCH_SORT_FIELDS.has(sortStr)) {
@@ -29576,35 +30689,39 @@ function formatSearchOutput(result, options) {
   return lines.join("\n");
 }
 function validateInteractiveOptions(options) {
-  const outputOptions = [options.json, options.idsOnly, options.uuid, options.bibtex].filter(
-    Boolean
-  );
+  const outputOptions = [
+    options.output,
+    options.json,
+    options.idsOnly,
+    options.uuidOnly,
+    options.bibtex
+  ].filter(Boolean);
   if (outputOptions.length > 0) {
     throw new Error(
-      "Interactive mode cannot be combined with output format options (--json, --ids-only, --uuid, --bibtex)"
+      "TUI mode cannot be combined with output format options (--output, --json, --ids-only, --uuid-only, --bibtex)"
     );
   }
 }
 async function executeInteractiveSearch(options, context, config2) {
   validateInteractiveOptions(options);
-  const { checkTTY } = await import("./tty-CDBIQraQ.js");
+  const { checkTTY } = await import("./tty-BMyaEOhX.js");
   const { runSearchPrompt } = await import("./search-prompt-BrWpOcij.js");
-  const { runActionMenu } = await import("./action-menu-CVSizwXm.js");
-  const { search } = await import("./file-watcher-D2Y-SlcE.js").then((n) => n.y);
-  const { tokenize } = await import("./file-watcher-D2Y-SlcE.js").then((n) => n.x);
+  const { runActionMenu } = await import("./action-menu-DwCcc6Gt.js");
+  const { search } = await import("./file-watcher-B_WpVHSV.js").then((n) => n.y);
+  const { tokenize } = await import("./file-watcher-B_WpVHSV.js").then((n) => n.x);
   checkTTY();
   const allReferences = await context.library.getAll();
   const searchFn = (query) => {
     const { tokens } = tokenize(query);
     return search(allReferences, tokens);
   };
-  const interactiveConfig = config2.cli.interactive;
+  const tuiConfig = config2.cli.tui;
   const searchResult = await runSearchPrompt(
     allReferences,
     searchFn,
     {
-      limit: interactiveConfig.limit,
-      debounceMs: interactiveConfig.debounceMs
+      limit: tuiConfig.limit,
+      debounceMs: tuiConfig.debounceMs
     },
     options.query || ""
   );
@@ -29667,7 +30784,7 @@ async function startServerForeground(options) {
     server.close();
     await dispose();
     await removePortfile(options.portfilePath);
-    process.exit(0);
+    setExitCode(ExitCode.SUCCESS);
   };
   process.on("SIGINT", cleanup);
   process.on("SIGTERM", cleanup);
@@ -29897,12 +31014,12 @@ function formatUpdateOutput(result, identifier) {
   return parts.join("\n");
 }
 async function executeInteractiveUpdate(context, config2) {
-  const { selectReferencesOrExit } = await import("./reference-select-DSVwE9iu.js");
+  const { selectReferencesOrExit } = await import("./reference-select-B9w9CLa1.js");
   const allReferences = await context.library.getAll();
   const identifiers = await selectReferencesOrExit(
     allReferences,
     { multiSelect: false },
-    config2.cli.interactive
+    config2.cli.tui
   );
   return identifiers[0];
 }
@@ -29919,14 +31036,16 @@ async function resolveUpdateIdentifier(identifierArg, hasSetOptions, context, co
       process.stderr.write(
         "Error: No identifier provided. Provide an ID, pipe one via stdin, or run interactively in a TTY.\n"
       );
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
+      return "";
     }
     return stdinId;
   }
   process.stderr.write(
     "Error: No identifier provided. When using stdin for JSON input, identifier must be provided as argument.\n"
   );
-  process.exit(1);
+  setExitCode(ExitCode.ERROR);
+  return "";
 }
 function parseUpdateInput(setOptions, file) {
   if (setOptions && setOptions.length > 0 && file) {
@@ -29947,23 +31066,25 @@ function handleUpdateError(error) {
   if (message.includes("Parse error")) {
     process.stderr.write(`Error: ${message}
 `);
-    process.exit(3);
+    setExitCode(3);
   }
   if (message.includes("not found") || message.includes("validation")) {
     process.stderr.write(`Error: ${message}
 `);
-    process.exit(1);
+    setExitCode(ExitCode.ERROR);
   }
   process.stderr.write(`Error: ${message}
 `);
-  process.exit(4);
+  setExitCode(ExitCode.INTERNAL_ERROR);
 }
 function handleUpdateErrorWithFormat(error, identifier, outputFormat) {
   const message = error instanceof Error ? error.message : String(error);
   if (outputFormat === "json") {
     process.stdout.write(`${JSON.stringify({ success: false, id: identifier, error: message })}
 `);
-    process.exit(message.includes("not found") || message.includes("validation") ? 1 : 4);
+    setExitCode(
+      message.includes("not found") || message.includes("validation") ? ExitCode.ERROR : ExitCode.INTERNAL_ERROR
+    );
   }
   handleUpdateError(error);
 }
@@ -29997,7 +31118,7 @@ async function handleUpdateAction(identifierArg, file, options, globalOpts) {
       process.stderr.write(`${output}
 `);
     }
-    process.exit(result.updated ? 0 : 1);
+    setExitCode(result.updated ? ExitCode.SUCCESS : ExitCode.ERROR);
   } catch (error) {
     handleUpdateErrorWithFormat(error, identifierArg ?? "", outputFormat);
   }
@@ -30007,8 +31128,13 @@ function collectSetOption(value, previous) {
 }
 const SEARCH_SORT_FIELDS = searchSortFieldSchema.options;
 const SORT_ORDERS = sortOrderSchema.options;
-const CITATION_FORMATS = ["text", "html", "rtf"];
+const CITATION_OUTPUT_FORMATS = ["text", "html", "rtf"];
+const EXPORT_OUTPUT_FORMATS = ["json", "yaml", "bibtex"];
+const LIST_OUTPUT_FORMATS = ["pretty", "json", "bibtex", "ids", "uuid"];
+const MUTATION_OUTPUT_FORMATS = ["json", "text"];
+const CONFIG_OUTPUT_FORMATS = ["text", "json"];
 const LOG_LEVELS = ["silent", "info", "debug"];
+const ADD_INPUT_FORMATS = ["json", "bibtex", "ris", "pmid", "doi", "isbn", "auto"];
 const CONFIG_SECTIONS = [
   "backup",
   "citation",
@@ -30019,17 +31145,44 @@ const CONFIG_SECTIONS = [
   "server",
   "watch"
 ];
+const ATTACHMENT_ROLES = ["fulltext", "supplement", "notes", "draft"];
 const OPTION_VALUES = {
   "--sort": SEARCH_SORT_FIELDS,
   // search includes 'relevance'
   "--order": SORT_ORDERS,
-  "--format": CITATION_FORMATS,
   "--style": BUILTIN_STYLES,
   "--log-level": LOG_LEVELS,
-  "--section": CONFIG_SECTIONS
+  "--section": CONFIG_SECTIONS,
+  "--input": ADD_INPUT_FORMATS,
+  "-i": ADD_INPUT_FORMATS,
+  "--role": ATTACHMENT_ROLES,
+  "-r": ATTACHMENT_ROLES
 };
+const OUTPUT_VALUES_BY_COMMAND = {
+  cite: CITATION_OUTPUT_FORMATS,
+  export: EXPORT_OUTPUT_FORMATS,
+  list: LIST_OUTPUT_FORMATS,
+  search: LIST_OUTPUT_FORMATS,
+  add: MUTATION_OUTPUT_FORMATS,
+  remove: MUTATION_OUTPUT_FORMATS,
+  update: MUTATION_OUTPUT_FORMATS
+  // config show uses CONFIG_OUTPUT_FORMATS, handled specially
+};
+function getOptionValuesForCommand(option, command, subcommand) {
+  if (option === "--output" || option === "-o") {
+    if (command === "config" && subcommand === "show") {
+      return CONFIG_OUTPUT_FORMATS;
+    }
+    if (command && OUTPUT_VALUES_BY_COMMAND[command]) {
+      return OUTPUT_VALUES_BY_COMMAND[command];
+    }
+    return CITATION_OUTPUT_FORMATS;
+  }
+  return OPTION_VALUES[option];
+}
 const ID_COMPLETION_COMMANDS = /* @__PURE__ */ new Set(["cite", "remove", "update"]);
 const ID_COMPLETION_FULLTEXT_SUBCOMMANDS = /* @__PURE__ */ new Set(["attach", "get", "detach", "open"]);
+const ID_COMPLETION_ATTACH_SUBCOMMANDS = /* @__PURE__ */ new Set(["open", "add", "list", "get", "detach", "sync"]);
 function toCompletionItems(values) {
   return values.map((name2) => ({ name: name2 }));
 }
@@ -30063,6 +31216,13 @@ function extractGlobalOptions(program) {
 function findSubcommand(program, name2) {
   return program.commands.find((cmd) => cmd.name() === name2);
 }
+function parseCommandContext(env) {
+  const words = env.line.trim().split(/\s+/);
+  const args = words.slice(1);
+  const command = args[0];
+  const subcommand = args.length >= 2 ? args[1] : void 0;
+  return { command, subcommand };
+}
 function getCompletions(env, program) {
   const { line, prev, last } = env;
   const words = line.trim().split(/\s+/);
@@ -30074,7 +31234,8 @@ function getCompletions(env, program) {
   }
   const firstArg = args[0] ?? "";
   if (prev?.startsWith("-")) {
-    const optionValues = OPTION_VALUES[prev];
+    const { command, subcommand } = parseCommandContext(env);
+    const optionValues = getOptionValuesForCommand(prev, command, subcommand);
     if (optionValues) {
       return toCompletionItems(optionValues);
     }
@@ -30114,6 +31275,13 @@ function needsIdCompletion(env) {
     }
     return { needs: false };
   }
+  if (command === "attach" && args.length >= 2) {
+    const subcommand = args[1] ?? "";
+    if (ID_COMPLETION_ATTACH_SUBCOMMANDS.has(subcommand)) {
+      return { needs: true, command, subcommand };
+    }
+    return { needs: false };
+  }
   if (ID_COMPLETION_COMMANDS.has(command)) {
     return { needs: true, command };
   }
@@ -30235,7 +31403,7 @@ function registerCompletionCommand(program) {
     } else {
       console.error(`Unknown action: ${action}`);
       console.error("Usage: ref completion [install|uninstall]");
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
     }
   });
 }
@@ -30253,6 +31421,7 @@ function createProgram() {
   registerCiteCommand(program);
   registerServerCommand(program);
   registerFulltextCommand(program);
+  registerAttachCommand(program);
   registerMcpCommand(program);
   registerConfigCommand(program);
   registerCompletionCommand(program);
@@ -30269,15 +31438,13 @@ async function handleListAction(options, program) {
       process.stdout.write(`${output}
 `);
     }
-    process.exit(0);
+    setExitCode(ExitCode.SUCCESS);
   } catch (error) {
-    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
-`);
-    process.exit(4);
+    exitWithError(error instanceof Error ? error.message : String(error), ExitCode.INTERNAL_ERROR);
   }
 }
 function registerListCommand(program) {
-  program.command("list").description("List all references in the library").option("--json", "Output in JSON format").option("--ids-only", "Output only citation keys").option("--uuid", "Output only UUIDs").option("--bibtex", "Output in BibTeX format").option("--sort <field>", "Sort by field: created|updated|published|author|title").option("--order <order>", "Sort order: asc|desc").option("-n, --limit <n>", "Maximum number of results", Number.parseInt).option("--offset <n>", "Number of results to skip", Number.parseInt).action(async (options) => {
+  program.command("list").description("List all references in the library").option("-o, --output <format>", "Output format: pretty|json|bibtex|ids|uuid").option("--json", "Alias for --output json").option("--bibtex", "Alias for --output bibtex").option("--ids-only", "Alias for --output ids").option("--uuid-only", "Alias for --output uuid").option("--sort <field>", "Sort by field: created|updated|published|author|title").option("--order <order>", "Sort order: asc|desc").option("-n, --limit <n>", "Maximum number of results", Number.parseInt).option("--offset <n>", "Number of results to skip", Number.parseInt).action(async (options) => {
     await handleListAction(options, program);
   });
 }
@@ -30298,15 +31465,15 @@ async function handleExportAction(ids, options, program) {
 `);
       }
     }
-    process.exit(getExportExitCode(result));
+    setExitCode(getExportExitCode(result));
   } catch (error) {
     process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(4);
+    setExitCode(ExitCode.INTERNAL_ERROR);
   }
 }
 function registerExportCommand(program) {
-  program.command("export [ids...]").description("Export raw CSL-JSON for external tool integration").option("--uuid", "Interpret identifiers as UUIDs").option("--all", "Export all references").option("--search <query>", "Export references matching search query").option("-f, --format <fmt>", "Output format: json (default), yaml, bibtex").action(async (ids, options) => {
+  program.command("export [ids...]").description("Export raw CSL-JSON for external tool integration").option("--uuid", "Interpret identifiers as UUIDs").option("--all", "Export all references").option("--search <query>", "Export references matching search query").option("-o, --output <format>", "Output format: json (default), yaml, bibtex").action(async (ids, options) => {
     await handleExportAction(ids, options, program);
   });
 }
@@ -30315,13 +31482,13 @@ async function handleSearchAction(query, options, program) {
     const globalOpts = program.opts();
     const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
     const context = await createExecutionContext(config2, Library.load);
-    if (options.interactive) {
+    if (options.tui) {
       const result2 = await executeInteractiveSearch({ ...options, query }, context, config2);
       if (result2.output) {
         process.stdout.write(`${result2.output}
 `);
       }
-      process.exit(result2.cancelled ? 0 : 0);
+      setExitCode(ExitCode.SUCCESS);
     }
     const result = await executeSearch({ ...options, query }, context);
     const output = formatSearchOutput(result, { ...options, query });
@@ -30329,18 +31496,19 @@ async function handleSearchAction(query, options, program) {
       process.stdout.write(`${output}
 `);
     }
-    process.exit(0);
+    setExitCode(ExitCode.SUCCESS);
   } catch (error) {
     process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(4);
+    setExitCode(ExitCode.INTERNAL_ERROR);
   }
 }
 function registerSearchCommand(program) {
-  program.command("search").description("Search references").argument("[query]", "Search query (required unless using --interactive)").option("-i, --interactive", "Enable interactive search mode").option("--json", "Output in JSON format").option("--ids-only", "Output only citation keys").option("--uuid", "Output only UUIDs").option("--bibtex", "Output in BibTeX format").option("--sort <field>", "Sort by field: created|updated|published|author|title|relevance").option("--order <order>", "Sort order: asc|desc").option("-n, --limit <n>", "Maximum number of results", Number.parseInt).option("--offset <n>", "Number of results to skip", Number.parseInt).action(async (query, options) => {
-    if (!options.interactive && !query) {
-      process.stderr.write("Error: Search query is required unless using --interactive\n");
-      process.exit(1);
+  program.command("search").description("Search references").argument("[query]", "Search query (required unless using --tui)").option("-t, --tui", "Enable TUI (interactive) search mode").option("-o, --output <format>", "Output format: pretty|json|bibtex|ids|uuid").option("--json", "Alias for --output json").option("--bibtex", "Alias for --output bibtex").option("--ids-only", "Alias for --output ids").option("--uuid-only", "Alias for --output uuid").option("--sort <field>", "Sort by field: created|updated|published|author|title|relevance").option("--order <order>", "Sort order: asc|desc").option("-n, --limit <n>", "Maximum number of results", Number.parseInt).option("--offset <n>", "Number of results to skip", Number.parseInt).action(async (query, options) => {
+    if (!options.tui && !query) {
+      process.stderr.write("Error: Search query is required unless using --tui\n");
+      setExitCode(ExitCode.ERROR);
+      return;
     }
     await handleSearchAction(query ?? "", options, program);
   });
@@ -30350,8 +31518,8 @@ function buildAddOptions(inputs, options, config2, stdinContent) {
     inputs,
     force: options.force ?? false
   };
-  if (options.format !== void 0) {
-    addOptions.format = options.format;
+  if (options.input !== void 0) {
+    addOptions.format = options.input;
   }
   if (options.verbose !== void 0) {
     addOptions.verbose = options.verbose;
@@ -30405,7 +31573,7 @@ async function handleAddAction(inputs, options, program) {
       process.stderr.write(`${output}
 `);
     }
-    process.exit(getExitCode(result));
+    setExitCode(getExitCode(result));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     if (outputFormat === "json") {
@@ -30415,15 +31583,11 @@ async function handleAddAction(inputs, options, program) {
       process.stderr.write(`Error: ${message}
 `);
     }
-    process.exit(1);
+    setExitCode(ExitCode.ERROR);
   }
 }
 function registerAddCommand(program) {
-  program.command("add").description("Add new reference(s) to the library").argument("[input...]", "File paths or identifiers (PMID/DOI/ISBN), or use stdin").option("-f, --force", "Skip duplicate detection").option(
-    "--format <format>",
-    "Explicit input format: json|bibtex|ris|pmid|doi|isbn|auto",
-    "auto"
-  ).option("--verbose", "Show detailed error information").option("-o, --output <format>", "Output format: json|text", "text").option("--full", "Include full CSL-JSON data in JSON output").action(async (inputs, options) => {
+  program.command("add").description("Add new reference(s) to the library").argument("[input...]", "File paths or identifiers (PMID/DOI/ISBN), or use stdin").option("-f, --force", "Skip duplicate detection").option("-i, --input <format>", "Input format: json|bibtex|ris|pmid|doi|isbn|auto", "auto").option("--verbose", "Show detailed error information").option("-o, --output <format>", "Output format: json|text", "text").option("--full", "Include full CSL-JSON data in JSON output").action(async (inputs, options) => {
     await handleAddAction(inputs, options, program);
   });
 }
@@ -30441,7 +31605,7 @@ function registerEditCommand(program) {
   program.command("edit").description("Edit references interactively using an external editor").argument(
     "[identifier...]",
     "Citation keys or UUIDs to edit (interactive selection if omitted)"
-  ).option("--uuid", "Interpret identifiers as UUIDs").option("-f, --format <format>", "Edit format: yaml (default), json").option("--editor <editor>", "Editor command (overrides $VISUAL/$EDITOR)").action(async (identifiers, options) => {
+  ).option("--uuid", "Interpret identifiers as UUIDs").option("--format <format>", "Edit format: yaml (default), json").option("--editor <editor>", "Editor command (overrides $VISUAL/$EDITOR)").action(async (identifiers, options) => {
     await handleEditAction(identifiers, options, program.opts());
   });
 }
@@ -30449,7 +31613,7 @@ function registerCiteCommand(program) {
   program.command("cite").description("Generate formatted citations for references").argument(
     "[id-or-uuid...]",
     "Citation keys or UUIDs to cite (interactive selection if omitted)"
-  ).option("--uuid", "Treat arguments as UUIDs instead of IDs").option("--style <style>", "CSL style name").option("--csl-file <path>", "Path to custom CSL file").option("--locale <locale>", "Locale code (e.g., en-US, ja-JP)").option("--format <format>", "Output format: text|html|rtf").option("--in-text", "Generate in-text citations instead of bibliography entries").action(async (identifiers, options) => {
+  ).option("--uuid", "Treat arguments as UUIDs instead of IDs").option("--style <style>", "CSL style name").option("--csl-file <path>", "Path to custom CSL file").option("--locale <locale>", "Locale code (e.g., en-US, ja-JP)").option("-o, --output <format>", "Output format: text|html|rtf").option("--in-text", "Generate in-text citations instead of bibliography entries").action(async (identifiers, options) => {
     await handleCiteAction(identifiers, options, program.opts());
   });
 }
@@ -30469,18 +31633,18 @@ function registerServerCommand(program) {
       };
       await serverStart(startOptions);
       if (options.daemon) {
-        process.exit(0);
+        setExitCode(ExitCode.SUCCESS);
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       if (message.includes("already running") || message.includes("conflict")) {
         process.stderr.write(`Error: ${message}
 `);
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
       }
       process.stderr.write(`Error: ${message}
 `);
-      process.exit(4);
+      setExitCode(ExitCode.INTERNAL_ERROR);
     }
   });
   serverCmd.command("stop").description("Stop running server").action(async () => {
@@ -30488,17 +31652,17 @@ function registerServerCommand(program) {
       const portfilePath = getPortfilePath();
       await serverStop(portfilePath);
       process.stderr.write("Server stopped.\n");
-      process.exit(0);
+      setExitCode(ExitCode.SUCCESS);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       if (message.includes("not running")) {
         process.stderr.write(`Error: ${message}
 `);
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
       }
       process.stderr.write(`Error: ${message}
 `);
-      process.exit(4);
+      setExitCode(ExitCode.INTERNAL_ERROR);
     }
   });
   serverCmd.command("status").description("Check server status").action(async () => {
@@ -30513,15 +31677,15 @@ PID: ${status.pid}
 Library: ${status.library}
 `
         );
-        process.exit(0);
+        setExitCode(ExitCode.SUCCESS);
       } else {
         process.stdout.write("Server not running\n");
-        process.exit(1);
+        setExitCode(ExitCode.ERROR);
       }
     } catch (error) {
       process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      process.exit(4);
+      setExitCode(ExitCode.INTERNAL_ERROR);
     }
   });
 }
@@ -30550,10 +31714,34 @@ function registerMcpCommand(program) {
     } catch (error) {
       process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      process.exit(1);
+      setExitCode(ExitCode.ERROR);
     }
   });
 }
+function registerAttachCommand(program) {
+  const attachCmd = program.command("attach").description("Manage file attachments for references");
+  attachCmd.command("open").description("Open attachments directory or specific file").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").argument("[filename]", "Specific file to open").option("--role <role>", "Open file by role").option("--print", "Output path instead of opening").option("--no-sync", "Skip interactive sync prompt").option("--uuid", "Interpret identifier as UUID").action(async (identifier, filename, options) => {
+    await handleAttachOpenAction(identifier, filename, options, program.opts());
+  });
+  attachCmd.command("add").description("Add a file attachment to a reference").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").argument("<file-path>", "Path to the file to attach").requiredOption(
+    "--role <role>",
+    "Role for the file (fulltext, supplement, notes, draft, or custom)"
+  ).option("--label <label>", "Human-readable label").option("--move", "Move file instead of copy").option("-f, --force", "Overwrite existing attachment").option("--uuid", "Interpret identifier as UUID").action(async (identifier, filePath, options) => {
+    await handleAttachAddAction(identifier, filePath, options, program.opts());
+  });
+  attachCmd.command("list").description("List attachments for a reference").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").option("--role <role>", "Filter by role").option("--uuid", "Interpret identifier as UUID").action(async (identifier, options) => {
+    await handleAttachListAction(identifier, options, program.opts());
+  });
+  attachCmd.command("get").description("Get attachment file path or content").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").argument("[filename]", "Specific file to get").option("--role <role>", "Get file by role").option("--stdout", "Output file content to stdout").option("--uuid", "Interpret identifier as UUID").action(async (identifier, filename, options) => {
+    await handleAttachGetAction(identifier, filename, options, program.opts());
+  });
+  attachCmd.command("detach").description("Detach file from a reference").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").argument("[filename]", "Specific file to detach").option("--role <role>", "Detach files by role").option("--all", "Detach all files of specified role").option("--remove-files", "Also delete files from disk").option("--uuid", "Interpret identifier as UUID").action(async (identifier, filename, options) => {
+    await handleAttachDetachAction(identifier, filename, options, program.opts());
+  });
+  attachCmd.command("sync").description("Synchronize metadata with files on disk").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").option("--yes", "Apply changes (add new files)").option("--fix", "Remove missing files from metadata").option("--uuid", "Interpret identifier as UUID").action(async (identifier, options) => {
+    await handleAttachSyncAction(identifier, options, program.opts());
+  });
+}
 function registerFulltextCommand(program) {
   const fulltextCmd = program.command("fulltext").description("Manage full-text files attached to references");
   fulltextCmd.command("attach").description("Attach a full-text file to a reference").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").argument("[file-path]", "Path to the file to attach").option("--pdf [path]", "Attach as PDF (path optional if provided as argument)").option("--markdown [path]", "Attach as Markdown (path optional if provided as argument)").option("--move", "Move file instead of copy").option("-f, --force", "Overwrite existing attachment").option("--uuid", "Interpret identifier as UUID").action(async (identifier, filePath, options) => {
@@ -30562,7 +31750,7 @@ function registerFulltextCommand(program) {
   fulltextCmd.command("get").description("Get full-text file path or content").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").option("--pdf", "Get PDF file only").option("--markdown", "Get Markdown file only").option("--stdout", "Output file content to stdout").option("--uuid", "Interpret identifier as UUID").action(async (identifier, options) => {
     await handleFulltextGetAction(identifier, options, program.opts());
   });
-  fulltextCmd.command("detach").description("Detach full-text file from a reference").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").option("--pdf", "Detach PDF only").option("--markdown", "Detach Markdown only").option("--delete", "Also delete the file from disk").option("-f, --force", "Skip confirmation for delete").option("--uuid", "Interpret identifier as UUID").action(async (identifier, options) => {
+  fulltextCmd.command("detach").description("Detach full-text file from a reference").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").option("--pdf", "Detach PDF only").option("--markdown", "Detach Markdown only").option("--remove-files", "Also delete the file from disk").option("-f, --force", "Skip confirmation for file removal").option("--uuid", "Interpret identifier as UUID").action(async (identifier, options) => {
     await handleFulltextDetachAction(identifier, options, program.opts());
   });
   fulltextCmd.command("open").description("Open full-text file with system default application").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").option("--pdf", "Open PDF file").option("--markdown", "Open Markdown file").option("--uuid", "Interpret identifier as UUID").action(async (identifier, options) => {
@@ -30576,16 +31764,22 @@ async function main(argv) {
     return;
   }
   process.on("SIGINT", () => {
-    process.exit(130);
+    setExitCode(ExitCode.SIGINT);
   });
   process.on("SIGTERM", () => {
-    process.exit(0);
+    setExitCode(ExitCode.SUCCESS);
   });
   await program.parseAsync(argv);
 }
 export {
+  addAttachment as a,
   createProgram as c,
+  detachAttachment as d,
   formatBibtex as f,
-  main as m
+  getAttachment as g,
+  listAttachments as l,
+  main as m,
+  openAttachment as o,
+  syncAttachments as s
 };
-//# sourceMappingURL=index-CXoDLO8W.js.map
+//# sourceMappingURL=index-B4RmLBI1.js.map