@ncukondo/reference-manager 0.14.0 → 0.15.0

package/dist/chunks/{index-UpzsmbyY.js → index-Bv5IgsL-.js}

@@ -1,22 +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, mkdtempSync, writeFileSync } 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, 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-4FFB4igw.js";
 import { spawn, spawnSync } from "node:child_process";
 import process$1, { stdin, stdout } from "node:process";
-import { l as loadConfig, o as openWithSystemApp } from "./loader-C1EpnyPm.js";
-import { mkdir, unlink, rename, copyFile, rm, readFile } from "node:fs/promises";
-import { u as updateReference, B as BUILTIN_STYLES, g as getFulltextAttachmentTypes, s as startServerWithFileWatcher } from "./index-4KSTJ3rp.js";
+import { parse as parse$2, stringify as stringify$2 } from "@iarna/toml";
 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.0";
+const version$1 = "0.15.0";
 const description$1 = "A local reference management tool using CSL-JSON as the single source of truth";
 const packageJson = {
   name,
@@ -260,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;
@@ -286,15 +879,15 @@ class OperationsLibrary {
   }
   // High-level operations
   async search(options) {
-    const { searchReferences } = await import("./index-4KSTJ3rp.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-4KSTJ3rp.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-4KSTJ3rp.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 = {
@@ -305,9 +898,34 @@ class OperationsLibrary {
     return citeReferences(this.library, mergedOptions);
   }
   async import(inputs, options) {
-    const { addReferences } = await import("./index-4KSTJ3rp.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-B_WCu-ZQ.js");
+    return addAttachment2(this.library, options);
+  }
+  async attachList(options) {
+    const { listAttachments: listAttachments2 } = await import("./index-B_WCu-ZQ.js");
+    return listAttachments2(this.library, options);
+  }
+  async attachGet(options) {
+    const { getAttachment: getAttachment2 } = await import("./index-B_WCu-ZQ.js");
+    return getAttachment2(this.library, options);
+  }
+  async attachDetach(options) {
+    const { detachAttachment: detachAttachment2 } = await import("./index-B_WCu-ZQ.js");
+    return detachAttachment2(this.library, options);
+  }
+  async attachSync(options) {
+    const { syncAttachments: syncAttachments2 } = await import("./index-B_WCu-ZQ.js");
+    return syncAttachments2(this.library, options);
+  }
+  async attachOpen(options) {
+    const { openAttachment: openAttachment2 } = await import("./index-B_WCu-ZQ.js");
+    return openAttachment2(this.library, options);
+  }
 }
 class ServerClient {
   constructor(baseUrl) {
@@ -494,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) {
@@ -652,145 +1375,1411 @@ async function readStdinBuffer() {
   }
   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.cslFile) {
-    const fs2 = await import("node:fs");
-    if (!fs2.existsSync(options.cslFile)) {
-      throw new Error(`CSL file '${options.cslFile}' not found`);
-    }
-  }
+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);
 }
-function buildCiteOptions(options) {
-  return {
-    identifiers: options.identifiers,
-    ...options.uuid && { idType: "uuid" },
-    ...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.inText !== void 0 && { inText: options.inText }
+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 executeCite(options, context) {
-  await validateOptions$2(options);
-  return context.library.cite(buildCiteOptions(options));
+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);
 }
-function formatCiteOutput(result) {
+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 = [];
-  for (const r of result.results) {
-    if (r.success) {
-      lines.push(r.citation);
+  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");
+  return lines.join("\n").trimEnd();
 }
-function formatCiteErrors(result) {
+function formatAttachDetachOutput(result) {
+  if (!result.success) {
+    return `Error: ${result.error}`;
+  }
   const lines = [];
-  for (const r of result.results) {
-    if (!r.success) {
-      lines.push(`Error for '${r.identifier}': ${r.error}`);
+  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 getCiteExitCode(result) {
-  const hasSuccess = result.results.some((r) => r.success);
-  const hasError = result.results.some((r) => !r.success);
-  if (hasSuccess) {
-    return 0;
+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}`);
   }
-  if (hasError) {
-    return 1;
+  lines.push("");
+}
+function formatAttachSyncOutput(result) {
+  if (!result.success) {
+    return `Error: ${result.error}`;
   }
-  return 0;
+  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) {
+    if (hasNewFiles) {
+      lines.push("Run with --yes to add new files");
+    }
+    if (hasMissingFiles) {
+      lines.push("Run with --fix to remove missing files");
+    }
+  }
+  return lines.join("\n").trimEnd();
 }
-async function executeInteractiveCite(options, context, config2) {
-  const { selectReferencesOrExit } = await import("./reference-select-DSVwE9iu.js");
-  const { runStyleSelect } = await import("./style-select-CHjDTyq2.js");
+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: true },
-    config2.cli.interactive
+    { multiSelect: false },
+    config2.cli.tui
   );
-  let style = options.style;
-  if (!style && !options.cslFile) {
-    const styleResult = await runStyleSelect({
-      cslDirectory: config2.citation.cslDirectory,
-      defaultStyle: config2.citation.defaultStyle
+  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"
+    );
+    process.exit(1);
+  }
+  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();
     });
-    if (styleResult.cancelled) {
+  });
+}
+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}
+`);
+      process.exit(1);
+    }
+    if (options.print) {
+      process.stdout.write(`${result.path}
+`);
       process.exit(0);
     }
-    style = styleResult.style;
+    if (shouldUseInteractive) {
+      await runInteractiveMode(
+        identifier,
+        result.path ?? "",
+        config2.attachments.directory,
+        options.uuid ? "uuid" : void 0,
+        context
+      );
+    } else {
+      process.stderr.write(`${formatAttachOpenOutput(result)}
+`);
+    }
+    process.exit(0);
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
   }
-  return executeCite({ ...options, ...style && { style }, identifiers }, context);
 }
-async function handleCiteAction(identifiers, options, globalOpts) {
+async function handleAttachAddAction(identifierArg, filePathArg, options, globalOpts) {
   try {
     const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
     const context = await createExecutionContext(config2, Library.load);
-    let result;
-    if (identifiers.length === 0) {
-      if (isTTY()) {
-        result = await executeInteractiveCite(options, context, config2);
-      } else {
-        const stdinIds = await readIdentifiersFromStdin();
-        if (stdinIds.length === 0) {
-          process.stderr.write(
-            "Error: No identifiers provided. Provide IDs, pipe them via stdin, or run interactively in a TTY.\n"
-          );
-          process.exit(1);
-        }
-        result = await executeCite({ ...options, identifiers: stdinIds }, context);
-      }
-    } else {
-      result = await executeCite({ ...options, identifiers }, context);
+    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}
+`);
+    process.exit(getAttachExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
+  }
+}
+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}
+`);
+    process.exit(getAttachExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
+  }
+}
+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}
+`);
+    }
+    process.exit(getAttachExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
+  }
+}
+async function handleAttachDetachAction(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 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}
+`);
+    process.exit(getAttachExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
+  }
+}
+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 syncOptions = {
+      identifier,
+      attachmentsDirectory: config2.attachments.directory,
+      ...options.yes && { yes: options.yes },
+      ...options.fix && { fix: options.fix },
+      ...options.uuid && { idType: "uuid" }
+    };
+    const result = await executeAttachSync(syncOptions, context);
+    const output = formatAttachSyncOutput(result);
+    process.stderr.write(`${output}
+`);
+    process.exit(getAttachExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
+  }
+}
+async function validateOptions$2(options) {
+  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");
+    if (!fs2.existsSync(options.cslFile)) {
+      throw new Error(`CSL file '${options.cslFile}' not found`);
+    }
+  }
+}
+function buildCiteOptions(options) {
+  return {
+    identifiers: options.identifiers,
+    ...options.uuid && { idType: "uuid" },
+    ...options.style !== void 0 && { style: options.style },
+    ...options.cslFile !== void 0 && { cslFile: options.cslFile },
+    ...options.locale !== void 0 && { locale: options.locale },
+    ...options.output !== void 0 && { format: options.output },
+    ...options.inText !== void 0 && { inText: options.inText }
+  };
+}
+async function executeCite(options, context) {
+  await validateOptions$2(options);
+  return context.library.cite(buildCiteOptions(options));
+}
+function formatCiteOutput(result) {
+  const lines = [];
+  for (const r of result.results) {
+    if (r.success) {
+      lines.push(r.citation);
+    }
+  }
+  return lines.join("\n");
+}
+function formatCiteErrors(result) {
+  const lines = [];
+  for (const r of result.results) {
+    if (!r.success) {
+      lines.push(`Error for '${r.identifier}': ${r.error}`);
+    }
+  }
+  return lines.join("\n");
+}
+function getCiteExitCode(result) {
+  const hasSuccess = result.results.some((r) => r.success);
+  const hasError = result.results.some((r) => !r.success);
+  if (hasSuccess) {
+    return 0;
+  }
+  if (hasError) {
+    return 1;
+  }
+  return 0;
+}
+async function executeInteractiveCite(options, context, config2) {
+  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.tui
+  );
+  let style = options.style;
+  if (!style && !options.cslFile) {
+    const styleResult = await runStyleSelect({
+      cslDirectory: config2.citation.cslDirectory,
+      defaultStyle: config2.citation.defaultStyle
+    });
+    if (styleResult.cancelled) {
+      process.exit(0);
+    }
+    style = styleResult.style;
+  }
+  return executeCite({ ...options, ...style && { style }, identifiers }, context);
+}
+async function handleCiteAction(identifiers, options, globalOpts) {
+  try {
+    const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config2, Library.load);
+    let result;
+    if (identifiers.length === 0) {
+      if (isTTY()) {
+        result = await executeInteractiveCite(options, context, config2);
+      } else {
+        const stdinIds = await readIdentifiersFromStdin();
+        if (stdinIds.length === 0) {
+          process.stderr.write(
+            "Error: No identifiers provided. Provide IDs, pipe them via stdin, or run interactively in a TTY.\n"
+          );
+          process.exit(1);
+        }
+        result = await executeCite({ ...options, identifiers: stdinIds }, context);
+      }
+    } else {
+      result = await executeCite({ ...options, identifiers }, context);
+    }
+    const output = formatCiteOutput(result);
+    if (output) {
+      process.stdout.write(`${output}
+`);
+    }
+    const errors2 = formatCiteErrors(result);
+    if (errors2) {
+      process.stderr.write(`${errors2}
+`);
+    }
+    process.exit(getCiteExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
+  }
+}
+const ENV_OVERRIDE_MAP = {
+  REFERENCE_MANAGER_LIBRARY: "library",
+  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",
+  PUBMED_API_KEY: "pubmed.api_key"
+};
+const KEY_TO_ENV_MAP = Object.fromEntries(
+  Object.entries(ENV_OVERRIDE_MAP).map(([envVar, configKey]) => [configKey, envVar])
+);
+function getEnvOverrideInfo(configKey) {
+  const envVar = KEY_TO_ENV_MAP[configKey];
+  if (!envVar) {
+    return null;
+  }
+  const value = process.env[envVar];
+  return {
+    envVar,
+    value: value ?? null
+  };
+}
+const CONFIG_KEY_REGISTRY = [
+  // Top-level keys
+  { key: "library", type: "string", description: "Path to library file" },
+  {
+    key: "log_level",
+    type: "enum",
+    description: "Log level",
+    enumValues: ["silent", "info", "debug"]
+  },
+  // backup section
+  { key: "backup.max_generations", type: "integer", description: "Maximum backup generations" },
+  { key: "backup.max_age_days", type: "integer", description: "Maximum backup age in days" },
+  { key: "backup.directory", type: "string", description: "Backup directory path" },
+  // watch section
+  { key: "watch.debounce_ms", type: "integer", description: "File watch debounce delay (ms)" },
+  { key: "watch.poll_interval_ms", type: "integer", description: "File watch poll interval (ms)" },
+  {
+    key: "watch.retry_interval_ms",
+    type: "integer",
+    description: "File watch retry interval (ms)"
+  },
+  { key: "watch.max_retries", type: "integer", description: "Maximum file watch retries" },
+  // server section
+  { key: "server.auto_start", type: "boolean", description: "Auto-start server on CLI commands" },
+  {
+    key: "server.auto_stop_minutes",
+    type: "integer",
+    description: "Auto-stop server after idle minutes (0 = never)"
+  },
+  // citation section
+  { key: "citation.default_style", type: "string", description: "Default citation style" },
+  { key: "citation.csl_directory", type: "string[]", description: "CSL style file directories" },
+  { key: "citation.default_locale", type: "string", description: "Default locale for citations" },
+  {
+    key: "citation.default_format",
+    type: "enum",
+    description: "Default format",
+    enumValues: ["text", "html", "rtf"]
+  },
+  // pubmed section
+  { key: "pubmed.email", type: "string", description: "Email for PubMed API", optional: true },
+  { key: "pubmed.api_key", type: "string", description: "API key for PubMed", optional: true },
+  // fulltext section
+  { key: "fulltext.directory", type: "string", description: "Fulltext storage directory" },
+  // cli section
+  {
+    key: "cli.default_limit",
+    type: "integer",
+    description: "Default result limit (0 = unlimited)"
+  },
+  {
+    key: "cli.default_sort",
+    type: "enum",
+    description: "Default sort field",
+    enumValues: ["created", "updated", "published", "author", "title"]
+  },
+  {
+    key: "cli.default_order",
+    type: "enum",
+    description: "Default sort order",
+    enumValues: ["asc", "desc"]
+  },
+  // cli.tui section
+  {
+    key: "cli.tui.limit",
+    type: "integer",
+    description: "Result limit in TUI mode"
+  },
+  {
+    key: "cli.tui.debounce_ms",
+    type: "integer",
+    description: "Search debounce delay (ms)"
+  },
+  // cli.edit section
+  {
+    key: "cli.edit.default_format",
+    type: "enum",
+    description: "Default edit format",
+    enumValues: ["yaml", "json"]
+  },
+  // mcp section
+  { key: "mcp.default_limit", type: "integer", description: "Default result limit for MCP" }
+];
+const KEY_MAP = new Map(CONFIG_KEY_REGISTRY.map((info) => [info.key, info]));
+let allKeysCache = null;
+function parseConfigKey(key) {
+  return key.split(".");
+}
+function isValidConfigKey(key) {
+  if (!key) {
+    return false;
+  }
+  return KEY_MAP.has(key);
+}
+function getConfigKeyInfo(key) {
+  return KEY_MAP.get(key) ?? null;
+}
+function getAllConfigKeys(section) {
+  if (!allKeysCache) {
+    allKeysCache = CONFIG_KEY_REGISTRY.map((info) => info.key).sort();
+  }
+  if (!section) {
+    return allKeysCache;
+  }
+  const prefix = `${section}.`;
+  return allKeysCache.filter((key) => key.startsWith(prefix));
+}
+function toInternalPath(key) {
+  const segments = parseConfigKey(key);
+  return segments.map((segment, index) => {
+    if (index === 0) {
+      if (segment === "log_level") {
+        return "logLevel";
+      }
+      return segment;
+    }
+    return snakeToCamel(segment);
+  });
+}
+function snakeToCamel(str2) {
+  return str2.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function validateConfigValue(key, value) {
+  const keyInfo = getConfigKeyInfo(key);
+  if (!keyInfo) {
+    return { valid: false, error: `Unknown configuration key: '${key}'` };
+  }
+  return validateByType(keyInfo, value);
+}
+function validateByType(keyInfo, value) {
+  switch (keyInfo.type) {
+    case "string":
+      return validateString(keyInfo, value);
+    case "integer":
+      return validateInteger(keyInfo, value);
+    case "boolean":
+      return validateBoolean(value);
+    case "enum":
+      return validateEnum(keyInfo, value);
+    case "string[]":
+      return validateStringArray(value);
+    default:
+      return { valid: false, error: `Unknown type: ${keyInfo.type}` };
+  }
+}
+function validateString(keyInfo, value) {
+  if (typeof value !== "string") {
+    return { valid: false, error: `Expected string, received ${typeof value}` };
+  }
+  if (value === "" && !keyInfo.optional) {
+    return { valid: false, error: "Value cannot be empty" };
+  }
+  return { valid: true, value };
+}
+function validateInteger(keyInfo, value) {
+  if (typeof value !== "number") {
+    return { valid: false, error: `Expected number, received ${typeof value}` };
+  }
+  if (!Number.isInteger(value)) {
+    return { valid: false, error: "Value must be an integer" };
+  }
+  const requiresPositive = keyInfo.key.startsWith("backup.") && keyInfo.key !== "backup.directory";
+  if (requiresPositive && value <= 0) {
+    return { valid: false, error: "Value must be a positive integer" };
+  }
+  if (!requiresPositive && value < 0) {
+    return { valid: false, error: "Value must be a non-negative integer" };
+  }
+  return { valid: true, value };
+}
+function validateBoolean(value) {
+  if (typeof value !== "boolean") {
+    return { valid: false, error: `Expected boolean, received ${typeof value}` };
+  }
+  return { valid: true, value };
+}
+function validateEnum(keyInfo, value) {
+  if (typeof value !== "string") {
+    return { valid: false, error: `Expected string, received ${typeof value}` };
+  }
+  const allowedValues = keyInfo.enumValues ?? [];
+  if (!allowedValues.includes(value)) {
+    return {
+      valid: false,
+      error: `Invalid value '${value}'. Expected one of: ${allowedValues.join(", ")}`
+    };
+  }
+  return { valid: true, value };
+}
+function validateStringArray(value) {
+  if (!Array.isArray(value)) {
+    return { valid: false, error: "Expected array" };
+  }
+  for (const item of value) {
+    if (typeof item !== "string") {
+      return { valid: false, error: "All array elements must be strings" };
+    }
+  }
+  return { valid: true, value };
+}
+function parseValueForKey(key, stringValue) {
+  const keyInfo = getConfigKeyInfo(key);
+  if (!keyInfo) {
+    return null;
+  }
+  switch (keyInfo.type) {
+    case "string":
+    case "enum":
+      return stringValue;
+    case "integer": {
+      const num = Number(stringValue);
+      if (Number.isNaN(num)) {
+        return stringValue;
+      }
+      return num;
+    }
+    case "boolean":
+      if (stringValue === "true") return true;
+      if (stringValue === "false") return false;
+      return stringValue;
+    // Let validation catch the error
+    case "string[]":
+      return stringValue.split(",").map((s) => s.trim());
+    default:
+      return stringValue;
+  }
+}
+function getConfigEditTarget(options, context) {
+  const cwd = process.cwd();
+  let path2;
+  if (options.local) {
+    path2 = join(cwd, getDefaultCurrentDirConfigFilename());
+  } else {
+    path2 = getDefaultUserConfigPath();
+  }
+  return {
+    path: path2,
+    exists: existsSync(path2)
+  };
+}
+function createConfigTemplate() {
+  return `# Reference Manager Configuration
+# Documentation: https://github.com/ncukondo/reference-manager#configuration
+
+# library = "~/.local/share/reference-manager/library.json"
+# log_level = "info"  # silent, info, debug
+
+[backup]
+# max_generations = 50
+# max_age_days = 365
+# directory = "~/.cache/reference-manager/backups"
+
+[server]
+# auto_start = false
+# auto_stop_minutes = 0
+
+[citation]
+# default_style = "apa"
+# default_locale = "en-US"
+# default_format = "text"  # text, html, rtf
+# csl_directory = ["~/.local/share/reference-manager/csl"]
+
+[pubmed]
+# email = ""
+# api_key = ""
+
+[fulltext]
+# directory = "~/.local/share/reference-manager/fulltext"
+
+[cli]
+# default_limit = 0  # 0 = unlimited
+# default_sort = "updated"  # created, updated, published, author, title
+# default_order = "desc"  # asc, desc
+
+[cli.tui]
+# limit = 20
+# debounce_ms = 200
+
+[cli.edit]
+# default_format = "yaml"  # yaml, json
+
+[mcp]
+# default_limit = 20
+`;
+}
+function getConfigValue(config2, key, options) {
+  if (!isValidConfigKey(key)) {
+    return { found: false, error: `Unknown configuration key: '${key}'` };
+  }
+  if (options.envOverride !== void 0 && !options.configOnly) {
+    return {
+      found: true,
+      value: options.envOverride,
+      fromEnv: true
+    };
+  }
+  const internalPath = toInternalPath(key);
+  const value = getNestedValue(config2, internalPath);
+  if (value === void 0 || value === null) {
+    return { found: false, error: `Value for '${key}' is not set` };
+  }
+  return { found: true, value };
+}
+function getNestedValue(obj, path2) {
+  let current = obj;
+  for (const segment of path2) {
+    if (current === null || current === void 0) {
+      return void 0;
+    }
+    if (typeof current !== "object") {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+function formatValue(value) {
+  if (Array.isArray(value)) {
+    return value.join(",");
+  }
+  if (typeof value === "object" && value !== null) {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+const get = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  formatValue,
+  getConfigValue
+}, Symbol.toStringTag, { value: "Module" }));
+function listConfigKeys(options) {
+  const keys = getAllConfigKeys(options.section);
+  if (keys.length === 0) {
+    return "";
+  }
+  const entries = keys.map((key) => {
+    const info = getConfigKeyInfo(key);
+    if (!info) {
+      return null;
+    }
+    return {
+      key: info.key,
+      type: info.type,
+      description: info.description
+    };
+  }).filter((e) => e !== null);
+  const maxKeyWidth = Math.max(...entries.map((e) => e.key.length));
+  const maxTypeWidth = Math.max(...entries.map((e) => e.type.length));
+  const lines = entries.map((entry) => {
+    const keyPadded = entry.key.padEnd(maxKeyWidth);
+    const typePadded = entry.type.padEnd(maxTypeWidth);
+    return `${keyPadded}  ${typePadded}  ${entry.description}`;
+  });
+  return lines.join("\n");
+}
+function getExistenceStatus(path2) {
+  return existsSync(path2) ? "exists" : "not found";
+}
+function showConfigPaths(options, context) {
+  const cwd = process.cwd();
+  const userConfigPath = getDefaultUserConfigPath();
+  const localConfigPath = join(cwd, getDefaultCurrentDirConfigFilename());
+  const envConfigPath = process.env.REFERENCE_MANAGER_CONFIG;
+  if (options.user) {
+    return userConfigPath;
+  }
+  if (options.local) {
+    return localConfigPath;
+  }
+  const lines = [];
+  lines.push(`User:    ${userConfigPath} (${getExistenceStatus(userConfigPath)})`);
+  lines.push(`Local:   ${localConfigPath} (${getExistenceStatus(localConfigPath)})`);
+  if (envConfigPath) {
+    lines.push(
+      `Env:     ${envConfigPath} (${getExistenceStatus(envConfigPath)}) (REFERENCE_MANAGER_CONFIG)`
+    );
+  }
+  return lines.join("\n");
+}
+function serializeToTOML$1(obj) {
+  return stringify$2(obj);
+}
+function parseKeyPath(key) {
+  return key.split(".");
+}
+function setNestedValue(obj, keyPath, value) {
+  if (keyPath.length === 0) {
+    return;
+  }
+  let current = obj;
+  for (let i = 0; i < keyPath.length - 1; i++) {
+    const segment = keyPath[i];
+    if (!(segment in current) || typeof current[segment] !== "object") {
+      current[segment] = {};
+    }
+    current = current[segment];
+  }
+  const finalKey = keyPath[keyPath.length - 1];
+  current[finalKey] = value;
+}
+function removeNestedValue(obj, keyPath) {
+  if (keyPath.length === 0) {
+    return false;
+  }
+  const firstKey = keyPath[0];
+  if (keyPath.length === 1) {
+    if (firstKey in obj) {
+      delete obj[firstKey];
+      return true;
+    }
+    return false;
+  }
+  if (!(firstKey in obj) || typeof obj[firstKey] !== "object") {
+    return false;
+  }
+  const nested = obj[firstKey];
+  const removed = removeNestedValue(nested, keyPath.slice(1));
+  if (removed && Object.keys(nested).length === 0) {
+    delete obj[firstKey];
+  }
+  return removed;
+}
+function loadExistingTOML(filePath) {
+  if (!existsSync(filePath)) {
+    return {};
+  }
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    return parse$2(content);
+  } catch {
+    return {};
+  }
+}
+async function writeTOMLValue(filePath, key, value) {
+  const dir = dirname(filePath);
+  await mkdir(dir, { recursive: true });
+  const obj = loadExistingTOML(filePath);
+  const keyPath = parseKeyPath(key);
+  setNestedValue(obj, keyPath, value);
+  const content = serializeToTOML$1(obj);
+  writeFileSync(filePath, content, "utf-8");
+}
+async function removeTOMLKey(filePath, key) {
+  if (!existsSync(filePath)) {
+    return;
+  }
+  const obj = loadExistingTOML(filePath);
+  const keyPath = parseKeyPath(key);
+  const removed = removeNestedValue(obj, keyPath);
+  if (removed) {
+    const content = serializeToTOML$1(obj);
+    writeFileSync(filePath, content, "utf-8");
+  }
+}
+async function setConfigValue(configPath, key, value, options = {}) {
+  if (!isValidConfigKey(key)) {
+    return { success: false, error: `Unknown configuration key: '${key}'` };
+  }
+  const validation2 = validateConfigValue(key, value);
+  if (!validation2.valid) {
+    return { success: false, error: validation2.error ?? "Validation failed" };
+  }
+  try {
+    await writeTOMLValue(configPath, key, value);
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to write config: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  if (options.envOverrideInfo?.value !== void 0 && options.envOverrideInfo?.value !== null) {
+    const warning = `Warning: '${key}' is overridden by environment variable ${options.envOverrideInfo.envVar}
+  Environment value: ${options.envOverrideInfo.value}
+  Config file value: ${value} (saved but inactive)
+
+The environment variable takes precedence. To use the config file value,
+unset the environment variable: unset ${options.envOverrideInfo.envVar}`;
+    return { success: true, warning };
+  }
+  return { success: true };
+}
+function toSnakeCaseConfig(config2) {
+  const result = {};
+  result.library = config2.library;
+  result.log_level = config2.logLevel;
+  result.backup = {
+    max_generations: config2.backup.maxGenerations,
+    max_age_days: config2.backup.maxAgeDays,
+    directory: config2.backup.directory
+  };
+  result.watch = {
+    debounce_ms: config2.watch.debounceMs,
+    poll_interval_ms: config2.watch.pollIntervalMs,
+    retry_interval_ms: config2.watch.retryIntervalMs,
+    max_retries: config2.watch.maxRetries
+  };
+  result.server = {
+    auto_start: config2.server.autoStart,
+    auto_stop_minutes: config2.server.autoStopMinutes
+  };
+  result.citation = {
+    default_style: config2.citation.defaultStyle,
+    csl_directory: config2.citation.cslDirectory,
+    default_locale: config2.citation.defaultLocale,
+    default_format: config2.citation.defaultFormat
+  };
+  result.pubmed = {
+    email: config2.pubmed.email,
+    api_key: config2.pubmed.apiKey
+  };
+  result.fulltext = {
+    directory: config2.fulltext.directory
+  };
+  result.cli = {
+    default_limit: config2.cli.defaultLimit,
+    default_sort: config2.cli.defaultSort,
+    default_order: config2.cli.defaultOrder,
+    tui: {
+      limit: config2.cli.tui.limit,
+      debounce_ms: config2.cli.tui.debounceMs
+    },
+    edit: {
+      default_format: config2.cli.edit.defaultFormat
+    }
+  };
+  result.mcp = {
+    default_limit: config2.mcp.defaultLimit
+  };
+  return result;
+}
+function filterSection(config2, section) {
+  const sectionValue = config2[section];
+  if (sectionValue === void 0) {
+    return {};
+  }
+  return { [section]: sectionValue };
+}
+function serializeToTOML(config2, withSources) {
+  const lines = [];
+  if (withSources) {
+    lines.push("# Effective configuration");
+    lines.push("# Source priority: CLI > current dir > env > user > default");
+    lines.push("");
+  }
+  for (const [key, value] of Object.entries(config2)) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      lines.push(formatTOMLValue(key, value));
+    }
+  }
+  const hasTopLevel = Object.values(config2).some(
+    (v) => typeof v !== "object" || v === null || Array.isArray(v)
+  );
+  if (hasTopLevel) {
+    lines.push("");
+  }
+  for (const [key, value] of Object.entries(config2)) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      serializeSection(lines, key, value);
+    }
+  }
+  return lines.join("\n");
+}
+function serializeSection(lines, prefix, obj) {
+  const scalarEntries = [];
+  const objectEntries = [];
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      objectEntries.push([key, value]);
+    } else {
+      scalarEntries.push([key, value]);
+    }
+  }
+  if (scalarEntries.length > 0) {
+    lines.push(`[${prefix}]`);
+    for (const [key, value] of scalarEntries) {
+      lines.push(formatTOMLValue(key, value));
+    }
+    lines.push("");
+  }
+  for (const [key, value] of objectEntries) {
+    serializeSection(lines, `${prefix}.${key}`, value);
+  }
+}
+function formatTOMLValue(key, value) {
+  if (typeof value === "string") {
+    return `${key} = "${value}"`;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return `${key} = ${value}`;
+  }
+  if (Array.isArray(value)) {
+    const items2 = value.map((v) => typeof v === "string" ? `"${v}"` : String(v));
+    return `${key} = [ ${items2.join(", ")} ]`;
+  }
+  if (value === void 0 || value === null) {
+    return `# ${key} = (not set)`;
+  }
+  return `${key} = ${JSON.stringify(value)}`;
+}
+function showConfig(config2, options) {
+  let snakeCaseConfig = toSnakeCaseConfig(config2);
+  if (options.section) {
+    snakeCaseConfig = filterSection(snakeCaseConfig, options.section);
+  }
+  if (options.json) {
+    return JSON.stringify(snakeCaseConfig, null, 2);
+  }
+  return serializeToTOML(snakeCaseConfig, options.sources ?? false);
+}
+async function unsetConfigValue(configPath, key) {
+  if (!isValidConfigKey(key)) {
+    return { success: false, error: `Unknown configuration key: '${key}'` };
+  }
+  try {
+    await removeTOMLKey(configPath, key);
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to update config: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  return { success: true };
+}
+function resolveWriteTarget(options) {
+  const { local, user, cwd, userConfigPath } = options;
+  const localConfigPath = join(cwd, getDefaultCurrentDirConfigFilename());
+  if (local) {
+    return localConfigPath;
+  }
+  if (user) {
+    return userConfigPath;
+  }
+  if (existsSync(localConfigPath)) {
+    return localConfigPath;
+  }
+  return userConfigPath;
+}
+function createTempFile(content, format2) {
+  const timestamp2 = Date.now();
+  const extension = format2 === "yaml" ? ".yaml" : ".json";
+  const fileName = `ref-edit-${timestamp2}${extension}`;
+  const filePath = path.join(os.tmpdir(), fileName);
+  fs.writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+function openEditor(editor, filePath) {
+  const command = `${editor} "${filePath}"`;
+  const result = spawnSync(command, {
+    stdio: "inherit",
+    shell: true
+  });
+  return result.status ?? 1;
+}
+function readTempFile(filePath) {
+  return fs.readFileSync(filePath, "utf-8");
+}
+function deleteTempFile(filePath) {
+  try {
+    fs.unlinkSync(filePath);
+  } catch {
+  }
+}
+function resolveEditor(platform) {
+  const visual = process.env.VISUAL;
+  if (visual && visual.trim() !== "") {
+    return visual;
+  }
+  const editor = process.env.EDITOR;
+  if (editor && editor.trim() !== "") {
+    return editor;
+  }
+  const currentPlatform = process.platform;
+  return currentPlatform === "win32" ? "notepad" : "vi";
+}
+function registerConfigCommand(program) {
+  const configCmd = program.command("config").description("Manage configuration settings");
+  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.output === "json",
+        section: options.section,
+        sources: options.sources
+      });
+      process.stdout.write(`${output}
+`);
+      process.exit(0);
+    } catch (error) {
+      process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+      process.exit(1);
+    }
+  });
+  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) => {
+    try {
+      const config2 = loadConfig();
+      const envOverrideValue = options.configOnly ? null : getEnvOverrideInfo(key)?.value ?? null;
+      const getOptions = {
+        configOnly: options.configOnly
+      };
+      if (envOverrideValue !== null) {
+        getOptions.envOverride = envOverrideValue;
+      }
+      const result = getConfigValue(config2, key, getOptions);
+      if (result.found) {
+        const { formatValue: formatValue2 } = await Promise.resolve().then(() => get);
+        process.stdout.write(`${formatValue2(result.value)}
+`);
+        process.exit(0);
+      } else {
+        process.exit(1);
+      }
+    } catch (error) {
+      process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+      process.exit(1);
+    }
+  });
+  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) => {
+    try {
+      const configPath = resolveWriteTarget({
+        local: options.local,
+        user: options.user,
+        cwd: process.cwd(),
+        userConfigPath: getDefaultUserConfigPath()
+      });
+      const parsedValue = parseValueForKey(key, value);
+      const envOverrideInfo = getEnvOverrideInfo(key);
+      const setOptions = envOverrideInfo ? { envOverrideInfo } : {};
+      const result = await setConfigValue(configPath, key, parsedValue, setOptions);
+      if (!result.success) {
+        process.stderr.write(`Error: ${result.error}
+`);
+        process.exit(1);
+      }
+      if (result.warning) {
+        process.stderr.write(`${result.warning}
+`);
+      }
+      process.exit(0);
+    } catch (error) {
+      process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+      process.exit(1);
+    }
+  });
+  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) => {
+    try {
+      const configPath = resolveWriteTarget({
+        local: options.local,
+        user: options.user,
+        cwd: process.cwd(),
+        userConfigPath: getDefaultUserConfigPath()
+      });
+      const result = await unsetConfigValue(configPath, key);
+      if (!result.success) {
+        process.stderr.write(`Error: ${result.error}
+`);
+        process.exit(1);
+      }
+      process.exit(0);
+    } catch (error) {
+      process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+      process.exit(1);
+    }
+  });
+  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);
+    } catch (error) {
+      process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+      process.exit(1);
     }
-    const output = formatCiteOutput(result);
-    if (output) {
+  });
+  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) => {
+    try {
+      const output = showConfigPaths({ user: options.user, local: options.local });
       process.stdout.write(`${output}
 `);
-    }
-    const errors2 = formatCiteErrors(result);
-    if (errors2) {
-      process.stderr.write(`${errors2}
+      process.exit(0);
+    } catch (error) {
+      process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
+      process.exit(1);
     }
-    process.exit(getCiteExitCode(result));
-  } catch (error) {
-    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(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);
+      }
+      const target = getConfigEditTarget({ local: options.local });
+      if (!target.exists) {
+        const template = createConfigTemplate();
+        mkdirSync(dirname(target.path), { recursive: true });
+        writeFileSync(target.path, template, "utf-8");
+      }
+      const editor = resolveEditor();
+      const exitCode = openEditor(editor, target.path);
+      process.exit(exitCode);
+    } catch (error) {
+      process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(4);
-  }
-}
-function createTempFile(content, format2) {
-  const timestamp2 = Date.now();
-  const extension = format2 === "yaml" ? ".yaml" : ".json";
-  const fileName = `ref-edit-${timestamp2}${extension}`;
-  const filePath = path.join(os.tmpdir(), fileName);
-  fs.writeFileSync(filePath, content, "utf-8");
-  return filePath;
-}
-function openEditor(editor, filePath) {
-  const command = `${editor} "${filePath}"`;
-  const result = spawnSync(command, {
-    stdio: "inherit",
-    shell: true
+      process.exit(1);
+    }
   });
-  return result.status ?? 1;
-}
-function readTempFile(filePath) {
-  return fs.readFileSync(filePath, "utf-8");
-}
-function deleteTempFile(filePath) {
-  try {
-    fs.unlinkSync(filePath);
-  } catch {
-  }
 }
 function datePartsToIso(dateParts) {
   if (!dateParts || dateParts.length === 0 || !dateParts[0]) {
@@ -3576,18 +5565,6 @@ ${yamlContent}`);
   }
   return sections.join("\n---\n\n");
 }
-function resolveEditor(platform) {
-  const visual = process.env.VISUAL;
-  if (visual && visual.trim() !== "") {
-    return visual;
-  }
-  const editor = process.env.EDITOR;
-  if (editor && editor.trim() !== "") {
-    return editor;
-  }
-  const currentPlatform = process.platform;
-  return currentPlatform === "win32" ? "notepad" : "vi";
-}
 function serialize(items2, format2) {
   return format2 === "yaml" ? serializeToYaml(items2) : serializeToJson(items2);
 }
@@ -3741,12 +5718,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(
@@ -6977,7 +8954,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") {
@@ -6994,183 +8971,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";
@@ -7195,8 +8995,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) {
@@ -7211,13 +9011,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);
@@ -7227,12 +9020,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 {
@@ -7245,71 +9052,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 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 getFilePaths(manager, item, types2, identifier) {
+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) {
@@ -7323,92 +9137,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}'` };
   }
-  const attachedTypes = type2 ? [type2] : manager.getAttachedTypes(item);
-  if (attachedTypes.length === 0) {
+  if (type2) {
+    return getSingleTypePath(attachments, type2, identifier, fulltextDirectory);
+  }
+  if (!attachments) {
     return { success: false, error: `No fulltext attached to '${identifier}'` };
   }
-  return getFilePaths(manager, item, attachedTypes, identifier);
+  return getAllFulltextPaths(attachments, fulltextFiles, fulltextDirectory, identifier);
+}
+function getFilesToDetach(attachments, type2) {
+  if (type2) {
+    const file = findFulltextFile(attachments, type2);
+    return file ? [file] : [];
+  }
+  return findFulltextFiles(attachments);
 }
-async function performDetachOperations(manager, item, typesToDetach, deleteFile) {
+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;
+function buildResult(detached, deleted, identifier) {
+  if (detached.length === 0) {
+    return { success: false, error: `Failed to detach fulltext from '${identifier}'` };
   }
-  if (currentFulltext.markdown && !detached.includes("markdown")) {
-    newFulltext.markdown = currentFulltext.markdown;
+  const result = { success: true, detached };
+  if (deleted.length > 0) {
+    result.deleted = deleted;
   }
-  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 };
-  }
-  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) {
@@ -7417,14 +9237,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,
@@ -7472,7 +9294,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
   };
@@ -7543,12 +9365,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];
 }
@@ -7587,7 +9409,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 },
@@ -7641,7 +9463,7 @@ async function handleFulltextGetAction(identifierArg, options, globalOpts) {
     }
     const getOptions = {
       identifier,
-      fulltextDirectory: config2.fulltext.directory,
+      fulltextDirectory: config2.attachments.directory,
       ...options.pdf && { type: "pdf" },
       ...options.markdown && { type: "markdown" },
       ...options.stdout && { stdout: options.stdout },
@@ -7677,10 +9499,10 @@ async function handleFulltextDetachAction(identifierArg, options, globalOpts) {
     }
     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" }
     };
@@ -7716,7 +9538,7 @@ async function handleFulltextOpenAction(identifierArg, options, globalOpts) {
     }
     const openOptions = {
       identifier,
-      fulltextDirectory: config2.fulltext.directory,
+      fulltextDirectory: config2.attachments.directory,
       ...options.pdf && { type: "pdf" },
       ...options.markdown && { type: "markdown" },
       ...options.uuid && { idType: "uuid" }
@@ -7823,21 +9645,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)) {
@@ -28249,7 +30078,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 {
@@ -28282,7 +30111,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 {
@@ -28296,7 +30125,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({
@@ -28335,7 +30164,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 {
@@ -28541,7 +30370,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-4KSTJ3rp.js").then((n) => n.r);
+    const { removeReference } = await import("./index-DHgeuWGP.js").then((n) => n.r);
     return removeReference(context.library, {
       identifier,
       idType,
@@ -28595,12 +30424,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 };
@@ -28682,7 +30511,7 @@ async function handleRemoveAction(identifierArg, options, globalOpts) {
     const removeOptions = {
       identifier,
       idType: useUuid ? "uuid" : "id",
-      fulltextDirectory: config2.fulltext.directory,
+      fulltextDirectory: config2.attachments.directory,
       deleteFulltext: force && hasFulltext
     };
     const result = await executeRemove(removeOptions, context);
@@ -28705,21 +30534,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)) {
@@ -28775,35 +30611,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-DNlpGiwS.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-DvwR6nMj.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 || ""
   );
@@ -29096,12 +30936,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];
 }
@@ -29206,18 +31046,61 @@ 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",
+  "cli",
+  "fulltext",
+  "mcp",
+  "pubmed",
+  "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
+  "--log-level": LOG_LEVELS,
+  "--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 }));
 }
@@ -29251,6 +31134,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+/);
@@ -29262,7 +31152,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);
     }
@@ -29302,11 +31193,43 @@ 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 };
   }
   return { needs: false };
 }
+const CONFIG_KEY_SUBCOMMANDS = /* @__PURE__ */ new Set(["get", "set", "unset"]);
+function needsConfigKeyCompletion(env) {
+  const { line, prev } = env;
+  const words = line.trim().split(/\s+/);
+  const args = words.slice(1);
+  if (args.length < 2) {
+    return false;
+  }
+  const command = args[0] ?? "";
+  const subcommand = args[1] ?? "";
+  if (prev?.startsWith("-")) {
+    return false;
+  }
+  if (command === "config" && CONFIG_KEY_SUBCOMMANDS.has(subcommand)) {
+    if (subcommand === "set" && args.length > 3) {
+      return false;
+    }
+    return true;
+  }
+  return false;
+}
+function getConfigKeyCompletions(prefix) {
+  const keys = getAllConfigKeys();
+  return keys.filter((key) => key.toLowerCase().startsWith(prefix.toLowerCase())).map((key) => ({ name: key }));
+}
 const MAX_ID_COMPLETIONS = 100;
 async function getLibraryForCompletion() {
   try {
@@ -29372,6 +31295,11 @@ async function handleCompletion(program) {
     tabtab.log(completions2);
     return;
   }
+  if (needsConfigKeyCompletion(env)) {
+    const keyCompletions = getConfigKeyCompletions(env.last);
+    tabtab.log(keyCompletions);
+    return;
+  }
   const idContext = needsIdCompletion(env);
   if (idContext.needs) {
     const library = await getLibraryForCompletion();
@@ -29411,7 +31339,9 @@ function createProgram() {
   registerCiteCommand(program);
   registerServerCommand(program);
   registerFulltextCommand(program);
+  registerAttachCommand(program);
   registerMcpCommand(program);
+  registerConfigCommand(program);
   registerCompletionCommand(program);
   return program;
 }
@@ -29434,7 +31364,7 @@ async function handleListAction(options, program) {
   }
 }
 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);
   });
 }
@@ -29463,7 +31393,7 @@ async function handleExportAction(ids, options, program) {
   }
 }
 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);
   });
 }
@@ -29472,7 +31402,7 @@ 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}
@@ -29494,9 +31424,9 @@ async function handleSearchAction(query, options, program) {
   }
 }
 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");
+  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");
       process.exit(1);
     }
     await handleSearchAction(query ?? "", options, program);
@@ -29507,8 +31437,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;
@@ -29576,11 +31506,7 @@ async function handleAddAction(inputs, options, program) {
   }
 }
 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);
   });
 }
@@ -29598,7 +31524,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());
   });
 }
@@ -29606,7 +31532,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());
   });
 }
@@ -29711,6 +31637,30 @@ function registerMcpCommand(program) {
     }
   });
 }
+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) => {
@@ -29719,7 +31669,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) => {
@@ -29741,8 +31691,14 @@ async function main(argv) {
   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-UpzsmbyY.js.map
+//# sourceMappingURL=index-Bv5IgsL-.js.map